MCP `releases`: the forge's kept releases, which one is live and since when, for whoever may read /releases #5388

I added a read-only MCP tool, releases, that takes no arguments and answers the kept releases newest first. test/mcp-releases.test.ts, test/mcp-size.test.ts and test/mcp.test.ts pass. I did not run the type check: bun x tsc --noEmit couldn't find the bun types here.

• What it returns: each release has its short sha, the pull that landed it (repo and number) and when it landed. It also says whether the preflight passed (ok). The live release adds live: true, its version and since. It reads through listReleases and running(), as releasesPage does.
• Who can call it: it sits behind mayRead. Someone the page refuses gets the refusal in words (forbidden, "the release history is for the forge's administrators and its repository's readers"). There is no rollback; a person does that on the page.
• Version: releases don't store a version, so only the live one carries it; the others show null.
• Tests and docs: test/mcp-releases.test.ts covers an empty forge, an allowed reader seeing the list with the live release marked, and a refused reader. I also added releases to the tool-name list in test/mcp.test.ts and one row to docs/MCP.md.
• Size trimmed: the new tool pushed tools/list over the 37,000-byte headroom in test/mcp-size.test.ts. I did not raise that limit; the test says it is the owner's. Instead I shortened nine existing tool descriptions in src/http/mcp.ts: asks_act, access, flow, quotas, issue, limb, pull, cloud_account and asks. tell and propose_to_parent_forge also lost a few words.

The cuts drop detail: asks_act no longer says "(never undone)", quotas no longer says "" clears, pull no longer lists checkStale and cloud_account no longer lists the audit verb. If you want any back, it needs more headroom or other cuts.

Closes #5365

I added a read-only MCP tool, releases, that takes no arguments and answers the kept releases newest first. test/mcp-releases.test.ts, test/mcp-size.test.ts and test/mcp.test.ts pass. I did not run the type check: bun x tsc --noEmit couldn't find the bun types here.

• What it returns: each release has its short sha, the pull that landed it (repo and number) and when it landed. It also says whether the preflight passed (ok). The live release adds live: true, its version and since. It reads through listReleases and running(), as releasesPage does.
• Who can call it: it sits behind mayRead. Someone the page refuses gets the refusal in words (forbidden, "the release history is for the forge's administrators and its repository's readers"). There is no rollback; a person does that on the page.
• Version: releases don't store a version, so only the live one carries it; the others show null.
• Tests and docs: test/mcp-releases.test.ts covers an empty forge, an allowed reader seeing the list with the live release marked, and a refused reader. I also added releases to the tool-name list in test/mcp.test.ts and one row to docs/MCP.md.
• Size trimmed: the new tool pushed tools/list over the 37,000-byte headroom in test/mcp-size.test.ts. I did not raise that limit; the test says it is the owner's. Instead I shortened nine existing tool descriptions in src/http/mcp.ts: asks_act, access, flow, quotas, issue, limb, pull, cloud_account and asks. tell and propose_to_parent_forge also lost a few words.

The cuts drop detail: asks_act no longer says "(never undone)", quotas no longer says "" clears, pull no longer lists checkStale and cloud_account no longer lists the audit verb. If you want any back, it needs more headroom or other cuts.

This adds a read-only MCP tool, releases, that answers the forge's kept releases newest first with the live one marked. It takes no arguments.

The failed check came from a duplicate import { running } in src/http/mcp.ts. I added a second import when running was already imported at the top of the file, and I've removed mine. The type check passes now. test/mcp-releases.test.ts, test/mcp-size.test.ts and test/mcp.test.ts pass too. I pushed the fix and haven't seen the forge's check re-run on it.

• What each release shows: its short sha, the pull that landed it (repo and number), when it landed, and whether its preflight passed (ok). The live release also carries live: true, its version and since. Releases don't store a version, so the others show version: null.
• Who can call it: the tool uses the same mayRead gate as the /releases page. Someone the page refuses gets a forbidden error saying the release history is for the forge's administrators and its repository's readers.
• Rollback: there is none in this tool. A person rolls back on the page.
• Tests and docs: test/mcp-releases.test.ts covers a forge with no kept releases, an allowed reader seeing the live one marked, and a refused reader. I added releases to the tool list in test/mcp.test.ts and one row to docs/MCP.md.
• Descriptions I shortened: the new tool pushed the tools/list answer over the 37,000-byte limit in test/mcp-size.test.ts. I left that limit alone, since the test says it is the owner's, and cut words from ten existing tool descriptions instead. asks_act no longer says "(never undone)", quotas no longer says "" clears, pull drops checkStale, and cloud_account drops the audit verb. issue and asks are shorter, and flow, access, limb and propose_to_parent_forge lost a few words; tell now says its note is kept "as a thought" rather than "answers a thought id". If any of that detail should come back, it needs more headroom or other cuts.

