@staix/agent-hub 0.12.20 → 0.12.22

package/src/hub/bench.ts

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hubHome } from "./project.ts";
+import { processLiveness } from "../pi/process-signature.ts";
+
+/**
+ * #251: benchmark suites, runs and their comparison. A run's records hold ids, outcomes, exit codes, counts, tokens
+ * and times, never the suite's text, a command's output or anything an agent wrote.
+ */
+export const BENCH_SCHEMA = "agent-hub.bench/v1";
+
+export interface SuiteTask { id: string; title: string; detail?: string; class?: string; owner?: string; ref: string; setup?: string; verify: string; timeout_s: number }
+export interface Suite { name: string; tasks: SuiteTask[] }
+
+const TASK_FIELDS = new Set(["id", "title", "detail", "class", "owner", "ref", "setup", "verify", "timeout_s"]);
+const CLASSES = new Set(["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"]);
+/** A suite file, checked field by field; every refusal names the task and the field. */
+export function parseSuite(text: string): Suite {
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new Error("suite: not valid JSON"); }
+  const suite = raw as Record<string, unknown>;
+  if (!suite || typeof suite !== "object" || Array.isArray(suite)) throw new Error("suite: expected an object with name and tasks");
+  for (const key of Object.keys(suite)) if (key !== "name" && key !== "tasks") throw new Error(`suite: unknown field ${key}`);
+  if (typeof suite.name !== "string" || !suite.name.trim()) throw new Error("suite: name is required");
+  if (!Array.isArray(suite.tasks) || !suite.tasks.length) throw new Error("suite: tasks must be a non-empty list");
+  const ids = new Set<string>();
+  const tasks = suite.tasks.map((item, i): SuiteTask => {
+    const t = item as Record<string, unknown>;
+    const where = `suite task ${typeof t?.id === "string" ? t.id : `#${i + 1}`}`;
+    if (!t || typeof t !== "object" || Array.isArray(t)) throw new Error(`${where}: expected an object`);
+    for (const key of Object.keys(t)) if (!TASK_FIELDS.has(key)) throw new Error(`${where}: unknown field ${key}`);
+    for (const key of ["id", "title", "ref", "verify"]) if (typeof t[key] !== "string" || !(t[key] as string).trim()) throw new Error(`${where}: ${key} is required`);
+    for (const key of ["detail", "class", "owner", "setup"]) if (t[key] !== undefined && typeof t[key] !== "string") throw new Error(`${where}: ${key} must be text`);
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(t.id as string)) throw new Error(`${where}: id may hold letters, digits, dot, dash and underscore`);
+    if (ids.has(t.id as string)) throw new Error(`${where}: duplicate id`);
+    ids.add(t.id as string);
+    if (t.class !== undefined && !CLASSES.has(t.class as string)) throw new Error(`${where}: class must be one of ${[...CLASSES].join(", ")}`);
+    if (typeof t.timeout_s !== "number" || !Number.isFinite(t.timeout_s) || t.timeout_s < 10 || t.timeout_s > 86_400) throw new Error(`${where}: timeout_s must be a number of seconds from 10 to 86400`);
+    return t as unknown as SuiteTask;
+  });
+  return { name: suite.name, tasks };
+}
+export const suiteHash = (text: string): string => createHash("sha256").update(text).digest("hex");
+
+export interface Fingerprint { peers: { id: string; model?: string; permissionMode?: string }[]; routingHash: string | null; hubVersion: string }
+export interface RunHeader {
+  schema: typeof BENCH_SCHEMA; kind: "run"; run: string; suite: string; suiteHash: string; arm: string; fingerprint: Fingerprint;
+  version: string; startedAt: string; tasks: number; repeats: number; runner: { pid: number; signature: string | null };
+  /** Task ids in run order, so a running run can name the attempt in progress. */
+  order: string[];
+}
+export type Outcome = "pass" | "fail" | "timeout" | "error";
+/** Closed list: a reason never quotes a command or its output. */
+export type AttemptError = "setup failed" | "setup timeout" | "propose refused" | "hub stopped" | "verify timeout" | "reset failed" | "interrupted";
+export interface AttemptMetrics {
+  tokens: number; wallMs: number | null; activeMs: number; reviewRounds: number; changesRequested: number; checkFailed: number;
+  firstPass: boolean; turns: number; filesChanged: number; models: string[];
+}
+export interface Attempt {
+  schema: typeof BENCH_SCHEMA; kind: "attempt"; run: string; task: string; repeat: number; outcome: Outcome; error?: AttemptError;
+  verifyExit: number | null; hubTask: number | null; startedAt: string; endedAt: string; ms: number; metrics: AttemptMetrics | null;
+}
+export interface RunEnd { schema: typeof BENCH_SCHEMA; kind: "end"; run: string; endedAt: string; stopped?: "timeout" | "interrupted" | "error" }
+export type BenchRecord = RunHeader | Attempt | RunEnd;
+export interface BenchRun { header: RunHeader; attempts: Attempt[]; end?: RunEnd; state: "running" | "finished" | "stopped" | "interrupted" | "unknown" }
+
+export const benchDir = (home = hubHome()): string => join(home, "bench");
+export const runFile = (run: string, home = hubHome()): string => join(benchDir(home), `${run}.jsonl`);
+export function appendBench(record: BenchRecord, home = hubHome()): void {
+  mkdirSync(benchDir(home), { recursive: true, mode: 0o700 });
+  chmodSync(benchDir(home), 0o700); // mkdir's mode applies only when it creates the directory
+  const file = runFile(record.run, home);
+  appendFileSync(file, JSON.stringify(record) + "\n", { mode: 0o600 });
+  chmodSync(file, 0o600);
+}
+
+/** Every run on this machine, newest first. A run with no end record is running while its runner lives. */
+export function readRuns(home = hubHome()): BenchRun[] {
+  const dir = benchDir(home);
+  if (!existsSync(dir)) return [];
+  const runs: BenchRun[] = [];
+  for (const name of readdirSync(dir).filter((n) => n.endsWith(".jsonl"))) try {
+    let header: RunHeader | undefined, end: RunEnd | undefined;
+    const attempts: Attempt[] = [];
+    for (const line of readFileSync(join(dir, name), "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      let r: BenchRecord;
+      try { r = JSON.parse(line); } catch { continue; }
+      if (r?.schema !== BENCH_SCHEMA) continue;
+      if (r.kind === "run") header = r; else if (r.kind === "attempt") attempts.push(r); else if (r.kind === "end") end = r;
+    }
+    if (!header || typeof header.startedAt !== "string" || !header.runner) continue;
+    const owner = end ? undefined : processLiveness(header.runner.pid, header.runner.signature);
+    const state = end ? (end.stopped ? "stopped" : "finished") : owner === "live" ? "running" : owner === "gone" ? "interrupted" : "unknown";
+    runs.push({ header, attempts, ...(end ? { end } : {}), state });
+  } catch { /* a file that cannot be read or has no valid header is not a run; the others still are */ }
+  return runs.sort((a, b) => b.header.startedAt.localeCompare(a.header.startedAt));
+}
+
+const median = (values: number[]): number | null => {
+  if (!values.length) return null;
+  const s = [...values].sort((a, b) => a - b), m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+};
+export interface Measures {
+  attempts: number; pass: number; fail: number; timeout: number; error: number;
+  /** What the measures are computed over: attempts that did not end in an error; attempts that have #247 measures. */
+  scored: number; measured: number;
+  passRate: number | null; firstPassRate: number | null; tokensMedian: number | null; wallMsMedian: number | null; reworkMean: number | null;
+}
+export function measures(attempts: Attempt[]): Measures {
+  const count = (o: Outcome) => attempts.filter((a) => a.outcome === o).length;
+  const scored = attempts.filter((a) => a.outcome !== "error");
+  const withMetrics = attempts.flatMap((a) => a.metrics ? [a.metrics] : []);
+  return { attempts: attempts.length, pass: count("pass"), fail: count("fail"), timeout: count("timeout"), error: count("error"), scored: scored.length, measured: withMetrics.length,
+    passRate: scored.length ? count("pass") / scored.length : null,
+    firstPassRate: withMetrics.length ? withMetrics.filter((m) => m.firstPass).length / withMetrics.length : null,
+    tokensMedian: median(withMetrics.map((m) => m.tokens)), wallMsMedian: median(scored.map((a) => a.ms)),
+    reworkMean: withMetrics.length ? withMetrics.reduce((n, m) => n + m.changesRequested, 0) / withMetrics.length : null };
+}
+export interface RunSummary extends Measures { run: string; suite: string; arm: string; state: BenchRun["state"]; startedAt: string; done: number; total: number; current?: string }
+export function runSummary(r: BenchRun): RunSummary {
+  const total = r.header.tasks * r.header.repeats;
+  const current = r.state === "running" && r.attempts.length < total ? r.header.order?.[r.attempts.length % r.header.order.length] : undefined;
+  return { run: r.header.run, suite: r.header.suite, arm: r.header.arm, state: r.state, startedAt: r.header.startedAt, done: r.attempts.length, total, ...(current ? { current } : {}), ...measures(r.attempts) };
+}
+/** Per task and overall for one run (or several runs of one arm). */
+export function benchReport(runs: BenchRun[]): { overall: Measures; tasks: Record<string, Measures> } {
+  const attempts = runs.flatMap((r) => r.attempts);
+  // A Map: a task id may be `constructor` or `__proto__`, which a plain object answers with an inherited value.
+  const tasks = new Map<string, Attempt[]>();
+  for (const a of attempts) { const id = String(a.task); tasks.set(id, [...(tasks.get(id) ?? []), a]); } // a store line is not trusted to hold a string
+  return { overall: measures(attempts), tasks: Object.fromEntries([...tasks].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, measures(v)])) };
+}
+
+/** A seeded generator, so a comparison prints the same interval every time for the same records. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => { a = (a + 0x6d2b79f5) >>> 0; let t = a; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+export const MIN_ATTEMPTS = 5;
+type MeasureName = "passRate" | "firstPassRate" | "tokensMedian" | "wallMsMedian";
+export interface Comparison {
+  arms: { arm: string; runs: number; measures: Measures }[];
+  /** Each other arm against the first: the difference and its 95% bootstrap interval; inconclusive below MIN_ATTEMPTS. */
+  differences: { arm: string; measure: MeasureName; diff: number | null; low: number | null; high: number | null; inconclusive: boolean }[];
+}
+export function benchCompare(groups: { arm: string; runs: BenchRun[] }[], resamples = 1000, seed = 251): Comparison {
+  const arms = groups.map((g) => ({ arm: g.arm, runs: g.runs.length, attempts: g.runs.flatMap((r) => r.attempts) }));
+  const base = arms[0];
+  const differences: Comparison["differences"] = [];
+  const names: MeasureName[] = ["passRate", "firstPassRate", "tokensMedian", "wallMsMedian"];
+  if (base) for (const other of arms.slice(1)) {
+    const random = mulberry32(seed);
+    const pick = (xs: Attempt[]) => Array.from({ length: xs.length }, () => xs[Math.floor(random() * xs.length)]!);
+    const samples: Record<MeasureName, number[]> = { passRate: [], firstPassRate: [], tokensMedian: [], wallMsMedian: [] };
+    if (base.attempts.length && other.attempts.length) for (let i = 0; i < resamples; i++) {
+      const a = measures(pick(base.attempts)), b = measures(pick(other.attempts));
+      for (const n of names) if (a[n] !== null && b[n] !== null) samples[n].push(b[n]! - a[n]!);
+    }
+    const ma = measures(base.attempts), mb = measures(other.attempts);
+    // What each measure is computed over: pass rate and wall time over attempts that did not end in an error, the
+    // #247 measures over attempts that have them. Below MIN_ATTEMPTS of those in either arm a difference is inconclusive.
+    const counted = (xs: Attempt[], n: MeasureName) => n === "passRate" || n === "wallMsMedian" ? xs.filter((a) => a.outcome !== "error").length : xs.filter((a) => a.metrics).length;
+    for (const n of names) {
+      const s = samples[n].sort((x, y) => x - y);
+      const diff = ma[n] !== null && mb[n] !== null ? mb[n]! - ma[n]! : null;
+      const rank = (q: number) => s[Math.min(s.length - 1, Math.max(0, Math.ceil(q * s.length) - 1))]!; // nearest rank
+      differences.push({ arm: other.arm, measure: n, diff, low: s.length ? rank(0.025) : null, high: s.length ? rank(0.975) : null,
+        inconclusive: counted(base.attempts, n) < MIN_ATTEMPTS || counted(other.attempts, n) < MIN_ATTEMPTS || diff === null });
+    }
+  }
+  return { arms: arms.map((a) => ({ arm: a.arm, runs: a.runs, measures: measures(a.attempts) })), differences };
+}
+
+/** The runs an arm label stands for: every run of it that is over, a stopped one included (its attempts carry their own outcomes). */
+export const armRuns = (runs: BenchRun[], arm: string): BenchRun[] => runs.filter((r) => r.header.arm === arm && r.state !== "running" && r.state !== "unknown");
+/** Groups to compare must run the same suite (name and file hash), or their numbers measure different work. */
+export function sameSuite(groups: { arm: string; runs: BenchRun[] }[]): string | null {
+  const keys = new Set(groups.flatMap((g) => g.runs.map((r) => `${r.header.suite} (${String(r.header.suiteHash ?? "").slice(0, 12)})`)));
+  return keys.size > 1 ? `these runs come from different suites or suite versions: ${[...keys].join(", ")}` : null;
+}
+
+const pct = (v: number | null) => v === null ? "-" : `${Math.round(v * 100)}%`;
+const num = (v: number | null) => v === null ? "-" : String(Math.round(v));
+const dur = (ms: number | null) => ms === null ? "-" : ms < 120_000 ? `${Math.round(ms / 1000)}s` : `${Math.round(ms / 60_000)}m`;
+const row = (name: string, m: Measures) => `${name.padEnd(28)} ${String(m.attempts).padStart(8)}  ${pct(m.passRate).padStart(5)}  ${`${m.pass}/${m.fail}/${m.timeout}/${m.error}`.padStart(11)}  ${pct(m.firstPassRate).padStart(10)}  ${(m.reworkMean === null ? "-" : m.reworkMean.toFixed(2)).padStart(6)}  ${num(m.tokensMedian).padStart(10)}  ${dur(m.wallMsMedian).padStart(8)}`;
+const HEAD = `${"".padEnd(28)} ${"attempts".padStart(8)}  ${"pass".padStart(5)}  ${"p/f/t/e".padStart(11)}  ${"first pass".padStart(10)}  ${"rework".padStart(6)}  ${"tokens p50".padStart(10)}  ${"wall p50".padStart(8)}`;
+export function formatRuns(runs: BenchRun[]): string[] {
+  if (!runs.length) return ["no benchmark runs on this machine (ahub bench run <suite.json> --arm <label>)"];
+  return runs.map(runSummary).map((s) => `${s.run}  ${s.state.padEnd(11)} ${s.suite} [${s.arm}]  ${s.done}/${s.total}  pass ${pct(s.passRate)}  tokens p50 ${num(s.tokensMedian)}  wall p50 ${dur(s.wallMsMedian)}  ${s.startedAt}`);
+}
+export function formatReport(r: ReturnType<typeof benchReport>): string[] {
+  return [HEAD, row("all tasks", r.overall), ...Object.entries(r.tasks).map(([k, m]) => row(k, m))];
+}
+export function formatCompare(c: Comparison): string[] {
+  const lines = [HEAD, ...c.arms.map((a) => row(`${a.arm} (${a.runs} run${a.runs === 1 ? "" : "s"})`, a.measures))];
+  const fmt = (n: MeasureName, v: number | null) => v === null ? "-" : n.endsWith("Rate") ? `${v >= 0 ? "+" : ""}${Math.round(v * 100)}pt` : n === "wallMsMedian" ? `${v >= 0 ? "+" : "-"}${dur(Math.abs(v))}` : `${v >= 0 ? "+" : ""}${Math.round(v)}`;
+  for (const d of c.differences) lines.push(`${d.arm} vs ${c.arms[0]!.arm}: ${d.measure} ${fmt(d.measure, d.diff)} (95% ${fmt(d.measure, d.low)} to ${fmt(d.measure, d.high)})${d.inconclusive ? `, inconclusive: fewer than ${MIN_ATTEMPTS} attempts counted for it in an arm` : ""}`);
+  return lines;
+}
+export const CSV_COLUMNS = ["run", "suite", "arm", "task", "repeat", "outcome", "error", "verifyExit", "hubTask", "startedAt", "endedAt", "ms", "tokens", "wallMs", "activeMs",
+  "reviewRounds", "changesRequested", "checkFailed", "firstPass", "turns", "filesChanged", "models"] as const;
+export function benchCsv(runs: BenchRun[]): string {
+  const cell = (v: unknown) => { const s = v === null || v === undefined ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
+  const rows = runs.flatMap((r) => r.attempts.map((a) => [r.header.run, r.header.suite, r.header.arm, a.task, a.repeat, a.outcome, a.error, a.verifyExit, a.hubTask, a.startedAt, a.endedAt, a.ms,
+    a.metrics?.tokens, a.metrics?.wallMs, a.metrics?.activeMs, a.metrics?.reviewRounds, a.metrics?.changesRequested, a.metrics?.checkFailed, a.metrics?.firstPass, a.metrics?.turns,
+    a.metrics?.filesChanged, a.metrics?.models.join(" ")].map(cell).join(",")));
+  return [CSV_COLUMNS.join(","), ...rows].join("\n") + "\n";
+}

package/src/hub/bus.ts

@@ -17,6 +17,8 @@ export type BusEvent =
   | { t: "state"; peer: PeerId; state: PeerState };
 
 export interface BusOptions {
+  /** Transient owner lifecycle fence: retain new work without changing console/budget pauses. */
+  deliveryHeld?: (peer: PeerId) => boolean;
   /** Observe original envelopes immediately before a transport starts its turn. */
   onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
   retryMs: number;
@@ -295,7 +297,14 @@ export class Bus {
       if (current.revision === 0) {
         this.journal.importSnapshot(snapshot.journal ?? { schemaVersion: 1, revision: 1, instanceId: this.journal.instanceId, bus: snapshot, deliveries: [], manualPaused: snapshot.manualPaused ?? [] }, _operationId);
       }
+      const committedQueues = snapshot.queues;
       snapshot = this.journal.snapshot().bus;
+      // Offline peers need not reattach. Their empty queue keys still belong to the
+      // committed integrity view, even when no delivery ever persisted those keys (#234).
+      // The journal remains authoritative for work: never resurrect a non-empty queue.
+      for (const [id, queue] of Object.entries(committedQueues)) {
+        if (queue.length === 0 && !Object.hasOwn(snapshot.queues, id)) snapshot.queues[id] = [];
+      }
     }
     this.loadSnapshot(snapshot);
     this.persist();
@@ -348,7 +357,10 @@ export class Bus {
     if (record.revision !== revision) throw new Error("stale delivery revision");
     if (record.state === "queued" && action === "retry") throw new Error("queued delivery is already scheduled");
     if (action === "retry" && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
-    const before = this.snapshotWithoutJournal();
+    const queue = this.queues.get(record.peer) ?? [];
+    const hadQueue = this.queues.has(record.peer);
+    const before = [...queue];
+    const preface = this.prefaces.get(record.peer);
     try {
       this.journal.transaction(() => {
         if (!this.journal!.get(id)) this.journal!.createDelivery({ ...record });
@@ -356,10 +368,9 @@ export class Bus {
         this.journal!.resolve(id, current.revision, action, reason, revision);
         if (record.state === "queued") {
           const ids = new Set(record.originals.map((env) => env.id));
-          this.queues.set(record.peer, (this.queues.get(record.peer) ?? []).filter((env) => !ids.has(env.id)));
+          queue.splice(0, queue.length, ...queue.filter((env) => !ids.has(env.id)));
         }
         if (action === "retry") {
-          const queue = this.queues.get(record.peer) ?? [];
           for (const env of record.originals) {
             if (env.from === HUB && env.kind === "presence") this.restorePreface(record.peer, env);
             else if (!queue.some((old) => old.id === env.id)) queue.push(env);
@@ -368,7 +379,13 @@ export class Bus {
         }
         this.persist();
       });
-    } catch (error) { this.loadSnapshot(before); throw error; }
+    } catch (error) {
+      queue.splice(0, queue.length, ...before);
+      if (!hadQueue) this.queues.delete(record.peer);
+      if (preface) this.prefaces.set(record.peer, preface);
+      else this.prefaces.delete(record.peer);
+      throw error;
+    }
     this.refreshRecoveryHold(record.peer);
     this.onQueues?.();
     void this.drain(record.peer);
@@ -533,7 +550,7 @@ export class Bus {
     try { for (const id of targets) {
       const peer = this.peers.get(id);
       if (!peer) { this.enqueue(id, env); continue; }
-      if (!this.journal && !this.recoveryHeld && !this.recoveryHeldPeers.has(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
+      if (!this.journal && !this.recoveryHeld && !this.recoveryHeldPeers.has(id) && !this.opts.deliveryHeld?.(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
         // Not queued while the steer is in flight, or an idle transition would deliver it a second time.
         this.steering++;
         const deliveryId = crypto.randomUUID();
@@ -553,7 +570,7 @@ export class Bus {
       this.onQueues?.();
       for (const id of targets) {
         const peer = this.peers.get(id);
-        if (!this.recoveryHeld && !this.recoveryHeldPeers.has(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
+        if (!this.recoveryHeld && !this.recoveryHeldPeers.has(id) && !this.opts.deliveryHeld?.(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
         else void this.drain(id);
       }
     }
@@ -717,7 +734,7 @@ export class Bus {
 
   /** Holds on a peer's queue, for a drain and a pull alike: recovery, an uncertain delivery, a pause (console, budget, conductor). */
   private held(id: PeerId): boolean {
-    return this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.paused.has(id);
+    return this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.paused.has(id) || this.opts.deliveryHeld?.(id) === true;
   }
 
   /** What a peer was just handed stays resolvable for `reply_to`: moved to the newest end, the stored envelope kept. */

package/src/hub/conductor.ts

@@ -3,6 +3,7 @@ import type { Task } from "./board.ts";
 import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
 import { HUB, USER } from "./envelope.ts";
 import { OWNERSHIP_EVENTS } from "./tasks.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
 import type { Budget } from "./budget.ts";
@@ -24,8 +25,8 @@ export function publicPeerBudget(status: ReturnType<Budget["status"]>, nameable:
 }
 
 const PEER = /^[a-z][a-z0-9-]{0,31}$/;
-const peerId = (value: unknown): string => {
-  if (typeof value !== "string" || /\s/.test(value) || !PEER.test(value) || ["user", "hub", "digest"].includes(value)) throw new Error("peer must be a valid agent peer id");
+const peerId = (value: unknown, preEffect = false): string => {
+  if (typeof value !== "string" || /\s/.test(value) || !PEER.test(value) || ["user", "hub", "digest"].includes(value)) throw new (preEffect ? PreEffectToolRefusal : Error)("peer must be a valid agent peer id");
   return value;
 };
 
@@ -45,16 +46,16 @@ export function conductorPeer(roles: unknown): string | null {
 }
 
 /** The role check always comes first; default-allow capabilities cannot grant a role. */
-export function requireConductor(peer: string, roles: unknown, capabilities: Record<string, unknown> = {}, assign = false): void {
-  if (conductorPeer(roles) !== peer) throw new Error("this operation requires the explicit conductor role");
-  if (assign) requireAssign(peer, capabilities);
+export function requireConductor(peer: string, roles: unknown, capabilities: Record<string, unknown> = {}, assign = false, preEffect = false): void {
+  if (conductorPeer(roles) !== peer) throw new (preEffect ? PreEffectToolRefusal : Error)("this operation requires the explicit conductor role");
+  if (assign) requireAssign(peer, capabilities, preEffect);
 }
 
 /** A peer with an explicit capabilities list needs `assign` in it to move work. */
-function requireAssign(peer: string, capabilities: Record<string, unknown>): void {
+function requireAssign(peer: string, capabilities: Record<string, unknown>, preEffect = false): void {
   if (!Object.hasOwn(capabilities, peer)) return;
   const caps = capabilities[peer];
-  if (!Array.isArray(caps) || !caps.includes("assign")) throw new Error(`${peer} requires assign capability for this operation`);
+  if (!Array.isArray(caps) || !caps.includes("assign")) throw new (preEffect ? PreEffectToolRefusal : Error)(`${peer} requires assign capability for this operation`);
 }
 
 export interface ConductorHold { peer: string; actor: string; since: number }
@@ -101,11 +102,11 @@ export class ConductorHolds {
 
 export type ConductorStart = { peer: "local" | "kimi" | "pi"; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
 /** Preview commands come from the same launch planner the CLI uses, never caller-supplied shell text. */
-export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string): ConductorStart {
-  if (mode !== undefined && mode !== "headless" && mode !== "tui") throw new Error("mode must be headless or tui");
+export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect = false): ConductorStart {
+  if (mode !== undefined && mode !== "headless" && mode !== "tui") throw new (preEffect ? PreEffectToolRefusal : Error)("mode must be headless or tui");
   if (peer === "claude" || peer === "codex" || (peer === "pi" && mode === "tui")) return { peer, mode: "tui", command: preview(peer) };
   if ((peer === "local" || peer === "kimi" || peer === "pi") && mode !== "tui") return { peer, mode: "headless" };
-  throw new Error("only local, kimi and headless pi may be started by the conductor");
+  throw new (preEffect ? PreEffectToolRefusal : Error)("only local, kimi and headless pi may be started by the conductor");
 }
 
 const numberOrNull = (v: unknown): number | null => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
@@ -169,7 +170,7 @@ const taskId = (v: unknown): number | undefined => {
 export class Conductor {
   constructor(private readonly holds: ConductorHolds, private readonly hooks: ConductorHooks) {}
   async execute(actor: string, tool: string, args: Record<string, unknown>): Promise<unknown> {
-    if (!CONDUCTOR_TOOL_NAMES.has(tool)) throw new Error("unknown conductor tool");
+    if (!CONDUCTOR_TOOL_NAMES.has(tool)) throw new PreEffectToolRefusal("unknown conductor tool");
     if ((tool === "hub_task_show" || tool === "hub_task_assign") && conductorPeer(this.hooks.roles()) !== actor) {
       const id = taskId(args.id);
       const task = id === undefined ? undefined : this.hooks.task(id);
@@ -182,14 +183,14 @@ export class Conductor {
       const moved = task?.history.findLast((h) => h.by !== HUB && (OWNERSHIP_EVENTS.has(h.event) || h.event === "reserved"));
       const accepted = task?.history.some((h) => h.event === "accepted");
       if (task && tool === "hub_task_assign" && task.history[0]?.by === actor && task.state === "proposed" && !accepted && moved?.by !== USER) {
-        const peer = peerId(args.peer);
-        if (peer !== actor) requireAssign(actor, this.hooks.capabilities());
+        const peer = peerId(args.peer, true);
+        if (peer !== actor) requireAssign(actor, this.hooks.capabilities(), true);
         await this.hooks.assign(actor, task.id, peer);
         const updated = this.hooks.task(task.id);
         return updated ? publicConductorTask(updated, this.hooks.publicView) : { id: task.id };
       }
     }
-    requireConductor(actor, this.hooks.roles(), this.hooks.capabilities(), tool === "hub_task_assign" || tool === "hub_task_escalate");
+    requireConductor(actor, this.hooks.roles(), this.hooks.capabilities(), tool === "hub_task_assign" || tool === "hub_task_escalate", true);
     const action = tool.slice(4);
     const emit = (extra: Pick<ConductEvent, "task" | "peer"> = {}) => {
       try { this.hooks.audit({ kind: "conduct", actor, action, ...extra }); } catch { /* never throw after a task or hold write */ }
@@ -197,12 +198,12 @@ export class Conductor {
     if (tool === "hub_status") { const result = publicConductorStatus(this.hooks.status()); emit(); return result; }
     if (tool.startsWith("hub_task_")) {
       const id = taskId(args.id);
-      if (id === undefined) throw new Error("id must be a positive integer");
+      if (id === undefined) throw new PreEffectToolRefusal("id must be a positive integer");
       const task = this.hooks.task(id);
-      if (!task) throw new Error(`no task #${args.id}`);
+      if (!task) throw new PreEffectToolRefusal(`no task #${args.id}`);
       if (tool === "hub_task_show") { const result = publicConductorTask(task, this.hooks.publicView); emit({ task: task.id }); return result; }
       if (tool === "hub_task_assign") {
-        const peer = peerId(args.peer);
+        const peer = peerId(args.peer, true);
         await this.hooks.assign(actor, task.id, peer); emit({ task: task.id, peer });
       } else { await this.hooks.escalate(actor, task.id); emit({ task: task.id }); }
       // Task callbacks may return raw objects; always re-read and apply the public view.
@@ -210,15 +211,15 @@ export class Conductor {
       return updated ? publicConductorTask(updated, this.hooks.publicView) : { id: task.id };
     }
     if (tool === "hub_peer_start") {
-      const start = conductorStart(args.peer, args.mode, this.hooks.preview);
+      const start = conductorStart(args.peer, args.mode, this.hooks.preview, true);
       if (start.mode === "headless") await this.hooks.start(start.peer);
       emit({ peer: start.peer }); return start;
     }
-    const peer = peerId(args.peer);
-    if (!this.hooks.known(peer)) throw new Error(`unknown peer: ${peer}`);
+    const peer = peerId(args.peer, true);
+    if (!this.hooks.known(peer)) throw new PreEffectToolRefusal(`unknown peer: ${peer}`);
     if (tool === "hub_peer_hold") { this.holds.hold(peer, actor); this.hooks.pause(peer); }
     else {
-      if (this.holds.get(peer)?.actor !== actor) throw new Error("you may release only a conductor hold you placed");
+      if (this.holds.get(peer)?.actor !== actor) throw new PreEffectToolRefusal("you may release only a conductor hold you placed");
       await this.hooks.validateRelease?.(peer);
       requireConductor(actor, this.hooks.roles(), this.hooks.capabilities());
       this.holds.release(peer, actor); this.hooks.release(peer);

package/src/hub/config-trust.ts

@@ -10,6 +10,7 @@ import { childEnv } from "./child-process.ts";
  */
 export const MACHINE_LOCAL = [
   "kimi_cmd",
+  "permission_modes",
   "codex_bin",
   "pi.cmd",
   "checks",

package/src/hub/control-client.ts

@@ -30,6 +30,8 @@ export interface ControlDescriptor {
   cwd?: string;
   protocol?: number;
   pid?: number;
+  /** #226: the daemon's processSignature, written into status.json only (not the status reply); absent before 0.12.21. */
+  pidSignature?: string;
 }
 
 /** Where the daemon of this state dir listens. Re-read before every connect: port and token change per run. */
@@ -39,7 +41,8 @@ export function readControl(stateDir: string): ControlDescriptor | undefined {
     const token = readFileSync(join(stateDir, "control-token"), "utf8").trim();
     if (!Number.isInteger(status.controlPort) || status.controlPort < 1 || status.controlPort > 65535 || !token) return undefined;
     return { url: `ws://127.0.0.1:${status.controlPort}`, token, projectId: status.projectId,
-      instanceId: status.instanceId, cwd: status.cwd, protocol: status.protocol, pid: status.pid };
+      instanceId: status.instanceId, cwd: status.cwd, protocol: status.protocol, pid: status.pid,
+      ...(typeof status.pidSignature === "string" && status.pidSignature ? { pidSignature: status.pidSignature } : {}) };
   } catch {
     return undefined;
   }