harnery 0.22.0 → 0.23.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/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/validate.ts

@@ -111,7 +111,16 @@ export function validateAgainstSchema(value: unknown, schema: StageSchema, path
   }
 }
 
-/** Strip accidental markdown code fences, then strict-parse JSON. */
+/**
+ * Parse one schema-gated JSON value.
+ *
+ * Exact JSON and a whole fenced value remain the normal paths. Some harnesses
+ * prepend a short narration despite an explicit JSON-only contract. Accept
+ * that drift only when the reply contains exactly one unambiguous top-level
+ * object or array, the value reaches the end of the reply, and JSON.parse
+ * accepts it. Trailing prose, multiple values, and malformed candidates remain
+ * failures.
+ */
 export function parseStageOutput(text: string): { value?: unknown; error?: string } {
   const stripped = text
     .trim()
@@ -120,10 +129,75 @@ export function parseStageOutput(text: string): { value?: unknown; error?: strin
   try {
     return { value: JSON.parse(stripped) };
   } catch (err) {
+    const embedded = singleTrailingJsonContainer(stripped);
+    if (embedded !== undefined) return { value: embedded };
     return { error: `not valid JSON: ${(err as Error).message}` };
   }
 }
 
+function singleTrailingJsonContainer(text: string): unknown | undefined {
+  const candidates: Array<{ end: number; value: unknown }> = [];
+  let start = -1;
+  let stack: string[] = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]!;
+    if (start === -1) {
+      if (char === "{" || char === "[") {
+        start = index;
+        stack = [char];
+        inString = false;
+        escaped = false;
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char);
+      continue;
+    }
+    if (char !== "}" && char !== "]") continue;
+
+    const expectedOpen = char === "}" ? "{" : "[";
+    if (stack.at(-1) !== expectedOpen) {
+      start = -1;
+      stack = [];
+      continue;
+    }
+    stack.pop();
+    if (stack.length > 0) continue;
+
+    const end = index + 1;
+    try {
+      candidates.push({ end, value: JSON.parse(text.slice(start, end)) });
+    } catch {
+      // A balanced brace pair in narration is not a JSON candidate.
+    }
+    start = -1;
+  }
+
+  if (candidates.length !== 1 || text.slice(candidates[0]!.end).trim() !== "") {
+    return undefined;
+  }
+  return candidates[0]!.value;
+}
+
 function short(value: unknown): string {
   const s = JSON.stringify(value);
   return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;

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");
+  }
+}