@yunhozz/arc 0.1.10 → 0.2.0

package/lib/installer/shell-completion.mjs

@@ -1,29 +1,24 @@
 import path from 'node:path';
-import {applyTransaction} from './transaction.mjs';
 import {inspectPath,TargetConfigurationError} from './targets.mjs';
 const start='# >>> arc completion >>>',end='# <<< arc completion <<<';
-const body='if command -v arc >/dev/null 2>&1; then\n  eval "$(arc completion zsh)"\nfi';
-export function renderShellCompletion(original){
+export function removeShellCompletion(original){
  let text;try{text=original===null?'':new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(original);}catch{throw new TargetConfigurationError('.zshrc must be valid UTF-8');}
  const starts=[...text.matchAll(/# >>> arc completion >>>/g)],ends=[...text.matchAll(/# <<< arc completion <<</g)];
- if(starts.length!==ends.length||starts.length>1)throw new TargetConfigurationError('Malformed ARC completion markers');
- const newline=text.includes('\r\n')?'\r\n':'\n',block=start+newline+body.replaceAll('\n',newline)+newline+end;
- if(starts.length){const first=starts[0].index,last=ends[0].index;if(first>=last||(first>0&&text[first-1]!=='\n')||(last>0&&text[last-1]!=='\n')||!['','\n','\r'].includes(text[last+end.length]??''))throw new TargetConfigurationError('Malformed ARC completion markers');return Buffer.from(text.slice(0,first)+block+text.slice(last+end.length));}
- return Buffer.concat([original??Buffer.alloc(0),Buffer.from((text&&!text.endsWith('\n')?newline:'')+block+newline)]);
+ const malformed=()=>{throw new TargetConfigurationError('Malformed ARC completion markers');};
+ if(starts.length!==ends.length||starts.length>1)malformed();
+ if(!starts.length)return{changed:false,content:original};
+ const first=starts[0].index,last=ends[0].index;let stop=last+end.length;
+ if(first>=last||(first>0&&text[first-1]!=='\n')||(last>0&&text[last-1]!=='\n')||!['','\n','\r\n'].includes(text.slice(stop,stop+2).startsWith('\r')?text.slice(stop,stop+2):text.slice(stop,stop+1)))malformed();
+ if(text.slice(stop,stop+2)==='\r\n')stop+=2;else if(text[stop]==='\n')stop++;
+ return{changed:true,content:Buffer.from(text.slice(0,first)+text.slice(stop))};
 }
-export function attachShellCompletion(plans,{safeFs}){
- const plan=plans[0];if(!plan||plan.skipGlobal)return;
+export function attachShellCompletionCleanup(plans,{safeFs}){
+ const plan=plans[0];if(!plan)return;
  const filename=path.join(plan.target.userHome,'.zshrc'),current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot:plan.snapshot}),original=current.bytes??null;
+ const removed=removeShellCompletion(original);
+ for(const item of plans){item.managedPaths=item.managedPaths.filter(name=>name!==filename);item.globalChanges=item.globalChanges.filter(change=>change.path!==filename);if(item!==plan)item.snapshot.delete(filename);}
+ if(!removed.changed)return;
  const metadata=plan.snapshot.get(filename);if(metadata&&(metadata.mode&0o222n)===0n)throw new TargetConfigurationError('.zshrc is not writable');
- const content=renderShellCompletion(original);plan.managedPaths.push(filename);
- if(original===null||!content.equals(original))plan.globalChanges.push({path:filename,original,content,action:'register completion'});
- plan.summary.push(`${filename}: zsh completion; opens automatically in a new zsh session. For this session: eval "$(arc completion zsh)"`);
-}
-
-export function registerShellCompletion(userHome,{safeFs,hooks={}}){
- const plan={target:{userHome},globalChanges:[],managedPaths:[],externalPaths:[],snapshot:new Map(),summary:[]};
- attachShellCompletion([plan],{safeFs});
- if(!plan.globalChanges.length)return{status:'unchanged',residualPaths:[]};
- const result=applyTransaction(plan,{safeFs,hooks,specs:plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))});
- return{...result,status:result.cleanupError?'failed':'registered'};
+ plan.managedPaths.push(filename);plan.globalChanges.push({path:filename,original,content:removed.content,action:'remove managed completion'});
+ plan.summary.push(`${filename}: remove managed ARC completion block`);
 }

package/lib/installer/uninstall.mjs

@@ -3,6 +3,7 @@ import {inspectPath,sameIdentity,TargetConfigurationError} from './targets.mjs';
 import {SKILLS,snapshotSkill} from './superpowers.mjs';
 import {validatePlanSet} from './plan.mjs';
 import {removeManagedBlock} from './global-config.mjs';
