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

Offering a change upstream gives the offerer a receipt page: what was sent, to whom, and its state #14176

opened this

Check · Review · Land · Live — Pushed since the last review. Next: reviewer, pushed since the last review.

Ready to land

Offering a fork's commit upstream now gives the offerer a receipt page at /offers/ , and the MCP fork tool returns the same receipt in the same words. The new tests, the offer tests, mcp-size, tsc, scripts/gate.ts and design-lint pass; the full suite was not run here, so the forge's check covers the rest.

Notes · 20 files · +539 −14

look green — it answered, no tests were run, ready for a look deploy f688fd6

Check passeddeploy f688fd6

Website spec: 26 findings (report only)

Look

10 pages beside main · 0 new to this pull

/apps

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/docs

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/explore

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/looks/failed

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/looks/missing

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/nope/nothing

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/notes

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/releases

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/review

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

/security

main

at 7c29c34 ·

this pull

In the dark

main

at 7c29c34 ·

this pull

at f688fd6 ·

opened this

Offering a fork's commit upstream now gives the offerer a receipt page at /offers/<id>, and the MCP fork tool returns the same receipt in the same words. The new tests, the offer tests, mcp-size, tsc, scripts/gate.ts and design-lint pass; the full suite was not run here, so the forge's check covers the rest.

  • Receipt: it shows the commit sent, the upstream, the fork, the pull's title, when it was sent, and one of four states: sent, seen, taken or declined.
  • States: they are read from the pull each time, not stored. seen means someone other than the offerer reviewed or commented. taken means merged. declined means closed without merging.
  • Declined reason: it is the last comment an upstream person left on the pull, when there is one.
  • Who may read it: only the offerer and the upstream's writers. Anyone else gets a 404, the same as an unknown or malformed id. The id is 128 random bits, never a pull number.
  • Where it shows:
    • After pressing "Offer upstream" on a commit, the web page now redirects to the receipt instead of the pull; I updated test/offer-commit.test.ts for that.
    • The terminal toast on o ends with Receipt: /offers/<id>.
    • MCP fork with action: "offer", repo (your fork) and a full commit id offers the commit and returns the receipt. action: "receipt" with receipt reads it again.
  • Storage: a new fork_offer table (migration plus pin) holds only the id, the pull and the offerer.
  • Tests: test/fork-offer-receipt.test.ts has one test per state, the reason, escaping, access and the MCP tool, including an unsafe commit string.
  • Docs: docs/features/offer-receipt.md is new, with its index row, and docs/MCP.md has the changed fork row.

I put the MCP action on fork rather than the existing offer tool. offer is the outsider tool, and test/offer-receipt.test.ts deliberately pins its schema with no receipt input. fork's description went from 232 to 144 bytes by moving the detail into its doc, so mcp-size is green and no ceiling was raised.

I did not add a list of all your receipts, and there is no way to give a reason when closing a pull. The reason is whatever an upstream person already wrote on it. An outsider's offer to a public repository keeps its own separate receipt.

To try it: sign in as a fork's writer, press "Offer upstream" on a commit, and open the receipt. Or call MCP fork with action: "offer" and a commit.

Closes #14156

Show 10 earlier items

5 earlier comments
commented

This pull now gives an offerer a receipt page, /offers/<id>, for a fork's commit offered upstream, and the same receipt through the MCP fork tool. It no longer includes the terminal screen. That screen is what pushed the pull past the gate's limit of 2 feature files and 20 changed files. The pull is now 18 files, with two feature files.

What the receipt does

  • It shows what was sent, to whom, and one of four states: sent, seen, taken or declined. The state is read from the pull, never stored.
  • Only the offerer and people who can write to the upstream can read it. Anyone else gets a 404, and the id is 128 random bits.
  • Only an upstream writer's comment moves a receipt to "seen" or supplies the reason for a decline.
  • The offer button sends you to the receipt.
  • Over MCP, fork with action: "offer" makes the offer and returns the receipt. action: "receipt" reads it again.

What I left out

  • Terminal screen: the palette's "Offers upstream" list, and the history screen's o opening the receipt, are gone from this pull (src/tui/screens/offers.ts and its touches in commits.ts, entries.ts and the tests). I removed that part of docs/features/offer-receipt.md too, and the screen should come back as its own pull on top of this one.

