flowviant 0.103.0 → 0.104.0

package/bin/lib/workRetire.mjs

@@ -0,0 +1,185 @@
+/**
+ * THE MANAGER'S DISK HYGIENE — which session directories this daemon holds,
+ * retiring the worktrees of closed tabs (and stopping a stopped agent's CLI
+ * there), and fast-forwarding each person's clean manual place.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). All three read the
+ * `sessions/` directory the poll hands back and act only on what the roster
+ * says is no longer live or is safely behind; none of them runs a turn or
+ * reports a measurement.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { git, isSafePathSegment } from './git.mjs';
+
+export function createWorkRetire({
+  repoRoot,
+  baseDir,
+  baseRef,
+  placeOf,
+  placeLocks,
+  shipping,
+  workTokens,
+  agentChildren,
+  sweepMergedSessionBranch,
+}) {
+  /**
+   * Retire the worktrees of sessions the server says are CLOSED.
+   *
+   * `activeWorkSessions` on the roster is the list of this fleet's LIVE
+   * sessions; a directory whose id is absent belongs to a tab its owner
+   * closed, and the directory — never the branch: committed work survives on
+   * `session/<id>`, and ship re-attaches to it — is returned to disk. NEVER
+   * by count: the old cap-12 retirement destroyed live sessions on shared
+   * machines. When the roster omits the field entirely (older server),
+   * absence of signal is not a close — retire nothing.
+   */
+  /** Every session this daemon currently has a worktree for — what renews our
+   *  lease on the poll. Read off the directory rather than a map, so it is the
+   *  same fact retirement acts on. */
+  const heldSessionIds = () => {
+    const dir = join(baseDir, 'sessions');
+    try {
+      return readdirSync(dir).filter(isSafePathSegment).slice(0, 50);
+    } catch {
+      return [];
+    }
+  };
+
+  const retireWorkSessions = (activeIds, heldElsewhere) => {
+    if (!Array.isArray(activeIds)) return;
+    // Sessions ANOTHER daemon on this credential is serving. They are absent
+    // from activeWorkSessions for us and present for them, and removing their
+    // worktree would pull the directory out from under a running turn. Absence
+    // means "the tab closed"; this is the one other thing it can mean.
+    const peers = new Set(Array.isArray(heldElsewhere) ? heldElsewhere : []);
+    // A peer-held session's CACHED work token is a claim-bypass: the mint is
+    // the one place the session lease 409s a non-holder, and a token younger
+    // than ~23h skips the mint entirely — so a daemon that lost a lease would
+    // run the next turn anyway, editing the worktree while every MCP call
+    // 401s (the peer's mint rotated the secret). Dropping the cache forces
+    // the next turn through the mint, where the 409 stands it down.
+    for (const id of peers) workTokens.delete(id);
+    const dir = join(baseDir, 'sessions');
+    if (!existsSync(dir)) return;
+    let ids;
+    try {
+      ids = readdirSync(dir);
+    } catch {
+      return;
+    }
+    const live = new Set(activeIds);
+    let removed = 0;
+    for (const id of ids) {
+      if (live.has(id)) continue;
+      if (peers.has(id)) continue; // another daemon's tab — not ours to retire
+      /**
+       * A HARD STOP REACHES THE CLI HERE, and this is the whole of it.
+       *
+       * `stopAgent` marked the agent abandoned in D1 and nothing on the wire
+       * told the machine, so the CLI went on working, editing the worktree and
+       * spending the operator's quota — while the confirm dialog said the agent
+       * was stopped. It also never got cleaned up, because the check below
+       * skips any place whose lock is held and a running turn holds it: a
+       * stopped agent mid-turn kept its directory forever.
+       *
+       * No new wire field and no version floor: an abandoned agent simply drops
+       * out of `activeWorkSessions` (that list is built from LIVE statuses), so
+       * the server ALREADY says everything needed. Absence means "nothing here
+       * is live any more", and the honest response to that is to stop what we
+       * are running in it and then take the directory.
+       *
+       * SIGTERM the CHILD, never its group — the rule teardown keeps, so an
+       * unattended sweep cannot take the driver's dev server with it. The lock
+       * is released when the child exits, so the removal happens on the next
+       * pass rather than this one.
+       */
+      const running = agentChildren.get(id);
+      if (running) {
+        try {
+          running.kill('SIGTERM');
+        } catch {
+          /* already gone */
+        }
+        agentChildren.delete(id);
+      }
+      // Asked of the PLACE, not the session: the lock is keyed by directory,
+      // and a session sharing one with a busy peer is not ours to retire
+      // either — its worktree is the peer's working directory.
+      if (placeLocks.has(placeOf(id)) || shipping.has(id)) continue; // still draining here
+      const wt = join(dir, id);
+      try {
+        // Uncommitted work is the human's — a resource sweep does not outrank
+        // it, closed tab or not. (The non-force remove would refuse anyway;
+        // the explicit check keeps the intent legible.)
+        if (git(['status', '--porcelain'], wt) !== '') continue;
+        git(['worktree', 'remove', wt], repoRoot); // non-force
+        workTokens.delete(id);
+        removed++;
+        // NOW the branch can be judged. While this worktree existed the branch
+        // was checked out in it, so `git branch -d` refused on every earlier
+        // attempt — a tab that shipped and then closed would otherwise leave
+        // its merged branch behind forever, which is the common case.
+        // Unshipped work still refuses here: `-d` is what decides.
+        sweepMergedSessionBranch(id);
+      } catch {
+        /* not cleanly removable — leave it */
+      }
+    }
+    if (removed) {
+      try {
+        git(['worktree', 'prune'], repoRoot);
+      } catch {
+        /* best effort */
+      }
+    }
+  };
+
+  /**
+   * KEEP EACH PERSON'S MANUAL WORKTREE FRESH.
+   *
+   * Every teammate's Workbench tabs share one directory of their own on a
+   * branch of their own — which is not a preference, it is what git allows:
+   * two worktrees cannot have the same branch checked out, so "everyone works
+   * on main" is only true for the machine's OPERATOR, whose place is the
+   * checkout itself. Everyone else needs a branch, and a branch left alone
+   * drifts behind main until the first thing they do in a new tab is a merge
+   * they did not ask for.
+   *
+   * FAST-FORWARD ONLY, and that is the whole safety argument. If their branch
+   * has no commits of its own it simply catches up, which is the ordinary case
+   * and the one worth automating. The moment it HAS diverged, this stops and
+   * leaves it exactly as it is: their commits are theirs, a rebase would
+   * rewrite them under somebody who is not looking, and a merge would put a
+   * commit in their history that they did not make. Their own Claude can fold
+   * base in whenever they ask it to.
+   *
+   * Guarded three ways: a DIRTY tree is left alone (uncommitted work outranks
+   * freshness), a place with a live lock is skipped (a turn is standing in it),
+   * and the whole thing is silent — nothing here reports, warns or blocks.
+   */
+  const freshenManualPlaces = () => {
+    let dir;
+    try {
+      dir = readdirSync(join(baseDir, 'sessions'));
+    } catch {
+      return; // no worktrees yet
+    }
+    for (const place of dir) {
+      // Only a PERSON's manual place. An agent's own worktree (`a-<id>`) is
+      // deliberately not touched: its branch is the reviewable unit, and
+      // moving it under a review would change what somebody is deciding about.
+      if (!place.startsWith('u-') || !isSafePathSegment(place)) continue;
+      if (placeLocks.has(place)) continue;
+      const wt = join(baseDir, 'sessions', place);
+      try {
+        if (git(['status', '--porcelain'], wt).trim() !== '') continue;
+        git(['merge', '--ff-only', baseRef()], wt);
+      } catch {
+        /* diverged, or something else is going on in there. Leave it. */
+      }
+    }
+  };
+
+  return { heldSessionIds, retireWorkSessions, freshenManualPlaces };
+}

