@staix/agent-hub 0.12.44 → 0.13.0

package/src/hub/code-facts.ts

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { childEnv, stopOwnedProcess, trackGroup } from "./child-process.ts";
+import { hubGitEnv, hubGitSync } from "./git.ts";
+import { foldSegment } from "./permission-mode.ts";
+import { realPath } from "./project.ts";
+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 }
+const unknown = (): {state:"unknown"} => ({state:"unknown"});
+const SHA = /^[a-f0-9]{40}$/;
+// 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");
+setInterval(()=>{},1000);
+let code=null;
+try { code=await Bun.spawn(process.argv.slice(1),{stdin:"ignore",stdout:"inherit",stderr:"ignore"}).exited; } catch {}
+try { closeSync(1); } catch {}
+writeSync(3,JSON.stringify({code})+"\n");
+`;
+const MAX_OUTPUT = 256 * 1024, MAX_SYMBOLS = 256, MAX_FILES = 4096, MAX_TREE_BYTES = 32 * 1024 * 1024;
+const within = (root:string,file:string) => {const r=relative(root,file);return r !== ".." && !r.startsWith("../") && !isAbsolute(r);};
+const text = (value:unknown,cap=512): value is string => typeof value === "string" && !!value && Buffer.byteLength(value)<=cap && !/[\p{Cc}\p{Cf}]/u.test(value);
+const pathName = (value:unknown): value is string => text(value,2048) && !isAbsolute(value) && !value.includes("\\") && !value.split("/").some(p=>!p || [".","..",".git"].includes(foldSegment(p)));
+const integer = (value:unknown) => typeof value === "string" && /^\d+$/.test(value) && Number.isSafeInteger(Number(value));
+interface Xml { tag:string; attrs:Record<string,string>; children:Xml[] }
+/** Small bounded XML data reader: no DTD, entities, processing instructions or external resources. */
+function xml(raw:string): Xml {
+  let root:Xml|undefined;const stack:Xml[]=[];let count=0;
+  const decode=(s:string)=>s.replace(/&(amp|lt|gt|quot|apos);/g,(_,e:string)=>({amp:"&",lt:"<",gt:">",quot:'"',apos:"'"})[e]!);
+  const tokens=raw.match(/<!--[\s\S]*?-->|<[^>]*>|[^<]+/g)??[];if(tokens.join("")!==raw)throw Error();
+  for(const part of tokens) {
+    if(part.startsWith("<!--"))continue;
+    if(!part.startsWith("<")){if(part.trim())throw Error();continue;}
+    if(part.startsWith("</")){if(!/^<\/[a-z][a-z0-9_-]*>$/.test(part)||stack.pop()?.tag!==part.slice(2,-1))throw Error();continue;}
+    const m=/^<([a-z][a-z0-9_-]*)([\s\S]*?)(\/?)>$/.exec(part);if(!m || ++count>4096 || stack.length>16)throw Error();
+    const attrs:Record<string,string>=Object.create(null);let rest=m[2]!;
+    while(rest.trim()) {
+      const a=/^\s+([a-z_][a-z0-9_-]*)="([^"<>]*)"/.exec(rest);if(!a || Object.hasOwn(attrs,a[1]!) || /&(?!amp;|lt;|gt;|quot;|apos;)/.test(a[2]!))throw Error();
+      attrs[a[1]!]=decode(a[2]!);rest=rest.slice(a[0].length);
+    }
+    const node={tag:m[1]!,attrs,children:[] as Xml[]};
+    if(stack.length)stack.at(-1)!.children.push(node);else {if(root)throw Error();root=node;}
+    if(!m[3])stack.push(node);
+  }
+  if(!root || stack.length)throw Error();return root;
+}
+function cleanSymbol(name:unknown,kind:unknown,position:unknown,via?:unknown): CodeSymbol {
+  if(via!==undefined && via!=="name" && via!=="resolved")throw Error();
+  if(!text(name) || !text(kind,32) || !/^[a-z_]+$/.test(kind) || !text(position,2100))throw Error();
+  const p=/^(.*):(\d+)$/.exec(position);if(!p || !pathName(p[1]) || !integer(p[2]) || Number(p[2])<1)throw Error();
+  return {name,kind,path:p[1],line:Number(p[2]),ambiguous:via === "name",change:"unknown"};
+}
+function changed(raw:string,head:string,base:string,cwd:string): CodeSymbol[] {
+  const root=xml(raw),a=root.attrs;
+  if(root.tag!=="pr-context" || a.schema!=="ripwire.pr-context/v1" || !a.root || realPath(a.root)!==realPath(cwd) || !a.at || !head.startsWith(a.at) || a.at.length<9 || !a.base_sha || !base.startsWith(a.base_sha) || a.base_sha.length<9
+    || a.anchor!=="merge-base" || a.direction!=="head-since-fork" || ![undefined,"0","false","none"].includes(a.truncated) || ![undefined,"0"].includes(a.trim_level) || ![undefined,"0","1","false","true"].includes(a.counts_floor))throw Error();
+  const files=root.children.filter(n=>n.tag==="file");if(!integer(a.files)||Number(a.files)!==files.length)throw Error();
+  const out:CodeSymbol[]=[];
+  for(const file of files) {
+    if(!pathName(file.attrs.p))throw Error();
+    const group=file.children.find(n=>n.tag==="changed-symbols");if(!group || !integer(group.attrs.count))throw Error();
+    const symbols=group.children.filter(n=>n.tag==="s");if(Number(group.attrs.count)!==symbols.length || !integer(file.attrs.symbols) || Number(file.attrs.symbols)<symbols.length)throw Error();
+    for(const symbol of symbols) {
+      if(![undefined,"0","false"].includes(symbol.attrs.capped))throw Error();
+      const s=cleanSymbol(symbol.attrs.n,symbol.attrs.t,symbol.attrs.p,symbol.attrs.via);if(s.path!==file.attrs.p)throw Error();out.push(s);
+    }
+  }
+  if(out.length>MAX_SYMBOLS)throw Error();return out;
+}
+
+/** 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 busy=false;
+  private closing=false;
+  private pending?:Promise<CodeFactResult<unknown>>;
+  private cancelActive?:()=>void;
+  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;
+    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}={}) {}
+  private git(repo:string,args:string[]) {
+    return hubGitSync(["-C",repo,...args],{encoding:"utf8",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:1024*1024});
+  }
+  private value(repo:string,args:string[]):string {const r=this.git(repo,args);if(r.status!==0)throw Error();return r.stdout.trim();}
+  private nativeEnv(cwd:string):NodeJS.ProcessEnv {
+    const env=hubGitEnv(childEnv(this.options.env ?? process.env),{repositoryIsolation:true});
+    const filters=this.git(cwd,["config","--name-only","--get-regexp","^filter\\..*\\.(clean|smudge|process|required)$"]);
+    if(filters.status!==0 && filters.status!==1)throw Error();
+    const keys=filters.stdout.trim()?filters.stdout.trim().split("\n"):[];
+    if(keys.length>128 || keys.some(key=>!/^filter\.[A-Za-z0-9_.-]+\.(clean|smudge|process|required)$/.test(key)))throw Error();
+    const config=["core.fsmonitor=false","core.hooksPath=/dev/null","diff.external=","core.pager=cat",...keys.map(key=>`${key}=${key.endsWith(".required")?"false":""}`)];
+    env.GIT_CONFIG_GLOBAL="/dev/null";env.GIT_CONFIG_NOSYSTEM="1";env.GIT_ATTR_NOSYSTEM="1";env.GIT_PAGER="cat";delete env.GIT_EXTERNAL_DIFF;
+    env.GIT_CONFIG_COUNT=String(config.length);
+    config.forEach((item,index)=>{const at=item.indexOf("=");env[`GIT_CONFIG_KEY_${index}`]=item.slice(0,at);env[`GIT_CONFIG_VALUE_${index}`]=item.slice(at+1);});
+    return env;
+  }
+  private async run(bin:string,args:string[],cwd:string):Promise<{code:number;out:string}> {
+    if(this.closing)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;}
+      let size=0,done=false,failed=false,control="";const parts:Buffer[]=[];
+      let ended=false;const outputEnd=new Promise<void>(resolveEnd=>child.stdout!.once("end",()=>{ended=true;resolveEnd();}));
+      const finish=async(code:number|null)=>{
+        if(done)return;done=true;clearTimeout(timer);if(code===null)failed=true;
+        if(code!==null && !ended)await Promise.race([outputEnd,Bun.sleep(500)]);
+        if(!ended)code=null;
+        try{await stopOwnedProcess(child,{group:true,termMs:50,killMs:500});}catch{this.failedChild=child;code=null;}
+        if(this.cancelActive===cancel)this.cancelActive=undefined;
+        resolve({code:failed?1:code??1,out:!failed && code!==null?Buffer.concat(parts).toString("utf8"):""});
+      };
+      const cancel=()=>{void finish(null);};this.cancelActive=cancel;
+      const timer=setTimeout(cancel,Math.max(1,Math.min(5000,this.options.timeoutMs ?? 5000)));
+      child.once("spawn",()=>trackGroup(child));
+      child.stdout!.on("data",(b:Buffer)=>{if(failed)return;if(size+b.length>MAX_OUTPUT){failed=true;void finish(null);return;}parts.push(b);size+=b.length;});
+      child.stdio[3]!.on("data",(b:Buffer)=>{
+        if(done)return;control+=b.toString("utf8");if(control.length>64){void finish(null);return;}
+        if(!control.endsWith("\n"))return;
+        try{const message=JSON.parse(control);if(Object.keys(message).length!==1 || !(message.code===null || Number.isSafeInteger(message.code)&&message.code>=0&&message.code<=255))throw Error();void finish(message.code);}catch{void finish(null);}
+      });
+      child.once("error",()=>{void finish(null);});child.once("close",()=>{void finish(null);});
+    });
+  }
+  private tree(repo:string,head:string):{cwd:string;close:()=>void} {
+    const inventory=this.value(repo,["ls-tree","-rz","--full-tree",head]);
+    const entries=inventory ? inventory.split("\0").filter(Boolean).map(line=>{
+      const m=/^(100644|100755) blob ([a-f0-9]{40})\t([\s\S]+)$/.exec(line);if(!m || !pathName(m[3]))throw Error();return {mode:m[1]!,oid:m[2]!,name:m[3]!};
+    }):[];
+    // ponytail: regular-file trees only, <=4096 entries/32 MiB/4 MiB per file. Symlink/gitlink trees stay unknown; a verified materializer is the upgrade.
+    if(entries.length>MAX_FILES)throw Error();
+    // Always materialize: tracked-clean owner trees can still contain untracked or ignored analysis inputs.
+    const parent=mkdtempSync(join(tmpdir(),"ahub-code-facts-")),cwd=join(parent,"tree");let registered=false;
+    const close=()=>{
+      let failed=false;
+      if(registered){const r=this.git(repo,["worktree","remove","--force",cwd]);failed=r.status!==0;}
+      rmSync(parent,{recursive:true,force:true});if(failed)throw Error();
+    };
+    try{
+      if(this.git(repo,["worktree","add","--detach","--no-checkout",cwd,head]).status!==0)throw Error();registered=true;
+      if(this.git(cwd,["read-tree",head]).status!==0)throw Error();
+      // --batch needs explicit object ids; no working-tree filters or checkout hooks are invoked.
+      const result=hubGitSync(["-C",repo,"cat-file","--batch"],{input:entries.map(e=>e.oid).join("\n")+"\n",encoding:"latin1",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:MAX_TREE_BYTES+1024*1024});
+      if(result.status!==0)throw Error();
+      const bytes=Buffer.from(result.stdout,"latin1");let offset=0,total=0;
+      for(const entry of entries){
+        const end=bytes.indexOf(10,offset);if(end<0)throw Error();const m=/^([a-f0-9]{40}) blob (\d+)$/.exec(bytes.subarray(offset,end).toString("ascii"));
+        if(!m || m[1]!==entry.oid || !integer(m[2]))throw Error();const size=Number(m[2]);total+=size;offset=end+1;
+        if(size>4*1024*1024 || total>MAX_TREE_BYTES || offset+size>=bytes.length || bytes[offset+size]!==10)throw Error();
+        const file=join(cwd,entry.name);mkdirSync(dirname(file),{recursive:true});writeFileSync(file,bytes.subarray(offset,offset+size));chmodSync(file,entry.mode==="100755"?0o755:0o644);offset+=size+1;
+      }
+      if(offset!==bytes.length || !releaseTrackedClean(cwd,args=>{const r=this.git(cwd,args);return{code:r.status??1,stdout:r.stdout};}))throw Error();
+      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;
+    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 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();
+        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;}
+      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));
+  }
+  changedSymbols(repo:string,base:string,head:string,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<CodeSymbol[]>> {
+    if(!SHA.test(base))return Promise.resolve(unknown());
+    return this.query({...options,repo,head},`changed:${base}`,async(cwd,bin)=>{const r=await this.run(bin,[cwd,`--pr-context=${base}`,"--no-cache"],cwd);if(r.code!==0)throw Error();return changed(r.out,head,base,cwd);});
+  }
+  enclosing(repo:string,head:string,file:string,line:number,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<CodeSymbol[]>> {
+    if(!pathName(file)||!Number.isSafeInteger(line)||line<1)return Promise.resolve(unknown());
+    return this.query({...options,repo,head},`at:${file}:${line}`,async(cwd,bin)=>{
+      const r=await this.run(bin,[cwd,`--at=${file}:${line}`,"--no-cache"],cwd);if(r.code!==0)throw Error();const node=xml(r.out),a=node.attrs;
+      if(node.tag!=="at" || a.schema!=="ripwire.at/v1" || a.p!==file || Number(a.l)!==line || !integer(a.chain)||Number(a.chain)!==node.children.length || node.children.length>32)throw Error();
+      return node.children.map(n=>{if(n.tag!=="s" || !integer(n.attrs.l)||!integer(n.attrs.el)||Number(n.attrs.el)<line || Number(n.attrs.l)>line)throw Error();return {...cleanSymbol(n.attrs.n,n.attrs.t,`${file}:${n.attrs.l}`,n.attrs.via),endLine:Number(n.attrs.el)};});
+    });
+  }
+  private async relations(cwd:string,bin:string,symbol:string,kind:"callers"|"callees"):Promise<{defs:number;items:CodeSymbol[];countsFloor:boolean}> {
+    const r=await this.run(bin,[cwd,`--${kind}=${symbol}`,"--json","--no-cache"],cwd);if(r.code!==0)throw Error();const v=JSON.parse(r.out);
+    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();
+    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();}
+      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}>> {
+    if(depth!==1 || !text(symbol))return Promise.resolve(unknown());
+    return this.query({...options,repo,head},`neighbours:${symbol}:1`,async(cwd,bin)=>{
+      const incoming=await this.relations(cwd,bin,symbol,"callers"),outgoing=await this.relations(cwd,bin,symbol,"callees"),callers=incoming.items,callees=outgoing.items;
+      return {countsFloor:incoming.countsFloor || outgoing.countsFloor,callers:callers.filter(s=>!s.ambiguous),callees:callees.filter(s=>!s.ambiguous),hiddenAmbiguous:[...callers,...callees].filter(s=>s.ambiguous).length};
+    });
+  }
+}

package/src/hub/config-apply.ts

@@ -1,3 +1,7 @@
+import { ACTION_CLASSES } from "./action-class.ts";
+import { actionPolicyConfig } from "./action-policy.ts";
+import { adapterModuleDeclarations } from "../adapters/external-modules.ts";
+import { externalMetadataDefinitions, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 import { reviewerPoolConfig } from "./reviewer-pool-config.ts";
 import type { HubConfig } from "./daemon.ts";
 import { ALL_MACHINE_LOCAL, configRepositoryPresent, configTracked } from "./config-trust.ts";
@@ -10,7 +14,7 @@ import { resolveProfile } from "./profiles.ts";
 import { taskSweepConfig } from "./task-sweep.ts";
 import { projectionConfig } from "./text-projection.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
-import { peerRosterConfig } from "./roster.ts";
+import { peerRosterConfig, staleInstanceKey } from "./roster.ts";
 import { CHARACTER_IDS } from "../pet/characters.ts";
 import { petPalette } from "../pet/config.ts";
 
@@ -18,9 +22,9 @@ export type ApplyClass = "live" | "next use" | "restart";
 export interface ApplyRule { applies: ApplyClass; reason?: string }
 export interface ConfigIdentityScope { catalog: ProjectAdapterCatalog; instances: InstancesConfig }
 /** Plain captured metadata stays cloneable with ConfigSources; native callbacks are compiled outside it. */
-export interface ConfigIdentitySnapshot { adapters?: HubConfig["adapters"]; instances: InstancesConfig }
+export interface ConfigIdentitySnapshot { adapters?: HubConfig["adapters"]; externalAdapters?: readonly ExternalAdapterMetadata[]; instances: InstancesConfig }
 export function configIdentityScope(snapshot: ConfigIdentitySnapshot): ConfigIdentityScope {
-  return { catalog: createProjectAdapterCatalog(snapshot.adapters), instances: snapshot.instances };
+  return { catalog: createProjectAdapterCatalog(snapshot.adapters, externalMetadataDefinitions(snapshot.externalAdapters)), instances: snapshot.instances };
 }
 export interface ConfigChange extends ApplyRule { key: string; before: unknown; after: unknown }
 export interface ConfigLayer { name: "config.json" | "config.local.json"; raw: Record<string, unknown> }
@@ -30,6 +34,8 @@ export interface ConfigAuthorizationInput {
   before: unknown;
   after: unknown;
   source: "config" | "routing";
+  /** Captured host filename, not the requested setting or a caller-provided authority. */
+  sourceFile?: string;
   tracked: boolean | undefined;
   authority: "ordinary" | "settings" | "terminal";
   /** The daemon supplies this only for the selected setting or an explicitly confirmed reload key. */
@@ -46,6 +52,10 @@ export interface ConfigAuthorizationDecision { key: string; allowed: boolean; gu
 export function authorizeConfigLeaf(input: ConfigAuthorizationInput): ConfigAuthorizationDecision {
   const { key, before, after } = input;
   const result = (allowed: boolean, guarded: boolean, reason: string): ConfigAuthorizationDecision => ({ key, allowed, guarded, reason });
+  if (key === "action_policy" || key.startsWith("action_policy.")) {
+    if (input.sourceFile !== "config.local.json") return result(false, true, "action policy requires .agenthub/config.local.json");
+    if (input.tracked !== false) return result(false, true, "action policy requires an untracked machine-local source");
+  }
   if (same(before, after)) return result(true, false, "unchanged");
   const supplied = input.guard;
   const guard = supplied && (key === supplied.key || key === `${supplied.store === "routing" ? "routing." : ""}${supplied.path.join(".")}`) ? supplied : undefined;
@@ -133,7 +143,9 @@ const nativeValidators = { bool, text, strings, argv, number, words, block };
 const schema: Record<string, Check> = {
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.schema?.(nativeValidators) ?? {})),
   watchdog_ms: number(1, 2_147_483_647), kimi_cmd: argv, qwen_cmd: argv, jcode_cmd: argv, codex_bin: text, jcode_home: text, jcode_provider_profile: text,
+  action_policy: block({ enabled: bool, always_ask: (v, k) => { actionPolicyConfig({ always_ask: v }); }, budgets: map(number(0, 1000, true), ACTION_CLASSES) }),
   permission_modes: v => { permissionDefaults(v); }, protect_instruction_files: bool,
+  adapter_modules: v => { adapterModuleDeclarations(v); },
   adapters: v => { createProjectAdapterCatalog(v); }, instances: v => { validateInstances(v, createProjectAdapterCatalog()); }, pet: validatePetConfig,
   batch_max: number(1, 100_000, true), batch_ms: number(0, 2_147_483_647), queue_cap: number(1, 1_000_000, true),
   memory: block({ enabled: bool, worker_url: text, inject_tokens: number(0, 1_000_000, true), brief_items: number(0, 10_000, true), native: bool,
@@ -166,27 +178,28 @@ const schema: Record<string, Check> = {
   capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
 export const SCHEMA_KEYS: readonly string[] = Object.freeze(Object.keys(schema));
-export function validateRawConfig(raw: unknown, declarations?: InstancesConfig, context?: ProjectAdapterCatalog): asserts raw is Record<string, unknown> {
+export function validateRawConfig(raw: unknown, declarations?: InstancesConfig, context?: ProjectAdapterCatalog, inertModuleRoster = false): asserts raw is Record<string, unknown> {
   const value = object(raw, "config");
-  const catalog = value.adapters !== undefined ? createProjectAdapterCatalog(value.adapters) : context ?? createProjectAdapterCatalog();
+  const catalog = value.adapters !== undefined ? createProjectAdapterCatalog(value.adapters, context?.externalDefinitions) : context ?? createProjectAdapterCatalog();
   const instances = validateInstances(value.instances ?? declarations, catalog);
   block({ ...schema,
     instances: v => { validateInstances(v, catalog); },
     permission_modes: v => { permissionDefaults(v, instances, catalog); },
-    roster: v => { peerRosterConfig(v, instances, catalog); },
+    roster: v => { peerRosterConfig(v, instances, catalog, inertModuleRoster); },
     peers: v => { peerStartConfig(v, instances, catalog); },
   })(raw, "config");
 }
-export function validateEffectiveConfig(value: unknown): asserts value is HubConfig {
+export function validateEffectiveConfig(value: unknown, catalog?: ProjectAdapterCatalog): asserts value is HubConfig {
   const raw = { ...object(value, "config") };
   delete raw.ignored; delete raw.retired; delete raw.permission_default_sources;
-  validateRawConfig(raw);
+  validateRawConfig(raw, undefined, catalog);
   const profile = resolveProfile(raw.profile, raw.profile_overrides);
   for (const key of Object.keys(object(raw.checks, "checks"))) if (!["timeout_s", "runner", ...CLASSES, ...Object.keys(profile.classes)].includes(key)) fail(`checks.${key}`, "unknown task class");
   for (const adapter of ADAPTERS) adapter.configuration?.validateEffective?.(raw, fail);
 }
 
 const restart: Record<string, string> = {
+  adapter_modules: "External adapter modules are verified and imported only at daemon startup",
   adapters: "Configured adapter identity, commands and capability policy are fixed at daemon startup",
   instances: "Native instance identity, worktree, ports and account bindings are fixed at daemon startup",
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.restartReasons ?? {})),
@@ -197,7 +210,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "approvals.notify", "pet"]);
+const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "approvals.notify", "pet"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {
@@ -214,7 +227,7 @@ export function configApply(key: string, scopes: readonly ConfigIdentityScope[]
       if (shape?.fields) { if (!Object.hasOwn(shape.fields, part)) return fail(key, "unknown configuration key"); check = shape.fields[part]; }
       else if (shape?.item) { if (shape.keys && !shape.keys.includes(part) && !(top === "roster" && scopes.some(scope => scope.catalog.definitionOf(part, scope.instances)))) return fail(key, "unknown configuration key"); check = shape.item; }
       else if (index === 0 && (special[top]?.includes(part) || top === "checks" && /^[a-z][a-z0-9_]{0,47}$/.test(part))) break;
-      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers", "instances", "adapters"].includes(top)) break;
+      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers", "instances", "adapters", "adapter_modules"].includes(top)) break;
       else return fail(key, "unknown configuration key");
     }
   }
@@ -237,7 +250,11 @@ export function configChanges(running: HubConfig, next: HubConfig, scopes: reado
     if (same(before, after)) return;
     if (before && after && typeof before === "object" && typeof after === "object" && !Array.isArray(before) && !Array.isArray(after)) {
       for (const child of new Set([...Object.keys(before), ...Object.keys(after)])) walk(at(before, [child]), at(after, [child]), key ? `${key}.${child}` : child);
-    } else changes.push({ key, before, after, ...configApply(key, scopes) });
+    } else {
+      // #225: deleting a roster key whose instance was undeclared is live and needs no identity; adding or setting one stays an unknown key.
+      const stale = after === undefined && /^roster\.[^.]+$/.test(key) && scopes.some(scope => staleInstanceKey(key.slice("roster.".length), scope.catalog));
+      changes.push({ key, before, after, ...(stale ? { applies: "live" as const } : configApply(key, scopes)) });
+    }
   };
   const clean = (v: HubConfig) => Object.fromEntries(Object.entries(v).filter(([key]) => !["ignored", "retired", "permission_default_sources"].includes(key)));
   walk(clean(running), clean(next), ""); return changes.sort((a, b) => a.key.localeCompare(b.key));

package/src/hub/config-reload.ts

@@ -1,4 +1,5 @@
 import { ADAPTERS, createProjectAdapterCatalog } from "../adapters/registry.ts";
+import { externalMetadataDefinitions, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -86,7 +87,7 @@ function validateRoutingRaw(value: unknown): void {
 }
 
 /** Strict reloads never use routing's last-good fallback. Startup can retain its existing fallback explicitly. */
-export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: Routing, cwd?: string): ConfigSources {
+export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: Routing, cwd?: string, externalAdapters?: readonly ExternalAdapterMetadata[]): ConfigSources {
   const layers: ConfigLayer[] = [], trustLayers: ConfigSources["trustLayers"] = [];
   const jsonLayers: ConfigLayer[] = [];
   for (const name of ["config.json", "config.local.json"] as const) {
@@ -103,13 +104,15 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
   const localRaw = jsonLayers.find(layer => layer.name === "config.local.json")?.raw ?? {};
   let declared;
   let identityAdapters: ConfigIdentitySnapshot["adapters"];
+  let inertModuleRoster = false;
   let catalog = createProjectAdapterCatalog();
   try {
     if (cwd) {
-      const accepted = readInstanceConfig(cwd, jsonLayers);
+      const accepted = readInstanceConfig(cwd, jsonLayers, externalAdapters === undefined ? undefined : externalMetadataDefinitions(externalAdapters));
       catalog = accepted.catalog; declared = accepted.instances; identityAdapters = accepted.adapters;
+      inertModuleRoster = !!accepted.adapter_modules?.length;
     } else {
-      catalog = createProjectAdapterCatalog(localRaw?.adapters);
+      catalog = createProjectAdapterCatalog(localRaw?.adapters, externalMetadataDefinitions(externalAdapters));
       identityAdapters = localRaw?.adapters as ConfigIdentitySnapshot["adapters"];
       declared = validateInstances(localRaw?.instances, catalog);
     }
@@ -135,7 +138,7 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
           const structural = { ...raw };
           // Declaration provenance was checked before compilation; ignored source data is never re-admitted.
           delete structural.adapters; delete structural.instances;
-          validateRawConfig(structural, declared, catalog);
+          validateRawConfig(structural, declared, catalog, inertModuleRoster);
         }
         catch (error) { throw new Error(`.agenthub/${name}: ${(error as Error).message}`); }
       }
@@ -153,5 +156,5 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
     try { routing = parseRouting(base, overlay); }
     catch { throw new Error(".agenthub/routing.toml / routing.local.toml: invalid effective routing"); }
   }
-  return { texts, layers, trustLayers, routing, fingerprint: configFingerprint(texts), identity: { ...(identityAdapters ? { adapters: structuredClone(identityAdapters) } : {}), instances: declared ?? validateInstances(undefined, catalog) } };
+  return { texts, layers, trustLayers, routing, fingerprint: configFingerprint(texts), identity: { ...(identityAdapters ? { adapters: structuredClone(identityAdapters) } : {}), instances: declared ?? validateInstances(undefined, catalog), ...(catalog.externalDefinitions.length ? { externalAdapters: catalog.externalDefinitions.map(({ kind, displayName }) => ({ kind, displayName })) } : {}) } };
 }

package/src/hub/config-trust.ts

@@ -29,7 +29,7 @@ export const MACHINE_LOCAL = [
   "terminal.open", // the command a hub-made TUI start runs to open a terminal (#269)
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
-export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "text_projection", "instances"] as const;
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "adapter_modules", "text_projection", "instances"] as const;
 
 /** A known repository, including an unreadable marker, must never be mistaken for a plain directory. */
 export function configRepositoryPresent(cwd: string): boolean {
@@ -95,14 +95,17 @@ const drop = (file: Record<string, unknown>, path: string) => {
  * once resolved to the project root). A committed copy of the template sets them to defaults and asks git nothing.
  */
 export function stripUntrusted(file: Record<string, unknown>, defaults: object, cwd: string, name: string): string | undefined {
+  const localOnly = name !== "config.local.json" && file.action_policy !== undefined;
+  if (localOnly) delete file.action_policy;
+  const originNotice = localOnly ? "action_policy ignored: only .agenthub/config.local.json may set it" : undefined;
   for (const p of ALL_MACHINE_LOCAL) if (valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
   const set = ALL_MACHINE_LOCAL.filter((p) => {
     const v = valueAt(file, p);
     return v !== undefined && JSON.stringify(v) !== JSON.stringify(valueAt(defaults, p));
   });
-  if (!set.length) return undefined;
+  if (!set.length) return originNotice;
   const why = configRefusal(cwd, name);
-  if (!why) return undefined;
+  if (!why) return originNotice;
   for (const p of set) drop(file, p);
-  return `${set.join(", ")} in .agenthub/${name} ignored: ${why}`;
+  return [originNotice, `${set.join(", ")} in .agenthub/${name} ignored: ${why}`].filter(Boolean).join("; ");
 }

package/src/hub/control-client.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { projectContext } from "./project.ts";
+import { externalAdapterMetadata, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 
 export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
@@ -8,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 = ["configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "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", "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;
 
@@ -38,6 +39,7 @@ export interface ControlDescriptor {
   features?: readonly string[];
   /** The daemon's accepted native start modes, used by launchers when the file value is retained. */
   startModes?: Readonly<Record<string, "tui" | "headless">>;
+  externalAdapters?: readonly ExternalAdapterMetadata[];
   /** #226: the daemon's processSignature, written into status.json only (not the status reply); absent before 0.12.21. */
   pidSignature?: string;
 }
@@ -54,6 +56,7 @@ export function readControl(stateDir: string): ControlDescriptor | undefined {
     return { url: `ws://127.0.0.1:${status.controlPort}`, token, projectId: status.projectId,
       instanceId: status.instanceId, cwd: status.cwd, protocol: status.protocol, pid: status.pid, features: Array.isArray(status.features) ? status.features.filter((feature: unknown): feature is string => typeof feature === "string") : [],
       ...(startModes ? { startModes } : {}),
+      ...(status.externalAdapters !== undefined ? { externalAdapters: externalAdapterMetadata(status.externalAdapters) } : {}),
       ...(typeof status.pidSignature === "string" && status.pidSignature ? { pidSignature: status.pidSignature } : {}) };
   } catch {
     return undefined;