flowviant 0.103.0 → 0.105.0

package/bin/lib/workAgentTurns.mjs

@@ -1,26 +1,33 @@
-/** Agent turns, trace delivery, admission, and held settlement reports. */
-import { limitLine } from './workAgentReview.mjs';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { FLEET_URL, FLEET_TOKEN, USER_AGENT, PROJECT_ID } from './config.mjs';
-import { setRuntimeLimit } from './desktopContract.mjs';
-import { git, isSafePathSegment } from './git.mjs';
-import { parseTurnResult } from './agentPlan.mjs';
-import { stashCard } from './agentCards.mjs';
+/**
+ * THE AGENT-TURN LANE: which offered turns run on this machine, and that each
+ * one is settled exactly once.
+ *
+ * Since the 2026-09-26 SOLID pass (F036) this file is the coordinator and
+ * nothing else. It admits a roster's turns against the machine's pressure,
+ * re-POSTs a finished turn's held body instead of re-running its CLI, refuses
+ * the turns no box should run (a traversal place, a card that is gone), takes
+ * the agent's place lock as a WRITER, publishes the branch after the settle,
+ * and settles everything in flight when the machine moves away. What it hands
+ * off, each to the module named for it:
+ *  - every POST and the held-body map: workAgentTurnReports.mjs
+ *  - running one turn in its worktree: workAgentTurnExecution.mjs
+ *  - the begun-guard: workAgentTurnBegun.mjs
+ *  - what a finished (or failed) run reports: workAgentTurnOutcome.mjs
+ *
+ * The split exposed the defect it fixes: a run that THREW left its turn
+ * unsettled, so the next offer ran it again. The lane now catches, measures
+ * what the run had learned, and settles `nothing` once — unless the run had
+ * already sent a settle, which always outranks the crash.
+ */
+import { existsSync } from 'node:fs';
+import { isSafePathSegment } from './git.mjs';
 import { c, note } from './ui.mjs';
