fix(skill): read bounded frontmatter independently of document size

[abruption]

Summary

Fixes #318. Related #302 / #303. Patch candidate for v1.2.1; no runtime version bump or publication.

The previous metadata reader rejected a whole skill document above 16,384 bytes. Both released Python skill snapshots exceed this limit (v0.3.2: 16,459 bytes; v0.3.3: 18,824 bytes), causing unknown installed version/minimum metadata despite valid small frontmatter.

• Read a bounded binary prefix (at most 16,384 + 1 bytes), locate a complete leading frontmatter section, and decode only that section as strict UTF-8. The 16 KiB header budget includes opening/closing delimiters and line endings; the extra byte is lookahead, not extra accepted header space.
• Retain existing published-field matching, semantic-version bounds, per-field unknown results, and manager-owned symlink support. The constrained existing regular-expression extraction is not a general YAML validator and this patch does not claim to reject every malformed YAML form. Do not parse or execute YAML/instructions or read an unbounded body.
• Use a regular-file descriptor with nonblocking POSIX open to avoid FIFO reads, always close it, and return unknown for unreadable/nonregular/over-budget/incomplete metadata.
• A malformed excessively long numeric component becomes unknown only for that field; the shared version parser and independently valid metadata field remain unchanged.
• Regenerate standalone source. No canonical skill, manager installation, metadata schema, global configuration or runtime behavior outside this reader is changed.

Verification

Exact pre-PR source: 3b90b7fcff5d1168a180b43394b0cc4e25e38e61, based on published v1.2.0/main 4fc526f36afc65bb6ec460439eb0986c09ecc8ee.

• Python 3.13.7 relevant tests 91 OK, 1 skipped; Python 3.9.6 39 OK.
• Documentation 62 OK; distribution checks against final built wheel/sdist 41 OK, 3 PowerShell skips; standalone generator and diff checks pass.
• Fourteen new tests cover released byte-identical frontmatter at observed full-document sizes, invalid/split UTF-8 body, UTF-8 header byte budgets, LF/CRLF/CR/EOF framing and lookahead, malformed/truncated/oversized header, field compatibility and large integers, finite/short reads, manager symlinks, permissions, directories/FIFO, descriptor cleanup and failure paths.
• Regression was observed before the fix; real released v0.3.2 and v0.3.3 files were directly recognized by the final helper as versions 0.3.2/0.3.3 and minimum 0.9.1. The canonical instructions were not edited or executed.
• Initial build --no-isolation failed because the private build tool environment lacked the pinned hatchling 1.32.4 backend. The failure log was preserved; standard isolated builds supplied that backend without changing the shared environment and final wheel/sdist checks passed.
• No full-project rerun or live agent/native message experiment is claimed for this bounded reader fix. Related suites emitted no observed unraisable/ResourceWarning diagnostics. This does not resolve test(relay): investigate intermittent native CI crash and shutdown diagnostics #316.

Independent pre-PR review

The requested independent-cli-review used the same frozen sanitized packet in separate parallel non-interactive processes before PR creation, with reviewer tools/tests/network/writes disabled and before/after input hashes checked:

• Claude Code 2.1.303, requested and metadata-confirmed claude-opus-5-5; Codex CLI 0.163.0, isolated default (actual model name not exposed).
• Source 3b90b7fcff5d1168a180b43394b0cc4e25e38e61, immutable packet 29,997 bytes, SHA-256 1b40533296524c90d51556b01a5960a6c24501ee74c4df8a7d6057a7e0a352ff. Both exit 0 with valid completed responses; input/source unchanged.
• Neither established a mandatory source correction. Root checked two conditional evidence questions against the actual generator/package layout (common.py supplies stat; fragments are not independently imported runtime modules) and cache-validation code (fresh cache requires a valid stable version). Those questions do not establish defects.
• Additional CRLF/short-read boundary and byte-accounting test coverage was recommended, not presented as a confirmed runtime failure. Legacy regex limitations and native/platform acceptance limits remain explicit. No reviewer test result was treated as an executed experiment.

Boundaries

No merge, tag, release, package publication, global installation, skill-source rewrite or operations change. Existing metadata interpretation is not a grant to execute a skill. The configured automatic Codex review is left to run without a mention.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-19T04:34:48.183437Z	3b90b7f	PR opened
🔒 Security Review	✅ Completed 2026-10-19T04:35:44.165412Z	3b90b7f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.