harnery 0.30.0 → 0.31.1

package/src/core/{scratch → journal}/index.ts

@@ -19,7 +19,7 @@ import {
 } from "../agents/index.ts";
 
 /**
- * Agent scratchpad: per-agent markdown journal at `.harnery/scratch/<instance_id>.md`.
+ * Agent journal: per-agent markdown journal at `.harnery/journal/<instance_id>.md`.
  *
  * Rules:
  *   - Single writer (the agent itself, via this lib). Peers read but never write.
@@ -27,12 +27,12 @@ import {
  *   - Strict entry-header format: `## <Chicago datetime> · <category>`. The
  *     linter enforces this so format violations are impossible at the write path.
  *   - 50 KB hard cap; auto-prunes oldest entries when exceeded.
- *   - SessionEnd hook archives to `.harnery/scratch/archived/<instance_id>-<ts>.md`;
+ *   - SessionEnd hook archives to `.harnery/journal/archived/<instance_id>-<ts>.md`;
  *     SessionStart janitor deletes archives older than 7 days + surfaces the
  *     most-recent archive as a recovery cue.
  */
 
-export const SCRATCH_CATEGORIES = [
+export const JOURNAL_CATEGORIES = [
   "note",
   "plan",
   "decision",
@@ -42,27 +42,27 @@ export const SCRATCH_CATEGORIES = [
   "handoff",
 ] as const;
 
-export type ScratchCategory = (typeof SCRATCH_CATEGORIES)[number];
+export type JournalCategory = (typeof JOURNAL_CATEGORIES)[number];
 
-export const MAX_SCRATCH_BYTES = 50 * 1024;
-export const WARN_SCRATCH_BYTES = 40 * 1024;
+export const MAX_JOURNAL_BYTES = 50 * 1024;
+export const WARN_JOURNAL_BYTES = 40 * 1024;
 export const ARCHIVE_RETENTION_DAYS = 7;
 
 /** Entry-header regex: `## 2026-05-15 1:48 AM CDT · note` */
 export const ENTRY_HEADER_RE =
   /^## (\d{4}-\d{2}-\d{2}) (\d{1,2}):(\d{2}) (AM|PM) (CDT|CST) · (note|plan|decision|blocker|question|done|handoff)$/;
 
-/** First line of every scratchpad file: this prefix followed by the agent name. */
-export const SCRATCHPAD_HEADER_PREFIX = "# Scratchpad: agent-";
+/** First line of every journal file: this prefix followed by the agent name. */
+export const JOURNAL_HEADER_PREFIX = "# Journal: agent-";
 
-export interface ScratchEntry {
+export interface JournalEntry {
   ts_iso: string; // canonical ISO (computed from Chicago wall time at write)
   ts_display: string; // "2026-05-15 1:48 AM CDT", what's in the file
-  category: ScratchCategory;
+  category: JournalCategory;
   body: string;
 }
 
-export interface ScratchHeader {
+export interface JournalHeader {
   name: string;
   session_id: string;
   machine: string;
@@ -70,32 +70,32 @@ export interface ScratchHeader {
   last_updated: string;
 }
 
-export interface ScratchDoc {
+export interface JournalDoc {
   path: string;
-  header: ScratchHeader;
-  entries: ScratchEntry[];
+  header: JournalHeader;
+  entries: JournalEntry[];
   bytes: number;
 }
 
 // ─── Paths ────────────────────────────────────────────────────────────────
 
-export function scratchDir(): string {
+export function journalDir(): string {
   const root = monorepoRoot();
   if (!root) throw new Error("Not in a coord-aware repo (coord_root() returned null).");
-  const dir = resolve(root, ".harnery", "scratch");
+  const dir = resolve(root, ".harnery", "journal");
   mkdirSync(dir, { recursive: true });
   return dir;
 }
 
 export function archiveDir(): string {
-  const dir = resolve(scratchDir(), "archived");
+  const dir = resolve(journalDir(), "archived");
   mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-export function scratchPath(instanceId: string): string {
+export function journalPath(instanceId: string): string {
   assertSafeInstanceId(instanceId);
-  return resolveContainedFile(scratchDir(), `${instanceId}.md`);
+  return resolveContainedFile(journalDir(), `${instanceId}.md`);
 }
 
 // ─── Chicago time formatting ──────────────────────────────────────────────
@@ -127,22 +127,22 @@ export function formatChicago(d: Date = new Date()): string {
 
 // ─── Parse / serialize ────────────────────────────────────────────────────
 
-/** Parse a scratchpad file (or empty content) into a structured doc. */
-export function parseScratch(path: string, content: string): ScratchDoc {
+/** Parse a journal file (or empty content) into a structured doc. */
+export function parseJournal(path: string, content: string): JournalDoc {
   const lines = content.split("\n");
-  const header: ScratchHeader = {
+  const header: JournalHeader = {
     name: "unknown",
     session_id: "",
     machine: "",
     started: "",
     last_updated: "",
   };
-  const entries: ScratchEntry[] = [];
+  const entries: JournalEntry[] = [];
 
   let i = 0;
   // ── header ──
-  if (lines[i]?.startsWith(SCRATCHPAD_HEADER_PREFIX)) {
-    header.name = lines[i].replace(SCRATCHPAD_HEADER_PREFIX, "").trim();
+  if (lines[i]?.startsWith(JOURNAL_HEADER_PREFIX)) {
+    header.name = lines[i].replace(JOURNAL_HEADER_PREFIX, "").trim();
     i++;
   }
   for (; i < lines.length; i++) {
@@ -181,7 +181,7 @@ export function parseScratch(path: string, content: string): ScratchDoc {
     entries.push({
       ts_iso: chicagoToIso(date, hour, minute, period as "AM" | "PM", tz as "CDT" | "CST"),
       ts_display: `${date} ${hour}:${minute} ${period} ${tz}`,
-      category: category as ScratchCategory,
+      category: category as JournalCategory,
       body: bodyLines.join("\n").trim(),
     });
     currentHeader = null;
@@ -203,9 +203,9 @@ export function parseScratch(path: string, content: string): ScratchDoc {
 }
 
 /** Serialize a parsed doc back to markdown. */
-export function serializeScratch(doc: ScratchDoc): string {
+export function serializeJournal(doc: JournalDoc): string {
   const lines: string[] = [];
-  lines.push(`${SCRATCHPAD_HEADER_PREFIX}${doc.header.name}`);
+  lines.push(`${JOURNAL_HEADER_PREFIX}${doc.header.name}`);
   if (doc.header.session_id) lines.push(`session_id: ${doc.header.session_id}`);
   if (doc.header.machine) lines.push(`machine: ${doc.header.machine}`);
   if (doc.header.started) lines.push(`started: ${doc.header.started}`);
@@ -245,13 +245,13 @@ export interface LintIssue {
   message: string;
 }
 
-export function lintScratch(content: string, byteCap = MAX_SCRATCH_BYTES): LintIssue[] {
+export function lintJournal(content: string, byteCap = MAX_JOURNAL_BYTES): LintIssue[] {
   const issues: LintIssue[] = [];
   const lines = content.split("\n");
 
   // Frontmatter checks
-  if (!lines[0]?.startsWith(SCRATCHPAD_HEADER_PREFIX)) {
-    issues.push({ line: 1, message: `missing '${SCRATCHPAD_HEADER_PREFIX}<name>' header` });
+  if (!lines[0]?.startsWith(JOURNAL_HEADER_PREFIX)) {
+    issues.push({ line: 1, message: `missing '${JOURNAL_HEADER_PREFIX}<name>' header` });
   }
   for (const required of ["session_id:", "machine:", "started:"]) {
     if (!lines.slice(0, 10).some((l) => l.startsWith(required))) {
@@ -310,17 +310,17 @@ export function lintScratch(content: string, byteCap = MAX_SCRATCH_BYTES): LintI
 
 export function appendEntry(
   instanceId: string,
-  category: ScratchCategory,
+  category: JournalCategory,
   body: string,
-): ScratchDoc {
+): JournalDoc {
   const hb = readHeartbeat(instanceId);
-  const path = scratchPath(instanceId);
-  let doc: ScratchDoc;
+  const path = journalPath(instanceId);
+  let doc: JournalDoc;
   if (existsSync(path)) {
-    doc = parseScratch(path, readFileSync(path, "utf8"));
+    doc = parseJournal(path, readFileSync(path, "utf8"));
   } else {
     // Seed `started` from the heartbeat's session start so cross-agent writes
-    // (`harn agents ping`) don't stamp the peer's scratchpad with our wall-clock.
+    // (`harn agents ping`) don't stamp the peer's journal with our wall-clock.
     const startedSeed = hb?.started_at ? formatChicago(new Date(hb.started_at)) : formatChicago();
     doc = {
       path,
@@ -337,7 +337,7 @@ export function appendEntry(
   }
 
   const now = new Date();
-  const entry: ScratchEntry = {
+  const entry: JournalEntry = {
     ts_iso: now.toISOString(),
     ts_display: formatChicago(now),
     category,
@@ -350,22 +350,22 @@ export function appendEntry(
   }
 
   // Prune from the tail until under cap.
-  let serialized = serializeScratch(doc);
+  let serialized = serializeJournal(doc);
   let pruned = 0;
-  while (Buffer.byteLength(serialized, "utf8") > MAX_SCRATCH_BYTES && doc.entries.length > 1) {
+  while (Buffer.byteLength(serialized, "utf8") > MAX_JOURNAL_BYTES && doc.entries.length > 1) {
     doc.entries.pop();
     pruned++;
-    serialized = serializeScratch(doc);
+    serialized = serializeJournal(doc);
   }
   if (pruned > 0) {
-    const pruneEntry: ScratchEntry = {
+    const pruneEntry: JournalEntry = {
       ts_iso: new Date().toISOString(),
       ts_display: formatChicago(),
       category: "note",
-      body: `(auto-pruned ${pruned} oldest entries to stay under ${MAX_SCRATCH_BYTES}-byte cap)`,
+      body: `(auto-pruned ${pruned} oldest entries to stay under ${MAX_JOURNAL_BYTES}-byte cap)`,
     };
     doc.entries.unshift(pruneEntry);
-    serialized = serializeScratch(doc);
+    serialized = serializeJournal(doc);
   }
   doc.bytes = Buffer.byteLength(serialized, "utf8");
 
@@ -381,9 +381,9 @@ export function appendEntry(
 // ─── Archive lifecycle ────────────────────────────────────────────────────
 
 /** Move `<owner>.md` → `archived/<owner>-<ts>.md`. No-op if missing. Returns archive path (or null). */
-export function archiveScratch(instanceId: string): string | null {
+export function archiveJournal(instanceId: string): string | null {
   assertSafeInstanceId(instanceId);
-  const src = scratchPath(instanceId);
+  const src = journalPath(instanceId);
   if (!existsSync(src)) return null;
   const ts = new Date().toISOString().replace(/[:.]/g, "-");
   const dest = resolveContainedFile(archiveDir(), `${instanceId}-${ts}.md`);
@@ -412,16 +412,16 @@ export function pruneArchives(days = ARCHIVE_RETENTION_DAYS): number {
   return deleted;
 }
 
-/** Sweep `.harnery/scratch/<owner>.md` files whose corresponding heartbeat is gone. */
-export function sweepOrphanScratchpads(): string[] {
-  const dir = scratchDir();
+/** Sweep `.harnery/journal/<owner>.md` files whose corresponding heartbeat is gone. */
+export function sweepOrphanJournals(): string[] {
+  const dir = journalDir();
   const archived: string[] = [];
   for (const f of readdirSync(dir)) {
     if (!f.endsWith(".md")) continue;
     const instanceId = f.replace(/\.md$/, "");
     const hb = readHeartbeat(instanceId);
     if (!hb) {
-      const dest = archiveScratch(instanceId);
+      const dest = archiveJournal(instanceId);
       if (dest) archived.push(dest);
     }
   }
@@ -457,10 +457,10 @@ export function currentOwnerOrThrow(): string {
   return owner;
 }
 
-export function loadScratch(instanceId: string): ScratchDoc | null {
-  const path = scratchPath(instanceId);
+export function loadJournal(instanceId: string): JournalDoc | null {
+  const path = journalPath(instanceId);
   if (!existsSync(path)) return null;
-  return parseScratch(path, readFileSync(path, "utf8"));
+  return parseJournal(path, readFileSync(path, "utf8"));
 }
 
 /** Resolve an agent name → instance_id by walking active heartbeats (case-insensitive). */

package/src/core/policy/evaluate.ts

@@ -22,7 +22,7 @@ const POLICY_FIELDS = new Set([
   "name",
   "max_cost_usd",
   "unknown_cost",
-  "allowed_harnesses",
+  "allowed_adapters",
   "allowed_models",
   "allowed_paths",
   "network",
@@ -59,7 +59,7 @@ export function normalizePolicy(
     name: boundedString(input.name ?? "workflow policy", "policy name", MAX_NAME),
     max_cost_usd: optionalMoney(input.max_cost_usd, "max_cost_usd"),
     unknown_cost: enumValue(input.unknown_cost ?? "deny", ["ask", "deny"], "unknown_cost"),
-    allowed_harnesses: optionalStringList(input.allowed_harnesses, "allowed_harnesses"),
+    allowed_adapters: optionalStringList(input.allowed_adapters, "allowed_adapters"),
     allowed_models: optionalStringList(input.allowed_models, "allowed_models"),
     allowed_paths: optionalPathList(input.allowed_paths, baseDir),
     network: enumValue(input.network ?? "deny", VERDICTS, "network"),
@@ -83,12 +83,12 @@ export function evaluatePolicy(
     rules.push({ code, verdict, reason });
   };
 
-  if (policy.allowed_harnesses && request.phase === "dispatch") {
-    if (!request.harness || !policy.allowed_harnesses.includes(request.harness)) {
+  if (policy.allowed_adapters && request.phase === "dispatch") {
+    if (!request.adapter || !policy.allowed_adapters.includes(request.adapter)) {
       add(
-        "harness_not_allowed",
+        "adapter_not_allowed",
         "deny",
-        `harness ${JSON.stringify(request.harness ?? "unknown")} is not allowed`,
+        `adapter ${JSON.stringify(request.adapter ?? "unknown")} is not allowed`,
       );
     }
   }
@@ -172,7 +172,7 @@ export function evaluatePolicy(
   };
 }
 
-/** Bound and normalize the receipt-safe subset before it reaches a journal or proof. */
+/** Bound and normalize the receipt-safe subset before it reaches a transcript or proof. */
 export function summarizePolicyRequest(input: PolicyRequest): PolicyRequestSummary {
   if (!isRecord(input)) throw new Error("policy request must be an object");
   const phase = enumValue(input.phase, ["dispatch", "external_mutation"], "policy phase");
@@ -186,7 +186,7 @@ export function summarizePolicyRequest(input: PolicyRequest): PolicyRequestSumma
     phase,
     action: boundedString(input.action, "policy action", MAX_FIELD),
     path: optionalBounded(input.path, "policy path"),
-    harness: optionalBounded(input.harness, "policy harness"),
+    adapter: optionalBounded(input.adapter, "policy adapter"),
     model: optionalBounded(input.model, "policy model"),
     effort: optionalBounded(input.effort, "policy effort"),
     max_attempts: optionalWholeNumber(input.max_attempts, "policy max_attempts", 1),

package/src/core/policy/types.ts

@@ -12,7 +12,7 @@ export interface PolicySpec {
   max_cost_usd?: number;
   /** Applied when a cost ceiling exists but the host cannot price a dispatch. */
   unknown_cost?: Exclude<PolicyVerdict, "allow">;
-  allowed_harnesses?: readonly string[];
+  allowed_adapters?: readonly string[];
   allowed_models?: readonly string[];
   /** Absolute paths, or paths relative to the policy file. */
   allowed_paths?: readonly string[];
@@ -27,7 +27,7 @@ export interface NormalizedPolicy {
   name: string;
   max_cost_usd?: number;
   unknown_cost: Exclude<PolicyVerdict, "allow">;
-  allowed_harnesses?: readonly string[];
+  allowed_adapters?: readonly string[];
   allowed_models?: readonly string[];
   allowed_paths?: readonly string[];
   network: PolicyVerdict;
@@ -39,7 +39,7 @@ export interface PolicyRequest {
   phase: PolicyPhase;
   action: string;
   path?: string;
-  harness?: string;
+  adapter?: string;
   model?: string;
   effort?: string;
   max_attempts?: number;

package/src/core/work/state.ts

@@ -16,9 +16,9 @@ import { hostname } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { readWorkflowApproval } from "../workflow/approvals.ts";
 import { stableDigest } from "../workflow/durable-record.ts";
-import { WORKFLOW_JOURNAL_EVENT_BYTES, workflowJournalPath } from "../workflow/journal.ts";
 import { readWorkflowProof } from "../workflow/proof.ts";
 import { readWorkflowRunManifest, workflowScriptDigest } from "../workflow/run-state.ts";
+import { WORKFLOW_TRANSCRIPT_EVENT_BYTES, workflowTranscriptPath } from "../workflow/transcript.ts";
 import { isWorkspaceBoundExecutionEvidence } from "../workflow/workspaces/validate.ts";
 
 export const WORK_INTENT_SCHEMA_VERSION = 1 as const;
@@ -42,7 +42,7 @@ const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
 /** Default ceiling on consecutive uncharged attempts (ADR 0046). Kept low: each
  * one is a real vendor round-trip, so a handful gives a transient outage room
  * to recover before the item stops and names the outside service. There is no
- * backoff between them beyond the cadence of the supervisor and the vendor's own
+ * backoff between them beyond the cadence of the governor and the vendor's own
  * responses, which is why the bound stays small. */
 const DEFAULT_MAX_UNCHARGED_ATTEMPTS = 3;
 
@@ -136,14 +136,17 @@ export interface WorkAttempt {
   run_id: string;
   started_at: string;
   trigger?: WorkAttemptTrigger;
-  status: "running" | "parked" | "succeeded" | "failed" | "lost" | "journal_unreadable";
+  status: "running" | "parked" | "succeeded" | "failed" | "lost" | "transcript_unreadable";
   approval_id?: string;
   proof_path?: string;
-  journal_error?: string;
+  transcript_error?: string;
   /** Why this failed attempt was uninformative about the work (ADR 0046), read
    * from the proof's run.class. Absent ⇒ the attempt is charged, exactly as
    * before ADR 0046 (which is also how a proof without a class reads). */
-  uncharged?: "environment" | "upstream";
+  uncharged?: "environment" | "upstream" | "decision";
+  /** Docket id this attempt stopped on, when uncharged is "decision" and the
+   * script named one. Lets the projection point at the question itself. */
+  blocked_on?: string;
 }
 
 export interface WorkProjection {
@@ -165,6 +168,11 @@ export interface WorkProjection {
   latest_run_id?: string;
   approval_id?: string;
   proof_path?: string;
+  /** Set when this item stopped because a human must rule. The value is the
+   * docket id when the script named one, else the empty string — present either
+   * way, so a reader can distinguish "waiting on a person" from every other
+   * terminal block without parsing the reason prose. */
+  blocked_on_decision?: string;
   updated_at: string;
 }
 
@@ -500,12 +508,12 @@ function deriveWorkProjection(
     };
   }
   const attemptsRemaining = intent.max_attempts - chargedAttempts;
-  if (latest.status === "journal_unreadable") {
+  if (latest.status === "transcript_unreadable") {
     return {
       ...base,
       state: "blocked",
-      reason: `workflow attempt ${latest.number} journal is unreadable: ${
-        latest.journal_error ?? "unknown journal read error"
+      reason: `workflow attempt ${latest.number} transcript is unreadable: ${
+        latest.transcript_error ?? "unknown transcript read error"
       }`,
       next_action: attemptsRemaining > 0 ? "retry" : "none",
     };
@@ -516,7 +524,7 @@ function deriveWorkProjection(
   if (latest.status === "failed" && latest.uncharged === "environment") {
     // A missing precondition. The operator chose to STOP the item immediately
     // rather than retry an unchanged environment (ADR 0046); next_action "none"
-    // stops the supervisor. A human who fixes the environment can still force a
+    // stops the governor. A human who fixes the environment can still force a
     // retry — the attempt was uncharged, so the budget is intact.
     return {
       ...base,
@@ -525,6 +533,20 @@ function deriveWorkProjection(
       next_action: "none",
     };
   }
+  if (latest.status === "failed" && latest.uncharged === "decision") {
+    // The script did its job and the answer was "a person has to settle this".
+    // Terminal for the same reason "environment" is terminal — retrying cannot
+    // change the blocker — but the fix is a ruling, not a repair, so the reason
+    // names the decision instead of a precondition. Uncharged, so once the
+    // decision lands the item can be retried with its budget intact.
+    return {
+      ...base,
+      state: "blocked",
+      reason: decisionBlockedReason(latest),
+      next_action: "none",
+      blocked_on_decision: latest.blocked_on ?? "",
+    };
+  }
   if (latest.status === "failed" && latest.uncharged === "upstream") {
     // Count trailing consecutive uncharged attempts in the current window. The
     // bound is the only brake on an outage that never ends, so at the limit the
@@ -574,7 +596,7 @@ function unchargedProofError(attempt: WorkAttempt): string | undefined {
     const run = proof.run;
     const error =
       run && typeof run === "object" ? (run as Record<string, unknown>).error : undefined;
-    return typeof error === "string" && error.trim() ? boundedJournalError(error) : undefined;
+    return typeof error === "string" && error.trim() ? boundedTranscriptError(error) : undefined;
   } catch {
     return undefined;
   }
@@ -591,6 +613,21 @@ function upstreamReason(attempt: WorkAttempt): string {
   return unchargedProofError(attempt) ?? "the vendor was reached and refused";
 }
 
+/** Operator-facing reason for a run that stopped on a human. Reads the script's
+ * own sentence out of the proof and drops the WorkflowBlockedError prefix the
+ * engine added, so the projection says the thing once rather than twice. */
+function decisionBlockedReason(attempt: WorkAttempt): string {
+  const raw = unchargedProofError(attempt);
+  const detail = raw
+    ?.replace(/^blocked on decision \S+: /, "")
+    .replace(/^blocked pending a human decision: /, "")
+    .trim();
+  const named = attempt.blocked_on ? ` (decision ${attempt.blocked_on})` : "";
+  return detail
+    ? `a human must rule before this can proceed: ${detail}${named}`
+    : `a human must rule before this can proceed${named}`;
+}
+
 function inspectAttempt(
   coordRoot: string,
   event: WorkEvent,
@@ -659,24 +696,29 @@ function inspectAttempt(
     // failed attempt: a succeeded run never carries a class.
     if (
       attempt.status === "failed" &&
-      (proof.run.class === "environment" || proof.run.class === "upstream")
+      (proof.run.class === "environment" ||
+        proof.run.class === "upstream" ||
+        proof.run.class === "decision")
     ) {
       attempt.uncharged = proof.run.class;
+      if (proof.run.class === "decision" && typeof proof.run.decision_id === "string") {
+        attempt.blocked_on = proof.run.decision_id;
+      }
     }
     return attempt;
   }
-  const journalPath = workflowJournalPath(coordRoot, runId);
-  if (existsSync(journalPath)) {
+  const transcriptPath = workflowTranscriptPath(coordRoot, runId);
+  if (existsSync(transcriptPath)) {
     let parked: string | undefined;
     let resumed = false;
     try {
       for (const line of readBoundedLines(
-        journalPath,
+        transcriptPath,
         MAX_EVENTS_BYTES,
-        WORKFLOW_JOURNAL_EVENT_BYTES,
-        "workflow journal",
+        WORKFLOW_TRANSCRIPT_EVENT_BYTES,
+        "workflow transcript",
       )) {
-        const value = parseObject(line, `workflow run ${runId} journal`);
+        const value = parseObject(line, `workflow run ${runId} transcript`);
         if (value.event === "run.parked" && typeof value.approval_id === "string") {
           parked = value.approval_id;
           resumed = false;
@@ -692,8 +734,8 @@ function inspectAttempt(
       if (workflowResumeLeaseIsLive(coordRoot, runId)) {
         attempt.status = "running";
       } else {
-        attempt.status = "journal_unreadable";
-        attempt.journal_error = boundedJournalError((error as Error).message);
+        attempt.status = "transcript_unreadable";
+        attempt.transcript_error = boundedTranscriptError((error as Error).message);
       }
       return attempt;
     }
@@ -1171,13 +1213,13 @@ export function acquireWorkLease(coordRoot: string, workId: string): () => void
   return acquireWorkFileLease(coordRoot, workId, "lease.json", "is already active");
 }
 
-/** @internal Work journal mutation seam. */
+/** @internal Work transcript mutation seam. */
 export function acquireWorkEventLease(coordRoot: string, workId: string): () => void {
   return acquireWorkFileLease(
     coordRoot,
     workId,
     "events.lease.json",
-    "event journal is already active",
+    "event transcript is already active",
   );
 }
 
@@ -1308,8 +1350,8 @@ function readBoundedLines(
   return lines;
 }
 
-function boundedJournalError(message: string): string {
-  const normalized = message.trim() || "unknown journal read error";
+function boundedTranscriptError(message: string): string {
+  const normalized = message.trim() || "unknown transcript read error";
   return normalized.length > MAX_REASON ? normalized.slice(0, MAX_REASON) : normalized;
 }
 

package/src/core/workflow/adapters.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-adapter CLI metadata: binary names plus install/login hints, shared by
+ * the spawn adapters (a not-found error should say how to fix it, not just
+ * that it happened) and `harn doctor`'s workflow-adapter checks.
+ *
+ * Install commands are the vendors' official one-liners; they drift rarely
+ * but they do drift — keep this module the single place they live.
+ */
+
+import { BUILTIN_ADAPTER_PROFILES } from "../adapters/profiles.ts";
+import type { AdapterName } from "./types.ts";
+
+export const ADAPTER_BINARIES: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_ADAPTER_PROFILES).map((profile) => [profile.id, profile.binary]),
+);
+
+export const ADAPTER_INSTALL_HINTS: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_ADAPTER_PROFILES).map((profile) => [profile.id, profile.installHint]),
+);
+
+/** How to authenticate each CLI with a subscription login (the billing
+ * default — see billing.ts). */
+export const ADAPTER_LOGIN_HINTS: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_ADAPTER_PROFILES).map((profile) => [profile.id, profile.loginHint]),
+);
+
+/** One-line "it's missing, here's the fix" string for spawn adapters. */
+export function notFoundError(adapter: AdapterName): string {
+  const binary = ADAPTER_BINARIES[adapter] ?? adapter;
+  const install = ADAPTER_INSTALL_HINTS[adapter] ?? "install the adapter CLI";
+  const login = ADAPTER_LOGIN_HINTS[adapter] ?? "authenticate the adapter CLI";
+  return `${binary} CLI not found on PATH; ` + `install: ${install}  then authenticate: ${login}`;
+}

package/src/core/workflow/approvals.ts

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import type { PolicyEvaluation, PolicyRequestSummary, PolicyVerdict } from "../policy/index.ts";
-import { appendWorkflowJournalEvent } from "./journal.ts";
+import { appendWorkflowTranscriptEvent } from "./transcript.ts";
 
 export const WORKFLOW_APPROVAL_SCHEMA_VERSION = 1 as const;
 
@@ -148,7 +148,7 @@ export function resolveWorkflowApproval(input: ResolveWorkflowApprovalInput): {
       `approval ${input.approvalId} is already ${resolved.status}; conflicting ${input.verdict === "allow" ? "approval" : "denial"} refused`,
     );
   }
-  if (applied) appendResolutionJournal(input.coordRoot, resolved);
+  if (applied) appendResolutionTranscript(input.coordRoot, resolved);
   return { approval: resolved, applied };
 }
 
@@ -214,16 +214,16 @@ export function assertWorkflowRunId(runId: string): void {
   assertRunId(runId);
 }
 
-function appendResolutionJournal(coordRoot: string, approval: WorkflowApproval): void {
-  const journalPath = join(
+function appendResolutionTranscript(coordRoot: string, approval: WorkflowApproval): void {
+  const transcriptPath = join(
     coordRoot,
     ".harnery",
     "workflows",
     approval.request.run_id,
-    "journal.jsonl",
+    "transcript.jsonl",
   );
-  if (!existsSync(journalPath) || !approval.decision) return;
-  appendWorkflowJournalEvent(coordRoot, approval.request.run_id, "approval.resolved", {
+  if (!existsSync(transcriptPath) || !approval.decision) return;
+  appendWorkflowTranscriptEvent(coordRoot, approval.request.run_id, "approval.resolved", {
     ts: approval.decision.decided_at,
     stage: "",
     approval_id: approval.request.id,