+import {attachShellCompletionCleanup} from './shell-completion.mjs';
 export function buildUninstallPlan({target,safeFs,skipGlobal=false}){
  const snapshot=new Map(),removals=[],managedPaths=[path.join(target.home,'skills/arc'),...target.profileNames.map(name=>path.join(target.home,'agents',name))],globalChanges=[];
  for(const filename of managedPaths){const directory=filename===managedPaths[0];const found=inspectPath(safeFs,filename,{kind:directory?'directory':'file',tree:directory,allowLinks:directory,snapshot});if(found.exists)removals.push(filename);}
@@ -14,11 +15,14 @@ export function buildUninstallPlan({target,safeFs,skipGlobal=false}){
  }
  for(const skill of linkedSkills){const root=arc+'/references/superpowers/'+skill,directory=safeFs.openRoot(root);try{if(!sameIdentity(snapshot.get(root),directory.stat()))throw new TargetConfigurationError('Removal reference root changed');snapshotSkill(directory,root,[]);}finally{directory.close();}}
  if(!skipGlobal){const filename=target.instructionPath??target.globalPaths[0],found=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot});managedPaths.push(filename);if(found.exists){const removed=removeManagedBlock(found.bytes);if(removed.changed)globalChanges.push({path:filename,content:removed.content});}}
- return{target,skipGlobal,snapshot,removals,managedPaths,externalPaths:[],globalChanges,summary:[target.platform==='codex'?'Codex config.toml wait settings and native concurrency key are preserved.':'Claude settings.json native concurrency key is preserved.']};
+ const plan={target,skipGlobal,snapshot,removals,managedPaths,externalPaths:[],globalChanges,summary:[target.platform==='codex'?'Codex config.toml wait settings and native concurrency key are preserved.':'Claude settings.json native concurrency key is preserved.']};
+ attachShellCompletionCleanup([plan],{safeFs});return plan;
 }
 import {assertPlanSnapshot,applyUninstallTransaction} from './transaction.mjs';
 export async function uninstallTargets(plans,{safeFs,signal,hooks={}}){
  const results=plans.map(plan=>({platform:plan.target.platform,status:'not-started',rollback:'not-needed',residualPaths:[],error:null}));let invalid=false;
+ // Each standalone preview retains its snapshot; only the first plan owns the shared shell write.
+ for(const plan of plans.slice(1)){const filename=path.join(plans[0].target.userHome,'.zshrc');plan.managedPaths=plan.managedPaths.filter(name=>name!==filename);plan.globalChanges=plan.globalChanges.filter(change=>change.path!==filename);plan.snapshot.delete(filename);}
  try{validatePlanSet(plans);}catch(error){return{results:results.map(item=>({...item,status:'failed',error})),interrupted:false};}
  for(let i=0;i<plans.length;i++)try{assertPlanSnapshot(plans[i],{safeFs});}catch(error){results[i]={...results[i],status:'failed',error};invalid=true;}
  if(invalid)return{results,interrupted:false};

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/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/bootstrap.mjs

@@ -5,7 +5,7 @@ import {validateCooperativeCommand,validateCooperativeState} from './cooperative
 import {observeCooperativeTarget,validateObservedTarget,validateWorkflowId,workflowStatePath,inspectPath} from './scope.mjs';
 import {saveDurableState} from './store.mjs';
 export const COOPERATIVE_RUNTIME_MODULES=Object.freeze([
- 'bootstrap.mjs','cooperative-schema.mjs','cooperative.mjs','evaluate.mjs',
+ 'cli.mjs','command.mjs','bootstrap.mjs','cooperative-schema.mjs','cooperative.mjs','evaluate.mjs',
  'scope.mjs','store.mjs','git-evidence.mjs','assignment.mjs','verification.mjs','acceptance.mjs','external.mjs'
 ]);
 export const cooperativeCoverage=()=>({enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false});

package/lib/runtime/cli.mjs

@@ -0,0 +1,8 @@
+import fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {runWorkflowCommand} from './command.mjs';
+export {runWorkflowCommand};
+// Importing the installed entry is safe for callers that own their own IO.
+if(process.argv[1]&&fs.realpathSync(process.argv[1])===fileURLToPath(import.meta.url)){
+ process.exitCode=await runWorkflowCommand(process.argv.slice(2));
+}

package/lib/runtime/command.mjs

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {initializeCooperativeWorkflow,commandResult} from './bootstrap.mjs';
+import {runCooperativeCommand} from './cooperative.mjs';
+import {validateWorkflowId} from './scope.mjs';
+export async function runWorkflowCommand(args,io={}){
+ const output=io.output??process.stdout;let workflowId=null;
+ try{
+  const [command,...rest]=args,options={};
+  if(!['init','record','status','reconcile','prepare','result'].includes(command))throw Error('Expected workflow command');
+  for(let i=0;i<rest.length;i+=2){const key=rest[i];if(!['--cwd','--workflow','--input'].includes(key)||options[key]!==undefined||typeof rest[i+1]!=='string')throw Error('Invalid workflow option');options[key]=rest[i+1];}
+  const cwd=options['--cwd'];workflowId=options['--workflow'];validateWorkflowId(workflowId);
+  if(typeof cwd!=='string'||!path.isAbsolute(cwd)||path.normalize(cwd)!==cwd)throw Error('Absolute workspace required');
+  if(command==='status'?options['--input']!==undefined:options['--input']!=='-')throw Error('Mutations require --input -; status takes no input');
+  // Check/review, commit and external intents are recorded for the operator.
+  // Actual Git mutations remain Orchestrator actions; reconciliation observes their results.
+  const input=command==='status'?undefined:JSON.parse(io.input??fs.readFileSync(0,'utf8'));
+  const result=await(command==='init'?initializeCooperativeWorkflow({cwd,workflowId,input}):runCooperativeCommand({cwd,workflowId,command,input}));
+  output.write(JSON.stringify(result)+'\n');return result.decision==='deny'?2:result.decision==='hold'?3:0;
+ }catch(error){output.write(JSON.stringify(commandResult({workflowId,decision:'hold',ruleId:'cooperative.error',error:error.message}))+'\n');return 1;}
+}

package/lib/tui/app.mjs

@@ -0,0 +1,41 @@
+import {createTerminalSession} from './terminal.mjs';
+import {escapeTerminalText} from './render.mjs';
+import {createManagementContext,prepareOperation,executeOperation} from '../management/operations.mjs';
+import {collectStatus} from '../management/status.mjs';
+import {runSetup,summary} from './setup.mjs';
+import {runWorkflow,workflowRows} from './workflow.mjs';
+const home=['Install / Reconfigure','Change Preset','Workflow','Update Harness','Uninstall Harness','Exit'];
+function interrupted(){return Object.assign(Error('Session interrupted'),{code:'ARC_CANCELLED'});}
+function operationRows(prepared){
+ if(prepared.kind==='workflow')return['Command: '+prepared.command,'Workspace: '+prepared.cwd,'Workflow: '+prepared.workflowId,'Confirmation does not supply runtime approval evidence.'];
+ const rows=['Operation: '+prepared.kind];if(prepared.options)rows.push('Target: '+prepared.options.target,...(prepared.kind==='install'?['Settings: '+summary(prepared.options),'External references must be downloaded after applying.']:[]));
+ for(const plan of prepared.plans??[]){rows.push('Target: '+(plan.target?.platform??plan.platform??'harness'),'Destination: '+(plan.target?.home??plan.home??''));for(const key of ['managedPaths','writes','deletes','removals','preserved','preserve']){const values=plan[key];if(Array.isArray(values))for(const item of values)rows.push(key+': '+(typeof item==='string'?item:item.path??item.destination??item.relativePath??'managed file'));}for(const change of plan.globalChanges??[])rows.push('Global: '+change.path+' — '+(change.action??'managed ARC update'));for(const note of plan.summary??[])rows.push(note);}
+ if(prepared.kind==='uninstall')rows.push('Remove ARC harness and managed profiles.',prepared.options?.skipGlobal?'Preserve ARC global instruction blocks.':'Remove selected ARC global instruction blocks.','Preserve native concurrency, user files, other skills and workflow audit state.','CLI npm package is retained.');
+ if(prepared.kind==='update')rows.push('Installed settings are preserved.','Global CLI replacement ends this session.');
+ return rows;
+}
+export function createTuiInterface(session,{input,controller}={}){
+ async function event(){const e=await session.nextEvent();if(e.name==='interrupt')throw interrupted();if(e.name==='eof')throw Object.assign(Error('Session closed'),{code:'ARC_TUI_EOF'});if(e.name==='error')throw e.error;return e;}
+ async function menu(title,rows,{selected=0,info=[],requiresConfirmation=false}={}){
+  while(true){const offset=Math.max(0,selected-7),visible=rows.slice(offset,offset+8);const screen={title,rows:[...info,...visible],selected:info.length+selected-offset,requiresConfirmation,hint:'Up/Down: select | Enter: continue | Esc: back'+(rows.length>8?' | '+(offset+1)+'-'+Math.min(offset+8,rows.length)+'/'+rows.length:'')};const rendered=session.render(screen);const e=await event();if(e.name==='up')selected=(selected+rows.length-1)%rows.length;else if(e.name==='down')selected=(selected+1)%rows.length;else if(e.name==='back')return null;else if(e.name==='enter'&&(!requiresConfirmation||rendered.applyEnabled))return selected;}
+ }
+ async function text(title,initial=''){let value=initial;while(true){session.render({title,rows:[value],hint:'Type or paste | Left: delete | Enter: accept | Esc/Backspace: back'});const e=await event();if(e.name==='text'||e.name==='paste')value+=e.text;else if(e.name==='left')value=[...value].slice(0,-1).join('');else if(e.name==='back')return null;else if(e.name==='enter')return value;}}
+ async function page(title,rows,{requireRead=false}={}){let offset=0;while(true){const size=8,slice=rows.slice(offset,offset+size);const rendered=session.render({title,rows:slice,requiresConfirmation:requireRead,hint:`Rows ${offset+1}-${Math.min(offset+size,rows.length)} of ${rows.length} | Up/Down: scroll | Enter/Esc: back`});const e=await event();if(e.name==='down')offset=Math.min(Math.max(0,rows.length-size),offset+1);else if(e.name==='up')offset=Math.max(0,offset-1);else if(e.name==='back')return false;else if(e.name==='enter'&&(!requireRead||rendered.applyEnabled)){if(requireRead&&offset+size<rows.length){offset=Math.min(rows.length-size,offset+size);}else return true;}}}
+ async function review(title,prepared){const rows=operationRows(prepared);while(true){const choice=await menu('Review '+title,['Cancel','Edit','Apply','View change details','Validate (read only)'],{info:rows.slice(0,8),requiresConfirmation:true});if(choice===null||choice===0)return'cancel';if(choice===1)return'edit';if(choice===2){if(rows.length>8){if(!await page('Review all changes',rows,{requireRead:true}))continue;const confirm=await menu('Confirm '+title,['Cancel','Apply'],{info:['All details reviewed. Apply the prepared snapshot?'],requiresConfirmation:true});if(confirm!==1)continue;}return'apply';}if(choice===3)await page('Change details',rows);if(choice===4)await page('Validation',['Prepared plans validated without changes or downloads.','Execution rechecks the reviewed snapshot.','External downloads are checked only after applying.']);}}
+ async function busy(action){session.render({title:'Working',rows:['Operation in progress. Please wait.'],hint:'Ctrl+C: interrupt'});session.setBusy(true);const wasFlowing=input?.readableFlowing;const onData=chunk=>{if(String(chunk).includes('\x03')||String(chunk).includes('\x04'))controller?.abort();};input?.on('data',onData);try{const result=await action();if(controller?.signal.aborted){if(typeof result?.code!=='number')throw interrupted();return{...result,code:130,interrupted:true};}return result;}finally{input?.removeListener('data',onData);if(wasFlowing!==true)input?.pause?.();session.setBusy(false);session.discardInput();}}
+ return{menu,text,page,review,busy};
+}
+export function resultRows(result){return[...(result.messages??[]).map(s=>s.trim()),...[result.stdout,result.stderr].flatMap(text=>text?text.trimEnd().split(/\r?\n/):[]),...(result.results??[]).flatMap(item=>[`${item.platform??item.target?.platform??'Target'}: ${item.status}; rollback: ${item.rollback??'not needed'}`,...(item.residualPaths??[]).map(p=>'Residual path: '+p),...(item.error?['Error: '+item.error.message]:[])]),...(result.error?['Error: '+result.error.message]:[]),'Exit code: '+result.code,...(result.code===0?['Open a new agent session to use changed harness settings.']:['Review the failed target and retry from the menu.']),...(result.exitSession?['CLI replacement ended this session. Run arc again for further management.']:[])];}
+export async function runTui(options={}){
+ let session=options.session,code=0,finalReport;const controller=new AbortController(),signals=options.signals??process;const abort=()=>controller.abort();signals.on('SIGINT',abort);signals.on('SIGTERM',abort);
+ try{session??=createTerminalSession(options);const ui=createTuiInterface(session,{input:options.input??process.stdin,controller}),api={collectStatus,prepareOperation,executeOperation,...options.services},context=options.context?{...options.context,signal:controller.signal}:await createManagementContext({...options.contextOptions,signal:controller.signal});const draft={};let selected=0;
+  while(true){const statuses=await api.collectStatus(context);const info=statuses.map(s=>s.platform+': '+s.state+(s.diagnostics?.length?' — '+s.diagnostics.map(e=>e.message).join('; '):''));const choice=await ui.menu('ARC Management',home,{selected,info});if(choice===null)continue;selected=choice;if(choice===5)return code;
+   try{if(choice===2){await runWorkflow({ui,cwd:context.cwd??process.cwd(),services:options.services,onResult:result=>{code=result.code;if(code===130){finalReport=workflowRows(result);throw interrupted();}}});continue;}
+    let prepared;if(choice===0||choice===1)prepared=await runSetup({ui,statuses,draft,kind:choice===0?'install':'preset',prepare:settings=>api.prepareOperation(context,settings)});
+    else if(choice===3){prepared=await ui.busy(()=>api.prepareOperation(context,{kind:'update'}));const decision=await ui.review('Update Harness',prepared);if(decision!=='apply')prepared=null;}
+    else{const target=await ui.menu('Uninstall target',['Codex','Claude','Both targets']);if(target===null)continue;const global=await ui.menu('Global ARC instructions',['Remove ARC blocks','Preserve ARC blocks']);if(global===null)continue;prepared=await ui.busy(()=>api.prepareOperation(context,{kind:'uninstall',target:['codex','claude','all'][target],skipGlobal:global===1}));const decision=await ui.review('Uninstall Harness',prepared);if(decision!=='apply')prepared=null;}
+    if(!prepared)continue;const result=await ui.busy(()=>api.executeOperation(context,prepared));code=result.code;if(code===130){finalReport=resultRows(result);return 130;}if(result.exitSession){finalReport=resultRows(result);session.render({title:'Result',rows:finalReport,hint:'Session ended'});return code;}await ui.page('Result',resultRows(result));
+   }catch(error){if(['ARC_CANCELLED','ARC_TUI_EOF'].includes(error.code))throw error;code=error.code==='ARC_CLI_INPUT'?2:1;await ui.page('Operation unavailable',[error.message,'No unreviewed changes were applied.']);}
+  }
+ }catch(error){if(error.code==='ARC_CANCELLED')return 130;if(error.code==='ARC_TUI_EOF')return code;if(error.code==='ARC_TUI_TERMINAL')return 2;throw error;}finally{signals.removeListener('SIGINT',abort);signals.removeListener('SIGTERM',abort);session?.dispose();if(finalReport)(options.output??process.stdout).write(finalReport.map(row=>escapeTerminalText(row)).join('\n')+'\n');}
+}

package/lib/tui/render.mjs

@@ -0,0 +1,21 @@
+// Treat all screen content as data. Only terminal.mjs emits terminal commands.
+export function escapeTerminalText(value=''){
+ return String(value).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu,character=>{
+  const code=character.codePointAt(0);return code<=255?'\\x'+code.toString(16).padStart(2,'0'):'\\u{'+code.toString(16)+'}';
+ });
+}
+function width(character){return /[\p{Mark}]/u.test(character)?0:character.codePointAt(0)>=0x1100?2:1;}
+function fit(text,columns){let used=0,result='';for(const character of text){const size=width(character);if(used+size>columns)return{text:result,complete:false};result+=character;used+=size;}return{text:result,complete:true};}
+export function renderScreen(screen={}, {columns=80,rows=24}={}){
+ // Leave the last column unused to avoid terminal autowrap at the right edge.
+ columns=Math.max(1,Math.floor(Number(columns)||80)-1);rows=Math.max(1,Math.floor(Number(rows)||24));
+ const entries=screen.rows??[],hint=screen.hint??'Up/Down: select | Enter: continue | Esc: back';
+ const lines=[escapeTerminalText(screen.title),...entries.map((row,index)=>(index===screen.selected?'> ':'  ')+escapeTerminalText(row)),escapeTerminalText(hint)];
+ const fitted=lines.map(line=>fit(line,columns));
+ const required=screen.requiredRows??entries.map((_,index)=>index);
+ const requiredVisible=required.every(index=>Number.isInteger(index)&&index>=0&&index<entries.length&&index+1<rows-1&&fitted[index+1].complete);
+ const applyEnabled=!screen.requiresConfirmation||(requiredVisible&&fitted[0].complete&&lines.length<=rows&&fitted.at(-1).complete);
+ const visible=fitted.slice(0,rows).map(line=>line.text);
+ if(!applyEnabled)visible[visible.length-1]=fit('Resize terminal to review before applying.',columns).text;
+ return{text:visible.join('\n'),applyEnabled};
+}

package/lib/tui/setup.mjs

@@ -0,0 +1,20 @@
+import {parsePositiveLimit} from '../limits.mjs';
+export function initialSettings(statuses){return Object.fromEntries(['codex','claude'].map(platform=>{const settings=statuses.find(s=>s.platform===platform)?.settings;return[platform,{preset:settings?.modelConfig?.preset??'balanced',language:settings?.language??'en',maxTotalSubagents:settings?.limits?.max_total_subagents??100,maxConcurrentSubagents:settings?.limits?.max_concurrent_subagents??5,skipGlobal:false}];}));}
+export function setupOptions(draft,target){if(target==='all'&&JSON.stringify(draft.codex)!==JSON.stringify(draft.claude))throw Error('Target settings differ. Explicitly select common values before applying to both.');return{...draft[target==='all'?'codex':target],target};}
+export async function runSetup({ui,statuses,draft,kind,prepare}){
+ for(const[key,value]of Object.entries(initialSettings(statuses)))draft[key]??=value;
+ while(true){const targetIndex=await ui.menu(kind==='preset'?'Change Preset':'Install / Reconfigure',['Codex','Claude','Both targets']);if(targetIndex===null)return null;const target=['codex','claude','all'][targetIndex];
+  if(target==='all'&&JSON.stringify(draft.codex)!==JSON.stringify(draft.claude)){
+   const choice=await ui.menu('Target settings differ',['Back','Use Codex values for both','Use Claude values for both'],{info:['Codex: '+summary(draft.codex),'Claude: '+summary(draft.claude),'Choosing common values replaces the other target values.']});if(choice===null||choice===0)continue;const source=choice===1?'codex':'claude';draft.codex={...draft[source]};draft.claude={...draft[source]};
+  }
+  const settings=draft[target==='all'?'codex':target];let editing=true;
+  while(editing){const labels=kind==='preset'?['Preset: '+settings.preset,'Review changes']:['Preset: '+settings.preset,'Harness language: '+settings.language,'Total subagents: '+settings.maxTotalSubagents,'Concurrent subagents: '+settings.maxConcurrentSubagents,'Apply global settings: '+!settings.skipGlobal,'Review changes'];const field=await ui.menu('Settings — '+target,labels);if(field===null)break;
+   if(field===0){const value=await ui.menu('Performance preset',['Economy','Balanced','Smart'],{selected:['economy','balanced','smart'].indexOf(settings.preset)});if(value!==null)settings.preset=['economy','balanced','smart'][value];}
+   else if(kind==='install'&&field===1){const value=await ui.menu('Harness output language',['English','Korean'],{selected:settings.language==='ko'?1:0});if(value!==null)settings.language=['en','ko'][value];}
+   else if(kind==='install'&&(field===2||field===3)){const key=field===2?'maxTotalSubagents':'maxConcurrentSubagents';const raw=await ui.text(field===2?'Maximum total subagents':'Maximum concurrent subagents',String(settings[key]));if(raw!==null)try{settings[key]=parsePositiveLimit(raw);}catch{await ui.page('Invalid limit',['Enter a positive safe ASCII decimal integer.']);}}
+   else if(kind==='install'&&field===4)settings.skipGlobal=!settings.skipGlobal;
+   else{if(target==='all')draft.claude={...settings};const prepared=await prepare({kind,...setupOptions(draft,target)});const action=await ui.review(kind==='preset'?'Change Preset':'Install / Reconfigure',prepared);if(action==='apply'||action===true)return prepared;if(action==='cancel')return null;}
+  }
+ }
+}
+export function summary(s){return`preset=${s.preset}, language=${s.language}, total=${s.maxTotalSubagents}, concurrent=${s.maxConcurrentSubagents}, global=${!s.skipGlobal}`;}

package/lib/tui/terminal.mjs

@@ -0,0 +1,71 @@
+import {StringDecoder} from 'node:string_decoder';
+import {renderScreen} from './render.mjs';
+
+/** Events are {name, sequence, ...detail}. Names: up/down/left/right, enter,
+ * back, text/paste (text), resize (columns,rows), blocked, eof, interrupt
+ * (signal), error (error). Every data chunk gets a sequence; paste is one event.
+ * render/discardInput/setBusy invalidate buffered input. While busy all data is
+ * discarded. Only one nextEvent waiter is allowed. dispose is idempotent,
+ * restores owned terminal state, and settles a waiting reader with eof. Shutdown
+ * discards unread events; a chunk is fully decoded before resolving a reader,
+ * so an Enter followed by EOF in that chunk cannot escape shutdown.
+ */
+export function createTerminalSession({input=process.stdin,output=process.stdout,signals=process}={}){
+ if(!input.isTTY||!output.isTTY)throw Object.assign(Error('An interactive terminal is required.'),{code:'ARC_TUI_TERMINAL'});
+ const wasRaw=Boolean(input.isRaw),wasFlowing=input.readableFlowing;
+ let disposed=false,busy=false,parsing=false,pending='',paste=null,sequence=0,escapeTimer,waiter,queue=[],screen,lastLines=0,applyEnabled=true;
+ let decoder=new StringDecoder('utf8'),lastWasCR=false;
+ const clearTimer=()=>{clearTimeout(escapeTimer);escapeTimer=undefined;};
+ function deliver(name,detail={}){
+  const event={name,sequence,...detail};if(waiter&&!parsing){const resolve=waiter;waiter=undefined;resolve(event);}else queue.push(event);
+ }
+ function discardInput(){clearTimer();pending='';paste=null;decoder=new StringDecoder('utf8');queue=[];}
+ function dispose(){
+  if(disposed)return;disposed=true;clearTimer();pending='';paste=null;queue=[];
+  input.removeListener('data',onData);input.removeListener('end',onEnd);input.removeListener('close',onEnd);input.removeListener('error',onError);
+  output.removeListener('resize',onResize);output.removeListener('error',onError);signals.removeListener('SIGINT',onSigint);signals.removeListener('SIGTERM',onSigterm);
+  try{if(input.setRawMode&&!input.destroyed)input.setRawMode(wasRaw);}finally{
+   try{if(wasFlowing!==true)input.pause();}finally{
+    try{output.write('\x1b[?2004l\x1b[?25h\n');}finally{if(waiter){const resolve=waiter;waiter=undefined;resolve({name:'eof',sequence});}}
+   }
+  }
+ }
+ function finish(name,detail){const resolve=waiter;waiter=undefined;dispose();if(resolve)resolve({name,sequence,...detail});else deliver(name,detail);}
+ function onEnd(){if(!disposed)finish('eof');}
+ function onError(error){if(!disposed)finish('error',{error});}
+ function onSigint(){if(!disposed)finish('interrupt',{signal:'SIGINT'});}
+ function onSigterm(){if(!disposed)finish('interrupt',{signal:'SIGTERM'});}
+ function draw(){
+  const result=renderScreen(screen,{columns:output.columns,rows:output.rows});applyEnabled=result.applyEnabled;
+  if(lastLines)output.write(`\x1b[${lastLines}A\r`);
+  const lines=result.text.split('\n');
+  for(let index=0;index<Math.max(lastLines,lines.length);index++)output.write('\x1b[2K'+(lines[index]??'')+'\n');
+  if(lastLines>lines.length)output.write(`\x1b[${lastLines-lines.length}A\r`);
+  lastLines=lines.length;return result;
+ }
+ function render(value){if(disposed)return{applyEnabled:false,text:''};discardInput();screen=value;try{return draw();}catch(error){dispose();throw error;}}
+ function onResize(){if(disposed)return;discardInput();try{if(screen)draw();deliver('resize',{columns:output.columns,rows:output.rows});}catch(error){onError(error);}}
+ function parse(){
+  while(pending&&!disposed){
+   if(paste!==null){const end=pending.indexOf('\x1b[201~');if(end<0){const tail=pending.lastIndexOf('\x1b');if(tail<0){paste+=pending;pending='';}else{paste+=pending.slice(0,tail);pending=pending.slice(tail);}return;}paste+=pending.slice(0,end);pending=pending.slice(end+6);deliver('paste',{text:paste});paste=null;continue;}
+   if(pending.startsWith('\x1b[200~')){pending=pending.slice(6);paste='';continue;}
+   const arrow=/^\x1b(?:\[|O)([ABCD])/.exec(pending);
+   if(arrow){pending=pending.slice(arrow[0].length);deliver({A:'up',B:'down',C:'right',D:'left'}[arrow[1]]);continue;}
+   if(pending[0]==='\x1b'){
+    if(pending==='\x1b'||['\x1b[','\x1bO','\x1b[2','\x1b[20','\x1b[200'].includes(pending)){escapeTimer=setTimeout(()=>{escapeTimer=undefined;pending='';deliver('back');},35);return;}
+    // Unknown escape sequences are consumed as text, never executed as keys.
+    const unknown=/^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(pending);if(unknown){pending=pending.slice(unknown[0].length);continue;}
+    pending=pending.slice(1);deliver('back');continue;
+   }
+   const character=[...pending][0];pending=pending.slice(character.length);const skipLF=lastWasCR&&character==='\n';lastWasCR=character==='\r';if(skipLF)continue;
+   if(character==='\x03'){onSigint();return;}if(character==='\x04'){onEnd();return;}
+   if(character==='\r'||character==='\n')deliver(applyEnabled?'enter':'blocked');
+   else if(character==='\x7f'||character==='\b')deliver('back');
+   else if(!/[\p{Cc}]/u.test(character))deliver('text',{text:character});
+  }
+ }
+ function onData(chunk){if(disposed||busy)return;sequence++;clearTimer();pending+=typeof chunk==='string'?chunk:decoder.write(chunk);parsing=true;try{parse();}finally{parsing=false;if(waiter&&queue.length){const resolve=waiter;waiter=undefined;resolve(queue.shift());}}}
+ input.on('data',onData);input.on('end',onEnd);input.on('close',onEnd);input.on('error',onError);output.on('resize',onResize);output.on('error',onError);signals.on('SIGINT',onSigint);signals.on('SIGTERM',onSigterm);
+ try{input.setRawMode?.(true);input.resume();output.write('\x1b[?25l\x1b[?2004h');}catch(error){dispose();throw error;}
+ return{render,discardInput,dispose,setBusy(value){busy=Boolean(value);discardInput();},nextEvent(){if(queue.length)return Promise.resolve(queue.shift());if(disposed)return Promise.resolve({name:'eof',sequence});if(waiter)return Promise.reject(Error('Only one terminal event reader is allowed.'));return new Promise(resolve=>{waiter=resolve;});}};
+}

package/lib/tui/workflow.mjs

@@ -0,0 +1,12 @@
+import * as workflowServices from '../management/workflow.mjs';
+export async function runWorkflow({ui,cwd,services={},onResult=()=>{}}){
+ const api={...workflowServices,...services};let workspace=cwd;
+ while(true){let observed;try{observed=await api.observeWorkspace(workspace);}catch(error){if(['ARC_CANCELLED','ARC_TUI_EOF'].includes(error.code))throw error;const selection=await ui.menu('Workflow workspace',['Back','Change workspace'],{info:['Workspace: '+workspace,'Cannot observe this repository. Select a valid repository root.']});if(selection!==1)return;const value=await ui.text('Absolute repository root',workspace);if(value!==null)workspace=value;continue;}workspace=observed.realpath;const selection=await ui.menu('Workflow workspace',['Continue','Change workspace'],{info:['Workspace: '+observed.realpath,'Branch: '+(observed.branch??'(detached)'),'HEAD: '+observed.head]});if(selection===null)return;if(selection===1){const value=await ui.text('Absolute repository root',workspace);if(value!==null)workspace=value;continue;}
+  let leave=false;while(!leave){const workflows=await api.listWorkflows(workspace);const pick=await ui.menu('Workflows',['Initialize workflow',...workflows.map(w=>w.id+(w.foreign?' — different target':w.invalid?' — invalid state':` — revision ${w.revision}`))]);if(pick===null)break;
+   let workflowId;if(pick===0){workflowId=await ui.text('Workflow ID','');if(workflowId===null)continue;const actor=await ui.text('Actor ID (operator attestation)','');if(actor===null)continue;const messageRef=await ui.text('Target selection message reference','');if(messageRef===null)continue;const contentHash=await ui.text('Target selection content hash (sha256:...)','');if(contentHash===null)continue;await submit('init',{mode:'plan',actor:{id:actor},selection:{messageRef,contentHash}});}
+   else{workflowId=workflows[pick-1].id;while(true){const action=await ui.menu('Workflow — '+workflowId,['Refresh status','Record evidence','Prepare task / operation','Record result','Reconcile']);if(action===null)break;const command=['status','record','prepare','result','reconcile'][action];if(command==='status')await submit(command);else{const jsonPath=await ui.text('Absolute regular JSON file (payload stays private)','');if(jsonPath!==null)await submit(command,undefined,jsonPath);}}}
+   async function submit(command,input,jsonPath){try{const prepared=await api.prepareWorkflow({cwd:workspace,workflowId,command,input,jsonPath});const review=await ui.review('Workflow '+command,{kind:'workflow',command,cwd:workspace,workflowId});if(review!=='apply'&&review!==true)return;const result=await ui.busy?.(()=>api.executeWorkflow(prepared))??await api.executeWorkflow(prepared);onResult(result);await ui.page('Workflow '+String(result.decision).toUpperCase(),workflowRows(result));}catch(error){if(['ARC_CANCELLED','ARC_TUI_EOF'].includes(error.code))throw error;await ui.page('Workflow input rejected',['Check absolute paths, JSON schema, revision and matching checkout.','Payload and error details are hidden to protect secrets.']);}}
+  }
+ }
+}
+export function workflowRows(result){return['Decision: '+result.decision+' (exit '+result.code+')','Workflow: '+result.workflowId,'Revision: '+result.revision,...(result.target?['Workspace: '+result.target.realpath,'HEAD: '+result.target.head]:[]),...(result.ruleIds??[]).map(r=>'Rule: '+r),...(result.tasks??[]).map(t=>'Task: '+t.id+' — '+t.status),...(result.unresolved??[]),...(result.requiredEvidence??[]).map(r=>'Required: '+r),...(result.nextActions??[]).map(r=>'Next: '+r),...(result.error?[result.error]:[])];}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunhozz/arc",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/scripts/postinstall.mjs

@@ -1,4 +1,2 @@
-import {fileURLToPath} from 'node:url';
 import {runPostinstall} from '../lib/cli/postinstall.mjs';
-const packageRoot=fileURLToPath(new URL('../',import.meta.url));
-process.exitCode=await runPostinstall({packageRoot,cwd:packageRoot});
+process.exitCode=await runPostinstall({});