harnery 0.45.1 → 0.46.0

package/dist/core/agents/state/process-handle.js

@@ -1,121 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { constants } from "node:os";
-// The helper owns the descriptor throughout observation and effect. The second
-// input line authorizes the effect; EOF releases the handle without signaling.
-export const LINUX_PROCESS_HANDLE_SCRIPT = `
-import json, os, pathlib, signal, sys
-result = {"sent": False, "verdict": "unknown"}
-fd = None
-try:
-    request = json.loads(sys.stdin.readline())
-    if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
-        raise RuntimeError("pidfd support unavailable")
-    fd = os.pidfd_open(request["pid"])
-    stat = pathlib.Path("/proc/%d/stat" % request["pid"]).read_text()
-    ticks = stat[stat.rfind(") ") + 2:].split()[19]
-    boot = pathlib.Path("/proc/sys/kernel/random/boot_id").read_text().strip().replace("-", "")[:8]
-    token = "l%s.%s" % (boot, ticks)
-    result["token"] = token
-    recorded = request.get("token")
-    result["verdict"] = "same" if token == recorded else "different"
-    if request["mode"] == "signal" and result["verdict"] == "same":
-        print(json.dumps({"phase": "verified"}), flush=True)
-        if sys.stdin.readline().strip() == "signal":
-            signal.pidfd_send_signal(fd, request["signal"])
-            result["sent"] = True
-except Exception:
-    pass
-finally:
-    if fd is not None:
-        os.close(fd)
-print(json.dumps(result), flush=True)
-`;
-export const WINDOWS_PROCESS_HANDLE_SCRIPT = `
-$ErrorActionPreference = 'Stop'
-$result = @{ sent = $false; verdict = 'unknown' }
-$handle = [IntPtr]::Zero
-try {
-  Add-Type -TypeDefinition @'
-using System;
-using System.Runtime.InteropServices;
-public static class HarneryProcessHandle {
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, uint processId);
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool GetProcessTimes(IntPtr handle, out long creation, out long exit, out long kernel, out long user);
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool TerminateProcess(IntPtr handle, uint exitCode);
-  [DllImport("kernel32.dll")] public static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
-  [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
-}
-'@
-  $request = [Console]::In.ReadLine() | ConvertFrom-Json
-  $access = [uint32]0x101000
-  if ($request.mode -eq 'signal') { $access = $access -bor 1 }
-  $handle = [HarneryProcessHandle]::OpenProcess($access, $false, [uint32]$request.pid)
-  if ($handle -eq [IntPtr]::Zero) { throw 'process handle unavailable' }
-  [long]$creation = 0; [long]$exitTime = 0; [long]$kernel = 0; [long]$userTime = 0
-  if (-not [HarneryProcessHandle]::GetProcessTimes($handle, [ref]$creation, [ref]$exitTime, [ref]$kernel, [ref]$userTime)) { throw 'process time unavailable' }
-  $token = 'w' + $creation.ToString([Globalization.CultureInfo]::InvariantCulture)
-  $result.token = $token
-  $result.verdict = if ($token -ceq $request.token) { 'same' } else { 'different' }
-  if ($request.mode -eq 'signal' -and $result.verdict -eq 'same') {
-    [Console]::Out.WriteLine('{"phase":"verified"}')
-    [Console]::Out.Flush()
-    if ([Console]::In.ReadLine() -eq 'signal' -and [HarneryProcessHandle]::WaitForSingleObject($handle, 0) -eq 258) {
-      $result.sent = [HarneryProcessHandle]::TerminateProcess($handle, 1)
-    }
-  }
-} catch {} finally {
-  if ($handle -ne [IntPtr]::Zero) { [void][HarneryProcessHandle]::CloseHandle($handle) }
-}
-$result | ConvertTo-Json -Compress
-`;
-function runHelper(request, platform, run) {
-    const unknown = { sent: false, verdict: "unknown" };
-    if (!Number.isInteger(request.pid) || request.pid <= 0)
-        return unknown;
-    if (platform !== "linux" && platform !== "win32")
-        return unknown;
-    try {
-        const command = platform === "linux" ? "python3" : "powershell.exe";
-        const args = platform === "linux"
-            ? ["-I", "-c", LINUX_PROCESS_HANDLE_SCRIPT]
-            : ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_PROCESS_HANDLE_SCRIPT];
-        const output = run(command, args, {
-            input: `${JSON.stringify(request)}\nsignal\n`,
-            encoding: "utf8",
-            timeout: 10_000,
-            maxBuffer: 64 * 1024,
-            windowsHide: true,
-        });
-        if (output.error || output.status !== 0)
-            return unknown;
-        const lines = String(output.stdout ?? "")
-            .trim()
-            .split(/\r?\n/);
-        const parsed = JSON.parse(lines.at(-1) ?? "");
-        if (typeof parsed.sent !== "boolean" ||
-            !["same", "different", "unknown"].includes(parsed.verdict) ||
-            (parsed.sent && parsed.verdict !== "same"))
-            return unknown;
-        return parsed;
-    }
-    catch {
-        return unknown;
-    }
-}
-/** Windows creation FILETIME, read from an OpenProcess handle. */
-export function windowsProcessStartToken(pid, run = spawnSync) {
-    const result = runHelper({ mode: "probe", pid }, "win32", run);
-    return typeof result.token === "string" && /^w\d+$/.test(result.token) ? result.token : null;
-}
-/** No numeric-PID signaling fallback is permitted when an exact handle fails. */
-export function signalProcessWithHandle(pid, recordedToken, signal, options = {}) {
-    const platform = options.platform ?? process.platform;
-    const number = typeof signal === "number" ? signal : constants.signals[signal];
-    if (!Number.isInteger(number) ||
-        number <= 0 ||
-        (platform === "linux" && !/^l[0-9a-f]{8}\.\d+$/.test(recordedToken)) ||
-        (platform === "win32" && (!/^w\d+$/.test(recordedToken) || ![9, 15].includes(number))))
-        return { sent: false, verdict: "unknown" };
-    const result = runHelper({ mode: "signal", pid, token: recordedToken, signal: number }, platform, options.run ?? spawnSync);
-    return { sent: result.sent, verdict: result.verdict };
-}

