@jaimevalasek/aioson 1.37.0 → 1.37.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [1.37.1] - 2026-07-11
+
+### Added
+- Intelligent, bounded resolution of human-readable and approximate Codex model names.
+- Separate reasoning-effort propagation and model-resolution metadata across execution, reports, telemetry, and verification.
+
+### Changed
+- **Operator-memory promotion threshold is now per signal type.** `authorization`, `exclusion`, and `correction` are single explicit standing decisions and promote to a decision on **first** detection; `confirmation` still needs **2×** (it must repeat to distinguish a pattern from a one-off acceptance). Previously all four required 2× (`op-capture.js`), so a firmly-stated one-shot correction/authorization never persisted unless the agent emitted `op:capture` twice. Aligns the storage engine with the signal taxonomy already documented in `agents/_shared/memory-capture-directive.md`. New `promotionThresholdFor(signalType)` helper.
+
+### Fixed
+- **Re-detecting an already-promoted decision no longer duplicates its FTS row or resets `promoted_at`.** `op:capture` now reinforces in place — bumps `reinforcement_count` + refreshes `last_reinforced` (PMD-11) via the new `decision.reinforceDecision` primitive — instead of re-running promotion when a decision for the slug already exists (the stray proposal from re-detection is dropped). This latent double-insert also affected the old uniform-2× flow on the 3rd+ detection of the same signal.
+
 ## [1.37.0] - 2026-07-06
 
 **Full-feature autopilot + CLI-owned briefing refinement.** Two independent arcs land together. A feature built the normal way (`@product` → `@sheldon`/`@orchestrator` → `@dev`) can now run unattended through `@qa`/`@tester`/`@pentester`/`@validator` to `feature:close` — stopping only at genuine human decisions; `@product` asks the run mode once at kickoff (no hidden flag), settable inline (`--auto`/`--step`) or disarmed per feature. Separately, `@briefing-refiner`'s review surface stops being hand-written every round: the CLI now owns the schema, the render, and the apply, closing an explicit iterate-until-clean loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.37.0",
+  "version": "1.37.1",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agent-execution/adapters/base.js

@@ -0,0 +1,15 @@
+'use strict';
+const { spawn } = require('node:child_process');
+const { capabilities, requiredCapability } = require('../capabilities');
+const { resolveExecutable } = require('../executable-resolver');
+function redact(text) { return String(text||'').replace(/(authorization\s*[:=]\s*(?:bearer\s+)?|api[_-]?key\s*[:=]\s*|token\s*[:=]\s*|password\s*[:=]\s*)[^\s,;]+/gi,'$1[REDACTED]'); }
+function normalizeError(error) { const text=String(error?.message||error||'').toLowerCase(); if(/unexpected argument|invalid (?:argument|option)|unknown option/.test(text))return'invalid_arguments';if(/capacity|overloaded|rate limit/.test(text)) return 'capacity'; if(/model.*invalid|unknown model/.test(text)) return 'invalid_model'; if(/unauthorized|authentication failed|not authenticated|forbidden/.test(text)) return 'auth'; if(/timeout|timed out/.test(text)) return 'timeout'; return 'crash'; }
+function createAdapter(host, buildArgs) {
+  return {
+    host,
+    probe() { return capabilities(host); },
+    build(input) { const cap=this.probe(); const required=requiredCapability(input.mode); if(required && !cap[required]) return {ok:false,reason:'unsupported_capability',capability:required,host};if(input.reasoning_effort&&!cap.reasoning_effort)return{ok:false,reason:'unsupported_reasoning_effort',capability:'reasoning_effort',host};if(input.writable_roots?.length&&!cap.additional_workspaces)return{ok:false,reason:'host_capability_missing',capability:'additional_workspaces',host};const command=buildArgs(input);const args=Array.isArray(command)?command:command.args;return {ok:true,executable:cap.executable,args,stdin:Boolean(command.stdin),options:{cwd:input.cwd,shell:false,stdio:'pipe'}}; },
+    async execute(input) { const built=this.build(input); if(!built.ok) return built;let resolved;try{resolved=await resolveExecutable(built.executable,input.resolverOptions)}catch(error){return{ok:false,reason:'executable_not_found',error:redact(error.message)}}return new Promise(resolve=>{ const child=spawn(resolved.executable,[...resolved.prefixArgs,...built.args],built.options); input.onSpawn?.(child.pid,new Date().toISOString());let stderr='';let timedOut=false;let settled=false;child.stdout.on('data',d=>input.onStdout?.(d));child.stderr.on('data',d=>{input.onStderr?.(d);stderr+=d;if(stderr.length>4000)stderr=stderr.slice(-4000)});if(built.stdin)child.stdin.end(String(input.prompt_text||''));else child.stdin.end();const finish=result=>{if(settled)return;settled=true;if(timer)clearTimeout(timer);child.stdout.destroy();child.stderr.destroy();input.onExit?.(result);resolve(result)};const timer=input.timeout?setTimeout(()=>{timedOut=true;child.kill()},input.timeout):null;child.on('error',e=>finish({ok:false,reason:normalizeError(e),error:redact(e.message)}));child.on('exit',code=>finish(code===0&&!timedOut?{ok:true,code,resolver_source:resolved.source}:{ok:false,code,reason:timedOut?'timeout':normalizeError(stderr),error:redact(stderr).slice(0,1000),resolver_source:resolved.source})); }); }
+  };
+}
+module.exports={createAdapter,normalizeError,redact};

package/src/agent-execution/adapters/claude.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('claude',i=>['--print',...(i.model==='configured-default'?[]:['--model',i.model]),...(i.writable_roots?.length?['--add-dir',...i.writable_roots]:[]),i.prompt_text]);

package/src/agent-execution/adapters/codex.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('codex',i=>({args:['exec',...(i.model==='configured-default'?[]:['--model',i.model]),...(i.reasoning_effort?['-c',`model_reasoning_effort="${i.reasoning_effort}"`]:[]),...(i.writable_roots||[]).flatMap(root=>['--add-dir',root]),'-'],stdin:true}));

package/src/agent-execution/adapters/opencode.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('opencode',i=>['run',...(i.model==='configured-default'?[]:['--model',i.model]),i.prompt_text]);

package/src/agent-execution/capabilities.js

@@ -0,0 +1,9 @@
+'use strict';
+const MATRIX = {
+  claude: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: true, model_catalog: false, reasoning_effort: false, executable: 'claude' },
+  codex: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: true, model_catalog: true, reasoning_effort: true, executable: 'codex' },
+  opencode: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: false, model_catalog: false, reasoning_effort: false, executable: 'opencode' }
+};
+function capabilities(host) { return { ...(MATRIX[host] || {}), source: 'registered_adapter' }; }
+function requiredCapability(mode) { return mode === 'subagent' ? 'native_subagent' : mode === 'fresh-session' ? 'fresh_session' : mode === 'external' ? 'external_process' : null; }
+module.exports = { MATRIX, capabilities, requiredCapability };

