crewforth 3.0.4 → 3.1.0-rc.2

package/kit/skills/frontend-flutter/references/sensitive-data.md

@@ -0,0 +1,54 @@
+# An app that holds sensitive data (Flutter)
+
+Apply only when the app stores data its user would not want read off a lost phone, a backup or the network:
+financial, health, identity. Checked against https://pub.dev/packages/sqlite3 and its hook documentation,
+https://pub.dev/packages/sqlcipher_flutter_libs and https://developer.android.com/identity/data/autobackup
+(2026-10-07). The iOS part is from Apple's API names and was **not checked against a fetched page**.
+
+## The database is encrypted
+- The project's database package decides how; the rule is that the file on disk is ciphertext.
+- With `package:sqlite3` 3.x the SQLite build is chosen by a build hook, in the `pubspec.yaml` at the workspace root:
+
+  ```yaml
+  hooks:
+    user_defines:
+      sqlite3:
+        source: sqlcipher   # or sqlite3mc; the default is sqlite3, which does not encrypt
+  ```
+
+- `sqlcipher_flutter_libs` belongs to version 2.x of `package:sqlite3`; its own page says "Not used anymore, update
+  to version 3.x of package:sqlite3 instead". Do not add it to a project on 3.x.
+- A test opens the database file without the key and expects the open to fail: an encryption that was configured
+  and silently not applied looks the same from the app.
+
+## The key is in the platform's secure store
+- Generated on the device, kept in the Keychain (iOS) or behind the Keystore (Android) through the project's
+  secure-storage package. Not in the database's directory, not in shared preferences, not in the code or its assets.
+- A key that is lost makes the data unreadable. Decide and write down what the app does then (an `adr`).
+
+## Out of backup and device transfer
+The database and the secure store's own files are excluded on both platforms; a restored copy without its key is
+unreadable at best, and a copy with its key is the data on another device.
+
+- **Android.** `android:allowBackup="false"` on `<application>`. For an app that targets Android 12 (API 31) or
+  higher that turns off cloud backup but, in the documentation's words, "doesn't disable device-to-device transfers"
+  on some manufacturers' devices. So also `android:dataExtractionRules` pointing at an XML file whose
+  `<cloud-backup>` and `<device-transfer>` sections each exclude the database and the secure-storage files. Devices
+  on Android 11 or lower read `android:fullBackupContent` instead.
+- **iOS.** The files carry the resource value `isExcludedFromBackup` (`NSURLIsExcludedFromBackupKey`), set from
+  native code or a plugin after the file exists. Set it again when the file is created anew.
+- A test (or a check in CI) reads the manifest and the rules file and fails when either attribute is missing.
+
+## Every network call through a transport bound to its allowed hosts
+- A transport is the one object a service's requests leave through. Each holds the host or hosts **it** may talk
+  to and **refuses any other**: it throws before the request is sent. An app with one backend has one transport;
+  an app that talks to several services gives each its own, with its own list, so a transport for one service
+  cannot reach another's host.
+- A test asks each transport for a host that is not on its list and expects the throw. An architecture test fails
+  on a network call made outside a transport (a client constructed or a socket opened anywhere else). In a debug
+  run the throw is a crash someone sees; it is never swallowed.
+
+## Ads
+In an app that shows ads, **no ad is drawn in a window where a sensitive screen is visible.** In a two-pane layout
+the detail pane may be the sensitive one while the list is not: the rule is about the window, so the list's ad goes
+too. A widget test at an expanded width expects no ad widget while the sensitive detail is shown.

package/kit/studio/server/hooks/studio-gate.sh

@@ -35,6 +35,35 @@ _field() {                                 # _field <key>  -> value on stdout
   printf '%s' "${r%%\"*}"
 }
 
+# ---- what "allowed" says to Claude Code --------------------------------------
+# Exit 0 with nothing on stdout is not an approval: the harness reads it as "no
+# decision" and sends the call through its own permission flow, and a headless
+# session has nobody to ask. Measured in real sessions (Claude Code 2.1.284): in
+# `default` mode Edit, Write and a writing Bash were all refused AFTER the viewer
+# allowed them here, and in `acceptEdits` the Bash was. So an allowance given in
+# the panel is said out loud, as the JSON decision the harness documents.
+#
+# Never in plan mode. The mode is an allow-list of two, and it has to agree with
+# what the harness itself reports for the session: a hook configured for
+# `default` that finds the session in `plan` stays silent, and so does one with
+# no mode, or with a mode this file does not name. Silence leaves plan's own
+# blocks, and every other check the harness makes, exactly where they were.
+#
+# This approves the call the viewer was shown. It does not unblock anything:
+# another hook that exits 2 still blocks, and this hook's own denials are exit 2.
+_grant() {
+  case "${CREW_GATE_MODE:-}" in
+    acceptEdits|default) ;;
+    *) exit 0 ;;
+  esac
+  case "$(_field permission_mode || true)" in
+    ''|acceptEdits|default) ;;
+    *) exit 0 ;;
+  esac
+  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"allowed in Crewforth Studio"}}'
+  exit 0
+}
+
 TOOL="$(_field tool_name || true)"
 TUID="$(_field tool_use_id || true)"
 SID="$(_field session_id || true)"
