plans: row 199 design r4, answers duckworth-0017 B3 (TLS fake through a test seam), B4 (decision binds the commit, push by oid), N6 to N8 (#1697)

agents/megavolt/work/queue-199/DESIGN.md

@@ -10,6 +10,9 @@ and T3, N1 in section 6 and Q-M3, N2 in section 6, N3 in D9 step 3, N4 in D9a an
 r3 records Mos's rulings (mos-1027) in section 9. The Q-M2 hard wait changes D9 step 1, D9b and T3. Q-M1
 drops O2 (D10, A3, R2).
 
+r4 answers duckworth-0017 (REVIEW-r3.md at 4065ed59f): B3 in T3 and D9 step 5, B4 in D9 steps 1, 3 and 5, N6
+and N7 in D9a, N8 in D9 step 1.
+
 ## 0. Terms
 
 - **Stack instance**: one Mosaic Stack deployment (row 190). It has one OS user, one config dir
@@ -126,10 +129,19 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
 
 1. Identity from the cap (E5), then the broker's `#checkAuthority(s, "git.push.remote", {decision, target:
    task_ref})`, as `checkLand` does for a merge (`broker.mjs:907-913`). `git.push.remote` is a new action in
-   ACTIONS and is not in ROUTED (REQ-WAIT-3, `vocabulary.mjs:52-55`, `broker.mjs:42-69`), so it is a hard wait
-   and classifies `gated` for every role. Every publish therefore needs a decision the human resolved for
-   this task ref, and the decision names the commit. A decision is spent once (`decision-consumed`), and a
-   commit other than the task's latest recorded push refuses `ref-moved` (`#latestPush`, `broker.mjs:936`).
+   ACTIONS and is not in ROUTED (REQ-WAIT-3, `packages/business/src/vocabulary.mjs:52-58`,
+   `broker.mjs:42-69`), so it is a hard wait and classifies `gated` for every role. Every publish therefore
+   needs a decision the human resolved for this task ref. A decision is spent once (`decision-consumed`).
+
+   **The decision binds one commit.** `#authorityFor` binds action, role, thread and target only
+   (`broker.mjs:769-798`), so the commit needs its own carrier. The raise records it the same way it records
+   `holderRun` for `role.revoke` (`broker.mjs:1733`). When the action is `git.push.remote`, the
+   `decision.raise` event body gets `pushCommit`. That is the commit of `#latestPush(business, target)` at
+   raise time, read by the broker and never taken from the agent. A raise with no recorded push for the task
+   refuses `no-push`. The decision's question shown to the human ends with that commit. `#authorityFor` then
+   refuses `decision-mismatch` when `context.pushCommit` differs from the commit of `#latestPush` now, which
+   is the same check `holderRun` gets at `broker.mjs:796`. So the sequence approve at A, push B, publish B
+   refuses.
    No role definition grants the action yet. When Jason's PRD version routes it (Sage, Vikunja #420), a
    reviewed commit adds it to both ROUTED lists and to coder's `withinRole`. From then on a coder publishes
    without a decision, and `decision` is optional for a within-role class only.
@@ -139,19 +151,24 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
    counts as 443 on both sides. `remote` is a new key
    beside `root` and `repo` (`business.mjs:186`), and `identity` and `publish` are new keys on a role entry
    (`business.mjs:89`). All three are optional, so today's business files load unchanged.
-3. The source is the task's work ref in the working repo, `work/vikunja-<project>-<task>`
-   (`working.mjs:110-114`). That ref is per task, not per agent. Two checks make it the caller's: the
-   broker's last recorded push for that ref (`recordPush`) was made by the caller's role (`work-not-yours`),
-   and step 4. The destination is always `refs/heads/<gitea.user>/<branch>`, built by the host.
+3. The source is one commit, `C = context.pushCommit`. It is checked three ways, so all three are equal:
+   the decision's commit, the commit of `#latestPush`, and the work ref's tip in the working repo,
+   `work/vikunja-<project>-<task>` (`working.mjs:110-114`). The tip is read under the repository's lock, and
+   if they differ the push refuses `ref-moved`. The work ref is per task, not per agent. Two checks make it the
+   caller's: `#latestPush` was recorded by the caller's role (`work-not-yours`), and step 4. The destination is always `refs/heads/<gitea.user>/<branch>`, built by the host.
    `validBranch(branch)` holds (`invalid-request`). The agent never names the destination ref.
 4. Every commit in `main..<work ref>` has author and committer email equal to `identity.email`
    (`identity-mismatch`).
