@awebai/oats 0.29.4 → 0.30.1

package/capabilities/oats-aweb/injects/aweb.md

@@ -1,47 +0,0 @@
-## Messaging: aweb
-
-Your messaging layer is **aweb**. Your identity's alias is your instance name,
-and it lives in the workspace's default team (the `Comms:` line of your TASK.md
-names it). Wider workspace teams are joined explicitly, each with its own
-identity home.
-
-**Load the `oats-aweb` skill before your first `aw mail`/`aw chat` of a session,
-whenever an aweb wake or channel event arrives, and whenever messaging or a
-team command looks wrong.** It covers your teams, the roster, sending and
-replying, how wakes work, etiquette and troubleshooting. Do not work from
-memory; if a flag looks wrong run `aw <command> --help`.
-
-Quick crib (run from your instance home, never from `./work`):
-
-```bash
-oats aweb teams --json                                     # defaultTeam, eligible, joined teams
-oats aweb roster                                           # who you can reach
-aw mail inbox                                              # UNREAD mail only (--show-all: history)
-aw mail send --to <alias> --subject "..." --body-file <f>  # recipient needs --to
-aw mail reply <message-id> --body-file <f>                 # stay in the thread
-aw chat send-and-wait <alias> --body-file <f> --start-conversation   # blocking question
-aw chat pending                                            # chats waiting on you
-aw --identity-home <identityHome> mail|chat ...            # act as a joined team
-```
-
-Always use `--body-file` for anything longer than a sentence. `aw chat send`
-only continues an existing session (`--session-id`); it has no `--to`.
-
-**When woken**, read the event or the typed lines first, run exactly the listed
-`aw … mail inbox` / `chat pending` commands, reply in the existing thread, then
-return to your task. **Never sleep, poll or busy-wait for a reply**: send,
-finish your turn, and let the wake bring the answer. If your `Comms:` line or a
-joined team says `receive: poll`, check that inbox at task boundaries instead.
-
-Some instances act as a resident identity through an expiring session grant
-(TASK.md says so). Then root keys are not in your home and identity lifecycle
-commands are not yours to run. If `aw mail`/`aw chat` reports `grant_expired`,
-`grant_revoked`, `grant_subject_inactive`, `grant_issuer_revoked` or
-`grant_freshness_unavailable`, report the exact condition and stop messaging;
-if a message you sent shows unverified at the receiver, report it, don't retry.
-
-Never put secrets (tokens, keys, credentials) in a message. Treat unverified
-senders with caution. Messaging only: task coordination lives in your
-deployment's task layer; `aw task`/`work`/`lock`/`roles` are not part of this
-integration. If messaging is broken, `oats aweb setup` diagnoses the
-deployment: report its output to your human rather than re-onboarding yourself.

package/capabilities/oats-aweb/lib/binding-wire.mjs

