@relayflows/sdk 2.0.30 → 2.0.32

package/src/agent-cwd.ts

@@ -0,0 +1,139 @@
+import { realpathSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+
+/**
+ * Where an agent step runs.
+ *
+ * A declared `cwd` is a path relative to the **run root** — the working
+ * directory of the process running the agent worker, which is the directory
+ * `flows run` was invoked from and, on the Cloud path, the uploaded tree
+ * (docs/CLOUD.md, "Code sync"). Absent, a step runs in the run root itself.
+ *
+ * Two checks, in two places, because they are two different facts:
+ *
+ * - The **declaration** is lexical and filesystem-free, so `flows check`, the
+ *   kernel's `validate()` and this worker all answer identically for the same
+ *   spec. `testdata/agent-cwd-cases.json` is the shared corpus both dialects
+ *   are tested against.
+ * - The **target** is resolved here, in the worker that spawns the CLI — the
+ *   one process provably sharing the agent's filesystem. A directory that
+ *   exists, and whose symlink-free path is inside the symlink-free run root.
+ *   Repeated at execution even when a preflight already passed, because the
+ *   filesystem moves underneath a spec.
+ *
+ * This contains a declaration; it does not sandbox an agent. Nothing stops a
+ * CLI from writing outside the directory it was started in. Per-step scoping
+ * is `permissions`, which is recorded and not enforced (gate 8 / #442).
+ */
+export class AgentCwdError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentCwdError';
+  }
+}
+
+/**
+ * Why a declared `cwd` is not a run-root-relative path, or `undefined` when it
+ * is one. Pure and lexical: the exact rule
+ * `relayflowd_core::spec::is_run_root_relative_path` applies at the kernel
+ * boundary, so a declaration that passes `flows check` is not refused later by
+ * the daemon for its shape.
+ */
+export function agentCwdDeclarationError(cwd: unknown): string | undefined {
+  const expected = 'expected a run-root-relative path';
+  if (typeof cwd !== 'string') return `${expected} (got ${cwd === null ? 'null' : typeof cwd})`;
+  if (cwd === '') return `${expected}, not an empty string`;
+  if (PADDING.test(cwd)) return `${expected} without surrounding whitespace`;
+  if (cwd.includes('\0')) return `${expected} without NUL`;
+  if (cwd.startsWith('/')) return `${expected}, not an absolute path`;
+  if (cwd.includes('://')) return `${expected}, not a URI-like mount identity`;
+  if (cwd.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    return `${expected} without empty, "." or ".." components`;
+  }
+  return undefined;
+}
+
+/**
+ * Whitespace at either end, spelled so both dialects refuse the same set.
+ * JavaScript's `\s` is Unicode `White_Space` without U+0085 and with U+FEFF;
+ * Rust's `char::is_whitespace` is `White_Space` exactly. Naming U+0085 here
+ * and U+FEFF there makes both `White_Space ∪ {U+FEFF}`. Left to `trim()`
+ * alone, a path padded with either character would pass `flows check` and be
+ * refused by the kernel — the accept-then-refuse split this contract closes.
+ */
+const PADDING = /^[\s\u0085]|[\s\u0085]$/u;
+
+/**
+ * The refusal for a `cwd` declared on a step dispatched over the relay
+ * transport, or `undefined` when there is nothing to refuse.
+ *
+ * The relay agent runs on another host. This process can neither resolve that
+ * host's filesystem nor establish that the directory is inside that run's
+ * tree, and forwarding the string as `worker_cwd` would let a declaration this
+ * contract promises to contain go unchecked. Fail closed instead of pretending.
+ */
+export function agentCwdTransportError(cwd: unknown, transport: unknown): string | undefined {
+  if (cwd === undefined || transport !== 'relay') return undefined;
+  return 'cwd is not supported with transport "relay": the agent runs on another host, '
+    + 'where this worker cannot resolve the directory or hold it inside the run root';
+}
+
+/**
+ * The directory to spawn the CLI in: `root` when nothing is declared, else the
+ * symlink-free directory `cwd` names beneath `root`.
+ *
+ * @throws AgentCwdError naming the declaration and what is wrong with it.
+ */
+export function resolveAgentCwd(root: string, cwd: unknown, transport?: unknown): string | undefined {
+  if (cwd === undefined) return undefined;
+  const refusal = (detail: string): AgentCwdError =>
+    new AgentCwdError(`cwd ${JSON.stringify(cwd)}: ${detail}`);
+  const declaration = agentCwdDeclarationError(cwd);
+  if (declaration !== undefined) throw refusal(declaration);
+  const unsupported = agentCwdTransportError(cwd, transport);
+  if (unsupported !== undefined) throw new AgentCwdError(unsupported);
+
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    throw refusal(`the run root ${JSON.stringify(root)} cannot be resolved on this host`);
+  }
+  let target: string;
+  try {
+    target = realpathSync(resolve(realRoot, cwd as string));
+  } catch {
+    throw refusal(`no such directory under the run root ${JSON.stringify(realRoot)}`);
+  }
+  // Component-aware, on the symlink-free forms of both: `checkout-b-old` is
+  // not inside `checkout-b`, and a symlink pointing out of the tree is not
+  // inside it either however it is spelled.
+  const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (target !== realRoot && !target.startsWith(prefix)) {
+    throw refusal(`resolves to ${JSON.stringify(target)}, outside the run root ${JSON.stringify(realRoot)}`);
+  }
+  if (!statSync(target).isDirectory()) throw refusal(`${JSON.stringify(target)} is not a directory`);
+  return target;
+}
+
+/** Either the directory an agent step runs in, or why the step is refused. */
+export type AgentCwdOutcome = { directory: string | undefined } | { refusal: string };
+
+/**
+ * The dispatch-time form: resolve a dispatched agent step's `cwd` against the
+ * run root, or report the refusal for the worker to complete the step with.
+ * Reporting rather than throwing keeps the refusal on the step's completion —
+ * `worker_error`, with the reason journaled — instead of on the worker.
+ */
+export function agentStepCwd(
+  spec: { cwd?: unknown; transport?: unknown },
+  stepId: string,
+  root: string = process.cwd(),
+): AgentCwdOutcome {
+  try {
+    return { directory: resolveAgentCwd(root, spec.cwd, spec.transport) };
+  } catch (error) {
+    if (!(error instanceof AgentCwdError)) throw error;
+    return { refusal: `agent step "${stepId}": ${error.message}` };
+  }
+}

