crewforth 3.1.0-rc.4 → 3.1.0-rc.6

package/kit/studio/server/lib/permissions.js

@@ -18,14 +18,74 @@ import { fileURLToPath } from 'node:url';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const HOOK = path.resolve(HERE, '..', 'hooks', 'studio-gate.sh');
+const HOST = path.resolve(HERE, '..', 'hooks', 'studio-host.mjs');
 
 // The hook answers at HOOK_WAIT; the harness is told a larger number, so the
 // two never race and the harness has nothing to kill.
 const HOOK_WAIT_S = 45;
+// A question to the viewer, and a plan to read, are not a yes-or-no on one command: they get longer. The hook still
+// answers by itself, with a denial, when this runs out.
+const ASK_WAIT_S = 300;
 const HARNESS_TIMEOUT_S = 90;
+// The longer limit is given to the harness for those two tools alone, on a hook entry of their own: every other
+// call keeps the 90 seconds it had.
+const ASK_HARNESS_TIMEOUT_S = ASK_WAIT_S + 45;
+
+// The two tools Claude Code offers only when someone can answer them. Their answer is not allow-or-deny: a
+// question is answered with the answers, a plan with the mode to go on in.
+export const INTERACTIVE = ['AskUserQuestion', 'ExitPlanMode'];
+// The modes a plan can be approved into. `plan` is not one (that is "keep planning"), and nothing else exists here.
+export const PLAN_MODES = ['acceptEdits', 'default'];
+// The name the permission host has to Claude Code, and its one tool's: mcp__<server>__<tool>. The server's name
+// carries the session's id, so it cannot be the name of a server the user's own configuration already has, and
+// two sessions' hosts are never one name.
+export function hostNames(sessionId) {
+  const server = `crew_studio_host_${String(sessionId).replace(/[^A-Za-z0-9]/g, '').slice(0, 16)}`;
+  return { server, tool: `mcp__${server}__approve` };
+}
+
+/**
+ * Is this directory ours alone? The spool holds the answers a hook acts on: a file dropped into it is an answer.
+ * It sits under the system's temporary directory, which on some systems every user can write to, so a directory
+ * of that name is not taken on trust: it must be a real directory (not a link to one), owned by this user, and
+ * closed to everyone else. One that is ours and too open is closed; one that is somebody else's is refused.
+ * Where the platform has no owner to ask about (Windows), only "a real directory" is asked.
+ * @param uid  whose it has to be: this process's user. A parameter so the rule can be asked about another one.
+ * @returns null when it is, or the reason it is not
+ */
+export function spoolProblem(dir, uid = typeof process.getuid === 'function' ? process.getuid() : null) {
+  let st;
+  try { st = fs.lstatSync(dir); } catch { return 'it does not exist'; }
+  if (st.isSymbolicLink()) return 'it is a symbolic link';
+  if (!st.isDirectory()) return 'it is not a directory';
+  if (uid === null) return null;
+  if (st.uid !== uid) return 'it belongs to another user';
+  if ((st.mode & 0o077) !== 0) {
+    try { fs.chmodSync(dir, 0o700); } catch { return 'it is open to other users and could not be closed'; }
+    if ((fs.lstatSync(dir).mode & 0o077) !== 0) return 'it is open to other users and could not be closed';
+  }
+  return null;
+}
+
+/** Make a directory that is ours alone, or say why the one that is there is not. */
+function ownDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* spoolProblem says what is there */ }
+  return spoolProblem(dir);
+}
+
+/** The spool of a session, checked each time it is about to be read or written. */
+function spoolUsable(sessionId) {
+  const spool = spoolFor(sessionId);
+  return spoolProblem(ROOT) === null && spoolProblem(spool) === null ? spool : null;
+}
 const POLL_MS = 250;
 
-const ROOT = path.join(os.tmpdir(), 'crew-studio-gate');
+// One root per user: on a machine with a shared temp directory, two users' panels do not meet in one directory.
+// Where the platform has no user id to ask for (Windows), the temp directory is already the user's own.
+const UID = typeof process.getuid === 'function' ? process.getuid() : null;
+const ROOT = path.join(os.tmpdir(), UID === null ? 'crew-studio-gate' : `crew-studio-gate-${UID}`);
+// Where spools were kept before the root carried the user: swept, never written to.
+const OLD_ROOT = path.join(os.tmpdir(), 'crew-studio-gate');
 
 export function spoolFor(sessionId) {
   if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) throw new Error('bad session id');
