@staix/agent-hub 0.12.29 → 0.12.31

package/src/hub/memory-staleness.ts

@@ -0,0 +1,55 @@
+import { lstatSync, type Stats } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { nodePath } from "@staix/agent-mem";
+import { isDenied } from "../local/deny.ts";
+import { foldSegment } from "./permission-mode.ts";
+import { matchesPolicyLexically } from "./path-policy.ts";
+
+export const STALENESS_MAX_PROBES = 32;
+export interface StalenessOptions {
+  cwd: string;
+  privatePaths?: string[];
+  deny?: string[];
+  /** A metadata-only seam for privacy and budget regressions. */
+  probe?: (path: string) => Pick<Stats, "isSymbolicLink" | "isDirectory">;
+}
+
+/** One call-scoped budget/cache, shared by every displayed note. Unknown never produces a marker. */
+export function createStalenessProbe(options: StalenessOptions): (about: readonly string[]) => boolean {
+  const root = resolve(options.cwd), cache = new Map<string, boolean>();
+  let remaining = STALENESS_MAX_PROBES;
+  const allowed = (path: string) => {
+    const name = relative(root, resolve(root, path));
+    return !isDenied(name, options.deny) && !isDenied(foldSegment(name), options.deny?.map(foldSegment))
+      && !matchesPolicyLexically(root, name, [...(options.privatePaths ?? []), ...(options.deny ?? [])]);
+  };
+  const missing = (path: string): boolean => {
+    if (cache.has(path)) return cache.get(path)!;
+    cache.set(path, false);
+    if (!path || path.length > 4096 || isAbsolute(path) || /[\0\r\n]/.test(path) || path.split("/").includes("..") || !allowed(path)) return false;
+    const target = resolve(root, path), rel = relative(root, target);
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) return false;
+    let current = root;
+    // ponytail: private/deny exclusion assumes a tree not modified during this call. A concurrent ancestor swap
+    // by a process running as you can expose one existence bit and is outside docs/security.md's threat model.
+    // Descriptor-anchored no-follow traversal is needed before supporting adversarial concurrent tree mutation.
+    for (const component of rel.split("/")) {
+      current = join(current, component);
+      if (!remaining || !allowed(current)) return false;
+      remaining--;
+      try {
+        const stat = (options.probe ?? lstatSync)(current);
+        // Never follow even a publicly named alias: its target could be private.
+        if (stat.isSymbolicLink()) return false;
+        if (current !== target && !stat.isDirectory()) return false;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") { cache.set(path, true); return true; }
+        return false;
+      }
+    }
+    return false;
+  };
+  // ponytail: file-level only, so a symbol removed from an existing file is unknown. Add a policy-gated symbol
+  // resolver with its own C3 privacy/budget tests before inspecting source contents.
+  return about => about.some(node => { const path = nodePath(node); return path !== undefined && missing(path); });
+}

package/src/hub/path-policy.ts

@@ -147,6 +147,14 @@ function globScope(root: string, lexical: string, actual: string, path: string,
   };
   return visit(root, start, 0, new Set());
 }
+/** Policy preflight without filesystem access. Callers must reject symlink traversal separately. */
+export function matchesPolicyLexically(cwd: string, path: string, paths: string[]): boolean {
+  const root = resolve(cwd), lexical = resolve(root, path);
+  return paths.some(entry => /[?*]/.test(entry)
+    ? patternScope(entry.split("/").filter(p => p && p !== "."), new Set([0]), relative(root, lexical), false)
+    : beneath(lexical, resolve(root, entry)));
+}
+
 /** Compare declared spelling, real targets and bounded aliases; legacy discovery errors fail closed. */
 export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false): boolean {
   if (!paths.length) return false;

package/src/hub/peer-catalog.ts

@@ -26,3 +26,6 @@ const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
 export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
   return Object.fromEntries(Object.entries(PEER_ROLES).filter(([peer]) => includeOptional || !(OPTIONAL_PEERS as readonly string[]).includes(peer)).map(([peer, roles]) => [peer, [...roles]]));
 }
+
+/** #455: who may hold the planner role, in the order automatic assignment tries them; the hub-sandboxed pi and local never plan. */
+export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;

package/src/hub/project.ts

@@ -1,43 +1,10 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { hubGitSync } from "./git.ts";
 