-import { runTurn } from './claude.mjs';
-import { SYSTEM_AGENT_FOR, agentTaskKindOf, unknownAgentTaskKind, AGENT_TASK_KICKOFF, AGENT_TASK_SPEC, AGENT_HUMAN_KICKOFF, withProjectContext } from './prompts.mjs';
-import { knowledgeDirFor } from './knowledge.mjs';
-import { changedArtifacts, scanArtifacts } from './artifacts.mjs';
-import { scrub as envScrub } from './env.mjs';
-import { canRun, recordSkills, recordMcpServers, toolEventOf, CLAUDE_TOOL_PROSE_KINDS, RUNTIMES } from './runtimes.mjs';
-import { makeTraceRelay } from './trace.mjs';
-import { readBaseTools, prepareAgentTools } from './projectTools.mjs';
+import { createAgentTurnReports } from './workAgentTurnReports.mjs';
+import { createAgentTurnExecution } from './workAgentTurnExecution.mjs';
+import { failedTurnSettlement } from './workAgentTurnOutcome.mjs';
 
 export function createWorkAgentTurns({
   REJECT_RETRY_MS,
-  CODEX_THREAD_RE,
-  resumeConversationLost,
   baseRef,
   inPlace,
   baseDir,
@@ -28,7 +35,6 @@ export function createWorkAgentTurns({
   fetchPublishedBranch,
   placeWtFor,
   sessionMetaPath,
-  brainFor,
   beforeArtifacts,
   getArtifactsAccepted,
   noteSessionGroup,
@@ -37,14 +43,19 @@ export function createWorkAgentTurns({
   runReviewEntry,
   publishAgentBranch,
   admit,
-  state,
+  workChildren,
+  agentPublished,
+  agentRemoteAt,
 }) {
-  const AGENT_TURN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-turn-done');
-  const AGENT_TRACE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-trace');
-  const AGENT_ACTIVITY_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-activity');
-  const AGENT_PARKED_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-parked');
-
-  const { workChildren, agentPublished, agentRemoteAt } = state;
+  const {
+    postAgentTurn,
+    postAgentTrace,
+    postAgentActivity,
+    postAgentParked,
+    pruneHeldReports,
+    agentReported,
+    agentRejectedUntil,
+  } = createAgentTurnReports({ REJECT_RETRY_MS });
 
   // ── AGENT TURNS: one task per prompt ───────────────────────────────────────
   //
@@ -79,164 +90,25 @@ export function createWorkAgentTurns({
    */
   const agentChildren = new Map(); // placeId -> child process
 
-  /** Returns the server's reply, because it carries ONE instruction the machine
-   *  can act on immediately: `review: true` means the agent's queue just
-   *  emptied, so run the project's own check in the worktree we are already
-   *  standing in. A job lane for that would need a claim, a floor and a settle
-   *  to say something this reply already can. */
-  /**
-   * Turns whose work is DONE but whose settle has not landed, keyed to the
-   * finished BODY. The delivery half of what `pendingWorkReports` is for a
-   * tab: a settle that fails to POST must not re-run the turn — that is a
-   * second CLI, a second set of commits, and the operator's quota spent again
-   * — but a guard that only SKIPPED left the other half undone. One failed
-   * POST parked the agent for the server's whole six-hour expiry, holding a
-   * cap slot the entire time, and then expired into "nobody ran it" — a false
-   * sentence about a turn this machine finished. The server's settle is
-   * idempotent (conditional on the row still being pending), so a re-offer of
-   * a held turn re-POSTs the stored body instead: safe, and it lands the
-   * moment the network heals rather than six hours later.
-   *
-   * BOUNDED by the roster itself: a held body's clock is refreshed while the
-   * server keeps offering its turn, and once offering stops — settled by the
-   * re-POST, or expired server-side — the grace below is all that keeps it.
-   */
-  const agentReported = new Map(); // turnId -> { body, at }
-  const agentRejectedUntil = new Map(); // turnId -> earliest re-POST of a refused body
-  const AGENT_REPORT_GRACE_MS = 30 * 60_000;
-
-  const postAgentTurn = async (body) => {
-    const turnId = String(body.turnId);
-    agentReported.set(turnId, { body, at: Date.now() });
-    try {
-      const res = await fetch(AGENT_TURN_DONE_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),
-      });
-      const j = await res.json().catch(() => null);
-      /**
-       * ONLY A 2xx IS DELIVERED. The server answers an already-settled,
-       * expired or unknown turn with 200 `{ settled: false }` — its only 4xx
-       * are a body it could not parse (deploy skew) and auth, and an edge WAF
-       * rule tripped by a summary that quotes an exploit string is a 403 from
-       * in front of it. Each of those left the turn row PENDING, and dropping
-       * the held body on them meant the next offer found nothing held and ran
-       * the CLI again: a second set of commits and the operator's quota spent,
-       * every poll, for six hours. The tab lane learned this as its 'reject'
-       * class. So a refused body stays HELD — it is the skip-guard — and its
-       * re-POST backs off instead of hammering a body the server just refused.
-       */
-      if (res.ok) {
-        agentReported.delete(turnId);
-        agentRejectedUntil.delete(turnId);
-      } else if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
-        agentRejectedUntil.set(turnId, Date.now() + REJECT_RETRY_MS);
-      }
-      return j?.data ?? null;
-    } catch {
-      // Unsettled — a network error, so the body STAYS held and the next
-      // re-offer retries the POST rather than the CLI.
-      return null;
-    }
-  };
-
-  /**
-   * ONE BATCH OF A TURN'S TRACE. See trace.mjs for the whole contract.
-   *
-   * Resolves TRUE for a permanent refusal as well as a success, and that is
-   * deliberate: a server with no such route 404s every batch, and a relay that
-   * held them would fill its buffer, shed the turn's real steps and retry the
-   * same rejected body for the life of the turn. There is no version floor here
-   * — this is a daemon→server report, so an older server simply never learns
-   * the trace and the board renders what it always did.
-   */
-  const postAgentTrace = async (body) => {
-    try {
-      const res = await fetch(AGENT_TRACE_URL, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${FLEET_TOKEN}`,
-          'User-Agent': USER_AGENT,
-          'Content-Type': 'application/json',
-        },
-        signal: AbortSignal.timeout(15_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 — the same entries go again at the same seq
-    }
-  };
-
-  /** How long the final flush may hold the settle. Bounded because the settle
-   *  is the turn's contract and the trace is a readout: a wedged uplink costs
-   *  the tail of a trace, never the answer behind it. */
-  const TRACE_FINAL_FLUSH_MS = 8_000;
-
-  const postAgentActivity = async (agentId, text) => {
-    try {
-      await fetch(AGENT_ACTIVITY_URL, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${FLEET_TOKEN}`,
-          'User-Agent': USER_AGENT,
-          'Content-Type': 'application/json',
-        },
-        signal: AbortSignal.timeout(15_000),
-        body: JSON.stringify({ agentId, text }),
-      });
-    } catch {
-      /* narration is a readout; losing a line costs nothing */
-    }
-  };
-
-  /** Every sha that landed on this branch between two points. Measured, never
-   *  asserted — this is the whole reason an agent is not asked for its own. */
-  const commitsBetween = (wt, from) => {
-    if (!from) return [];
-    /**
-     * `--not <base>` and `--no-merges`, because `from..HEAD` alone reports
-     * BASE'S commits as this turn's receipts the moment anything folds base in
-     * — which the stale path does on purpose before a merge. A receipt naming
-     * somebody else's commit is worse than a missing one.
-     */
-    /**
-     * IT CANNOT THROW, and that guard is the whole point of it being here.
-     *
-     * `git()` throws on a non-zero exit, and `baseRef()` is built from the
-     * project's Base branch setting — free text an owner types, never verified
-     * against the remote. Point it at a branch with no tracking ref (`develop`
-     * on a repo whose remote branch is `dev`) and this exits "fatal: ambiguous
-     * argument". The throw escaped `runAgentTurn` AFTER the CLI had already run
-     * the card, so `postAgentTurn` was never reached, the server never settled
-     * the turn, and the next poll handed back the identical turn — the same
-     * card re-run every poll for six hours, on the operator's shared account,
-     * piling commits onto the review branch, silently.
-     *
-     * An unreadable range means we cannot MEASURE the receipts, which is a
-     * smaller failure than not settling: the turn still reports, and ship-time
-     * reconciliation books whatever no card claimed. Missing beats fabricated
-     * and both beat a stall.
-     */
-    let out;
-    try {
-      out = git(['log', '--format=%H', '--no-merges', `${from}..HEAD`, '--not', baseRef()], wt);
-    } catch {
-      return [];
-    }
-    return typeof out === 'string'
-      ? out.split('\n').map((x) => x.trim()).filter(Boolean).slice(0, 50)
-      : [];
-  };
+  const { runAgentTurnInPlace, commitsBetween } = createAgentTurnExecution({
+    baseRef,
+    baseDir,
+    repoRoot,
+    fetchPublishedBranch,
+    placeWtFor,
+    sessionMetaPath,
+    beforeArtifacts,
+    getArtifactsAccepted,
+    noteSessionGroup,
+    reportSessionWorktree,
+    artifacts,
+    runReviewEntry,
+    workChildren,
+    agentChildren,
+    postAgentTrace,
+    postAgentActivity,
+    postAgentParked,
+  });
 
   /** `releaseSlot` hands back the admission reservation the caller took on this
    *  turn's behalf, at the moment the CLI actually exists. Idempotent and
@@ -252,7 +124,7 @@ export function createWorkAgentTurns({
     /**
      * A TASK TURN WITH NO CARD IS REFUSED, NOT IMPROVISED.
      *
-     * The kickoff below branches on `job.kind === 'task' && job.task` and falls
+     * The kickoff (workAgentTurnExecution.mjs) branches on `job.kind === 'task' && job.task` and falls
      * through to the HUMAN kickoff otherwise — and a task turn's body is empty
      * by design, because the daemon composes the prompt from the card's own
      * spec. So a card deleted while its agent held it spawned a real CLI on a
@@ -275,688 +147,45 @@ export function createWorkAgentTurns({
       return;
     }
 
+    /**
+     * A RUN THAT THROWS IS STILL SETTLED — ONCE (SOLID F036).
+     *
+     * The run posts its own settle on every path it knows about. `settled`
+     * records that one was SENT (delivered or held for re-POST, either way the
+     * turn is answered), so a throw after it — the review-entry beat, say —
+     * never posts a second, contradicting `nothing`. A throw before it is
+     * settled here, with what the run had measured by then: the commits on the
+     * branch, the spend, the branch and worktree. Through the same held-body
+     * wire, so a failed POST is re-sent on the next offer and the CLI is not
+     * run again.
+     */
+    const measured = { wt: null, before: null, branch: null, usage: null };
+    let settled = false;
+    const settleOnce = (body) => {
+      settled = true;
+      return postAgentTurn(body);
+    };
+
     // A WRITER on the agent's own place — see the lane header. Only `a-<id>`
     // places: those are agents' by construction, and anything else here would
     // be a tab's directory, where a turn is a reader by the product's own law.
     await inPlace(place, place.startsWith('a-'), async () => {
-      /**
-       * WORK THAT HAS BEGUN LIVES ON EXACTLY ONE BOX, AND THIS MAY NOT BE IT.
-       *
-       * A project has ONE machine credential and every device is handed the same
-       * raw token, so two boxes can both be polling for the same agents. Nothing
-       * pushes an agent's branch before approve, so a turn that has already run
-       * somewhere has its worktree, its branch and its CONVERSATION on that box's
-       * disk and nowhere else. `placeWtFor` cannot tell the difference: it finds
-       * no directory, cuts a fresh `session/a-<id>` off base, and the CLI starts
-       * with no memory of the card — a confident, context-free redo of work
-       * somebody is in the middle of, on the operator's shared account, landing
-       * on a rival branch of the same name.
-       *
-       * So: if the server says this agent has BEGUN and this box holds neither
-       * its directory nor its branch, refuse before anything is cut. `nothing` is
-       * the honest outcome — this machine did not run the turn — and the sentence
-       * says what was measured (two absences here, and the box name only when the
-       * server recorded one; inferring where the work is would be invention).
-       *
-       * THE BRANCH ALONE IS ENOUGH TO CONTINUE. `placeWtFor`'s attach fallback
-       * re-attaches a worktree to a surviving branch, so a directory somebody
-       * cleaned up on THIS box is same-box recovery of real committed work and
-       * behaves exactly as it did before this guard existed.
-       *
-       * The remedy is the stop path and nothing else. "Reconnect the other
-       * machine" is not reachable from here once holdership has moved, and a
-       * remedy somebody cannot carry out is worse than none.
-       */
-      if (job.begun) {
-        const wtDir = join(baseDir, 'sessions', place);
-        let hasBranch = false;
-        /**
-         * THREE STATES, AND THE MIDDLE ONE IS WHY THIS IS NOT A BARE CATCH.
-         *
-         * `rev-parse --verify --quiet` exits 1 and prints nothing for a ref that
-         * is not there — that exit code IS the measurement, and it is the one
-         * this guard acts on. Any OTHER failure (128 for "not a repository",
-         * ENOENT for no git at all, a momentary index lock) measured nothing;
-         * collapsing it onto "the branch is absent" would make the daemon assert
-         * "this machine does not hold this agent's branch" off a repo it could
-         * not read — the guard inventing the very fact it exists to relay.
-         *
-         * So an unmeasured branch stands the guard DOWN. That re-enters the path
-         * this guard is a belt for, which is the fail-open direction it wants;
-         * `placeWtFor` is about to fail on the same unreadable repo and say so
-         * in its own words, which is the honest sentence.
-         */
-        let branchMeasured = true;
-        try {
-          hasBranch = Boolean(
-            git(['rev-parse', '--verify', '--quiet', `refs/heads/session/${place}`], repoRoot)
-          );
-        } catch (e) {
-          if (e?.status === 1) hasBranch = false;
-          else branchMeasured = false;
-        }
-        if (branchMeasured && !existsSync(wtDir) && !hasBranch) {
-          /**
-           * …UNLESS THE WORK IS ON THE REMOTE (0.86.0).
-           *
-           * The guard's premise was "nothing pushes an agent's branch before
-           * approve", and a project that publishes has changed exactly that
-           * third of it: the COMMITS are on `origin` under `flowviant/`, so a
-           * box that holds neither the directory nor the branch can fetch them
-           * and continue the work instead of redoing it. The other two thirds
-           * are untouched — the conversation still does not move, which is why
-           * the kickoff re-prompts from the card either way.
-           *
-           * The refusal below is still the fallback, and it is the fallback for
-           * BOTH shapes of failure: a project that does not publish (no ref,
-           * sentence unchanged) and a fetch that could not land (sentence
-           * extended with git's own reason, because "this machine does not hold
-           * it" alone would hide that we tried and how it went).
-           */
-          const fetched = fetchPublishedBranch(place, job.publishedRef);
-          if (!fetched?.ok) {
-            const on = typeof job.begunOn === 'string' && job.begunOn.trim()
-              ? job.begunOn.trim().slice(0, 64)
-              : null;
-            await postAgentTurn({
-              turnId,
-              outcome: 'nothing',
-              answer:
-                `This machine does not hold this agent's worktree or branch${on ? ` — its work is on ${on}` : ''}. ` +
-                'Stop the agent to re-plan it here.' +
-                (fetched ? ` Its published branch could not be fetched (${fetched.why}).` : ''),
-            });
-            return;
-          }
-          // The branch is here and measured. `placeWtFor`'s attach fallback
-          // opens a worktree on it below — the same path a directory somebody
-          // cleaned up already takes, on commits this box now genuinely holds.
-        }
-      }
-      const dir = placeWtFor(place);
-      if (!dir) {
-        // No worktree and none could be cut. `nothing`, WITH git's own words:
-        // without them the agent sat in Stuck with no question and no reason
-        // (the owner, 2026-09-25: "it got stuck without saying why").
-        const why = placeWtFor.lastError ?? null;
-        await postAgentTurn({ turnId, outcome: 'nothing', ...(why ? { answer: `This machine could not start the turn: ${why}` } : {}) });
-        return;
-      }
-      const wt = dir.wt;
-      /**
-       * NEITHER OF THESE MAY THROW. `git()` throws on a non-zero exit, and both
-       * of these exit non-zero in states a real worktree reaches: `symbolic-ref`
-       * on a DETACHED HEAD (an agent that ran `git checkout <sha>`, a rebase
-       * left half-done), and `rev-parse HEAD` on a branch with no commits yet.
-       * An escape here happens BEFORE any settle, so the turn stays pending
-       * until the six-hour expiry while the agent sits in Working with nothing
-       * behind it — the wedge this whole lane exists to avoid.
-       *
-       * `runAgentMerge` learned this two commits ago and says so in its own
-       * comment; this is the same call, in the same file, left unguarded. Both
-       * facts are OPTIONAL to a turn — they describe the branch, they do not
-       * gate the work — so failing to read them costs a null, not the turn.
-       */
-      const readGit = (args) => {
-        try {
-          return (git(args, wt) || '').trim() || null;
-        } catch {
-          return null;
-        }
-      };
-      // WHERE THE BRANCH WAS BEFORE THIS TURN, so the commits reported are the
-      // ones this turn actually made.
-      const before = readGit(['rev-parse', 'HEAD']);
-      const branch = readGit(['symbolic-ref', '--quiet', '--short', 'HEAD']);
-
-      const rt = job.runtime || 'claude';
-      /**
-       * WHAT THIS CARD HANDS BACK, AND THE POSTURE THAT FOLLOWS (0.97.0).
-       *
-       * `code` (the default — absent on the job IS code) is the build turn,
-       * byte-for-byte what every agent turn was. `design` and `research` run
-       * their own contract (SYSTEM_AGENT_DESIGN / _RESEARCH) under their own
-       * posture, which can write ONLY `.flowviant/artifacts/` (claude.mjs).
-       *
-       * A RUNTIME THAT CANNOT EXPRESS THE POSTURE IS REFUSED, NOT IMPROVISED.
-       * Codex and antigravity declare neither (runtimes.mjs), and the only
-       * alternative to refusing is running the card as a BUILD turn with
-       * permissions skipped — an agent writing code for an ask that was a
-       * mockup, reporting success. `nothing` puts the agent in Stuck saying so.
-       *
-       * THE JOB'S OWN KIND FIRST (2026-09-23). A `human` turn — a send-back
-       * from the review deck, an answer — usually names NO card: the queue has
-       * emptied, or the card it is about was just re-queued behind it. Read off
-       * `job.task` alone, a send-back on a design agent ran as a BUILD turn
-       * under the code contract with permissions skipped — the one turn in the
-       * owner's loop ("iterate in the review column, the agent opened") that
-       * could edit code on an ask that was a mockup. So the server projects the
-       * kind of the card the turn is ABOUT onto the job itself (`taskKind`,
-       * sent only for design and research; the same `DAEMON_TASK_KIND_MIN`
-       * floor as the card's own key, no new one), and the card's key stays the
-       * fallback for a server that sends only that. Absent on both is code.
-       */
-      /**
-       * A KIND THIS DAEMON DOES NOT KNOW IS REFUSED, NEVER BUILT (2026-09-23).
-       * `agentTaskKindOf` reads anything unrecognised as code — right for a
-       * printed label, wrong here, where code means the build posture with
-       * permissions skipped. A server that learned a fourth kind ahead of
-       * this daemon is exactly the case the version floor cannot cover (the
-       * handout does not re-check it), and the answer is an update, said in
-       * the word the server used. `nothing` puts the agent in Stuck with it.
-       */
-      const strangeKind = unknownAgentTaskKind(job.taskKind ?? job.task?.taskKind);
-      if (strangeKind !== null) {
-        await postAgentTurn({
-          turnId,
-          outcome: 'nothing',
-          answer: `this daemon does not know the card kind '${strangeKind}' — update it`,
-          branch,
-          worktree: wt,
-        });
-        return;
-      }
-      const taskKind = agentTaskKindOf(job.taskKind ?? job.task?.taskKind);
-      const posture = taskKind === 'code' ? 'build' : taskKind;
-      if (!canRun(RUNTIMES[rt], posture)) {
-        await postAgentTurn({
-          turnId,
-          outcome: 'nothing',
-          answer:
-            posture === 'build'
-              ? `this machine cannot run ${rt}`
-              : 'design and research cards run on Claude on this machine',
-          branch,
-          worktree: wt,
-        });
-        return;
-      }
-
-      // ONE AGENT IS ONE DIRECTORY, so the CLI's own cwd-keyed resume is exactly
-      // right here — the ambiguity that forced per-tab session pinning in the
-      // Workbench (many tabs, one place) cannot arise. The marker is what
-      // distinguishes the first turn from every later one across restarts.
-      //
-      // IT MEANS "CLAUDE HAS SPOKEN HERE", and since 2026-09-24 only a Claude
-      // turn writes it: an agent can be switched between CLIs, and a marker a
-      // codex turn left behind would send the first Claude turn to
-      // `--continue` a directory holding no Claude conversation at all.
-      const ranMarker = sessionMetaPath(wt, 'flowviant-agent-ran');
-      /**
-       * CODEX RESUMES BY ITS OWN THREAD ID, PINNED PER AGENT (2026-09-24).
-       *
-       * Resume was Claude-only, because codex's `resume --last` is
-       * MACHINE-GLOBAL and would cross-resume whichever conversation spoke
-       * last anywhere on the box. The cost was that every codex card started
-       * a stranger: no memory of the card before it, and — worse — an answer
-       * to the agent's own question arrived at a codex that never asked it.
-       * The Workbench solved the same problem in 0.69.0 by pinning the id
-       * `thread.started` announces; this is that, keyed by the AGENT rather
-       * than a tab. The id is shape-checked before it rides argv.
-       */
-      const codexThreadMarker =
-        rt === 'codex' ? sessionMetaPath(wt, 'flowviant-agent-codex-thread', agentId) : null;
-      let codexResumeId = null;
-      if (codexThreadMarker && existsSync(codexThreadMarker)) {
-        try {
-          const v = readFileSync(codexThreadMarker, 'utf8').trim();
-          if (CODEX_THREAD_RE.test(v)) codexResumeId = v;
-        } catch {
-          /* unreadable marker — run fresh */
-        }
-      }
-      let seenThreadId = null;
-      const resume =
-        rt === 'codex'
-          ? Boolean(codexResumeId)
-          : rt === 'claude' && Boolean(ranMarker && existsSync(ranMarker));
-
-      /**
-       * WRITE THE CARD DOWN BEFORE HANDING IT OVER — the material the AI
-       * pre-review reads at review entry (see agentCards.mjs).
-       *
-       * HERE rather than at review entry because here is the ONLY moment this
-       * machine holds the card at all: the server feeds an agent one card per
-       * prompt and keeps no copy on this disk, so by the time the queue empties
-       * card one exists locally as nothing but its own commit messages — which
-       * are a claim about the work, not the specification it was judged against.
-       *
-       * BEFORE the CLI runs rather than after, so a turn that crashes still
-       * leaves the spec behind: the card really was given to the agent, the
-       * commits it made are on the branch, and a reviewer is entitled to read
-       * what was asked for either way.
-       *
-       * ONE SPEC BUILDER (`AGENT_TASK_SPEC`) shared with the kickoff below, so
-       * what the reviewer reads is byte-identical to what the agent read.
-       * Failure is swallowed inside `stashCard`: a note about a turn may never
-       * cost the turn.
-       */
-      if (job.kind === 'task' && job.task) {
-        stashCard(
-          sessionMetaPath(wt, 'flowviant-agent-cards', agentId),
-          job.task.id,
-          AGENT_TASK_SPEC(job.task)
-        );
-      }
-
-      /**
-       * THE WHOLE STREAM, not just its latest line — see trace.mjs.
-       *
-       * The pulse below is untouched and still sent: it carries staleness (how
-       * long the machine has been quiet), which an append-only list of steps
-       * cannot say, because a list that stopped growing looks exactly like a
-       * list that is finished.
-       */
-      const trace = makeTraceRelay({
-        agentId,
-        turnId,
-        post: postAgentTrace,
-        scrub: envScrub,
-      });
-      /**
-       * Prose the structured event will carry anyway, dropped so a read does
-       * not render twice — but ONLY on a runtime whose stream reaches
-       * `onToolEvent` at all. Codex and agy have their own parsers and never
-       * call it, so dropping their tool prose would blank their agents' traces.
-       * `parse: null` is exactly the claude.mjs stream path. See
-       * CLAUDE_TOOL_PROSE_KINDS.
-       */
-      const doubledKinds = RUNTIMES[rt]?.parse ? null : CLAUDE_TOOL_PROSE_KINDS;
-
-      /**
-       * WHICH BRAIN THIS CONTAINER WAS PINNED TO — the same `brainFor` the tab
-       * lane runs, on the same two job keys, because an agent turn and a
-       * session turn differ in who is watching and in nothing else that a model
-       * name touches. Every guard lives in `brainFor`: a second copy here would
-       * be a second answer to "is this a model we can spell", and the two would
-       * drift the first time one of them learned a new effort.
-       *
-       * Absent stays genuinely absent — an agent nobody pinned produces the
-       * byte-identical argv it produced yesterday, on the machine's own
-       * default. That is also what an OLDER server yields, since it sends
-       * neither key.
-       */
-      const brain = brainFor(job);
-
-      let out = '';
-      let child = null;
-      /**
-       * WHAT THIS TURN SPENT, AS THE CLI COUNTED IT (2026-09-19).
-       *
-       * Held across the whole turn so every settle below can carry it — a turn
-       * that hit a limit, produced no parseable outcome or delivered properly
-       * all spent real tokens, and a readout that only charged the happy path
-       * would under-report the runs somebody opens the number to understand.
-       *
-       * The three settles it is spread into are the ones that follow a CLI
-       * actually running. The pre-spawn refusals above (a bad place, a missing
-       * card, the begun-guard) and the teardown sweep below deliberately do NOT
-       * take it: nothing ran there, and `usage` stays null anyway, which is
-       * what makes `...(usage ? … : {})` the whole guard.
-       */
-      let usage = null;
-      /**
-       * THE AGENT'S LAST MESSAGE, ALONE — where the final JSON object lives.
-       * Codex's `out` is every message plus stderr plus error text, and
-       * `parseTurnResult` takes the first object that fits, so an early
-       * message quoting the format could be read as the outcome. Claude never
-       * calls this (its `out` is already the result under `answerFromResult`).
-       */
-      let lastAnswer = null;
-      /** The agent's artifact directory as it stood before this turn — the
-       *  tab lane's rule, in the agent's own worktree (2026-09-22). */
-      const artifactsBefore = beforeArtifacts(wt);
-      let projectTools = null;
       try {
-        // A turn reads the base ref afresh. Changes the agent has made to its
-        // own worktree cannot silently change the next turn's tools.
-        projectTools = prepareAgentTools(readBaseTools(repoRoot, baseRef()), rt, process.env, wt);
-        const agentTurnArgs = {
-          prompt:
-            job.kind === 'task' && job.task
-              ? AGENT_TASK_KICKOFF({
-                  agentName: job.agentName,
-                  task: job.task,
-                  position: job.position ?? 1,
-                  total: job.total ?? 1,
-                })
-              : AGENT_HUMAN_KICKOFF({
-                  agentName: job.agentName,
-                  message: job.body ?? '',
-                  askedByName: job.askedByName,
-                  task: job.task,
-                  position: job.position ?? 1,
-                  total: job.total ?? 1,
-                }),
-          // The knowledge paragraph, when this box holds a library — the same
-          // composer the tabs use, so an agent and a tab can never be told two
-          // different things about the same directory.
-          system: withProjectContext(SYSTEM_AGENT_FOR(taskKind), {
-            knowledgeDir: knowledgeDirFor(repoRoot),
-            // ARTIFACTS (0.94.0), while the server can show one — an agent's
-            // land on its page, under the facts row.
-            artifacts: getArtifactsAccepted(),
-          }) + (projectTools.instructions ? `\n\n${projectTools.instructions}` : ''),
-          agentTools: projectTools,
-          ...(projectTools.codexHome ? { mcpEnv: { CODEX_HOME: projectTools.codexHome } } : {}),
-          ...(posture === 'build' && rt === 'claude'
-            ? { mcpArgs: ['--strict-mcp-config', '--mcp-config', projectTools.mcpPath] }
-            : posture === 'build' && rt === 'codex'
-              ? { mcpArgs: projectTools.codexArgs }
-              : {}),
-          knowledgeDir: knowledgeDirFor(repoRoot),
-          // Named only for the two non-code kinds; a code turn passes nothing
-          // and keeps the build branch it always had.
-          ...(posture !== 'build' ? { posture } : {}),
-          cwd: wt,
-          runtime: rt,
-          resume,
-          resumeThreadId: codexResumeId || undefined,
-          onThreadId: (id) => {
-            seenThreadId = String(id ?? '').trim() || seenThreadId;
-          },
-          onAnswer: (t) => {
-            lastAnswer = t;
-          },
-          // Present only when the container named one — see brainFor.
-          ...brain,
-          streamJson: true,
-          answerFromResult: true,
-          label: c.cyan('[agent]'),
-          // The CLI's own tail, relayed. Throttled by the same rule the tab's
-          // narrator keeps: overwritten, never appended, and ignored by the
-          // board past ~90 seconds.
-          onActivity: (a) => {
-            const line = a?.label;
-            if (!line) return;
-            // THE TRACE TAKES EVERY LINE; the pulse takes one every two
-            // seconds. Two channels, one stream, and the drop-sampler stays a
-            // drop-sampler — buffering the pulse would make a stale line look
-            // fresh, which is the one thing it exists to answer.
-            //
-            // …AND THE TRACE TAKES THE WHOLE LINE. `label` is a 160-char
-            // console readout; `full` is what the CLI actually said, when the
-            // parser had more than the label could hold (see runtimes.mjs).
-            // The fallback is not a degradation — it is what every activity
-            // without a fuller form carries, and what an entire pre-0.87.0
-            // daemon carried for all of them. The PULSE below is deliberately
-            // still `line`: it is one overwritten line on a board, and a
-            // paragraph there would be a paragraph nobody can read.
-            if (!doubledKinds || !doubledKinds.has(a.kind)) trace.prose(a.kind, a.full ?? line);
-            const now = Date.now();
-            if (now - (lastAgentBeat.get(agentId) ?? 0) < 2_000) return;
-            lastAgentBeat.set(agentId, now);
-            void postAgentActivity(agentId, envScrub(String(line)).slice(0, 400));
-          },
-          // The structured twin of the line above — the same `tool_use` the
-          // Workbench's tool cards are built from, scrubbed at collection by
-          // the builder itself (bounded window BEFORE its caps; see
-          // toolEventOf). A tool it does not know pushes nothing.
-          onToolEvent: (name, input) => {
-            trace.tool(toolEventOf(name, input, wt, envScrub));
-          },
-          // The CLI's own per-turn token counts, off the `result` event. One
-          // result per turn, so this is a set and not an accumulate — the
-          // adding-up happens SERVER-side, behind the settle's idempotent win,
-          // because a retried settle must not charge the same turn twice.
-          // …tagged with WHICH CLI counted it (2026-09-24), so the server can
-          // split an agent's spend per CLI rather than labelling a codex
-          // agent's total with whatever the pre-review spent.
-          onUsage: (u) => {
-            usage = { ...u, runtime: rt };
-          },
-          // WHAT THE CLI SAYS IT CAN BE ASKED FOR, AND WHICH CONNECTORS NEED A
-          // LOGIN — the same free fact off the same init event the tab lane
-          // records (2026-09-23). Without it a box that only ever runs agents
-          // taught the app its skills and connectors ONCE, from the startup
-          // probe, and never again: a connector signed into at the box kept
-          // reading "needs authorization" for the life of the process.
-          onInit: (i) => {
-            recordSkills(i.skills);
-            recordMcpServers(i.mcpServers);
-          },
-          onSpawn: (ch) => {
-            child = ch;
-            // The AGENT it serves — what the machine snapshot charges this
-            // child's memory to.
-            workChildren.set(ch, agentId);
-            // …and the registry now counts what the reservation was standing
-            // in for.
-            releaseSlot();
-            // Under the PLACE, the id every reader asks with — the worktree
-            // sweep and `killTargetOk` both key on `a-<agentId>`. Recorded under
-            // the bare agent id it was never read, reported `processes: []`
-            // over a running watcher, and left one dead entry per turn.
-            noteSessionGroup(place, ch.pid);
-            // Keyed by PLACE, because the retire sweep iterates directory names
-            // and a place id IS one. It is what lets a hard stop actually reach
-            // the CLI — see `retireWorkSessions`.
-            agentChildren.set(place, ch);
-          },
-        };
-        out = await runTurn(agentTurnArgs);
-        /**
-         * A RESUME THAT CAME BACK EMPTY, OR WITH ONLY THE CLI SAYING THE
-         * CONVERSATION IS GONE, RUNS ONCE MORE FRESH — the tab lane's rule,
-         * for the tab lane's reason: a pinned id the CLI has since pruned
-         * (or a `--continue` over a directory Claude never spoke in, which an
-         * agent switched between CLIs can reach) would otherwise settle
-         * `nothing` on every turn forever. Same worktree, never a reset.
-         */
-        if (resume && (!(out || '').trim() || resumeConversationLost(out))) {
-          seenThreadId = null;
-          lastAnswer = null;
-          out = await runTurn({ ...agentTurnArgs, resume: false, resumeThreadId: undefined });
-        }
-      } finally {
-        projectTools?.cleanup();
-        /**
-         * THE TAIL, BEFORE THE SETTLE — so the last thing the agent did is on
-         * the record by the time the board is told the turn is over.
-         *
-         * The server deliberately does NOT require a pending turn to accept a
-         * trace batch (a late tail is still that turn's record), so a race here
-         * is survivable rather than lossy; flushing first simply means it
-         * almost never happens. Bounded, and the settle is what matters: an
-         * uplink that will not answer costs the tail and nothing else.
-         */
-        trace.stop();
-        await trace.flush(TRACE_FINAL_FLUSH_MS);
-        if (child) workChildren.delete(child);
-        if (agentChildren.get(place) === child) agentChildren.delete(place);
-        if (ranMarker && rt === 'claude') {
-          try {
-            writeFileSync(ranMarker, '1');
-          } catch {
-            /* a missing marker only costs one un-resumed turn */
-          }
-        }
-        // The thread THIS turn spoke under, pinned so the next card, answer
-        // or merge-resolve resumes it. After the turn, like the tab lane: an
-        // id learned mid-turn is only true once the turn that learned it ends.
-        if (codexThreadMarker && seenThreadId && CODEX_THREAD_RE.test(seenThreadId)) {
-          try {
-            writeFileSync(codexThreadMarker, seenThreadId);
-          } catch {
-            /* best-effort — the next turn runs fresh */
-          }
-        }
-        /**
-         * AN ACTION THAT CHANGES WHAT THE MACHINE WOULD MEASURE MUST CAUSE A
-         * NEW MEASUREMENT — the rule every session settle keeps, and the one
-         * lane that did not. An agent's branch diff, head sha and trailered
-         * commits only refreshed on the ≤60s sweep, so review opened right
-         * after a turn described the branch as it was BEFORE the work.
-         *
-         * Here rather than after the settle POST because the CLI has exited,
-         * so the tree is final — and because a queue that just emptied runs
-         * the project's check next, which may hold this function for ten
-         * minutes. Fire-and-forget on an endpoint that already exists, so no
-         * floor: it must never delay the settle behind it.
-         */
-        void reportSessionWorktree(place).catch(() => {});
-        // …and what it drew to SHOW the person (2026-09-22): uploaded against
-        // the AGENT, so it lands on the agent's page whoever is looking.
-        // Fire-and-forget for the same reason — never delay the settle.
-        void artifacts
-          .report({ placeDir: wt, before: artifactsBefore, agentId, turnId })
-          .catch(() => {});
-      }
-
-      const commits = commitsBetween(wt, before);
-      const res = (lastAnswer && parseTurnResult(lastAnswer)) || parseTurnResult(out);
-      /**
-       * A LIMIT IS ONLY A LIMIT WHEN THE TURN PRODUCED NOTHING.
-       *
-       * `limitLine` is a literal phrase match over the CLI's output, and the
-       * output of a successful turn contains whatever the agent wrote — so a
-       * card about rate limiting, or a summary mentioning one, parked every
-       * agent on the project. Gating on "the turn declared no outcome" is what
-       * makes the match mean what it says: the CLI failed and this is the
-       * sentence it failed with.
-       */
-      const limit = res ? null : limitLine(out);
-      if (res) setRuntimeLimit(PROJECT_ID, rt, null);
-      if (limit) {
-        setRuntimeLimit(PROJECT_ID, rt, limit);
-        // Every agent ON THIS CLI parks, because that account is shared: one
-        // hitting the limit means all of them have. Named since 2026-09-24 —
-        // a machine can hold a Claude login and a Codex login, and a Codex
-        // limit is no reason to stop the Claude agents. The turn itself is
-        // reported as `nothing` — it did not deliver and it did not ask.
-        await postAgentParked(limit, rt);
-        await postAgentTurn({
-          turnId,
-          outcome: 'nothing',
-          answer: limit,
-          ...(usage ? { usage } : {}),
-          branch,
-          worktree: wt,
-        });
-        return;
-      }
-
-      if (!res) {
-        await postAgentTurn({
-          turnId,
-          outcome: 'nothing',
-          // The CLI's own words when it produced any. A turn that explained why
-          // it stopped is far more use than "the agent stopped".
-          answer: out.trim()
-            ? envScrub(out).slice(-1500)
-            : 'the turn produced no output on the machine — its CLI may be signed out',
-          ...(commits.length ? { commits } : {}),
-          ...(usage ? { usage } : {}),
-          branch,
-          worktree: wt,
-        });
-        return;
-      }
-      /**
-       * A DESIGN OR RESEARCH CARD IS NOT DELIVERED UNTIL ITS ARTIFACT EXISTS
-       * (0.97.0) — measured, never taken on the agent's word.
-       *
-       * Its whole product is one file under `.flowviant/artifacts/`: a `.html`
-       * mockup for design, a `.md` write-up for research. A turn that says
-       * "delivered" without having written one would land the agent in Review
-       * with nothing to look at and a summary describing a page that does not
-       * exist — so it settles `nothing` with the measured sentence, and the
-       * agent lands in Stuck with a true reason instead.
-       *
-       * WHAT COUNTS: on a TASK turn, only what the scan found NEW OR CHANGED
-       * this turn (`changedArtifacts` against the snapshot taken before the
-       * spawn) — a second design card in the same agent must not pass on the
-       * first card's page. On a HUMAN turn (an answer, a send-back) a matching
-       * file already standing in the directory also counts: "keep it as it
-       * is" is a legitimate answer to a question the agent asked after
-       * drawing, and the turn did not have to rewrite the page to deliver it.
-       *
-       * …AND ON A REDO (2026-09-23): a TASK turn re-running a card this agent
-       * already delivered, which is what a send-back's "Needs work" queues —
-       * the human turn in front of it usually rewrote the mockup already, so
-       * the task turn that follows truthfully says "revised last turn" with
-       * nothing new to write, and the task rule sent it to Stuck with a false
-       * sentence. The server marks such a job `redo: true` (a link delivered
-       * before, or carrying a `needs_work` verdict), and then a standing match
-       * counts, as it does for a human turn. No floor: an older server never
-       * sends the key, and absent keeps the stricter task rule.
-       *
-       * Commits are still reported if any exist — the posture prevents them,
-       * and a report never lies by omission about what is on the branch.
-       */
-      if (res.outcome === 'delivered' && taskKind !== 'code') {
-        const want = taskKind === 'design' ? /\.html?$/i : /\.md$/i;
-        const standing = scanArtifacts(wt);
-        const wrote = changedArtifacts(artifactsBefore, standing).some((e) => want.test(e.name));
-        const present =
-          wrote || ((job.kind !== 'task' || job.redo === true) && standing.some((e) => want.test(e.name)));
-        if (!present) {
-          await postAgentTurn({
+        await runAgentTurnInPlace(job, { turnId, agentId, place, releaseSlot, postAgentTurn: settleOnce, measured });
+      } catch (error) {
+        if (settled) return;
+        const commits = measured.wt ? commitsBetween(measured.wt, measured.before) : [];
+        await postAgentTurn(
+          failedTurnSettlement({
             turnId,
-            outcome: 'nothing',
-            answer:
-              taskKind === 'design'
-                ? 'the turn ended without writing a mockup under .flowviant/artifacts/'
-                : 'the turn ended without writing a write-up under .flowviant/artifacts/',
-            ...(commits.length ? { commits } : {}),
-            ...(usage ? { usage } : {}),
-            branch,
-            worktree: wt,
-          });
-          return;
-        }
+            error,
+            commits,
+            usage: measured.usage,
+            branch: measured.branch,
+            wt: measured.wt,
+          })
+        );
       }
-      const reply = await postAgentTurn({
-        turnId,
-        outcome: res.outcome,
-        answer: envScrub(res.answer ?? '').slice(0, 8000),
-        ...(commits.length ? { commits } : {}),
-        // SCRUBBED like the answer beside it: a raised card lands in the
-        // project doc every member reads, and a brief quoting the `.env` the
-        // agent just read ("value sk_live_… is logged in pay.ts") went out
-        // verbatim while the same value in the summary was redacted.
-        ...(res.raised?.length
-          ? {
-              raised: res.raised.map((r) => ({
-                title: envScrub(r.title).slice(0, 300),
-                ...(r.brief ? { brief: envScrub(r.brief).slice(0, 2000) } : {}),
-              })),
-            }
-          : {}),
-        ...(usage ? { usage } : {}),
-        /**
-         * THE AGENT'S RUNNING ACCOUNT OF THIS BRANCH (2026-09-22).
-         *
-         * The owner: "we should add a brief summary of what the agent has done
-         * overall at the top that updates." A RELAY — the agent wrote it in its
-         * own final JSON object and nothing here composes, narrows or infers
-         * one. It rides only this settle, which is the one that follows a
-         * PARSED result: the two `nothing` settles above it come from a turn
-         * that declared no outcome at all, so there is no account to carry and
-         * inventing one would be the machine speaking for the agent.
-         *
-         * SCRUBBED BEFORE IT IS CUT, the order that matters and the one the
-         * check's output lane learned the expensive way: `envScrub` replaces
-         * EXACT values, so a paragraph capped first hands the scrub a
-         * credential already cut in half — it matches nothing and the surviving
-         * prefix ships. `parseTurnResult` trims it and bounds it for absurdity
-         * at 8000, DELIBERATELY above the 1000 below, so this slice is the
-         * first one a value of any interest meets and the scrub has already
-         * run when it does. The first cut of this feature bounded the parser at
-         * 1000 as well, which read identically and quietly put the cap first.
-         *
-         * OMITTED WHEN THE TURN DID NOT WRITE ONE, never sent empty. Absence is
-         * the server's signal to KEEP the last account that was true; an empty
-         * string would blank the head because a model dropped a key.
-         */
-        ...(res.progress ? { progress: envScrub(res.progress).slice(0, 1000) } : {}),
-        branch,
-        worktree: wt,
-      });
-      // The queue just emptied. Run the project's own check and the AI
-      // pre-review HERE, in the worktree we are already standing in and still
-      // hold the lock on — see `runReviewEntry`.
-      if (reply?.review === true) await runReviewEntry(agentId, wt, job.agentName);
     });
     /**
      * …AND THEN PUBLISH, IF THE PROJECT PUBLISHES.
@@ -1002,45 +231,9 @@ export function createWorkAgentTurns({
     }
   };
 
-  const lastAgentBeat = new Map(); // agentId -> last activity POST, ms
-
-  const postAgentParked = async (reason, runtime) => {
-    try {
-      await fetch(AGENT_PARKED_URL, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${FLEET_TOKEN}`,
-          'User-Agent': USER_AGENT,
-          'Content-Type': 'application/json',
-        },
-        signal: AbortSignal.timeout(15_000),
-        // `runtime` scopes the park to that CLI's agents; a server that does
-        // not know the key parks every agent, which is what it always did.
-        body: JSON.stringify({ reason, ...(runtime ? { runtime } : {}) }),
-      });
-    } catch {
-      /* the next turn will hit the same limit and try again */
-    }
-  };
-
   const processAgentTurnJobs = (jobs) => {
     const list = Array.isArray(jobs) ? jobs : [];
-    if (agentReported.size) {
-      // The roster is the held bodies' clock: an offered turn is still pending
-      // server-side and worth retrying; one the roster stopped naming was
-      // settled or expired, and holding its body past a generous grace would
-      // grow this map for the life of the process. The server's own expiry is
-      // the true bound — the grace only covers its POST racing a final offer.
-      const offered = new Set(list.map((j) => String(j?.id || '')));
-      const now = Date.now();
-      for (const [id, held] of agentReported) {
-        if (offered.has(id)) held.at = now;
-        else if (now - held.at > AGENT_REPORT_GRACE_MS) {
-          agentReported.delete(id);
-          agentRejectedUntil.delete(id);
-        }
-      }
-    }
+    pruneHeldReports(list);
     /** One deferral line per tick, however many turns were offered. */
     let saidPressure = false;
     for (const job of list.slice(0, 4)) {