@staix/agent-hub 0.8.1 → 0.9.0

package/src/hub/hub-tools.ts

@@ -35,11 +35,11 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 export const TASK_TOOLS: HubTool[] = [
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan }, ["id"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
-  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] } }),
+  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
@@ -49,7 +49,7 @@ export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 
 /** Role contracts, by role name. Shown to each peer for the roles `.agenthub/config.json` gives it. */
 export const ROLE_TEXT: Record<string, string> = {
-  planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs) instead of doing everything yourself.",
+  planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs, and after: [ids] for work that must wait for other tasks) instead of doing everything yourself.",
   implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs. With a claim or an accept, give a plan: the files, symbols and signatures you will change and where new code goes.",
   verifier: "verifier: run the checks a task names and report what passed and what did not in hub_task_done.",
   reviewer: "reviewer: when asked to review, read the change itself, then hub_review with approved or changes_requested and a note that says what to fix.",

package/src/hub/limits.ts

@@ -0,0 +1,71 @@
+import type { PeerId, Priority } from "./envelope.ts";
+
+/** Per-sender limits on what agents send (issue #38). 0 turns a limit off; the console user and the hub are never limited. */
+export interface LimitsConfig {
+  /** Messages a sender may send per minute, to anyone. */
+  sender_per_min: number;
+  /** Messages a sender may send per minute to one recipient (a broadcast counts as one recipient, `*`). */
+  pair_per_min: number;
+  /** `important` messages a sender may send per hour: each can interrupt a running turn. */
+  important_per_hour: number;
+  /** An identical message to the same recipients within this many seconds is dropped. */
+  repeat_window_s: number;
+}
+// Off here like approvals.notify, so tests and a hub without a config file are unlimited; the template turns it on.
+export const DEFAULT_LIMITS: LimitsConfig = { sender_per_min: 0, pair_per_min: 0, important_per_hour: 0, repeat_window_s: 0 };
+/** What a project config gets unless it says otherwise. */
+export const PROJECT_LIMITS: LimitsConfig = { sender_per_min: 12, pair_per_min: 6, important_per_hour: 6, repeat_window_s: 120 };
+
+interface Bucket {
+  tokens: number;
+  at: number;
+}
+
+/**
+ * Token buckets per sender, per (sender, recipient) and for `important`, plus repeat suppression. A refusal says why
+ * and when to retry, and costs no token: the sender learns at once instead of a queue filling up downstream.
+ */
+export class Limiter {
+  private readonly buckets = new Map<string, Bucket>();
+  private readonly recent = new Map<string, number>();
+
+  constructor(
+    private readonly cfg: LimitsConfig,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * undefined when the message may go; otherwise the reason, for the sender. `parent` is the id of what the message
+   * answers: "Yes." to two different questions is two messages, not a repeat.
+   */
+  admit(from: PeerId, to: PeerId[] | undefined, priority: Priority, body: string, parent = ""): string | undefined {
+    const now = this.now();
+    const audience = to?.length ? [...new Set(to)].sort() : ["*"];
+    const key = `${from}\0${audience.join(",")}\0${parent}\0${body.trim().replace(/\s+/g, " ")}`;
+    if (this.cfg.repeat_window_s > 0) {
+      const last = this.recent.get(key);
+      if (last !== undefined && now - last < this.cfg.repeat_window_s * 1000) {
+        return `the same message went to ${to?.length ? audience.join(", ") : "everyone"} ${Math.round((now - last) / 1000)} s ago`;
+      }
+      this.recent.set(key, now);
+      if (this.recent.size > 1000) for (const [k, at] of this.recent) if (now - at >= this.cfg.repeat_window_s * 1000) this.recent.delete(k);
+    }
+    const wanted: [string, number, number][] = []; // key, capacity, refill per ms
+    if (this.cfg.sender_per_min > 0) wanted.push([`s\0${from}`, this.cfg.sender_per_min, this.cfg.sender_per_min / 60_000]);
+    if (this.cfg.pair_per_min > 0) for (const r of audience) wanted.push([`p\0${from}\0${r}`, this.cfg.pair_per_min, this.cfg.pair_per_min / 60_000]);
+    if (priority === "important" && this.cfg.important_per_hour > 0) wanted.push([`i\0${from}`, this.cfg.important_per_hour, this.cfg.important_per_hour / 3_600_000]);
+    const filled = wanted.map(([key, cap, rate]) => {
+      const b = this.buckets.get(key) ?? { tokens: cap, at: now };
+      return { key, rate, b: { tokens: Math.min(cap, b.tokens + (now - b.at) * rate), at: now } };
+    });
+    const short = filled.filter((f) => f.b.tokens < 1);
+    if (short.length) {
+      const wait = Math.max(...short.map((f) => Math.ceil(Math.round((1 - f.b.tokens) / f.rate) / 1000))); // whole ms first: 1/(1/x) is not always x
+      if (this.cfg.repeat_window_s > 0) this.recent.delete(key); // refused, so not sent
+      const what = short.some((f) => f.key.startsWith("i\0")) ? "important messages" : "messages";
+      return `rate limited: too many ${what} from ${from}; retry after ${wait} s${what === "important messages" ? ", or send it without [IMPORTANT]" : ""}`;
+    }
+    for (const f of filled) this.buckets.set(f.key, { tokens: f.b.tokens - 1, at: now });
+    return undefined;
+  }
+}

package/src/hub/peers.ts

@@ -18,7 +18,7 @@ export interface PeerAdapter {
   start(): Promise<void>;
   stop(): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
-  onMessage?: (body: string, opts?: EnvelopeOpts) => void;
+  onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   /** Set by the bus. */
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
@@ -33,7 +33,8 @@ export const DEFAULT_WATCHDOG_MS = 300_000;
 
 /** State holder with a per-turn inactivity watchdog: a busy peer that goes silent is forced back to idle. */
 export abstract class BasePeer implements PeerAdapter {
-  onMessage?: (body: string, opts?: EnvelopeOpts) => void;
+  /** Returns a reason (a string) when the hub refused the message (issue #38). */
+  onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   onState?: (state: PeerState) => void;
   onFailed?: (envs: Envelope[]) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;

package/src/hub/report.ts

@@ -6,13 +6,15 @@ export interface Report {
   peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
   messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
   overlaps: { warnings: number; pairs: number };
+  /** Files one agent changed after another owner's open task had changed them (issue #32). */
+  conflicts: number;
   tasks: Record<string, number>;
   quota: { readings: number; hard: number };
 }
 
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
   const pairs = new Set<string>();
   const taskMessages = new Map<string, number>();
@@ -43,6 +45,9 @@ export function summarize(events: StampedEvent[]): Report {
         r.overlaps.warnings++;
         for (const o of e.others) pairs.add([e.task, o.task].sort((a, b) => a - b).join("-"));
         break;
+      case "conflict":
+        r.conflicts++;
+        break;
       case "quota":
         r.quota.readings++;
         if (e.hard) r.quota.hard++;
@@ -60,7 +65,7 @@ export function formatReport(r: Report): string[] {
   for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) lines.push(`peer ${id}: ${p.turns} turn${p.turns === 1 ? "" : "s"}, ${p.busyMinutes} busy minutes, ${p.tokens || "-"} tokens`);
   const dropped = Object.entries(r.messages.dropped).map(([k, n]) => `${n} ${k}`).join(", ");
   lines.push(`messages: ${r.messages.total} (dropped: ${dropped || "none"}; overflow ${r.messages.overflow}; undeliverable ${r.messages.undeliverable}); ${r.messages.perTask} per task that had any`);
-  lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}`);
+  lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}; edit conflicts: ${r.conflicts}`);
   const tasks = Object.entries(r.tasks).sort().map(([k, n]) => `${k} ${n}`).join(", ");
   lines.push(`task events: ${tasks || "none"}`);
   lines.push(`quota readings: ${r.quota.readings} (${r.quota.hard} hard limits)`);

package/src/hub/routing.ts

@@ -89,7 +89,7 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
   }
 }
 