This pull adds a read-only MCP tool, releases, that answers the kept releases newest first. It takes no arguments. I haven't seen the forge's check re-run on the fix I just pushed. The type check is clean. test/asks-mute.test.ts, the new test/mcp-releases.test.ts, test/mcp-size.test.ts, test/mcp.test.ts and every other test that reads a tool description pass locally: 188 in the last run.

The failing check came from me. To make room for the new tool under the 37,000-byte limit on tools/list, I had shortened the asks description and dropped "your saved filter applies". test/asks-mute.test.ts requires the words "saved filter" in the asks and feed descriptions. I put the wording back and made up the bytes by cutting "max 500" from the access description and shortening the quotas description.

• What it returns: each release has its short sha, the pull that landed it (repo and number), when it landed, and whether its preflight passed (ok). The live release adds live: true, its version and since. Releases don't store a version, so the others show version: null.
• Who can call it: it uses the same mayRead gate as the /releases page, so a refused reader gets a forbidden error that says why. It has no rollback; a person does that on the page.
• Tests and docs: test/mcp-releases.test.ts covers an empty forge, an allowed reader seeing the live release marked, and a refused reader. docs/MCP.md has one new row.
• Cut detail: I left the size limit alone, since the test says it belongs to the owner, and shortened the existing tool descriptions to fit. Some detail is gone from them: asks_act no longer says "(never undone)", pull drops checkStale, and cloud_account drops the audit verb.

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 [82.52ms] [shard 103]

Red on top of #5399, 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.

This pull adds the read-only MCP tool releases. The gate-audit test that went red on land is fixed in scripts/shards.ts and passes locally. The type check is clean. test/shards.test.ts, test/mcp-size.test.ts, test/mcp.test.ts, test/asks-mute.test.ts and test/mcp-releases.test.ts pass. I merged origin/main and pushed to the same branch, and haven't seen the forge's gate run again.

• The red test: it builds a shard spec from the gate's file count plus one, such as 1000/1000. parseShardSpec in scripts/shards.ts only accepted up to three digits, so once the gate reached 999 files the spec was refused and nothing ran. It was a bug in scripts/shards.ts (the three-digit cap) that no test pointed at, not in the test. It showed up when the gate crossed 999 files, which #5399 and this pull's new test file together did. I widened the pattern to four digits. It is outside the issue's file list; it is the cause of the red gate.
• Sentinel's nit: I put "(never undone)" back on ship in the asks_act description. The size budget allows it and test/mcp-size.test.ts still passes.
• What the tool does: releases takes no arguments. It answers the kept releases newest first through the same mayRead gate as the /releases page. Each release shows its short sha, the pull that landed it, when, and whether its preflight passed (ok). The live one adds live: true, its version and since. A reader the page refuses gets a forbidden error in words. It has no rollback.
• Tests and docs: test/mcp-releases.test.ts covers an empty forge, an allowed reader and a refused one. docs/MCP.md has the new row.

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.

The branch is merged with main, and the MCP releases tool now lives in its own file, src/http/mcp/tools/releases.ts, as the #5932 split requires. The MCP and shard tests pass and tsc --noEmit is clean. I did not run the whole check, since the forge runs it on the push.

• Conflicts: src/http/mcp.ts took main's version because the tools moved out of it. docs/MCP.md was conflicted and is regenerated with bun scripts/mcp-tools.ts, which also adds the releases line to tools/index.ts.
• What the tool does: unchanged. It is read-only and behind mayRead, the same gate as the /releases page and the terminal screen. It lists kept releases newest first, marks the live one with live and since, and offers no rollback.
• Budget: the tool pushed tools/list over the 37,000-byte limit in test/mcp-size.test.ts. I did not raise the limit. I shortened the descriptions of releases and a few other tools, and bun test test/mcp passes with the limit unchanged.
• Shortened descriptions: tell, issue, decisions_by, probe, new_app, prompts, front_page, follow_mode, egress_grants, hooks, plan, flow, asks_act, and a few property descriptions. For these I trimmed wording only, and no test pins any of it. Check those edits if you want.
• scripts/shards.ts: four-digit shard specs stay, because the gate has passed 999 files.

Not done: sentinel's note about extra refusal tests (a non-admin who can read the forge repo, and an agent). mayRead is shared with the page and tested there.

I made no code change for this note.

I kept forbidden in src/http/mcp/tools/releases.ts:15. Sentinel marked the note low and non-blocking and said the current behaviour is fine. A tool caller has already authenticated with a bearer token, so forbidden plus the message naming who may read tells an agent why it was refused. A not_found would hide that. The page answers notFoundPage because a browser has no other way to be refused. The tool and the page use the same mayRead gate, so they agree on who is let in. They differ only in how the refusal is worded.

The refusal test (test/mcp-releases.test.ts:91) still asserts the current message. I didn't re-run the tests, since nothing changed.

Nothing new was pushed, so the branch is the same as at head 37404967.

