@relayflows/sdk 2.0.29 → 2.0.31

package/dist/cli/observer-session.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The observer half of `flows run` / `flows resume`: once the run id is known,
+ * project the run into its `wf-<runId>` channel and mint a read-only link
+ * scoped to that channel, so the link opens on this run's step graph instead
+ * of an arbitrary workspace channel. The link is printed on stderr the moment
+ * it exists, so a human can follow the run live, and again after `RUN`.
+ *
+ * Best-effort throughout: no workspace key means no session, and a projection
+ * or mint failure is a labeled stderr line. The run never depends on it.
+ */
+import type { CliIo } from '../cli.js';
+import type { JournalEvent } from '../journal-reader.js';
+import { type MintObserverOptions } from '../observer-link.js';
+import type { ProgressEvent } from '../progress.js';
+import { type ProjectionFetch } from '../run-projection.js';
+import type { RunReport } from './run.js';
+type MintOutcome = {
+    observerUrl?: string;
+    warning?: string;
+};
+export interface ObserverSession {
+    /** YAML runs: every entry `run.start {watch}` / `run.watch` pushes. */
+    onJournalEntry(entry: JournalEvent): void;
+    /** Authored runs: the root's id and name, known once it is admitted. */
+    onRunStarted(run: {
+        runId: string;
+        flow: string;
+        resumed?: boolean;
+    }): void;
+    /** Authored runs: step transitions from the body's executor. */
+    onProgress(event: ProgressEvent): void;
+    /** Close the projection from the final report and settle the link. */
+    finish(report: RunReport): Promise<MintOutcome> | undefined;
+}
+export interface ObserverSessionDeps {
+    fetch?: ProjectionFetch;
+    mint?: (options: MintObserverOptions) => Promise<MintOutcome>;
+}
+export declare function createObserverSession(command: 'run' | 'resume', io: CliIo, env?: NodeJS.ProcessEnv, deps?: ObserverSessionDeps): ObserverSession | undefined;
+export {};
+//# sourceMappingURL=observer-session.d.ts.map

package/dist/cli/observer-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-session.d.ts","sourceRoot":"","sources":["../../src/cli/observer-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAA2C,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACxG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACmD,KAAK,eAAe,EAC7E,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,KAAK,WAAW,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAK9D,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1C,wEAAwE;IACxE,YAAY,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E,gEAAgE;IAChE,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC,sEAAsE;IACtE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/D;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,KAAK,GAAG,QAAQ,EACzB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,mBAAwB,GAC7B,eAAe,GAAG,SAAS,CA2D7B"}

package/dist/cli/observer-session.js

