@staix/agent-hub 0.12.19 → 0.12.21

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

@@ -27,12 +27,16 @@ export interface HistoryEntry {
   note?: string;
   /** The owner an event that set it left the task with (#67); absent in rows written before 0.11. */
   owner?: PeerId | null;
+  /** On a decline or an escalation: the owner it was declined for or taken from (#207); later reroutes leave it out. */
+  from?: PeerId;
   /** On a hand-over: the new owner's split profile then (#109); absent when it was unknown. */
   profile?: string;
   /** Structured cause recorded at the operation source, never inferred from note text. */
   reason?: TaskMoveReason;
   /** Persisted task-idle ladder; never counted as fresh task activity (#186). */
   sweep?: SweepRecord;
+  /** The PII screen did not clear this entry's note (#198): only the console reads it. */
+  withheld?: true;
 }
 export interface Task {
   id: number;
@@ -47,6 +51,8 @@ export interface Task {
   plan?: TaskPlan;
   /** Tasks that must be approved before this one is offered (issue #34); fixed when it is proposed. */
   deps?: number[];
+  /** Who routing offers the task first once nothing is left to wait for (issue #207); null when nobody was named. */
+  reserved?: PeerId | null;
   signals: string[];
   /** consecutive changes_requested verdicts */
   rejections: number;
@@ -95,14 +101,16 @@ export class Board {
     for (const [col, empty] of [["plan", "{}"], ["deps", "[]"]] as const) {
       if (!have.has(col)) this.db.run(`ALTER TABLE tasks ADD COLUMN ${col} TEXT NOT NULL DEFAULT '${empty}'`);
     }
+    // And from before issue #207: existing rows reserve nobody.
+    if (!have.has("reserved")) this.db.run("ALTER TABLE tasks ADD COLUMN reserved TEXT");
   }
 
-  propose(by: PeerId, t: { title: string; detail?: string; class: TaskClass; refs?: TaskRefs; plan?: TaskPlan; deps?: number[]; signals?: string[] }): Task {
+  propose(by: PeerId, t: { title: string; detail?: string; class: TaskClass; refs?: TaskRefs; plan?: TaskPlan; deps?: number[]; reserved?: PeerId; signals?: string[] }): Task {
     const now = Date.now();
     const history: HistoryEntry[] = [{ at: now, by, event: "proposed" }];
     const { lastInsertRowid } = this.db
-      .query("INSERT INTO tasks (title, detail, class, state, refs, plan, deps, signals, history, created, updated) VALUES (?, ?, ?, 'proposed', ?, ?, ?, ?, ?, ?, ?)")
-      .run(t.title, t.detail ?? "", t.class, JSON.stringify(t.refs ?? {}), JSON.stringify(t.plan ?? {}), JSON.stringify(t.deps ?? []), JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now);
+      .query("INSERT INTO tasks (title, detail, class, state, refs, plan, deps, reserved, signals, history, created, updated) VALUES (?, ?, ?, 'proposed', ?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(t.title, t.detail ?? "", t.class, JSON.stringify(t.refs ?? {}), JSON.stringify(t.plan ?? {}), JSON.stringify(t.deps ?? []), t.reserved ?? null, JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now);
     const task = this.get(Number(lastInsertRowid))!;
     this.changed(task, history[0]!);
     return task;
@@ -126,17 +134,17 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason"> = {}): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "withheld"> = {}): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state)) {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.withheld && note ? { withheld: true as const } : {}) }];
     this.db
-      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, plan = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
-      .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(history), Date.now(), id);
+      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, updated = ? WHERE id = ?")
+      .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), Date.now(), id);
     const updated = this.get(id)!;
     this.changed(updated, history.at(-1)!);
     return updated;

package/src/hub/bus.ts

@@ -295,7 +295,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 +355,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 +366,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 +377,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);
@@ -715,13 +730,69 @@ export class Bus {
     finally { this.steering--; this.onQueues?.(); }
   }
 
+  /** 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);
+  }
+
+  /** What a peer was just handed stays resolvable for `reply_to`: moved to the newest end, the stored envelope kept. */
+  private remember(envs: Envelope[]): void {
+    for (const e of envs) { const kept = this.seen.get(e.id) ?? e; this.seen.delete(e.id); this.seen.set(e.id, kept); }
+    while (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
+  }
+
+  /** A push may go out now: nothing holds the queue, the peer is idle, and its session shows pushes (issue #205). */
+  private deliverable(id: PeerId): boolean {
+    return !this.held(id) && this.stateOf(id) === "idle" && !this.peers.get(id)?.pullOnly;
+  }
+
+  /**
+   * What one push delivery would take (the preface, then `take`'s batch), handed to a pull-only peer and recorded as
+   * completed: the tool result that returns it is the readback, so nothing waits for settlement and nothing is ever
+   * `accepted` (issue #205). It is checkpointed like a push, so queued rows of the same envelopes (an operator retry)
+   * are grouped into it, and registered for `reply_to` like a push. Undefined while held. A failed journal write puts
+   * back only this peer's queue and preface (every pause stays) and stops the bus like any other journal failure.
+   * ponytail: recorded completed at hand-out, before anything shows the model saw it: a reply lost on the way, a tool
+   * call cancelled (Esc) or a plugin that dies loses the batch, and `ahub queue resolve --action retry` refuses a
+   * terminal row. The completed row keeps the envelopes (`ahub queue show <id>`) to resend by hand; take/confirm in two
+   * steps if loss is ever observed.
+   */
+  pull(id: PeerId): Envelope[] | undefined {
+    if (this.storageError) throw new Error("delivery journal unavailable");
+    if (this.held(id)) return undefined;
+    const queue = this.queues.get(id) ?? [];
+    this.dropIrrelevant(id, queue);
+    const preface = this.prefaces.get(id);
+    if (!preface && !queue.length) return [];
+    const queued = [...queue];
+    const batch = [...(preface ? [preface] : []), ...this.take(id, queue)];
+    this.prefaces.delete(id);
+    // Before the checkpoint, as in a drain, so the persisted snapshot carries it; on a failure the bus stops anyway.
+    this.remember(batch);
+    try {
+      const deliveryId = crypto.randomUUID();
+      this.journal?.transaction(() => {
+        this.durableHandoff(id, deliveryId, batch, batch); // its bus snapshot is the queue after this pull
+        this.journal!.transition(deliveryId, "completed", "read through hub_inbox");
+      });
+    } catch (error) {
+      queue.splice(0, queue.length, ...queued);
+      if (preface) this.prefaces.set(id, preface);
+      this.storageError = "delivery journal unavailable";
+      throw error;
+    }
+    this.failureStreak.delete(id); this.lastFailure.delete(id); // read, as a completed push receipt clears them
+    this.onQueues?.();
+    return batch;
+  }
+
   private async drain(id: PeerId): Promise<void> {
     if (this.storageError || this.draining.has(id) || !this.peers.has(id)) return;
     this.draining.add(id);
     try {
       const peer = this.peers.get(id)!;
       const queue = this.queues.get(id)!;
-      while (!this.storageError && !this.recoveryHeld && !this.recoveryHeldPeers.has(id) && queue.length && this.stateOf(id) === "idle") {
+      while (!this.storageError && queue.length && this.deliverable(id)) {
         if (this.dropIrrelevant(id, queue) && !queue.length) break;
         const delay = this.wait(queue);
         if (delay > 0) { this.arm(id, delay); break; }
@@ -736,7 +807,8 @@ export class Bus {
         this.condensing += mayCondense ? 1 : 0;
         const out = mayCondense ? await this.opts.condense!(delivery).catch(() => delivery) : delivery;
         this.condensing -= mayCondense ? 1 : 0;
-        if (this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.stateOf(id) !== "idle") {
+        // A session that cannot show pushes may have taken the peer while this was condensed (issue #205).
+        if (!this.deliverable(id)) {
           if (!this.journal) { if (preface) this.restorePreface(id, preface); queue.unshift(...batch.filter((e) => !this.withdrawn.has(e.id))); }
           break;
         }
@@ -751,8 +823,7 @@ export class Bus {
           for (const env of batch) queue.splice(queue.findIndex((item) => item.id === env.id), 1);
           this.prefaces.delete(id);
         }
-        for (const e of out) if (!this.seen.has(e.id)) this.seen.set(e.id, e);
-        while (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
+        this.remember(out);
         this.lastDelivery.set(id, { out, originals: delivery });
         this.preparing.delete(id); // from here on the transport/journal owns settlement
         const deliveryId = crypto.randomUUID();

package/src/hub/child-process.ts

@@ -17,6 +17,7 @@ export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.e
   delete env.CLAUDECODE;
   delete env.CLAUDE_CODE_SESSION_ID;
   delete env.CODEX_THREAD_ID;
+  delete env.AGENTHUB_CHANNEL;
   delete env.AGENTHUB_PEER_ID;
   env.AGENTHUB_PEER_ID = peer;
   return env;

package/src/hub/conductor.ts

@@ -1,6 +1,9 @@
 import { Database } from "bun:sqlite";
 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";
@@ -22,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;
 };
 
@@ -43,12 +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 && Object.hasOwn(capabilities, peer)) {
-    const caps = capabilities[peer];
-    if (!Array.isArray(caps) || !caps.includes("assign")) throw new Error(`${peer} requires assign capability for this operation`);
-  }
+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>, preEffect = false): void {
+  if (!Object.hasOwn(capabilities, peer)) return;
+  const caps = capabilities[peer];
+  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 }
@@ -95,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;
@@ -154,23 +161,49 @@ export interface ConductorHooks {
   audit(event: ConductEvent): void;
 }
 
+/** A task id as `Tasks.need()` takes it: a whole number or a digit string. */
+const taskId = (v: unknown): number | undefined => {
+  const n = typeof v === "number" ? v : typeof v === "string" && /^\s*\d+\s*$/.test(v) ? Number(v) : NaN;
+  return Number.isSafeInteger(n) && n > 0 ? n : 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");
-    requireConductor(actor, this.hooks.roles(), this.hooks.capabilities(), tool === "hub_task_assign" || tool === "hub_task_escalate");
+    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);
+      // A task's current owner and reviewer read its public view without the role (#208); nobody else does.
+      if (task && tool === "hub_task_show" && (task.owner === actor || task.reviewer === actor)) return publicConductorTask(task, this.hooks.publicView);
+      // Its proposer (the first history entry) redirects it while nobody ever accepted it (#207: a decline or a release puts
+      // worked tasks back in proposed); work that waits gets a reserved owner. Never over the person: a console assign or
+      // reservation stands until the conductor or the console moves it, also once the hub carried it out (the hub's own
+      // moves are not decisions).
+      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, 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", 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 */ }
     };
     if (tool === "hub_status") { const result = publicConductorStatus(this.hooks.status()); emit(); return result; }
     if (tool.startsWith("hub_task_")) {
-      if (typeof args.id !== "number" || !Number.isSafeInteger(args.id) || args.id <= 0) throw new Error("id must be a positive integer");
-      const task = this.hooks.task(args.id);
-      if (!task) throw new Error(`no task #${args.id}`);
+      const id = taskId(args.id);
+      if (id === undefined) throw new PreEffectToolRefusal("id must be a positive integer");
+      const task = this.hooks.task(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.
@@ -178,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

@@ -6,15 +6,17 @@ export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
-/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 15;
+/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
+export const PROTOCOL = 16;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
-export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, PROTOCOL] as const;
+export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */
   role: "peer" | "console" | "tools";
   peer?: string;
+  /** `peer` only: false when the session cannot show channel pushes; its queue then waits for `inbox` (issue #205). */
+  channel?: boolean;
   projectId?: string;
   instanceId?: string;
   projectRoot?: string;
@@ -28,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. */
@@ -37,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;
   }