flowviant 0.56.1 → 0.57.0

package/bin/lib/devServer.mjs

@@ -0,0 +1,306 @@
+/**
+ * RUNNING THE PROJECT'S DEV COMMAND IN A TAB'S WORKTREE.
+ *
+ * THIS FILE MUST NEVER READ A REPO FILE TO DECIDE WHAT TO EXECUTE. That is the
+ * one rule, and it is the whole difference between this and the live-preview
+ * target deleted in 2026-08-21, whose obituary is in `preview.mjs`: that one
+ * read a command out of `.flowviant/preview.json` — a file the BRANCH controls
+ * — or inferred one from package.json, then `spawn(cmd, {shell: true})` with
+ * `{...process.env}`, running `npm install` and its lifecycle scripts and
+ * handing the resulting internet-exposed process the daemon's own credential.
+ * One click behind a button and a hostile branch owned the machine.
+ *
+ * Here the argv arrives ON THE JOB, already parsed from a string a human
+ * approved once for this project and stored server-side. The branch cannot
+ * change it. This file re-validates the SHAPE at its own boundary — one place
+ * doing a check is one deploy away from being zero places — and spawns with
+ * `shell: false`.
+ *
+ * THE HONEST LIMIT, stated here rather than implied: pinning the command does
+ * not pin what the command does. `npm run dev` dereferences to `scripts.dev`,
+ * which the branch writes. What this buys is that a human chose the ENTRYPOINT
+ * in the open, plus a child environment that is a strict subset of what the
+ * agent's own `npm run dev` gets today. The child runs as the SAME UID as this
+ * daemon and `~/.flowviant/credentials.json` is 0600 and readable by it. The
+ * env allowlist is a control against ACCIDENT AND INHERITANCE — a crash
+ * reporter, an error page that dumps `process.env`, a build log — and it is NOT
+ * confinement. Nothing in the UI may say "sandboxed" or "isolated".
+ *
+ * NO PORT IS EVER SCRAPED. The deleted feature learned its port from the
+ * child's stdout and tunnelled a guess when it found none. A scraped port has
+ * no attribution behind it, and "this port was measured, by cwd, inside THIS
+ * worktree" is the only real security control this feature family has. The port
+ * here comes from `listenersIn` or it does not come at all — and a running
+ * server with no measured port is a REAL state that gets a sentence.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { childEnv } from './childEnv.mjs';
+import { mutateRegistry, processAlive, readRegistry } from './procRegistry.mjs';
+import { listenersIn } from './listeners.mjs';
+import { scrub } from './env.mjs';
+
+const FLOWVIANT_DIR = join(homedir(), '.flowviant');
+const REGISTRY = join(FLOWVIANT_DIR, 'devruns.json');
+const REGISTRY_LOCK = join(FLOWVIANT_DIR, 'devruns.lock');
+
+/** Output we keep. Only the tail is ever uplinked, and it is scrubbed on the
+ *  way out: a dev server routinely prints connection strings. */
+const RING_BYTES = 512 * 1024;
+const TAIL_BYTES = 4096;
+/** How long we wait for the command to bind something inside the worktree
+ *  before reporting it as running-but-unmeasured. */
+const BIND_WATCH_MS = 45_000;
+/** At most this many restarts inside the window, and only for a run that bound
+ *  at least once — a server that never bound is a broken command, not a crash,
+ *  and restarting it burns the box. */
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW_MS = 10 * 60_000;
+const BACKOFF_MS = [2_000, 8_000, 30_000];
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+
+const remember = (entry) =>
+  mutateRegistry(FLOWVIANT_DIR, REGISTRY, REGISTRY_LOCK, (list) => [
+    ...list.filter((e) => e.pid !== entry.pid),
+    entry,
+  ]);
+const forget = (pid) =>
+  mutateRegistry(FLOWVIANT_DIR, REGISTRY, REGISTRY_LOCK, (list) =>
+    list.filter((e) => e.pid !== pid)
+  );
+
+/** SIGTERM the GROUP, wait, then SIGKILL it. `npm run dev` spawns grandchildren
+ *  that outlive a kill of the parent, which is what `detached: true` and the
+ *  negative pid are for. */
+function killGroup(pid, graceMs = 8_000) {
+  const signal = (sig) => {
+    try {
+      process.kill(-pid, sig);
+    } catch {
+      try {
+        process.kill(pid, sig);
+      } catch {
+        /* already gone */
+      }
+    }
+  };
+  signal('SIGTERM');
+  setTimeout(() => {
+    if (processAlive(pid)) signal('SIGKILL');
+  }, graceMs).unref?.();
+}
+
+/**
+ * THE FRESH-WORKTREE ANSWER, measured rather than discovered as a bug.
+ *
+ * `ensureWorktree` is a bare `git worktree add`, so a new tab has source and no
+ * `node_modules`, and the first run there would fail with something unhelpful.
+ * This is a measurement, and it routes dependency installation to the one place
+ * that should own it: a turn in the tab, with a human asking and an audit row
+ * for it. The button is never silently broken and the remedy is one sentence.
+ */
+export function missingDeps(worktree, argv) {
+  if (!PACKAGE_MANAGERS.has(argv[0])) return false;
+  return !existsSync(join(worktree, 'node_modules'));
+}
+
+/**
+ * Start the command and supervise it.
+ *
+ * `onState` is called with `{started, port, pid, error, endedReason, logTail,
+ * restarts}` at each transition; the caller reports it upward. Resolves once
+ * the first outcome is known — bound, or running-unmeasured, or failed — and
+ * keeps supervising after that.
+ */
+export function startDevServer({ sessionId, worktree, argv, log, onState, onExit }) {
+  if (missingDeps(worktree, argv)) {
+    return Promise.resolve({
+      ok: false,
+      endedReason: 'no_deps',
+      error:
+        "No dependencies are installed in this tab's worktree. Ask your Claude to install them, then run dev again.",
+    });
+  }
+
+  let ring = '';
+  let child = null;
+  let stopped = false;
+  let everBound = false;
+  let restarts = 0;
+  const restartTimes = [];
+
+  const append = (buf) => {
+    ring = (ring + buf.toString('utf8')).slice(-RING_BYTES);
+  };
+  const tail = () => scrub(ring.slice(-TAIL_BYTES));
+
+  const spawnOnce = () => {
+    child = spawn(argv[0], argv.slice(1), {
+      cwd: worktree,
+      env: childEnv({ cwd: worktree }),
+      // Its own process group, so the whole tree can be reaped. Load-bearing:
+      // a package manager is a wrapper and the server is its grandchild.
+      detached: true,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // PERMANENT DRAIN LISTENERS, and this is not optional. A detached
+    // long-lived child on piped stdio with no reader BLOCKS ON WRITE once the
+    // pipe buffer fills, so a dev server would hang after a few minutes of HMR
+    // logs — the least diagnosable failure this feature could have.
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+    return child;
+  };
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v) => {
+      if (settled) return;
+      settled = true;
+      resolve(v);
+    };
+
+    const attachExit = () => {
+      child.once('error', (e) => {
+        forget(child?.pid);
+        finish({ ok: false, endedReason: 'spawn_failed', error: String(e?.message || e) });
+      });
+      child.once('exit', (code, signal) => {
+        const pid = child?.pid;
+        forget(pid);
+        if (stopped) return;
+        // A command that NEVER bound is a broken command, not a crash. Restarting
+        // it would spin the box on somebody's typo.
+        const now = Date.now();
+        while (restartTimes.length && now - restartTimes[0] > RESTART_WINDOW_MS) restartTimes.shift();
+        if (everBound && restartTimes.length < MAX_RESTARTS) {
+          const delay = BACKOFF_MS[Math.min(restartTimes.length, BACKOFF_MS.length - 1)];
+          restartTimes.push(now);
+          restarts += 1;
+          log?.(`dev server exited (${signal || code}); restarting in ${delay / 1000}s`);
+          setTimeout(() => {
+            if (stopped) return;
+            spawnOnce();
+            attachExit();
+            remember(entryFor());
+            onState?.({ started: true, port: null, pid: child.pid, restarts, logTail: tail() });
+          }, delay).unref?.();
+          return;
+        }
+        onExit?.({
+          exitCode: typeof code === 'number' ? code : null,
+          signal: signal || null,
+          logTail: tail(),
+          endedReason: everBound ? 'crashed' : 'spawn_failed',
+          error: everBound
+            ? `the dev server exited (${signal || `code ${code}`})`
+            : `the command exited immediately (${signal || `code ${code}`}) without listening`,
+        });
+        finish({ ok: false, endedReason: everBound ? 'crashed' : 'spawn_failed' });
+      });
+    };
+
+    const entryFor = () => ({
+      sessionId,
+      pid: child.pid,
+      cwd: worktree,
+      startedAt: Date.now(),
+      owner: process.pid,
+    });
+
+    try {
+      spawnOnce();
+    } catch (e) {
+      finish({ ok: false, endedReason: 'spawn_failed', error: String(e?.message || e) });
+      return;
+    }
+    attachExit();
+    remember(entryFor());
+
+    // WATCH FOR THE BIND through `listenersIn` and nowhere else.
+    const deadline = Date.now() + BIND_WATCH_MS;
+    const poll = setInterval(() => {
+      if (stopped || !child || child.exitCode !== null) {
+        clearInterval(poll);
+        return;
+      }
+      const found = listenersIn(worktree)[0];
+      if (found) {
+        clearInterval(poll);
+        everBound = true;
+        onState?.({ started: true, port: found.port, pid: child.pid, restarts, logTail: tail() });
+        finish({ ok: true, port: found.port, pid: child.pid, stop, restarts });
+        return;
+      }
+      if (Date.now() > deadline) {
+        clearInterval(poll);
+        // RUNNING, NOTHING MEASURED. A real state and not a spinner: a
+        // `docker compose up` binds from inside a container whose cwd is not
+        // this worktree and will never be attributed.
+        onState?.({ started: true, port: null, pid: child.pid, restarts, logTail: tail() });
+        finish({ ok: true, port: null, pid: child.pid, stop, restarts });
+      }
+    }, 1000);
+    poll.unref?.();
+
+    function stop() {
+      stopped = true;
+      clearInterval(poll);
+      const pid = child?.pid;
+      if (pid) {
+        killGroup(pid);
+        forget(pid);
+      }
+    }
+  });
+}
+
+/**
+ * What survived a daemon restart.
+ *
+ * IDENTITY IS NOT THE COMMAND STRING. `stillOurs` in `preview.mjs` matches a
+ * substring of `/proc/<pid>/cmdline`, which cannot work here: `npm run dev` is
+ * a human-authored string identical across two tabs, two worktrees, and the
+ * driver's own hand-started server. Identity is the CWD — the same readlink
+ * `listeners.mjs` already does — plus the pid still being alive. Both must
+ * hold, and a could-not-measure is NOT a match and kills nothing.
+ */
+export function adoptableDevRuns() {
+  const out = [];
+  for (const e of readRegistry(REGISTRY)) {
+    if (!e || typeof e.sessionId !== 'string' || !Number.isInteger(e.pid)) continue;
+    // Another LIVE daemon owns it — leave it alone entirely.
+    if (e.owner && e.owner !== process.pid && processAlive(e.owner)) continue;
+    if (!processAlive(e.pid)) continue;
+    out.push(e);
+  }
+  return out;
+}
+
+/** Kill a registry entry's process group and drop the row. Used when the
+ *  session it belonged to is gone. */
+export function killDevRunEntry(entry) {
+  if (!entry || !Number.isInteger(entry.pid)) return;
+  killGroup(entry.pid);
+  forget(entry.pid);
+}
+
+/** Adopt or reap what the previous process left behind. `activeIds` is the set
+ *  of sessions still live on the server; a run whose session is gone is killed,
+ *  and one whose session survives is handed back to the caller to re-supervise. */
+export function reapOrphanDevRuns(activeIds, log) {
+  const adopt = [];
+  for (const e of adoptableDevRuns()) {
+    if (Array.isArray(activeIds) && !activeIds.includes(e.sessionId)) {
+      log?.(`dev server for a closed tab (pid ${e.pid}) — stopping it`);
+      killDevRunEntry(e);
+      continue;
+    }
+    adopt.push(e);
+  }
+  return adopt;
+}

