pi-daddy 0.24.0 → 0.25.1

package/src/measured-order.ts

@@ -0,0 +1,67 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, realpath, lstat, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { withFileLock } from "./file-lock.ts";
+import { intentKey } from "./intent-control.ts";
+import { runMeasuredAgentSession, MeasuredSessionFailure, MeasuredSessionUnknownError, type MeasuredSessionHost, type MeasuredSessionInput } from "./measured-session.ts";
+import { openResourceBudget, resourceBindingDigest, type GovernedBudgetBinding } from "./resource-budget.ts";
+import { freezeWork } from "./work-ledger-json.ts";
+
+const ID=/^[a-zA-Z0-9:_-]{1,128}$/,HEX=/^[a-f0-9]{64}$/;
+const hash=(value:unknown)=>createHash("sha256").update(typeof value==="string"?value:intentKey(value)).digest("hex");
+const exact=(value:object,keys:string[])=>Object.keys(value).sort().join()===keys.sort().join();
+export type MeasuredOutputContract={version:"measured-output-exact-v1";expectedSha256:string}|{version:"measured-output-json-projection-v1";requiredKeys:string[];textFields:string[];arrayField:string;minItems:number;maxItems:number;itemRequiredFields:string[];projectionFields:string[];expectedProjectionSha256:string};
+export interface MeasuredOrderAttempt extends Omit<MeasuredSessionInput,"budget"|"attempt"|"signal">{attemptId:string;includeDependencies:boolean;qualification:MeasuredOutputContract}
+export interface MeasuredOrderNode {nodeId:string;dependencies:string[];attempts:MeasuredOrderAttempt[]}
+export interface MeasuredOrder {version:"measured-order-v1";orderId:string;authorityDigest:string;budgetDigest:string;nodes:MeasuredOrderNode[]}
+export interface MeasuredOrderBinding {version:"measured-order-binding-v1";directory:string;directoryDevice:string;directoryInode:string;journalDevice:string;journalInode:string;budget:GovernedBudgetBinding;order:MeasuredOrder;digest:string}
+export interface MeasuredOrderAuthority {authorityDigest:string;orderDigests:string[];acknowledgementDigests:string[]}
+export interface MeasuredOrderAcknowledgement {version:"measured-order-ack-v1";requestId:string;bindingDigest:string;attemptId:string;claimOwner:string;claimDigest:string}
+type JournalEvent=
+ |{type:"claim";sequence:number;previousDigest:string|null;attemptId:string;owner:string;digest:string}
+ |{type:"result";sequence:number;previousDigest:string;attemptId:string;owner:string;state:"completed"|"failed"|"cancelled"|"unknown"|"mismatch";outputSha256:string|null;result:unknown;digest:string}
+ |{type:"acknowledge-unknown";sequence:number;previousDigest:string;request:MeasuredOrderAcknowledgement;digest:string};
+export interface MeasuredOrderNodeView {nodeId:string;state:"eligible"|"dependency-blocked"|"running"|"unknown"|"exhausted"|"satisfied";action:"dispatch"|"wait"|"acknowledge"|"none";attemptId:string|null;outputSha256:string|null;unknownClaim:{owner:string;digest:string}|null}
+function field(value:unknown):value is string{return typeof value==="string"&&/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(value);}
+function checkedContract(input:MeasuredOutputContract):MeasuredOutputContract{const c=JSON.parse(intentKey(input)) as MeasuredOutputContract;if(c.version==="measured-output-exact-v1"){if(!exact(c,["version","expectedSha256"])||!HEX.test(c.expectedSha256))throw Error("invalid exact output contract");return c;}if(c.version!=="measured-output-json-projection-v1"||!exact(c,["version","requiredKeys","textFields","arrayField","minItems","maxItems","itemRequiredFields","projectionFields","expectedProjectionSha256"])||![c.requiredKeys,c.textFields,c.itemRequiredFields,c.projectionFields].every(x=>Array.isArray(x)&&x.length<=32&&new Set(x).size===x.length&&x.every(field))||!field(c.arrayField)||!Number.isSafeInteger(c.minItems)||!Number.isSafeInteger(c.maxItems)||c.minItems<0||c.maxItems<c.minItems||c.maxItems>4096||!c.requiredKeys.includes(c.arrayField)||c.textFields.some(x=>!c.requiredKeys.includes(x))||c.projectionFields.some(x=>!c.itemRequiredFields.includes(x))||!HEX.test(c.expectedProjectionSha256))throw Error("invalid deterministic JSON output contract");return c;}
+export function qualifyMeasuredOutput(output:string,input:MeasuredOutputContract){const contract=checkedContract(input),outputSha256=hash(output);if(contract.version==="measured-output-exact-v1")return{eligible:outputSha256===contract.expectedSha256,outputSha256,projectionSha256:null};let value:unknown;try{value=JSON.parse(output);}catch{return{eligible:false,outputSha256,projectionSha256:null};}if(!value||typeof value!=="object"||Array.isArray(value)||Object.keys(value).sort().join()!==[...contract.requiredKeys].sort().join())return{eligible:false,outputSha256,projectionSha256:null};const object=value as Record<string,unknown>,items=object[contract.arrayField];if(contract.textFields.some(x=>typeof object[x]!=="string"||!(object[x] as string).trim())||!Array.isArray(items)||items.length<contract.minItems||items.length>contract.maxItems||items.some(x=>!x||typeof x!=="object"||Array.isArray(x)||contract.itemRequiredFields.some(k=>!Object.hasOwn(x,k))))return{eligible:false,outputSha256,projectionSha256:null};const projection=(items as Record<string,unknown>[]).map(item=>Object.fromEntries(contract.projectionFields.map(k=>[k,item[k]]))),projectionSha256=hash(intentKey(projection));return{eligible:projectionSha256===contract.expectedProjectionSha256,outputSha256,projectionSha256};}
+
+function checkedOrder(input:MeasuredOrder,budget:GovernedBudgetBinding):MeasuredOrder{
+ const order=JSON.parse(intentKey(input)) as MeasuredOrder;if(!exact(order,["version","orderId","authorityDigest","budgetDigest","nodes"])||order.version!=="measured-order-v1"||!ID.test(order.orderId)||!HEX.test(order.authorityDigest)||order.budgetDigest!==resourceBindingDigest(budget)||!Array.isArray(order.nodes)||!order.nodes.length||order.nodes.length>8)throw Error("invalid bounded measured order");
+ const ids=new Set<string>(),attempts=new Set<string>();let inputBytes=0,count=0;
+ for(const node of order.nodes){if(!exact(node,["nodeId","dependencies","attempts"])||!ID.test(node.nodeId)||ids.has(node.nodeId)||!Array.isArray(node.dependencies)||node.dependencies.length>8||new Set(node.dependencies).size!==node.dependencies.length||!Array.isArray(node.attempts)||!node.attempts.length||node.attempts.length>3)throw Error("invalid node/dependency/recovery policy");ids.add(node.nodeId);
+  for(const a of node.attempts){if(!exact(a,["attemptId","model","thinkingLevel","prompt","deadlineMs","terminationGraceMs","maxRetainedOutputBytes","maxOutputTokens","includeDependencies","qualification"])||!ID.test(a.attemptId)||attempts.has(a.attemptId)||typeof a.includeDependencies!=="boolean"||!["openai-codex/gpt-5.6-sol","openai-codex/gpt-5.6-terra"].includes(a.model)||typeof a.prompt!=="string"||!a.prompt.length||Buffer.byteLength(a.prompt)>16384||!Number.isSafeInteger(a.deadlineMs)||a.deadlineMs<1000||a.deadlineMs>300000||!Number.isSafeInteger(a.terminationGraceMs)||a.terminationGraceMs<100||a.terminationGraceMs>10000||!Number.isSafeInteger(a.maxRetainedOutputBytes)||a.maxRetainedOutputBytes<1||a.maxRetainedOutputBytes>1024*1024||!Number.isSafeInteger(a.maxOutputTokens)||a.maxOutputTokens<1||a.maxOutputTokens>16384)throw Error("invalid read-only model attempt");checkedContract(a.qualification);attempts.add(a.attemptId);inputBytes+=Buffer.byteLength(a.prompt);count++;}
+ }
+ for(const node of order.nodes)for(const attempt of node.attempts)if(attempt.includeDependencies){let extra=0;for(const dependency of node.dependencies){const prior=order.nodes.find(n=>n.nodeId===dependency);extra+=256+Math.max(...(prior?.attempts.map(a=>a.maxRetainedOutputBytes)??[0]));}if(Buffer.byteLength(attempt.prompt)+extra>16384)throw Error("sealed dependency prompt exceeds attempt bound");inputBytes+=extra;}
+ if(count>budget.limits.maxAttempts||inputBytes>budget.limits.maxInputBytes||budget.limits.maxConcurrent<count)throw Error("order exceeds original accounting allowance");
+ const visiting=new Set<string>(),done=new Set<string>();const visit=(id:string)=>{if(done.has(id))return;if(visiting.has(id))throw Error("dependency cycle");const node=order.nodes.find(n=>n.nodeId===id);if(!node)throw Error("missing dependency");visiting.add(id);node.dependencies.forEach(visit);visiting.delete(id);done.add(id);};order.nodes.forEach(n=>visit(n.nodeId));return order;
+}
+export const measuredOrderDigest=(order:MeasuredOrder)=>hash(order);
+export function measuredOrderAcknowledgementDigest(input:MeasuredOrderAcknowledgement){const value=JSON.parse(intentKey(input)) as MeasuredOrderAcknowledgement;if(!exact(value,["version","requestId","bindingDigest","attemptId","claimOwner","claimDigest"])||value.version!=="measured-order-ack-v1"||![value.requestId,value.attemptId,value.claimOwner].every(x=>ID.test(x))||![value.bindingDigest,value.claimDigest].every(x=>HEX.test(x)))throw Error("invalid unknown acknowledgement");return hash(value);}
+function paths(directory:string){return{binding:join(directory,"binding.json"),journal:join(directory,"journal.jsonl")};}
+async function privateDirectory(directory:string){const st=await lstat(directory,{bigint:true});if(!st.isDirectory()||(st.mode&0o077n)||st.uid!==BigInt(process.getuid!())||await realpath(directory)!==directory)throw Error("owner-private measured order directory required");}
+export async function createMeasuredOrder(input:{directory:string;budget:GovernedBudgetBinding;order:MeasuredOrder}):Promise<Readonly<MeasuredOrderBinding>>{
+ if(!isAbsolute(input.directory)||resolve(input.directory)!==input.directory)throw Error("absolute measured order directory required");const order=checkedOrder(input.order,input.budget);await mkdir(input.directory,{recursive:false,mode:0o700});await privateDirectory(input.directory);
+ const p=paths(input.directory);await writeFile(p.journal,"",{mode:0o600,flag:"wx"});const directoryStat=await lstat(input.directory,{bigint:true}),journalStat=await lstat(p.journal,{bigint:true}),identity={directory:input.directory,directoryDevice:String(directoryStat.dev),directoryInode:String(directoryStat.ino),journalDevice:String(journalStat.dev),journalInode:String(journalStat.ino)};
+ const binding={version:"measured-order-binding-v1" as const,...identity,budget:input.budget,order,digest:hash({...identity,budgetDigest:resourceBindingDigest(input.budget),orderDigest:measuredOrderDigest(order)})};await writeFile(p.binding,intentKey(binding)+"\n",{mode:0o600,flag:"wx"});return freezeWork(binding) as unknown as Readonly<MeasuredOrderBinding>;
+}
+function checkedBinding(input:MeasuredOrderBinding):MeasuredOrderBinding{const b=JSON.parse(intentKey(input)) as MeasuredOrderBinding,identity={directory:b.directory,directoryDevice:b.directoryDevice,directoryInode:b.directoryInode,journalDevice:b.journalDevice,journalInode:b.journalInode};if(!exact(b,["version","directory","directoryDevice","directoryInode","journalDevice","journalInode","budget","order","digest"])||b.version!=="measured-order-binding-v1"||!isAbsolute(b.directory)||resolve(b.directory)!==b.directory||![b.directoryDevice,b.directoryInode,b.journalDevice,b.journalInode].every(x=>/^\d+$/.test(x))||b.digest!==hash({...identity,budgetDigest:resourceBindingDigest(b.budget),orderDigest:measuredOrderDigest(checkedOrder(b.order,b.budget))}))throw Error("invalid measured order binding");return b;}
+async function pinnedJournal(binding:MeasuredOrderBinding,writable=false){const path=paths(binding.directory).journal,handle=await open(path,(writable?constants.O_RDWR|constants.O_APPEND:constants.O_RDONLY)|constants.O_NOFOLLOW);try{const st=await handle.stat({bigint:true});if(!st.isFile()||st.nlink!==1n||(st.mode&0o077n)||String(st.dev)!==binding.journalDevice||String(st.ino)!==binding.journalInode)throw Error("measured order binding changed");return handle;}catch(error){await handle.close();throw error;}}
+async function linked(binding:MeasuredOrderBinding){const st=await lstat(paths(binding.directory).journal,{bigint:true});if(!st.isFile()||st.nlink!==1n||String(st.dev)!==binding.journalDevice||String(st.ino)!==binding.journalInode||(await realpath(paths(binding.directory).journal))!==paths(binding.directory).journal)throw Error("measured order binding changed");}
+function parseJournal(text:string):JournalEvent[]{if(text&&!text.endsWith("\n"))throw Error("incomplete measured order journal");const rows=text?text.trimEnd().split("\n").map(line=>{const row=JSON.parse(line) as JournalEvent;if(intentKey(row)!==line)throw Error("noncanonical measured order journal");return row;}):[];let prior:string|null=null;for(let i=0;i<rows.length;i++){const row=rows[i],copy={...row} as any,claimed=copy.digest;delete copy.digest;if(row.sequence!==i||row.previousDigest!==prior||claimed!==hash(copy))throw Error("invalid measured order journal");prior=claimed;}return rows;}
+async function appendJournal(binding:MeasuredOrderBinding,event:Omit<JournalEvent,"sequence"|"previousDigest"|"digest">){const path=paths(binding.directory).journal;return withFileLock(path,"measured order",async()=>{const handle=await pinnedJournal(binding,true);try{const rows=parseJournal(await handle.readFile("utf8")),base={...event,sequence:rows.length,previousDigest:rows.at(-1)?.digest??null} as any,record={...base,digest:hash(base)} as JournalEvent;await linked(binding);await handle.writeFile(intentKey(record)+"\n");await handle.sync();return record;}finally{await handle.close();}});}
+function project(order:MeasuredOrder,events:JournalEvent[],currentOwner:string):MeasuredOrderNodeView[]{const rows=new Map<string,MeasuredOrderNodeView>();const evaluate=(node:MeasuredOrderNode):MeasuredOrderNodeView=>{const prior=rows.get(node.nodeId);if(prior)return prior;const row:MeasuredOrderNodeView={nodeId:node.nodeId,state:"exhausted",action:"none",attemptId:null,outputSha256:null,unknownClaim:null};if(node.dependencies.some(id=>evaluate(order.nodes.find(n=>n.nodeId===id)!).state!=="satisfied")){row.state="dependency-blocked";row.action="wait";rows.set(node.nodeId,row);return row;}
+ for(const attempt of node.attempts){const claim=events.find(e=>e.type==="claim"&&e.attemptId===attempt.attemptId) as Extract<JournalEvent,{type:"claim"}>|undefined;if(!claim){row.state="eligible";row.action="dispatch";row.attemptId=attempt.attemptId;break;}const result=events.find(e=>e.type==="result"&&e.attemptId===attempt.attemptId) as Extract<JournalEvent,{type:"result"}>|undefined;const acknowledged=events.some(e=>e.type==="acknowledge-unknown"&&e.request.attemptId===attempt.attemptId&&e.request.claimDigest===claim.digest&&e.request.claimOwner===claim.owner);if(!result){if(claim.owner!==currentOwner){if(acknowledged)continue;row.state="unknown";row.action="acknowledge";row.unknownClaim={owner:claim.owner,digest:claim.digest};}else{row.state="running";row.action="wait";}row.attemptId=attempt.attemptId;break;}if(result.state==="unknown"){if(!acknowledged){row.state="unknown";row.action="acknowledge";row.attemptId=attempt.attemptId;row.unknownClaim={owner:claim.owner,digest:claim.digest};break;}continue;}if(result.state==="completed"){row.state="satisfied";row.outputSha256=result.outputSha256;row.attemptId=attempt.attemptId;break;}}
+ rows.set(node.nodeId,row);return row;};return order.nodes.map(evaluate);}
+export function openMeasuredOrder(input:MeasuredOrderBinding,hostAuthority:MeasuredOrderAuthority|null,host:MeasuredSessionHost){const binding=checkedBinding(input),p=paths(binding.directory),owner=randomUUID(),authorized=()=>hostAuthority?.authorityDigest===binding.order.authorityDigest&&hostAuthority.orderDigests.includes(measuredOrderDigest(binding.order));
+ const read=async()=>{await privateDirectory(binding.directory);const directoryStat=await lstat(binding.directory,{bigint:true});if(String(directoryStat.dev)!==binding.directoryDevice||String(directoryStat.ino)!==binding.directoryInode||(await readFile(p.binding,"utf8")).trimEnd()!==intentKey(binding))throw Error("measured order binding changed");await linked(binding);const handle=await pinnedJournal(binding);try{return parseJournal(await handle.readFile("utf8"));}finally{await handle.close();}};
+ const inspect=async()=>{const events=await read(),accounting=await openResourceBudget(binding.budget).inspect(),diagnostics=events.filter((e):e is Extract<JournalEvent,{type:"result"}>=>e.type==="result"&&e.state!=="completed").map(e=>`${e.attemptId}:${e.state}`);return freezeWork({version:"measured-order-view-v1",orderId:binding.order.orderId,nodes:project(binding.order,events,owner),resources:accounting,diagnostics,acceptance:"not-assessed",freshness:"snapshot-unknown" as const});};
+ return Object.freeze({inspect,async advance(){if(!authorized())throw Error("independent exact order authority required");await read();let selected:MeasuredOrderAttempt|undefined,claim:Extract<JournalEvent,{type:"claim"}>|undefined;
+  await withFileLock(p.journal,"measured order advance",async()=>{const handle=await pinnedJournal(binding,true);try{const events=parseJournal(await handle.readFile("utf8")),eligible=project(binding.order,events,owner).find(n=>n.state==="eligible");if(!eligible)return;selected=binding.order.nodes.flatMap(n=>n.attempts).find(a=>a.attemptId===eligible.attemptId)!;const base={type:"claim",sequence:events.length,previousDigest:events.at(-1)?.digest??null,attemptId:selected.attemptId,owner} as const;claim={...base,digest:hash(base)};await linked(binding);await handle.writeFile(intentKey(claim)+"\n");await handle.sync();}finally{await handle.close();}});
+  if(!selected||!claim)return inspect();const node=binding.order.nodes.find(n=>n.attempts.some(a=>a.attemptId===selected!.attemptId))!,index=node.attempts.findIndex(a=>a.attemptId===selected!.attemptId),controller=new AbortController();let state:Extract<JournalEvent,{type:"result"}>["state"]="failed",result:unknown=null,outputSha256:string|null=null;
+  try{const accounting=await openResourceBudget(binding.budget).inspect(),parent=[...node.attempts.slice(0,index)].reverse().find(a=>accounting.reservations.some(r=>r.attemptId===a.attemptId))??null,events=await read();let prompt=selected.prompt;if(selected.includeDependencies)for(const dependency of node.dependencies){const dependencyNode=binding.order.nodes.find(n=>n.nodeId===dependency)!,prior=dependencyNode.attempts.map(a=>events.find(e=>e.type==="result"&&e.attemptId===a.attemptId)).find((e):e is Extract<JournalEvent,{type:"result"}>=>e?.type==="result"&&e.state==="completed"),output=(prior?.result as {output?:unknown})?.output;if(!prior||typeof output!=="string"||hash(output)!==prior.outputSha256)throw Error("sealed dependency output unavailable");prompt+=`\n\n<sealed-dependency node=${JSON.stringify(dependency)} sha256=${JSON.stringify(prior.outputSha256)}>\n${output}\n</sealed-dependency>`;}
+   result=await runMeasuredAgentSession({budget:binding.budget,attempt:{attemptId:selected.attemptId,orderId:binding.order.orderId,experimentId:`${binding.order.orderId}:${node.nodeId}`,kind:parent?"retry":"primary",parentAttemptId:parent?.attemptId??null},model:selected.model,thinkingLevel:selected.thinkingLevel,prompt,deadlineMs:selected.deadlineMs,terminationGraceMs:selected.terminationGraceMs,maxRetainedOutputBytes:selected.maxRetainedOutputBytes,maxOutputTokens:selected.maxOutputTokens,signal:controller.signal},host);const qualified=qualifyMeasuredOutput((result as {output:string}).output,selected.qualification);outputSha256=qualified.outputSha256;state=qualified.eligible?"completed":"mismatch";}catch(error){result=error instanceof MeasuredSessionFailure?error.evidence:{errorType:error instanceof Error?error.name:"unknown",errorCode:typeof error==="object"&&error&&"code" in error?String(error.code):null,message:error instanceof Error?error.message:"unknown"};state=error instanceof MeasuredSessionUnknownError?"unknown":error instanceof MeasuredSessionFailure&&(error.evidence as {state?:string})?.state==="cancelled"?"cancelled":"failed";}
+  await appendJournal(binding,{type:"result",attemptId:selected.attemptId,owner:claim.owner,state,outputSha256,result} as Omit<JournalEvent,"sequence"|"previousDigest"|"digest">);return inspect();},
+  async acknowledgeUnknown(request:MeasuredOrderAcknowledgement,authority:MeasuredOrderAuthority|null){const digest=measuredOrderAcknowledgementDigest(request);if(authority?.authorityDigest!==binding.order.authorityDigest||!authority.acknowledgementDigests.includes(digest)||request.bindingDigest!==binding.digest)throw Error("independent exact acknowledgement authority required");await read();await withFileLock(p.journal,"measured order acknowledgement",async()=>{const handle=await pinnedJournal(binding,true);try{const events=parseJournal(await handle.readFile("utf8")),claim=events.find(e=>e.type==="claim"&&e.attemptId===request.attemptId) as Extract<JournalEvent,{type:"claim"}>|undefined,result=events.find(e=>e.type==="result"&&e.attemptId===request.attemptId) as Extract<JournalEvent,{type:"result"}>|undefined;if(!claim||claim.owner!==request.claimOwner||claim.digest!==request.claimDigest||!(result?.state==="unknown"||!result&&claim.owner!==owner)||events.some(e=>e.type==="acknowledge-unknown"&&e.request.attemptId===request.attemptId))throw Error("exact current unknown claim required");const base={type:"acknowledge-unknown",sequence:events.length,previousDigest:events.at(-1)!.digest,request} as const,record={...base,digest:hash(base)};await linked(binding);await handle.writeFile(intentKey(record)+"\n");await handle.sync();}finally{await handle.close();}});return inspect();}});
+}

