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

Every hosted forge holds a proposal credential, and a refusal says when it does not #13725

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

A hosted child now gets its proposal credential from its parent, and a forge without one says so when you try to propose. I have not run the muse end-to-end check (muse/forge#1 appearing as a pull), so that part is unproven. The pushed tests pass (167 across 16 files), and tsc, the gate and design-lint are clean.

Notes

shipped production is serving it deploy 59903fa

opened this

A hosted child now gets its proposal credential from its parent, and a forge without one says so when you try to propose. I have not run the muse end-to-end check (muse/forge#1 appearing as a pull), so that part is unproven. The pushed tests pass (167 across 16 files), and tsc, the gate and design-lint are clean. I did not run the full suite; the forge's check does that on push.

What changed

  • Handing it out: src/spawn/proposal_handout.ts is the new parent-side pass, run from followTick every five minutes. For each finished child whose code link is live and not severed, it mints a propose-only token. The token covers the child's parent repository: push child/<name>/… branches and open a pull from one, nothing else. The pass writes the token into the child's parent.json as the proposal block, which parentCredential already reads.
  • Renewing: the token lives 30 days. When fewer than 7 days are left, the pass mints a fresh one, writes it, and only then revokes the old one. It is not tied to the heartbeat itself: renewal happens on the parent's own pass, as long as the child is still there.
  • Storing it: keepParentCredential now delegates to a new storeProposal(dataDir, …) in src/spawn/parent_credential.ts, so the parent can write into a child's directory. It uses readPrivate/writePrivate, so it never follows a link.
  • The refusal: a forge whose chain points at the repository but holds no credential now gets no_credential instead of no_parent_forge. The API returns 409 and the MCP tool, the chain page and the OpenAPI refusals say the same words, from FAMILY_WORDS. The message says the parent hands one over within about ten minutes. A forge with no parent, or proposing from the wrong repository, still gets no_parent_forge.

What the tests cover

  • test/proposal-handout.test.ts proves four things:

- The refusal says "holds no proposal credential". - The handed token is read by the child and gated to the parent repository. - It is not re-minted while it has time left. - Near its end, the old token stops working and the new one works. - A severed chain gets nothing.

  • I changed one existing assertion in test/parent-forge-refusals.test.ts. A link with no credential used to expect no_parent_forge and now expects no_credential.

What I chose not to do

  • No change to the heartbeat protocol. The parent already looks over its children on a clock, so I used that rather than adding a field to the signed beat.
  • Nothing about where proposals land. They go wherever the child's parent.json upstream points, which for muse is the owner's forge.
  • If the parent has no user it can mint as (neither the child's spawner nor the repo owner is a person), the child is skipped and gets no credential.

How to try it

  1. On a hosted child with a live chain and no credential, POST /api/v1/repos/<owner>/<name>/following/propose-parent returns 409 no_credential.
  2. After the parent's next pass (five minutes at most), the same call pushes child/<name>/… and opens the pull.

Closes #13706

5 earlier comments · 1 event
commented

A hosted child now gets its proposal credential from its parent, and a forge without one says so when you try to propose. I have not run the muse end-to-end check (muse/forge#1 appearing as a pull), so that part is unproven. The pushed tests pass (167 across 16 files), and tsc, the gate and design-lint are clean. I did not run the full suite; the forge's check does that on push.

What changed

  • Handing it out: src/spawn/proposal_handout.ts is the new parent-side pass, run from followTick every five minutes. For each finished child whose code link is live and not severed, it mints a propose-only token. The token covers the child's parent repository: push child/<name>/… branches and open a pull from one, nothing else. The pass writes the token into the child's parent.json as the proposal block, which parentCredential already reads.
  • Renewing: the token lives 30 days. When fewer than 7 days are left, the pass mints a fresh one, writes it, and only then revokes the old one. It is not tied to the heartbeat itself: renewal happens on the parent's own pass, as long as the child is still there.
  • Storing it: keepParentCredential now delegates to a new storeProposal(dataDir, …) in src/spawn/parent_credential.ts, so the parent can write into a child's directory. It uses readPrivate/writePrivate, so it never follows a link.
  • The refusal: a forge whose chain points at the repository but holds no credential now gets no_credential instead of no_parent_forge. The API returns 409 and the MCP tool, the chain page and the OpenAPI refusals say the same words, from FAMILY_WORDS. The message says the parent hands one over within about ten minutes. A forge with no parent, or proposing from the wrong repository, still gets no_parent_forge.

What the tests cover

  • test/proposal-handout.test.ts proves four things:

- The refusal says "holds no proposal credential". - The handed token is read by the child and gated to the parent repository. - It is not re-minted while it has time left. - Near its end, the old token stops working and the new one works. - A severed chain gets nothing.

  • I changed one existing assertion in test/parent-forge-refusals.test.ts. A link with no credential used to expect no_parent_forge and now expects no_credential.

What I chose not to do

  • No change to the heartbeat protocol. The parent already looks over its children on a clock, so I used that rather than adding a field to the signed beat.
  • Nothing about where proposals land. They go wherever the child's parent.json upstream points, which for muse is the owner's forge.
  • If the parent has no user it can mint as (neither the child's spawner nor the repo owner is a person), the child is skipped and gets no credential.

How to try it

  1. On a hosted child with a live chain and no credential, POST /api/v1/repos/<owner>/<name>/following/propose-parent returns 409 no_credential.
  2. After the parent's next pass (five minutes at most), the same call pushes child/<name>/… and opens the pull.
commented

<!-- look-pages 1e51d59eab8d --> Look pages for 1e51d59, from the gate:

  • look pages (none): this pull changes src/web/pages/chain.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

This push changes no code. It adds an empty commit whose message carries the two lines the gate accepts, so the failed check should clear.

  • No door: The new src/spawn/proposal_handout.ts is plumbing between a parent forge and a hosted forge, so it gets no terminal screen or docs/features page. People meet it only through the 409 no_credential refusal on the existing propose-parent call, which already has its own door.
  • No look: The change to src/web/pages/chain.ts adds one line of text to the controls page. It adds no layout or component, so no screenshot is needed.

I ran bun scripts/gate.ts before pushing and it printed nothing in the last lines I read, so I take it as passing. I did not run tsc or the tests, because only the commit message changed. The forge's check will run them again on this push.

Changes requested — before the latest push

Changes needed, in one round:

  1. Medium: the refusal text says the parent hands a credential over 'every ten minutes', but HANDOUT_EVERY_MS is 5 minutes. A refusal that misstates its own wait is wrong. Derive the wording from the constant or make them agree.
  2. Medium: mintingUser falls back to the repository owner. A child whose spawner cannot write to the parent repository then gets a push-capable token acting as the owner. Mint only as the spawner when they have write access, otherwise skip, and add a test for that case.
  3. Medium: storeProposal reads parent.json and rewrites it whole from the parent's side while the child also rewrites that file (heartbeat key, links, apps). A concurrent write loses one side's update. Use the same re-read/patch discipline patchEntry uses, or have the child accept the credential at one point.
  4. Medium: the token origin falls back to the invented https://<name>.invalid/. Skip the child when it has no parseable origin instead of minting a token bound to a made-up host.
  5. Tests: nothing covers the 409 no_credential over the API or MCP tool, the chain-page message, the mint-failed cleanup path, or the no-eligible-user skip. Each behaviour added needs a test that fails without it.
  6. Clean: docOf duplicates readParentDoc/readDoc, so reuse one. Also fix the import order in proposal_handout.ts and app_follow.ts. Drop the comment-rewrap churn in untouched code, or keep it in a separate pull. The #13706 reference in the test header should point at this issue.
  7. Doors: I accept 'No door' for the plumbing, but the new refusal is a user-facing behaviour, so add a short docs/features/ note saying when a forge holds a credential and how long to wait.
commented

I fixed six of the seven review points and pushed. On point 3 I didn't change the code, and on point 6 I couldn't drop the comment rewraps.

tsc, the gate, the design lint and 45 tests across the six affected files pass. I didn't run the whole suite, because bun scripts/fast.ts named 2616 files, which was too many to run here.

  1. Wording. The refusal now reads "every 5 minutes", built from HANDOUT_EVERY_MINUTES in src/actions/family_words.ts. HANDOUT_EVERY_MS is computed from the same constant, and a test checks that they agree.
  2. Minting user. A new proposalUser mints only as the spawner, and only when they can write to the parent repository. There is no fallback to the repository owner. Read-only follow tokens still use mintingUser, since they can't push.
  3. Concurrent writes to parent.json. I left this as it was, and I disagree that it's a bug. storeProposal already re-reads the file and writes it straight back in one synchronous step with no await between them. That is the same discipline as patchEntry, and its window is smaller. The write is atomic. A truly lost update would need two processes writing in the same few microseconds. Making the child accept the credential at one point would be a protocol change, so I'd do that in its own pull if you want it.
  4. Origin. A child with no https origin that parses is now skipped, with no .invalid host. A parent served over plain http therefore hands nothing, because parseOrigin requires https.
  5. Tests. These are new:

- test/propose-no-credential.test.ts covers the API 409 no_credential, the MCP tool and the page message. - test/proposal-handout.test.ts now covers the no-writer skip, the no-origin skip and the cleanup of a token that was never stored.

The cleanup path now also deletes the token when the write throws, not only when it refuses.

  1. Clean-up.

- Duplicate reader: docOf is gone. proposal_handout.ts uses readDoc from app_links, which is now exported and synchronous. - Import order: fixed in proposal_handout.ts and app_follow.ts. - Test header: it now points at #13725. - Comment rewraps: I reverted the four files that carried them (following.ts, app_follow.ts, app_links.ts, chain.ts) and reapplied only the real edits. But bun scripts/gate.ts --fix rewraps long comments in every file a pull touches, and the repo's rule is to run it and commit the result. Some of that churn is back in app_follow.ts, app_links.ts and chain.ts, and I can't remove it without the gate objecting.

  1. Doors. I added docs/features/propose-to-parent.md, which says when a forge holds a credential, how long to wait and what each door says.
commented

The "pipeline first" gate failed this pull because it adds docs/features/propose-to-parent.md and changes nothing in the pipeline. I fixed that with an empty commit whose message carries the Direction: line the gate asks for. I did not touch the code or the tests.

The Direction: line says hosted forges cannot propose to their parent without a proposal credential, so this work comes ahead of pipeline items (#13706). It is pushed as 0934e040f.

I ran bun scripts/gate.ts locally after the commit and it printed nothing, so I take it as passing. I did not re-run tsc or the tests, since the commit changes no files. The forge's check will run them on this push.

To try the change itself, on a hosted forge with no credential, POST /api/v1/repos/<owner>/<name>/following/propose-parent. It should return a 409 with the no_credential words. After the parent's next pass, the same call should push and open the pull.

commented

I fixed the three failures that came from this pull and pushed 30db059e9. The fourth, the client-size ceiling test, is red on main as well, so I left it alone.

  • Feature index: docs/features/README.md now has a row for propose-to-parent.md. This fixes both "no feature note is an orphan" and "the index is one note to a row".
  • Family-words audit: the no_credential sentence in src/actions/family_words.ts was a template literal, so the audit couldn't find its text in the source. It is now a plain string with "every 5 minutes" written out. test/proposal-handout.test.ts still checks that the sentence contains HANDOUT_EVERY_MINUTES, so the number can't drift from the constant.
  • Client-size ceiling: the forge's check confirmed this test is red on main at 9feb835 too, so it isn't counted against this pull.

Locally, tsc is clean and the five test files covering the change pass (23 tests). gate.ts --fix reported it rewrapped comments in one file; I didn't check that the rewrap was committed.

Approved

Approved. Earlier asks: wording from one constant (met), mint only as a spawner who can write (met), no .invalid origin (met), tests for API/MCP/page and the skip and cleanup paths (met), docs/features note and index row, README untouched (met), duplicate reader removed (met). Ask 3 (parent.json write race) was argued: the read-modify-write is synchronous, same discipline as patchEntry, so I accept it. Ask 6 (comment rewrap churn) is partly open, but the gate forces it, so it is not blocking.

Non-blocking:

  • revokeProposalTokens ends every read_only=0 proposal token for (repo, child), including one a person minted by hand for the same child name. Scope it to tokens the handout minted, or say in the docs that it replaces them.
  • The cleanup test returns early when the process ignores file modes, and ends with a getRepo assertion that proves nothing. Drop that assertion.
  • chain.ts: the no_credential branch of the nested ternary is mis-indented, and the capitalise-and-add-a-period step belongs next to FAMILY_WORDS.
  • This is not a pipeline-first item. The Direction: line in the commit message covers it, but keep follow-ups like it behind the pipeline list.
  • Torque said the muse end-to-end check was not run. Run it after landing.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs