claude-code-kanban 7.6.0 → 7.7.0

package/hub-app.json

@@ -5,7 +5,7 @@
   "icon": "columns",
   "run": { "entry": "server.js", "defaultPort": 3541 },
   "publishes": ["session.changed"],
-  "keys": { "keeps": ["ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s"] },
+  "keys": { "keeps": ["ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s", "ctrl+shift+k", "ctrl+shift+p", "ctrl+shift+z"] },
   "plugin": {
     "id": "claude-code-kanban@claude-code-kanban",
     "path": "plugin/plugins/claude-code-kanban",

package/kanbot/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "cck-kanbot",
+  "version": "0.1.0",
+  "description": "The board's own assistant: one agent, loaded with --plugin-dir by the kanbot chat. Moves into claude-code-kanban once it settles."
+}

package/kanbot/agents/kanbot.md

@@ -0,0 +1,34 @@
+---
+name: kanbot
+description: Kanbot, the assistant built into the claude-code-kanban board. Answers questions, looks things up, drives the board through the claude-code-kanban CLI and hands project work to other sessions.
+color: orange
+memory: project
+---
+
+You are Kanbot, a general assistant built into the claude-code-kanban board (cck). The user talks to you in a popover on the board, often about 55 columns wide: answer in a few short lines or a short list, in plain words.
+
+You help with anything: questions, research, reading code and transcripts, and running the board. You are the user's front desk, not a worker on their projects.
+
+## Delegate the work
+
+Work that changes a project (code edits, fixes, features, refactors, long builds or test runs) belongs in its own session, where the user can watch and steer it. Do not do it yourself. Instead:
+
+- Suggest a session for it: name the project folder and write the task as a short, self-contained prompt.
+- When the user agrees, start it with the dispatch skill (`/claude-code-kanban:dispatch`) or `claude-code-kanban dispatch start`, or give the user the command to run.
+- For work already running in a session, point the user to that session or send the task there, not to you.
+
+Small things that change no project you may do yourself: answer, explain, search, read files, sketch a plan, write a scratch note.
+
+## Which session
+
+You cannot see which session the user has open on the board. When the user means one ("this session", "the siem one"), find it with `claude-code-kanban session search <text>` or `session list`, and ask when more than one fits. Keep using that session until the user names another.
+
+`session list` and `group list` show what the sidebar's Active view shows; add `--all` for every session. `group list --json` gives each member's title, branch, status and pin, so you need no `session list` to describe a group.
+
+Your own session is hidden from the board, so the CLI's default session is yours, not the user's. Pass `--session <id>` with the user's session to every command that takes `--session`.
+
+## Where to look
+
+- **A session**: `session view <id>` prints its project and transcript path. Read the transcript and task files.
+- **cck itself** (keys, themes, panes, settings, the terminal, the hub): read the docs at https://nikiforovall.blog/claude-code-kanban/ with WebFetch. Start from `reference/keyboard-shortcuts/`, `reference/configuration/` or the `guides/` page for the feature.
+- **The board CLI**: its top-level help and this board's URL are below. Read `claude-code-kanban help <command> <subcommand>` for the flags before you run a command.

package/lib/http-error.js

@@ -1,6 +1,7 @@
 // An error a route answers with `status`; `code` is the machine-readable reason, where one is set.
+// `expose` lets the API error handler send the message for a 5xx too, because it was written for the user.
 function httpError(status, message, code) {
-  return Object.assign(new Error(message), { status, code });
+  return Object.assign(new Error(message), { status, code, expose: true });
 }
 
 module.exports = { httpError };

