@yunhozz/arc 0.1.9 → 0.2.0

package/lib/installer/upgrade-state.mjs

@@ -5,7 +5,7 @@ import {loadModelConfig} from '../models/index.mjs';
 import {parseLanguage} from './language.mjs';
 import {parseLimits} from './limits.mjs';
 import {removeManagedBlock} from './global-config.mjs';
-import {renderShellCompletion} from './shell-completion.mjs';
+import {removeShellCompletion} from './shell-completion.mjs';
 import {readRuntimeConcurrency} from './runtime-config.mjs';
 const fail=message=>{throw new TargetConfigurationError(message);};
 export function collectInstalledState({safeFs,userHome,env={},cwd}){
@@ -21,7 +21,7 @@ export function collectInstalledState({safeFs,userHome,env={},cwd}){
   mandatory('SKILL.md');if(profiles.some(item=>!item.exists||!item.bytes.length))fail(`Incomplete ARC installation: missing profile at ${target.home}`);
   let language,modelConfig,limits;try{language=parseLanguage(mandatory('settings.toml')).language;modelConfig=loadModelConfig(mandatory('models.toml'),platform);limits=parseLimits(mandatory('limits.toml'));}catch(cause){throw new TargetConfigurationError(`Invalid installed ARC settings at ${target.home}: ${cause.message}`,{cause});}
   const native=inspectPath(safeFs,target.runtimeConfigPath,{kind:'file',read:true,snapshot});if(native.exists)try{readRuntimeConcurrency(platform,native.bytes);}catch(cause){throw new TargetConfigurationError(`Invalid native configuration at ${target.runtimeConfigPath}: ${cause.message}`,{cause});}
-  const shell=inspectPath(safeFs,path.join(userHome,'.zshrc'),{kind:'file',read:true,snapshot});if(shell.exists)renderShellCompletion(shell.bytes);
+  const shell=inspectPath(safeFs,path.join(userHome,'.zshrc'),{kind:'file',read:true,snapshot});if(shell.exists)removeShellCompletion(shell.bytes);
   targets.push({target,language,modelConfig,limits,snapshot});
  }
  const hash=createHash('sha256');for(const entry of targets){hash.update(entry.target.platform+'\0'+entry.target.home+'\0');for(const [name,value]of [...entry.snapshot].sort(([a],[b])=>a.localeCompare(b)))hash.update(JSON.stringify([name,value],(key,value)=>key==='atimeNs'?undefined:typeof value==='bigint'?value.toString():value));}

package/lib/installer/upgrade.mjs

@@ -5,7 +5,7 @@ import {buildInstallPlan,validatePlanSet} from './plan.mjs';
 import {assertPlanSnapshot} from './transaction.mjs';
 import {inspectPath} from './targets.mjs';
 import {renderManagedBlock,removeManagedBlock,agentsBlockBody} from './global-config.mjs';
-import {renderShellCompletion} from './shell-completion.mjs';
+import {attachShellCompletionCleanup} from './shell-completion.mjs';
 import {verifyPayload} from './manifest.mjs';
 import {installTargets} from './install.mjs';
 import {acquireExternalSkills} from './acquisition.mjs';
@@ -19,10 +19,7 @@ export function buildUpgradePlans({payload,state,safeFs}){
   if(current.exists&&removeManagedBlock(current.bytes).changed){const rendered=renderManagedBlock(current.bytes,agentsBlockBody(target.home,target.userHome,language,target.platform));plan.managedPaths.push(target.instructionPath);if(!rendered.content.equals(current.bytes))plan.globalChanges.push({path:target.instructionPath,original:current.bytes,...rendered});}
   return plan;
  });
- const first=plans[0];if(first){const filename=path.join(first.target.userHome,'.zshrc'),current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot:first.snapshot});
-  if(current.exists){const content=renderShellCompletion(current.bytes);if(current.bytes.includes(Buffer.from('# >>> arc completion >>>'))){first.managedPaths.push(filename);if(!content.equals(current.bytes))first.globalChanges.push({path:filename,original:current.bytes,content,action:'update completion'});}}
-  for(const plan of plans.slice(1))plan.snapshot.delete(filename);
- }
+ attachShellCompletionCleanup(plans,{safeFs});
  validatePlanSet(plans);return plans;
 }
 export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal,acquisition}){

package/lib/management/operations.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {resolveTarget} from '../installer/targets.mjs';
+import {buildInstallPlan,validatePlanSet} from '../installer/plan.mjs';
+import {verifyPayload} from '../installer/manifest.mjs';
+import {buildPresetPlan,switchPresetTargets} from '../installer/preset.mjs';
+import {buildUninstallPlan,uninstallTargets} from '../installer/uninstall.mjs';
+import {installTargets} from '../installer/install.mjs';
+import {attachShellCompletionCleanup} from '../installer/shell-completion.mjs';
+import {acquireExternalSkills} from '../installer/acquisition.mjs';
+/** @typedef {{packageRoot:string,userHome:string,cwd:string,env:object,safeFs:object,signal?:AbortSignal,acquisition?:Function}} ManagementContext */
+/** @typedef {{kind:string,plans:object[],options:object}} PreparedOperation */
+/** @typedef {{code:number,exitSession:boolean,results:object[],interrupted:boolean}} OperationResult */
+export async function createManagementContext(options={}){
+ let safeFs=options.safeFs;if(!safeFs){const[{loadNative},{openRoot}]=await Promise.all([import('../safe-fs/native.mjs'),import('../safe-fs/index.mjs')]);const native=loadNative();safeFs={openRoot:p=>openRoot(p,{native})};}
+ return{packageRoot:fileURLToPath(new URL('../../',import.meta.url)),userHome:os.homedir(),cwd:process.cwd(),env:process.env,...options,safeFs};
+}
+export async function prepareOperation(context,options,{selections=[]}={}){
+ if(options.kind==='update'){const{prepareUpdate}=await import('./update.mjs');return prepareUpdate(context);}
+ if(!['install','preset','uninstall'].includes(options.kind))throw Object.assign(Error('Unknown management operation'),{code:'ARC_CLI_INPUT'});
+ const platforms=options.target==='all'?['codex','claude']:[options.target],payload=options.kind==='install'?verifyPayload(context):null;
+ const plans=platforms.map(platform=>{const target=resolveTarget(platform,context),selection=selections.find(item=>item.target.platform===platform&&item.target.home===target.home);if(options.kind==='preset')return buildPresetPlan({target,preset:options.preset,safeFs:context.safeFs});if(options.kind==='uninstall')return buildUninstallPlan({target,safeFs:context.safeFs,skipGlobal:options.skipGlobal});return buildInstallPlan({payload,target,limitsPreview:selection?.preview,languagePreview:selection?.languagePreview,preset:options.preset,language:options.language,skipGlobal:options.skipGlobal,safeFs:context.safeFs,limits:{...(options.maxTotalSubagents===undefined?{}:{max_total_subagents:options.maxTotalSubagents}),...(options.maxConcurrentSubagents===undefined?{}:{max_concurrent_subagents:options.maxConcurrentSubagents})},concurrentExplicit:options.maxConcurrentSubagents!==undefined||Boolean(options.concurrentSelected)});});
+ if(options.kind==='install')attachShellCompletionCleanup(plans,context);
+ // Uninstall plans initially share the completion snapshot; its executor assigns one owner.
+ if(options.kind!=='uninstall')validatePlanSet(plans);
+ return{kind:options.kind,plans,options:{...options}};
+}
+export function operationResult(result,successStatuses=['installed']){return{...result,code:result.interrupted?130:result.results.every(item=>successStatuses.includes(item.status)&&!item.error)?0:1,exitSession:false};}
+export function acquisitionFor(context){return context.acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;try{acquired=await acquireExternalSkills({work,safeFs:context.safeFs,signal:context.signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});}
+export async function executeOperation(context,prepared){
+ if(prepared.kind==='update'){const{executeUpdate}=await import('./update.mjs');return executeUpdate(context,prepared);}
+ const options={safeFs:context.safeFs,signal:context.signal,hooks:context.hooks};
+ if(prepared.kind==='install')return operationResult(await installTargets(prepared.plans,{...options,acquisition:acquisitionFor(context)}));
+ if(prepared.kind==='preset')return operationResult(await switchPresetTargets(prepared.plans,options),['updated','unchanged']);
+ if(prepared.kind==='uninstall')return operationResult(await uninstallTargets(prepared.plans,options),['uninstalled']);
+ throw Object.assign(Error('Unknown prepared operation'),{code:'ARC_CLI_INPUT'});
+}

package/lib/management/status.mjs

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import {resolveTarget,inspectPath} from '../installer/targets.mjs';
+import {parseLanguage} from '../installer/language.mjs';
+import {parseLimits} from '../installer/limits.mjs';
+import {loadModelConfig} from '../models/index.mjs';
+import {removeManagedBlock} from '../installer/global-config.mjs';
+import {readRuntimeConcurrency} from '../installer/runtime-config.mjs';
+import {removeShellCompletion} from '../installer/shell-completion.mjs';
+/** @typedef {{platform:string,target?:object,state:'absent'|'installed'|'incomplete',settings?:object,diagnostics:Error[]}} TargetStatus */
+export async function collectStatus(context){return ['codex','claude'].map(platform=>{
+ let target;try{target=resolveTarget(platform,context);const snapshot=new Map(),read=(name,kind='file')=>inspectPath(context.safeFs,name,{kind,read:true,snapshot,tree:kind==='directory',allowLinks:kind==='directory'}),arc=path.join(target.home,'skills/arc'),skill=read(arc,'directory'),profiles=target.profileNames.map(name=>read(path.join(target.home,'agents',name))),instruction=read(target.instructionPath),managed=instruction.exists&&removeManagedBlock(instruction.bytes).changed;
+ if(!skill.exists&&!profiles.some(x=>x.exists)&&!managed)return{platform,target,state:'absent',diagnostics:[]};
+ const mandatory=name=>{const found=read(path.join(arc,name));if(!found.exists||!found.bytes.length)throw Error(`Incomplete ARC installation: missing ${name} at ${target.home}`);return found.bytes;};
+ mandatory('SKILL.md');if(profiles.some(x=>!x.exists||!x.bytes.length))throw Error(`Incomplete ARC installation: missing profile at ${target.home}`);
+ const settings={language:parseLanguage(mandatory('settings.toml')).language,modelConfig:loadModelConfig(mandatory('models.toml'),platform),limits:parseLimits(mandatory('limits.toml'))};const native=read(target.runtimeConfigPath);if(native.exists)readRuntimeConcurrency(platform,native.bytes);const shell=read(path.join(context.userHome,'.zshrc'));if(shell.exists)removeShellCompletion(shell.bytes);
+ return{platform,target,state:'installed',settings,snapshot,diagnostics:[]};
+ }catch(error){return{platform,target,state:'incomplete',diagnostics:[error]};}
+ });}

package/lib/management/update.mjs

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+const packageRoot=path.resolve(fileURLToPath(new URL('../../',import.meta.url)));
+const inputError=message=>Object.assign(Error(message),{code:'ARC_CLI_INPUT'});
+const configurationError=message=>Object.assign(Error(message),{code:'ARC_TARGET_CONFIGURATION'});
+function identity(root){const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));if(pkg.name!=='@yunhozz/arc'||!/^\d+\.\d+\.\d+$/.test(pkg.version))throw configurationError('Invalid ARC package identity');return pkg;}
+export async function runtime(deps){
+ const [context,state,upgrade,npm]=await Promise.all([import('../npm/context.mjs'),import('../installer/upgrade-state.mjs'),import('../installer/upgrade.mjs'),import('../npm/upgrade.mjs')]);
+ let safeFs=deps.safeFs;if(!safeFs){const[{loadNative},{openRoot}]=await Promise.all([import('../safe-fs/native.mjs'),import('../safe-fs/index.mjs')]);const native=loadNative();safeFs={openRoot:root=>openRoot(root,{native})};}
+ return{...context,...state,...upgrade,...npm,...deps,safeFs};
+}
+export function report(result,output,error){
+ for(const item of result.results){output.write(item.platform+': '+item.status+'; rollback: '+item.rollback+'\n');for(const filename of item.residualPaths??[])output.write('Residual path: '+filename+'\n');if(item.error)error.write('Error: '+item.error.message+'\n');}
+ if(result.interrupted)return 130;
+ if(result.results.every(item=>item.status==='installed'&&!item.error)){output.write('ARC version '+result.version+' harness upgraded! Previous harness version: not recorded.\n');return 0;}
+ error.write('Harness update did not complete. Run arc again and choose Update Harness, or run npx --yes @yunhozz/arc@latest and choose Update Harness.\n');return 1;
+}
+export function failure(cause,error){error.write('Error: '+cause.message+'\n');return ['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(cause.code)?130:['ARC_CLI_INPUT','ARC_TARGET_CONFIGURATION','ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE'].includes(cause.code)?2:1;}
+export async function runChild(request,io={},deps={}){
+ const output=io.output??process.stdout,error=io.error??process.stderr;let onInterrupt;
+ try{
+  if(!request||Object.keys(request).sort().join(',')!=='expectedStateToken,expectedVersion,invocationCwd,protocol'||request.protocol!==1||typeof request.expectedVersion!=='string'||!/^\d+\.\d+\.\d+$/.test(request.expectedVersion)||typeof request.expectedStateToken!=='string'||!/^[a-f0-9]{64}$/.test(request.expectedStateToken)||typeof request.invocationCwd!=='string'||!path.isAbsolute(request.invocationCwd)||fs.realpathSync(request.invocationCwd)!==request.invocationCwd)throw inputError('Invalid private upgrade request');
+  const root=deps.packageRoot??packageRoot,pkg=identity(root);if(pkg.version!==request.expectedVersion)throw configurationError('The new ARC package version does not match the requested upgrade');
+  const api=await runtime(deps),env=io.env??process.env,cwd=request.invocationCwd,context=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc-upgrade.mjs'),env,cwd});
+  if(context.kind!=='global'||context.packageRoot!==root)throw configurationError('Cannot verify the replaced global ARC package');
+  const state=api.collectInstalledState({safeFs:api.safeFs,userHome:deps.userHome??os.homedir(),env,cwd});if(state.stateToken!==request.expectedStateToken)throw configurationError('Installed ARC settings changed during CLI replacement; retry upgrade');
+  if(!state.targets.length)throw configurationError('No installed ARC harness found');
+  const controller=new AbortController();onInterrupt=()=>controller.abort();process.once('SIGINT',onInterrupt);process.once('SIGTERM',onInterrupt);
+  return report(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:controller.signal}),output,error);
+ }catch(cause){return failure(cause,error);}finally{if(onInterrupt){process.removeListener('SIGINT',onInterrupt);process.removeListener('SIGTERM',onInterrupt);}}
+}
+
+export async function prepareUpdate(context){
+ const root=context.packageRoot??packageRoot,pkg=identity(root),api=await runtime(context),cwd=fs.realpathSync(context.cwd??process.cwd()),env=context.env??process.env;
+ const state=api.collectInstalledState({safeFs:api.safeFs,userHome:context.userHome??os.homedir(),env,cwd});
+ if(!state.targets.length)throw configurationError('No installed ARC harness found. Run npx --yes @yunhozz/arc to install it first');
+ let plans,version;
+ if(!context.upgradeInstalledTargets){const[{verifyPayload},{buildUpgradePlans}]=await Promise.all([import('../installer/manifest.mjs'),import('../installer/upgrade.mjs')]);const payload=verifyPayload({packageRoot:root,safeFs:api.safeFs});plans=buildUpgradePlans({payload,state,safeFs:api.safeFs});version=JSON.parse(payload.files.get('package.json')).version;}
+ return{kind:'update',root,pkg,cwd,env,state,plans,version};
+}
+export async function executeUpdate(context,prepared){
+ let packageStarted=false;const messages=[];try{
+  const api=await runtime(context),{root,pkg,cwd,env,state}=prepared;
+  const{assertPlanSnapshot}=await import('../installer/transaction.mjs');for(const entry of state.targets)assertPlanSnapshot(entry,{safeFs:api.safeFs});
+  const npmContext=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc.mjs'),env,cwd});
+  if(!['global','npx'].includes(npmContext.kind))throw configurationError('Run arc from a verified global ARC installation or npx --yes @yunhozz/arc@latest, then choose Update Harness');
+  if(npmContext.kind==='npx'){
+   let result;if(prepared.plans){const[{installTargets},{acquisitionFor,operationResult}]=await Promise.all([import('../installer/install.mjs'),import('./operations.mjs')]);result=operationResult({version:prepared.version,...await installTargets(prepared.plans,{safeFs:api.safeFs,signal:context.signal,acquisition:acquisitionFor({...context,safeFs:api.safeFs})})});}else{const{operationResult}=await import('./operations.mjs');result=operationResult(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:context.signal}));}return result;
+  }
+  const latest=await api.resolveLatest({context:npmContext,env,cwd,signal:context.signal});packageStarted=true;
+  const replaced=await api.upgradeGlobal({context:npmContext,expectedVersion:latest.version,env,cwd,signal:context.signal});if(replaced.packageStatus!=='updated')throw replaced.error??Error('CLI replacement failed');
+  messages.push('CLI: updated to '+latest.version+' (previous '+pkg.version+').\n');
+  const child=await api.runUpgradeChild({entryPath:path.join(npmContext.packageRoot,'bin/arc-upgrade.mjs'),request:{protocol:1,expectedVersion:latest.version,invocationCwd:cwd,expectedStateToken:state.stateToken},env,cwd,signal:context.signal});
+  return{...child,code:child.code===0&&!child.signal?0:child.code===130?130:1,exitSession:true,results:[],messages};
+ }catch(error){return{code:['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(error.code)?130:['ARC_CLI_INPUT','ARC_TARGET_CONFIGURATION','ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE'].includes(error.code)?2:1,exitSession:packageStarted,results:[],error,messages};}
+}

package/lib/management/workflow.mjs

@@ -0,0 +1,51 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {absolute,inspectPath,observeCooperativeTarget,workflowStatePath,validateWorkflowId} from '../runtime/scope.mjs';
+import {validateCooperativeCommand} from '../runtime/cooperative-schema.mjs';
+import {runWorkflowCommand} from '../runtime/command.mjs';
+const invalid=message=>Object.assign(Error(message),{code:'ARC_CLI_INPUT'});
+export async function observeWorkspace(cwd){
+ await inspectPath(cwd,{directory:true});
+ const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>!key.toUpperCase().startsWith('GIT_')));
+ Object.assign(env,{GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:process.platform==='win32'?'NUL':'/dev/null',GIT_OPTIONAL_LOCKS:'0',GIT_NO_LAZY_FETCH:'1',GIT_TERMINAL_PROMPT:'0'});
+ const result=spawnSync('git',['--no-pager','-c','core.fsmonitor=false','rev-parse','--show-toplevel'],{cwd,env,encoding:'utf8',timeout:10000,maxBuffer:1024*1024});
+ if(result.status!==0||result.error||!result.stdout.endsWith('\n')||result.stdout.slice(0,-1).includes('\n'))throw invalid('Cannot observe repository root.');
+ return observeCooperativeTarget(result.stdout.slice(0,-1));
+}
+export async function readWorkflowJson(filename){
+ if(!absolute(filename))throw invalid('An absolute JSON file path is required.');
+ await inspectPath(filename);let input;try{input=JSON.parse(await fs.readFile(filename,'utf8'));}catch{throw invalid('Cannot parse workflow JSON file.');}
+ return input;
+}
+export async function listWorkflows(cwd){
+ const target=await observeWorkspace(cwd),directory=path.join(target.gitCommonDir,'arc','workflows');
+ try{await inspectPath(directory,{directory:true});}catch(error){if(error.code==='ENOENT')return[];throw error;}
+ const entries=await fs.readdir(directory,{withFileTypes:true}),items=[];
+ for(const entry of entries){if(!entry.isDirectory())continue;try{validateWorkflowId(entry.name);}catch{continue;}
+  const filename=await workflowStatePath(target,entry.name);try{const state=JSON.parse(await fs.readFile(filename,'utf8'));items.push({id:entry.name,revision:state.revision,target:state.target,foreign:!sameTarget(target,state.target)});}catch(error){if(error.code==='ENOENT')continue;items.push({id:entry.name,invalid:true});}
+ }
+ return items.sort((a,b)=>a.id.localeCompare(b.id));
+}
+function sameTarget(a,b){return b&&['realpath','gitCommonDir','gitDir','branch','head'].every(key=>a[key]===b[key]);}
+export async function prepareWorkflow({cwd,workflowId,command,input,jsonPath}){
+ validateWorkflowId(workflowId);const target=await observeWorkspace(cwd);cwd=target.realpath;const filename=await workflowStatePath(target,workflowId);
+ if(jsonPath!==undefined)input=await readWorkflowJson(jsonPath);
+ if(command!=='status'){try{validateCooperativeCommand({command,input});}catch{throw invalid('Invalid workflow input. Check the command schema; payload is not displayed.');}}
+ else if(input!==undefined)throw invalid('Status takes no input.');
+ if(!['init','status','record','prepare','result','reconcile'].includes(command))throw invalid('Invalid workflow command.');
+ if(!['status','init'].includes(command)){const state=JSON.parse(await fs.readFile(filename,'utf8'));if(!sameTarget(target,state.target))throw invalid('Workflow target differs from this checkout or HEAD. Use the matching target before mutation.');}
+ return{cwd,workflowId,command,input:input===undefined?undefined:structuredClone(input),target};
+}
+// Only expose structural status fields. Evidence payloads, operator statements,
+// request arguments and runtime error text may contain secrets and stay private.
+export function workflowView(body,code){
+ const state=body.state;
+ return{code,decision:body.decision,workflowId:body.workflowId,revision:body.revision,persisted:body.persisted,ruleIds:body.ruleIds??[],requiredEvidence:(body.requiredEvidence??[]).map(value=>typeof value==='string'?value:'Additional runtime evidence required'),nextActions:(body.nextActions??[]).map(value=>typeof value==='string'?value:'Consult installed runtime instructions'),...(body.error?{error:'Workflow command rejected. Check runtime inputs and target.'}:{}),...(state?{target:state.target,tasks:(state.tasks??[]).map(t=>({id:t.id,status:t.status})),unresolved:(state.unresolved??[]).map(()=> 'Unresolved runtime condition')}: {})};
+}
+export async function executeWorkflow(prepared){
+ const current=await observeWorkspace(prepared.cwd);if(!sameTarget(current,prepared.target))return{code:3,decision:'hold',workflowId:prepared.workflowId,ruleIds:['cooperative.target'],error:'Workspace target changed. Review again.',nextActions:[]};
+ let text='';const args=[prepared.command,'--cwd',prepared.cwd,'--workflow',prepared.workflowId];if(prepared.command!=='status')args.push('--input','-');
+ const code=await runWorkflowCommand(args,{input:JSON.stringify(prepared.input),output:{write(chunk){text+=chunk;}}});
+ return workflowView(JSON.parse(text),code);
+}

package/lib/models/config.mjs

@@ -1,5 +1,5 @@
 import { parse, stringify } from '../../vendor/toml/dist/index.js';
-export const ROLES = Object.freeze(['arc_scouter', 'arc_planner', 'arc_coder', 'arc_qa', 'arc_reviewer']);
+export const ROLES = Object.freeze(['arc_scouter', 'arc_planner', 'arc_implementer', 'arc_qa', 'arc_reviewer']);
 export class ModelValidationError extends Error {
   constructor(message, options) { super(message, options); this.name = 'ModelValidationError'; this.code = 'ARC_MODEL_VALIDATION'; }
 }

package/lib/models/profiles.mjs

@@ -3,7 +3,7 @@ import { parseToml, exactKeys, validateRoles, effortField, ROLES, fail } from '.
 const tools = {
   arc_scouter: ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch'],
   arc_planner: ['Read', 'Grep', 'Glob'],
-  arc_coder: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
+  arc_implementer: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
   arc_qa: ['Read', 'Grep', 'Glob', 'Bash'],
   arc_reviewer: ['Read', 'Grep', 'Glob'],
 };

package/lib/policy/placement.mjs

@@ -2,12 +2,12 @@
 const reviews = ['review.significant-no-plan', 'review.significant-plan', 'review.final-plan-recheck'];
 export const POLICY_PROJECTIONS = Object.freeze(Object.fromEntries(Object.entries({
   core: ['scope.non-escalation', 'external.explicit-user-authority', 'role.orchestrator-boundary'],
-  assignment: ['git.specialists-deny', 'role.scouter-read-only', 'role.planner-draft-only', 'role.coder-implementation', 'role.qa-verification', 'role.reviewer-independent'],
-  planning: ['git.orchestrator-accept-commit', ...reviews],
-  handoff: ['git.specialists-deny', 'role.coder-implementation', ...reviews],
-  preparation: ['scope.non-escalation', 'git.specialists-deny', 'git.orchestrator-accept-commit', 'external.explicit-user-authority'],
-  verification: ['git.orchestrator-accept-commit', ...reviews],
-  commit: ['scope.non-escalation', 'git.orchestrator-accept-commit', 'external.explicit-user-authority'],
+  assignment: ['git.specialists-deny', 'role.scouter-read-only', 'role.planner-draft-only', 'role.implementer-implementation', 'role.qa-verification', 'role.reviewer-independent'],
+  planning: ['git.orchestrator-accept-commit', ...reviews, 'planning.plan-amend', 'planning.planner-brief'],
+  handoff: ['git.specialists-deny', 'role.implementer-implementation', ...reviews],
+  preparation: ['scope.non-escalation', 'git.specialists-deny', 'git.orchestrator-accept-commit', 'external.explicit-user-authority', 'planning.plan-amend'],
+  verification: ['git.orchestrator-accept-commit', ...reviews, 'planning.plan-amend'],
+  commit: ['scope.non-escalation', 'git.orchestrator-accept-commit', 'external.explicit-user-authority', 'planning.plan-amend'],
 }).map(([name, ids]) => [name, Object.freeze(ids)])));
 
 export function validatePolicyProjections(policy, projections = POLICY_PROJECTIONS) {

package/lib/policy/render.mjs

@@ -2,7 +2,7 @@ import {renderSourceClaudeHook} from './claude-hook.mjs';
 import {POLICY_PROJECTIONS, validatePolicyProjections} from './placement.mjs';
 import {validateGitPolicy} from '../../claude/skill/hooks/role-git-guard.mjs';
 import source from './role-policy.json' with {type: 'json'};
-const ROLES = ['orchestrator','scouter','planner','coder','qa','reviewer'];
+const ROLES = ['orchestrator','scouter','planner','implementer','qa','reviewer'];
 const CONTROLS = ['prompt','capability','hook'];
 const fail = message => { throw new Error(`Role policy: ${message}`); };
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -18,10 +18,10 @@ export function validateRolePolicy(input) {
     if (!strings(rule.roles) || rule.roles.some(x=>!ROLES.includes(x)) || !['allow','deny','require'].includes(rule.effect) || !strings(rule.operations) || !strings(rule.evidence) || !['user','orchestrator'].includes(rule.authority) || typeof rule.text !== 'string' || !rule.text || /[\r\n]/.test(rule.text)) fail(`invalid rule ${rule.id}`);
     if (!object(rule.controls) || !same(Object.keys(rule.controls).sort(),['claude','codex']) || Object.values(rule.controls).some(x=>!CONTROLS.includes(x))) fail(`invalid control level for ${rule.id}`);
   }
-  for (const id of ['scope.non-escalation','git.specialists-deny','git.orchestrator-accept-commit','external.explicit-user-authority',...ROLES.map(x=>({orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',coder:'role.coder-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'})[x]),'review.significant-no-plan','review.significant-plan','review.final-plan-recheck']) if(!ids.has(id)) fail(`missing required rule ${id}`);
+  for (const id of ['scope.non-escalation','git.specialists-deny','git.orchestrator-accept-commit','external.explicit-user-authority',...ROLES.map(x=>({orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',implementer:'role.implementer-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'})[x]),'review.significant-no-plan','review.significant-plan','review.final-plan-recheck']) if(!ids.has(id)) fail(`missing required rule ${id}`);
   for (const platform of ['codex','claude']) if (!object(input.platforms?.[platform]) || !CONTROLS.includes(input.platforms[platform].level) || typeof input.platforms[platform].notice !== 'string' || !input.platforms[platform].notice) fail(`invalid ${platform} controls`);
   // These are workflow invariants, not customizable scheduling options.
-  const routes = {noPlan:['coder','qa','reviewer','orchestrator-accept'],planTask:['coder','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['coder','reviewer']};
+  const routes = {noPlan:['implementer','qa','reviewer','orchestrator-accept'],planTask:['implementer','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['implementer','reviewer']};
   if (!object(input.review) || Object.keys(input.review).length !== 4 || Object.entries(routes).some(([key,value])=>!same(input.review[key],value))) fail('invalid review routing');
   try {validateGitPolicy(input.git);} catch {fail('invalid Git policy');}
   if (!object(input.runtime) || input.runtime.schemaVersion !== 1 || !same(input.runtime.roles,ROLES) || !strings(input.runtime.requiredEvidence) || !strings(input.runtime.ruleIds) || ['platform-identity','user-approval','current-target-versions','resolved-paths'].some(x=>!input.runtime.requiredEvidence.includes(x)) || ['runtime.schema','runtime.policy','runtime.identity','runtime.target','runtime.assignment','runtime.approval','runtime.paths','runtime.docs-commit','runtime.mode','runtime.transition'].some(x=>!input.runtime.ruleIds.includes(x)) || input.runtime.status !== 'decision-only') fail('invalid runtime policy');

package/lib/policy/role-policy.json

@@ -14,7 +14,7 @@
       "description": "Return design, spec and plan drafts to Orchestrator."
     },
     {
-      "id": "coder",
+      "id": "implementer",
       "description": "Implement assigned approved changes and focused checks."
     },
     {
@@ -33,7 +33,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -58,7 +58,7 @@
       "roles": [
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -114,7 +114,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -150,7 +150,7 @@
         "role-ownership"
       ],
       "authority": "orchestrator",
-      "text": "Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it. Use a fresh Coder per top-level task and a fresh QA per top-level task that needs QA; QA findings alone do not create a new task. While approved scope, workspace, ownership and relevant assignment context remain valid, default same-task QA findings to the current Coder and post-fix rechecks to the current QA. Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes; an approved plan or acceptance-criteria amendment requires a fresh Coder even within the task. Before reusing Coder, refresh actual workspace, branch/HEAD and change state; QA reruns the reproduction path and invalidated related checks and reports actual actor, target state, outcomes and limitations. Preserve task-boundary acceptance and the final plan Reviewer correction exception.",
+      "text": "Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Implementer. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it. Use a fresh Implementer per top-level task and a fresh QA per top-level task that needs QA; QA findings alone do not create a new task. While approved scope, workspace, ownership and relevant assignment context remain valid, default same-task QA findings to the current Implementer and post-fix rechecks to the current QA. Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes; an approved plan or acceptance-criteria amendment requires a fresh Implementer even within the task. Before reusing Implementer, refresh actual workspace, branch/HEAD and change state; QA reruns the reproduction path and invalidated related checks and reports actual actor, target state, outcomes and limitations. Preserve task-boundary acceptance and the final plan Reviewer correction exception.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -197,9 +197,9 @@
       }
     },
     {
-      "id": "role.coder-implementation",
+      "id": "role.implementer-implementation",
       "roles": [
-        "coder"
+        "implementer"
       ],
       "effect": "allow",
       "operations": [
@@ -233,7 +233,7 @@
         "criterion-evidence"
       ],
       "authority": "orchestrator",
-      "text": "Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.",
+      "text": "Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -265,7 +265,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -278,7 +278,7 @@
         "qa-rechecks"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk work without a plan: Coder \u2192 QA and required QA rechecks \u2192 Reviewer of the final full change \u2192 Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.",
+      "text": "For significant/high-risk work without a plan: Implementer \u2192 QA and required QA rechecks \u2192 Reviewer of the final full change \u2192 Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -290,7 +290,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -303,7 +303,7 @@
         "required-qa"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk plan work: each task uses Coder \u2192 fresh QA as required \u2192 Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
+      "text": "For significant/high-risk plan work: each task uses Implementer \u2192 fresh QA as required \u2192 Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -315,7 +315,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -327,7 +327,52 @@
         "reviewer-findings"
       ],
       "authority": "orchestrator",
-      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Coder \u2192 Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Implementer \u2192 Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "planning.plan-amend",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "require",
+      "operations": [
+        "plan-update",
+        "plan-commit-amend"
+      ],
+      "evidence": [
+        "change-classification",
+        "actual-approval-chronology",
+        "rewrite-safety",
+        "sha-mapping"
+      ],
+      "authority": "orchestrator",
+      "text": "During approved task execution, mechanical plan progress records need no new user approval; changed goals, scope, criteria, method, risk, dependencies or required verification require revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, without a separate document or fixup commit. Preserve actual approval chronology, recoverable old/new contents, hashes, versions and SHA mappings; never retroactively authorize earlier work. Rewrite only unpublished, unshared local linear history with clear ownership and no merges; stop on unknown publication, ownership, unexpected state or replay conflicts, without force push or a fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. See planning, handoff-prep, commit and verification for the full contract.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "planning.planner-brief",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "require",
+      "operations": [
+        "planner-brief",
+        "planner-feedback"
+      ],
+      "evidence": [
+        "complete-stage-brief",
+        "prepared-target",
+        "preceding-approval"
+      ],
+      "authority": "orchestrator",
+      "text": "Before formal drafting, Orchestrator supplies one complete stage-specific brief with original requirements and criteria IDs, approved/open decisions, verified target and ownership, document paths and preceding approved versions, current behavior and connected source/generated/runtime/installer/documentation surfaces, policy conflicts, depth, dependencies, checks, holds and exact deliverable. Preserve shared brief field order. Review the complete draft once and consolidate substantive feedback as changed fields with other fields marked unchanged. Preserve sequential design, spec and plan approvals; no fixed call cap or incomplete drafts, and no calls for already resolved questions.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -337,7 +382,7 @@
   "platforms": {
     "codex": {
       "level": "prompt",
-      "notice": "Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Coder and QA need shell for approved checks."
+      "notice": "Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks."
     },
     "claude": {
       "level": "capability",
@@ -346,13 +391,13 @@
   },
   "review": {
     "noPlan": [
-      "coder",
+      "implementer",
       "qa",
       "reviewer",
       "orchestrator-accept"
     ],
     "planTask": [
-      "coder",
+      "implementer",
       "fresh-qa",
       "orchestrator-accept",
       "orchestrator-commit"
@@ -362,7 +407,7 @@
       "reviewer"
     ],
     "planFinding": [
-      "coder",
+      "implementer",
       "reviewer"
     ]
   },
@@ -580,7 +625,7 @@
       "orchestrator",
       "scouter",
       "planner",
-      "coder",
+      "implementer",
       "qa",
       "reviewer"
     ],

package/lib/release/artifact.mjs

@@ -99,7 +99,7 @@ function validateTarball(bytes,{expectedName,expectedVersion}){
  const files=archive(bytes),pkgFile=files.get('package.json');if(!pkgFile)throw new Error('Artifact package metadata is missing');
  const pkg=JSON.parse(pkgFile.bytes);metadata(pkg,undefined,{artifact:true});
  if(pkg.name!==expectedName||pkg.version!==expectedVersion)throw new Error('Artifact package identity mismatch');
- for(const name of ['scripts/postinstall.mjs','lib/cli/postinstall.mjs','lib/cli/terminal.mjs'])if(!files.has(name))throw new Error('Artifact runtime asset missing: '+name);
+ for(const name of ['scripts/postinstall.mjs','lib/cli/postinstall.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/cli/root.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs'])if(!files.has(name))throw new Error('Artifact runtime asset missing: '+name);
  if(files.has('package-lock.json')||[...files.keys()].some(name=>name.split('/').some(part=>part==='.git'||part.startsWith('.arc-release'))))throw new Error('Private staging data in artifact');
  const root=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-release-verify-'));
  try{

package/lib/runtime/acceptance.mjs

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import {fingerprintRequest} from './store.mjs';
+import {validateGitPreflight,validateGitCommitResult} from './git-evidence.mjs';
+import {within} from './scope.mjs';
+const reconciliations=new WeakMap();
+export function verifiedCooperativeReconciliation(decision,state){const proof=reconciliations.get(decision);return !!proof&&proof.before===fingerprintRequest(state)&&proof.after===fingerprintRequest(decision.proposedTransition);}
+const completed=(state,id)=>state.tasks?.some(t=>t.id===id&&t.status==='committed'&&!t.invalidated)&&state.commits?.some(c=>c.taskId===id&&c.observationSource==='local-git'&&state.intents.some(i=>i.operation==='commit'&&i.requestId===c.requestId&&i.taskId===id&&i.status==='succeeded'));
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const text=v=>typeof v==='string'&&v.length>0;
+const list=v=>Array.isArray(v)&&v.every(text)&&new Set(v).size===v.length;
+const exact=(a,b)=>list(a)&&list(b)&&same([...a].sort(),[...b].sort());
+const fields=(v,keys)=>v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).every(k=>keys.includes(k));
+const semanticLimit='Semantically unrelated hunks inside the same file require Orchestrator inspection; path and byte evidence cannot distinguish them automatically.';
+const base=state=>({expectedRevision:state?.revision??0,coverage:{enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false},semanticLimit,requiredEvidence:[],nextActions:[],proposedTransition:null});
+const hold=(state,reason)=>({...base(state),decision:'hold',ruleIds:['cooperative.acceptance'],reason});
+const allow=(state,transition)=>({...base(state),decision:'allow',ruleIds:['cooperative.acceptance'],proposedTransition:transition});
+const approval=(state,id)=>state.records.filter(r=>r.kind==='approval'&&(!r.data.affectedTaskIds||r.data.affectedTaskIds.includes(id))).at(-1);
+function authorized(state,task){const a=approval(state,task?.id);return state.mode==='plan'&&task&&!task.invalidated&&a?.source==='operator-attested'&&a.targetVersion===state.targetVersion&&task.targetVersion===state.targetVersion&&task.scopeVersion===a.scopeVersion&&task.approvalRef===a.messageRef&&task.approvalVersion===a.data.approvalVersion&&task.documentVersion===a.data.documentVersion;}
+function checkEvidence(state,task,a,changes){
+ if(!same(a.criteria,task.criteria)||!task.criteria.length||!list(a.checkIds)||!list(a.findingIds)||a.changeFingerprint!==changes?.tasks?.[task.id])return false;
+ const checks=state.checks.filter(c=>c.scope==='task'&&c.taskId===task.id);
+ const latest=task.requiredChecks.map(d=>checks.filter(c=>same(c.descriptor,d)).at(-1));
+ if(!task.requiredChecks.length||latest.some(c=>!c||c.stale||c.status!=='passed'||c.verdict!=='proven'||!text(c.resultRef)||c.source!=='operator-attested'||c.verificationActor?.role!=='qa'||!text(c.verificationActor.id)||state.assignments.some(a=>a.agentId===c.verificationActor.id)||c.changeFingerprint!==a.changeFingerprint)||!exact(a.checkIds,latest.map(c=>c?.id)))return false;
+ const findings=state.findings.filter(f=>f.scope==='task'&&f.taskId===task.id);
+ return exact(a.findingIds,findings.map(f=>f.id))&&findings.every(f=>f.status==='closed'&&text(f.resolutionRef)&&text(f.recheckRef)&&f.resolutionActor?.role==='implementer'&&f.recheckActor?.role==='qa'&&f.changeFingerprint===a.changeFingerprint);
+}
+function waitingFor(state,task,predecessor){
+ if(task.status!=='pending'||state.intents.some(i=>i.taskId===task.id&&i.operation==='assign-agent'&&['prepared','unknown','mismatch','succeeded'].includes(i.status)))return false;
+ const seen=new Set(),queue=[...(task.dependencies??[])];while(queue.length){const id=queue.pop();if(id===predecessor)return true;if(seen.has(id))continue;seen.add(id);queue.push(...(state.tasks.find(t=>t.id===id)?.dependencies??[]));}return false;
+}
+function dirtyOtherTask(state,task,git){return git.stagedPaths?.some(name=>state.tasks.some(t=>t.id!==task.id&&!completed(state,t.id)&&!waitingFor(state,t,task.id)&&t.paths.some(p=>within(p,path.join(state.target.realpath,...name.split('/'))))));}
+function freshAcceptance(state,task,acceptance,changes){return acceptance&&!acceptance.stale&&authorized(state,task)&&acceptance.taskFingerprint===fingerprintRequest({...task,status:'pending'})&&same(acceptance.approval,approval(state,task.id))&&same(acceptance.target,state.target)&&same(acceptance.versions,state.versions)&&checkEvidence(state,task,acceptance,changes);}
+/** Operator attests semantic sufficiency; code binds exact current evidence only. */
+export function evaluateCooperativeAcceptance({state,request,evidence}={}){
+ const task=state?.tasks?.find(t=>t.id===request?.taskId),a=request?.arguments,g=evidence?.git;
+ if(request?.expectedRevision!==state?.revision||request.actor?.role!=='orchestrator'||!authorized(state,task)||task.status!=='pending'||state.acceptances.some(v=>v.taskId===task.id&&!v.stale)||state.commits.some(v=>v.taskId===task.id))return hold(state,'Current pending approved task and Orchestrator acceptance required');
+ if(!fields(a,['messageRef','criteria','checkIds','findingIds','changeFingerprint'])||!text(a.messageRef)||!checkEvidence(state,task,a,evidence?.changes)||state.checks.some(c=>a.checkIds?.includes(c.id)&&c.verificationActor?.id===request.actor.id))return hold(state,'Exact criteria, current required QA checks and closed findings required');
+ const descriptor={kind:'task',parent:state.target.head,indexTree:g?.indexTree,fingerprint:g?.stagedFingerprint,paths:g?.stagedPaths};
+ const invalid=validateGitPreflight({target:state.target,descriptor,scope:task.paths,gitEvidence:g});
+ if(invalid||dirtyOtherTask(state,task,g))return hold(state,invalid??'Index includes another task changes');
+ return allow(state,{acceptance:{...structuredClone(a),id:request.requestId,taskId:task.id,actor:structuredClone(request.actor),source:'operator-attested',descriptor:structuredClone(descriptor),taskFingerprint:fingerprintRequest({...task,status:'pending'}),approval:structuredClone(approval(state,task.id)),target:structuredClone(state.target),versions:structuredClone(state.versions)}});
+}
+/** Prepares a durable intent; never stages or executes a commit. */
+export function prepareCooperativeCommit({state,request,gitEvidence,evidence}={}){
+ const task=state?.tasks?.find(t=>t.id===request?.taskId),a=state?.acceptances?.find(a=>a.id===request?.arguments?.acceptanceId&&a.taskId===request.taskId);
+ if(request?.expectedRevision!==state?.revision||request.actor?.role!=='orchestrator'||!fields(request.arguments,['acceptanceId'])||task?.status!=='accepted'||!freshAcceptance(state,task,a,evidence?.changes)||state.commits.some(c=>c.taskId===task.id)||state.intents.some(i=>i.operation==='commit'&&i.taskId===task.id&&['prepared','unknown','mismatch'].includes(i.status)))return hold(state,'Exact current acceptance and no prior task commit or unresolved commit required');
+ const invalid=validateGitPreflight({target:state.target,descriptor:a.descriptor,scope:task.paths,gitEvidence});
+ if(invalid||dirtyOtherTask(state,task,gitEvidence))return hold(state,invalid??'Index includes another task changes');
+ const expected={parent:a.descriptor.parent,tree:a.descriptor.indexTree,paths:[...a.descriptor.paths],fingerprint:a.descriptor.fingerprint,remainingPaths:[...new Set([...gitEvidence.workingPaths,...gitEvidence.untrackedPaths])].sort()};
+ return allow(state,{intent:{requestId:request.requestId,operation:'commit',taskId:task.id,status:'prepared',acceptanceId:a.id,acceptanceFingerprint:fingerprintRequest(a),expected,target:structuredClone(state.target),versions:structuredClone(state.versions),fingerprint:fingerprintRequest(request),source:'operator-attested'}});
+}
+/** Results are local Git observations, correlated with an operator statement.
+ * Mismatch observations remain historical evidence and never rebind the target. */
+export function reconcileCooperativeCommit({state,intent,result,gitEvidence}={}){
+ if(!intent||intent.operation!=='commit'||!['prepared','unknown','mismatch'].includes(intent.status)||state.commits.some(c=>c.taskId===intent.taskId))return hold(state,'Matching unresolved commit intent required; replay cannot authorize another effect');
+ const task=state.tasks.find(t=>t.id===intent.taskId),a=state.acceptances.find(a=>a.id===intent.acceptanceId),g=gitEvidence;
+ const observation=g?structuredClone(g):null;
+ const transition={observation,result:{...structuredClone(result),status:'mismatch',source:'operator-attested'}};
+ const reject=reason=>({...hold(state,reason),proposedTransition:transition});
+ if(!result||!text(result.messageRef)||!fields(result.data,['commit'])||!['succeeded','failed','unknown','mismatch'].includes(result.status))return reject('Exact commit result statement required');
+ if(result.status!=='succeeded'){transition.result.status=result.status;return reject('Execution did not establish a successful commit');}
+ if(task?.status!=='accepted'||!authorized(state,task)||a?.stale||!a||intent.acceptanceFingerprint!==fingerprintRequest(a)||a.taskFingerprint!==fingerprintRequest({...task,status:'pending'})||!same(a.approval,approval(state,task.id))||!checkEvidence(state,task,a,{tasks:{[task.id]:a.changeFingerprint}})||!same(intent.target,state.target)||!same(intent.versions,state.versions)||!g?.commit||result.data.commit!==g.commit.commit||g.stagedPaths?.length||g.indexTree!==g.commit.tree)return reject('Acceptance, observed commit or clean resulting index mismatch');
+ const actual={...g.commit,target:g.target,remainingPaths:[...new Set([...g.workingPaths??[],...g.untrackedPaths??[]])].sort()};
+ const invalid=validateGitCommitResult({target:state.target,expected:intent.expected,result:actual,scope:task.paths});
+ if(invalid)return reject(invalid);
+ transition.result.status='succeeded';transition.commit={...actual,taskId:task.id,requestId:intent.requestId,acceptanceId:a.id,source:'operator-attested',observationSource:'local-git',fingerprint:a.changeFingerprint};transition.target=structuredClone(g.target);
+ const decision=allow(state,transition);reconciliations.set(decision,{before:fingerprintRequest(state),after:fingerprintRequest(transition)});return decision;
+}