package/src/agent-execution/dispatcher.js

@@ -0,0 +1,72 @@
+'use strict';
+const fs=require('node:fs/promises');const path=require('node:path');const crypto=require('node:crypto');
+const adapters={claude:require('./adapters/claude'),codex:require('./adapters/codex'),opencode:require('./adapters/opencode')};
+const {loadManifest,resolveAgentExecution,resolveExecutionEntry}=require('./manifest');
+const {safeReportPath,validateReport}=require('./reports');
+const {createTelemetryBridge}=require('./telemetry-bridge');
+const TERMINAL=['approved','failed','cancelled'];const LEASE_MS=30000;
+function statePath(projectDir,feature){return path.join(projectDir,'.aioson','context',`agent-execution-state-${feature}.json`)}
+function leasePath(projectDir,feature){return `${statePath(projectDir,feature)}.lock`}
+async function atomic(file,value){await fs.mkdir(path.dirname(file),{recursive:true});const tmp=`${file}.${process.pid}.${crypto.randomUUID()}.tmp`;await fs.writeFile(tmp,`${JSON.stringify(value,null,2)}\n`);await fs.rename(tmp,file)}
+async function readState(projectDir,feature){try{return JSON.parse(await fs.readFile(statePath(projectDir,feature),'utf8'))}catch(e){if(e.code==='ENOENT')return null;throw e}}
+async function acquireLease(projectDir,feature){const file=leasePath(projectDir,feature);await fs.mkdir(path.dirname(file),{recursive:true});const owner=crypto.randomUUID();for(let pass=0;pass<2;pass++){try{const h=await fs.open(file,'wx');await h.writeFile(JSON.stringify({owner,expires_at:Date.now()+LEASE_MS}));await h.close();return{file,owner}}catch(e){if(e.code!=='EEXIST')throw e;try{const current=JSON.parse(await fs.readFile(file,'utf8'));if(current.expires_at>Date.now())return null;await fs.unlink(file)}catch(readError){if(readError.code!=='ENOENT'&&readError.name!=='SyntaxError')throw readError}}}return null}
+async function releaseLease(lease){if(!lease)return;try{const current=JSON.parse(await fs.readFile(lease.file,'utf8'));if(current.owner===lease.owner)await fs.unlink(lease.file)}catch(e){if(e.code!=='ENOENT')throw e}}
+async function safePromptPath(projectDir,promptPath){const root=await fs.realpath(projectDir);const candidate=path.resolve(root,promptPath||'.aioson/context/dev-state.md');const real=await fs.realpath(candidate);if(real!==root&&!real.startsWith(root+path.sep))throw new Error('prompt_path escapes project workspace');const stat=await fs.stat(real);if(!stat.isFile())throw new Error('prompt_path must be a regular file');return real}
+async function resolveWritableRoots(projectDir,roots=[]){const resolved=[];for(const configured of roots){if(typeof configured!=='string'||!configured.trim())throw new Error('writable_root must be a non-empty path');if(configured.split(/[\\/]+/).includes('..'))throw new Error(`writable_root traversal is forbidden: ${configured}`);const candidate=path.resolve(projectDir,configured);let real;try{real=await fs.realpath(candidate)}catch{throw new Error(`writable_root does not exist: ${configured}`)}if(!(await fs.stat(real)).isDirectory())throw new Error(`writable_root is not a directory: ${configured}`);if(!resolved.includes(real))resolved.push(real)}return resolved}
+function capacitySequence(manifest,resolved){const policy=manifest.capacity_policy;if(policy.strategy!=='fallback')return[];return resolved.fallbacks.filter(item=>policy.allow_cross_host===true||item.host===resolved.host)}
+function applyCapacityPolicy(manifest,resolved,attemptCount=0){const p=manifest.capacity_policy;if(attemptCount>=p.max_attempts)return{action:'pause',reason:'capacity_limit'};if(p.strategy==='fallback'){const sequence=capacitySequence(manifest,resolved);return sequence.length?{action:'fallback',sequence}:{action:'pause',reason:'no_authorized_fallback'}}if(p.strategy==='retry'||p.strategy==='wait')return{action:p.strategy,backoff_ms:p.backoff_ms};return{action:'pause'}}
+async function executeWithCapacityPolicy({manifest,resolved,input,adapterRegistry=adapters,catalogLoader,wait=(ms)=>new Promise(resolve=>setTimeout(resolve,ms))}) {
+  const history=[];
+  const primary=resolved.ok?resolved:await resolveExecutionEntry(resolved,{catalogLoader});
+  if(!primary.ok)return{ok:false,reason:primary.reason,candidates:primary.candidates||[],history};
+  const candidates=[primary,...capacitySequence(manifest,resolved).map(item=>({...resolved,ok:false,host:item.host,model:item.model,model_requested:undefined}))];
+  let index=0;
+  for(let count=0;count<manifest.capacity_policy.max_attempts;count++){
+    let candidate=candidates[index];
+    if(!candidate.ok){
+      candidate=await resolveExecutionEntry(candidate,{catalogLoader});
+      candidates[index]=candidate;
+      if(!candidate.ok){
+        history.push({attempt:count+1,host:candidate.host,model_requested:candidate.model_requested||candidate.model,model:null,reason:candidate.reason});
+        return{ok:false,reason:candidate.reason,candidates:candidate.candidates||[],history};
+      }
+    }
+    const adapter=adapterRegistry[candidate.host];
+    if(!adapter)return{ok:false,reason:'unsupported_host',history};
+    const prompt_text=String(input.prompt_text||'')
+      .replace(/host=[^,\n]+/,`host=${candidate.host}`)
+      .replace(/model_resolved=[^,\n]+/,`model_resolved=${candidate.model}`)
+      .replace(/model_resolution_strategy=[^,\n]+/,`model_resolution_strategy=${candidate.model_resolution_strategy}`);
+    const result=await adapter.execute({...input,prompt_text,mode:candidate.mode,model:candidate.model,reasoning_effort:candidate.reasoning_effort});
+    history.push({attempt:count+1,host:candidate.host,model_requested:candidate.model_requested,model:candidate.model,model_resolution_strategy:candidate.model_resolution_strategy,reasoning_effort:candidate.reasoning_effort,reason:result.reason||null});
+    if(result.ok)return{...result,host:candidate.host,model:candidate.model,model_requested:candidate.model_requested,model_resolution_strategy:candidate.model_resolution_strategy,reasoning_effort:candidate.reasoning_effort,history};
+    if(result.reason!=='capacity')return{...result,history};
+    const decision=applyCapacityPolicy(manifest,resolved,count);
+    if(decision.action==='pause')return{ok:false,reason:decision.reason||'capacity',history};
+    if(decision.action==='fallback'){
+      if(index+1>=candidates.length)return{ok:false,reason:'fallback_exhausted',history};
+      index+=1;
+    }else if(decision.action==='wait'||decision.action==='retry'){
+      if(decision.backoff_ms)await wait(decision.backoff_ms);
+    }
+  }
+  return{ok:false,reason:'capacity_limit',history};
+}
+function buildExecutionPrompt(promptText,expected,reportPath){return `${promptText}\n\nAIOSON EXECUTION CONTRACT\nComplete the requested agent work, then write exactly one JSON report to: ${reportPath}\nThe report must include: version=1, feature=${expected.feature}, run_id=${expected.run_id}, attempt_id=${expected.attempt_id}, agent=${expected.agent}, host=${expected.host}, model_requested=${expected.model_requested}, model_resolved=${expected.model_resolved}, model_resolution_strategy=${expected.model_resolution_strategy}, reasoning_effort=${expected.reasoning_effort||'null'}, manifest_digest=${expected.manifest_digest}, writable_roots=${JSON.stringify(expected.writable_roots)}, started_at, finished_at, verdict (PASS|FAIL|BLOCKED), findings[], evidence[]. Do not report PASS unless the work and verification completed.`}
+async function readBoundReport(projectDir,relative,expected){const file=safeReportPath(projectDir,relative);let report;try{report=JSON.parse(await fs.readFile(file,'utf8'))}catch(error){return{ok:false,reason:error.code==='ENOENT'?'report_missing':'report_invalid_json',error:error.message}}const validation=validateReport(report,expected);return validation.ok?{ok:true,file,report}:{ok:false,reason:'report_binding_invalid',errors:validation.errors}}
+async function dispatch({projectDir,feature,agent='dev',runId,promptPath,adapterRegistry=adapters,catalogLoader,timeout=600000}){
+ const lease=await acquireLease(projectDir,feature);if(!lease)return{ok:false,status:'paused',reason:'lease_held',resume_command:`aioson agent:execution:resume . --feature=${feature}`};
+ try{const loaded=await loadManifest(projectDir,feature);if(!loaded.exists)return{ok:false,status:'paused',reason:'manifest_missing',resume_command:`aioson agent:execution:resume . --feature=${feature}`};if(!loaded.ok)return{ok:false,status:'paused',reason:'manifest_invalid',errors:loaded.errors};
+  let state=await readState(projectDir,feature);if(state&&state.manifest_digest!==loaded.digest&&!TERMINAL.includes(state.status))return{ok:false,status:'paused',reason:'manifest_digest_changed',expected:state.manifest_digest,actual:loaded.digest};if(state?.completed_agents?.includes(agent))return{ok:true,status:state.status,idempotent:true,state};
+  let safePrompt;try{safePrompt=await safePromptPath(projectDir,promptPath)}catch(error){return{ok:false,status:'paused',reason:'invalid_prompt_path',error:error.message}}
+  const resolved=await resolveAgentExecution(loaded.manifest,agent,{}, {catalogLoader});if(!resolved.ok)return{ok:false,status:'paused',reason:resolved.reason,candidates:resolved.candidates||[],supported:resolved.supported||[]};const adapter=adapterRegistry[resolved.host];const run_id=runId||state?.run_id||crypto.randomUUID();const attempt_id=crypto.randomUUID();if(!adapter)return{ok:false,status:'paused',reason:'unsupported_host'};let writableRoots;try{writableRoots=await resolveWritableRoots(projectDir,resolved.writable_roots)}catch(error){return{ok:false,status:'paused',reason:'invalid_writable_root',error:error.message}}const reportRelative=resolved.report.replace(/\{run_id\}/g,run_id);const reportFile=safeReportPath(projectDir,reportRelative);const expected={feature,run_id,attempt_id,agent,host:resolved.host,model_requested:resolved.model_requested,model_resolved:resolved.model,model_resolution_strategy:resolved.model_resolution_strategy,reasoning_effort:resolved.reasoning_effort,manifest_digest:loaded.digest,writable_roots:writableRoots,status:'running'};const promptText=await fs.readFile(safePrompt,'utf8');const executionInput={mode:resolved.mode,model:resolved.model,reasoning_effort:resolved.reasoning_effort,writable_roots:writableRoots,cwd:projectDir,prompt_text:buildExecutionPrompt(promptText,expected,path.relative(projectDir,reportFile)),timeout};const built=adapter.build(executionInput);
+  const correlation={feature,agent,dispatcher_run_id:run_id,attempt_id,host:resolved.host,model:resolved.model,model_requested:resolved.model_requested,model_resolved:resolved.model,reasoning_effort:resolved.reasoning_effort,model_resolution_strategy:resolved.model_resolution_strategy,catalog_source:resolved.catalog_source};const telemetry=await createTelemetryBridge(projectDir,correlation);
+  const attempt={...expected,telemetry_run_id:telemetry.run.telemetry_run_id,status:built.ok?'running':'blocked',reason:built.reason||null,report:reportRelative};state={version:1,feature,run_id,manifest_path:path.relative(projectDir,loaded.path),manifest_digest:loaded.digest,status:built.ok?'running':'paused',reason:built.reason||null,attempts:[...(state?.attempts||[]),attempt],completed_agents:state?.completed_agents||[],updated_at:new Date().toISOString()};await atomic(statePath(projectDir,feature),state);if(!built.ok){telemetry.transition('paused',built.reason);telemetry.close();return{ok:false,status:'paused',reason:built.reason,capability:built.capability,resume_command:`aioson agent:execution:resume . --feature=${feature}`,state}};
+  Object.assign(executionInput,{onSpawn:(pid,at)=>telemetry.onSpawn(pid,at),onStdout:d=>telemetry.output('stdout',d),onStderr:d=>telemetry.output('stderr',d)});
+  const execution=await executeWithCapacityPolicy({manifest:loaded.manifest,resolved,input:executionInput,adapterRegistry,catalogLoader});attempt.execution_history=execution.history||[];for(const item of attempt.execution_history){if(item.attempt>1)telemetry.event(item.host===resolved.host?'retry':'fallback',`${item.host}/${item.model}`,{attempt:item.attempt,reason:item.reason})}attempt.model_resolved=execution.model||resolved.model;attempt.model_resolution_strategy=execution.model_resolution_strategy||resolved.model_resolution_strategy;attempt.reasoning_effort=execution.reasoning_effort||resolved.reasoning_effort;attempt.host_resolved=execution.host||resolved.host;if(!execution.ok){attempt.status='blocked';attempt.reason=execution.reason;state.status='paused';state.reason=execution.reason;state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);if(execution.reason==='timeout')telemetry.event('timeout','Execution timeout');telemetry.transition('paused',execution.reason);telemetry.close();return{ok:false,status:'paused',reason:execution.reason,candidates:execution.candidates||[],execution,state,resume_command:`aioson agent:execution:resume . --feature=${feature}`}}
+  telemetry.transition('waiting_report');
+  const boundExpected={...expected,host:attempt.host_resolved,model_resolved:attempt.model_resolved,model_resolution_strategy:attempt.model_resolution_strategy,reasoning_effort:attempt.reasoning_effort,status:'running'};const reportResult=await readBoundReport(projectDir,reportRelative,boundExpected);if(!reportResult.ok){attempt.status='blocked';attempt.reason=reportResult.reason;state.status='paused';state.reason=reportResult.reason;state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);telemetry.transition('paused',reportResult.reason);telemetry.close();return{ok:false,status:'paused',reason:reportResult.reason,report:reportResult,state,resume_command:`aioson agent:execution:resume . --feature=${feature}`}}
+  const digest=crypto.createHash('sha256').update(JSON.stringify(reportResult.report)).digest('hex');telemetry.report(reportResult.report,reportRelative,digest);attempt.status='completed';attempt.verdict=reportResult.report.verdict;state.status=reportResult.report.verdict==='PASS'?'verification_planned':'correcting';telemetry.transition(reportResult.report.verdict==='PASS'?'passed':reportResult.report.verdict==='FAIL'?'failed':'correcting');telemetry.close();if(reportResult.report.verdict==='PASS'&&!state.completed_agents.includes(agent))state.completed_agents.push(agent);state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);return{ok:true,status:state.status,run_id,attempt_id,execution,report:reportResult.report,state};
+ }finally{await releaseLease(lease)}
+}
+module.exports={acquireLease,applyCapacityPolicy,buildExecutionPrompt,capacitySequence,dispatch,executeWithCapacityPolicy,leasePath,readBoundReport,readState,releaseLease,resolveWritableRoots,safePromptPath,statePath};

