flowviant 0.103.0 → 0.104.0

package/bin/lib/workAgentPlans.mjs

@@ -5,26 +5,28 @@ import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mj
 import { git, isSafePathSegment } from './git.mjs';
 import { parseProposal } from './agentPlan.mjs';
 import { c, note } from './ui.mjs';
-import { runTurn } from './claude.mjs';
+import { runTurn } from './runTurn.mjs';
 import { SYSTEM_PLAN, AGENT_PLAN_KICKOFF } from './prompts.mjs';
-import { scrub as envScrub } from './env.mjs';
-import { pickRuntimeFor, removeProbeTranscript, RUNTIMES } from './runtimes.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { RUNTIMES } from './runtimes.mjs';
+import { pickRuntimeFor } from './runtimeDetection.mjs';
+import { removeProbeTranscript } from './runtimeCapabilities.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { REPO_PLACE } from './workPlaces.mjs';
 
 export function createWorkAgentPlans({
   postBestEffort,
   baseDir,
   baseRef,
-  REPO_PLACE,
   inPlace,
   repoRoot,
   admit,
-  state,
+  placeLocks,
+  workChildren,
 }) {
-  const AGENT_PLAN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-plan-done');
-  const AGENT_PLAN_ACTIVITY_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-plan-activity');
-  const AGENT_PLAN_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-plan-claim');
-
-  const { placeLocks, workChildren } = state;
+  const AGENT_PLAN_DONE_URL = fleetEndpoint('agent-plan-done', FLEET_URL);
+  const AGENT_PLAN_ACTIVITY_URL = fleetEndpoint('agent-plan-activity', FLEET_URL);
+  const AGENT_PLAN_CLAIM_URL = fleetEndpoint('agent-plan-claim', FLEET_URL);
 
   // ── AGENT PLAN JOBS: the Deploy press ──────────────────────────────────────
   //
@@ -33,7 +35,7 @@ export function createWorkAgentPlans({
   // proposes on the board, and ACCEPTING is what spawns anything. Nothing here
   // creates a worktree, a branch or a card.
   //
-  // READ-ONLY IN THE CHECKOUT. `readOnly: true` selects `consultPermFor` (the
+  // READ-ONLY IN THE CHECKOUT. `profile: 'consult'` selects `consultPermFor` (the
   // fenced Read/Glob rules plus a few path-validated `git`/`ls`/`cat` reads —
   // no Write, no Edit, no mkdir, no rm) and NO MCP is passed at all, so this
   // turn has no control plane to reach even if the repository it reads tries
@@ -323,7 +325,7 @@ export function createWorkAgentPlans({
           system: SYSTEM_PLAN,
           // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
           // passed empty, so there is no control plane on this turn at all.
-          readOnly: true,
+          profile: 'consult',
           cwd: repoRoot,
           runtime: rt,
           streamJson: true,

package/bin/lib/workAgentPrecheck.mjs

@@ -0,0 +1,393 @@
+/**
+ * THE AI PRE-REVIEW — a fresh, read-only reader of the agent's branch, run on
+ * the review-entry beat after the check, whose reading is posted as a label.
+ *
+ * Split out of workAgentReview.mjs (SOLID F039): this half changes for
+ * MODEL-REPORTING reasons (which CLI reads, what it is shown, how its answer
+ * is parsed, scrubbed and re-sent), the project check for SECURITY ones. The
+ * review entry beat sequences the two and owns neither.
+ */
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { git } from './git.mjs';
+import { parsePrecheck } from './agentPlan.mjs';
+import { readStash } from './agentCards.mjs';
+import { c, note } from './ui.mjs';
+import { runTurn } from './runTurn.mjs';
+import { SYSTEM_PRECHECK, AGENT_PRECHECK_KICKOFF } from './prompts.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { pickRuntimeFor } from './runtimeDetection.mjs';
+import { removeProbeTranscript } from './runtimeCapabilities.mjs';
+import { taskIdsFromMessage } from './worktreeDiff.mjs';
+import { limitLine } from './cliLimit.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+
+export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workChildren }) {
+  const AGENT_PRECHECK_URL = fleetEndpoint('agent-precheck', FLEET_URL);
+
+  // ── THE AI PRE-REVIEW ──────────────────────────────────────────────────────
+  //
+  // A FRESH Claude reads the branch before the human does. The owner asked for
+  // it in these words: "before having the user manually check, can we have the
+  // daemon … spawn an agent to review the work so basically we get an ai to look
+  // at the review before a human looks at it for a double check."
+  //
+  // IT IS NOT THE AGENT CHECKING ITSELF. `runTurn` is called with no `resume`,
+  // so there is no conversation to inherit: an agent that spent four turns
+  // arguing itself into a design defends that design, and asked whether its work
+  // meets the card it answers from the very context that produced the work. The
+  // reviewer stands IN the agent's worktree because it needs the code and the
+  // diff, under the `consult` profile (`consultPermFor` — the fenced Read/Glob rules plus
+  // a few path-validated git reads) with NO MCP passed at all, so there is no
+  // control plane on this turn even if the repository it reads tries to steer
+  // it.
+  //
+  // IT LABELS AND NEVER BLOCKS — the check's own law (workAgentCheck.mjs). Approve,
+  // the per-card verdicts and the ship quiz do not know this exists. Every exit
+  // below POSTS NOTHING, and the server renders an absent precheck as nothing:
+  // a failed, timed-out, skipped or unparseable read leaves the human's review
+  // exactly as it was before this feature existed. Ignorance never withholds.
+  //
+  // NO VERSION FLOOR. This is a daemon→server report on a NEW endpoint, so an
+  // older daemon simply never posts, and an older SERVER 404s — which `postPre`
+  // treats as delivered-and-done for the agent-trace reason stated there.
+  //
+  // IT RIDES THE BEAT THE CHECK ALREADY OWNS (`runReviewEntry`), AFTER it: the
+  // check is a local command and this is a model call, so the cheap answer lands
+  // on the row first and a wedged reviewer cannot delay it.
+  /**
+   * FIVE MINUTES, and `runTurn` has no timer of its own.
+   *
+   * Half the planner's cap, because this turn is strictly smaller — it reads one
+   * branch's diff and answers, where a planner reads a repository to decide
+   * whether a batch of work collides. And it is HELD INSIDE THE PLACE WRITER
+   * LOCK by the beat it rides, so every minute here is a minute the agent's next
+   * turn (or its merge) is waiting: a generous cap on a label would be spending
+   * the work's time on a note about the work.
+   */
+  const PRECHECK_TIMEOUT_MS = 5 * 60_000;
+  /** Commit subjects handed to the reviewer. A bound on the prompt, not on the
+   *  branch — the reviewer reads the diff itself, and the log is context. */
+  const PRECHECK_LOG_LINES = 80;
+
+  /**
+   * ONE PRE-REVIEW, POSTED.
+   *
+   * Resolves TRUE for a permanent refusal as well as a success, and that is
+   * deliberate — the `postAgentTrace` rule, for the same reason: a server with
+   * no such route 404s this body and will 404 every retry of it, so re-sending
+   * would be a wedge wearing a retry's clothes. A NETWORK error resolves false
+   * and is retried ONCE, because unlike a trace batch this body cost a whole
+   * model call and losing it to a blip means the operator paid for a label
+   * nobody ever sees.
+   *
+   * THE RETRY IS NOT A GUARANTEE THAT THE FIRST ATTEMPT FAILED, and since the
+   * body started carrying `usage` (0.90.0) that matters. The `catch` below
+   * takes the 30-second `AbortSignal` with everything else, so a server that
+   * was merely SLOW — and committed — receives this identical body twice. The
+   * store was always idempotent; the token counts riding it were not, and a
+   * timed-out-but-committed post added them twice. The SERVER closes that: its
+   * write refuses a body whose text already sits on the row, so a re-send
+   * stores the same reading and charges nothing for it. Nothing here needs to
+   * change, and nothing here may start assuming a thrown fetch means the
+   * server never saw this.
+   */
+  const postPre = async (body) => {
+    try {
+      const res = await fetch(AGENT_PRECHECK_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify(body),
+      });
+      return (
+        res.ok ||
+        (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
+      );
+    } catch {
+      return false; // a blip — worth one more attempt at a model call's answer
+    }
+  };
+
+  /**
+   * THE BRANCH'S OWN COMMITS, subject + trailers, and the card ids they name.
+   *
+   * MEASURED, never asserted — the same reason `commitsBetween` exists. The
+   * trailer ids are what let the prompt say "N earlier cards' specs are not on
+   * this box" honestly: the difference between the cards this branch claims and
+   * the specs this disk holds is a fact, and a box that adopted the agent
+   * mid-run is exactly the case where it is non-zero.
+   *
+   * IT CANNOT THROW. `baseRef()` is free text an owner typed and may name no
+   * ref at all; an unreadable range costs the reviewer its context, never the
+   * review-entry beat it is standing in.
+   */
+  const branchLog = (wt) => {
+    let out;
+    try {
+      out = git(['log', '--format=%s%n%b%n--', `${baseRef()}..HEAD`, '--not', baseRef()], wt);
+    } catch {
+      return { text: '', taskIds: [] };
+    }
+    if (typeof out !== 'string') return { text: '', taskIds: [] };
+    // LINEAR, never backtracking (audit 2026-09-24) — this was
+    // `out.matchAll(/^\s*Flowviant-Task:\s*(\S+)\s*$/gm)`, whose `\s*$` is
+    // quadratic against a long trailing run of whitespace on one line
+    // (measured ~1s at 40KB), and a branch's own commit log is exactly the
+    // kind of text an agent's commits can grow past that. `taskIdsFromMessage`
+    // is the same line-split, length-capped reader every other trailer scan
+    // in this codebase uses.
+    const taskIds = taskIdsFromMessage(out);
+    const text = out
+      .split('\n')
+      .filter((l) => l.trim())
+      .slice(0, PRECHECK_LOG_LINES)
+      .join('\n');
+    return { text, taskIds: [...taskIds] };
+  };
+
+  const runPrecheck = async (agentId, wt, agentName) => {
+    /**
+     * WHICH CLI READS. `pickRuntimeFor('consult')` — the same picker the scratch
+     * planner uses, and for the same reason: this prompt was written against
+     * Claude, and a machine with no read-only-capable runtime simply does not
+     * produce a precheck. Nothing is posted and nothing is said on the row.
+     */
+    const rt = pickRuntimeFor('consult');
+    if (!rt) return;
+    /**
+     * THE PRESSURE GUARD, at the spawn, exactly as every other unattended lane
+     * asks it. `churn` and never `interactive`: nobody is watching this, and a
+     * label is the first thing that should not be started on a box that is
+     * struggling. Deferring here does NOT queue anything — there is no job and
+     * no re-offer — so a precheck skipped under pressure is simply a precheck
+     * that did not happen, which is what absence already means.
+     */
+    const hold = admit('churn');
+    if (hold) {
+      note(`${c.cyan('pre-review')} ${c.dim(`— skipped: ${hold.reason}`)}`);
+      return;
+    }
+    const releaseSlot = admit.reserve();
+
+    // THE HEAD THE READING BELONGS TO, taken BEFORE the turn — the
+    // `checkFingerprint` shape, so a commit landing after this voids it rather
+    // than letting an old reading label a branch it never saw. Optional: an
+    // unreadable head costs the staleness comparison, not the precheck.
+    let headSha = null;
+    try {
+      headSha = (git(['rev-parse', 'HEAD'], wt) || '').trim() || null;
+    } catch {
+      headSha = null;
+    }
+
+    const stash = readStash(sessionMetaPath(wt, 'flowviant-agent-cards', agentId));
+    const log = branchLog(wt);
+    /** Cards the BRANCH names that this box has no spec for. Measured, not
+     *  guessed — see agentCards.mjs on why a stash is per-box. */
+    const held = new Set(stash.map((s) => s.taskId));
+    const missingSpecs = log.taskIds.filter((id) => !held.has(id)).length;
+
+    let out = '';
+    let child = null;
+    let timer = null;
+    /** The cap fired: the CLI was still running when this machine stopped it. */
+    let wedged = false;
+    /**
+     * WHAT THE READING SPENT — the agent-turn lane's own relay, on the one
+     * other lane that charges an AGENT (2026-09-19).
+     *
+     * It rides the agent and never a card link: a pre-review belongs to no card
+     * (the same reason `workChildren` gets a null task id below), so the four
+     * counters it adds to are the container's alone. That is also why an
+     * agent's links can never sum to its total, and the schema says so.
+     *
+     * A WEDGED OR UNPARSEABLE READING POSTS NOTHING AT ALL, so it charges
+     * nothing either — which under-reports a turn that really did spend. That
+     * is the honest direction: there is no row to put it on, and inventing a
+     * settle to carry a number would be a post whose only content is a bill.
+     */
+    let usage = null;
+    /**
+     * THE CONVERSATION THIS READING SPEAKS UNDER — held for exactly one reason:
+     * to DELETE the transcript it leaves behind (review, 2026-09-17).
+     *
+     * This is the first thing in the daemon to run a second `claude -p` inside
+     * an AGENT's worktree, and the agent's own resume is `--continue`, which is
+     * CWD-KEYED — the invariant `runAgentTurn` states in words ("ONE AGENT IS
+     * ONE DIRECTORY, so the CLI's own cwd-keyed resume is exactly right here").
+     * Leaving this turn's `~/.claude/projects/<munged-cwd>/<id>.jsonl` in place
+     * makes the read-only stranger the newest conversation in that directory,
+     * so the agent's NEXT turn — a send-back's re-queued card, a merge-resolve,
+     * a human's typed answer — resumes "you are a SECOND reviewer… YOU ARE
+     * READ-ONLY" instead of its own four-turn context, under build permissions.
+     * That is the 0.69.0 Workbench cross-resume and codex's `resume --last`,
+     * arriving a third time by a third route.
+     *
+     * `removeProbeTranscript` is exported for precisely this and already serves
+     * the skills probe and the dev-command resolver.
+     */
+    let preSession = null;
+    try {
+      /**
+       * THE CAP RESOLVES THE WAIT ITSELF rather than waiting for `close` after
+       * the kill — the shape the project check and the planner both keep. A
+       * SIGKILLed process whose stdio a grandchild still holds can be slow to
+       * emit `close`, or never emit it, and this promise is inside the place's
+       * writer lock.
+       */
+      let stopWaiting = () => {};
+      const capped = new Promise((r) => {
+        stopWaiting = r;
+      });
+      const turn = runTurn({
+        prompt: AGENT_PRECHECK_KICKOFF({
+          agentName,
+          cards: stash.map((s) => s.prompt).join('\n---\n'),
+          missingSpecs,
+          commits: log.text,
+          diffCommand: `git diff ${baseRef()}...HEAD`,
+        }),
+        system: SYSTEM_PRECHECK,
+        // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
+        // passed empty, so there is no control plane on this turn at all.
+        profile: 'consult',
+        cwd: wt,
+        runtime: rt,
+        // NO `resume`, AND THAT IS THE FEATURE. A resumed turn would be the
+        // agent grading its own homework out of its own context; this is a
+        // stranger reading a diff.
+        streamJson: true,
+        answerFromResult: true,
+        label: c.cyan('[pre-review]'),
+        // The id the CLI reports at `system.init` — harvested off the stream
+        // this turn already parses, no probe and no extra spawn. Held only so
+        // the `finally` below can delete this turn's transcript; see
+        // `preSession`.
+        onInit: (i) => {
+          if (typeof i.sessionId === 'string' && i.sessionId.trim())
+            preSession = i.sessionId.trim();
+        },
+        // The CLI's own count for this reading. Set, never accumulated: one
+        // turn is one `result` event, and the adding-up is the server's.
+        // Tagged with the CLI, so a Claude pre-review of a Codex agent is
+        // charged as Claude's and not folded into the agent's own figure.
+        onUsage: (u) => {
+          usage = { ...u, runtime: rt };
+        },
+        onSpawn: (ch) => {
+          child = ch;
+          // No task id: a pre-review belongs to no card, and the machine
+          // snapshot's per-task rows must not invent one. It still COUNTS
+          // against the machine's ceiling — see liveTurnCount.
+          workChildren.set(ch, null);
+          releaseSlot();
+          // ARMED AT THE SPAWN, not at entry: time spent getting here is not a
+          // wedged CLI. The CHILD and never its group — a read-only turn starts
+          // no server, so there is nothing behind it worth signalling and
+          // everything to lose by signalling somebody else's.
+          timer = setTimeout(() => {
+            wedged = true;
+            try {
+              ch.kill('SIGKILL');
+            } catch {
+              /* already gone */
+            }
+            stopWaiting('');
+          }, PRECHECK_TIMEOUT_MS);
+          timer.unref?.();
+        },
+      });
+      out = await Promise.race([turn, capped]);
+    } catch {
+      return; // a label may never fail the beat it rides
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (child) workChildren.delete(child);
+      releaseSlot();
+      /**
+       * DELETE THIS READING'S TRANSCRIPT, on EVERY exit — settled, wedged and
+       * killed, or thrown — because every one of them leaves the file behind
+       * and the agent's `--continue` reads the newest one in the directory.
+       *
+       * AFTER the kill and ON A DELAY, the skills probe's own shape: the
+       * transcript is the CHILD's file, so removing it while the child is still
+       * dying races a recreate. Unref'd — it must not hold the process open.
+       */
+      if (preSession) setTimeout(() => removeProbeTranscript(wt, preSession), 750).unref?.();
+    }
+
+    // A WEDGED READING POSTS NOTHING. There is no row to settle and nobody
+    // waiting on an answer, so the honest record is that no pre-review exists —
+    // the same silence a machine that never ran one leaves.
+    if (wedged) {
+      note(`${c.cyan('pre-review')} ${c.dim('— ran past five minutes and was stopped')}`);
+      return;
+    }
+
+    /**
+     * SCRUBBED ON THE WAY OUT, every string — AND SCRUBBED BEFORE IT IS CUT,
+     * which is the order that matters and the reason `envScrub` rides INTO the
+     * parser rather than being applied to what comes back out.
+     *
+     * This turn read the repository with `cat` and `git show` in a worktree
+     * holding the project's materialized dev secrets, and its answer is about to
+     * be stored and rendered to every member of the project. `scrub` replaces
+     * EXACT full values, so a note capped first and scrubbed second hands the
+     * scrub a credential already cut in half: it matches nothing and the
+     * surviving prefix ships. The check's output lane learned exactly that the
+     * expensive way, and this lane relearned it in review (2026-09-17) — see
+     * `parsePrecheck`, which now caps only what it has already redacted.
+     */
+    const result = parsePrecheck(out, envScrub);
+
+    /**
+     * A QUOTA LIMIT SKIPS THE PRE-REVIEW AND PARKS NOTHING — AND A LIMIT IS
+     * ONLY A LIMIT WHEN THE READING PRODUCED NOTHING.
+     *
+     * `limitLine` is a literal phrase match over the CLI's whole output, and
+     * under `answerFromResult` that output IS the reviewer's answer — so a
+     * pre-review OF rate-limiting code, or any triage that quotes the phrase,
+     * read as a quota failure and threw a perfectly good reading away. The
+     * agent-turn lane fixed this exact false positive once (`const limit = res
+     * ? null : limitLine(out)`); gating on "nothing parsed" is what makes the
+     * match mean what it says.
+     *
+     * And when it IS a limit, nothing parks. `postAgentParked` stops EVERY
+     * agent on the project, because the CLI login is shared — the right answer
+     * when the thing that hit the limit was somebody's actual work, the wrong
+     * one here: parking a whole fleet because a LABEL could not be written
+     * would let an optional readout take the product's primary lane down. The
+     * branch is still reviewable; it just has no note on it.
+     */
+    if (!result) {
+      if (limitLine(out)) {
+        note(`${c.cyan('pre-review')} ${c.dim('— skipped: the CLI reported a limit')}`);
+      }
+      // UNPARSEABLE POSTS NOTHING. A half-read triage is a plausible-looking
+      // paragraph nobody wrote, rendered on the surface where somebody decides
+      // whether a branch reaches main — see parsePrecheck.
+      return;
+    }
+
+    const body = {
+      agentId,
+      ...(headSha ? { headSha } : {}),
+      ...(usage ? { usage } : {}),
+      cards: result.cards.map((cd) => ({
+        taskId: cd.taskId,
+        verdict: cd.verdict,
+        ...(cd.note ? { note: cd.note } : {}),
+      })),
+      ...(result.overall ? { overall: result.overall } : {}),
+    };
+    // ONE RETRY, and only for a network error — see `postPre`. A permanent
+    // refusal is an older server, and asking it again changes nothing.
+    if (!(await postPre(body))) await postPre(body);
+  };
+
+  return { runPrecheck };
+}

package/bin/lib/workAgentPublish.mjs

@@ -0,0 +1,177 @@
+/**
+ * PUBLISHING AN AGENT'S BRANCH — the push to the name the server gave it, the
+ * fetch that brings a published branch back to a box that lost it, and the
+ * two process-local records (what this machine pushed; what it has seen at
+ * the remote ref) that the push's lease and the worktree report read.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). The argv shapes are
+ * agentPublish.mjs's (pure, tested there); this module owns the STATE and the
+ * network calls. The agent lane pushes after a settle and fetches at the
+ * begun-guard, the sweep keeps a published branch current, the merge lane
+ * retires the ref — all through the maps and two functions returned here.
+ */
+import { git } from './git.mjs';
+import { publishPushArgs, publishFetchArgs, publishErrorText } from './agentPublish.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+
+export function createWorkAgentPublish({ repoRoot, gitNet }) {
+  // ── PUBLISHING AN AGENT'S BRANCH ───────────────────────────────────────────
+  //
+  // The server names the target (`agentTurnJobs[].publishTo`) and this machine
+  // pushes to it. Two laws hold the whole lane up:
+  //
+  // A PUSH NEVER BLOCKS OR FAILS A TURN. It is tail work after the settle, it
+  // is try/catch'd like every sweep, and a failure is REPORTED in git's own
+  // words rather than thrown. An agent whose remote push fails has still done
+  // its work, still committed it, and still settled.
+  //
+  // THE SERVER LEARNS OF A PUSH ONLY BY BEING TOLD. Nothing here composes a
+  // name: an absent `publishTo` is a project that has publishing off, or a
+  // server older than this daemon, and in both the honest behaviour is to push
+  // nothing and report nothing. Absence keeps one meaning.
+  /**
+   * WHAT THIS MACHINE LAST DID WITH EACH AGENT'S BRANCH, by place —
+   * `{ ref, sha }` for a push that landed, `{ ref, error, at, tried }` for one
+   * that did not. Mutually exclusive by construction, which is what makes the
+   * report's two keys mutually exclusive without a second rule.
+   *
+   * Process-local on purpose: it is a record of what THIS daemon pushed, so a
+   * restart re-pushes once and re-reports — a push of the same sha to the same
+   * ref is a no-op at the remote, and re-learning beats trusting a file about
+   * something a rebase can invalidate.
+   */
+  const agentPublished = new Map();
+  /**
+   * WHAT THIS PROCESS HAS SEEN AT EACH AGENT'S REMOTE REF — `{ ref, sha }`, and
+   * the ONLY input to the push's lease.
+   *
+   * It is deliberately NOT `agentPublished`: that map is the REPORT record (what
+   * this machine pushed, and what the server may be told), while this one is an
+   * observation of the REMOTE's own position, which a box also gets by FETCHING
+   * a ref it never pushed. A box that fetch-continues an agent has seen the ref
+   * and must be able to lease against it; a box that has seen nothing pushes
+   * with no force flag at all.
+   *
+   * Process-local for the same reason the record beside it is: a restart has
+   * observed nothing, and an unforced push is the honest thing to do about that
+   * — it lands, or it refuses and says so.
+   */
+  const agentRemoteAt = new Map();
+  /** A failed push retries on the next sweep, but not FOREVER at sweep cadence:
+   *  a remote that refuses (no credentials on this box, a protected prefix)
+   *  would otherwise cost a blocking network call per agent per minute for the
+   *  life of the daemon. A moved branch always retries immediately — the
+   *  throttle is on repeating the SAME attempt, never on new work. */
+  const PUBLISH_RETRY_MS = 5 * 60_000;
+  /** The tip of an agent's local branch, or null when this box does not hold it
+   *  — which is a perfectly ordinary state (the begun-guard's whole subject) and
+   *  means there is nothing to publish, never that a push failed. */
+  const agentBranchSha = (place) => {
+    try {
+      return (
+        git(['rev-parse', '--verify', '--quiet', `refs/heads/session/${place}`], repoRoot) || null
+      );
+    } catch {
+      return null;
+    }
+  };
+  /**
+   * PUSH ONE AGENT'S BRANCH TO THE NAME THE SERVER GAVE IT.
+   *
+   * Returns TRUE when the recorded state CHANGED, because the caller's next act
+   * is a worktree report and a report that says what the last one said is a
+   * write per minute restating a fact. The rule this serves is the one every
+   * settle keeps: an action that changes what the machine would measure must
+   * cause a new measurement — and only then.
+   *
+   * Never throws.
+   */
+  const publishAgentBranch = async (place, target) => {
+    const sha = agentBranchSha(place);
+    if (!sha) return false;
+    const prev = agentPublished.get(place);
+    if (prev?.ref === target && prev.sha === sha) return false; // already there
+    if (
+      prev?.ref === target &&
+      prev.error &&
+      prev.tried === sha &&
+      Date.now() - (prev.at ?? 0) < PUBLISH_RETRY_MS
+    )
+      return false; // the same attempt failed moments ago
+    // THE LEASE IS THIS PROCESS'S OWN LAST SIGHTING of that ref, and nothing
+    // else — never git's remote-tracking ref, which this daemon's own sweep
+    // fetch refreshes (the argument is in `publishPushArgs`). An expectation
+    // recorded against a DIFFERENT ref is no expectation for this one.
+    const seen = agentRemoteAt.get(place);
+    // A ref that is not the server's shape never reaches argv. Silent, because
+    // a refusal here is a feature not happening on this turn, not a failure of
+    // it — and a `publishError` about a value we declined to use would be this
+    // machine reporting on a push it never attempted.
+    const args = publishPushArgs(place, target, seen?.ref === target ? seen.sha : null);
+    if (!args) return false;
+    try {
+      gitNet(args, 60_000);
+      agentPublished.set(place, { ref: target, sha });
+      agentRemoteAt.set(place, { ref: target, sha });
+      return true;
+    } catch (e) {
+      const error = publishErrorText(envScrub(e?.stderr?.toString?.() || e?.message || ''));
+      agentPublished.set(place, { ref: target, error, at: Date.now(), tried: sha });
+      // A repeat of a failure already reported is not news; the server's stored
+      // sentence is already this one.
+      return !(prev?.error === error && prev.ref === target);
+    }
+  };
+  /**
+   * BRING A PUBLISHED BRANCH BACK DOWN — the other half of the durability
+   * promise, and the only thing that lets an agent's work outlive its box.
+   *
+   * Reached from ONE place: the begun-guard's refusal arm, where this machine
+   * has just MEASURED that it holds neither the agent's worktree nor its branch.
+   * The server only sends `publishedRef` when it heard about a real push, so
+   * this is not a guess at a remote branch — it is a fetch of one a machine
+   * reported writing.
+   *
+   * ── WHAT IT RECOVERS, AND WHAT IT CANNOT ──
+   *
+   * COMMITS COME BACK. The CONVERSATION DOES NOT: the CLI's held context lives
+   * in the box that ran it and nothing here transports it. The turn kickoff
+   * re-prompts from the card, which is the honest continuation — an agent that
+   * picks up its own commits and re-reads its own card, never one that remembers
+   * the argument. Nothing this returns may be phrased as if it did.
+   *
+   * THREE ANSWERS, because two would lie. `null` is "there was nothing to try"
+   * (no ref, or one whose shape this machine will not put in argv), and it must
+   * leave the existing refusal EXACTLY as it was — a sentence about a fetch
+   * nobody attempted is worse than the plain refusal. `{ ok: false, why }` is a
+   * measured failure, relayed in git's own words. `{ ok: true }` is only ever
+   * returned after re-reading the ref: a fetch that exits 0 having created
+   * nothing would otherwise walk straight into `placeWtFor` cutting a fresh
+   * branch off base — the context-free redo the guard above exists to prevent,
+   * wearing this feature's name.
+   */
+  const fetchPublishedBranch = (place, ref) => {
+    const args = publishFetchArgs(ref, place);
+    if (!args) return null;
+    try {
+      gitNet(args, 120_000);
+    } catch (e) {
+      return {
+        ok: false,
+        why: publishErrorText(envScrub(e?.stderr?.toString?.() || e?.message || '')),
+      };
+    }
+    const sha = agentBranchSha(place);
+    if (!sha) return { ok: false, why: 'the fetch reported nothing and left no local branch' };
+    // WHAT THIS PROCESS HAS NOW SEEN AT THAT REMOTE REF. A fetch is an
+    // observation of the remote's own position, and for a box that continues an
+    // agent it never started it is the ONLY one it will ever have — without it
+    // this box's first push would carry no lease and would have to go unforced.
+    // It is not a `publishAgentBranch` record: this machine pushed nothing, so
+    // the server is told nothing.
+    agentRemoteAt.set(place, { ref, sha });
+    return { ok: true };
+  };
+
+  return { agentPublished, agentRemoteAt, publishAgentBranch, fetchPublishedBranch };
+}