Size the plan import request limit from the parser bound (#146)

[mchwang]

Closes #146.

What changed

POST /api/plan/import refused every body over 16 KiB before parsing, though the parser accepts a 1 MiB source and the v1 schema permits plans far larger than 16 KiB.

• web/server.ts: the import body limit is now MAX_IMPORT_REQUEST_BYTES = 6 * MAX_SOURCE_BYTES + MAX_REQUEST_BYTES (6 MiB + 16 KiB = 6,307,840 bytes). Every other POST keeps MAX_REQUEST_BYTES (16 KiB).
• core/parse-v1.ts: exports the parser's 1 MiB bound as MAX_SOURCE_BYTES.
• Why 6×: any JSON encoding writes each UTF-8 byte of the source as at most 6 bytes. The yaml parser accepts a raw control character in a quoted scalar, and JSON writes it as \^A. So every source within the parser limit fits, inside any envelope that fits 16 KiB with an empty source. A body within the limit whose source is above 1 MiB gets the parser's refusal (409, recorded and replayed), not a transport one.
• Docs: docs/plan-format.md (the documented maximum) and the endpoint table in docs/implementation/runner-lifecycle.md.

The schema was not tightened: the parser's 1 MiB bound already binds before the schema's larger theoretical maximum, so the contracts agree once transport admits every parser-valid source.

Tests

New import request size (#146) block in test/runner-planning-feedback.test.ts, against the real server and Store:

1. A schema-valid import whose request is over 16 KiB → 200, new revision.
2. A 1 MiB YAML source of raw control characters, whose request is over 5.5 MiB → 200. Fails if the factor were 5×.
3. A request exactly at the limit → 409 with the parser's "exceeds 1 MiB" refusal, replayed under the same action ID; revision unchanged.
4. A request one byte over the limit → 413; revision unchanged.
5. Eight other POST routes, including the other planning routes, → 413 at 16 KiB + 1 byte.

With the limit set back to 16 KiB, tests 1–3 fail with 413. With the import limit applied to every planning path, test 5 fails.

Validation

Gate	Result
Focused (-t 146)	5/5 pass
Affected suites (runner-planning-feedback, runner-shutdown)	33/33 pass at f7d47e8
Type check (tsc --noEmit)	clean at f7d47e8
Full suite, parallel project	Validated head f7d47e8: 74 files, 1990/1990 pass (load average ~84). Earlier runs at intermediate checkpoint 3cb9673 (load 150–200) had different pre-merge.test.ts timing failures each time; that file passed 40/40 alone. Recorded as infrastructure, not product.
CI (test)	pass on validated head f7d47e8
Real Docker	not triggered: agent-isolation.yml path filters do not match this diff

Review record

Round	Type / reviewer	Base / head	Findings	What changed
1	Self-review	ae9fc3d / 3cb9673	None outstanding	—
2	Independent agent (fresh context)	ae9fc3d / 3cb9673	(a) Low: other-POST test only covered /api/action, so the import limit leaking to every planning path would pass. (b) Low: at-limit test asserted only not 413. (c) Nit: code comment implied the parser refusal was unconditional.	(a) Test now covers 8 routes. (b) Asserts 409 and replay. (c) Comment reworded. All in f7d47e8.
3	Independent agent (fresh context)	ae9fc3d / f7d47e8	Clean for this diff. Pre-existing on main: a 413 with a large unread body stops server.close() from settling, and can reset the client. Info: the 6× worst case relies on the yaml library's leniency for C0 controls.	Pre-existing bug filed as #157 (out of scope). Info noted; if the parser is made strict, test 2 fails, which is the intended signal.
4	Copilot (ran automatically, before the full-suite gate)	ae9fc3d / f7d47e8	0 findings. Summary concern: exact-head full-suite and CI validation incomplete.	No code change. Resolved by the exact-head CI and full-suite results above.

Review-lesson audit

• Round 2 (a), (b): covered by existing rules — CLAUDE.md "Review readiness": every behavioural claim gets a test that fails if the claim is false.
• Round 2 (c): one-off wording fix.
• Round 3 shutdown hang: pre-existing defect, follow-up Shut down cleanly after refusing an oversized request body #157; not a review-process lesson.
• Overall change: covered by AGENTS.md:101 (align transport limits with every payload the schema accepts).
• No AGENTS.md/CLAUDE.md update needed.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Exact-head full-suite and CI validation remain incomplete.

0 open findings

What changed in this PR

Aligns plan-import transport limits with the parser’s 1 MiB source bound.

Changes:

• Derives a 6 MiB + 16 KiB import limit from parser constraints.
• Adds boundary and route-isolation tests.
• Documents the endpoint limit.

File	Description
web/​server.ts	Applies the expanded limit only to plan imports.
core/​parse-v1.ts	Exports the parser source-size bound.
test/​runner-planning-feedback.test.ts	Tests valid, boundary, oversized, and unaffected routes.
docs/​plan-format.md	Documents sizing and refusal behavior.
docs/​implementation/​runner-lifecycle.md	Updates the endpoint contract.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.