package/src/agent-execution/executable-resolver.js

@@ -0,0 +1,7 @@
+'use strict';
+const fs=require('node:fs/promises');const path=require('node:path');
+async function isFile(file){try{return(await fs.stat(file)).isFile()}catch{return false}}
+async function resolveNpmCmdShim(cmdPath){const text=await fs.readFile(cmdPath,'utf8');const dir=path.dirname(cmdPath);const matches=[...text.matchAll(/["'](%~dp0|%dp0%)[\\/]?([^"']+\.(?:js|exe))["']/gi)];const targets=matches.map(match=>path.resolve(dir,match[2].replace(/[\\/]+/g,path.sep))).filter(file=>!/[\\/]node\.exe$/i.test(file));for(const target of targets.reverse()){if(!(await isFile(target)))continue;const real=await fs.realpath(target);return path.extname(real).toLowerCase()==='.js'?{executable:process.execPath,prefixArgs:[real],source:'npm_cmd_js'}:{executable:real,prefixArgs:[],source:'npm_cmd_exe'}}throw new Error(`Unsupported or invalid npm command shim: ${cmdPath}`)}
+async function resolveExecutable(command,{env=process.env,platform=process.platform}={}){if(typeof command!=='string'||!command.trim())throw new Error('Executable is required');const raw=command.trim();if(path.isAbsolute(raw)){if(!(await isFile(raw)))throw new Error(`Executable not found: ${raw}`);return platform==='win32'&&path.extname(raw).toLowerCase()==='.cmd'?resolveNpmCmdShim(raw):{executable:await fs.realpath(raw),prefixArgs:[],source:'absolute'}}if(platform!=='win32')return{executable:raw,prefixArgs:[],source:'path'};const dirs=String(env.PATH||env.Path||'').split(';').filter(Boolean);for(const dir of dirs){for(const ext of ['.exe','.cmd','']){const candidate=path.join(dir,`${raw}${ext}`);if(!(await isFile(candidate)))continue;if(ext==='.cmd')return resolveNpmCmdShim(candidate);if(ext==='.exe')return{executable:await fs.realpath(candidate),prefixArgs:[],source:'windows_exe'};}}
+ throw new Error(`Executable not found on PATH: ${raw}`)}
+module.exports={resolveExecutable,resolveNpmCmdShim};