package/lib/kanbot.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { encodeProjectDirName } = require('./claude-dir');
+const { MODELS } = require('./terminal');
+const { topHelp } = require('../cli');
+
+const PLUGIN_DIR = path.join(__dirname, '..', 'kanbot');
+const AGENT = 'cck-kanbot:kanbot';
+const TRANSCRIPT_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+function kanbotOn(cfg) {
+  return cfg?.kanbot?.enabled !== false;
+}
+
+function kanbotModel(cfg) {
+  const model = cfg?.kanbot?.model;
+  return MODELS.has(model) ? model : null;
+}
+
+function writeHelpPrompt(cwd, boardUrl) {
+  const file = path.join(cwd, 'cli-help.md');
+  const board = boardUrl ? `This board runs at ${boardUrl}; \`$CCK_URL\` holds the same URL, so the CLI talks to it.\n\n` : '';
+  fs.writeFileSync(file, `# claude-code-kanban CLI\n\n${board}\`claude-code-kanban help\` prints:\n\n\`\`\`\n${topHelp()}\n\`\`\`\n`);
+  return file;
+}
+
+function kanbotArgs(cwd, claudeDir, boardUrl) {
+  return ['--plugin-dir', PLUGIN_DIR, '--agent', AGENT, '--append-system-prompt-file', writeHelpPrompt(cwd, boardUrl), '--add-dir', claudeDir];
+}
+
+function createKanbot({ cckDir, projectsDir }) {
+  const cwd = path.join(cckDir, 'kanbot');
+  const projectDir = path.join(projectsDir, encodeProjectDirName(cwd));
+  const ownIds = new Set();
+  let sessionId = null;
+
+  function transcriptIds() {
+    try {
+      return fs.readdirSync(projectDir).map((f) => TRANSCRIPT_RE.exec(f)?.[1]).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  // The newest transcript is the chat to resume: /clear starts a new one in the same folder.
+  function newestTranscript() {
+    let best = null;
+    for (const id of transcriptIds()) {
+      const mtime = fs.statSync(path.join(projectDir, `${id}.jsonl`), { throwIfNoEntry: false })?.mtimeMs;
+      if (mtime && (!best || mtime > best.mtime)) best = { id, mtime };
+    }
+    return best?.id || null;
+  }
+
+  for (const id of transcriptIds()) ownIds.add(id);
+
+  return {
+    cwd,
+    ptyId: null,
+    isOwnPath: (p) => p === projectDir || p.startsWith(projectDir + path.sep),
+    isOwnProjectDirName: (name) => name === path.basename(projectDir),
+    isOwnSession: (id) => ownIds.has(id),
+    // A fresh start writes hook files under its id before claude writes a transcript.
+    own: (id) => ownIds.add(id),
+    onTranscript(filePath, event) {
+      const id = TRANSCRIPT_RE.exec(path.basename(filePath))?.[1];
+      if (event === 'unlink' || !id) return;
+      sessionId = id;
+      ownIds.add(id);
+    },
+    startSpec({ model = null, boardUrl = null } = {}) {
+      fs.mkdirSync(cwd, { recursive: true });
+      sessionId = newestTranscript();
+      const extraArgs = kanbotArgs(cwd, path.dirname(cckDir), boardUrl);
+      // Not restored on a cck restart: a restore would bring it back without the agent args.
+      return { cwd, name: 'kanbot', model, extraArgs, restore: false, ...(sessionId && { resume: sessionId }) };
+    },
+    get sessionId() {
+      return sessionId;
+    },
+  };
+}
+
+module.exports = { kanbotOn, kanbotModel, createKanbot, KANBOT_AGENT: AGENT, KANBOT_PLUGIN_DIR: PLUGIN_DIR };

package/lib/owner-routing.js

@@ -0,0 +1,53 @@
+// `dispatched` is the store from lib/retention.js; `listToSessions[listId]` is `{[sessionId]: …}`
+// from the plugin's task maps; `metadata` is a getter for session metadata.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const linkKey = (list, owner) => `${list}\n${owner}`;
+
+// A list's candidates are the sessions the list's session dispatched (a session's own list)
+// and the sessions mapped to the list (a shared list). `owner` matches the live `agentName`,
+// which follows /rename the same way SendMessage does. A name two candidates share gets no link.
+function ownerLinks(listIds, { dispatched, listToSessions, metadata }) {
+  const candidates = new Map();
+  const add = (list, id) => {
+    if (!candidates.has(list)) candidates.set(list, new Set());
+    candidates.get(list).add(id);
+  };
+  for (const [id, e] of dispatched.entries()) if (listIds.has(e?.parent)) add(e.parent, id);
+  for (const list of listIds) for (const id of Object.keys(listToSessions[list] || {})) add(list, id);
+
+  const links = new Map();
+  if (candidates.size) {
+    const meta = metadata();
+    for (const [list, ids] of candidates) {
+      for (const id of ids) {
+        const name = meta[id]?.agentName;
+        if (!name) continue;
+        const key = linkKey(list, name);
+        links.set(key, links.has(key) ? null : id);
+      }
+    }
+  }
+  return (list, owner) => links.get(linkKey(list, owner)) || null;
+}
+
+// Who gets a board move on a shared list: the owner, else the one session that dispatched the
+// list's sessions, else no one, because a line to every worker makes them race for the task.
+// Null when the rule does not apply: a session's own list goes to that session, the orchestrator,
+// even for a child's card, and a list with no task map (a team board) keeps its old routing.
+function moveRecipients(listId, owner, inputs) {
+  const mapped = !UUID_RE.test(listId) && inputs.listToSessions[listId];
+  if (!mapped) return null;
+  const id = owner && ownerLinks(new Set([listId]), inputs)(listId, owner);
+  if (id) return [id];
+  const onList = Object.keys(mapped);
+  const on = new Set(onList);
+  const parentOf = (s) => inputs.dispatched.get(s)?.parent || null;
+  // A session on the list that dispatched others on it is the orchestrator; its own parent is
+  // outside the swarm and does not count.
+  const orchestrators = new Set(onList.map(parentOf).filter((p) => on.has(p)));
+  const parents = new Set(onList.filter((s) => !orchestrators.has(s)).map(parentOf).filter(Boolean));
+  return parents.size === 1 ? [...parents] : [];
+}
+
+module.exports = { ownerLinks, moveRecipients };

package/lib/preview-action.js

@@ -0,0 +1,55 @@
+const { oneLine } = require('./one-line');
+const { httpError } = require('./http-error');
+
+const ACTION_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const KIND_RE = /^[a-z]{1,20}$/;
+const MAX_FIELDS = 50;
+const MAX_VALUES = 50;
+const MAX_CHARS = 4000;
+
+// The `source` of a review or an action: the view it came from. The caller resolves `path`.
+function parseReviewSource(source) {
+  if (!KIND_RE.test(source?.kind || '')) throw httpError(400, 'source.kind is required');
+  // The label is pasted into the terminal; an ESC could end bracketed paste and submit text.
+  const label = oneLine(source.label, 200);
+  if (!label) throw httpError(400, 'source.label is required');
+  return {
+    kind: source.kind,
+    label,
+    path: source.kind === 'file' ? source.path : null,
+    locate: oneLine(source.locate, 600) || null,
+  };
+}
+
+// The fields come from a form inside a sandboxed card, so the card's author picks the names and
+// values: they are capped here and printed as JSON, never as markdown.
+function parseActionBody(body) {
+  const { source, action, label, data } = body || {};
+  const src = parseReviewSource(source);
+  if (!ACTION_RE.test(action || '')) throw httpError(400, 'action must match [A-Za-z0-9._-]{1,64}');
+  const fields = {};
+  const entries = Object.entries(data && typeof data === 'object' && !Array.isArray(data) ? data : {});
+  if (entries.length > MAX_FIELDS) throw httpError(400, `data holds at most ${MAX_FIELDS} fields`);
+  for (const [k, v] of entries) {
+    const list = Array.isArray(v) ? v : [v];
+    if (list.length > MAX_VALUES || list.some((x) => typeof x !== 'string')) {
+      throw httpError(400, 'each field is a string or a list of strings');
+    }
+    const vals = list.map((x) => x.slice(0, MAX_CHARS));
+    fields[k.slice(0, 200)] = Array.isArray(v) ? vals : vals[0];
+  }
+  return { src, action, label: oneLine(label, 200) || action, fields };
+}
+
+function formatActionMarkdown({ src, action, label, fields }) {
+  const parts = [
+    `# Action "${action}" on ${src.path || src.label}`,
+    '',
+    `The user pressed "${label}" on the page in the board. Treat it as the user's answer.`,
+  ];
+  if (src.locate) parts.push('', src.locate);
+  if (Object.keys(fields).length) parts.push('', '```json', JSON.stringify(fields, null, 2), '```');
+  return `${parts.join('\n')}\n`;
+}
+
+module.exports = { parseReviewSource, parseActionBody, formatActionMarkdown };

package/lib/session-events.js

@@ -68,6 +68,10 @@ function formatReviewSubmitted(count, label, reviewFile) {
   return `${EVENT_PREFIX} Address ${comments} on ${label}: ${reviewFile}`;
 }
 
+function formatActionSubmitted(action, label, file) {
+  return `${EVENT_PREFIX} User submitted "${action}" on ${label}: ${file}`;
+}
+
 // Names this board run in every reply, so a mod drops `got` and `ack` counted against a run
 // that has since restarted.
 const BOARD_RUN = crypto.randomBytes(6).toString('hex');
@@ -260,6 +264,7 @@ module.exports = {
   formatTaskMoved,
   boardEventsOn,
   formatReviewSubmitted,
+  formatActionSubmitted,
   hasDoorbell,
   configureSessionEvents,
   enqueueSessionEvent,

package/lib/session-pins.js

@@ -0,0 +1,99 @@
+// Session pins: which sessions the sidebar pins, and which of those are sticky. The board, the CLI
+// and every board on the same config dir share them through `.cck/pins.json`, a flat
+// {sessionId: "pinned"|"sticky"} map. Each write changes only the sessions it names, so the last
+// write for a session wins.
+
+const { httpError } = require('./http-error');
+
+const MAX_PINS = 1000;
+const MAX_REF = 4096;
+const STATES = new Set(['pinned', 'sticky']);
+
+const fail = (status, message) => {
+  throw httpError(status, message);
+};
+
+const isRef = (s) => typeof s === 'string' && s.length > 0 && s.length <= MAX_REF;
+
+function readPins(obj) {
+  const out = {};
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return out;
+  let n = 0;
+  for (const [id, state] of Object.entries(obj)) {
+    if (n >= MAX_PINS) break;
+    if (isRef(id) && STATES.has(state)) {
+      out[id] = state;
+      n++;
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} o
+ * @param {() => object|null|undefined} o.load `undefined` means keep what is in memory: the file has
+ *   not changed since the last load, or cannot be read
+ * @param {(data: object) => void} o.save throws when the pins must not or cannot be written
+ */
+function createSessionPinStore({ load, save }) {
+  let pins = {};
+
+  // Another board on the same config dir writes the same file. Returns the sessions whose state
+  // changed, as [{id, state}] with state 'none' for a removed pin.
+  function reload() {
+    const saved = load();
+    if (saved === undefined) return [];
+    const before = pins;
+    pins = readPins(saved);
+    return diff(before, pins);
+  }
+  reload();
+
+  const state = () => ({ pins });
+
+  function commit(next) {
+    save(next);
+    const changed = diff(pins, next);
+    pins = next;
+    return changed;
+  }
+
+  function set(ids, s) {
+    if (!Array.isArray(ids) || !ids.length || !ids.every(isRef)) fail(400, 'ids is required');
+    if (s !== 'none' && !STATES.has(s)) fail(400, 'state must be none|pinned|sticky');
+    const next = { ...pins };
+    for (const id of ids) {
+      if (s === 'none') delete next[id];
+      else next[id] = s;
+    }
+    if (Object.keys(next).length > MAX_PINS) fail(422, `at most ${MAX_PINS} pins`);
+    return commit(next);
+  }
+
+  // A browser's lists from before the server kept pins. Each origin sends its own once, so every
+  // import is merged; a session the server already holds keeps its state.
+  function importLocal({ pinned, sticky } = {}) {
+    const next = { ...pins };
+    const add = (list, s) => {
+      for (const id of Array.isArray(list) ? list : []) {
+        if (Object.keys(next).length >= MAX_PINS) return;
+        if (isRef(id) && !(id in next)) next[id] = s;
+      }
+    };
+    add(sticky, 'sticky');
+    add(pinned, 'pinned');
+    return commit(next);
+  }
+
+  return { state, reload, set, importLocal };
+}
+
+function diff(before, after) {
+  const out = [];
+  for (const id of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (before[id] !== after[id]) out.push({ id, state: after[id] || 'none' });
+  }
+  return out;
+}
+
+module.exports = { createSessionPinStore };

package/lib/stamped-json-file.js

@@ -0,0 +1,49 @@
+const path = require('node:path');
+const { readFileSync, statSync } = require('node:fs');
+const { httpError } = require('./http-error');
+
+// A JSON file that the board keeps in memory and other boards on the same config dir also write.
+// `load` answers undefined while the file's mtime and size are the ones last read or written, and
+// null when there is no file. A file that cannot be read or parsed (a hand edit, a cut-off write,
+// EBUSY while another board renames over it) also answers undefined, so memory keeps the last good
+// state, and the next load tries again. While it cannot be read, `save` refuses with a 503, because
+// the write would replace the user's file. A failed write is a 503 too.
+function stampedJsonFile(file, writeJsonAtomic) {
+  const name = path.basename(file);
+  const stampOf = () => {
+    try {
+      const s = statSync(file);
+      return `${s.mtimeMs}:${s.size}`;
+    } catch {
+      return null;
+    }
+  };
+  let stamp;
+  let readError = null;
+  return {
+    load: () => {
+      const next = stampOf();
+      if (next === stamp && !readError) return undefined;
+      try {
+        const data = next === null ? null : JSON.parse(readFileSync(file, 'utf8'));
+        readError = null;
+        stamp = next;
+        return data;
+      } catch (e) {
+        readError = e;
+        return undefined;
+      }
+    },
+    save: (data) => {
+      if (readError) throw httpError(503, `${name} cannot be read (${readError.code || readError.message}); fix or delete it`);
+      try {
+        writeJsonAtomic(file, data);
+      } catch (e) {
+        throw httpError(503, `${name} not saved (${e.code || e.message})`);
+      }
+      stamp = stampOf();
+    },
+  };
+}
+
+module.exports = { stampedJsonFile };

package/lib/terminal.js

@@ -37,7 +37,7 @@ const MODELS = new Set(['fable', 'opus', 'sonnet', 'haiku']);
 // Extra claude args reach the command line inside plain quotes (quoteArg), so a character
 // that ends or expands those quotes in any of the shells is refused.
 // biome-ignore lint/suspicious/noControlCharactersInRegex: refuses control characters on purpose
-const EXTRA_ARG_RE = /^[^\x00-\x1f\x7f'"%]*$/;
+const EXTRA_ARG_RE = /^[^\x00-\x1f\x7f"%]*$/;
 const MAX_EXTRA_ARGS = 64;
 const MAX_EXTRA_ARG = 4096;
 // cck sets these itself, or they would start something other than a new session.
@@ -142,11 +142,11 @@ function resolveShell(value, which, platform = process.platform, env = process.e
 }
 
 // claudeArgs is null for a plain shell. Its items are fixed flags, a validated UUID, or
-// values that passed NAME_RE / WORKTREE_RE / EXTRA_ARG_RE, so plain quoting is enough to
-// keep a space from splitting an argument and nothing can break out of the quotes.
+// values that passed NAME_RE / WORKTREE_RE / EXTRA_ARG_RE. Those hold no " or %, so cmd's
+// double quotes hold them, and quotePrompt escapes the ' a path such as O'Brien can carry.
 function quoteArg(arg, family) {
   if (/^[A-Za-z0-9._-]+$/.test(arg)) return arg;
-  return family === 'cmd' ? `"${arg}"` : `'${arg}'`;
+  return family === 'cmd' ? `"${arg}"` : quotePrompt(arg, family);
 }
 
 // Free text, unlike quoteArg's input. Inside single quotes pwsh only reads a quote mark (it
@@ -182,7 +182,9 @@ function claudeArgsFor(mode, id, spec) {
   if (mode === 'new') {
     // claude takes --session-id with --resume only together with --fork-session.
     const fork = spec.forkOf ? ['--resume', spec.forkOf, '--fork-session'] : [];
-    const args = [...fork, '--session-id', id, ...(spec.extraArgs || [])];
+    // A plain resume keeps the transcript's id, so the PTY's own id is not passed on.
+    const own = spec.resume ? ['--resume', spec.resume] : ['--session-id', id];
+    const args = [...fork, ...own, ...(spec.extraArgs || [])];
     if (spec.name) args.push('--name', spec.name);
     if (spec.model) args.push('--model', spec.model);
     // Last, because its value is optional and a following flag must not be taken for it.
@@ -196,7 +198,7 @@ function claudeArgsFor(mode, id, spec) {
 function extraArgsError(args) {
   if (!Array.isArray(args) || args.length > MAX_EXTRA_ARGS) return `claude args (at most ${MAX_EXTRA_ARGS})`;
   for (const a of args) {
-    if (typeof a !== 'string' || a.length > MAX_EXTRA_ARG || !EXTRA_ARG_RE.test(a)) return 'claude arg: no quotes, % or control characters';
+    if (typeof a !== 'string' || a.length > MAX_EXTRA_ARG || !EXTRA_ARG_RE.test(a)) return 'claude arg: no double quotes, % or control characters';
     const flag = a.split('=')[0];
     if (OWNED_FLAGS.has(flag)) return `claude arg: cck sets ${flag}`;
   }
@@ -207,6 +209,8 @@ function extraArgsError(args) {
 function parseNewSpec(msg) {
   const forkOf = msg.forkOf ?? null;
   if (forkOf !== null && (typeof forkOf !== 'string' || !UUID_RE.test(forkOf))) return 'session to fork';
+  const resume = msg.resume ?? null;
+  if (resume !== null && (typeof resume !== 'string' || !UUID_RE.test(resume) || forkOf)) return 'session to resume';
   if (!forkOf && (typeof msg.cwd !== 'string' || !msg.cwd)) return 'folder';
   const name = typeof msg.name === 'string' ? msg.name.trim() : '';
   if (name && !NAME_RE.test(name)) return 'name';
@@ -227,7 +231,8 @@ function parseNewSpec(msg) {
   const bad = extraArgsError(extraArgs);
   if (bad) return bad;
   if (forkOf && worktree) return 'worktree: a fork runs in its parent session folder';
-  return { cwd: forkOf ? null : msg.cwd, forkOf, name: name || null, worktree, model, taskList, prompt: prompt || null, extraArgs, edit };
+  const restore = msg.restore !== false;
+  return { cwd: forkOf ? null : msg.cwd, forkOf, resume, name: name || null, worktree, model, taskList, prompt: prompt || null, extraArgs, edit, restore };
 }
 
 function samePath(a, b) {
@@ -258,7 +263,11 @@ function screenText(term) {
 // show tool posts to.
 function ptyEnv({ claudeDir, isDefaultDir, noFlicker, cckUrl, terminalId }) {
   const env = { ...process.env };
+  const inHub = !!env.CLAUDE_HUB;
   for (const k of STRIP_ENV) delete env[k];
+  // Claude Code reports TERM_PROGRAM as the metrics attribute terminal_type.
+  env.TERM_PROGRAM = inHub ? 'claude-code-hub' : 'claude-code-kanban';
+  delete env.TERM_PROGRAM_VERSION;
   if (isDefaultDir) delete env.CLAUDE_CONFIG_DIR;
   else env.CLAUDE_CONFIG_DIR = claudeDir;
   if (cckUrl) env.CCK_URL = cckUrl;
@@ -418,7 +427,7 @@ function createTerminalService(o) {
       if (savedTerminalIds[id]) terminalIds[id] = savedTerminalIds[id];
     }
     for (const s of sessions.values()) {
-      if (s.ended || s.claudeExitedAt || !RESTORABLE_MODES.has(s.mode)) continue;
+      if (s.ended || s.claudeExitedAt || !RESTORABLE_MODES.has(s.mode) || !s.restore) continue;
       ids.add(s.id);
       if (s.taskList) taskLists[s.id] = s.taskList;
       terminalIds[s.id] = s.terminalId;
@@ -544,8 +553,10 @@ function createTerminalService(o) {
     if (moved) changed();
   }
 
+  // A resumed transcript keeps its own id, which is not the PTY's.
   function ownEntry(live, s, since) {
-    return live.find((l) => l.pid && l.sessionId === s.id && l.startedAt >= since - PICK_START_SLACK_MS);
+    const sid = s.resumeOf || s.id;
+    return live.find((l) => l.pid && l.sessionId === sid && l.startedAt >= since - PICK_START_SLACK_MS);
   }
 
   // claude writes its registry entry a moment after it starts, so the pid is polled for.
@@ -595,7 +606,7 @@ function createTerminalService(o) {
     const s = {
       id, terminalId, mode, cwd, pty: proc, term, serializer, sockets: new Set(), exited: false, ended: false, paused: false, startedAt: Date.now(),
       name: spec?.name || null, worktree: spec?.worktree || false, taskList, onOutput: null, edit: !!spec?.edit,
-      forkOf: spec?.forkOf || null,
+      forkOf: spec?.forkOf || null, resumeOf: spec?.resume || null, restore: spec?.restore !== false,
     };
     if (s.edit) queueText(s, claudeCommand(shell, claudeArgs, spec.prompt), false);
     else if (spec?.prompt) queueText(s, spec.prompt, true);
@@ -744,6 +755,9 @@ function createTerminalService(o) {
     if (mode === 'new') {
       spec = parseNewSpec(msg);
       if (typeof spec === 'string') return { code: 4002, status: 400, error: `invalid ${spec}` };
+      if (spec.resume && o.isLiveElsewhere(spec.resume)) {
+        return { code: 4006, status: 409, error: 'the session to resume is running in another terminal' };
+      }
       if (spec.edit && spec.prompt && shellFamily(shell) === 'cmd') {
         return { code: 4002, status: 400, error: 'cmd cannot take a typed prompt; clear the prompt or set the terminal shell to pwsh or gitbash' };
       }
@@ -756,7 +770,7 @@ function createTerminalService(o) {
       cwd = spec?.forkOf ? forkCwd : msg.cwd;
       if (spec?.forkOf && cwd === null) return { code: 4004, status: 404, error: 'unknown session to fork' };
       if (!spec?.forkOf && (typeof cwd !== 'string' || !(await o.isAllowedFolder(cwd)))) {
-        return { code: 4004, status: 403, error: 'folder is not a known project or a folder picked in this run' };
+        return { code: 4004, status: 404, error: 'folder does not exist' };
       }
     } else if (mode !== 'shell' && known === null) {
       return { code: 4004, status: 404, error: 'unknown session' };
@@ -803,7 +817,7 @@ function createTerminalService(o) {
   function list() {
     return [...sessions.values()].filter((s) => !s.ended).map((s) => ({
       id: s.id, terminalId: s.terminalId, mode: s.mode, cwd: s.cwd, pid: s.pty.pid, clients: s.sockets.size, startedAt: s.startedAt,
-      name: s.name, worktree: s.worktree, edit: s.edit, forkOf: s.forkOf,
+      name: s.name, worktree: s.worktree, edit: s.edit, forkOf: s.forkOf, claudeExited: !!s.claudeExitedAt,
     }));
   }
 
@@ -878,4 +892,4 @@ function createTerminalService(o) {
   return { token, handleUpgrade, clientConfig, list, claudePids, isRunning, end, authorized, startNew, paste, restore, shutdown, unavailableReason };
 }
 
-module.exports = { createTerminalService, readTerminalConfig, localUnavailableReason, refuseUpgrade, clientConfigFor, ptyEnv, shellArgs, claudeCommand, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };
+module.exports = { MODELS,createTerminalService, readTerminalConfig, localUnavailableReason, refuseUpgrade, clientConfigFor, ptyEnv, shellArgs, claudeCommand, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };