@staix/agent-hub 0.12.22 → 0.12.24

package/src/hub/path-policy.ts

@@ -0,0 +1,96 @@
+import { lstatSync, opendirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { realPath } from "./project.ts";
+/** Bounded project-relative exact paths/subtrees or *, ? and whole-segment ** globs. */
+export function policyPaths(raw: unknown, field: string): string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || raw.length > 64 || raw.some(p => typeof p !== "string" || !p || p.length > 200 || isAbsolute(p) || /[\[\]{}!]/.test(p) || /[\x00-\x1f\x7f]/.test(p) || p.split(/[\\/]/).includes("..") ||
+    (/[?*]/.test(p) && (p.includes("\\") || (p.match(/[?*]/g)?.length ?? 0) > 16 || p.split("/").some(s => s.includes("**") && s !== "**"))))) throw new Error(`${field} takes up to 64 bounded project-relative paths or *, ? and whole-segment ** globs`);
+  return [...new Set(raw.map(p => p.replace(/\/+/g, "/").replace(/\/$/, "") || "."))];
+}
+function existing(path: string): boolean { try { lstatSync(path); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; } }
+/** Resolve the deepest existing ancestor, retaining dangling links as failures. */
+export function policyRealPath(path: string): string {
+  let ancestor = path;
+  while (!existing(ancestor)) { const parent = dirname(ancestor); if (parent === ancestor) throw new Error("path cannot be resolved"); ancestor = parent; }
+  return join(realPath(ancestor), relative(ancestor, path));
+}
+const beneath = (path: string, root: string) => { path = path.toLowerCase(); root = root.toLowerCase(); return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep); };
+export function policyTargets(cwd: string, paths: string[]): string[] {
+  const root = realPath(cwd);
+  return [...new Set(paths.flatMap(path => { const lexical = resolve(root, path); return [lexical, policyRealPath(lexical)]; }))];
+}
+/** Linear-space wildcard DP, avoiding regex backtracking on untrusted paths. */
+function segmentMatches(pattern: string, name: string): boolean {
+  const chars = [...name.toLowerCase()];
+  let previous = new Array<boolean>(chars.length + 1).fill(false); previous[0] = true;
+  for (const char of pattern.toLowerCase()) {
+    const next = new Array<boolean>(chars.length + 1).fill(false);
+    next[0] = char === "*" && previous[0]!;
+    for (let i = 1; i <= chars.length; i++) next[i] = char === "*" ? previous[i]! || next[i - 1]! : previous[i - 1]! && (char === "?" || char === chars[i - 1]);
+    previous = next;
+  }
+  return previous[chars.length]!;
+}
+function closure(pattern: string[], states: Set<number>): Set<number> {
+  const out = new Set(states);
+  for (const i of out) if (pattern[i] === "**") out.add(i + 1);
+  return out;
+}
+function advance(pattern: string[], states: Set<number>, name: string): Set<number> {
+  const next = new Set<number>();
+  for (const i of closure(pattern, states)) {
+    if (pattern[i] === "**") next.add(i);
+    else if (pattern[i] !== undefined && segmentMatches(pattern[i]!, name)) next.add(i + 1);
+  }
+  return closure(pattern, next);
+}
+function patternScope(pattern: string[], states: Set<number>, path: string, includeParents: boolean): boolean {
+  if (isAbsolute(path) || path === ".." || path.startsWith("../")) return false;
+  states = closure(pattern, states);
+  if (states.has(pattern.length)) return true;
+  for (const name of path.split("/").filter(p => p && p !== ".")) {
+    states = advance(pattern, states, name);
+    if (states.has(pattern.length)) return true; // a matched directory protects its entire subtree
+    if (!states.size) return false;
+  }
+  return includeParents && states.size > 0; // this scope can contain a future protected descendant
+}
+/** Resolve wildcard directory aliases without trusting a cached expansion. Bound all filesystem discovery. */
+function globScope(root: string, lexical: string, actual: string, path: string, includeParents: boolean, budget: { entries: number }): boolean {
+  const pattern = path.split("/").filter(p => p && p !== ".");
+  const start = closure(pattern, new Set([0]));
+  if (patternScope(pattern, start, relative(root, lexical), includeParents) || patternScope(pattern, start, relative(root, actual), includeParents)) return true;
+  const visit = (dir: string, states: Set<number>, depth: number, ancestors: Set<string>): boolean => {
+    const real = policyRealPath(dir);
+    if (states.has(pattern.length)) return beneath(lexical, real) || beneath(actual, real) || includeParents && (beneath(real, lexical) || beneath(real, actual));
+    if (patternScope(pattern, states, relative(real, actual), includeParents)) return true;
+    if (!existing(dir)) return false;
+    if (!beneath(real, root)) throw new Error("policy glob discovery outside project");
+    const info = statSync(dir);
+    if (!info.isDirectory()) return false;
+    if (depth > 32 || ancestors.has(real) || budget.entries > 4096) throw new Error("policy glob discovery unavailable");
+    const chain = new Set(ancestors); chain.add(real);
+    const handle = opendirSync(dir);
+    try {
+      for (let entry = handle.readSync(); entry; entry = handle.readSync()) {
+        if (++budget.entries > 4096) throw new Error("policy glob discovery unavailable");
+        const next = advance(pattern, states, entry.name);
+        if (next.size && visit(join(dir, entry.name), next, depth + 1, chain)) return true;
+      }
+    } finally { handle.closeSync(); }
+    return false;
+  };
+  return visit(root, start, 0, new Set());
+}
+/** Compare declared spelling, real targets and wildcard aliases. Unknown discovery conservatively protects. */
+export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false): boolean {
+  if (!paths.length) return false;
+  try {
+    if (path.length > 4096) return true;
+    const root = realPath(cwd), lexical = resolve(root, path), actual = policyRealPath(lexical);
+    includeParents &&= !existing(lexical) || statSync(lexical).isDirectory();
+    const budget = { entries: 0 };
+    return paths.some(entry => /[?*]/.test(entry) ? globScope(root, lexical, actual, entry, includeParents, budget) : policyTargets(root, [entry]).some(target => beneath(lexical, target) || beneath(actual, target) || (includeParents && (beneath(target, lexical) || beneath(target, actual)))));
+  } catch { return true; }
+}