@@ -0,0 +1,78 @@
+/**
+ * The observer half of `flows run` / `flows resume`: once the run id is known,
+ * project the run into its `wf-<runId>` channel and mint a read-only link
+ * scoped to that channel, so the link opens on this run's step graph instead
+ * of an arbitrary workspace channel. The link is printed on stderr the moment
+ * it exists, so a human can follow the run live, and again after `RUN`.
+ *
+ * Best-effort throughout: no workspace key means no session, and a projection
+ * or mint failure is a labeled stderr line. The run never depends on it.
+ */
+import { createJournalProjector } from '../journal-projection.js';
+import { mintObserverUrl, resolveObserverLinkEnv } from '../observer-link.js';
+import { createRunProjection, runChannelName, } from '../run-projection.js';
+/** Bounded so an unreachable Relaycast cannot hold the CLI open. */
+const DRAIN_GRACE_MS = 5_000;
+export function createObserverSession(command, io, env = process.env, deps = {}) {
+    const link = resolveObserverLinkEnv(env);
+    if (link.suppressed || link.workspaceKey === undefined)
+        return undefined;
+    const workspaceKey = link.workspaceKey;
+    const mint = deps.mint ?? mintObserverUrl;
+    const liveSinceMs = command === 'resume' ? Date.now() : 0;
+    let projection;
+    let minted;
+    let rootRunId;
+    const mintFor = (runId) => minted ??= mint({
+        workspaceKey,
+        channel: runChannelName(runId),
+        ...(link.baseUrl === undefined ? {} : { baseUrl: link.baseUrl }),
+        ...(link.dashboardUrl === undefined ? {} : { dashboardUrl: link.dashboardUrl }),
+    }).catch((error) => ({ warning: error instanceof Error ? error.message : 'unknown mint error' }));
+    const open = (run) => {
+        if (projection !== undefined)
+            return projection;
+        rootRunId = run.runId;
+        projection = createRunProjection({
+            workspaceKey,
+            ...(link.baseUrl === undefined ? {} : { baseUrl: link.baseUrl }),
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+            diagnostic: message => io.stderr(`[observer] ${message}`),
+        }, run);
+        void mintFor(run.runId).then(outcome => {
+            if (outcome.observerUrl !== undefined)
+                io.stderr(`Observer: ${outcome.observerUrl}`);
+        });
+        return projection;
+    };
+    const project = createJournalProjector(run => open({ ...run, ...(liveSinceMs > 0 ? { resumed: true } : {}) }), liveSinceMs);
+    return {
+        onJournalEntry(entry) {
+            try {
+                project(entry);
+            }
+            catch (error) {
+                io.stderr(`[observer] could not project journal entry ${entry.seq}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        onRunStarted: run => { open(run); },
+        onProgress(event) { projection?.step(event); },
+        finish(report) {
+            const runId = rootRunId ?? report.runId;
+            if (runId === undefined)
+                return undefined;
+            if (projection === undefined) {
+                io.stderr('[observer] this run was not projected (the daemon did not stream its journal); '
+                    + 'the observer link opens an empty channel');
+            }
+            projection?.finish({
+                status: report.status === 'parked' ? 'parked' : report.completionReason === 'canceled' ? 'canceled'
+                    : report.ok ? 'completed' : 'failed',
+                ...(report.completionReason === undefined ? {} : { completionReason: report.completionReason }),
+            });
+            const drained = projection?.close(DRAIN_GRACE_MS) ?? Promise.resolve();
+            return drained.then(() => mintFor(runId));
+        },
+    };
+}
+//# sourceMappingURL=observer-session.js.map

package/dist/cli/observer-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-session.js","sourceRoot":"","sources":["../../src/cli/observer-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAA4B,MAAM,qBAAqB,CAAC;AAExG,OAAO,EACL,mBAAmB,EAAE,cAAc,GACpC,MAAM,sBAAsB,CAAC;AAK9B,oEAAoE;AACpE,MAAM,cAAc,GAAG,KAAK,CAAC;AAkB7B,MAAM,UAAU,qBAAqB,CACnC,OAAyB,EACzB,EAAS,EACT,MAAyB,OAAO,CAAC,GAAG,EACpC,OAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzE,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,eAAe,CAAC;IAC1C,MAAM,WAAW,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,UAAqC,CAAC;IAC1C,IAAI,MAAwC,CAAC;IAC7C,IAAI,SAA6B,CAAC;IAElC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAwB,EAAE,CAAC,MAAM,KAAK,IAAI,CAAC;QACvE,YAAY;QACZ,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAChE,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;KAChF,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;IAE3G,MAAM,IAAI,GAAG,CAAC,GAA+E,EAAiB,EAAE;QAC9G,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC;QAChD,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC;QACtB,UAAU,GAAG,mBAAmB,CAAC;YAC/B,YAAY;YACZ,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YAChE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1D,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,OAAO,EAAE,CAAC;SAC1D,EAAE,GAAG,CAAC,CAAC;QACR,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;YACrC,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;gBAAE,EAAE,CAAC,MAAM,CAAC,aAAa,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;QACH,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,sBAAsB,CACpC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,CACpF,CAAC;IAEF,OAAO;QACL,cAAc,CAAC,KAAK;YAClB,IAAI,CAAC;gBAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAAC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACrC,EAAE,CAAC,MAAM,CAAC,8CAA8C,KAAK,CAAC,GAAG,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClI,CAAC;QACH,CAAC;QACD,YAAY,EAAE,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnC,UAAU,CAAC,KAAK,IAAI,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,CAAC,MAAM;YACX,MAAM,KAAK,GAAG,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC;YACxC,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,EAAE,CAAC,MAAM,CAAC,iFAAiF;sBACvF,0CAA0C,CAAC,CAAC;YAClD,CAAC;YACD,UAAU,EAAE,MAAM,CAAC;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU;oBACjG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ;gBACtC,GAAG,CAAC,MAAM,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC;aAChG,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACvE,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/run.d.ts

@@ -1,11 +1,12 @@
 import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait } from '../authored-flow-error.js';
 import type { ProgressEvent } from '../progress.js';
+import type { JournalEvent } from '../journal-reader.js';
 import { type EnsureDaemonOptions } from '../daemon-lifecycle.js';
-import type { RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
+import type { ParkCause, RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
 import { JournalClient } from '../journal-client.js';
 import type { RunCompletionReason, RunOutcome, RunStatus } from '../protocol.js';
 import type { StepType } from '../spec.js';
-import type { LoweredCompletionReason } from '../authored-flow-executor.js';
+import { type LoweredCompletionReason } from '../authored-completion.js';
 import { type CheckReport } from './check.js';
 export type RunExitCode = 0 | 1 | 2 | 3;
 export type RunCommand = 'run' | 'resume' | 'answer';
@@ -28,6 +29,13 @@ export interface RunReport {
     socketPath?: string;
     status?: RunStatus;
     completionReason?: RunCompletionReason;
+    /**
+     * What the body passed to `done(reason, { detail })`, normalized: redacted,
+     * trimmed, and bounded to 2,000 code points. Absent for every one-argument
+     * call, so an existing report keeps its exact shape — and absent on the
+     * paths where no authored body declared the outcome at all.
+     */
+    completionDetail?: string;
     completedSteps?: number;
     reuse?: {
         fromRunId: string;
@@ -35,6 +43,17 @@ export interface RunReport {
         executedSteps: number;
     };
     parkedStep?: ParkedStep;
+    /**
+     * Why an exit-3 park happened, when classification established it.
+     *
+     * Carried structurally so a consumer — including this package's own authored
+     * boundaries — can tell "nothing is attached to run this step" from "the
+     * kernel is waiting for a human to recover it" without matching on the
+     * rendered message. Absent means the cause was not established, never
+     * `worker_unavailable` by default: recommending a worker for a `needs_human`
+     * park is the wrong answer, and guessing it is worse than saying nothing.
+     */
+    parkCause?: ParkCause;
     /** The open `f.human` question a parked authored run is waiting on. */
     humanWait?: AuthoredHumanWait;
     /** `flows answer` only: the answer it recorded. */
@@ -67,6 +86,14 @@ export interface RunLifecycleOptions {
     onPtyReady?: (path: string) => void;
     reuseFromRunId?: string;
     onProgress?: (event: ProgressEvent) => void;
+    /** Stream the run's journal entries while it runs (YAML runs, via `run.start {watch}` / `run.watch`). */
+    onJournalEntry?: (entry: JournalEvent) => void;
+    /** An authored root was admitted: its id is known before its body runs. */
+    onRunStarted?: (run: {
+        runId: string;
+        flow: string;
+        resumed?: boolean;
+    }) => void;
     localAgent?: boolean;
     /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
     agentCapacity?: number;
@@ -129,6 +156,7 @@ export declare function authoredHumanParked(command: RunCommand, base: CheckRepo
 export declare function authoredCompletion(command: RunCommand, base: RunReport, socketPath: string, result: {
     name: string;
     completionReason: LoweredCompletionReason;
+    completionDetail?: string;
     journalSteps: readonly unknown[];
 }, runId: string | undefined): RunExecution;
 /**

package/dist/cli/run.d.ts.map

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

package/dist/cli/run.js

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from '../worker-lease.js';
 import { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from '../communication/preflight.js';
 import { parseHumanRecipient } from '../human-to.js';
@@ -12,11 +13,13 @@ import { socketPathFor } from '../daemon-connection.js';
 import { ensureDaemon } from '../daemon-lifecycle.js';
 import { isAuthoredFlowPath } from '../direct-input.js';
 import { daemonRefusal } from './daemon-refusal.js';
+import { authoredInput, authoredWorkerRemedy, localAgentRemedy, } from './local-agent-remedy.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './step-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import { readAuthoredRootMetadata, resumeDurableAuthoredFlow } from '../authored-root.js';
+import { singleLineCompletionDetail, } from '../authored-completion.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
 import { checkFlow, } from './check.js';
 export async function runFlow(path, dataDir, options = {}) {
@@ -60,7 +63,9 @@ async function executeCheckedFlow(checked, dataDir, options) {
             const { attachCommunicationWorkers } = await import('../communication/local.js');
             communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
         }
-        const outcome = await client.runStart(spec, options.reuseFromRunId);
+        if (options.onJournalEntry !== undefined)
+            client.on('entry', options.onJournalEntry);
+        const outcome = await startWatched(client, spec, options);
         const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
         if (options.reuseFromRunId !== undefined) {
             execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
@@ -81,6 +86,8 @@ async function executeCheckedFlow(checked, dataDir, options) {
         return protocolFailure('run', base, socketPath, communicationWorkers?.failure ?? localAgent?.failure ?? error);
     }
     finally {
+        if (options.onJournalEntry !== undefined)
+            client.off('entry', options.onJournalEntry);
         try {
             await communicationWorkers?.close();
         }
@@ -94,6 +101,26 @@ async function executeCheckedFlow(checked, dataDir, options) {
         }
     }
 }
+/**
+ * `run.start`, streaming the run's entries to `onJournalEntry` when one is
+ * given. A daemon that predates `watch` refuses the field while decoding,
+ * before any run exists, so starting again without it is the same request
+ * minus the observation — never a second run.
+ */
+async function startWatched(client, spec, options) {
+    const onEntry = options.onJournalEntry;
+    if (onEntry === undefined)
+        return client.runStart(spec, options.reuseFromRunId);
+    try {
+        return await client.runStart(spec, options.reuseFromRunId, undefined, true);
+    }
+    catch (error) {
+        if (!(error instanceof JournalProtocolError) || error.code !== 'bad_request'
+            || !/unknown field `watch`/.test(error.message))
+            throw error;
+        return await client.runStart(spec, options.reuseFromRunId);
+    }
+}
 export async function resumeFlow(runId, dataDir, options = {}) {
     const socketPath = socketFor(dataDir);
     const base = emptyReport('resume');
@@ -104,16 +131,32 @@ export async function resumeFlow(runId, dataDir, options = {}) {
     let communicationWorkers;
     let authoredAgent;
     let authoredLlm;
+    let llmFailure;
     let authoredLlmClient;
+    // Hoisted so the catch below can build the authored park remedy from the same
+    // metadata this resume was admitted against — the journal is the only place
+    // the flow path and the original `--input` survive a process boundary.
+    let authoredRoot;
     const workerCapacity = options.agentCapacity ?? DEFAULT_LOCAL_AGENT_CAPACITY;
     try {
-        const authoredRoot = await readAuthoredRootMetadata(client, runId);
+        authoredRoot = await readAuthoredRootMetadata(client, runId);
         if (authoredRoot !== undefined) {
+            // Both worker-surface mismatches are refusals, not protocol failures.
+            // They used to throw bare `Error`s, which landed on `protocol_error`
+            // ("RUN <id> unknown") and told nobody what to do instead; and the
+            // second one is the exact complaint this change answers — `--local-agent`
+            // accepted on a run that cannot grow one is worse than rejected, because
+            // the run parks again with a message that has not changed.
             if (authoredRoot.localAgentStream !== undefined && !options.localAgent) {
-                throw new Error('authored root requires --local-agent to resume its pinned worker surface');
+                return localAgentRefusal(base, runId, socketPath, `Run "${runId}" was started with a local agent worker surface, so resuming it needs the same flag.`
+                    + ` To continue this run: ${resumeCommand(runId, dataDir, true)}.`);
             }
             if (authoredRoot.localAgentStream === undefined && options.localAgent) {
-                throw new Error('authored root was started without a local agent worker surface');
+                return localAgentRefusal(base, runId, socketPath, `Run "${runId}" was started without a local agent worker surface:`
+                    + ' --local-agent is admitted at run start; start a new run.'
+                    + localAgentRemedy(authoredWorkerRemedy('worker_unavailable', false, {
+                        path: authoredRoot.flowPath, input: authoredInputArgument(authoredRoot), dataDir,
+                    })));
             }
             if (options.localAgent) {
                 authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, authoredRoot.localAgentStream, workerCapacity);
@@ -121,6 +164,10 @@ export async function resumeFlow(runId, dataDir, options = {}) {
                 await authoredLlmClient.connect();
                 await authoredLlmClient.hello('flows-authored-resume-llm');
                 authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity);
+                authoredLlm.on('error', onWorkerFailure('resume-llm', error => {
+                    llmFailure = error;
+                    client.close();
+                }));
                 await authoredLlm.attach();
             }
             const result = await resumeDurableAuthoredFlow(runId, client, {
@@ -146,6 +193,13 @@ export async function resumeFlow(runId, dataDir, options = {}) {
                 communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
             }
         }
+        const onEntry = options.onJournalEntry;
+        if (onEntry !== undefined) {
+            client.on('entry', onEntry);
+            // Observation never decides a resume: a watch the daemon refuses leaves
+            // the run unprojected, and the resume below reports the run's own fate.
+            await client.runWatch(runId).catch(() => client.off('entry', onEntry));
+        }
         let outcome = await client.runResume(runId, options.allowHumanInfluenced);
         if (await resumeHelperEffect(client, runId, dataDir)) {
             outcome = await client.runResume(runId, options.allowHumanInfluenced);
@@ -178,11 +232,38 @@ export async function resumeFlow(runId, dataDir, options = {}) {
         if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
             return authoredStepFailure('resume', base, socketPath, error, runId);
         }
+        // An authored resume that parks for want of a worker is a park, reported
+        // like the run path's — and with the same remedy, because an authored root
+        // admits its worker at run start: resuming again cannot attach one, so the
+        // only honest instruction is a new run carrying the same `--input`.
+        // `runId` here is the CHILD run holding the evidence; the root this resume
+        // named stays separate, so `flows` can still collect it.
+        if (error instanceof AuthoredFlowExecutionError && (error.code === 'agent_parked' || error.code === 'llm_parked')) {
+            return {
+                exitCode: 3,
+                report: {
+                    ...base,
+                    ok: false,
+                    runId: error.runId ?? runId,
+                    rootRunId: runId,
+                    socketPath,
+                    status: 'parked',
+                    parkCause: error.parkCause,
+                    diagnostics: [...base.diagnostics, {
+                            severity: 'parked',
+                            kind: 'run_parked',
+                            message: error.message + localAgentRemedy(authoredWorkerRemedy(error.parkCause, options.localAgent === true, { path: authoredRoot?.flowPath, input: authoredInputArgument(authoredRoot), dataDir })),
+                        }],
+                },
+            };
+        }
         if (error instanceof AuthoredHumanParked) {
             return authoredHumanParked('resume', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
         }
         if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
-            return protocolFailure('resume', base, socketPath, error, runId);
+            const cause = error instanceof AuthoredFlowExecutionError
+                ? error : llmFailure ?? authoredAgent?.failure ?? error;
+            return protocolFailure('resume', base, socketPath, cause, runId);
         }
         return {
             exitCode: 2,
@@ -200,6 +281,8 @@ export async function resumeFlow(runId, dataDir, options = {}) {
     }
     finally {
         try {
+            if (options.onJournalEntry !== undefined)
+                client.off('entry', options.onJournalEntry);
             await communicationWorkers?.close();
             await authoredLlm?.close();
             authoredLlmClient?.close();
@@ -210,6 +293,42 @@ export async function resumeFlow(runId, dataDir, options = {}) {
         }
     }
 }
+/**
+ * A `--local-agent` mismatch, refused before the resume touches the journal.
+ *
+ * Exit 2 and `ok` left false by `emptyReport`: nothing ran, so this is the same
+ * shape as every other pre-journal refusal on this surface (docs/SURFACE.md §5).
+ * It returns rather than throwing so no worker is attached on the way out.
+ */
+function localAgentRefusal(base, runId, socketPath, message) {
+    return {
+        exitCode: 2,
+        report: { ...base, runId, socketPath,
+            diagnostics: [...base.diagnostics, { severity: 'refusal', kind: 'local_agent_unavailable', message }] },
+    };
+}
+/**
+ * The `--input` argument a new run of this authored root would have to repeat,
+ * rendered back from the journaled metadata.
+ *
+ * `absent` when the root recorded no input, and also when the recorded input is
+ * something `JSON.stringify` cannot render — the remedy formatter then says an
+ * input is required instead of printing a command that would be refused as
+ * `input_invalid`. What it must never do is substitute `{}`: that is a
+ * different invocation of the flow than the one that parked.
+ *
+ * Unlike `runDirectFlow`, this side has only the decoded value: the journal
+ * records the input, not the `--input` word that carried it, so a run started
+ * from a file comes back as inline JSON. `authoredInput` is what keeps that
+ * honest about its own size — a recorded input can be larger than a shell
+ * argument even when the file that supplied it was unremarkable.
+ */
+function authoredInputArgument(metadata) {
+    if (metadata === undefined || !metadata.inputPresent)
+        return { kind: 'absent' };
+    const rendered = JSON.stringify(metadata.input);
+    return authoredInput(typeof rendered === 'string' ? rendered : undefined);
+}
 /**
  * A step that ran and failed, reported as the run failure it is.
  *
@@ -302,8 +421,18 @@ export function authoredCompletion(command, base, socketPath, result, runId) {
         ...fromBase(command, base),
         ...(runId === undefined ? {} : { runId }),
         socketPath,
+        ...(result.completionDetail === undefined ? {} : { completionDetail: result.completionDetail }),
         completedSteps: result.journalSteps.length,
     };
+    // Two spellings of the same fact, on purpose. `detail` is the structured
+    // one — the `StepFailedDetails` key the diagnostic already declares, here
+    // describing the AUTHOR's verdict rather than the daemon's account of a
+    // failing step — and keeps the body's own line breaks. `said` is the same
+    // text folded onto one line for the message, because Cloud renders a run's
+    // `error` through a view that elides the middle of a long one.
+    const detail = result.completionDetail;
+    const evidence = detail === undefined ? {} : { detail };
+    const said = detail === undefined ? '' : singleLineCompletionDetail(detail);
     switch (result.completionReason) {
         case 'success':
             return {
@@ -317,7 +446,9 @@ export function authoredCompletion(command, base, socketPath, result, runId) {
                     ...common, ok: true, status: 'completed', completionReason: 'success',
                     diagnostics: [...base.diagnostics, {
                             severity: 'declined', kind: 'run_declined',
-                            message: 'Flow deliberately chose not to act on this input.',
+                            ...evidence,
+                            message: 'Flow deliberately chose not to act on this input.'
+                                + (detail === undefined ? '' : ` ${said}`),
                         }],
                 },
             };
@@ -328,7 +459,9 @@ export function authoredCompletion(command, base, socketPath, result, runId) {
                     ...common, ok: false, status: 'parked',
                     diagnostics: [...base.diagnostics, {
                             severity: 'parked', kind: 'run_parked',
-                            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
+                            ...evidence,
+                            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`
+                                + (detail === undefined ? '' : ` ${said}`),
                         }],
                 },
             };
@@ -344,9 +477,16 @@ export function authoredCompletion(command, base, socketPath, result, runId) {
                     ...common, ok: false, status: 'failed', completionReason: 'step_failed',
                     diagnostics: [...base.diagnostics, {
                             severity: 'failure', kind: 'step_failed',
-                            message: `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
-                                + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
-                                + 'every step the flow ran before it decided.',
+                            ...evidence,
+                            // With a detail, the flow's own account REPLACES the generic
+                            // sentence: "no step-level evidence to inspect" is the only thing
+                            // there is to say when the body said nothing, and saying it
+                            // beside a real explanation would bury the explanation.
+                            message: detail === undefined
+                                ? `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
+                                    + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
+                                    + 'every step the flow ran before it decided.'
+                                : `Flow "${result.name}" declared done("step_failed"): ${said}`,
                         }],
                 },
             };
