@yunhozz/arc 0.2.4 → 0.2.6

package/codex/skill/runtime/target-preparation.mjs

@@ -0,0 +1,110 @@
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const text=value=>typeof value==='string'&&value.length>0;
+const relative=value=>text(value)&&!/[\\\x00\r\n:]/.test(value)&&!value.startsWith('/')&&!value.split('/').some(part=>!part||part==='.'||part==='..');
+
+export async function readTargetPreparationEvidence({state,targetIntent,destination,observe=observeCooperativeTarget,readChanges=readCooperativeChanges,gitRunner}={}){
+ const sourceTarget=await observe(state.target.realpath);
+ const snapshot=await readChanges({state:{...state,target:sourceTarget},...(gitRunner?{gitRunner}:{})});
+ const stage=state.plannerLedger?.stages?.find(s=>s.id===targetIntent?.firstStageId);
+ const source={target:sourceTarget,fingerprint:snapshot.final,snapshot:snapshot.transitionSnapshot,preserved:!!targetIntent?.sourceSnapshot&&same(snapshot.transitionSnapshot,targetIntent.sourceSnapshot),inputVersion:stage?.inputVersion,candidate:targetIntent?.candidate,base:targetIntent?.base};
+ if(!destination)return {source};
+ const target=await observe(destination.realpath),tasks=state.tasks.map(task=>({...task,paths:task.paths.map(p=>{if(!within(state.target.realpath,p))throw Error('Task path escapes source');return path.join(target.realpath,path.relative(state.target.realpath,p));})})),destinationSnapshot=await readChanges({state:{...state,target,tasks},...(gitRunner?{gitRunner}:{})}),result={target,snapshot:destinationSnapshot.transitionSnapshot};
+ source.preserved=source.preserved&&same(destinationSnapshot.transitionSnapshot,targetIntent.sourceSnapshot);
+ if(target.realpath!==state.target.realpath){
+  const query=await (gitRunner??defaultRunner)({cwd:sourceTarget.realpath,args:['worktree','list','--porcelain','-z']});
+  if(query?.status!==0||query.error||!Buffer.isBuffer(query.stdout))throw Error('Worktree registration query failed');
+  const raw=new TextDecoder('utf-8',{fatal:true}).decode(query.stdout);if(raw&&!raw.endsWith('\0\0'))throw Error('Incomplete worktree registration');
+  const entries=raw?raw.slice(0,-2).split('\0\0').map(entry=>entry.split('\0')):[];
+  result.registered=entries.some(entry=>entry.includes('worktree '+target.realpath)&&entry.includes('HEAD '+target.head)&&entry.includes('branch refs/heads/'+target.branch));
+  const attachment=state.records?.find(r=>r.kind==='note'&&r.messageRef===destination.attachmentRef&&r.targetVersion===state.targetVersion&&r.source==='operator-attested'&&r.data?.type==='worktree-attachment'&&r.data.realpath===target.realpath&&r.data.gitDir===target.gitDir&&r.data.gitCommonDir===target.gitCommonDir);
+  if(attachment)result.attachmentRef=attachment.messageRef;
+ }
+ if(destination.path!==undefined){
+  if(!relative(destination.path))throw Error('Invalid destination path');
+  const filename=path.join(target.realpath,...destination.path.split('/'));
+  if(!within(target.realpath,filename))throw Error('Destination path escapes workspace');
+  await inspectPath(filename);const handle=await fs.open(filename,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  let bytes,after;
+  try{const before=await handle.stat();if(!before.isFile())throw Error('Destination must be a regular file');bytes=await handle.readFile();after=await handle.stat();const named=await fs.lstat(filename);if(before.dev!==after.dev||before.ino!==after.ino||before.size!==after.size||before.mtimeMs!==after.mtimeMs||before.mode!==after.mode||after.dev!==named.dev||after.ino!==named.ino)throw Error('Destination changed while reading');}finally{await handle.close();}
+  await inspectPath(filename);if(!within(target.realpath,await fs.realpath(filename)))throw Error('Destination path escapes workspace');
+  result.document={path:destination.path,hash:'sha256:'+createHash('sha256').update(bytes).digest('hex'),mode:0o100000|(after.mode&0o777),verification:{status:'verified',source:'local-bytes'}};
+ }
+ return {source,destination:result};
+}
+
+export function validateTargetPreparationRecord(kind,data){
+ if(!data||data.type!==kind||!['intent','checkpoint','transition','destination'].includes(kind))throw Error('Invalid target preparation type');
+ if(kind==='intent'&&(!text(data.id)||!text(data.workflowId)||!data.sourceTarget||!Number.isSafeInteger(data.sourceTargetVersion)||!text(data.selectionRef)||!['current','branch','worktree'].includes(data.kind)||!text(data.candidate)||!text(data.base)||!text(data.firstStageId)||!Array.isArray(data.documents)||!data.documents.length||data.documents.some(d=>!['spec','plan'].includes(d.kind)||!relative(d.path))||new Set(data.documents.map(d=>d.kind)).size!==data.documents.length))throw Error('Invalid target preparation intent');
+ if(kind==='intent'&&(!Number.isSafeInteger(data.sourceTargetVersion)||data.sourceTargetVersion<1||!['realpath','gitCommonDir','gitDir'].every(k=>typeof data.sourceTarget[k]==='string'&&path.isAbsolute(data.sourceTarget[k])&&path.normalize(data.sourceTarget[k])===data.sourceTarget[k])||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(data.sourceTarget.head)||!(data.sourceTarget.branch===null||text(data.sourceTarget.branch))||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(data.base)||new Set(data.documents.map(d=>d.path)).size!==data.documents.length))throw Error('Invalid target preparation intent identity');
+ if(kind==='checkpoint'&&(!text(data.intentId)||!text(data.stageId)||!text(data.resultRef)||!text(data.selfReviewRef)))throw Error('Invalid target preparation checkpoint');
+ if(kind==='transition'&&(!text(data.intentId)||!text(data.checkpointRef)||!Number.isSafeInteger(data.expectedRevision)||data.expectedRevision<0))throw Error('Invalid target preparation transition');
+ if(kind==='destination'&&(!text(data.intentId)||!text(data.transitionRef)||!text(data.stageId)||!text(data.resultRef)||!text(data.selfReviewRef)||!relative(data.path)||!/^sha256:[a-f0-9]{64}$/.test(data.hash)||![0o100644,0o100755].includes(data.mode)||!text(data.reviewRef)||!text(data.approvalRef)||!Number.isSafeInteger(data.targetVersion)||data.targetVersion<1))throw Error('Invalid target preparation destination');
+ return data;
+}
+
+export function evaluateTargetPreparation({state,request,evidence}={}){
+ const hold=reason=>({decision:'hold',ruleIds:['cooperative.target-preparation'],reason});
+ try{validateTargetPreparationRecord(request?.type,request);}catch{return hold('Invalid target preparation record');}
+ if(request.type==='intent'){
+  if(state.targetIntents?.some(intent=>!state.targetTransitions?.some(transition=>transition.intentId===intent.id)))return hold('Existing target preparation intent is still active');
+  const approval=state.records?.find(r=>r.kind==='approval'&&r.messageRef===request.approvalRef&&r.source==='operator-attested'&&r.actor?.role==='orchestrator'&&r.targetVersion===state.targetVersion&&r.scopeVersion===state.scopeVersion);
+  const approved=approval?.data?.targetPreparation;
+  if(!['Bounded','Architectural'].includes(request.depth)||(request.depth==='Architectural'&&(!request.documents.some(d=>d.kind==='spec')||!request.documents.some(d=>d.kind==='plan'))))return hold('Approved depth requires its complete document set');
+  if(!text(request.approvalRef)||!text(request.depth)||['depth','selectionRef','kind','candidate','base','workflowId','firstStageId','sourceTargetVersion'].some(k=>approved?.[k]!==request[k])||!same(approved?.sourceTarget,request.sourceTarget)||!same(approved?.documents,request.documents)||request.workflowId!==state.workflowId||request.sourceTargetVersion!==state.targetVersion||!same(request.sourceTarget,state.target)||!same(evidence?.source?.target,state.target)||!text(evidence?.source?.fingerprint)||!state.selections?.some(s=>s.messageRef===request.selectionRef&&s.targetVersion===state.targetVersion)||state.targetIntents?.some(i=>i.id===request.id)||request.base!==state.target.head)return hold('Current approval, document set, source, explicit choice and preservation snapshot required');
+  return {decision:'allow',ruleIds:['cooperative.target-preparation'],proposedTransition:{intent:{...structuredClone(request),scopeVersion:state.scopeVersion,sourceFingerprint:evidence.source.fingerprint,...(evidence.source.snapshot?{sourceSnapshot:structuredClone(evidence.source.snapshot)}:{}),source:'operator-attested'}}};
+ }
+ if(request.type==='transition'){
+  const intent=state?.targetIntents?.find(i=>i.id===request.intentId),checkpoint=state?.targetCheckpoints?.find(c=>c.intentId===request.intentId&&c.messageRef===request.checkpointRef);
+  const source=evidence?.source,destination=evidence?.destination?.target;
+  if(state.plannerLedger?.stages?.some(s=>s.pending||s.calls?.some(c=>['reserved','unknown'].includes(c.status))))return hold('Pending or unknown Planner execution');
+  const stage=state.plannerLedger?.stages?.find(s=>s.id===intent?.firstStageId),result=stage?.result,chat=result?.chatDraft;
+  if(!intent||intent.scopeVersion!==state.scopeVersion||stage?.scopeVersion!==state.scopeVersion||stage.targetVersion!==state.targetVersion||!state.records?.some(r=>r.kind==='approval'&&r.messageRef===intent.approvalRef&&r.scopeVersion===state.scopeVersion&&r.targetVersion===state.targetVersion&&r.actor?.role==='orchestrator'&&r.source==='operator-attested'))return hold('Current scope approval and source stage required');
+  if(!stage||stage.targetIntentId!==intent.id||checkpoint?.stageId!==stage.id||checkpoint.resultRef!==result?.ref||checkpoint.selfReviewRef!==chat?.selfReviewRef||checkpoint.candidate!==intent.candidate||checkpoint.base!==intent.base||checkpoint.inputVersion!==stage.inputVersion||result.status!=='succeeded'||chat?.intentId!==intent.id||chat.complete!==true||!text(chat.draftRef)||!stage.calls?.some(c=>c.requestId===result.requestId&&c.status==='succeeded'))return hold('Checkpoint source result changed');
+  if(!intent||!checkpoint||state.targetTransitions?.some(t=>t.intentId===intent.id)||request.expectedRevision!==state.revision||intent.sourceTargetVersion!==state.targetVersion||!same(intent.sourceTarget,state.target)||!same(evidence?.versions,state.versions)||!source?.preserved||!destination||source.target?.realpath!==state.target.realpath||source.target?.gitCommonDir!==state.target.gitCommonDir||source.target?.gitDir!==state.target.gitDir||destination.gitCommonDir!==state.target.gitCommonDir||state.unresolved?.some(u=>!u.resolvedBy)||state.assignments?.some(a=>a.status==='active')||state.intents?.some(i=>['prepared','unknown','mismatch'].includes(i.status)))return hold('Current checkpoint, preservation and independent target evidence required');
+  if(intent.kind==='branch'&&!(destination.realpath===state.target.realpath&&destination.gitDir===state.target.gitDir&&destination.branch===intent.candidate&&destination.head===intent.base&&source.target.branch===intent.candidate&&source.target.head===intent.base))return hold('Branch target differs from intent');
+  if(intent.kind==='current'&&(!same(destination,state.target)||destination.branch!==intent.candidate||destination.head!==intent.base))return hold('Current target changed');
+  if(intent.kind==='worktree'&&state.tasks?.some(task=>task.paths?.length))return hold('Worktree transition with source-bound task paths is unsupported');
+  if(intent.kind==='worktree'&&!(same(source.target,state.target)&&destination.realpath!==state.target.realpath&&destination.gitDir!==state.target.gitDir&&destination.branch===intent.candidate&&destination.head===intent.base&&evidence.destination.registered===true&&text(evidence.destination.attachmentRef)&&state.records?.some(r=>r.kind==='note'&&r.messageRef===evidence.destination.attachmentRef&&r.targetVersion===state.targetVersion&&r.source==='operator-attested'&&r.data?.type==='worktree-attachment'&&r.data.realpath===destination.realpath&&r.data.gitDir===destination.gitDir&&r.data.gitCommonDir===destination.gitCommonDir)))return hold('Worktree registration and attachment required');
+  return {decision:'allow',ruleIds:['cooperative.target-preparation'],proposedTransition:{target:structuredClone(destination),intentId:intent.id,checkpointRef:request.checkpointRef,sourceTargetVersion:state.targetVersion,expectedRevision:state.revision,validation:{request:structuredClone(request),evidence:structuredClone(evidence)}}};
+ }
+ if(request.type==='destination'){
+  const intent=state.targetIntents?.find(i=>i.id===request.intentId),document=intent?.documents?.find(d=>d.path===request.path),transition=state.targetTransitions?.find(t=>t.intentId===request.intentId&&t.messageRef===request.transitionRef&&t.targetVersion===state.targetVersion),checkpoint=state.targetCheckpoints?.find(c=>c.intentId===request.intentId&&c.messageRef===transition?.checkpointRef),stage=state.plannerLedger?.stages?.find(s=>s.id===request.stageId),chat=stage?.result?.chatDraft,observed=evidence?.destination?.document;
+  const review=state.records?.find(r=>r.kind==='planner-review'&&r.messageRef===request.reviewRef&&r.scopeVersion===state.scopeVersion&&r.targetVersion===state.targetVersion&&r.source==='operator-attested'),approval=state.records?.find(r=>r.kind==='approval'&&r.messageRef===request.approvalRef&&r.scopeVersion===state.scopeVersion&&r.targetVersion===state.targetVersion&&r.source==='operator-attested');
+  if(!intent||!document||intent.firstStageId!==request.stageId||!transition||!same(transition.target,state.target)||request.targetVersion!==state.targetVersion||!checkpoint||checkpoint.stageId!==request.stageId||checkpoint.resultRef!==request.resultRef||checkpoint.selfReviewRef!==request.selfReviewRef||stage?.targetIntentId!==intent.id||stage.result?.ref!==request.resultRef||stage.result.status!=='succeeded'||chat?.intentId!==intent.id||chat.complete!==true||chat.selfReviewRef!==request.selfReviewRef||!same(evidence?.destination?.target,state.target)||observed?.verification?.status!=='verified'||observed.verification.source!=='local-bytes'||observed.path!==request.path||observed.hash!==request.hash||observed.mode!==request.mode)return hold('Current transition, source attestation and observed destination bytes required');
+  if(stage.scopeVersion!==state.scopeVersion||review?.data?.resultRef!==request.resultRef||review.data.full!==true||review.data.complete!==true||review.data.hash!==request.hash||!Array.isArray(stage.criteria)||!Array.isArray(review.data.criteria)||review.data.criteria.length!==stage.criteria.length||new Set(review.data.criteria.map(c=>c.id)).size!==stage.criteria.length||review.data.criteria.some(c=>!stage.criteria.some(s=>s.id===c.id)||c.status!=='resolved'||!text(c.judgmentRef))||approval?.data?.kind!==document.kind||approval.data.contentHash!==request.hash||![request.path,path.join(state.target.realpath,request.path)].includes(approval.data.path))return hold('Current full review and document approval required');
+  return {decision:'allow',ruleIds:['cooperative.target-preparation'],proposedTransition:{destination:{...structuredClone(request),scopeVersion:state.scopeVersion,sourceLink:'operator-attested',verification:{status:'verified',source:'local-bytes'}}}};
+ }
+ if(request?.type!=='checkpoint')return hold('Unsupported target preparation request');
+ const intent=state?.targetIntents?.find(i=>i.id===request.intentId);
+ const stage=state?.plannerLedger?.stages?.find(s=>s.id===request.stageId);
+ const source=evidence?.source,result=stage?.result,chat=result?.chatDraft;
+ if(!intent||intent.scopeVersion!==state.scopeVersion||stage?.scopeVersion!==state.scopeVersion||stage.targetVersion!==state.targetVersion||!state.records?.some(r=>r.kind==='approval'&&r.messageRef===intent.approvalRef&&r.scopeVersion===state.scopeVersion&&r.targetVersion===state.targetVersion&&r.actor?.role==='orchestrator'&&r.source==='operator-attested'))return hold('Current scope approval and source stage required');
+ if(!intent||!stage||intent.firstStageId!==stage.id||stage.targetIntentId!==intent.id||intent.sourceTargetVersion!==state.targetVersion||!same(intent.sourceTarget,state.target)||!same(source?.target,state.target)||source.preserved!==true||source.inputVersion!==stage.inputVersion||source.candidate!==intent.candidate||source.base!==intent.base)return hold('Current source and intent evidence required');
+ if(stage.pending||result?.ref!==request.resultRef||result?.status!=='succeeded'||!stage.calls?.some(c=>c.requestId===result.requestId&&c.status==='succeeded')||stage.calls.some(c=>['reserved','unknown'].includes(c.status))||chat?.intentId!==intent.id||!chat.draftRef||!chat.selfReviewRef||chat.selfReviewRef!==request.selfReviewRef||chat.complete!==true)return hold('Complete confirmed chat draft and self-review required');
+ return {decision:'allow',ruleIds:['cooperative.target-preparation'],reason:'Chat checkpoint attested',proposedTransition:{checkpoint:{intentId:intent.id,stageId:stage.id,resultRef:result.ref,selfReviewRef:chat.selfReviewRef,candidate:intent.candidate,base:intent.base,inputVersion:stage.inputVersion}}};
+}
+
+export function applyTargetPreparationTransition({state,decision}={}){
+ const next=structuredClone(state),transition=decision?.proposedTransition;
+ if(decision?.decision!=='allow'||!transition?.target||transition.sourceTargetVersion!==state.targetVersion||transition.expectedRevision!==state.revision||state.targetTransitions?.some(t=>t.intentId===transition.intentId))return next;
+ if(!transition.validation)return next;
+ const checked=evaluateTargetPreparation({state,...transition.validation});
+ if(checked.decision!=='allow'||!same(checked.proposedTransition,transition))return next;
+ const intent=state.targetIntents?.find(i=>i.id===transition.intentId),checkpoint=state.targetCheckpoints?.find(c=>c.intentId===transition.intentId&&c.messageRef===transition.checkpointRef);
+ if(!intent||!checkpoint||intent.sourceTargetVersion!==state.targetVersion||!same(intent.sourceTarget,state.target))return next;
+ next.target=structuredClone(transition.target);next.targetVersion++;
+ (next.targetTransitions??=[]).push({...structuredClone(transition),targetVersion:next.targetVersion});
+ return next;
+}
+import fs from 'node:fs/promises';
+import {constants} from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {inspectPath,within,observeCooperativeTarget} from './scope.mjs';
+import {readCooperativeChanges} from './verification.mjs';
+import {spawnSync} from 'node:child_process';
+function defaultRunner({cwd,args}){
+ const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>!key.toUpperCase().startsWith('GIT_')));
+ Object.assign(env,{GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:process.platform==='win32'?'NUL':'/dev/null',GIT_OPTIONAL_LOCKS:'0',GIT_NO_REPLACE_OBJECTS:'1',GIT_NO_LAZY_FETCH:'1',GIT_TERMINAL_PROMPT:'0'});
+ return spawnSync('git',['--no-pager','-c','core.fsmonitor=false',...args],{cwd,env,encoding:'buffer',timeout:10000,maxBuffer:1024*1024});
+}

package/codex/skill/runtime/verification.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import {constants} from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawnSync} from 'node:child_process';
@@ -108,16 +109,17 @@ export async function readCooperativeChanges({state,gitRunner=defaultRunner}){
  if(raw&&!raw.endsWith('\0'))throw Error('Incomplete verification inventory');
  const index=await gitRunner({cwd:state.target.realpath,args:['ls-files','--stage','-z']});
  if(index?.status!==0||index.error||!Buffer.isBuffer(index.stdout))throw Error('Verification index query failed');
- const indexText=new TextDecoder('utf-8',{fatal:true}).decode(index.stdout),indexRows=[];
+ const indexText=new TextDecoder('utf-8',{fatal:true}).decode(index.stdout),indexRows=[],transitionIndex=[];
  if(indexText&&!indexText.endsWith('\0'))throw Error('Incomplete verification index');
- for(const entry of indexText?indexText.slice(0,-1).split('\0'):[]){const match=/^(100644|100755) ([a-f0-9]{40}|[a-f0-9]{64}) 0\t([\s\S]+)$/.exec(entry);if(!match)throw Error('Verification requires regular stage-0 index entries');indexRows.push({path:path.join(state.target.realpath,match[3]),entry});}
+ for(const entry of indexText?indexText.slice(0,-1).split('\0'):[]){const match=/^(100644|100755) ([a-f0-9]{40}|[a-f0-9]{64}) 0\t([\s\S]+)$/.exec(entry);if(!match||!match[3]||/[\\\x00\r\n:]/.test(match[3])||match[3].startsWith('/')||match[3].split('/').some(p=>!p||p==='.'||p==='..'))throw Error('Verification requires regular stage-0 index entries');indexRows.push({path:path.join(state.target.realpath,match[3]),entry});transitionIndex.push({path:match[3],mode:match[1],blob:match[2],stage:0});}
  const names=[...new Set(raw?raw.slice(0,-1).split('\0'):[])].sort(),rows=[];
  for(const name of names){
   if(!name||name.includes('\\')||name.includes('\n')||name.includes('\r')||path.isAbsolute(name)||name.split('/').some(p=>!p||p==='.'||p==='..'))throw Error('Invalid verification path');
   const file=path.join(state.target.realpath,...name.split('/'));
-  try{await inspectPath(file);const stat=await fs.lstat(file);if(!stat.isFile())throw Error('Verification requires regular files');rows.push({path:file,mode:stat.mode&0o777,hash:'sha256:'+createHash('sha256').update(await fs.readFile(file)).digest('hex')});}
+  try{await inspectPath(file);const handle=await fs.open(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);let stat,bytes;try{stat=await handle.stat();if(!stat.isFile())throw Error('Verification requires regular files');bytes=await handle.readFile();const after=await handle.stat(),named=await fs.lstat(file);if(stat.dev!==after.dev||stat.ino!==after.ino||stat.size!==after.size||stat.mtimeMs!==after.mtimeMs||stat.mode!==after.mode||after.dev!==named.dev||after.ino!==named.ino)throw Error('Verification file changed while reading');}finally{await handle.close();}await inspectPath(file);rows.push({path:file,mode:stat.mode&0o777,hash:'sha256:'+createHash('sha256').update(bytes).digest('hex')});}
   catch(error){if(error.code!=='ENOENT')throw error;rows.push({path:file,deleted:true});}
  }
  const tasks={},taskSnapshots={};for(const task of state.tasks){if(!list(task.paths)||!task.paths.every(p=>absolute(p)&&within(state.target.realpath,p)))throw Error('Invalid task paths');taskSnapshots[task.id]={scope:'task',taskId:task.id,target:Object.fromEntries(Object.entries(state.target).filter(([key])=>key!=='head')),paths:task.paths,index:indexRows.filter(row=>task.paths.some(p=>within(p,row.path))),rows:rows.filter(row=>task.paths.some(p=>within(p,row.path)))};tasks[task.id]=fingerprintRequest(taskSnapshots[task.id]);}
- return {tasks,taskSnapshots,final:fingerprintRequest({scope:'final',target:state.target,index:indexRows,rows})};
+ const transitionSnapshot={index:transitionIndex.sort((a,b)=>a.path.localeCompare(b.path)),files:rows.map(row=>({...row,path:path.relative(state.target.realpath,row.path).split(path.sep).join('/')}))};
+ return {tasks,taskSnapshots,final:fingerprintRequest({scope:'final',target:state.target,index:indexRows,rows}),transitionSnapshot};
 }