-const canonical = (path: string): string => {
-  const absolute = resolve(path);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    const parent = dirname(absolute);
-    return parent === absolute ? absolute : join(canonical(parent), basename(absolute));
-  }
-};
-
-export function canonicalPath(path: string): string {
-  return canonical(path);
-}
-
-/**
- * realpathSync, except that Bun (1.3.14, and 1.4.2 still: #121) throws ENOENT for an existing path containing a
- * backslash (issue #26). Such a path goes to the system realpath, which handles it and returns every component as
- * stored on disk: guardPath checks names, and on a case-insensitive disk `.GIT/config` or `id_rſa` would otherwise
- * pass for another file. A missing path or a dangling symlink still throws, which guardPath relies on. Other paths take
- * realpathSync's answer unchanged.
- */
-export function realPath(path: string): string {
-  try {
-    return realpathSync(path);
-  } catch (error) {
-    if (!resolve(path).includes("\\")) throw error; // a relative path can sit under a backslash directory too
-    // The path as given: resolve() would fold a `..` after a symlink by text. GNU realpath accepts a dangling last
-    // component unless told -e; the BSD one on macOS refuses it by default.
-    const argv = process.platform === "darwin" ? ["/bin/realpath", "--", path] : ["realpath", "-e", "--", path];
-    const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
-    if (r.status !== 0 || !r.stdout.endsWith("\n")) throw error;
-    return r.stdout.slice(0, -1);
-  }
-}
+import { canonicalPath as canonical } from "@staix/agent-mem/platform";
+export { canonicalPath, realPath } from "@staix/agent-mem/platform";
 
 function gitRoot(dir: string): string | undefined {
   const result = hubGitSync(["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });

package/src/hub/read-tools.ts

@@ -0,0 +1,127 @@
+import type { MemoryStore, View, Graph } from "@staix/agent-mem";
+import { looksSecret } from "@staix/agent-mem";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+
+export const MEMORY_READ_TOOLS = new Set(["hub_memory_search", "hub_memory_show", "hub_memory_graph"]);
+const REFUSAL = "memory read unavailable";
+const bytes = (v: string) => Buffer.byteLength(v, "utf8");
+const excerpt = (text: string, max = 200): string => {
+  if (bytes(text) <= max) return text;
+  const points = Array.from(text), marker = " [incomplete]";
+  let length = 0, out = "";
+  for (const point of points) { if (length + bytes(point) + bytes(marker) > max) break; out += point; length += bytes(point); }
+  return out + marker;
+};
+function reject(): never { throw new PreEffectToolRefusal(REFUSAL); }
+export type MemoryScreen = <T extends { title: string | null; text: string }>(rows: T[]) => T[];
+
+/** Validate before capability logging, storage, or privacy work. Schemas alone do not enforce tool input. */
+export function validateMemoryRead(op: string, a: Record<string, unknown>): void {
+  if (!a || typeof a !== "object" || Array.isArray(a)) reject();
+  const string = (v: unknown, min: number, max: number): v is string => typeof v === "string" && bytes(v) >= min && bytes(v) <= max;
+  const array = (v: unknown, min: number, max: number): v is string[] => Array.isArray(v) && v.length > 0 && v.length <= 8 && v.every(s => string(s, min, max));
+  const limit = (max: number) => a.limit === undefined || (Number.isInteger(a.limit) && Number(a.limit) >= 1 && Number(a.limit) <= max);
+  const keys = op === "hub_memory_search" ? ["query", "limit"] : op === "hub_memory_show" ? ["ids"] : ["starts", "hops", "limit"];
+  if (Object.keys(a).some(k => !keys.includes(k))) reject();
+  if (op === "hub_memory_search" ? !string(a.query, 0, 200) || !limit(20)
+    : op === "hub_memory_show" ? !array(a.ids, 6, 64)
+    : !array(a.starts, 1, 200) || (a.hops !== undefined && a.hops !== 1 && a.hops !== 2) || !limit(120)) reject();
+}
+
+/** Read-only model projection. Counts and caps are computed only after screening whole records and metadata. */
+export function memoryRead(store: MemoryStore | undefined, project: string, screen: MemoryScreen, op: string, a: Record<string, unknown>, stale: (about: readonly string[]) => boolean = () => false): string {
+  validateMemoryRead(op, a);
+  const safe = (v: unknown): boolean => {
+    try {
+      const text = typeof v === "string" ? v : JSON.stringify(v);
+      return !looksSecret(text) && screen([{ title: null, text }]).length === 1;
+    } catch { return false; }
+  };
+  if (!safe(a)) reject();
+  if (!store) return JSON.stringify({ error: REFUSAL });
+  try {
+    const all = screen(store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })).filter(safe);
+    const resolve = (input: string): View => {
+      const id = input.replace(/^mem:/, "");
+      const aliases = [...new Set(all.flatMap(v => [v.id, ...(v.promotedFrom ? [v.promotedFrom] : [])]))];
+      const matched = aliases.includes(id) ? [id] : aliases.filter(v => v.startsWith(id));
+      if (id.length < 6) reject();
+      if (!matched.length) {
+        // Older promotion chains are resolved by the store, but only a fully screened visible terminal is exposed.
+        const redirected = store.get(id, project);
+        const visible = redirected && all.find(v => v.id === redirected.id);
+        if (visible) return visible;
+        reject();
+      }
+      if (matched.length !== 1) reject();
+      const found = all.find(v => v.id === matched[0]) ?? all.find(v => v.promotedFrom === matched[0]);
+      if (!found) reject();
+      return found;
+    };
+    const finish = (v: unknown) => { if (!safe(v)) reject(); return JSON.stringify(v); };
+    const order = (x: View, y: View) => Number(y.kind === "fail") - Number(x.kind === "fail") || y.at.localeCompare(x.at) || x.id.localeCompare(y.id);
+    if (op !== "hub_memory_graph") {
+      const show = op === "hub_memory_show", cap = show ? 8192 : 4096;
+      const query = String(a.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+      const rows = show ? [...new Map((a.ids as string[]).map(id => { const v = resolve(id); return [v.id, v]; })).values()]
+        : all.filter(v => !v.supersededBy && query.every(q => `${v.title ?? ""} ${v.text} ${v.about.join(" ")}`.toLowerCase().includes(q))).sort(order);
+      const lines: string[] = [];
+      const render = () => ({ lines, truncated: rows.length - lines.length });
+      for (const v of rows) {
+        if (lines.length >= (show ? 8 : Number(a.limit ?? 8))) break;
+        const header = `mem:${v.id} ${v.kind} ${v.tier} source:${v.source} peer:${v.peer} project:${v.project} at:${v.at}: `.replace(/\s+/g, " ");
+        const body = `${show && stale(v.about) ? "(stale?) " : ""}${v.title ? `${v.title}: ` : ""}${v.text}`.replace(/\s+/g, " ").trim();
+        lines.push(header + body);
+        if (bytes(JSON.stringify(render())) > cap) {
+          const points = Array.from(body);
+          let low = 0, high = points.length;
+          while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            lines[lines.length - 1] = header + points.slice(0, mid).join("") + " [incomplete]";
+            if (bytes(JSON.stringify(render())) <= cap) low = mid; else high = mid - 1;
+          }
+          lines[lines.length - 1] = header + points.slice(0, low).join("") + " [incomplete]";
+          if (bytes(JSON.stringify(render())) > cap) lines.pop();
+        }
+      }
+      return finish(render());
+    }
+    const visible = new Map(all.map(v => [`mem:${v.id}`, v]));
+    const goals = new Map(store.goals(project).filter(safe).map(v => [`goal:${v.id}`, v]));
+    const starts = (a.starts as string[]).map(n => {
+      if (n.startsWith("mem:")) return `mem:${resolve(n).id}`;
+      if (n.startsWith("goal:") && !goals.has(n)) reject();
+      return n;
+    });
+    const nodes = new Map<string, Graph["nodes"][number]>(), edges = new Map<string, Graph["edges"][number]>();
+    for (const start of starts) {
+      const graph = store.graph(project, start, Number(a.hops ?? 1), Number.MAX_SAFE_INTEGER);
+      for (const n of graph.nodes) {
+        if ((n.id.startsWith("mem:") && !visible.has(n.id)) || (n.id.startsWith("goal:") && !goals.has(n.id))) continue;
+        const memory = visible.get(n.id), goal = goals.get(n.id);
+        // The dashboard graph already slices labels; model excerpts must retain a visible incompleteness marker.
+        const shown = { ...n, label: excerpt(memory ? memory.title ?? memory.text : goal ? goal.title : n.label) };
+        if (safe(shown)) nodes.set(n.id, shown);
+      }
+      for (const e of graph.edges) if (safe(e)) edges.set(JSON.stringify(e), e);
+    }
+    const screenedEdges = [...edges.values()].filter(e => nodes.has(e.from) && nodes.has(e.to));
+    const connected = new Set(screenedEdges.flatMap(e => [e.from, e.to]));
+    const rank = (n: Graph["nodes"][number]) => n.kind === "fail" ? 0 : starts.includes(n.id) ? 1 : n.type !== "memory" ? 2 : 3;
+    const eligibleNodes = [...nodes.values()].filter(n => connected.has(n.id) || starts.includes(n.id)).sort((x, y) => rank(x) - rank(y) || x.id.localeCompare(y.id));
+    const eligibleEdges = screenedEdges.sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
+    const out: Graph & { truncated: number } = { nodes: [], edges: [], truncated: eligibleNodes.length + eligibleEdges.length };
+    for (const n of eligibleNodes) {
+      if (out.nodes.length >= Number(a.limit ?? 60)) break;
+      out.nodes.push(n); out.truncated--;
+      if (bytes(JSON.stringify(out)) > (eligibleEdges.length ? 5120 : 6144)) { out.nodes.pop(); out.truncated++; }
+    }
+    const kept = new Set(out.nodes.map(n => n.id));
+    for (const e of eligibleEdges) {
+      if (!kept.has(e.from) || !kept.has(e.to) || out.edges.length >= 240) continue;
+      out.edges.push(e); out.truncated--;
+      if (bytes(JSON.stringify(out)) > 6144) { out.edges.pop(); out.truncated++; }
+    }
+    return finish(out);
+  } catch { return JSON.stringify({ error: REFUSAL }); }
+}

package/src/hub/routing.ts

@@ -1,6 +1,9 @@
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
+import { isGitHubRepository, specRefs } from "./spec-read.ts";
+
+export interface PeerCapabilities { tests: boolean; spec: boolean; testsReason?: string; specReason?: string; }
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -231,7 +234,10 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
+export type RoutingRefusalCode = "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
+  refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
   /** what `local` should ask for on this task: a Switchyard route id and the model to fall back to */
@@ -248,10 +254,12 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state">>,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: {
+    capabilities?: Record<PeerId, PeerCapabilities>;
+    repository?: string;
     exclude?: PeerId[];
     /** Owner admission limits do not remove otherwise eligible reviewers. */
     excludeOwners?: PeerId[];
@@ -280,6 +288,7 @@ export function assign(
     roles?: Record<string, string[]>;
   } = {},
 ): Assignment {
+  if (task.state === "cancelled" || task.state === "approved") return { trace: [`${task.state}: closed; not routed`] };
   if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
   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"}`];
@@ -292,29 +301,39 @@ export function assign(
   if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
   const pii = task.signals.includes("pii_path") || (task.signals.includes("pii") && routing.constraints.pii === "local_only");
 
+  let needsSpec = false;
+  if (!pii) try { needsSpec = specRefs({ title: task.title ?? "", detail: task.detail ?? "", refs: task.refs ?? {}, external: task.external }, opts.repository ?? "", { bareTitle: isGitHubRepository(opts.repository) }).length > 0; }
+  catch { needsSpec = true; } // an invalid/foreign reference never grants a sandboxed peer spec access
+  const needsTests = ["implement", "test", "bulk_edit"].includes(task.class);
+  const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
-    if (opts.offRoster?.includes(peer)) return "off roster";
+    const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
+    if (role === "owner" && opts.capabilities && !pii) {
+      const caps = peerEntry(opts.capabilities, peer);
+      if (needsTests && !caps?.tests) return deny("tests", `missing tests: ${caps?.testsReason ?? "capability unavailable"}`);
+      if (needsSpec && !caps?.spec) return deny("spec", `missing spec: ${caps?.specReason ?? "capability unavailable"}`);
+    }
+    if (opts.offRoster?.includes(peer)) return deny("roster", "off roster");
     const named = role === "owner" ? opts.namedOwner ?? reserved : opts.namedReviewer;
-    if (opts.pullOnly?.includes(peer) && named !== peer) return "pull-only: takes work when named or when it claims it";
-    if (!Object.hasOwn(states, peer)) return "not attached";
-    if (opts.exclude?.includes(peer)) return "excluded (declined or replaced)";
-    if (role === "owner" && opts.excludeOwners?.includes(peer)) return "owner admission: WIP or delivery hold";
-    if (states[peer] === "offline") return "offline";
-    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
+    if (opts.pullOnly?.includes(peer) && named !== peer) return deny("pull-only", "pull-only: takes work when named or when it claims it");
+    if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
+    if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
+    if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
+    if (states[peer] === "offline") return deny("offline", "offline");
+    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
-    if (failing) return `failing: ${failing}`;
-    if (pii && peer !== LOCAL) return "pii: on-prem peers only";
-    if (peer === LOCAL && policy?.local_allowed === false) return "local_allowed = false for this class";
-    if (peer === PI && policy?.local_allowed === false) return "local_allowed = false also excludes pi for this class";
+    if (failing) return deny("failing", `failing: ${failing}`);
+    if (pii && peer !== LOCAL) return deny("pii", "pii: on-prem peers only");
+    if (peer === LOCAL && policy?.local_allowed === false) return deny("policy", "local_allowed = false for this class");
+    if (peer === PI && policy?.local_allowed === false) return deny("policy", "local_allowed = false also excludes pi for this class");
     if (peer === PI && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
       const limit = backend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens;
-      if (routing.signals.long_context_tokens > limit) return `pi ${backend} capability limit ${limit} tokens`;
+      if (routing.signals.long_context_tokens > limit) return deny("policy", `pi ${backend} capability limit ${limit} tokens`);
     }
-    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return "long_context: skip local";
+    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
     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 = peerEntry(opts.quota, p);
@@ -396,7 +415,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner === LOCAL) trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner === PI) trace.push(`pi decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), trace };
+  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/settings.ts

@@ -1,4 +1,4 @@
-import { SUPPORTED_PEERS } from "./peer-catalog.ts";
+import { PLANNER_PEERS, SUPPORTED_PEERS } from "./peer-catalog.ts";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -46,6 +46,7 @@ const perClass = (name: TaskClass): SettingDef[] => [
 ];
 export const SETTINGS: readonly SettingDef[] = [
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "hub start", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  { key: "planner", group: "Roles", label: "Planner (the one peer that plans)", type: "enum", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "peer start", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),

package/src/hub/spec-read.ts

@@ -0,0 +1,120 @@
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { spawn } from "node:child_process";
+import { hostExecutable } from "./host-executable.ts";
+import type { Task } from "./board.ts";
+import { childEnv, stopOwnedProcess, trackGroup } from "./child-process.ts";
+
+const BODY_LIMIT = 64 * 1024, RESULT_LIMIT = 80 * 1024, STDOUT_LIMIT = 512 * 1024;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const bytes = (text: string) => Buffer.byteLength(text, "utf8");
+export interface SpecResult { number: number; title: string; state: string; updated_at: string; html_url: string; body: string; }
+/** PATH/shorter timeout are host-owned fixture seams, never tool inputs. */
+export interface SpecOptions { path?: string; timeoutMs?: number; projectDir?: string; }
+export interface FetchSpecOptions extends SpecOptions { screen: (whole: string) => boolean | Promise<boolean>; }
+/** Canonical owner/repo identity accepted by the fixed github.com fetch boundary. */
+export const isGitHubRepository = (repo: unknown): repo is string => typeof repo === "string" && REPO.test(repo);
+function validRepo(repo: string): void { if (!isGitHubRepository(repo)) throw new PreEffectToolRefusal("other repository"); }
+
+/** Resolve only task-bound issue references; foreign references never fall through to local #N. */
+export function specRefs(task: Pick<Task, "title" | "detail" | "refs"> & Partial<Pick<Task, "external">>, repo: string, options: { bareTitle?: boolean } = {}): number[] {
+  const references: { repo?: string; number: number }[] = [];
+  // Bare detail numbers name hub tasks. File paths are not issue references.
+  for (const section of [{ text: task.title, bare: true }, { text: task.detail, bare: false }]) {
+    for (const match of section.text.matchAll(/(?<![A-Za-z0-9_./-])(?:https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/issues\/([1-9][0-9]*)\b|([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)\b|#([1-9][0-9]*)\b)/g)) {
+      const qualified = match[1] ?? match[3];
+      if (!qualified && (!section.bare || options.bareTitle === false)) continue;
+      references.push({ repo: qualified, number: Number(match[2] ?? match[4] ?? match[5]) });
+    }
+  }
+  if (!references.length && task.external === undefined && !task.refs.repo) return [];
+  validRepo(repo);
+  if (task.refs.repo && task.refs.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+  const issues = new Set<number>();
+  if (task.external !== undefined) {
+    const source = task.external;
+    if (!source || source.provider !== "github" || typeof source.repo !== "string") throw new PreEffectToolRefusal("not found");
+    validRepo(source.repo);
+    if (source.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+    if (!Number.isSafeInteger(source.issue) || source.issue < 1 || typeof source.url !== "string"
+      || source.url.toLowerCase() !== `https://github.com/${repo}/issues/${source.issue}`.toLowerCase()) throw new PreEffectToolRefusal("not found");
+    issues.add(source.issue);
+  }
+  for (const reference of references) {
+    if (reference.repo && reference.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+    if (!Number.isSafeInteger(reference.number)) throw new PreEffectToolRefusal("not found");
+    issues.add(reference.number);
+    if (issues.size > 3) throw new PreEffectToolRefusal("too many spec references");
+  }
+  return [...issues];
+}
+
+interface GhResult { code: number; stdout: string; }
+/** One fixed-argv authenticated boundary, no shell, no retries and no retained stderr. */
+function gh(args: string[], opts: SpecOptions): Promise<GhResult> {
+  return new Promise((resolve, reject) => {
+    const env: NodeJS.ProcessEnv = { ...childEnv(), GH_HOST: "github.com", GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", ...(opts.path === undefined ? {} : { PATH: opts.path }) };
+    if (opts.path !== undefined) {
+      for (const key of ["GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"]) delete env[key];
+      env.GH_CONFIG_DIR = opts.path;
+    }
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(hostExecutable("gh", opts.projectDir ?? process.cwd(), opts.path ?? process.env.PATH), args, { env, detached: true, stdio: ["ignore", "pipe", "ignore"] });
+      trackGroup(child);
+    }
+    catch { reject(new Error("gh unavailable")); return; }
+    let output: Buffer[] = [], size = 0, failure: string | undefined;
+    const stop = (reason: string) => {
+      if (failure) return;
+      failure = reason; output = [];
+      void stopOwnedProcess(child, { group: true, termMs: 100, killMs: 500 }).catch(() => {});
+    };
+    const timeout = opts.timeoutMs === undefined || !Number.isFinite(opts.timeoutMs) ? 15_000 : Math.max(1, Math.min(15_000, opts.timeoutMs));
+    const timer = setTimeout(() => stop("timeout"), timeout);
+    child.stdout?.on("data", (chunk: Buffer) => {
+      if (failure) return;
+      size += chunk.length;
+      if (size > STDOUT_LIMIT) stop("too large"); else output.push(chunk);
+    });
+    child.once("error", () => { clearTimeout(timer); reject(new Error("gh unavailable")); });
+    child.once("close", code => {
+      clearTimeout(timer);
+      if (failure) reject(new Error(failure));
+      else resolve({ code: code ?? 1, stdout: Buffer.concat(output).toString("utf8") });
+    });
+  });
+}
+
+/** Startup-only availability evidence; daemon caches it until restart. */
+export async function specAvailable(opts: SpecOptions = {}): Promise<{ available: boolean; reason?: string }> {
+  try {
+    const result = await gh(["auth", "status", "--hostname", "github.com"], opts);
+    return result.code === 0 ? { available: true } : { available: false, reason: "gh unauthenticated" };
+  } catch (error) { return { available: false, reason: error instanceof Error ? error.message : "gh unavailable" }; }
+}
+
+export async function fetchSpec(repo: string, n: number, opts: FetchSpecOptions): Promise<SpecResult> {
+  validRepo(repo);
+  if (!Number.isSafeInteger(n) || n < 1) throw new PreEffectToolRefusal("not found");
+  const raw = await gh(["api", "-X", "GET", `repos/${repo}/issues/${n}`], opts);
+  let value: unknown;
+  try { value = JSON.parse(raw.stdout); } catch { throw new Error(raw.code === 4 ? "unauthenticated" : "not found"); }
+  if (raw.code !== 0) {
+    const status = (value as { status?: unknown })?.status;
+    throw new Error(raw.code === 4 || status === 401 ? "unauthenticated" : "not found");
+  }
+  if (!value || typeof value !== "object") throw new Error("not found");
+  const row = value as Record<string, unknown>;
+  if (typeof row.repository_url !== "string" || row.repository_url.toLowerCase() !== `https://api.github.com/repos/${repo}`.toLowerCase()
+    || typeof row.html_url !== "string" || ![`https://github.com/${repo}/issues/${n}`, `https://github.com/${repo}/pull/${n}`].some(url => row.html_url!.toString().toLowerCase() === url.toLowerCase())) throw new PreEffectToolRefusal("other repository");
+  if (row.number !== n || typeof row.title !== "string" || typeof row.state !== "string" || typeof row.updated_at !== "string" || (row.body !== null && typeof row.body !== "string")) throw new Error("not found");
+  const result: SpecResult = { number: n, title: row.title, state: row.state, updated_at: row.updated_at, html_url: row.html_url, body: row.body ?? "" };
+  // GET completed without task/check mutations; these explicit complete-contract refusals withhold only its result.
+  const length = bytes(result.body);
+  if (length > BODY_LIMIT) throw new PreEffectToolRefusal(`spec too large (${length} > 65536); ask the reviewer to put the contract in the repo`);
+  if (bytes(JSON.stringify(result)) > RESULT_LIMIT) throw new PreEffectToolRefusal("too large");
+  let allowed = false;
+  try { allowed = await opts.screen(`${result.title}\n${result.body}`); } catch { /* policy unavailable withholds the entire spec */ }
+  if (allowed !== true) throw new PreEffectToolRefusal("spec withheld by privacy policy");
+  return result;
+}

