@orion-agents/orion-code 0.1.8 → 0.1.9

package/dist/services/session-storage.js

@@ -10,6 +10,8 @@ exports.SESSION_SIDECAR_SUFFIXES = exports.redactTraceText = void 0;
 exports.resolveProjectPath = resolveProjectPath;
 exports.getProjectKey = getProjectKey;
 exports.isSessionMetaFile = isSessionMetaFile;
+exports.prepareSessionCompactSourceReceipt = prepareSessionCompactSourceReceipt;
+exports.advanceSessionCompactSourceReceipt = advanceSessionCompactSourceReceipt;
 exports.createSession = createSession;
 exports.saveSessionMeta = saveSessionMeta;
 exports.updateSessionEffort = updateSessionEffort;
@@ -60,11 +62,55 @@ const tool_call_groups_1 = require("./compact/tool-call-groups");
 const redaction_1 = require("./redaction");
 const debug_log_1 = require("../utils/debug-log");
 const goal_storage_1 = require("./goal-storage");
+const fingerprint_1 = require("./compact/fingerprint");
+const token_estimate_1 = require("../utils/token-estimate");
 const harness_1 = require("../harness");
 var redaction_2 = require("./redaction");
 Object.defineProperty(exports, "redactTraceText", { enumerable: true, get: function () { return redaction_2.redactTraceText; } });
 function sanitizeTraceEvent(event) {
     const sanitized = { ...event };
+    if (sanitized.stopDecision) {
+        sanitized.stopDecision = {
+            ...sanitized.stopDecision,
+            reason: {
+                ...sanitized.stopDecision.reason,
+                message: (0, redaction_1.redactTraceText)(sanitized.stopDecision.reason.message),
+            },
+            evidence: sanitized.stopDecision.evidence.map(item => ({
+                ...item,
+                source: (0, redaction_1.redactTraceText)(item.source),
+                detail: (0, redaction_1.redactTraceText)(item.detail),
+            })),
+            nextActions: sanitized.stopDecision.nextActions.map(item => ({
+                ...item,
+                label: (0, redaction_1.redactTraceText)(item.label),
+                command: item.command ? (0, redaction_1.redactTraceText)(item.command) : undefined,
+            })),
+            resources: Object.fromEntries(Object.entries(sanitized.stopDecision.resources).map(([key, value]) => [
+                key,
+                value ? { ...value } : value,
+            ])),
+            criterionStates: sanitized.stopDecision.criterionStates?.map(item => ({
+                ...item,
+                id: (0, redaction_1.redactTraceText)(item.id),
+            })),
+            evidenceRefs: sanitized.stopDecision.evidenceRefs?.map(redaction_1.redactTraceText),
+            progressDelta: sanitized.stopDecision.progressDelta
+                ? {
+                    ...sanitized.stopDecision.progressDelta,
+                    criterionChanges: sanitized.stopDecision.progressDelta.criterionChanges.map(item => ({
+                        ...item,
+                        id: (0, redaction_1.redactTraceText)(item.id),
+                    })),
+                    newEvidenceRefs: sanitized.stopDecision.progressDelta.newEvidenceRefs.map(redaction_1.redactTraceText),
+                    newChangedFiles: sanitized.stopDecision.progressDelta.newChangedFiles.map(redaction_1.redactTraceText),
+                    newDecisions: sanitized.stopDecision.progressDelta.newDecisions.map(redaction_1.redactTraceText),
+                    newBlockers: sanitized.stopDecision.progressDelta.newBlockers.map(redaction_1.redactTraceText),
+                    newDiagnostics: sanitized.stopDecision.progressDelta.newDiagnostics.map(redaction_1.redactTraceText),
+                }
+                : undefined,
+        };
+    }
     for (const key of [
         'argsSummary',
         'error',
@@ -94,6 +140,14 @@ function sanitizeTraceEvent(event) {
     if (sanitized.promptOmittedEvidence) {
         sanitized.promptOmittedEvidence = sanitized.promptOmittedEvidence.map(redaction_1.redactTraceText);
     }
+    if (sanitized.promptSectionManifest) {
+        sanitized.promptSectionManifest = sanitized.promptSectionManifest.map(item => ({
+            ...item,
+            name: (0, redaction_1.redactTraceText)(item.name),
+            source: (0, redaction_1.redactTraceText)(item.source),
+            reason: item.reason ? (0, redaction_1.redactTraceText)(item.reason) : undefined,
+        }));
+    }
     if (sanitized.workspaceChangedByTurn) {
         sanitized.workspaceChangedByTurn = sanitized.workspaceChangedByTurn.map(redaction_1.redactTraceText);
     }
@@ -419,10 +473,277 @@ function parseHarnessSidecarFile(path) {
         return null;
     }
 }
+function canonicalizeForHash(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeForHash);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, canonicalizeForHash(entry)]));
+}
+function canonicalContentHash(value) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify(canonicalizeForHash(value)), 'utf-8')
+        .digest('hex');
+}
+function compactBindingHash(parts) {
+    return canonicalContentHash(parts);
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string' && item.length > 0);
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function validatePrepareSourceReceipt(receipt, sessionId) {
+    if (receipt.schemaVersion !== 1 ||
+        receipt.sessionId !== sessionId ||
+        !Number.isInteger(receipt.sourceMessageCount) ||
+        receipt.sourceMessageCount < 0 ||
+        !isSha256(receipt.sourcePrefixHash) ||
+        (receipt.activeCheckpointId !== null &&
+            (typeof receipt.activeCheckpointId !== 'string' || !receipt.activeCheckpointId))) {
+        throw new Error('Invalid compact prepare-source receipt');
+    }
+}
+function assertPrepareSourceMatches(receipt, session, rawMessages) {
+    validatePrepareSourceReceipt(receipt, session.id);
+    const activeCheckpointId = session.activeCompactCheckpointId ?? null;
+    if (activeCheckpointId !== receipt.activeCheckpointId) {
+        throw new Error(`Stale compact candidate: active checkpoint changed from ${receipt.activeCheckpointId ?? 'none'} to ${activeCheckpointId ?? 'none'}`);
+    }
+    if (rawMessages.length !== receipt.sourceMessageCount) {
+        throw new Error(`Stale compact candidate: source message count changed from ${receipt.sourceMessageCount} to ${rawMessages.length}`);
+    }
+    const prefixHash = canonicalContentHash(rawMessages);
+    if (prefixHash !== receipt.sourcePrefixHash) {
+        throw new Error('Stale compact candidate: source transcript hash changed during preparation');
+    }
+}
+/** Capture the append-only transcript identity before preparing a compact candidate. */
+function prepareSessionCompactSourceReceipt(sessionId) {
+    const receipt = withLockedSession(sessionId, session => {
+        const rawMessages = readSessionMessagesForSession(session);
+        return {
+            schemaVersion: 1,
+            sessionId,
+            sourceMessageCount: rawMessages.length,
+            sourcePrefixHash: canonicalContentHash(rawMessages),
+            activeCheckpointId: session.activeCompactCheckpointId ?? null,
+        };
+    });
+    if (!receipt)
+        throw new Error(`Session not found: ${sessionId}`);
+    return receipt;
+}
+/**
+ * Advance a prepare receipt only across the exact messages written by the
+ * preparing turn. Any interleaved writer fails closed instead of being claimed
+ * by a candidate that never observed its messages.
+ */
+function advanceSessionCompactSourceReceipt(receipt, appendedMessages) {
+    const advanced = withLockedSession(receipt.sessionId, session => {
+        validatePrepareSourceReceipt(receipt, session.id);
+        if ((session.activeCompactCheckpointId ?? null) !== receipt.activeCheckpointId) {
+            throw new Error('Stale compact candidate: active checkpoint changed during preparation');
+        }
+        const rawMessages = readSessionMessagesForSession(session);
+        if (rawMessages.length !== receipt.sourceMessageCount + appendedMessages.length ||
+            canonicalContentHash(rawMessages.slice(0, receipt.sourceMessageCount)) !==
+                receipt.sourcePrefixHash ||
+            canonicalContentHash(rawMessages.slice(receipt.sourceMessageCount)) !==
+                canonicalContentHash(appendedMessages)) {
+            throw new Error('Stale compact candidate: transcript tail contains concurrent or unexpected messages');
+        }
+        return {
+            ...receipt,
+            sourceMessageCount: rawMessages.length,
+            sourcePrefixHash: canonicalContentHash(rawMessages),
+        };
+    });
+    if (!advanced)
+        throw new Error(`Session not found: ${receipt.sessionId}`);
+    return advanced;
+}
+function inspectSemanticSummary(value) {
+    if (!isRecord(value) || value.version !== 1) {
+        throw new Error('Compact semantic summary schema is invalid');
+    }
+    if (!Number.isInteger(value.taskEpoch) || value.taskEpoch < 1) {
+        throw new Error('Compact semantic summary taskEpoch is invalid');
+    }
+    for (const field of [
+        'constraints',
+        'decisions',
+        'completed',
+        'pending',
+        'blockers',
+        'files',
+        'evidenceRefs',
+    ]) {
+        if (!isStringArray(value[field])) {
+            throw new Error(`Compact semantic summary ${field} must be a string array`);
+        }
+    }
+    if (!isRecord(value.coverage) || !isStringArray(value.coverage.groupIds)) {
+        throw new Error('Compact semantic summary coverage is invalid');
+    }
+    const coverageGroupIds = value.coverage.groupIds;
+    if (value.coverage.groupCount !== coverageGroupIds.length ||
+        !Number.isInteger(value.coverage.messageCount) ||
+        value.coverage.messageCount < 0) {
+        throw new Error('Compact semantic summary coverage counts are inconsistent');
+    }
+    if (!Array.isArray(value.items)) {
+        throw new Error('Compact semantic summary items must be an array');
+    }
+    const taskEpochs = [];
+    for (const item of value.items) {
+        if (!isRecord(item) ||
+            typeof item.id !== 'string' ||
+            !item.id ||
+            typeof item.groupId !== 'string' ||
+            !item.groupId ||
+            !isStringArray(item.sourceRefs) ||
+            !Number.isInteger(item.tokenEstimate) ||
+            item.tokenEstimate < 0 ||
+            !Number.isInteger(item.taskEpoch) ||
+            item.taskEpoch < 1 ||
+            typeof item.text !== 'string') {
+            throw new Error('Compact semantic summary contains an invalid ContextItem');
+        }
+        taskEpochs.push(item.taskEpoch);
+    }
+    const criterionStatesValue = value.criterionStates;
+    if (criterionStatesValue !== undefined && !Array.isArray(criterionStatesValue)) {
+        throw new Error('Compact semantic criterionStates must be an array');
+    }
+    const criterionStates = (criterionStatesValue ?? []).map(item => {
+        if (!isRecord(item) ||
+            typeof item.id !== 'string' ||
+            !item.id ||
+            typeof item.statement !== 'string' ||
+            !['pending', 'passed', 'failed', 'waived'].includes(String(item.status)) ||
+            !isStringArray(item.evidenceRefs)) {
+            throw new Error('Compact semantic summary contains an invalid criterion state');
+        }
+        return {
+            id: item.id,
+            status: String(item.status),
+            evidenceRefs: item.evidenceRefs,
+        };
+    });
+    if (new Set(criterionStates.map(item => item.id)).size !== criterionStates.length) {
+        throw new Error('Compact semantic summary contains duplicate criterion IDs');
+    }
+    return {
+        coverageGroupIds,
+        criterionStates,
+        taskEpoch: value.taskEpoch,
+        taskEpochs,
+    };
+}
+function semanticValidationReceipt(semanticSummary, candidate, harnessState) {
+    const view = inspectSemanticSummary(semanticSummary);
+    const expectedCoverage = candidate.plan.evictedGroups.map(group => group.id);
+    if (!sameStrings(view.coverageGroupIds, expectedCoverage)) {
+        throw new Error('Compact semantic summary does not cover the prepared evicted groups');
+    }
+    const expectedTaskEpoch = Math.max(1, Math.floor(harnessState?.taskEpoch ?? harnessState?.contract?.taskEpoch ?? view.taskEpochs[0] ?? 1));
+    if (view.taskEpoch !== expectedTaskEpoch ||
+        view.taskEpochs.some(taskEpoch => taskEpoch !== expectedTaskEpoch)) {
+        throw new Error('Compact semantic summary taskEpoch does not match the active Harness epoch');
+    }
+    const contractCriteria = harnessState?.contract?.criteria ?? [];
+    const expectedCriteria = contractCriteria.map(criterion => ({
+        id: criterion.id,
+        status: criterion.status ?? 'pending',
+        evidenceRefs: [...criterion.evidenceRefs],
+    }));
+    if (expectedCriteria.length > 0) {
+        if (view.criterionStates.length !== expectedCriteria.length) {
+            throw new Error('Compact semantic summary omitted active task criteria');
+        }
+        for (const [index, expected] of expectedCriteria.entries()) {
+            const actual = view.criterionStates[index];
+            if (actual.id !== expected.id ||
+                actual.status !== expected.status ||
+                !sameStrings(actual.evidenceRefs, expected.evidenceRefs)) {
+                throw new Error(`Compact semantic criterion mismatch: ${expected.id}`);
+            }
+        }
+    }
+    const knownEvidenceRefs = new Set([
+        ...(harnessState?.ledger.flatMap(item => [item.id, `ledger:${item.id}`]) ?? []),
+        ...(harnessState?.evidenceIndex?.flatMap(item => [item.id, `evidence:${item.id}`]) ?? []),
+        ...(harnessState?.capsule?.keyFacts.flatMap(item => [item.id, `fact:${item.id}`]) ?? []),
+    ]);
+    const validatedEvidenceRefs = [
+        ...new Set(view.criterionStates.flatMap(item => item.evidenceRefs)),
+    ];
+    if (validatedEvidenceRefs.length > 0 && !harnessState) {
+        throw new Error('Compact semantic evidence references require an authoritative Harness state');
+    }
+    for (const criterion of view.criterionStates) {
+        if (criterion.status === 'passed' && criterion.evidenceRefs.length === 0) {
+            throw new Error(`Passed compact criterion lacks evidence: ${criterion.id}`);
+        }
+        for (const evidenceRef of criterion.evidenceRefs) {
+            if (!knownEvidenceRefs.has(evidenceRef)) {
+                throw new Error(`Dangling compact criterion evidence reference: ${evidenceRef}`);
+            }
+        }
+    }
+    return {
+        schemaValid: true,
+        coverageValid: true,
+        taskEpoch: expectedTaskEpoch,
+        taskEpochVerified: true,
+        criterionEvidenceRefsValid: true,
+        preservedCriterionIds: view.criterionStates.map(item => item.id),
+        validatedEvidenceRefs,
+    };
+}
+function validatePersistedSemanticReceipt(semanticSummary, receipt) {
+    const view = inspectSemanticSummary(semanticSummary);
+    if (receipt.schemaValid !== true ||
+        receipt.coverageValid !== true ||
+        receipt.taskEpochVerified !== true ||
+        receipt.criterionEvidenceRefsValid !== true ||
+        !Number.isInteger(receipt.taskEpoch) ||
+        receipt.taskEpoch < 1 ||
+        !isStringArray(receipt.preservedCriterionIds) ||
+        !Array.isArray(receipt.validatedEvidenceRefs) ||
+        !receipt.validatedEvidenceRefs.every(ref => typeof ref === 'string' && ref.length > 0) ||
+        view.taskEpoch !== receipt.taskEpoch ||
+        view.taskEpochs.some(taskEpoch => taskEpoch !== receipt.taskEpoch) ||
+        !sameStrings(view.criterionStates.map(item => item.id), receipt.preservedCriterionIds) ||
+        !sameStrings([...new Set(view.criterionStates.flatMap(item => item.evidenceRefs))], receipt.validatedEvidenceRefs)) {
+        throw new Error('Compact semantic validation receipt does not match its summary');
+    }
+}
+function reportInvalidCompactCheckpoint(path, reason) {
+    (0, debug_log_1.debugError)('session-storage.validateCompactCheckpoint', new Error(`Invalid compact checkpoint: ${reason}`), path);
+    return null;
+}
+function compactCandidatePath(path) {
+    return `${path}.candidate`;
+}
+function compactPreviousPath(path) {
+    return `${path}.previous`;
+}
 function parseCompactCheckpointFile(path) {
     try {
         const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf-8'));
-        if (parsed?.version !== 1 ||
+        if ((parsed?.version !== 1 && parsed?.version !== 2) ||
             !parsed.checkpointId ||
             !parsed.sessionId ||
             !Array.isArray(parsed.modelHistory) ||
@@ -430,6 +751,117 @@ function parseCompactCheckpointFile(path) {
             parsed.sourceMessageCount < 0 ||
             !parsed.summary ||
             typeof parsed.summary.text !== 'string') {
+            return reportInvalidCompactCheckpoint(path, 'base schema mismatch');
+        }
+        if (parsed.version === 1)
+            return parsed;
+        if (parsed.sourceBoundary?.startMessageIndex !== 0 ||
+            parsed.sourceBoundary.endMessageIndexExclusive !== parsed.sourceMessageCount ||
+            !isSha256(parsed.sourcePrefixHash) ||
+            !isSha256(parsed.modelHistoryHash) ||
+            parsed.summary.schemaVersion !== 2 ||
+            typeof parsed.summary.strategy !== 'string' ||
+            !parsed.summary.strategy ||
+            !Number.isInteger(parsed.contractVersion) ||
+            parsed.contractVersion < 1 ||
+            !Number.isInteger(parsed.harnessStateVersion) ||
+            parsed.harnessStateVersion < 1 ||
+            parsed.validation?.schemaValid !== true ||
+            parsed.validation.toolCallGroupsValid !== true ||
+            parsed.validation.sourcePrefixVerified !== true ||
+            parsed.validation.targetMet !== true ||
+            !isSha256(parsed.validation.bindingHash) ||
+            !Number.isFinite(parsed.validation.targetHeadroomRatio) ||
+            !Number.isFinite(parsed.validation.achievedUsageRatio) ||
+            !parsed.candidateReceipt ||
+            !['semantic_candidate', 'compatibility_adapter'].includes(parsed.candidateReceipt.source) ||
+            !isSha256(parsed.candidateReceipt.candidateFingerprint) ||
+            !isSha256(parsed.candidateReceipt.persistedProjectionFingerprint) ||
+            !Number.isInteger(parsed.candidateReceipt.beforeTokens) ||
+            parsed.candidateReceipt.beforeTokens < 0 ||
+            !Number.isInteger(parsed.candidateReceipt.afterTokens) ||
+            parsed.candidateReceipt.afterTokens < 0 ||
+            (parsed.candidateReceipt.targetTokens !== undefined &&
+                (!Number.isInteger(parsed.candidateReceipt.targetTokens) ||
+                    parsed.candidateReceipt.targetTokens < 0)) ||
+            !Number.isFinite(parsed.candidateReceipt.targetRatio) ||
+            !Array.isArray(parsed.candidateReceipt.diagnostics) ||
+            (parsed.harnessBinding !== undefined &&
+                (!Number.isInteger(parsed.harnessBinding.schemaVersion) ||
+                    parsed.harnessBinding.schemaVersion < 1 ||
+                    !isSha256(parsed.harnessBinding.stateHash))) ||
+            (parsed.goalBinding !== undefined &&
+                (!parsed.goalBinding.goalId ||
+                    !Number.isInteger(parsed.goalBinding.revision) ||
+                    parsed.goalBinding.revision < 0 ||
+                    !isSha256(parsed.goalBinding.stateHash)))) {
+            return reportInvalidCompactCheckpoint(path, 'V2 receipt mismatch');
+        }
+        if (canonicalContentHash(parsed.modelHistory) !== parsed.modelHistoryHash) {
+            return reportInvalidCompactCheckpoint(path, 'replacement history hash mismatch');
+        }
+        if ((0, fingerprint_1.canonicalMessagesFingerprint)(parsed.modelHistory) !==
+            parsed.candidateReceipt.persistedProjectionFingerprint) {
+            return reportInvalidCompactCheckpoint(path, 'persisted projection fingerprint mismatch');
+        }
+        const semanticSummaryHash = parsed.candidateReceipt.semanticSummary
+            ? canonicalContentHash(parsed.candidateReceipt.semanticSummary)
+            : undefined;
+        if (semanticSummaryHash !== parsed.candidateReceipt.semanticSummaryHash) {
+            return reportInvalidCompactCheckpoint(path, 'semantic summary hash mismatch');
+        }
+        const coverageHash = parsed.candidateReceipt.semanticSummary
+            ? canonicalContentHash(parsed.candidateReceipt.semanticSummary.coverage)
+            : undefined;
+        if (coverageHash !== parsed.candidateReceipt.coverageHash) {
+            return reportInvalidCompactCheckpoint(path, 'semantic coverage hash mismatch');
+        }
+        if (parsed.candidateReceipt.source === 'semantic_candidate') {
+            if (!parsed.candidateReceipt.prepareSource ||
+                !parsed.candidateReceipt.semanticSummary ||
+                !parsed.candidateReceipt.semanticValidation ||
+                parsed.validation.prepareSourceVerified !== true ||
+                parsed.validation.candidateTokensVerified !== true ||
+                parsed.validation.semanticReceiptVerified !== true) {
+                return reportInvalidCompactCheckpoint(path, 'semantic candidate validation is incomplete');
+            }
+            try {
+                validatePrepareSourceReceipt(parsed.candidateReceipt.prepareSource, parsed.sessionId);
+                if (parsed.candidateReceipt.prepareSource.sourceMessageCount !== parsed.sourceMessageCount ||
+                    parsed.candidateReceipt.prepareSource.sourcePrefixHash !== parsed.sourcePrefixHash) {
+                    return reportInvalidCompactCheckpoint(path, 'prepare-source boundary mismatch');
+                }
+                validatePersistedSemanticReceipt(parsed.candidateReceipt.semanticSummary, parsed.candidateReceipt.semanticValidation);
+            }
+            catch (error) {
+                return reportInvalidCompactCheckpoint(path, error instanceof Error ? error.message : String(error));
+            }
+        }
+        const prepareSourceHash = parsed.candidateReceipt.prepareSource
+            ? canonicalContentHash(parsed.candidateReceipt.prepareSource)
+            : undefined;
+        const semanticValidationHash = parsed.candidateReceipt.semanticValidation
+            ? canonicalContentHash(parsed.candidateReceipt.semanticValidation)
+            : undefined;
+        const expectedBindingHash = compactBindingHash({
+            sourcePrefixHash: parsed.sourcePrefixHash,
+            modelHistoryHash: parsed.modelHistoryHash,
+            candidateFingerprint: parsed.candidateReceipt.candidateFingerprint,
+            persistedProjectionFingerprint: parsed.candidateReceipt.persistedProjectionFingerprint,
+            semanticSummaryHash,
+            prepareSourceHash,
+            semanticValidationHash,
+            harnessStateHash: parsed.harnessBinding?.stateHash,
+            goalStateHash: parsed.goalBinding?.stateHash,
+        });
+        if (expectedBindingHash !== parsed.validation.bindingHash) {
+            return reportInvalidCompactCheckpoint(path, 'cross-state binding hash mismatch');
+        }
+        try {
+            (0, tool_call_groups_1.assertToolCallGroups)(parsed.modelHistory);
+        }
+        catch (error) {
+            (0, debug_log_1.debugError)('session-storage.validateCompactCheckpoint.toolGroups', error, path);
             return null;
         }
         return parsed;
@@ -733,30 +1165,158 @@ function persistSessionCompactHistory(sessionId, messages, timestamp = Date.now(
     appendSessionMessages(sessionId, compactMessages);
     return markSessionTranscriptDisplayStart(sessionId, timestamp);
 }
-function loadSessionCompactCheckpoint(sessionId) {
-    const session = loadSessionMeta(sessionId);
-    if (!session)
-        return null;
-    const checkpoint = parseCompactCheckpointFile((0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, sessionId));
-    if (!checkpoint || checkpoint.sessionId !== sessionId)
-        return null;
-    if (session.activeCompactCheckpointId !== checkpoint.checkpointId) {
-        return null;
+function loadCompactCheckpointForSession(session, messages) {
+    const compactPath = (0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, session.id);
+    const candidatePaths = [compactPath, compactPreviousPath(compactPath)];
+    for (const path of candidatePaths) {
+        if (!(0, fs_1.existsSync)(path))
+            continue;
+        const checkpoint = parseCompactCheckpointFile(path);
+        if (!checkpoint || checkpoint.sessionId !== session.id)
+            continue;
+        if (session.activeCompactCheckpointId !== checkpoint.checkpointId)
+            continue;
+        if (checkpoint.sourceMessageCount > messages.length)
+            continue;
+        if (checkpoint.version === 2 &&
+            canonicalContentHash(messages.slice(0, checkpoint.sourceMessageCount)) !==
+                checkpoint.sourcePrefixHash) {
+            reportInvalidCompactCheckpoint(path, 'covered transcript prefix hash mismatch');
+            continue;
+        }
+        return checkpoint;
     }
-    const rawCount = readSessionMessages(sessionId).length;
-    if (checkpoint.sourceMessageCount > rawCount)
-        return null;
-    return checkpoint;
+    return null;
+}
+function loadSessionCompactCheckpoint(sessionId) {
+    return (withLockedSession(sessionId, session => loadCompactCheckpointForSession(session, readSessionMessagesForSession(session))) ?? null);
 }
 function commitSessionCompactCheckpoint(input) {
     const checkpoint = withLockedSession(input.sessionId, session => {
-        const rawCount = readSessionMessagesForSession(session).length;
+        const rawMessages = readSessionMessagesForSession(session);
+        const rawCount = rawMessages.length;
+        if (input.candidate && !input.prepareSource) {
+            throw new Error('Semantic compact candidate requires a prepare-source receipt');
+        }
+        if (input.prepareSource) {
+            if (input.prepareSource.sourceMessageCount !== input.sourceMessageCount) {
+                throw new Error('Compact source boundary differs from its prepare-source receipt');
+            }
+            assertPrepareSourceMatches(input.prepareSource, session, rawMessages);
+        }
         if (input.sourceMessageCount < 0 || input.sourceMessageCount > rawCount) {
             throw new Error(`Invalid compact source boundary ${input.sourceMessageCount}; transcript has ${rawCount} messages`);
         }
         const createdAt = input.createdAt ?? Date.now();
+        const candidateModelHistory = input.modelHistory.map(message => JSON.parse(JSON.stringify(message)));
+        (0, tool_call_groups_1.assertToolCallGroups)(candidateModelHistory);
+        const modelHistory = input.modelHistory
+            .filter(message => message.role !== 'system')
+            .map(message => JSON.parse(JSON.stringify(message)));
+        (0, tool_call_groups_1.assertToolCallGroups)(modelHistory);
+        const targetHeadroomRatio = 0.65;
+        const safeInputBudget = Math.max(1, input.afterUsage.safeInputBudget ?? input.afterUsage.contextWindow);
+        const achievedUsageRatio = input.afterUsage.usedTokens / safeInputBudget;
+        if (!Number.isFinite(achievedUsageRatio) || achievedUsageRatio > targetHeadroomRatio) {
+            throw new Error(`Compact candidate did not reach the required ${Math.round(targetHeadroomRatio * 100)}% safe-input headroom target (${Math.round(achievedUsageRatio * 100)}% used)`);
+        }
+        const sourcePrefixHash = canonicalContentHash(rawMessages.slice(0, input.sourceMessageCount));
+        const modelHistoryHash = canonicalContentHash(modelHistory);
+        const persistedProjectionFingerprint = (0, fingerprint_1.canonicalMessagesFingerprint)(modelHistory);
+        const candidateBeforeTokens = input.candidate?.beforeTokens ?? input.beforeUsage.usedTokens;
+        const candidateAfterTokens = input.candidate?.afterTokens ?? input.afterUsage.usedTokens;
+        const candidateTargetRatio = input.candidate?.plan.targetRatio ?? targetHeadroomRatio;
+        const candidateFingerprint = input.candidate?.fingerprint ?? persistedProjectionFingerprint;
+        for (const [name, value] of [
+            ['beforeTokens', candidateBeforeTokens],
+            ['afterTokens', candidateAfterTokens],
+        ]) {
+            if (!Number.isInteger(value) || value < 0) {
+                throw new Error(`Compact candidate ${name} must be a non-negative integer`);
+            }
+        }
+        if (!isSha256(candidateFingerprint)) {
+            throw new Error('Compact candidate fingerprint must be a SHA-256 digest');
+        }
+        if (input.candidate) {
+            const actualCandidateTokens = (0, token_estimate_1.estimateMessagesTokens)(candidateModelHistory);
+            if (candidateAfterTokens !== actualCandidateTokens) {
+                throw new Error(`Compact candidate afterTokens ${candidateAfterTokens} does not match actual history ${actualCandidateTokens}`);
+            }
+            if (input.candidate.plan.targetTokens !== undefined &&
+                candidateAfterTokens > input.candidate.plan.targetTokens) {
+                throw new Error('Compact candidate exceeds its prepared target token budget');
+            }
+        }
+        if (!Number.isFinite(candidateTargetRatio) ||
+            candidateTargetRatio <= 0 ||
+            candidateTargetRatio > targetHeadroomRatio) {
+            throw new Error(`Compact candidate target ratio must be within (0, ${targetHeadroomRatio}]`);
+        }
+        const semanticSummary = input.candidate
+            ? JSON.parse(JSON.stringify(input.candidate.semanticSummary))
+            : undefined;
+        const semanticSummaryHash = semanticSummary ? canonicalContentHash(semanticSummary) : undefined;
+        const coverageHash = semanticSummary
+            ? canonicalContentHash(semanticSummary.coverage)
+            : undefined;
+        const semanticValidation = input.candidate && semanticSummary
+            ? semanticValidationReceipt(semanticSummary, input.candidate, input.semanticHarnessState ?? input.harnessState)
+            : undefined;
+        const prepareSource = input.prepareSource
+            ? { ...input.prepareSource }
+            : undefined;
+        const harnessBinding = input.harnessState
+            ? {
+                schemaVersion: input.harnessState.version ?? input.harnessStateVersion ?? 2,
+                stateHash: canonicalContentHash(input.harnessState),
+            }
+            : undefined;
+        const goalBinding = input.goalBinding
+            ? {
+                goalId: input.goalBinding.goalId,
+                revision: input.goalBinding.revision,
+                stateHash: canonicalContentHash(input.goalBinding.state ?? {
+                    goalId: input.goalBinding.goalId,
+                    revision: input.goalBinding.revision,
+                }),
+            }
+            : undefined;
+        const candidateReceipt = {
+            source: input.candidate ? 'semantic_candidate' : 'compatibility_adapter',
+            candidateFingerprint,
+            persistedProjectionFingerprint,
+            beforeTokens: candidateBeforeTokens,
+            afterTokens: candidateAfterTokens,
+            targetTokens: input.candidate?.plan.targetTokens,
+            targetRatio: candidateTargetRatio,
+            semanticSummary,
+            semanticSummaryHash,
+            diagnostics: input.candidate?.diagnostics.map(diagnostic => ({
+                ...diagnostic,
+                message: (0, redaction_1.redactTraceText)(diagnostic.message),
+            })) ?? [],
+            coverageHash,
+            prepareSource,
+            semanticValidation,
+        };
+        const prepareSourceHash = prepareSource ? canonicalContentHash(prepareSource) : undefined;
+        const semanticValidationHash = semanticValidation
+            ? canonicalContentHash(semanticValidation)
+            : undefined;
+        const bindingHash = compactBindingHash({
+            sourcePrefixHash,
+            modelHistoryHash,
+            candidateFingerprint,
+            persistedProjectionFingerprint,
+            semanticSummaryHash,
+            prepareSourceHash,
+            semanticValidationHash,
+            harnessStateHash: harnessBinding?.stateHash,
+            goalStateHash: goalBinding?.stateHash,
+        });
         const nextCheckpoint = {
-            version: 1,
+            version: 2,
             checkpointId: (0, crypto_1.randomUUID)(),
             sessionId: input.sessionId,
             createdAt,
@@ -764,34 +1324,128 @@ function commitSessionCompactCheckpoint(input) {
             modelId: input.modelId,
             sourceMessageCount: input.sourceMessageCount,
             transcriptStartMessageIndex: Math.max(0, Math.min(input.sourceMessageCount, input.transcriptStartMessageIndex)),
-            modelHistory: input.modelHistory
-                .filter(message => message.role !== 'system')
-                .map(message => ({ ...message })),
+            sourceBoundary: {
+                startMessageIndex: 0,
+                endMessageIndexExclusive: input.sourceMessageCount,
+            },
+            sourcePrefixHash,
+            modelHistory,
+            modelHistoryHash,
             summary: {
                 ...input.summary,
                 sourceMessageCount: input.sourceMessageCount,
+                schemaVersion: 2,
+                strategy: input.strategy ??
+                    (input.summary.source === 'llm' ? 'semantic-llm-v2' : 'deterministic-fallback-v2'),
             },
             beforeUsage: { ...input.beforeUsage },
             afterUsage: { ...input.afterUsage },
+            contractVersion: (() => {
+                const derivedContractVersion = input.harnessState?.contract?.version ?? 1;
+                if (input.contractVersion !== undefined &&
+                    input.harnessState?.contract?.version !== undefined &&
+                    input.contractVersion !== derivedContractVersion) {
+                    throw new Error(`Compact contractVersion ${input.contractVersion} does not match Harness contract ${derivedContractVersion}`);
+                }
+                return input.contractVersion ?? derivedContractVersion;
+            })(),
+            harnessStateVersion: harnessBinding?.schemaVersion ?? input.harnessStateVersion ?? 2,
+            harnessBinding,
+            goalBinding,
+            candidateReceipt,
+            validation: {
+                schemaValid: true,
+                toolCallGroupsValid: true,
+                sourcePrefixVerified: true,
+                targetHeadroomRatio,
+                achievedUsageRatio,
+                targetMet: true,
+                prepareSourceVerified: prepareSource ? true : undefined,
+                candidateTokensVerified: input.candidate ? true : undefined,
+                semanticReceiptVerified: semanticValidation ? true : undefined,
+                bindingHash,
+                validatedAt: createdAt,
+            },
         };
         const previousId = session.activeCompactCheckpointId;
         const previousTime = session.lastCompactAt;
-        session.activeCompactCheckpointId = nextCheckpoint.checkpointId;
-        session.lastCompactAt = createdAt;
-        session.updatedAt = createdAt;
-        session.updatedAtIso = new Date(createdAt).toISOString();
-        // Commit the pointer before replacing the atomic sidecar. If the process
-        // crashes between writes, the loader safely uses the last valid sidecar.
-        writeSessionMetaUnlocked(session);
+        const previousUpdatedAt = session.updatedAt;
+        const previousUpdatedAtIso = session.updatedAtIso;
+        const compactPath = (0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, input.sessionId);
+        const candidatePath = compactCandidatePath(compactPath);
+        const previousPath = compactPreviousPath(compactPath);
+        // Recover a process that crashed after installing a new sidecar but before
+        // committing its pointer. The previous file is keyed by the durable pointer.
+        if ((0, fs_1.existsSync)(previousPath)) {
+            const installed = (0, fs_1.existsSync)(compactPath) ? parseCompactCheckpointFile(compactPath) : null;
+            const previous = parseCompactCheckpointFile(previousPath);
+            if (previousId &&
+                installed?.checkpointId !== previousId &&
+                previous?.checkpointId === previousId) {
+                if ((0, fs_1.existsSync)(compactPath))
+                    (0, fs_1.unlinkSync)(compactPath);
+                (0, fs_1.renameSync)(previousPath, compactPath);
+            }
+            else if (installed?.checkpointId === previousId) {
+                (0, fs_1.unlinkSync)(previousPath);
+            }
+            else {
+                throw new Error('Cannot reconcile interrupted compact checkpoint transaction');
+            }
+        }
+        (0, atomic_write_1.atomicWriteFileSync)(candidatePath, JSON.stringify(nextCheckpoint, null, 2), { mode: 0o600 });
+        const prepared = parseCompactCheckpointFile(candidatePath);
+        if (prepared?.version !== 2 || prepared.checkpointId !== nextCheckpoint.checkpointId) {
+            if ((0, fs_1.existsSync)(candidatePath))
+                (0, fs_1.unlinkSync)(candidatePath);
+            throw new Error('Compact candidate failed durable reload validation');
+        }
+        let previousInstalled = false;
+        let candidateInstalled = false;
         try {
-            (0, atomic_write_1.atomicWriteFileSync)((0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, input.sessionId), JSON.stringify(nextCheckpoint, null, 2), { mode: 0o600 });
+            if ((0, fs_1.existsSync)(compactPath)) {
+                (0, fs_1.renameSync)(compactPath, previousPath);
+                previousInstalled = true;
+            }
+            (0, fs_1.renameSync)(candidatePath, compactPath);
+            candidateInstalled = true;
+            session.activeCompactCheckpointId = nextCheckpoint.checkpointId;
+            session.lastCompactAt = createdAt;
+            session.updatedAt = createdAt;
+            session.updatedAtIso = new Date(createdAt).toISOString();
+            writeSessionMetaUnlocked(session);
+            const persistedSession = readSessionMetaAtPath((0, config_dir_1.getProjectSessionMetaPath)(session.projectPath, session.id));
+            const persistedCheckpoint = parseCompactCheckpointFile(compactPath);
+            if (persistedSession?.activeCompactCheckpointId !== nextCheckpoint.checkpointId ||
+                persistedCheckpoint?.checkpointId !== nextCheckpoint.checkpointId) {
+                throw new Error('Compact checkpoint commit could not be read back atomically');
+            }
         }
         catch (error) {
             session.activeCompactCheckpointId = previousId;
             session.lastCompactAt = previousTime;
-            writeSessionMetaUnlocked(session);
+            session.updatedAt = previousUpdatedAt;
+            session.updatedAtIso = previousUpdatedAtIso;
+            if (candidateInstalled && (0, fs_1.existsSync)(compactPath))
+                (0, fs_1.unlinkSync)(compactPath);
+            if (previousInstalled && (0, fs_1.existsSync)(previousPath))
+                (0, fs_1.renameSync)(previousPath, compactPath);
+            if ((0, fs_1.existsSync)(candidatePath))
+                (0, fs_1.unlinkSync)(candidatePath);
+            const persistedSession = readSessionMetaAtPath((0, config_dir_1.getProjectSessionMetaPath)(session.projectPath, session.id));
+            if (persistedSession?.activeCompactCheckpointId === nextCheckpoint.checkpointId) {
+                writeSessionMetaUnlocked(session);
+            }
             throw error;
         }
+        if ((0, fs_1.existsSync)(previousPath)) {
+            try {
+                (0, fs_1.unlinkSync)(previousPath);
+            }
+            catch (error) {
+                (0, debug_log_1.debugError)('session-storage.compactPreviousCleanup', error, previousPath);
+            }
+        }
         return nextCheckpoint;
     });
     if (!checkpoint)
@@ -799,16 +1453,16 @@ function commitSessionCompactCheckpoint(input) {
     return checkpoint;
 }
 function loadSessionTranscriptMessages(sessionId) {
-    const messages = readSessionMessages(sessionId);
-    const checkpoint = loadSessionCompactCheckpoint(sessionId);
-    if (checkpoint) {
-        return messages.slice(checkpoint.transcriptStartMessageIndex);
-    }
-    const session = loadSessionMeta(sessionId);
-    const displayStartTime = session?.transcriptDisplayStartTime;
-    return typeof displayStartTime === 'number'
-        ? messages.filter(message => (message.timestamp ?? 0) >= displayStartTime)
-        : messages;
+    return (withLockedSession(sessionId, session => {
+        const messages = readSessionMessagesForSession(session);
+        const checkpoint = loadCompactCheckpointForSession(session, messages);
+        if (checkpoint) {
+            return messages.slice(checkpoint.transcriptStartMessageIndex);
+        }
+        return typeof session.transcriptDisplayStartTime === 'number'
+            ? messages.filter(message => (message.timestamp ?? 0) >= (session.transcriptDisplayStartTime ?? 0))
+            : messages;
+    }) ?? []);
 }
 function hasPersistedCompactContext(messages) {
     return messages.some(message => message.content.includes('[Orion Code Context State v2]') ||
@@ -1192,24 +1846,37 @@ function readSessionTraceEvents(sessionId) {
  * 包含完整的 tool_calls 信息，确保 LLM 能理解之前的工具调用
  */
 function loadSessionHistory(sessionId) {
-    const messages = readSessionMessages(sessionId);
-    const checkpoint = loadSessionCompactCheckpoint(sessionId);
-    if (checkpoint) {
-        return (0, tool_call_groups_1.sealToolCallGroups)([
-            ...checkpoint.modelHistory.map(message => ({ ...message })),
-            ...messages.slice(checkpoint.sourceMessageCount).map(sessionMessageToModelMessage),
-        ]);
-    }
-    const session = loadSessionMeta(sessionId);
-    const displayStartTime = session?.transcriptDisplayStartTime;
-    let modelVisibleMessages = messages;
-    if (typeof displayStartTime === 'number') {
-        const afterDisplayStart = messages.filter(message => (message.timestamp ?? 0) >= displayStartTime);
-        modelVisibleMessages = hasPersistedCompactContext(afterDisplayStart)
-            ? afterDisplayStart
-            : messages;
-    }
-    return (0, tool_call_groups_1.sealToolCallGroups)(modelVisibleMessages.map(sessionMessageToModelMessage));
+    return (withLockedSession(sessionId, session => {
+        const messages = readSessionMessagesForSession(session);
+        const checkpoint = loadCompactCheckpointForSession(session, messages);
+        if (checkpoint) {
+            const restored = [
+                ...checkpoint.modelHistory.map(message => ({ ...message })),
+                ...messages.slice(checkpoint.sourceMessageCount).map(sessionMessageToModelMessage),
+            ];
+            if (checkpoint.version === 2) {
+                try {
+                    (0, tool_call_groups_1.assertToolCallGroups)(restored);
+                    return restored;
+                }
+                catch (error) {
+                    // Never mutate or synthesize data inside a validated V2
+                    // replacement. Fall back to the append-only transcript instead.
+                    (0, debug_log_1.debugError)('session-storage.restoreCompactCheckpoint.toolGroups', error, sessionId);
+                    return (0, tool_call_groups_1.sealToolCallGroups)(messages.map(sessionMessageToModelMessage));
+                }
+            }
+            return (0, tool_call_groups_1.sealToolCallGroups)(restored);
+        }
+        let modelVisibleMessages = messages;
+        if (typeof session.transcriptDisplayStartTime === 'number') {
+            const afterDisplayStart = messages.filter(message => (message.timestamp ?? 0) >= (session.transcriptDisplayStartTime ?? 0));
+            modelVisibleMessages = hasPersistedCompactContext(afterDisplayStart)
+                ? afterDisplayStart
+                : messages;
+        }
+        return (0, tool_call_groups_1.sealToolCallGroups)(modelVisibleMessages.map(sessionMessageToModelMessage));
+    }) ?? []);
 }
 function sessionMessageToModelMessage(message) {
     const result = {
@@ -1292,11 +1959,14 @@ function renameSession(sessionId, name) {
 function deleteSession(sessionId) {
     return (withLockedSession(sessionId, session => {
         let deleted = false;
+        const compactPath = (0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, sessionId);
         const paths = [
             (0, config_dir_1.getProjectSessionMetaPath)(session.projectPath, sessionId),
             (0, config_dir_1.getProjectSessionMessagesPath)(session.projectPath, sessionId),
             (0, config_dir_1.getProjectSessionHarnessPath)(session.projectPath, sessionId),
-            (0, config_dir_1.getProjectSessionCompactPath)(session.projectPath, sessionId),
+            compactPath,
+            compactCandidatePath(compactPath),
+            compactPreviousPath(compactPath),
             (0, config_dir_1.getProjectSessionTracePath)(session.projectPath, sessionId),
         ];
         // Preserve a durable deletion fence so a stale writer in another process