flowviant 0.115.0 → 0.117.0

package/bin/lib/git.mjs

@@ -3,9 +3,49 @@
 import { execFileSync, spawn } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { killGroup } from './processGroup.mjs';
 
-export function git(args, cwd) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+/**
+ * ONE LOCAL GIT CALL, trimmed. Throws on a non-zero exit (with git's stderr on
+ * the error), like `execFileSync` itself.
+ *
+ * `opts` SPREADS OVER THE DEFAULTS (audit 2026-10-10, F107): with none, the
+ * call is exactly what it always was — utf8, stderr piped, no timeout, Node's
+ * own 1 MiB `maxBuffer`. A caller that needs a wider buffer, a timeout, a
+ * quiet stderr (`stdio: ['ignore', 'pipe', 'ignore']`) or an `env` asks for it
+ * here instead of re-spelling `execFileSync('git', …)` with its own drifted
+ * options — nine modules did, one of them under this function's own name.
+ * Buffer output (`encoding: 'buffer'`) goes through `gitRaw`: there is nothing
+ * to trim.
+ */
+export function git(args, cwd, opts = {}) {
+  return gitRaw(args, cwd, opts).trim();
+}
+
+/**
+ * THE WIDE BUFFER — 8 MiB, for a read whose output grows with the repository
+ * (a catch-up range's commit list, a patch, the branch report). Node's 1 MiB
+ * default threw ENOBUFS mid-read in three lanes, each of which then learned the
+ * number on its own (landed.mjs, repoState.mjs, workDiffs.mjs); one name now.
+ */
+export const GIT_WIDE_BUFFER = 8 * 1024 * 1024;
+
+/**
+ * A git fact, or NULL when git could not answer — a non-zero exit (a detached
+ * HEAD for `symbolic-ref`, an unborn branch for `rev-parse HEAD`, a range
+ * naming a ref that is not there) or empty output. For the reads that are
+ * OPTIONAL to their caller: the lanes each re-learned that `git()` throws
+ * rather than returning a non-string, and wrote the same try/catch → null ten
+ * times, one of them left out (audit 2026-10-10, F144). A caller that must
+ * tell one failure from another (the begun-guard's exit status) does not use
+ * this.
+ */
+export function gitOrNull(args, cwd) {
+  try {
+    return git(args, cwd) || null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -37,12 +77,10 @@ export function gitNetEnv(cwd, env = process.env) {
   if (env.GIT_SSH_COMMAND || env.GIT_SSH) return out;
   let configured = '';
   try {
-    configured = execFileSync('git', ['config', '--get', 'core.sshCommand'], {
-      cwd,
-      encoding: 'utf8',
+    configured = git(['config', '--get', 'core.sshCommand'], cwd, {
       stdio: ['ignore', 'pipe', 'ignore'],
       timeout: 5_000,
-    }).trim();
+    });
   } catch {
     /* unset (exit 1) or unreadable — ours, then */
   }
@@ -62,14 +100,7 @@ export function gitNetEnv(cwd, env = process.env) {
  * throws with `code: 'ETIMEDOUT'`).
  */
 export function gitNet(args, cwd, ms = GIT_NET_TIMEOUT_MS) {
-  return execFileSync('git', args, {
-    cwd,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: ms,
-    killSignal: 'SIGKILL',
-    env: gitNetEnv(cwd),
-  });
+  return gitRaw(args, cwd, { timeout: ms, killSignal: 'SIGKILL', env: gitNetEnv(cwd) });
 }
 
 /**
@@ -103,15 +134,7 @@ export function gitNetAsync(args, cwd, ms = GIT_NET_TIMEOUT_MS) {
       fn(v);
     };
     const timer = setTimeout(() => {
-      try {
-        process.kill(-child.pid, 'SIGKILL');
-      } catch {
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          /* already gone */
-        }
-      }
+      killGroup(child, 'SIGKILL');
       const e = new Error(`git ${args[0]} timed out after ${ms}ms`);
       e.code = 'ETIMEDOUT';
       finish(reject, e);
@@ -147,8 +170,8 @@ export function gitNetAsync(args, cwd, ms = GIT_NET_TIMEOUT_MS) {
  * has an accent in it. For the patch collision check, "silently stops matching"
  * means "overwrites the edits it exists to protect".
  */
-export function gitRaw(args, cwd) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+export function gitRaw(args, cwd, opts = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts, cwd });
 }
 
 /** Split NUL-separated git output into entries. */