package/src/agent-execution/manifest.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { AGENTS, validateManifest } = require('./schema');
+const { capabilities } = require('./capabilities');
+const { loadModelCatalog } = require('./model-catalog');
+const { resolveModel, validateReasoningEffort } = require('./model-resolver');
+
+function manifestPath(projectDir, feature) { return path.join(projectDir, '.aioson', 'context', `agent-execution-${feature}.json`); }
+function defaults(feature, host = 'codex') {
+  const agents = {};
+  for (const id of AGENTS) agents[id] = { enabled: true, host, mode: 'external', model: 'configured-default', writable_roots: [], fallbacks: [], report: `.aioson/context/reports/${feature}/{run_id}/${id}.json` };
+  return { version: 1, feature, host, generated_at: new Date().toISOString(), agents, capacity_policy: { strategy: 'pause', max_attempts: 1, backoff_ms: 0 }, cycle_limits: { dev_qa: 3, tester: 3, pentester: 3 }, reporting: { format: 'json', markdown: true } };
+}
+function stable(value) { if (Array.isArray(value)) return value.map(stable); if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(k => [k, stable(value[k])])); return value; }
+function digest(value) { return crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex'); }
+function mergeAdditive(existing, base) {
+  if (Array.isArray(existing)) return existing;
+  if (!existing || typeof existing !== 'object') return existing === undefined ? base : existing;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(existing)) out[key] = value && typeof value === 'object' && !Array.isArray(value) ? mergeAdditive(value, base && base[key]) : value;
+  return out;
+}
+async function initManifest(projectDir, feature, host, { overwrite = false } = {}) {
+  const file = manifestPath(projectDir, feature); const base = defaults(feature, host);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  let value = base;
+  try { const old = JSON.parse(await fs.readFile(file, 'utf8')); if (!overwrite) value = mergeAdditive(old, base); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return { path: file, manifest: value, digest: digest(value) };
+}
+async function loadManifest(projectDir, feature) {
+  const file = manifestPath(projectDir, feature);
+  try { const value = JSON.parse(await fs.readFile(file, 'utf8')); const validation = validateManifest(value, feature); return { exists: true, path: file, manifest: value, digest: digest(value), ...validation }; }
+  catch (error) { if (error.code === 'ENOENT') return { exists: false, legacy: true, path: file, ok: true }; return { exists: true, path: file, ok: false, errors: [{ path: '$', message: error.message }] }; }
+}
+function resolveAgent(manifest, agent, overrides = {}) { const entry = manifest.agents[agent]; return { ...entry, host: overrides.host || entry.host || manifest.host, model: overrides.model || entry.model, source: 'manifest' }; }
+async function resolveExecutionEntry(entry, { catalogLoader = loadModelCatalog } = {}) {
+  const cap = capabilities(entry.host);
+  if (entry.reasoning_effort && !cap.reasoning_effort) return { ok: false, reason: 'unsupported_reasoning_effort', host: entry.host, model_requested: entry.model, candidates: [] };
+  const catalog = cap.model_catalog ? await catalogLoader(entry.host) : { available: false, reason: 'unsupported_model_catalog', models: [] };
+  const model = resolveModel(entry.model, catalog);
+  if (!model.ok) return { ...entry, ...model, model_requested: entry.model };
+  const effort = validateReasoningEffort(model, entry.reasoning_effort);
+  if (!effort.ok) return { ...entry, ok: false, reason: effort.reason, supported: effort.supported, candidates: [], model_requested: entry.model, model_resolved: model.resolved };
+  return {
+    ...entry,
+    ok: true,
+    model_requested: entry.model,
+    model: model.resolved,
+    model_resolved: model.resolved,
+    model_resolution_strategy: model.strategy,
+    catalog_source: model.catalog_source,
+    catalog_fetched_at: model.catalog_fetched_at,
+    reasoning_effort: effort.reasoning_effort,
+    reasoning_effort_verification: effort.verification
+  };
+}
+async function resolveAgentExecution(manifest, agent, overrides = {}, options = {}) { return resolveExecutionEntry(resolveAgent(manifest, agent, overrides), options); }
+module.exports = { defaults, digest, initManifest, loadManifest, manifestPath, mergeAdditive, resolveAgent, resolveAgentExecution, resolveExecutionEntry };

package/src/agent-execution/model-catalog.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { REASONING_EFFORTS } = require('./schema');
+
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_MODELS = 1000;
+const SAFE_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+
+function unavailable(reason) {
+  return { available: false, reason, source: null, fetched_at: null, client_version: null, models: [] };
+}
+
+function codexHome(env, home) {
+  const configured = typeof env.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
+  return configured || path.join(home, '.codex');
+}
+
+function normalizeEfforts(levels) {
+  if (!Array.isArray(levels)) return [];
+  const supported = new Set(REASONING_EFFORTS);
+  return [...new Set(levels.map(level => typeof level === 'string' ? level : level?.effort)
+    .filter(effort => typeof effort === 'string' && supported.has(effort)))];
+}
+
+function sanitizeModels(models) {
+  if (!Array.isArray(models)) return [];
+  const bySlug = new Map();
+  for (const model of models) {
+    const slug = typeof model?.slug === 'string' ? model.slug.trim() : '';
+    if (!SAFE_MODEL_ID.test(slug) || bySlug.has(slug)) continue;
+    const display = typeof model.display_name === 'string' && model.display_name.trim()
+      ? model.display_name.trim().slice(0, 200)
+      : slug;
+    bySlug.set(slug, {
+      slug,
+      display_name: display,
+      supported_efforts: normalizeEfforts(model.supported_reasoning_levels)
+    });
+  }
+  return [...bySlug.values()];
+}
+
+async function loadModelCatalog(host, options = {}) {
+  if (host !== 'codex') return unavailable('unsupported_model_catalog');
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+  const file = path.join(codexHome(env, home), 'models_cache.json');
+  const maxBytes = Math.max(1, Number(options.maxBytes) || DEFAULT_MAX_BYTES);
+  const maxModels = Math.max(1, Number(options.maxModels) || DEFAULT_MAX_MODELS);
+  let stat;
+  try {
+    stat = await fs.stat(file);
+  } catch {
+    return unavailable('catalog_unavailable');
+  }
+  if (!stat.isFile()) return unavailable('catalog_unavailable');
+  if (stat.size > maxBytes) return unavailable('catalog_too_large');
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return unavailable('catalog_invalid');
+  }
+  if (Array.isArray(parsed?.models) && parsed.models.length > maxModels) return unavailable('catalog_too_many_models');
+  const models = sanitizeModels(parsed?.models);
+  if (!models.length) return unavailable('catalog_incompatible');
+  return {
+    available: true,
+    reason: null,
+    source: 'codex_local_cache',
+    fetched_at: typeof parsed.fetched_at === 'string' ? parsed.fetched_at.slice(0, 100) : null,
+    client_version: typeof parsed.client_version === 'string' ? parsed.client_version.slice(0, 50) : null,
+    models
+  };
+}
+
+module.exports = { DEFAULT_MAX_BYTES, DEFAULT_MAX_MODELS, loadModelCatalog, sanitizeModels };