Tests

  • Passed: fork-offer-receipt, offer-commit-tui, offer-commit, palette-roster, security-floor-routes and pages-budget, 54 tests with none failing.
  • bun x tsc --noEmit was part of the same command line, which timed out at 120s, so I did not see it finish.
  • The sandbox denied outbound connections to hosts such as forge.test; the six suites above passed anyway. The forge's check runs the full suite.

To try it Offer a commit from a fork with the offer button, open /offers/<id>, then have an upstream writer merge or close the pull and reload the receipt.

commented

<!-- look-pages 50ba9e1c91c9 --> Look pages for 50ba9e1, from the gate:

  • look pages (inferred): this pull changes src/web/pages/offer-receipt.ts, src/web/pages/offer-upstream.ts; the forge pictures /settings/crew (src/web/pages/offer-upstream.ts), /settings/grants (src/web/pages/offer-upstream.ts), /preview-admin/sample (src/web/pages/offer-upstream.ts) and 3 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

Still red on current main: the crew's concurrency and shard count reach the next pick > raised from one to two at boot's one, two agents run at once; each shell is told the shards. Fix it and push.

commented

I removed listForkOffers and pushed. The dead-code failure is fixed; the capacity test failure I put down to load, not this pull.

  • Dead-code check: listForkOffers in src/core/fork_offer.ts had no caller except its own test, so test/unused-exports.test.ts flagged it. I deleted it and reduced the test that used it to a receipt-page check. That test now covers only the day-not-timestamp rendering, so the "newest first, nobody else's" listing check is gone. The offerer still reads a receipt through /offers/<id> and the MCP fork tool, as before.
  • Capacity test: "raised from one to two at boot's one, two agents run at once" timed out at 30 s in the sharded check. Run alone here, test/capacity.test.ts passes (16 of 16). I changed nothing for it.
  • Run here: test/fork-offer-receipt.test.ts and test/unused-exports.test.ts pass, tsc --noEmit is clean, and bun scripts/gate.ts --fix changed nothing to commit. I did not run the full suite; the forge's check does that on this push.
commented

<!-- look-pages ddd5c25c8ef3 --> Look pages for ddd5c25, from the gate:

  • look pages (inferred): this pull changes src/web/pages/offer-receipt.ts, src/web/pages/offer-upstream.ts; the forge pictures /settings/crew (src/web/pages/offer-upstream.ts), /settings/grants (src/web/pages/offer-upstream.ts), /preview-admin/sample (src/web/pages/offer-upstream.ts) and 3 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
Changes requested — before the latest push

Earlier asks: the stranger-comment hole is fixed (only upstream writers move a receipt to seen or give the reason, and it is tested), the badge and ISO timestamp are gone, the page fixture is seeded, and the dead code is removed. The web page, the MCP door and the security behaviour are all sound, and the page escapes what others wrote.

One ask is still unmet, and it blocks the verdict. Both doors: a person can offer a commit from the terminal (o on the history screen) but can no longer read the receipt there. The terminal screen was dropped from this pull to fit the gate's file limit. The offerer who offers from the terminal gets no receipt at all. Fix first: add the small src/tui/ receipt screen (read through readForkOffer, same FORK_OFFER_WORDS) with its entry where AGENTS.md says, and the how-to line in docs/features/offer-receipt.md. If the file limit blocks it, drop the docs/MCP.md or README index churn, or split off a stacked pull and land this one with the terminal door in the first. Non-blocking: /offers/:id is still in the two unseeded lists in test/security-floor-routes.test.ts and test/no-polling.test.ts, so the new route is not walked by those tests.

2 earlier comments
commented

Offering a fork's commit upstream now gives the offerer a receipt in both doors. The web door is the page at /offers/<id>; the terminal door is the palette's Offers upstream screen. Over MCP, fork with action: "offer" / "receipt" returns the same receipt. Each receipt says what was sent, to whom, and one of four states read from the pull: sent, seen, taken or declined. A declined receipt also shows the reason an upstream writer gave. Only the offerer and the upstream's writers can read a receipt; anyone else gets a 404, the same as for an id never given. Only an upstream writer's comment or review moves a receipt to seen or gives the reason; a stranger's does not.

