@staix/agent-hub 0.9.0 → 0.11.0

package/src/hub/ask.ts

@@ -85,14 +85,19 @@ export async function gather(question: string, d: AskDeps): Promise<{ evidence:
 
   // Matching tasks first, then the most recently touched; PII rows keep their place with a stub, so counts stay right.
   const tasks = d.board.list().sort((a, b) => hit(b.title) - hit(a.title) || b.updated - a.updated).slice(0, MAX_TASKS);
-  const anyPii = tasks.some((t) => d.isPii(t));
+  // An ordinary task's last note is model-written (a summary, a review note): one that matches a PII pattern is shown
+  // only on campus, like a PII task (#69).
+  const notePii = (t: (typeof tasks)[number]) => !d.isPii(t) && !!t.history.at(-1)?.note && (d.isPiiText?.(t.history.at(-1)!.note!) ?? false);
+  const anyPii = tasks.some((t) => d.isPii(t) || notePii(t));
   const showPii = anyPii ? await onCampus() : false;
   let piiShown = false;
   const taskRows: Evidence[] = tasks.map((t) => {
     const secret = d.isPii(t);
     if (secret && showPii) piiShown = true;
     const last = t.history.at(-1);
-    const text = secret && !showPii ? "[pii] (its text is shown only when the model is reached on campus)" : `${t.title}${last ? ` | last: ${last.event} by ${last.by}${last.note ? ` (${last.note})` : ""}` : ""}`;
+    if (notePii(t) && showPii) piiShown = true;
+    const note = last?.note && notePii(t) && !showPii ? "its note is shown only when the model is reached on campus" : last?.note;
+    const text = secret && !showPii ? "[pii] (its text is shown only when the model is reached on campus)" : `${t.title}${last ? ` | last: ${last.event} by ${last.by}${note ? ` (${note})` : ""}` : ""}`;
     return { id: `task #${t.id}`, kind: "task", text: `[${t.class}] ${t.state}, owner ${t.owner ?? "none"}, reviewer ${t.reviewer ?? "none"}: ${text}`.slice(0, ITEM_CHARS) };
   });
 

package/src/hub/board.ts

@@ -22,6 +22,8 @@ export interface HistoryEntry {
   by: PeerId;
   event: string; // proposed | assigned | accepted | declined | done | approved | changes_requested | escalated | reassigned
   note?: string;
+  /** The owner an event that set it left the task with (#67); absent in rows written before 0.11. */
+  owner?: PeerId | null;
 }
 export interface Task {
   id: number;
@@ -74,6 +76,11 @@ export class Board {
     // Who did well or badly at which class, for demotion (issue #36). Only peers, classes and times: no task text.
     this.db.run("CREATE TABLE IF NOT EXISTS outcomes (peer TEXT NOT NULL, class TEXT NOT NULL, ok INTEGER NOT NULL, at INTEGER NOT NULL)");
     this.db.run("CREATE INDEX IF NOT EXISTS outcomes_class_at ON outcomes (class, at)");
+    // How reviews turned out, per (implementer, reviewer, class) (issue #35): approved, contradicted later, caught, escalated.
+    this.db.run("CREATE TABLE IF NOT EXISTS reviews (implementer TEXT NOT NULL, reviewer TEXT NOT NULL, class TEXT NOT NULL, kind TEXT NOT NULL, task INTEGER NOT NULL, at INTEGER NOT NULL)");
+    // ponytail: kept for good (a record is the whole history); prune by age if it ever grows large.
+    this.db.run("CREATE INDEX IF NOT EXISTS reviews_class ON reviews (class)");
+    this.db.run("CREATE INDEX IF NOT EXISTS reviews_task ON reviews (task)");
     // Boards from before issues #31 and #34 lack these columns; existing rows get the defaults.
     const have = new Set((this.db.query("PRAGMA table_info(tasks)").all() as { name: string }[]).map((c) => c.name));
     for (const [col, empty] of [["plan", "{}"], ["deps", "[]"]] as const) {
@@ -117,7 +124,7 @@ export class Board {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}) }];
     this.db
       .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, plan = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
       .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(history), Date.now(), id);
@@ -135,11 +142,32 @@ export class Board {
     return this.db.query("SELECT peer, ok, at FROM outcomes WHERE class = ? AND at >= ?").all(cls, since) as { peer: PeerId; ok: number; at: number }[];
   }
 
+  recordReview(r: Omit<ReviewOutcome, "at">, at = Date.now()): void {
+    this.db.query("INSERT INTO reviews (implementer, reviewer, class, kind, task, at) VALUES (?, ?, ?, ?, ?, ?)").run(r.implementer, r.reviewer, r.class, r.kind, r.task, at);
+  }
+
+  /** One task's review outcomes, or a class's (for reviewer choice). */
+  reviews(where: { task: number } | { class: TaskClass }): ReviewOutcome[] {
+    return ("task" in where
+      ? this.db.query("SELECT * FROM reviews WHERE task = ? ORDER BY at").all(where.task)
+      : this.db.query("SELECT * FROM reviews WHERE class = ? ORDER BY at").all(where.class)) as ReviewOutcome[];
+  }
+
   close(): void {
     this.db.close();
   }
 }
 
+export interface ReviewOutcome {
+  implementer: PeerId;
+  reviewer: PeerId;
+  class: TaskClass;
+  /** approved; contradicted (a later check failure or changes requested on the same places); caught (changes requested, then the redo passed); escalated */
+  kind: "approved" | "contradicted" | "caught" | "escalated";
+  task: number;
+  at: number;
+}
+
 function parse(row: Record<string, unknown>): Task {
   const out = { ...row } as Record<string, unknown>;
   for (const col of JSON_COLS) out[col] = JSON.parse(String(row[col]));

package/src/hub/config-trust.ts

@@ -24,6 +24,8 @@ export const MACHINE_LOCAL = [
   "memory.worker_url",
   "local.read_allow",
   "local.bash_network",
+  "local.network_allow", // the hosts the egress proxy opens (#65)
+  "local.sandbox", // "allow-default" widens what the worker's commands may do
 ] as const;
 
 /**

package/src/hub/crash.ts

@@ -0,0 +1,109 @@
+import { chmodSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { JournalDelivery } from "./delivery-journal.ts";
+
+/**
+ * Unplanned-crash recovery (issue #37). While the hub runs it keeps `sessions.json`: each attached peer's session
+ * identity (the adapters' recovery metadata: ids and launch options, never message text). A clean stop removes the
+ * file, so finding it at start means the previous run died.
+ */
+export interface SessionRecord {
+  peer: string;
+  /** The adapter's recovery metadata: `launch`, and `sessionId` / `threadId` / `sessionFile` where it has one. */
+  meta: Record<string, unknown>;
+}
+export interface SessionsFile {
+  instanceId: string;
+  at: number;
+  peers: SessionRecord[];
+}
+
+const fileOf = (stateDir: string) => join(stateDir, "sessions.json");
+
+export function writeSessions(stateDir: string, s: SessionsFile): void {
+  const tmp = `${fileOf(stateDir)}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(s)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, fileOf(stateDir));
+}
+
+export function readSessions(stateDir: string): SessionsFile | undefined {
+  if (!existsSync(fileOf(stateDir))) return undefined;
+  try {
+    const s = JSON.parse(readFileSync(fileOf(stateDir), "utf8")) as SessionsFile;
+    if (!Array.isArray(s.peers)) return undefined;
+    // A record without a peer id or metadata says nothing to resume, and reading it would stop recovery for the rest.
+    return { ...s, peers: s.peers.filter((p) => !!p && typeof p.peer === "string" && !!p.meta && typeof p.meta === "object") };
+  } catch {
+    return undefined; // cut short by the crash: nothing to resume from
+  }
+}
+
+/**
+ * Only the run that wrote it removes it: a stop of an older instance must not erase a newer run's record. Without an
+ * instance id it goes whatever wrote it (a controlled restart, which has its own record of the peers).
+ */
+export function removeSessions(stateDir: string, instanceId?: string): void {
+  if (instanceId === undefined || readSessions(stateDir)?.instanceId === instanceId) rmSync(fileOf(stateDir), { force: true });
+}
+
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
+
+/**
+ * What can come back after a crash. `resume` holds the start arguments for peers the hub launches itself (Kimi through
+ * ACP `session/load`, Pi through its session file, the local worker afresh); the others say what the user has to do.
+ */
+export function crashPlan(records: SessionRecord[]): { peer: string; resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }[] {
+  return records.map(({ peer, meta }) => {
+    const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
+    const model = str(launch.model);
+    switch (peer) {
+      case "claude":
+        return { peer, how: "claude: the Claude Code plugin reconnects by itself while that session is still open" };
+      case "codex":
+        return { peer, how: `codex: its app-server died with the hub; run ahub codex again${str(meta.threadId) ? ` (its conversation was thread ${meta.threadId})` : ""}` };
+      case "kimi": {
+        const sessionId = str(meta.sessionId);
+        if (!sessionId) return { peer, how: "kimi: no session id was recorded; start it again with ahub kimi" };
+        return { peer, resume: { sessionId, ...(model ? { model } : {}) }, how: `kimi: session ${sessionId} can be loaded again (ACP session/load)` };
+      }
+      case "pi": {
+        // `fresh`: what a new headless session keeps of the recorded one (pi.auto_start's fallback, #66).
+        const fresh: Record<string, string> = {};
+        for (const k of ["backend", "model"] as const) if (str(launch[k])) fresh[k] = str(launch[k])!;
+        const sessionFile = str(meta.sessionFile) ?? str(launch.sessionFile);
+        if (!sessionFile) return { peer, fresh, how: "pi: no session file was recorded; start it again with ahub pi" };
+        // A terminal Pi is run by the CLI that launched it, not by the hub: nothing here could start it again.
+        if (str(launch.mode) === "tui") return { peer, fresh, tui: true, how: `pi: it ran in a terminal; start it again with ahub pi --mode tui --session-file ${sessionFile}` };
+        const args: Record<string, string> = { sessionFile };
+        for (const k of ["mode", "backend", "model"] as const) if (str(launch[k])) args[k] = str(launch[k])!;
+        return { peer, fresh, resume: args, how: `pi: its session file can be resumed (${sessionFile})` };
+      }
+      case "local": {
+        // `model` is also recorded as the route's fallback, and a model given at start pins it: pass one or the other.
+        const route = str(launch.route);
+        const args: Record<string, string> = route ? { route } : model ? { model } : {};
+        return { peer, resume: args, how: "local: starts again without its history (the worker keeps none across a hub stop)" };
+      }
+      default:
+        return { peer, how: `${peer}: reconnects by itself if its client is still running` };
+    }
+  });
+}
+
+/**
+ * The loss notice for one peer: the deliveries to it that the crash left in needs_review, with their senders and the
+ * tasks they were about. `taskTitle` must return the public title (`#n [pii]` for a PII task). No message text.
+ */
+export function lossNotice(lost: JournalDelivery[], taskTitle: (id: number) => string | undefined): string {
+  const lines = lost.map((d) => {
+    const from = [...new Set(d.originals.map((e) => e.from))].join(", ");
+    const tasks = [...new Set(d.originals.map((e) => Number(e.refs?.task)).filter((n) => Number.isInteger(n) && n > 0))].map((n) => taskTitle(n) ?? `#${n}`);
+    return `- delivery ${d.id} from ${from}${tasks.length ? `, about task ${tasks.join(", ")}` : ""}`;
+  });
+  return [
+    "The hub stopped unexpectedly and was started again. These deliveries to you were in flight when it stopped, so whether you acted on them is not known; the console has since marked each one completed, retried or discarded:",
+    ...lines,
+    "Check your work against them before you go on.",
+  ].join("\n");
+}

package/src/hub/daemon.ts

@@ -14,7 +14,8 @@ import { PiPeer } from "../adapters/pi.ts";
 import { startModelRelay, type ModelRelay } from "../models/relay.ts";
 import type { MlxOptions } from "../models/mlx.ts";
 import { PiToolReceipts } from "../pi/tool-receipts.ts";
-import { profile } from "../local/sandbox.ts";
+import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
+import { DEFAULT_NETWORK_ALLOW, startEgressProxy, type EgressProxy } from "../local/proxy.ts";
 import { runTool, TOOL_SCHEMAS, type ToolContext } from "../local/tools.ts";
 import { LocalPeer } from "../adapters/local-worker.ts";
 import { Capture, skipTools } from "../memory/capture.ts";
@@ -42,6 +43,8 @@ import { MemoryClient, workerUrl } from "../memory/client.ts";
 import { VERSION } from "../version.ts";
 import { projectChain, recallFor } from "../memory/recall.ts";
 import { conflictsOf } from "./conflicts.ts";
+import { crashPlan, lossNotice, readSessions, removeSessions, writeSessions, type SessionsFile } from "./crash.ts";
+import type { JournalDelivery } from "./delivery-journal.ts";
 import { DEFAULT_LIMITS, Limiter, PROJECT_LIMITS, type LimitsConfig } from "./limits.ts";
 import { changedPaths, repoOf, snapshot, Turns } from "./snapshots.ts";
 import { archiveRestartSnapshot, readRestartSnapshot, removeRestartSnapshot, restartPath, writeRestartSnapshot, type RecoveryPhase, type RestartPeerSnapshot, type RestartSnapshot } from "./restart.ts";
@@ -60,7 +63,9 @@ export interface HubConfig {
   omniroute: OmniRouteConfig;
   pi: { enabled: boolean; auto_start: boolean; cmd: string[]; backend: "auto" | "dgx" | "mlx"; dgx_coding: string; dgx_fast: string; max_steps: number };
   mlx: Pick<MlxOptions, "provider" | "host" | "runtimeDir" | "modelPath" | "port" | "model" | "sourceModel" | "contextWindow" | "maxInputTokens" | "maxTokens" | "maxConcurrency">;
-  local: { deny: string[]; bash_network: boolean; max_steps: number; read_allow: string[] };
+  /** `sandbox`: "deny-default" (issue #39), or "allow-default", the profile of 0.9 and earlier, kept for one release. */
+  /** `bash_network`: true is network through the egress proxy to `network_allow` (#65); "direct" is everything, for one release. */
+  local: { deny: string[]; bash_network: boolean | "direct"; network_allow: string[]; max_steps: number; read_allow: string[]; sandbox: "deny-default" | "allow-default" };
   /** Pending permission requests: how long they wait, and whether the desktop is told (issue #5). */
   approvals: { timeout_s: number; notify: boolean };
   /** An owner offline this long loses its open tasks back to routing; 0 turns it off (issue #6). */
@@ -71,6 +76,12 @@ export interface HubConfig {
   snapshots: { enabled: boolean; keep: number };
   /** Per-sender rate limits and repeat suppression for what agents send (issue #38). */
   limits: LimitsConfig;
+  /** Reviewer choice from recorded review outcomes, once a reviewer has `min_reviews` of an implementer (issue #35). */
+  review: { adaptive: boolean; min_reviews: number };
+  /** After an unplanned stop, start Kimi, Pi and the local worker again with their recorded sessions (issue #37). */
+  recovery: { auto_resume_after_crash: boolean };
+  /** Per peer, the hub-tool capabilities it has (issue #39); a peer not listed has all of them. */
+  capabilities: Record<string, string[]>;
   /** Machine-local fields a config file set but git could not vouch for, and why (issue #17). */
   ignored?: string[];
 }
@@ -88,7 +99,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   omniroute: DEFAULT_OMNIROUTE,
   pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto", dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 },
   mlx: { provider: "ollama", model: "agenthub-fast-mlx:4b-8k", sourceModel: "qwen3.5:4b-mlx", contextWindow: 8192, maxInputTokens: 6000, maxTokens: 2048, maxConcurrency: 1 },
-  local: { deny: [], bash_network: false, max_steps: 30, read_allow: [] },
+  local: { deny: [], bash_network: false, network_allow: DEFAULT_NETWORK_ALLOW, max_steps: 30, read_allow: [], sandbox: "deny-default" },
   // Off here, so tests and a hub without a config file stay silent; a project's config defaults it on for macOS.
   approvals: { timeout_s: 120, notify: false },
   tasks: { release_after_min: 30 },
@@ -96,6 +107,9 @@ export const DEFAULT_CONFIG: HubConfig = {
   // Off here like approvals.notify, so tests (whose cwd is this repository) write no objects; a project's config turns it on.
   snapshots: { enabled: false, keep: 20 },
   limits: DEFAULT_LIMITS,
+  review: { adaptive: false, min_reviews: 5 },
+  recovery: { auto_resume_after_crash: false },
+  capabilities: {},
 };
 
 export { stateDirFor };
@@ -106,7 +120,7 @@ const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 
 /** The shared project config, then the machine's own file, which overrides it block by block (issue #17). */
 const CONFIG_FILES = ["config.json", "config.local.json"] as const;
-const CONFIG_BLOCKS = ["memory", "roles", "budget", "inference", "omniroute", "local", "pi", "approvals", "tasks", "checks", "snapshots", "limits", "mlx"];
+const CONFIG_BLOCKS = ["memory", "roles", "budget", "inference", "omniroute", "local", "pi", "approvals", "tasks", "checks", "snapshots", "limits", "review", "recovery", "capabilities", "mlx"];
 
 export function loadConfig(cwd: string): HubConfig {
   const ignored: string[] = [];
@@ -151,6 +165,9 @@ export function loadConfig(cwd: string): HubConfig {
     checks: { ...DEFAULT_CONFIG.checks, ...file.checks },
     snapshots: { ...DEFAULT_CONFIG.snapshots, enabled: true, ...file.snapshots },
     limits: { ...PROJECT_LIMITS, ...file.limits }, // on with any project config (issue #38)
+    review: { ...DEFAULT_CONFIG.review, ...file.review },
+    recovery: { ...DEFAULT_CONFIG.recovery, ...file.recovery },
+    capabilities: { ...file.capabilities },
     mlx,
     ...(ignored.length ? { ignored } : {}),
   };
@@ -280,9 +297,36 @@ export async function startDaemon(opts: DaemonOptions) {
     : undefined;
   if ((restartFilePresent && !restored) || (recoveryOperation && !restored)) throw new Error("restart state is unreadable, missing, or does not match this project and recovery operation");
 
+  // A session record left by a run that never shut down means it crashed (issue #37). A controlled restart has its own.
+  const crashed = !recoveryOperation && !restartFilePresent ? readSessions(opts.stateDir) : undefined;
+  // A controlled restart's source may have been cut short before it removed its record: this run is not a crash, and
+  // a record left now would make the next ordinary start look like one.
+  if (recoveryOperation || restartFilePresent) try { removeSessions(opts.stateDir); } catch { /* nothing to remove */ }
+  const autoResume = config.recovery.auto_resume_after_crash === true; // a string "false" is not a yes
+  const piAutoStart = config.pi.enabled && config.pi.auto_start;
+  const startedAt = Date.now();
+  /** What crash recovery did or asks the user to do, for `ahub status`. */
+  const crashReport: string[] = [];
+
   // The hub's own model calls (digest condensation, task triage) are wired below, once the gateway client exists.
   let inference: Inference | undefined;
   const journal = new DeliveryJournal({ file: join(opts.stateDir, "hub.db"), projectRoot: opts.cwd, projectId, instanceId, operationId: recoveryOperation });
+  // What the crash left in flight, per recipient: opening the journal just marked these needs_review.
+  const lost = new Map<PeerId, JournalDelivery[]>();
+  if (crashed) for (const d of journal.list()) if (d.state === "needs_review" && d.reason === "daemon stopped during delivery" && d.updatedAt >= startedAt) lost.set(d.peer, [...(lost.get(d.peer) ?? []), d]);
+  // Capabilities (issue #39): enforced here and in taskOp, never by role text alone. Unlisted peers keep everything.
+  // A listed peer whose value is not a list gets nothing: whoever listed it meant to narrow it.
+  const may = (peer: PeerId, cap: "propose" | "assign" | "remember" | "important"): boolean => {
+    if (peer === USER || peer === HUB || !Object.hasOwn(config.capabilities, peer)) return true;
+    const list = config.capabilities[peer];
+    return Array.isArray(list) && list.includes(cap);
+  };
+  const CAPABILITIES = ["propose", "assign", "remember", "important"];
+  for (const [peer, list] of Object.entries(config.capabilities)) {
+    if (!PEER_ID.test(peer)) log(`capabilities.${peer} is not a peer id; ignored (capabilities is an object of lists, one per peer)`);
+    else if (!Array.isArray(list)) log(`capabilities.${peer} is not a list: ${peer} gets no capabilities`);
+    else for (const c of list) if (!CAPABILITIES.includes(c)) log(`capabilities.${peer}: ${JSON.stringify(c)} is not a capability (${CAPABILITIES.join(", ")}); it grants nothing`);
+  }
   // Agents only: the console user and the hub itself are never limited (issue #38).
   // A typo such as "12/min" would read as 0, which turns a limit off without a word: the project default instead.
   for (const k of Object.keys(config.limits)) if (!(k in PROJECT_LIMITS)) log(`limits.${k} is not a known limit; ignored`);
@@ -293,9 +337,23 @@ export async function startDaemon(opts: DaemonOptions) {
     return [k, fallback];
   })) as unknown as LimitsConfig;
   const limiter = new Limiter(limits);
+  // The local worker's and Pi's commands reach the network only through this proxy (issue #65); "direct" keeps the
+  // open network of 0.10 and earlier for one release, anything else means none.
+  let egress: EgressProxy | undefined;
+  if (config.local.bash_network === true) {
+    const allow = Array.isArray(config.local.network_allow) ? config.local.network_allow.filter((h): h is string => typeof h === "string") : DEFAULT_NETWORK_ALLOW;
+    egress = await startEgressProxy({ allow, log });
+    startupCleanup.push(() => void egress?.close());
+    log(`network: egress proxy on 127.0.0.1:${egress.port}, ${allow.length} allowed host(s) (local.network_allow)`);
+  }
+  const sandboxNetwork: SandboxNetwork = config.local.bash_network === "direct" ? true : egress ? { proxyPort: egress.port } : false;
   const admit = (env: Envelope, parent?: string): string | undefined => {
     // [FYI] is recorded and costs nobody a turn: nothing to limit.
     if (env.from === USER || env.from === HUB || env.from === DIGEST || env.priority === "fyi") return undefined;
+    if (env.priority === "important" && !may(env.from, "important")) {
+      log(`capabilities: ${env.from} may not send important messages`);
+      return `${env.from} may not send important messages (no "important" in capabilities.${env.from}): send it without [IMPORTANT]`;
+    }
     const refused = limiter.admit(env.from, env.to, env.priority, env.body, parent);
     if (refused) log(`limits: ${env.from}: ${refused}`);
     return refused;
@@ -410,6 +468,7 @@ export async function startDaemon(opts: DaemonOptions) {
     },
     triage: { classify: (title, detail) => inference?.triage(title, detail) ?? Promise.resolve(undefined), onCampus: () => onCampus() },
     quota: (): ReturnType<Budget["headroom"]> => budget.headroom(), // budget is built below; this runs at assignment time
+    review: config.review,
   });
   board.onChange = (t, h) => event({ type: "task", id: t.id, event: h.event, by: h.by, state: t.state, owner: t.owner, reviewer: t.reviewer, class: t.class, pii: tasks.isPii(t) });
   // ---- budget relay -------------------------------------------------------------------------------------------
@@ -555,6 +614,13 @@ export async function startDaemon(opts: DaemonOptions) {
       taskOpsInFlight--;
     }
   };
+  /** A model-written peer argument: a peer id, or nothing for absent, null or "". Anything else is refused. */
+  const peerArg = (v: unknown, name: string): PeerId | undefined => {
+    if (v == null || v === "") return undefined;
+    const id = typeof v === "string" ? v.trim().toLowerCase() : undefined; // peer ids are lowercase; "Codex" means codex
+    if (!id || !PEER_ID.test(id)) throw new Error(`${name} must be a peer id, not ${JSON.stringify(v).slice(0, 60)}`);
+    return id;
+  };
   async function taskOpBody(by: PeerId, op: string, a: Record<string, any>, inProcess = false, piiTurn = false): Promise<string> {
     // Inside a PII turn the worker's words may carry the PII whatever they are attached to: a note would go to
     // claude-mem (a cloud observer) and a new task could be routed to a cloud peer without matching any pattern.
@@ -570,6 +636,18 @@ export async function startDaemon(opts: DaemonOptions) {
     // console reads a PII task's text deliberately, with `ahub task show <id>`.
     const onPrem = inProcess && by === "local";
     const line = (t: { id: number; state: string; owner: PeerId | null; reviewer: PeerId | null }) => `task #${t.id}: ${t.state}, owner ${t.owner ?? "none"}, reviewer ${t.reviewer ?? "none"}`;
+    const need = (cap: "propose" | "assign" | "remember", what: string) => {
+      if (may(by, cap)) return;
+      log(`capabilities: ${by} may not ${what} (${op})`);
+      throw new Error(`${by} may not ${what} (no "${cap}" in capabilities.${by} in .agenthub/config.json)`);
+    };
+    // Tool callers are models (#70): `owner` is a peer id or nothing, settled before anything reaches the board.
+    if (op === "hub_task_propose") {
+      a = { ...a, owner: peerArg(a.owner, "owner") };
+      need("propose", "propose tasks");
+      if (a.owner && a.owner !== by) need("assign", "hand tasks to other peers");
+    }
+    if (op === "hub_remember") need("remember", "save notes to shared memory");
     switch (op) {
       case "hub_task_propose": {
         const t = await tasks.propose(by, a);
@@ -588,7 +666,7 @@ export async function startDaemon(opts: DaemonOptions) {
         return tasks.isChecking(t.id) ? `${line(t)}; its check is queued or running, and the result comes as a task message` : line(t);
       }
       case "hub_review":
-        return line(await tasks.review(by, a.id, a.verdict, a.note));
+        return line(await tasks.review(by, a.id, a.verdict, a.note, a.unmet));
       case "hub_remember":
         return tasks.remember(by, a);
       case "hub_checkpoint": {
@@ -604,9 +682,12 @@ export async function startDaemon(opts: DaemonOptions) {
     if (by !== USER) throw new Error(`${op} is a console command`);
     switch (op) {
       case "task_show":
-        return JSON.stringify(board.get(Number(a.id)) ?? `no task #${a.id}`, null, 2);
-      case "task_assign":
-        return line(await tasks.assignTo(a.id, String(a.peer)));
+        return JSON.stringify(board.get(Number(a.id)) ? { ...board.get(Number(a.id)), reviews: board.reviews({ task: Number(a.id) }) } : `no task #${a.id}`, null, 2);
+      case "task_assign": {
+        const peer = peerArg(a.peer, "peer");
+        if (!peer) throw new Error("peer is required");
+        return line(await tasks.assignTo(a.id, peer));
+      }
       case "task_escalate":
         return line(await tasks.escalate(USER, a.id));
       case "route_explain":
@@ -735,6 +816,7 @@ export async function startDaemon(opts: DaemonOptions) {
     return now;
   };
   const status = () => ({
+    ...(crashReport.length ? { crash: crashReport } : {}),
     projectId,
     instanceId,
     version: VERSION,
@@ -833,6 +915,49 @@ export async function startDaemon(opts: DaemonOptions) {
     }
   };
 
+  // Session identities of the attached peers, kept current for crash recovery (issue #37); a clean stop removes them.
+  let sessionsWritten = "";
+  const recordSessions = () => {
+    if (stopping) return;
+    const peers = [...bus.peers.values()].filter((p) => p.state !== "offline").map((p) => {
+      let meta: Record<string, unknown> = {};
+      try { meta = (p as { recoveryMetadata?: () => Record<string, unknown> }).recoveryMetadata?.() ?? {}; } catch { /* not ready yet: the id alone */ }
+      return { peer: p.id, meta };
+    });
+    const text = JSON.stringify(peers);
+    if (text === sessionsWritten) return;
+    sessionsWritten = text;
+    try { writeSessions(opts.stateDir, { instanceId, at: Date.now(), peers }); } catch (error) { log(`session record not written: ${(error as Error).message}`); }
+  };
+  const recoverAfterCrash = async (prev: SessionsFile) => {
+    const report = (line: string) => (crashReport.push(line), notify(`crash recovery: ${line}`));
+    const lostCount = [...lost.values()].reduce((n, l) => n + l.length, 0);
+    report(`the previous hub run stopped without shutting down${lostCount ? `; ${lostCount} deliveries it had in flight are in needs_review (ahub queue list)` : ""}`);
+    const start = (peer: string, args: Parameters<typeof startPeer>[1]) => startPeer(peer, args).catch((e: Error) => ({ ok: false, error: e.message }));
+    for (const step of crashPlan(prev.peers)) {
+      // `pi.auto_start` already asks for Pi (#66): its recorded headless session comes back, auto-resume or not, and a
+      // fresh one starts when that fails or there is nothing headless to resume. Pi runs on-prem: no cloud quota.
+      if (step.peer === "pi" && piAutoStart) {
+        if (step.resume) {
+          const r = await start("pi", step.resume as Parameters<typeof startPeer>[1]);
+          if (r.ok) { report(`pi resumed (pi.auto_start): ${step.how}`); continue; }
+          report(`pi not resumed (${String(r.error)}); ${step.how}`);
+        } else report(step.how);
+        const fresh = await start("pi", { ...(step.fresh as Parameters<typeof startPeer>[1]), fresh: true });
+        const back = step.tui ? `; to go back to the recorded session, run ahub kill, start the hub without pi.auto_start, then the command above` : "";
+        report(fresh.ok ? `pi.auto_start started a fresh session${back}` : `pi.auto_start could not start Pi either (${String(fresh.error)})`);
+        continue;
+      }
+      if (!step.resume || !autoResume) {
+        report(`${step.how}${step.resume ? " (recovery.auto_resume_after_crash is off)" : ""}`);
+        continue;
+      }
+      const r = await start(step.peer, step.resume as Parameters<typeof startPeer>[1]);
+      report(r.ok ? `${step.peer} resumed: ${step.how}` : `${step.peer} not resumed (${String(r.error)}); ${step.how}`);
+    }
+    writeStatus();
+  };
+
   bus.tap((e) => {
     e = redact(e);
     uiEvents.push({ seq: ++uiSequence, event: e });
@@ -873,6 +998,13 @@ export async function startDaemon(opts: DaemonOptions) {
       }
       if (e.state === "offline") offlineSince.set(e.peer, offlineSince.get(e.peer) ?? Date.now());
       else offlineSince.delete(e.peer);
+      // After a crash, a peer's first attach brings the loss notice: it leads its next delivery (issue #37).
+      if (e.state !== "offline" && lost.has(e.peer)) {
+        const still = lost.get(e.peer)!.filter((d) => { try { return journal.get(d.id)?.state === "needs_review"; } catch { return false; } });
+        lost.delete(e.peer);
+        if (still.length) bus.preface(e.peer, lossNotice(still, (id) => { const t = board.get(id); return t ? tasks.publicTitle(t) : undefined; }));
+      }
+      recordSessions();
     }
     else if (e.t === "undeliverable" || e.t === "overflow") {
       log(e.t === "undeliverable" ? `UNDELIVERABLE to ${e.peer} after retries: ${e.env.id} from ${e.env.from}` : `OVERFLOW ${e.peer}: dropped ${e.env.id} from ${e.env.from}`);
@@ -944,7 +1076,7 @@ export async function startDaemon(opts: DaemonOptions) {
 
   // One start per peer at a time: a second `ahub codex` must not tear down an adapter that is still coming up.
   const starting = new Map<string, Promise<Record<string, unknown>>>();
-  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string }): Promise<Record<string, unknown>> {
+  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean }): Promise<Record<string, unknown>> {
     if (stopping) return Promise.resolve({ ok: false, error: "hub is stopping" });
     if (peer === "pi" && starting.has(peer)) return Promise.resolve({ ok: false, error: "Pi start is in progress; inspect status before retrying" });
     const running = starting.get(peer) ?? startPeerOnce(peer, args).finally(() => starting.delete(peer));
@@ -968,7 +1100,7 @@ export async function startDaemon(opts: DaemonOptions) {
     };
   }
 
-  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string }): Promise<Record<string, unknown>> {
+  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean }): Promise<Record<string, unknown>> {
     let unmute: (() => void) | undefined;
     try {
       return await startPeerBody(peer, args, (p) => { unmute = muteState(p); });
@@ -977,7 +1109,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
   }
 
-  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
+  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
     if (peer === "pi") {
       if (args.mode !== undefined && !["headless", "tui"].includes(args.mode)) return { ok: false, error: "invalid Pi mode" };
       if (args.backend !== undefined && !["auto", "dgx", "mlx"].includes(args.backend)) return { ok: false, error: "invalid Pi backend" };
@@ -993,7 +1125,8 @@ export async function startDaemon(opts: DaemonOptions) {
       const unclaimed = existing.state === "offline" && !saved.sessionId && !saved.sessionFile;
       if (changesOwner && (existing.state === "busy" || (existing.state !== "offline" && !existing.recoveryReady))) return { ok: false, error: "Pi is busy; wait for agent_settled before changing mode/backend" };
       if (unclaimed) {
-        if (!args.sessionId && !args.sessionFile) args = { ...args, ...existing.pendingResume };
+        // `fresh` (crash recovery's fallback, #66): the pending session is the one that just failed to load.
+        if (!args.sessionId && !args.sessionFile && !args.fresh) args = { ...args, ...existing.pendingResume };
         // Revoke the previous launch bridge before issuing another launch. A late
         // process from the abandoned CLI cannot claim the replacement owner.
         // The replacement's start event is the only state change the console should see (issue #42).
@@ -1023,6 +1156,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const kimi = new AcpPeer("kimi", {
         cmd,
         ...(args.model ? { launchModel: args.model } : {}),
+        ...(args.sessionId ? { resumeSessionId: args.sessionId } : {}),
         cwd: opts.cwd,
         watchdogMs: config.watchdog_ms,
         onPermission,
@@ -1082,7 +1216,8 @@ export async function startDaemon(opts: DaemonOptions) {
       let piReply: Envelope | undefined;
       const ctx: ToolContext = {
         cwd: opts.cwd, deny: config.local.deny,
-        sandboxProfile: profile(opts.cwd, config.local.bash_network, config.local.read_allow, config.local.deny),
+        sandboxProfile: profile(opts.cwd, sandboxNetwork, config.local.read_allow, config.local.deny, config.local.sandbox === "allow-default" ? "allow" : "deny"),
+        sandboxEnv: proxyEnv(sandboxNetwork),
         permit: (title) => onPermission({ peer: "pi", title, options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }, { optionId: "deny", name: "Deny", kind: "reject_once" }] }).then((picked) => picked === "allow" && pi.acceptingTools && bus.peers.get("pi") === pi),
         send: (text, to) => {
           if (to?.some((id) => !bus.peers.has(id) && id !== USER)) return "error: unknown peer";
@@ -1173,7 +1308,7 @@ export async function startDaemon(opts: DaemonOptions) {
         omni,
         ...(sidecar && route ? { sidecar, route } : {}),
         fixedModel: args.model ?? routing.local.fixed_model,
-        tools: { deny: config.local.deny, bashNetwork: config.local.bash_network, readAllow: config.local.read_allow, permit },
+        tools: { deny: config.local.deny, bashNetwork: sandboxNetwork, readAllow: config.local.read_allow, sandbox: config.local.sandbox, permit },
         ...(capture ? { capture } : {}),
         taskTool: (name, a, turn) => taskOp("local", name, a, true, turn.pii),
         turnPolicy: (envs) => tasks.turnPolicy(envs),
@@ -1619,6 +1754,8 @@ export async function startDaemon(opts: DaemonOptions) {
   }
   async function stopOnce(): Promise<void> {
     stopping = true;
+    // A stop someone asked for is not a crash, even if it then runs past the shutdown deadline: forget the sessions now.
+    try { removeSessions(opts.stateDir, instanceId); } catch { /* the state dir is gone */ }
     checksClosed = true;
     for (const kill of runningChecks) kill();
     log("hub stopping");
@@ -1636,6 +1773,7 @@ export async function startDaemon(opts: DaemonOptions) {
       // logged and shutdown finishes anyway, or the process ignores SIGTERM forever.
       for (const exit of exits) if (exit.status === "rejected") log(`peer stop failed during shutdown: ${(exit.reason as Error)?.message ?? exit.reason}`);
       await modelRelay?.close();
+      await egress?.close();
       await piReceipts?.close();
       budget.close();
       board.close();
@@ -1674,7 +1812,18 @@ export async function startDaemon(opts: DaemonOptions) {
   writeStatus();
   log(`${RUN_START}${process.pid} control=127.0.0.1:${server.port} cwd=${opts.cwd}`);
   ready = true;
-  if (config.pi.enabled && config.pi.auto_start && !recoveryActive()) void startPeer("pi", {}).catch((error) => log(`Pi auto-start failed: ${error.message}`));
+  if (crashed) {
+    // This run owns the record now, so its clean stop removes it even if no peer attaches to rewrite it.
+    try { if (readSessions(opts.stateDir)?.instanceId === crashed.instanceId) writeSessions(opts.stateDir, { ...crashed, instanceId, at: Date.now() }); } catch (error) { log(`session record not adopted: ${(error as Error).message}`); }
+    void recoverAfterCrash(crashed).catch((error) => {
+      log(`crash recovery failed: ${(error as Error).message}`);
+      // pi.auto_start still holds: a running Pi answers `already`, a starting one refuses the second start.
+      if (piAutoStart) void startPeer("pi", {}).catch((e) => log(`Pi auto-start failed: ${e.message}`));
+    });
+  }
+  // After a crash that recorded Pi, crash recovery starts it (#66): its recorded session first, a fresh one if that fails.
+  const piRecovered = !!crashed?.peers.some((p) => p.peer === "pi");
+  if (piAutoStart && !recoveryActive() && !piRecovered) void startPeer("pi", {}).catch((error) => log(`Pi auto-start failed: ${error.message}`));
   return { bus, token, port: server.port as number, stop, stopped: new Promise<void>((r) => (onStop = r)) };
   } finally {
     if (!ready) for (const cleanup of startupCleanup.reverse()) { try { cleanup(); } catch { /* preserve startup error */ } }

package/src/hub/hub-tools.ts

@@ -40,7 +40,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result, and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
 ];