package/src/agent-execution/model-resolver.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { MAX_MODEL_NAME_LENGTH, REASONING_EFFORTS } = require('./schema');
+
+const LITERAL_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+const GENERIC_ALIASES = new Set(['gpt', 'model', 'openai', 'codex']);
+
+function tokens(value) {
+  return String(value || '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase().match(/[a-z]+|\d+/g) || [];
+}
+
+function normalizeModelName(value) { return tokens(value).join('-'); }
+function numericTokens(value) { return tokens(value).filter(token => /^\d+$/.test(token)); }
+function alphaTokens(value) { return tokens(value).filter(token => /^[a-z]+$/.test(token)); }
+
+function distance(left, right) {
+  const a = String(left); const b = String(right);
+  if (a.length > MAX_MODEL_NAME_LENGTH || b.length > MAX_MODEL_NAME_LENGTH) return Number.POSITIVE_INFINITY;
+  const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) matrix[i][0] = i;
+  for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        matrix[i][j] = Math.min(matrix[i][j], matrix[i - 2][j - 2] + cost);
+      }
+    }
+  }
+  return matrix[a.length][b.length];
+}
+
+function candidates(models) {
+  return (Array.isArray(models) ? models : []).filter(model => model && typeof model.slug === 'string')
+    .map(model => ({
+      slug: model.slug,
+      display_name: typeof model.display_name === 'string' ? model.display_name : model.slug,
+      supported_efforts: Array.isArray(model.supported_efforts) ? model.supported_efforts : []
+    }));
+}
+
+function uniqueBySlug(models) { return [...new Map(models.map(model => [model.slug, model])).values()]; }
+function diagnosticSlugs(models) { return uniqueBySlug(models).map(model => model.slug).sort().slice(0, 5); }
+
+function success(requested, model, strategy, catalog) {
+  return {
+    ok: true,
+    requested,
+    resolved: model.slug,
+    strategy,
+    catalog_source: catalog?.source || null,
+    catalog_fetched_at: catalog?.fetched_at || null,
+    supported_efforts: model.supported_efforts || []
+  };
+}
+
+function failure(requested, reason, models = [], catalog = null) {
+  return {
+    ok: false,
+    requested,
+    resolved: null,
+    reason,
+    candidates: diagnosticSlugs(models),
+    catalog_source: catalog?.source || null,
+    catalog_fetched_at: catalog?.fetched_at || null
+  };
+}
+
+function resolveModel(value, catalog) {
+  const requested = typeof value === 'string' ? value.trim() : '';
+  if (!requested) return failure(requested, 'invalid_model');
+  if (requested.length > MAX_MODEL_NAME_LENGTH) return failure(requested.slice(0, MAX_MODEL_NAME_LENGTH), 'invalid_model');
+  if (requested === 'configured-default') {
+    return success(requested, { slug: requested, supported_efforts: [] }, 'configured_default', catalog);
+  }
+  if (!catalog?.available) {
+    if (!LITERAL_MODEL_ID.test(requested)) return failure(requested, catalog?.reason || 'catalog_unavailable');
+    return success(requested, { slug: requested, supported_efforts: [] }, 'unverified_literal', null);
+  }
+  const models = candidates(catalog.models);
+  const exact = models.find(model => model.slug === requested);
+  if (exact) return success(requested, exact, 'exact_slug', catalog);
+
+  const requestedKey = normalizeModelName(requested);
+  const normalized = uniqueBySlug(models.filter(model => normalizeModelName(model.slug) === requestedKey
+    || normalizeModelName(model.display_name) === requestedKey));
+  if (normalized.length === 1) return success(requested, normalized[0], 'normalized_name', catalog);
+  if (normalized.length > 1) return failure(requested, 'ambiguous_model', normalized, catalog);
+
+  const requestedTokens = tokens(requested);
+  const isGeneric = requestedTokens.length === 1 && GENERIC_ALIASES.has(requestedTokens[0]);
+  const isUsableAlias = requestedKey.length >= 4 && !isGeneric && requestedTokens.some(token => /^[a-z]+$/.test(token));
+  if (isUsableAlias) {
+    const alias = uniqueBySlug(models.filter(model => {
+      const slugTokens = tokens(model.slug); const displayTokens = tokens(model.display_name);
+      const suffix = list => list.length >= requestedTokens.length
+        && requestedTokens.every((token, index) => token === list[list.length - requestedTokens.length + index]);
+      return suffix(slugTokens) || suffix(displayTokens);
+    }));
+    if (alias.length === 1) return success(requested, alias[0], 'unique_alias', catalog);
+    if (alias.length > 1) return failure(requested, 'ambiguous_model', alias, catalog);
+  }
+
+  const requestedNumbers = numericTokens(requested);
+  const requestedAlpha = alphaTokens(requested);
+  const eligible = models.filter(model => {
+    const modelNumbers = numericTokens(model.slug);
+    if (requestedNumbers.length && requestedNumbers.join('.') !== modelNumbers.join('.')) return false;
+    const modelAlpha = alphaTokens(model.slug);
+    return !requestedAlpha.length || requestedAlpha[0] === modelAlpha[0];
+  });
+  const ranked = eligible.map(model => ({ model, score: distance(requestedKey, normalizeModelName(model.slug)) }))
+    .sort((a, b) => a.score - b.score || a.model.slug.localeCompare(b.model.slug));
+  const maxDistance = Math.min(3, Math.max(1, Math.floor(requestedKey.length * 0.1)));
+  if (!ranked.length || ranked[0].score > maxDistance) return failure(requested, 'model_not_found', [], catalog);
+  const best = ranked.filter(item => item.score === ranked[0].score);
+  if (best.length !== 1) return failure(requested, 'ambiguous_model', best.map(item => item.model), catalog);
+  return success(requested, best[0].model, 'fuzzy_unique', catalog);
+}
+
+function validateReasoningEffort(resolution, effort) {
+  if (effort === undefined || effort === null || effort === '') return { ok: true, reasoning_effort: null, verification: 'inherited' };
+  if (!REASONING_EFFORTS.includes(effort)) return { ok: false, reason: 'invalid_reasoning_effort', supported: REASONING_EFFORTS };
+  if (!resolution?.ok) return { ok: false, reason: resolution?.reason || 'model_resolution_failed', supported: [] };
+  const supported = Array.isArray(resolution.supported_efforts) ? resolution.supported_efforts : [];
+  if (supported.length && !supported.includes(effort)) return { ok: false, reason: 'unsupported_reasoning_effort', supported };
+  return { ok: true, reasoning_effort: effort, verification: supported.length ? 'catalog' : 'unverified' };
+}
+
+module.exports = { distance, normalizeModelName, resolveModel, validateReasoningEffort };

