@relayflows/sdk 2.0.30 → 2.0.32

package/src/cli/cloud-status-view.ts

@@ -0,0 +1,213 @@
+// The `flows status --cloud` page: one run record and its step rows, rendered
+// in the grammar `cli/status.ts` already uses for a local run.
+//
+// Moved out of `cli/cloud-read.ts` so the one-shot read and the watched read
+// (cli/cloud-live.ts) draw the identical page through the identical scrubber.
+// A watched frame that redacted differently to the page it replaces would be
+// a leak nobody could see from either file alone.
+//
+// Live rows are the part this view has that the local one does not have to
+// think about: Cloud's step snapshot is the only evidence, and where it is
+// silent the row stays silent. An elapsed time is derived only for a step that
+// is demonstrably running, an attempt number is printed only where the
+// snapshot establishes one, and neither a maximum-attempt denominator nor a
+// wait id is invented — Cloud's step rows carry neither.
+
+import { isCloudRunActive } from '../cloud-run-record.js';
+import { redact } from '../redact.js';
+import type { CloudRunDetail, CloudStep } from '../cloud-read.js';
+import { ago, dollars, errorLines, safe, thousands } from './cloud-format.js';
+import { formatDuration } from './status.js';
+
+const GLYPH: Record<string, string> = {
+  completed: '✓', succeeded: '✓', failed: '✗', cancelled: '✗',
+  running: '↻', backoff: '↻', waiting: '⏸', needs_human: '⏸',
+  pending: '○', queued: '○',
+};
+
+/**
+ * Step statuses that mean the step is in flight, in the local view's
+ * vocabulary (`cli/status.ts`). These are the rows with no `durationMs` and no
+ * `endTime`: their timing has to be derived, and their attempt number is the
+ * one being attempted rather than a count of the ones that finished.
+ */
+const ACTIVE_STEP_STATUSES: readonly string[] = ['running', 'backoff', 'waiting', 'needs_human'];
+
+function glyph(step: CloudStep): string {
+  if (step.status === 'completed' && step.completion_reason !== null && step.completion_reason !== 'success') return '✗';
+  return GLYPH[step.status] ?? '○';
+}
+
+/** The `steps N: 3 done · 1 running` line, counted off whatever Cloud called each status. */
+function stepCounts(steps: readonly CloudStep[]): string {
+  const counts = new Map<string, number>();
+  for (const step of steps) counts.set(step.status, (counts.get(step.status) ?? 0) + 1);
+  const parts = [...counts].map(([status, count]) => `${count} ${status}`);
+  return `steps ${steps.length}${parts.length === 0 ? '' : `: ${parts.join(' · ')}`}`;
+}
+
+/**
+ * How long an in-flight step has been in flight.
+ *
+ * Only from a start timestamp the row actually carries, and only while the row
+ * says the step has not ended: a finished step whose `endTime` is missing keeps
+ * whatever duration Cloud reported rather than being advanced to now, which
+ * would make a step that ended an hour ago look like it is still burning. A
+ * start in the future is clock skew between Cloud and here, not negative time,
+ * so it clamps to zero.
+ */
+function liveElapsed(step: CloudStep, now: number): number | null {
+  if (!ACTIVE_STEP_STATUSES.includes(step.status) || step.ended_at !== null || step.started_at === null) return null;
+  const started = Date.parse(step.started_at);
+  return Number.isFinite(started) ? Math.max(0, now - started) : null;
+}
+
+/**
+ * The attempt cell.
+ *
+ * A finished step counts the attempt records Cloud kept. An in-flight step
+ * wants the number of the attempt *now running*, and `attempts` cannot supply
+ * it: those entries are completion records, so during a second attempt the
+ * array still holds one entry and would print `attempt 1`. `retryCount` plus
+ * one is that number — but only where the row also shows the step was
+ * dispatched, because a row with no start timestamp has not attempted
+ * anything and `attempt 1` would be a claim about work that has not begun.
+ * Where neither establishes it, the cell is omitted: the local view prints no
+ * attempt at zero either. No `/max` denominator — Cloud's step rows carry no
+ * maximum, and printing one would invent a budget.
+ */
+function attemptCell(step: CloudStep): string | null {
+  if (!ACTIVE_STEP_STATUSES.includes(step.status)) {
+    const attempts = step.attempts.length;
+    return attempts > 0 ? `${attempts} attempt${attempts === 1 ? '' : 's'}` : null;
+  }
+  if (step.retry_count === null || step.started_at === null) return null;
+  return `attempt ${Math.max(0, Math.trunc(step.retry_count)) + 1}`;
+}
+
+function renderStep(step: CloudStep, runId: string, idWidth: number, now: number): string[] {
+  const cells = [
+    safe(step.step_name).slice(0, 24).padEnd(idWidth),
+    step.step_type.padEnd(13),
+    step.status.padEnd(11),
+  ];
+  const attempt = attemptCell(step);
+  if (attempt !== null) cells.push(attempt);
+  // The derived time first, not second: a row that is still in flight can
+  // carry a `wallclockMs` from the attempt that already ended, and preferring
+  // it would freeze the cell at that attempt's duration while the step runs
+  // on. `liveElapsed` is null for every row that is not demonstrably in
+  // flight, so a finished row still prints the duration Cloud reported.
+  const elapsed = liveElapsed(step, now) ?? step.duration_ms;
+  if (elapsed !== null) cells.push(formatDuration(elapsed));
+  if (step.completion_reason !== null) cells.push(safe(step.completion_reason));
+  if (step.gate !== null) cells.push(`gate: ${safe(step.gate.gate)} ${safe(step.gate.verdict)}`);
+  const lines = [`  ${glyph(step)} ${cells.join('  ')}`.trimEnd()];
+
+  if (step.gate !== null && step.gate.verdict !== 'pass' && step.gate.detail.length > 0) {
+    lines.push(`        gate: ${safe(step.gate.gate)} ${step.gate.verdict.toUpperCase()} — ${JSON.stringify(safe(step.gate.detail))}`);
+  }
+  const transcript = step.transcript;
+  if (transcript !== null) {
+    const facts = [
+      transcript.model === null ? null : safe(transcript.model),
+      transcript.num_turns === null ? null : `${transcript.num_turns} turn${transcript.num_turns === 1 ? '' : 's'}`,
+      transcript.total_calls === null ? null : `${transcript.total_calls} tool call${transcript.total_calls === 1 ? '' : 's'}`,
+      transcript.total_cost_usd === null ? null : dollars(transcript.total_cost_usd),
+    ].filter((fact): fact is string => fact !== null);
+    lines.push(`      transcript (attempt ${transcript.attempt ?? step.attempts.length})${facts.length === 0 ? '' : `: ${facts.join(' · ')}`}`);
+    if (transcript.frames_total !== null || transcript.bytes_total !== null) {
+      const frames = transcript.frames_total === null ? ''
+        : `${thousands(transcript.frames_kept ?? transcript.frames_total)} of ${thousands(transcript.frames_total)} frames`;
+      const bytes = transcript.bytes_total === null ? '' : `${thousands(transcript.bytes_total)} bytes`;
+      const cut = transcript.truncated ? ', truncated' : '';
+      lines.push(`        ${[frames, bytes].filter((part) => part.length > 0).join(', ')}${cut}`);
+    }
+    if (transcript.tokens_in !== null || transcript.tokens_out !== null) {
+      const cache = [
+        transcript.cache_read === null ? null : `${thousands(transcript.cache_read)} cache read`,
+        transcript.cache_creation === null ? null : `${thousands(transcript.cache_creation)} cache write`,
+      ].filter((part): part is string => part !== null);
+      lines.push(`        ${thousands(transcript.tokens_in ?? 0)} in / ${thousands(transcript.tokens_out ?? 0)} out`
+        + `${cache.length === 0 ? '' : ` · ${cache.join(' · ')}`}`);
+    }
+    if (transcript.tools.length > 0) {
+      lines.push(`        tools: ${transcript.tools.map((tool) =>
+        `${safe(tool.name)} ×${tool.calls ?? 0}${tool.errors ? ` (${tool.errors} error${tool.errors === 1 ? '' : 's'})` : ''}`).join(', ')}`);
+    }
+    for (const call of transcript.last_calls) {
+      const excerpt = call.input_excerpt === null ? '' : ` ${safe(call.input_excerpt).slice(0, 120)}`;
+      lines.push(`        call ${call.seq ?? '?'} ${safe(call.name)}${excerpt} → ${thousands(call.result_bytes ?? 0)} bytes`);
+    }
+    lines.push(`        artifacts: ${transcript.artifacts.length === 0
+      ? 'none' : transcript.artifacts.slice(0, 10).map(safe).join(', ')}`);
+  }
+  if (step.sandbox_id.length > 0) lines.push(`      logs: flows logs ${runId} --step ${safe(step.sandbox_id)}`);
+  return lines;
+}
+
+export function renderCloudStatus(run: CloudRunDetail, steps: readonly CloudStep[], now: number): string[] {
+  let tokensIn = 0;
+  let tokensOut = 0;
+  let cost = 0;
+  for (const step of steps) {
+    tokensIn += step.tokens_in ?? 0;
+    tokensOut += step.tokens_out ?? 0;
+    cost += step.cost_usd ?? 0;
+  }
+  // Summed from the step rows, because the run record carries no total. Cloud
+  // stores `costUsd` as a float, so this is a float sum — not the exact decimal
+  // addition the local journal fold does (run-state.ts `addDollars`). Shown to
+  // six places and labelled `spend`, the same word the local view uses.
+  const spend = `${thousands(tokensIn)} in / ${thousands(tokensOut)} out / ${dollars(cost)}`;
+  const finished = run.completion_reason === null ? '' : `   finished ${safe(run.completion_reason)}`;
+  const lines = [
+    `RUN ${run.run_id}   ${safe(run.name)}   ${run.status}   started ${ago(run.created_at, now)}${finished}   spend ${spend}`,
+    stepCounts(steps),
+  ];
+  // `steps 0` alone reads as "this run has no steps", which is a claim about
+  // the run. For a run that is still going it is a fact about the snapshot:
+  // Cloud served no rows, this time.
+  if (steps.length === 0 && isCloudRunActive(run.status)) lines.push('No step snapshot available yet.');
+  if (run.authority !== null) {
+    const facts = [
+      run.authority.surface_version === null ? null : `surface ${run.authority.surface_version}`,
+      run.authority.artifact_sha256 === null ? null : `artifact ${run.authority.artifact_sha256.slice(0, 12)}`,
+      run.authority.source_commit === null ? null : `commit ${run.authority.source_commit.slice(0, 12)}`,
+    ].filter((fact): fact is string => fact !== null);
+    if (facts.length > 0) lines.push(`authority ${facts.join(' · ')}`);
+  }
+  if (run.pull_request_url !== null) lines.push(`pr ${run.pull_request_url}`);
+  if (run.error !== null) lines.push('error', ...errorLines(run.error, '  '));
+  lines.push('');
+  const idWidth = Math.max(4, ...steps.map((step) => Math.min(24, step.step_name.length)));
+  for (const step of steps) lines.push(...renderStep(step, run.run_id, idWidth, now));
+  return lines;
+}
+
+/** Every free-text field of the run record, through the status page's redactor. */
+export function scrubRun(run: CloudRunDetail, env: NodeJS.ProcessEnv): CloudRunDetail {
+  return {
+    ...run,
+    name: redact(run.name, env),
+    error: run.error === null ? null : redact(run.error, env),
+  };
+}
+
+/** The same, for the step rows — including every string inside the digest. */
+export function scrubSteps(steps: readonly CloudStep[], env: NodeJS.ProcessEnv): CloudStep[] {
+  return steps.map((step) => ({
+    ...step,
+    output_summary: step.output_summary === null ? null : redact(step.output_summary, env),
+    gate: step.gate === null ? null : { ...step.gate, detail: redact(step.gate.detail, env) },
+    transcript: step.transcript === null ? null : {
+      ...step.transcript,
+      model: step.transcript.model === null ? null : redact(step.transcript.model, env),
+      last_calls: step.transcript.last_calls.map((call) => ({
+        ...call,
+        input_excerpt: call.input_excerpt === null ? null : redact(call.input_excerpt, env),
+      })),
+      artifacts: step.transcript.artifacts.map((path) => redact(path, env)),
+    },
+  }));
+}

