flowviant 0.103.0 → 0.104.0

package/bin/lib/claudeSessions.mjs

@@ -0,0 +1,411 @@
+/**
+ * CLAUDE CODE'S SESSION PRESENCE, read off its own on-disk state (split out of
+ * localSessions.mjs 2026-09-26, SOLID F062). The liveness registry
+ * (~/.claude/sessions/<pid>.json) says what is open right now, and the
+ * transcript store (~/.claude/projects/<munged-cwd>/<id>.jsonl) says what was.
+ * A Claude transcript-format change lands here; the Antigravity reader is
+ * agySessions.mjs and the shared fence and report cap are the coordinator's
+ * (localSessions.mjs).
+ *
+ * NOTHING in this file throws: a torn registry file or a vanished cwd is a
+ * session to skip, not an error to raise.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  openSync,
+  readSync,
+  closeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// ENDED sessions are the adoptable inventory, and the useful ones are FRESH:
+// newest per directory, few. (The window itself is the coordinator's.)
+const ENDED_CAP = 5;
+
+/**
+ * The conversation's own title, off the transcript's `ai-title` records
+ * (the LAST one wins — titles get rewritten as a session evolves), and ONLY
+ * those records: this wire is presence METADATA, and the first user message
+ * — the fallback this used to relay — is transcript CONTENT wearing a
+ * title's clothes. An untitled row is honest presence; a quoted message is
+ * a leak. Those records sit anywhere in the file (measured: line 81 to line
+ * 4457), so this reads the WHOLE transcript — behind an mtime cache, because
+ * the scan runs every minute and a title only changes when the file does:
+ * steady state is a stat, not a read.
+ */
+const titleCache = new Map(); // file → { mtimeMs, title }
+function transcriptTitle(file, mtimeMs) {
+  const hit = titleCache.get(file);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.title;
+  let title = null;
+  try {
+    const stat = statSync(file);
+    // A transcript past this is not worth a read per minute of drift.
+    if (stat.size <= 64 * 1024 * 1024) {
+      for (const line of readFileSync(file, 'utf8').split('\n')) {
+        if (!line.includes('"type":"ai-title"')) continue;
+        try {
+          const t = JSON.parse(line)?.aiTitle;
+          if (typeof t === 'string' && t.trim()) title = t.trim(); // last wins
+        } catch {
+          /* torn line */
+        }
+      }
+      if (title) title = title.replace(/\s+/g, ' ').slice(0, 120);
+    }
+  } catch {
+    title = null;
+  }
+  if (titleCache.size > 400) titleCache.clear(); // a bound, not an LRU — refills in one scan
+  titleCache.set(file, { mtimeMs, title });
+  return title;
+}
+
+/**
+ * THE TITLE CLAUDE GAVE ITS OWN CONVERSATION, for one session we already know
+ * the id of.
+ *
+ * `scanLocalSessions` finds transcripts the hard way — walk every project
+ * directory, read each file's own `cwd` — because it is answering "what is in
+ * this repo" and knows no ids. This asks the same store a narrower question:
+ * the tab pinned the id the CLI reported at `system.init`, and the directory is
+ * the place the turn was spawned in, so the file is one munge away (Claude Code
+ * names the directory after the cwd with `/` and `.` replaced by `-`).
+ *
+ * The realpath fallback is not defensive padding: a place under a symlinked
+ * home munges to a DIFFERENT directory name depending on which form the CLI was
+ * handed, and the daemon does not control which that was.
+ *
+ * Returns null for anything it cannot read. A missing title is honest silence —
+ * the tab keeps whatever name it has.
+ */
+export function titleForSession(cwd, sessionId) {
+  if (!cwd || typeof sessionId !== 'string' || !/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) {
+    return null;
+  }
+  const projects = join(homedir(), '.claude', 'projects');
+  const dirs = [String(cwd)];
+  try {
+    const real = realpathSync(String(cwd));
+    if (real !== String(cwd)) dirs.push(real);
+  } catch {
+    /* the place is gone — nothing to read */
+  }
+  for (const dir of dirs) {
+    const file = join(projects, claudeProjectDir(dir), `${sessionId}.jsonl`);
+    try {
+      return transcriptTitle(file, statSync(file).mtimeMs);
+    } catch {
+      /* not this munge — try the other */
+    }
+  }
+  return null;
+}
+
+/**
+ * THE DIRECTORY CLAUDE CODE FILES A CWD'S TRANSCRIPTS UNDER — its own rule,
+ * copied exactly (2.1.281): every character that is not an ASCII letter or
+ * digit becomes `-`, and a name past 200 characters is cut there and suffixed
+ * with a base-36 Java-style string hash of the ORIGINAL path.
+ *
+ * This file used `replace(/[/.]/g, '-')`, which agrees with Claude Code only
+ * while a path holds nothing but letters, digits, `/` and `.` — so a repo at
+ * `~/code/my_app` or `~/My Projects/x` never offered an ended terminal session
+ * for adoption and never got a tab auto-title, silently (audit 2026-09-24).
+ */
+const CLAUDE_DIR_MAX = 200;
+export function claudeProjectDir(path) {
+  const p = String(path);
+  const s = p.replace(/[^a-zA-Z0-9]/g, '-');
+  if (s.length <= CLAUDE_DIR_MAX) return s;
+  let h = 0;
+  for (let i = 0; i < p.length; i++) h = ((h << 5) - h + p.charCodeAt(i)) | 0;
+  return `${s.slice(0, CLAUDE_DIR_MAX)}-${Math.abs(h).toString(36)}`;
+}
+
+/**
+ * Is this pid the SAME process the registry entry recorded?
+ *
+ * Registry entries go stale — Claude exits, the pid is recycled by something
+ * else, the file stays. `/proc/<pid>` existing only proves A process; the
+ * starttime (field 22 of /proc/<pid>/stat) proves it is THAT process. The comm
+ * field (parenthesised, may itself contain spaces and parens) makes naive
+ * whitespace-splitting wrong, so fields are counted from after the LAST ')':
+ * the first post-comm field is field 3, which puts starttime at index 19.
+ */
+function pidAlive(pid, procStart) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  let stat;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+  } catch {
+    // No /proc ENTRY means the process is gone — but only where /proc exists
+    // at all. On macOS there is no /proc, so this read fails for EVERY pid,
+    // every session scans as dead, and live sessions become adoptable — the
+    // exact two-drivers-on-one-conversation outcome liveness exists to
+    // prevent. Probe by name instead: `ps -o comm=` on the pid, alive only if
+    // the surviving process still LOOKS like a coding-CLI process. A bare
+    // signal-0 probe was tried first and reads a RECYCLED pid as alive
+    // forever — a crashed session whose pid a launchd service inherited would
+    // report live for weeks, refuse adoption, and suppress its own ended row.
+    // The name check keeps the conservative direction (a transient race still
+    // errs live) without the permanent false-live.
+    if (!existsSync('/proc')) {
+      try {
+        const comm = execFileSync('ps', ['-o', 'comm=', '-p', String(pid)], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 5_000,
+        })
+          .trim()
+          .toLowerCase();
+        return /\b(claude|node|bun|codex|agy)\b|\/(claude|node|bun|codex|agy)$/.test(comm);
+      } catch {
+        return false; // ps errored or the pid is gone — the process is dead
+      }
+    }
+    return false; // /proc is real and has no entry — the process is gone
+  }
+  if (procStart == null) return true; // nothing recorded to compare against
+  const close = stat.lastIndexOf(')');
+  if (close === -1) return false;
+  const fields = stat.slice(close + 1).trim().split(/\s+/);
+  return fields[19] === String(procStart);
+}
+
+/**
+ * Is a terminal Claude session with this id open on the machine RIGHT NOW?
+ *
+ * The adoption path asks this at the moment of adopting: forking a session
+ * while its terminal is still typing into it would put two Claudes on one
+ * conversation, which is the exact incoherence the Workbench's own locks
+ * exist to prevent.
+ */
+export function isTerminalSessionLive(sessionId) {
+  try {
+    const dir = join(homedir(), '.claude', 'sessions');
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      let rec;
+      try {
+        rec = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+      } catch {
+        continue; // torn write / not JSON — not evidence of anything
+      }
+      if (rec?.sessionId !== sessionId) continue;
+      if (pidAlive(rec.pid, rec.procStart)) return true;
+    }
+  } catch {
+    /* registry unreadable — no proof of life is "not live" */
+  }
+  return false;
+}
+
+/**
+ * First transcript record that carries a cwd, from the file's head only.
+ *
+ * A transcript can be megabytes; the cwd/gitBranch identity rides on every
+ * record, so ~16KB from the front is enough to verify WHOSE session this is
+ * without paying to read the conversation. A file whose first cwd-bearing
+ * line does not parse (truncated at the window edge) is skipped, not retried
+ * deeper — this is presence, not forensics.
+ */
+function firstCwdRecord(file) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(16384);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    for (const line of buf.subarray(0, n).toString('utf8').split('\n')) {
+      if (!line.includes('"cwd":"')) continue;
+      try {
+        const rec = JSON.parse(line);
+        if (rec && typeof rec.cwd === 'string' && rec.cwd) return rec;
+      } catch {
+        /* an incomplete line at the window edge — try the next candidate */
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+}
+
+/**
+ * Every Claude terminal session belonging to this repo: LIVE ones from the
+ * liveness registry, ENDED ones from the transcript store. Returns
+ * [{ id, cwd, live, lastActiveAt, branch?, title? }], live first, then newest
+ * ended, capped at `cap`, deterministically ordered (so a stringified report
+ * only changes when the facts do).
+ *
+ * The coordinator (localSessions.mjs) hands over the fence: `realRoot`, the
+ * `ours(path)` containment test with the daemon's worktrees carved out, the
+ * `mine` id set (our own tabs), and the ended-session `cutoff`.
+ */
+export function scanClaudeSessions({ realRoot, ours, mine, cutoff, cap }) {
+  const live = [];
+  const ended = [];
+  try {
+    // ── LIVE: the registry, validated pid by pid ─────────────────────────
+    const nowIso = new Date().toISOString();
+    const liveIds = new Set();
+    let regNames = [];
+    try {
+      regNames = readdirSync(join(homedir(), '.claude', 'sessions'));
+    } catch {
+      /* no registry — no live sessions */
+    }
+    for (const name of regNames) {
+      if (!name.endsWith('.json')) continue; // .key files ride alongside
+      let rec;
+      try {
+        rec = JSON.parse(readFileSync(join(homedir(), '.claude', 'sessions', name), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!rec || typeof rec.sessionId !== 'string' || typeof rec.cwd !== 'string') continue;
+      if (liveIds.has(rec.sessionId)) continue;
+      if (!pidAlive(rec.pid, rec.procStart)) continue;
+      let cwd;
+      try {
+        cwd = realpathSync(rec.cwd);
+      } catch {
+        continue; // the directory is gone — nothing to point a tab at
+      }
+      if (!ours(cwd)) continue;
+      liveIds.add(rec.sessionId);
+      // A live session's title, off its own transcript (the registry `name`
+      // is a machine-y fallback like "flowviant-35").
+      let liveTitle = null;
+      try {
+        const liveFile = join(
+          homedir(),
+          '.claude',
+          'projects',
+          claudeProjectDir(cwd),
+          `${rec.sessionId}.jsonl`
+        );
+        liveTitle = transcriptTitle(liveFile, statSync(liveFile).mtimeMs);
+      } catch {
+        /* no transcript yet */
+      }
+      if (!liveTitle && typeof rec.name === 'string' && rec.name.trim()) liveTitle = rec.name.trim();
+      if (mine.has(rec.sessionId)) continue; // our own tab, not a terminal session
+      live.push({
+        id: rec.sessionId,
+        cwd,
+        live: true,
+        lastActiveAt: nowIso,
+        ...(typeof rec.gitBranch === 'string' && rec.gitBranch ? { branch: rec.gitBranch } : {}),
+        ...(liveTitle ? { title: liveTitle } : {}),
+      });
+    }
+    live.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+    // ── ENDED: the transcript store, verified file by file ───────────────
+    //
+    // The munged directory name is a PREFIX match on purpose: a session run in
+    // a SUBDIRECTORY of the repo munges to a longer name sharing the root's.
+    // But so does a sibling repo ('flowviant-two' shares 'flowviant' + '-'),
+    // which is why every candidate is verified against the cwd its own records
+    // embed rather than trusted on its directory name.
+    const munged = claudeProjectDir(realRoot);
+    // A root past Claude's 200-character cut carries a hash of ITSELF, which a
+    // subdirectory's name does not share — so the prefix a subdirectory can
+    // match is the cut, and the cwd verification below does the rest.
+    const mungedStem = munged.length > CLAUDE_DIR_MAX ? munged.slice(0, CLAUDE_DIR_MAX) : `${munged}-`;
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    let projDirs = [];
+    try {
+      projDirs = readdirSync(projectsDir);
+    } catch {
+      /* no transcript store — live sessions still report */
+    }
+    const candidates = [];
+    for (const dirName of projDirs) {
+      if (dirName !== munged && !dirName.startsWith(mungedStem)) continue;
+      let entries = [];
+      try {
+        entries = readdirSync(join(projectsDir, dirName), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const ent of entries) {
+        if (!ent.isFile() || !ent.name.endsWith('.jsonl')) continue; // top-level only
+        const id = ent.name.slice(0, -'.jsonl'.length);
+        if (!id || liveIds.has(id)) continue; // a live session outranks its own transcript
+        const file = join(projectsDir, dirName, ent.name);
+        let mtimeMs;
+        try {
+          mtimeMs = statSync(file).mtimeMs;
+        } catch {
+          continue;
+        }
+        if (mtimeMs < cutoff) continue; // an aged session is history, not presence
+        candidates.push({ id, file, mtimeMs });
+      }
+    }
+    // Newest first, then verify only as many as the cap still has room for —
+    // the verification read is the expensive step, so it is not spent on
+    // sessions the report would drop anyway.
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.id < b.id ? -1 : 1));
+    // ONE row per DIRECTORY, newest first, few: twenty sessions in the repo
+    // root are one offer — the newest is the one `--resume`'s picker would
+    // reach for and the only one worth importing 95% of the time. The rest
+    // are scrollback, and the product's own law says scrollback doesn't
+    // matter.
+    const room = Math.min(ENDED_CAP, Math.max(0, cap - Math.min(live.length, cap)));
+    const endedIds = new Set();
+    const seenCwds = new Set(live.map((s) => s.cwd));
+    for (const cand of candidates) {
+      if (ended.length >= room) break;
+      if (endedIds.has(cand.id)) continue; // one row per session, whatever dir names it
+      endedIds.add(cand.id);
+      const rec = firstCwdRecord(cand.file);
+      if (!rec) continue;
+      let cwd;
+      try {
+        cwd = realpathSync(rec.cwd);
+      } catch {
+        continue;
+      }
+      if (!ours(cwd)) continue;
+      /**
+       * OUR OWN TAB IS NOT A CANDIDATE, and it is skipped BEFORE `seenCwds`
+       * claims the directory — otherwise the daemon's transcript (always the
+       * freshest thing in the checkout) took the one slot that directory gets
+       * and a genuine terminal session there could never be offered at all.
+       */
+      if (mine.has(cand.id)) continue;
+      if (seenCwds.has(cwd)) continue; // newest per directory; a live one owns its cwd
+      seenCwds.add(cwd);
+      const title = transcriptTitle(cand.file, cand.mtimeMs);
+      ended.push({
+        id: cand.id,
+        cwd,
+        live: false,
+        lastActiveAt: new Date(cand.mtimeMs).toISOString(),
+        ...(typeof rec.gitBranch === 'string' && rec.gitBranch ? { branch: rec.gitBranch } : {}),
+        ...(title ? { title } : {}),
+      });
+    }
+  } catch {
+    /* presence must never throw into the poll loop — report what was gathered */
+  }
+  return [...live.slice(0, cap), ...ended];
+}

package/bin/lib/claudeStream.mjs

@@ -0,0 +1,207 @@
+/**
+ * CLAUDE CODE'S EVENT STREAM, READ — one line of `--output-format stream-json`
+ * into feed activities, the answer text, the init facts and the turn's tokens.
+ *
+ * Split out of claude.mjs (SOLID 2026-09-26) because it changes when the CLI's
+ * event schema changes, which is a different reason from a permission list or
+ * a process's lifetime. Codex's and agy's readers, and the Claude tool
+ * humanizers this loop calls, live in runtimeEvents.mjs; this is the stream
+ * loop Claude's `parse: null` means.
+ */
+
+import { humanizeClaudeTool, THINK_MARKER } from './runtimeEvents.mjs';
+
+// Turn one Claude tool_use into a compact activity {kind, label}, or null for
+// tools not worth surfacing. `kind:'read'` is what the file counter counts; a
+// Write/Edit of a vault page is the "writing" signal. Used by wiki turns to
+// stream exactly which files Claude is touching (daemon console + app cover).
+//
+// The body moved to runtimeEvents.mjs, beside Codex's equivalent, because they are
+// the same job for two vendors and keeping them apart is how the two activity
+// vocabularies drift. Re-exported under its original name: a dozen call sites
+// know it, and none of them care where it lives.
+export const humanizeToolUse = humanizeClaudeTool;
+
+// Collapse whitespace + clip so a narration/thinking snippet is one tidy feed line.
+const oneLine = (s, n = 160) => String(s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+/**
+ * WHAT THIS TURN COST, IN THE CLI'S OWN NUMBERS (2026-09-19).
+ *
+ * The `result` event carries a `usage` object — `input_tokens`,
+ * `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` —
+ * and this reads exactly those four and nothing else. A RELAY: nothing here
+ * derives, estimates or prices anything.
+ *
+ * DELIBERATELY NOT `total_cost_usd`, which rides the same event. It is a
+ * notional list price that a subscription operator did not pay, so relaying it
+ * as "cost" would be the product asserting a figure nobody was charged — the
+ * refusal the board's fix pass already made once against the mock's "1.4
+ * spent". Tokens are measured; dollars are not.
+ *
+ * COERCED AND FLOORED, never trusted: a non-number, a NaN, an Infinity or a
+ * negative reads as 0, because these are summed into a counter that only ever
+ * goes up and one bad field must not poison the other three.
+ *
+ * Returns null when there is no usage object at all — the three-state rule
+ * every readout here keeps: a turn that reported nothing charges nothing, and
+ * that is not the same as a turn that reported zeros.
+ */
+export function usageFromResult(ev) {
+  const u = ev?.usage;
+  if (!u || typeof u !== 'object') return null;
+  const n = (v) => {
+    const x = Number(v);
+    return Number.isFinite(x) && x > 0 ? Math.floor(x) : 0;
+  };
+  return {
+    input: n(u.input_tokens),
+    output: n(u.output_tokens),
+    cacheCreate: n(u.cache_creation_input_tokens),
+    cacheRead: n(u.cache_read_input_tokens),
+  };
+}
+
+// Parse ONE line of `--output-format stream-json` NDJSON into feed activities.
+// Surfaces the WHOLE turn — thinking, narration, AND every tool — so neither the
+// daemon console nor the app cover goes dark while Claude reasons (Opus thinks in
+// 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.
+//
+// `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.
+//
+// EXPORTED FOR ITS TEST ONLY (2026-09-19), and the reason is worth stating: the
+// `onUsage` threading through this function, `runTurn`'s options and `onLine`
+// was four edits and NOT ONE of them was reachable from either suite — delete
+// any one and both stay green, while the only symptom in production is a
+// container that reports no spend, which is indistinguishable from an older
+// daemon by design. A callback that is silent when it breaks has to be called
+// directly by something.
+export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage }) {
+  let ev;
+  try {
+    ev = JSON.parse(line);
+  } catch {
+    appendText(line + '\n');
+    emit(line + '\n');
+    return;
+  }
+  const push = (a) => {
+    if (!a || !a.label) return;
+    emit(a.label + '\n');
+    onActivity?.(a);
+  };
+  if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
+    for (const b of ev.message.content) {
+      if (b.type === 'thinking' || b.type === 'redacted_thinking') {
+        /**
+         * NO THINKING TEXT ARRIVES TODAY, AND THAT IS MEASURED (2026-09-16).
+         *
+         * This used to say the text is "usually redacted", which was a guess
+         * doing the work of a fact. The fact: across three real transcripts, 93
+         * thinking blocks, EVERY ONE of them carried an empty `thinking` — and
+         * a live probe with MAX_THINKING_TOKENS set and
+         * `--include-partial-messages` on returned an empty `thinking_delta`
+         * and a complete block of length zero (signature only). So the CLI
+         * emits the FACT that it reasoned and not a word of the reasoning, and
+         * "show the full thinking" cannot be conjured from this stream.
+         *
+         * THE BRANCH BELOW EXISTS ANYWAY, and deliberately. The shape is the
+         * whole point: when text is present it rides `full` UNCLIPPED, so the
+         * day a CLI release starts emitting it, the trace carries the thought
+         * whole with no daemon change and no version floor — the report's own
+         * presence is the capability. Until then every block takes the marker
+         * arm, and `trace.mjs` collapses a run of identical markers so the
+         * absence reads as one quiet step rather than forty.
+         */
+        push(
+          b.thinking
+            ? { kind: 'think', label: `thinking: ${oneLine(b.thinking)}`, full: b.thinking }
+            : { kind: 'think', label: THINK_MARKER }
+        );
+      } else if (b.type === 'text' && b.text?.trim()) {
+        if (!answerFromResult) appendText(b.text + '\n');
+        // `label` for the console and the pulse — one collapsed 160-char line,
+        // byte-identical to what it has always printed. `full` for the trace:
+        // a `say` is the agent NARRATING, several sentences at a time, and the
+        // clip at 160 was landing mid-sentence on the one thing a person opens
+        // the page to read.
+        push({ kind: 'say', label: oneLine(b.text), full: b.text });
+      } else if (b.type === 'tool_use') {
+        push(humanizeToolUse(b.name, b.input || {}, cwd));
+        // The STRUCTURED form of the same event, for the transcript's tool
+        // cards — raw name + input, so the collector can keep what the
+        // one-line humanizer drops (an Edit's counts, the plan's items).
+        onToolEvent?.(b.name, b.input || {});
+      }
+    }
+  } else if (ev.type === 'system' && ev.subtype === 'init') {
+    // WHAT THIS MACHINE'S CLI CAN BE ASKED FOR BY NAME. The init event is the
+    // CLI's OWN answer — it has already resolved personal skills, this repo's
+    // skills, plugins and whatever the project settings enable or disable — so
+    // reading it costs nothing and cannot drift the way a `~/.claude/skills`
+    // scan of our own would. `skills` (rather than `slash_commands`) is the
+    // deliberate narrowing: the 50-odd commands beside it are the CLI's own
+    // interactive furniture (/clear, /model, /compact), and offering those in a
+    // relayed tab would be an offer wired to nothing.
+    //
+    // Only ever REPORTED, never enforced. Flowviant does not decide what your
+    // Claude can do; it relays what your Claude said it has.
+    // `sessionId` rides along for one reason: a `-p` turn WRITES a transcript,
+    // and `claudeSessions.mjs` offers the newest ended session per directory as
+    // ADOPTABLE — so any headless turn we run for our own purposes would leave
+    // a phantom untitled session in the `+` menu. The caller that needs to
+    // clean up after itself cannot do so without this id.
+    //
+    // `mcpServers` (0.97.0) is the same kind of fact from the same event: the
+    // MCP servers and claude.ai connectors the CLI mounted, each with its own
+    // status (`needs-auth` above all — a sign-in that has to happen at this
+    // box). Relayed raw; `recordMcpServers` (runtimeCapabilities.mjs) normalises it and
+    // drops this daemon's own `flowviant` server.
+    if (Array.isArray(ev.skills) || typeof ev.session_id === 'string' || Array.isArray(ev.mcp_servers)) {
+      onInit?.({
+        skills: Array.isArray(ev.skills) ? ev.skills.map(String) : undefined,
+        sessionId: typeof ev.session_id === 'string' ? ev.session_id : undefined,
+        mcpServers: Array.isArray(ev.mcp_servers) ? ev.mcp_servers : undefined,
+      });
+    }
+  } else if (ev.type === 'result') {
+    /**
+     * WHAT THE TURN SPENT, BEFORE ANYTHING ELSE IN THIS BRANCH.
+     *
+     * FIRED ON A FAILED RESULT TOO, and that ordering is the point: a turn that
+     * hit a limit, ran out of permission or aborted still sent the requests it
+     * sent, and a spend readout that quietly skipped every unhappy turn would
+     * under-report exactly the runs somebody is looking at the number to
+     * understand. `usageFromResult` returns null when the event carries no
+     * usage at all, and a caller that passes no `onUsage` sees no change.
+     */
+    const usage = usageFromResult(ev);
+    if (usage) onUsage?.(usage);
+    // The final assistant text (carries WIKI_DONE / REGROUND_DONE).
+    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.
+      // `errors[]` FIRST, because it is where the real sentence is. Claude
+      // Code reports a dead `--resume` id as
+      // `{subtype:'error_during_execution', errors:['No conversation found
+      // with session ID: …']}` — reading only `error`/`subtype` dropped that
+      // and appended the literal string `error_during_execution`, which told
+      // the driver nothing and hid the one phrase the caller needs to
+      // recognise a lost conversation.
+      const listed = Array.isArray(ev.errors)
+        ? ev.errors.filter((e) => typeof e === 'string' && e.trim()).join('; ')
+        : '';
+      const msg = listed || ev.error?.message || ev.error || ev.subtype;
+      appendText(`${typeof msg === 'string' ? msg : JSON.stringify(msg)}\n`);
+    }
+  }
+}