package/src/agent-execution/reports.js

@@ -0,0 +1,9 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const VERDICTS = ['PASS', 'FAIL', 'BLOCKED'];
+const IDENTITY_FIELDS = ['feature','run_id','attempt_id','agent','host','model_resolved','manifest_digest'];
+function validateReport(r, expected = null) { const errors=[]; const req=['version','feature','run_id','attempt_id','agent','host','model_requested','model_resolved','manifest_digest','writable_roots','started_at','finished_at','verdict','findings','evidence'];if(expected?.model_resolution_strategy!==undefined)req.push('model_resolution_strategy'); for(const k of req) if(r?.[k]===undefined) errors.push({path:`$.${k}`,message:'is required'}); if(r && !VERDICTS.includes(r.verdict)) errors.push({path:'$.verdict',message:'must be PASS, FAIL, or BLOCKED'}); if(r && !Array.isArray(r.findings)) errors.push({path:'$.findings',message:'must be an array'});if(r&&!Array.isArray(r.writable_roots))errors.push({path:'$.writable_roots',message:'must be an array'}); if(expected) for(const key of IDENTITY_FIELDS) if(r?.[key]!==expected[key]) errors.push({path:`$.${key}`,message:'does not match the registered attempt'});for(const key of ['model_requested','model_resolution_strategy'])if(expected?.[key]!==undefined&&r?.[key]!==expected[key])errors.push({path:`$.${key}`,message:'does not match the registered attempt'});if(expected&&expected.reasoning_effort&&r?.reasoning_effort!==expected.reasoning_effort)errors.push({path:'$.reasoning_effort',message:'does not match the registered attempt'});if(expected&&JSON.stringify(r?.writable_roots)!==JSON.stringify(expected.writable_roots))errors.push({path:'$.writable_roots',message:'does not match the registered attempt'}); if(expected && !['ready','running'].includes(expected.status)) errors.push({path:'$.attempt_id',message:'attempt is not eligible to report'}); return {ok:errors.length===0,errors}; }
+function safeReportPath(projectDir, relative) { const root=path.resolve(projectDir,'.aioson','context','reports'); const target=path.resolve(projectDir,relative); if(target!==root && !target.startsWith(root+path.sep)) throw new Error('report path escapes report root'); return target; }
+async function writeReport(projectDir, relative, report, expected) { const check=validateReport(report,expected); if(!check.ok){const e=new Error('invalid report');e.errors=check.errors;throw e;} const file=safeReportPath(projectDir,relative); await fs.mkdir(path.dirname(file),{recursive:true}); const handle=await fs.open(file,'wx'); try{await handle.writeFile(`${JSON.stringify(report,null,2)}\n`,'utf8')}finally{await handle.close()} return file; }
+module.exports={validateReport,safeReportPath,writeReport};

