@yunhozz/arc 0.1.2 → 0.1.3

package/codex/skill/runtime/evaluate.mjs

@@ -0,0 +1,103 @@
+/**
+ * @typedef {object} GateDecision
+ * @property {'allow'|'deny'|'hold'} decision
+ * @property {string[]} ruleIds
+ * @property {string} reason
+ * @property {string[]} requiredEvidence
+ * @property {number} expectedRevision
+ * @property {object|null} proposedTransition
+ * @property {object} coverage
+ */
+import path from 'node:path';
+import {validateWorkflowState, validateRequest, validateEvidence} from './schema.mjs';
+import {ROLES, ROLE_OPERATIONS, GIT_OPERATIONS, EXTERNAL_OPERATIONS} from './operations.mjs';
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const within=(base,file)=>{const relative=path.relative(base,file);return relative===''||(!relative.startsWith('..'+path.sep)&&relative!=='..'&&!path.isAbsolute(relative));};
+/** Pure policy decision. Evidence is supplied by a trusted adapter/provider, never tool arguments. */
+export function evaluate(policy, state, request, evidence){
+ const result=(decision,id,reason,requiredEvidence=[])=>({decision,ruleIds:[id],reason,requiredEvidence,expectedRevision:state?.revision??0,proposedTransition:null,coverage:{platform:request?.platform??'unknown',enforcement:'decision-only'}});
+ try{validateWorkflowState(state);validateRequest(request);validateEvidence(evidence);}catch(error){return result('hold','runtime.schema',error.message,['valid-state-request-evidence']);}
+ if(policy?.runtime?.schemaVersion!==1||!same(policy.runtime.roles,ROLES)||!Array.isArray(policy.runtime.ruleIds)||!Array.isArray(policy.runtime.requiredEvidence)||policy.runtime.status!=='decision-only')return result('hold','runtime.policy','runtime policy unavailable',['runtime-policy']);
+ const actor=state.identities.find(i=>i.actorRef===request.actorRef);
+ if(!actor)return result('hold','runtime.identity','platform identity unresolved',['platform-identity']);
+ const role=actor.role;
+ const roleRule={orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',coder:'role.coder-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'}[role];
+ if(!ROLE_OPERATIONS[role]?.includes(request.operation))return result('deny',GIT_OPERATIONS.includes(request.operation)?'git.specialists-deny':roleRule,'operation forbidden for assigned role');
+ const lease=state.leases.find(l=>l.actorRef===actor.actorRef);
+ if(lease?.status==='retired')return result('deny','runtime.identity','retired identity');
+ if(!lease||lease.status!=='active'||lease.taskId!==request.taskId||actor.taskId!==request.taskId)return result('hold','runtime.identity','active task lease missing',['active-lease']);
+ const observation=evidence.provenance.find(p=>p.id===actor.observationRef&&p.source==='platform-event'&&p.actorRef===actor.actorRef&&p.platform===request.platform&&p.verification.sourceRef===p.eventRef);
+ if(!observation)return result('hold','runtime.identity','platform observation unavailable',['platform-observation']);
+ if(!same(evidence.target,state.target)||evidence.revision!==state.revision||!same(evidence.versions,state.versions))return result('hold','runtime.target','target revision or versions mismatch',['current-target-versions']);
+ if(!within(state.target.realpath,request.cwd))return result('deny','scope.non-escalation','cwd outside workspace');
+ const assignment=state.assignments.find(a=>a.actorRef===actor.actorRef&&a.taskId===request.taskId&&a.role===role);
+ if(!assignment||!assignment.operations.includes(request.operation))return result('hold','runtime.assignment','approved operation assignment missing',['assignment']);
+ const approval=state.approvals.find(a=>a.id===assignment.approvalRef);
+ const proof=evidence.provenance.find(p=>p.id===approval?.id&&p.source===approval?.source&&p.messageRef===approval?.messageRef&&p.contentHash===approval?.contentHash&&p.verification.sourceRef===p.messageRef);
+ if(!approval||!proof||approval.scope.taskId!==request.taskId||approval.scope.target!==state.target.realpath||!approval.scope.operations.includes(request.operation))return result('hold','runtime.approval','user approval provenance unavailable',['user-approval']);
+ for(const filename of [request.cwd,...request.paths]){
+  const resolved=evidence.resolvedPaths?.find(p=>p.path===filename)?.realpath;
+  if(!resolved||!path.isAbsolute(resolved))return result('hold','runtime.paths','resolved path evidence missing',['resolved-paths']);
+  if(!within(state.target.realpath,resolved))return result('deny','scope.non-escalation','resolved path escapes workspace');
+  if(filename!==request.cwd&&(!assignment.paths.some(p=>within(p,resolved))||!approval.scope.paths.some(p=>within(p,resolved))))return result('deny','scope.non-escalation','path outside assigned approval');
+ }
+ const fact=kind=>evidence.facts?.find(f=>f.kind===kind&&f.workflowId===state.workflowId&&f.revision===state.revision&&same(f.target,state.target)&&f.policyHash===state.versions.policyHash&&evidence.provenance.some(p=>p.id===f.sourceRef));
+ const task=state.tasks.find(t=>t.id===request.taskId);
+ if(!task)return result('hold','runtime.assignment','task unavailable',['task']);
+ if(role==='coder'&&['accepted','committed'].includes(task.status))return result('deny','runtime.identity','task execution ended');
+ if(request.operation==='temporary-write'){
+  const temporary=assignment.temporary;
+  if(!temporary||temporary.cleanupOwner!==request.actorRef||!Number.isFinite(Date.parse(temporary.expiresAt))||!Number.isFinite(Date.parse(evidence.observedAt))||Date.parse(temporary.expiresAt)<=Date.parse(evidence.observedAt)||!request.paths.every(p=>temporary.paths?.some(base=>within(base,p))))return result('hold','role.qa-verification','temporary scope lifetime and cleanup ownership required',['temporary-assignment']);
+ }
+ if(request.operation==='check'){
+  if(!assignment.checks?.some(c=>same(c,request.descriptor)))return result('hold',roleRule,'exact assigned check descriptor required',['check-descriptor']);
+ }
+ if(role==='orchestrator'&&request.operation==='write'&&request.descriptor.kind!=='document')return result('hold','role.orchestrator-boundary','direct implementation requires reviewed small-task exception',['small-task-exception']);
+ if(request.operation==='assign-agent'){
+  const d=request.descriptor;
+  if(!ROLES.includes(d.role)||d.taskId!==request.taskId)return result('deny','runtime.identity','invalid assignment');
+  const previous=state.identities.find(i=>i.actorRef===d.actorRef);
+  if(previous&&(previous.taskId!==d.taskId||state.leases.some(l=>l.actorRef===d.actorRef&&l.status==='retired')))return result('deny','runtime.identity','identity cannot cross tasks or revive');
+  if(d.role==='coder'){
+   if(state.mode==='plan'){
+    // T3 supplies verified Git object evidence. Local assertions never satisfy this gate.
+    if(!state.documents.some(d=>d.kind==='spec')||!state.documents.some(d=>d.kind==='plan'))return result('hold','runtime.docs-commit','approved complete spec and plan required',['approved-documents','docs-only-commit']);
+    const docs=fact('docs-commit')?.data;
+    const approved=state.documents.every(d=>state.approvals.some(a=>a.id===d.approvalRef&&a.contentHash===d.contentHash&&evidence.provenance.some(p=>p.id===a.id&&p.source===a.source&&p.verification.sourceRef===p.messageRef&&p.messageRef===a.messageRef&&p.contentHash===d.contentHash)));
+    if(!approved||!docs||!docs.commit||!docs.parent||!docs.tree||!same(docs.documents,state.documents)||!same([...docs.paths??[]].sort(),state.documents.map(d=>d.gitPath).sort())||state.documents.some(d=>d.commit!==docs.commit))return result('hold','runtime.docs-commit','Git object and approval verification required',['verified-docs-only-commit']);
+   }
+   else return result('hold','runtime.mode','mode name does not establish exception eligibility',['verified-mode-exception']);
+  }
+  const correlation=fact('assignment-correlation');
+  const expected={requestId:request.requestId,platform:request.platform,...d};
+  const correlationProof=evidence.provenance.find(p=>p.id===correlation?.sourceRef&&p.source==='platform-event'&&p.verification.sourceRef===p.eventRef&&p.platform===request.platform&&p.actorRef===request.actorRef&&p.correlationRef===d.correlationRef&&p.requestId===request.requestId);
+  if(d.actorRef!==undefined||!d.correlationRef||!correlationProof||!same(correlation?.data,expected))return result('hold','runtime.identity','trusted platform request correlation required',['assignment-correlation']);
+  if(!Array.isArray(d.paths)||!d.paths.length||!same([...d.paths].sort(),[...request.paths].sort())||!Array.isArray(d.operations)||!d.operations.length||d.approvalRef!==approval.id||!approval.scope.roles?.includes(d.role)||d.paths.some(p=>!task.paths.some(base=>within(base,p)))||d.operations.some(op=>!ROLE_OPERATIONS[d.role].includes(op)||!approval.scope.operations.includes(op)))return result('hold','runtime.assignment','delegated role paths operations and approval must match',['delegated-scope']);
+  if(d.checks&&(!Array.isArray(approval.scope.checks)||d.checks.some(c=>!approval.scope.checks.some(approved=>same(approved,c)))))return result('hold','runtime.assignment','delegated checks not approved',['delegated-checks']);
+  if(d.temporary&&!same(d.temporary,approval.scope.temporary))return result('hold','runtime.assignment','delegated temporary scope not approved',['delegated-temporary-scope']);
+  if(state.assignments.some(a=>a.assignmentId===request.requestId||a.correlationRef===d.correlationRef))return result('hold','runtime.identity','assignment correlation already registered',['new-assignment-correlation']);
+  const next=structuredClone(state);next.assignments.push({assignmentId:request.requestId,requestId:request.requestId,requestedBy:request.actorRef,status:'pending',actorRef:null,platform:request.platform,correlationRef:d.correlationRef,role:d.role,taskId:d.taskId,paths:[...d.paths],operations:[...d.operations],approvalRef:d.approvalRef,...(d.checks?{checks:structuredClone(d.checks)}:{}),...(d.temporary?{temporary:structuredClone(d.temporary)}:{})});
+  try{validateWorkflowState(next);}catch{return result('hold','runtime.assignment','invalid pending assignment scope',['valid-assignment']);}
+  return {...result('allow','runtime.assignment','pending assignment authorized; observed spawn result still required'),proposedTransition:next};
+ }
+ if(request.operation==='accept'){
+  const d=request.descriptor;const observed=fact('acceptance')?.data;
+  const checks=Array.isArray(d.checkIds)&&task.requiredChecks?.every(id=>d.checkIds?.includes(id)&&state.checks.some(c=>c.id===id&&c.taskId===task.id&&c.status==='passed'&&c.fingerprint===d.fingerprint&&c.resultRef&&c.actorRef!==actor.actorRef&&state.identities.some(i=>i.actorRef===c.actorRef&&i.taskId===task.id&&i.role==='qa')));
+  const findings=state.findings.filter(f=>f.taskId===task.id);
+  if(!observed||!same(observed,d)||!d.fingerprint||!task.criteria?.length||!same(task.criteria,d.criteria)||!checks||findings.some(f=>!Array.isArray(d.findingIds)||!d.findingIds.includes(f.id)||!f.resolutionRef))return result('hold','git.orchestrator-accept-commit','criteria checks findings and fingerprint verification required',['acceptance-evidence']);
+ }
+ if(GIT_OPERATIONS.includes(request.operation)){
+  const d=request.descriptor;const observed=fact('git-index')?.data;
+  const relative=p=>typeof p==='string'&&p.length>0&&!/[\\\x00\r\n:]/.test(p)&&!p.startsWith('/')&&!p.split('/').some(x=>!x||x==='.'||x==='..');
+  if(!observed||!same(observed,d)||d.parent!==state.target.head||!d.indexTree||!Array.isArray(d.paths)||!d.paths.length||!d.paths.every(relative)||new Set(d.paths).size!==d.paths.length||!same([...d.paths.map(p=>path.join(state.target.realpath,...p.split('/')))].sort(),[...request.paths].sort()))return result('hold','git.orchestrator-accept-commit','actual Git objects and relative path verification required',['git-evidence']);
+  if(d.kind==='documents'){
+   if(state.mode!=='plan'||state.documents.length!==2||!same(state.documents.map(x=>x.kind).sort(),['plan','spec'])||!same([...d.paths].sort(),state.documents.map(x=>x.gitPath).sort())||state.documents.some(doc=>doc.path!==path.join(state.target.realpath,...doc.gitPath.split('/'))||!state.approvals.some(a=>a.id===doc.approvalRef&&a.contentHash===doc.contentHash&&evidence.provenance.some(p=>p.id===a.id&&p.source===a.source&&p.messageRef===a.messageRef&&p.contentHash===doc.contentHash&&p.verification.sourceRef===a.messageRef))))return result('hold','runtime.docs-commit','exact approved documents required',['approved-documents']);
+  }else{
+   const accepted=state.acceptances.find(a=>a.taskId===task.id&&a.fingerprint===d.fingerprint&&state.identities.some(i=>i.actorRef===a.actorRef&&i.role==='orchestrator'));
+   if(d.kind!=='task'||!accepted||task.status!=='accepted'||request.paths.some(p=>!task.paths.some(base=>within(base,p))))return result('hold','git.orchestrator-accept-commit','accepted task verification required',['git-evidence']);
+  }
+ }
+ if(EXTERNAL_OPERATIONS.includes(request.operation))return result('hold','external.explicit-user-authority','explicit external target approval must be verified',['external-approval']);
+ if(request.operation==='transition')return result('hold','runtime.transition','result confirmation required',['observed-result']);
+ return result('allow',roleRule,'assigned operation with verified provenance');
+}

package/codex/skill/runtime/gate.mjs

@@ -0,0 +1,71 @@
+import path from 'node:path';
+
+const reconciliations=new WeakMap();
+export function verifiedReconciliation(decision,state,next,expectedCommit){const proof=reconciliations.get(decision);return !!proof&&proof.before===JSON.stringify(state)&&proof.after===JSON.stringify(next)&&(expectedCommit===undefined||proof.expected===JSON.stringify(expectedCommit));}
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const oid=value=>typeof value==='string'&&/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+const hash=value=>typeof value==='string'&&/^sha256:[a-f0-9]{64}$/.test(value);
+const gitPath=value=>typeof value==='string'&&value.length>0&&!/[\\\x00\r\n:]/.test(value)&&!value.startsWith('/')&&!value.split('/').some(p=>!p||p==='.'||p==='..');
+const validPaths=values=>Array.isArray(values)&&values.every(gitPath)&&new Set(values).size===values.length;
+const samePaths=(a,b)=>validPaths(a)&&validPaths(b)&&same([...a].sort(),[...b].sort());
+const within=(base,file)=>{const relative=path.relative(base,file);return relative===''||!path.isAbsolute(relative)&&relative!=='..'&&!relative.startsWith('..'+path.sep);};
+const targetValid=t=>t&&path.isAbsolute(t.realpath)&&path.normalize(t.realpath)===t.realpath&&path.isAbsolute(t.gitCommonDir)&&oid(t.head)&&(t.branch===null||typeof t.branch==='string'&&t.branch);
+
+/** Git-specific validation ONLY. Trusted adapters must separately satisfy T2
+ * evaluate() role/identity/approval policy and transactWorkflow() persistence.
+ * Inputs here are provider observations, never facts accepted from tool input.
+ * Preflight permission does not mean execution or completed commit. */
+export async function runGate({phase,state,request,gitEvidence,expectedCommit,result}={}){
+ const hold=(reason,id='runtime.git-evidence')=>({decision:'hold',ruleIds:[id],reason,requiredEvidence:['observed-git-state'],expectedRevision:state?.revision??0,proposedTransition:null,coverage:{enforcement:'git-validation-only'}});
+ const allow=(reason,extra={})=>({...hold(reason),decision:'allow',requiredEvidence:[],...extra});
+ try{
+  if(!state||!targetValid(state.target)||!Number.isSafeInteger(state.revision)||state.revision<0||!request||request.operation!=='commit'||typeof request.requestId!=='string'||!request.requestId||request.cwd!==state.target.realpath)return hold('Invalid Git gate input');
+  const actors=state.identities?.filter(i=>i.actorRef===request.actorRef);
+  const leases=state.leases?.filter(l=>l.actorRef===request.actorRef&&l.taskId===request.taskId&&l.status==='active');
+  if(actors?.length!==1||actors[0].role!=='orchestrator'||actors[0].taskId!==request.taskId||leases?.length!==1)return hold('Only the observed active Orchestrator may request commit','git.specialists-deny');
+  const task=state.tasks?.find(t=>t.id===request.taskId);
+  const d=request.descriptor;
+  if(!task||!d||!['documents','task'].includes(d.kind)||!oid(d.parent)||!oid(d.indexTree)||!hash(d.fingerprint)||!validPaths(d.paths)||!d.paths.length||d.parent!==state.target.head||d.parent.length!==d.indexTree.length)return hold('Incomplete or stale commit descriptor');
+  if(!Array.isArray(request.paths)||!samePaths(request.paths.map(file=>{
+   if(typeof file!=='string'||!path.isAbsolute(file)||!within(state.target.realpath,file)||path.normalize(file)!==file)throw Error('Requested path escapes target');
+   return path.relative(state.target.realpath,file).split(path.sep).join('/');
+  }),d.paths))return hold('Request paths differ from commit paths');
+  if(d.kind==='documents'){
+   if(state.mode!=='plan'||state.documents?.length!==2||!samePaths(state.documents.map(x=>x.kind),['spec','plan'])||!samePaths(d.paths,state.documents.map(x=>x.gitPath)))return hold('Complete exact approved spec and plan set required','runtime.docs-commit');
+   for(const document of state.documents){
+    const approvals=state.approvals?.filter(a=>a.id===document.approvalRef);
+    if(!hash(document.contentHash)||document.path!==path.join(state.target.realpath,...document.gitPath.split('/'))||approvals?.length!==1||!['user-message','human-confirmation'].includes(approvals[0].source)||!approvals[0].messageRef||approvals[0].contentHash!==document.contentHash)return hold('Approved document hash unavailable','runtime.docs-commit');
+   }
+  }else{
+   const accepted=state.acceptances?.filter(a=>a.taskId===task.id&&a.fingerprint===d.fingerprint&&state.identities.some(i=>i.actorRef===a.actorRef&&i.role==='orchestrator'));
+   if(task.status!=='accepted'||accepted?.length!==1||!task.criteria?.length||!same(accepted[0].criteria,task.criteria)||!Array.isArray(accepted[0].checkIds)||!task.requiredChecks?.every(id=>accepted[0].checkIds.includes(id))||!Array.isArray(accepted[0].findingIds)||state.commits?.some(c=>c.kind==='task'&&c.taskId===task.id))return hold('Exact accepted task diff required','git.orchestrator-accept-commit');
+   const allowed=task.paths;
+   if(!Array.isArray(allowed)||request.paths.some(file=>!allowed.some(base=>path.isAbsolute(base)&&within(base,file))))return hold('Commit contains another task or unrelated changes','git.orchestrator-accept-commit');
+  }
+  if(phase==='preflight'){
+   const g=gitEvidence;
+   if(!g||!same(g.target,state.target)||g.indexTree!==d.indexTree||g.stagedFingerprint!==d.fingerprint||!samePaths(g.stagedPaths,d.paths)||!validPaths(g.workingPaths)||!validPaths(g.untrackedPaths))return hold('Actual Git target index diff and exact paths required');
+   const dirty=[...g.workingPaths,...g.untrackedPaths];
+   const scope=d.kind==='documents'?state.documents.map(x=>x.path):task.paths;
+   if(dirty.some(file=>scope.some(base=>within(base,path.join(state.target.realpath,...file.split('/'))))))return hold('Unstaged or untracked task changes invalidate acceptance');
+   if(d.kind==='documents'){
+    if(!Array.isArray(g.documents)||!samePaths(g.documents.map(x=>x.gitPath),d.paths)||state.documents.some(document=>!g.documents.some(observed=>observed.gitPath===document.gitPath&&observed.path===document.path&&observed.contentHash===document.contentHash&&observed.observedHash===document.contentHash)))return hold('Observed document bytes differ from approved hashes','runtime.docs-commit');
+   }
+   return allow('Git preflight passed; observed commit result still required',{expectedCommit:{requestId:request.requestId,taskId:task.id,kind:d.kind,parent:d.parent,tree:d.indexTree,paths:[...d.paths],fingerprint:d.fingerprint,target:structuredClone(state.target),remainingPaths:[...new Set(dirty)].sort()}});
+  }
+  if(phase!=='reconcile')return hold('Unknown Git gate phase');
+  const expected=expectedCommit;
+  if(!expected||expected.requestId!==request.requestId||expected.taskId!==task.id||expected.parent!==d.parent||expected.tree!==d.indexTree||expected.fingerprint!==d.fingerprint||!samePaths(expected.paths,d.paths)||expected.kind!==undefined&&expected.kind!==d.kind||expected.target!==undefined&&!same(expected.target,state.target))return hold('Preflight correlation unavailable');
+  if(!result||!oid(result.commit)||result.commit===expected.parent||result.commit.length!==expected.parent.length||result.parent!==expected.parent||result.tree!==expected.tree||!samePaths(result.paths,expected.paths)||result.head!==result.commit||!same(result.target,{...state.target,head:result.commit})||!validPaths(result.remainingPaths))return hold('Commit result unavailable or differs from expected parent tree paths and HEAD');
+  const scopedPaths=d.kind==='documents'?state.documents.map(x=>x.path):task.paths;
+  if(result.remainingPaths.some(file=>scopedPaths.some(base=>within(base,path.join(state.target.realpath,...file.split('/'))))))return hold('Committed task still has remaining changes');
+  if(expected.remainingPaths!==undefined&&!samePaths(result.remainingPaths,expected.remainingPaths))return hold('Remaining changes differ from preflight observation');
+  const next=structuredClone(state);next.target.head=result.commit;
+  next.commits=[...state.commits??[],{requestId:request.requestId,taskId:task.id,kind:d.kind,purpose:d.kind,expectedParent:expected.parent,expectedTree:expected.tree,commit:result.commit,parent:result.parent,tree:result.tree,paths:[...result.paths],fingerprint:d.fingerprint,actorRef:request.actorRef}];
+  if(d.kind==='task')next.tasks.find(t=>t.id===task.id).status='committed';
+  else for(const document of next.documents)document.commit=result.commit;
+  const decision=allow('Observed commit matches preflight',{proposedTransition:next});
+  reconciliations.set(decision,{before:JSON.stringify(state),after:JSON.stringify(next),expected:JSON.stringify(expected)});
+  return decision;
+ }catch(error){return hold('Git validation failed: '+error.message);}
+}

package/codex/skill/runtime/git-evidence.mjs

@@ -0,0 +1,114 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+
+const oid=value=>typeof value==='string'&&/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+const hash=bytes=>'sha256:'+crypto.createHash('sha256').update(bytes).digest('hex');
+const equal=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const text=bytes=>new TextDecoder('utf-8',{fatal:true}).decode(bytes);
+const gitPath=value=>typeof value==='string'&&value.length>0&&!/[\\\x00\r\n:]/.test(value)&&!value.startsWith('/')&&!value.split('/').some(p=>!p||p==='.'||p==='..');
+const absolute=value=>typeof value==='string'&&path.isAbsolute(value)&&path.normalize(value)===value;
+const unique=values=>new Set(values).size===values.length;
+const samePaths=(a,b)=>Array.isArray(a)&&Array.isArray(b)&&unique(a)&&unique(b)&&equal([...a].sort(),[...b].sort());
+function paths(bytes){
+ const output=text(bytes);if(!output)return [];
+ if(!output.endsWith('\0'))throw Error('Incomplete Git path output');
+ const result=output.slice(0,-1).split('\0');if(!result.every(gitPath)||!unique(result))throw Error('Invalid Git paths');return result;
+}
+/** The default transport is read-only, bounded and shell-free. Inherited Git
+ * overrides and optional locks are disabled; no caller environment is accepted. */
+function defaultRunner({args,cwd}){
+ 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','--literal-pathspecs','-c','core.fsmonitor=false','-c','core.untrackedCache=false',...args],{cwd,env,encoding:'buffer',maxBuffer:16*1024*1024,timeout:10000,windowsHide:true});
+}
+/** Construct Git tree object IDs in memory from the complete stage-0 index.
+ * No write-tree/hash-object -w or other repository mutation is needed. */
+function indexTree(bytes,objectLength){
+ const entries=text(bytes);if(entries&&!entries.endsWith('\0'))throw Error('Incomplete index');
+ const root=new Map();
+ for(const entry of entries?entries.slice(0,-1).split('\0'):[]){
+  const match=/^(100644|100755|120000|160000) ([a-f0-9]+) ([0-3])\t([\s\S]+)$/.exec(entry);
+  if(!match||match[3]!=='0'||!oid(match[2])||match[2].length!==objectLength||!gitPath(match[4]))throw Error('Invalid or unmerged index');
+  const parts=match[4].split('/');let directory=root;
+  for(const part of parts.slice(0,-1)){if(directory.has(part)&&!(directory.get(part) instanceof Map))throw Error('Index path collision');if(!directory.has(part))directory.set(part,new Map());directory=directory.get(part);}
+  const name=parts.at(-1);if(directory.has(name))throw Error('Duplicate index path');directory.set(name,{mode:match[1],object:match[2]});
+ }
+ const algorithm=objectLength===64?'sha256':'sha1';
+ const tree=directory=>{
+  const rows=[...directory].map(([name,value])=>({name,directory:value instanceof Map,value}));
+  rows.sort((a,b)=>Buffer.compare(Buffer.from(a.name+(a.directory?'/':'')),Buffer.from(b.name+(b.directory?'/':''))));
+  const body=Buffer.concat(rows.map(row=>Buffer.concat([Buffer.from(`${row.directory?'40000':row.value.mode} ${row.name}\0`),Buffer.from(row.directory?tree(row.value):row.value.object,'hex')])));
+  return crypto.createHash(algorithm).update(Buffer.from(`tree ${body.length}\0`)).update(body).digest('hex');
+ };
+ return tree(root);
+}
+function documentInput(documents,target){
+ if(!Array.isArray(documents))throw Error('Documents must be an array');
+ for(const d of documents){
+  if(!d||!['spec','plan'].includes(d.kind)||!gitPath(d.gitPath)||!absolute(d.path)||d.path!==path.join(target.realpath,...d.gitPath.split('/'))||!/^sha256:[a-f0-9]{64}$/.test(d.contentHash)||typeof d.approvalRef!=='string'||!d.approvalRef||(d.commit!==undefined&&!oid(d.commit)))throw Error('Invalid approved document');
+ }
+ if(!unique(documents.map(d=>d.gitPath))||!unique(documents.map(d=>d.kind)))throw Error('Duplicate document');
+ const commits=new Set(documents.map(d=>d.commit));if(commits.size>1)throw Error('Documents must share a single commit');
+}
+/** Read actual objects/index and compare approved documents. gitRunner is a
+ * trusted transport injection for tests/providers, never a tool argument. */
+export async function readGitEvidence({target,documents=[],gitRunner=defaultRunner,env,...options}={}){
+ if(!target||!absolute(target.realpath)||!absolute(target.gitCommonDir)||!oid(target.head)||!(target.branch===null||typeof target.branch==='string'&&target.branch)||typeof gitRunner!=='function'||env!==undefined&&(!env||Object.keys(env).length)||Object.keys(options).length)throw Error('Invalid Git evidence target or overrides');
+ documentInput(documents,target);
+ const run=async args=>{
+  const result=await gitRunner({args,cwd:target.realpath});
+  if(!result||result.status!==0||result.error||!(typeof result.stdout==='string'||Buffer.isBuffer(result.stdout)))throw Error('Git evidence query failed: '+args[0]);
+  return Buffer.isBuffer(result.stdout)?result.stdout:Buffer.from(result.stdout);
+ };
+ const line=async args=>{const output=text(await run(args));if(!output.endsWith('\n')||output.slice(0,-1).includes('\n'))throw Error('Invalid Git scalar output');return output.slice(0,-1);};
+ const observeTarget=async()=>{
+  const realpath=await line(['rev-parse','--show-toplevel']);
+  const gitCommonDir=await line(['rev-parse','--path-format=absolute','--git-common-dir']);
+  const head=await line(['rev-parse','HEAD']);
+  // Detached HEAD is deliberately represented as null, never silently rebound.
+  let branch;
+  if(target.branch===null){
+   const r=await gitRunner({args:['symbolic-ref','--quiet','--short','HEAD'],cwd:target.realpath});
+   if(r?.status!==1||r.error)throw Error('Expected detached HEAD');branch=null;
+  }else branch=await line(['symbolic-ref','--quiet','--short','HEAD']);
+  if(realpath!==target.realpath||gitCommonDir!==target.gitCommonDir||head!==target.head||branch!==target.branch)throw Error('Git target or HEAD drift');
+  return {...target,realpath,gitCommonDir,head,branch};
+ };
+ const observedTarget=await observeTarget();
+ const index=await run(['ls-files','--stage','-z']);
+ const stagedPaths=paths(await run(['diff','--cached','--name-only','-z','--']));
+ const diff=await run(['diff','--cached','--binary','--no-ext-diff','--no-textconv','--']);
+ const workingPaths=paths(await run(['diff','--name-only','-z','--no-ext-diff','--no-textconv','--']));
+ const untrackedPaths=paths(await run(['ls-files','--others','--exclude-standard','-z']));
+ const observedDocuments=[];let docsCommit;
+ if(documents.length){
+  const commit=documents[0].commit;
+  if(commit){
+   const metadata=text(await run(['show','--no-patch','--format=%P%n%T',commit])).trimEnd().split('\n');
+   if(metadata.length!==2||!oid(metadata[0])||!oid(metadata[1]))throw Error('Expected a single-parent document commit');
+   await run(['merge-base','--is-ancestor',commit,target.head]);
+   const committedPaths=paths(await run(['diff-tree','--no-commit-id','--name-only','-r','-z',commit,'--']));
+   if(!samePaths(committedPaths,documents.map(d=>d.gitPath)))throw Error('Document commit must contain the exact approved document set');
+   const rows=pathsForTree(await run(['ls-tree','-r','-z',commit,'--',...documents.map(d=>d.gitPath)]));
+   if(!samePaths(rows.map(row=>row.path),documents.map(d=>d.gitPath))||rows.some(row=>!['100644','100755'].includes(row.mode)||row.type!=='blob'))throw Error('Documents must be regular committed files');
+   docsCommit={commit,parent:metadata[0],tree:metadata[1],paths:committedPaths,documents:structuredClone(documents)};
+  }
+  const stagedModes=new Map(text(index).split('\0').filter(Boolean).map(entry=>{const m=/^(\d+) [a-f0-9]+ 0\t([\s\S]+)$/.exec(entry);return m?[m[2],m[1]]:[];}));
+  for(const d of documents){
+   if(!commit&&!['100644','100755'].includes(stagedModes.get(d.gitPath)))throw Error('Documents must be regular staged files');
+   const bytes=await run(['show',`${commit??''}:${d.gitPath}`]);
+   const observedHash=hash(bytes);if(observedHash!==d.contentHash)throw Error('Approved document hash mismatch');
+   observedDocuments.push({...d,observedHash});
+  }
+ }
+ // Reading a concurrent index twice is conservative: never publish a mixed
+ // snapshot or infer completion after the target changed during observation.
+ if(!(await run(['ls-files','--stage','-z'])).equals(index)||!(await run(['diff','--cached','--binary','--no-ext-diff','--no-textconv','--'])).equals(diff))throw Error('Index changed during Git observation');
+ await observeTarget();
+ return {target:observedTarget,indexTree:indexTree(index,target.head.length),stagedPaths,stagedFingerprint:hash(diff),workingPaths,untrackedPaths,documents:observedDocuments,...(docsCommit?{docsCommit}:{})};
+}
+function pathsForTree(bytes){
+ const output=text(bytes);if(!output||!output.endsWith('\0'))throw Error('Invalid document tree');
+ return output.slice(0,-1).split('\0').map(entry=>{const match=/^(\d+) (blob|tree|commit) ([a-f0-9]+)\t([\s\S]+)$/.exec(entry);if(!match||!oid(match[3])||!gitPath(match[4]))throw Error('Invalid document tree entry');return {mode:match[1],type:match[2],path:match[4]};});
+}

package/codex/skill/runtime/git-query.mjs

@@ -0,0 +1,88 @@
+/** Shared, non-executing Git query classifier. Target/configuration overrides fail closed. */
+const deny = reason => ({allowed:false,reason});
+const isGit = word => /(?:^|[\\/])git(?:\.exe)?$/i.test(word);
+export function validateGitPolicy(policy) {
+  if (!policy || policy.schemaVersion !== 1 || !Array.isArray(policy.globalValueOptions) || !Array.isArray(policy.globalFlags) || !policy.commands || typeof policy.commands !== 'object' || Array.isArray(policy.commands)) throw Error('Invalid Git policy');
+  const strings = list => Array.isArray(list) && list.every(x=>typeof x === 'string' && x.startsWith('-'));
+  if (!strings(policy.globalValueOptions) || !strings(policy.globalFlags) || !Object.keys(policy.commands).length) throw Error('Invalid Git policy');
+  for (const rule of Object.values(policy.commands)) if (!rule || !strings(rule.flags) || !strings(rule.values) || !['any','none','query','list'].includes(rule.positionals)) throw Error('Invalid Git command policy');
+  return policy;
+}
+// This deliberately supports a small shell grammar, rather than executing a shell.
+function tokenize(command) {
+  const tokens=[]; let word='', started=false, quote=null;
+  for(let i=0;i<command.length;i++) {
+    const char=command[i];
+    if(char==='\\' && /[\r\n]/.test(command[i+1]??'')) throw Error('Escaped line terminator');
+    if(quote) {
+      if(char===quote){quote=null;continue;}
+      if(quote==='"' && /[$`]/.test(char)) throw Error('Dynamic shell syntax');
+      // Preserve Windows paths in quoted executable names.
+      if(char==='\\' && quote==='"' && /["\\$`]/.test(command[i+1]??'')){word+=command[++i];continue;}
+      word+=char;continue;
+    }
+    if(char==='"'||char==="'"){quote=char;started=true;continue;}
+    if(/[\r\n\x00<>`$(){}&]/.test(char) && !(char==='&'&&command[i+1]==='&')) throw Error('Unsupported shell syntax');
+    if(char===';'||char==='|'||char==='&') {
+      if(started){tokens.push(word);word='';started=false;}
+      const operator=command.slice(i,i+2); if(operator==='&&'||operator==='||')i++;
+      tokens.push({operator:operator==='&&'||operator==='||'?operator:char});continue;
+    }
+    if(/\s/.test(char)){if(started){tokens.push(word);word='';started=false;}continue;}
+    if(char==='\\') {if(i+1>=command.length)throw Error('Incomplete escape'); word+=command[++i];started=true;continue;}
+    if(char==='#')throw Error('Unsupported shell comment');
+    word+=char;started=true;
+  }
+  if(quote)throw Error('Unclosed quote'); if(started)tokens.push(word);return tokens;
+}
+function classifyWords(words,policy,depth) {
+  if(!words.length)return deny('Empty shell segment');
+  const executable=words[0].split(/[\\/]/).at(-1).toLowerCase();
+  if(['sh','bash','sh.exe','bash.exe'].includes(executable)) {
+    if(depth>=4 || words.length!==3 || words[1]!=='-c')return deny('Unsupported shell wrapper');
+    return classifyGitCommand(words[2],policy,depth+1);
+  }
+  if(!isGit(words[0]))return words.some(isGit)?deny('Unsupported indirect Git invocation'):{allowed:true};
+  let i=1;
+  while(i<words.length && words[i].startsWith('-')) {
+    const option=words[i++],equal=option.indexOf('='),key=equal<0?option:option.slice(0,equal);
+    if(policy.globalFlags.includes(option))continue;
+    // A query must stay on the target already resolved by the trusted adapter.
+    if(['-C','--git-dir','--work-tree','--namespace','--config-env','-c'].includes(key))return deny('Git target or configuration override');
+    if(!policy.globalValueOptions.includes(key))return deny('Unknown Git global option');
+    if(equal<0 && (i>=words.length || words[i++].startsWith('-')))return deny('Missing Git option value');
+    if(equal>=0 && !option.slice(equal+1))return deny('Missing Git option value');
+  }
+  const combined=`${words[i]} ${words[i+1]}`;
+  const name=Object.hasOwn(policy.commands,combined)?(i+=2,combined):words[i++];
+  const rule=Object.hasOwn(policy.commands,name)?policy.commands[name]:null; if(!rule)return deny('Git mutation or unknown subcommand');
+  let positions=0,query=false,list=false,paths=false;
+  for(;i<words.length;i++) {
+    const arg=words[i];
+    if(arg==='--no-index')return deny('Query outside repository');
+    if(arg!=='--'&&!arg.startsWith('-')&&(/^(?:[\\/]|[A-Za-z]:)/.test(arg)||arg.split(/[\\/]/).includes('..')||arg.includes(':(')))return deny('Query path escapes target');
+    if(arg==='--' && rule.positionals==='any'){paths=true;continue;}
+    if(!paths && arg.startsWith('-')) {
+      if(/^-[0-9]+$/.test(arg)&&rule.flags.includes('-<count>'))continue;
+      const equal=arg.indexOf('='),key=equal<0?arg:arg.slice(0,equal);
+      if(rule.values.includes(key)) {if(equal<0 && (i+1>=words.length||words[++i].startsWith('-')))return deny('Missing query option value'); if(equal>=0&&!arg.slice(equal+1))return deny('Missing query option value');continue;}
+      if(!rule.flags.includes(arg))return deny('Unknown or mutating Git option');
+      if(['--get','--get-all','--get-regexp','--list','-l'].includes(arg))query=true;
+      if(['--list','-l','--show-current'].includes(arg))list=true;
+    } else positions++;
+  }
+  if(rule.positionals==='none'&&positions || rule.positionals==='query'&&(!query||positions>1) || rule.positionals==='list'&&positions&&!list)return deny('Git write or unsupported arguments');
+  return {allowed:true};
+}
+export function classifyGitCommand(command,policy,depth=0) {
+  try {
+    validateGitPolicy(policy);
+    if(typeof command!=='string'||!command.trim())return deny('Missing shell command');
+    const tokens=tokenize(command); let words=[];
+    for(const token of [...tokens,{operator:'end'}]) {
+      if(typeof token==='string'){words.push(token);continue;}
+      const result=classifyWords(words,policy,depth);if(!result.allowed)return result;words=[];
+    }
+    return {allowed:true};
+  } catch {return deny('Invalid policy or unsupported command syntax');}
+}

package/codex/skill/runtime/identity.mjs

@@ -0,0 +1,27 @@
+import {validateWorkflowState, text} from './schema.mjs';
+import {ROLES} from './operations.mjs';
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+/** Observation is supplied by the trusted platform provider, never agent/tool arguments. */
+export function registerAgentObservation(state, observation){
+ validateWorkflowState(state);
+ const result=(decision,reason)=>({decision,reason,state,proposedTransition:null});
+ if(!observation||!text(observation.actorRef)||!text(observation.taskId)||!text(observation.observationRef)||!ROLES.includes(observation.role))return result('hold','complete observed identity required');
+ const old=state.identities.find(i=>i.actorRef===observation.actorRef);
+ const lease=state.leases.find(l=>l.actorRef===observation.actorRef);
+ if(old&&(old.taskId!==observation.taskId||old.role!==observation.role))return result('deny','identity rebind');
+ if(lease?.status==='retired')return result('deny','retired identity');
+ const p=observation.provenance;
+ if(!text(observation.eventRef)||!text(observation.correlationRef)||!p||p.source!=='platform-event'||p.eventRef!==observation.eventRef||p.actorRef!==observation.actorRef||p.platform!==observation.platform||p.correlationRef!==observation.correlationRef||p.verification?.status!=='verified'||!text(p.verification.verifierRef)||p.verification.sourceRef!==observation.eventRef)return result('hold','trusted platform spawn observation and correlation required');
+ const assignment=state.assignments.find(a=>a.assignmentId===observation.assignmentId&&a.correlationRef===observation.correlationRef);
+ if(!assignment||assignment.taskId!==observation.taskId||assignment.role!==observation.role||assignment.platform!==observation.platform||assignment.approvalRef!==observation.approvalRef||!same(assignment.paths,observation.paths)||!same(assignment.operations,observation.operations))return result('hold','observation does not match approved pending assignment');
+ if(old){
+  if(assignment.status==='active'&&assignment.actorRef===old.actorRef&&old.observationRef===observation.observationRef&&lease?.status==='active')return result('allow','same confirmed observation');
+  return result('hold','existing identity cannot be assigned through another observation');
+ }
+ if(assignment.status!=='pending'||assignment.actorRef!==null||lease)return result('hold','new identity requires pending unbound assignment');
+ const task=state.tasks.find(t=>t.id===assignment.taskId);if(!task||['accepted','committed'].includes(task.status))return result('hold','task no longer accepts agent observations');
+ const next=structuredClone(state);const active=next.assignments.find(a=>a.assignmentId===assignment.assignmentId);active.actorRef=observation.actorRef;active.status='active';active.observationRef=observation.observationRef;
+ next.identities.push({actorRef:observation.actorRef,taskId:observation.taskId,role:observation.role,observationRef:observation.observationRef});next.leases.push({actorRef:observation.actorRef,taskId:observation.taskId,status:'active'});next.tasks.find(t=>t.id===assignment.taskId).status='assigned';
+ validateWorkflowState(next);
+ return {decision:'allow',reason:'matching observed spawn bound to pending assignment',state:next,proposedTransition:next};
+}

package/codex/skill/runtime/operations.mjs

@@ -0,0 +1,6 @@
+/** Canonical semantic operations, independent of platform tool aliases. */
+export const ROLES = Object.freeze(['orchestrator','scouter','planner','coder','qa','reviewer']);
+export const GIT_OPERATIONS = Object.freeze(['stage','commit','push','merge','rebase','reset','branch-create','branch-switch','worktree-create','worktree-remove']);
+export const EXTERNAL_OPERATIONS = Object.freeze(['push','merge','deploy','publish','external-message']);
+export const OPERATIONS = Object.freeze(['read','draft','write','check','qa','review','temporary-write','operational-query','install','prepare-target','request-approval','assign-agent','accept','transition','scope-expansion','indirect-bypass',...new Set([...GIT_OPERATIONS,...EXTERNAL_OPERATIONS])]);
+export const ROLE_OPERATIONS = Object.freeze({orchestrator:['read','write','check','prepare-target','request-approval','assign-agent','accept','transition','install',...GIT_OPERATIONS,...EXTERNAL_OPERATIONS],scouter:['read'],planner:['read','draft'],coder:['read','write','check'],qa:['read','check','temporary-write'],reviewer:['read','review']});