harnery 0.45.0 → 0.45.1

package/src/commands/turn-rollback.ts

@@ -1,111 +0,0 @@
-import type { Command } from "commander";
-import type { EmitContext, HarneryProgramContext } from "../commander.ts";
-import { monorepoRoot } from "../core/agents/index.ts";
-import {
-  applyTurnRollback,
-  beginTurnRollback,
-  inspectTurnRollback,
-  prepareTurnRollback,
-  sealTurnRollback,
-  type TurnRollbackPlan,
-} from "../core/turn-rollback/index.ts";
-import { readJsonRecord } from "../core/workflow/durable-record.ts";
-import { readWorkspaceBinding } from "../core/workflow/workspaces/state.ts";
-
-/** Explicit turn boundaries; hooks cannot infer provider ownership or path scope. */
-export function registerTurnRollbackCommand(
-  program: Command,
-  emit: EmitContext,
-  context?: HarneryProgramContext,
-): void {
-  const command = program
-    .command("turn-rollback")
-    .description("Capture and review exact-path content rollback in an owned workspace");
-  type Options = {
-    binding: string;
-    turn?: string;
-    generation?: string;
-    path?: string[];
-    yes?: boolean;
-    actor?: string;
-    reason?: string;
-    plan?: string;
-  };
-  const run =
-    (operation: (coordRoot: string, options: Options) => unknown | Promise<unknown>) =>
-    async (options: Options) => {
-      try {
-        const coordRoot = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot();
-        if (!coordRoot) throw new Error("project coordination root is unavailable");
-        emit.config({ format: "json" });
-        const result = await operation(coordRoot, options);
-        emit.data(result);
-        if (
-          result &&
-          typeof result === "object" &&
-          "status" in result &&
-          result.status === "unknown"
-        )
-          emit.setExitCode(1);
-      } catch (error) {
-        emit.error({ code: "turn_rollback_refused", message: String(error) });
-        emit.setExitCode(1);
-      }
-    };
-  const binding = (root: string, options: Options) => {
-    const value = readWorkspaceBinding(root, "local-git-worktree", options.binding);
-    if (!value) throw new Error("immutable workspace binding was not found");
-    return value;
-  };
-  command
-    .command("begin")
-    .description("Capture exact literal paths before a turn")
-    .requiredOption("--binding <id>", "Owned workspace binding ID")
-    .requiredOption("--turn <id>", "Caller turn identity")
-    .requiredOption("--generation <number>", "Increasing turn generation")
-    .requiredOption("--path <file...>", "Exact relative file paths, including planned new files")
-    .action(
-      run((root, options) =>
-        beginTurnRollback(root, {
-          binding: binding(root, options),
-          turn: { turn_id: options.turn!, generation: Number(options.generation) },
-          paths: options.path!,
-        }),
-      ),
-    );
-  for (const operation of ["seal", "prepare", "show"] as const) {
-    command
-      .command(`${operation} <capture-id>`)
-      .description(`${operation} an exact turn capture`)
-      .requiredOption("--binding <id>", "Owned workspace binding ID")
-      .action((id: string, options: Options) =>
-        run((root, opts) => {
-          const input = { binding: binding(root, opts), capture_id: id };
-          return operation === "seal"
-            ? sealTurnRollback(root, input)
-            : operation === "prepare"
-              ? prepareTurnRollback(root, input)
-              : inspectTurnRollback(root, input);
-        })(options),
-      );
-  }
-  command
-    .command("apply")
-    .description("Preview a saved proposal, or apply it after exact confirmation")
-    .requiredOption("--binding <id>", "Owned workspace binding ID")
-    .requiredOption("--plan <file>", "Saved JSON proposal returned by prepare")
-    .option("--yes", "Apply this exact proposal; preview is the default")
-    .option("--actor <name>", "Who authorized the restore")
-    .option("--reason <text>", "Why this turn is being restored")
-    .action(
-      run((root, options) =>
-        applyTurnRollback(root, {
-          binding: binding(root, options),
-          plan: readJsonRecord<TurnRollbackPlan>(options.plan!, "rollback proposal"),
-          yes: options.yes,
-          actor: options.actor,
-          reason: options.reason,
-        }),
-      ),
-    );
-}

package/src/core/agents/state/unchanged-file.ts

