crewforth 3.0.3 → 3.1.0-rc.1

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

@@ -16,6 +16,14 @@ const FEED = process.env.CREW_UPDATE_URL
 const FEED_TTL_MS = 60 * 60 * 1000;   // the hook uses a day; a panel refreshes hourly
 const FETCH_TIMEOUT_MS = 8000;
 
+// How an install made of files is updated: the command, as the project's own update notice words it. It lives
+// here and travels in the payload so that the panel never types a command of its own.
+//
+// It is given ONLY to a project that has `.claude/VERSION`. A plugin install leaves no file in the project, so
+// from here it cannot be told from a project without Crewforth — and it does not update through npx. Such a
+// project gets null, and the panel shows the `/crew-update` hint instead of a command it would have to invent.
+const FILE_INSTALL_UPDATE = 'npx crewforth@latest update --here';
+
 let latestCache = null;   // { at, value }
 let inflight = null;
 
@@ -120,7 +128,12 @@ export async function kitStatus(cwd, latest) {
     // the other is a dead path.
     let present = false;
     try { await fsp.stat(cwd); present = true; } catch { present = false; }
-    return { installed: false, dirExists: present, reason: present ? 'Crewforth not installed' : 'directory no longer exists' };
+    return {
+      installed: false,
+      dirExists: present,
+      reason: present ? 'Crewforth not installed' : 'directory no longer exists',
+      updateCommand: null,
+    };
   }
 
   const conf = {};
