harnery 0.43.0 → 0.45.0

package/src/core/context/index.ts

@@ -8,15 +8,27 @@
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import type { Adapter } from "../adapter.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import { resolveBinName } from "../config.ts";
+import type { HarneryInboxMessageRecordV1 } from "../inbox/contract.ts";
+import { peerInbox } from "../inbox/peer-messages.ts";
+import { project } from "../inbox/service.ts";
 import { stateFileMode } from "../storage/modes.ts";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.ts";
+import type { RepoObservation, RepoSnapshot } from "./observation.ts";
+import { observationsComparable } from "./observation.ts";
+
+export type { RepoObservation, RepoSnapshot } from "./observation.ts";
+export { observationsComparable } from "./observation.ts";
 
 export const CONTEXT_SCHEMA_VERSION = 1 as const;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
 const MAX_SNAPSHOT_PATHS = 15;
 const MAX_SNAPSHOT_PATH_CHARS = 500;
+const MAX_OBSERVATION_DETAIL_CHARS = 500;
+const MAX_RECOVERY_INPUT_BODY_BYTES = 160;
 
 export type ContextSampleSource = "hook" | "native_event" | "result" | "transcript" | "estimate";
 export type ContextSampleConfidence = "exact" | "reported" | "estimated";
@@ -49,15 +61,6 @@ export interface ContextContinuityState {
   degraded_reason?: string;
 }
 