package/dist/core/workflow/recovery-audit.d.ts

@@ -1,30 +0,0 @@
-export interface WorkflowRecoveryAuthorization {
-    actor: string;
-    reason: string;
-}
-export interface WorkflowRecoveryIntent extends WorkflowRecoveryAuthorization {
-    schema_version: 1;
-    operation_id: string;
-    run_id: string;
-    action: "reclaim_unknown_liveness" | "unlock_resume";
-    target_sha256: string;
-    target: Record<string, unknown>;
-    recorded_at: string;
-    pid: number;
-    host: string;
-    outcome: "unknown";
-}
-export interface WorkflowRecoveryRecord {
-    intent: WorkflowRecoveryIntent;
-    outcome: "unknown" | "completed";
-}
-export declare function validateWorkflowRecoveryAuthorization(authorization: WorkflowRecoveryAuthorization): void;
-/** Canonical recovery ledger: immutable intent is durable before effects.
- * Completion cites that exact intent; absence always means unknown. */
-export declare function beginWorkflowRecovery(coordRoot: string, input: Omit<WorkflowRecoveryIntent, "schema_version" | "operation_id" | "recorded_at" | "pid" | "host" | "outcome">): {
-    intent: WorkflowRecoveryIntent;
-    assertCurrent(): void;
-    complete(): void;
-};
-export declare function readWorkflowRecoveryLedger(coordRoot: string, runId: string): WorkflowRecoveryRecord[];
-//# sourceMappingURL=recovery-audit.d.ts.map

