harnery 0.22.1 → 0.24.0

package/src/core/workflow/run-state.ts

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
   chmodSync,
   closeSync,
@@ -6,7 +6,6 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
-  renameSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -23,6 +22,7 @@ import {
 } from "../policy/index.ts";
 import { assertWorkflowRunId, readWorkflowApproval } from "./approvals.ts";
 import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
+import { readJsonRecord, writeImmutableJson } from "./durable-record.ts";
 import { normalizeWorkflowSpecialists } from "./specialists.ts";
 import type {
   WorkflowAttemptContext,
@@ -30,6 +30,16 @@ import type {
   WorkflowWorkContext,
 } from "./types.ts";
 import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
+import type {
+  WorkspaceAllocationRequest,
+  WorkspaceBinding,
+  WorkspaceUnsupportedExecutionEvidence,
+} from "./workspaces/index.ts";
+import {
+  assertWorkspaceManifestAuthority,
+  isWorkspaceBinding,
+  isWorkspaceUnsupportedExecutionEvidence,
+} from "./workspaces/validate.ts";
 
 export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
 
@@ -59,6 +69,8 @@ export interface WorkflowRunManifest {
     network_access: PolicyNetworkAccess;
     policy?: NormalizedPolicy;
     specialists?: Record<string, WorkflowSpecialistProfile>;
+    workspace_binding?: WorkspaceBinding;
+    workspace_fallback?: WorkspaceUnsupportedExecutionEvidence;
   };
 }
 
@@ -73,6 +85,10 @@ export function workflowScriptDigest(scriptPath: string): string {
 
 export function writeWorkflowRunManifest(input: WriteWorkflowRunManifestInput): string {
   assertWorkflowRunId(input.manifest.run_id);
+  assertWorkspaceManifestAuthority(
+    input.manifest,
+    readManifestWorkspaceRequest(input.coordRoot, input.manifest.run_id),
+  );
   const path = workflowRunManifestPath(input.coordRoot, input.manifest.run_id);
   if (existsSync(path))
     throw new Error(`workflow run ${input.manifest.run_id} already has a manifest`);
@@ -81,14 +97,7 @@ export function writeWorkflowRunManifest(input: WriteWorkflowRunManifestInput):
     throw new Error(`workflow run manifest exceeds ${MANIFEST_LIMIT_BYTES} bytes`);
   }
   mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
-  try {
-    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
-    renameSync(temporary, path);
-    chmodSync(path, 0o600);
-  } finally {
-    if (existsSync(temporary)) unlinkSync(temporary);
-  }
+  writeImmutableJson(path, input.manifest);
   return path;
 }
 
@@ -131,6 +140,7 @@ export function readWorkflowRunManifest(coordRoot: string, runId: string): Workf
   ) {
     throw new Error(`workflow run manifest at ${path} has an unsupported or mismatched schema`);
   }
+  assertWorkspaceManifestAuthority(manifest, readManifestWorkspaceRequest(coordRoot, runId));
   return manifest;
 }
 
@@ -273,10 +283,35 @@ function validExecution(value: WorkflowRunManifest["execution"]): boolean {
     ["shared", "worktree", "sandbox", "remote"].includes(value.isolation) &&
     ["enabled", "disabled", "unknown"].includes(value.network_access) &&
     validSpecialists(value.specialists) &&
-    validFrozenPolicy(value.policy, value.cwd)
+    validFrozenPolicy(value.policy, value.workspace_binding?.integration_root ?? value.cwd) &&
+    validWorkspaceBinding(value.workspace_binding) &&
+    validWorkspaceFallback(value.workspace_fallback) &&
+    !(value.workspace_binding && value.workspace_fallback) &&
+    (value.workspace_fallback === undefined ||
+      value.workspace_fallback.requested_isolation === value.isolation)
   );
 }
 