@@ -50,6 +79,11 @@ REQ="$SPOOL/req"; ANS="$SPOOL/ans"; ALWAYS="$SPOOL/always"
 mkdir -p "$REQ" "$ANS" "$ALWAYS" 2>/dev/null || exit 0
 
 # A tool the panel already blanket-approved for this session skips the round trip.
+# It is NOT approved out loud: nobody saw this call. The hook stays silent and the
+# harness decides as it would have without a panel, so a call it wants a person
+# for — a commit, anything a project's settings mark `ask` — is still refused in
+# a headless session instead of running unseen. _grant is for a call a person
+# answered, and only for that one.
 case "$TOOL" in
   *[!A-Za-z0-9_-]*) ;;                     # odd tool name: never treated as approved
   *) [ -f "$ALWAYS/$TOOL" ] && exit 0 ;;
@@ -156,7 +190,7 @@ while :; do
     read -r VERDICT < "$ANS/$TUID" 2>/dev/null || VERDICT=deny
     rm -f "$ANS/$TUID" "$REQ/$TUID.json" 2>/dev/null
     case "$VERDICT" in
-      allow|always) exit 0 ;;
+      allow|always) _grant ;;
       *) printf 'studio: denied in the panel\n' >&2; exit 2 ;;
     esac
   fi

package/kit/studio/server/index.js

@@ -25,7 +25,7 @@ import { parsePeers, askAll, ask } from './lib/peers.js';
 import {
   createSession, getSession, listSessionsOwned, reap, stopAll, ALLOWED_MODES,
 } from './lib/session.js';
-import { decide, pending, alwaysList } from './lib/permissions.js';
+import { decide, pending, alwaysList, revoke } from './lib/permissions.js';
 import { open as openTerminal, plan as terminalPlan } from './lib/terminal.js';
 import { gateLog, gateReport, sessionStats, board } from './lib/kit-telemetry.js';
 import { writeState, clearStateSync, findRunning } from './lib/instance.js';
@@ -387,7 +387,7 @@ async function handle(req, res) {
 
   if (url.pathname === '/api/owned' && req.method === 'GET') {
     reap();
-    return sendJson(res, 200, { measured: true, modes: ALLOWED_MODES, sessions: listSessionsOwned() });
+    return sendJson(res, 200, { measured: true, modes: ALLOWED_MODES, sessions: listSessionsOwned(), now: Date.now() });
   }
 
   if (url.pathname === '/api/owned' && req.method === 'POST') {
@@ -418,17 +418,27 @@ async function handle(req, res) {
         waitSeconds: s.gate?.waitSeconds ?? null,
         pending: s.gate ? pending(s.id) : [],
         always: s.gate ? alwaysList(s.id) : [],
+        now: Date.now(),
       });
     }
 
     const gate = writeAllowed(req);
     if (!gate.ok) return sendJson(res, 403, { ok: false, reason: gate.reason });
-    if (req.method !== 'POST' || !permMatch[2]) return sendJson(res, 405, { ok: false, reason: 'POST to a request id' });
     if (!s.gate) return sendJson(res, 409, { ok: false, reason: 'this session has no gate to answer' });
+    // DELETE /permissions/<tool> takes back an "allow this tool for the session".
+    if (req.method === 'DELETE' && permMatch[2]) {
+      const out = revoke(s.id, decodeURIComponent(permMatch[2]));
+      return sendJson(res, out.ok ? 200 : 400, { ...out, always: alwaysList(s.id) });
+    }
+    if (req.method !== 'POST' || !permMatch[2]) {
+      return sendJson(res, 405, { ok: false, reason: 'POST to a request id, or DELETE a tool name' });
+    }
 
     const body = await readBody(req);
     if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
-    const out = decide(s.id, decodeURIComponent(permMatch[2]), body.verdict);
+    const toolUseId = decodeURIComponent(permMatch[2]);
+    const out = decide(s.id, toolUseId, body.verdict);
+    if (out.ok) s.noteDecision(toolUseId, body.verdict);
     return sendJson(res, out.ok ? 200 : 400, out);
   }
 

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