package/src/hub/supervision.ts

@@ -1,4 +1,4 @@
-import type { HistoryEntry, Task, TaskMoveReason } from "./board.ts";
+import { isClosedTaskState, type HistoryEntry, type Task, type TaskMoveReason, type TaskStall } from "./board.ts";
 import { sanitize, type Kind, type Priority } from "./envelope.ts";
 
 export type SupervisionScope = "own" | "all" | "off";
@@ -11,7 +11,7 @@ export interface SupervisionFields {
   check?: "passed" | "failed" | "unknown";
   verdict?: "approved" | "changes_requested";
   reason?: SupervisionReason;
-  sweep?: "unaccepted-assignment" | "idle-owner" | "review-pending";
+  sweep?: "unaccepted-assignment" | "idle-owner" | "review-pending" | "ready-unassigned";
 }
 export interface SupervisionNotice {
   peer: string;
@@ -102,13 +102,25 @@ export class SupervisionFeed {
     this.checkRound();
   }
 
+  /** Tasks owns durable cause/replan deduplication; the feed keeps its configured recipient and scope. */
+  taskStalled(stall: TaskStall): boolean {
+    const task = this.d.tasks().find(task => task.id === stall.task);
+    if (!task || isClosedTaskState(task.state) || !this.includes(task)) return false;
+    const cause = stall.cause;
+    const bits = [`#${stall.task}: stalled`, `cause ${cause.kind}`, `reason ${cause.code}`];
+    if (cause.peer) bits.push(`peer ${cause.peer}`);
+    if (cause.dependency !== undefined) bits.push(`dependency #${cause.dependency}`);
+    if (cause.refusals?.length) bits.push(`refusals ${cause.refusals.map(refusal => `${refusal.peer}:${refusal.code}`).join(", ")}`);
+    return this.send(`task:${stall.task}:stall`, bits.join("; "), "status", stall.task);
+  }
+
   peerOffline(peer: string): boolean {
-    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && !isClosedTaskState(t.state) && (t.owner === peer || t.reviewer === peer))) return false;
     return this.send(`peer:${peer}:offline`, `${peer}: offline`);
   }
 
   budgetPaused(peer: string, resetsAt?: number): boolean {
-    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && !isClosedTaskState(t.state) && (t.owner === peer || t.reviewer === peer))) return false;
     const resetDate = new Date(resetsAt ?? NaN);
     const reset = Number.isFinite(resetDate.getTime()) ? resetDate.toISOString() : "unknown";
     return this.send(`peer:${peer}:budget`, `${peer}: budget paused; reset ${reset}`, "status", undefined, "budget");