package/src/artifact-scan-policy.ts

@@ -0,0 +1,51 @@
+/**
+ * The bundled agent worker's artifact-scan policy, as a pure predicate.
+ *
+ * `agent-artifacts.ts` walks an agent step's cwd and records every regular
+ * file it finds, except entries named exactly `.git`, `.relayflowd` or
+ * `node_modules` — files as well as directories, in both cases. Dotfiles and
+ * dot-directories ARE eligible: `.workflow-artifacts/` is the conventional
+ * place a flow tells its agents to write. What that walk records is one
+ * source of the journaled `output.artifacts` list, which is the only thing an
+ * `artifact_exists` gate reads (`named-gate-lowering.ts` tests exact
+ * membership in that list and never touches disk).
+ *
+ * Static analysis needs the same rule without importing filesystem traversal,
+ * so the rule lives here and both consume it. It bounds the *scan*, not the
+ * list: `worker.ts` journals object-shaped JSON stdout and completed Relay
+ * task output verbatim instead of the scanned wrapper, and
+ * `JournalClient.stepComplete` accepts any `output` from any worker — so a
+ * path this predicate excludes can still reach the list by those routes
+ * (`named-gate-preflight.ts` warns rather than refusing for exactly that
+ * reason).
+ */
+
+/**
+ * Entry names the walk never descends into or records, matched exactly, at
+ * any depth, before the entry's type is consulted — so a `.git` *file* (a
+ * worktree's gitdir pointer) is skipped as surely as a `.git` directory.
+ * Exact names, not prefixes: `.github`, `.relayflowd-notes` and every other
+ * author-chosen name that merely starts the same way stays eligible.
+ */
+const SKIPPED_ENTRY_NAMES = new Set(['.git', '.relayflowd', 'node_modules']);
+
+export function isUnscannedEntryName(name: string): boolean {
+  return SKIPPED_ENTRY_NAMES.has(name);
+}
+
+/**
+ * The shortest `/`-prefix of a relative POSIX `path` the scan excludes, or
+ * `undefined` when every segment is scanned.
+ *
+ * Segments are compared exactly, with no normalization: the gate matches the
+ * author's literal string against the worker's literal list, so `node_modules`
+ * is excluded and `node_modules-copy` is not, and a backslash is an ordinary
+ * filename character rather than a separator. The whole prefix is returned,
+ * not the offending segment alone, because that prefix is the directory an
+ * author has to move the artifact out of.
+ */
+export function unscannedArtifactPrefix(path: string): string | undefined {
+  const segments = path.split('/');
+  const index = segments.findIndex(isUnscannedEntryName);
+  return index === -1 ? undefined : segments.slice(0, index + 1).join('/');
+}

