@milpa/comal 0.1.6 → 0.2.0

package/src/workflows/source-task-v1.mjs

@@ -0,0 +1,124 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {digest,immutable} from '../operations.mjs';
+import Ajv from 'ajv';
+import {compileGovernance} from '../governance.mjs';
+import {workProjection,registerWorkOperations} from '../work-plan.mjs';
+import {auditExecution} from '../audit.mjs';
+import {GitWorkspaces} from '../git-workspaces.mjs';
+import {inspectGitSource} from '../git-source.mjs';
+import {gitIntegrationDefinitions} from '../git-integration-operations.mjs';
+import {acquireProcessLock} from '../process-lock.mjs';
+import {SOURCE_TASK_MECHANISM,savedSourceTask,sourceTaskFactValid} from '../source-task-proof.mjs';
+const source='source_task_host',empty={type:'object',properties:{},additionalProperties:false},fail=(message,code='SOURCE_TASK_CONFLICT',details)=>Object.assign(new Error(message),{code,...(details?{details}:{})});
+const str=n=>({type:'string',minLength:1,maxLength:n});
+export const sourceTaskSchema={type:'object',additionalProperties:false,required:['criterion','editors','verification','target'],properties:{criterion:str(4000),target:gitIntegrationDefinitions[0].input_schema.properties.target,source:{type:'string',enum:['head','working']},editors:{type:'array',minItems:1,maxItems:3,items:{type:'object',additionalProperties:false,required:['id','prompt'],properties:{id:{type:'string',pattern:'^[a-zA-Z0-9][a-zA-Z0-9_-]{0,39}$'},prompt:str(12000),max_turns:{type:'integer',minimum:1,maximum:12}}}},verification:gitIntegrationDefinitions[0].input_schema.properties.verification}};
+const validateSourceTask=new Ajv({strict:false,allErrors:true}).compile(sourceTaskSchema);
+export function normalizeSourceTask(task){if(!validateSourceTask(task))throw fail('Invalid source contract: '+validateSourceTask.errors.map(e=>e.instancePath+' '+e.message).join('; '));if(Buffer.byteLength(JSON.stringify(task))>32768||new Set(task.editors.map(e=>e.id)).size!==task.editors.length)throw fail('Source task must be at most 32 KiB with unique editor IDs.');return immutable({...structuredClone(task),source:task.source??'working'});}
+export async function readSourceTask(file){const bytes=await readFile(file);if(bytes.length>32768)throw fail('Source task exceeds 32 KiB.');return normalizeSourceTask(JSON.parse(bytes));}
+export async function prepareSourceTaskV1({cwd,store,house,executor,policy,subagents,integrationOperations,workspace,task,sessionId,actor={id:'root-agent',kind:'agent'},fault=async()=>{}}){
+ let book=await store.load(sessionId),accepted=savedSourceTask(book);if(accepted&&accepted.mechanism!==SOURCE_TASK_MECHANISM)throw fail('This frozen coordinator only restores source-task v1.');if(!task&&!accepted)return null;if(!book.journalAudit.verified||auditExecution(book,house.stateContext()).violations.length)throw fail('A verified source-task journal is required.','AUDIT_INVALID');
+ const brief=normalizeSourceTask(task??accepted.task),taskDigest=digest(brief),goal=book.goal?.id??null,epoch=book.rows.findLastIndex(r=>r.type==='reset');
+ if(accepted&&(!sourceTaskFactValid(accepted)||accepted.task_digest!==taskDigest||digest(accepted.actor)!==digest(actor)))throw fail('The original source contract/owner changed. Start a new session for another accepted criterion.');
+ if(!accepted&&workProjection(book))throw fail('This session already has accepted work. A source contract cannot replace it.');
+ for(const name of ['AgentBatch','AgentContinue','AgentResume',...gitIntegrationDefinitions.map(t=>t.name)])if(!house.registry.get(name))throw fail('Missing native source coordination operation: '+name);
+ registerWorkOperations({store,house});
+ const plan=compileGovernance(JSON.parse(await readFile(new URL('../../governance/source-task-v1.json',import.meta.url))),['runtime:source-task.scope','runtime:source-task.close']);
+ if(!integrationOperations||!workspace?.registerSettlement)throw fail('The source task needs native integration and settlement ports.');
+ const ownNames=new Set(['SourceDeliver','SourceStatus','SourceVerify','SourceEvidence']),publicNames=new Set(['SourceDeliver','SourceStatus','SourceEvidence','EvidenceRead']);
+ const contract={id:'source-task',title:'Implement and verify accepted source contract',criterion:brief.criterion,capabilities:['workspace.git'],checks:[{step_id:'combined-source',operation:'SourceVerify',arguments:{},assertions:[{kind:'json_equals',pointer:'/status',value:'verified'}]}]};
+ const state=async({historical=false}={})=>{const s=await store.load(sessionId),a=savedSourceTask(s);if(!s.journalAudit.verified||auditExecution(s,house.stateContext()).violations.length||!sourceTaskFactValid(a)||a.task_digest!==taskDigest||a.binding.reset_ref!==s.rows.findLastIndex(r=>r.type==='reset'))throw fail('The accepted source task/reset scope changed.','SOURCE_TASK_SCOPE_CHANGED');const execution=s.rows.find(r=>r.type==='source_task_execution_bound'&&r.source===source&&r.task_digest===taskDigest);if(!historical&&execution&&execution.goal_owner!==(s.goal?.status==='active'?s.goal.id:null))throw fail('The original active source execution goal changed.','SOURCE_TASK_SCOPE_CHANGED');const work=workProjection(s,house.stateContext());if(work){const defs=s.rows[work.plan.ref]?.tasks,definition=defs?.[0]&&Object.fromEntries(Object.entries(defs[0]).filter(([k])=>!['definition_digest','work_digest'].includes(k)));if(work.plan.version!==1||defs.length!==1||digest(definition)!==digest({...contract,depends_on:[]}))throw fail('The accepted source work/check definition changed.');}return s;};
+ const inputForEditors={tasks:brief.editors.map(e=>({prompt:e.prompt,description:e.id,isolation:'git',git_source:brief.source,work_tracking:'parent',...(e.max_turns?{max_turns:e.max_turns}:{})}))};
+ const stages=s=>s.rows.filter(r=>r.type==='source_task_stage'&&r.source===source&&r.task_digest===taskDigest&&r.session_id===sessionId);
+ const preparedStage=(s,key)=>stages(s).find(r=>r.key===key);
+ const proposal=(s,stage)=>s.rows.find(r=>r.type==='house_proposal'&&r.call_id===stage.call_id&&r.operation===stage.operation&&r.arguments_digest===stage.arguments_digest&&digest(r.actor)===digest(actor));
+ const stageReceipt=(s,stage)=>{const p=proposal(s,stage);return p&&s.rows.findLast(r=>r.type==='house_receipt'&&r.invocation_id===p.invocation_id);};
+ const evidenceCall=call=>{const {integration_id,...input}=call.input;return{name:'SourceEvidence',input};};
+ const projectEvidence=items=>items?.map(item=>({...item,read_call:evidenceCall(item.read_call)}))??[];
+ const parse=r=>{if(r?.status!=='returned'||r.output_truncated||r.output_digest!==digest(r.output))throw fail('The original native stage did not return a complete durable outcome.','SOURCE_TASK_STAGE_CLOSED',{receipt_id:r?.invocation_id,code:r?.code??null});return JSON.parse(r.output);};
+ const recordCall=async(name,input,o)=>o.recordWork({type:'source_task_call_prepared',source,operation:name,arguments_digest:digest(input),task_digest:taskDigest});
+ const frame=async(o,options)=>{if(o.sessionId!==sessionId||digest(o.actor)!==digest(actor))throw fail('The accepted source task belongs to another actor/session.','SOURCE_TASK_OWNER');await state(options);await o.revalidate();};
+ const stage=async(key,name,input,o)=>{
+  let s=await state(),saved=preparedStage(s,key);if(saved&&(saved.operation!==name||saved.arguments_digest!==digest(input)||digest(saved.input)!==digest(input)))throw fail('A source stage cannot replace its original native intent.');
+  if(!saved){await o.recordWork({type:'source_task_stage',source,task_digest:taskDigest,key,operation:name,input,arguments_digest:digest(input),call_id:randomUUID()});s=await state();saved=preparedStage(s,key);}
+  const p=proposal(s,saved);if(p){const r=stageReceipt(s,saved);if(!r)throw fail('A source stage has an unsettled native dispatch. Recover the same session; no effect was replayed.','SOURCE_TASK_UNCERTAIN');return{value:r.status==='returned'?parse(r):null,receipt:r,proposal:p,stage:saved};}
+  await frame(o);if(key==='editors'&&(await inspectGitSource({cwd,signal:o.signal})).source_identity!==savedSourceTask(await state()).binding.source_identity)throw fail('The accepted parent source changed before editor launch.','SOURCE_TASK_STALE');await o.recordWork({type:'source_task_dispatch',source,task_digest:taskDigest,stage_ref:s.rows.indexOf(saved),stage_digest:saved.audit.sha256,key});
+  await o.invoke(name,input,{signal:o.signal,callId:saved.call_id,beforeEffect:()=>frame(o)});s=await state();const r=stageReceipt(s,saved);return{value:parse(r),receipt:r,proposal:proposal(s,saved),stage:saved};
+ };
+ // Retry only a lost handler reply, preserving the native intent/attempt. The
+ // kernel remains responsible for refusing an uncertain mutation or check.
+ const recoverStage=async(key,name,input,o)=>{
+  for(let n=0;;n++){
+   const value=await stage(n?key+'-recovered-'+n:key,name,input,o);
+   if(value.value)return value;
+   if(!value.receipt.recovery&&!['HOUSE_RECOVERY_NOT_STARTED','HOUSE_RECOVERY_NOT_DISPATCHED'].includes(value.receipt.code))throw fail('The original native stage is closed; no fresh intent was substituted.','SOURCE_TASK_STAGE_CLOSED',{receipt_id:value.receipt.invocation_id});
+  }
+ };
+ const integration=async(options)=>{const s=await state(options),saved=preparedStage(s,'prepare');if(!saved)return null;const r=stageReceipt(s,saved);if(r?.status==='returned')return parse(r).integration_id;const intent=s.rows.find(row=>row.type==='git_integration_intent'&&row.operation==='GitIntegrationPrepare'&&row.input.request_id==='source-'+taskDigest.slice(0,40)&&row.owner_digest===digest({actor,session_id:sessionId}));return intent?.binding.resolved.integration_id??null;};
+ const inspect=async(o,{invoke=true,historical=false}={})=>{
+  const id=await integration({historical});if(!id)return{status:'not_prepared',task_digest:taskDigest,asked:'unjudged'};
+  if(!invoke)throw fail('A native observation context is required.');
+  const result=await integrationOperations.status({integration_id:id},o),status=result.integrations[0];
+  const kernel=new GitWorkspaces({cwd}),resource=await kernel.status(id,{owner:{actor,session_id:sessionId}}),prepared=resource.completed.find(r=>r.action==='integration_prepare')?.output;
+  let target=null,current=null;if(prepared){target=await kernel.rootRef('refs/comal/integrations/'+brief.target,o.signal);current=await inspectGitSource({cwd:prepared.worktree,signal:o.signal});}
+  const rootSource=await inspectGitSource({cwd,signal:o.signal});
+  const valid=rootSource.source_identity===savedSourceTask(await state({historical})).binding.source_identity&&resource.lifecycle==='retained'&&!resource.pending.length&&status.verification==='passed_declared_checks'&&status.applied===status.candidate&&target===status.candidate&&current?.head===status.candidate&&!current.dirty&&current.source_identity===prepared.source_identity;
+  o.observe?.({kind:'source_task_ref_observation',task_digest:taskDigest,integration_id:id,target_ref:'refs/comal/integrations/'+brief.target,observed_commit:target,candidate:status.candidate,source_identity:current?.source_identity??null});
+  return{status:valid?'verified':'needs_verification',task_digest:taskDigest,integration_id:id,candidate:status.candidate,target_ref:'refs/comal/integrations/'+brief.target,observed_commit:target,verification:status.verification,pending:status.pending,rejected:status.rejected,evidence:projectEvidence(status.evidence),scope:'native_source_and_declared_checks_not_human_acceptance',asked:'unjudged'};
+ };
+ const locks=new Map();
+ const lock=async o=>{const lease=await acquireProcessLock(path.join(store.dir,'.source-task-'+digest({sessionId,actor,taskDigest})+'.lock'),{resource:{session_id:sessionId,invocation_id:o.invocation_id},validate:async old=>{const s=await state();if(old.resource?.session_id!==sessionId||!s.rows.some(r=>r.type==='house_receipt'&&r.invocation_id===old.resource.invocation_id))throw fail('Recover the original coordinator before continuing.','SOURCE_TASK_UNCERTAIN');}}).catch(error=>{if(error.code==='SESSION_IN_USE')throw fail('The accepted source pipeline is already running.','SOURCE_TASK_BUSY');throw error;});locks.set(o.invocation_id,lease);};
+ const settle=async({invocation_id,receiptRecorded})=>{const lease=locks.get(invocation_id);if(!lease)return;locks.delete(invocation_id);if(receiptRecorded)await lease.release();else await lease.file.close();};
+ const deliver=async(input,o)=>{
+  if(policy.mode==='plan')throw fail('Plan mode cannot start the source delivery pipeline.','HOUSE_REFUSED');
+  await lock(o);await frame(o);const entered=await state();if(!entered.rows.some(r=>r.type==='source_task_execution_bound'&&r.source===source&&r.task_digest===taskDigest))await o.recordWork({type:'source_task_execution_bound',source,task_digest:taskDigest,goal_owner:entered.goal?.status==='active'?entered.goal.id:null});if(workProjection(await state(),house.stateContext()).counts.done===1){const observed=JSON.parse(await o.invoke('SourceVerify',{}, {signal:o.signal}));if(observed.status!=='verified')throw fail('The recorded delivery is historical; its source or current target changed.','SOURCE_TASK_STALE');return{...observed,status:'done',reused:true};}
+  await fault('before_editors',{o});let s=await state(),launch=preparedStage(s,'editors'),batch;
+  if(!launch||!proposal(s,launch))batch=await stage('editors','AgentBatch',inputForEditors,o);
+  else{const p=proposal(s,launch),r=stageReceipt(s,launch);if(!r)throw fail('The original editor launch is unsettled; recover it before continuing.','SOURCE_TASK_UNCERTAIN');if(r.status==='returned')batch={value:parse(r),receipt:r,proposal:p};else if(['HOUSE_RECOVERY_CONTINUE','HOUSE_RECOVERY_NOT_DISPATCHED'].includes(r.code))batch=await recoverStage('editors-continue','AgentContinue',{invocation_id:p.invocation_id},o);else throw fail('The original editor batch was refused/failed; it was not restarted.','SOURCE_TASK_EDITORS_CLOSED');}
+  await subagents.reconcile(sessionId);s=await state();launch=preparedStage(s,'editors');const parent=proposal(s,launch),runs=(await subagents.runs(sessionId)).filter(run=>run.parent_invocation_id===parent.invocation_id);
+  for(const run of runs)if(['paused','interrupted'].includes(run.status)&&input.resume_editors===true){const resumed=await recoverStage('resume-'+run.run_id+'-'+run.turn_id,'AgentResume',{run_id:run.run_id},o);if(!resumed.value)throw fail('The original editor resume is closed; inspect its native outcome.','SOURCE_TASK_STAGE_CLOSED');}
+  const current=(await subagents.runs(sessionId)).filter(run=>run.parent_invocation_id===parent.invocation_id);if(current.length!==brief.editors.length||current.some(run=>run.status!=='completed'||!run.source_offer))return{status:'needs_editor_attention',task_digest:taskDigest,editors:current.map(r=>({run_id:r.run_id,status:r.status,turn_state:r.turn_state,error:r.error,result_read_call:r.result_read_call})),next_action:'Inspect evidence; SourceDeliver resume_editors:true explicitly resumes only paused/interrupted original editors. No new batch is created.',asked:'unjudged'};
+  await fault('editors_returned',{o,runs:current});
+  const prepInput={request_id:'source-'+taskDigest.slice(0,40),target:brief.target,run_ids:current.map(r=>r.run_id),verification:brief.verification};const prep=await recoverStage('prepare','GitIntegrationPrepare',prepInput,o);
+  const id=prep.value.integration_id;await fault('prepared',{o,integration_id:id});let status=JSON.parse(await o.invoke('GitIntegrationStatus',{integration_id:id},{signal:o.signal})).integrations[0];
+  if(status.verification!=='passed_declared_checks'){
+   const failed=status.rejected.filter(r=>r.action==='integration_verify').length;
+   if(failed&&!input.retry_checks)return{status:'needs_correction',task_digest:taskDigest,integration_id:id,evidence:projectEvidence(status.evidence),next_action:'Accepted combined checks failed. Criteria remain immutable. Inspect/correct source before a deliberate retry; no check was repeated.',asked:'unjudged'};
+   const number=failed?String(failed):'first',attempt_id='source-check-'+number;await recoverStage('verify-'+number,'GitIntegrationVerify',{integration_id:id,attempt_id},o);
+  }
+  await fault('verified',{o,integration_id:id});status=JSON.parse(await o.invoke('GitIntegrationStatus',{integration_id:id},{signal:o.signal})).integrations[0];if(status.verification!=='passed_declared_checks')throw fail('No passed native combined verification exists.','SOURCE_TASK_CHECK_FAILED');
+  if(!status.applied)await recoverStage('apply','GitIntegrationApply',{integration_id:id,attempt_id:'source-apply'},o);
+  await fault('applied',{o,integration_id:id});const observed=await inspect(o);if(observed.status!=='verified')throw fail('Current source/ref differs from the passed native candidate.','SOURCE_TASK_STALE');
+  const work=workProjection(await state(),house.stateContext());if(work.counts.done!==1){const check=await o.invoke('WorkStepRun',{task_id:'source-task',plan_version:1,step_id:'combined-source',recheck:true},{signal:o.signal});await fault('close_check_returned',{o,check});await o.invoke('WorkTaskUpdate',{task_id:'source-task',plan_version:1,status:'done'},{signal:o.signal});}
+  await fault('closed',{o});return{...observed,status:'done',editors:current.map(r=>({run_id:r.run_id,source_offer:r.source_offer})),acceptance:'unjudged'};
+ };
+ const publicWork=book=>{const w=workProjection(book,house.stateContext());return{counts:w.counts,cards:w.cards.map(({title,status})=>({title,status})),current:w.current?{title:w.current.title,status:w.current.status,criterion:w.current.criterion}:null,close_call:{name:'SourceDeliver',input:{}},administrative_controls:'host_owned',permissions_from_plan:false};};
+ const evidenceSchema=structuredClone(gitIntegrationDefinitions.find(d=>d.name==='GitIntegrationEvidence').input_schema);delete evidenceSchema.properties.integration_id;evidenceSchema.required=evidenceSchema.required.filter(k=>k!=='integration_id');
+ const defs=[{name:'SourceDeliver',description:'Continue the SAME accepted source task. The house owns editor/check/ref/work identities. Native AgentBatch editors implement source, then native combined checks and reserved-ref CAS establish closure. resume_editors explicitly resumes paused/interrupted originals; retry_checks explicitly retries known failed checks. Never rewrites criteria or restarts an uncertain batch.',input_schema:{type:'object',properties:{resume_editors:{type:'boolean'},retry_checks:{type:'boolean'}},additionalProperties:false},run:deliver},{name:'SourceEvidence',description:'Page exact native combined-check evidence for THIS accepted task, including failed/uncertain outcomes. Use the read_call supplied by SourceStatus. No owner, integration ID, permission or success override.',input_schema:evidenceSchema,run:async(input,o)=>{const id=await integration({historical:true});if(!id)throw fail('No native combined verifier exists yet.','SOURCE_TASK_NOT_PREPARED');const result=await integrationOperations.evidence({...input,integration_id:id},o);if(result.next_call)result.next_call=evidenceCall(result.next_call);return result;}},...['SourceStatus','SourceVerify'].map(name=>({name,description:name==='SourceStatus'?'Read accepted source-task state, original editor outcomes and native evidence; no polling or permission grant.':'Host-only declared check: observe passed native combined checks, current candidate source and actual reserved target. No model success flag.',input_schema:empty,run:async(_,o)=>name==='SourceVerify'?inspect(o):{task:brief,task_digest:taskDigest,work:publicWork(await state({historical:true})),editors:(await subagents.runs(sessionId)).map(r=>({run_id:r.run_id,status:r.status,source_offer:r.source_offer,error:r.error})),integration:await inspect(o,{historical:true})}}))];
+ house.registry.replace([...ownNames],defs.map(d=>({...d,revision:SOURCE_TASK_MECHANISM,steps:d.name==='SourceDeliver',permission:d.name==='SourceDeliver'?d.name:d.name==='SourceEvidence'?'GitIntegrationEvidence':'GitIntegrationStatus',effects:d.name==='SourceDeliver'?{workspace:'unknown',external:'unknown',process:'unknown',authority:'none'}:{workspace:'read',external:'none',process:'read',authority:'none'},run:async(input,o)=>{await recordCall(d.name,input,o);await frame(o,{historical:['SourceStatus','SourceEvidence'].includes(d.name)});return JSON.stringify(await d.run(input,o));}})));
+ if(accepted)await workspace.recoverInterrupted();
+ let setupTurn;
+ if(house.registry.get('ToolPack')){setupTurn=randomUUID();await store.append(sessionId,{type:'tool_turn',source:'capability_host',actor,id:setupTurn,open:true});await executor.execute('ToolPack',{action:'acquire',pack:'workspace.git'});}
+ try{
+ if(!accepted){const observed=JSON.parse(await executor.execute('GitInspect',{}));const binding={cwd,session_id:sessionId,actor,goal_id:goal,reset_ref:epoch,source_identity:observed.source_identity};accepted=await store.append(sessionId,{type:'source_task_accepted',source,mechanism:SOURCE_TASK_MECHANISM,house:cwd,session_id:sessionId,actor,surface:'agent',task:brief,task_digest:taskDigest,governance_plan_hash:plan.plan_hash,binding,binding_digest:digest(binding)});}
+ if(!workProjection(await store.load(sessionId)))await executor.execute('WorkPlanSet',{objective:brief.criterion,expected_version:0,tasks:[contract]});
+ if(workProjection(await store.load(sessionId)).current?.status==='pending')await executor.execute('WorkTaskUpdate',{task_id:'source-task',plan_version:1,status:'in_progress'});
+ if(house.registry.get('ToolPack'))await executor.execute('ToolPack',{action:'acquire',pack:'workspace.git'});
+ }finally{if(setupTurn)await store.append(sessionId,{type:'tool_turn',source:'capability_host',actor,id:setupTurn,open:false});}
+ const scope=async v=>{if(v.actor.kind==='human')return true;try{await state({historical:['SourceStatus','SourceEvidence'].includes(v.operation)&&v.session_id===sessionId});}catch(error){return{allowed:false,reason:error.message};}if(v.session_id!==sessionId)return true;if(digest(v.actor)!==digest(actor))return false;if(ownNames.has(v.operation))return v.operation!=='SourceVerify'||['WorkStepRun','SourceDeliver'].includes(v.parent_operation);if(v.operation==='EvidenceRead')return true;if(v.operation==='AgentBatch')return v.parent_operation==='SourceDeliver'&&digest(v.input)===digest(inputForEditors);if(['AgentContinue','AgentResume','GitIntegrationPrepare','GitIntegrationVerify','GitIntegrationApply'].includes(v.operation))return v.parent_operation==='SourceDeliver';if(v.operation==='GitIntegrationStatus')return ['SourceDeliver','SourceVerify','SourceStatus'].includes(v.parent_operation);if(v.operation==='WorkStepRun')return v.parent_operation==='SourceDeliver'&&digest(v.input)===digest({task_id:'source-task',plan_version:1,step_id:'combined-source',recheck:true});if(v.operation==='WorkTaskUpdate')return v.parent_operation==='SourceDeliver'&&digest(v.input)===digest({task_id:'source-task',plan_version:1,status:'done'});return{allowed:false,reason:'This accepted source task uses native source actions; generic work/shell administration is unavailable.'};};
+ const close=async v=>{if(v.session_id!==sessionId||v.actor.kind==='human'||v.input.status!=='done')return true;const s=await state(),r=s.rows.findLast(row=>row.type==='house_receipt'&&row.operation==='SourceVerify'&&row.status==='returned');if(!r||JSON.parse(r.output).status!=='verified')return false;const value=JSON.parse(r.output),kernel=new GitWorkspaces({cwd});return await kernel.rootRef(value.target_ref)===value.candidate;};
+ if(accepted.governance_plan_hash&&accepted.governance_plan_hash!==plan.plan_hash)throw fail('The saved source workflow policy changed.');
+ await house.activateGovernance({sessionId,plan,bindings:{'runtime:source-task.scope':{revision:SOURCE_TASK_MECHANISM,operations:['*'],configuration_digest:taskDigest,check:scope},'runtime:source-task.close':{revision:SOURCE_TASK_MECHANISM,operations:['WorkTaskUpdate'],configuration_digest:taskDigest,check:close}}});
+ const retireSettlement=workspace.registerSettlement(settle);
+ const project=snapshot=>{const definitions=snapshot.definitions().filter(d=>publicNames.has(d.name)),offered=new Set(definitions.map(d=>d.name));return{...snapshot,definitions:()=>definitions,execute:(name,input,options={})=>{if(options.modelProposed&&!offered.has(name))throw fail('The house owns accepted source bookkeeping; use the offered source actions.','SOURCE_TASK_SCOPE');return snapshot.execute(name,input,options);}};};
+ return{task:brief,taskDigest,system:'Accepted source task: '+JSON.stringify(brief)+'. Use SourceDeliver to implement through the original native editors, combine, verify and close. SourceStatus/SourceEvidence/EvidenceRead inspect missing failure evidence. The house derives IDs and performs declared verification. Never create generic work plans, administer Git, change criteria or infer acceptance. Report limits on refusal/uncertainty.',dispose:()=>{retireSettlement();house.retireGovernance(sessionId);house.registry.replace([...ownNames],[]);},wrap:tools=>({...tools,house,policy,workflow:'source-task',definitions:()=>project(tools.snapshot()).definitions(),snapshot:()=>project(tools.snapshot()),execute:(n,i,o)=>project(tools.snapshot()).execute(n,i,o)}),settle,
+ async finishResult(final,context){
+  let delivery={status:'open',task_digest:taskDigest,asked:'unjudged',scope:'accepted_source_and_declared_checks_not_human_acceptance'};
+  const s=await state({historical:true}),closed=s.rows.slice(context.baseline).findLast(r=>r.type==='house_receipt'&&r.operation==='SourceDeliver'&&r.status==='returned'&&JSON.parse(r.output).status==='done');
+  if(!final.is_error&&!final.work_stop_reason&&closed){try{await state();const observed=JSON.parse(await executor.execute('SourceStatus',{}, {signal:context.signal}));if(observed.integration.status!=='verified')throw fail('Final native source/ref observation failed.','SOURCE_TASK_STALE');const read=(await state()).rows.findLast(r=>r.type==='house_receipt'&&r.operation==='SourceStatus'&&r.status==='returned');delivery={...delivery,status:'verified',receipt_id:read.invocation_id,candidate:observed.integration.candidate,target_ref:observed.integration.target_ref};}catch(error){delivery={...delivery,status:'needs_verification',code:error.code??'SOURCE_TASK_FINAL_CHECK'};final.is_error=true;final.work_stop_reason='verification_failed';final.result+='\nThe final source/ref check failed; delivery remains unverified.';}}
+  else if(!final.is_error){final.is_error=true;final.work_stop_reason??='source_task_open';final.result+='\nThe accepted source delivery remains unverified.';}
+  final.delivery=delivery;await store.append(sessionId,{type:'source_task_delivery',source,...delivery});
+ },
+ async completedResult(calls=[]){const s=await state(),r=s.rows.findLast(r=>r.type==='house_receipt'&&r.operation==='SourceDeliver'&&r.status==='returned'&&calls.some(c=>c.id===r.call_id&&c.name==='SourceDeliver'));if(!r||workProjection(s,house.stateContext()).counts.done!==1)return null;const value=JSON.parse(r.output);if(value.status!=='done')return null;return{terminal:true,receipt_id:r.invocation_id,result:`Source candidate verified at ${value.target_ref}: ${value.candidate}. Accepted combined checks passed; evidence ${r.invocation_id}. Human acceptance remains unjudged.`};}};
+}

