flowviant 0.47.1 → 0.48.0

package/README.md

@@ -68,6 +68,31 @@ Flowviant only stores the tunnel URL; your browser talks to it directly.
 | `FLOWVIANT_TOKENS=a,b,c` | a static fleet, one worktree each |
 | `FLOWVIANT_SAFE=1` | restrict the toolset instead of running unattended |
 
+## Security posture
+
+Every project member with edit access can run turns on this machine —
+Workbench tabs and @-dispatches both execute a coding agent with the daemon's
+own OS permissions. Membership is the consent boundary, the same trust plane
+as the shared repository: invite people you would give a shell to.
+
+Two knobs bound the blast radius, and both are worth setting on a shared box:
+
+- **Run the daemon under a dedicated OS user** that owns only the repository
+  checkout and `~/.flowviant`. This is the single biggest hardening available
+  — a session can then only touch that account's files, not your keys, your
+  home directory, or the rest of the machine. A plain separate account works;
+  a systemd unit with `ProtectHome=read-only` and `ReadWritePaths=` works
+  better.
+- **`FLOWVIANT_SAFE=1`** narrows the toolset: Claude to an allowlist
+  (edit/read/search plus `git`/`gh`/`npm`/`bun` — no arbitrary shell), Codex
+  to a workspace-write sandbox. Antigravity has no per-invocation narrowing —
+  its permission engine is machine-wide — which is surfaced in the app rather
+  than papered over.
+
+The posture is reported on every poll and shown in the project's
+Settings → Machine section, so the team can see whether the box runs the
+guarded toolset or full permissions.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/bin/lib/claude.mjs

@@ -191,7 +191,13 @@ const oneLine = (s, n = 160) => String(s).replace(/\s+/g, ' ').trim().slice(0, n
 // bursts before/between tools; emitting only tools left long silent gaps).
 // Assistant text is also folded into `out` so the WIKI_DONE/REGROUND_DONE
 // sentinels still match. A non-JSON line (a stray warning) is kept as raw text.
-function handleStreamLine(line, { cwd, emit, onActivity, appendText }) {
+//
+// `answerFromResult` narrows that last part for callers whose `out` IS the
+// answer rather than a haystack to match sentinels in (a Workbench tab's turn):
+// every intermediate text block still NARRATES, but only the final `result`
+// event contributes text — otherwise the same sentences arrive twice, once as
+// they stream and once in the result, and the tab posts the duplicate.
+function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult }) {
   let ev;
   try {
     ev = JSON.parse(line);
@@ -212,15 +218,23 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText }) {
         // marker — enough to show Claude is actively reasoning, not hung.
         push({ kind: 'think', label: b.thinking ? `thinking: ${oneLine(b.thinking)}` : 'thinking…' });
       } else if (b.type === 'text' && b.text?.trim()) {
-        appendText(b.text + '\n');
+        if (!answerFromResult) appendText(b.text + '\n');
         push({ kind: 'say', label: oneLine(b.text) });
       } else if (b.type === 'tool_use') {
         push(humanizeToolUse(b.name, b.input || {}, cwd));
       }
     }
-  } else if (ev.type === 'result' && typeof ev.result === 'string') {
+  } else if (ev.type === 'result') {
     // The final assistant text (carries WIKI_DONE / REGROUND_DONE).
-    appendText(ev.result + '\n');
+    if (typeof ev.result === 'string') appendText(ev.result + '\n');
+    else if (ev.is_error || ev.subtype) {
+      // A result that carries no text is a FAILED turn (a limit, a refused
+      // permission, an aborted run). Under `answerFromResult` this is the only
+      // stdout that would have said so, and a caller whose `out` is the answer
+      // must not report "no output" for a turn that explained itself.
+      const msg = ev.error?.message ?? ev.error ?? ev.subtype;
+      appendText(`${typeof msg === 'string' ? msg : JSON.stringify(msg)}\n`);
+    }
   }
 }
 
