flowviant 0.125.4 → 0.125.6

package/bin/lib/workAgentTurnExecution.mjs

@@ -6,8 +6,9 @@ import { finishRepositoryDelivery, allResolutionsCommitted } from './repositoryD
  * decides WHICH turns run and makes sure each one is settled exactly once; this
  * runs one, inside the place lock the lane already holds — the begun-guard
  * (workAgentTurnBegun.mjs), the worktree and its branch facts, the kind's
- * refusals, the prompt, the CLI and its resume, the trace and pulse relays,
- * the markers and the re-measurement after it exits — then hands the
+ * refusals, the prompt, the CLI and its resume (whose markers are
+ * workAgentResume.mjs's since 2026-10-18), the trace and pulse relays, and the
+ * re-measurement after it exits — then hands the
  * measurements to the one settlement decision (workAgentTurnOutcome.mjs) and
  * posts the body that decision chose.
  *
@@ -17,38 +18,39 @@ import { finishRepositoryDelivery, allResolutionsCommitted } from './repositoryD
  * answered. `measured` is the same bargain the other way: the branch facts and
  * the spend, written here as they are learned, read by that catch.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { PROJECT_ID } from './config.mjs';
 import { setRuntimeLimit } from './daemonState.mjs';
 import { gitOrNull } from './git.mjs';
+import { turnCommits } from './turnReceipts.mjs';
+import { addUsage } from './turnUsage.mjs';
 import { stashCard } from './agentCards.mjs';
 import { c } from './ui.mjs';
 import { runTurn } from './runTurn.mjs';
 import { killGroup } from './processGroup.mjs';
-import { SYSTEM_AGENT_FOR, AGENT_TASK_KICKOFF, AGENT_TASK_SPEC, AGENT_HUMAN_KICKOFF, withProjectContext } from './prompts.mjs';
+import { AGENT_TASK_SPEC } from './prompts.mjs';
+import { agentKickoff, agentFollowupKickoff, agentTurnSystem } from './workAgentTurnShape.mjs';
 import { AGENT_TASK_KINDS, agentTaskKindOf, unknownAgentTaskKind } from './agentTaskKinds.mjs';
 import { knowledgeDirFor } from './knowledgeFiles.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { canRun, runtimeById } from './runtimes.mjs';
 import { toolEventOf, CLAUDE_TOOL_PROSE_KINDS, scrubNativeText } from './runtimeEvents.mjs';
 import { makeTraceRelay } from './trace.mjs';
-import { mcpJsonServerNamesAbove, readBaseTools, prepareAgentTools } from './projectTools.mjs';
-import { TURN_PROFILES } from './turnProfile.mjs';
-import { postureToolsNote } from './postureTools.mjs';
+import { prepareCardTools } from './workAgentTools.mjs';
 import { runTurnResumingOnce } from './resumeLost.mjs';
-import { INTERNAL_WAIT_CONTRACT, runAgentWithInternalWaits } from './agentInternalWait.mjs';
-import { CODEX_THREAD_RE } from './workSessionRuntime.mjs';
+import { runAgentWithInternalWaits } from './agentInternalWait.mjs';
 import { brainFor } from './workBrain.mjs';
 import { refreshRestartBase } from './workAgentRecovery.mjs';
 import { begunTurnRefusal } from './workAgentTurnBegun.mjs';
-import { agentTurnSettlement } from './workAgentTurnOutcome.mjs';
+import { agentTurnSettlement, interruptedTurnSettlement } from './workAgentTurnOutcome.mjs';
 import { ensureArtifactDir, ensureFenceScratch } from './artifacts.mjs';
 import { agentBrowserHome } from './noWindowEnv.mjs';
-import { CLAUDE_SESSION_RE, RESUME_MARKERS } from './conversationIds.mjs';
+import { agentTurnResume } from './workAgentResume.mjs';
 import { createDeliveryReporter } from './workDelivery.mjs';
 import { createLiveMessages } from './workLiveMessages.mjs';
 import { createOrchestrator } from './orchestrator.mjs';
-import { ORCHESTRATOR_CONTRACT } from './orchestratorPrompt.mjs';
+import { claudeOrchestrationSafe } from './orchestratorHooks.mjs';
+import { codexSubagentsSafe } from './runtimeCodex.mjs';
+import { measuredRuntimeVersion } from './runtimeDetection.mjs';
 
 export function createAgentTurnExecution({
   admit,
@@ -82,38 +84,6 @@ export function createAgentTurnExecution({
 
   const lastAgentBeat = new Map(); // agentId -> last activity POST, ms
 
-  /** 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.
-     */
-    const out = gitOrNull(['log', '--format=%H', '--no-merges', `${from}..HEAD`, '--not', baseRef()], wt);
-    return out?.split('\n').map((x) => x.trim()).filter(Boolean).slice(0, 50) ?? [];
-  };
-
   /**
    * The turn, run inside its place's writer lock (the lane takes it). `turnId`,
    * `agentId` and `place` are the lane's own readings of the job, handed down
@@ -179,6 +149,7 @@ export function createAgentTurnExecution({
     measured.branch = branch;
 
     const rt = job.runtime || 'claude';
+    const liveInput = runtimeById(rt)?.liveInput === true;
     /**
      * WHAT THIS CARD HANDS BACK, AND THE POSTURE THAT FOLLOWS (0.97.0).
      *
@@ -279,64 +250,9 @@ export function createAgentTurnExecution({
       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 claudeMarker = rt === 'claude' ? sessionMetaPath(wt, RESUME_MARKERS.claude, agentId) : null;
-    let claudeResumeId = null;
-    try { const id = readFileSync(claudeMarker, 'utf8').trim(); if (CLAUDE_SESSION_RE.test(id)) claudeResumeId = id; } catch { /* unknown */ }
-    const resume =
-      rt === 'codex'
-        ? Boolean(codexResumeId)
-        : rt === 'claude' && (Boolean(claudeResumeId) || Boolean(ranMarker && existsSync(ranMarker)));
-    /**
-     * …AND THE HOME THAT THREAD IS FILED UNDER, KEPT PER AGENT (2026-09-29).
-     *
-     * Codex's thread index records each rollout under the CODEX_HOME the turn
-     * ran with, as that path — not the personal store the link leads to — so
-     * the per-turn home in /tmp every turn used to get died with its turn and
-     * took the pinned thread with it: the next card's `resume` failed "no
-     * rollout found" and the agent went to Stuck. Beside the thread marker,
-     * in the worktree's private git dir: outside the working tree (never
-     * committed, never seen by `git add -A`), refreshed by every turn and
-     * removed only with the worktree, when the agent retires and its threads
-     * stop mattering. One agent runs one turn at a time (its place's writer
-     * lock), so no two turns refresh it at once. Null (no git dir to hold it)
-     * is the per-turn home again, and a lost resume then runs once fresh.
-     */
-    const codexAgentHome =
-      rt === 'codex' ? sessionMetaPath(wt, 'flowviant-agent-codex-home', agentId) : null;
+    // Which conversation this turn resumes, and the kept Codex home it is
+    // filed under: the agent's resume across turns (workAgentResume.mjs).
+    const agentResume = agentTurnResume({ rt, wt, agentId, sessionMetaPath });
 
     /**
      * THE TURN'S FILES, ON DISK BEFORE THE PROMPT NAMES THEM (0.112.0) — the
@@ -370,11 +286,11 @@ export function createAgentTurnExecution({
      * 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 — the
-     * card's discussion included (0.106.0): both are handed the same
-     * `job.cardThread`, and the builder prints it inside the spec — and the
-     * card's files after it (0.112.0), fetched just above.
+     * ONE SPEC BUILDER (`AGENT_TASK_SPEC`) shared with the kickoff
+     * (workAgentTurnShape.mjs), so what the reviewer reads is byte-identical
+     * to what the agent read — the card's discussion included (0.106.0): both
+     * are handed the same `job.cardThread`, and the builder prints it inside
+     * the spec — and the card's files after it (0.112.0), fetched just above.
      * Failure is swallowed inside `stashCard`: a note about a turn may never
      * cost the turn.
      */
@@ -386,6 +302,12 @@ export function createAgentTurnExecution({
       );
     }
 
+    // ORCHESTRATED ONLY WHERE THE CLI CAN BE GATED (2026-10-17). v2 reaches every
+    // job at the floor; a fenced card or a CLI below its measured floor (unknown
+    // included) has no controller, so no marker: its notes fold on receipt.
+    const codexVersion = rt === 'codex' ? measuredRuntimeVersion('codex')?.version : undefined;
+    const orchestrating = job.orchestrationVersion === 2 && posture === 'build' &&
+      (rt === 'claude' ? claudeOrchestrationSafe(measuredRuntimeVersion('claude')?.version) : rt === 'codex' && codexSubagentsSafe(codexVersion));
     /**
      * THE WHOLE STREAM, not just its latest line — see trace.mjs.
      *
@@ -398,12 +320,12 @@ export function createAgentTurnExecution({
       agentId,
       turnId,
       post: postAgentTrace,
-      orchestrationVersion: job.orchestrationVersion,
+      orchestrationVersion: orchestrating ? 2 : undefined,
       scrub: envScrub,
     });
     // A live Send can choose its path as soon as the CLI starts, including a
     // silent solo turn. Do not leave a two-second first-flush race at spawn.
-    if (job.orchestrationVersion === 2) await trace.flush(1_000);
+    if (orchestrating) await trace.flush(1_000);
     /**
      * Prose the structured event will carry anyway, dropped so a read does
      * not render twice — but ONLY on a runtime whose stream reaches
@@ -479,122 +401,42 @@ export function createAgentTurnExecution({
     let projectTools = null;
     let orchestrator = null;
     try {
-      const orchestrated = job.orchestrationVersion === 2;
-      if (orchestrated && posture === 'build' && ['claude', 'codex'].includes(rt)) {
+      if (orchestrating) {
         orchestrator = await createOrchestrator({ turnId, runtime: rt, trace, admit,
-          notify: message => { if (rt === 'claude') run.live?.inject(message); },
+          // Whether the words reached the CLI; Codex reads its inbox from hooks.
+          notify: message => liveInput ? run.live?.inject(message) === true : false,
           taken: id => run.live?.onTaken(id) });
       }
-      // A turn reads the base ref afresh. Changes the agent has made to its
-      // own worktree cannot silently change the next turn's tools.
-      const sources = repositoryRun?.sources ?? [];
-      const source = sources.find((r) => r.wt === wt);
-      const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef());
-      for (const other of sources.filter((r) => r !== source)) {
-        const base = readBaseTools(other.repoRoot, other.baseRef);
-        snapshot.instructions.push(...[...base.instructions, ...base.skillFiles].map((file) => ({ ...file, path: `repositories/${other.folder}/${file.path}` })));
-      }
-      projectTools = prepareAgentTools(snapshot, rt, process.env, wt, { codexHome: codexAgentHome, turnServers: {
-        ...(repositoryRun?.tool ? { card_repositories: repositoryRun.tool.config } : {}),
-        ...(orchestrator ? { card_orchestrator: orchestrator.config } : {}),
-      } });
-      const mountsProjectMcp = TURN_PROFILES[posture]?.projectMcp === true && (rt === 'claude' || rt === 'codex');
-      // A fenced posture on a runner that ignores its own file there (Codex's
-      // `--ignore-user-config`) takes the servers as `fencedMount` instead.
-      const fencedMount = mountsProjectMcp && posture !== 'build' ? projectTools.fencedMount : null;
-      // THE MACHINE'S OWN SERVERS ON CLAUDE (2026-10-11, the owner): the turn
-      // is not strict, and every `.mcp.json` name from the worktree up is
-      // disabled so only the base copy speaks for the project. Null (an
-      // unboundable walk) mounts strictly: the base copy alone.
-      const claudeDisabled = mountsProjectMcp && rt === 'claude' ? mcpJsonServerNamesAbove(wt) : null;
-      // What this card's posture withholds, said to the agent — with the
-      // servers it did and did not mount, and why — so it relays the fence
-      // instead of inventing a setting (postureTools.mjs). Empty for a code card.
-      const toolsNote = postureToolsNote({
-        posture,
-        runtime: rt,
-        mounted: !mountsProjectMcp ? [] : fencedMount ? fencedMount.mounted : projectTools.mcpServers,
-        machine: mountsProjectMcp && (rt === 'codex' || claudeDisabled != null),
-        unmounted: [...projectTools.mcpUnmounted.map((u) => ({ ...u, source: 'project' })), ...(fencedMount ? fencedMount.unmounted : [])],
-      });
+      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
+      projectTools = tools.projectTools;
+      const { toolsNote } = tools;
       const agentTurnArgs = {
-        ...((rt === 'claude' || orchestrator) ? { liveMessages: (run.live = makeLiveMessages({
+        ...((liveInput || orchestrator) ? { liveMessages: (run.live = makeLiveMessages({
           scope: 'agent', turnId, cwd: wt, sessionMetaPath, interrupted: () => run.interrupted,
           observe: message => orchestrator?.note(message),
           ...(rt === 'codex' ? { nativeIds: () => null } : {}),
           format: async (followup) => {
             orchestrator?.note(followup);
             const attached = followup.attachments?.length ? await fetchAgentFiles(wt, followup.attachments.map((file) => ({ ...file, from: 'message' }))) : { message: [], card: [] };
-            return AGENT_HUMAN_KICKOFF({ agentName: job.agentName, message: followup.body + (followup.libraryPrompt ?? '') + (orchestrator ? `\nMessage id: ${followup.id}. Choose and report its route with card_orchestrator.route_message.` : ''),
-              askedByName: followup.askedByName, task: job.task, cardThread: job.cardThread,
-              investigationContext: job.investigationContext, researchContext: job.researchContext,
-              messageFiles: attached.message, cardFiles: files.card, position: job.position ?? 1, total: job.total ?? 1 });
+            return agentFollowupKickoff(job, followup, { messageFiles: attached.message, cardFiles: files.card, orchestrated: Boolean(orchestrator) });
           },
         })) } : {}),
-        prompt:
-          job.kind === 'task' && job.task
-            ? AGENT_TASK_KICKOFF({
-                agentName: job.agentName,
-                task: job.task,
-                // The card's discussion (0.106.0), printed inside THE CARD by
-                // the same builder the stash above wrote down — and the files
-                // on it (0.112.0), after it, the same way.
-                resumeBody: job.body,
-                investigationContext: job.investigationContext,
-                researchContext: job.researchContext,
-                cardThread: job.cardThread,
-                cardFiles: files.card,
-                position: job.position ?? 1,
-                total: job.total ?? 1,
-              })
-            : AGENT_HUMAN_KICKOFF({
-                agentName: job.agentName,
-                // INTERRUPT NOW: the previous run was stopped to send this.
-                interrupted: job.interrupted === true,
-                message: job.body ?? '',
-                investigationContext: job.investigationContext,
-                researchContext: job.researchContext,
-                askedByName: job.askedByName,
-                task: job.task,
-                // The discussion on the one card this message is about, in a
-                // fence of its own after the person's words (0.106.0).
-                cardThread: job.cardThread,
-                // The files (0.112.0): the person's inside their words, the
-                // card's at the foot of its discussion.
-                messageFiles: files.message,
-                cardFiles: files.card,
-                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.
-        // Spoken to the CLI that runs it (0.115.0): a mockup on Codex is
-        // told it is Codex, never Claude.
-        system: withProjectContext(SYSTEM_AGENT_FOR(taskKind, runtimeById(rt)?.label, { prerequisitesAccepted: job.prerequisitesAccepted === true }), {
-          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(),
-        }) + (toolsNote ? `\n\n${toolsNote}` : '') + (artifactInstructions ? `\n\n${artifactInstructions}` : '') + `\n\n${INTERNAL_WAIT_CONTRACT}` + (projectTools.instructions ? `\n\n${projectTools.instructions}` : '') + (repositoryRun ? `\n\n${repositoryRun.note}\nRepository command argv: ${JSON.stringify([repositoryRun.tool?.config.command, ...(repositoryRun.tool?.config.args.slice(0, -1) ?? []), "__repository", "<name>"])}` : '') + (orchestrator ? `\n\n${ORCHESTRATOR_CONTRACT}` : ''),
+        // The kickoff and the system prompt, composed by the agent lane's
+        // shape (workAgentTurnShape.mjs) from what this run measured.
+        prompt: agentKickoff(job, { cardFiles: files.card, messageFiles: files.message }),
+        system: agentTurnSystem({ taskKind, runtimeLabel: runtimeById(rt)?.label, prerequisitesAccepted: job.prerequisitesAccepted === true, knowledgeDir: knowledgeDirFor(repoRoot), artifactsAccepted: getArtifactsAccepted(), toolsNote, artifactInstructions, toolInstructions: projectTools.instructions, repositoryRun, orchestrated: Boolean(orchestrator) }),
         agentTools: projectTools,
         writableDirs: repositoryRun?.writableDirs,
-        ...((projectTools.codexHome || fencedMount || repositoryRun?.tool || orchestrator) ? { mcpEnv: { ...(projectTools.codexHome ? { CODEX_HOME: projectTools.codexHome } : {}), ...(fencedMount?.env ?? {}), ...(repositoryRun?.tool?.env ?? {}), ...(orchestrator?.env ?? {}) } } : {}),
+        ...((tools.envNeeded || repositoryRun?.tool || orchestrator) ? { mcpEnv: { ...tools.env, ...(repositoryRun?.tool?.env ?? {}), ...(orchestrator?.env ?? {}) } } : {}),
         orchestration: Boolean(orchestrator),
+        ...(rt === 'codex' ? { codexVersion } : {}),
         // NOBODY IS AT THIS SCREEN (2026-09-29): no display, BROWSER=none, and
         // a browser profile of the agent's own, kept beside its Codex home —
         // so a Chrome it starts to look at its page never reaches the
         // person's (noWindowEnv.mjs).
         browserHome: agentBrowserHome(sessionMetaPath, wt, agentId),
-        // Reviewed project servers and the machine's configured servers, on
-        // initial cards, answers and review iterations alike.
-        ...(mountsProjectMcp && rt === 'claude'
-          ? {
-              mcpArgs: [...(claudeDisabled ? [] : ['--strict-mcp-config']), '--mcp-config', projectTools.mcpPath],
-              projectMcpServers: projectTools.mcpServers,
-              ...(claudeDisabled ? { machineMcp: claudeDisabled } : {}),
-            }
-          : fencedMount ? { mcpArgs: fencedMount.args } : {}),
+        // What the card mounts, as its runner takes it (workAgentTools.mjs).
+        ...tools.mountArgs,
         knowledgeDir: knowledgeDirFor(repoRoot),
         // The kind's posture, as the one turn profile (turnProfile.mjs):
         // build for code, the fenced design/research postures otherwise.
@@ -604,16 +446,17 @@ export function createAgentTurnExecution({
         onSpawnResult: result => orchestrator?.spawnResult(result),
         cwd: wt,
         runtime: rt,
-        resume,
-        resumeThreadId: codexResumeId || claudeResumeId || undefined,
+        resume: agentResume.resume,
+        resumeThreadId: agentResume.resumeThreadId,
         onInit: (init) => {
           orchestrator?.root(init.sessionId);
-          if (claudeMarker && CLAUDE_SESSION_RE.test(init.sessionId ?? ''))
-            try { writeFileSync(claudeMarker, init.sessionId); } catch { /* best effort */ }
+          // A server that did not connect, as the CLI said (unknown: nothing).
+          trace.mcpStatus(init.mcpServers);
+          agentResume.sawSession(init.sessionId);
         },
         onThreadId: (id) => {
           orchestrator?.root(id);
-          seenThreadId = String(id ?? '').trim() || seenThreadId;
+          agentResume.sawThread(id);
         },
         onAnswer: (t) => {
           lastAnswer = t;
@@ -757,7 +600,7 @@ export function createAgentTurnExecution({
           resume: rt === 'codex' && posture === 'research' ? false : args.resume,
           runtime: rt,
           beforeFresh: () => {
-            seenThreadId = null;
+            agentResume.forgetThread();
             lastAnswer = null;
             model = null;
           },
@@ -775,13 +618,10 @@ export function createAgentTurnExecution({
           const counted = usage;
           return runCli({
             ...agentTurnArgs, prompt, liveContinuation: true,
-            onUsage: (next) => agentTurnArgs.onUsage(Object.fromEntries(
-              ['input', 'output', 'cacheCreate', 'cacheRead'].map((k) =>
-                [k, (counted?.[k] ?? 0) + (next?.[k] ?? 0)])
-            )),
+            onUsage: (next) => agentTurnArgs.onUsage(addUsage(counted, next)),
             writableDirs: repositoryRun.sourcesNow().filter((r) => r.wt !== wt).map((r) => r.wt),
             resume: true,
-            resumeThreadId: seenThreadId ?? agentTurnArgs.resumeThreadId,
+            resumeThreadId: agentResume.threadNow() ?? agentTurnArgs.resumeThreadId,
           });
         },
       });
@@ -829,23 +669,9 @@ export function createAgentTurnExecution({
       }
       for (const ch of spawnedChildren) workChildren.delete(ch);
       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 */
-        }
-      }
+      // The ran marker and the thread this turn spoke under, written now
+      // that the turn is over (workAgentResume.mjs).
+      agentResume.persist();
       /**
        * AN ACTION THAT CHANGES WHAT THE MACHINE WOULD MEASURE MUST CAUSE A
        * NEW MEASUREMENT — the rule every session settle keeps, and the one
@@ -866,7 +692,7 @@ export function createAgentTurnExecution({
     }
 
 
-    const commits = repositoryRun ? [...new Set(repositoryRun.receipts().map((r) => r.sha))].slice(0, 50) : commitsBetween(wt, before);
+    const commits = turnCommits({ repositoryReceipts: repositoryRun?.receipts, wt, before, baseRef });
     /**
      * A PERSON INTERRUPTED IT (Interrupt now). Whatever the CLI printed was
      * cut off, so there is no outcome to read: the turn reports `interrupted`
@@ -877,17 +703,7 @@ export function createAgentTurnExecution({
      */
     if (run.interrupted) {
       measured.ranCli = spawnedChildren.size > 0;
-      await postAgentTurn({
-        turnId,
-        outcome: 'nothing',
-        interrupted: true,
-        ran: spawnedChildren.size > 0,
-        commits,
-        ...(usage ? { usage } : {}),
-        ...(model ? { model } : {}),
-        ...(branch ? { branch } : {}),
-        worktree: wt,
-      });
+      await postAgentTurn(interruptedTurnSettlement({ turnId, ran: spawnedChildren.size > 0, commits, usage, model, branch, wt }));
       return;
     }
     // WHAT THE TURN REPORTS is one decision, off what was measured here
@@ -926,5 +742,5 @@ export function createAgentTurnExecution({
     } finally { await repositoryRun?.tool?.close(); }
   };
 
-  return { runAgentTurnInPlace, commitsBetween };
+  return { runAgentTurnInPlace };
 }

package/bin/lib/workAgentTurnOutcome.mjs

@@ -16,6 +16,11 @@
  * and settles once, so a crash in the run can never leave a turn unsettled to
  * be re-offered and re-run on the operator's account.
  *
+ * `interruptedTurnSettlement` is the sixth (2026-10-18, the SOLID pass): a turn
+ * a person stopped, where no outcome is read. The run and the lane's catch
+ * both send it — the catch when the stopped run then threw — and they had
+ * already drifted apart, so its body is built here once.
+ *
  * `agentTurnSettlement` returns `{ res, limit, body, final }`; the caller posts
  * `body` through the one turn-done wire, clears or sets the machine's limit off
  * `res`/`limit`, parks on `limit`, and runs the review-entry beat only after a
@@ -27,6 +32,7 @@ import { changedArtifacts, scanArtifacts } from './artifacts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { usableImageArtifact } from './imageArtifact.mjs';
 import { withoutTurnDeclaration } from './turnDeclaration.mjs';
+import { ANSWER_DELIVERED_USES, researchUseOf, withResearchHeader } from './researchUse.mjs';
 
 export function agentTurnSettlement({ turnId, job, kind, out, lastAnswer, usage, model = null, commits, artifactsBefore, branch, wt }) {
   const res = (lastAnswer && parseTurnResult(lastAnswer)) || parseTurnResult(out);
@@ -117,9 +123,9 @@ export function agentTurnSettlement({ turnId, job, kind, out, lastAnswer, usage,
    */
   // Existing document deliveries default to the Markdown proof. Only an
   // explicit temporary-use declaration can deliver through the stored answer.
-  const briefUse = /^Research intended use: (tasks|context|document)(?:\r?\n|$)/.exec(job.task?.brief ?? '')?.[1];
+  const briefUse = researchUseOf(job.task?.brief);
   const researchUse = kind.posture === 'research' ? briefUse ?? res.researchUse : null;
-  const temporaryResearch = ['tasks', 'context'].includes(researchUse);
+  const temporaryResearch = ANSWER_DELIVERED_USES.includes(researchUse);
   if (res.outcome === 'delivered' && temporaryResearch && !res.answer?.trim()) {
     return report({ turnId, outcome: 'nothing', answer: 'The research turn returned no findings.', branch, worktree: wt });
   }
@@ -154,7 +160,7 @@ export function agentTurnSettlement({ turnId, job, kind, out, lastAnswer, usage,
       ...(prerequisite && !cannotRequest ? { prerequisite } : {}),
       outcome: res.outcome,
       answer: cannotRequest ?? envScrub(kind.posture === 'research' && researchUse
-        ? `Research intended use: ${researchUse}\n\n${res.answer ?? ''}` : res.answer ?? ''),
+        ? withResearchHeader(researchUse, res.answer ?? '') : res.answer ?? ''),
       ...(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
@@ -235,3 +241,24 @@ export function failedTurnSettlement({ turnId, error, commits = [], usage = null
     ...(wt ? { branch, worktree: wt } : {}),
   };
 }
+
+/**
+ * A PERSON INTERRUPTED IT (Interrupt now), so there is no outcome to read:
+ * whatever the CLI printed was cut off. What was measured rides along — the
+ * commits it made, its spend, the model it ran on, the branch and the
+ * worktree — and nothing measured is nothing claimed. `ran` is whether its
+ * CLI started at all.
+ */
+export function interruptedTurnSettlement({ turnId, ran, commits, usage = null, model = null, branch = null, wt = null }) {
+  return {
+    turnId,
+    outcome: 'nothing',
+    interrupted: true,
+    ran,
+    commits,
+    ...(usage ? { usage } : {}),
+    ...(model ? { model } : {}),
+    ...(branch ? { branch } : {}),
+    ...(wt ? { worktree: wt } : {}),
+  };
+}

package/bin/lib/workAgentTurnShape.mjs

@@ -0,0 +1,90 @@
+/**
+ * AN AGENT TURN'S PROMPT PAIR — its kickoff, a live message's follow-up and
+ * its system prompt (pure, 2026-10-18, the SOLID pass). The twin of
+ * workTurnShape.mjs, which is the same thing for a tab.
+ *
+ * Split out of workAgentTurnExecution.mjs, which composed all three inline in
+ * the turn: two AGENT_HUMAN_KICKOFF argument bags spelling the same ten
+ * fields, the task kickoff beside them, and a system prompt of eight sections
+ * on one line. The copies had already drifted: investigationContext reached
+ * the task and human kickoffs on 2026-10-12, the follow-up written two days
+ * later went without it, and live messages carried less context than the
+ * first prompt until 2026-10-15 added it beside researchContext at all three
+ * sites. So the fields every kickoff shares are spelled once (`shared`), and
+ * the next job context key is one edit here.
+ *
+ * ONE SPEC BUILDER (`AGENT_TASK_SPEC`) is shared by the stash the run writes
+ * before the CLI and the kickoff here, so what the reviewer reads is
+ * byte-identical to what the agent read — the card's discussion included
+ * (0.106.0): both are handed the same `job.cardThread`, and the builder
+ * prints it inside the spec — and the card's files after it (0.112.0).
+ *
+ * Pure: the run measures (the files, the roster's answers, the tools note)
+ * and hands the values in; nothing here reads a disk or a clock.
+ */
+import { AGENT_TASK_KICKOFF, AGENT_HUMAN_KICKOFF, SYSTEM_AGENT_FOR, withProjectContext } from './prompts.mjs';
+import { INTERNAL_WAIT_CONTRACT } from './agentInternalWait.mjs';
+import { ORCHESTRATOR_CONTRACT } from './orchestratorPrompt.mjs';
+
+/** What every kickoff of this job is handed: the agent, the card and its
+ *  discussion, the job's context handoffs, the card's files, the place in
+ *  the run. */
+const shared = (job, cardFiles) => ({
+  agentName: job.agentName,
+  task: job.task,
+  cardThread: job.cardThread,
+  investigationContext: job.investigationContext,
+  researchContext: job.researchContext,
+  cardFiles,
+  position: job.position ?? 1,
+  total: job.total ?? 1,
+});
+
+/** The turn's first prompt: the card, on a task turn; the person's words
+ *  otherwise. `cardFiles` and `messageFiles` are the files already on disk. */
+export const agentKickoff = (job, { cardFiles, messageFiles }) =>
+  job.kind === 'task' && job.task
+    ? AGENT_TASK_KICKOFF({
+        // The card's discussion (0.106.0), printed inside THE CARD by
+        // the same builder the run's stash wrote down — and the files
+        // on it (0.112.0), after it, the same way.
+        ...shared(job, cardFiles),
+        resumeBody: job.body,
+      })
+    : AGENT_HUMAN_KICKOFF({
+        // The discussion on the one card this message is about, in a
+        // fence of its own after the person's words (0.106.0).
+        ...shared(job, cardFiles),
+        // INTERRUPT NOW: the previous run was stopped to send this.
+        interrupted: job.interrupted === true,
+        message: job.body ?? '',
+        askedByName: job.askedByName,
+        // The files (0.112.0): the person's inside their words, the
+        // card's at the foot of its discussion.
+        messageFiles,
+      });
+
+/** A live message sent while the turn runs, as the CLI is handed it — on an
+ *  orchestrated card with its id, so the route it takes is reported. */
+export const agentFollowupKickoff = (job, followup, { cardFiles, messageFiles, orchestrated }) =>
+  AGENT_HUMAN_KICKOFF({
+    ...shared(job, cardFiles),
+    message: followup.body + (followup.libraryPrompt ?? '') + (orchestrated ? `\nMessage id: ${followup.id}. Choose and report its route with card_orchestrator.route_message.` : ''),
+    askedByName: followup.askedByName,
+    messageFiles,
+  });
+
+/** The turn's system prompt, in its fixed section order. */
+export function agentTurnSystem({ taskKind, runtimeLabel, prerequisitesAccepted, knowledgeDir, artifactsAccepted, toolsNote, artifactInstructions, toolInstructions, repositoryRun, orchestrated }) {
+  // 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.
+  // Spoken to the CLI that runs it (0.115.0): a mockup on Codex is
+  // told it is Codex, never Claude.
+  return withProjectContext(SYSTEM_AGENT_FOR(taskKind, runtimeLabel, { prerequisitesAccepted }), {
+    knowledgeDir,
+    // ARTIFACTS (0.94.0), while the server can show one — an agent's
+    // land on its page, under the facts row.
+    artifacts: artifactsAccepted,
+  }) + (toolsNote ? `\n\n${toolsNote}` : '') + (artifactInstructions ? `\n\n${artifactInstructions}` : '') + `\n\n${INTERNAL_WAIT_CONTRACT}` + (toolInstructions ? `\n\n${toolInstructions}` : '') + (repositoryRun ? `\n\n${repositoryRun.note}\nRepository command argv: ${JSON.stringify([repositoryRun.tool?.config.command, ...(repositoryRun.tool?.config.args.slice(0, -1) ?? []), "__repository", "<name>"])}` : '') + (orchestrated ? `\n\n${ORCHESTRATOR_CONTRACT}` : '');
+}