flowviant 0.34.2 → 0.36.0

package/bin/lib/claude.mjs

@@ -89,8 +89,18 @@ export const RESUME =
   'Resume. First call get_blocker_resolution for any blocker you reported; if resolved, ' +
   'apply the human’s answer and continue. Otherwise keep picking up and completing ' +
   'the tasks you were @mentioned on, per your instructions.';
-export const SINGLE_KICKOFF =
-  'Pick up and complete exactly ONE Flowviant task per your instructions, then stop.';
+// `intentId` is the task the SERVER says this lane is next in line for. Naming
+// it matters beyond saving a lookup: the daemon has already spawned this Claude
+// with that task's --model and --effort, and those cannot change once the
+// process exists. Left to pick freely, a lane could claim a sibling task and
+// run it under settings its owner chose for something else. Omitted (older
+// server, or nothing waiting) it falls back to the original free pick.
+export const SINGLE_KICKOFF = (intentId) =>
+  intentId
+    ? `Pick up Flowviant task ${intentId} — call claim_next_intent with intentId "${intentId}" — ` +
+      'complete exactly that ONE task per your instructions, then stop. If that ' +
+      'claim comes back unavailable, claim whatever is next for you instead.'
+    : 'Pick up and complete exactly ONE Flowviant task per your instructions, then stop.';
 export const SINGLE_RESUME =
   'Resume your current task. Call get_blocker_resolution for the blocker you reported; ' +
   'if resolved, apply the human’s answer and finish this one intent, then stop.';