package/src/workflows/source-task-v2.mjs

@@ -0,0 +1,227 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {digest,immutable} from '../operations.mjs';
+import {compileGovernance} from '../governance.mjs';
+import {inspectWork,workProjection,registerWorkOperations} from '../work-plan.mjs';
+import {auditExecution} from '../audit.mjs';
+import {GitWorkspaces} from '../git-workspaces.mjs';
+import {inspectGitSource} from '../git-source.mjs';
+import {gitIntegrationDefinitions} from '../git-integration-operations.mjs';
+import {acquireProcessLock} from '../process-lock.mjs';
+import {SOURCE_TASK_MECHANISM_V2 as SOURCE_TASK_MECHANISM,savedSourceTask,sourceTaskFactValid} from '../source-task-proof.mjs';
+const source='source_task_host',empty={type:'object',properties:{},additionalProperties:false},fail=(message,code='SOURCE_TASK_CONFLICT',details)=>Object.assign(new Error(message),{code,...(details?{details}:{})});
+import {normalizeSourceTask} from './source-task-v1.mjs';
+import {sourceTaskRevisions,correctionRequest,correctionEditor} from '../source-task-revision-proof.mjs';
+export async function prepareSourceTaskV2({cwd,store,house,executor,policy,subagents,integrationOperations,workspace,task,sessionId,actor={id:'root-agent',kind:'agent'},fault=async()=>{}}){
+ let book=await store.load(sessionId),accepted=savedSourceTask(book);if(accepted&&accepted.mechanism!==SOURCE_TASK_MECHANISM)throw fail('This coordinator only restores source-task v2.');if(!task&&!accepted)return null;if(!book.journalAudit.verified||auditExecution(book,house.stateContext()).violations.length)throw fail('A verified source-task journal is required.','AUDIT_INVALID');
+ const brief=normalizeSourceTask(task??accepted.task),taskDigest=digest(brief),goal=book.goal?.id??null,epoch=book.rows.findLastIndex(r=>r.type==='reset');
+ if(accepted&&(!sourceTaskFactValid(accepted)||accepted.task_digest!==taskDigest||digest(accepted.actor)!==digest(actor)))throw fail('The original source contract/owner changed. Start a new session for another accepted criterion.');
+ if(!accepted&&workProjection(book))throw fail('This session already has accepted work. A source contract cannot replace it.');
+ for(const name of ['Agent','AgentBatch','AgentContinue','AgentResume',...gitIntegrationDefinitions.map(t=>t.name)])if(!house.registry.get(name))throw fail('Missing native source coordination operation: '+name);
+ registerWorkOperations({store,house});
+ const plan=compileGovernance(JSON.parse(await readFile(new URL('../../governance/source-task-v2.json',import.meta.url))),['runtime:source-task.scope','runtime:source-task.close']);
+ if(!integrationOperations||!workspace?.registerSettlement)throw fail('The source task needs native integration and settlement ports.');
+ const ownNames=new Set(['SourceDeliver','SourceRevise','SourceStatus','SourceVerify','SourceEvidence']),publicNames=new Set(['SourceDeliver','SourceRevise','SourceStatus','SourceEvidence','EvidenceRead']);
+ // Work cards have smaller display bounds than the accepted 4,000-character contract.
+ // Reference the complete immutable criterion; never truncate or replace its acceptance.
+ const contractReference='Implement the complete immutable accepted source task (SHA256 '+taskDigest+'). The full criterion is available through SourceStatus; this card is only its work projection.',criterionLength=Array.from(brief.criterion).length;
+ const contract={id:'source-task',title:'Implement and verify accepted source contract',criterion:criterionLength>1000?contractReference:brief.criterion,capabilities:['workspace.git'],checks:[{step_id:'combined-source',operation:'SourceVerify',arguments:{},assertions:[{kind:'json_equals',pointer:'/status',value:'verified'}]}]};
+ const state=async({historical=false}={})=>{const s=await store.load(sessionId),a=savedSourceTask(s),inspection=inspectWork(s,house.stateContext());if(!s.journalAudit.verified||inspection.audit.violations.length||!sourceTaskFactValid(a)||a.task_digest!==taskDigest||a.binding.reset_ref!==s.rows.findLastIndex(r=>r.type==='reset'))throw fail('The accepted source task/reset scope changed.','SOURCE_TASK_SCOPE_CHANGED');const execution=s.rows.find(r=>r.type==='source_task_execution_bound'&&r.source===source&&r.task_digest===taskDigest);if(!historical&&execution&&execution.goal_owner!==(s.goal?.status==='active'?s.goal.id:null))throw fail('The original active source execution goal changed.','SOURCE_TASK_SCOPE_CHANGED');sourceTaskRevisions(s.rows,a);const work=inspection.work;if(work){const defs=s.rows[work.plan.ref]?.tasks,definition=defs?.[0]&&Object.fromEntries(Object.entries(defs[0]).filter(([k])=>!['definition_digest','work_digest'].includes(k)));if(work.plan.version!==1||defs.length!==1||digest(definition)!==digest({...contract,depends_on:[]}))throw fail('The accepted source work/check definition changed.');}return s;};
+ const inputForEditors={tasks:brief.editors.map(e=>({prompt:e.prompt,description:e.id,isolation:'git',git_source:brief.source,work_tracking:'parent',...(e.max_turns?{max_turns:e.max_turns}:{})}))};
+ const stages=s=>s.rows.filter(r=>r.type==='source_task_stage'&&r.source===source&&r.task_digest===taskDigest&&r.session_id===sessionId);
+ const preparedStage=(s,key)=>stages(s).find(r=>r.key===key);
+ const proposal=(s,stage)=>s.rows.find(r=>r.type==='house_proposal'&&r.call_id===stage.call_id&&r.operation===stage.operation&&r.arguments_digest===stage.arguments_digest&&digest(r.actor)===digest(actor));
+ const stageReceipt=(s,stage)=>{const p=proposal(s,stage);return p&&s.rows.findLast(r=>r.type==='house_receipt'&&r.invocation_id===p.invocation_id);};
+ const evidenceCall=call=>{const {integration_id,...input}=call.input;return{name:'SourceEvidence',input};};
+ const projectEvidence=(items,generation)=>items?.map(item=>({...item,read_call:{...evidenceCall(item.read_call),input:{...evidenceCall(item.read_call).input,generation}}}))??[];
+ const parse=r=>{if(r?.status!=='returned'||r.output_truncated||r.output_digest!==digest(r.output))throw fail('The original native stage did not return a complete durable outcome.','SOURCE_TASK_STAGE_CLOSED',{receipt_id:r?.invocation_id,code:r?.code??null});return JSON.parse(r.output);};
+ const recordCall=async(name,input,o)=>o.recordWork({type:'source_task_call_prepared',source,operation:name,arguments_digest:digest(input),task_digest:taskDigest});
+ const frame=async(o,options)=>{
+  if(o.sessionId!==sessionId||digest(o.actor)!==digest(actor))throw fail('The accepted source task belongs to another actor/session.','SOURCE_TASK_OWNER');
+  const s=await state(options),observed=await o.revalidate(),proposal=s.rows.find(r=>r.type==='house_proposal'&&r.invocation_id===o.invocation_id),contract=proposal&&s.rows.findLast(r=>r.type==='house_contract'&&r.contract_digest===proposal.contract_digest)?.contract;
+  if(observed.invocation_id!==o.invocation_id||proposal?.operation!==o.command_name||contract?.origin!==null||contract.revision!==SOURCE_TASK_MECHANISM)throw fail('An admitted native source coordinator frame is required.','SOURCE_TASK_FRAME_REQUIRED');
+  if(['SourceDeliver','SourceRevise'].includes(o.command_name)){const id=await integration();if(id){const original=await integrationOperations.preparation(o,id),chain=await integrationOperations.lineage(o,original);await integrationOperations.frame(o,chain);}}
+ };
+ const stage=async(key,name,input,o)=>{
+  let s=await state(),saved=preparedStage(s,key);if(saved&&(saved.operation!==name||saved.arguments_digest!==digest(input)||digest(saved.input)!==digest(input)))throw fail('A source stage cannot replace its original native intent.');
+  if(!saved){await o.recordWork({type:'source_task_stage',source,task_digest:taskDigest,key,operation:name,input,arguments_digest:digest(input),call_id:randomUUID()});s=await state();saved=preparedStage(s,key);}
+  const p=proposal(s,saved);if(p){const r=stageReceipt(s,saved);if(!r)throw fail('A source stage has an unsettled native dispatch. Recover the same session; no effect was replayed.','SOURCE_TASK_UNCERTAIN');return{value:r.status==='returned'?parse(r):null,receipt:r,proposal:p,stage:saved};}
+  await frame(o);if((key==='editors'||name==='Agent')&&(await inspectGitSource({cwd,signal:o.signal})).source_identity!==savedSourceTask(await state()).binding.source_identity)throw fail('The accepted parent source changed before editor launch.','SOURCE_TASK_STALE');await o.recordWork({type:'source_task_dispatch',source,task_digest:taskDigest,stage_ref:s.rows.indexOf(saved),stage_digest:saved.audit.sha256,key});
+  try{await o.invoke(name,input,{signal:o.signal,callId:saved.call_id,beforeEffect:()=>frame(o)});}catch(error){if(!['GIT_MERGE_CONFLICT','GIT_NATIVE_CHECK_FAILED'].includes(error.code))throw error;}s=await state();const r=stageReceipt(s,saved);return{value:r?.status==='returned'?parse(r):null,receipt:r,proposal:proposal(s,saved),stage:saved};
+ };
+ // Retry only a lost handler reply, preserving the native intent/attempt. The
+ // kernel remains responsible for refusing an uncertain mutation or check.
+ const recoverStage=async(key,name,input,o,{failure=false}={})=>{
+  for(let n=0;;n++){
+   const value=await stage(n?key+'-recovered-'+n:key,name,input,o);
+   if(value.value||failure&&['GIT_MERGE_CONFLICT','GIT_NATIVE_CHECK_FAILED'].includes(value.receipt.code))return value;
+   if(!value.receipt.recovery&&!['HOUSE_RECOVERY_NOT_STARTED','HOUSE_RECOVERY_NOT_DISPATCHED'].includes(value.receipt.code))throw fail('The original native stage is closed; no fresh intent was substituted.','SOURCE_TASK_STAGE_CLOSED',{receipt_id:value.receipt.invocation_id});
+  }
+ };
+ const revisions=s=>sourceTaskRevisions(s.rows,savedSourceTask(s));
+ const integration=async(options={})=>{
+  const s=await state(options),last=options.generation??revisions(s).at(-1)?.binding.generation??0,candidates=options.generation!==undefined?[last]:Array.from({length:last+1},(_,i)=>last-i),owner=digest({actor,session_id:sessionId});
+  for(const generation of candidates){const request_id=generation?correctionRequest(taskDigest,generation):'source-'+taskDigest.slice(0,40),intent=s.rows.find(row=>row.type==='git_integration_intent'&&row.operation==='GitIntegrationPrepare'&&row.input.request_id===request_id&&row.owner_digest===owner);if(intent)return intent.binding.resolved.integration_id;}
+  return null;
+ };
+ const generationOf=async id=>{const s=await state({historical:true}),intent=s.rows.find(r=>r.type==='git_integration_intent'&&r.operation==='GitIntegrationPrepare'&&r.binding.resolved.integration_id===id);return revisions(s).find(r=>correctionRequest(taskDigest,r.binding.generation)===intent?.input.request_id)?.binding.generation??0;};
+ const inspect=async(o,{invoke=true,historical=false}={})=>{
+  const id=await integration({historical});if(!id)return{status:'not_prepared',task_digest:taskDigest,asked:'unjudged'};
+  if(!invoke)throw fail('A native observation context is required.');
+  const result=await integrationOperations.status({integration_id:id},o),status=result.integrations[0];
+  const kernel=new GitWorkspaces({cwd}),resource=await kernel.status(id,{owner:{actor,session_id:sessionId}}),prepared=resource.completed.find(r=>r.action==='integration_prepare')?.output;
+  let target=null,current=null;if(prepared){target=await kernel.rootRef('refs/comal/integrations/'+brief.target,o.signal);current=await inspectGitSource({cwd:prepared.worktree,signal:o.signal});}
+  const rootSource=await inspectGitSource({cwd,signal:o.signal});
+  const valid=rootSource.source_identity===savedSourceTask(await state({historical})).binding.source_identity&&resource.lifecycle==='retained'&&!resource.pending.length&&status.verification==='passed_declared_checks'&&status.applied===status.candidate&&target===status.candidate&&current?.head===status.candidate&&!current.dirty&&current.source_identity===prepared.source_identity;
+  o.observe?.({kind:'source_task_ref_observation',task_digest:taskDigest,integration_id:id,target_ref:'refs/comal/integrations/'+brief.target,observed_commit:target,candidate:status.candidate,source_identity:current?.source_identity??null});
+  return{status:valid?'verified':'needs_verification',task_digest:taskDigest,integration_id:id,candidate:status.candidate,target_ref:'refs/comal/integrations/'+brief.target,observed_commit:target,verification:status.verification,pending:status.pending,rejected:status.rejected,evidence:projectEvidence(status.evidence,await generationOf(id)),conflicts:status.conflicts,scope:'native_source_and_declared_checks_not_human_acceptance',asked:'unjudged'};
+ };
+ const locks=new Map();
+ const lock=async o=>{const lease=await acquireProcessLock(path.join(store.dir,'.source-task-'+digest({sessionId,actor,taskDigest})+'.lock'),{resource:{session_id:sessionId,invocation_id:o.invocation_id},validate:async old=>{const s=await state();if(old.resource?.session_id!==sessionId||!s.rows.some(r=>r.type==='house_receipt'&&r.invocation_id===old.resource.invocation_id))throw fail('Recover the original coordinator before continuing.','SOURCE_TASK_UNCERTAIN');}}).catch(error=>{if(error.code==='SESSION_IN_USE')throw fail('The accepted source pipeline is already running.','SOURCE_TASK_BUSY');throw error;});locks.set(o.invocation_id,lease);};
+ const settle=async({invocation_id,receiptRecorded})=>{const lease=locks.get(invocation_id);if(!lease)return;locks.delete(invocation_id);if(receiptRecorded)await lease.release();else await lease.file.close();};
+ const enter=async o=>{
+  if(policy.mode==='plan')throw fail('Plan mode cannot start source effects.','HOUSE_REFUSED');await lock(o);await frame(o);const entered=await state();
+  if(!entered.rows.some(r=>r.type==='source_task_execution_bound'&&r.source===source&&r.task_digest===taskDigest))await o.recordWork({type:'source_task_execution_bound',source,task_digest:taskDigest,goal_owner:entered.goal?.status==='active'?entered.goal.id:null});
+  if(workProjection(await state(),house.stateContext()).counts.done===1){const observed=JSON.parse(await o.invoke('SourceVerify',{}, {signal:o.signal}));if(observed.status!=='verified')throw fail('The recorded delivery is historical; source or target changed.','SOURCE_TASK_STALE');return{...observed,status:'done',reused:true};}
+ };
+ const correctionState=async(id,o)=>{
+  const status=(await integrationOperations.status({integration_id:id},o)).integrations[0],kernel=new GitWorkspaces({cwd});let descriptor,error;
+  try{descriptor=await kernel.revisionSource(id,{owner:{actor,session_id:sessionId},signal:o.signal});}catch(e){error=e;}
+  return{status,descriptor,error};
+ };
+ // A proposed next action, never authorization or a task-specific answer. The
+ // native editor receives the frozen source, full criterion and failure data.
+ const correctionCall=()=>({name:'SourceRevise',input:{instructions:'Inspect the frozen failed source and supplied native diagnostics. Diagnose and correct the observed failure under the complete accepted task; preserve other components and the original verification contract and target.'}});
+ const diagnosisAction='The correction editor can read the frozen failed source and diagnose the supplied native failure. Use correction_call to delegate diagnosis and correction, or supply your own SourceRevise instructions. Original criteria, checks, target and permissions remain effective.';
+ const editorAttention=(editors,generation)=>({status:'needs_editor_attention',task_digest:taskDigest,...(generation===undefined?{}:{generation}),editors,...(editors.some(r=>['paused','interrupted'].includes(r.status))?{resume_call:{name:'SourceDeliver',input:{resume_editors:true}}}:{}),next_action:'Inspect the original editor outcome. If resume_call is present, it resumes only the saved paused/interrupted editors; no new editor is created. This advice grants no permission.',asked:'unjudged'});
+ const failedSource=async(id,o,code)=>{
+  const {status,descriptor,error}=await correctionState(id,o);
+  if(!descriptor)throw fail('This native outcome is not a known source failure; no correction or verification was replayed.',code??error.code,{native_code:error.code,evidence:projectEvidence(status.evidence,await generationOf(id))});
+  const generation=await generationOf(id);
+  return{status:'needs_correction',task_digest:taskDigest,generation,kind:descriptor.kind,evidence:projectEvidence(status.evidence,generation),conflicts:status.conflicts,...(generation<31?{correction_call:correctionCall()}:{}),next_action:generation<31?diagnosisAction:'The original bounded correction lineage is full; no further correction is offered.',asked:'unjudged'};
+ };
+ const finishCandidate=async(prefix,id,input,o)=>{
+  let status=JSON.parse(await o.invoke('GitIntegrationStatus',{integration_id:id},{signal:o.signal})).integrations[0];
+  if(status.verification!=='passed_declared_checks'){
+   const failed=status.rejected.filter(r=>r.action==='integration_verify').length;if(failed&&!input.retry_checks)return failedSource(id,o);
+   const number=failed?String(failed):'first',attempt_id='source-check-'+number,check=await recoverStage(prefix+'verify-'+number,'GitIntegrationVerify',{integration_id:id,attempt_id},o,{failure:true});if(!check.value)return failedSource(id,o,check.receipt.code);
+  }
+  await fault('verified',{o,integration_id:id});status=JSON.parse(await o.invoke('GitIntegrationStatus',{integration_id:id},{signal:o.signal})).integrations[0];if(status.verification!=='passed_declared_checks')throw fail('No passed native combined verification exists.','SOURCE_TASK_CHECK_FAILED');
+  if(!status.applied)await recoverStage(prefix+'apply','GitIntegrationApply',{integration_id:id,attempt_id:'source-apply'},o);
+  await fault('applied',{o,integration_id:id});const observed=await inspect(o);if(observed.status!=='verified')throw fail('Current source/ref differs from the passed native candidate.','SOURCE_TASK_STALE');
+  const work=workProjection(await state(),house.stateContext());if(work.counts.done!==1){const check=await o.invoke('WorkStepRun',{task_id:'source-task',plan_version:1,step_id:'combined-source',recheck:true},{signal:o.signal});await fault('close_check_returned',{o,check});await o.invoke('WorkTaskUpdate',{task_id:'source-task',plan_version:1,status:'done'},{signal:o.signal});}
+  await fault('closed',{o});return{...observed,status:'done',acceptance:'unjudged'};
+ };
+ const useRevision=async(row,o)=>{await o.recordWork({type:'source_task_revision_used',source,task_digest:taskDigest,generation:row.binding.generation,revision_digest:row.audit.sha256});};
+ // A recovered/missing coordinator return is not an acknowledgement of a new
+ // failure. Continue that generation once before selecting another editor.
+ const revisionAcknowledged=(s,row)=>Boolean(row&&s.rows.some(used=>used.type==='source_task_revision_used'&&used.source===source&&used.task_digest===taskDigest&&used.revision_digest===row.audit.sha256&&s.rows.some(r=>r.type==='house_receipt'&&r.invocation_id===used.invocation_id&&r.status==='returned'&&JSON.parse(r.output).status==='needs_correction')));
+ const continueRevision=async(row,input,o)=>{
+  const b=row.binding,prefix='revision-'+b.generation+'-';await useRevision(row,o);let s=await state(),launch=preparedStage(s,prefix+'editor'),p=launch&&proposal(s,launch),r=launch&&stageReceipt(s,launch);
+  if(!p)await stage(prefix+'editor','Agent',b.editor_input,o);
+  else if(!r)throw fail('The original correction editor launch is unsettled; recover this session.','SOURCE_TASK_UNCERTAIN');
+  else if(r.status!=='returned'){
+   if(['HOUSE_RECOVERY_CONTINUE','HOUSE_RECOVERY_NOT_DISPATCHED'].includes(r.code))await recoverStage(prefix+'editor-continue','AgentContinue',{invocation_id:p.invocation_id},o);
+   else throw fail('The original correction editor launch was refused; no new editor was substituted.','SOURCE_TASK_EDITORS_CLOSED');
+  }
+  await subagents.reconcile(sessionId);s=await state();launch=preparedStage(s,prefix+'editor');p=proposal(s,launch);let runs=(await subagents.runs(sessionId)).filter(run=>run.parent_invocation_id===p.invocation_id);
+  if(runs.length!==1)throw fail('The correction must retain exactly one original native editor.','SOURCE_TASK_REVISION_BINDING');
+  let run=runs[0];if(['paused','interrupted'].includes(run.status)&&input.resume_editors===true){await recoverStage(prefix+'resume-'+run.run_id+'-'+run.turn_id,'AgentResume',{run_id:run.run_id},o);run=(await subagents.runs(sessionId)).find(r=>r.run_id===run.run_id);}
+  if(run.status!=='completed'||!run.source_offer)return editorAttention([{run_id:run.run_id,status:run.status,error:run.error,result_read_call:run.result_read_call}],b.generation);
+  await fault('revision_editor_returned',{o,run,generation:b.generation});
+  const prepared=await recoverStage(prefix+'prepare','GitIntegrationRevise',{request_id:correctionRequest(taskDigest,b.generation),integration_id:b.parent_integration_id,run_id:run.run_id},o,{failure:true});
+  const id=await integration();if(!prepared.value)return failedSource(id,o,prepared.receipt.code);
+  await fault('revision_prepared',{o,integration_id:id,generation:b.generation});return finishCandidate(prefix,id,input,o);
+ };
+ const revise=async(input,o)=>{
+  if(!await integration())throw fail('Prepare and observe a known native failure through SourceDeliver first.','SOURCE_TASK_NOT_PREPARED');
+  const done=await enter(o);if(done)return done;
+  let s=await state(),latest=revisions(s).at(-1),id=await integration();if(!id)throw fail('Prepare and observe a known native failure through SourceDeliver first.','SOURCE_TASK_NOT_PREPARED');
+  const failed=await correctionState(id,o),sameGeneration=latest&&await generationOf(id)===latest.binding.generation;
+  const acknowledged=revisionAcknowledged(s,latest);
+  if(latest&&!(sameGeneration&&failed.descriptor&&acknowledged)){
+   if(input.instructions!==latest.binding.instructions)throw fail('Continue the original correction instructions before selecting new work. Use SourceStatus for the exact continuation call.','SOURCE_TASK_REVISION_CONFLICT');
+   return continueRevision(latest,{},o);
+  }
+  if(!failed.descriptor)throw fail('Correction requires a known native source/check failure, never a denial or uncertain effect.','SOURCE_TASK_REVISION_NOT_REQUIRED',{native_code:failed.error.code});
+  if((await inspectGitSource({cwd,signal:o.signal})).source_identity!==savedSourceTask(s).binding.source_identity)throw fail('The accepted human source changed before correction.','SOURCE_TASK_STALE');
+  const generation=(latest?.binding.generation??0)+1;if(generation>31)throw fail('The bounded original correction lineage is full.','SOURCE_TASK_REVISION_LIMIT');
+  const diagnostics={kind:failed.descriptor.kind,conflicts:failed.status.conflicts.map(c=>({details:c.details?.slice(0,4000)}))};
+  const reference=failed.status.evidence.find(e=>e.operation==='Bash')?.read_call;
+  if(reference){const call=evidenceCall(reference),page=JSON.parse(await o.invoke('SourceEvidence',{...call.input,generation:await generationOf(id),limit:4000},{signal:o.signal}));diagnostics.check_output=page.content;diagnostics.evidence={...call.input,generation:await generationOf(id)};}
+  const original=await integrationOperations.preparation(o,id);s=await state();const binding={generation,parent_integration_id:id,source:failed.descriptor,instructions:input.instructions,diagnostics,goal_owner:s.rows.find(r=>r.type==='source_task_execution_bound'&&r.task_digest===taskDigest).goal_owner,origin:{row:s.rows.findIndex(r=>r.audit.sha256===original.audit.sha256),digest:original.audit.sha256,binding_digest:original.binding_digest}};binding.editor_input=correctionEditor(brief,binding);
+  await o.recordWork({type:'source_task_revision',source,task_digest:taskDigest,binding,binding_digest:digest(binding)});s=await state();latest=revisions(s).at(-1);await fault('revision_selected',{o,generation});return continueRevision(latest,{},o);
+ };
+ const deliver=async(input,o)=>{
+  const done=await enter(o);if(done)return done;
+  const latest=revisions(await state()).at(-1);if(latest)return continueRevision(latest,input,o);
+  await fault('before_editors',{o});let s=await state(),launch=preparedStage(s,'editors'),batch;
+  if(!launch||!proposal(s,launch))batch=await stage('editors','AgentBatch',inputForEditors,o);
+  else{const p=proposal(s,launch),r=stageReceipt(s,launch);if(!r)throw fail('The original editor launch is unsettled; recover it before continuing.','SOURCE_TASK_UNCERTAIN');if(r.status==='returned')batch={value:parse(r),receipt:r,proposal:p};else if(['HOUSE_RECOVERY_CONTINUE','HOUSE_RECOVERY_NOT_DISPATCHED'].includes(r.code))batch=await recoverStage('editors-continue','AgentContinue',{invocation_id:p.invocation_id},o);else throw fail('The original editor batch was refused/failed; it was not restarted.','SOURCE_TASK_EDITORS_CLOSED');}
+  await subagents.reconcile(sessionId);s=await state();launch=preparedStage(s,'editors');const parent=proposal(s,launch),runs=(await subagents.runs(sessionId)).filter(run=>run.parent_invocation_id===parent.invocation_id);
+  for(const run of runs)if(['paused','interrupted'].includes(run.status)&&input.resume_editors===true){const resumed=await recoverStage('resume-'+run.run_id+'-'+run.turn_id,'AgentResume',{run_id:run.run_id},o);if(!resumed.value)throw fail('The original editor resume is closed; inspect its native outcome.','SOURCE_TASK_STAGE_CLOSED');}
+  const current=(await subagents.runs(sessionId)).filter(run=>run.parent_invocation_id===parent.invocation_id);if(current.length!==brief.editors.length||current.some(run=>run.status!=='completed'||!run.source_offer))return editorAttention(current.map(r=>({run_id:r.run_id,status:r.status,turn_state:r.turn_state,error:r.error,result_read_call:r.result_read_call})));
+  await fault('editors_returned',{o,runs:current});
+
+  const prepInput={request_id:'source-'+taskDigest.slice(0,40),target:brief.target,run_ids:current.map(r=>r.run_id),verification:brief.verification},prep=await recoverStage('prepare','GitIntegrationPrepare',prepInput,o,{failure:true}),id=await integration();
+  if(!prep.value)return failedSource(id,o,prep.receipt.code);await fault('prepared',{o,integration_id:id});return finishCandidate('',id,input,o);
+ };
+ const revisionView=async(observed)=>{
+  const s=await state({historical:true}),items=revisions(s),latest=items.at(-1),id=await integration({historical:true});let failure;
+  if(id){try{failure=await new GitWorkspaces({cwd}).revisionSource(id,{owner:{actor,session_id:sessionId}});}catch(error){if(!['GIT_REVISION_NOT_REQUIRED','GIT_REVISION_UNCERTAIN','GIT_RESOURCE_RETIRED'].includes(error.code))throw error;}}
+  const acknowledged=revisionAcknowledged(s,latest),generation=await generationOf(id),continuing=observed.status!=='verified'&&latest&&!(generation===latest.binding.generation&&failure&&acknowledged),canCorrect=failure&&!continuing&&generation<31;
+  return{available:Boolean(failure),current_generation:generation,generations:items.map(r=>({generation:r.binding.generation,kind:r.binding.source.kind})),...(continuing?{continue_call:{name:'SourceRevise',input:{instructions:latest.binding.instructions}}}:canCorrect?{correction_call:correctionCall()}:{}),next_action:observed.status==='verified'?'Native delivery is verified; human acceptance remains unjudged.':continuing?'Continue the exact saved correction with continue_call; do not select another editor. SourceDeliver can explicitly resume a paused editor.':canCorrect?diagnosisAction:failure?'The original bounded correction lineage is full; no further correction is offered.':'SourceDeliver continues any saved editor/check/ref stages. Denial or uncertainty does not authorize a source correction.'};
+ };
+ const publicWork=book=>{const w=workProjection(book,house.stateContext());return{counts:w.counts,cards:w.cards.map(({title,status})=>({title,status})),current:w.current?{title:w.current.title,status:w.current.status,criterion:w.current.criterion}:null,close_call:{name:'SourceDeliver',input:{}},administrative_controls:'host_owned',permissions_from_plan:false};};
+ const evidenceSchema=structuredClone(gitIntegrationDefinitions.find(d=>d.name==='GitIntegrationEvidence').input_schema);delete evidenceSchema.properties.integration_id;evidenceSchema.required=evidenceSchema.required.filter(k=>k!=='integration_id');evidenceSchema.properties.generation={type:'integer',minimum:0,maximum:31};
+ const defs=[{name:'SourceRevise',description:'Correct a known failed accepted source using one new native editor and the ORIGINAL checks/target. The editor can read the frozen failed source, inspect native diagnostics and diagnose the defect itself; you do not need to identify an application fix first. Use a supplied correction_call or your own source correction instructions, not replacement criteria. Continue a lost/unfinished correction with its exact saved instructions; SourceDeliver can resume its paused editor. House owns all generation/run/check/ref IDs. A known failed correction may be revised again after its outcome is recorded.',input_schema:{type:'object',required:['instructions'],properties:{instructions:{type:'string',minLength:1,maxLength:12000}},additionalProperties:false},run:revise},{name:'SourceDeliver',description:'Continue the SAME accepted source task. The house owns editor/check/ref/work identities. Native AgentBatch editors implement source, then native combined checks and reserved-ref CAS establish closure. resume_editors explicitly resumes paused/interrupted originals; retry_checks explicitly retries known failed checks. Never rewrites criteria or restarts an uncertain batch.',input_schema:{type:'object',properties:{resume_editors:{type:'boolean'},retry_checks:{type:'boolean'}},additionalProperties:false},run:deliver},{name:'SourceEvidence',description:'Page exact native combined-check evidence for THIS accepted task, including failed/uncertain outcomes. Use the read_call supplied by SourceStatus. No owner, integration ID, permission or success override.',input_schema:evidenceSchema,run:async(input,o)=>{const {generation,...query}=input;const id=await integration({historical:true,...(generation!==undefined?{generation}:{} )});if(generation!==undefined&&await generationOf(id)!==generation)throw fail('No verifier exists for the selected original source generation.','SOURCE_TASK_NOT_PREPARED');if(!id)throw fail('No native combined verifier exists yet.','SOURCE_TASK_NOT_PREPARED');const result=await integrationOperations.evidence({...query,integration_id:id},o);if(result.next_call){result.next_call=evidenceCall(result.next_call);result.next_call.input.generation=await generationOf(id);}return result;}},...['SourceStatus','SourceVerify'].map(name=>({name,description:name==='SourceStatus'?'Read accepted source-task state, original editor outcomes and native evidence; no polling or permission grant.':'Host-only declared check: observe passed native combined checks, current candidate source and actual reserved target. No model success flag.',input_schema:empty,run:async(_,o)=>{if(name==='SourceVerify')return inspect(o);const observed=await inspect(o,{historical:true});return{task:brief,task_digest:taskDigest,work:publicWork(await state({historical:true})),editors:(await subagents.runs(sessionId)).map(r=>({run_id:r.run_id,status:r.status,source_offer:r.source_offer,error:r.error})),integration:observed,correction:await revisionView(observed)};}}))];
+ house.registry.replace([...ownNames],defs.map(d=>({...d,revision:SOURCE_TASK_MECHANISM,steps:['SourceDeliver','SourceRevise'].includes(d.name),permission:['SourceDeliver','SourceRevise'].includes(d.name)?d.name:d.name==='SourceEvidence'?'GitIntegrationEvidence':'GitIntegrationStatus',effects:['SourceDeliver','SourceRevise'].includes(d.name)?{workspace:'unknown',external:'unknown',process:'unknown',authority:'none'}:{workspace:'read',external:'none',process:'read',authority:'none'},run:async(input,o)=>{o={...o,command_name:d.name};await recordCall(d.name,input,o);await frame(o,{historical:['SourceStatus','SourceEvidence'].includes(d.name)});const value=await d.run(input,o);if(['SourceDeliver','SourceRevise'].includes(d.name))await frame(o);return JSON.stringify(value);}})));
+ if(accepted)await workspace.recoverInterrupted();
+ let setupTurn;
+ if(house.registry.get('ToolPack')){setupTurn=randomUUID();await store.append(sessionId,{type:'tool_turn',source:'capability_host',actor,id:setupTurn,open:true});await executor.execute('ToolPack',{action:'acquire',pack:'workspace.git'});}
+ try{
+ if(!accepted){const observed=JSON.parse(await executor.execute('GitInspect',{}));const binding={cwd,session_id:sessionId,actor,goal_id:goal,reset_ref:epoch,source_identity:observed.source_identity};accepted=await store.append(sessionId,{type:'source_task_accepted',source,mechanism:SOURCE_TASK_MECHANISM,house:cwd,session_id:sessionId,actor,surface:'agent',task:brief,task_digest:taskDigest,governance_plan_hash:plan.plan_hash,binding,binding_digest:digest(binding)});}
+ if(!workProjection(await store.load(sessionId)))await executor.execute('WorkPlanSet',{objective:criterionLength>2200?contractReference:brief.criterion,expected_version:0,tasks:[contract]});
+ if(workProjection(await store.load(sessionId)).current?.status==='pending')await executor.execute('WorkTaskUpdate',{task_id:'source-task',plan_version:1,status:'in_progress'});
+ if(house.registry.get('ToolPack'))await executor.execute('ToolPack',{action:'acquire',pack:'workspace.git'});
+ }finally{if(setupTurn)await store.append(sessionId,{type:'tool_turn',source:'capability_host',actor,id:setupTurn,open:false});}
+ const stageBound=(v,s)=>{
+  const p=s.rows.find(r=>r.type==='house_proposal'&&r.invocation_id===v.invocation_id);
+  return p&&stages(s).some(stage=>stage.operation===v.operation&&stage.call_id===p.call_id&&stage.arguments_digest===digest(v.input)&&digest(stage.input)===digest(v.input));
+ };
+ const scope=async v=>{
+  if(v.actor.kind==='human')return true;let s;try{s=await state({historical:['SourceStatus','SourceEvidence'].includes(v.operation)&&v.session_id===sessionId});}catch(error){return{allowed:false,reason:error.message};}
+  if(v.session_id!==sessionId)return true;if(digest(v.actor)!==digest(actor))return false;
+  const coordinator=['SourceDeliver','SourceRevise'].includes(v.parent_operation);
+  if(ownNames.has(v.operation))return v.operation!=='SourceVerify'||['WorkStepRun','SourceDeliver','SourceRevise'].includes(v.parent_operation);
+  if(v.operation==='EvidenceRead')return true;
+  if(['Agent','AgentBatch','AgentContinue','AgentResume','GitIntegrationRevise','GitIntegrationPrepare','GitIntegrationVerify','GitIntegrationApply'].includes(v.operation)){
+   if(coordinator&&stageBound(v,s))return true;
+   if(v.operation==='GitIntegrationPrepare'&&v.parent_operation==='GitIntegrationRevise'){
+    const parent=s.rows.find(r=>r.type==='house_proposal'&&r.invocation_id===v.parent_invocation_id),stage=parent&&stages(s).find(r=>r.operation==='GitIntegrationRevise'&&r.call_id===parent.call_id&&r.arguments_digest===parent.arguments_digest);
+    return Boolean(stage&&coordinatorParent(s,parent)&&digest(v.input)===digest({request_id:stage.input.request_id,target:brief.target,run_ids:[stage.input.run_id],verification:brief.verification,revision_of:stage.input.integration_id}));
+   }
+   return false;
+  }
+  if(v.operation==='GitIntegrationStatus')return ['SourceDeliver','SourceRevise','SourceVerify','SourceStatus'].includes(v.parent_operation);
+  if(v.operation==='WorkStepRun')return coordinator&&digest(v.input)===digest({task_id:'source-task',plan_version:1,step_id:'combined-source',recheck:true});
+  if(v.operation==='WorkTaskUpdate')return coordinator&&digest(v.input)===digest({task_id:'source-task',plan_version:1,status:'done'});
+  return{allowed:false,reason:'This accepted v2 source task uses bounded native source/correction actions; generic administration remains unavailable.'};
+ };
+ const coordinatorParent=(s,p)=>s.rows.some(r=>r.type==='house_proposal'&&r.invocation_id===p.parent_invocation_id&&['SourceDeliver','SourceRevise'].includes(r.operation)&&digest(r.actor)===digest(actor));
+ const close=async v=>{if(v.session_id!==sessionId||v.actor.kind==='human'||v.input.status!=='done')return true;const s=await state(),r=s.rows.findLast(row=>row.type==='house_receipt'&&row.operation==='SourceVerify'&&row.status==='returned');if(!r||JSON.parse(r.output).status!=='verified')return false;const value=JSON.parse(r.output),kernel=new GitWorkspaces({cwd});return await kernel.rootRef(value.target_ref)===value.candidate;};
+ if(accepted.governance_plan_hash&&accepted.governance_plan_hash!==plan.plan_hash)throw fail('The saved source workflow policy changed.');
+ await house.activateGovernance({sessionId,plan,bindings:{'runtime:source-task.scope':{revision:SOURCE_TASK_MECHANISM,operations:['*'],configuration_digest:taskDigest,check:scope},'runtime:source-task.close':{revision:SOURCE_TASK_MECHANISM,operations:['WorkTaskUpdate'],configuration_digest:taskDigest,check:close}}});
+ const retireSettlement=workspace.registerSettlement(settle);
+ const project=snapshot=>{const definitions=snapshot.definitions().filter(d=>publicNames.has(d.name)),offered=new Set(definitions.map(d=>d.name));return{...snapshot,definitions:()=>definitions,execute:(name,input,options={})=>{if(options.modelProposed&&!offered.has(name))throw fail('The house owns accepted source bookkeeping; use the offered source actions.','SOURCE_TASK_SCOPE');return snapshot.execute(name,input,options);}};};
+ return{task:brief,taskDigest,system:'Accepted source task: '+JSON.stringify(brief)+'. Use SourceDeliver to implement through the original native editors, combine, verify and close. SourceRevise corrects known source/check failures under the same accepted criteria. The correction editor can inspect the frozen failed source and diagnose supplied native failure data; you may delegate diagnosis with correction_call without identifying an application fix yourself. Use continue_call for a saved correction and resume_call for paused editors. SourceStatus/SourceEvidence are optional inspection when needed, not prerequisites for delegating diagnosis. SourceDeliver continues a saved correction; do not invent bookkeeping. SourceStatus/SourceEvidence/EvidenceRead inspect missing failure evidence. The house derives IDs and performs declared verification. Never create generic work plans, administer Git, change criteria or infer acceptance. Report limits on refusal/uncertainty.',dispose:()=>{retireSettlement();house.retireGovernance(sessionId);house.registry.replace([...ownNames],[]);},wrap:tools=>({...tools,house,policy,workflow:'source-task',definitions:()=>project(tools.snapshot()).definitions(),snapshot:()=>project(tools.snapshot()),execute:(n,i,o)=>project(tools.snapshot()).execute(n,i,o)}),settle,
+ async finishResult(final,context){
+  let delivery={status:'open',task_digest:taskDigest,asked:'unjudged',scope:'accepted_source_and_declared_checks_not_human_acceptance'};
+  const s=await state({historical:true}),closed=s.rows.slice(context.baseline).findLast(r=>r.type==='house_receipt'&&['SourceDeliver','SourceRevise'].includes(r.operation)&&r.status==='returned'&&JSON.parse(r.output).status==='done');
+  if(!final.is_error&&!final.work_stop_reason&&closed){try{await state();const observed=JSON.parse(await executor.execute('SourceStatus',{}, {signal:context.signal}));if(observed.integration.status!=='verified')throw fail('Final native source/ref observation failed.','SOURCE_TASK_STALE');const read=(await state()).rows.findLast(r=>r.type==='house_receipt'&&r.operation==='SourceStatus'&&r.status==='returned');delivery={...delivery,status:'verified',receipt_id:read.invocation_id,candidate:observed.integration.candidate,target_ref:observed.integration.target_ref};}catch(error){delivery={...delivery,status:'needs_verification',code:error.code??'SOURCE_TASK_FINAL_CHECK'};final.is_error=true;final.work_stop_reason='verification_failed';final.result+='\nThe final source/ref check failed; delivery remains unverified.';}}
+  else if(!final.is_error){final.is_error=true;final.work_stop_reason??='source_task_open';final.result+='\nThe accepted source delivery remains unverified.';}
+  final.delivery=delivery;await store.append(sessionId,{type:'source_task_delivery',source,...delivery});
+ },
+ async completedResult(calls=[]){const s=await state(),r=s.rows.findLast(r=>r.type==='house_receipt'&&['SourceDeliver','SourceRevise'].includes(r.operation)&&r.status==='returned'&&calls.some(c=>c.id===r.call_id&&c.name===r.operation));if(!r||workProjection(s,house.stateContext()).counts.done!==1)return null;const value=JSON.parse(r.output);if(value.status!=='done')return null;return{terminal:true,receipt_id:r.invocation_id,result:`Source candidate verified at ${value.target_ref}: ${value.candidate}. Accepted combined checks passed; evidence ${r.invocation_id}. Human acceptance remains unjudged.`};}};
+}

package/src/workflows/source-task.mjs

@@ -0,0 +1,13 @@
+import {savedSourceTask,SOURCE_TASK_MECHANISM,SOURCE_TASK_MECHANISM_V2} from '../source-task-proof.mjs';
+import {prepareSourceTaskV1} from './source-task-v1.mjs';
+import {prepareSourceTaskV2} from './source-task-v2.mjs';
+export {sourceTaskSchema,normalizeSourceTask,readSourceTask} from './source-task-v1.mjs';
+
+// A saved mechanism selects its original implementation. New sessions bind v2;
+// startup does not migrate an accepted v1 scope or silently grant new actions.
+export async function prepareSourceTask(options){
+ const accepted=savedSourceTask(await options.store.load(options.sessionId));
+ if(accepted?.mechanism===SOURCE_TASK_MECHANISM)return prepareSourceTaskV1(options);
+ if(accepted&&accepted.mechanism!==SOURCE_TASK_MECHANISM_V2)throw Object.assign(new Error('Unsupported accepted source-task mechanism; no workflow was migrated.'),{code:'SOURCE_TASK_VERSION'});
+ return prepareSourceTaskV2(options);
+}