@@ -540,31 +680,51 @@ export async function classifyOutcome(client, command, outcome, base, socketPath
             report: {
                 ...report,
                 parkedStep,
+                parkCause: needsHuman ? 'needs_human' : 'worker_unavailable',
                 diagnostics: [...report.diagnostics, {
                         severity: 'parked',
                         kind: 'run_parked',
                         message: needsHuman
                             ? `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): waiting for human recovery after the worker attempt failed.`
                             : `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): no worker is attached for step type "${parkedStep.type}".`
-                                // Only suggest the `--local-agent` remedy for YAML flows.
-                                // Authored TS flows require `--input`; the bare command below
-                                // would be refused (Cursor Bugbot flagged as LOW on flows#293).
-                                // For TS we omit the hint rather than fabricate a syntactically
-                                // valid but semantically wrong command — the direct-run refusal
-                                // for TS already names its own missing --input.
-                                + (command === 'run'
-                                    && parkedStep.type === 'agent'
-                                    && !options.localAgent
-                                    && base.path !== undefined
-                                    && !isAuthoredFlowPath(base.path)
-                                    ? ` To start a new run with a local agent worker: flows run --local-agent '${base.path.replace(/'/g, "'\\''")}'. Declared workspace or stream surfaces require a worker that holds their pins.`
-                                    : ''),
+                                + localAgentRemedy(declarativeWorkerRemedy(command, current.run_id, parkedStep, base, options)),
                     }],
             },
         };
     }
     return protocolFailure(command, base, socketPath, new Error(`relayflowd returned status ${current.status} without a classifiable completion`), current.run_id);
 }
