harnery 0.29.0 → 0.31.0

package/dist/core/work/state.js

@@ -4,9 +4,9 @@ import { hostname } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { readWorkflowApproval } from "../workflow/approvals.js";
 import { stableDigest } from "../workflow/durable-record.js";
-import { WORKFLOW_JOURNAL_EVENT_BYTES, workflowJournalPath } from "../workflow/journal.js";
 import { readWorkflowProof } from "../workflow/proof.js";
 import { readWorkflowRunManifest, workflowScriptDigest } from "../workflow/run-state.js";
+import { WORKFLOW_TRANSCRIPT_EVENT_BYTES, workflowTranscriptPath } from "../workflow/transcript.js";
 import { isWorkspaceBoundExecutionEvidence } from "../workflow/workspaces/validate.js";
 export const WORK_INTENT_SCHEMA_VERSION = 1;
 export const WORK_EVENT_SCHEMA_VERSION = 1;
@@ -25,6 +25,12 @@ const MAX_EVENTS_BYTES = 4 * 1024 * 1024;
 const MAX_EVENT_BYTES = 16 * 1024;
 const MAX_EVENTS = 1_000;
 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 governor and the vendor's own
+ * responses, which is why the bound stays small. */
+const DEFAULT_MAX_UNCHARGED_ATTEMPTS = 3;
 export function createWorkItem(input) {
     const coordRoot = resolve(input.coordRoot);
     const id = input.id ?? newWorkId();
@@ -45,6 +51,12 @@ export function createWorkItem(input) {
     if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 100) {
         throw new Error("work maxAttempts must be an integer from 1 to 100");
     }
+    const maxUnchargedAttempts = input.maxUnchargedAttempts ?? DEFAULT_MAX_UNCHARGED_ATTEMPTS;
+    if (!Number.isSafeInteger(maxUnchargedAttempts) ||
+        maxUnchargedAttempts < 1 ||
+        maxUnchargedAttempts > 100) {
+        throw new Error("work maxUnchargedAttempts must be an integer from 1 to 100");
+    }
     const acceptance = (input.acceptance ?? []).map((value, index) => boundedString(value, `work acceptance[${index}]`, MAX_ACCEPTANCE_ITEM));
     if (acceptance.length > MAX_ACCEPTANCE) {
         throw new Error(`work acceptance exceeds ${MAX_ACCEPTANCE} criteria`);
@@ -59,6 +71,7 @@ export function createWorkItem(input) {
         dependencies,
         workflow: { path: workflowPath, sha256: workflowScriptDigest(workflowPath) },
         max_attempts: maxAttempts,
+        max_uncharged_attempts: maxUnchargedAttempts,
         source,
         created_at: new Date().toISOString(),
     };
@@ -178,13 +191,18 @@ function deriveWorkProjection(coordRoot, intent, events, ignoreLease = false) {
     const terminal = latestGovernance?.event === "work.accepted" || latestGovernance?.event === "work.cancelled";
     const attemptEvents = events.filter((event) => event.event === "attempt.started");
     const attempts = attemptEvents.map((event, index) => inspectAttempt(coordRoot, event, intent, attemptEvents[index - 1]?.run_id));
+    // Charged attempts — not the raw count — are what max_attempts budgets
+    // (ADR 0046). An uncharged environment/upstream attempt still increments
+    // attempts_used (ordering + next number) but not the budget.
+    const chargedAttempts = attempts.filter((attempt) => attempt.uncharged === undefined).length;
     const base = {
         id: intent.id,
         title: intent.title,
         unresolved_dependencies: [],
         attempts,
         attempts_used: attempts.length,
-        attempts_remaining: Math.max(0, intent.max_attempts - attempts.length),
+        charged_attempts: chargedAttempts,
+        attempts_remaining: Math.max(0, intent.max_attempts - chargedAttempts),
         latest_run_id: attempts.at(-1)?.run_id,
         approval_id: attempts.at(-1)?.approval_id,
         proof_path: attempts.at(-1)?.proof_path,
@@ -266,15 +284,72 @@ function deriveWorkProjection(coordRoot, intent, events, ignoreLease = false) {
             next_action: "review",
         };
     }
-    const attemptsRemaining = intent.max_attempts - attempts.length;
-    if (latest.status === "journal_unreadable") {
+    const attemptsRemaining = intent.max_attempts - chargedAttempts;
+    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",
         };
     }
+    // Uncharged failures (ADR 0046) are handled before the ordinary work-failure
+    // path: they did not touch the work, so they neither spent the budget nor
+    // signal that retrying the work would help.
+    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 governor. A human who fixes the environment can still force a
+        // retry — the attempt was uncharged, so the budget is intact.
+        return {
+            ...base,
+            state: "blocked",
+            reason: environmentBlockedReason(latest),
+            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
+        // item stops and names the outside service — distinct from work-blocked.
+        const maxUncharged = intent.max_uncharged_attempts ?? DEFAULT_MAX_UNCHARGED_ATTEMPTS;
+        let trailingUncharged = 0;
+        for (let index = currentAttempts.length - 1; index >= 0; index--) {
+            if (currentAttempts[index].uncharged === undefined)
+                break;
+            trailingUncharged++;
+        }
+        if (trailingUncharged >= maxUncharged || attemptsRemaining <= 0) {
+            return {
+                ...base,
+                state: "blocked",
+                reason: trailingUncharged >= maxUncharged
+                    ? `blocked waiting on an outside service after ${trailingUncharged} consecutive uncharged attempt(s): ${upstreamReason(latest)}`
+                    : `workflow attempt ${latest.number} was uncharged (${upstreamReason(latest)}) but the work attempt budget is exhausted`,
+                next_action: "none",
+            };
+        }
+        return {
+            ...base,
+            state: "blocked",
+            reason: `workflow attempt ${latest.number} did not touch the work; an outside service refused: ${upstreamReason(latest)}`,
+            next_action: "retry",
+        };
+    }
     return {
         ...base,
         state: "blocked",
@@ -284,6 +359,45 @@ function deriveWorkProjection(coordRoot, intent, events, ignoreLease = false) {
         next_action: attemptsRemaining > 0 ? "retry" : "none",
     };
 }
+/** The failure reason for an uncharged attempt, read from the proof when
+ * present. Bounded so a verbose vendor transcript cannot bloat the projection
+ * reason (which is persisted verbatim into the reconciliation event). */
+function unchargedProofError(attempt) {
+    if (!attempt.proof_path)
+        return undefined;
+    try {
+        const proof = parseObject(readFileSync(attempt.proof_path, "utf8"), "workflow proof");
+        const run = proof.run;
+        const error = run && typeof run === "object" ? run.error : undefined;
+        return typeof error === "string" && error.trim() ? boundedTranscriptError(error) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function environmentBlockedReason(attempt) {
+    const detail = unchargedProofError(attempt);
+    return detail
+        ? `workflow attempt ${attempt.number} could not start; a required precondition is missing: ${detail}`
+        : `workflow attempt ${attempt.number} could not start; a required precondition is missing`;
+}
+function upstreamReason(attempt) {
+    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) {
+    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, event, intent, priorRunId) {
     const runId = event.run_id;
     const attempt = {
@@ -334,15 +448,27 @@ function inspectAttempt(coordRoot, event, intent, priorRunId) {
                 proof.acceptance.summary.unknown === 0
                 ? "succeeded"
                 : "failed";
+        // A failed attempt the run classified as uninformative about the work is
+        // uncharged (ADR 0046). Absent class ⇒ charged, as before. Read only for a
+        // failed attempt: a succeeded run never carries a class.
+        if (attempt.status === "failed" &&
+            (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;
         let resumed = false;
         try {
-            for (const line of readBoundedLines(journalPath, MAX_EVENTS_BYTES, WORKFLOW_JOURNAL_EVENT_BYTES, "workflow journal")) {
-                const value = parseObject(line, `workflow run ${runId} journal`);
+            for (const line of readBoundedLines(transcriptPath, MAX_EVENTS_BYTES, WORKFLOW_TRANSCRIPT_EVENT_BYTES, "workflow transcript")) {
+                const value = parseObject(line, `workflow run ${runId} transcript`);
                 if (value.event === "run.parked" && typeof value.approval_id === "string") {
                     parked = value.approval_id;
                     resumed = false;
@@ -361,8 +487,8 @@ function inspectAttempt(coordRoot, event, intent, priorRunId) {
                 attempt.status = "running";
             }
             else {
-                attempt.status = "journal_unreadable";
-                attempt.journal_error = boundedJournalError(error.message);
+                attempt.status = "transcript_unreadable";
+                attempt.transcript_error = boundedTranscriptError(error.message);
             }
             return attempt;
         }
@@ -596,7 +722,13 @@ function validateWorkIntent(intent, workId) {
         !/^[a-f0-9]{64}$/.test(intent.workflow.sha256) ||
         !Number.isSafeInteger(intent.max_attempts) ||
         intent.max_attempts < 1 ||
-        intent.max_attempts > 100) {
+        intent.max_attempts > 100 ||
+        // Optional for back-compat: absent on pre-ADR-0046 intents. When present it
+        // must be a valid bound.
+        (intent.max_uncharged_attempts !== undefined &&
+            (!Number.isSafeInteger(intent.max_uncharged_attempts) ||
+                intent.max_uncharged_attempts < 1 ||
+                intent.max_uncharged_attempts > 100))) {
         throw new Error(`work intent ${workId} has an unsupported or mismatched schema`);
     }
     boundedString(intent.title, "work title", MAX_TITLE);
@@ -743,9 +875,9 @@ function workDir(coordRoot, workId) {
 export function acquireWorkLease(coordRoot, workId) {
     return acquireWorkFileLease(coordRoot, workId, "lease.json", "is already active");
 }
-/** @internal Work journal mutation seam. */
+/** @internal Work transcript mutation seam. */
 export function acquireWorkEventLease(coordRoot, workId) {
-    return acquireWorkFileLease(coordRoot, workId, "events.lease.json", "event journal is already active");
+    return acquireWorkFileLease(coordRoot, workId, "events.lease.json", "event transcript is already active");
 }
 function acquireWorkFileLease(coordRoot, workId, filename, activeMessage) {
     readWorkIntent(coordRoot, workId);
@@ -862,8 +994,8 @@ function readBoundedLines(path, maxBytes, maxRecordBytes, field) {
     }
     return lines;
 }
-function boundedJournalError(message) {
-    const normalized = message.trim() || "unknown journal read error";
+function boundedTranscriptError(message) {
+    const normalized = message.trim() || "unknown transcript read error";
     return normalized.length > MAX_REASON ? normalized.slice(0, MAX_REASON) : normalized;
 }
 function parseObject(input, field) {

package/dist/core/workflow/adapters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { AdapterName } from "./types.js";
+export declare const ADAPTER_BINARIES: Record<string, string>;
+export declare const ADAPTER_INSTALL_HINTS: Record<string, string>;
+/** How to authenticate each CLI with a subscription login (the billing
+ * default — see billing.ts). */
+export declare const ADAPTER_LOGIN_HINTS: Record<string, string>;
+/** One-line "it's missing, here's the fix" string for spawn adapters. */
+export declare function notFoundError(adapter: AdapterName): string;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/core/workflow/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEnD,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAExD,CAAC;AAEF;gCACgC;AAChC,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEtD,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAK1D"}

package/dist/core/workflow/adapters.js

@@ -0,0 +1,21 @@
+/**
+ * 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.js";
+export const ADAPTER_BINARIES = Object.fromEntries(Object.values(BUILTIN_ADAPTER_PROFILES).map((profile) => [profile.id, profile.binary]));
+export const ADAPTER_INSTALL_HINTS = 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 = 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) {
+    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/dist/core/workflow/approvals.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, existsSync, linkSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { appendWorkflowJournalEvent } from "./journal.js";
+import { appendWorkflowTranscriptEvent } from "./transcript.js";
 export const WORKFLOW_APPROVAL_SCHEMA_VERSION = 1;
 const RECORD_LIMIT_BYTES = 128 * 1024;
 const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
@@ -67,7 +67,7 @@ export function resolveWorkflowApproval(input) {
         throw new Error(`approval ${input.approvalId} is already ${resolved.status}; conflicting ${input.verdict === "allow" ? "approval" : "denial"} refused`);
     }
     if (applied)
-        appendResolutionJournal(input.coordRoot, resolved);
+        appendResolutionTranscript(input.coordRoot, resolved);
     return { approval: resolved, applied };
 }
 export function readWorkflowApproval(coordRoot, approvalId) {
@@ -133,11 +133,11 @@ export function renderWorkflowApproval(approval) {
 export function assertWorkflowRunId(runId) {
     assertRunId(runId);
 }
-function appendResolutionJournal(coordRoot, approval) {
-    const journalPath = join(coordRoot, ".harnery", "workflows", approval.request.run_id, "journal.jsonl");
-    if (!existsSync(journalPath) || !approval.decision)
+function appendResolutionTranscript(coordRoot, approval) {
+    const transcriptPath = join(coordRoot, ".harnery", "workflows", approval.request.run_id, "transcript.jsonl");
+    if (!existsSync(transcriptPath) || !approval.decision)
         return;
-    appendWorkflowJournalEvent(coordRoot, approval.request.run_id, "approval.resolved", {
+    appendWorkflowTranscriptEvent(coordRoot, approval.request.run_id, "approval.resolved", {
         ts: approval.decision.decided_at,
         stage: "",
         approval_id: approval.request.id,

package/dist/core/workflow/billing.d.ts

@@ -1,23 +1,23 @@
 /**
- * Billing-mode probe: which auth a headless harness child will actually use.
+ * Billing-mode probe: which auth a headless adapter child will actually use.
  *
- * The engine never handles credentials — children are plain harness CLIs and
+ * The engine never handles credentials — children are plain adapter CLIs and
  * authenticate however that CLI does. But the CLIs prefer an exported API key
  * over a stored (subscription) login when both are present, and that override
  * is almost always an accident: a sourced .env or a leftover export silently
  * moves the run from subsidized subscription billing to per-token API billing.
- * This probe classifies the state per harness so the engine can refuse the
+ * This probe classifies the state per adapter so the engine can refuse the
  * silent-override case (see decision 0015 addendum) while leaving deliberate
  * key-only hosts (CI boxes with no login) working.
  *
  * Detection is a heuristic over well-known credential locations; when a
  * location can't prove presence or absence (e.g. Claude Code stores its OAuth
  * token in the macOS keychain, not a file), the state is "unknown" and the
- * engine never hard-fails on it — the harness CLI itself is the final
+ * engine never hard-fails on it — the adapter CLI itself is the final
  * authority and will error loudly if truly unauthenticated.
  */
-import type { HarnessName } from "./types.js";
-/** The env var each harness CLI reads as an API key (preferred over a stored
+import type { AdapterName } from "./types.js";
+/** The env var each adapter CLI reads as an API key (preferred over a stored
  * login when set). Shared with the child-env builder's subscription-only
  * scrub. */
 export declare const API_KEY_VARS: Record<string, string>;
@@ -31,7 +31,7 @@ export type BillingMode =
  * subsidized auth. The engine refuses this unless explicitly allowed. */
  | "api-key-override";
 export interface BillingProbe {
-    harness: HarnessName;
+    adapter: AdapterName;
     /** The env var checked (from API_KEY_VARS), or a note when the key was
      * found in a credential file instead of the environment. */
     apiKeySource: string | null;
@@ -43,6 +43,6 @@ export interface ProbeIo {
     env?: NodeJS.ProcessEnv;
     home?: string;
 }
-export type BillingProber = (harness: HarnessName) => BillingProbe;
-export declare function probeBilling(harness: HarnessName, io?: ProbeIo): BillingProbe;
+export type BillingProber = (adapter: AdapterName) => BillingProbe;
+export declare function probeBilling(adapter: AdapterName, io?: ProbeIo): BillingProbe;
 //# sourceMappingURL=billing.d.ts.map

package/dist/core/workflow/billing.js

@@ -1,25 +1,25 @@
 /**
- * Billing-mode probe: which auth a headless harness child will actually use.
+ * Billing-mode probe: which auth a headless adapter child will actually use.
  *
- * The engine never handles credentials — children are plain harness CLIs and
+ * The engine never handles credentials — children are plain adapter CLIs and
  * authenticate however that CLI does. But the CLIs prefer an exported API key
  * over a stored (subscription) login when both are present, and that override
  * is almost always an accident: a sourced .env or a leftover export silently
  * moves the run from subsidized subscription billing to per-token API billing.
- * This probe classifies the state per harness so the engine can refuse the
+ * This probe classifies the state per adapter so the engine can refuse the
  * silent-override case (see decision 0015 addendum) while leaving deliberate
  * key-only hosts (CI boxes with no login) working.
  *
  * Detection is a heuristic over well-known credential locations; when a
  * location can't prove presence or absence (e.g. Claude Code stores its OAuth
  * token in the macOS keychain, not a file), the state is "unknown" and the
- * engine never hard-fails on it — the harness CLI itself is the final
+ * engine never hard-fails on it — the adapter CLI itself is the final
  * authority and will error loudly if truly unauthenticated.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-/** The env var each harness CLI reads as an API key (preferred over a stored
+/** The env var each adapter CLI reads as an API key (preferred over a stored
  * login when set). Shared with the child-env builder's subscription-only
  * scrub. */
 export const API_KEY_VARS = {
@@ -27,15 +27,15 @@ export const API_KEY_VARS = {
     codex: "OPENAI_API_KEY",
     cursor: "CURSOR_API_KEY",
 };
-export function probeBilling(harness, io = {}) {
+export function probeBilling(adapter, io = {}) {
     const env = io.env ?? process.env;
     const home = io.home ?? homedir();
-    const keyVar = API_KEY_VARS[harness];
+    const keyVar = API_KEY_VARS[adapter];
     const envKey = keyVar ? Boolean(env[keyVar]?.trim()) : false;
     let login;
     let apiKeyPresent = envKey;
     let apiKeySource = envKey ? keyVar : null;
-    switch (harness) {
+    switch (adapter) {
         case "claude-code":
             login = probeClaudeLogin(home);
             break;
@@ -68,7 +68,7 @@ export function probeBilling(harness, io = {}) {
         : apiKeyPresent
             ? "api-key"
             : "subscription";
-    return { harness, apiKeySource, apiKeyPresent, login, mode };
+    return { adapter, apiKeySource, apiKeyPresent, login, mode };
 }
 /** Claude Code: OAuth login lives at ~/.claude/.credentials.json on Linux;
  * macOS stores it in the keychain (dir exists, file doesn't → unknown). */

package/dist/core/workflow/child-env.d.ts

@@ -2,8 +2,8 @@
  * Child-process environment builder shared by every spawn adapter.
  *
  * Rules (the first is a hard-won Phase 1 spike finding):
- * 1. **Delete inherited harness-session vars, never blank them.** A nested
- *    harness CLI under a live session inherits vars that make it exit 1 with
+ * 1. **Delete inherited adapter-session vars, never blank them.** A nested
+ *    adapter CLI under a live session inherits vars that make it exit 1 with
  *    empty output; an empty-string var still reads as set. Scrub all three
  *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
  *    a codex child launched from inside a Claude Code session must not inherit
@@ -25,10 +25,18 @@
  *    hooks stay on, keeping heartbeat + event capture.
  * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
  *    web UI can associate child sessions with their workflow run.
+ * 6. **Stamp the agent id** (HARNERY_WORKFLOW_AGENT_ID) so that association is
+ *    per-agent rather than only per-run. The orchestrator cannot use the child's
+ *    session id for this: the adapter mints that id and reports it back only in
+ *    the result envelope, which is to say only once the work being watched is
+ *    over. Passing in the id the orchestrator already owns is the only way to
+ *    attribute in-flight activity to a particular agent.
  */
 export interface ChildEnvOpts {
     /** Delete all API-key vars so children can only use stored logins. */
     subscriptionOnly?: boolean;
+    /** Transcript agent id (`a1`, `a2`, …) this child is running. */
+    agentId?: string;
 }
 export declare function buildChildEnv(runId?: string, opts?: ChildEnvOpts): Record<string, string>;
 //# sourceMappingURL=child-env.d.ts.map

package/dist/core/workflow/child-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"child-env.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/child-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB7F"}
+{"version":3,"file":"child-env.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/child-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAOH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmB7F"}

package/dist/core/workflow/child-env.js

@@ -2,8 +2,8 @@
  * Child-process environment builder shared by every spawn adapter.
  *
  * Rules (the first is a hard-won Phase 1 spike finding):
- * 1. **Delete inherited harness-session vars, never blank them.** A nested
- *    harness CLI under a live session inherits vars that make it exit 1 with
+ * 1. **Delete inherited adapter-session vars, never blank them.** A nested
+ *    adapter CLI under a live session inherits vars that make it exit 1 with
  *    empty output; an empty-string var still reads as set. Scrub all three
  *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
  *    a codex child launched from inside a Claude Code session must not inherit
@@ -25,10 +25,16 @@
  *    hooks stay on, keeping heartbeat + event capture.
  * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
  *    web UI can associate child sessions with their workflow run.
+ * 6. **Stamp the agent id** (HARNERY_WORKFLOW_AGENT_ID) so that association is
+ *    per-agent rather than only per-run. The orchestrator cannot use the child's
+ *    session id for this: the adapter mints that id and reports it back only in
+ *    the result envelope, which is to say only once the work being watched is
+ *    over. Passing in the id the orchestrator already owns is the only way to
+ *    attribute in-flight activity to a particular agent.
  */
 import { API_KEY_VARS } from "./billing.js";
 const SCRUB_PREFIXES = ["CLAUDE", "CODEX", "CURSOR"];
-const PRESERVED_HARNESS_VARS = new Set(["CODEX_HOME"]);
+const PRESERVED_ADAPTER_VARS = new Set(["CODEX_HOME"]);
 export function buildChildEnv(runId, opts = {}) {
     const env = {};
     const keyVars = new Set(Object.values(API_KEY_VARS));
@@ -39,7 +45,7 @@ export function buildChildEnv(runId, opts = {}) {
             continue;
         if (SCRUB_PREFIXES.some((p) => k.startsWith(p)) &&
             !keyVars.has(k) &&
-            !PRESERVED_HARNESS_VARS.has(k)) {
+            !PRESERVED_ADAPTER_VARS.has(k)) {
             continue;
         }
         env[k] = v;
@@ -47,5 +53,7 @@ export function buildChildEnv(runId, opts = {}) {
     env.HARNERY_WORKFLOW_CHILD = "1";
     if (runId)
         env.HARNERY_WORKFLOW_RUN_ID = runId;
+    if (opts.agentId)
+        env.HARNERY_WORKFLOW_AGENT_ID = opts.agentId;
     return env;
 }

package/dist/core/workflow/engine.d.ts

@@ -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).
  */
 import type { EngineOpts, RunReport } from "./types.js";
@@ -25,8 +25,18 @@ export declare class WorkflowRunError extends Error {
 export declare class WorkflowParkedError extends Error {
     readonly runId: string;
     readonly approvalId: string;
-    readonly journalPath: string;
-    constructor(message: string, runId: string, approvalId: string, journalPath: string);
+    readonly transcriptPath: string;
+    constructor(message: string, runId: string, approvalId: string, transcriptPath: string);
+}
+/** 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 declare class WorkflowBlockedError extends Error {
+    readonly reason: string;
+    readonly decisionId?: string;
+    constructor(reason: string, decisionId?: string);
 }
 export declare function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/core/workflow/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAyCH,OAAO,KAAK,EAEV,UAAU,EAGV,SAAS,EAYV,MAAM,YAAY,CAAC;AAsCpB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM/E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAOpF;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA6E1F"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0CH,OAAO,KAAK,EAIV,UAAU,EAEV,SAAS,EAYV,MAAM,YAAY,CAAC;AAsCpB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM/E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAOvF;AAED;;;;6EAI6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAUhD;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA6E1F"}