@@ -137,6 +150,7 @@ export async function kitStatus(cwd, latest) {
     version,
     stack: conf.stack ?? null,
     installer: conf.installer ?? null,
+    updateCommand: FILE_INSTALL_UPDATE,
   };
 
   if (!latest?.measured) {
@@ -155,4 +169,4 @@ export async function kitStatus(cwd, latest) {
   return out;
 }
 
-export const _internals = { sane, FEED };
+export const _internals = { sane, FEED, FILE_INSTALL_UPDATE };

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

@@ -39,7 +39,7 @@ export function spoolFor(sessionId) {
  * are never read, written, or merged. Returns null when the hook is missing, so
  * the caller can say "no gate" instead of quietly running without one.
  */
-export function prepare(sessionId) {
+export function prepare(sessionId, mode = null) {
   if (!fs.existsSync(HOOK)) return null;
 
   const spool = spoolFor(sessionId);
@@ -57,7 +57,10 @@ export function prepare(sessionId) {
           // Named, not left to the default: on Windows without a detected Git Bash, Claude Code runs a hook through
           // PowerShell, which cannot read the VAR=… prefix — the gate would fail open.
           shell: 'bash',
-          command: `CREW_GATE_WAIT=${HOOK_WAIT_S} bash ${JSON.stringify(HOOK)} ${JSON.stringify(spool)}`,
+          // 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)}`,
           timeout: HARNESS_TIMEOUT_S,
         }],
       }],
@@ -67,6 +70,10 @@ export function prepare(sessionId) {
   return { settingsPath, spool, waitSeconds: HOOK_WAIT_S };
 }
 
+function gateMode(mode) {
+  return typeof mode === 'string' && /^[A-Za-z]+$/.test(mode) ? `CREW_GATE_MODE=${mode} ` : '';
+}
+
 /** One pending request, as the panel needs to show it. */
 function readRequest(spool, file) {
   const toolUseId = file.replace(/\.json$/, '');
@@ -85,6 +92,10 @@ function readRequest(spool, file) {
     detail: input.command ?? input.file_path ?? input.pattern ?? input.query ?? input.description ?? null,
     input,
     cwd: payload.cwd ?? null,
+    // Who asked. Claude Code puts these in the hook's input only when the call comes from inside a subagent, so
+    // 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,
     askedAt: (() => {
       try { return fs.statSync(path.join(spool, 'req', file)).mtimeMs; } catch { return Date.now(); }
     })(),
@@ -133,6 +144,70 @@ export function decide(sessionId, toolUseId, verdict) {
   return { ok: true, verdict, toolName: req?.toolName ?? null };
 }
 
+/**
+ * Take back an "allow this tool for the session". The hook looks for the tool's file on every call, so the next
+ * call of that tool is asked about again. Returns whether there was anything to take back.
+ */
+export function revoke(sessionId, tool) {
+  if (typeof tool !== 'string' || !/^[A-Za-z0-9_-]+$/.test(tool)) return { ok: false, reason: 'bad tool name' };
+  const file = path.join(spoolFor(sessionId), 'always', tool);
+  try {
+    fs.rmSync(file);
+    return { ok: true, tool, revoked: true };
+  } catch (e) {
+    if (e?.code === 'ENOENT') return { ok: true, tool, revoked: false };
+    return { ok: false, reason: String(e?.message ?? e) };
+  }
+}
+
+// How many answered requests a session remembers. In memory only: a server that restarts starts the record
+// again, and the page says from when the record runs.
+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' };
+
+/**
+ * Fold the requests waiting now into a session's record of approvals.
+ *
+ * A request not seen before is opened with the moment it was asked. One that was open and is no longer waiting
+ * is closed with the moment that was noticed and with what became of it: the answer the panel recorded, a
+ * timeout if nobody answered and the hook's deadline had come, and otherwise "unanswered" — the hook went away
+ * without one, as it does when the session is stopped. Nothing is guessed into an answer.
+ *
+ * @param log        the record so far, oldest first; changed in place and returned
+ * @param pending    what `pending()` returns now
+ * @param decisions  Map toolUseId -> verdict the panel recorded
+ */
+export function logApprovals(log, pending, decisions, now, waitSeconds) {
+  const waiting = new Set(pending.map((r) => r.toolUseId));
+  const open = new Set(log.filter((e) => e.endedAt === null).map((e) => e.toolUseId));
+  for (const e of log) {
+    if (e.endedAt !== null || waiting.has(e.toolUseId)) continue;
+    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 e.outcome = 'unanswered';
+    decisions?.delete(e.toolUseId);
+  }
+  for (const r of pending) {
+    if (open.has(r.toolUseId)) continue;
+    log.push({
+      toolUseId: r.toolUseId, toolName: r.toolName, agentId: r.agentId ?? null, agentType: r.agentType ?? null,
+      askedAt: r.askedAt, endedAt: null, outcome: null,
+    });
+  }
+  // The oldest closed entries go first; a request still waiting is never dropped.
+  while (log.length > APPROVAL_LOG_MAX) {
+    const i = log.findIndex((e) => e.endedAt !== null);
+    if (i === -1) break;
+    log.splice(i, 1);
+  }
+  return log;
+}
+
 /** Watch a session's spool and call back whenever the pending set changes. */
 export function watch(sessionId, onChange) {
   let last = '';

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

@@ -68,15 +68,25 @@ export async function allProjectDirs() {
 // Reading them means scanning the transcript, and the sidebar refreshes on a
 // timer over every session in the project — so only the tail is read (the
 // latest record wins anyway) and the result is cached against size+mtime.
+//
+// The branch comes out of the same read. Every record carries `gitBranch`, and the last one in the tail is the
+// branch the session is on now — a session can change branch, and the navigator names where it is, not where it
+// began. A transcript with no such field, or an empty one (not a repository), yields null: the caller shows
+// nothing rather than a branch nobody read.
 const TITLE_TAIL_BYTES = 131072;
-const titleCache = new Map(); // file -> { sig, title }
+const titleCache = new Map(); // file -> { sig, title, branch }
 
 export async function sessionTitle(file, size, mtimeMs) {
+  return (await sessionTail(file, size, mtimeMs)).title;
+}
+
+export async function sessionTail(file, size, mtimeMs) {
   const sig = `${size}:${mtimeMs}`;
   const hit = titleCache.get(file);
-  if (hit && hit.sig === sig) return hit.title;
+  if (hit && hit.sig === sig) return { title: hit.title, branch: hit.branch };
 
   let title = null;
+  let branch = null;
   let fh;
   try {
     fh = await fsp.open(file, 'r');
@@ -100,15 +110,24 @@ export async function sessionTitle(file, size, mtimeMs) {
       }
     }
     title = found.custom ?? found.agent ?? found.ai ?? null;
+
+    // In a record the key is followed by a bare quote; inside a quoted message every quote is escaped, so text
+    // that merely mentions the field cannot match.
+    let last = null;
+    for (const m of text.matchAll(/"gitBranch"\s*:\s*"((?:[^"\\]|\\.)*)"/g)) last = m[1];
+    if (last) {
+      try { branch = JSON.parse(`"${last}"`) || null; } catch { branch = null; }
+    }
   } catch {
     title = null;
+    branch = null;
   } finally {
     if (fh !== undefined) try { await fh.close(); } catch { /* already gone */ }
   }
 
   if (titleCache.size > 500) titleCache.clear();
-  titleCache.set(file, { sig, title });
-  return title;
+  titleCache.set(file, { sig, title, branch });
+  return { title, branch };
 }
 
 // The working directory a session ran in. The encoded folder name cannot be
@@ -162,13 +181,16 @@ export async function listSessions(dir) {
     try { st = await fsp.stat(file); } catch { return null; }
 
     const subagentsDir = path.join(dir, sessionId, 'subagents');
-    const [agentCount, title, cwd] = await Promise.all([
+    const [agentCount, tail, cwd] = await Promise.all([
       countAgentMetas(subagentsDir),
-      sessionTitle(file, st.size, st.mtimeMs),
+      sessionTail(file, st.size, st.mtimeMs),
       sessionCwd(file, st.size),
     ]);
 
-    return { sessionId, file, subagentsDir, bytes: st.size, modifiedAt: st.mtimeMs, agentCount, title, cwd };
+    return {
+      sessionId, file, subagentsDir, bytes: st.size, modifiedAt: st.mtimeMs, agentCount,
+      title: tail.title, branch: tail.branch, cwd,
+    };
   }));
 
   const out = settled.filter(Boolean);
@@ -222,6 +244,34 @@ export async function agentMetaFiles(subagentsDir, depth = 0) {
   return out;
 }
 
+/**
+ * The branch a directory is on NOW, read from its `.git/HEAD` and nowhere else.
+ *
+ * No process is started: a `git` per project per poll is the cost this file exists to avoid. A worktree's `.git`
+ * is a file that points at its real git directory, and that pointer is followed once. A detached HEAD, a
+ * directory that is not a repository's root, and a file that cannot be read all answer null: the caller then
+ * names no branch, which is different from naming the one a session recorded last week.
+ */
+export async function headBranch(cwd) {
+  if (!cwd) return null;
+  const dot = path.join(cwd, '.git');
+  let head;
+  try {
+    const st = await fsp.stat(dot);
+    if (st.isDirectory()) {
+      head = await fsp.readFile(path.join(dot, 'HEAD'), 'utf8');
+    } else {
+      const m = (await fsp.readFile(dot, 'utf8')).match(/^gitdir:\s*(.+?)\s*$/m);
+      if (!m) return null;
+      head = await fsp.readFile(path.join(path.resolve(cwd, m[1]), 'HEAD'), 'utf8');
+    }
+  } catch {
+    return null;
+  }
+  const ref = head.match(/^ref:\s*refs\/heads\/(\S+)\s*$/m);
+  return ref ? ref[1] : null;
+}
+
 /**
  * Every session on this machine, grouped by the project it ran in.
  *
@@ -257,6 +307,9 @@ export async function listProjects({ currentCwd = null, limitPerProject = 60, ki
       // not deleted: the panel says how many it is holding back rather than
       // quietly shortening the list.
       exists: kit?.dirExists ?? (g.cwd ? await existsCached(g.cwd) : false),
+      // Where a session started here now would be working. Not the branch a session recorded: that one is on
+      // each session row, and may be weeks old.
+      branch: await headBranch(g.cwd),
       total: g.sessions.length,
       agentTotal: g.sessions.reduce((n, s) => n + s.agentCount, 0),
       modifiedAt: g.sessions[0]?.modifiedAt ?? 0,

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 } from './permissions.js';
+import { prepare, pending, watch, cleanup, alwaysList, logApprovals } from './permissions.js';
 import { getFleet } from './fleet.js';
 
 export const ALLOWED_MODES = ['plan', 'acceptEdits', 'default'];
@@ -49,12 +49,17 @@ class OwnedSession {
     // The gate is prepared before the child exists, so its very first tool call
     // is already covered. A missing hook is reported, never worked around: a
     // panel that silently ran ungated would be worse than one that cannot run.
-    this.gate = prepare(this.id);
+    this.gate = prepare(this.id, this.permissionMode);
     this.pendingPermissions = [];
     this.gateEvents = [];      // hook lifecycle, newest last
+    // What was asked of the viewer in this session, when, and what became of it. Kept from the moment Studio
+    // started the session, in memory: it is what the Timeline's waiting periods are drawn from.
+    this.approvals = [];
+    this.decisions = new Map();
     this.unwatch = this.gate
       ? watch(this.id, (reqs) => {
         this.pendingPermissions = reqs;
+        logApprovals(this.approvals, reqs, this.decisions, Date.now(), this.gate.waitSeconds);
         this.#emit({ type: 'permissions', pending: reqs });
       })
       : null;
@@ -181,6 +186,9 @@ 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); }
+
   /** 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);
@@ -235,6 +243,12 @@ class OwnedSession {
       gated: Boolean(this.gate),
       gateWaitSeconds: this.gate?.waitSeconds ?? null,
       pendingPermissions: this.pendingPermissions,
+      // Tools the viewer allowed for the rest of this session, so they can be listed and taken back.
+      alwaysAllowed: this.gate ? alwaysList(this.id) : [],
+      approvals: this.approvals,
+      // This machine's clock. A countdown is `askedAt + wait - now`, and all three have to come from one clock:
+      // a viewer on another machine has a different one.
+      now: Date.now(),
       gateEvents: this.gateEvents.slice(-40),
     };
   }