# Row 236 build notes: #436b Gitea grant path (#1742, schema 3j-3k)

Builder Megavolt, reviewer Dewey, gate owner Sage. Draft; the results sections are filled in after the
runs on Sage's gate.

## Sources

- Brief: `docs/plans/2026-10-20_agent-credentials.md`, "Brief: #436b Gitea grant path, build (schema 3j-3k)",
  blob 9259ba2a1.
- Design: `agents/megavolt/work/436b/DESIGN.md` r5 at 1be535aca (sha256 68df02cd…f4), unedited. Scope:
  sections 2 to 7, and section 9's X-G1 to X-G15 and mutants. Section 10 (GitHub half) is out of scope.
- Build carry: `agents/megavolt/work/436b/BUILD-CARRY.md` at 3330c901b (N9, N10).
- Schema label 3j-3k per sage-2237. If 264a or 206 lands first, this rebases onto a new branch name and reruns
  the whole bus suite, the schema.test counts and the T46 lists.
- Rebases: onto 86f95bb27 after row 273 (sage-2403, no conflicts), then onto 0fa7bf421 after row 191
  (sage-2452, sage-2457). The 191 rebase took three unions in commit 1, 191's `processing` first and then the
  grant options: the Broker constructor (broker.mjs:317), the runtime's Broker options (runtime.mjs:173) and
  the cli case line in `scripts/mosaic` (191's `halt|resume|processing|` plus `grants`).

## What changed

- `packages/bus/src/gitea-grant.mjs` (new): the grant body check, the admin slot (set, rotate, remove), the
  admin and seat API calls, the start-time scan (`giteaStart`, `openGiteaGrants`, `tokenUnknown`).
- `packages/bus/src/broker.mjs`: the gitea executor (steps 0 to 8), settle, restart reconcile, revoke and fire,
  sweep, status, and the `grants.*` verbs.
- `packages/bus/src/credentials.mjs`: `held` pairs at start; the register and claim paths the executor uses.
- `packages/bus/src/migrations/3j-3k.sql`, `schema.sql`, `store.mjs`: `gitea_users` and `gitea_grants`, new
  tables only.
- `packages/bus/src/runtime.mjs`, `server.mjs`, `human-cli.mjs`: wiring of the start scan and the verbs.
- `packages/cli/src/grants.mjs` (new), `cli.mjs`, `scripts/mosaic`: `mosaic grants`.
- Tests: `gitea-grant.test.mjs`, `gitea-migration.test.mjs`, `gitea-grant-docker.test.mjs` (X-G3),
  `fake-gitea-api.mjs`, `fixtures/schema-3j.sql` (02da6a2ae's schema.sql), `cli/tests/grants.test.mjs`, and the
  pin updates in the migration tests, `schema.test.mjs`, `channel-proof.test.mjs` and `stack-release.test.mjs`
  (T46).
- READMEs of bus and cli.

## Choices and assumptions

Each is a reading of the design where it left room. Dewey may rule otherwise.

1. Admin rotation is due once today is past `rotateBy` (the date itself is still good).
2. A seat-token rotation moves the record at step 8, after the old token's delete (step 7).
3. A step 7 failure leaves the grant applied, with the old id in `serviceLeft` and the notice "The previous
   token X is still live".
4. A failure after the commit step's rename returns `settle-pending`; the next start settles it.
5. tester-cli keeps its 5 s timeout; the grant verbs answer at once and the executor runs after.
6. A revoke of a token-unknown agent takes both ids from that decision's last commit step.
7. A user adopted at restart is upserted in the same transaction as its `grant.failed interrupted`.
8. `#giteaUnlink` (first-grant commit undo) uses a temporary reference dated `9999-12-31`, so it is never due
   while it lives.
9. X-G12's org-team case: the fake models team membership as collaborator reach on the repository, which is
   what `/user/repos` shows (F11, F12).
10. X-G15's look-alikes are stored under `action.refused` and under a non-grant kind, since the 3j trigger
    refuses the human's NULL pair on `action.allowed`. The trigger cases of X-G13 (session, NULL pair,
    `grant.host.enrolled`) are in `grant-migration.test.mjs`.
11. Step 6 faults: a pre-rename failure is injected by making `gitea.tmp` a directory; a step 8 store fault by
    a TEMP trigger on `gitea_grants`.
12. The credentials-verb revoke close is tracked, so `giteaIdle()` waits for it.
13. `openGiteaGrants` gives `agent: null` for a spend with no step yet, so `status.running` can show a null
    agent; the CLI prints it empty.
14. N9: a restart ignores a settle-pending commit with a `grant.revoked` after it and ends it `revoked` with
    no message (notify false). A 404 on a delete by id counts as done.
15. N10: `serviceLeft` is a list in every body and answer.
16. A restart claims the agent's key for each open grant it undoes. One executor runs per agent
    (grant-busy), so a killed child leaves at most one open grant per agent. If a store ever held two, the
    second's claim fails and the undo runs with no admin: its token is left and named in `serviceLeft`,
    never deleted unclaimed.
17. X-G7 changes the binding with a fixture decision whose hash differs (row 234's G9 pattern), since the
    broker keeps its own copy of the business. The admin url check takes row 199's `parseGiteaUrl`, which
    accepts the origin with or without a trailing slash.
18. r2, Dewey B1 (dewey-0781): step 8 and both settle branches (forward, back) check for a `grant.revoked`
    of the agent after the decision's raise, in the same transaction as their write. A revoke that came
    while step 7's or the settle's delete awaited took the record and both tokens, so the grant ends
    `revoked` with the human's notice, as a revoke of a running executor ends it (X-G11), and no record is
    written back. N9's restart case stays silent: a restart never settles a revoked rotation.
19. r2, Dewey B2: a sweep retry of `tokens` or `login` checks the user's id first, as the revoke close does,
    against the `gitea_users` row (it survives a fire). A 404 skips with `gitea-user-gone`, a 200 with
    another id with `gitea-user-foreign`, any other status leaves the entry. Skips go in `grant.swept` and
    the sweep answer as `skipped: [{agent, user, id, reason}]`; a skipped entry is not left, so the next
    sweep does not retry it.
20. r3, Dewey N5 (dewey-0783): the settle's 401 branch and its grant-token-unknown branch take the same
    revoke check. A revoke during the whoami ends the grant `revoked`, not `grant-lost`, and the
    token-unknown branch neither holds the agent again nor writes `grant-token-unknown`, so no start
    names a file the revoke unlinked.
21. sage-2453, ruling (a) on megavolt-0123: 191's `#processingGate` refuses every agent verb off its read list
    while processing is halted. `grants.status` is a read like `hosts.status`, and the kill-switch plan
    (`docs/plans/2026-10-20_kill-switch.md`:16) says "Reads and the human's own verbs, including the clear,
    still work", so it joins the list. This touches row 191's list (one entry). An agent's `grants.revoke`
    stays refused while halted, as `hosts.revoke` does.

## Named for DEFERRED (r2, Dewey N1-N4)

None is a small local change, so none is in r2. sage-2388: all four DEFERRED; N3 and N4 get a bus README
sentence each in r3 (a left admin token is deleted by hand at Gitea; a running executor keeps the admin
api it started with).

- N1: an admin rotate cut between the mint and the slot write leaves a token at Gitea that no event names.
  A `grant.admin rotate-begin {oldName}` before the mint would close it; that is a new event shape.
- N2: `adminTokenLeft` is `unknown` when `/api/v1/token` gives no name. Which 1.27 F-fact shows the name
  needs a check against the container, not a code change.
- N3: admin set or remove records `adminTokenLeft: null`, so a left token drops out of status. Carrying it
  forward lets `rotate --finish` delete by name under a slot of another account or url; refusing remove
  while one is left blocks the human's remove when Gitea is down. Either needs a ruling.
- N4: rotate or remove while a gitea claim is held. Refusing it blocks the human's remove during a run;
  the running executor keeps the api it began with. Needs a ruling or a line in the README.

## Q188

No test creates a grant except through fixtures or the human's yes on a scratch store. No test reaches
git.mosaicstack.dev, tasks.woltje.com or any provider. Unit tests use the fake Gitea on 127.0.0.1; X-G3 uses a
throwaway gitea/gitea:1.27.1 container from the local image (never pulled), removed after. Every token is a
fake or a scratch-container token; values are compared with `assert.ok`, never printed.

## Runs

Sage's CLEAR (sage-2554), 10-22 09:00-09:28Z, one slot script that stops at the first red. Logs are in
`scratch/megavolt-r236/logs/` (`slot-2c.txt`, `slot-gate.txt`, `slot-mutants.txt`, `slot-all.txt`).

- Section 2c files whole, in the seat worktree, TMPDIR under `/mnt/storage/scratch/tmp`:
  - bus (gitea-grant, the migration tests, schema, channel-proof, chief-of-staff, grant-host,
    project-runtime): 131 pass, 0 fail, 0 skipped;
  - cli (grants, stack-release): 224 pass;
  - route (grants, access): 28 pass;
  - docker (gitea-grant-docker): 1 pass.
- The whole gate, in a detached worktree at bd5f11ded:
  - `packages/bus/tests/*.test.mjs` 765 pass, `packages/business/tests/` 228 pass,
    `packages/cli/tests/*.test.mjs` 832 pass, each 0 fail and 0 skipped;
  - every `scripts/test-*.sh` rc=0: auth, conductor, config, discord, extension-package, foundation,
    land-work, queue (156 pass), release, task.
  - Named skips: test-queue line 34 (queue verify and render --check, because the gate worktree isn't the
    queue's canonical root), and test-task lines 87 and 93 (live provider cases, row 244: no provider call in
    the gate).
- The gate worktree was clean after the run. GATE_PASSED at 09:23:11Z.

## Mutants

(section 9's list, each with the test that kills it; filled in after the runs)

Result, at bd5f11ded after the gate (`r236-mutants.sh`): the base (gitea-grant, gitea-migration,
grant-migration, schema; cli grants) was green, then all 40 killed and none survived: M1-M37, N9a, N9b and M38.
Each mutant's restore left the worktree clean. SLOT_GREEN at 09:28:50Z.

A static pass over the 39 mutants (all apply, problems=0) found five with no test to kill them. Four tests
were added before any mutant run:

- M8, M9 (user or mint step written after its call) and M16 (grant.result written before its call): "X-G6
  and X-G8: the user and mint steps are written before their calls, and each result after its call". It
  reads the store from the fake while user-create and token-create are at Gitea, and checks every result's
  status.
- M29 (fork parent not checked): "X-G4: a fork by the seat user of another repository than the project
  refuses fork-foreign".
- M28 (memory and file revoked after the Gitea delete): "X-G11: a revoke unloads memory and removes the file
  before its Gitea delete", which holds the DELETE open and reads the file and state.
- M37 (evidence without its kind filter): "X-G15: a look-alike spend under another kind with the grant writer
  pair is not an open grant".

r2 tests, each red on 8bf442be9 by reading:

- B1: "X-G11: a revoke during a rotation step 7 ends it revoked, and step 8 writes no record back" and
  "X-G11: a revoke while a sweep settles a rotation, forward or back, ends it revoked with no record".
  On 8bf442be9 step 8 and the settle write the record and `grant.applied` (forward) or `grant.failed
  interrupted settled:back` after the revoke deleted it.
- B2: "X-G14: a sweep retries a fire only for the user it fired: a remade or gone user is skipped and
  named". On 8bf442be9 the retry fires the remade user (token list, delete, PATCH) and has no `skipped`.
- N5 (r3, sage-2388): "X-G11: a revoke during a settle whoami that finds a foreign token ends it revoked, not
  held" and "X-G11: a revoke during a settle whoami that gets a 401 ends it revoked, not lost". On 77dd43c9e
  they end `grant-token-unknown` (the agent back in tokenUnknown) and `grant-lost`.
- Choice 21 (sage-2453): "kill switch (plan :16): while halted the chief still reads grants.status, and an
  agent grants.revoke refuses". M38 drops `'grants.status'` from the read list; the chief's status then
  refuses `processing-halted` and the test fails.