harnery 0.45.0 → 0.45.2

package/src/core/context/index.ts

@@ -7,8 +7,8 @@
 
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join } from "node:path";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { Adapter } from "../adapter.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 import { resolveBinName } from "../config.ts";
@@ -16,12 +16,11 @@ 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";
+import type { RepoSnapshot } from "./observation.ts";
+import { repoComparisonProblems } from "./observation.ts";
 
 export type { RepoObservation, RepoSnapshot } from "./observation.ts";
-export { observationsComparable } from "./observation.ts";
+export { repoComparisonProblems } from "./observation.ts";
 
 export const CONTEXT_SCHEMA_VERSION = 1 as const;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
@@ -125,7 +124,6 @@ export interface PreparedContextCheckpoint {
   instance_id: string;
   generation: number;
   capsule_id: string;
-  capsule_sha256: string;
 }
 
 export interface PreparedContextRecovery {
@@ -206,26 +204,24 @@ export function recordContextSample(
   instanceId: string,
   sample: ContextSample,
 ): { state: ContextContinuityState; changed: boolean } {
-  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 };
-  });
+  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 };
 }
 
 /**
@@ -237,64 +233,62 @@ export function checkpointContext(
   coordRoot: string,
   input: CheckpointContextInput,
 ): CheckpointContextResult {
-  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 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 relativePath = capsuleRelativePath(input.sessionId, generation);
-    const absolutePath = join(coordRoot, ".harnery", relativePath);
-    writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
-    const next: ContextContinuityState = {
-      ...current,
+  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,
-      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 };
-  });
+      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 };
 }
 
 /** Prepare a briefing without claiming that a adapter has accepted it yet. */
@@ -302,48 +296,45 @@ export function prepareContextRecovery(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; cwd: string },
 ): PreparedContextRecovery | null {
-  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),
-      }),
+  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,
+    }),
+  };
 }
 
 /** Recovery lists input without surfacing it again or changing its receipts. */
@@ -404,8 +395,11 @@ function inputLine(messageId: string, status: string, body: string): string {
 
 /**
  * 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.
+ * A foreign or superseded checkpoint refuses without writing, and repeating
+ * the same accepted checkpoint is an exact no-op. The write is a
+ * compare-and-write: if the state changed after it was read, for example
+ * because a newer checkpoint landed, completion refuses instead of
+ * overwriting it.
  */
 export function completeContextRecovery(
   coordRoot: string,
@@ -415,43 +409,36 @@ export function completeContextRecovery(
     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;
-  });
+  const path = statePath(coordRoot, input.sessionId);
+  const observed = readText(path);
+  if (observed === null) return null;
+  const current = parseJson<ContextContinuityState>(observed);
+  const { checkpoint } = input;
+  if (
+    !current ||
+    checkpoint.session_id !== input.sessionId ||
+    checkpoint.instance_id !== input.instanceId ||
+    checkpoint.generation !== current.generation ||
+    (current.phase !== "checkpointed" && current.phase !== "recovered")
+  )
+    return null;
+  const capsule = readLatestCapsule(coordRoot, input.sessionId);
+  if (
+    !capsule ||
+    !capsuleMatchesState(current, capsule, input) ||
+    capsule.capsule_id !== checkpoint.capsule_id
+  )
+    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,
+  };
+  return writeBoundedJson(path, recovered, MAX_CAPSULE_BYTES, observed) ? recovered : null;
 }
 
 /** Record that the adapter, rather than Harnery, reported compaction complete. */
@@ -459,25 +446,23 @@ export function markContextCompactionCompleted(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; observedAt?: string },
 ): ContextContinuityState {
-  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;
-  });
+  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. */
@@ -520,29 +505,8 @@ export function readContextState(
 
 export function readLatestCapsule(coordRoot: string, sessionId: string): ContinuityCapsule | null {
   const state = readContextState(coordRoot, sessionId);
-  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;
+  if (!state?.latest_capsule) return null;
+  return readJson<ContinuityCapsule>(join(coordRoot, ".harnery", state.latest_capsule));
 }
 
 export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: RepoSnapshot): string {
@@ -557,35 +521,10 @@ 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");
+  const unknown = repoComparisonProblems(capsule.repo, liveRepo, [
+    "checkpoint",
+    "current repository",
+  ]);
   if (unknown.length > 0) {
     lines.push(
       `Repository could not be verified against the checkpoint: ${unknown.join("; ")}. Re-check before editing.`,
@@ -594,11 +533,11 @@ export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: Rep
   }
 
   const drift: string[] = [];
-  if (capsule.repo.branch && liveRepo.branch && capsule.repo.branch !== liveRepo.branch) {
+  if (capsule.repo.branch !== liveRepo.branch) {
     drift.push(`branch changed ${capsule.repo.branch} -> ${liveRepo.branch}`);
   }
-  if (capsule.repo.head && liveRepo.head && capsule.repo.head !== liveRepo.head) {
-    drift.push(`HEAD changed ${capsule.repo.head.slice(0, 8)} -> ${liveRepo.head.slice(0, 8)}`);
+  if (capsule.repo.head !== liveRepo.head) {
+    drift.push(`HEAD changed ${capsule.repo.head?.slice(0, 8)} -> ${liveRepo.head?.slice(0, 8)}`);
   }
   const beforeDirty = new Set(capsule.repo.dirty_paths);
   const afterDirty = new Set(liveRepo.dirty_paths);
@@ -715,47 +654,20 @@ function newState(input: {
   };
 }
 
+/** The capsule is the one the state names, written for the requesting task. */
 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.session.instance_id === input.instanceId &&
     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);
 }
@@ -781,7 +693,17 @@ function sessionKey(sessionId: string): string {
   return createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
 }
 
-function writeBoundedJson(path: string, value: unknown, maxBytes: number): void {
+/**
+ * Atomically replace a record. With `expected`, the replacement happens only
+ * while the file still holds exactly those bytes, so a concurrent writer's
+ * newer record is never overwritten by a decision made on older state.
+ */
+function writeBoundedJson(
+  path: string,
+  value: unknown,
+  maxBytes: number,
+  expected?: string,
+): boolean {
   const text = `${JSON.stringify(value, null, 2)}\n`;
   const bytes = Buffer.byteLength(text, "utf8");
   if (bytes > maxBytes) {
@@ -790,18 +712,35 @@ function writeBoundedJson(path: string, value: unknown, maxBytes: number): void
   mkdirSync(dirname(path), { recursive: true });
   const temp = `${path}.tmp.${process.pid}.${randomUUID()}`;
   writeFileSync(temp, text, { encoding: "utf8", mode: stateFileMode() });
+  if (expected !== undefined && readText(path) !== expected) {
+    unlinkSync(temp);
+    return false;
+  }
   renameSync(temp, path);
+  return true;
 }
 
-function readJson<T>(path: string): T | null {
-  if (!existsSync(path)) return null;
+function readText(path: string): string | null {
   try {
-    return JSON.parse(readFileSync(path, "utf8")) as T;
+    return readFileSync(path, "utf8");
   } catch {
     return null;
   }
 }
 
+function parseJson<T>(text: string): T | null {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+
+function readJson<T>(path: string): T | null {
+  const text = readText(path);
+  return text === null ? null : parseJson<T>(text);
+}
+
 type GitReadResult =
   | { ok: true; out: string }
   | { ok: false; reason: "not_repository" | "failed" | "timed_out" | "spawn_error" };
@@ -828,10 +767,6 @@ function git(cwd: string, args: string[]): GitReadResult {
   }
 }
 
-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 (