@staix/agent-hub 0.15.0 → 0.16.0

package/src/hub/code-facts.ts

@@ -10,9 +10,12 @@ import { releaseTrackedClean } from "./release-worktree.ts";
 
 export interface CodeSymbol { name: string; kind: string; path: string; line: number; endLine?: number; ambiguous: boolean; change: "unknown" }
 export type CodeFactResult<T> = { state: "known"; value: T } | { state: "unknown" };
-export interface CodeLocation { repo: string; head: string; private?: boolean }
+export interface CodeLocation { repo: string; head: string; private?: boolean; priority?: "optional" }
+export const OPTIONAL_CODE_UNKNOWN_TTL_MS = 5000;
 const unknown = (): {state:"unknown"} => ({state:"unknown"});
 const SHA = /^[a-f0-9]{40}$/;
+/** These host anchor spellings have no indexed-name lookup attestation in ripwire 0.6.7. */
+export const unindexedSymbolSyntax = (name: string): boolean => /#|:|->/.test(name);
 // Keep the owned group leader alive after the CLI exits, until the host has stopped every group member.
 const LAUNCHER = String.raw`
 const {writeSync,closeSync}=require("node:fs");
@@ -76,6 +79,9 @@ function changed(raw:string,head:string,base:string,cwd:string): CodeSymbol[] {
 /** Sole optional ripwire boundary. No model/config-selected command, no raw output in results or errors. */
 export class CodeFacts {
   private readonly cache=new Map<string,Promise<CodeFactResult<unknown>>>();
+  private readonly optionalUnknown=new Map<string,number>();
+  private priorityWaiting=0;
+  private active?:{id:string;optional:boolean;cancelled:boolean;done:Promise<void>};
   private busy=false;
   private closing=false;
   private pending?:Promise<CodeFactResult<unknown>>;
@@ -83,13 +89,13 @@ export class CodeFacts {
   private failedChild?:ReturnType<typeof spawn>;
   private retained?:{tree:{cwd:string;close:()=>void};child:ReturnType<typeof spawn>};
   async close():Promise<void> {
-    this.closing=true;this.cancelActive?.();await this.pending;
+    this.closing=true;this.cancelActive?.();await (this.active?.done ?? this.pending);
     if(this.retained){
       try{await stopOwnedProcess(this.retained.child,{group:true,termMs:50,killMs:500});this.retained.tree.close();this.retained=undefined;}
       catch{throw Error("code facts cleanup unconfirmed");}
     }
   }
-  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number}={}) {}
+  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number;now?:()=>number}={}) {}
   private git(repo:string,args:string[]) {
     return hubGitSync(["-C",repo,...args],{encoding:"utf8",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:1024*1024});
   }
@@ -107,7 +113,7 @@ export class CodeFacts {
     return env;
   }
   private async run(bin:string,args:string[],cwd:string):Promise<{code:number;out:string}> {
-    if(this.closing)return {code:1,out:""};
+    if(this.closing || this.active?.cancelled)return {code:1,out:""};
     return new Promise(resolve=>{
       let child:ReturnType<typeof spawn>;
       try{child=spawn(process.execPath,["-e",LAUNCHER,"--",bin,...args],{cwd,env:this.nativeEnv(cwd),detached:true,stdio:["ignore","pipe","ignore","pipe"]});}catch{resolve({code:1,out:""});return;}
@@ -164,29 +170,58 @@ export class CodeFacts {
       return{cwd,close};
     }catch{close();throw Error();}
   }
-  private query<T>(at:CodeLocation,key:string,read:(cwd:string,bin:string)=>Promise<T>):Promise<CodeFactResult<T>> {
-    if(this.closing || this.retained || at.private || !SHA.test(at.head))return Promise.resolve(unknown());
-    let repo:string;try{repo=realPath(at.repo);}catch{return Promise.resolve(unknown());}
-    const id=JSON.stringify([repo,at.head,key]),hit=this.cache.get(id);if(hit)return (hit as Promise<CodeFactResult<T>>).then(value=>structuredClone(value));
-    if(this.busy)return Promise.resolve(unknown());
-    this.busy=true;this.failedChild=undefined;
+  private async query<T>(at:CodeLocation,key:string,read:(cwd:string,bin:string)=>Promise<T>):Promise<CodeFactResult<T>> {
+    if(this.closing || this.retained || at.private || !SHA.test(at.head))return unknown();
+    const optional=at.priority==="optional";
+    // A read-time graph poll must never take the next slot from review/completion work.
+    if(optional && (this.priorityWaiting>0 || this.active && !this.active.optional))return unknown();
+    let repo:string;try{repo=realPath(at.repo);}catch{return unknown();}
+    const id=JSON.stringify([repo,at.head,key]),hit=this.cache.get(id);
+    if(hit && !(this.active?.optional && !optional && this.active.id===id))return structuredClone(await hit) as CodeFactResult<T>;
+    if(!optional && this.active?.optional) {
+      const interrupted=this.active;
+      this.priorityWaiting++;
+      interrupted.cancelled=true;this.cache.delete(interrupted.id);this.cancelActive?.();
+      try{await interrupted.done;}finally{this.priorityWaiting--;}
+      return this.query(at,key,read);
+    }
+    if(optional) {
+      const now=(this.options.now ?? performance.now.bind(performance))(),until=this.optionalUnknown.get(id);
+      if(until!==undefined && until>now)return unknown();
+      this.optionalUnknown.delete(id);
+    }
+    if(this.busy)return unknown(); // Preserve default-vs-default contention semantics.
+    let finished!:()=>void;
+    const active={id,optional,cancelled:false,done:new Promise<void>(resolve=>{finished=resolve;})};
+    this.active=active;this.busy=true;this.failedChild=undefined;
     const job=(async()=>{
       let tree:ReturnType<CodeFacts["tree"]>|undefined;let answer:CodeFactResult<T>=unknown();
       try{
         const found=Bun.which("ripwire",{PATH:(this.options.env??process.env).PATH});if(!found)throw Error();const bin=realPath(found);if(within(repo,bin))throw Error();
         tree=this.tree(repo,at.head);
-        const version=await this.run(bin,["--version"],tree.cwd);if(version.code!==0 || !/^ripwire 0\.6\.7(?:\s|$)/.test(version.out))throw Error();
+        const version=await this.run(bin,["--version"],tree.cwd);if(active.cancelled || version.code!==0 || !/^ripwire 0\.6\.7(?:\s|$)/.test(version.out))throw Error();
         const value=await read(tree.cwd,bin);
-        if(this.value(tree.cwd,["rev-parse","HEAD"])!==at.head || !releaseTrackedClean(tree.cwd,args=>{const r=this.git(tree!.cwd,args);return{code:r.status??1,stdout:r.stdout};}))throw Error();
+        if(active.cancelled || this.value(tree.cwd,["rev-parse","HEAD"])!==at.head || !releaseTrackedClean(tree.cwd,args=>{const r=this.git(tree!.cwd,args);return{code:r.status??1,stdout:r.stdout};}))throw Error();
         answer={state:"known",value};
       }catch{/* Optional derived evidence is unknown, never a review refusal. */}
-      finally{if(tree && this.failedChild){this.retained={tree,child:this.failedChild};answer=unknown();}else try{tree?.close();}catch{answer=unknown();}this.busy=false;}
+      finally{
+        if(tree && this.failedChild){this.retained={tree,child:this.failedChild};answer=unknown();}else try{tree?.close();}catch{answer=unknown();}
+        this.busy=false;if(this.active===active)this.active=undefined;finished();
+      }
       return answer;
     })();
     this.pending=job;this.cache.set(id,job);
     if(this.cache.size>128)this.cache.delete(this.cache.keys().next().value!);
-    void job.then(answer=>{if(answer.state==="unknown" && this.cache.get(id)===job)this.cache.delete(id);});
-    return job.then(value=>structuredClone(value));
+    void job.then(answer=>{
+      if(answer.state==="unknown") {
+        if(this.cache.get(id)===job)this.cache.delete(id);
+        if(optional && !this.closing) {
+          this.optionalUnknown.set(id,(this.options.now ?? performance.now.bind(performance))()+OPTIONAL_CODE_UNKNOWN_TTL_MS);
+          if(this.optionalUnknown.size>128)this.optionalUnknown.delete(this.optionalUnknown.keys().next().value!);
+        }
+      } else this.optionalUnknown.delete(id);
+    });
+    return structuredClone(await job);
   }
   changedSymbols(repo:string,base:string,head:string,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<CodeSymbol[]>> {
     if(!SHA.test(base))return Promise.resolve(unknown());
@@ -205,12 +240,17 @@ export class CodeFacts {
     if(v.of!==symbol || !Number.isSafeInteger(v.defs)||v.defs<1 || !Number.isSafeInteger(v.count)||v.count<0 || !Array.isArray(v[kind])||v.count!==v[kind].length || v.count>MAX_SYMBOLS || realPath(v.root)!==realPath(cwd) || ![0,1,false,true].includes(v.counts_floor)
       || !Number.isSafeInteger(v.hop_tested)||v.hop_tested<0||!Number.isSafeInteger(v.hop_untested)||v.hop_untested<0
       || !Number.isSafeInteger(v.graph_ambiguous)||v.graph_ambiguous<0||!Number.isSafeInteger(v.graph_unresolved)||v.graph_unresolved<0)throw Error();
+    if(v.defs!==1 || v.via!==undefined && v.via!=="resolved")throw Error(); // A name-only or multiply-defined seed is unknown, never a known empty neighbourhood.
     return {defs:v.defs,countsFloor:!!v.counts_floor,items:v[kind].map((s:Record<string,unknown>)=>({...cleanSymbol(s.n,s.t,s.p,s.via),ambiguous:s.via==="name" || v.defs>1 || v.graph_ambiguous>0}))};
   }
   exists(repo:string,head:string,symbol:string,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<{exists:boolean;ambiguous:boolean}>> {
     if(!text(symbol))return Promise.resolve(unknown());
     return this.query({...options,repo,head},`exists:${symbol}`,async(cwd,bin)=>{const r=await this.run(bin,[cwd,`--callers=${symbol}`,"--no-cache"],cwd);
-      if(r.code!==0){const n=xml(r.out);if(n.tag==="callers" && n.attrs.schema==="ripwire.callers/v1" && n.attrs.of===symbol && n.attrs.found==="0")return{exists:false,ambiguous:false};throw Error();}
+      if(r.code!==0){const n=xml(r.out);if(n.tag==="callers" && n.attrs.schema==="ripwire.callers/v1" && n.attrs.of===symbol && n.attrs.found==="0") {
+        // ponytail: ripwire 0.6.7 can miss a qualified name whose bare method exists. Require a CLI/schema qualified-lookup attestation before trusting its absence.
+        if(symbol.includes(".") || unindexedSymbolSyntax(symbol))throw Error();
+        return{exists:false,ambiguous:false};
+      }throw Error();}
       const n=xml(r.out);if(n.tag!=="callers" || n.attrs.schema!=="ripwire.callers/v1" || n.attrs.of!==symbol || !integer(n.attrs.defs)||Number(n.attrs.defs)<1)throw Error();return{exists:true,ambiguous:n.attrs.via==="name" || Number(n.attrs.defs)>1};});
   }
   neighbours(repo:string,head:string,symbol:string,depth=1,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<{callers:CodeSymbol[];callees:CodeSymbol[];hiddenAmbiguous:number;countsFloor:boolean}>> {

package/src/hub/conductor.ts

@@ -9,6 +9,7 @@ import type { StartMode } from "./start-mode.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
 import type { Budget } from "./budget.ts";
+import { windowKind, type WindowKind } from "./window-kind.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { supportsHeadlessInstances } from "./instances.ts";
 
@@ -17,9 +18,11 @@ export function conductorProgressSink(record: (event: HubEvent) => void, feed: P
   return event => { record(event); if (event.type === "stuck") feed.milestone(event.task, "stuck", { reason: event.category }); };
 }
 
-export function publicPeerBudget(status: ReturnType<Budget["status"]>, nameable: (text: string) => boolean): Record<string, unknown> {
+/** What `Budget.status` returns, with the fields added after it optional so an older shape still projects. */
+type PublicBudgetStatus = Record<string, { windows: (Omit<ReturnType<Budget["status"]>[string]["windows"][number], "kind" | "superseded"> & { kind?: WindowKind; superseded?: boolean })[]; paused?: ReturnType<Budget["status"]>[string]["paused"] }>;
+export function publicPeerBudget(status: PublicBudgetStatus, nameable: (text: string) => boolean): Record<string, unknown> {
   return Object.fromEntries(Object.entries(status).map(([peer, value]) => [peer, {
-    windows: value.windows.map(window => ({ id: window.id, used: window.used, at: window.at, stale: window.stale,
+    windows: value.windows.map(window => ({ id: window.id, kind: windowKind(window), used: window.used, at: window.at, stale: window.stale, ...(window.superseded ? { superseded: true } : {}),
       ...(window.resetsAt === undefined ? {} : { resetsAt: window.resetsAt }),
       ...(window.windowMins === undefined ? {} : { windowMins: window.windowMins }),
       source: nameable(window.source) ? window.source : "[quota source withheld]",

package/src/hub/config-apply.ts

@@ -17,6 +17,7 @@ import { projectionConfig } from "./text-projection.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
 import { peerRosterConfig, staleInstanceKey } from "./roster.ts";
 import { CHARACTER_IDS } from "../pet/characters.ts";
+import { checkSettingValue, settingDef } from "./settings.ts";
 import { petPalette } from "../pet/config.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
@@ -189,6 +190,12 @@ export function validateRawConfig(raw: unknown, declarations?: InstancesConfig,
   const instances = validateInstances(value.instances ?? declarations, catalog);
   block({ ...schema,
     instances: v => { validateInstances(v, catalog); },
+    planner: v => {
+      if (v === null) fail("config.planner", "takes a peer id or a nonempty list");
+      const def = settingDef("planner", instances, catalog);
+      if (typeof def === "string") return fail("config.planner", def);
+      checkSettingValue(def, v);
+    },
     permission_modes: v => { permissionDefaults(v, instances, catalog); },
     roster: v => { peerRosterConfig(v, instances, catalog, inertModuleRoster); },
     peers: v => { peerStartConfig(v, instances, catalog); },

package/src/hub/control-client.ts

@@ -9,7 +9,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
+export const DAEMON_FEATURES = ["external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;