package/src/measured-session.ts

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } from '@earendil-works/pi-coding-agent';
+import { openResourceBudget, type AttemptDemand, type GovernedBudgetBinding } from './resource-budget.ts';
+import { freezeWork } from './work-ledger-json.ts';
+
+const MODELS=['openai-codex/gpt-5.6-sol','openai-codex/gpt-5.6-terra'] as const;
+const THINKING=['off','minimal','low','medium','high','xhigh','max'] as const;
+export interface ProviderUsage {input:number;output:number;cacheRead:number;cacheWrite:number;reasoning:number;totalTokens:number;cost:{input:number;output:number;cacheRead:number;cacheWrite:number;total:number}}
+export interface MeasuredSessionHostInput {model:typeof MODELS[number];thinkingLevel:typeof THINKING[number];prompt:string;deadlineMs:number;maxOutputTokens:number;tools:readonly [];discovery:'factory-only';signal:AbortSignal}
+export interface MeasuredSessionHostResult {output:string;usage:ProviderUsage;provider:'openai-codex';model:'gpt-5.6-sol'|'gpt-5.6-terra';stopReason:string}
+export interface MeasuredSessionHost {run(input:MeasuredSessionHostInput):Promise<MeasuredSessionHostResult>}
+export interface MeasuredSessionInput {budget:GovernedBudgetBinding;attempt:Omit<AttemptDemand,'inputBytes'|'inputDigest'>;model:typeof MODELS[number];thinkingLevel:typeof THINKING[number];prompt:string;deadlineMs:number;terminationGraceMs:number;maxRetainedOutputBytes:number;maxOutputTokens:number;signal?:AbortSignal}
+export class MeasuredSessionFailure extends Error {readonly evidence:unknown;constructor(message:string,evidence:unknown){super(message);this.name='MeasuredSessionFailure';this.evidence=evidence;}}
+export class MeasuredSessionUnknownError extends Error {constructor(){super('measured session did not settle after owned abort; reservation remains active');this.name='MeasuredSessionUnknownError';}}
+const finite=(value:unknown)=>typeof value==='number'&&Number.isFinite(value)&&value>=0;
+function checkedUsage(value:ProviderUsage):ProviderUsage {
+ if(!value||typeof value!=='object'||Object.keys(value).sort().join()!=='cacheRead,cacheWrite,cost,input,output,reasoning,totalTokens'||![value.input,value.output,value.cacheRead,value.cacheWrite,value.reasoning,value.totalTokens].every(finite)||!Number.isSafeInteger(value.totalTokens)||!value.cost||Object.keys(value.cost).sort().join()!=='cacheRead,cacheWrite,input,output,total'||!Object.values(value.cost).every(finite))throw Error('provider usage unavailable or malformed');
+ return JSON.parse(JSON.stringify(value));
+}
+function checked(input:MeasuredSessionInput):MeasuredSessionInput {
+ if(!input||typeof input!=='object'||!MODELS.includes(input.model)||!THINKING.includes(input.thinkingLevel))throw Error('measured sessions require exact Codex Sol or Terra');
+ if(typeof input.prompt!=='string'||!input.prompt.length||Buffer.byteLength(input.prompt)>65536||!Number.isSafeInteger(input.deadlineMs)||input.deadlineMs<1000||input.deadlineMs>300000||!Number.isSafeInteger(input.terminationGraceMs)||input.terminationGraceMs<100||input.terminationGraceMs>10000||!Number.isSafeInteger(input.maxRetainedOutputBytes)||input.maxRetainedOutputBytes<1||input.maxRetainedOutputBytes>1024*1024||!Number.isSafeInteger(input.maxOutputTokens)||input.maxOutputTokens<1||input.maxOutputTokens>16384)throw Error('invalid measured session bounds');
+ if(input.signal?.aborted)throw new MeasuredSessionFailure('measured session cancelled before reservation',{state:'cancelled-before-reservation',reason:'caller-signal'});
+ return input;
+}
+/** Opt-in one-prompt route. Existing resource budgets own attempts; byte retention is checked after generation. */
+export async function runMeasuredAgentSession(raw:MeasuredSessionInput,host:MeasuredSessionHost){
+ const input=checked(raw),bytes=Buffer.from(input.prompt),budget=openResourceBudget(input.budget),permit=await budget.reserve({...input.attempt,inputBytes:bytes.length,inputDigest:createHash('sha256').update(bytes).digest('hex')});
+ const controller=new AbortController(),abort=()=>controller.abort(input.signal?.reason??'operator-cancellation');input.signal?.addEventListener('abort',abort,{once:true});if(input.signal?.aborted)abort();
+ const timer=setTimeout(()=>controller.abort('deadline'),input.deadlineMs);let outcome:'completed'|'failed'|'cancelled'|null='failed';
+ try{
+  const unknown=new Promise<never>((_,reject)=>controller.signal.addEventListener('abort',()=>setTimeout(()=>reject(new MeasuredSessionUnknownError()),input.terminationGraceMs),{once:true}));
+  if(controller.signal.aborted)throw new MeasuredSessionFailure('measured session cancelled after reservation',{state:'cancelled-before-host',reason:'caller-signal'});
+  const running=host.run({model:input.model,thinkingLevel:input.thinkingLevel,prompt:input.prompt,deadlineMs:input.deadlineMs,maxOutputTokens:input.maxOutputTokens,tools:[],discovery:'factory-only',signal:controller.signal});
+  const result=await Promise.race([running,unknown]);
+  const outputBytes=Buffer.from(result.output),outputEvidence={sha256:createHash('sha256').update(outputBytes).digest('hex'),bytes:outputBytes.length,retainedPrefix:outputBytes.subarray(0,input.maxRetainedOutputBytes).toString('utf8')};
+  let usage:ProviderUsage;try{usage=checkedUsage(result.usage);}catch(error){throw new MeasuredSessionFailure(String(error),{state:'failed',model:result.model,stopReason:result.stopReason,output:outputEvidence});}
+  if(result.provider!=='openai-codex'||`${result.provider}/${result.model}`!==input.model)throw new MeasuredSessionFailure('measured model identity mismatch',{state:'failed',observedProvider:result.provider,observedModel:result.model,stopReason:result.stopReason,output:outputEvidence,usage});
+  if(outputEvidence.bytes>input.maxRetainedOutputBytes)throw new MeasuredSessionFailure('measured retained-output bound exceeded',{state:'failed',model:input.model,stopReason:result.stopReason,output:outputEvidence,usage});
+  if(controller.signal.aborted||result.stopReason!=='stop')throw new MeasuredSessionFailure('measured assistant did not stop cleanly',{state:controller.signal.aborted?'cancelled':'failed',model:input.model,stopReason:result.stopReason,output:outputEvidence,usage});
+  outcome='completed';return freezeWork({version:'measured-session-result-v1',state:'completed',model:input.model,thinkingLevel:input.thinkingLevel,output:result.output,usage,stopReason:result.stopReason,acceptance:'not-assessed',grantExpansion:false});
+ }catch(error){
+  if(error instanceof MeasuredSessionUnknownError){outcome=null;throw error;}
+  if(controller.signal.aborted)outcome='cancelled';
+  if(error instanceof MeasuredSessionFailure)throw error;
+  throw new MeasuredSessionFailure('measured host failed',{state:controller.signal.aborted?'cancelled':'failed',errorType:error instanceof Error?error.name:'unknown'});
+ }
+ finally{clearTimeout(timer);input.signal?.removeEventListener('abort',abort);if(outcome)await permit.settle(outcome);}
+}
+export interface MeasuredAuthRuntime {isUsingOAuth(provider:string):boolean;isUsingSubscription(provider:string):boolean;checkAuth(provider:string,options?:{signal?:AbortSignal}):Promise<{type:string}|undefined>}
+export async function verifyMeasuredSubscription(runtime:MeasuredAuthRuntime,signal?:AbortSignal){
+ signal?.throwIfAborted();const auth=await runtime.checkAuth('openai-codex',{signal});signal?.throwIfAborted();
+ if(auth?.type!=='oauth'||!runtime.isUsingOAuth('openai-codex')||!runtime.isUsingSubscription('openai-codex'))throw Error('exact OpenAI Codex OAuth subscription authorization required');
+}
+/** Concrete SDK host: in-memory session/settings, empty discovery roots, no tools, one factory-named inline extension. */
+export function piSdkMeasuredSessionHost():MeasuredSessionHost{return{async run(input){
+ const root=await mkdtemp(join(resolve(process.env.TMPDIR??'/tmp'),'pi-daddy-measured-'));let session:Awaited<ReturnType<typeof createAgentSession>>['session']|undefined;
+ try{
+  const agentDir=join(root,'agent');await mkdir(agentDir,{mode:0o700});const settings=SettingsManager.inMemory({compaction:{enabled:false},retry:{enabled:false,maxRetries:0}});
+  const loader=new DefaultResourceLoader({cwd:root,agentDir,settingsManager:settings,systemPromptOverride:()=> 'Follow the supplied bounded task. Do not use tools or claim acceptance.',agentsFilesOverride:()=>({agentsFiles:[],diagnostics:[]}),skillsOverride:()=>({skills:[],diagnostics:[]}),promptsOverride:()=>({prompts:[],diagnostics:[]}),extensionFactories:[{name:'pi-daddy-measured-session',factory:()=>{}}]});await loader.reload();
+  input.signal.throwIfAborted();const runtime=await ModelRuntime.create({signal:input.signal});input.signal.throwIfAborted();await verifyMeasuredSubscription(runtime,input.signal);input.signal.throwIfAborted();
+  const [provider,modelId]=input.model.split('/'),found=runtime.getModel(provider,modelId);if(!found)throw Error('requested measured model unavailable');
+  const created=await createAgentSession({cwd:root,agentDir,model:{...found,maxTokens:input.maxOutputTokens},thinkingLevel:input.thinkingLevel,modelRuntime:runtime,resourceLoader:loader,sessionManager:SessionManager.inMemory(root),settingsManager:settings,noTools:'all'});session=created.session;if(created.extensionsResult.errors.length)throw Error('factory-only extension load failed');
+  const abort=()=>void session!.abort();input.signal.addEventListener('abort',abort,{once:true});try{if(input.signal.aborted){await session.abort();throw input.signal.reason;}await session.prompt(input.prompt,{expandPromptTemplates:false});}finally{input.signal.removeEventListener('abort',abort);}
+  const message=[...session.messages].reverse().find(m=>m.role==='assistant');if(!message)throw Error('measured assistant result unavailable');
+  return {output:message.content.filter(c=>c.type==='text').map(c=>c.text).join(''),usage:message.usage as ProviderUsage,provider:message.provider as MeasuredSessionHostResult['provider'],model:message.model as MeasuredSessionHostResult['model'],stopReason:message.stopReason};
+ }finally{session?.dispose();await rm(root,{recursive:true,force:true});}
+}};}

