flowviant 0.125.23 → 0.125.24

package/README.md

@@ -328,6 +328,18 @@ pinned because [npm 12 removed shrinkwrap support](https://github.com/npm/cli/bl
 and omits it from tarballs; npm 12 consumers also ignore that lockfile.
 No sibling repository or separate app deploy key is required.
 
+### Staged agent worktree startup and restart protection (0.125.24)
+
+Card launches verify their exact Git worktree and repository before starting,
+including after tool preparation. Fresh empty leftover directories are
+initialized; nonempty invalid directories are preserved. Verified Codex
+launches use an explicit cwd and the daemon's repository checks. Agent turns,
+retirement and manual fast-forwarding honor live CLI PID/start-time receipts
+across daemon restarts. Existing begun work still needs its worktree, surviving
+branch or published recovery copy; restarting the daemon alone does not reset
+a stuck board agent. No new wire floor or database migration is required.
+This version is staged, not published or installed.
+
 ### Staged artifact handoff revisions (0.125.18)
 
 A failed handoff's retry drops every pending source the agent's

package/bin/lib/runTurn.mjs

@@ -204,6 +204,7 @@ function runPlainTurn(opts) {
     const stdinText = rt.stdin?.({ prompt, system, profile: turnProfile.adapterProfile }) ?? null;
     const args = rt.args({
       cardTurn: opts.cardTurn === true,
+      verifiedWorktree: opts.verifiedWorktree === true,
       orchestration: opts.orchestration === true,
       readOnlyCoordination: opts.readOnlyCoordination === true,
       // The lane's own measurement when it decided to orchestrate, so the

package/bin/lib/runtimeCodex.mjs

@@ -270,18 +270,17 @@ export const CODEX_RUNTIME = {
    * the prompt always carries them too. Workbench tabs keep their normal
    * checkout discovery.
    *
-   * `--skip-git-repo-check` is deliberately NOT passed by the build or any
-   * fence but research's: a task always builds in a git worktree, and if it
-   * somehow is not one, failing loudly beats silently editing files nobody
-   * can diff. A write-up reads a COPY with no `.git` and never resumes
-   * (codexResearch.mjs), so its fence passes it.
+   * Agent launches verify their exact worktree root and repository ownership
+   * through git before every spawn. Only those launches may replace Codex's
+   * own repository discovery with `--skip-git-repo-check`; this grants no
+   * project-config trust. Research's isolated copy has its own exception.
    *
    * The prompt positional stays last; runTurn uses `-` and sends the complete
    * framed text through stdin. A whole batch can exceed Linux's single-argument
    * limit even when its argv plus environment is far below ARG_MAX. Both exec
    * and exec resume support `-` (verified on Codex 0.160.0, 2026-10-16).
    */
-  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, codexVersion, orchestration = false, readOnlyCoordination = false }) {
+  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, verifiedWorktree = false, codexVersion, orchestration = false, readOnlyCoordination = false }) {
     // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
     // agy moves) — codex has no adoptable store wired yet. Reaching here
     // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -289,6 +288,8 @@ export const CODEX_RUNTIME = {
     // context with a different brain.
     if (adoptResumeId) throw new Error("codex has no adoptable terminal store — an adopt id can't reach this builder");
     const a = ['exec'];
+    // --cd belongs to exec, before resume (resume has no --cd option).
+    if (verifiedWorktree) a.push('--cd', cwd);
     // BY ID when the caller knows WHICH conversation this is — a Workbench
     // tab's held context, captured off thread.started and stored with its
     // worktree. `--last` resumes the machine's most recent codex conversation,
@@ -298,6 +299,7 @@ export const CODEX_RUNTIME = {
     if (resumeThreadId) a.push('resume', resumeThreadId);
     else if (resume) a.push('resume', '--last');
     a.push('--json');
+    if (verifiedWorktree) a.push('--skip-git-repo-check');
     if (agentTools) {
       a.push('-c', 'project_doc_max_bytes=0');
       // A person's existing developer instructions keep their authority.

package/bin/lib/turnLock.mjs

@@ -18,10 +18,23 @@
  * 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, readdirSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { aliveAndOurs, processStartTime } from './procRegistry.mjs';
 
+/** The child owns the receipt, so a daemon restart still sees its live PID. */
+export function recordTurnLock(path, pid) {
+  if (!path || !pid) return () => {};
+  const start = processStartTime(pid);
+  const value = start ? `${pid}:${start}` : String(pid);
+  writeFileSync(path, value);
+  return () => {
+    try {
+      if (readFileSync(path, 'utf8') === value) rmSync(path);
+    } catch { /* already removed, or replaced by another holder */ }
+  };
+}
+
 /**
  * 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

package/bin/lib/work.mjs

@@ -450,6 +450,7 @@ export function createWorkManager({
   // Retirement asks the agent lane which CLI to stop.
   const { heldSessionIds, retireWorkSessions, freshenManualPlaces } = createWorkRetire({
     repositoryPlaces, repoRoot,
+    sessionMetaPath,
     baseDir,
     baseRef,
     placeOf,

package/bin/lib/workAgentTurnBegun.mjs

@@ -13,6 +13,7 @@
  * through the one turn-done wire (workAgentTurnReports.mjs). Null means go on.
  */
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { git, sessionBranchRef } from './git.mjs';
 import { worktreePath } from './workPlaces.mjs';
 
@@ -49,6 +50,9 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
   // null directory AND a null ref below, and the null ref stands the guard
   // down — the same fail-open direction as an unreadable repo.
   const wtDir = worktreePath(baseDir, place);
+  // A shell left by an interrupted setup is not the agent's git worktree.
+  // The launch path validates ownership and readability before using it.
+  const hasWorktree = Boolean(wtDir && existsSync(join(wtDir, '.git')));
   const ref = sessionBranchRef(place);
   let hasBranch = false;
   /**
@@ -76,7 +80,7 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
       else branchMeasured = false;
     }
   }
-  if (branchMeasured && !existsSync(wtDir) && !hasBranch) {
+  if (branchMeasured && !hasWorktree && !hasBranch) {
     /**
      * …UNLESS THE WORK IS ON THE REMOTE (0.86.0).
      *
@@ -110,6 +114,6 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
     // 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();
+  if (hasBranch || hasWorktree) onAvailable();
   return null;
 }

package/bin/lib/workAgentTurnExecution.mjs

@@ -31,6 +31,8 @@ import { finishRepositoryDelivery, allResolutionsCommitted } from './repositoryD
 import { MODEL, PROJECT_ID } from './config.mjs';
 import { setRuntimeLimit } from './daemonState.mjs';
 import { gitOrNull } from './git.mjs';
+import { assertWorktree } from './worktreeHealth.mjs';
+import { placeTurnLockedByLivePid, recordTurnLock } from './turnLock.mjs';
 import { turnCommits } from './turnReceipts.mjs';
 import { addUsage } from './turnUsage.mjs';
 import { stashCard, stashGaps } from './agentCards.mjs';
@@ -148,6 +150,10 @@ export function createAgentTurnExecution({
       return;
     }
     const wt = dir.wt;
+    const worktreeRepo = repositoryRun?.sources.find(r => r.wt === wt)?.repoRoot ?? repoRoot;
+    assertWorktree(wt, worktreeRepo);
+    const turnLock = sessionMetaPath(wt, 'flowviant-turn.lock', place);
+    if (placeTurnLockedByLivePid(sessionMetaPath(wt, 'flowviant-turn.lock'))) return;
     /**
      * NEITHER OF THESE MAY THROW. `git()` throws on a non-zero exit, and both
      * of these exit non-zero in states a real worktree reaches: `symbolic-ref`
@@ -412,6 +418,10 @@ export function createAgentTurnExecution({
     let videoNote = '';
     const runCli = (args) => {
       if (run.interrupted) return Promise.resolve('');
+      // Preparation awaits external work; remeasure before each fresh or
+      // resumed spawn, before replacing Codex's own repository discovery.
+      assertWorktree(wt, worktreeRepo);
+      args.verifiedWorktree = true;
       args = withUiReview(args, uiReviewNote, uiReview?.env);
       args = withUiReview(args, videoNote);
       return runTurnImpl(args);
@@ -667,6 +677,10 @@ export function createAgentTurnExecution({
         // (runTurn.mjs, `initHarvestFor`). An agent-only box learns from the
         // startup probe and its Terminal tabs.
         onSpawn: (ch) => {
+          let releaseTurnLock;
+          try { releaseTurnLock = recordTurnLock(turnLock, ch.pid); }
+          catch (error) { killGroup(ch); throw error; }
+          ch.once('close', releaseTurnLock);
           if (orchestrator && rt === 'codex') run.live?.connect((id, body) => orchestrator.input(id, body));
           if (rt !== 'claude') reportDelivery('agent', job, 'taken');
           brief?.running(true);

package/bin/lib/workPlaces.mjs

@@ -13,9 +13,10 @@
  * so a lane that learns a place cannot store one unvalidated.
  */
 import { readRepositoryPlace } from './repositoryPlaces.mjs';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { git, isSafePathSegment, hasCommits, gitFailure, sessionBranch } from './git.mjs';
+import { assertWorktree } from './worktreeHealth.mjs';
 
 /** The place id meaning "the checkout", not a worktree. Must match the
  *  server's REPO_PLACE — it is a wire value, not a local convention. The
@@ -213,6 +214,7 @@ export function createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged })
    * same way adoption resolves a cwd, and for the same reason.
    */
   const placeWtFor = (placeId, baseAt) => {
+    placeWtFor.lastError = null;
     if (placeId === REPO_PLACE) {
       // The checkout. `fresh: false` on purpose — nothing was opened, so no
       // caller may treat this as a newly-cut branch.
@@ -220,7 +222,14 @@ export function createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged })
     }
     const wt = worktreePath(baseDir, placeId);
     if (!wt) return null;
-    const fresh = !existsSync(wt);
+    let fresh;
+    try {
+      fresh = !existsSync(wt) || readdirSync(wt).length === 0;
+      if (!fresh) assertWorktree(wt, repoRoot);
+    } catch (error) {
+      placeWtFor.lastError = error.message;
+      return null;
+    }
     if (fresh) {
       const branch = sessionBranch(placeId);
       // `baseAt` is the adoption override: a tab born from a terminal session
@@ -276,6 +285,8 @@ export function createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged })
       // always did (runTurn.mjs spawns with `{...process.env}`), so anything
       // exported in the shell the daemon was started from is present here.
     }
+    try { assertWorktree(wt, repoRoot); }
+    catch (error) { placeWtFor.lastError = error.message; return null; }
     return { wt, fresh };
   };
 

package/bin/lib/workRetire.mjs

@@ -12,6 +12,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { git, isSafePathSegment } from './git.mjs';
 import { PERSON_PLACE_PREFIX } from './workPlaces.mjs';
+import { placeTurnLockedByLivePid } from './turnLock.mjs';
 
 export function createWorkRetire({
   repositoryPlaces,
@@ -24,6 +25,7 @@ export function createWorkRetire({
   workTokens,
   agentChildren,
   sweepMergedSessionBranch,
+  sessionMetaPath,
 }) {
   /**
    * Retire the worktrees of sessions the server says are CLOSED.
@@ -111,6 +113,8 @@ export function createWorkRetire({
       if (placeLocks.has(placeOf(id)) || shipping.has(id)) continue; // still draining here
       const wt = join(dir, id);
       try {
+        const places = repositoryPlaces?.stateFor(id) ? repositoryPlaces.entries(id).filter(r => r.writable).map(r => r.wt) : [wt];
+        if (places.some(path => placeTurnLockedByLivePid(sessionMetaPath?.(path, 'flowviant-turn.lock')))) continue;
         // Uncommitted work is the human's — a resource sweep does not outrank
         // it, closed tab or not. (The non-force remove would refuse anyway;
         // the explicit check keeps the intent legible.)
@@ -179,6 +183,7 @@ export function createWorkRetire({
       if (placeLocks.has(place)) continue;
       const wt = join(baseDir, 'sessions', place);
       try {
+        if (placeTurnLockedByLivePid(sessionMetaPath?.(wt, 'flowviant-turn.lock'))) continue;
         if (git(['status', '--porcelain'], wt).trim() !== '') continue;
         git(['merge', '--ff-only', baseRef()], wt);
       } catch {

package/bin/lib/worktreeHealth.mjs

@@ -0,0 +1,23 @@
+/** Verify the directory itself, rather than a parent git happened to discover. */
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { git } from './git.mjs';
+
+export function assertWorktree(wt, repoRoot) {
+  try {
+    const top = realpathSync(git(['rev-parse', '--show-toplevel'], wt));
+    if (top !== realpathSync(wt)) throw new Error('the directory is not a git worktree root');
+    const common = (dir) => realpathSync(resolve(dir, git(['rev-parse', '--git-common-dir'], dir)));
+    if (common(wt) !== common(repoRoot)) throw new Error('the worktree belongs to another repository');
+    const registered = git(['worktree', 'list', '--porcelain', '-z'], repoRoot).split('\0')
+      .some(line => {
+        if (!line.startsWith('worktree ')) return false;
+        try { return realpathSync(line.slice(9)) === top; } catch { return false; }
+      });
+    if (!registered) throw new Error('the worktree is not registered with this repository');
+    git(['rev-parse', '--verify', 'HEAD'], wt);
+  } catch (error) {
+    const why = error.stderr?.toString().trim() || error.message;
+    throw new Error(`The worktree at ${wt} is unavailable: ${why}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.23",
+  "version": "0.125.24",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {