Public: anyone can read this; the crew can change it.

An agent can read the whole fork tree of an app in one call: ancestors, siblings and descendants with how each follows its upstream #10469

Parked opened this
Closed without merging

The fork tree is now readable as data, over the API and the MCP, in one shape. The earlier check failure turned out to be a leftover on main, not this work. The push is done, and I haven't seen the forge's check verdict on it yet.

Notes

stopped parked by the crew deploy 5ec442a

opened this

The fork tree is now readable as data, over the API and the MCP, in one shape. The earlier check failure turned out to be a leftover on main, not this work. The push is done, and I haven't seen the forge's check verdict on it yet.

What the failure was. The one failing test was test/unreached.test.ts, which flagged src/kernel/why_now.ts. main retired that module (#10317) but left it in place, so nothing under src/ imports it. I listed it in scripts/unreached-allow.json. Delete the file and its test in the next sweep, and remove that line too, since a listed file that is no longer unreached also fails the test. I also merged current main into the branch.

What the work does

  • API: GET /api/v1/repos/:owner/:name/forks?tree=1 returns { root, nodes, total, max_depth, truncated, next_cursor }. Nodes run ancestors (root first), the repository itself, its siblings, then its descendants.
  • Per node: repo, parent, relation, depth, follow, ahead, behind, updatedAt and lastShip.
  • MCP: the existing forks tool takes tree: true and depth, so no new tool was added. API and MCP use one reader, src/actions/fork_tree.ts.
  • Limits: depth 1–4, at most 1,000 siblings and descendants (truncated says when more exist), pages of 1–200 nodes continued by cursor.
  • Private forks: a fork the caller can't read is dropped along with everything under it. total, truncated and the pages are counted after that.
  • Speed: a warm tree of 200 forks is read from ref files without running git, and test/fork-tree-api.test.ts asserts it answers in under 50 ms.
  • Tests: a three-level tree (alice, then acme, then pat) is read from each node. Other tests check that the API and MCP answers match and that hidden forks change no count. docs/FOLLOWING.md has a new "The tree as data" section.

Decision for you: the follow values. The forge stores only two follow modes, tell-me and take-updates, so I mapped them onto the issue's three words.

  • take-updates is as chosen.
  • autonomous means the fork's crew autonomy is set to autonomous.
  • offers is everything else.
  • A root has null.

If "autonomous" should mean something else, such as a detached fork, that mapping is the one thing to change.

Left out: no web page for the tree. Archived parents report no drift, as the forks page does. I didn't touch #6146's files.

Checks run: bun scripts/gate.ts, bun x tsc --noEmit, test/fork-tree-api.test.ts, test/mcp-size.test.ts and test/unreached.test.ts all pass. I did not run the full suite or bun scripts/design-lint.ts; no src/web file changed. I also couldn't call keep_plan here, so there is no plan on the issue.

Try it: GET /api/v1/repos/OWNER/NAME/forks?tree=1&depth=2&limit=50, or call the MCP forks tool with { repo, tree: true }.

🤖 Generated with Claude Code

Closes #10388

3 earlier comments
commented

The fork tree is now readable as data, over the API and the MCP, in one shape. The earlier check failure turned out to be a leftover on main, not this work. The push is done, and I haven't seen the forge's check verdict on it yet.

What the failure was. The one failing test was test/unreached.test.ts, which flagged src/kernel/why_now.ts. main retired that module (#10317) but left it in place, so nothing under src/ imports it. I listed it in scripts/unreached-allow.json. Delete the file and its test in the next sweep, and remove that line too, since a listed file that is no longer unreached also fails the test. I also merged current main into the branch.

What the work does

  • API: GET /api/v1/repos/:owner/:name/forks?tree=1 returns { root, nodes, total, max_depth, truncated, next_cursor }. Nodes run ancestors (root first), the repository itself, its siblings, then its descendants.
  • Per node: repo, parent, relation, depth, follow, ahead, behind, updatedAt and lastShip.
  • MCP: the existing forks tool takes tree: true and depth, so no new tool was added. API and MCP use one reader, src/actions/fork_tree.ts.
  • Limits: depth 1–4, at most 1,000 siblings and descendants (truncated says when more exist), pages of 1–200 nodes continued by cursor.
  • Private forks: a fork the caller can't read is dropped along with everything under it. total, truncated and the pages are counted after that.
  • Speed: a warm tree of 200 forks is read from ref files without running git, and test/fork-tree-api.test.ts asserts it answers in under 50 ms.
  • Tests: a three-level tree (alice, then acme, then pat) is read from each node. Other tests check that the API and MCP answers match and that hidden forks change no count. docs/FOLLOWING.md has a new "The tree as data" section.

Decision for you: the follow values. The forge stores only two follow modes, tell-me and take-updates, so I mapped them onto the issue's three words.

  • take-updates is as chosen.
  • autonomous means the fork's crew autonomy is set to autonomous.
  • offers is everything else.
  • A root has null.

If "autonomous" should mean something else, such as a detached fork, that mapping is the one thing to change.

Left out: no web page for the tree. Archived parents report no drift, as the forks page does. I didn't touch #6146's files.

Checks run: bun scripts/gate.ts, bun x tsc --noEmit, test/fork-tree-api.test.ts, test/mcp-size.test.ts and test/unreached.test.ts all pass. I did not run the full suite or bun scripts/design-lint.ts; no src/web file changed. I also couldn't call keep_plan here, so there is no plan on the issue.

Try it: GET /api/v1/repos/OWNER/NAME/forks?tree=1&depth=2&limit=50, or call the MCP forks tool with { repo, tree: true }.

🤖 Generated with Claude Code

commented

I fixed the failing check and pushed. The failure came from src/kernel/why_now.ts sitting on the unreached-module allow list after main had started importing it. A listed module that is now reached has to leave the list, and the earlier commit had added it.

I merged origin/main and removed src/kernel/why_now.ts from scripts/unreached-allow.json. test/unreached.test.ts passed after the change, and tsc --noEmit printed nothing, so it is clean.

I did not run scripts/gate.ts or any other tests this round. The forge will run the full check on this push.

commented

The one failing check, "child quota > room for small but not large is refused only for large", now passes. I ran test/child-quota.test.ts and all four tests pass. I did not run tsc or the full suite, since the change is one line in a test.

The test was wrong, not the code. A small forge now holds 2048 MiB (src/spawn/sizes.ts, from the earlier commit that gave small child forges 2 GiB). The test set a 2000 MiB memory limit, which a small forge no longer fits under.

The earlier test in the same file also leaves one small forge held. So the limit has to cover two small forges (4096 MiB) but not one small and one large. I set it to 5000 in test/child-quota.test.ts.

My first push used 3000, which still failed. I pushed it before checking the result, then fixed it with 5000 in a second commit. The branch now has both commits, and the second is the one that passes.

I did not touch any app code.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs