@staix/agent-hub 0.7.6 → 0.7.8

package/docs/specs/2026-09-20-upgrade-recovery-design.md

@@ -113,6 +113,12 @@ stopped with its matching CLI before a protocol-8 manager is launched.
 
 ## Current 0.7.0 correction and recovery contract
 
+Amended 2026-09-30: 0.7.0 shipped protocol 10 and the queue commands; protocol 10
+went into production with 0.7.0 and was verified there with 0.7.1, where
+`ahub queue list` read back live receipts ([smoke checklist](../smoke.md)). `ahub queue show` and `ahub queue resolve` are
+covered by tests, not by a live run. The paragraphs below keep the pre-release
+wording.
+
 The earlier sections record the protocol-8 implementation history. The current
 release is 0.6.4 with protocol 9; the next target is 0.7.0 with protocol 10.
 This correction supersedes the earlier protocol-8 source/target statement for
@@ -146,6 +152,6 @@ The documented verification sequence is: run a dry-run, verify package and
 session identity, manually confirm Claude recovery, read back version, session,
 queue, task, and budget state, then release the held queues. Do not claim a
 successful 0.7.0 cutover from tests, synthetic approvals, or package
-installation alone. Issue [#12](https://github.com/STAIxBWLB/agent-hub/issues/12)
+installation alone. Issue [#1](https://github.com/STAIxBWLB/agent-hub/issues/1)
 remains open for off-campus Access credentials and a natural near-limit budget
 pause.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15727,7 +15727,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.7.6",
+  version: "0.7.8",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15806,7 +15806,7 @@ var TASK_TOOLS = [
   tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you.", { id }, ["id"]),
   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.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
+  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"] } }),
   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_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"]),

package/src/adapters/acp.ts

@@ -13,6 +13,8 @@ export interface PermissionRequest {
   peer: PeerId;
   title: string;
   options: PermissionOption[];
+  /** The tool's name alone, when the adapter knows it apart from the title (which can quote the payload). */
+  tool?: string;
 }
 
 export interface AcpOptions {
@@ -33,6 +35,8 @@ export interface AcpOptions {
   /** Resolve with an optionId, or undefined to cancel. Absent = every request is cancelled.
    *  A request whose payload could not be resolved is titled as such and carries no session-wide allow option. */
   onPermission?: (req: PermissionRequest) => Promise<string | undefined>;
+  /** Tool titles approved once without asking: the hub's own tools, as Codex gets them (issue #72). Exact names only. */
+  autoApprove?: (toolTitle: string) => boolean;
   log?: (line: string) => void;
 }
 
@@ -42,6 +46,16 @@ const TOOL_INPUT_CAP = 64;
 
 type Pending = { resolve: (v: any) => void; reject: (e: Error) => void };
 
+/** Streamed argument text as a payload: a complete JSON object, or nothing (a partial stream is not what will run). */
+function jsonObject(text: string | undefined): object | undefined {
+  try {
+    const v = text === undefined ? undefined : JSON.parse(text);
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** ACP client (JSON-RPC 2.0, newline-delimited, over the child's stdio). One session, one prompt in flight. */
 export class AcpPeer extends BasePeer {
   private proc: ChildProcessWithoutNullStreams | undefined;
@@ -50,6 +64,7 @@ export class AcpPeer extends BasePeer {
   private readonly pending = new Map<number, Pending>();
   private chunks: string[] = [];
   private readonly toolInputs = new Map<string, unknown>();
+  private readonly toolText = new Map<string, string>(); // streamed argument text, per call, until it finishes
   private primed = false;
   private turn = 0; // generation: a prompt cancelled by the watchdog must not touch the turn that followed it
   private activeDeliveryId: string | undefined;
@@ -183,10 +198,15 @@ export class AcpPeer extends BasePeer {
       if (u?.sessionUpdate === "agent_message_chunk" && u.content?.type === "text") this.chunks.push(u.content.text);
       // The permission request that follows may carry no `rawInput` (Kimi 2.0.1 does not), and then the
       // console would be asked to approve a bare tool name. Keep what the call said it would run (issue #31).
+      // Kimi 2.1.1 sends no rawInput before the answer either: the argument JSON streams as content text (issue #72).
       else if ((u?.sessionUpdate === "tool_call" || u?.sessionUpdate === "tool_call_update") && typeof u.toolCallId === "string") {
+        // A new call starts clean, so a reused id can never show the arguments of the call before it.
+        if (u.sessionUpdate === "tool_call") (this.toolInputs.delete(u.toolCallId), this.toolText.delete(u.toolCallId));
         if (u.rawInput !== undefined) this.toolInputs.set(u.toolCallId, u.rawInput);
-        if (u.status === "completed" || u.status === "failed") this.toolInputs.delete(u.toolCallId);
-        while (this.toolInputs.size > TOOL_INPUT_CAP) this.toolInputs.delete(this.toolInputs.keys().next().value as string);
+        const text = Array.isArray(u.content) ? u.content.map((c: any) => (c?.type === "content" && c.content?.type === "text" ? String(c.content.text) : "")).join("") : "";
+        if (text) this.toolText.set(u.toolCallId, text);
+        if (u.status === "completed" || u.status === "failed") (this.toolInputs.delete(u.toolCallId), this.toolText.delete(u.toolCallId));
+        for (const map of [this.toolInputs, this.toolText]) while (map.size > TOOL_INPUT_CAP) map.delete(map.keys().next().value as string);
       }
       else if (u?.sessionUpdate === "usage_update" && this.opts.onTokens) {
         const f = { ...u, ...(typeof u.usage === "object" ? u.usage : {}) } as Record<string, unknown>;
@@ -208,14 +228,34 @@ export class AcpPeer extends BasePeer {
 
   private async answerPermission(msg: any): Promise<void> {
     const call = msg.params?.toolCall ?? {};
+    const once = (msg.params?.options ?? []).find((o: PermissionOption) => o.kind === "allow_once");
+    if (once && typeof call.title === "string" && this.opts.autoApprove?.(call.title)) {
+      this.opts.log?.(`permission auto-approved for ${this.id}: ${call.title}`); // the name only: arguments may quote a PII turn
+      return this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: { outcome: "selected", optionId: once.optionId } } });
+    }
     // The approver has to see what runs, not only the tool's name ("Bash"). The request itself carries it
-    // for some agents; for the rest it was on the `tool_call` update that announced the call.
-    const raw = call.rawInput ?? (typeof call.toolCallId === "string" ? this.toolInputs.get(call.toolCallId) : undefined);
-    const input = raw === undefined ? "" : `: ${(typeof raw === "string" ? raw : JSON.stringify(raw)).slice(0, 600)}`;
+    // for some agents; for the rest it was on the `tool_call` update that announced the call, as rawInput or,
+    // failing that, as streamed argument text that only counts once it is a complete JSON object.
+    const id = typeof call.toolCallId === "string" ? call.toolCallId : undefined;
+    const raw = call.rawInput ?? (id === undefined ? undefined : this.toolInputs.get(id) ?? jsonObject(this.toolText.get(id)));
+    const full = raw === undefined ? "" : typeof raw === "string" ? raw : JSON.stringify(raw);
+    // A cut payload hides its tail, and a tail can change what runs: it is marked and buys no session-wide grant.
+    const cut = full.length > 600;
+    const input = raw === undefined ? "" : `: ${cut ? `${full.slice(0, 600)} [cut, ${full.length} chars]` : full}`;
     // An unknown payload is never dressed up as a description, and it must not buy a blanket grant.
     const title: string = raw === undefined ? `${call.title ?? "tool call"} (payload not reported by the agent)` : `${call.title ?? "tool call"}${input}`;
-    const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => raw !== undefined || o.kind !== "allow_always");
-    const picked = await this.opts.onPermission?.({ peer: this.id, title, options }).catch(() => undefined);
+    const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => (raw !== undefined && !cut) || o.kind !== "allow_always");
+    // Only a bare tool name travels on its own (a desktop notice shows it); anything prose-like stays in the title.
+    const tool = typeof call.title === "string" && /^[\w.:@-]{1,80}$/.test(call.title) ? call.title : undefined;
+    // Waiting for a person is not the agent going silent: keep the watchdog from cancelling the turn meanwhile.
+    const turn = this.turn;
+    const alive = setInterval(() => this.state === "busy" && turn === this.turn && this.touch(), Math.max(10, Math.min(30_000, Math.floor(this.watchdogMs / 3))));
+    let picked: string | undefined;
+    try {
+      picked = await this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}) }).catch(() => undefined);
+    } finally {
+      clearInterval(alive); // also when there is no handler at all
+    }
     const valid = options.some((o) => o.optionId === picked);
     this.send({
       jsonrpc: "2.0",

package/src/adapters/codex-appserver.ts

@@ -1,6 +1,6 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
-import { renderDigest, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
+import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { childEnv, stopOwnedProcess } from "../hub/child-process.ts";
 
@@ -54,6 +54,7 @@ export class CodexPeer extends BasePeer {
   private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void; deliveryId?: string; kind?: "deliver" | "steer" }>();
   private usageTimer: ReturnType<typeof setInterval> | undefined;
   private injected: Envelope | undefined; // the hub envelope that started the current turn, if any
+  private answering: Envelope[] = []; // everything delivered or steered into the current turn: who its answer is for
   private lastAnswer = "";
   private readonly deltas = new Map<string, string[]>();
   private primed = false;
@@ -146,6 +147,7 @@ export class CodexPeer extends BasePeer {
         resolve: (result) => {
           this.primed = true;
           this.injected = replyParent(envs);
+          this.answering = [...envs];
           const nativeTurn = typeof result?.turn?.id === "string" ? result.turn.id : undefined;
           if (deliveryId) {
             if (nativeTurn) this.addTurnDelivery(nativeTurn, deliveryId);
@@ -188,6 +190,7 @@ export class CodexPeer extends BasePeer {
           this.primed = true;
           // The turn now answers these too; the highest hop wins so a steer cannot reset the hop cap.
           this.injected = replyParent(this.injected ? [this.injected, ...envs] : envs);
+          this.answering.push(...envs);
           if (deliveryId) {
             this.addTurnDelivery(expectedTurnId, deliveryId);
             this.delivery({ id: deliveryId, state: "accepted" });
@@ -216,6 +219,7 @@ export class CodexPeer extends BasePeer {
     for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex turn watchdog timeout" });
     this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.injected = undefined;
+    this.answering = [];
     this.lastAnswer = "";
     this.abandonSteers("turn went silent");
     super.onWatchdog();
@@ -297,9 +301,17 @@ export class CodexPeer extends BasePeer {
     for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex TUI detached" });
     for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex TUI detached" });
     this.turnDeliveries.clear(); this.unboundDeliveries.clear();
+    this.forgetTurn();
     this.setState("offline");
   }
 
+  /** Nothing of an interrupted turn may address a later answer: a TUI that comes back starts its own. */
+  private forgetTurn(): void {
+    this.injected = undefined;
+    this.answering = [];
+    this.lastAnswer = "";
+  }
+
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
     if (msg?.id !== undefined && TRACKED.has(msg.method)) link.tracked.set(msg.id, msg.method);
@@ -329,6 +341,7 @@ export class CodexPeer extends BasePeer {
     this.link = link;
     this.threadId = threadId;
     this.activeTurns.clear();
+    this.forgetTurn();
     this.opts.log?.(`[${this.id}] thread ${threadId}`);
     this.setState("idle");
     this.readUsage();
@@ -385,11 +398,13 @@ export class CodexPeer extends BasePeer {
         this.turnDeliveries.delete(nativeTurn);
       }
       const inReplyTo = this.injected;
+      const to = replyAudience(this.answering);
       this.injected = undefined;
+      this.answering = [];
       this.deltas.clear();
-      // ponytail: the reply is addressed to the highest-hop sender only (newEnvelope's default). A digest that
-      // mixed senders answers the last of them; track the audience alongside `injected` if that starts to matter.
-      if (this.lastAnswer) this.onMessage?.(this.lastAnswer, inReplyTo ? { inReplyTo } : {});
+      // Addressed like every other adapter's answer (issue #3): each sender it answers, including one steered in;
+      // the bus maps a condensed delivery's `digest` back to the senders it replaced, a steer beside it or not.
+      if (this.lastAnswer) this.onMessage?.(this.lastAnswer, inReplyTo ? { inReplyTo, to } : {});
       this.lastAnswer = "";
       this.setState("idle");
     }

package/src/cli/main.ts

@@ -404,6 +404,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     else {
       console.log(`ahub setup changes your Claude Code plugin configuration, one step at a time, re-checking after each. First step:\n  ${step.argv.join(" ")}\n      ${step.why}`);
       if (!args.includes("--yes")) {
+        // Nobody can answer without a terminal: waiting would hang a script forever (issue #73).
+        if (!process.stdin.isTTY) fail("not a terminal: nothing was changed; rerun with --yes to apply");
         const rl = createInterface({ input: process.stdin, output: process.stdout });
         const answer = (await rl.question("Proceed (this and the steps that follow from it)? [y/N] ")).trim().toLowerCase();
         rl.close();

package/src/hub/bus.ts

@@ -130,9 +130,12 @@ export class Bus {
       const last = this.lastDelivery.get(peer.id);
       const answers = opts?.inReplyTo?.id !== undefined && last?.out.some((e) => e.id === opts.inReplyTo!.id);
       const originals = answers ? last!.originals : undefined;
+      // `digest` in the audience stands for the condensed delivery even when a steer, not the digest, is the parent.
+      const condensed = !!last?.out.some((e) => e.from === DIGEST);
+      const audienceOriginals = originals ?? (opts?.to?.includes(DIGEST) && condensed ? last?.originals : undefined);
       this.publish(newEnvelope(peer.id, body, {
         ...opts,
-        ...(opts?.to?.length ? { to: resolveTo(opts.to, originals) } : {}),
+        ...(opts?.to?.length ? { to: resolveTo(opts.to, audienceOriginals) } : {}),
         priority: opts?.priority ?? capPriority(peer, priority, opts?.inReplyTo, originals),
       }));
     };
@@ -387,6 +390,11 @@ export class Bus {
     return () => this.taps.delete(fn);
   }
 
+  /** Paused by the console or the budget relay, whatever the adapter's own state. */
+  isPaused(id: PeerId): boolean {
+    return this.paused.has(id);
+  }
+
   /** The adapter's state, or `paused` while the peer is held by `pause()`. */
   stateOf(id: PeerId): PeerState {
     const state = this.peers.get(id)?.state ?? "offline";

package/src/hub/checks.ts

@@ -0,0 +1,91 @@
+import { spawn, spawnSync } from "node:child_process";
+import { childEnv } from "./child-process.ts";
+
+export interface CheckResult {
+  code: number | null;
+  timedOut: boolean;
+  /** Killed because the hub stopped: not a verdict on the work. */
+  interrupted?: boolean;
+  /** The last lines of stdout and stderr together, capped. */
+  tail: string;
+}
+
+const TAIL_LINES = 40;
+const TAIL_CHARS = 4000;
+const KEEP_CHARS = 64 * 1024;
+/** How long output may still arrive after the command exited; a descendant that left the group can hold the pipes. */
+const DRAIN_MS = 500;
+
+/**
+ * Why the completion checks of issue #7 must not run, or undefined when git confirms nobody committed the config.
+ * A command a cloned repository ships would otherwise run on the owner's machine the first time an agent marks a task
+ * done. Unknown is not untracked: no repository, no git, or a git error all refuse. The directory itself counts too (a
+ * committed symlink or submodule at `.agenthub`), and so does any spelling of the path, since macOS opens either.
+ */
+export function checksRefusal(cwd: string): string | undefined {
+  const r = spawnSync("git", ["-C", cwd, "ls-files", "-s", "-z", "--", ":(icase).agenthub"], { encoding: "utf8", env: childEnv(process.env) });
+  if (r.status !== 0) return "git could not confirm that .agenthub/config.json is untracked";
+  const tracked = r.stdout.split("\0").some((row) => {
+    const path = row.slice(row.indexOf("\t") + 1).toLowerCase();
+    return path === ".agenthub" || path === ".agenthub/config.json";
+  });
+  return tracked ? ".agenthub/config.json is committed to git" : undefined;
+}
+
+/** Runs one check command in the project root, in its own process group so a timeout stops what it started. */
+export function runCheck(command: string, cwd: string, timeoutMs: number, running?: Set<() => void>): Promise<CheckResult> {
+  return new Promise((resolve) => {
+    let out = "";
+    let timedOut = false;
+    let interrupted = false;
+    let settled = false;
+    let exited = false;
+    const child = spawn("sh", ["-c", command], { cwd, env: childEnv(process.env), stdio: ["ignore", "pipe", "pipe"], detached: true });
+    const killGroup = () => {
+      try {
+        if (child.pid) process.kill(-child.pid, "SIGKILL");
+      } catch {
+        // already gone
+      }
+    };
+    const stop = () => {
+      if (exited) return; // finished before the hub stopped: its own result stands
+      interrupted = true;
+      killGroup();
+    };
+    running?.add(stop);
+    const keep = (chunk: string) => {
+      out += chunk;
+      if (out.length > KEEP_CHARS) out = out.slice(-KEEP_CHARS);
+    };
+    for (const s of [child.stdout, child.stderr]) {
+      s?.setEncoding("utf8"); // decodes across chunk edges, so Korean output is not cut into U+FFFD
+      s?.on("data", keep);
+    }
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup();
+    }, timeoutMs);
+    const done = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      running?.delete(stop);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      const tail = out.replace(/\s+$/, "").split("\n").slice(-TAIL_LINES).join("\n").slice(-TAIL_CHARS);
+      resolve({ code: timedOut || interrupted ? null : code, timedOut, ...(interrupted ? { interrupted } : {}), tail });
+    };
+    child.on("error", (e) => {
+      out += `\n${e.message}`;
+      done(null);
+    });
+    child.on("exit", (code) => {
+      exited = true;
+      clearTimeout(timer); // it finished in time; only its output may still be on the way
+      killGroup(); // a background job it left behind (sh has no job control, so it is still in the group)
+      setTimeout(() => done(code), DRAIN_MS);
+    });
+    child.on("close", (code) => done(code));
+  });
+}

package/src/hub/daemon.ts

@@ -2,6 +2,9 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { childEnv } from "./child-process.ts";
+import { checksRefusal, runCheck } from "./checks.ts";
 import type { ServerWebSocket } from "bun";
 import { AcpPeer, type PermissionRequest } from "../adapters/acp.ts";
 import { CodexPeer } from "../adapters/codex-appserver.ts";
@@ -16,7 +19,7 @@ import { Capture, skipTools } from "../memory/capture.ts";
 import { DEFAULT_OMNIROUTE, OmniRoute, type OmniRouteConfig } from "../omniroute/client.ts";
 import { Sidecar } from "../switchyard/sidecar.ts";
 import { Briefs } from "../memory/brief.ts";
-import { Board, type TaskClass } from "./board.ts";
+import { Board, CLASSES, type TaskClass } from "./board.ts";
 import { Budget, claudeWindows, codexWindows, DEFAULT_BUDGET, type BudgetConfig } from "./budget.ts";
 import { HUB } from "./envelope.ts";
 import { trimToTokens } from "../memory/recall.ts";
@@ -53,6 +56,12 @@ export interface HubConfig {
   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[] };
+  /** 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). */
+  tasks: { release_after_min: number };
+  /** A command per task class run when the owner marks the task done, and its timeout (issue #7). */
+  checks: { timeout_s: number; [cls: string]: string | number };
 }
 export const DEFAULT_CONFIG: HubConfig = {
   watchdog_ms: DEFAULT_WATCHDOG_MS,
@@ -69,6 +78,10 @@ export const DEFAULT_CONFIG: HubConfig = {
   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: [] },
+  // 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 },
+  checks: { timeout_s: 600 },
 };
 
 export { stateDirFor };
@@ -98,6 +111,12 @@ export function loadConfig(cwd: string): HubConfig {
       omniroute: { ...DEFAULT_CONFIG.omniroute, ...file.omniroute },
       local: { ...DEFAULT_CONFIG.local, ...file.local },
       pi: { ...DEFAULT_CONFIG.pi, ...file.pi },
+      approvals: {
+        timeout_s: file.approvals?.timeout_s ?? DEFAULT_CONFIG.approvals.timeout_s,
+        notify: typeof file.approvals?.notify === "boolean" ? file.approvals.notify : process.platform === "darwin",
+      },
+      tasks: { ...DEFAULT_CONFIG.tasks, ...file.tasks },
+      checks: { ...DEFAULT_CONFIG.checks, ...file.checks },
       mlx,
     };
   } catch (error) {
@@ -121,6 +140,8 @@ export interface DaemonOptions {
   /** Auto-approve ACP permission requests with the agent's allow_once option. */
   unattended?: boolean;
   permissionTimeoutMs?: number;
+  /** Tests replace the desktop notifier; the default posts a macOS notification when approvals.notify is on. */
+  notifier?: (title: string, body: string) => void;
   /** Called once when shutdown begins, however it was triggered; the lifecycle uses it to arm a hard deadline. */
   onShutdownStart?: () => void;
   /** How often the daemon checks that its project root and state dir still exist. Tests shrink this. */
@@ -301,6 +322,17 @@ export async function startDaemon(opts: DaemonOptions) {
   };
   const board = new Board(join(opts.stateDir, "hub.db"));
   startupCleanup.push(() => board.close());
+  // Completion checks (issue #7): only from a config file git does not track, one at a time, killed on stop.
+  const checkCommands = Object.fromEntries(Object.entries(config.checks).filter(([k, v]) => (CLASSES as readonly string[]).includes(k) && typeof v === "string" && v.trim())) as Record<string, string>;
+  const strayChecks = Object.keys(config.checks).filter((k) => k !== "timeout_s" && !(k in checkCommands));
+  if (strayChecks.length) log(`checks ignored for ${strayChecks.join(", ")}: not a task class with a command (classes: ${CLASSES.join(", ")})`);
+  const checksRefused = Object.keys(checkCommands).length ? checksRefusal(opts.cwd) : undefined;
+  if (checksRefused) log(`checks ignored: ${checksRefused}, and only a file nobody committed may choose commands the hub runs`);
+  const checksAllowed = Object.keys(checkCommands).length > 0 && !checksRefused;
+  const checkTimeoutS = typeof config.checks.timeout_s === "number" && config.checks.timeout_s >= 1 ? Math.min(config.checks.timeout_s, 3600) : 600;
+  const runningChecks = new Set<() => void>();
+  let checksClosed = false; // set on stop: a check still queued then must not start and outlive the hub
+  const interrupted = { code: null, timedOut: false, interrupted: true, tail: "" };
   const tasks = new Tasks({
     board,
     bus,
@@ -309,6 +341,7 @@ export async function startDaemon(opts: DaemonOptions) {
     project: chain.at(-1)!,
     ...(config.memory.enabled ? { memory, briefs: new Briefs(memory, chain.at(-1)!, config.memory.brief_items) } : {}),
     notify,
+    ...(checksAllowed ? { check: (cls: string) => checkCommands[cls], runCheck: async (command: string) => (checksClosed ? interrupted : runCheck(command, opts.cwd, checkTimeoutS * 1000, runningChecks)) } : {}),
     // What a peer learned reaches the peers working now, on their next delivery, instead of at their next session (#68).
     // Fail-open: the note is already saved, so a bus that cannot persist costs the sharing, not the tool call.
     share: (by, line) => {
@@ -318,6 +351,13 @@ export async function startDaemon(opts: DaemonOptions) {
         log(`note from ${by} not shared: ${(e as Error).message}`);
       }
     },
+    tell: (peer, line) => {
+      try {
+        bus.note(peer, line);
+      } catch (e) {
+        log(`note for ${peer} not kept: ${(e as Error).message}`);
+      }
+    },
     triage: { classify: (title, detail) => inference?.triage(title, detail) ?? Promise.resolve(undefined), onCampus: () => onCampus() },
   });
   // ---- budget relay -------------------------------------------------------------------------------------------
@@ -409,6 +449,10 @@ export async function startDaemon(opts: DaemonOptions) {
     return { ...e, env: { ...env, ...(task ? { refs: { task } } : {}), body: `[private${task ? `: task #${task}, see ahub task show ${task}` : ""}]` } };
   };
   const SERVER_JS = join(import.meta.dir, "..", "..", "plugins", "agent-hub", "server.js");
+  // What the hub's MCP server offers a native peer. Codex approves them in config, Kimi's requests for exactly these
+  // names are answered by the hub: no file or process is touched, and every call passes the hub's own checks.
+  const HUB_TOOLS = ["hub_send", ...TASK_TOOLS.map((t) => t.name)];
+  const HUB_TOOL_TITLES = new Set(HUB_TOOLS.map((name) => `mcp__agent-hub__${name}`));
   const toolEnv = (peer: PeerId) => ({ AGENTHUB_MODE: "tools", AGENTHUB_PEER_ID: peer, AGENTHUB_STATE_DIR: opts.stateDir, AGENTHUB_PROJECT_DIR: opts.cwd });
 
   /** One entry point for the task tools, whoever calls them: MCP clients, the local worker, the console. */
@@ -431,8 +475,10 @@ export async function startDaemon(opts: DaemonOptions) {
         return line(tasks.accept(by, a.id));
       case "hub_task_decline":
         return line(await tasks.decline(by, a.id, a.reason));
-      case "hub_task_done":
-        return line(await tasks.done(by, a.id, a.summary, a.refs));
+      case "hub_task_done": {
+        const t = await tasks.done(by, a.id, a.summary, a.refs);
+        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));
       case "hub_remember":
@@ -477,8 +523,9 @@ export async function startDaemon(opts: DaemonOptions) {
     const r = budget.record(id); // one read per peer: status.json is rewritten on every bus event
     return r ? { paused: `budget: ${r.reason}, resets ${new Date(r.resetsAt).toLocaleTimeString()}` } : manualPaused.has(id) && bus.stateOf(id) === "offline" ? { paused: "manual" } : {};
   };
+  let releasing = false; // gone-owner release (#6): one run at a time, and a recovery commit waits for it
   const recoveryReady = () => {
-    if (!recoveryActive() || (piReceipts?.inFlight ?? 0) !== 0 || permissions.size !== 0 || starting.size !== 0 || !budget.recoverySettled || [...bus.peers.values()].some((peer) => peer.state === "busy" || (peer instanceof PiPeer && !peer.recoveryReady))) return false;
+    if (!recoveryActive() || releasing || (piReceipts?.inFlight ?? 0) !== 0 || permissions.size !== 0 || starting.size !== 0 || !budget.recoverySettled || [...bus.peers.values()].some((peer) => peer.state === "busy" || (peer instanceof PiPeer && !peer.recoveryReady))) return false;
     if (!recoveryPeerSnapshot) return true;
     const current = recoveryPeers();
     return recoveryPeerSnapshot.every((saved) => {
@@ -573,17 +620,70 @@ export async function startDaemon(opts: DaemonOptions) {
   // message and keeps a phantom `queued N` after the queue drains (measured on a live 0.6.3 hub).
   bus.onQueues = () => { if (!stopping) writeStatus(); };
 
+  // When each peer went offline; a peer never seen attached counts from hub start (issue #6).
+  const offlineSince = new Map<PeerId, number>();
+  const hubStartedAt = Date.now();
+  const releaseGoneOwners = async () => {
+    const limit = config.tasks.release_after_min;
+    if (!(limit > 0) || releasing || stopping || recoveryActive()) return;
+    releasing = true;
+    try {
+      await releaseOwners(limit);
+    } finally {
+      releasing = false;
+    }
+  };
+  const releaseOwners = async (limit: number) => {
+    const owners = new Set(board.list().filter((t) => t.owner && ["proposed", "in_progress", "changes_requested"].includes(t.state)).map((t) => t.owner!));
+    for (const owner of owners) {
+      if (stopping || recoveryActive()) return;
+      if (owner === USER || owner === "hub" || bus.isPaused(owner) || bus.stateOf(owner) !== "offline") continue;
+      const since = offlineSince.get(owner) ?? hubStartedAt;
+      if (Date.now() - since < limit * 60_000) continue;
+      const moved = await tasks.releaseFromGone(owner, Math.round((Date.now() - since) / 60_000)).catch((e) => (log(`releasing tasks of ${owner} failed: ${(e as Error).message}`), []));
+      for (const m of moved) notify(`task ${m.title} moved from ${owner} (offline) to ${m.to ?? "nobody"}`);
+    }
+  };
+  const releaseTimer = setInterval(() => void releaseGoneOwners(), 60_000);
+  releaseTimer.unref?.();
+  intervals.push(releaseTimer);
+
   bus.tap((e) => {
     e = redact(e);
     uiEvents.push({ seq: ++uiSequence, event: e });
     if (uiEvents.length > 200) uiEvents.shift();
-    if (e.t === "state") log(`state ${e.peer} -> ${e.state}`);
+    if (e.t === "state") {
+      log(`state ${e.peer} -> ${e.state}`);
+      if (e.state === "offline") offlineSince.set(e.peer, offlineSince.get(e.peer) ?? Date.now());
+      else offlineSince.delete(e.peer);
+    }
     else if (e.t === "undeliverable") log(`UNDELIVERABLE to ${e.peer} after retries: ${e.env.id} from ${e.env.from}`);
     else if (e.t === "overflow") log(`OVERFLOW ${e.peer}: dropped ${e.env.id} from ${e.env.from}`);
     else log(`msg ${e.env.from} -> ${e.env.to?.join(",") ?? "*"} ${e.env.priority} hop=${e.env.hop}${e.dropped ? ` NOT DELIVERED(${e.dropped})` : ""}: ${e.env.body.slice(0, 200)}`);
     if (!stopping) writeStatus();
   });
 
+  const approvalTimeoutS = (() => {
+    const s = config.approvals.timeout_s;
+    if (typeof s === "number" && s >= 30 && s <= 3600) return s;
+    log(`approvals.timeout_s ${JSON.stringify(s)} is outside 30-3600 seconds; using 120`);
+    return 120;
+  })();
+  let notifierBroken = false;
+  // Peer and tool name only: a title can quote what a PII turn is about to write (issue #5).
+  const desktop = opts.notifier ?? ((title: string, body: string) => {
+    const quote = (t: string) => `"${t.replace(/[\\"]/g, "\\$&")}"`;
+    const child = spawn("osascript", ["-e", `display notification ${quote(body)} with title ${quote(title)}`], { stdio: "ignore", env: childEnv(process.env) });
+    const kill = setTimeout(() => child.kill(), 5000);
+    kill.unref?.();
+    const failed = (why: string) => {
+      if (!notifierBroken) log(`desktop notification failed (${why}); later ones are not reported`);
+      notifierBroken = true;
+    };
+    child.on("error", (e: Error) => (clearTimeout(kill), failed(e.message)));
+    child.on("exit", (code: number | null, signal: string | null) => (clearTimeout(kill), code || signal ? failed(signal ? `osascript stopped by ${signal}` : `osascript exit ${code}`) : undefined));
+  });
+
   async function onPermission(req: PermissionRequest): Promise<string | undefined> {
     if (stopping) return undefined;
     if (opts.unattended) return req.options.find((o) => o.kind === "allow_once")?.optionId;
@@ -593,11 +693,24 @@ export async function startDaemon(opts: DaemonOptions) {
     const title = req.title.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
     // The title can quote what a PII turn is about to write. It is for the person approving, on the console; the log
     // (which `ahub ask` reads as evidence) only records that a request was made.
-    log(`permission ${id} requested by ${req.peer} (${title.length} chars, shown on the console)`);
-    const push = JSON.stringify({ t: "permission", id, ...req, title });
+    const timeoutMs = opts.permissionTimeoutMs ?? approvalTimeoutS * 1000;
+    log(`permission ${id} requested by ${req.peer} (${title.length} chars, shown on the console; cancelled after ${timeoutMs / 1000}s)`);
+    // The tool name is for the desktop notice only: the console push keeps its shape.
+    const { tool: _tool, ...shown } = req;
+    const push = JSON.stringify({ t: "permission", id, ...shown, title });
     for (const c of consoles) if (c.data.tail) c.send(push);
+    if (config.approvals.notify) {
+      try {
+        desktop("agent-hub", `${req.peer} asks for approval${req.tool ? `: ${req.tool}` : ""} (ahub tail)`);
+      } catch {
+        // never let a notifier break the request itself
+      }
+    }
     return new Promise((resolve) => {
-      const timer = setTimeout(() => done(undefined), opts.permissionTimeoutMs ?? 120_000);
+      const timer = setTimeout(() => {
+        notify(`permission ${id} from ${req.peer} was not answered within ${Math.round(timeoutMs / 1000)}s and was cancelled`);
+        done(undefined);
+      }, timeoutMs);
       const done = (optionId: string | undefined) => {
         clearTimeout(timer);
         permissions.delete(id);
@@ -691,6 +804,10 @@ export async function startDaemon(opts: DaemonOptions) {
         cwd: opts.cwd,
         watchdogMs: config.watchdog_ms,
         onPermission,
+        // The hub's own tools pass without a console prompt, as Codex's do (approval_mode below; issue #72). This
+        // relies on the agent putting the tool name in `title`, as Kimi does; an ACP agent that titles calls with
+        // model-written text must not be configured as kimi_cmd. A stopping hub approves nothing.
+        autoApprove: (title) => !stopping && HUB_TOOL_TITLES.has(title),
         log,
         onTokens: onKimiTokens,
         mcpServers: [{ name: "agent-hub", command: "bun", args: ["run", SERVER_JS], env: Object.entries(toolEnv("kimi")).map(([name, value]) => ({ name, value })) }],
@@ -713,7 +830,7 @@ export async function startDaemon(opts: DaemonOptions) {
           ["command", '"bun"'],
           ["args", JSON.stringify(["run", SERVER_JS])],
           ["env", `{${Object.entries(toolEnv("codex")).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(", ")}}`],
-          ...["hub_send", ...TASK_TOOLS.map((t) => t.name)].map((name) => [`tools.${name}.approval_mode`, '"approve"']),
+          ...HUB_TOOLS.map((name) => [`tools.${name}.approval_mode`, '"approve"']),
         ].flatMap(([k, v]) => ["-c", `mcp_servers.agent-hub.${k}=${v}`]),
         preamble: roleContract("codex", config.roles),
         onUsage: (rateLimits, hard) => budget.report("codex", codexWindows(rateLimits), hard),
@@ -1270,6 +1387,8 @@ export async function startDaemon(opts: DaemonOptions) {
   }
   async function stopOnce(): Promise<void> {
     stopping = true;
+    checksClosed = true;
+    for (const kill of runningChecks) kill();
     log("hub stopping");
     writeStatus();
     dashboard?.stop();