@zhivex-ai/harness 1.2.0 → 1.3.0-rc.7

package/dist/index-a97bezbz.js

@@ -0,0 +1,1073 @@
+import {
+  HARNESS_OPERATIONS_SCHEMA_VERSION,
+  HARNESS_SQLITE_FILE,
+  openHarnessPersistence,
+  sqliteAdapter,
+  workspaceCheckpointSchema,
+  workspaceRestoreOperationSchema
+} from "./index-h0mqx2ed.js";
+import {
+  HARNESS_SESSION_SCHEMA_VERSION,
+  openCliSessionStore,
+  validateStateDirectory
+} from "./index-42gp2hy8.js";
+import {
+  SqliteDatabase,
+  readRegularFileChunksNoFollow
+} from "./index-yb239ghk.js";
+import {
+  HarnessStateConflictError,
+  HarnessWorkspaceError
+} from "./index-gq9xagx2.js";
+
+// src/persistence/recorded-workspace.ts
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+async function validateRecordedWorkspace(workspace, allowAbsent = false) {
+  if (!path.isAbsolute(workspace) || path.normalize(workspace) !== workspace || /[\x00-\x1f\x7f]/.test(workspace))
+    throw new Error("RECORDED_WORKSPACE_INVALID");
+  let ancestor = workspace;
+  for (;; ) {
+    try {
+      const info = await lstat(ancestor);
+      if (!info.isDirectory() || info.isSymbolicLink() || await realpath(ancestor) !== ancestor)
+        throw new Error("RECORDED_WORKSPACE_INVALID");
+      return workspace;
+    } catch (error) {
+      if (!allowAbsent || error.code !== "ENOENT")
+        throw error;
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor)
+        throw new Error("RECORDED_WORKSPACE_INVALID");
+      ancestor = parent;
+    }
+  }
+}
+
+// src/persistence/state-backup-stream.ts
+var MAGIC = `ZHIVEX-STATE-SEGMENTS-1
+`;
+var STRING_CHARS = 8192;
+var MAX_FRAME_BYTES = 64 * 1024;
+function* canonicalChunks(value) {
+  if (typeof value === "string") {
+    yield '"';
+    for (let i = 0;i < value.length; ) {
+      let end = Math.min(i + STRING_CHARS, value.length);
+      if (end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1]))
+        end--;
+      yield JSON.stringify(value.slice(i, end)).slice(1, -1);
+      i = end;
+    }
+    yield '"';
+  } else if (value === null || typeof value !== "object") {
+    yield JSON.stringify(value);
+  } else if (Array.isArray(value)) {
+    yield "[";
+    for (let i = 0;i < value.length; i++) {
+      if (i)
+        yield ",";
+      yield* canonicalChunks(value[i]);
+    }
+    yield "]";
+  } else {
+    yield "{";
+    let first = true;
+    for (const key of Object.keys(value).sort()) {
+      if (!first)
+        yield ",";
+      first = false;
+      yield* canonicalChunks(key);
+      yield ":";
+      yield* canonicalChunks(value[key]);
+    }
+    yield "}";
+  }
+}
+function* tokens(value) {
+  if (typeof value === "string") {
+    for (let i = 0;i < value.length; i += STRING_CHARS)
+      yield ["text", value.slice(i, i + STRING_CHARS)];
+    yield ["string"];
+  } else if (value === null || typeof value !== "object")
+    yield ["value", value];
+  else {
+    yield [Array.isArray(value) ? "array" : "object"];
+    if (Array.isArray(value))
+      for (const item of value)
+        yield* tokens(item);
+    else
+      for (const [key, item] of Object.entries(value)) {
+        yield* tokens(key);
+        yield* tokens(item);
+      }
+    yield ["end"];
+  }
+}
+function* segmentedChunks(value) {
+  yield MAGIC;
+  for (const token of tokens(value))
+    yield `${JSON.stringify(token)}
+`;
+}
+async function readBackupTransport(source, legacyMaxBytes) {
+  const fail = () => {
+    throw new Error("Harness state backup segment stream is invalid or incomplete.");
+  };
+  const stack = [];
+  let root;
+  let hasRoot = false;
+  let pieces = [];
+  let pending = Buffer.alloc(0);
+  let segmented;
+  const legacy = [];
+  let legacyBytes = 0;
+  const append = (value) => {
+    const parent = stack.at(-1);
+    if (!parent) {
+      if (hasRoot)
+        fail();
+      root = value;
+      hasRoot = true;
+    } else if (Array.isArray(parent.value))
+      parent.value.push(value);
+    else if (parent.key === undefined) {
+      if (typeof value !== "string" || Object.hasOwn(parent.value, value))
+        fail();
+      parent.key = value;
+    } else {
+      Object.defineProperty(parent.value, parent.key, { value, enumerable: true, writable: true, configurable: true });
+      delete parent.key;
+    }
+  };
+  const consume = (line) => {
+    if (line.length > MAX_FRAME_BYTES)
+      fail();
+    const token = JSON.parse(line.toString("utf8"));
+    if (!Array.isArray(token))
+      fail();
+    const frame = token;
+    const [kind, value] = frame;
+    if (kind === "text" && frame.length === 2 && typeof value === "string") {
+      pieces.push(value);
+      return;
+    }
+    if (kind === "string" && frame.length === 1) {
+      append(pieces.join(""));
+      pieces = [];
+      return;
+    }
+    if (pieces.length)
+      fail();
+    if (kind === "value" && frame.length === 2 && (value === null || typeof value === "boolean" || typeof value === "number"))
+      append(value);
+    else if ((kind === "array" || kind === "object") && frame.length === 1) {
+      if (stack.length >= 512)
+        fail();
+      const value2 = kind === "array" ? [] : {};
+      append(value2);
+      stack.push({ value: value2 });
+    } else if (kind === "end" && frame.length === 1) {
+      const parent = stack.pop();
+      if (!parent || parent.key !== undefined)
+        fail();
+    } else
+      fail();
+  };
+  for await (const chunk of readRegularFileChunksNoFollow(source, {
+    label: "Harness state backup",
+    requireSingleLink: true,
+    requirePrivate: true
+  })) {
+    pending = Buffer.concat([pending, chunk]);
+    if (segmented === undefined) {
+      if (pending.length < Buffer.byteLength(MAGIC))
+        continue;
+      segmented = pending.subarray(0, MAGIC.length).toString() === MAGIC;
+      if (segmented)
+        pending = pending.subarray(MAGIC.length);
+    }
+    if (!segmented) {
+      legacyBytes += pending.length;
+      if (legacyBytes > legacyMaxBytes)
+        throw new Error("Harness state backup exceeds the legacy size limit.");
+      legacy.push(pending);
+      pending = Buffer.alloc(0);
+      continue;
+    }
+    let newline;
+    while ((newline = pending.indexOf(10)) !== -1) {
+      consume(pending.subarray(0, newline));
+      pending = pending.subarray(newline + 1);
+    }
+    if (pending.length > MAX_FRAME_BYTES)
+      fail();
+  }
+  if (!segmented) {
+    if (legacyBytes + pending.length > legacyMaxBytes)
+      throw new Error("Harness state backup exceeds the legacy size limit.");
+    return JSON.parse(Buffer.concat([...legacy, pending]).toString("utf8"));
+  }
+  if (pending.length || stack.length || pieces.length || !hasRoot)
+    fail();
+  return root;
+}
+
+// src/persistence/state-backup.ts
+import { createHash, randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { chmod, link, lstat as lstat2, open, realpath as realpath2, unlink } from "node:fs/promises";
+import path2 from "node:path";
+import { z } from "zod";
+import { normalizeAgentRunState } from "@zhivex-ai/agents";
+import { createSqliteAgentRunStore } from "@zhivex-ai/agents/ops";
+var HARNESS_STATE_BACKUP_SCHEMA_VERSION = 1;
+var HARNESS_STATE_BACKUP_MAX_BYTES = 64 * 1024 * 1024;
+var terminalRunStatuses = new Set(["completed", "failed", "cancelled", "timed_out"]);
+var terminalSessionStatuses = new Set(["completed", "failed", "cancelled", "timed_out"]);
+var digestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+var bindingKeySchema = z.string().regex(/^[a-f0-9]{64}$/);
+var jsonRecordSchema = z.record(z.string(), z.unknown());
+var durableScopeSchema = z.object({
+  tenantId: z.string().min(1),
+  userId: z.string().min(1).optional(),
+  namespace: z.string().min(1).optional()
+}).strict();
+var journalEntrySchema = z.object({
+  runId: z.string().min(1),
+  scope: durableScopeSchema,
+  toolCallId: z.string().min(1),
+  toolName: z.string().min(1),
+  status: z.enum(["pending", "running", "completed", "failed"]),
+  idempotencyKey: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+  input: z.json().optional(),
+  output: z.json().optional(),
+  error: z.object({ message: z.string() }).strict().optional(),
+  startedAt: z.number().nonnegative().optional(),
+  completedAt: z.number().nonnegative().optional(),
+  updatedAt: z.number().nonnegative()
+}).passthrough();
+var runRecordSchema = z.object({
+  key: z.string().min(1).max(1024),
+  state: jsonRecordSchema,
+  updatedAt: z.number().int().nonnegative()
+}).strict();
+var journalRecordSchema = z.object({
+  runKey: z.string().min(1).max(1024),
+  toolCallId: z.string().min(1).max(1024),
+  entry: journalEntrySchema,
+  revision: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative()
+}).strict();
+var idempotencyRecordSchema = z.object({
+  key: z.string().min(1).max(1024),
+  runKey: z.string().min(1).max(1024),
+  updatedAt: z.number().int().nonnegative()
+}).strict();
+var parentRecordSchema = z.object({
+  runKey: z.string().min(1).max(1024),
+  parentRunKey: z.string().min(1).max(1024),
+  updatedAt: z.number().int().nonnegative()
+}).strict();
+var memoryRecordSchema = z.object({
+  key: z.string().min(1).max(1024),
+  messages: z.array(z.unknown()),
+  updatedAt: z.number().int().nonnegative()
+}).strict();
+var sessionRecordSchema = z.object({
+  sessionId: z.string().min(1).max(260),
+  workspaceKey: bindingKeySchema,
+  scopeKey: bindingKeySchema,
+  title: z.string().nullable(),
+  parentSessionId: z.string().nullable(),
+  forkedFromTurnId: z.string().nullable(),
+  revision: z.number().int().nonnegative(),
+  activitySequence: z.number().int().nonnegative(),
+  createdAt: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative(),
+  archivedAt: z.number().int().nonnegative().nullable(),
+  deletedAt: z.number().int().nonnegative().nullable(),
+  metadataBytes: z.number().int().nonnegative()
+}).strict();
+var sessionRunRecordSchema = z.object({
+  turnId: z.string().min(1).max(260),
+  sourceTurnId: z.string().nullable(),
+  sessionId: z.string().min(1).max(260),
+  ordinal: z.number().int().nonnegative(),
+  runId: z.string().min(1).max(260),
+  provider: z.string().min(1).max(260),
+  model: z.string().min(1).max(260),
+  role: z.string().nullable(),
+  status: z.string().min(1),
+  createdAt: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative(),
+  completedAt: z.number().int().nonnegative().nullable(),
+  metadataBytes: z.number().int().nonnegative()
+}).strict();
+var checkpointRecordSchema = z.discriminatedUnion("kind", [
+  z.object({
+    id: z.string().uuid(),
+    workspaceKey: bindingKeySchema,
+    scopeKey: bindingKeySchema,
+    kind: z.literal("checkpoint"),
+    body: workspaceCheckpointSchema
+  }).strict(),
+  z.object({
+    id: z.string().uuid(),
+    workspaceKey: bindingKeySchema,
+    scopeKey: bindingKeySchema,
+    kind: z.literal("restore"),
+    body: workspaceRestoreOperationSchema
+  }).strict()
+]);
+var checkpointTableSql = "CREATE TABLE IF NOT EXISTS zhivex_workspace_checkpoints (id TEXT PRIMARY KEY, workspace_key TEXT NOT NULL, scope_key TEXT NOT NULL, kind TEXT NOT NULL, body TEXT NOT NULL)";
+var stateBackupPayloadSchema = z.object({
+  schemaVersion: z.literal(HARNESS_STATE_BACKUP_SCHEMA_VERSION),
+  kind: z.literal("state-backup"),
+  createdAt: z.iso.datetime({ precision: 3 }),
+  binding: z.object({
+    workspaceKey: bindingKeySchema,
+    scopeKey: bindingKeySchema,
+    scopePrefix: z.string().min(1).max(1024)
+  }).strict(),
+  schemas: z.object({
+    operations: z.literal(HARNESS_OPERATIONS_SCHEMA_VERSION),
+    sessions: z.literal(HARNESS_SESSION_SCHEMA_VERSION)
+  }).strict(),
+  records: z.object({
+    runs: z.array(runRecordSchema),
+    toolJournal: z.array(journalRecordSchema),
+    idempotency: z.array(idempotencyRecordSchema),
+    parents: z.array(parentRecordSchema),
+    memory: z.array(memoryRecordSchema),
+    sessions: z.array(sessionRecordSchema),
+    sessionRuns: z.array(sessionRunRecordSchema),
+    workspaceCheckpoints: z.array(checkpointRecordSchema).max(100).optional(),
+    budgetLedgers: z.array(runRecordSchema).optional()
+  }).strict()
+}).strict();
+var stateBackupBundleSchema = stateBackupPayloadSchema.extend({ checksum: digestSchema }).strict();
+var canonicalJson = (value) => {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+};
+var checksumPayload = (payload) => {
+  const hash = createHash("sha256");
+  for (const chunk of canonicalChunks(payload))
+    hash.update(chunk);
+  return `sha256:${hash.digest("hex")}`;
+};
+var stableKey = (kind, value) => createHash("sha256").update(kind).update("\x00").update(value).digest("hex");
+var scopeValue = (config) => `${config.scope.tenantId}\x00${config.scope.userId ?? ""}\x00${config.scope.namespace ?? ""}`;
+var scopePrefix = (config) => `${encodeURIComponent(config.scope.namespace ?? "default")}:${encodeURIComponent(config.scope.tenantId)}:${encodeURIComponent(config.scope.userId ?? "*")}:`;
+var stateMatchesScope = (config, state) => {
+  if (!state || typeof state !== "object" || Array.isArray(state))
+    return false;
+  const candidate = state;
+  if (!candidate.scope || typeof candidate.scope !== "object" || Array.isArray(candidate.scope))
+    return false;
+  const scope = candidate.scope;
+  return scope.tenantId === config.scope.tenantId && (scope.userId ?? undefined) === (config.scope.userId ?? undefined) && (scope.namespace ?? undefined) === (config.scope.namespace ?? undefined);
+};
+var budgetScopePrefix = (config) => `__zhivex_budget__:${encodeURIComponent(config.scope.tenantId)}:${encodeURIComponent(config.scope.userId ?? "*")}:`;
+var coordinatorIds = (runs) => new Set(runs.flatMap(({ state }) => {
+  const id = state.budgetCoordinatorId;
+  return typeof id === "string" ? [id] : [];
+}));
+var validateBudgetLedger = (config, run, identities) => {
+  const state = validatedRunState(run.state, `Budget ledger ${run.key}`);
+  const identity = state.metadata?.budgetIdentity;
+  if (state.scope?.namespace !== "__zhivex_budget__" || state.scope?.tenantId !== config.scope.tenantId || (state.scope?.userId ?? undefined) !== (config.scope.userId ?? undefined) || state.provider !== "zhivex" || state.modelId !== "budget-coordinator" || state.metadata?.budgetCoordinator !== true || typeof identity !== "string" || !identities.has(identity) || !/^budget_[a-f0-9]{64}$/.test(state.runId) || run.key !== `${budgetScopePrefix(config)}${state.runId}`) {
+    throw new HarnessStateConflictError("Budget ledger is not bound to an exported run and durable scope.");
+  }
+  assertTerminalState(state, `Budget ledger ${run.key}`);
+  const allocations = state.metadata?.allocations;
+  if (!allocations || typeof allocations !== "object" || Array.isArray(allocations))
+    throw new HarnessStateConflictError("Invalid budget ledger allocations.");
+  for (const [id, value] of Object.entries(allocations)) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(id) || !value || typeof value !== "object" || Array.isArray(value) || value.status !== "confirmed") {
+      throw new HarnessStateConflictError("Budget ledger retains unresolved reservations or unknown consumption.");
+    }
+    const tokens2 = value.tokens;
+    if (!tokens2 || typeof tokens2 !== "object" || Array.isArray(tokens2) || ![tokens2.inputTokens, tokens2.outputTokens, tokens2.totalTokens].every((amount) => typeof amount === "number" && Number.isSafeInteger(amount) && amount >= 0) || tokens2.totalTokens < tokens2.inputTokens + tokens2.outputTokens) {
+      throw new HarnessStateConflictError("Invalid budget ledger token receipt.");
+    }
+  }
+  return identity;
+};
+var bindingForConfig = async (config) => ({
+  workspaceKey: stableKey("workspace", await realpath2(path2.resolve(config.workspace))),
+  scopeKey: stableKey("scope", scopeValue(config)),
+  scopePrefix: scopePrefix(config)
+});
+var parseJsonRecord = (value, label) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new HarnessStateConflictError(`${label} contains invalid JSON.`, { cause: error });
+  }
+  return jsonRecordSchema.parse(parsed);
+};
+var prepareDatabase = async (config) => {
+  if (config.storeBackend !== "sqlite") {
+    throw new HarnessStateConflictError("State backup requires the sqlite store backend.");
+  }
+  const persistence = await openHarnessPersistence(config, { migrateLegacyFileStore: false });
+  persistence.close();
+  const sessions = await openCliSessionStore({
+    workspace: config.workspace,
+    stateDirectory: config.stateDirectory,
+    scope: config.scope
+  });
+  sessions.close();
+  return path2.join(await realpath2(config.stateDirectory), HARNESS_SQLITE_FILE);
+};
+var locateExistingDatabase = async (config) => {
+  if (config.storeBackend !== "sqlite") {
+    throw new HarnessStateConflictError("State backup requires the sqlite store backend.");
+  }
+  await validateStateDirectory(config.workspace, config.stateDirectory);
+  let canonicalStateDirectory;
+  try {
+    canonicalStateDirectory = await realpath2(config.stateDirectory);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+  const databasePath = path2.join(canonicalStateDirectory, HARNESS_SQLITE_FILE);
+  try {
+    const entry = await lstat2(databasePath);
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+      throw new HarnessWorkspaceError(`The SQLite state path must be a real file: ${databasePath}.`);
+    }
+    return databasePath;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+};
+var assertTerminalState = (state, label) => {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw new HarnessStateConflictError(`${label} is not a terminal run.`);
+  }
+  const candidate = state;
+  if (typeof candidate.runId !== "string" || !terminalRunStatuses.has(String(candidate.status))) {
+    throw new HarnessStateConflictError(`${label} is not a terminal run.`);
+  }
+  const unresolvedAuxiliary = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      return false;
+    const entry = value;
+    return entry.unknownCompactionUsage === true || Array.isArray(entry.compactionAttempts) && entry.compactionAttempts.some((attempt) => !attempt || typeof attempt !== "object" || attempt.status !== "confirmed") || Array.isArray(entry.childRuns) && entry.childRuns.some(unresolvedAuxiliary) || entry.resumeState !== undefined && unresolvedAuxiliary(entry.resumeState);
+  };
+  if (unresolvedAuxiliary(candidate))
+    throw new HarnessStateConflictError(`${label} retains unresolved auxiliary model consumption.`);
+  if (Array.isArray(candidate.pendingApprovals) && candidate.pendingApprovals.length > 0) {
+    throw new HarnessStateConflictError(`${label} retains approval authority and cannot be backed up.`);
+  }
+};
+var validatedRunState = (value, label) => {
+  try {
+    return normalizeAgentRunState(value);
+  } catch (error) {
+    throw new HarnessStateConflictError(`${label} is not a valid AgentRunState.`, { cause: error });
+  }
+};
+var readPayload = async (config, recordedWorkspace, accessLease) => {
+  const databasePath = recordedWorkspace ? await locateExistingDatabase(config) : await prepareDatabase(config);
+  if (!databasePath)
+    throw new HarnessStateConflictError("Archived state database is missing.");
+  const binding = recordedWorkspace ? { workspaceKey: stableKey("workspace", recordedWorkspace), scopeKey: stableKey("scope", scopeValue(config)), scopePrefix: scopePrefix(config) } : await bindingForConfig(config);
+  const database = new SqliteDatabase(databasePath, { create: false, strict: true, ...recordedWorkspace ? { readonly: true } : {}, ...accessLease ? { accessLease } : {} });
+  let transactionStarted = false;
+  try {
+    database.exec("PRAGMA busy_timeout = 5000");
+    database.exec("PRAGMA foreign_keys = ON");
+    database.exec(recordedWorkspace ? "BEGIN" : "BEGIN IMMEDIATE");
+    transactionStarted = true;
+    if (recordedWorkspace && database.query("SELECT version FROM zhivex_cli_session_schema WHERE singleton=1").get()?.version !== HARNESS_SESSION_SCHEMA_VERSION)
+      throw new HarnessStateConflictError("Archived session schema is incompatible.");
+    const allRunRows = database.query("SELECT run_id, state_json, updated_at_ms FROM zhivex_agent_runs ORDER BY run_id").all();
+    let historyReader;
+    const runRows = allRunRows.flatMap((row) => {
+      const record = parseJsonRecord(row.state_json, `Run ${row.run_id}`);
+      const hydrated = record.checkpointHistory ? (historyReader ??= createSqliteAgentRunStore({ db: sqliteAdapter(database), history: "incremental" })).load(String(record.runId), record.scope) : record;
+      if (hydrated instanceof Promise || !hydrated)
+        throw new HarnessStateConflictError("Cannot hydrate state backup history.");
+      const state = validatedRunState(hydrated, `Run ${row.run_id}`);
+      return stateMatchesScope(config, state) ? [{ row, state }] : [];
+    });
+    const runs = runRows.map(({ row, state }) => {
+      assertTerminalState(state, `Run ${row.run_id}`);
+      return { key: row.run_id, state, updatedAt: row.updated_at_ms };
+    });
+    const identities = coordinatorIds(runs);
+    const budgetLedgers = allRunRows.flatMap((row) => {
+      const state = parseJsonRecord(row.state_json, `Run ${row.run_id}`);
+      const metadata = state.metadata;
+      if (typeof metadata?.budgetIdentity !== "string" || !identities.has(metadata.budgetIdentity)) {
+        const scope = state.scope;
+        if (scope?.namespace === "__zhivex_budget__" && scope.tenantId === config.scope.tenantId && (scope.userId ?? undefined) === (config.scope.userId ?? undefined)) {
+          throw new HarnessStateConflictError("An unlinked shared budget ledger cannot be safely assigned to this backup scope; retain the original database.");
+        }
+        return [];
+      }
+      const record = { key: row.run_id, state, updatedAt: row.updated_at_ms };
+      validateBudgetLedger(config, record, identities);
+      return [record];
+    });
+    if (new Set(budgetLedgers.map((run) => run.state.metadata.budgetIdentity)).size !== identities.size || budgetLedgers.length !== identities.size) {
+      throw new HarnessStateConflictError("An exported run has a missing or duplicate shared budget ledger.");
+    }
+    const runKeys = new Set([...runs, ...budgetLedgers].map((run) => run.key));
+    const activeLeases = database.query("SELECT run_key, expires_at_ms FROM zhivex_agent_runs_leases").all().filter((row) => runKeys.has(row.run_key) && row.expires_at_ms > Date.now()).length;
+    if (activeLeases > 0) {
+      throw new HarnessStateConflictError("State export refuses to capture active run leases.", { retryable: true });
+    }
+    const journal = database.query("SELECT run_key, tool_call_id, entry_json, revision, updated_at_ms FROM zhivex_agent_runs_tool_journal ORDER BY run_key, tool_call_id").all().filter((row) => runKeys.has(row.run_key)).map((row) => {
+      let entry;
+      try {
+        entry = journalEntrySchema.parse(parseJsonRecord(row.entry_json, `Tool journal ${row.tool_call_id}`));
+      } catch (error) {
+        throw new HarnessStateConflictError(`Tool journal ${row.tool_call_id} is invalid.`, { cause: error });
+      }
+      if (!stateMatchesScope(config, entry)) {
+        throw new HarnessStateConflictError(`Tool journal ${row.tool_call_id} is bound to another durable scope.`);
+      }
+      return {
+        runKey: row.run_key,
+        toolCallId: row.tool_call_id,
+        entry,
+        revision: row.revision,
+        updatedAt: row.updated_at_ms
+      };
+    });
+    const idempotency = database.query("SELECT idempotency_key, run_id, updated_at_ms FROM zhivex_agent_runs_idempotency ORDER BY idempotency_key").all().filter((row) => runKeys.has(row.run_id)).map((row) => ({
+      key: row.idempotency_key,
+      runKey: row.run_id,
+      updatedAt: row.updated_at_ms
+    }));
+    const parents = database.query("SELECT run_id, parent_run_id, updated_at_ms FROM zhivex_agent_runs_parents ORDER BY run_id").all().filter((row) => runKeys.has(row.run_id) && runKeys.has(row.parent_run_id)).map((row) => ({
+      runKey: row.run_id,
+      parentRunKey: row.parent_run_id,
+      updatedAt: row.updated_at_ms
+    }));
+    const memoryKeys = new Set(runs.map((run) => `${binding.scopePrefix}${String(run.state.runId)}`));
+    const memory = database.query("SELECT memory_key, messages_json, updated_at_ms FROM zhivex_agent_memory ORDER BY memory_key").all().filter((row) => memoryKeys.has(row.memory_key)).map((row) => ({
+      key: row.memory_key,
+      messages: z.array(z.unknown()).parse(JSON.parse(row.messages_json)),
+      updatedAt: row.updated_at_ms
+    }));
+    const sessionRows = database.query("SELECT * FROM zhivex_cli_sessions ORDER BY session_id").all().filter((row) => row.workspace_key === binding.workspaceKey && row.scope_key === binding.scopeKey);
+    const selectedSessionIds = new Set(sessionRows.map((row) => row.session_id));
+    const sessionRunRows = database.query("SELECT * FROM zhivex_cli_session_runs ORDER BY session_id, ordinal").all().filter((row) => selectedSessionIds.has(row.session_id));
+    for (const row of sessionRunRows) {
+      if (!terminalSessionStatuses.has(row.status) || !runs.some((run) => run.state.runId === row.run_id)) {
+        throw new HarnessStateConflictError(`Session run ${row.run_id} is active or has no terminal run state.`);
+      }
+    }
+    const sessions = sessionRows.map((row) => ({
+      sessionId: row.session_id,
+      workspaceKey: row.workspace_key,
+      scopeKey: row.scope_key,
+      title: row.title,
+      parentSessionId: row.parent_session_id,
+      forkedFromTurnId: row.forked_from_turn_id,
+      revision: row.revision,
+      activitySequence: row.activity_seq,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      archivedAt: row.archived_at,
+      deletedAt: row.deleted_at,
+      metadataBytes: row.metadata_bytes
+    }));
+    const sessionRuns = sessionRunRows.map((row) => ({
+      turnId: row.turn_id,
+      sourceTurnId: row.source_turn_id,
+      sessionId: row.session_id,
+      ordinal: row.ordinal,
+      runId: row.run_id,
+      provider: row.provider,
+      model: row.model,
+      role: row.role,
+      status: row.status,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      completedAt: row.completed_at,
+      metadataBytes: row.metadata_bytes
+    }));
+    const hasCheckpoints = database.query("SELECT name FROM sqlite_master WHERE type='table' AND name='zhivex_workspace_checkpoints'").get();
+    const workspaceCheckpoints = hasCheckpoints ? database.query("SELECT * FROM zhivex_workspace_checkpoints WHERE workspace_key=? AND scope_key=? ORDER BY id").all(binding.workspaceKey, binding.scopeKey).map((row) => ({
+      id: row.id,
+      workspaceKey: row.workspace_key,
+      scopeKey: row.scope_key,
+      kind: row.kind,
+      body: JSON.parse(row.body)
+    })) : [];
+    const payload = stateBackupPayloadSchema.parse({
+      schemaVersion: HARNESS_STATE_BACKUP_SCHEMA_VERSION,
+      kind: "state-backup",
+      createdAt: new Date().toISOString(),
+      binding,
+      schemas: { operations: HARNESS_OPERATIONS_SCHEMA_VERSION, sessions: HARNESS_SESSION_SCHEMA_VERSION },
+      records: { runs, toolJournal: journal, idempotency, parents, memory, sessions, sessionRuns, ...workspaceCheckpoints.length ? { workspaceCheckpoints } : {}, ...budgetLedgers.length ? { budgetLedgers } : {} }
+    });
+    for (const record of payload.records.workspaceCheckpoints ?? []) {
+      if (record.kind === "restore" && record.body.stage !== "completed") {
+        throw new HarnessStateConflictError("State backup refuses an unfinished workspace restore operation.");
+      }
+    }
+    database.exec("COMMIT");
+    transactionStarted = false;
+    return payload;
+  } catch (error) {
+    if (transactionStarted)
+      database.exec("ROLLBACK");
+    throw error;
+  } finally {
+    database.close(false);
+  }
+};
+var createHarnessStateBackup = async (config) => {
+  const payload = await readPayload(config);
+  return stateBackupBundleSchema.parse({ ...payload, checksum: checksumPayload(payload) });
+};
+var createArchivedHarnessStateBackup = async (config, options = {}) => {
+  const workspace = await validateRecordedWorkspace(config.workspace, true);
+  const payload = await readPayload(config, workspace, options.accessLease);
+  return stateBackupBundleSchema.parse({ ...payload, checksum: checksumPayload(payload) });
+};
+var writePrivateBackup = async (target, contents) => {
+  const requested = path2.resolve(target);
+  const parent = path2.dirname(requested);
+  let parentHandle;
+  try {
+    parentHandle = await open(parent, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    if (!(await parentHandle.stat()).isDirectory()) {
+      throw new Error("Backup parent is not a directory.");
+    }
+  } catch (error) {
+    await parentHandle?.close();
+    throw new HarnessWorkspaceError(`Backup parent must be a real non-symlink directory: ${parent}.`, {
+      cause: error
+    });
+  }
+  const staged = path2.join(parent, `.zhivex-state-backup-${randomUUID()}.tmp`);
+  let handle;
+  let published = false;
+  let stagedExists = false;
+  try {
+    handle = await open(staged, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 384);
+    stagedExists = true;
+    let pending = [];
+    let pendingBytes = 0;
+    for (const chunk of contents) {
+      pending.push(chunk);
+      pendingBytes += Buffer.byteLength(chunk);
+      if (pendingBytes >= 64 * 1024) {
+        await handle.writeFile(pending.join(""), "utf8");
+        pending = [];
+        pendingBytes = 0;
+      }
+    }
+    if (pending.length)
+      await handle.writeFile(pending.join(""), "utf8");
+    await handle.sync();
+    await chmod(staged, 384);
+    await handle.close();
+    handle = undefined;
+    await link(staged, requested);
+    published = true;
+    await unlink(staged);
+    stagedExists = false;
+    await parentHandle.sync();
+  } catch (error) {
+    if (published)
+      await unlink(requested).catch(() => {
+        return;
+      });
+    throw error;
+  } finally {
+    await handle?.close();
+    if (stagedExists)
+      await unlink(staged).catch(() => {
+        return;
+      });
+    await parentHandle.close();
+  }
+};
+var exportHarnessStateBackup = async (config, target) => {
+  const bundle = await createHarnessStateBackup(config);
+  let bytes = 0;
+  for (const chunk of canonicalChunks(bundle)) {
+    bytes += Buffer.byteLength(chunk);
+    if (bytes > HARNESS_STATE_BACKUP_MAX_BYTES)
+      break;
+  }
+  await writePrivateBackup(target, bytes > HARNESS_STATE_BACKUP_MAX_BYTES ? segmentedChunks(bundle) : canonicalChunks(bundle));
+  return {
+    schemaVersion: HARNESS_STATE_BACKUP_SCHEMA_VERSION,
+    kind: "state-export",
+    path: path2.resolve(target),
+    checksum: bundle.checksum,
+    counts: Object.fromEntries(Object.entries(bundle.records).map(([name, rows]) => [name, rows?.length ?? 0]))
+  };
+};
+var readHarnessStateBackup = async (source) => {
+  let input;
+  try {
+    input = await readBackupTransport(path2.resolve(source), HARNESS_STATE_BACKUP_MAX_BYTES);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new HarnessStateConflictError("Harness state backup is not valid JSON.", { cause: error });
+    }
+    throw error;
+  }
+  return validateStateBackupBundle(input);
+};
+var validateStateBackupBundle = (input) => {
+  let bundle;
+  try {
+    bundle = stateBackupBundleSchema.parse(input);
+  } catch (error) {
+    throw new HarnessStateConflictError("Harness state backup schema is invalid or unsupported.", { cause: error });
+  }
+  const { checksum, ...payload } = bundle;
+  if (checksumPayload(payload) !== checksum) {
+    throw new HarnessStateConflictError("Harness state backup checksum does not match its payload.");
+  }
+  return bundle;
+};
+var validateBundleBinding = async (config, bundle) => {
+  const expected = await bindingForConfig(config);
+  if (canonicalJson(expected) !== canonicalJson(bundle.binding)) {
+    throw new HarnessStateConflictError("Harness state backup cannot be rebound to a different workspace or scope.");
+  }
+  const runKeys = new Set(bundle.records.runs.map((run) => run.key));
+  if (runKeys.size !== bundle.records.runs.length) {
+    throw new HarnessStateConflictError("Harness state backup contains duplicate run keys.");
+  }
+  const runIds = new Set;
+  for (const run of bundle.records.runs) {
+    const state = validatedRunState(run.state, `Run ${run.key}`);
+    assertTerminalState(state, `Run ${run.key}`);
+    if (!stateMatchesScope(config, state)) {
+      throw new HarnessStateConflictError(`Run ${run.key} is bound to another durable scope.`);
+    }
+    runIds.add(state.runId);
+    if (run.key !== `${expected.scopePrefix}${state.runId}`) {
+      throw new HarnessStateConflictError(`Run ${run.key} does not match its bound scope and runId.`);
+    }
+  }
+  const identities = coordinatorIds(bundle.records.runs);
+  const ledgerIdentities = new Set;
+  const ledgerKeys = new Set;
+  for (const ledger of bundle.records.budgetLedgers ?? []) {
+    const identity = validateBudgetLedger(config, ledger, identities);
+    if (ledgerIdentities.has(identity) || ledgerKeys.has(ledger.key) || runKeys.has(ledger.key))
+      throw new HarnessStateConflictError("Duplicate shared budget ledger.");
+    ledgerIdentities.add(identity);
+    ledgerKeys.add(ledger.key);
+  }
+  if (ledgerIdentities.size !== identities.size)
+    throw new HarnessStateConflictError("An imported run is missing its shared budget ledger.");
+  const journalKeys = new Set;
+  for (const entry of bundle.records.toolJournal) {
+    const journalKey = `${entry.runKey}\x00${entry.toolCallId}`;
+    if (journalKeys.has(journalKey) || !runKeys.has(entry.runKey) || !stateMatchesScope(config, entry.entry) || entry.entry.runId !== entry.runKey.slice(expected.scopePrefix.length)) {
+      throw new HarnessStateConflictError(`Tool journal ${entry.toolCallId} is not bound to an imported run.`);
+    }
+    journalKeys.add(journalKey);
+  }
+  const idempotencyKeys = new Set;
+  for (const entry of bundle.records.idempotency) {
+    if (idempotencyKeys.has(entry.key) || !runKeys.has(entry.runKey)) {
+      throw new HarnessStateConflictError("Idempotency record is duplicated or targets a missing run.");
+    }
+    idempotencyKeys.add(entry.key);
+    const state = bundle.records.runs.find((run) => run.key === entry.runKey).state;
+    if (typeof state.idempotencyKey !== "string" || entry.key !== `${expected.scopePrefix}${state.idempotencyKey}`) {
+      throw new HarnessStateConflictError("Idempotency record does not match its bound run state.");
+    }
+  }
+  const parentKeys = new Set;
+  for (const entry of bundle.records.parents) {
+    if (parentKeys.has(entry.runKey) || !runKeys.has(entry.runKey) || !runKeys.has(entry.parentRunKey)) {
+      throw new HarnessStateConflictError("Parent record targets a missing run.");
+    }
+    parentKeys.add(entry.runKey);
+  }
+  const memoryKeys = new Set;
+  for (const entry of bundle.records.memory) {
+    const memoryRunId = entry.key.startsWith(expected.scopePrefix) ? entry.key.slice(expected.scopePrefix.length) : "";
+    if (memoryKeys.has(entry.key) || !runIds.has(memoryRunId)) {
+      throw new HarnessStateConflictError(`Memory record ${entry.key} is not bound to an imported run.`);
+    }
+    memoryKeys.add(entry.key);
+  }
+  for (const session of bundle.records.sessions) {
+    if (session.workspaceKey !== expected.workspaceKey || session.scopeKey !== expected.scopeKey) {
+      throw new HarnessStateConflictError(`Session ${session.sessionId} is bound to another workspace or scope.`);
+    }
+  }
+  const sessionIds = new Set(bundle.records.sessions.map((session) => session.sessionId));
+  if (sessionIds.size !== bundle.records.sessions.length) {
+    throw new HarnessStateConflictError("Harness state backup contains duplicate session IDs.");
+  }
+  for (const session of bundle.records.sessions) {
+    if (session.parentSessionId && !sessionIds.has(session.parentSessionId)) {
+      throw new HarnessStateConflictError(`Session ${session.sessionId} targets a missing parent session.`);
+    }
+  }
+  const turnIds = new Set;
+  const sessionOrdinals = new Set;
+  const sessionRunIds = new Set;
+  for (const run of bundle.records.sessionRuns) {
+    const ordinalKey = `${run.sessionId}\x00${run.ordinal}`;
+    const sessionRunKey = `${run.sessionId}\x00${run.runId}`;
+    if (turnIds.has(run.turnId) || sessionOrdinals.has(ordinalKey) || sessionRunIds.has(sessionRunKey) || !sessionIds.has(run.sessionId) || !runIds.has(run.runId) || !terminalSessionStatuses.has(run.status)) {
+      throw new HarnessStateConflictError(`Session run ${run.runId} is active or targets a missing session.`);
+    }
+    turnIds.add(run.turnId);
+    sessionOrdinals.add(ordinalKey);
+    sessionRunIds.add(sessionRunKey);
+  }
+  const checkpointIds = new Set;
+  for (const record of bundle.records.workspaceCheckpoints ?? []) {
+    if (checkpointIds.has(record.id) || record.id !== record.body.id || record.workspaceKey !== expected.workspaceKey || record.scopeKey !== expected.scopeKey) {
+      throw new HarnessStateConflictError("Invalid checkpoint identity or workspace/scope binding.");
+    }
+    checkpointIds.add(record.id);
+    const checkpoint = record.kind === "checkpoint" ? record.body : record.body.checkpoint;
+    const turn = bundle.records.sessionRuns.find((run) => run.turnId === checkpoint.turnId && run.sessionId === checkpoint.sessionId);
+    if (!turn || !terminalSessionStatuses.has(turn.status))
+      throw new HarnessStateConflictError("Checkpoint targets a missing terminal turn.");
+    if (new Set(checkpoint.files.map((file) => file.path)).size !== checkpoint.files.length || checkpoint.files.some((file) => `sha256:${createHash("sha256").update(file.content).digest("hex")}` !== file.digest || Buffer.byteLength(file.content) > 65536)) {
+      throw new HarnessStateConflictError("Checkpoint content identity is invalid.");
+    }
+    if (record.kind === "restore") {
+      const operation = record.body;
+      if (operation.stage !== "completed")
+        throw new HarnessStateConflictError("State backup refuses an unfinished workspace restore operation.");
+      const fork = bundle.records.sessions.find((session) => session.sessionId === operation.forkSessionId);
+      if (!fork || fork.parentSessionId !== checkpoint.sessionId || fork.forkedFromTurnId !== checkpoint.turnId) {
+        throw new HarnessStateConflictError("Restore operation targets a missing conversation fork.");
+      }
+    }
+  }
+  for (const run of bundle.records.sessionRuns) {
+    if (run.sourceTurnId && !turnIds.has(run.sourceTurnId)) {
+      throw new HarnessStateConflictError(`Session run ${run.runId} targets a missing source turn.`);
+    }
+  }
+};
+var rowJson = (value) => canonicalJson(value);
+var setEquals = (left, right) => left.size === right.size && [...left].every((value) => right.has(value));
+var importHarnessStateBackup = async (config, bundle, options = {}) => {
+  bundle = validateStateBackupBundle(bundle);
+  await validateBundleBinding(config, bundle);
+  const databasePath = options.dryRun ? await locateExistingDatabase(config) : await prepareDatabase(config);
+  if (!databasePath) {
+    return {
+      schemaVersion: HARNESS_STATE_BACKUP_SCHEMA_VERSION,
+      kind: "state-import",
+      dryRun: true,
+      checksum: bundle.checksum,
+      inserted: {},
+      identical: 0
+    };
+  }
+  const database = new SqliteDatabase(databasePath, {
+    create: false,
+    strict: true,
+    ...options.dryRun ? { readonly: true } : {}
+  });
+  database.exec("PRAGMA busy_timeout = 5000");
+  database.exec("PRAGMA foreign_keys = ON");
+  database.exec(options.dryRun ? "BEGIN" : "BEGIN IMMEDIATE");
+  const availableTables = new Set(database.query("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name));
+  let writes = 0;
+  let identical = 0;
+  const inserted = {};
+  const checkFailure = () => {
+    if (options.failAfterWrites !== undefined && writes >= options.failAfterWrites) {
+      throw new Error("Injected state import failure.");
+    }
+  };
+  const insertOrCompare = (table, keyWhere, keyBindings, selectColumns, expected, insertSql, insertBindings) => {
+    if (!availableTables.has(table)) {
+      if (options.dryRun)
+        return;
+      throw new HarnessStateConflictError(`Required state table ${table} is unavailable.`);
+    }
+    const existing = database.query(`SELECT ${selectColumns} FROM ${table} WHERE ${keyWhere}`).get(...keyBindings);
+    if (existing) {
+      const actual = Object.values(existing).map((value) => typeof value === "string" && (value.startsWith("{") || value.startsWith("[")) ? rowJson(JSON.parse(value)) : value);
+      const normalizedExpected = expected.map((value) => typeof value === "string" && (value.startsWith("{") || value.startsWith("[")) ? rowJson(JSON.parse(value)) : value);
+      if (rowJson(actual) !== rowJson(normalizedExpected)) {
+        throw new HarnessStateConflictError(`Conflicting state already exists in ${table}.`);
+      }
+      identical += 1;
+      return;
+    }
+    if (options.dryRun)
+      return;
+    checkFailure();
+    database.query(insertSql).run(...insertBindings);
+    writes += 1;
+    inserted[table] = (inserted[table] ?? 0) + 1;
+  };
+  try {
+    const expectedKeys = {
+      runs: new Set([...bundle.records.runs, ...bundle.records.budgetLedgers ?? []].map((row) => row.key)),
+      toolJournal: new Set(bundle.records.toolJournal.map((row) => `${row.runKey}\x00${row.toolCallId}`)),
+      idempotency: new Set(bundle.records.idempotency.map((row) => row.key)),
+      parents: new Set(bundle.records.parents.map((row) => row.runKey)),
+      memory: new Set(bundle.records.memory.map((row) => row.key)),
+      sessions: new Set(bundle.records.sessions.map((row) => row.sessionId)),
+      sessionRuns: new Set(bundle.records.sessionRuns.map((row) => row.turnId)),
+      workspaceCheckpoints: new Set((bundle.records.workspaceCheckpoints ?? []).map((row) => row.id))
+    };
+    const expectedBudgetKeys = new Set((bundle.records.budgetLedgers ?? []).map((row) => row.key));
+    const destinationRunRows = availableTables.has("zhivex_agent_runs") ? database.query("SELECT run_id, state_json, updated_at_ms FROM zhivex_agent_runs ORDER BY run_id").all().filter((row) => expectedBudgetKeys.has(row.run_id) || stateMatchesScope(config, parseJsonRecord(row.state_json, `Run ${row.run_id}`))) : [];
+    const destinationRunKeys = new Set(destinationRunRows.map((row) => row.run_id));
+    const destinationSessionRows = availableTables.has("zhivex_cli_sessions") ? database.query("SELECT * FROM zhivex_cli_sessions ORDER BY session_id").all().filter((row) => row.workspace_key === bundle.binding.workspaceKey && row.scope_key === bundle.binding.scopeKey) : [];
+    const destinationSessionIds = new Set(destinationSessionRows.map((row) => row.session_id));
+    const destinationKeys = {
+      workspaceCheckpoints: new Set(availableTables.has("zhivex_workspace_checkpoints") ? database.query("SELECT * FROM zhivex_workspace_checkpoints WHERE workspace_key=? AND scope_key=?").all(bundle.binding.workspaceKey, bundle.binding.scopeKey).map((row) => row.id) : []),
+      runs: destinationRunKeys,
+      toolJournal: new Set(availableTables.has("zhivex_agent_runs_tool_journal") ? database.query("SELECT run_key, tool_call_id, entry_json, revision, updated_at_ms FROM zhivex_agent_runs_tool_journal").all().filter((row) => destinationRunKeys.has(row.run_key)).map((row) => `${row.run_key}\x00${row.tool_call_id}`) : []),
+      idempotency: new Set(availableTables.has("zhivex_agent_runs_idempotency") ? database.query("SELECT idempotency_key, run_id, updated_at_ms FROM zhivex_agent_runs_idempotency").all().filter((row) => destinationRunKeys.has(row.run_id)).map((row) => row.idempotency_key) : []),
+      parents: new Set(availableTables.has("zhivex_agent_runs_parents") ? database.query("SELECT run_id, parent_run_id, updated_at_ms FROM zhivex_agent_runs_parents").all().filter((row) => destinationRunKeys.has(row.run_id)).map((row) => row.run_id) : []),
+      memory: new Set(availableTables.has("zhivex_agent_memory") ? database.query("SELECT memory_key, messages_json, updated_at_ms FROM zhivex_agent_memory").all().filter((row) => destinationRunRows.some((run) => {
+        const state = JSON.parse(run.state_json);
+        return row.memory_key === `${bundle.binding.scopePrefix}${String(state.runId)}`;
+      })).map((row) => row.memory_key) : []),
+      sessions: destinationSessionIds,
+      sessionRuns: new Set(availableTables.has("zhivex_cli_session_runs") ? database.query("SELECT * FROM zhivex_cli_session_runs ORDER BY session_id, ordinal").all().filter((row) => destinationSessionIds.has(row.session_id)).map((row) => row.turn_id) : [])
+    };
+    if (availableTables.has("zhivex_agent_runs_leases")) {
+      const activeLease = database.query("SELECT run_key, expires_at_ms FROM zhivex_agent_runs_leases").all().some((row) => (destinationRunKeys.has(row.run_key) || expectedKeys.runs.has(row.run_key)) && row.expires_at_ms > Date.now());
+      if (activeLease) {
+        throw new HarnessStateConflictError("State import refuses a destination with active run leases.", {
+          retryable: true
+        });
+      }
+    }
+    const destinationHasState = Object.values(destinationKeys).some((keys) => keys.size > 0);
+    if (destinationHasState && Object.keys(expectedKeys).some((name) => !setEquals(destinationKeys[name], expectedKeys[name]))) {
+      throw new HarnessStateConflictError("State import requires an empty destination or an exactly identical prior import.");
+    }
+    for (const run of [...bundle.records.runs, ...bundle.records.budgetLedgers ?? []])
+      insertOrCompare("zhivex_agent_runs", "run_id = ?", [run.key], "state_json, updated_at_ms", [JSON.stringify(run.state), run.updatedAt], "INSERT INTO zhivex_agent_runs (run_id, state_json, updated_at_ms) VALUES (?, ?, ?)", [run.key, JSON.stringify(run.state), run.updatedAt]);
+    for (const entry of bundle.records.idempotency)
+      insertOrCompare("zhivex_agent_runs_idempotency", "idempotency_key = ?", [entry.key], "run_id, updated_at_ms", [entry.runKey, entry.updatedAt], "INSERT INTO zhivex_agent_runs_idempotency (idempotency_key, run_id, updated_at_ms) VALUES (?, ?, ?)", [entry.key, entry.runKey, entry.updatedAt]);
+    for (const entry of bundle.records.parents)
+      insertOrCompare("zhivex_agent_runs_parents", "run_id = ?", [entry.runKey], "parent_run_id, updated_at_ms", [entry.parentRunKey, entry.updatedAt], "INSERT INTO zhivex_agent_runs_parents (run_id, parent_run_id, updated_at_ms) VALUES (?, ?, ?)", [entry.runKey, entry.parentRunKey, entry.updatedAt]);
+    for (const entry of bundle.records.toolJournal)
+      insertOrCompare("zhivex_agent_runs_tool_journal", "run_key = ? AND tool_call_id = ?", [entry.runKey, entry.toolCallId], "entry_json, revision, updated_at_ms", [JSON.stringify(entry.entry), entry.revision, entry.updatedAt], "INSERT INTO zhivex_agent_runs_tool_journal (run_key, tool_call_id, entry_json, revision, updated_at_ms) VALUES (?, ?, ?, ?, ?)", [entry.runKey, entry.toolCallId, JSON.stringify(entry.entry), entry.revision, entry.updatedAt]);
+    for (const entry of bundle.records.memory)
+      insertOrCompare("zhivex_agent_memory", "memory_key = ?", [entry.key], "messages_json, updated_at_ms", [JSON.stringify(entry.messages), entry.updatedAt], "INSERT INTO zhivex_agent_memory (memory_key, messages_json, updated_at_ms) VALUES (?, ?, ?)", [entry.key, JSON.stringify(entry.messages), entry.updatedAt]);
+    for (const session of bundle.records.sessions)
+      insertOrCompare("zhivex_cli_sessions", "session_id = ?", [session.sessionId], "workspace_key, scope_key, title, parent_session_id, forked_from_turn_id, revision, activity_seq, created_at, updated_at, archived_at, deleted_at, metadata_bytes", [
+        session.workspaceKey,
+        session.scopeKey,
+        session.title,
+        session.parentSessionId,
+        session.forkedFromTurnId,
+        session.revision,
+        session.activitySequence,
+        session.createdAt,
+        session.updatedAt,
+        session.archivedAt,
+        session.deletedAt,
+        session.metadataBytes
+      ], "INSERT INTO zhivex_cli_sessions (session_id, workspace_key, scope_key, title, parent_session_id, forked_from_turn_id, revision, activity_seq, created_at, updated_at, archived_at, deleted_at, metadata_bytes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [
+        session.sessionId,
+        session.workspaceKey,
+        session.scopeKey,
+        session.title,
+        session.parentSessionId,
+        session.forkedFromTurnId,
+        session.revision,
+        session.activitySequence,
+        session.createdAt,
+        session.updatedAt,
+        session.archivedAt,
+        session.deletedAt,
+        session.metadataBytes
+      ]);
+    for (const run of bundle.records.sessionRuns)
+      insertOrCompare("zhivex_cli_session_runs", "turn_id = ?", [run.turnId], "source_turn_id, session_id, ordinal, run_id, provider, model, role, status, created_at, updated_at, completed_at, metadata_bytes", [
+        run.sourceTurnId,
+        run.sessionId,
+        run.ordinal,
+        run.runId,
+        run.provider,
+        run.model,
+        run.role,
+        run.status,
+        run.createdAt,
+        run.updatedAt,
+        run.completedAt,
+        run.metadataBytes
+      ], "INSERT INTO zhivex_cli_session_runs (turn_id, source_turn_id, session_id, ordinal, run_id, provider, model, role, status, created_at, updated_at, completed_at, metadata_bytes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [
+        run.turnId,
+        run.sourceTurnId,
+        run.sessionId,
+        run.ordinal,
+        run.runId,
+        run.provider,
+        run.model,
+        run.role,
+        run.status,
+        run.createdAt,
+        run.updatedAt,
+        run.completedAt,
+        run.metadataBytes
+      ]);
+    if ((bundle.records.workspaceCheckpoints?.length ?? 0) > 0 && !options.dryRun && !availableTables.has("zhivex_workspace_checkpoints")) {
+      database.exec(checkpointTableSql);
+      availableTables.add("zhivex_workspace_checkpoints");
+    }
+    for (const record of bundle.records.workspaceCheckpoints ?? [])
+      insertOrCompare("zhivex_workspace_checkpoints", "id=?", [record.id], "workspace_key, scope_key, kind, body", [record.workspaceKey, record.scopeKey, record.kind, JSON.stringify(record.body)], "INSERT INTO zhivex_workspace_checkpoints(id,workspace_key,scope_key,kind,body) VALUES(?,?,?,?,?)", [record.id, record.workspaceKey, record.scopeKey, record.kind, JSON.stringify(record.body)]);
+    if (options.dryRun)
+      database.exec("ROLLBACK");
+    else
+      database.exec("COMMIT");
+    return {
+      schemaVersion: HARNESS_STATE_BACKUP_SCHEMA_VERSION,
+      kind: "state-import",
+      dryRun: options.dryRun ?? false,
+      checksum: bundle.checksum,
+      inserted,
+      identical
+    };
+  } catch (error) {
+    database.exec("ROLLBACK");
+    throw error;
+  } finally {
+    database.close(false);
+  }
+};
+var importHarnessStateBackupFile = async (config, source, options = {}) => importHarnessStateBackup(config, await readHarnessStateBackup(source), options);
+var inspectHarnessState = async (config) => {
+  const payload = await readPayload(config);
+  return {
+    schemaVersion: HARNESS_STATE_BACKUP_SCHEMA_VERSION,
+    kind: "state-status",
+    compatible: true,
+    schemas: payload.schemas,
+    counts: Object.fromEntries(Object.entries(payload.records).map(([name, rows]) => [name, rows?.length ?? 0]))
+  };
+};
+
+export { validateRecordedWorkspace, HARNESS_STATE_BACKUP_SCHEMA_VERSION, HARNESS_STATE_BACKUP_MAX_BYTES, stateBackupBundleSchema, createHarnessStateBackup, createArchivedHarnessStateBackup, exportHarnessStateBackup, readHarnessStateBackup, importHarnessStateBackup, importHarnessStateBackupFile, inspectHarnessState };