harnery 0.26.0 → 0.28.0

package/src/core/workflow/index.ts

@@ -154,6 +154,7 @@ export {
   isWorkspaceLifecycleState,
   listWorkflowWorkspaceInspections,
   prepareIntegration,
+  prepareReclaim,
   probeLocalGitWorktreeProvider,
   readWorkflowWorkspaceStatus,
   renderWorkflowWorkspaceStatus,

package/src/core/workflow/journal.ts

@@ -0,0 +1,90 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fsyncParentDirectory, stableDigest } from "./durable-record.ts";
+
+// Limit for the JSON record body. The trailing newline delimiter is outside the
+// record and is not counted by readers after splitting journal lines.
+export const WORKFLOW_JOURNAL_EVENT_BYTES = 16 * 1024;
+
+/** Key under which a shrunk record names the fields it had to drop. */
+export const WORKFLOW_JOURNAL_OMITTED = "omitted_fields";
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+
+export interface WorkflowJournalOmission {
+  field: string;
+  bytes: number;
+  sha256: string;
+}
+
+export function workflowJournalPath(coordRoot: string, runId: string): string {
+  if (!RUN_ID.test(runId)) throw new Error(`invalid workflow run id ${JSON.stringify(runId)}`);
+  return join(resolve(coordRoot), ".harnery", "workflows", runId, "journal.jsonl");
+}
+
+/**
+ * Append one journal record, always.
+ *
+ * A record that would exceed what a reader accepts has its largest fields
+ * replaced by a digest and a byte count until it fits, and it names what it
+ * dropped. Size never raises.
+ *
+ * Refusing an oversized record would let a valid run fail on its own opening
+ * line: `run.start` carries the workflow's declared metadata plus the frozen
+ * work and attempt context, and Harnery's own validators permit those to exceed
+ * this limit by construction. Losing detail from a record is recoverable.
+ * Losing the run that was writing it is not.
+ */
+export function appendWorkflowJournalEvent(
+  coordRoot: string,
+  runId: string,
+  event: string,
+  data: Record<string, unknown>,
+): void {
+  const path = workflowJournalPath(coordRoot, runId);
+  const record = fitWorkflowJournalRecord(
+    { schema_version: 1, run_id: runId, ts: new Date().toISOString(), event },
+    data,
+  );
+  const line = `${JSON.stringify(record)}\n`;
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const existed = existsSync(path);
+  const fd = openSync(path, "a", 0o600);
+  try {
+    writeFileSync(fd, line, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  if (!existed) fsyncParentDirectory(path);
+}
+
+/**
+ * Shrink a record to the reader's limit by dropping its largest fields first.
+ * The envelope is never dropped, so a record keeps its run id, timestamp, and
+ * event name however much detail it loses. Exported for tests.
+ */
+export function fitWorkflowJournalRecord(
+  envelope: Record<string, unknown>,
+  data: Record<string, unknown>,
+): Record<string, unknown> {
+  const candidate = { ...envelope, ...data };
+  if (Buffer.byteLength(JSON.stringify(candidate)) <= WORKFLOW_JOURNAL_EVENT_BYTES) {
+    return candidate;
+  }
+  const kept: Record<string, unknown> = { ...data };
+  const omitted: WorkflowJournalOmission[] = [];
+  const bySize = Object.keys(data)
+    .map((field) => ({ field, bytes: Buffer.byteLength(JSON.stringify(data[field]) ?? "") }))
+    .sort((a, b) => b.bytes - a.bytes);
+
+  for (const { field, bytes } of bySize) {
+    omitted.push({ field, bytes, sha256: stableDigest(data[field]) });
+    delete kept[field];
+    const next = { ...envelope, ...kept, [WORKFLOW_JOURNAL_OMITTED]: omitted };
+    if (Buffer.byteLength(JSON.stringify(next)) <= WORKFLOW_JOURNAL_EVENT_BYTES) return next;
+  }
+  // Every field dropped and still over: the omission list is itself the excess.
+  // Keep the envelope and a count so the record stays parseable and honest.
+  return { ...envelope, [WORKFLOW_JOURNAL_OMITTED]: omitted.length };
+}

package/src/core/workflow/proof.ts

@@ -30,6 +30,7 @@ import type {
   WorkflowProofUnknown,
   WorkflowRepoEvidence,
   WorkflowRepoSnapshot,
+  WorkflowSandboxProjectionEvidence,
   WorkflowWorkContext,
 } from "./types.ts";
 import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
@@ -82,6 +83,8 @@ export interface BuildWorkflowProofInput {
   agents: WorkflowAgentProof[];
   evidence: WorkflowEvidenceRecord[];
   harnessEvidence?: Readonly<Record<string, HarnessEvidenceCapability | undefined>>;
+  /** Filesystem policy actually projected into children (ADR 0039). */
+  sandboxProjection?: WorkflowSandboxProjectionEvidence;
   /** Live attestations backing each harness's claims (ADR 0038). Injected by
    * the caller so proof stays free of filesystem lookups. */
   harnessAttestations?: Readonly<Record<string, HarnessAttestationCitation | undefined>>;
@@ -254,6 +257,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
         ? buildExecutionEvidence(input.status, input.workspaceBinding, input.workspaceAttestation)
         : input.workspaceFallback,
     repository,
+    ...(input.sandboxProjection ? { sandbox_projection: input.sandboxProjection } : {}),
     harnesses,
     unknowns,
     integrity: {

package/src/core/workflow/sandbox-projection.ts

@@ -0,0 +1,150 @@
+/**
+ * Project the host's filesystem policy into a harness's own vendor sandbox
+ * (ADR 0039).
+ *
+ * Harnery decides where a workflow child may write. Until this existed it never
+ * told the child, so a child working in a provider-owned Git worktree could
+ * edit files and could not commit: the vendor excludes a repository's
+ * administrative directory from its writable set by policy, and Harnery had no
+ * way to name it as an exception.
+ *
+ * The one rule that matters here is that a projection an adapter cannot
+ * represent is refused before launch. Passing a policy that gets silently
+ * dropped would leave an operator believing a child was constrained when it was
+ * not, which is worse than refusing and worse than never offering the feature.
+ */
+
+import type { HarnessSandboxProjection } from "../harnesses/types.ts";
+import type { GitAdministrativeGrant, SpawnFilesystemPolicy } from "./types.ts";
+import type { WorkspaceBinding } from "./workspaces/types.ts";
+
+export class SandboxProjectionError extends Error {
+  readonly harness: string;
+  readonly reason:
+    | "mode_unrepresentable"
+    | "writable_roots_unrepresentable"
+    | "no_projection"
+    | "writable_root_escapes_workspace"
+    | "git_grant_unavailable";
+
+  constructor(harness: string, reason: SandboxProjectionError["reason"], message: string) {
+    super(message);
+    this.name = "SandboxProjectionError";
+    this.harness = harness;
+    this.reason = reason;
+  }
+}
+
+export interface ResolvedSandboxProjection {
+  /** Vendor-native name for the requested mode. */
+  nativeMode: string;
+  writableRoots: readonly string[];
+}
+
+/**
+ * Resolve a requested policy against what the adapter declares it can carry.
+ * Throws rather than degrading; see the module note.
+ */
+export function resolveSandboxProjection(
+  harness: string,
+  declaration: HarnessSandboxProjection | undefined,
+  policy: SpawnFilesystemPolicy,
+): ResolvedSandboxProjection {
+  if (!declaration) {
+    throw new SandboxProjectionError(
+      harness,
+      "no_projection",
+      `${harness} cannot project a filesystem policy into its sandbox; remove the policy or use a harness that can`,
+    );
+  }
+  const nativeMode = declaration.modes[policy.mode];
+  if (!nativeMode) {
+    throw new SandboxProjectionError(
+      harness,
+      "mode_unrepresentable",
+      `${harness} does not distinguish the "${policy.mode}" filesystem mode, so it cannot be enforced`,
+    );
+  }
+  const writableRoots = policy.writableRoots ?? [];
+  if (writableRoots.length > 0 && !declaration.writableRoots) {
+    throw new SandboxProjectionError(
+      harness,
+      "writable_roots_unrepresentable",
+      `${harness} does not accept an explicit writable-root set, so ${writableRoots.length} declared path(s) could not be enforced`,
+    );
+  }
+  for (const root of writableRoots) {
+    // Relative paths cannot be validated against the provider's roots and are
+    // resolved differently by every vendor, so they are refused outright.
+    if (typeof root !== "string" || !root.startsWith("/")) {
+      throw new SandboxProjectionError(
+        harness,
+        "writable_roots_unrepresentable",
+        `writable root ${JSON.stringify(root)} must be an absolute path`,
+      );
+    }
+  }
+  return { nativeMode, writableRoots };
+}
+
+/** True when `candidate` is `root` or lies beneath it, comparing whole path
+ * segments so `/a/bc` is not treated as inside `/a/b`. */
+function isWithin(root: string, candidate: string): boolean {
+  const normalizedRoot = root.endsWith("/") ? root.slice(0, -1) : root;
+  return candidate === normalizedRoot || candidate.startsWith(`${normalizedRoot}/`);
+}
+
+/**
+ * Refuse a projection that would grant write access outside the root the
+ * workspace provider already validated (ADR 0039).
+ *
+ * The renderer alone cannot do this: it never sees the binding. Granting a path
+ * the provider never sanctioned would let a projection quietly widen the blast
+ * radius of a run that the workspace lifecycle believes it has contained.
+ */
+export function assertProjectionWithinWorkspace(
+  harness: string,
+  allowedRootRealpath: string,
+  writableRoots: readonly string[],
+): void {
+  for (const root of writableRoots) {
+    if (!isWithin(allowedRootRealpath, root)) {
+      throw new SandboxProjectionError(
+        harness,
+        "writable_root_escapes_workspace",
+        `writable root ${JSON.stringify(root)} is outside the workspace root ${JSON.stringify(allowedRootRealpath)} the provider validated`,
+      );
+    }
+  }
+}
+
+/**
+ * Resolve a named Git administrative grant into concrete writable roots
+ * (ADR 0040).
+ *
+ * These are the only paths a run may write outside its workspace, and the
+ * caller never names them: they come from the binding the provider verified.
+ * A caller-supplied path is checked by `assertProjectionWithinWorkspace` and can
+ * never reach here, so asking for the grant is the whole of the widening.
+ *
+ * In a linked worktree both halves of the administrative directory live under
+ * the source repository, and a commit needs the shared half regardless, so the
+ * grant returns both rather than pretending the private half is useful alone.
+ */
+export function resolveGitGrantRoots(
+  grant: GitAdministrativeGrant,
+  binding: WorkspaceBinding | undefined,
+): readonly string[] {
+  if (grant === "none") return [];
+  const repository = binding?.repository;
+  if (!repository) {
+    throw new SandboxProjectionError(
+      "workflow",
+      "git_grant_unavailable",
+      `gitWrite "${grant}" needs a Git repository binding; this run has ${binding ? "a workspace with no repository" : "no isolated workspace"}`,
+    );
+  }
+  // Deduplicated: a full-clone topology reports the same path for both, and a
+  // repeated writable root is noise in the rendered argv and in proof.
+  return [...new Set([repository.gitdir.realpath, repository.common_dir.realpath])];
+}

package/src/core/workflow/spawn-claude.ts

@@ -19,10 +19,11 @@
  */
 
 import { exec } from "../../lib/exec.ts";
-import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
 import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
+import { resolveSandboxProjection } from "./sandbox-projection.ts";
 import { vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
@@ -38,6 +39,14 @@ interface ClaudeEnvelope {
 
 export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
   validateHarnessEffort("claude-code", req.effort);
+  if (req.filesystemPolicy) {
+    // Declared unrepresentable: refuse rather than drop it silently (ADR 0039).
+    resolveSandboxProjection(
+      "claude-code",
+      builtinHarnessProfile("claude-code")?.sandboxProjection,
+      req.filesystemPolicy,
+    );
+  }
   const argv = [
     "claude",
     "-p",
@@ -53,6 +62,14 @@ export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
 }
 
 export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `claude timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return {
       ok: false,

package/src/core/workflow/spawn-codex.ts

@@ -20,16 +20,25 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { exec } from "../../lib/exec.ts";
-import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
 import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
+import { resolveSandboxProjection } from "./sandbox-projection.ts";
 import { vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): HarnessInvocation {
   validateHarnessEffort("codex", req.effort);
   if (!resultFile) throw new Error("codex adapter requires a final-message result file");
+  // Default stays workspace-write so an unprojected request is unchanged.
+  const projection = req.filesystemPolicy
+    ? resolveSandboxProjection(
+        "codex",
+        builtinHarnessProfile("codex")?.sandboxProjection,
+        req.filesystemPolicy,
+      )
+    : undefined;
   const argv = [
     "codex",
     "exec",
@@ -38,14 +47,28 @@ export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): Ha
     resultFile,
     "--skip-git-repo-check",
     "--sandbox",
-    "workspace-write",
+    projection?.nativeMode ?? "workspace-write",
   ];
+  if (projection && projection.writableRoots.length > 0) {
+    argv.push(
+      "-c",
+      `sandbox_workspace_write.writable_roots=${JSON.stringify(projection.writableRoots)}`,
+    );
+  }
   if (req.model) argv.push("--model", req.model);
   if (req.effort) argv.push("-c", `model_reasoning_effort=${JSON.stringify(req.effort)}`);
   return { argv, resultFile };
 }
 
 export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `codex timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
   }

package/src/core/workflow/spawn-cursor.ts

@@ -20,10 +20,11 @@
  */
 
 import { exec } from "../../lib/exec.ts";
-import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
 import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
+import { resolveSandboxProjection } from "./sandbox-projection.ts";
 import { vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
@@ -54,6 +55,14 @@ export function parseCursorOutput(stdout: string): {
 
 export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
   validateHarnessEffort("cursor", req.effort);
+  if (req.filesystemPolicy) {
+    // Declared unrepresentable: refuse rather than drop it silently (ADR 0039).
+    resolveSandboxProjection(
+      "cursor",
+      builtinHarnessProfile("cursor")?.sandboxProjection,
+      req.filesystemPolicy,
+    );
+  }
   // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
   // "Workspace Trust Required"). --force: a print-mode child has no interactive
   // approval channel, so host-authorized workflow dispatch must let it run
@@ -65,6 +74,14 @@ export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
 }
 
 export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `cursor timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
   if (raw.exitCode === 127) {
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
   }

package/src/core/workflow/types.ts

@@ -151,6 +151,13 @@ export interface HarnessEvidenceCoverage {
   attestation?: HarnessAttestationCitation;
 }
 
+export interface WorkflowSandboxProjectionEvidence {
+  mode: SpawnFilesystemPolicy["mode"];
+  writable_roots: string[];
+  /** Which Git administrative grant the run asked for (ADR 0040). */
+  git_grant: GitAdministrativeGrant;
+}
+
 export interface WorkflowProofUnknown {
   code:
     | "tool_evidence_unavailable"
@@ -190,6 +197,10 @@ export interface WorkflowProof {
   /** Immutable terminal provider evidence for isolated execution. */
   execution?: WorkspaceExecutionEvidence;
   repository: WorkflowRepoEvidence;
+  /** Filesystem policy projected into every child's vendor sandbox (ADR 0039).
+   * Absent means no projection was applied, which is the default. Present means
+   * the run can be audited for exactly what its children could write. */
+  sandbox_projection?: WorkflowSandboxProjectionEvidence;
   harnesses: HarnessEvidenceCoverage[];
   unknowns: WorkflowProofUnknown[];
   integrity: {
@@ -313,6 +324,33 @@ export interface SpawnRequest {
   /** Scrub all API-key vars from the child env so it can only authenticate
    * via its stored (subscription) login. See billing.ts. */
   subscriptionOnly?: boolean;
+  /** Filesystem policy to project into the child's own vendor sandbox
+   * (ADR 0039). Absent leaves the adapter's default invocation untouched, which
+   * is what shared-checkout runs use. An adapter that cannot represent the
+   * requested projection refuses before launch rather than downgrading. */
+  filesystemPolicy?: SpawnFilesystemPolicy;
+}
+
+/**
+ * Whether a run may write the Git administrative directory (ADR 0040).
+ *
+ * There is no middle setting, and the reason is a property of Git rather than a
+ * design choice. A linked worktree has a private administrative directory and a
+ * shared one, but object writes and branch refs live in the shared half, so even
+ * `git add` fails without it. A grant that enables a commit is therefore always
+ * a grant on the repository every worktree shares, including the operator's own
+ * checkout. That is why it has to be asked for by name.
+ */
+export type GitAdministrativeGrant = "none" | "shared-repository";
+
+/** What the host has decided the child may write. `full-access` is deliberately
+ * not a mode: Harnery does not project a no-sandbox state into a vendor CLI. */
+export interface SpawnFilesystemPolicy {
+  mode: "read-only" | "workspace-write";
+  /** Explicit absolute paths the child may write, declared rather than derived
+   * from `cwd`. The path that needs writing (a repository's administrative
+   * directory, for instance) is routinely outside the working directory. */
+  writableRoots?: readonly string[];
 }
 
 /** One headless-subagent runner. The engine is adapter-agnostic; claude-code
@@ -389,6 +427,18 @@ export interface WorkflowAttemptContext {
   readonly number: number;
   readonly trigger: "initial" | "retry";
   readonly prior?: Readonly<WorkflowAttemptPriorContext>;
+  /** Open findings an operator raised against a prior attempt. Present on any
+   * trigger, because a reopen with findings starts a fresh initial attempt.
+   * Distinct from `prior`, which is evidence the run itself produced. */
+  readonly findings?: readonly Readonly<WorkflowOperatorFinding>[];
+}
+
+/** One correction an operator raised against work they judged wrong. Authored
+ * by a human, not derived from proof, and carried until explicitly disposed. */
+export interface WorkflowOperatorFinding {
+  readonly id: string;
+  readonly actor: string;
+  readonly statement: string;
 }
 
 export interface EngineOpts {
@@ -444,6 +494,22 @@ export interface EngineOpts {
   /** Live attestations backing each harness's claims (ADR 0038). Read once by
    * the host and injected, so the engine performs no capability lookups. */
   harnessAttestations?: Readonly<Record<HarnessName, HarnessAttestationCitation | undefined>>;
+  /** Filesystem policy projected into every child's own vendor sandbox
+   * (ADR 0039). Validated against the workspace binding before the first spawn,
+   * and recorded in proof. Absent leaves every adapter invocation unchanged. */
+  filesystemPolicy?: SpawnFilesystemPolicy;
+  /**
+   * Whether children may write the repository's administrative directory
+   * (ADR 0040). Defaults to `"none"`.
+   *
+   * The caller asks for the grant by name and never supplies the path: the
+   * engine resolves it from the workspace binding the provider already
+   * verified. That asymmetry is deliberate. `filesystemPolicy.writableRoots` is
+   * caller-supplied and must stay inside the workspace, so a caller cannot use
+   * it to reach the source repository; this grant can, which is exactly why it
+   * is a named capability rather than another path.
+   */
+  gitWrite?: GitAdministrativeGrant;
   /** Immutable host policy. Workflow scripts and model prompts cannot replace it. */
   policy?: PolicySpec | NormalizedPolicy;
   /** Host callback for ASK. Missing, invalid, throwing, or timed-out resolution denies. */

package/src/core/workflow/workspaces/index.ts

@@ -35,6 +35,8 @@ export {
   createLocalGitWorktreeProvider,
   probe as probeLocalGitWorktreeProvider,
 } from "./local-git.ts";
+export type { PrepareReclaimInput, ReclaimMode, ReclaimPreparation } from "./reclaim.ts";
+export { prepareReclaim } from "./reclaim.ts";
 export type {
   AuthorizedIntegrationPlan,
   AuthorizedProviderIntegrationInput,

package/src/core/workflow/workspaces/inspect.ts

@@ -337,9 +337,24 @@ export function renderWorkflowWorkspaceStatus(status: WorkflowWorkspaceStatus):
     `cleanup: ${status.cleanup.state}; ${status.cleanup.attempts} attempt`,
   );
   if (status.cleanup.reason) lines.push(`cleanup reason: ${status.cleanup.reason}`);
+  // A count alone cannot be acted on: an operator deciding whether to salvage or
+  // discard has to know what is actually uncommitted, and leaving Harnery to run
+  // `git status` is the gap `reclaim` exists to close (ADR 0042). Bounded,
+  // because a dirty tree can be arbitrarily large.
+  if (status.repository.dirty_paths.length > 0) {
+    // Entries arrive in porcelain form (` M path`), so the status code is worth
+    // keeping and the leading pad is not.
+    const shown = status.repository.dirty_paths
+      .slice(0, MAX_LISTED_DIRTY_PATHS)
+      .map((path) => path.trim());
+    const remainder = status.repository.dirty_paths.length - shown.length;
+    lines.push(`dirty paths: ${shown.join(", ")}${remainder > 0 ? ` (+${remainder} more)` : ""}`);
+  }
   return `${lines.join("\n")}\n`;
 }
 
+const MAX_LISTED_DIRTY_PATHS = 12;
+
 function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalProjectionEvent[] {
   const path = join(runDir, "journal.jsonl");
   if (!existsSync(path)) return [];

package/src/core/workflow/workspaces/reclaim.ts

@@ -0,0 +1,109 @@
+/**
+ * Resolve a workspace stuck at `preserved_dirty` (ADR 0042).
+ *
+ * When a run ends with uncommitted work, the provider preserves the worktree
+ * rather than destroying the only copy of that work. That decision is correct,
+ * and until this existed it was also permanent: cleanup re-attempted, found the
+ * tree still dirty, preserved again, and incremented a counter. The only exit
+ * was to leave Harnery and remove the directory by hand, after which Harnery's
+ * records described a workspace that no longer existed.
+ *
+ * The shape of the fix is deliberate. Neither mode deletes anything directly.
+ * Each one makes the working tree *clean* by an explicit, named act, and then
+ * hands off to the ordinary cleanup path, which releases a clean workspace as it
+ * always has. So reclaim adds no second removal path that could diverge from the
+ * audited one, and a force-delete of live work exists nowhere in the codebase.
+ */
+
+import { existsSync } from "node:fs";
+import { git, gitMaybe } from "./git.ts";
+
+export type ReclaimMode = "salvage" | "discard";
+
+export type ReclaimPreparation =
+  | { action: "salvaged"; branch: string; commit: string; detail: string }
+  | { action: "discarded"; detail: string }
+  | { action: "already_clean"; detail: string }
+  | { action: "already_gone"; detail: string };
+
+export interface PrepareReclaimInput {
+  worktreePath: string;
+  mode: ReclaimMode;
+  runId: string;
+}
+
+/**
+ * Bring the worktree to a clean state so ordinary cleanup can release it.
+ *
+ * Returns `already_gone` rather than throwing when the directory has been
+ * removed out from under us. A workspace whose worktree no longer exists has
+ * effectively been reclaimed; treating that as an error is what produced an
+ * attempt counter that only ever went up.
+ */
+export function prepareReclaim(input: PrepareReclaimInput): ReclaimPreparation {
+  if (!existsSync(input.worktreePath)) {
+    return {
+      action: "already_gone",
+      detail: "the worktree directory is already gone; nothing to reclaim",
+    };
+  }
+
+  const status = gitMaybe(input.worktreePath, ["status", "--porcelain"]);
+  if (!status.ok) {
+    throw new Error(`cannot read worktree status for reclaim: ${status.err || "git failed"}`);
+  }
+  if (status.out.trim().length === 0) {
+    return { action: "already_clean", detail: "the worktree has no uncommitted changes" };
+  }
+
+  if (input.mode === "discard") {
+    // Ordered: reset drops tracked modifications, clean removes what reset
+    // cannot see. Running clean first would leave staged deletions behind.
+    git(input.worktreePath, ["reset", "--hard"]);
+    git(input.worktreePath, ["clean", "-fd"]);
+    return { action: "discarded", detail: "uncommitted changes were discarded on request" };
+  }
+
+  // Salvage onto a ref of its own, then put the checked-out branch back exactly
+  // where it was. Two reasons, both learned by doing it the obvious way first:
+  //
+  //  1. Cleanup DELETES the provider's workspace branch. Committing the salvage
+  //     there would have parked the work on a ref that the very next step
+  //     removes, leaving it unreachable and eventually collectable.
+  //  2. Cleanup pins the workspace ref's OID in a frozen intent and refuses when
+  //     it moves, which is a guard worth keeping. Advancing that branch turned
+  //     every reclaim into `blocked`.
+  //
+  // Committing and rewinding satisfies both: the tree ends clean, the workspace
+  // ref ends untouched, and the work lives on a ref cleanup has no reason to
+  // touch.
+  const before = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+  git(input.worktreePath, ["add", "-A"]);
+  git(input.worktreePath, ["commit", "--no-verify", "-m", salvageMessage(input.runId)]);
+  const commit = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+  const branch = salvageBranch(input.runId);
+  git(input.worktreePath, ["branch", "--force", branch, commit]);
+  git(input.worktreePath, ["reset", "--hard", before]);
+  return {
+    action: "salvaged",
+    branch,
+    commit,
+    detail: `salvaged to ${branch} at ${commit.slice(0, 12)}`,
+  };
+}
+
+/**
+ * `--no-verify` above is not a shortcut. A salvage commit is an archival act on
+ * an abandoned workspace, so a repository hook that rejects work in progress
+ * would convert "preserve the work" into "cannot preserve the work", which is
+ * the failure this whole path exists to prevent.
+ */
+function salvageMessage(runId: string): string {
+  return `chore(workspace): salvage uncommitted work from run ${runId}`;
+}
+
+/** Named for the run rather than the workspace, because the run id is what an
+ * operator has in hand when they come looking for the work later. */
+export function salvageBranch(runId: string): string {
+  return `harnery/salvage/${runId}`;
+}