@relayflows/sdk 2.0.30 → 2.0.32

package/src/authored-step-output.ts

@@ -22,19 +22,23 @@ export interface AuthoredStepContext {
 }
 
 /**
- * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
- * find its `step.completed` entry, record it, and refuse anything but a
+ * Shared by every `f.*` verb that lowers to its own kernel run: find the
+ * operation's `step.completed` entry, record it, and refuse anything but a
  * clean success before handing the raw `output` back for verb-specific
  * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
  *
- * Callers are responsible for having already established that the RUN
- * reached a terminal, successful state before calling this — `f.run`'s
- * caller relies on `runStart`'s own immediate response (the kernel drives a
- * deterministic step to completion inline, no race); `f.agent`'s caller
- * relies on `classifyOutcome` (cli/run.ts) having already polled to a true
- * terminal state. Given that, a single read from the start of this run's
- * (small, single-step) journal is enough — no polling here, and no run
- * outcome ever needs re-checking.
+ * Callers are responsible for having already waited for the run to reach a
+ * terminal state — `f.run`'s caller relies on `runStart`'s own immediate
+ * response (the kernel drives a deterministic step to completion inline, no
+ * race); `f.agent`'s caller relies on `classifyOutcome` (cli/run.ts) having
+ * already polled to one. Given that, a single read from the start of this
+ * run's small journal is enough, and no polling happens here.
+ *
+ * What is NOT delegated to the caller is the run's verdict. A child spec has
+ * more than one step whenever the author declared a `.gate()`, and that gate
+ * step runs after the producer, so the producer's own `success` is not the
+ * run's. Both are checked here, and the run-level check is what makes a failed
+ * gate reject the authored operation.
  *
  * A non-success completion used to throw `journal step "run-1" completed with
  * retries_exhausted` and stop there, discarding the evidence it was holding:
@@ -63,26 +67,19 @@ export async function readCompletedStepOutput(
   const edges = context.stepEdges?.(stepId);
   journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason, ...edges }));
   if (reason !== 'success') {
-    let message = `journal step "${stepId}" completed with ${reason}`;
-    let details: StepFailedDetails | undefined;
-    try {
-      details = await stepFailureDetails(journal, runId);
-    } catch (error) {
-      // Inspection must not erase the already known step failure; the two
-      // failures stay separately visible, as in classifyOutcome.
-      message += ` Could not inspect the failed step: ${errorMessage(error)}`;
-    }
-    if (details !== undefined) message += renderStepEvidence(details);
-    // Appended whatever inspection found — including nothing. A failure shape
-    // this reader does not recognise must still end with somewhere to go.
-    const where = inspectionHint(runId, details?.stepId ?? stepId, context.dataDir);
-    message += renderInspection(where);
-    message += await alsoRecord(journal, context.rootRunId, {
-      step: stepId, runId, state: 'completed', completionReason: reason,
-      ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
-      ...edges,
-    });
-    throw new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
+    throw await stepFailure(journal, runId, stepId, reason, context, edges,
+      `journal step "${stepId}" completed with ${reason}`);
+  }
+  // An authored operation does not always lower to ONE kernel step. A declared
+  // `.gate()` becomes its own barrier step that runs AFTER the producer
+  // (`lowerNamedGates`), so the producer's own success is not the run's
+  // verdict. Reading only the producer's entry let a failed gate resolve as
+  // though the command had passed — the `|| true` invisibility this module's
+  // recording policy exists to remove, reappearing one layer up.
+  const runReason = entries.map(runCompletionReason).find((value) => value !== undefined);
+  if (runReason !== undefined && runReason !== 'success') {
+    throw await stepFailure(journal, runId, stepId, runReason, context, edges,
+      `journal run for step "${stepId}" completed with ${runReason}`);
   }
   await recordAuthoredChild(journal, context.rootRunId, {
     step: stepId, runId, state: 'completed', completionReason: reason, ...edges,
@@ -90,6 +87,42 @@ export async function readCompletedStepOutput(
   return completed.payload.output;
 }
 
+/**
+ * The one `step_failed` grammar both the step-level and the run-level refusal
+ * report through: inspect the journal for the step that actually failed, render
+ * its evidence, name where to look, and index the child before throwing.
+ */
+async function stepFailure(
+  journal: JournalClient,
+  runId: string,
+  stepId: string,
+  reason: ProtocolCompletionReason | ProtocolRunCompletionReason,
+  context: AuthoredStepContext,
+  edges: ReturnType<NonNullable<AuthoredStepContext['stepEdges']>>,
+  header: string,
+): Promise<AuthoredFlowExecutionError> {
+  let message = header;
+  let details: StepFailedDetails | undefined;
+  try {
+    details = await stepFailureDetails(journal, runId);
+  } catch (error) {
+    // Inspection must not erase the already known step failure; the two
+    // failures stay separately visible, as in classifyOutcome.
+    message += ` Could not inspect the failed step: ${errorMessage(error)}`;
+  }
+  if (details !== undefined) message += renderStepEvidence(details);
+  // Appended whatever inspection found — including nothing. A failure shape
+  // this reader does not recognise must still end with somewhere to go.
+  const where = inspectionHint(runId, details?.stepId ?? stepId, context.dataDir);
+  message += renderInspection(where);
+  message += await alsoRecord(journal, context.rootRunId, {
+    step: stepId, runId, state: 'completed', completionReason: reason,
+    ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
+    ...edges,
+  });
+  return new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
+}
+
 export async function readSuccessfulOutput(
   journal: JournalClient,
   outcome: RunOutcome,
@@ -98,24 +131,74 @@ export async function readSuccessfulOutput(
   context: AuthoredStepContext = {},
 ): Promise<string> {
   const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
-    .catch(error => {
-      if (error instanceof AuthoredFlowExecutionError
-        && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
-        // A timeout is still a failed command, and the evidence extracted for
-        // it is the same evidence. Re-labelling the error must not delete it.
-        throw new AuthoredFlowExecutionError('lease_exceeded',
-          `f.run step "${stepId}" exceeded its command timeout.`
-            + ` ${error.message.slice(`${error.code}: `.length)}`,
-          error.completionReason, error.runId, error.details);
-      }
-      throw error;
-    });
+    .catch(relabelCommandTimeout(stepId));
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
   }
   return output['stdout_tail'];
 }
 
