@staix/agent-hub 0.7.7 → 0.7.9

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/init.ts

@@ -59,7 +59,11 @@ export function init(cwd: string): string[] {
   }
 
   const ignore = join(cwd, ".gitignore");
-  const lines = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
-  if (!lines.split("\n").includes(".agenthub/state/")) write(ignore, `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}.agenthub/state/\n`);
+  let lines = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+  // The machine's own config: only a file nobody committed may choose commands and credential files (issue #17).
+  for (const entry of [".agenthub/state/", ".agenthub/config.local.json"]) {
+    if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
+  }
+  write(ignore, lines);
   return changed;
 }

package/src/cli/main.ts

@@ -96,6 +96,12 @@ try {
   } else selected = projectContext(process.cwd());
 } catch (error) { fail((error as Error).message); }
 const cwd = selected.root;
+/** The project config, saying on stderr which machine-local fields it had to ignore (issue #17). */
+const projectConfig = () => {
+  const config = loadConfig(cwd);
+  for (const line of config.ignored ?? []) console.error(`note: ${line}; only a config file nobody committed may set it`);
+  return config;
+};
 const stateDir = selected.stateDir;
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
@@ -472,7 +478,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (!res.ok) fail(res.error);
     const control = readControl(stateDir);
     if (control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
-    const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: loadConfig(cwd).codex_bin });
+    const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
     if (launch0.warning) console.error(launch0.warning);
     exec(launch.cmd, launch.args);
   },
