@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/native-permission-request.ts

@@ -0,0 +1,77 @@
+import { types } from "node:util";
+
+export const NATIVE_PERMISSION_PROBE_MAX_BYTES = 4096;
+export const NATIVE_PERMISSION_PROBE_MAX_PER_LAUNCH = 4;
+const MAX_DEPTH = 8, MAX_NODES = 256;
+
+/** The approval path's pre-existing inline checks, deliberately without stricter shape checks.
+ * Keep ordinary property reads and their failure behavior; diagnostics cannot change native admission. */
+export function acceptsNativePermissionRequest(value: unknown): boolean {
+  const args = value as Record<string, unknown> | undefined;
+  if (typeof args?.tool_name !== "string" || !/^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$/.test(args.tool_name)
+    || !args.input || typeof args.input !== "object" || Array.isArray(args.input)
+    || typeof args.tool_use_id !== "string" || !args.tool_use_id.length || args.tool_use_id.length > 256) return false;
+  return true;
+}
+
+/** Strict diagnostic classification only. Never use this to narrow the approval path. */
+export function validateNativePermissionRequest(value: unknown): boolean {
+  try {
+    if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== 3 || !keys.every(key => key === "tool_name" || key === "input" || key === "tool_use_id")) return false;
+    const data = (key: string): unknown => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+    };
+    const tool = data("tool_name"), input = data("input"), id = data("tool_use_id");
+    return typeof tool === "string" && tool.length <= 128 && tool === tool.trim() && /^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$/.test(tool)
+      && input !== null && typeof input === "object" && !Array.isArray(input)
+      && typeof id === "string" && id.length > 0 && id.length <= 256;
+  } catch { return false; }
+}
+
+/** A temporary bounded validation input, never retained evidence or an authorization request. */
+export function buildNativePermissionProbe(request: unknown): { t: "permission_failure_probe"; request: unknown } | undefined {
+  try {
+    let nodes = 0, bytes = 0;
+    const ancestors = new Set<object>(), encoder = new TextEncoder();
+    const charge = (count: number) => { bytes += count; if (bytes > NATIVE_PERMISSION_PROBE_MAX_BYTES) throw new Error(); };
+    const string = (value: string) => {
+      if (value.length > NATIVE_PERMISSION_PROBE_MAX_BYTES) throw new Error();
+      charge(encoder.encode(JSON.stringify(value)).byteLength);
+      return value;
+    };
+    const clone = (value: unknown, depth: number): unknown => {
+      if (++nodes > MAX_NODES || depth > MAX_DEPTH) throw new Error();
+      if (typeof value === "string") return string(value);
+      if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+        charge(value === null ? 4 : typeof value === "boolean" ? value ? 4 : 5 : String(value).length); return value;
+      }
+      if (!value || typeof value !== "object" || types.isProxy(value) || ancestors.has(value)) throw new Error();
+      const array = Array.isArray(value), prototype = Object.getPrototypeOf(value);
+      if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw new Error();
+      const keys = Reflect.ownKeys(value);
+      if (keys.length > MAX_NODES || keys.some(key => typeof key !== "string")) throw new Error();
+      ancestors.add(value);
+      try {
+        const copy: Record<string, unknown> | unknown[] = array ? Object.setPrototypeOf([], null) : Object.create(null);
+        const length = array ? Object.getOwnPropertyDescriptor(value, "length")?.value : undefined;
+        if (array && (!Number.isSafeInteger(length) || length < 0 || length > MAX_NODES || keys.length !== length + 1)) throw new Error();
+        const names = array ? Array.from({ length }, (_, index) => String(index)) : keys as string[];
+        charge(2 + Math.max(0, names.length - 1) + (array ? 0 : names.length));
+        for (const key of names) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, key);
+          if (!descriptor || !Object.hasOwn(descriptor, "value") || !descriptor.enumerable) throw new Error();
+          if (!array) string(key);
+          Object.defineProperty(copy, key, { value: clone(descriptor.value, depth + 1), enumerable: true, writable: true, configurable: true });
+        }
+        return copy;
+      } finally { ancestors.delete(value); }
+    };
+    const payload = Object.assign(Object.create(null), { t: "permission_failure_probe" as const, request: clone(request, 0) });
+    return encoder.encode(JSON.stringify(payload)).byteLength <= NATIVE_PERMISSION_PROBE_MAX_BYTES ? payload : undefined;
+  } catch { return; }
+}

package/src/hub/operational-authority.ts

@@ -1,10 +1,16 @@
 import type { SettingDef } from "./settings.ts";
 
-/** Existing live registry rows only. A new registry key never inherits conductor authority from a prefix. */
+/**
+ * Existing live registry rows only. A new registry key never inherits conductor authority from a prefix.
+ * #933: every live config key outside the person's group. The registry's groups cannot tell spending from operations
+ * (`tasks.wip_limits.*`, `tasks.auto_pull` and `tasks.queue_backpressure.*` decide how much work the hub hands out unattended,
+ * and an agent never turns auto pull on), and Permissions, Roles and Start are trust or not live, so the list stays explicit.
+ */
 export const CONDUCTOR_SETTING_KEYS = [
   "task_sweep.enabled", "task_sweep.auto_reassign", "task_sweep.no_writes_turns", "task_sweep.interval_s",
   "task_sweep.unaccepted_min", "task_sweep.idle_min", "task_sweep.review_min", "task_sweep.ready_min", "task_sweep.ladder_min",
   "snapshots.enabled", "research.enabled", "approvals.notify",
+  "tasks.escalate_after",
 ] as const;
 const settingKeys: ReadonlySet<string> = new Set(CONDUCTOR_SETTING_KEYS);
 export const operationalSettingKey = (value: unknown): value is string => typeof value === "string" && settingKeys.has(value);
@@ -24,19 +30,67 @@ export function operationalRosterSetting(def: Pick<SettingDef,"key"|"path"|"appl
 export const CONDUCTOR_LOCAL_ACTIONS = ["doctor orphans kill","logs","export"] as const;
 export type ConductorLocalAction = typeof CONDUCTOR_LOCAL_ACTIONS[number];
 export const conductorLocalAction = (value:unknown): value is ConductorLocalAction => typeof value==="string" && (CONDUCTOR_LOCAL_ACTIONS as readonly string[]).includes(value);
-export type ConductorOperation = ConductorLocalAction | "roster add" | "roster remove" | "stop" | "queue show" | "queue resolve" | "queue discard" | "task cancel" | "settings set";
+/** Daemon-authorized labels. Recovery labels pass the initial role check, then require their separate per-operation proof. */
+export const CONDUCTOR_DAEMON_OPERATIONS = ["roster add","roster remove","stop","queue show","queue resolve","queue discard","settings set","doctor orphans kill","logs","export",
+  "board import","intake approve","schedule run","schedule pause","schedule resume","goal link","task unassign","restart","upgrade","recovery resume","recovery abort"] as const;
+/**
+ * #933: forms whose effect runs in the CLI process itself (local files). The daemon admits and audits them once at the handshake (`admit`),
+ * after the CLI has validated their arguments. Recovery-bearing restart/upgrade forms use the separate source-issued continuation proof.
+ * ponytail: `memory promote|demote|forget|supersede|rebuild|machine --label` and the local `goal` changes stay the person's because the pinned
+ * amem (0.12.0) records their actor as "user"; once the hub passes an agent actor through agent-mem 0.13.0 attribution (agent-mem#143, after
+ * the pin bump in #958) they can join this list. `goal link` is a daemon form: the hub records the peer as its actor.
+ */
+export const CONDUCTOR_LOCAL_OPERATIONS = ["research backfill","bench run","source add"] as const;
+export type ConductorOperation = typeof CONDUCTOR_DAEMON_OPERATIONS[number] | typeof CONDUCTOR_LOCAL_OPERATIONS[number];
+export const conductorLocalOperation = (value:unknown): boolean => typeof value==="string" && (CONDUCTOR_LOCAL_OPERATIONS as readonly string[]).includes(value);
+
+function operationalDisplayArgument(arg: string): boolean {
+  return arg === "--json" || arg === "--verbose" || arg.startsWith("--color=");
+}
+
+function recoveryConductorAction(args: readonly string[]): "resume" | "abort" | undefined {
+  const words = args.filter(arg => !operationalDisplayArgument(arg));
+  const action = words[0];
+  if (action !== "resume" && action !== "abort") return undefined;
+  const tail = words.slice(1);
+  if (tail.length > 1 || tail.some(arg => arg.startsWith("-"))) return undefined;
+  return action;
+}
+
+function restartOrUpgrade(command: string, args: readonly string[]): "restart" | "upgrade" | undefined {
+  const words = args.filter(arg => !operationalDisplayArgument(arg));
+  if (words.includes("--dry-run")) return undefined;
+  if (command === "restart") return words.length === 1 && words[0] === "--yes" ? "restart" : undefined;
+  if (command !== "upgrade" || words.length !== 3) return undefined;
+  if (words[0] === "--yes" && words[1] === "--to" && !words[2]!.startsWith("-")) return "upgrade";
+  if (words[0] === "--to" && !words[1]!.startsWith("-") && words[2] === "--yes") return "upgrade";
+  return undefined;
+}
 
 /** Select the closed command family; the existing command parser still validates all arguments before effects. */
 export function conductorOperation(command:string,args:readonly string[]): ConductorOperation | undefined {
   const words=args.filter(arg=>!arg.startsWith("--"));
   const sub=words[0];
+  if (command === "restart" || command === "upgrade") return restartOrUpgrade(command, args);
+  if (command === "recovery") {
+    const action = recoveryConductorAction(args);
+    return action ? `recovery ${action}` : undefined;
+  }
   if (command==="roster" && (sub==="add" || sub==="remove")) return `roster ${sub}`;
   if (command==="stop" && args.length===1 && /^[a-z][a-z0-9-]{0,31}$/.test(args[0]!)) return "stop";
   if (command==="queue" && (sub==="show" || sub==="resolve" || sub==="discard")) return `queue ${sub}`;
-  if (command==="task" && sub==="cancel") return "task cancel";
+  if (command==="task" && sub==="unassign") return "task unassign";
   if (command==="doctor" && args.includes("--orphans") && args.includes("--kill")) return "doctor orphans kill";
   if (command==="logs" || command==="export") return command;
   if (command==="settings" && sub==="set" && operationalSettingKey(words[1])) return "settings set";
+  // #933: operational forms the person no longer has to run; recovery-bearing forms above use their own proof.
+  if (command==="board" && args[0]==="import") return "board import";
+  if (command==="research" && args[0]==="backfill") return "research backfill";
+  if (command==="bench" && args.find(arg=>arg!=="--json")==="run") return "bench run";
+  if (command==="source" && sub==="add") return "source add";
+  if (command==="intake" && sub==="approve" && words.length===2) return "intake approve";
+  if (command==="schedule" && (sub==="run" || sub==="pause" || sub==="resume")) return `schedule ${sub}`;
+  if (command==="goal" && args.find(arg=>arg!=="--json")==="link") return "goal link";
   return undefined;
 }
 
@@ -51,16 +105,20 @@ export const OPERATIONAL_PERSON_GUIDANCE="the person runs it in ahub console or
 export function operationalRefusal(peer:string,command:string):string {
   return `${peer} cannot run ahub ${command}; ${OPERATIONAL_PERSON_GUIDANCE}; this operation requires the explicit conductor role`;
 }
+/** #933: the console task ops the conductor may now run, by audit label. The daemon admits each through `admitOperational` before Tasks sees it. */
+export const CONDUCTOR_TASK_OPS: Readonly<Record<string,ConductorOperation>> = {github_import:"board import",intake_approve:"intake approve",schedule_run:"schedule run",schedule_pause:"schedule pause",schedule_resume:"schedule resume",task_unassign:"task unassign"};
 /** Fixed labels only; refused requests never put argument text in the audit. */
 export function operationalRequestLabel(value:unknown):string|undefined {
   if(!value || typeof value!=="object" || Array.isArray(value))return undefined;
   const message=value as Record<string,unknown>;
   if(message.t==="conductor_operational") {
-    if(message.op==="authorize")return typeof message.command==="string" && ["roster add","roster remove","stop","queue show","queue resolve","queue discard","task cancel","settings set","doctor orphans kill","logs","export"].includes(message.command)?message.command:"unknown";
+    if(message.op==="authorize")return typeof message.command==="string" && (CONDUCTOR_DAEMON_OPERATIONS as readonly string[]).includes(message.command)?message.command:"unknown";
+    if(message.op==="admit")return conductorLocalOperation(message.command)?message.command as string:"unknown";
     return message.op==="orphans"?"doctor orphans kill":message.op==="logs"||message.op==="export"?message.op:"unknown";
   }
   if(message.t==="peer_stop")return "stop";
-  if(message.t==="task" && message.op==="hub_task_cancel")return "task cancel";
+  if(message.t==="goal_link")return "goal link";
+  if(message.t==="task" && typeof message.op==="string" && Object.hasOwn(CONDUCTOR_TASK_OPS,message.op))return CONDUCTOR_TASK_OPS[message.op];
   if(message.t==="queue" && typeof message.op==="string" && ["show","resolve","discard"].includes(message.op))return `queue ${message.op}`;
   if(message.t==="settings_set"||message.t==="settings_preview")return "settings set";
   return undefined;

package/src/hub/operational-settings.ts

@@ -0,0 +1,154 @@
+import type { SettingDef } from "./settings.ts";
+
+/** Numeric operational metadata only: existing schema, settings and reload retain all authority. */
+export interface OperationalNumberSetting extends Pick<SettingDef, "key" | "group" | "label" | "path" | "applies" | "restartReason"> {
+  type: "number" | "integer";
+  store: "config";
+  risk: "raises";
+  min: number;
+  max: number;
+  defaultValue: number;
+  unit: string;
+  /** The independently classified H0 item, not a safety floor or wire/storage contract. */
+  inventory: string;
+}
+
+export const GROOM_FYI_WINDOW_SETTING = {
+  key: "tasks.groom_fyi_window_min",
+  path: ["tasks", "groom_fyi_window_min"],
+  group: "Routing",
+  label: "Planner state-update FYI interval (minutes)",
+  type: "number",
+  store: "config",
+  risk: "raises",
+  applies: "live",
+  min: 1,
+  max: 1440,
+  defaultValue: 10,
+  unit: "minutes",
+  inventory: "src/hub/tasks.ts:GROOM_FYI_WINDOW_MS",
+} as const satisfies OperationalNumberSetting;
+
+const taskNumber = <const T extends Omit<OperationalNumberSetting, "group" | "store" | "risk" | "applies">>(def: T) => ({ group: "Routing", store: "config", risk: "raises", applies: "live", ...def }) as const satisfies OperationalNumberSetting;
+
+/** #489 H2, tasks and routing. Each default equals the constant it replaces (pinned in test/operational-settings.test.ts); none is a safety floor or a contract. */
+export const DEMOTE_AT_SETTING = taskNumber({
+  key: "tasks.demote_at", path: ["tasks", "demote_at"], label: "Peer demotion threshold (decayed recent failures)",
+  type: "number", min: 0.5, max: 20, defaultValue: 1.5, unit: "failures", inventory: "src/hub/tasks.ts:DEMOTE_AT",
+});
+export const DEMOTION_HALF_LIFE_SETTING = taskNumber({
+  key: "tasks.demotion_half_life_h", path: ["tasks", "demotion_half_life_h"], label: "Demotion half-life: a failure counts half after (hours)",
+  type: "number", min: 1, max: 168, defaultValue: 24, unit: "hours", inventory: "src/hub/tasks.ts:DEMOTION_HALF_LIFE_MS",
+});
+export const CONTRADICTION_WINDOW_SETTING = taskNumber({
+  key: "tasks.contradiction_window_days", path: ["tasks", "contradiction_window_days"], label: "Approval contradiction window (days)",
+  type: "number", min: 1, max: 90, defaultValue: 7, unit: "days", inventory: "src/hub/tasks.ts:CONTRADICTION_WINDOW_MS",
+});
+export const RESCREEN_MAX_SETTING = taskNumber({
+  key: "tasks.rescreen_max", path: ["tasks", "rescreen_max"], label: "PII re-screen attempts per task in a hub run",
+  type: "integer", min: 1, max: 100, defaultValue: 10, unit: "attempts", inventory: "src/hub/tasks.ts:RESCREEN_MAX",
+});
+export const SPLIT_MIN_SETTING = taskNumber({
+  key: "tasks.split_min_observations", path: ["tasks", "split_min_observations"], label: "Shadow split prediction: measured tasks a peer needs",
+  type: "integer", min: 3, max: 100, defaultValue: 5, unit: "tasks", inventory: "src/hub/routing.ts:SPLIT_MIN",
+});
+export const SPLIT_FAILURE_SHARE_SETTING = taskNumber({
+  key: "tasks.split_max_failure_share", path: ["tasks", "split_max_failure_share"], label: "Shadow split prediction: failed share a history may hold",
+  type: "number", min: 0, max: 1, defaultValue: 0.3, unit: "share", inventory: "src/hub/routing.ts:SPLIT_FAILURE_SHARE",
+});
+
+const busNumber = <const T extends Omit<OperationalNumberSetting, "group" | "store" | "risk" | "applies" | "type" | "min">>(def: T) => ({ group: "Routing", store: "config", risk: "raises", applies: "live", type: "integer", min: 1, ...def }) as const satisfies OperationalNumberSetting;
+
+export const BUS_MAX_ATTEMPTS_SETTING = busNumber({
+  key: "bus.max_attempts", path: ["bus", "max_attempts"], label: "Safe-failure delivery attempts",
+  max: 100, defaultValue: 3, unit: "attempts", inventory: "src/hub/bus.ts:MAX_ATTEMPTS",
+});
+export const BUS_DIGEST_MAX_SETTING = busNumber({
+  key: "bus.digest_max", path: ["bus", "digest_max"], label: "Maximum originals in a push digest",
+  max: 10, defaultValue: 10, unit: "envelopes", inventory: "src/hub/bus.ts:DIGEST_MAX",
+});
+export const BUS_PULL_BUDGET_BYTES_SETTING = busNumber({
+  key: "bus.pull_budget_bytes", path: ["bus", "pull_budget_bytes"], label: "Pull rendered-text budget (bytes)",
+  max: 65_536, defaultValue: 65_536, unit: "bytes", inventory: "src/hub/bus.ts:PULL_BUDGET_BYTES",
+});
+export const BUS_NOTES_KEPT_SETTING = busNumber({
+  key: "bus.notes_kept", path: ["bus", "notes_kept"], label: "Shared notes retained in a merged preface",
+  max: 10, defaultValue: 10, unit: "notes", inventory: "src/hub/bus.ts:NOTES_KEPT",
+});
+export const BUS_TERMINAL_HISTORY_LIMIT_SETTING = busNumber({
+  key: "bus.terminal_history_limit", path: ["bus", "terminal_history_limit"], label: "Unprotected terminal delivery history target",
+  max: 2048, defaultValue: 2048, unit: "rows", inventory: "src/hub/delivery-journal.ts:TERMINAL_CAP",
+});
+
+/**
+ * #489 H4, recovery and upgrade waits. These are read by the upgrade coordinator (a CLI process) from the project's own config at the START of each wait, so a change applies at the next wait and a wait
+ * already running keeps its deadline. Every row's minimum is today's constant: a person-visible wait can be raised, never cut below what ships (a request that times out may already have applied, and a
+ * shorter reconnect wait fails a recovery earlier than the person was told). The one row that may shorten, `recovery.terminal_idle_wait_s`, only ends a wait in manual-required, which retains the terminal.
+ */
+const recoveryNumber = <const T extends Omit<OperationalNumberSetting, "group" | "store" | "risk" | "applies" | "type">>(def: T) => ({ group: "Routing", store: "config", risk: "raises", applies: "next use", type: "integer", ...def }) as const satisfies OperationalNumberSetting;
+export const RECOVERY_RECONNECT_WAIT_SETTING = recoveryNumber({
+  key: "recovery.reconnect_wait_s", path: ["recovery", "reconnect_wait_s"], label: "Upgrade recovery: wait for a managed terminal to attach (seconds)",
+  min: 600, max: 3600, defaultValue: 600, unit: "seconds", inventory: "src/cli/upgrade-runtime.ts:RECONNECT_WAIT_MS",
+});
+export const RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING = recoveryNumber({
+  key: "recovery.unmanaged_reconnect_wait_s", path: ["recovery", "unmanaged_reconnect_wait_s"], label: "Upgrade recovery: wait for an unmanaged Claude to reconnect (seconds)",
+  min: 90, max: 900, defaultValue: 90, unit: "seconds", inventory: "src/cli/upgrade-runtime.ts:UNMANAGED_RECONNECT_WAIT_MS",
+});
+export const RECOVERY_CONTROL_TIMEOUT_SETTING = recoveryNumber({
+  key: "recovery.control_timeout_s", path: ["recovery", "control_timeout_s"], label: "Upgrade recovery: wait for one control request to a hub (seconds)",
+  min: 30, max: 300, defaultValue: 30, unit: "seconds", inventory: "src/cli/upgrade-runtime.ts:RECOVERY_CONTROL_TIMEOUT_MS",
+});
+export const RECOVERY_SHUTDOWN_WAIT_SETTING = recoveryNumber({
+  key: "recovery.shutdown_wait_s", path: ["recovery", "shutdown_wait_s"], label: "Upgrade recovery: wait for the old hub to stop after commit (seconds)",
+  min: 30, max: 300, defaultValue: 30, unit: "seconds", inventory: "src/cli/upgrade.ts:deadline",
+});
+export const RECOVERY_TERMINAL_IDLE_WAIT_SETTING = recoveryNumber({
+  key: "recovery.terminal_idle_wait_s", path: ["recovery", "terminal_idle_wait_s"], label: "Upgrade recovery: wait for a terminal to go idle before closing it (seconds)",
+  min: 30, max: 600, defaultValue: 120, unit: "seconds", inventory: "src/cli/upgrade-runtime.ts:waitForIdle",
+});
+
+/** Fixed metadata; never registration from a file, request, adapter or environment variable. */
+export const OPERATIONAL_NUMBERS: readonly OperationalNumberSetting[] = [GROOM_FYI_WINDOW_SETTING, DEMOTE_AT_SETTING, DEMOTION_HALF_LIFE_SETTING, CONTRADICTION_WINDOW_SETTING, RESCREEN_MAX_SETTING, SPLIT_MIN_SETTING, SPLIT_FAILURE_SHARE_SETTING,
+  BUS_MAX_ATTEMPTS_SETTING, BUS_DIGEST_MAX_SETTING, BUS_PULL_BUDGET_BYTES_SETTING, BUS_NOTES_KEPT_SETTING, BUS_TERMINAL_HISTORY_LIMIT_SETTING,
+  RECOVERY_RECONNECT_WAIT_SETTING, RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING, RECOVERY_CONTROL_TIMEOUT_SETTING, RECOVERY_SHUTDOWN_WAIT_SETTING, RECOVERY_TERMINAL_IDLE_WAIT_SETTING];
+/** The `tasks` leaves the six #489 H2 readers need; `HubConfig.tasks` has them all. */
+export interface TaskOperationalConfig { tasks: { demote_at?: number; demotion_half_life_h?: number; contradiction_window_days?: number; rescreen_max?: number; split_min_observations?: number; split_max_failure_share?: number } }
+/**
+ * The one place the daemon turns the six task settings into `TasksDeps` readers. `config` is asked at every use, so a reload applies at the next demotion read, verdict, re-screen or prediction; an unset leaf is the row's default,
+ * which is the constant it replaced.
+ */
+export const taskOperationalReaders = (config: () => TaskOperationalConfig) => ({
+  demoteAt: () => config().tasks.demote_at ?? DEMOTE_AT_SETTING.defaultValue,
+  demotionHalfLifeH: () => config().tasks.demotion_half_life_h ?? DEMOTION_HALF_LIFE_SETTING.defaultValue,
+  contradictionWindowDays: () => config().tasks.contradiction_window_days ?? CONTRADICTION_WINDOW_SETTING.defaultValue,
+  rescreenMax: () => config().tasks.rescreen_max ?? RESCREEN_MAX_SETTING.defaultValue,
+  splitMinObservations: () => config().tasks.split_min_observations ?? SPLIT_MIN_SETTING.defaultValue,
+  splitMaxFailureShare: () => config().tasks.split_max_failure_share ?? SPLIT_FAILURE_SHARE_SETTING.defaultValue,
+});
+export interface BusOperationalConfig { bus?: { max_attempts?: number; digest_max?: number; pull_budget_bytes?: number; notes_kept?: number; terminal_history_limit?: number } }
+/** Read accepted configuration at the next operation; a reload itself never trims or retries work. */
+export const busOperationalReaders = (config: () => BusOperationalConfig) => ({
+  maxAttempts: () => config().bus?.max_attempts ?? BUS_MAX_ATTEMPTS_SETTING.defaultValue,
+  digestMax: () => config().bus?.digest_max ?? BUS_DIGEST_MAX_SETTING.defaultValue,
+  pullBudgetBytes: () => config().bus?.pull_budget_bytes ?? BUS_PULL_BUDGET_BYTES_SETTING.defaultValue,
+  notesKept: () => config().bus?.notes_kept ?? BUS_NOTES_KEPT_SETTING.defaultValue,
+  terminalHistoryLimit: () => config().bus?.terminal_history_limit ?? BUS_TERMINAL_HISTORY_LIMIT_SETTING.defaultValue,
+});
+export interface RecoveryOperationalConfig { recovery?: { reconnect_wait_s?: unknown; unmanaged_reconnect_wait_s?: unknown; control_timeout_s?: unknown; shutdown_wait_s?: unknown; terminal_idle_wait_s?: unknown } }
+export interface RecoveryWaits { reconnectWaitMs: number; unmanagedReconnectWaitMs: number; controlTimeoutMs: number; shutdownWaitMs: number; terminalIdleWaitMs: number }
+const recoveryMs = (def: OperationalNumberSetting, raw: unknown): number => {
+  // A value outside the row's bounds, a non-integer or a non-number is the default, never an error inside a recovery: the file was validated when it was written, and a recovery must not fail on a later edit.
+  return typeof raw === "number" && Number.isSafeInteger(raw) && raw >= def.min && raw <= def.max ? raw * 1000 : def.defaultValue * 1000;
+};
+/** The one place the coordinator turns the five recovery settings into milliseconds. `config` is asked at each wait, so the next wait reads the file as it is then. */
+export const recoveryWaits = (config: () => RecoveryOperationalConfig | undefined): RecoveryWaits => {
+  const leaf = config()?.recovery;
+  return {
+    reconnectWaitMs: recoveryMs(RECOVERY_RECONNECT_WAIT_SETTING, leaf?.reconnect_wait_s),
+    unmanagedReconnectWaitMs: recoveryMs(RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING, leaf?.unmanaged_reconnect_wait_s),
+    controlTimeoutMs: recoveryMs(RECOVERY_CONTROL_TIMEOUT_SETTING, leaf?.control_timeout_s),
+    shutdownWaitMs: recoveryMs(RECOVERY_SHUTDOWN_WAIT_SETTING, leaf?.shutdown_wait_s),
+    terminalIdleWaitMs: recoveryMs(RECOVERY_TERMINAL_IDLE_WAIT_SETTING, leaf?.terminal_idle_wait_s),
+  };
+};
+export const operationalNumber = (key: string): OperationalNumberSetting | undefined => OPERATIONAL_NUMBERS.find(def => def.key === key);

package/src/hub/operational-view.ts

@@ -66,7 +66,7 @@ function metadataValue(type:string,key:string,value:unknown):boolean {
   if(key==="item")return oneOf(value,["task","summary","review note","handoff","note"]);
   if(key==="category")return oneOf(value,["name","student_id","phone","address","grade","health","other"]);
   if(key==="miss")return oneOf(value,["too long","off campus","timeout","unreadable","failed"]);
-  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire"]):identifier(value);
+  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire","jcode_acp"]):identifier(value);
   if(key==="measuredAt")return type==="context_pressure" || type==="quota_reset"?typeof value==="number"&&Number.isFinite(value):typeof value==="string"&&Number.isFinite(Date.parse(value));
   if(key==="window")return value===null || typeof value==="number"&&Number.isFinite(value)&&value>=0 || identifier(value);
   if(key==="priority")return value===null || typeof value==="number"&&Number.isFinite(value) || oneOf(value,["status","important","fyi"]);

package/src/hub/packs.ts

@@ -0,0 +1,132 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_NAMES, resolveProfile, type ProfileName } from "./profiles.ts";
+import { loadRoleCatalog } from "./roles.ts";
+import { SHIPPED_PACKS } from "./shipped-packs.ts";
+import { criterionId } from "./workflow.ts";
+
+/**
+ * A domain pack (#513a): a profile plus the roles it expects, a review rubric and example checks, in one file. It is data, never authority: it selects an
+ * existing profile, names roles that must already be in the catalog, and contributes only `profile_overrides` text (`review_checklist`, `example_checks`)
+ * that `resolveProfile` already bounds. Checks are display text exactly like `example_checks`: nothing here selects or runs a command.
+ * The rubric ids follow #507's criterion ids (`criterionId`), so a reviewer names an unmet item by the same id the task's checklist uses.
+ */
+export interface DomainPack {
+  name: string; profile: ProfileName; summary: string; roles: string[];
+  rubric: { id: string; text: string; required: boolean }[];
+  checks: { id: string; note: string }[];
+  layer: "shipped" | "project";
+}
+export interface PackCatalog { packs: Map<string, DomainPack>; errors: { id: string; reason: string }[] }
+export const PACK_SUFFIX = ".pack.json";
+const NAME = /^[a-z][a-z0-9-]{0,47}$/;
+const MAX_BYTES = 8192, MAX_FILES = 16, MAX_ROLES = 8, MAX_RUBRIC = 12, MAX_CHECKS = 8;
+const KEYS = ["name", "profile", "summary", "roles", "rubric", "checks"];
+
+const plain = (value: unknown, cap: number, what: string): string => {
+  if (typeof value !== "string" || !value.trim() || value.length > cap || value !== value.trim()) throw new Error(`${what} must be trimmed text of at most ${cap} characters`);
+  for (const char of value) if (/[\x00-\x1f\x7f]/.test(char) || (char.codePointAt(0)! > 127 && /[\p{P}\p{S}\p{Z}\p{C}]/u.test(char))) throw new Error(`${what} must use plain punctuation and no control characters`);
+  return value;
+};
+const object = (value: unknown, keys: string[], what: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) throw new Error(`${what}: unexpected shape or field`);
+  return value as Record<string, unknown>;
+};
+
+/** One pack file. `stem` is the file name without `.pack.json`; the name inside must equal it. */
+export function parsePack(text: string, stem: string, layer: DomainPack["layer"]): DomainPack {
+  if (Buffer.byteLength(text) > MAX_BYTES || text.includes("\r") || !NAME.test(stem)) throw new Error("invalid pack size, encoding or file name");
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new Error("pack is not valid JSON"); }
+  const data = object(raw, KEYS, "pack");
+  if (KEYS.some(key => data[key] === undefined)) throw new Error("pack needs name, profile, summary, roles, rubric and checks");
+  if (data.name !== stem) throw new Error("pack name must equal its file name");
+  if ((PROFILE_NAMES as readonly string[]).includes(stem)) throw new Error("a pack cannot take a profile's name");
+  if (typeof data.profile !== "string" || !(PROFILE_NAMES as readonly string[]).includes(data.profile)) throw new Error(`pack profile must be one of ${PROFILE_NAMES.join(", ")}`);
+  const summary = plain(data.summary, 160, "summary");
+  if (!Array.isArray(data.roles) || data.roles.length > MAX_ROLES || new Set(data.roles).size !== data.roles.length || data.roles.some(id => typeof id !== "string" || !NAME.test(id))) throw new Error(`pack roles must be at most ${MAX_ROLES} distinct role ids`);
+  if (!Array.isArray(data.rubric) || !data.rubric.length || data.rubric.length > MAX_RUBRIC) throw new Error(`pack rubric needs 1 to ${MAX_RUBRIC} criteria`);
+  const rubric = data.rubric.map((entry, index) => {
+    const item = object(entry, ["id", "text", "required"], `rubric ${index + 1}`);
+    if (!criterionId(item.id) || typeof item.required !== "boolean") throw new Error(`rubric ${index + 1} needs a criterion id and a required flag`);
+    return { id: item.id, text: plain(item.text, 300, `rubric ${item.id} text`), required: item.required };
+  });
+  if (new Set(rubric.map(item => item.id)).size !== rubric.length) throw new Error("rubric criterion ids must be distinct");
+  if (!Array.isArray(data.checks) || data.checks.length > MAX_CHECKS) throw new Error(`pack checks must be at most ${MAX_CHECKS} entries`);
+  const checks = data.checks.map((entry, index) => {
+    const item = object(entry, ["id", "note"], `check ${index + 1}`);
+    if (typeof item.id !== "string" || !NAME.test(item.id)) throw new Error(`check ${index + 1} needs a check id`);
+    return { id: item.id, note: plain(item.note, 500, `check ${item.id} note`) };
+  });
+  if (new Set(checks.map(item => item.id)).size !== checks.length) throw new Error("check ids must be distinct");
+  return { name: stem, profile: data.profile as ProfileName, summary, roles: [...data.roles as string[]], rubric, checks, layer };
+}
+
+/** Read one bounded regular file without following links, as `loadRoleCatalog` reads a project role. */
+function readPack(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > MAX_BYTES) throw new Error("pack must be a bounded regular file");
+    const bytes = Buffer.alloc(MAX_BYTES + 1); let length = 0, n = 0;
+    while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > MAX_BYTES) throw new Error("pack exceeds file cap"); }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("pack changed during read");
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+
+/**
+ * Project-layer packs, `.agenthub/roles/<name>.pack.json` (#513a AC4): the same directory the role catalog reads, which ignores these files (it takes `.md` only).
+ * A pack whose roles are not all in the catalog (shipped or project) is refused with the reason, never loaded half-usable. Reasons carry ids, never file contents.
+ */
+export function loadPacks(cwd?: string, shippedPacks: Readonly<Record<string, string>> = SHIPPED_PACKS): PackCatalog {
+  const packs = new Map<string, DomainPack>(), errors: PackCatalog["errors"] = [];
+  // The shipped layer comes first and a project pack of the same name replaces it, as a project role replaces a shipped one. Its roles are checked against the shipped catalog only: it must not depend on a project file.
+  const shipped = loadRoleCatalog();
+  for (const [id, text] of Object.entries(shippedPacks)) {
+    try {
+      const pack = parsePack(text, id, "shipped");
+      const missing = pack.roles.filter(role => !shipped.roles.has(role));
+      if (missing.length) throw new Error(`unknown roles: ${missing.join(", ")}`);
+      packs.set(id, pack);
+    } catch { errors.push({ id, reason: "invalid shipped pack" }); }
+  }
+  if (!cwd) return { packs, errors };
+  const catalog = loadRoleCatalog(cwd);
+  try {
+    const config = join(cwd, ".agenthub"), dir = join(config, "roles");
+    // lstat, never stat: a link is not a directory to lstat, so a symlinked `.agenthub` or `roles` is refused before anything is read through it.
+    for (const path of [config, dir]) if (!lstatSync(path).isDirectory()) throw new Error("unsafe role directory");
+    // ponytail: 16 flat pack files, no recursive scan; an explicit pack index before larger collections.
+    const files = readdirSync(dir).filter(name => name.endsWith(PACK_SUFFIX)).sort();
+    if (files.length > MAX_FILES) throw new Error("too many project packs");
+    for (const file of files) {
+      const id = file.slice(0, -PACK_SUFFIX.length);
+      try {
+        const pack = parsePack(readPack(join(dir, file)), id, "project");
+        const missing = pack.roles.filter(role => !catalog.roles.has(role));
+        if (missing.length) throw new Error(`unknown roles: ${missing.join(", ")}`);
+        packs.set(id, pack);
+      } catch (error) { errors.push({ id: NAME.test(id) ? id : "invalid-file-id", reason: (error as Error).message.slice(0, 200) }); }
+    }
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push({ id: "project", reason: "project pack directory unavailable or unsafe" }); }
+  return { packs, errors };
+}
+
+/** A stable text of plain JSON data: object keys sorted at every depth, array order kept (a checklist's order is its meaning). Two values with the same data compare equal whatever order their keys were written in. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** What a pack contributes to the project's `profile_overrides`: the rubric as the profile's review checklist, the checks as advisory examples. Validated by `resolveProfile`. */
+export function packOverrides(pack: DomainPack): Record<string, unknown> {
+  const overrides: Record<string, unknown> = {
+    review_checklist: [...pack.rubric.map(item => `${item.id}${item.required ? "" : " (optional)"}: ${item.text}`), "{check}"],
+    ...(pack.checks.length ? { example_checks: pack.checks.map(check => `${check.id}: ${check.note}`) } : {}),
+  };
+  resolveProfile(pack.profile, overrides);
+  return overrides;
+}

package/src/hub/path-policy.ts

@@ -2,6 +2,13 @@ import { accessSync, constants, lstatSync, opendirSync, readlinkSync, statSync }
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { realPath } from "./project.ts";
 import { foldSegment } from "./permission-mode.ts";
+/**
+ * Whether `rel`, the result of `relative(root, path)`, names something inside the root: not `..`, not a path that starts with a `..` SEGMENT, and not absolute.
+ * A string prefix test is wrong here: `..ignored/f.txt` is a valid directory named `..ignored` inside the project (#552), while `../f.txt` leaves it.
+ * An empty `rel` is the root itself, which is inside; callers that need a file name check for it themselves.
+ */
+export const insideRoot = (rel: string): boolean => rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+
 /** Bounded project-relative exact paths/subtrees or *, ? and whole-segment ** globs. */
 export function policyPaths(raw: unknown, field: string): string[] {
   if (raw === undefined) return [];