@@ -166,10 +189,10 @@ export function repoRootOrDie() {
 }
 
 // ── Server-value validation ────────────────────────────────────────────────
-// prUrl / branch / agentId arrive from the fleet server. execFileSync blocks
-// SHELL injection but NOT git/gh option injection (a leading '-' becomes a
-// flag) or cross-repo/cross-path abuse. These guards make a malicious or buggy
-// server unable to touch a repo/branch/path outside the expected scope.
+// Shas and ids arrive from the fleet server. execFileSync blocks SHELL
+// injection but NOT git/gh option injection (a leading '-' becomes a flag) or
+// cross-path abuse. These guards make a malicious or buggy server unable to
+// touch a revision/path outside the expected scope.
 
 /** The `owner/repo` the daemon is running inside, from origin's URL. Null if
  *  origin isn't a github remote. */
@@ -183,32 +206,27 @@ export function originSlug(repoRoot) {
   }
 }
 
-/** A PR URL is accepted only if it's an https github.com PR in THIS repo. */
-export function isValidPrUrl(prUrl, slug) {
-  if (typeof prUrl !== 'string' || !slug) return false;
-  const m = prUrl.match(/^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/\d+$/);
-  return !!m && m[1].toLowerCase() === slug.toLowerCase();
-}
-
-/** A branch name is accepted only if git considers it a well-formed ref, it's
- *  not the base branch, and it doesn't start with '-' (option injection). */
-export function isValidBranch(branch, repoRoot, baseRef) {
-  if (typeof branch !== 'string' || !branch || branch.startsWith('-')) return false;
-  if (baseRef && (branch === baseRef || `origin/${branch}` === baseRef)) return false;
-  try {
-    git(['check-ref-format', '--branch', branch], repoRoot);
-    return true;
-  } catch {
-    return false;
-  }
-}
+/**
+ * THE TWO SHA SHAPES THE DAEMON CHECKS, named in one place (audit 2026-10-10,
+ * F749) so the split between them is visible instead of spelled five ways:
+ * `SHA1_ABBREV_RE` — lowercase, 7 to 40 hex, a SHA-1 id or its abbreviation
+ * (`isValidSha`, and the publish lease's `isSha`, which is this same guard);
+ * `OBJECT_ID_RE` — either case, 7 to 64 hex, which also admits a SHA-256
+ * repository's ids (the landed observer, the commit-diff lane). Each site
+ * keeps the shape it already checked; unifying on 64 is a behaviour change on
+ * SHA-256 repositories and an owner's call. Neither admits a leading `-` or a
+ * range. Anchored and flag-free of `g`, so `.test` holds no state.
+ */
+export const SHA1_ABBREV_RE = /^[0-9a-f]{7,40}$/;
+export const OBJECT_ID_RE = /^[0-9a-f]{7,64}$/i;
 
