harnery 0.29.0 → 0.31.0

package/src/core/workflow/types.ts

@@ -1,6 +1,6 @@
 /**
  * Workflow engine contracts. A workflow is a small throwaway JS script with
- * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * bounded, schema-gated stages that fan work out to headless adapter-CLI
  * subagents; the SCRIPT (deterministic code), not any model, decides routing
  * between stages, and the run always terminates when the script returns.
  *
@@ -28,7 +28,18 @@ export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION = 1 as const;
 
-export type EvidenceKind = "test" | "command" | "artifact" | "change" | "review" | "observation";
+/** The evidence vocabulary, as a value so the runtime validator and the
+ * pre-flight source scan cannot drift from the type or from each other. */
+export const EVIDENCE_KINDS = [
+  "test",
+  "command",
+  "artifact",
+  "change",
+  "review",
+  "observation",
+] as const;
+
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
 export type EvidenceStatus = "passed" | "failed" | "observed" | "unknown";
 export type EvidenceSource = "workflow" | "engine";
 export type AcceptanceStatus = "satisfied" | "unsatisfied" | "unknown";
@@ -90,7 +101,7 @@ export interface WorkflowAgentProof {
   label: string;
   stage?: string;
   specialist?: string;
-  harness: HarnessName;
+  adapter: AdapterName;
   model?: string;
   status: "succeeded" | "failed" | "cached";
   attempts: number;
@@ -99,6 +110,11 @@ export interface WorkflowAgentProof {
   session_id?: string;
   result?: ResultDigest;
   error?: string;
+  /** Set on a failed agent whose spawn was classified uninformative about the
+   * work (ADR 0046): environment (binary absent) or upstream (vendor refused).
+   * Absent ⇒ a work failure. Recorded even when a script's parallel() swallows
+   * the rejection, so the run-level class can still be derived from proof. */
+  class?: SpawnFailureClass;
 }
 
 export interface WorkflowRepoSnapshot {
@@ -126,16 +142,16 @@ export interface WorkflowRepoEvidence {
   };
 }
 
-/** Bounded pointer to the live attestation backing a harness's claims
+/** Bounded pointer to the live attestation backing a adapter's claims
  * (ADR 0038). Structural facts only: no prompt text, no host paths. */
-export interface HarnessAttestationCitation {
+export interface AdapterAttestationCitation {
   binary_version: string;
   observed_at: string;
   record_digest: string;
 }
 
-export interface HarnessEvidenceCoverage {
-  harness: HarnessName;
+export interface AdapterEvidenceCoverage {
+  adapter: AdapterName;
   tool_evidence: {
     support: "supported" | "partial" | "unsupported" | "unknown";
     note?: string;
@@ -145,10 +161,10 @@ export interface HarnessEvidenceCoverage {
     session_ids: number;
     costs: number;
   };
-  /** What backs this harness's capability claims (ADR 0038). Absent when the
+  /** What backs this adapter's capability claims (ADR 0038). Absent when the
    * host recorded no live attestation, which is the common case and is not by
    * itself a proof unknown. */
-  attestation?: HarnessAttestationCitation;
+  attestation?: AdapterAttestationCitation;
 }
 
 export interface WorkflowSandboxProjectionEvidence {
@@ -161,12 +177,12 @@ export interface WorkflowSandboxProjectionEvidence {
 export interface WorkflowProofUnknown {
   code:
     | "tool_evidence_unavailable"
-    | "harness_capability_unregistered"
+    | "adapter_capability_unregistered"
     | "agent_cost_unreported"
     | "agent_session_unreported"
     | "repository_drift_incomplete";
   message: string;
-  harness?: HarnessName;
+  adapter?: AdapterName;
   agent_id?: string;
 }
 
@@ -186,6 +202,17 @@ export interface WorkflowProof {
     objective?: string;
     error?: string;
     result?: ResultDigest;
+    /** Set on a failed run that was uninformative about the work (ADR 0046):
+     * environment, upstream, or decision. The first two are derived from the
+     * agents' classes when no agent produced a result; `decision` is declared by
+     * the script through ctx.blocked(). Absent ⇒ the attempt is charged as
+     * before. The durable work projection reads this to decide charging,
+     * stopping, and the uncharged-attempt bound. */
+    class?: RunFailureClass;
+    /** Docket id of the decision this run stopped on. Only ever set alongside
+     * class "decision", and only when the script named one. Carried so the work
+     * projection can point a human at the exact question rather than at prose. */
+    decision_id?: string;
   };
   acceptance: {
     criteria: AcceptanceResult[];
@@ -201,11 +228,11 @@ export interface WorkflowProof {
    * 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[];
+  adapters: AdapterEvidenceCoverage[];
   unknowns: WorkflowProofUnknown[];
   integrity: {
-    journal: {
-      path: "journal.jsonl";
+    transcript: {
+      path: "transcript.jsonl";
       sha256: string;
       bytes: number;
     };
@@ -228,8 +255,8 @@ export interface WorkflowPolicyProof {
   };
 }
 
-export interface HarnessEvidenceCapability {
-  toolEvidence: HarnessEvidenceCoverage["tool_evidence"];
+export interface AdapterEvidenceCapability {
+  toolEvidence: AdapterEvidenceCoverage["tool_evidence"];
 }
 
 /** JSON-schema *subset* accepted by stage gates (see validate.ts). */
@@ -261,36 +288,36 @@ export interface AgentOpts {
    * validate; the engine retries with the validation error appended, up to
    * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
   schema?: StageSchema;
-  /** Model slug passed through to the harness CLI (default: the CLI's default). */
+  /** Model slug passed through to the adapter CLI (default: the CLI's default). */
   model?: string;
-  /** Reasoning effort mapped through the selected harness profile. Unsupported
+  /** Reasoning effort mapped through the selected adapter profile. Unsupported
    * values fail before the vendor process starts. */
   effort?: string;
   /** Attempt ceiling for the schema-retry loop (default 2). */
   maxAttempts?: number;
   /** Subprocess timeout ms (default 300_000). */
   timeoutMs?: number;
-  /** Harness-turn ceiling for the child (default 25; use 1 for pure
+  /** Adapter-turn ceiling for the child (default 25; use 1 for pure
    * classification stages — cheaper and faster). */
   maxTurns?: number;
-  /** Display label in the journal (default: prompt head). */
+  /** Display label in the transcript (default: prompt head). */
   label?: string;
-  /** Which harness runs this agent (default: the run's default harness).
-   * Mixed-harness workflows are legal: triage on one CLI, deep work on
+  /** Which adapter runs this agent (default: the run's default adapter).
+   * Mixed-adapter workflows are legal: triage on one CLI, deep work on
    * another. */
-  harness?: HarnessName;
+  adapter?: AdapterName;
 }
 
 /** Open registry key. The built-in catalog currently contains Claude Code,
  * Codex, and Cursor; consumers may register another adapter without widening
  * a package-owned union first. */
-export type HarnessName = string;
+export type AdapterName = string;
 
-/** Durable role defaults supplied by a goal supervisor or embedding host.
+/** Durable role defaults supplied by a goal governor or embedding host.
  * Profiles are frozen into a workflow run manifest before the first spawn. */
 export interface WorkflowSpecialistProfile {
   instructions: string;
-  harness?: HarnessName;
+  adapter?: AdapterName;
   model?: string;
   effort?: string;
   maxAttempts?: number;
@@ -298,17 +325,51 @@ export interface WorkflowSpecialistProfile {
   maxTurns?: number;
 }
 
+/**
+ * Why a failed run was uninformative about the work (ADR 0046). Absent means
+ * the attempt produced information about the work (or succeeded), which is the
+ * default and is charged against the attempt budget exactly as before.
+ *
+ * - `environment`: the run never started — a precondition was missing (the
+ *   vendor binary was absent). Uncharged AND not retried: retrying an unchanged
+ *   environment cannot help, so the work item stops and names the precondition.
+ * - `upstream`: the vendor was reached and refused (5xx, 429, circuit open).
+ *   Uncharged, but retry stays available (bounded by max_uncharged_attempts).
+ */
+export type SpawnFailureClass = "environment" | "upstream";
+
+/**
+ * Why a failed run was uninformative about the work. A superset of
+ * {@link SpawnFailureClass}: a spawn can fail for reasons outside the work, and
+ * so can the script itself.
+ *
+ * - `decision`: the script reached a correct conclusion and that conclusion is
+ *   that a human must rule before the work can proceed. Nothing about the work
+ *   was wrong, so the attempt is uncharged; nothing about a retry can help,
+ *   because the blocker is a person, so the item stops and names the decision.
+ *
+ * This class exists because without it a correct refusal and a botched attempt
+ * are the same outcome to the engine. Automatic retry then re-issues work an
+ * agent already answered correctly, once per attempt budget, and the answer is
+ * identical every time — the loop cannot converge, because the thing it is
+ * waiting for is a person who was never told.
+ */
+export type RunFailureClass = SpawnFailureClass | "decision";
+
 /** What a spawn adapter returns for one subagent run. */
 export interface SpawnResult {
   ok: boolean;
   /** The model's final reply text (envelope-unwrapped). */
   text: string;
-  /** Child harness session id when the envelope carries one. */
+  /** Child adapter session id when the envelope carries one. */
   sessionId?: string;
   costUsd?: number;
   durationMs: number;
   /** Populated when ok=false. */
   error?: string;
+  /** Set when ok=false and the failure was positively identified as
+   * uninformative about the work. Absent ⇒ a work failure (charged). */
+  class?: SpawnFailureClass;
 }
 
 export interface SpawnRequest {
@@ -321,6 +382,10 @@ export interface SpawnRequest {
   /** Run id, stamped into the child env (HARNERY_WORKFLOW_RUN_ID) so the
    * coord layer can associate child sessions with their workflow run. */
   runId?: string;
+  /** Transcript agent id (`a1`, `a2`, …), stamped into the child env
+   * (HARNERY_WORKFLOW_AGENT_ID) so in-flight child activity attributes to one
+   * agent row rather than only to the run. */
+  agentId?: string;
   /** Scrub all API-key vars from the child env so it can only authenticate
    * via its stored (subscription) login. See billing.ts. */
   subscriptionOnly?: boolean;
@@ -370,14 +435,33 @@ export interface WorkflowContext {
   agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
   /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
   parallel: <T>(thunks: Array<() => Promise<T>>) => Promise<Array<T | null>>;
-  /** Declare the current stage (journal + progress grouping). */
+  /** Declare the current stage (transcript + progress grouping). */
   stage: (title: string) => void;
-  /** Narrate progress (stderr + journal). */
+  /** Narrate progress (stderr + transcript). */
   log: (message: string) => void;
   /** Attach a bounded, sourced receipt to the run and optional acceptance criteria. */
   evidence: (input: WorkflowEvidenceInput) => string;
   /** Authorize one host-mediated external mutation before performing it. */
   authorize: (input: ExternalMutationRequest) => Promise<PolicyDecision>;
+  /** Stop the run because a human must rule before the work can proceed.
+   *
+   * This is not a failure and must not be used as one. Reach for it only when
+   * the script determined something *correct* — that the question in front of
+   * it belongs to a person. The run ends uncharged and the work item stops
+   * naming the decision, so no automatic retry re-issues work that was already
+   * answered correctly. A plain `throw` means the opposite: the work failed and
+   * a retry might do better. */
+  blocked: (input: BlockedInput) => never;
+}
+
+/** Why a run stopped on a human. */
+export interface BlockedInput {
+  /** What a human has to settle, in one sentence. Shown verbatim to the
+   * operator as the work item's reason, so write it for them, not for a log. */
+  reason: string;
+  /** Docket id of the decision to resolve. Strongly preferred: without it the
+   * operator gets prose and has to go find the question themselves. */
+  decision?: string;
 }
 
 export interface WorkflowMeta {
@@ -442,18 +526,18 @@ export interface WorkflowOperatorFinding {
 }
 
 export interface EngineOpts {
-  /** Repo root whose .harnery/ receives the run journal. */
+  /** Repo root whose .harnery/ receives the run transcript. */
   coordRoot: string;
-  /** Spawner registry keyed by harness. A single-harness caller registers one
-   * entry and names it in `defaultHarness`. */
-  spawners: Readonly<Record<HarnessName, Spawner | undefined>>;
-  /** Harness used when an agent() call doesn't name one (default "claude-code"). */
-  defaultHarness?: HarnessName;
+  /** Spawner registry keyed by adapter. A single-adapter caller registers one
+   * entry and names it in `defaultAdapter`. */
+  spawners: Readonly<Record<AdapterName, Spawner | undefined>>;
+  /** Adapter used when an agent() call doesn't name one (default "claude-code"). */
+  defaultAdapter?: AdapterName;
   /** Named specialist roles available to agent(..., { specialist }). */
   specialists?: Readonly<Record<string, WorkflowSpecialistProfile>>;
-  /** Resume: run id of a prior run whose journal supplies cached results.
+  /** Resume: run id of a prior run whose transcript supplies cached results.
    * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
-   * completed prior agent return the journaled result without spawning. */
+   * completed prior agent return the transcripted result without spawning. */
   resumeFrom?: string;
   /** Continue a parked run in its original directory after its durable
    * approval has been resolved. The frozen run manifest supplies execution
@@ -478,7 +562,7 @@ export interface EngineOpts {
   /** Progress sink (default: process.stderr). */
   onLog?: (line: string) => void;
   /** Guarantee subscription billing: API-key vars are scrubbed from every
-   * child env, and a harness whose stored login is provably absent fails
+   * child env, and a adapter whose stored login is provably absent fails
    * loud before spawning. */
   subscriptionOnly?: boolean;
   /** Permit the api-key-override billing state (an exported API key silently
@@ -490,10 +574,10 @@ export interface EngineOpts {
   probeBilling?: BillingProber;
   /** Capability claims used to state whether adapter-native tool evidence was
    * available. Missing claims remain unknown. */
-  harnessEvidence?: Readonly<Record<HarnessName, HarnessEvidenceCapability | undefined>>;
-  /** Live attestations backing each harness's claims (ADR 0038). Read once by
+  adapterEvidence?: Readonly<Record<AdapterName, AdapterEvidenceCapability | undefined>>;
+  /** Live attestations backing each adapter's claims (ADR 0038). Read once by
    * the host and injected, so the engine performs no capability lookups. */
-  harnessAttestations?: Readonly<Record<HarnessName, HarnessAttestationCitation | undefined>>;
+  adapterAttestations?: Readonly<Record<AdapterName, AdapterAttestationCitation | 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. */
@@ -524,7 +608,7 @@ export interface EngineOpts {
   approvalAddressee?: string;
   /** Execution boundary created by the host (default shared). */
   isolation?: PolicyIsolation;
-  /** Network state of spawned harness subprocesses (default unknown). */
+  /** Network state of spawned adapter subprocesses (default unknown). */
   networkAccess?: PolicyNetworkAccess;
   /** Explicit provider and host-owned roots. Omit for shared or declaration-only execution. */
   workspace?: {
@@ -540,19 +624,19 @@ export interface RunReport {
   /** What the script's default export returned. */
   result: unknown;
   agentsSpawned: number;
-  /** agent() calls satisfied from the resumeFrom journal without spawning. */
+  /** agent() calls satisfied from the resumeFrom transcript without spawning. */
   agentsCached: number;
   costUsd: number;
   durationMs: number;
-  journalPath: string;
+  transcriptPath: string;
   proofPath: string;
   acceptance: AcceptanceSummary;
   /** Estimated tokens of repo instructions (CLAUDE.md/AGENTS.md at the child
    * cwd) that EVERY child cache-writes on spawn — the fixed per-child context
    * overhead a fan-out multiplies. bytes/4 heuristic; 0 when no such file. */
   contextTokensPerChildEstimate: number;
-  /** Billing mode per harness actually used this run (probed on first use). */
-  billing: Array<{ harness: HarnessName; mode: BillingMode }>;
+  /** Billing mode per adapter actually used this run (probed on first use). */
+  billing: Array<{ adapter: AdapterName; mode: BillingMode }>;
   /** Policy verdict totals when the host supplied a policy. */
   policy?: WorkflowPolicyProof["summary"];
   /** Isolated workspace binding when this run requested a provider capability. */

package/src/core/workflow/validate.ts

@@ -114,7 +114,7 @@ export function validateAgainstSchema(value: unknown, schema: StageSchema, path
 /**
  * Parse one schema-gated JSON value.
  *
- * Exact JSON and a whole fenced value remain the normal paths. Some harnesses
+ * Exact JSON and a whole fenced value remain the normal paths. Some adapters
  * 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

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

@@ -5,7 +5,7 @@ import {
 } from "../../work/state.ts";
 import { readWorkflowRunManifest } from "../run-state.ts";
 import {
-  appendWorkflowJournalEvent,
+  appendWorkflowTranscriptEvent,
   readWorkflowSupplement,
   stableDigest,
   writeWorkflowSupplement,
@@ -72,7 +72,7 @@ export async function cancelWorkspace(
       reason: result.reason,
     };
     writeWorkflowSupplement(input.coordRoot, input.runId, "cancellation/outcome.json", receipt);
-    appendWorkflowJournalEvent(input.coordRoot, input.runId, "workspace.cancel", {
+    appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "workspace.cancel", {
       binding_id: binding.binding_id,
       provider_id: binding.provider.id,
       receipt_id: receipt.receipt_id,

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

@@ -5,7 +5,7 @@ import { acquireNoClobberLease } from "./leases.ts";
 import { containsPath } from "./paths.ts";
 import {
   appendCleanupAttempt,
-  appendWorkflowJournalEvent,
+  appendWorkflowTranscriptEvent,
   readCleanupAttempts,
   readWorkflowSupplement,
   stableDigest,
@@ -112,7 +112,7 @@ async function cleanupWorkspaceUnderLease(
     reason: result.reason,
     recorded_at: result.recorded_at,
   });
-  appendWorkflowJournalEvent(input.coordRoot, input.runId, "workspace.cleanup", {
+  appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "workspace.cleanup", {
     binding_id: binding.binding_id,
     provider_id: binding.provider.id,
     operation_id: intent.operation_id,

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

@@ -10,7 +10,7 @@ import {
   sameFilesystemIdentity,
   validateConfiguredRoot,
 } from "./paths.ts";
-import { appendWorkflowJournalEvent, stableDigest, writeWorkspaceRequest } from "./state.ts";
+import { appendWorkflowTranscriptEvent, stableDigest, writeWorkspaceRequest } from "./state.ts";
 import type {
   WorkspaceAttestation,
   WorkspaceBinding,
@@ -72,7 +72,7 @@ export async function resolveWorkspaceBinding(input: {
       unknowns: [],
       receipts: {},
     };
-    appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.compatibility", {
+    appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.compatibility", {
       requested_isolation: fallback.requested_isolation,
       effective_isolation: fallback.effective_isolation,
       selection_reason: fallback.selection_reason,
@@ -114,7 +114,7 @@ export async function resolveWorkspaceBinding(input: {
       }
       throw new Error(`workflow run ${input.runId} could not reattach its frozen workspace`);
     }
-    appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.reattach", {
+    appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.reattach", {
       binding_id: frozenBinding.binding_id,
       provider_id: frozenBinding.provider.id,
       attestation_sha256: stableDigest(reattached),
@@ -180,7 +180,7 @@ export async function resolveWorkspaceBinding(input: {
         unknowns: [...probe.unknowns],
         receipts: {},
       };
-      appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "workspace.fallback", {
+      appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "workspace.fallback", {
         requested_isolation: fallback.requested_isolation,
         effective_isolation: fallback.effective_isolation,
         selection_reason: fallback.selection_reason,
@@ -226,7 +226,7 @@ export async function resolveWorkspaceBinding(input: {
     idempotency_key: stableDigest(requestWithoutKey),
   };
   writeWorkspaceRequest(input.opts.coordRoot, request);
-  appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "execution.allocate.start", {
+  appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "execution.allocate.start", {
     provider_id: probe.capabilities.provider_id,
     request_sha256: stableDigest(request),
   });
@@ -261,7 +261,7 @@ export async function resolveWorkspaceBinding(input: {
     }
     throw new Error("workspace provider returned a binding that failed initial attestation");
   }
-  appendWorkflowJournalEvent(input.opts.coordRoot, input.runId, "execution.allocate.end", {
+  appendWorkflowTranscriptEvent(input.opts.coordRoot, input.runId, "execution.allocate.end", {
     binding_id: binding.binding_id,
     provider_id: binding.provider.id,
     active_root: binding.active_root,

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

@@ -97,7 +97,7 @@ export type WorkflowWorkspaceInspection =
   | { ok: true; value: WorkflowWorkspaceStatus }
   | { ok: false; run_id: string; error: string };
 
-interface WorkflowJournalProjectionEvent {
+interface WorkflowTranscriptProjectionEvent {
   event: string;
   ok?: boolean;
   status?: "blocked" | "lost" | "cancelled" | "unsupported" | "preserved_dirty";
@@ -119,7 +119,7 @@ export function readWorkflowWorkspaceStatus(
   const root = resolve(coordRoot);
   const runDir = workflowRunDir(root, runId);
   const manifest = readWorkflowRunManifest(root, runId);
-  const journal = readWorkspaceJournal(runDir, runId);
+  const transcript = readWorkspaceTranscript(runDir, runId);
   const proofPath = join(runDir, "proof.json");
   const proof = existsSync(proofPath) ? readWorkflowProof(root, runId) : undefined;
   const proofSha256 = proof ? fileSha256(proofPath) : undefined;
@@ -129,7 +129,7 @@ export function readWorkflowWorkspaceStatus(
   if (!binding) {
     const lifecycle = deriveWorkspaceLifecycle({
       manifest,
-      workflow_journal: journal,
+      workflow_transcript: transcript,
       proof,
       proof_sha256: proofSha256,
       allocation_unsupported: fallback !== undefined,
@@ -212,7 +212,7 @@ export function readWorkflowWorkspaceStatus(
     binding,
     provider_events: providerEvents,
     manifest,
-    workflow_journal: journal,
+    workflow_transcript: transcript,
     proof,
     proof_sha256: proofSha256,
     integration_plan: integrationPlan,
@@ -355,8 +355,11 @@ export function renderWorkflowWorkspaceStatus(status: WorkflowWorkspaceStatus):
 
 const MAX_LISTED_DIRTY_PATHS = 12;
 
-function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalProjectionEvent[] {
-  const path = join(runDir, "journal.jsonl");
+function readWorkspaceTranscript(
+  runDir: string,
+  runId: string,
+): WorkflowTranscriptProjectionEvent[] {
+  const path = join(runDir, "transcript.jsonl");
   if (!existsSync(path)) return [];
   return readFileSync(path, "utf8")
     .split("\n")
@@ -367,7 +370,7 @@ function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalPro
         record = JSON.parse(line) as Record<string, unknown>;
       } catch (error) {
         throw new Error(
-          `cannot parse workflow journal event ${index + 1}: ${
+          `cannot parse workflow transcript event ${index + 1}: ${
             error instanceof Error ? error.message : String(error)
           }`,
         );
@@ -376,12 +379,12 @@ function readWorkspaceJournal(runDir: string, runId: string): WorkflowJournalPro
         typeof record.event !== "string" ||
         (record.run_id !== undefined && record.run_id !== runId)
       ) {
-        throw new Error(`workflow journal event ${index + 1} is foreign or unsupported`);
+        throw new Error(`workflow transcript event ${index + 1} is foreign or unsupported`);
       }
       return {
         event: record.event,
         ok: typeof record.ok === "boolean" ? record.ok : undefined,
-        status: journalStatus(record.status),
+        status: transcriptStatus(record.status),
         work_event_seq:
           typeof record.work_event_seq === "number" ? record.work_event_seq : undefined,
         work_event_sha256:
@@ -424,10 +427,10 @@ function cleanupState(
   return intent || attemptStatus ? "pending" : "not_requested";
 }
 
-function journalStatus(value: unknown): WorkflowJournalProjectionEvent["status"] {
+function transcriptStatus(value: unknown): WorkflowTranscriptProjectionEvent["status"] {
   return typeof value === "string" &&
     ["blocked", "lost", "cancelled", "unsupported", "preserved_dirty"].includes(value)
-    ? (value as WorkflowJournalProjectionEvent["status"])
+    ? (value as WorkflowTranscriptProjectionEvent["status"])
     : undefined;
 }
 

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

@@ -16,7 +16,7 @@ import { readWorkflowRunManifest } from "../run-state.ts";
 import { acquireNoClobberLease } from "./leases.ts";
 import {
   appendIntegrationAttempt,
-  appendWorkflowJournalEvent,
+  appendWorkflowTranscriptEvent,
   fileSha256,
   readIntegrationAttempts,
   readWorkflowSupplement,
@@ -177,7 +177,7 @@ export async function prepareIntegration(input: PrepareIntegrationInput): Promis
     }
     if (!prior) {
       writeWorkflowSupplement(input.coordRoot, input.runId, "integration/plan.json", plan);
-      appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.plan", {
+      appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.plan", {
         plan_id: plan.plan_id,
         plan_sha256: stableDigest(plan),
       });
@@ -236,12 +236,12 @@ export async function applyIntegration(
     }
     if (
       authorization.decision_sha256 !== stableDigest(authorization.decision) ||
-      authorization.journal_anchor.event !== "integration.plan" ||
-      authorization.journal_anchor.plan_sha256 !== planSha256
+      authorization.transcript_anchor.event !== "integration.plan" ||
+      authorization.transcript_anchor.plan_sha256 !== planSha256
     ) {
-      throw new Error("integration authorization digest or journal anchor is corrupt");
+      throw new Error("integration authorization digest or transcript anchor is corrupt");
     }
-    assertIntegrationPlanJournal(input.coordRoot, input.runId, planSha256);
+    assertIntegrationPlanTranscript(input.coordRoot, input.runId, planSha256);
     if (authorization.approval_id) {
       const approval = readWorkflowApproval(input.coordRoot, authorization.approval_id);
       if (
@@ -397,7 +397,7 @@ export async function applyIntegration(
       applied_at: providerResult.applied_at,
     };
     writeWorkflowSupplement(input.coordRoot, input.runId, "integration/receipt.json", receipt);
-    appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.apply", {
+    appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.apply", {
       receipt_id: receipt.receipt_id,
       status: receipt.status,
       target_commit: receipt.target_commit,
@@ -721,7 +721,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
     approval_id: approvalId,
     approval_actor: approvalActor,
     approval_sha256: approvalSha256,
-    journal_anchor: {
+    transcript_anchor: {
       event: "integration.plan",
       plan_sha256: stableDigest(plan),
     },
@@ -740,7 +740,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
       prior.decision_sha256 !== stableDigest(prior.decision) ||
       prior.approval_id !== authorization.approval_id ||
       prior.approval_sha256 !== authorization.approval_sha256 ||
-      stableDigest(prior.journal_anchor) !== stableDigest(authorization.journal_anchor)
+      stableDigest(prior.transcript_anchor) !== stableDigest(authorization.transcript_anchor)
     ) {
       throw new Error("existing integration authorization does not match the exact plan");
     }
@@ -752,7 +752,7 @@ function authorizePlan(input: PrepareIntegrationInput, plan: IntegrationPlan): v
     "integration/authorization.json",
     authorization,
   );
-  appendWorkflowJournalEvent(input.coordRoot, input.runId, "integration.authorized", {
+  appendWorkflowTranscriptEvent(input.coordRoot, input.runId, "integration.authorized", {
     plan_id: plan.plan_id,
     authorization_sha256: stableDigest(authorization),
     policy_sha256: authorization.policy_sha256,
@@ -787,8 +787,12 @@ function requiredIntegrationRoot(binding: WorkspaceBinding): string {
   return binding.integration_root;
 }
 
-function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha256: string): void {
-  const path = join(workflowRunDir(coordRoot, runId), "journal.jsonl");
+function assertIntegrationPlanTranscript(
+  coordRoot: string,
+  runId: string,
+  planSha256: string,
+): void {
+  const path = join(workflowRunDir(coordRoot, runId), "transcript.jsonl");
   let records: Array<Record<string, unknown>>;
   try {
     records = readFileSync(path, "utf8")
@@ -796,7 +800,7 @@ function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha2
       .filter(Boolean)
       .map((line) => JSON.parse(line) as Record<string, unknown>);
   } catch (error) {
-    throw new Error(`workflow journal is corrupt: ${(error as Error).message}`);
+    throw new Error(`workflow transcript is corrupt: ${(error as Error).message}`);
   }
   if (
     records.some((record) => record.run_id !== runId || typeof record.event !== "string") ||
@@ -804,7 +808,7 @@ function assertIntegrationPlanJournal(coordRoot: string, runId: string, planSha2
       (record) => record.event === "integration.plan" && record.plan_sha256 === planSha256,
     )
   ) {
-    throw new Error("integration plan journal anchor is missing or mismatched");
+    throw new Error("integration plan transcript anchor is missing or mismatched");
   }
 }