package/src/authored-completion-record.ts

@@ -0,0 +1,119 @@
+// The authored verdict, written to the root BEFORE the marker is admitted.
+//
+// The terminal marker's command embeds the detail, and the marker run is
+// opened under a stable admission key (`authored-child:<hash(root, step)>`).
+// Those two facts together mean the detail has to be a durable decision, not a
+// recomputed one: normalization redacts against `process.env`, so a credential
+// rotated or removed while this process was down makes the SAME authored
+// sentence normalize differently. A body resumed into that environment would
+// retry the marker's admission key with a drifted spec, and the kernel refuses
+// that as `run_admission_conflict` — losing an explanation the root had
+// already journaled, for a flow whose every step succeeded.
+//
+// So the verdict is appended to a stream on the root run before the marker run
+// is opened, and a later attempt reaching the same terminal step reuses what
+// is recorded. That is exactly the durability the executor already gives a
+// predicate gate (`applyPredicateGate`): record the decision first, so the
+// spec built from it is identical on every attempt and author code is never
+// asked the question twice.
+//
+// Nothing is recorded for a `done()` with no detail. Without one the marker
+// command is a function of the reason alone — no environment, no drift, and
+// nothing to recover — so a flow that does not opt in writes exactly the
+// journal it has always written.
+
+import {
+  isDurableCompletionDetail,
+  isLoweredCompletion,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import type { JournalClient } from './journal-client.js';
+
+export const AUTHORED_VERDICT_STREAM = 'authored-verdict';
+
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-verdict.v1';
+
+export interface AuthoredVerdictRecord {
+  readonly reason: LoweredCompletionReason;
+  /** Recorded only when the body passed one; see the module comment. */
+  readonly detail?: string;
+}
+
+/**
+ * Commit this body's verdict, or recover the one this root already committed.
+ *
+ * Returns the verdict the marker must be built from — the recorded one when
+ * the root holds it, this attempt's otherwise. With no root run there is
+ * nothing durable to write to (the non-durable executor seam), so that path
+ * passes straight through without a round trip. A root run is always read
+ * first: a committed record stays authoritative even for an attempt that has
+ * no detail of its own — an optional source can be present on the first
+ * execution and gone on the retry, and "this attempt has no detail" is not
+ * "this root never recorded one". Only when no record exists AND this attempt
+ * has no detail does it return without appending, preserving the no-detail
+ * marker, spec hash, and journal exactly as before.
+ */
+export async function commitAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  step: string,
+  verdict: AuthoredVerdictRecord,
+): Promise<AuthoredVerdictRecord> {
+  if (rootRunId === undefined) return verdict;
+  const committed = await readAuthoredVerdict(journal, rootRunId, step);
+  if (committed !== undefined) return committed;
+  if (verdict.detail === undefined) return verdict;
+  await journal.streamAppend(rootRunId, AUTHORED_VERDICT_STREAM, {
+    verdict: RECORD_KIND, step, reason: verdict.reason, detail: verdict.detail,
+  });
+  return verdict;
+}
+
+/**
+ * The verdict this root recorded for `step`, or `undefined`.
+ *
+ * The FIRST valid record wins: it is the one the marker was — or was about to
+ * be — admitted from, and a later attempt's differently-redacted text must not
+ * displace it. Records this version does not recognise, and details that fail
+ * the durable check every other read boundary applies, are skipped rather than
+ * trusted; the marker then drifts and the kernel refuses it loudly, which is
+ * the right outcome for a record this process cannot read.
+ */
+export async function readAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string,
+  step: string,
+): Promise<AuthoredVerdictRecord | undefined> {
+  let offset = 0;
+  for (;;) {
+    const page = await journal.streamRead(rootRunId, AUTHORED_VERDICT_STREAM, offset, 1000);
+    for (const message of page.messages) {
+      // `stream.read` returns either the envelope or the bare message,
+      // matching how the executor reads predicate verdicts.
+      const raw = (message as { message?: unknown }).message ?? message;
+      if (isVerdictRecord(raw) && raw.step === step) {
+        return Object.freeze({ reason: raw.reason, detail: raw.detail });
+      }
+    }
+    if (page.messages.length === 0 || page.next_offset <= offset) break;
+    offset = page.next_offset;
+  }
+  return undefined;
+}
+
+interface StoredVerdict {
+  readonly verdict: typeof RECORD_KIND;
+  readonly step: string;
+  readonly reason: LoweredCompletionReason;
+  readonly detail: string;
+}
+
+function isVerdictRecord(value: unknown): value is StoredVerdict {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<StoredVerdict>;
+  return record.verdict === RECORD_KIND
+    && typeof record.step === 'string' && record.step.length > 0
+    && isLoweredCompletion(record.reason)
+    && isDurableCompletionDetail(record.detail);
+}