package/src/hub/peer-catalog.ts

@@ -0,0 +1,28 @@
+/** Native peers the hub knows; membership checks share this list. */
+export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+/** Optional production peers are added explicitly; legacy defaults remain stable. */
+export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
+export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
+export type KnownPeer = typeof SUPPORTED_PEERS[number];
+
+export const isKnownPeer = (value: unknown): value is KnownPeer =>
+  typeof value === "string" && (KNOWN_PEERS as readonly string[]).includes(value);
+
+export const isSupportedPeer = (value: unknown): value is KnownPeer =>
+  typeof value === "string" && (SUPPORTED_PEERS as readonly string[]).includes(value);
+
+// Policy metadata, not a membership list. Preserve DEFAULT_ROLES' existing key order.
+const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
+  claude: ["planner", "reviewer"],
+  codex: ["implementer"],
+  kimi: ["implementer", "verifier"],
+  local: ["implementer", "verifier"],
+  pi: ["implementer", "verifier"],
+  qwen: ["implementer", "verifier"],
+  jcode: ["implementer", "verifier"],
+};
+
+/** Each caller owns its role arrays; changing a project's defaults cannot change another's. */
+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]]));
+}

package/src/hub/peers.ts

@@ -4,6 +4,8 @@ export interface DeliveryReceipt {
   id: string;
   state: "accepted" | "completed" | "failed_safe" | "needs_review";
   reason?: string;
+  /** A provider refused before acceptance for quota; requeue without spending poison retries while paused. */
+  quota?: true;
 }
 
 export interface PeerAdapter {
@@ -24,7 +26,7 @@ export interface PeerAdapter {
   /** 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. */
-  onFailed?: (envs: Envelope[]) => void;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   /** Correlated durable-delivery lifecycle, emitted only when the bus supplied an id. */
   onDelivery?: (receipt: DeliveryReceipt) => void;
   /** Safe restart metadata only: ids and launch parameters, never prompt/message text. */
@@ -38,7 +40,7 @@ export abstract class BasePeer implements PeerAdapter {
   /** 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;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;
   private _state: PeerState = "offline";
   private timer: ReturnType<typeof setTimeout> | undefined;
@@ -77,7 +79,7 @@ export abstract class BasePeer implements PeerAdapter {
     this.onDelivery?.(receipt);
   }
 
-  private clearWatchdog(): void {
+  protected clearWatchdog(): void {
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
   }

package/src/hub/permission-mode.ts

@@ -1,25 +1,52 @@
+import { isSupportedPeer } from "./peer-catalog.ts";
 import { lstatSync } from "node:fs";
-import { isAbsolute, relative, sep } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 
 /** Operator-selected approval frequency; agent sandboxes remain separate. */
 export const PERMISSION_MODES = ["ask", "ask-when-needed", "never-ask"] as const;
 export type PermissionMode = typeof PERMISSION_MODES[number];
 export const KIMI_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "yolo", "never-ask": "auto" };
+export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
 export function permissionDefaults(value: unknown): Record<string, PermissionMode> {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("permission_modes must be an object with ask, ask-when-needed or never-ask values");
   const result: Record<string, PermissionMode> = {};
   for (const [peer, mode] of Object.entries(value)) {
-    if (!["claude", "codex", "kimi", "pi", "local"].includes(peer)) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (!isSupportedPeer(peer)) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (peer === "jcode") throw new Error("Jcode native policy is unmanaged; no hub permission_modes.jcode mapping exists");
     if (!isPermissionMode(mode)) throw new Error(`permission_modes.${peer} must be ask, ask-when-needed or never-ask`);
     result[peer] = mode;
   }
   return result;
 }
+/** Approval frequency does not create a common sandbox across native peers. */
+export function permissionBoundary(peer: string): string {
+  if (peer === "jcode") return "jcode: native policy unmanaged; NO hub sandbox; approvals belong to its native tools";
+  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
+  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
+  return `${peer}: runs its own tools; NO hub sandbox`;
+}
+/** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
+export function permissionGrant(peer: string, mode: PermissionMode): string {
+  if (peer === "jcode") return "no verified hub mode mapping; native policy only";
+  if (mode === "ask") return peer === "codex" ? "the session's own approval policy applies again" : peer === "kimi" ? "Kimi asks as it does on its own" : peer === "claude" ? "Claude's own permission rules decide" : "every write, edit and shell command asks";
+  if (peer === "qwen") return mode === "never-ask" ? "Qwen yolo approves every tool; NO hub sandbox" : "Qwen auto-edit approves file edits; shell commands ask; NO hub sandbox";
+  if (peer === "kimi") return mode === "never-ask" ? "Kimi's auto mode: nothing asks" : "Kimi's yolo mode: it asks only where it judges it must";
+  if (peer === "codex") return mode === "never-ask" ? "approval policy never on every turn: nothing asks" : "approval policy on-request on every turn";
+  if (peer === "claude") return mode === "never-ask" ? "every tool runs without asking" : "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules";
+  return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write and edit inside the project run without asking; shell and git writes still ask";
+}
 export const PI_EDIT_TOOLS = new Set(["edit", "write"]);
 /** Native agent policy files are never included in scoped automatic file grants. */
-export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".pi", ".mcp.json"]);
+export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".kimi-code", ".jcode", ".pi", ".mcp.json", ".agents", ".claude.json"]);
+export const INSTRUCTION_FILES: ReadonlySet<string> = new Set(["agents.md", "claude.md", "qwen.md"]);
+export const isInstructionPath = (path: string): boolean => path.split(/[\\/]/).some(segment => INSTRUCTION_FILES.has(foldSegment(segment)));
+export function instructionProtection(value: unknown): boolean {
+  if (value === undefined) return false;
+  if (typeof value !== "boolean") throw new Error("protect_instruction_files must be a boolean");
+  return value;
+}
 /**
  * One spelling per name, as a case-insensitive disk sees it: it opens `.mcp.j\u017Fon` (long s) as `.mcp.json`, and
  * HFS+ also ignores the default-ignorable code points (a zero-width joiner inside `.codex` is still `.codex`).
@@ -38,7 +65,8 @@ export function hardLinked(path: string): boolean {
  * inside the project, outside every agent's configuration, judged by the path within the project (a project that
  * itself lives under `.claude/worktrees/` is still a project), and not a hard link.
  */
