flowviant 0.117.0 → 0.124.1

package/bin/lib/workAgentBrief.mjs

@@ -0,0 +1,92 @@
+/** A readout alongside ONE running CLI, never another worker on its branch.
+ * No events since the last snapshot means no model call. A stopped child,
+ * pause, park or lost holder prevents a call or a late result from publishing. */
+import { AGENT_BRIEF_SYSTEM, parseAgentBrief, briefModelFor } from './agentBrief.mjs';
+
+export const AGENT_BRIEF_INTERVAL_MS = 3 * 60_000;
+export const AGENT_BRIEF_FIRST_MS = 20_000;
+export const AGENT_BRIEF_INPUT_MAX = 24_000;
+export function makeAgentBrief({ runtime, model, context, summarize, post, scrub = (s) => s, models = () => [], now = Date.now,
+  setTimer = setTimeout, clearTimer = clearTimeout }) {
+  let running = false;
+  let stopped = false;
+  let timer = null;
+  let sequence = 0;
+  let consumed = 0;
+  let entries = [];
+  let flight = null;
+  let controller = null;
+  let held = null;
+  const append = (kind, data) => {
+    if (stopped || data == null) return;
+    // Scrub before trimming so a cut never turns a secret into an unrecognized prefix.
+    let text;
+    try {
+      text = (typeof data === 'string' ? scrub(data) : JSON.stringify(data, (_key, value) => {
+        // Redact decoded strings BEFORE JSON escapes quotes and newlines;
+        // otherwise a multiline secret no longer matches its learned value.
+        if (typeof value === 'string') return scrub(value);
+        if (value && typeof value === 'object' && !Array.isArray(value))
+          return Object.fromEntries(Object.entries(value).map(([key, item]) => [scrub(key), item]));
+        return value;
+      })).slice(0, 4_000);
+    } catch { return; } // an optional readout must never fail the working CLI
+    if (!text.trim()) return;
+    entries.push({ seq: ++sequence, kind, text });
+    while (entries.length > 100 || entries.reduce((sum, e) => sum + e.text.length, 0) > AGENT_BRIEF_INPUT_MAX) entries.shift();
+  };
+  const schedule = (ms = AGENT_BRIEF_INTERVAL_MS) => {
+    if (timer || stopped || !running) return;
+    timer = setTimer(() => { timer = null; void tick(); }, ms);
+    timer?.unref?.();
+  };
+  const refresh = async () => {
+    if (!running || stopped || (!held && sequence === consumed)) return;
+    // Retry a paid-for reading without paying for another. The API rechecks
+    // holder and turn in the write, and duplicate/older snapshots cannot win.
+    if (held) { if (await post(held)) held = null; return; }
+    const brain = briefModelFor(runtime, typeof model === 'function' ? model() : model, models());
+    if (!brain) return;
+    controller = new AbortController();
+    const state = await context(controller.signal);
+    if (state?.unsupported) { stopped = true; if (timer) clearTimer(timer); timer = null; return; }
+    if (stopped || !running || !state?.active || controller.signal.aborted) return;
+    // Card changes and daemon restarts do not reset the agent's three-minute
+    // cadence. Both dates came from the server, not this machine's clock.
+    if (state.brief && Date.parse(state.sourceAt) - Date.parse(state.brief.updatedAt) < AGENT_BRIEF_INTERVAL_MS) return;
+    const through = sequence;
+    const events = entries.filter((e) => e.seq > consumed);
+    if (!events.length) return;
+    const prompt = JSON.stringify({ previous: state.brief ?? null, taskId: state.taskId ?? null,
+      omittedEvents: Math.max(0, events[0].seq - consumed - 1), events: events.map(({ kind, text }) => ({ kind, text })) });
+    const out = await summarize({ runtime, ...brain, system: AGENT_BRIEF_SYSTEM, prompt, signal: controller.signal });
+    if (stopped || !running || controller.signal.aborted) return;
+    const content = parseAgentBrief(typeof out === 'string' ? out : out?.out, scrub);
+    if (!content) return;
+    consumed = through;
+    entries = entries.filter((e) => e.seq > through);
+    held = { ...content, sourceAt: state.sourceAt ?? new Date(now()).toISOString(), ...(out?.usage ? { usage: out.usage } : {}) };
+    if (await post(held)) held = null;
+  };
+  const tick = () => {
+    if (flight) return flight;
+    flight = refresh().catch(() => {}).finally(() => { flight = null; controller = null; schedule(); });
+    return flight;
+  };
+  return {
+    append, tick,
+    running(active) {
+      running = active;
+      if (active) schedule(AGENT_BRIEF_FIRST_MS);
+      else { if (timer) clearTimer(timer); timer = null; controller?.abort(); }
+    },
+    async stop() {
+      stopped = true;
+      running = false;
+      if (timer) clearTimer(timer);
+      timer = null;
+      controller?.abort();
+      await flight;
+    },
+  };
+}