-5. The push runs through `credentials.useFor(session, "gitea", ...)`: `git push <remote> <src>:<dst>` with no
-   `+` and no `--force` (`non-fast-forward` from git stays a refusal). Git runs with E8's SAFE flags
+5. The push runs through `credentials.useFor(session, "gitea", ...)`: `git push <remote> <C>:<dst>`, by oid,
+   with no `+` and no `--force`. It never pushes by ref name, so a push to the working repo after
+   `checkPublish` can't change what goes out (`non-fast-forward` from git stays a refusal). Git runs with E8's SAFE flags
    (`working.mjs:92-98`), which set `protocol.allow=never`. `publish` adds exactly two flags,
    `protocol.https.allow=always` and `http.followRedirects=false`, plus `GIT_TERMINAL_PROMPT=0` and no global
    or system config. The token reaches git through a one-shot credential helper that reads it from an
-   inherited pipe, never through argv, env, the URL or a file. The helper answers `get` only when `protocol`
+   inherited pipe, never through argv, env, the URL or a file. Seat `gitEnv` (`checkout.mjs:79-89`) takes only
+   PATH from the host and sets the rest itself, so no proxy or `GIT_SSL_*` variable reaches git. `publish` takes a `tls` parameter that
+   defaults to `[]`, the same way `push` takes `fsck = FSCK` (`working.mjs:100`). Tests pass
+   `["-c", "http.sslCAInfo=<scratch CA>"]`. The host never sets it, and nothing in config or env reaches it. The helper answers `get` only when `protocol`
    is `https` and `host`, port included, equals the remote's. It writes nothing for any other `get` and for
    `store` and `erase`. `assertClean` checks git's output, so a remote that echoes the token gets
    `credential-leak`.
@@ -160,6 +177,10 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
 D9a. **The remote must share root's history.** A push sends every object the remote lacks. The working
 repo's `main` is the project root's history (`working.mjs`, seed), so a remote that doesn't share it would
 receive all of root, landing squashes included. A project's `remote` must be root's upstream or a fork of it.
+`publish` runs `seed` first (`working.mjs:164-176`), under the repository's lock as `push` does, so `main`
+catches up with root before the check below. That means a fork also receives any landed root commits that
+upstream doesn't have yet, because they sit under the agent's work. That is expected: the agent's branch is
+built on them.
 Before the push, the host runs `git ls-remote` (same flags and helper) for the remote's default branch. It
 refuses `remote-unrelated` when the remote is empty or when that tip isn't a commit the working repo already
 has and an ancestor of `main`. Only `ls-remote` crosses the network for this, so nothing is fetched from the
@@ -294,10 +315,15 @@ All tests use scratch roots, fake tokens and a fake Gitea: `git http-backend` be
   status is `not-issued`. A missing `{file}` still refuses start.
 - T2. `useFor` keys from the cap only. A request naming another agent is refused and leaves one
   `action.refused`.
-- T3. `publish`: happy path lands `refs/heads/<user>/<branch>` on the fake remote, a fork that shares root's
-  history. Refusals for each step in D9, one test each, including `work-not-yours`. Until routing, a publish with
+- T3. The fake Gitea serves https on 127.0.0.1 with a cert from a scratch CA made by the test. It reaches git
+  only through the `tls` parameter (D9 step 5). Each refusal test that should reach the network asserts that
+  the first port received the request, so no test passes because git refused http first. `publish`: the
+  happy path lands `refs/heads/<user>/<branch>` on the fake remote, a fork that shares root's history, at
+  exactly the decision's commit. Refusals for each step in D9, one test each, including `work-not-yours`. Until routing, a publish with
   no decision refuses, one with a decision for another task or commit refuses, and a second publish on a
-  spent decision refuses `decision-consumed`. A test pins that `git.push.remote` is in neither ROUTED list
+  spent decision refuses `decision-consumed`. Approve while the latest push is A, push B, publish: refuses
+  `decision-mismatch`, and the remote receives nothing. A push to the working repo between `checkPublish` and
+  the git push doesn't change the commit that lands. A raise with no recorded push refuses `no-push`. A test pins that `git.push.remote` is in neither ROUTED list
   and that no `roles/*.json` grants it. A force-push attempt is
   refused by git's non-fast-forward. A fake remote that answers 302 to a second 127.0.0.1 port: the push
   fails, and the second port receives no request with an Authorization header. A remote on the right host
@@ -315,7 +341,8 @@ the refspec, skip the identity check, put the token in the URL, revoke file befo
 check, allow a `{file}` reference into another agent's dir, make ENOENT on a `store` path fatal again, make
 ENOENT on a `{file}` path silent, a helper that answers any host, drop `http.followRedirects=false`, drop the
 `work-not-yours` check, drop the `remote-unrelated` check, add `git.push.remote` to ROUTED, skip the spent
-check on the decision.
+check on the decision, drop the `pushCommit` comparison in `#authorityFor`, push by ref name in place of the
+oid, skip the tip check under the lock, and pass a CA flag in production.
 
 ## 12. Risks