opencode-swarm 7.167.2 → 7.168.0

package/dist/cli/index-yv76j77m.js

@@ -0,0 +1,2008 @@
+// @bun
+import {
+  derivePlanId,
+  derivePlanIdentityHash
+} from "./index-h439y187.js";
+import {
+  getProjectDb,
+  projectDbExists,
+  withImmediateTransaction,
+  withProjectDbReadOnly
+} from "./index-wst6n478.js";
+import {
+  assertProjectRoot,
+  withEvidenceLock
+} from "./index-4r5pmtvk.js";
+import {
+  emit
+} from "./index-z6qreakh.js";
+import {
+  ExecutionProfileSchema,
+  PlanSchema,
+  TaskStatusSchema,
+  init_loader,
+  loadPluginConfig
+} from "./index-seetnhpx.js";
+import {
+  init_package,
+  package_default
+} from "./index-exatbqwj.js";
+import {
+  criticalWarn,
+  init_logger,
+  log
+} from "./index-zgwm4ryv.js";
+
+// src/plan/planning-profile.ts
+init_loader();
+function renderPlanningProfileDirective(resolution, context = "runtime") {
+  const header = context === "repository_default" ? `[PLANNING PROFILE DEFAULT \u2014 USE ONLY WHEN NO RUNTIME RESOLUTION EXISTS] effective=${resolution.effective} source=${resolution.source}` : `[PLANNING PROFILE \u2014 CURRENT RUNTIME AUTHORITY] effective=${resolution.effective} source=${resolution.source}`;
+  const precedence = context === "runtime" ? `
+This runtime resolution supersedes any planning-profile default in the base prompt.` : "";
+  if (resolution.effective === "balanced") {
+    return `${header}${precedence}
+BALANCED ceremony: use durable QA and execution defaults without pausing for the full questionnaire. Do not require a spec solely as ceremony. Ask the user only about unresolved material ambiguity, destructive or high-risk authorization, or another decision only they can make. save_plan exact-binds the default QA profile; persist planning_profile: "balanced" in the execution profile. Follow persisted QA gates after save.`;
+  }
+  return `${header}${precedence}
+STRICT ceremony: require an effective spec, run the complete clarification funnel, present the unified QA/execution questionnaire, wait for the user's answers, exact-bind those choices, and persist planning_profile: "strict". A locked legacy profile with no field uses this ceremony without materializing a new hash field.`;
+}
+function resolveRepositoryDefaultPlanningProfile(config) {
+  return config.execution_mode === "strict" ? "strict" : "balanced";
+}
+function resolvePlanningProfile({
+  directory,
+  incomingExecutionProfile,
+  existingExecutionProfile,
+  resetStatuses,
+  config
+}) {
+  if (incomingExecutionProfile?.planning_profile) {
+    return {
+      effective: incomingExecutionProfile.planning_profile,
+      persisted: incomingExecutionProfile.planning_profile,
+      source: "incoming"
+    };
+  }
+  const existingProfile = resetStatuses ? undefined : existingExecutionProfile;
+  if (existingProfile?.planning_profile) {
+    return {
+      effective: existingProfile.planning_profile,
+      persisted: existingProfile.planning_profile,
+      source: "persisted"
+    };
+  }
+  if (existingProfile?.locked === true) {
+    return {
+      effective: "strict",
+      persisted: undefined,
+      source: "legacy_locked_default"
+    };
+  }
+  const loadedConfig = config ?? loadPluginConfig(directory);
+  const repositoryDefault = resolveRepositoryDefaultPlanningProfile(loadedConfig);
+  return {
+    effective: repositoryDefault,
+    persisted: repositoryDefault,
+    source: "repository_default"
+  };
+}
+function normalizeExecutionProfileForHash(profile) {
+  if (!profile) {
+    return;
+  }
+  return {
+    ...profile,
+    commit_after_each_completed_task: profile.commit_after_each_completed_task === true ? true : undefined
+  };
+}
+
+// src/plan/ledger.ts
+init_package();
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path2 from "path";
+init_logger();
+
+// src/plan/ledger-sqlite.ts
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import path from "path";
+class SqliteLedgerStaleWriterError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SqliteLedgerStaleWriterError";
+  }
+}
+
+class SqliteLedgerImportError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SqliteLedgerImportError";
+  }
+}
+function withDirectory(first, second) {
+  if (typeof first === "string") {
+    if (second === undefined)
+      throw new TypeError("SQLite ledger input is required");
+    return { directory: first, input: second };
+  }
+  const { directory, ...input } = first;
+  return { directory, input };
+}
+function bytesOf(value) {
+  if (typeof value === "string")
+    return new TextEncoder().encode(value);
+  if (value instanceof ArrayBuffer)
+    return new Uint8Array(value.slice(0));
+  return new Uint8Array(value);
+}
+function canonicalJson(value) {
+  return bytesOf(JSON.stringify(value));
+}
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function parseCanonical(bytes) {
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (error) {
+    throw new SqliteLedgerImportError(`Canonical plan-ledger event is not valid UTF-8: ${String(error)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new SqliteLedgerImportError(`Canonical plan-ledger event is not valid JSON: ${String(error)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new SqliteLedgerImportError("Canonical plan-ledger event must be a JSON object");
+  }
+  return parsed;
+}
+function stringOrNull(value) {
+  return typeof value === "string" ? value : value === null ? null : null;
+}
+function numberOrNull(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function metadataFor(input, bytes, parsed, index) {
+  const provided = input.metadata ?? {};
+  const get = (_camel, snake) => parsed[snake];
+  const seqValue = get("seq", "seq") ?? (index === undefined ? undefined : index + 1);
+  const seq = typeof seqValue === "number" && Number.isInteger(seqValue) ? seqValue : NaN;
+  const timestamp = get("timestamp", "timestamp");
+  const planId = get("planId", "plan_id");
+  const eventType = get("eventType", "event_type");
+  const source = get("source", "source");
+  const planHashBefore = get("planHashBefore", "plan_hash_before");
+  const planHashAfter = get("planHashAfter", "plan_hash_after");
+  const schemaVersion = get("schemaVersion", "schema_version");
+  if (!Number.isInteger(seq) || seq < 1 || typeof timestamp !== "string" || typeof planId !== "string" || typeof eventType !== "string" || typeof source !== "string" || typeof planHashBefore !== "string" || typeof planHashAfter !== "string" || typeof schemaVersion !== "string") {
+    throw new SqliteLedgerImportError(`Canonical event at index ${index ?? seqValue ?? "?"} is missing required typed metadata`);
+  }
+  const payload = parsed.payload;
+  const payloadRecord = payload && typeof payload === "object" ? payload : null;
+  const metadata = {
+    seq,
+    timestamp,
+    planId,
+    eventType,
+    taskId: stringOrNull(get("taskId", "task_id")),
+    phaseId: numberOrNull(get("phaseId", "phase_id")),
+    fromStatus: stringOrNull(get("fromStatus", "from_status")),
+    toStatus: stringOrNull(get("toStatus", "to_status")),
+    source,
+    planHashBefore,
+    planHashAfter,
+    schemaVersion,
+    eventHash: sha256(bytes),
+    rootEventHash: stringOrNull(get("rootEventHash", "root_event_hash") ?? payloadRecord?.root_event_hash),
+    planEpoch: stringOrNull(get("planEpoch", "plan_epoch") ?? payloadRecord?.plan_epoch),
+    payloadHash: stringOrNull(get("payloadHash", "payload_hash") ?? payloadRecord?.payload_hash),
+    payload: payload ?? null
+  };
+  const typedInputs = [
+    ["seq", "seq", "seq"],
+    ["timestamp", "timestamp", "timestamp"],
+    ["planId", "plan_id", "planId"],
+    ["eventType", "event_type", "eventType"],
+    ["taskId", "task_id", "taskId"],
+    ["phaseId", "phase_id", "phaseId"],
+    ["fromStatus", "from_status", "fromStatus"],
+    ["toStatus", "to_status", "toStatus"],
+    ["source", "source", "source"],
+    ["planHashBefore", "plan_hash_before", "planHashBefore"],
+    ["planHashAfter", "plan_hash_after", "planHashAfter"],
+    ["schemaVersion", "schema_version", "schemaVersion"],
+    ["rootEventHash", "root_event_hash", "rootEventHash"],
+    ["planEpoch", "plan_epoch", "planEpoch"],
+    ["payloadHash", "payload_hash", "payloadHash"]
+  ];
+  for (const [camel, snake, key] of typedInputs) {
+    const supplied = provided[camel] ?? provided[snake] ?? input[snake];
+    if (supplied !== undefined && supplied !== metadata[key]) {
+      throw new SqliteLedgerImportError(`Supplied SQLite plan-ledger metadata ${snake} disagrees with canonical event bytes`);
+    }
+  }
+  return metadata;
+}
+function normalizeEvent(value, index) {
+  const input = typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer ? { canonicalEvent: value } : value;
+  const raw = input.canonicalEvent ?? input.canonical_event ?? input.bytes;
+  const bytes = raw === undefined ? canonicalJson(input.event) : bytesOf(raw);
+  if (bytes.length === 0)
+    throw new SqliteLedgerImportError("Canonical plan-ledger event is empty");
+  const parsed = parseCanonical(bytes);
+  return { bytes, parsed, metadata: metadataFor(input, bytes, parsed, index) };
+}
+function stateValue(input, camel, snake) {
+  if (!input)
+    return;
+  return input[camel] ?? input[snake];
+}
+function projectionBytes(input) {
+  const value = stateValue(input, "terminalProjection", "terminal_projection");
+  if (value === undefined || value === null)
+    return value;
+  return bytesOf(value);
+}
+function jsonValue(value) {
+  if (value === undefined || value === null)
+    return null;
+  if (typeof value === "string")
+    return value;
+  return JSON.stringify(value);
+}
+function decodeBytes(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (value instanceof Uint8Array)
+    return new Uint8Array(value);
+  if (value instanceof ArrayBuffer)
+    return new Uint8Array(value.slice(0));
+  return null;
+}
+function readStateFromRow(row) {
+  if (!row)
+    return null;
+  const authority = row.authority_mode;
+  const parity = row.parity_status;
+  if (authority !== "file_shadow" && authority !== "sqlite" || parity !== "pending" && parity !== "clean" && parity !== "diverged" && parity !== "failed") {
+    throw new Error("Invalid plan_ledger_state authority or parity value");
+  }
+  const projection = decodeBytes(row.terminal_projection);
+  let metadata = null;
+  if (typeof row.terminal_metadata === "string") {
+    try {
+      metadata = JSON.parse(row.terminal_metadata);
+    } catch {
+      metadata = row.terminal_metadata;
+    }
+  }
+  return {
+    id: 1,
+    authorityMode: authority,
+    shadowStartedVersion: stringOrNull(row.shadow_started_version),
+    parityStatus: parity,
+    fileReplayHash: stringOrNull(row.file_replay_hash),
+    sqliteReplayHash: stringOrNull(row.sqlite_replay_hash),
+    terminalProjectionHash: typeof row.terminal_projection_hash === "string" ? row.terminal_projection_hash : "",
+    lastSeq: typeof row.last_seq === "number" ? row.last_seq : Number(row.last_seq ?? 0),
+    lastEventHash: stringOrNull(row.last_event_hash),
+    rootEventHash: stringOrNull(row.root_event_hash),
+    planId: stringOrNull(row.plan_id),
+    planEpoch: stringOrNull(row.plan_epoch),
+    terminalPlanHash: stringOrNull(row.terminal_plan_hash),
+    terminalProjection: projection,
+    terminalProjectionJson: stringOrNull(row.terminal_projection_json),
+    terminalMetadata: metadata,
+    updatedAt: typeof row.updated_at === "string" ? row.updated_at : "",
+    authority_mode: authority,
+    shadow_started_version: stringOrNull(row.shadow_started_version),
+    parity_status: parity,
+    file_replay_hash: stringOrNull(row.file_replay_hash),
+    sqlite_replay_hash: stringOrNull(row.sqlite_replay_hash),
+    terminal_projection_hash: typeof row.terminal_projection_hash === "string" ? row.terminal_projection_hash : "",
+    last_seq: typeof row.last_seq === "number" ? row.last_seq : Number(row.last_seq ?? 0)
+  };
+}
+function readState(db) {
+  return readStateFromRow(db.query("SELECT * FROM plan_ledger_state WHERE id = 1").get());
+}
+function rowMetadata(row) {
+  return {
+    seq: Number(row.seq),
+    timestamp: String(row.timestamp),
+    planId: String(row.plan_id),
+    eventType: String(row.event_type),
+    taskId: stringOrNull(row.task_id),
+    phaseId: numberOrNull(row.phase_id),
+    fromStatus: stringOrNull(row.from_status),
+    toStatus: stringOrNull(row.to_status),
+    source: String(row.source),
+    planHashBefore: String(row.plan_hash_before),
+    planHashAfter: String(row.plan_hash_after),
+    schemaVersion: String(row.schema_version),
+    eventHash: String(row.event_hash),
+    rootEventHash: stringOrNull(row.root_event_hash),
+    planEpoch: stringOrNull(row.plan_epoch),
+    payloadHash: stringOrNull(row.payload_hash),
+    payload: typeof row.payload_json === "string" ? (() => {
+      try {
+        return JSON.parse(row.payload_json);
+      } catch {
+        return row.payload_json;
+      }
+    })() : null
+  };
+}
+function rowEvent(row) {
+  const canonical = decodeBytes(row.canonical_event);
+  if (!canonical)
+    throw new Error(`SQLite plan-ledger event ${String(row.seq)} has no BLOB bytes`);
+  const parsed = parseCanonical(canonical);
+  const metadata = rowMetadata(row);
+  const canonicalMetadata = metadataFor({ canonicalEvent: canonical }, canonical, parsed);
+  const checkedMetadata = [
+    "seq",
+    "timestamp",
+    "planId",
+    "eventType",
+    "taskId",
+    "phaseId",
+    "fromStatus",
+    "toStatus",
+    "source",
+    "planHashBefore",
+    "planHashAfter",
+    "schemaVersion",
+    "eventHash",
+    "rootEventHash",
+    "planEpoch",
+    "payloadHash"
+  ].map((key) => [key, metadata[key], canonicalMetadata[key]]);
+  const mismatch = checkedMetadata.find(([, actual, expected]) => actual !== expected);
+  const payloadMismatch = JSON.stringify(metadata.payload) !== JSON.stringify(canonicalMetadata.payload);
+  if (mismatch || payloadMismatch)
+    throw new Error(`SQLite plan-ledger event ${metadata.seq} typed metadata mismatch (${mismatch?.[0] ?? "payload"})`);
+  return {
+    ...metadata,
+    canonicalEvent: canonical,
+    canonical_event: canonical,
+    event: parsed,
+    parsed
+  };
+}
+function currentStateForWrite(db) {
+  return readState(db);
+}
+function upsertState(db, input, fallback) {
+  const existing = currentStateForWrite(db);
+  const authorityMode = stateValue(input, "authorityMode", "authority_mode") ?? stateValue(fallback, "authorityMode", "authority_mode") ?? existing?.authorityMode ?? "sqlite";
+  const shadowVersion = stateValue(input, "shadowStartedVersion", "shadow_started_version") ?? stateValue(fallback, "shadowStartedVersion", "shadow_started_version") ?? existing?.shadowStartedVersion ?? null;
+  const parityStatus = stateValue(input, "parityStatus", "parity_status") ?? stateValue(fallback, "parityStatus", "parity_status") ?? existing?.parityStatus ?? "pending";
+  const fileHash = stateValue(input, "fileReplayHash", "file_replay_hash") ?? stateValue(fallback, "fileReplayHash", "file_replay_hash") ?? existing?.fileReplayHash ?? null;
+  const sqliteHash = stateValue(input, "sqliteReplayHash", "sqlite_replay_hash") ?? stateValue(fallback, "sqliteReplayHash", "sqlite_replay_hash") ?? existing?.sqliteReplayHash ?? null;
+  const projection = projectionBytes(input) ?? projectionBytes(fallback) ?? existing?.terminalProjection ?? null;
+  const projectionHash = stateValue(input, "terminalProjectionHash", "terminal_projection_hash") ?? stateValue(fallback, "terminalProjectionHash", "terminal_projection_hash") ?? (projection ? sha256(projection) : existing?.terminalProjectionHash ?? "");
+  const lastSeq = stateValue(input, "lastSeq", "last_seq") ?? stateValue(fallback, "lastSeq", "last_seq") ?? existing?.lastSeq ?? 0;
+  const lastEventHash = stateValue(input, "lastEventHash", "last_event_hash") ?? stateValue(fallback, "lastEventHash", "last_event_hash") ?? existing?.lastEventHash ?? null;
+  const rootEventHash = stateValue(input, "rootEventHash", "root_event_hash") ?? stateValue(fallback, "rootEventHash", "root_event_hash") ?? existing?.rootEventHash ?? null;
+  const planId = stateValue(input, "planId", "plan_id") ?? stateValue(fallback, "planId", "plan_id") ?? existing?.planId ?? null;
+  const planEpoch = stateValue(input, "planEpoch", "plan_epoch") ?? stateValue(fallback, "planEpoch", "plan_epoch") ?? existing?.planEpoch ?? null;
+  const terminalPlanHash = stateValue(input, "terminalPlanHash", "terminal_plan_hash") ?? stateValue(fallback, "terminalPlanHash", "terminal_plan_hash") ?? existing?.terminalPlanHash ?? null;
+  const projectionJson = stateValue(input, "terminalProjectionJson", "terminal_projection_json") ?? stateValue(fallback, "terminalProjectionJson", "terminal_projection_json") ?? existing?.terminalProjectionJson ?? (projection ? new TextDecoder().decode(projection) : null);
+  const terminalMetadata = jsonValue(input?.terminalMetadata ?? input?.terminal_metadata) ?? jsonValue(fallback.terminalMetadata ?? fallback.terminal_metadata) ?? (existing?.terminalMetadata === null ? null : jsonValue(existing?.terminalMetadata));
+  if (authorityMode !== "file_shadow" && authorityMode !== "sqlite")
+    throw new Error(`Invalid plan-ledger authority mode: ${authorityMode}`);
+  if (!["pending", "clean", "diverged", "failed"].includes(parityStatus))
+    throw new Error(`Invalid plan-ledger parity status: ${parityStatus}`);
+  db.run(`INSERT INTO plan_ledger_state (
+		id, authority_mode, shadow_started_version, parity_status, file_replay_hash,
+		sqlite_replay_hash, terminal_projection_hash, last_seq, last_event_hash,
+		root_event_hash, plan_id, plan_epoch, terminal_plan_hash, terminal_projection,
+		terminal_projection_json, terminal_metadata, updated_at
+	) VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	ON CONFLICT(id) DO UPDATE SET
+		authority_mode = excluded.authority_mode,
+		shadow_started_version = excluded.shadow_started_version,
+		parity_status = excluded.parity_status,
+		file_replay_hash = excluded.file_replay_hash,
+		sqlite_replay_hash = excluded.sqlite_replay_hash,
+		terminal_projection_hash = excluded.terminal_projection_hash,
+		last_seq = excluded.last_seq,
+		last_event_hash = excluded.last_event_hash,
+		root_event_hash = excluded.root_event_hash,
+		plan_id = excluded.plan_id,
+		plan_epoch = excluded.plan_epoch,
+		terminal_plan_hash = excluded.terminal_plan_hash,
+		terminal_projection = excluded.terminal_projection,
+		terminal_projection_json = excluded.terminal_projection_json,
+		terminal_metadata = excluded.terminal_metadata,
+		updated_at = excluded.updated_at`, [
+    authorityMode,
+    shadowVersion,
+    parityStatus,
+    fileHash,
+    sqliteHash,
+    projectionHash,
+    lastSeq,
+    lastEventHash,
+    rootEventHash,
+    planId,
+    planEpoch,
+    terminalPlanHash,
+    projection,
+    projectionJson,
+    terminalMetadata,
+    new Date().toISOString()
+  ]);
+}
+function insertEvent(db, event) {
+  const m = event.metadata;
+  const existing = db.query("SELECT * FROM plan_ledger_event WHERE seq = ?").get(m.seq);
+  if (existing) {
+    const current = rowEvent(existing);
+    if (current.eventHash !== m.eventHash || !current.canonicalEvent.every((v, i) => v === event.bytes[i]))
+      throw new SqliteLedgerStaleWriterError(`SQLite plan-ledger sequence ${m.seq} already contains a different event`);
+    return current;
+  }
+  db.run(`INSERT INTO plan_ledger_event (
+		seq, canonical_event, event_hash, root_event_hash, plan_epoch, timestamp, plan_id,
+		event_type, task_id, phase_id, from_status, to_status, source, plan_hash_before,
+		plan_hash_after, schema_version, payload_hash, payload_json
+	) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    m.seq,
+    event.bytes,
+    m.eventHash,
+    m.rootEventHash,
+    m.planEpoch,
+    m.timestamp,
+    m.planId,
+    m.eventType,
+    m.taskId,
+    m.phaseId,
+    m.fromStatus,
+    m.toStatus,
+    m.source,
+    m.planHashBefore,
+    m.planHashAfter,
+    m.schemaVersion,
+    m.payloadHash,
+    jsonValue(m.payload)
+  ]);
+  return {
+    ...m,
+    canonicalEvent: new Uint8Array(event.bytes),
+    canonical_event: new Uint8Array(event.bytes),
+    event: event.parsed,
+    parsed: event.parsed
+  };
+}
+function appendInTransaction(db, input) {
+  const normalized = normalizeEvent({
+    canonicalEvent: input.canonicalEvent,
+    metadata: input.metadata
+  });
+  const maxSeq = db.query("SELECT MAX(seq) AS max FROM plan_ledger_event").get()?.max ?? 0;
+  const expectedSeq = input.expectedSeq ?? input.expected_seq;
+  if (expectedSeq !== undefined && expectedSeq !== maxSeq)
+    throw new SqliteLedgerStaleWriterError(`Stale SQLite plan-ledger writer: expected seq ${expectedSeq} but found ${maxSeq}`);
+  const expectedHash = input.expectedHash ?? input.expected_hash;
+  if (expectedHash !== undefined) {
+    const actual = db.query("SELECT plan_hash_after FROM plan_ledger_event ORDER BY seq DESC LIMIT 1").get()?.plan_hash_after ?? null;
+    if (actual !== expectedHash)
+      throw new SqliteLedgerStaleWriterError(`Stale SQLite plan-ledger writer: expected hash ${expectedHash} but found ${actual ?? "<missing>"}`);
+  }
+  if (normalized.metadata.seq !== maxSeq + 1)
+    throw new SqliteLedgerStaleWriterError(`SQLite plan-ledger append expected seq ${maxSeq + 1} but received ${normalized.metadata.seq}`);
+  const row = insertEvent(db, normalized);
+  upsertState(db, input.state, {
+    lastSeq: row.seq,
+    lastEventHash: row.eventHash,
+    rootEventHash: row.rootEventHash,
+    planId: row.planId,
+    planEpoch: row.planEpoch,
+    terminalPlanHash: row.planHashAfter
+  });
+  return row;
+}
+function hasSqliteLedger(directory) {
+  if (!projectDbExists(directory))
+    return false;
+  const db = getProjectDb(directory);
+  return (db.query("SELECT COUNT(*) AS count FROM plan_ledger_event").get()?.count ?? 0) > 0;
+}
+function getPlanLedgerState(directory) {
+  if (!projectDbExists(directory))
+    return null;
+  return readState(getProjectDb(directory));
+}
+function validateStateAgainstRows(state, rows) {
+  if (rows.length === 0)
+    return;
+  if (!state)
+    throw new Error("SQLite plan ledger has events but no authority state");
+  const last = rows.at(-1);
+  const expectedPlanEpoch = [...rows].reverse().find((row) => row.planEpoch !== null)?.planEpoch ?? null;
+  const expectedRootEventHash = [...rows].reverse().find((row) => row.rootEventHash !== null)?.rootEventHash ?? rows[0].eventHash;
+  const projectionHash = state.terminalProjection ? sha256(state.terminalProjection) : state.terminalProjectionJson ? sha256(new TextEncoder().encode(state.terminalProjectionJson)) : "";
+  const stateChecks = [
+    ["last_seq", state.lastSeq, last.seq],
+    ["last_event_hash", state.lastEventHash, last.eventHash],
+    ["root_event_hash", state.rootEventHash, expectedRootEventHash],
+    ["plan_id", state.planId, last.planId],
+    ["plan_epoch", state.planEpoch, expectedPlanEpoch],
+    ["terminal_plan_hash", state.terminalPlanHash, last.planHashAfter]
+  ];
+  if (state.terminalProjectionHash !== "") {
+    stateChecks.push([
+      "terminal_projection_hash",
+      state.terminalProjectionHash,
+      projectionHash
+    ]);
+  }
+  const mismatch = stateChecks.find(([, actual, expected]) => actual !== expected);
+  if (mismatch) {
+    throw new Error(`SQLite plan-ledger state metadata mismatch (${mismatch[0]}: state=${String(mismatch[1])}, rows=${String(mismatch[2])})`);
+  }
+}
+function readSqliteLedgerEvents(directory) {
+  if (!projectDbExists(directory))
+    return { events: [], state: null, import: null };
+  const db = getProjectDb(directory);
+  const rows = db.query("SELECT * FROM plan_ledger_event ORDER BY seq ASC").all().map(rowEvent);
+  const importRow = db.query("SELECT * FROM plan_ledger_import ORDER BY imported_at DESC, source ASC LIMIT 1").get();
+  const state = readState(db);
+  validateStateAgainstRows(state, rows);
+  return {
+    events: rows,
+    state,
+    import: importRow ? {
+      source: String(importRow.source),
+      sourceHash: String(importRow.source_hash),
+      archivePath: stringOrNull(importRow.archive_path),
+      archiveHash: stringOrNull(importRow.archive_hash),
+      archiveSize: typeof importRow.archive_size === "number" ? importRow.archive_size : null,
+      archiveCreatedAt: stringOrNull(importRow.archive_created_at),
+      mode: String(importRow.mode),
+      version: stringOrNull(importRow.version),
+      rowCount: Number(importRow.row_count ?? 0),
+      importedAt: String(importRow.imported_at)
+    } : null
+  };
+}
+function readSqliteLedgerEventsReadOnly(directory) {
+  const resetMarker = path.join(directory, ".swarm", "plan-ledger.resetting");
+  if (existsSync(resetMarker))
+    return { events: [], state: null, import: null };
+  try {
+    const result = withProjectDbReadOnly(directory, (db) => {
+      const table = db.query("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'plan_ledger_event'").get();
+      if (!table)
+        return { events: [], state: null, import: null };
+      const rows = db.query("SELECT * FROM plan_ledger_event ORDER BY seq ASC").all().map(rowEvent);
+      const state = readState(db);
+      validateStateAgainstRows(state, rows);
+      return { events: rows, state, import: null };
+    }) ?? { events: [], state: null, import: null };
+    return existsSync(resetMarker) ? { events: [], state: null, import: null } : result;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/no such table|no such column/i.test(message)) {
+      return { events: [], state: null, import: null };
+    }
+    throw error;
+  }
+}
+function appendSqliteLedger(first, second) {
+  const { directory, input } = withDirectory(first, second);
+  return withImmediateTransaction(getProjectDb(directory), "full", () => appendInTransaction(getProjectDb(directory), input));
+}
+function importInTransaction(db, input, replace) {
+  const existingCount = db.query("SELECT COUNT(*) AS count FROM plan_ledger_event").get()?.count ?? 0;
+  if (existingCount > 0 && !replace) {
+    const existing = readSqliteRows(db);
+    const incoming = input.canonicalEvents.map((event, index) => normalizeEvent(event, index));
+    if (existing.length !== incoming.length || existing.some((row, index) => row.eventHash !== incoming[index]?.metadata.eventHash))
+      throw new SqliteLedgerImportError("SQLite plan-ledger is not empty and does not match the requested import");
+  } else {
+    if (replace) {
+      db.run("DELETE FROM plan_ledger_event");
+      db.run("DELETE FROM plan_ledger_import");
+    }
+    let previousSeq = 0;
+    for (const [index, raw] of input.canonicalEvents.entries()) {
+      const event = normalizeEvent(raw, index);
+      if (event.metadata.seq !== previousSeq + 1)
+        throw new SqliteLedgerImportError(`SQLite plan-ledger import sequence must be contiguous at ${event.metadata.seq}`);
+      insertEvent(db, event);
+      previousSeq = event.metadata.seq;
+    }
+  }
+  const events = readSqliteRows(db);
+  const last = events.at(-1);
+  upsertState(db, input.state, {
+    authorityMode: input.state?.authorityMode ?? input.state?.authority_mode ?? "file_shadow",
+    lastSeq: last?.seq ?? 0,
+    lastEventHash: last?.eventHash ?? null,
+    rootEventHash: [...events].reverse().find((event) => event.rootEventHash !== null)?.rootEventHash ?? events[0]?.eventHash ?? null,
+    planId: last?.planId ?? null,
+    planEpoch: [...events].reverse().find((event) => event.planEpoch !== null)?.planEpoch ?? null,
+    terminalPlanHash: last?.planHashAfter ?? null
+  });
+  const source = input.source ?? "plan-ledger.jsonl";
+  const sourceHash = input.sourceHash ?? input.source_hash ?? sha256(new TextEncoder().encode(events.map((e) => new TextDecoder().decode(e.canonicalEvent)).join(`
+`)));
+  const archivePath = input.archivePath ?? input.archive_path ?? null;
+  const archiveHash = input.archiveHash ?? input.archive_hash ?? null;
+  const archiveSize = input.archiveSize ?? input.archive_size ?? null;
+  const archiveCreatedAt = input.archiveCreatedAt ?? input.archive_created_at ?? null;
+  const mode = input.mode ?? "file_shadow";
+  const version = input.version ?? null;
+  const priorImport = db.query("SELECT source_hash FROM plan_ledger_import WHERE source = ?").get(source);
+  if (priorImport && priorImport.source_hash !== sourceHash)
+    throw new SqliteLedgerImportError(`SQLite plan-ledger source ${source} was already imported with a different hash`);
+  db.run(`INSERT INTO plan_ledger_import (
+		source, source_hash, archive_path, archive_hash, archive_size, archive_created_at,
+		mode, version, row_count, imported_at
+	) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	ON CONFLICT(source) DO UPDATE SET
+		source_hash = excluded.source_hash, archive_path = excluded.archive_path,
+		archive_hash = excluded.archive_hash, archive_size = excluded.archive_size,
+		archive_created_at = excluded.archive_created_at, mode = excluded.mode,
+		version = excluded.version, row_count = excluded.row_count,
+		imported_at = excluded.imported_at`, [
+    source,
+    sourceHash,
+    archivePath,
+    archiveHash,
+    archiveSize,
+    archiveCreatedAt,
+    mode,
+    version,
+    events.length,
+    new Date().toISOString()
+  ]);
+  return readSqliteLedgerEventsFromDb(db);
+}
+function readSqliteRows(db) {
+  return db.query("SELECT * FROM plan_ledger_event ORDER BY seq ASC").all().map(rowEvent);
+}
+function readSqliteLedgerEventsFromDb(db) {
+  const events = readSqliteRows(db);
+  const row = db.query("SELECT * FROM plan_ledger_import ORDER BY imported_at DESC, source ASC LIMIT 1").get();
+  return {
+    events,
+    state: readState(db),
+    import: row ? {
+      source: String(row.source),
+      sourceHash: String(row.source_hash),
+      archivePath: stringOrNull(row.archive_path),
+      archiveHash: stringOrNull(row.archive_hash),
+      archiveSize: typeof row.archive_size === "number" ? row.archive_size : null,
+      archiveCreatedAt: stringOrNull(row.archive_created_at),
+      mode: String(row.mode),
+      version: stringOrNull(row.version),
+      rowCount: Number(row.row_count ?? 0),
+      importedAt: String(row.imported_at)
+    } : null
+  };
+}
+function importSqliteLedger(first, second) {
+  const { directory, input } = withDirectory(first, second);
+  return withImmediateTransaction(getProjectDb(directory), "full", () => importInTransaction(getProjectDb(directory), input, false));
+}
+function replaceSqliteLedger(first, second) {
+  const { directory, input } = withDirectory(first, second);
+  return withImmediateTransaction(getProjectDb(directory), "full", () => importInTransaction(getProjectDb(directory), input, true));
+}
+function recordSqliteLedgerParity(first, second) {
+  const { directory, input } = withDirectory(first, second);
+  const db = getProjectDb(directory);
+  return withImmediateTransaction(db, "full", () => {
+    const fileHash = input.fileReplayHash ?? input.file_replay_hash;
+    const sqliteHash = input.sqliteReplayHash ?? input.sqlite_replay_hash;
+    if (fileHash === undefined || sqliteHash === undefined)
+      throw new Error("Parity requires both file_replay_hash and sqlite_replay_hash");
+    const status = input.parityStatus ?? input.parity_status ?? (fileHash === sqliteHash ? "clean" : "diverged");
+    upsertState(db, {
+      fileReplayHash: fileHash,
+      sqliteReplayHash: sqliteHash,
+      terminalProjectionHash: input.terminalProjectionHash ?? input.terminal_projection_hash,
+      parityStatus: status
+    }, {});
+    return readState(db);
+  });
+}
+function cutoverSqliteLedger(first, second) {
+  const { directory, input } = typeof first === "string" ? { directory: first, input: second } : { directory: first.directory, input: first };
+  const db = getProjectDb(directory);
+  return withImmediateTransaction(db, "full", () => {
+    const state = readState(db);
+    if (!state)
+      throw new Error("Cannot cut over an uninitialized SQLite plan ledger");
+    if (state.parityStatus !== "clean" || !state.fileReplayHash || state.fileReplayHash !== state.sqliteReplayHash)
+      throw new Error("Cannot cut over SQLite plan ledger before a clean parity record");
+    const expected = input?.expectedShadowStartedVersion ?? input?.expected_shadow_started_version;
+    if (expected !== undefined && state.shadowStartedVersion !== expected)
+      throw new SqliteLedgerStaleWriterError(`SQLite plan-ledger shadow version changed: expected ${expected}, found ${state.shadowStartedVersion ?? "<missing>"}`);
+    db.run("UPDATE plan_ledger_state SET authority_mode = 'sqlite', updated_at = ? WHERE id = 1", [new Date().toISOString()]);
+    return readState(db);
+  });
+}
+function clearSqliteLedger(directory) {
+  if (!projectDbExists(directory))
+    return;
+  const db = getProjectDb(directory);
+  withImmediateTransaction(db, "full", () => {
+    db.run("DELETE FROM plan_ledger_event");
+    db.run("DELETE FROM plan_ledger_import");
+    db.run("DELETE FROM plan_ledger_state");
+  });
+}
+
+// src/plan/ledger.ts
+var LEDGER_SCHEMA_VERSION = "1.1.0";
+function resolvePlanEpochIdentity(events, authoritativePlan) {
+  const planId = derivePlanId(authoritativePlan);
+  const planIdentityHash = derivePlanIdentityHash(authoritativePlan);
+  const payloadHash = computePlanLedgerHash(authoritativePlan);
+  const candidates = extractPlanEpochCandidates(events, planId);
+  const distinctCandidateKeys = new Set(candidates.map((candidate) => `${candidate.planEpoch}:${candidate.rootEventHash}`));
+  if (distinctCandidateKeys.size > 1) {
+    throw new Error(`Conflicting plan epoch metadata detected for ${planId}; refusing to continue.`);
+  }
+  if (candidates.length === 0) {
+    return null;
+  }
+  const existing = candidates[0];
+  return {
+    planId,
+    planIdentityHash,
+    planEpoch: existing.planEpoch,
+    rootEventHash: existing.rootEventHash,
+    payloadHash,
+    source: existing.source
+  };
+}
+var LEDGER_FILENAME = "plan-ledger.jsonl";
+var LEDGER_LOCK_PATH = path2.join(".swarm", LEDGER_FILENAME);
+var PLAN_JSON_FILENAME = "plan.json";
+
+class LedgerStaleWriterError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LedgerStaleWriterError";
+  }
+}
+function getLedgerPath(directory) {
+  return path2.join(directory, ".swarm", LEDGER_FILENAME);
+}
+function getPlanJsonPath(directory) {
+  return path2.join(directory, ".swarm", PLAN_JSON_FILENAME);
+}
+function compareCodeUnits(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function readLedgerDirectory(directory) {
+  return fs.readdirSync(directory);
+}
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return null;
+}
+function isSha256Hex(value) {
+  return /^[a-f0-9]{64}$/i.test(value);
+}
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function serializeLedgerEvent(event) {
+  return JSON.stringify(event);
+}
+function computeLedgerEventHash(event) {
+  return crypto.createHash("sha256").update(serializeLedgerEvent(event), "utf8").digest("hex");
+}
+function extractPlanEpochCandidates(events, expectedPlanId) {
+  if (events.length === 0) {
+    throw new Error("Plan ledger is empty; missing plan_created root.");
+  }
+  const rootEvent = events[0];
+  if (rootEvent.event_type !== "plan_created") {
+    throw new Error(`Plan ledger root must be plan_created; found ${rootEvent.event_type} at seq ${rootEvent.seq}.`);
+  }
+  if (rootEvent.plan_id !== expectedPlanId) {
+    throw new Error(`Plan ledger identity mismatch: expected ${expectedPlanId} but found ${rootEvent.plan_id}.`);
+  }
+  const rootEventHash = computeLedgerEventHash(rootEvent);
+  const candidates = [];
+  const rootPayload = asRecord(rootEvent.payload);
+  const rootPlanEpoch = rootPayload?.plan_epoch;
+  if (typeof rootPlanEpoch === "string" && rootPlanEpoch.length > 0) {
+    if (!isUuid(rootPlanEpoch)) {
+      throw new Error("Plan ledger root carries an invalid plan_epoch.");
+    }
+    candidates.push({
+      planEpoch: rootPlanEpoch,
+      rootEventHash,
+      source: "root"
+    });
+  }
+  for (const event of events) {
+    if (event.event_type !== "snapshot" || event.source !== "plan_epoch_adopted") {
+      continue;
+    }
+    if (event.plan_id !== expectedPlanId) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} belongs to ${event.plan_id}, expected ${expectedPlanId}.`);
+    }
+    const payload = asRecord(event.payload);
+    const planEpoch = payload?.plan_epoch;
+    const rootHash = payload?.root_event_hash;
+    const embeddedPlan = PlanSchema.safeParse(payload?.plan);
+    if (!embeddedPlan.success) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} carries an invalid embedded plan.`);
+    }
+    const payloadHash = payload?.payload_hash;
+    if (typeof planEpoch !== "string" || !isUuid(planEpoch)) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} has an invalid plan_epoch.`);
+    }
+    if (typeof rootHash !== "string" || !isSha256Hex(rootHash)) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} has an invalid root_event_hash.`);
+    }
+    if (rootHash !== rootEventHash) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} does not match the canonical ledger root.`);
+    }
+    if (typeof payloadHash !== "string") {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} is missing payload_hash.`);
+    }
+    if (derivePlanId(embeddedPlan.data) !== expectedPlanId) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} embeds a different plan identity.`);
+    }
+    if (computePlanLedgerHash(embeddedPlan.data) !== payloadHash) {
+      throw new Error(`Plan epoch adoption snapshot at seq ${event.seq} has a mismatched payload_hash.`);
+    }
+    candidates.push({
+      planEpoch,
+      rootEventHash: rootHash,
+      source: "plan_epoch_adopted"
+    });
+  }
+  return candidates;
+}
+function writeFileFsyncedThenRename(tempPath, targetPath, data) {
+  const fd = fs.openSync(tempPath, "w");
+  try {
+    fs.writeFileSync(fd, data, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tempPath, targetPath);
+}
+function fsyncRecoveryDirectory(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, "r");
+    fs.fsyncSync(fd);
+  } catch (error) {
+    const code = error.code;
+    const unsupportedOnWindows = process.platform === "win32" && ["EPERM", "EACCES", "EINVAL", "EBADF", "EISDIR", "ENOTSUP"].includes(code ?? "");
+    if (unsupportedOnWindows) {
+      log(`[ledger] Directory fsync unavailable for recovery archive ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    throw new Error(`Failed to fsync recovery archive directory before canonical replacement: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    if (fd !== undefined)
+      fs.closeSync(fd);
+  }
+}
+function findRawMalformedSuffix(content) {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let lineStart = 0;
+  for (let index = 0;index <= content.length; index++) {
+    if (index < content.length && content[index] !== 10)
+      continue;
+    let lineEnd = index;
+    if (lineEnd > lineStart && content[lineEnd - 1] === 13)
+      lineEnd--;
+    const line = content.subarray(lineStart, lineEnd);
+    if (line.length > 0) {
+      try {
+        JSON.parse(decoder.decode(line));
+      } catch {
+        return content.subarray(lineStart);
+      }
+    }
+    lineStart = index + 1;
+  }
+  return Buffer.alloc(0);
+}
+function isStructurallyValidLedgerEvent(value) {
+  const event = asRecord(value);
+  return event !== null && Number.isSafeInteger(event.seq) && event.seq > 0 && typeof event.timestamp === "string" && typeof event.plan_id === "string" && typeof event.event_type === "string" && typeof event.source === "string" && typeof event.plan_hash_before === "string" && typeof event.plan_hash_after === "string" && typeof event.schema_version === "string";
+}
+function readFileLedgerExact(directory) {
+  const ledgerPath = getLedgerPath(directory);
+  if (!fs.existsSync(ledgerPath)) {
+    return { events: [], lines: [], truncated: false, badSuffix: null };
+  }
+  const bytes = fs.readFileSync(ledgerPath);
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const events = [];
+  const lenientEvents = [];
+  const lines = [];
+  let truncated = false;
+  let badSuffix = null;
+  let start = 0;
+  for (let index = 0;index <= bytes.length; index++) {
+    if (index < bytes.length && bytes[index] !== 10)
+      continue;
+    let end = index;
+    if (end > start && bytes[end - 1] === 13)
+      end--;
+    const line = bytes.subarray(start, end);
+    if (line.length > 0) {
+      try {
+        const parsed = JSON.parse(decoder.decode(line));
+        if (!isStructurallyValidLedgerEvent(parsed)) {
+          throw new Error("invalid ledger event shape");
+        }
+        lenientEvents.push(parsed);
+        if (!truncated)
+          events.push(parsed);
+        if (!truncated)
+          lines.push(new Uint8Array(line));
+      } catch {
+        if (!truncated) {
+          truncated = true;
+          badSuffix = bytes.subarray(start).toString("utf8");
+        }
+      }
+    }
+    start = index + 1;
+  }
+  return { events, lines, truncated, badSuffix, lenientEvents };
+}
+function sqliteEventsAsLedger(directory) {
+  const rows = readSqliteLedgerEvents(directory).events;
+  return {
+    events: rows.map((row) => row.event),
+    lines: rows.map((row) => row.canonicalEvent)
+  };
+}
+function exactPrefix(prefix, complete) {
+  return prefix.length <= complete.length && prefix.every((line, index) => Buffer.from(line).equals(Buffer.from(complete[index])));
+}
+function eventsProjection(directory, events) {
+  const plan = reconstructPlanFromEvents(directory, structuredClone(events));
+  const projection = new TextEncoder().encode(JSON.stringify(plan));
+  return {
+    replayHash: plan ? computePlanLedgerHash(plan) : crypto.createHash("sha256").update(projection).digest("hex"),
+    projectionHash: crypto.createHash("sha256").update(projection).digest("hex"),
+    projection
+  };
+}
+function stateForEvents(directory, events, authorityMode) {
+  const terminal = eventsProjection(directory, events);
+  const last = events.at(-1);
+  return {
+    authorityMode,
+    shadowStartedVersion: getPlanLedgerState(directory)?.shadowStartedVersion ?? package_default.version,
+    parityStatus: "pending",
+    terminalProjectionHash: terminal.projectionHash,
+    terminalProjection: terminal.projection,
+    lastSeq: last?.seq ?? 0,
+    planId: last?.plan_id ?? null,
+    terminalPlanHash: last?.plan_hash_after ?? null
+  };
+}
+function writePortableLedger(directory, lines) {
+  const ledgerPath = getLedgerPath(directory);
+  fs.mkdirSync(path2.dirname(ledgerPath), { recursive: true });
+  const content = Buffer.concat(lines.flatMap((line) => [Buffer.from(line), Buffer.from(`
+`)]));
+  const tempPath = `${ledgerPath}.sqlite-export.${crypto.randomBytes(16).toString("hex")}.tmp`;
+  try {
+    _internals.writeFileFsyncedThenRename(tempPath, ledgerPath, content);
+  } finally {
+    try {
+      fs.unlinkSync(tempPath);
+    } catch {}
+  }
+}
+function archiveLegacyLedger(directory, bytes) {
+  const hash = crypto.createHash("sha256").update(bytes).digest("hex");
+  const archivePath = path2.join(directory, ".swarm", `plan-ledger.legacy-archive.${hash}.jsonl`);
+  if (!fs.existsSync(archivePath)) {
+    const tempPath = `${archivePath}.tmp.${crypto.randomBytes(16).toString("hex")}`;
+    try {
+      _internals.writeFileFsyncedThenRename(tempPath, archivePath, bytes);
+    } finally {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {}
+    }
+    fsyncRecoveryDirectory(path2.dirname(archivePath));
+  }
+  return { path: archivePath, hash };
+}
+function importCanonicalIntoSqlite(directory, file, legacy) {
+  if (file.truncated)
+    return;
+  const ledgerBytes = fs.readFileSync(getLedgerPath(directory));
+  const archive = legacy ? archiveLegacyLedger(directory, ledgerBytes) : null;
+  const terminal = eventsProjection(directory, file.events);
+  importSqliteLedger(directory, {
+    canonicalEvents: file.lines,
+    state: {
+      ...stateForEvents(directory, file.events, "file_shadow"),
+      fileReplayHash: terminal.replayHash,
+      sqliteReplayHash: terminal.replayHash,
+      parityStatus: "clean"
+    },
+    source: "plan-ledger.jsonl",
+    sourceHash: crypto.createHash("sha256").update(ledgerBytes).digest("hex"),
+    archivePath: archive?.path ?? null,
+    archiveHash: archive?.hash ?? null,
+    archiveSize: archive ? ledgerBytes.length : null,
+    archiveCreatedAt: archive ? new Date().toISOString() : null,
+    mode: "file_shadow",
+    version: package_default.version
+  });
+}
+function coordinateLedger(directory) {
+  if (fs.existsSync(path2.join(directory, ".swarm", "plan-ledger.resetting")))
+    return { events: [], lines: [], truncated: false, badSuffix: null };
+  const file = readFileLedgerExact(directory);
+  if (!hasSqliteLedger(directory)) {
+    if (file.events.length > 0 && !file.truncated) {
+      try {
+        importCanonicalIntoSqlite(directory, file, true);
+      } catch (error) {
+        log(`[ledger] SQLite shadow import deferred after file read: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return file;
+  }
+  let sqlite = sqliteEventsAsLedger(directory);
+  const state = getPlanLedgerState(directory);
+  if (!state)
+    throw new Error("SQLite plan ledger has events but no authority state");
+  if (state.authorityMode === "file_shadow") {
+    if (!fs.existsSync(getLedgerPath(directory))) {
+      writePortableLedger(directory, sqlite.lines);
+      return {
+        events: sqlite.events,
+        lines: sqlite.lines,
+        truncated: false,
+        badSuffix: null
+      };
+    }
+    if (file.truncated) {
+      if (!exactPrefix(file.lines, sqlite.lines)) {
+        throw new Error("PLAN_LEDGER_DIVERGED: malformed file prefix differs from SQLite authority");
+      }
+      return file;
+    }
+    if (file.events[0]?.seq === 1 && file.events[0]?.event_type === "plan_created" && sqlite.events[0]?.plan_id !== file.events[0]?.plan_id) {
+      try {
+        replaceSqliteLedger(directory, {
+          canonicalEvents: file.lines,
+          state: stateForEvents(directory, file.events, "file_shadow"),
+          source: "plan_identity_reinitialized",
+          mode: "file_shadow",
+          version: package_default.version
+        });
+        sqlite = sqliteEventsAsLedger(directory);
+      } catch (error) {
+        log(`[ledger] SQLite shadow re-root reconciliation deferred: ${error instanceof Error ? error.message : String(error)}`);
+        return file;
+      }
+    }
+    if (!exactPrefix(sqlite.lines, file.lines)) {
+      throw new Error("PLAN_LEDGER_DIVERGED: JSONL and SQLite committed prefixes differ");
+    }
+    try {
+      for (let index = sqlite.lines.length;index < file.lines.length; index++) {
+        appendSqliteLedger(directory, {
+          canonicalEvent: file.lines[index],
+          expectedSeq: index,
+          state: stateForEvents(directory, file.events.slice(0, index + 1), "file_shadow")
+        });
+      }
+    } catch (error) {
+      log(`[ledger] SQLite shadow suffix repair deferred: ${error instanceof Error ? error.message : String(error)}`);
+      return file;
+    }
+    sqlite = sqliteEventsAsLedger(directory);
+    const fileProjection = eventsProjection(directory, file.events);
+    const current = getPlanLedgerState(directory);
+    const sqliteReplayHash = sqlite.events.at(-1)?.plan_hash_after ?? "";
+    const sqliteProjectionHash = current.terminalProjectionHash;
+    const parityStatus = fileProjection.replayHash === sqliteReplayHash && fileProjection.projectionHash === sqliteProjectionHash ? "clean" : "diverged";
+    if (current.parityStatus !== parityStatus || current.fileReplayHash !== fileProjection.replayHash || current.sqliteReplayHash !== sqliteReplayHash) {
+      recordSqliteLedgerParity(directory, {
+        fileReplayHash: fileProjection.replayHash,
+        sqliteReplayHash,
+        terminalProjectionHash: sqliteProjectionHash,
+        parityStatus
+      });
+    }
+    const refreshed = getPlanLedgerState(directory);
+    if (refreshed.parityStatus === "clean" && refreshed.shadowStartedVersion !== null && refreshed.shadowStartedVersion !== package_default.version) {
+      cutoverSqliteLedger(directory, {
+        expectedShadowStartedVersion: refreshed.shadowStartedVersion
+      });
+    }
+    return file;
+  }
+  if (file.truncated || file.lines.length !== sqlite.lines.length || !exactPrefix(file.lines, sqlite.lines)) {
+    writePortableLedger(directory, sqlite.lines);
+  }
+  return {
+    events: sqlite.events,
+    lines: sqlite.lines,
+    truncated: false,
+    badSuffix: null
+  };
+}
+function computePlanLedgerHash(plan) {
+  const normalized = {
+    schema_version: plan.schema_version,
+    title: plan.title,
+    swarm: plan.swarm,
+    current_phase: plan.current_phase,
+    migration_status: plan.migration_status,
+    execution_profile: normalizeExecutionProfileForHash(plan.execution_profile),
+    phases: plan.phases.map((phase) => ({
+      id: phase.id,
+      name: phase.name,
+      status: phase.status,
+      required_agents: phase.required_agents ? [...phase.required_agents].sort() : undefined,
+      tasks: phase.tasks.map((task) => ({
+        id: task.id,
+        phase: task.phase,
+        status: task.status,
+        size: task.size,
+        description: task.description,
+        depends: [...task.depends].sort(),
+        acceptance: task.acceptance,
+        files_touched: [...task.files_touched].sort(),
+        evidence_path: task.evidence_path,
+        blocked_reason: task.blocked_reason
+      }))
+    }))
+  };
+  const jsonString = JSON.stringify(normalized);
+  return crypto.createHash("sha256").update(jsonString, "utf8").digest("hex");
+}
+function computePlanStructureHash(plan) {
+  const normalized = {
+    schema_version: plan.schema_version,
+    title: plan.title,
+    swarm: plan.swarm,
+    current_phase: plan.current_phase,
+    migration_status: plan.migration_status,
+    execution_profile: normalizeExecutionProfileForHash(plan.execution_profile),
+    phases: plan.phases.map((phase) => ({
+      id: phase.id,
+      name: phase.name,
+      required_agents: phase.required_agents ? [...phase.required_agents].sort() : undefined,
+      tasks: phase.tasks.map((task) => ({
+        id: task.id,
+        phase: task.phase,
+        size: task.size,
+        description: task.description,
+        depends: [...task.depends].sort(),
+        acceptance: task.acceptance,
+        files_touched: [...task.files_touched].sort(),
+        evidence_path: task.evidence_path,
+        blocked_reason: task.blocked_reason
+      }))
+    }))
+  };
+  const jsonString = JSON.stringify(normalized);
+  return crypto.createHash("sha256").update(jsonString, "utf8").digest("hex");
+}
+function computeCurrentPlanHash(directory) {
+  const planPath = getPlanJsonPath(directory);
+  try {
+    const content = fs.readFileSync(planPath, "utf8");
+    const plan = JSON.parse(content);
+    return computePlanLedgerHash(plan);
+  } catch {
+    return "";
+  }
+}
+async function ledgerExists(directory) {
+  const ledgerPath = getLedgerPath(directory);
+  return fs.existsSync(ledgerPath) || hasSqliteLedger(directory);
+}
+async function getLatestLedgerSeq(directory) {
+  const coordinated = coordinateLedger(directory);
+  return coordinated.events.reduce((maximum, event) => Math.max(maximum, event.seq), 0);
+}
+async function readLedgerEvents(directory) {
+  const result = coordinateLedger(directory);
+  const events = result.truncated ? result.lenientEvents ?? result.events : result.events;
+  return [...events].sort((a, b) => a.seq - b.seq);
+}
+async function initLedger(directory, planId, initialPlanHash, initialPlan) {
+  assertProjectRoot(directory);
+  const ledgerPath = getLedgerPath(directory);
+  const planJsonPath = getPlanJsonPath(directory);
+  if (fs.existsSync(ledgerPath)) {
+    throw new Error("Ledger already initialized. Use appendLedgerEvent to add events.");
+  }
+  let planHashAfter = initialPlanHash ?? "";
+  let embeddedPlan = initialPlan;
+  if (!initialPlanHash) {
+    try {
+      if (fs.existsSync(planJsonPath)) {
+        const content = fs.readFileSync(planJsonPath, "utf8");
+        const plan = JSON.parse(content);
+        planHashAfter = computePlanLedgerHash(plan);
+        if (!embeddedPlan)
+          embeddedPlan = plan;
+      }
+    } catch {}
+  }
+  const payload = {
+    plan_epoch: crypto.randomUUID(),
+    ...embeddedPlan ? { plan: embeddedPlan, payload_hash: planHashAfter } : {}
+  };
+  const event = {
+    seq: 1,
+    timestamp: new Date().toISOString(),
+    plan_id: planId,
+    event_type: "plan_created",
+    source: "initLedger",
+    plan_hash_before: "",
+    plan_hash_after: planHashAfter,
+    schema_version: LEDGER_SCHEMA_VERSION,
+    ...payload ? { payload } : {}
+  };
+  fs.mkdirSync(path2.join(directory, ".swarm"), { recursive: true });
+  const tempPath = `${ledgerPath}.tmp.${Date.now()}.${Math.floor(Math.random() * 1e9)}`;
+  const line = `${JSON.stringify(event)}
+`;
+  writeFileFsyncedThenRename(tempPath, ledgerPath, line);
+  const initialized = readFileLedgerExact(directory);
+  if (hasSqliteLedger(directory)) {
+    const priorMode = getPlanLedgerState(directory)?.authorityMode ?? "file_shadow";
+    try {
+      replaceSqliteLedger(directory, {
+        canonicalEvents: initialized.lines,
+        state: stateForEvents(directory, initialized.events, priorMode),
+        source: "plan_identity_reinitialized",
+        mode: priorMode,
+        version: package_default.version
+      });
+    } catch (error) {
+      if (priorMode !== "file_shadow")
+        throw error;
+      log(`[ledger] SQLite shadow re-root deferred after file commit: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    importCanonicalIntoSqlite(directory, initialized, false);
+  }
+}
+async function readLedgerEventsForEpoch(directory) {
+  const integrity = await _internals.readLedgerEventsWithIntegrity(directory, {
+    failClosedOnReadError: true
+  });
+  if (integrity.truncated) {
+    throw new Error(`PLAN_LEDGER_TRUNCATED: ${getLedgerPath(directory)} has a malformed line; plan epoch identity cannot be resolved. Preserve this file and quarantine the corrupted suffix before retrying.`);
+  }
+  return integrity.events;
+}
+async function readPlanEpochIdentity(directory, authoritativePlan) {
+  assertProjectRoot(directory);
+  if (!await ledgerExists(directory)) {
+    return null;
+  }
+  const events = await readLedgerEventsForEpoch(directory);
+  if (events.length === 0) {
+    throw new Error("Plan ledger is empty; missing plan_created root.");
+  }
+  return resolvePlanEpochIdentity(events, authoritativePlan);
+}
+async function getOrAdoptPlanEpochUnderLock(directory, authoritativePlan) {
+  assertProjectRoot(directory);
+  const planId = derivePlanId(authoritativePlan);
+  const planIdentityHash = derivePlanIdentityHash(authoritativePlan);
+  const payloadHash = computePlanLedgerHash(authoritativePlan);
+  let lastStaleWriterError;
+  for (let attempt = 0;attempt < 4; attempt++) {
+    if (!await ledgerExists(directory)) {
+      try {
+        await initLedger(directory, planId, payloadHash, authoritativePlan);
+      } catch (error) {
+        if (!(error instanceof Error && error.message.includes("Ledger already initialized"))) {
+          throw error;
+        }
+      }
+    }
+    const events = await readLedgerEventsForEpoch(directory);
+    const existing = resolvePlanEpochIdentity(events, authoritativePlan);
+    if (existing) {
+      return existing;
+    }
+    if (events.length === 0) {
+      throw new Error("Plan ledger is empty; cannot adopt a plan epoch.");
+    }
+    const rootEvent = events[0];
+    const rootEventHash = computeLedgerEventHash(rootEvent);
+    const tail = events[events.length - 1];
+    const planEpoch = _internals.randomUUID();
+    const adoptionPayload = {
+      plan: authoritativePlan,
+      payload_hash: payloadHash,
+      plan_epoch: planEpoch,
+      root_event_hash: rootEventHash
+    };
+    try {
+      const appended = await _internals.appendLedgerEvent(directory, {
+        event_type: "snapshot",
+        source: "plan_epoch_adopted",
+        plan_id: planId,
+        payload: adoptionPayload
+      }, {
+        expectedSeq: tail.seq,
+        expectedLedgerHash: tail.plan_hash_after,
+        planHashAfter: payloadHash
+      });
+      const verifiedEvents = await readLedgerEventsForEpoch(directory);
+      const verified = verifiedEvents[verifiedEvents.length - 1];
+      const verifiedPayload = asRecord(verified?.payload);
+      if (!verified || verified.seq !== appended.seq || verified.event_type !== "snapshot" || verified.source !== "plan_epoch_adopted" || verified.plan_id !== planId || verifiedPayload?.plan_epoch !== planEpoch || verifiedPayload?.root_event_hash !== rootEventHash || verifiedPayload?.payload_hash !== payloadHash) {
+        throw new Error(`Plan epoch adoption read verification failed for ${planId}.`);
+      }
+      return {
+        planId,
+        planIdentityHash,
+        planEpoch,
+        rootEventHash,
+        payloadHash,
+        source: "plan_epoch_adopted"
+      };
+    } catch (error) {
+      if (error instanceof LedgerStaleWriterError) {
+        lastStaleWriterError = error;
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error(`Unable to settle plan epoch for ${planId} after repeated stale-writer retries.`, { cause: lastStaleWriterError });
+}
+async function appendLedgerEvent(directory, eventInput, options) {
+  assertProjectRoot(directory);
+  return withEvidenceLock(directory, LEDGER_LOCK_PATH, "plan-ledger", "append-ledger-event", async () => {
+    const ledgerPath = getLedgerPath(directory);
+    if (options?.expectedLedgerHash !== undefined && options.expectedSeq === undefined) {
+      throw new Error("expectedLedgerHash requires expectedSeq so stale-projection recovery is bound to one exact ledger tail");
+    }
+    const latestSeq = await getLatestLedgerSeq(directory);
+    const nextSeq = latestSeq + 1;
+    let ledgerHashBefore;
+    if (options?.expectedLedgerHash !== undefined) {
+      const events = await readLedgerEvents(directory);
+      const tail = events[events.length - 1];
+      if (!tail || tail.plan_hash_after !== options.expectedLedgerHash) {
+        throw new LedgerStaleWriterError(`Stale writer: expected ledger hash ${options.expectedLedgerHash} but found ${tail?.plan_hash_after ?? "<missing>"}`);
+      }
+      ledgerHashBefore = tail.plan_hash_after;
+    }
+    const planHashBefore = computeCurrentPlanHash(directory);
+    if (options?.expectedSeq !== undefined && options.expectedSeq !== latestSeq) {
+      throw new LedgerStaleWriterError(`Stale writer: expected seq ${options.expectedSeq} but found ${latestSeq}`);
+    }
+    if (options?.expectedHash !== undefined && options.expectedHash !== planHashBefore) {
+      throw new LedgerStaleWriterError(`Stale writer: expected hash ${options.expectedHash} but found ${planHashBefore}`);
+    }
+    const planHashAfter = options?.planHashAfter ?? planHashBefore;
+    const event = {
+      ...eventInput,
+      seq: nextSeq,
+      timestamp: new Date().toISOString(),
+      plan_hash_before: ledgerHashBefore ?? planHashBefore,
+      plan_hash_after: planHashAfter,
+      schema_version: LEDGER_SCHEMA_VERSION
+    };
+    fs.mkdirSync(path2.join(directory, ".swarm"), { recursive: true });
+    const canonicalEvent = new TextEncoder().encode(serializeLedgerEvent(event));
+    const state = getPlanLedgerState(directory);
+    const authorityMode = state?.authorityMode ?? "file_shadow";
+    if (authorityMode === "sqlite") {
+      try {
+        const existing = sqliteEventsAsLedger(directory);
+        appendSqliteLedger(directory, {
+          canonicalEvent,
+          expectedSeq: latestSeq,
+          state: stateForEvents(directory, [...existing.events, event], "sqlite")
+        });
+      } catch (error) {
+        if (error instanceof SqliteLedgerStaleWriterError) {
+          throw new LedgerStaleWriterError(error.message);
+        }
+        throw error;
+      }
+      try {
+        writePortableLedger(directory, sqliteEventsAsLedger(directory).lines);
+      } catch (error) {
+        criticalWarn(`[ledger] SQLite committed event ${event.seq}, but refreshing the portable plan-ledger.jsonl export failed: ${error instanceof Error ? error.message : String(error)}. SQLite remains authoritative; a later read will retry the export.`);
+      }
+    } else {
+      const tempPath = `${ledgerPath}.tmp.${Date.now()}.${Math.floor(Math.random() * 1e9)}`;
+      if (!fs.existsSync(ledgerPath)) {
+        throw new Error("Ledger not initialized. Call initLedger() first.");
+      }
+      const existingContent = fs.readFileSync(ledgerPath);
+      writeFileFsyncedThenRename(tempPath, ledgerPath, Buffer.concat([
+        existingContent,
+        Buffer.from(canonicalEvent),
+        Buffer.from(`
+`)
+      ]));
+      try {
+        appendSqliteLedger(directory, {
+          canonicalEvent,
+          expectedSeq: latestSeq,
+          state: {
+            authorityMode: "file_shadow",
+            parityStatus: "pending"
+          }
+        });
+      } catch (error) {
+        log(`[ledger] SQLite shadow append deferred after file commit: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return event;
+  });
+}
+async function appendLedgerEventWithRetry(directory, eventInput, options) {
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffBase = options.backoffMs ?? 10;
+  let currentExpected = options.expectedHash;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await appendLedgerEvent(directory, eventInput, {
+        expectedHash: currentExpected,
+        planHashAfter: options.planHashAfter
+      });
+    } catch (error) {
+      if (!(error instanceof LedgerStaleWriterError) || attempt >= maxRetries) {
+        throw error;
+      }
+      attempt++;
+      const delayMs = backoffBase * 2 ** (attempt - 1);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      if (options.verifyValid) {
+        const stillValid = await options.verifyValid();
+        if (!stillValid) {
+          return null;
+        }
+      }
+      currentExpected = computeCurrentPlanHash(directory);
+    }
+  }
+}
+async function takeSnapshotWithRetry(directory, plan, options) {
+  const MAX_RETRIES = 3;
+  const TOTAL_ATTEMPTS = 1 + MAX_RETRIES;
+  const telemetrySource = options?.source ?? "save_plan_tool";
+  const snapshotOptions = { planHashAfter: options?.planHashAfter };
+  let lastError;
+  for (let attempt = 1;attempt <= TOTAL_ATTEMPTS; attempt++) {
+    try {
+      await takeSnapshotEvent(directory, plan, snapshotOptions);
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < TOTAL_ATTEMPTS) {
+        await new Promise((r) => setTimeout(r, 10 * 2 ** (attempt - 1)));
+      }
+    }
+  }
+  criticalWarn(`[takeSnapshotWithRetry] Snapshot failed after ${MAX_RETRIES} retries (${TOTAL_ATTEMPTS} attempts): ${lastError.message}`);
+  try {
+    emit("snapshot_failed", {
+      error: lastError.message,
+      retries: MAX_RETRIES,
+      source: telemetrySource
+    });
+  } catch {}
+}
+async function takeSnapshotEvent(directory, plan, options) {
+  const payloadHash = options?.payloadHashOverride ?? (options?.source === "critic_approved" ? computePlanStructureHash(plan) : computePlanLedgerHash(plan));
+  const snapshotPayload = {
+    plan,
+    payload_hash: payloadHash
+  };
+  if (options?.approvalMetadata) {
+    snapshotPayload.approval = options.approvalMetadata;
+  }
+  const planId = derivePlanId(plan);
+  return appendLedgerEvent(directory, {
+    event_type: "snapshot",
+    source: options?.source ?? "takeSnapshotEvent",
+    plan_id: planId,
+    payload: snapshotPayload
+  }, {
+    planHashAfter: options?.planHashAfter,
+    expectedSeq: options?.expectedSeq,
+    expectedLedgerHash: options?.expectedLedgerHash
+  });
+}
+async function replaceTruncatedLedgerWithRecoveryRoot(directory, plan, expected) {
+  assertProjectRoot(directory);
+  const validated = PlanSchema.parse(plan);
+  return withEvidenceLock(directory, LEDGER_LOCK_PATH, "plan-ledger", "reconcile-truncated-ledger", async () => {
+    const ledgerPath = getLedgerPath(directory);
+    if (!fs.existsSync(ledgerPath)) {
+      throw new LedgerStaleWriterError("Stale writer: canonical ledger disappeared before truncated-ledger recovery");
+    }
+    const events = await readLedgerEvents(directory);
+    const tail = events[events.length - 1];
+    if (!tail || tail.seq !== expected.seq || tail.plan_hash_after !== expected.ledgerHash || events[0]?.plan_id !== derivePlanId(validated)) {
+      throw new LedgerStaleWriterError("Stale writer: ledger identity or tail changed before truncated-ledger recovery");
+    }
+    const integrity = await readLedgerEventsWithIntegrity(directory);
+    if (!integrity.truncated || integrity.badSuffix === null) {
+      throw new LedgerStaleWriterError("Stale writer: ledger is no longer truncated; retry against its current tail");
+    }
+    const originalBytes = fs.readFileSync(ledgerPath);
+    const archiveSha256 = crypto.createHash("sha256").update(originalBytes).digest("hex");
+    const swarmDir = path2.dirname(ledgerPath);
+    const archiveSuffix = `.${archiveSha256.slice(0, 12)}.jsonl`;
+    let archiveName = `plan-ledger.reconcile-archive.${Date.now()}.${Math.floor(Math.random() * 1e9)}${archiveSuffix}`;
+    let archivePath = path2.join(swarmDir, archiveName);
+    let archiveNeedsWrite = true;
+    for (const candidate of _internals.readLedgerDirectory(swarmDir).sort(compareCodeUnits)) {
+      if (!candidate.startsWith("plan-ledger.reconcile-archive.") || !candidate.endsWith(archiveSuffix)) {
+        continue;
+      }
+      const candidatePath = path2.join(swarmDir, candidate);
+      if (fs.readFileSync(candidatePath).equals(originalBytes)) {
+        archiveName = candidate;
+        archivePath = candidatePath;
+        archiveNeedsWrite = false;
+        break;
+      }
+    }
+    const archiveTempPath = `${archivePath}.tmp.${crypto.randomBytes(16).toString("hex")}`;
+    const canonicalTempPath = `${ledgerPath}.reconcile.${crypto.randomBytes(16).toString("hex")}.tmp`;
+    const planHash = computePlanLedgerHash(validated);
+    const rawBadSuffix = findRawMalformedSuffix(originalBytes);
+    if (rawBadSuffix.length === 0) {
+      throw new LedgerStaleWriterError("Stale writer: raw ledger bytes no longer contain the malformed suffix detected during replay");
+    }
+    const badSuffixSha256 = crypto.createHash("sha256").update(rawBadSuffix).digest("hex");
+    const recoveryRoot = {
+      seq: 1,
+      timestamp: new Date().toISOString(),
+      plan_id: derivePlanId(validated),
+      event_type: "plan_created",
+      source: "save_plan_truncated_ledger_reconcile",
+      plan_hash_before: "",
+      plan_hash_after: planHash,
+      schema_version: LEDGER_SCHEMA_VERSION,
+      payload: {
+        plan: validated,
+        payload_hash: planHash,
+        recovery: {
+          kind: "truncated_ledger_reconcile",
+          archived_ledger: `.swarm/${archiveName}`,
+          archived_sha256: archiveSha256,
+          bad_suffix_sha256: badSuffixSha256,
+          prior_tail_seq: expected.seq,
+          prior_tail_hash: expected.ledgerHash
+        }
+      }
+    };
+    try {
+      if (archiveNeedsWrite) {
+        _internals.writeFileFsyncedThenRename(archiveTempPath, archivePath, originalBytes);
+      }
+      _internals.fsyncRecoveryDirectory(swarmDir);
+      _internals.writeFileFsyncedThenRename(canonicalTempPath, ledgerPath, `${JSON.stringify(recoveryRoot)}
+`);
+    } finally {
+      for (const tempPath of [archiveTempPath, canonicalTempPath]) {
+        try {
+          fs.unlinkSync(tempPath);
+        } catch {}
+      }
+    }
+    return { archivePath, archiveSha256, recoveryRoot };
+  });
+}
+async function clearPlanLedgerForReset(directory) {
+  assertProjectRoot(directory);
+  await withEvidenceLock(directory, LEDGER_LOCK_PATH, "plan-ledger", "reset-plan-ledger", async () => {
+    const marker = path2.join(directory, ".swarm", "plan-ledger.resetting");
+    fs.writeFileSync(marker, `resetting
+`, "utf8");
+    try {
+      clearSqliteLedger(directory);
+      try {
+        fs.unlinkSync(getLedgerPath(directory));
+      } catch (error) {
+        if (error?.code !== "ENOENT")
+          throw error;
+      }
+    } finally {
+      try {
+        fs.unlinkSync(marker);
+      } catch {}
+    }
+  });
+}
+async function replacePlanLedgerWithRoot(directory, plan, source) {
+  assertProjectRoot(directory);
+  const validated = PlanSchema.parse(plan);
+  await withEvidenceLock(directory, LEDGER_LOCK_PATH, "plan-ledger", "replace-plan-ledger-root", async () => {
+    const ledgerPath = getLedgerPath(directory);
+    if (fs.existsSync(ledgerPath)) {
+      archiveLegacyLedger(directory, fs.readFileSync(ledgerPath));
+    }
+    const planHash = computePlanLedgerHash(validated);
+    const root = {
+      seq: 1,
+      timestamp: new Date().toISOString(),
+      plan_id: derivePlanId(validated),
+      event_type: "plan_created",
+      source,
+      plan_hash_before: "",
+      plan_hash_after: planHash,
+      schema_version: LEDGER_SCHEMA_VERSION,
+      payload: {
+        plan: validated,
+        payload_hash: planHash,
+        plan_epoch: crypto.randomUUID()
+      }
+    };
+    const line = new TextEncoder().encode(serializeLedgerEvent(root));
+    const priorMode = getPlanLedgerState(directory)?.authorityMode ?? "file_shadow";
+    if (priorMode === "file_shadow") {
+      writePortableLedger(directory, [line]);
+      try {
+        replaceSqliteLedger(directory, {
+          canonicalEvents: [line],
+          state: stateForEvents(directory, [root], priorMode),
+          source: source === "savePlan_identity_migration" ? "plan_identity_reinitialized" : "checkpoint_rollback",
+          mode: priorMode,
+          version: package_default.version
+        });
+      } catch (error) {
+        log(`[ledger] SQLite shadow re-root deferred after authoritative file commit: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return;
+    }
+    replaceSqliteLedger(directory, {
+      canonicalEvents: [line],
+      state: stateForEvents(directory, [root], priorMode),
+      source: "checkpoint_rollback",
+      mode: priorMode,
+      version: package_default.version
+    });
+    try {
+      writePortableLedger(directory, [line]);
+    } catch (error) {
+      criticalWarn(`[ledger] SQLite committed rollback root, but refreshing the portable plan-ledger.jsonl export failed: ${error instanceof Error ? error.message : String(error)}. SQLite remains authoritative; a later read will retry the export.`);
+    }
+  });
+}
+async function replayFromLedger(directory, options) {
+  const { plan } = await replayFromLedgerWithStatus(directory, options);
+  return plan;
+}
+async function peekPlanFromLedger(directory, _options) {
+  if (fs.existsSync(path2.join(directory, ".swarm", "plan-ledger.resetting")))
+    return { plan: null, truncated: false, badSuffix: null };
+  const file = readFileLedgerExact(directory);
+  let events = file.events;
+  let truncated = file.truncated;
+  let badSuffix = file.badSuffix;
+  const sqliteReadOnly = readSqliteLedgerEventsReadOnly(directory);
+  if (fs.existsSync(path2.join(directory, ".swarm", "plan-ledger.resetting")))
+    return { plan: null, truncated: false, badSuffix: null };
+  if (sqliteReadOnly.events.length > 0) {
+    const sqlite = {
+      events: sqliteReadOnly.events.map((row) => row.event)
+    };
+    const authority = sqliteReadOnly.state;
+    if (authority?.authorityMode === "sqlite" || events.length === 0) {
+      events = sqlite.events;
+      truncated = false;
+      badSuffix = null;
+    }
+  }
+  if (events.length === 0) {
+    return { plan: null, truncated, badSuffix };
+  }
+  return {
+    plan: reconstructPlanFromEvents(directory, events),
+    truncated,
+    badSuffix
+  };
+}
+async function replayFromLedgerWithStatus(directory, _options) {
+  const { events, truncated, badSuffix } = await readLedgerEventsWithIntegrity(directory);
+  if (events.length === 0) {
+    return { plan: null, truncated, badSuffix };
+  }
+  if (truncated && badSuffix !== null) {
+    await quarantineLedgerSuffix(directory, badSuffix);
+  }
+  const plan = reconstructPlanFromEvents(directory, events);
+  return { plan, truncated, badSuffix };
+}
+function reconstructPlanFromEvents(directory, events) {
+  const targetPlanId = events[0].plan_id;
+  const relevantEvents = events.filter((e) => e.plan_id === targetPlanId);
+  {
+    const snapshotEvents = relevantEvents.filter((e) => e.event_type === "snapshot");
+    if (snapshotEvents.length > 0) {
+      const latestSnapshotEvent = snapshotEvents[snapshotEvents.length - 1];
+      const snapshotPayload = latestSnapshotEvent.payload;
+      let plan2 = snapshotPayload.plan;
+      const eventsAfterSnapshot = relevantEvents.filter((e) => e.seq > latestSnapshotEvent.seq);
+      for (const event of eventsAfterSnapshot) {
+        plan2 = applyEventToPlan(plan2, event);
+        if (plan2 === null) {
+          return null;
+        }
+      }
+      return plan2;
+    }
+  }
+  const createdEvent = relevantEvents.find((e) => e.event_type === "plan_created");
+  if (createdEvent?.payload && typeof createdEvent.payload === "object" && "plan" in createdEvent.payload) {
+    const parseResult = PlanSchema.safeParse(createdEvent.payload.plan);
+    if (parseResult.success) {
+      let plan2 = parseResult.data;
+      const eventsAfterCreated = relevantEvents.filter((e) => e.seq > createdEvent.seq);
+      for (const event of eventsAfterCreated) {
+        if (plan2 === null)
+          return null;
+        plan2 = applyEventToPlan(plan2, event);
+      }
+      return plan2;
+    }
+  }
+  const planJsonPath = getPlanJsonPath(directory);
+  if (!fs.existsSync(planJsonPath)) {
+    return null;
+  }
+  let plan;
+  try {
+    const content = fs.readFileSync(planJsonPath, "utf8");
+    plan = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  for (const event of relevantEvents) {
+    if (plan === null) {
+      return null;
+    }
+    plan = applyEventToPlan(plan, event);
+  }
+  return plan;
+}
+function applyEventToPlan(plan, event) {
+  switch (event.event_type) {
+    case "plan_created":
+      if (event.payload && typeof event.payload === "object" && "plan" in event.payload) {
+        const parsed = PlanSchema.safeParse(event.payload.plan);
+        if (parsed.success)
+          return parsed.data;
+      }
+      return plan;
+    case "task_status_changed":
+      if (event.task_id && event.to_status) {
+        const parseResult = TaskStatusSchema.safeParse(event.to_status);
+        if (!parseResult.success) {
+          return plan;
+        }
+        for (const phase of plan.phases) {
+          const task = phase.tasks.find((t) => t.id === event.task_id);
+          if (task) {
+            task.status = parseResult.data;
+            break;
+          }
+        }
+      }
+      return plan;
+    case "phase_completed":
+      if (event.phase_id) {
+        const phase = plan.phases.find((p) => p.id === event.phase_id);
+        if (phase) {
+          phase.status = "complete";
+        }
+      }
+      return plan;
+    case "plan_exported":
+      return plan;
+    case "task_added":
+      return plan;
+    case "task_removed":
+      if (event.task_id) {
+        for (const phase of plan.phases) {
+          const idx = phase.tasks.findIndex((t) => t.id === event.task_id);
+          if (idx !== -1) {
+            phase.tasks.splice(idx, 1);
+            break;
+          }
+        }
+      }
+      return plan;
+    case "task_updated":
+      return plan;
+    case "plan_rebuilt":
+      return plan;
+    case "task_reordered":
+      return plan;
+    case "snapshot":
+      return plan;
+    case "plan_reset":
+      return null;
+    case "execution_profile_set": {
+      const rawProfile = event.payload?.execution_profile;
+      if (rawProfile !== undefined) {
+        const parsed = ExecutionProfileSchema.safeParse(rawProfile);
+        if (parsed.success) {
+          return { ...plan, execution_profile: parsed.data };
+        }
+      }
+      return plan;
+    }
+    case "execution_profile_locked": {
+      if (plan.execution_profile) {
+        return {
+          ...plan,
+          execution_profile: { ...plan.execution_profile, locked: true }
+        };
+      }
+      return plan;
+    }
+    default:
+      throw new Error(`applyEventToPlan: unhandled event type "${event.event_type}" at seq ${event.seq}`);
+  }
+}
+async function readLedgerEventsWithIntegrity(directory, options) {
+  const ledgerPath = getLedgerPath(directory);
+  if (!fs.existsSync(ledgerPath) && !hasSqliteLedger(directory)) {
+    return { events: [], truncated: false, badSuffix: null };
+  }
+  try {
+    const result = coordinateLedger(directory);
+    return {
+      events: [...result.events].sort((a, b) => a.seq - b.seq),
+      truncated: result.truncated,
+      badSuffix: result.badSuffix
+    };
+  } catch (error) {
+    if (options?.failClosedOnReadError) {
+      throw new Error(`PLAN_LEDGER_UNREADABLE: ${ledgerPath} exists but could not be read (${error instanceof Error ? error.message : String(error)}); plan state cannot be resolved. This is NOT an absent ledger \u2014 preserve the file and check permissions/filesystem health before retrying.`);
+    }
+    const code = error?.code;
+    if (code && ["EACCES", "EIO", "EISDIR", "EPERM"].includes(code)) {
+      return { events: [], truncated: false, badSuffix: null };
+    }
+    throw error;
+  }
+}
+async function quarantineLedgerSuffix(directory, badSuffix) {
+  let salvagedCount = 0;
+  for (const line of badSuffix.split(`
+`)) {
+    if (line.trim() === "")
+      continue;
+    try {
+      JSON.parse(line);
+      salvagedCount++;
+    } catch {}
+  }
+  try {
+    assertProjectRoot(directory);
+    const hash = crypto.createHash("sha256").update(badSuffix, "utf8").digest("hex").slice(0, 12);
+    const swarmDir = path2.join(directory, ".swarm");
+    try {
+      const existing = _internals.readLedgerDirectory(swarmDir).sort(compareCodeUnits).filter((name) => name.startsWith("plan-ledger.quarantine.") && name.endsWith(`.${hash}`));
+      for (const name of existing) {
+        const existingPath = path2.join(swarmDir, name);
+        if (fs.readFileSync(existingPath, "utf8") === badSuffix) {
+          return { path: existingPath, salvagedCount };
+        }
+      }
+    } catch {}
+    const quarantinePath = path2.join(swarmDir, `plan-ledger.quarantine.${Date.now()}.${hash}`);
+    fs.writeFileSync(quarantinePath, badSuffix, "utf8");
+    log(`[ledger] Corrupted suffix quarantined to ${path2.relative(directory, quarantinePath)} (salvageable events: ${salvagedCount})`);
+    return { path: quarantinePath, salvagedCount };
+  } catch {
+    return { path: null, salvagedCount };
+  }
+}
+async function loadLastApprovedPlan(directory, expectedPlanId) {
+  const events = await readLedgerEvents(directory);
+  return findLastApprovedSnapshot(events, expectedPlanId);
+}
+async function loadLastPlanCriticApprovedSnapshot(directory, expectedPlanId) {
+  const events = await readLedgerEvents(directory);
+  return findLastApprovedSnapshot(events, expectedPlanId, (payload) => payload.approval?.source === "plan_critic_gate");
+}
+function findLastApprovedSnapshot(events, expectedPlanId, extraFilter) {
+  if (events.length === 0) {
+    return null;
+  }
+  for (let i = events.length - 1;i >= 0; i--) {
+    const event = events[i];
+    if (event.event_type !== "snapshot")
+      continue;
+    if (event.source !== "critic_approved")
+      continue;
+    if (expectedPlanId !== undefined && event.plan_id !== expectedPlanId) {
+      continue;
+    }
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object" || !payload.plan) {
+      continue;
+    }
+    if (expectedPlanId !== undefined) {
+      const payloadPlanId = derivePlanId(payload.plan);
+      if (payloadPlanId !== expectedPlanId) {
+        continue;
+      }
+    }
+    if (extraFilter && !extraFilter(payload)) {
+      continue;
+    }
+    return {
+      plan: payload.plan,
+      seq: event.seq,
+      timestamp: event.timestamp,
+      approval: payload.approval,
+      payloadHash: payload.payload_hash
+    };
+  }
+  return null;
+}
+var _internals = {
+  computePlanLedgerHash,
+  computePlanStructureHash,
+  computeCurrentPlanHash,
+  ledgerExists,
+  getLatestLedgerSeq,
+  readLedgerEvents,
+  initLedger,
+  appendLedgerEvent,
+  appendLedgerEventWithRetry,
+  takeSnapshotEvent,
+  replayFromLedger,
+  replayFromLedgerWithStatus,
+  peekPlanFromLedger,
+  applyEventToPlan,
+  readLedgerEventsWithIntegrity,
+  quarantineLedgerSuffix,
+  loadLastApprovedPlan,
+  loadLastPlanCriticApprovedSnapshot,
+  getLedgerPath,
+  getPlanJsonPath,
+  archiveLegacyLedger,
+  writePortableLedger,
+  writeFileFsyncedThenRename,
+  fsyncRecoveryDirectory,
+  readLedgerDirectory,
+  randomUUID: () => crypto.randomUUID()
+};
+
+export { renderPlanningProfileDirective, resolvePlanningProfile, normalizeExecutionProfileForHash, LedgerStaleWriterError, computePlanLedgerHash, computePlanStructureHash, computeCurrentPlanHash, ledgerExists, getLatestLedgerSeq, readLedgerEvents, initLedger, readPlanEpochIdentity, getOrAdoptPlanEpochUnderLock, appendLedgerEvent, takeSnapshotWithRetry, takeSnapshotEvent, replaceTruncatedLedgerWithRecoveryRoot, clearPlanLedgerForReset, replacePlanLedgerWithRoot, replayFromLedger, peekPlanFromLedger, replayFromLedgerWithStatus, readLedgerEventsWithIntegrity, loadLastApprovedPlan };