flowviant 0.53.0 → 0.54.1

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
@@ -18,29 +19,35 @@
  * `npx flowviant` can reuse a stale cache). A running daemon also self-updates
  * 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).
+ * `flowviant stop` stops every daemon on this box — the answer to "is one even
+ * running?", which otherwise ends in a pid hunt through `ps`.
  *
- * 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,21 +139,46 @@ 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));
   process.exit(0);
 }
 
+// `flowviant stop` — stop every flowviant daemon on this machine.
+//
+// THE FRICTION IT REMOVES is not knowing whether one is running. So you run
+// `flowviant`, get a refusal naming a pid in a directory you do not recognise,
+// and go hunting through `ps`. This asks no question and takes no argument: it
+// sweeps every credential's lock file, not just the one this checkout keys to,
+// because a stop command with a scope is one you have to be sure about before
+// you can use it — and being unsure is the whole reason you typed it.
+//
+// It identifies each holder before signalling it and says so when it cannot
+// (see stopAllDaemons); it needs NO credential and NO network — it reads lock
+// files under ~/.flowviant and signals pids — so it runs BEFORE the auth gate,
+// like `shot`. "I don't know what is running" is not a state in which we should
+// also be asking someone to log in.
+//
+// EXIT 0 when it stopped something AND when it found nothing: "no flowviant
+// daemon is running on this machine." is the answer the asker came for, not an
+// error. Non-zero only when something was alive and could not be stopped.
+if (process.argv[2] === 'stop') {
+  const { stopAllDaemons } = await import('./lib/instance.mjs');
+  const { failed } = stopAllDaemons({ log: (m) => console.log(m) });
+  process.exit(failed > 0 ? 1 : 0);
+}
+
 // `flowviant env <import|set|show>` — the CLI half of team env sync. Values
 // 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 +196,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"
@@ -266,25 +270,60 @@ async function maybeReportLocalSessions({ repoRoot, excludeDirs }) {
   }
 }
 
+/**
+ * A STOP COMMANDED BY FLOWVIANT, read off the roster poll.
+ *
+ * The daemon is a PULL client — the /fleet/stream socket is a one-way wake
+ * nudge with no server→daemon request path — so "stop this machine" can never
+ * be a request the server makes of us. It rides the roster RESPONSE instead, on
+ * the same `daemon` object the version signal already travels on, which is why
+ * it needs no new endpoint and no version floor: an older daemon reads an
+ * unknown key as nothing and keeps running, and fail-open is the safe direction
+ * for a switch whose failure mode is "your machine went dark".
+ *
+ * The server decides whether a stop is LIVE — it stamps the credential and only
+ * sends the key inside a short honor window — and the daemon does NOT re-derive
+ * that. The key's PRESENCE is the command. Evaluating the same TTL on both
+ * sides would make clock skew the arbiter of whether a machine may run, and get
+ * it wrong in the direction that bricks the box: a relaunch that re-reads an
+ * old timestamp and stops itself again, forever.
+ *
+ * Pure and exported so the decision can be proved without a credential or a
+ * live server. `null` means keep running.
+ */
+export function shouldStop(rosterDaemon) {
+  const stop = rosterDaemon?.stop;
+  // An OBJECT, and not an array: `typeof [] === 'object'`, so the plain typeof
+  // guard let `stop: []` — an empty list, which is how this codebase spells "no
+  // jobs" on every other roster key — read as a live stop with no reason. A
+  // switch that kills a machine gets the narrow test.
+  if (!stop || typeof stop !== 'object' || Array.isArray(stop)) return null;
+  // Re-sanitized HERE even though the server wrote it: this string is operator
+  // prose typed into a SQL UPDATE and then printed straight to a terminal, so
+  // control bytes would let a stop reason repaint the console it is being read
+  // on, and an unbounded one would bury the line that matters. The WORDING is
+  // untouched — the operator's own sentence is the whole point of the field,
+  // and paraphrasing it would leave the person at the keyboard guessing.
+  const reason = String(stop.reason ?? '')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300);
+  return { stop: true, reason };
+}
+
 // One roster agent's loop: persistent worktree, one intent per turn, reset to
 // base between tasks (fresh conversation), resume in place while on a blocker.
 
 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 +334,50 @@ 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.');
+    }
+    // WITHHELD when we could not identify the holder. ALLOW_MULTI runs this
+    // daemon unguarded beside one we just admitted we cannot see, and in the
+    // same repo that is two `git fetch`, two worktree sweeps, and one
+    // `retireWorkSessions` deleting directories the other is serving. Offering
+    // it as the way out of "I don't know what that process is" would be handing
+    // someone the worst option at the moment they have the least information.
+    if (!instance.unidentified) {
+      note('or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
+    }
     console.log('');
     process.exit(1);
   }
@@ -606,6 +677,7 @@ export async function runFleetDaemon() {
     processWorkTurns,
     processShipJobs,
     processDiffJobs,
+    heldSessionIds,
     processPreviewJobs,
     livePreviewIds,
     retirePreviews,
@@ -873,20 +945,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 +1136,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 +1144,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 +1264,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.`);
@@ -1196,6 +1290,36 @@ export async function runFleetDaemon() {
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
     if (roster.project?.id) wikiProjectId = roster.project.id; // keys the vault dir
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
+    // A COMMANDED STOP OUTRANKS AN UPDATE, and that ordering is the whole reason
+    // this sits ABOVE the version signal rather than inside it. Both read the
+    // same `roster.daemon` object, but `handleVersionSignal` can re-exec this
+    // process into a newer build — so checked second, a machine somebody just
+    // told to stop would come back up wearing a different version instead of
+    // going away.
+    const stopSignal = shouldStop(roster.daemon);
+    if (stopSignal) {
+      warn(
+        stopSignal.reason
+          ? `stopped by Flowviant — ${stopSignal.reason}`
+          : 'stopped by Flowviant — no reason given.'
+      );
+      note('shutting down — stopping workers. Worktrees are kept: in-flight work resumes next run.');
+      // teardown() is NOT optional on this path. Detached preview tunnels
+      // survive this process BY DESIGN, so exiting without it strands a public
+      // hostname pointed into a worktree until somebody reboots the box — which
+      // is precisely the state a remote stop is usually being used to end. It
+      // also kills the session CLIs and the wiki Claude, which would otherwise
+      // keep editing worktrees and burning quota for a machine nobody is
+      // watching any more.
+      teardown();
+      // EXIT 0, and this is load-bearing: the stop was ASKED FOR, so it is not
+      // a failure. Under `Restart=on-failure` a nonzero code has systemd
+      // relaunch the daemon immediately, fighting the very command that stopped
+      // it; exit 0 reads as "the job is done" and leaves it down. The server's
+      // honor window is what makes the other half work — a deliberate relaunch
+      // minutes later comes up clean instead of stopping itself forever.
+      process.exit(0);
+    }
     // Keep the daemon current. Safe = no worker mid-task (true at startup, since
     // no workers are spawned yet). If it self-updates it re-execs into the new
     // version and this process becomes a proxy — stop the loop.
@@ -1237,7 +1361,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 +1395,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 +1427,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 */
         }