@@ -1,456 +0,0 @@
-import {
-  closeSync,
-  constants,
-  fstatSync,
-  fsyncSync,
-  linkSync,
-  lstatSync,
-  mkdtempSync,
-  openSync,
-  readdirSync,
-  readFileSync,
-  readlinkSync,
-  realpathSync,
-  renameSync,
-  rmdirSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { hostname } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-import { stateFileMode } from "../../storage/modes.ts";
-
-export interface FileRevision {
-  readonly bytes: Buffer;
-  readonly dev: bigint;
-  readonly ino: bigint;
-  readonly size: bigint;
-  readonly mtimeNs: bigint;
-  readonly ctimeNs: bigint;
-}
-
-export type DeleteFileResult =
-  | { state: "deleted" | "changed" | "missing" | "rejected" }
-  | { state: "recovery-required"; recoveryPath: string; error?: string }
-  | { state: "error"; recoveryPath?: string; error: string };
-
-export interface FileRecoveryResult {
-  state: "restored" | "retained" | "error";
-  recoveryPath: string;
-  sourcePath?: string;
-  error?: string;
-}
-
-const PRIVATE_PREFIX = ".harnery-delete-";
-const MANIFEST = "intent.json";
-const PIN = "pinned";
-
-interface PinIntent {
-  version: 1;
-  source: string;
-  ownerPid: number;
-  ownerHost: string;
-  ownerPlatform: string;
-  ownerProcessNamespace: string;
-  state: "active" | "retained";
-}
-
-interface PrivateDirectoryRevision {
-  path: string;
-  dev: bigint;
-  ino: bigint;
-  birthtimeNs: bigint;
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function errorCode(error: unknown): string | undefined {
-  return (error as NodeJS.ErrnoException | undefined)?.code;
-}
-
-function sameRevision(a: FileRevision, b: FileRevision, includeCtime = true): boolean {
-  return (
-    a.dev === b.dev &&
-    a.ino === b.ino &&
-    a.size === b.size &&
-    a.mtimeNs === b.mtimeNs &&
-    (!includeCtime || a.ctimeNs === b.ctimeNs) &&
-    a.bytes.equals(b.bytes)
-  );
-}
-
-function sameCanonicalPath(a: string, b: string): boolean {
-  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
-}
-
-function processNamespace(): string {
-  if (process.platform === "linux") {
-    try {
-      const namespace = readlinkSync("/proc/self/ns/pid");
-      return /^pid:\[\d+\]$/.test(namespace) ? namespace : "unknown";
-    } catch {
-      return "unknown";
-    }
-  }
-  return process.platform === "win32" || process.platform === "darwin" ? "host" : "unknown";
-}
-
-/** Refuse symlink parents and protocol-private paths rather than following them. */
-function safePath(filePath: string): string | null {
-  const path = resolve(filePath);
-  if (basename(path).startsWith(PRIVATE_PREFIX)) return null;
-  try {
-    if (!sameCanonicalPath(realpathSync(dirname(path)), dirname(path))) return null;
-    return path;
-  } catch {
-    return null;
-  }
-}
-
-/** A stable read of one regular file, including its exact bytes and revision. */
-export function captureFileRevision(filePath: string): FileRevision | null {
-  const path = safePath(filePath);
-  if (!path) return null;
-  let fd: number | undefined;
-  try {
-    const namedBefore = lstatSync(path, { bigint: true });
-    if (!namedBefore.isFile()) return null;
-    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    const before = fstatSync(fd, { bigint: true });
-    const bytes = readFileSync(fd);
-    const after = fstatSync(fd, { bigint: true });
-    const namedAfter = lstatSync(path, { bigint: true });
-    const snapshot: FileRevision = { ...before, bytes };
-    if (
-      !after.isFile() ||
-      !namedAfter.isFile() ||
-      before.size !== BigInt(bytes.length) ||
-      !sameRevision(snapshot, { ...after, bytes }) ||
-      !sameRevision(snapshot, { ...namedBefore, bytes }) ||
-      !sameRevision(snapshot, { ...namedAfter, bytes })
-    ) {
-      return null;
-    }
-    return {
-      bytes,
-      dev: before.dev,
-      ino: before.ino,
-      size: before.size,
-      mtimeNs: before.mtimeNs,
-      ctimeNs: before.ctimeNs,
-    };
-  } catch {
-    return null;
-  } finally {
-    if (fd !== undefined) closeSync(fd);
-  }
-}
-
-export function fileRevisionMatches(filePath: string, expected: FileRevision): boolean {
-  const actual = captureFileRevision(filePath);
-  return actual !== null && sameRevision(actual, expected);
-}
-
-function capturePrivateDirectory(path: string): PrivateDirectoryRevision | null {
-  try {
-    const stat = lstatSync(path, { bigint: true });
-    // Windows mode bits do not describe its ACL. The caller-owned parent's
-    // inherited ACL defines authorized principals there; random private names
-    // separate these operations from cooperating publishers on every platform.
-    if (
-      !/^\.harnery-delete-[A-Za-z0-9]{6}$/.test(basename(path)) ||
-      !stat.isDirectory() ||
-      (process.platform !== "win32" && (stat.mode & 0o077n) !== 0n) ||
-      !sameCanonicalPath(realpathSync(path), path)
-    ) {
-      return null;
-    }
-    return { path, dev: stat.dev, ino: stat.ino, birthtimeNs: stat.birthtimeNs };
-  } catch {
-    return null;
-  }
-}
-
-function privateDirectoryMatches(expected: PrivateDirectoryRevision): boolean {
-  const actual = capturePrivateDirectory(expected.path);
-  return (
-    actual !== null &&
-    actual.dev === expected.dev &&
-    actual.ino === expected.ino &&
-    actual.birthtimeNs === expected.birthtimeNs
-  );
-}
-
-function writeIntent(
-  directory: PrivateDirectoryRevision,
-  intent: PinIntent,
-  create: boolean,
-): void {
-  if (!privateDirectoryMatches(directory)) throw new Error("unsafe_file_deletion_directory");
-  const target = join(directory.path, create ? MANIFEST : "intent.next");
-  const fd = openSync(
-    target,
-    constants.O_WRONLY | constants.O_NOFOLLOW | constants.O_CREAT | constants.O_EXCL,
-    stateFileMode(),
-  );
-  try {
-    writeFileSync(fd, JSON.stringify(intent));
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-  if (!create) renameSync(target, join(directory.path, MANIFEST));
-}
-
-function removeEmptyPrivateDirectory(directory: PrivateDirectoryRevision): void {
-  if (!privateDirectoryMatches(directory)) throw new Error("unsafe_file_deletion_directory");
-  unlinkSync(join(directory.path, MANIFEST));
-  rmdirSync(directory.path);
-}
-
-function present(path: string): boolean {
-  try {
-    lstatSync(path);
-    return true;
-  } catch (error) {
-    if (errorCode(error) === "ENOENT") return false;
-    throw error;
-  }
-}
-
-/**
- * Restore by a no-clobber hard link. A newer publication always wins its name;
- * an unresolved pin stays available as evidence and for restart recovery.
- */
-function restore(directory: PrivateDirectoryRevision, source: string): FileRecoveryResult {
-  const pin = join(directory.path, PIN);
-  const result = { recoveryPath: pin, sourcePath: source };
-  try {
-    if (!privateDirectoryMatches(directory) || !safePath(source)) {
-      return { ...result, state: "retained", error: "unsafe_file_deletion_path" };
-    }
-    const pinned = captureFileRevision(pin);
-    if (!pinned) return { ...result, state: "retained", error: "unsafe_file_deletion_pin" };
-    try {
-      linkSync(pin, source);
-    } catch (error) {
-      // A previous recovery may have linked successfully before it was killed.
-      const current = captureFileRevision(source);
-      if (errorCode(error) !== "EEXIST" || !current || !sameRevision(current, pinned)) {
-        return { ...result, state: "retained", error: errorMessage(error) };
-      }
-    }
-    if (!privateDirectoryMatches(directory)) {
-      return { ...result, state: "retained", error: "unsafe_file_deletion_directory" };
-    }
-    unlinkSync(pin);
-    removeEmptyPrivateDirectory(directory);
-    return { ...result, state: "restored" };
-  } catch (error) {
-    return { ...result, state: "error", error: errorMessage(error) };
-  }
-}
-
-/**
- * Writers must publish by atomic rename, never by an open descriptor to the old
- * inode. The private directory is outside their publication namespace. Moving
- * the row gives deletion custody over that inode without owning its live name.
- * The caller owns the state parent and keeps its topology stable. Its platform
- * permissions define which principals can modify it; this protocol does not
- * exclude principals already authorized to change that parent.
- */
-export function deleteFileIfUnchanged(
-  filePath: string,
-  expected: FileRevision,
-  validate: (pinned: FileRevision) => boolean,
-): DeleteFileResult {
-  const path = safePath(filePath);
-  if (
-    !path ||
-    path.split(/[\\/]/).some((part) => part.startsWith(PRIVATE_PREFIX)) ||
-    typeof validate !== "function"
-  ) {
-    return { state: "rejected" };
-  }
-  const observed = { ...expected, bytes: Buffer.from(expected.bytes) };
-  const before = captureFileRevision(path);
-  if (!before) {
-    try {
-      return { state: present(path) ? "rejected" : "missing" };
-    } catch (error) {
-      return { state: "error", error: errorMessage(error) };
-    }
-  }
-  if (!sameRevision(before, observed)) return { state: "changed" };
-
-  let directory: PrivateDirectoryRevision | undefined;
-  let moved = false;
-  let intent: PinIntent | undefined;
-  const retain = (state: "changed" | "rejected" | "error", error?: unknown): DeleteFileResult => {
-    if (!directory || !intent) return { state: "error", error: errorMessage(error) };
-    try {
-      writeIntent(directory, { ...intent, state: "retained" }, false);
-    } catch {
-      // The still-active manifest remains recoverable when its process exits.
-    }
-    const recovered = restore(directory, path);
-    if (recovered.state !== "restored") {
-      return {
-        state: "recovery-required",
-        recoveryPath: recovered.recoveryPath,
-        error: error === undefined ? recovered.error : errorMessage(error),
-      };
-    }
-    return state === "error" ? { state, error: errorMessage(error) } : { state };
-  };
-  try {
-    const privatePath = mkdtempSync(join(dirname(path), PRIVATE_PREFIX));
-    directory = capturePrivateDirectory(privatePath) ?? undefined;
-    if (!directory) throw new Error("unsafe_file_deletion_directory");
-    intent = {
-      version: 1,
-      source: basename(path),
-      ownerPid: process.pid,
-      ownerHost: hostname(),
-      ownerPlatform: process.platform,
-      ownerProcessNamespace: processNamespace(),
-      state: "active",
-    };
-    writeIntent(directory, intent, true);
-    const pin = join(directory.path, PIN);
-    renameSync(path, pin);
-    moved = true;
-    const pinned = captureFileRevision(pin);
-    // rename may update ctime; the pre-move check included the observed ctime.
-    if (!pinned || !sameRevision(pinned, observed, false)) return retain("changed");
-    if (!validate({ ...pinned, bytes: Buffer.from(pinned.bytes) })) return retain("rejected");
-    if (!privateDirectoryMatches(directory) || !fileRevisionMatches(pin, pinned) || present(path)) {
-      return retain("changed");
-    }
-    unlinkSync(pin);
-    moved = false;
-    removeEmptyPrivateDirectory(directory);
-    // A publication at the unlink boundary belongs to the writer, even though
-    // the obsolete private inode was successfully removed.
-    return { state: present(path) ? "changed" : "deleted" };
-  } catch (error) {
-    if (moved) return retain("error", error);
-    if (directory && privateDirectoryMatches(directory)) {
-      try {
-        removeEmptyPrivateDirectory(directory);
-      } catch {
-        // Keep any unknown private contents rather than remove them recursively.
-      }
-    }
-    return errorCode(error) === "ENOENT"
-      ? { state: "missing" }
-      : { state: "error", error: errorMessage(error) };
-  }
-}
-
-/**
- * Recover same-host/platform/PID-namespace pins after process termination. File fsync
- * protects manifest contents; directory entries are not fsynced, so this does
- * not promise recovery after an OS crash or power loss.
- */
-export function recoverInterruptedFileDeletions(
-  directoryPath: string,
-  validate: (sourcePath: string) => boolean,
-): FileRecoveryResult[] {
-  const directory = resolve(directoryPath);
-  if (typeof validate !== "function") return [];
-  try {
-    if (!sameCanonicalPath(realpathSync(directory), directory)) return [];
-    const results: FileRecoveryResult[] = [];
-    for (const entry of readdirSync(directory).sort()) {
-      const privatePath = join(directory, entry);
-      const privateRevision = capturePrivateDirectory(privatePath);
-      if (!privateRevision) continue;
-      const unknownPin = (): FileRecoveryResult => ({
-        state: "error",
-        recoveryPath: join(privatePath, PIN),
-        error: "file_deletion_manifest_invalid",
-      });
-      const manifest = captureFileRevision(join(privatePath, MANIFEST));
-      if (!manifest) {
-        if (present(join(privatePath, PIN))) results.push(unknownPin());
-        continue;
-      }
-      let intent: PinIntent;
-      try {
-        intent = JSON.parse(manifest.bytes.toString("utf8"));
-      } catch {
-        if (present(join(privatePath, PIN))) results.push(unknownPin());
-        continue;
-      }
-      if (
-        intent?.version !== 1 ||
-        typeof intent.source !== "string" ||
-        intent.source.length === 0 ||
-        intent.source !== basename(intent.source) ||
-        intent.source === "." ||
-        intent.source === ".." ||
-        intent.source.startsWith(PRIVATE_PREFIX) ||
-        !Number.isSafeInteger(intent.ownerPid) ||
-        intent.ownerPid <= 0 ||
-        (intent.state !== "active" && intent.state !== "retained")
-      ) {
-        if (present(join(privatePath, PIN))) results.push(unknownPin());
-        continue;
-      }
-      const source = join(directory, intent.source);
-      const retained: FileRecoveryResult = {
-        state: "retained",
-        recoveryPath: join(privatePath, PIN),
-        sourcePath: source,
-      };
-      if (
-        typeof intent.ownerHost !== "string" ||
-        !intent.ownerHost ||
-        typeof intent.ownerPlatform !== "string" ||
-        !intent.ownerPlatform ||
-        typeof intent.ownerProcessNamespace !== "string" ||
-        !intent.ownerProcessNamespace ||
-        intent.ownerProcessNamespace === "unknown" ||
-        processNamespace() === "unknown"
-      ) {
-        results.push({ ...retained, error: "file_deletion_owner_unknown" });
-        continue;
-      }
-      if (
-        intent.ownerHost !== hostname() ||
-        intent.ownerPlatform !== process.platform ||
-        intent.ownerProcessNamespace !== processNamespace()
-      ) {
-        results.push({ ...retained, error: "file_deletion_owner_foreign" });
-        continue;
-      }
-      if (intent.state === "active") {
-        try {
-          process.kill(intent.ownerPid, 0);
-          results.push({ ...retained, error: "file_deletion_owner_alive" });
-          continue;
-        } catch (error) {
-          if (errorCode(error) !== "ESRCH") {
-            results.push({ ...retained, error: "file_deletion_owner_unknown" });
-            continue;
-          }
-        }
-      }
-      if (!validate(source)) {
-        results.push({ ...retained, error: "file_deletion_recovery_rejected" });
-        continue;
-      }
-      if (!present(join(privatePath, PIN))) {
-        removeEmptyPrivateDirectory(privateRevision);
-        continue;
-      }
-      results.push(restore(privateRevision, source));
-    }
-    return results;
-  } catch (error) {
-    return [{ state: "error", recoveryPath: directory, error: errorMessage(error) }];
-  }
-}

package/src/core/events/v3/generation-custody.ts

@@ -1,59 +0,0 @@
-import { createHash } from "node:crypto";
-import { hostname } from "node:os";
-import { join, resolve } from "node:path";
-import { acquireNoClobberLease } from "../../workflow/workspaces/leases.ts";
-import { readHookProducerStateByInstanceV3 } from "./producers/recorder.ts";
-
-const held = new Set<string>();
-
-/** Serialize synchronous authority work with generation changes for these instances only. */
-export function withGenerationCustodyV3<T>(
-  coordRoot: string,
-  instanceIds: readonly string[],
-  operation: () => T,
-): T {
-  const ids = [...new Set(instanceIds)].sort();
-  for (const id of ids) {
-    if (!/^inst_[a-zA-Z0-9._-]{1,128}$/.test(id)) {
-      throw new Error("generation custody instance is invalid");
-    }
-  }
-  const enter = (index: number): T => {
-    const id = ids[index];
-    if (id === undefined) return operation();
-    const key = `${resolve(coordRoot)}\0${id}`;
-    if (held.has(key)) return enter(index + 1);
-    const authority = createHash("sha256").update(key).digest("hex");
-    const lease = acquireNoClobberLease({
-      // Custody spans epoch rotation; the ledger directory itself is archived.
-      path: join(coordRoot, ".harnery", "private", "event-v3-generation-custody", authority),
-      scope: "event-v3-generation-custody",
-      authoritySha256: authority,
-      // Expiry never permits stealing a live/unknown owner. A dead local process
-      // can be recovered immediately, including after a cache-handoff crash.
-      staleAfterMs: 1,
-      validateStaleOwner: (owner) =>
-        owner.host === hostname() && owner.authority_sha256 === authority,
-    });
-    held.add(key);
-    try {
-      return enter(index + 1);
-    } finally {
-      held.delete(key);
-      lease.release();
-    }
-  };
-  return enter(0);
-}
-
-/** The event already durably binds the generation; replay must not rebind its actor. */
-export function assertCurrentGenerationV3(
-  coordRoot: string,
-  instanceId: string,
-  generationId: string | undefined,
-): void {
-  const current = readHookProducerStateByInstanceV3(coordRoot, instanceId as `inst_${string}`);
-  if (!generationId || !current || current.generation_id !== generationId) {
-    throw new Error("authority_generation_changed");
-  }
-}