@yunhozz/arc 0.0.0-stage → 0.1.1

package/lib/installer/superpowers.mjs

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {readCheckedFile,sameIdentity,typeOf,metadataOf} from './targets.mjs';
+export const REQUIRED=Object.freeze({
+ 'brainstorming':['SKILL.md','visual-companion.md','scripts/start-server.sh','scripts/stop-server.sh','scripts/server.cjs','scripts/helper.js','scripts/frame-template.html'],
+ 'writing-plans':['SKILL.md'],
+ 'test-driven-development':['SKILL.md','writing-good-tests.md'],
+});
+export const SKILLS=Object.freeze(Object.keys(REQUIRED));
+export const REPOSITORY='https://github.com/obra/superpowers';
+export const DYNAMIC_ROOTS=Object.freeze(['codex','claude'].map(platform=>`${platform}/skill/references/superpowers`));
+export const isDynamicReferencePath=name=>DYNAMIC_ROOTS.some(root=>name===root||name.startsWith(root+'/'));
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+function failure(message){throw new Error(message);}
+export function snapshotSkill(root,absolute,required){
+ const rootBefore=root.stat(),entries=new Map(),snapshot=new Map();
+ function walk(directory,prefix=''){
+  const before=directory.stat(),names=directory.readDir();
+  for(const name of names){const relative=prefix?prefix+'/'+name:name,stat=directory.lstat(name),type=typeOf(stat);
+   if(type===0o040000){const child=directory.openDir(name);try{if(!sameIdentity(stat,child.stat()))failure('Acquired directory changed during validation');entries.set(relative,{type:'directory',mode:stat.mode});snapshot.set(relative,{...metadataOf(stat),type:'directory'});walk(child,relative);}finally{child.close();}}
+   else if(type===0o100000){const file=readCheckedFile(directory,name,stat);entries.set(relative,{type:'file',bytes:file.bytes,mode:stat.mode});snapshot.set(relative,file.metadata);}
+   else if(type===0o120000){const raw=directory.readlink(name);const after=directory.lstat(name);if(!sameIdentity(stat,after))failure('Acquired symlink changed during validation');entries.set(relative,{type:'symlink',raw,mode:stat.mode});snapshot.set(relative,{...metadataOf(stat),type:'symlink',link:raw});}
+   else failure('Acquired tree contains a special file');
+  }if(!sameIdentity(before,directory.stat()))failure('Acquired directory changed during validation');
+ }
+ walk(root);
+ const resolvedLinks=new Map();
+ function targetOf(name,trail=new Set()){
+  if(trail.has(name))failure('Acquired symlink cycle');
+  if(resolvedLinks.has(name))return resolvedLinks.get(name);
+  const entry=entries.get(name);if(!entry||entry.type!=='symlink')failure('Invalid acquired link');
+  const active=new Set(trail);active.add(name);
+  const parent=path.posix.dirname(name);const target=resolvePath(entry.raw,parent==='.'?[]:parent.split('/'),active);
+  resolvedLinks.set(name,target);return target;
+ }
+ function resolvePath(raw,base=[],trail=new Set()){
+  let current=[...base],parts;
+  if(raw.startsWith('/')){if(!raw.startsWith(absolute+'/'))failure('Acquired link escapes its root');current=[];parts=raw.slice(absolute.length+1).split('/');}
+  else parts=raw.split('/');
+  for(let i=0;i<parts.length;i++){
+   const part=parts[i];if(!part||part==='.')continue;
+   if(part==='..'){if(!current.length)failure('Acquired link escapes its root');current.pop();continue;}
+   const name=[...current,part].join('/'),entry=entries.get(name);if(!entry)failure('Acquired link is dangling');
+   const canonical=entry.type==='symlink'?targetOf(name,trail):name;
+   if(i<parts.length-1&&entries.get(canonical)?.type!=='directory')failure('Acquired link parent is not a directory');
+   current=canonical.split('/');
+  }
+  const result=current.join('/');if(!result||!entries.has(result))failure('Acquired link resolves to its root or a missing entry');return result;
+ }
+ for(const[name,entry]of entries)if(entry.type==='symlink')targetOf(name);
+ for(const[name,target]of resolvedLinks){const entry=entries.get(name);entry.target=target;entry.link=path.posix.relative(path.posix.dirname(name),target);delete entry.raw;}
+ // Build directory edges, including directory symlinks, to reject cycles that
+ // resolve individually but would create recursive staging traversals.
+ const graph=new Map([['',new Set()]]);for(const[relative,entry]of entries){const parent=path.posix.dirname(relative)==='.'?'':path.posix.dirname(relative);if(!graph.has(parent))graph.set(parent,new Set());if(entry.type==='directory'){graph.get(parent).add(relative);if(!graph.has(relative))graph.set(relative,new Set());}else if(entry.type==='symlink'&&entries.get(entry.target)?.type==='directory')graph.get(parent).add(entry.target);}
+ const active=new Set(),done=new Set();function visit(node){if(active.has(node))failure('Acquired directory links create a cycle');if(done.has(node))return;active.add(node);for(const next of graph.get(node)??[])visit(next);active.delete(node);done.add(node);}visit('');
+ for(const name of required){const actual=resolvePath(name);if(entries.get(actual)?.type!=='file')failure('Required acquired skill file is missing or not regular');}
+ if(!sameIdentity(rootBefore,root.stat()))failure('Acquired root changed during validation');
+ return{root:absolute,rootMetadata:{...metadataOf(rootBefore),type:'directory',entries:root.readDir()},entries,snapshot};
+}
+
+export function createReferenceBundle({skills,license,revision,fetchedAt=new Date().toISOString()}){
+ const entries=new Map([['LICENSE',{type:'file',bytes:Buffer.from(license),mode:0o644n}]]);
+ for(const name of SKILLS){const tree=skills.get(name);if(!tree)failure('Required skill is missing');entries.set(name,{type:'directory',mode:tree.rootMetadata.mode});for(const[key,entry]of tree.entries)entries.set(name+'/'+key,{...entry});}
+ const provenance={schemaVersion:1,repository:REPOSITORY,revision,fetchedAt,skills:[...SKILLS],files:{},links:{}};
+ for(const[name,entry]of entries){if(entry.type==='file')provenance.files[name]=hash(entry.bytes);else if(entry.type==='symlink')provenance.links[name]=entry.link;}
+ entries.set('provenance.json',{type:'file',bytes:Buffer.from(JSON.stringify(provenance,null,2)+'\n'),mode:0o644n});
+ const bundle={entries,provenance};validateReferenceBundle(bundle);return bundle;
+}
+export function validateReferenceBundle(bundle){
+ const entries=bundle?.entries,p=bundle?.provenance;
+ if(!(entries instanceof Map)||!p||p.schemaVersion!==1||p.repository!==REPOSITORY||!/^[a-f0-9]{40,64}$/.test(p.revision)||typeof p.fetchedAt!=='string'||!Number.isFinite(Date.parse(p.fetchedAt))||new Date(p.fetchedAt).toISOString()!==p.fetchedAt||JSON.stringify(p.skills)!==JSON.stringify(SKILLS)||!p.files||typeof p.files!=='object'||Array.isArray(p.files)||!p.links||typeof p.links!=='object'||Array.isArray(p.links))failure('Invalid reference provenance');
+ const files={},links={};
+ for(const[name,entry]of entries){
+  if(typeof name!=='string'||name.includes('\\')||name.includes('\0')||name.split('/').some(part=>!part||part==='.'||part==='..')||!['LICENSE','provenance.json',...SKILLS].includes(name.split('/')[0]))failure('Unexpected reference path');
+  const parent=path.posix.dirname(name);if(parent!=='.'&&entries.get(parent)?.type!=='directory')failure('Reference parent is missing');
+  if(entry.type==='file'){if(!Buffer.isBuffer(entry.bytes))failure('Invalid reference bytes');if(name!=='provenance.json')files[name]=hash(entry.bytes);}
+  else if(entry.type==='symlink'){if(!SKILLS.includes(name.split('/')[0])||typeof entry.link!=='string'||path.posix.isAbsolute(entry.link))failure('Unsafe reference link');const resolved=path.posix.normalize(path.posix.join(parent,entry.link));if(!resolved.startsWith(name.split('/')[0]+'/')||!entries.has(resolved))failure('Reference link escapes or is missing');links[name]=entry.link;}
+  else if(entry.type!=='directory')failure('Unsafe reference entry');
+ }
+ for(const name of ['LICENSE','provenance.json'])if(entries.get(name)?.type!=='file')failure('Reference metadata file missing');
+ if(!entries.get('LICENSE').bytes.length)failure('Reference license is empty');
+ let recorded;try{recorded=JSON.parse(entries.get('provenance.json').bytes);}catch{failure('Malformed reference provenance');}
+ const equal=(a,b)=>Object.keys(a).sort().join('\0')===Object.keys(b).sort().join('\0')&&Object.keys(a).every(key=>a[key]===b[key]);
+ if(JSON.stringify(recorded)!==JSON.stringify(p)||!equal(files,p.files)||!equal(links,p.links))failure('Reference inventory or hash mismatch');
+ function resolve(name,trail=new Set()){
+  if(trail.has(name))failure('Reference link cycle');const entry=entries.get(name);if(!entry)failure('Required reference is missing');
+  if(entry.type==='symlink'){const next=new Set(trail);next.add(name);return resolve(path.posix.normalize(path.posix.join(path.posix.dirname(name),entry.link)),next);}
+  return entry;
+ }
+ for(const[name,entry]of entries)if(entry.type==='symlink')resolve(name);
+ const graph=new Map([['',new Set()]]);
+ for(const[name,entry]of entries){const parent=path.posix.dirname(name)==='.'?'':path.posix.dirname(name);if(!graph.has(parent))graph.set(parent,new Set());if(entry.type==='directory'){graph.get(parent).add(name);if(!graph.has(name))graph.set(name,new Set());}else if(entry.type==='symlink'&&resolve(name).type==='directory')graph.get(parent).add(path.posix.normalize(path.posix.join(path.posix.dirname(name),entry.link)));}
+ const active=new Set(),done=new Set();function visit(name){if(active.has(name))failure('Reference directory link cycle');if(done.has(name))return;active.add(name);for(const next of graph.get(name)??[])visit(next);active.delete(name);done.add(name);}visit('');
+
+ for(const[skill,names]of Object.entries(REQUIRED)){if(entries.get(skill)?.type!=='directory')failure('Required skill tree missing');for(const name of names){let parts=(skill+'/'+name).split('/'),current='';for(let i=0;i<parts.length;i++){current=current?current+'/'+parts[i]:parts[i];const e=entries.get(current);if(e?.type==='symlink'){current=path.posix.normalize(path.posix.join(path.posix.dirname(current),e.link));resolve(current);}if(i===parts.length-1&&resolve(current).type!=='file')failure('Required reference is not regular');}}}
+ return bundle;
+}
+export function readReferenceBundle({safeFs,root,directory:held}){
+ const directory=held??safeFs.openRoot(root);try{
+  const allowed=new Set(['LICENSE','provenance.json',...SKILLS]);if(directory.readDir().some(name=>!allowed.has(name)))failure('Unknown reference tree');
+  const skills=new Map();for(const name of SKILLS){const skill=directory.openDir(name);try{skills.set(name,snapshotSkill(skill,path.join(root,name),REQUIRED[name]));}finally{skill.close();}}
+  const license=readCheckedFile(directory,'LICENSE'),provenance=readCheckedFile(directory,'provenance.json');let p;try{p=JSON.parse(provenance.bytes);}catch{failure('Malformed reference provenance');}
+  const entries=new Map([['LICENSE',{type:'file',bytes:license.bytes,mode:license.metadata.mode}],['provenance.json',{type:'file',bytes:provenance.bytes,mode:provenance.metadata.mode}]]);
+  for(const[name,tree]of skills){entries.set(name,{type:'directory',mode:tree.rootMetadata.mode});for(const[key,value]of tree.entries)entries.set(name+'/'+key,value);}
+  return validateReferenceBundle({entries,provenance:p});
+ }finally{if(!held)directory.close();}
+}
+export function composeArcSkillTree(skillFiles,references){
+ validateReferenceBundle(references);const entries=new Map();
+ for(const[name,bytes]of skillFiles){if(name==='references/superpowers'||name.startsWith('references/superpowers/'))continue;const parts=name.split('/');if(parts.some(part=>!part||part==='.'||part==='..'))failure('Unsafe ARC path');for(let i=1;i<parts.length;i++)entries.set(parts.slice(0,i).join('/'),{type:'directory',mode:0o700n});entries.set(name,{type:'file',bytes:Buffer.from(bytes),mode:0o600n});}
+ entries.set('references',{type:'directory',mode:0o700n});entries.set('references/superpowers',{type:'directory',mode:0o700n});
+ for(const[name,entry]of references.entries)entries.set('references/superpowers/'+name,{...entry});return entries;
+}