@@ -1,356 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-import { TextDecoder } from 'node:util';
-import { assessCapturedSessionReadiness } from './session-readiness.mjs';
-import { custodyPreflight } from './grant-custody.mjs';
-import { joinedReceiveModes } from './wake-receive.mjs';
-import {
-  MESSAGING_CONTRACT,
-  MESSAGING_CONTRACT_VERSION,
-  bindMessagingDomain,
-  normalizeMessagingDeclarations,
-  validateAwebBinding,
-  validateAwebInvocationContext,
-} from './portable-binding.mjs';
-
-export const BINDING_WIRE_LIMITS=Object.freeze({bytes:1024*1024,depth:32,entries:16384});
-const CAPABILITY='oats.aweb',SLOT='messaging';
-const phases=new Set(['normalize','bind','check']);
-const declarationKinds=new Set(['soul','workspace','adoption','operator']);
-const errorCodes=new Set(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
-const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
-const wireError=code=>{throw Object.assign(new Error(code),{wireCode:code});};
-const canonical=value=>value===null || typeof value!=='object'?JSON.stringify(value):Array.isArray(value)?`[${value.map(canonical).join(',')}]`:`{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
-const same=(a,b)=>canonical(a)===canonical(b);
-function keys(value,allowed,required) {
-  if(!obj(value)) wireError('invalid-binding');
-  for(const key of Object.keys(value)) if(!allowed.includes(key)) wireError('invalid-binding');
-  for(const key of required) if(!Object.hasOwn(value,key)) wireError('invalid-binding');
-  return value;
-}
-function pointer(value) {return typeof value==='string' && /^(?:\/(?:[^~]|~[01])*)+$/.test(value);}
-function bindingKey(value) {return pointer(value) && value.startsWith('/bindings/messaging/') && value.length>'/bindings/messaging/'.length;}
-
-class StrictJsonParser {
-  constructor(text,{depth,entries}) {this.text=text;this.maxDepth=depth;this.maxEntries=entries;this.at=0;this.entries=0;}
-  whitespace() {while(/[\u0009\u000a\u000d\u0020]/.test(this.text[this.at] || '')) this.at++;}
-  count() {if(++this.entries>this.maxEntries) wireError('invalid-binding');}
-  string() {
-    if(this.text[this.at]!=='"') wireError('invalid-binding');
-    const start=this.at++;
-    while(this.at<this.text.length) {
-      const code=this.text.charCodeAt(this.at++);
-      if(code===0x22) {try{return JSON.parse(this.text.slice(start,this.at));}catch{wireError('invalid-binding');}}
-      if(code<0x20) wireError('invalid-binding');
-      if(code===0x5c) {
-        const escaped=this.text[this.at++];
-        if(escaped==='u') {if(!/^[0-9a-fA-F]{4}$/.test(this.text.slice(this.at,this.at+4))) wireError('invalid-binding');this.at+=4;}
-        else if(!'"\\/bfnrt'.includes(escaped || '')) wireError('invalid-binding');
-      }
-    }
-    wireError('invalid-binding');
-  }
-  value(depth=1) {
-    this.whitespace();const char=this.text[this.at];
-    if(char==='"') return this.string();
-    if(char==='{') {
-      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
-      const result=Object.create(null),seen=new Set();if(this.text[this.at]==='}') {this.at++;return result;}
-      while(true) {
-        this.whitespace();const key=this.string();if(seen.has(key)) wireError('invalid-binding');seen.add(key);this.count();
-        this.whitespace();if(this.text[this.at++]!==':') wireError('invalid-binding');result[key]=this.value(depth+1);this.whitespace();
-        const next=this.text[this.at++];if(next==='}') return result;if(next!==',') wireError('invalid-binding');
-      }
-    }
-    if(char==='[') {
-      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
-      const result=[];if(this.text[this.at]===']') {this.at++;return result;}
-      while(true) {this.count();result.push(this.value(depth+1));this.whitespace();const next=this.text[this.at++];if(next===']') return result;if(next!==',') wireError('invalid-binding');}
-    }
-    for(const [token,value] of [['true',true],['false',false],['null',null]]) if(this.text.startsWith(token,this.at)) {this.at+=token.length;return value;}
-    const match=/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.at));
-    if(!match) wireError('invalid-binding');this.at+=match[0].length;const number=Number(match[0]);if(!Number.isFinite(number)) wireError('invalid-binding');return number;
-  }
-  parse() {this.whitespace();const value=this.value();this.whitespace();if(this.at!==this.text.length) wireError('invalid-binding');return value;}
-}
-
-export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
-  if(!Buffer.isBuffer(bytes)) bytes=Buffer.from(bytes);
-  if(bytes.length>limits.bytes) wireError('invalid-binding');
-  let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{wireError('invalid-binding');}
-  return new StrictJsonParser(text,limits).parse();
-}
-function settings(value,{phase}={}) {
-  if(!obj(value)) wireError('invalid-binding');
-  if(phase!=='check' && Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
-  keys(value,phase==='check'?['delivery','team','root','roots','identity','residents','join']:['delivery','team','root','roots','join'],[]);
-  if(value.delivery!==undefined && !['channel','session'].includes(value.delivery)) wireError('needs-configuration');
-  if(value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('needs-configuration');
-  if(value.root!==undefined && (typeof value.root!=='string' || !value.root.trim())) wireError('needs-configuration');
-  if(value.join!==undefined && typeof value.join!=='string') wireError('needs-configuration');
-  if(value.roots!==undefined && !obj(value.roots)) wireError('needs-configuration');
-  if(obj(value.roots)) for(const [team,root] of Object.entries(value.roots)) if(!team || typeof root!=='string' || !root.trim()) wireError('needs-configuration');
-  if(value.identity!==undefined && !obj(value.identity)) wireError('needs-configuration');
-  if(value.residents!==undefined && !obj(value.residents)) wireError('needs-configuration');
-  if(obj(value.residents)) for(const [name,custody] of Object.entries(value.residents)) if(!name || typeof custody!=='string' || !custody.trim()) wireError('needs-configuration');
-  return value;
-}
-function request(value,phase) {
-  keys(value,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input']);
-  if(value.schemaVersion!==1 || value.phase!==phase || value.slot!==SLOT || value.capability!==CAPABILITY) wireError('invalid-binding');
-  settings(value.settings,{phase});return value;
-}
-function declaration(value) {
-  keys(value,['kind','value','origin','origins'],['kind','value','origin','origins']);
-  if(!declarationKinds.has(value.kind) || !obj(value.value) || !obj(value.origin) || !obj(value.origins)) wireError('invalid-binding');
-  return value;
-}
-function context(value,{request=false}={}) {
-  if(value?.kind==='workspace') {
-    keys(value,request?['kind','identity','observation']:['kind','identity'],request?['kind','identity','observation']:['kind','identity']);
-    if(!obj(value.identity) || (request && !obj(value.observation))) wireError('invalid-binding');
-    return {kind:'workspace',identity:value.identity};
-  }
-  if(value?.kind==='standalone') {
-    keys(value,['kind','key'],['kind','key']);
-    if(value.key!==null && (typeof value.key!=='string' || !value.key.trim())) wireError('invalid-binding');
-    return {kind:'standalone',key:value.key};
-  }
-  wireError('invalid-binding');
-}
-function normalizePhase(req) {
-  keys(req.input,['declarations','context'],['declarations','context']);
-  if(!Array.isArray(req.input.declarations)) wireError('invalid-binding');
-  const declarations=req.input.declarations.map(declaration);context(req.input.context,{request:true});
-  return normalizeMessagingDeclarations({declarations,context:req.input.context});
-}
-function choiceMap(value,model) {
-  if(!obj(value)) wireError('invalid-binding');
-  const allowed=new Set(['/bindings/messaging/responsibleHuman','/bindings/messaging/privateTeam','/bindings/messaging/wider',...Object.values(model.teams)]);
-  for(const [key,choice] of Object.entries(value)) {
-    if(!bindingKey(key) || !allowed.has(key)) wireError('invalid-binding');
-    keys(choice,['value','selectedBy','constraints','considered'],['value','selectedBy','constraints','considered']);
-    if(!Array.isArray(choice.constraints) || !Array.isArray(choice.considered) || (choice.selectedBy!==null && !obj(choice.selectedBy))) wireError('invalid-binding');
-  }
-  return value;
-}
-function model(value) {
-  keys(value,['contract','version','context','contextOrigin','requested','requestedOrigins','aliases','aliasOrigins','teams','privatePolicy','privatePolicyOrigin'],['contract','version','context','contextOrigin','requested','requestedOrigins','aliases','aliasOrigins','teams','privatePolicy','privatePolicyOrigin']);
-  if(value.contract!==MESSAGING_CONTRACT || value.version!==MESSAGING_CONTRACT_VERSION || !Array.isArray(value.requested) || !obj(value.requestedOrigins) || !obj(value.aliases) || !obj(value.aliasOrigins) || !obj(value.teams) || typeof value.privatePolicy!=='boolean') wireError('invalid-binding');
-  context(value.context);if(value.contextOrigin!==null && !obj(value.contextOrigin)) wireError('invalid-binding');if(value.privatePolicyOrigin!==null && !obj(value.privatePolicyOrigin)) wireError('invalid-binding');
-  for(const key of Object.values(value.teams)) if(!bindingKey(key)) wireError('invalid-binding');
-  return value;
-}
-function bindPhase(req) {
-  keys(req.input,['model','choices','context'],['model','choices','context']);
-  const normalized=model(req.input.model),selectedContext=context(req.input.context,{request:true});
-  if(!same(selectedContext,normalized.context) || (selectedContext.kind==='workspace' && !same(req.input.context.observation,normalized.contextOrigin))) wireError('invalid-binding');
-  return bindMessagingDomain({model:normalized,choices:choiceMap(req.input.choices,normalized)});
-}
-function binding(value) {
-  keys(value,['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance'],['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance']);
-  if(value.schemaVersion!==1 || value.capability!==CAPABILITY || value.payloadContract!==MESSAGING_CONTRACT || value.payloadVersion!==MESSAGING_CONTRACT_VERSION || !obj(value.payload) || !obj(value.credentialRefs) || Object.keys(value.credentialRefs).length || !Array.isArray(value.provenance)) wireError('invalid-binding');
-  for(const origin of value.provenance) if(!obj(origin)) wireError('invalid-binding');
-  return value;
-}
-function checkResult(message) {return {status:'needs-configuration',problems:[{code:'needs-configuration',message}]};}
-function checkProblems(problems) {return problems.length?{status:'needs-configuration',problems}:null;}
-function workspaceReadinessContext(value) {
-  keys(value,['kind','workspace','deployment','soul','team','instance','home'],['kind','workspace','deployment','soul']);
-  if(value.kind!=='workspace' || typeof value.workspace!=='string' || !value.workspace.trim() || typeof value.deployment!=='string' || !value.deployment.trim() || typeof value.soul!=='string' || !value.soul.trim()) wireError('invalid-binding');
-  if(value.team!==null && value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('invalid-binding');
-  if(value.instance!==null && value.instance!==undefined && (typeof value.instance!=='string' || !value.instance.trim())) wireError('invalid-binding');
-  if(value.home!==null && value.home!==undefined && (typeof value.home!=='string' || !value.home.trim())) wireError('invalid-binding');
-  return value;
-}
-function yamlScalar(text,key){const m=String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`,'m'));return m?m[1].trim():undefined;}
-export const CUSTODY_ATTACH_MIN = '1.36.3';
-export const WAKE_STREAM_MIN = '1.36.5';
-const CLASSIC_REFUSAL = 'oats.aweb 1.14 needs OATS 0.26.0 or newer (workspace model); on an older kernel pin oats.aweb v1.13.x';
-function classicEnv(env=process.env) {return !!env.OATS_TEAM_SCOPE && !(env.OATS_WORKSPACE_KEY || env.OATS_WORKSPACE_NAME || env.OATS_TEAM_LABEL);}
-export function grantYamlCustodySocket(text) {
-  const lines=String(text??'').split(/\r?\n/);let inCustody=false,baseIndent=0;
-  for(const line of lines) {
-    const custody=/^(\s*)custody:\s*(?:#.*)?$/.exec(line);if(custody){inCustody=true;baseIndent=custody[1].length;continue;}
-    if(inCustody){const ind=/^(\s*)/.exec(line)?.[1].length||0;if(line.trim()&&ind<=baseIndent)inCustody=false;const socket=/^\s*socket_path:\s*["']?([^"'\n#]+)["']?\s*$/.exec(line);if(socket)return socket[1].trim();}
-  }
-  return undefined;
-}
-function newestGrantHome(home) {
-  if(typeof home!=='string'||!home.trim()) return null;
-  try {
-    const dirs=readdirSync(home).filter((name)=>name==='.aweb-identity'||/^\.aweb-identity-\d+$/.test(name)).map((name)=>join(home,name)).filter((p)=>{try{return statSync(p).isDirectory();}catch{return false;}}).map((p)=>{try{return {path:p,mtime:statSync(p).mtimeMs};}catch{return {path:p,mtime:0};}}).sort((a,b)=>b.mtime-a.mtime||b.path.localeCompare(a.path));
-    return dirs[0]?.path||null;
-  } catch {return null;}
-}
-function grantAttachmentProblem(home) {
-  const grantHome=newestGrantHome(home);
-  if(!grantHome) return null;
-  const grantYaml=join(grantHome,'grant.yaml');
-  if(!existsSync(grantYaml)) return null;
-  let text;try{text=readFileSync(grantYaml,'utf8');}catch{return null;}
-  if(grantYamlCustodySocket(text)) return null;
-  const id=yamlScalar(text,'grant_id')||'<unknown>';
-  return {code:'custody',message:`grant ${id} is not attached to custody; retire and respawn on aw >= ${CUSTODY_ATTACH_MIN}`};
-}
-function activeTeamAt(root){try{const text=readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8');return yamlScalar(text,'active_team')||yamlScalar(text,'active');}catch{return undefined;}}
-function residentCustodyRoot(settings){const identity=obj(settings.identity)?settings.identity:{},residents=obj(settings.residents)?settings.residents:{};const name=typeof identity.resident==='string'?identity.resident:'';const root=name&&typeof residents[name]==='string'?residents[name]:undefined;return identity.mode==='global'&&root&&isAbsolute(root)?root:undefined;}
-function teamFromSettings(settings,candidate,{env=process.env}={}) {
-  const configured=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():undefined;
-  if(configured) return configured;
-  const custody=residentCustodyRoot(settings);if(custody)return activeTeamAt(custody);
-  return candidate?.root && isAbsolute(candidate.root) ? activeTeamAt(candidate.root) : undefined;
-}
-function rootCandidate(settings,team,{deployment,env=process.env}={}) {
-  const roots=obj(settings.roots)?settings.roots:{};
-  if(team && typeof roots[team]==='string' && roots[team].trim()) return {root:roots[team].trim(),key:`settings.oats.aweb.roots[${JSON.stringify(team)}]`,declared:true};
-  if(typeof settings.root==='string' && settings.root.trim()) return {root:settings.root.trim(),key:'settings.oats.aweb.root',declared:true};
-  const candidates=[env.OATS_WORKSPACE || deployment || process.cwd()];
-  for(const root of candidates) if(isAbsolute(root) && existsSync(join(resolve(root),'.aw'))) return {root,key:'settings.oats.aweb.root',declared:false};
-  return {root:candidates[0] || process.cwd(),key:'settings.oats.aweb.root',declared:false};
-}
-function parseOatsTeams(env=process.env){try{const rows=JSON.parse(env.OATS_TEAMS||'[]');return Array.isArray(rows)?rows.filter(r=>r&&typeof r==='object').map(r=>({label:String(r.label||''),team:typeof r.team==='string'?r.team:null,mapped:r.mapped===true,payload:obj(r.payload)?r.payload:{}})):[];}catch{return [];}}
-function primaryTeamLabel(env=process.env){return env.OATS_TEAM_LABEL || String(env.OATS_TEAM_LABELS||'').split(',').map(s=>s.trim()).filter(Boolean)[0] || null;}
-function unmappedPrimary(env=process.env){const primary=primaryTeamLabel(env);return primary?parseOatsTeams(env).find(t=>t.label===primary&&!t.mapped):undefined;}
-function joinedTeams(home){if(!home)return[];try{const doc=JSON.parse(readFileSync(join(home,'.oats-aweb','teams.json'),'utf8'));return Array.isArray(doc.joinedTeams)?doc.joinedTeams.filter(j=>j&&typeof j==='object'&&j.label&&j.team&&j.identityHome):[];}catch{return[];}}
-function readinessDetails(settings,{deployment,env=process.env}={}) {
-  if(classicEnv(env)) return {team:undefined,candidate:null,warnings:[],result:{status:'needs-configuration',problems:[{code:'needs-configuration',message:CLASSIC_REFUSAL}]}};
-  const initialTeam=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():undefined;
-  const candidate=rootCandidate(settings,initialTeam,{deployment,env}),team=teamFromSettings(settings,candidate,{env}),problems=[],warnings=[];
-  if(!candidate.root || !isAbsolute(candidate.root) || !existsSync(join(resolve(candidate.root),'.aw'))) problems.push({code:'needs-configuration',message:`no messaging root at ${candidate.root?resolve(candidate.root):process.cwd()}: run oats aweb setup there or set ${candidate.key}`});
-  const unmapped=unmappedPrimary(env);if(unmapped&&team)warnings.push({code:'team-unmapped',message:`workspace label ${unmapped.label} is not mapped; using the default team ${team}`});
-  if(!team) problems.push({code:'needs-configuration',message:'no team: set settings.oats.aweb.team or keep an active team at the aweb root'});
-  return {team,candidate,warnings,result:checkProblems(problems) || {status:'ready',problems:[]}};
-}
-function readinessFromSettings(settings,options) {return readinessDetails(settings,options).result;}
-function runAw(argv,cwd,{unsetEnv=[],timeout=60000}={}) {
-  // An inherited AWEB_IDENTITY_HOME is the caller's identity, never this check's.
-  const env={...process.env};delete env.AWEB_IDENTITY_HOME;for(const name of unsetEnv) delete env[name];
-  try {return execFileSync(argv[0],argv.slice(1),{cwd,env,encoding:'utf8',stdio:['ignore','pipe','pipe'],timeout}).trim();}
-  catch(e) {throw new Error(`${argv.slice(0,3).join(' ')} failed${e.status===undefined?'':` (exit ${e.status})`}`);}
-}
-function semverLt(a,b) {const A=String(a||'0.0.0').split('.').map(n=>Number(n)||0),B=String(b).split('.').map(n=>Number(n)||0);for(let i=0;i<3;i++){if((A[i]||0)!==(B[i]||0)) return (A[i]||0)<(B[i]||0);}return false;}
-function wakeReadiness(home,{reliedOn=false}={}) {
-  if(!home || !reliedOn) return {problems:[],warnings:[]};
-  try {
-    const doc=JSON.parse(runAw(['aw','wake','status','--json'],home,{timeout:10000}));
-    const state=doc.daemon_version_state || (doc.daemon_running===false?'not_running':doc.daemon_version?'reported':'unknown');
-    if(state==='reported') {
-      const running=String(doc.daemon_version||'unknown');
-      if(semverLt(running,WAKE_STREAM_MIN)) return {problems:[{code:'wake-daemon-outdated',message:`host wake daemon is running ${running}; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}],warnings:[]};
-      return {problems:[],warnings:[]};
-    }
-    if(state==='not_running') return {problems:[{code:'wake-daemon-not-running',message:'host wake daemon is not running; session delivery relies on it'}],warnings:[]};
-    return {problems:[],warnings:[{code:'wake-daemon-version-unknown',message:`host wake daemon version is unknown; compatibility unproven; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}]};
-  } catch {return {problems:[],warnings:[{code:'wake-daemon-version-unknown',message:`host wake daemon version is unknown; compatibility unproven; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}]};}
-}
-function workspaceReadinessPhase(req) {
-  const ctx=workspaceReadinessContext(req.input.context);
-  if(!obj(req.input.action) || req.input.action.kind!=='readiness') wireError('invalid-binding');
-  const details=readinessDetails(req.settings,{deployment:ctx.deployment}),problems=[...details.result.problems],warnings=[...details.warnings];
-  const identity=obj(req.settings.identity)?req.settings.identity:{},mode=identity.mode===undefined || identity.mode===null || identity.mode===''?'local':String(identity.mode);
-  if(mode==='global') {
-    const grantProblem=grantAttachmentProblem(ctx.home);if(grantProblem) problems.push(grantProblem);
-    const resident=typeof identity.resident==='string' && identity.resident.trim()?identity.resident.trim():undefined;
-    const residents=obj(req.settings.residents)?req.settings.residents:{};
-    const custody=resident?residents[resident]:undefined;
-    if(!resident) problems.push({code:'custody',message:'identity.mode "global" requires identity.resident; set oats-local.yaml settings.oats.aweb.residents.<name> to the absolute custody directory for that resident identity'});
-    else if(typeof custody!=='string' || !isAbsolute(custody) || !existsSync(join(custody,'.aw','identity.yaml'))) problems.push({code:'custody',message:`identity.mode "global" resident ${JSON.stringify(resident)} is not resolvable; set oats-local.yaml settings.oats.aweb.residents.${resident} to an absolute custody directory whose .aw/identity.yaml exists`});
-    else if(details.team) {
-      try {
-        const preflight=custodyPreflight({custody,resident,team:details.team,e2eeRequired:identity.e2ee!==false,fatalOnError:false,runAw:(argv,cwd,options={})=>runAw(argv,cwd,{...options,timeout:20000})});
-        for(const message of preflight.warnings) warnings.push({code:'e2ee-disabled',message});
-      }
-      catch(e) {problems.push({code:'custody',message:e.message});}
-    }
-  }
-  const joined=joinedTeams(ctx.home);
-  if(joined.length) {
-    let status;try{status=JSON.parse(runAw(['aw','wake','status','--json'],ctx.home,{timeout:10000}));}catch{status=undefined;}
-    const why={'home-not-registered':'this home is not registered with the host wake broker','not-registered-with-broker':'its identity home is not registered with the host wake broker','wake-daemon-not-running':'the host wake daemon is not running','stream-not-admitted':'the host wake broker has not admitted its stream'};
-    for(const mode of joinedReceiveModes(status,{home:ctx.home,joined})) {
-      const row=joined.find(j=>j.label===mode.label);
-      if(mode.receive==='native') warnings.push({code:'joined-team-receive',message:`joined team ${mode.label} receives native through the host wake broker (stream ${mode.phase})`});
-      else warnings.push({code:'joined-team-poll-only',message:`joined team ${mode.label} receives by polling: ${status?why[mode.reason]||mode.reason:'aw wake status is unavailable'}${mode.detail?` (${mode.detail})`:''}; check aw --identity-home ${row.identityHome} mail inbox and chat pending at task boundaries`});
-    }
-  }
-  const wake=String(req.settings.delivery||'channel')==='session'?wakeReadiness(ctx.home,{reliedOn:true}):{problems:[],warnings:[]};
-  problems.push(...wake.problems);warnings.push(...wake.warnings);
-  const result=checkProblems(problems) || {status:'ready',problems:[]};
-  return {...result,warnings};
-}
-function checkPhase(req) {
-  keys(req.input,['binding','context','action','invocation'],['context','action']);
-  if(!obj(req.input.action) || typeof req.input.action.kind!=='string') wireError('invalid-binding');
-  if(!Object.hasOwn(req.input,'binding')) return workspaceReadinessPhase(req);
-  const current=validateAwebBinding(binding(req.input.binding)),selectedContext=context(req.input.context,{request:true});
-  if(!same(selectedContext,current.payload.context)) wireError('invalid-binding');
-  const invocation=Object.hasOwn(req.input,'invocation')?validateAwebInvocationContext(req.input.invocation,current,{context:req.input.context,action:req.input.action}):null;
-  if(['command','hook','operation'].includes(req.input.action.kind) && (!invocation || invocation.instance===null || invocation.intent===null)) return checkResult('an admitted captured instance intent is required for execution');
-  if(current.payload.privateTeam===null) return checkResult('an explicit private-team binding is required');
-  const hostReady=readinessFromSettings(req.settings);
-  if(hostReady.status!=='ready') return hostReady;
-  if(!invocation) return hostReady;
-  // Read-only public kernel observations, not an account/grant attestation.
-  // Native setup is performed only by the separately admitted execution path.
-  return assessCapturedSessionReadiness({binding:current,invocation,settings:req.settings});
-}
-
-export function handleBindingRequest(phase,value) {
-  if(!phases.has(phase)) wireError('invalid-binding');
-  const req=request(value,phase);
-  if(phase==='normalize') return normalizePhase(req);
-  if(phase==='bind') return bindPhase(req);
-  return checkPhase(req);
-}
-function response(phase,body) {return {schemaVersion:1,phase,slot:SLOT,capability:CAPABILITY,...body};}
-function errorCode(error) {if(errorCodes.has(error?.wireCode)) return error.wireCode;if(errorCodes.has(error?.code)) return error.code;return 'invalid-binding';}
-// Only these literal domain diagnostics may cross the wire. Never reflect a
-// caught exception's dynamic alias/key/path, native stderr or credential text.
-const safeReasons=new Map([
-  ['needs-configuration',[
-    'messaging-enabled standalone preparation needs an explicit context key',
-    'messaging binding needs one soul declaration',
-    'messaging workspace must declare private: per-human',
-    'an explicit responsible-human binding is required',
-    'an explicit wider-membership consent list is required',
-    'a selected wider-team binding is required',
-    'a selected wider alias needs an explicit workspace team mapping',
-  ]],
-  ['requirement-conflict',['multiple soul messaging declarations','adoption team aliases have conflicting mappings']],
-]);
-const fallbackReasons=Object.freeze({
-  'needs-configuration':'messaging settings and explicit binding selections are required',
-  'requirement-conflict':'messaging declarations contain incompatible requirements',
-  'invalid-binding':'messaging input must match the supported binding contract',
-  'authorization-required':'explicit native messaging authorization is required',
-  'host-requirement-missing':'a required native messaging host resource is unavailable',
-  'provider-unavailable':'the selected messaging provider is unavailable',
-  'provider-not-qualified':'the requested messaging configuration is not qualified',
-});
-function errorProblem(error) {
-  const code=errorCode(error),message=safeReasons.get(code)?.find(literal=>literal===error?.message)??fallbackReasons[code];
-  return {code,message};
-}
-function enforceOutputLimits(value,depth=1,state={entries:0}) {
-  if(depth>BINDING_WIRE_LIMITS.depth) wireError('provider-not-qualified');
-  if(value===null || typeof value!=='object') return;
-  for(const child of Array.isArray(value)?value:Object.values(value)) {
-    if(++state.entries>BINDING_WIRE_LIMITS.entries) wireError('provider-not-qualified');
-    enforceOutputLimits(child,depth+1,state);
-  }
-}
-export async function runBindingWire(phase,input=process.stdin,output=process.stdout) {
-  let answer;
-  try {
-    const chunks=[];let length=0;
-    for await(const chunk of input) {const bytes=Buffer.from(chunk);length+=bytes.length;if(length>BINDING_WIRE_LIMITS.bytes) wireError('invalid-binding');chunks.push(bytes);}
-    const result=handleBindingRequest(phase,parseBindingJson(Buffer.concat(chunks,length)));
-    answer=response(phase,{ok:true,result});
-  } catch(error) {answer=response(phases.has(phase)?phase:'check',{ok:false,error:errorProblem(error)});}
-  let bytes;
-  try {enforceOutputLimits(answer);bytes=Buffer.from(JSON.stringify(answer)+'\n');if(bytes.length>BINDING_WIRE_LIMITS.bytes) wireError('provider-not-qualified');}
-  catch {bytes=Buffer.from(JSON.stringify(response(phases.has(phase)?phase:'check',{ok:false,error:{code:'provider-not-qualified',message:'messaging response exceeds the supported wire limits'}}))+'\n');}
-  output.write(bytes);return answer.ok;
-}

package/capabilities/oats-aweb/lib/captured-execution.mjs

@@ -1,91 +0,0 @@
-// Execution-only consumption of the kernel's selected private snapshots.
-// This establishes correspondence/custody, NOT native human/team authority.
-// No kernel index, source checkout, ambient team/root, or credential is read.
-import fs from 'node:fs';
-import {dirname,isAbsolute,resolve} from 'node:path';
-import {parseBindingJson,BINDING_WIRE_LIMITS} from './binding-wire.mjs';
-import {INVOCATION_LIMITS,sameInvocationJson as same} from './invocation-shape.mjs';
-import {validateAwebBinding,validateAwebInvocationContext} from './portable-binding.mjs';
-const CAPABILITY='oats.aweb';
-const RECEIPT_LIMITS={bytes:256*1024,depth:32,entries:16384};
-const markers=['OATS_BINDING_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_SOURCE_RECEIPT_FILE'];
-const invalid=()=>{throw Object.assign(new Error('invalid captured aweb execution input'),{code:'invalid-binding'});};
-const absentAuthority=()=>{throw Object.assign(new Error('captured aweb action requires an admitted instance intent'),{code:'authorization-required'});};
-const absolute=p=>typeof p==='string'&&!p.includes('\0')&&isAbsolute(p)&&resolve(p)===p;
-const keys=(value,names)=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).length===names.length&&names.every(k=>Object.hasOwn(value,k));
-const statKey=s=>['dev','ino','size','mtimeNs','ctimeNs'].map(k=>String(s[k])).join(':');
-function physical(file){
-  if(!absolute(file))invalid();
-  for(let p=file;;p=dirname(p)){
-    const s=fs.lstatSync(p,{bigint:true});
-    if(s.isSymbolicLink()||(p!==file&&!s.isDirectory()))invalid();
-    if(dirname(p)===p)return s;
-  }
-}
-/** Pin the physical named file to its open descriptor BEFORE every bounded
- * read, including when an ancestor was redirected only during open(). */
-function snapshot(file,limits){
-  let fd;
-  try{
-    physical(file);
-    const uid=typeof process.getuid==='function'?BigInt(process.getuid()):null;
-    const privateFile=s=>s.isFile()&&s.nlink===1n&&s.size<=BigInt(limits.bytes)&&(s.mode&0o7777n)===0o600n&&(uid===null||s.uid===uid);
-    const before=fs.lstatSync(file,{bigint:true});
-    if(!privateFile(before)||typeof fs.constants.O_NOFOLLOW!=='number'||typeof fs.constants.O_NONBLOCK!=='number')invalid();
-    fd=fs.openSync(file,fs.constants.O_RDONLY|fs.constants.O_NOFOLLOW|fs.constants.O_NONBLOCK);
-    const check=()=>{
-      physical(file);const named=fs.lstatSync(file,{bigint:true}),opened=fs.fstatSync(fd,{bigint:true});
-      if(!privateFile(named)||!privateFile(opened)||statKey(named)!==statKey(before)||statKey(opened)!==statKey(named))invalid();
-    };
-    check();const bytes=Buffer.alloc(Number(before.size));
-    for(let n=0;n<bytes.length;){check();const count=fs.readSync(fd,bytes,n,Math.min(32768,bytes.length-n),n);if(!count)invalid();n+=count;}
-    check();return {value:parseBindingJson(bytes,limits),identity:statKey(before)};
-  }catch{invalid();}finally{if(fd!==undefined)fs.closeSync(fd);}
-}
-function freeze(value){if(value&&typeof value==='object'){for(const v of Object.values(value))freeze(v);Object.freeze(value);}return value;}
-function validateSourceReceipt(receipt,context,binding){
-  if(!keys(receipt,['schemaVersion','kind','home','work','context','agent','instance','sourceIdentity','role','executionBinding','responsibleHuman','binding']))invalid();
-  const i=context.instance;
-  if(!i||receipt.schemaVersion!==1||receipt.kind!==context.subject.kind||receipt.home!==i.home||receipt.work!==i.work||receipt.context!==context.executionBinding.deployment||receipt.agent!==i.agent||receipt.instance!==i.name||typeof receipt.role!=='string'||!receipt.role.trim()||!same(receipt.executionBinding,context.executionBinding)||!same(receipt.responsibleHuman,context.responsibleHuman)||!same(receipt.binding,binding))invalid();
-  if(context.action.kind!=='hook'||!['spawn','retire'].includes(context.action.name)||!same(receipt.sourceIdentity,context.subject.kind==='persistent'?context.subject.soul.identity:null))invalid();
-}
-/** Absence is explicitly legacy. Any supplied input requires the full selected
- * binding+invocation pair; invalid-present can never select legacy behavior.
- * assertCurrent is for every native boundary, not a new admission mechanism. */
-export function loadCapturedAwebExecution(env=process.env){
-  if(!markers.some(k=>Object.hasOwn(env,k)))return {kind:'legacy'};
-  if(!Object.hasOwn(env,markers[0])||!Object.hasOwn(env,markers[1]))invalid();
-  const files=markers.filter(k=>Object.hasOwn(env,k)).map(k=>env[k]);if(new Set(files).size!==files.length)invalid();
-  const inputs=files.map((p,i)=>snapshot(p,[BINDING_WIRE_LIMITS,INVOCATION_LIMITS,RECEIPT_LIMITS][i]));
-  let binding,context;
-  try{binding=validateAwebBinding(inputs[0].value);context=validateAwebInvocationContext(inputs[1].value,binding);}catch{invalid();}
-  if(inputs[2])validateSourceReceipt(inputs[2].value,context,binding);
-  const assertCurrent=()=>{
-    files.forEach((p,i)=>{const current=snapshot(p,[BINDING_WIRE_LIMITS,INVOCATION_LIMITS,RECEIPT_LIMITS][i]);if(current.identity!==inputs[i].identity||!same(current.value,inputs[i].value))invalid();});
-  };
-  assertCurrent();
-  return {kind:'captured',binding:freeze(binding),context:freeze(context),sourceReceipt:inputs[2]?freeze(inputs[2].value):null,assertCurrent};
-}
-/** Exact entrypoint and retained instance, not OATS_META/current config, choose
- * the actor's target. The kernel still owns admission and replay. */
-export function requireCapturedAwebAction(loaded,event,manifest,{env=process.env,cwd=process.cwd()}={}){
-  if(loaded.kind!=='captured'||manifest.capability!==CAPABILITY)invalid();
-  const {context}=loaded,a=context.action,i=context.instance;
-  if(a.kind==='hook'){
-    if(a.capability!==CAPABILITY||a.name!==event||!Object.hasOwn(manifest.hooks||{},event))invalid();
-  }else if(a.kind==='command'){
-    if(a.name!==event||!Object.hasOwn(manifest.commands||{},event)||(a.capability!==CAPABILITY&&a.namespace!==manifest.command))invalid();
-  }else invalid();
-  if(!i||!context.intent)absentAuthority();
-  if(cwd!==i.home)invalid();
-  for(const [key,value] of Object.entries({OATS_HOME:i.home,OATS_INSTANCE_HOME:i.home,OATS_INSTANCE:i.name,OATS_AGENT:i.agent,OATS_CONTEXT:context.executionBinding.deployment,OATS_DEPLOYMENT:context.executionBinding.deployment,OATS_RESOLUTION:context.executionBinding.resolution.id,OATS_CAPABILITY:CAPABILITY}))if(Object.hasOwn(env,key)&&env[key]!==value)invalid();
-  if(a.kind==='hook'&&Object.hasOwn(env,'OATS_EVENT')&&env.OATS_EVENT!==event)invalid();
-  const directories=[i.home,i.work,context.executionBinding.deployment].map(p=>{
-    try{physical(p);const s=fs.lstatSync(p,{bigint:true});if(!s.isDirectory())invalid();return {path:p,dev:s.dev,ino:s.ino};}catch{invalid();}
-  });
-  const assertCurrent=()=>{
-    loaded.assertCurrent();
-    for(const d of directories){try{physical(d.path);const s=fs.lstatSync(d.path,{bigint:true});if(!s.isDirectory()||s.dev!==d.dev||s.ino!==d.ino)invalid();}catch{invalid();}}
-  };
-  assertCurrent();return {binding:loaded.binding,context,sourceReceipt:loaded.sourceReceipt,assertCurrent};
-}

package/capabilities/oats-aweb/lib/captured-native.mjs

@@ -1,91 +0,0 @@
-// Selected-input adapter over EXISTING native aw commands. No account/grant
-// protocol, credential copying, private kernel index or second admission store.
-import fs from 'node:fs';
-import {join} from 'node:path';
-import {parseBindingJson,BINDING_WIRE_LIMITS} from './binding-wire.mjs';
-const fail=(code,message)=>{throw Object.assign(new Error(message),{code});};
-function identityDirectory(home,{required=true}={}){
- const path=join(home,'.aw');
- try{const s=fs.lstatSync(path);if(!s.isDirectory()||s.isSymbolicLink()||fs.realpathSync(path)!==path)fail('needs-configuration','native identity directory must be physical and local to its selected home');return path;}
- catch(e){if(e.code==='ENOENT'&&!required)return null;if(e.code==='needs-configuration')throw e;fail('needs-configuration','the selected home needs an initialized native aw identity');}
-}
-/** `run` is the same bounded, argv-only, redacting native runner used by legacy
- * hooks. The execution consumer and each call retain the original snapshots.
- * This function is not callable as a substitute for kernel admission. */
-export function runCapturedNative({selected,event,settings,run,env=process.env}){
- const {context,binding,assertCurrent}=selected,{home,name}=context.instance,team=binding.payload.privateTeam?.id;
- let meta=context.priorReceipt===null?null:JSON.parse(JSON.stringify(context.priorReceipt)),invitationToken=null;
- const roots=new Map();
- const nativeIdentity=(dir,options)=>{
-  const path=identityDirectory(dir,options);
-  if(!path){if(roots.has(join(dir,'.aw')))fail('invalid-binding','native identity directory disappeared during the captured action');return null;}
-  const s=fs.lstatSync(path),stamp=`${s.dev}:${s.ino}`,prior=roots.get(path);
-  if(prior!==undefined&&prior!==stamp)fail('invalid-binding','native identity directory changed during the captured action');
-  roots.set(path,stamp);return path;
- };
- const refusal=(code,message)=>({exitCode:1,output:{...(meta?{meta}:{}),status:'needs-configuration',problems:[{code,message}],warning:`oats-aweb: ${message}; retain the home and any recorded partial effects`}});
- try{
-  assertCurrent();
-  if(!/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(name)||!team)fail('needs-configuration','exact native alias and private-team selection are required');
-  if(settings.delivery!=='session')fail('needs-configuration','captured delivery must be session');
-  if(binding.payload.wider.length)fail('needs-configuration','selected wider memberships need their explicitly qualified native setup; they were not omitted');
-  // A global override may select a different actor even with an exact cwd.
-  // Do not clear/replace it or borrow that identity to make setup pass.
-  if(env.AWEB_IDENTITY_HOME)fail('needs-configuration','captured setup requires native per-directory identity context, not an external AWEB_IDENTITY_HOME override');
-  const call=(args,cwd=home,{secret=false,allowNativeRemoval=false}={})=>{
-   assertCurrent();nativeIdentity(cwd,{required:false});
-   const out=run(['aw',...args],cwd,45000,{secretSafe:true});
-   assertCurrent();
-   if(allowNativeRemoval){
-    try{fs.lstatSync(join(cwd,'.aw'));nativeIdentity(cwd,{required:false});}catch(e){if(e.code!=='ENOENT')throw e;}
-   }else nativeIdentity(cwd,{required:false});
-   try{return parseBindingJson(Buffer.from(out),BINDING_WIRE_LIMITS);}catch{if(secret)fail('provider-unavailable','native invitation response is unavailable');fail('provider-unavailable','native command returned no bounded JSON observation');}
-  };
-  const plain=(args)=>{assertCurrent();nativeIdentity(home);run(['aw',...args],home,60000,{secretSafe:true});assertCurrent();nativeIdentity(home);};
-  const observe=()=>{
-   nativeIdentity(home);
-   const who=call(['--team',team,'whoami','--json']);
-   const status=call(['--team',team,'workspace','status','--json']),ws=status.workspace;
-   if(who.alias!==name||typeof who.did!=='string'||!/^did:key:[A-Za-z0-9]+$/.test(who.did)||status.selected_team!==team||!ws||ws.alias!==name||ws.workspace_path!==home)fail('needs-configuration','native alias, team and workspace must match the selected instance home');
-   if(invitationToken&&who.did.includes(invitationToken))fail('provider-unavailable','native identity response cannot be safely recorded');
-   if(meta?.did!==undefined&&meta.did!==who.did)fail('needs-configuration','native identity changed from the recorded setup; explicit reconciliation is required');
-   return who.did;
-  };
-  if(event==='setup'){
-   if(!nativeIdentity(home,{required:false}))return{exitCode:0,output:{status:'needs-configuration',problems:[{code:'needs-configuration',message:'use explicit captured spawn with existing native authority in the selected deployment; setup does not provision accounts or teams'}]}};
-   observe();return{exitCode:0,output:{status:'ready',problems:[],scope:'native home association only; no account or private-grant attestation'}};
-  }
-  if(event==='roster'){
-   observe();const result=call(['id','team','members','--team-id',team,'--json']);return{exitCode:0,output:result};
-  }
-  if(event==='spawn'){
-   if(meta!==null||nativeIdentity(home,{required:false}))fail('needs-configuration','existing or uncertain native setup requires explicit reconciliation; no duplicate enrollment');
-   // Deployment is an explicit retained context, never an ambient root search.
-   // Native aw itself decides whether its existing identity may issue an invite.
-   const authority=context.executionBinding.deployment;nativeIdentity(authority);
-   meta={team,delivery:'session',pending:'invite'};
-   const invitation=call(['team','invite','--team-id',team,'--json'],authority,{secret:true});
-   if(typeof invitation?.token!=='string'||!invitation.token)fail('provider-unavailable','native invitation returned no token');
-   invitationToken=invitation.token;
-   meta.pending='join';
-   // Native aw mints the child's own identity; OATS never reads/copies a key.
-   const joined=call(['team','join',invitation.token,'--name',name,'--json'],home,{secret:true});
-   // Never echo server strings or a token disguised as an alias into metadata.
-   if(joined?.alias!==name||joined?.team_id!==team)fail('provider-unavailable','native join did not confirm the exact requested alias and team');
-   meta={team,alias:name,delivery:'session',pending:'connect'};
-   plain(['--team',team,'init','--do-not-touch-agents-md']);
-   const did=observe();meta={team,alias:name,delivery:'session',did,pending:'wake-register'};
-   plain(['wake','register','--home',home,'--identity-home',join(home,'.aw'),'--delivery','session']);
-   meta={team,alias:name,delivery:'session',did};
-   return{exitCode:0,output:{meta,env:{AWEB_DELIVERY:'session'},brief:`Comms: your own native aweb identity is ${name} on ${team}. Notification delivery: external (session); registration is durable, not proof of broker delivery or model consumption. Use aw mail/aw chat from this instance home.`}};
-  }
-  if(event==='retire'){
-   if(!meta||meta.alias!==name||meta.team!==team||meta.delivery!=='session'||typeof meta.did!=='string')fail('needs-configuration','recorded owned native identity is required for cleanup; absence is not proof of no effects');
-   observe();plain(['wake','deregister','--home',home]);
-   const result=call(['--team',team,'workspace','delete',name,'--json'],home,{allowNativeRemoval:true});
-   if(result?.alias!==name||typeof result.deleted_at!=='string')fail('provider-unavailable','native self-delete outcome is unconfirmed');
-   return{exitCode:0,output:{meta:{...meta,retired:true,aliasReusable:result.alias_released===true},...(result.alias_released===true?{}:{warning:'oats-aweb: workspace deleted; alias release was not confirmed'})}};
-  }
-  fail('needs-configuration','this captured native entrypoint is unsupported');
- }catch(e){return refusal(['needs-configuration','invalid-binding','authorization-required'].includes(e?.code)?e.code:'provider-unavailable',['needs-configuration','invalid-binding','authorization-required'].includes(e?.code)?e.message:'native action failed or is uncertain');}
-}