@@ -517,7 +523,7 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   models: async () => {
     const action = args[0] ?? "status";
-    const configured = loadConfig(cwd).mlx;
+    const configured = projectConfig().mlx;
     const runtimeDir = configured.runtimeDir ? resolve(cwd, configured.runtimeDir) : join(homedir(), ".agenthub", "runtimes", "mlx");
     const modelPath = configured.modelPath ? resolve(cwd, configured.modelPath) : join(homedir(), ".agenthub", "models", "qwen3-8b-mlx");
     const mlxOptions = configured.provider === "ollama" ? configured : { ...configured, runtimeDir, modelPath };
@@ -757,13 +763,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     row(plugin.state === "current", "claude plugin", plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
 
     const config = loadConfig(cwd);
+    row(!config.ignored, "config", config.ignored ? `${config.ignored.join("; ")} (move them to .agenthub/config.local.json)` : "no machine-local field ignored");
     const omni = new OmniRoute(config.omniroute);
     const gateway = await omni.base();
-    row(!!gateway, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.json (any OpenAI-compatible gateway); ahub local cannot run");
-    row(!!omni.apiKey(), "omniroute key", omni.apiKey() ? "present" : "missing: set OMNIROUTE_API_KEY or omniroute.api_key_file in .agenthub/config.json");
+    row(!!gateway, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.local.json (any OpenAI-compatible gateway); ahub local cannot run");
+    row(!!omni.apiKey(), "omniroute key", omni.apiKey() ? "present" : "missing: set OMNIROUTE_API_KEY or omniroute.api_key_file in .agenthub/config.local.json");
     const sy = spawnSync(process.env.AGENTHUB_SWITCHYARD_BIN ?? "switchyard-server", ["--version"], { encoding: "utf8" });
     row(sy.status === 0 ? true : undefined, "switchyard", sy.status === 0 ? sy.stdout.trim() : "not installed: ahub local uses fixed_model on OmniRoute (cargo install --locked switchyard-server)");
-    const mlxConfig = loadConfig(cwd).mlx;
+    const mlxConfig = config.mlx;
     const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
     row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
 

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,75 @@
+import { spawn } 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;
+
+/** 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/config-trust.ts

@@ -0,0 +1,84 @@
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { childEnv } from "./child-process.ts";
+
+/**
+ * Fields of the project config that choose what the hub runs, which files it sends as credentials, where task text
+ * goes, or how far the local worker's sandbox reaches (issue #17). Only a file git confirms nobody committed may set
+ * them; a cloned repository would otherwise choose them for the owner's machine.
+ */
+export const MACHINE_LOCAL = [
+  "kimi_cmd",
+  "codex_bin",
+  "pi.cmd",
+  "checks",
+  "mlx.bin",
+  "mlx.runtimeDir",
+  "mlx.modelPath", // the legacy runtime runs code a model directory names (mlx-lm's model_file)
+  "omniroute.urls",
+  "omniroute.access_hosts",
+  "omniroute.api_key_file",
+  "omniroute.cf_client_id_file",
+  "omniroute.cf_client_secret_file",
+  "memory.worker_url",
+  "local.read_allow",
+  "local.bash_network",
+] as const;
+
+/**
+ * Why `.agenthub/<name>` must not set machine-local fields, or undefined when git confirms nobody committed it.
+ * 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`). A tracked file is matched by identity, not by name: macOS opens
+ * spellings git keeps apart (letter case, and folds such as "ſ" for "s").
+ */
+export function configRefusal(cwd: string, name: 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/${name} is untracked`;
+  let opened: { dev: number; ino: number } | undefined;
+  try {
+    opened = statSync(join(cwd, ".agenthub", name));
+  } catch {
+    // not there: only the directory entry can still matter
+  }
+  const tracked = r.stdout.split("\0").filter(Boolean).some((row) => {
+    const path = row.slice(row.indexOf("\t") + 1);
+    if (path.toLowerCase() === ".agenthub") return true;
+    try {
+      const s = statSync(join(cwd, path));
+      return !!opened && s.dev === opened.dev && s.ino === opened.ino;
+    } catch {
+      return false;
+    }
+  });
+  return tracked ? `.agenthub/${name} is committed to git` : undefined;
+}
+
+const valueAt = (o: unknown, path: string): unknown => path.split(".").reduce<unknown>((v, k) => (v && typeof v === "object" ? (v as Record<string, unknown>)[k] : undefined), o);
+/** An empty value chooses nothing (the template writes `""` for the key files), so it is never reported. */
+const chooses = (v: unknown) => v !== undefined && v !== null && v !== "" && !(Array.isArray(v) && v.length === 0);
+
+const drop = (file: Record<string, unknown>, path: string) => {
+  const [head, key] = path.split(".") as [string, string?];
+  const block = file[head];
+  if (!key) delete file[head];
+  else if (block && typeof block === "object") delete (block as Record<string, unknown>)[key];
+};
+
+/**
+ * Drops the machine-local fields `file` sets to anything but the default unless git vouches for it, and says which
+ * went and why. An empty value always goes, trusted or not: it means the default, never "here" (an empty runtimeDir
+ * once resolved to the project root). A committed copy of the template sets them to defaults and asks git nothing.
+ */
+export function stripUntrusted(file: Record<string, unknown>, defaults: object, cwd: string, name: string): string | undefined {
+  for (const p of MACHINE_LOCAL) if (valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
+  const set = MACHINE_LOCAL.filter((p) => {
+    const v = valueAt(file, p);
+    return v !== undefined && JSON.stringify(v) !== JSON.stringify(valueAt(defaults, p));
+  });
+  if (!set.length) return undefined;
+  const why = configRefusal(cwd, name);
+  if (!why) return undefined;
+  for (const p of set) drop(file, p);
+  return `${set.join(", ")} in .agenthub/${name} ignored: ${why}`;
+}

package/src/hub/daemon.ts

@@ -2,6 +2,10 @@ 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 { runCheck } from "./checks.ts";
+import { stripUntrusted } from "./config-trust.ts";
 import type { ServerWebSocket } from "bun";
 import { AcpPeer, type PermissionRequest } from "../adapters/acp.ts";
 import { CodexPeer } from "../adapters/codex-appserver.ts";
@@ -16,7 +20,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 +57,14 @@ 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 };
+  /** Machine-local fields a config file set but git could not vouch for, and why (issue #17). */
+  ignored?: string[];
 }
 export const DEFAULT_CONFIG: HubConfig = {
   watchdog_ms: DEFAULT_WATCHDOG_MS,
@@ -69,6 +81,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 };
@@ -77,33 +93,54 @@ export { stateDirFor };
 const RESERVED_IDS = new Set([USER, "codex", "kimi", "local", "pi", "hub", DIGEST]);
 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", "mlx"];
+
 export function loadConfig(cwd: string): HubConfig {
-  try {
-    const file = JSON.parse(readFileSync(join(cwd, ".agenthub", "config.json"), "utf8"));
-    if (file.mlx != null && (typeof file.mlx !== "object" || Array.isArray(file.mlx))) throw new Error("mlx configuration must be an object");
-    if (file.mlx?.provider !== undefined && !["ollama", "legacy"].includes(file.mlx.provider)) throw new Error("mlx.provider must be ollama or legacy");
-    if (file.mlx?.provider === undefined && (file.mlx?.modelPath || file.mlx?.runtimeDir || file.mlx?.bin || file.mlx?.port)) {
-      throw new Error("legacy MLX configuration requires explicit mlx.provider=legacy; migrate to provider=ollama to avoid Python serving");
+  const ignored: string[] = [];
+  const files = CONFIG_FILES.flatMap((name) => {
+    let file: Record<string, any>; // parsed JSON, checked field by field below
+    try {
+      file = JSON.parse(readFileSync(join(cwd, ".agenthub", name), "utf8"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
     }
-    const mlx = { ...(file.mlx?.provider === "legacy" ? { provider: "legacy" as const, maxInputTokens: 16_000, maxTokens: 2048 } : DEFAULT_CONFIG.mlx), ...file.mlx };
-    if (typeof mlx.runtimeDir === "string") mlx.runtimeDir = resolve(cwd, mlx.runtimeDir);
-    if (typeof mlx.modelPath === "string") mlx.modelPath = resolve(cwd, mlx.modelPath);
-    return {
-      ...DEFAULT_CONFIG,
-      ...file,
-      memory: { ...DEFAULT_CONFIG.memory, ...file.memory },
-      roles: { ...DEFAULT_CONFIG.roles, ...file.roles },
-      budget: { ...DEFAULT_CONFIG.budget, ...file.budget },
-      inference: { ...DEFAULT_CONFIG.inference, ...file.inference },
-      omniroute: { ...DEFAULT_CONFIG.omniroute, ...file.omniroute },
-      local: { ...DEFAULT_CONFIG.local, ...file.local },
-      pi: { ...DEFAULT_CONFIG.pi, ...file.pi },
-      mlx,
-    };
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return DEFAULT_CONFIG;
-    throw error;
+    const why = stripUntrusted(file, DEFAULT_CONFIG, cwd, name);
+    if (why) ignored.push(why);
+    return [file];
+  });
+  if (!files.length) return DEFAULT_CONFIG;
+  const file = files.reduce((a, b) => ({ ...a, ...b, ...Object.fromEntries(CONFIG_BLOCKS.filter((k) => a[k] !== undefined && b[k] !== undefined).map((k) => [k, { ...a[k], ...b[k] }])) }));
+  delete file.ignored; // the hub's own record, never a file's
+  if (file.mlx != null && (typeof file.mlx !== "object" || Array.isArray(file.mlx))) throw new Error("mlx configuration must be an object");
+  if (file.mlx?.provider !== undefined && !["ollama", "legacy"].includes(file.mlx.provider)) throw new Error("mlx.provider must be ollama or legacy");
+  if (file.mlx?.provider === undefined && (file.mlx?.modelPath || file.mlx?.runtimeDir || file.mlx?.bin || file.mlx?.port)) {
+    throw new Error("legacy MLX configuration requires explicit mlx.provider=legacy; migrate to provider=ollama to avoid Python serving");
   }
+  const mlx = { ...(file.mlx?.provider === "legacy" ? { provider: "legacy" as const, maxInputTokens: 16_000, maxTokens: 2048 } : DEFAULT_CONFIG.mlx), ...file.mlx };
+  if (typeof mlx.runtimeDir === "string" && mlx.runtimeDir) mlx.runtimeDir = resolve(cwd, mlx.runtimeDir);
+  if (typeof mlx.modelPath === "string" && mlx.modelPath) mlx.modelPath = resolve(cwd, mlx.modelPath);
+  return {
+    ...DEFAULT_CONFIG,
+    ...file,
+    memory: { ...DEFAULT_CONFIG.memory, ...file.memory },
+    roles: { ...DEFAULT_CONFIG.roles, ...file.roles },
+    budget: { ...DEFAULT_CONFIG.budget, ...file.budget },
+    inference: { ...DEFAULT_CONFIG.inference, ...file.inference },
+    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,
+    ...(ignored.length ? { ignored } : {}),
+  };
 }
 
 export interface DaemonOptions {
@@ -121,6 +158,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 +340,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(", ")})`);
+  // Commands and the other machine-local fields came only from a file git vouched for (loadConfig, issue #17).
+  for (const line of config.ignored ?? []) log(`${line}; only a config file nobody committed may set it`);
+  const checksAllowed = Object.keys(checkCommands).length > 0;
+  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 +359,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 +369,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 -------------------------------------------------------------------------------------------
@@ -435,8 +493,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":
@@ -481,8 +541,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) => {
@@ -577,17 +638,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;
@@ -597,11 +711,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);
@@ -1278,6 +1405,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();