harnery 0.29.0 → 0.31.0

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;
@@ -39,6 +39,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 type WorkState =
   | "waiting"
@@ -71,6 +77,12 @@ export interface WorkIntent {
   dependencies: string[];
   workflow: { path: string; sha256: string };
   max_attempts: number;
+  /** Ceiling on CONSECUTIVE uncharged attempts (ADR 0046), separate from
+   * max_attempts. An upstream outage produces uncharged attempt after uncharged
+   * attempt; without a bound it would retry forever. At the bound the item stops
+   * and reports it is blocked on an outside service. Optional for back-compat:
+   * an intent written before ADR 0046 has none and falls back to the default. */
+  max_uncharged_attempts?: number;
   source?: { kind: "human" | "workflow" | "external"; ref?: string };
   created_at: string;
 }
@@ -124,10 +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" | "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 {
@@ -138,11 +157,22 @@ export interface WorkProjection {
   next_action: WorkNextAction;
   unresolved_dependencies: string[];
   attempts: WorkAttempt[];
+  /** Every attempt started, charged or not. Drives the next attempt number and
+   * history ordering, so it counts uncharged attempts too. */
   attempts_used: number;
+  /** Attempts that were informative about the work (ADR 0046). This — not
+   * attempts_used — is what max_attempts budgets, so an uncharged environment or
+   * upstream attempt does not consume the retry budget. */
+  charged_attempts: number;
   attempts_remaining: number;
   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;
 }
 
@@ -160,6 +190,7 @@ export interface CreateWorkItemInput {
   acceptance?: string[];
   dependencies?: string[];
   maxAttempts?: number;
+  maxUnchargedAttempts?: number;
   source?: WorkIntent["source"];
   id?: string;
   actor?: string;
@@ -188,6 +219,14 @@ export function createWorkItem(input: CreateWorkItemInput): WorkRecord {
   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),
   );
@@ -204,6 +243,7 @@ export function createWorkItem(input: CreateWorkItemInput): WorkRecord {
     dependencies,
     workflow: { path: workflowPath, sha256: workflowScriptDigest(workflowPath) },
     max_attempts: maxAttempts,
+    max_uncharged_attempts: maxUnchargedAttempts,
     source,
     created_at: new Date().toISOString(),
   };
@@ -375,13 +415,18 @@ function deriveWorkProjection(
   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: [] as string[],
     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,
@@ -462,17 +507,74 @@ function deriveWorkProjection(
       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",
@@ -484,6 +586,48 @@ function deriveWorkProjection(
   };
 }
 
+/** 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: WorkAttempt): string | undefined {
+  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 as Record<string, unknown>).error : undefined;
+    return typeof error === "string" && error.trim() ? boundedTranscriptError(error) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function environmentBlockedReason(attempt: WorkAttempt): string {
+  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: 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,
@@ -547,20 +691,34 @@ function inspectAttempt(
       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: 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;
@@ -576,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;
     }
@@ -882,7 +1040,13 @@ function validateWorkIntent(intent: WorkIntent, workId: string): void {
     !/^[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`);
   }
@@ -1049,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",
   );
 }
 
@@ -1186,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,

package/src/core/workflow/billing.ts

@@ -1,28 +1,28 @@
 /**
- * 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";
-import type { HarnessName } from "./types.ts";
+import type { AdapterName } from "./types.ts";
 
-/** 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: Record<string, string> = {
@@ -43,7 +43,7 @@ export type BillingMode =
   | "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;
@@ -57,19 +57,19 @@ export interface ProbeIo {
   home?: string;
 }
 
-export type BillingProber = (harness: HarnessName) => BillingProbe;
+export type BillingProber = (adapter: AdapterName) => BillingProbe;
 
-export function probeBilling(harness: HarnessName, io: ProbeIo = {}): BillingProbe {
+export function probeBilling(adapter: AdapterName, io: ProbeIo = {}): BillingProbe {
   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: LoginState;
   let apiKeyPresent = envKey;
   let apiKeySource: string | null = envKey ? keyVar : null;
 
-  switch (harness) {
+  switch (adapter) {
     case "claude-code":
       login = probeClaudeLogin(home);
       break;
@@ -105,7 +105,7 @@ export function probeBilling(harness: HarnessName, io: ProbeIo = {}): BillingPro
         ? "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;

package/src/core/workflow/child-env.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,16 +25,24 @@
  *    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.ts";
 
 const SCRUB_PREFIXES = ["CLAUDE", "CODEX", "CURSOR"];
-const PRESERVED_HARNESS_VARS = new Set(["CODEX_HOME"]);
+const PRESERVED_ADAPTER_VARS = new Set(["CODEX_HOME"]);
 
 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 function buildChildEnv(runId?: string, opts: ChildEnvOpts = {}): Record<string, string> {
@@ -46,7 +54,7 @@ export function buildChildEnv(runId?: string, opts: ChildEnvOpts = {}): Record<s
     if (
       SCRUB_PREFIXES.some((p) => k.startsWith(p)) &&
       !keyVars.has(k) &&
-      !PRESERVED_HARNESS_VARS.has(k)
+      !PRESERVED_ADAPTER_VARS.has(k)
     ) {
       continue;
     }
@@ -54,5 +62,6 @@ export function buildChildEnv(runId?: string, opts: ChildEnvOpts = {}): Record<s
   }
   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;
 }