-export function grantablePath(root: string, path: string): boolean {
+export function grantablePath(root: string, path: string, originalPath?: string, protectInstructions = false): boolean {
   const inside = relative(root, path);
-  return !!inside && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside) && !isAgentConfigPath(inside) && !isHubWritePath(inside) && !hardLinked(path);
+  const original = originalPath === undefined ? inside : relative(root, resolve(root, originalPath));
+  return !!inside && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside) && !isAgentConfigPath(inside) && !isHubWritePath(inside) && !isAgentConfigPath(original) && !isHubWritePath(original) && !(protectInstructions && (isInstructionPath(inside) || isInstructionPath(original))) && !hardLinked(path);
 }

package/src/hub/planning.ts

@@ -0,0 +1,70 @@
+import type { Task } from "./board.ts";
+
+export const BACKLOG_SPLIT_SCREEN_TIMEOUT_MS = 8000;
+
+export const PLANNING_FIELDS = ["rank", "priority", "release", "plannedStart", "due", "pinned", "deps", "reserved"] as const;
+export interface PlanningFields {
+  rank?: number | null;
+  priority?: number | null;
+  release?: number | null;
+  plannedStart?: number | null;
+  due?: number | null;
+  pinned?: boolean;
+  deps?: number[];
+  reserved?: string | null;
+}
+export interface PlanningPatch extends PlanningFields {}
+/** Machine-local capacity settings; ids never grant roster membership or authority. */
+export function planningWipLimits(input: unknown): Record<string, number> {
+  if (input === undefined) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length > 64) throw new Error("tasks.wip_limits must be a bounded peer map");
+  const limits: Record<string, number> = Object.create(null);
+  for (const [peer, value] of Object.entries(input)) {
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer) || typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 32) throw new Error("tasks.wip_limits needs peer ids and integer capacities 0..32");
+    limits[peer] = value;
+  }
+  return limits;
+}
+export const RELEASE_STATES = ["planning", "active", "frozen", "shipped", "dropped"] as const;
+export type ReleaseState = (typeof RELEASE_STATES)[number];
+export interface Release {
+  id: number; name: string; goal: string; order: number; state: ReleaseState;
+  plannedStart: number | null; cut: number | null; ship: number | null;
+  activatedAt: number | null; frozenAt: number | null; shippedAt: number | null;
+  created: number; updated: number; revision: number;
+}
+
+/** Validate the entire planning input before a write; actual dates are never caller input. */
+export function planningPatch(input: unknown): PlanningPatch {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("planning fields must be an object");
+  const fields = input as Record<string, unknown>;
+  if (!Object.keys(fields).length || Object.keys(fields).some(key => !(PLANNING_FIELDS as readonly string[]).includes(key))) throw new Error("unknown or empty planning fields");
+  const result: PlanningPatch = {};
+  for (const key of PLANNING_FIELDS) {
+    if (!Object.hasOwn(fields, key)) continue;
+    const value = fields[key];
+    if (key === "deps") {
+      if (!Array.isArray(value) || value.length > 64 || value.some(id => !Number.isSafeInteger(id) || id <= 0) || new Set(value).size !== value.length) throw new Error("deps must be at most 64 unique positive task ids");
+      result.deps = [...value];
+    } else if (key === "reserved") {
+      const peer = typeof value === "string" ? value.trim().toLowerCase() : null;
+      if (value !== null && (!peer || !/^[a-z][a-z0-9-]{0,31}$/.test(peer) || ["user", "hub", "digest"].includes(peer))) throw new Error("reserved must be a valid agent peer id or null");
+      result.reserved = peer;
+    } else if (key === "pinned") {
+      if (typeof value !== "boolean") throw new Error("pinned must be a boolean");
+      result.pinned = value;
+    } else {
+      if (value !== null && (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "release" || key === "plannedStart" || key === "due" ? 1 : 0) || (key === "priority" && value > 3) || (["plannedStart", "due"].includes(key) && value > 8_640_000_000_000_000))) throw new Error(`invalid planning field ${key}`);
+      result[key] = value as number | null;
+    }
+  }
+  return result;
+}
+
+/** Structured lifecycle events only, including reviewerless approval via done. */
+export function actualTaskDates(task: Pick<Task, "history" | "state" | "reviewer">) {
+  const first = (events: readonly string[]) => task.history.find(entry => events.includes(entry.event))?.at ?? null;
+  const approved = first(["approved"]), reviewed = task.reviewer !== null || task.history.some(entry => entry.event === "approved" || entry.event === "changes_requested");
+  const reviewerlessDone = task.state === "approved" && !task.reviewer ? [...task.history].reverse().find(entry => entry.event === "done")?.at ?? null : null;
+  return { startedAt: first(["accepted"]), reviewAt: reviewed ? first(["done"]) : null, doneAt: approved ?? reviewerlessDone };
+}