package/bin/lib/workSessionGroups.mjs

@@ -0,0 +1,166 @@
+/**
+ * WHICH PROCESS GROUPS EACH TAB HAS STARTED — kept, persisted per repo and
+ * boot, and pruned against the kernel on every read.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). It changes for one reason —
+ * how a watcher that outlives its turn stays attributed to its tab — and has
+ * three writers (the session lane and the agent lane note a group at spawn,
+ * the sweep prunes closed ids) and two readers (the worktree report's
+ * `processes`, and the kill lane's check in workProcesses.mjs, which is handed
+ * `sessionGroups` itself). groupRegistry.test.mjs drives it through the
+ * manager against a real registry file.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { measureProcesses, liveGroups, processesSupported } from './processes.mjs';
+import { bootMark, mutateRegistry, readRegistry, sameBoot } from './procRegistry.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+
+export function createWorkSessionGroups({ repoRoot }) {
+  /**
+   * WHICH PROCESS GROUPS EACH TAB HAS STARTED.
+   *
+   * A turn's CLI is spawned `detached`, so its pid is a process-group id and
+   * everything the agent starts inherits it — through `nohup` and `setsid`,
+   * which is precisely where attribution by ppid falls apart. Kept per SESSION
+   * and not per turn: the point of the feature is the watcher that outlives the
+   * turn that started it.
+   *
+   * PRUNED ON EVERY READ against the kernel, which is not housekeeping. A pgid
+   * is a pid and pids are recycled, so an un-pruned set would eventually
+   * attribute a stranger's process to a tab that has been closed for a week.
+   */
+  const sessionGroups = new Map(); // sessionId -> Set<pgid>
+
+  /**
+   * …AND IT SURVIVES A RESTART, which it did not until 2026-08-27.
+   *
+   * This map used to live only in this closure. The processes it tracks
+   * OUTLIVE the daemon on purpose — `shutdownWork` SIGTERMs the CLI child and
+   * never the group, precisely so an unattended auto-update does not kill the
+   * driver's dev server — so every daemon restart left a live watcher running
+   * with nothing left that knew whose it was. The tab reported `[]`, the web
+   * read that as "looked, found none", and the Running section went dark until
+   * some later turn happened to open a new group.
+   *
+   * That is not a small bug: AUTO_UPDATE is on by default, so it fired on every
+   * release, on every machine. And it broke the three-state rule this file
+   * states in its own header — the honest answer after a restart was "we have
+   * forgotten", and `[]` is not that. Persisting is what makes `[]` true again,
+   * which is why the fix is a disk write and not a fourth state.
+   *
+   * `procRegistry` is the right home and was sitting unused: it was built for
+   * exactly this ("the daemon spawns things that outlive it… the successor has
+   * to find them"), was orphaned when the dev-run system was deleted, and
+   * already does the atomic write, the stale-lock recovery, the entry cap and
+   * the dead-pid TTL. Its prune is deliberately LOOSE here — it keeps an entry
+   * whose leader is gone, because the leader is the CLI and it exits at the end
+   * of every turn while the watcher it started keeps running. `liveGroups` is
+   * the real prune, on every read, against the kernel.
+   */
+  /*
+   * THREE RULES THE FIRST CUT BROKE (2026-09-24), each a way the file named a
+   * group that was not this tab's, or forgot one that was:
+   *
+   *  - ONE FILE PER REPO, not per OS user. Each daemon rewrote the shared file
+   *    with only its own groups, so two daemons on one box (project A in one
+   *    checkout, B in another) erased each other's entries and A's watcher
+   *    was forgotten at A's next restart. The instance lock already makes a
+   *    repo one daemon, so the repo is the right owner. The pre-2026-09-24
+   *    shared file is not read: its entries carry no boot, so no rule below
+   *    could believe them anyway.
+   *  - AN ENTRY IS BELIEVED ONLY IN THE BOOT THAT WROTE IT. After a reboot the
+   *    remembered pgid belongs to whatever the kernel handed it to next — the
+   *    operator's shell, another project's children — and the Running list
+   *    relayed that group's command lines as this tab's and `killTargetOk`
+   *    accepted a Stop on them.
+   *  - ONLY LIVE GROUPS ARE WRITTEN, each with the time it was FIRST seen.
+   *    Every persist used to restamp every entry with `Date.now()`, so the
+   *    registry's 7-day TTL never applied to anything, and dead entries (one per
+   *    agent turn, recorded under a key nothing read) filled the 32-entry cap
+   *    and pushed a tab's live watcher off the end.
+   */
+  const GROUPS_DIR = join(homedir(), '.flowviant');
+  const GROUPS_KEY = createHash('sha256').update(String(repoRoot)).digest('hex').slice(0, 16);
+  const GROUPS_FILE = join(GROUPS_DIR, `session-groups-${GROUPS_KEY}.json`);
+  const GROUPS_LOCK = join(GROUPS_DIR, `session-groups-${GROUPS_KEY}.lock`);
+  const groupFirstSeen = new Map(); // pgid -> ms first recorded
+  const BOOT = bootMark();
+
+  const persistGroups = () => {
+    const flat = [];
+    for (const [sid, set] of sessionGroups) {
+      for (const pgid of liveGroups(set)) {
+        if (!groupFirstSeen.has(pgid)) groupFirstSeen.set(pgid, Date.now());
+        flat.push({ sessionId: sid, pid: pgid, startedAt: groupFirstSeen.get(pgid), boot: BOOT });
+      }
+    }
+    const kept = new Set(flat.map((e) => e.pid));
+    for (const g of groupFirstSeen.keys()) if (!kept.has(g)) groupFirstSeen.delete(g);
+    try {
+      mutateRegistry(GROUPS_DIR, GROUPS_FILE, GROUPS_LOCK, () => flat);
+    } catch {
+      /* best-effort: losing the file costs a restart's visibility, never a turn */
+    }
+  };
+
+  try {
+    for (const e of readRegistry(GROUPS_FILE)) {
+      if (!e?.sessionId || !Number.isInteger(e?.pid)) continue;
+      if (!sameBoot(e.boot, BOOT)) continue; // another boot's pgid names a stranger now
+      const set = sessionGroups.get(e.sessionId) ?? new Set();
+      set.add(e.pid);
+      sessionGroups.set(e.sessionId, set);
+      if (Number(e.startedAt) > 0) groupFirstSeen.set(e.pid, Number(e.startedAt));
+    }
+  } catch {
+    /* no registry yet — the ordinary first run */
+  }
+
+  /** Forget the groups of every id the roster no longer names — a closed tab,
+   *  a finished agent. Nothing reports or stops a group for an id that is not
+   *  live, so holding it only grows the map for the life of the process. */
+  const pruneSessionGroups = (activeIds) => {
+    const live = new Set(activeIds);
+    let changed = false;
+    for (const id of [...sessionGroups.keys()]) {
+      if (live.has(id)) continue;
+      sessionGroups.delete(id);
+      changed = true;
+    }
+    if (changed) persistGroups();
+  };
+
+  const noteSessionGroup = (sessionId, pgid) => {
+    if (!sessionId || !pgid) return;
+    const set = sessionGroups.get(sessionId) ?? new Set();
+    if (set.has(pgid)) return;
+    set.add(pgid);
+    sessionGroups.set(sessionId, set);
+    persistGroups();
+  };
+
+  /** This tab's live processes, or null where the machine cannot look. */
+  const sessionProcesses = (sessionId) => {
+    if (!processesSupported()) return null;
+    const known = sessionGroups.get(sessionId);
+    // The SHAPE `measureProcesses` returns — a bare `[]` here has no `.rows`,
+    // so the report's `processes` key came out undefined and was dropped from
+    // the JSON: "looked and found none" arrived as "never looked".
+    if (!known || known.size === 0) return { rows: [], total: 0 };
+    const alive = liveGroups(known);
+    // Only touch the disk when the set actually MOVED. This runs on every
+    // sweep, for every live tab, forever; an unconditional write would be a
+    // file rewrite a minute for the life of the daemon to restate what is
+    // already there — the same reasoning the auto-name relay uses for its
+    // unchanged-title check.
+    const changed = alive.size !== known.size;
+    if (alive.size === 0) sessionGroups.delete(sessionId);
+    else sessionGroups.set(sessionId, alive);
+    if (changed) persistGroups();
+    return measureProcesses(alive, { scrub: envScrub });
+  };
+
+  return { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses };
+}