package/src/cli/direct-run.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from '../worker-lease.js';
 import { McpStepError } from '../authored-mcp.js';
 import { randomUUID } from 'node:crypto';
 import { authoredLocalAgentStream } from '../authored-admission.js';
@@ -15,6 +16,7 @@ import { DirectInputError, parseDirectInput } from '../direct-input.js';
 import { JournalClient } from '../journal-client.js';
 import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
+import { authoredInput, authoredWorkerRemedy, localAgentRemedy } from './local-agent-remedy.js';
 import {
   authoredCompletion,
   authoredHumanParked,
@@ -82,7 +84,7 @@ export async function runDirectFlow(
       await llmClient.connect();
       await llmClient.hello('flows-local-llm');
       localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity);
-      localLlm.on('error', error => { llmFailure = error; client.close(); });
+      localLlm.on('error', onWorkerFailure('local-llm', error => { llmFailure = error; client.close(); }));
       await localLlm.attach();
     }
     const result = await executeDurableAuthoredFlow(
@@ -94,6 +96,7 @@ export async function runDirectFlow(
         ...(localAgent === undefined ? {} : { workerCapacity }),
         lifecycle: {
           onProgress: options.onProgress,
+          ...(options.onRunStarted !== undefined ? { onRunStarted: options.onRunStarted } : {}),
           ...(options.signal !== undefined ? { signal: options.signal } : {}),
           ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
         },
@@ -163,12 +166,26 @@ export async function runDirectFlow(
           ...base,
           ok: false,
           runId: error.runId,
+          rootRunId: error.rootRunId,
           socketPath,
           status: 'parked',
+          parkCause: error.parkCause,
           diagnostics: [...base.diagnostics, {
             severity: 'parked',
             kind: 'run_parked',
-            message: error.message,
+            // The remedy is rendered here rather than by the child's own
+            // `classifyOutcome`, which is deliberately silent for authored
+            // paths: this is the only frame that knows both the flow path and
+            // the `--input` argument a new run has to repeat, and it knows
+            // whether a worker was already attached.
+            //
+            // `inputArgument` is the word this process was invoked with, so a
+            // run started from a file names that file rather than the megabyte
+            // inside it — the thing the journal can no longer tell a resume.
+            message: error.message + localAgentRemedy(authoredWorkerRemedy(
+              error.parkCause, options.localAgent === true,
+              { path, input: authoredInput(inputArgument), dataDir },
+            )),
           }],
         },
       };

package/src/cli/hn-monitor.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from '../worker-lease.js';
 /**
  * `flows hn-monitor start` — CLI-inlined proactive workload for gate 2.
  *
@@ -169,7 +170,7 @@ async function defaultAttachWorker(
   // synchronously, bypasses the drain-aware close(), and crashes the
   // process. Subscribe BEFORE attach so an error during attach is not
   // lost.
-  worker.on('error', onWorkerError);
+  worker.on('error', onWorkerFailure('hn-monitor', onWorkerError));
   await worker.attach();
   return worker;
 }

package/src/cli/local-agent-remedy.ts

@@ -0,0 +1,160 @@
+import { resumeCommand } from '../authored-human.js';
+import type { ParkCause } from '../failure-kinds.js';
+import { shellQuote, shellWord } from '../shell-word.js';
+
+/**
+ * What to tell someone whose run stopped for want of an agent worker.
+ *
+ * A closed union rather than a bag of optional fields: the remedy for a spec
+ * run is a *new* run, for a spec resume it is *this* run, and for an authored
+ * `.flow.ts` it is a new run that must carry the same `--input` — three
+ * different sentences, and no combination of them is meaningful. `attached`
+ * is the case the message used to get wrong by omission: a worker WAS offered
+ * and none of them was eligible, so naming the flag again is not the fix.
+ */
+export type LocalAgentRemedy =
+  /** Nothing to say: not a worker park, or the caller renders it elsewhere. */
+  | { kind: 'none' }
+  | { kind: 'attached' }
+  | { kind: 'spec-run'; path: string; dataDir?: string }
+  | { kind: 'spec-resume'; runId: string; dataDir?: string }
+  | { kind: 'authored-run'; path: string; input: AuthoredInput; dataDir?: string };
+
+/**
+ * The `--input` argument a new run of an authored flow would have to repeat.
+ *
+ * Three outcomes, not an optional string, because each is a different sentence
+ * and only one of them ends in a command. None of them is `{}`: fabricating an
+ * input would hand over a command that runs a different flow invocation than
+ * the one that parked.
+ */
+export type AuthoredInput =
+  /** The argument this run was started with, rendered back verbatim. */
+  | { kind: 'inline'; argument: string }
+  /** The journal recorded no input argument to repeat. */
+  | { kind: 'absent' }
+  /** Recorded, but too many bytes to hand a shell as one word. */
+  | { kind: 'oversized'; bytes: number };
+
+/**
+ * The largest `--input` value worth printing inline, in bytes.
+ *
+ * Linux caps a single `execve` argument at `MAX_ARG_STRLEN` — 32 pages,
+ * 131072 bytes including the terminating NUL — independently of the much
+ * larger `ARG_MAX` total. `MAX_DIRECT_INPUT_BYTES` admits a full mebibyte, so
+ * a run started from a perfectly ordinary input file can have recorded more
+ * input than any shell can pass back. Printing it anyway yields a command that
+ * dies with `Argument list too long` before the CLI is even reached, which is
+ * no better than the park it was meant to answer.
+ */
+const MAX_INLINE_INPUT_BYTES = 131_071;
+
+/** How a recorded input argument should be rendered, given its size. */
+export function authoredInput(argument: string | undefined): AuthoredInput {
+  if (argument === undefined) return { kind: 'absent' };
+  const bytes = Buffer.byteLength(argument, 'utf8');
+  return bytes > MAX_INLINE_INPUT_BYTES ? { kind: 'oversized', bytes } : { kind: 'inline', argument };
+}
+
+/**
+ * The declared-surface caveat, stated as the condition it is.
+ *
+ * A step that declares a workspace or a stream needs a worker holding those
+ * pins, and the local agent worker holds only its own stream. That is worth
+ * saying next to the command — but it is a caveat on the remedy, not a
+ * diagnosis of this park, and it is phrased so it cannot be read as one.
+ */
+const PINS = 'Declared workspace or stream surfaces require a worker that holds their pins.';
+
+/**
+ * The remedy clause appended to a worker-park diagnostic, with a leading
+ * space, or `''` when there is nothing to add.
+ */
+export function localAgentRemedy(remedy: LocalAgentRemedy): string {
+  switch (remedy.kind) {
+    case 'none':
+      return '';
+    case 'attached':
+      // Never "pass --local-agent": it was passed. The honest report is that
+      // a worker was offered and the daemon matched none of them to this step.
+      return ' A local agent worker is already attached to this run, so passing --local-agent again'
+        + ' changes nothing: no attached worker was eligible for this step.'
+        + ` ${PINS} The local agent worker holds only its own stream.`;
+    case 'spec-run':
+      return ` To start a new run with a local agent worker: ${
+        newRunCommand(remedy.path, undefined, remedy.dataDir)}. ${PINS}`;
+    case 'spec-resume':
+      // This run is resumable, so the remedy is this run — not a new one.
+      return ` To continue this run with a local agent worker: ${
+        resumeCommand(remedy.runId, remedy.dataDir, true)}. ${PINS}`;
+    case 'authored-run':
+      return authoredRunRemedy(remedy);
+  }
+}
+
+/**
+ * Either a runnable new run, or the requirement stated in prose.
+ *
+ * Prose, not a command, whenever the `--input` cannot be printed as something
+ * a shell would deliver intact: a `.flow.ts` invocation without its `--input`
+ * is refused (`input_missing`), and a placeholder or a truncation in its place
+ * is worse than a sentence, because it looks runnable.
+ */
+function authoredRunRemedy(remedy: Extract<LocalAgentRemedy, { kind: 'authored-run' }>): string {
+  if (remedy.input.kind === 'inline') {
+    return ` To start a new run with a local agent worker: ${
+      newRunCommand(remedy.path, remedy.input.argument, remedy.dataDir)}. ${PINS}`;
+  }
+  const requirement = ' A local agent worker is admitted at run start, so this run needs a new one.'
+    + ` Starting one needs --local-agent, the flow path ${shellQuote(remedy.path)}, and the same`
+    + ' --input this flow takes; ';
+  return requirement + (remedy.input.kind === 'absent'
+    ? 'the journal recorded no input argument to repeat here.'
+    // Naming the size says which input, and says why this clause is prose:
+    // the recorded value is larger than one `execve` argument may be, so a
+    // printed `--input '<json>'` would fail before the CLI ran at all.
+    : `the journal recorded ${remedy.input.bytes} bytes of input, more than a shell`
+      + ' can carry in one argument, so pass the input file this run was started from.')
+    + ` ${PINS}`;
+}
+
+/**
+ * Which remedy an authored `.flow.ts` park gets, decided once for both authored
+ * boundaries (`cli/direct-run.ts` on a fresh run, `resumeFlow` on a resume).
+ *
+ * The cause is trusted, not guessed: anything other than `worker_unavailable` —
+ * including an absent cause — yields `none`, so a `needs_human` recovery wait is
+ * never answered with "attach a worker", and an unclassified park says nothing
+ * at all rather than something plausible.
+ *
+ * `path` is optional because the caller may only have the journal to go on. A
+ * park with no known flow path yields `none` for the same reason an unknown
+ * input yields prose: the point of this clause is a command someone can run.
+ */
+export function authoredWorkerRemedy(
+  parkCause: ParkCause | undefined,
+  attached: boolean,
+  run: { path?: string; input: AuthoredInput; dataDir?: string },
+): LocalAgentRemedy {
+  if (parkCause !== 'worker_unavailable') return { kind: 'none' };
+  if (attached) return { kind: 'attached' };
+  if (run.path === undefined) return { kind: 'none' };
+  return { kind: 'authored-run', path: run.path, input: run.input, dataDir: run.dataDir };
+}
+
+/**
+ * `flows run --local-agent <path> [--input <input>] [--data-dir <dir>]`.
+ *
+ * The flag/path prefix is byte-for-byte what the spec-run message has always
+ * emitted, so the one thing people already grep for still matches. `--input`
+ * and `--data-dir` follow the path because the parser is order-insensitive
+ * (cli.ts `parseRunArgs`), and keeping the prefix intact matters more than
+ * mirroring the usage line's flag order.
+ */
+function newRunCommand(path: string, input: string | undefined, dataDir: string | undefined): string {
+  return `flows run --local-agent ${shellQuote(path)}`
+    + (input === undefined ? '' : ` --input ${shellQuote(input)}`)
+    // `shellWord` here, matching `resumeCommand`/`answerCommand`: a data dir is
+    // this machine's path, and the two renderings must not disagree.
+    + (dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`);
+}

package/src/cli/observer-session.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 { createJournalProjector } from '../journal-projection.js';
+import type { JournalEvent } from '../journal-reader.js';
+import { mintObserverUrl, resolveObserverLinkEnv, type MintObserverOptions } from '../observer-link.js';
+import type { ProgressEvent } from '../progress.js';
+import {
+  createRunProjection, runChannelName, type DeclaredStep, type ProjectionFetch, type RunProjection,
+} from '../run-projection.js';
+import type { RunReport } from './run.js';
+
+type MintOutcome = { observerUrl?: string; warning?: string };
+
+/** Bounded so an unreachable Relaycast cannot hold the CLI open. */
+const DRAIN_GRACE_MS = 5_000;
+
+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 function createObserverSession(
+  command: 'run' | 'resume',
+  io: CliIo,
+  env: NodeJS.ProcessEnv = process.env,
+  deps: ObserverSessionDeps = {},
+): ObserverSession | undefined {
+  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: RunProjection | undefined;
+  let minted: Promise<MintOutcome> | undefined;
+  let rootRunId: string | undefined;
+
+  const mintFor = (runId: string): Promise<MintOutcome> => minted ??= mint({
+    workspaceKey,
+    channel: runChannelName(runId),
+    ...(link.baseUrl === undefined ? {} : { baseUrl: link.baseUrl }),
+    ...(link.dashboardUrl === undefined ? {} : { dashboardUrl: link.dashboardUrl }),
+  }).catch((error: unknown) => ({ warning: error instanceof Error ? error.message : 'unknown mint error' }));
+
+  const open = (run: { runId: string; flow: string; steps?: DeclaredStep[]; resumed?: boolean }): RunProjection => {
+    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));
+    },
+  };
+}