-export interface RepoSnapshot {
-  cwd: string;
-  root?: string;
-  branch?: string;
-  head?: string;
-  dirty_paths: string[];
-  dirty_paths_truncated?: boolean;
-}
-
 export interface ContinuityCapsule {
   schema_version: typeof CONTEXT_SCHEMA_VERSION;
   capsule_id: string;
@@ -113,7 +116,20 @@ export interface RecoverContextResult {
   recovered: boolean;
 }
 
+/**
+ * Authority for accepting exactly the capsule supplied during preparation.
+ * It is returned by prepareContextRecovery, not reconstructed from latest state.
+ */
+export interface PreparedContextCheckpoint {
+  session_id: string;
+  instance_id: string;
+  generation: number;
+  capsule_id: string;
+  capsule_sha256: string;
+}
+
 export interface PreparedContextRecovery {
+  checkpoint: Readonly<PreparedContextCheckpoint>;
   state: ContextContinuityState;
   capsule: ContinuityCapsule;
   briefing: string;
@@ -190,19 +206,26 @@ export function recordContextSample(
   instanceId: string,
   sample: ContextSample,
 ): { state: ContextContinuityState; changed: boolean } {
-  const current = readContextState(coordRoot, sample.session_id);
-  const state =
-    current ?? newState({ sessionId: sample.session_id, instanceId, now: sample.observed_at });
-  const changed = !sameMeasurement(state.latest_context, sample);
-  if (!changed) return { state, changed: false };
-  const next: ContextContinuityState = {
-    ...state,
-    instance_id: instanceId,
-    latest_context: sample,
-    updated_at: sample.observed_at,
-  };
-  writeState(coordRoot, next);
-  return { state: next, changed: true };
+  return withContextMutation(coordRoot, sample.session_id, () => {
+    const current = readContextState(coordRoot, sample.session_id);
+    const state =
+      current?.instance_id === instanceId
+        ? current
+        : {
+            ...newState({ sessionId: sample.session_id, instanceId, now: sample.observed_at }),
+            generation: current?.generation ?? 0,
+          };
+    const changed = !sameMeasurement(state.latest_context, sample);
+    if (!changed) return { state, changed: false };
+    const next: ContextContinuityState = {
+      ...state,
+      instance_id: instanceId,
+      latest_context: sample,
+      updated_at: sample.observed_at,
+    };
+    writeState(coordRoot, next);
+    return { state: next, changed: true };
+  });
 }
 
 /**
@@ -214,57 +237,64 @@ export function checkpointContext(
   coordRoot: string,
   input: CheckpointContextInput,
 ): CheckpointContextResult {
-  const now = new Date().toISOString();
-  const current =
-    readContextState(coordRoot, input.sessionId) ??
-    newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-  if (input.reason === "pre_compact" && current.phase === "checkpointed") {
-    const existing = readLatestCapsule(coordRoot, input.sessionId);
-    if (existing && current.latest_capsule) {
-      return {
-        capsule: existing,
-        path: join(coordRoot, ".harnery", current.latest_capsule),
-        state: current,
-        reused: true,
-      };
+  return withContextMutation(coordRoot, input.sessionId, () => {
+    const now = new Date().toISOString();
+    const previous = readContextState(coordRoot, input.sessionId);
+    const current =
+      previous?.instance_id === input.instanceId
+        ? previous
+        : {
+            ...newState({ sessionId: input.sessionId, instanceId: input.instanceId, now }),
+            generation: previous?.generation ?? 0,
+          };
+    if (input.reason === "pre_compact" && current.phase === "checkpointed") {
+      const existing = readLatestCapsule(coordRoot, input.sessionId);
+      if (existing && capsuleMatchesState(current, existing, input) && current.latest_capsule) {
+        return {
+          capsule: existing,
+          path: join(coordRoot, ".harnery", current.latest_capsule),
+          state: current,
+          reused: true,
+        };
+      }
     }
-  }
 
-  const heartbeat = readHeartbeat(coordRoot, input.instanceId);
-  const generation = current.generation + 1;
-  const capsule: ContinuityCapsule = {
-    schema_version: CONTEXT_SCHEMA_VERSION,
-    capsule_id: randomUUID(),
-    generation,
-    created_at: now,
-    reason: input.reason,
-    session: {
-      session_id: input.sessionId,
-      instance_id: input.instanceId,
-      adapter: input.adapter,
-      model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
-    },
-    context: current.latest_context,
-    work: buildWorkSnapshot(heartbeat, input.continuationNote),
-    repo: snapshotRepo(input.cwd),
-  };
+    const heartbeat = readHeartbeat(coordRoot, input.instanceId);
+    const generation = current.generation + 1;
+    const capsule: ContinuityCapsule = {
+      schema_version: CONTEXT_SCHEMA_VERSION,
+      capsule_id: randomUUID(),
+      generation,
+      created_at: now,
+      reason: input.reason,
+      session: {
+        session_id: input.sessionId,
+        instance_id: input.instanceId,
+        adapter: input.adapter,
+        model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
+      },
+      context: current.latest_context,
+      work: buildWorkSnapshot(heartbeat, input.continuationNote),
+      repo: snapshotRepo(input.cwd),
+    };
 
-  const relativePath = capsuleRelativePath(input.sessionId, generation);
-  const absolutePath = join(coordRoot, ".harnery", relativePath);
-  writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
-  const next: ContextContinuityState = {
-    ...current,
-    instance_id: input.instanceId,
-    phase: "checkpointed",
-    generation,
-    latest_capsule: relativePath,
-    updated_at: now,
-    recovered_at: undefined,
-    compaction_completed_at: undefined,
-    degraded_reason: undefined,
-  };
-  writeState(coordRoot, next);
-  return { capsule, path: absolutePath, state: next, reused: false };
+    const relativePath = capsuleRelativePath(input.sessionId, generation);
+    const absolutePath = join(coordRoot, ".harnery", relativePath);
+    writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
+    const next: ContextContinuityState = {
+      ...current,
+      instance_id: input.instanceId,
+      phase: "checkpointed",
+      generation,
+      latest_capsule: relativePath,
+      updated_at: now,
+      recovered_at: undefined,
+      compaction_completed_at: undefined,
+      degraded_reason: undefined,
+    };
+    writeState(coordRoot, next);
+    return { capsule, path: absolutePath, state: next, reused: false };
+  });
 }
 
 /** Prepare a briefing without claiming that a adapter has accepted it yet. */
@@ -272,47 +302,156 @@ export function prepareContextRecovery(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; cwd: string },
 ): PreparedContextRecovery | null {
-  const now = new Date().toISOString();
-  const current =
-    readContextState(coordRoot, input.sessionId) ??
-    newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-  const capsule = readLatestCapsule(coordRoot, input.sessionId);
-  if (!capsule) {
-    const degraded: ContextContinuityState = {
-      ...current,
-      instance_id: input.instanceId,
-      phase: "degraded",
-      updated_at: now,
-      degraded_reason: "post-compaction signal arrived without a continuity checkpoint",
+  return withContextMutation(coordRoot, input.sessionId, () => {
+    const now = new Date().toISOString();
+    const current =
+      readContextState(coordRoot, input.sessionId) ??
+      newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    // A reused provider ID does not transfer the prior task's context.
+    if (current.instance_id !== input.instanceId) return null;
+    const capsule = readLatestCapsule(coordRoot, input.sessionId);
+    if (!capsule || !capsuleMatchesState(current, capsule, input)) {
+      const degraded: ContextContinuityState = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: "degraded",
+        updated_at: now,
+        degraded_reason: capsule
+          ? "continuity checkpoint does not match the requesting instance and state"
+          : "post-compaction signal arrived without a continuity checkpoint",
+      };
+      writeState(coordRoot, degraded);
+      return null;
+    }
+
+    const liveRepo = snapshotRepo(input.cwd);
+    const briefing = [
+      renderRecoveryBriefing(capsule, liveRepo),
+      renderRecoveryInput(coordRoot, input.instanceId),
+    ]
+      .filter(Boolean)
+      .join("\n\n");
+    return {
+      state: current,
+      capsule,
+      briefing,
+      checkpoint: Object.freeze({
+        session_id: input.sessionId,
+        instance_id: input.instanceId,
+        generation: capsule.generation,
+        capsule_id: capsule.capsule_id,
+        capsule_sha256: capsuleDigest(capsule),
+      }),
     };
-    writeState(coordRoot, degraded);
-    return null;
+  });
+}
+
+/** Recovery lists input without surfacing it again or changing its receipts. */
+function renderRecoveryInput(coordRoot: string, instanceId: string): string {
+  const readCommand = `${resolveBinName(coordRoot)} agents inbox list ${instanceId}`;
+  try {
+    const records = peerInbox(coordRoot).records(instanceId);
+    if (
+      records.some(
+        (record) =>
+          (record.kind !== "message" && record.kind !== "surfaced") ||
+          typeof record.message_id !== "string" ||
+          Buffer.byteLength(record.message_id) > 128,
+      )
+    ) {
+      throw new Error("inbox input cannot be listed safely");
+    }
+    const { surfaced } = project(records);
+    const messages = records.filter(
+      (record): record is HarneryInboxMessageRecordV1 =>
+        record.kind === "message" && record.recipient_instance_id === instanceId,
+    );
+    const pending = messages.filter((message) => !surfaced.has(message.message_id));
+    const recent = messages.filter((message) => surfaced.has(message.message_id)).slice(-10);
+    if (pending.length === 0 && recent.length === 0) return "";
+    const lines = [
+      "Coordination input after compaction (surfaced does not mean read):",
+      ...pending
+        .slice(0, 25)
+        .map((message) => inputLine(message.message_id, "pending", message.body)),
+      ...recent.map((message) =>
+        inputLine(message.message_id, "previously surfaced", message.body),
+      ),
+    ];
+    if (pending.length > 25)
+      lines.push(`${pending.length - 25} more pending messages are not listed.`);
+    lines.push(
+      `Recovery did not acknowledge these messages. Read pending input with \`${readCommand}\`.`,
+    );
+    return lines.join("\n");
+  } catch {
+    return `Coordination input could not be read. Check \`${readCommand}\` before continuing.`;
   }
+}
 
-  const liveRepo = snapshotRepo(input.cwd);
-  const briefing = renderRecoveryBriefing(capsule, liveRepo);
-  return { state: current, capsule, briefing };
+function inputLine(messageId: string, status: string, body: string): string {
+  const text = body.replace(/\s+/g, " ").trim();
+  let excerpt = "";
+  let bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > MAX_RECOVERY_INPUT_BODY_BYTES) break;
+    excerpt += character;
+    bytes += size;
+  }
+  return `- ${messageId} (${status}): ${excerpt}${excerpt.length < text.length ? " [excerpt]" : ""}`;
 }
 