package/src/hub/profiles.ts

@@ -0,0 +1,74 @@
+import dev from "../../templates/profiles/dev.json";
+import research from "../../templates/profiles/research.json";
+import writing from "../../templates/profiles/writing.json";
+import general from "../../templates/profiles/general.json";
+import { ALL_PLAN_KEYS, CLASSES, type TaskClass } from "./board.ts";
+import { catalogAssignments } from "./roles.ts";
+import { sanitize } from "./envelope.ts";
+export const PROFILE_NAMES = ["dev", "research", "writing", "general"] as const;
+export type ProfileName = (typeof PROFILE_NAMES)[number];
+export interface ProjectProfile {
+  name: string; classes: Record<string, string>; plan_keys: string[]; role_text: Record<string, string>;
+  catalog_roles: Record<string, string[]>; agents: string; example_checks: string[];
+}
+const PROFILES: Record<ProfileName, ProjectProfile> = { dev, research, writing, general };
+export function profileName(raw: unknown): ProfileName {
+  if (raw === undefined) return "dev";
+  if (typeof raw !== "string" || !PROFILE_NAMES.includes(raw as ProfileName)) throw new Error(`profile must be one of ${PROFILE_NAMES.join(", ")}`);
+  return raw as ProfileName;
+}
+export const projectProfile = (raw?: unknown): ProjectProfile => PROFILES[profileName(raw)];
+export type ProfileSelection = ProfileName | ProjectProfile;
+export const profileData = (profile: ProfileSelection = "dev"): ProjectProfile => typeof profile === "string" ? projectProfile(profile) : profile;
+export function profileClass(raw: string, profile: ProfileSelection = "dev"): TaskClass {
+  const data = profileData(profile);
+  const base = typeof raw === "string" ? (Object.hasOwn(data.classes, raw) ? data.classes[raw] : Object.hasOwn(dev.classes, raw) ? (dev.classes as Record<string, string>)[raw] : undefined) : undefined;
+  if (!base) throw new Error(`class must be one of ${Object.keys(data.classes).join(", ")} (profile ${data.name}; existing base classes also accepted)`);
+  return base as TaskClass;
+}
+export const profileTaskLabel = (task: { class: string; profile?: string; profileClass?: string }) => task.profileClass ? `${task.profileClass} (base ${task.class}, ${task.profile})` : task.class;
+export const PROFILE_CLASS_NAMES = [...new Set(Object.values(PROFILES).flatMap(p => Object.keys(p.classes)))];
+
+/** Pure project data resolution. No mutation of shipped profiles or executable check defaults. */
+export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfile {
+  const original = projectProfile(raw);
+  if (overrides === undefined) return original;
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("profile_overrides must be an object");
+  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks"]);
+  if (Object.keys(data).some(key => !allowed.has(key))) throw new Error("unknown profile override field");
+  if (!Object.keys(data).length) return original;
+  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks] };
+  const text = (value: unknown, cap: number): string => { if (typeof value !== "string" || value.length > cap) throw new Error("profile text is missing or oversized"); return sanitize(value); };
+  if (data.classes !== undefined) {
+    if (!data.classes || typeof data.classes !== "object" || Array.isArray(data.classes) || Object.keys(data.classes).length > 32) throw new Error("profile classes must be a bounded base-class map");
+    for (const [name, base] of Object.entries(data.classes)) {
+      if (!/^[a-z][a-z0-9_]{0,47}$/.test(name) || typeof base !== "string" || !CLASSES.includes(base as TaskClass) || CLASSES.includes(name as TaskClass) && name !== base) throw new Error("profile class must retain an existing base-class meaning");
+      result.classes[name] = base;
+    }
+  }
+  if (data.plan_keys !== undefined) {
+    if (!Array.isArray(data.plan_keys) || !data.plan_keys.length || data.plan_keys.length > ALL_PLAN_KEYS.length || new Set(data.plan_keys).size !== data.plan_keys.length || data.plan_keys.some(key => !ALL_PLAN_KEYS.includes(key))) throw new Error("profile plan_keys must select distinct supported fields");
+    result.plan_keys = [...data.plan_keys];
+  }
+  if (data.role_text !== undefined) {
+    if (!data.role_text || typeof data.role_text !== "object" || Array.isArray(data.role_text) || Object.keys(data.role_text).length > 8) throw new Error("profile role_text must be bounded guidance");
+    for (const [role, value] of Object.entries(data.role_text)) {
+      if (!["planner", "implementer", "verifier", "reviewer", "conductor"].includes(role)) throw new Error("profile role_text must name an existing flow role");
+      result.role_text[role] = text(value, 2000);
+    }
+  }
+  if (data.catalog_roles !== undefined) result.catalog_roles = { ...result.catalog_roles, ...catalogAssignments(data.catalog_roles) };
+  if (data.agents !== undefined) result.agents = text(data.agents, 16000);
+  if (data.example_checks !== undefined) {
+    if (!Array.isArray(data.example_checks) || data.example_checks.length > 16) throw new Error("profile example_checks must be a bounded display list");
+    result.example_checks = data.example_checks.map(value => text(value, 2000));
+  }
+  return result;
+}
+
+/** Maps merge across shared/local layers; selections and display text replace as a unit. */
+export function mergeProfileOverrides(a: unknown, b: unknown): Record<string, unknown> | undefined {
+  if (a === undefined && b === undefined) return undefined;
+  const left = (a ?? {}) as Record<string, unknown>, right = (b ?? {}) as Record<string, unknown>;
+  return { ...left, ...right, ...Object.fromEntries(["classes", "role_text", "catalog_roles"].filter(key => left[key] !== undefined && right[key] !== undefined).map(key => [key, { ...(left[key] as object), ...(right[key] as object) }])) };
+}