package/src/run-herdr.ts

@@ -27,9 +27,11 @@ import type { ChildRunResult } from "./run-child.ts";
 import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "./run-child.ts";
 import { MAX_OPEN_PANES, markPaneSettled, trackPane, trimOpenPanes, untrackPane } from "./pane-reaper.ts";
 import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
-import { readPane, waitForSettled, seqOf, observeHerdrSession, type PollTarget } from "./herdr-poll.ts";
+import { FRESH_LIFECYCLE_TIMEOUT_MS, readPane, waitForLifecycleBaseline, waitForSettled, observeHerdrSession, type PollTarget } from "./herdr-poll.ts";
 import { stageSystemPrompt } from "./herdr-stage.ts";
 import { uniqueAgentName } from "./herdr-name.ts";
+import { bundledHerdrPiLifecycleExtension } from "./herdr-pi-lifecycle.ts";
+import { startHerdrAgent } from "./herdr-start.ts";
 
 /**
  * Re-exported so importers of the executor still reach the protocol at the name they always used.
@@ -42,13 +44,15 @@ export { type HerdrExec, parseReply } from "./herdr-cli.ts";
 export { splitSystemPrompt, stageSystemPrompt } from "./herdr-stage.ts";
 /** Re-exported: the name rules moved to `./herdr-name.ts` under the ceiling; tests import them here. */
 export { uniqueAgentName } from "./herdr-name.ts";