package/codex/skill/scripts/model_config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 import json
 import re
 import tomllib
@@ -77,10 +78,14 @@ PRESETS = ("economy", "balanced", "smart")
 
 
 def validate_config(config: dict, path: Path) -> dict:
-    if not isinstance(config, dict) or set(config) != {"version", "preset", "roles"} or type(config["version"]) is not int or config["version"] != 1:
-        raise _error(path, "settings", "update to version 1 unified presets; reinstall ARC or edit models.toml to include preset and all role presets")
-    if not isinstance(config["preset"], str) or config["preset"] not in PRESETS:
-        raise _error(path, "preset", "must be economy, balanced or smart")
+    if not isinstance(config, dict) or type(config.get("version")) is not int or config["version"] not in (1, 2):
+        raise _error(path, "settings", "update to version 1 or 2 unified presets; reinstall ARC or edit models.toml to include preset and all role presets")
+    has_custom = "custom" in config
+    allowed = {"version", "preset", "roles"} | ({"custom"} if config["version"] == 2 and has_custom else set())
+    if set(config) != allowed:
+        raise _error(path, "settings", "update to version 1 or 2 unified presets; reinstall ARC or edit models.toml to include preset and all role presets")
+    if not isinstance(config["preset"], str) or config["preset"] not in (*PRESETS, "custom") or (config["preset"] == "custom" and not has_custom):
+        raise _error(path, "preset", "must select an available preset")
     roles = config["roles"]
     if not isinstance(roles, dict) or set(roles) != set(ROLE_FILES):
         raise _error(path, "roles", "must define exactly the five ARC roles")