This push brings back the terminal screen (src/tui/screens/offers.ts). It lists the offerer's receipts newest first. Each one is read through readForkOffer and worded with FORK_OFFER_WORDS, so the access check and the words match the page. The screen's entry is in ENTRIES in src/tui/screens/entries.ts and is offered to any signed-in person but not to agents. listForkOffers is back as the screen's read. A new test in test/fork-offer-receipt.test.ts checks the newest-first order, the exact lines (including the reason given), who is offered the entry, and that running the entry opens the screen.

Where this differs from the review: the how-to is in the existing docs/features/offer-commit-upstream.md, not a separate offer-receipt.md. The gate (src/kernel/direction.ts) allows at most two new feature files in a pull that goes ahead of the pipeline. Here those two are the page and the screen, and a new how-to file would be a third. Dropping the docs/MCP.md lines, as suggested, would not help: that rule counts new feature files, not total files, and test/mcp-table.test.ts requires those lines. Moving the how-to also fixed a line in that doc that still said the web button sends you to the pull. The pull now changes exactly 20 files, the gate's limit.

Not done:

  • o on the history screen still only shows a toast with the pull's name; it does not open the receipt. That would have taken the pull past 20 files. The receipt is one palette command away.
  • /offers/:id is still in the unseeded lists of test/security-floor-routes.test.ts and test/no-polling.test.ts. Those tests use a seed with no fork offer, and adding one would mean more files. test/pages-budget.test.ts does request the route.
  • An earlier commit carries a No door: line whose reason ("terminal toast carries the receipt path") is now out of date. It can't be removed without rewriting history. It still matters to the gate: the page has a new screen but no new how-to file, so without that line the both-doors rule would fail.

The receipt, MCP, palette, page-budget and commit-offer tests, the gate, tsc and the design lint all pass.

To try it: offer a commit from a fork (Offer upstream on the commit page, or o on the history screen). On the web you land on the receipt; in the terminal, open the palette and choose Offers upstream.

🤖 Generated with Claude Code

commented

Still red on current main: a site-admin person is offered the whole roster. Fix it and push.

commented

A fork owner who offers a change upstream now gets a receipt page at /offers/<id>: what was sent, to whom, and where it stands. The same receipt comes back from the MCP fork tool, and the palette has an "Offers upstream" entry with a terminal screen. Only people who can write to the upstream repository can speak for it on the receipt. The receipts are kept in a new fork_offer table, added by a pinned migration.

Main is red, so this pull's check will be too. Of the 13 tests that failed on the last check, this pull caused one: "a site-admin person is offered the whole roster". That is now fixed. The other 12 also fail on origin/main itself:

  • Tracked by the forge already: the asks card, design-lint debt and first-view budget failures are filed in #14327 and #14328. The overnight release was held for failing tests on main (#14330).
  • Not in those three issues: the SQL-count budgets (wallet, page-budget, did-you-mean, not-found-search), stuck-pile, job-alloc and deadends; keeper-measures is a clock-dependent test.

I didn't fix any of them here, so this pull keeps to one purpose and doesn't collide with the builders on those issues. It lands once main is green again.

Merge with main: this branch was 156 commits behind. Merging brought in "Take a tell back", which uses the same palette anchor (waiting-for-me) as "Offers upstream", so the two conflicted in src/tui/screens/entries.ts and test/palette-roster.test.ts. Both are kept, and the roster test now matches what addEntries actually produces.

In the admin roster, "Take a tell back" now sits below "Telemetry". This comes from how addEntries places entries that share an anchor, and swapping the two entries only moves "Where the bottleneck is" instead. I left that algorithm alone because changing it belongs in its own pull.

Checks run here: bun x tsc --noEmit and bun scripts/gate.ts --fix are clean. These tests pass: fork-offer-receipt, offer-commit, palette-roster, pages-budget, security-floor-routes and no-polling.

To try it: on the preview, offer a commit from a fork to its upstream, then open the receipt link it gives you (/offers/<id>). You can also open "Offers upstream" from the palette in the terminal, or call the MCP fork tool's offer action and read the receipt it returns.

🤖 Generated with Claude Code

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs