@yunhozz/arc 0.0.0-stage → 0.1.0

package/lib/installer/acquisition.mjs

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import {spawn as nodeSpawn} from 'node:child_process';
+import {readCheckedFile,sameIdentity,typeOf} from './targets.mjs';
+
+import {REQUIRED,SKILLS,snapshotSkill,createReferenceBundle} from './superpowers.mjs';
+const ARGV=['clone','--depth','1','--single-branch','--no-tags','--','https://github.com/obra/superpowers'];
+const defaultClock={setTimeout:(fn,ms)=>setTimeout(fn,ms),clearTimeout:id=>clearTimeout(id)};
+export class AcquisitionError extends Error{
+ constructor(message,{code='ARC_ACQUISITION',cause,residualPaths}={}){super(message,{cause});this.name='AcquisitionError';this.code=code;this.exitCode=code==='ARC_ACQUISITION_CANCELLED'?130:1;if(residualPaths)this.residualPaths=residualPaths;}
+}
+const failure=message=>{throw new AcquisitionError(message);};
+function decode(bytes,stream){try{return new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes);}catch{failure(`Upstream Git returned non-UTF-8 ${stream}`);}}
+function environment(work){
+ const result={};for(const key of ['PATH','LANG','LC_ALL'])if(process.env[key]!==undefined)result[key]=process.env[key];
+ Object.assign(result,{CI:'1',DO_NOT_TRACK:'1',HOME:path.join(work,'home'),XDG_CONFIG_HOME:path.join(work,'config'),CODEX_HOME:path.join(work,'codex-runtime'),TMPDIR:path.join(work,'tmp'),XDG_STATE_HOME:path.join(work,'state'),npm_config_cache:path.join(work,'npm-cache'),npm_config_userconfig:path.join(work,'npm-userconfig'),npm_config_globalconfig:path.join(work,'npm-globalconfig'),npm_config_audit:'false',npm_config_fund:'false',npm_config_update_notifier:'false',GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:path.join(work,'gitconfig'),GIT_TERMINAL_PROMPT:'0',GIT_CONFIG_COUNT:'3',GIT_CONFIG_KEY_0:'core.hooksPath',GIT_CONFIG_VALUE_0:'/dev/null',GIT_CONFIG_KEY_1:'protocol.file.allow',GIT_CONFIG_VALUE_1:'never',GIT_CONFIG_KEY_2:'submodule.recurse',GIT_CONFIG_VALUE_2:'false'});
+ return result;
+}
+function clearHeldDirectory(directory){
+ for(const name of directory.readDir()){
+  const before=directory.lstat(name);
+  if(typeOf(before)===0o040000){const child=directory.openDir(name);try{if(!sameIdentity(before,child.stat()))failure('Work entry changed before cleanup');clearHeldDirectory(child);}finally{child.close();}directory.rmdir(name);}
+  else directory.unlink(name);
+ }
+}
+function groupExists(pid){if(!pid)return false;try{process.kill(-pid,0);return true;}catch(error){if(error.code==='ESRCH')return false;if(error.code==='EPERM')return true;throw error;}}
+function signalGroup(pid,signal){if(!pid)return;try{process.kill(-pid,signal);}catch(error){if(error.code!=='ESRCH')throw error;}}
+function groupGone(pid,clock){
+ if(!groupExists(pid))return Promise.resolve();
+ return new Promise((resolve,reject)=>{let poll,done=false;const finish=error=>{if(done)return;done=true;clock.clearTimeout(poll);clock.clearTimeout(deadline);if(error)reject(error);else resolve();};const check=()=>{try{if(!groupExists(pid))finish();else poll=clock.setTimeout(check,20);}catch(error){finish(error);}};const deadline=clock.setTimeout(()=>{try{finish(groupExists(pid)?new AcquisitionError('External skill descendants did not terminate'):undefined);}catch(error){finish(error);}},5000);check();});
+}
+async function terminateGroup(child,completed,clock){
+ const pid=child?.pid;if(!groupExists(pid))return;
+ signalGroup(pid,'SIGTERM');let timer;const grace=new Promise(resolve=>{timer=clock.setTimeout(resolve,5000);});
+ try{await Promise.race([completed,grace]);if(groupExists(pid))await grace;if(groupExists(pid))signalGroup(pid,'SIGKILL');await groupGone(pid,clock);await completed;}
+ finally{clock.clearTimeout(timer);}
+}
+export async function acquireExternalSkills({work,safeFs,spawn=nodeSpawn,signal,clock=defaultClock}){
+ let root,owned=false,transferred=false,child,completed,timer,onAbort,termination;try{
+  if(typeof work!=='string'||!path.isAbsolute(work)||path.normalize(work)!==work)failure('Acquisition work must be an absolute normalized directory');
+  root=safeFs.openRoot(work);const identity=root.stat();if(root.readDir().length)failure('Acquisition work directory must be empty');owned=true;
+  if(signal?.aborted)throw new AcquisitionError('External skill acquisition cancelled',{code:'ARC_ACQUISITION_CANCELLED'});
+  for(const name of ['home','config','codex-runtime','npm-cache','state','tmp'])root.mkdir(name,0o700);
+  for(const name of ['npm-userconfig','npm-globalconfig','gitconfig']){const file=root.openFile(name,{createExclusive:true,mode:0o600});file.close();}
+  async function run(args){
+  termination=undefined;
+  const stdout=[],stderr=[];let startError;
+  child=spawn('git',args,{cwd:work,env:environment(work),stdio:['ignore','pipe','pipe'],detached:true,shell:false});
+  completed=new Promise(resolve=>{child.stdout.on('data',bytes=>stdout.push(Buffer.from(bytes)));child.stderr.on('data',bytes=>stderr.push(Buffer.from(bytes)));child.once('error',error=>{startError=error;});child.once('close',(code,killedBy)=>resolve({code,killedBy}));});
+  const interrupted=new Promise((resolve,reject)=>{timer=clock.setTimeout(()=>reject(new AcquisitionError('External skill acquisition timed out after 300 seconds',{code:'ARC_ACQUISITION_TIMEOUT'})),300000);onAbort=()=>reject(new AcquisitionError('External skill acquisition cancelled',{code:'ARC_ACQUISITION_CANCELLED'}));signal?.addEventListener('abort',onAbort,{once:true});if(signal?.aborted)onAbort();});
+  const result=await Promise.race([completed,interrupted]);clock.clearTimeout(timer);termination=terminateGroup(child,completed,clock);await termination;
+  if(signal?.aborted)throw new AcquisitionError('External skill acquisition cancelled',{code:'ARC_ACQUISITION_CANCELLED'});
+  if(startError)throw new AcquisitionError(`Cannot start upstream Git: ${startError.message}`,{cause:startError});
+  const errorText=decode(Buffer.concat(stderr),'stderr');if(result.code!==0)failure(`Upstream Git failed with exit code ${result.code}${errorText.trim()?': '+errorText.trim():''}`);
+  signal?.removeEventListener('abort',onAbort);onAbort=undefined;
+  return decode(Buffer.concat(stdout),'stdout');
+  }
+  await run([...ARGV,path.join(work,'upstream')]);
+  const revision=(await run(['-C',path.join(work,'upstream'),'rev-parse','HEAD'])).trim();
+  if(!/^[a-f0-9]{40,64}$/.test(revision))failure('Git returned an invalid revision');
+  const current=safeFs.openRoot(work);try{const now=current.stat();if(now.dev!==identity.dev||now.ino!==identity.ino)failure('Acquisition work path was replaced');}finally{current.close();}
+  const agents=root.openDir('upstream');let directory;try{directory=agents.openDir('skills');}finally{agents.close();}
+  const skills=new Map();try{for(const name of SKILLS){const skill=directory.openDir(name);try{skills.set(name,snapshotSkill(skill,path.join(work,'upstream/skills',name),REQUIRED[name]));}finally{skill.close();}}}finally{directory.close();}
+  const upstream=root.openDir('upstream');let license;try{license=readCheckedFile(upstream,'LICENSE').bytes;}finally{upstream.close();}
+  const references=createReferenceBundle({skills,license,revision});
+  let disposed=false;
+  const dispose=async()=>{
+   if(disposed)return;disposed=true;
+   try{clearHeldDirectory(root);}
+   catch(cause){throw new AcquisitionError('Cannot dispose private acquisition work; preserve residual work',{code:'ARC_ACQUISITION_CLEANUP',cause,residualPaths:[work]});}
+   finally{root.close();}
+  };
+  transferred=true;return{work,skills,references,dispose};
+ }catch(cause){let error=cause instanceof AcquisitionError?cause:new AcquisitionError(`External skill acquisition failed: ${cause.message}`,{cause});
+  try{if(child&&completed){termination??=terminateGroup(child,completed,clock);await termination;}if(owned)clearHeldDirectory(root);}catch(cleanup){error=new AcquisitionError(`Acquisition cleanup failed; preserve residual work: ${work}`,{code:'ARC_ACQUISITION_CLEANUP',cause:cleanup,residualPaths:[work]});error.work=work;}
+  throw error;
+ }finally{if(timer!==undefined)clock.clearTimeout(timer);if(onAbort)signal?.removeEventListener('abort',onAbort);if(!transferred)root?.close();}
+}

package/lib/installer/global-config.mjs

@@ -0,0 +1,43 @@
+import{defaultRolePolicy,renderPolicySection}from'../policy/render.mjs';
+import{languagePolicy}from'./language.mjs';
+import{isDeepStrictEqual}from'node:util';import{parseToml}from'../models/config.mjs';
+export class GlobalConfigurationError extends Error{constructor(message,options){super(message,options);this.name='GlobalConfigurationError';this.code='ARC_GLOBAL_CONFIGURATION';}}
+const fail=message=>{throw new GlobalConfigurationError(message);};
+const BEGIN='<!-- arc:begin -->',END='<!-- arc:end -->';
+function decode(bytes){if(bytes===null)return'';if(!Buffer.isBuffer(bytes))fail('Global configuration must be read as bytes');try{return new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes);}catch{fail('Global file is not UTF-8; fix it or use --skip-global');}}
+export function removeManagedBlock(original){return removeBlock(original,false,true);}
+function removeBlock(original,consumeEol,consumeTerminalEol=false){
+ const text=decode(original);
+ if(/<!--\s*[A-Za-z0-9_-]+\s*:\s*begin\b[^\r\n]*managed\s+by\s+install\.py/i.test(text)||/<!--\s*(?!arc\s*:)[A-Za-z0-9_-]+\s*:\s*(?:begin|end)\b/i.test(text))fail('Unsupported prior managed markers; automatic migration is not supported');
+ const begins=text.split(BEGIN).length-1,ends=text.split(END).length-1,starts=[...text.matchAll(/<!--\s*arc\b/gi)].length;
+ if(starts!==begins+ends||begins!==ends||begins>1||(begins&&text.indexOf(BEGIN)>text.indexOf(END)))fail('Malformed ARC managed markers');
+ let rest=text;if(begins){const start=text.indexOf(BEGIN);let stop=text.indexOf(END)+END.length;if(consumeEol||consumeTerminalEol&&/^(?:\r\n|\n)*$/.test(text.slice(stop))){if(text.slice(stop,stop+2)==='\r\n')stop+=2;else if(text[stop]==='\n')stop++;}rest=text.slice(0,start)+text.slice(stop);}
+ return{content:Buffer.from(rest),changed:Boolean(begins)};
+}
+export function renderManagedBlock(original,body){
+ const text=decode(original),eol=/\r?\n/.exec(text)?.[0]??'\n';
+ const {content:removed}=removeBlock(original,true);
+ const begins=text.includes(BEGIN);let rest=removed.toString('utf8');
+ const outside=rest;
+ if(rest&&!rest.endsWith('\n'))rest+=eol;
+ const separator=!rest||rest.endsWith(eol+eol)?'':eol;
+ const normalizedBody=body.replace(/\r?\n/g,eol);const block=BEGIN+eol+'## Agent Role Coordination'+eol+eol+normalizedBody+(normalizedBody.endsWith(eol)?'':eol)+END+eol;
+ return{content:Buffer.from(rest+separator+block),action:original===null?'create with managed ARC block':begins?'update managed ARC block at the end':'append managed ARC block',notes:/^(#{1,6})[ \t]+(?:\d+\.[ \t]*)?(?:ARC|Agent Role Coordination)[ \t]*\r?$/im.test(outside)?['An existing ARC section outside the managed block was preserved']:[]};
+}
+export function renderWaitSettings(original){
+ const text=decode(original);let data;try{data=parseToml(text);}catch(cause){throw new GlobalConfigurationError(`Cannot parse Codex config.toml: ${cause.message}`,{cause});}
+ const wanted={min_wait_timeout_ms:120000n,default_wait_timeout_ms:300000n};const features=data.features,current=features?.multi_agent_v2;
+ if(current&&typeof current==='object'&&Object.entries(wanted).every(([k,v])=>current[k]===v))return{content:Buffer.from(text),action:'unchanged'};
+ const manual=reason=>({content:null,action:`skip: set [features.multi_agent_v2] wait settings manually (${reason})`});
+ const lines=text.match(/[^\n]*\n|[^\n]+$/g)??[],eol=/\r?\n/.exec(text)?.[0]??'\n';
+ const index=lines.findIndex(line=>/^[ \t]*\[[ \t]*features[ \t]*\.[ \t]*multi_agent_v2[ \t]*\][ \t]*(?:#[^\r\n]*)?\r?\n?$/.test(line));
+ if(features!==undefined&&(!features||typeof features!=='object'||Array.isArray(features))||current!==undefined&&(!current||typeof current!=='object'||Array.isArray(current)||index<0))return manual('features.multi_agent_v2 is not its own table');
+ let updated;if(index<0){let prefix=text;if(prefix&&!prefix.endsWith('\n'))prefix+=eol;if(prefix&&!prefix.endsWith(eol+eol))prefix+=eol;updated=prefix+'[features.multi_agent_v2]'+eol+Object.entries(wanted).map(([k,v])=>`${k} = ${v}${eol}`).join('');}
+ else{if(!lines[index].endsWith('\n'))lines[index]+=eol;let end=lines.findIndex((line,i)=>i>index&&/^[ \t]*\[/.test(line));if(end<0)end=lines.length;const section=lines.slice(index+1,end),remaining=new Map(Object.entries(wanted));for(let i=0;i<section.length;i++){const m=/^([ \t]*(min_wait_timeout_ms|default_wait_timeout_ms)[ \t]*=[ \t]*)([^#\r\n]*?)([ \t]*(?:#[^\r\n]*)?)(\r?\n)?$/.exec(section[i]);if(m&&remaining.has(m[2])){section[i]=m[1]+remaining.get(m[2])+m[4]+(m[5]??'');remaining.delete(m[2]);}}
+ let insertion=section.length;while(insertion&&!section[insertion-1].trim())insertion--;if(insertion&& !section[insertion-1].endsWith('\n'))section[insertion-1]+=eol;section.splice(insertion,0,...[...remaining].map(([k,v])=>`${k} = ${v}${eol}`));updated=[...lines.slice(0,index+1),...section,...lines.slice(end)].join('');}
+ const expected=parseToml(text);expected.features??=Object.create(null);expected.features.multi_agent_v2??=Object.create(null);Object.assign(expected.features.multi_agent_v2,wanted);
+ try{if(!isDeepStrictEqual(parseToml(updated),expected))return manual('automatic edit could not be verified');}catch{return manual('automatic edit could not be verified');}
+ return{content:Buffer.from(updated),action:'set ARC wait settings'};
+}
+export function agentsBlockBody(home,userHome,language='en',platform='codex'){const skill=home+'/skills/arc/SKILL.md',within=skill.startsWith(userHome+'/'),shown=within?'~/'+skill.slice(userHome.length+1):skill;return '- '+languagePolicy(language)+'\n'+'- For requests requiring substantive multi-step research, analysis, or implementation, configuration, or test work, and for design, spec, plan, and brainstorming requests (these are NOT standalone document writing), load and follow `'+shown+'`; keep following it in relevant follow-up turns of the same chat without re-reading it unless it changed.'+(within?" Resolve `~` to the current user's home directory.":'')+' ARC subagents (depth 2) follow their role profile and brief instead and do not load `SKILL.md`.\n'+'- Design, spec, plan, and brainstorming drafts are authored ONLY by the Planner. Orchestrator MUST NEVER author them; route drafting skills to the Planner.\n'+
+'- For repository implementation, configuration, or test work, Orchestrator owns coordination and acceptance; assign file edits and other work to the other roles according to their defined responsibilities. Orchestrator must not edit implementation, configuration, or test-code files directly, except under the ARC Orchestrator direct path for small, low-risk tasks.\n'+'\n[ARC role policy: global begin]\n'+renderPolicySection(defaultRolePolicy,{platform,audience:'orchestrator',section:'contract',skillPath:shown})+'\n[ARC role policy: global end]\n';}

package/lib/installer/install.mjs

@@ -0,0 +1,28 @@
+import {validatePlanSet} from './plan.mjs';
+import {assertPlanSnapshot,applyTransaction} from './transaction.mjs';
+function pending(plan){return{platform:plan.target.platform,status:'not-started',rollback:'not-needed',residualPaths:[],error:null};}
+export async function installTargets(plans,{safeFs,acquisition,signal,hooks={}}){
+ const ordered=[...plans].sort((a,b)=>(a.target.platform==='codex'?0:1)-(b.target.platform==='codex'?0:1));const results=ordered.map(pending);let interrupted=false;
+ let invalid=false;
+ for(let index=0;index<ordered.length;index++){
+  try{validatePlanSet([ordered[index]]);assertPlanSnapshot(ordered[index],{safeFs});}catch(error){results[index]={...results[index],status:'failed',error};invalid=true;}
+ }
+ for(let first=0;first<ordered.length;first++)for(let second=first+1;second<ordered.length;second++){
+  if(results[first].status==='failed'||results[second].status==='failed')continue;
+  try{validatePlanSet([ordered[first],ordered[second]]);}catch(error){results[first]={...results[first],status:'failed',error};results[second]={...results[second],status:'failed',error};invalid=true;}
+ }
+ if(invalid)return{results,interrupted};
+ for(let index=0;index<ordered.length;index++){
+  const plan=ordered[index];if(signal?.aborted){interrupted=true;break;}
+  let acquired,failed=false;
+  try{
+   hooks.fault?.({phase:'before-acquisition',plan});assertPlanSnapshot(plan,{safeFs});
+   acquired=await acquisition(plan,{signal});
+   hooks.fault?.({phase:'after-acquisition',plan});assertPlanSnapshot(plan,{safeFs});
+   const installed=applyTransaction(plan,{safeFs,acquired,signal,hooks});
+   results[index]={...results[index],status:'installed',error:installed.cleanupError??null,residualPaths:[...results[index].residualPaths,...(installed.residualPaths??[])]};if(installed.cleanupError)failed=true;
+  }catch(error){const cancelled=signal?.aborted||error.code==='ARC_ACQUISITION_CANCELLED'||error.code==='ARC_INSTALL_CANCELLED';interrupted=Boolean(cancelled);results[index]={...results[index],status:'failed',rollback:error.rollback??'not-needed',residualPaths:[...results[index].residualPaths,...(error.residualPaths??[])],error};failed=true;}finally{if(acquired?.dispose){try{const disposal=await acquired.dispose();if(disposal?.residualPaths)results[index].residualPaths=[...new Set([...results[index].residualPaths,...disposal.residualPaths])];}catch(cleanup){const result=results[index];result.error=result.error?new AggregateError([result.error,cleanup],'Installation and acquisition cleanup reported failures'):cleanup;result.residualPaths=[...new Set([...result.residualPaths,...(cleanup.residualPaths??(acquired.work?[acquired.work]:[]))])];failed=true;}}}
+  if(failed)break;
+ }
+ return{results,interrupted};
+}

package/lib/installer/language.mjs

@@ -0,0 +1,13 @@
+import {parseToml} from '../models/config.mjs';
+const MARKER='{{ARC_OUTPUT_LANGUAGE_POLICY}}';
+export function validateLanguage(language){if(!['en','ko'].includes(language))throw new Error(`Invalid language: ${language}`);return language;}
+export function parseLanguage(bytes){
+ if(!Buffer.isBuffer(bytes))throw new Error('Language settings must be bytes');
+ const data=parseToml(new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes));
+ if(Object.keys(data).length!==2||!Object.hasOwn(data,'version')||!Object.hasOwn(data,'language')||data.version!==1n&&data.version!==1)throw new Error('Invalid language settings schema or version');
+ return{version:1,language:validateLanguage(data.language)};
+}
+export function serializeLanguage(language){return Buffer.from(`version = 1\nlanguage = "${validateLanguage(language)}"\n`);}
+export function defaultLanguage(existing){return existing.length&&existing.every(value=>value===existing[0])&&existing[0]?validateLanguage(existing[0]):'en';}
+export function languagePolicy(language){return `Use ${validateLanguage(language)==='ko'?'Korean':'English'} by default for user-facing responses, progress updates, reports, and document titles and prose, including designs, specs, and plans. An explicit user language request overrides this installed default. Preserve identifiers, skill/API names, code, paths, commands, and literal values exactly.`;}
+export function renderLanguagePolicy(bytes,language){const text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);if(text.split(MARKER).length!==2)throw new Error('Expected exactly one ARC output language policy marker');return Buffer.from(text.replace(MARKER,languagePolicy(language)));}

package/lib/installer/limits.mjs

@@ -0,0 +1,21 @@
+import {parseToml} from '../models/config.mjs';
+import {resolveLimits} from '../limits.mjs';
+function validate(data) {
+ const keys=['version','max_total_subagents','max_concurrent_subagents'];
+ if(!data||Object.keys(data).length!==3||keys.some(key=>!Object.hasOwn(data,key))||data.version!==1n&&data.version!==1)throw new Error('Invalid limits schema or version');
+ const value={version:1};
+ for(const key of keys.slice(1)) {
+  const raw=data[key];
+  if(typeof raw!=='bigint'&&typeof raw!=='number'||raw<1||raw>Number.MAX_SAFE_INTEGER)throw new Error(`Invalid ${key}`);
+  value[key]=Number(raw);
+ }
+ return resolveLimits({existing:value});
+}
+export function parseLimits(bytes) {
+ if(!Buffer.isBuffer(bytes))throw new Error('Limits must be bytes');
+ return validate(parseToml(new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes)));
+}
+export function serializeLimits(limits) {
+ const value=validate(limits);
+ return Buffer.from(`version = 1\nmax_total_subagents = ${value.max_total_subagents}\nmax_concurrent_subagents = ${value.max_concurrent_subagents}\n`);
+}

package/lib/installer/manifest.mjs

@@ -0,0 +1,37 @@
+import {POLICY_TARGETS,buildPolicyOutputs} from '../policy/render.mjs';
+import {isDynamicReferencePath,readReferenceBundle} from './superpowers.mjs';
+import path from 'node:path';import crypto from 'node:crypto';import{loadModelConfig,resolveModelSettings,renderProfiles}from '../models/index.mjs';import{readCheckedFile,typeOf,sameIdentity,metadataOf}from './targets.mjs';
+export class PayloadValidationError extends Error{constructor(message,options){super(message,options);this.name='PayloadValidationError';this.code='ARC_PAYLOAD_VALIDATION';}}
+const MUTABLE=new Set(['codex/skill/models.toml','claude/skill/models.toml']);
+const ROOTS=['bin','lib','scripts','vendor','prebuilds','codex/skill','codex/agents','claude/skill','claude/agents'];
+const FIXED=['README.md','install.command','package.json','native/binding.c','native/binding.gyp'];
+function safeName(name){return typeof name==='string'&&name.length>0&&!name.includes('\\')&&!name.includes('\0')&&!name.startsWith('/')&&name.split('/').every(p=>p&&p!=='.'&&p!=='..')&&path.posix.normalize(name)===name;}
+function allowed(name){return FIXED.includes(name)||ROOTS.some(root=>name.startsWith(root+'/'));}
+export function verifyPayload({packageRoot,safeFs}){
+ let root;try{
+  root=safeFs.openRoot(packageRoot);const manifest=readCheckedFile(root,'MANIFEST.sha256').bytes;let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(manifest);}catch{throw Error('Manifest is not UTF-8');}
+  const listed=new Map();for(const line of text.split(/\r?\n/)){if(!line)continue;const m=/^([a-fA-F0-9]{64})  (.+)$/.exec(line);if(!m||!safeName(m[2]))throw Error('Malformed or escaping manifest path');const name=m[2];if(MUTABLE.has(name)||isDynamicReferencePath(name)||!allowed(name)||name.split('/').includes('.DS_Store')||listed.has(name))throw Error(`Duplicate, mutable or unexpected manifest entry: ${name}`);listed.set(name,m[1].toLowerCase());}
+  const files=new Map(),snapshot=new Map(),referenceTrees={};
+  function walk(directory,prefix){const before=directory.stat();for(const name of directory.readDir()){
+    const relative=prefix?prefix+'/'+name:name;const stat=directory.lstat(name),type=typeOf(stat);
+    if(name==='.DS_Store'){if(type!==0o100000)throw Error('DS_Store must be a regular file');continue;}
+    if(type===0o040000){const sub=directory.openDir(name);try{if(!sameIdentity(stat,sub.stat()))throw Error('Payload directory changed');snapshot.set(relative,{...metadataOf(stat),type:'directory'});if(isDynamicReferencePath(relative))referenceTrees[relative.split('/')[0]]=readReferenceBundle({safeFs,root:path.join(packageRoot,relative),directory:sub});else walk(sub,relative);}finally{sub.close();}}
+    else if(type===0o100000){const item=readCheckedFile(directory,name,stat);if(!MUTABLE.has(relative)&&(!listed.has(relative)||crypto.createHash('sha256').update(item.bytes).digest('hex')!==listed.get(relative)))throw Error(`Missing entry or hash mismatch: ${relative}`);files.set(relative,item.bytes);snapshot.set(relative,item.metadata);}
+    else throw Error(`Unsafe payload type: ${relative}`);
+   }if(!sameIdentity(before,directory.stat()))throw Error('Payload directory changed while reading');}
+  function select(relative,isTree){const parts=relative.split('/');let parent=root;const opened=[];try{for(const component of parts.slice(0,-1)){let st;try{st=parent.lstat(component);}catch(e){if(e.code==='ENOENT')return;throw e;}if(typeOf(st)!==0o040000)throw Error('Unsafe payload parent');const next=parent.openDir(component);if(!sameIdentity(st,next.stat())){next.close();throw Error('Payload parent changed');}opened.push(next);parent=next;}const name=parts.at(-1);let st;try{st=parent.lstat(name);}catch(e){if(e.code==='ENOENT')return;throw e;}if(isTree){if(typeOf(st)!==0o040000)throw Error('Payload root is not a directory');const sub=parent.openDir(name);try{if(!sameIdentity(st,sub.stat()))throw Error('Payload root changed');snapshot.set(relative,{...metadataOf(st),type:'directory'});if(isDynamicReferencePath(relative))referenceTrees[relative.split('/')[0]]=readReferenceBundle({safeFs,root:path.join(packageRoot,relative),directory:sub});else walk(sub,relative);}finally{sub.close();}}else{if(typeOf(st)!==0o100000)throw Error('Payload file is not regular');const item=readCheckedFile(parent,name,st);if(!listed.has(relative)||crypto.createHash('sha256').update(item.bytes).digest('hex')!==listed.get(relative))throw Error(`Missing entry or hash mismatch: ${relative}`);files.set(relative,item.bytes);snapshot.set(relative,item.metadata);}}finally{for(const h of opened.reverse())h.close();}}
+  for(const item of FIXED)select(item,false);for(const item of ROOTS)select(item,true);
+  for(const platform of ['codex','claude'])if(!referenceTrees[platform])throw Error('Required superpowers reference tree is missing');
+  for(const name of listed.keys())if(!files.has(name))throw Error(`Manifest entry is missing: ${name}`);
+  const required=['claude/skill/hooks/role-git-guard.mjs','claude/skill/hooks/git-policy.json','lib/policy/claude-hook.mjs','lib/policy/role-policy.json','lib/policy/render.mjs','scripts/update-role-policy.mjs','lib/limits.mjs','lib/installer/limits.mjs','lib/installer/runtime-config.mjs','README.md','install.command','package.json','bin/arc.mjs','lib/cli/root.mjs','lib/cli/completion.mjs','lib/installer/shell-completion.mjs','lib/installer/manifest.mjs','lib/installer/targets.mjs','lib/installer/global-config.mjs','lib/installer/plan.mjs','lib/safe-fs/index.mjs','lib/safe-fs/native.mjs','lib/models/index.mjs','lib/models/config.mjs','lib/models/profiles.mjs','vendor/toml/LICENSE','vendor/toml/package.json','vendor/toml/provenance.json','vendor/toml/dist/index.js','prebuilds/index.json'];
+  for(const tuple of ['darwin-arm64','darwin-x64','linux-arm64-gnu','linux-x64-gnu'])required.push(`prebuilds/${tuple}/arc_safe_fs.node`);
+  const modelInputs={};for(const platform of ['codex','claude']){const base=`${platform}/skill`;required.push(`${base}/SKILL.md`,`${base}/models.toml`,`${base}/references/limits.md`);const profiles=new Map();for(const role of ['scouter','planner','coder','qa','reviewer']){const name=`arc-${role}.${platform==='codex'?'toml':'md'}`,key=`${platform}/agents/${name}`;required.push(key);profiles.set(name,files.get(key));}modelInputs[platform]={models:files.get(`${base}/models.toml`),profiles};}
+  for(const name of required)if(!files.has(name))throw Error(`Required runtime asset is missing: ${name}`);
+  const policyInputs=new Map(POLICY_TARGETS.map(({path:name})=>[name,files.get(name)]));
+  const policyOutputs=buildPolicyOutputs(policyInputs,JSON.parse(files.get('lib/policy/role-policy.json').toString('utf8')));
+  for(const [name,bytes] of policyOutputs)if(!bytes.equals(files.get(name)))throw Error(`Stale role policy output: ${name}`);
+  const vendor=JSON.parse(files.get('vendor/toml/provenance.json'));for(const name of Object.keys(vendor.files??{}))if(!safeName(name)||!files.has('vendor/toml/'+name))throw Error('Vendored runtime asset is missing');
+  for(const platform of ['codex','claude']){const input=modelInputs[platform];const config=loadModelConfig(input.models,platform);renderProfiles(input.profiles,resolveModelSettings(config));modelInputs[platform]={models:Buffer.from(input.models),profiles:new Map([...input.profiles].map(([k,v])=>[k,Buffer.from(v)]))};}
+  return{packageRoot,files,modelInputs,snapshot,referenceTrees};
+ }catch(cause){throw new PayloadValidationError(`Payload verification failed: ${cause.message}`,{cause});}finally{root?.close();}
+}

package/lib/installer/package-references.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {openRoot} from '../safe-fs/index.mjs';
+import {loadNative} from '../safe-fs/native.mjs';
+import {acquireExternalSkills} from './acquisition.mjs';
+import {DYNAMIC_ROOTS,validateReferenceBundle} from './superpowers.mjs';
+import {inspectPath} from './targets.mjs';
+import {applyTransaction} from './transaction.mjs';
+
+export async function refreshPackageReferences({packageRoot,safeFs,acquisition,signal,hooks={}}){
+ if(!safeFs){const native=loadNative({root:packageRoot});safeFs={openRoot:p=>openRoot(p,{native})};}
+ const paths=DYNAMIC_ROOTS.map(root=>path.join(packageRoot,root)),snapshot=new Map();
+ for(const filename of paths)inspectPath(safeFs,filename,{kind:'directory',tree:true,allowLinks:true,snapshot});
+ let acquired;
+ try{
+  if(acquisition)acquired=await acquisition({signal});
+  else{
+   const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-package-acquire-'));
+   try{acquired=await acquireExternalSkills({work,safeFs,signal});}catch(error){if(!error.residualPaths?.length)fs.rmdirSync(work);throw error;}
+   const dispose=acquired.dispose;acquired.dispose=async()=>{await dispose();fs.rmdirSync(work);};
+  }
+  validateReferenceBundle(acquired.references);
+  const plan={target:{home:packageRoot},managedPaths:paths,externalPaths:[],snapshot};
+  const result=applyTransaction(plan,{safeFs,signal,hooks,specs:paths.map(filename=>({path:filename,tree:acquired.references.entries}))});
+  if(result.cleanupError)throw result.cleanupError;
+  return{...result,provenance:acquired.references.provenance};
+ }catch(error){
+  if(acquired?.dispose){const owned=acquired;acquired=undefined;try{await owned.dispose();}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Reference refresh and cleanup failed'),{residualPaths:[...new Set([...(error.residualPaths??[]),...(cleanup.residualPaths??[])])]});}}
+  throw error;
+ }finally{if(acquired?.dispose)await acquired.dispose();}
+}

package/lib/installer/plan.mjs

@@ -0,0 +1,62 @@
+import {installClaudeHook} from '../policy/claude-hook.mjs';
+import {validateGitPolicy} from '../../claude/skill/hooks/role-git-guard.mjs';
+import{parseLanguage,serializeLanguage,renderLanguagePolicy,validateLanguage}from'./language.mjs';
+import{resolveLimits}from'../limits.mjs';import{parseLimits,serializeLimits}from'./limits.mjs';import{readRuntimeConcurrency,renderCodexConcurrency,renderClaudeConcurrency}from'./runtime-config.mjs';import{assertPlanSnapshot}from'./transaction.mjs';
+import path from'node:path';import{loadModelConfig,applyPreset,serializeModelConfig,renderProfiles,resolveModelSettings}from'../models/index.mjs';import{inspectPath,TargetConfigurationError}from'./targets.mjs';import{renderManagedBlock,renderWaitSettings,agentsBlockBody}from'./global-config.mjs';
+function fail(message){throw new TargetConfigurationError(message);}
+export function previewLimits({target,safeFs}){
+ const snapshot=new Map(),filename=path.join(target.home,'skills/arc/limits.toml');
+ const current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot});
+ let existing=null;try{if(current.exists)existing=parseLimits(current.bytes);}catch(cause){fail(`Invalid ARC limits: ${cause.message}`);}
+ return{existing,snapshot};
+}
+export function previewLanguage({target,safeFs}){
+ const snapshot=new Map(),filename=path.join(target.home,'skills/arc/settings.toml');
+ const current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot});
+ let existing=null;try{if(current.exists)existing=parseLanguage(current.bytes).language;}catch(cause){fail(`Invalid ARC language settings: ${cause.message}`);}
+ return{existing,snapshot};
+}
+export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,limits,concurrentExplicit=false,limitsPreview,language='en',languagePreview}){
+ validateLanguage(language);
+ if(languagePreview)assertPlanSnapshot({snapshot:languagePreview.snapshot},{safeFs});
+ const languageState=languagePreview??previewLanguage({target,safeFs});
+ if(limitsPreview)assertPlanSnapshot({snapshot:limitsPreview.snapshot},{safeFs});
+ const preview=limitsPreview??previewLimits({target,safeFs});
+ limits=resolveLimits({existing:preview.existing,overrides:limits??{}});
+ const input=payload.modelInputs[target.platform];if(!input)fail('Selected payload platform is unavailable');
+ const config=applyPreset(loadModelConfig(input.models,target.platform),preset),profiles=renderProfiles(input.profiles,resolveModelSettings(config));for(const[name,bytes]of profiles)profiles.set(name,renderLanguagePolicy(bytes,language));const modelBytes=Buffer.from(serializeModelConfig(config));
+ if(target.platform==='claude'){try{const script=payload.files.get('claude/skill/hooks/role-git-guard.mjs'),policy=payload.files.get('claude/skill/hooks/git-policy.json');if(!Buffer.isBuffer(script)||!script.length||!Buffer.isBuffer(policy))throw Error('Missing hook assets');validateGitPolicy(JSON.parse(policy.toString('utf8')));for(const[name,bytes]of profiles)profiles.set(name,installClaudeHook(bytes,path.join(target.home,'skills/arc')));}catch(cause){fail(`Invalid Claude Git guard: ${cause.message}`);}}
+ const skill=new Map();for(const[name,bytes]of payload.files)if(name.startsWith(target.payloadPrefix+'/skill/'))skill.set(name.slice((target.payloadPrefix+'/skill/').length),Buffer.from(bytes));skill.set('SKILL.md',renderLanguagePolicy(skill.get('SKILL.md'),language));skill.set('settings.toml',serializeLanguage(language));skill.set('models.toml',modelBytes);skill.set('limits.toml',serializeLimits(limits));
+ const snapshot=new Map(),home=target.home;const skills=path.join(home,'skills'),agents=path.join(home,'agents'),arc=path.join(skills,'arc');
+ for(const name of [home,skills,agents])inspectPath(safeFs,name,{kind:'directory',snapshot});
+ inspectPath(safeFs,arc,{kind:'directory',tree:true,allowLinks:true,snapshot});
+ const profilePaths=target.profileNames.map(name=>path.join(agents,name));for(const name of profilePaths)inspectPath(safeFs,name,{kind:'file',snapshot});
+ const externalPaths=[],summary=['Fresh superpowers references will be acquired inside ARC'];
+ const globalChanges=[];summary.push(`ARC limits: total ${limits.max_total_subagents}; concurrent ${limits.max_concurrent_subagents} (policy: ${arc}/limits.toml)`);
+ if(limits.max_concurrent_subagents>limits.max_total_subagents)summary.push(`Effective concurrency is at most ${limits.max_total_subagents} for a fresh ARC session; it may be lower after cumulative use or due to native capacity.`);
+ if(skipGlobal)summary.push('Native concurrency update skipped (--skip-global).');
+ else for(const filename of target.globalPaths){
+  const current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot}),original=current.bytes??null;
+  let rendered;
+  if(filename===target.instructionPath)rendered=renderManagedBlock(original,agentsBlockBody(home,target.userHome,language,target.platform));
+  else{
+   let previous;try{previous=readRuntimeConcurrency(target.platform,original);}catch(cause){fail(`Invalid native configuration: ${cause.message}`);}
+   if(preview.existing&&previous!==null&&previous!==preview.existing.max_concurrent_subagents&&!concurrentExplicit)fail(`Native concurrency drift at ${filename}; explicitly select --max-concurrent-subagents to update it`);
+   let base=original;if(target.platform==='codex'){const wait=renderWaitSettings(original);base=wait.content??original;if(wait.content===null)summary.push(`${filename}: ${wait.action}`);}
+   try{rendered=target.platform==='codex'?renderCodexConcurrency(base,limits.max_concurrent_subagents):renderClaudeConcurrency(base,limits.max_concurrent_subagents);}catch(cause){fail(`Cannot merge native concurrency: ${cause.message}`);}
+   summary.push(`${filename}: native concurrency ${previous??'missing'} -> ${limits.max_concurrent_subagents}`);
+  }
+  if(rendered.content!==null&&(original===null||!rendered.content.equals(original)))globalChanges.push({path:filename,original,content:rendered.content,action:rendered.action});
+  for(const note of rendered.notes??[])summary.push(`${filename}: ${note}`);
+ }
+ const managedPaths=[arc,...profilePaths,...(skipGlobal?[]:target.globalPaths)];
+ for(const [filename,metadata]of preview.snapshot)snapshot.set(filename,metadata);
+ for(const [filename,metadata]of languageState.snapshot)snapshot.set(filename,metadata);
+ summary.push(`ARC output language: ${language}`);
+ const plan={target,language,preset,skipGlobal,limits,concurrentExplicit,generated:{models:modelBytes,profiles,skill},globalChanges,managedPaths,externalPaths,snapshot,summary};validatePlanSet([plan]);return plan;
+}
+function overlaps(a,b){return a===b||a.startsWith(b+'/')||b.startsWith(a+'/');}
+export function validatePlanSet(plans){
+ const paths=[];for(let i=0;i<plans.length;i++){const plan=plans[i];if(!plan.target?.home||!path.isAbsolute(plan.target.home)||plan.target.home==='/')fail('Unsafe install home');for(let j=0;j<i;j++)if(overlaps(plan.target.home,plans[j].target.home))fail('Selected platform homes overlap');
+ for(const value of [...plan.managedPaths,...plan.externalPaths]){if(typeof value!=='string'||!path.isAbsolute(value)||value==='/'||path.normalize(value)!==value)fail('Unsafe planned write path');for(const previous of paths)if(overlaps(value,previous.path))fail(`Install write paths collide: ${value}`);paths.push({path:value,plan:i});}}
+}

package/lib/installer/preset.mjs

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import {inspectPath,TargetConfigurationError} from './targets.mjs';
+import {loadModelConfig,applyPreset,serializeModelConfig,resolveModelSettings,renderProfiles} from '../models/index.mjs';
+import {assertPlanSnapshot,applyTransaction} from './transaction.mjs';
+import {validatePlanSet} from './plan.mjs';
+export function buildPresetPlan({target,preset,safeFs}){
+ const snapshot=new Map(),modelsPath=path.join(target.home,'skills/arc/models.toml'),managedPaths=[modelsPath,...target.profileNames.map(name=>path.join(target.home,'agents',name))];
+ const read=filename=>{const found=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot});if(!found.exists)throw new TargetConfigurationError(`Installed ARC file missing: ${filename}`);return found.bytes;};
+ const originalModels=read(modelsPath),config=loadModelConfig(originalModels,target.platform),next=applyPreset(config,preset),originalProfiles=new Map(target.profileNames.map((name,i)=>[name,read(managedPaths[i+1])]));
+ const profiles=renderProfiles(originalProfiles,resolveModelSettings(next)),specs=[];
+ if(config.preset!==preset)specs.push({path:modelsPath,bytes:Buffer.from(serializeModelConfig(next))});
+ for(const[name,bytes]of profiles)if(!bytes.equals(originalProfiles.get(name)))specs.push({path:path.join(target.home,'agents',name),bytes});
+ return{target,preset,snapshot,managedPaths,externalPaths:[],specs};
+}
+export async function switchPresetTargets(plans,{safeFs,signal,hooks={}}){
+ const results=plans.map(plan=>({platform:plan.target.platform,status:'not-started',rollback:'not-needed',residualPaths:[],error:null}));
+ try{validatePlanSet(plans);}catch(error){return{results:results.map(item=>({...item,status:'failed',error})),interrupted:false};}
+ let invalid=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};
+ for(let i=0;i<plans.length;i++){
+  if(signal?.aborted)return{results,interrupted:true};const plan=plans[i];
+  try{assertPlanSnapshot(plan,{safeFs});const applied=plan.specs.length?applyTransaction(plan,{safeFs,signal,hooks,specs:plan.specs}):{residualPaths:[],cleanupError:null};results[i]={...results[i],status:plan.specs.length?'updated':'unchanged',residualPaths:applied.residualPaths,error:applied.cleanupError};if(applied.cleanupError)break;}
+  catch(error){results[i]={...results[i],status:'failed',rollback:error.rollback??'not-needed',residualPaths:error.residualPaths??[],error};return{results,interrupted:Boolean(signal?.aborted)};}
+ }
+ return{results,interrupted:false};
+}

package/lib/installer/runtime-config.mjs

@@ -0,0 +1,85 @@
+import {isDeepStrictEqual} from 'node:util';
+import {parseToml} from '../models/config.mjs';
+const KEY='max_concurrent_threads_per_session';
+const ENV='CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS';
+const fail=message=>{throw new Error(message);};
+function decode(bytes) {
+ if(bytes===null)return '';
+ if(!Buffer.isBuffer(bytes))fail('Runtime configuration must be bytes');
+ return new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes);
+}
+function object(value){return value!==null&&typeof value==='object'&&!Array.isArray(value)&&!(value instanceof Date);}
+function positive(value){if(!Number.isSafeInteger(value)||value<1)fail('Concurrency must be a positive safe integer');return value;}
+function codex(text) {
+ const data=parseToml(text);
+ if(data.agents!==undefined&&!object(data.agents))fail('Codex agents must be a table');
+ const value=data.agents?.[KEY];
+ if(value!==undefined&&(typeof value!=='bigint'||value<1n||value>BigInt(Number.MAX_SAFE_INTEGER)))fail('Invalid Codex concurrency integer');
+ return data;
+}
+export function readRuntimeConcurrency(platform,original) {
+ const text=decode(original);
+ if(platform==='codex'){const value=codex(text).agents?.[KEY];return value===undefined?null:Number(value);}
+ if(platform==='claude'){const value=claude(text).env?.[ENV];return value===undefined?null:Number(value);}
+ fail('Unknown runtime platform');
+}
+export function renderCodexConcurrency(original,value) {
+ positive(value);const text=decode(original),data=codex(text);
+ if(data.agents?.[KEY]===BigInt(value))return {content:Buffer.from(text),action:'unchanged'};
+ const eol=/\r?\n/.exec(text)?.[0]??'\n',lines=text.match(/[^\n]*\n|[^\n]+$/g)??[];
+ const header=/^[ \t]*\[[ \t]*agents[ \t]*\][ \t]*(?:#[^\r\n]*)?\r?\n?$/;
+ const index=lines.findIndex(line=>header.test(line));
+ let updated;
+ if(index<0) {
+  // An explicit agents value (inline or dotted) requires manual editing.
+  if(data.agents!==undefined&&!lines.some(line=>/^\s*\[agents\./.test(line)))fail('Unsupported Codex agents representation');
+  let prefix=text;if(prefix&&!prefix.endsWith('\n'))prefix+=eol;
+  updated=prefix+`[agents]${eol}${KEY} = ${value}${eol}`;
+ } else {
+  let end=lines.findIndex((line,i)=>i>index&&/^[ \t]*\[/.test(line));if(end<0)end=lines.length;
+  let found=false;
+  for(let i=index+1;i<end;i++) {
+   const match=/^([ \t]*max_concurrent_threads_per_session[ \t]*=[ \t]*)([^#\r\n]*?)([ \t]*(?:#[^\r\n]*)?)(\r?\n)?$/.exec(lines[i]);
+   if(match){if(found)fail('Ambiguous Codex concurrency');found=true;lines[i]=match[1]+value+match[3]+(match[4]??'');}
+  }
+  if(data.agents?.[KEY]!==undefined&&!found)fail('Unsupported Codex concurrency representation');
+  if(!found){if(!lines[end-1].endsWith('\n'))lines[end-1]+=eol;lines.splice(end,0,`${KEY} = ${value}${eol}`);}
+  updated=lines.join('');
+ }
+ const expected=parseToml(text);expected.agents??=Object.create(null);expected.agents[KEY]=BigInt(value);
+ if(!isDeepStrictEqual(parseToml(updated),expected))fail('Cannot verify safe Codex concurrency edit');
+ return {content:Buffer.from(updated),action:'set Codex concurrency'};
+}
+function claude(text) {
+ const data=text===''?{}:JSON.parse(text);
+ // Validate duplicate names before JSON.parse can silently discard them.
+ const tokens=[...text.matchAll(/"(?:[^"\\]|\\[\s\S])*"|[{}\[\]:,]|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null/g)].map(match=>match[0]);
+ const stack=[];
+ for(let i=0;i<tokens.length;i++) {
+  const token=tokens[i];
+  if(token==='{')stack.push(new Set());
+  else if(token==='[')stack.push(null);
+  else if(token==='}'||token===']')stack.pop();
+  else if(token.startsWith('"')&&tokens[i+1]===':') {
+   const key=JSON.parse(token),keys=stack.at(-1);
+   if(keys?.has(key))fail('Duplicate Claude settings key');
+   keys?.add(key);
+  } else if(/^-?\d/.test(token)) {
+   const number=Number(token);
+   if(!Number.isFinite(number)||Number.isInteger(number)&&!Number.isSafeInteger(number))fail('Unsafe Claude JSON number');
+  }
+ }
+ if(!object(data))fail('Claude settings root must be an object');
+ if(data.env!==undefined&&!object(data.env))fail('Claude env must be an object');
+ const value=data.env?.[ENV];
+ if(value!==undefined&&(typeof value!=='string'||! /^[0-9]+$/.test(value)||!Number.isSafeInteger(Number(value))||Number(value)<1))fail('Invalid Claude concurrency string');
+ return data;
+}
+export function renderClaudeConcurrency(original,value) {
+ positive(value);const text=decode(original),data=claude(text);
+ if(data.env?.[ENV]===String(value))return {content:Buffer.from(text),action:'unchanged'};
+ data.env??={};data.env[ENV]=String(value);
+ const content=Buffer.from(JSON.stringify(data,null,2)+'\n');
+ if(!isDeepStrictEqual(JSON.parse(content),data))fail('Cannot verify safe Claude concurrency edit');
+ return {content,action:'set Claude concurrency'};
+}

package/lib/installer/shell-completion.mjs

@@ -0,0 +1,29 @@
+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){
+ 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)]);
+}
+export function attachShellCompletion(plans,{safeFs}){
+ const plan=plans[0];if(!plan||plan.skipGlobal)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 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'};
+}

package/lib/installer/stage-cleanup.mjs

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import {metadataOf,sameIdentity,sameObjectIdentity,typeOf,readCheckedFile} from './targets.mjs';
+function fail(message){throw new Error(message);}
+export function captureCleanupEntry(parent,name){
+ const stat=parent.lstat(name),type=typeOf(stat);
+ if(type===0o100000)return readCheckedFile(parent,name,stat).metadata;
+ if(type===0o120000){const link=parent.readlink(name);if(!sameIdentity(stat,parent.lstat(name)))fail('Cleanup link changed during inspection');return{...metadataOf(stat),type:'symlink',link};}
+ if(type!==0o040000)fail('Unsafe cleanup item type');
+ const directory=parent.openDir(name);try{if(!sameIdentity(stat,directory.stat()))fail('Cleanup directory changed during inspection');const children=new Map();for(const child of directory.readDir())children.set(child,captureCleanupEntry(directory,child));if(!sameIdentity(stat,directory.stat()))fail('Cleanup directory changed during inspection');return{...metadataOf(stat),type:'directory',children};}finally{directory.close();}
+}
+function matches(expected,actual,{moved=false}={}){
+ const fields=['dev','ino','mode','size','mtimeNs','type','link',...(expected.type==='file'?['sha256']:[]),...(moved?[]:['ctimeNs'])];
+ if(!fields.every(key=>expected[key]===actual[key]))return false;
+ if(expected.children){if(!actual.children||expected.children.size!==actual.children.size)return false;for(const[name,item]of expected.children)if(!actual.children.has(name)||!matches(item,actual.children.get(name)))return false;}
+ return true;
+}
+// Only a currently held, transaction-owned stage and its recorded children may
+// be removed. No stale-prefix scanning, pathname recursion or symlink following.
+export function cleanupStage(area,{safeFs,hooks={}}){
+ const guard=()=>{const named=safeFs.openRoot(path.dirname(area.path));try{if(!sameObjectIdentity(named.stat(),area.parent.stat()))fail('Cleanup parent namespace changed');}finally{named.close();}if(!sameObjectIdentity(area.identity,area.stage.stat())||!sameObjectIdentity(area.identity,area.parent.lstat(area.name)))fail('Cleanup stage identity changed');};
+ const namesMatch=(directory,expected)=>{const names=directory.readDir();if(names.length!==expected.size||names.some(name=>!expected.has(name)))fail('Unknown or missing cleanup entry');};
+ const verify=(parent,name,expected)=>{if(!matches(expected,captureCleanupEntry(parent,name),{moved:true}))fail('Cleanup item drift: '+name);};
+ const remove=(parent,name,expected,absolute)=>{
+  guard();verify(parent,name,expected);
+  if(expected.type==='directory'){
+   const directory=parent.openDir(name);try{if(!sameObjectIdentity(expected,directory.stat()))fail('Cleanup directory identity changed');const remaining=new Map(expected.children);for(const[child,item]of expected.children){namesMatch(directory,remaining);remove(directory,child,item,absolute+'/'+child);remaining.delete(child);}namesMatch(directory,remaining);directory.sync();}finally{directory.close();}
+  }
+  hooks.fault?.({phase:'before-cleanup-item',path:absolute});guard();
+  if(expected.type==='directory'){
+   if(!sameObjectIdentity(expected,parent.lstat(name)))fail('Cleanup directory identity changed before deletion');const directory=parent.openDir(name);try{if(!sameObjectIdentity(expected,directory.stat())||directory.readDir().length)fail('Cleanup directory changed before deletion');}finally{directory.close();}
+   if(!sameObjectIdentity(expected,parent.lstat(name)))fail('Cleanup directory identity changed before deletion');parent.rmdir(name);
+  }else{verify(parent,name,expected);parent.unlink(name);}
+  parent.sync();hooks.fault?.({phase:'after-cleanup-item',path:absolute});
+ };
+ try{
+  guard();namesMatch(area.stage,area.expected);for(const[name,expected]of area.expected)verify(area.stage,name,expected);
+  const remaining=new Map(area.expected);for(const[name,expected]of area.expected){guard();namesMatch(area.stage,remaining);remove(area.stage,name,expected,area.path+'/'+name);remaining.delete(name);}
+  guard();namesMatch(area.stage,remaining);area.stage.sync();guard();area.parent.rmdir(area.name);area.parent.sync();return{residualPaths:[],cleanupError:null};
+ }catch(cause){const cleanupError=Object.assign(new Error(`Stage cleanup failed for ${area.path}: ${cause.message}`,{cause}),{code:'ARC_INSTALL_CLEANUP',residualPaths:[area.path]});return{residualPaths:[area.path],cleanupError};}
+}