@@ -43,9 +103,22 @@ export function prepare(sessionId, mode = null) {
   if (!fs.existsSync(HOOK)) return null;
 
   const spool = spoolFor(sessionId);
-  for (const d of ['req', 'ans', 'always']) fs.mkdirSync(path.join(spool, d), { recursive: true });
+  // A spool that is not ours alone is not used: the session starts without a gate, and says so, rather than
+  // with one whose answers somebody else can write.
+  for (const d of [ROOT, spool, ...['req', 'ans', 'always', 'host'].map((x) => path.join(spool, x))]) {
+    const problem = ownDir(d);
+    if (problem) { prepare.refused = `${d}: ${problem}`; return null; }
+  }
+  prepare.refused = null;
+  // Whose spool this is: the server that made it. A later start reads this to tell a spool that was left behind
+  // (see `sweep`) from one a running server is still using.
+  try { fs.writeFileSync(path.join(spool, OWNER), `${process.pid}\n`, { mode: 0o600 }); } catch { /* swept by age instead */ }
+  // The mode an allowance in the panel is said out loud in. It starts as the mode the session starts in, and
+  // changes only when the viewer approves a plan into another one (see `decide`).
+  writeMode(spool, mode);
 
   const settingsPath = path.join(spool, 'settings.json');
+  const ask = (role) => `CREW_GATE_WAIT=${HOOK_WAIT_S} CREW_GATE_WAIT_ASK=${ASK_WAIT_S} CREW_GATE_ROLE=${role} ${gateMode(mode)}bash ${JSON.stringify(HOOK)} ${JSON.stringify(spool)}`;
   const settings = {
     hooks: {
       PreToolUse: [{
@@ -60,14 +133,42 @@ export function prepare(sessionId, mode = null) {
           // The mode goes to the hook so that an allowance given in the panel can be an approval the harness
           // honours — in the modes that may write, and never in plan. A mode that is not a plain word is not
           // passed at all, and the hook then approves nothing.
-          command: `CREW_GATE_WAIT=${HOOK_WAIT_S} ${gateMode(mode)}bash ${JSON.stringify(HOOK)} ${JSON.stringify(spool)}`,
+          // `general`: it answers every tool but the two below, and for those two it says nothing and leaves at
+          // once, so it is never held past this entry's limit.
+          command: ask('general'),
           timeout: HARNESS_TIMEOUT_S,
         }],
+      }, {
+        // The two tools that wait for a person to read something: the same hook, with the longer limit that only
+        // they need. If this entry did not fire for them, nothing would answer them and the permission host
+        // would deny them: the failure is a refusal.
+        matcher: INTERACTIVE.join('|'),
+        hooks: [{ type: 'command', shell: 'bash', command: ask('ask'), timeout: ASK_HARNESS_TIMEOUT_S }],
       }],
     },
   };
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-  return { settingsPath, spool, waitSeconds: HOOK_WAIT_S };
+
+  // The permission host: what makes Claude Code offer AskUserQuestion and ExitPlanMode in this session at all. It
+  // denies whatever reaches it (hooks/studio-host.mjs says why). Without the file the session starts as it did
+  // before there was one: the two tools are not offered, and nothing else changes.
+  let host = null;
+  if (fs.existsSync(HOST)) {
+    const names = hostNames(sessionId);
+    const mcpPath = path.join(spool, 'mcp.json');
+    fs.writeFileSync(mcpPath, JSON.stringify({ mcpServers: { [names.server]: { command: process.execPath, args: [HOST, spool] } } }, null, 2));
+    host = { mcpPath, tool: names.tool, server: names.server };
+  }
+  return { settingsPath, spool, waitSeconds: HOOK_WAIT_S, askWaitSeconds: ASK_WAIT_S, host };
+}
+
+/** Record the mode the hook may approve in. A word that is not one of the session's modes is not written. */
+export function writeMode(spool, mode) {
+  const file = path.join(spool, 'mode');
+  try {
+    if (typeof mode === 'string' && /^[A-Za-z]+$/.test(mode)) fs.writeFileSync(file, `${mode}\n`);
+    else fs.rmSync(file, { force: true });
+  } catch { /* the hook then approves nothing, which is the safe side */ }
 }
 
 function gateMode(mode) {
@@ -104,6 +205,8 @@ function readRequest(spool, file) {
     // their absence means the session itself asked — it is not a missing answer.
     agentId: typeof payload.agent_id === 'string' && /^[A-Za-z0-9_-]+$/.test(payload.agent_id) ? payload.agent_id : null,
     agentType: typeof payload.agent_type === 'string' ? payload.agent_type.slice(0, 120) : null,
+    // How long this one waits before the hook denies it: longer for a question and for a plan.
+    waitSeconds: INTERACTIVE.includes(payload.tool_name) ? ASK_WAIT_S : HOOK_WAIT_S,
     askedAt: (() => {
       try { return fs.statSync(path.join(spool, 'req', file)).mtimeMs; } catch { return Date.now(); }
     })(),
@@ -111,7 +214,8 @@ function readRequest(spool, file) {
 }
 
 export function pending(sessionId) {
-  const spool = spoolFor(sessionId);
+  const spool = spoolUsable(sessionId);
+  if (!spool) return [];
   let files;
   try { files = fs.readdirSync(path.join(spool, 'req')); } catch { return []; }
   return files
@@ -125,31 +229,105 @@ export function alwaysList(sessionId) {
   try { return fs.readdirSync(path.join(spoolFor(sessionId), 'always')); } catch { return []; }
 }
 
+const QUESTIONS_MAX = 8;      // the tool takes one to four questions; twice that is refused as not a question
+const ANSWER_MAX = 2000;      // one answer's length; a question's options are short, free text may not be
+
 /**
- * Answer one request. `always` also allows that tool for the rest of the
- * session, which is the user widening their own gate deliberately — it is
- * scoped to one session and disappears with it.
+ * The answers to a question, checked: one per question of the request, keyed by the question's own text, each a
+ * string or (for a question that takes several) a list of strings. Returns null when what was sent is not that.
  */
-export function decide(sessionId, toolUseId, verdict) {
+export function cleanAnswers(questions, answers) {
+  if (!Array.isArray(questions) || questions.length > QUESTIONS_MAX || !answers || typeof answers !== 'object' || Array.isArray(answers)) return null;
+  // No prototype: a question whose text is `__proto__` or `constructor` is a key like any other, and nothing
+  // an answer is called can reach an inherited one.
+  const out = Object.create(null);
+  const seen = new Set();
+  for (const q of questions) {
+    const key = q?.question;
+    if (typeof key !== 'string' || seen.has(key) || !Object.hasOwn(answers, key)) return null;
+    seen.add(key);
+    const v = answers[key];
+    const ok = (x) => typeof x === 'string' && x.trim() !== '' && x.length <= ANSWER_MAX;
+    // Several answers only to a question that takes several, and no more of them than it has options plus the
+    // viewer's own one.
+    const most = (Array.isArray(q.options) ? q.options.length : 0) + 1;
+    if (Array.isArray(v) ? !(q.multiSelect === true && v.length > 0 && v.length <= most && v.every(ok)) : !ok(v)) return null;
+    out[key] = v;
+  }
+  return out;
+}
+
+const hookAllow = (updatedInput) => JSON.stringify({
+  hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'answered in Crewforth Studio', updatedInput },
+});
+
+/**
+ * Answer one request.
+ *
+ *   allow | deny | always   an ordinary tool call. `always` also allows that tool for the rest of the session,
+ *                           which is the user widening their own gate deliberately — it is scoped to one session
+ *                           and disappears with it.
+ *   answer                  AskUserQuestion: `extra.answers` are the viewer's answers. The hook hands them to
+ *                           Claude Code as the tool's input, which is how the hooks reference says a hook answers it.
+ *   plan                    ExitPlanMode: the plan is approved, to go on in `extra.mode` — `default` (the hook
+ *                           approves it; that is where Claude Code lands) or `acceptEdits` (the hook stays silent
+ *                           and the permission host approves it with the change of mode, which only it can make).
+ *
+ * The two interactive tools take only their own verdict or `deny`: a bare allow does not answer them, and neither
+ * may be allowed "for the session". No other tool takes `answer` or `plan`.
+ */
+export function decide(sessionId, toolUseId, verdict, extra = {}) {
   if (!/^[A-Za-z0-9_-]+$/.test(toolUseId)) return { ok: false, reason: 'bad tool use id' };
-  if (!['allow', 'deny', 'always'].includes(verdict)) return { ok: false, reason: `unknown verdict: ${verdict}` };
+  if (!['allow', 'deny', 'always', 'answer', 'plan'].includes(verdict)) return { ok: false, reason: `unknown verdict: ${verdict}` };
 
-  const spool = spoolFor(sessionId);
+  const spool = spoolUsable(sessionId);
+  if (!spool) return { ok: false, reason: 'the gate\'s spool is not a directory of this user\'s alone' };
   const req = pending(sessionId).find((r) => r.toolUseId === toolUseId);
+  const tool = req?.toolName ?? null;
+  const own = { AskUserQuestion: 'answer', ExitPlanMode: 'plan' }[tool] ?? null;
+  if (verdict === 'answer' || verdict === 'plan') {
+    if (!req) return { ok: false, reason: 'no such request is waiting' };
+    if (own !== verdict) return { ok: false, reason: `${tool} is not answered with "${verdict}"` };
+  } else if (own && verdict !== 'deny') {
+    return { ok: false, reason: `${tool} is answered with "${own}" or denied, not with "${verdict}"` };
+  }
+
+  let line = `${verdict}\n`;
+  let mode = null;
+  if (verdict === 'answer') {
+    const answers = cleanAnswers(req.input?.questions, extra?.answers);
+    if (!answers) return { ok: false, reason: 'the answers do not match the questions' };
+    // Verdict on the first line, the hook's whole output on the second: the hook prints it and does nothing else.
+    line = `output\n${hookAllow({ questions: req.input.questions, answers })}\n`;
+  } else if (verdict === 'plan') {
+    mode = extra?.mode;
+    if (!PLAN_MODES.includes(mode)) return { ok: false, reason: `a plan is approved into ${PLAN_MODES.join(' or ')}` };
+    try {
+      if (mode === 'default') {
+        line = `output\n${hookAllow(req.input ?? {})}\n`;
+      } else {
+        // Only the permission host can change the mode: the hook says nothing, and the host answers from this.
+        fs.writeFileSync(path.join(spool, 'host', `${toolUseId}.json`), JSON.stringify({ mode }));
+        line = 'host\n';
+      }
+      writeMode(spool, mode);
+    } catch (e) {
+      return { ok: false, reason: String(e?.message ?? e) };
+    }
+  }
 
   if (verdict === 'always') {
-    const tool = req?.toolName;
     if (tool && /^[A-Za-z0-9_-]+$/.test(tool)) {
       try { fs.writeFileSync(path.join(spool, 'always', tool), ''); } catch { /* best effort */ }
     }
   }
 
   try {
-    fs.writeFileSync(path.join(spool, 'ans', toolUseId), `${verdict}\n`);
+    fs.writeFileSync(path.join(spool, 'ans', toolUseId), line);
   } catch (e) {
     return { ok: false, reason: String(e?.message ?? e) };
   }
-  return { ok: true, verdict, toolName: req?.toolName ?? null };
+  return { ok: true, verdict, toolName: tool, mode };
 }
 
 /**
@@ -174,7 +352,7 @@ export const APPROVAL_LOG_MAX = 200;
 // A request that vanished this close to the hook's own deadline, with no answer recorded, timed out. The hook
 // polls and so does the watcher; this is their combined slack.
 const TIMEOUT_SLACK_MS = 2500;
-const VERDICT_OUTCOME = { allow: 'allowed', always: 'allowed-session', deny: 'denied' };
+const VERDICT_OUTCOME = { allow: 'allowed', always: 'allowed-session', deny: 'denied', answer: 'allowed', plan: 'allowed' };
 
 /**
  * Fold the requests waiting now into a session's record of approvals.
@@ -196,7 +374,7 @@ export function logApprovals(log, pending, decisions, now, waitSeconds) {
     e.endedAt = now;
     const verdict = decisions?.get(e.toolUseId);
     if (verdict && VERDICT_OUTCOME[verdict]) e.outcome = VERDICT_OUTCOME[verdict];
-    else if (typeof waitSeconds === 'number' && now >= e.askedAt + waitSeconds * 1000 - TIMEOUT_SLACK_MS) e.outcome = 'timed-out';
+    else if (typeof (e.waitSeconds ?? waitSeconds) === 'number' && now >= e.askedAt + (e.waitSeconds ?? waitSeconds) * 1000 - TIMEOUT_SLACK_MS) e.outcome = 'timed-out';
     else e.outcome = 'unanswered';
     decisions?.delete(e.toolUseId);
   }
@@ -205,6 +383,8 @@ export function logApprovals(log, pending, decisions, now, waitSeconds) {
     log.push({
       toolUseId: r.toolUseId, toolName: r.toolName, agentId: r.agentId ?? null, agentType: r.agentType ?? null,
       askedAt: r.askedAt, endedAt: null, outcome: null,
+      // A question and a plan wait longer than a command; each entry times out on its own clock.
+      waitSeconds: r.waitSeconds ?? null,
     });
   }
   // The oldest closed entries go first; a request still waiting is never dropped.
@@ -233,4 +413,67 @@ export function cleanup(sessionId) {
   try { fs.rmSync(spoolFor(sessionId), { recursive: true, force: true }); } catch { /* already gone */ }
 }
 
-export const _internals = { HOOK, HOOK_WAIT_S, HARNESS_TIMEOUT_S, ROOT };
+const OWNER = 'owner';
+const STALE_MS = 24 * 60 * 60 * 1000;
+
+/** Is a process with this id running? One that exists and is somebody else's counts: it is not ours to judge. */
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === 'EPERM'; }
+}
+
+/** The latest change time of a directory and of what is in it, two levels down: a spool is no deeper. Links are not followed. */
+function newest(dir, seen, depth = 2) {
+  let at = seen;
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return at; }
+  for (const n of names) {
+    let st;
+    try { st = fs.lstatSync(path.join(dir, n)); } catch { continue; }
+    if (st.mtimeMs > at) at = st.mtimeMs;
+    if (depth > 1 && st.isDirectory()) at = newest(path.join(dir, n), at, depth - 1);
+  }
+  return at;
+}
+
+/** What `sweep` is run on when a server starts: this user's root, and the one from before roots carried the user. */
+export function sweepLeft(opts = {}) {
+  return [...sweep({ ...opts, root: ROOT }), ...(OLD_ROOT === ROOT ? [] : sweep({ ...opts, root: OLD_ROOT }))];
+}
+
+/**
+ * Remove the spools a server left behind.
+ *
+ * A session's spool goes when the session exits (`cleanup`). A server that is killed never sees that exit, and on
+ * Windows a kill runs no handler at all, so its spools stay under the temp directory: settings, the mode, and
+ * whatever was waiting. This is run when a server starts.
+ *
+ * What is removed, and nothing else: a real directory (not a link) directly under the root, named like a session
+ * id, that is this user's alone, and whose owner — the server that made it — is no longer running. A spool with
+ * no owner written (made by a version before this) goes once it has not been touched for a day. A spool whose
+ * owner is running is another panel's, or this one's, and is left.
+ *
+ * @returns the names removed
+ */
+export function sweep({ root = ROOT, alive = pidAlive, self = process.pid, now = Date.now(), staleMs = STALE_MS } = {}) {
+  const gone = [];
+  if (spoolProblem(root) !== null) return gone;
+  let names;
+  try { names = fs.readdirSync(root); } catch { return gone; }
+  for (const name of names) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) continue;
+    const dir = path.join(root, name);
+    let st;
+    try { st = fs.lstatSync(dir); } catch { continue; }
+    if (!st.isDirectory() || spoolProblem(dir) !== null) continue;
+    let pid = null;
+    try { pid = Number.parseInt(fs.readFileSync(path.join(dir, OWNER), 'utf8'), 10); } catch { /* no owner written */ }
+    // With no owner to ask, age decides, and the age is the newest thing in the spool: a hook that wrote a request
+    // a minute ago touched a file two levels down, not the directory at the top.
+    const left = Number.isInteger(pid) && pid > 0 ? pid !== self && !alive(pid) : now - newest(dir, st.mtimeMs) > staleMs;
+    if (!left) continue;
+    try { fs.rmSync(dir, { recursive: true, force: true }); gone.push(name); } catch { /* still there; the next start tries again */ }
+  }
+  return gone;
+}
+
+export const _internals = { HOOK, HOST, HOOK_WAIT_S, ASK_WAIT_S, HARNESS_TIMEOUT_S, ASK_HARNESS_TIMEOUT_S, ROOT, OLD_ROOT, UID };

