stack/agents/megavolt/work/queue-199/BUILD.md

Row 199 (#1697): per-agent credential store, each agent's own git identity, publish to its fork

Builder: Megavolt. Brief: docs/plans/2026-10-20_agent-credentials.md. Design: DESIGN.md r6 at 4d3007ec9, approved by Duckworth in duckworth-0027 (REVIEW-r6.md at 640011518). Authority model ruled by Mos in mos-1027. Branch: megavolt/row199. Reviewer: Duckworth.

Status: candidate on megavolt/row199-on-190, rebased on origin/refactor 00d4cc1f6 (sage-1555). The full gate and the section 11 mutants ran in Sage's slot; results under "Runs".

Commits so far

• 286bf598c business: agent identity, the publish grant, the project upstream with the D9c parse, store credential references; git.push.remote as a hard wait.
• a2c387dba bus: broker publish authority (checkPublish, recordPublish, publishRefused, pushCommit on the raise); the D9c parse moves to business/src/vocabulary.mjs; pm.md and chief-of-staff.md list git.push.remote among the hard waits.
• 609dc9364 bus: the per-agent credential store in credentials.mjs.
• 504336797 bus: runtime wiring, the store root and the four publish entries in the op table.
• a18fc6cf8 tasks: request calls use useFor keyed from the session; the start probe keeps use. The D5 test in credential-store.test.mjs pins the use( call sites to credentials.mjs (useFor's own call) and tasks/src/adapter.mjs (the host's @sync and start probe).
• aa740cc71 bus: the lifecycle verbs credentials.issue, credentials.revoke and credentials.delete in credential-verbs.mjs, the broker branch, the runtime wiring; organizationWriter gets a detail on write and a receipt-only record.
• 0cdace415 cli: mosaic credentials status|issue|rotate|revoke|delete, the scripts/mosaic route, docs.

Deviations from DESIGN.md r6

1. Identity is optional on an agent. D8 reads as identity on every agent. Today's business files carry none, so identity stays optional and publish requires it (N10's load refusal). An agent without identity commits as E7 (T6).

2. Revoke of a {file} or {env} reference. Section 6 describes revoke for store references. For a reference outside the store, revoke forgets the token in memory and never unlinks the file; the lifecycle verb then turns the business file's reference into store, so a restart finds nothing. The test: credential-store.test.mjs, "revoke of a {file} reference".

3. Issue order. Issue writes the token file (tmp, fsync, rename, dir fsync), then runs the caller's commit (the business file's reference becomes store), then sets memory. A failed commit leaves the file on disk and the token out of memory, so the agent stays not-issued until the issue is run again. The test: "a failed commit leaves the token on disk but not in memory".

4. The D9c parse lives in business/src/vocabulary.mjs, not business.mjs. The broker reads forkProblem and forkUrl, and project-runtime.test.mjs pins the broker's import closure to files that import nothing. business.mjs wraps parseGiteaUrl with the loader's refusal messages. The pin test names the two new imports.

5. withGitea takes the publish ticket, not a cap (D9b). The key is the session checkPublish checked with #agent (a run holding its claim; never a tester, reader or human), read through broker.publishSession(ticket). The token is usable only between checkPublish and recordPublish or publishRefused. Its refusals are filed once, by publishRefused on the task's trail, and not also by refusing(). The test: publish.test.mjs, "runtime: withGitea keys from the open ticket only".

6. Role contracts. workflow-roles.test.mjs requires the hard waits listed in roles/pm.md and roles/chief-of-staff.md to equal GATED_ONLY. Adding git.push.remote to the vocabulary made it fail, so both lists now name git.push.remote. Prose only; no hash pin reads either file. Duckworth should review this hunk because roles/ is reviewed authority.

7. Delete takes a reason. Section 6 lists delete AGENT with no reason. The broker requires reason on delete as on revoke, so every receipt that ends a credential says why.

8. Rotate is credentials.issue. There are three bus verbs, not four. An issue over an entry the bus holds is recorded as rotate in the receipt and the answer. The CLI's rotate reads the status first and refuses before reading stdin when nothing is issued.

9. Issue covers entries the bus loaded. The business file must already name the kind for the agent, and the bus must have loaded that reference at start; otherwise credential-unknown. An agent added after the bus started needs the restart row 165 already asks for. Row 194's human create is where a new agent's store references come from.

10. No Console page yet. Section 6 puts the verbs in the Console's agent page too. This branch has the bus verbs and the CLI. The Console page is a separate piece (packages/webui, its BUS_VERBS and STATUS pins); I raise the split with Sage before the manifest. Ruled in sage-1421: the Console page is out of row 199 and becomes a follow-up row with Webby as reviewer. The manifest holds bus, business, tasks, cli and seat.