@@ -233,7 +247,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, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, onActivity, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
   return new Promise((resolve) => {
     const rt = runtimeById(runtime);
     if (!rt.args) {
@@ -344,7 +358,8 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEn
       };
       /** One line of the child's stdout, in whichever dialect it speaks. */
       const onLine = (line) => {
-        if (!rt.parse) return handleStreamLine(line, { cwd, emit, onActivity, appendText });
+        if (!rt.parse)
+          return handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult });
         const ev = rt.parse(line, cwd);
         if (!ev) return;
         // The conversation id, when the runtime announces one (codex's

package/bin/lib/fleet.mjs

@@ -101,6 +101,12 @@ async function fetchRoster(haveIds) {
   // our own package.json). Older servers ignore unknown params, so sending it
   // unconditionally is always safe.
   url.searchParams.set('dv', VERSION);
+  // The permission posture this machine runs turns under — '1' when
+  // FLOWVIANT_SAFE narrows the toolset, '0' when everything is granted. A
+  // statement of configuration, not a request: the app SHOWS it in Settings
+  // so a team can see whether the shared box runs wide open, and enforces
+  // nothing (membership is the consent boundary). Older servers ignore it.
+  url.searchParams.set('safe', SAFE ? '1' : '0');
   // WHICH CLIs this machine actually has, so the app can stop guessing.
   //
   // Until now every surface that listed Gemini or Codex said "not wired up yet"
@@ -1207,6 +1213,7 @@ export async function runFleetDaemon() {
     processWorkTurns,
     processShipJobs,
     retireWorkSessions,
+    reportWorktrees,
     shutdownWork,
   } = createWorkManager({
     repoRoot,
@@ -1825,6 +1832,11 @@ export async function runFleetDaemon() {
     // sessions are LIVE, and the guards above (chains, shipping) are populated
     // by the intake this same tick.
     retireWorkSessions(roster.activeWorkSessions);
+    // …and what the SURVIVING ones hold: branch, ahead-of-base, diffstat.
+    // Throttled inside, never awaited — a `git status` the human cannot run
+    // themselves from a browser, relayed. After retirement so a directory that
+    // just went away is not reported as a place.
+    reportWorktrees(roster.activeWorkSessions);
     // Terminal-session presence, throttled + dedup'd inside; never awaited —
     // the daemon's own worktrees are carved out (a session the daemon spawned
     // is already a tab, not something to offer adopting).

package/bin/lib/prompts.mjs

@@ -458,26 +458,40 @@ MECHANICS OF THIS TAB:
 4. NEVER merge to main, deploy, or force-push unless the human explicitly says
    so in this conversation. Branch pushes and PRs are fine when asked. Shipping
    is their word to say, not yours to infer.
+5. WHEN THEY HAVE TO CHOOSE, HAND THEM THE CHOICES. A real pick between known
+   options — not an open question — ends your reply with a fenced block the app
+   renders as buttons; their click composes their answer as the next message:
+
+   \`\`\`flowviant-ask
+   {"question": "Which auth flow?", "options": ["Magic link", "Password", "Both"], "multiSelect": false}
+   \`\`\`
+
+   ONE block per reply, and always the LAST thing in it. Two to eight options,
+   each label short enough to sit on a button. multiSelect true only for a
+   genuine check-several-of-these case. NEVER for an open question — ask those
+   in prose, like anyone would. And ask the question in prose above the block
+   as well: a client that doesn't render the fence shows it as plain text, so
+   the reply has to read as a question with its options either way.
 
 THE LEDGER. This session's work is logged as CARDS as it happens, by you,
 through tools — so a four-hour churn doesn't evaporate into scrollback. The
 rules:
 
-5. CLAIM WHAT YOU WORK. When they say "take the auth card" or "next", call
+6. CLAIM WHAT YOU WORK. When they say "take the auth card" or "next", call
    list_cards, then claim_card the one they mean. The card you hold is the
    tab's "Now" — it is how they and their team see what this session is doing.
-6. LOG DRIFT, don't ask permission for it. "Also fix that redirect" mid-flow:
+7. LOG DRIFT, don't ask permission for it. "Also fix that redirect" mid-flow:
    do the work, and file_card it — check list_cards FIRST; if a planned card
    already covers it, claim that one instead of filing a twin. One card per
    shippable unit. Never card-ify chatter, questions, or exploration.
-7. DELIVER WITH RECEIPTS. When a card's work is committed, deliver_card with a
+8. DELIVER WITH RECEIPTS. When a card's work is committed, deliver_card with a
    one-paragraph summary and the commit shas. Delivered is ASSERTED; done is
    OBSERVED (the merge, on their word). Never claim done, and never deliver
    work that isn't committed.
-8. RAISE WHAT YOU SPOT. A design flaw, a follow-up they named for later —
+9. RAISE WHAT YOU SPOT. A design flaw, a follow-up they named for later —
    raise_card, queued, unheld. You do not start raised work.
-9. BE PROPORTIONAL. A one-line typo fix inside the card you already hold is
-   that card's work, not a new card. When in doubt, fewer cards.
+10. BE PROPORTIONAL. A one-line typo fix inside the card you already hold is
+    that card's work, not a new card. When in doubt, fewer cards.
 
 POSTURE: terminal, not ticket. Don't ask permission to look at things. Don't
 narrate ceremony. Ground claims in files you opened. When they ask a question,
@@ -514,6 +528,21 @@ MECHANICS OF THIS TAB:
 4. NEVER merge to main, deploy, or force-push unless the human explicitly says
    so in this conversation. Branch pushes are fine when asked. Shipping is
    their word to say, not yours to infer.
+5. WHEN THEY HAVE TO CHOOSE, HAND THEM THE CHOICES. You have no tools here, but
+   this one costs none — it is text. A real pick between known options (not an
+   open question) ends your reply with a fenced block the app renders as
+   buttons; their click composes their answer as the next message:
+
+   \`\`\`flowviant-ask
+   {"question": "Which auth flow?", "options": ["Magic link", "Password", "Both"], "multiSelect": false}
+   \`\`\`
+
+   ONE block per reply, and always the LAST thing in it. Two to eight options,
+   each label short enough to sit on a button. multiSelect true only for a
+   genuine check-several-of-these case. NEVER for an open question — ask those
+   in prose, like anyone would. And ask the question in prose above the block
+   as well: a client that doesn't render the fence shows it as plain text, so
+   the reply has to read as a question with its options either way.
 
 POSTURE: terminal, not ticket. Don't ask permission to look at things. Ground
 claims in files you opened. When they ask a question, answer it; when they ask

package/bin/lib/work.mjs

@@ -43,12 +43,54 @@ import {
 import { materializeInto, scrub as envScrub } from './env.mjs';
 import { detectRuntimes, canRun, RUNTIMES } from './runtimes.mjs';
 import { isTerminalSessionLive, isAgyConversationLive } from './localSessions.mjs';
+import { worktreeDiff } from './worktreeDiff.mjs';
 import { homedir } from 'node:os';
 
+/**
+ * The shape a per-tab model name must have before it rides argv as
+ * `--model <name>`. Conservative for the same reason the codex thread id is
+ * (below): it comes off the wire and lands in a child process's arguments —
+ * alphanumerics plus dot/dash/underscore, at most 40 characters, and NEVER a
+ * leading dash, which is an argv that parses as a flag.
+ */
+const WORK_MODEL_RE = /^[a-zA-Z0-9._][a-zA-Z0-9._-]{0,39}$/;
+
+/** The five efforts the CLIs actually accept. A literal set rather than a
+ *  pattern: there is no such thing as an effort we haven't heard of, and the
+ *  server's own union is exactly this list. */
+const WORK_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * WHICH BRAIN, AT WHICH EFFORT — the tab's own pick, off the roster.
+ *
+ * Absent is the resting state and it must stay genuinely absent: every tab ran
+ * with no `--model` and no `--effort` until now, so a job that names neither
+ * has to produce the byte-identical argv it produced yesterday — Claude falling
+ * back to the machine's MODEL pin, codex and agy to their own defaults. Hence
+ * an object with the key MISSING rather than one holding null: a null would
+ * reach the builders as a value and Claude's `model || MODEL` is the only one
+ * that would survive it.
+ *
+ * A value that fails its guard is DROPPED, not passed through and not an error.
+ * The honest outcome of "the server named a model this machine can't spell" is
+ * the machine's own default — a turn that runs — rather than a flag no CLI
+ * understands and a tab that fails every message.
+ */
+function brainFor(job) {
+  const out = {};
+  const model = typeof job?.model === 'string' ? job.model.trim() : '';
+  if (model && WORK_MODEL_RE.test(model)) out.model = model;
+  const effort = typeof job?.effort === 'string' ? job.effort.trim() : '';
+  if (effort && WORK_EFFORTS.has(effort)) out.effort = effort;
+  return out;
+}
+
 export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLeaseTtl }) {
   const WORK_TOKEN_URL = FLEET_URL.replace(/\/agents\/?$/, '/work-token');
   const WORK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/work-turn-done');
   const SHIP_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/ship-done');
+  const ACTIVITY_URL = FLEET_URL.replace(/\/agents\/?$/, '/session-activity');
+  const WORKTREES_URL = FLEET_URL.replace(/\/agents\/?$/, '/session-worktrees');
   const workAnswering = new Set(); // turn ids currently queued/running here
   const workAttempts = new Map(); // turn id -> completed runTurn attempts
   const MAX_WORK_TRIES = 3;
@@ -129,6 +171,144 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     else pendingShipReports.delete(sessionId);
     return r;
   };
+  /**
+   * THE TAB'S LIVE NARRATION — the terminal's own stdout, relayed.
+   *
+   * A turn used to be a spinner: the tab said "working…" for minutes and the
+   * only thing that ever appeared was the finished reply. The CLI is printing
+   * the whole time (thinking, reads, greps, commands), so the honest fix is to
+   * FORWARD that, not to invent a progress model on the server. Flowviant
+   * relays; it does not narrate on its own behalf.
+   *
+   * Best-effort by construction: throttled to one POST per window (a turn can
+   * emit hundreds of lines), never awaited by the turn, and every failure is
+   * swallowed. A spinner must never be able to fail a build. The server clears
+   * the line at settle, so a daemon killed mid-turn cannot leave one stuck.
+   */
+  const ACTIVITY_MIN_MS = 1_500;
+  const ACTIVITY_KEEP = 4; // the last few lines — a tail, not a log
+  const makeNarrator = (sessionId) => {
+    const recent = [];
+    let lastSent = 0;
+    let dirty = false;
+    let timer = null;
+    let sending = false;
+    let stopped = false;
+    const send = async () => {
+      if (sending || stopped) return;
+      sending = true;
+      dirty = false;
+      lastSent = Date.now();
+      const lines = recent.slice(-ACTIVITY_KEEP);
+      try {
+        await fetch(ACTIVITY_URL, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${FLEET_TOKEN}`,
+            'User-Agent': USER_AGENT,
+            'Content-Type': 'application/json',
+          },
+          signal: AbortSignal.timeout(10_000),
+          body: JSON.stringify({ sessionId, lines }),
+        });
+      } catch {
+        /* narration is decoration — a dropped line is not an incident */
+      }
+      sending = false;
+      if (dirty && !stopped) schedule();
+    };
+    const schedule = () => {
+      if (timer || stopped) return;
+      const wait = Math.max(0, ACTIVITY_MIN_MS - (Date.now() - lastSent));
+      timer = setTimeout(() => {
+        timer = null;
+        void send();
+      }, wait);
+      timer.unref?.(); // never hold the process open for a spinner
+    };
+    return {
+      line(label) {
+        const s = String(label ?? '')
+          .replace(/\s+/g, ' ')
+          .trim()
+          .slice(0, 200);
+        if (!s || stopped) return;
+        recent.push(s);
+        if (recent.length > ACTIVITY_KEEP * 2) recent.shift();
+        dirty = true;
+        schedule();
+      },
+      stop() {
+        stopped = true;
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      },
+    };
+  };
+
+  /**
+   * WHERE EACH TAB IS STANDING, and what it holds — the readout a human would
+   * get by running `git status` in the session's directory, which is the one
+   * thing they cannot do from a browser.
+   *
+   * Two triggers, both cheap: right after a turn settles (the moment the diff
+   * changed) and a throttled sweep over every live session (a human editing in
+   * the worktree, a build writing files, a ship landing). Best-effort like the
+   * narrator: never awaited by a turn, every failure swallowed.
+   */
+  const WORKTREE_SWEEP_MS = 60_000;
+  let lastWorktreeSweep = 0;
+  let sweepingWorktrees = false;
+  const postWorktrees = async (reports) => {
+    if (!reports.length) return;
+    try {
+      await fetch(WORKTREES_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(20_000),
+        body: JSON.stringify({ reports }),
+      });
+    } catch {
+      /* a readout — the next sweep carries it */
+    }
+  };
+  const sessionWorktreeReport = (sessionId) => {
+    if (!isSafePathSegment(sessionId)) return null;
+    const d = worktreeDiff(join(baseDir, 'sessions', sessionId), baseRef);
+    return d ? { sessionId, ...d } : null;
+  };
+  /** One session, now — called after its turn settles. */
+  const reportSessionWorktree = async (sessionId) => {
+    const r = sessionWorktreeReport(sessionId);
+    if (r) await postWorktrees([r]);
+  };
+  /** Every live session, throttled — called from the reconcile loop. */
+  const reportWorktrees = (activeIds) => {
+    if (!Array.isArray(activeIds) || activeIds.length === 0) return;
+    if (sweepingWorktrees) return;
+    if (Date.now() - lastWorktreeSweep < WORKTREE_SWEEP_MS) return;
+    sweepingWorktrees = true;
+    lastWorktreeSweep = Date.now();
+    void (async () => {
+      try {
+        const reports = [];
+        for (const id of activeIds.slice(0, 20)) {
+          const r = sessionWorktreeReport(id);
+          if (r) reports.push(r);
+        }
+        await postWorktrees(reports);
+      } finally {
+        sweepingWorktrees = false;
+      }
+    })();
+  };
+
   let flushingReports = false;
   const flushWorkReports = async () => {
     if (flushingReports) return;
@@ -879,12 +1059,17 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
           const mcp = plainTab
             ? { args: [], env: null, dir: null }
             : mcpFor(rt.id, mint.token, getMcpUrl());
+          // The tab's model/effort, if it named any. Spread into turnArgs so
+          // BOTH runTurn calls below carry it — the retry is the same turn on
+          // the same brain, not a quieter second opinion.
+          const brain = brainFor(job);
           // Attempts count RUNS: the infra refusals above consumed nothing and
           // settled on their own terms.
           workAttempts.set(job.id, tries + 1);
           let out;
           let seenThreadId = null; // codex's conversation id, off thread.started
           const spawned = []; // this turn's children, for the teardown registry
+          const narrator = makeNarrator(job.sessionId);
           try {
             const message = [job.body, adoptNote, carryNote].filter(Boolean).join('\n\n');
             const turnArgs = {
@@ -908,6 +1093,16 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
               // ordinary --continue resume path, unchanged.
               ...(adopting ? { adoptResumeId: job.adopt.id } : {}),
               system: plainTab ? SYSTEM_WORK_PLAIN : SYSTEM_WORK,
+              // Present only when the tab named one — see brainFor.
+              ...brain,
+              // The tab watches the CLI work. Claude needs the flag to speak
+              // events at all (codex and agy always do); `answerFromResult`
+              // keeps `out` — which IS the reply posted to the transcript — to
+              // the final result, so streamed prose is narrated once and
+              // posted once. Every line goes to the narrator above, throttled.
+              streamJson: true,
+              answerFromResult: true,
+              onActivity: (a) => narrator.line(a?.label),
               cwd: dir.wt,
               mcpArgs: mcp.args,
               mcpEnv: mcp.env,
@@ -953,6 +1148,10 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
             if (!adopting && resume && !(out || '').trim())
               out = await runTurn({ ...turnArgs, resume: false });
           } finally {
+            // The CLI has stopped printing, so stop relaying. The LINE itself
+            // is cleared server-side at settle — clearing it here would race
+            // the settle and blank the tab a beat before the reply lands.
+            narrator.stop();
             for (const ch of spawned) workChildren.delete(ch);
             if (lockPath) {
               try {
@@ -1038,6 +1237,12 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
           warn(`session turn failed: ${e?.message ?? e}`);
         } finally {
           workAnswering.delete(job.id);
+          // The turn just changed the directory — say what it looks like now,
+          // whether it succeeded or blew up (a failed turn can still have
+          // written half a file, and the tab should show that honestly). NOT
+          // awaited: this runs inside the session's chain, and a slow POST
+          // would delay the next turn of that tab behind a readout.
+          void reportSessionWorktree(job.sessionId).catch(() => {});
         }
       });
     }
@@ -1375,5 +1580,12 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     }
   };
 