@@ -405,24 +405,47 @@ export const _internals = { scanMain, harvestCompletions, SESSION_NODE };
 export async function agentDetail(session, agentId) {
   if (!/^[A-Za-z0-9_-]+$/.test(agentId)) return null;
 
-  const file = path.join(session.subagentsDir, `agent-${agentId}.jsonl`);
-  try { await fsp.stat(file); } catch { return null; }
+  // An agent a workflow started lives one directory down (subagents/workflows/<run>/). The graph finds those;
+  // looking only at the top level answered "no such agent" for every one of them.
+  let file = path.join(session.subagentsDir, `agent-${agentId}.jsonl`);
+  try {
+    await fsp.stat(file);
+  } catch {
+    const nested = (await agentMetaFiles(session.subagentsDir)).find((m) => path.basename(m) === `agent-${agentId}.meta.json`);
+    if (!nested) return null;
+    file = nested.replace(/\.meta\.json$/, '.jsonl');
+    try { await fsp.stat(file); } catch { return null; }
+  }
 
   const { records, malformed } = await readAll(file);
 
   let meta = {};
   try {
-    meta = JSON.parse(await fsp.readFile(path.join(session.subagentsDir, `agent-${agentId}.meta.json`), 'utf8'));
+    meta = JSON.parse(await fsp.readFile(file.replace(/\.jsonl$/, '.meta.json'), 'utf8'));
   } catch { /* the transcript is still the source of truth */ }
 
   const timeline = [];
   const texts = [];       // every text block, in order
   let prompt = null;
   let lastThinking = null;
+  // The last tool call that came back as an error: which tool, when, and the end of what it said. Null when
+  // none did — which is a finding about this transcript, and not the same as the transcript being unread.
+  const toolNames = new Map();
+  let lastError = null;
+  let errors = 0;
 
   for (const r of records) {
     const at = r?.timestamp ? Date.parse(r.timestamp) : null;
 
+    if (r?.type === 'user' && Array.isArray(r.message?.content)) {
+      for (const c of r.message.content) {
+        if (c?.type !== 'tool_result' || c.is_error !== true) continue;
+        errors += 1;
+        const res = toolResult(c);
+        lastError = { tool: toolNames.get(c.tool_use_id) ?? null, at, text: res.text, truncated: res.truncated, length: res.length };
+      }
+    }
+
     if (r?.type === 'user' && prompt === null) {
       const c = r.message?.content;
       const t = typeof c === 'string' ? c : (Array.isArray(c) ? c.find((x) => x?.type === 'text')?.text : null);
@@ -443,6 +466,7 @@ export async function agentDetail(session, agentId) {
         // through their most identifying input.
         const i = c.input ?? {};
         const label = i.description ?? i.file_path ?? i.pattern ?? i.query ?? i.command ?? i.skill ?? null;
+        if (typeof c.id === 'string') toolNames.set(c.id, c.name ?? 'unknown');
         timeline.push({
           at,
           name: c.name ?? 'unknown',
@@ -458,6 +482,8 @@ export async function agentDetail(session, agentId) {
 
   return {
     agentId,
+    // Where this agent's transcript is, for whoever wants to open it themselves.
+    transcriptPath: file,
     agentType: meta.agentType ?? null,
     description: meta.description ?? null,
     spawnDepth: meta.spawnDepth ?? null,
@@ -468,12 +494,32 @@ export async function agentDetail(session, agentId) {
     narration: texts.slice(0, -1).map((t) => t.text),
     thinking: lastThinking,
     timeline,
+    lastError,
+    errors,
     records: records.length,
     malformed,
   };
 }
 
 
+// How much of a tool's output travels to the page. The END is kept: a test run says how it went in its last
+// lines, and a build says what broke there.
+const RESULT_TAIL_BYTES = 4096;
+
+/** One tool result, cut to its tail, with the cut said. */
+export function toolResult(c) {
+  const raw = typeof c.content === 'string'
+    ? c.content
+    : Array.isArray(c.content) ? c.content.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+  const truncated = raw.length > RESULT_TAIL_BYTES;
+  return {
+    error: c.is_error === true,
+    text: truncated ? raw.slice(-RESULT_TAIL_BYTES) : raw,
+    truncated,
+    length: raw.length,
+  };
+}
+
 /**
  * The conversation a transcript holds, as the panel renders conversations.
  *
@@ -488,6 +534,16 @@ export async function conversation(session, { limit = 400 } = {}) {
   const { records } = await readAll(session.file);
   const out = [];
 
+  // What each tool call came back with, by the call's id. A call with no entry here has not returned, or its
+  // result is not in this transcript; the block then carries `result: null`, which is not "it returned nothing".
+  const results = new Map();
+  for (const r of records) {
+    if (r?.isSidechain === true || r?.type !== 'user' || !Array.isArray(r.message?.content)) continue;
+    for (const c of r.message.content) {
+      if (c?.type === 'tool_result' && typeof c.tool_use_id === 'string') results.set(c.tool_use_id, toolResult(c));
+    }
+  }
+
   for (const r of records) {
     if (r?.isSidechain === true) continue;
     if (r?.parent_tool_use_id) continue;
@@ -515,6 +571,11 @@ export async function conversation(session, { limit = 400 } = {}) {
             kind: 'tool',
             name: c.name ?? 'tool',
             label: i.description ?? i.file_path ?? i.command ?? i.pattern ?? i.query ?? null,
+            // The call's own id: what a result, and an agent on the graph, are matched to it by.
+            id: typeof c.id === 'string' ? c.id : null,
+            // Only a delegation has one. The agent's type is what the card in the conversation is named after.
+            subagentType: typeof i.subagent_type === 'string' ? i.subagent_type : null,
+            result: (typeof c.id === 'string' ? results.get(c.id) : null) ?? null,
           });
         }
       }

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),
     };
   }