Summary of the pull: MCP releases is a read-only tool. It lists the forge's kept releases newest first: short sha, version, the pull that landed each one (as owner/name plus number), when, and ok. The live release is marked live: true with since. It is gated by mayRead from release/gate.ts, the same gate as /releases and the terminal screen. It leaves out the preflight line, which can carry log text, and it has no rollback. To try it, call releases through /mcp with a bearer token.

The releases MCP tool now merges cleanly with main. The pull had conflicts, which I resolved by merging main in. Nobody had commented on it since my last run.

I ran the three tests that cover this change (test/mcp-releases.test.ts, test/mcp-size.test.ts, test/mcp.test.ts). All 50 pass, and bun x tsc --noEmit is clean. I did not run the rest of the suite, and the forge's check on this push hasn't come back yet.

• What it does: releases takes no arguments and answers the kept releases newest first. Each release has its short sha, the pull that landed it, when it landed, and whether its preflight passed. The live one also carries live: true, its version and since. It sits behind the same mayRead gate as the /releases page, so a refused reader gets the page's refusal in words. The tool is in src/http/mcp/tools/releases.ts, with a row in docs/MCP.md.
• What changed in this push:

- Merge: the conflicts came from the description trims I made in the earlier push. I took main's version of every conflicted tool file instead of resolving them one by one. The earlier cuts to asks_act, access, quotas and pull are gone, so those descriptions read as they do on main. - Size budget: with releases added, tools/list was 142 bytes over the 37,000-byte headroom in test/mcp-size.test.ts. I trimmed a few words from spawn, plan, cloud_account, limb, feed and front_page instead of raising the limit, which the test says is the owner's to change. The cuts are mostly in descriptions that were already one short sentence: limb's close no longer mentions reason in its description, and spawn no longer mentions its apps and briefs.

• Not done: there is no rollback tool; a person does that on the /releases page. Releases don't store a version, so only the live one shows it and the others show null.
• Try it: call tools/list and then releases over /mcp on the preview at https://lab--5388--forge-trevato-apps.open-platform.sh, or run bun test test/mcp-releases.test.ts.

Closes #5365

🤖 Generated with Claude Code

I merged main into this branch and pushed it. The MCP tests pass (45) and tsc --noEmit is clean. I didn't run the full suite, because the forge's check does that on the push.

The conflicts were in src/http/mcp/tools/feed.ts and src/http/mcp/tools/spawn.ts. In both, main had reworded a tool description that this branch had already shortened so tools/list fits its size budget with the releases tool added. I kept the shorter wording:

• feed: "Your ranked home timeline; cursor pages; feed_chips apply."
• spawn: "Spawn a child forge. Plans first."

The releases MCP tool itself is unchanged by the merge. The longer main wording for those two descriptions is gone, so a person may want to look at it if they preferred it.

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

• now reads its rows in batches with 200 open issues, 40 open pulls and 5 active runs
• now reads its rows in batches with 200 open issues, 40 open pulls and 5 active runs [297.45ms] [shard 253]

The gate's log: /api/v1/repos/trevato/forge/gates/1793049223067-2c73118d00ec/log

I took @sentinel's note: the releases tool now names a release with releaseName(r) from release/record.ts, so the sha is 12 characters, the same as on the /releases page. tsc --noEmit is clean. test/mcp.test.ts and test/app-home-batched.test.ts pass, and I've pushed with main merged in again.

I didn't change anything for the red gate test. "now reads its rows in batches…" in test/app-home-batched.test.ts failed on a timing budget, and its log line says Expected: < 5, Received: 5. That is a measured time in ms on a loaded gate machine, not a count. This pull doesn't touch the repository home or its queries, and the test passes here, both before and after the merge. I take it to be a flake, so I left the test alone. If it fails again on this head, that points to something on main.

I didn't add a test for the 12-character sha.

The failing test was mine. I had switched the releases tool to the page's 12-character releaseName, and test/mcp-releases.test.ts still expected the old 7-character shas. I updated its expectation to 12 characters. test/mcp-releases.test.ts and test/mcp.test.ts now pass (48 tests), and I've pushed the fix. I didn't run the rest of the suite.

I missed this last time because I ran test/mcp.test.ts and not test/mcp-releases.test.ts.

This pull adds a releases MCP tool. It lists the forge's kept releases and names each one the way the release page does, by its 12-character release name.

The check failed on asks-mute.test.ts ("MCP asks applies the saved filter…"). It requires the feed and asks tool descriptions to say "saved filter". While trimming tool descriptions to stay under the tools/list size limit, I had shortened the feed one to "feed_chips apply." and lost that phrase. It now reads "Your ranked home timeline; cursor pages; saved filter applies." The test was right and the code was wrong, so I changed only src/http/mcp/tools/feed.ts.

asks-mute, mcp and mcp-releases tests pass locally (54 tests). I did not re-run the rest of the check. Its log shows three other shards killed after the fail-fast stop, so I haven't seen those pass.

To try it, call the releases tool over the MCP. It is documented in docs/MCP.md.