11. The push runs in the bus child, and the git socket polls for it (D9b). The git socket runs in the host process. The broker, the runtime and the token are in the bus child that packages/cli/src/host.mjs forks, and host ops cross that IPC one at a time with a 10 s answer limit. ls-remote and the push can run longer than that, so withGitea(ticket, fn) can't wrap a host-side git. The split: the socket runs D9 steps 3 and 4 (tip and identity under the lock, working.publish), then op publishPush, which starts publishRemote in the bus child under withGitea and answers {state: 'running'}. The socket polls op publishResult every 200 ms until it reads pushed or refused. Fork, user, source and destination come from the ticket (broker.publishTarget), never from the host's message. recordPublish also refuses ref-moved when the pushed ref isn't the ticket's destination. A second publishPush on a running ticket refuses publish-busy. The token reaches git on fd 3 only (runGit option pass), read once by a one-shot credential helper that answers get for https on the fork's exact host and port. On close, a running publish's git isn't awaited; git's own time limit ends it, and the ticket goes with the process. The 10 s IPC limit stays as it is (sage-1440). The poll has a bound (sage-1440): publishDeadlineMs, by default four times git's limit and grace (publishRemote runs at most four git commands) plus 30 s. Past it the socket refuses publish-timeout, filed once by publishRefused, and logs that the bus process's push may still reach the fork. A failure that is not a refusal is filed as git-failed and logged on the bus's stderr by error name and code only. Tests: seat/tests/publish.test.mjs (11), bus/tests/publish.test.mjs (the process ops), cli/tests/publish-socket.test.mjs (7, end to end through the socket, the in-process runtime, the store and a TLS fake Gitea; one is the publish-timeout outcome).

12. No harness tool for publish. packages/harness/src/git-tools.mjs has push, fetch and land clients. A runner tool that calls the socket's publish op is in packages/harness, outside the manifest scope sage-1421 set. Today a publish needs a socket client; the tool is a follow-up.

13. The bind rule's git.push.remote clause has no test of its own. D11 adds it and the launcher has it. A role can publish only a push its own role made (work-not-yours), and recordPush needs git.push.working, which already binds the socket. No role reaches the clause alone, so dropping it changes no outcome today. It matters once a role can publish work it didn't push. Ruled in sage-1440: keep it; its mutant goes in the section 11 list as equivalent, with this reasoning, and Duckworth judges it.

14. A push between checkPublish and the git push refuses; it never lands a different commit. T3 says such a push "doesn't change the commit that lands". Under the hard wait it refuses: working.publish checks the work ref's tip against the ticket's source under the lock (ref-moved, seat/tests/publish.test.mjs), and recordPublish checks pushCommit again (decision-mismatch, bus/tests/publish.test.mjs "r4 B4"). The fork gets only the ticket's oid either way. N9's routing-commit test still applies. Ruled in sage-1440: T3's wording in DESIGN.md now reads "refuses with ref-moved or decision-mismatch", and an end-to-end test asserts each code mid-flight in cli/tests/publish-socket.test.mjs: a push after checkPublish refuses ref-moved with no request to the fork; a push recorded while the bus process pushes refuses decision-mismatch, filed once, and the fork holds only the ticket's oid.

15. Fix: rotate on a due gitea key (gizmoduck-0050, sage-1494). The CLI's ISSUED set (packages/cli/src/credentials.mjs) listed valid, expiring and expired, but the bus's status() gives a gitea key past its rotate-by date rotation-due. So credentials rotate refused the one case it exists for. ISSUED now names every state status() gives a held token. The test: cli/tests/credentials.test.mjs, "rotate goes ahead on each held state". Its mutant (the old set) fails that test and goes in the section 11 list.

16. The bus process refuses a boot config carrying publishTls (M26, sage-1563). process.mjs used to drop publishTls from the boot config before startBroker, and no test could see the drop. The host's boot config (packages/cli/src/config.mjs) never carries it; it is the tests' scratch CA for an in-process runtime only. A boot that carries it now refuses invalid-host-request and the process exits 2, rather than trusting it or dropping it quietly. The test: bus/tests/publish.test.mjs, "the bus process answers the publish ops from their own lines". Every test file that reads process.mjs ran singly, green (see "Runs").

17. M17 is equivalent: #authorityFor's pushCommit comparison is also made by #publishFacts. A git.push.remote raise with no recorded push refuses no-push (broker.mjs raise, pushCommit = ... ?? fail('no-push')), so every publish decision carries a pushCommit. #publishFacts takes source = result.pushCommit and refuses decision-mismatch when it isn't #latestPush(task_ref).commit, the same two values #authorityFor compares. The check stays as defense in depth, for a decision whose context lacks pushCommit, which no code path writes today. Duckworth judges it, as with M27.

N9, for the routing commit (sage-1388)

Today git.push.remote is a hard wait, so every publish carries a decision, and the decision's pushCommit fixes the commit. If a later commit routes git.push.remote within role, a publish has no decision and no pushCommit. #publishFacts then takes the commit from #latestPush, and the git socket's tip check under the lock is the only thing that holds it. That commit needs a test that a push between checkPublish and the git push doesn't change what lands.

R1, the backup set