package/dist/core/workflow/recovery-audit.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery-audit.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/recovery-audit.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAuB,SAAQ,6BAA6B;IAC3E,cAAc,EAAE,CAAC,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,0BAA0B,GAAG,eAAe,CAAC;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,OAAO,EAAE,SAAS,GAAG,WAAW,CAAC;CAClC;AAED,wBAAgB,qCAAqC,CACnD,aAAa,EAAE,6BAA6B,GAC3C,IAAI,CAmBN;AAED;uEACuE;AACvE,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,CACT,sBAAsB,EACtB,gBAAgB,GAAG,cAAc,GAAG,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAC/E,GACA;IAAE,MAAM,EAAE,sBAAsB,CAAC;IAAC,aAAa,IAAI,IAAI,CAAC;IAAC,QAAQ,IAAI,IAAI,CAAA;CAAE,CAmD7E;AAkBD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,sBAAsB,EAAE,CAyC1B"}

package/dist/core/workflow/recovery-audit.js

@@ -1,116 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
-import { hostname } from "node:os";
-import { dirname, join } from "node:path";
-import { stateDirMode } from "../storage/modes.js";
-import { assertWorkflowRunId } from "./approvals.js";
-import { fsyncParentDirectory, readJsonRecord, stableDigest, writeImmutableJson, } from "./durable-record.js";
-export function validateWorkflowRecoveryAuthorization(authorization) {
-    for (const [field, limit] of [
-        ["actor", 200],
-        ["reason", 2_000],
-    ]) {
-        const value = authorization[field];
-        if (typeof value !== "string" ||
-            !value.trim() ||
-            value.length > limit ||
-            Array.from(value).some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) {
-            throw new Error(`workflow recovery requires a nonempty ${field} of at most ${limit} characters without control characters`);
-        }
-    }
-}
-/** Canonical recovery ledger: immutable intent is durable before effects.
- * Completion cites that exact intent; absence always means unknown. */
-export function beginWorkflowRecovery(coordRoot, input) {
-    assertWorkflowRunId(input.run_id);
-    validateWorkflowRecoveryAuthorization(input);
-    if (!/^[a-f0-9]{64}$/.test(input.target_sha256))
-        throw new Error("workflow recovery requires an exact preview digest");
-    const intent = {
-        ...input,
-        schema_version: 1,
-        operation_id: `recovery-${randomUUID()}`,
-        recorded_at: new Date().toISOString(),
-        pid: process.pid,
-        host: hostname(),
-        outcome: "unknown",
-    };
-    const directory = join(coordRoot, ".harnery", "workflows", input.run_id, "recovery", intent.operation_id);
-    // Sync each newly published directory name too. Syncing only the intent's
-    // immediate parent cannot make a newly created ancestor durable.
-    const runDirectory = join(coordRoot, ".harnery", "workflows", input.run_id);
-    ensureDurableDirectory(runDirectory);
-    const ledgerDirectory = join(runDirectory, "recovery");
-    ensureDurableDirectory(ledgerDirectory);
-    fsyncParentDirectory(ledgerDirectory);
-    mkdirSync(directory, { mode: stateDirMode() });
-    fsyncParentDirectory(directory);
-    const intentPath = join(directory, "intent.json");
-    writeImmutableJson(intentPath, intent);
-    const assertCurrent = () => {
-        if (stableDigest(readJsonRecord(intentPath, "recovery intent")) !== stableDigest(intent))
-            throw new Error("workflow recovery audit authority changed");
-    };
-    return {
-        intent,
-        assertCurrent,
-        complete: () => {
-            assertCurrent();
-            writeImmutableJson(join(directory, "completion.json"), {
-                schema_version: 1,
-                operation_id: intent.operation_id,
-                intent_sha256: stableDigest(intent),
-                outcome: "completed",
-                recorded_at: new Date().toISOString(),
-            });
-        },
-    };
-}
-function ensureDurableDirectory(path) {
-    if (existsSync(path)) {
-        if (!lstatSync(path).isDirectory())
-            throw new Error("workflow recovery ledger is not a directory");
-        return;
-    }
-    ensureDurableDirectory(dirname(path));
-    try {
-        mkdirSync(path, { mode: stateDirMode() });
-    }
-    catch (error) {
-        if (error.code !== "EEXIST" || !lstatSync(path).isDirectory())
-            throw error;
-    }
-    fsyncParentDirectory(path);
-}
-export function readWorkflowRecoveryLedger(coordRoot, runId) {
-    assertWorkflowRunId(runId);
-    const directory = join(coordRoot, ".harnery", "workflows", runId, "recovery");
-    if (!existsSync(directory))
-        return [];
-    return readdirSync(directory)
-        .sort()
-        .map((entry) => {
-        if (!/^recovery-[a-f0-9-]{36}$/.test(entry))
-            throw new Error("invalid workflow recovery ledger entry");
-        const intent = readJsonRecord(join(directory, entry, "intent.json"), "recovery intent");
-        if (intent.schema_version !== 1 ||
-            intent.operation_id !== entry ||
-            intent.run_id !== runId ||
-            intent.outcome !== "unknown" ||
-            !["reclaim_unknown_liveness", "unlock_resume"].includes(intent.action) ||
-            !/^[a-f0-9]{64}$/.test(intent.target_sha256)) {
-            throw new Error("invalid workflow recovery intent authority");
-        }
-        validateWorkflowRecoveryAuthorization(intent);
-        const completionPath = join(directory, entry, "completion.json");
-        if (!existsSync(completionPath))
-            return { intent, outcome: "unknown" };
-        const completion = readJsonRecord(completionPath, "recovery completion");
-        if (completion.schema_version !== 1 ||
-            completion.operation_id !== entry ||
-            completion.intent_sha256 !== stableDigest(intent) ||
-            completion.outcome !== "completed")
-            throw new Error("invalid workflow recovery completion authority");
-        return { intent, outcome: "completed" };
-    });
-}