package/lib/installer/targets.mjs

@@ -0,0 +1,55 @@
+import path from 'node:path';import crypto from 'node:crypto';
+export class TargetConfigurationError extends Error{constructor(message,options){super(message,options);this.name='TargetConfigurationError';this.code='ARC_TARGET_CONFIGURATION';}}
+const fail=message=>{throw new TargetConfigurationError(message);};
+export function resolveTarget(platform,{userHome,env={},cwd}={}){
+ if(!['codex','claude'].includes(platform))fail('Target must be codex or claude');
+ if(typeof userHome!=='string'||!path.isAbsolute(userHome)||!userHome.trim())fail('userHome must be an absolute user directory');
+ userHome=path.resolve(userHome);if(!env||typeof env!=='object')fail('env must be an environment object');
+ const expand=value=>value==='~'?userHome:value.startsWith('~/')?path.join(userHome,value.slice(2)):value;
+ let home;if(platform==='codex'){const raw=env.CODEX_HOME;if(raw!==undefined&&(typeof raw!=='string'||!raw.trim()))fail('CODEX_HOME is empty or invalid');const expanded=expand(raw??path.join(userHome,'.codex'));if(path.isAbsolute(expanded))home=path.resolve(expanded);else{const base=cwd??process.cwd();if(typeof base!=='string'||!path.isAbsolute(base))fail('cwd must be absolute for relative CODEX_HOME');home=path.resolve(base,expanded);}}
+ else{home=path.join(userHome,'.claude');const raw=env.CLAUDE_CONFIG_DIR;if(raw!==undefined&&(typeof raw!=='string'||!raw.trim()||!path.isAbsolute(expand(raw))||path.resolve(expand(raw))!==home))fail('CLAUDE_CONFIG_DIR must select the default ~/.claude directory');}
+ if(home==='/'||home===path.resolve(userHome))fail('Target home must not be the filesystem or user-home root');
+ const profileNames=['scouter','planner','coder','qa','reviewer'].map(role=>`arc-${role}.${platform==='codex'?'toml':'md'}`);
+ return Object.freeze({platform,home,userHome:path.resolve(userHome),payloadPrefix:platform,profileNames:Object.freeze(profileNames),instructionPath:path.join(home,platform==='codex'?'AGENTS.md':'CLAUDE.md'),runtimeConfigPath:path.join(home,platform==='codex'?'config.toml':'settings.json'),globalPaths:Object.freeze(platform==='codex'?[path.join(home,'AGENTS.md'),path.join(home,'config.toml')]:[path.join(home,'CLAUDE.md'),path.join(home,'settings.json')])});
+}
+export function typeOf(metadata){return Number(metadata.mode&0o170000n);}
+export function sameObjectIdentity(a,b){return ['dev','ino','mode'].every(key=>a[key]===b[key]);}
+export function sameIdentity(a,b){return ['dev','ino','mode','size','mtimeNs','ctimeNs'].every(key=>a[key]===b[key]);}
+export function metadataOf(stat){return Object.fromEntries(['dev','ino','mode','size','atimeNs','mtimeNs','ctimeNs'].map(key=>[key,stat[key]]));}
+export function readCheckedFile(directory,name,before=directory.lstat(name)){
+ const file=directory.openFile(name,{read:true});try{const opened=file.stat();if(!sameIdentity(before,opened))fail('File identity changed before reading');const bytes=file.readAll();const after=file.stat();if(!sameIdentity(opened,after))fail('File changed during read');return{bytes,metadata:{...metadataOf(after),type:'file',sha256:crypto.createHash('sha256').update(bytes).digest('hex')}};}finally{file.close();}
+}
+// Traverse every existing component through held directory descriptors. Missing
+// targets are recorded without creating their parents or opening a fallback path.
+export function inspectPath(safeFs,absolute,{kind,tree=false,allowLinks=false,snapshot=new Map(),read=false,allowLeafLink=false}={}){
+ if(!path.isAbsolute(absolute))fail('Inspection requires an absolute path');
+ const parts=absolute.split('/').filter(Boolean);if(parts.some(p=>p==='.'||p==='..'))fail('Unsafe destination component');
+ let directory=safeFs.openRoot('/');let current='';
+ try{
+  for(let index=0;index<parts.length;index++){
+   const name=parts[index];current+='/'+name;let stat;
+   try{stat=directory.lstat(name);}catch(error){if(error.code==='ENOENT'){snapshot.set(absolute,null);return{exists:false};}throw error;}
+   const type=typeOf(stat),leaf=index===parts.length-1;
+   if(type===0o120000){if(leaf&&allowLeafLink){const link=directory.readlink(name);snapshot.set(current,{...metadataOf(stat),type:'symlink',link});return{exists:true,type:'symlink',link};}fail(`Symlink destination is unsafe: ${current}`);}
+   if(!leaf||kind==='directory'){
+    if(type!==0o040000)fail(`Expected destination directory: ${current}`);
+    const next=directory.openDir(name);if(!sameObjectIdentity(stat,next.stat())){next.close();fail('Directory identity changed during traversal');}directory.close();directory=next;
+    if(leaf){snapshot.set(current,{...metadataOf(stat),type:'directory'});if(tree)inspectTree(directory,current,{allowLinks,snapshot});return{exists:true,type:'directory'};}
+   }else{
+    if(type!==0o100000)fail(`Expected regular destination file: ${current}`);
+    const result=readCheckedFile(directory,name,stat);snapshot.set(current,result.metadata);return{exists:true,type:'file',...(read?{bytes:result.bytes}:{})};
+   }
+  }
+  fail('Filesystem root cannot be a managed destination');
+ }catch(error){if(error instanceof TargetConfigurationError)throw error;throw new TargetConfigurationError(`Cannot inspect destination ${absolute}: ${error.message}`,{cause:error});}finally{directory.close();}
+}
+function inspectTree(directory,absolute,{allowLinks,snapshot}){
+ const before=directory.stat(),names=directory.readDir();snapshot.set(absolute,{...metadataOf(before),type:'directory',entries:names});
+ for(const name of names){const child=absolute+'/'+name,stat=directory.lstat(name),type=typeOf(stat);
+  if(type===0o040000){const next=directory.openDir(name);try{if(!sameIdentity(stat,next.stat()))fail('Directory changed before tree traversal');inspectTree(next,child,{allowLinks,snapshot});}finally{next.close();}}
+  else if(type===0o100000)snapshot.set(child,readCheckedFile(directory,name,stat).metadata);
+  else if(type===0o120000&&allowLinks)snapshot.set(child,{...metadataOf(stat),type:'symlink',link:directory.readlink(name)});
+  else fail(`Unsafe entry in existing destination tree: ${child}`);
+ }
+ if(!sameIdentity(before,directory.stat()))fail('Directory changed during tree inspection');
+}

