flowviant 0.124.0 → 0.125.0

package/bin/lib/turnLock.mjs

@@ -1,22 +1,32 @@
 /**
  * THE CROSS-PROCESS TURN LOCK — the one reading of "is a CLI of ours already
- * working in this directory".
+ * working in this tab's conversation" (and, for ship, "anywhere in this
+ * directory").
  *
  * Split out of work.mjs (2026-09-26, SOLID F037). It is read by the session
  * lane before a spawn and by the ship executor before a merge, and it is pure
  * over the disk and the kernel: no manager state, so it needs no factory and
  * is tested directly (turnLock.test.mjs). The lock FILE's path is the
- * caller's (`sessionMetaPath(wt, 'flowviant-turn.lock')`); what a pid in it
- * means is this module's.
+ * caller's (`sessionMetaPath(wt, 'flowviant-turn.lock', sessionId)`); what a
+ * pid in it means is this module's.
+ *
+ * PER TAB, NOT PER DIRECTORY (2026-10-14). It was keyed by the directory alone,
+ * on the assumption that a place holds one session. Every tab a person opens
+ * shares the checkout, so the one file serialized all of their tabs: a
+ * fourteen-minute turn in one tab held a message in two others for eight
+ * minutes each. The lock guards a CONVERSATION (two CLIs resuming one held
+ * context), so it is scoped by the tab; the unscoped file is what a daemon
+ * from before this change wrote, and is still honored while its CLI lives.
  */
-import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { aliveAndOurs, processStartTime } from './procRegistry.mjs';
 
 /**
- * The spawn lock: the pid of the CLI currently live in this worktree. A
- * restarted daemon must not put a second Claude into a directory the orphan
- * of its previous life is still editing — two CLIs appending to one held
- * conversation is exactly the incoherence workChains prevents in-process,
+ * The spawn lock: the pid of the CLI currently live in this tab. A restarted
+ * daemon must not resume the conversation its previous life's orphan still
+ * holds — two CLIs appending to one held conversation is exactly the
+ * incoherence the synchronous start claim prevents in-process,
  * and the lock extends that guarantee across a restart. A dead pid is a
  * stale lock (removed here); a live one means "come back next poll".
  *
@@ -59,3 +69,33 @@ export const turnLockedByLivePid = (lockPath) => {
   }
   return false;
 };
+
+/**
+ * ANY TAB'S TURN IN THIS DIRECTORY — ship's question, asked of the unscoped
+ * lock path (`sessionMetaPath(wt, 'flowviant-turn.lock')`). Ship folds and
+ * merges with git in the directory every tab there shares, so a live CLI of
+ * ANY tab defers it, not only the shipping tab's own. Reads the unscoped file
+ * and every `<name>-<scope>` beside it; nothing else in the git dir. Return
+ * the holding tab's id so the waiting log names the holder, not the shipper.
+ * A legacy lock has no tab id: null is an honest unknown.
+ */
+export const placeTurnLockHolder = (placeLockPath) => {
+  if (!placeLockPath) return null;
+  const dir = dirname(placeLockPath);
+  const name = basename(placeLockPath);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (entry !== name && !entry.startsWith(`${name}-`)) continue;
+    if (turnLockedByLivePid(join(dir, entry))) {
+      return { sessionId: entry === name ? null : entry.slice(name.length + 1) };
+    }
+  }
+  return null;
+};
+
+export const placeTurnLockedByLivePid = (placeLockPath) => Boolean(placeTurnLockHolder(placeLockPath));

package/bin/lib/work.mjs

@@ -51,17 +51,21 @@
  *   workCappedTurn.mjs     one capped read-only consult turn: its child, its slot,
  *                          its cap and its transcript — the planner, the pre-review
  *                          and intake all run one (2026-10-10)
- *   turnLock.mjs           whether a live CLI of ours holds a directory's turn
+ *   turnLock.mjs           tab pid locks; workLiveMessages.mjs — live input; workDelivery.mjs — queue
  *   (and, split earlier: workDiffs, workPreviews, workPullRequests, workShip,
  *   workAgentPlans, workAgentCheck, workAgentPrecheck, workAgentReview,
- *   workAgentTurns, workAgentMerges, workProcesses; and out of workAgentTurns,
+ *   workAgentTurns, workAgentRecovery, workAgentMerges, workProcesses; and out of workAgentTurns,
  *   SOLID F036: workAgentTurnReports, workAgentTurnExecution, workAgentTurnBegun,
- *   workAgentTurnOutcome; the live brief: workAgentBrief, workAgentBriefRunner)
+ *   workAgentTurnOutcome; repositoryPlaces + agentRepositories: multi-repo places; the live brief: workAgentBrief, workAgentBriefRunner)
  */
 
+import { trackedRepositorySetup } from './repositorySetup.mjs';
+import { createRepositoryPlaces } from './repositoryPlaces.mjs';
+import { createAgentRepositories } from './agentRepositories.mjs';
 import { createWorkProcesses } from './workProcesses.mjs';
 import { createWorkAgentMerges } from './workAgentMerges.mjs';
 import { createWorkAgentTurns } from './workAgentTurns.mjs';
+import { createAgentRecovery } from './workAgentRecovery.mjs';
 import { createWorkAgentCheck } from './workAgentCheck.mjs';
 import { createWorkAgentPrecheck } from './workAgentPrecheck.mjs';
 import { createWorkAgentReview } from './workAgentReview.mjs';
@@ -87,7 +91,7 @@ import { createWorkSessionTurns } from './workSessionTurns.mjs';
 import { createWorkRetire } from './workRetire.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 import { gitNet as gitNetIn, excludeInWorktree } from './git.mjs';
-import { createLandedObserver } from './landed.mjs';
+import { createProjectLandedObserver } from './projectLanded.mjs';
 import { createPlaceLock } from './placeLock.mjs';
 import { warn } from './ui.mjs';
 import { FLOWVIANT_OWN_PATHS } from './knowledgeLibrary.mjs';
@@ -99,6 +103,7 @@ import { scrub as envScrub, secretIn as envSecretIn } from './uplinkScrub.mjs';
 
 export function createWorkManager({
   repoRoot,
+  repositories,
   baseDir,
   getBaseRef,
   getMcpUrl,
@@ -135,10 +140,12 @@ export function createWorkManager({
    * `origin/<branch you happened to be on>` for the life of the daemon.
    */
   const baseRef = () => getBaseRef();
+  const repositoryPlaces = repositories && createRepositoryPlaces({ repoRoot, baseDir, repositories, changed: onRepoChanged, setup: (...args) => trackedRepositorySetup(workChildren, groupKillChildren)(...args) });
+  const agentRepositories = repositories && createAgentRepositories({ repositories, places: repositoryPlaces });
   // What arrived on base, whichever road it took — observed after every beat
   // that can move origin/<base>: the sweep's fetch, a ship's push, a PR merge
   // this daemon performed. See landed.mjs for the seeding and delivery rules.
-  const landed = createLandedObserver({ repoRoot, baseRef });
+  const landed = createProjectLandedObserver({ repoRoot, baseRef, repositories });
   /**
    * THE ARTIFACT RELAY (2026-09-22, 0.94.0) — what a turn wrote under
    * `.flowviant/artifacts/`, uploaded after it. One reporter for the life of
@@ -200,14 +207,13 @@ export function createWorkManager({
    */
   const gitNet = (args, ms) => gitNetIn(args, repoRoot, ms);
 
-  // ── THE SESSION'S OWN HALF — built first, because the lanes below are handed it.
   const { placeOf, notePlace, learnPlaces, placeDir, branchAt, placeWtFor, sessionMetaPath, worktreeBornAt } =
     createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged });
   const { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses } =
     createWorkSessionGroups({ repoRoot });
   const { workChildren, groupKillChildren, shutdownWork, liveTurnCount, liveTurns, admit } =
     createWorkChildren({ extraLiveTurns });
-  const { agentPublished, agentRemoteAt, publishAgentBranch, fetchPublishedBranch } =
+  const { agentPublished, agentRemoteAt, publishAgentBranch, stopAgentPublishing, fetchPublishedBranch, fetchPublishedBranchAsync } =
     createWorkAgentPublish({ repoRoot, gitNet });
   const { reconcileIdleArtifacts } = createWorkArtifactReconcile({
     artifacts,
@@ -220,6 +226,7 @@ export function createWorkManager({
   });
   const { reportSessionWorktree, reportPlaceWorktrees, burstListeners, reportWorktrees } =
     createWorkPlaceReports({
+      repositoryPlaces,
       repoRoot,
       baseRef,
       placeOf,
@@ -295,15 +302,10 @@ export function createWorkManager({
    * which lanes share which map (workChildren: plans, review, turns; the
    * publication maps: turns and merges).
    */
-
-  const { processDiffJobs } = createWorkDiffs({
-    repoRoot,
-  });
-
+  const { processDiffJobs } = createWorkDiffs({ repoRoot });
   const { processPreviewJobs, livePreviewIds, retirePreviews, shutdownPreviews } = createWorkPreviews({
     placeDir,
   });
-
   const { processPrJobs } = createWorkPullRequests({
     placeOf,
     placeDir,
@@ -314,7 +316,6 @@ export function createWorkManager({
     landed,
     onRepoChanged,
   });
-
   const { processShipJobs } = createWorkShipper({
     inPlace,
     placeOf,
@@ -330,7 +331,6 @@ export function createWorkManager({
     shipping,
     pendingShipReports,
   });
-
   const { processAgentPlanJobs, planning } = createWorkAgentPlans({
     postBestEffort,
     baseDir,
@@ -341,7 +341,6 @@ export function createWorkManager({
     placeLocks,
     workChildren,
   });
-
   const { processIntakeJobs, intake } = createWorkIntake({
     postBestEffort,
     inPlace,
@@ -367,9 +366,9 @@ export function createWorkManager({
     workChildren,
   });
   const { runReviewEntry } = createWorkAgentReview({ runCheck, runPrecheck });
-
+  const processAgentRecoveryJobs = createAgentRecovery({ baseDir, repoRoot, fetchPublishedBranch: fetchPublishedBranchAsync, inPlace, placeWtFor, reportSessionWorktree });
   const { processAgentTurnJobs, interruptAgentTurns, settleAgentTurns, agentTurns, agentChildren, agentReported } = createWorkAgentTurns({
-    REJECT_RETRY_MS,
+    agentRepositories, REJECT_RETRY_MS,
     baseRef,
     inPlace,
     baseDir,
@@ -383,15 +382,16 @@ export function createWorkManager({
     reportSessionWorktree,
     artifacts,
     runReviewEntry,
-    publishAgentBranch,
+    publishAgentBranch, stopAgentPublishing,
     admit,
     workChildren,
     agentPublished,
     agentRemoteAt,
     fetchAgentFiles,
   });
-
   const { processAgentMergeJobs, agentMerges } = createWorkAgentMerges({
+    runCheck, workChildren, groupKillChildren, admit,
+    repositoryPlaces,
     repoRoot,
     inPlace,
     baseDir,
@@ -404,10 +404,9 @@ export function createWorkManager({
     agentPublished,
   });
 
-  // Built after the agent lane: retirement stops a stopped agent's CLI, and
-  // only the agent lane knows which child that is.
+  // Retirement asks the agent lane which CLI to stop.
   const { heldSessionIds, retireWorkSessions, freshenManualPlaces } = createWorkRetire({
-    repoRoot,
+    repositoryPlaces, repoRoot,
     baseDir,
     baseRef,
     placeOf,
@@ -485,7 +484,7 @@ export function createWorkManager({
     liveTurnCount,
     processAgentPlanJobs,
     processIntakeJobs,
-    processAgentTurnJobs, interruptAgentTurns,
+    processAgentTurnJobs, processAgentRecoveryJobs, interruptAgentTurns,
     // Only the roster's stand-down calls this — a displacement, a removal or a
     // commanded stop (holder.mjs, `standDownDisplaced`); see its comment.
     // Exported rather than hooked into `shutdownWork` because the signal

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, commandOverride) => {
+    const cmd = commandOverride ?? 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,12 @@
+import { createWorkMergeBatch } from './workMergeBatch.mjs';
+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 +33,8 @@ export function agentMergeFailureDetail(error) {
 }
 
 export function createWorkAgentMerges({
+  runCheck, workChildren = new Map(), groupKillChildren = new Set(), admit,
+  repositoryPlaces,
   repoRoot,
   inPlace,
   baseDir,
@@ -111,7 +116,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 +124,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' });
@@ -417,13 +436,14 @@ export function createWorkAgentMerges({
     }
   };
 
+  const runBatch = createWorkMergeBatch({ repositoryPlaces, repoRoot, baseDir, inPlace, runCheck, workChildren, groupKillChildren, admit, onRepoChanged, landed });
   const processAgentMergeJobs = (jobs) => {
     if (!Array.isArray(jobs) || jobs.length === 0) return;
     for (const job of jobs.slice(0, 2)) {
-      const id = String(job?.agentId || '');
+      const id = String(job?.batch?.spec?.id || job?.agentId || '');
       if (!id || agentMerges.has(id)) continue;
       agentMerges.add(id);
-      void runAgentMerge(job).finally(() => agentMerges.delete(id));
+      void (job.batch ? runBatch(job) : runAgentMerge(job)).finally(() => agentMerges.delete(id));
     }
   };
 

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

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;
 }