-export type Signal = "pii" | "long_context";
+export type Signal = "pii" | "long_context" | "urgent";
 
 /** What the policy can see in a task. Context length is estimated from the referenced files, 3 characters per token as elsewhere. */
 export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, routing: Routing, cwd: string): Signal[] {
@@ -125,10 +125,22 @@ export function assign(
   task: Pick<Task, "class" | "signals">,
   states: Record<PeerId, PeerState>,
   routing: Routing,
-  opts: { exclude?: PeerId[]; candidates?: PeerId[]; notReviewer?: PeerId } = {},
+  opts: {
+    exclude?: PeerId[];
+    candidates?: PeerId[];
+    notReviewer?: PeerId;
+    waitsFor?: number[];
+    /** Quota per peer from its fresh readings, and the clock they are read against (issue #36). */
+    quota?: Record<PeerId, { headroom: number; resetsAt?: number }>;
+    now?: number;
+    /** Peers demoted for this task's class, with their recent failure weight (issue #36). */
+    demoted?: Record<PeerId, number>;
+  } = {},
 ): Assignment {
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
+  // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.
+  if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`] };
   const pii = task.signals.includes("pii") && routing.constraints.pii === "local_only";
 
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
@@ -148,6 +160,29 @@ export function assign(
     return undefined;
   };
 
+  /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
+  const drain = (p: PeerId): number | undefined => {
+    const q = opts.quota?.[p];
+    return q?.resetsAt === undefined ? undefined : q.headroom / Math.max((q.resetsAt - (opts.now ?? 0)) / 3_600_000, 0.25);
+  };
+  /** Peers with readings swap places among themselves by drain rate; peers without (local, pi) keep theirs. */
+  const byDrain = (list: PeerId[]): PeerId[] => {
+    const slots = list.flatMap((p, i) => (drain(p) === undefined ? [] : [i]));
+    if (slots.length < 2) return list;
+    const sorted = slots.map((i) => list[i]!).sort((a, b) => drain(b)! - drain(a)!);
+    const out = [...list];
+    slots.forEach((i, k) => (out[i] = sorted[k]!));
+    const left = (p: PeerId) => `${p} ${Math.round(opts.quota![p]!.headroom * 100)}% left, resets in ${Math.max(0, Math.round((opts.quota![p]!.resetsAt! - (opts.now ?? 0)) / 60_000))} min`;
+    if (sorted.join() !== slots.map((i) => list[i]).join()) trace.push(`  quota first: ${sorted.map(left).join("; ")}`);
+    return out;
+  };
+  /** Demoted peers go behind the rest for this class (owners only); each group is then ordered by quota. */
+  const rank = (ok: PeerId[], role: "owner" | "reviewer"): PeerId[] => {
+    const down = role === "owner" ? ok.filter((p) => opts.demoted?.[p]) : [];
+    if (down.length) trace.push(`  demoted for ${task.class}: ${down.map((p) => `${p} (${opts.demoted![p]!.toFixed(1)} recent failures)`).join(", ")}`);
+    return [...byDrain(ok.filter((p) => !down.includes(p))), ...byDrain(down)];
+  };
+
   const pick = (list: PeerId[], role: "owner" | "reviewer", not?: PeerId): PeerId | undefined => {
     const ok: PeerId[] = [];
     for (const peer of list) {
@@ -155,9 +190,11 @@ export function assign(
       trace.push(`  ${role} candidate ${peer}: ${why ? `skipped, ${why}` : states[peer]}`);
       if (!why) ok.push(peer);
     }
-    const localTier = ok.filter((p) => p === LOCAL || p === PI);
+    const ranked = rank(ok, role);
+    // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
+    const localTier = ranked.filter((p) => (p === LOCAL || p === PI) && !(role === "owner" && opts.demoted?.[p]));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
-    return ok.find((p) => states[p] === "idle") ?? ok[0];
+    return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
 
   // Never the task's current owner by default: a decline or an escalation has to reach the next peer in the list.

package/src/hub/snapshots.ts

@@ -1,9 +1,10 @@
 import { Database } from "bun:sqlite";
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { childEnv } from "./child-process.ts";
+import type { Touch } from "./conflicts.ts";
 
 /**
  * Per-turn workspace snapshots (issue #33): git tree objects written through a copy of the index, so the user's index
@@ -50,7 +51,15 @@ export function snapshot(repo: Repo): string | undefined {
   const tmp = mkdtempSync(join(tmpdir(), "ahub-snap-"));
   try {
     const env = { GIT_INDEX_FILE: join(tmp, "index") };
-    if (existsSync(join(repo.dir, "index"))) copyFileSync(join(repo.dir, "index"), env.GIT_INDEX_FILE);
+    const index = join(repo.dir, "index");
+    if (existsSync(index)) {
+      // git trusts an entry's stat only when the entry is older than the index file, and compares in whole seconds. A
+      // copy written now makes a same-size edit in the second the index was written look clean: keep the original's
+      // time. Taken before the copy, so an index replaced in between gives the copy an earlier time (safe), not later.
+      const { atime, mtime } = statSync(index);
+      copyFileSync(index, env.GIT_INDEX_FILE);
+      utimesSync(env.GIT_INDEX_FILE, atime, mtime);
+    }
     if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
     // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
     // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
@@ -141,6 +150,9 @@ export class Turns {
     // Opened by a starting hub: a turn still open was cut short when the last run stopped. It has no end snapshot, and
     // it may have run until now, so its window ends now (other turns that overlapped it stay unknowable).
     this.db.query("UPDATE turns SET ended = ? WHERE ended IS NULL").run(Date.now());
+    // ponytail: rows of finished tasks stay (a few per file per task); prune by task state if hub.db ever grows.
+    this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
+    this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
   }
   begin(id: string, peer: string, startTree: string | undefined): void {
     this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);
@@ -181,6 +193,21 @@ export class Turns {
     return { paths: [...new Set(known.flatMap((r) => JSON.parse(r.changed) as string[]))], unknown: [...rows.filter((r) => !known.includes(r)).map((r) => r.id), ...pruned] };
   }
 
+  /** Files a peer's turn changed while it owned `task` in progress (issue #32). */
+  touch(task: number, peer: string, paths: string[]): void {
+    const at = Date.now();
+    const q = this.db.query("INSERT OR REPLACE INTO touches (task, peer, path, at) VALUES (?, ?, ?, ?)");
+    this.db.transaction(() => { for (const p of paths) q.run(task, peer, p, at); })();
+  }
+  touchesFor(tasks: number[]): Touch[] {
+    if (!tasks.length) return [];
+    return this.db.query(`SELECT * FROM touches WHERE task IN (${tasks.map(() => "?").join(",")})`).all(...tasks) as Touch[];
+  }
+  /** Other peers with a turn that was open at some point since `since`: their changes may be in this turn's diff. */
+  busySince(peer: string, since: number): string[] {
+    return (this.db.query("SELECT DISTINCT peer FROM turns WHERE peer != ? AND (ended IS NULL OR ended >= ?) ORDER BY peer").all(peer, since) as { peer: string }[]).map((r) => r.peer);
+  }
+
   /** The latest turn of a peer: a conversation can only be reverted from its latest turn. */
   latest(peer: string): TurnRecord | undefined {
     return this.list(peer, 1)[0];

package/src/hub/tasks.ts

@@ -1,6 +1,6 @@
 import type { Briefs } from "../memory/brief.ts";
 import type { MemoryClient } from "../memory/client.ts";
-import { CLASSES, PLAN_KEYS, type Board, type Task, type TaskClass, type TaskPlan, type TaskRefs } from "./board.ts";
+import { CLASSES, OUTCOMES_KEPT_MS, PLAN_KEYS, type Board, type Task, type TaskClass, type TaskPlan, type TaskRefs } from "./board.ts";
 import type { Bus } from "./bus.ts";
 import { HUB, newEnvelope, NOTE_KINDS, noteLine, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
 import { assign, detectSignals, LOCAL, PI, type Assignment, type Routing } from "./routing.ts";
@@ -25,17 +25,24 @@ export interface TasksDeps {
   tell?: (peer: PeerId, line: string) => void;
   /** Structured overlap records for telemetry (issue #40); the notice line stays for the human. */
   recordOverlap?: (task: number, owner: PeerId, others: { task: number; owner: PeerId; paths: string[]; symbols?: string[] }[]) => void;
+  /** Quota per peer from fresh readings (issue #36): routing drains the windows that reset soonest first. */
+  quota?: () => Record<PeerId, { headroom: number; resetsAt?: number }>;
   /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
   triage?: { classify: (title: string, detail: string) => Promise<TaskClass | undefined>; onCampus: () => Promise<boolean> };
 }
 
 const ESCALATE_AFTER = 2;
+// Demotion (issue #36): a failure counts half after a day. A peer is demoted for a class once its decayed failures
+// reach 1.5 (two within about half a day, three within two days) and outweigh its decayed successes there.
+// ponytail: fixed constants; make them config when someone needs to tune them.
+const DEMOTION_HALF_LIFE_MS = 24 * 3_600_000;
+const DEMOTE_AT = 1.5;
 const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
 /** Board events that leave a task where its completion check found it; any other event means it moved on meanwhile. */
 const QUIET_EVENTS = new Set(["answer", "reviewer changed"]);
 
 /** Same path, or one is a directory of the other; the project root (`.`) holds everything. */
-const samePlace = (a: string, b: string) => {
+export const samePlace = (a: string, b: string) => {
   const norm = (p: string) => p.replace(/^\.\//, "").replace(/\/+$/, "") || ".";
   const [x, y] = [norm(a), norm(b)];
   return x === "." || y === "." || x === y || x.startsWith(`${y}/`) || y.startsWith(`${x}/`);
@@ -99,16 +106,57 @@ export class Tasks {
     return Object.fromEntries([...this.d.bus.peers.keys()].map((id) => [id, this.d.bus.stateOf(id)]));
   }
 
-  async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; refs?: TaskRefs; plan?: TaskPlan; owner?: PeerId }): Promise<Task> {
+  /** Dependencies of a task that are not approved yet: while there are any, it is offered to nobody (issue #34). */
+  waitsFor = (task: Pick<Task, "deps">): number[] => (task.deps ?? []).filter((id) => this.d.board.get(id)?.state !== "approved");
+
+  /** Decayed failure weights of the peers demoted for a class: failures count half after a day (issue #36). */
+  demoted(cls: TaskClass, now = Date.now()): Record<PeerId, number> {
+    const sums = new Map<PeerId, { bad: number; good: number }>();
+    for (const o of this.d.board.outcomes(cls, now - OUTCOMES_KEPT_MS)) {
+      const w = 0.5 ** ((now - o.at) / DEMOTION_HALF_LIFE_MS);
+      const s = sums.get(o.peer) ?? { bad: 0, good: 0 };
+      if (o.ok) s.good += w;
+      else s.bad += w;
+      sums.set(o.peer, s);
+    }
+    return Object.fromEntries([...sums].filter(([, s]) => s.bad >= DEMOTE_AT && s.bad > s.good).map(([p, s]) => [p, s.bad]));
+  }
+
+  /** What assignment weighs besides states and policy: quota and demotion. */
+  private weights(cls: TaskClass) {
+    const now = Date.now();
+    const quota = this.d.quota?.();
+    return { now, demoted: this.demoted(cls, now), ...(quota ? { quota } : {}) };
+  }
+
+  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");
+    // 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[] = [];
+    if (Array.isArray(input.after)) afterIds = input.after;
+    else if (input.after != null) afterIds = [input.after];
+    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 (!deps.includes(id)) deps.push(id);
+    }
+    const waits = this.waitsFor({ deps });
+    if (waits.length && input.owner) {
+      throw new Error(`this task would wait for ${waits.map((id) => `#${id}`).join(", ")}, not approved yet: ${input.owner === by ? "claim it once they are" : "propose it without an owner; routing offers it when they are approved"}`);
+    }
     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(", ")}`);
     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.
     const signals = detectSignals({ ...text, detail: [text.detail, planText(plan)].join("\n") }, this.d.routing(), this.d.cwd);
+    // Urgent work is handed over even when its paused owner's window resets soon (issue #36).
+    if (input.urgent === true && !signals.includes("urgent")) signals.push("urgent");
     let cls = given as TaskClass | undefined;
     let triaged = false;
     if (!cls && this.d.triage) {
@@ -122,10 +170,16 @@ export class Tasks {
     if (defaulted) cls = "implement";
     if (!cls) throw new Error(`class is required (one of ${CLASSES.join(", ")}); the hub could not name one for you`);
     const draft = { ...text, class: cls };
-    let task = this.d.board.propose(by, { ...draft, plan, signals });
+    let task = this.d.board.propose(by, { ...draft, plan, ...(deps.length ? { deps } : {}), signals });
     if (triaged) task = this.d.board.update(task.id, "hub", "triaged", {}, `class ${cls} named by the hub's model`);
     if (defaulted) task = this.d.board.update(task.id, "hub", "class defaulted", {}, "class implement for a claim without one");
     this.d.notify(`task ${this.publicTitle(task)} proposed by ${by} [${task.class}]${task.signals.length ? ` signals: ${task.signals.join(", ")}` : ""}`);
+    // Re-read: a dependency approved while triage was awaited looked for its dependents before this row existed.
+    const still = this.waitsFor(task);
+    if (still.length) {
+      this.d.notify(`task ${this.publicTitle(task)} waits for ${still.map((id) => `#${id}`).join(", ")}; it is offered once they are approved`);
+      return this.d.board.update(task.id, HUB, "blocked", {}, `waits for ${still.map((id) => `#${id}`).join(", ")}`);
+    }
     // Naming yourself is a claim: the work is already yours, so no offer comes back to you (paper: Agensh CLAIM, #68).
     return this.assignOwner(task, by, input.owner ? { candidates: [input.owner], claim: input.owner === by } : {});
   }
@@ -146,7 +200,7 @@ export class Tasks {
   private releasing: PeerId | undefined;
 
   /** Whether a model-written name may be shown to other peers and in the log: one matching a PII pattern may be PII. */
-  private nameable = (t: string): boolean => !this.isPii({ signals: detectSignals({ title: "", detail: t, refs: {} }, this.d.routing(), this.d.cwd) });
+  nameable = (t: string): boolean => !this.isPii({ signals: detectSignals({ title: "", detail: t, refs: {} }, this.d.routing(), this.d.cwd) });
 
   /** Where two tasks meet: shared paths, then shared symbols, leaving out any name that matches a PII pattern. */
   private where(hit: { paths: string[]; symbols: string[] }): string {
@@ -227,16 +281,21 @@ export class Tasks {
     if (typeof target === "number") {
       const task = this.d.board.get(target);
       if (!task) throw new Error(`no task #${target}`);
-      return [`task ${this.publicTitle(task)} (${task.state}, owner ${task.owner ?? "none"})`, "if it were assigned now:", ...assign(task, this.states(), routing, { exclude: this.declined(task) }).trace];
+      return [`task ${this.publicTitle(task)} (${task.state}, owner ${task.owner ?? "none"})`, "if it were assigned now:", ...assign(task, this.states(), routing, { exclude: this.declined(task), waitsFor: this.waitsFor(task), ...this.weights(task.class) }).trace];
     }
     const draft = { title: target.title, detail: target.detail ?? "", refs: target.refs ?? {} };
-    return assign({ class: target.class, signals: detectSignals(draft, routing, this.d.cwd) }, this.states(), routing).trace;
+    return assign({ class: target.class, signals: detectSignals(draft, routing, this.d.cwd) }, this.states(), routing, this.weights(target.class)).trace;
   }
 
   private declined = (task: Task) => task.history.filter((h) => h.event === "declined").map((h) => h.by);
 
   private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; event?: string; note?: string; clearOnFail?: boolean; exclude?: PeerId[]; context?: string; claim?: boolean } = {}): Promise<Task> {
-    const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}) });
+    const waits = this.waitsFor(task);
+    const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}), waitsFor: waits, ...this.weights(task.class) });
+    if (waits.length) {
+      this.d.notify(`task ${this.publicTitle(task)} waits for ${waits.map((id) => `#${id}`).join(", ")}; it is offered once they are approved`);
+      return task;
+    }
     if (!a.owner) {
       this.d.notify(`task ${this.publicTitle(task)}: no peer can take it (${a.trace.filter((l) => l.includes("skipped")).length} skipped); assign with: ahub task assign ${task.id} <peer>`);
       // Only a decline takes the task away from its owner; a failed console assign or escalation leaves it where it was.
@@ -278,6 +337,46 @@ export class Tasks {
     this.d.bus.publish(newEnvelope(HUB, body, { to: [task.owner!], kind: "task", priority: "important", refs: { ...task.refs, task: String(task.id) }, ...(pii ? { private: true } : {}) }));
   }
 
+  /** Nobody, the console user included, works on a task before what it waits for is approved. */
+  private ready(task: Task): 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`);
+  }
+
+  /** 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`);
+    }
+  }
+
+  private readonly offered = new Set<number>(); // ready tasks offered in this hub run
+
+  /**
+   * 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).
+   */
+  async releaseReady(): Promise<void> {
+    for (const t of this.d.board.list("proposed")) {
+      const last = t.history.at(-1)?.event;
+      if (!t.deps?.length || t.owner || this.offered.has(t.id) || (last !== "blocked" && last !== "ready") || this.waitsFor(t).length) continue;
+      if (!assign(t, this.states(), this.d.routing(), { exclude: this.declined(t) }).owner) continue; // nobody attached can take it yet
+      await this.offerReady(t, "nothing left to wait for");
+    }
+  }
+
+  /** 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}`));
+  }
+
   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`);
   }
@@ -297,6 +396,7 @@ export class Tasks {
   accept(by: PeerId, id: unknown, plan?: unknown): Task {
     const task = this.need(id);
     this.mine(task, by, "owner");
+    this.ready(task);
     // 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;
@@ -327,6 +427,9 @@ export class Tasks {
   /** Tasks whose check is queued or running, and the owner it was started for. */
   private readonly checking = new Map<number, PeerId | null>();
   private checkQueue: Promise<void> = Promise.resolve();
