flowviant 0.53.0 → 0.54.0

package/README.md

@@ -1,15 +1,18 @@
 # flowviant
 
-Run your own [Claude Code](https://claude.com/claude-code) as headless build agents for [Flowviant](https://flowviant.com). You manage a team of agents in the app; this daemon runs them on your machine, on your own credentials — Flowviant never sees your Claude or GitHub logins.
+Run your own coding CLIs as build agents for [Flowviant](https://flowviant.com) — [Claude Code](https://claude.com/claude-code), Codex or Antigravity, on your own credentials. This daemon holds your sessions, keeps a worktree per tab, and ships branches on your word. Flowviant never sees your Claude, Codex or GitHub logins.
 
 ```bash
-npx flowviant login      # approve the code in Flowviant → connected
-npx flowviant            # run your fleet
+npx flowviant@latest login   # approve the code in Flowviant → connected
 ```
 
+Login keeps going straight into the daemon — there is no second command to run.
+
 ## What it does
 
-You create named agents in Flowviant and dispatch work to them. This daemon, running on a machine you control, gives each agent its own git worktree and drives **your** locally-authenticated `claude` to do the work — it claims a task, works it, captures evidence for each acceptance criterion, opens a pull request, and routes any question it can't answer back to you as a blocker. You review and merge in the app.
+A Flowviant project has ONE machine, and this is it: one box, running one Claude (or Codex, or Antigravity) account, serving the whole team's sessions so nobody has to set up their own. Solo and team are the same architecture at N=1 and N>1.
+
+You work in the **Workbench**, where your sessions are TABS — each one a held context plus a persistent git worktree on its own `session/<id>` branch. The browser is a terminal projected onto this machine, so you reach the same session from any device. When you say ship, the tab merges its own branch into base with `--no-ff` — no squash, so the commit shas the work reported still exist on main.
 
 Because it drives the CLIs you're already logged into, **the cost is yours** (your Claude subscription, your GitHub) and **the daemon never handles a credential** — it shells out to tools you authenticated yourself.
 
@@ -17,9 +20,9 @@ Because it drives the CLIs you're already logged into, **the cost is yours** (yo
 
 On the machine that runs the daemon:
 
-- **[Claude Code](https://claude.com/claude-code)** installed and signed in (`claude`)
-- **[GitHub CLI](https://cli.github.com)** authenticated (`gh auth login`) — for opening PRs
+- **at least one coding CLI** installed and signed in — [Claude Code](https://claude.com/claude-code) (`claude`), Codex (`codex`) or Antigravity (`agy`)
 - **git**, and **Node 20+**
+- **[GitHub CLI](https://cli.github.com)** (`gh`) — optional; the daemon offers to fetch an isolated copy, and `flowviant gh-auth` signs it in
 - run it from inside the git repository you want worked
 
 ## Connecting
@@ -27,53 +30,44 @@ On the machine that runs the daemon:
 The easy way — device login, like `gh auth login`:
 
 ```bash
-npx flowviant login
+npx flowviant@latest login
 ```
 
-It shows a short code; enter it in Flowviant under **Agents → Connect a machine**. The credential is stored at `~/.flowviant/credentials.json`, and from then on `npx flowviant` just runs.
+It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `npx flowviant@latest` just runs.
 
-Prefer an explicit token? Create a fleet credential in the app and pass it directly:
+Prefer an explicit token? Create a machine credential in the app and pass it directly:
 
 ```bash
-FLOWVIANT_FLEET=fva_… npx flowviant
+FLOWVIANT_FLEET=fva_… npx flowviant@latest
 ```
 
-## Live mode (the default)
-
-Each task runs a **persistent** Claude session you can talk to mid-task from the app: the agent streams its work into the task's conversation, you `@`-mention it to steer or answer questions, and it resumes in place. Blockers park the session at zero cost until you answer. When it finishes, it posts a delivery card (summary + checklist self-report) in the thread — a human confirms done by merging there.
+Launch with `@latest` so each start pulls the newest published version — a bare `npx flowviant` can reuse a stale cache. A running daemon also self-updates at startup and when idle (`FLOWVIANT_NO_UPDATE=1` makes it nag-only; `flowviant update` updates now).
 
-Prefer the legacy one-shot poll mode (no streaming, no previews)? Escape hatch:
+## Sessions
 
-```bash
-FLOWVIANT_POLL=1 npx flowviant
-```
+Each tab in the Workbench is a persistent Claude session with its own worktree, and it stays where you left it — the branch outlives the tab. The daemon runs each turn in event mode and relays what the CLI is printing (thinking, reads, greps, commands) back to the tab, reports the worktree's branch and diffstat after every turn, and fetches a commit's patch when you click a sha in the app.
 
-### Live previews
+Nothing starts work except you opening a tab and typing in it.
 
-For UI/API tasks, the daemon can start the branch's dev server in the agent's worktree and open a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel so you can drive the real running change during review — no Cloudflare account needed (it's auto-fetched if missing). Configure it once per repo, or let it infer common setups:
+## Sharing a preview
 
-```json
-// .flowviant/preview.json
-{ "ui": { "cmd": "npm run dev", "port": 5173 } }
-```
+You run your dev server yourself, in the session's own worktree, exactly as you would in any terminal. The daemon NOTICES the listening port; ask for a share in the app and it puts a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel in front of it (auto-fetched if missing, pinned and checksummed) behind a **mandatory password gate**. Flowviant stores only the tunnel URL; your browser talks to it directly.
 
-Flowviant only stores the tunnel URL; your browser talks to it directly.
+The daemon never executes anything the repository declares. An earlier version read a `.flowviant/preview.json` from the branch and spawned the command it named — that start path was removed in 0.53.0 and is not coming back; see the header of `bin/lib/preview.mjs` for exactly what it did, so nobody rebuilds it.
 
 ## Modes
 
 | Env | What runs |
 | --- | --- |
-| _(stored login)_ or `FLOWVIANT_FLEET` | **Fleet daemon** — one worktree + worker per agent on your roster, managed in the app |
-| `FLOWVIANT_TOKEN` | a single agent in the current checkout |
-| `FLOWVIANT_TOKENS=a,b,c` | a static fleet, one worktree each |
+| _(stored login)_ or `FLOWVIANT_FLEET` | **the daemon** — the project's machine, serving its sessions |
 | `FLOWVIANT_SAFE=1` | restrict the toolset instead of running unattended |
 
 ## Security posture
 
-Every project member with edit access can run turns on this machine —
-Workbench tabs and @-dispatches both execute a coding agent with the daemon's
-own OS permissions. Membership is the consent boundary, the same trust plane
-as the shared repository: invite people you would give a shell to.
+Every project member with edit access can run turns on this machine — a
+Workbench tab executes a coding agent with the daemon's own OS permissions.
+Membership is the consent boundary, the same trust plane as the shared
+repository: invite people you would give a shell to.
 
 Two knobs bound the blast radius, and both are worth setting on a shared box:
 

package/bin/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 /**
- * flowviant — run your own Claude Code as headless Flowviant build agents.
+ * flowviant — run your own coding CLI (Claude Code, Codex, Antigravity) as the
+ * machine behind a Flowviant project.
  *
  * ONE mode, one credential:
  *
- *   FLOWVIANT_FLEET=fft_…   npx flowviant@latest  # the fleet daemon
+ *   FLOWVIANT_FLEET=fva_…   npx flowviant@latest  # the machine daemon
  *
  * `FLOWVIANT_TOKEN` (one worker, current checkout) and `FLOWVIANT_TOKENS` (a
  * comma list, one worktree each) stood beside it until 2026-08-19. Both ran the
@@ -19,28 +20,32 @@
  * on its own — at startup and when idle — so it stays current without restarts
  * (FLOWVIANT_NO_UPDATE=1 makes it nag-only; `flowviant update` updates now).
  *
- * Fleet daemon: install ONCE with a fleet credential, then manage everything
- * from Flowviant. The daemon polls GET /api/v2/fleet/agents, reconciles one
- * persistent git worktree + worker loop per roster agent, rotates each worker's
- * short-lived MCP token, and only spawns Claude when an agent has work. Add/remove
- * agents in the app — the daemon picks up the change on its next poll. Each worker
- * claims its work, resets its worktree to base per task (fresh Claude conversation),
- * opens one PR per intent, and routes questions back as blockers.
+ * The daemon: install ONCE with a machine credential, then work entirely from
+ * Flowviant. It polls GET /api/v2/fleet/agents, and the roster hands it the
+ * project's SESSIONS — the Workbench's tabs. Each session gets one persistent
+ * git worktree on its own `session/<id>` branch, held across turns (never reset
+ * to base: the branch outlives the tab). A turn spawns the session's CLI with a
+ * short-lived per-session MCP token, relays what it prints back to the tab,
+ * reports the worktree's branch and diffstat when it settles, and answers the
+ * odd side job the roster carries — a commit's patch, a preview share, a wiki
+ * regen. When you say ship, the daemon merges that branch into base `--no-ff`.
  *
  * Env:
- *   FLOWVIANT_TOKEN / FLOWVIANT_TOKENS / FLOWVIANT_FLEET  (one of) credentials.
+ *   FLOWVIANT_FLEET     the machine credential (or use `flowviant login`).
  *   FLOWVIANT_API_URL   default https://api.flowviant.com/api/v2
  *   FLOWVIANT_MCP_URL   default <API_URL>/mcp
  *   FLOWVIANT_FLEET_URL default <API_URL>/fleet/agents
- *   POLL_SECONDS        gap between turns while waiting on a blocker (default 20)
- *   IDLE_SECONDS        gap between work checks when idle (default 30)
- *   RECONCILE_SECONDS   fleet roster poll cadence (default 10)
+ *   RECONCILE_SECONDS   roster poll cadence (default 10)
  *   FLOWVIANT_SAFE=1    restrict the toolset instead of running unattended.
  *
- * Requires the `claude` CLI (and `gh` for PRs) on PATH; run from inside the git
- * repo you want worked. Fleet & static-fleet modes also require `git`.
+ * Requires one of `claude` / `codex` / `agy` on PATH, plus `git`; run from
+ * inside the git repo you want worked. `gh` is optional.
  *
- * Implementation lives in ./lib/: config, ui, claude, git, fleet, single.
+ * Implementation lives in ./lib/: config, ui, preflight, install, update,
+ * instance, login, mcp-cli; fleet (the roster loop) and work (session turns);
+ * claude + runtimes + prompts + stream (spawning a CLI and reading its events);
+ * git + worktreeDiff + patch; localSessions, listeners, preview + authproxy;
+ * env + env-cli + vault, resources, deploy, shot.
  */
 import { FLEET_TOKEN } from './lib/config.mjs';
 import { runFleetDaemon } from './lib/fleet.mjs';
@@ -132,9 +137,9 @@ if (process.argv[2] === 'clean') {
 }
 
 // `flowviant shot <url>` — capture a headless-browser screenshot of a running
-// page. Build agents shell out to this to attach REAL visual evidence to the
-// delivery card. Self-contained + graceful (no browser → exit 1, agent falls
-// back to text evidence); needs no credential, so it runs before the auth gate.
+// page. A session's agent shells out to this to SEE the change it just made.
+// Self-contained + graceful (no browser → exit 1, and the agent carries on in
+// text); needs no credential, so it runs before the auth gate.
 if (process.argv[2] === 'shot') {
   const { runShot } = await import('./lib/shot.mjs');
   await runShot(process.argv.slice(3));
@@ -145,8 +150,9 @@ if (process.argv[2] === 'shot') {
 // are sealed to the project pubkey ON THIS MACHINE (same write-only crypto as
 // the browser); `show` decrypts locally — it only works on an ENROLLED machine.
 // `flowviant mcp` — connect YOUR Claude to Flowviant so you can file work from
-// the terminal. Mints a `cli` credential: a separate principal from the build
-// workers, with only the management tools and no way to claim or ship work.
+// the terminal. Mints a `cli` credential: a separate principal from the
+// per-session tokens, with only the management tools and no way to work or ship
+// a card.
 if (process.argv[2] === 'mcp') {
   const { runMcpCommand } = await import('./lib/mcp-cli.mjs');
   await runMcpCommand(process.argv.slice(3));
@@ -164,7 +170,7 @@ if (!FLEET_TOKEN) {
     'error: no credential found. Easiest:\n' +
       '  flowviant login      (approve in the app — recommended)\n' +
       'Or set:\n' +
-      '  FLOWVIANT_FLEET=fft_…   (fleet token, manage machines in Flowviant)'
+      '  FLOWVIANT_FLEET=fva_…   (machine token, from the app)'
   );
   process.exit(1);
 }

package/bin/lib/config.mjs

@@ -44,11 +44,6 @@ function argFlag(name) {
   return i >= 0 ? process.argv[i + 1] : undefined;
 }
 
-/** A bare boolean flag (no value follows it). */
-function hasFlag(name) {
-  return process.argv.includes(name);
-}
-
 const API_BASE = process.env.FLOWVIANT_API_URL || 'https://api.flowviant.com/api/v2';
 export const MCP_URL = process.env.FLOWVIANT_MCP_URL || `${API_BASE}/mcp`;
 export const FLEET_URL = process.env.FLOWVIANT_FLEET_URL || `${API_BASE}/fleet/agents`;
@@ -149,22 +144,6 @@ export const AUTO_UPDATE = process.env.FLOWVIANT_NO_UPDATE !== '1';
 // path (one-shot `claude -p` turns) survives behind FLOWVIANT_POLL=1 as the
 // escape hatch; FLOWVIANT_LIVE=1 is still honored for old scripts.
 export const LIVE = process.env.FLOWVIANT_POLL !== '1';
-/**
- * Does this machine accept PATCHES — commits cherry-picked straight into your
- * working checkout, with no PR and no review?
- *
- * Patch placement is chosen by a model, and any teammate who @mentions one of
- * your agents can trigger it, so whether it happens at all belongs to whoever
- * owns the checkout. Turning it off does not lose the work: the task falls back
- * to branch placement and arrives as a PR like anything else.
- *
- * On by default — the guard that actually protects you (never touching a file
- * you have uncommitted edits in) is enforced at apply time, and the whole point
- * of patches is to spare you a review cycle for a nine-character diff.
- * `--no-patches` or FLOWVIANT_PATCHES=0 to refuse them.
- */
-export const ALLOW_PATCHES =
-  !hasFlag('--no-patches') && process.env.FLOWVIANT_PATCHES !== '0';
 // Sent on the daemon's own HTTP calls so Cloudflare Bot Fight Mode doesn't 403
 // them (Node's default UA is treated as a bot). Claude Code sends its own UA.
 export const USER_AGENT = `flowviant/${VERSION}`;

package/bin/lib/fleet.mjs

@@ -31,7 +31,6 @@ import {
   REFRESH_BEFORE_SECONDS,
   LIVE,
   AUTO_UPDATE,
-  ALLOW_PATCHES,
 } from './config.mjs';
 import { handleVersionSignal } from './update.mjs';
 import {
@@ -78,7 +77,7 @@ import { detectRuntimes, knownSkills, pickRuntimeFor, RUNTIMES } from './runtime
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
 
-async function fetchRoster(haveIds, livePreviewSessionIds = []) {
+async function fetchRoster(haveIds, livePreviewSessionIds = [], heldSessionIds = []) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
   // What this machine will run at once. The server grows lanes to meet waiting
@@ -108,6 +107,11 @@ async function fetchRoster(haveIds, livePreviewSessionIds = []) {
   // the server still calls live is a 530 on somebody's phone. Always set, even
   // empty: '' means "serving none", absent would mean "an older daemon".
   url.searchParams.set('pv', livePreviewSessionIds.join(','));
+  // The sessions this daemon holds a worktree for. Its LEASE on each renews
+  // here — one beat, no extra endpoint, and the server can tell "this daemon is
+  // still serving that tab" from "it went away" within a reconcile interval
+  // instead of minutes. Always set, even empty: '' means "holding none".
+  url.searchParams.set('ws', heldSessionIds.join(','));
   // WHICH CLIs this machine actually has, so the app can stop guessing.
   //
   // Until now every surface that listed Gemini or Codex said "not wired up yet"
@@ -271,20 +275,13 @@ async function maybeReportLocalSessions({ repoRoot, excludeDirs }) {
 
 export async function runFleetDaemon() {
   console.log('');
-  console.log(`  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`fleet daemon · v${VERSION}`)}`);
+  console.log(`  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`machine daemon · v${VERSION}`)}`);
   console.log(`  ${c.dim('──────────────────────────────────────────────')}`);
   const repoRoot = repoRootOrDie();
   const baseRef = detectBaseRef(repoRoot);
   info(SAFE ? 'mode   · safe (restricted toolset)' : 'mode   · unattended (skips permission prompts)');
   info(`repo   · ${repoRoot}`);
   info(`base   · ${baseRef}`);
-  // Stated out loud because it is the one setting that lets something else write
-  // into the checkout you are sitting in.
-  info(
-    ALLOW_PATCHES
-      ? 'patches· accepted — small changes land in your checkout for Keep/Revert (--no-patches to refuse)'
-      : 'patches· refused — everything arrives as a branch + PR'
-  );
   info(`server · ${FLEET_URL}`);
   console.log('');
 
@@ -295,18 +292,42 @@ export async function runFleetDaemon() {
   // the SAME project served twice, and the worst version of this: their session
   // worktrees are in different directories, so the per-turn lock cannot even see
   // across them. See instance.mjs for why that lock is not enough on its own.
-  const instance = acquireInstanceLock(FLEET_TOKEN, repoRoot);
+  // Same repo -> this run replaces whatever was serving it. Different repo ->
+  // refused, and nothing is signalled. See instance.mjs's header for the rule.
+  const instance = acquireInstanceLock(FLEET_TOKEN, repoRoot, {
+    takeover:
+      process.argv.includes('--takeover') || process.argv.includes('--takeover-downgrade'),
+    noTakeover:
+      process.argv.includes('--no-takeover') || process.env.FLOWVIANT_NO_TAKEOVER === '1',
+    allowDowngrade: process.argv.includes('--takeover-downgrade'),
+    log: (m) => info(m),
+  });
   if (!instance.ok) {
     const h = instance.holder;
     console.log('');
-    fail('a flowviant daemon is already running for this credential.');
+    // Two different refusals, because they are two different mistakes and the
+    // fix is not the same. Same CREDENTIAL: one project is being served twice.
+    // Same REPO under another credential: two daemons in one working tree,
+    // which the credential-keyed lock cannot see on its own.
+    if (instance.takeoverFailed) {
+      fail(`could not replace the running daemon: ${instance.takeoverFailed}`);
+    } else if (instance.sameRepo) {
+      fail('a flowviant daemon is already running in this repo.');
+    } else {
+      fail('a flowviant daemon is already running for this credential.');
+    }
     if (h?.pid) info(`holder · pid ${h.pid}${h.repoRoot ? ` in ${h.repoRoot}` : ''}`);
     // The two-checkouts case is the one nobody spots on their own: both tabs
     // look healthy, and the damage is doubled cards and doubled edits in a repo
     // you are not looking at. Name the other repo when it is a different one.
-    if (h?.repoRoot && h.repoRoot !== repoRoot)
+    if (!instance.sameRepo && h?.repoRoot && h.repoRoot !== repoRoot) {
       warn('that is a DIFFERENT checkout — one credential serves one project, so both would answer the same tabs.');
-    note('stop the other one first, or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
+      // Not offered lightly: that daemon is serving other work, and this
+      // command was run somewhere else. Replacing it is a decision, not a
+      // restart, so it takes a word.
+      note('run with --takeover to stop it and serve this repo instead.');
+    }
+    note('or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
     console.log('');
     process.exit(1);
   }
@@ -606,6 +627,7 @@ export async function runFleetDaemon() {
     processWorkTurns,
     processShipJobs,
     processDiffJobs,
+    heldSessionIds,
     processPreviewJobs,
     livePreviewIds,
     retirePreviews,
@@ -873,20 +895,42 @@ export async function runFleetDaemon() {
 
   // Changed files of a (merged) PR, for the re-ground prompt. Capped so a huge
   // PR can't blow up the prompt. prUrl was already validated before the merge.
-  // Returns null on a gh FAILURE (network/auth) — distinct from a PR that
-  // genuinely changed nothing — so the caller can retry instead of silently
-  // consuming the durable job with no re-ground run.
-  const changedFilesForPr = (prUrl) => {
-    try {
-      const out = execFileSync('gh', ['pr', 'view', prUrl, '--json', 'files'], {
-        cwd: repoRoot,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-      return (JSON.parse(out).files ?? []).map((f) => f.path).filter(Boolean).slice(0, 60);
-    } catch {
-      return null;
+  // WHICH FILES A SHIP CHANGED, read from the commits it landed.
+  //
+  // This asked `gh pr view <prUrl> --json files` until 2026-08-22, and `prUrl`
+  // has been null by construction since dispatch was deleted on 2026-08-19 —
+  // the server writes null and says so in a comment. Node threw on the null
+  // argument, the catch below read it as "gh failed", and the re-ground retried
+  // three times and gave up. Every post-ship re-ground for three months did
+  // that silently, while the spec said ship re-grounds the wiki.
+  //
+  // Returns null when it learned NOTHING (no shas, or none of them resolvable),
+  // which the caller still treats as retryable — distinct from a ship that
+  // genuinely changed no files.
+  const changedFilesForShas = (shas) => {
+    if (!Array.isArray(shas) || shas.length === 0) return null;
+    const files = new Set();
+    for (const sha of shas.slice(0, 50)) {
+      if (!/^[0-9a-f]{7,40}$/i.test(String(sha))) continue;
+      try {
+        const out = execFileSync(
+          'git',
+          ['show', '--name-only', '--pretty=format:', String(sha)],
+          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }
+        );
+        for (const line of out.split('\n')) {
+          const f = line.trim();
+          if (f) files.add(f);
+          if (files.size >= 60) break;
+        }
+      } catch {
+        // One unreachable commit is not a failed re-ground — the ship merged
+        // to main and the rest of the shas still name real files. Only an
+        // EMPTY result is treated as "we learned nothing".
+      }
+      if (files.size >= 60) break;
     }
+    return files.size ? [...files] : null;
   };
   const regroundAttempts = new Map(); // intentId -> gh-failure count
 
@@ -1042,7 +1086,7 @@ export async function runFleetDaemon() {
               warn('wiki sweep ended without WIKI_DONE — partial pages synced; retry from the app.');
             await runSync(complete);
           } else {
-            const files = changedFilesForPr(task.prUrl);
+            const files = changedFilesForShas(task.shas);
             if (files === null) {
               // gh failed (network/auth) — retry via the durable job a couple
               // of times before consuming it, so a transient outage doesn't
@@ -1050,11 +1094,11 @@ export async function runFleetDaemon() {
               const n = (regroundAttempts.get(task.intentId) ?? 0) + 1;
               regroundAttempts.set(task.intentId, n);
               if (n < 3) {
-                warn(`wiki re-ground for "${task.title}": gh failed — will retry (${n}/3)`);
+                warn(`wiki re-ground for "${task.title}": no changed files resolved — will retry (${n}/3)`);
                 groundedIntents.delete(task.intentId); // let the roster re-offer it
                 continue;
               }
-              warn(`wiki re-ground for "${task.title}": gh failed ${n} times — giving up (heals on the next full sweep)`);
+              warn(`wiki re-ground for "${task.title}": could not resolve changed files ${n} times — giving up (heals on the next full sweep)`);
             } else if (files.length === 0) {
               note(`${c.cyan('wiki')} ${c.dim(`— "${task.title}": no changed files to re-ground`)}`);
             } else {
@@ -1170,7 +1214,7 @@ export async function runFleetDaemon() {
   for (;;) {
     let roster;
     try {
-      roster = await fetchRoster(buildHave(), livePreviewIds());
+      roster = await fetchRoster(buildHave(), livePreviewIds(), heldSessionIds());
     } catch (e) {
       if (e.auth) {
         fail(`${e.message} — credential revoked or invalid. Shutting down.`);
@@ -1237,7 +1281,16 @@ export async function runFleetDaemon() {
     // in a directory that no longer exists — a human is shown the wrong thing
     // and nothing errors anywhere.
     retirePreviews(roster.activeWorkSessions);
-    retireWorkSessions(roster.activeWorkSessions);
+    // A session another daemon on this credential is serving is NOT a closed
+    // tab. Without this the daemon that lost the lease removes the worktree the
+    // winner is working in — absence would mean "somebody else won" instead of
+    // "the tab closed".
+    retireWorkSessions(
+      Array.isArray(roster.activeWorkSessions)
+        ? roster.activeWorkSessions
+        : roster.activeWorkSessions,
+      roster.sessionsHeldElsewhere
+    );
     // Diffs somebody has open and is waiting on. Project-scoped rather than
     // per-session: `git show` runs from the repo ROOT, which can see a closed
     // tab's branch and a shipped commit on main alike.
@@ -1262,24 +1315,23 @@ export async function runFleetDaemon() {
     const sig = [...rosterIds].sort().join(',');
     if (sig !== rosterSig) {
       rosterSig = sig;
-      if (rosterIds.size === 0) {
-        // `agents` is permanently [] — the lanes it counted died with dispatch
-        // and the array survives only as wire compat. So this branch is the one
-        // that always runs, and it used to point at the Cockpit, a surface
-        // deleted 2026-08-04 that now redirects to the Board. Say what is
-        // actually true instead: the machine is up, and work starts in a tab.
-        info('Machine online. Open a tab in Flowviant → Workbench to start working.');
-      } else {
-        note(`Roster: ${c.bold(String(rosterIds.size))} agent${rosterIds.size === 1 ? '' : 's'}.`);
-      }
+      // `agents` is permanently [] — the lanes it counted died with dispatch
+      // and the array survives only as wire compat, so this runs once, on the
+      // first poll. It used to point at the Cockpit, a surface deleted
+      // 2026-08-04 that now redirects to the Board. Say what is actually true
+      // instead: the machine is up, and work starts in a tab.
+      info('Machine online. Open a tab in Flowviant → Workbench to start working.');
     }
-    // Heartbeat so a quiet/empty daemon visibly stays alive.
-    if (rosterIds.size === 0 && Date.now() - idleBeatAt > 60_000) {
+    // Heartbeat so a quiet daemon visibly stays alive. Gated on REAL work —
+    // `rosterIds` is built from `roster.agents`, which the server sends
+    // permanently empty, so gating on it printed "waiting" once a minute even
+    // while a tab's turn was running. `workBusy()` is the honest question: are
+    // there session turns, ships or unsettled reports in flight?
+    if (!workBusy() && Date.now() - idleBeatAt > 60_000) {
       idleBeatAt = Date.now();
-      info('idle — waiting for agents…');
+      info('machine online — nothing running right now.');
     }
 
-
     // Living-wiki work (runs under its own minted wiki token — no agent
     // needed). enqueueSweep queues a Regenerate; regroundJobs re-offers merged
     // deliveries whose re-ground never ran (e.g. we restarted between merge and
@@ -1295,13 +1347,18 @@ export async function runFleetDaemon() {
 
     // Env sync tick: register/bootstrap/wrap/rotate/sync as the roster block
     // dictates (self-guarded — one operation at a time, errors retry next
-    // poll). A fresh bundle rematerializes every AGENT worktree; the wiki
-    // worktree NEVER gets env (the cartographer doesn't need secrets).
+    // poll). A fresh bundle rematerializes every SESSION worktree this daemon
+    // holds — read off the sessions directory, the same fact retirement acts
+    // on; the wiki worktree NEVER gets env (the cartographer doesn't need
+    // secrets). This used to iterate the dispatch-era `workers` map, which
+    // nothing has ever `.set()`, so a rotation reached no worktree at all.
+    // Safe mid-turn by construction: materializeInto refuses to write anything
+    // git does not ignore, so it cannot dirty a tree and block a ship.
     void handleRosterEnv(roster.env, { projectId: roster.project?.id }).then(({ changed }) => {
       if (!changed) return;
-      for (const [, w] of workers) {
+      for (const id of heldSessionIds()) {
         try {
-          materializeInto(w.wt);
+          materializeInto(join(baseDir, 'sessions', id));
         } catch {
           /* best-effort */
         }

package/bin/lib/git.mjs

@@ -35,7 +35,7 @@ export function repoRootOrDie() {
   try {
     return git(['rev-parse', '--show-toplevel'], process.cwd());
   } catch {
-    console.error('error: fleet mode must run inside a git repo.');
+    console.error('error: the flowviant daemon must run inside a git repo.');
     process.exit(1);
   }
 }

package/bin/lib/instance.mjs

@@ -1,11 +1,24 @@
 /**
- * ONE DAEMON PER CREDENTIAL, refused at startup.
+ * ONE DAEMON PER REPO (and per credential), ARBITRATED at startup — a second
+ * run in the same repo takes the first one's place rather than being turned
+ * away. See "WHAT A SECOND RUN DOES" below for the whole rule.
  *
- * WHY THIS EXISTS. Nothing stopped two daemons before, and the server hands
- * work out by READING, never claiming: `listWorkTurnJobs` selects every pending
- * turn for the fleet token, `listShipJobs` reads a flag. So two daemons on one
- * credential are offered the SAME turn — and the ProjectRoom nudges every
- * connected daemon socket at once, so they do not even drift out of phase.
+ * WHY THIS EXISTS. Nothing stopped two daemons before, and the server USED to
+ * hand work out by READING, never claiming: `listWorkTurnJobs` selected every
+ * pending turn for the machine credential, `listShipJobs` read a flag. So two
+ * daemons on one credential were offered the SAME turn — and the ProjectRoom
+ * nudges every connected daemon socket at once, so they did not even drift out
+ * of phase.
+ *
+ * That half is fixed on the server now: since 0.53.0 each SESSION is leased to
+ * one daemon INSTANCE nonce — `di`, regenerated every start (config.mjs) and
+ * sent on every poll beside `ws`, the list of sessions this daemon holds a
+ * worktree for — so a turn is handed to the instance holding that session and
+ * to no one else. It does NOT retire this lock. The lease fails OPEN when no
+ * instance is reported (an older daemon cannot name itself), and it arbitrates
+ * only what rides a session: the wiki sweep, env materialization, previews,
+ * deploys and every worktree operation the server never sees are still first
+ * come, first served.
  *
  * The per-worktree `flowviant-turn.lock` cannot save it. That lock is written
  * AFTER the work token is minted and the attachments are fetched — a window
@@ -14,27 +27,70 @@
  * (its own comment says so, work.mjs), where the holder is already live when
  * the successor looks; it was never a concurrency primitive.
  *
- * What the duplicate run costs, all of it invisible in the tab: two Claudes
- * editing one worktree, two cards from one `file_card` (no idempotency key),
- * the session write budget spent twice, quota spent twice — and then exactly
- * ONE answer survives, because `settleWorkTurn` is atomic. The side effects
- * land twice and the transcript shows one turn.
+ * What a duplicate run cost before the session lease, all of it invisible in
+ * the tab: two Claudes editing one worktree, two cards from one `file_card` (no
+ * idempotency key), the session write budget spent twice, quota spent twice —
+ * and then exactly ONE answer surviving, because `settleWorkTurn` is atomic.
+ * The side effects landed twice and the transcript showed one turn. Two daemons
+ * in one checkout still cost the un-leased half of that: two `git fetch`, two
+ * worktree sweeps, and the collisions listed under ONE DAEMON PER REPO below.
  *
- * KEYED ON THE CREDENTIAL, NOT THE REPO. The credential is stored once, at
+ * KEYED ON THE CREDENTIAL — and, as the next paragraph adds, on the REPO as
+ * well; both checks run, and either one is enough. The credential is stored once, at
  * ~/.flowviant/credentials.json, so `flowviant` in two DIFFERENT checkouts is
  * still one project served twice — and that case is strictly worse, because the
  * two daemons have different worktree roots and the turn lock cannot even see
  * across them. Keying on the token catches both, and still lets a second
  * credential run a second project on the same machine.
  *
+ * ...AND ONE DAEMON PER REPO, which is NOT the same statement. The lock above
+ * is keyed on the credential, and the two coincide only while one credential
+ * serves one project — which is the product's law but not a thing this file can
+ * assume. Two DIFFERENT credentials pointing at one checkout both acquired
+ * happily (measured), giving two daemons in one working tree: two `git fetch`,
+ * two worktree sweeps, `retireWorkSessions` in one removing directories the
+ * other is serving, and a ship in one racing a rebase in the other. No server
+ * lease can arbitrate any of that, because the server never sees a directory.
+ * So the repo is checked too, across every credential's lock.
+ *
+ * WHAT A SECOND RUN DOES, and this is the whole rule:
+ *
+ *   SAME REPO      -> the new run WINS. The holder is asked to stand down and
+ *                     this daemon takes its place. Re-running `flowviant` in a
+ *                     directory you are working in means "serve this repo", and
+ *                     the process already serving it is by definition the one
+ *                     you are replacing. That is a restart, and a restart
+ *                     should not require you to go and find a pid.
+ *
+ *   DIFFERENT REPO -> REFUSED, and nothing is signalled. That daemon is serving
+ *                     other work; killing it because you happened to run this
+ *                     command elsewhere is not a restart, it is collateral.
+ *                     `--takeover` overrides, deliberately explicitly.
+ *
+ * One rule, and it is the invariant stated as behaviour: one daemon per repo.
+ * `--no-takeover` (or FLOWVIANT_NO_TAKEOVER=1) makes even the same-repo case
+ * refuse, for anyone who wants the old ceremony.
+ *
  * IT FAILS OPEN. A home directory we cannot write to is not a reason to refuse
  * to start; it is a reason to say so and carry on unguarded.
  */
 
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs';
+import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+import { VERSION } from './config.mjs';
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken) {
@@ -42,6 +98,20 @@ export function instanceLockPath(fleetToken) {
   return join(homedir(), '.flowviant', `daemon-${key}.lock`);
 }
 
+/** Numeric dotted compare, -1/0/1. Unparsable compares EQUAL, so a version we
+ *  cannot read never silently authorises a downgrade. */
+function cmpVersion(a, b) {
+  const x = String(a).split('.').map((n) => Number.parseInt(n, 10));
+  const y = String(b).split('.').map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const p = x[i] ?? 0;
+    const q = y[i] ?? 0;
+    if (Number.isNaN(p) || Number.isNaN(q)) return 0;
+    if (p !== q) return p > q ? 1 : -1;
+  }
+  return 0;
+}
+
 /** Signal 0 — a liveness probe, not a kill. EPERM means alive and not ours. */
 function alive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -63,7 +133,192 @@ function readHolder(path) {
 }
 
 const record = (repoRoot) =>
-  JSON.stringify({ pid: process.pid, repoRoot, startedAt: new Date().toISOString() });
+  JSON.stringify({
+    pid: process.pid,
+    repoRoot,
+    startedAt: new Date().toISOString(),
+    // The script we were started from, and what we are. A takeover matches the
+    // live command line against `entry` before signalling anything — a lock
+    // records a PID, and a crashed daemon's PID can be reused by anything.
+    entry: process.argv[1] || '',
+    version: VERSION,
+  });
+
+/** Same directory, whatever it is spelled as — symlinks and trailing slashes
+ *  included. A repo compared by string would let `/repo` and `/repo/` past. */
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const norm = (v) => {
+    try {
+      return realpathSync(v);
+    } catch {
+      return String(v).replace(/\/+$/, '');
+    }
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * A LIVE daemon in this same checkout, under a DIFFERENT credential.
+ *
+ * The lock above cannot see one: it is keyed on the credential, so a second
+ * token in the same directory opens its own file and takes it. Every other
+ * lock file on this machine is ours to read, so read them.
+ *
+ * Returns the holder, or null. A stale file never blocks — it is cleared by
+ * whichever acquire owns it, and blocking on a corpse would be worse than the
+ * thing this prevents.
+ */
+/** Which lock file a neighbour holder was read from — takeOverFrom waits on it. */
+const NEIGHBOUR_PATHS = new WeakMap();
+function neighbourLockPath(holder, fallback) {
+  return NEIGHBOUR_PATHS.get(holder) ?? fallback;
+}
+
+export function daemonInSameRepo(repoRoot, ownPath) {
+  const dir = join(homedir(), '.flowviant');
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => /^daemon-[0-9a-f]{12}\.lock$/.test(f));
+  } catch {
+    return null;
+  }
+  for (const f of files) {
+    const path = join(dir, f);
+    if (path === ownPath) continue; // our own credential — the lock above owns that question
+    const holder = readHolder(path);
+    if (!holder || !alive(holder.pid)) continue;
+    if (holder.pid === process.ppid) continue; // ourselves mid self-update re-exec
+    if (samePath(holder.repoRoot, repoRoot)) {
+      NEIGHBOUR_PATHS.set(holder, path);
+      return holder;
+    }
+  }
+  return null;
+}
+
+/**
+ * IS THIS PID STILL THE DAEMON THAT TOOK THE LOCK?
+ *
+ * `process.kill(pid, 0)` says "a process exists", which is not the same claim,
+ * and the difference matters the moment we are about to signal it. Matched on
+ * the holder's own recorded ENTRYPOINT, never on the word "flowviant": a
+ * command line merely CONTAINING it matches a shell, an editor, or a test
+ * runner living under a `…-flowviant/` directory. That last one is not
+ * hypothetical — a looser version of this check SIGTERMed one.
+ *
+ * A lock with no `entry` predates this and is never signalled.
+ */
+function stillTheHolder(holder) {
+  const want = typeof holder?.entry === 'string' ? holder.entry : null;
+  if (!want) return false;
+  try {
+    if (platform() === 'linux') {
+      return readFileSync(`/proc/${holder.pid}/cmdline`, 'utf8').replace(/\0/g, ' ').includes(want);
+    }
+    return execFileSync('ps', ['-o', 'command=', '-p', String(holder.pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+    }).includes(want);
+  } catch {
+    return false; // gone, or unreadable — not something we signal
+  }
+}
+
+/** Blocking, because this runs before there is an event loop worth yielding to
+ *  and the caller cannot proceed until it knows whether the holder is gone. */
+const sleep = (ms) => {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    /* no SharedArrayBuffer — check again immediately */
+  }
+};
+
+/** How long the outgoing daemon gets to stand down cleanly. Its SIGTERM handler
+ *  kills the CLI children it spawned and stops its preview tunnels; both are
+ *  why we ask before we insist. */
+const TAKEOVER_GRACE_MS = 20_000;
+
+/**
+ * Ask the holder to stand down, then take its place.
+ *
+ * SIGTERM FIRST, and not out of politeness: the daemon's handler runs its
+ * teardown — it kills the CLI children it spawned and stops its preview
+ * tunnels, which are DETACHED and would otherwise keep a public hostname
+ * serving a worktree until the box reboots.
+ *
+ * WAIT ON THE LOCK FILE, not the pid. A departing daemon's release() removes it
+ * on exit, so the file changing IS the handover. `kill(pid, 0)` cannot see it:
+ * a process that exited but has not been reaped is a ZOMBIE and answers signal
+ * 0 exactly like a living one — measured, a peer that exited cleanly still read
+ * as alive for the full grace window.
+ *
+ * And "gone" is NOT "the file stopped naming our pid". It can stop naming it
+ * because the holder SELF-UPDATED: update.mjs re-execs and the successor adopts
+ * this same lock through the ppid branch. Treating that as free steals a live
+ * daemon's lock and leaves it running unguarded — measured doing exactly that.
+ */
+function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
+  if (!holder?.pid || !alive(holder.pid)) return null; // already gone
+  if (!stillTheHolder(holder)) {
+    return { failed: `pid ${holder.pid} is no longer the daemon that took this lock — refusing to signal it` };
+  }
+  if (!allowDowngrade && holder.version && cmpVersion(VERSION, holder.version) < 0) {
+    return {
+      failed: `the running daemon is ${holder.version} and this one is ${VERSION} — refusing to replace a newer daemon with an older one (--takeover-downgrade if you mean it)`,
+    };
+  }
+
+  log?.(`asking daemon pid ${holder.pid} to stand down…`);
+  try {
+    process.kill(holder.pid, 'SIGTERM');
+  } catch {
+    return { failed: `could not signal pid ${holder.pid}` };
+  }
+
+  const standing = () => {
+    const now = readHolder(path);
+    if (!now || !alive(now.pid)) return null;
+    return now;
+  };
+  const deadline = Date.now() + TAKEOVER_GRACE_MS;
+  for (;;) {
+    const now = standing();
+    if (!now) break;
+    if (now.pid !== holder.pid) {
+      return {
+        failed: `the daemon handed over to pid ${now.pid}${now.version ? ` (${now.version})` : ''} while we waited — it is mid-update, so try again in a moment`,
+      };
+    }
+    if (Date.now() >= deadline) {
+      log?.(`pid ${holder.pid} did not stand down within ${TAKEOVER_GRACE_MS / 1000}s — forcing it.`);
+      try {
+        process.kill(holder.pid, 'SIGKILL');
+      } catch {
+        /* exited in the gap */
+      }
+      sleep(600);
+      const after = standing();
+      if (after && after.pid !== holder.pid) {
+        return { failed: `the daemon handed over to pid ${after.pid} — try again in a moment` };
+      }
+      if (after) return { failed: `pid ${holder.pid} would not stop` };
+      break;
+    }
+    sleep(400);
+  }
+
+  // A SIGKILLed daemon never ran its release(), so clear what it left.
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    return { failed: 'could not clear the lock file' };
+  }
+  log?.(`daemon pid ${holder.pid} stopped — taking over.`);
+  return null;
+}
 
 /**
  * Take the lock, or report who holds it.
@@ -75,7 +330,8 @@ const record = (repoRoot) =>
  * `wx` is the whole guarantee: create-exclusive is one atomic syscall, which is
  * the property the turn lock's check-then-write does not have.
  */
-export function acquireInstanceLock(fleetToken, repoRoot) {
+export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
+  const { takeover: force = false, noTakeover = false, allowDowngrade = false, log } = opts;
   if (process.env.FLOWVIANT_ALLOW_MULTI === '1') return { ok: true, release: () => {} };
   const path = instanceLockPath(fleetToken);
   try {
@@ -84,6 +340,20 @@ export function acquireInstanceLock(fleetToken, repoRoot) {
     return { ok: true, release: () => {}, unguarded: true };
   }
 
+  // ONE DAEMON PER REPO, checked across every credential — see the header. This
+  // runs BEFORE we take our own lock, so a refusal leaves nothing behind.
+  const neighbour = daemonInSameRepo(repoRoot, path);
+  if (neighbour) {
+    // Same working tree, another credential. Under "one daemon per repo" the
+    // new run wins here too — but it is signalling a process that belongs to a
+    // DIFFERENT project, so it is worth saying out loud rather than doing
+    // quietly.
+    if (noTakeover) return { ok: false, holder: neighbour, sameRepo: true };
+    log?.(`another project's daemon is serving this repo (pid ${neighbour.pid}).`);
+    const bad = takeOverFrom(neighbour, neighbourLockPath(neighbour, path), log);
+    if (bad) return { ok: false, holder: neighbour, sameRepo: true, takeoverFailed: bad.failed };
+  }
+
   // Two passes at most: one to clear a stale holder, one to take the lock. A
   // loop here would spin against a peer that keeps re-taking it.
   for (let attempt = 0; attempt < 2; attempt++) {
@@ -118,7 +388,16 @@ export function acquireInstanceLock(fleetToken, repoRoot) {
         }
         return { ok: true, release: makeRelease(path) };
       }
-      return { ok: false, holder };
+      // THE RULE. Same repo -> this run replaces it; different repo -> refuse
+      // and signal nothing, unless --takeover says otherwise. See the header.
+      const here = samePath(holder.repoRoot, repoRoot);
+      const wanted = force || (here && !noTakeover);
+      if (wanted) {
+        const bad = takeOverFrom(holder, path, log, { allowDowngrade });
+        if (bad) return { ok: false, holder, takeoverFailed: bad.failed, sameRepo: here };
+        continue; // the file is gone — the next pass takes it
+      }
+      return { ok: false, holder, sameRepo: here };
     }
     try {
       writeSync(fd, record(repoRoot));

package/bin/lib/login.mjs

@@ -56,7 +56,11 @@ export async function runLogin({ thenStart = false } = {}) {
   }
   const { deviceCode, userCode, intervalSeconds = 5, expiresInSeconds = 600 } = start;
   const pretty = `${userCode.slice(0, 4)}-${userCode.slice(4)}`;
-  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Agents')} panel → ${c.bold('Connect a machine')}.`);
+  // Where the control ACTUALLY is. It was "the Agents panel", a settings
+  // section deleted 2026-08-17; connecting a machine is offered on the surface
+  // you are on when it matters, and for a new operator that is the Workbench —
+  // the project's empty state says so before it can show you any sessions.
+  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Workbench')} → ${c.bold('Connect a machine')}.`);
   console.log(`  2. Enter this code:   ${c.bold(c.green(pretty))}\n`);
   info('waiting for you to approve…');
 

package/bin/lib/mcp-cli.mjs

@@ -2,17 +2,18 @@
  * `flowviant mcp` — connect YOUR Claude to Flowviant so you can file work from
  * the terminal ("stick that on the board", "file a task for this TODO").
  *
- * This mints a `cli` credential, which is a different principal from the worker
- * tokens the daemon rotates for builds. That separation is the point, not
- * bookkeeping: a worker reads untrusted repo, PR and issue text all day, so
- * giving THAT principal tools that write to your workspace would mean a hostile
- * string in a README could file work as you. The cli credential sees only the
- * management tools and can never claim or complete work; the worker can never
- * reach create_task.
+ * This mints a `cli` credential, which is a different principal from the
+ * per-session `work` tokens the daemon mints for Workbench tabs. That
+ * separation is the point, not bookkeeping: a session's agent reads untrusted
+ * repo and issue text all day, so giving THAT principal tools that write to
+ * your workspace would mean a hostile string in a README could file work as
+ * you. The cli credential sees only the management tools and can never work or
+ * ship a card; a session token can never reach create_task.
  *
  * There is deliberately no invite capability on it. Invites grant access to a
- * paid workspace and are guarded by a human browser session; you ask Flowvy in
- * the app for those, and approve the card.
+ * paid workspace and are guarded by a human browser session — they are sent
+ * from the workspace card's gear menu in the app, and never from a CLI
+ * credential sitting on a shared machine.
  */
 
 import { FLEET_TOKEN, USER_AGENT, MCP_URL, FLEET_URL } from './config.mjs';
@@ -77,7 +78,7 @@ export async function runMcpCommand(args = []) {
   console.log(`  ${cmd}`);
   console.log('');
   console.log('Then, in any Claude session: "file a task in Flowviant for …".');
-  console.log('Tasks land as drafts — nothing runs until you open one in the');
-  console.log('app and @mention an agent.');
+  console.log('Tasks land as drafts on the board — nothing runs until you open');
+  console.log('a session tab in the Workbench and type in it.');
   console.log('');
 }

package/bin/lib/preflight.mjs

@@ -91,20 +91,23 @@ export async function preflight({ needGit = true } = {}) {
     }
   }
 
-  // gh — needed to open PRs. Offer to fetch the isolated binary (yes-default:
-  // low-risk, no login carried by the install itself).
+  // gh — OPTIONAL. The daemon pushes and merges with plain `git`; nothing in
+  // the product opens a pull request any more, so gh is a convenience for the
+  // agent, not a requirement. Hence the offer no longer defaults to yes: an
+  // install nobody asked for, defaulted on, is how a preflight installs
+  // software on a machine whose operator only wanted a status line.
   if (gh && ghAuthed()) {
     ok('gh authenticated');
   } else if (gh) {
     warn('gh not signed in — run: gh auth login');
   } else {
-    warn('gh NOT found — needed to open PRs.');
-    if (await promptYesNo('Install GitHub CLI (gh) now?', true)) {
+    info('gh not found (optional).');
+    if (await promptYesNo('Install GitHub CLI (gh) now?', false)) {
       if (await installGh((m) => info(m))) gh = present('gh');
     }
     gh
       ? ok('gh installed to ~/.flowviant/bin — authenticate with: flowviant gh-auth')
-      : warn('install gh manually: https://cli.github.com, then run: gh auth login');
+      : info(c.dim('or install it later: https://cli.github.com, then: gh auth login'));
   }
 
   if (needGit) (git ? ok('git installed') : warn('git NOT found — install git'));

package/bin/lib/runtimes.mjs

@@ -687,9 +687,18 @@ export const RUNTIMES = {
         // turn reports failure having touched nothing. Caught only because an
         // end-to-end test had to add the flag by hand to work.
         //
-        // NOT `--sandbox` here, unlike wiki: a build has to `git push` and run
-        // `gh pr create`, so it needs the network by definition. The containment
-        // is the worktree, as it is for every runtime.
+        // NOT `--sandbox` here, unlike wiki: a build has to `git push`, so it
+        // needs the network by definition.
+        //
+        // AND NOTHING ELSE CONTAINS IT EITHER. This comment used to end "the
+        // containment is the worktree, as it is for every runtime", which was
+        // false and is the kind of false that stops people looking: `cwd` is a
+        // starting directory, not a jail. A build turn runs with the operator's
+        // full user permissions — it can write outside the worktree, to their
+        // home directory, to their other checkouts. Claude gets
+        // --dangerously-skip-permissions, codex gets --sandbox
+        // danger-full-access, and agy gets no sandbox flag at all. The only
+        // real boundary today is that the person driving the tab is trusted.
         //
         // FLOWVIANT_SAFE HAS NO EXPRESSION ON THIS RUNTIME. Claude narrows to an
         // allowlist and Codex to `workspace-write`; agy's only per-invocation

package/bin/lib/stream.mjs

@@ -1,11 +1,13 @@
 /**
- * Fleet daemon push channel — the best-practice endgame for dispatch latency.
+ * Machine daemon push channel — the best-practice endgame for pickup latency.
  *
- * Holds a hibernatable WebSocket open to the server. When a job lands (a wiki
- * regen, a dispatch, a merge request, an @mention), the server pushes a
- * `{type:'wake'}` frame and the daemon reconciles IMMEDIATELY — its normal
- * roster fetch — instead of waiting out the poll. That collapses pickup latency
- * from ≤RECONCILE_SECONDS to ~a round trip.
+ * Holds a hibernatable WebSocket open to the server. When a job lands — a
+ * session turn typed into a tab, a diff request, a preview, an env sync, a
+ * deploy, a wiki regen — the server pushes a `{type:'wake'}` frame and the
+ * daemon reconciles IMMEDIATELY — its normal roster fetch — instead of waiting
+ * out the poll. That collapses pickup latency from ≤RECONCILE_SECONDS to ~a
+ * round trip, which is what makes a message typed in the browser start on the
+ * machine at once.
  *
  * The socket carries NO authority: it's a dumb nudge, the roster HTTP fetch is
  * the source of truth (notify-then-reconcile, à la k8s watch). So a dropped or
@@ -74,9 +76,9 @@ export function connectStream({ onWake, isAlive }) {
       lastRxAt = Date.now();
       if (announcedDown) {
         announcedDown = false;
-        info(c.dim('push channel reconnected — instant dispatch back on'));
+        info(c.dim('push channel reconnected — turns start instantly again'));
       } else {
-        note(c.dim('push channel connected — instant dispatch on'));
+        note(c.dim('push channel connected — turns start instantly'));
       }
       clearPing();
       pingTimer = setInterval(() => {

package/bin/lib/update.mjs

@@ -114,10 +114,11 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
 
   if (wantInstall && !npx) {
     if (!safeToUpdate) {
-      // Outdated but an agent is mid-task — wait for idle. Nag once meanwhile.
+      // Outdated but a turn is running — wait until the machine is quiet. Nag
+      // once meanwhile.
       if (naggedFor !== target) {
         naggedFor = target;
-        note(`flowviant ${cur} → ${target} available — self-updating once agents go idle.`);
+        note(`flowviant ${cur} → ${target} available — self-updating once no turn is running.`);
       }
       return false;
     }

package/bin/lib/work.mjs

@@ -799,9 +799,17 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
           'Content-Type': 'application/json',
         },
         signal: AbortSignal.timeout(30_000),
-        body: JSON.stringify({ sessionId }),
+        // The instance is what CLAIMS the session lease server-side. Two
+        // daemons share one fleet credential, so the token cannot say which of
+        // us is serving this tab — and the mint is the moment that matters:
+        // there is one work-token row per session and minting ROTATES it, so a
+        // second mint revokes the first daemon's live secret mid-turn.
+        body: JSON.stringify({ sessionId, instance: DAEMON_INSTANCE }),
       });
       if (res.status === 404) return { gone: true };
+      // 409 — another daemon on this credential holds the session. Not ours to
+      // serve and not a retry: stand down and let the holder answer.
+      if (res.status === 409) return { heldElsewhere: true };
       if (!res.ok) return null;
       const token = (await res.json().catch(() => null))?.data?.token ?? null;
       if (!token) return null;
@@ -1168,8 +1176,25 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
    * machines. When the roster omits the field entirely (older server),
    * absence of signal is not a close — retire nothing.
    */
-  const retireWorkSessions = (activeIds) => {
+  /** Every session this daemon currently has a worktree for — what renews our
+   *  lease on the poll. Read off the directory rather than a map, so it is the
+   *  same fact retirement acts on. */
+  const heldSessionIds = () => {
+    const dir = join(baseDir, 'sessions');
+    try {
+      return readdirSync(dir).filter(isSafePathSegment).slice(0, 50);
+    } catch {
+      return [];
+    }
+  };
+
+  const retireWorkSessions = (activeIds, heldElsewhere) => {
     if (!Array.isArray(activeIds)) return;
+    // Sessions ANOTHER daemon on this credential is serving. They are absent
+    // from activeWorkSessions for us and present for them, and removing their
+    // worktree would pull the directory out from under a running turn. Absence
+    // means "the tab closed"; this is the one other thing it can mean.
+    const peers = new Set(Array.isArray(heldElsewhere) ? heldElsewhere : []);
     const dir = join(baseDir, 'sessions');
     if (!existsSync(dir)) return;
     let ids;
@@ -1182,6 +1207,7 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     let removed = 0;
     for (const id of ids) {
       if (live.has(id)) continue;
+      if (peers.has(id)) continue; // another daemon's tab — not ours to retire
       if (workChains.has(id) || shipping.has(id)) continue; // still draining here
       const wt = join(dir, id);
       try {
@@ -1412,6 +1438,15 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
           if (!plainTab) {
             mint = await mintWorkToken(job.sessionId);
             if (!mint) mint = await mintWorkToken(job.sessionId, true); // one transient blip ≠ a dead turn
+            // Another daemon on this credential holds the session. Return
+            // WITHOUT settling: the holder is answering this same turn, and
+            // settling it here — even as a failure — would race the real
+            // answer and could win. Dropping it means the turn stays pending
+            // and the holder's answer lands, which is the whole point.
+            if (mint?.heldElsewhere) {
+              workAnswering.delete(job.id);
+              return;
+            }
             if (mint?.gone) {
               await settleWorkTurn(job.id, {
                 ok: false,
@@ -2064,6 +2099,7 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     processWorkTurns,
     processShipJobs,
     processDiffJobs,
+    heldSessionIds,
     processPreviewJobs,
     livePreviewIds,
     retirePreviews,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "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": {