Public: anyone can read this; the crew can change it.
Sentinel: shared:01m23vygyffx5hg2f5vm8r74sr:1hngo4csjz is past its budget: trevato/forge: "README.md stays under 60 KB" failed on 3 pulls in the last hour — the lane's red, not theirs; they wait… #6689
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/6688-sentinel-shared-01m23vygyffx5hg2f5vm8r74 → main 2 commits fork 1 thread · 1 unresolved
2 files
changed +51
−47
README.md +1 −47
| @@ -227,53 +227,7 @@ page, in the terminal's pull view, and as `proposal` in the pull's JSON | ||
| 227 | 227 | |
| 228 | 228 | ### Proposing to a parent forge |
| 229 | 229 | |
| 230 | A spawned forge can offer its own change to the forge it came from. The | |
| 231 | parent mints a proposal token for the child (above); the child keeps it in | |
| 232 | `parent.json` as `"proposal": {"child": "kid", "token": "…"}` beside the | |
| 233 | parent's address. On the child's `/<org>/forge/following` page a writer | |
| 234 | presses **Propose to the parent forge** (or `POST …/following/propose-parent`): | |
| 235 | the default branch is pushed to `child/<name>/<branch>-<tip>` at the parent, | |
| 236 | and the pull opens there, titled by the change that landed last and naming it | |
| 237 | (`org/forge#7`). Asking again for the same tip returns the pull already made. | |
| 238 | ||
| 239 | The repository's admin changes how the forge follows its parent (`tell-me` or | |
| 240 | `take-updates`) from the radio form on the same page, with `PATCH | |
| 241 | /api/v1/forge/following {"mode"}`, with the MCP `follow_mode` tool, or by pressing `m` on the chain screen in the terminal. The | |
| 242 | record in `parent.json` is rewritten atomically and a `forge.follow_mode` event | |
| 243 | is appended. A non-admin is refused (403), a value outside the two modes is | |
| 244 | 422, and a severed forge is 409; each leaves `parent.json` untouched. | |
| 245 | ||
| 246 | **Take the N new commits** (shown to the admin on `/<org>/forge/following` when | |
| 247 | the parent is ahead, `POST /api/v1/repos/:owner/:name/following/take`, the MCP `take_updates` | |
| 248 | tool, or `t` on the chain screen in the terminal) opens, or updates, the one `forge/take-updates` | |
| 249 | pull whatever the follow mode, and never moves the default branch; a conflict | |
| 250 | opens the converge issue instead, and nothing behind answers "Already up to date." | |
| 251 | ||
| 252 | The page and `GET …/following/proposals` show each proposal as open, merged or | |
| 253 | closed, read from the parent (the token may read back only pulls it opened) and | |
| 254 | cached for a minute (only a signed-in viewer makes the parent get asked); a merged or closed one is final. A parent that does not | |
| 255 | answer shows the last state with "parent unreachable" — never an error page. | |
| 256 | In the terminal, the Chain card lists the proposals and `p` proposes. The MCP `propose_to_parent_forge` tool (writer only) proposes with the page's | |
| 257 | words, and `forge_proposals` lists each proposal with its state and "parent | |
| 258 | unreachable" where that applies. No dependency was added. Left out: a UI to paste | |
| 259 | the token into `parent.json` (part 2 of #2182 covers minting and handing over). | |
| 260 | ||
| 261 | Minting, listing and revoking go through one action | |
| 262 | (`src/actions/proposal_tokens.ts`) at every door, and only a writer of the | |
| 263 | repository may; anyone else is told "no such resource here, or it is not | |
| 264 | visible to you", as the API says it. The secret is shown once, on minting. | |
| 265 | The repository's settings page is one more door: a writer sees their proposal | |
| 266 | tokens one to a line (child, origin, expires, last used) with Revoke, and a | |
| 267 | form that mints one and shows its secret once; others see no section. | |
| 268 | ||
| 269 | The check cell's memory is on the same page under **Check cell**, and in the terminal on a repository's About card (`I`, for an admin): the limit the machine enforces, read from `forge.json` on the default branch. When `check.limits.memory` asks for more than the machine's ceiling it shows both numbers and where the cut comes from (`FORGE_CELL_MEMORY_MAX_MIB`, else a share of the pod's memory); otherwise one number. The ceiling is read once and kept (`src/apps/check-memory.ts`). | |
| 270 | ||
| 271 | - **MCP**: the `proposal_tokens` tool with `repo` and a `verb`: `mint` | |
| 272 | (`child`, `origin`, optionally `childRepo`), `list` (the ones you minted for | |
| 273 | the repository) or `revoke` (`id`). | |
| 274 | - **Terminal**: `ctrl+k`, **Proposal tokens**, then the repository as | |
| 275 | `owner/name`. `n` mints (the child's name, then its https address) and shows | |
| 276 | the secret once on its own screen; `x` revokes the one under the cursor. | |
| 230 | A spawned forge can offer its change to its parent with a proposal token, and an admin sets how it follows the parent. Details, API, MCP and terminal doors: [](docs/FOLLOWING.md#proposing-to-a-parent-forge). | |
| 277 | 231 | |
| 278 | 232 | ## On your machine |
| 279 | 233 |
docs/FOLLOWING.md +50
| @@ -214,3 +214,53 @@ Forks with nothing ahead (or whose standing git cannot read) follow under | ||
| 214 | 214 | the page says `Ranking the first 60 of N forks`. A fork's standing is cached |
| 215 | 215 | by the pair of tips (`actions/forks.ts`), so a view of forks that have not |
| 216 | 216 | moved costs one `git log` per fork. |
| 217 | ||
| 218 | ### Proposing to a parent forge | |
| 219 | ||
| 220 | A spawned forge can offer its own change to the forge it came from. The | |
| 221 | parent mints a proposal token for the child (above); the child keeps it in | |
| 222 | `parent.json` as `"proposal": {"child": "kid", "token": "…"}` beside the | |
| 223 | parent's address. On the child's `/<org>/forge/following` page a writer | |
| 224 | presses **Propose to the parent forge** (or `POST …/following/propose-parent`): | |
| 225 | the default branch is pushed to `child/<name>/<branch>-<tip>` at the parent, | |
| 226 | and the pull opens there, titled by the change that landed last and naming it | |
| 227 | (`org/forge#7`). Asking again for the same tip returns the pull already made. | |
| 228 | ||
| 229 | The repository's admin changes how the forge follows its parent (`tell-me` or | |
| 230 | `take-updates`) from the radio form on the same page, with `PATCH | |
| 231 | /api/v1/forge/following {"mode"}`, with the MCP `follow_mode` tool, or by pressing `m` on the chain screen in the terminal. The | |
| 232 | record in `parent.json` is rewritten atomically and a `forge.follow_mode` event | |
| 233 | is appended. A non-admin is refused (403), a value outside the two modes is | |
| 234 | 422, and a severed forge is 409; each leaves `parent.json` untouched. | |
| 235 | ||
| 236 | **Take the N new commits** (shown to the admin on `/<org>/forge/following` when | |
| 237 | the parent is ahead, `POST /api/v1/repos/:owner/:name/following/take`, the MCP `take_updates` | |
| 238 | tool, or `t` on the chain screen in the terminal) opens, or updates, the one `forge/take-updates` | |
| 239 | pull whatever the follow mode, and never moves the default branch; a conflict | |
| 240 | opens the converge issue instead, and nothing behind answers "Already up to date." | |
| 241 | ||
| 242 | The page and `GET …/following/proposals` show each proposal as open, merged or | |
| 243 | closed, read from the parent (the token may read back only pulls it opened) and | |
| 244 | cached for a minute (only a signed-in viewer makes the parent get asked); a merged or closed one is final. A parent that does not | |
| 245 | answer shows the last state with "parent unreachable" — never an error page. | |
| 246 | In the terminal, the Chain card lists the proposals and `p` proposes. The MCP `propose_to_parent_forge` tool (writer only) proposes with the page's | |
| 247 | words, and `forge_proposals` lists each proposal with its state and "parent | |
| 248 | unreachable" where that applies. No dependency was added. Left out: a UI to paste | |
| 249 | the token into `parent.json` (part 2 of #2182 covers minting and handing over). | |
| 250 | ||
| 251 | Minting, listing and revoking go through one action | |
| 252 | (`src/actions/proposal_tokens.ts`) at every door, and only a writer of the | |
| 253 | repository may; anyone else is told "no such resource here, or it is not | |
| 254 | visible to you", as the API says it. The secret is shown once, on minting. | |
| 255 | The repository's settings page is one more door: a writer sees their proposal | |
| 256 | tokens one to a line (child, origin, expires, last used) with Revoke, and a | |
| 257 | form that mints one and shows its secret once; others see no section. | |
| 258 | ||
| 259 | The check cell's memory is on the same page under **Check cell**, and in the terminal on a repository's About card (`I`, for an admin): the limit the machine enforces, read from `forge.json` on the default branch. When `check.limits.memory` asks for more than the machine's ceiling it shows both numbers and where the cut comes from (`FORGE_CELL_MEMORY_MAX_MIB`, else a share of the pod's memory); otherwise one number. The ceiling is read once and kept (`src/apps/check-memory.ts`). | |
| 260 | ||
| 261 | - **MCP**: the `proposal_tokens` tool with `repo` and a `verb`: `mint` | |
| 262 | (`child`, `origin`, optionally `childRepo`), `list` (the ones you minted for | |
| 263 | the repository) or `revoke` (`id`). | |
| 264 | - **Terminal**: `ctrl+k`, **Proposal tokens**, then the repository as | |
| 265 | `owner/name`. `n` mints (the child's name, then its https address) and shows | |
| 266 | the secret once on its own screen; `x` revokes the one under the cursor. |
new above
offline
"The parent mints a proposal token for the child (above)": the minting prose stays in README.md, and FOLLOWING.md has no such section above this line. Link it, e.g. "(see the README, Proposal tokens)", so the reference resolves.