@@ -89,24 +94,38 @@ def validate_config(config: dict, path: Path) -> dict:
             raise _error(path, f"roles.{role}", "must contain exactly economy, balanced and smart")
         for preset, values in variants.items():
             _settings_for_profile(values, f"{role}.{preset}", path)
-    return config
+    if has_custom:
+        custom = config["custom"]
+        if not isinstance(custom, dict) or set(custom) != set(ROLE_FILES):
+            raise _error(path, "custom", "must define exactly the five ARC roles")
+        for role, values in custom.items():
+            _settings_for_profile(values, f"custom.{role}", path)
+    result = copy.deepcopy(config)
+    result["version"] = 2
+    return result
 
 
 def load_settings(config_path: Path) -> dict[str, RoleSettings]:
     """Validate every preset and return the active role settings."""
     _, _, config = _parse_file(config_path, "settings")
     config = validate_config(config, config_path)
+    if config["preset"] == "custom":
+        return config["custom"]
     return {role: dict(variants[config["preset"]]) for role, variants in config["roles"].items()}
 
 
 def serialize_settings(config: dict) -> bytes:
     """Serialize a complete unified configuration without losing inactive presets."""
     config = validate_config(config, Path("models.toml"))
-    lines = ["version = 1", f'preset = {json.dumps(config["preset"])}']
+    lines = ["version = 2", f'preset = {json.dumps(config["preset"])}']
     for role in ROLE_FILES:
         for preset in PRESETS:
             lines.extend(["", f"[roles.{role}.{preset}]"])
             lines.extend(f"{key} = {json.dumps(config['roles'][role][preset][key], ensure_ascii=False)}" for key in _MODEL_FIELDS)
+    if "custom" in config:
+        for role in ROLE_FILES:
+            lines.extend(["", f"[custom.{role}]"])
+            lines.extend(f"{key} = {json.dumps(config['custom'][role][key], ensure_ascii=False)}" for key in _MODEL_FIELDS)
     return ("\n".join(lines) + "\n").encode("utf-8")
 
 

package/lib/installer/global-config.mjs

@@ -39,5 +39,5 @@ export function renderWaitSettings(original){
  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'+
+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 and brainstorming drafts and first complete spec and plan drafts are authored only by the Planner; route drafting skills to the Planner. Orchestrator reviews and directly revises the same spec or plan when needed; a missing or failed first draft does not transfer initial authorship. New product decisions outside approved scope require user input first.\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';}

package/lib/installer/manifest.mjs

@@ -1,3 +1,4 @@
+import {validateAgentTemplates} from '../prompts/render.mjs';
 import {COOPERATIVE_RUNTIME_MODULES} from '../runtime/bootstrap.mjs';
 import {RUNTIME_MODULE_PATHS} from './runtime-assets.mjs';
 import {POLICY_TARGETS,buildPolicyOutputs} from '../policy/render.mjs';
@@ -40,18 +41,21 @@ export function verifyPayload({packageRoot,safeFs,payloadMode='auto'}){
   for(const platform of ['codex','claude'])referenceTrees[platform]=validateFlatReferenceFiles(files,platform);
   for(const{destination}of REFERENCE_PATH_MAP)if(!referenceTrees.codex.entries.get(destination).bytes.equals(referenceTrees.claude.entries.get(destination).bytes))throw Error('Imported platform parity mismatch: '+destination);
   for(const name of listed.keys())if(!files.has(name))throw Error(`Manifest entry is missing: ${name}`);
-  const required=['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/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.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'];
+  const required=['lib/prompts/agent-fragments.json','lib/prompts/render.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/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.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'];
   required.push('lib/installer/runtime-assets.mjs',...RUNTIME_MODULE_PATHS);
   for(const platform of ['codex','claude'])required.push(`${platform}/skill/runtime/role-policy.json`,...RUNTIME_MODULE_PATHS.map(name=>`${platform}/skill/runtime/${name.slice('lib/runtime/'.length)}`));
   for(const tuple of ['darwin-arm64','darwin-x64','linux-arm64-gnu','linux-x64-gnu'])required.push(`prebuilds/${tuple}/arc_safe_fs.node`);
   for(const platform of ['codex','claude'])for(const name of [...COOPERATIVE_RUNTIME_MODULES,'role-policy.json'])required.push(`${platform}/skill/runtime/${name}`);
   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','implementer','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 agentRegistry=JSON.parse(files.get('lib/prompts/agent-fragments.json').toString('utf8'));
+  const agentTemplates=new Map();for(const platform of ['codex','claude'])for(const [name,bytes] of modelInputs[platform].profiles)agentTemplates.set(`${platform}/agents/${name}`,bytes);
+  validateAgentTemplates(agentTemplates,agentRegistry);
   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};
+  return{packageRoot,files,modelInputs,agentRegistry,snapshot,referenceTrees};
  }catch(cause){throw new PayloadValidationError(`Payload verification failed: ${cause.message}`,{cause});}finally{root?.close();}
 }

package/lib/installer/plan.mjs

@@ -1,7 +1,10 @@
+import {renderAgentProfile} from '../prompts/render.mjs';
+import {PayloadValidationError} from './manifest.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{validateModelConfig}from'../models/config.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';
+import{assertCatalogRoles}from'../models/catalog.mjs';
+import path from'node:path';import{loadModelConfig,applyPreset,applyCustomRoles,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');
@@ -15,9 +18,9 @@ export function previewLanguage({target,safeFs}){
  let existing=null;try{if(current.exists)existing=parseLanguage(current.bytes).language;}catch(cause){fail(`Invalid ARC language settings: ${cause.message}`);}
  return{existing,snapshot};
 }
-function renderModelAssets({payload,target,preset,modelConfig,language}){
+function renderModelAssets({payload,target,preset,modelConfig,language,customRoles,preservedCustomRoles,verifiedCatalog}){
  const input=payload.modelInputs[target.platform];if(!input)fail('Selected payload platform is unavailable');
- const config=modelConfig===undefined?applyPreset(loadModelConfig(input.models,target.platform),preset):validateModelConfig(modelConfig);if(config.platform!==target.platform)fail('Model config platform does not match target');const profiles=renderProfiles(input.profiles,resolveModelSettings(config));for(const[name,bytes]of profiles)profiles.set(name,renderLanguagePolicy(bytes,language));const modelBytes=Buffer.from(serializeModelConfig(config));
+ let config;if(modelConfig!==undefined)config=validateModelConfig(modelConfig);else{const base=loadModelConfig(input.models,target.platform);if(preset==='custom'){assertCatalogRoles({platform:target.platform,roles:customRoles,catalog:verifiedCatalog});config=applyCustomRoles(base,customRoles);}else {if(customRoles!==undefined)assertCatalogRoles({platform:target.platform,roles:customRoles,catalog:verifiedCatalog});config=applyPreset(customRoles!==undefined?applyCustomRoles(base,customRoles):preservedCustomRoles!==undefined?applyCustomRoles(base,preservedCustomRoles):base,preset);}}if(config.platform!==target.platform)fail('Model config platform does not match target');const settings=resolveModelSettings(config),profiles=renderProfiles(input.profiles,settings);try{for(const[name,bytes]of profiles){const expanded=renderAgentProfile(`${target.platform}/agents/${name}`,bytes,payload.agentRegistry);const final=renderLanguagePolicy(expanded,language);if(final.toString('utf8').includes('ARC_AGENT_FRAGMENT'))throw Error('Unresolved fragment marker');profiles.set(name,final);}const checked=renderProfiles(profiles,settings);if(checked.size!==profiles.size||[...profiles].some(([name,bytes],i)=>{const entry=[...checked][i];return !entry||entry[0]!==name||!entry[1].equals(bytes);}))throw Error('Final profile model settings changed');}catch(cause){throw new PayloadValidationError(`Payload profile rendering failed: ${cause.message}`,{cause});}const modelBytes=Buffer.from(serializeModelConfig(config));
  return{profiles,modelBytes};
 }
 function renderSkillPayload({payload,target,language,modelBytes,limits}){
@@ -45,14 +48,14 @@ function renderNativeChanges({target,safeFs,snapshot,skipGlobal,preview,concurre
  }
  return globalChanges;
 }
-export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,limits,concurrentExplicit=false,limitsPreview,language='en',languagePreview,modelConfig}){
+export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,limits,concurrentExplicit=false,limitsPreview,language='en',languagePreview,modelConfig,customRoles,preservedCustomRoles,verifiedCatalog}){
  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 {profiles,modelBytes}=renderModelAssets({payload,target,preset,modelConfig,language});
+ const {profiles,modelBytes}=renderModelAssets({payload,target,preset,modelConfig,language,customRoles,preservedCustomRoles,verifiedCatalog});
  const skill=renderSkillPayload({payload,target,language,modelBytes,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});

package/lib/installer/preset.mjs

@@ -1,14 +1,17 @@
 import path from 'node:path';
 import {inspectPath,TargetConfigurationError} from './targets.mjs';
-import {loadModelConfig,applyPreset,serializeModelConfig,resolveModelSettings,renderProfiles} from '../models/index.mjs';
+import {loadModelConfig,applyPreset,applyCustomRoles,serializeModelConfig,resolveModelSettings,renderProfiles} from '../models/index.mjs';
 import {assertPlanSnapshot,applyTransaction} from './transaction.mjs';
+import {assertCatalogRoles} from '../models/catalog.mjs';
 import {validatePlanSet} from './plan.mjs';
-export function buildPresetPlan({target,preset,safeFs}){
+export function buildPresetPlan({target,preset,safeFs,customRoles,verifiedCatalog}){
  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 originalModels=read(modelsPath),config=loadModelConfig(originalModels,target.platform);
+ if(preset==='custom'||customRoles!==undefined)assertCatalogRoles({platform:target.platform,roles:customRoles,catalog:verifiedCatalog});
+ const next=customRoles!==undefined?applyPreset(applyCustomRoles(config,customRoles),preset):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))});
+ if(config.preset!==preset||(customRoles!==undefined&&(!config.custom||Object.keys(next.custom).some(role=>Object.keys(next.custom[role]).some(key=>config.custom[role]?.[key]!==next.custom[role][key])))))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};
 }

package/lib/installer/runtime-assets.mjs

@@ -21,5 +21,6 @@ export const RUNTIME_MODULE_PATHS = Object.freeze([
  'lib/runtime/schema.mjs',
  'lib/runtime/scope.mjs',
  'lib/runtime/store.mjs',
+ 'lib/runtime/target-preparation.mjs',
  'lib/runtime/verification.mjs'
 ]);

package/lib/management/operations.mjs

@@ -21,7 +21,7 @@ export async function prepareOperation(context,options,{selections=[]}={}){
  if(!['install','preset','uninstall'].includes(options.kind))throw Object.assign(Error('Unknown management operation'),{code:'ARC_CLI_INPUT'});
  if(options.kind==='uninstall')options={...options,removeCli:options.removeCli!==false};
  const platforms=options.target==='all'?['codex','claude']:[options.target],payload=options.kind==='install'?verifyPayload(context):null;
- const plans=platforms.map(platform=>{const target=resolveTarget(platform,context),selection=selections.find(item=>item.target.platform===platform&&item.target.home===target.home);if(options.kind==='preset')return buildPresetPlan({target,preset:options.preset,safeFs:context.safeFs});if(options.kind==='uninstall')return buildUninstallPlan({target,safeFs:context.safeFs,skipGlobal:options.skipGlobal,removeCompletion:options.removeCli!==false});return buildInstallPlan({payload,target,limitsPreview:selection?.preview,languagePreview:selection?.languagePreview,preset:options.preset,language:options.language,skipGlobal:options.skipGlobal,safeFs:context.safeFs,limits:{...(options.maxTotalSubagents===undefined?{}:{max_total_subagents:options.maxTotalSubagents}),...(options.maxConcurrentSubagents===undefined?{}:{max_concurrent_subagents:options.maxConcurrentSubagents})},concurrentExplicit:options.maxConcurrentSubagents!==undefined||Boolean(options.concurrentSelected)});});
+ const plans=platforms.map(platform=>{const target=resolveTarget(platform,context),selection=selections.find(item=>item.target.platform===platform&&item.target.home===target.home);if(options.kind==='preset')return buildPresetPlan({target,preset:options.preset,safeFs:context.safeFs,customRoles:options.customRoles,verifiedCatalog:options.verifiedCatalog});if(options.kind==='uninstall')return buildUninstallPlan({target,safeFs:context.safeFs,skipGlobal:options.skipGlobal,removeCompletion:options.removeCli!==false});return buildInstallPlan({payload,target,limitsPreview:selection?.preview,languagePreview:selection?.languagePreview,preset:options.preset,customRoles:options.customRoles,preservedCustomRoles:options.preservedCustomRoles,verifiedCatalog:options.verifiedCatalog,language:options.language,skipGlobal:options.skipGlobal,safeFs:context.safeFs,limits:{...(options.maxTotalSubagents===undefined?{}:{max_total_subagents:options.maxTotalSubagents}),...(options.maxConcurrentSubagents===undefined?{}:{max_concurrent_subagents:options.maxConcurrentSubagents})},concurrentExplicit:options.maxConcurrentSubagents!==undefined||Boolean(options.concurrentSelected)});});
  if(options.kind==='install')attachShellCompletionCleanup(plans,context);
  // Uninstall plans initially share the completion snapshot; its executor assigns one owner.
  if(options.kind!=='uninstall')validatePlanSet(plans);

package/lib/models/catalog-anthropic.mjs

@@ -0,0 +1,46 @@
+const API = 'https://api.anthropic.com/v1/models';
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const unavailable = (code, message) => ({ status: 'unavailable', code, message });
+
+export async function discoverAnthropicCatalog({ apiKey, fetchImpl = globalThis.fetch, signal } = {}) {
+  if (typeof apiKey !== 'string' || !apiKey.trim() || /[\r\n]/.test(apiKey)) return unavailable('missing_api_key', 'Anthropic API key is unavailable.');
+  if (typeof fetchImpl !== 'function') return unavailable('unavailable', 'Anthropic catalog is unavailable.');
+  const pairs = [], unavailableModels = [], seenPairs = new Set(), seenModels = new Set(), supportedModels = new Set(), cursors = new Set();
+  let cursor;
+  try {
+    for (let pageNumber = 0; pageNumber < 1000; pageNumber++) {
+      if (signal?.aborted) return unavailable('aborted', 'Catalog lookup was cancelled.');
+      const url = new URL(API);
+      if (cursor) url.searchParams.set('after_id', cursor);
+      const response = await fetchImpl(url, {
+        method: 'GET', redirect: 'manual', signal,
+        headers: { 'anthropic-version': '2026-10-21', Authorization: `Bearer ${apiKey}` },
+      });
+      if (!response?.ok) return unavailable('http_error', 'Anthropic catalog is unavailable.');
+      if (response.url) {
+        const actual = new URL(response.url);
+        if (actual.origin !== url.origin || actual.pathname !== url.pathname) return unavailable('http_error', 'Anthropic catalog is unavailable.');
+      }
+      const page = await response.json();
+      if (!page || !Array.isArray(page.data) || !page.data.length || typeof page.has_more !== 'boolean') throw Error('invalid page');
+      for (const model of page.data) {
+        if (!model || typeof model.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:/@+\-]*$/.test(model.id) || model.id.includes(apiKey)) throw Error('invalid model');
+        const capability = model.capabilities?.effort;
+        const supported = capability?.supported === true ? EFFORTS.filter(effort => capability[effort]?.supported === true) : [];
+        if (!supported.length && !seenModels.has(model.id)) unavailableModels.push({ model: model.id, reason: 'Effort capability is unavailable.' });
+        seenModels.add(model.id);
+        for (const effort of supported) {
+          supportedModels.add(model.id);
+          const key = JSON.stringify([model.id, effort]);
+          if (!seenPairs.has(key)) { seenPairs.add(key); pairs.push({ model: model.id, effort }); }
+        }
+      }
+      if (!page.has_more) return { status: 'ready', catalog: { platform: 'claude', pairs, unavailable: unavailableModels.filter(item => !supportedModels.has(item.model)) } };
+      if (typeof page.last_id !== 'string' || !page.last_id || page.last_id !== page.data.at(-1).id || cursors.has(page.last_id)) throw Error('invalid cursor');
+      cursor = page.last_id; cursors.add(cursor);
+    }
+    throw Error('too many pages');
+  } catch {
+    return signal?.aborted ? unavailable('aborted', 'Catalog lookup was cancelled.') : unavailable('invalid_response', 'Anthropic catalog is unavailable.');
+  }
+}

package/lib/models/catalog.mjs

@@ -0,0 +1,62 @@
+import { effortField, validateRoles, ModelValidationError } from './config.mjs';
+import { discoverAnthropicCatalog } from './catalog-anthropic.mjs';
+export { discoverAnthropicCatalog } from './catalog-anthropic.mjs';
+export { listCodexModelCapabilities } from './codex-catalog.mjs';
+
+const unavailable = (code, message) => ({ status: 'unavailable', code, message });
+const validText = value => typeof value === 'string' && value.length > 0 && value === value.trim() && !/[\p{Cc}\u2028\u2029]/u.test(value);
+
+function codexCatalog(models, secrets) {
+  if (!Array.isArray(models) || !models.length) throw Error('invalid catalog');
+  const pairs = [], missing = [], seenPairs = new Set(), seenModels = new Set(), supportedModels = new Set();
+  for (const item of models) {
+    if (!item || !validText(item.model) || secrets.some(secret => item.model.includes(secret)) || !Array.isArray(item.efforts) || !item.efforts.every(value => validText(value) && !secrets.some(secret => value.includes(secret)))) throw Error('invalid model');
+    if (!item.efforts.length && !seenModels.has(item.model)) missing.push({ model: item.model, reason: 'Effort capability is unavailable.' });
+    seenModels.add(item.model);
+    for (const effort of item.efforts) {
+      supportedModels.add(item.model);
+      const key = JSON.stringify([item.model, effort]);
+      if (!seenPairs.has(key)) { seenPairs.add(key); pairs.push({ model: item.model, effort }); }
+    }
+  }
+  return { platform: 'codex', pairs, unavailable: missing.filter(item => !supportedModels.has(item.model)) };
+}
+
+export async function discoverModelCatalog({ platform, env = process.env, fetchImpl = globalThis.fetch, listCodexModels, signal, timeoutMs = 10000 } = {}) {
+  if (!['codex', 'claude'].includes(platform)) return unavailable('unsupported_platform', 'Catalog is unavailable.');
+  if (signal?.aborted) return unavailable('aborted', 'Catalog lookup was cancelled.');
+  if (platform === 'codex' && typeof listCodexModels !== 'function') return unavailable('unavailable', 'Codex catalog is unavailable.');
+  const controller = new AbortController(); let timedOut = false, resolveAbort;
+  const abortPromise = new Promise(resolve => { resolveAbort = resolve; });
+  const onAbort = () => { controller.abort(); resolveAbort(); };
+  signal?.addEventListener('abort', onAbort, { once: true });
+  const timer = setTimeout(() => { timedOut = true; onAbort(); }, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 10000);
+  const operation = Promise.resolve().then(async () => platform === 'codex'
+    ? { status: 'ready', catalog: codexCatalog(await listCodexModels({ env, signal: controller.signal }), [env?.OPENAI_API_KEY, env?.ANTHROPIC_API_KEY].filter(value => typeof value === 'string' && value.length)) }
+    : discoverAnthropicCatalog({ apiKey: env?.ANTHROPIC_API_KEY, fetchImpl, signal: controller.signal }));
+  const settled = operation.then(value => ({ value }), () => ({ failed: true }));
+  try {
+    const first = await Promise.race([settled, abortPromise.then(() => ({ aborted: true }))]);
+    if (first.aborted) {
+      if (platform === 'codex') {
+        let graceTimer;
+        await Promise.race([settled, new Promise(resolve => { graceTimer = setTimeout(resolve, 2100); })]);
+        clearTimeout(graceTimer);
+      }
+      return timedOut ? unavailable('timeout', 'Catalog lookup timed out.') : unavailable('aborted', 'Catalog lookup was cancelled.');
+    }
+    return first.failed ? unavailable('unavailable', 'Catalog is unavailable.') : first.value;
+  } finally { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); }
+}
+
+export function assertCatalogRoles({ platform, roles, catalog } = {}) {
+  const validRoles = validateRoles(roles, platform);
+  if (!catalog || catalog.platform !== platform || !Array.isArray(catalog.pairs)) throw new ModelValidationError('Catalog is unavailable.');
+  const pairs = new Set();
+  for (const pair of catalog.pairs) {
+    if (!pair || !validText(pair.model) || !validText(pair.effort)) throw new ModelValidationError('Catalog is invalid.');
+    pairs.add(JSON.stringify([pair.model, pair.effort]));
+  }
+  const effort = effortField(platform);
+  if (Object.values(validRoles).some(value => !pairs.has(JSON.stringify([value.model, value[effort]])))) throw new ModelValidationError('Roles contain a pair absent from the catalog.');
+}