@@ -590,7 +600,7 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText }) {
 // returned string for sentinel detection, and each activity is handed to
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
-export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn, streamJson, onActivity, wikiPerm, readOnly }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn, streamJson, onActivity, wikiPerm, readOnly, model, effort }) {
   return new Promise((resolve) => {
     const args = [];
     if (resume) args.push('--continue');
@@ -599,17 +609,29 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn
     if (mcpConfig) args.push('--mcp-config', mcpConfig);
     // Pin the model — never inherit the user's global default (which may be a
     // 1M/long-context tier their subscription can't bill autonomous work on).
-    args.push('--model', MODEL);
+    // A per-task override (chosen in the app, validated server-side against a
+    // fixed list before it ever reaches this argv) wins over the machine pin;
+    // absent, the pin stands. Effort has no machine-level pin at all: unset
+    // means Claude Code's own default, which is the honest resting state.
+    args.push('--model', model || MODEL);
+    if (effort) args.push('--effort', effort);
     if (streamJson) args.push('--output-format', 'stream-json', '--verbose');
     // readOnly wins over wikiPerm: a consult must never inherit write tools.
     args.push(...(readOnly ? CONSULT_PERM : wikiPerm ? WIKI_PERM : PERM));
-    // Force the user's Claude Code subscription — never the API. A key exported in
-    // the shell would otherwise silently bill every poll-mode turn as raw API
-    // usage (same invariant live mode enforces on its SDK session env).
-    const env = { ...process.env };
-    delete env.ANTHROPIC_API_KEY;
-    delete env.ANTHROPIC_AUTH_TOKEN;
-    const child = spawn('claude', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Whatever this machine is signed in with, we use. We do NOT pick.
+    //
+    // This used to delete ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN to force
+    // the subscription path, which was right when the daemon ran on a
+    // developer's laptop: a key left in their shell would silently bill every
+    // turn as raw API usage instead of the plan they were already paying for.
+    // On a machine the project leaves running, an inherited org key is the
+    // POINT — deleting it is the daemon overriding the credential its operator
+    // deliberately configured.
+    //
+    // Which credential is correct, and whether an account may be shared, is
+    // between the operator and Anthropic. Flowviant does not detect it and does
+    // not enforce it; it runs Claude the ordinary way and relays what happens.
+    const child = spawn('claude', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
     onSpawn?.(child);
     let out = '';
     const pfx = label ? `${label} ` : '';

package/bin/lib/config.mjs

@@ -3,7 +3,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir, cpus } from 'node:os';
+import { homedir, cpus, totalmem } from 'node:os';
 
 // Read the daemon's version from its OWN package.json (always shipped in the npm
 // tarball) — never hardcode it. The hardcoded constant drifted: it sat at
@@ -59,30 +59,74 @@ export const STREAM_URL =
   FLEET_URL.replace(/\/agents(\/?)$/, '/stream$1').replace(/^http/, 'ws');
 export const POLL_SECONDS = Number(process.env.POLL_SECONDS || 20);
 
+/**
+ * What this machine can actually be given, read from the machine.
+ *
+ * `os.totalmem()` and `cpus().length` report the HOST inside a container: a
+ * 4GB container on a 256GB box reads 256GB and cheerfully oversubscribes until
+ * the OOM killer picks a victim — which, because it picks by resident size, is
+ * frequently not the task that caused it. cgroup v2 publishes the real limits,
+ * so read those first and treat the os module as the fallback it is.
+ */
+function machineLimits() {
+  const readCgroup = (f) => {
+    try {
+      return readFileSync(`/sys/fs/cgroup/${f}`, 'utf8').trim();
+    } catch {
+      return null;
+    }
+  };
+  let memBytes = totalmem();
+  const memMax = readCgroup('memory.max');
+  if (memMax && memMax !== 'max') {
+    const n = Number(memMax);
+    if (Number.isFinite(n) && n > 0) memBytes = Math.min(memBytes, n);
+  }
+  let cores = cpus().length || 2;
+  // "<quota> <period>" in microseconds, or "max <period>" for unlimited.
+  const cpuMax = readCgroup('cpu.max');
+  if (cpuMax && !cpuMax.startsWith('max')) {
+    const [q, p] = cpuMax.split(/\s+/).map(Number);
+    if (Number.isFinite(q) && Number.isFinite(p) && p > 0) {
+      cores = Math.max(1, Math.min(cores, Math.floor(q / p)));
+    }
+  }
+  return { memBytes, cores };
+}
+
+export const MACHINE = machineLimits();
+
 /**
  * How many tasks THIS MACHINE will build at once.
  *
  * The limit belongs here, not on the server: a task in flight is a Claude Code
  * session plus its own git worktree plus whatever the project's dev server and
  * tests want, and this process is the only party that can see the cores, the
- * RAM and the fan. The server used to decide it, indirectly, by how many lanes
- * a user had pre-sized with a dial — which asked them to answer a question
- * about their laptop in a web app, before they knew what they were going to
- * dispatch.
+ * RAM and the fan.
  *
  * Sent to the server on every roster poll so it can grow lanes to meet waiting
  * work UNDER this ceiling, and enforced locally besides — the roster can carry
- * more lanes than this (someone added capacity by hand, or a second machine
- * shares the fleet), and a ceiling that only exists as a request is not one.
+ * more lanes than this, and a ceiling that only exists as a request is not one.
+ *
+ * MEMORY is the bound, not cores. Cores oversubscribe gracefully (everything
+ * gets slower); memory does not (something dies, and not necessarily the
+ * offender). A task is a Claude session plus a dev server plus whatever the
+ * test runner spawns — call it 2GB, keep 2GB back for the operating system,
+ * and let cores cap it only when they are the scarcer thing.
  *
- * Half the cores, floor 1, cap 4. Half because a build agent is not the only
- * thing running — the user is working on this machine too — and 4 because past
- * that the shared Claude account, not the CPU, is what runs out.
+ * This used to be `min(4, cores/2)` — half the cores because "the user is
+ * working on this machine too", and a hard 4 because a personal Claude plan
+ * ran out before the CPU did. Both were laptop assumptions. The machine is now
+ * a box the project leaves running, so it reserves one core rather than half of
+ * them, and the ceiling is what the hardware can hold rather than a guess about
+ * somebody's plan.
  */
 export const MAX_CONCURRENT = (() => {
   const asked = Number(process.env.FLOWVIANT_MAX_CONCURRENT);
   if (Number.isFinite(asked) && asked >= 1) return Math.min(Math.floor(asked), 32);
-  return Math.max(1, Math.min(4, Math.floor((cpus().length || 2) / 2)));
+  const byMem = Math.floor((MACHINE.memBytes / 2 ** 30 - 2) / 2);
+  const byCpu = MACHINE.cores - 1;
+  return Math.max(1, Math.min(32, byMem, byCpu));
 })();
 export const IDLE_SECONDS = Number(process.env.IDLE_SECONDS || 30);
 // Live mode: after this long idle-parked on a blocker, tear the session down to

package/bin/lib/fleet.mjs

@@ -5,7 +5,7 @@
  * MCP token, and only spawns Claude when the server says an agent has work.
  */
 
-import { mkdirSync, existsSync, rmSync } from 'node:fs';
+import { mkdirSync, existsSync, rmSync, readdirSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
@@ -30,6 +30,7 @@ import { handleVersionSignal } from './update.mjs';
 import {
   git,
   resetWorktree,
+  ensureWorktree,
   repoRootOrDie,
   detectBaseRef,
   originSlug,
@@ -73,6 +74,7 @@ import {
   scrub as envScrub,
 } from './env.mjs';
 import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
+import { machineSnapshot } from './resources.mjs';
 
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
@@ -122,7 +124,7 @@ async function fetchRoster(haveIds) {
 
 // One roster agent's loop: persistent worktree, one intent per turn, reset to
 // base between tasks (fresh conversation), resume in place while on a blocker.
-async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWork, getMcpUrl, isAlive, onChild, onTokenSuspect }) {
+async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWork, getNext, getMcpUrl, isAlive, onChild, onTokenSuspect }) {
   let resuming = false;
   let needsReset = true; // reset to base before a FRESH task, not on idle polls
   let phase = ''; // '', 'idle', 'blocked' — log each transition once, not per poll
@@ -152,15 +154,25 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
       needsReset = false;
     }
     const { dir, path: mcpConfig } = mcpConfigFor(token, getMcpUrl());
+    // The task the server says is next for this lane, read ONCE per turn: the
+    // model and effort below become process flags, so they must describe the
+    // same task the kickoff tells Claude to claim. Re-reading the map mid-turn
+    // could pair one task's flags with another's work.
+    const next = resuming ? null : getNext?.(agentId) || null;
     let out = '';
     try {
       out = await runTurn({
-        prompt: resuming ? SINGLE_RESUME : SINGLE_KICKOFF,
+        prompt: resuming ? SINGLE_RESUME : SINGLE_KICKOFF(next?.intentId),
         resume: resuming,
         system: SYSTEM_SINGLE,
         cwd,
         mcpConfig,
         label,
+        // Per-task overrides — null/absent means this machine's own defaults
+        // (FLOWVIANT_MODEL, and Claude Code's own effort). A resume keeps the
+        // session it already has, so there is nothing to re-pick there.
+        model: next?.model || undefined,
+        effort: next?.effort || undefined,
         onSpawn: (ch) => onChild?.(ch),
       });
     } finally {
@@ -227,11 +239,31 @@ export async function runFleetDaemon() {
   reapOrphanPreviews((m) => info(m));
 
   // Persistent worktree home (0.9.0) — survives daemon restarts AND reboots,
-  // so Ctrl+C mid-task never loses local work. Keyed per repo path; each
-  // agent's worktree carries a task marker so a resumed claim keeps its files.
+  // so Ctrl+C mid-task never loses local work. Keyed per repo path.
   const repoKey = `${basename(repoRoot)}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`;
   const baseDir = join(homedir(), '.flowviant', 'worktrees', repoKey);
   mkdirSync(baseDir, { recursive: true });
+
+  // ONE CHECKOUT PER TASK, named after the task. Worktrees used to be
+  // `agent-<agentId>` — a long-lived tree per lane, reset to base between
+  // tasks — and that was the last thing a lane owned. Now a lane is a
+  // credential and nothing more, which is what makes it disposable: the server
+  // can hand any lane any task, and two tasks can never be in each other's
+  // files even when one is mid-edit.
+  const taskWorktreePath = (intentId) => join(baseDir, `task-${intentId}`);
+  const worktreeFor = (intentId) => {
+    const r = ensureWorktree(repoRoot, taskWorktreePath(intentId), baseRef);
+    // Only on creation: a resumed tree already has its env, and rewriting it
+    // mid-task would clobber anything the agent changed.
+    if (r.fresh) {
+      try {
+        materializeInto(r.path);
+      } catch {
+        /* best-effort — the task still builds, secrets-backed paths may 500 */
+      }
+    }
+    return r;
+  };
   try {
     const kb = Number(execFileSync('du', ['-sk', baseDir], { encoding: 'utf8' }).split('\t')[0]);
     if (kb > 1024)
@@ -241,9 +273,48 @@ export async function runFleetDaemon() {
   } catch {
     /* du unavailable (Windows) — skip the disk line */
   }
+
+  // Reap long-dead task checkouts. Per-lane trees were self-limiting — N lanes,
+  // N directories, reused forever. Per-task trees are not: every task ever
+  // built leaves one behind, so without this the disk grows without bound and
+  // `flowviant clean` becomes a chore rather than a convenience.
+  //
+  // Age, not state, is the test. The daemon has no list of which intents are
+  // still open, and asking the server for one would put a delete behind a
+  // network call that can fail — so anything untouched for a fortnight goes,
+  // which is far beyond how long a task stays reviewable and far beyond any
+  // pause a human takes mid-build. Runs at startup only: mid-run this would
+  // race a worker that is quietly parked on a blocker.
+  try {
+    const cutoff = Date.now() - 14 * 24 * 60 * 60 * 1000;
+    let reaped = 0;
+    for (const name of readdirSync(baseDir)) {
+      if (!name.startsWith('task-')) continue;
+      const p = join(baseDir, name);
+      try {
+        if (statSync(p).mtimeMs > cutoff) continue;
+        // Through git, so the worktree REGISTRATION goes too — an rm -rf leaves
+        // a stale entry that blocks re-adding the same path later.
+        git(['worktree', 'remove', '--force', p], repoRoot);
+        reaped++;
+      } catch {
+        /* held, gone, or not ours — leave it for `flowviant clean` */
+      }
+    }
+    if (reaped) info(`disk   · reclaimed ${reaped} task worktree${reaped === 1 ? '' : 's'} idle > 14d`);
+  } catch {
+    /* the worktree home may not exist yet on a first run */
+  }
   const tokenByAgent = new Map(); // agentId -> latest worker token
   const mintedAt = new Map(); // agentId -> ms when we last got a fresh token
   const hasWorkByAgent = new Map(); // agentId -> server says it has claimable work
+  // agentId -> the intent the server would hand this lane next: { intentId,
+  // title, model, effort }. `--model`/`--effort` are fixed when Claude starts,
+  // and by then nothing has been claimed — so the server names the task first
+  // and the turn pins its claim to that id. Absent on older servers, in which
+  // case the lane behaves exactly as it did before: generic kickoff, machine
+  // defaults.
+  const nextByAgent = new Map();
   let leaseTtlSeconds = 24 * 60 * 60; // updated from each roster response
   let mcpUrl = MCP_URL;
   const workers = new Map(); // agentId -> { state, promise, wt, label }
@@ -486,6 +557,8 @@ export async function runFleetDaemon() {
   };
 
   const PLAN_CHECK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/plan-check-done');
+  // Machine telemetry — what the box is doing with itself, for the admin view.
+  const MACHINE_URL = FLEET_URL.replace(/\/agents\/?$/, '/machine');
   const checkingPlans = new Set();
   const processPlanCheckJobs = (jobs) => {
     for (const job of jobs ?? []) {
@@ -561,16 +634,17 @@ export async function runFleetDaemon() {
   let joinChain = Promise.resolve();
 
   /** The worktree currently building this intent, or null if this machine isn't.
-   *  The task marker lives in the worktree's git dir and is what a resume already
-   *  uses to recognise its own half-built tree, so it is the honest answer to
-   *  "where is this task actually being built". */
+   *  Now a direct lookup rather than a scan: a task's checkout is named after
+   *  the task, so there is exactly one place it could be. The marker is still
+   *  consulted, but for LIFECYCLE rather than identity — a directory that
+   *  outlived its run (finished, cleared its marker, kept for the review
+   *  preview) exists but is not building anything, and must not take an edit. */
   const worktreeBuilding = (intentId) => {
-    for (const w of workers.values()) {
-      try {
-        if (w.wt && readTaskMarker(w.wt) === intentId) return w;
-      } catch {
-        /* a worktree that vanished isn't building anything */
-      }
+    const wt = taskWorktreePath(intentId);
+    try {
+      if (existsSync(wt) && readTaskMarker(wt) === intentId) return { wt };
+    } catch {
+      /* a worktree that vanished isn't building anything */
     }
     return null;
   };
@@ -1302,6 +1376,8 @@ export async function runFleetDaemon() {
         mintedAt.set(a.agentId, Date.now());
       }
       hasWorkByAgent.set(a.agentId, !!a.hasWork);
+      if (a.next && typeof a.next.intentId === 'string') nextByAgent.set(a.agentId, a.next);
+      else nextByAgent.delete(a.agentId);
       if (!workers.has(a.agentId)) {
         // Local ceiling, enforced and not merely requested. The roster can carry
         // more lanes than this machine asked for — someone added capacity by
@@ -1320,46 +1396,50 @@ export async function runFleetDaemon() {
           }
           continue;
         }
-        const wt = join(baseDir, `agent-${a.agentId}`);
-        try {
-          if (!existsSync(wt)) {
-            try {
-              git(['worktree', 'add', '--detach', wt, baseRef], repoRoot);
-            } catch {
-              // A stale registration (e.g. after `flowviant clean` rm'd the
-              // dir) blocks re-adding the same path — prune and retry once.
-              git(['worktree', 'prune'], repoRoot);
-              git(['worktree', 'add', '--detach', wt, baseRef], repoRoot);
-            }
+        // LIVE lanes get NO checkout of their own — they ask for one per task,
+        // once they know which task. Poll mode is the legacy escape hatch and
+        // keeps its per-lane tree; it predates per-task sandboxes and isn't
+        // worth restructuring for a path nobody runs by default.
+        let wt = null;
+        if (!LIVE) {
+          try {
+            ensureWorktree(repoRoot, (wt = join(baseDir, `agent-${a.agentId}`)), baseRef);
+          } catch (e) {
+            fail(`could not create worktree for "${a.name}": ${e.message}`);
+            continue;
+          }
+          try {
+            materializeInto(wt); // synced env into the fresh worktree
+          } catch {
+            /* best-effort */
           }
-        } catch (e) {
-          fail(`could not create worktree for "${a.name}": ${e.message}`);
-          continue;
-        }
-        try {
-          materializeInto(wt); // synced env into the fresh worktree
-        } catch {
-          /* best-effort */
         }
         const colorFn = LABEL_COLORS[joinCount++ % LABEL_COLORS.length];
         const label = colorFn(`[${a.name}]`);
         const state = { alive: true, child: null };
-        ok(`${label} ${c.dim(`online — worktree ready${LIVE ? ' · live session' : ''}`)}`);
+        ok(`${label} ${c.dim(LIVE ? 'online — live session' : 'online — worktree ready')}`);
         const workerFn = LIVE ? runLiveWorker : runFleetWorker;
         const promise = workerFn({
           agentId: a.agentId,
           label,
-          cwd: wt,
+          ...(LIVE ? { worktreeFor } : { cwd: wt }),
           baseRef,
           repoRoot, // for copying the repo's local env into the preview worktree
 
           getToken: (id) => tokenByAgent.get(id),
           getHasWork: (id) => hasWorkByAgent.get(id) ?? false,
+          getNext: (id) => nextByAgent.get(id) ?? null,
           getMcpUrl: () => mcpUrl,
           isAlive: () => state.alive,
           onChild: (ch) => {
             state.child = ch;
           },
+          // Which task this lane is holding, so per-process memory can be
+          // attributed to a task rather than to an anonymous pid. "The box is
+          // full" is not actionable; "this task is holding 9GB" is.
+          onIntent: (id) => {
+            state.intentId = id;
+          },
           // Hold the preview's stop fn so teardown/removal can kill the detached
           // dev-server + tunnel (they survive our exit otherwise).
           onPreview: (stop) => {
@@ -1404,6 +1484,27 @@ export async function runFleetDaemon() {
       }
     });
 
+    // Tell the app what this machine is doing with itself. Every reconcile,
+    // best-effort, and never awaited — telemetry that can delay a dispatch is
+    // worse than no telemetry.
+    //
+    // The one thing Flowviant could never answer about a task was "why is it
+    // slow", because the box was somebody's laptop and only they could look at
+    // it. Centralising is supposed to make one machine easier to manage than N
+    // laptops; that is only true if the machine is visible. Per-task RSS is the
+    // load-bearing part — "the box is full" is not actionable, "this task is
+    // holding 9GB" is.
+    void reportMergeOutcome(
+      MACHINE_URL,
+      machineSnapshot({
+        worktreeDir: baseDir,
+        tasks: [...workers].map(([, w]) => ({
+          intentId: w.state.intentId ?? null,
+          pid: w.state.child?.pid,
+        })),
+      })
+    );
+
     // Deploy: a deploy-authorized daemon reports its .flowviant/deploy.json and
     // runs queued deploy jobs (the server only sends deployJobs to authorized
     // machines). Config report is cheap + dedup'd; jobs are single-flight.
@@ -1415,7 +1516,7 @@ export async function runFleetDaemon() {
     // Stop workers whose agent left the roster (removed in the app).
     for (const [id, w] of [...workers]) {
       if (!rosterIds.has(id)) {
-        warn(`${w.label} removed — stopping it now, freeing its worktree.`);
+        warn(`${w.label} removed — stopping it now.`);
         w.state.alive = false;
         // Immediate teardown (Q6=B): kill the in-flight Claude process now; its
         // task was already requeued server-side on removal.
@@ -1429,14 +1530,21 @@ export async function runFleetDaemon() {
         } catch {
           /* best-effort */
         }
-        try {
-          git(['worktree', 'remove', '--force', w.wt], repoRoot);
-        } catch {
-          /* best-effort */
+        // Only poll mode's per-lane tree dies with the lane. A live lane owns no
+        // checkout: the task it was building has its own, which must SURVIVE —
+        // removing a lane requeues its task, and the next lane to pick that task
+        // up resumes in that same directory rather than starting over.
+        if (w.wt) {
+          try {
+            git(['worktree', 'remove', '--force', w.wt], repoRoot);
+          } catch {
+            /* best-effort */
+          }
         }
         workers.delete(id);
         tokenByAgent.delete(id);
         hasWorkByAgent.delete(id);
+        nextByAgent.delete(id);
         mintedAt.delete(id); // was leaked on removal (finding 14)
       }
     }

package/bin/lib/git.mjs

@@ -1,6 +1,10 @@
 /** Git worktree helpers (fleet & static-fleet modes). */
 
 import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 
 export function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
@@ -113,6 +117,149 @@ export function baseBranchName(baseRef) {
   return String(baseRef || '').replace(/^origin\//, '') || 'main';
 }
 
+/**
+ * Get a detached worktree at `wt`, creating it at `ref` if it isn't there.
+ *
+ * Returns `{ path, fresh }` — `fresh` is the whole point. A worktree that
+ * ALREADY existed is one somebody was mid-way through, and the caller must not
+ * reset it; a freshly created one is at base by construction and has nothing to
+ * preserve. That single bit replaces the in-memory `resuming` flag and the
+ * on-disk task marker for the common case, because once a worktree is named
+ * after its task, "does this directory exist" IS "am I resuming".
+ *
+ * The prune-and-retry is not paranoia: `git worktree add` refuses a path that
+ * is still REGISTERED even when the directory is gone (`flowviant clean` rm's
+ * the dirs, `git worktree list` keeps the stale entries), and that failure is
+ * permanent until pruned.
+ */
+export function ensureWorktree(repoRoot, wt, ref) {
+  // Resolve first. `existsSync` answers relative to THIS process's cwd while
+  // `git worktree add` answers relative to repoRoot, so a relative path makes
+  // the two disagree: the check says "not there", the add says "already
+  // exists", and the prune-and-retry can't fix a path that was never the one
+  // we looked at. Callers pass absolute paths today; this makes that not matter.
+  wt = resolve(wt);
+  if (existsSync(wt)) return { path: wt, fresh: false };
+  try {
+    git(['worktree', 'add', '--detach', wt, ref], repoRoot);
+  } catch {
+    git(['worktree', 'prune'], repoRoot);
+    git(['worktree', 'add', '--detach', wt, ref], repoRoot);
+  }
+  return { path: wt, fresh: true };
+}
+
+// ── WIP checkpoints: the sandbox's state, on the remote ────────────────────
+//
+// A task's uncommitted work used to exist in exactly one place — a directory on
+// whichever machine claimed it. That made the checkout precious: losing the box
+// lost the work, so a task was pinned to a host, the host had to be named in the
+// UI, and a container could never be thrown away. Pushing the work somewhere
+// durable inverts all of that. The sandbox becomes a cache.
+//
+// These snapshots go to `refs/flowviant-wip/<intentId>`, NOT to a branch: they
+// are machine state, not history, and they must never appear in a PR, a branch
+// listing, or anyone's `git log`. Force-pushed, because only the latest matters.
+
+const wipRef = (intentId) => `refs/flowviant-wip/${intentId}`;
+
+/** git, with extra environment — for GIT_INDEX_FILE and a committer identity we
+ *  can't assume the machine has configured. */
+function gitWithEnv(args, cwd, extraEnv) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, ...extraEnv },
+  }).trim();
+}
+
+/**
+ * Snapshot everything in the worktree — staged, unstaged and untracked — and
+ * push it, WITHOUT touching the agent's HEAD, index or files.
+ *
+ * That constraint is why this doesn't just commit. The agent is a live process
+ * with its own git intentions; committing under it would rewrite state it is
+ * mid-way through reasoning about, and `git stash` would rip the files out from
+ * under an editor. Building the tree in a throwaway index leaves the agent's
+ * world untouched — it cannot tell this happened.
+ *
+ * Returns the commit sha, or null if there was nothing dirty / no remote.
+ */
+export function checkpointWip(wt, intentId, baseRef) {
+  if (!isSafePathSegment(intentId)) return null;
+  const idx = join(tmpdir(), `flowviant-idx-${intentId}-${process.pid}`);
+  const env = {
+    GIT_INDEX_FILE: idx,
+    // A snapshot must never fail because the machine has no user.name — this is
+    // ours, not the user's, and it never lands in history anyone reads.
+    GIT_AUTHOR_NAME: 'Flowviant',
+    GIT_AUTHOR_EMAIL: 'daemon@flowviant.com',
+    GIT_COMMITTER_NAME: 'Flowviant',
+    GIT_COMMITTER_EMAIL: 'daemon@flowviant.com',
+  };
+  try {
+    const head = git(['rev-parse', 'HEAD'], wt);
+    gitWithEnv(['read-tree', head], wt, env);
+    gitWithEnv(['add', '-A'], wt, env);
+    const tree = gitWithEnv(['write-tree'], wt, env);
+    // Nothing changed since HEAD — no snapshot worth pushing.
+    if (tree === git(['rev-parse', `${head}^{tree}`], wt)) return null;
+    const commit = gitWithEnv(
+      ['commit-tree', tree, '-p', head, '-m', `flowviant wip ${intentId}`],
+      wt,
+      env
+    );
+    git(['push', '--force', 'origin', `${commit}:${wipRef(intentId)}`], wt);
+    return commit;
+  } catch {
+    // Offline, no push rights, a repo with no origin — a checkpoint is an
+    // optimisation, never a reason to fail a task.
+    return null;
+  } finally {
+    try {
+      rmSync(idx, { force: true });
+    } catch {
+      /* best-effort */
+    }
+    void baseRef;
+  }
+}
+
+/**
+ * Rebuild a worktree from its last pushed checkpoint. Returns true if one was
+ * found and applied.
+ *
+ * The reset is MIXED on purpose: it leaves the snapshot's content in the files
+ * with HEAD back at the parent, which is what the agent had before — dirty
+ * working tree, nothing staged it didn't stage itself. A soft reset would hand
+ * it a fully-staged index it never created.
+ */
+export function restoreWip(wt, intentId) {
+  if (!isSafePathSegment(intentId)) return false;
+  const ref = wipRef(intentId);
+  try {
+    git(['fetch', 'origin', `+${ref}:${ref}`], wt);
+    const commit = git(['rev-parse', ref], wt);
+    const parent = git(['rev-parse', `${commit}^`], wt);
+    git(['checkout', '--detach', commit], wt);
+    git(['reset', parent], wt);
+    return true;
+  } catch {
+    return false; // no checkpoint for this task, or it's unreachable
+  }
+}
+
+/** Drop a task's checkpoint once its work has landed somewhere real. */
+export function clearWip(wt, intentId) {
+  if (!isSafePathSegment(intentId)) return;
+  try {
+    git(['push', 'origin', '--delete', wipRef(intentId)], wt);
+  } catch {
+    /* already gone, or no remote */
+  }
+}
+
 export function resetWorktree(wt, baseRef) {
   try {
     git(['fetch', 'origin', '--quiet'], wt);

package/bin/lib/live.mjs

@@ -7,9 +7,11 @@
  * the human's answer and injects it to resume in place). Same session = the
  * iterating loop, hosted through Flowviant.
  *
- * Auth invariant: the SDK runs the user's own Claude Code (subscription), never
- * the API — we strip ANTHROPIC_API_KEY from the session env so a key in the
- * user's shell can't silently divert to API billing.
+ * Auth: whatever this machine's Claude Code is signed in with. The daemon used
+ * to strip ANTHROPIC_API_KEY so a stray key couldn't divert a laptop's turns to
+ * API billing; on a machine the project leaves running an org key is the
+ * intended credential, and which one is legitimate is between the operator and
+ * Anthropic — not something Flowviant detects or enforces.
  *
  * NOTE: the SDK mechanics here (streaming-input continuity, tool_use visibility,
  * one result per turn) are validated by spikes; the end-to-end task loop needs a
@@ -33,7 +35,14 @@ import {
 } from './config.mjs';
 import { c, info, ok, warn } from './ui.mjs';
 import { sleep } from './claude.mjs';
-import { git, resetWorktree, isValidBranch } from './git.mjs';
+import {
+  git,
+  resetWorktree,
+  isValidBranch,
+  checkpointWip,
+  restoreWip,
+  clearWip,
+} from './git.mjs';
 import { applyPatch, fileDiffs, ownerCurrentBranch, withPatchLock } from './patch.mjs';
 import { loadPreviewConfig, startPreview } from './preview.mjs';
 import { materializeInto, scrub as envScrub } from './env.mjs';
@@ -48,6 +57,11 @@ const LIVE_TARGET_URL = FLEET_URL.replace(/\/agents\/?$/, '/live-target');
 // missed heartbeats.
 const PREVIEW_TTL_MINUTES = 6;
 const PREVIEW_HEARTBEAT_MS = 90_000;
+// How often a running task snapshots its uncommitted work to the remote. Two
+// minutes bounds what an unannounced death can cost while staying invisible:
+// an unchanged tree writes no commit and pushes nothing, so an agent that is
+// thinking rather than editing costs one cheap tree comparison.
+const CHECKPOINT_MS = 120_000;
 async function registerLiveTarget(intentId, kind, url) {
   try {
     await fetch(LIVE_TARGET_URL, {
@@ -544,12 +558,13 @@ async function landPatch({ mcpUrl, token, runId, intentId, repoRoot, cwd, patchB
 export async function runLiveTask({
   mcpUrl,
   token,
-  cwd,
+  worktreeFor,
   baseRef,
   repoRoot,
   isAlive,
   resumeIntentId,
   onChild,
+  onIntent,
 }) {
   const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
   if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
@@ -557,12 +572,29 @@ export async function runLiveTask({
   const brief = claim.brief ?? {};
   const title = brief.title ?? 'a task';
 
+  // THE SANDBOX BELONGS TO THE TASK, not to the lane that happened to pick it
+  // up. Worktrees used to be `agent-<agentId>` — one long-lived checkout per
+  // lane, wiped back to base between tasks — which is why a lane had to own
+  // anything at all, and why every claim had to work out whether the directory
+  // it was standing in held its own half-built work or somebody else's finished
+  // work. Keyed by intent, that question answers itself: the directory either
+  // exists (yours, mid-flight) or it doesn't (nothing to lose).
+  //
+  // Note this is the first point at which a worktree can be chosen — the claim
+  // is what tells us which task we're building, and the daemon has no business
+  // creating a checkout for work it hasn't been given.
+  // Name the task this lane is holding, so its memory can be attributed to a
+  // task rather than to an anonymous pid.
+  onIntent?.(intentId);
+  const { path: cwd, fresh: freshTree } = worktreeFor(intentId);
+
   // Re-claiming the SAME intent this worker was just working — either this
-  // daemon's own memory (parked on a blocker, now resuming) or the persistent
-  // task marker (the daemon restarted mid-task). Its worktree holds hours of
-  // uncommitted work. Do NOT reset.
+  // daemon's own memory (parked on a blocker, now resuming) or a worktree that
+  // was already on disk (the daemon restarted mid-task). Either way it holds
+  // hours of uncommitted work. Do NOT reset. `!fresh` subsumes what the task
+  // marker used to tell us, since the directory is now named after the task.
   const resuming = !!resumeIntentId && intentId === resumeIntentId;
-  const resumedInPlace = !resuming && readTaskMarker(cwd) === intentId;
+  const resumedInPlace = !resuming && !freshTree;
 
   // CONSENT. A patch writes commits into the working checkout of whoever runs
   // this daemon — chosen by a model, and triggerable by any teammate who
@@ -656,6 +688,20 @@ export async function runLiveTask({
     }
     if (!stacked) resetWorktree(cwd, baseRef);
   }
+  // A fresh checkout is not necessarily a fresh TASK. This machine may never
+  // have seen this intent while another one built on it for an hour before
+  // dying, being released, or simply being a different container — and that
+  // work is on the remote. Restoring here, AFTER the resets above, is what
+  // makes a sandbox a cache rather than the only copy: any machine can pick up
+  // any task exactly where it was left.
+  if (freshTree && restoreWip(cwd, intentId)) {
+    info(`${c.dim('restored work in progress from the last checkpoint')}`);
+    await mcpCall(mcpUrl, token, 'stream_turn', {
+      runId,
+      turnId: `restore:${runId}`,
+      text: 'Picked this up on another machine — restored the work in progress from its last checkpoint.',
+    }).catch(() => {});
+  }
   materializeInto(cwd); // resets wipe the synced env files — rewrite them
   writeTaskMarker(cwd, intentId);
 
@@ -669,14 +715,11 @@ export async function runLiveTask({
     }).catch(() => {});
   }
 
+  // The machine's own credentials, inherited as configured. See claude.mjs for
+  // why this no longer strips ANTHROPIC_API_KEY / AUTH_TOKEN / BASE_URL: on a
+  // machine the project leaves running, an org key is the intended credential
+  // and deleting it overrides the operator. Enforcement is Anthropic's.
   const env = { ...process.env };
-  // Force the user's Claude Code subscription — strip EVERY var that could
-  // divert to API billing or a proxy (poll mode strips these too; live mode
-  // was only clearing API_KEY, so an exported AUTH_TOKEN/BASE_URL silently
-  // billed the API on the default path).
-  delete env.ANTHROPIC_API_KEY;
-  delete env.ANTHROPIC_AUTH_TOKEN;
-  delete env.ANTHROPIC_BASE_URL;
 
   // The conversation arrives WITH the brief (0.30.0) — the claim already read
   // it, so asking again over poll_channel was a round-trip that told us nothing
@@ -695,6 +738,21 @@ export async function runLiveTask({
   let afterId =
     brief.lastMessageId ?? (priorMsgs.length ? priorMsgs[priorMsgs.length - 1].id : null);
 
+  // Checkpoint on a timer for the whole session. Not on turn boundaries: the
+  // expensive-to-lose states are the ones that arrive without a boundary — the
+  // box is killed, the container is reclaimed, the process is OOMed — and a
+  // long tool-running turn is exactly when the most uncommitted work exists.
+  // Cheap when idle: an unchanged tree writes no commit and pushes nothing.
+  let landed = false; // set when the work reaches a branch/PR/patch — see finally
+  const checkpointTimer = setInterval(() => {
+    try {
+      checkpointWip(cwd, intentId);
+    } catch {
+      /* never let a snapshot disturb a running task */
+    }
+  }, CHECKPOINT_MS);
+  checkpointTimer.unref?.();
+
   const input = makeInput(seedPrompt(runId, brief, transcript, resumedInPlace));
   const session = query({
     prompt: input.stream(),
@@ -814,6 +872,7 @@ export async function runLiveTask({
           if (isPatch) {
             await landPatch({ mcpUrl, token, runId, intentId, repoRoot, cwd, patchBase, baseRef });
           }
+          landed = true;
           return { outcome: 'done', title, intentId };
         }
 
@@ -838,12 +897,27 @@ export async function runLiveTask({
         }).catch(() => null);
         // Torn down out from under us (restart / reassign in Flowviant): the
         // server killed this run — abandon the session, don't keep building.
+        // RELEASED: stop, and touch nothing. The human freed the machine, not
+        // the work — the branch, the PR and the worktree all stay exactly as
+        // they are, and re-@mentioning resumes here rather than from base. The
+        // finally block takes a last checkpoint on the way out, so even the
+        // uncommitted edits survive to whichever machine picks it up next.
+        if (poll && poll.ok === false && poll.released) {
+          return { outcome: 'released', title, intentId };
+        }
         if (poll && poll.ok === false && poll.reason === 'run_not_active') {
-          // Discarded (restart/reassign): clear the marker AND reset the
-          // worktree so the next fresh claim starts from clean base, never
-          // resuming the abandoned attempt.
+          // Discarded (restart/reassign). REMOVE the checkout rather than reset
+          // it: the directory is named after the intent, so a restart of this
+          // same task would otherwise find it, read "already exists" as "I am
+          // resuming", and pick the abandoned attempt back up — the precise
+          // failure the old marker-clearing existed to prevent. Deleting it
+          // makes the next claim genuinely fresh.
           clearTaskMarker(cwd);
-          resetWorktree(cwd, baseRef);
+          try {
+            git(['worktree', 'remove', '--force', cwd], repoRoot);
+          } catch {
+            resetWorktree(cwd, baseRef); // couldn't remove it — at least empty it
+          }
           return { outcome: 'torn_down', title, intentId };
         }
         const fresh = (poll?.messages ?? []).filter((x) => x.role === 'user');
@@ -884,6 +958,7 @@ export async function runLiveTask({
         return { outcome: 'stalled', title, intentId };
       }
     }
+    landed = completed;
     return { outcome: completed ? 'done' : 'stalled', title, intentId };
   } catch (e) {
     const rl = classifyRateLimit(e);
@@ -896,7 +971,21 @@ export async function runLiveTask({
     }
     return { outcome: 'error', error: e?.message ?? String(e), title, intentId };
   } finally {
+    clearInterval(checkpointTimer);
+    // Last word on this task's state. If the work landed (branch pushed, PR
+    // open, patch applied) the checkpoint has served its purpose and the ref is
+    // deleted — otherwise it accumulates one hidden ref per task, forever, on
+    // everyone's remote. If it did NOT land, this is the most important
+    // checkpoint of the run: it is the one taken as the task parks, is released,
+    // hits a usage limit, or dies.
+    try {
+      if (landed) clearWip(cwd, intentId);
+      else checkpointWip(cwd, intentId);
+    } catch {
+      /* teardown must not throw */
+    }
     onChild?.(null); // no longer busy — token may rotate between tasks
+    onIntent?.(null);
     input.close();
     try {
       await session.interrupt?.();
@@ -943,7 +1032,10 @@ function copyLocalEnvFiles(repoRoot, worktree, log) {
 export async function runLiveWorker({
   agentId,
   label,
-  cwd,
+  // `(intentId) => { path, fresh }`. A lane no longer HAS a working directory —
+  // it is a credential and nothing else. Every checkout belongs to a task, so
+  // the worker asks for one only once it knows which task it is holding.
+  worktreeFor,
   baseRef,
   repoRoot,
   getToken,
@@ -952,6 +1044,7 @@ export async function runLiveWorker({
   isAlive,
   onTokenSuspect,
   onChild,
+  onIntent,
   onPreview,
 }) {
   // The intent this worker is holding across iterations. When a task parks on a
@@ -1000,6 +1093,12 @@ export async function runLiveWorker({
   };
   const startReviewPreview = async (intentId) => {
     stopPreview();
+    if (!intentId) return;
+    // The finished task's own worktree — already on disk, so this is a lookup,
+    // not a creation. A review preview serves the branch that was just built,
+    // which now has a durable home instead of living in whichever lane's
+    // checkout happened to run it (and being wiped by that lane's next task).
+    const { path: cwd } = worktreeFor(intentId);
     const cfg = loadPreviewConfig(cwd);
     const kind = cfg?.ui ? 'ui' : cfg?.api ? 'api' : null;
     const entry = kind ? cfg[kind] : null;
@@ -1090,9 +1189,10 @@ export async function runLiveWorker({
     let res;
     try {
       res = await runLiveTask({
+        onIntent,
         mcpUrl: getMcpUrl() ?? MCP_URL,
         token,
-        cwd,
+        worktreeFor,
         baseRef,
         repoRoot,
         isAlive,
@@ -1133,6 +1233,18 @@ export async function runLiveWorker({
       phase = '';
       continue;
     }
+    if (res.outcome === 'released') {
+      // Released: the human wanted the machine back, not the work undone. The
+      // session is already gone (the finally checkpointed on the way out) and
+      // the worktree stays untouched, so a later @mention resumes here rather
+      // than from base. Clear lastIntentId so this worker doesn't treat a
+      // future claim of the same task as its own in-memory resume — the
+      // on-disk checkout is the resume signal now, and it may well be a
+      // different machine that picks this up.
+      info(`${label} ${c.dim(`"${res.title}" was released — stopped; its work is kept`)}`);
+      phase = '';
+      continue;
+    }
     if (res.outcome === 'parked') {
       // Idle-parked too long on a blocker: we freed the Claude process. The intent
       // stays claimed; a later poll re-claims + resumes (with transcript) once the

package/bin/lib/resources.mjs

@@ -0,0 +1,127 @@
+/**
+ * What this machine is actually doing with itself.
+ *
+ * Flowviant can tell you a task is building and nothing about why it is slow.
+ * That gap is affordable when the machine is your own laptop — you can look at
+ * it — and not when the machine is a box in a rack that four people share. The
+ * whole argument for one central machine is that one machine is easier to
+ * manage than N laptops, and that is only true if you can SEE the one machine.
+ *
+ * This is deliberately telemetry, never a budget. It reports pressure that
+ * exists right now, which is the same category as "what is building" — a fact
+ * about the world you would have known by sitting at the keyboard. It must
+ * never become a headroom number in front of the person dispatching: "you may
+ * run 2 more tasks" is the capacity dial wearing a lab coat, and that is dead.
+ * The only surface for this is project settings, whose audience is whoever
+ * administers the box.
+ */
+
+import { readFileSync, readdirSync, statfsSync } from 'node:fs';
+import { freemem, loadavg } from 'node:os';
+import { MACHINE } from './config.mjs';
+
+const readFile = (p) => {
+  try {
+    return readFileSync(p, 'utf8').trim();
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Memory in use, from the cgroup when there is one.
+ *
+ * `freemem()` reports the HOST inside a container — the same trap that made
+ * `cpus().length` lie about core count — so a container at 95% of its own
+ * limit looks idle if you ask the os module. Prefer memory.current against
+ * memory.max, and fall back only when there is no cgroup to read.
+ */
+function memoryUsed() {
+  const cur = readFile('/sys/fs/cgroup/memory.current');
+  if (cur !== null) {
+    const n = Number(cur);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return Math.max(0, MACHINE.memBytes - freemem());
+}
+
+/**
+ * Resident memory of a process AND everything it spawned.
+ *
+ * A task is never one process: it is Claude, plus a dev server, plus whatever
+ * the test runner forked. Charging a task only its own RSS would report a few
+ * hundred megabytes for something holding twelve gigabytes, which is worse than
+ * reporting nothing — it would exonerate the exact task you are hunting.
+ *
+ * Linux only, and that is stated rather than hidden: /proc is how you read this
+ * honestly, and a wrong number here sends someone to kill the wrong task.
+ */
+export function processTreeRssBytes(pid) {
+  if (!pid) return null;
+  const rssOf = (p) => {
+    const roll = readFile(`/proc/${p}/smaps_rollup`);
+    const src = roll ?? readFile(`/proc/${p}/status`);
+    if (!src) return 0;
+    const m = src.match(/^(?:Rss|VmRSS):\s+(\d+)\s+kB/m);
+    return m ? Number(m[1]) * 1024 : 0;
+  };
+  const childrenOf = (p) => {
+    const t = readFile(`/proc/${p}/task`);
+    if (t === null && !readFile(`/proc/${p}/stat`)) return [];
+    const out = [];
+    try {
+      for (const tid of readdirSync(`/proc/${p}/task`)) {
+        const kids = readFile(`/proc/${p}/task/${tid}/children`);
+        if (kids) out.push(...kids.split(/\s+/).filter(Boolean).map(Number));
+      }
+    } catch {
+      /* no children file (not Linux, or the process just exited) */
+    }
+    return out;
+  };
+  let total = 0;
+  const seen = new Set();
+  const stack = [Number(pid)];
+  while (stack.length) {
+    const p = stack.pop();
+    if (!Number.isFinite(p) || seen.has(p)) continue;
+    seen.add(p);
+    total += rssOf(p);
+    stack.push(...childrenOf(p));
+  }
+  return total || null;
+}
+
+/** Free bytes on the volume holding the worktrees. */
+export function diskFreeBytes(path) {
+  try {
+    // statfsSync landed in Node 18.15; the daemon's floor is well past that.
+    const s = statfsSync(path);
+    return { free: s.bavail * s.bsize, total: s.blocks * s.bsize };
+  } catch {
+    return null; // no statfs on this platform, or the path is gone
+  }
+}
+
+/**
+ * A snapshot for the roster poll. Small, flat, and all of it observed — nothing
+ * here is a prediction or an allowance.
+ */
+export function machineSnapshot({ worktreeDir, tasks = [] } = {}) {
+  const used = memoryUsed();
+  const disk = worktreeDir ? diskFreeBytes(worktreeDir) : null;
+  return {
+    memTotal: MACHINE.memBytes,
+    memUsed: used,
+    cores: MACHINE.cores,
+    // Unix only; Windows reports zeroes, which we send as null rather than as a
+    // very calm-looking 0.00.
+    load1: loadavg()[0] || null,
+    diskFree: disk?.free ?? null,
+    diskTotal: disk?.total ?? null,
+    // Per-task, so "the box is full" can be traced to the task that filled it.
+    tasks: tasks
+      .map((t) => ({ intentId: t.intentId, rss: processTreeRssBytes(t.pid) }))
+      .filter((t) => t.intentId && t.rss),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.34.2",
+  "version": "0.36.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {