@staix/agent-hub 0.12.45 → 0.13.0

package/src/hub/action-policy.ts

@@ -0,0 +1,106 @@
+import { ACTION_CLASSES, type ActionClass } from "./action-class.ts";
+import { sanitize } from "./envelope.ts";
+
+export interface ActionPolicyConfig { enabled: boolean; always_ask: ActionClass[]; budgets: Record<ActionClass, number> }
+const DEFAULT_BUDGETS: Record<ActionClass, number> = { publish: 1, destroy: 3, "external-write": 5, install: 2 };
+/** Defaults are host policy; overrides belong only in untracked config.local.json.
+ * ponytail: startup adopts that local policy without a retained person confirmation.
+ * Before adapter enforcement (#312/#313), bind weakened startup policy to person
+ * confirmation or surface it as attention; slice 1 never enforces these grants.
+ */
+export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
+  const fail = (): never => { throw new Error("action_policy: expected enabled, always_ask and class budgets (integers 0..1000)"); };
+  if (value === undefined) return { enabled: true, always_ask: [...ACTION_CLASSES], budgets: { ...DEFAULT_BUDGETS } };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail();
+  const raw = value as Record<string, unknown>;
+  if (Object.keys(raw).some(key => !["enabled", "always_ask", "budgets"].includes(key))) return fail();
+  if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") return fail();
+  const classes = raw.always_ask === undefined ? ACTION_CLASSES : raw.always_ask;
+  if (!Array.isArray(classes) || classes.length > ACTION_CLASSES.length || new Set(classes).size !== classes.length || classes.some(key => !ACTION_CLASSES.includes(key))) return fail();
+  const budgets = { ...DEFAULT_BUDGETS };
+  if (raw.budgets !== undefined) {
+    if (!raw.budgets || typeof raw.budgets !== "object" || Array.isArray(raw.budgets)) return fail();
+    for (const [key, amount] of Object.entries(raw.budgets)) {
+      if (!ACTION_CLASSES.includes(key as ActionClass) || typeof amount !== "number" || !Number.isSafeInteger(amount) || amount < 0 || amount > 1000) return fail();
+      budgets[key as ActionClass] = amount;
+    }
+  }
+  return { enabled: raw.enabled ?? true, always_ask: [...classes], budgets } as ActionPolicyConfig;
+}
+
+export interface ActionSessionBudget { readonly peer: string; readonly session: string }
+export interface ActionChallenge { readonly classes: readonly ActionClass[] }
+export type ActionDecision = { kind: "native" } | { kind: "ask"; classes: ActionClass[]; challenge?: ActionChallenge } | { kind: "budget"; classes: ActionClass[] };
+interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number> }
+const empty = (): Record<ActionClass, number> => ({ publish: 0, destroy: 0, "external-write": 0, install: 0 });
+/** Host-only ledger: session ids and policy come from current runtime ports, never a tool argument. */
+export class ActionBudgets {
+  private sessions = new Map<string, Session>();
+  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[] }>();
+  constructor(private readonly config: () => ActionPolicyConfig | undefined, private readonly currentSession: (peer: string) => string | undefined) {}
+  bindSession(peer: string, session: string): ActionSessionBudget | undefined {
+    if (!session || this.currentSession(peer) !== session) return undefined;
+    const previous = this.sessions.get(peer);
+    if (previous?.handle.session === session) return previous.handle;
+    const handle = Object.freeze({ peer, session });
+    this.sessions.set(peer, { handle, policy: "", remaining: empty() });
+    return handle;
+  }
+  revoke(peer: string): void { this.sessions.delete(peer); }
+  policyChanged(): void {
+    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); }
+    this.challenges = new WeakMap();
+  }
+  private current(handle: ActionSessionBudget | undefined): Session | undefined {
+    if (!handle) return undefined;
+    const state = this.sessions.get(handle.peer);
+    if (state?.handle !== handle || this.currentSession(handle.peer) !== handle.session) return undefined;
+    const policy = JSON.stringify(actionPolicyConfig(this.config()));
+    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); }
+    return state;
+  }
+  private selected(actions: readonly ActionClass[]): ActionClass[] {
+    const config = actionPolicyConfig(this.config());
+    return config.enabled ? ACTION_CLASSES.filter(key => actions.includes(key) && config.always_ask.includes(key)) : [];
+  }
+  /** A budget decision consumes every selected class atomically; native never grants permission. */
+  request(handle: ActionSessionBudget | undefined, actions: readonly ActionClass[]): ActionDecision {
+    const state = this.current(handle), classes = this.selected(actions);
+    if (!classes.length) return { kind: "native" };
+    if (!state) return { kind: "ask", classes };
+    if (classes.some(key => state.remaining[key] <= 0)) {
+      const challenge = Object.freeze({ classes: Object.freeze([...classes]) });
+      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes] });
+      return { kind: "ask", classes, challenge };
+    }
+    for (const key of classes) state.remaining[key]--;
+    return { kind: "budget", classes };
+  }
+  /** Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. */
+  approve(challenge: ActionChallenge | undefined): boolean {
+    if (!challenge) return false;
+    const grant = this.challenges.get(challenge); this.challenges.delete(challenge);
+    if (!grant) return false;
+    const state = this.current(grant.handle), config = actionPolicyConfig(this.config());
+    if (!state || state.policy !== grant.policy) return false;
+    for (const key of grant.classes) state.remaining[key] = Math.max(0, config.budgets[key] - 1);
+    return true;
+  }
+  /** Read-only projection: no session is created, rebound or reset by a status poll. */
+  status(peer: string, enforced: boolean) {
+    const config = actionPolicyConfig(this.config()), state = this.sessions.get(peer);
+    const bound = !!state && this.currentSession(peer) === state.handle.session && state.policy === JSON.stringify(config);
+    return { enabled: config.enabled, alwaysAsk: [...config.always_ask], limits: { ...config.budgets }, remaining: bound ? { ...state.remaining } : empty(), sessionBound: bound,
+      enforceable: enforced, note: !enforced ? `always-ask not enforceable: adapter integration pending${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled" };
+  }
+}
+
+/** Adapter integrations must pass the host's publicView and current command/private-turn screens. */
+export function actionApprovalText<T>(classes: readonly ActionClass[], command: string, task: T | undefined,
+  ports: { publicView(task: T): Record<string, unknown>; private: boolean; commandView(command: string): string | undefined }): string {
+  const view = task === undefined ? undefined : ports.publicView(task);
+  const title = typeof view?.title === "string" ? sanitize(view.title).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 160) : undefined;
+  const shown = ports.private ? undefined : ports.commandView(command);
+  const line = shown === undefined ? "[private command withheld]" : sanitize(shown).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 512);
+  return `Action approval (${ACTION_CLASSES.filter(key => classes.includes(key)).join(", ")})${title ? `; task ${title}` : ""}: ${line}`;
+}

package/src/hub/board.ts

@@ -1,3 +1,4 @@
+import { HOST_CODE_SYMBOLS, parseTaskCodeSymbols, type TaskCodeSymbols } from "./task-code-symbols.ts";
 import { planFingerprint } from "./plan-conformance.ts";
 import type { ReviewerPoolReason } from "./reviewer-pool.ts";
 import type { GitHubSource } from "./github-import.ts";
@@ -105,6 +106,8 @@ export interface Task extends PlanningFields {
   plan?: TaskPlan;
   /** Artifact identities and bounded evidence, owned by Tasks (#257). */
   sdlc?: SdlcReceipt;
+  /** Host-derived observation for one head, never accepted from task tool arguments. */
+  codeSymbols?: TaskCodeSymbols;
   /** Tasks that must be approved before this one is offered; planning edits are limited to unstarted backlog. */
   deps?: number[];
   /** Who routing offers the task first once nothing is left to wait for (issue #207); null when nobody was named. */
@@ -155,6 +158,8 @@ const MOVES: Record<TaskState, TaskState[]> = {
 };
 
 const JSON_COLS = ["refs", "plan", "deps", "signals", "history", "sdlc"] as const;
+// Separate storage keeps older SELECT * readers from exporting unscreened derived metadata.
+const TASK_SELECT = "SELECT tasks.*, (SELECT CASE WHEN length(CAST(payload AS BLOB)) <= 65536 THEN payload END FROM task_code_symbols WHERE task=tasks.id) AS code_symbols FROM tasks";
 
 /** Task board in `.agenthub/state/hub.db`. It outlives the hub process: `ahub kill` leaves the file. */
 export class Board {
@@ -225,6 +230,8 @@ export class Board {
     if (!have.has("external_issue")) this.db.run("ALTER TABLE tasks ADD COLUMN external_issue INTEGER");
     this.db.run("CREATE UNIQUE INDEX IF NOT EXISTS tasks_external_issue ON tasks(external_repo,external_issue) WHERE external_repo IS NOT NULL AND external_issue IS NOT NULL");
     if (!have.has("sdlc")) this.db.run("ALTER TABLE tasks ADD COLUMN sdlc TEXT");
+    this.db.run("CREATE TABLE IF NOT EXISTS task_code_symbols (task INTEGER PRIMARY KEY, payload TEXT NOT NULL)");
+    this.db.run("DELETE FROM task_code_symbols WHERE task NOT IN (SELECT id FROM tasks) OR task IN (SELECT id FROM tasks WHERE json_valid(signals) AND EXISTS (SELECT 1 FROM json_each(signals) WHERE value IN ('pii','pii_path')))");
     if (!have.has("task_role")) this.db.run("ALTER TABLE tasks ADD COLUMN task_role TEXT");
     if (!have.has("project_profile")) this.db.run("ALTER TABLE tasks ADD COLUMN project_profile TEXT");
     for (const col of ["rank", "priority", "release", "planned_start", "due"]) {
@@ -253,17 +260,17 @@ export class Board {
   }
 
   imported(repo: string, issue: number): Task | undefined {
-    const row = this.db.query("SELECT * FROM tasks WHERE external_repo=? AND external_issue=?").get(repo.toLowerCase(), issue) as Record<string, unknown> | null;
+    const row = this.db.query(`${TASK_SELECT} WHERE external_repo=? AND external_issue=?`).get(repo.toLowerCase(), issue) as Record<string, unknown> | null;
     return row ? parse(row) : undefined;
   }
 
   get(id: number): Task | undefined {
-    const row = this.db.query("SELECT * FROM tasks WHERE id = ?").get(id) as Record<string, unknown> | null;
+    const row = this.db.query(`${TASK_SELECT} WHERE id = ?`).get(id) as Record<string, unknown> | null;
     return row ? parse(row) : undefined;
   }
 
   list(state?: TaskState): Task[] {
-    const rows = state ? this.db.query("SELECT * FROM tasks WHERE state = ? ORDER BY id").all(state) : this.db.query("SELECT * FROM tasks ORDER BY id").all();
+    const rows = state ? this.db.query(`${TASK_SELECT} WHERE state = ? ORDER BY id`).all(state) : this.db.query(`${TASK_SELECT} ORDER BY id`).all();
     return (rows as Record<string, unknown>[]).map(parse);
   }
 
@@ -318,7 +325,7 @@ 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" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewFindings" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewFindings" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -328,6 +335,17 @@ export class Board {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
+    const headOf = (row: Task) => row.refs.commit ?? row.sdlc?.head ?? row.sdlc?.localHead;
+    const privateSymbols = next.signals.includes("pii") || next.signals.includes("pii_path");
+    if (Object.hasOwn(patch, "codeSymbols")) {
+      if (codeSymbolsAuthority !== HOST_CODE_SYMBOLS) throw new Error("code symbols require host authority");
+      const observation = patch.codeSymbols === undefined ? undefined : parseTaskCodeSymbols(patch.codeSymbols);
+      if (patch.codeSymbols !== undefined && !observation) throw new Error("invalid task code symbols");
+      if (observation && (privateSymbols || observation.head !== headOf(next))) throw new Error("code symbol head or privacy differs from task");
+      next.codeSymbols = observation;
+    } else if (privateSymbols || headOf(task) !== headOf(next) || task.refs.repo !== next.refs.repo || JSON.stringify(task.refs.paths) !== JSON.stringify(next.refs.paths) || task.sdlc?.repo !== next.sdlc?.repo) {
+      next.codeSymbols = undefined;
+    }
     if (next.state === "backlog" && (next.owner || next.reviewer)) throw new Error(`task #${id}: backlog cannot have an owner or reviewer`);
     if (!untouchedReturn) {
       if (patch.state === "backlog" && task.owner) throw new Error(`task #${id}: owned work cannot return to backlog`);
@@ -350,9 +368,15 @@ export class Board {
     const repositoryRefsChanged = patch.refs !== undefined && JSON.stringify([task.refs.repo, task.refs.paths]) !== JSON.stringify([next.refs.repo, next.refs.paths]);
     const departureInvalidated = extra.planDepartureInvalidated === true || hasDeparture && (planChanged || repositoryRefsChanged);
     const history = [...task.history, { at: Date.now(), by, event, ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("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.capacity === true ? { capacity: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}) }];
-    this.taskWrite(() => this.db
-      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, 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), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), id));
+    this.taskWrite(() => {
+      const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, 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), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), id);
+      if (result.changes) {
+        if (next.codeSymbols) this.db.query("INSERT INTO task_code_symbols(task,payload) VALUES(?,?) ON CONFLICT(task) DO UPDATE SET payload=excluded.payload").run(id, JSON.stringify(next.codeSymbols));
+        else this.db.query("DELETE FROM task_code_symbols WHERE task=?").run(id);
+      }
+      return result;
+    });
     const updated = this.get(id)!;
     this.changed(updated, history.at(-1)!);
     return updated;
@@ -431,7 +455,10 @@ export class Board {
       }
       if (this.list().some(task => task.id !== id && !ids.has(task.id) && (task.deps?.some(dep => ids.has(dep)) || task.sdlc?.phase?.tasks.some(ref => ids.has(ref.id) || ref.after.some(dep => ids.has(dep)))))) throw new Error("split children are referenced by other work");
       const restored = this.plan(id, by, { deps: entry!.planning!.previous.deps ?? [] }, revision, `undo split revision ${revision}`);
-      for (const child of ids) this.taskWrite(() => this.db.query("DELETE FROM tasks WHERE id=?").run(child));
+      for (const child of ids) this.taskWrite(() => {
+        this.db.query("DELETE FROM task_code_symbols WHERE task=?").run(child);
+        return this.db.query("DELETE FROM tasks WHERE id=?").run(child);
+      });
       return restored;
     });
   }