package/src/core/agents/state/process-handle.ts

@@ -1,165 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { constants } from "node:os";
-import type { ProcessGenerationVerdict } from "./proc-start.ts";
-
-export interface ProcessHandleSignalResult {
-  sent: boolean;
-  verdict: ProcessGenerationVerdict;
-}
-
-interface NativeHelperResult extends ProcessHandleSignalResult {
-  token?: string;
-}
-
-export type NativeProcessHelperRunner = (
-  command: string,
-  args: string[],
-  options: {
-    input: string;
-    encoding: "utf8";
-    timeout: number;
-    maxBuffer: number;
-    windowsHide: boolean;
-  },
-) => { status: number | null; stdout: string | Buffer | null; error?: Error };
-
-// The helper owns the descriptor throughout observation and effect. The second
-// input line authorizes the effect; EOF releases the handle without signaling.
-export const LINUX_PROCESS_HANDLE_SCRIPT = `
-import json, os, pathlib, signal, sys
-result = {"sent": False, "verdict": "unknown"}
-fd = None
-try:
-    request = json.loads(sys.stdin.readline())
-    if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
-        raise RuntimeError("pidfd support unavailable")
-    fd = os.pidfd_open(request["pid"])
-    stat = pathlib.Path("/proc/%d/stat" % request["pid"]).read_text()
-    ticks = stat[stat.rfind(") ") + 2:].split()[19]
-    boot = pathlib.Path("/proc/sys/kernel/random/boot_id").read_text().strip().replace("-", "")[:8]
-    token = "l%s.%s" % (boot, ticks)
-    result["token"] = token
-    recorded = request.get("token")
-    result["verdict"] = "same" if token == recorded else "different"
-    if request["mode"] == "signal" and result["verdict"] == "same":
-        print(json.dumps({"phase": "verified"}), flush=True)
-        if sys.stdin.readline().strip() == "signal":
-            signal.pidfd_send_signal(fd, request["signal"])
-            result["sent"] = True
-except Exception:
-    pass
-finally:
-    if fd is not None:
-        os.close(fd)
-print(json.dumps(result), flush=True)
-`;
-
-export const WINDOWS_PROCESS_HANDLE_SCRIPT = `
-$ErrorActionPreference = 'Stop'
-$result = @{ sent = $false; verdict = 'unknown' }
-$handle = [IntPtr]::Zero
-try {
-  Add-Type -TypeDefinition @'
-using System;
-using System.Runtime.InteropServices;
-public static class HarneryProcessHandle {
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, uint processId);
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool GetProcessTimes(IntPtr handle, out long creation, out long exit, out long kernel, out long user);
-  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool TerminateProcess(IntPtr handle, uint exitCode);
-  [DllImport("kernel32.dll")] public static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
-  [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
-}
-'@
-  $request = [Console]::In.ReadLine() | ConvertFrom-Json
-  $access = [uint32]0x101000
-  if ($request.mode -eq 'signal') { $access = $access -bor 1 }
-  $handle = [HarneryProcessHandle]::OpenProcess($access, $false, [uint32]$request.pid)
-  if ($handle -eq [IntPtr]::Zero) { throw 'process handle unavailable' }
-  [long]$creation = 0; [long]$exitTime = 0; [long]$kernel = 0; [long]$userTime = 0
-  if (-not [HarneryProcessHandle]::GetProcessTimes($handle, [ref]$creation, [ref]$exitTime, [ref]$kernel, [ref]$userTime)) { throw 'process time unavailable' }
-  $token = 'w' + $creation.ToString([Globalization.CultureInfo]::InvariantCulture)
-  $result.token = $token
-  $result.verdict = if ($token -ceq $request.token) { 'same' } else { 'different' }
-  if ($request.mode -eq 'signal' -and $result.verdict -eq 'same') {
-    [Console]::Out.WriteLine('{"phase":"verified"}')
-    [Console]::Out.Flush()
-    if ([Console]::In.ReadLine() -eq 'signal' -and [HarneryProcessHandle]::WaitForSingleObject($handle, 0) -eq 258) {
-      $result.sent = [HarneryProcessHandle]::TerminateProcess($handle, 1)
-    }
-  }
-} catch {} finally {
-  if ($handle -ne [IntPtr]::Zero) { [void][HarneryProcessHandle]::CloseHandle($handle) }
-}
-$result | ConvertTo-Json -Compress
-`;
-
-function runHelper(
-  request: { mode: "probe" | "signal"; pid: number; token?: string; signal?: number },
-  platform: NodeJS.Platform,
-  run: NativeProcessHelperRunner,
-): NativeHelperResult {
-  const unknown = { sent: false, verdict: "unknown" } as const;
-  if (!Number.isInteger(request.pid) || request.pid <= 0) return unknown;
-  if (platform !== "linux" && platform !== "win32") return unknown;
-  try {
-    const command = platform === "linux" ? "python3" : "powershell.exe";
-    const args =
-      platform === "linux"
-        ? ["-I", "-c", LINUX_PROCESS_HANDLE_SCRIPT]
-        : ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_PROCESS_HANDLE_SCRIPT];
-    const output = run(command, args, {
-      input: `${JSON.stringify(request)}\nsignal\n`,
-      encoding: "utf8",
-      timeout: 10_000,
-      maxBuffer: 64 * 1024,
-      windowsHide: true,
-    });
-    if (output.error || output.status !== 0) return unknown;
-    const lines = String(output.stdout ?? "")
-      .trim()
-      .split(/\r?\n/);
-    const parsed = JSON.parse(lines.at(-1) ?? "") as NativeHelperResult;
-    if (
-      typeof parsed.sent !== "boolean" ||
-      !["same", "different", "unknown"].includes(parsed.verdict) ||
-      (parsed.sent && parsed.verdict !== "same")
-    )
-      return unknown;
-    return parsed;
-  } catch {
-    return unknown;
-  }
-}
-
-/** Windows creation FILETIME, read from an OpenProcess handle. */
-export function windowsProcessStartToken(
-  pid: number,
-  run: NativeProcessHelperRunner = spawnSync,
-): string | null {
-  const result = runHelper({ mode: "probe", pid }, "win32", run);
-  return typeof result.token === "string" && /^w\d+$/.test(result.token) ? result.token : null;
-}
-
-/** No numeric-PID signaling fallback is permitted when an exact handle fails. */
-export function signalProcessWithHandle(
-  pid: number,
-  recordedToken: string,
-  signal: NodeJS.Signals | number,
-  options: { platform?: NodeJS.Platform; run?: NativeProcessHelperRunner } = {},
-): ProcessHandleSignalResult {
-  const platform = options.platform ?? process.platform;
-  const number = typeof signal === "number" ? signal : constants.signals[signal];
-  if (
-    !Number.isInteger(number) ||
-    number <= 0 ||
-    (platform === "linux" && !/^l[0-9a-f]{8}\.\d+$/.test(recordedToken)) ||
-    (platform === "win32" && (!/^w\d+$/.test(recordedToken) || ![9, 15].includes(number)))
-  )
-    return { sent: false, verdict: "unknown" };
-  const result = runHelper(
-    { mode: "signal", pid, token: recordedToken, signal: number },
-    platform,
-    options.run ?? spawnSync,
-  );
-  return { sent: result.sent, verdict: result.verdict };
-}