-/** Advance continuity only after the adapter context channel accepted the briefing. */
+/**
+ * Advance continuity only after the adapter accepted the prepared briefing.
+ * Missing, altered, foreign or superseded checkpoints refuse without writing.
+ * Repeating the same accepted checkpoint is an exact no-op.
+ */
 export function completeContextRecovery(
   coordRoot: string,
-  input: { sessionId: string; instanceId: string },
-): ContextContinuityState {
-  const now = new Date().toISOString();
-  const current =
-    readContextState(coordRoot, input.sessionId) ??
-    newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-  const recovered: ContextContinuityState = {
-    ...current,
-    instance_id: input.instanceId,
-    phase: "recovered",
-    updated_at: now,
-    recovered_at: now,
-    degraded_reason: undefined,
-  };
-  writeState(coordRoot, recovered);
-  return recovered;
+  input: {
+    sessionId: string;
+    instanceId: string;
+    checkpoint: Readonly<PreparedContextCheckpoint>;
+  },
+): ContextContinuityState | null {
+  return withContextMutation(coordRoot, input.sessionId, () => {
+    const current = readContextState(coordRoot, input.sessionId);
+    const checkpoint = input.checkpoint;
+    if (
+      !current ||
+      !checkpoint ||
+      checkpoint.session_id !== input.sessionId ||
+      checkpoint.instance_id !== input.instanceId ||
+      !Number.isSafeInteger(checkpoint.generation) ||
+      checkpoint.generation < 1 ||
+      typeof checkpoint.capsule_id !== "string" ||
+      !checkpoint.capsule_id ||
+      !/^[a-f0-9]{64}$/.test(checkpoint.capsule_sha256) ||
+      (current.phase !== "checkpointed" && current.phase !== "recovered")
+    )
+      return null;
+    const capsule = readLatestCapsule(coordRoot, input.sessionId);
+    if (
+      !capsule ||
+      !capsuleMatchesState(current, capsule, input) ||
+      checkpoint.generation !== capsule.generation ||
+      checkpoint.capsule_id !== capsule.capsule_id ||
+      checkpoint.capsule_sha256 !== capsuleDigest(capsule)
+    )
+      return null;
+    if (current.phase === "recovered") return current;
+    const now = new Date().toISOString();
+    const recovered: ContextContinuityState = {
+      ...current,
+      phase: "recovered",
+      updated_at: now,
+      recovered_at: now,
+      degraded_reason: undefined,
+    };
+    writeState(coordRoot, recovered);
+    return recovered;
+  });
 }
 
 /** Record that the adapter, rather than Harnery, reported compaction complete. */
@@ -320,22 +459,25 @@ export function markContextCompactionCompleted(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; observedAt?: string },
 ): ContextContinuityState {
-  const now = input.observedAt ?? new Date().toISOString();
-  const current =
-    readContextState(coordRoot, input.sessionId) ??
-    newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-  const next: ContextContinuityState = {
-    ...current,
-    instance_id: input.instanceId,
-    phase: current.latest_capsule ? current.phase : "degraded",
-    compaction_completed_at: now,
-    updated_at: now,
-    degraded_reason: current.latest_capsule
-      ? current.degraded_reason
-      : "post-compaction signal arrived without a continuity checkpoint",
-  };
-  writeState(coordRoot, next);
-  return next;
+  return withContextMutation(coordRoot, input.sessionId, () => {
+    const now = input.observedAt ?? new Date().toISOString();
+    const current =
+      readContextState(coordRoot, input.sessionId) ??
+      newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    if (current.instance_id !== input.instanceId) return current;
+    const next: ContextContinuityState = {
+      ...current,
+      instance_id: input.instanceId,
+      phase: current.latest_capsule ? current.phase : "degraded",
+      compaction_completed_at: now,
+      updated_at: now,
+      degraded_reason: current.latest_capsule
+        ? current.degraded_reason
+        : "post-compaction signal arrived without a continuity checkpoint",
+    };
+    writeState(coordRoot, next);
+    return next;
+  });
 }
 
 /** Convenience API for callers whose injection is synchronous and guaranteed. */
@@ -348,7 +490,19 @@ export function recoverContext(
     const state = readContextState(coordRoot, input.sessionId)!;
     return { state, capsule: null, briefing: "", recovered: false };
   }
-  const recovered = completeContextRecovery(coordRoot, input);
+  const recovered = completeContextRecovery(coordRoot, {
+    sessionId: input.sessionId,
+    instanceId: input.instanceId,
+    checkpoint: prepared.checkpoint,
+  });
+  if (!recovered) {
+    return {
+      state: readContextState(coordRoot, input.sessionId) ?? prepared.state,
+      capsule: null,
+      briefing: "",
+      recovered: false,
+    };
+  }
   return {
     state: recovered,
     capsule: prepared.capsule,
@@ -366,8 +520,29 @@ export function readContextState(
 
 export function readLatestCapsule(coordRoot: string, sessionId: string): ContinuityCapsule | null {
   const state = readContextState(coordRoot, sessionId);
-  if (!state?.latest_capsule) return null;
-  return readJson<ContinuityCapsule>(join(coordRoot, ".harnery", state.latest_capsule));
+  if (typeof state?.latest_capsule !== "string" || !state.latest_capsule) return null;
+  const capsule = readJson<ContinuityCapsule>(join(coordRoot, ".harnery", state.latest_capsule));
+  if (
+    !capsule ||
+    !record(capsule.repo) ||
+    !record(capsule.work) ||
+    typeof capsule.repo.cwd !== "string" ||
+    !Array.isArray(capsule.repo.dirty_paths) ||
+    !capsule.repo.dirty_paths.every((path) => typeof path === "string") ||
+    !Array.isArray(capsule.work.files_held) ||
+    !capsule.work.files_held.every((path) => typeof path === "string")
+  ) {
+    return null;
+  }
+  capsule.repo.observation = repoObservation(capsule.repo.observation);
+  capsule.repo.observation_detail = clampString(
+    string(capsule.repo.observation_detail),
+    MAX_OBSERVATION_DETAIL_CHARS,
+  );
+  capsule.repo.branch = string(capsule.repo.branch)?.trim() || undefined;
+  capsule.repo.head = string(capsule.repo.head)?.trim() || undefined;
+  capsule.repo.root = string(capsule.repo.root)?.trim() || undefined;
+  return capsule;
 }
 
 export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: RepoSnapshot): string {
@@ -382,6 +557,42 @@ export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: Rep
     lines.push(`Files held: ${capsule.work.files_held.join(", ")}`);
   }
 
+  const unknown: string[] = [];
+  if (!observationsComparable(capsule.repo, liveRepo)) {
+    for (const [label, repo] of [
+      ["checkpoint", capsule.repo],
+      ["current repository", liveRepo],
+    ] as const) {
+      if (repo.observation !== "ok") {
+        const detail = clampString(string(repo.observation_detail), MAX_OBSERVATION_DETAIL_CHARS);
+        unknown.push(
+          `${label}: ${repoObservation(repo.observation)}${detail ? ` (${detail})` : ""}`,
+        );
+      }
+    }
+  }
+  if (capsule.repo.dirty_paths_truncated || liveRepo.dirty_paths_truncated) {
+    unknown.push("dirty path list is truncated");
+  }
+  if (
+    !capsule.repo.root ||
+    !liveRepo.root ||
+    !isAbsolute(capsule.repo.root) ||
+    !isAbsolute(liveRepo.root)
+  ) {
+    unknown.push("repository root is unknown");
+  } else if (capsule.repo.root !== liveRepo.root) {
+    unknown.push("repository root differs from the checkpoint");
+  }
+  if (!capsule.repo.branch?.trim() || !liveRepo.branch?.trim()) unknown.push("branch is unknown");
+  if (!capsule.repo.head?.trim() || !liveRepo.head?.trim()) unknown.push("HEAD is unknown");
+  if (unknown.length > 0) {
+    lines.push(
+      `Repository could not be verified against the checkpoint: ${unknown.join("; ")}. Re-check before editing.`,
+    );
+    return lines.join("\n");
+  }
+
   const drift: string[] = [];
   if (capsule.repo.branch && liveRepo.branch && capsule.repo.branch !== liveRepo.branch) {
     drift.push(`branch changed ${capsule.repo.branch} -> ${liveRepo.branch}`);
@@ -405,23 +616,60 @@ export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: Rep
 
 export function snapshotRepo(cwd: string): RepoSnapshot {
   const root = git(cwd, ["rev-parse", "--show-toplevel"]);
-  if (!root) return { cwd, dirty_paths: [] };
+  if (!root.ok || !root.out.trim()) {
+    return {
+      cwd: clampString(cwd, 2_000) ?? cwd,
+      observation: "unavailable",
+      observation_detail: `top-level: ${root.ok ? "empty result" : root.reason}`,
+      dirty_paths: [],
+    };
+  }
   const status = git(cwd, ["status", "--porcelain=v1", "--untracked-files=normal"]);
-  const dirty = status
-    ? status
+  const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const head = git(cwd, ["rev-parse", "HEAD"]);
+  const reads = [
+    ["status", status],
+    ["branch", branch],
+    ["HEAD", head],
+  ] as const;
+  const details = reads.flatMap(([label, read]) =>
+    !read.ok
+      ? [`${label}: ${read.reason}`]
+      : label !== "status" && !read.out.trim()
+        ? [`${label}: empty result`]
+        : [],
+  );
+  const dirty = status.ok
+    ? status.out
         .split("\n")
         .map((line) => line.trimEnd())
         .filter(Boolean)
-        .map((line) => clampString(line.slice(3).trim(), MAX_SNAPSHOT_PATH_CHARS) ?? "")
+        .map((line) => line.slice(3).trim())
         .filter(Boolean)
     : [];
+  const truncated =
+    dirty.length > MAX_SNAPSHOT_PATHS ||
+    dirty.some((path) => path.length > MAX_SNAPSHOT_PATH_CHARS);
+  if (truncated) details.push("dirty path list is truncated");
   return {
     cwd: clampString(cwd, 2_000) ?? cwd,
-    root: clampString(root, 2_000),
-    branch: git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
-    head: git(cwd, ["rev-parse", "HEAD"]),
-    dirty_paths: dirty.slice(0, MAX_SNAPSHOT_PATHS),
-    ...(dirty.length > MAX_SNAPSHOT_PATHS ? { dirty_paths_truncated: true } : {}),
+    observation: reads.some(([, read]) => !read.ok && read.reason === "timed_out")
+      ? "unavailable"
+      : details.length > 0
+        ? "partial"
+        : "ok",
+    ...(details.length > 0
+      ? {
+          observation_detail: clampString(details.join("; "), MAX_OBSERVATION_DETAIL_CHARS),
+        }
+      : {}),
+    root: clampString(root.out.trim(), 2_000),
+    branch: branch.ok ? branch.out.trim() || undefined : undefined,
+    head: head.ok ? head.out.trim() || undefined : undefined,
+    dirty_paths: dirty
+      .slice(0, MAX_SNAPSHOT_PATHS)
+      .map((path) => path.slice(0, MAX_SNAPSHOT_PATH_CHARS)),
+    ...(truncated ? { dirty_paths_truncated: true } : {}),
   };
 }
 
@@ -467,6 +715,47 @@ function newState(input: {
   };
 }
 
+function capsuleMatchesState(
+  state: ContextContinuityState,
+  capsule: ContinuityCapsule,
+  input: { sessionId: string; instanceId: string },
+): boolean {
+  return (
+    state.session_id === input.sessionId &&
+    state.instance_id === input.instanceId &&
+    capsule.session?.session_id === input.sessionId &&
+    capsule.session?.instance_id === input.instanceId &&
+    capsule.schema_version === CONTEXT_SCHEMA_VERSION &&
+    Number.isSafeInteger(capsule.generation) &&
+    capsule.generation > 0 &&
+    capsule.generation === state.generation &&
+    typeof capsule.capsule_id === "string" &&
+    capsule.capsule_id.length > 0 &&
+    state.latest_capsule === capsuleRelativePath(input.sessionId, capsule.generation)
+  );
+}
+
+function capsuleDigest(capsule: ContinuityCapsule): string {
+  return createHash("sha256").update(JSON.stringify(capsule)).digest("hex");
+}
+
+/** Every state writer shares the same crash-recoverable session reservation. */
+function withContextMutation<T>(coordRoot: string, sessionId: string, action: () => T): T {
+  const authority = createHash("sha256").update(sessionId).digest("hex");
+  const lease = acquireNoClobberLease({
+    path: join(contextDir(coordRoot, sessionId), "mutation.lease"),
+    scope: "context-continuity",
+    authoritySha256: authority,
+    staleAfterMs: 30_000,
+    validateStaleOwner: (owner) => owner.authority_sha256 === authority,
+  });
+  try {
+    return action();
+  } finally {
+    lease.release();
+  }
+}
+
 function writeState(coordRoot: string, state: ContextContinuityState): void {
   writeBoundedJson(statePath(coordRoot, state.session_id), state, MAX_CAPSULE_BYTES);
 }
@@ -513,15 +802,36 @@ function readJson<T>(path: string): T | null {
   }
 }
 
-function git(cwd: string, args: string[]): string | undefined {
+type GitReadResult =
+  | { ok: true; out: string }
+  | { ok: false; reason: "not_repository" | "failed" | "timed_out" | "spawn_error" };
+
+function git(cwd: string, args: string[]): GitReadResult {
   try {
     const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 2_000 });
-    return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+    if (result.error) {
+      return {
+        ok: false,
+        reason:
+          (result.error as NodeJS.ErrnoException).code === "ETIMEDOUT"
+            ? "timed_out"
+            : "spawn_error",
+      };
+    }
+    if (result.status === 0) return { ok: true, out: result.stdout.trimEnd() };
+    return {
+      ok: false,
+      reason: /not a git repository/i.test(result.stderr) ? "not_repository" : "failed",
+    };
   } catch {
-    return undefined;
+    return { ok: false, reason: "spawn_error" };
   }
 }
 
+function repoObservation(value: unknown): RepoObservation {
+  return value === "ok" || value === "partial" ? value : "unavailable";
+}
+
 function sameMeasurement(a: ContextSample | undefined, b: ContextSample): boolean {
   if (!a) return false;
   return (