@@ -137,13 +149,16 @@ export class SupervisionFeed {
     const peer = this.recipient();
     if (!peer) return false;
     const tasks = this.d.tasks().filter((t) => this.includes(t));
-    if (!tasks.length || tasks.some((t) => t.state !== "approved")) return false;
+    if (!tasks.length || tasks.some((t) => !isClosedTaskState(t.state))) return false;
     const signature = tasks.map((t) => t.id).sort((a, b) => a - b).join(",");
     const previous = this.d.readRound?.(peer) ?? this.rounds.get(peer);
     const completed = new Set(previous?.split(",") ?? []);
     const newlyJoined = tasks.filter((t) => !completed.has(String(t.id)));
     if (!newlyJoined.length) return false;
-    const sent = this.send("round", `Supervision round complete: ${newlyJoined.length} task${newlyJoined.length === 1 ? "" : "s"} approved; report the results and open decisions to the person.`);
+    const count = `${newlyJoined.length} task${newlyJoined.length === 1 ? "" : "s"}`;
+    const cancelled = newlyJoined.filter(t => t.state === "cancelled").length;
+    const outcome = cancelled ? `${count} closed (${newlyJoined.length - cancelled} approved, ${cancelled} cancelled)` : `${count} approved`;
+    const sent = this.send("round", `Supervision round complete: ${outcome}; report the results and open decisions to the person.`);
     if (sent) {
       this.rounds.set(peer, signature);
       this.d.writeRound?.(peer, signature);

package/src/hub/task-sweep.ts

@@ -1,6 +1,6 @@
 import type { Task } from "./board.ts";
 
-export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending";
+export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending" | "ready-unassigned";
 export interface SweepRecord {
   kind: SweepKind;
   /** Index of the last real activity, distinguishing even events at the same time. */
@@ -14,11 +14,12 @@ export interface TaskSweepConfig {
   unaccepted_min: number;
   idle_min: number;
   review_min: number;
+  ready_min?: number;
   ladder_min: number;
   auto_reassign: boolean;
 }
 export const DEFAULT_TASK_SWEEP: TaskSweepConfig = {
-  enabled: false, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
+  enabled: false, ready_min: 60, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
 };
 
 /** Config cannot silently enable a sweep or reassignment through a truthy string. */
@@ -32,7 +33,7 @@ export function taskSweepConfig(input: unknown): TaskSweepConfig {
     if (typeof values[key] !== "boolean") throw new Error(`task_sweep.${key} must be a boolean`);
     out[key] = values[key];
   }
-  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ladder_min"] as const) {
+  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"] as const) {
     if (values[key] === undefined) continue;
     const value = values[key];
     if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value * (key === "interval_s" ? 1000 : 60_000) > 2_147_483_647) throw new Error(`task_sweep.${key} must be a bounded number of at least 1`);
@@ -42,16 +43,16 @@ export function taskSweepConfig(input: unknown): TaskSweepConfig {
 }
 
 /** Pure time/kind ladder; Tasks decides whether the responsible peer is available. */
-export function nextSweep(task: Task, config: TaskSweepConfig, now: number): SweepRecord | undefined {
+export function nextSweep(task: Task, config: TaskSweepConfig, now: number, ready = true): SweepRecord | undefined {
   if (!config.enabled || !Number.isFinite(now)) return undefined;
   const kind = task.state === "proposed" && task.owner ? "unaccepted-assignment"
     : task.state === "in_progress" && task.owner ? "idle-owner"
-      : task.state === "in_review" && task.reviewer ? "review-pending" : undefined;
+      : task.state === "in_review" && task.reviewer ? "review-pending" : task.state === "proposed" && !task.owner && !task.reviewer && ready ? "ready-unassigned" : undefined;
   if (!kind) return undefined;
   let activity = task.history.length - 1;
   while (activity >= 0 && (task.history[activity]?.sweep || task.history[activity]?.event === "memory reference started")) activity--;
   const at = task.history[activity]?.at ?? task.created;
-  const threshold = kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
+  const threshold = kind === "ready-unassigned" ? config.ready_min ?? 60 : kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
   if (now - at < threshold * 60_000) return undefined;
   const previous = task.history.flatMap((h) => h.sweep?.kind === kind && h.sweep.activity === activity ? [h.sweep] : []).at(-1);
   if (previous && (previous.step === 3 || now - previous.at < config.ladder_min * 60_000)) return undefined;