@ornexus/neocortex 4.60.73 → 4.60.74

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

@@ -1,1920 +1 @@
-/**
- * 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);
-}
+import{promises as O}from"node:fs";import{existsSync as z}from"node:fs";import{createHash as X}from"node:crypto";import{join as S,dirname as W}from"node:path";import{hostname as w}from"node:os";import{setSecureFilePermissions as G,setSecureDirPermissions as Z}from"../config/secure-config.js";import{RECOVERY_HISTORY_CAP as A}from"./shared-yoloop-types.js";import{applyCrossEpicContinuationReconciliation as P,epicOperationalCanonicalJson as x,epicOperationalHash as f,mutateEpicOperationalState as Q,readEpicOperationalState as k}from"../git/epic-operational-state.js";const ee=".neocortex",Y="yoloop-state.json",te="yoloop.lock",ne="yoloop-state.mutation.lock",H="yoloop-session-rollover.json",U="yoloop-successor-transition.json",D=360*60*1e3,se=3e4,oe=200,F=Object.freeze(["rollover-session-v1","successor-transition-v1","continuation-replan-v1"]),re={warn:()=>{},info:()=>{},error:()=>{}};function R(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 ge(t){return{lock:null,state:R(t),capabilities:F}}class Ae{projectRoot;stateDir;statePath;lockPath;mutationLockPath;rolloverManifestPath;successorTransitionManifestPath;logger;constructor(e,n=re){this.projectRoot=e,this.stateDir=S(e,ee),this.statePath=S(this.stateDir,Y),this.lockPath=S(this.stateDir,te),this.mutationLockPath=S(this.stateDir,ne),this.rolloverManifestPath=S(this.stateDir,H),this.successorTransitionManifestPath=S(this.stateDir,U),this.logger=n}async readAll(e){const n=e??new Date().toISOString(),s=this.readCommonAuthorityIfPresent();if(s)return{lock:s.yoloop.lock,state:s.yoloop.state,capabilities:s.yoloop.capabilities};await this.cleanupOrphanTempFiles(),await this.recoverSessionRolloverIfPresent(n),await this.recoverSuccessorTransitionIfPresent(n);const[o,r]=await Promise.all([this.readLock(),this.readState(n)]);return{lock:await this.prepareLockForSnapshot(o,n),state:r,capabilities:F}}async applyUpdate(e,n){const s=n??new Date().toISOString();if(this.readCommonAuthorityIfPresent()){for(const o of e.operations)await this.applyCommonOperation(o,s);return}await this.ensureDir(),await this.recoverSessionRolloverIfPresent(s),await this.recoverSuccessorTransitionIfPresent(s);for(const o of e.operations)await this.applyOperation(o,s)}async requestRunTransition(e,n){const s=n??new Date().toISOString();return await this.ensureDir(),this.withMutationLock(()=>this.transitionRun(e,s))}async requestLifecycleAction(e,n={},s){const o=s??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=n.operationId??`op-${e}-${a}`,d=n.idempotencyKey??`idem-${e}-${a}`,h=c.receipts.find(p=>p.operationId===i||p.idempotencyKey===d);if(h){if(h.operationId===i&&h.idempotencyKey===d)return h;throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}const u=_e(c.status,e);if(!u)throw new Error(N.has(c.status)?"YOLOOP_RUN_TERMINAL":"YOLOOP_RUN_TRANSITION_INVALID");return this.transitionRun(Ie({current:c,action:e,target:u,operationId:i,idempotencyKey:d,occurredAt:o}),o)})}async applyOperation(e,n){switch(e.type){case"acquire_lock":await this.withMutationLock(()=>this.acquireLock(e.lock,n));return;case"release_lock":await this.withMutationLock(()=>this.releaseLock(e));return;case"write_state":await this.withMutationLock(async()=>{const s=await this.readState(n),{runControl:o,...r}=e.state;await this.writeState({...r,...s.runControl?{version:"1.2",runControl:s.runControl}:{}})});return;case"advance_epic":await this.advanceEpic(e.nextEpicIndex,e.nextEpicId,n);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,n);return;case"acknowledge_continuation_authority":await this.acknowledgeContinuationAuthority(e.idempotencyKey,e.receipt,n);return;case"repair_continuation_authority":await this.repairContinuationAuthority(e.beforeHash,e.authority,e.receipt,n);return;case"switch_continuation_policy":await this.switchContinuationPolicy(e.policy,e.session,n);return;case"transition_run":await this.requestRunTransition(e,n);return;case"start_successor_run":await this.withMutationLock(()=>this.startSuccessorRun(e,n));return;case"commit_successor_transition":await this.withMutationLock(()=>this.commitSuccessorTransition(e,n));return;case"rollover_session":await this.withMutationLock(()=>this.rolloverSession(e,n));return;case"replan_continuation_session":await this.withMutationLock(()=>this.replanContinuationSession(e,n));return;case"reconcile_cross_epic_continuation":await P(this.projectRoot,e);return;case"recovery_attempted":await this.appendRecoveryAttempt(e.attempt,n);return;case"recovery_resolved":await this.resolveRecoveryAttempt(e.attempt_id,e.outcome,n);return;default:{const s=e;throw this.logger.error({event:"yoloop_unknown_op",op:s},"unknown yoloop operation rejected"),new Error("YOLOOP_STATE_OPERATION_UNSUPPORTED")}}}readCommonAuthorityIfPresent(){try{const e=k(this.projectRoot).operational;if(e.activeJournal!==null)throw new Error("epic-operational-recovery-required");return e}catch(e){if(e instanceof Error&&["git-lifecycle-runtime-missing","epic-operational-store-missing"].includes(e.message)||e instanceof Error&&e.message==="git-lifecycle-common-dir-invalid"&&!z(S(this.projectRoot,".git")))return null;throw e}}async applyCommonOperation(e,n){if(e.type==="no_op")return;if(e.type==="reconcile_cross_epic_continuation"){await P(this.projectRoot,e);return}const{document:s,operational:o}=k(this.projectRoot),r=Object.keys(o.identities);if(r.length!==1)throw new Error("epic-operational-identity-mismatch");const c=r[0];await Q(this.projectRoot,{identityHash:c,expectedRevision:s.revision,expectedWriterEpoch:o.writerEpoch},a=>{const i=a.yoloop.state;let d=a.yoloop.lock,h=i;switch(e.type){case"acquire_lock":{if(d&&d.sessionId!==e.lock.sessionId)throw new Error("YOLOOP_LOCK_HELD");d={...e.lock,pid:process.pid,hostname:w(),ownerKind:"client",leaseId:e.lock.leaseId??j(e.lock.sessionId,n),leaseState:"active",leaseAcquiredAt:e.lock.leaseAcquiredAt??n,leaseDurationMs:e.lock.leaseDurationMs??D,leaseExpiresAt:e.lock.leaseExpiresAt??e.lock.ttlExpiresAt};break}case"release_lock":{if(e.expectedSessionId&&d?.sessionId!==e.expectedSessionId)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT");if(e.expectedLeaseId&&d?.leaseId!==e.expectedLeaseId)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT");if(e.expectedRunId&&i.runControl?.runId!==e.expectedRunId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");d=null;break}case"write_state":{const{runControl:u,...p}=e.state;h={...p,...i.runControl?{version:"1.2",runControl:i.runControl}:{}};break}case"advance_epic":{if(!i.currentSession)return;h={...i,currentSession:{...i.currentSession,currentEpicIndex:e.nextEpicIndex}};break}case"reserve_continuation_authority":{const u=i.pendingContinuationAuthorities??[],p=String(e.authority.idempotencyKey??""),_=u.find(I=>I.idempotencyKey===p);if(_){if(x(_)!==x(e.authority))throw new Error("YOLOOP_CONTINUATION_AUTHORITY_CONFLICT");return}if(!p||u.length>=64)throw new Error("YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED");h={...i,pendingContinuationAuthorities:[...u,e.authority]};break}case"acknowledge_continuation_authority":{const u=i.pendingContinuationAuthorities??[],p=u.find(I=>I.idempotencyKey===e.idempotencyKey);if(!p)throw new Error("YOLOOP_CONTINUATION_RECEIPT_ORPHAN");const _=i.continuationReceipts??[];if(_.length>=64)throw new Error("YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED");h={...i,pendingContinuationAuthorities:u.filter(I=>I!==p),continuationReceipts:[..._,e.receipt]};break}case"repair_continuation_authority":{const u=i.pendingContinuationAuthorities??[];if(u.length!==1||f("p208-legacy-authority-before-v1",u[0])!==e.beforeHash)throw new Error("YOLOOP_CONTINUATION_RECOVERY_BEFORE_MISMATCH");const p=i.continuationRecoveryReceipts??[];if(p.length>=64)throw new Error("YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED");h={...i,pendingContinuationAuthorities:[e.authority],continuationRecoveryReceipts:[...p,e.receipt]};break}case"switch_continuation_policy":{if(i.currentSession||(i.pendingContinuationAuthorities?.length??0)>0)throw new Error("YOLOOP_POLICY_SWITCH_ACTIVE");h={...i,continuationPolicy:e.policy,continuationSession:e.session};break}case"transition_run":case"start_successor_run":{const u=i.runControl;if(!u||u.revision!==e.expectedRevision||u.latestSnapshotHash!==e.expectedSnapshotHash)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");h={...i,version:"1.2",runControl:e.next};break}case"commit_successor_transition":h={...e.state,version:"1.2",runControl:e.successor.next};break;case"rollover_session":h=e.next,d=null;break;case"replan_continuation_session":{const u=i.pendingContinuationAuthorities??[];if(f("p222-yoloop-replan-session-v1",i.continuationSession??null)!==e.expectedSessionHash||f("p222-yoloop-replan-pending-v1",u)!==e.expectedPendingHash||u.length>1||u.some(_=>_.delegated!==!1))throw new Error("YOLOOP_CONTINUATION_REPLAN_AUTHORITY_CONFLICT");const p=i.continuationReplanReceipts??[];if(p.length>=64)throw new Error("YOLOOP_CONTINUATION_RECEIPT_CAPACITY_EXCEEDED");h={...i,continuationSession:e.nextSession,pendingContinuationAuthorities:[],continuationReplanReceipts:[...p,e.receipt]};break}case"recovery_attempted":h={...i,recovery_history:m([...i.recovery_history??[],e.attempt])};break;case"recovery_resolved":{const u=[...i.recovery_history??[]],p=u.findIndex(_=>_.recovery_step_id_tokenized===e.attempt_id);p>=0&&(u[p]={...u[p],outcome:e.outcome,finished_at:n}),h={...i,recovery_history:u};break}default:{const u=e;throw new Error(`YOLOOP_STATE_OPERATION_UNSUPPORTED:${String(u)}`)}}a.yoloop={...a.yoloop,lock:d,state:h}})}async reserveContinuationAuthority(e,n){const s=await this.readState(n),o=s.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(l(c)===l(e))return;throw new Error("YOLOOP_CONTINUATION_AUTHORITY_CONFLICT")}if(o.length>=64)throw new Error("YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED");await this.writeState({...s,pendingContinuationAuthorities:[...o,e]})}async acknowledgeContinuationAuthority(e,n,s){const o=await this.readState(s),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(n.idempotencyKey!==e||n.sessionId!==a.sessionId||JSON.stringify(n.storyIds)!==JSON.stringify(a.storyIds))throw new Error("YOLOOP_CONTINUATION_RECEIPT_MISMATCH");const i=r.filter((h,u)=>u!==c),d=o.continuationReceipts??[];await this.writeState({...o,pendingContinuationAuthorities:i,continuationReceipts:[...d.slice(-63),n]})}async repairContinuationAuthority(e,n,s,o){const r=await this.readState(o),c=r.pendingContinuationAuthorities??[],a=r.continuationRecoveryReceipts??[],i=typeof s.idempotencyKey=="string"?s.idempotencyKey:"",d=a.find(p=>p.idempotencyKey===i);if(d){if(l(d)===l(s))return;throw new Error("YOLOOP_CONTINUATION_RECOVERY_RECEIPT_CONFLICT")}if(c.length!==1||y("p208-legacy-authority-before-v1",c[0])!==e)throw new Error("YOLOOP_CONTINUATION_RECOVERY_BEFORE_MISMATCH");const h=y("p208-legacy-authority-after-v1",n);if(s.beforeHash!==e||s.afterHash!==h)throw new Error("YOLOOP_CONTINUATION_RECOVERY_HASH_MISMATCH");const u={...s};if(delete u.idempotencyKey,!i||y("p208-legacy-authority-recovery-receipt-v1",u)!==i)throw new Error("YOLOOP_CONTINUATION_RECOVERY_RECEIPT_INVALID");await this.writeState({...r,pendingContinuationAuthorities:[n],continuationRecoveryReceipts:[...a.slice(-63),s]})}async switchContinuationPolicy(e,n,s){const o=await this.readState(s);if(o.currentSession||(o.pendingContinuationAuthorities?.length??0)>0)throw new Error("YOLOOP_POLICY_SWITCH_ACTIVE");try{await O.copyFile(this.statePath,`${this.statePath}.policy-backup`)}catch(r){if(r.code!=="ENOENT")throw r}await this.writeState({...o,continuationPolicy:e,continuationSession:n})}async replanContinuationSession(e,n){const{type:s,payloadHash:o,receipt:r,...c}=e;if(ie(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:y("p222-yoloop-replan-session-v1",e.nextSession),retiredAuthorityHash:e.expectedPendingHash,retiredAuthorityCount:e.expectedPendingHash===y("p222-yoloop-replan-pending-v1",[])?0:1,payloadHash:e.payloadHash,outcome:"graph-replanned",publicSafe:!0};if(l(e.receipt)!==l(a))throw new Error("YOLOOP_CONTINUATION_REPLAN_RECEIPT_INVALID");const i=await this.readState(n);if(await this.readLock()||i.currentSession!==null)throw new Error("YOLOOP_CONTINUATION_REPLAN_ACTIVE");const d=i.runControl;if(!d||d.runId!==e.expectedRunId||!["success","exhausted"].includes(d.status)||d.revision!==e.expectedRevision||d.latestSnapshotHash!==e.expectedSnapshotHash||i.continuationPolicy!=="p205-finite-resume-v2")throw new Error("YOLOOP_CONTINUATION_REPLAN_RUN_CONFLICT");const h=i.continuationReplanReceipts??[],u=h.find(I=>I.idempotencyKey===e.idempotencyKey||I.operationId===e.operationId);if(u){if(l(u)===l(a)&&l(i.continuationSession)===l(e.nextSession)&&(i.pendingContinuationAuthorities?.length??0)===0)return;throw new Error("YOLOOP_CONTINUATION_REPLAN_REPLAY_CONFLICT")}const p=i.continuationSession,_=i.pendingContinuationAuthorities??[];if(!K(p)||y("p222-yoloop-replan-session-v1",p)!==e.expectedSessionHash||y("p222-yoloop-replan-pending-v1",_)!==e.expectedPendingHash||_.length>1||_.some(I=>I.delegated!==!1||I.sessionId!==p.sessionId||!I.certificate||I.certificate.sessionId!==p.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,n){const s=await this.readState(n),o=s.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={...s,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,n,s){const o=await this.readState(s),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===n&&a.finished_at){this.logger.info({event:"recovery_resolved_duplicate",attempt_id:e,outcome:n},"duplicate recovery_resolved op; skipping");return}const i=r.slice();i[c]={...a,outcome:n,finished_at:s};const d={...o,recovery_history:i};await this.writeState(d),this.logger.info({event:"recovery_resolved_persisted",attempt_id:e,outcome:n},"recovery attempt resolved")}async acquireLock(e,n){const s={...e,pid:process.pid,hostname:w(),ownerKind:"client",startedAt:e.startedAt||n,leaseId:e.leaseId??j(e.sessionId,n),leaseState:"active",leaseAcquiredAt:e.leaseAcquiredAt??n,leaseDurationMs:e.leaseDurationMs??D,leaseExpiresAt:e.leaseExpiresAt??e.ttlExpiresAt},o=JSON.stringify(s,null,2);try{const r=await O.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:s.pid,sessionId:s.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,s)){this.logger.info({event:"yoloop_lock_acquire_duplicate",sessionId:s.sessionId},"duplicate acquire_lock for current yoloop session; treating as no-op");return}if(!await this.maybeRecoverOrphanLock(n))throw this.logger.warn({event:"yoloop_lock_held"},"yoloop lock held by another live process"),r;const d=await O.open(this.lockPath,"wx");try{await d.writeFile(o,"utf8")}finally{await d.close()}this.trySetFilePerms(this.lockPath),this.logger.info({event:"yoloop_lock_acquired_after_recovery",pid:s.pid},"yoloop lock acquired after orphan recovery")}}async releaseLock(e){const n=await this.readState(new Date().toISOString()),s=await this.readLock();if(n.runControl){if(!e.expectedRunId||!e.expectedSessionId||!e.expectedLeaseId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if(e.expectedRunId!==n.runControl.runId)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");if(!s||e.expectedSessionId!==s.sessionId||e.expectedLeaseId!==s.leaseId)throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}try{await O.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 O.readFile(this.lockPath,"utf8"),n=JSON.parse(e),s=n.currentEpicId??n.epicId??"";return{pid:n.pid??0,hostname:n.hostname??"",...n.ownerKind?{ownerKind:n.ownerKind}:{},...n.ownerPidState?{ownerPidState:n.ownerPidState}:{},...typeof n.leaseId=="string"?{leaseId:n.leaseId}:{},...n.leaseState?{leaseState:n.leaseState}:{},...typeof n.leaseAcquiredAt=="string"?{leaseAcquiredAt:n.leaseAcquiredAt}:{},...typeof n.leaseDurationMs=="number"?{leaseDurationMs:n.leaseDurationMs}:{},...typeof n.leaseExpiresAt=="string"?{leaseExpiresAt:n.leaseExpiresAt}:{},startedAt:n.startedAt??"",sessionId:n.sessionId??"",mode:n.mode??"epic-id",inputPath:n.inputPath??"",epicQueue:n.epicQueue??(s?[s]:[]),currentEpicIndex:n.currentEpicIndex??0,currentEpicId:s,ttlExpiresAt:n.ttlExpiresAt??"",epicId:n.epicId??s}}catch{return null}}async readState(e){try{const n=await O.readFile(this.statePath,"utf8"),s=JSON.parse(n);return fe(s,e)}catch(n){const s=n;return s.code!=="ENOENT"&&this.logger.warn({event:"yoloop_state_read_error",err:s.message},"yoloop state file unreadable; using defaults"),R(e)}}async writeState(e){const n=`${this.statePath}.tmp.${process.pid}.${Date.now()}`,s=JSON.stringify(e,null,2);try{const o=await O.open(n,"w",384);try{await o.writeFile(s,"utf8"),await o.sync()}finally{await o.close()}this.trySetFilePerms(n),await O.rename(n,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 O.unlink(n)}catch{}throw o}}async rolloverSession(e,n){C(e);const s=await this.readRolloverManifest();if(s){if(Oe(s.operation,e)){if(s.operation.payloadHash!==e.payloadHash)throw new Error("YOLOOP_SESSION_ROLLOVER_CONFLICT");if(s.phase==="applied")return;await this.completePreparedSessionRollover(s.operation,n);return}else if(s.phase==="prepared")throw new Error("YOLOOP_SESSION_ROLLOVER_CONFLICT")}const o=await this.readState(n),r=await this.readLock();V(e,o,r),await this.writeRolloverManifest({schemaVersion:"YoloopSessionRolloverManifest/1.0",phase:"prepared",operation:e}),await this.completePreparedSessionRollover(e,n)}async completePreparedSessionRollover(e,n){const s=await this.readState(n);let o=l(s)===l(e.next);if(!o){const c=await this.readLock();V(e,s,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 O.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 O.access(this.rolloverManifestPath)}catch(n){if(n.code==="ENOENT")return;throw n}await this.ensureDir(),await this.withMutationLock(async()=>{const n=await this.readRolloverManifest();n?.phase==="prepared"&&await this.completePreparedSessionRollover(n.operation,e)})}async readRolloverManifest(){try{const e=JSON.parse(await O.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 C(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 n=`${this.rolloverManifestPath}.tmp.${process.pid}.${Date.now()}`,s=await O.open(n,"w",384);try{await s.writeFile(JSON.stringify(e,null,2),"utf8"),await s.sync()}finally{await s.close()}this.trySetFilePerms(n),await O.rename(n,this.rolloverManifestPath),await this.syncStateDirectory()}async commitSuccessorTransition(e,n){E(e);const s=await this.readSuccessorTransitionManifest();if(s){if(ue(s.operation,e)){if(s.operation.payloadHash!==e.payloadHash)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT");if(s.phase==="applied")return;await this.completePreparedSuccessorTransition(s.operation,n);return}if(s.phase==="prepared")throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT")}const o=await this.readState(n);if(T(e,o)){await this.writeSuccessorTransitionManifest({schemaVersion:"YoloopSuccessorTransitionManifest/1.0",phase:"applied",operation:e});return}M(e,o),await this.writeSuccessorTransitionManifest({schemaVersion:"YoloopSuccessorTransitionManifest/1.0",phase:"prepared",operation:e}),await this.completePreparedSuccessorTransition(e,n)}async completePreparedSuccessorTransition(e,n){let s=await this.readState(n);if(!T(e,s)){l(s.runControl)===l(e.successor.next)||(await this.startSuccessorRun(e.successor,n),s=await this.readState(n));const r=pe(e,s);await this.writeState(r),s=await this.readState(n)}if(!T(e,s))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 O.access(this.successorTransitionManifestPath)}catch(n){if(n.code==="ENOENT")return;throw n}await this.ensureDir(),await this.withMutationLock(async()=>{const n=await this.readSuccessorTransitionManifest();n?.phase==="prepared"&&await this.completePreparedSuccessorTransition(n.operation,e)})}async readSuccessorTransitionManifest(){try{const e=JSON.parse(await O.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 E(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 n=`${this.successorTransitionManifestPath}.tmp.${process.pid}.${Date.now()}`,s=await O.open(n,"w",384);try{await s.writeFile(JSON.stringify(e,null,2),"utf8"),await s.sync()}finally{await s.close()}this.trySetFilePerms(n),await O.rename(n,this.successorTransitionManifestPath),await this.syncStateDirectory()}async advanceEpic(e,n,s){const o=await this.readState(s);if(!o.currentSession){this.logger.warn({event:"yoloop_advance_no_session",nextEpicId:n},"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:n,nextIndex:e},"yoloop advanced to next epic")}async ensureDir(){try{await O.mkdir(this.stateDir,{recursive:!0}),this.trySetDirPerms(this.stateDir)}catch(e){const n=e;throw this.logger.error({event:"yoloop_mkdir_error",err:n.message,path:this.stateDir},"failed to ensure .neocortex/ directory"),e}}async syncStateDirectory(){try{const e=await O.open(this.stateDir,"r");try{await e.sync()}finally{await e.close()}}catch(e){const n=e.code;if(n!=="EINVAL"&&n!=="EISDIR"&&n!=="ENOTSUP"&&n!=="EPERM")throw e}}async withMutationLock(e){let n=null;for(let s=0;s<oe;s+=1)try{n=await O.open(this.mutationLockPath,"wx",384),await n.writeFile(JSON.stringify({pid:process.pid,acquiredAt:new Date().toISOString()})),await n.sync();break}catch(o){if(o.code!=="EEXIST")throw o;try{const r=await O.stat(this.mutationLockPath);if(Date.now()-r.mtimeMs>se){await O.unlink(this.mutationLockPath);continue}}catch{continue}await new Promise(r=>setTimeout(r,5))}if(!n)throw new Error("YOLOOP_RUN_REVISION_CONFLICT");try{return await e()}finally{await n.close().catch(()=>{}),await O.unlink(this.mutationLockPath).catch(()=>{})}}async transitionRun(e,n){v(e);const s=await this.readState(n),o=s.runControl,r=o?.receipts.find(d=>d.operationId===e.operationId||d.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({...s,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,n){b(e);const s=await this.readState(n),o=s.runControl,r={schemaVersion:"YoloopRunPredecessor/1.0",runId:e.previousRunId,revision:e.expectedRevision,snapshotHash:e.expectedSnapshotHash,successorOperationId:e.operationId,publicSafe:!0},c=o?.receipts.find(d=>d.operationId===e.operationId||d.idempotencyKey===e.idempotencyKey);if(c){if(c.operationId===e.operationId&&c.idempotencyKey===e.idempotencyKey&&e.next.receipts.at(-1)?.payloadHash===c.payloadHash&&l(o?.predecessor)===l(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||s.currentSession!==null)throw new Error("YOLOOP_RUN_SUCCESSOR_CONFLICT");const a=e.next.receipts.at(-1);if(!a||l(e.next.predecessor)!==l(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 v(i),L(void 0,i),await this.writeState({...s,version:"1.2",runControl:e.next}),a}trySetFilePerms(e){try{G(e)}catch{}}trySetDirPerms(e){try{Z(e)}catch{}}async prepareLockForSnapshot(e,n){if(!e)return null;if(e.ownerKind!=="client")return e;const s=B(e,n),o={...e,leaseState:s};if(s==="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 n=await this.readLock();if(!n)return!0;if(B(n,e)==="expired")return await this.deleteLockBestEffort(),this.logger.warn({event:"yoloop_orphan_lock_recovered",reason:"lease_expired"},"expired yoloop lock lease recovered"),!0;if(!n.pid||n.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(n.hostname&&n.hostname!==w())return this.logger.warn({event:"yoloop_lock_remote_host",ownerKind:n.ownerKind??"server",ownerPidState:"unknown"},"lock held by a remote host; honoring"),!1;try{return process.kill(n.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 O.unlink(this.lockPath)}catch{}}isSameClientSessionLock(e,n){return e.ownerKind==="client"&&e.sessionId===n.sessionId&&e.pid===process.pid&&e.hostname===w()}async cleanupOrphanTempFiles(){try{const e=W(this.statePath),n=await O.readdir(e),s=[`${Y}.tmp.`,`${H}.tmp.`,`${U}.tmp.`],o=n.filter(r=>s.some(c=>r.startsWith(c)));for(const r of o)try{await O.unlink(S(e,r))}catch{}}catch{}}}function l(t){return t===null||typeof t!="object"?JSON.stringify(t):Array.isArray(t)?`[${t.map(l).join(",")}]`:`{${Object.entries(t).filter(([,e])=>e!==void 0).sort(([e],[n])=>e.localeCompare(n)).map(([e,n])=>`${JSON.stringify(e)}:${l(n)}`).join(",")}}`}function y(t,e){return X("sha256").update(`${t}\0${l(e)}`).digest("hex")}function ie(t){return y("p222-yoloop-continuation-replan-v1",t)}function K(t){if(!t||typeof t!="object"||Array.isArray(t))return!1;const{sessionId:e,...n}=t;return typeof e=="string"&&/^[a-f0-9]{64}$/.test(e)&&e===y("p205-yoloop-session-v1",n)}function ae(t){return y("p9390812898200217364-yoloop-session-v1",t)}function ce(t){return y("p9390812898200217364-yoloop-rollover-v1",t)}function de(t){return y("p9390812898200217364-yoloop-successor-run-v1",t)}function le(t){return y("p9046281030721413419-yoloop-successor-transition-v1",t)}function ue(t,e){return t.operationId===e.operationId&&t.idempotencyKey===e.idempotencyKey}function E(t){const e=/^[A-Za-z0-9._:-]{1,128}$/;b(t.successor);const n={operationId:t.operationId,idempotencyKey:t.idempotencyKey,successor:t.successor,state:t.state,...t.acknowledgement?{acknowledgement:t.acknowledgement}:{},...t.reservation?{reservation:t.reservation}:{}},s=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!==le(n)||Buffer.byteLength(l(n),"utf8")>1048576||t.acknowledgement!==void 0&&(t.acknowledgement.type!=="acknowledge_continuation_authority"||typeof s!="string"||!e.test(s)||o!==s)||t.reservation!==void 0&&(t.reservation.type!=="reserve_continuation_authority"||typeof r!="string"||!e.test(r))||s!==void 0&&r===s)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_CONFLICT")}function M(t,e){if(E(t),!(l(e.runControl)===l(t.successor.next))){const s=e.runControl;if(!s||s.runId!==t.successor.previousRunId||!["exhausted","success"].includes(s.status)||s.revision!==t.successor.expectedRevision||s.latestSnapshotHash!==t.successor.expectedSnapshotHash||e.currentSession!==null)throw new Error("YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT")}he(t,e)}function he(t,e){const n=e.pendingContinuationAuthorities??[],s=e.continuationReceipts??[],o=t.acknowledgement;if(o){const d=n.find(p=>p.idempotencyKey===o.idempotencyKey);if(!d||o.receipt.sessionId!==d.sessionId||l(o.receipt.storyIds)!==l(d.storyIds))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT");const h=n.filter(p=>p.idempotencyKey!==o.idempotencyKey),u=[...s.slice(-63),o.receipt];if(l(t.state.pendingContinuationAuthorities??[])!==l(h)||l(t.state.continuationReceipts??[])!==l(u))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT")}else if(l(t.state.pendingContinuationAuthorities??[])!==l(n)||l(t.state.continuationReceipts??[])!==l(s))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(d=>d.idempotencyKey===c);if(i&&l(i)!==l(r))throw new Error("YOLOOP_SUCCESSOR_TRANSITION_AUTHORITY_CONFLICT");if(!i&&a.length>=64)throw new Error("YOLOOP_PENDING_AUTHORITY_CAPACITY_EXCEEDED")}function pe(t,e){M(t,e);const n=t.reservation?.authority,s=[...t.state.pendingContinuationAuthorities??[]];return n&&!s.some(o=>o.idempotencyKey===n.idempotencyKey)&&s.push(n),{...t.state,version:"1.2",runControl:t.successor.next,...n||t.state.pendingContinuationAuthorities!==void 0?{pendingContinuationAuthorities:s}:{}}}function T(t,e){const n=t.reservation?.authority,s=[...t.state.pendingContinuationAuthorities??[]];n&&!s.some(r=>r.idempotencyKey===n.idempotencyKey)&&s.push(n);const o={...t.state,version:"1.2",runControl:t.successor.next,...n||t.state.pendingContinuationAuthorities!==void 0?{pendingContinuationAuthorities:s}:{}};return l(e)===l(o)}function Oe(t,e){return t.operationId===e.operationId&&t.idempotencyKey===e.idempotencyKey}function C(t){const e=/^[A-Za-z0-9._:-]{1,128}$/,n={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!==ce(n)||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 b(t){const e=/^[A-Za-z0-9._:-]{1,128}$/,n={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!==de(n))throw new Error("YOLOOP_RUN_SUCCESSOR_CONFLICT")}function V(t,e,n){C(t);const s=e.currentSession;if(!s||ae(s)!==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(n)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT")}else if(!n||n.sessionId!==t.expectedSessionId||n.leaseId!==t.expectedLeaseId)throw new Error("YOLOOP_SESSION_ROLLOVER_LOCK_CONFLICT");const r=t.exhaustedRun;if(o)if(o.status==="exhausted"){if(l(r)!==l(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};v(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(l(c)!==l(t.next))throw new Error("YOLOOP_SESSION_ROLLOVER_STATE_CONFLICT")}function $(t){const{receipts:e,...n}=t.next;return y("p220-yoloop-run-transition-payload-v1",{runId:t.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.expectedRevision,expectedSnapshotHash:t.expectedSnapshotHash,next:n})}const N=new Set(["success","partial","blocked","failure","exhausted","cancelled"]),ye={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 _e(t,e){return e==="pause"?t==="running"?"pausing":null:e==="resume"?t==="paused"?"resuming":null:N.has(t)||t==="cancelling"?null:"cancelling"}function Ie(t){const e=t.current.revision+1,n=t.action==="cancel"?["YOLOOP_RUN_CANCEL_REQUESTED"]:[],s={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:s,reasonCodes:n,publicSafe:!0},r=y("p220-yoloop-progress-snapshot-id-v1",{runId:o.runId,operationId:o.operationId,sequence:o.sequence,phase:o.phase}),c={...o,snapshotId:r,snapshotHash:y("p220-yoloop-progress-snapshot-v1",{...o,snapshotId:r})},a={...o,sequence:c.sequence+1,phase:"after",status:t.target,parentSnapshotHash:c.snapshotHash},i=y("p220-yoloop-progress-snapshot-id-v1",{runId:a.runId,operationId:a.operationId,sequence:a.sequence,phase:a.phase}),d={...a,snapshotId:i,snapshotHash:y("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:n,budgetDimension:null,parentEventHash:t.current.events.at(-1)?.eventHash??null,publicSafe:!0},u=y("p220-yoloop-run-event-id-v1",{runId:h.runId,operationId:h.operationId,sequence:h.sequence}),p={...h,eventId:u,eventHash:y("p220-yoloop-run-event-v1",{...h,eventId:u})},_={...t.current,revision:e,status:t.target,events:[...t.current.events,p],progressSnapshots:[...t.current.progressSnapshots,c,d],latestSnapshotHash:d.snapshotHash,receipts:[...t.current.receipts]},I={runId:t.current.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,expectedRevision:t.current.revision,expectedSnapshotHash:t.current.latestSnapshotHash,next:_},g=$(I),J={schemaVersion:"YoloopRunTransitionReceipt/1.0",runId:t.current.runId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,payloadHash:g,revision:e,snapshotHash:d.snapshotHash,status:t.target};return{type:"transition_run",...I,payloadHash:g,next:{..._,receipts:[..._.receipts,J]}}}function v(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!==$(t))throw new Error("YOLOOP_RUN_OPERATION_CONFLICT")}function L(t,e){const n=e.next,s=t?.events??[],o=t?.progressSnapshots??[],r=t?.receipts??[];if(n.schemaVersion!=="YoloopRunControl/1.0"||n.runId!==e.runId||n.revision!==e.expectedRevision+1||n.events.length!==s.length+1||n.progressSnapshots.length!==o.length+2||n.receipts.length!==r.length+1||l(n.events.slice(0,s.length))!==l(s)||l(n.progressSnapshots.slice(0,o.length))!==l(o)||l(n.receipts.slice(0,r.length))!==l(r))throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(t){if(N.has(t.status))throw new Error("YOLOOP_RUN_TERMINAL");const h=n.progressSnapshots.at(-2)?.boundary,u=t.status===n.status&&(h==="budget"||h==="retry");if(!(ye[t.status]??[]).includes(n.status)&&!u)throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(t.startedAt!==n.startedAt||t.deadlineAt!==n.deadlineAt)throw new Error("YOLOOP_RUN_TRANSITION_INVALID");if(l(t.predecessor)!==l(n.predecessor))throw new Error("YOLOOP_RUN_TRANSITION_INVALID")}else if(n.status!=="created")throw new Error("YOLOOP_RUN_TRANSITION_INVALID");const c=n.progressSnapshots.at(-2),a=n.progressSnapshots.at(-1),i=n.events.at(-1),d=n.receipts.at(-1);if(!c||!a||!i||!d||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!==n.revision||a.revision!==n.revision||i.revision!==n.revision||c.parentSnapshotHash!==(t?.latestSnapshotHash??null)||a.parentSnapshotHash!==c.snapshotHash||n.latestSnapshotHash!==a.snapshotHash||d.schemaVersion!=="YoloopRunTransitionReceipt/1.0"||d.runId!==e.runId||d.operationId!==e.operationId||d.idempotencyKey!==e.idempotencyKey||d.payloadHash!==e.payloadHash||d.revision!==n.revision||d.snapshotHash!==n.latestSnapshotHash||d.status!==n.status||Date.parse(n.deadlineAt)<=Date.parse(n.startedAt))throw new Error("YOLOOP_RUN_TRANSITION_INVALID");q(c),q(a),Se(i,s.at(-1)?.eventHash??null)}function q(t){const{snapshotHash:e,...n}=t;if(e!==y("p220-yoloop-progress-snapshot-v1",n))throw new Error("YOLOOP_RUN_SNAPSHOT_CONFLICT")}function Se(t,e){const{eventHash:n,...s}=t;if(t.parentEventHash!==e||n!==y("p220-yoloop-run-event-v1",s))throw new Error("YOLOOP_RUN_SNAPSHOT_CONFLICT")}function j(t,e){return`lease-${we(`${t}:${e}`)}`}function we(t){let e=2166136261;for(let n=0;n<t.length;n+=1)e^=t.charCodeAt(n),e=Math.imul(e,16777619)>>>0;return e.toString(36).padStart(7,"0")}function B(t,e){const n=t.leaseExpiresAt??t.ttlExpiresAt,s=Date.parse(n),o=Date.parse(e);return!Number.isFinite(s)||!Number.isFinite(o)?"unknown":s<=o?"expired":"active"}function fe(t,e){const n=R(e);return{...t,version:t.version==="1.2"?"1.2":"1.1",lastResetAt:t.lastResetAt??n.lastResetAt,storiesRunToday:t.storiesRunToday??0,iterationsToday:t.iterationsToday??0,iterationsTodayDate:t.iterationsTodayDate??n.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<=A?t:t.slice(t.length-A)}export{F as YOLOOP_PERSISTENCE_CAPABILITIES,Ae as YoloopClientStateStore,ie as buildYoloopContinuationReplanPayloadHash,$ as buildYoloopRunTransitionPayloadHash,ce as buildYoloopSessionRolloverPayloadHash,de as buildYoloopSuccessorRunPayloadHash,le as buildYoloopSuccessorTransitionPayloadHash,m as capRecoveryHistory,R as createDefaultCounters,ge as createDefaultState,ae as fingerprintYoloopSession};