harnery 0.43.0 → 0.45.0

package/src/lib/guarded-remove.ts

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, type Stats } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 
 export interface RemoveOptions {
   root: string;
@@ -16,6 +16,12 @@ export interface RemoveOptions {
   allowProtected?: string[];
   /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
   liveRoots?: string[];
+  /** Command-layer validation of the current caller's ownership of this exact managed artifact root. */
+  assertOwnedArtifact?: (root: string) => void;
+  /** Inspection bound; values above 10,000 require verified ownership of the exact artifact root. */
+  entryLimit?: number;
+  /** Remove only verified-clean standalone clones inside the caller's owned artifact. */
+  cleanClone?: boolean;
 }
 
 export interface RemovalLink {
@@ -30,6 +36,7 @@ export interface RemovalReport {
   root: string;
   targets: string[];
   entries: number;
+  entry_limit: number;
   bytes: number;
   /** Protected paths removed because the caller named them with allowProtected. */
   protected: string[];
@@ -39,6 +46,7 @@ export interface RemovalReport {
 
 const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
 const MAX_ENTRIES = 10_000;
+const MAX_OWNED_ARTIFACT_ENTRIES = 100_000;
 
 /** Permanent removal is deliberately limited to inspected, untracked local outputs. */
 export function guardedRemove(
@@ -48,18 +56,48 @@ export function guardedRemove(
 ): RemovalReport {
   const cwd = realpathSync(process.cwd());
   const root = checkedPath(options.root, new Set(), true);
-  const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? []);
+  if (options.cleanClone) {
+    if (!options.recursive) throw new Error("Clean clone removal requires --recursive");
+    if (options.allowProtected?.length)
+      throw new Error("Clean clone removal cannot be combined with --allow-protected");
+    if (!options.assertOwnedArtifact)
+      throw new Error("Clean clone removal requires one current caller-owned managed artifact");
+    options.assertOwnedArtifact(root);
+  }
+  const entryLimit = options.entryLimit ?? MAX_ENTRIES;
+  if (
+    !Number.isSafeInteger(entryLimit) ||
+    entryLimit < 1 ||
+    entryLimit > MAX_OWNED_ARTIFACT_ENTRIES
+  )
+    throw new Error(`The entry limit must be an integer from 1 to ${MAX_OWNED_ARTIFACT_ENTRIES}`);
+  const assertEntryLimitAuthority = () => {
+    if (entryLimit <= MAX_ENTRIES) return;
+    if (!options.assertOwnedArtifact)
+      throw new Error(
+        "An entry limit above 10000 requires one current caller-owned managed artifact",
+      );
+    options.assertOwnedArtifact(root);
+  };
+  const allowed = allowedProtected(
+    options.allowProtected ?? [],
+    root,
+    options.liveRoots ?? [],
+    options.assertOwnedArtifact,
+  );
   const rootStat = lstatSync(root);
   const rootFingerprint = fingerprint(rootStat);
   if (!rootStat.isDirectory()) throw new Error("--root must be a directory");
   if (root === parse(root).root || root === realpathSync(homedir()))
     throw new Error("--root cannot be a filesystem root or home directory");
+  assertEntryLimitAuthority();
   if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
   const targets = paths.map((path) => checkedPath(path, allowed));
   const snapshots = new Map<string, string>();
   const removedProtected = new Set<string>();
   const links: RemovalLink[] = [];
   const gitDirs = new Set<string>();
+  const cleanClones = new Set<string>();
   let bytes = 0;
   const devices = new Set<number>();
 
@@ -110,6 +148,10 @@ export function guardedRemove(
     if (stat.isDirectory() && !options.recursive)
       throw new Error(`Directory removal requires --recursive: ${target}`);
     const device = stat.dev;
+    if (options.cleanClone) {
+      assertCleanClone(target);
+      cleanClones.add(target);
+    }
     devices.add(device);
     const pending = [target];
     while (pending.length) {
@@ -118,6 +160,12 @@ export function guardedRemove(
       if (basename(path) === ARTIFACT_RECORD && insideArtifactWorkspace(path, null))
         throw new Error(`An artifact's record is managed by the artifact commands: ${path}`);
       if (protectedNames.has(basename(path).toLowerCase())) {
+        if (options.cleanClone && basename(path) === ".git") {
+          const clone = dirname(path);
+          assertCleanClone(clone);
+          cleanClones.add(clone);
+          allowed.add(path);
+        }
         if (!allowed.has(path)) throw new Error(protectedMessage(path));
         removedProtected.add(path);
       }
@@ -126,9 +174,9 @@ export function guardedRemove(
         // read, followed, or counted. (The target itself and its ancestors
         // were already refused if they were links, in checkedPath.)
         if (path === target) throw new Error(`Path contains a symlink: ${path}`);
-        if (snapshots.size >= MAX_ENTRIES)
+        if (snapshots.size >= entryLimit)
           throw new Error(
-            `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+            `Removal exceeds the ${entryLimit}-entry limit; use the owning cleanup command`,
           );
         snapshots.set(path, fingerprint(info));
         links.push({ path, target: readlinkSync(path) });
@@ -136,9 +184,9 @@ export function guardedRemove(
       }
       if (info.dev !== device || (!info.isDirectory() && !info.isFile()))
         throw new Error(`Mount boundary or special file cannot be removed: ${path}`);
-      if (snapshots.size >= MAX_ENTRIES)
+      if (snapshots.size >= entryLimit)
         throw new Error(
-          `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+          `Removal exceeds the ${entryLimit}-entry limit; use the owning cleanup command`,
         );
       snapshots.set(path, fingerprint(info));
       if (info.isFile()) bytes += info.size;
@@ -172,6 +220,7 @@ export function guardedRemove(
     root,
     targets,
     entries: snapshots.size,
+    entry_limit: entryLimit,
     bytes,
     protected: [...removedProtected].sort(),
     links,
@@ -185,11 +234,21 @@ export function guardedRemove(
     fingerprint(lstatSync(root)) !== rootFingerprint
   )
     throw new Error("Allowed root changed during inspection");
+  assertEntryLimitAuthority();
+  if (options.cleanClone) options.assertOwnedArtifact!(root);
+  // Ownership may have been released or changed while the contents were inspected.
+  allowedProtected(
+    options.allowProtected ?? [],
+    root,
+    options.liveRoots ?? [],
+    options.assertOwnedArtifact,
+  );
   for (const target of targets) {
     checkedPath(target, allowed);
     assertUntracked(target);
   }
   for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  for (const clone of cleanClones) assertCleanClone(clone);
   checkClaims(targets);
   for (const [path, previous] of snapshots) {
     if (fingerprint(lstatSync(path)) !== previous)
@@ -200,6 +259,47 @@ export function guardedRemove(
   return { ...report, applied: true };
 }
 
+/** A disposable clone must not be the only copy of work or a registered worktree. */
+function assertCleanClone(clone: string): void {
+  const metadata = join(clone, ".git");
+  const stat = lstatSync(metadata);
+  if (!stat.isDirectory() || stat.isSymbolicLink())
+    throw new Error(`Clean clone removal requires a standalone .git directory: ${clone}`);
+  const git = (args: string[]) => {
+    const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-C", clone, ...args], {
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+      env: {
+        ...process.env,
+        LC_ALL: "C",
+        GIT_DIR: undefined,
+        GIT_COMMON_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+        GIT_INDEX_FILE: undefined,
+        GIT_OPTIONAL_LOCKS: "0",
+      },
+    });
+    if (result.error || result.status !== 0)
+      throw new Error(`Cannot verify clean clone ${clone}: git ${args[0]} failed`);
+    return result.stdout;
+  };
+  if (
+    realpathSync(git(["rev-parse", "--show-toplevel"]).trim()) !== clone ||
+    realpathSync(resolve(clone, git(["rev-parse", "--git-common-dir"]).trim())) !== metadata
+  )
+    throw new Error(`Clean clone removal refuses shared repository metadata: ${clone}`);
+  const worktrees = git(["worktree", "list", "--porcelain", "-z"])
+    .split("\0")
+    .filter((entry) => entry.startsWith("worktree "));
+  if (worktrees.length !== 1 || worktrees[0] !== `worktree ${clone}`)
+    throw new Error(`Clean clone removal refuses registered or linked worktrees: ${clone}`);
+  if (git(["status", "--porcelain=v1", "--untracked-files=all"]).trim())
+    throw new Error(`Clean clone has uncommitted or untracked work: ${clone}`);
+  if (git(["rev-list", "--max-count=1", "HEAD", "--all", "--reflog", "--not", "--remotes"]).trim())
+    throw new Error(`Clean clone has HEAD, ref or reflog commits not on any remote: ${clone}`);
+}
+
 /** The metadata file the artifact commands keep in each artifact workspace. */
 const ARTIFACT_RECORD = ".harnery-artifact.json";
 
@@ -238,9 +338,14 @@ function insideAllowed(path: string, allowed: ReadonlySet<string>): boolean {
  * protected path strictly inside the root, reached without symlinks, and
  * never the Git metadata or Harnery state of a live workspace root.
  */
-function allowedProtected(paths: string[], root: string, liveRoots: string[]): Set<string> {
+function allowedProtected(
+  paths: string[],
+  root: string,
+  liveRoots: string[],
+  assertOwnedArtifact?: (root: string) => void,
+): Set<string> {
   const allowed = new Set<string>();
-  const live = liveRoots.map((dir) => resolve(dir));
+  const live = liveRoots.map((dir) => realpathSync(dir));
   for (const input of paths) {
     if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
       throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
@@ -261,13 +366,26 @@ function allowedProtected(paths: string[], root: string, liveRoots: string[]): S
     if (!named && !(info.isDirectory() && isRepositoryMetadata(path)))
       throw new Error(`--allow-protected must name a protected path itself: ${path}`);
     for (const dir of live) {
-      const own = [".git", ".harnery"].map((name) => resolve(dir, name));
-      if (
-        path === dir ||
-        strictlyInside(path, dir) ||
-        own.some((state) => path === state || strictlyInside(state, path))
-      )
+      if (path === dir || strictlyInside(path, dir))
+        throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+      for (const name of [".git", ".harnery"]) {
+        const state = resolve(dir, name);
+        if (path !== state && !strictlyInside(state, path)) continue;
+        // Only an explicitly named copied state directory inside one owned
+        // artifact may cross the outer live-state ancestor. Other live roots
+        // (including a checkout inside that artifact) still veto the path.
+        if (
+          name === ".harnery" &&
+          basename(path) === ".harnery" &&
+          info.isDirectory() &&
+          dirname(root) === resolve(state, "artifacts") &&
+          assertOwnedArtifact
+        ) {
+          assertOwnedArtifact(root);
+          continue;
+        }
         throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+      }
     }
     allowed.add(realpathSync(path));
   }

package/src/lib/identities/assume.ts

@@ -140,6 +140,7 @@ export function reclaimAbandonedLocalConflict(
   let sessionId = conflict.instance_id;
   let ageSecs: number | undefined;
   const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
+  let expectedGenerationId = liveRow?.v3_generation_id ?? null;
   if (liveRow) {
     adapter = adapterOf(liveRow.platform);
     sessionId = liveRow.session_id || conflict.instance_id;
@@ -153,7 +154,9 @@ export function reclaimAbandonedLocalConflict(
       // It is required to join the exact producer state when recording the sweep.
       adapter = adapterOf(hb.platform);
       sessionId = hb.session_id || conflict.instance_id;
+      expectedGenerationId = hb.v3_generation_id ?? null;
     } catch {
+      expectedGenerationId = null;
       /* content unreadable — still reclaim the file */
     }
     try {
@@ -168,6 +171,7 @@ export function reclaimAbandonedLocalConflict(
     owner: conflict.instance_id,
     nativeSessionId: sessionId,
     adapter,
+    expectedGenerationId,
     observation: "stale_heartbeat",
     ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
   });

package/src/lib/tunnel/state.ts

@@ -2,6 +2,7 @@
 // <cwd>/.cache/tunnel/; gitignored, so the allowlist is per-machine.
 
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import {
   accessSync,
   chmodSync,
@@ -10,6 +11,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  renameSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -104,10 +106,12 @@ export interface TunnelState {
   provider: TunnelProvider;
   url: string;
   gate_pid: number;
+  gate_start_token?: string;
+  cloudflared_start_token?: string;
+  registration_id?: string;
+  provider_state?: "pending" | "ready";
   /** Present for Cloudflare quick tunnels; absent for Tailscale Serve/Funnel. */
   cloudflared_pid?: number;
-  /** Optional provider-side process when a provider owns one. */
-  provider_pid?: number;
   started_at: string;
   target: string;
   vhost: string;
@@ -168,7 +172,15 @@ export function readState(
 }
 
 export function writeState(state: TunnelState, root: string = process.cwd()): void {
-  writeFileSync(cachePath(stateFile(state.name), root), JSON.stringify(state, null, 2));
+  const path = cachePath(stateFile(state.name), root);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(state, null, 2), { flag: "wx", mode: 0o600 });
+    renameSync(temporary, path);
+  } catch (error) {
+    if (existsSync(temporary)) unlinkSync(temporary);
+    throw error;
+  }
 }
 
 export function clearState(name: string = DEFAULT_INSTANCE, root: string = process.cwd()): void {
@@ -202,17 +214,60 @@ export function isProcessAlive(pid: number): boolean {
   }
 }
 
-export type ProcessAliveCheck = (pid: number) => boolean;
+export type TunnelReadiness = "ready" | "dead" | "unknown";
+export type TunnelProcessObservation = "same" | "absent" | "different" | "unknown";
+
+export interface TunnelReadinessVerifier {
+  observeProcess(pid: number, originalToken: string): TunnelProcessObservation;
+  withRegistration(state: TunnelState, inspect: () => TunnelReadiness): TunnelReadiness;
+}
 
-/** True when both the local gate and its provider-side process are live. */
-export function isTunnelStateLive(
+/** Classify saved original witnesses under the verifier's registration custody. */
+export function tunnelReadiness(
   state: TunnelState,
-  processAlive: ProcessAliveCheck = isProcessAlive,
-): boolean {
-  if (!processAlive(state.gate_pid)) return false;
-  if (state.provider === "tailscale") return true;
-  const providerPid = state.cloudflared_pid ?? state.provider_pid;
-  return typeof providerPid === "number" && processAlive(providerPid);
+  verifier: TunnelReadinessVerifier,
+): TunnelReadiness {
+  if (
+    !state ||
+    typeof state !== "object" ||
+    Object.hasOwn(state, "provider_pid") ||
+    Object.hasOwn(state, "provider_start_token") ||
+    typeof state.registration_id !== "string" ||
+    !state.registration_id ||
+    !Number.isSafeInteger(state.gate_pid) ||
+    state.gate_pid < 1 ||
+    typeof state.gate_start_token !== "string" ||
+    !state.gate_start_token
+  )
+    return "unknown";
+  const targets = [{ pid: state.gate_pid, token: state.gate_start_token }];
+  if (state.provider === "tailscale") {
+    if (
+      state.provider_state !== "ready" ||
+      state.cloudflared_pid !== undefined ||
+      state.cloudflared_start_token !== undefined
+    )
+      return "unknown";
+  } else if (state.provider === "cloudflare") {
+    if (
+      !Number.isSafeInteger(state.cloudflared_pid) ||
+      state.cloudflared_pid! < 1 ||
+      typeof state.cloudflared_start_token !== "string" ||
+      !state.cloudflared_start_token
+    )
+      return "unknown";
+    targets.push({ pid: state.cloudflared_pid!, token: state.cloudflared_start_token });
+  } else return "unknown";
+  try {
+    return verifier.withRegistration(state, () => {
+      const observed = targets.map(({ pid, token }) => verifier.observeProcess(pid, token));
+      if (observed.every((value) => value === "absent")) return "dead";
+      if (observed.every((value) => value === "same")) return "ready";
+      return "unknown";
+    });
+  } catch {
+    return "unknown";
+  }
 }
 
 export function tunnelTargetPort(state: TunnelState): number | null {
@@ -242,15 +297,15 @@ export function tunnelTargetPort(state: TunnelState): number | null {
 export function findLiveTunnelForOrigin(
   port: number,
   vhost: string,
-  root: string = process.cwd(),
-  processAlive: ProcessAliveCheck = isProcessAlive,
+  root: string,
+  verifier: TunnelReadinessVerifier,
 ): TunnelState | null {
   return (
     listStates(root).find(
       (state) =>
         tunnelTargetPort(state) === port &&
         state.vhost === vhost &&
-        isTunnelStateLive(state, processAlive),
+        tunnelReadiness(state, verifier) === "ready",
     ) ?? null
   );
 }