Add the harness guides, widen ACP capabilities, refuse stray top-level keys

[VeryComplexAndLongName]

Three changes implemented into one working tree, plus two proposals that came out of doing the human-only checks.

agentic-harness-documentation

HARNESS.md and LIMITS.md exist, and README.md contains the word "harness" for the first time.

The agent reference table is read out of HARNESS_AGENT_CAPABILITIES rather than recalled. LIMITS.md separates the chain-wide budget evaluated between stages from the per-stage cap passed to one invocation, and says outright:

There is no wall-clock or duration limit on a harness run, and no per-stage timeout.

The question that prompted this document assumed one existed, which is exactly why it has to be stated.

Standalone screenshots are now produced by a Playwright spec, so the settings image can no longer show a screen that stopped existing three commits ago — which is what the committed one did.

acp-agent-capabilities

copilot-cli-acp and claude-cli-acp get the capabilities their plain counterparts have, because they run the same binaries with the same flags. codex-cli-acp and gemini-cli-acp get explicit empty entries, so an omission stops being spelled the same way as a decision.

harness-config-top-level-keys

A top-level key the schema does not define is refused — what would have caught the harness.json that sat in this repository doing nothing.

---

Two human-only tasks done, not deferred

harness-config-top-level-keys 3.6. The deleted file written back byte-for-byte and read through the real loader:

Invalid harness config: unrecognized top-level key "apply" (accepted keys: stepAgents, autonomyLevel, reviewGate, checkpoints, budget, gitStageAllowlist). Did you mean "stepAgents.apply"?

It used to return silently.

acp-agent-capabilities 3.7 — verified along the whole path, not at its ends, which is what harness-step-models needed three rounds to learn:

link	result
real agent-harness.json → resolveHarnessConfig	loads (was refused)
→ buildInvocation	copilot --acp --effort high --max-ai-credits 30
→ checkAllowlist	{"allowed": true}
→ real binary via cross-spawn	accepts the flags, waits on stdin for ACP

An unknown flag exits immediately and non-zero — which is how gh pr create --json was caught.

agentic-harness-documentation 6.7, standalone half. Checked against the generated images: every control the document places is where it says, effort and budget appear only where the agent accepts them, no model control, archive shows "runs mechanically — no agent", and the checkpoint offers Continue and Cancel and nothing else. The VS Code half cannot be done here and stays open, with 3.4.

Two proposals from doing that check

harness-git-stage-no-agent

The settings screenshot shows an agent picker on the git stage. Nothing reads stepAgents.git — CHAIN_STAGE_COMMAND covers only propose/review/apply/verify, and runStage routes git straight to runGitStage.

HARNESS.md already documents this honestly as a known defect. But a defect described in prose with no tracked change is how it becomes permanent. It is the same defect harness-mechanical-checks removed for archive, missed because git was not yet in CHAIN_STAGES when that change narrowed the type — both landed in #179.

core-test-worker-contention

git.push.test.ts takes 2.6 s alone and hangs past 20 s beside one other worker; both pass in 7.7 s under a single fork. The cause is contention over real git subprocesses and temp directories, not duration.

Raising the ceiling to 20000 ms was tried and produced a 20 s failure instead of a 5 s one — the clearest possible evidence that duration is not the problem. Two task notes had recorded this as "timeout flakiness", and one had worked around it with --pool=forks --poolOptions.forks.singleFork=true without recognising the flag as the diagnosis.

git.push.test.ts also moves afterEach → afterAll for its cleanup, which is what ends its EBUSY ... rmdir failures — the fix git-fixture-test-cost already applied to the other two git-fixture files.

Test plan

• npm run typecheck — clean
• npm run lint — clean
• packages/core — 512/512 under a single fork (the contention above is why the flag is needed; it is the subject of the new proposal, not a claim that the suite is fine)
• openspec change validate --strict — all five changes valid
• npm run lint:english — passed
• CI green

🤖 Generated with Claude Code