+  private pendingChecks = 0;
+  /** Checks queued or running, until their result is on the board: a recovery commit waits for them. */
+  checksPending = () => this.pendingChecks;
 
   /** Whether a completion check is still running for this task. */
   isChecking = (id: number) => this.checking.has(id);
@@ -335,6 +438,7 @@ export class Tasks {
     let task = this.need(id);
     this.mine(task, by, "owner");
     if (task.state === "in_review" || task.state === "approved") throw new Error(`task #${task.id} is already ${task.state}`);
+    this.ready(task);
     if (this.checking.has(task.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(task.id) === task.owner ? `task #${task.id}: its check is still running; its result comes as a task message` : `task #${task.id}: a check from before it changed hands is still running; call hub_task_done again in a few minutes`);
@@ -347,9 +451,11 @@ export class Tasks {
     const pending = this.d.board.update(task.id, by, "done (checking)", { refs: cleanRefs(refs) }, summary);
     this.d.notify(`task ${this.publicTitle(pending)} done by ${by}; its check is queued or running: ${command}`);
     const seen = { events: pending.history.length, owner: pending.owner };
+    this.pendingChecks++;
     this.checkQueue = this.checkQueue
       .then(() => this.finishChecked(pending.id, by, summary, command, seen))
-      .catch((e: Error) => this.d.notify(`task #${pending.id}: its check result could not be recorded: ${e.message}`));
+      .catch((e: Error) => this.d.notify(`task #${pending.id}: its check result could not be recorded: ${e.message}`))
+      .finally(() => this.pendingChecks--);
     return pending;
   }
 
@@ -375,6 +481,7 @@ export class Tasks {
       return;
     }
     this.d.board.update(id, HUB, "check failed", {}, `${outcome}\n${result.tail}`.trim());
+    if (task.owner) this.d.board.recordOutcome(task.owner, task.class, false);
     this.d.notify(`task ${this.publicTitle(task)}: its check failed (${outcome}); it stays with ${task.owner ?? by}`);
     this.tell(task, `Task #${id}: its check failed.\n$ ${outcome}${result.tail ? `\n${result.tail}` : ""}\nFix it and call hub_task_done again.`, pii);
   }
@@ -384,7 +491,11 @@ export class Tasks {
     const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", refs: cleanRefs(refs) }, checkOutput ? `${summary ?? ""}\n${checkOutput}`.trim() : summary);
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`);
     this.tellCompleted(next, summary);
-    if (!reviewer) this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
+    if (!reviewer) {
+      if (next.owner) this.d.board.recordOutcome(next.owner, next.class, true); // approved without a review is a success too
+      this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
+      await this.releaseDependents(next);
+    }
     else if (reviewer === USER) this.d.notify(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
     else this.sendReview(next, reviewer);
     return next;
@@ -432,11 +543,14 @@ export class Tasks {
     const pii = this.isPii(task);
     if (verdict === "approved") {
       const next = this.d.board.update(task.id, by, "approved", { state: "approved", rejections: 0 }, note);
+      if (next.owner) this.d.board.recordOutcome(next.owner, next.class, true);
       this.note(next, by, "decision", `Task #${next.id} approved by ${by}: ${next.title}\n${note ?? ""}`);
       this.tell(next, `Task #${next.id} approved by ${by}.${note ? ` ${note}` : ""}`, pii);
+      await this.releaseDependents(next);
       return next;
     }
     const rejected = this.d.board.update(task.id, by, "changes_requested", { state: "changes_requested", rejections: task.rejections + 1 }, note);
+    if (rejected.owner) this.d.board.recordOutcome(rejected.owner, rejected.class, false);
     this.note(rejected, by, "decision", `Task #${rejected.id} changes requested by ${by}: ${rejected.title}\n${note ?? ""}`);
     if (rejected.rejections >= ESCALATE_AFTER) {
       const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`);
@@ -456,6 +570,9 @@ export class Tasks {
     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;
+    // The hub's own escalations are not counted: after repeated changes_requested each one already was, and after a
+    // Pi inference failure the backend failed, not the work. An escalation by hand counts on its own.
+    if (from && by !== HUB) this.d.board.recordOutcome(from, task.class, false);
     const next = await this.assignOwner(task, by, { candidates: list, event: "escalated", note: `${why}; from ${from ?? "none"}`, context: why });
     if (next.owner && next.owner !== from) {
       this.d.notify(`task ${this.publicTitle(next)} escalated from ${from} to ${next.owner} (${why})`);
@@ -474,10 +591,12 @@ export class Tasks {
    * Budget relay: a paused peer's open work moves on. `local` first (it has no quota), then the class list, all through
    * the usual constraints. Tasks it was reviewing get another reviewer. Moves are reported, never taken back automatically.
    */
-  async reassignForPause(peer: PeerId, context: string | undefined): Promise<{ id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]> {
+  async reassignForPause(peer: PeerId, context: string | undefined, urgentOnly = false): Promise<{ id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]> {
     const moved: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[] = [];
     const routing = this.d.routing();
     for (const task of this.d.board.list()) {
+      // Waiting out a window that resets soon (issue #36): only urgent work moves.
+      if (urgentOnly && !task.signals.includes("urgent")) continue;
       if (task.owner === peer && OPEN.includes(task.state)) {
         const pii = this.isPii(task);
         const candidates = [pii ? LOCAL : PI, pii ? undefined : LOCAL, ...(routing.classes[task.class]?.peers ?? []).filter((p) => p !== LOCAL && p !== PI)].filter((p): p is PeerId => !!p);
@@ -486,7 +605,7 @@ export class Tasks {
         moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner, role: "owner" });
       } else if (task.reviewer === peer && task.state !== "approved") {
         // No owner candidates: only the reviewer is wanted, and it must be neither the paused peer nor the task's owner.
-        const a = assign(task, this.states(), routing, { exclude: [peer], candidates: [], ...(task.owner ? { notReviewer: task.owner } : {}) });
+        const a = assign(task, this.states(), routing, { exclude: [peer], candidates: [], ...(task.owner ? { notReviewer: task.owner } : {}), ...this.weights(task.class) });
         const reviewer = a.reviewer && a.reviewer !== peer && a.reviewer !== task.owner ? a.reviewer : null;
         const next = this.d.board.update(task.id, HUB, "reviewer changed", { reviewer }, `budget pause of ${peer}`);
         moved.push({ id: task.id, title: this.publicTitle(task), to: reviewer, role: "reviewer" });

package/templates/claude-hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "ahub check-path --hook", "timeout": 10 }]
+      }
+    ]
+  }
+}

package/templates/config.json

@@ -14,7 +14,7 @@
     "local": ["implementer", "verifier"],
     "pi": ["implementer", "verifier"]
   },
-  "budget": { "gate": 0.9, "stale_min": 30, "poll_min": 10, "checkpoint_timeout_s": 90, "kimi_tokens_5h": 0 },
+  "budget": { "gate": 0.9, "stale_min": 30, "poll_min": 10, "checkpoint_timeout_s": 90, "kimi_tokens_5h": 0, "wait_max_min": 30 },
   "inference": { "enabled": true, "digest_min_items": 5, "digest_min_chars": 8000, "triage": true },
   "omniroute": {
     "urls": [],
@@ -27,5 +27,6 @@
   "approvals": { "timeout_s": 120 },
   "tasks": { "release_after_min": 30 },
   "checks": { "timeout_s": 600 },
-  "snapshots": { "enabled": true, "keep": 20 }
+  "snapshots": { "enabled": true, "keep": 20 },
+  "limits": { "sender_per_min": 12, "pair_per_min": 6, "important_per_hour": 6, "repeat_window_s": 120 }
 }