+/** What `f.run` resolves to under `onNonZero: 'record'` (surface `RunResult`). */
+export interface RecordedRunOutcome {
+  ok: boolean;
+  exitCode: number;
+  output: string;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * The read side of `onNonZero: 'record'`.
+ *
+ * A recorded red exit is a SUCCESSFUL step, so this takes the same path as
+ * `readSuccessfulOutput` and every field comes from the journaled envelope —
+ * nothing is re-run and nothing is re-measured. What still throws is what the
+ * policy never covered: a timeout, a signal, a step that never ran, or a
+ * declared content or schema gate that failed. The `-1` the executor writes
+ * for "no exit status" is refused rather than handed back as a plausible
+ * code, mirroring the kernel's own rule, so a malformed envelope can never
+ * reach an author's `if (!result.ok)` as a real verdict.
+ */
+export async function readRecordedOutcome(
+  journal: JournalClient,
+  outcome: RunOutcome,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
+): Promise<RecordedRunOutcome> {
+  const envelope = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
+    .catch(relabelCommandTimeout(stepId));
+  const exitCode = isRecord(envelope) ? envelope['exit_code'] : undefined;
+  if (!isRecord(envelope) || typeof envelope['stdout_tail'] !== 'string'
+    || typeof envelope['stderr_tail'] !== 'string'
+    || typeof exitCode !== 'number' || !Number.isInteger(exitCode) || exitCode < 0) {
+    throw protocolViolation(outcome.run_id,
+      `step "${stepId}" recorded no {exit_code, stdout_tail, stderr_tail} to report`);
+  }
+  const stdout = envelope['stdout_tail'];
+  const stderr = envelope['stderr_tail'];
+  return {
+    ok: exitCode === 0, exitCode, stdout, stderr,
+    // Concatenated, not interleaved: the two tails were captured separately,
+    // so joining them is a reading convenience and is documented as one.
+    output: stdout !== '' && stderr !== '' ? `${stdout}\n${stderr}` : stdout + stderr,
+  };
+}
+
+/** A timeout is still a failed command; re-labelling it must not delete its evidence. */
+function relabelCommandTimeout(stepId: string): (error: unknown) => never {
+  return (error) => {
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
+      throw new AuthoredFlowExecutionError('lease_exceeded',
+        `f.run step "${stepId}" exceeded its command timeout.`
+          + ` ${error.message.slice(`${error.code}: `.length)}`,
+        error.completionReason, error.runId, error.details);
+    }
+    throw error;
+  };
+}
+
 interface StepCompletedEntry {
   entry_type: 'step.completed';
   step_id: string;
@@ -135,6 +218,20 @@ function isStepCompleted(value: unknown, stepId: string): value is StepCompleted
     && 'output' in payload;
 }
 