+/** Re-exported after startup retry extraction; existing executor importers keep this public constant. */
+export { PANE_READY_POLL_MS } from "./herdr-start.ts";
 /**
  * Re-exported so `test/run-herdr.test.ts` and any importer keep reaching these where they always were.
  *
  * `POLL_INTERVAL_MS` and `newSuffix` moved to `./herdr-poll.ts` under the 400-line ceiling; the names are part
  * of this module's surface and moving a file should not move an export.
  */
-export { DEFAULT_SNAPSHOT_LINES, POLL_INTERVAL_MS, readPane, tailLines, waitForSettled, type PollTarget } from "./herdr-poll.ts";
+export { DEFAULT_SNAPSHOT_LINES, POLL_INTERVAL_MS, readPane, tailLines, waitForLifecycleBaseline, waitForSettled, type PollTarget } from "./herdr-poll.ts";
 
 export interface HerdrRunRequest {
   /** `planSpawn` args **without** the prompt — see `prompt`. */
@@ -122,10 +126,6 @@ export class HerdrWriterCloseError extends Error {
   }
 }
 
-/** How often to retry `agent start` while a freshly created pane is still reaching its shell prompt. */
-export const PANE_READY_POLL_MS = 300;
-
-
 /**
  * Run one governed child in a pane and return its output.
  *
@@ -162,7 +162,16 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
   const staged = await stageSystemPrompt(request.args);
   if (staged.error) return { ...empty, spawnError: staged.error };
   const promptDir = staged.promptDir;
-  const effectiveArgs = staged.args;
+  let lifecycleExtension: string;
+  try {
+    lifecycleExtension = bundledHerdrPiLifecycleExtension();
+  } catch (error) {
+    if (promptDir) await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+    return { ...empty, spawnError: String(error) };
+  }
+  // Pi's `--no-extensions` disables discovery, not this explicit, package-pinned lifecycle reporter. It
+  // registers no tools; pi's existing `--tools` allowlist remains the governed child surface.
+  const effectiveArgs = [...staged.args, "-e", lifecycleExtension];
 
   const create = ["tab", "create", "--label", request.name, "--cwd", request.cwd];
   if (request.workspace) create.push("--workspace", request.workspace);
@@ -301,11 +310,19 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
   let settledCleanly = false;
 
   return runWithFinalizers(async () => {
-    const started = await startAgent(exec, agentName, paneId, effectiveArgs, deadline);
+    const started = await startHerdrAgent(exec, agentName, paneId, effectiveArgs, deadline);
     if (started.error) return { ...empty, spawnError: `herdr agent start failed: ${started.error}` };
 
-    // The state counter BEFORE prompting is what makes the wait correct — see the R-33 note below.
-    const before = seqOf(started.result);
+    // The bundled reporter queues its initial idle state asynchronously. Establish its native-authority
+    // baseline before prompting, otherwise that initial report could advance the counter after prompt and
+    // be mistaken for settlement.
+    const baseline = await waitForLifecycleBaseline(
+      exec,
+      { ...request, name: agentName, nativePaneId: paneId },
+      Math.min(deadline, Date.now() + FRESH_LIFECYCLE_TIMEOUT_MS),
+    );
+    if (baseline.aborted) return { ...empty, aborted: true };
+    if (baseline.spawnError || baseline.before === undefined) return { ...empty, spawnError: baseline.spawnError ?? "Herdr lifecycle baseline is unavailable" };
     observeHerdrSession(started.result?.agent, paneId, request.onSessionReference);
 
     const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
@@ -318,7 +335,7 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
       }
     }
 
-    const settled = await waitForSettled(exec, { ...request, name: agentName, nativePaneId: paneId }, before, deadline, maxOutputBytes);
+    const settled = await waitForSettled(exec, { ...request, name: agentName, nativePaneId: paneId }, baseline.before, deadline, maxOutputBytes);
     if (settled.aborted || settled.timedOut) {
       // Still read: a timed-out child usually produced something, and a partial answer labelled partial is
       // more useful than none. R-03's rule — a missing result must never look like an empty one.
@@ -367,32 +384,3 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
     run: () => cleanup(settledCleanly),
   }]);
 }
-
-/**
- * Start the agent, retrying while the pane is still coming up.
- *
- * **Measured, and only visible once automated.** A pane created by `tab create` is not immediately at a
- * shell prompt, and `herdr agent start` requires one — it fails with
- * `agent_pane_busy: … is not an available shell`. Driving the two commands by hand hid this completely,
- * because the think-time between them was longer than the shell took to start; the first scripted run hit
- * it every time.
- *
- * Retried rather than preceded by a fixed sleep: a sleep long enough for a loaded machine is wasted on
- * every spawn, and a fan-out pays it per child. Only the busy condition is retried — any other error is a
- * real failure and returns immediately.
- */
-async function startAgent(
-  exec: HerdrExec,
-  name: string,
-  paneId: string,
-  args: string[],
-  deadline: number,
-): Promise<{ result?: Record<string, unknown>; error?: string }> {
-  for (;;) {
-    const reply = parseReply(await exec(["agent", "start", name, "--kind", "pi", "--pane", paneId, "--", ...args]));
-    if (!reply.error) return reply;
-    const busy = /not an available shell|agent_pane_busy/.test(reply.error);
-    if (!busy || Date.now() >= deadline) return reply;
-    await new Promise((r) => setTimeout(r, PANE_READY_POLL_MS));
-  }
-}