package/src/hub/project.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { hubGitSync } from "./git.ts";
 
 const canonical = (path: string): string => {
   const absolute = resolve(path);
@@ -39,7 +40,7 @@ export function realPath(path: string): string {
 }
 
 function gitRoot(dir: string): string | undefined {
-  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const result = hubGitSync(["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
   if (result.status !== 0) return undefined;
   const root = result.stdout.trim();
   return root ? canonical(root) : undefined;

package/src/hub/projected-diff.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { hubGitSync } from "./git.ts";
+import { sanitize } from "./envelope.ts";
+import { foldSegment } from "./permission-mode.ts";
+import { isDenied } from "../local/deny.ts";
+import { MAX_PROJECTION_INPUT, type TextProjections } from "./text-projection.ts";
+import { repoGitArgs, repoGitEnv, type Repo } from "./snapshots.ts";
+
+export const PROJECTED_DIFF_BYTES = 12000;
+const MAX_FILES = 8, DIFF_MS = 8000;
+const HEADER = "Projected text only (authorship and raw restore safety are independent):";
+const treeId = (tree: string) => /^[a-f0-9]{40}$|^[a-f0-9]{64}$/.test(tree);
+export function projectionPath(repo: Repo, path: string, deny: string[] = []): boolean {
+  const parts = path.split("/"), folded = parts.map(foldSegment).join("/");
+  return !!path && !path.startsWith("/") && path.startsWith(repo.prefix) && parts.every(part => !!part && part !== "." && part !== ".." && ![".git", ".agenthub"].includes(foldSegment(part))) && !isDenied(path, deny) && !isDenied(folded, deny.map(foldSegment));
+}
+/** null is an absent file; undefined is unavailable evidence or a non-regular object. */
+export function snapshotBytes(repo: Repo, tree: string, path: string, deadline = performance.now() + DIFF_MS): Buffer | null | undefined {
+  if (!treeId(tree) || !projectionPath(repo, path) || performance.now() >= deadline) return undefined;
+  const run = (args: string[], encoding: "utf8" | "latin1" = "utf8", maxBuffer = 8192) => hubGitSync(repoGitArgs(repo, args), { encoding, maxBuffer, timeout: Math.ceil(Math.max(1, Math.min(DIFF_MS, deadline - performance.now()))), env: repoGitEnv(repo) });
+  const entry = run(["ls-tree", "-z", tree, "--", `:(literal)${path}`]);
+  if (entry.status !== 0) return undefined;
+  if (!entry.stdout) return null;
+  const match = /^(100644|100755) blob ([a-f0-9]+)\t/.exec(entry.stdout);
+  if (!match || entry.stdout.slice(match[0].length) !== path + "\0" || !treeId(match[2]!)) return undefined;
+  if (performance.now() >= deadline) return undefined;
+  const size = run(["cat-file", "-s", match[2]!]);
+  const length = Number(size.stdout.trim());
+  if (size.status !== 0 || !Number.isSafeInteger(length) || length < 0 || length > MAX_PROJECTION_INPUT || performance.now() >= deadline) return undefined;
+  // Latin1 preserves all byte values through the existing bounded git wrapper.
+  const blob = run(["cat-file", "blob", match[2]!], "latin1", MAX_PROJECTION_INPUT + 1);
+  if (blob.status !== 0 || blob.stdout.length !== length) return undefined;
+  return Buffer.from(blob.stdout, "latin1");
+}
+function hunks(repo: Repo, before: string, after: string, deadline: number): string | undefined {
+  if (performance.now() >= deadline) return undefined;
+  const scratch = mkdtempSync(join(tmpdir(), "ahub-projected-diff-"));
+  try {
+    const a = join(scratch, "before"), b = join(scratch, "after"); writeFileSync(a, before, { mode: 0o600 }); writeFileSync(b, after, { mode: 0o600 });
+    const diff = hubGitSync(repoGitArgs(repo, ["diff", "--no-index", "--no-color", "--no-ext-diff", "--no-textconv", "--unified=2", "--", a, b]), { encoding: "utf8", maxBuffer: 1024 * 1024, timeout: Math.ceil(Math.max(1, Math.min(DIFF_MS, deadline - performance.now()))), env: repoGitEnv(repo) });
+    if (diff.status !== 0 && diff.status !== 1) return undefined;
+    const start = diff.stdout.indexOf("@@");
+    if (start < 0) return diff.status === 0 ? "(projected text unchanged)" : undefined;
+    return diff.stdout.slice(start).replace(/\n$/, "");
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+/** Presentation of checked snapshot bytes, never evidence of authorship or restore safety. */
+export function projectedDiff(options: { repo: Repo; from: string; to: string; paths: string[]; projections: TextProjections; deny?: string[]; privatePath?: (path: string) => boolean; nameable?: (text: string) => boolean }): string | undefined {
+  const { repo, projections } = options;
+  if (!projections.enabled) return undefined;
+  const deadline = performance.now() + DIFF_MS, rows: string[] = []; let bytes = Buffer.byteLength(HEADER) + 1, files = 0;
+  const add = (text: string) => { const safe = sanitize(text); if (bytes + Buffer.byteLength(safe) + 1 > PROJECTED_DIFF_BYTES) return false; rows.push(safe); bytes += Buffer.byteLength(safe) + 1; return true; };
+  for (const path of [...new Set(options.paths)]) {
+    if (!projections.handles(path) || !projectionPath(repo, path, options.deny) || options.nameable?.(path) === false) continue;
+    if (files++ >= MAX_FILES || performance.now() >= deadline) { add("(remaining projection previews omitted: count or time limit)"); break; }
+    if (options.privatePath?.(path)) { if (!add(`${path}: (projection withheld: private path)`)) break; continue; }
+    const before = snapshotBytes(repo, options.from, path, deadline), after = snapshotBytes(repo, options.to, path, deadline);
+    if (before === undefined || after === undefined) { if (!add(`${path}: (projection unavailable: snapshot file is unknown)`)) break; continue; }
+    if (before === null && after === null) { if (!add(`${path}: (projection unavailable: file is absent from both snapshots)`)) break; continue; }
+    const a = before === null ? null : projections.projectBytes(join(repo.top, path), before, deadline);
+    if (a === undefined) continue;
+    const b = after === null ? null : projections.projectBytes(join(repo.top, path), after, deadline);
+    if (a === undefined || b === undefined) continue; // converter failure keeps the ordinary file-only view
+    if (a && b && a.configHash !== b.configHash) { if (!add(`${path}: (projection unavailable: converter changed during comparison)`)) break; continue; }
+    const diff = hunks(repo, a?.text ?? "", b?.text ?? "", deadline);
+    if (diff === undefined) { if (!add(`${path}: (projection unavailable: diff could not be read)`)) break; continue; }
+    const text = options.nameable?.(diff) === false ? `${path}: (projection withheld: private-data pattern)` : `${path}:\n${diff}`;
+    if (!add(text)) { add("(remaining projection previews omitted: output limit)"); break; }
+  }
+  return rows.length ? `${HEADER}\n${rows.join("\n")}` : undefined;
+}

package/src/hub/projection-exec.ts

@@ -0,0 +1,24 @@
+// Trusted synchronous-boundary helper: the parent waits, this process owns and stops the converter group.
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+let ownedGroup: number | undefined;
+const stop = () => { if (ownedGroup) try { process.kill(-ownedGroup, "SIGKILL"); } catch { /* owned group gone */ } };
+// The aggregate preview deadline can expire before the converter's own timer.
+process.on("SIGTERM", () => { stop(); process.exit(143); });
+process.on("SIGINT", () => { stop(); process.exit(130); });
+const request = JSON.parse(await new Response(Bun.stdin.stream()).text()) as { cwd: string; sandbox: string; argv: string[]; timeoutMs?: number };
+const limit = 256 * 1024;
+const child = spawn("/usr/bin/sandbox-exec", ["-p", request.sandbox, ...request.argv], {
+  cwd: request.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"],
+  env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: homedir(), LANG: "en_US.UTF-8", TERM: "dumb" },
+});
+ownedGroup = child.pid;
+const decoder = new TextDecoder("utf-8", { fatal: true });
+let stdout = "", stderrBytes = 0, outputBytes = 0, invalid = false;
+const timeout = typeof request.timeoutMs === "number" && Number.isFinite(request.timeoutMs) ? Math.ceil(Math.max(1, Math.min(5000, request.timeoutMs))) : 5000;
+const timer = setTimeout(() => { invalid = true; stop(); }, timeout);
+child.stdout.on("data", (bytes: Buffer) => { outputBytes += bytes.length; if (outputBytes > limit) { invalid = true; stop(); } else try { stdout += decoder.decode(bytes, { stream: true }); } catch { invalid = true; stop(); } });
+child.stderr.on("data", (bytes: Buffer) => { stderrBytes += bytes.length; if (stderrBytes > limit) { invalid = true; stop(); } });
+child.on("exit", () => stop()); // descendants may retain the output pipe after the leader exits
+child.on("error", () => { clearTimeout(timer); invalid = true; process.stdout.write(JSON.stringify({ ok: false })); });
+child.on("close", code => { clearTimeout(timer); ownedGroup = undefined; try { stdout += decoder.decode(); } catch { invalid = true; } process.stdout.write(JSON.stringify({ ok: !invalid && code === 0, ...(invalid || code !== 0 ? {} : { text: stdout }) })); });

package/src/hub/recovery-error.ts

@@ -0,0 +1,31 @@
+import { sanitize } from "./envelope.ts";
+
+/** Additive recovery outcome: older clients still receive ok:false and a useful error. */
+export class RecoveryDatabaseBusy extends Error {
+  readonly code = "database_busy";
+  readonly retryable = true;
+  constructor() {
+    super("database_busy: a database is busy; wait for the other connection to settle before retrying the request");
+  }
+}
+
+export function isDatabaseBusy(error: unknown): boolean {
+  if (error instanceof RecoveryDatabaseBusy) return true;
+  if (!error || typeof error !== "object") return false;
+  const value = error as { code?: unknown; errno?: unknown };
+  if (typeof value.code === "string") return /^(SQLITE_BUSY|SQLITE_LOCKED)(_|$)/.test(value.code);
+  return error instanceof Error && error.name === "SQLiteError"
+    && typeof value.errno === "number" && value.errno > 0 && [5, 6].includes(value.errno & 255);
+}
+
+/** Only exact legacy SQLite refusals are inferred from an authenticated hub reply. */
+export function isDatabaseBusyReply(reply: any): boolean {
+  return reply?.ok === false && (reply.code === "database_busy"
+    || reply.error === "database is locked" || reply.error === "database table is locked");
+}
+
+/** Frames only: retain the throw site without carrying a native error's message. */
+export function databaseBusySite(error: unknown): string[] {
+  const stack = error instanceof Error ? error.stack : undefined;
+  return (stack ?? "").split("\n").filter(line => /^\s*at /.test(line)).slice(0, 8).map(line => sanitize(line.trim()).slice(0, 400));
+}

package/src/hub/recovery-store.ts

@@ -5,6 +5,7 @@ import { Database } from "bun:sqlite";
 import { hubHome } from "./project.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
+const RUNNER_DB_BUSY_TIMEOUT_MS = 3000;
 export const operationIdPattern = /^[a-f0-9-]{36}$/;
 export function operationPath(id: string, home = hubHome()): string {
   if (!operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
@@ -111,7 +112,7 @@ export function recoveryRunner(id: string, home = hubHome()): number | "unknown"
   let db: Database | undefined;
   try {
     db = new Database(path, { readonly: true });
-    db.run("PRAGMA busy_timeout = 3000"); // a claim in progress must not read as no runner
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`); // a claim in progress must not read as no runner
     // A crash between creating the file and its table leaves no runner; claimRunner creates the table and claims.
     if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runner'").get()) return undefined;
     const row = db.query(`SELECT pid${signed(db) ? ", signature" : ""} FROM runner WHERE slot = 1`).get() as { pid: number; signature?: string | null } | null;
@@ -133,7 +134,7 @@ export function signedRunner(id: string, home = hubHome()): number | undefined {
   let db: Database | undefined;
   try {
     db = new Database(path, { readonly: true });
-    db.run("PRAGMA busy_timeout = 3000");
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
     if (!signed(db)) return undefined;
     const row = db.query("SELECT pid, signature FROM runner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
     if (!row?.signature || !Number.isSafeInteger(row.pid) || row.pid < 1) return undefined;
@@ -157,11 +158,11 @@ export async function stopSignedRunner(id: string, home = hubHome(), waitMs = 50
 /** An exclusive runner claim. Never steal a live or uncertain owner on resume. */
 export function claimRunner(id: string, home = hubHome()): () => void {
   const path = `${operationPath(id, home)}.runner.db`;
-  const db = new Database(path, { create: true });
-  chmodSync(path, 0o600);
   const nonce = randomUUID();
+  const db = new Database(path, { create: true });
   try {
-    db.run("PRAGMA busy_timeout = 3000");
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+    chmodSync(path, 0o600);
     db.run("CREATE TABLE IF NOT EXISTS runner (slot INTEGER PRIMARY KEY, pid INTEGER NOT NULL, nonce TEXT NOT NULL, signature TEXT)");
     if (!signed(db)) {
       try { db.run("ALTER TABLE runner ADD COLUMN signature TEXT"); }

package/src/hub/registry.ts

@@ -7,6 +7,7 @@ import { processLiveness } from "../pi/process-signature.ts";
 
 const BASE_PORT = 4600;
 const STRIDE = 10;
+export const REGISTRY_DB_BUSY_TIMEOUT_MS = 5000;
 const MAX_PORT = 65535 - 3;
 const LEGACY_DONE = "legacy_ports_imported";
 type Tx = { immediate(): void };
@@ -50,7 +51,7 @@ export class Registry {
     this.path = path;
     mkdirSync(dirname(path), { recursive: true });
     this.db = new Database(path, { create: true });
-    this.db.run("PRAGMA busy_timeout = 5000");
+    this.db.run(`PRAGMA busy_timeout = ${REGISTRY_DB_BUSY_TIMEOUT_MS}`);
     try {
       this.db.run("PRAGMA journal_mode = WAL");
     } catch (error) {