Harden headless boundaries and model-facing prompt metadata

[kky42]

Summary

This review PR applies the low-risk fixes found while auditing v3.1.1 (78c71d35) and keeps larger behavior changes as explicit follow-ups.

1. Design / bug fixes

• Validate maxConcurrentSubagents as a positive integer before headless execution.
• Validate subagentTimeoutMs and workflowTimeoutMs as non-negative integers, so negative/ fractional values cannot silently disable a subagent timeout or become an accidental immediate workflow timeout.
• Return immutable HeadlessUsage snapshots by cloning the nested cost object on callbacks/results/errors. Previously the initial onSubagentStart snapshot shared usage.cost with the live accumulator and could change after the callback returned.

2. Prompt hardening

• Normalize registered subagent/workflow descriptions to one model-facing line before inserting them into the system prompt. This preserves the complete description while preventing embedded newlines from escaping the roster item and creating prompt headings/list entries.

3. Documentation / tests

• Add regression coverage for invalid headless bounds, immutable usage snapshots, and multiline roster descriptions.
• Simplify test/readme.test.ts: keep package/link validity and verify that documented profile examples are parseable, but stop pinning the README to exactly two natural-language examples, exactly three profile examples, and specific example model IDs/text.

4. Maintainability

• Centralize headless numeric boundary validation and usage snapshotting in small helpers instead of relying on downstream setTimeout / timeout-helper behavior.

Review findings intentionally not changed here

These are higher-impact contract/security changes and should be handled separately:

1. External CLI trust is advisory, not enforced. The prompt says Codex/Claude profiles are for trusted repositories, but the interactive execution path does not gate them on ctx.isProjectTrusted(), while Codex uses --dangerously-bypass-approvals-and-sandbox and Claude uses --dangerously-skip-permissions.
2. workflow: false leaves workflow instructions in the system prompt. run_workflow is not registered, but before_agent_start still injects the workflow authoring guide and saved-workflow roster.
3. Direct run_agent.prompt accepts empty/whitespace-only strings. label has a non-whitespace schema constraint; prompt does not.
4. AGENTS.md and CLAUDE.md duplicate a large evolving contract/history surface. Consolidating them needs an explicit decision about which file is canonical for each agent harness.

Validation

• Added/updated Vitest regression coverage in test/headless.test.ts, test/subagent-contract.test.ts, and test/readme.test.ts.
• Branch is based directly on v3.1.1 main and contains only the five reviewed files.