package/bin/lib/cliLimit.mjs

@@ -0,0 +1,34 @@
+/**
+ * The CLI-limit trigger — whether a CLI's output says the account hit a
+ * usage limit, relayed in the CLI's own words. Split out of
+ * workAgentReview.mjs (SOLID F039) because two lanes read it (the agent turn,
+ * which parks on it, and the pre-review, which only skips) and neither owns
+ * it: it is a fact about what the CLIs print.
+ */
+import { scrub as envScrub } from './uplinkScrub.mjs';
+
+/**
+ * DID THE ACCOUNT HIT A LIMIT?
+ *
+ * Deliberately a LITERAL MATCH on the few sentences the CLIs actually print,
+ * and the matched line is relayed VERBATIM. It is a trigger, not a
+ * classifier: nothing here decides what an error "means" or writes a sentence
+ * of its own, because the product's own rule is that it relays and never
+ * infers. The honest limit is that a phrasing nobody listed reads as an
+ * ordinary failed turn — which lands the agent in Stuck with the CLI's words
+ * attached, and is a perfectly survivable second-best.
+ */
+const LIMIT_PHRASES = [
+  /usage limit reached/i,
+  /rate limit/i,
+  /you've reached your .* limit/i,
+  /quota exceeded/i,
+  /insufficient_quota/i,
+];
+export const limitLine = (text) => {
+  for (const line of String(text ?? '').split('\n')) {
+    const t = line.trim();
+    if (t && LIMIT_PHRASES.some((re) => re.test(t))) return envScrub(t).slice(0, 300);
+  }
+  return null;
+};