harnery 0.29.0 → 0.31.0

package/dist/core/workflow/engine.js

@@ -1,7 +1,7 @@
 /**
  * Workflow engine: loads a workflow script (plain JS, `export default
- * async (ctx) => …`), injects the ctx API, enforces the caps, journals every
- * step to `.harnery/workflows/<run-id>/journal.jsonl`, and returns a RunReport.
+ * async (ctx) => …`), injects the ctx API, enforces the caps, transcripts every
+ * step to `.harnery/workflows/<run-id>/transcript.jsonl`, and returns a RunReport.
  *
  * Guarantees the engine makes (the pitch, in code):
  *   - **Bounded**: hard total-agent ceiling + bounded parallel() concurrency.
@@ -13,7 +13,7 @@
  *     validate; failures re-prompt with the validation errors appended, up to
  *     `maxAttempts`, then throw. Routing decisions read validated fields, so
  *     the deterministic script — not a model — decides what runs next.
- *   - **Journaled**: every stage/agent start+end lands in the run journal with
+ *   - **Transcripted**: every stage/agent start+end lands in the run transcript with
  *     cost, duration, and child session id (the resume + web-UI substrate).
  */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
@@ -34,11 +34,12 @@ import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.js";
 import { freezeWorkflowAttemptContext } from "./attempt-context.js";
 import { probeBilling } from "./billing.js";
 import { stableDigest } from "./durable-record.js";
-import { appendWorkflowJournalEvent } from "./journal.js";
+import { evidencePreflightError } from "./evidence-preflight.js";
 import { buildWorkflowProof, createEvidenceRecord, digestResult, normalizeWorkflowMeta, writeWorkflowProof, } from "./proof.js";
 import { acquireWorkflowResumeLease, assertWorkflowRunResumable, assertWorkflowScriptUnchanged, workflowScriptDigest, writeWorkflowRunManifest, } from "./run-state.js";
 import { assertProjectionWithinWorkspace, resolveGitGrantRoots } from "./sandbox-projection.js";
 import { normalizeWorkflowSpecialists, resolveSpecialistAssignment } from "./specialists.js";
+import { appendWorkflowTranscriptEvent } from "./transcript.js";
 import { parseStageOutput, validateAgainstSchema } from "./validate.js";
 import { freezeWorkflowWorkContext } from "./work-context.js";
 import { attestTerminal, attestWorkspaceFailure, resolveWorkspaceBinding, } from "./workspaces/execution.js";
