@staix/agent-hub 0.17.0 → 0.19.0

package/src/hub/operational-authority.ts

@@ -0,0 +1,67 @@
+import type { SettingDef } from "./settings.ts";
+
+/** Existing live registry rows only. A new registry key never inherits conductor authority from a prefix. */
+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",
+] 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);
+
+/** Host registry identity must still match the exact live data leaf. This is policy, never proof of the caller's role. */
+export function operationalSetting(def: Pick<SettingDef,"key"|"path"|"applies"|"store"|"locked">): boolean {
+  return !def.locked && def.applies==="live" && def.store==="config" && def.path.join(".")===def.key && operationalSettingKey(def.key);
+}
+
+/** Roster participation uses its existing lifecycle-aware write, independently of generic settings set. */
+export function operationalRosterSetting(def: Pick<SettingDef,"key"|"path"|"applies"|"store"|"locked"|"group">): boolean {
+  return !def.locked && def.group==="Roster" && def.applies==="live" && def.store==="config"
+    && def.path.length===2 && def.path[0]==="roster" && typeof def.path[1]==="string"
+    && /^[a-z][a-z0-9-]{0,31}$/.test(def.path[1]) && def.key===`roster.${def.path[1]}`;
+}
+
+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";
+
+/** 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==="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==="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";
+  return undefined;
+}
+
+
+/** Only a failed conductor/operational authority fence carries this marker, never an ordinary operation error. */
+export class OperationalAuthorityError extends Error {
+  readonly code = "AHUB_OPERATIONAL_AUTHORITY";
+  constructor(message:string,readonly scope:"conductor"|"person"|"operational"="operational") { super(message); }
+}
+
+export const OPERATIONAL_PERSON_GUIDANCE="the person runs it in ahub console or a terminal";
+export function operationalRefusal(peer:string,command:string):string {
+  return `${peer} cannot run ahub ${command}; ${OPERATIONAL_PERSON_GUIDANCE}; this operation requires the explicit conductor role`;
+}
+/** 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";
+    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==="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-view.ts

@@ -0,0 +1,137 @@
+import { sanitize } from "./envelope.ts";
+import type { BusEvent } from "./bus.ts";
+import { CLASSES, type Task } from "./board.ts";
+
+export interface OperationalViewPorts {
+  tasks: readonly Task[];
+  isPii(task:Task):boolean;
+  publicView(task:Task):Record<string,unknown>;
+  publicMetadataText(text:string):boolean;
+  redact(record:unknown):unknown;
+}
+/** Closed metadata receipts only. Unsupported nested records are withheld until given their own projection. */
+const EVENT_FIELDS: Record<string,readonly string[]>={
+  state:["peer","state"],hub_start:["instance"],native_thread:["peer","thread","fresh"],turn_start:["peer","turn"],native_turn_end:["peer","id"],
+  task:["id","event","by","state","owner","reviewer","class","profile","profileClass","role","pii","reason","release","priority","plannedStart","due"],
+  tokens:["peer","n","task","attribution","pii"],
+  usage:["peer","source","id","task","attribution","pii","reasoningTokens","measuredAt","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","totalTokens"],
+  turn_end:["peer","turn","ms","tokens","files","snapshotMs","task","attribution","pii"],
+  conduct:["peer","action","task","target"],agent_cli:["peer","command","refused","delegated"],
+  pii_screen:["task","item","label","source","category","miss","ms"],
+  overflow:["id","from","peer"],undeliverable:["id","from","peer"],stale:["id","from","peer","task"],quiet:["id","from","peers"],
+  envelope:["id","from","to","priority","hop","kind","task","bytes","private","dropped"],
+  memory_brief:["source","peer","task","native","fails","claudeMem"],
+  fact:["peer","id","files","plans","unknown","named","bytes","via","ms","hookMs","rttMs","accepted","unanswered","probe","coverage"],
+  fact_ack:["peer","id","via","ms"],permission_mode:["peer","from","to"],
+  permission:["id","peer","event","latencyMs","surface","option"],
+  supervision_turn:["peer","turn","tokens","ms"],hook_stats:["peer","n","startupMs","hubMs","maxStartupMs"],
+  capability:["peer","state","via"],cohort:["id","event","silent","tasks","owners"],
+  planning:["by","task","release","fields","revision"],context_pressure:["peer","source","measuredAt","used","window"],
+  budget_pause:["peer","reason","window","resetsAt","by"],budget_resume:["peer","reason","window","resetsAt","by"],
+  quota_reset:["peer","window","cause","resetsAt","used","previousUsed","previousResetsAt","measuredAt"],
+};
+const EVENT_REQUIRED:Record<string,readonly string[]>={
+  state:["peer","state"],hub_start:["instance"],native_thread:["peer","thread","fresh"],turn_start:["peer","turn"],native_turn_end:["peer"],
+  task:["id","event","by","state","owner","reviewer","class","pii"],tokens:["peer","n"],usage:["peer","source","id"],turn_end:["peer","turn","ms"],
+  conduct:["peer","action"],agent_cli:["peer","command","refused"],pii_screen:["item","label","source"],
+  overflow:["id","from","peer"],undeliverable:["id","from","peer"],stale:["id","from","peer"],quiet:["id","from","peers"],envelope:["id","from","priority","hop"],
+  memory_brief:["peer","task","native","fails","claudeMem"],fact:["peer","id","files","plans","unknown","named","bytes","via"],fact_ack:["peer","id","via","ms"],
+  permission_mode:["peer","from","to"],permission:["id","peer","event"],supervision_turn:["peer","turn"],hook_stats:["peer","n","startupMs","hubMs","maxStartupMs"],
+  capability:["peer","state"],cohort:["id","event","silent","tasks","owners"],planning:["by","fields","revision"],context_pressure:["peer","source","measuredAt","used","window"],
+  budget_pause:["peer","reason","window","resetsAt","by"],budget_resume:["peer","reason","window","resetsAt","by"],quota_reset:["peer","window","cause","used","previousUsed"],
+};
+const NUMBERS=new Set(["n","ms","tokens","files","snapshotMs","reasoningTokens","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","totalTokens","hop","bytes","native","fails","claudeMem","plans","unknown","named","hookMs","rttMs","latencyMs","startupMs","hubMs","maxStartupMs","used","previousUsed","previousResetsAt","resetsAt","plannedStart","due","revision"]);
+const BOOLEANS=new Set(["pii","private","fresh","refused","delegated","accepted","unanswered","probe","coverage","silent"]);
+const TASK_EVENTS=new Set(["proposed","backlogged","backlog pulled","backlog returned","accepted","assigned","reassigned","unassigned","reserved","ready","blocked","declined","escalated","done","approved","changes_requested","cancelled","lifecycle"]);
+const identifier=(value:unknown):value is string=>typeof value==="string" && /^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/.test(value);
+const peerId=(value:unknown):value is string=>typeof value==="string" && /^[a-z][a-z0-9-]{0,63}$/.test(value);
+const oneOf=(value:unknown,values:readonly string[])=>typeof value==="string" && values.includes(value);
+function metadataValue(type:string,key:string,value:unknown):boolean {
+  if(value===null && ["plannedStart","due"].includes(key))return true;
+  if(NUMBERS.has(key))return typeof value==="number" && Number.isFinite(value) && value>=0;
+  if(BOOLEANS.has(key))return typeof value==="boolean";
+  if(["peer","owner","reviewer","target","by"].includes(key))return value===null && ["owner","reviewer"].includes(key) || peerId(value);
+  if(key==="from" || key==="to")return type==="permission_mode"?oneOf(value,["ask","ask-when-needed","never-ask"]):key==="to"?Array.isArray(value)&&value.length<=64&&value.every(peerId):peerId(value);
+  if(["peers","owners"].includes(key))return Array.isArray(value)&&value.length<=64&&value.every(peerId);
+  if(key==="tasks")return Array.isArray(value)&&value.length<=500&&value.every(positive);
+  if(key==="task" || key==="release")return key==="release"&&value===null || positive(value) || key==="task"&&typeof value==="string"&&/^[1-9][0-9]*$/.test(value);
+  if(key==="id")return type==="task" || type==="cohort"?positive(value):identifier(value);
+  if(key==="class")return oneOf(value,CLASSES);
+  if(key==="profile")return oneOf(value,["dev","research","writing","general"]);
+  if(key==="profileClass")return typeof value==="string" && /^[a-z][a-z0-9_]{0,47}$/.test(value);
+  if(key==="state")return type==="task"?oneOf(value,["backlog","proposed","in_progress","in_review","approved","changes_requested","cancelled"]):type==="capability"?oneOf(value,["verified","lost"]):oneOf(value,["idle","busy","paused","offline"]);
+  if(key==="event")return type==="task"?typeof value==="string"&&TASK_EVENTS.has(value):type==="cohort"?oneOf(value,["formed","joined","lifted"]):oneOf(value,["requested","answered","expired","cancelled"]);
+  if(key==="attribution")return oneOf(value,["delivery","single_open","unattributed"]);
+  if(key==="label")return oneOf(value,["pii","clear"]);
+  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==="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"]);
+  if(key==="fields")return Array.isArray(value)&&value.length<=32&&value.every(identifier);
+  if(["action","command","reason"].includes(key))return typeof value==="string" && /^[a-z][a-z0-9_ .:-]{0,63}$/.test(value);
+  return identifier(value);
+}
+
+/** Shared by the daemon's existing console stream and operational projection tests. */
+export function redactBusEvent(e:BusEvent):BusEvent {
+  if (!("env" in e) || !e.env.private) return e;
+  const {refs,...env}=e.env;
+  const task=refs?.task && /^[0-9]+$/.test(refs.task)?refs.task:undefined;
+  return {...e,env:{...env,...(task?{refs:{task}}:{}),body:`[private${task?`: task #${task}, see ahub task show ${task}`:""}]`}};
+}
+const WITHHELD="[withheld: private or unclassifiable operational record]";
+const positive=(value:unknown):value is number=>Number.isSafeInteger(value) && (value as number)>0;
+
+/** Bind the existing task/privacy projections once per read; no private title or path leaves this closure. */
+export function operationalView(ports:OperationalViewPorts) {
+  const publicTasks=new Set<number>();
+  const privateTitles:string[]=[];
+  // The caller caches this complete inventory by board/privacy revision; there is no task-count display ceiling.
+  let known=true;
+  try {for(const task of ports.tasks) {const view=ports.publicView(task);if(ports.isPii(task) || view.title!==task.title) privateTitles.push(task.title);else publicTasks.add(task.id);}} catch {known=false;}
+  const safeTask=(id:number):boolean=>known && publicTasks.has(id);
+  const safeText=(text:string):boolean=>{
+    if (!known || Buffer.byteLength(text)>65536 || privateTitles.some(title=>title && text.includes(title))) return false;
+    try {return ports.publicMetadataText(text);} catch {return false;}
+  };
+  const line=(value:unknown):string=>{
+    if (typeof value!=="string" || !safeText(value)) return WITHHELD;
+    for(const match of value.matchAll(/\btask\s+#?([1-9][0-9]*)\b/gi)) if(!safeTask(Number(match[1])))return WITHHELD;
+    return sanitize(value);
+  };
+  const event=(value:unknown):Record<string,unknown>=>{
+    const withheld={type:"withheld"};
+    try {
+      if (!value || typeof value!=="object" || Array.isArray(value)) return withheld;
+      const raw=value as Record<string,unknown>;
+      if(raw.v!==1 || typeof raw.at!=="string" || !Number.isFinite(Date.parse(raw.at)) || typeof raw.type!=="string")return withheld;
+      const fields=EVENT_FIELDS[raw.type];
+      if(!fields || !Object.hasOwn(EVENT_FIELDS,raw.type))return withheld;
+      const allowed=new Set(["v","at","type",...fields]);
+      if(Object.keys(raw).some(key=>!allowed.has(key)) || EVENT_REQUIRED[raw.type]!.some(key=>!Object.hasOwn(raw,key) || raw[key]===undefined))return withheld;
+      if(fields.some(key=>raw[key]!==undefined && !metadataValue(raw.type as string,key,raw[key])))return withheld;
+      if (raw.pii===true || raw.private===true) return withheld;
+      const ids:unknown[]=[];
+      if (raw.type==="task") ids.push(raw.id);
+      if (raw.task!==undefined) ids.push(typeof raw.task==="string" && /^[1-9][0-9]*$/.test(raw.task)?Number(raw.task):raw.task);
+      if (raw.type==="conflict") ids.push(raw.other);
+      if (raw.type==="overlap") {
+        if(!Array.isArray(raw.others))return withheld;
+        for(const other of raw.others) {if(!other || typeof other!=="object")return withheld;ids.push(other.task);}
+      }
+      if(raw.type==="cohort") {if(!Array.isArray(raw.tasks))return withheld;ids.push(...raw.tasks);}
+      if(ids.some(id=>!positive(id) || !safeTask(id)))return withheld;
+      const redacted=ports.redact(value);
+      if(!redacted || typeof redacted!=="object" || Array.isArray(redacted))return withheld;
+      const projected=Object.fromEntries(["v","at","type",...fields].filter(key=>Object.hasOwn(redacted,key)).map(key=>[key,(redacted as Record<string,unknown>)[key]]));
+      const text=JSON.stringify(projected);
+      if(!safeText(text))return withheld;
+      // Rebuild through JSON, then sanitize every rendered string, including metadata strings.
+      return JSON.parse(text,(_key,item)=>typeof item==="string"?sanitize(item):item) as Record<string,unknown>;
+    } catch {return withheld;}
+  };
+  return {line,event,complete:known,...(!known?{incompleteReason:"privacy inventory unavailable"}: {})};
+}

package/src/hub/orphan-process.ts

@@ -0,0 +1,69 @@
+import { lstatSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { processLiveness, type Liveness } from "../pi/process-signature.ts";
+import type { Project } from "./registry.ts";
+import type { ControlDescriptor } from "./control-client.ts";
+
+export interface OrphanSelection { root:string; projectId:string; instanceId:string; pid:number; executable:string; programs:readonly string[] }
+export interface SignedOrphan { pid:number; signature:string; root:string; projectId:string; instanceId:string; self:boolean }
+export interface OrphanPorts {
+  rootState(root:string):"missing"|"present"|"unknown";
+  liveness(pid:number,signature:string):Liveness;
+  command(pid:number):string|undefined;
+  signal(pid:number,signal:"SIGTERM"|"SIGKILL"):void;
+  current():void;
+  now():number;
+  sleep(ms:number):Promise<unknown>;
+}
+export const orphanProcessPorts: OrphanPorts = {
+  rootState(root) { try {lstatSync(root);return "present";} catch(error) {return ["ENOENT","ENOTDIR"].includes((error as NodeJS.ErrnoException).code??"")?"missing":"unknown";} },
+  liveness:processLiveness,
+  command(pid) {const r=spawnSync("/bin/ps",["-p",String(pid),"-o","command="],{encoding:"utf8",timeout:2000,maxBuffer:65536});return r.status===0?r.stdout.trim()||undefined:undefined;},
+  signal:(pid,signal)=>process.kill(pid,signal),current:()=>{throw new Error("conductor authority unavailable");},now:Date.now,sleep:ms=>Bun.sleep(ms),
+};
+
+/** Host-known Bun executable and hub entrypoint only; joined argv cannot prove paths containing whitespace. */
+export function exactOrphanCommand(command:string|undefined,selection:Pick<OrphanSelection,"root"|"executable"|"programs">):boolean {
+  if (!command || [selection.root,selection.executable,...selection.programs].some(word=>/\s/.test(word))) return false;
+  const words=command.trim().split(/\s+/);
+  return words[0]===selection.executable && selection.programs.includes(words[1]??"") && words[2]==="--project"
+    && words[3]===selection.root && words[4]==="daemon" && (words.length===5 || words.length===6 && words[5]==="--unattended");
+}
+function owns(candidate:SignedOrphan,selection:OrphanSelection,ports:OrphanPorts):boolean {
+  ports.current();
+  return candidate.root===selection.root && candidate.projectId===selection.projectId && candidate.instanceId===selection.instanceId && ports.rootState(selection.root)==="missing"
+    && ports.liveness(candidate.pid,candidate.signature)==="live" && exactOrphanCommand(ports.command(candidate.pid),selection)
+    // Recheck the signature after argv inspection, immediately before the caller may signal.
+    && ports.liveness(candidate.pid,candidate.signature)==="live";
+}
+/** Host-selected project only. Unsigned legacy pid files are never conductor signal authority. */
+export function inspectSelectedOrphans(selection:OrphanSelection,registration:Project|undefined,control:ControlDescriptor|undefined,ports:OrphanPorts=orphanProcessPorts) {
+  ports.current();
+  const root=ports.rootState(selection.root);
+  if (root!=="missing") return {state:root==="present"?"not_orphan" as const:"unknown" as const,candidates:[] as SignedOrphan[]};
+  const proofs:{pid:number|null|undefined;signature:string|null|undefined}[]=[];
+  if (registration?.root===selection.root && registration.id===selection.projectId && registration.instanceId===selection.instanceId) proofs.push({pid:registration.pid,signature:registration.pidSignature});
+  if (control?.cwd===selection.root && control.projectId===selection.projectId && control.instanceId===selection.instanceId && control.pid===selection.pid) proofs.push({pid:control.pid,signature:control.pidSignature});
+  let unknown=proofs.length===0;
+  const candidates:SignedOrphan[]=[];
+  for (const proof of proofs) {
+    if (!Number.isSafeInteger(proof.pid) || proof.pid!<=0 || typeof proof.signature!=="string" || !proof.signature) {unknown=true;continue;}
+    const prior=candidates.find(c=>c.pid===proof.pid);
+    if (prior) {if(prior.signature!==proof.signature){unknown=true;candidates.splice(candidates.indexOf(prior),1);}continue;}
+    const candidate={pid:proof.pid!,signature:proof.signature,root:selection.root,projectId:selection.projectId,instanceId:selection.instanceId,self:proof.pid===selection.pid};
+    if (owns(candidate,selection,ports)) candidates.push(candidate); else if(ports.liveness(candidate.pid,candidate.signature)!=="gone") unknown=true;
+  }
+  return {state:unknown?"unknown" as const:"ready" as const,candidates};
+}
+/** A self candidate is returned for the daemon's existing reply-then-lifecycle-stop path, never self-signalled. */
+export async function stopSelectedOrphan(candidate:SignedOrphan,selection:OrphanSelection,ports:OrphanPorts=orphanProcessPorts):Promise<"stopped"|"self"|"unknown"> {
+  if (!owns(candidate,selection,ports)) return "unknown";
+  if (candidate.pid===selection.pid) return "self";
+  for (const [signal,wait] of [["SIGTERM",3000],["SIGKILL",2000]] as const) {
+    if (!owns(candidate,selection,ports)) return ports.liveness(candidate.pid,candidate.signature)==="gone"?"stopped":"unknown";
+    try {ports.signal(candidate.pid,signal);} catch {return ports.liveness(candidate.pid,candidate.signature)==="gone"?"stopped":"unknown";}
+    const until=ports.now()+wait;
+    while (ports.now()<until) {ports.current();const alive=ports.liveness(candidate.pid,candidate.signature);if(alive==="gone")return "stopped";if(alive!=="live")return "unknown";await ports.sleep(100);}
+  }
+  return ports.liveness(candidate.pid,candidate.signature)==="gone"?"stopped":"unknown";
+}

package/src/hub/permission-mode.ts

@@ -36,7 +36,7 @@ export function permissionGrant(peer: string, mode: PermissionMode, instances?:
   const grant = (catalog?.definitionOf ?? definitionOf)(peer, instances)?.permission.grants?.[mode];
   if (grant !== undefined) return grant;
   if (mode === "ask") return "every write, edit and shell command asks";
-  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";
+  return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write, edit and proven bounded read-only shell commands inside the project run without asking; other shell commands 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. */

package/src/hub/read-only-shell-proof.ts

@@ -0,0 +1,81 @@
+import { accessSync, constants, lstatSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { guardPath, type ShellExecutionCheck } from "../local/tools.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { realPath } from "./project.ts";
+import { parseSimpleShell, readOnlyShellForm, type ReadOnlyProgram } from "./read-only-shell.ts";
+import { hostShellEnvironment } from "../local/shell-environment.ts";
+
+export interface ShellProofOptions { root:string; projectRoot?:string; deny:string[]; readOnly?:string[]; env?:Record<string,string> }
+export interface ReadOnlyShellProof { fingerprint:string; program:ReadOnlyProgram; executable:string; argv:readonly string[] }
+const within=(root:string,path:string)=>{const p=relative(root,path);return p==="" || p!==".."&&!p.startsWith("../")&&!isAbsolute(p);};
+function firstProgram(name:string,root:string,path:string):string|undefined {
+  if(path.length>16384)return undefined;
+  const dirs=path.split(":");if(dirs.length>128)return undefined;
+  for(const dir of dirs) {
+    // Bash consumes the original PATH: do not normalize an ambiguous entry into a different program.
+    if(!isAbsolute(dir) || dir.split("/").includes(".."))return undefined;
+    const candidate=resolve(root,dir,name);
+    try {accessSync(candidate,constants.X_OK);if(lstatSync(candidate).isDirectory())continue;return candidate;}catch{/* Try only the next actual PATH entry. */}
+  }
+  return undefined;
+}
+function stamp(path:string,program:boolean):unknown {
+  try {const s=lstatSync(path);return program?[path,s.dev,s.ino,s.mode,s.size,s.mtimeMs,s.ctimeMs]:[path,s.dev,s.ino,s.mode];}catch(error){if((error as NodeJS.ErrnoException).code==="ENOENT")return [path,"missing"];throw error;}
+}
+function ancestors(path:string,stop:string):string[] {
+  const out=[path];for(let n=0;path!==stop && n<64;n++){const parent=dirname(path);if(parent===path)break;path=parent;out.push(path);}return out;
+}
+// Git's subsection names retain case. Expand the literal letters so the entire anchored key pattern is case-insensitive.
+const GIT_HELPER_KEYS = /^(core\.fsmonitor|log\.showsignature|gpg\.(program|.+\.program)|diff\.(external|.+\.(command|textconv))|format\.pretty|pretty\..+)$/.source
+  .replace(/[a-z]/g, letter => `[${letter}${letter.toUpperCase()}]`);
+/** No config values escape this predicate. Accept only the two exact helper overrides injected by the core. */
+export function gitHelpersUnconfigured(git:string,cwd:string,env:NodeJS.ProcessEnv,current:()=>boolean):boolean {
+  if(!current() || Object.keys(env).some(key=>key==="GIT_CONFIG_COUNT"||key==="GIT_CONFIG_PARAMETERS"||key.startsWith("GIT_CONFIG_KEY_")||key.startsWith("GIT_CONFIG_VALUE_")))return false;
+  const argv=hubGitArgv(["-C",cwd,"config","--show-scope","--get-regexp",GIT_HELPER_KEYS]);
+  const result=spawnSync(git,argv.slice(1),{cwd,env:hubGitEnv(env),encoding:"utf8",timeout:1000,maxBuffer:16384,stdio:["ignore","pipe","pipe"]});
+  if(!current() || result.error || result.status!==0 || !result.stdout.endsWith("\n"))return false;
+  return result.stdout === "command\tcore.fsmonitor false\ncommand\tdiff.external \n";
+}
+/** A proof is private host metadata, never an argv/env rewrite or an authorization by itself. */
+export function proveReadOnlyShell(input:unknown,options:ShellProofOptions,current:()=>boolean):ReadOnlyShellProof|undefined {
+  try {
+    if(!current() || !input || typeof input!=="object" || Array.isArray(input))return undefined;
+    const args=input as Record<string,unknown>;if(typeof args.command!=="string")return undefined;
+    if(args.timeout_s!==undefined && (!Number.isFinite(args.timeout_s)||typeof args.timeout_s!=="number"||args.timeout_s<1||args.timeout_s>600))return undefined;
+    const root=realPath(options.root),projectRoot=realPath(options.projectRoot??options.root),names:string[]=[root,projectRoot];
+    const form=readOnlyShellForm(args.command,root,(path,base=root)=>{if(path.split("/").includes(".."))throw new Error("ambiguous parent traversal");const lexical=resolve(base,path),canonical=guardPath({cwd:root,deny:options.deny,readOnly:options.readOnly},lexical,"read");names.push(lexical,canonical);return canonical;});
+    if(!form || !current())return undefined;
+    const env=hostShellEnvironment(options.env);
+    const lexical=firstProgram(form.program,root,env.PATH);if(!lexical || within(root,lexical) || within(projectRoot,lexical))return undefined;
+    const executable=hostExecutable(form.program,root,env.PATH);if(realPath(lexical)!==executable || within(projectRoot,executable) || !current())return undefined;
+    if(form.gitCwd && !gitHelpersUnconfigured(executable,form.gitCwd,env,current))return undefined;
+    // ponytail: this screens the declared helper-bearing config keys and explicit diff/textconv flags; other config-mediated helpers need dedicated audited forms before extending the allowlist.
+    const paths=new Set([...names.flatMap(name=>ancestors(name,root)),...ancestors(lexical,"/"),...ancestors(executable,"/")]);
+    const fingerprint=createHash("sha256").update(JSON.stringify([root,projectRoot,args.command,env,lexical,executable,[...paths].map(path=>stamp(path,path===lexical||path===executable))])).digest("hex");
+    const argv=parseSimpleShell(args.command)!.words.slice(1);
+    return current()?{fingerprint,program:form.program,executable,argv}:undefined;
+  } catch {return undefined;}
+}
+interface Decision { command:string; current:()=>boolean; proof?:ReadOnlyShellProof }
+export class ShellExecutionProofs {
+  private decisions=new WeakMap<object,Decision>();
+  constructor(private readonly options:ShellProofOptions){}
+  private key(input:unknown):input is Record<string,unknown>{return !!input&&typeof input==="object"&&!Array.isArray(input)&&typeof (input as Record<string,unknown>).command==="string";}
+  ordinary(input:unknown,current:()=>boolean):void {if(this.key(input))this.decisions.set(input,{command:input.command as string,current});}
+  readonly(input:unknown,proof:ReadOnlyShellProof,current:()=>boolean):void {if(this.key(input))this.decisions.set(input,{command:input.command as string,current,proof});}
+  check(input:unknown):ShellExecutionCheck {
+    if(!this.key(input))return "ask";const decision=this.decisions.get(input);
+    if(!decision)return "ask";
+    if(!decision.current())return "aborted";
+    if(input.command!==decision.command)return "ask";
+    if(!decision.proof)return "valid";
+    const proof=proveReadOnlyShell(input,this.options,decision.current);
+    if(!decision.current())return "aborted";
+    if(!proof || proof.fingerprint!==decision.proof.fingerprint){this.decisions.delete(input);return "ask";}
+    return "valid";
+  }
+}

package/src/hub/read-only-shell.ts

@@ -0,0 +1,162 @@
+/** Lexical data only. A successful parse grants no permission and proves no program read-only. */
+export interface SimpleShellWords {
+  words: readonly string[];
+  /** Syntax-looking characters survived as quoted/escaped data; the grant policy must decide whether to accept them. */
+  quotedMeta: boolean;
+}
+export const READ_ONLY_SHELL_LIMITS = { characters: 4000, words: 128 } as const;
+const ACTIVE = ";|&<>`$(){}*?[]~#";
+
+/** One bounded literal command, without active operators or expansion. Never executes or resolves any word. */
+export function parseSimpleShell(command: unknown): SimpleShellWords | undefined {
+  if (typeof command !== "string" || command.length > READ_ONLY_SHELL_LIMITS.characters
+    || command.includes("\n") || command.includes("\r") || command.includes("\0")) return undefined;
+  const words: string[] = [];
+  let word = "", started = false, quote: "" | "'" | '"' = "", quotedMeta = false;
+  const append = (character: string, literal = false) => {
+    word += character;
+    started = true;
+    if (literal && (ACTIVE.includes(character) || character === "\\")) quotedMeta = true;
+  };
+  const finish = () => {
+    if (!started) return true;
+    words.push(word);
+    word = ""; started = false;
+    return words.length <= READ_ONLY_SHELL_LIMITS.words;
+  };
+  for (let i = 0; i < command.length; i++) {
+    const character = command[i]!;
+    if (quote === "'") {
+      if (character === "'") quote = "";
+      else append(character, true);
+      continue;
+    }
+    if (quote === '"') {
+      if (character === '"') { quote = ""; continue; }
+      if (character === "$" || character === "`") return undefined;
+      if (character === "\\") return undefined;
+      append(character, true);
+      continue;
+    }
+    if (character === " " || character === "\t") { if (!finish()) return undefined; continue; }
+    if (character === "'" || character === '"') { quote = character; started = true; continue; }
+    if (character === "\\") {
+      const next = command[++i];
+      if (next === undefined) return undefined;
+      append(next, true);
+      continue;
+    }
+    if (ACTIVE.includes(character) && !(character === "~" && started)) return undefined;
+    append(character);
+  }
+  if (quote || !finish() || !words.length) return undefined;
+  if (/^[A-Za-z_][A-Za-z0-9_]*[+]?=/.test(words[0]!)) return undefined;
+  return { words, quotedMeta };
+}
+
+export const READ_ONLY_PROGRAMS = ["ls","cat","head","tail","wc","rg","grep","stat","file","tree","pwd","find","git"] as const;
+export type ReadOnlyProgram = typeof READ_ONLY_PROGRAMS[number];
+export interface ReadOnlyShellForm { program:ReadOnlyProgram; paths:readonly string[]; gitCwd?:string }
+type FlagKind = "none"|"number"|"pattern"|"path";
+const flags=(none:string[],values:Record<string,FlagKind>={}):Record<string,FlagKind>=>Object.assign(Object.fromEntries(none.map(flag=>[flag,"none"])),values);
+const numberArg=(value:string)=>/^[0-9]{1,7}$/.test(value) && Number(value)<=1_000_000;
+function options(args:string[],rules:Record<string,FlagKind>,path:(value:string)=>void) {
+  const positional:string[]=[],seen=new Set<string>();let ended=false;
+  for(let i=0;i<args.length;i++) {
+    const word=args[i]!;
+    if(!ended && word==="--"){ended=true;continue;}
+    if(ended || !word.startsWith("-") || word==="-"){positional.push(word);continue;}
+    let key=word,value:string|undefined;
+    if(word.startsWith("--") && word.includes("=")){const at=word.indexOf("=");key=word.slice(0,at);value=word.slice(at+1);}
+    if(!Object.hasOwn(rules,key) && /^-[^-].+/.test(word)) {
+      const letters=word.slice(1);let consumed=false;
+      for(let n=0;n<letters.length;n++) {
+        const short=`-${letters[n]}`;
+        if(!Object.hasOwn(rules,short))return undefined;
+        seen.add(short);
+        if(rules[short]!=="none") {key=short;value=letters.slice(n+1)||args[++i];consumed=true;break;}
+      }
+      if(!consumed)continue;
+    }
+    if(!Object.hasOwn(rules,key))return undefined;
+    seen.add(key);const kind=rules[key]!;
+    if(kind==="none"){if(value!==undefined)return undefined;continue;}
+    value??=args[++i];if(value===undefined || value.startsWith("-") || kind==="number"&&!numberArg(value))return undefined;
+    if(kind==="path")path(value);
+  }
+  return {positional,seen};
+}
+
+/** Structural allowlist only; the host must still prove executable identity, paths, config and current authority. */
+export function readOnlyShellForm(command:unknown,root:string,readPath:(path:string,base?:string)=>string):ReadOnlyShellForm|undefined {
+  try {
+    const parsed=parseSimpleShell(command);if(!parsed)return undefined;
+    const [name,...args]=parsed.words;
+    if(!READ_ONLY_PROGRAMS.includes(name as ReadOnlyProgram))return undefined;
+    const program=name as ReadOnlyProgram,paths:string[]=[];
+    const path=(value:string,base=root)=>{if(value!=="-")paths.push(readPath(value,base));};
+    path(".");
+    if(program==="git") {
+      let cwd=root,i=0;
+      while(i<args.length){if(args[i]==="--no-pager"||args[i]==="--no-optional-locks"){i++;continue;}if(args[i]==="-C"&&args[i+1]!==undefined){cwd=readPath(args[i+1]!,cwd);paths.push(cwd);i+=2;continue;}break;}
+      const sub=args[i++],rest=args.slice(i);
+      const ref=(value:string)=>{
+        if(!value || value.startsWith("-") || value.startsWith("/") || value.startsWith("~") || value.includes("..")&&value.startsWith("."))throw new Error("unknown revision");
+        if(value.startsWith(":") || /[*?\[\]]/.test(value))throw new Error("unresolved pathspec");
+        const colon=value.indexOf(":");if(colon>=0)path(value.slice(colon+1),cwd);else path(value,cwd);
+      };
+      if(sub==="branch") {if(rest[0]!=="--list" || rest.slice(1).some(a=>a.startsWith("-")))return undefined;return {program,paths,gitCwd:cwd};}
+      if(sub==="cat-file") {if(rest.length!==2||!["-p","-t","-s"].includes(rest[0]!))return undefined;ref(rest[1]!);return {program,paths,gitCwd:cwd};}
+      // These commands do not accept both required diff-disabling flags, so their shell forms keep asking.
+      if(sub==="blame"||sub==="grep")return undefined;
+      let rule:Record<string,FlagKind>;
+      if(sub==="status")rule=flags(["-s","-b","--short","--branch","--porcelain","--ignored"],{"--untracked-files":"pattern"});
+      else if(sub==="rev-parse")rule=flags(["--show-toplevel","--git-dir","--is-inside-work-tree","--show-prefix","--verify","--short"]);
+      else if(sub==="ls-files")rule=flags(["-z","--cached","--deleted","--modified","--others","--exclude-standard","--stage","--error-unmatch"]);
+      else if(sub==="describe")rule=flags(["--always","--tags","--long","--all","--dirty"],{"--abbrev":"number","--match":"pattern","--exclude":"pattern"});
+      else if(sub==="log"||sub==="diff"||sub==="show") {
+        rule=flags(["--no-ext-diff","--no-textconv","--no-patch","--oneline","--all","--decorate","--no-decorate","--name-only","--name-status","--stat","-p","--patch","--cached","--staged"],{"-n":"number","--max-count":"number"});
+      } else return undefined;
+      const parsedArgs=options(rest,rule,value=>path(value,cwd));if(!parsedArgs)return undefined;
+      const patch=sub==="diff" || sub==="show" || sub==="log" && ["-p","--patch","--stat"].some(flag=>parsedArgs.seen.has(flag));
+      if(patch && !(parsedArgs.seen.has("--no-ext-diff")&&parsedArgs.seen.has("--no-textconv")))return undefined;
+      for(const value of parsedArgs.positional)ref(value);
+      return {program,paths,gitCwd:cwd};
+    }
+    if(program==="find") {
+      let i=0,depth=0;while(i<args.length && !args[i]!.startsWith("-") && !["(",")","!"].includes(args[i]!))path(args[i++]!);
+      for(;i<args.length;i++) {
+        const value=args[i]!;
+        if(value==="("){if(++depth>16)return undefined;continue;}if(value===")"){if(--depth<0)return undefined;continue;}
+        if(["!","-a","-o","-not","-print","-print0","-ls","-depth"].includes(value))continue;
+        if(["-name","-iname","-path","-ipath","-regex","-iregex"].includes(value)){if(args[++i]===undefined)return undefined;continue;}
+        if(value==="-type"){if(!["f","d","l","b","c","p","s"].includes(args[++i]??""))return undefined;continue;}
+        if(["-maxdepth","-mindepth"].includes(value)){if(!numberArg(args[++i]??""))return undefined;continue;}
+        if(["-newer","-samefile"].includes(value)){if(args[i+1]===undefined)return undefined;path(args[++i]!);continue;}
+        return undefined;
+      }
+      return depth===0?{program,paths}:undefined;
+    }
+    let rule:Record<string,FlagKind>;
+    if(program==="ls")rule=flags(["-a","-A","-l","-h","-1","-d","-F","-i","-p","-r","-R","-s","-S","-t","-u"]);
+    else if(program==="cat")rule=flags(["-b","-e","-n","-s","-t","-u","-v"]);
+    else if(program==="head"||program==="tail")rule=flags(["-q","-v"],{"-n":"number","-c":"number","--lines":"number","--bytes":"number"});
+    else if(program==="wc")rule=flags(["-c","-l","-m","-w","-L"]);
+    else if(program==="stat")rule=flags(["-L"]);
+    else if(program==="file")rule=flags(["-b","-i","-L","-h"]);
+    else if(program==="pwd")rule=flags(["-L","-P"]);
+    else if(program==="tree")rule=flags(["-a","-d","-f","-i","-p","-s","-h","-D","-F","-q","-N","-n","--noreport","--dirsfirst"],{"-L":"number","-I":"pattern","-P":"pattern"});
+    else if(program==="rg")rule=flags(["-n","-l","-i","-w","-s","-S","-F","-v","-H","-h","-o","-0","-q","-c","-u","-U","-a","--files","--hidden","--no-ignore","--no-heading","--line-number","--files-with-matches","--count","--ignore-case","--fixed-strings"],{"-e":"pattern","--regexp":"pattern","-f":"path","--file":"path","-g":"pattern","--glob":"pattern","--iglob":"pattern","-t":"pattern","--type":"pattern","-T":"pattern","--type-not":"pattern","-m":"number","--max-count":"number","--max-depth":"number","-A":"number","-B":"number","-C":"number"});
+    else if(program==="grep")rule=flags(["-n","-l","-i","-w","-x","-F","-E","-v","-H","-h","-o","-c","-q","-s","-r"],{"-e":"pattern","-f":"path","-A":"number","-B":"number","-C":"number","-m":"number","--include":"pattern","--exclude":"pattern","--exclude-dir":"pattern"});
+    else return undefined;
+    const parsedArgs=options(args,rule,path);if(!parsedArgs)return undefined;
+    const operands=[...parsedArgs.positional];
+    if(program==="pwd" && operands.length)return undefined;
+    if(program==="rg"||program==="grep") {
+      const pattern=parsedArgs.seen.has("-e")||parsedArgs.seen.has("--regexp")||parsedArgs.seen.has("-f")||parsedArgs.seen.has("--file")||parsedArgs.seen.has("--files");
+      if(!pattern && operands.shift()===undefined)return undefined;
+    }
+    for(const value of operands)path(value);
+    return {program,paths};
+  } catch {return undefined;}
+}

package/src/hub/review-scope.ts

@@ -0,0 +1,13 @@
+/**
+ * #852: a reviewer's review scope. `full` reads the code, runs the affected tests and reads CI; `code` reads the code only, because its sandbox
+ * cannot run tests or read CI. AC3 (amended 2026-10-26) is structural, never a reading of free text: a `code` reviewer's changes_requested is always
+ * recorded, and one with no open structured finding is recorded as evidence-only (see Tasks.review).
+ */
+export type ReviewScope = "full" | "code";
+export const REVIEW_SCOPES: readonly ReviewScope[] = ["full", "code"];
+export const isReviewScope = (value: unknown): value is ReviewScope => value === "full" || value === "code";
+
+/** The one review-request line for a `code` reviewer (AC2). Fixed text: no hub or PR content is interpolated. */
+export const CODE_SCOPE_LINE = "Your sandbox cannot run tests or read CI: review the code against the plan. The merger gates on exact-head CI (#852). Findings are only for defects in the reviewed code, docs or tests. A missing check result, CI result, test run or PR/branch identity is an evidence request: put it in unmet, never in findings. Report every code defect as a structured finding with an id (hub_review findings, disposition open); a verdict with no open finding is recorded as evidence-only and does not count as a rejection.";
+/** The one task notice the conductor gets when a code-scope reviewer's verdict is recorded as evidence-only (ids only, never text). */
+export const evidenceOnlyNotice = (task: number, reviewer: string): string => `Task #${task}: a code-scope review by ${reviewer} was recorded as evidence-only (no open finding) and the task returned to its owner. Take the review.`;

package/src/hub/reviewer-pool-config.ts

@@ -1,4 +1,4 @@
-export interface ReviewerPoolConfig { pool: string[]; rerotate: boolean }
+export interface ReviewerPoolConfig { pool: string[]; rerotate: boolean; sameFamily?: "never" }
 
 /** Kind order is project policy; capability and isolation evidence remain host-owned registry facts. */
 export function reviewerPoolConfig(raw: unknown, defaults: readonly string[], known: readonly string[]): ReviewerPoolConfig {
@@ -7,5 +7,6 @@ export function reviewerPoolConfig(raw: unknown, defaults: readonly string[], kn
   const pool = value.pool === undefined ? defaults : value.pool;
   if (!Array.isArray(pool) || pool.length < 1 || pool.length > 16 || pool.some(kind => typeof kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(kind) || !known.includes(kind)) || new Set(pool).size !== pool.length) throw new Error("review.pool must list 1..16 distinct known kinds");
   if (value.rerotate !== undefined && typeof value.rerotate !== "boolean") throw new Error("review.rerotate must be a boolean");
-  return { pool: [...pool], rerotate: value.rerotate === true };
+  if (value.same_family !== undefined && value.same_family !== "fallback" && value.same_family !== "never") throw new Error("review.same_family must be \"fallback\" or \"never\"");
+  return { pool: [...pool], rerotate: value.rerotate === true, ...(value.same_family === "never" ? { sameFamily: "never" as const } : {}) };
 }

package/src/hub/reviewer-pool.ts

@@ -8,6 +8,8 @@ export interface ReviewerPoolInput {
   continuityFamily?: string;
   rerotate?: boolean;
   failed?: readonly string[];
+  /** `never` (#820): an implementer-family candidate is never selected, not even as the last resort. */
+  sameFamily?: "fallback" | "never";
 }
 export interface ReviewerPoolSelection {
   reviewer: string | null;
@@ -65,6 +67,7 @@ export function selectReviewerPool(input: ReviewerPoolInput): ReviewerPoolSelect
     return finish({ reviewer: candidate.id, family: candidate.family, reason });
   }
   // The caller supplies separate fresh reviewer instances; this does not authorize an implementer's own session.
+  if (input.sameFamily === "never") return finish({ reviewer: null, blocked: "no reviewer can run" });
   for (const candidate of ordered) {
     if (!candidate.id || input.implementerFamily === undefined || candidate.family !== input.implementerFamily) continue;
     const blocked = unavailable(candidate);