tinker-agent 1.0.65 → 1.2.0

package/src/session/session-store.ts

@@ -4,6 +4,7 @@ import {
   lstat,
   mkdir,
   open,
+  readFile,
   readdir,
   realpath,
   rename,
@@ -14,6 +15,7 @@ import { randomUUID } from "node:crypto";
 import { Database } from "bun:sqlite";
 import type {
   ContextRevisionId,
+  ContextSurfaceId,
   IterationId,
   MessageId,
   ProtocolFrameId,
@@ -22,11 +24,13 @@ import type {
   ToolCallId,
   TurnId,
 } from "../ids/runtime-id";
-import type {
-  ModelContextBudget,
-  ModelContextProfile,
+import {
+  createModelContextProfile,
+  type ModelContextProfile,
 } from "../model/model-context-profile";
-import type { ToolRawResult } from "../tools/types";
+import type { ModelMessageProtocol } from "../model/model-client";
+import type { InputTokenEstimatorCompatibility } from "../model/input-token-estimator";
+import type { ToolDefinition, ToolRawResult } from "../tools/types";
 import { sha256, stableJsonStringify } from "../model/model-request-preflight";
 import {
   ContextProtocolError,
@@ -41,33 +45,54 @@ import {
   ContextRevisionCompiler,
   createInitialContextRevision,
 } from "../context/context-revision-compiler";
+import { recallFirstRetirementPolicyV1 } from "../context/context-policy";
 import {
   ContextSwapRenderer,
   SWAP_OBSERVATION_FORMAT,
 } from "../context/context-swap-renderer";
 import {
-  TOOL_OBSERVATION_FORMAT,
+  SUPPORTED_TOOL_OBSERVATION_FORMATS,
   contentHash,
   immutableCanonicalClone,
   immutableRecord,
   interruptedCompletionInputs,
   observationForCompletion,
+  userMessageHash,
   type CanonicalMessageRecord,
   type ProtocolContextView,
   type ProtocolFrame,
   type ToolCompletion,
   type ToolResultRecord,
 } from "../context/protocol-frame";
+import {
+  contextSurfaceChangeManifestHash,
+  contextSurfaceChanges,
+  validateStoredContextSurface,
+  type ContextSurfaceChanges,
+  type StoredContextSurfaceV8,
+} from "../context/context-surface";
 import type {
-  StoredContextRevisionV5,
-  StoredContextSnapshotV5,
-  StoredSwapOverrideV5,
+  StoredContextRevisionV8,
+  StoredContextSnapshotV8,
+  StoredContextOverrideV8,
   SwapOverride,
 } from "../context/context-revision";
 import type { IterationIdentity, ToolCall } from "../agent/types";
+import {
+  parseImageAssetId,
+  parseImageAttachmentId,
+  validateOriginalImageName,
+  validateUserMessage,
+  type ImageAssetRef,
+  type UserImageAttachment,
+} from "../image/image-types";
+import { ImageAssetStore } from "../image/image-asset-store";
 import type { MeasuredContextAnchor } from "../agent/context-meter";
 import type { ProjectInstructionManifest } from "../instructions/project-instructions";
+import { SUPPORTED_RECALL_RETIREMENT_CONTRACT_VERSIONS } from "../context/recall-retirement-contract";
+import type { ClosedTurnBoundary } from "../context/prefix-retirement-planner";
 import {
+  AdmissionStaleError,
   InMemorySessionLedger,
   type LedgerMutation,
   type SessionLedgerCommitter,
@@ -79,31 +104,57 @@ import {
 } from "./session-history-reader";
 import { SessionLease } from "./session-lock";
 import {
-  SESSION_SCHEMA_V5_FINGERPRINT,
+  SESSION_SCHEMA_V9_FINGERPRINT,
   SESSION_SCHEMA_VERSION,
   configureWritableDatabase,
   createSessionSchema,
+  dropSessionCloneTriggers,
   rebuildRecallIndex,
+  reinstallSessionCloneTriggers,
   verifyRecallIndex,
   verifySessionSchema,
   verifySqliteIntegrity,
 } from "./session-schema";
+import type { AgentEvent } from "../events/types";
+import { renderObservationLogEvent } from "../events/observation-text-log";
+import {
+  SKILL_FILE_MAX_BYTES,
+  SKILL_RESOURCE_MAX_DEPTH,
+  SKILL_RESOURCE_MAX_ENTRIES,
+  type SkillScope,
+} from "../skills/skill-loader";
+import type {
+  ActiveSkillManifestEntry,
+  SkillCatalogManifestEntry,
+} from "../skills/skill-catalog";
+import {
+  SKILL_ACTIVATION_RECEIPT_FORMAT,
+  SKILL_POLICY_VERSION,
+  renderSkillActivationReceipt,
+} from "../skills/skill-context";
+import {
+  IMAGE_INPUT_POLICY,
+  IMAGE_INPUT_POLICY_VERSION,
+} from "../image/image-input-policy";
 
-export type RuntimeContractV1 = {
-  version: 1;
+export type SessionImageInputCompatibility = {
+  readonly policyVersion: string;
+  readonly policySha256: string;
+  readonly inputModalities: readonly ("text" | "image")[];
+  readonly tokenEstimator?: InputTokenEstimatorCompatibility;
+};
+
+export type SessionCompatibilityContract = {
   modelName: string;
   profileName?: string;
   includeReasoningContent: boolean;
   contextProfile: ModelContextProfile;
-  contextBudget: ModelContextBudget;
-  systemPromptSha256: string;
-  toolSchemaSha256: string;
-  requestConfigSha256: string;
-  observationFormat: typeof TOOL_OBSERVATION_FORMAT;
+  messageProtocol: ModelMessageProtocol;
+  imageInput: SessionImageInputCompatibility;
 };
 
-export type StoredSessionMetaV5 = {
-  schemaVersion: 5;
+export type StoredSessionMetaV9 = {
+  schemaVersion: 9;
   schemaFingerprint: string;
   initializationState: "creating" | "ready";
   sessionId: SessionId;
@@ -111,10 +162,9 @@ export type StoredSessionMetaV5 = {
   modelName: string;
   systemPromptSha256: string;
   projectInstruction?: ProjectInstructionManifest;
-  toolSchemaSha256: string | null;
-  runtimeContractJson: string | null;
-  runtimeContractSha256: string | null;
-  activeRevisionId: ContextRevisionId;
+  sessionCompatibilityJson: string | null;
+  sessionCompatibilitySha256: string | null;
+  activeRevisionId: ContextRevisionId | null;
   nextTurnNumber: number;
   nextEventSequence: number;
   openCount: number;
@@ -131,7 +181,7 @@ export type StoredSessionMetaV5 = {
     | null;
 };
 
-export type SessionCloseReason = NonNullable<StoredSessionMetaV5["lastCloseReason"]>;
+export type SessionCloseReason = NonNullable<StoredSessionMetaV9["lastCloseReason"]>;
 
 export type SessionRecoveryResult = {
   recoveredTurnId?: TurnId;
@@ -150,12 +200,12 @@ export type CommitSwapRevisionInput = {
   expectedBaseRevisionId: ContextRevisionId;
   expectedBaseRevisionNumber: number;
   expectedCanonicalThroughOrdinal: number;
-  expectedBaseOverrideManifestSha256: string;
+  expectedBaseActiveOverrideManifestSha256: string;
   policyVersion: "swap-only-v1";
   rendererFormat: typeof SWAP_OBSERVATION_FORMAT;
   planHash: string;
   addedOverrides: readonly SwapOverride[];
-  nextOverrideManifestSha256: string;
+  nextActiveOverrideManifestSha256: string;
   canonicalSequenceSha256: string;
   renderedMessageSha256: string;
 };
@@ -172,6 +222,155 @@ export type CommitSwapRevisionOptions = {
   faultInjector?: (stage: CommitSwapRevisionFaultStage) => void;
 };
 
+export type CommitSurfaceRefreshInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedBaseActiveOverrideManifestSha256: string;
+  surface: StoredContextSurfaceV8;
+  changes: ContextSurfaceChanges;
+  changeManifestSha256: string;
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+};
+
+export type CommitSurfaceRefreshFaultStage =
+  | "before_surface_insert"
+  | "after_surface_insert"
+  | "after_revision_insert"
+  | "after_measurement_delete"
+  | "after_active_update";
+
+export type CommitSurfaceRefreshOptions = {
+  faultInjector?: (stage: CommitSurfaceRefreshFaultStage) => void;
+};
+
+export type CommitPrefixRetirementRevisionInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedBaseKeepFromOrdinal: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedSurfaceSha256: string;
+  expectedBaseActiveOverrideManifestSha256: string;
+  policyVersion: "recall-first-retirement-v1";
+  planHash: string;
+  nextKeepFromOrdinal: number;
+  retiredThroughOrdinal: number;
+  retiredTurnCount: number;
+  retiredFrameCount: number;
+  retiredMessageCount: number;
+  nextActiveOverrideCount: number;
+  nextActiveOverrideManifestSha256: string;
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+};
+
+export type CommitPrefixRetirementRevisionFaultStage =
+  | "before_revision_insert"
+  | "after_revision_insert"
+  | "after_override_readback"
+  | "after_measurement_delete"
+  | "after_active_update"
+  | "after_snapshot_readback";
+
+export type CommitPrefixRetirementRevisionOptions = {
+  faultInjector?: (stage: CommitPrefixRetirementRevisionFaultStage) => void;
+};
+
+export type StoredSkillActivation = {
+  readonly activationMessageId: MessageId;
+  readonly toolCallId: ToolCallId;
+  readonly sessionId: SessionId;
+  readonly name: string;
+  readonly scope: SkillScope;
+  readonly skillFileSha256: string;
+  readonly state: "pending" | "dispatched" | "promoted" | "rejected";
+  readonly dispatchedIterationId?: IterationId;
+  readonly settledRevisionId?: ContextRevisionId;
+  readonly rejectionReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type CommitSkillsUpdateInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedBaseActiveOverrideManifestSha256: string;
+  surface: StoredContextSurfaceV8;
+  changes: ContextSurfaceChanges;
+  changeManifestSha256: string;
+  activationManifestSha256: string;
+  addedOverrides: readonly SwapOverride[];
+  nextActiveOverrideManifestSha256: string;
+  settlements: readonly {
+    activationMessageId: MessageId;
+    name: string;
+    state: "promoted" | "rejected";
+    rejectionReason?: string;
+  }[];
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+};
+
+export type CommitSkillsUpdateFaultStage =
+  | "before_surface_insert"
+  | "after_surface_insert"
+  | "after_revision_insert"
+  | "after_first_override_insert"
+  | "after_overrides_insert"
+  | "after_activations_update"
+  | "after_measurement_delete"
+  | "after_active_update";
+
+export type CommitSkillsUpdateOptions = {
+  faultInjector?: (stage: CommitSkillsUpdateFaultStage) => void;
+};
+
+export type CloneSessionFaultStage =
+  | "after_staging_mkdir"
+  | "after_snapshot"
+  | "after_trigger_drop"
+  | "after_identity_update"
+  | "after_revision_hash_rewrite"
+  | "after_trigger_reinstall"
+  | "after_recall_validation"
+  | "after_event_rewrite"
+  | "after_observation_render"
+  | "after_artifact_validation"
+  | "before_publish_rename";
+
+export type CloneSessionStoreInput = {
+  targetSessionId: SessionId;
+  faultInjector?: (stage: CloneSessionFaultStage) => void;
+};
+
+export function skillActivationManifestSha256(
+  settlements: CommitSkillsUpdateInput["settlements"],
+): string {
+  return sha256(
+    stableJsonStringify(
+      [...settlements]
+        .sort(
+          (left, right) =>
+            compareCanonicalText(left.name, right.name) ||
+            compareCanonicalText(left.activationMessageId, right.activationMessageId),
+        )
+        .map((settlement) => ({
+          activationMessageId: settlement.activationMessageId,
+          name: settlement.name,
+          state: settlement.state,
+          ...(settlement.rejectionReason === undefined
+            ? {}
+            : { rejectionReason: settlement.rejectionReason }),
+        })),
+    ),
+  );
+}
+
 export type CreateNewSessionStoreInput = {
   workspaceRoot: string;
   sessionId: SessionId;
@@ -254,21 +453,14 @@ export class SessionStore implements SessionLedgerCommitter {
       createSessionSchema(database);
       verifySessionSchema(database, input.sessionId);
 
-      const revisionId = input.idFactory.createContextRevisionId();
       const initialLedger = new InMemorySessionLedger({
         sessionId: input.sessionId,
         systemPrompt: input.systemPrompt,
         idFactory: input.idFactory,
-        initialRevisionId: revisionId,
         clock,
       });
       const initialView = initialLedger.snapshot({ fullIntegrity: true });
       const createdAt = clock();
-      const initialRevision = createInitialContextRevision({
-        revisionId,
-        canonical: initialView,
-        createdAt,
-      });
       runTransaction(database, () => {
         database!
           .query(
@@ -277,14 +469,14 @@ export class SessionStore implements SessionLedgerCommitter {
             session_id, workspace_root, model_name, system_prompt_sha256,
             project_instruction_file, project_instruction_byte_length,
             project_instruction_sha256,
-            tool_schema_sha256, runtime_contract_json, runtime_contract_sha256,
+            session_compatibility_json, session_compatibility_sha256,
             active_revision_id, next_turn_number, next_event_sequence, open_count,
             created_at, updated_at, last_opened_at, last_closed_at, last_close_reason
-          ) VALUES (1, ?, ?, 'creating', ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?, 1, 1, 1, ?, ?, ?, NULL, NULL)`,
+          ) VALUES (1, ?, ?, 'creating', ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, 1, 1, 1, ?, ?, ?, NULL, NULL)`,
           )
           .run(
             SESSION_SCHEMA_VERSION,
-            SESSION_SCHEMA_V5_FINGERPRINT,
+            SESSION_SCHEMA_V9_FINGERPRINT,
             input.sessionId,
             workspaceRoot,
             input.modelName,
@@ -292,7 +484,6 @@ export class SessionStore implements SessionLedgerCommitter {
             input.projectInstruction?.path ?? null,
             input.projectInstruction?.byteLength ?? null,
             input.projectInstruction?.sha256 ?? null,
-            revisionId,
             createdAt,
             createdAt,
             createdAt,
@@ -302,24 +493,6 @@ export class SessionStore implements SessionLedgerCommitter {
           database!,
           requireItem(initialView.messages, 0, "system message"),
         );
-        database!
-          .query(
-            `INSERT INTO context_revisions (
-            revision_id, session_id, revision_number, parent_revision_id, kind,
-            keep_from_ordinal, source_through_ordinal, added_override_count,
-            total_override_count, override_manifest_sha256,
-            canonical_sequence_sha256, rendered_message_sha256, policy_version,
-            renderer_format, plan_sha256, created_at
-          ) VALUES (?, ?, 1, NULL, 'initial_full', 1, 1, 0, 0, ?, ?, ?, NULL, NULL, NULL, ?)`,
-          )
-          .run(
-            revisionId,
-            input.sessionId,
-            initialRevision.overrideManifestSha256,
-            initialRevision.canonicalSequenceSha256,
-            initialRevision.renderedMessageSha256,
-            createdAt,
-          );
       });
 
       const store = new SessionStore(database, lease, {
@@ -330,7 +503,7 @@ export class SessionStore implements SessionLedgerCommitter {
         clock,
       });
       await store.correctDatabaseModes();
-      store.validateAll({ allowOpenTail: false });
+      store.validateCreatingState();
       verifyRecallIndex(database, input.sessionId);
       return store;
     } catch (error) {
@@ -394,7 +567,12 @@ export class SessionStore implements SessionLedgerCommitter {
           { sessionId: input.sessionId },
         );
       }
-      store.validateAll({ allowOpenTail: true });
+      if (meta.initializationState === "creating") {
+        store.validateCreatingState();
+      } else {
+        store.validateAll({ allowOpenTail: true });
+        await store.verifyImageAssetFiles();
+      }
       try {
         verifyRecallIndex(database, input.sessionId);
       } catch (error) {
@@ -455,6 +633,9 @@ export class SessionStore implements SessionLedgerCommitter {
         }
       });
     } catch (error) {
+      if (error instanceof AdmissionStaleError) {
+        throw error;
+      }
       throw sessionWriteError(mutation.kind, this.sessionId, error);
     }
   }
@@ -554,46 +735,106 @@ export class SessionStore implements SessionLedgerCommitter {
     }
   }
 
-  finalizeRuntimeContract(contract: RuntimeContractV1): void {
+  finalizeInitialization(input: {
+    contract: SessionCompatibilityContract;
+    surface: StoredContextSurfaceV8;
+    revisionId: ContextRevisionId;
+  }): void {
     this.requireOpen();
+    const contract = normalizeSessionCompatibilityContract(input.contract);
     const json = stableJsonStringify(contract);
     const contractSha256 = sha256(json);
     const now = this.clock();
     try {
       runTransaction(this.database, () => {
+        const meta = this.readMeta();
+        if (
+          meta.initializationState !== "creating" ||
+          meta.activeRevisionId !== null ||
+          input.surface.sessionId !== this.sessionId
+        ) {
+          throw new Error("Session initialization base is invalid.");
+        }
+        validateStoredContextSurface(input.surface);
+        const canonical = this.loadProtocolView();
+        const creationPrompt = this.readCreationSystemPrompt();
+        if (input.surface.systemPrompt !== creationPrompt) {
+          throw new Error(
+            "Initial context surface must match the creation system prompt.",
+          );
+        }
+        const revision = createInitialContextRevision({
+          revisionId: input.revisionId,
+          canonical,
+          surface: input.surface,
+          createdAt: now,
+        });
+        insertContextSurface(this.database, input.surface);
+        this.database
+          .query(
+            `INSERT INTO context_revisions (
+              revision_id, session_id, revision_number, parent_revision_id, kind,
+              surface_id, surface_sha256, keep_from_ordinal,
+              source_through_ordinal, added_override_count, active_override_count,
+              active_override_manifest_sha256, canonical_sequence_sha256,
+              rendered_message_sha256, policy_version, renderer_format,
+              plan_sha256, change_manifest_sha256, created_at
+            ) VALUES (?, ?, 1, NULL, 'initial_full', ?, ?, 1, 1, 0, 0, ?, ?, ?, NULL, NULL, NULL, NULL, ?)`,
+          )
+          .run(
+            revision.revisionId,
+            this.sessionId,
+            revision.surfaceId,
+            revision.surfaceSha256,
+            revision.activeOverrideManifestSha256,
+            revision.canonicalSequenceSha256,
+            revision.renderedMessageSha256,
+            revision.createdAt,
+          );
         const updated = this.database
           .query(
             `UPDATE session_meta
-           SET initialization_state = 'ready', tool_schema_sha256 = ?,
-               runtime_contract_json = ?, runtime_contract_sha256 = ?, updated_at = ?
+           SET initialization_state = 'ready', session_compatibility_json = ?,
+               session_compatibility_sha256 = ?, active_revision_id = ?, updated_at = ?
            WHERE singleton = 1 AND initialization_state = 'creating'
-             AND runtime_contract_json IS NULL`,
+             AND session_compatibility_json IS NULL AND active_revision_id IS NULL`,
           )
-          .run(contract.toolSchemaSha256, json, contractSha256, now);
+          .run(json, contractSha256, revision.revisionId, now);
         requireSingleChange(
           this.database,
           updated.changes,
-          "finalize runtime contract",
+          "finalize session initialization",
         );
+        const readback = this.loadContextSnapshot();
+        if (
+          readback.revision.revisionId !== revision.revisionId ||
+          readback.surface.surfaceId !== input.surface.surfaceId
+        ) {
+          throw new Error("Finalized session initialization readback failed.");
+        }
       });
     } catch (error) {
-      throw sessionWriteError("finalize_runtime_contract", this.sessionId, error);
+      throw sessionWriteError("finalize_session_initialization", this.sessionId, error);
     }
   }
 
-  assertRuntimeContract(contract: RuntimeContractV1): void {
+  assertSessionCompatibility(contract: SessionCompatibilityContract): void {
     const meta = this.readMeta();
-    const current = stableJsonStringify(contract);
+    const currentContract = normalizeSessionCompatibilityContract(contract);
+    const current = stableJsonStringify(currentContract);
     const currentHash = sha256(current);
     if (
-      meta.runtimeContractJson !== current ||
-      meta.runtimeContractSha256 !== currentHash
+      meta.sessionCompatibilityJson !== current ||
+      meta.sessionCompatibilitySha256 !== currentHash
     ) {
-      const changed = runtimeContractDifferences(meta.runtimeContractJson, contract);
+      const changed = compatibilityContractDifferences(
+        meta.sessionCompatibilityJson,
+        currentContract,
+      );
       throw new SessionError(
-        "SESSION_RUNTIME_MISMATCH",
-        "compare_runtime_contract",
-        `Session runtime contract changed: ${changed.join(", ") || "stored contract is invalid"}.`,
+        "SESSION_COMPATIBILITY_MISMATCH",
+        "compare_session_compatibility",
+        `Session compatibility contract changed: ${changed.join(", ") || "stored contract is invalid"}.`,
         { sessionId: this.sessionId },
       );
     }
@@ -602,7 +843,7 @@ export class SessionStore implements SessionLedgerCommitter {
   writeMeasuredContextAnchor(anchor: MeasuredContextAnchor): void {
     this.requireOpen();
     assertMeasuredContextAnchor(anchor);
-    const revisionId = this.readMeta().activeRevisionId;
+    const revisionId = requireActiveRevisionId(this.readMeta());
     const now = this.clock();
     try {
       runTransaction(this.database, () => {
@@ -655,7 +896,7 @@ export class SessionStore implements SessionLedgerCommitter {
     if (state === undefined) {
       return undefined;
     }
-    if (state.revisionId !== this.readMeta().activeRevisionId) {
+    if (state.revisionId !== requireActiveRevisionId(this.readMeta())) {
       return undefined;
     }
     return state.anchor;
@@ -686,10 +927,82 @@ export class SessionStore implements SessionLedgerCommitter {
     }
   }
 
+  loadClosedTurnBoundaries(): readonly ClosedTurnBoundary[] {
+    this.requireOpen();
+    this.assertContextRevisionIdle();
+    const canonical = this.loadProtocolView();
+    this.validator.validate(canonical, { fullIntegrity: true });
+    return this.readClosedTurnBoundaries(canonical);
+  }
+
+  private readClosedTurnBoundaries(
+    canonical: ProtocolContextView,
+  ): readonly ClosedTurnBoundary[] {
+    const rows = this.database
+      .query("SELECT * FROM turns ORDER BY turn_number")
+      .all() as Array<Record<string, unknown>>;
+    const boundaries: ClosedTurnBoundary[] = [];
+    let expectedOrdinal = 2;
+    for (let index = 0; index < rows.length; index += 1) {
+      const row = requireItem(rows, index, "turn row");
+      const turnId = stringFromSql(row.turn_id, "turn_id") as TurnId;
+      const turnNumber = numberFromSql(row.turn_number, "turn_number");
+      const status = enumFromSql(
+        row.status,
+        ["completed", "failed", "cancelled", "interrupted"] as const,
+        "closed turn status",
+      );
+      const frames = canonical.frames.filter((frame) => frame.turnId === turnId);
+      const messages = canonical.messages.filter(
+        (message) => message.role !== "system" && message.turnId === turnId,
+      );
+      const firstMessage = messages[0];
+      const lastMessage = messages.at(-1);
+      let nextFrameOrdinal = expectedOrdinal;
+      for (const frame of frames) {
+        if (
+          frame.state !== "closed" ||
+          frame.firstOrdinal !== nextFrameOrdinal ||
+          frame.lastOrdinal === undefined
+        ) {
+          throw new Error(`Turn ${turnId} has an invalid closed frame boundary.`);
+        }
+        nextFrameOrdinal = frame.lastOrdinal + 1;
+      }
+      if (
+        turnNumber !== index + 1 ||
+        frames.length < 1 ||
+        messages.length < 1 ||
+        firstMessage?.role !== "user" ||
+        firstMessage.ordinal !== expectedOrdinal ||
+        lastMessage === undefined ||
+        nextFrameOrdinal !== lastMessage.ordinal + 1
+      ) {
+        throw new Error(`Turn ${turnId} has an invalid canonical boundary.`);
+      }
+      boundaries.push(
+        Object.freeze({
+          turnId,
+          turnNumber,
+          status,
+          firstOrdinal: expectedOrdinal,
+          lastOrdinal: lastMessage.ordinal,
+          frameCount: frames.length,
+          messageCount: messages.length,
+        }),
+      );
+      expectedOrdinal = lastMessage.ordinal + 1;
+    }
+    if (expectedOrdinal !== canonical.messages.length + 1) {
+      throw new Error("Closed turn boundaries do not cover canonical history.");
+    }
+    return Object.freeze(boundaries);
+  }
+
   commitSwapRevision(
     input: CommitSwapRevisionInput,
     options: CommitSwapRevisionOptions = {},
-  ): Extract<StoredContextRevisionV5, { kind: "swap_only" }> {
+  ): Extract<StoredContextRevisionV8, { kind: "swap_only" }> {
     this.requireOpen();
     assertCommitSwapRevisionInput(input);
     const now = this.clock();
@@ -702,8 +1015,8 @@ export class SessionStore implements SessionLedgerCommitter {
           baseRevision.revisionNumber !== input.expectedBaseRevisionNumber ||
           snapshot.canonical.messages.length !==
             input.expectedCanonicalThroughOrdinal ||
-          baseRevision.overrideManifestSha256 !==
-            input.expectedBaseOverrideManifestSha256
+          baseRevision.activeOverrideManifestSha256 !==
+            input.expectedBaseActiveOverrideManifestSha256
         ) {
           throw new Error("Context revision commit base is stale.");
         }
@@ -718,7 +1031,7 @@ export class SessionStore implements SessionLedgerCommitter {
           new Set(candidateOverrides.map((override) => override.messageId)).size !==
             candidateOverrides.length ||
           activeOverrideManifestHash(candidateOverrides) !==
-            input.nextOverrideManifestSha256
+            input.nextActiveOverrideManifestSha256
         ) {
           throw new Error("Candidate override manifest is invalid.");
         }
@@ -727,6 +1040,7 @@ export class SessionStore implements SessionLedgerCommitter {
           canonical: snapshot.canonical,
           activeOverrides: snapshot.activeOverrides,
           addedOverrides: input.addedOverrides,
+          activeSurface: snapshot.surface,
         });
         if (
           canonicalSequenceHash(
@@ -743,28 +1057,32 @@ export class SessionStore implements SessionLedgerCommitter {
         this.validateAddedOverrides(input.addedOverrides, snapshot.canonical);
 
         const revisionNumber = baseRevision.revisionNumber + 1;
-        const totalOverrideCount =
-          baseRevision.totalOverrideCount + input.addedOverrides.length;
+        const activeOverrideCount =
+          baseRevision.activeOverrideCount + input.addedOverrides.length;
         options.faultInjector?.("before_revision_insert");
         this.database
           .query(
             `INSERT INTO context_revisions (
               revision_id, session_id, revision_number, parent_revision_id, kind,
-              keep_from_ordinal, source_through_ordinal, added_override_count,
-              total_override_count, override_manifest_sha256,
+              surface_id, surface_sha256, keep_from_ordinal,
+              source_through_ordinal, added_override_count,
+              active_override_count, active_override_manifest_sha256,
               canonical_sequence_sha256, rendered_message_sha256, policy_version,
-              renderer_format, plan_sha256, created_at
-            ) VALUES (?, ?, ?, ?, 'swap_only', 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+              renderer_format, plan_sha256, change_manifest_sha256, created_at
+            ) VALUES (?, ?, ?, ?, 'swap_only', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
           )
           .run(
             input.revisionId,
             this.sessionId,
             revisionNumber,
             baseRevision.revisionId,
+            baseRevision.surfaceId,
+            baseRevision.surfaceSha256,
+            baseRevision.keepFromOrdinal,
             input.expectedCanonicalThroughOrdinal,
             input.addedOverrides.length,
-            totalOverrideCount,
-            input.nextOverrideManifestSha256,
+            activeOverrideCount,
+            input.nextActiveOverrideManifestSha256,
             input.canonicalSequenceSha256,
             input.renderedMessageSha256,
             input.policyVersion,
@@ -816,15 +1134,15 @@ export class SessionStore implements SessionLedgerCommitter {
             `SELECT co.* FROM context_overrides co
              JOIN context_revisions cr
                ON cr.revision_id = co.introduced_revision_id
-             WHERE cr.revision_number <= ?
+             WHERE cr.revision_number <= ? AND co.ordinal >= ?
              ORDER BY co.ordinal`,
           )
-          .all(revisionNumber)
+          .all(revisionNumber, baseRevision.keepFromOrdinal)
           .map(decodeStoredSwapOverride);
         if (
-          storedCandidateOverrides.length !== totalOverrideCount ||
+          storedCandidateOverrides.length !== activeOverrideCount ||
           activeOverrideManifestHash(storedCandidateOverrides) !==
-            input.nextOverrideManifestSha256
+            input.nextActiveOverrideManifestSha256
         ) {
           throw new Error("Stored candidate override readback is invalid.");
         }
@@ -856,7 +1174,7 @@ export class SessionStore implements SessionLedgerCommitter {
         return readback.revision;
       });
     } catch (error) {
-      if (this.readMeta().activeRevisionId !== input.expectedBaseRevisionId) {
+      if (requireActiveRevisionId(this.readMeta()) !== input.expectedBaseRevisionId) {
         throw new Error("Failed context revision transaction changed active state.", {
           cause: error,
         });
@@ -865,59 +1183,734 @@ export class SessionStore implements SessionLedgerCommitter {
     }
   }
 
-  private validateAddedOverrides(
-    overrides: readonly SwapOverride[],
-    canonical: ProtocolContextView,
-  ): void {
-    const messages = new Map(
-      canonical.messages.map((message) => [message.messageId, message] as const),
-    );
-    const results = new Map(
-      canonical.toolResults.map((result) => [result.toolMessageId, result] as const),
-    );
-    for (const override of overrides) {
-      const message = messages.get(override.messageId);
-      const result = results.get(override.messageId);
-      if (message?.role !== "tool" || result === undefined) {
-        throw new Error("Added context override does not target a tool result.");
-      }
-      const expected = this.swapRenderer.render({ message, result });
-      if (stableJsonStringify(expected) !== stableJsonStringify(override)) {
-        throw new Error("Added context override is not deterministic.");
-      }
-    }
-  }
-
-  markResumed(): number {
+  commitPrefixRetirementRevision(
+    input: CommitPrefixRetirementRevisionInput,
+    options: CommitPrefixRetirementRevisionOptions = {},
+  ): Extract<StoredContextRevisionV8, { kind: "prefix_retirement" }> {
     this.requireOpen();
+    assertCommitPrefixRetirementRevisionInput(input);
     const now = this.clock();
     try {
       return runTransaction(this.database, () => {
-        const meta = this.readMeta();
-        const next = meta.openCount + 1;
-        const updated = this.database
+        const snapshot = this.loadContextSnapshot();
+        const baseRevision = snapshot.revision;
+        if (
+          baseRevision.revisionId !== input.expectedBaseRevisionId ||
+          baseRevision.revisionNumber !== input.expectedBaseRevisionNumber ||
+          baseRevision.keepFromOrdinal !== input.expectedBaseKeepFromOrdinal ||
+          snapshot.canonical.messages.length !==
+            input.expectedCanonicalThroughOrdinal ||
+          snapshot.surface.surfaceSha256 !== input.expectedSurfaceSha256 ||
+          baseRevision.activeOverrideManifestSha256 !==
+            input.expectedBaseActiveOverrideManifestSha256
+        ) {
+          throw new Error("Prefix retirement commit base is stale.");
+        }
+        this.assertContextRevisionIdle();
+        const closedTurns = this.readClosedTurnBoundaries(snapshot.canonical);
+        const activeTurns = closedTurns.filter(
+          (turn) => turn.firstOrdinal >= baseRevision.keepFromOrdinal,
+        );
+        const nextBoundary = activeTurns.find(
+          (turn) => turn.firstOrdinal === input.nextKeepFromOrdinal,
+        );
+        const retainedTurns = activeTurns.filter(
+          (turn) => turn.firstOrdinal >= input.nextKeepFromOrdinal,
+        );
+        const retiredTurns = activeTurns.filter(
+          (turn) => turn.lastOrdinal < input.nextKeepFromOrdinal,
+        );
+        if (
+          nextBoundary === undefined ||
+          input.nextKeepFromOrdinal <= baseRevision.keepFromOrdinal ||
+          retainedTurns.length <
+            recallFirstRetirementPolicyV1.protectedRecentTurnCount ||
+          retiredTurns.length !== input.retiredTurnCount ||
+          retiredTurns.reduce((total, turn) => total + turn.frameCount, 0) !==
+            input.retiredFrameCount ||
+          retiredTurns.reduce((total, turn) => total + turn.messageCount, 0) !==
+            input.retiredMessageCount
+        ) {
+          throw new Error("Prefix retirement turn boundary is invalid.");
+        }
+
+        const active = this.revisionCompiler.compileActive(snapshot);
+        const nextActiveOverrides = snapshot.activeOverrides.filter(
+          (override) => override.ordinal >= input.nextKeepFromOrdinal,
+        );
+        const candidate = this.revisionCompiler.compileProspective({
+          active,
+          canonical: snapshot.canonical,
+          activeOverrides: snapshot.activeOverrides,
+          addedOverrides: [],
+          activeSurface: snapshot.surface,
+          keepFromOrdinal: input.nextKeepFromOrdinal,
+        });
+        if (
+          input.retiredThroughOrdinal !== input.nextKeepFromOrdinal - 1 ||
+          nextActiveOverrides.length !== input.nextActiveOverrideCount ||
+          activeOverrideManifestHash(nextActiveOverrides) !==
+            input.nextActiveOverrideManifestSha256 ||
+          canonicalSequenceHash(
+            snapshot.canonical,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.canonicalSequenceSha256 ||
+          renderedMessageHash(
+            candidate.entries,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.renderedMessageSha256
+        ) {
+          throw new Error("Prefix retirement candidate is invalid.");
+        }
+
+        const revisionNumber = baseRevision.revisionNumber + 1;
+        options.faultInjector?.("before_revision_insert");
+        this.database
           .query(
-            `UPDATE session_meta
-           SET open_count = ?, last_opened_at = ?, updated_at = ?,
-               last_closed_at = NULL, last_close_reason = NULL
-           WHERE singleton = 1 AND open_count = ?`,
+            `INSERT INTO context_revisions (
+              revision_id, session_id, revision_number, parent_revision_id, kind,
+              surface_id, surface_sha256, keep_from_ordinal,
+              source_through_ordinal, added_override_count, active_override_count,
+              active_override_manifest_sha256, canonical_sequence_sha256,
+              rendered_message_sha256, policy_version, renderer_format,
+              plan_sha256, change_manifest_sha256, retired_through_ordinal,
+              retired_turn_count, retired_frame_count, retired_message_count,
+              created_at
+            ) VALUES (?, ?, ?, ?, 'prefix_retirement', ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, NULL, ?, NULL, ?, ?, ?, ?, ?)`,
           )
-          .run(next, now, now, meta.openCount);
-        requireSingleChange(this.database, updated.changes, "increment open count");
-        return next;
+          .run(
+            input.revisionId,
+            this.sessionId,
+            revisionNumber,
+            baseRevision.revisionId,
+            baseRevision.surfaceId,
+            baseRevision.surfaceSha256,
+            input.nextKeepFromOrdinal,
+            input.expectedCanonicalThroughOrdinal,
+            input.nextActiveOverrideCount,
+            input.nextActiveOverrideManifestSha256,
+            input.canonicalSequenceSha256,
+            input.renderedMessageSha256,
+            input.policyVersion,
+            input.planHash,
+            input.retiredThroughOrdinal,
+            input.retiredTurnCount,
+            input.retiredFrameCount,
+            input.retiredMessageCount,
+            now,
+          );
+        options.faultInjector?.("after_revision_insert");
+
+        const storedActiveOverrides = this.database
+          .query(
+            `SELECT co.* FROM context_overrides co
+             JOIN context_revisions introduced
+               ON introduced.revision_id = co.introduced_revision_id
+             WHERE introduced.revision_number <= ? AND co.ordinal >= ?
+             ORDER BY co.ordinal`,
+          )
+          .all(revisionNumber, input.nextKeepFromOrdinal)
+          .map(decodeStoredSwapOverride);
+        if (
+          storedActiveOverrides.length !== input.nextActiveOverrideCount ||
+          activeOverrideManifestHash(storedActiveOverrides) !==
+            input.nextActiveOverrideManifestSha256
+        ) {
+          throw new Error("Prefix retirement override readback is invalid.");
+        }
+        options.faultInjector?.("after_override_readback");
+
+        this.database.query("DELETE FROM context_measurement_state").run();
+        options.faultInjector?.("after_measurement_delete");
+        const switched = this.database
+          .query(
+            `UPDATE session_meta SET active_revision_id = ?, updated_at = ?
+             WHERE singleton = 1 AND active_revision_id = ?`,
+          )
+          .run(input.revisionId, now, baseRevision.revisionId);
+        requireSingleChange(
+          this.database,
+          switched.changes,
+          "activate prefix retirement revision",
+        );
+        options.faultInjector?.("after_active_update");
+
+        const readback = this.loadContextSnapshot();
+        if (
+          readback.revision.kind !== "prefix_retirement" ||
+          readback.revision.revisionId !== input.revisionId ||
+          readback.revision.keepFromOrdinal !== input.nextKeepFromOrdinal ||
+          this.loadMeasuredContextState() !== undefined
+        ) {
+          throw new Error("Committed prefix retirement readback failed.");
+        }
+        options.faultInjector?.("after_snapshot_readback");
+        return readback.revision;
       });
     } catch (error) {
-      throw sessionWriteError("mark_resumed", this.sessionId, error);
+      if (requireActiveRevisionId(this.readMeta()) !== input.expectedBaseRevisionId) {
+        throw new Error("Failed prefix retirement changed active state.", {
+          cause: error,
+        });
+      }
+      throw sessionWriteError("commit_prefix_retirement", this.sessionId, error);
     }
   }
 
-  recoverInterruptedState(idFactory: RuntimeIdFactory): SessionRecoveryResult {
+  commitSurfaceRefresh(
+    input: CommitSurfaceRefreshInput,
+    options: CommitSurfaceRefreshOptions = {},
+  ): Extract<StoredContextRevisionV8, { kind: "surface_refresh" }> {
     this.requireOpen();
-    const view = this.loadProtocolView();
-    const openTurns = this.database
-      .query("SELECT turn_id FROM turns WHERE status = 'open' ORDER BY turn_number")
-      .all() as Array<{ turn_id: string }>;
-    const openFrames = view.frames.filter((frame) => frame.state === "open");
+    assertCommitSurfaceRefreshInput(input);
+    const now = this.clock();
+    try {
+      return runTransaction(this.database, () => {
+        const snapshot = this.loadContextSnapshot();
+        const baseRevision = snapshot.revision;
+        if (
+          baseRevision.revisionId !== input.expectedBaseRevisionId ||
+          baseRevision.revisionNumber !== input.expectedBaseRevisionNumber ||
+          snapshot.canonical.messages.length !==
+            input.expectedCanonicalThroughOrdinal ||
+          baseRevision.activeOverrideManifestSha256 !==
+            input.expectedBaseActiveOverrideManifestSha256
+        ) {
+          throw new Error("Context surface refresh base is stale.");
+        }
+        this.assertContextRevisionIdle();
+        validateStoredContextSurface(input.surface);
+        if (
+          input.surface.sessionId !== this.sessionId ||
+          input.surface.surfaceId === snapshot.surface.surfaceId ||
+          input.surface.surfaceSha256 === snapshot.surface.surfaceSha256
+        ) {
+          throw new Error("Context surface refresh does not introduce a new surface.");
+        }
+        const actualChanges = contextSurfaceChanges(snapshot.surface, input.surface);
+        if (
+          stableJsonStringify(actualChanges) !== stableJsonStringify(input.changes) ||
+          contextSurfaceChangeManifestHash(actualChanges) !==
+            input.changeManifestSha256 ||
+          !Object.values(actualChanges).some(Boolean)
+        ) {
+          throw new Error("Context surface refresh change manifest is invalid.");
+        }
+
+        const active = this.revisionCompiler.compileActive(snapshot);
+        const candidate = this.revisionCompiler.compileProspective({
+          active,
+          canonical: snapshot.canonical,
+          activeOverrides: snapshot.activeOverrides,
+          addedOverrides: [],
+          activeSurface: snapshot.surface,
+          surface: input.surface,
+        });
+        if (
+          canonicalSequenceHash(
+            snapshot.canonical,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.canonicalSequenceSha256 ||
+          renderedMessageHash(
+            candidate.entries,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.renderedMessageSha256
+        ) {
+          throw new Error("Candidate context surface prefix hash is invalid.");
+        }
+
+        const revisionNumber = baseRevision.revisionNumber + 1;
+        options.faultInjector?.("before_surface_insert");
+        insertContextSurface(this.database, input.surface);
+        options.faultInjector?.("after_surface_insert");
+        this.database
+          .query(
+            `INSERT INTO context_revisions (
+              revision_id, session_id, revision_number, parent_revision_id, kind,
+              surface_id, surface_sha256, keep_from_ordinal,
+              source_through_ordinal, added_override_count, active_override_count,
+              active_override_manifest_sha256, canonical_sequence_sha256,
+              rendered_message_sha256, policy_version, renderer_format,
+              plan_sha256, change_manifest_sha256, created_at
+            ) VALUES (?, ?, ?, ?, 'surface_refresh', ?, ?, ?, ?, 0, ?, ?, ?, ?, NULL, NULL, NULL, ?, ?)`,
+          )
+          .run(
+            input.revisionId,
+            this.sessionId,
+            revisionNumber,
+            baseRevision.revisionId,
+            input.surface.surfaceId,
+            input.surface.surfaceSha256,
+            baseRevision.keepFromOrdinal,
+            input.expectedCanonicalThroughOrdinal,
+            baseRevision.activeOverrideCount,
+            baseRevision.activeOverrideManifestSha256,
+            input.canonicalSequenceSha256,
+            input.renderedMessageSha256,
+            input.changeManifestSha256,
+            now,
+          );
+        options.faultInjector?.("after_revision_insert");
+
+        this.database.query("DELETE FROM context_measurement_state").run();
+        options.faultInjector?.("after_measurement_delete");
+        const switched = this.database
+          .query(
+            `UPDATE session_meta SET active_revision_id = ?, updated_at = ?
+             WHERE singleton = 1 AND active_revision_id = ?`,
+          )
+          .run(input.revisionId, now, baseRevision.revisionId);
+        requireSingleChange(
+          this.database,
+          switched.changes,
+          "activate context surface revision",
+        );
+        options.faultInjector?.("after_active_update");
+
+        const readback = this.loadContextSnapshot();
+        if (
+          readback.revision.kind !== "surface_refresh" ||
+          readback.revision.revisionId !== input.revisionId ||
+          readback.surface.surfaceId !== input.surface.surfaceId ||
+          this.loadMeasuredContextState() !== undefined
+        ) {
+          throw new Error("Committed context surface revision readback failed.");
+        }
+        return readback.revision;
+      });
+    } catch (error) {
+      if (requireActiveRevisionId(this.readMeta()) !== input.expectedBaseRevisionId) {
+        throw new Error("Failed context surface transaction changed active state.", {
+          cause: error,
+        });
+      }
+      throw sessionWriteError("commit_context_surface", this.sessionId, error);
+    }
+  }
+
+  commitSkillsUpdate(
+    input: CommitSkillsUpdateInput,
+    options: CommitSkillsUpdateOptions = {},
+  ): Extract<StoredContextRevisionV8, { kind: "skills_update" }> {
+    this.requireOpen();
+    assertCommitSkillsUpdateInput(input);
+    const now = this.clock();
+    try {
+      return runTransaction(this.database, () => {
+        const snapshot = this.loadContextSnapshot();
+        const baseRevision = snapshot.revision;
+        if (
+          baseRevision.revisionId !== input.expectedBaseRevisionId ||
+          baseRevision.revisionNumber !== input.expectedBaseRevisionNumber ||
+          snapshot.canonical.messages.length !==
+            input.expectedCanonicalThroughOrdinal ||
+          baseRevision.activeOverrideManifestSha256 !==
+            input.expectedBaseActiveOverrideManifestSha256
+        ) {
+          throw new Error("Agent Skills update base is stale.");
+        }
+        this.assertContextRevisionIdle();
+        validateStoredContextSurface(input.surface);
+
+        const surfaceChanged =
+          input.surface.surfaceSha256 !== snapshot.surface.surfaceSha256;
+        const actualChanges = contextSurfaceChanges(snapshot.surface, input.surface);
+        if (
+          input.surface.sessionId !== this.sessionId ||
+          stableJsonStringify(actualChanges) !== stableJsonStringify(input.changes) ||
+          contextSurfaceChangeManifestHash(actualChanges) !==
+            input.changeManifestSha256 ||
+          (surfaceChanged && input.surface.surfaceId === snapshot.surface.surfaceId) ||
+          (!surfaceChanged && input.surface.surfaceId !== snapshot.surface.surfaceId) ||
+          (!surfaceChanged && Object.values(actualChanges).some(Boolean))
+        ) {
+          throw new Error("Agent Skills surface change manifest is invalid.");
+        }
+
+        const unresolved = new Map(
+          this.loadSkillActivations(["pending", "dispatched"]).map((entry) => [
+            entry.activationMessageId,
+            entry,
+          ]),
+        );
+        if (
+          input.settlements.length !== input.addedOverrides.length ||
+          input.settlements.length !== unresolved.size ||
+          new Set(input.settlements.map((entry) => entry.activationMessageId)).size !==
+            input.settlements.length ||
+          skillActivationManifestSha256(input.settlements) !==
+            input.activationManifestSha256
+        ) {
+          throw new Error("Agent Skills settlement manifest is invalid.");
+        }
+        const canonicalMessages = new Map(
+          snapshot.canonical.messages.map((message) => [message.messageId, message]),
+        );
+        const providedOverrides = new Map(
+          input.addedOverrides.map((override) => [override.messageId, override]),
+        );
+        for (const settlement of input.settlements) {
+          const activation = unresolved.get(settlement.activationMessageId);
+          const message = canonicalMessages.get(settlement.activationMessageId);
+          const override = providedOverrides.get(settlement.activationMessageId);
+          if (
+            activation === undefined ||
+            message?.role !== "tool" ||
+            message.name !== "Skill" ||
+            override === undefined ||
+            settlement.name !== activation.name ||
+            (settlement.state === "promoted" &&
+              (activation.state !== "dispatched" ||
+                settlement.rejectionReason !== undefined)) ||
+            (settlement.state === "rejected" &&
+              (settlement.rejectionReason === undefined ||
+                settlement.rejectionReason.trim() === "" ||
+                settlement.rejectionReason.length > 256))
+          ) {
+            throw new Error(
+              `Agent Skill activation ${settlement.activationMessageId} cannot be settled.`,
+            );
+          }
+          const activeManifest = input.surface.activeSkills.find(
+            (entry) =>
+              entry.name === activation.name &&
+              entry.activationMessageId === activation.activationMessageId,
+          );
+          if (
+            (settlement.state === "promoted" && activeManifest === undefined) ||
+            (settlement.state === "rejected" && activeManifest !== undefined)
+          ) {
+            throw new Error("Agent Skills active manifest does not match settlements.");
+          }
+          const expected = renderSkillActivationReceipt({
+            message: {
+              messageId: message.messageId,
+              frameId: message.frameId,
+              ordinal: message.ordinal,
+              content: message.content,
+              contentSha256: message.contentSha256,
+            },
+            name: activation.name,
+            outcome:
+              settlement.state === "promoted"
+                ? "promoted"
+                : settlement.rejectionReason === "unavailable"
+                  ? "unavailable"
+                  : "rejected",
+          });
+          if (stableJsonStringify(expected) !== stableJsonStringify(override)) {
+            throw new Error("Agent Skill activation receipt is not deterministic.");
+          }
+        }
+
+        const active = this.revisionCompiler.compileActive(snapshot);
+        const candidateOverrides = [
+          ...snapshot.activeOverrides,
+          ...input.addedOverrides,
+        ];
+        if (
+          new Set(candidateOverrides.map((override) => override.messageId)).size !==
+            candidateOverrides.length ||
+          activeOverrideManifestHash(candidateOverrides) !==
+            input.nextActiveOverrideManifestSha256
+        ) {
+          throw new Error("Agent Skills override manifest is invalid.");
+        }
+        const candidate = this.revisionCompiler.compileProspective({
+          active,
+          canonical: snapshot.canonical,
+          activeOverrides: snapshot.activeOverrides,
+          addedOverrides: input.addedOverrides,
+          activeSurface: snapshot.surface,
+          ...(surfaceChanged ? { surface: input.surface } : {}),
+          allowCombinedSurfaceAndOverrides: true,
+        });
+        if (
+          canonicalSequenceHash(
+            snapshot.canonical,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.canonicalSequenceSha256 ||
+          renderedMessageHash(
+            candidate.entries,
+            input.expectedCanonicalThroughOrdinal,
+          ) !== input.renderedMessageSha256
+        ) {
+          throw new Error("Agent Skills compiled context hashes are invalid.");
+        }
+
+        options.faultInjector?.("before_surface_insert");
+        if (surfaceChanged) {
+          insertContextSurface(this.database, input.surface);
+        }
+        options.faultInjector?.("after_surface_insert");
+        const revisionNumber = baseRevision.revisionNumber + 1;
+        const activeOverrideCount =
+          baseRevision.activeOverrideCount + input.addedOverrides.length;
+        this.database
+          .query(
+            `INSERT INTO context_revisions (
+              revision_id, session_id, revision_number, parent_revision_id, kind,
+              surface_id, surface_sha256, keep_from_ordinal,
+              source_through_ordinal, added_override_count, active_override_count,
+              active_override_manifest_sha256, canonical_sequence_sha256,
+              rendered_message_sha256, policy_version, renderer_format,
+              plan_sha256, change_manifest_sha256, activation_manifest_sha256,
+              retired_through_ordinal, retired_turn_count, retired_frame_count,
+              retired_message_count, created_at
+            ) VALUES (?, ?, ?, ?, 'skills_update', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, NULL, NULL, NULL, NULL, ?)`,
+          )
+          .run(
+            input.revisionId,
+            this.sessionId,
+            revisionNumber,
+            baseRevision.revisionId,
+            input.surface.surfaceId,
+            input.surface.surfaceSha256,
+            baseRevision.keepFromOrdinal,
+            input.expectedCanonicalThroughOrdinal,
+            input.addedOverrides.length,
+            activeOverrideCount,
+            input.nextActiveOverrideManifestSha256,
+            input.canonicalSequenceSha256,
+            input.renderedMessageSha256,
+            SKILL_POLICY_VERSION,
+            SKILL_ACTIVATION_RECEIPT_FORMAT,
+            input.changeManifestSha256,
+            input.activationManifestSha256,
+            now,
+          );
+        options.faultInjector?.("after_revision_insert");
+
+        for (let index = 0; index < input.addedOverrides.length; index += 1) {
+          const override = requireItem(
+            input.addedOverrides,
+            index,
+            "Agent Skill receipt override",
+          );
+          this.database
+            .query(
+              `INSERT INTO context_overrides (
+                introduced_revision_id, session_id, message_id, frame_id, ordinal,
+                representation, renderer_format, source, original_content_sha256,
+                rendered_content, rendered_content_sha256, original_bytes,
+                rendered_bytes, byte_savings, created_at
+              ) VALUES (?, ?, ?, ?, ?, 'swapped', ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            )
+            .run(
+              input.revisionId,
+              this.sessionId,
+              override.messageId,
+              override.frameId,
+              override.ordinal,
+              SKILL_ACTIVATION_RECEIPT_FORMAT,
+              override.source,
+              override.originalContentSha256,
+              override.renderedContent,
+              override.renderedContentSha256,
+              override.originalBytes,
+              override.renderedBytes,
+              override.byteSavings,
+              now,
+            );
+          if (index === 0) {
+            options.faultInjector?.("after_first_override_insert");
+          }
+        }
+        options.faultInjector?.("after_overrides_insert");
+
+        for (const settlement of input.settlements) {
+          const activation = unresolved.get(settlement.activationMessageId)!;
+          const updated =
+            settlement.state === "promoted"
+              ? this.database
+                  .query(
+                    `UPDATE skill_activations
+                     SET state = 'promoted', settled_revision_id = ?, updated_at = ?
+                     WHERE activation_message_id = ? AND state = 'dispatched'`,
+                  )
+                  .run(input.revisionId, now, settlement.activationMessageId)
+              : this.database
+                  .query(
+                    `UPDATE skill_activations
+                     SET state = 'rejected', settled_revision_id = ?, rejection_reason = ?, updated_at = ?
+                     WHERE activation_message_id = ? AND state = ?`,
+                  )
+                  .run(
+                    input.revisionId,
+                    settlement.rejectionReason!,
+                    now,
+                    settlement.activationMessageId,
+                    activation.state,
+                  );
+          requireSingleChange(
+            this.database,
+            updated.changes,
+            `settle Agent Skill activation ${settlement.activationMessageId}`,
+          );
+        }
+        options.faultInjector?.("after_activations_update");
+
+        this.database.query("DELETE FROM context_measurement_state").run();
+        options.faultInjector?.("after_measurement_delete");
+        const switched = this.database
+          .query(
+            `UPDATE session_meta SET active_revision_id = ?, updated_at = ?
+             WHERE singleton = 1 AND active_revision_id = ?`,
+          )
+          .run(input.revisionId, now, baseRevision.revisionId);
+        requireSingleChange(
+          this.database,
+          switched.changes,
+          "activate Agent Skills context revision",
+        );
+        options.faultInjector?.("after_active_update");
+
+        const readback = this.loadContextSnapshot();
+        if (
+          readback.revision.kind !== "skills_update" ||
+          readback.revision.revisionId !== input.revisionId ||
+          readback.surface.surfaceId !== input.surface.surfaceId ||
+          this.loadMeasuredContextState() !== undefined ||
+          this.loadSkillActivations(["pending", "dispatched"]).some((entry) =>
+            input.settlements.some(
+              (settlement) =>
+                settlement.activationMessageId === entry.activationMessageId,
+            ),
+          )
+        ) {
+          throw new Error("Committed Agent Skills update readback failed.");
+        }
+        return readback.revision;
+      });
+    } catch (error) {
+      if (requireActiveRevisionId(this.readMeta()) !== input.expectedBaseRevisionId) {
+        throw new Error("Failed Agent Skills transaction changed active state.", {
+          cause: error,
+        });
+      }
+      throw sessionWriteError("commit_skills_update", this.sessionId, error);
+    }
+  }
+
+  private validateAddedOverrides(
+    overrides: readonly SwapOverride[],
+    canonical: ProtocolContextView,
+  ): void {
+    const messages = new Map(
+      canonical.messages.map((message) => [message.messageId, message] as const),
+    );
+    const results = new Map(
+      canonical.toolResults.map((result) => [result.toolMessageId, result] as const),
+    );
+    for (const override of overrides) {
+      const message = messages.get(override.messageId);
+      const result = results.get(override.messageId);
+      if (message?.role !== "tool" || result === undefined) {
+        throw new Error("Added context override does not target a tool result.");
+      }
+      const expected = this.swapRenderer.render({ message, result });
+      if (stableJsonStringify(expected) !== stableJsonStringify(override)) {
+        throw new Error("Added context override is not deterministic.");
+      }
+    }
+  }
+
+  loadSkillActivations(
+    states?: readonly StoredSkillActivation["state"][],
+  ): readonly StoredSkillActivation[] {
+    this.requireOpen();
+    const rows = this.database
+      .query(
+        `SELECT sa.*, m.ordinal AS activation_ordinal
+         FROM skill_activations sa
+         JOIN messages m ON m.message_id = sa.activation_message_id
+         ORDER BY m.ordinal`,
+      )
+      .all()
+      .map(decodeSkillActivation);
+    const filtered =
+      states === undefined ? rows : rows.filter((row) => states.includes(row.state));
+    return Object.freeze(filtered);
+  }
+
+  markSkillActivationsDispatched(input: {
+    iterationId: IterationId;
+    activationMessageIds: readonly MessageId[];
+  }): readonly StoredSkillActivation[] {
+    this.requireOpen();
+    if (input.activationMessageIds.length === 0) {
+      return Object.freeze([]);
+    }
+    if (
+      new Set(input.activationMessageIds).size !== input.activationMessageIds.length
+    ) {
+      throw new Error("Agent Skill dispatch contains duplicate activation messages.");
+    }
+    const now = this.clock();
+    try {
+      return runTransaction(this.database, () => {
+        const iteration = this.requireIterationRow(input.iterationId);
+        if (iteration.outcome !== "open") {
+          throw new Error(`Iteration ${input.iterationId} is not open for dispatch.`);
+        }
+        for (const messageId of input.activationMessageIds) {
+          const updated = this.database
+            .query(
+              `UPDATE skill_activations
+               SET state = 'dispatched', dispatched_iteration_id = ?, updated_at = ?
+               WHERE activation_message_id = ? AND session_id = ? AND state = 'pending'`,
+            )
+            .run(input.iterationId, now, messageId, this.sessionId);
+          requireSingleChange(
+            this.database,
+            updated.changes,
+            `dispatch Agent Skill activation ${messageId}`,
+          );
+        }
+        this.touch(now);
+        const dispatched = this.loadSkillActivations(["dispatched"]).filter((row) =>
+          input.activationMessageIds.includes(row.activationMessageId),
+        );
+        if (dispatched.length !== input.activationMessageIds.length) {
+          throw new Error("Agent Skill dispatch readback failed.");
+        }
+        return Object.freeze(dispatched);
+      });
+    } catch (error) {
+      throw sessionWriteError("dispatch_skill_activations", this.sessionId, error);
+    }
+  }
+
+  markResumed(): number {
+    this.requireOpen();
+    const now = this.clock();
+    try {
+      return runTransaction(this.database, () => {
+        const meta = this.readMeta();
+        const next = meta.openCount + 1;
+        const updated = this.database
+          .query(
+            `UPDATE session_meta
+           SET open_count = ?, last_opened_at = ?, updated_at = ?,
+               last_closed_at = NULL, last_close_reason = NULL
+           WHERE singleton = 1 AND open_count = ?`,
+          )
+          .run(next, now, now, meta.openCount);
+        requireSingleChange(this.database, updated.changes, "increment open count");
+        return next;
+      });
+    } catch (error) {
+      throw sessionWriteError("mark_resumed", this.sessionId, error);
+    }
+  }
+
+  recoverInterruptedState(idFactory: RuntimeIdFactory): SessionRecoveryResult {
+    this.requireOpen();
+    const view = this.loadProtocolView();
+    const openTurns = this.database
+      .query("SELECT turn_id FROM turns WHERE status = 'open' ORDER BY turn_number")
+      .all() as Array<{ turn_id: string }>;
+    const openFrames = view.frames.filter((frame) => frame.state === "open");
     if (openTurns.length === 0 && openFrames.length === 0) {
       return {
         syntheticCompletionCount: 0,
@@ -1091,6 +2084,7 @@ export class SessionStore implements SessionLedgerCommitter {
 
   loadProtocolView(): ProtocolContextView {
     this.requireOpen();
+    const imageAttachments = loadMessageImageAttachments(this.database);
     const frames = this.database
       .query("SELECT * FROM protocol_frames ORDER BY first_ordinal")
       .all()
@@ -1098,7 +2092,16 @@ export class SessionStore implements SessionLedgerCommitter {
     const messages = this.database
       .query("SELECT * FROM messages ORDER BY ordinal")
       .all()
-      .map(decodeMessage);
+      .map((row) => {
+        const record = recordFromSql(row, "message");
+        const messageId = stringFromSql(record.message_id, "message_id");
+        const message = decodeMessage(row, imageAttachments.get(messageId));
+        imageAttachments.delete(messageId);
+        return message;
+      });
+    if (imageAttachments.size > 0) {
+      throw new Error("Image attachment rows reference unknown messages.");
+    }
     const toolResults = this.database
       .query(
         `SELECT tr.* FROM tool_results tr
@@ -1116,13 +2119,43 @@ export class SessionStore implements SessionLedgerCommitter {
     });
   }
 
-  loadContextSnapshot(): StoredContextSnapshotV5 {
+  async verifyImageAssetFiles(): Promise<void> {
+    this.requireOpen();
+    const distinct = new Map<string, ImageAssetRef>();
+    for (const message of this.loadProtocolView().messages) {
+      if (message.role !== "user") {
+        continue;
+      }
+      for (const attachment of message.attachments ?? []) {
+        const previous = distinct.get(attachment.assetId);
+        const asset = imageAssetRefFromAttachment(attachment);
+        if (
+          previous !== undefined &&
+          stableJsonStringify(previous) !== stableJsonStringify(asset)
+        ) {
+          throw new Error(
+            `Conflicting metadata for image asset ${attachment.assetId}.`,
+          );
+        }
+        distinct.set(attachment.assetId, asset);
+      }
+    }
+    if (distinct.size === 0) {
+      return;
+    }
+    const store = await ImageAssetStore.open({ workspaceRoot: this.workspaceRoot });
+    for (const asset of distinct.values()) {
+      await store.verify(asset);
+    }
+  }
+
+  loadContextSnapshot(): StoredContextSnapshotV8 {
     this.requireOpen();
     const meta = this.readMeta();
     try {
       if (
         meta.sessionId !== this.sessionId ||
-        meta.schemaFingerprint !== SESSION_SCHEMA_V5_FINGERPRINT
+        meta.schemaFingerprint !== SESSION_SCHEMA_V9_FINGERPRINT
       ) {
         throw new Error("Session metadata identity or schema fingerprint changed.");
       }
@@ -1168,7 +2201,7 @@ export class SessionStore implements SessionLedgerCommitter {
     }
   }
 
-  readMeta(): StoredSessionMetaV5 {
+  readMeta(): StoredSessionMetaV9 {
     this.requireOpen();
     const rows = this.database.query("SELECT * FROM session_meta").all();
     if (rows.length !== 1) {
@@ -1182,7 +2215,7 @@ export class SessionStore implements SessionLedgerCommitter {
     return decodeMeta(rows[0], this.sessionId);
   }
 
-  readStoredSystemPrompt(): string {
+  readCreationSystemPrompt(): string {
     this.requireOpen();
     try {
       const frames = this.database
@@ -1235,8 +2268,8 @@ export class SessionStore implements SessionLedgerCommitter {
       }
       throw new SessionError(
         "SESSION_RECOVERY_FAILED",
-        "read_stored_system_prompt",
-        "Stored system prompt is missing or invalid.",
+        "read_creation_system_prompt",
+        "Creation system prompt is missing or invalid.",
         { sessionId: this.sessionId, cause: error },
       );
     }
@@ -1246,6 +2279,56 @@ export class SessionStore implements SessionLedgerCommitter {
     return this.readMeta().projectInstruction;
   }
 
+  validateCreatingState(): void {
+    this.requireOpen();
+    const meta = this.readMeta();
+    if (
+      meta.initializationState !== "creating" ||
+      meta.activeRevisionId !== null ||
+      meta.sessionCompatibilityJson !== null ||
+      meta.sessionCompatibilitySha256 !== null
+    ) {
+      throw new SessionError(
+        "SESSION_INTEGRITY_FAILED",
+        "validate_creating_store",
+        "Creating session metadata is invalid.",
+        { sessionId: this.sessionId },
+      );
+    }
+    this.readCreationSystemPrompt();
+    const counts = this.database
+      .query(
+        `SELECT
+          (SELECT COUNT(*) FROM context_surfaces) AS surfaces,
+          (SELECT COUNT(*) FROM context_revisions) AS revisions,
+          (SELECT COUNT(*) FROM turns) AS turns`,
+      )
+      .get() as Record<string, unknown> | null;
+    if (
+      counts === null ||
+      numberFromSql(counts.surfaces, "surfaces") !== 0 ||
+      numberFromSql(counts.revisions, "revisions") !== 0 ||
+      numberFromSql(counts.turns, "turns") !== 0
+    ) {
+      throw new SessionError(
+        "SESSION_INTEGRITY_FAILED",
+        "validate_creating_store",
+        "Creating session contains finalized or turn state.",
+        { sessionId: this.sessionId },
+      );
+    }
+    const view = this.loadProtocolView();
+    this.validator.validate(view, { fullIntegrity: true });
+    if (view.messages.length !== 1 || view.frames.length !== 1) {
+      throw new SessionError(
+        "SESSION_INTEGRITY_FAILED",
+        "validate_creating_store",
+        "Creating session must contain only its creation system frame.",
+        { sessionId: this.sessionId },
+      );
+    }
+  }
+
   nextTurnNumber(): number {
     return this.readMeta().nextTurnNumber;
   }
@@ -1254,7 +2337,9 @@ export class SessionStore implements SessionLedgerCommitter {
     const meta = this.readMeta();
     if (
       meta.sessionId !== this.sessionId ||
-      meta.schemaFingerprint !== SESSION_SCHEMA_V5_FINGERPRINT
+      meta.schemaFingerprint !== SESSION_SCHEMA_V9_FINGERPRINT ||
+      meta.initializationState !== "ready" ||
+      meta.activeRevisionId === null
     ) {
       throw new SessionError(
         "SESSION_SCHEMA_INVALID",
@@ -1263,15 +2348,16 @@ export class SessionStore implements SessionLedgerCommitter {
         { sessionId: this.sessionId },
       );
     }
-    this.readStoredSystemPrompt();
-    const view = this.loadProtocolView();
     try {
+      this.readCreationSystemPrompt();
+      const view = this.loadProtocolView();
       this.validator.validate(view, {
         allowOpenTail: options.allowOpenTail,
         fullIntegrity: true,
       });
       this.loadValidatedContextSnapshot(meta, view);
       this.validateCounters(meta, view);
+      return view;
     } catch (error) {
       if (error instanceof SessionError) {
         throw error;
@@ -1297,7 +2383,121 @@ export class SessionStore implements SessionLedgerCommitter {
         { sessionId: this.sessionId, cause: error },
       );
     }
-    return view;
+  }
+
+  async cloneTo(input: CloneSessionStoreInput): Promise<void> {
+    this.requireOpen();
+    if (input.targetSessionId === this.sessionId) {
+      throw new Error("Session clone target must differ from the source session.");
+    }
+
+    const sourceView = this.validateAll({ allowOpenTail: false });
+    const sourceMeta = this.readMeta();
+    const sessionsRoot = path.dirname(this.sessionDirectory);
+    await validateSessionsRoot(sessionsRoot, this.sessionId);
+    const targetDirectory = safeSessionDirectory(sessionsRoot, input.targetSessionId);
+    await assertPathMissing(targetDirectory, input.targetSessionId);
+
+    const stagingDirectory = path.join(sessionsRoot, `.cloning-${randomUUID()}`);
+    const stagingDatabasePath = path.join(stagingDirectory, "session.sqlite");
+    let stagingDatabase: Database | undefined;
+    let published = false;
+
+    try {
+      await mkdir(stagingDirectory, { mode: 0o700 });
+      await chmod(stagingDirectory, 0o700);
+      input.faultInjector?.("after_staging_mkdir");
+      this.database.query("VACUUM INTO ?").run(stagingDatabasePath);
+      await chmod(stagingDatabasePath, 0o600);
+      input.faultInjector?.("after_snapshot");
+
+      stagingDatabase = openWritableDatabase(stagingDatabasePath);
+      verifySessionSchema(stagingDatabase, this.sessionId);
+      dropSessionCloneTriggers(stagingDatabase);
+      input.faultInjector?.("after_trigger_drop");
+
+      const targetCanonical = rekeyProtocolView(sourceView, input.targetSessionId);
+      runTransaction(stagingDatabase, () => {
+        stagingDatabase!.exec("PRAGMA defer_foreign_keys = ON");
+        for (const table of SESSION_SCOPED_TABLES) {
+          stagingDatabase!
+            .query(`UPDATE ${table} SET session_id = ? WHERE session_id = ?`)
+            .run(input.targetSessionId, this.sessionId);
+        }
+        rekeyStoredToolCalls(stagingDatabase!, input.targetSessionId);
+        input.faultInjector?.("after_identity_update");
+
+        rewriteCloneRevisionHashes(stagingDatabase!, targetCanonical);
+        input.faultInjector?.("after_revision_hash_rewrite");
+
+        if (stagingDatabase!.query("PRAGMA foreign_key_check").all().length !== 0) {
+          throw new Error("Cloned session identity re-key broke foreign keys.");
+        }
+      });
+
+      reinstallSessionCloneTriggers(stagingDatabase);
+      input.faultInjector?.("after_trigger_reinstall");
+      verifySessionSchema(stagingDatabase, input.targetSessionId);
+      verifySqliteIntegrity(stagingDatabase, input.targetSessionId);
+      verifyRecallIndex(stagingDatabase, input.targetSessionId);
+      input.faultInjector?.("after_recall_validation");
+      const clonedStore = new SessionStore(stagingDatabase, this.lease, {
+        sessionId: input.targetSessionId,
+        workspaceRoot: this.workspaceRoot,
+        sessionDirectory: stagingDirectory,
+        databasePath: stagingDatabasePath,
+        clock: this.clock,
+      });
+      clonedStore.validateAll({ allowOpenTail: false });
+      await clonedStore.verifyImageAssetFiles();
+
+      await cloneDiagnosticFiles({
+        sourceDirectory: this.sessionDirectory,
+        stagingDirectory,
+        sourceSessionId: this.sessionId,
+        targetSessionId: input.targetSessionId,
+        nextEventSequence: sourceMeta.nextEventSequence,
+        faultInjector: input.faultInjector,
+      });
+
+      stagingDatabase.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+      const standaloneJournal = stagingDatabase
+        .query("PRAGMA journal_mode = DELETE")
+        .get() as Record<string, unknown> | null;
+      if (String(standaloneJournal?.journal_mode).toLowerCase() !== "delete") {
+        throw new Error("Cloned session database did not leave WAL mode.");
+      }
+      stagingDatabase.close();
+      stagingDatabase = undefined;
+      await unlinkIfExists(`${stagingDatabasePath}-wal`);
+      await unlinkIfExists(`${stagingDatabasePath}-shm`);
+      await validateSecureDirectory(stagingDirectory, input.targetSessionId);
+      await validateSecureFile(stagingDatabasePath, input.targetSessionId);
+      await validateSecureOptionalFile(
+        path.join(stagingDirectory, "events.jsonl"),
+        input.targetSessionId,
+      );
+      await validateSecureOptionalFile(
+        path.join(stagingDirectory, "observations.md"),
+        input.targetSessionId,
+      );
+      input.faultInjector?.("after_artifact_validation");
+      await assertPathMissing(targetDirectory, input.targetSessionId);
+      input.faultInjector?.("before_publish_rename");
+      await rename(stagingDirectory, targetDirectory);
+      published = true;
+    } finally {
+      if (stagingDatabase !== undefined) {
+        try {
+          stagingDatabase.close();
+        } catch {
+          // Preserve the clone failure.
+        }
+      }
+      if (!published) {
+        await removeKnownInitializationFiles(stagingDirectory).catch(() => undefined);
+      }
+    }
   }
 
   async close(reason: SessionCloseReason): Promise<void> {
@@ -1404,6 +2604,24 @@ export class SessionStore implements SessionLedgerCommitter {
     now: string,
   ): void {
     const meta = this.readMeta();
+    if (mutation.admissionBase !== undefined) {
+      const snapshot = this.loadContextSnapshot();
+      const head = snapshot.canonical.messages.at(-1);
+      const base = mutation.admissionBase;
+      if (
+        head === undefined ||
+        base.canonicalMessageCount !== snapshot.canonical.messages.length ||
+        base.canonicalHeadMessageId !== head.messageId ||
+        base.canonicalHeadContentSha256 !== head.contentSha256 ||
+        base.activeRevisionId !== snapshot.revision.revisionId ||
+        base.activeRevisionNumber !== snapshot.revision.revisionNumber ||
+        base.surfaceSha256 !== snapshot.surface.surfaceSha256 ||
+        base.sessionCompatibilitySha256 !== meta.sessionCompatibilitySha256 ||
+        base.nextTurnNumber !== meta.nextTurnNumber
+      ) {
+        throw new AdmissionStaleError();
+      }
+    }
     if (
       meta.initializationState !== "ready" ||
       meta.nextTurnNumber !== mutation.turn.turnNumber
@@ -1477,14 +2695,11 @@ export class SessionStore implements SessionLedgerCommitter {
       throw new Error(`Frame ${mutation.frameBefore.frameId} is not open.`);
     }
     for (let index = 0; index < mutation.messages.length; index += 1) {
-      insertMessage(
-        this.database,
-        requireItem(mutation.messages, index, "tool message"),
-      );
-      insertToolResult(
-        this.database,
-        requireItem(mutation.toolResults, index, "tool result"),
-      );
+      const message = requireItem(mutation.messages, index, "tool message");
+      const result = requireItem(mutation.toolResults, index, "tool result");
+      insertMessage(this.database, message);
+      insertToolResult(this.database, result);
+      insertPendingSkillActivation(this.database, message, result, now);
     }
     if (mutation.frameAfter.state === "closed") {
       const updated = this.database
@@ -1594,9 +2809,23 @@ export class SessionStore implements SessionLedgerCommitter {
   }
 
   private loadValidatedContextSnapshot(
-    meta: StoredSessionMetaV5,
+    meta: StoredSessionMetaV9,
     canonical: ProtocolContextView,
-  ): StoredContextSnapshotV5 {
+  ): StoredContextSnapshotV8 {
+    const activeRevisionId = requireActiveRevisionId(meta);
+    const surfaces = this.database
+      .query("SELECT * FROM context_surfaces ORDER BY rowid")
+      .all()
+      .map(decodeContextSurface);
+    const surfacesById = new Map<ContextSurfaceId, StoredContextSurfaceV8>();
+    for (const surface of surfaces) {
+      validateStoredContextSurface(surface);
+      if (surface.sessionId !== this.sessionId || surfacesById.has(surface.surfaceId)) {
+        throw new Error("Context surface identity is invalid or duplicated.");
+      }
+      surfacesById.set(surface.surfaceId, surface);
+    }
+
     const revisions = this.database
       .query("SELECT * FROM context_revisions ORDER BY revision_number")
       .all()
@@ -1609,13 +2838,28 @@ export class SessionStore implements SessionLedgerCommitter {
     for (let index = 0; index < revisions.length; index += 1) {
       const revision = requireItem(revisions, index, "context revision");
       const previous = revisions[index - 1];
+      const surface = surfacesById.get(revision.surfaceId);
       if (
         revision.sessionId !== this.sessionId ||
         revision.revisionNumber !== index + 1 ||
+        surface === undefined ||
+        surface.surfaceSha256 !== revision.surfaceSha256 ||
         (index === 0
           ? revision.kind !== "initial_full" || revision.parentRevisionId !== null
-          : revision.kind !== "swap_only" ||
-            revision.parentRevisionId !== previous?.revisionId)
+          : revision.kind === "initial_full" ||
+            revision.parentRevisionId !== previous?.revisionId) ||
+        ((revision.kind === "swap_only" || revision.kind === "prefix_retirement") &&
+          revision.surfaceId !== previous?.surfaceId) ||
+        (revision.kind === "surface_refresh" &&
+          revision.surfaceId === previous?.surfaceId) ||
+        (previous !== undefined &&
+          (revision.keepFromOrdinal < previous.keepFromOrdinal ||
+            ((revision.kind === "swap_only" ||
+              revision.kind === "surface_refresh" ||
+              revision.kind === "skills_update") &&
+              revision.keepFromOrdinal !== previous.keepFromOrdinal) ||
+            (revision.kind === "prefix_retirement" &&
+              revision.keepFromOrdinal <= previous.keepFromOrdinal)))
       ) {
         throw new Error("Context revision chain is not linear and contiguous.");
       }
@@ -1632,15 +2876,36 @@ export class SessionStore implements SessionLedgerCommitter {
       }
       revisionNumberById.set(revision.revisionId, revision.revisionNumber);
     }
+    const introducedSurfaceIds = new Set(
+      revisions.flatMap((revision, index) => {
+        const previous = revisions[index - 1];
+        return revision.kind === "initial_full" ||
+          revision.kind === "surface_refresh" ||
+          (revision.kind === "skills_update" &&
+            revision.surfaceId !== previous?.surfaceId)
+          ? [revision.surfaceId]
+          : [];
+      }),
+    );
+    if (
+      introducedSurfaceIds.size !== surfaces.length ||
+      surfaces.some((surface) => !introducedSurfaceIds.has(surface.surfaceId))
+    ) {
+      throw new Error("Context surface chain contains an orphan or duplicate surface.");
+    }
 
     const activeRevision = requireItem(
       revisions,
       revisions.length - 1,
       "active context revision",
     );
-    if (activeRevision.revisionId !== meta.activeRevisionId) {
+    if (activeRevision.revisionId !== activeRevisionId) {
       throw new Error("Active context revision is not the latest committed revision.");
     }
+    const activeSurface = surfacesById.get(activeRevision.surfaceId);
+    if (activeSurface === undefined) {
+      throw new Error("Active context revision surface is missing.");
+    }
 
     const overrides = this.database
       .query(
@@ -1652,27 +2917,117 @@ export class SessionStore implements SessionLedgerCommitter {
       .all()
       .map(decodeStoredSwapOverride);
     this.validateStoredOverrides(overrides, canonical, revisions, revisionNumberById);
+    this.validateSkillActivationRows(canonical, revisions, overrides, surfaces);
 
-    let cumulativeCount = 0;
     for (const revision of revisions) {
+      const surface = surfacesById.get(revision.surfaceId);
+      if (surface === undefined) {
+        throw new Error(`Context revision ${revision.revisionId} has no surface.`);
+      }
       const activeOverrides = overrides.filter(
         (override) =>
           (revisionNumberById.get(override.introducedRevisionId) ??
-            Number.POSITIVE_INFINITY) <= revision.revisionNumber,
+            Number.POSITIVE_INFINITY) <= revision.revisionNumber &&
+          override.ordinal >= revision.keepFromOrdinal,
       );
       const introducedCount = overrides.filter(
         (override) => override.introducedRevisionId === revision.revisionId,
       ).length;
-      cumulativeCount += introducedCount;
       if (
         introducedCount !== revision.addedOverrideCount ||
-        cumulativeCount !== revision.totalOverrideCount ||
-        activeOverrideManifestHash(activeOverrides) !== revision.overrideManifestSha256
+        activeOverrides.length !== revision.activeOverrideCount ||
+        activeOverrideManifestHash(activeOverrides) !==
+          revision.activeOverrideManifestSha256
       ) {
         throw new Error(
           `Context revision ${revision.revisionId} override manifest is invalid.`,
         );
       }
+      if (
+        revision.kind === "surface_refresh" &&
+        previousRevision(revisions, revision)?.activeOverrideManifestSha256 !==
+          revision.activeOverrideManifestSha256
+      ) {
+        throw new Error(
+          `Context surface revision ${revision.revisionId} changed overrides.`,
+        );
+      }
+      if (revision.kind === "skills_update") {
+        const parent = previousRevision(revisions, revision);
+        const parentSurface =
+          parent === undefined ? undefined : surfacesById.get(parent.surfaceId);
+        const settlements = this.loadSkillActivations().filter(
+          (activation) => activation.settledRevisionId === revision.revisionId,
+        );
+        if (
+          parentSurface === undefined ||
+          contextSurfaceChangeManifestHash(
+            contextSurfaceChanges(parentSurface, surface),
+          ) !== revision.changeManifestSha256 ||
+          settlements.length !== revision.addedOverrideCount ||
+          skillActivationManifestSha256(
+            settlements.map((activation) => ({
+              activationMessageId: activation.activationMessageId,
+              name: activation.name,
+              state: activation.state === "promoted" ? "promoted" : "rejected",
+              ...(activation.rejectionReason === undefined
+                ? {}
+                : { rejectionReason: activation.rejectionReason }),
+            })),
+          ) !== revision.activationManifestSha256
+        ) {
+          throw new Error(
+            `Agent Skills revision ${revision.revisionId} manifest is invalid.`,
+          );
+        }
+      }
+      if (revision.kind === "prefix_retirement") {
+        const parent = previousRevision(revisions, revision);
+        if (parent === undefined) {
+          throw new Error("Prefix retirement revision has no parent.");
+        }
+        const retiredStart = Math.max(parent.keepFromOrdinal, 2);
+        const retiredMessages = canonical.messages.filter(
+          (message) =>
+            message.ordinal >= retiredStart &&
+            message.ordinal < revision.keepFromOrdinal,
+        );
+        const retiredFrames = canonical.frames.filter(
+          (frame) =>
+            frame.firstOrdinal >= retiredStart &&
+            (frame.lastOrdinal ?? Number.POSITIVE_INFINITY) < revision.keepFromOrdinal,
+        );
+        const retiredTurns = new Set(
+          retiredMessages.flatMap((message) =>
+            message.role === "system" ? [] : [message.turnId],
+          ),
+        );
+        if (
+          revision.retiredThroughOrdinal !== revision.keepFromOrdinal - 1 ||
+          revision.retiredMessageCount !== retiredMessages.length ||
+          revision.retiredFrameCount !== retiredFrames.length ||
+          revision.retiredTurnCount !== retiredTurns.size
+        ) {
+          throw new Error(
+            `Context retirement revision ${revision.revisionId} counts are invalid.`,
+          );
+        }
+      }
+      if (revision.kind === "surface_refresh") {
+        const parent = previousRevision(revisions, revision);
+        const parentSurface =
+          parent === undefined ? undefined : surfacesById.get(parent.surfaceId);
+        if (
+          parentSurface === undefined ||
+          contextSurfaceChangeManifestHash(
+            contextSurfaceChanges(parentSurface, surface),
+          ) !== revision.changeManifestSha256
+        ) {
+          throw new Error(
+            `Context surface revision ${revision.revisionId} change manifest is invalid.`,
+          );
+        }
+      }
       const prefix = protocolPrefixView(canonical, revision.sourceThroughOrdinal);
       this.revisionCompiler.compileActive({
         meta: Object.freeze({
@@ -1680,6 +3035,7 @@ export class SessionStore implements SessionLedgerCommitter {
           activeRevisionId: revision.revisionId,
         }),
         revision,
+        surface,
         activeOverrides,
         canonical: prefix,
       });
@@ -1696,18 +3052,26 @@ export class SessionStore implements SessionLedgerCommitter {
     return Object.freeze({
       meta: Object.freeze({
         sessionId: meta.sessionId,
-        activeRevisionId: meta.activeRevisionId,
+        activeRevisionId,
       }),
       revision: activeRevision,
-      activeOverrides: Object.freeze(overrides),
+      surface: activeSurface,
+      activeOverrides: Object.freeze(
+        overrides.filter(
+          (override) =>
+            (revisionNumberById.get(override.introducedRevisionId) ??
+              Number.POSITIVE_INFINITY) <= activeRevision.revisionNumber &&
+            override.ordinal >= activeRevision.keepFromOrdinal,
+        ),
+      ),
       canonical,
     });
   }
 
   private validateStoredOverrides(
-    overrides: readonly StoredSwapOverrideV5[],
+    overrides: readonly StoredContextOverrideV8[],
     canonical: ProtocolContextView,
-    revisions: readonly StoredContextRevisionV5[],
+    revisions: readonly StoredContextRevisionV8[],
     revisionNumberById: ReadonlyMap<ContextRevisionId, number>,
   ): void {
     const messages = new Map(
@@ -1729,8 +3093,13 @@ export class SessionStore implements SessionLedgerCommitter {
       const frame = frames.get(override.frameId);
       const result = results.get(override.messageId);
       if (
-        revision?.kind !== "swap_only" ||
+        (revision?.kind !== "swap_only" && revision?.kind !== "skills_update") ||
+        (revision.kind === "swap_only" &&
+          override.rendererFormat !== SWAP_OBSERVATION_FORMAT) ||
+        (revision.kind === "skills_update" &&
+          override.rendererFormat !== SKILL_ACTIVATION_RECEIPT_FORMAT) ||
         revisionNumberById.get(revision.revisionId) === undefined ||
+        override.ordinal < revision.keepFromOrdinal ||
         override.ordinal > revision.sourceThroughOrdinal ||
         seenMessages.has(override.messageId) ||
         message?.role !== "tool" ||
@@ -1742,17 +3111,137 @@ export class SessionStore implements SessionLedgerCommitter {
       ) {
         throw new Error("Stored context override canonical identity is invalid.");
       }
-      const rendered = this.swapRenderer.render({ message, result });
+      const rendered =
+        override.rendererFormat === SWAP_OBSERVATION_FORMAT
+          ? this.swapRenderer.render({ message, result })
+          : this.renderStoredSkillReceipt(message, result, revision.revisionId);
       if (
         stableJsonStringify(rendered) !==
         stableJsonStringify(stripStoredOverride(override))
       ) {
-        throw new Error(
-          `Stored context override ${override.messageId} does not match deterministic rendering.`,
-        );
+        throw new Error(
+          `Stored context override ${override.messageId} does not match deterministic rendering.`,
+        );
+      }
+      seenMessages.add(override.messageId);
+    }
+  }
+
+  private validateSkillActivationRows(
+    canonical: ProtocolContextView,
+    revisions: readonly StoredContextRevisionV8[],
+    overrides: readonly StoredContextOverrideV8[],
+    surfaces: readonly StoredContextSurfaceV8[],
+  ): void {
+    const activations = this.loadSkillActivations();
+    const activationByMessage = new Map(
+      activations.map((activation) => [activation.activationMessageId, activation]),
+    );
+    const messages = new Map(
+      canonical.messages.map((message) => [message.messageId, message]),
+    );
+    const results = new Map(
+      canonical.toolResults.map((result) => [result.toolMessageId, result]),
+    );
+    const loadedResults = canonical.toolResults.filter(
+      (result) =>
+        result.completion.kind === "returned" &&
+        result.completion.raw.kind === "skill" &&
+        result.completion.raw.ok &&
+        result.completion.raw.status === "loaded",
+    );
+    if (loadedResults.length !== activations.length) {
+      throw new Error("Loaded Agent Skill results and activation rows differ.");
+    }
+    const revisionsById = new Map(
+      revisions.map((revision) => [revision.revisionId, revision]),
+    );
+    const overridesByMessage = new Map(
+      overrides.map((override) => [override.messageId, override]),
+    );
+    for (const activation of activations) {
+      const message = messages.get(activation.activationMessageId);
+      const result = results.get(activation.activationMessageId);
+      const raw =
+        result?.completion.kind === "returned" ? result.completion.raw : undefined;
+      if (
+        activation.sessionId !== this.sessionId ||
+        message?.role !== "tool" ||
+        message.name !== "Skill" ||
+        message.toolCallId !== activation.toolCallId ||
+        raw?.kind !== "skill" ||
+        !raw.ok ||
+        raw.status !== "loaded" ||
+        raw.name !== activation.name ||
+        raw.scope !== activation.scope ||
+        raw.sha256 !== activation.skillFileSha256
+      ) {
+        throw new Error("Agent Skill activation canonical identity is invalid.");
       }
-      seenMessages.add(override.messageId);
+      if (activation.settledRevisionId !== undefined) {
+        const revision = revisionsById.get(activation.settledRevisionId);
+        const override = overridesByMessage.get(activation.activationMessageId);
+        if (
+          revision?.kind !== "skills_update" ||
+          override?.introducedRevisionId !== revision.revisionId ||
+          override.rendererFormat !== SKILL_ACTIVATION_RECEIPT_FORMAT
+        ) {
+          throw new Error("Settled Agent Skill activation receipt is invalid.");
+        }
+      }
+    }
+    for (const surface of surfaces) {
+      for (const active of surface.activeSkills) {
+        const activation = activationByMessage.get(active.activationMessageId);
+        if (activation?.state !== "promoted" || activation.name !== active.name) {
+          throw new Error(
+            "Context surface references an invalid Agent Skill activation.",
+          );
+        }
+      }
+    }
+  }
+
+  private renderStoredSkillReceipt(
+    message: Extract<CanonicalMessageRecord, { role: "tool" }>,
+    result: ToolResultRecord,
+    revisionId: ContextRevisionId,
+  ): SwapOverride {
+    if (
+      message.name !== "Skill" ||
+      result.completion.kind !== "returned" ||
+      result.completion.raw.kind !== "skill" ||
+      !result.completion.raw.ok ||
+      result.completion.raw.status !== "loaded"
+    ) {
+      throw new Error("Agent Skill receipt does not target a loaded Skill result.");
+    }
+    const activation = this.loadSkillActivations().find(
+      (entry) => entry.activationMessageId === message.messageId,
+    );
+    if (
+      activation === undefined ||
+      activation.settledRevisionId !== revisionId ||
+      (activation.state !== "promoted" && activation.state !== "rejected")
+    ) {
+      throw new Error("Agent Skill receipt has no matching settled activation.");
     }
+    return renderSkillActivationReceipt({
+      message: {
+        messageId: message.messageId,
+        frameId: message.frameId,
+        ordinal: message.ordinal,
+        content: message.content,
+        contentSha256: message.contentSha256,
+      },
+      name: activation.name,
+      outcome:
+        activation.state === "promoted"
+          ? "promoted"
+          : activation.rejectionReason === "unavailable"
+            ? "unavailable"
+            : "rejected",
+    });
   }
 
   private loadMeasuredContextState(): StoredMeasuredContextState | undefined {
@@ -1768,7 +3257,7 @@ export class SessionStore implements SessionLedgerCommitter {
       : decodeMeasuredContextState(row, this.sessionId);
   }
 
-  private validateCounters(meta: StoredSessionMetaV5, view: ProtocolContextView): void {
+  private validateCounters(meta: StoredSessionMetaV9, view: ProtocolContextView): void {
     const turns = this.database
       .query("SELECT * FROM turns ORDER BY turn_number")
       .all() as Array<Record<string, unknown>>;
@@ -1939,30 +3428,168 @@ export class SessionStore implements SessionLedgerCommitter {
   }
 }
 
-export function createRuntimeContract(input: {
+function insertPendingSkillActivation(
+  database: Database,
+  message: CanonicalMessageRecord,
+  result: ToolResultRecord,
+  now: string,
+): void {
+  if (
+    message.role !== "tool" ||
+    result.completion.kind !== "returned" ||
+    result.completion.raw.kind !== "skill" ||
+    !result.completion.raw.ok ||
+    result.completion.raw.status !== "loaded"
+  ) {
+    return;
+  }
+  const raw = result.completion.raw;
+  if (message.name !== "Skill" || message.messageId !== result.toolMessageId) {
+    throw new Error("Loaded Agent Skill completion has invalid tool identity.");
+  }
+  database
+    .query(
+      `INSERT INTO skill_activations (
+        activation_message_id, tool_call_id, session_id, name, scope,
+        skill_file_sha256, state, dispatched_iteration_id, settled_revision_id,
+        rejection_reason, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, NULL, ?, ?)`,
+    )
+    .run(
+      message.messageId,
+      result.toolCallId,
+      result.sessionId,
+      raw.name,
+      raw.scope,
+      raw.sha256,
+      now,
+      now,
+    );
+}
+
+export function createSessionCompatibilityContract(input: {
   modelName: string;
   profileName?: string;
   includeReasoningContent: boolean;
   contextProfile: ModelContextProfile;
-  contextBudget: ModelContextBudget;
-  systemPrompt: string;
-  toolSchemaSha256: string;
-  requestConfigSha256: string;
-}): RuntimeContractV1 {
+  messageProtocol: ModelMessageProtocol;
+  inputModalities?: readonly ("text" | "image")[];
+  tokenEstimator?: InputTokenEstimatorCompatibility;
+}): SessionCompatibilityContract {
+  if (input.modelName.trim() === "") {
+    throw new Error("Session compatibility model name must not be empty.");
+  }
+  if (input.profileName !== undefined && input.profileName.trim() === "") {
+    throw new Error("Session compatibility profile name must not be empty.");
+  }
+  if (typeof input.includeReasoningContent !== "boolean") {
+    throw new Error("Session compatibility reasoning replay flag must be boolean.");
+  }
+  if (
+    !["openai-chat", "fake"].includes(input.messageProtocol.adapter) ||
+    input.messageProtocol.serializationVersion.trim() === ""
+  ) {
+    throw new Error("Session compatibility message protocol is invalid.");
+  }
+  const inputModalities = normalizeInputModalities(input.inputModalities ?? ["text"]);
+  if (inputModalities.includes("image") && input.tokenEstimator === undefined) {
+    throw new Error(
+      "Session compatibility image input requires a token estimator identity.",
+    );
+  }
+  if (input.tokenEstimator !== undefined) {
+    validateTokenEstimatorCompatibility(input.tokenEstimator);
+  }
   return Object.freeze({
-    version: 1,
     modelName: input.modelName,
     ...(input.profileName === undefined ? {} : { profileName: input.profileName }),
     includeReasoningContent: input.includeReasoningContent,
-    contextProfile: immutableCanonicalClone(input.contextProfile),
-    contextBudget: immutableCanonicalClone(input.contextBudget),
-    systemPromptSha256: sha256(input.systemPrompt),
-    toolSchemaSha256: input.toolSchemaSha256,
-    requestConfigSha256: input.requestConfigSha256,
-    observationFormat: TOOL_OBSERVATION_FORMAT,
+    contextProfile: Object.freeze(createModelContextProfile(input.contextProfile)),
+    messageProtocol: immutableCanonicalClone(input.messageProtocol),
+    imageInput: Object.freeze({
+      policyVersion: IMAGE_INPUT_POLICY_VERSION,
+      policySha256: sha256(
+        stableJsonStringify({
+          version: IMAGE_INPUT_POLICY_VERSION,
+          ...IMAGE_INPUT_POLICY,
+        }),
+      ),
+      inputModalities,
+      ...(input.tokenEstimator === undefined
+        ? {}
+        : { tokenEstimator: immutableCanonicalClone(input.tokenEstimator) }),
+    }),
+  });
+}
+
+function normalizeSessionCompatibilityContract(
+  contract: SessionCompatibilityContract,
+): SessionCompatibilityContract {
+  return createSessionCompatibilityContract({
+    modelName: contract.modelName,
+    ...(contract.profileName === undefined
+      ? {}
+      : { profileName: contract.profileName }),
+    includeReasoningContent: contract.includeReasoningContent,
+    contextProfile: contract.contextProfile,
+    messageProtocol: contract.messageProtocol,
+    inputModalities: contract.imageInput.inputModalities,
+    ...(contract.imageInput.tokenEstimator === undefined
+      ? {}
+      : { tokenEstimator: contract.imageInput.tokenEstimator }),
   });
 }
 
+function normalizeInputModalities(
+  modalities: readonly ("text" | "image")[],
+): readonly ("text" | "image")[] {
+  if (
+    modalities.length === 0 ||
+    modalities.some((value) => value !== "text" && value !== "image") ||
+    new Set(modalities).size !== modalities.length ||
+    !modalities.includes("text")
+  ) {
+    throw new Error("Session compatibility input modalities are invalid.");
+  }
+  return Object.freeze(
+    modalities.includes("image") ? (["text", "image"] as const) : (["text"] as const),
+  );
+}
+
+function validateTokenEstimatorCompatibility(
+  estimator: InputTokenEstimatorCompatibility,
+): void {
+  if (
+    estimator.kind !== "moonshot-estimate-token-count-v1" ||
+    estimator.coverageVersion !== "full-request-v1" ||
+    estimator.model.trim() === "" ||
+    !isNormalizedEstimatorEndpoint(estimator.endpoint) ||
+    !Number.isSafeInteger(estimator.timeoutMs) ||
+    estimator.timeoutMs < 1_000 ||
+    estimator.timeoutMs > 60_000 ||
+    estimator.maxRetries !== 0
+  ) {
+    throw new Error("Session compatibility token estimator identity is invalid.");
+  }
+}
+
+function isNormalizedEstimatorEndpoint(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return (
+      (url.protocol === "https:" || url.protocol === "http:") &&
+      url.username === "" &&
+      url.password === "" &&
+      url.search === "" &&
+      url.hash === "" &&
+      url.pathname.endsWith("/tokenizers/estimate-token-count") &&
+      url.toString() === value
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function sessionDatabasePath(
   workspaceRoot: string,
   sessionId: SessionId,
@@ -2031,6 +3658,83 @@ function insertMessage(database: Database, message: CanonicalMessageRecord): voi
       message.origin,
       message.createdAt,
     );
+  if (message.role === "user" && message.attachments !== undefined) {
+    insertMessageImageAttachments(database, message);
+  }
+}
+
+function insertMessageImageAttachments(
+  database: Database,
+  message: Extract<CanonicalMessageRecord, { role: "user" }>,
+): void {
+  const userMessage = {
+    role: "user" as const,
+    content: message.content,
+    attachments: message.attachments,
+  };
+  validateUserMessage(userMessage);
+  if (userMessageHash(userMessage) !== message.contentSha256) {
+    throw new Error("User image attachment hash does not match the message hash.");
+  }
+  for (let position = 0; position < message.attachments!.length; position += 1) {
+    const attachment = requireItem(message.attachments!, position, "image attachment");
+    const existing = database
+      .query(
+        `SELECT mime_type, byte_length, width, height, created_at
+         FROM image_assets WHERE asset_id = ?`,
+      )
+      .get(attachment.assetId) as {
+      mime_type: unknown;
+      byte_length: unknown;
+      width: unknown;
+      height: unknown;
+      created_at: unknown;
+    } | null;
+    if (existing === null) {
+      database
+        .query(
+          `INSERT INTO image_assets (
+             asset_id, mime_type, byte_length, width, height, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          attachment.assetId,
+          attachment.mimeType,
+          attachment.byteLength,
+          attachment.width,
+          attachment.height,
+          message.createdAt,
+        );
+    } else {
+      timestampFromSql(existing.created_at, "image asset created_at");
+      if (
+        existing.mime_type !== attachment.mimeType ||
+        numberFromSql(existing.byte_length, "image asset byte_length") !==
+          attachment.byteLength ||
+        numberFromSql(existing.width, "image asset width") !== attachment.width ||
+        numberFromSql(existing.height, "image asset height") !== attachment.height
+      ) {
+        throw new Error(`Image asset metadata conflicts for ${attachment.assetId}.`);
+      }
+    }
+    database
+      .query(
+        `INSERT INTO message_image_attachments (
+           message_id, attachment_id, asset_id, position, label,
+           range_start, range_end, original_name
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        message.messageId,
+        attachment.attachmentId,
+        attachment.assetId,
+        position,
+        attachment.label,
+        attachment.range.start,
+        attachment.range.end,
+        attachment.originalName,
+      );
+  }
 }
 
 function insertToolResult(database: Database, result: ToolResultRecord): void {
@@ -2060,6 +3764,45 @@ function insertToolResult(database: Database, result: ToolResultRecord): void {
     );
 }
 
+function insertContextSurface(
+  database: Database,
+  surface: StoredContextSurfaceV8,
+): void {
+  validateStoredContextSurface(surface);
+  database
+    .query(
+      `INSERT INTO context_surfaces (
+        surface_id, session_id, system_prompt, system_prompt_sha256,
+        recall_contract_version,
+        project_instruction_json, skill_catalog_json, skill_catalog_sha256,
+        active_skills_json, active_skills_sha256, tool_definitions_json,
+        tool_definitions_sha256, tool_schema_sha256, request_config_sha256,
+        request_max_output_tokens, surface_sha256, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      surface.surfaceId,
+      surface.sessionId,
+      surface.systemPrompt,
+      surface.systemPromptSha256,
+      surface.recallContractVersion,
+      surface.projectInstruction === undefined
+        ? null
+        : stableJsonStringify(surface.projectInstruction),
+      stableJsonStringify(surface.skillCatalog),
+      surface.skillCatalogSha256,
+      stableJsonStringify(surface.activeSkills),
+      surface.activeSkillsSha256,
+      stableJsonStringify(surface.toolDefinitions),
+      surface.toolDefinitionsSha256,
+      surface.toolSchemaSha256,
+      surface.requestConfigSha256,
+      surface.requestMaxOutputTokens,
+      surface.surfaceSha256,
+      surface.createdAt,
+    );
+}
+
 function decodeFrame(rowValue: unknown): ProtocolFrame {
   const row = recordFromSql(rowValue, "protocol frame");
   const state = enumFromSql(row.state, ["open", "closed"] as const, "frame state");
@@ -2090,7 +3833,67 @@ function decodeFrame(rowValue: unknown): ProtocolFrame {
   });
 }
 
-function decodeMessage(rowValue: unknown): CanonicalMessageRecord {
+function loadMessageImageAttachments(
+  database: Database,
+): Map<string, readonly UserImageAttachment[]> {
+  const rows = database
+    .query(
+      `SELECT mia.*, ia.mime_type, ia.byte_length, ia.width, ia.height,
+              ia.created_at AS asset_created_at
+       FROM message_image_attachments mia
+       JOIN image_assets ia ON ia.asset_id = mia.asset_id
+       JOIN messages m ON m.message_id = mia.message_id
+       ORDER BY m.ordinal, mia.position`,
+    )
+    .all();
+  const mutable = new Map<string, UserImageAttachment[]>();
+  for (const rowValue of rows) {
+    const row = recordFromSql(rowValue, "message image attachment");
+    const messageId = stringFromSql(row.message_id, "attachment message_id");
+    const attachments = mutable.get(messageId) ?? [];
+    const position = numberFromSql(row.position, "attachment position");
+    if (position !== attachments.length) {
+      throw new Error(
+        `Image attachment positions for message ${messageId} are not continuous.`,
+      );
+    }
+    timestampFromSql(row.asset_created_at, "image asset created_at");
+    const attachment = immutableRecord<UserImageAttachment>({
+      attachmentId: parseImageAttachmentId(
+        stringFromSql(row.attachment_id, "attachment_id"),
+      ),
+      assetId: parseImageAssetId(stringFromSql(row.asset_id, "asset_id")),
+      mimeType: enumFromSql(
+        row.mime_type,
+        ["image/png", "image/jpeg", "image/webp"] as const,
+        "image mime_type",
+      ),
+      byteLength: numberFromSql(row.byte_length, "image byte_length"),
+      width: numberFromSql(row.width, "image width"),
+      height: numberFromSql(row.height, "image height"),
+      label: stringFromSql(row.label, "attachment label"),
+      range: immutableRecord({
+        start: numberFromSql(row.range_start, "attachment range_start"),
+        end: numberFromSql(row.range_end, "attachment range_end"),
+      }),
+      originalName: stringFromSql(row.original_name, "attachment original_name"),
+    });
+    validateOriginalImageName(attachment.originalName);
+    attachments.push(attachment);
+    mutable.set(messageId, attachments);
+  }
+  return new Map(
+    [...mutable].map(([messageId, attachments]) => [
+      messageId,
+      Object.freeze(attachments),
+    ]),
+  );
+}
+
+function decodeMessage(
+  rowValue: unknown,
+  attachments?: readonly UserImageAttachment[],
+): CanonicalMessageRecord {
   const row = recordFromSql(rowValue, "message");
   const base = {
     messageId: stringFromSql(row.message_id, "message_id") as MessageId,
@@ -2107,21 +3910,37 @@ function decodeMessage(rowValue: unknown): CanonicalMessageRecord {
   );
   switch (role) {
     case "system":
+      if (attachments !== undefined) {
+        throw new Error("System messages cannot have image attachments.");
+      }
       return immutableRecord({
         ...base,
         role,
         content: stringFromSql(row.content, "content"),
         origin: "runtime",
       });
-    case "user":
-      return immutableRecord({
+    case "user": {
+      const message = {
         ...base,
         role,
         turnId: stringFromSql(row.turn_id, "turn_id") as TurnId,
         content: stringFromSql(row.content, "content"),
+        ...(attachments === undefined ? {} : { attachments }),
         origin: "user",
+      } as const;
+      validateUserMessage({
+        role: "user",
+        content: message.content,
+        ...(message.attachments === undefined
+          ? {}
+          : { attachments: message.attachments }),
       });
+      return immutableRecord(message);
+    }
     case "assistant": {
+      if (attachments !== undefined) {
+        throw new Error("Assistant messages cannot have image attachments.");
+      }
       const content = nullableTextFromSql(row.content, "content");
       const reasoningPresent = numberFromSql(
         row.reasoning_content_present,
@@ -2157,6 +3976,9 @@ function decodeMessage(rowValue: unknown): CanonicalMessageRecord {
       });
     }
     case "tool":
+      if (attachments !== undefined) {
+        throw new Error("Tool messages cannot have image attachments.");
+      }
       return immutableRecord({
         ...base,
         role,
@@ -2174,6 +3996,16 @@ function decodeMessage(rowValue: unknown): CanonicalMessageRecord {
   }
 }
 
+function imageAssetRefFromAttachment(attachment: UserImageAttachment): ImageAssetRef {
+  return Object.freeze({
+    assetId: attachment.assetId,
+    mimeType: attachment.mimeType,
+    byteLength: attachment.byteLength,
+    width: attachment.width,
+    height: attachment.height,
+  });
+}
+
 function decodeToolResult(rowValue: unknown): ToolResultRecord {
   const row = recordFromSql(rowValue, "tool result");
   const kind = enumFromSql(
@@ -2191,7 +4023,7 @@ function decodeToolResult(rowValue: unknown): ToolResultRecord {
       rawSha256: stringFromSql(row.raw_sha256, "raw_sha256"),
       observationFormat: enumFromSql(
         row.observation_format,
-        [TOOL_OBSERVATION_FORMAT] as const,
+        SUPPORTED_TOOL_OBSERVATION_FORMATS,
         "observation format",
       ),
     });
@@ -2229,26 +4061,102 @@ function decodeToolResult(rowValue: unknown): ToolResultRecord {
   });
 }
 
-function decodeContextRevision(rowValue: unknown): StoredContextRevisionV5 {
+function decodeContextSurface(rowValue: unknown): StoredContextSurfaceV8 {
+  const row = recordFromSql(rowValue, "context surface");
+  const projectInstruction =
+    row.project_instruction_json === null
+      ? undefined
+      : decodeProjectInstructionManifest(
+          parseJson(
+            stringFromSql(row.project_instruction_json, "project_instruction_json"),
+            "project_instruction_json",
+          ),
+        );
+  const toolDefinitions = decodeToolDefinitions(
+    parseJson(
+      stringFromSql(row.tool_definitions_json, "tool_definitions_json"),
+      "tool_definitions_json",
+    ),
+  );
+  const skillCatalog = decodeSkillCatalogManifest(
+    parseJson(
+      stringFromSql(row.skill_catalog_json, "skill_catalog_json"),
+      "skill_catalog_json",
+    ),
+  );
+  const activeSkills = decodeActiveSkillsManifest(
+    parseJson(
+      stringFromSql(row.active_skills_json, "active_skills_json"),
+      "active_skills_json",
+    ),
+  );
+  const surface = Object.freeze({
+    surfaceId: stringFromSql(row.surface_id, "surface_id") as ContextSurfaceId,
+    sessionId: stringFromSql(row.session_id, "session_id") as SessionId,
+    systemPrompt: stringFromSql(row.system_prompt, "system_prompt"),
+    systemPromptSha256: sha256FromSql(row.system_prompt_sha256, "system_prompt_sha256"),
+    recallContractVersion: enumFromSql(
+      row.recall_contract_version,
+      SUPPORTED_RECALL_RETIREMENT_CONTRACT_VERSIONS,
+      "recall_contract_version",
+    ),
+    ...(projectInstruction === undefined ? {} : { projectInstruction }),
+    skillCatalog,
+    skillCatalogSha256: sha256FromSql(row.skill_catalog_sha256, "skill_catalog_sha256"),
+    activeSkills,
+    activeSkillsSha256: sha256FromSql(row.active_skills_sha256, "active_skills_sha256"),
+    toolDefinitions,
+    toolDefinitionsSha256: sha256FromSql(
+      row.tool_definitions_sha256,
+      "tool_definitions_sha256",
+    ),
+    toolSchemaSha256: sha256FromSql(row.tool_schema_sha256, "tool_schema_sha256"),
+    requestConfigSha256: sha256FromSql(
+      row.request_config_sha256,
+      "request_config_sha256",
+    ),
+    requestMaxOutputTokens: numberFromSql(
+      row.request_max_output_tokens,
+      "request_max_output_tokens",
+    ),
+    surfaceSha256: sha256FromSql(row.surface_sha256, "surface_sha256"),
+    createdAt: timestampFromSql(row.created_at, "created_at"),
+  });
+  validateStoredContextSurface(surface);
+  return surface;
+}
+
+function decodeContextRevision(rowValue: unknown): StoredContextRevisionV8 {
   const row = recordFromSql(rowValue, "context revision");
   const kind = enumFromSql(
     row.kind,
-    ["initial_full", "swap_only"] as const,
+    [
+      "initial_full",
+      "swap_only",
+      "surface_refresh",
+      "prefix_retirement",
+      "skills_update",
+    ] as const,
     "context revision kind",
   );
   const common = {
     revisionId: stringFromSql(row.revision_id, "revision_id") as ContextRevisionId,
     sessionId: stringFromSql(row.session_id, "session_id") as SessionId,
+    surfaceId: stringFromSql(row.surface_id, "surface_id") as ContextSurfaceId,
+    surfaceSha256: sha256FromSql(row.surface_sha256, "surface_sha256"),
     keepFromOrdinal: numberFromSql(row.keep_from_ordinal, "keep_from_ordinal"),
     sourceThroughOrdinal: numberFromSql(
       row.source_through_ordinal,
       "source_through_ordinal",
     ),
     addedOverrideCount: numberFromSql(row.added_override_count, "added_override_count"),
-    totalOverrideCount: numberFromSql(row.total_override_count, "total_override_count"),
-    overrideManifestSha256: sha256FromSql(
-      row.override_manifest_sha256,
-      "override_manifest_sha256",
+    activeOverrideCount: numberFromSql(
+      row.active_override_count,
+      "active_override_count",
+    ),
+    activeOverrideManifestSha256: sha256FromSql(
+      row.active_override_manifest_sha256,
+      "active_override_manifest_sha256",
     ),
     canonicalSequenceSha256: sha256FromSql(
       row.canonical_sequence_sha256,
@@ -2260,8 +4168,8 @@ function decodeContextRevision(rowValue: unknown): StoredContextRevisionV5 {
     ),
     createdAt: timestampFromSql(row.created_at, "created_at"),
   };
-  if (common.keepFromOrdinal !== 1) {
-    throw new Error("Context revision keep_from_ordinal must be 1 in schema v5.");
+  if (common.keepFromOrdinal < 1) {
+    throw new Error("Context revision keep_from_ordinal must be positive.");
   }
   const revisionNumber = numberFromSql(row.revision_number, "revision_number");
   const parentRevisionId = nullableStringFromSql(
@@ -2274,10 +4182,14 @@ function decodeContextRevision(rowValue: unknown): StoredContextRevisionV5 {
       parentRevisionId !== null ||
       common.sourceThroughOrdinal !== 1 ||
       common.addedOverrideCount !== 0 ||
-      common.totalOverrideCount !== 0 ||
+      common.activeOverrideCount !== 0 ||
+      common.keepFromOrdinal !== 1 ||
       row.policy_version !== null ||
       row.renderer_format !== null ||
-      row.plan_sha256 !== null
+      row.plan_sha256 !== null ||
+      row.change_manifest_sha256 !== null ||
+      row.activation_manifest_sha256 !== null ||
+      !hasNoRetirementFields(row)
     ) {
       throw new Error("Initial context revision row is invalid.");
     }
@@ -2289,38 +4201,165 @@ function decodeContextRevision(rowValue: unknown): StoredContextRevisionV5 {
       keepFromOrdinal: 1,
       sourceThroughOrdinal: 1,
       addedOverrideCount: 0,
-      totalOverrideCount: 0,
+      activeOverrideCount: 0,
+    });
+  }
+  if (
+    kind === "swap_only" &&
+    (revisionNumber < 2 ||
+      parentRevisionId === null ||
+      common.addedOverrideCount < 1 ||
+      common.activeOverrideCount < common.addedOverrideCount)
+  ) {
+    throw new Error("Swap context revision row is invalid.");
+  }
+  if (kind === "swap_only") {
+    if (
+      row.change_manifest_sha256 !== null ||
+      row.activation_manifest_sha256 !== null ||
+      !hasNoRetirementFields(row)
+    ) {
+      throw new Error("Swap context revision has a change manifest.");
+    }
+    return Object.freeze({
+      ...common,
+      revisionNumber,
+      parentRevisionId: parentRevisionId!,
+      kind,
+      policyVersion: enumFromSql(
+        row.policy_version,
+        ["swap-only-v1"] as const,
+        "context revision policy",
+      ),
+      rendererFormat: enumFromSql(
+        row.renderer_format,
+        [SWAP_OBSERVATION_FORMAT] as const,
+        "context revision renderer format",
+      ),
+      planSha256: sha256FromSql(row.plan_sha256, "plan_sha256"),
+    });
+  }
+  if (kind === "skills_update") {
+    if (
+      revisionNumber < 2 ||
+      parentRevisionId === null ||
+      common.addedOverrideCount < 1 ||
+      common.activeOverrideCount < common.addedOverrideCount ||
+      row.plan_sha256 !== null ||
+      !hasNoRetirementFields(row)
+    ) {
+      throw new Error("Agent Skills context revision row is invalid.");
+    }
+    return Object.freeze({
+      ...common,
+      revisionNumber,
+      parentRevisionId,
+      kind,
+      policyVersion: enumFromSql(
+        row.policy_version,
+        [SKILL_POLICY_VERSION] as const,
+        "Agent Skills context revision policy",
+      ),
+      rendererFormat: enumFromSql(
+        row.renderer_format,
+        [SKILL_ACTIVATION_RECEIPT_FORMAT] as const,
+        "Agent Skills context revision renderer format",
+      ),
+      changeManifestSha256: sha256FromSql(
+        row.change_manifest_sha256,
+        "change_manifest_sha256",
+      ),
+      activationManifestSha256: sha256FromSql(
+        row.activation_manifest_sha256,
+        "activation_manifest_sha256",
+      ),
+    });
+  }
+  if (kind === "prefix_retirement") {
+    const retiredThroughOrdinal = numberFromSql(
+      row.retired_through_ordinal,
+      "retired_through_ordinal",
+    );
+    const retiredTurnCount = numberFromSql(
+      row.retired_turn_count,
+      "retired_turn_count",
+    );
+    const retiredFrameCount = numberFromSql(
+      row.retired_frame_count,
+      "retired_frame_count",
+    );
+    const retiredMessageCount = numberFromSql(
+      row.retired_message_count,
+      "retired_message_count",
+    );
+    if (
+      revisionNumber < 2 ||
+      parentRevisionId === null ||
+      common.keepFromOrdinal <= 1 ||
+      common.addedOverrideCount !== 0 ||
+      retiredThroughOrdinal !== common.keepFromOrdinal - 1 ||
+      retiredTurnCount < 1 ||
+      retiredFrameCount < 1 ||
+      retiredMessageCount < 1 ||
+      row.renderer_format !== null ||
+      row.change_manifest_sha256 !== null ||
+      row.activation_manifest_sha256 !== null
+    ) {
+      throw new Error("Prefix retirement revision row is invalid.");
+    }
+    return Object.freeze({
+      ...common,
+      revisionNumber,
+      parentRevisionId,
+      kind,
+      addedOverrideCount: 0,
+      policyVersion: enumFromSql(
+        row.policy_version,
+        ["recall-first-retirement-v1"] as const,
+        "context revision policy",
+      ),
+      planSha256: sha256FromSql(row.plan_sha256, "plan_sha256"),
+      retiredThroughOrdinal,
+      retiredTurnCount,
+      retiredFrameCount,
+      retiredMessageCount,
     });
   }
   if (
     revisionNumber < 2 ||
     parentRevisionId === null ||
-    common.addedOverrideCount < 1 ||
-    common.totalOverrideCount < common.addedOverrideCount
+    common.addedOverrideCount !== 0 ||
+    row.policy_version !== null ||
+    row.renderer_format !== null ||
+    row.plan_sha256 !== null ||
+    row.activation_manifest_sha256 !== null ||
+    !hasNoRetirementFields(row)
   ) {
-    throw new Error("Swap context revision row is invalid.");
+    throw new Error("Surface context revision row is invalid.");
   }
   return Object.freeze({
     ...common,
     revisionNumber,
     parentRevisionId,
     kind,
-    keepFromOrdinal: 1,
-    policyVersion: enumFromSql(
-      row.policy_version,
-      ["swap-only-v1"] as const,
-      "context revision policy",
-    ),
-    rendererFormat: enumFromSql(
-      row.renderer_format,
-      [SWAP_OBSERVATION_FORMAT] as const,
-      "context revision renderer format",
+    addedOverrideCount: 0,
+    changeManifestSha256: sha256FromSql(
+      row.change_manifest_sha256,
+      "change_manifest_sha256",
     ),
-    planSha256: sha256FromSql(row.plan_sha256, "plan_sha256"),
   });
 }
 
-function decodeStoredSwapOverride(rowValue: unknown): StoredSwapOverrideV5 {
+function hasNoRetirementFields(row: Record<string, unknown>): boolean {
+  return (
+    row.retired_through_ordinal === null &&
+    row.retired_turn_count === null &&
+    row.retired_frame_count === null &&
+    row.retired_message_count === null
+  );
+}
+
+function decodeStoredSwapOverride(rowValue: unknown): StoredContextOverrideV8 {
   const row = recordFromSql(rowValue, "context override");
   if (row.representation !== "swapped") {
     throw new Error("Context override representation must be swapped.");
@@ -2335,10 +4374,10 @@ function decodeStoredSwapOverride(rowValue: unknown): StoredSwapOverrideV5 {
     ordinal: numberFromSql(row.ordinal, "ordinal"),
     rendererFormat: enumFromSql(
       row.renderer_format,
-      [SWAP_OBSERVATION_FORMAT] as const,
+      [SWAP_OBSERVATION_FORMAT, SKILL_ACTIVATION_RECEIPT_FORMAT] as const,
       "context override renderer format",
     ),
-    source: stringFromSql(row.source, "source") as StoredSwapOverrideV5["source"],
+    source: stringFromSql(row.source, "source") as StoredContextOverrideV8["source"],
     originalContentSha256: sha256FromSql(
       row.original_content_sha256,
       "original_content_sha256",
@@ -2355,7 +4394,7 @@ function decodeStoredSwapOverride(rowValue: unknown): StoredSwapOverrideV5 {
   });
 }
 
-function stripStoredOverride(override: StoredSwapOverrideV5): SwapOverride {
+function stripStoredOverride(override: StoredContextOverrideV8): SwapOverride {
   return Object.freeze({
     frameId: override.frameId,
     messageId: override.messageId,
@@ -2367,6 +4406,71 @@ function stripStoredOverride(override: StoredSwapOverrideV5): SwapOverride {
     originalBytes: override.originalBytes,
     renderedBytes: override.renderedBytes,
     byteSavings: override.byteSavings,
+    ...(override.rendererFormat === SWAP_OBSERVATION_FORMAT
+      ? {}
+      : { rendererFormat: override.rendererFormat }),
+  });
+}
+
+function decodeSkillActivation(rowValue: unknown): StoredSkillActivation {
+  const row = recordFromSql(rowValue, "skill activation");
+  const state = enumFromSql(
+    row.state,
+    ["pending", "dispatched", "promoted", "rejected"] as const,
+    "skill activation state",
+  );
+  const dispatchedIterationId = nullableStringFromSql(
+    row.dispatched_iteration_id,
+    "dispatched_iteration_id",
+  ) as IterationId | null;
+  const settledRevisionId = nullableStringFromSql(
+    row.settled_revision_id,
+    "settled_revision_id",
+  ) as ContextRevisionId | null;
+  const rejectionReason = nullableStringFromSql(
+    row.rejection_reason,
+    "rejection_reason",
+  );
+  if (
+    (state === "pending" &&
+      (dispatchedIterationId !== null ||
+        settledRevisionId !== null ||
+        rejectionReason !== null)) ||
+    (state === "dispatched" &&
+      (dispatchedIterationId === null ||
+        settledRevisionId !== null ||
+        rejectionReason !== null)) ||
+    (state === "promoted" &&
+      (dispatchedIterationId === null ||
+        settledRevisionId === null ||
+        rejectionReason !== null)) ||
+    (state === "rejected" &&
+      (settledRevisionId === null ||
+        rejectionReason === null ||
+        rejectionReason.trim() === ""))
+  ) {
+    throw new Error("Skill activation lifecycle fields are invalid.");
+  }
+  return Object.freeze({
+    activationMessageId: stringFromSql(
+      row.activation_message_id,
+      "activation_message_id",
+    ) as MessageId,
+    toolCallId: stringFromSql(row.tool_call_id, "tool_call_id") as ToolCallId,
+    sessionId: stringFromSql(row.session_id, "session_id") as SessionId,
+    name: stringFromSql(row.name, "skill activation name"),
+    scope: enumFromSql(
+      row.scope,
+      ["project", "user"] as const,
+      "skill activation scope",
+    ),
+    skillFileSha256: sha256FromSql(row.skill_file_sha256, "skill_file_sha256"),
+    state,
+    ...(dispatchedIterationId === null ? {} : { dispatchedIterationId }),
+    ...(settledRevisionId === null ? {} : { settledRevisionId }),
+    ...(rejectionReason === null ? {} : { rejectionReason }),
+    createdAt: timestampFromSql(row.created_at, "created_at"),
+    updatedAt: timestampFromSql(row.updated_at, "updated_at"),
   });
 }
 
@@ -2455,12 +4559,158 @@ export function decodeStoredToolCalls(json: string): readonly ToolCall[] {
           }),
     };
   });
-  return Object.freeze(calls);
+  return Object.freeze(calls);
+}
+
+function decodeProjectInstructionManifest(value: unknown): ProjectInstructionManifest {
+  const record = recordFromSql(value, "project instruction manifest");
+  assertObjectKeys(
+    record,
+    ["path", "byteLength", "sha256"],
+    ["path", "byteLength", "sha256"],
+    "project instruction manifest",
+  );
+  return Object.freeze({
+    path: enumFromSql(
+      record.path,
+      ["AGENTS.md", "CLAUDE.md"] as const,
+      "project instruction path",
+    ),
+    byteLength: numberFromJson(record.byteLength, "project instruction byteLength"),
+    sha256: sha256FromSql(record.sha256, "project instruction sha256"),
+  });
+}
+
+function decodeSkillCatalogManifest(
+  value: unknown,
+): readonly SkillCatalogManifestEntry[] {
+  if (!Array.isArray(value)) {
+    throw new Error("skill_catalog_json must contain an array.");
+  }
+  return Object.freeze(
+    value.map((entry, index) => {
+      const record = recordFromSql(entry, `skill catalog entry ${index}`);
+      assertObjectKeys(
+        record,
+        [
+          "name",
+          "scope",
+          "directorySha256",
+          "descriptionSha256",
+          "skillFileSha256",
+          "byteLength",
+        ],
+        [
+          "name",
+          "scope",
+          "directorySha256",
+          "descriptionSha256",
+          "skillFileSha256",
+          "byteLength",
+        ],
+        `skill catalog entry ${index}`,
+      );
+      return Object.freeze({
+        name: stringFromSql(record.name, "skill name"),
+        scope: enumFromSql(record.scope, ["project", "user"] as const, "skill scope"),
+        directorySha256: sha256FromSql(record.directorySha256, "skill directorySha256"),
+        descriptionSha256: sha256FromSql(
+          record.descriptionSha256,
+          "skill descriptionSha256",
+        ),
+        skillFileSha256: sha256FromSql(record.skillFileSha256, "skill skillFileSha256"),
+        byteLength: numberFromJson(record.byteLength, "skill byteLength"),
+      });
+    }),
+  );
+}
+
+function decodeActiveSkillsManifest(
+  value: unknown,
+): readonly ActiveSkillManifestEntry[] {
+  if (!Array.isArray(value)) {
+    throw new Error("active_skills_json must contain an array.");
+  }
+  return Object.freeze(
+    value.map((entry, index) => {
+      const record = recordFromSql(entry, `active skill entry ${index}`);
+      assertObjectKeys(
+        record,
+        [
+          "name",
+          "scope",
+          "directorySha256",
+          "descriptionSha256",
+          "skillFileSha256",
+          "byteLength",
+          "activationMessageId",
+        ],
+        [
+          "name",
+          "scope",
+          "directorySha256",
+          "descriptionSha256",
+          "skillFileSha256",
+          "byteLength",
+          "activationMessageId",
+        ],
+        `active skill entry ${index}`,
+      );
+      const [catalogEntry] = decodeSkillCatalogManifest([
+        {
+          name: record.name,
+          scope: record.scope,
+          directorySha256: record.directorySha256,
+          descriptionSha256: record.descriptionSha256,
+          skillFileSha256: record.skillFileSha256,
+          byteLength: record.byteLength,
+        },
+      ]);
+      if (catalogEntry === undefined) {
+        throw new Error(`Active skill entry ${index} is missing.`);
+      }
+      return Object.freeze({
+        ...catalogEntry,
+        activationMessageId: stringFromSql(
+          record.activationMessageId,
+          "skill activationMessageId",
+        ) as MessageId,
+      });
+    }),
+  );
+}
+
+function decodeToolDefinitions(value: unknown): readonly ToolDefinition[] {
+  if (!Array.isArray(value)) {
+    throw new Error("tool_definitions_json must contain an array.");
+  }
+  const definitions = value.map((entry, index): ToolDefinition => {
+    const record = recordFromSql(entry, `tool definition ${index}`);
+    assertObjectKeys(
+      record,
+      ["name", "description", "parameters"],
+      ["name", "description", "parameters"],
+      `tool definition ${index}`,
+    );
+    const parameters = recordFromSql(
+      record.parameters,
+      `tool definition ${index} parameters`,
+    );
+    return Object.freeze({
+      name: stringFromSql(record.name, `tool definition ${index} name`),
+      description: stringFromSql(
+        record.description,
+        `tool definition ${index} description`,
+      ),
+      parameters: immutableCanonicalClone(parameters),
+    });
+  });
+  return Object.freeze(definitions);
 }
 
 export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
   const raw = recordFromSql(value, "tool raw result");
-  enumFromSql(
+  const kind = enumFromSql(
     raw.kind,
     [
       "read",
@@ -2475,6 +4725,7 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
       "web_search",
       "web_fetch",
       "recall",
+      "skill",
       "mcp",
       "generic",
     ] as const,
@@ -2483,9 +4734,206 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
   if (typeof raw.ok !== "boolean") {
     throw new Error("tool raw result ok must be a boolean.");
   }
+  if (kind === "skill") {
+    return decodeStoredSkillRawResult(raw);
+  }
   return immutableCanonicalClone(raw) as ToolRawResult;
 }
 
+function decodeStoredSkillRawResult(
+  raw: Record<string, unknown>,
+): Extract<ToolRawResult, { kind: "skill" }> {
+  const status = enumFromSql(
+    raw.status,
+    ["loaded", "already_loaded", "already_active", "failed"] as const,
+    "Skill raw result status",
+  );
+  const name = stringFromSql(raw.name, "Skill raw result name");
+  if (status === "failed") {
+    if (raw.ok !== false) {
+      throw new Error("Failed Skill raw result must have ok=false.");
+    }
+    assertObjectKeys(
+      raw,
+      ["kind", "ok", "status", "name", "errorCode", "error"],
+      ["kind", "ok", "status", "name", "errorCode", "error"],
+      "failed Skill raw result",
+    );
+    const errorCode = stringFromSql(raw.errorCode, "Skill errorCode");
+    const error = stringFromSql(raw.error, "Skill error");
+    if (
+      (name !== "" && !isValidSkillName(name)) ||
+      !/^[A-Z][A-Z0-9_]{0,79}$/.test(errorCode) ||
+      error.trim() === ""
+    ) {
+      throw new Error("Failed Skill raw result fields are invalid.");
+    }
+    return immutableRecord({
+      kind: "skill" as const,
+      ok: false as const,
+      status,
+      name,
+      errorCode,
+      error,
+    });
+  }
+  if (raw.ok !== true) {
+    throw new Error("Successful Skill raw result must have ok=true.");
+  }
+  const scope = enumFromSql(
+    raw.scope,
+    ["project", "user"] as const,
+    "Skill raw result scope",
+  );
+  const skillFileSha256 = sha256FromSql(raw.sha256, "Skill raw result sha256");
+  if (!isValidSkillName(name)) {
+    throw new Error("Successful Skill raw result name is invalid.");
+  }
+  if (status === "already_loaded") {
+    assertObjectKeys(
+      raw,
+      ["kind", "ok", "status", "name", "scope", "lifecycle", "sha256"],
+      ["kind", "ok", "status", "name", "scope", "lifecycle", "sha256"],
+      "already loaded Skill raw result",
+    );
+    return immutableRecord({
+      kind: "skill" as const,
+      ok: true as const,
+      status,
+      name,
+      scope,
+      lifecycle: enumFromSql(
+        raw.lifecycle,
+        ["pending", "dispatched"] as const,
+        "Skill lifecycle",
+      ),
+      sha256: skillFileSha256,
+    });
+  }
+  if (status === "already_active") {
+    assertObjectKeys(
+      raw,
+      ["kind", "ok", "status", "name", "scope", "sha256"],
+      ["kind", "ok", "status", "name", "scope", "sha256"],
+      "already active Skill raw result",
+    );
+    return immutableRecord({
+      kind: "skill" as const,
+      ok: true as const,
+      status,
+      name,
+      scope,
+      sha256: skillFileSha256,
+    });
+  }
+  assertObjectKeys(
+    raw,
+    [
+      "kind",
+      "ok",
+      "status",
+      "name",
+      "scope",
+      "directory",
+      "skillFilePath",
+      "content",
+      "byteLength",
+      "sha256",
+      "resources",
+      "resourcesTruncated",
+    ],
+    [
+      "kind",
+      "ok",
+      "status",
+      "name",
+      "scope",
+      "directory",
+      "skillFilePath",
+      "content",
+      "byteLength",
+      "sha256",
+      "resources",
+      "resourcesTruncated",
+    ],
+    "loaded Skill raw result",
+  );
+  if (
+    !Array.isArray(raw.resources) ||
+    raw.resources.some((entry) => typeof entry !== "string") ||
+    raw.resources.length > SKILL_RESOURCE_MAX_ENTRIES ||
+    typeof raw.resourcesTruncated !== "boolean"
+  ) {
+    throw new Error("Loaded Skill resource manifest is invalid.");
+  }
+  const directory = stringFromSql(raw.directory, "Skill directory");
+  const skillFilePath = stringFromSql(raw.skillFilePath, "Skill file path");
+  const content = stringFromSql(raw.content, "Skill content");
+  const byteLength = numberFromJson(raw.byteLength, "Skill byteLength");
+  const resources = raw.resources as string[];
+  if (
+    !path.isAbsolute(directory) ||
+    !path.isAbsolute(skillFilePath) ||
+    !isPathWithin(directory, skillFilePath) ||
+    byteLength < 1 ||
+    byteLength > SKILL_FILE_MAX_BYTES ||
+    Buffer.byteLength(content, "utf8") !== byteLength ||
+    sha256(content) !== skillFileSha256 ||
+    !isValidResourceManifest(resources)
+  ) {
+    throw new Error("Loaded Skill raw result snapshot is invalid.");
+  }
+  return immutableRecord({
+    kind: "skill" as const,
+    ok: true as const,
+    status,
+    name,
+    scope,
+    directory,
+    skillFilePath,
+    content,
+    byteLength,
+    sha256: skillFileSha256,
+    resources: Object.freeze([...resources]),
+    resourcesTruncated: raw.resourcesTruncated,
+  });
+}
+
+function isValidSkillName(value: string): boolean {
+  return value.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+
+function isPathWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative !== "" &&
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+function isValidResourceManifest(resources: readonly string[]): boolean {
+  let previous: string | undefined;
+  for (const resource of resources) {
+    const parts = resource.split("/");
+    if (
+      resource === "" ||
+      resource.includes("\\") ||
+      path.posix.isAbsolute(resource) ||
+      path.posix.normalize(resource) !== resource ||
+      !["assets", "references", "scripts"].includes(parts[0] ?? "") ||
+      parts.length < 2 ||
+      parts.length > SKILL_RESOURCE_MAX_DEPTH + 1 ||
+      (previous !== undefined && previous >= resource)
+    ) {
+      return false;
+    }
+    previous = resource;
+  }
+  return true;
+}
+
 function decodeMeasuredContextState(
   value: unknown,
   expectedSessionId: SessionId,
@@ -2535,9 +4983,12 @@ function assertCommitSwapRevisionInput(input: CommitSwapRevisionInput): void {
     throw new Error("Commit swap revision input is invalid.");
   }
   for (const [name, hash] of [
-    ["expectedBaseOverrideManifestSha256", input.expectedBaseOverrideManifestSha256],
+    [
+      "expectedBaseActiveOverrideManifestSha256",
+      input.expectedBaseActiveOverrideManifestSha256,
+    ],
     ["planHash", input.planHash],
-    ["nextOverrideManifestSha256", input.nextOverrideManifestSha256],
+    ["nextActiveOverrideManifestSha256", input.nextActiveOverrideManifestSha256],
     ["canonicalSequenceSha256", input.canonicalSequenceSha256],
     ["renderedMessageSha256", input.renderedMessageSha256],
   ] as const) {
@@ -2547,16 +4998,130 @@ function assertCommitSwapRevisionInput(input: CommitSwapRevisionInput): void {
   }
 }
 
-function decodeMeta(value: unknown, expectedSessionId: SessionId): StoredSessionMetaV5 {
+function assertCommitSurfaceRefreshInput(input: CommitSurfaceRefreshInput): void {
+  if (
+    input.revisionId.trim() === "" ||
+    input.expectedBaseRevisionId.trim() === "" ||
+    !Number.isSafeInteger(input.expectedBaseRevisionNumber) ||
+    input.expectedBaseRevisionNumber < 1 ||
+    !Number.isSafeInteger(input.expectedCanonicalThroughOrdinal) ||
+    input.expectedCanonicalThroughOrdinal < 1
+  ) {
+    throw new Error("Commit surface refresh input is invalid.");
+  }
+  for (const [name, hash] of [
+    [
+      "expectedBaseActiveOverrideManifestSha256",
+      input.expectedBaseActiveOverrideManifestSha256,
+    ],
+    ["changeManifestSha256", input.changeManifestSha256],
+    ["canonicalSequenceSha256", input.canonicalSequenceSha256],
+    ["renderedMessageSha256", input.renderedMessageSha256],
+  ] as const) {
+    if (!/^[0-9a-f]{64}$/.test(hash)) {
+      throw new Error(`Commit surface refresh ${name} must be a SHA-256 hash.`);
+    }
+  }
+}
+
+function assertCommitSkillsUpdateInput(input: CommitSkillsUpdateInput): void {
+  if (
+    input.revisionId.trim() === "" ||
+    input.expectedBaseRevisionId.trim() === "" ||
+    !Number.isSafeInteger(input.expectedBaseRevisionNumber) ||
+    input.expectedBaseRevisionNumber < 1 ||
+    !Number.isSafeInteger(input.expectedCanonicalThroughOrdinal) ||
+    input.expectedCanonicalThroughOrdinal < 1 ||
+    input.addedOverrides.length < 1 ||
+    input.settlements.length !== input.addedOverrides.length
+  ) {
+    throw new Error("Commit Agent Skills update input is invalid.");
+  }
+  for (const [name, hash] of [
+    [
+      "expectedBaseActiveOverrideManifestSha256",
+      input.expectedBaseActiveOverrideManifestSha256,
+    ],
+    ["changeManifestSha256", input.changeManifestSha256],
+    ["activationManifestSha256", input.activationManifestSha256],
+    ["nextActiveOverrideManifestSha256", input.nextActiveOverrideManifestSha256],
+    ["canonicalSequenceSha256", input.canonicalSequenceSha256],
+    ["renderedMessageSha256", input.renderedMessageSha256],
+  ] as const) {
+    if (!/^[0-9a-f]{64}$/.test(hash)) {
+      throw new Error(`Commit Agent Skills update ${name} must be a SHA-256 hash.`);
+    }
+  }
+}
+
+function assertCommitPrefixRetirementRevisionInput(
+  input: CommitPrefixRetirementRevisionInput,
+): void {
+  if (
+    input.revisionId.trim() === "" ||
+    input.expectedBaseRevisionId.trim() === "" ||
+    input.policyVersion !== "recall-first-retirement-v1" ||
+    !Number.isSafeInteger(input.expectedBaseRevisionNumber) ||
+    input.expectedBaseRevisionNumber < 1 ||
+    !Number.isSafeInteger(input.expectedBaseKeepFromOrdinal) ||
+    input.expectedBaseKeepFromOrdinal < 1 ||
+    !Number.isSafeInteger(input.expectedCanonicalThroughOrdinal) ||
+    input.expectedCanonicalThroughOrdinal < 1 ||
+    !Number.isSafeInteger(input.nextKeepFromOrdinal) ||
+    input.nextKeepFromOrdinal <= input.expectedBaseKeepFromOrdinal ||
+    input.retiredThroughOrdinal !== input.nextKeepFromOrdinal - 1 ||
+    !Number.isSafeInteger(input.retiredTurnCount) ||
+    input.retiredTurnCount < 1 ||
+    !Number.isSafeInteger(input.retiredFrameCount) ||
+    input.retiredFrameCount < 1 ||
+    !Number.isSafeInteger(input.retiredMessageCount) ||
+    input.retiredMessageCount < 1 ||
+    !Number.isSafeInteger(input.nextActiveOverrideCount) ||
+    input.nextActiveOverrideCount < 0
+  ) {
+    throw new Error("Commit prefix retirement input is invalid.");
+  }
+  for (const [name, hash] of [
+    ["expectedSurfaceSha256", input.expectedSurfaceSha256],
+    [
+      "expectedBaseActiveOverrideManifestSha256",
+      input.expectedBaseActiveOverrideManifestSha256,
+    ],
+    ["planHash", input.planHash],
+    ["nextActiveOverrideManifestSha256", input.nextActiveOverrideManifestSha256],
+    ["canonicalSequenceSha256", input.canonicalSequenceSha256],
+    ["renderedMessageSha256", input.renderedMessageSha256],
+  ] as const) {
+    if (!/^[0-9a-f]{64}$/.test(hash)) {
+      throw new Error(`Commit prefix retirement ${name} must be a SHA-256 hash.`);
+    }
+  }
+}
+
+function requireActiveRevisionId(meta: StoredSessionMetaV9): ContextRevisionId {
+  if (meta.initializationState !== "ready" || meta.activeRevisionId === null) {
+    throw new Error("Session has no active context revision.");
+  }
+  return meta.activeRevisionId;
+}
+
+function previousRevision(
+  revisions: readonly StoredContextRevisionV8[],
+  revision: StoredContextRevisionV8,
+): StoredContextRevisionV8 | undefined {
+  return revisions[revision.revisionNumber - 2];
+}
+
+function decodeMeta(value: unknown, expectedSessionId: SessionId): StoredSessionMetaV9 {
   const row = recordFromSql(value, "session metadata");
   const sessionId = stringFromSql(row.session_id, "session_id") as SessionId;
   if (sessionId !== expectedSessionId) {
     throw new Error(`Metadata session ID ${sessionId} does not match directory.`);
   }
   const schemaVersion = numberFromSql(row.schema_version, "schema_version");
-  if (schemaVersion !== 5) {
+  if (schemaVersion !== 9) {
     throw new Error(
-      `Session metadata schema version must be 5; received ${schemaVersion}.`,
+      `Session metadata schema version must be 9; received ${schemaVersion}.`,
     );
   }
   const projectInstructionFile = nullableStringFromSql(
@@ -2594,35 +5159,52 @@ function decodeMeta(value: unknown, expectedSessionId: SessionId): StoredSession
           byteLength: projectInstructionByteLength,
           sha256: sha256FromSql(projectInstructionSha256, "project_instruction_sha256"),
         };
+  const initializationState = enumFromSql(
+    row.initialization_state,
+    ["creating", "ready"] as const,
+    "initialization_state",
+  );
+  const sessionCompatibilityJson = nullableStringFromSql(
+    row.session_compatibility_json,
+    "session_compatibility_json",
+  );
+  const sessionCompatibilitySha256 = nullableStringFromSql(
+    row.session_compatibility_sha256,
+    "session_compatibility_sha256",
+  );
+  const activeRevisionId = nullableStringFromSql(
+    row.active_revision_id,
+    "active_revision_id",
+  ) as ContextRevisionId | null;
+  const modelName = stringFromSql(row.model_name, "model_name");
+  const storedContract =
+    sessionCompatibilityJson === null
+      ? undefined
+      : decodeSessionCompatibilityContract(sessionCompatibilityJson);
+  if (
+    (sessionCompatibilityJson === null) !== (sessionCompatibilitySha256 === null) ||
+    (sessionCompatibilityJson !== null &&
+      sha256(sessionCompatibilityJson) !== sessionCompatibilitySha256) ||
+    (initializationState === "creating") !== (activeRevisionId === null) ||
+    (initializationState === "creating") !== (sessionCompatibilityJson === null) ||
+    (storedContract !== undefined &&
+      (storedContract.modelName !== modelName ||
+        stableJsonStringify(storedContract) !== sessionCompatibilityJson))
+  ) {
+    throw new Error("Session compatibility or initialization metadata is invalid.");
+  }
   return {
     schemaVersion,
     schemaFingerprint: stringFromSql(row.schema_fingerprint, "schema_fingerprint"),
-    initializationState: enumFromSql(
-      row.initialization_state,
-      ["creating", "ready"] as const,
-      "initialization_state",
-    ),
+    initializationState,
     sessionId,
     workspaceRoot: stringFromSql(row.workspace_root, "workspace_root"),
-    modelName: stringFromSql(row.model_name, "model_name"),
+    modelName,
     systemPromptSha256: stringFromSql(row.system_prompt_sha256, "system_prompt_sha256"),
     ...(projectInstruction === undefined ? {} : { projectInstruction }),
-    toolSchemaSha256: nullableStringFromSql(
-      row.tool_schema_sha256,
-      "tool_schema_sha256",
-    ),
-    runtimeContractJson: nullableStringFromSql(
-      row.runtime_contract_json,
-      "runtime_contract_json",
-    ),
-    runtimeContractSha256: nullableStringFromSql(
-      row.runtime_contract_sha256,
-      "runtime_contract_sha256",
-    ),
-    activeRevisionId: stringFromSql(
-      row.active_revision_id,
-      "active_revision_id",
-    ) as ContextRevisionId,
+    sessionCompatibilityJson,
+    sessionCompatibilitySha256,
+    activeRevisionId,
     nextTurnNumber: numberFromSql(row.next_turn_number, "next_turn_number"),
     nextEventSequence: numberFromSql(row.next_event_sequence, "next_event_sequence"),
     openCount: numberFromSql(row.open_count, "open_count"),
@@ -2650,23 +5232,197 @@ function decodeMeta(value: unknown, expectedSessionId: SessionId): StoredSession
   };
 }
 
-function runtimeContractDifferences(
+function compatibilityContractDifferences(
   storedJson: string | null,
-  current: RuntimeContractV1,
+  current: SessionCompatibilityContract,
 ): string[] {
   if (storedJson === null) {
-    return ["runtimeContract"];
+    return ["sessionCompatibility"];
   }
-  const stored = parseJson(storedJson, "runtime_contract_json");
+  const stored = parseJson(storedJson, "session_compatibility_json");
   if (typeof stored !== "object" || stored === null || Array.isArray(stored)) {
-    return ["runtimeContract"];
+    return ["sessionCompatibility"];
   }
   const record = stored as Record<string, unknown>;
-  return Object.keys(current).filter(
-    (key) =>
-      stableJsonStringify(record[key]) !==
-      stableJsonStringify(current[key as keyof RuntimeContractV1]),
+  const fields: readonly (keyof SessionCompatibilityContract)[] = [
+    "modelName",
+    "profileName",
+    "includeReasoningContent",
+    "contextProfile",
+    "messageProtocol",
+    "imageInput",
+  ];
+  return fields.filter((key) => {
+    const storedValue = record[key];
+    const currentValue = current[key];
+    if (storedValue === undefined || currentValue === undefined) {
+      return storedValue !== currentValue;
+    }
+    return stableJsonStringify(storedValue) !== stableJsonStringify(currentValue);
+  });
+}
+
+function decodeSessionCompatibilityContract(
+  json: string,
+): SessionCompatibilityContract {
+  const record = recordFromSql(
+    parseJson(json, "session_compatibility_json"),
+    "session compatibility contract",
+  );
+  assertObjectKeys(
+    record,
+    [
+      "modelName",
+      "profileName",
+      "includeReasoningContent",
+      "contextProfile",
+      "messageProtocol",
+      "imageInput",
+    ],
+    [
+      "modelName",
+      "includeReasoningContent",
+      "contextProfile",
+      "messageProtocol",
+      "imageInput",
+    ],
+    "session compatibility contract",
+  );
+  const contextProfile = recordFromSql(
+    record.contextProfile,
+    "session compatibility context profile",
+  );
+  assertObjectKeys(
+    contextProfile,
+    ["contextWindowTokens", "maxSupportedOutputTokens"],
+    ["contextWindowTokens", "maxSupportedOutputTokens"],
+    "session compatibility context profile",
+  );
+  const messageProtocol = recordFromSql(
+    record.messageProtocol,
+    "session compatibility message protocol",
+  );
+  assertObjectKeys(
+    messageProtocol,
+    ["adapter", "serializationVersion"],
+    ["adapter", "serializationVersion"],
+    "session compatibility message protocol",
+  );
+  const imageInput = recordFromSql(
+    record.imageInput,
+    "session compatibility image input",
+  );
+  assertObjectKeys(
+    imageInput,
+    ["policyVersion", "policySha256", "inputModalities", "tokenEstimator"],
+    ["policyVersion", "policySha256", "inputModalities"],
+    "session compatibility image input",
+  );
+  const inputModalities = imageInput.inputModalities;
+  if (!Array.isArray(inputModalities)) {
+    throw new Error("Session compatibility input modalities must be an array.");
+  }
+  const tokenEstimator =
+    imageInput.tokenEstimator === undefined
+      ? undefined
+      : decodeTokenEstimatorCompatibility(imageInput.tokenEstimator);
+  if (typeof record.includeReasoningContent !== "boolean") {
+    throw new Error("Session compatibility reasoning replay flag must be boolean.");
+  }
+  const modelName = stringFromSql(record.modelName, "compatibility modelName");
+  const profileName =
+    record.profileName === undefined
+      ? undefined
+      : stringFromSql(record.profileName, "compatibility profileName");
+  const context = createModelContextProfile({
+    contextWindowTokens: numberFromJson(
+      contextProfile.contextWindowTokens,
+      "compatibility contextWindowTokens",
+    ),
+    maxSupportedOutputTokens: numberFromJson(
+      contextProfile.maxSupportedOutputTokens,
+      "compatibility maxSupportedOutputTokens",
+    ),
+  });
+  const protocol: ModelMessageProtocol = Object.freeze({
+    adapter: enumFromSql(
+      messageProtocol.adapter,
+      ["openai-chat", "fake"] as const,
+      "compatibility message adapter",
+    ),
+    serializationVersion: stringFromSql(
+      messageProtocol.serializationVersion,
+      "compatibility serializationVersion",
+    ),
+  });
+  const modalities = normalizeInputModalities(
+    inputModalities.map((value) =>
+      enumFromSql(value, ["text", "image"] as const, "compatibility input modality"),
+    ),
+  );
+  if (modalities.includes("image") && tokenEstimator === undefined) {
+    throw new Error("Stored image input compatibility has no token estimator.");
+  }
+  const policyVersion = stringFromSql(
+    imageInput.policyVersion,
+    "compatibility image policyVersion",
+  );
+  const policySha256 = stringFromSql(
+    imageInput.policySha256,
+    "compatibility image policySha256",
+  );
+  if (!/^[0-9a-f]{64}$/.test(policySha256)) {
+    throw new Error("Session image policy hash is invalid.");
+  }
+  return Object.freeze({
+    modelName,
+    ...(record.profileName === undefined ? {} : { profileName: profileName! }),
+    includeReasoningContent: record.includeReasoningContent,
+    contextProfile: Object.freeze(context),
+    messageProtocol: protocol,
+    imageInput: Object.freeze({
+      policyVersion,
+      policySha256,
+      inputModalities: modalities,
+      ...(tokenEstimator === undefined ? {} : { tokenEstimator }),
+    }),
+  });
+}
+
+function decodeTokenEstimatorCompatibility(
+  value: unknown,
+): InputTokenEstimatorCompatibility {
+  const record = recordFromSql(value, "session compatibility token estimator");
+  assertObjectKeys(
+    record,
+    ["kind", "coverageVersion", "model", "endpoint", "timeoutMs", "maxRetries"],
+    ["kind", "coverageVersion", "model", "endpoint", "timeoutMs", "maxRetries"],
+    "session compatibility token estimator",
   );
+  const estimator: InputTokenEstimatorCompatibility = {
+    kind: enumFromSql(
+      record.kind,
+      ["moonshot-estimate-token-count-v1"] as const,
+      "compatibility token estimator kind",
+    ),
+    coverageVersion: enumFromSql(
+      record.coverageVersion,
+      ["full-request-v1"] as const,
+      "compatibility token estimator coverage",
+    ),
+    model: stringFromSql(record.model, "compatibility token estimator model"),
+    endpoint: stringFromSql(record.endpoint, "compatibility token estimator endpoint"),
+    timeoutMs: numberFromJson(
+      record.timeoutMs,
+      "compatibility token estimator timeoutMs",
+    ),
+    maxRetries: zeroFromJson(
+      record.maxRetries,
+      "compatibility token estimator maxRetries",
+    ),
+  };
+  validateTokenEstimatorCompatibility(estimator);
+  return Object.freeze(estimator);
 }
 
 function openWritableDatabase(databasePath: string): Database {
@@ -2696,6 +5452,250 @@ function runTransaction<T>(database: Database, operation: () => T): T {
   }
 }
 
+const SESSION_SCOPED_TABLES = [
+  "session_meta",
+  "turns",
+  "iterations",
+  "protocol_frames",
+  "messages",
+  "tool_results",
+  "context_surfaces",
+  "context_revisions",
+  "context_overrides",
+  "skill_activations",
+  "context_measurement_state",
+] as const;
+
+function rekeyStoredToolCalls(database: Database, targetSessionId: SessionId): void {
+  const rows = database
+    .query(
+      `SELECT message_id, tool_calls_json FROM messages
+       WHERE tool_calls_json IS NOT NULL ORDER BY ordinal`,
+    )
+    .all() as Array<{ message_id: string; tool_calls_json: string }>;
+  for (const row of rows) {
+    const calls = decodeStoredToolCalls(row.tool_calls_json).map((call) => ({
+      ...call,
+      sessionId: targetSessionId,
+    }));
+    database
+      .query("UPDATE messages SET tool_calls_json = ? WHERE message_id = ?")
+      .run(stableJsonStringify(calls), row.message_id);
+  }
+}
+
+function rekeyProtocolView(
+  source: ProtocolContextView,
+  targetSessionId: SessionId,
+): ProtocolContextView {
+  return {
+    sessionId: targetSessionId,
+    faulted: source.faulted,
+    frames: source.frames.map((frame) => ({
+      ...frame,
+      sessionId: targetSessionId,
+    })),
+    messages: source.messages.map((message) => ({
+      ...message,
+      sessionId: targetSessionId,
+      ...(message.role === "assistant" && message.toolCalls !== undefined
+        ? {
+            toolCalls: message.toolCalls.map((call) => ({
+              ...call,
+              sessionId: targetSessionId,
+            })),
+          }
+        : {}),
+    })),
+    toolResults: source.toolResults.map((result) => ({
+      ...result,
+      sessionId: targetSessionId,
+    })),
+  };
+}
+
+function rewriteCloneRevisionHashes(
+  database: Database,
+  canonical: ProtocolContextView,
+): void {
+  const surfaces = database
+    .query("SELECT * FROM context_surfaces")
+    .all()
+    .map(decodeContextSurface);
+  const surfacesById = new Map(surfaces.map((surface) => [surface.surfaceId, surface]));
+  const revisions = database
+    .query("SELECT * FROM context_revisions ORDER BY revision_number")
+    .all()
+    .map(decodeContextRevision);
+  const revisionNumberById = new Map(
+    revisions.map((revision) => [revision.revisionId, revision.revisionNumber]),
+  );
+  const overrides = database
+    .query(
+      `SELECT co.* FROM context_overrides co
+       JOIN context_revisions cr ON cr.revision_id = co.introduced_revision_id
+       ORDER BY cr.revision_number, co.ordinal`,
+    )
+    .all()
+    .map(decodeStoredSwapOverride);
+  const compiler = new ContextRevisionCompiler();
+  for (const revision of revisions) {
+    const surface = surfacesById.get(revision.surfaceId);
+    if (surface === undefined) {
+      throw new Error(`Cloned revision ${revision.revisionId} has no surface.`);
+    }
+    const activeOverrides = overrides.filter(
+      (override) =>
+        (revisionNumberById.get(override.introducedRevisionId) ??
+          Number.POSITIVE_INFINITY) <= revision.revisionNumber &&
+        override.ordinal >= revision.keepFromOrdinal,
+    );
+    const prefix = protocolPrefixView(canonical, revision.sourceThroughOrdinal);
+    const compiled = compiler.compileForIdentityRekey({
+      canonical: prefix,
+      revisionId: revision.revisionId,
+      activeOverrides,
+      keepFromOrdinal: revision.keepFromOrdinal,
+      surface,
+    });
+    database
+      .query(
+        `UPDATE context_revisions
+         SET canonical_sequence_sha256 = ?, rendered_message_sha256 = ?
+         WHERE revision_id = ?`,
+      )
+      .run(
+        canonicalSequenceHash(canonical, revision.sourceThroughOrdinal),
+        renderedMessageHash(compiled.entries, revision.sourceThroughOrdinal),
+        revision.revisionId,
+      );
+  }
+}
+
+async function cloneDiagnosticFiles(input: {
+  sourceDirectory: string;
+  stagingDirectory: string;
+  sourceSessionId: SessionId;
+  targetSessionId: SessionId;
+  nextEventSequence: number;
+  faultInjector?: (stage: CloneSessionFaultStage) => void;
+}): Promise<void> {
+  const sourcePath = path.join(input.sourceDirectory, "events.jsonl");
+  try {
+    await lstat(sourcePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  await validateSecureFile(sourcePath, input.sourceSessionId);
+
+  const bytes = await readFile(sourcePath);
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const rawLines = text.split("\n");
+  if (rawLines.at(-1) === "") {
+    rawLines.pop();
+  }
+  const events: AgentEvent[] = [];
+  let previousSequence = 0;
+  for (const [index, line] of rawLines.entries()) {
+    if (line === "") {
+      throw new Error(`Session event log contains an empty line at ${index + 1}.`);
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Session event log has invalid JSON at line ${index + 1}.`, {
+        cause: error,
+      });
+    }
+    if (!isEventEnvelope(value)) {
+      throw new Error(
+        `Session event log has an invalid envelope at line ${index + 1}.`,
+      );
+    }
+    if (value.sessionId !== input.sourceSessionId) {
+      throw new Error(`Session event log identity changed at line ${index + 1}.`);
+    }
+    if (value.eventSequence <= previousSequence) {
+      throw new Error(
+        `Session event sequence is not strictly increasing at line ${index + 1}.`,
+      );
+    }
+    if (value.eventSequence >= input.nextEventSequence) {
+      throw new Error(
+        `Session event sequence exceeds the canonical next counter at line ${index + 1}.`,
+      );
+    }
+    previousSequence = value.eventSequence;
+    events.push({ ...value, sessionId: input.targetSessionId });
+  }
+
+  const eventText = events.map((event) => JSON.stringify(event)).join("\n");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "events.jsonl"),
+    eventText === "" ? "" : `${eventText}\n`,
+  );
+  input.faultInjector?.("after_event_rewrite");
+  const observationText = events
+    .map((event) => renderObservationLogEvent(event))
+    .filter((block): block is string => block !== undefined)
+    .join("");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "observations.md"),
+    observationText,
+  );
+  input.faultInjector?.("after_observation_render");
+}
+
+function isEventEnvelope(value: unknown): value is AgentEvent {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.sessionId === "string" &&
+    Number.isSafeInteger(record.eventSequence) &&
+    Number(record.eventSequence) >= 1 &&
+    typeof record.timestamp === "string" &&
+    typeof record.type === "string" &&
+    record.data !== null &&
+    typeof record.data === "object"
+  );
+}
+
+async function writePrivateNewFile(filePath: string, content: string): Promise<void> {
+  const handle = await open(filePath, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+  } finally {
+    await handle.close();
+  }
+  await chmod(filePath, 0o600);
+}
+
+async function assertPathMissing(
+  filePath: string,
+  sessionId: SessionId,
+): Promise<void> {
+  try {
+    await lstat(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  throw new SessionError(
+    "SESSION_ALREADY_EXISTS",
+    "clone_session",
+    `Session directory already exists: ${filePath}.`,
+    { sessionId },
+  );
+}
+
 async function canonicalWorkspaceRoot(workspaceRoot: string): Promise<string> {
   if (!path.isAbsolute(workspaceRoot)) {
     throw new Error("Session workspace root must be absolute.");
@@ -3020,6 +6020,13 @@ function numberFromJson(value: unknown, name: string): number {
   return value as number;
 }
 
+function zeroFromJson(value: unknown, name: string): 0 {
+  if (value !== 0) {
+    throw new Error(`${name} must be 0.`);
+  }
+  return 0;
+}
+
 function enumFromSql<const T extends readonly string[]>(
   value: unknown,
   values: T,
@@ -3058,6 +6065,10 @@ function requireItem<T>(items: readonly T[], index: number, name: string): T {
   return item;
 }
 
+function compareCanonicalText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }