harnery 0.22.1 → 0.24.0

package/dist/core/workflow/workspaces/git.js

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+const MAX_GIT_OUTPUT = 8 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 30_000;
+export function git(cwd, args) {
+    const result = gitMaybe(cwd, args);
+    if (!result.ok)
+        throw new Error(result.err || `git ${args.join(" ")} failed`);
+    return result.out;
+}
+export function gitMaybe(cwd, args) {
+    return runGit(cwd, args);
+}
+export function gitMaybeWithDirectoryDescriptor(cwd, args, fd) {
+    const stdio = ["ignore", "pipe", "pipe"];
+    while (stdio.length <= fd)
+        stdio.push("ignore");
+    stdio[fd] = fd;
+    return runGit(cwd, args, stdio);
+}
+export function worktreeInventory(cwd) {
+    return parseWorktreeInventory(git(cwd, ["worktree", "list", "--porcelain"]));
+}
+export function parseWorktreeInventory(body) {
+    const entries = [];
+    let current;
+    const fields = body.includes("\0") ? body.split("\0") : body.split("\n");
+    for (const field of fields) {
+        if (field.startsWith("worktree ")) {
+            if (current)
+                entries.push(current);
+            current = { path: field.slice("worktree ".length) };
+        }
+        else if (current && field.startsWith("HEAD ")) {
+            current.head = field.slice("HEAD ".length);
+        }
+        else if (current && field.startsWith("branch ")) {
+            current.ref = field.slice("branch ".length);
+        }
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+export function gitOperations(cwd) {
+    const gitDir = realpathSync(resolve(cwd, git(cwd, ["rev-parse", "--git-dir"])));
+    const candidates = [
+        ["MERGE_HEAD", "merge"],
+        ["CHERRY_PICK_HEAD", "cherry-pick"],
+        ["REVERT_HEAD", "revert"],
+        ["BISECT_LOG", "bisect"],
+        ["rebase-merge", "rebase"],
+        ["rebase-apply", "rebase"],
+    ];
+    return [
+        ...new Set(candidates.filter(([entry]) => existsSync(join(gitDir, entry))).map(([, name]) => name)),
+    ];
+}
+export function overwriteRiskPaths(cwd, changed) {
+    const untracked = nulEntries(git(cwd, ["ls-files", "-z", "--others", "--exclude-standard"]));
+    const ignored = nulEntries(git(cwd, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard"]));
+    const candidates = new Set([...untracked, ...ignored]);
+    return changed.filter((path) => candidates.has(path));
+}
+export function isAncestor(cwd, ancestor, descendant) {
+    return gitMaybe(cwd, ["merge-base", "--is-ancestor", ancestor, descendant]).ok;
+}
+export function nulEntries(value) {
+    return value.split("\0").filter(Boolean);
+}
+function runGit(cwd, args, stdio) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        env: isolatedGitEnvironment(),
+        maxBuffer: MAX_GIT_OUTPUT,
+        timeout: GIT_TIMEOUT_MS,
+        stdio,
+    });
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            err: (result.stderr || result.stdout || result.error?.message || "git failed").trim(),
+        };
+    }
+    return { ok: true, out: result.stdout.replace(/\n$/, "") };
+}
+function isolatedGitEnvironment() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.startsWith("GIT_"))
+            delete env[key];
+    }
+    env.GIT_TERMINAL_PROMPT = "0";
+    env.GIT_CONFIG_NOSYSTEM = "1";
+    env.GCM_INTERACTIVE = "Never";
+    env.GIT_CONFIG_COUNT = "1";
+    env.GIT_CONFIG_KEY_0 = "core.hooksPath";
+    env.GIT_CONFIG_VALUE_0 = process.platform === "win32" ? "NUL" : "/dev/null";
+    return env;
+}

package/dist/core/workflow/workspaces/index.d.ts

@@ -0,0 +1,15 @@
+export type { CancelWorkspaceInput } from "./cancellation.js";
+export { cancelWorkspace } from "./cancellation.js";
+export type { CleanupWorkspaceInput } from "./cleanup.js";
+export { cleanupWorkspace } from "./cleanup.js";
+export type { WorkflowWorkspaceInspection, WorkflowWorkspaceSelection, WorkflowWorkspaceStatus, WorkflowWorkspaceVerification, } from "./inspect.js";
+export { inspectWorkflowWorkspace, listWorkflowWorkspaceInspections, readWorkflowWorkspaceStatus, renderWorkflowWorkspaceStatus, } from "./inspect.js";
+export type { ApplyIntegrationInput, PrepareIntegrationInput } from "./integration.js";
+export { applyIntegration, IntegrationPrepareParkedError, prepareIntegration, } from "./integration.js";
+export type { WorkspaceLifecycleProjection, WorkspaceLifecycleProjectionInput, } from "./lifecycle.js";
+export { assertWorkspaceLifecycleTransition, deriveWorkspaceLifecycle, isWorkspaceLifecycleState, validateProviderEventChain, } from "./lifecycle.js";
+export type { LocalGitWorktreeProviderOptions } from "./local-git.js";
+export { createLocalGitWorktreeProvider, probe as probeLocalGitWorktreeProvider, } from "./local-git.js";
+export type { AuthorizedIntegrationPlan, AuthorizedProviderIntegrationInput, FilesystemIdentity, GitRepositoryBinding, IntegrationApplyAttempt, IntegrationApplyReceipt, IntegrationAuthorization, IntegrationPlan, IntegrationReviewRecord, IntegrationTarget, ProviderIntegrationInput, ProviderIntegrationPreview, ProviderIntegrationResult, ProviderUnknown, ProviderUnsupportedReason, RepositoryBinding, RepositoryObservation, ValidatedFilesystemPath, ValidatedFilesystemRoot, WorkspaceAllocationRequest, WorkspaceAttestation, WorkspaceBinding, WorkspaceBoundExecutionEvidence, WorkspaceCancellationReceipt, WorkspaceCancellationResult, WorkspaceCleanupAttempt, WorkspaceCleanupIntent, WorkspaceCleanupMode, WorkspaceCleanupReceipt, WorkspaceCleanupResult, WorkspaceCompatibilityExecutionEvidence, WorkspaceExecutionEvidence, WorkspaceIntegrationState, WorkspaceIsolation, WorkspaceLifecycleState, WorkspaceObservation, WorkspaceOwner, WorkspaceProbeInput, WorkspaceProbeResult, WorkspaceProofLifecycleState, WorkspaceProofOutcome, WorkspaceProvider, WorkspaceProviderCapabilities, WorkspaceProviderRef, WorkspaceResourceState, WorkspaceUnsupportedExecutionEvidence, } from "./types.js";
+export { WORKSPACE_BINDING_SCHEMA_VERSION, WORKSPACE_RECEIPT_SCHEMA_VERSION, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/workflow/workspaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,2BAA2B,EAC3B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EACL,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,4BAA4B,EAC5B,iCAAiC,GAClC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,8BAA8B,EAC9B,KAAK,IAAI,6BAA6B,GACvC,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,yBAAyB,EACzB,kCAAkC,EAClC,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,eAAe,EACf,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,oBAAoB,EACpB,gBAAgB,EAChB,+BAA+B,EAC/B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,uCAAuC,EACvC,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,iBAAiB,EACjB,6BAA6B,EAC7B,oBAAoB,EACpB,sBAAsB,EACtB,qCAAqC,GACtC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gCAAgC,EAChC,gCAAgC,GACjC,MAAM,YAAY,CAAC"}

package/dist/core/workflow/workspaces/index.js

@@ -0,0 +1,7 @@
+export { cancelWorkspace } from "./cancellation.js";
+export { cleanupWorkspace } from "./cleanup.js";
+export { inspectWorkflowWorkspace, listWorkflowWorkspaceInspections, readWorkflowWorkspaceStatus, renderWorkflowWorkspaceStatus, } from "./inspect.js";
+export { applyIntegration, IntegrationPrepareParkedError, prepareIntegration, } from "./integration.js";
+export { assertWorkspaceLifecycleTransition, deriveWorkspaceLifecycle, isWorkspaceLifecycleState, validateProviderEventChain, } from "./lifecycle.js";
+export { createLocalGitWorktreeProvider, probe as probeLocalGitWorktreeProvider, } from "./local-git.js";
+export { WORKSPACE_BINDING_SCHEMA_VERSION, WORKSPACE_RECEIPT_SCHEMA_VERSION, } from "./types.js";

package/dist/core/workflow/workspaces/inspect.d.ts

@@ -0,0 +1,85 @@
+import type { WorkflowProof } from "../types.js";
+import { type WorkspaceLifecycleProjection } from "./lifecycle.js";
+import type { WorkspaceCompatibilityExecutionEvidence, WorkspaceIsolation, WorkspaceProviderRef } from "./types.js";
+export type WorkflowWorkspaceSelection = "shared" | "compatibility" | "isolated";
+export type WorkflowWorkspaceVerification = "not_applicable" | "pending" | "ok" | "blocked" | "lost";
+export interface WorkflowWorkspaceStatus {
+    schema_version: 1;
+    run_id: string;
+    run_name: string;
+    work_item_id?: string;
+    started_at: string;
+    selection: WorkflowWorkspaceSelection;
+    requested_isolation: "shared" | WorkspaceIsolation;
+    effective_isolation: "shared" | WorkspaceIsolation;
+    provider?: WorkspaceProviderRef;
+    compatibility?: {
+        reason: WorkspaceCompatibilityExecutionEvidence["selection_reason"];
+        unsupported: WorkspaceCompatibilityExecutionEvidence["unsupported"];
+        unknowns: WorkspaceCompatibilityExecutionEvidence["unknowns"];
+    };
+    allocation?: {
+        binding_id: string;
+        workspace_id: string;
+        workspace_root: string;
+        active_root: string;
+        created_at: string;
+    };
+    lifecycle: WorkspaceLifecycleProjection;
+    verification: {
+        status: WorkflowWorkspaceVerification;
+        workflow_status?: WorkflowProof["run"]["status"];
+        attested_at?: string;
+        drift: string[];
+        unsupported: Array<{
+            code: string;
+            message: string;
+        }>;
+        unknowns: Array<{
+            code: string;
+            message: string;
+        }>;
+    };
+    integration: {
+        state: WorkspaceLifecycleProjection["integration_state"];
+        changed_paths: string[];
+        target_ref?: string;
+        target_commit?: string;
+        receipt_id?: string;
+    };
+    cleanup: {
+        state: "not_requested" | "pending" | "released" | "preserved_dirty" | "blocked";
+        attempts: number;
+        reason?: string;
+        receipt_id?: string;
+    };
+    repository: {
+        dirty_paths: string[];
+        conflicts: string[];
+        operations_in_progress: string[];
+    };
+    integrity: {
+        status: "verified";
+        proof_sha256?: string;
+        provider_event_chain_sha256: string | null;
+    };
+}
+export type WorkflowWorkspaceInspection = {
+    ok: true;
+    value: WorkflowWorkspaceStatus;
+} | {
+    ok: false;
+    run_id: string;
+    error: string;
+};
+/**
+ * Read one workflow's workspace state from validated durable authority.
+ *
+ * Corrupt, contradictory, or foreign records throw instead of being projected
+ * as healthy. Use inspectWorkflowWorkspace when a UI needs a typed error row.
+ */
+export declare function readWorkflowWorkspaceStatus(coordRoot: string, runId: string): WorkflowWorkspaceStatus;
+export declare function inspectWorkflowWorkspace(coordRoot: string, runId: string): WorkflowWorkspaceInspection;
+export declare function listWorkflowWorkspaceInspections(coordRoot: string): WorkflowWorkspaceInspection[];
+export declare function renderWorkflowWorkspaceStatus(status: WorkflowWorkspaceStatus): string;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/core/workflow/workspaces/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/inspect.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow/workspaces/inspect.js

@@ -0,0 +1,255 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readWorkItem } from "../../work/state.js";
+import { readWorkflowProof } from "../proof.js";
+import { readWorkflowRunManifest } from "../run-state.js";
+import { deriveWorkspaceLifecycle } from "./lifecycle.js";
+import { fileSha256, readCleanupAttempts, readIntegrationAttempts, readWorkflowSupplement, readWorkspaceEvents, workflowRunDir, } from "./state.js";
+import { isWorkspaceBoundExecutionEvidence } from "./validate.js";
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+/**
+ * Read one workflow's workspace state from validated durable authority.
+ *
+ * Corrupt, contradictory, or foreign records throw instead of being projected
+ * as healthy. Use inspectWorkflowWorkspace when a UI needs a typed error row.
+ */
+export function readWorkflowWorkspaceStatus(coordRoot, runId) {
+    assertRunId(runId);
+    const root = resolve(coordRoot);
+    const runDir = workflowRunDir(root, runId);
+    const manifest = readWorkflowRunManifest(root, runId);
+    const journal = readWorkspaceJournal(runDir, runId);
+    const proofPath = join(runDir, "proof.json");
+    const proof = existsSync(proofPath) ? readWorkflowProof(root, runId) : undefined;
+    const proofSha256 = proof ? fileSha256(proofPath) : undefined;
+    const binding = manifest.execution.workspace_binding;
+    const fallback = manifest.execution.workspace_fallback;
+    if (!binding) {
+        const lifecycle = deriveWorkspaceLifecycle({
+            manifest,
+            workflow_journal: journal,
+            proof,
+            proof_sha256: proofSha256,
+            allocation_unsupported: fallback !== undefined,
+        });
+        return {
+            schema_version: 1,
+            run_id: runId,
+            run_name: manifest.name,
+            work_item_id: manifest.work_item_id,
+            started_at: manifest.started_at,
+            selection: fallback ? "compatibility" : "shared",
+            requested_isolation: manifest.execution.isolation,
+            effective_isolation: "shared",
+            provider: fallback?.provider,
+            compatibility: fallback
+                ? {
+                    reason: fallback.selection_reason,
+                    unsupported: [...fallback.unsupported],
+                    unknowns: [...fallback.unknowns],
+                }
+                : undefined,
+            lifecycle,
+            verification: {
+                status: "not_applicable",
+                workflow_status: proof?.run.status,
+                drift: [...(fallback?.drift ?? [])],
+                unsupported: [...(fallback?.unsupported ?? [])],
+                unknowns: [...(fallback?.unknowns ?? [])],
+            },
+            integration: { state: "none", changed_paths: [] },
+            cleanup: { state: "not_requested", attempts: 0 },
+            repository: { dirty_paths: [], conflicts: [], operations_in_progress: [] },
+            integrity: {
+                status: "verified",
+                proof_sha256: proofSha256,
+                provider_event_chain_sha256: null,
+            },
+        };
+    }
+    const providerEvents = readWorkspaceEvents(root, binding.provider.id, binding.binding_id);
+    const integrationPlan = readWorkflowSupplement(root, runId, "integration/plan.json");
+    const integrationAuthorization = readWorkflowSupplement(root, runId, "integration/authorization.json");
+    const integrationAttempts = readIntegrationAttempts(root, runId);
+    const integrationReceipt = readWorkflowSupplement(root, runId, "integration/receipt.json");
+    const cleanupIntent = readWorkflowSupplement(root, runId, "cleanup/intent.json");
+    const cleanupAttempts = readCleanupAttempts(root, runId);
+    const cleanupReceipt = readWorkflowSupplement(root, runId, "cleanup/receipt.json");
+    const cancellationReceipt = readWorkflowSupplement(root, runId, "cancellation/outcome.json");
+    const workEvents = binding.owner.kind === "work_attempt"
+        ? readWorkItem(root, binding.owner.work_item_id).events
+        : undefined;
+    const lifecycle = deriveWorkspaceLifecycle({
+        binding,
+        provider_events: providerEvents,
+        manifest,
+        workflow_journal: journal,
+        proof,
+        proof_sha256: proofSha256,
+        integration_plan: integrationPlan,
+        integration_authorization: integrationAuthorization,
+        integration_attempts: integrationAttempts,
+        integration_receipt: integrationReceipt,
+        cleanup_intent: cleanupIntent,
+        cleanup_attempts: cleanupAttempts,
+        cleanup_receipt: cleanupReceipt,
+        work_events: workEvents,
+        cancellation_receipt: cancellationReceipt,
+    });
+    const latestCleanup = cleanupAttempts.at(-1);
+    const attestation = latestAttestation(proof, latestCleanup?.attestation, cleanupReceipt);
+    return {
+        schema_version: 1,
+        run_id: runId,
+        run_name: manifest.name,
+        work_item_id: manifest.work_item_id,
+        started_at: manifest.started_at,
+        selection: "isolated",
+        requested_isolation: manifest.execution.isolation,
+        effective_isolation: binding.isolation,
+        provider: binding.provider,
+        allocation: {
+            binding_id: binding.binding_id,
+            workspace_id: binding.workspace_id,
+            workspace_root: binding.workspace_root,
+            active_root: binding.active_root,
+            created_at: binding.created_at,
+        },
+        lifecycle,
+        verification: {
+            status: verificationStatus(proof, attestation),
+            workflow_status: proof?.run.status,
+            attested_at: attestation?.recorded_at,
+            drift: [...(attestation?.provider_drift ?? [])],
+            unsupported: [...(attestation?.unsupported ?? [])],
+            unknowns: [...(attestation?.unknowns ?? [])],
+        },
+        integration: {
+            state: lifecycle.integration_state,
+            changed_paths: [...(integrationPlan?.provider_preview.changed_paths ?? [])],
+            target_ref: integrationPlan?.provider_preview.target_ref,
+            target_commit: integrationReceipt?.target_commit ?? integrationPlan?.provider_preview.target_commit,
+            receipt_id: integrationReceipt?.receipt_id,
+        },
+        cleanup: {
+            state: cleanupState(cleanupIntent, latestCleanup?.status, cleanupReceipt),
+            attempts: cleanupAttempts.length,
+            reason: latestCleanup?.reason,
+            receipt_id: cleanupReceipt?.receipt_id,
+        },
+        repository: {
+            dirty_paths: [...(attestation?.repository?.dirty_paths ?? [])],
+            conflicts: [...(attestation?.repository?.conflicts ?? [])],
+            operations_in_progress: [...(attestation?.repository?.operation_in_progress ?? [])],
+        },
+        integrity: {
+            status: "verified",
+            proof_sha256: proofSha256,
+            provider_event_chain_sha256: lifecycle.provider_event_chain_sha256,
+        },
+    };
+}
+export function inspectWorkflowWorkspace(coordRoot, runId) {
+    try {
+        return { ok: true, value: readWorkflowWorkspaceStatus(coordRoot, runId) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            run_id: runId,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function listWorkflowWorkspaceInspections(coordRoot) {
+    const workflowsRoot = join(resolve(coordRoot), ".harnery", "workflows");
+    if (!existsSync(workflowsRoot))
+        return [];
+    return readdirSync(workflowsRoot)
+        .filter((runId) => RUN_ID.test(runId) && existsSync(join(workflowsRoot, runId, "run.json")))
+        .sort((a, b) => b.localeCompare(a))
+        .map((runId) => inspectWorkflowWorkspace(coordRoot, runId));
+}
+export function renderWorkflowWorkspaceStatus(status) {
+    const lines = [
+        `run ${status.run_id} (${status.run_name}): ${status.selection}`,
+        `isolation: requested ${status.requested_isolation}; effective ${status.effective_isolation}`,
+        `lifecycle: ${status.lifecycle.state}; resource ${status.lifecycle.resource_state ?? "not applicable"}; integration ${status.lifecycle.integration_state}; cancellation ${status.lifecycle.cancellation}`,
+    ];
+    if (status.provider) {
+        lines.push(`provider: ${status.provider.id}@${status.provider.version}`);
+    }
+    if (status.compatibility) {
+        lines.push(`compatibility: ${status.compatibility.reason}`);
+    }
+    if (status.allocation) {
+        lines.push(`binding: ${status.allocation.binding_id}; workspace ${status.allocation.workspace_id}`, `workspace root: ${status.allocation.workspace_root}`, `active root: ${status.allocation.active_root}`);
+    }
+    lines.push(`verification: ${status.verification.status}; workflow ${status.verification.workflow_status ?? "not terminal"}; ${status.verification.drift.length} drift; ${status.verification.unknowns.length} unknown`, `repository: ${status.repository.dirty_paths.length} dirty; ${status.repository.conflicts.length} conflict; ${status.repository.operations_in_progress.length} operation in progress`, `integration: ${status.integration.state}; ${status.integration.changed_paths.length} changed path`, `cleanup: ${status.cleanup.state}; ${status.cleanup.attempts} attempt`);
+    if (status.cleanup.reason)
+        lines.push(`cleanup reason: ${status.cleanup.reason}`);
+    return `${lines.join("\n")}\n`;
+}
+function readWorkspaceJournal(runDir, runId) {
+    const path = join(runDir, "journal.jsonl");
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line, index) => {
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`cannot parse workflow journal event ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (typeof record.event !== "string" ||
+            (record.run_id !== undefined && record.run_id !== runId)) {
+            throw new Error(`workflow journal event ${index + 1} is foreign or unsupported`);
+        }
+        return {
+            event: record.event,
+            ok: typeof record.ok === "boolean" ? record.ok : undefined,
+            status: journalStatus(record.status),
+            work_event_seq: typeof record.work_event_seq === "number" ? record.work_event_seq : undefined,
+            work_event_sha256: typeof record.work_event_sha256 === "string" ? record.work_event_sha256 : undefined,
+        };
+    });
+}
+function latestAttestation(proof, cleanupAttempt, cleanupReceipt) {
+    if (cleanupReceipt)
+        return cleanupReceipt.attestation;
+    if (cleanupAttempt)
+        return cleanupAttempt;
+    if (proof && isWorkspaceBoundExecutionEvidence(proof.execution, proof.run.id)) {
+        return proof.execution.terminal_attestation;
+    }
+    return undefined;
+}
+function verificationStatus(proof, attestation) {
+    if (!proof || !attestation)
+        return "pending";
+    return attestation.status;
+}
+function cleanupState(intent, attemptStatus, receipt) {
+    if (receipt)
+        return "released";
+    if (attemptStatus === "preserved_dirty")
+        return "preserved_dirty";
+    if (attemptStatus && ["blocked", "unsupported", "partial"].includes(attemptStatus)) {
+        return "blocked";
+    }
+    return intent || attemptStatus ? "pending" : "not_requested";
+}
+function journalStatus(value) {
+    return typeof value === "string" &&
+        ["blocked", "lost", "cancelled", "unsupported", "preserved_dirty"].includes(value)
+        ? value
+        : undefined;
+}
+function assertRunId(runId) {
+    if (!RUN_ID.test(runId))
+        throw new Error("workflow run id is invalid");
+}

package/dist/core/workflow/workspaces/integration.d.ts

@@ -0,0 +1,32 @@
+import { type NormalizedPolicy, type PolicySpec } from "../../policy/index.js";
+import type { IntegrationApplyReceipt, IntegrationPlan, WorkspaceProvider } from "./types.js";
+export interface PrepareIntegrationInput {
+    coordRoot: string;
+    runId: string;
+    provider: WorkspaceProvider;
+    policy: PolicySpec | NormalizedPolicy;
+    targetRoot?: string;
+    review?: {
+        actor: string;
+        reason?: string;
+    };
+    acceptedUnknowns?: readonly string[];
+    approvalAddressee?: string;
+}
+export interface ApplyIntegrationInput {
+    coordRoot: string;
+    runId: string;
+    provider: WorkspaceProvider;
+    plan?: IntegrationPlan;
+}
+/** Host-policy ASK still pending during integration prepare. Carries the exact
+ * durable IDs an operator needs to approve and resume the same plan. */
+export declare class IntegrationPrepareParkedError extends Error {
+    readonly runId: string;
+    readonly planId: string;
+    readonly approvalId: string;
+    constructor(runId: string, planId: string, approvalId: string);
+}
+export declare function prepareIntegration(input: PrepareIntegrationInput): Promise<IntegrationPlan>;
+export declare function applyIntegration(input: ApplyIntegrationInput): Promise<IntegrationApplyReceipt>;
+//# sourceMappingURL=integration.d.ts.map

package/dist/core/workflow/workspaces/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/integration.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,gBAAgB,EAGrB,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAgB/B,OAAO,KAAK,EAEV,uBAAuB,EAEvB,eAAe,EAOf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED;wEACwE;AACxE,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAO9D;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,eAAe,CAAC,CA2GjG;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAuNlC"}