package/src/vendor/herdr-pi-lifecycle.ts

@@ -0,0 +1,257 @@
+// installed by herdr
+// managed by herdr; reinstalling or updating the integration overwrites this file.
+// add custom hooks/plugins beside this file instead of editing it.
+// HERDR_INTEGRATION_ID=pi
+// HERDR_INTEGRATION_VERSION=8
+// @ts-nocheck
+
+import net from "node:net";
+
+const HERDR_ENV = process.env.HERDR_ENV;
+const socketPath = process.env.HERDR_SOCKET_PATH;
+const socketEndpoint =
+  process.platform === "win32" && socketPath ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+const paneId = process.env.HERDR_PANE_ID;
+const source = "herdr:pi";
+
+function enabled() {
+  return HERDR_ENV === "1" && !!socketPath && !!paneId;
+}
+
+function sendRequestAttempt(request: unknown, timeoutMs: number): Promise<boolean> {
+  if (!enabled()) {
+    return Promise.resolve(true);
+  }
+
+  return new Promise((resolve) => {
+    let done = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const finish = (delivered: boolean) => {
+      if (done) return;
+      done = true;
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      socket.destroy();
+      resolve(delivered);
+    };
+
+    const socket = net.createConnection(socketEndpoint!);
+    socket.on("error", () => finish(false));
+    socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", () => finish(true));
+    socket.on("end", () => finish(false));
+    timeout = setTimeout(() => finish(false), timeoutMs);
+    timeout.unref?.();
+  });
+}
+
+async function sendRequest(request: unknown): Promise<void> {
+  if (await sendRequestAttempt(request, 500)) {
+    return;
+  }
+  await sendRequestAttempt(request, 1500);
+}
+
+type AgentState = "working" | "blocked" | "idle";
+
+type QueuedState = {
+  state: AgentState;
+  message?: string;
+  seq: number;
+};
+
+let reportSeq = Date.now() * 1000;
+let currentAgentSessionId: string | undefined;
+let currentAgentSessionPath: string | undefined;
+
+function nextReportSeq(): number {
+  reportSeq += 1;
+  return reportSeq;
+}
+
+function updateSessionRef(ctx: any): void {
+  try {
+    const file = ctx?.sessionManager?.getSessionFile?.();
+    currentAgentSessionPath =
+      typeof file === "string" && file.startsWith("/") ? file : undefined;
+  } catch {
+    currentAgentSessionPath = undefined;
+  }
+
+  try {
+    const id = ctx?.sessionManager?.getSessionId?.();
+    currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;
+  } catch {
+    currentAgentSessionId = undefined;
+  }
+}
+
+function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {
+  if (currentAgentSessionPath) {
+    return { ...params, agent_session_path: currentAgentSessionPath };
+  }
+  if (currentAgentSessionId) {
+    return { ...params, agent_session_id: currentAgentSessionId };
+  }
+  return params;
+}
+
+function currentSessionRef(): Record<string, unknown> | undefined {
+  if (currentAgentSessionPath) {
+    return { agent_session_path: currentAgentSessionPath };
+  }
+  if (currentAgentSessionId) {
+    return { agent_session_id: currentAgentSessionId };
+  }
+  return undefined;
+}
+
+function reportSession(sessionStartSource?: string): Promise<void> {
+  const sessionRef = currentSessionRef();
+  if (!sessionRef) {
+    return Promise.resolve();
+  }
+
+  return sendRequest({
+    id: `${source}:session:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    method: "pane.report_agent_session",
+    params: {
+      pane_id: paneId,
+      source,
+      agent: "pi",
+      seq: nextReportSeq(),
+      session_start_source: sessionStartSource,
+      ...sessionRef,
+    },
+  });
+}
+
+function sendState(state: AgentState, message?: string, seq = nextReportSeq()): Promise<void> {
+  return sendRequest({
+    id: `${source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    method: "pane.report_agent",
+    params: withSessionRef({
+      pane_id: paneId,
+      source,
+      agent: "pi",
+      state,
+      message,
+      seq,
+    }),
+  });
+}
+
+let sendInFlight = false;
+let queuedState: QueuedState | undefined;
+
+function queueState(state: AgentState, message?: string): void {
+  queuedState = { state, message, seq: nextReportSeq() };
+  if (!sendInFlight) {
+    void drainStateQueue();
+  }
+}
+
+async function drainStateQueue(): Promise<void> {
+  if (sendInFlight) {
+    return;
+  }
+
+  sendInFlight = true;
+  try {
+    while (queuedState) {
+      const next = queuedState;
+      queuedState = undefined;
+      await sendState(next.state, next.message, next.seq);
+    }
+  } finally {
+    sendInFlight = false;
+    if (queuedState) {
+      void drainStateQueue();
+    }
+  }
+}
+
+export default function (pi) {
+  if (!enabled()) {
+    return;
+  }
+
+  let agentActive = false;
+  let blockedCount = 0;
+  let blockedMessage: string | undefined;
+  let lastState: AgentState | undefined;
+  let lastMessage: string | undefined;
+  let rootSession = false;
+
+  function desiredState() {
+    if (blockedCount > 0) {
+      return { state: "blocked" as const, message: blockedMessage };
+    }
+    if (agentActive) {
+      return { state: "working" as const, message: undefined };
+    }
+    return { state: "idle" as const, message: undefined };
+  }
+
+  function publishState(force = false) {
+    const next = desiredState();
+    if (!force && next.state === lastState && next.message === lastMessage) {
+      return;
+    }
+    lastState = next.state;
+    lastMessage = next.message;
+    queueState(next.state, next.message);
+  }
+
+  pi.events.on("herdr:blocked", (data) => {
+    if (!rootSession) {
+      return;
+    }
+    if (!data?.active) {
+      blockedCount = Math.max(0, blockedCount - 1);
+      if (blockedCount === 0) {
+        blockedMessage = undefined;
+      }
+      publishState();
+      return;
+    }
+
+    blockedCount += 1;
+    blockedMessage = data.label;
+    publishState();
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    // TUI only: RPC/JSON/print modes are headless (no PTY herdr can display),
+    // and RPC still reports hasUI=true, so mode is the reliable gate.
+    if (ctx?.mode !== "tui") {
+      return;
+    }
+    rootSession = true;
+    updateSessionRef(ctx);
+    await reportSession(event?.reason);
+    // A reload can replace this extension mid-run without emitting another agent_start.
+    agentActive = ctx?.isIdle?.() === false;
+    publishState(true);
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    if (!rootSession) {
+      return;
+    }
+    updateSessionRef(ctx);
+    void reportSession();
+    agentActive = true;
+    publishState();
+  });
+
+  pi.on("agent_settled", (_event, ctx) => {
+    if (!rootSession || ctx?.isIdle?.() !== true) {
+      return;
+    }
+
+    agentActive = false;
+    publishState();
+  });
+}

package/src/work-command.ts

@@ -16,6 +16,7 @@ import {
   type WorkRevision,
 } from "./work-ledger.ts";
 import { withFileLock } from "./file-lock.ts";
+import { resolveWorkSnapshotText } from "./work-ledger-snapshot.ts";
 
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,127}$/;
 const DIGEST = /^[a-f0-9]{64}$/;