package/src/authored-completion.ts

@@ -0,0 +1,203 @@
+// The authored verdict: which completions this runtime lowers, the durable
+// marker that carries one, and the optional detail that says why.
+//
+// Split out of `authored-flow-executor.ts` so the CLI report and the status
+// projection can read this vocabulary without importing the executor — and
+// with it every provider adapter, MCP client and helper the executor pulls
+// in. Nothing here does I/O or reads a clock.
+
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { redact } from './redact.js';
+
+/**
+ * The completion reasons an authored body may declare and this executor lowers.
+ *
+ * `FlowCompletionReason` is wider than this on purpose — it is the journal's
+ * run vocabulary plus authored verdicts — but the two sets drifting silently is
+ * exactly what made a type-valid `done("step_failed")` die at runtime as
+ * `unsupported_completion`. Every gate that asks "is this a completion this
+ * runtime can lower?" now asks this one function, so a reason cannot be
+ * accepted in one place and rejected in another.
+ *
+ * These are internal cross-module helpers for the authored seam (the executor,
+ * the durable root, the IPC verifier, the CLI report and `flows status`), NOT
+ * public SDK surface. `src/index.ts` deliberately re-exports nothing from this
+ * module — keep it that way, or the whole authored seam leaks with them.
+ */
+export const LOWERED_COMPLETIONS = ['success', 'needs_human', 'step_failed', 'declined'] as const;
+export type LoweredCompletionReason = (typeof LOWERED_COMPLETIONS)[number];
+
+export function isLoweredCompletion(value: unknown): value is LoweredCompletionReason {
+  return typeof value === 'string' && (LOWERED_COMPLETIONS as readonly string[]).includes(value);
+}
+
+/**
+ * The bound on a normalized completion detail: 2,000 Unicode code points in
+ * the FINAL string, {@link COMPLETION_DETAIL_TRUNCATED_SUFFIX} included.
+ *
+ * Code points, not `String.length`: `.length` counts UTF-16 code units, so an
+ * emoji-heavy detail measured that way is half the length a reader would call
+ * it. The number matches `@relayflows/surface`'s
+ * `COMPLETION_DETAIL_MAX_CODE_POINTS`, which is what an author sees; it is the
+ * same order as the kernel's gate-detail cap
+ * (`kernel/relayflowd/src/engine/remote.rs`) but deliberately NOT the same
+ * bound — that one takes 2,000 characters and then appends its suffix, so its
+ * final string is longer than the number it advertises.
+ */
+export const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;
+
+/** Fixed width, so the bound above can reserve exactly its room. */
+export const COMPLETION_DETAIL_TRUNCATED_SUFFIX = '… (truncated)';
+
+/**
+ * Read `done()`'s optional second argument into the detail the marker carries.
+ *
+ * Absence has four spellings — no argument, `undefined`, `{}`, and
+ * `{ detail: undefined }` — and all four mean the same thing: no detail, and a
+ * marker command byte-identical to the one the one-argument call has always
+ * produced. Whitespace-only joins them: say nothing, or say something.
+ *
+ * A `detail` that is present and not a string is a programming error the type
+ * system already catches for TypeScript callers; the runtime check is here for
+ * the same reason `isSurfaceFlowCompletionReason` is, and it refuses with the
+ * existing closed `unsupported_completion` code rather than widening the
+ * taxonomy. Refusals name the type they got, never the value — a malformed
+ * detail is exactly the kind of text that may carry a credential.
+ *
+ * Redaction runs BEFORE truncation, and the order is load-bearing rather than
+ * cosmetic: truncating first can split a token so no pattern matches it any
+ * more, which is a truncation that *causes* a leak. What redaction recognises
+ * is the SDK's existing policy — known token shapes, named credential fields,
+ * and the values of secret-looking environment variables (`redact.ts`) — not a
+ * guarantee to recognise every possible secret.
+ *
+ * Lone surrogates are substituted here too, so what leaves this function is a
+ * well-formed string the journal protocol can carry — see {@link wellFormed}.
+ */
+export function normalizeCompletionDetail(
+  options: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (options === undefined) return undefined;
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new AuthoredFlowExecutionError(
+      'unsupported_completion',
+      `done() options must be an object with an optional string "detail"; received ${typeName(options)}`,
+    );
+  }
+  const detail = (options as { detail?: unknown }).detail;
+  if (detail === undefined) return undefined;
+  if (typeof detail !== 'string') {
+    throw new AuthoredFlowExecutionError(
+      'unsupported_completion',
+      `done() detail must be a string; received ${typeName(detail)}`,
+    );
+  }
+  const redacted = wellFormed(redact(detail, env)).trim();
+  return redacted.length === 0 ? undefined : bound(redacted);
+}
+
+/**
+ * Lone UTF-16 surrogates, as code points.
+ *
+ * Under `u` a subject string is iterated by CODE POINT, so a well-formed pair
+ * is one code point above U+FFFF and never enters this class. What the class
+ * matches is exactly a surrogate with no partner.
+ */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+const LONE_SURROGATES = /[\uD800-\uDFFF]/gu;
+
+/**
+ * Replace every lone surrogate with U+FFFD, the replacement character.
+ *
+ * A JavaScript string is UTF-16 code units, not text. Slicing a character off
+ * the end of an agent's output — `(prose + '\u{1F642}').slice(0, -1)` — leaves
+ * a high surrogate with no partner, and the type system calls the result a
+ * `string`. Nothing downstream does.
+ * `JSON.stringify` escapes it, so the marker COMMAND is admitted; the raw
+ * detail then travels in the root's `step.complete` output, where the kernel's
+ * JSON decoder refuses it ("unexpected end of hex escape") and answers with a
+ * `bad_request` carrying a null request id — which resolves no pending
+ * request, so the call hangs and the authored explanation never lands.
+ *
+ * Substituting is right here where refusing is not: the flow has already done
+ * its work and reached a verdict, and losing the whole explanation over one
+ * broken code unit destroys more than it protects. One code unit in, one code
+ * unit out, so the bound below still counts what a reader would count.
+ */
+function wellFormed(text: string): string {
+  return LONE_SURROGATE.test(text) ? text.replace(LONE_SURROGATES, '\uFFFD') : text;
+}
+
+/**
+ * Is this a detail a durable record may carry?
+ *
+ * The gate every read boundary uses — the completed root's output, and the
+ * IPC frame the Bun runner returns — so an over-long or wrong-typed value
+ * fails closed there instead of flowing into a report as if it had been
+ * journaled by this process.
+ */
+export function isDurableCompletionDetail(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.length > 0
+    && !LONE_SURROGATE.test(value)
+    && [...value].length <= COMPLETION_DETAIL_MAX_CODE_POINTS;
+}
+
+/**
+ * The detail as ONE line, for a diagnostic message.
+ *
+ * Cloud renders a run's `error` through a line-oriented view that elides the
+ * middle of a long one (`cli/cloud-read.ts` `errorLines`), so a forty-line
+ * detail can lose the very finding it exists to carry. Escaping the breaks
+ * keeps the whole detail on the single line that renderer cannot elide, and
+ * keeps control characters out of a terminal. The unescaped normalized detail
+ * still travels in the structured fields beside it.
+ */
+export function singleLineCompletionDetail(detail: string): string {
+  return detail.replace(/[\u0000-\u001F\u007F-\u009F]/gu, (char) =>
+    NAMED_ESCAPE[char] ?? `\\u${char.codePointAt(0)!.toString(16).padStart(4, '0')}`);
+}
+
+const NAMED_ESCAPE: Record<string, string> = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+
+/**
+ * The deterministic command that carries an authored verdict into the journal.
+ *
+ * `success` with no detail lowers to `:` because success needs no marker: the
+ * marker run's own kernel `success` already IS that record. Every other
+ * lowered verdict is something the kernel's completion vocabulary cannot
+ * express on a step that *succeeded*, so it travels as data on stdout and is
+ * read back from `step.completed`. It is deliberately not lowered as a failing
+ * command: no step failed here, and a fabricated failure would put bogus
+ * evidence in the journal for a flow whose steps all ran correctly.
+ *
+ * A detail rides in the same JSON object, so the marker stays the one durable
+ * record of the verdict and the IPC verifier's existing command comparison
+ * checks the detail against the journal for free. With no detail the command
+ * is byte-identical to the one this function has always returned, which is
+ * what keeps `spec_hash` stable for every flow that does not opt in.
+ */
+export function completionMarker(reason: LoweredCompletionReason, detail?: string): string {
+  if (detail === undefined) {
+    return reason === 'success' ? ':' : `printf '%s' '{"completionReason":"${reason}"}'`;
+  }
+  // `JSON.stringify` escapes quotes, backslashes and every control character,
+  // so the command is one line and the only shell-significant character left
+  // in it is `'` — which the single-quote escape below closes.
+  const json = JSON.stringify({ completionReason: reason, detail });
+  return `printf '%s' '${json.replaceAll("'", "'\\''")}'`;
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a ${typeof value}`;
+}
+
+function bound(text: string): string {
+  const points = [...text];
+  if (points.length <= COMPLETION_DETAIL_MAX_CODE_POINTS) return text;
+  const keep = COMPLETION_DETAIL_MAX_CODE_POINTS - [...COMPLETION_DETAIL_TRUNCATED_SUFFIX].length;
+  return `${points.slice(0, keep).join('')}${COMPLETION_DETAIL_TRUNCATED_SUFFIX}`;
+}

package/src/authored-flow-error.ts

@@ -1,5 +1,5 @@
 import type { HumanRecipient } from './human-to.js';
-import type { StepFailedDetails } from './failure-kinds.js';
+import type { ParkCause, StepFailedDetails } from './failure-kinds.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
@@ -42,6 +42,18 @@ export type AuthoredFlowExecutionErrorCode =
 export class AuthoredFlowExecutionError extends Error {
   /** Set by the durable root driver after the child error crosses any IPC boundary. */
   rootRunId?: string;
+  /**
+   * Why an `agent_parked`/`llm_parked` child run parked, as the child's own
+   * classification established it (`RunReport.parkCause`).
+   *
+   * Set by the worker runner beside the code, because the code alone does not
+   * say: `agent_parked` covers both "nothing is attached to run this step" and
+   * the kernel's `needs_human` recovery wait, and only the first is fixed by
+   * attaching a worker. The CLI boundary reads this field rather than matching
+   * the message, so the remedy it prints cannot drift from the cause. Absent
+   * means unestablished — the boundary then says nothing about workers.
+   */
+  parkCause?: ParkCause;
   constructor(
     readonly code: AuthoredFlowExecutionErrorCode,
     message: string,