package/bin/lib/workSessionRuntime.mjs

@@ -0,0 +1,164 @@
+/**
+ * WHICH CLI A TAB SPEAKS, AND WHICH CONVERSATION IT RESUMES — the runtime pin
+ * and the shapes a resume id must have before it rides argv.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). The pin and the id guards
+ * change together (a new CLI brings both), and none of it is about running a
+ * turn: the session lane asks `sessionRuntime` before it spawns. The two id
+ * guards are pure and module-level: both turn lanes import them, so the
+ * manager never carries a constant between lanes.
+ */
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { canRun, RUNTIMES } from './runtimes.mjs';
+import { detectRuntimes } from './runtimeDetection.mjs';
+
+/**
+ * The shape a codex thread id must have before it is written to disk or —
+ * decisive — pushed into argv as `resume <id>`. Conservative on purpose:
+ * alphanumeric plus dash/underscore, never a leading dash (an argv that
+ * parses as a flag), never whitespace. Anything else is dropped and the
+ * session simply runs fresh in its own worktree.
+ */
+export const CODEX_THREAD_RE = /^[0-9a-zA-Z][0-9a-zA-Z_-]{7,63}$/;
+
+/** agy conversation ids are plain UUIDs (the db filename IS the identity —
+ *  measured: a renamed copy fails "trajectory not found"). Guarded the same
+ *  way as the codex id: it rides in argv as `--conversation <id>`. */
+export const AGY_CONV_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function createWorkSessionRuntime({ sessionMetaPath }) {
+  /**
+   * WHICH CLI drives this session — picked ONCE, on the first turn, and pinned
+   * in the worktree's meta dir. The held context belongs to the CLI that made
+   * it: `--continue` under a different binary is a different brain wearing the
+   * session's half-finished state (the dispatch path pins heldRuntime for the
+   * same reason). If the pinned CLI has left the machine, the turn settles
+   * honestly instead of substituting. A retired-and-reattached directory has
+   * no marker and no held context either, so re-picking there is correct.
+   *
+   * THE SERVER'S WORD COMES FIRST. A tab is created AS a runtime's tab
+   * (`job.runtime`; null/absent = Claude, which is what every tab ran on until
+   * now), so on the first turn a named runtime IS the pick — never a
+   * preference the machine may override. And a named runtime that DISAGREES
+   * with an existing pin is an identity change mid-life: something upstream
+   * now calls this tab a different brain's, and the only honest move is to
+   * settle the turn and say so ({ mismatch }), because a held context must
+   * never be answered by a different brain.
+   *
+   * Returns { id } | { id: null } (nothing installed) | { missing: label } |
+   * { unsupported: label } (a runtime no session can run on) |
+   * { mismatch: { pin, runtime } } (labels, for the caller's sentence).
+   *
+   * SESSION-CAPABLE means rt.mcp is truthy — the session tools ride a real
+   * per-invocation MCP config — OR the runtime runs tabs PLAIN (Antigravity):
+   * no MCP at all, no cards, no streaming; the final answer is delivered by
+   * the daemon's own report and ship-time reconciliation keeps the ledger
+   * whole. `pickRuntimeFor('build')` is still the WRONG question here — it
+   * says yes to the mediated DISPATCH path without saying how a tab would
+   * speak, and a session pinned by it once threw in mcpFor on every turn.
+   */
+  const sessionCapable = (rid) =>
+    (Boolean(RUNTIMES[rid]?.mcp) || rid === 'antigravity') && canRun(RUNTIMES[rid], 'build');
+  const sessionRuntime = (wt, jobRuntime, sessionId) => {
+    // SCOPED: two tabs standing in one directory may run different CLIs, and an
+    // unscoped pin would hand the second one the first one's runtime.
+    const marker = sessionMetaPath(wt, 'flowviant-runtime', sessionId);
+    let pinned = null;
+    if (marker && existsSync(marker)) {
+      try {
+        pinned = readFileSync(marker, 'utf8').trim() || null;
+      } catch {
+        /* unreadable marker — re-pin below */
+      }
+    }
+    if (pinned && RUNTIMES[pinned]) {
+      if (jobRuntime && jobRuntime !== pinned) {
+        return {
+          mismatch: {
+            pin: RUNTIMES[pinned].label || pinned,
+            runtime: RUNTIMES[jobRuntime]?.label || jobRuntime,
+          },
+        };
+      }
+      // A pin that names a non-session-capable runtime is settled honestly by
+      // the caller, not silently re-picked: re-picking would hand the held
+      // context to a different brain, which is the exact substitution the pin
+      // exists to prevent.
+      if (!sessionCapable(pinned)) return { unsupported: RUNTIMES[pinned].label || pinned };
+      const installed = detectRuntimes().find((r) => r.id === pinned)?.installed;
+      return installed ? { id: pinned } : { missing: RUNTIMES[pinned].label || pinned };
+    }
+    // First turn, and the server named the brain: that IS the pick, gated the
+    // same two ways as a pin — not session-capable and not installed both
+    // settle honestly via the caller's existing paths, never substituted.
+    if (jobRuntime) {
+      if (!sessionCapable(jobRuntime))
+        return { unsupported: RUNTIMES[jobRuntime]?.label || jobRuntime };
+      const installed = detectRuntimes().find((r) => r.id === jobRuntime)?.installed;
+      if (!installed) return { missing: RUNTIMES[jobRuntime]?.label || jobRuntime };
+      if (marker) {
+        try {
+          writeFileSync(marker, jobRuntime);
+        } catch {
+          /* best-effort — an unpinnable session just re-picks next turn */
+        }
+      }
+      return { id: jobRuntime };
+    }
+    // The fresh pick — Claude first when it qualifies, for the reason
+    // pickRuntimeFor gives: the prompts were tuned against it. DELIBERATELY
+    // NARROWER than sessionCapable: a PLAIN tab (Antigravity — no cards, no
+    // streaming) is a degraded mode someone CHOOSES, so it is honored only
+    // when the server names it, never handed out as a default.
+    const rows = detectRuntimes();
+    const okFor = (rid) =>
+      Boolean(RUNTIMES[rid]?.mcp) &&
+      sessionCapable(rid) &&
+      Boolean(rows.find((r) => r.id === rid)?.installed);
+    const id = okFor('claude') ? 'claude' : (Object.keys(RUNTIMES).find(okFor) ?? null);
+    if (!id) return { id: null };
+    if (marker) {
+      try {
+        writeFileSync(marker, id);
+      } catch {
+        /* best-effort — an unpinnable session just re-picks next turn */
+      }
+    }
+    return { id };
+  };
+
+  /** agy's own cwd registry — {cwd → the conversation that ran there LAST}.
+   *  Read once, right after a fresh agy turn, to learn the id the turn just
+   *  created; from then on the tab's marker is the identity and this registry
+   *  is never consulted again (a dispatch sharing the machine may overwrite
+   *  the cwd's entry between turns). */
+  const agyRegistryLookup = (cwd) => {
+    try {
+      const raw = readFileSync(
+        join(homedir(), '.gemini', 'antigravity-cli', 'cache', 'last_conversations.json'),
+        'utf8'
+      );
+      const map = JSON.parse(raw);
+      if (!map || typeof map !== 'object') return null;
+      // agy keys by the cwd as IT resolved it — try our literal path and its
+      // realpath, so a symlinked home doesn't orphan the lookup.
+      let keys = [cwd];
+      try {
+        keys.push(realpathSync(cwd));
+      } catch {
+        /* the literal alone, then */
+      }
+      for (const k of keys) {
+        const id = map[k];
+        if (typeof id === 'string' && AGY_CONV_RE.test(id)) return id;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  };
+
+  return { sessionRuntime, agyRegistryLookup };
+}

package/bin/lib/workSessionTokens.mjs

@@ -0,0 +1,68 @@
+/**
+ * THE WORK CREDENTIAL, ONE PER SESSION — minted, cached near its lease, and
+ * the mint's three answers (a token, gone, held by another daemon).
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). The session lane mints; the
+ * retirement sweep drops a peer-held session's cache so the next turn goes
+ * back through the mint (the one place the lease 409s a non-holder). Both hold
+ * the same map, handed out by name.
+ */
+import {
+  FLEET_URL,
+  FLEET_TOKEN,
+  USER_AGENT,
+  REFRESH_BEFORE_SECONDS,
+  DAEMON_INSTANCE,
+} from './config.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+
+export function createWorkSessionTokens({ getLeaseTtl }) {
+  const WORK_TOKEN_URL = fleetEndpoint('work-token', FLEET_URL);
+  /**
+   * The work credential, ONE PER SESSION. The server binds each minted token
+   * to the sessionId in the mint body and the MCP layer refuses it for any
+   * other session, so a process-wide token would fail every tab but the one
+   * that minted it. Cached per session, re-minted near expiry (the endpoint
+   * rotates on every mint; per-session chaining means no turn is in flight
+   * for the session when its next turn mints). 404 means the server no longer
+   * holds that session for this fleet — a fact for the turn to settle with,
+   * not a retry.
+   */
+  const workTokens = new Map(); // sessionId -> { token, mintedAt }
+  const mintWorkToken = async (sessionId, force = false) => {
+    const cached = workTokens.get(sessionId);
+    const freshEnoughS = getLeaseTtl() - REFRESH_BEFORE_SECONDS;
+    if (cached && !force && (Date.now() - cached.mintedAt) / 1000 < freshEnoughS)
+      return { token: cached.token };
+    try {
+      const res = await fetch(WORK_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        // The instance is what CLAIMS the session lease server-side. Two
+        // daemons share one fleet credential, so the token cannot say which of
+        // us is serving this tab — and the mint is the moment that matters:
+        // there is one work-token row per session and minting ROTATES it, so a
+        // second mint revokes the first daemon's live secret mid-turn.
+        body: JSON.stringify({ sessionId, instance: DAEMON_INSTANCE }),
+      });
+      if (res.status === 404) return { gone: true };
+      // 409 — another daemon on this credential holds the session. Not ours to
+      // serve and not a retry: stand down and let the holder answer.
+      if (res.status === 409) return { heldElsewhere: true };
+      if (!res.ok) return null;
+      const token = (await res.json().catch(() => null))?.data?.token ?? null;
+      if (!token) return null;
+      workTokens.set(sessionId, { token, mintedAt: Date.now() });
+      return { token };
+    } catch {
+      return null;
+    }
+  };
+
+  return { workTokens, mintWorkToken };
+}