@@ -75,13 +76,30 @@ export class WorkflowRunError extends Error {
 export class WorkflowParkedError extends Error {
     runId;
     approvalId;
-    journalPath;
-    constructor(message, runId, approvalId, journalPath) {
+    transcriptPath;
+    constructor(message, runId, approvalId, transcriptPath) {
         super(message);
         this.name = "WorkflowParkedError";
         this.runId = runId;
         this.approvalId = approvalId;
-        this.journalPath = journalPath;
+        this.transcriptPath = transcriptPath;
+    }
+}
+/** Thrown by ctx.blocked(). Carries the run out of the script and into the
+ * failure path, where its presence — not its message — is what stamps the proof
+ * with class "decision". A script cannot fake this by throwing an ordinary
+ * Error with a suggestive message, which is the point: the class has to mean
+ * "the script deliberately declared this", not "the text looked like it". */
+export class WorkflowBlockedError extends Error {
+    reason;
+    decisionId;
+    constructor(reason, decisionId) {
+        super(decisionId
+            ? `blocked on decision ${decisionId}: ${reason}`
+            : `blocked pending a human decision: ${reason}`);
+        this.name = "WorkflowBlockedError";
+        this.reason = reason;
+        this.decisionId = decisionId;
     }
 }
 export async function runWorkflow(scriptPath, opts) {
@@ -151,9 +169,28 @@ export async function runWorkflow(scriptPath, opts) {
         releaseResumeLease?.();
     }
 }
+/** Throws when the script names an evidence kind the proof layer will refuse.
+ * Silent when the file cannot be read: the import a moment later will produce a
+ * better error than a guess from here would. */
+function assertEvidenceKindsAreUsable(scriptPath, absScript) {
+    let source;
+    try {
+        source = readFileSync(absScript, "utf8");
+    }
+    catch {
+        return;
+    }
+    const message = evidencePreflightError(source, scriptPath);
+    if (message)
+        throw new Error(message);
+}
 async function executeWorkflow(scriptPath, absScript, opts, resumeState, workContext, attemptContext) {
     const frozen = resumeState?.manifest.execution;
     const isolation = frozen?.isolation ?? opts.isolation ?? "shared";
+    // Before anything is spawned, and before either import path below: an evidence
+    // kind the proof will reject is fatal at the END of a workflow, which is the
+    // most expensive place to learn it. Reading the file is the cheapest moment.
+    assertEvidenceKindsAreUsable(scriptPath, absScript);
     let sharedWorkflow;
     let sharedMeta;
     if (isolation === "shared") {
@@ -170,7 +207,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         `wf-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
     const runDir = join(opts.coordRoot, ".harnery", "workflows", runId);
     mkdirSync(runDir, { recursive: true });
-    const journalPath = join(runDir, "journal.jsonl");
+    const transcriptPath = join(runDir, "transcript.jsonl");
     const proofPath = join(runDir, "proof.json");
     const maxAgents = frozen?.max_agents ?? opts.maxAgents ?? DEFAULT_MAX_AGENTS;
     const concurrency = frozen?.concurrency ?? opts.concurrency ?? DEFAULT_CONCURRENCY;
@@ -178,7 +215,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
     assertPositiveWorkflowBound(concurrency, "concurrency");
     const cwd = frozen?.cwd ?? opts.cwd ?? opts.coordRoot;
     const log = opts.onLog ?? ((line) => process.stderr.write(`${line}\n`));
-    const defaultHarness = frozen?.default_harness ?? opts.defaultHarness ?? "claude-code";
+    const defaultAdapter = frozen?.default_adapter ?? opts.defaultAdapter ?? "claude-code";
     const specialists = frozen?.specialists ?? (resumeState ? {} : normalizeWorkflowSpecialists(opts.specialists));
     const networkAccess = frozen?.network_access ?? opts.networkAccess ?? "unknown";
     const policy = frozen?.policy ?? (opts.policy ? normalizePolicy(opts.policy, { baseDir: cwd }) : undefined);
@@ -220,19 +257,19 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         const endedAt = new Date().toISOString();
         const durationMs = Date.now() - t0;
         const failedAttestation = await attestWorkspaceFailure(workspaceProvider, frozenBinding, error);
-        appendWorkflowJournalEvent(opts.coordRoot, runId, "run.resume", {
+        appendWorkflowTranscriptEvent(opts.coordRoot, runId, "run.resume", {
             approval_id: resumeState.approvalId,
             script: absScript,
             resumed_at: new Date().toISOString(),
         });
-        appendWorkflowJournalEvent(opts.coordRoot, runId, "workspace.reattach.failed", {
+        appendWorkflowTranscriptEvent(opts.coordRoot, runId, "workspace.reattach.failed", {
             binding_id: frozenBinding.binding_id,
             provider_id: frozenBinding.provider.id,
             status: failedAttestation.status,
             reason: failure.message,
             attestation_sha256: stableDigest(failedAttestation),
         });
-        appendWorkflowJournalEvent(opts.coordRoot, runId, "run.end", {
+        appendWorkflowTranscriptEvent(opts.coordRoot, runId, "run.end", {
             ok: false,
             error: failure.message,
             agents: 0,
@@ -251,13 +288,13 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 startedAt,
                 endedAt,
                 durationMs,
-                journalPath,
+                transcriptPath,
                 before: resumeState.manifest.repository_before,
                 after: resumeState.manifest.repository_before,
                 agents: [],
                 evidence: [],
-                harnessEvidence: opts.harnessEvidence,
-                harnessAttestations: opts.harnessAttestations,
+                adapterEvidence: opts.adapterEvidence,
+                adapterAttestations: opts.adapterAttestations,
                 sandboxProjection: sandboxProjectionEvidence(opts.filesystemPolicy, opts.gitWrite ?? "none"),
                 policy: policy
                     ? {
@@ -320,7 +357,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 repository_before: executionRepoBefore,
                 execution: {
                     cwd: executionCwd,
-                    default_harness: defaultHarness,
+                    default_adapter: defaultAdapter,
                     max_agents: maxAgents,
                     concurrency,
                     subscription_only: subscriptionOnly,
@@ -363,7 +400,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                     : undefined;
                 throw new Error("workspace authority changed during workflow module initialization");
             }
-            appendWorkflowJournalEvent(opts.coordRoot, runId, "workspace.reattach.module_initialized", {
+            appendWorkflowTranscriptEvent(opts.coordRoot, runId, "workspace.reattach.module_initialized", {
                 binding_id: workspaceBinding.binding_id,
                 provider_id: workspaceBinding.provider.id,
                 attestation_sha256: stableDigest(postImport),
@@ -377,7 +414,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                     cause: reattachmentError,
                 })
                 : reattachmentError;
-            appendWorkflowJournalEvent(opts.coordRoot, runId, "workspace.reattach.module_initialization_failed", {
+            appendWorkflowTranscriptEvent(opts.coordRoot, runId, "workspace.reattach.module_initialization_failed", {
                 binding_id: workspaceBinding.binding_id,
                 provider_id: workspaceBinding.provider.id,
                 status: initializationAttestation.status,
@@ -396,12 +433,12 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         log(`[context] each child cache-writes ~${Math.round(contextTokensPerChildEstimate / 1000)}K tokens of repo ` +
             `instructions from ${executionCwd}; a fan-out multiplies this per agent`);
     }
-    // Resume: journaled results of a prior run, keyed by agent-call identity.
+    // Resume: transcripted results of a prior run, keyed by agent-call identity.
     const resumeSource = opts.resumeRunId ?? opts.resumeFrom;
     const resumeCache = resumeSource
         ? loadResumeCache(opts.coordRoot, resumeSource)
         : new Map();
-    const history = opts.resumeRunId ? loadRunHistory(journalPath) : undefined;
+    const history = opts.resumeRunId ? loadRunHistory(transcriptPath) : undefined;
     let agentsSpawned = history?.agentsSpawned ?? 0;
     let agentsCached = 0;
     let costUsd = history?.costUsd ?? 0;
@@ -415,14 +452,14 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
     const evidenceRecords = [];
     const policyDecisions = new Map(history?.policyDecisions.map((decision) => [decision.id, decision]));
     const acceptanceIds = new Set(meta.acceptance.map((criterion) => criterion.id));
-    const journal = (event, data) => {
-        appendWorkflowJournalEvent(opts.coordRoot, runId, event, { stage: currentStage, ...data });
+    const transcript = (event, data) => {
+        appendWorkflowTranscriptEvent(opts.coordRoot, runId, event, { stage: currentStage, ...data });
     };
-    const journalAgentEnd = (data, resultKind, result) => {
+    const transcriptAgentEnd = (data, resultKind, result) => {
         // The writer shrinks an oversized record itself and names what it dropped,
         // so no per-call fallback is needed here. A digest rides along regardless so
         // a shrunk record can still be tied back to the exact result.
-        journal("agent.end", {
+        transcript("agent.end", {
             ...data,
             result_kind: resultKind,
             result_digest: digestResult(result, resultKind),
@@ -475,7 +512,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         const evaluation = evaluatePolicy(policy, request);
         const id = `p${++policySeq}`;
         const checkedAt = new Date().toISOString();
-        journal("policy.check", {
+        transcript("policy.check", {
             id,
             policy: policy.name,
             policy_sha256: policyDigest(policy),
@@ -521,25 +558,25 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 });
                 if (stored.approval.status === "pending") {
                     if (stored.created) {
-                        journal("approval.requested", {
+                        transcript("approval.requested", {
                             approval_id: stored.approval.request.id,
                             decision_id: id,
                             addressed_to: stored.approval.request.addressed_to,
                             request_sha256: stored.approval.request.request_sha256,
                         });
                     }
-                    journal("run.parked", {
+                    transcript("run.parked", {
                         approval_id: stored.approval.request.id,
                         decision_id: id,
                         phase: request.phase,
                         action: request.action,
                     });
-                    throw new WorkflowParkedError(`workflow parked for approval ${stored.approval.request.id}: ${evaluation.reason}`, runId, stored.approval.request.id, journalPath);
+                    throw new WorkflowParkedError(`workflow parked for approval ${stored.approval.request.id}: ${evaluation.reason}`, runId, stored.approval.request.id, transcriptPath);
                 }
                 verdict = stored.approval.decision.verdict;
                 resolvedBy = "approval";
                 reason = boundedPolicyReason(stored.approval.decision.reason ?? evaluation.reason);
-                journal("approval.consumed", {
+                transcript("approval.consumed", {
                     approval_id: stored.approval.request.id,
                     decision_id: id,
                     verdict,
@@ -561,7 +598,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             request,
         };
         policyDecisions.set(decision.id, decision);
-        journal("policy.resolve", { ...decision });
+        transcript("policy.resolve", { ...decision });
         if (decision.verdict === "deny") {
             throw new PolicyDeniedError(`policy ${JSON.stringify(policy.name)} denied ${request.phase} ${JSON.stringify(request.action)}: ${decision.reason}`, decision.id);
         }
@@ -576,10 +613,10 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             : assignmentPrompt;
         let reservedForDispatch = 0;
         let spawnCountClaimed = false;
-        const harness = agentOpts.harness ?? defaultHarness;
-        const spawner = opts.spawners[harness];
+        const adapter = agentOpts.adapter ?? defaultAdapter;
+        const spawner = opts.spawners[adapter];
         if (!spawner) {
-            throw new Error(`no spawner registered for harness "${harness}" (registered: ${Object.keys(opts.spawners).join(", ") || "none"})`);
+            throw new Error(`no spawner registered for adapter "${adapter}" (registered: ${Object.keys(opts.spawners).join(", ") || "none"})`);
         }
         const id = `a${++agentSeq}`;
         const label = agentOpts.label ?? `${prompt.slice(0, 60).replace(/\s+/g, " ")}…`;
@@ -590,16 +627,16 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             label: proofLabel,
             stage: currentStage || undefined,
             specialist: agentOpts.specialist,
-            harness,
+            adapter,
             model: agentOpts.model,
             status: "failed",
             attempts: 0,
             duration_ms: 0,
         };
         agentProofs.set(id, agentProof);
-        // Call identity for resume: same stage + harness + model + effort + turns + schema
+        // Call identity for resume: same stage + adapter + model + effort + turns + schema
         // + ORIGINAL prompt → same key. Retry-mutated prompts never enter the key.
-        const key = agentCallKey(currentStage, harness, agentOpts, assignmentPrompt);
+        const key = agentCallKey(currentStage, adapter, agentOpts, assignmentPrompt);
         const cached = resumeCache.get(key);
         if (cached) {
             // Exact-run replay skips dispatch authorization because no dispatch
@@ -610,11 +647,11 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             agentsCached++;
             agentProof.status = "cached";
             agentProof.result = digestResult(cached.value, cached.kind);
-            journal("agent.cached", {
+            transcript("agent.cached", {
                 id,
                 label,
                 key,
-                harness,
+                adapter,
                 specialist: agentOpts.specialist ?? null,
                 model: agentOpts.model ?? null,
                 kind: cached.kind,
@@ -627,7 +664,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 phase: "dispatch",
                 action: "spawn agent",
                 path: executionCwd,
-                harness,
+                adapter,
                 model: agentOpts.model,
                 effort: agentOpts.effort,
                 max_attempts: maxAttempts,
@@ -649,8 +686,8 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                     projectedCost = candidate;
                 }
                 catch (error) {
-                    journal("policy.cost_estimate_failed", {
-                        harness,
+                    transcript("policy.cost_estimate_failed", {
+                        adapter,
                         model: agentOpts.model ?? null,
                         error: boundedPolicyReason(error.message),
                     });
@@ -688,17 +725,17 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 throw error;
             }
         }
-        // Billing safeguard: on a harness's FIRST spawn this run, classify which
+        // Billing safeguard: on a adapter's FIRST spawn this run, classify which
         // auth its children will use and refuse the silent-override state (an
         // exported API key shadowing a stored subscription login) unless the
         // caller explicitly opted into API billing. Cached agents never reach
         // this — no spawn, no billing.
         try {
-            if (!billingProbed.has(harness)) {
-                const probe = (opts.probeBilling ?? probeBilling)(harness);
-                billingProbed.set(harness, probe);
-                journal("billing.probe", {
-                    harness,
+            if (!billingProbed.has(adapter)) {
+                const probe = (opts.probeBilling ?? probeBilling)(adapter);
+                billingProbed.set(adapter, probe);
+                transcript("billing.probe", {
+                    adapter,
                     mode: subscriptionOnly ? "subscription" : probe.mode,
                     api_key_source: probe.apiKeySource,
                     login: probe.login,
@@ -706,26 +743,26 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 });
                 if (subscriptionOnly) {
                     if (probe.login === "absent") {
-                        throw new Error(`subscription-only: no stored login detected for ${harness}; ` +
-                            `log the harness CLI in (or drop --subscription-only for a key-only host)`);
+                        throw new Error(`subscription-only: no stored login detected for ${adapter}; ` +
+                            `log the adapter CLI in (or drop --subscription-only for a key-only host)`);
                     }
-                    log(`[billing] ${harness}: subscription-only (API-key vars scrubbed from child env)`);
+                    log(`[billing] ${adapter}: subscription-only (API-key vars scrubbed from child env)`);
                 }
                 else if (probe.mode === "api-key-override" && !allowApiBilling) {
-                    throw new Error(`${probe.apiKeySource} is set AND a stored ${harness} login exists — the key silently ` +
+                    throw new Error(`${probe.apiKeySource} is set AND a stored ${adapter} login exists — the key silently ` +
                         `overrides your subscription auth, so children would bill per-token API rates. ` +
                         `Either unset ${probe.apiKeySource}, run with --subscription-only to scrub it from ` +
                         `child envs, or pass --allow-api-billing if API billing is intended`);
                 }
                 else if (probe.mode === "api-key") {
-                    log(`[billing] ${harness}: API-key billing (${probe.apiKeySource}; no stored login detected) — ` +
+                    log(`[billing] ${adapter}: API-key billing (${probe.apiKeySource}; no stored login detected) — ` +
                         `children bill per-token rates`);
                 }
                 else if (probe.mode === "api-key-override") {
-                    log(`[billing] ${harness}: API-key billing (--allow-api-billing; key overrides stored login)`);
+                    log(`[billing] ${adapter}: API-key billing (--allow-api-billing; key overrides stored login)`);
                 }
                 else {
-                    log(`[billing] ${harness}: subscription login`);
+                    log(`[billing] ${adapter}: subscription login`);
                 }
             }
         }
@@ -743,16 +780,16 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             agentsSpawned++;
         await acquire();
         try {
-            journal("agent.start", {
+            transcript("agent.start", {
                 id,
                 label,
                 key,
-                harness,
+                adapter,
                 specialist: agentOpts.specialist ?? null,
                 model: agentOpts.model ?? null,
                 effort: agentOpts.effort ?? null,
             });
-            log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${harness}] ${label}`);
+            log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${adapter}] ${label}`);
             let attemptPrompt = dispatchPrompt;
             let last = null;
             let agentCostUsd = 0;
@@ -765,6 +802,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                     maxTurns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
                     cwd: executionCwd,
                     runId,
+                    agentId: id,
                     subscriptionOnly,
                     filesystemPolicy,
                 });
@@ -773,7 +811,13 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 agentCostUsd += last.costUsd ?? 0;
                 costUsd += last.costUsd ?? 0;
                 if (!last.ok) {
-                    journal("agent.attempt_failed", { id, attempt, error: last.error });
+                    transcript("agent.attempt_failed", { id, attempt, error: last.error });
+                    // ADR 0046: an environment failure (the binary was absent) cannot be
+                    // helped by retrying an unchanged environment, so stop the in-agent
+                    // retry too — not just the outer attempt/replan budget. An upstream
+                    // refusal keeps retrying here: the vendor may recover mid-loop.
+                    if (last.class === "environment")
+                        break;
                     continue; // spawn-level failure: retry with the original prompt
                 }
                 if (!agentOpts.schema) {
@@ -782,7 +826,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                         agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
                     agentProof.session_id = last.sessionId;
                     agentProof.result = digestResult(last.text, "text");
-                    journalAgentEnd({
+                    transcriptAgentEnd({
                         id,
                         key,
                         attempts: attempt,
@@ -803,7 +847,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                         agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
                     agentProof.session_id = last.sessionId;
                     agentProof.result = digestResult(parsed.value, "json");
-                    journalAgentEnd({
+                    transcriptAgentEnd({
                         id,
                         key,
                         attempts: attempt,
@@ -814,7 +858,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                     }, "json", parsed.value);
                     return parsed.value;
                 }
-                journal("agent.schema_retry", { id, attempt, problems });
+                transcript("agent.schema_retry", { id, attempt, problems });
                 // Keep the original cache identity while making the actual output
                 // contract explicit. A full bounded copy of the rejected value lets the
                 // child repair omissions instead of reconstructing an unseen object.
@@ -833,7 +877,14 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 agentCostUsd > 0 || last?.costUsd !== undefined ? agentCostUsd : undefined;
             agentProof.session_id = last?.sessionId;
             agentProof.error = reason;
-            journal("agent.failed", { id, error: reason });
+            // Carry the spawn class (environment/upstream) onto the proof only when the
+            // final outcome was a spawn failure. A schema failure after a spawn that
+            // reached the model is a work failure — left unclassed (charged). An
+            // earlier attempt that transiently failed and then succeeded returned
+            // above, so this only fires when the agent genuinely failed.
+            if (last && !last.ok && last.class)
+                agentProof.class = last.class;
+            transcript("agent.failed", { id, error: reason });
             throw new Error(`agent ${proofLabel}: ${reason}`);
         }
         catch (error) {
@@ -850,13 +901,13 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         // concurrency. A rejected thunk lands as null so one bad item can't kill
         // the batch — the script filters and routes.
         return Promise.all(thunks.map((t) => t().catch((err) => {
-            journal("parallel.item_failed", { error: err.message });
+            transcript("parallel.item_failed", { error: err.message });
             return null;
         })));
     };
     const stage = (title) => {
         currentStage = title;
-        journal("stage.start", { title });
+        transcript("stage.start", { title });
         log(`[${name}] ── stage: ${title}`);
     };
     const evidence = (input) => {
@@ -868,7 +919,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         });
         evidenceSeq++;
         evidenceRecords.push(record);
-        journal("evidence.recorded", { ...record });
+        transcript("evidence.recorded", { ...record });
         return record.id;
     };
     const authorize = async (input) => {
@@ -886,6 +937,16 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             current_cost_usd: round4(costUsd),
         });
     };
+    const blocked = (input) => {
+        const reason = input.reason.trim();
+        if (!reason)
+            throw new Error("ctx.blocked() requires a reason");
+        transcript("run.blocked", {
+            reason,
+            ...(input.decision ? { decision_id: input.decision } : {}),
+        });
+        throw new WorkflowBlockedError(reason, input.decision);
+    };
     const ctx = {
         work: workContext,
         attempt: attemptContext,
@@ -895,17 +956,18 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         log,
         evidence,
         authorize,
+        blocked,
     };
     try {
         if (resumeState) {
-            journal("run.resume", {
+            transcript("run.resume", {
                 approval_id: resumeState.approvalId,
                 script: absScript,
                 resumed_at: new Date().toISOString(),
             });
         }
         else {
-            journal("run.start", {
+            transcript("run.start", {
                 name,
                 work_item_id: opts.workItemId ?? null,
                 work_context: workContext ?? null,
@@ -938,7 +1000,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
         if (workspaceAttestation && workspaceAttestation.status !== "ok") {
             throw new Error(`terminal workspace attestation ${workspaceAttestation.status}: ${workspaceAttestation.provider_drift.join("; ") || "provider could not prove the workspace"}`);
         }
-        journal("run.end", {
+        transcript("run.end", {
             ok: true,
             agents: agentsSpawned,
             cached: agentsCached,
@@ -957,13 +1019,13 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 startedAt,
                 endedAt,
                 durationMs,
-                journalPath,
+                transcriptPath,
                 before: executionRepoBefore,
                 after: snapshotRepo(executionCwd),
                 agents: Array.from(agentProofs.values()),
                 evidence: evidenceRecords,
-                harnessEvidence: opts.harnessEvidence,
-                harnessAttestations: opts.harnessAttestations,
+                adapterEvidence: opts.adapterEvidence,
+                adapterAttestations: opts.adapterAttestations,
                 sandboxProjection: sandboxProjectionEvidence(filesystemPolicy, gitWrite),
                 policy: policy
                     ? {
@@ -992,12 +1054,12 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             agentsCached,
             costUsd: round4(costUsd),
             durationMs,
-            journalPath,
+            transcriptPath,
             proofPath,
             acceptance: proof.acceptance.summary,
             contextTokensPerChildEstimate,
             billing: Array.from(billingProbed.values()).map((p) => ({
-                harness: p.harness,
+                adapter: p.adapter,
                 mode: subscriptionOnly ? "subscription" : p.mode,
             })),
             policy: proof.policy?.summary,
@@ -1013,7 +1075,7 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
             throw err;
         const endedAt = new Date().toISOString();
         const durationMs = Date.now() - t0;
-        journal("run.end", {
+        transcript("run.end", {
             ok: false,
             error: err.message,
             agents: agentsSpawned,
@@ -1036,13 +1098,13 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 startedAt,
                 endedAt,
                 durationMs,
-                journalPath,
+                transcriptPath,
                 before: executionRepoBefore,
                 after: snapshotRepo(executionCwd),
                 agents: Array.from(agentProofs.values()),
                 evidence: evidenceRecords,
-                harnessEvidence: opts.harnessEvidence,
-                harnessAttestations: opts.harnessAttestations,
+                adapterEvidence: opts.adapterEvidence,
+                adapterAttestations: opts.adapterAttestations,
                 sandboxProjection: sandboxProjectionEvidence(filesystemPolicy, gitWrite),
                 policy: policy
                     ? {
@@ -1056,6 +1118,12 @@ async function executeWorkflow(scriptPath, absScript, opts, resumeState, workCon
                 workspaceAttestation,
                 workspaceFallback,
                 error: err.message,
+                // A deliberate stop-on-human, not a work failure. Overrides whatever the
+                // agents' own classes would have derived: the script's determination is
+                // the more specific fact about why this run ended.
+                blocked: err instanceof WorkflowBlockedError
+                    ? { reason: err.reason, decisionId: err.decisionId }
+                    : undefined,
             });
             writeWorkflowProof(proofPath, proof);
         }
@@ -1078,10 +1146,10 @@ function boundedSchemaReply(value) {
 }
 /** Stable identity for one agent() call, for the resume cache. The ORIGINAL
  * prompt (never a retry-mutated one) plus everything that changes behavior. */
-function agentCallKey(stage, harness, agentOpts, prompt) {
+function agentCallKey(stage, adapter, agentOpts, prompt) {
     const parts = [
         stage,
-        harness,
+        adapter,
         agentOpts.model ?? null,
         agentOpts.effort ?? null,
         agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
@@ -1110,14 +1178,14 @@ function estimateInstructionTokens(cwd) {
     }
     return 0;
 }
-/** Load a prior run's journal into a key → result map. Only `agent.end`
+/** Load a prior run's transcript into a key → result map. Only `agent.end`
  * entries (completed, validated) are resumable; failed or retried-out agents
- * re-run live. Unreadable journal → error (a typo'd run id should fail loud,
+ * re-run live. Unreadable transcript → error (a typo'd run id should fail loud,
  * not silently run everything fresh). */
 function loadResumeCache(coordRoot, resumeFrom) {
-    const path = join(coordRoot, ".harnery", "workflows", resumeFrom, "journal.jsonl");
+    const path = join(coordRoot, ".harnery", "workflows", resumeFrom, "transcript.jsonl");
     if (!existsSync(path)) {
-        throw new Error(`--resume-from ${resumeFrom}: no journal at ${path}`);
+        throw new Error(`--resume-from ${resumeFrom}: no transcript at ${path}`);
     }
     const cache = new Map();
     for (const line of readFileSync(path, "utf8").split("\n")) {