@@ -517,6 +544,14 @@ function parse(row: Record<string, unknown>): Task {
     if (col === "sdlc" && row[col] == null) delete out[col];
     else out[col] = JSON.parse(String(row[col]));
   }
+  try {
+    const rawSymbols = row.code_symbols == null ? undefined : String(row.code_symbols);
+    const symbols = rawSymbols === undefined || Buffer.byteLength(rawSymbols) > 64 * 1024 ? undefined : parseTaskCodeSymbols(JSON.parse(rawSymbols));
+    const head = (out.refs as TaskRefs).commit ?? (out.sdlc as SdlcReceipt | undefined)?.head ?? (out.sdlc as SdlcReceipt | undefined)?.localHead;
+    const privateSymbols = (out.signals as string[]).some(signal => signal === "pii" || signal === "pii_path");
+    if (symbols && symbols.head === head && !privateSymbols) out.codeSymbols = symbols;
+  } catch { /* Malformed optional derived evidence stays unavailable. */ }
+  delete out.code_symbols;
   if (out.project_profile != null) Object.assign(out, JSON.parse(String(out.project_profile)));
   delete out.project_profile;
   if (out.external_repo != null && out.external_issue != null) out.external = { provider: "github", repo: String(out.external_repo), issue: Number(out.external_issue), url: `https://github.com/${out.external_repo}/issues/${out.external_issue}` };

package/src/hub/budget.ts

@@ -49,6 +49,13 @@ export interface BudgetConfig {
 // wait_max_min is off here, as approvals.notify is: a project config turns it on (30 unless it says otherwise).
 export const DEFAULT_BUDGET: BudgetConfig = { gate: 0.9, stale_min: 30, poll_min: 10, checkpoint_timeout_s: 90, kimi_tokens_5h: 0, wait_max_min: 0 };
 
+export type BudgetLedgerEntry =
+  | { type: "budget_pause"; peer: PeerId; reason: string; window: string; resetsAt: number; by: "hub" | "person" }
+  | { type: "budget_resume"; peer: PeerId; reason: string; window: string; resetsAt: number; by: "hub" | "person" }
+  | { type: "quota_reset"; peer: PeerId; window: string; cause: "resets_at_moved" | "used_dropped"; resetsAt?: number; previousResetsAt?: number; used: number; previousUsed: number; measuredAt?: string };
+/** The window a pause record names: the id before ` window at` in its reason (`5h window at 93% (...)`), else unknown. */
+const reasonWindow = (reason: string): string => /^(\S+) window at /.exec(reason)?.[1] ?? "unknown";
+
 export interface BudgetHooks {
   /** Startup-bound project resolver; undefined keeps builtin-only compatibility. */
   definitionOf?(peer: PeerId): AdapterDefinition | undefined;
@@ -70,10 +77,23 @@ export interface BudgetHooks {
   resumed(record: PauseRecord): void;
   /** Every reading as it arrives, with the time it was measured (telemetry, issue #40). */
   reading?(peer: PeerId, windows: UsageWindow[], hard: boolean, at: number): void;
+  /**
+   * The limit ledger (#683 U1): a pause or resume of the account, and a window reset derived from its readings. Ids, windows and
+   * numbers only. Telemetry never costs a pause or a reading, so a throwing hook is ignored.
+   */
+  ledger?(entry: BudgetLedgerEntry): void;
   notify(line: string): void;
 }
 
 const HYSTERESIS = 0.1;
+/** A window whose `used` falls by this much inside one window id has been reset (#683 U1). */
+const RESET_DROP = 0.5;
+/**
+ * A provider's `resetsAt` for one window wobbles by seconds between readings (observed on the real log: 25 of 85 first-cut resets were jumps
+ * of 1 to 9 s with `used` unchanged, five more of about 10 min) while a real reset moves it by hours (the smallest of the 53 real ones: 2.4 h).
+ * A forward move of this much or less is the same window, not a reset (#683 U1).
+ */
+const RESET_JITTER_MS = 15 * 60_000;
 /** Mark a pause whose handoff was a wait, and one whose wait was undone, in its reason (issue #36). */
 const WAIT_NOTE = "; keeps its work:";
 const WAITED_NOTE = "; waited, then the reset moved to";
@@ -90,6 +110,10 @@ export class Budget {
   private readonly readings = new Map<PeerId, Map<string, Reading>>();
   private readonly pausing = new Map<PeerId, object>();
   private readonly handingOff = new Set<PeerId>();
+  /** The last reading of each window of an account, for the derived `quota_reset` (see `deriveResets`). */
+  private readonly lastSeen = new Map<PeerId, Map<string, { used: number; resetsAt?: number; at: number }>>();
+  /** `peer|window|resetsAt` of every reset already written this run, so a duplicate reading adds no reset. */
+  private readonly resetsRecorded = new Set<string>();
   /** `ahub budget resume`: the owner overrode a pause; readings over the gate are ignored for that peer until then. */
   private readonly ignoreUntil = new Map<PeerId, number>();
   /** Chosen fallback bounds belong to a window, never to every window of the peer. */
@@ -216,6 +240,7 @@ export class Budget {
       try { this.hooks.notify(`budget: ${peer} provider refused again; budget override ended`); } catch { /* a notice cannot prevent the hard pause */ }
     }
     try { this.hooks.reading?.(reporter, windows, hard, at); } catch { /* telemetry never costs a reading */ }
+    this.deriveResets(peer, windows, at);
     const mine = this.readings.get(peer) ?? new Map<string, Reading>();
     this.readings.set(peer, mine);
     for (const w of windows) mine.set(w.id, { ...w, used: Math.max(0, Math.min(1, w.used)), at });
@@ -230,6 +255,45 @@ export class Budget {
     return [...(this.readings.get(peer)?.values() ?? [])].filter((r) => this.now() - r.at <= staleMs && !(r.resetsAt && r.resetsAt <= this.now()));
   }
 
+  /**
+   * `quota_reset` (#683 U1), derived from two readings of one window id of the account: the window's `resetsAt` moved forward (a new
+   * window began, by more than RESET_JITTER_MS), or `used` fell by RESET_DROP or more inside one window id (the provider emptied it before its stated reset). The
+   * baseline is the last reading seen, kept apart from `readings` (a resume clears those) so a reset that ended a pause is still seen.
+   * One entry per peer, window and `resetsAt`: a repeated reading, a replay after a restart of the same value, or a second member of the
+   * account adds none. A stale file reading (`at` older than the baseline) never counts: it describes an earlier window.
+   */
+  private deriveResets(peer: PeerId, windows: UsageWindow[], at: number): void {
+    const last = this.lastSeen.get(peer) ?? new Map<string, { used: number; resetsAt?: number; at: number }>();
+    this.lastSeen.set(peer, last);
+    for (const w of windows) {
+      const used = Math.max(0, Math.min(1, w.used)), before = last.get(w.id);
+      if (before && at >= before.at) {
+        const moved = w.resetsAt !== undefined && before.resetsAt !== undefined && w.resetsAt - before.resetsAt > RESET_JITTER_MS;
+        const sameWindow = w.resetsAt === undefined || before.resetsAt === undefined || Math.abs(w.resetsAt - before.resetsAt) <= RESET_JITTER_MS;
+        const dropped = !moved && before.used - used >= RESET_DROP && sameWindow;
+        if (moved || dropped) {
+          const key = `${peer}|${w.id}|${w.resetsAt ?? "none"}`;
+          if (!this.resetsRecorded.has(key)) {
+            this.resetsRecorded.add(key);
+            this.writeLedger({ type: "quota_reset", peer, window: w.id, cause: moved ? "resets_at_moved" : "used_dropped", ...(w.resetsAt !== undefined ? { resetsAt: w.resetsAt } : {}),
+              ...(before.resetsAt !== undefined ? { previousResetsAt: before.resetsAt } : {}), used, previousUsed: before.used, ...(Math.abs(this.now() - at) > 60_000 ? { measuredAt: new Date(at).toISOString() } : {}) });
+          }
+        }
+      }
+      if (!before || at >= before.at) last.set(w.id, { used, ...(w.resetsAt !== undefined ? { resetsAt: w.resetsAt } : {}), at });
+    }
+  }
+
+  /** The resets already in the ledger from earlier hub runs, so a replayed reading adds none (the daemon reads them from events.jsonl). */
+  seedResets(known: Iterable<{ peer: PeerId; window: string; resetsAt?: number }>): void {
+    for (const r of known) this.resetsRecorded.add(`${r.peer}|${r.window}|${r.resetsAt ?? "none"}`);
+  }
+
+  /** One ledger entry; a failing hook never costs the pause, the resume or the reading it describes. */
+  private writeLedger(entry: BudgetLedgerEntry): void {
+    try { this.hooks.ledger?.(entry); } catch { /* telemetry */ }
+  }
+
   /** The owner's override: lift the pause now and leave the peer alone until the window that caused it has reset. */
   override(peer: PeerId): boolean {
     peer = this.account(peer);
@@ -237,7 +301,7 @@ export class Budget {
     if (!open) return false;
     this.ignoreUntil.set(peer, open.resetsAt);
     const bounds = this.resetBounds.get(peer);
-    this.resume(peer, "overridden by the console user");
+    this.resume(peer, "overridden by the console user", "person");
     // A new refusal may end the override before this same window has reset.
     if (bounds) this.resetBounds.set(peer, bounds);
     return true;
@@ -298,6 +362,10 @@ export class Budget {
       if (this.recoveryHeld) { this.deferred = true; return; }
       if (this.closed) return; // the hub is shutting down: nothing is recorded, the next run sees the reading again
       this.db.query("INSERT OR REPLACE INTO budget_pauses (peer, since, resets_at, reason, summary, moved) VALUES (?, ?, ?, ?, ?, ?)").run(peer, this.now(), resetsAt, reason, summary ?? null, JSON.stringify(open?.moved ?? []));
+      // A new pause that replaces an expired record (its window reset while nobody was attached to be resumed) ends that pause: without this
+      // the ledger would hold two open pauses for one peer, and a pause-duration timeline would be wrong (#683 U1).
+      if (open) this.writeLedger({ type: "budget_resume", peer, reason: "replaced by a new pause after its window reset", window: reasonWindow(open.reason), resetsAt: open.resetsAt, by: "hub" });
+      this.writeLedger({ type: "budget_pause", peer, reason, window: worst.id, resetsAt, by: "hub" });
       this.hooks.pause(peer);
       this.hooks.notify(`budget: ${peer} paused, ${reason}; resumes ${new Date(resetsAt).toLocaleTimeString()}${summary ? "; checkpoint received" : hard ? "; hard limit, no checkpoint" : "; no checkpoint"}`);
       await this.finishHandoff(peer, summary);
@@ -371,11 +439,12 @@ export class Budget {
     }
   }
 
-  private resume(peer: PeerId, why: string): void {
+  private resume(peer: PeerId, why: string, by: "hub" | "person" = "hub"): void {
     peer = this.account(peer);
     const record = this.record(peer);
     if (!record) return;
     this.db.query("DELETE FROM budget_pauses WHERE peer = ?").run(peer);
+    this.writeLedger({ type: "budget_resume", peer, reason: why, window: reasonWindow(record.reason), resetsAt: record.resetsAt, by });
     this.readings.get(peer)?.clear(); // the old numbers describe the window that just ended
     this.resetBounds.delete(peer);
     // The notice is queued while the peer is still paused, so it leads the first delivery: the peer learns what moved

package/src/hub/bus.ts

@@ -1,4 +1,4 @@
-import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
+import { appendNote, DIGEST, frame, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
 import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
 import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
@@ -103,6 +103,9 @@ const MAX_ATTEMPTS = 3;
 // ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
 // Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
 const DIGEST_MAX = 10;
+// #713: a pull-only peer reads between steps, often minutes apart, so one pull drains its queue up to this many bytes of rendered text instead of ten items.
+// Bounded, not unbounded: a queue larger than the budget takes more than one pull, and the reply says how many are still waiting. Push peers keep DIGEST_MAX.
+const PULL_BUDGET_BYTES = 64 * 1024;
 const NOTES_KEPT = 10;
 
 /**
@@ -479,7 +482,11 @@ export class Bus {
       return;
     }
     const recipientConsent = actor === `peer:${record.peer}` && action === "retry" && record.state === "needs_review";
-    if (["dispatching", "accepted"].includes(record.state) || (this.peers.get(record.peer)?.state === "busy" && !recipientConsent)) throw new Error("active delivery cannot be resolved");
+    // #713: a `queued` delivery was never handed to the peer, so nothing is in flight and a busy peer (a pull-only TUI is busy most of the time) does not block
+    // discarding it. `dispatching` and `accepted` stay refused, and every other resolution keeps the busy fence.
+    if (["dispatching", "accepted"].includes(record.state)) throw new Error("active delivery cannot be resolved");
+    const queuedDiscard = record.state === "queued" && action === "discard";
+    if (this.peers.get(record.peer)?.state === "busy" && !recipientConsent && !queuedDiscard) throw new Error("peer busy: its delivery cannot be resolved while it works");
     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");
@@ -907,6 +914,18 @@ export class Bus {
     if (this.withdrawn.has(env.id)) return;
     const queue = this.queues.get(id) ?? [];
     this.queues.set(id, queue);
+    // #713: a newer "task T is done, check your work" notice for this recipient replaces an earlier queued one for the same T: only the newest is useful, and the older
+    // one is discarded through the same stale/discard path with a journal outcome. Never one that already failed once or is being prepared, as for supervision.
+    const completedFor = env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.completedFor) ? env.refs!.completedFor : undefined;
+    if (!front && completedFor !== undefined) {
+      for (let i = queue.length - 1; i >= 0; i--) {
+        const old = queue[i]!;
+        if (old.from !== HUB || old.refs?.completedFor !== completedFor || this.attempts.has(`${id}:${old.id}`)) continue;
+        queue.splice(i, 1);
+        this.markWithdrawn(old.id);
+        this.discardQueued(id, old, `superseded completed-change notice for task #${completedFor}`);
+      }
+    }
     const key = env.from === HUB && env.refs?.supervision ? env.refs.supervisionKey : undefined;
     const replace = !front && key ? queue.findIndex((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`)) : -1;
     const preparing = !front && key ? this.preparing.get(id)?.find((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`) && !this.withdrawn.has(old.id)) : undefined;
@@ -1012,7 +1031,8 @@ export class Bus {
     const preface = this.prefaces.get(id);
     if (!preface && !queue.length) return [];
     const queued = [...queue];
-    const batch = [...(preface ? [preface] : []), ...this.take(id, queue)];
+    // A pull-only peer drains within a byte budget (oldest first, important ones marked as they always were); an attached channel session that pulls keeps one push's worth (#493).
+    const batch = [...(preface ? [preface] : []), ...(this.peers.get(id)?.pullOnly ? this.takeBudget(id, queue) : this.take(id, queue))];
     let out: Envelope[] = [];
     const deliveryId = crypto.randomUUID();
     try {
@@ -1158,6 +1178,26 @@ export class Bus {
     return batch;
   }
 
+  /**
+   * #713: what one pull hands a pull-only peer. Oldest first, so the oldest ordinary item is never kept behind newer important ones (the push order is important
+   * first; a pull is a catch-up). The budget counts each item's rendered bytes as the peer will read them (`frame`), and the first item always goes, so one huge
+   * envelope cannot stall the queue. An envelope that already failed once still goes alone, as in `take`.
+   */
+  private takeBudget(id: PeerId, queue: Envelope[]): Envelope[] {
+    const batch: Envelope[] = [];
+    let bytes = 0;
+    for (const env of queue) {
+      const failedBefore = this.attempts.has(`${id}:${env.id}`);
+      if (failedBefore && batch.length) break;
+      const size = Buffer.byteLength(frame(env)) + 2;
+      if (batch.length && bytes + size > PULL_BUDGET_BYTES) break;
+      batch.push(env); bytes += size;
+      if (failedBefore) break;
+    }
+    for (const env of batch) queue.splice(queue.indexOf(env), 1);
+    return batch;
+  }
+
   private arm(id: PeerId, ms: number): void {
     clearTimeout(this.timers.get(id));
     const timer = setTimeout(() => void this.drain(id), ms);

package/src/hub/checks.ts

@@ -1,4 +1,3 @@
-import { spawn } from "node:child_process";
 import { childEnv } from "./child-process.ts";
 
 export interface CheckResult {
@@ -10,24 +9,64 @@ export interface CheckResult {
   tail: string;
 }
 
+/** The part of a `Bun.spawn` child a check reads; tests substitute their own. */
+export interface CheckProcess {
+  pid: number;
+  /** Resolves with the exit code once the child is gone (128 + signal for a signalled child). */
+  exited: Promise<number>;
+  signalCode: string | null;
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+}
+export type CheckSpawn = (argv: string[], options: { cwd: string; env: NodeJS.ProcessEnv }) => CheckProcess;
+
+/**
+ * Why this is `Bun.spawn` and not `node:child_process` (#558): under `bun test` on a loaded macOS runner, node's spawn can
+ * reap a quick child inside `spawn()` itself and emit its exit and close events (and destroy its pipes, output unread)
+ * before any listener exists (oven-sh/bun#45483). The check then waited for events that had come already and returned a
+ * timeout, empty tail included, after its limit plus the kill grace. `Bun.spawn` hands over `exited` and the stream
+ * readers as values, so an early exit is still there to read. Measured under CPU load, one quick check per test file:
+ * node:child_process failed 9 of 300 rounds of 60 files, `Bun.spawn` 0 of 300.
+ */
+const bunSpawn: CheckSpawn = (argv, options) => Bun.spawn(argv, { cwd: options.cwd, env: options.env as Record<string, string>, stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true });
+
 const TAIL_LINES = 40;
 const TAIL_CHARS = 4000;
 const KEEP_CHARS = 64 * 1024;
 /** How long output may still arrive after the command exited; a descendant that left the group can hold the pipes. */
 const DRAIN_MS = 500;
-/** How long a killed check may wait for its exit and close events before it settles without them (#558). */
+/** How long a killed check may wait for its exit and its pipes before it settles without them (#558). */
 const KILL_GRACE_MS = 1000;
 
+/** The last lines of the output, capped by lines and characters: the one shape every result's tail has, a failed spawn's included. */
+const tailOf = (text: string): string => text.replace(/\s+$/, "").split("\n").slice(-TAIL_LINES).join("\n").slice(-TAIL_CHARS);
+
 /** Runs one check command in the project root, in its own process group so a timeout stops what it started. */
-export function runCheck(command: string, cwd: string, timeoutMs: number, running?: Set<() => void>, spawnChild: typeof spawn = spawn): Promise<CheckResult> {
+export function runCheck(command: string, cwd: string, timeoutMs: number, running?: Set<() => void>, spawnChild: CheckSpawn = bunSpawn): Promise<CheckResult> {
   return new Promise((resolve) => {
     let out = "";
     let timedOut = false;
     let interrupted = false;
     let settled = false;
     let exited = false;
-    const child = spawnChild("sh", ["-c", command], { cwd, env: childEnv(process.env), stdio: ["ignore", "pipe", "pipe"], detached: true });
+    const readers: { cancel(): Promise<unknown> }[] = [];
     let grace: ReturnType<typeof setTimeout> | undefined;
+    let drain: ReturnType<typeof setTimeout> | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let child: CheckProcess;
+    const stopListening = () => {
+      clearTimeout(timer);
+      clearTimeout(grace);
+      clearTimeout(drain);
+      for (const reader of readers) reader.cancel().catch(() => {});
+    };
+    const done = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      stopListening();
+      running?.delete(stop);
+      resolve({ code: timedOut || interrupted ? null : code, timedOut, ...(interrupted ? { interrupted } : {}), tail: tailOf(out) });
+    };
     const killGroup = () => {
       try {
         if (child.pid) process.kill(-child.pid, "SIGKILL");
@@ -35,51 +74,61 @@ export function runCheck(command: string, cwd: string, timeoutMs: number, runnin
         // already gone
       }
     };
-    /** A kill that is a verdict (timeout, hub stop) settles even if the child's events never come. */
+    /** A kill that is a verdict (timeout, hub stop) settles even if the child's exit and pipes never report. */
     const killAndSettle = () => {
       killGroup();
       grace ??= setTimeout(() => done(null), KILL_GRACE_MS);
     };
-    const stop = () => {
-      if (exited || settled) return; // finished before the hub stopped, or already settled: its result stands and the group may be reused
+    function stop() {
+      if (exited || settled) return; // finished in time or already settled: its result stands and the group may be reused
       interrupted = true;
       killAndSettle();
-    };
+    }
+    try {
+      child = spawnChild(["sh", "-c", command], { cwd, env: childEnv(process.env) });
+    } catch (e) {
+      resolve({ code: null, timedOut: false, tail: tailOf(e instanceof Error ? e.message : String(e)) });
+      return;
+    }
     running?.add(stop);
     const keep = (chunk: string) => {
       out += chunk;
       if (out.length > KEEP_CHARS) out = out.slice(-KEEP_CHARS);
     };
-    for (const s of [child.stdout, child.stderr]) {
-      s?.setEncoding("utf8"); // decodes across chunk edges, so Korean output is not cut into U+FFFD
-      s?.on("data", keep);
-    }
-    const timer = setTimeout(() => {
+    /** Reads one pipe to its end; resolves when it closes, or when `done` cancels it. */
+    const pump = (stream: ReadableStream<Uint8Array>): Promise<void> => {
+      const reader = stream.getReader();
+      readers.push(reader);
+      const decoder = new TextDecoder(); // decodes across chunk edges, so Korean output is not cut into U+FFFD
+      return (async () => {
+        try {
+          for (;;) {
+            const { value, done: ended } = await reader.read();
+            if (ended) break;
+            keep(decoder.decode(value, { stream: true }));
+          }
+          keep(decoder.decode());
+        } catch {
+          // cancelled or broken: what was read stands
+        }
+      })();
+    };
+    const pipes = Promise.all([pump(child.stdout), pump(child.stderr)]);
+    timer = setTimeout(() => {
       timedOut = true;
       killAndSettle();
     }, timeoutMs);
-    const done = (code: number | null) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      clearTimeout(grace);
-      running?.delete(stop);
-      child.stdout?.destroy();
-      child.stderr?.destroy();
-      const tail = out.replace(/\s+$/, "").split("\n").slice(-TAIL_LINES).join("\n").slice(-TAIL_CHARS);
-      resolve({ code: timedOut || interrupted ? null : code, timedOut, ...(interrupted ? { interrupted } : {}), tail });
-    };
-    child.on("error", (e) => {
-      out += `\n${e.message}`;
-      done(null);
-    });
-    child.on("exit", (code) => {
+    child.exited.then((code) => {
       if (settled) return; // the kill grace settled it: the process group id is no longer ours to signal
       exited = true;
       clearTimeout(timer); // it finished in time; only its output may still be on the way
       killGroup(); // a background job it left behind (sh has no job control, so it is still in the group)
-      setTimeout(() => done(code), DRAIN_MS);
+      const result = child.signalCode ? null : code;
+      drain = setTimeout(() => done(result), DRAIN_MS);
+      void pipes.then(() => done(result)); // every pipe closed: nothing more is coming
+    }, (e: unknown) => {
+      out += `\n${e instanceof Error ? e.message : String(e)}`;
+      done(null);
     });
-    child.on("close", (code) => done(code));
   });
 }