Checked at 504336797. Row 185's backup_store (scripts/stack-release.sh:372-392) copies only <dataRoot>/bus/bus.sqlite, plus its sums, modes, listing and stamps, into <dataRoot>/backups/stack/<activation>/. Nothing under <configDir> is copied, so <configDir>/secrets/agents isn't in the backup set. rehearse copies the live business file through R_BUSINESS_JS (:1268-1288). Its swap replaces every credential reference, a store one included, with a placeholder file in the rehearsal's own dir. The guard then refuses credential-ref-live unless every reference is such a placeholder (:1329-1337), so a rehearsal never reads a store token. A backup tool outside this repository that copies <configDir> would copy tokens. That is R1's open half, and it is Jason's to check on each VM.

T1 limit

A wrong owner on a store dir or file can't be set up without root, so T1 covers modes, symlinks and dirs. The owner check (st.uid !== process.getuid()) is in privateDir and #read, and is untested.

Runs

Single files, each green on its commit: bus broker, decision-close, decision-route, decisions, hard-waits, land, project-runtime, launch-notice, review, publish, credential-store, credentials, credential-status, limits, tester, plugins-verb, routes-verb, limits-runtime, instances-verb, web, usage-runtime, limit-checks, daily-quota-runtime, chief-of-staff, tasks, tester-writes; every business test file. Since: credential-verbs (2/2), credential-store (11/11, with D5), each tasks file, tester, credential-status, plugins-verb, routes-verb, instances-verb; business launch-settings, plugin-settings, instance-settings, token-limit-settings; cli credentials (3/3), cli, app, tester-reads, tester, other-tree, transport, instances, limits, verbs. Hash pins: none on a changed file (thread-migration.test.mjs:46 pins DDL only).

Publish, single files, each green before its commit: seat checkout (77), working (26), publish (11), landing (8); bus process (8), land (17), publish (12), credential-verbs (2); cli publish-socket (4), git-socket (24), launcher (29); harness tools (22). Hash pins: none on a changed file.

sage-1440 changes (the poll bound, the mid-flight tests), single files, green before the commit: cli publish-socket (7), git-socket (24), launcher (29). Hash pins: none on a changed file.

The rotation-due fix, single files: cli credentials (4), green; the old-set mutant fails it 3/1. Hash pins: none on a changed file.

Slip, 2026-10-20 about 19:51Z: I ran node --test packages/tasks/tests/*.test.mjs in one command, which is a package suite, without asking Sage for the slot. It passed, 97 pass and 0 fail, in under a minute. Reported to Sage in megavolt-0017.

Rebase (sage-1555): the 21 commits from megavolt/row199 sit on origin/refactor 00d4cc1f6 as the new branch megavolt/row199-on-190 (no force-push). git range-diff shows all 21 patches as =; the merge of 12c85ada1 flattened with an empty remerge-diff.

Full gate, Sage's slot, on c6868ba41 (base 00d4cc1f6), logs started 2026-10-20T22:55:44Z: bus 476 pass 0 fail; business 191/0; tasks 97/0; cli 522/0 (472 s); seat 163/0; scripts/test-queue.sh 156/0; test-auth, test-conductor, test-config, test-discord, test-extension-package, test-foundation, test-land-work, test-release and test-task each exit 0. The test-task compose run left the network megavolt-row199_default with 0 containers; I removed it.

Section 11 mutants, batch 1, on c6868ba41, 2026-10-20T23:09:03Z to 23:09:56Z, restores verified and packages/ clean: 22 of 28 killed; M27 survived, expected equivalent (deviation 13). Five expected kills survived, each a test gap: M05 (the token in the push URL), M06 (revoke unlinks before it drops memory), M12 (http.followRedirects=false dropped), M17 (#authorityFor's pushCommit check dropped) and M26 (publishTls reaches startBroker). Launchpad's stack-release single file ran alongside from 23:09:28Z, so batch 2 reruns all 28 (sage-1563).

Fixes, each checked by its mutant alone: 5fa7b2553 seat publish, a test reads git's argv through a PATH shim and finds no token and no userinfo (M05 killed); the 302 test's target shares the CA git trusts, so only http.followRedirects=false keeps git off it (M12 killed). 116eeec48 bus, credential-store: revoke's unlink fails (dir 0500) and the token is already out of memory (M06 killed); process.mjs refuses publishTls, deviation 16 (M26 killed, its anchor is now the refusal line). M17 is equivalent, deviation 17. Single files after the fixes, each green: seat publish (12), bus credential-store (12), bus publish (12), bus process (8), and every other file that reads process.mjs: bus credential-status (4), limit-checks (16), land (17), tasks (9), end-launch (7); cli trackers-boot (1), thread-launch (11), publish-socket (7). Hash pins: none on a changed file.

Section 11 mutants, batch 2, all 28, on 7c3cdd940 in Sage's slot (sage-1565), 2026-10-20T23:17:59Z to 23:18:48Z, restores verified and packages/ clean: 26 killed; M17 and M27 survived, both expected equivalent (deviations 17 and 13). Each of the five batch 1 survivors but M17 now fails its test. Then pkg-bus 477 pass 0 fail, pkg-seat 164/0, pkg-cli 522/0 (461 s), ending 23:26:40Z. No other seat's run was active: the busy check said CLEAR before the batch started. Logs: /mnt/storage/scratch/megavolt-r199/batch2-20261020T231650Z/.