-  return { flushWorkReports, processWorkTurns, processShipJobs, retireWorkSessions, shutdownWork };
+  return {
+    flushWorkReports,
+    processWorkTurns,
+    processShipJobs,
+    retireWorkSessions,
+    reportWorktrees,
+    shutdownWork,
+  };
 }

package/bin/lib/worktreeDiff.mjs

@@ -0,0 +1,147 @@
+/**
+ * What a session's worktree actually holds, measured — not guessed.
+ *
+ * A Workbench tab IS a directory on this machine, on its own `session/<id>`
+ * branch, and the human driving it from a browser cannot run `git status` in
+ * it. So the daemon runs it for them: the branch, how far ahead of base it is,
+ * and the per-file diffstat — the same numbers `git diff --stat` prints in that
+ * directory, relayed rather than interpreted.
+ *
+ * Measured against the MERGE-BASE with the project's base ref, and against the
+ * WORKING TREE rather than HEAD, so one number answers the question a human
+ * actually asks ("what has this session changed?") with committed and
+ * uncommitted work in the same total. Untracked files count too: git calls them
+ * nothing until they are added, and a human calls them new work.
+ *
+ * Everything here is best-effort and read-only. A worktree mid-rebase, a
+ * deleted directory, a file that vanished between listing and reading — each
+ * degrades to a smaller answer, never to a thrown error. Nothing about a
+ * readout is worth failing a turn over.
+ */
+
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { git } from './git.mjs';
+
+/** Rows reported. The rail shows a handful; the totals below cover the rest. */
+const MAX_FILES = 20;
+/** Untracked paths we are willing to open. A stray build directory that isn't
+ *  gitignored must not turn a 60-second sweep into a disk crawl. */
+const MAX_UNTRACKED_SCAN = 200;
+/** Past this we call a file binary rather than counting its lines. */
+const MAX_COUNT_BYTES = 512 * 1024;
+
+/** Lines in a buffer, the way a diff counts them: a trailing newline does not
+ *  add a line, and a NUL byte anywhere means we are not looking at text. */
+function countLines(buf) {
+  if (buf.includes(0)) return null; // binary — git's own heuristic
+  const s = buf.toString('utf8');
+  if (s === '') return 0;
+  const n = s.split('\n').length;
+  return s.endsWith('\n') ? n - 1 : n;
+}
+
+/**
+ * @param {string} wt   the worktree directory
+ * @param {string} baseRef  the project's base ref (e.g. `origin/main`)
+ * @returns {null | {branch:string, path:string, ahead:number, dirty:boolean,
+ *   additions:number, deletions:number, fileCount:number, truncated:number,
+ *   files:{path:string, added:number, deleted:number, binary?:boolean}[]}}
+ */
+export function worktreeDiff(wt, baseRef) {
+  if (!wt || !existsSync(wt)) return null;
+  let branch = '';
+  try {
+    branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], wt);
+  } catch {
+    return null; // not a worktree (or not readable) — report nothing, not zeros
+  }
+  let base = '';
+  try {
+    base = git(['merge-base', 'HEAD', baseRef], wt);
+  } catch {
+    /* a branch with no common ancestor (or an unfetched base) — fall back to
+       HEAD below, which still reports the uncommitted half honestly */
+  }
+
+  const files = [];
+  let additions = 0;
+  let deletions = 0;
+  const push = (path, added, deleted, binary = false) => {
+    if (!path) return;
+    files.push(binary ? { path, added, deleted, binary } : { path, added, deleted });
+    additions += added;
+    deletions += deleted;
+  };
+
+  // Tracked: working tree vs base. `git diff <base>` (no --cached, no second
+  // ref) is exactly "everything this session did", committed or not.
+  try {
+    const raw = git(['diff', '--numstat', base || 'HEAD'], wt);
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      const [a, d, ...rest] = line.split('\t');
+      const path = rest.join('\t');
+      const binary = a === '-' || d === '-';
+      push(path, binary ? 0 : Number(a) || 0, binary ? 0 : Number(d) || 0, binary);
+    }
+  } catch {
+    /* report what we have */
+  }
+
+  // Untracked, minus everything gitignored — new files are the most visible
+  // work a session does and they would otherwise show as nothing at all.
+  try {
+    const others = git(['ls-files', '--others', '--exclude-standard'], wt)
+      .split('\n')
+      .filter(Boolean);
+    for (const path of others.slice(0, MAX_UNTRACKED_SCAN)) {
+      try {
+        const full = join(wt, path);
+        const st = statSync(full);
+        if (!st.isFile()) continue;
+        if (st.size > MAX_COUNT_BYTES) {
+          push(path, 0, 0, true);
+          continue;
+        }
+        const lines = countLines(readFileSync(full));
+        if (lines === null) push(path, 0, 0, true);
+        else push(path, lines, 0);
+      } catch {
+        /* vanished between listing and reading — it wasn't there to report */
+      }
+    }
+  } catch {
+    /* report what we have */
+  }
+
+  let ahead = 0;
+  try {
+    if (base) ahead = Number(git(['rev-list', '--count', `${base}..HEAD`], wt)) || 0;
+  } catch {
+    /* leave at 0 */
+  }
+  let dirty = false;
+  try {
+    dirty = git(['status', '--porcelain'], wt) !== '';
+  } catch {
+    /* leave at false */
+  }
+
+  // Biggest first: with a 20-row cap, the rows that survive should be the ones
+  // worth looking at. Ties break by path so the list doesn't shuffle per sweep.
+  files.sort(
+    (x, y) => y.added + y.deleted - (x.added + x.deleted) || (x.path < y.path ? -1 : 1)
+  );
+  return {
+    branch,
+    path: wt,
+    ahead,
+    dirty,
+    additions,
+    deletions,
+    fileCount: files.length,
+    truncated: Math.max(0, files.length - MAX_FILES),
+    files: files.slice(0, MAX_FILES),
+  };
+}

package/package.json

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