package/lib/models/codex-catalog.mjs

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+
+const ENV_KEYS = ['PATH', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'SYSTEMROOT', 'WINDIR', 'TMPDIR', 'TEMP', 'TMP', 'CODEX_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME'];
+const validText = value => typeof value === 'string' && value.length > 0 && value === value.trim() && !/[\p{Cc}\u2028\u2029]/u.test(value);
+const failure = () => new Error('Codex catalog is unavailable.');
+
+export async function listCodexModelCapabilities({ env = process.env, cwd, spawnImpl = spawn, signal, timeoutMs = 10000 } = {}) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || path.normalize(cwd) !== cwd || typeof spawnImpl !== 'function' || signal?.aborted) throw failure();
+  const childEnv = Object.fromEntries(ENV_KEYS.filter(key => typeof env?.[key] === 'string').map(key => [key, env[key]]));
+  const secrets = [env?.OPENAI_API_KEY, env?.ANTHROPIC_API_KEY].filter(value => typeof value === 'string' && value.length);
+  const containsSecret = value => secrets.some(secret => value.includes(secret));
+  let child;
+  try { child = spawnImpl('codex', ['app-server'], { cwd, env: childEnv, stdio: ['pipe', 'pipe', 'pipe'], shell: false }); }
+  catch { throw failure(); }
+  if (!child?.stdin || !child?.stdout || !child?.stderr || typeof child.on !== 'function' || typeof child.kill !== 'function') throw failure();
+
+  let closed = false, interrupted = false, cancelled = false, nextId = 0, buffer = '';
+  const pending = new Map(), decoder = new StringDecoder('utf8');
+  let resolveClosed;
+  const closedPromise = new Promise(resolve => { resolveClosed = resolve; });
+  const rejectPending = () => { interrupted = true; for (const entry of pending.values()) entry.reject(failure()); pending.clear(); };
+  const onClose = () => { closed = true; resolveClosed(); rejectPending(); };
+  const onError = () => rejectPending();
+  const onData = chunk => {
+    buffer += decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    if (buffer.length > 1048576) { rejectPending(); return; }
+    let newline;
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      if (!line.trim()) continue;
+      let message; try { message = JSON.parse(line); } catch { rejectPending(); return; }
+      if (message?.id === undefined) continue;
+      const entry = pending.get(message.id);
+      if (!entry) { rejectPending(); return; }
+      pending.delete(message.id);
+      if (message.error || !Object.hasOwn(message, 'result')) entry.reject(failure()); else entry.resolve(message.result);
+    }
+  };
+  child.on('close', onClose); child.on('error', onError);
+  child.stdout.on('data', onData); child.stdout.on('error', onError); child.stdin.on('error', onError); child.stderr.on('error', onError); child.stderr.resume();
+  const onAbort = () => { cancelled = true; rejectPending(); };
+  signal?.addEventListener('abort', onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  const timer = setTimeout(onAbort, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 10000);
+  const send = value => { if (interrupted || closed) throw failure(); child.stdin.write(JSON.stringify(value) + '\n'); };
+  const request = (method, params) => new Promise((resolve, reject) => {
+    if (interrupted || closed) { reject(failure()); return; }
+    const id = ++nextId; pending.set(id, { resolve, reject });
+    try { send({ id, method, params }); } catch { pending.delete(id); reject(failure()); }
+  });
+  let result, error;
+  try {
+    const initialized = await request('initialize', { clientInfo: { name: 'arc', title: 'ARC', version: '1.0.0' } });
+    if (!initialized || typeof initialized !== 'object' || Array.isArray(initialized) || !validText(initialized.userAgent)) throw failure();
+    send({ method: 'initialized', params: {} });
+    const models = new Map(), cursors = new Set(); let cursor;
+    for (let pageNumber = 0; pageNumber < 1000; pageNumber++) {
+      const page = await request('model/list', { limit: 100, includeHidden: true, ...(cursor ? { cursor } : {}) });
+      if (interrupted) throw failure();
+      if (!page || !Array.isArray(page.data) || !page.data.length || !(page.nextCursor === null || validText(page.nextCursor))) throw failure();
+      for (const descriptor of page.data) {
+        if (descriptor?.hidden === true) continue;
+        if (!descriptor || !validText(descriptor.model) || containsSecret(descriptor.model) || !Array.isArray(descriptor.supportedReasoningEfforts)) throw failure();
+        let efforts = models.get(descriptor.model);
+        if (!efforts) { efforts = []; models.set(descriptor.model, efforts); }
+        for (const option of descriptor.supportedReasoningEfforts) {
+          if (!validText(option?.reasoningEffort) || containsSecret(option.reasoningEffort)) throw failure();
+          if (!efforts.includes(option.reasoningEffort)) efforts.push(option.reasoningEffort);
+        }
+      }
+      if (page.nextCursor === null) { result = [...models].map(([model, efforts]) => ({ model, efforts })); break; }
+      if (cursors.has(page.nextCursor)) throw failure();
+      cursors.add(page.nextCursor); cursor = page.nextCursor;
+    }
+    if (!result) throw failure();
+  } catch { error = failure(); }
+  finally {
+    rejectPending();
+    try { child.stdin.end(); } catch { error = failure(); }
+    if (!closed) { try { child.kill('SIGTERM'); } catch { error = failure(); } }
+    const wait = async ms => { if (closed) return true; let timerId; const timeout = new Promise(resolve => { timerId = setTimeout(() => resolve(false), ms); }); const value = await Promise.race([closedPromise.then(() => true), timeout]); clearTimeout(timerId); return value; };
+    if (!await wait(1000)) {
+      try { child.kill('SIGKILL'); } catch { error = failure(); }
+      if (!await wait(1000)) error = failure();
+    }
+    if (!closed) {
+      // A failed close may still emit late errors; keep only a guard until close.
+      const guard = () => {};
+      const streams = [child.stdin, child.stdout, child.stderr];
+      child.on('error', guard); for (const stream of streams) stream.on('error', guard);
+      child.once('close', () => { child.removeListener('error', guard); for (const stream of streams) stream.removeListener('error', guard); });
+      for (const stream of streams) stream.destroy();
+    }
+    clearTimeout(timer); signal?.removeEventListener('abort', onAbort);
+    if (cancelled) error = failure();
+    child.stdout.removeListener('data', onData); child.stdout.removeListener('error', onError); child.stdin.removeListener('error', onError); child.stderr.removeListener('error', onError);
+    child.removeListener('close', onClose); child.removeListener('error', onError);
+  }
+  if (error) throw error;
+  return result;
+}