@@ -100,8 +101,8 @@ export async function declareWork(input: DeclareWorkInput): Promise<WorkFrozen<D
   }
   if (!ID.test(input.id) || typeof input.outcome !== "string" || !input.outcome.trim()) throw new TypeError("work declaration requires an identifier and non-empty outcome");
   const resolved = paths(input), outcomeDigest = sha256(input.outcome.trim());
-  await mkdir(dirname(resolved.ledgerPath), { recursive: true });
-  await mkdir(dirname(resolved.statePath), { recursive: true });
+  await mkdir(dirname(resolved.ledgerPath), { recursive: true, mode: 0o700 });
+  await mkdir(dirname(resolved.statePath), { recursive: true, mode: 0o700 });
   return withFileLock(resolved.statePath, "declared work", async () => {
     const existing = await loadDeclaredWork(resolved.statePath);
     if (existing) {
@@ -148,6 +149,11 @@ export async function declareWork(input: DeclareWorkInput): Promise<WorkFrozen<D
   });
 }
 
+/** Persist an already-applied exact selection so the next governed dispatch cannot keep using the old cached declaration. */
+export async function rebindDeclaredWork(state:WorkFrozen<DeclaredWorkState>,selectedSnapshot:NonNullable<WorkProjectionContext["selectedSnapshot"]>):Promise<WorkFrozen<DeclaredWorkState>>{
+ return withFileLock(state.statePath,"declared work rebind",async()=>{const current=await loadDeclaredWork(state.statePath);if(!current||JSON.stringify(current.selectedSnapshot)!==JSON.stringify(state.selectedSnapshot))throw Error("declared work rebind is stale; new dispatch remains unsupported");const text=await readFile(state.ledgerPath,"utf8"),resolved=resolveWorkSnapshotText(text,selectedSnapshot),binding=resolved.snapshot?.bindings[0];if(resolved.scopeState!=="valid"||!resolved.scope||!resolved.snapshot||!binding)throw Error("applied declared selection cannot bind future dispatch");const stored:StoredDeclaredWorkState={version:"pi-daddy-declared-work-v1",id:state.id,outcomeDigest:state.outcomeDigest,ledgerPath:state.ledgerPath,grantLedgerPath:state.grantLedgerPath,selectedSnapshot,scope:{kind:resolved.scope.kind,id:resolved.scope.id,revision:resolved.scope.revision,digest:resolved.scope.digest},intent:binding.intent,obligation:binding.obligation,policy:binding.policy};const temporary=`${state.statePath}.${process.pid}.${randomUUID()}.tmp`;try{await writeFile(temporary,`${JSON.stringify(stored,null,2)}\n`,{encoding:"utf8",mode:0o600,flag:"wx"});await rename(temporary,state.statePath);}finally{await rm(temporary,{force:true});}return Object.freeze({...stored,statePath:state.statePath});});
+}
+
 export type DeclaredOccurrenceIdentity = Pick<WorkOccurrencePayload["labels"], "toolCallId" | "taskId" | "workspaceId" | "definitionDigest" | "configurationDigest" | "modelId" | "effortId"> & {
   executionId: string;
   parentExecutionId: string | null;