package/bin/lib/workAgentBriefRunner.mjs

@@ -0,0 +1,59 @@
+/** A separate, short-lived CLI conversation using the same vendor's login.
+ * It stands in an empty scratch directory, never in the working agent's
+ * cwd-keyed resume. No project tools, no MCP, no repository instructions. */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { runTurn } from './runTurn.mjs';
+import { runCappedTurn } from './workCappedTurn.mjs';
+import { makeAgentBrief } from './workAgentBrief.mjs';
+import { knownCodexModels } from './runtimeOfferings.mjs';
+import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
+import { fleetRequest } from './fleetPost.mjs';
+import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
+import { scrub } from './uplinkScrub.mjs';
+
+export function createAgentBriefRunner({ admit, workChildren, run = runTurn, request = fleetRequest }) {
+  return ({ agentId, turnId, runtime, model }) => {
+    const identity = { agentId, turnId, instance: DAEMON_INSTANCE };
+    return makeAgentBrief({ runtime, model, scrub, models: knownCodexModels,
+      context: async (signal) => {
+        // Node >=20, including versions before AbortSignal.any was added.
+        const abort = new AbortController();
+        const timeout = AbortSignal.timeout(15_000);
+        const cancel = () => abort.abort();
+        signal.addEventListener('abort', cancel, { once: true });
+        timeout.addEventListener('abort', cancel, { once: true });
+        if (signal.aborted) cancel();
+        try {
+          const r = await request(fleetEndpoint('agent-brief-context', FLEET_URL), { body: identity, signal: abort.signal });
+          return r.ok ? r.json?.data : isConsideredRefusal(r.status) ? { unsupported: true } : null;
+        } finally {
+          signal.removeEventListener('abort', cancel);
+          timeout.removeEventListener('abort', cancel);
+        }
+      },
+      post: async (content) => {
+        const r = await request(fleetEndpoint('agent-brief', FLEET_URL), { body: { ...identity, ...content }, timeoutMs: 15_000 });
+        return r.ok || isConsideredRefusal(r.status);
+      },
+      summarize: async ({ signal, ...turnArgs }) => {
+        if (signal.aborted || admit('churn')) return '';
+        const releaseSlot = admit.reserve();
+        let cwd = null;
+        let usage = null;
+        try {
+          cwd = mkdtempSync(join(tmpdir(), 'flowviant-brief-'));
+          const result = await runCappedTurn({ runTurn: run, workChildren, releaseSlot, signal,
+            capMs: 60_000, transcriptCwd: cwd,
+            turnArgs: { ...turnArgs, cwd, profile: 'consult', answerFromResult: true, label: '[brief]',
+              onUsage: (u) => { usage = { ...u, runtime: turnArgs.runtime }; } } });
+          return result.wedged ? '' : { out: result.out, usage };
+        } finally {
+          releaseSlot();
+          if (cwd) rmSync(cwd, { recursive: true, force: true });
+        }
+      },
+    });
+  };
+}

package/bin/lib/workAgentCheck.mjs