package/kit/studio/server/lib/session.js

@@ -15,7 +15,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 
-import { prepare, pending, watch, cleanup, alwaysList, logApprovals } from './permissions.js';
+import { prepare, pending, watch, cleanup, alwaysList, logApprovals, writeMode } from './permissions.js';
 import { getFleet } from './fleet.js';
 
 export const ALLOWED_MODES = ['plan', 'acceptEdits', 'default'];
@@ -102,6 +102,9 @@ class OwnedSession {
     // Our own settings file in our own directory. The user's settings are never
     // read, written or merged.
     if (this.gate) args.push('--settings', this.gate.settingsPath);
+    // The permission host: with one, Claude Code offers the two tools that need a person (a question, leaving
+    // plan mode). It denies every prompt that reaches it; the dock is where a call is allowed.
+    if (this.gate?.host) args.push('--mcp-config', this.gate.host.mcpPath, '--permission-prompt-tool', this.gate.host.tool);
 
     this.child = spawn('claude', args, {
       cwd: this.cwd,
@@ -168,6 +171,8 @@ class OwnedSession {
       this.gateEvents.push(ev);
       if (this.gateEvents.length > 500) this.gateEvents.shift();
     }
+    // The mode the session is in is what Claude Code says it is in: at the start, and each time it changes.
+    if (rec?.type === 'system' && typeof rec.permissionMode === 'string') this.#seeMode(rec.permissionMode);
     if (rec?.type === 'system' && rec.subtype === 'init') this.state = 'idle';
     else if (rec?.type === 'stream_event' && rec.event?.type === 'message_start') this.state = 'working';
     else if (rec?.type === 'result') {
@@ -189,6 +194,30 @@ class OwnedSession {
   /** The panel recorded an answer to a request. Remembered until the request is seen to have gone. */
   noteDecision(toolUseId, verdict) { this.decisions.set(toolUseId, verdict); }
 
+  /**
+   * Claude Code reported the session's mode. That is the mode: the header shows it, and the gate's hook is told it,
+   * so an allowance in the dock is said out loud in the mode the session is really in and in no other.
+   */
+  #seeMode(mode) {
+    if (mode === this.permissionMode) return;
+    this.permissionMode = mode;
+    if (this.gate) writeMode(this.gate.spool, mode);
+    this.#emit({ type: 'mode', permissionMode: mode });
+  }
+
+  /**
+   * Ask Claude Code to put the session in another mode: one of the modes a session may be started in, and no
+   * other. It is asked the way the Agent SDK's `setPermissionMode()` asks, as a control request on the session's
+   * input; nothing here is changed until Claude Code reports the new mode on its stream (`#seeMode`).
+   */
+  requestMode(mode) {
+    if (!ALLOWED_MODES.includes(mode)) return { ok: false, reason: `the mode is one of ${ALLOWED_MODES.join(', ')}` };
+    if (this.state === 'exited' || this.state === 'failed') return { ok: false, reason: `session has ${this.state}` };
+    const line = `${JSON.stringify({ type: 'control_request', request_id: randomUUID(), request: { subtype: 'set_permission_mode', mode } })}\n`;
+    try { this.child.stdin.write(line); } catch (e) { return { ok: false, reason: String(e?.message ?? e) }; }
+    return { ok: true, requested: mode };
+  }
+
   /** Replay from `after`, then follow. Returns an unsubscribe function. */
   subscribe(fn, after = 0) {
     for (const ev of this.events) if (ev.seq > after) fn(ev);
@@ -303,6 +332,9 @@ export async function createSession({ cwd, model, permissionMode, resume } = {})
 
 export function getSession(id) { return sessions.get(id) ?? null; }
 
+// For the selfcheck: what a session writes to Claude Code when a mode is asked for, without starting one.
+export const _internals = { OwnedSession };
+
 export function listSessionsOwned() {
   return [...sessions.values()].map((s) => s.summary());
 }
@@ -321,3 +353,11 @@ export function stopAll() {
     if (s.state !== 'exited' && s.state !== 'failed') s.stop();
   }
 }
+
+/**
+ * Remove the spool of every session this server started. For the server's own way out: it stops its sessions and
+ * leaves before their exits are seen, and the exit is where a spool is otherwise removed.
+ */
+export function dropSpools() {
+  for (const s of sessions.values()) cleanup(s.id);
+}

package/kit/studio/server/lib/usage.js

@@ -36,55 +36,115 @@ export function usageOfRecord(r) {
   };
 }
 
-export class Usage {
+const KINDS = ['input', 'output', 'cacheWrite', 'cacheRead'];
+
+/** One running sum: tokens by kind, what they cost, and which models had no price. */
+class Tally {
   constructor() {
-    this.seen = new Set();
     this.tokens = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0 };
     this.usd = 0;
     this.responses = 0;
-    this.priced = new Set();
     this.unpriced = new Set();
   }
 
-  /** Add a transcript's records. A response already counted, from this file or another, is not counted again. */
-  add(records) {
+  take(u, usd) {
+    this.responses += 1;
+    this.tokens.input += u.input;
+    this.tokens.output += u.output;
+    this.tokens.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
+    this.tokens.cacheRead += u.cacheRead;
+    if (usd === null) this.unpriced.add(u.model ?? 'unknown model');
+    else this.usd += usd;
+  }
+
+  /**
+   * `fresh` is what was sent and written for the first time: input, output and cache writes. `cacheRead` is the
+   * same context read back from the cache on every later response, which is why it dwarfs the rest in a long
+   * session and is kept out of the headline. `cost` is null when any of the tokens came from a model the price
+   * table has no row for — a sum that leaves some of them out would read as the whole.
+   */
+  result() {
+    const t = this.tokens;
+    return {
+      tokens: { ...t, fresh: t.input + t.output + t.cacheWrite, total: KINDS.reduce((a, k) => a + t[k], 0) },
+      responses: this.responses,
+      cost: this.unpriced.size ? null : this.usd,
+      unpriced: [...this.unpriced].sort(),
+    };
+  }
+}
+
+export class Usage {
+  constructor() {
+    this.seen = new Set();
+    this.all = new Tally();
+    this.who = new Map();      // 'session', or an agent's id -> Tally
+    this.model = new Map();    // model id -> Tally
+    this.first = null;         // the earliest and the latest record of any file added
+    this.last = null;
+  }
+
+  #tally(map, key) {
+    if (!map.has(key)) map.set(key, new Tally());
+    return map.get(key);
+  }
+
+  /**
+   * Add a transcript's records. A response already counted, from this file or another, is not counted again.
+   * @param who  'session' for the session's own transcript, or the id of the agent whose transcript this is.
+   *             A record the session's transcript marks as an agent's (`isSidechain`) is counted as an agent's.
+   */
+  add(records, who = 'session') {
     for (const r of records ?? []) {
+      const t = r?.timestamp ? Date.parse(r.timestamp) : NaN;
+      if (Number.isFinite(t)) {
+        if (this.first === null || t < this.first) this.first = t;
+        if (this.last === null || t > this.last) this.last = t;
+      }
       const u = usageOfRecord(r);
       if (!u) continue;
       if (u.id) { if (this.seen.has(u.id)) continue; this.seen.add(u.id); }
-      const total = u.input + u.output + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead;
-      if (!total) continue;                    // a record the harness made up for itself carries no tokens
-      this.responses += 1;
-      this.tokens.input += u.input;
-      this.tokens.output += u.output;
-      this.tokens.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
-      this.tokens.cacheRead += u.cacheRead;
+      if (!(u.input + u.output + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead)) continue;   // a record the harness made up carries no tokens
       const usd = costOf(u);
-      if (usd === null) this.unpriced.add(u.model ?? 'unknown model');
-      else { this.usd += usd; this.priced.add(u.model); }
+      this.all.take(u, usd);
+      this.#tally(this.who, who === 'session' && r.isSidechain === true ? 'agents:inline' : who).take(u, usd);
+      this.#tally(this.model, u.model ?? 'unknown model').take(u, usd);
     }
     return this;
   }
 
+  /** One agent's own share, or null when its transcript carried no usage. */
+  of(who) { return this.who.get(who)?.result() ?? null; }
+
   /**
-   * @returns tokens by kind and in total; `cost` in USD at list price, or null when any of the tokens came from
-   *          a model the table has no row for — a sum that leaves some of them out would read as the whole.
+   * @returns the whole session's tally, and the same split two ways: `parts.session` is what the session's own
+   *          transcript spent and `parts.agents` everything its agents did; `byModel` is one tally per model.
    */
   result() {
-    const t = this.tokens;
+    const agents = new Tally();
+    for (const [who, t] of this.who) {
+      if (who === 'session') continue;
+      for (const k of KINDS) agents.tokens[k] += t.tokens[k];
+      agents.usd += t.usd;
+      agents.responses += t.responses;
+      for (const m of t.unpriced) agents.unpriced.add(m);
+    }
+    const all = this.all.result();
     return {
-      tokens: { ...t, total: t.input + t.output + t.cacheWrite + t.cacheRead },
-      responses: this.responses,
-      cost: this.unpriced.size ? null : this.usd,
-      models: [...this.priced].sort(),
-      unpriced: [...this.unpriced].sort(),
+      ...all,
+      models: [...this.model.keys()].filter((m) => !all.unpriced.includes(m)).sort(),
+      parts: { session: (this.who.get('session') ?? new Tally()).result(), agents: agents.result() },
+      byModel: Object.fromEntries([...this.model].map(([m, t]) => [m, t.result()]).sort((a, b) => b[1].tokens.total - a[1].tokens.total)),
+      startedAt: this.first,
+      lastAt: this.last,
       priceSource: SOURCE,
     };
   }
 }
 
 /**
- * How long a session took, two ways. `durationMs` is from its first record to its last, pauses included.
+ * How long a session's own transcript says it took. `durationMs` is from its first record to its last, pauses
+ * included; with its agents' transcripts counted too, that span is `Usage`'s `startedAt` to `lastAt`.
  * `workedMs` is the turns Claude Code timed itself (`system` / `turn_duration` records), added up; zero when it
  * recorded none, and a turn that is still running is not in it.
  */
@@ -107,6 +167,16 @@ export function timesOf(records) {
   return { durationMs: first !== null && last !== null ? last - first : null, workedMs, turns };
 }
 
+/**
+ * The usage with the times beside it. The span runs to the last record of ANY of the session's files: an agent
+ * can be writing long after the session's own transcript last moved.
+ */
+export function withTimes(usage, mainRecords) {
+  const u = usage.result();
+  const t = timesOf(mainRecords);
+  return { ...u, workedMs: t.workedMs, turns: t.turns, durationMs: u.startedAt !== null && u.lastAt !== null ? u.lastAt - u.startedAt : null };
+}
+
 /** A session's usage with its agents', and how long it took. */
 export async function sessionUsage(session) {
   const usage = new Usage();
@@ -114,9 +184,17 @@ export async function sessionUsage(session) {
   usage.add(records);
   for (const meta of await agentMetaFiles(session.subagentsDir)) {
     const jsonl = meta.replace(/\.meta\.json$/, '.jsonl');
-    try { usage.add((await readAll(jsonl)).records); } catch { /* an agent that has not written yet */ }
+    const agentId = path.basename(jsonl).slice('agent-'.length, -'.jsonl'.length);
+    try { usage.add((await readAll(jsonl)).records, agentId); } catch { /* an agent that has not written yet */ }
+  }
+  // Each agent's own share, by its id: what the Models view prices a class of work with.
+  const agents = {};
+  for (const [who, t] of usage.who) {
+    if (who === 'session' || who.startsWith('agents:')) continue;
+    const r = t.result();
+    agents[who] = { fresh: r.tokens.fresh, cacheRead: r.tokens.cacheRead, cost: r.cost };
   }
-  return { ...usage.result(), ...timesOf(records) };
+  return { ...withTimes(usage, records), agents };
 }
 
 // One answer per session, kept until one of its files changes. The key is what the stream's own signature