@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/yoloop/yoloop-client-state-store.js

@@ -1 +1,1920 @@
-import{promises as u}from"node:fs";import{createHash as V}from"node:crypto";import{join as S,dirname as $}from"node:path";import{hostname as w}from"node:os";import{setSecureFilePermissions as q,setSecureDirPermissions as B}from"../config/secure-config.js";import{RECOVERY_HISTORY_CAP as m}from"./shared-yoloop-types.js";const j=".neocortex",g="yoloop-state.json",J="yoloop.lock",z="yoloop-state.mutation.lock",A="yoloop-session-rollover.json",P="yoloop-successor-transition.json",W=360*60*1e3,G=3e4,X=200,x=Object.freeze(["rollover-session-v1","successor-transition-v1","continuation-replan-v1"]),Z={warn:()=>{},info:()=>{},error:()=>{}};function f(t){const e=t.slice(0,10);return{version:"1.1",lastResetAt:t,storiesRunToday:0,iterationsToday:0,iterationsTodayDate:e,tokensUsedToday:0,lastRunAt:null,coolDownUntil:null,totalRunsAllTime:0,totalStoriesAllTime:0,currentSession:null,continuationPolicy:"p205-finite-resume-v2",pendingContinuationAuthorities:[],continuationReceipts:[],continuationRecoveryReceipts:[]}}function Re(t){return{lock:null,state:f(t),capabilities:x}}class ve{stateDir;statePath;lockPath;mutationLockPath;rolloverManifestPath;successorTransitionManifestPath;logger;constructor(e,s=Z){this.stateDir=S(e,j),this.statePath=S(this.stateDir,g),this.lockPath=S(this.stateDir,J),this.mutationLockPath=S(this.stateDir,z),this.rolloverManifestPath=S(this.stateDir,A),this.successorTransitionManifestPath=S(this.stateDir,P),this.logger=s}async readAll(e){const s=e??new Date().toISOString();await this.cleanupOrphanTempFiles(),await this.recoverSessionRolloverIfPresent(s),await this.recoverSuccessorTransitionIfPresent(s);const[n,o]=await Promise.all([this.readLock(),this.readState(s)]);return{lock:await this.prepareLockForSnapshot(n,s),state:o,capabilities:x}}async applyUpdate(e,s){const n=s??new Date().toISOString();await this.ensureDir(),await this.recoverSessionRolloverIfPresent(n),await this.recoverSuccessorTransitionIfPresent(n);for(const o of e.operations)await this.applyOperation(o,n)}async requestRunTransition(e,s){const n=s??new Date().toISOString();return await this.ensureDir(),this.withMutationLock(()=>this.transitionRun(e,n))}async requestLifecycleAction(e,s={},n){const o=n??new Date().toISOString();return await this.ensureDir(),this.withMutationLock(async()=>{const c=(await this.readState(o)).runControl;if(!c)throw new Error("YOLOOP_RUN_TRANSITION_INVALID");const a=Date.parse(o).toString(36),i=s.operationId??`op-${e}-${a}`,l=s.idempotencyKey??`idem-${e}-${a}`,h=c.receipts.find(y=>y.operationId===i||y.idempotencyKey===l);if(h){if(h.operationId===i&&h.idempotencyKey===l)return h;throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}const O=de(c.status,e);if(!O)throw new Error(T.has(c.status)?"YOLOOP_RUN_TERMINAL":"YOLOOP_RUN_TRANSITION_INVALID");return this.transitionRun(le({current:c,action:e,target:O,operationId:i,idempotencyKey:l,occurredAt:o}),o)})}async applyOperation(e,s){switch(e.type){case"acquire_lock":await this.withMutationLock(()=>this.acquireLock(e.lock,s));return;case"release_lock":await this.withMutationLock(()=>this.releaseLock(e));return;case"write_state":await this.withMutationLock(async()=>{const n=await this.readState(s),{runControl:o,...r}=e.state;await this.writeState({...r,...n.runControl?{version:"1.2",runControl:n.runControl}:{}})});return;case"advance_epic":await this.advanceEpic(e.nextEpicIndex,e.nextEpicId,s);return;case"no_op":this.logger.info({event:"yoloop_noop"},"yoloop server sent no-op");return;case"reserve_continuation_authority":await this.reserveContinuationAuthority(e.authority,s);return;case"acknowledge_continuation_authority":await this.acknowledgeContinuationAuthority(e.idempotencyKey,e.receipt,s);return;case"repair_continuation_authority":await this.repairContinuationAuthority(e.beforeHash,e.authority,e.receipt,s);return;case"switch_continuation_policy":await this.switchContinuationPolicy(e.policy,e.session,s);return;case"transition_run":await this.requestRunTransition(e,s);return;case"start_successor_run":await this.withMutationLock(()=>this.startSuccessorRun(e,s));return;case"commit_successor_transition":await this.withMutationLock(()=>this.commitSuccessorTransition(e,s));return;case"rollover_session":await this.withMutationLock(()=>this.rolloverSession(e,s));return;case"replan_continuation_session":await this.withMutationLock(()=>this.replanContinuationSession(e,s));return;case"recovery_attempted":await this.appendRecoveryAttempt(e.attempt,s);return;case"recovery_resolved":await this.resolveRecoveryAttempt(e.attempt_id,e.outcome,s);return;default:{const n=e;throw this.logger.error({event:"yoloop_unknown_op",op:n},"unknown yoloop operation rejected"),new Error("YOLOOP_STATE_OPERATION_UNSUPPORTED")}}}async reserveContinuationAuthority(e,s){const n=await this.readState(s),o=n.pendingContinuationAuthorities??[],r=typeof e.idempotencyKey=="string"?e.idempotencyKey:"";if(!r)throw new Error("YOLOOP_CONTINUATION_AUTHORITY_INVALID");const c=o.find(a=>a.idempotencyKey===r);if(c){if(d(c)===d(e))return;throw new Error("YOLOOP_CONTINUATION_AUTHORITY_CONFLICT")}if(o.length>=64)throw new Error("YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED");await this.writeState({...n,pendingContinuationAuthorities:[...o,e]})}async acknowledgeContinuationAuthority(e,s,n){const o=await this.readState(n),r=o.pendingContinuationAuthorities??[],c=r.findIndex(h=>h.idempotencyKey===e);if(c<0)throw new Error("YOLOOP_CONTINUATION_RECEIPT_ORPHAN");const a=r[c];if(s.idempotencyKey!==e||s.sessionId!==a.sessionId||JSON.stringify(s.storyIds)!==JSON.stringify(a.storyIds))throw new Error("YOLOOP_CONTINUATION_RECEIPT_MISMATCH");const i=r.filter((h,O)=>O!==c),l=o.continuationReceipts??[];await this.writeState({...o,pendingContinuationAuthorities:i,continuationReceipts:[...l.slice(-63),s]})}async repairContinuationAuthority(e,s,n,o){const r=await this.readState(o),c=r.pendingContinuationAuthorities??[],a=r.continuationRecoveryReceipts??[],i=typeof n.idempotencyKey=="string"?n.idempotencyKey:"",l=a.find(y=>y.idempotencyKey===i);if(l){if(d(l)===d(n))return;throw new Error("YOLOOP_CONTINUATION_RECOVERY_RECEIPT_CONFLICT")}if(c.length!==1||p("p208-legacy-authority-before-v1",c[0])!==e)throw new Error("YOLOOP_CONTINUATION_RECOVERY_BEFORE_MISMATCH");const h=p("p208-legacy-authority-after-v1",s);if(n.beforeHash!==e||n.afterHash!==h)throw new Error("YOLOOP_CONTINUATION_RECOVERY_HASH_MISMATCH");const O={...n};if(delete O.idempotencyKey,!i||p("p208-legacy-authority-recovery-receipt-v1",O)!==i)throw new Error("YOLOOP_CONTINUATION_RECOVERY_RECEIPT_INVALID");await this.writeState({...r,pendingContinuationAuthorities:[s],continuationRecoveryReceipts:[...a.slice(-63),n]})}async switchContinuationPolicy(e,s,n){const o=await this.readState(n);if(o.currentSession||(o.pendingContinuationAuthorities?.length??0)>0)throw new Error("YOLOOP_POLICY_SWITCH_ACTIVE");try{await u.copyFile(this.statePath,`${this.statePath}.policy-backup`)}catch(r){if(r.code!=="ENOENT")throw r}await this.writeState({...o,continuationPolicy:e,continuationSession:s})}async replanContinuationSession(e,s){const{type:n,payloadHash:o,receipt:r,...c}=e;if(Q(c)!==e.payloadHash||!k(e.nextSession))throw new Error("YOLOOP_CONTINUATION_REPLAN_PAYLOAD_INVALID");const a={schemaVersion:"YoloopContinuationReplanReceipt/1.0",operationId:e.operationId,idempotencyKey:e.idempotencyKey,runId:e.expectedRunId,previousSessionHash:e.expectedSessionHash,nextSessionHash:p("p222-yoloop-replan-session-v1",e.nextSession),retiredAuthorityHash:e.expectedPendingHash,retiredAuthorityCount:e.expectedPendingHash===p("p222-yoloop-replan-pending-v1",[])?0:1,payloadHash:e.payloadHash,outcome:"graph-replanned",publicSafe:!0};if(d(e.receipt)!==d(a))throw new Error("YOLOOP_CONTINUATION_REPLAN_RECEIPT_INVALID");const i=await this.readState(s);if(await this.readLock()||i.currentSession!==null)throw new Error("YOLOOP_CONTINUATION_REPLAN_ACTIVE");const l=i.runControl;if(!l||l.runId!==e.expectedRunId||!["success","exhausted"].includes(l.status)||l.revision!==e.expectedRevision||l.latestSnapshotHash!==e.expectedSnapshotHash||i.continuationPolicy!=="p205-finite-resume-v2")throw new Error("YOLOOP_CONTINUATION_REPLAN_RUN_CONFLICT");const h=i.continuationReplanReceipts??[],O=h.find(_=>_.idempotencyKey===e.idempotencyKey||_.operationId===e.operationId);if(O){if(d(O)===d(a)&&d(i.continuationSession)===d(e.nextSession)&&(i.pendingContinuationAuthorities?.length??0)===0)return;throw new Error("YOLOOP_CONTINUATION_REPLAN_REPLAY_CONFLICT")}const y=i.continuationSession,I=i.pendingContinuationAuthorities??[];if(!k(y)||p("p222-yoloop-replan-session-v1",y)!==e.expectedSessionHash||p("p222-yoloop-replan-pending-v1",I)!==e.expectedPendingHash||I.length>1||I.some(_=>_.delegated!==!1||_.sessionId!==y.sessionId||!_.certificate||_.certificate.sessionId!==y.sessionId))throw new Error("YOLOOP_CONTINUATION_REPLAN_AUTHORITY_CONFLICT");await this.writeState({...i,continuationSession:e.nextSession,pendingContinuationAuthorities:[],continuationReplanReceipts:[...h.slice(-63),a]})}async appendRecoveryAttempt(e,s){const n=await this.readState(s),o=n.recovery_history??[];if(o.some(i=>i.attempted_at===e.attempted_at&&i.story_id===e.story_id)){this.logger.warn({event:"recovery_attempted_duplicate",story_id:e.story_id},"duplicate recovery_attempted op; skipping");return}const c=M([...o,e]),a={...n,recovery_history:c};await this.writeState(a),this.logger.info({event:"recovery_attempted_persisted",story_id:e.story_id,history_size:c.length},"recovery attempt persisted")}async resolveRecoveryAttempt(e,s,n){const o=await this.readState(n),r=o.recovery_history??[],c=r.findIndex(h=>h.recovery_step_id_tokenized===e);if(c===-1){this.logger.warn({event:"recovery_resolve_orphan",attempt_id:e},"recovery_resolved op had no matching attempt; skipping");return}const a=r[c];if(a.outcome===s&&a.finished_at){this.logger.info({event:"recovery_resolved_duplicate",attempt_id:e,outcome:s},"duplicate recovery_resolved op; skipping");return}const i=r.slice();i[c]={...a,outcome:s,finished_at:n};const l={...o,recovery_history:i};await this.writeState(l),this.logger.info({event:"recovery_resolved_persisted",attempt_id:e,outcome:s},"recovery attempt resolved")}async acquireLock(e,s){const n={...e,pid:process.pid,hostname:w(),ownerKind:"client",startedAt:e.startedAt||s,leaseId:e.leaseId??he(e.sessionId,s),leaseState:"active",leaseAcquiredAt:e.leaseAcquiredAt??s,leaseDurationMs:e.leaseDurationMs??W,leaseExpiresAt:e.leaseExpiresAt??e.ttlExpiresAt},o=JSON.stringify(n,null,2);try{const r=await u.open(this.lockPath,"wx");try{await r.writeFile(o,"utf8")}finally{await r.close()}this.trySetFilePerms(this.lockPath),this.logger.info({event:"yoloop_lock_acquired",pid:n.pid,sessionId:n.sessionId},"yoloop lock acquired");return}catch(r){const c=r;if(c.code!=="EEXIST")throw this.logger.error({event:"yoloop_lock_acquire_error",err:c.message},"failed to acquire yoloop lock"),r;const a=await this.readLock();if(a&&this.isSameClientSessionLock(a,n)){this.logger.info({event:"yoloop_lock_acquire_duplicate",sessionId:n.sessionId},"duplicate acquire_lock for current yoloop session; treating as no-op");return}if(!await this.maybeRecoverOrphanLock(s))throw this.logger.warn({event:"yoloop_lock_held"},"yoloop lock held by another live process"),r;const l=await u.open(this.lockPath,"wx");try{await l.writeFile(o,"utf8")}finally{await l.close()}this.trySetFilePerms(this.lockPath),this.logger.info({event:"yoloop_lock_acquired_after_recovery",pid:n.pid},"yoloop lock acquired after orphan recovery")}}async releaseLock(e){const s=await this.readState(new Date().toISOString()),n=await this.readLock();if(s.runControl){if(!e.expectedRunId||!e.expectedSessionId||!e.expectedLeaseId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if(e.expectedRunId!==s.runControl.runId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if(!n||e.expectedSessionId!==n.sessionId||e.expectedLeaseId!==n.leaseId)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}try{await u.unlink(this.lockPath),this.logger.info({event:"yoloop_lock_released"},"yoloop lock released")}catch(o){const r=o;if(r.code==="ENOENT"){this.logger.info({event:"yoloop_lock_release_noop"},"yoloop lock release noop (file absent)");return}this.logger.warn({event:"yoloop_lock_release_error",err:r.message},"unexpected error releasing yoloop lock")}}async readLock(){try{const e=await u.readFile(this.lockPath,"utf8"),s=JSON.parse(e),n=s.currentEpicId??s.epicId??"";return{pid:s.pid??0,hostname:s.hostname??"",...s.ownerKind?{ownerKind:s.ownerKind}:{},...s.ownerPidState?{ownerPidState:s.ownerPidState}:{},...typeof s.leaseId=="string"?{leaseId:s.leaseId}:{},...s.leaseState?{leaseState:s.leaseState}:{},...typeof s.leaseAcquiredAt=="string"?{leaseAcquiredAt:s.leaseAcquiredAt}:{},...typeof s.leaseDurationMs=="number"?{leaseDurationMs:s.leaseDurationMs}:{},...typeof s.leaseExpiresAt=="string"?{leaseExpiresAt:s.leaseExpiresAt}:{},startedAt:s.startedAt??"",sessionId:s.sessionId??"",mode:s.mode??"epic-id",inputPath:s.inputPath??"",epicQueue:s.epicQueue??(n?[n]:[]),currentEpicIndex:s.currentEpicIndex??0,currentEpicId:n,ttlExpiresAt:s.ttlExpiresAt??"",epicId:s.epicId??n}}catch{return null}}async readState(e){try{const s=await u.readFile(this.statePath,"utf8"),n=JSON.parse(s);return Oe(n,e)}catch(s){const n=s;return n.code!=="ENOENT"&&this.logger.warn({event:"yoloop_state_read_error",err:n.message},"yoloop state file unreadable; using defaults"),f(e)}}async writeState(e){const s=`${this.statePath}.tmp.${process.pid}.${Date.now()}`,n=JSON.stringify(e,null,2);try{const o=await u.open(s,"w",384);try{await o.writeFile(n,"utf8"),await o.sync()}finally{await o.close()}this.trySetFilePerms(s),await u.rename(s,this.statePath),await this.syncStateDirectory()}catch(o){const r=o;this.logger.error({event:"yoloop_state_write_error",err:r.message},"failed to write yoloop state");try{await u.unlink(s)}catch{}throw o}}async rolloverSession(e,s){E(e);const n=await this.readRolloverManifest();if(n){if(ae(n.operation,e)){if(n.operation.payloadHash!==e.payloadHash)throw new Error("YOLOOP_SESSION_ROLLOVER_CONFLICT");if(n.phase==="applied")return;await this.completePreparedSessionRollover(n.operation,s);return}else if(n.phase==="prepared")throw new Error("YOLOOP_SESSION_ROLLOVER_CONFLICT")}const o=await this.readState(s),r=await this.readLock();U(e,o,r),await this.writeRolloverManifest({schemaVersion:"YoloopSessionRolloverManifest/1.0",phase:"prepared",operation:e}),await this.completePreparedSessionRollover(e,s)}async completePreparedSessionRollover(e,s){const n=await this.readState(s);let o=d(n)===d(e.next);if(!o){const c=await this.readLock();U(e,n,c),await this.writeState(e.next),o=!0}const r=await this.readLock();if(e.expectedSessionId===null||e.expectedLeaseId===null){if(e.expectedSessionId!==null||e.expectedLeaseId!==null||r)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT")}else if(r){if(r.sessionId!==e.expectedSessionId||r.leaseId!==e.expectedLeaseId)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT");await u.unlink(this.lockPath),await this.syncStateDirectory()}else if(!o)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT");await this.writeRolloverManifest({schemaVersion:"YoloopSessionRolloverManifest/1.0",phase:"applied",operation:e}),this.logger.info({event:"yoloop_session_rollover_applied",runId:e.runId,operationId:e.operationId,coolDownUntil:e.coolDownUntil},"yoloop per-run-cap session rollover applied")}async recoverSessionRolloverIfPresent(e){try{await u.access(this.rolloverManifestPath)}catch(s){if(s.code==="ENOENT")return;throw s}await this.ensureDir(),await this.withMutationLock(async()=>{const s=await this.readRolloverManifest();s?.phase==="prepared"&&await this.completePreparedSessionRollover(s.operation,e)})}async readRolloverManifest(){try{const e=JSON.parse(await u.readFile(this.rolloverManifestPath,"utf8"));if(e.schemaVersion!=="YoloopSessionRolloverManifest/1.0"||e.phase!=="prepared"&&e.phase!=="applied"||!e.operation||e.operation.type!=="rollover_session")throw new Error("YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT");return E(e.operation),e}catch(e){if(e.code==="ENOENT")return null;throw e.message==="YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT"?e:new Error("YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT")}}async writeRolloverManifest(e){const s=`${this.rolloverManifestPath}.tmp.${process.pid}.${Date.now()}`,n=await u.open(s,"w",384);try{await n.writeFile(JSON.stringify(e,null,2),"utf8"),await n.sync()}finally{await n.close()}this.trySetFilePerms(s),await u.rename(s,this.rolloverManifestPath),await this.syncStateDirectory()}async commitSuccessorTransition(e,s){R(e);const n=await this.readSuccessorTransitionManifest();if(n){if(oe(n.operation,e)){if(n.operation.payloadHash!==e.payloadHash)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT");if(n.phase==="applied")return;await this.completePreparedSuccessorTransition(n.operation,s);return}if(n.phase==="prepared")throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT")}const o=await this.readState(s);if(v(e,o)){await this.writeSuccessorTransitionManifest({schemaVersion:"YoloopSuccessorTransitionManifest/1.0",phase:"applied",operation:e});return}H(e,o),await this.writeSuccessorTransitionManifest({schemaVersion:"YoloopSuccessorTransitionManifest/1.0",phase:"prepared",operation:e}),await this.completePreparedSuccessorTransition(e,s)}async completePreparedSuccessorTransition(e,s){let n=await this.readState(s);if(!v(e,n)){d(n.runControl)===d(e.successor.next)||(await this.startSuccessorRun(e.successor,s),n=await this.readState(s));const r=ie(e,n);await this.writeState(r),n=await this.readState(s)}if(!v(e,n))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT");await this.writeSuccessorTransitionManifest({schemaVersion:"YoloopSuccessorTransitionManifest/1.0",phase:"applied",operation:e}),this.logger.info({event:"yoloop_successor_transition_applied",runId:e.successor.runId,operationId:e.operationId},"yoloop successor transition applied")}async recoverSuccessorTransitionIfPresent(e){try{await u.access(this.successorTransitionManifestPath)}catch(s){if(s.code==="ENOENT")return;throw s}await this.ensureDir(),await this.withMutationLock(async()=>{const s=await this.readSuccessorTransitionManifest();s?.phase==="prepared"&&await this.completePreparedSuccessorTransition(s.operation,e)})}async readSuccessorTransitionManifest(){try{const e=JSON.parse(await u.readFile(this.successorTransitionManifestPath,"utf8"));if(e.schemaVersion!=="YoloopSuccessorTransitionManifest/1.0"||e.phase!=="prepared"&&e.phase!=="applied"||!e.operation||e.operation.type!=="commit_successor_transition")throw new Error("YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT");return R(e.operation),e}catch(e){if(e.code==="ENOENT")return null;throw e.message==="YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT"?e:new Error("YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT")}}async writeSuccessorTransitionManifest(e){const s=`${this.successorTransitionManifestPath}.tmp.${process.pid}.${Date.now()}`,n=await u.open(s,"w",384);try{await n.writeFile(JSON.stringify(e,null,2),"utf8"),await n.sync()}finally{await n.close()}this.trySetFilePerms(s),await u.rename(s,this.successorTransitionManifestPath),await this.syncStateDirectory()}async advanceEpic(e,s,n){const o=await this.readState(n);if(!o.currentSession){this.logger.warn({event:"yoloop_advance_no_session",nextEpicId:s},"advance_epic with no active session; skipping");return}const r={...o,currentSession:{...o.currentSession,currentEpicIndex:e}};await this.writeState(r),this.logger.info({event:"yoloop_epic_advance",nextEpicId:s,nextIndex:e},"yoloop advanced to next epic")}async ensureDir(){try{await u.mkdir(this.stateDir,{recursive:!0}),this.trySetDirPerms(this.stateDir)}catch(e){const s=e;throw this.logger.error({event:"yoloop_mkdir_error",err:s.message,path:this.stateDir},"failed to ensure .neocortex/ directory"),e}}async syncStateDirectory(){try{const e=await u.open(this.stateDir,"r");try{await e.sync()}finally{await e.close()}}catch(e){const s=e.code;if(s!=="EINVAL"&&s!=="EISDIR"&&s!=="ENOTSUP"&&s!=="EPERM")throw e}}async withMutationLock(e){let s=null;for(let n=0;n<X;n+=1)try{s=await u.open(this.mutationLockPath,"wx",384),await s.writeFile(JSON.stringify({pid:process.pid,acquiredAt:new Date().toISOString()})),await s.sync();break}catch(o){if(o.code!=="EEXIST")throw o;try{const r=await u.stat(this.mutationLockPath);if(Date.now()-r.mtimeMs>G){await u.unlink(this.mutationLockPath);continue}}catch{continue}await new Promise(r=>setTimeout(r,5))}if(!s)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");try{return await e()}finally{await s.close().catch(()=>{}),await u.unlink(this.mutationLockPath).catch(()=>{})}}async transitionRun(e,s){N(e);const n=await this.readState(s),o=n.runControl,r=o?.receipts.find(l=>l.operationId===e.operationId||l.idempotencyKey===e.idempotencyKey);if(r){if(r.operationId===e.operationId&&r.idempotencyKey===e.idempotencyKey&&r.payloadHash===e.payloadHash)return r;throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}if(o&&o.runId!==e.runId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if((o?.revision??0)!==e.expectedRevision)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if((o?.latestSnapshotHash??null)!==e.expectedSnapshotHash)throw new Error("YOLOOP_RUN_SNAPSHOT_CONFLICT");L(o,e);const i=e.next.receipts.at(-1);if(!i)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT");return await this.writeState({...n,version:"1.2",runControl:e.next}),this.logger.info({event:"yoloop_run_transition_committed",runId:e.runId,operationId:e.operationId,revision:i.revision,status:i.status},"yoloop run transition committed"),i}async startSuccessorRun(e,s){Y(e);const n=await this.readState(s),o=n.runControl,r={schemaVersion:"YoloopRunPredecessor/1.0",runId:e.previousRunId,revision:e.expectedRevision,snapshotHash:e.expectedSnapshotHash,successorOperationId:e.operationId,publicSafe:!0},c=o?.receipts.find(l=>l.operationId===e.operationId||l.idempotencyKey===e.idempotencyKey);if(c){if(c.operationId===e.operationId&&c.idempotencyKey===e.idempotencyKey&&e.next.receipts.at(-1)?.payloadHash===c.payloadHash&&d(o?.predecessor)===d(r))return c;throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}if(!o||o.runId!==e.previousRunId||!["exhausted","success"].includes(o.status)||o.revision!==e.expectedRevision||o.latestSnapshotHash!==e.expectedSnapshotHash||n.currentSession!==null)throw new Error("YOLOOP_RUN_SUCCESSOR_CONFLICT");const a=e.next.receipts.at(-1);if(!a||d(e.next.predecessor)!==d(r))throw new Error("YOLOOP_RUN_SUCCESSOR_CONFLICT");const i={type:"transition_run",runId:e.runId,operationId:e.operationId,idempotencyKey:e.idempotencyKey,expectedRevision:0,expectedSnapshotHash:null,payloadHash:a.payloadHash,next:e.next};return N(i),L(void 0,i),await this.writeState({...n,version:"1.2",runControl:e.next}),a}trySetFilePerms(e){try{q(e)}catch{}}trySetDirPerms(e){try{B(e)}catch{}}async prepareLockForSnapshot(e,s){if(!e)return null;if(e.ownerKind!=="client")return e;const n=K(e,s),o={...e,leaseState:n};if(n==="expired")return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_client_lock_recovered",reason:"lease_expired"},"expired client-owned yoloop lock lease recovered before snapshot echo"),null;if(!o.pid||o.pid<=0)return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_client_lock_recovered",reason:"invalid_pid"},"invalid PID in client-owned yoloop lock; recovered"),null;if(o.hostname&&o.hostname!==w())return{...o,ownerPidState:"unknown"};try{return process.kill(o.pid,0),{...o,ownerPidState:"live"}}catch{return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_client_lock_recovered",reason:"dead_pid"},"stale client-owned yoloop lock recovered before snapshot echo"),null}}async maybeRecoverOrphanLock(e){const s=await this.readLock();if(!s)return!0;if(K(s,e)==="expired")return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_orphan_lock_recovered",reason:"lease_expired"},"expired yoloop lock lease recovered"),!0;if(!s.pid||s.pid<=0)return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_orphan_lock_recovered",reason:"invalid_pid"},"invalid PID in lock file; recovered"),!0;if(s.hostname&&s.hostname!==w())return this.logger.warn({event:"yoloop_lock_remote_host",ownerKind:s.ownerKind??"server",ownerPidState:"unknown"},"lock held by a remote host; honoring"),!1;try{return process.kill(s.pid,0),!1}catch{return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_orphan_lock_recovered",reason:"dead_pid"},"orphan yoloop lock recovered"),!0}}async deleteLockBestEffort(){try{await u.unlink(this.lockPath)}catch{}}isSameClientSessionLock(e,s){return e.ownerKind==="client"&&e.sessionId===s.sessionId&&e.pid===process.pid&&e.hostname===w()}async cleanupOrphanTempFiles(){try{const e=$(this.statePath),s=await u.readdir(e),n=[`${g}.tmp.`,`${A}.tmp.`,`${P}.tmp.`],o=s.filter(r=>n.some(c=>r.startsWith(c)));for(const r of o)try{await u.unlink(S(e,r))}catch{}}catch{}}}function d(t){return t===null||typeof t!="object"?JSON.stringify(t):Array.isArray(t)?`[${t.map(d).join(",")}]`:`{${Object.entries(t).filter(([,e])=>e!==void 0).sort(([e],[s])=>e.localeCompare(s)).map(([e,s])=>`${JSON.stringify(e)}:${d(s)}`).join(",")}}`}function p(t,e){return V("sha256").update(`${t}\0${d(e)}`).digest("hex")}function Q(t){return p("p222-yoloop-continuation-replan-v1",t)}function k(t){if(!t||typeof t!="object"||Array.isArray(t))return!1;const{sessionId:e,...s}=t;return typeof e=="string"&&/^[a-f0-9]{64}$/.test(e)&&e===p("p205-yoloop-session-v1",s)}function ee(t){return p("p9390812898200217364-yoloop-session-v1",t)}function te(t){return p("p9390812898200217364-yoloop-rollover-v1",t)}function se(t){return p("p9390812898200217364-yoloop-successor-run-v1",t)}function ne(t){return p("p9046281030721413419-yoloop-successor-transition-v1",t)}function oe(t,e){return t.operationId===e.operationId&&t.idempotencyKey===e.idempotencyKey}function R(t){const e=/^[A-Za-z0-9._:-]{1,128}$/;Y(t.successor);const s={operationId:t.operationId,idempotencyKey:t.idempotencyKey,successor:t.successor,state:t.state,...t.acknowledgement?{acknowledgement:t.acknowledgement}:{},...t.reservation?{reservation:t.reservation}:{}},n=t.acknowledgement?.idempotencyKey,o=t.acknowledgement?.receipt.idempotencyKey,r=t.reservation?.authority.idempotencyKey;if(t.successor.type!=="start_successor_run"||!e.test(t.operationId)||!e.test(t.idempotencyKey)||t.operationId!==t.successor.operationId||t.idempotencyKey!==t.successor.idempotencyKey||!/^[a-f0-9]{64}$/.test(t.payloadHash)||t.payloadHash!==ne(s)||Buffer.byteLength(d(s),"utf8")>1048576||t.acknowledgement!==void 0&&(t.acknowledgement.type!=="acknowledge_continuation_authority"||typeof n!="string"||!e.test(n)||o!==n)||t.reservation!==void 0&&(t.reservation.type!=="reserve_continuation_authority"||typeof r!="string"||!e.test(r))||n!==void 0&&r===n)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT")}function H(t,e){if(R(t),!(d(e.runControl)===d(t.successor.next))){const n=e.runControl;if(!n||n.runId!==t.successor.previousRunId||!["exhausted","success"].includes(n.status)||n.revision!==t.successor.expectedRevision||n.latestSnapshotHash!==t.successor.expectedSnapshotHash||e.currentSession!==null)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT")}re(t,e)}function re(t,e){const s=e.pendingContinuationAuthorities??[],n=e.continuationReceipts??[],o=t.acknowledgement;if(o){const l=s.find(y=>y.idempotencyKey===o.idempotencyKey);if(!l||o.receipt.sessionId!==l.sessionId||d(o.receipt.storyIds)!==d(l.storyIds))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT");const h=s.filter(y=>y.idempotencyKey!==o.idempotencyKey),O=[...n.slice(-63),o.receipt];if(d(t.state.pendingContinuationAuthorities??[])!==d(h)||d(t.state.continuationReceipts??[])!==d(O))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT")}else if(d(t.state.pendingContinuationAuthorities??[])!==d(s)||d(t.state.continuationReceipts??[])!==d(n))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT");const r=t.reservation?.authority;if(!r)return;const c=String(r.idempotencyKey??""),a=t.state.pendingContinuationAuthorities??[],i=a.find(l=>l.idempotencyKey===c);if(i&&d(i)!==d(r))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT");if(!i&&a.length>=64)throw new Error("YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED")}function ie(t,e){H(t,e);const s=t.reservation?.authority,n=[...t.state.pendingContinuationAuthorities??[]];return s&&!n.some(o=>o.idempotencyKey===s.idempotencyKey)&&n.push(s),{...t.state,version:"1.2",runControl:t.successor.next,...s||t.state.pendingContinuationAuthorities!==void 0?{pendingContinuationAuthorities:n}:{}}}function v(t,e){const s=t.reservation?.authority,n=[...t.state.pendingContinuationAuthorities??[]];s&&!n.some(r=>r.idempotencyKey===s.idempotencyKey)&&n.push(s);const o={...t.state,version:"1.2",runControl:t.successor.next,...s||t.state.pendingContinuationAuthorities!==void 0?{pendingContinuationAuthorities:n}:{}};return d(e)===d(o)}function ae(t,e){return t.operationId===e.operationId&&t.idempotencyKey===e.idempotencyKey}function E(t){const e=/^[A-Za-z0-9._:-]{1,128}$/,s={runId:t.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.expectedRevision,expectedSnapshotHash:t.expectedSnapshotHash,expectedSessionId:t.expectedSessionId,expectedSessionFingerprint:t.expectedSessionFingerprint,expectedLeaseId:t.expectedLeaseId,coolDownUntil:t.coolDownUntil,reason:t.reason,exhaustedRun:t.exhaustedRun,next:t.next};if(!e.test(t.runId)||!e.test(t.operationId)||!e.test(t.idempotencyKey)||!/^[a-f0-9]{64}$/.test(t.expectedSessionFingerprint)||!/^[a-f0-9]{64}$/.test(t.payloadHash)||!Number.isSafeInteger(t.expectedRevision)||t.expectedRevision<0||!Number.isFinite(Date.parse(t.coolDownUntil))||!["YOLOOP_PER_RUN_CAP_REACHED","YOLOOP_SESSION_TIMEOUT"].includes(t.reason)||t.payloadHash!==te(s)||t.receipt.schemaVersion!=="YoloopSessionRolloverReceipt/1.0"||t.receipt.runId!==t.runId||t.receipt.operationId!==t.operationId||t.receipt.idempotencyKey!==t.idempotencyKey||t.receipt.payloadHash!==t.payloadHash||t.receipt.coolDownUntil!==t.coolDownUntil||t.receipt.revision!==(t.exhaustedRun?.revision??0)||t.receipt.snapshotHash!==(t.exhaustedRun?.latestSnapshotHash??null)||t.receipt.status!=="exhausted"||t.receipt.publicSafe!==!0)throw new Error("YOLOOP_SESSION_ROLLOVER_CONFLICT");if(t.expectedSessionId===null!=(t.expectedLeaseId===null)||t.expectedSessionId!==null&&!e.test(t.expectedSessionId)||t.expectedLeaseId!==null&&!e.test(t.expectedLeaseId))throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT")}function Y(t){const e=/^[A-Za-z0-9._:-]{1,128}$/,s={runId:t.runId,previousRunId:t.previousRunId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.expectedRevision,expectedSnapshotHash:t.expectedSnapshotHash,next:t.next};if(!e.test(t.runId)||!e.test(t.previousRunId)||t.runId===t.previousRunId||!e.test(t.operationId)||!e.test(t.idempotencyKey)||!/^[a-f0-9]{64}$/.test(t.payloadHash)||!Number.isSafeInteger(t.expectedRevision)||t.expectedRevision<1||t.payloadHash!==se(s))throw new Error("YOLOOP_RUN_SUCCESSOR_CONFLICT")}function U(t,e,s){E(t);const n=e.currentSession;if(!n||ee(n)!==t.expectedSessionFingerprint)throw new Error("YOLOOP_SESSION_ROLLOVER_SESSION_CONFLICT");const o=e.runControl;if((o?.revision??0)!==t.expectedRevision||(o?.latestSnapshotHash??null)!==t.expectedSnapshotHash||o&&o.runId!==t.runId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if(t.expectedSessionId===null||t.expectedLeaseId===null){if(s)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT")}else if(!s||s.sessionId!==t.expectedSessionId||s.leaseId!==t.expectedLeaseId)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT");const r=t.exhaustedRun;if(o)if(o.status==="exhausted"){if(d(r)!==d(o))throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT")}else{if(!r||r.status!=="exhausted")throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT");const a=r.receipts.at(-1);if(!a)throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT");const i={type:"transition_run",runId:o.runId,operationId:a.operationId,idempotencyKey:a.idempotencyKey,expectedRevision:o.revision,expectedSnapshotHash:o.latestSnapshotHash,payloadHash:a.payloadHash,next:r};N(i),L(o,i)}else{const a=r?.receipts[0],i=r?.receipts[1];if(r&&(r.runId!==t.runId||r.status!=="exhausted"||r.revision!==2||r.events.length!==2||r.progressSnapshots.length!==4||r.receipts.length!==2||a?.runId!==t.runId||a.revision!==1||a.status!=="created"||i?.runId!==t.runId||i.revision!==2||i.status!=="exhausted"||i.operationId!==`${t.operationId}:run`||i.idempotencyKey!==`${t.idempotencyKey}:run`||r.latestSnapshotHash!==i.snapshotHash||r.predecessor!==void 0))throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT")}const c={...e,version:"1.2",coolDownUntil:t.coolDownUntil,currentSession:null,...r?{runControl:r}:{}};if(d(c)!==d(t.next))throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT")}function D(t){const{receipts:e,...s}=t.next;return p("p220-yoloop-run-transition-payload-v1",{runId:t.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.expectedRevision,expectedSnapshotHash:t.expectedSnapshotHash,next:s})}const T=new Set(["success","partial","blocked","failure","exhausted","cancelled"]),ce={created:["running","cancelling","exhausted"],running:["pausing","cancelling","success","partial","blocked","failure","exhausted"],pausing:["paused","cancelling","failure","exhausted"],paused:["resuming","cancelling","exhausted"],resuming:["running","cancelling","failure","exhausted"],cancelling:["cancelled","failure","exhausted"]};function de(t,e){return e==="pause"?t==="running"?"pausing":null:e==="resume"?t==="paused"?"resuming":null:T.has(t)||t==="cancelling"?null:"cancelling"}function le(t){const e=t.current.revision+1,s=t.action==="cancel"?["YOLOOP_RUN_CANCEL_REQUESTED"]:[],n={schemaVersion:"YoloopOperationalBudgetSummary/1.0",limits:t.current.operationalBudget.limits,usage:t.current.usage,exhaustedDimension:null},o={schemaVersion:"ProgressSnapshot/1.0",runId:t.current.runId,sequence:t.current.progressSnapshots.length+1,revision:e,operationId:t.operationId,boundary:t.action,phase:"before",status:t.current.status,occurredAt:t.occurredAt,parentSnapshotHash:t.current.latestSnapshotHash,budget:n,reasonCodes:s,publicSafe:!0},r=p("p220-yoloop-progress-snapshot-id-v1",{runId:o.runId,operationId:o.operationId,sequence:o.sequence,phase:o.phase}),c={...o,snapshotId:r,snapshotHash:p("p220-yoloop-progress-snapshot-v1",{...o,snapshotId:r})},a={...o,sequence:c.sequence+1,phase:"after",status:t.target,parentSnapshotHash:c.snapshotHash},i=p("p220-yoloop-progress-snapshot-id-v1",{runId:a.runId,operationId:a.operationId,sequence:a.sequence,phase:a.phase}),l={...a,snapshotId:i,snapshotHash:p("p220-yoloop-progress-snapshot-v1",{...a,snapshotId:i})},h={schemaVersion:"YoloopRunEvent/1.0",runId:t.current.runId,operationId:t.operationId,kind:"intent",sequence:t.current.events.length+1,revision:e,occurredAt:t.occurredAt,fromStatus:t.current.status,toStatus:t.target,reasonCodes:s,budgetDimension:null,parentEventHash:t.current.events.at(-1)?.eventHash??null,publicSafe:!0},O=p("p220-yoloop-run-event-id-v1",{runId:h.runId,operationId:h.operationId,sequence:h.sequence}),y={...h,eventId:O,eventHash:p("p220-yoloop-run-event-v1",{...h,eventId:O})},I={...t.current,revision:e,status:t.target,events:[...t.current.events,y],progressSnapshots:[...t.current.progressSnapshots,c,l],latestSnapshotHash:l.snapshotHash,receipts:[...t.current.receipts]},_={runId:t.current.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.current.revision,expectedSnapshotHash:t.current.latestSnapshotHash,next:I},C=D(_),b={schemaVersion:"YoloopRunTransitionReceipt/1.0",runId:t.current.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,payloadHash:C,revision:e,snapshotHash:l.snapshotHash,status:t.target};return{type:"transition_run",..._,payloadHash:C,next:{...I,receipts:[...I.receipts,b]}}}function N(t){const e=/^[A-Za-z0-9._:-]{1,128}$/;if(!e.test(t.runId)||!e.test(t.operationId)||!e.test(t.idempotencyKey)||!/^[a-f0-9]{64}$/.test(t.payloadHash)||!Number.isSafeInteger(t.expectedRevision)||t.expectedRevision<0)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT");if(t.payloadHash!==D(t))throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}function L(t,e){const s=e.next,n=t?.events??[],o=t?.progressSnapshots??[],r=t?.receipts??[];if(s.schemaVersion!=="YoloopRunControl/1.0"||s.runId!==e.runId||s.revision!==e.expectedRevision+1||s.events.length!==n.length+1||s.progressSnapshots.length!==o.length+2||s.receipts.length!==r.length+1||d(s.events.slice(0,n.length))!==d(n)||d(s.progressSnapshots.slice(0,o.length))!==d(o)||d(s.receipts.slice(0,r.length))!==d(r))throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(t){if(T.has(t.status))throw new Error("YOLOOP_RUN_TERMINAL");const h=s.progressSnapshots.at(-2)?.boundary,O=t.status===s.status&&(h==="budget"||h==="retry");if(!(ce[t.status]??[]).includes(s.status)&&!O)throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(t.startedAt!==s.startedAt||t.deadlineAt!==s.deadlineAt)throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(d(t.predecessor)!==d(s.predecessor))throw new Error("YOLOOP_RUN_TRANSITION_INVALID")}else if(s.status!=="created")throw new Error("YOLOOP_RUN_TRANSITION_INVALID");const c=s.progressSnapshots.at(-2),a=s.progressSnapshots.at(-1),i=s.events.at(-1),l=s.receipts.at(-1);if(!c||!a||!i||!l||c.phase!=="before"||a.phase!=="after"||c.operationId!==e.operationId||a.operationId!==e.operationId||i.operationId!==e.operationId||c.runId!==e.runId||a.runId!==e.runId||i.runId!==e.runId||c.revision!==s.revision||a.revision!==s.revision||i.revision!==s.revision||c.parentSnapshotHash!==(t?.latestSnapshotHash??null)||a.parentSnapshotHash!==c.snapshotHash||s.latestSnapshotHash!==a.snapshotHash||l.schemaVersion!=="YoloopRunTransitionReceipt/1.0"||l.runId!==e.runId||l.operationId!==e.operationId||l.idempotencyKey!==e.idempotencyKey||l.payloadHash!==e.payloadHash||l.revision!==s.revision||l.snapshotHash!==s.latestSnapshotHash||l.status!==s.status||Date.parse(s.deadlineAt)<=Date.parse(s.startedAt))throw new Error("YOLOOP_RUN_TRANSITION_INVALID");F(c),F(a),ue(i,n.at(-1)?.eventHash??null)}function F(t){const{snapshotHash:e,...s}=t;if(e!==p("p220-yoloop-progress-snapshot-v1",s))throw new Error("YOLOOP_RUN_SNAPSHOT_CONFLICT")}function ue(t,e){const{eventHash:s,...n}=t;if(t.parentEventHash!==e||s!==p("p220-yoloop-run-event-v1",n))throw new Error("YOLOOP_RUN_SNAPSHOT_CONFLICT")}function he(t,e){return`lease-${pe(`${t}:${e}`)}`}function pe(t){let e=2166136261;for(let s=0;s<t.length;s+=1)e^=t.charCodeAt(s),e=Math.imul(e,16777619)>>>0;return e.toString(36).padStart(7,"0")}function K(t,e){const s=t.leaseExpiresAt??t.ttlExpiresAt,n=Date.parse(s),o=Date.parse(e);return!Number.isFinite(n)||!Number.isFinite(o)?"unknown":n<=o?"expired":"active"}function Oe(t,e){const s=f(e);return{...t,version:t.version==="1.2"?"1.2":"1.1",lastResetAt:t.lastResetAt??s.lastResetAt,storiesRunToday:t.storiesRunToday??0,iterationsToday:t.iterationsToday??0,iterationsTodayDate:t.iterationsTodayDate??s.iterationsTodayDate,tokensUsedToday:t.tokensUsedToday??0,lastRunAt:t.lastRunAt??null,coolDownUntil:t.coolDownUntil??null,totalRunsAllTime:t.totalRunsAllTime??0,totalStoriesAllTime:t.totalStoriesAllTime??0,currentSession:t.currentSession??null,...t.runControl!==void 0?{runControl:t.runControl}:{},...t.continuationPolicy!==void 0?{continuationPolicy:t.continuationPolicy}:{},...t.continuationSession!==void 0?{continuationSession:t.continuationSession}:{},...t.pendingContinuationAuthorities!==void 0?{pendingContinuationAuthorities:t.pendingContinuationAuthorities}:{},...t.continuationReceipts!==void 0?{continuationReceipts:t.continuationReceipts}:{},...t.continuationRecoveryReceipts!==void 0?{continuationRecoveryReceipts:t.continuationRecoveryReceipts}:{},...t.continuationReplanReceipts!==void 0?{continuationReplanReceipts:t.continuationReplanReceipts}:{},recovery_history:Array.isArray(t.recovery_history)?M(t.recovery_history):[]}}function M(t){return t.length<=m?t:t.slice(t.length-m)}export{x as YOLOOP_PERSISTENCE_CAPABILITIES,ve as YoloopClientStateStore,Q as buildYoloopContinuationReplanPayloadHash,D as buildYoloopRunTransitionPayloadHash,te as buildYoloopSessionRolloverPayloadHash,se as buildYoloopSuccessorRunPayloadHash,ne as buildYoloopSuccessorTransitionPayloadHash,M as capRecoveryHistory,f as createDefaultCounters,Re as createDefaultState,ee as fingerprintYoloopSession};
+/**
+ * Epic P101.06 -- YoloopClientStateStore.
+ *
+ * Client-side counterpart of the (soon-to-be-deleted) server YoloopStateStore.
+ * Owns `.neocortex/yoloop.lock` and `.neocortex/yoloop-state.json` in the
+ * user's local project workspace.
+ *
+ * The client is the ONLY filesystem writer for yoloop state after P101
+ * lands. The server is pure: it reads state echoed by the client via
+ * `stateSnapshot.yoloop` and returns `metadata.yoloopStateUpdate` with an
+ * operation log the client applies here.
+ *
+ * Atomicity guarantees (P96.03):
+ *   - acquireLock uses fs.open(... 'wx') -- POSIX exclusive create
+ *   - writeState uses tmp + rename (POSIX atomic rename)
+ *
+ * Fail-open philosophy (P61.04 / P66.01):
+ *   - chmod / ACL failure -> warn log, NEVER blocks operation
+ *   - release on missing lock is idempotent (no-op)
+ *   - readAll returns defaults on any I/O or parse error
+ *
+ * Cross-platform: Unix chmod + Windows icacls via existing
+ * setSecureFilePermissions helper from secure-config.ts.
+ */
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { hostname } from 'node:os';
+import { setSecureFilePermissions, setSecureDirPermissions } from '../config/secure-config.js';
+import { RECOVERY_HISTORY_CAP } from './shared-yoloop-types.js';
+import { applyCrossEpicContinuationReconciliation, epicOperationalCanonicalJson, epicOperationalHash, mutateEpicOperationalState, readEpicOperationalState, } from '../git/epic-operational-state.js';
+const NEOCORTEX_DIR = '.neocortex';
+const STATE_FILE = 'yoloop-state.json';
+const LOCK_FILE = 'yoloop.lock';
+const MUTATION_LOCK_FILE = 'yoloop-state.mutation.lock';
+const ROLLOVER_MANIFEST_FILE = 'yoloop-session-rollover.json';
+const SUCCESSOR_TRANSITION_MANIFEST_FILE = 'yoloop-successor-transition.json';
+const DEFAULT_LOCK_LEASE_MS = 6 * 60 * 60 * 1000;
+const MUTATION_LOCK_STALE_MS = 30_000;
+const MUTATION_LOCK_RETRIES = 200;
+export const YOLOOP_PERSISTENCE_CAPABILITIES = Object.freeze([
+    'rollover-session-v1',
+    'successor-transition-v1',
+    'continuation-replan-v1',
+]);
+const NOOP_LOGGER = {
+    warn: () => { },
+    info: () => { },
+    error: () => { },
+};
+/** Build default counters for a fresh project (no state file present). */
+export function createDefaultCounters(nowIso) {
+    const dateOnly = nowIso.slice(0, 10);
+    return {
+        version: '1.1',
+        lastResetAt: nowIso,
+        storiesRunToday: 0,
+        iterationsToday: 0,
+        iterationsTodayDate: dateOnly,
+        tokensUsedToday: 0,
+        lastRunAt: null,
+        coolDownUntil: null,
+        totalRunsAllTime: 0,
+        totalStoriesAllTime: 0,
+        currentSession: null,
+        continuationPolicy: 'p205-finite-resume-v2',
+        pendingContinuationAuthorities: [],
+        continuationReceipts: [],
+        continuationRecoveryReceipts: [],
+    };
+}
+/** Build default state envelope (no lock, default counters). */
+export function createDefaultState(nowIso) {
+    return {
+        lock: null,
+        state: createDefaultCounters(nowIso),
+        capabilities: YOLOOP_PERSISTENCE_CAPABILITIES,
+    };
+}
+export class YoloopClientStateStore {
+    projectRoot;
+    stateDir;
+    statePath;
+    lockPath;
+    mutationLockPath;
+    rolloverManifestPath;
+    successorTransitionManifestPath;
+    logger;
+    constructor(projectRoot, logger = NOOP_LOGGER) {
+        this.projectRoot = projectRoot;
+        this.stateDir = join(projectRoot, NEOCORTEX_DIR);
+        this.statePath = join(this.stateDir, STATE_FILE);
+        this.lockPath = join(this.stateDir, LOCK_FILE);
+        this.mutationLockPath = join(this.stateDir, MUTATION_LOCK_FILE);
+        this.rolloverManifestPath = join(this.stateDir, ROLLOVER_MANIFEST_FILE);
+        this.successorTransitionManifestPath = join(this.stateDir, SUCCESSOR_TRANSITION_MANIFEST_FILE);
+        this.logger = logger;
+    }
+    // ── Public read/apply API (P101.06 AC3 + AC4) ───────────────────────
+    /**
+     * Read lock + state in a single call. Used by invoke.ts pre-request hook
+     * to populate `stateSnapshot.yoloop` for the server. Handles ENOENT
+     * gracefully by returning default state.
+     */
+    async readAll(nowIso) {
+        const now = nowIso ?? new Date().toISOString();
+        const common = this.readCommonAuthorityIfPresent();
+        if (common) {
+            return {
+                lock: common.yoloop.lock,
+                state: common.yoloop.state,
+                capabilities: common.yoloop.capabilities,
+            };
+        }
+        await this.cleanupOrphanTempFiles();
+        await this.recoverSessionRolloverIfPresent(now);
+        await this.recoverSuccessorTransitionIfPresent(now);
+        const [rawLock, state] = await Promise.all([this.readLock(), this.readState(now)]);
+        const lock = await this.prepareLockForSnapshot(rawLock, now);
+        return { lock, state, capabilities: YOLOOP_PERSISTENCE_CAPABILITIES };
+    }
+    /**
+     * Apply server-provided operations in order. Called by invoke.ts
+     * post-response hook. Operations are applied atomically per-op; if one
+     * fails, subsequent ops are NOT applied and the caller (invoke.ts)
+     * decides whether to log-and-continue or abort.
+     *
+     * Contract: partial application is safe because each operation is a
+     * single atomic filesystem mutation. Next invoke's readAll() reconciles.
+     */
+    async applyUpdate(update, nowIso) {
+        const now = nowIso ?? new Date().toISOString();
+        if (this.readCommonAuthorityIfPresent()) {
+            for (const op of update.operations)
+                await this.applyCommonOperation(op, now);
+            return;
+        }
+        await this.ensureDir();
+        await this.recoverSessionRolloverIfPresent(now);
+        await this.recoverSuccessorTransitionIfPresent(now);
+        for (const op of update.operations) {
+            await this.applyOperation(op, now);
+        }
+    }
+    /**
+     * Local typed lifecycle-control API. Server transitions and local
+     * pause/resume/cancel requests share this serialized CAS boundary.
+     */
+    async requestRunTransition(operation, nowIso) {
+        const now = nowIso ?? new Date().toISOString();
+        await this.ensureDir();
+        return this.withMutationLock(() => this.transitionRun(operation, now));
+    }
+    /** Persist a cooperative control intent before the next orchestration effect. */
+    async requestLifecycleAction(action, options = {}, nowIso) {
+        const now = nowIso ?? new Date().toISOString();
+        await this.ensureDir();
+        return this.withMutationLock(async () => {
+            const state = await this.readState(now);
+            const current = state.runControl;
+            if (!current)
+                throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+            const suffix = Date.parse(now).toString(36);
+            const operationId = options.operationId ?? `op-${action}-${suffix}`;
+            const idempotencyKey = options.idempotencyKey ?? `idem-${action}-${suffix}`;
+            const replay = current.receipts.find((receipt) => receipt.operationId === operationId || receipt.idempotencyKey === idempotencyKey);
+            if (replay) {
+                if (replay.operationId === operationId && replay.idempotencyKey === idempotencyKey)
+                    return replay;
+                throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+            }
+            const target = localLifecycleRequestTarget(current.status, action);
+            if (!target) {
+                throw new Error(TERMINAL_RUN_STATUSES.has(current.status)
+                    ? 'YOLOOP_RUN_TERMINAL'
+                    : 'YOLOOP_RUN_TRANSITION_INVALID');
+            }
+            return this.transitionRun(buildLocalLifecycleOperation({
+                current, action, target, operationId, idempotencyKey, occurredAt: now,
+            }), now);
+        });
+    }
+    // ── Per-operation dispatch ──────────────────────────────────────────
+    async applyOperation(op, nowIso) {
+        switch (op.type) {
+            case 'acquire_lock':
+                await this.withMutationLock(() => this.acquireLock(op.lock, nowIso));
+                return;
+            case 'release_lock':
+                await this.withMutationLock(() => this.releaseLock(op));
+                return;
+            case 'write_state':
+                await this.withMutationLock(async () => {
+                    const current = await this.readState(nowIso);
+                    const { runControl: _untrustedRunControl, ...legacyCounters } = op.state;
+                    await this.writeState({
+                        ...legacyCounters,
+                        ...(current.runControl
+                            ? { version: '1.2', runControl: current.runControl }
+                            : {}),
+                    });
+                });
+                return;
+            case 'advance_epic':
+                await this.advanceEpic(op.nextEpicIndex, op.nextEpicId, nowIso);
+                return;
+            case 'no_op':
+                this.logger.info({ event: 'yoloop_noop' }, 'yoloop server sent no-op');
+                return;
+            case 'reserve_continuation_authority':
+                await this.reserveContinuationAuthority(op.authority, nowIso);
+                return;
+            case 'acknowledge_continuation_authority':
+                await this.acknowledgeContinuationAuthority(op.idempotencyKey, op.receipt, nowIso);
+                return;
+            case 'repair_continuation_authority':
+                await this.repairContinuationAuthority(op.beforeHash, op.authority, op.receipt, nowIso);
+                return;
+            case 'switch_continuation_policy':
+                await this.switchContinuationPolicy(op.policy, op.session, nowIso);
+                return;
+            case 'transition_run':
+                await this.requestRunTransition(op, nowIso);
+                return;
+            case 'start_successor_run':
+                await this.withMutationLock(() => this.startSuccessorRun(op, nowIso));
+                return;
+            case 'commit_successor_transition':
+                await this.withMutationLock(() => this.commitSuccessorTransition(op, nowIso));
+                return;
+            case 'rollover_session':
+                await this.withMutationLock(() => this.rolloverSession(op, nowIso));
+                return;
+            case 'replan_continuation_session':
+                await this.withMutationLock(() => this.replanContinuationSession(op, nowIso));
+                return;
+            case 'reconcile_cross_epic_continuation':
+                await applyCrossEpicContinuationReconciliation(this.projectRoot, op);
+                return;
+            // ── P104.06: self-healing recovery audit ops ──────────────────────
+            case 'recovery_attempted':
+                await this.appendRecoveryAttempt(op.attempt, nowIso);
+                return;
+            case 'recovery_resolved':
+                await this.resolveRecoveryAttempt(op.attempt_id, op.outcome, nowIso);
+                return;
+            default: {
+                // Exhaustiveness check; never reached for typed inputs but
+                // defensive against forward-compat shape drift.
+                const _exhaustive = op;
+                this.logger.error({ event: 'yoloop_unknown_op', op: _exhaustive }, 'unknown yoloop operation rejected');
+                throw new Error('YOLOOP_STATE_OPERATION_UNSUPPORTED');
+            }
+        }
+    }
+    /**
+     * Runtime v2 is authoritative once present. Missing/non-Git/v1 projects keep
+     * the legacy checkout-local adapter; a corrupt v2 never falls back.
+     */
+    readCommonAuthorityIfPresent() {
+        try {
+            const operational = readEpicOperationalState(this.projectRoot).operational;
+            if (operational.activeJournal !== null)
+                throw new Error('epic-operational-recovery-required');
+            return operational;
+        }
+        catch (error) {
+            if (error instanceof Error && [
+                'git-lifecycle-runtime-missing',
+                'epic-operational-store-missing',
+            ].includes(error.message))
+                return null;
+            if (error instanceof Error && error.message === 'git-lifecycle-common-dir-invalid'
+                && !existsSync(join(this.projectRoot, '.git')))
+                return null;
+            throw error;
+        }
+    }
+    /** Apply legacy operation semantics to the common authority under its Git CAS. */
+    async applyCommonOperation(op, nowIso) {
+        if (op.type === 'no_op')
+            return;
+        if (op.type === 'reconcile_cross_epic_continuation') {
+            await applyCrossEpicContinuationReconciliation(this.projectRoot, op);
+            return;
+        }
+        const { document, operational } = readEpicOperationalState(this.projectRoot);
+        const identities = Object.keys(operational.identities);
+        if (identities.length !== 1)
+            throw new Error('epic-operational-identity-mismatch');
+        const identityHash = identities[0];
+        await mutateEpicOperationalState(this.projectRoot, {
+            identityHash,
+            expectedRevision: document.revision,
+            expectedWriterEpoch: operational.writerEpoch,
+        }, (state) => {
+            const current = state.yoloop.state;
+            let lock = state.yoloop.lock;
+            let next = current;
+            switch (op.type) {
+                case 'acquire_lock': {
+                    if (lock && lock.sessionId !== op.lock.sessionId)
+                        throw new Error('YOLOOP_LOCK_HELD');
+                    lock = {
+                        ...op.lock,
+                        pid: process.pid,
+                        hostname: hostname(),
+                        ownerKind: 'client',
+                        leaseId: op.lock.leaseId ?? buildPublicLeaseId(op.lock.sessionId, nowIso),
+                        leaseState: 'active',
+                        leaseAcquiredAt: op.lock.leaseAcquiredAt ?? nowIso,
+                        leaseDurationMs: op.lock.leaseDurationMs ?? DEFAULT_LOCK_LEASE_MS,
+                        leaseExpiresAt: op.lock.leaseExpiresAt ?? op.lock.ttlExpiresAt,
+                    };
+                    break;
+                }
+                case 'release_lock': {
+                    if (op.expectedSessionId && lock?.sessionId !== op.expectedSessionId)
+                        throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+                    if (op.expectedLeaseId && lock?.leaseId !== op.expectedLeaseId)
+                        throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+                    if (op.expectedRunId && current.runControl?.runId !== op.expectedRunId)
+                        throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+                    lock = null;
+                    break;
+                }
+                case 'write_state': {
+                    const { runControl: _untrusted, ...legacy } = op.state;
+                    next = { ...legacy, ...(current.runControl ? { version: '1.2', runControl: current.runControl } : {}) };
+                    break;
+                }
+                case 'advance_epic': {
+                    if (!current.currentSession)
+                        return;
+                    next = { ...current, currentSession: { ...current.currentSession, currentEpicIndex: op.nextEpicIndex } };
+                    break;
+                }
+                case 'reserve_continuation_authority': {
+                    const pending = current.pendingContinuationAuthorities ?? [];
+                    const key = String(op.authority.idempotencyKey ?? '');
+                    const existing = pending.find((item) => item.idempotencyKey === key);
+                    if (existing) {
+                        if (epicOperationalCanonicalJson(existing) !== epicOperationalCanonicalJson(op.authority)) {
+                            throw new Error('YOLOOP_CONTINUATION_AUTHORITY_CONFLICT');
+                        }
+                        return;
+                    }
+                    if (!key || pending.length >= 64)
+                        throw new Error('YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED');
+                    next = { ...current, pendingContinuationAuthorities: [...pending, op.authority] };
+                    break;
+                }
+                case 'acknowledge_continuation_authority': {
+                    const pending = current.pendingContinuationAuthorities ?? [];
+                    const authority = pending.find((item) => item.idempotencyKey === op.idempotencyKey);
+                    if (!authority)
+                        throw new Error('YOLOOP_CONTINUATION_RECEIPT_ORPHAN');
+                    const receipts = current.continuationReceipts ?? [];
+                    if (receipts.length >= 64)
+                        throw new Error('YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED');
+                    next = {
+                        ...current,
+                        pendingContinuationAuthorities: pending.filter((item) => item !== authority),
+                        continuationReceipts: [...receipts, op.receipt],
+                    };
+                    break;
+                }
+                case 'repair_continuation_authority': {
+                    const pending = current.pendingContinuationAuthorities ?? [];
+                    if (pending.length !== 1 || epicOperationalHash('p208-legacy-authority-before-v1', pending[0]) !== op.beforeHash) {
+                        throw new Error('YOLOOP_CONTINUATION_RECOVERY_BEFORE_MISMATCH');
+                    }
+                    const receipts = current.continuationRecoveryReceipts ?? [];
+                    if (receipts.length >= 64)
+                        throw new Error('YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED');
+                    next = { ...current, pendingContinuationAuthorities: [op.authority], continuationRecoveryReceipts: [...receipts, op.receipt] };
+                    break;
+                }
+                case 'switch_continuation_policy': {
+                    if (current.currentSession || (current.pendingContinuationAuthorities?.length ?? 0) > 0)
+                        throw new Error('YOLOOP_POLICY_SWITCH_ACTIVE');
+                    next = { ...current, continuationPolicy: op.policy, continuationSession: op.session };
+                    break;
+                }
+                case 'transition_run':
+                case 'start_successor_run': {
+                    const run = current.runControl;
+                    if (!run || run.revision !== op.expectedRevision || run.latestSnapshotHash !== op.expectedSnapshotHash) {
+                        throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+                    }
+                    next = { ...current, version: '1.2', runControl: op.next };
+                    break;
+                }
+                case 'commit_successor_transition':
+                    next = { ...op.state, version: '1.2', runControl: op.successor.next };
+                    break;
+                case 'rollover_session':
+                    next = op.next;
+                    lock = null;
+                    break;
+                case 'replan_continuation_session': {
+                    const pending = current.pendingContinuationAuthorities ?? [];
+                    if (epicOperationalHash('p222-yoloop-replan-session-v1', current.continuationSession ?? null) !== op.expectedSessionHash
+                        || epicOperationalHash('p222-yoloop-replan-pending-v1', pending) !== op.expectedPendingHash
+                        || pending.length > 1 || pending.some((item) => item.delegated !== false)) {
+                        throw new Error('YOLOOP_CONTINUATION_REPLAN_AUTHORITY_CONFLICT');
+                    }
+                    const receipts = current.continuationReplanReceipts ?? [];
+                    if (receipts.length >= 64)
+                        throw new Error('YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED');
+                    next = { ...current, continuationSession: op.nextSession, pendingContinuationAuthorities: [], continuationReplanReceipts: [...receipts, op.receipt] };
+                    break;
+                }
+                case 'recovery_attempted':
+                    next = { ...current, recovery_history: capRecoveryHistory([...(current.recovery_history ?? []), op.attempt]) };
+                    break;
+                case 'recovery_resolved': {
+                    const history = [...(current.recovery_history ?? [])];
+                    const index = history.findIndex((item) => item.recovery_step_id_tokenized === op.attempt_id);
+                    if (index >= 0)
+                        history[index] = { ...history[index], outcome: op.outcome, finished_at: nowIso };
+                    next = { ...current, recovery_history: history };
+                    break;
+                }
+                default: {
+                    const _exhaustive = op;
+                    throw new Error(`YOLOOP_STATE_OPERATION_UNSUPPORTED:${String(_exhaustive)}`);
+                }
+            }
+            state.yoloop = { ...state.yoloop, lock, state: next };
+        });
+    }
+    async reserveContinuationAuthority(authority, nowIso) {
+        const current = await this.readState(nowIso);
+        const pending = current.pendingContinuationAuthorities ?? [];
+        const key = typeof authority.idempotencyKey === 'string' ? authority.idempotencyKey : '';
+        if (!key)
+            throw new Error('YOLOOP_CONTINUATION_AUTHORITY_INVALID');
+        const existing = pending.find((item) => item.idempotencyKey === key);
+        if (existing) {
+            if (stablePublicJson(existing) === stablePublicJson(authority))
+                return;
+            throw new Error('YOLOOP_CONTINUATION_AUTHORITY_CONFLICT');
+        }
+        if (pending.length >= 64)
+            throw new Error('YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED');
+        await this.writeState({ ...current, pendingContinuationAuthorities: [...pending, authority] });
+    }
+    async acknowledgeContinuationAuthority(idempotencyKey, receipt, nowIso) {
+        const current = await this.readState(nowIso);
+        const pending = current.pendingContinuationAuthorities ?? [];
+        const index = pending.findIndex((item) => item.idempotencyKey === idempotencyKey);
+        if (index < 0)
+            throw new Error('YOLOOP_CONTINUATION_RECEIPT_ORPHAN');
+        const authority = pending[index];
+        if (receipt.idempotencyKey !== idempotencyKey || receipt.sessionId !== authority.sessionId || JSON.stringify(receipt.storyIds) !== JSON.stringify(authority.storyIds))
+            throw new Error('YOLOOP_CONTINUATION_RECEIPT_MISMATCH');
+        const retained = pending.filter((_, itemIndex) => itemIndex !== index);
+        const receipts = current.continuationReceipts ?? [];
+        await this.writeState({ ...current, pendingContinuationAuthorities: retained, continuationReceipts: [...receipts.slice(-63), receipt] });
+    }
+    async repairContinuationAuthority(beforeHash, authority, receipt, nowIso) {
+        const current = await this.readState(nowIso);
+        const pending = current.pendingContinuationAuthorities ?? [];
+        const recoveryReceipts = current.continuationRecoveryReceipts ?? [];
+        const receiptKey = typeof receipt.idempotencyKey === 'string' ? receipt.idempotencyKey : '';
+        const existingReceipt = recoveryReceipts.find((item) => item.idempotencyKey === receiptKey);
+        if (existingReceipt) {
+            if (stablePublicJson(existingReceipt) === stablePublicJson(receipt))
+                return;
+            throw new Error('YOLOOP_CONTINUATION_RECOVERY_RECEIPT_CONFLICT');
+        }
+        if (pending.length !== 1 || domainHash('p208-legacy-authority-before-v1', pending[0]) !== beforeHash) {
+            throw new Error('YOLOOP_CONTINUATION_RECOVERY_BEFORE_MISMATCH');
+        }
+        const afterHash = domainHash('p208-legacy-authority-after-v1', authority);
+        if (receipt.beforeHash !== beforeHash || receipt.afterHash !== afterHash) {
+            throw new Error('YOLOOP_CONTINUATION_RECOVERY_HASH_MISMATCH');
+        }
+        const receiptBase = { ...receipt };
+        delete receiptBase.idempotencyKey;
+        if (!receiptKey || domainHash('p208-legacy-authority-recovery-receipt-v1', receiptBase) !== receiptKey) {
+            throw new Error('YOLOOP_CONTINUATION_RECOVERY_RECEIPT_INVALID');
+        }
+        await this.writeState({
+            ...current,
+            pendingContinuationAuthorities: [authority],
+            continuationRecoveryReceipts: [...recoveryReceipts.slice(-63), receipt],
+        });
+    }
+    async switchContinuationPolicy(policy, session, nowIso) {
+        const current = await this.readState(nowIso);
+        if (current.currentSession || (current.pendingContinuationAuthorities?.length ?? 0) > 0)
+            throw new Error('YOLOOP_POLICY_SWITCH_ACTIVE');
+        try {
+            await fs.copyFile(this.statePath, `${this.statePath}.policy-backup`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await this.writeState({ ...current, continuationPolicy: policy, continuationSession: session });
+    }
+    async replanContinuationSession(operation, nowIso) {
+        const { type: _type, payloadHash: _payloadHash, receipt: _receipt, ...payload } = operation;
+        if (buildYoloopContinuationReplanPayloadHash(payload) !== operation.payloadHash
+            || !isSealedYoloopFrozenSession(operation.nextSession)) {
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_PAYLOAD_INVALID');
+        }
+        const expectedReceipt = {
+            schemaVersion: 'YoloopContinuationReplanReceipt/1.0',
+            operationId: operation.operationId,
+            idempotencyKey: operation.idempotencyKey,
+            runId: operation.expectedRunId,
+            previousSessionHash: operation.expectedSessionHash,
+            nextSessionHash: domainHash('p222-yoloop-replan-session-v1', operation.nextSession),
+            retiredAuthorityHash: operation.expectedPendingHash,
+            retiredAuthorityCount: operation.expectedPendingHash === domainHash('p222-yoloop-replan-pending-v1', []) ? 0 : 1,
+            payloadHash: operation.payloadHash,
+            outcome: 'graph-replanned',
+            publicSafe: true,
+        };
+        if (stablePublicJson(operation.receipt) !== stablePublicJson(expectedReceipt)) {
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_RECEIPT_INVALID');
+        }
+        const current = await this.readState(nowIso);
+        if (await this.readLock() || current.currentSession !== null) {
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_ACTIVE');
+        }
+        const run = current.runControl;
+        if (!run || run.runId !== operation.expectedRunId
+            || !['success', 'exhausted'].includes(run.status)
+            || run.revision !== operation.expectedRevision
+            || run.latestSnapshotHash !== operation.expectedSnapshotHash
+            || current.continuationPolicy !== 'p205-finite-resume-v2') {
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_RUN_CONFLICT');
+        }
+        const receipts = current.continuationReplanReceipts ?? [];
+        const existing = receipts.find((item) => item.idempotencyKey === operation.idempotencyKey
+            || item.operationId === operation.operationId);
+        if (existing) {
+            if (stablePublicJson(existing) === stablePublicJson(expectedReceipt)
+                && stablePublicJson(current.continuationSession) === stablePublicJson(operation.nextSession)
+                && (current.pendingContinuationAuthorities?.length ?? 0) === 0)
+                return;
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_REPLAY_CONFLICT');
+        }
+        const session = current.continuationSession;
+        const pending = current.pendingContinuationAuthorities ?? [];
+        if (!isSealedYoloopFrozenSession(session)
+            || domainHash('p222-yoloop-replan-session-v1', session) !== operation.expectedSessionHash
+            || domainHash('p222-yoloop-replan-pending-v1', pending) !== operation.expectedPendingHash
+            || pending.length > 1
+            || pending.some((authority) => authority.delegated !== false
+                || authority.sessionId !== session.sessionId
+                || !authority.certificate
+                || authority.certificate.sessionId !== session.sessionId)) {
+            throw new Error('YOLOOP_CONTINUATION_REPLAN_AUTHORITY_CONFLICT');
+        }
+        await this.writeState({
+            ...current,
+            continuationSession: operation.nextSession,
+            pendingContinuationAuthorities: [],
+            continuationReplanReceipts: [...receipts.slice(-63), expectedReceipt],
+        });
+    }
+    // ── P104.06: recovery_history audit semantics ───────────────────────────
+    /**
+     * Append a new recovery attempt to `state.recovery_history[]`. FIFO cap
+     * via `capRecoveryHistory`. Idempotent against retry storms: duplicate
+     * (story_id + attempted_at) entries are skipped with a warn log.
+     */
+    async appendRecoveryAttempt(attempt, nowIso) {
+        const current = await this.readState(nowIso);
+        const history = current.recovery_history ?? [];
+        // P104.06 AC8: idempotency via composite key
+        const isDuplicate = history.some((a) => a.attempted_at === attempt.attempted_at && a.story_id === attempt.story_id);
+        if (isDuplicate) {
+            this.logger.warn({ event: 'recovery_attempted_duplicate', story_id: attempt.story_id }, 'duplicate recovery_attempted op; skipping');
+            return;
+        }
+        const next = capRecoveryHistory([...history, attempt]);
+        const updated = {
+            ...current,
+            recovery_history: next,
+        };
+        await this.writeState(updated);
+        this.logger.info({
+            event: 'recovery_attempted_persisted',
+            story_id: attempt.story_id,
+            history_size: next.length,
+        }, 'recovery attempt persisted');
+    }
+    /**
+     * Resolve a pending recovery attempt by tokenized step id. Updates
+     * `outcome` and stamps `finished_at`. If the attempt was already evicted
+     * by the FIFO cap or never existed, emits a warn log (`recovery_resolve_orphan`)
+     * but does not throw -- bound state cap is a deliberate trade-off.
+     */
+    async resolveRecoveryAttempt(attemptId, outcome, nowIso) {
+        const current = await this.readState(nowIso);
+        const history = current.recovery_history ?? [];
+        const idx = history.findIndex((a) => a.recovery_step_id_tokenized === attemptId);
+        if (idx === -1) {
+            this.logger.warn({ event: 'recovery_resolve_orphan', attempt_id: attemptId }, 'recovery_resolved op had no matching attempt; skipping');
+            return;
+        }
+        const currentAttempt = history[idx];
+        if (currentAttempt.outcome === outcome && currentAttempt.finished_at) {
+            this.logger.info({ event: 'recovery_resolved_duplicate', attempt_id: attemptId, outcome }, 'duplicate recovery_resolved op; skipping');
+            return;
+        }
+        const updatedHistory = history.slice();
+        updatedHistory[idx] = {
+            ...currentAttempt,
+            outcome,
+            finished_at: nowIso,
+        };
+        const updated = {
+            ...current,
+            recovery_history: updatedHistory,
+        };
+        await this.writeState(updated);
+        this.logger.info({ event: 'recovery_resolved_persisted', attempt_id: attemptId, outcome }, 'recovery attempt resolved');
+    }
+    // ── Lock semantics (AC5 + AC6) ──────────────────────────────────────
+    /**
+     * Atomically acquire the yoloop lock. On EEXIST, performs PID liveness
+     * check (same-host) and retries once if orphan detected. Cross-host
+     * locks are honored (cannot signal across hosts).
+     *
+     * The server's `acquire_lock` operation provides the lock payload; we
+     * overwrite the `pid` and `hostname` fields with OUR values (the client
+     * is the authoritative writer of pid/hostname; server can't know them).
+     */
+    async acquireLock(lock, nowIso) {
+        // Replace server-suggested pid+hostname with real client values.
+        const payload = {
+            ...lock,
+            pid: process.pid,
+            hostname: hostname(),
+            ownerKind: 'client',
+            startedAt: lock.startedAt || nowIso,
+            leaseId: lock.leaseId ?? buildPublicLeaseId(lock.sessionId, nowIso),
+            leaseState: 'active',
+            leaseAcquiredAt: lock.leaseAcquiredAt ?? nowIso,
+            leaseDurationMs: lock.leaseDurationMs ?? DEFAULT_LOCK_LEASE_MS,
+            leaseExpiresAt: lock.leaseExpiresAt ?? lock.ttlExpiresAt,
+        };
+        const json = JSON.stringify(payload, null, 2);
+        try {
+            const fh = await fs.open(this.lockPath, 'wx');
+            try {
+                await fh.writeFile(json, 'utf8');
+            }
+            finally {
+                await fh.close();
+            }
+            this.trySetFilePerms(this.lockPath);
+            this.logger.info({ event: 'yoloop_lock_acquired', pid: payload.pid, sessionId: payload.sessionId }, 'yoloop lock acquired');
+            return;
+        }
+        catch (err) {
+            const e = err;
+            if (e.code !== 'EEXIST') {
+                this.logger.error({ event: 'yoloop_lock_acquire_error', err: e.message }, 'failed to acquire yoloop lock');
+                throw err;
+            }
+            const existing = await this.readLock();
+            if (existing && this.isSameClientSessionLock(existing, payload)) {
+                this.logger.info({ event: 'yoloop_lock_acquire_duplicate', sessionId: payload.sessionId }, 'duplicate acquire_lock for current yoloop session; treating as no-op');
+                return;
+            }
+            // EEXIST: try orphan recovery once.
+            const recovered = await this.maybeRecoverOrphanLock(nowIso);
+            if (!recovered) {
+                this.logger.warn({ event: 'yoloop_lock_held' }, 'yoloop lock held by another live process');
+                throw err;
+            }
+            // Retry after orphan recovery.
+            const fh = await fs.open(this.lockPath, 'wx');
+            try {
+                await fh.writeFile(json, 'utf8');
+            }
+            finally {
+                await fh.close();
+            }
+            this.trySetFilePerms(this.lockPath);
+            this.logger.info({ event: 'yoloop_lock_acquired_after_recovery', pid: payload.pid }, 'yoloop lock acquired after orphan recovery');
+        }
+    }
+    /** Release the lock. V1.2 active runs require compare-bound ownership. */
+    async releaseLock(binding) {
+        const current = await this.readState(new Date().toISOString());
+        const lock = await this.readLock();
+        if (current.runControl) {
+            if (!binding.expectedRunId || !binding.expectedSessionId || !binding.expectedLeaseId) {
+                throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+            }
+            if (binding.expectedRunId !== current.runControl.runId) {
+                throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+            }
+            if (!lock
+                || binding.expectedSessionId !== lock.sessionId
+                || binding.expectedLeaseId !== lock.leaseId) {
+                throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+            }
+        }
+        try {
+            await fs.unlink(this.lockPath);
+            this.logger.info({ event: 'yoloop_lock_released' }, 'yoloop lock released');
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === 'ENOENT') {
+                this.logger.info({ event: 'yoloop_lock_release_noop' }, 'yoloop lock release noop (file absent)');
+                return;
+            }
+            this.logger.warn({ event: 'yoloop_lock_release_error', err: e.message }, 'unexpected error releasing yoloop lock');
+        }
+    }
+    /** Read lock file. Returns null on ENOENT / parse error. */
+    async readLock() {
+        try {
+            const raw = await fs.readFile(this.lockPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            const currentEpicId = parsed.currentEpicId ?? parsed.epicId ?? '';
+            return {
+                pid: parsed.pid ?? 0,
+                hostname: parsed.hostname ?? '',
+                ...(parsed.ownerKind ? { ownerKind: parsed.ownerKind } : {}),
+                ...(parsed.ownerPidState ? { ownerPidState: parsed.ownerPidState } : {}),
+                ...(typeof parsed.leaseId === 'string' ? { leaseId: parsed.leaseId } : {}),
+                ...(parsed.leaseState ? { leaseState: parsed.leaseState } : {}),
+                ...(typeof parsed.leaseAcquiredAt === 'string' ? { leaseAcquiredAt: parsed.leaseAcquiredAt } : {}),
+                ...(typeof parsed.leaseDurationMs === 'number' ? { leaseDurationMs: parsed.leaseDurationMs } : {}),
+                ...(typeof parsed.leaseExpiresAt === 'string' ? { leaseExpiresAt: parsed.leaseExpiresAt } : {}),
+                startedAt: parsed.startedAt ?? '',
+                sessionId: parsed.sessionId ?? '',
+                mode: parsed.mode ?? 'epic-id',
+                inputPath: parsed.inputPath ?? '',
+                epicQueue: parsed.epicQueue ?? (currentEpicId ? [currentEpicId] : []),
+                currentEpicIndex: parsed.currentEpicIndex ?? 0,
+                currentEpicId,
+                ttlExpiresAt: parsed.ttlExpiresAt ?? '',
+                epicId: parsed.epicId ?? currentEpicId,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── State semantics (AC5 + AC7) ─────────────────────────────────────
+    /** Read state file; returns defaults on any I/O or parse error. */
+    async readState(nowIso) {
+        try {
+            const raw = await fs.readFile(this.statePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return mergeCountersWithDefaults(parsed, nowIso);
+        }
+        catch (err) {
+            const e = err;
+            if (e.code !== 'ENOENT') {
+                this.logger.warn({ event: 'yoloop_state_read_error', err: e.message }, 'yoloop state file unreadable; using defaults');
+            }
+            return createDefaultCounters(nowIso);
+        }
+    }
+    /** Durable atomic state write: same-filesystem temp + fsync + rename + dir fsync. */
+    async writeState(state) {
+        const tmpPath = `${this.statePath}.tmp.${process.pid}.${Date.now()}`;
+        const json = JSON.stringify(state, null, 2);
+        try {
+            const handle = await fs.open(tmpPath, 'w', 0o600);
+            try {
+                await handle.writeFile(json, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            this.trySetFilePerms(tmpPath);
+            await fs.rename(tmpPath, this.statePath);
+            await this.syncStateDirectory();
+        }
+        catch (err) {
+            const e = err;
+            this.logger.error({ event: 'yoloop_state_write_error', err: e.message }, 'failed to write yoloop state');
+            try {
+                await fs.unlink(tmpPath);
+            }
+            catch {
+                // best-effort cleanup
+            }
+            throw err;
+        }
+    }
+    /**
+     * Apply the per-run-cap boundary as one journaled logical transaction over
+     * yoloop-state.json and yoloop.lock. The mutation lock serializes local
+     * writers; the durable manifest makes every crash point resumable.
+     */
+    async rolloverSession(operation, nowIso) {
+        validateBoundedSessionRollover(operation);
+        const manifest = await this.readRolloverManifest();
+        if (manifest) {
+            if (!sameRolloverIdentity(manifest.operation, operation)) {
+                if (manifest.phase === 'prepared')
+                    throw new Error('YOLOOP_SESSION_ROLLOVER_CONFLICT');
+            }
+            else {
+                if (manifest.operation.payloadHash !== operation.payloadHash) {
+                    throw new Error('YOLOOP_SESSION_ROLLOVER_CONFLICT');
+                }
+                if (manifest.phase === 'applied')
+                    return;
+                await this.completePreparedSessionRollover(manifest.operation, nowIso);
+                return;
+            }
+        }
+        const current = await this.readState(nowIso);
+        const lock = await this.readLock();
+        validateSessionRolloverBeforeState(operation, current, lock);
+        await this.writeRolloverManifest({
+            schemaVersion: 'YoloopSessionRolloverManifest/1.0',
+            phase: 'prepared',
+            operation,
+        });
+        await this.completePreparedSessionRollover(operation, nowIso);
+    }
+    async completePreparedSessionRollover(operation, nowIso) {
+        const current = await this.readState(nowIso);
+        let stateApplied = stablePublicJson(current) === stablePublicJson(operation.next);
+        if (!stateApplied) {
+            const lockBefore = await this.readLock();
+            validateSessionRolloverBeforeState(operation, current, lockBefore);
+            await this.writeState(operation.next);
+            stateApplied = true;
+        }
+        const lock = await this.readLock();
+        if (operation.expectedSessionId === null || operation.expectedLeaseId === null) {
+            if (operation.expectedSessionId !== null || operation.expectedLeaseId !== null || lock) {
+                throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+            }
+        }
+        else if (lock) {
+            if (lock.sessionId !== operation.expectedSessionId
+                || lock.leaseId !== operation.expectedLeaseId) {
+                throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+            }
+            await fs.unlink(this.lockPath);
+            await this.syncStateDirectory();
+        }
+        else if (!stateApplied) {
+            throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+        }
+        await this.writeRolloverManifest({
+            schemaVersion: 'YoloopSessionRolloverManifest/1.0',
+            phase: 'applied',
+            operation,
+        });
+        this.logger.info({
+            event: 'yoloop_session_rollover_applied',
+            runId: operation.runId,
+            operationId: operation.operationId,
+            coolDownUntil: operation.coolDownUntil,
+        }, 'yoloop per-run-cap session rollover applied');
+    }
+    async recoverSessionRolloverIfPresent(nowIso) {
+        try {
+            await fs.access(this.rolloverManifestPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        await this.ensureDir();
+        await this.withMutationLock(async () => {
+            const manifest = await this.readRolloverManifest();
+            if (manifest?.phase === 'prepared') {
+                await this.completePreparedSessionRollover(manifest.operation, nowIso);
+            }
+        });
+    }
+    async readRolloverManifest() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.rolloverManifestPath, 'utf8'));
+            if (parsed.schemaVersion !== 'YoloopSessionRolloverManifest/1.0'
+                || (parsed.phase !== 'prepared' && parsed.phase !== 'applied')
+                || !parsed.operation
+                || parsed.operation.type !== 'rollover_session')
+                throw new Error('YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT');
+            validateBoundedSessionRollover(parsed.operation);
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            if (error.message === 'YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT')
+                throw error;
+            throw new Error('YOLOOP_SESSION_ROLLOVER_MANIFEST_CORRUPT');
+        }
+    }
+    async writeRolloverManifest(manifest) {
+        const tmpPath = `${this.rolloverManifestPath}.tmp.${process.pid}.${Date.now()}`;
+        const handle = await fs.open(tmpPath, 'w', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(manifest, null, 2), 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        this.trySetFilePerms(tmpPath);
+        await fs.rename(tmpPath, this.rolloverManifestPath);
+        await this.syncStateDirectory();
+    }
+    /**
+     * Journal the predecessor replacement, completed-story acknowledgement and
+     * next authority reservation as one recoverable logical CAS transition.
+     * Individual state-file renames remain atomic; the prepared/applied manifest
+     * closes every crash window between them.
+     */
+    async commitSuccessorTransition(operation, nowIso) {
+        validateBoundedSuccessorTransition(operation);
+        const manifest = await this.readSuccessorTransitionManifest();
+        if (manifest) {
+            if (sameSuccessorTransitionIdentity(manifest.operation, operation)) {
+                if (manifest.operation.payloadHash !== operation.payloadHash) {
+                    throw new Error('YOLOOP_SUCCESSOR_TRANSITION_CONFLICT');
+                }
+                if (manifest.phase === 'applied')
+                    return;
+                await this.completePreparedSuccessorTransition(manifest.operation, nowIso);
+                return;
+            }
+            if (manifest.phase === 'prepared') {
+                throw new Error('YOLOOP_SUCCESSOR_TRANSITION_CONFLICT');
+            }
+        }
+        const current = await this.readState(nowIso);
+        if (successorTransitionApplied(operation, current)) {
+            await this.writeSuccessorTransitionManifest({
+                schemaVersion: 'YoloopSuccessorTransitionManifest/1.0',
+                phase: 'applied',
+                operation,
+            });
+            return;
+        }
+        validateSuccessorTransitionBeforeState(operation, current);
+        await this.writeSuccessorTransitionManifest({
+            schemaVersion: 'YoloopSuccessorTransitionManifest/1.0',
+            phase: 'prepared',
+            operation,
+        });
+        await this.completePreparedSuccessorTransition(operation, nowIso);
+    }
+    async completePreparedSuccessorTransition(operation, nowIso) {
+        let current = await this.readState(nowIso);
+        if (!successorTransitionApplied(operation, current)) {
+            const successorApplied = stablePublicJson(current.runControl)
+                === stablePublicJson(operation.successor.next);
+            if (!successorApplied) {
+                await this.startSuccessorRun(operation.successor, nowIso);
+                current = await this.readState(nowIso);
+            }
+            const next = buildSuccessorTransitionState(operation, current);
+            await this.writeState(next);
+            current = await this.readState(nowIso);
+        }
+        if (!successorTransitionApplied(operation, current)) {
+            throw new Error('YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT');
+        }
+        await this.writeSuccessorTransitionManifest({
+            schemaVersion: 'YoloopSuccessorTransitionManifest/1.0',
+            phase: 'applied',
+            operation,
+        });
+        this.logger.info({
+            event: 'yoloop_successor_transition_applied',
+            runId: operation.successor.runId,
+            operationId: operation.operationId,
+        }, 'yoloop successor transition applied');
+    }
+    async recoverSuccessorTransitionIfPresent(nowIso) {
+        try {
+            await fs.access(this.successorTransitionManifestPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        await this.ensureDir();
+        await this.withMutationLock(async () => {
+            const manifest = await this.readSuccessorTransitionManifest();
+            if (manifest?.phase === 'prepared') {
+                await this.completePreparedSuccessorTransition(manifest.operation, nowIso);
+            }
+        });
+    }
+    async readSuccessorTransitionManifest() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.successorTransitionManifestPath, 'utf8'));
+            if (parsed.schemaVersion !== 'YoloopSuccessorTransitionManifest/1.0'
+                || (parsed.phase !== 'prepared' && parsed.phase !== 'applied')
+                || !parsed.operation
+                || parsed.operation.type !== 'commit_successor_transition')
+                throw new Error('YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT');
+            validateBoundedSuccessorTransition(parsed.operation);
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            if (error.message === 'YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT')
+                throw error;
+            throw new Error('YOLOOP_SUCCESSOR_TRANSITION_MANIFEST_CORRUPT');
+        }
+    }
+    async writeSuccessorTransitionManifest(manifest) {
+        const tmpPath = `${this.successorTransitionManifestPath}.tmp.${process.pid}.${Date.now()}`;
+        const handle = await fs.open(tmpPath, 'w', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(manifest, null, 2), 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        this.trySetFilePerms(tmpPath);
+        await fs.rename(tmpPath, this.successorTransitionManifestPath);
+        await this.syncStateDirectory();
+    }
+    /**
+     * Advance to next epic: read-modify-write on currentSession.currentEpicIndex.
+     * Fail-open if no active session (logs warn; subsequent *yoloop will
+     * emit a fresh acquire_lock).
+     */
+    async advanceEpic(nextIndex, nextEpicId, nowIso) {
+        const current = await this.readState(nowIso);
+        if (!current.currentSession) {
+            this.logger.warn({ event: 'yoloop_advance_no_session', nextEpicId }, 'advance_epic with no active session; skipping');
+            return;
+        }
+        const updated = {
+            ...current,
+            currentSession: {
+                ...current.currentSession,
+                currentEpicIndex: nextIndex,
+            },
+        };
+        await this.writeState(updated);
+        this.logger.info({ event: 'yoloop_epic_advance', nextEpicId, nextIndex }, 'yoloop advanced to next epic');
+    }
+    // ── Internal helpers ────────────────────────────────────────────────
+    async ensureDir() {
+        try {
+            await fs.mkdir(this.stateDir, { recursive: true });
+            this.trySetDirPerms(this.stateDir);
+        }
+        catch (err) {
+            const e = err;
+            this.logger.error({ event: 'yoloop_mkdir_error', err: e.message, path: this.stateDir }, 'failed to ensure .neocortex/ directory');
+            throw err;
+        }
+    }
+    async syncStateDirectory() {
+        try {
+            const directory = await fs.open(this.stateDir, 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EINVAL' && code !== 'EISDIR' && code !== 'ENOTSUP' && code !== 'EPERM') {
+                throw error;
+            }
+        }
+    }
+    async withMutationLock(operation) {
+        let handle = null;
+        for (let attempt = 0; attempt < MUTATION_LOCK_RETRIES; attempt += 1) {
+            try {
+                handle = await fs.open(this.mutationLockPath, 'wx', 0o600);
+                await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }));
+                await handle.sync();
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                try {
+                    const stat = await fs.stat(this.mutationLockPath);
+                    if (Date.now() - stat.mtimeMs > MUTATION_LOCK_STALE_MS) {
+                        await fs.unlink(this.mutationLockPath);
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        }
+        if (!handle)
+            throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+        try {
+            return await operation();
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            await fs.unlink(this.mutationLockPath).catch(() => undefined);
+        }
+    }
+    async transitionRun(operation, nowIso) {
+        validateBoundedRunOperation(operation);
+        const current = await this.readState(nowIso);
+        const existing = current.runControl;
+        const replay = existing?.receipts.find((receipt) => receipt.operationId === operation.operationId
+            || receipt.idempotencyKey === operation.idempotencyKey);
+        if (replay) {
+            if (replay.operationId === operation.operationId
+                && replay.idempotencyKey === operation.idempotencyKey
+                && replay.payloadHash === operation.payloadHash)
+                return replay;
+            throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+        }
+        if (existing && existing.runId !== operation.runId) {
+            throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+        }
+        const actualRevision = existing?.revision ?? 0;
+        if (actualRevision !== operation.expectedRevision) {
+            throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+        }
+        const actualSnapshotHash = existing?.latestSnapshotHash ?? null;
+        if (actualSnapshotHash !== operation.expectedSnapshotHash) {
+            throw new Error('YOLOOP_RUN_SNAPSHOT_CONFLICT');
+        }
+        validateProposedRunTransition(existing, operation);
+        const receipt = operation.next.receipts.at(-1);
+        if (!receipt)
+            throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+        await this.writeState({ ...current, version: '1.2', runControl: operation.next });
+        this.logger.info({
+            event: 'yoloop_run_transition_committed',
+            runId: operation.runId,
+            operationId: operation.operationId,
+            revision: receipt.revision,
+            status: receipt.status,
+        }, 'yoloop run transition committed');
+        return receipt;
+    }
+    /** Replace a proven exhausted run, or an explicitly reopened success, with a fresh successor. */
+    async startSuccessorRun(operation, nowIso) {
+        validateBoundedSuccessorRunOperation(operation);
+        const current = await this.readState(nowIso);
+        const existing = current.runControl;
+        const expectedPredecessor = {
+            schemaVersion: 'YoloopRunPredecessor/1.0',
+            runId: operation.previousRunId,
+            revision: operation.expectedRevision,
+            snapshotHash: operation.expectedSnapshotHash,
+            successorOperationId: operation.operationId,
+            publicSafe: true,
+        };
+        const replay = existing?.receipts.find((receipt) => receipt.operationId === operation.operationId
+            || receipt.idempotencyKey === operation.idempotencyKey);
+        if (replay) {
+            if (replay.operationId === operation.operationId
+                && replay.idempotencyKey === operation.idempotencyKey
+                && operation.next.receipts.at(-1)?.payloadHash === replay.payloadHash
+                && stablePublicJson(existing?.predecessor) === stablePublicJson(expectedPredecessor))
+                return replay;
+            throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+        }
+        if (!existing
+            || existing.runId !== operation.previousRunId
+            || !['exhausted', 'success'].includes(existing.status)
+            || existing.revision !== operation.expectedRevision
+            || existing.latestSnapshotHash !== operation.expectedSnapshotHash
+            || current.currentSession !== null)
+            throw new Error('YOLOOP_RUN_SUCCESSOR_CONFLICT');
+        const createdReceipt = operation.next.receipts.at(-1);
+        if (!createdReceipt
+            || stablePublicJson(operation.next.predecessor) !== stablePublicJson(expectedPredecessor))
+            throw new Error('YOLOOP_RUN_SUCCESSOR_CONFLICT');
+        const createdTransition = {
+            type: 'transition_run',
+            runId: operation.runId,
+            operationId: operation.operationId,
+            idempotencyKey: operation.idempotencyKey,
+            expectedRevision: 0,
+            expectedSnapshotHash: null,
+            payloadHash: createdReceipt.payloadHash,
+            next: operation.next,
+        };
+        validateBoundedRunOperation(createdTransition);
+        validateProposedRunTransition(undefined, createdTransition);
+        await this.writeState({ ...current, version: '1.2', runControl: operation.next });
+        return createdReceipt;
+    }
+    /**
+     * Fire-and-forget chmod/ACL. Uses sync helpers from secure-config.ts
+     * which are fail-open by contract (never throw).
+     */
+    trySetFilePerms(path) {
+        try {
+            setSecureFilePermissions(path);
+        }
+        catch {
+            // setSecureFilePermissions is fail-open but be defensive
+        }
+    }
+    trySetDirPerms(path) {
+        try {
+            setSecureDirPermissions(path);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /**
+     * Normalize a lock before echoing it to the server. The local client can
+     * check PID liveness for client-owned same-host locks; the server cannot.
+     */
+    async prepareLockForSnapshot(meta, nowIso) {
+        if (!meta)
+            return null;
+        if (meta.ownerKind !== 'client') {
+            return meta;
+        }
+        const leaseState = classifyClientLease(meta, nowIso);
+        const metaWithLease = { ...meta, leaseState };
+        if (leaseState === 'expired') {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_client_lock_recovered', reason: 'lease_expired' }, 'expired client-owned yoloop lock lease recovered before snapshot echo');
+            return null;
+        }
+        if (!metaWithLease.pid || metaWithLease.pid <= 0) {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_client_lock_recovered', reason: 'invalid_pid' }, 'invalid PID in client-owned yoloop lock; recovered');
+            return null;
+        }
+        if (metaWithLease.hostname && metaWithLease.hostname !== hostname()) {
+            return { ...metaWithLease, ownerPidState: 'unknown' };
+        }
+        try {
+            process.kill(metaWithLease.pid, 0);
+            return { ...metaWithLease, ownerPidState: 'live' };
+        }
+        catch {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_client_lock_recovered', reason: 'dead_pid' }, 'stale client-owned yoloop lock recovered before snapshot echo');
+            return null;
+        }
+    }
+    /**
+     * If the existing lock is held by a dead PID on the same host, delete
+     * it and return true (caller retries acquisition). Otherwise return
+     * false (honor the lock).
+     */
+    async maybeRecoverOrphanLock(nowIso) {
+        const meta = await this.readLock();
+        if (!meta) {
+            // Lock file disappeared between EEXIST and our read -> safe to retry
+            return true;
+        }
+        if (classifyClientLease(meta, nowIso) === 'expired') {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_orphan_lock_recovered', reason: 'lease_expired' }, 'expired yoloop lock lease recovered');
+            return true;
+        }
+        if (!meta.pid || meta.pid <= 0) {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_orphan_lock_recovered', reason: 'invalid_pid' }, 'invalid PID in lock file; recovered');
+            return true;
+        }
+        // Cross-host locks cannot be killed; honor them.
+        if (meta.hostname && meta.hostname !== hostname()) {
+            this.logger.warn({
+                event: 'yoloop_lock_remote_host',
+                ownerKind: meta.ownerKind ?? 'server',
+                ownerPidState: 'unknown',
+            }, 'lock held by a remote host; honoring');
+            return false;
+        }
+        try {
+            process.kill(meta.pid, 0); // liveness check
+            return false; // alive -> honor
+        }
+        catch {
+            await this.deleteLockBestEffort();
+            this.logger.warn({ event: 'yoloop_orphan_lock_recovered', reason: 'dead_pid' }, 'orphan yoloop lock recovered');
+            return true;
+        }
+    }
+    async deleteLockBestEffort() {
+        try {
+            await fs.unlink(this.lockPath);
+        }
+        catch {
+            // ignore
+        }
+    }
+    isSameClientSessionLock(existing, next) {
+        return (existing.ownerKind === 'client' &&
+            existing.sessionId === next.sessionId &&
+            existing.pid === process.pid &&
+            existing.hostname === hostname());
+    }
+    /** Remove `yoloop-state.json.tmp.*` orphans from crashed writes. */
+    async cleanupOrphanTempFiles() {
+        try {
+            const dir = dirname(this.statePath);
+            const entries = await fs.readdir(dir);
+            const stems = [
+                `${STATE_FILE}.tmp.`,
+                `${ROLLOVER_MANIFEST_FILE}.tmp.`,
+                `${SUCCESSOR_TRANSITION_MANIFEST_FILE}.tmp.`,
+            ];
+            const candidates = entries.filter((entry) => stems.some((stem) => entry.startsWith(stem)));
+            for (const entry of candidates) {
+                try {
+                    await fs.unlink(join(dir, entry));
+                }
+                catch {
+                    // ignore individual failures
+                }
+            }
+        }
+        catch {
+            // dir may not exist yet; ignore
+        }
+    }
+}
+function stablePublicJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stablePublicJson).join(',')}]`;
+    return `{${Object.entries(value).filter(([, child]) => child !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => `${JSON.stringify(key)}:${stablePublicJson(child)}`).join(',')}}`;
+}
+function domainHash(domain, value) {
+    return createHash('sha256').update(`${domain}\0${stablePublicJson(value)}`).digest('hex');
+}
+export function buildYoloopContinuationReplanPayloadHash(payload) {
+    return domainHash('p222-yoloop-continuation-replan-v1', payload);
+}
+function isSealedYoloopFrozenSession(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const { sessionId, ...pinned } = value;
+    return typeof sessionId === 'string'
+        && /^[a-f0-9]{64}$/.test(sessionId)
+        && sessionId === domainHash('p205-yoloop-session-v1', pinned);
+}
+export function fingerprintYoloopSession(session) {
+    return domainHash('p9390812898200217364-yoloop-session-v1', session);
+}
+export function buildYoloopSessionRolloverPayloadHash(operation) {
+    return domainHash('p9390812898200217364-yoloop-rollover-v1', operation);
+}
+export function buildYoloopSuccessorRunPayloadHash(operation) {
+    return domainHash('p9390812898200217364-yoloop-successor-run-v1', operation);
+}
+export function buildYoloopSuccessorTransitionPayloadHash(operation) {
+    return domainHash('p9046281030721413419-yoloop-successor-transition-v1', operation);
+}
+function sameSuccessorTransitionIdentity(left, right) {
+    return left.operationId === right.operationId
+        && left.idempotencyKey === right.idempotencyKey;
+}
+function validateBoundedSuccessorTransition(operation) {
+    const boundedId = /^[A-Za-z0-9._:-]{1,128}$/;
+    validateBoundedSuccessorRunOperation(operation.successor);
+    const base = {
+        operationId: operation.operationId,
+        idempotencyKey: operation.idempotencyKey,
+        successor: operation.successor,
+        state: operation.state,
+        ...(operation.acknowledgement ? { acknowledgement: operation.acknowledgement } : {}),
+        ...(operation.reservation ? { reservation: operation.reservation } : {}),
+    };
+    const acknowledgementKey = operation.acknowledgement?.idempotencyKey;
+    const acknowledgementReceiptKey = operation.acknowledgement?.receipt.idempotencyKey;
+    const reservationKey = operation.reservation?.authority.idempotencyKey;
+    if (operation.successor.type !== 'start_successor_run'
+        || !boundedId.test(operation.operationId)
+        || !boundedId.test(operation.idempotencyKey)
+        || operation.operationId !== operation.successor.operationId
+        || operation.idempotencyKey !== operation.successor.idempotencyKey
+        || !/^[a-f0-9]{64}$/.test(operation.payloadHash)
+        || operation.payloadHash !== buildYoloopSuccessorTransitionPayloadHash(base)
+        || Buffer.byteLength(stablePublicJson(base), 'utf8') > 1_048_576
+        || (operation.acknowledgement !== undefined && (operation.acknowledgement.type !== 'acknowledge_continuation_authority'
+            || typeof acknowledgementKey !== 'string'
+            || !boundedId.test(acknowledgementKey)
+            || acknowledgementReceiptKey !== acknowledgementKey))
+        || (operation.reservation !== undefined && (operation.reservation.type !== 'reserve_continuation_authority'
+            || typeof reservationKey !== 'string'
+            || !boundedId.test(reservationKey)))
+        || (acknowledgementKey !== undefined && reservationKey === acknowledgementKey))
+        throw new Error('YOLOOP_SUCCESSOR_TRANSITION_CONFLICT');
+}
+function validateSuccessorTransitionBeforeState(operation, current) {
+    validateBoundedSuccessorTransition(operation);
+    const successorAlreadyApplied = stablePublicJson(current.runControl)
+        === stablePublicJson(operation.successor.next);
+    if (!successorAlreadyApplied) {
+        const predecessor = current.runControl;
+        if (!predecessor
+            || predecessor.runId !== operation.successor.previousRunId
+            || !['exhausted', 'success'].includes(predecessor.status)
+            || predecessor.revision !== operation.successor.expectedRevision
+            || predecessor.latestSnapshotHash !== operation.successor.expectedSnapshotHash
+            || current.currentSession !== null)
+            throw new Error('YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT');
+    }
+    validateSuccessorTransitionAuthorityProjection(operation, current);
+}
+function validateSuccessorTransitionAuthorityProjection(operation, current) {
+    const pending = current.pendingContinuationAuthorities ?? [];
+    const receipts = current.continuationReceipts ?? [];
+    const acknowledgement = operation.acknowledgement;
+    if (acknowledgement) {
+        const authority = pending.find((item) => item.idempotencyKey === acknowledgement.idempotencyKey);
+        if (!authority
+            || acknowledgement.receipt.sessionId !== authority.sessionId
+            || stablePublicJson(acknowledgement.receipt.storyIds) !== stablePublicJson(authority.storyIds))
+            throw new Error('YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT');
+        const projectedPending = pending.filter((item) => item.idempotencyKey !== acknowledgement.idempotencyKey);
+        const projectedReceipts = [...receipts.slice(-63), acknowledgement.receipt];
+        if (stablePublicJson(operation.state.pendingContinuationAuthorities ?? [])
+            !== stablePublicJson(projectedPending)
+            || stablePublicJson(operation.state.continuationReceipts ?? [])
+                !== stablePublicJson(projectedReceipts))
+            throw new Error('YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT');
+    }
+    else if (stablePublicJson(operation.state.pendingContinuationAuthorities ?? []) !== stablePublicJson(pending)
+        || stablePublicJson(operation.state.continuationReceipts ?? []) !== stablePublicJson(receipts)) {
+        throw new Error('YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT');
+    }
+    const reservation = operation.reservation?.authority;
+    if (!reservation)
+        return;
+    const key = String(reservation.idempotencyKey ?? '');
+    const projected = operation.state.pendingContinuationAuthorities ?? [];
+    const existing = projected.find((item) => item.idempotencyKey === key);
+    if (existing && stablePublicJson(existing) !== stablePublicJson(reservation)) {
+        throw new Error('YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT');
+    }
+    if (!existing && projected.length >= 64) {
+        throw new Error('YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED');
+    }
+}
+function buildSuccessorTransitionState(operation, current) {
+    validateSuccessorTransitionBeforeState(operation, current);
+    const reservation = operation.reservation?.authority;
+    const projected = [...(operation.state.pendingContinuationAuthorities ?? [])];
+    if (reservation && !projected.some((item) => item.idempotencyKey === reservation.idempotencyKey)) {
+        projected.push(reservation);
+    }
+    return {
+        ...operation.state,
+        version: '1.2',
+        runControl: operation.successor.next,
+        ...(reservation || operation.state.pendingContinuationAuthorities !== undefined
+            ? { pendingContinuationAuthorities: projected }
+            : {}),
+    };
+}
+function successorTransitionApplied(operation, current) {
+    const reservation = operation.reservation?.authority;
+    const projected = [...(operation.state.pendingContinuationAuthorities ?? [])];
+    if (reservation && !projected.some((item) => item.idempotencyKey === reservation.idempotencyKey)) {
+        projected.push(reservation);
+    }
+    const expected = {
+        ...operation.state,
+        version: '1.2',
+        runControl: operation.successor.next,
+        ...(reservation || operation.state.pendingContinuationAuthorities !== undefined
+            ? { pendingContinuationAuthorities: projected }
+            : {}),
+    };
+    return stablePublicJson(current) === stablePublicJson(expected);
+}
+function sameRolloverIdentity(left, right) {
+    return left.operationId === right.operationId
+        && left.idempotencyKey === right.idempotencyKey;
+}
+function validateBoundedSessionRollover(operation) {
+    const boundedId = /^[A-Za-z0-9._:-]{1,128}$/;
+    const base = {
+        runId: operation.runId,
+        operationId: operation.operationId,
+        idempotencyKey: operation.idempotencyKey,
+        expectedRevision: operation.expectedRevision,
+        expectedSnapshotHash: operation.expectedSnapshotHash,
+        expectedSessionId: operation.expectedSessionId,
+        expectedSessionFingerprint: operation.expectedSessionFingerprint,
+        expectedLeaseId: operation.expectedLeaseId,
+        coolDownUntil: operation.coolDownUntil,
+        reason: operation.reason,
+        exhaustedRun: operation.exhaustedRun,
+        next: operation.next,
+    };
+    if (!boundedId.test(operation.runId)
+        || !boundedId.test(operation.operationId)
+        || !boundedId.test(operation.idempotencyKey)
+        || !/^[a-f0-9]{64}$/.test(operation.expectedSessionFingerprint)
+        || !/^[a-f0-9]{64}$/.test(operation.payloadHash)
+        || !Number.isSafeInteger(operation.expectedRevision)
+        || operation.expectedRevision < 0
+        || !Number.isFinite(Date.parse(operation.coolDownUntil))
+        || !['YOLOOP_PER_RUN_CAP_REACHED', 'YOLOOP_SESSION_TIMEOUT'].includes(operation.reason)
+        || operation.payloadHash !== buildYoloopSessionRolloverPayloadHash(base)
+        || operation.receipt.schemaVersion !== 'YoloopSessionRolloverReceipt/1.0'
+        || operation.receipt.runId !== operation.runId
+        || operation.receipt.operationId !== operation.operationId
+        || operation.receipt.idempotencyKey !== operation.idempotencyKey
+        || operation.receipt.payloadHash !== operation.payloadHash
+        || operation.receipt.coolDownUntil !== operation.coolDownUntil
+        || operation.receipt.revision !== (operation.exhaustedRun?.revision ?? 0)
+        || operation.receipt.snapshotHash !== (operation.exhaustedRun?.latestSnapshotHash ?? null)
+        || operation.receipt.status !== 'exhausted'
+        || operation.receipt.publicSafe !== true)
+        throw new Error('YOLOOP_SESSION_ROLLOVER_CONFLICT');
+    if ((operation.expectedSessionId === null) !== (operation.expectedLeaseId === null)
+        || (operation.expectedSessionId !== null && !boundedId.test(operation.expectedSessionId))
+        || (operation.expectedLeaseId !== null && !boundedId.test(operation.expectedLeaseId)))
+        throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+}
+function validateBoundedSuccessorRunOperation(operation) {
+    const boundedId = /^[A-Za-z0-9._:-]{1,128}$/;
+    const base = {
+        runId: operation.runId,
+        previousRunId: operation.previousRunId,
+        operationId: operation.operationId,
+        idempotencyKey: operation.idempotencyKey,
+        expectedRevision: operation.expectedRevision,
+        expectedSnapshotHash: operation.expectedSnapshotHash,
+        next: operation.next,
+    };
+    if (!boundedId.test(operation.runId)
+        || !boundedId.test(operation.previousRunId)
+        || operation.runId === operation.previousRunId
+        || !boundedId.test(operation.operationId)
+        || !boundedId.test(operation.idempotencyKey)
+        || !/^[a-f0-9]{64}$/.test(operation.payloadHash)
+        || !Number.isSafeInteger(operation.expectedRevision)
+        || operation.expectedRevision < 1
+        || operation.payloadHash !== buildYoloopSuccessorRunPayloadHash(base))
+        throw new Error('YOLOOP_RUN_SUCCESSOR_CONFLICT');
+}
+function validateSessionRolloverBeforeState(operation, current, lock) {
+    validateBoundedSessionRollover(operation);
+    const session = current.currentSession;
+    if (!session || fingerprintYoloopSession(session) !== operation.expectedSessionFingerprint) {
+        throw new Error('YOLOOP_SESSION_ROLLOVER_SESSION_CONFLICT');
+    }
+    const currentRun = current.runControl;
+    if ((currentRun?.revision ?? 0) !== operation.expectedRevision
+        || (currentRun?.latestSnapshotHash ?? null) !== operation.expectedSnapshotHash
+        || (currentRun && currentRun.runId !== operation.runId))
+        throw new Error('YOLOOP_RUN_REVISION_CONFLICT');
+    if (operation.expectedSessionId === null || operation.expectedLeaseId === null) {
+        if (lock)
+            throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+    }
+    else if (!lock
+        || lock.sessionId !== operation.expectedSessionId
+        || lock.leaseId !== operation.expectedLeaseId) {
+        throw new Error('YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT');
+    }
+    const nextRun = operation.exhaustedRun;
+    if (!currentRun) {
+        const createdReceipt = nextRun?.receipts[0];
+        const exhaustedReceipt = nextRun?.receipts[1];
+        if (nextRun && (nextRun.runId !== operation.runId
+            || nextRun.status !== 'exhausted'
+            || nextRun.revision !== 2
+            || nextRun.events.length !== 2
+            || nextRun.progressSnapshots.length !== 4
+            || nextRun.receipts.length !== 2
+            || createdReceipt?.runId !== operation.runId
+            || createdReceipt.revision !== 1
+            || createdReceipt.status !== 'created'
+            || exhaustedReceipt?.runId !== operation.runId
+            || exhaustedReceipt.revision !== 2
+            || exhaustedReceipt.status !== 'exhausted'
+            || exhaustedReceipt.operationId !== `${operation.operationId}:run`
+            || exhaustedReceipt.idempotencyKey !== `${operation.idempotencyKey}:run`
+            || nextRun.latestSnapshotHash !== exhaustedReceipt.snapshotHash
+            || nextRun.predecessor !== undefined))
+            throw new Error('YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT');
+    }
+    else if (currentRun.status === 'exhausted') {
+        if (stablePublicJson(nextRun) !== stablePublicJson(currentRun)) {
+            throw new Error('YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT');
+        }
+    }
+    else {
+        if (!nextRun || nextRun.status !== 'exhausted') {
+            throw new Error('YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT');
+        }
+        const receipt = nextRun.receipts.at(-1);
+        if (!receipt)
+            throw new Error('YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT');
+        const transition = {
+            type: 'transition_run',
+            runId: currentRun.runId,
+            operationId: receipt.operationId,
+            idempotencyKey: receipt.idempotencyKey,
+            expectedRevision: currentRun.revision,
+            expectedSnapshotHash: currentRun.latestSnapshotHash,
+            payloadHash: receipt.payloadHash,
+            next: nextRun,
+        };
+        validateBoundedRunOperation(transition);
+        validateProposedRunTransition(currentRun, transition);
+    }
+    const expectedNext = {
+        ...current,
+        version: '1.2',
+        coolDownUntil: operation.coolDownUntil,
+        currentSession: null,
+        ...(nextRun ? { runControl: nextRun } : {}),
+    };
+    if (stablePublicJson(expectedNext) !== stablePublicJson(operation.next)) {
+        throw new Error('YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT');
+    }
+}
+export function buildYoloopRunTransitionPayloadHash(input) {
+    const { receipts: _receipts, ...nextWithoutReceipts } = input.next;
+    return domainHash('p220-yoloop-run-transition-payload-v1', {
+        runId: input.runId,
+        operationId: input.operationId,
+        idempotencyKey: input.idempotencyKey,
+        expectedRevision: input.expectedRevision,
+        expectedSnapshotHash: input.expectedSnapshotHash,
+        next: nextWithoutReceipts,
+    });
+}
+const TERMINAL_RUN_STATUSES = new Set([
+    'success', 'partial', 'blocked', 'failure', 'exhausted', 'cancelled',
+]);
+const RUN_EDGES = {
+    created: ['running', 'cancelling', 'exhausted'],
+    running: ['pausing', 'cancelling', 'success', 'partial', 'blocked', 'failure', 'exhausted'],
+    pausing: ['paused', 'cancelling', 'failure', 'exhausted'],
+    paused: ['resuming', 'cancelling', 'exhausted'],
+    resuming: ['running', 'cancelling', 'failure', 'exhausted'],
+    cancelling: ['cancelled', 'failure', 'exhausted'],
+};
+function localLifecycleRequestTarget(status, action) {
+    if (action === 'pause')
+        return status === 'running' ? 'pausing' : null;
+    if (action === 'resume')
+        return status === 'paused' ? 'resuming' : null;
+    return TERMINAL_RUN_STATUSES.has(status) || status === 'cancelling' ? null : 'cancelling';
+}
+function buildLocalLifecycleOperation(input) {
+    const revision = input.current.revision + 1;
+    const reasonCodes = input.action === 'cancel' ? ['YOLOOP_RUN_CANCEL_REQUESTED'] : [];
+    const budget = {
+        schemaVersion: 'YoloopOperationalBudgetSummary/1.0',
+        limits: input.current.operationalBudget.limits,
+        usage: input.current.usage,
+        exhaustedDimension: null,
+    };
+    const beforeBase = {
+        schemaVersion: 'ProgressSnapshot/1.0',
+        runId: input.current.runId,
+        sequence: input.current.progressSnapshots.length + 1,
+        revision,
+        operationId: input.operationId,
+        boundary: input.action,
+        phase: 'before',
+        status: input.current.status,
+        occurredAt: input.occurredAt,
+        parentSnapshotHash: input.current.latestSnapshotHash,
+        budget,
+        reasonCodes,
+        publicSafe: true,
+    };
+    const beforeId = domainHash('p220-yoloop-progress-snapshot-id-v1', {
+        runId: beforeBase.runId, operationId: beforeBase.operationId,
+        sequence: beforeBase.sequence, phase: beforeBase.phase,
+    });
+    const before = {
+        ...beforeBase,
+        snapshotId: beforeId,
+        snapshotHash: domainHash('p220-yoloop-progress-snapshot-v1', { ...beforeBase, snapshotId: beforeId }),
+    };
+    const afterBase = {
+        ...beforeBase,
+        sequence: before.sequence + 1,
+        phase: 'after',
+        status: input.target,
+        parentSnapshotHash: before.snapshotHash,
+    };
+    const afterId = domainHash('p220-yoloop-progress-snapshot-id-v1', {
+        runId: afterBase.runId, operationId: afterBase.operationId,
+        sequence: afterBase.sequence, phase: afterBase.phase,
+    });
+    const after = {
+        ...afterBase,
+        snapshotId: afterId,
+        snapshotHash: domainHash('p220-yoloop-progress-snapshot-v1', { ...afterBase, snapshotId: afterId }),
+    };
+    const eventBase = {
+        schemaVersion: 'YoloopRunEvent/1.0',
+        runId: input.current.runId,
+        operationId: input.operationId,
+        kind: 'intent',
+        sequence: input.current.events.length + 1,
+        revision,
+        occurredAt: input.occurredAt,
+        fromStatus: input.current.status,
+        toStatus: input.target,
+        reasonCodes,
+        budgetDimension: null,
+        parentEventHash: input.current.events.at(-1)?.eventHash ?? null,
+        publicSafe: true,
+    };
+    const eventId = domainHash('p220-yoloop-run-event-id-v1', {
+        runId: eventBase.runId, operationId: eventBase.operationId, sequence: eventBase.sequence,
+    });
+    const event = {
+        ...eventBase,
+        eventId,
+        eventHash: domainHash('p220-yoloop-run-event-v1', { ...eventBase, eventId }),
+    };
+    const nextWithoutReceipt = {
+        ...input.current,
+        revision,
+        status: input.target,
+        events: [...input.current.events, event],
+        progressSnapshots: [...input.current.progressSnapshots, before, after],
+        latestSnapshotHash: after.snapshotHash,
+        receipts: [...input.current.receipts],
+    };
+    const base = {
+        runId: input.current.runId,
+        operationId: input.operationId,
+        idempotencyKey: input.idempotencyKey,
+        expectedRevision: input.current.revision,
+        expectedSnapshotHash: input.current.latestSnapshotHash,
+        next: nextWithoutReceipt,
+    };
+    const payloadHash = buildYoloopRunTransitionPayloadHash(base);
+    const receipt = {
+        schemaVersion: 'YoloopRunTransitionReceipt/1.0',
+        runId: input.current.runId,
+        operationId: input.operationId,
+        idempotencyKey: input.idempotencyKey,
+        payloadHash,
+        revision,
+        snapshotHash: after.snapshotHash,
+        status: input.target,
+    };
+    return {
+        type: 'transition_run', ...base, payloadHash,
+        next: { ...nextWithoutReceipt, receipts: [...nextWithoutReceipt.receipts, receipt] },
+    };
+}
+function validateBoundedRunOperation(operation) {
+    const boundedId = /^[A-Za-z0-9._:-]{1,128}$/;
+    if (!boundedId.test(operation.runId)
+        || !boundedId.test(operation.operationId)
+        || !boundedId.test(operation.idempotencyKey)
+        || !/^[a-f0-9]{64}$/.test(operation.payloadHash)
+        || !Number.isSafeInteger(operation.expectedRevision)
+        || operation.expectedRevision < 0)
+        throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+    if (operation.payloadHash !== buildYoloopRunTransitionPayloadHash(operation)) {
+        throw new Error('YOLOOP_RUN_OPERATION_CONFLICT');
+    }
+}
+function validateProposedRunTransition(current, operation) {
+    const next = operation.next;
+    const currentEvents = current?.events ?? [];
+    const currentSnapshots = current?.progressSnapshots ?? [];
+    const currentReceipts = current?.receipts ?? [];
+    if (next.schemaVersion !== 'YoloopRunControl/1.0'
+        || next.runId !== operation.runId
+        || next.revision !== operation.expectedRevision + 1
+        || next.events.length !== currentEvents.length + 1
+        || next.progressSnapshots.length !== currentSnapshots.length + 2
+        || next.receipts.length !== currentReceipts.length + 1
+        || stablePublicJson(next.events.slice(0, currentEvents.length)) !== stablePublicJson(currentEvents)
+        || stablePublicJson(next.progressSnapshots.slice(0, currentSnapshots.length)) !== stablePublicJson(currentSnapshots)
+        || stablePublicJson(next.receipts.slice(0, currentReceipts.length)) !== stablePublicJson(currentReceipts))
+        throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+    if (current) {
+        if (TERMINAL_RUN_STATUSES.has(current.status))
+            throw new Error('YOLOOP_RUN_TERMINAL');
+        const proposedBoundary = next.progressSnapshots.at(-2)?.boundary;
+        const boundaryOnly = current.status === next.status
+            && (proposedBoundary === 'budget' || proposedBoundary === 'retry');
+        if (!(RUN_EDGES[current.status] ?? []).includes(next.status) && !boundaryOnly) {
+            throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+        }
+        if (current.startedAt !== next.startedAt || current.deadlineAt !== next.deadlineAt) {
+            throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+        }
+        if (stablePublicJson(current.predecessor) !== stablePublicJson(next.predecessor)) {
+            throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+        }
+    }
+    else if (next.status !== 'created') {
+        throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+    }
+    const before = next.progressSnapshots.at(-2);
+    const after = next.progressSnapshots.at(-1);
+    const event = next.events.at(-1);
+    const receipt = next.receipts.at(-1);
+    if (!before || !after || !event || !receipt
+        || before.phase !== 'before' || after.phase !== 'after'
+        || before.operationId !== operation.operationId || after.operationId !== operation.operationId
+        || event.operationId !== operation.operationId
+        || before.runId !== operation.runId || after.runId !== operation.runId || event.runId !== operation.runId
+        || before.revision !== next.revision || after.revision !== next.revision || event.revision !== next.revision
+        || before.parentSnapshotHash !== (current?.latestSnapshotHash ?? null)
+        || after.parentSnapshotHash !== before.snapshotHash
+        || next.latestSnapshotHash !== after.snapshotHash
+        || receipt.schemaVersion !== 'YoloopRunTransitionReceipt/1.0'
+        || receipt.runId !== operation.runId
+        || receipt.operationId !== operation.operationId
+        || receipt.idempotencyKey !== operation.idempotencyKey
+        || receipt.payloadHash !== operation.payloadHash
+        || receipt.revision !== next.revision
+        || receipt.snapshotHash !== next.latestSnapshotHash
+        || receipt.status !== next.status
+        || Date.parse(next.deadlineAt) <= Date.parse(next.startedAt))
+        throw new Error('YOLOOP_RUN_TRANSITION_INVALID');
+    validateSnapshotHash(before);
+    validateSnapshotHash(after);
+    validateEventHash(event, currentEvents.at(-1)?.eventHash ?? null);
+}
+function validateSnapshotHash(snapshot) {
+    const { snapshotHash, ...hashed } = snapshot;
+    if (snapshotHash !== domainHash('p220-yoloop-progress-snapshot-v1', hashed)) {
+        throw new Error('YOLOOP_RUN_SNAPSHOT_CONFLICT');
+    }
+}
+function validateEventHash(event, expectedParent) {
+    const { eventHash, ...hashed } = event;
+    if (event.parentEventHash !== expectedParent
+        || eventHash !== domainHash('p220-yoloop-run-event-v1', hashed))
+        throw new Error('YOLOOP_RUN_SNAPSHOT_CONFLICT');
+}
+function buildPublicLeaseId(sessionId, nowIso) {
+    return `lease-${publicStableHash(`${sessionId}:${nowIso}`)}`;
+}
+function publicStableHash(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36).padStart(7, '0');
+}
+function classifyClientLease(lock, nowIso) {
+    const expiresAt = lock.leaseExpiresAt ?? lock.ttlExpiresAt;
+    const expiresMs = Date.parse(expiresAt);
+    const nowMs = Date.parse(nowIso);
+    if (!Number.isFinite(expiresMs) || !Number.isFinite(nowMs))
+        return 'unknown';
+    return expiresMs <= nowMs ? 'expired' : 'active';
+}
+// ── Pure merge helper (used by readState) ───────────────────────────────
+function mergeCountersWithDefaults(parsed, nowIso) {
+    const defaults = createDefaultCounters(nowIso);
+    return {
+        // Preserve additive/unknown fields byte-semantically across read/write cycles.
+        ...parsed,
+        version: parsed.version === '1.2' ? '1.2' : '1.1',
+        lastResetAt: parsed.lastResetAt ?? defaults.lastResetAt,
+        storiesRunToday: parsed.storiesRunToday ?? 0,
+        iterationsToday: parsed.iterationsToday ?? 0,
+        iterationsTodayDate: parsed.iterationsTodayDate ?? defaults.iterationsTodayDate,
+        tokensUsedToday: parsed.tokensUsedToday ?? 0,
+        lastRunAt: parsed.lastRunAt ?? null,
+        coolDownUntil: parsed.coolDownUntil ?? null,
+        totalRunsAllTime: parsed.totalRunsAllTime ?? 0,
+        totalStoriesAllTime: parsed.totalStoriesAllTime ?? 0,
+        currentSession: parsed.currentSession ?? null,
+        ...(parsed.runControl !== undefined ? { runControl: parsed.runControl } : {}),
+        ...(parsed.continuationPolicy !== undefined ? { continuationPolicy: parsed.continuationPolicy } : {}),
+        ...(parsed.continuationSession !== undefined ? { continuationSession: parsed.continuationSession } : {}),
+        ...(parsed.pendingContinuationAuthorities !== undefined ? { pendingContinuationAuthorities: parsed.pendingContinuationAuthorities } : {}),
+        ...(parsed.continuationReceipts !== undefined ? { continuationReceipts: parsed.continuationReceipts } : {}),
+        ...(parsed.continuationRecoveryReceipts !== undefined ? { continuationRecoveryReceipts: parsed.continuationRecoveryReceipts } : {}),
+        ...(parsed.continuationReplanReceipts !== undefined ? { continuationReplanReceipts: parsed.continuationReplanReceipts } : {}),
+        // P104.06: preserve recovery_history (defensive default to [])
+        recovery_history: Array.isArray(parsed.recovery_history)
+            ? capRecoveryHistory(parsed.recovery_history)
+            : [],
+    };
+}
+// ── P104.06: pure FIFO cap helper (exported for tests) ─────────────────────
+/**
+ * Enforce FIFO bound on `recovery_history[]`. Returns a new array of length
+ * <= `RECOVERY_HISTORY_CAP`, preserving the most recent entries (drops from
+ * head). Pure: input is not mutated.
+ */
+export function capRecoveryHistory(history) {
+    if (history.length <= RECOVERY_HISTORY_CAP)
+        return history;
+    return history.slice(history.length - RECOVERY_HISTORY_CAP);
+}