MCP `restore_drill`: restore the newest snapshot as a drill and say its verdict, as the Backups page's button does, for a forge admin #5433

This adds an MCP tool restore_drill, so "is my backup restorable?" is one call from any harness. It takes no arguments and runs the same drill as the Backups page's button, through snapshotsOf(ctx.app).drill(). It answers { verdict, failedStep?, says }.

The new test, test/mcp.test.ts, test/mcp-docs.test.ts and test/mcp-size.test.ts pass, and so do the other 36 files matching test/mcp. I did not run the whole suite. bun x tsc --noEmit could not run here: it couldn't find the bun type definitions.

• Wording: says uses the page's flashes: "The drill restored green.", "The drill failed at <step>.", "This forge has no snapshots to drill." and "The drill could not run: …". A failure or a missing store is an answer, never a throw.
• Verdicts: verdict is green or red. The page has no value for "no store" or "could not run", so I used none for those two cases.
• Access: admin only, and it needs an admin-scope token. Other users don't see the tool in tools/list, and calling it returns an error. It is marked as a write, like the other writes.
• Placement: it sits after account_suspend. #5415, #5422 and #5423 hadn't landed, so there was no backup tool to follow.
• Docs: there is one new row in docs/MCP.md.
• Test: test/mcp-restore-drill.test.ts covers the three cases. The store case uses the drill test seam with a stub, as the page's own test does, so no real restore runs. It checks the kept drill is what the page reads.

Size ceiling: tools/list was 3 bytes under its 37,000-byte headroom on main, and this tool pushed it over. I did not raise the ceiling. I trimmed about 150 bytes from the descriptions of flow, asks_act, access, prompts, quotas and bottleneck, plus the "offer to parent" description, without removing any tool or argument. The edits are in src/http/mcp.ts; the descriptions that changed are:

• the pipeline: dropped "by reviewer" and reviewing/queue
• access: dropped "to public paths, newest first, max 500"
• asks_act: dropped "(never undone)"
• prompts: "Repository admin token" is now "Admin token"
• quotas: dropped "yet" and "plans"
• the parent offer: dropped "the same tip answers that pull"

I also added restore_drill to the expected tool list in test/mcp.test.ts.

Closes #5427

This adds an MCP tool restore_drill, so "is my backup restorable?" is one call from any harness. It takes no arguments and runs the same drill as the Backups page's button, through snapshotsOf(ctx.app).drill(). It answers { verdict, failedStep?, says }.

The new test, test/mcp.test.ts, test/mcp-docs.test.ts and test/mcp-size.test.ts pass, and so do the other 36 files matching test/mcp. I did not run the whole suite. bun x tsc --noEmit could not run here: it couldn't find the bun type definitions.

• Wording: says uses the page's flashes: "The drill restored green.", "The drill failed at <step>.", "This forge has no snapshots to drill." and "The drill could not run: …". A failure or a missing store is an answer, never a throw.
• Verdicts: verdict is green or red. The page has no value for "no store" or "could not run", so I used none for those two cases.
• Access: admin only, and it needs an admin-scope token. Other users don't see the tool in tools/list, and calling it returns an error. It is marked as a write, like the other writes.
• Placement: it sits after account_suspend. #5415, #5422 and #5423 hadn't landed, so there was no backup tool to follow.
• Docs: there is one new row in docs/MCP.md.
• Test: test/mcp-restore-drill.test.ts covers the three cases. The store case uses the drill test seam with a stub, as the page's own test does, so no real restore runs. It checks the kept drill is what the page reads.

Size ceiling: tools/list was 3 bytes under its 37,000-byte headroom on main, and this tool pushed it over. I did not raise the ceiling. I trimmed about 150 bytes from the descriptions of flow, asks_act, access, prompts, quotas and bottleneck, plus the "offer to parent" description, without removing any tool or argument. The edits are in src/http/mcp.ts; the descriptions that changed are:

• the pipeline: dropped "by reviewer" and reviewing/queue
• access: dropped "to public paths, newest first, max 500"
• asks_act: dropped "(never undone)"
• prompts: "Repository admin token" is now "Admin token"
• quotas: dropped "yet" and "plans"
• the parent offer: dropped "the same tip answers that pull"

I also added restore_drill to the expected tool list in test/mcp.test.ts.

This pull adds the MCP tool restore_drill. It restores the newest snapshot as a drill, the same drill as the Backups page's button, and answers { verdict, failedStep?, says }.

All 175 tests under test/mcp pass, including the size, docs and tools/list tests. I didn't run bun x tsc --noEmit this round; last round it couldn't find the bun type definitions.

What changed after review

• Descriptions restored. I put every other tool's description back exactly as on main. That brings back "ship (never undone)" on asks_act and "Repository admin token" on prompts, and undoes the trims to flow, access and quotas and the parent offer. The pull now touches no description but its own.
• Headroom raised, with the reason. HEADROOM_CEILING in test/mcp-size.test.ts goes from 37,000 to 37,150. Main had 3 bytes spare, and the tool costs 124 bytes even with a one-sentence description and a minimal schema, so it can't fit by shrinking itself. The 40,000 ceiling is untouched, and the comment in the test names this pull.
• Tests added in test/mcp-restore-drill.test.ts:

- A red drill returns failedStep: "unseal" and "The drill failed at unseal." - A drill that throws returns verdict: "none" and "The drill could not run: Error: store went away", as an answer rather than an error. - An admin holding a read-only token is refused ("this token may read, not act"), and no drill is kept. - A non-admin now gets the exact "no tool named restore_drill" error and an empty result, instead of the check that passed on any failure.

• Nit: the "restore_drill" line in test/mcp.test.ts is now indented like its neighbours.

The full gate on land was red; the pull is open again. Red tests:

• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited
• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited [112.73ms] [shard 103]

Red on top of #5347, #5345, which landed first from the same merge-queue candidate: red on its own on that base, or only together with them. Bring this pull up to date with the base and push.

The full gate on land was red and named no test; the pull is open again.

The full gate on land was red and named no test; the pull is open again.

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

MCP restore_drill is now brought up to date with main and re-pushed. I ran the MCP tests (359 pass) and the gate tests (11 pass). I did not run the type check, because tsc here has no Bun types. The forge's own check will run on this push.

• What it does: a forge admin with an admin-scope token calls restore_drill with no input. It restores the newest snapshot as a drill and answers { verdict, failedStep?, says }. The wording matches the Backups page's button. A missing store, a thrown error or a red drill comes back as an answer, not an error. A read-only token or an agent admin is refused.
• Merge with main: after #5932 split src/http/mcp.ts, I took main's version of that file and moved the tool into src/http/mcp/tools/restore_drill.ts. I regenerated tools/index.ts and docs/MCP.md with bun scripts/mcp-tools.ts. The earlier test files came through the merge unchanged.
• Size test: the tool adds 124 bytes to tools/list, so I raised the headroom ceiling to 37,150 and the hard cap to 37,100 in test/mcp-size.test.ts. The 40,000 ceiling is untouched. The comment now cites #5433, which fixes Sentinel's nit.
• Gate failure: the earlier failure was the gate audit's "new file with no list naming it". That should be covered now, since tools/index.ts and docs/MCP.md list the new file, and the gate tests pass here. If it comes back red, the forge's full check will say so.
• Not done: the terminal has no drill, as before, because the Backups page's drill was never there either.