+function readManifestWorkspaceRequest(
+  coordRoot: string,
+  runId: string,
+): WorkspaceAllocationRequest | undefined {
+  const path = join(coordRoot, ".harnery", "workflows", runId, "workspace-request.json");
+  return existsSync(path)
+    ? readJsonRecord<WorkspaceAllocationRequest>(path, "workspace request")
+    : undefined;
+}
+
+function validWorkspaceBinding(binding: WorkspaceBinding | undefined): boolean {
+  return binding === undefined || isWorkspaceBinding(binding);
+}
+
+function validWorkspaceFallback(
+  fallback: WorkspaceUnsupportedExecutionEvidence | undefined,
+): boolean {
+  return fallback === undefined || isWorkspaceUnsupportedExecutionEvidence(fallback);
+}
+
 function validSpecialists(
   specialists: Record<string, WorkflowSpecialistProfile> | undefined,
 ): boolean {

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

@@ -10,6 +10,9 @@
  *   session_id, …}`).
  * - `--trust` is required: headless runs refuse untrusted workspaces (exit 1,
  *   "Workspace Trust Required") — see the argv comment below.
+ * - `--force` is required: print mode has no channel for an operator to approve
+ *   shell commands, so Smart Auto can leave a child able to patch files but
+ *   unable to test or commit them.
  * - Envelope drift guard: when stdout doesn't parse as JSON but the process
  *   exited 0, the raw stdout is returned as the reply text.
  * - No per-run cost surface → undefined. No max-turns equivalent → `maxTurns`
@@ -51,10 +54,11 @@ export function parseCursorOutput(stdout: string): {
 export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
   validateHarnessEffort("cursor", req.effort);
   // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
-  // "Workspace Trust Required"). Workflow children run in the engine's cwd
-  // deliberately and may edit files — the same posture as the codex adapter's
-  // `--sandbox workspace-write` — so trusting that directory is implied.
-  const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust"];
+  // "Workspace Trust Required"). --force: a print-mode child has no interactive
+  // approval channel, so host-authorized workflow dispatch must let it run
+  // commands. Neither flag maps host policy into child tools; that capability
+  // remains explicitly unsupported.
+  const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust", "--force"];
   if (req.model) argv.push("--model", req.model);
   return { argv };
 }

package/src/core/workflow/types.ts

@@ -18,6 +18,11 @@ import type {
   PolicySpec,
 } from "../policy/index.ts";
 import type { BillingMode, BillingProber } from "./billing.ts";
+import type {
+  WorkspaceBinding,
+  WorkspaceExecutionEvidence,
+  WorkspaceProvider,
+} from "./workspaces/index.ts";
 
 export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION = 1 as const;
@@ -170,6 +175,8 @@ export interface WorkflowProof {
   agents: WorkflowAgentProof[];
   evidence: WorkflowEvidenceRecord[];
   policy?: WorkflowPolicyProof;
+  /** Immutable terminal provider evidence for isolated execution. */
+  execution?: WorkspaceExecutionEvidence;
   repository: WorkflowRepoEvidence;
   harnesses: HarnessEvidenceCoverage[];
   unknowns: WorkflowProofUnknown[];
@@ -438,6 +445,11 @@ export interface EngineOpts {
   isolation?: PolicyIsolation;
   /** Network state of spawned harness subprocesses (default unknown). */
   networkAccess?: PolicyNetworkAccess;
+  /** Explicit provider and host-owned roots. Omit for shared or declaration-only execution. */
+  workspace?: {
+    provider: WorkspaceProvider;
+    writableRoots: readonly string[];
+  };
 }
 
 export interface RunReport {
@@ -462,4 +474,6 @@ export interface RunReport {
   billing: Array<{ harness: HarnessName; mode: BillingMode }>;
   /** Policy verdict totals when the host supplied a policy. */
   policy?: WorkflowPolicyProof["summary"];
+  /** Isolated workspace binding when this run requested a provider capability. */
+  workspaceBinding?: WorkspaceBinding;
 }

package/src/core/workflow/workspaces/attestation-error.ts

@@ -0,0 +1,30 @@
+import type { WorkspaceAttestation, WorkspaceBinding } from "./types.ts";
+import { isWorkspaceAttestation } from "./validate.ts";
+
+export class WorkspaceAttestationError extends Error {
+  readonly attestation: WorkspaceAttestation;
+
+  constructor(message: string, attestation: WorkspaceAttestation) {
+    super(message);
+    this.name = "WorkspaceAttestationError";
+    this.attestation = attestation;
+  }
+}
+
+export function workspaceAttestationFromError(
+  error: unknown,
+  binding: WorkspaceBinding,
+): WorkspaceAttestation | undefined {
+  const seen = new Set<unknown>();
+  let current = error;
+  while (current !== undefined && current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (isWorkspaceAttestation(current, binding)) return current;
+    if (typeof current !== "object") return undefined;
+    if ("attestation" in current && isWorkspaceAttestation(current.attestation, binding)) {
+      return current.attestation;
+    }
+    current = "cause" in current ? current.cause : undefined;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,137 @@
+import {
+  acquireWorkEventLease,
+  readWorkItemIgnoringLease,
+  type WorkEvent,
+} from "../../work/state.ts";
+import { readWorkflowRunManifest } from "../run-state.ts";
+import {
+  appendWorkflowJournalEvent,
+  readWorkflowSupplement,
+  stableDigest,
+  writeWorkflowSupplement,
+} from "./state.ts";
+import type {
+  WorkspaceBinding,
+  WorkspaceCancellationReceipt,
+  WorkspaceCancellationResult,
+  WorkspaceProvider,
+} from "./types.ts";
+import { isWorkspaceAttestation } from "./validate.ts";
+
+export interface CancelWorkspaceInput {
+  coordRoot: string;
+  runId: string;
+  provider: WorkspaceProvider;
+}
+
+export async function cancelWorkspace(
+  input: CancelWorkspaceInput,
+): Promise<WorkspaceCancellationReceipt> {
+  const manifest = readWorkflowRunManifest(input.coordRoot, input.runId);
+  const binding = manifest.execution.workspace_binding;
+  if (binding?.owner.kind !== "work_attempt") {
+    throw new Error("workspace cancellation requires a work-linked isolated binding");
+  }
+  const release = acquireWorkEventLease(input.coordRoot, binding.owner.work_item_id);
+  try {
+    const cancellation = currentWorkCancellation(input.coordRoot, binding);
+    const bindingSha256 = stableDigest(binding);
+    const eventSha256 = stableDigest(cancellation);
+    const prior = readWorkflowSupplement<WorkspaceCancellationReceipt>(
+      input.coordRoot,
+      input.runId,
+      "cancellation/outcome.json",
+    );
+    if (prior) {
+      validateCancellationReceipt(prior, binding, cancellation);
+      return prior;
+    }
+
+    const providerBinding = await input.provider.readBinding(binding);
+    if (stableDigest(providerBinding) !== bindingSha256) {
+      throw new Error("workspace cancellation provider binding differs from the frozen manifest");
+    }
+    const result = await input.provider.cancel(binding);
+    validateCancellationResult(result, binding);
+    const receipt: WorkspaceCancellationReceipt = {
+      schema_version: 1,
+      receipt_id: `cancellation-${stableDigest({
+        binding: bindingSha256,
+        event: eventSha256,
+        result,
+      }).slice(0, 24)}`,
+      run_id: input.runId,
+      binding_id: binding.binding_id,
+      binding_sha256: bindingSha256,
+      work_item_id: binding.owner.work_item_id,
+      work_event_seq: cancellation.seq,
+      work_event_sha256: eventSha256,
+      status: result.status,
+      recorded_at: result.recorded_at,
+      attestation: result.attestation,
+      reason: result.reason,
+    };
+    writeWorkflowSupplement(input.coordRoot, input.runId, "cancellation/outcome.json", receipt);
+    appendWorkflowJournalEvent(input.coordRoot, input.runId, "workspace.cancel", {
+      binding_id: binding.binding_id,
+      provider_id: binding.provider.id,
+      receipt_id: receipt.receipt_id,
+      work_event_seq: cancellation.seq,
+      work_event_sha256: eventSha256,
+      status: receipt.status,
+    });
+    return receipt;
+  } finally {
+    release();
+  }
+}
+
+function currentWorkCancellation(coordRoot: string, binding: WorkspaceBinding): WorkEvent {
+  if (binding.owner.kind !== "work_attempt") {
+    throw new Error("workspace cancellation requires a work attempt owner");
+  }
+  const work = readWorkItemIgnoringLease(coordRoot, binding.owner.work_item_id);
+  const governance = [...work.events]
+    .reverse()
+    .find((event) => ["work.accepted", "work.cancelled", "work.reopened"].includes(event.event));
+  if (work.projection.state !== "cancelled" || governance?.event !== "work.cancelled") {
+    throw new Error("workspace cancellation requires the current host work cancellation");
+  }
+  return governance;
+}
+
+function validateCancellationResult(
+  result: WorkspaceCancellationResult,
+  binding: WorkspaceBinding,
+): void {
+  if (
+    result.schema_version !== 1 ||
+    result.binding_id !== binding.binding_id ||
+    !["cancelled", "unsupported", "preserved_dirty", "blocked"].includes(result.status) ||
+    !Number.isFinite(Date.parse(result.recorded_at)) ||
+    !isWorkspaceAttestation(result.attestation, binding)
+  ) {
+    throw new Error("workspace cancellation provider returned an invalid result");
+  }
+}
+
+function validateCancellationReceipt(
+  receipt: WorkspaceCancellationReceipt,
+  binding: WorkspaceBinding,
+  cancellation: WorkEvent,
+): void {
+  if (
+    receipt.schema_version !== 1 ||
+    receipt.run_id !== binding.run_id ||
+    receipt.binding_id !== binding.binding_id ||
+    receipt.binding_sha256 !== stableDigest(binding) ||
+    receipt.work_item_id !== binding.owner.work_item_id ||
+    receipt.work_event_seq !== cancellation.seq ||
+    receipt.work_event_sha256 !== stableDigest(cancellation) ||
+    !["cancelled", "unsupported", "preserved_dirty", "blocked"].includes(receipt.status) ||
+    !Number.isFinite(Date.parse(receipt.recorded_at)) ||
+    !isWorkspaceAttestation(receipt.attestation, binding)
+  ) {
+    throw new Error("workspace cancellation outcome does not match current host authority");
+  }
+}

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

@@ -0,0 +1,308 @@
+import { join } from "node:path";
+import { readWorkflowProof } from "../proof.ts";
+import { readWorkflowRunManifest } from "../run-state.ts";
+import { acquireNoClobberLease } from "./leases.ts";
+import { containsPath } from "./paths.ts";
+import {
+  appendCleanupAttempt,
+  appendWorkflowJournalEvent,
+  readCleanupAttempts,
+  readWorkflowSupplement,
+  stableDigest,
+  workflowRunDir,
+  writeWorkflowSupplement,
+} from "./state.ts";
+import type {
+  WorkspaceBinding,
+  WorkspaceCleanupAttempt,
+  WorkspaceCleanupIntent,
+  WorkspaceCleanupMode,
+  WorkspaceCleanupReceipt,
+  WorkspaceCleanupResult,
+  WorkspaceProvider,
+} from "./types.ts";
+import { isWorkspaceAttestation, isWorkspaceBoundExecutionEvidence } from "./validate.ts";
+
+const CLEANUP_LEASE_STALE_MS = 5 * 60 * 1_000;
+
+export interface CleanupWorkspaceInput {
+  coordRoot: string;
+  runId: string;
+  provider: WorkspaceProvider;
+  mode?: WorkspaceCleanupMode;
+}
+
+export async function cleanupWorkspace(
+  input: CleanupWorkspaceInput,
+): Promise<WorkspaceCleanupAttempt | WorkspaceCleanupReceipt> {
+  const release = acquireCleanupLease(input.coordRoot, input.runId);
+  try {
+    return await cleanupWorkspaceUnderLease(input);
+  } finally {
+    release();
+  }
+}
+
+async function cleanupWorkspaceUnderLease(
+  input: CleanupWorkspaceInput,
+): Promise<WorkspaceCleanupAttempt | WorkspaceCleanupReceipt> {
+  const manifest = readWorkflowRunManifest(input.coordRoot, input.runId);
+  const proof = readWorkflowProof(input.coordRoot, input.runId);
+  const binding = manifest.execution.workspace_binding;
+  if (
+    !binding ||
+    !isWorkspaceBoundExecutionEvidence(proof.execution, input.runId) ||
+    stableDigest(binding) !== stableDigest(proof.execution.binding)
+  ) {
+    throw new Error("workspace cleanup requires matching terminal execution evidence");
+  }
+  assertCleanupPathAuthority(binding, manifest.execution.policy?.allowed_paths ?? []);
+
+  const mode = input.mode ?? "normal";
+  const current = await input.provider.attest(binding);
+  if (!isWorkspaceAttestation(current, binding)) {
+    throw new Error("workspace cleanup provider returned an invalid current attestation");
+  }
+  const intent = resolveCleanupIntent(input, binding, current, mode);
+  for (const attempt of readCleanupAttempts(input.coordRoot, input.runId)) {
+    if (
+      attempt.operation_id !== intent.operation_id ||
+      attempt.binding_id !== binding.binding_id ||
+      attempt.binding_sha256 !== intent.binding_sha256 ||
+      attempt.mode !== intent.mode ||
+      (attempt.attestation !== undefined && !isWorkspaceAttestation(attempt.attestation, binding))
+    ) {
+      throw new Error("workspace cleanup attempt does not match the immutable intent");
+    }
+  }
+
+  const receipt = readWorkflowSupplement<WorkspaceCleanupReceipt>(
+    input.coordRoot,
+    input.runId,
+    "cleanup/receipt.json",
+  );
+  if (receipt) {
+    validateCleanupReceipt(receipt, binding, intent);
+    if (!isReleasedAttestation(current)) {
+      throw new Error("existing cleanup receipt no longer reattests exact resource absence");
+    }
+    return receipt;
+  }
+
+  appendCleanupAttempt(input.coordRoot, input.runId, {
+    schema_version: 1,
+    operation_id: intent.operation_id,
+    binding_id: binding.binding_id,
+    binding_sha256: intent.binding_sha256,
+    mode,
+    status: "started",
+    recorded_at: new Date().toISOString(),
+  });
+  const result = await input.provider.cleanup(binding, intent);
+  validateCleanupResult(result, binding);
+  const attempt = appendCleanupAttempt(input.coordRoot, input.runId, {
+    schema_version: 1,
+    operation_id: intent.operation_id,
+    binding_id: binding.binding_id,
+    binding_sha256: intent.binding_sha256,
+    mode,
+    status: result.status,
+    branch_deleted: result.branch_deleted,
+    attestation: result.attestation,
+    reason: result.reason,
+    recorded_at: result.recorded_at,
+  });
+  appendWorkflowJournalEvent(input.coordRoot, input.runId, "workspace.cleanup", {
+    binding_id: binding.binding_id,
+    provider_id: binding.provider.id,
+    operation_id: intent.operation_id,
+    attempt: attempt.seq,
+    status: attempt.status,
+  });
+  if (result.status !== "released" && result.status !== "already_released") {
+    return attempt;
+  }
+  if (!result.branch_deleted || !isReleasedAttestation(result.attestation)) {
+    throw new Error("workspace cleanup cannot receipt an incomplete resource release");
+  }
+  const terminal: WorkspaceCleanupReceipt = {
+    schema_version: 1,
+    receipt_id: `cleanup-${stableDigest({
+      operation: intent.operation_id,
+      binding: intent.binding_sha256,
+    }).slice(0, 24)}`,
+    operation_id: intent.operation_id,
+    binding_id: binding.binding_id,
+    binding_sha256: intent.binding_sha256,
+    mode,
+    status: result.status,
+    branch_deleted: true,
+    attestation: result.attestation,
+    recorded_at: result.recorded_at,
+  };
+  writeWorkflowSupplement(input.coordRoot, input.runId, "cleanup/receipt.json", terminal);
+  return terminal;
+}
+
+function assertCleanupPathAuthority(
+  binding: WorkspaceBinding,
+  allowedPaths: readonly string[],
+): void {
+  if (
+    allowedPaths.length > 0 &&
+    (!allowedPaths.some((root) => containsPath(root, binding.workspace_root)) ||
+      !allowedPaths.some((root) => containsPath(root, binding.active_root)) ||
+      (binding.repository !== undefined &&
+        (!allowedPaths.some((root) =>
+          containsPath(root, binding.repository!.source_root.realpath),
+        ) ||
+          !allowedPaths.some((root) =>
+            containsPath(root, binding.repository!.common_dir.realpath),
+          ))))
+  ) {
+    throw new Error("workspace cleanup path is outside frozen policy path authority");
+  }
+  if (
+    !containsPath(binding.writable_root.realpath, binding.workspace_root) ||
+    !containsPath(binding.writable_root.realpath, binding.active_root)
+  ) {
+    throw new Error("workspace cleanup path is outside frozen writable-root authority");
+  }
+}
+
+function acquireCleanupLease(coordRoot: string, runId: string): () => void {
+  const authoritySha256 = stableDigest({ run_id: runId, operation: "cleanup" });
+  const lease = acquireNoClobberLease({
+    path: join(workflowRunDir(coordRoot, runId), "cleanup", "operation.lease"),
+    scope: "cleanup",
+    authoritySha256,
+    staleAfterMs: CLEANUP_LEASE_STALE_MS,
+    metadata: { run_id: runId },
+    validateStaleOwner: (owner) =>
+      owner.authority_sha256 === authoritySha256 && owner.metadata?.run_id === runId,
+  });
+  return () => lease.release();
+}
+
+function resolveCleanupIntent(
+  input: CleanupWorkspaceInput,
+  binding: WorkspaceBinding,
+  attestation: WorkspaceCleanupResult["attestation"],
+  mode: WorkspaceCleanupMode,
+): WorkspaceCleanupIntent {
+  if (!binding.repository) throw new Error("workspace cleanup requires repository identity");
+  const bindingSha256 = stableDigest(binding);
+  const operationId = `cleanup-${stableDigest({ binding: bindingSha256, mode }).slice(0, 24)}`;
+  const prior = readWorkflowSupplement<WorkspaceCleanupIntent>(
+    input.coordRoot,
+    input.runId,
+    "cleanup/intent.json",
+  );
+  if (prior) {
+    if (
+      prior.schema_version !== 1 ||
+      prior.run_id !== input.runId ||
+      prior.binding_id !== binding.binding_id ||
+      prior.binding_sha256 !== bindingSha256 ||
+      prior.mode !== mode ||
+      prior.operation_id !== operationId
+    ) {
+      throw new Error("existing cleanup intent does not match current workspace authority");
+    }
+    validateCleanupIntentExpected(prior, binding);
+    return prior;
+  }
+  const workspaceRefOid = attestation.repository?.workspace_ref_oid;
+  const targetRefOid = attestation.repository?.target_ref_oid;
+  if (!workspaceRefOid || !targetRefOid) {
+    throw new Error("workspace cleanup cannot freeze exact source and target ref identities");
+  }
+  const proposed: WorkspaceCleanupIntent = {
+    schema_version: 1,
+    run_id: input.runId,
+    operation_id: operationId,
+    binding_id: binding.binding_id,
+    binding_sha256: bindingSha256,
+    mode,
+    expected: {
+      worktree_path: binding.workspace_root,
+      gitdir: binding.repository.gitdir,
+      workspace_ref: binding.repository.workspace_ref,
+      workspace_ref_oid: workspaceRefOid,
+      target_ref: binding.repository.target_ref,
+      target_ref_oid: targetRefOid,
+    },
+    created_at: new Date().toISOString(),
+  };
+  writeWorkflowSupplement(input.coordRoot, input.runId, "cleanup/intent.json", proposed);
+  return proposed;
+}
+
+function validateCleanupIntentExpected(
+  intent: WorkspaceCleanupIntent,
+  binding: WorkspaceBinding,
+): void {
+  const repository = binding.repository;
+  if (
+    !repository ||
+    intent.expected.worktree_path !== binding.workspace_root ||
+    stableDigest(intent.expected.gitdir) !== stableDigest(repository.gitdir) ||
+    intent.expected.workspace_ref !== repository.workspace_ref ||
+    intent.expected.target_ref !== repository.target_ref ||
+    !/^[0-9a-f]{40,64}$/.test(intent.expected.workspace_ref_oid) ||
+    !/^[0-9a-f]{40,64}$/.test(intent.expected.target_ref_oid)
+  ) {
+    throw new Error("cleanup intent expected identities do not match the workspace binding");
+  }
+}
+
+function validateCleanupResult(result: WorkspaceCleanupResult, binding: WorkspaceBinding): void {
+  if (
+    result.schema_version !== 1 ||
+    result.binding_id !== binding.binding_id ||
+    ![
+      "released",
+      "already_released",
+      "preserved_dirty",
+      "blocked",
+      "unsupported",
+      "partial",
+    ].includes(result.status) ||
+    !Number.isFinite(Date.parse(result.recorded_at)) ||
+    typeof result.branch_deleted !== "boolean" ||
+    !isWorkspaceAttestation(result.attestation, binding) ||
+    ((result.status === "released" || result.status === "already_released") &&
+      !isReleasedAttestation(result.attestation))
+  ) {
+    throw new Error("workspace cleanup provider returned an invalid result");
+  }
+}
+
+function validateCleanupReceipt(
+  receipt: WorkspaceCleanupReceipt,
+  binding: WorkspaceBinding,
+  intent: WorkspaceCleanupIntent,
+): void {
+  if (
+    receipt.schema_version !== 1 ||
+    receipt.operation_id !== intent.operation_id ||
+    receipt.binding_id !== binding.binding_id ||
+    receipt.binding_sha256 !== intent.binding_sha256 ||
+    receipt.mode !== intent.mode ||
+    (receipt.status !== "released" && receipt.status !== "already_released") ||
+    receipt.branch_deleted !== true ||
+    !isWorkspaceAttestation(receipt.attestation, binding) ||
+    !isReleasedAttestation(receipt.attestation)
+  ) {
+    throw new Error("workspace cleanup receipt is invalid or mismatched");
+  }
+}
+
+function isReleasedAttestation(attestation: WorkspaceCleanupResult["attestation"]): boolean {
+  return (
+    attestation.status === "ok" &&
+    attestation.provider_drift.length === 0 &&
+    attestation.resource_state === "released" &&
+    !attestation.workspace_exists
+  );
+}