@volter/supercode-orchestrator 0.4.17 → 0.4.19

package/board/cli.mjs

@@ -1,55 +1,73 @@
 // `supercode workflow <verb>` (docs/architecture/orchestrator.md §2.9): supercode's own board, in Hermes Kanban's
-// format, and its dispatcher. The Rust CLI hands every verb but `load` to `bin/orchestrator.mjs workflow`, which
-// lands here. The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`, else `HERMES_HOME`; the board is
-// `--board <slug>` (default `default`). Every verb prints a line for a person, or one JSON object with `--json`.
-import { existsSync } from 'node:fs';
+// format, and its dispatcher. Every verb of `hermes kanban` is here under its own name, with its own flags and its own
+// output lines, so a caller of Hermes's CLI calls this one unchanged; supercode's own verbs (`move`, `adopt`, `close`,
+// `serve`, `--at`) are added beside them. The Rust CLI hands every verb but `load` to `bin/orchestrator.mjs workflow`,
+// which lands here. The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`, else `HERMES_HOME`; the board is
+// `--board <slug>`, else `HERMES_KANBAN_BOARD`, else the home's current board (`kanban/current`), else `default`.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { basename, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import { resolve } from 'node:path';
 import { read } from '../orchestration.mjs';
 import { holdDispatcherLock } from '../hermes-locks.mjs';
-import { boardPath, DEFAULT_BOARD, event, listBoards, openBoard, tx } from './store.mjs';
+import { boardPath, DEFAULT_BOARD, event, json, listBoards, now, openBoard, tx } from './store.mjs';
 import * as engine from './engine.mjs';
-import { attachSession, boardLabel, boardSettings, lanesOf, observeFleet, tick } from './dispatch.mjs';
+import { adoptSession, boardLabel, boardSettings, lanesOf, localMachine, observeFleet, paused, startTriageSession, tick } from './dispatch.mjs';
 
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
-  create <title> [--body T] [--assignee PROFILE] [--machine M] [--workspace dir:<path>|scratch|worktree[:<path>]]
-         [--branch B] [--parent ID]... [--priority N] [--tenant T] [--triage] [--idempotency-key K] [--max-runtime SECONDS]
-         [--max-retries N] [--skill S]... [--model M] [--provider P] [--created-by NAME] [--notify ADDRESS | --no-notify]
-         [--subtask-of ARC] [--no-start]
-      File a card. With a lane and capacity it starts at once and answers "started" with its session; otherwise it
-      answers why it waits, and its creator is told when it starts. A subtask is worked by its arc's session and never
-      starts on its own; another card may wait on it (link).
-  list [--status S] [--assignee P] [--machine M] [--all]     show <id>     context <id>
-  comment <id> <text> [--author NAME]      complete <id> [--summary T] [--result T]
-  block <id> [reason] [--kind dependency|needs_input|capability|transient]      unblock <id>
-  review <id> [--summary T] [--reviewer P]     changes <id> [--reason T] [--reviewer P]
-  schedule <id> [reason]     promote <id> [--force]     reclaim <id> [reason]     archive <id>
-  assign <id> <profile|none>     move <id> <machine|none>     link <parent> <child>     unlink <parent> <child>
-  subscribe <id> [--address A] [--role creator|worker|dependency]     unsubscribe <id> [--address A]
-  close <id>                close the session of a card that is not running (an idle session holds its machine's place)
-  attach <id> <session> [--workspace dir:<path>]
-                            put a live session the board did not start on the card (an address, id or name@machine the
-                            fleet lists); the board watches, resumes and tells it from then on
-
-  A card's own session may comment on, block (with --kind) or send to review its card, and create, complete, block and
-  comment on its subtasks; its arc is marked done by its reviewers, never by itself.
-  init                      create the board if it does not exist
-  dispatch                  one dispatcher tick over every board of the home
-  serve                     the dispatcher, a tick every kanban.dispatch_interval_seconds, until SIGTERM
+Hermes Kanban's verbs, with their flags:
+  init · boards list|create|rm|switch|show|rename|set-default-workdir|export|import
+  create <title> [--body] [--assignee] [--parent]... [--workspace scratch|worktree[:<path>]|dir:<path>] [--branch] [--project]
+         [--tenant] [--priority] [--triage] [--idempotency-key] [--max-runtime 30m] [--created-by] [--skill]... [--max-retries]
+         [--model] [--provider] [--goal] [--goal-max-turns] [--initial-status blocked|running]
+  swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
+  list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   runs <id>
+  assign <id> <profile|none>   reassign <id> <profile> [--reclaim] [--reason]   set-model <id> [model] [--provider]
+  claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note]   link|unlink <parent> <child>
+  comment <id> <text> [--author] [--max-len]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
+  complete <id>... [--result] [--summary] [--metadata JSON]   edit <id> --result [--summary] [--metadata]
+  block <id> [reason] [--kind dependency|needs_input|capability|transient] [--ids ...]   schedule <id> [reason] [--ids ...]
+  unblock <id>...   request-review <id> [--summary] [--reviewer]   request-changes <id> <reason>   reopen-review <id>...
+  promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... [--rm <id>...]
+  specify <id> [--title --body] [--all]   decompose <id> [--child "<title>[@<profile>]"]... [--all]
+  diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
+  notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
+  dispatch [--dry-run] [--max N] [--failure-limit N]   daemon   gc [--event-retention-days] [--log-retention-days]   repair
+  pause [reason] · resume   (Hermes's emergency stop, the ESTOP file: new starts stop, running sessions go on)
+
+supercode's own:
+  create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
+      With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
+      waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
+  move <id> <machine|none>   adopt <id> <session>   close <id>   serve (= daemon)   list --machine M
+  notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
+  Any verb … --at sc:<machine>:board:<home>: sent as mail to a board kept on another machine.
+
+  specify/decompose with no spec start a session on the triage card to write it. A card's own session may comment on,
+  block (with --kind), heartbeat and request review of its card, specify or decompose it in triage, and file, complete,
+  block and comment on its subtasks; its arc is marked done by its reviewers, never by itself.
 `;
 
-const MULTI = new Set(['parent', 'skill']);
-const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help']);
+const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm']);
+const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'reclaim', 'dry-run',
+  'goal', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose']);
+// flags that take every following word up to the next flag (Hermes's nargs='+')
+const GREEDY = new Set(['ids', 'rm']);
 
 function parse(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
-    if (!a.startsWith('--')) { out._.push(a); continue; }
+    if (!a.startsWith('--') || a === '--') { out._.push(a); continue; }
     const [key, inline] = a.slice(2).split(/=(.*)/s);
     if (FLAGS.has(key)) { out[key] = true; continue; }
+    if (GREEDY.has(key)) {
+      const values = inline !== undefined ? [inline] : [];
+      while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) values.push(argv[++i]);
+      (out[key] ??= []).push(...values);
+      continue;
+    }
     const value = inline ?? argv[++i];
     if (value === undefined) throw new Error(`--${key} needs a value`);
     if (MULTI.has(key)) (out[key] ??= []).push(value);
@@ -64,11 +82,74 @@ function homeOf(args) {
   return resolve(root);
 }
 
+const SLUG = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+function normalSlug(slug) {
+  const s = String(slug ?? '').trim().toLowerCase();
+  if (!SLUG.test(s)) throw new Error(`invalid board slug ${slug}: 1-64 lowercase letters, digits, - or _, not starting with - or _`);
+  return s;
+}
+
+const currentFile = (root) => join(root, 'kanban', 'current');
+
+/** The board a verb acts on, as Hermes resolves it. */
+function boardOf(root, args) {
+  for (const want of [args.board, process.env.HERMES_KANBAN_BOARD, existsSync(currentFile(root)) ? readFileSync(currentFile(root), 'utf8').trim() : null]) {
+    if (!want) continue;
+    const slug = normalSlug(want);
+    if (slug === DEFAULT_BOARD || existsSync(boardPath(root, slug))) return slug;
+    if (want === args.board) return slug;
+  }
+  return DEFAULT_BOARD;
+}
+
+const boardDir = (root, slug) => join(root, 'kanban', 'boards', slug);
+const metaPath = (root, slug) => join(boardDir(root, slug), 'board.json');
+
+function boardMeta(root, slug) {
+  const meta = { slug, name: slug === DEFAULT_BOARD ? 'Default' : slug, description: '', icon: '', color: '', default_workdir: null, project_id: null, created_at: null, archived: false };
+  try { Object.assign(meta, JSON.parse(readFileSync(metaPath(root, slug), 'utf8')), { slug }); } catch { /* no metadata yet */ }
+  return { ...meta, db_path: boardPath(root, slug) };
+}
+
+function writeMeta(root, slug, patch) {
+  const { db_path: _, ...meta } = boardMeta(root, slug);
+  for (const [k, v] of Object.entries(patch)) if (v !== undefined) meta[k] = v;
+  meta.created_at ??= now();
+  mkdirSync(boardDir(root, slug), { recursive: true });
+  writeFileSync(metaPath(root, slug), `${JSON.stringify(meta, null, 2)}\n`);
+  return { ...meta, db_path: boardPath(root, slug) };
+}
+
+/** Hermes's list: the default board and every named one with a database or metadata. */
+function boardsOf(root, { includeArchived = true } = {}) {
+  const out = [boardMeta(root, DEFAULT_BOARD)];
+  const dir = join(root, 'kanban', 'boards');
+  if (existsSync(dir)) {
+    for (const slug of readdirSync(dir).sort()) {
+      if (slug === DEFAULT_BOARD || !SLUG.test(slug)) continue;
+      if (!existsSync(boardPath(root, slug)) && !existsSync(metaPath(root, slug))) continue;
+      const meta = boardMeta(root, slug);
+      if (meta.archived && !includeArchived) continue;
+      out.push(meta);
+    }
+  }
+  return out;
+}
+
+function counts(root, slug) {
+  if (!existsSync(boardPath(root, slug))) return {};
+  const b = openBoard(root, slug);
+  try {
+    return Object.fromEntries(b.db.prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status').all().map((r) => [r.status, Number(r.n)]));
+  } finally { b.close(); }
+}
+
 /** The home's lanes (profiles' workers) and board settings (the root config's `kanban:` block), as the IR reads them. */
 async function laneState(root) {
   const orchestration = await read(root);
   const kanban = orchestration.profiles?.default?.residue?.config?.kanban ?? {};
-  return { lanes: lanesOf(orchestration.profiles), settings: boardSettings(kanban), kanban };
+  return { lanes: lanesOf(orchestration.profiles), settings: boardSettings(kanban), kanban, profiles: Object.keys(orchestration.profiles ?? {}) };
 }
 
 /** The caller's own supercode address, when it is a session supercode can reach (for its card's notices). */
@@ -79,22 +160,56 @@ function callerAddress() {
   return [...fleet.alive].find((a) => a.endsWith(`:${id}`)) ?? null;
 }
 
-const say = (args, human, value) => { process.stdout.write(args.json ? `${JSON.stringify(value)}\n` : `${human}\n`); };
+const callerName = () => process.env.HERMES_PROFILE || process.env.USER || 'user';
 
-function row(t) {
-  return `${t.id}  ${t.status.padEnd(9)} ${(t.assignee ?? '-').padEnd(14)} ${(t.machine ?? '-').padEnd(20)} ${t.title}`;
+const say = (args, human, value) => { process.stdout.write(args.json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`); };
+
+// Hermes's own output lines, so a reader of `hermes kanban list` reads this one
+const ICONS = { todo: '◻', ready: '▶', running: '●', scheduled: '⏱', blocked: '⊘', done: '✓', archived: '—' };
+const ts = (t) => {
+  if (!t) return '';
+  const d = new Date(Number(t) * 1000);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+};
+const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${t.status.padEnd(8)}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+const cardDict = (t) => ({
+  id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant,
+  workspace_kind: t.workspace_kind, workspace_path: t.workspace_path, branch_name: t.branch_name, project_id: t.project_id,
+  created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
+  skills: t.skills ?? [], max_retries: t.max_retries, model_override: t.model_override, provider_override: t.provider_override,
+  session_id: t.session_id, workflow_template_id: t.workflow_template_id, current_step_key: t.current_step_key,
+  machine: t.machine ?? null, subtask_of: t.subtask_of ?? null,
+});
+
+/** Hermes's durations: seconds, or 30s / 5m / 2h / 1d. */
+function duration(v) {
+  if (v === undefined || v === null || v === '') return null;
+  const s = String(v).trim().toLowerCase();
+  if (/^\d+$/.test(s)) return Number(s);
+  const m = /^(\d+(?:\.\d+)?)([smhd])$/.exec(s);
+  if (!m) throw new Error(`malformed duration ${v} (expected 30s, 5m, 2h, 1d, or a number)`);
+  return Math.floor(Number(m[1]) * { s: 1, m: 60, h: 3600, d: 86400 }[m[2]]);
 }
 
+const metadataOf = (v) => {
+  if (v === undefined) return undefined;
+  const got = json(v, undefined);
+  if (got === undefined || typeof got !== 'object') throw new Error('--metadata is a JSON object');
+  return got;
+};
+
 export async function runWorkflow(argv) {
   const args = parse(argv);
   const [verb, ...rest] = args._;
   if (!verb || verb === 'help' || args.help) { process.stdout.write(HELP); return 0; }
   const root = homeOf(args);
-  const slug = args.board ?? DEFAULT_BOARD;
+  const slug = boardOf(root, args);
   const open = (create = false) => { const b = openBoard(root, slug, { create }); b.label = boardLabel(root, slug); return b; };
   const withBoard = (fn, create = false) => { const b = open(create); try { return fn(b); } finally { b.close(); } };
   const id = rest[0];
   const need = (n, what) => { if (rest.length < n) throw new Error(`${verb} needs ${what}`); };
+  const ids = (first = rest) => [...first, ...(args.ids ?? [])];
 
   // a caller that is a card's own session (its harness names it; the board recorded which session it launched)
   const sid = process.env.CLAUDE_CODE_SESSION_ID || process.env.CODEX_THREAD_ID;
@@ -103,34 +218,34 @@ export async function runWorkflow(argv) {
   }
 
   switch (verb) {
-    case 'close': {
-      need(1, 'a card id');
-      const closed = withBoard((b) => closeSession(b, id));
-      say(args, closed ? `closed ${closed.session_id} (pane ${closed.pane} on ${closed.machine})` : `${id} has no live session`, { ok: true, closed });
+    case 'init': {
+      withBoard(() => {}, true);
+      const { profiles } = await laneState(root).catch(() => ({ profiles: [] }));
+      say(args, `Kanban DB initialized at ${boardPath(root, slug)}\n\n${profiles.length ? `Profiles of this home (any can be an --assignee): ${profiles.join(', ')}` : 'No profiles in this home.'}\nThe dispatcher: \`supercode workflow serve\`, or the orchestrator while it serves the home.`, { ok: true, board: slug, path: boardPath(root, slug), profiles });
       return 0;
     }
-    case 'attach': {
-      need(2, 'a card id and a session');
-      const { settings } = await laneState(root);
-      const got = withBoard((b) => attachSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl }));
-      say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });
-      return 0;
-    }
-    case 'init': withBoard(() => {}, true); say(args, `board ${slug} ready in ${root}`, { ok: true, board: slug }); return 0;
+
+    case 'boards': return boardsVerb(root, rest, args);
+
     case 'create': {
       need(1, 'a title');
       const { lanes, settings } = await laneState(root);
+      const maxRetries = args['max-retries'] !== undefined ? Number(args['max-retries']) : null;
+      if (maxRetries !== null && !(maxRetries >= 1)) throw new Error(`--max-retries must be >= 1 (got ${args['max-retries']}); use 1 to trip on the first failure`);
+      const meta = boardMeta(root, slug);
+      let workspace = args.workspace;
+      if ((workspace === 'dir' || workspace === 'worktree') && meta.default_workdir) workspace = `${workspace}:${meta.default_workdir}`;
       const created = withBoard((b) => engine.createCard(b, {
         title: rest.join(' '), body: args.body, assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
-        workspace: args.workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
-        triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: args['max-runtime'] ? Number(args['max-runtime']) : null,
-        maxRetries: args['max-retries'] ? Number(args['max-retries']) : null, skills: args.skill, model: args.model,
-        provider: args.provider, createdBy: args['created-by'] ?? callerName(), sessionId: process.env.CLAUDE_CODE_SESSION_ID ?? null,
-        subtaskOf: args['subtask-of'] ?? null,
+        workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
+        triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
+        maxRetries, skills: args.skill, model: args.model, provider: args.provider, createdBy: args['created-by'] ?? callerName(),
+        sessionId: process.env.CLAUDE_CODE_SESSION_ID ?? null, subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
+        project: args.project ?? meta.project_id ?? null, goal: args.goal ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : null,
       }), true);
       let answer = { id: created.id, existing: created.existing };
       if (!args['no-start'] && !created.existing && !args['subtask-of']) {
-        const [report] = tick({ root, lanes, settings, only: created.id, slugs: [slug] });
+        const [report] = await tick({ root, lanes, settings, only: created.id, slugs: [slug] });
         const started = report.started.find(([t]) => t === created.id);
         const queued = report.queued.find(([t]) => t === created.id);
         const failed = report.failed.find(([t]) => t === created.id);
@@ -139,115 +254,691 @@ export async function runWorkflow(argv) {
       // the creator hears what happens from here on; a start answered above is not told twice
       const address = args['no-notify'] ? null : args.notify ?? callerAddress();
       if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator'));
-      const status = withBoard((b) => tx(b, (db) => engine.getTask(db, created.id)));
-      answer = { ...answer, status: status.status, notify: address ?? null };
-      const line = answer.started ? `started ${created.id}: session ${answer.session} (${answer.mode})`
-        : answer.failed ? `${created.id} did not start: ${answer.failed}`
-          : answer.waits ? `${created.id} waits: ${answer.waits}`
-            : `${created.existing ? 'existing' : 'created'} ${created.id} (${status.status})`;
-      say(args, `${line}${address ? `; notices go to ${address}` : ''}`, answer);
+      const task = withBoard((b) => tx(b, (db) => engine.getTask(db, created.id)));
+      if (args.json) { say(args, '', { ...cardDict(task), ...answer, notify: address ?? null }); return answer.failed ? 1 : 0; }
+      const said = answer.started ? `; started session ${answer.session} (${answer.mode})` : answer.failed ? `; did not start: ${answer.failed}` : answer.waits ? `; waits: ${answer.waits}` : '';
+      say(args, `${created.existing ? 'Existing' : 'Created'} ${created.id}  (${task.status}, assignee=${task.assignee || '-'})${said}${address ? `; notices go to ${address}` : ''}`, null);
       return answer.failed ? 1 : 0;
     }
-    case 'list': {
-      const cards = withBoard((b) => engine.listCards(b.db, { status: args.status, assignee: args.assignee, machine: args.machine, includeArchived: args.all }));
-      if (args.json) say(args, '', cards); else process.stdout.write(`${cards.map(row).join('\n')}${cards.length ? '\n' : ''}`);
+
+    case 'swarm': {
+      need(1, 'a goal');
+      const workers = (args.worker ?? []).map((w) => {
+        const [profile, title, skills] = w.split(':');
+        if (!profile || !title) throw new Error(`--worker is PROFILE:TITLE[:SKILL,SKILL], not ${w}`);
+        return { profile, title, skills: skills ? skills.split(',').map((x) => x.trim()).filter(Boolean) : [] };
+      });
+      if (!args.verifier || !args.synthesizer) throw new Error('a swarm names its --verifier and --synthesizer');
+      const made = withBoard((b) => engine.swarm(b, { goal: rest.join(' '), workers, verifier: args.verifier, synthesizer: args.synthesizer, tenant: args.tenant ?? null, createdBy: args['created-by'] ?? callerName(), priority: Number(args.priority) || 0, idempotencyKey: args['idempotency-key'] ?? null }), true);
+      say(args, `Swarm root: ${made.root_id}\nWorkers: ${(made.worker_ids ?? []).join(', ')}\nVerifier: ${made.verifier_id}\nSynthesizer: ${made.synthesizer_id}`, made);
       return 0;
     }
+
+    case 'list': case 'ls': {
+      const assignee = args.assignee ?? (args.mine ? callerName() : null);
+      const cards = withBoard((b) => {
+        engine.recomputeReady(b);
+        let rows = engine.listCards(b.db, { status: args.status, assignee, machine: args.machine, includeArchived: args.archived || args.all });
+        if (args.tenant) rows = rows.filter((t) => t.tenant === args.tenant);
+        if (args.session) rows = rows.filter((t) => t.session_id === args.session);
+        if (args['workflow-template-id']) rows = rows.filter((t) => t.workflow_template_id === args['workflow-template-id']);
+        if (args['step-key']) rows = rows.filter((t) => t.current_step_key === args['step-key']);
+        return rows;
+      });
+      const sorters = {
+        assignee: (a, b) => String(a.assignee ?? '').localeCompare(String(b.assignee ?? '')), created: (a, b) => a.created_at - b.created_at,
+        'created-desc': (a, b) => b.created_at - a.created_at, priority: (a, b) => a.priority - b.priority, 'priority-desc': (a, b) => b.priority - a.priority,
+        status: (a, b) => a.status.localeCompare(b.status), title: (a, b) => a.title.localeCompare(b.title),
+        updated: (a, b) => (b.completed_at ?? b.started_at ?? b.created_at) - (a.completed_at ?? a.started_at ?? a.created_at),
+      };
+      if (args.sort) { if (!sorters[args.sort]) throw new Error(`--sort is one of ${Object.keys(sorters).join(', ')}`); cards.sort(sorters[args.sort]); }
+      if (args.json) { say(args, '', cards.map(cardDict)); return 0; }
+      const others = boardsOf(root, { includeArchived: false }).length - 1;
+      if (others > 0) process.stdout.write(`Board: ${slug} (${others} other board${others === 1 ? '' : 's'} — \`supercode workflow boards list\`)\n\n`);
+      process.stdout.write(cards.length ? `${cards.map(line).join('\n')}\n` : '(no matching tasks)\n');
+      return 0;
+    }
+
     case 'show': {
       need(1, 'a card id');
-      const card = withBoard((b) => engine.showCard(b.db, id));
-      if (args.json) { say(args, '', card); return 0; }
+      const { settings } = await laneState(root).catch(() => ({ settings: boardSettings({}) }));
+      const card = withBoard((b) => {
+        const got = engine.showCard(b.db, id);
+        got.runs = engine.runs(b.db, id, { stateType: args['state-type'] ?? null, stateName: args['state-name'] ?? null });
+        got.diagnostics = engine.diagnose(b.db, got.task, { failureLimit: settings.failureLimit });
+        return got;
+      });
       const t = card.task;
-      const lines = [row(t), t.body ? `\n${t.body}\n` : ''];
-      if (card.parents.length) lines.push(`parents: ${card.parents.map((p) => `${p.id} (${p.status})`).join(', ')}`);
-      if (card.children.length) lines.push(`children: ${card.children.join(', ')}`);
-      if (t.subtask_of) lines.push(`subtask of ${t.subtask_of}`);
-      for (const st of card.subtasks) lines.push(`subtask ${st.id} [${st.status}] ${st.title}`);
-      for (const r of card.runs) {
-        const s = r.metadata?.supercode;
-        const who = s ? (s.session_id ? `session ${s.session_id}${s.pane ? ` in pane ${s.pane}` : ''}` : `worker pid ${s.pid}`) : '';
-        lines.push(`run ${r.id}: ${r.status}${r.outcome ? ` / ${r.outcome}` : ''}${s ? ` — ${who} on ${s.machine} (${s.mode})` : ''}${r.summary ? ` — ${r.summary.split('\n')[0]}` : ''}`);
+      const latest = [...card.runs].reverse().find((r) => r.summary)?.summary ?? null;
+      if (args.json) {
+        say(args, '', { task: cardDict(t), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
+        return 0;
+      }
+      const out = [`Task ${t.id}: ${t.title}`, `  status:    ${t.status}`, `  assignee:  ${t.assignee || '-'}`];
+      if (t.machine) out.push(`  machine:   ${t.machine}`);
+      if (t.subtask_of) out.push(`  subtask of: ${t.subtask_of}`);
+      if (t.tenant) out.push(`  tenant:    ${t.tenant}`);
+      out.push(`  workspace: ${t.workspace_kind}${t.workspace_path ? ` @ ${t.workspace_path}` : ''}`);
+      if (t.branch_name) out.push(`  branch:    ${t.branch_name}`);
+      if (t.skills?.length) out.push(`  skills:    ${t.skills.join(', ')}`);
+      if (t.model_override) out.push(`  model:     ${t.model_override}${t.provider_override ? ` (provider: ${t.provider_override})` : ''}`);
+      out.push(`  max-retries: ${t.max_retries ?? settings.failureLimit} (${t.max_retries !== null ? 'task' : 'board'})`);
+      out.push(`  created:   ${ts(t.created_at)} by ${t.created_by || '-'}`);
+      if (card.diagnostics.length) {
+        out.push('', `  Diagnostics (${card.diagnostics.length}):`);
+        for (const d of card.diagnostics) { out.push(`    ${{ warning: '⚠', error: '!!', critical: '!!!' }[d.severity]} [${d.severity}] ${d.title}`); for (const a of d.actions.slice(0, 1)) out.push(`       → ${a}`); }
       }
-      for (const c of card.comments) lines.push(`${c.author}: ${c.body}`);
-      for (const s of card.subscriptions) lines.push(`notices → ${s.chat_id} (${s.delivery_metadata?.role ?? s.platform})`);
-      process.stdout.write(`${lines.filter(Boolean).join('\n')}\n`);
+      if (t.started_at) out.push(`  started:   ${ts(t.started_at)}`);
+      if (t.completed_at) out.push(`  completed: ${ts(t.completed_at)}`);
+      if (card.parents.length) out.push(`  parents:   ${card.parents.map((p) => p.id).join(', ')}`);
+      if (card.children.length) out.push(`  children:  ${card.children.join(', ')}`);
+      if (card.subtasks.length) out.push(`  subtasks:  ${card.subtasks.map((s) => `${s.id} (${s.status})`).join(', ')}`);
+      if (t.body) out.push('', 'Body:', t.body);
+      if (t.result) out.push('', 'Result:', t.result);
+      else if (latest) out.push('', 'Latest summary:', latest);
+      if (card.comments.length) { out.push('', `Comments (${card.comments.length}):`); for (const c of card.comments) out.push(`  [${ts(c.created_at)}] ${c.author}: ${c.body}`); }
+      if (card.events.length) {
+        out.push('', `Events (${card.events.length}):`);
+        for (const e of card.events.slice(-20)) out.push(`  [${ts(e.created_at)}]${e.run_id ? ` [run ${e.run_id}]` : ''} ${e.kind}${e.payload ? ` ${JSON.stringify(e.payload)}` : ''}`);
+      }
+      if (card.runs.length) {
+        out.push('', `Runs (${card.runs.length}):`);
+        for (const r of card.runs) {
+          const s = r.metadata?.supercode;
+          out.push(`  #${String(r.id).padEnd(3)} ${(r.outcome || r.status || 'active').padEnd(12)} @${r.profile || '-'}  ${r.ended_at ? `${Math.max(0, r.ended_at - r.started_at)}s` : 'active'}  ${ts(r.started_at)}`);
+          if (s) out.push(`        ⇢ ${s.session_id ? `session ${s.session_id}${s.pane ? ` in pane ${s.pane}` : ''}` : `worker pid ${s.pid}`} on ${s.machine} (${s.mode})`);
+          if (r.summary) out.push(`        → ${r.summary.split('\n')[0].slice(0, 160)}`);
+          if (r.error) out.push(`        ! ${r.error.split('\n')[0].slice(0, 160)}`);
+        }
+      }
+      if (card.subscriptions.length) { out.push('', 'Notices:'); for (const s of card.subscriptions) out.push(`  → ${s.chat_id} (${s.platform === 'supercode' ? s.delivery_metadata?.role ?? 'creator' : s.platform})`); }
+      process.stdout.write(`${out.join('\n')}\n`);
       return 0;
     }
+
     case 'context': need(1, 'a card id'); process.stdout.write(`${withBoard((b) => tx(b, (db) => engine.cardContext(db, id)))}\n`); return 0;
+
+    case 'runs': {
+      need(1, 'a card id');
+      const got = withBoard((b) => engine.runs(b.db, id, { stateType: args['state-type'] ?? null, stateName: args['state-name'] ?? null }));
+      if (args.json) { say(args, '', got); return 0; }
+      process.stdout.write(got.length ? `${got.map((r) => `#${r.id}  ${(r.outcome || r.status).padEnd(14)} @${r.profile || '-'}  ${ts(r.started_at)}${r.ended_at ? ` → ${ts(r.ended_at)}` : ' (active)'}${r.metadata?.supercode?.address ? `  ${r.metadata.supercode.address}` : ''}${r.summary ? `\n     → ${r.summary.split('\n')[0].slice(0, 160)}` : ''}`).join('\n')}\n` : `(no runs for ${id})\n`);
+      return 0;
+    }
+
+    case 'assign': need(2, 'a card id and a profile (or none)'); withBoard((b) => engine.assign(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `Assigned ${id} to ${rest[1] === 'none' ? '(nobody)' : rest[1]}`, { ok: true }); return 0;
+    case 'reassign': {
+      need(2, 'a card id and a profile');
+      withBoard((b) => {
+        const task = tx(b, (db) => engine.getTask(db, id));
+        if (task?.status === 'running' && args.reclaim) engine.reclaim(b, id, args.reason ?? 'reassign');
+        engine.assign(b, id, rest[1] === 'none' ? null : rest[1]);
+      });
+      say(args, `Reassigned ${id} to ${rest[1]}`, { ok: true }); return 0;
+    }
+    case 'set-model': need(1, 'a card id'); withBoard((b) => engine.setModel(b, id, rest[1] ?? null, args.provider ?? null)); say(args, rest[1] ? `${id} runs on model ${rest[1]}${args.provider ? ` (${args.provider})` : ''} from its next start` : `${id} uses its profile's model`, { ok: true }); return 0;
+    case 'move': need(2, 'a card id and a machine (or none)'); withBoard((b) => engine.setMachine(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `${id} runs on ${rest[1]}`, { ok: true }); return 0;
+
+    case 'claim': {
+      need(1, 'a card id');
+      const ttl = args.ttl ? duration(args.ttl) : engine.claimTtl();
+      const runId = withBoard((b) => engine.claim(b, id, { ttl }));
+      if (!runId) throw new Error(`cannot claim ${id} (not ready, already claimed, or waiting on parents)`);
+      const task = withBoard((b) => tx(b, (db) => engine.getTask(db, id)));
+      // Hermes's claim resolves the workspace and prints it; a scratch one is made under the board's workspaces
+      let workspace = task.workspace_path;
+      if (!workspace && task.workspace_kind === 'scratch') {
+        workspace = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'workspaces') : join(boardDir(root, slug), 'workspaces'), id);
+        mkdirSync(workspace, { recursive: true });
+        withBoard((b) => tx(b, (db) => db.prepare('UPDATE tasks SET workspace_path = ? WHERE id = ?').run(workspace, id)));
+      }
+      say(args, workspace ?? `(claimed ${id}; its ${task.workspace_kind} workspace is made where it starts)`, { ok: true, run_id: runId, workspace });
+      return 0;
+    }
+    case 'reclaim': need(1, 'a card id'); withBoard((b) => engine.reclaim(b, id, args.reason ?? (rest.slice(1).join(' ') || null))); say(args, `Reclaimed ${id}`, { ok: true }); return 0;
+    case 'heartbeat': need(1, 'a card id'); withBoard((b) => engine.heartbeat(b, id, args.note ?? null)); say(args, `Heartbeat recorded for ${id}`, { ok: true }); return 0;
+
+    case 'link': need(2, 'a parent and a child'); withBoard((b) => engine.link(b, rest[0], rest[1])); say(args, `Linked ${rest[0]} -> ${rest[1]}`, { ok: true }); return 0;
+    case 'unlink': { need(2, 'a parent and a child'); const gone = withBoard((b) => engine.unlink(b, rest[0], rest[1])); say(args, gone ? `Unlinked ${rest[0]} -> ${rest[1]}` : `no link ${rest[0]} -> ${rest[1]}`, { ok: gone }); return gone ? 0 : 1; }
+
     case 'comment': {
       need(2, 'a card id and the text');
-      const n = withBoard((b) => engine.comment(b, id, args.author ?? callerAddress() ?? callerName(), rest.slice(1).join(' ')));
-      say(args, `commented on ${id}`, { ok: true, comment: n }); return 0;
-    }
-    case 'complete': need(1, 'a card id'); withBoard((b) => engine.complete(b, id, { summary: args.summary ?? null, result: args.result ?? null })); say(args, `${id} done`, { ok: true }); return 0;
-    case 'block': { need(1, 'a card id'); const s = withBoard((b) => engine.block(b, id, { reason: rest.slice(1).join(' ') || null, kind: args.kind ?? null })); say(args, `${id} ${s}`, { ok: true, status: s }); return 0; }
-    case 'unblock': { need(1, 'a card id'); const s = withBoard((b) => engine.unblock(b, id)); say(args, `${id} ${s}`, { ok: true, status: s }); return 0; }
-    case 'review': need(1, 'a card id'); withBoard((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null })); say(args, `${id} in review`, { ok: true }); return 0;
-    case 'changes': need(1, 'a card id'); withBoard((b) => engine.requestChanges(b, id, { reason: args.reason ?? null, reviewer: args.reviewer ?? null })); say(args, `${id} sent back`, { ok: true }); return 0;
-    case 'schedule': need(1, 'a card id'); withBoard((b) => engine.schedule(b, id, rest.slice(1).join(' ') || null)); say(args, `${id} scheduled`, { ok: true }); return 0;
-    case 'promote': need(1, 'a card id'); withBoard((b) => engine.promote(b, id, { actor: callerName(), force: args.force })); say(args, `${id} ready`, { ok: true }); return 0;
-    case 'reclaim': need(1, 'a card id'); withBoard((b) => engine.reclaim(b, id, rest.slice(1).join(' ') || null)); say(args, `${id} reclaimed`, { ok: true }); return 0;
-    case 'archive': need(1, 'a card id'); withBoard((b) => engine.archive(b, id)); say(args, `${id} archived`, { ok: true }); return 0;
-    case 'assign': need(2, 'a card id and a profile (or none)'); withBoard((b) => engine.assign(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `${id} → ${rest[1]}`, { ok: true }); return 0;
-    case 'move': need(2, 'a card id and a machine (or none)'); withBoard((b) => engine.setMachine(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `${id} runs on ${rest[1]}`, { ok: true }); return 0;
-    case 'link': need(2, 'a parent and a child'); withBoard((b) => engine.link(b, rest[0], rest[1])); say(args, `${rest[1]} waits on ${rest[0]}`, { ok: true }); return 0;
-    case 'unlink': need(2, 'a parent and a child'); withBoard((b) => engine.unlink(b, rest[0], rest[1])); say(args, `${rest[1]} no longer waits on ${rest[0]}`, { ok: true }); return 0;
-    case 'subscribe': {
+      let text = rest.slice(1).join(' ');
+      if (args['max-len']) text = text.slice(0, Number(args['max-len']));
+      const n = withBoard((b) => engine.comment(b, id, args.author ?? callerAddress() ?? callerName(), text));
+      say(args, `Comment added to ${id}`, { ok: true, comment: n }); return 0;
+    }
+    case 'attach': {
+      need(2, 'a card id and a file');
+      const source = resolve(rest[1]);
+      if (!existsSync(source) || !statSync(source).isFile()) throw new Error(`no file ${rest[1]}`);
+      const name = basename(args.name ?? source).replace(/[^A-Za-z0-9._ -]/g, '_') || 'attachment';
+      const dir = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments'), id);
+      mkdirSync(dir, { recursive: true });
+      let target = join(dir, name);
+      for (let n = 1; existsSync(target); n += 1) target = join(dir, `${n}-${name}`);
+      copyFileSync(source, target);
+      const n = withBoard((b) => engine.addAttachment(b, id, { file: { path: target, size: statSync(target).size }, name, contentType: args['content-type'] ?? null, author: args.author ?? callerName() }));
+      say(args, `Attached ${name} to ${id} (#${n})`, { ok: true, id: n, path: target }); return 0;
+    }
+    case 'attachments': {
       need(1, 'a card id');
-      const address = args.address ?? callerAddress();
-      if (!address) throw new Error('whose notices? --address sc:<machine>:<harness>:<id>');
-      withBoard((b) => engine.subscribe(b, id, address, args.role ?? 'creator'));
-      say(args, `${address} hears ${id}`, { ok: true, address }); return 0;
+      const got = withBoard((b) => engine.attachments(b.db, id));
+      if (args.json) { say(args, '', got); return 0; }
+      process.stdout.write(got.length ? `${got.map((a) => `#${a.id}  ${a.filename}  ${a.size} bytes  ${ts(a.created_at)}  ${a.stored_path}`).join('\n')}\n` : `(no attachments on ${id})\n`);
+      return 0;
     }
-    case 'unsubscribe': {
+    case 'attach-rm': {
+      need(1, 'an attachment id');
+      const row = withBoard((b) => engine.removeAttachment(b, Number(id)));
+      try { unlinkSync(row.stored_path); } catch { /* already gone */ }
+      say(args, `Removed attachment #${id} (${row.filename})`, { ok: true }); return 0;
+    }
+
+    case 'complete': {
       need(1, 'a card id');
-      const address = args.address ?? callerAddress();
-      const gone = withBoard((b) => engine.unsubscribe(b, id, address));
-      say(args, gone ? `${address} no longer hears ${id}` : `${address} did not hear ${id}`, { ok: gone }); return 0;
+      const metadata = metadataOf(args.metadata);
+      for (const t of rest) withBoard((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null }));
+      say(args, rest.map((t) => `Completed ${t}`).join('\n'), { ok: true, completed: rest }); return 0;
     }
+    case 'edit': {
+      need(1, 'a card id');
+      if (args.result === undefined) throw new Error('edit needs --result');
+      withBoard((b) => engine.editResult(b, id, { result: args.result, summary: args.summary ?? null, metadata: metadataOf(args.metadata) }));
+      say(args, `Edited ${id}`, { ok: true }); return 0;
+    }
+    case 'block': {
+      need(1, 'a card id');
+      const reason = rest.slice(1).join(' ') || null;
+      const results = [id, ...(args.ids ?? [])].map((t) => [t, withBoard((b) => engine.block(b, t, { reason, kind: args.kind ?? null }))]);
+      say(args, results.map(([t, s]) => `${s === 'todo' ? 'Waiting on dependencies' : s === 'triage' ? 'Routed to triage' : 'Blocked'} ${t}`).join('\n'), { ok: true, results }); return 0;
+    }
+    case 'schedule': {
+      need(1, 'a card id');
+      const reason = rest.slice(1).join(' ') || null;
+      for (const t of [id, ...(args.ids ?? [])]) withBoard((b) => engine.schedule(b, t, reason));
+      say(args, [id, ...(args.ids ?? [])].map((t) => `Scheduled ${t}`).join('\n'), { ok: true }); return 0;
+    }
+    case 'unblock': {
+      need(1, 'a card id');
+      const results = ids().map((t) => [t, withBoard((b) => engine.unblock(b, t))]);
+      say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
+    }
+    case 'request-review': need(1, 'a card id'); withBoard((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null })); say(args, `${id} → review`, { ok: true }); return 0;
+    case 'request-changes': need(2, 'a card id and the reason'); withBoard((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? callerName() })); say(args, `${id} sent back for changes`, { ok: true }); return 0;
+    case 'reopen-review': {
+      need(1, 'a card id');
+      const results = ids().map((t) => [t, withBoard((b) => engine.reopenReview(b, t))]);
+      say(args, results.map(([t, s]) => `Reopened ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
+    }
+    case 'promote': {
+      need(1, 'a card id');
+      const reason = rest.slice(1).join(' ') || null;
+      const targets = [id, ...(args.ids ?? [])];
+      if (args['dry-run']) {
+        const verdicts = withBoard((b) => targets.map((t) => {
+          const card = engine.showCard(b.db, t);
+          const open = card.parents.filter((p) => !['done', 'archived'].includes(p.status)).map((p) => p.id);
+          const ok = ['todo', 'blocked'].includes(card.task.status) && (!open.length || args.force);
+          return { id: t, ok, reason: ok ? null : !['todo', 'blocked'].includes(card.task.status) ? `${t} is ${card.task.status}` : `parents not done: ${open.join(', ')}` };
+        }));
+        say(args, verdicts.map((v) => `${v.ok ? 'would promote' : 'would refuse'} ${v.id}${v.reason ? `: ${v.reason}` : ''}`).join('\n'), verdicts);
+        return 0;
+      }
+      for (const t of targets) withBoard((b) => engine.promote(b, t, { actor: callerName(), reason, force: args.force }));
+      say(args, targets.map((t) => `Promoted ${t} → ready`).join('\n'), { ok: true }); return 0;
+    }
+    case 'archive': {
+      for (const t of rest) withBoard((b) => engine.archive(b, t));
+      const purged = [];
+      for (const t of args.rm ?? []) {
+        withBoard((b) => tx(b, (db) => {
+          const task = engine.getTask(db, t);
+          if (!task) throw new Error(`no card ${t}`);
+          if (task.status !== 'archived') throw new Error(`${t} is ${task.status}; only an archived card is deleted`);
+          for (const table of ['task_links']) db.prepare(`DELETE FROM ${table} WHERE parent_id = ? OR child_id = ?`).run(t, t);
+          for (const table of ['task_comments', 'task_events', 'task_runs', 'task_attachments', 'kanban_notify_subs', 'supercode_cards']) db.prepare(`DELETE FROM ${table} WHERE task_id = ?`).run(t);
+          db.prepare('DELETE FROM tasks WHERE id = ?').run(t);
+        }));
+        purged.push(t);
+      }
+      say(args, [...rest.map((t) => `Archived ${t}`), ...purged.map((t) => `Deleted ${t}`)].join('\n'), { ok: true, archived: rest, deleted: purged }); return 0;
+    }
+
+    case 'specify': case 'decompose': {
+      const { lanes, settings } = await laneState(root);
+      const targets = args.all ? withBoard((b) => engine.listCards(b.db, { status: 'triage' }).filter((t) => !args.tenant || t.tenant === args.tenant).map((t) => t.id)) : [id];
+      if (!targets[0]) throw new Error(`${verb} needs a card id, or --all`);
+      const results = [];
+      for (const t of targets) {
+        if (verb === 'specify' && (args.title !== undefined || args.body !== undefined)) {
+          withBoard((b) => engine.specify(b, t, { title: args.title ?? null, body: args.body ?? null, author: args.author ?? callerName() }));
+          results.push({ id: t, specified: true });
+        } else if (verb === 'decompose' && args.child?.length) {
+          const children = args.child.map((c) => { const [title, assignee] = c.split(/@(?=[^@]*$)/); return { title: title.trim(), assignee: assignee?.trim() || undefined }; });
+          results.push({ id: t, children: withBoard((b) => engine.decompose(b, t, children, { author: args.author ?? callerName() })) });
+        } else {
+          const session = withBoard((b) => startTriageSession(b, t, lanes, settings, verb));
+          results.push({ id: t, session: session.address, mode: session.mode });
+        }
+      }
+      say(args, results.map((r) => (r.specified ? `Specified ${r.id} → todo` : r.children ? `Decomposed ${r.id} into ${r.children.join(', ')}` : `${r.id}: session ${r.session} (${r.mode}) is writing its ${verb === 'specify' ? 'spec' : 'breakdown'}`)).join('\n'), results);
+      return 0;
+    }
+
+    case 'diagnostics': case 'diag': {
+      const { settings } = await laneState(root).catch(() => ({ settings: boardSettings({}) }));
+      const fleet = observeFleet();
+      const order = ['warning', 'error', 'critical'];
+      const found = withBoard((b) => {
+        const cards = args.task ? [engine.getTask(b.db, args.task)].filter(Boolean) : engine.listCards(b.db, {});
+        return cards.flatMap((t) => engine.diagnose(b.db, t, { failureLimit: settings.failureLimit, fleet }).map((d) => ({ task: t.id, title_of_task: t.title, ...d })))
+          .filter((d) => !args.severity || order.indexOf(d.severity) >= order.indexOf(args.severity));
+      });
+      if (args.json) { say(args, '', found); return 0; }
+      process.stdout.write(found.length ? `${found.map((d) => `${d.severity.padEnd(8)} ${d.task}  ${d.kind}: ${d.title}${d.actions[0] ? `\n         → ${d.actions[0]}` : ''}`).join('\n')}\n` : '(no active diagnostics)\n');
+      return 0;
+    }
+    case 'stats': {
+      const s = withBoard((b) => engine.stats(b.db));
+      if (args.json) { say(args, '', s); return 0; }
+      const fmt = (o) => Object.entries(o).sort().map(([k, v]) => `${k}=${v}`).join(', ') || '(none)';
+      process.stdout.write(`By status:   ${fmt(s.by_status)}\nBy assignee:\n${Object.entries(s.by_assignee).map(([a, c]) => `  ${a.padEnd(20)} ${fmt(c)}`).join('\n') || '  (none)'}\nBy machine:\n${Object.entries(s.by_machine).map(([m, c]) => `  ${m.padEnd(20)} ${fmt(c)}`).join('\n') || '  (none)'}\nOldest ready: ${s.oldest_ready_age_seconds === null ? '-' : `${Math.floor(s.oldest_ready_age_seconds / 60)}m`}\n`);
+      return 0;
+    }
+    case 'assignees': {
+      const { profiles, lanes } = await laneState(root);
+      const c = withBoard((b) => engine.stats(b.db).by_assignee);
+      const data = [...new Set([...profiles, ...Object.keys(c)])].sort().map((name) => ({ name, on_disk: profiles.includes(name), surface: lanes[name]?.surface ?? null, counts: c[name] ?? {} }));
+      if (args.json) { say(args, '', data); return 0; }
+      process.stdout.write(`${'NAME'.padEnd(20)}  ${'ON DISK'.padEnd(8)}  ${'LANE'.padEnd(9)} COUNTS\n${data.map((e) => `${e.name.padEnd(20)}  ${(e.on_disk ? 'yes' : 'no').padEnd(8)}  ${(e.surface ?? '-').padEnd(9)} ${Object.entries(e.counts).sort().map(([k, v]) => `${k}=${v}`).join(', ') || '(idle)'}`).join('\n')}\n`);
+      return 0;
+    }
+    case 'log': {
+      need(1, 'a card id');
+      const file = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs'), `${id}.log`);
+      if (!existsSync(file)) {
+        // a pane session keeps no log file: its transcript is the harness's own, named by the run
+        const s = withBoard((b) => tx(b, (db) => engine.lastSession(db, id)));
+        process.stdout.write(s ? `(${id} runs as session ${s.address}; its transcript is that session's: \`supercode sessions show ${s.session_id}\`)\n` : `(no log for ${id})\n`);
+        return 0;
+      }
+      const text = readFileSync(file, 'utf8');
+      const tail = args.tail ? Number(args.tail) : null;
+      process.stdout.write(tail ? text.slice(-tail) : text);
+      return 0;
+    }
+    case 'tail': case 'watch': {
+      const interval = Math.max(Number(args.interval) || (verb === 'tail' ? 1 : 0.5), 0.2) * 1000;
+      const kinds = args.kinds ? new Set(String(args.kinds).split(',').map((k) => k.trim())) : null;
+      if (verb === 'tail') need(1, 'a card id');
+      let cursor = withBoard((b) => Number(b.db.prepare('SELECT COALESCE(MAX(id), 0) AS c FROM task_events').get().c));
+      if (verb === 'tail') cursor = 0;
+      let stop = false;
+      process.on('SIGINT', () => { stop = true; });
+      process.on('SIGTERM', () => { stop = true; });
+      while (!stop) {
+        const rows = withBoard((b) => b.db.prepare(`SELECT e.id, e.task_id, e.kind, e.payload, e.created_at, t.assignee, t.tenant FROM task_events e LEFT JOIN tasks t ON t.id = e.task_id WHERE e.id > ?${verb === 'tail' ? ' AND e.task_id = ?' : ''} ORDER BY e.id`).all(...(verb === 'tail' ? [cursor, id] : [cursor])));
+        for (const e of rows) {
+          cursor = e.id;
+          if (kinds && !kinds.has(e.kind)) continue;
+          if (args.assignee && e.assignee !== args.assignee) continue;
+          if (args.tenant && e.tenant !== args.tenant) continue;
+          process.stdout.write(`[${ts(e.created_at)}] ${verb === 'watch' ? `${e.task_id} ` : ''}${e.kind}${e.payload ? ` ${e.payload}` : ''}\n`);
+        }
+        await new Promise((done) => setTimeout(done, interval));
+      }
+      return 0;
+    }
+
+    case 'notify-subscribe': case 'notify-unsubscribe': {
+      need(1, 'a card id');
+      const platform = args.platform ?? 'supercode';
+      const chat = args['chat-id'] ?? args.address ?? (platform === 'supercode' ? callerAddress() : null);
+      if (!chat) throw new Error(`${verb} names the subscriber: --platform P --chat-id C (a supercode session's address with --platform supercode)`);
+      if (verb === 'notify-unsubscribe') {
+        const gone = withBoard((b) => tx(b, (db) => db.prepare('DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = ? AND chat_id = ? AND thread_id = ?').run(id, platform, chat, args['thread-id'] ?? '').changes > 0));
+        say(args, gone ? `Unsubscribed ${platform}:${chat} from ${id}` : `${platform}:${chat} was not subscribed to ${id}`, { ok: gone }); return gone ? 0 : 1;
+      }
+      withBoard((b) => tx(b, (db) => {
+        if (!engine.getTask(db, id)) throw new Error(`no card ${id}`);
+        if (platform === 'supercode') return engine.subscribeIn(db, id, chat, args.role ?? 'creator');
+        const cursor = db.prepare('SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?').get(id).c;
+        db.prepare(`INSERT INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, user_id, user_id_alt, chat_type, notifier_profile, delivery_mode, created_at, last_event_id)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(task_id, platform, chat_id, thread_id) DO UPDATE SET chat_type = COALESCE(excluded.chat_type, chat_type), delivery_mode = excluded.delivery_mode`)
+          .run(id, platform, chat, args['thread-id'] ?? '', args['user-id'] ?? null, args['user-id-alt'] ?? null, args['chat-type'] ?? 'dm', args['notifier-profile'] ?? null, args['delivery-mode'] ?? 'notify', now(), cursor);
+        return null;
+      }));
+      say(args, `Subscribed ${platform}:${chat} to ${id}`, { ok: true }); return 0;
+    }
+    case 'notify-list': {
+      const subs = withBoard((b) => engine.subscriptions(b.db, id ?? null));
+      if (args.json) { say(args, '', subs); return 0; }
+      process.stdout.write(subs.length ? `${subs.map((s) => `${s.task_id}  ${s.platform}:${s.chat_id}${s.thread_id ? `#${s.thread_id}` : ''}  ${s.platform === 'supercode' ? s.delivery_metadata?.role ?? 'creator' : s.delivery_mode}  cursor=${s.last_event_id}`).join('\n')}\n` : '(no subscriptions)\n');
+      return 0;
+    }
+
     case 'dispatch': {
       const { lanes, settings } = await laneState(root);
-      const reports = tick({ root, lanes, settings });
+      if (args['failure-limit']) settings.failureLimit = Number(args['failure-limit']);
+      if (args.max) settings.maxInProgress = Number(args.max);
+      if (args['dry-run']) {
+        const would = withBoard((b) => engine.listCards(b.db, { status: 'ready' }).filter((t) => t.assignee && lanes[t.assignee] && !t.subtask_of).map((t) => ({ id: t.id, assignee: t.assignee, machine: t.machine, surface: lanes[t.assignee].surface })));
+        say(args, would.length ? would.map((w) => `would start ${w.id} as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`).join('\n') : 'nothing would start', would);
+        return 0;
+      }
+      const reports = await tick({ root, lanes, settings });
       if (args.json) say(args, '', reports);
       else for (const r of reports) process.stdout.write(`${summary(r)}\n`);
       return reports.some((r) => r.error) ? 1 : 0;
     }
-    case 'serve': return serve(root);
+    case 'daemon': case 'serve': return serve(root);
+
+    case 'gc': {
+      const eventDays = Number(args['event-retention-days'] ?? 30);
+      const logDays = Number(args['log-retention-days'] ?? 30);
+      let removedWs = 0;
+      const scratchRoot = slug === DEFAULT_BOARD ? join(root, 'kanban', 'workspaces') : join(boardDir(root, slug), 'workspaces');
+      const archived = withBoard((b) => b.db.prepare("SELECT id, workspace_kind, workspace_path FROM tasks WHERE status = 'archived'").all());
+      for (const t of archived) {
+        if (t.workspace_kind === 'worktree' && t.workspace_path && existsSync(t.workspace_path)) {
+          // an archived card's worktree goes, as Hermes's gc removes it (the branch stays)
+          const r = spawnSync('git', ['-C', t.workspace_path, 'worktree', 'remove', '--force', t.workspace_path], { encoding: 'utf8' });
+          if (r.status === 0) removedWs += 1;
+          continue;
+        }
+        if (t.workspace_kind !== 'scratch') continue;
+        const dir = resolve(t.workspace_path || join(scratchRoot, t.id));
+        if (!dir.startsWith(`${resolve(scratchRoot)}/`) || !existsSync(dir)) continue;
+        rmSync(dir, { recursive: true, force: true });
+        removedWs += 1;
+      }
+      const events = withBoard((b) => engine.gcEvents(b, eventDays * 86400));
+      let logs = 0;
+      const logDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs');
+      if (existsSync(logDir)) for (const f of readdirSync(logDir)) { const p = join(logDir, f); if (statSync(p).isFile() && statSync(p).mtimeMs < Date.now() - logDays * 86400_000) { unlinkSync(p); logs += 1; } }
+      say(args, `GC complete: ${removedWs} workspace(s), ${events} event row(s), ${logs} log file(s) removed`, { workspaces: removedWs, events, logs });
+      return 0;
+    }
+    case 'repair': {
+      const path = boardPath(root, slug);
+      if (!existsSync(path)) { say(args, `No kanban DB at ${path} — nothing to repair.`, { status: 'missing', db_path: path }); return 0; }
+      const report = withBoard((b) => {
+        const check = () => b.db.prepare('PRAGMA integrity_check').all().map((r) => Object.values(r)[0]);
+        const first = check();
+        if (first.length === 1 && first[0] === 'ok') return { status: 'ok', messages: first };
+        // a copy of the damaged file first, as Hermes keeps one, then the index rebuild
+        const backup = `${path}.corrupt-${now()}`;
+        b.db.prepare('VACUUM INTO ?').run(backup);
+        b.db.exec('REINDEX');
+        const after = check();
+        return { status: after.length === 1 && after[0] === 'ok' ? 'repaired' : 'corrupt', messages: first, post_repair_messages: after, reindexed: true, backup_path: backup };
+      });
+      say(args, `${report.status}: ${path}${report.status !== 'ok' ? `\n${report.messages.join('\n')}` : ''}`, { ...report, db_path: path });
+      return report.status === 'corrupt' ? 1 : 0;
+    }
+
+    case 'pause': {
+      // Hermes's emergency stop: new starts stop on every board of the home; running sessions go on
+      writeFileSync(join(root, 'ESTOP'), `${JSON.stringify({ engaged_at: new Date().toISOString(), reason: rest.join(' ') || null })}\n`);
+      say(args, `New starts paused (${join(root, 'ESTOP')}); \`supercode workflow resume\` lifts it`, { ok: true, paused: join(root, 'ESTOP') });
+      return 0;
+    }
+    case 'resume': {
+      const lifted = [join(root, 'ESTOP'), join(process.env.HOME ?? '', '.hermes', 'ESTOP')].filter((p) => existsSync(p));
+      for (const p of lifted) unlinkSync(p);
+      say(args, lifted.length ? `Resumed (removed ${lifted.join(', ')})` : 'Not paused', { ok: true, lifted });
+      return 0;
+    }
+    case 'adopt': {
+      need(2, 'a card id and a session');
+      const { settings } = await laneState(root);
+      const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl }));
+      say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });
+      return 0;
+    }
+    case 'close': {
+      need(1, 'a card id');
+      const closed = withBoard((b) => closeSession(b, id));
+      say(args, closed ? `closed ${closed.session_id} (pane ${closed.pane} on ${closed.machine})` : `${id} has no live session`, { ok: true, closed });
+      return 0;
+    }
+
     default: throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
   }
 }
 
+// ------------------------------------------------------------------ boards
+
+async function boardsVerb(root, rest, args) {
+  const [action = 'list', target] = rest;
+  switch (action) {
+    case 'list': case 'ls': {
+      const current = boardOf(root, {});
+      const boards = boardsOf(root, { includeArchived: args.all }).map((b) => ({ ...b, is_current: b.slug === current, counts: counts(root, b.slug) }));
+      if (args.json) { say(args, '', boards); return 0; }
+      process.stdout.write(`${''.padEnd(2)}  ${'SLUG'.padEnd(24)}  ${'NAME'.padEnd(28)}  COUNTS\n${boards.map((b) => `${(b.is_current ? '●' : ' ').padEnd(2)}  ${b.slug.padEnd(24)}  ${`${b.name}${b.archived ? ' [archived]' : ''}`.padEnd(28)}  ${Object.entries(b.counts).sort().map(([k, v]) => `${k}=${v}`).join(', ') || '(empty)'}`).join('\n')}\n\nCurrent board: ${current}\n`);
+      return 0;
+    }
+    case 'create': case 'new': {
+      const slug = normalSlug(target);
+      const meta = writeMeta(root, slug, { name: args.name, description: args.description, icon: args.icon, color: args.color, default_workdir: args['default-workdir'] });
+      openBoard(root, slug, { create: true }).close();
+      if (args.switch) { mkdirSync(join(root, 'kanban'), { recursive: true }); writeFileSync(currentFile(root), `${slug}\n`); }
+      say(args, `Board '${slug}' ready.\n  Display name: ${meta.name}\n  DB path:      ${meta.db_path}${args.switch ? `\n  Switched to '${slug}'.` : ''}`, meta);
+      return 0;
+    }
+    case 'rm': case 'remove': case 'delete': {
+      const slug = normalSlug(target);
+      if (slug === DEFAULT_BOARD) throw new Error("the 'default' board cannot be removed");
+      if (!existsSync(boardDir(root, slug))) throw new Error(`board '${slug}' does not exist`);
+      if (boardOf(root, {}) === slug) rmSync(currentFile(root), { force: true });
+      if (args.delete || action === 'delete') { rmSync(boardDir(root, slug), { recursive: true, force: true }); say(args, `Board '${slug}' deleted.`, { slug, action: 'deleted' }); return 0; }
+      const archive = join(root, 'kanban', 'boards', '_archived');
+      mkdirSync(archive, { recursive: true });
+      let dest = join(archive, `${slug}-${now()}`);
+      for (let n = 1; existsSync(dest); n += 1) dest = join(archive, `${slug}-${now()}-${n}`);
+      renameSync(boardDir(root, slug), dest);
+      say(args, `Board '${slug}' archived → ${dest}`, { slug, action: 'archived', new_path: dest });
+      return 0;
+    }
+    case 'switch': case 'use': {
+      const slug = normalSlug(target);
+      if (slug !== DEFAULT_BOARD && !existsSync(boardPath(root, slug))) throw new Error(`board '${slug}' does not exist; \`supercode workflow boards create ${slug}\``);
+      mkdirSync(join(root, 'kanban'), { recursive: true });
+      writeFileSync(currentFile(root), `${slug}\n`);
+      say(args, `Active board is now '${slug}'.`, { ok: true, board: slug });
+      return 0;
+    }
+    case 'show': case 'current': {
+      const slug = boardOf(root, args);
+      const meta = boardMeta(root, slug);
+      const c = counts(root, slug);
+      say(args, `Current board: ${slug}\n  Display name: ${meta.name}${meta.description ? `\n  Description:  ${meta.description}` : ''}\n  DB path:      ${meta.db_path}\n  Tasks:        ${Object.values(c).reduce((a, b) => a + b, 0)} total${Object.keys(c).length ? ` (${Object.entries(c).sort().map(([k, v]) => `${k}=${v}`).join(', ')})` : ''}`, { ...meta, counts: c });
+      return 0;
+    }
+    case 'rename': {
+      const slug = normalSlug(target);
+      const meta = writeMeta(root, slug, { name: rest.slice(2).join(' ') || args.name });
+      say(args, `Board '${slug}' renamed to '${meta.name}'.`, meta); return 0;
+    }
+    case 'set-default-workdir': {
+      const slug = normalSlug(target);
+      const meta = writeMeta(root, slug, { default_workdir: rest[2] || null });
+      say(args, meta.default_workdir ? `Board '${slug}' default workdir set to '${meta.default_workdir}'.` : `Board '${slug}' default workdir cleared.`, meta); return 0;
+    }
+    case 'export': {
+      const slug = normalSlug(target ?? boardOf(root, args));
+      if (!existsSync(boardPath(root, slug))) throw new Error(`board '${slug}' has no database`);
+      const out = resolve(args.output ?? `${slug}.tar.gz`);
+      const made = exportBoard(root, slug, out, { attachments: !args['no-attachments'], logs: Boolean(args['include-logs']) });
+      say(args, `Exported board '${slug}' → ${out}\n  Tasks:       ${made.counts.tasks}\n  Comments:    ${made.counts.task_comments}\n  Attachments: ${made.counts.attachment_files}`, made);
+      return 0;
+    }
+    case 'import': {
+      const made = importBoard(root, resolve(target ?? ''), args.as ?? null);
+      if (args.switch) writeFileSync(currentFile(root), `${made.board}\n`);
+      say(args, `Imported board '${made.board}' (${made.name}).${made.renamed ? `\n  Renamed from '${made.requested_board}' — that slug was taken.` : ''}\n  Path:  ${made.path}\n  Tasks: ${made.counts.tasks}${made.warnings.map((w) => `\n  Note:  ${w}`).join('')}`, made);
+      return 0;
+    }
+    default: throw new Error(`boards ${action}: list | create | rm | switch | show | rename | set-default-workdir | export | import`);
+  }
+}
+
+// ------------------------------------------------------------------ board archives, in Hermes's format
+
+const ARCHIVE_FORMAT = 'hermes-kanban-board';
+const TABLES = ['tasks', 'task_links', 'task_comments', 'task_events', 'task_runs', 'task_attachments'];
+
+/**
+ * Strip what only means something on the machine that wrote it, as Hermes's transfer does: subscriptions, claims,
+ * pids, heartbeats, sessions, failure counters; a running card goes back to ready, its run is released. supercode's
+ * record of a run's session is such state too.
+ */
+function scrub(db) {
+  db.exec('DELETE FROM kanban_notify_subs');
+  db.exec(`UPDATE tasks SET claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, current_run_id = NULL, last_heartbeat_at = NULL,
+           session_id = NULL, project_id = NULL, consecutive_failures = 0, last_failure_error = NULL`);
+  db.exec("UPDATE tasks SET status = 'ready' WHERE status = 'running'");
+  db.prepare("UPDATE task_runs SET status = 'released', outcome = COALESCE(outcome, 'reclaimed'), ended_at = COALESCE(ended_at, ?), last_heartbeat_at = NULL WHERE status = 'running'").run(now());
+  db.exec('UPDATE task_runs SET claim_lock = NULL, worker_pid = NULL');
+  for (const r of db.prepare("SELECT id, metadata FROM task_runs WHERE metadata LIKE '%\"supercode\"%'").all()) {
+    const m = json(r.metadata, {}) ?? {};
+    delete m.supercode;
+    db.prepare('UPDATE task_runs SET metadata = ? WHERE id = ?').run(Object.keys(m).length ? JSON.stringify(m) : null, r.id);
+  }
+}
+
+const rowCounts = (db) => Object.fromEntries(TABLES.map((t) => [t, Number(db.prepare(`SELECT COUNT(*) AS n FROM ${t}`).get().n)]));
+
+function copyTree(from, to) {
+  if (!existsSync(from)) return 0;
+  let n = 0;
+  for (const name of readdirSync(from)) {
+    const src = join(from, name);
+    if (statSync(src).isDirectory()) n += copyTree(src, join(to, name));
+    else { mkdirSync(to, { recursive: true }); copyFileSync(src, join(to, name)); n += 1; }
+  }
+  return n;
+}
+
+function exportBoard(root, slug, out, { attachments, logs }) {
+  const staging = join(tmpdir(), `board-export-${process.pid}-${now()}`);
+  const base = join(staging, slug);
+  mkdirSync(base, { recursive: true });
+  try {
+    const b = openBoard(root, slug);
+    try { b.db.prepare('VACUUM INTO ?').run(join(base, 'kanban.db')); } finally { b.close(); }
+    const snap = openBoard(base, DEFAULT_BOARD);
+    let counts;
+    try { tx(snap, (db) => scrub(db)); counts = rowCounts(snap.db); } finally { snap.close(); }
+    const { db_path: _, default_workdir: __, project_id: ___, ...meta } = boardMeta(root, slug);
+    writeFileSync(join(base, 'board.json'), `${JSON.stringify(meta, null, 2)}\n`);
+    const attachmentsDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments');
+    const logsDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs');
+    const files = attachments ? copyTree(attachmentsDir, join(base, 'attachments')) : 0;
+    const logFiles = logs ? copyTree(logsDir, join(base, 'logs')) : 0;
+    const manifest = { format: ARCHIVE_FORMAT, format_version: 1, board: slug, board_name: meta.name || slug, exported_at: now(), exported_by: 'supercode',
+      includes: { attachments, logs }, counts: { ...counts, attachment_files: files, log_files: logFiles } };
+    writeFileSync(join(base, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    const r = spawnSync('tar', ['-czf', out, '-C', staging, slug], { encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`tar: ${r.stderr.trim()}`);
+    return { board: slug, archive: out, size: statSync(out).size, counts: manifest.counts };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function importBoard(root, archive, as) {
+  if (!existsSync(archive)) throw new Error(`archive not found: ${archive}`);
+  const staging = join(tmpdir(), `board-import-${process.pid}-${now()}`);
+  mkdirSync(staging, { recursive: true });
+  try {
+    const r = spawnSync('tar', ['-xzf', archive, '-C', staging], { encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`tar: ${r.stderr.trim()}`);
+    const tops = readdirSync(staging).filter((n) => statSync(join(staging, n)).isDirectory());
+    if (tops.length !== 1) throw new Error('a board archive holds exactly one top-level directory');
+    const extracted = join(staging, tops[0]);
+    const manifest = json(existsSync(join(extracted, 'manifest.json')) ? readFileSync(join(extracted, 'manifest.json'), 'utf8') : null, null);
+    if (manifest?.format !== ARCHIVE_FORMAT) throw new Error('the archive is not a Kanban board export (no manifest.json of format hermes-kanban-board)');
+    if (!existsSync(join(extracted, 'kanban.db'))) throw new Error('the archive is missing kanban.db');
+    const requested = normalSlug(as ?? manifest.board ?? tops[0]);
+    let slug = requested === DEFAULT_BOARD ? `${requested}-imported` : requested;
+    for (let n = 2; existsSync(boardDir(root, slug)); n += 1) slug = `${requested}-${n}`;
+    const dest = boardDir(root, slug);
+    mkdirSync(dest, { recursive: true });
+    renameSync(join(extracted, 'kanban.db'), join(dest, 'kanban.db'));
+    for (const tree of ['attachments', 'logs']) if (existsSync(join(extracted, tree))) renameSync(join(extracted, tree), join(dest, tree));
+    const staged = json(existsSync(join(extracted, 'board.json')) ? readFileSync(join(extracted, 'board.json'), 'utf8') : null, {}) ?? {};
+    const name = staged.name || manifest.board_name || slug;
+    writeMeta(root, slug, { name, description: staged.description ?? '', icon: staged.icon ?? '', color: staged.color ?? '', archived: false });
+    const warnings = [];
+    const b = openBoard(root, slug);
+    let counts;
+    try {
+      tx(b, (db) => {
+        scrub(db);
+        let dropped = 0;
+        for (const row of db.prepare('SELECT id, task_id, stored_path FROM task_attachments').all()) {
+          const landed = join(dest, 'attachments', row.task_id, basename(row.stored_path));
+          if (existsSync(landed)) db.prepare('UPDATE task_attachments SET stored_path = ? WHERE id = ?').run(landed, row.id);
+          else { db.prepare('DELETE FROM task_attachments WHERE id = ?').run(row.id); dropped += 1; }
+        }
+        if (dropped) warnings.push(`${dropped} attachment record(s) dropped — the files were not in the archive`);
+        const parked = db.prepare("SELECT id FROM tasks WHERE workspace_kind IN ('dir', 'worktree') AND status IN ('ready', 'running', 'todo', 'scheduled')").all().map((t) => t.id);
+        db.exec('UPDATE tasks SET workspace_path = NULL, branch_name = NULL');
+        for (const t of parked) { db.prepare("UPDATE tasks SET status = 'triage' WHERE id = ?").run(t); event(db, t, 'status', { status: 'triage', reason: 'imported: its directory means nothing on this machine' }); }
+        if (parked.length) warnings.push(`${parked.length} card(s) with a directory workspace parked in triage: the path means nothing here`);
+      });
+      counts = rowCounts(b.db);
+    } finally { b.close(); }
+    return { board: slug, requested_board: requested, renamed: slug !== requested, name, path: dest, db_path: boardPath(root, slug), counts, warnings };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+// ------------------------------------------------------------------ a card's own session
+
 /** The card whose latest session is `sessionId` (the caller works it), or null. */
 function ownCard(db, sessionId) {
-  const hit = db.prepare("SELECT task_id FROM task_runs WHERE metadata LIKE ? ORDER BY id DESC LIMIT 1").get(`%"session_id":"${sessionId}"%`);
+  const hit = db.prepare('SELECT task_id FROM task_runs WHERE metadata LIKE ? ORDER BY id DESC LIMIT 1').get(`%"session_id":"${sessionId}"%`);
   if (!hit) return null;
   return engine.lastSession(db, hit.task_id)?.session_id === sessionId ? engine.getTask(db, hit.task_id) : null;
 }
 
-const READS = new Set(['list', 'show', 'context', 'help', 'init', 'dispatch']);
+const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'help', 'init']);
 
 /**
- * What a card's own session may write (the owner's rule): on its card, comment, block with a typed reason, and send
- * it to review; on its subtasks, create, complete, block, unblock and comment. Never its arc's completion, and never
- * another arc's card: anything across arcs goes through the fleet's manager.
+ * What a card's own session may write (the owner's rule): on its card, comment, block with a typed reason, heartbeat,
+ * request review, attach a file, specify or decompose it in triage; on its subtasks, file, complete, block, unblock,
+ * comment and attach. Never its arc's completion, and never another arc's card: anything across arcs goes through the
+ * fleet's manager.
  */
 function authorize(db, verb, rest, args, own) {
-  if (READS.has(verb)) return;
   const refuse = (why) => { throw new Error(`the session working ${own.id} ${why}`); };
   if (verb === 'create') {
     if (args['subtask-of'] !== own.id) refuse(`files subtasks of its own card only (--subtask-of ${own.id})`);
     return;
   }
+  if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
+  // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
+  if (['pause', 'resume', 'swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'reassign', 'assign', 'set-model', 'claim', 'reclaim', 'archive', 'promote', 'schedule', 'link', 'unlink', 'edit', 'reopen-review', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if (args.all) refuse(`does not ${verb} every card; only its own`);
   const card = engine.getTask(db, rest[0]);
   if (!card) return; // the verb itself answers "no card"
   const mine = card.id === own.id;
   const sub = card.subtask_of === own.id;
+  // a session started from the review lane is the card's reviewer: its verdict is its to give
+  const reviewing = mine && json(db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND kind = 'claimed' ORDER BY id DESC LIMIT 1").get(card.id)?.payload, {})?.source_status === 'review';
+  if (reviewing && ['complete', 'request-changes'].includes(verb)) return;
   const allowed = {
-    comment: mine || sub, block: mine || sub, review: mine || sub, complete: sub, unblock: sub,
-    subscribe: mine || sub, unsubscribe: mine || sub,
+    comment: mine || sub, block: mine || sub, heartbeat: mine, 'request-review': mine || sub, attach: mine || sub,
+    specify: mine, decompose: mine, complete: sub, unblock: sub, 'notify-subscribe': mine || sub, 'notify-unsubscribe': mine || sub,
   }[verb];
   if (!allowed) refuse(mine ? `cannot ${verb} its own card; its reviewers and the fleet's manager do` : `writes only its own card and its subtasks, not ${card.id}`);
   if (verb === 'block' && mine && !args.kind) refuse('blocks its card with a typed reason (--kind needs_input|capability|transient|dependency)');
+  for (const other of args.ids ?? []) if (other !== own.id && engine.getTask(db, other)?.subtask_of !== own.id) refuse(`writes only its own card and its subtasks, not ${other}`);
 }
 
 /** Close the live session of a card that is not running, freeing its machine's place. */
@@ -262,10 +953,6 @@ function closeSession(board, id) {
   return session;
 }
 
-function callerName() {
-  return process.env.HERMES_PROFILE || process.env.USER || 'user';
-}
-
 export function summary(r) {
   const parts = [`board ${r.board}:`];
   if (r.error) parts.push(`error ${r.error}`);
@@ -288,17 +975,25 @@ async function serve(root) {
   const stop = () => { stopped = true; };
   process.on('SIGTERM', stop);
   process.on('SIGINT', stop);
-  const log = (line) => process.stdout.write(`${new Date().toISOString()} ${line}\n`);
-  log(`dispatching the boards of ${root}`);
+  const log = (text) => process.stdout.write(`${new Date().toISOString()} ${text}\n`);
+  log(`dispatching the boards of ${root} from ${localMachine()}`);
+  const stuck = {};
+  const warned = {};
+  let pausedSaid = false;
   try {
     while (!stopped) {
+      pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
       try {
         const { lanes, settings } = await laneState(root);
         interval = settings.interval;
-        for (const r of tick({ root, lanes, settings })) {
+        for (const r of await tick({ root, lanes, settings })) {
           const said = summary(r);
           if (!said.endsWith('nothing to do')) log(said);
+          if (r.paused && !pausedSaid) { log(`new starts paused by ${r.paused} (\`supercode workflow resume\` lifts it)`); pausedSaid = true; }
+          // Hermes's stuck warning: ready work for six ticks running and nothing started
+          stuck[r.board] = r.ready_waiting && !r.started.length && !r.paused ? (stuck[r.board] ?? 0) + 1 : 0;
+          if (stuck[r.board] >= 6 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log(`board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${stuck[r.board]} ticks; \`supercode workflow diagnostics\``); warned[r.board] = Date.now(); }
           for (const [t, why] of r.failed) log(`  ${t} did not start: ${why}`);
           for (const [t, s, m] of r.started) log(`  ${t} started ${s} (${m})`);
           for (const [t, to, why] of r.undelivered) log(`  notice for ${t} to ${to} not delivered: ${why}`);