package/src/core/workflow/recovery-audit.ts

@@ -1,181 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
-import { hostname } from "node:os";
-import { dirname, join } from "node:path";
-import { stateDirMode } from "../storage/modes.ts";
-import { assertWorkflowRunId } from "./approvals.ts";
-import {
-  fsyncParentDirectory,
-  readJsonRecord,
-  stableDigest,
-  writeImmutableJson,
-} from "./durable-record.ts";
-
-export interface WorkflowRecoveryAuthorization {
-  actor: string;
-  reason: string;
-}
-
-export interface WorkflowRecoveryIntent extends WorkflowRecoveryAuthorization {
-  schema_version: 1;
-  operation_id: string;
-  run_id: string;
-  action: "reclaim_unknown_liveness" | "unlock_resume";
-  target_sha256: string;
-  target: Record<string, unknown>;
-  recorded_at: string;
-  pid: number;
-  host: string;
-  outcome: "unknown";
-}
-
-export interface WorkflowRecoveryRecord {
-  intent: WorkflowRecoveryIntent;
-  outcome: "unknown" | "completed";
-}
-
-export function validateWorkflowRecoveryAuthorization(
-  authorization: WorkflowRecoveryAuthorization,
-): void {
-  for (const [field, limit] of [
-    ["actor", 200],
-    ["reason", 2_000],
-  ] as const) {
-    const value = authorization[field];
-    if (
-      typeof value !== "string" ||
-      !value.trim() ||
-      value.length > limit ||
-      Array.from(value).some(
-        (character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
-      )
-    ) {
-      throw new Error(
-        `workflow recovery requires a nonempty ${field} of at most ${limit} characters without control characters`,
-      );
-    }
-  }
-}
-
-/** Canonical recovery ledger: immutable intent is durable before effects.
- * Completion cites that exact intent; absence always means unknown. */
-export function beginWorkflowRecovery(
-  coordRoot: string,
-  input: Omit<
-    WorkflowRecoveryIntent,
-    "schema_version" | "operation_id" | "recorded_at" | "pid" | "host" | "outcome"
-  >,
-): { intent: WorkflowRecoveryIntent; assertCurrent(): void; complete(): void } {
-  assertWorkflowRunId(input.run_id);
-  validateWorkflowRecoveryAuthorization(input);
-  if (!/^[a-f0-9]{64}$/.test(input.target_sha256))
-    throw new Error("workflow recovery requires an exact preview digest");
-  const intent: WorkflowRecoveryIntent = {
-    ...input,
-    schema_version: 1,
-    operation_id: `recovery-${randomUUID()}`,
-    recorded_at: new Date().toISOString(),
-    pid: process.pid,
-    host: hostname(),
-    outcome: "unknown",
-  };
-  const directory = join(
-    coordRoot,
-    ".harnery",
-    "workflows",
-    input.run_id,
-    "recovery",
-    intent.operation_id,
-  );
-  // Sync each newly published directory name too. Syncing only the intent's
-  // immediate parent cannot make a newly created ancestor durable.
-  const runDirectory = join(coordRoot, ".harnery", "workflows", input.run_id);
-  ensureDurableDirectory(runDirectory);
-  const ledgerDirectory = join(runDirectory, "recovery");
-  ensureDurableDirectory(ledgerDirectory);
-  fsyncParentDirectory(ledgerDirectory);
-  mkdirSync(directory, { mode: stateDirMode() });
-  fsyncParentDirectory(directory);
-  const intentPath = join(directory, "intent.json");
-  writeImmutableJson(intentPath, intent);
-  const assertCurrent = () => {
-    if (stableDigest(readJsonRecord(intentPath, "recovery intent")) !== stableDigest(intent))
-      throw new Error("workflow recovery audit authority changed");
-  };
-  return {
-    intent,
-    assertCurrent,
-    complete: () => {
-      assertCurrent();
-      writeImmutableJson(join(directory, "completion.json"), {
-        schema_version: 1,
-        operation_id: intent.operation_id,
-        intent_sha256: stableDigest(intent),
-        outcome: "completed",
-        recorded_at: new Date().toISOString(),
-      });
-    },
-  };
-}
-
-function ensureDurableDirectory(path: string): void {
-  if (existsSync(path)) {
-    if (!lstatSync(path).isDirectory())
-      throw new Error("workflow recovery ledger is not a directory");
-    return;
-  }
-  ensureDurableDirectory(dirname(path));
-  try {
-    mkdirSync(path, { mode: stateDirMode() });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !lstatSync(path).isDirectory())
-      throw error;
-  }
-  fsyncParentDirectory(path);
-}
-
-export function readWorkflowRecoveryLedger(
-  coordRoot: string,
-  runId: string,
-): WorkflowRecoveryRecord[] {
-  assertWorkflowRunId(runId);
-  const directory = join(coordRoot, ".harnery", "workflows", runId, "recovery");
-  if (!existsSync(directory)) return [];
-  return readdirSync(directory)
-    .sort()
-    .map((entry) => {
-      if (!/^recovery-[a-f0-9-]{36}$/.test(entry))
-        throw new Error("invalid workflow recovery ledger entry");
-      const intent = readJsonRecord<WorkflowRecoveryIntent>(
-        join(directory, entry, "intent.json"),
-        "recovery intent",
-      );
-      if (
-        intent.schema_version !== 1 ||
-        intent.operation_id !== entry ||
-        intent.run_id !== runId ||
-        intent.outcome !== "unknown" ||
-        !["reclaim_unknown_liveness", "unlock_resume"].includes(intent.action) ||
-        !/^[a-f0-9]{64}$/.test(intent.target_sha256)
-      ) {
-        throw new Error("invalid workflow recovery intent authority");
-      }
-      validateWorkflowRecoveryAuthorization(intent);
-      const completionPath = join(directory, entry, "completion.json");
-      if (!existsSync(completionPath)) return { intent, outcome: "unknown" };
-      const completion = readJsonRecord<{
-        schema_version: number;
-        operation_id: string;
-        intent_sha256: string;
-        outcome: string;
-      }>(completionPath, "recovery completion");
-      if (
-        completion.schema_version !== 1 ||
-        completion.operation_id !== entry ||
-        completion.intent_sha256 !== stableDigest(intent) ||
-        completion.outcome !== "completed"
-      )
-        throw new Error("invalid workflow recovery completion authority");
-      return { intent, outcome: "completed" };
-    });
-}