@relayflows/sdk 2.0.30 → 2.0.32

package/dist/authored-step-output.d.ts

@@ -17,19 +17,23 @@ export interface AuthoredStepContext {
     readonly stepEdges?: (step: string) => AuthoredStepEdges | undefined;
 }
 /**
- * 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:
@@ -43,6 +47,27 @@ export interface AuthoredStepContext {
  */
 export declare function readCompletedStepOutput(journal: JournalClient, runId: string, stepId: string, journalSteps: AuthoredFlowJournalStep[], context?: AuthoredStepContext): Promise<unknown>;
 export declare function readSuccessfulOutput(journal: JournalClient, outcome: RunOutcome, stepId: string, journalSteps: AuthoredFlowJournalStep[], context?: AuthoredStepContext): Promise<string>;
+/** 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 declare function readRecordedOutcome(journal: JournalClient, outcome: RunOutcome, stepId: string, journalSteps: AuthoredFlowJournalStep[], context?: AuthoredStepContext): Promise<RecordedRunOutcome>;
 export declare function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason;
 export declare function isSurfaceRunCompletionReason(value: unknown): value is ProtocolRunCompletionReason;
 export declare function isSurfaceFlowCompletionReason(value: unknown): value is FlowCompletionReason;

package/dist/authored-step-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-step-output.d.ts","sourceRoot":"","sources":["../src/authored-step-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAErI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,IAAI,wBAAwB,EAAE,mBAAmB,IAAI,2BAA2B,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAClJ,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG3E,OAAO,EAAmC,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEnG;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,EACvC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAoClB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,EACvC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAqBD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAG3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,2BAA2B,CAGjG;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAG3F"}
+{"version":3,"file":"authored-step-output.d.ts","sourceRoot":"","sources":["../src/authored-step-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAErI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,IAAI,wBAAwB,EAAE,mBAAmB,IAAI,2BAA2B,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAClJ,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG3E,OAAO,EAAmC,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEnG;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,EACvC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAsCD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,EACvC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,EACvC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;AAiDD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAG3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,2BAA2B,CAGjG;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAG3F"}

package/dist/authored-step-output.js

@@ -3,19 +3,23 @@ import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './cli/step-failure.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 /**
- * 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:
@@ -37,50 +41,100 @@ export async function readCompletedStepOutput(journal, runId, stepId, journalSte
     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;
-        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,
     });
     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, runId, stepId, reason, context, edges, header) {
+    let message = header;
+    let details;
+    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, outcome, stepId, journalSteps, context = {}) {
     const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
-        .catch(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'];
+}
+/**
+ * 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, outcome, stepId, journalSteps, context = {}) {
+    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) {
+    return (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;
-    });
-    if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
-        throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
-    }
-    return output['stdout_tail'];
+    };
 }
 function isStepCompleted(value, stepId) {
     if (!isRecord(value) || value['entry_type'] !== 'step.completed' || value['step_id'] !== stepId) {
@@ -91,6 +145,20 @@ function isStepCompleted(value, stepId) {
         && isSurfaceCompletionReason(payload['completionReason'])
         && '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) {
+    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) {
     return typeof value === 'string'
         && COMPLETION_REASONS.includes(value);

package/dist/authored-step-output.js.map

@@ -1 +1 @@
-{"version":3,"file":"authored-step-output.js","sourceRoot":"","sources":["../src/authored-step-output.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authored-step-output.js","sourceRoot":"","sources":["../src/authored-step-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,uBAAuB,EAA6B,MAAM,qBAAqB,CAAC;AACrI,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAKtE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACjH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAA0B,MAAM,0BAA0B,CAAC;AAgBnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAsB,EACtB,KAAa,EACb,MAAc,EACd,YAAuC,EACvC,UAA+B,EAAE;IAEjC,MAAM,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1E,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;QACxC,MAAM,iBAAiB,CAAC,KAAK,EAAE,sCAAsC,MAAM,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1C,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,MAAM,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EACpE,iBAAiB,MAAM,oBAAoB,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,6EAA6E;IAC7E,sEAAsE;IACtE,sEAAsE;IACtE,0EAA0E;IAC1E,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IACxF,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,MAAM,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EACvE,yBAAyB,MAAM,oBAAoB,SAAS,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE;QACpD,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,KAAK;KAC5E,CAAC,CAAC;IACH,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CACxB,OAAsB,EACtB,KAAa,EACb,MAAc,EACd,MAA8D,EAC9D,OAA4B,EAC5B,KAAgE,EAChE,MAAc;IAEd,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,OAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oEAAoE;QACpE,2DAA2D;QAC3D,OAAO,IAAI,uCAAuC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAClE,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF,OAAO,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,MAAM,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE;QACtD,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM;QACjE,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACxE,GAAG,KAAK;KACT,CAAC,CAAC;IACH,OAAO,IAAI,0BAA0B,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;AACzG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAsB,EACtB,OAAmB,EACnB,MAAc,EACd,YAAuC,EACvC,UAA+B,EAAE;IAEjC,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC;SACjG,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnE,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,MAAM,6BAA6B,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC;AAC/B,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAsB,EACtB,OAAmB,EACnB,MAAc,EACd,YAAuC,EACvC,UAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,MAAM,uBAAuB,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC;SACnG,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACxE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,aAAa,CAAC,KAAK,QAAQ;WACjE,OAAO,QAAQ,CAAC,aAAa,CAAC,KAAK,QAAQ;WAC3C,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjF,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EACpC,SAAS,MAAM,+DAA+D,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IACvC,OAAO;QACL,EAAE,EAAE,QAAQ,KAAK,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;QAC5C,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,EAAE,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM;KAClF,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,qBAAqB,CAAC,MAAc;IAC3C,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,KAAK,YAAY,0BAA0B;eAC1C,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS,IAAI,KAAK,CAAC,gBAAgB,KAAK,eAAe,CAAC,EAAE,CAAC;YAC1F,MAAM,IAAI,0BAA0B,CAAC,gBAAgB,EACnD,eAAe,MAAM,iCAAiC;kBAClD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,EACvD,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAWD,SAAS,eAAe,CAAC,KAAc,EAAE,MAAc;IACrD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,gBAAgB,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,MAAM,EAAE,CAAC;QAChG,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,QAAQ,CAAC,OAAO,CAAC;WACnB,yBAAyB,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;WACtD,QAAQ,IAAI,OAAO,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC;IAClF,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,OAAO,4BAA4B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC1B,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC1B,sBAA4C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC1D,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC1B,uBAA6C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa,EAAE,MAAc;IACtD,OAAO,IAAI,0BAA0B,CACnC,4BAA4B,EAC5B,MAAM,EACN,SAAS,EACT,KAAK,CACN,CAAC;AACJ,CAAC"}

package/dist/authored-verdict.d.ts

@@ -0,0 +1,28 @@
+import { 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 declare 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 declare function authoredVerdictOf(events: readonly JournalEvent[]): AuthoredVerdict | null;
+//# sourceMappingURL=authored-verdict.d.ts.map

package/dist/authored-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-verdict.d.ts","sourceRoot":"","sources":["../src/authored-verdict.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,eAAe,GAAG,IAAI,CAoBzF"}

package/dist/authored-verdict.js

@@ -0,0 +1,79 @@
+// 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, } from './authored-completion.js';
+/** The `instruction` discriminator `authored-root.ts` writes into the root step. */
+export const AUTHORED_ROOT_KIND = 'relayflows.authored-root.v1';
+/**
+ * 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) {
+    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) {
+    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) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : null;
+}
+//# sourceMappingURL=authored-verdict.js.map

package/dist/authored-verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-verdict.js","sourceRoot":"","sources":["../src/authored-verdict.ts"],"names":[],"mappings":"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"}

package/dist/authored-worker-step.d.ts

@@ -2,7 +2,7 @@ import type { AuthoredBudget } from './authored-budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
 import { type RunLifecycleOptions } from './cli/run.js';
 import type { JournalClient } from './journal-client.js';
-import { type AuthoredStepContext } from './authored-step-output.js';
+import { type AuthoredStepContext, type RecordedRunOutcome } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 /** Agent and LLM calls share the exact declarative preflight and lease wait. */
 export declare function authoredWorkerRunner(definition: {
@@ -21,5 +21,8 @@ export declare function authoredWorkerRunner(definition: {
  * the worker runner builds; a failed `f.run` and a failed `f.agent` now report
  * through one grammar.
  */
-export declare function authoredDeterministicRunner(name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget, context?: AuthoredStepContext): (id: string, command: string, terminal?: boolean, leaseMs?: number, verification?: NamedGate) => Promise<string>;
+export declare function authoredDeterministicRunner(name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget, context?: AuthoredStepContext): {
+    (id: string, command: string, terminal?: boolean, leaseMs?: number, verification?: NamedGate): Promise<string>;
+    recording(id: string, command: string, leaseMs?: number, verification?: NamedGate): Promise<RecordedRunOutcome>;
+};
 //# sourceMappingURL=authored-worker-step.d.ts.map

package/dist/authored-worker-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-worker-step.d.ts","sourceRoot":"","sources":["../src/authored-worker-step.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG5F,OAAO,EAAmB,KAAK,mBAAmB,EAAkB,MAAM,cAAc,CAAC;AAGzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAA4E,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAC/I,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAS3E,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EACtE,YAAY,EAAE,uBAAuB,EAAE,EAAE,WAAW,EAAE,mBAAmB,EACzE,gBAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,OAAO,EAC1E,SAAS,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC;IA0GvF,mFAAmF;iBACtE,OAAO,GAAG,IAAI;cAIX,MAAM,WAAW,YAAY,iBAAiB,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAiEhF,MAAM,UAAU,MAAM,YAAY,UAAU,iBAAiB,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;EAmB1G;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,cAAc,EACrG,OAAO,GAAE,mBAAwB,IAGnB,IAAI,MAAM,EAAE,SAAS,MAAM,EAAE,kBAAgB,EAAE,UAAU,MAAM,EAAE,eAAe,SAAS,KAAG,OAAO,CAAC,MAAM,CAAC,CAoB1H"}
+{"version":3,"file":"authored-worker-step.d.ts","sourceRoot":"","sources":["../src/authored-worker-step.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG5F,OAAO,EAAmB,KAAK,mBAAmB,EAAkB,MAAM,cAAc,CAAC;AAIzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAiG,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC7L,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAS3E,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EACtE,YAAY,EAAE,uBAAuB,EAAE,EAAE,WAAW,EAAE,mBAAmB,EACzE,gBAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,OAAO,EAC1E,SAAS,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC;IAmHvF,mFAAmF;iBACtE,OAAO,GAAG,IAAI;cAIX,MAAM,WAAW,YAAY,iBAAiB,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqFhF,MAAM,UAAU,MAAM,YAAY,UAAU,iBAAiB,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;EAmB1G;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,cAAc,EACrG,OAAO,GAAE,mBAAwB;SAgCX,MAAM,WAAW,MAAM,gCAA8B,MAAM,iBAAiB,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;kBAInG,MAAM,WAAW,MAAM,YAAY,MAAM,iBAAiB,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;EAI5H"}

package/dist/authored-worker-step.js

@@ -1,11 +1,12 @@
-import { resolve } from 'node:path';
+import { isAbsolute, relative, sep } from 'node:path';
 import { parseBudget } from './budget.js';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { checkAuthoredFlow } from './cli/check.js';
+import { authoredPreflight } from './authored-preflight.js';
 import { classifyOutcome } from './cli/run.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { agentCwdDeclarationError, agentCwdTransportError } from './agent-cwd.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
-import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readRecordedOutcome, readSuccessfulOutput } from './authored-step-output.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
@@ -17,6 +18,7 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
     // 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 = {
         ...(rootRunId === undefined ? {} : { rootRunId }),
         ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
@@ -30,7 +32,7 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
         // (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.severity === 'refusal');
             throw new AuthoredFlowExecutionError(refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
@@ -58,10 +60,18 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
             const execution = await classifyOutcome(journal, 'run', outcome, report, '', waitOptions);
             if (execution.exitCode === 3) {
                 const parked = execution.report.parkedStep;
-                throw new AuthoredFlowExecutionError(step.type === 'llm' ? 'llm_parked' : 'agent_parked', execution.report.diagnostics.at(-1)?.message
+                const error = new AuthoredFlowExecutionError(step.type === 'llm' ? 'llm_parked' : 'agent_parked', execution.report.diagnostics.at(-1)?.message
                     ?? `flow "${definition.name}" step "${id}" parked`
                         + (parked !== undefined ? ` (${parked.type})` : '')
                         + ': no worker is attached to run it.', 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
@@ -121,12 +131,30 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
             if (options.model !== undefined && typeof options.model !== 'string') {
                 throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.model must be a string when set (got ${typeof options.model}).`);
             }
-            if (options.cwd !== undefined && typeof options.cwd !== 'string') {
-                throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.cwd must be a string when set (got ${typeof options.cwd}).`);
+            // 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: ${cwdProblem}.`);
             }
             if (options.transport !== undefined && options.transport !== 'direct' && options.transport !== 'relay') {
                 throw new AuthoredFlowExecutionError('agent_cli_unresolved', `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');
@@ -137,8 +165,7 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
                 ...(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 }),
             });
@@ -184,13 +211,18 @@ export function authoredWorkerRunner(definition, journal, flowPath, journalSteps
  */
 export function authoredDeterministicRunner(name, journal, journalSteps, budget, context = {}) {
     const rootRunId = context.rootRunId;
-    return async (id, command, terminal = false, leaseMs, verification) => {
+    // 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(id, command, terminal, leaseMs, verification, onNonZero, read) {
         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 }),
                 }],
         }));
@@ -199,12 +231,16 @@ export function authoredDeterministicRunner(name, journal, journalSteps, budget,
             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));
+            return journal.runStart(spec, undefined, admissionKey).then(consume);
         return budget.execute(journal, spec, consume, admissionKey);
-    };
+    }
+    const lowerRun = (id, command, terminal = false, leaseMs, verification) => 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, command, leaseMs, verification) => lower(id, command, false, leaseMs, verification, 'record', outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
+    return lowerRun;
 }
 /**
  * Lift the step-shaped fields off a run diagnostic.
@@ -233,6 +269,8 @@ function stepDetails(diagnostic) {
         ...(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 }),
     };