package/src/agent-execution/schema.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const HOSTS = ['claude', 'codex', 'opencode'];
+const MODES = ['fresh-session', 'subagent', 'external', 'current-session'];
+const AGENTS = ['dev', 'qa', 'tester', 'pentester', 'validator'];
+const REASONING_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const MAX_MODEL_NAME_LENGTH = 200;
+const ROOT_KEYS = ['version','feature','host','generated_at','agents','capacity_policy','cycle_limits','reporting'];
+const AGENT_KEYS = ['enabled','host','mode','model','reasoning_effort','writable_roots','fallbacks','report'];
+const SECRET_KEY = /token|secret|password|authorization|api[_-]?key/i;
+
+function validateManifest(value, expectedFeature) {
+  const errors = [];
+  const add = (path, message) => errors.push({ path, message });
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ok: false, errors: [{ path: '$', message: 'must be an object' }] };
+  const scanSecrets=(node,p='$')=>{if(!node||typeof node!=='object')return;for(const [key,child] of Object.entries(node)){if(SECRET_KEY.test(key))add(`${p}.${key}`,'secret fields are forbidden; use environment configuration');scanSecrets(child,`${p}.${key}`)}};scanSecrets(value);
+  for (const key of Object.keys(value)) if (!ROOT_KEYS.includes(key)) add(`$.${key}`, SECRET_KEY.test(key) ? 'secret fields are forbidden; use environment configuration' : 'unknown field');
+  if (value.version !== 1) add('$.version', 'must equal 1');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.feature || '')) add('$.feature', 'must be a kebab-case slug');
+  if (expectedFeature && value.feature !== expectedFeature) add('$.feature', `must equal ${expectedFeature}`);
+  if (!HOSTS.includes(value.host)) add('$.host', `must be one of ${HOSTS.join(', ')}`);
+  if (!value.agents || typeof value.agents !== 'object') add('$.agents', 'must be an object');
+  else for(const key of Object.keys(value.agents)) if(!AGENTS.includes(key)) add(`$.agents.${key}`,'unknown agent');
+  for (const id of AGENTS) {
+    const agent = value.agents && value.agents[id];
+    if (!agent || typeof agent !== 'object') { add(`$.agents.${id}`, 'is required'); continue; }
+    for (const key of Object.keys(agent)) if (!AGENT_KEYS.includes(key)) add(`$.agents.${id}.${key}`, SECRET_KEY.test(key) ? 'secret fields are forbidden; use environment configuration' : 'unknown field');
+    if (typeof agent.enabled !== 'boolean') add(`$.agents.${id}.enabled`, 'must be boolean');
+    if (!HOSTS.includes(agent.host)) add(`$.agents.${id}.host`, `must be one of ${HOSTS.join(', ')}`);
+    if (!MODES.includes(agent.mode)) add(`$.agents.${id}.mode`, `must be one of ${MODES.join(', ')}`);
+    if (typeof agent.model !== 'string' || !agent.model.trim()) add(`$.agents.${id}.model`, 'must be a non-empty model id');
+    else if (agent.model.length > MAX_MODEL_NAME_LENGTH) add(`$.agents.${id}.model`, `must be at most ${MAX_MODEL_NAME_LENGTH} characters`);
+    if (agent.reasoning_effort !== undefined && !REASONING_EFFORTS.includes(agent.reasoning_effort)) add(`$.agents.${id}.reasoning_effort`, `must be one of ${REASONING_EFFORTS.join(', ')}`);
+    if(!Array.isArray(agent.writable_roots))add(`$.agents.${id}.writable_roots`,'must be an array');else agent.writable_roots.forEach((root,index)=>{if(typeof root!=='string'||!root.trim())add(`$.agents.${id}.writable_roots[${index}]`,'must be a non-empty path')});
+    if (!Array.isArray(agent.fallbacks)) add(`$.agents.${id}.fallbacks`, 'must be an array');
+    else agent.fallbacks.forEach((fallback,index)=>{const p=`$.agents.${id}.fallbacks[${index}]`;if(!fallback||typeof fallback!=='object'||Array.isArray(fallback)){add(p,'must be {host, model}');return}for(const key of Object.keys(fallback))if(!['host','model'].includes(key))add(`${p}.${key}`,'unknown field');if(!HOSTS.includes(fallback.host))add(`${p}.host`,`must be one of ${HOSTS.join(', ')}`);if(typeof fallback.model!=='string'||!fallback.model.trim())add(`${p}.model`,'must be a non-empty model id');else if(fallback.model.length>MAX_MODEL_NAME_LENGTH)add(`${p}.model`,`must be at most ${MAX_MODEL_NAME_LENGTH} characters`)});
+    if (typeof agent.report !== 'string' || !agent.report.includes('{run_id}')) add(`$.agents.${id}.report`, 'must include {run_id}');
+  }
+  const limits = value.cycle_limits;
+  if (!limits || typeof limits !== 'object') add('$.cycle_limits', 'is required');
+  else for (const [key, number] of Object.entries(limits)) if (!Number.isInteger(number) || number < 0) add(`$.cycle_limits.${key}`, 'must be a non-negative integer');
+  if (!value.capacity_policy || !['pause', 'retry', 'wait', 'fallback'].includes(value.capacity_policy.strategy)) add('$.capacity_policy.strategy', 'must be pause, retry, wait, or fallback');
+  else { for(const key of Object.keys(value.capacity_policy)) if(!['strategy','max_attempts','backoff_ms','allow_cross_host'].includes(key)) add(`$.capacity_policy.${key}`,'unknown field'); if(!Number.isInteger(value.capacity_policy.max_attempts)||value.capacity_policy.max_attempts<1)add('$.capacity_policy.max_attempts','must be a positive integer'); if(!Number.isInteger(value.capacity_policy.backoff_ms)||value.capacity_policy.backoff_ms<0)add('$.capacity_policy.backoff_ms','must be a non-negative integer'); }
+  if(!value.reporting||typeof value.reporting!=='object')add('$.reporting','is required');else for(const key of Object.keys(value.reporting))if(!['format','markdown'].includes(key))add(`$.reporting.${key}`,'unknown field');
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = { AGENTS, HOSTS, MAX_MODEL_NAME_LENGTH, MODES, REASONING_EFFORTS, validateManifest };