@@ -150,9 +150,9 @@ export function createWorkAgentCheck({
   const CHECK_TIMEOUT_MS = 10 * 60_000;
   const CHECK_OUTPUT_CAP = 4000;
 
-  const readCheckCommand = () => {
+  const readCheckCommand = (root = repoRoot) => {
     try {
-      const raw = readFileSync(join(repoRoot, '.flowviant', 'check.json'), 'utf8');
+      const raw = readFileSync(join(root, '.flowviant', 'check.json'), 'utf8');
       const cfg = JSON.parse(raw);
       const cmd = typeof cfg?.command === 'string' ? cfg.command.trim() : '';
       return cmd ? cmd.slice(0, 500) : null;
@@ -168,8 +168,8 @@ export function createWorkAgentCheck({
     await postBestEffort(AGENT_CHECK_DONE_URL, body);
   };
 
-  const runCheck = async (agentId, wt) => {
-    const cmd = readCheckCommand();
+  const runCheck = async (agentId, wt, repository) => {
+    const cmd = readCheckCommand(repository ? wt : repoRoot);
     // OPTIONAL, like the pre-review's twin read: an unreadable head (a
     // worktree retired mid-beat, an unborn branch) costs the answer its
     // headSha, never the answer. This read was the one copy left unguarded,
@@ -178,7 +178,7 @@ export function createWorkAgentCheck({
     const headSha = gitOrNull(['rev-parse', 'HEAD'], wt) ?? undefined;
     if (!cmd) {
       await postCheck({ agentId, status: 'none', ...(headSha ? { headSha } : {}) });
-      return;
+      return { status: 'none' };
     }
     const cleared = clearNonArtifacts(wt);
     if (cleared.length)
@@ -325,6 +325,7 @@ export function createWorkAgentCheck({
       output: envScrub(out.text).slice(-CHECK_OUTPUT_CAP),
       ...(headSha ? { headSha } : {}),
     });
+    return out;
   };
 
   return { runCheck };

package/bin/lib/workAgentMerges.mjs

@@ -1,9 +1,11 @@
+import { mergeRepositoryPlace } from './repositoryMerge.mjs';
+import { fleetRequest } from './fleetPost.mjs';
 /** Agent merge claims, pull-request approval, and branch cleanup. */
 import { ensureOpenPr, ghReady, mergeAndVerifyTip, PR_URL_RE, relayedFailure } from './prWorkflow.mjs';
 import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
-import { FLEET_URL } from './config.mjs';
+import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
 import { git, gitOrNull, gitNet as gitNetIn, baseBranchName, isSafePathSegment, sessionBranch, stripUrlUserinfo } from './git.mjs';
 import { isPublishRef, publishPushArgs, publishDeleteArgs, publishErrorText } from './agentPublish.mjs';
 import { mergeOutward as shipMergeOutward } from './shipMerge.mjs';
@@ -30,6 +32,7 @@ export function agentMergeFailureDetail(error) {
 }
 
 export function createWorkAgentMerges({
+  repositoryPlaces,
   repoRoot,
   inPlace,
   baseDir,
@@ -111,7 +114,7 @@ export function createWorkAgentMerges({
     const report = async (body) => {
       reported = true;
       if (body?.ok === true) landedRef = job.publishedRef ?? null;
-      await postAgentMerge(body);
+      await postAgentMerge({ ...body, ...(body.detail ? { detail: envScrub(stripUrlUserinfo(String(body.detail))).slice(0, 2000) } : {}) });
     };
 
     // A WRITER on the place, exactly as a ship is. It folds base in and pushes
@@ -119,6 +122,20 @@ export function createWorkAgentMerges({
     // does not know exists.
     try {
       await inPlace(place, true, async () => {
+      if (job.repositoryMerge) {
+        if (!repositoryPlaces) throw new Error('Project repository worktrees are unavailable.');
+        const result = await mergeRepositoryPlace({ job, entries: repositoryPlaces.entries(place), baseDir,
+          check: (r) => runReviewEntry(agentId, r.wt, job.agentName, r),
+          progress: async (states, retry) => {
+            const response = await fleetRequest(fleetEndpoint('agent-merge-progress', FLEET_URL), {
+              body: { agentId, instance: DAEMON_INSTANCE, states, retry } });
+            if (response.error || response.json?.data?.ok !== true) throw new Error('Repository merge progress was not acknowledged. The next attempt will remeasure base.');
+          } });
+        if (result.retry) reported = true; // The lease was released; approval remains.
+        else await report({ agentId, ...result });
+        onRepoChanged();
+        return;
+      }
       const wt = worktreePath(baseDir, place);
       if (!existsSync(wt)) {
         await report({ agentId, ok: false, detail: 'the worktree is gone' });

package/bin/lib/workAgentPlans.mjs

@@ -1,11 +1,14 @@
 /** Agent plan claims, read-only planning turns, and proposal reports. */
-import { existsSync } from 'node:fs';
+import { discoveryGuide } from './discoveryContract.mjs';
+import { compareRepositoryBaselines, measureRepositoryBaseline, repositoryBaselineOf } from './repositoryBaseline.mjs';
+import { knowledgeDirFor } from './knowledgeFiles.mjs';
+import { createToolLog } from './workToolLog.mjs';
 import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
-import { gitOrNull, isSafePathSegment } from './git.mjs';
+import { measureAgentFootprint, liveAgentContext } from './agentFootprint.mjs';
 import { parseProposal } from './agentPlan.mjs';
 import { c, note } from './ui.mjs';
 import { runTurn as defaultRunTurn } from './runTurn.mjs';
-import { SYSTEM_PLAN, AGENT_PLAN_KICKOFF } from './prompts.mjs';
+import { SYSTEM_PLAN, AGENT_PLAN_KICKOFF, withProjectContext, REPOSITORY_BASELINE_PARAGRAPH } from './prompts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { canRun, runtimeById, runtimeLabel } from './runtimes.mjs';
 import { detectRuntimes as defaultDetectRuntimes, pickRuntimeFor as defaultPickRuntimeFor } from './runtimeDetection.mjs';
@@ -13,7 +16,7 @@ import { brainFor } from './workBrain.mjs';
 import { runCappedTurn } from './workCappedTurn.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { claimFleetLease, fleetHeaders } from './fleetPost.mjs';
-import { REPO_PLACE, worktreePath } from './workPlaces.mjs';
+import { REPO_PLACE } from './workPlaces.mjs';
 import { addUsage } from './turnUsage.mjs';
 
 export function createWorkAgentPlans({
@@ -133,56 +136,6 @@ export function createWorkAgentPlans({
   // The peer may hold it; doing nothing is the safe answer.
   const claimAgentPlan = (id) => claimFleetLease(AGENT_PLAN_CLAIM_URL, { id });
 
-  /**
-   * What a live agent has already TOUCHED, measured here rather than sent.
-   *
-   * The server could have shipped a copy of this, and deliberately does not:
-   * these are directories on THIS machine, and a server-side copy would be a
-   * second, staler source of truth for a fact the daemon is standing on top of.
-   *
-   * Uncommitted work AND commits against base, because a planner asking "will
-   * these collide" cares about both — a file this agent has already rewritten
-   * and merged into its own branch collides exactly as hard as one it is
-   * editing now.
-   */
-  const agentChangedFiles = (placeId) => {
-    if (!placeId || !isSafePathSegment(placeId)) return [];
-    const wt = worktreePath(baseDir, placeId);
-    if (!existsSync(wt)) return [];
-    const out = new Set();
-    for (const args of [
-      ['diff', '--name-only', 'HEAD'],
-      ['diff', '--name-only', `${baseRef()}...HEAD`],
-      ['ls-files', '--others', '--exclude-standard'],
-    ]) {
-      /**
-       * `git()` THROWS; it does not return a non-string.
-       *
-       * The guard below was `if (typeof r !== 'string') continue`, which is a
-       * value `execFileSync` can never produce — so every one of these calls
-       * was effectively unguarded. And this runs over the LIVE AGENTS a plan
-       * job carries, which include agents still in `planning`: they have no
-       * worktree yet, so `git diff` in a directory that does not exist exits
-       * non-zero and throws straight out of `runAgentPlan` — after the press
-       * has been claimed and before the try/finally below. The press then sat
-       * `planning` until its expiry, having spent nothing and explained
-       * nothing, on what would be an ordinary second Deploy.
-       *
-       * An agent whose files cannot be read contributes none — `gitOrNull`
-       * (git.mjs) reads a failure as null. That is the honest answer and it
-       * is what the planner should be told.
-       */
-      const r = gitOrNull(args, wt);
-      if (r == null) continue;
-      for (const line of r.split('\n')) {
-        const f = line.trim();
-        if (f) out.add(f);
-        if (out.size >= 60) return [...out];
-      }
-    }
-    return [...out];
-  };
-
   /** See `runAgentTurn` — the admission reservation, released the moment the
    *  planner's CLI exists. */
   const runAgentPlan = async (job, releaseSlot = () => {}) => {
@@ -268,20 +221,6 @@ export function createWorkAgentPlans({
       lastPlanBeat = Date.now();
       void postAgentPlanActivity(id, line);
     };
-    const liveAgents = (Array.isArray(job.liveAgents) ? job.liveAgents : []).map((a) => ({
-      id: String(a?.id ?? ''),
-      name: String(a?.name ?? ''),
-      status: String(a?.status ?? ''),
-      // Belt: `agentChangedFiles` is defensive internally, but it resolves a
-      // place first and this whole block sits outside the try below.
-      changedFiles: (() => {
-        try {
-          return agentChangedFiles(a?.placeId);
-        } catch {
-          return [];
-        }
-      })(),
-    }));
 
     let out = '';
     /** The cap fired: the CLI was still running when this machine stopped it. */
@@ -294,7 +233,8 @@ export function createWorkAgentPlans({
      * a report the retry posts again adds nothing. Null until the CLI reports.
      */
     let usage = null;
-    const spent = () => (usage ? { usage } : {});
+    const discovery = createToolLog(repoRoot);
+    const spent = () => ({ ...(usage ? { usage } : {}), tools: discovery.toolLog });
     // Said BEFORE the lock is asked for, because a reader only waits when a
     // writer holds the checkout or is queued ahead of it — which is exactly
     // this condition, read one line before we join the queue.
@@ -315,6 +255,12 @@ export function createWorkAgentPlans({
          * fork a read-only planner into a build tab, and being what their own
          * `claude --continue` resumed.
          */
+        const liveAgents = (Array.isArray(job.liveAgents) ? job.liveAgents : []).map(a =>
+          liveAgentContext(a, measureAgentFootprint({ placeId: a?.placeId, baseDir, baseRef })));
+        const knowledgeDir = knowledgeDirFor(repoRoot);
+        discovery.toolLog.baseline = measureRepositoryBaseline({ cwd: repoRoot, baseRef, knowledgeDir });
+        discovery.toolLog.captureBaseline = repositoryBaselineOf(job.captureBaseline);
+        discovery.toolLog.reconciliation = compareRepositoryBaselines(discovery.toolLog.baseline, discovery.toolLog.captureBaseline);
         ({ out, wedged } = await runCappedTurn({
           runTurn,
           capMs: PLAN_TURN_TIMEOUT_MS,
@@ -322,12 +268,14 @@ export function createWorkAgentPlans({
           releaseSlot,
           transcriptCwd: repoRoot,
           turnArgs: {
+            diagnosticPlanId: id,
             prompt: AGENT_PLAN_KICKOFF({
               tasks,
               liveAgents,
               agentCap: Number.isInteger(job.agentCap) && job.agentCap > 0 ? job.agentCap : 3,
             }),
-            system: SYSTEM_PLAN,
+            system: withProjectContext(SYSTEM_PLAN, { knowledgeDir }) + '\n\n' + discoveryGuide(rt, 'planning') + '\n\n' + REPOSITORY_BASELINE_PARAGRAPH(discovery.toolLog.baseline, discovery.toolLog.captureBaseline, discovery.toolLog.reconciliation),
+            knowledgeDir,
             // 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',
@@ -342,6 +290,7 @@ export function createWorkAgentPlans({
             onActivity: (a) => {
               if (a?.label) narrate(String(a.label));
             },
+            onToolEvent: discovery.pushToolEvent,
             // Tagged with the CLI that counted it; one turn, so the sum is the
             // one report (turnUsage.mjs keeps it null-safe).
             onUsage: (u) => {
@@ -354,11 +303,13 @@ export function createWorkAgentPlans({
         }));
       });
     } catch (e) {
+      discovery.toolLog.state = 'partial';
       await postAgentPlan({ id, error: envScrub(String(e?.message || e)).slice(0, 500), ...spent() });
       return;
     }
 
     if (wedged) {
+      discovery.toolLog.state = 'partial';
       // NEVER LEAVE A CLAIMED PRESS UNREPORTED — the belt the merge lane wears
       // beneath this one. The machine's own words, because the machine is the
       // only side that knows: the server would have expired this press in

package/bin/lib/workAgentPrecheck.mjs

@@ -116,8 +116,8 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
    * ref at all; an unreadable range costs the reviewer its context, never the
    * review-entry beat it is standing in.
    */
-  const branchLog = (wt) => {
-    const out = gitOrNull(['log', '--format=%s%n%b%n--', `${baseRef()}..HEAD`, '--not', baseRef()], wt);
+  const branchLog = (wt, ref = baseRef()) => {
+    const out = gitOrNull(['log', '--format=%s%n%b%n--', `${ref}..HEAD`, '--not', ref], wt);
     if (out == null) return { text: '', taskIds: [] };
     // LINEAR, never backtracking (audit 2026-09-24) — this was
     // `out.matchAll(/^\s*Flowviant-Task:\s*(\S+)\s*$/gm)`, whose `\s*$` is
@@ -135,7 +135,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
     return { text, taskIds: [...taskIds] };
   };
 
-  const runPrecheck = async (agentId, wt, agentName) => {
+  const runPrecheck = async (agentId, wt, agentName, repository) => {
     /**
      * WHICH CLI READS. `pickRuntimeFor('consult')` — the same picker the scratch
      * planner uses, and for the same reason: this prompt was written against
@@ -166,7 +166,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
     const headSha = gitOrNull(['rev-parse', 'HEAD'], wt);
 
     const stash = readStash(sessionMetaPath(wt, 'flowviant-agent-cards', agentId));
-    const log = branchLog(wt);
+    const log = branchLog(wt, repository?.baseRef ?? baseRef());
     /** 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));
@@ -224,7 +224,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
             cards: stash.map((s) => s.prompt).join('\n---\n'),
             missingSpecs,
             commits: log.text,
-            diffCommand: `git diff ${baseRef()}...HEAD`,
+            diffCommand: `git diff ${repository?.baseRef ?? baseRef()}...HEAD`,
           }),
           system: SYSTEM_PRECHECK,
           // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
@@ -314,10 +314,15 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
       agentId,
       ...(headSha ? { headSha } : {}),
       ...(usage ? { usage } : {}),
+      // Named fields, never a spread of what the parser returned: a field it
+      // keeps must be passed on here as well. `criteria` rides beside the verdict
+      // and note (2026-10-10), and an older server strips it and draws the one
+      // row it always drew.
       cards: result.cards.map((cd) => ({
         taskId: cd.taskId,
         verdict: cd.verdict,
         ...(cd.note ? { note: cd.note } : {}),
+        ...(cd.criteria ? { criteria: cd.criteria } : {}),
       })),
       ...(result.overall ? { overall: result.overall } : {}),
     };

package/bin/lib/workAgentPublish.mjs

@@ -8,9 +8,9 @@
  * 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.
+ * retires the ref — all through the maps and functions returned here.
  */
-import { gitOrNull, sessionBranchRef } from './git.mjs';
+import { gitOrNull, sessionBranchRef, gitNetAsync } from './git.mjs';
 import { publishPushArgs, publishFetchArgs, publishErrorText } from './agentPublish.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 
@@ -41,6 +41,8 @@ export function createWorkAgentPublish({ repoRoot, gitNet }) {
    * something a rebase can invalidate.
    */
   const agentPublished = new Map();
+  let publishingStopped = false;
+  const stopAgentPublishing = () => { publishingStopped = true; };
   /**
    * WHAT THIS PROCESS HAS SEEN AT EACH AGENT'S REMOTE REF — `{ ref, sha }`, and
    * the ONLY input to the push's lease.
@@ -85,6 +87,7 @@ export function createWorkAgentPublish({ repoRoot, gitNet }) {
    * Never throws.
    */
   const publishAgentBranch = async (place, target) => {
+    if (publishingStopped) return false;
     const sha = agentBranchSha(place);
     if (!sha) return false;
     const prev = agentPublished.get(place);
@@ -124,8 +127,8 @@ export function createWorkAgentPublish({ repoRoot, gitNet }) {
    * 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.
+   * Reached after the begun guard measures neither a worktree nor a branch,
+   * by the ordinary turn path or the holder's recovery inspection.
    * 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.
@@ -159,6 +162,16 @@ export function createWorkAgentPublish({ repoRoot, gitNet }) {
         why: publishErrorText(envScrub(e?.stderr?.toString?.() || e?.message || '')),
       };
     }
+    return fetchedBranch(place, ref);
+  };
+  const fetchPublishedBranchAsync = async (place, ref) => {
+    const args = publishFetchArgs(ref, place);
+    if (!args) return null;
+    try { await gitNetAsync(args, repoRoot, 120_000); }
+    catch (e) { return { ok: false, why: publishErrorText(envScrub(e?.stderr?.toString?.() || e?.message || '')) }; }
+    return fetchedBranch(place, ref);
+  };
+  const fetchedBranch = (place, ref) => {
     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
@@ -171,5 +184,5 @@ export function createWorkAgentPublish({ repoRoot, gitNet }) {
     return { ok: true };
   };
 
-  return { agentPublished, agentRemoteAt, publishAgentBranch, fetchPublishedBranch };
+  return { agentPublished, agentRemoteAt, publishAgentBranch, stopAgentPublishing, fetchPublishedBranch, fetchPublishedBranchAsync };
 }

package/bin/lib/workAgentRecovery.mjs

@@ -0,0 +1,85 @@
+import { DAEMON_INSTANCE, FLEET_URL } from './config.mjs';
+import { myPubB64 } from './boxIdentity.mjs';
+import { isSafePathSegment, sessionBranchRef, gitNetAsync } from './git.mjs';
+import { begunTurnRefusal } from './workAgentTurnBegun.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { fleetRequest } from './fleetPost.mjs';
+
+/** Inspect before any cut or CLI. A failed request waits for the next poll. */
+export function createAgentRecovery({
+  baseDir, repoRoot, fetchPublishedBranch, inPlace, placeWtFor, reportSessionWorktree,
+  boxId = () => myPubB64(), fleetUrl = FLEET_URL,
+  request = async (job, id) => {
+    const result = await fleetRequest(fleetEndpoint('agent-recover', fleetUrl), { body: {
+      agentId: job.agentId, sourceKey: job.sourceKey, sourceBoxId: job.sourceBoxId,
+      boxId: id, daemonInstance: DAEMON_INSTANCE,
+    } });
+    return result.ok && result.json?.data?.recovered === true;
+  },
+} = {}) {
+  const ready = new Map(); // source snapshot inspected for the next poll
+  let checking = null; // one repository fetch at a time; polling never waits
+  let lastInspected = null;
+  const processAgentRecoveryJobs = (jobs) => {
+    const blocked = new Set();
+    if (!Array.isArray(jobs)) return blocked;
+    const id = boxId();
+    if (!id) return blocked;
+    const offered = new Set(jobs.map((j) => j?.agentId));
+    for (const agent of ready.keys()) if (!offered.has(agent)) ready.delete(agent);
+    // A failed inspection must not keep every agent behind it waiting.
+    const next = jobs.findIndex((j) => j?.agentId === lastInspected) + 1;
+    for (const job of [...jobs.slice(next), ...jobs.slice(0, next)]) {
+      if (!job || !isSafePathSegment(job.agentId) || !isSafePathSegment(job.placeId) ||
+          sessionBranchRef(job.placeId) === null || typeof job.sourceKey !== 'string' ||
+          !job.sourceBoxId || job.sourceBoxId === id || job.placeId !== `a-${job.agentId}`) continue;
+      const key = `${job.sourceBoxId}:${job.sourceKey}`;
+      if (ready.get(job.agentId) === key) { ready.delete(job.agentId); continue; }
+      blocked.add(job.agentId);
+      if (checking) continue;
+      lastInspected = job.agentId;
+      checking = Promise.resolve().then(() => inPlace(job.placeId, true, async () => {
+        let available = false;
+        const facts = { begunOn: job.begunOn, publishedRef: job.publishedRef };
+        // The measurement stays in the begun guard. Only its network fallback
+        // is asynchronous here, so a slow origin never stops heartbeats.
+        const missing = begunTurnRefusal(facts, job.placeId, {
+          baseDir, repoRoot, fetchPublishedBranch: () => null,
+          onAvailable: () => { available = true; },
+        });
+        let refusal = null;
+        if (missing) {
+          const fetched = await fetchPublishedBranch(job.placeId, job.publishedRef);
+          refusal = begunTurnRefusal(facts, job.placeId, {
+            baseDir, repoRoot, fetchPublishedBranch: () => fetched,
+            onAvailable: () => { available = true; },
+          });
+        }
+        if (!refusal) {
+          // Unknown reads start no redo and leave the ordinary begun guard
+          // to report its own git failure. Inspect again on a later poll.
+          // Review and Stuck have no offered task turn to attach and measure
+          // the recovered branch. Report custody here for every available one.
+          if (available && placeWtFor?.(job.placeId)) await reportSessionWorktree?.(job.placeId);
+          ready.set(job.agentId, key);
+          return;
+        }
+        // Never run or settle the old offer while a restart is being decided.
+        await request(job, id);
+      })).catch(() => {}).finally(() => { checking = null; });
+    }
+    return blocked;
+  };
+  // A test or a graceful owner may wait for the current inspection. The fleet
+  // loop deliberately does not: the next poll observes its result.
+  processAgentRecoveryJobs.settled = () => checking ?? Promise.resolve();
+  return processAgentRecoveryJobs;
+}
+
+
+/** Refresh before cutting a redo. A failed fetch keeps the prompt pending. */
+export async function refreshRestartBase(job, repoRoot) {
+  if (!job.freshAfterSwap) return true;
+  try { await gitNetAsync(['fetch', '--prune', 'origin'], repoRoot); return true; }
+  catch { return false; }
+}

package/bin/lib/workAgentReview.mjs

@@ -27,17 +27,19 @@ export function createWorkAgentReview({ runCheck, runPrecheck }) {
    * INSIDE the place's writer lock on a path whose callers settle real work —
    * `runAgentMerge` in particular reports a claimed merge after this returns.
    */
-  const runReviewEntry = async (agentId, wt, agentName) => {
+  const runReviewEntry = async (agentId, wt, agentName, repository) => {
+    let result = { status: 'unknown' };
     try {
-      await runCheck(agentId, wt);
+      result = await runCheck(agentId, wt, repository) ?? result;
     } catch {
       /* the row keeps its previous check answer, which is null the first time */
     }
     try {
-      await runPrecheck(agentId, wt, agentName);
+      await runPrecheck(agentId, wt, agentName, repository);
     } catch {
       /* no pre-review is posted, and absence renders nothing */
     }
+    return result;
   };
 
   return { runReviewEntry };

package/bin/lib/workAgentTurnBegun.mjs

@@ -40,11 +40,11 @@ import { worktreePath } from './workPlaces.mjs';
  * 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.
+ * This remains the same-box and older-server refusal. The recovery coordinator
+ * now inspects foreign work before this ordinary turn path: after a person's
+ * machine swap it can replace missing work with an explicit start from briefs.
  */
-export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublishedBranch }) {
+export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublishedBranch, onAvailable = () => {} }) {
   // The caller validated `place` (workAgentTurns); an unsafe one would give a
   // null directory AND a null ref below, and the null ref stands the guard
   // down — the same fail-open direction as an unreadable repo.
@@ -105,9 +105,11 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
         (fetched ? ` Its published branch could not be fetched (${fetched.why}).` : '')
       );
     }
+    onAvailable();
     // 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.
   }
+  if (hasBranch || (wtDir && existsSync(wtDir))) onAvailable();
   return null;
 }