+/**
+ * The run's own terminal reason, when this entry is the one carrying it.
+ *
+ * Anything else — including a `run.completed` whose payload this reader does
+ * not recognise — yields `undefined` and leaves the step-level verdict
+ * untouched, so an unfamiliar journal shape cannot invent a failure.
+ */
+function runCompletionReason(entry: unknown): ProtocolRunCompletionReason | undefined {
+  if (!isRecord(entry) || entry['entry_type'] !== 'run.completed') return undefined;
+  const payload = entry['payload'];
+  const reason = isRecord(payload) ? payload['completionReason'] : undefined;
+  return isSurfaceRunCompletionReason(reason) ? reason : undefined;
+}
+
 export function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason {
   return typeof value === 'string'
     && (COMPLETION_REASONS as readonly string[]).includes(value);

package/src/authored-verdict.ts

@@ -0,0 +1,87 @@
+// Project an authored flow's own verdict out of its root journal.
+//
+// `foldRunState` answers what the KERNEL recorded: the root step succeeded, so
+// the run completed with `success`. That is true and must stay printed. It is
+// also not what a reader asking "why did this fail?" needs when the body
+// declared `step_failed` — a verdict the kernel's vocabulary cannot express on
+// a step that succeeded, so it travels as output on the root's own
+// `step.completed`.
+//
+// This is a separate, narrow projection rather than a branch inside the fold:
+// the fold is generic over every run and has no business knowing what an
+// authored root is, and the executor this vocabulary comes from must not
+// become a dependency of `flows status`.
+
+import {
+  isDurableCompletionDetail,
+  isLoweredCompletion,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import type { JournalEvent } from './journal-reader.js';
+
+/** The `instruction` discriminator `authored-root.ts` writes into the root step. */
+export const AUTHORED_ROOT_KIND = 'relayflows.authored-root.v1';
+
+export interface AuthoredVerdict {
+  readonly reason: LoweredCompletionReason;
+  /** Absent when the body called `done()` with one argument, as most do. */
+  readonly detail?: string;
+}
+
+/**
+ * The verdict an authored root attested, or `null` when this journal holds none.
+ *
+ * `null` is the answer for an ordinary run, for an authored run still in
+ * flight, and for one whose root output is malformed. The last of those
+ * matters: an ordinary flow may name a step `authored-root`, and a worker may
+ * journal anything into a step's output, so the step id alone attests nothing.
+ * A verdict is reported only when the run's own spec declares the authored
+ * root — carrying {@link AUTHORED_ROOT_KIND} metadata — and the root's last
+ * `step.completed` is a terminal kernel `success` whose output is a complete,
+ * in-bounds authored result. A retry or park completion is not terminal and a
+ * later attempt may still change the answer, so neither is promoted.
+ *
+ * This is a projection for a read-only view, so a malformed record yields no
+ * verdict rather than an error: refusing to render a whole status because one
+ * output field is the wrong type would replace the answer with a worse one.
+ */
+export function authoredVerdictOf(events: readonly JournalEvent[]): AuthoredVerdict | null {
+  const spawned = events[0];
+  if (spawned === undefined || spawned.entry_type !== 'run.spawned') return null;
+  if (!declaresAuthoredRoot(spawned)) return null;
+
+  const completed = [...events].reverse().find((event) =>
+    event.entry_type === 'step.completed' && event.step_id === 'authored-root');
+  const payload = record(completed?.payload);
+  if (payload === null || payload['completionReason'] !== 'success') return null;
+  const disposition = payload['disposition'];
+  if (disposition !== undefined && disposition !== 'step_done') return null;
+
+  const output = record(payload['output']);
+  if (output === null || typeof output['name'] !== 'string') return null;
+  const reason = output['completionReason'];
+  if (!isLoweredCompletion(reason)) return null;
+  const detail = output['completionDetail'];
+  if (detail !== undefined && !isDurableCompletionDetail(detail)) return null;
+
+  return Object.freeze({ reason, ...(detail === undefined ? {} : { detail }) });
+}
+
+function declaresAuthoredRoot(spawned: JournalEvent): boolean {
+  const spec = record(record(spawned.payload)?.['spec']);
+  const steps = spec?.['steps'];
+  if (!Array.isArray(steps)) return false;
+  const step = record(steps[0]);
+  if (step === null || step['id'] !== 'authored-root') return false;
+  if (typeof step['instruction'] !== 'string') return false;
+  try {
+    return record(JSON.parse(step['instruction']))?.['kind'] === AUTHORED_ROOT_KIND;
+  } catch {
+    return false;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : null;
+}

package/src/authored-worker-step.ts

@@ -1,15 +1,16 @@
-import { resolve } from 'node:path';
+import { dirname, resolve, isAbsolute, relative, sep } from 'node:path';
 import type { AuthoredBudget } from './authored-budget.js';
 import { parseBudget } from './budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { checkAuthoredFlow } from './cli/check.js';
+import { authoredPreflight } from './authored-preflight.js';
 import { classifyOutcome, type RunLifecycleOptions, type RunReport } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { agentCwdDeclarationError, agentCwdTransportError } from './agent-cwd.js';
 import type { JournalClient } from './journal-client.js';
 import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
-import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput, type AuthoredStepContext } from './authored-step-output.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readRecordedOutcome, readSuccessfulOutput, type AuthoredStepContext, type RecordedRunOutcome } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
@@ -30,6 +31,7 @@ export function authoredWorkerRunner(
   // slot instead of being admitted and parked for want of a free worker.
   const slots = workerCapacity === undefined ? undefined
     : { agent: new WorkerSlots(workerCapacity), llm: new WorkerSlots(workerCapacity) };
+  const check = authoredPreflight(flowPath);
   const context: AuthoredStepContext = {
     ...(rootRunId === undefined ? {} : { rootRunId }),
     ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
@@ -43,7 +45,7 @@ export function authoredWorkerRunner(
     // (cli/check.ts), searching for the nearest flows.json from `flowPath`
     // and real-probing auth/model readiness. An authored agent step gets
     // nothing for free just because it was declared in TS instead of YAML.
-    const { report, flow: resolved } = checkAuthoredFlow(authoring, flowPath);
+    const { report, flow: resolved } = await check(authoring);
     if (!report.ok || resolved === undefined) {
       const refusal = report.diagnostics.find(
         (diagnostic): diagnostic is PreflightDiagnostic & { severity: 'refusal' } =>
@@ -77,7 +79,7 @@ export function authoredWorkerRunner(
     const execution = await classifyOutcome(journal, 'run', outcome, report, '', waitOptions);
     if (execution.exitCode === 3) {
       const parked = execution.report.parkedStep;
-      throw new AuthoredFlowExecutionError(
+      const error = new AuthoredFlowExecutionError(
         step.type === 'llm' ? 'llm_parked' : 'agent_parked',
         execution.report.diagnostics.at(-1)?.message
           ?? `flow "${definition.name}" step "${id}" parked`
@@ -86,6 +88,14 @@ export function authoredWorkerRunner(
         undefined,
         outcome.run_id,
       );
+      // Both `agent_parked` and `llm_parked` cover two unrelated situations —
+      // nothing attached to run the step, and the kernel's `needs_human`
+      // recovery wait after a worker attempt failed — and only the first is
+      // fixed by attaching a worker. The child's classification already knows
+      // which; carry it so the CLI boundary can name a remedy without
+      // re-deriving one from this message's wording.
+      error.parkCause = execution.report.parkCause;
+      throw error;
     }
     if (execution.exitCode !== 0) {
       // `execution.report.completionReason` is the RUN's reason (normally
@@ -161,10 +171,27 @@ export function authoredWorkerRunner(
           `f.agent options.model must be a string when set (got ${typeof options.model}).`,
         );
       }
-      if (options.cwd !== undefined && typeof options.cwd !== 'string') {
+      // The same lexical rule the kernel and `flows check` apply, raised here
+      // so an authored body is refused before a run exists rather than at
+      // dispatch. Whether the directory is there is the worker's question.
+      // An absolute cwd is honored when it names a directory inside the run
+      // root — it lowers to the same relative declaration — and refused when
+      // it escapes, because a declaration this contract cannot contain is
+      // worse than none.
+      const declaredCwd = options.cwd === undefined || !isAbsolute(options.cwd) ? options.cwd
+        : relative(process.cwd(), options.cwd) || undefined;
+      if (options.cwd !== undefined && isAbsolute(options.cwd) && declaredCwd !== undefined
+        && (declaredCwd === '..' || declaredCwd.startsWith(`..${sep}`) || isAbsolute(declaredCwd))) {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.cwd must name a directory inside the run root ${JSON.stringify(process.cwd())} (got ${JSON.stringify(options.cwd)}).`,
+        );
+      }
+      const cwdProblem = declaredCwd === undefined ? undefined : agentCwdDeclarationError(declaredCwd);
+      if (cwdProblem !== undefined) {
         throw new AuthoredFlowExecutionError(
           'agent_cli_unresolved',
-          `f.agent options.cwd must be a string when set (got ${typeof options.cwd}).`,
+          `f.agent options.cwd: ${cwdProblem}.`,
         );
       }
       if (options.transport !== undefined && options.transport !== 'direct' && options.transport !== 'relay') {
@@ -173,6 +200,10 @@ export function authoredWorkerRunner(
           `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
         );
       }
+      const cwdTransport = agentCwdTransportError(declaredCwd, options.transport);
+      if (cwdTransport !== undefined) {
+        throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.${cwdTransport}.`);
+      }
       const permissions = options.permissions;
       const permissionsSnapshot = permissions === undefined ? undefined
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
@@ -183,8 +214,7 @@ export function authoredWorkerRunner(
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
         ...(options.cli === undefined ? {} : { cli: options.cli }),
         ...(options.model === undefined ? {} : { model: options.model }),
-        // The kernel takes only an absolute cwd; a relative one means the runner's own directory.
-        ...(options.cwd === undefined ? {} : { cwd: resolve(options.cwd) }),
+        ...(declaredCwd === undefined ? {} : { cwd: declaredCwd }),
         ...(options.transport === undefined ? {} : { transport: options.transport }),
         ...(verification === undefined ? {} : { verification }),
       });
@@ -234,26 +264,43 @@ export function authoredDeterministicRunner(
   context: AuthoredStepContext = {},
 ) {
   const rootRunId = context.rootRunId;
-  return async (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> => {
+  // One lowering, two readers. `record` changes what the child run's verdict
+  // MEANS, so the reader changes with it; everything before the read — spec,
+  // admission key, budget, child index — is deliberately shared, because a
+  // recorded red command is still an ordinary child run.
+  function lower<T>(
+    id: string, command: string, terminal: boolean, leaseMs: number | undefined,
+    verification: NamedGate | undefined, onNonZero: 'record' | undefined,
+    read: (outcome: import('./protocol.js').RunOutcome) => Promise<T>,
+  ): Promise<T> {
     const spec = toKernelSpec(compileSpec({
       version: SPEC_SCHEMA_VERSION,
       name: `${name}/${id}`,
       steps: [{
         id, type: 'deterministic', command,
         ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
+        ...(onNonZero === undefined ? {} : { onNonZero }),
         ...(verification === undefined ? {} : { verification }),
       }],
     }));
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
-    const consume = async (outcome: import('./protocol.js').RunOutcome): Promise<string> => {
+    const consume = async (outcome: import('./protocol.js').RunOutcome): Promise<T> => {
       await recordAuthoredChild(journal, rootRunId, {
         step: id, runId: outcome.run_id, state: 'admitted', ...context.stepEdges?.(id),
       });
-      return readSuccessfulOutput(journal, outcome, id, journalSteps, context);
+      return read(outcome);
     };
-    if (terminal) return consume(await journal.runStart(spec, undefined, admissionKey));
+    if (terminal) return journal.runStart(spec, undefined, admissionKey).then(consume);
     return budget.execute(journal, spec, consume, admissionKey);
-  };
+  }
+  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> =>
+    lower(id, command, terminal, leaseMs, verification, undefined,
+      outcome => readSuccessfulOutput(journal, outcome, id, journalSteps, context));
+  /** `f.run(..., { onNonZero: 'record' })`: the exit code is the result, not a throw. */
+  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate): Promise<RecordedRunOutcome> =>
+    lower(id, command, false, leaseMs, verification, 'record',
+      outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
+  return lowerRun;
 }
 
 /**
@@ -284,6 +331,8 @@ function stepDetails(
     ...(found.stderrTail === undefined ? {} : { stderrTail: found.stderrTail }),
     ...(found.detail === undefined ? {} : { detail: found.detail }),
     ...(found.transcriptPath === undefined ? {} : { transcriptPath: found.transcriptPath }),
+    ...(found.attempts === undefined ? {} : { attempts: found.attempts }),
+    ...(found.attemptEvidence === undefined ? {} : { attemptEvidence: found.attemptEvidence }),
     ...(found.hint === undefined ? {} : { hint: found.hint }),
     ...(found.journalPath === undefined ? {} : { journalPath: found.journalPath }),
   };

package/src/cli/check-worker-surface.ts

@@ -0,0 +1,66 @@
+import { compileSpec } from '../compile.js';
+import type { FlowSpec } from '../spec.js';
+import type { CheckWarningDiagnostic } from './check.js';
+
+/** Enough ids to recognise the flow, not enough to bury the remedy. */
+const NAMED_STEP_LIMIT = 3;
+
+/**
+ * `agent` steps need a worker attached for step type `agent`, and nothing in a
+ * spec says whether one will be. `flows run` attaches the SDK's `AgentWorker`
+ * only under `--local-agent` (`cli/run.ts`); with no worker the run parks at
+ * the first agent step with `no worker is attached for step type "agent"`.
+ * `flows check` already walks these steps to print its `REQUIRES` line, so the
+ * fact is in hand — this spends it.
+ *
+ * Warning, never a refusal, and worded as a requirement rather than a
+ * prediction: worker attachment is *unknown* here, not absent. A worker can be
+ * attached out of band (an SDK `AgentWorker` against the same daemon, Cloud's
+ * workers for a hosted run), and `flows check` is daemon-free by construction,
+ * so it cannot see one either way.
+ *
+ * Scoped to `agent` steps. `--local-agent` attaches no `llm` worker on the
+ * YAML path, so naming it for `llm` steps would be false; those steps are not
+ * counted and not mentioned.
+ *
+ * Blind spot, shared with `permissions_unenforced`: an authored `.flow.ts`
+ * flow is checked through `checkMcpHeader`, which preflights a synthetic
+ * one-step header spec without executing the body. There are no compiled
+ * `agent` steps to count, so this diagnostic is silent for `.flow.ts`.
+ */
+export function agentWorkerDiagnostics(authoring: FlowSpec): CheckWarningDiagnostic[] {
+  const steps = agentStepIds(authoring);
+  if (steps.length === 0) return [];
+  return [{ severity: 'warning', kind: 'agent_worker_unresolved', message: message(steps) }];
+}
+
+/**
+ * Compiled `agent` steps, by id. Compilation is the only walk that sees them
+ * all: a YAML helper step (`slack: { post: … }`) is an `agent` step carrying a
+ * helper envelope and needs the same SDK agent worker, and only the compiler
+ * lowers it into one. `requirements.harnesses` is the wrong source — it
+ * deduplicates by harness, counts `llm` use, and omits helper steps entirely.
+ *
+ * A spec that does not compile yields no diagnostic rather than a thrown
+ * check: the compile refusal is owned by the existing preflight path and is
+ * the whole report in that case.
+ */
+function agentStepIds(authoring: FlowSpec): string[] {
+  try {
+    return compileSpec(authoring).steps.filter((step) => step.type === 'agent').map((step) => step.id);
+  } catch {
+    return [];
+  }
+}
+
+function message(steps: readonly string[]): string {
+  const named = steps.slice(0, NAMED_STEP_LIMIT).map((id) => `"${id}"`).join(', ');
+  const rest = steps.length - NAMED_STEP_LIMIT;
+  const list = rest > 0 ? `${named} and ${rest} more` : named;
+  const subject = steps.length === 1
+    ? `1 agent step (${list}) requires`
+    : `${steps.length} agent steps (${list}) require`;
+  return `${subject} an attached worker. For a local run, use \`flows run --local-agent <flow>\`, `
+    + 'unless you already attach an agent worker for this daemon. `flows check` does not verify worker '
+    + 'attachment: with no worker attached the run parks at the first agent step.';
+}