package/bin/lib/fleet.mjs

@@ -76,11 +76,23 @@ import {
 } from './env.mjs';
 import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
 import { machineSnapshot } from './resources.mjs';
-import { detectRuntimes, knownSkills, pickRuntimeFor, RUNTIMES } from './runtimes.mjs';
+import {
+  detectRuntimes,
+  knownSkills,
+  pickRuntimeFor,
+  probeSkillsOnce,
+  recordSkills,
+  RUNTIMES,
+} from './runtimes.mjs';
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
 
-async function fetchRoster(haveIds, livePreviewSessionIds = [], heldSessionIds = []) {
+async function fetchRoster(
+  haveIds,
+  livePreviewSessionIds = [],
+  heldSessionIds = [],
+  liveDevRunSessionIds = []
+) {
   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
@@ -110,6 +122,11 @@ async function fetchRoster(haveIds, livePreviewSessionIds = [], heldSessionIds =
   // 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 dev runs this machine is still carrying. Same rule as `pv`: always set,
+  // even empty — '' means "running none", absent would mean "an older daemon",
+  // and a run the server still calls running with nothing behind it is a chip
+  // that says Serving over a dead port.
+  url.searchParams.set('dr', liveDevRunSessionIds.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
@@ -440,6 +457,11 @@ export async function runFleetDaemon() {
   // Kill any preview dev-server/tunnel groups a previously-crashed daemon left
   // running (detached children survive an ungraceful exit) before we start fresh.
   reapOrphanPreviews((m) => info(m));
+  // Dev servers are ADOPTED rather than reaped when their session is still
+  // live: a self-update or a same-repo takeover leaves them running on purpose,
+  // and the successor must supervise them or the row says running while nothing
+  // owns the process. The activeWorkSessions list is not known yet at startup,
+  // so the first reconcile does the adopting — see `adoptDevRuns`.
 
   // Persistent worktree home (0.9.0) — survives daemon restarts AND reboots,
   // so Ctrl+C mid-task never loses local work. Keyed per repo path.
@@ -558,6 +580,25 @@ export async function runFleetDaemon() {
     // Detached tunnels survive our exit by design, so leaving them would strand
     // a public hostname until the box rebooted.
     shutdownPreviews();
+    // AND THE DEV SERVERS, on every path that reaches here — all four are a
+    // stand-down: Ctrl-C, a service manager's SIGTERM, a revoked credential, a
+    // commanded stop.
+    //
+    // A SAME-REPO TAKEOVER IS DELIBERATELY NOT DISTINGUISHED, and that is a
+    // stated limitation rather than an oversight. The takeover asks the holder
+    // to stand down with SIGTERM, which is byte-for-byte what `systemctl stop`
+    // sends, so this handler cannot tell "another daemon is about to serve this
+    // repo in one second" from "this box is going down". Killing is the safe
+    // reading: the wrong guess in the other direction leaves dev servers
+    // running with nothing supervising them until a reboot. The cost is that
+    // re-running `flowviant` in your own repo restarts the app you were
+    // watching, and the successor's `adoptDevRuns` finds nothing.
+    //
+    // The SELF-UPDATE re-exec — the common unattended case — does NOT reach
+    // teardown, so its runs survive and are adopted, which is the half of
+    // "consistently running" this delivers today. Distinguishing a takeover
+    // would need the successor to mark the lock before it signals.
+    shutdownDevRuns(true);
   };
   process.on('SIGINT', () => {
     console.log('');
@@ -734,6 +775,11 @@ export async function runFleetDaemon() {
     livePreviewIds,
     retirePreviews,
     shutdownPreviews,
+    processDevRunJobs,
+    liveDevRunIds,
+    retireDevRuns,
+    shutdownDevRuns,
+    adoptDevRuns,
     retireWorkSessions,
     reportWorktrees,
     shutdownWork,
@@ -1185,6 +1231,13 @@ export async function runFleetDaemon() {
               label: c.cyan('[wiki]'),
               streamJson: true,
               onActivity,
+              // FREE SKILLS, off a turn that was running anyway. This stream is
+              // already parsed and its init event already carries the CLI's own
+              // resolved skill set — the same fact a tab turn teaches — so the
+              // only thing missing was the handler. The wiki turn runs in a
+              // detached worktree of THIS repo, so its `.claude/skills` and the
+              // machine's personal ones resolve identically to a tab's.
+              onInit: (i) => recordSkills(i.skills),
               onSpawn: (ch) => {
                 wikiChild = ch;
               },
@@ -1229,6 +1282,8 @@ export async function runFleetDaemon() {
                 label: c.cyan('[wiki]'),
                 streamJson: true,
                 onActivity,
+                // Same free harvest as the sweep above.
+                onInit: (i) => recordSkills(i.skills),
                 onSpawn: (ch) => {
                   wikiChild = ch;
                 },
@@ -1330,7 +1385,7 @@ export async function runFleetDaemon() {
   for (;;) {
     let roster;
     try {
-      roster = await fetchRoster(buildHave(), livePreviewIds(), heldSessionIds());
+      roster = await fetchRoster(buildHave(), livePreviewIds(), heldSessionIds(), liveDevRunIds());
     } catch (e) {
       if (e.auth) {
         fail(`${e.message} — credential revoked or invalid. Shutting down.`);
@@ -1449,6 +1504,18 @@ 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);
+    // THEN the process the tunnel pointed at, and only then the worktree. A
+    // viewer must not see a 502 from a gate whose origin vanished, and
+    // `retireWorkSessions`'s dirty check inspects only TRACKED files — so
+    // `git worktree remove` would happily pull the directory out from under a
+    // running node process, which then serves bytes from open file handles in
+    // a directory that no longer exists, with no error anywhere.
+    // ADOPT BEFORE RETIRING. A run left alive by a self-update or a takeover
+    // must be re-attached before the retire pass can decide it is unowned;
+    // doing it the other way round would kill exactly the processes this
+    // feature exists to keep.
+    adoptDevRuns(roster.activeWorkSessions);
+    retireDevRuns(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
@@ -1467,6 +1534,7 @@ export async function runFleetDaemon() {
     // credential are both handed this array, and both opening a tunnel strands
     // a public hostname nobody can settle.
     processPreviewJobs(roster.previewJobs);
+    processDevRunJobs(roster.devRunJobs);
     // …and what the SURVIVING ones hold: branch, ahead-of-base, diffstat.
     // Throttled inside, never awaited — a `git status` the human cannot run
     // themselves from a browser, relayed. After retirement so a directory that
@@ -1476,6 +1544,13 @@ export async function runFleetDaemon() {
     // the daemon's own worktrees are carved out (a session the daemon spawned
     // is already a tab, not something to offer adopting).
     void maybeReportLocalSessions({ repoRoot, excludeDirs: [baseDir] });
+    // WHAT `/` CAN OFFER, on a machine no turn has taught yet. One-shot and
+    // self-cancelling (it returns immediately if a turn has already reported),
+    // never awaited, and it lands in the cache that the NEXT poll reads — so
+    // nothing here waits on a child process. In the loop rather than at
+    // startup on purpose: a daemon that has been up since before this release
+    // gets measured too, without needing a restart to earn its own menu.
+    probeSkillsOnce(repoRoot);
     processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));
 

package/bin/lib/procRegistry.mjs

@@ -0,0 +1,134 @@
+/**
+ * A DISK REGISTRY OF DETACHED PROCESSES — one implementation, two users.
+ *
+ * The daemon spawns things that outlive it: cloudflared tunnels, and now dev
+ * servers. If the daemon dies without tearing them down, the successor has to
+ * find them — a public tunnel nobody is minding, or a dev server holding a port
+ * in a worktree about to be `git worktree remove`d, are both worse than the
+ * crash that caused them.
+ *
+ * Lifted verbatim out of `preview.mjs`, which grew all of this for the tunnel
+ * and now shares it rather than being copied. Two things were ADDED on the way
+ * out, because a dev server lives for hours where a tunnel lived for minutes
+ * and long-lived rows make both matter:
+ *
+ *  - an entry CAP, so a registry cannot grow without bound;
+ *  - a TTL sweep for entries whose pid is long dead, so a file nobody prunes
+ *    does not become a file nobody can read.
+ */
+
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+
+const LOCK_STALE_MS = 15_000;
+const MAX_ENTRIES = 32;
+const ENTRY_TTL_MS = 7 * 24 * 60 * 60_000;
+
+/**
+ * Best-effort exclusive lock. Returns a release function; on failure returns
+ * null and the caller proceeds UNLOCKED — losing an entry is bad, refusing to
+ * record one at all is worse.
+ */
+export function acquireLock(dir, lockPath) {
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return null;
+  }
+  for (let i = 0; i < 30; i++) {
+    try {
+      const fd = openSync(lockPath, 'wx');
+      closeSync(fd);
+      return () => {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          /* already released */
+        }
+      };
+    } catch {
+      // Held — unless it was left behind by something that died holding it.
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      const until = Date.now() + 20;
+      while (Date.now() < until) {
+        /* busy-wait: 20ms, 30 times, then give up entirely */
+      }
+    }
+  }
+  return null;
+}
+
+export function readRegistry(path) {
+  try {
+    const v = JSON.parse(readFileSync(path, 'utf8'));
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Atomic: write a sibling temp file and rename over the target, so a reader
+ *  never sees a half-written array. */
+export function writeRegistry(dir, path, list) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(list));
+    renameSync(tmp, path);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Signal-0 liveness. EPERM means alive and not ours, which is still alive. */
+export function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+/**
+ * Read-modify-write under the lock, then prune.
+ *
+ * The prune is here rather than at the call sites so it cannot be forgotten by
+ * one of them: an entry whose pid has been dead for a week is not a process
+ * anybody is going to reap, and keeping it only makes the next reader slower
+ * and the next pid collision more likely.
+ */
+export function mutateRegistry(dir, path, lockPath, fn) {
+  const release = acquireLock(dir, lockPath);
+  try {
+    const next = fn(readRegistry(path));
+    const now = Date.now();
+    const pruned = next
+      .filter((e) => {
+        if (processAlive(e?.pid)) return true;
+        const started = Number(e?.startedAt ?? 0);
+        return started > 0 && now - started < ENTRY_TTL_MS;
+      })
+      .slice(-MAX_ENTRIES);
+    writeRegistry(dir, path, pruned);
+    return pruned;
+  } finally {
+    release?.();
+  }
+}

package/bin/lib/runtimes.mjs

@@ -36,9 +36,9 @@
  * machine HAVE" — activity, never capacity, and never a default we invented.
  */
 
-import { execFileSync } from 'node:child_process';
-import { mkdtempSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SAFE, MODEL, USER_AGENT } from './config.mjs';
 
@@ -976,3 +976,191 @@ export function recordSkills(names) {
 export function knownSkills() {
   return skillsCache;
 }
+
+/**
+ * LEARN WHAT `/` CAN OFFER, ON A MACHINE NO TURN HAS TAUGHT.
+ *
+ * WHY THIS EXISTS. `recordSkills` above is fed from the init event of a tab
+ * turn — authoritative and free, but with a hole nobody priced: THE FIRST THING
+ * ANYONE DOES IN A NEW TAB IS TYPE `/`, and that is by definition before that
+ * machine has run a turn. The menu was guaranteed empty exactly where it is
+ * first reached. Not a theoretical hole: checked against production on
+ * 2026-08-25, `agent_tokens.skills` was NULL for EVERY machine credential that
+ * has ever existed, because the only tab turns ever run predated the release
+ * that reports. The feature had never worked for anyone, once.
+ *
+ * IT COSTS ONE SMALL REQUEST, AND THAT IS THE HONEST NUMBER. This file used to
+ * forbid probing outright — "a `claude -p` run purely to populate a dropdown
+ * would spend the operator's quota on an affordance" — and that rule was
+ * written picturing a COMPLETED TURN. This is not one: Claude Code emits
+ * `system.init`, carrying its own fully resolved skill set, within ~0.5s and
+ * long before it finishes answering, so the child is killed the moment that
+ * event is read. But the request HAS gone out by then — measured on 2.1.245 by
+ * reading the transcript a killed probe left behind: 2 input tokens, 4 output,
+ * ~6k cache-creation. Two zero-request routes were tried and both failed: an
+ * empty prompt errors before init is emitted, and `--input-format stream-json`
+ * emits nothing at all until a message arrives. So the cost is one cheap turn,
+ * ONCE per daemon process, on the cheapest model, and only on a machine no turn
+ * has taught. Do not let this grow into a per-tab or per-poll probe.
+ *
+ * `--model haiku` for that reason, and it is safe by this repo's own rule: a
+ * name lives in AGENT_MODELS only once `claude --model <name>` is known to be
+ * accepted on a real install. If it were ever refused the probe simply learns
+ * nothing and the machine stays unmeasured — which is exactly today's state, so
+ * the failure mode is the status quo rather than a regression.
+ *
+ * IT SCANS FOR THE INIT EVENT, never assuming it is line 1 — and that is not
+ * defensive padding, it is measured. With `--model haiku` the CLI prints a
+ * `system/status` line FIRST and init lands on line 2; with the default model
+ * init is line 1. A first-line-only reader (the version this replaced) silently
+ * learned nothing the moment a model flag was added.
+ *
+ * IT CLEANS UP AFTER ITSELF, and this is not optional. `claude -p` writes a
+ * transcript to `~/.claude/projects/<munged-cwd>/<session-id>.jsonl` the moment
+ * it starts, and `localSessions.mjs` reports the newest ENDED session per
+ * directory to the Workbench as an ADOPTABLE row. Left behind, every daemon
+ * start would put a phantom untitled session in the `+` menu offering to adopt
+ * a conversation that never happened. The init event names its own session id,
+ * so the file is ours by name and is removed by it.
+ *
+ * IT IS BEST-EFFORT IN EVERY DIRECTION. No claude, no PATH, a CLI that changed
+ * its event shape, an unwritable home — all leave `skillsCache` exactly as it
+ * was (null, "nobody looked"), which is the honest answer and the one the app
+ * already renders correctly. Nothing here may throw, and nothing may block the
+ * poll it is called from.
+ */
+
+/** Long enough for a cold CLI start on a slow box, short enough that a hung
+ *  child is not left holding a session for the life of the daemon. */
+const SKILL_PROBE_TIMEOUT_MS = 30_000;
+
+/** Init arrives within the first couple of events or not at all; this is the
+ *  guard against parsing a whole turn's output looking for it. */
+const SKILL_PROBE_MAX_LINES = 20;
+
+let skillProbeStarted = false;
+
+/** Where Claude Code keeps a transcript for `cwd`: `/` and `.` both become `-`. */
+function transcriptCandidates(cwd, sessionId) {
+  const base = join(homedir(), '.claude', 'projects');
+  const out = [join(base, cwd.replace(/[/.]/g, '-'), `${sessionId}.jsonl`)];
+  // The munge is Claude Code's, not ours, so a version that changes it must not
+  // leave the file behind: fall back to finding our own session id by name.
+  try {
+    for (const d of readdirSync(base)) out.push(join(base, d, `${sessionId}.jsonl`));
+  } catch {
+    /* no project store — nothing was written either */
+  }
+  return out;
+}
+
+function removeProbeTranscript(cwd, sessionId) {
+  if (!sessionId || !/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) return;
+  for (const f of transcriptCandidates(cwd, sessionId)) {
+    try {
+      if (existsSync(f)) {
+        rmSync(f, { force: true });
+        return;
+      }
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * One line of the probe's stdout → the init event's payload, or null for "not
+ * it, keep reading".
+ *
+ * SEPARATE FROM THE SCAN LOOP so the thing that actually broke can be tested
+ * without spawning a CLI. The first version of this probe read line 1 and
+ * stopped, which was measured-correct with the default model and silently
+ * WRONG with `--model haiku`: that path prints a `system/status` line first and
+ * puts init on line 2, so the probe learned nothing and reported nothing, which
+ * is indistinguishable from the bug it was written to fix.
+ *
+ * A line that is not JSON is not a failure — a CLI warning on stdout is a line
+ * to skip, not a reason to abandon the probe.
+ */
+export function parseInitLine(line) {
+  let ev;
+  try {
+    ev = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!ev || ev.type !== 'system' || ev.subtype !== 'init') return null;
+  return {
+    // An init event WITHOUT skills is still the init event: stop reading, but
+    // record nothing. Conflating the two would keep the probe scanning a whole
+    // turn's output on a CLI that does not report them.
+    skills: Array.isArray(ev.skills) ? ev.skills : null,
+    sessionId: typeof ev.session_id === 'string' ? ev.session_id : null,
+  };
+}
+
+/**
+ * Kick off the one-shot probe. Returns immediately; the result lands in
+ * `skillsCache` and rides the NEXT poll, so nothing waits on it.
+ *
+ * A no-op once a turn has taught us (`skillsCache !== null`) — a turn's init
+ * event and this one say the same thing, and the turn is free.
+ */
+export function probeSkillsOnce(cwd) {
+  if (skillProbeStarted || skillsCache !== null) return;
+  skillProbeStarted = true;
+  let child;
+  try {
+    // Claude Code specifically, not the `wiki` profile's runtime pick: `skills`
+    // is Claude Code's own field and the `/` tray only renders for claude tabs.
+    child = spawn(
+      RUNTIMES.claude.bin,
+      ['-p', 'x', '--model', 'haiku', '--output-format', 'stream-json', '--verbose'],
+      { cwd, stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+  } catch {
+    return; // no claude on PATH — the machine simply stays unmeasured
+  }
+  let buf = '';
+  let lines = 0;
+  let settled = false;
+  const finish = (sessionId) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+    // AFTER the kill, and on a delay: the transcript is the CHILD's file, so
+    // deleting it while the child still lives races a recreate.
+    if (sessionId) setTimeout(() => removeProbeTranscript(cwd, sessionId), 750).unref?.();
+  };
+  const timer = setTimeout(() => finish(null), SKILL_PROBE_TIMEOUT_MS);
+  timer.unref?.();
+  child.on('error', () => finish(null));
+  child.on('exit', () => finish(null));
+  child.stdout.on('data', (d) => {
+    if (settled) return;
+    buf += d.toString();
+    let nl;
+    while (!settled && (nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      if (!line.trim()) continue;
+      if (++lines > SKILL_PROBE_MAX_LINES) {
+        finish(null);
+        return;
+      }
+      const init = parseInitLine(line);
+      if (!init) continue;
+      if (init.skills) recordSkills(init.skills);
+      finish(init.sessionId);
+      return;
+    }
+    // A single line this long is not an init event; stop buffering a whole
+    // turn's output into memory waiting for one.
+    if (!settled && buf.length > 1_000_000) finish(null);
+  });
+}

package/bin/lib/work.mjs

@@ -38,8 +38,9 @@ import {
   DAEMON_INSTANCE,
 } from './config.mjs';
 import { git, gitRaw, splitNul, baseBranchName, isSafePathSegment } from './git.mjs';
-import { listenersIn } from './listeners.mjs';
+import { listenersIn, listenersSupported } from './listeners.mjs';
 import { openTunnel } from './preview.mjs';
+import { startDevServer, reapOrphanDevRuns, killDevRunEntry } from './devServer.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { mcpFor, runTurn } from './claude.mjs';
 import {
@@ -102,6 +103,8 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
   const DIFF_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/diff-done');
   const PREVIEW_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/preview-claim');
   const PREVIEW_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/preview-done');
+  const DEV_RUN_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-claim');
+  const DEV_RUN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-done');
   const SESSION_COMMANDS_URL = FLEET_URL.replace(/\/agents\/?$/, '/session-commands');
   const ATTACHMENT_URL = FLEET_URL.replace(/\/agents\/?$/, '/attachment');
   const workAnswering = new Set(); // turn ids currently queued/running here
@@ -350,7 +353,17 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     // The browser NEVER names a directory and never names a port this did not
     // report: ports are global to a box and a worktree is not, so this
     // measurement is the security boundary for the whole preview feature.
-    return { sessionId, ...d, listening: listenersIn(wt) };
+    // `listeningSupported` says whether this machine can measure AT ALL, which
+    // is a different fact from finding nothing. Windows reports nothing and a
+    // failed scan reports nothing, and both were indistinguishable from an idle
+    // worktree — harmless while the only consumer needed a NON-empty array, and
+    // a permanent `Starting…` the moment a Run dev offer hangs off an empty one.
+    return {
+      sessionId,
+      ...d,
+      listening: listenersIn(wt),
+      listeningSupported: listenersSupported(),
+    };
   };
   /** One session, now — called after its turn settles. */
   const reportSessionWorktree = async (sessionId) => {
@@ -634,6 +647,259 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
   /** The sessionIds this machine is still serving — sent on the poll so the
    *  server can tell a live share from one whose machine went away. Silence
    *  must never read as "live". */
+  /**
+   * The daemon's own shape check on an argv the server parsed.
+   *
+   * Deliberately a SHAPE check and not a re-parse: the server owns the policy
+   * (which argv[0] are allowed, the install refusal, the length caps) and the
+   * machine owns the refusal to EXECUTE something malformed. It is duplicated
+   * rather than imported because this package ships standalone and cannot
+   * depend on the monorepo — the mirror is small, and `devCommand.ts` is where
+   * the real rules live.
+   */
+  const isPlausibleDevArgv = (argv) =>
+    Array.isArray(argv) &&
+    argv.length > 0 &&
+    argv.length <= 8 &&
+    argv.every((a) => typeof a === 'string' && a.length > 0 && a.length <= 200) &&
+    !argv.some((a) => /[&|;<>`$(){}*?~\\]/.test(a));
+
+  // ── DEV RUNS ──────────────────────────────────────────────────────────
+  //
+  // The web asks for the PROJECT'S STORED command to run in a tab's worktree.
+  // The argv arrives on the job, already parsed from a string a human approved;
+  // nothing here reads a repo file to decide what executes. See devServer.mjs.
+  const liveDevRuns = new Map(); // sessionId -> { stop, pid }
+  const devRunClaiming = new Set();
+
+  const postDevRun = async (body) => {
+    try {
+      await fetch(DEV_RUN_DONE_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify({ ...body, instance: DAEMON_INSTANCE }),
+      });
+    } catch {
+      /* the row stops being confirmed and reads as stopped — which is true */
+    }
+  };
+
+  const claimDevRun = async (sessionId) => {
+    try {
+      const res = await fetch(DEV_RUN_CLAIM_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify({ sessionId, instance: DAEMON_INSTANCE }),
+      });
+      const j = await res.json().catch(() => ({}));
+      return Boolean(j?.data?.claimed);
+    } catch {
+      return false;
+    }
+  };
+
+  const stopDevRun = async (sessionId, reason) => {
+    const live = liveDevRuns.get(sessionId);
+    liveDevRuns.delete(sessionId);
+    try {
+      live?.stop?.();
+    } catch {
+      /* best-effort */
+    }
+    await postDevRun({ sessionId, ended: true, endedReason: reason });
+  };
+
+  const processDevRunJobs = (jobs) => {
+    if (!Array.isArray(jobs) || jobs.length === 0) return;
+    for (const job of jobs.slice(0, 5)) {
+      const sessionId = String(job?.sessionId || '');
+      if (!isSafePathSegment(sessionId)) continue;
+
+      if (job?.action === 'stop') {
+        if (devRunClaiming.has(sessionId)) continue;
+        devRunClaiming.add(sessionId);
+        void stopDevRun(sessionId, 'stopped').finally(() => devRunClaiming.delete(sessionId));
+        continue;
+      }
+
+      // RE-VALIDATE THE SHAPE at this boundary. The server parsed the string
+      // and owns the policy; the machine owns the refusal to execute something
+      // malformed, because one place doing a check is one deploy away from
+      // being zero places.
+      const argv = Array.isArray(job?.argv) ? job.argv.map(String) : [];
+      if (!isPlausibleDevArgv(argv)) {
+        void postDevRun({
+          sessionId,
+          started: false,
+          endedReason: 'refused',
+          error: 'the machine did not recognise that command',
+        });
+        continue;
+      }
+      // Already serving this tab. Re-starting would kill a server somebody is
+      // looking at right now.
+      if (liveDevRuns.has(sessionId)) continue;
+      if (devRunClaiming.has(sessionId)) continue;
+      devRunClaiming.add(sessionId);
+
+      void (async () => {
+        try {
+          if (!(await claimDevRun(sessionId))) return; // somebody else has it
+          const wt = join(baseDir, 'sessions', sessionId);
+          const r = await startDevServer({
+            sessionId,
+            worktree: wt,
+            argv,
+            log: (m) => note(`dev ${sessionId.slice(0, 8)}: ${m}`),
+            onState: (st) => {
+              void postDevRun({ sessionId, ...st });
+              // Re-report the worktree at once so the chip flips within a
+              // second instead of waiting up to 60s for the sweep.
+              void reportSessionWorktree(sessionId).catch(() => undefined);
+            },
+            onExit: (ex) => {
+              liveDevRuns.delete(sessionId);
+              void postDevRun({ sessionId, ended: true, ...ex });
+            },
+          });
+          if (!r.ok) {
+            await postDevRun({
+              sessionId,
+              started: false,
+              endedReason: r.endedReason ?? 'spawn_failed',
+              error: r.error ?? 'the machine could not start it',
+            });
+            return;
+          }
+          liveDevRuns.set(sessionId, { stop: r.stop, pid: r.pid });
+          // THE AUDIT ROW. Without it a daemon-spawned dev server would be the
+          // ONLY execution on this box with no entry in the very surface built
+          // so an admin can answer "what ran on this machine" — and it would be
+          // missing precisely the execution whose provenance is most worth
+          // checking. `runtime: null` because no CLI ran it: the daemon did.
+          void fetch(SESSION_COMMANDS_URL, {
+            method: 'POST',
+            headers: {
+              Authorization: `Bearer ${FLEET_TOKEN}`,
+              'User-Agent': USER_AGENT,
+              'Content-Type': 'application/json',
+            },
+            signal: AbortSignal.timeout(30_000),
+            body: JSON.stringify({
+              sessionId,
+              cwd: wt,
+              commands: [{ command: argv.join(' '), at: new Date().toISOString() }],
+            }),
+          }).catch(() => {
+            /* best-effort — the audit records what reached it */
+          });
+        } finally {
+          devRunClaiming.delete(sessionId);
+        }
+      })();
+    }
+  };
+
+  /**
+   * ADOPT what the previous process left behind.
+   *
+   * This is the half of "consistently running" that actually delivers it. A
+   * self-update re-execs, and a same-repo takeover replaces this process — both
+   * leave dev servers alive on purpose (see `shutdownDevRuns`), and without
+   * adoption the successor would neither supervise them nor be able to stop
+   * them, so the row would say running while nothing owned the process.
+   *
+   * Identity is the CWD plus liveness, never the command string: `npm run dev`
+   * is identical across two tabs, two worktrees, and the driver's own
+   * hand-started server, so a cmdline match would be indistinguishable from a
+   * coincidence. A could-not-measure is NOT a match and kills nothing.
+   */
+  const adoptDevRuns = (activeIds) => {
+    let adopted = 0;
+    for (const entry of reapOrphanDevRuns(activeIds, note)) {
+      const wt = join(baseDir, 'sessions', entry.sessionId);
+      // The recorded cwd must still be this session's worktree. A recycled pid
+      // pointing anywhere else is somebody else's process.
+      if (entry.cwd !== wt) continue;
+      if (liveDevRuns.has(entry.sessionId)) continue;
+      liveDevRuns.set(entry.sessionId, {
+        pid: entry.pid,
+        stop: () => killDevRunEntry(entry),
+      });
+      adopted += 1;
+      // The output ring is EMPTY for an adopted run and the row says so rather
+      // than pretending to a tail it does not have.
+      void postDevRun({
+        sessionId: entry.sessionId,
+        started: true,
+        pid: entry.pid,
+        port: listenersIn(wt)[0]?.port ?? null,
+        logTail: '[reattached after the machine restarted — earlier output is not kept]',
+      });
+    }
+    if (adopted > 0) note(`re-attached ${adopted} dev server${adopted === 1 ? '' : 's'}`);
+  };
+
+  /** The sessionIds this machine is still running, sent on the poll so the
+   *  server can tell a live run from one whose machine went away. */
+  const liveDevRunIds = () => [...liveDevRuns.keys()];
+
+  /** A tab closed. ORDER MATTERS and the caller keeps it: the tunnel is retired
+   *  BEFORE the process it points at, so a viewer sees a dead link rather than
+   *  a 502 from a gate whose origin vanished — and both happen before
+   *  `retireWorkSessions` can `git worktree remove` the directory out from
+   *  under a running node process, which it would do without complaint because
+   *  its dirty check inspects only TRACKED files and node_modules is not one. */
+  const retireDevRuns = (activeIds) => {
+    if (!Array.isArray(activeIds)) return; // an older server, not a close
+    const live = new Set(activeIds);
+    for (const sessionId of [...liveDevRuns.keys()]) {
+      if (live.has(sessionId)) continue;
+      if (devRunClaiming.has(sessionId)) continue;
+      devRunClaiming.add(sessionId);
+      void stopDevRun(sessionId, 'tab_closed').finally(() => devRunClaiming.delete(sessionId));
+    }
+  };
+
+  /**
+   * Daemon shutdown, and the SPLIT is what delivers "consistently running".
+   *
+   * `kill: true` — a human hit Ctrl-C, the credential was revoked, or a stop was
+   * commanded. All three mean THIS MACHINE IS STANDING DOWN, and leaving dev
+   * servers behind would strand them.
+   *
+   * `kill: false` — a same-repo takeover, or a self-update re-exec. Both mean
+   * ANOTHER DAEMON IS ABOUT TO SERVE THIS REPO IN ONE SECOND, and killing would
+   * mean `flowviant` re-run in your own directory restarts the app you were
+   * watching, and a routine auto-update silently kills every dev server with
+   * nothing to bring them back — precisely the goal defeated. The registry rows
+   * are left for the successor to adopt.
+   */
+  const shutdownDevRuns = (kill) => {
+    if (!kill) {
+      liveDevRuns.clear();
+      return;
+    }
+    for (const [, live] of liveDevRuns) {
+      try {
+        live.stop?.();
+      } catch {
+        /* best-effort */
+      }
+    }
+    liveDevRuns.clear();
+  };
+
   const livePreviewIds = () => [...livePreviews.keys()];
 
   /**
@@ -2238,6 +2504,11 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     livePreviewIds,
     retirePreviews,
     shutdownPreviews,
+    processDevRunJobs,
+    liveDevRunIds,
+    retireDevRuns,
+    shutdownDevRuns,
+    adoptDevRuns,
     retireWorkSessions,
     reportWorktrees,
     shutdownWork,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.56.1",
+  "version": "0.57.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": {