-/** A commit sha from the server, before it reaches `git revert` argv. Server
- *  values reaching git are validated here by convention (see isValidBranch,
- *  isValidPrUrl) — a revision RANGE ("HEAD~10..HEAD") or a leading-dash option
- *  must never pass, whatever the roster says. */
+/** A commit sha from the server, before it reaches git argv. Server values
+ *  reaching git are validated here by convention — a revision RANGE
+ *  ("HEAD~10..HEAD") or a leading-dash option must never pass, whatever the
+ *  roster says. (The PR-URL and branch guards beside it served only the
+ *  retired cleanup lane and went with it, audit 2026-10-10, F083.) */
 export function isValidSha(sha) {
-  return typeof sha === 'string' && /^[0-9a-f]{7,40}$/.test(sha);
+  return typeof sha === 'string' && SHA1_ABBREV_RE.test(sha);
 }
 
 /** A roster agent id used as a filesystem path segment — strict allowlist so
@@ -217,6 +235,45 @@ export function isSafePathSegment(id) {
   return typeof id === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(id);
 }
 
+/**
+ * THE BRANCH A PLACE IS CUT ON — `session/<id>`, for a tab's own worktree, a
+ * person's `u-` place and an agent's `a-` place alike. One definition, beside
+ * the segment rule that guards it (audit 2026-10-10, F122): the cutter, the
+ * begun-guard's rev-parse, the publish push and fetch, ship's and the PR
+ * lane's fallback, and the merged-branch sweep all name the branch through
+ * here, so a change to the scheme or to the id allowlist lands once instead of
+ * at nine template strings that could drift into cutting one branch and
+ * checking for another.
+ *
+ * Null for an id that is not a safe path segment: every caller treats that
+ * exactly as it treats a branch that is not there.
+ */
+export const SESSION_BRANCH_PREFIX = 'session/';
+export function sessionBranch(id) {
+  return isSafePathSegment(id) ? `${SESSION_BRANCH_PREFIX}${id}` : null;
+}
+/** The same branch as a full ref, for argv that must not let git guess. */
+export function sessionBranchRef(id) {
+  const name = sessionBranch(id);
+  return name ? `refs/heads/${name}` : null;
+}
+/** A ref Flowviant itself cut for a place. The ONLY thing that makes a branch
+ *  "ours" — the reader beside the writer, so the two cannot disagree. */
+export function isSessionBranch(name) {
+  return typeof name === 'string' && name.startsWith(SESSION_BRANCH_PREFIX);
+}
+
+/**
+ * A REMOTE URL'S USERINFO, REMOVED. `//user:token@host` is how a credential
+ * rides a remote, and git or gh can print that URL in the first line of a
+ * failure that is about to be stored where the whole project reads it. Shared
+ * by every relay of a push or `gh` failure (publishErrorText, ghFirstLine) so
+ * the rule is one regex, not two copies (audit 2026-10-10, F153).
+ */
+export function stripUrlUserinfo(text) {
+  return String(text ?? '').replace(/\/\/[^/@\s]+@/g, '//');
+}
+
 export function detectBaseRef(repoRoot) {
   try {
     return git(['rev-parse', '--abbrev-ref', 'origin/HEAD'], repoRoot); // e.g. origin/main
@@ -346,14 +403,7 @@ export function excludeInWorktree(wt, relPaths) {
   try {
     let gitdir;
     try {
-      gitdir = resolve(
-        wt,
-        execFileSync('git', ['rev-parse', '--git-common-dir'], {
-          cwd: wt,
-          encoding: 'utf8',
-          stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim()
-      );
+      gitdir = resolve(wt, git(['rev-parse', '--git-common-dir'], wt, { stdio: ['ignore', 'pipe', 'ignore'] }));
     } catch {
       return; // not a repo — there is no exclude file to write
     }

package/bin/lib/gitMergeIdentity.mjs

@@ -12,8 +12,7 @@
  * are their own.
  */
 
-import { execFileSync } from 'node:child_process';
-import { git } from './git.mjs';
+import { git, gitRaw } from './git.mjs';
 
 export const DAEMON_GIT_IDENTITY = Object.freeze({
   GIT_AUTHOR_NAME: 'Flowviant',
@@ -41,11 +40,6 @@ export function mergeIdentityEnv(repoRoot) {
 export function gitMergeIn(repoRoot) {
   return (args, cwd) => {
     const idEnv = mergeIdentityEnv(repoRoot);
-    return execFileSync('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      ...(idEnv ? { env: { ...process.env, ...idEnv } } : {}),
-    });
+    return gitRaw(args, cwd, idEnv ? { env: { ...process.env, ...idEnv } } : {});
   };
 }

package/bin/lib/grant.mjs

@@ -15,10 +15,13 @@
  * hostname is un-gated. It also means a network blip cannot turn somebody's
  * working preview into a 502.
  *
- * THIS FILE IS ONE HALF OF A WIRE CONTRACT. The other half is
- * `apps/api/src/lib/agent-runner/previewGrant.ts` in the Flowviant repo, and
- * the two are tested against the same vectors. A change here that the server
- * does not follow shows up as a preview nobody can open.
+ * THIS FILE IS ONE HALF OF A WIRE CONTRACT. The other half is the app's ONE
+ * minter, `mintGrant` in `packages/shared/src/previewGrant.ts`, which both the
+ * API's `/authorize` and the preview relay sign with. The release gate
+ * (`scripts/check-app-parity.mjs`, the grant case) mints with that function and
+ * verifies here, so a change on either side that the other does not follow
+ * fails a release instead of shipping as a preview nobody can open.
+ * (`grant.test.mjs` tests this half alone, against its own minter.)
  *
  * NO CANONICAL-ENCODING CONTRACT, deliberately: the signature covers the
  * RECEIVED payload string bytes and the JSON is parsed only afterwards. Field
@@ -30,7 +33,9 @@
 import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
 
 export const GRANT_VERSION = 1;
-const DOMAIN = `fvgrant.v${GRANT_VERSION}.`;
+/** Domain separation: the signed message is `fvgrant.v1.<body>`. Exported for
+ *  the release gate's comparison with the app's `GRANT_DOMAIN`. */
+export const GRANT_DOMAIN = `fvgrant.v${GRANT_VERSION}.`;
 
 /** `__Host-` is required rather than decorative: every quick tunnel is a
  *  hostname under the shared `trycloudflare.com` parent, so without the prefix
@@ -81,7 +86,7 @@ export function verifyGrant(raw, { secret, shareId, nowMs, skewMs } = {}) {
     return { ok: false, reason: 'shape' };
   }
 
-  const expected = b64url(createHmac('sha256', String(secret)).update(DOMAIN + body).digest());
+  const expected = b64url(createHmac('sha256', String(secret)).update(GRANT_DOMAIN + body).digest());
   if (!sameSecret(sig, expected)) return { ok: false, reason: 'sig' };
 
   let payload;
@@ -185,6 +190,15 @@ export function safePathname(url) {
  * the cheap first line; the origin comparison is the guarantee. Ported from
  * the server twins (previewAuthorize.routes.ts, preview-relay util.ts), which
  * closed the same hole the same way.
+ *
+ * …AND THE OUTPUT IS CHECKED, NOT ONLY THE INPUT (2026-10-10, audit F618). The
+ * parser resolves dot segments, so `/.//evil.com`, `/..//evil.com`,
+ * `/%2e%2e//evil.com` and `/./\evil.com` pass the lexical test above (none
+ * starts with two slashes) and then re-serialise to the pathname
+ * `//evil.com` — protocol-relative in Location, though the parse stayed on the
+ * dummy origin. The value returned must itself be a single-slash path. No
+ * version floor: the app's /authorize already re-cleans every `to` it hands
+ * this callback, so only a hand-crafted callback URL ever met the hole.
  */
 export function safeRelative(raw) {
   if (!raw) return '/';
@@ -198,7 +212,9 @@ export function safeRelative(raw) {
   try {
     const u = new URL(s, 'https://x.invalid');
     if (u.origin !== 'https://x.invalid') return '/';
-    return u.pathname + u.search + u.hash;
+    const out = u.pathname + u.search + u.hash;
+    if (/^\/[/\\]/.test(out)) return '/';
+    return out;
   } catch {
     return '/';
   }

package/bin/lib/holder.mjs

@@ -16,8 +16,23 @@
 
 import { safeName } from './credentials.mjs';
 import { emitMachineEvent } from './daemonLogging.mjs';
+import { printableLine } from './printable.mjs';
 import { note, warn } from './ui.mjs';
-import { sleep } from './claude.mjs';
+
+/** A bound on a wedged uplink, and never a reason to hang: the timer is
+ *  unref'd, so the only thing that keeps this process alive is the work.
+ *  The one copy every stand-down below waits behind (2026-10-10): the
+ *  commanded stop used to race a plain `sleep(5)` imported from claude.mjs —
+ *  a timer that held the loop, and an import that dragged the whole runtime
+ *  registry into a module that is pure or injected throughout. */
+const bounded = (p, seconds) =>
+  Promise.race([
+    p,
+    new Promise((resolve) => {
+      const t = setTimeout(resolve, seconds * 1000);
+      t.unref?.();
+    }),
+  ]);
 
 /**
  * A STOP COMMANDED BY FLOWVIANT, read off the roster poll.
@@ -53,11 +68,11 @@ export function shouldStop(rosterDaemon) {
   // 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);
+  //
+  // The SHARED class (printable.mjs, 2026-10-10, F084): this copy used to stop
+  // at C0 and DEL, so the 8-bit CSI `\u009b` and every bidi override reached
+  // the terminal whenever the server's own scrub was bypassed.
+  const reason = printableLine(String(stop.reason ?? ''), 300);
   return { stop: true, reason };
 }
 
@@ -263,7 +278,21 @@ export function removedTurnSentence() {
 }
 
 /**
- * THE MACHINE MOVED. STAND DOWN.
+ * …AND FOR THE THIRD: Flowviant STOPPED this machine (2026-10-10, F091).
+ *
+ * The commanded stop used to leave its agent turns unsettled: they sat pending
+ * until the server's six-hour expiry while the board showed an agent working
+ * on a machine that had gone dark. Settled now with `nothing` and this
+ * sentence — never delivered, so the card goes to Stuck rather than an
+ * optimistic Review. It names no box and no reason: nothing took over, and
+ * the operator's reason is said on this console, where the stop is read.
+ */
+export function stoppedTurnSentence() {
+  return 'This machine was stopped by Flowviant while this turn was running.';
+}
+
+/**
+ * THE ROSTER ENDED THIS DAEMON. STAND DOWN.
  *
  * The server sends `displaced` only when it is aimed at THIS box (it matches the
  * poll's own `envpub`) and only inside a short window, so there is nothing to
@@ -276,11 +305,15 @@ export function removedTurnSentence() {
  * board shows an agent working on a machine that has gone. `nothing` is the
  * honest outcome and the sentence says what happened.
  *
- * EXIT 0, for the reason the two existing terminal paths (the commanded stop,
- * and the revoked credential above it) both document: under `Restart=on-failure`
- * a nonzero code has systemd relaunch this daemon immediately, where it would
- * poll, be told again that it is not the machine, and stand down again — a
- * restart loop fighting a decision somebody made on purpose.
+ * EXIT 0, and this is load-bearing: every kind of stand-down was ASKED FOR, so
+ * it is not a failure. Under `Restart=on-failure` a nonzero code has systemd
+ * relaunch this daemon immediately — a stopped machine fighting the very
+ * command that stopped it, a displaced or removed one polling, being told
+ * again, and standing down again: a restart loop fighting a decision somebody
+ * made on purpose. Exit 0 reads as "the job is done" and leaves it down. For a
+ * stop, 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.
  *
  * Every dependency is injected so the whole stand-down can be proved without a
  * server, a repo or a process to kill.
@@ -288,6 +321,7 @@ export function removedTurnSentence() {
 export async function standDownDisplaced({
   by,
   kind = 'moved',
+  reason,
   project,
   settleAgentTurns,
   flushReports,
@@ -295,69 +329,83 @@ export async function standDownDisplaced({
   exit,
   log = { warn: () => {}, note: () => {} },
 }) {
-  /** A bound on a wedged uplink, and never a reason to hang: the timer is
-   *  unref'd, so the only thing that keeps this process alive is the work. */
-  const bounded = (p, seconds) =>
-    Promise.race([
-      p,
-      new Promise((resolve) => {
-        const t = setTimeout(resolve, seconds * 1000);
-        t.unref?.();
-      }),
-    ]);
   // Scrubbed before it reaches this box's own console (2026-09-24, the
   // audit) — see printable.mjs.
   const name = safeName(by)?.slice(0, 64) ?? null;
   /**
-   * TWO KINDS, ONE CHOREOGRAPHY (2026-09-21).
+   * THREE KINDS, ONE CHOREOGRAPHY (2026-09-21; the third 2026-10-10, F091).
    *
    * `moved` is the original: another box took the machine, and it is the
    * DEFAULT so the displaced call site reads exactly as it always did.
    * `removed` is the project saying this box is not its machine at all any
-   * more — somebody pressed a button in the app — and the only thing that
-   * differs is the WORDS. Everything below this point is the same, and it must
-   * be: settle the turns first, flush the reports, tear down the detached
-   * children, keep the worktrees, exit 0.
+   * more — somebody pressed a button in the app. `stopped` is Flowviant
+   * commanding this machine to stop (`shouldStop`; `reason` is its already
+   * scrubbed sentence). Only the WORDS differ. Everything below the words is
+   * the same, and it must be: settle the turns first, flush the reports, tear
+   * down the detached children, keep the worktrees, exit 0.
+   *
+   * The commanded stop was a third, hand-written copy of these steps until
+   * 2026-10-10, and it had drifted: it never settled its agent turns, which
+   * then sat pending until the server's expiry while the board showed agents
+   * working on a machine somebody had just stopped.
    *
-   * The sentences are picked HERE rather than passed in, so the two cannot
-   * drift and neither call site can invent a third.
+   * The sentences are picked HERE rather than passed in, so the kinds cannot
+   * drift and no call site can invent a fourth.
    */
   const removed = kind === 'removed';
-  const projectName = safeName(project)?.slice(0, 64) ?? 'this project';
-  log.warn(
-    removed
-      ? `removed from ${projectName} in the app — stopping.`
-      : name
-        ? `this project's machine moved to ${name} — standing down.`
-        : "this project's machine moved to another box — standing down."
-  );
-  if (removed) emitMachineEvent({ event: 'stopped', reason: 'removed' });
-  else emitMachineEvent({ event: 'displaced', message: displacedTurnSentence(by) });
+  const stopped = kind === 'stopped';
+  if (stopped) {
+    // The stop's own words and event, as they always were.
+    emitMachineEvent({ event: 'stopped', reason: reason ?? null });
+    log.warn(reason ? `stopped by Flowviant — ${reason}` : 'stopped by Flowviant — no reason given.');
+    // "Worktrees are kept" and no more: this note used to add "in-flight work
+    // resumes next run", which a settled agent turn — Stuck, waiting for a
+    // person — no longer does.
+    log.note('shutting down — stopping workers. Worktrees are kept.');
+  } else {
+    const projectName = safeName(project)?.slice(0, 64) ?? 'this project';
+    log.warn(
+      removed
+        ? `removed from ${projectName} in the app — stopping.`
+        : name
+          ? `this project's machine moved to ${name} — standing down.`
+          : "this project's machine moved to another box — standing down."
+    );
+    if (removed) emitMachineEvent({ event: 'stopped', reason: 'removed' });
+    else emitMachineEvent({ event: 'displaced', message: displacedTurnSentence(by) });
+  }
   // FIRST, and awaited: an unsettled turn is the one thing here that no later
   // poll from anybody can fix — this process holds the only copy of the fact
   // that it was running.
   try {
     await bounded(
-      settleAgentTurns(removed ? removedTurnSentence() : displacedTurnSentence(by)),
+      settleAgentTurns(
+        stopped ? stoppedTurnSentence() : removed ? removedTurnSentence() : displacedTurnSentence(by)
+      ),
       10
     );
   } catch {
     /* an unsettled turn expires server-side with words of its own */
   }
-  // THEN the queued settles, bounded exactly as the commanded stop bounds them:
-  // a queued report is a COMPLETED turn whose side effects already happened, and
-  // dropping it re-runs the whole turn somewhere else.
+  // THEN the queued settles, bounded: a queued-but-undelivered report is a
+  // COMPLETED turn whose side effects already happened, and dropping it re-runs
+  // the whole turn — quota spent twice and every card write doubled. This path
+  // is async (unlike the signal handlers, which cannot await), so it can afford
+  // five seconds of delivery before it obeys.
   try {
     await bounded(flushReports(), 5);
   } catch {
     /* undelivered reports re-run; delivering them was best-effort */
   }
-  // NOT optional, for the reason the commanded stop states: detached preview
-  // tunnels survive this process by design, and a public hostname pointed into a
-  // worktree on a box that no longer serves the project is the worst thing this
-  // path can leave behind.
+  // teardown() is NOT optional. Detached preview tunnels survive this process
+  // BY DESIGN, so exiting without it strands a public hostname pointed into a
+  // worktree — on a box that no longer serves the project, or until somebody
+  // reboots a stopped one, 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();
-  log.note('worktrees are kept — the branches here are the only copy of this box\'s work.');
+  if (!stopped) log.note('worktrees are kept — the branches here are the only copy of this box\'s work.');
   exit(0);
 }
 
@@ -382,39 +430,18 @@ export async function obeyRosterCommands(
   // going away.
   const stopSignal = shouldStop(roster.daemon);
   if (stopSignal) {
-    emitMachineEvent({ event: 'stopped', reason: stopSignal.reason ?? null });
-    log.warn(
-      stopSignal.reason
-        ? `stopped by Flowviant — ${stopSignal.reason}`
-        : 'stopped by Flowviant — no reason given.'
-    );
-    log.note('shutting down — stopping workers. Worktrees are kept: in-flight work resumes next run.');
-    // FLUSH the settle queue first, bounded: a queued-but-undelivered report
-    // is a COMPLETED turn whose side effects already happened, and dropping
-    // it re-runs the whole turn on the next start — quota spent twice and
-    // every card write doubled. This path is async (unlike the signal
-    // handlers, which cannot await), so the stop can afford five seconds of
-    // delivery before it obeys.
-    try {
-      await Promise.race([flushWorkReports(), sleep(5)]);
-    } catch {
-      /* undelivered reports re-run; delivering them was best-effort */
-    }
-    // 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.
-    exit(0);
+    // The same choreography as a displacement (`standDownDisplaced`, kind
+    // `stopped`): its own words and event, then settle the agent turns, flush
+    // the queued reports, tear down, exit 0.
+    await standDownDisplaced({
+      kind: 'stopped',
+      reason: stopSignal.reason,
+      settleAgentTurns,
+      flushReports: flushWorkReports,
+      teardown,
+      exit,
+      log,
+    });
     return true;
   }
   /**