package/src/agent-execution/telemetry-bridge.js

@@ -0,0 +1,15 @@
+'use strict';
+const crypto=require('node:crypto');
+const {openRuntimeDb,createExecutionRun,attachExecutionProcess,transitionExecutionRun,appendExecutionEvent,attachExecutionReport,pruneExecutionTelemetry}=require('../runtime-store');
+const DEFAULTS={maxQueueBytes:256*1024,maxEventBytes:16*1024,maxPersistedBytes:1024*1024,maxPendingBytes:64*1024,flushMs:100};
+function redact(value){return String(value||'').replace(/(authorization\s*[:=]\s*(?:bearer\s+)?|api[_-]?key\s*[:=]\s*|token\s*[:=]\s*|password\s*[:=]\s*)[^\s,;]+/gi,'$1[REDACTED]').replace(/\b(sk-[A-Za-z0-9_-]{8,})\b/g,'[REDACTED]');}
+function fingerprint(pid,startedAt){return crypto.createHash('sha256').update(`${pid}:${startedAt}`).digest('hex').slice(0,24);}
+async function createTelemetryBridge(projectDir,correlation,options={}){
+ const cfg={...DEFAULTS,...options};const opened=await openRuntimeDb(projectDir);const db=opened.db;pruneExecutionTelemetry(db,{retentionDays:options.retentionDays||14,batch:100});const run=createExecutionRun(db,correlation);let queue=[],queued=0,persisted=0,dropped=0,closed=false,timer=null;const pendingByStream=new Map();
+ const flush=()=>{if(!queue.length&&!dropped)return;const items=queue;queue=[];queued=0;for(const item of items){appendExecutionEvent(db,run.telemetry_run_id,item);persisted+=item.bytes;}if(dropped){appendExecutionEvent(db,run.telemetry_run_id,{type:'output_truncated',safe_summary:`${dropped} output bytes dropped`,bytes:Math.min(dropped,cfg.maxEventBytes)});db.prepare('UPDATE agent_execution_runs SET truncated_bytes=truncated_bytes+?,dropped_events=dropped_events+1 WHERE telemetry_run_id=?').run(dropped,run.telemetry_run_id);dropped=0;}};
+ const schedule=()=>{if(!timer)timer=setTimeout(()=>{timer=null;try{flush();}catch{}},cfg.flushMs)};
+ const enqueue=(stream,text)=>{let safe=redact(text);let bytes=Buffer.byteLength(safe);if(bytes>cfg.maxEventBytes){dropped+=bytes-cfg.maxEventBytes;safe=Buffer.from(safe).subarray(0,cfg.maxEventBytes).toString();bytes=Buffer.byteLength(safe)}if(persisted+queued+bytes>cfg.maxPersistedBytes||queued+bytes>cfg.maxQueueBytes){dropped+=bytes;return}queue.push({type:'output',stream,safe_summary:safe,bytes});queued+=bytes};
+ const output=(stream,chunk)=>{if(closed)return;let pending=(pendingByStream.get(stream)||'')+String(chunk||'');if(Buffer.byteLength(pending)>cfg.maxPendingBytes){dropped+=Buffer.byteLength(pending);pendingByStream.set(stream,'');return schedule()}let newline;while((newline=pending.indexOf('\n'))>=0){enqueue(stream,pending.slice(0,newline+1));pending=pending.slice(newline+1)}pendingByStream.set(stream,pending);schedule();};
+ return {run,output,onSpawn(pid,startedAt=new Date().toISOString()){return attachExecutionProcess(db,correlation,{pid,fingerprint:fingerprint(pid,startedAt)})},event(type,summary,payload){appendExecutionEvent(db,correlation,{type,safe_summary:redact(summary),payload})},transition(next,reason){flush();return transitionExecutionRun(db,correlation,next,reason)},report(report,path,digest){flush();return attachExecutionReport(db,correlation,{...report,path,digest})},close(){if(closed)return;closed=true;if(timer)clearTimeout(timer);for(const [stream,pending] of pendingByStream)if(pending)enqueue(stream,pending);flush();db.close();}};
+}
+module.exports={createTelemetryBridge,redact,fingerprint};

package/src/cli.js

@@ -188,7 +188,8 @@ const { runPreflight } = require('./commands/preflight');
 const { runClassify } = require('./commands/classify');
 const { runPrototypeCheck } = require('./commands/prototype-check');
 const { runVerifyImplementation } = require('./commands/verify-implementation');
-const { runVerificationPlan } = require('./commands/verification-plan');
+const { runVerificationPlan } = require('./commands/verification-plan');
+const { runAgentExecution } = require('./commands/agent-execution');
 const { runSizing } = require('./commands/sizing');
 const { runDetectTestRunner } = require('./commands/detect-test-runner');
 const { runPulseUpdate } = require('./commands/pulse-update');
@@ -673,7 +674,21 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'verify:implementation',
   'verify-implementation',
   'verification:plan',
-  'verification-plan',
+  'verification-plan',
+  'agent:execution:init',
+  'agent-execution-init',
+  'agent:execution:validate',
+  'agent-execution-validate',
+  'agent:execution:show',
+  'agent-execution-show',
+  'agent:execution:dispatch',
+  'agent-execution-dispatch',
+  'agent:execution:resume',
+  'agent-execution-resume',
+  'agent:execution:status',
+  'agent-execution-status',
+  'agent:execution:events',
+  'agent-execution-events',
   'sizing',
   'detect:test-runner',
   'detect-test-runner',
@@ -1626,8 +1641,11 @@ async function main() {
       result = await runPreflight({ args, options, logger: commandLogger });
     } else if (command === 'classify') {
       result = await runClassify({ args, options, logger: commandLogger });
-    } else if (command === 'verification:plan' || command === 'verification-plan') {
-      result = await runVerificationPlan({ args, options, logger: commandLogger });
+    } else if (command === 'verification:plan' || command === 'verification-plan') {
+      result = await runVerificationPlan({ args, options, logger: commandLogger });
+    } else if (command.startsWith('agent:execution:') || command.startsWith('agent-execution-')) {
+      const sub = command.replace(/^agent:execution:|^agent-execution-/, '');
+      result = await runAgentExecution({ args, options: { ...options, sub }, logger: commandLogger });
     } else if (command === 'prototype:check' || command === 'prototype-check') {
       result = await runPrototypeCheck({ args, options, logger: commandLogger });
     } else if (command === 'verify:implementation' || command === 'verify-implementation') {