package/lib/installer/transaction.mjs

@@ -0,0 +1,91 @@
+import {composeArcSkillTree} from './superpowers.mjs';
+import path from 'node:path';
+import {cleanupStage,captureCleanupEntry} from './stage-cleanup.mjs';
+import {randomUUID,createHash} from 'node:crypto';
+import {inspectPath,typeOf,metadataOf,sameObjectIdentity,readCheckedFile} from './targets.mjs';
+
+export class InstallError extends Error {
+ constructor(message,code='ARC_INSTALL_FAILED',details={}) {super(message,{cause:details.cause});this.name='InstallError';this.code=code;Object.assign(this,details);}
+}
+function fail(message,code='ARC_INSTALL_FAILED',details){throw new InstallError(message,code,details);}
+function exists(parent,name){try{return parent.lstat(name);}catch(error){if(error.code==='ENOENT')return null;throw error;}}
+function metadataEqual(a,b){if(a===null||b===null)return a===b;return ['dev','ino','mode','size','mtimeNs','ctimeNs','type','sha256','link'].every(key=>a[key]===b[key])&&JSON.stringify(a.entries)===JSON.stringify(b.entries);}
+function inspectOne(safeFs,filename,expected,snapshot,tree=expected?.type==='directory'){
+ inspectPath(safeFs,filename,{kind:expected?.type==='file'?'file':'directory',tree,allowLinks:true,allowLeafLink:expected?.type==='symlink',snapshot});
+}
+export function capturePlanSnapshot(plan,{safeFs}){
+ const snapshot=new Map();for(const filename of [...plan.managedPaths,...plan.externalPaths]){let parent;let stat=null;try{parent=safeFs.openRoot(path.dirname(filename));stat=exists(parent,path.basename(filename));}catch(error){if(error.code!=='ENOENT')throw error;}finally{parent?.close();}
+ inspectOne(safeFs,filename,stat?{type:typeOf(stat)===0o100000?'file':typeOf(stat)===0o120000?'symlink':'directory'}:null,snapshot);}
+ plan.snapshot=snapshot;return snapshot;
+}
+export function assertPlanSnapshot(plan,{safeFs}){
+ const fresh=new Map();try{
+ for(const[filename,expected]of plan.snapshot)inspectOne(safeFs,filename,expected,fresh,expected?.type==='directory'&&Object.hasOwn(expected,'entries'));
+ for(const[filename,expected]of plan.snapshot){const actual=fresh.get(filename)??null;if(!metadataEqual(expected,actual))fail(`Install target changed: ${filename}`,'ARC_INSTALL_DRIFT');}
+ }catch(error){if(error instanceof InstallError)throw error;throw new InstallError('Install target snapshot changed','ARC_INSTALL_DRIFT',{cause:error});}
+}
+function assertParentNamespace(safeFs,action){
+ let named;try{named=safeFs.openRoot(path.dirname(action.path));if(!sameObjectIdentity(named.stat(),action.parent.stat()))fail('Destination parent namespace changed','ARC_INSTALL_DRIFT');}catch(cause){if(cause instanceof InstallError)throw cause;throw new InstallError('Destination parent cannot be revalidated','ARC_INSTALL_DRIFT',{cause});}finally{named?.close();}
+}
+function openParent(safeFs,absolute,created){
+ const components=path.dirname(absolute).split('/').filter(Boolean);let current=safeFs.openRoot('/'),prefix='';
+ try{for(const name of components){prefix+='/'+name;let stat=exists(current,name);if(!stat){current.mkdir(name,0o700);stat=current.lstat(name);created.push(prefix);}if(typeOf(stat)!==0o040000)fail('Unsafe install parent');const next=current.openDir(name);if(!sameObjectIdentity(stat,next.stat())){next.close();fail('Install parent changed');}current.close();current=next;}return current;}catch(error){current.close();throw error;}
+}
+function treeFromDirectory(directory){
+ const entries=new Map();function walk(handle,prefix=''){for(const name of handle.readDir()){const key=prefix?prefix+'/'+name:name,stat=handle.lstat(name),type=typeOf(stat);
+ if(type===0o040000){const child=handle.openDir(name);try{if(!sameObjectIdentity(stat,child.stat()))fail('Backup directory changed');entries.set(key,{type:'directory',mode:stat.mode,times:metadataOf(stat)});walk(child,key);}finally{child.close();}}
+ else if(type===0o100000){const item=readCheckedFile(handle,name,stat);entries.set(key,{type:'file',mode:stat.mode,bytes:item.bytes,times:item.metadata});}
+ else if(type===0o120000)entries.set(key,{type:'symlink',mode:stat.mode,link:handle.readlink(name),times:metadataOf(stat)});
+ else fail('Special file in backup source');}}
+ walk(directory);return entries;
+}
+function finishDirectory(directory,mode,times){
+ const permissions=Number(mode&0o7777n);directory.chmod(permissions);if(times)directory.setTimes(times);directory.sync();
+ const actual=directory.stat();if(Number(actual.mode&0o7777n)!==permissions||times&&(actual.atimeNs!==times.atimeNs||actual.mtimeNs!==times.mtimeNs))fail('Copied directory metadata verification failed');
+}
+function writeTree(directory,entries){
+ const handles=new Map([['',directory]]);try{for(const[key,entry]of [...entries].sort((a,b)=>a[0].split('/').length-b[0].split('/').length||a[0].localeCompare(b[0]))){const parentKey=path.posix.dirname(key)==='.'?'':path.posix.dirname(key),parent=handles.get(parentKey);if(!parent)fail('Staged entry parent is missing');const name=path.posix.basename(key);
+ if(entry.type==='directory'){parent.mkdir(name,0o700);handles.set(key,parent.openDir(name));}
+ else if(entry.type==='file'){const file=parent.openFile(name,{createExclusive:true,mode:Number(entry.mode&0o7777n)});try{file.writeAll(entry.bytes);file.chmod(Number(entry.mode&0o7777n));if(entry.times)file.setTimes(entry.times);file.sync();}finally{file.close();}}
+ else if(entry.type==='symlink')parent.symlink(entry.link,name);else fail('Unknown staged entry type');}
+ for(const[key,handle]of [...handles].reverse()){if(key){const entry=entries.get(key);finishDirectory(handle,entry.mode,entry.times);}}
+ }finally{for(const[key,handle]of handles)if(key)handle.close();}
+}
+function snapshotEntry(parent,name){const stat=exists(parent,name);if(!stat)return null;const type=typeOf(stat);if(type===0o100000)return readCheckedFile(parent,name,stat).metadata;if(type===0o120000)return{...metadataOf(stat),type:'symlink',link:parent.readlink(name)};if(type===0o040000){const dir=parent.openDir(name);try{if(!sameObjectIdentity(stat,dir.stat()))fail('Entry directory changed');const entries=treeFromDirectory(dir);const hash=createHash('sha256');for(const[k,v]of entries){hash.update(JSON.stringify([k,v.type,...['dev','ino','mode','size','mtimeNs','ctimeNs'].map(field=>String(v.times[field])),v.bytes?.toString('hex')??v.link??null]));}return{...metadataOf(stat),type:'directory',sha256:hash.digest('hex'),children:captureCleanupEntry(parent,name).children};}finally{dir.close();}}fail('Special target entry');}
+function equalMoved(a,b){return a&&b&&['dev','ino','mode','size','mtimeNs','type','sha256','link'].every(k=>a[k]===b[k]);}
+export function applyTransaction(plan,{safeFs,acquired,signal,hooks={},specs:explicitSpecs}){
+ assertPlanSnapshot(plan,{safeFs});const actions=[],areas=[],parents=[],created=[],actionLog=[],byParent=new Map();
+ const cleanAreas=()=>{const paths=[],errors=[];for(const area of areas){const result=cleanupStage(area,{safeFs,hooks:{fault:event=>hooks.fault?.({...event,plan})}});paths.push(...result.residualPaths);if(result.cleanupError)errors.push(result.cleanupError);}return{paths,error:errors.length?Object.assign(new AggregateError(errors,errors.map(error=>error.message).join('; ')),{code:'ARC_INSTALL_CLEANUP',residualPaths:paths}):null};};
+ const event=(phase,details={})=>{actionLog.push({phase,...details});if(signal?.aborted)throw new InstallError('Install interrupted','ARC_INSTALL_CANCELLED');hooks.fault?.({phase,...details,plan});};
+ try{
+  event('before-prepare');
+  const specs=explicitSpecs??plan.uninstallSpecs??[...plan.externalPaths.map(p=>({path:p,tree:acquired.skills.get(path.basename(p))?.entries,rootMetadata:acquired.skills.get(path.basename(p))?.rootMetadata})),{path:plan.target.home+'/skills/arc',tree:composeArcSkillTree(plan.generated.skill,acquired.references)},...[...plan.generated.profiles].map(([name,bytes])=>({path:plan.target.home+'/agents/'+name,bytes})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))];
+  for(const spec of specs){if(!spec.remove&&!spec.tree&&!Buffer.isBuffer(spec.bytes))fail('Missing verified staged data');const parent=openParent(safeFs,spec.path,created);parents.push(parent);const name=path.basename(spec.path);event('before-stage',{path:spec.path});let area=byParent.get(path.dirname(spec.path));if(area&&!sameObjectIdentity(parent.stat(),area.parent.stat()))fail('Reused staging parent identity changed','ARC_INSTALL_DRIFT');if(!area){const stageName='.arc-stage-'+randomUUID();parent.mkdir(stageName,0o700);const stage=parent.openDir(stageName);area={parent,stage,name:stageName,path:path.dirname(spec.path)+'/'+stageName,identity:stage.stat(),expected:new Map()};areas.push(area);byParent.set(path.dirname(spec.path),area);}const stage=area.stage,preparedName='prepared-'+actions.length,previousName='previous-'+actions.length,rollbackName='rollback-installed-'+actions.length;
+   if(spec.remove){}
+   else if(spec.tree){stage.mkdir(preparedName,0o700);const dir=stage.openDir(preparedName);try{writeTree(dir,spec.tree);if(spec.rootMetadata)finishDirectory(dir,spec.rootMetadata.mode,spec.rootMetadata);else dir.sync();}finally{dir.close();}}
+   else{const prior=exists(parent,name),file=stage.openFile(preparedName,{createExclusive:true,mode:prior?Number(prior.mode&0o7777n):0o600});try{file.writeAll(spec.bytes);if(prior){file.chmod(Number(prior.mode&0o7777n));file.setTimes(metadataOf(prior));}file.sync();}finally{file.close();}}
+   if(!spec.remove)area.expected.set(preparedName,snapshotEntry(stage,preparedName));
+   const previous=snapshotEntry(parent,name);
+   actions.push({remove:spec.remove,path:spec.path,parent,name,stage,area,preparedName,previousName,rollbackName,previous,prepared:snapshotEntry(stage,preparedName),moved:false,published:false});event('after-stage',{path:spec.path});
+  }
+  // Directory metadata changed due to our private staging, so recheck actual
+  // managed leaves rather than treating installer-created siblings as drift.
+  const leafSnapshot=new Map([...plan.snapshot].filter(([filename])=>[...plan.managedPaths,...plan.externalPaths].some(root=>filename===root||filename.startsWith(root+'/'))));
+  assertPlanSnapshot({...plan,snapshot:leafSnapshot},{safeFs});
+  for(const action of actions){if(!equalNullable(action.previous,snapshotEntry(action.parent,action.name)))fail('Target changed during staging','ARC_INSTALL_DRIFT');}
+  for(const action of actions){event('before-preserve',{path:action.path});assertParentNamespace(safeFs,action);if(!equalNullable(action.previous,snapshotEntry(action.parent,action.name)))fail('Target changed immediately before replacement','ARC_INSTALL_DRIFT');if(action.previous){action.parent.renameNoReplaceTo(action.name,action.stage,action.previousName);action.moved=true;action.area.expected.set(action.previousName,action.previous);if(!equalMoved(action.previous,snapshotEntry(action.stage,action.previousName)))fail('Moved target identity is uncertain','ARC_INSTALL_RECOVERY');}event('after-preserve',{path:action.path});event('before-publish',{path:action.path});assertParentNamespace(safeFs,action);if(!action.remove){action.stage.renameNoReplaceTo(action.preparedName,action.parent,action.name);action.published=true;action.area.expected.delete(action.preparedName);if(!equalMoved(action.prepared,snapshotEntry(action.parent,action.name)))fail('Published target identity is uncertain','ARC_INSTALL_RECOVERY');action.installed=snapshotEntry(action.parent,action.name);}event('after-publish',{path:action.path});assertParentNamespace(safeFs,action);action.parent.sync();}
+  for(const action of actions)assertParentNamespace(safeFs,action);
+  const cleaned=cleanAreas();return{actionLog,installedSnapshot:new Map(actions.map(a=>[a.path,a.installed])),residualPaths:cleaned.paths,cleanupError:cleaned.error};
+ }catch(cause){const recovery=[],detachedParents=new Set();for(const action of [...actions].reverse()){try{hooks.fault?.({phase:'before-rollback',path:action.path,plan});if(action.published){if(!equalMoved(action.installed??action.prepared,snapshotEntry(action.parent,action.name)))fail('Installed target changed before rollback');action.parent.renameNoReplaceTo(action.name,action.stage,action.rollbackName);action.area.expected.set(action.rollbackName,action.installed??action.prepared);if(!equalMoved(action.installed??action.prepared,snapshotEntry(action.stage,action.rollbackName)))fail('Rollback source changed');}if(action.moved||action.published)try{assertParentNamespace(safeFs,action);}catch(error){detachedParents.add(path.dirname(action.path));throw error;}if(action.moved){if(!equalMoved(action.previous,snapshotEntry(action.stage,action.previousName)))fail('Previous entry changed');action.stage.renameNoReplaceTo(action.previousName,action.parent,action.name);action.area.expected.delete(action.previousName);try{assertParentNamespace(safeFs,action);}catch(error){detachedParents.add(path.dirname(action.path));if(!equalMoved(action.previous,snapshotEntry(action.parent,action.name)))throw error;action.parent.renameNoReplaceTo(action.name,action.stage,action.previousName);action.area.expected.set(action.previousName,action.previous);throw error;}}hooks.fault?.({phase:'after-rollback',path:action.path,plan});}catch{recovery.push(action.path,action.area.path);}}
+  const cleaned=recovery.length?{paths:areas.map(area=>area.path),error:null}:cleanAreas();
+  const details={cause,actionLog,detachedParents:[...detachedParents],residualPaths:[...new Set([...recovery,...cleaned.paths])],cleanupError:cleaned.error,rollback:recovery.length?'failed':'restored'};
+  if(recovery.length)throw new InstallError(detachedParents.size?'Rollback namespace unavailable; reported stage paths are last-known locations':'Rollback conflict; preserve reported residual paths','ARC_INSTALL_RECOVERY',details);
+  if(cleaned.error)throw new InstallError('Rollback restored targets; '+cleaned.error.message,'ARC_INSTALL_CLEANUP',details);
+  throw new InstallError(cause.message,cause.code==='ARC_INSTALL_CANCELLED'?'ARC_INSTALL_CANCELLED':cause.code==='ARC_INSTALL_DRIFT'?'ARC_INSTALL_DRIFT':'ARC_INSTALL_FAILED',details);
+ }finally{for(const area of areas)area.stage.close();for(const parent of parents)parent.close();}
+}
+function equalNullable(a,b){return a===null||b===null?a===b:equalMoved(a,b)&&a.ctimeNs===b.ctimeNs;}
+export function applyUninstallTransaction(plan,options){
+ if(!plan.removals.length&&!plan.globalChanges.length)return{residualPaths:[],cleanupError:null,installedSnapshot:new Map(),actionLog:[]};
+ return applyTransaction({...plan,uninstallSpecs:[...plan.removals.map(path=>({path,remove:true})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))]},options);
+}

package/lib/installer/uninstall.mjs

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import {inspectPath,sameIdentity,TargetConfigurationError} from './targets.mjs';
+import {SKILLS,snapshotSkill} from './superpowers.mjs';
+import {validatePlanSet} from './plan.mjs';
+import {removeManagedBlock} from './global-config.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);}
+ const linkedSkills=new Set(),arc=managedPaths[0];
+ for(const[filename,entry]of snapshot){if(entry?.type!=='symlink')continue;
+  const relative=path.relative(arc,filename),parts=relative.split('/'),skill=parts[2];
+  if(parts[0]!=='references'||parts[1]!=='superpowers'||!SKILLS.includes(skill)||parts.length<4||!entry.link||path.isAbsolute(entry.link)||entry.link.includes('\\')||entry.link.includes('\0'))throw new TargetConfigurationError('Unsafe ARC removal link');
+  linkedSkills.add(skill);
+ }
+ 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.']};
+}
+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;
+ 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};
+
+ 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=applyUninstallTransaction(plan,{safeFs,signal,hooks});results[i]={...results[i],status:'uninstalled',residualPaths:[...results[i].residualPaths,...applied.residualPaths],error:applied.cleanupError??null};if(applied.cleanupError)break;}
+  catch(error){results[i]={...results[i],status:'failed',rollback:error.rollback??'not-needed',residualPaths:[...results[i].residualPaths,...(error.residualPaths??[])],error};return{results,interrupted:Boolean(signal?.aborted)};}
+ }
+ return{results,interrupted:false};
+}

package/lib/limits.mjs

@@ -0,0 +1,13 @@
+export function parsePositiveLimit(raw,label='limit') {
+ if(typeof raw!=='string'||! /^[0-9]+$/.test(raw.trim())||!Number.isSafeInteger(Number(raw.trim()))||Number(raw.trim())<1)throw new Error(`${label} must be a positive safe ASCII decimal integer`);
+ return Number(raw.trim());
+}
+export function resolveLimits({existing=null,overrides={}}={}) {
+ const result={version:1};
+ for(const [key,fallback] of [['max_total_subagents',100],['max_concurrent_subagents',5]]) {
+  const value=overrides[key]??existing?.[key]??fallback;
+  if(typeof value!=='number'||!Number.isSafeInteger(value)||value<1)throw new Error(`Invalid ${key}`);
+  result[key]=value;
+ }
+ return result;
+}

package/lib/models/config.mjs

@@ -0,0 +1,58 @@
+import { parse, stringify } from '../../vendor/toml/dist/index.js';
+export const ROLES = Object.freeze(['arc_scouter', 'arc_planner', 'arc_coder', 'arc_qa', 'arc_reviewer']);
+export class ModelValidationError extends Error {
+  constructor(message, options) { super(message, options); this.name = 'ModelValidationError'; this.code = 'ARC_MODEL_VALIDATION'; }
+}
+export function fail(message) { throw new ModelValidationError(message); }
+export function platformOf(config) {
+  if (config?.platform === 'codex' && config.version === 1) return 'codex';
+  if (config?.platform === 'claude' && config.version === 1) return 'claude';
+  fail('Unsupported model schema version');
+}
+export function effortField(platform) {
+  if (platform === 'codex') return 'model_reasoning_effort';
+  if (platform === 'claude') return 'effort';
+  fail('Unknown model platform');
+}
+export function exactKeys(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) fail(`${label} must contain exactly ${keys.join(', ')}`);
+}
+function string(value, label) {
+  if (typeof value !== 'string' || !value || value !== value.trim() || /[\p{Cc}\u2028\u2029]/u.test(value)) fail(`${label} must be a nonempty string without whitespace or control characters`);
+}
+export function validateRoles(roles, platform) {
+  const effort = effortField(platform); exactKeys(roles, ROLES, 'roles');
+  for (const [role, fields] of Object.entries(roles)) {
+    exactKeys(fields, ['model', effort], role); string(fields.model, `${role}.model`); string(fields[effort], `${role}.${effort}`);
+    if (platform === 'claude' && (!/^[A-Za-z0-9][A-Za-z0-9._:/@+\-]*$/.test(fields.model) || !['low', 'medium', 'high', 'xhigh', 'max'].includes(fields.effort))) fail(`${role}: unsupported Claude model identifier or effort`);
+  }
+  return structuredClone(roles);
+}
+export const PRESETS = Object.freeze(['economy', 'balanced', 'smart']);
+export function validateModelConfig(config) {
+  exactKeys(config, ['platform', 'version', 'preset', 'roles'], 'model config'); const platform = platformOf(config);
+  if (!PRESETS.includes(config.preset)) fail('Unsupported performance preset');
+  exactKeys(config.roles, ROLES, 'roles');
+  for (const role of ROLES) exactKeys(config.roles[role], PRESETS, `roles.${role}`);
+  for (const preset of PRESETS) validateRoles(Object.fromEntries(ROLES.map(role => [role, config.roles[role][preset]])), platform);
+  return structuredClone(config);
+}
+export function resolveModelSettings(config) {
+  const validated = validateModelConfig(config);
+  return { platform: validated.platform, roles: Object.fromEntries(ROLES.map(role => [role, validated.roles[role][validated.preset]])) };
+}
+export function parseToml(text) {
+  try { return parse(typeof text === 'string' ? text : new TextDecoder('utf-8', { fatal: true }).decode(text), { integersAsBigInt: true }); }
+  catch (cause) { throw new ModelValidationError(`Invalid TOML: ${cause.message}`, { cause }); }
+}
+export function loadModelConfig(text, platform) {
+  effortField(platform); const config = parseToml(text); exactKeys(config, ['version', 'preset', 'roles'], 'model file (reinstall or update legacy role-only settings)');
+  if (config.version !== 1n) fail(`Expected ${platform} integer schema version 1; reinstall or update models.toml`);
+  return validateModelConfig({ platform, version: 1, preset: config.preset, roles: config.roles });
+}
+export function serializeModelConfig(config) { const { version, preset, roles } = validateModelConfig(config); return stringify({ version, preset, roles }); }
+export function applyPreset(config, preset) {
+  const validated = validateModelConfig(config);
+  if (!PRESETS.includes(preset)) fail('Unsupported performance preset');
+  return { ...validated, preset };
+}

