flowviant 0.57.0 → 0.59.0

package/README.md

@@ -41,7 +41,7 @@ Prefer an explicit token? Create a machine credential in the app and pass it dir
 FLOWVIANT_FLEET=fva_… npx flowviant@latest
 ```
 
-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).
+Launch with `@latest` so each start pulls the newest published version — a bare `npx flowviant` can reuse a stale cache. A running daemon also keeps itself current: from **0.58.0** it restarts itself through `npx flowviant@latest` when a new version ships, so npx launches stay up to date the same way a global install does. (Before 0.58.0 that was only true of a global install — under npx the daemon printed a notice and stayed put, which is how machines ended up sitting several releases back.) It only ever restarts when no turn is running. `FLOWVIANT_NO_UPDATE=1` makes it nag-only; `flowviant update` updates now.
 
 ## Sessions
 

package/bin/cli.mjs

@@ -16,8 +16,11 @@
  * sat against an empty tool list, which is a worse failure than not starting.
  *
  * Launch with `@latest` so each start pulls the newest published version (bare
- * `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
+ * `npx flowviant` can reuse a stale cache). A running daemon also keeps itself
+ * current — at startup and when idle, never mid-turn. Since 0.58.0 that is true
+ * under NPX too, by relaunching through `npx flowviant@latest`; before it, the
+ * npx branch refused to install and only nagged, so npx launches — the way this
+ * README tells everyone to start — silently stayed on whatever was cached
  * (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`.

package/bin/lib/fleet.mjs

@@ -86,6 +86,7 @@ import {
 } from './runtimes.mjs';
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
+import { repoState } from './repoState.mjs';
 
 async function fetchRoster(
   haveIds,
@@ -298,6 +299,62 @@ async function maybeReportLocalSessions({ repoRoot, excludeDirs }) {
   }
 }
 
+/**
+ * EVERY BRANCH AND WORKTREE ON THIS MACHINE, pushed on the same beat as
+ * presence — the answer to "is my Claude leaving a mess in here?".
+ *
+ * Same three economies as the presence report above and for the same reasons:
+ * scanned at most once a minute, not re-sent while identical (repoState orders
+ * deterministically so the string only moves when the repo does), and silent
+ * for the rest of the process once an older server 404s.
+ *
+ * ONE DIFFERENCE, deliberate: there is no re-send heartbeat window. Presence
+ * expires in the UI because a session that ENDED must stop reading as live;
+ * a branch list is not presence — a branch that existed a minute ago still
+ * exists — so re-posting an unchanged list would be a write per machine per
+ * five minutes to say nothing at all.
+ */
+const REPO_STATE_URL = FLEET_URL.replace(/\/agents\/?$/, '/repo-state');
+const REPO_STATE_SCAN_MS = 60_000;
+let repoStateUnsupported = false; // the server 404'd — quiet until restart
+let repoStateScanAt = 0;
+let repoStateSent = null; // last payload the server ACCEPTED, stringified
+async function maybeReportRepoState({ repoRoot, baseRef }) {
+  if (repoStateUnsupported) return;
+  if (Date.now() - repoStateScanAt < REPO_STATE_SCAN_MS) return;
+  repoStateScanAt = Date.now();
+  let payload;
+  try {
+    const state = repoState(repoRoot, baseRef);
+    if (!state) return; // not readable — say nothing rather than say "none"
+    payload = JSON.stringify(state);
+  } catch {
+    return; // a readout must never throw into the poll loop
+  }
+  if (payload === repoStateSent) return;
+  try {
+    const res = await fetch(REPO_STATE_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${FLEET_TOKEN}`,
+        'User-Agent': USER_AGENT,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(15_000),
+      body: payload,
+    });
+    if (res.status === 404) {
+      repoStateUnsupported = true; // older server — nothing was replaced here
+      return;
+    }
+    // Only an ACCEPTED report counts: anything else forgets it so the next
+    // pass retries rather than dedup-suppressing a report nobody received.
+    repoStateSent = res.ok ? payload : null;
+  } catch {
+    repoStateSent = null;
+  }
+}
+
 /**
  * A STOP COMMANDED BY FLOWVIANT, read off the roster poll.
  *
@@ -1544,6 +1601,9 @@ 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] });
+    // …and the repo itself: every worktree and every branch, ours and not.
+    // Never awaited, throttled inside, and silent on an older server.
+    void maybeReportRepoState({ repoRoot, baseRef });
     // 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

package/bin/lib/repoState.mjs

@@ -0,0 +1,183 @@
+/**
+ * EVERY WORKTREE AND EVERY BRANCH ON THIS MACHINE — including the ones
+ * Flowviant did not make.
+ *
+ * WHY THIS EXISTS, in the user's words: "can we show all branches or worktrees
+ * so we know if claude is polluting the branches or worktrees or not". The
+ * Workbench already reports the branch a TAB is standing on, but only for
+ * sessions the server knows about — so a branch your Claude cut mid-turn, a
+ * worktree left behind by a crash, or anything you made yourself at the
+ * keyboard was invisible from the browser. That is the same gap the Changes
+ * block was built to close, one level up: a browser has no `git branch` to run,
+ * so the machine runs it.
+ *
+ * IT IS A RELAY, NOT A JUDGEMENT. Nothing here decides what "pollution" is —
+ * it reports what git says and marks which refs Flowviant itself created
+ * (`session/<id>`), because that is a FACT about who made them and it is the
+ * distinction the question is actually asking about. No cleanup, no warnings,
+ * no "you have too many branches": the surface counts what is there, and a
+ * person decides.
+ *
+ * BOUNDED AT THE MACHINE, like every other report in this daemon. A repo with
+ * eight hundred branches must not put eight hundred rows on the wire every
+ * minute; the newest are kept, the rest are counted, and the caller says so
+ * rather than letting a short list read as the whole repo.
+ *
+ * DETERMINISTIC ORDER, for the same reason `recordSkills` sorts: the report is
+ * dedupe-compared against the last one that was accepted, and an unstable order
+ * would post a "change" every single minute forever.
+ *
+ * NOTHING HERE THROWS. It runs inside the poll loop's best-effort tail, and a
+ * repo mid-rebase or an unborn HEAD is a field to omit, not an error to raise.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { listenersIn, listenersSupported } from './listeners.mjs';
+
+/** Same cap the session diffstat uses: enough to see the shape, small enough
+ *  that one machine cannot flood a row. */
+const MAX_BRANCHES = 60;
+const MAX_WORKTREES = 40;
+
+function git(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 10_000,
+    maxBuffer: 8 * 1024 * 1024,
+  }).trim();
+}
+
+/** A ref Flowviant itself cut for a tab. The ONLY thing that makes a branch
+ *  "ours", and the distinction the whole report exists to draw. */
+export function isSessionBranch(name) {
+  return /^session\//.test(name);
+}
+
+/**
+ * `git worktree list --porcelain` → rows. The porcelain form is parsed rather
+ * than the human one because the human one aligns columns with spaces and a
+ * path containing a space silently splits into the wrong fields.
+ */
+function readWorktrees(repoRoot) {
+  let out;
+  try {
+    out = git(['worktree', 'list', '--porcelain'], repoRoot);
+  } catch {
+    return null; // not a git repo, or git is unhappy — say nothing
+  }
+  const rows = [];
+  let cur = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) rows.push(cur);
+      cur = { path: line.slice(9), branch: null, detached: false, locked: false, prunable: false };
+    } else if (!cur) {
+      continue;
+    } else if (line.startsWith('branch ')) {
+      cur.branch = line.slice(7).replace(/^refs\/heads\//, '');
+    } else if (line === 'detached') {
+      cur.detached = true;
+    } else if (line.startsWith('locked')) {
+      cur.locked = true;
+    } else if (line.startsWith('prunable')) {
+      // A directory git still lists but that is gone from disk — exactly the
+      // "left behind" case somebody looking for mess wants to see.
+      cur.prunable = true;
+    }
+  }
+  if (cur) rows.push(cur);
+  return rows;
+}
+
+/**
+ * Local branches with their distance from base.
+ *
+ * `for-each-ref` does the whole thing in ONE process — a `rev-list` per branch
+ * would be sixty spawns a minute on a busy repo. `%(ahead-behind:<ref>)` needs
+ * git 2.41+; when it is missing the counts are simply absent and the surface
+ * shows names without numbers, which is still the answer to "what is here".
+ */
+function readBranches(repoRoot, baseRef) {
+  const fmt = '%(refname:short)%09%(committerdate:unix)%09%(ahead-behind:' + baseRef + ')';
+  let out;
+  try {
+    out = git(['for-each-ref', '--sort=-committerdate', `--format=${fmt}`, 'refs/heads'], repoRoot);
+  } catch {
+    // No ahead-behind on this git. Names and dates still answer most of it.
+    try {
+      out = git(
+        ['for-each-ref', '--sort=-committerdate', '--format=%(refname:short)%09%(committerdate:unix)', 'refs/heads'],
+        repoRoot
+      );
+    } catch {
+      return null;
+    }
+  }
+  const rows = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    const [name, when, ab] = line.split('\t');
+    if (!name) continue;
+    const row = { name, at: Number(when) || 0, session: isSessionBranch(name) };
+    // `ahead-behind` prints "N M" — ahead of base, behind base, in that order.
+    if (ab) {
+      const [a, b] = ab.trim().split(/\s+/).map((n) => parseInt(n, 10));
+      if (Number.isFinite(a)) row.ahead = a;
+      if (Number.isFinite(b)) row.behind = b;
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * The whole picture, or null if this is not a repo we can read.
+ *
+ * `truncated` is not decoration: a list silently cut at sixty reads as the
+ * whole repo, and the one question this report exists to answer is "how much is
+ * in here". Same rule the session diffstat's own `truncated` keeps.
+ */
+export function repoState(repoRoot, baseRef) {
+  const worktrees = readWorktrees(repoRoot);
+  const branches = readBranches(repoRoot, baseRef);
+  if (!worktrees && !branches) return null;
+  /**
+   * WHAT IS LISTENING IN THE CHECKOUT ITSELF.
+   *
+   * `listenersIn` has always taken any directory, and had only ever been asked
+   * about SESSION WORKTREES — so somebody running `npm run dev` in their normal
+   * checkout, which is what "just testing or playing around in dev" actually
+   * looks like, was invisible to every surface in the product. The measurement
+   * was there; nobody was pointing it at the repo.
+   *
+   * THE ATTRIBUTION RULE IS UNCHANGED, and it is the reason this widens to the
+   * repo root and no further: a port is attributed by the CWD OF THE PROCESS
+   * HOLDING THE SOCKET, so this reports servers running inside THIS PROJECT'S
+   * checkout and nothing else. Postgres on 5432 has its own cwd and does not
+   * appear here — which is the whole point, and why "just show every port on
+   * the box" is not what this does.
+   *
+   * Reported, not offered: this is a readout of what is up. Sharing one is a
+   * separate act with its own gates (see previewJobs).
+   */
+  const listening = listenersIn(repoRoot);
+  const wt = worktrees ?? [];
+  const br = branches ?? [];
+  return {
+    base: baseRef,
+    worktrees: wt.slice(0, MAX_WORKTREES),
+    worktreesTotal: wt.length,
+    // Newest first (for-each-ref already sorted), so a truncated list is the
+    // part somebody is actually working in.
+    branches: br.slice(0, MAX_BRANCHES),
+    branchesTotal: br.length,
+    sessionBranches: br.filter((b) => b.session).length,
+    listening,
+    // "Nothing is listening" and "this machine cannot look" (Windows, a failed
+    // scan) are the same empty array without this — and the second must never
+    // render as the first. Same field, same reason, as the session report.
+    listeningSupported: listenersSupported(),
+  };
+}

package/bin/lib/update.mjs

@@ -6,8 +6,27 @@
  * version ships. The server reports {latest, min} on every roster poll; the
  * daemon compares its own VERSION and, at a SAFE boundary (startup or idle —
  * never mid-task), self-updates + re-execs. Below `min` it updates regardless
- * (older protocol is known-broken); otherwise it honors AUTO_UPDATE. When it
- * can't install (npx cache, or auto off) it nags with the exact command.
+ * (older protocol is known-broken); otherwise it honors AUTO_UPDATE.
+ *
+ * NPX UPDATES TOO, SINCE 0.58.0 — and until then it never did, which is the
+ * whole reason this comment is longer than it was. `AUTO_UPDATE` is ON by
+ * default (`FLOWVIANT_NO_UPDATE !== '1'`), so the flag was never what held
+ * machines back: the npx branch was. It refused to install — correctly, since
+ * `npm i -g` lands where the running process will never look — and then only
+ * NAGGED A CONSOLE NOBODY READS. The README meanwhile told everyone to launch
+ * with `npx flowviant@latest` and promised that "a running daemon also
+ * self-updates", which was false for exactly the audience it was written for.
+ * The result, measured across one account's five machines on 2026-08-25:
+ * 0.48.3, 0.51.1, 0.51.2, 0.54.2 and 0.56.0, each frozen at whatever npx had
+ * cached the day it launched. The clincher was the 0.56.0 one — it polled that
+ * morning, saw LATEST 0.56.1, had AUTO_UPDATE on, and still did not move.
+ *
+ * The fix is that under npx the RE-EXEC IS THE UPDATE. There is nothing to
+ * install: relaunching through `npx -y flowviant@latest` makes npx resolve
+ * `latest` against the registry and fetch it (measured — it pulled 0.57.0 into
+ * a new cache entry beside the stale 0.54.2). So the npx path stops nagging and
+ * starts restarting itself, honouring AUTO_UPDATE and the same idle gate as the
+ * global path.
  */
 
 import { execFileSync, spawn } from 'node:child_process';
@@ -51,13 +70,22 @@ export function runningViaNpx() {
  * this process alive only as a thin proxy waiting on the child, so the user's
  * shell stays attached to one foreground process.
  */
-function reexec(teardown) {
+function reexec(teardown, { viaNpx = false, target = null } = {}) {
   try {
     teardown?.();
   } catch {
     /* best-effort */
   }
-  const child = spawn(process.execPath, process.argv.slice(1), {
+  // UNDER NPX THE RE-EXEC IS THE UPDATE, so it must not re-run our own argv[1]:
+  // that path points into the npx cache entry holding the version we are trying
+  // to leave, and re-running it would reload the stale copy forever. Going back
+  // through `npx -y flowviant@latest` is what makes npx resolve `latest` against
+  // the registry and fetch the new one. `-y` because a restart must never stop
+  // on npx's install prompt — the same rule FLOWVIANT_REEXEC keeps below.
+  const [cmd, args] = viaNpx
+    ? ['npx', ['-y', 'flowviant@latest', ...process.argv.slice(2)]]
+    : [process.execPath, process.argv.slice(1)];
+  const child = spawn(cmd, args, {
     stdio: 'inherit',
     // MARK THE CHILD AS A RESTART, not as a person typing `flowviant`.
     // stdio is inherited, so the child sees two TTYs and believes a human is
@@ -69,11 +97,35 @@ function reexec(teardown) {
     // is not a widening — the daemon serves exactly the credential it was
     // already serving one second ago, and the question gets asked the next
     // time a human starts it by hand.
-    env: { ...process.env, FLOWVIANT_REEXEC: '1' },
+    env: {
+      ...process.env,
+      FLOWVIANT_REEXEC: '1',
+      // WHAT WE RESTARTED IN ORDER TO BECOME. The successor compares its own
+      // VERSION against this: if it came back still short, the update did not
+      // take (a registry serving a stale `latest`, an npx cache that refused to
+      // move, a half-written global install) and it must NAG rather than
+      // restart again. Without this the npx path is a re-exec loop — and unlike
+      // the global path there is no install step whose failure would throw and
+      // stop it.
+      ...(target ? { FLOWVIANT_UPDATE_TARGET: target } : {}),
+    },
   });
   child.on('exit', (code) => process.exit(code ?? 0));
 }
 
+/**
+ * Did a restart that was supposed to land us on `target` fail to?
+ *
+ * True only when a PREVIOUS process handed us a target we are still below. A
+ * plain start has no marker, and a successful update is at or above it — so
+ * this is false in every case except the one it exists for.
+ */
+export function updateRestartFailed(target) {
+  const attempted = process.env.FLOWVIANT_UPDATE_TARGET;
+  if (!attempted) return false;
+  return cmpVersion(VERSION, attempted) < 0 && cmpVersion(target ?? attempted, attempted) <= 0;
+}
+
 /** Install @latest globally. Throws on failure (EACCES without sudo, offline…). */
 function installLatest() {
   execFileSync('npm', ['install', '-g', 'flowviant@latest'], { stdio: 'inherit' });
@@ -122,6 +174,42 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
   const npx = runningViaNpx();
   const wantInstall = belowMin || autoUpdate;
 
+  // A RESTART THAT DID NOT TAKE must not be tried again on the next poll. The
+  // global path is self-limiting (a failed `npm i -g` throws and lands in the
+  // 15-minute backoff), but the npx path has no install step to fail — it just
+  // relaunches, so a registry or cache that keeps serving the old version would
+  // loop this process forever, tearing down live turns every ten seconds.
+  if (updateRestartFailed(target)) {
+    if (naggedFor !== target) {
+      naggedFor = target;
+      warn(
+        `restarted to pick up ${target} but came back as ${cur} — staying put. Update by hand: ${
+          npx ? 'relaunch with `npx flowviant@latest`' : 'npm i -g flowviant@latest'
+        }.`
+      );
+    }
+    return false;
+  }
+
+  // UNDER NPX THERE IS NOTHING TO INSTALL — the relaunch IS the update, because
+  // `npx -y flowviant@latest` resolves `latest` against the registry. Same two
+  // gates as the global path: the operator's AUTO_UPDATE choice, and an idle
+  // machine, because a re-exec mid-turn SIGTERMs the tab's CLI. No npm-view
+  // probe here: npx is about to ask the registry itself, and the loop guard
+  // above is what a stale answer runs into.
+  if (wantInstall && npx) {
+    if (!safeToUpdate) {
+      if (naggedFor !== target) {
+        naggedFor = target;
+        note(`flowviant ${cur} → ${target} available — restarting once no turn is running.`);
+      }
+      return false;
+    }
+    note(`flowviant ${cur} → ${target}: restarting through npx to pick it up…`);
+    reexec(teardown, { viaNpx: true, target });
+    return true;
+  }
+
   if (wantInstall && !npx) {
     if (!safeToUpdate) {
       // Outdated but a turn is running — wait until the machine is quiet. Nag
@@ -167,7 +255,7 @@ export function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, tea
       note(`flowviant ${cur} → ${published}: self-updating…`);
       installLatest();
       ok('updated — restarting into the new version.');
-      reexec(teardown);
+      reexec(teardown, { target: published });
       return true;
     } catch (e) {
       lastInstallFailAt = Date.now();

package/bin/lib/work.mjs

@@ -51,6 +51,10 @@ import {
 } from './prompts.mjs';
 import { materializeInto, hasMaterialized, excludeInWorktree, scrub as envScrub } from './env.mjs';
 import { detectRuntimes, canRun, recordSkills, RUNTIMES } from './runtimes.mjs';
+
+/** The place id meaning "the checkout", not a worktree. Must match the
+ *  server's REPO_PLACE — it is a wire value, not a local convention. */
+const REPO_PLACE = 'repo';
 import { isTerminalSessionLive, isAgyConversationLive } from './localSessions.mjs';
 import { worktreeDiff } from './worktreeDiff.mjs';
 import { homedir } from 'node:os';
@@ -119,8 +123,22 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
    * while that session's turn has a live CLI in it.
    */
   const workChains = new Map(); // sessionId -> settled-safe tail promise
-  const chainFor = (sessionId, fn) => {
-    const prev = workChains.get(sessionId) ?? Promise.resolve();
+  /**
+   * Serialize work by PLACE — the directory — not by session.
+   *
+   * It was keyed by session id, which was the same thing right up until a place
+   * could be shared: two sessions pointed at one worktree had independent
+   * chains, so their turns would run at the same time in the same directory and
+   * edit each other's files mid-edit. Keying on the place is what makes "two
+   * tabs in one repo" behave the way two terminal tabs in one repo behave —
+   * they take turns.
+   *
+   * The cross-PROCESS half was already right and needed no change: the turn
+   * lock is a file inside the worktree (`flowviant-turn.lock`), so two sessions
+   * sharing a place already share the lock by construction.
+   */
+  const chainFor = (placeId, fn) => {
+    const prev = workChains.get(placeId) ?? Promise.resolve();
     // `.then(fn, fn)`, like withWikiLock: one rejected link must never wedge
     // every later turn of the tab.
     const run = prev.then(fn, fn);
@@ -128,11 +146,11 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
       () => {},
       () => {}
     );
-    workChains.set(sessionId, stored);
+    workChains.set(placeId, stored);
     // Release the entry when the chain drains, so the map cannot grow for the
     // process lifetime and `workChains.has()` means "busy right now".
     stored.then(() => {
-      if (workChains.get(sessionId) === stored) workChains.delete(sessionId);
+      if (workChains.get(placeId) === stored) workChains.delete(placeId);
     });
     return run;
   };
@@ -1159,8 +1177,34 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
    * is the point. If the directory was retired but the branch survives, the
    * worktree re-attaches to the branch and the committed work is still there.
    */
-  const sessionWtFor = (sessionId, baseAt) => {
-    if (!isSafePathSegment(sessionId)) return null;
+  /**
+   * WHERE A SESSION WORKS — its PLACE, which is a directory on a branch.
+   *
+   * A session used to BE a worktree: one tab, one directory, cut at birth and
+   * retired at close. That binding was never an isolation guarantee — a turn
+   * runs with permissions skipped, so the worktree is a starting directory and
+   * not a fence, and any agent could always `cd` into another one. The product
+   * was asserting an invariant it did not have.
+   *
+   * So a session now REFERENCES a place rather than being one. Many sessions
+   * may name the same place; a session may name the repo checkout itself; and
+   * `session/<own-id>` is simply the DEFAULT place, cut fresh at first turn,
+   * which is why an absent `place` behaves exactly as every existing tab does.
+   *
+   * `'repo'` IS NOT A DIRECTORY NAME AND MUST NOT BECOME ONE. It resolves to
+   * the checkout the daemon already serves — never created, never retired,
+   * because it is not ours to remove. The value reaching here is a server-side
+   * enum, never a browser-supplied path: `sessions.routes.ts` resolves it the
+   * same way adoption resolves a cwd, and for the same reason.
+   */
+  const placeWtFor = (placeId, baseAt) => {
+    if (placeId === REPO_PLACE) {
+      // The checkout. `fresh: false` on purpose — nothing was opened, so no
+      // caller may treat this as a newly-cut branch.
+      return { wt: repoRoot, fresh: false };
+    }
+    if (!isSafePathSegment(placeId)) return null;
+    const sessionId = placeId;
     const wt = join(baseDir, 'sessions', sessionId);
     const fresh = !existsSync(wt);
     if (fresh) {
@@ -1538,6 +1582,10 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     }
   };
 
+  /** The pre-places name, kept so every existing caller reads unchanged: a
+   *  session's own id IS its default place. */
+  const sessionWtFor = (sessionId, baseAt) => placeWtFor(sessionId, baseAt);
+
   const retireWorkSessions = (activeIds, heldElsewhere) => {
     if (!Array.isArray(activeIds)) return;
     // Sessions ANOTHER daemon on this credential is serving. They are absent
@@ -1596,7 +1644,10 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
       // run it again while the report is merely undelivered.
       if (pendingWorkReports.has(job.id)) continue;
       workAnswering.add(job.id);
-      chainFor(job.sessionId, async () => {
+      // Serialized by PLACE: two tabs sharing a worktree take turns in it
+      // rather than editing the same files at the same time.
+      const place = job.place || job.sessionId;
+      chainFor(place, async () => {
         try {
           const tries = workAttempts.get(job.id) ?? 0;
           if (tries >= MAX_WORK_TRIES) {
@@ -1711,7 +1762,10 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
           }
           // Based at the SOURCE's HEAD when adopting — the resumed
           // conversation was had against those commits, not the project base.
-          const dir = sessionWtFor(job.sessionId, adopting ? srcHead : undefined);
+          // The PLACE this tab works in — its own worktree unless the server
+          // named another. An older server sends no `place` and the default is
+          // the session's own id, which is what every tab has always done.
+          const dir = placeWtFor(place, adopting ? srcHead : undefined);
           if (!dir) {
             await settleWorkTurn(job.id, {
               ok: false,
@@ -2193,8 +2247,53 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
             return;
           }
           note(`${c.cyan('ship')} ${c.dim(`— "${job.sessionName || job.sessionId}"`)}`);
-          const branch = `session/${job.sessionId}`;
+          /**
+           * WHAT IS ACTUALLY CHECKED OUT — not what we named it at birth.
+           *
+           * Ship used to compute `session/<id>` and then REFUSE if HEAD had
+           * moved: "ask it to return to its session branch, then ship again".
+           * That refusal is the thing this product says it never does — it had
+           * no reason of its own beyond bookkeeping, and in a terminal
+           * `git checkout -b` breaks nothing, which is the whole standard this
+           * surface is held to.
+           *
+           * The bug it was written for was real and is fixed properly here
+           * rather than frozen out: ship once merged the branch NAME while
+           * logging HEAD, so receipts named commits that never landed on main.
+           * That was TWO SOURCES OF TRUTH, not branch switching. There is one
+           * now, and it is the worktree's own HEAD.
+           *
+           * Resolved BEFORE the idempotency check below, and that ordering is
+           * load-bearing: `session/<id>` can still exist, stale and already an
+           * ancestor of base, while the real work sits on the branch that was
+           * checked out afterwards. Asking the old name first would answer
+           * "already merged — nothing new to ship" over unshipped commits.
+           *
+           * A directory that is gone (a retired or closed tab) cannot be asked,
+           * so the recorded name is the fallback — the one case where the name
+           * is the only thing there is.
+           */
           const wt = join(baseDir, 'sessions', job.sessionId);
+          let branch = `session/${job.sessionId}`;
+          let detached = false;
+          if (existsSync(wt)) {
+            try {
+              branch = git(['symbolic-ref', '--short', 'HEAD'], wt);
+            } catch {
+              detached = true;
+            }
+          }
+          // THE ONE REFUSAL LEFT, and it is not policy. A detached HEAD names
+          // no branch, so there is nothing to merge and nothing to record —
+          // that is an ambiguity in git, not a rule of ours.
+          if (detached) {
+            await done({
+              ok: false,
+              error:
+                'this session is on a detached HEAD — no branch to ship. Ask it to check out a branch, then ship again',
+            });
+            return;
+          }
           let branchExists = true;
           try {
             git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repoRoot);
@@ -2388,23 +2487,11 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
             });
             return;
           }
-          // What is checked out here must BE the session branch. Sessions may
-          // create branches when asked — but then "ship" is ambiguous, and
-          // folding+logging HEAD while merging the stale branch NAME once
-          // shipped receipts for commits that never landed on main.
-          let head = null;
-          try {
-            head = git(['symbolic-ref', '--short', 'HEAD'], dir.wt);
-          } catch {
-            /* detached */
-          }
-          if (head !== branch) {
-            await done({
-              ok: false,
-              error: `the session is on ${head ? `branch '${head}'` : 'a detached HEAD'}, not its own '${branch}' — ask it to return to its session branch, then ship again`,
-            });
-            return;
-          }
+          // NO "return to your session branch" GUARD. `branch` was read from
+          // this worktree's HEAD above, so the fold, the tip and the receipts
+          // below all name the same thing by construction — which is what the
+          // old guard was really protecting, and it protected it by refusing
+          // instead of by measuring.
           // Fold main into the branch FIRST: conflicts land here, in the
           // session's own worktree, where the next turn can resolve them.
           try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flowviant",
-  "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.",
+  "version": "0.59.0",
+  "description": "Run your own coding CLIs as build agents for Flowviant — 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": {
     "flowviant": "bin/cli.mjs"