@staix/agent-hub 0.16.0 → 0.18.0

package/src/hub/operational-view.ts

@@ -0,0 +1,141 @@
+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 tasks=new Map(ports.tasks.map(task=>[task.id,task]));
+  const privateTitles:string[]=[];
+  // ponytail: a complete privacy inventory is capped at 500 tasks; indexed scoped log records can extend it.
+  let known=ports.tasks.length<=500;
+  try {for(const task of ports.tasks.slice(0,500)) {const view=ports.publicView(task);if(ports.isPii(task) || view.title!==task.title) privateTitles.push(task.title);}} catch {known=false;}
+  const safeTask=(id:number):boolean=>{
+    const task=tasks.get(id);
+    if (!task) return false;
+    try {return !ports.isPii(task) && ports.publicView(task).title===task.title;} catch {return false;}
+  };
+  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};
+}

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,80 @@
+import { accessSync, constants, lstatSync } from "node:fs";
+import { homedir } from "node:os";
+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 { readOnlyShellForm, type ReadOnlyProgram } from "./read-only-shell.ts";
+
+export interface ShellProofOptions { root:string; projectRoot?:string; deny:string[]; readOnly?:string[]; env?:Record<string,string> }
+export interface ReadOnlyShellProof { fingerprint:string; program:ReadOnlyProgram }
+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={PATH:process.env.PATH??"/usr/bin:/bin",HOME:homedir(),LANG:process.env.LANG??"en_US.UTF-8",TERM:"dumb",...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.PATH,lexical,executable,[...paths].map(path=>stamp(path,path===lexical||path===executable))])).digest("hex");
+    return current()?{fingerprint,program:form.program}: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/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);

package/src/hub/routing.ts

@@ -419,7 +419,7 @@ export function assign(
     namedPlanner?: PeerId;
     /** The planner already recorded on the task (525-2): kept while it is still a holder. */
     keptPlanner?: PeerId;
-    reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean };
+    reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean; sameFamily?: "fallback" | "never" };
     candidates?: PeerId[];
     notReviewer?: PeerId;
     waitsFor?: number[];
@@ -602,8 +602,13 @@ export function assign(
       trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
       const reviewOwner = owner ?? opts.notReviewer;
       const automatic = [...new Set([...expandClassPeers(classPeers, states, opts), ...rolePeers])];
-      const ownerFamily = instanceMode && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
+      // #820: the rule needs the owner's family even when no instance is declared (builtin peers have families too).
+      const never = opts.reviewPool?.sameFamily === "never" && reviewOwner !== undefined;
+      const ownerFamily = (instanceMode || never) && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
       const sameFamily = (peer: PeerId) => ownerFamily !== undefined && (opts.adapterCatalog?.familyOf ?? familyOf)(peer, opts.instances) === ownerFamily;
+      // #820: with review.same_family = never, a reviewer of the owner's family is never chosen; the planner or the person reviews instead.
+      const neverSame = never;
+      if (neverSame) trace.push(`  review.same_family = never: no reviewer of the owner's family (${ownerFamily ?? "unknown"}) is chosen; another family, the planner or the person reviews`);
       const independent = ownerFamily === undefined ? [] : automatic.filter(peer => peer !== reviewOwner && !blocked(peer, "reviewer") && !sameFamily(peer));
       const named = opts.namedReviewer;
       const declaredPool = opts.reviewPool && named === undefined ? Object.keys(opts.instances ?? {}).flatMap(id => {
@@ -622,21 +627,25 @@ export function assign(
         const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? (opts.adapterCatalog?.familyOf ?? familyOf)(last.by, opts.instances) : undefined;
         const pr = task.sdlc?.pr;
         const seed = typeof pr === "number" && Number.isSafeInteger(pr) && pr > 0 ? pr : task.id ?? 0;
-        reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed });
+        reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed, ...(neverSame ? { sameFamily: "never" as const } : {}) });
         for (const row of reviewSelection.walk) trace.push(row.id ? `  reviewer pool candidate ${row.id} (${row.family}): ${row.reason}` : `  reviewer pool kind ${row.kind}: ${row.reason}`);
         reviewer = reviewSelection.reviewer ?? "user";
         if (reviewSelection.blocked) {
           trace.push("blocked: no reviewer can run");
           // Optional defaults retain the legacy planner escape when no fresh reviewer can run.
-          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
+          const planners = opts.reviewPool?.required && !neverSame ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && (!neverSame || peerEntry(opts.roles, peer)?.includes("reviewer") === true) && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
           const otherFamily = planners.filter(peer => !sameFamily(peer));
-          const planner = pick(otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
+          const planner = pick(neverSame || otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
           if (planner) {
             reviewer = planner;
             plannerFallback = true;
             trace.push(`  planner fallback: no declared reviewer-only instance is eligible; ${planner} reviews`);
           } else reviewBlocked = true;
         }
+      } else if (neverSame && named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named)) {
+        const reason = `same family as ${reviewOwner}; review.same_family is never`;
+        refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
+        trace.push(`  reviewer candidate ${named}: skipped, ${reason}`);
       } else if (named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named) && independent.length) {
         const reason = `same family as ${reviewOwner}; eligible other-family reviewer available`;
         refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
@@ -645,7 +654,9 @@ export function assign(
         // #223 R1: a declared instance that reviews and does not plan goes first, busy or not.
         const holds = (peer: PeerId, role: string) => opts.roles?.[peer]?.includes(role) === true;
         const dedicated = (peer: PeerId) => !!opts.instances && Object.hasOwn(opts.instances, peer) && holds(peer, "reviewer") && !holds(peer, "planner");
-        const pool = independent.length ? independent : automatic;
+        // Under never the planner escape needs the reviewer role: a peer that plans and does not review is not a reviewer here, class listing or not.
+        const planOnly = (peer: PeerId) => neverSame && holds(peer, "planner") && !holds(peer, "reviewer");
+        const pool = independent.length || neverSame ? independent.filter(peer => !planOnly(peer)) : automatic;
         const ready = named === undefined ? pool.filter(peer => dedicated(peer) && peer !== reviewOwner && !blocked(peer, "reviewer")) : [];
         reviewer = pick(named === undefined ? ready.length ? ready : pool : [named], "reviewer", reviewOwner, named === undefined);
         if (named === undefined && !ready.length && reviewer && holds(reviewer, "planner") && Object.keys(opts.roles ?? {}).some(dedicated)) {
@@ -657,6 +668,12 @@ export function assign(
         sameFamilyFallback = true;
         trace.push(`  same-family fallback: ${reviewer} and ${reviewOwner} share ${ownerFamily}; no eligible other family`);
       }
+      // Under never an exhausted automatic choice (nobody eligible, all offline, no candidate at all) is the person's, never an approval without review.
+      if (neverSame && !reviewer && named === undefined && !reviewSelection) {
+        reviewer = "user";
+        reviewBlocked = true;
+        trace.push("  review.same_family = never: no reviewer of another family and no eligible planner; the person reviews");
+      }
       // I-2 (#525-3): when the peers that implemented this task were the only candidates left, the person reviews. Never a fallback to an implementer.
       if (!reviewer && [...refusals.values()].some(row => row.role === "reviewer" && row.code === "policy" && row.reason === "implemented this task")) {
         reviewer = "user";