package/lib/models/index.mjs

@@ -0,0 +1,2 @@
+export { loadModelConfig, applyPreset, serializeModelConfig, resolveModelSettings, ModelValidationError } from './config.mjs';
+export { renderProfiles } from './profiles.mjs';

package/lib/models/profiles.mjs

@@ -0,0 +1,111 @@
+import {hookFrontmatter,validateClaudeHookCommand} from '../policy/claude-hook.mjs';
+import { parseToml, exactKeys, validateRoles, effortField, ROLES, fail } from './config.mjs';
+const tools = {
+  arc_scouter: ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch'],
+  arc_planner: ['Read', 'Grep', 'Glob'],
+  arc_coder: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
+  arc_qa: ['Read', 'Grep', 'Glob', 'Bash'],
+  arc_reviewer: ['Read', 'Grep', 'Glob'],
+};
+function decode(buffer) {
+  if (!Buffer.isBuffer(buffer)) fail('Profile input must be a verified Buffer');
+  if (buffer.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf]))) fail('Profile must not start with a UTF-8 BOM');
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(buffer); }
+  catch { fail('Profile must contain valid UTF-8'); }
+}
+function linesOf(text) { return text.match(/[^\n]*\n|[^\n]+$/g) ?? []; }
+// Track TOML strings and value nesting so instructions, inline tables and array
+// continuations cannot be mistaken for root assignments. The parser validates
+// syntax independently; the scanner only locates narrowly editable lines.
+function locateRootFields(lines) {
+  let quote = null, depth = 0, root = true, firstTable = null;
+  const fields = new Map();
+  for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
+    const line = lines[lineNumber];
+    if (quote === null && depth === 0 && root) {
+      if (/^[ \t]*\[/.test(line)) { root = false; firstTable = lineNumber; }
+      else {
+        const assignment = /^[ \t]*((?:[A-Za-z0-9_-]+)|(?:"(?:\\.|[^"\\])*"|'[^']*'))[ \t]*=/.exec(line);
+        if (assignment) {
+          const rawKey = assignment[1]; const parsed = parseToml(`${rawKey} = ""`); const key = Object.keys(parsed)[0];
+          if (['model', 'model_reasoning_effort'].includes(key)) {
+            if (![key, `"${key}"`, `'${key}'`].includes(rawKey) || fields.has(key)) fail('Unsupported root model assignment');
+            fields.set(key, lineNumber);
+          }
+        }
+      }
+    }
+    for (let i = 0; i < line.length;) {
+      if (quote !== null) {
+        if (quote.startsWith('"') && line[i] === '\\') { i += 2; continue; }
+        if (line.startsWith(quote, i)) {
+          if (quote.length === 3) { const char = quote[0]; let end = i + 3; while (line[end] === char) end++; i = end; }
+          else i++;
+          quote = null;
+        } else i++;
+      } else if (line[i] === '#') break;
+      else if (line[i] === '"' || line[i] === "'") { quote = line.startsWith(line[i].repeat(3), i) ? line[i].repeat(3) : line[i]; i += quote.length; }
+      else { if ('[{'.includes(line[i])) depth++; else if (']}'.includes(line[i])) depth--; i++; }
+    }
+  }
+  return { fields, firstTable };
+}
+function renderCodex(text, role, settings) {
+  const parsed = parseToml(text); if (parsed.name !== role) fail('Codex profile name does not match role filename');
+  const lines = linesOf(text), { fields, firstTable } = locateRootFields(lines);
+  const missing = [];
+  for (const key of ['model', 'model_reasoning_effort']) {
+    if (!Object.hasOwn(parsed, key)) { if (fields.has(key)) fail('Ambiguous root model field'); missing.push(key); continue; }
+    if (typeof parsed[key] !== 'string' || !fields.has(key)) fail('Root model field must be an editable one-line quoted string');
+    const index = fields.get(key);
+    const match = /^([ \t]*(?:model|model_reasoning_effort|"model"|"model_reasoning_effort"|'model'|'model_reasoning_effort')[ \t]*=[ \t]*)("(?:\\.|[^"\\\r\n])*"|'[^'\r\n]*')([ \t]*(?:#[^\r\n]*)?)(\r?\n)?$/.exec(lines[index]);
+    if (!match) fail('Root model field must be an editable one-line quoted string');
+    if (parsed[key] !== settings[key]) lines[index] = match[1] + JSON.stringify(settings[key]) + match[3] + (match[4] ?? '');
+  }
+  let output = lines.join('');
+  if (missing.length) {
+    const eol = /\r?\n/.exec(text)?.[0] ?? '\n';
+    let addition = missing.map(key => `${key} = ${JSON.stringify(settings[key])}${eol}`).join('');
+    const offset = firstTable === null ? output.length : lines.slice(0, firstTable).join('').length;
+    if (offset && !/[\r\n]$/.test(output.slice(0, offset))) addition = eol + addition;
+    output = output.slice(0, offset) + addition + output.slice(offset);
+  }
+  const checked = parseToml(output);
+  if (checked.name !== role || Object.entries(settings).some(([key, value]) => checked[key] !== value)) fail('Rendered Codex profile does not match settings');
+  return Buffer.from(output);
+}
+function renderClaude(text, role, settings) {
+  const lines = linesOf(text); if (lines[0]?.replace(/\r?\n$/, '') !== '---') fail('Missing opening Claude frontmatter');
+  const fields = {}, indices = {}; let current, closed = false;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].replace(/\r?\n$/, ''); if (line === '---') { closed = true; break; }
+    if(line==='hooks:') {
+      if(Object.hasOwn(fields,'hooks'))fail('Duplicate Claude hooks');
+      const raw=lines.slice(i,i+6).map(x=>x.replace(/\r?\n$/,''));
+      try {const command=JSON.parse(raw[5]?.replace(/^          command: /,''));validateClaudeHookCommand(command);if(raw.join('\n')!==hookFrontmatter(command))throw Error('Unsupported hooks');fields.hooks=command;}catch {fail('Unsupported managed Claude hooks');}
+      indices.hooks=i;i+=5;current='hooks';continue;
+    }
+    const item = /^  - ([A-Za-z][A-Za-z0-9]*)$/.exec(line);
+    if (item && current === 'tools') { fields.tools.push(item[1]); continue; }
+    const match = /^([a-z][a-zA-Z0-9_-]*):(?: (.+))?$/.exec(line);
+    if (!match || Object.hasOwn(fields, match[1])) fail('Malformed or duplicate Claude frontmatter');
+    const [, key, value] = match; current = key; indices[key] = i;
+    if (key === 'tools') { if (value !== undefined) fail('Claude tools must be an explicit list'); fields.tools = []; }
+    else { if (!value || value !== value.trim() || /[\t\x00{}\[\]#&*!|>"']/.test(value) || value.includes(': ')) fail('Claude frontmatter requires plain scalar values'); fields[key] = value; }
+  }
+  if (!closed || !['name', 'description', 'model', 'effort', 'tools', 'hooks'].every(key => Object.hasOwn(fields, key)) || fields.name !== role.replace('_', '-') || JSON.stringify(fields.tools) !== JSON.stringify(tools[role])) fail('Invalid Claude profile identity or role tools');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:/@+\-]*$/.test(fields.model) || !['low','medium','high','xhigh','max'].includes(fields.effort)) fail('Invalid Claude profile model or effort');
+  for (const key of ['model', 'effort']) { const index = indices[key], eol = /\r?\n$/.exec(lines[index])?.[0] ?? ''; lines[index] = `${key}: ${settings[key]}${eol}`; }
+  return Buffer.from(lines.join(''));
+}
+export function renderProfiles(profileBuffers, config) {
+  exactKeys(config, ['platform', 'roles'], 'effective model settings');
+  const platform = config.platform, validated = {roles: validateRoles(config.roles, platform)}, extension = platform === 'codex' ? 'toml' : 'md';
+  if (profileBuffers instanceof Map) profileBuffers = Object.fromEntries(profileBuffers);
+  const names = ROLES.map(role => `${role.replace('_', '-')}.${extension}`);
+  if (!profileBuffers || Object.keys(profileBuffers).length !== names.length || names.some(name => !Object.hasOwn(profileBuffers, name))) fail('Profile set must contain exactly the five platform role files');
+  return new Map(names.map((name, index) => {
+    const role = ROLES[index], text = decode(profileBuffers[name]);
+    return [name, platform === 'codex' ? renderCodex(text, role, validated.roles[role]) : renderClaude(text, role, validated.roles[role])];
+  }));
+}

package/lib/policy/claude-hook.mjs

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+// Only this fixed bootstrap is executed. The separately encoded path is data.
+const bootstrap="import(Buffer.from(process.argv[1],'base64').toString('utf8')).then(module=>module.runHook()).catch(()=>{process.stderr.write('ARC Git guard failed to load\\n');process.exitCode=2;});";
+const prefix=`node -e "eval(Buffer.from('${Buffer.from(bootstrap).toString('base64')}','base64').toString('utf8'))" `;
+export function buildClaudeHookCommand(scriptPath) {
+  if(typeof scriptPath!=='string'||/[\x00-\x1f]/.test(scriptPath)||!path.isAbsolute(scriptPath)&&!path.win32.isAbsolute(scriptPath))throw Error('Claude hook requires an absolute script path');
+  let url;
+  if(path.win32.isAbsolute(scriptPath)&&/^[A-Za-z]:[\\/]/.test(scriptPath)) {
+    const normalized=path.win32.normalize(scriptPath).replaceAll('\\','/');url='file:///'+normalized.split('/').map((part,i)=>i===0?part:encodeURIComponent(part)).join('/');
+  } else {if(!path.isAbsolute(scriptPath)||path.normalize(scriptPath)!==scriptPath)throw Error('Invalid absolute hook path');url=pathToFileURL(scriptPath).href;}
+  return prefix+`"${Buffer.from(url).toString('base64')}"`;
+}
+export const templateHookCommand=buildClaudeHookCommand('/__ARC_INSTALLED_SKILL__/hooks/role-git-guard.mjs');
+export function validateClaudeHookCommand(command) {
+  if(typeof command!=='string'||!command.startsWith(prefix))throw Error('Unmanaged Claude hook command');
+  const encoded=/^"([A-Za-z0-9+/]+={0,2})"$/.exec(command.slice(prefix.length));if(!encoded)throw Error('Invalid Claude hook command');
+  const decoded=Buffer.from(encoded[1],'base64');if(decoded.toString('base64')!==encoded[1])throw Error('Invalid hook path encoding');
+  const url=new URL(decoded.toString('utf8'));if(url.protocol!=='file:'||url.host||!url.pathname.endsWith('/hooks/role-git-guard.mjs')||url.search||url.hash)throw Error('Invalid hook file URL');
+  return command;
+}
+export function hookFrontmatter(command=templateHookCommand,eol='\n') {
+  validateClaudeHookCommand(command);
+  return ['hooks:','  PreToolUse:','    - matcher: Bash','      hooks:','        - type: command',`          command: ${JSON.stringify(command)}`].join(eol);
+}
+export function installClaudeHook(bytes,skillPath) {
+  const text=bytes.toString('utf8'),eol=/\r?\n/.exec(text)?.[0]??'\n';
+  const pattern=/^hooks:\r?\n  PreToolUse:\r?\n    - matcher: Bash\r?\n      hooks:\r?\n        - type: command\r?\n          command: ("[^\r\n]+")(?=\r?$)/gm;
+  const matches=[...text.matchAll(pattern)];if(matches.length!==1)throw Error('Missing or duplicate managed Claude hook');
+  validateClaudeHookCommand(JSON.parse(matches[0][1]));
+  return Buffer.from(text.replace(pattern,()=>hookFrontmatter(buildClaudeHookCommand(path.join(skillPath,'hooks/role-git-guard.mjs')),eol)));
+}
+export function renderSourceClaudeHook(text) {
+  const eol=/\r?\n/.exec(text)?.[0]??'\n';
+  const frontmatter=/^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/.exec(text);
+  if(!frontmatter)throw Error('Missing Claude frontmatter for hook generation');
+  if(/^hooks:/m.test(frontmatter[1]))return installClaudeHook(Buffer.from(text),'/__ARC_INSTALLED_SKILL__').toString('utf8');
+  const closing=frontmatter[0].lastIndexOf(eol+'---');
+  return text.slice(0,closing)+eol+hookFrontmatter(templateHookCommand,eol)+text.slice(closing);
+}