@staix/agent-hub 0.12.20 → 0.12.21

package/src/hub/research.ts

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { StampedEvent } from "./events.ts";
+import { hubHome } from "./project.ts";
+
+/**
+ * #247: opt-in research records of how tasks went, built only from `events.jsonl` (ids, states, counts, tokens), so the
+ * live writer and `ahub research backfill` produce the same records. Never a title, detail, plan, note, path, message
+ * body or check output: the events carry none of those.
+ */
+export const RESEARCH_SCHEMA = "agent-hub.research/v1";
+export const LABELS = ["ok", "regressed", "reverted", "incomplete", "wrong", "abandoned"] as const;
+export type Label = (typeof LABELS)[number];
+/** A person's later verdict that turns an approved task into a failure. */
+const FAILED: ReadonlySet<string> = new Set(["regressed", "reverted", "incomplete", "wrong", "abandoned"]);
+
+export interface PeerUsage { input: number | null; output: number | null; cacheRead: number | null; total: number | null }
+export interface TaskRecord {
+  schema: typeof RESEARCH_SCHEMA; kind: "task"; project: string; task: number;
+  class: string | null; pii: boolean; outcome: "approved";
+  /** The proposal time also tells a task from an earlier one with the same id after `ahub reset --all`. */
+  createdAt: string | null; startedAt: string | null; approvedAt: string;
+  /** From the first `in_progress` to the approval; null when the start is not in the events. */
+  wallMs: number | null;
+  /** Sum of the attributed turns' durations, the turns still open at the approval included. */
+  activeMs: number;
+  /** Owners in the order they held the task. */
+  owners: string[]; reviewer: string | null;
+  /** Times the task went to review, was sent back, passed or failed its check, was reported done. */
+  reviewRounds: number; changesRequested: number; checkPassed: number; checkFailed: number; dones: number;
+  /** Owner changes after the first owner, and the same counted by the board's move reason. */
+  reassignments: number; reassignedBy: Record<string, number>;
+  /** Approved on its first review with no failed check. */
+  firstPass: boolean;
+  stuck: number; overlaps: number; conflicts: number;
+  tests: { pass: number; fail: number };
+  /** Attributed tokens per peer and per #200 attribution rule; unattributed tokens are in no record. */
+  tokens: { total: number; byPeer: Record<string, number>; byAttribution: Record<string, number> };
+  usage: Record<string, PeerUsage>;
+  /** Provider-reported total tokens per served (else requested) model. */
+  usageByModel: Record<string, number>;
+  turns: number; filesChanged: number;
+  /** Model routes and served models seen for the task's attributed requests. */
+  models: string[];
+  writer: { version: string; source: "live" | "backfill" };
+}
+/** A person's later verdict on one task record: `createdAt` binds it to that task, not a later one with the same id. */
+export interface LabelRecord { schema: typeof RESEARCH_SCHEMA; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string }
+export type ResearchRecord = TaskRecord | LabelRecord;
+
+/** The store name for a project: a hash of its id, never its path. */
+export const projectKey = (projectId: string): string => createHash("sha256").update(projectId).digest("hex").slice(0, 16);
+export const researchDir = (home = hubHome()): string => join(home, "research");
+export const researchFile = (projectId: string, home = hubHome()): string => join(researchDir(home), `${projectKey(projectId)}.jsonl`);
+/** One task across every record about it: a task id is reused after `ahub reset --all`, its proposal time is not. */
+export const recordKey = (r: { project: string; task: number; createdAt: string | null; approvedAt?: string }): string => `${r.project}#${r.task}@${r.createdAt ?? r.approvedAt ?? ""}`;
+
+type Acc = Omit<TaskRecord, "schema" | "kind" | "project" | "approvedAt" | "wallMs" | "firstPass" | "outcome" | "writer" | "models"> & {
+  models: Set<string>; approvedAt: string | null; lastState: string | null;
+};
+/** Keyed by peer ids, model names and reasons, any of which may be `constructor` or `__proto__`: no prototype to inherit from. */
+const keyed = <T>(): Record<string, T> => Object.create(null) as Record<string, T>;
+const blank = (task: number): Acc => ({ task, class: null, pii: false, createdAt: null, startedAt: null, activeMs: 0, owners: [], reviewer: null,
+  reviewRounds: 0, changesRequested: 0, checkPassed: 0, checkFailed: 0, dones: 0, reassignments: 0, reassignedBy: keyed(), stuck: 0, overlaps: 0, conflicts: 0,
+  tests: { pass: 0, fail: 0 }, tokens: { total: 0, byPeer: keyed(), byAttribution: keyed() }, usage: keyed(), usageByModel: keyed(), turns: 0, filesChanged: 0, models: new Set(),
+  approvedAt: null, lastState: null });
+const add = (current: number | null, value: unknown): number | null => typeof value === "number" && Number.isFinite(value) ? (current ?? 0) + value : current;
+const bump = (counts: Record<string, number>, key: string, n = 1) => { counts[key] = (counts[key] ?? 0) + n; };
+
+/**
+ * One record per approved task in `events`. Approval is final on the board, so everything attributed to the task
+ * counts, also after the approval: the turn that approved it ends later, and its usage arrives after that. The live
+ * writer therefore waits for those turns (daemon `recordResearch`); backfill reads to the end of the file.
+ */
+export function taskRecords(events: StampedEvent[], projectId: string, writer: TaskRecord["writer"]): TaskRecord[] {
+  const tasks = new Map<number, Acc>(), earlier: Acc[] = [];
+  const acc = (id: number) => { let a = tasks.get(id); if (!a) tasks.set(id, a = blank(id)); return a; };
+  const seenUsage = new Set<string>();
+  for (const e of events) {
+    if (e.type === "task") {
+      // Ids restart after `ahub reset --all` archives the events, but a file that kept both starts the task anew.
+      if (e.event === "proposed" && tasks.get(e.id)?.createdAt) { earlier.push(tasks.get(e.id)!); tasks.delete(e.id); }
+      const a = acc(e.id);
+      a.class = e.class; if (e.pii) a.pii = true;
+      if (e.owner && e.owner !== a.owners.at(-1)) {
+        if (a.owners.length) { a.reassignments++; bump(a.reassignedBy, e.reason ?? "none"); }
+        a.owners.push(e.owner);
+      }
+      if (e.reviewer) a.reviewer = e.reviewer;
+      if (e.event === "proposed") a.createdAt ??= e.at;
+      if (e.state === "in_progress") a.startedAt ??= e.at;
+      if (e.event === "done") a.dones++;
+      if (e.event === "check passed") a.checkPassed++;
+      if (e.event === "check failed") a.checkFailed++;
+      if (e.state === "in_review" && a.lastState !== "in_review") a.reviewRounds++;
+      if (e.state === "changes_requested" && a.lastState !== "changes_requested") a.changesRequested++;
+      if (e.state === "approved") a.approvedAt ??= e.at;
+      a.lastState = e.state;
+      continue;
+    }
+    const task = "task" in e && typeof e.task === "number" ? e.task : undefined;
+    if (task === undefined) continue;
+    const a = acc(task);
+    if ("pii" in e && e.pii === true) a.pii = true;
+    if (e.type === "tokens") { a.tokens.total += e.n; bump(a.tokens.byPeer, e.peer, e.n); bump(a.tokens.byAttribution, e.attribution ?? "unknown", e.n); }
+    else if (e.type === "turn_end") { a.turns++; a.activeMs += e.ms; a.filesChanged += e.files ?? 0; }
+    else if (e.type === "usage") {
+      const key = `${e.peer}\0${e.source}\0${e.id}`;
+      if (seenUsage.has(key)) continue;
+      seenUsage.add(key);
+      const u = a.usage[e.peer] ??= { input: null, output: null, cacheRead: null, total: null };
+      u.input = add(u.input, e.inputTokens); u.output = add(u.output, e.outputTokens); u.cacheRead = add(u.cacheRead, e.cacheReadTokens); u.total = add(u.total, e.totalTokens);
+      const model = e.servedModel ?? e.requestedModel;
+      if (model) a.models.add(String(model));
+      if (typeof e.totalTokens === "number" && Number.isFinite(e.totalTokens)) bump(a.usageByModel, String(model ?? "unknown"), e.totalTokens);
+    }
+    else if (e.type === "route") a.models.add(e.route);
+    else if (e.type === "route_outcome") { if (e.next?.tests === "pass") a.tests.pass++; if (e.next?.tests === "fail") a.tests.fail++; }
+    else if (e.type === "stuck") a.stuck++;
+    else if (e.type === "overlap") a.overlaps++;
+    else if (e.type === "conflict") a.conflicts++;
+  }
+  const out: TaskRecord[] = [];
+  for (const a of [...earlier, ...tasks.values()]) {
+    if (!a.approvedAt) continue;
+    const { approvedAt, lastState: _state, models, ...rest } = a;
+    const start = a.startedAt ? Date.parse(a.startedAt) : NaN, end = Date.parse(approvedAt);
+    out.push({ schema: RESEARCH_SCHEMA, kind: "task", project: projectKey(projectId), ...rest, outcome: "approved", approvedAt,
+      wallMs: Number.isFinite(start) && Number.isFinite(end) && end >= start ? end - start : null,
+      firstPass: a.changesRequested === 0 && a.checkFailed === 0 && a.reviewRounds <= 1, models: [...models].sort(), writer });
+  }
+  return out.sort((x, y) => x.approvedAt.localeCompare(y.approvedAt) || x.task - y.task);
+}
+
+/** Every record in one store file; a line that does not parse is skipped. */
+export function readStore(file: string): ResearchRecord[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8").split("\n").flatMap((line) => {
+    if (!line.trim()) return [];
+    try { const r = JSON.parse(line); return r?.schema === RESEARCH_SCHEMA ? [r as ResearchRecord] : []; } catch { return []; }
+  });
+}
+/** This project's store, or every project's with `all`. */
+export function readStores(projectId: string | undefined, home = hubHome()): ResearchRecord[] {
+  if (projectId) return readStore(researchFile(projectId, home));
+  const dir = researchDir(home);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith(".jsonl")).sort().flatMap((name) => readStore(join(dir, name)));
+}
+
+/** Append task records the store does not hold yet (same task, by `recordKey`), and labels; returns how many were written. */
+export function appendRecords(projectId: string, records: ResearchRecord[], home = hubHome()): number {
+  if (!records.length) return 0;
+  const file = researchFile(projectId, home);
+  mkdirSync(researchDir(home), { recursive: true, mode: 0o700 });
+  chmodSync(researchDir(home), 0o700); // mkdir's mode applies only when it creates the directory
+  const held = new Set(readStore(file).flatMap((r) => r.kind === "task" ? [recordKey(r)] : []));
+  const added = records.filter((r) => r.kind === "label" || !held.has(recordKey(r)));
+  if (!added.length) return 0;
+  appendFileSync(file, added.map((r) => JSON.stringify(r)).join("\n") + "\n", { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return added.length;
+}
+
+/**
+ * The record a person's label is for. `created` (a record's `createdAt`, from `ahub research export`) names one exactly.
+ * Otherwise the current board's task with that id, found by its proposal in `events`, so a label never lands on an
+ * earlier task with the same id; an id this hub's events do not have (a task from before `ahub reset --all`) is the
+ * store's only record with that id. Throws why there is none, or which ones to choose from.
+ */
+export function labelTarget(records: ResearchRecord[], events: StampedEvent[], task: number, created?: string): TaskRecord {
+  // A record without a proposal time (its proposal was not in the events) cannot be told apart, so it takes no label.
+  const mine = records.filter((r): r is TaskRecord => r.kind === "task" && r.task === task && r.createdAt !== null);
+  if (created !== undefined) {
+    return mine.find((r) => r.createdAt === created) ?? fail(`no research record for task #${task} proposed at ${created}${mine.length ? ` (it has: ${mine.map((r) => r.createdAt).join(", ")})` : ""}`);
+  }
+  const proposed = events.filter((e) => e.type === "task" && e.id === task && e.event === "proposed").at(-1);
+  if (proposed) {
+    return mine.find((r) => r.createdAt === proposed.at)
+      ?? fail(`task #${task} has no research record yet: it is not approved, its record still waits for the turns that approved it, or it was approved while research was off (ahub research backfill builds that one)${mine.length ? `; an earlier task #${task} from before a reset is labelled with --created ${mine.map((r) => r.createdAt).join(" or ")}` : ""}`);
+  }
+  if (mine.length === 1) return mine[0]!;
+  if (!mine.length) throw new Error(records.some((r) => r.kind === "task" && r.task === task) ? `task #${task}'s research record has no proposal time (its proposal was not in the events), so it takes no label` : `no research record for task #${task}`);
+  throw new Error(`task #${task} is not on this hub's board and the store has ${mine.length} records with that id; name one with --created <time>: ${mine.map((r) => r.createdAt).join(", ")}`);
+}
+const fail = (message: string): never => { throw new Error(message); };
+
+const pct = (n: number, d: number) => d ? n / d : null;
+/** Linear interpolation between the closest ranks: the median of [100, 300] is 200. */
+function quantile(values: number[], q: number): number | null {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b), at = q * (sorted.length - 1), low = Math.floor(at);
+  return sorted[low]! + (sorted[Math.min(low + 1, sorted.length - 1)]! - sorted[low]!) * (at - low);
+}
+export interface Measures {
+  tasks: number; succeeded: number; failedByLabel: number;
+  successRate: number | null; firstPassRate: number | null; reworkRate: number | null; checkFailureRate: number | null;
+  tokensPerTask: { median: number | null; p90: number | null }; wallMsPerTask: { median: number | null; p90: number | null };
+}
+function measures(records: TaskRecord[], labels: Map<string, Label>): Measures {
+  const failed = records.filter((r) => FAILED.has(labels.get(recordKey(r)) ?? "")).length;
+  return { tasks: records.length, succeeded: records.length - failed, failedByLabel: failed,
+    successRate: pct(records.length - failed, records.length), firstPassRate: pct(records.filter((r) => r.firstPass).length, records.length),
+    reworkRate: pct(records.reduce((n, r) => n + r.changesRequested, 0), records.length),
+    checkFailureRate: pct(records.reduce((n, r) => n + r.checkFailed, 0), records.reduce((n, r) => n + r.checkFailed + r.checkPassed, 0)),
+    tokensPerTask: { median: quantile(records.map((r) => r.tokens.total), 0.5), p90: quantile(records.map((r) => r.tokens.total), 0.9) },
+    wallMsPerTask: { median: quantile(records.flatMap((r) => r.wallMs ?? []), 0.5), p90: quantile(records.flatMap((r) => r.wallMs ?? []), 0.9) } };
+}
+export interface ResearchReport { overall: Measures; byClass: Record<string, Measures>; byOwner: Record<string, Measures>; byProject: Record<string, Measures>; byModel: Record<string, Measures> }
+/**
+ * The derived measures, never stored as truth: each task counts once (its last record), and a person's latest label
+ * decides whether an approved task later failed. Records older than `since` (ms epoch, by approval) are left out.
+ */
+export function researchReport(records: ResearchRecord[], since = 0): ResearchReport {
+  const latest = new Map<string, TaskRecord>(), labels = new Map<string, Label>();
+  for (const r of records) {
+    const key = recordKey(r);
+    if (r.kind === "label") { labels.set(key, r.label); continue; }
+    if (Date.parse(r.approvedAt) >= since) latest.set(key, r);
+  }
+  const all = [...latest.values()];
+  const group = (keys: (r: TaskRecord) => string[]) => {
+    // A Map: a peer or model may be named `constructor`, which a plain object answers with an inherited value.
+    const out = new Map<string, TaskRecord[]>();
+    for (const r of all) for (const k of keys(r)) out.set(k, [...(out.get(k) ?? []), r]);
+    return Object.fromEntries([...out].sort(([a], [b]) => a.localeCompare(b)).map(([k, rs]) => [k, measures(rs, labels)]));
+  };
+  return { overall: measures(all, labels), byClass: group((r) => [r.class ?? "unknown"]), byOwner: group((r) => r.owners.length ? [...new Set(r.owners)] : ["none"]),
+    byProject: group((r) => [r.project]), byModel: group((r) => r.models.length ? r.models : ["unknown"]) };
+}
+
+const fmtPct = (v: number | null) => v === null ? "-" : `${Math.round(v * 100)}%`;
+const fmtNum = (v: number | null) => v === null ? "-" : String(Math.round(v));
+export function formatResearch(r: ResearchReport): string[] {
+  const row = (name: string, m: Measures) => `${name.padEnd(24)} ${String(m.tasks).padStart(5)}  ${fmtPct(m.successRate).padStart(7)}  ${fmtPct(m.firstPassRate).padStart(10)}  ${(m.reworkRate === null ? "-" : m.reworkRate.toFixed(2)).padStart(6)}  ${fmtPct(m.checkFailureRate).padStart(11)}  ${fmtNum(m.tokensPerTask.median).padStart(10)}  ${fmtNum(m.tokensPerTask.p90).padStart(10)}  ${(m.wallMsPerTask.median === null ? "-" : `${Math.round(m.wallMsPerTask.median / 60_000)}m`).padStart(8)}`;
+  const head = `${"".padEnd(24)} ${"tasks".padStart(5)}  ${"success".padStart(7)}  ${"first pass".padStart(10)}  ${"rework".padStart(6)}  ${"check fails".padStart(11)}  ${"tokens p50".padStart(10)}  ${"tokens p90".padStart(10)}  ${"wall p50".padStart(8)}`;
+  const section = (title: string, groups: Record<string, Measures>) => Object.keys(groups).length ? [``, title, head, ...Object.entries(groups).map(([k, m]) => row(k, m))] : [];
+  return [head, row("all approved tasks", r.overall), ...section("by class", r.byClass), ...section("by owner", r.byOwner), ...section("by model", r.byModel), ...section("by project", r.byProject)];
+}
+
+export const CSV_COLUMNS = ["project", "task", "class", "pii", "outcome", "createdAt", "startedAt", "approvedAt", "wallMs", "activeMs", "owners",
+  "reviewer", "reviewRounds", "changesRequested", "checkPassed", "checkFailed", "dones", "reassignments", "firstPass", "stuck", "overlaps", "conflicts",
+  "testsPass", "testsFail", "tokens", "turns", "filesChanged", "models", "label", "writerVersion", "writerSource"] as const;
+/** Task records as CSV with a header row, one row per record, each with the task's latest label; JSONL has every field. */
+export function toCsv(records: ResearchRecord[]): string {
+  const labels = new Map<string, Label>();
+  for (const r of records) if (r.kind === "label") labels.set(recordKey(r), r.label);
+  const cell = (v: unknown) => { const s = v === null || v === undefined ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
+  const rows = records.filter((r): r is TaskRecord => r.kind === "task").map((r) => [r.project, r.task, r.class, r.pii, r.outcome, r.createdAt, r.startedAt,
+    r.approvedAt, r.wallMs, r.activeMs, r.owners.join(" "), r.reviewer, r.reviewRounds, r.changesRequested, r.checkPassed, r.checkFailed, r.dones,
+    r.reassignments, r.firstPass, r.stuck, r.overlaps, r.conflicts, r.tests.pass, r.tests.fail, r.tokens.total, r.turns, r.filesChanged, r.models.join(" "),
+    labels.get(recordKey(r)) ?? "", r.writer.version, r.writer.source].map(cell).join(","));
+  return [CSV_COLUMNS.join(","), ...rows].join("\n") + "\n";
+}

package/src/hub/tasks.ts

@@ -9,6 +9,7 @@ import { assign, detectSignals, LOCAL, peerEntry, PI, predictSplit, type Assignm
 import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecision, type ExecutionBudgetStatus, type ExecutionUnit } from "./execution-budget.ts";
 import { Cohorts, MAX_REQUESTS, type Cohort, type Completion } from "./cohorts.ts";
 import { realPath } from "./project.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
 import { nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
 
 export interface TasksDeps {
@@ -470,7 +471,7 @@ export class Tasks {
   async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; refs?: TaskRefs; plan?: TaskPlan; owner?: PeerId; after?: unknown; urgent?: unknown }): Promise<Task> {
     // Callers are models: a title is one line (it is part of console and hub.log lines), not a document.
     const title = String(input.title ?? "").replace(/\s+/g, " ").trim().slice(0, 300);
-    if (!title) throw new Error("title is required");
+    if (!title) throw new PreEffectToolRefusal("title is required");
     // Dependencies can only name tasks that exist, so the new task closes no cycle: nothing can depend on it yet.
     // Callers are models: a missing or null `after` is no dependency, and an id is an integer or a digit string.
     let afterIds: unknown[] = [];
@@ -479,14 +480,14 @@ export class Tasks {
     const deps: number[] = [];
     for (const v of afterIds) {
       const id = typeof v === "number" || (typeof v === "string" && /^\s*\d+\s*$/.test(v)) ? Number(v) : NaN;
-      if (!Number.isInteger(id)) throw new Error(`after: ${JSON.stringify(v)} is not a task id`);
-      if (!this.d.board.get(id)) throw new Error(`after: no task #${id}`);
+      if (!Number.isInteger(id)) throw new PreEffectToolRefusal(`after: ${JSON.stringify(v)} is not a task id`);
+      if (!this.d.board.get(id)) throw new PreEffectToolRefusal(`after: no task #${id}`);
       if (!deps.includes(id)) deps.push(id);
     }
     // An owner for work that waits is reserved (issue #207): routing offers it to that peer first once it is ready.
     const reserved = this.waitsFor({ deps }).length ? input.owner : undefined;
     const given = input.class === undefined || input.class === "" ? undefined : input.class;
-    if (given !== undefined && !CLASSES.includes(given as TaskClass)) throw new Error(`class must be one of ${CLASSES.join(", ")}`);
+    if (given !== undefined && !CLASSES.includes(given as TaskClass)) throw new PreEffectToolRefusal(`class must be one of ${CLASSES.join(", ")}`);
     const text = { title, detail: String(input.detail ?? "").slice(0, 8000), refs: cleanRefs(input.refs) };
     const plan = cleanPlan(input.plan);
     // The plan reaches other owners, so a PII pattern in it makes the task a PII task like one in the detail would.
@@ -511,7 +512,7 @@ export class Tasks {
     // A claim is work the caller will do itself: without a class and a model to name one, it is implementation (#6).
     const defaulted = !cls && input.owner === by;
     if (defaulted) cls = "implement";
-    if (!cls) throw new Error(`class is required (one of ${CLASSES.join(", ")}); ${fenced ? "the task is handled as PII and the hub's model is not reached on campus, so it was not asked to name one" : "the hub could not name one for you"}`);
+    if (!cls) throw new PreEffectToolRefusal(`class is required (one of ${CLASSES.join(", ")}); ${fenced ? "the task is handled as PII and the hub's model is not reached on campus, so it was not asked to name one" : "the hub could not name one for you"}`);
     const draft = { ...text, class: cls };
     let task = this.d.board.propose(by, { ...draft, plan, ...(deps.length ? { deps } : {}), ...(reserved ? { reserved } : {}), signals });
     if (screening) task = this.screenedTask(task, screened);
@@ -902,26 +903,36 @@ export class Tasks {
   }
 
   /** Nobody, the console user included, works on a task before what it waits for is approved. */
-  private ready(task: Task): void {
+  private ready(task: Task, preEffect = false): void {
     const waits = this.waitsFor(task);
-    if (waits.length) throw new Error(`task #${task.id} waits for ${waits.map((id) => `#${id}`).join(", ")}, not approved yet`);
+    if (waits.length) throw new (preEffect ? PreEffectToolRefusal : Error)(`task #${task.id} waits for ${waits.map((id) => `#${id}`).join(", ")}, not approved yet`);
   }
 
   /** An approved task may be the last thing others waited for: those go through assignment now (issue #34). */
   private async releaseDependents(approved: Task): Promise<void> {
-    for (const t of this.d.board.list("proposed")) {
-      if (!t.deps?.includes(approved.id) || t.owner || this.waitsFor(t).length) continue;
-      await this.offerReady(t, `#${approved.id} approved`);
+    try {
+      for (const t of this.d.board.list("proposed")) {
+        if (!t.deps?.includes(approved.id) || t.owner || this.waitsFor(t).length) continue;
+        await this.offerReady(t, `#${approved.id} approved`);
+      }
+    } catch (e) {
+      this.releaseNotice(`task #${approved.id}: could not release dependents: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
 
-  private readonly offered = new Set<number>(); // ready tasks offered in this hub run
+  /** Notifications may read the same unavailable board; they must not undo a saved approval's return. */
+  private releaseNotice(line: string): void {
+    try { this.d.notify(line); } catch { /* best effort; the release timer retries ownerless work */ }
+  }
+
+  private readonly offered = new Set<number>(); // assignments in this hub run, including offers still in flight
   private readonly sent = new Map<string, PeerId>(); // hand-over (`handOver`) -> owner, for the owner's current turn: its task envelope started it, or it claimed the task in it
 
   /**
    * A stop between an approval and the assignment of its dependents (both are saved on their own) leaves them ownerless
    * with nothing left to wait for, and no later approval to offer them. The daemon calls this on its release timer:
-   * each such task is offered once per hub run, once an attached peer can take it (peers attach one by one).
+   * each such task is offered once an attached peer can take it (peers attach one by one). Only an assignment uses
+   * up its offer for this hub run; a failed or ownerless offer stays eligible, after approval and on the timer alike.
    */
   async releaseReady(): Promise<void> {
     for (const t of this.d.board.list("proposed")) {
@@ -936,26 +947,41 @@ export class Tasks {
 
   /** Callers hold a list read before an await: re-read, or a task the other caller offered meanwhile is offered twice. */
   private async offerReady(stale: Task, why: string): Promise<void> {
-    const t = this.d.board.get(stale.id);
-    if (!t || t.state !== "proposed" || t.owner || this.offered.has(t.id)) return;
-    this.offered.add(t.id);
-    const ready = t.history.at(-1)?.event === "ready" ? t : this.d.board.update(t.id, HUB, "ready", {}, why);
-    this.d.notify(`task ${this.publicTitle(ready)} is ready: what it waited for is approved`);
-    await this.assignOwner(ready, HUB).catch((e: Error) => this.d.notify(`task ${this.publicTitle(ready)}: could not be assigned: ${e.message}`));
+    let offering = false;
+    try {
+      const t = this.d.board.get(stale.id);
+      if (!t || t.state !== "proposed" || t.owner || this.offered.has(t.id)) return;
+      this.offered.add(t.id);
+      offering = true;
+      const ready = t.history.at(-1)?.event === "ready" ? t : this.d.board.update(t.id, HUB, "ready", {}, why);
+      this.releaseNotice(`task ${this.publicTitle(ready)} is ready: what it waited for is approved`);
+      await this.assignOwner(ready, HUB);
+    } catch (e) {
+      this.releaseNotice(`task ${this.publicTitle(stale)}: could not be assigned: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      if (offering) {
+        try {
+          if (!this.d.board.get(stale.id)?.owner) this.offered.delete(stale.id);
+        } catch (e) {
+          this.offered.delete(stale.id);
+          this.releaseNotice(`task ${this.publicTitle(stale)}: could not verify assignment: ${e instanceof Error ? e.message : String(e)}`);
+        }
+      }
+    }
   }
 
-  private mine(task: Task, by: PeerId, role: "owner" | "reviewer"): void {
-    if (by !== USER && task[role] !== by) throw new Error(`task #${task.id}: only its ${role} (${task[role] ?? "none"}) or the console user can do that`);
+  private mine(task: Task, by: PeerId, role: "owner" | "reviewer", preEffect = false): void {
+    if (by !== USER && task[role] !== by) throw new (preEffect ? PreEffectToolRefusal : Error)(`task #${task.id}: only its ${role} (${task[role] ?? "none"}) or the console user can do that`);
   }
 
-  private need(id: unknown, open = false): Task {
+  private need(id: unknown, open = false, preEffect = false): Task {
     // Callers are models (#70): an id is a whole number or a digit string, never an array that Number() would accept.
     const n = typeof id === "number" ? id : typeof id === "string" && /^\s*\d+\s*$/.test(id) ? Number(id) : NaN;
-    if (!Number.isInteger(n)) throw new Error(`id must be a task number, not ${(typeof id === "number" ? String(id) : JSON.stringify(id ?? null)).slice(0, 60)}`);
+    if (!Number.isInteger(n)) throw new (preEffect ? PreEffectToolRefusal : Error)(`id must be a task number, not ${(typeof id === "number" ? String(id) : JSON.stringify(id ?? null)).slice(0, 60)}`);
     const task = this.d.board.get(n);
-    if (!task) throw new Error(`no task #${n}`);
+    if (!task) throw new (preEffect ? PreEffectToolRefusal : Error)(`no task #${n}`);
     // Handing a task to someone else only makes sense while there is work left on it.
-    if (open && !OPEN.includes(task.state)) throw new Error(`task #${task.id} is ${task.state}: it can no longer change hands`);
+    if (open && !OPEN.includes(task.state)) throw new (preEffect ? PreEffectToolRefusal : Error)(`task #${task.id} is ${task.state}: it can no longer change hands`);
     return task;
   }
 
@@ -964,15 +990,16 @@ export class Tasks {
    * announced like one found at assignment (issue #31).
    */
   accept(by: PeerId, id: unknown, plan?: unknown): Task {
-    const task = this.need(id);
-    this.mine(task, by, "owner");
-    this.ready(task);
+    const task = this.need(id, false, true);
+    this.mine(task, by, "owner", true);
+    this.ready(task, true);
+    if (task.state !== "proposed" && task.state !== "changes_requested" && task.state !== "in_progress") throw new PreEffectToolRefusal(`task #${task.id} is ${task.state}: cannot move to in_progress`);
     // Models send null or {} for an optional field they leave empty: neither replaces a plan.
     const given = plan == null ? undefined : cleanPlan(plan);
     const cleaned = given && Object.keys(given).length ? given : undefined;
     // A task's signals are fixed when it is proposed: text that matches a PII pattern cannot be let in afterwards.
     if (cleaned && !this.isPii(task) && this.isPii({ signals: detectSignals({ title: "", detail: planText(cleaned), refs: {} }, this.d.routing(), this.d.cwd) })) {
-      throw new Error("this plan matches a PII pattern and is not kept: other owners would see it");
+      throw new PreEffectToolRefusal("this plan matches a PII pattern and is not kept: other owners would see it");
     }
     const before = new Set(this.overlapHits(task).map((h) => h.task.id));
     const next = this.d.board.update(task.id, by, "accepted", { state: "in_progress", ...(cleaned ? { plan: cleaned } : {}) });
@@ -1031,8 +1058,8 @@ export class Tasks {
   };
 
   async decline(by: PeerId, id: unknown, reason?: string): Promise<Task> {
-    const task = this.need(id, true);
-    this.mine(task, by, "owner");
+    const task = this.need(id, true, true);
+    this.mine(task, by, "owner", true);
     // The owner it is declined for goes on the entry, also when the console declines for it: `excluded()` keeps it out (#207).
     const back = this.d.board.update(task.id, by, "declined", task.state === "in_progress" ? { state: "proposed" } : {}, reason, task.owner ? { from: task.owner } : {});
     this.d.notify(`task ${this.publicTitle(back)} declined by ${by}${reason && !this.isPii(back) ? `: ${reason}` : ""}`);
@@ -1051,13 +1078,13 @@ export class Tasks {
 
   async done(by: PeerId, id: unknown, summary?: string, refs?: TaskRefs): Promise<Task> {
     const valid = (): Task => {
-      const t = this.need(id);
-      this.mine(t, by, "owner");
-      if (t.state === "in_review" || t.state === "approved") throw new Error(`task #${t.id} is already ${t.state}`);
-      this.ready(t);
+      const t = this.need(id, false, true);
+      this.mine(t, by, "owner", true);
+      if (t.state === "in_review" || t.state === "approved") throw new PreEffectToolRefusal(`task #${t.id} is already ${t.state}`);
+      this.ready(t, true);
       if (this.checking.has(t.id)) {
         // The result goes only to the owner the check was started for: anyone who took the task since hears nothing.
-        throw new Error(this.checking.get(t.id) === t.owner ? `task #${t.id}: its check is still running; its result comes as a task message` : `task #${t.id}: a check from before it changed hands is still running; call hub_task_done again in a few minutes`);
+        throw new PreEffectToolRefusal(this.checking.get(t.id) === t.owner ? `task #${t.id}: its check is still running; its result comes as a task message` : `task #${t.id}: a check from before it changed hands is still running; call hub_task_done again in a few minutes`);
       }
       return t;
     };
@@ -1306,10 +1333,10 @@ export class Tasks {
 
   async review(by: PeerId, id: unknown, verdict: unknown, note?: string, unmet?: unknown): Promise<Task> {
     const valid = (): Task => {
-      const t = this.need(id);
-      this.mine(t, by, "reviewer");
-      if (verdict !== "approved" && verdict !== "changes_requested") throw new Error('verdict must be "approved" or "changes_requested"');
-      if (t.state !== "in_review") throw new Error(`task #${t.id} is ${t.state}: cannot move to ${verdict} before its owner calls hub_task_done`);
+      const t = this.need(id, false, true);
+      this.mine(t, by, "reviewer", true);
+      if (verdict !== "approved" && verdict !== "changes_requested") throw new PreEffectToolRefusal('verdict must be "approved" or "changes_requested"');
+      if (t.state !== "in_review") throw new PreEffectToolRefusal(`task #${t.id} is ${t.state}: cannot move to ${verdict} before its owner calls hub_task_done`);
       return t;
     };
     const items = textList(unmet);
@@ -1352,8 +1379,8 @@ export class Tasks {
   }
 
   /** Task-level escalation: the next attached peer in the class's escalate_to takes over, with the history. */
-  async escalate(by: PeerId, id: unknown, why = "by hand", reason: TaskMoveReason | undefined = by === HUB ? undefined : "manual"): Promise<Task> {
-    let task = this.need(id, true);
+  async escalate(by: PeerId, id: unknown, why = "by hand", reason: TaskMoveReason | undefined = by === HUB ? undefined : "manual", preEffect = false): Promise<Task> {
+    let task = this.need(id, true, preEffect);
     const list = this.d.routing().classes[task.class]?.escalate_to ?? [];
     if (task.state === "changes_requested") task = this.d.board.update(task.id, HUB, "reopened", { state: "in_progress" });
     const from = task.owner;
@@ -1372,8 +1399,8 @@ export class Tasks {
   }
 
   /** Caller authority is checked by the daemon; keep the real actor in task history. */
-  async assignTo(id: unknown, peer: PeerId, by: PeerId = USER): Promise<Task> {
-    const task = this.need(id, true);
+  async assignTo(id: unknown, peer: PeerId, by: PeerId = USER, preEffect = false): Promise<Task> {
+    const task = this.need(id, true, preEffect);
     // Work that waits is handed to nobody yet (issue #207): the peer becomes its reserved owner instead.
     if (!this.waitsFor(task).length) return this.assignOwner(task, by, { candidates: [peer], event: "reassigned", reason: "manual", override: by === USER });
     const next = this.d.board.update(task.id, by, "reserved", { reserved: peer }, `for ${peer}`, { reason: "manual" });

package/src/hub/tool-refusal.ts

@@ -0,0 +1,7 @@
+/** A hub guard proved this request was refused before any task or board effect (screen telemetry is allowed). Never wrap arbitrary failures in this type. */
+export class PreEffectToolRefusal extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PreEffectToolRefusal";
+  }
+}

package/src/hub/ui.ts

@@ -1,3 +1,4 @@
+import { taskProgress } from "../ui/task-progress.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
@@ -20,7 +21,9 @@ export function startDashboard(options: DashboardOptions) {
   const now = options.now ?? Date.now;
   const tickets = new Map<string, number>();
   const sessions = new Map<string, number>();
-  const html = readFileSync(new URL("../ui/index.html", import.meta.url), "utf8");
+  // Inject the same pure public-board model used by the console before computing CSP hashes.
+  const html = readFileSync(new URL("../ui/index.html", import.meta.url), "utf8")
+    .replace("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`);
   const hashes = (tag: string) => [...html.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g"))]
     .map((m) => `'sha256-${createHash("sha256").update(m[1]!).digest("base64")}'`).join(" ");
   const headers = {

package/src/local/tools.ts

@@ -1,7 +1,8 @@
 import { lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
-import { hasSegment, isDenied } from "./deny.ts";
+import { isHubWritePath } from "../hub/permission-mode.ts";
+import { isDenied } from "./deny.ts";
 import { OUTPUT_CAP, sandboxedExec } from "./sandbox.ts";
 
 export { isDenied };
@@ -17,14 +18,11 @@ export interface ToolContext {
   /** Turn cancellation signal, including the execution-budget wall cap. */
   signal?: AbortSignal;
   /** Ask the console. Resolves false on deny or timeout. */
-  permit: (title: string) => Promise<boolean>;
+  permit: (title: string, tool?: string, signal?: AbortSignal, path?: string) => Promise<boolean>;
   /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
   send: (text: string, to?: string[]) => string;
 }
 
-/** Not secret, but writing them changes what runs outside the worker's control. */
-const WRITE_DENY_SEGMENTS = [".git", ".agenthub"];
-
 const lexists = (p: string) => {
   try {
     lstatSync(p);
@@ -52,7 +50,9 @@ export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string,
   const rel = relative(root, real);
   if (rel.startsWith("..") || resolve(root, rel) !== real) throw new Error(`${path} is outside the project directory`);
   if (isDenied(rel, ctx.deny)) throw new Error(`${path} is on the secrets denylist`);
-  if (mode === "write" && WRITE_DENY_SEGMENTS.some((s) => hasSegment(rel, s))) throw new Error(`${path} is not writable by the local worker`);
+  // Not secret, but writing .git or .agenthub changes what runs outside the worker's control. Names are compared
+  // folded: a new `.GIT/config` is `.git/config` to a case-insensitive disk, and git then runs what it names.
+  if (mode === "write" && isHubWritePath(rel)) throw new Error(`${path} is not writable by the local worker`);
   return real;
 }
 
@@ -129,23 +129,27 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
       }
       case "write": {
         let file = guardPath(ctx, String(a.path), "write");
+        const approvedTarget = file;
         const content = String(a.content ?? "");
-        if (!(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`))) return "error: the user did not approve this write";
+        if (!(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file))) return "error: the user did not approve this write";
         if (ctx.signal?.aborted) return "error: turn cancelled before write";
         file = guardPath(ctx, String(a.path), "write");
+        if (file !== approvedTarget) return "error: path target changed during approval; inspect before retrying";
         mkdirSync(dirname(file), { recursive: true });
         writeFileSync(file, content);
         return `wrote ${a.path}`;
       }
       case "edit": {
         let file = guardPath(ctx, String(a.path), "write");
+        const approvedTarget = file;
         let text = readFileSync(file, "utf8");
         let count = text.split(String(a.old)).length - 1;
         if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
-        if (!(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`))) return "error: the user did not approve this edit";
+        if (!(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file))) return "error: the user did not approve this edit";
         if (ctx.signal?.aborted) return "error: turn cancelled before edit";
         // Approval can outlive another peer's edit or a path change. Apply only the approved fragment to current bytes.
         file = guardPath(ctx, String(a.path), "write");
+        if (file !== approvedTarget) return "error: path target changed during approval; inspect before retrying";
         text = readFileSync(file, "utf8");
         count = text.split(String(a.old)).length - 1;
         if (count !== 1) return `error: file changed during approval; \`old\` must match exactly once, it matched ${count} times`;
@@ -157,7 +161,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (!command.trim()) return "error: empty command";
         // The approver sees the whole command, not a prefix: what is hidden cannot be approved.
         if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
-        if (!(await ctx.permit(`bash: ${command}`))) return "error: the user did not approve this command";
+        if (!(await ctx.permit(`bash: ${command}`, "bash", ctx.signal))) return "error: the user did not approve this command";
         const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         return `${res.output}\n(exit ${res.code})`;
       }
@@ -167,7 +171,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (!GIT_READ.has(sub) && !GIT_WRITE.has(sub)) return `error: git ${sub} is not available to the local worker`;
         const problem = gitArgsProblem(args, ctx.deny);
         if (problem) return `error: git ${sub}: ${problem}`;
-        if (GIT_WRITE.has(sub) && !(await ctx.permit(`git ${args.join(" ")}`))) return "error: the user did not approve this git command";
+        if (GIT_WRITE.has(sub) && !(await ctx.permit(`git ${args.join(" ")}`, "git", ctx.signal))) return "error: the user did not approve this git command";
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
         const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         return `${res.output}\n(exit ${res.code})`;

package/src/pi/process-signature.ts

@@ -17,3 +17,26 @@ export function processSignature(pid: number): string | undefined {
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
   } catch { return undefined; }
 }
+
+export type Liveness = "live" | "gone" | "unknown";
+
+/**
+ * #226: the one ownership check behind every recorded pid (hub manifest, registry claim, recovery runner, manager
+ * owner, launcher records). With a recorded `signature` the identity decides: equal is live, different is gone (the
+ * pid was reused, after a reboot for example, also by a process we may not signal), and a pid that exists but whose
+ * identity cannot be read is unknown. Without one (records written by 0.12.20 and older) the pid probe answers as it
+ * always did: live, gone on ESRCH, unknown otherwise. Unknown is never gone.
+ */
+// ponytail: `ps lstart` is derived from boot time plus the process's age; a wall-clock step on Linux can change it for a
+// live process, which then reads as gone (a second hub could take its claim). Upgrade path: a boot-id or start-tick
+// (Linux /proc/<pid>/stat field 22) component in the signature.
+export function processLiveness(pid: unknown, signature?: string | null, identity: (pid: number) => string | undefined = processSignature): Liveness {
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return "unknown";
+  if (signature) {
+    let current: string | undefined;
+    try { current = identity(pid); } catch { /* unreadable: the pid probe below decides between gone and unknown */ }
+    if (current) return current === signature ? "live" : "gone";
+  }
+  try { process.kill(pid, 0); return signature ? "unknown" : "live"; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? "gone" : "unknown"; }
+}