+/**
+ * Which remedy a worker park gets from the declarative classifier.
+ *
+ * An authored `.flow.ts` is deliberately SILENT here, and the suppression is
+ * tested first on purpose. Its remedy is a new run carrying the same `--input`,
+ * an argument this function does not have; `runDirectFlow` and `resumeFlow`
+ * render it once at the authored boundary where the input (or the journaled
+ * metadata holding it) is in hand. `classifyOutcome` also runs once per
+ * authored `f.agent` CHILD run, so answering here as well would append a
+ * remedy to every child message on the way out — and, on resume, a second
+ * contradictory one after the attached-worker branch below.
+ *
+ * `llm` parks get nothing, unchanged: the declarative verbs attach an
+ * agent-only worker (local-agent.ts advertises `['agent']`), so `--local-agent`
+ * is not a remedy for an `llm` step outside the authored path, which attaches
+ * an `LlmWorker` of its own.
+ */
+function declarativeWorkerRemedy(command, runId, parkedStep, base, options) {
+    const dataDir = options.dataDir;
+    if (parkedStep.type !== 'agent')
+        return { kind: 'none' };
+    if (base.path !== undefined && isAuthoredFlowPath(base.path))
+        return { kind: 'none' };
+    if (options.localAgent === true)
+        return { kind: 'attached' };
+    if (command === 'resume')
+        return { kind: 'spec-resume', runId, dataDir };
+    if (command === 'run' && base.path !== undefined)
+        return { kind: 'spec-run', path: base.path, dataDir };
+    return { kind: 'none' };
+}
 // Bound on re-polling a run that reports `running` with no identifiable step.
 // 40 x 50ms = 2s, far longer than the sub-second window observed in #179, and
 // short enough that a genuinely stuck run still reports rather than hangs.
@@ -593,6 +753,8 @@ async function inspectOutOfBandStep(client, runId) {
         ...(runningStep !== undefined ? { runningStep } : {}),
     };
 }
+// Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
+const LEASE_SWEEP_GRACE_MS = 5_000;
 async function waitForRunningStep(client, runId, runningStep, options) {
     let leaseDeadlineMs = runningStep.leaseDeadlineMs;
     if (!Number.isFinite(leaseDeadlineMs)) {
@@ -606,7 +768,7 @@ async function waitForRunningStep(client, runId, runningStep, options) {
     });
     while (true) {
         throwIfCanceled(options.signal, runningStep.id);
-        const remainingMs = leaseDeadlineMs - Date.now();
+        const remainingMs = leaseDeadlineMs + LEASE_SWEEP_GRACE_MS - Date.now();
         if (remainingMs <= 0) {
             throw new Error(`worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`);
         }