@relayflows/sdk 2.0.21 → 2.0.22

package/src/cli/status.ts

@@ -0,0 +1,329 @@
+// `flows status`: what an agent can see about its own run, from disk.
+//
+// Read-only and offline. Opens exactly one file — the run's journal, through
+// the same copy-then-verify `walkJournal` that `flows replay` uses — and never
+// the registry, `connection.json`, the daemon socket or the network. There is
+// no credential to hold because nothing here is authenticated: the journal is
+// on the same filesystem as the process asking. Everything a hosted run knows
+// about itself is in that file; whatever is not (its Cloud run id, its
+// sandbox, its listener) is Cloud's to answer, and this verb does not guess.
+
+import type { CliIo } from '../cli.js';
+import { canonicalize } from '../canonical.js';
+import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
+import { JournalReadError, walkJournal, type JournalEvent } from '../journal-client.js';
+import { redact } from '../redact.js';
+import { foldRunState, RunStateError, type RunView, type StepView } from '../run-state.js';
+import { DATA_DIR_ENV, RUN_ID_ENV, STEP_ID_ENV } from '../step-env.js';
+
+export interface StatusArgs {
+  command: 'status';
+  json: boolean;
+  dataDir?: string;
+  tail?: number;
+  runId?: string;
+}
+
+export const DEFAULT_TAIL_LINES = 20;
+/** A gate's `detail` may be 2,000 chars (engine/remote.rs); the view shows the head. */
+const DETAIL_LIMIT = 1024;
+const BUSY_RETRIES = 5;
+const BUSY_RETRY_DELAY_MS = 50;
+
+/** One transcript tail on disk, already redacted, as `--tail` renders it. */
+export interface TranscriptTail {
+  attempt: number;
+  bytes: number;
+  lines: string[];
+}
+
+export type StepTails = { stdout: TranscriptTail | null; stderr: TranscriptTail | null } | null;
+
+/** How the verb finds transcript tails; `null` until the tail writer ships. */
+export interface TailSource {
+  read(dataDir: string, runId: string, step: StepView, lines: number): Promise<StepTails>;
+}
+
+export interface StatusOptions {
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  tails?: TailSource;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined {
+  let json = false;
+  let dataDir: string | undefined;
+  let tail: number | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!;
+    if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+    } else if (argument === '--data-dir' || argument === '--tail') {
+      const value = args[++index];
+      if (value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
+      if (argument === '--data-dir') {
+        if (dataDir !== undefined) return undefined;
+        dataDir = value;
+      } else {
+        if (tail !== undefined || !/^\d{1,4}$/.test(value)) return undefined;
+        tail = Number(value);
+      }
+    } else if (argument.startsWith('-')) {
+      return undefined;
+    } else {
+      positionals.push(argument);
+    }
+  }
+  if (positionals.length > 1) return undefined;
+  return {
+    command: 'status', json,
+    ...(dataDir === undefined ? {} : { dataDir }),
+    ...(tail === undefined ? {} : { tail }),
+    ...(positionals[0] === undefined ? {} : { runId: positionals[0] }),
+  };
+}
+
+interface Snapshot {
+  events: JournalEvent[];
+  partial: string[];
+  failure?: JournalReadError;
+}
+
+/**
+ * Take one consistent snapshot of the journal. `journal_busy` means a writer
+ * was mid-flight, so wait briefly and try again; any other mid-walk failure
+ * keeps the events read so far and reports the section as partial.
+ */
+async function snapshot(runId: string, dataDir: string, sleep: (ms: number) => Promise<void>): Promise<Snapshot> {
+  for (let attempt = 1; ; attempt += 1) {
+    const events: JournalEvent[] = [];
+    try {
+      for await (const event of walkJournal(runId, dataDir)) events.push(event);
+      return { events, partial: [] };
+    } catch (error) {
+      const failure = error instanceof JournalReadError ? error
+        : new JournalReadError('journal_read_failed', error instanceof Error ? error.message : String(error));
+      if (failure.code === 'journal_busy' && attempt < BUSY_RETRIES) { await sleep(BUSY_RETRY_DELAY_MS); continue; }
+      return { events, partial: [failure.code], failure };
+    }
+  }
+}
+
+export async function runStatus(args: StatusArgs, io: CliIo, options: StatusOptions = {}): Promise<0 | 1 | 2> {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  // Discovery: an explicit run id wins; otherwise the step's own identity from
+  // the environment the worker set. A shared data dir holds other people's
+  // runs, so there is no "list everything" mode to fall back to.
+  const runId = args.runId ?? env[RUN_ID_ENV];
+  if (runId === undefined || runId.length === 0) {
+    io.stderr(`REFUSED [run_unknown] pass <run-id> or run inside a step (${RUN_ID_ENV} unset)`);
+    return 2;
+  }
+  const dataDir = args.dataDir ?? env[DATA_DIR_ENV] ?? DEFAULT_DATA_DIR;
+  const thisStep = args.runId === undefined ? env[STEP_ID_ENV] ?? null : null;
+
+  const taken = await snapshot(runId, dataDir, sleep);
+  if (taken.events.length === 0) {
+    const failure = taken.failure ?? new JournalReadError('journal_read_failed', 'Journal holds no entries.');
+    io.stderr(`REFUSED [${failure.code}] ${failure.message}`);
+    return 2;
+  }
+  let view: RunView;
+  try {
+    view = foldRunState(taken.events, now());
+  } catch (error) {
+    const message = error instanceof RunStateError ? error.message : error instanceof Error ? error.message : String(error);
+    io.stderr(`REFUSED [run_state_invalid] ${message}`);
+    return 2;
+  }
+
+  // Tails are read for JSON (bounded, and the schema carries them) and for
+  // text only on request; a plain `flows status` opens the journal and nothing else.
+  const wantTails = args.json || args.tail !== undefined;
+  const tails = new Map<string, StepTails>();
+  if (options.tails !== undefined && wantTails) {
+    for (const step of view.steps) {
+      try {
+        tails.set(step.id, await options.tails.read(dataDir, runId, step, args.tail ?? DEFAULT_TAIL_LINES));
+      } catch {
+        if (!taken.partial.includes('transcript_tail_unreadable')) taken.partial.push('transcript_tail_unreadable');
+        tails.set(step.id, null);
+      }
+    }
+  }
+
+  const presented = present(view, thisStep, tails, env);
+  if (args.json) {
+    io.stdout(canonicalize({ v: 1, ...presented, partial: taken.partial }));
+  } else {
+    for (const line of renderText(presented, taken.partial, args.tail !== undefined)) io.stdout(line);
+  }
+  if (taken.failure !== undefined) io.stderr(`FAILED [${taken.failure.code}] ${taken.failure.message}`);
+  return taken.partial.length === 0 ? 0 : 1;
+}
+
+type PresentedStep = StepView & { tails: StepTails };
+type Presented = Omit<RunView, 'steps'> & { this_step: string | null; steps: PresentedStep[] };
+
+/** Apply the redaction and size bounds the on-disk model does not have. */
+function present(view: RunView, thisStep: string | null, tails: Map<string, StepTails>, env: NodeJS.ProcessEnv): Presented {
+  return {
+    ...view,
+    this_step: thisStep,
+    steps: view.steps.map((step) => ({
+      ...step,
+      // An agent names the files it writes, and it inherits this process's
+      // environment, so a path is free text like any other here.
+      artifacts: { ...step.artifacts, paths: step.artifacts.paths.map((path) => redact(path, env)) },
+      last_attempt: step.last_attempt === null ? null : {
+        ...step.last_attempt,
+        verification: step.last_attempt.verification === null ? null : {
+          ...step.last_attempt.verification,
+          detail: redact(step.last_attempt.verification.detail, env).slice(0, DETAIL_LIMIT),
+        },
+        // The digest's strings were redacted when it was built (flows#491), by
+        // a redactor with a different rule set to this one. Redacting again on
+        // the way out costs nothing and closes the difference — this module is
+        // the one place that decides what reaches an agent-facing page.
+        transcript: step.last_attempt.transcript === null ? null : {
+          ...step.last_attempt.transcript,
+          path: step.last_attempt.transcript.path === null
+            ? null : redact(step.last_attempt.transcript.path, env),
+          model: step.last_attempt.transcript.model === null
+            ? null : redact(step.last_attempt.transcript.model, env),
+          failure: step.last_attempt.transcript.failure === null ? null : {
+            ...step.last_attempt.transcript.failure,
+            excerpt: redact(step.last_attempt.transcript.failure.excerpt, env).slice(0, DETAIL_LIMIT),
+          },
+        },
+      },
+      tails: tails.get(step.id) ?? null,
+    })),
+  };
+}
+
+const GLYPH: Record<StepView['state'], string> = {
+  pending: '○', runnable: '○', running: '↻', backoff: '↻', waiting: '⏸', needs_human: '⏸', done: '✓',
+};
+
+/** Agent-authored names cannot inject terminal control sequences (progress.ts). */
+function safe(name: string): string {
+  return name.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
+}
+
+export function formatDuration(ms: number): string {
+  const seconds = Math.max(0, ms) / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${String(Math.floor(seconds % 60)).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+function thousands(value: number): string {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+function instant(ms: number): string {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function renderText(view: Presented, partial: string[], wantTails: boolean): string[] {
+  const lines: string[] = [];
+  const spend = `${thousands(view.spend.tokens_in)} in / ${thousands(view.spend.tokens_out)} out / $${view.spend.dollars}`
+    + (view.spend.dollars_unmetered ? ' (unmetered)' : '');
+  const finished = view.completion_reason === null ? '' : `   finished ${view.completion_reason}`;
+  lines.push(`RUN ${view.run_id}   ${safe(view.name)}   ${view.status}   started ${formatDuration(view.now_ms - view.spawned_at_ms)} ago${finished}   spend ${spend}`);
+  const counts = (['done', 'running', 'pending', 'backoff', 'waiting', 'needs_human'] as const)
+    .filter((key) => view.counts[key] > 0).map((key) => `${view.counts[key]} ${key}`);
+  // The denominator is always printed, even for zero steps, so a reader can
+  // tell "nothing to show" from "nothing was read".
+  lines.push(`steps ${view.counts.total}${counts.length === 0 ? '' : `: ${counts.join(' · ')}`}`);
+  if (partial.length > 0) lines.push(`partial: ${partial.join(', ')}`);
+  lines.push('');
+  const idWidth = Math.max(4, ...view.steps.map((step) => Math.min(24, step.id.length)));
+  for (const step of view.steps) lines.push(...renderStep(step, view, idWidth, wantTails));
+  return lines;
+}
+
+function renderStep(step: PresentedStep, view: Presented, idWidth: number, wantTails: boolean): string[] {
+  // `completion_reason`, not `last_attempt`: an epoch summary carries the
+  // reason without an attempt record, and reading the latter marked every
+  // compacted success as a failure.
+  const failed = step.state === 'done' && step.completion_reason !== 'success';
+  const glyph = failed ? '✗' : GLYPH[step.state];
+  const cells = [safe(step.id).slice(0, 24).padEnd(idWidth), step.type.padEnd(13), step.state.padEnd(11)];
+  const iterations = step.max_iterations === null ? '' : `/${step.max_iterations}`;
+  // `> 0` matters for a step carried done by an epoch summary: the summary
+  // has no attempt count, so the fold leaves it 0 and printing "0 attempts"
+  // would state a fact the journal no longer holds. Blank, like every other
+  // state does at 0.
+  if (step.state === 'done' && step.attempt > 0) cells.push(`${step.attempt} attempt${step.attempt === 1 ? '' : 's'}`);
+  else if (step.attempt > 0) cells.push(`attempt ${step.attempt}${iterations}`);
+  if (step.elapsed_ms !== null) cells.push(formatDuration(step.elapsed_ms));
+  if (step.state === 'running' && step.lease !== null) {
+    cells.push(step.lease.overdue_ms > 0
+      ? `LEASE OVERDUE by ${formatDuration(step.lease.overdue_ms)}`
+      : `lease ok (expires in ${formatDuration(step.lease.deadline_ms - view.now_ms)})`);
+  }
+  if (step.state === 'backoff' && step.backoff_until_ms !== null) cells.push(`backoff until ${instant(step.backoff_until_ms)}`);
+  if (step.wait !== null) cells.push(`awaiting ${step.wait.kind}: ${safe(step.wait.wait_id)}`);
+  if (step.state === 'done' && step.completion_reason !== null) {
+    // From the step, not the attempt: an epoch-carried step has the reason
+    // and no attempt record, and the reason is the thing worth printing.
+    cells.push(step.completion_reason);
+    const verification = step.last_attempt?.verification ?? null;
+    if (verification !== null) cells.push(`gate: ${verification.gate} ${verification.verdict}`);
+  }
+  if (step.id === view.this_step) cells.push('← this step');
+  const lines = [`  ${glyph} ${cells.join('  ')}`.trimEnd()];
+
+  const last = step.last_attempt;
+  if (last !== null && step.state !== 'done') {
+    lines.push(`      last attempt ${last.attempt}: ${last.completion_reason} → ${last.disposition}`);
+  }
+  if (last?.verification !== null && last?.verification !== undefined && last.verification.verdict !== 'pass') {
+    lines.push(`        gate: ${last.verification.gate} ${last.verification.verdict.toUpperCase()} — ${JSON.stringify(last.verification.detail)}`);
+  }
+  const transcript = last?.transcript ?? null;
+  if (transcript !== null) {
+    // One line of provenance: what ran, how much it cost, and where the full
+    // transcript is. `flows status` never prints the transcript itself — that
+    // is `--tail`'s job for the live attempt, and the file's for a finished one.
+    const facts = [
+      transcript.model === null ? null : safe(transcript.model),
+      transcript.num_turns === null ? null : `${transcript.num_turns} turn${transcript.num_turns === 1 ? '' : 's'}`,
+      transcript.tool_calls === null ? null : `${transcript.tool_calls} tool call${transcript.tool_calls === 1 ? '' : 's'}`,
+      transcript.total_cost_usd === null ? null : `$${transcript.total_cost_usd}`,
+    ].filter((fact): fact is string => fact !== null);
+    const size = transcript.bytes === null ? '' : ` (${transcript.bytes} bytes${transcript.truncated ? ', truncated' : ''})`;
+    lines.push(`      transcript (attempt ${last!.attempt})${facts.length === 0 ? '' : `: ${facts.join(' · ')}`}`);
+    if (transcript.path !== null) lines.push(`        ${safe(transcript.path)}${size}`);
+    if (transcript.failure !== null && transcript.failure.excerpt.length > 0) {
+      lines.push(`        failed at ${safe(transcript.failure.kind)}: ${JSON.stringify(transcript.failure.excerpt)}`);
+    }
+  }
+  if (step.type === 'agent' && last !== null) {
+    const shown = step.artifacts.paths.slice(0, 10).map(safe).join(', ');
+    const more = step.artifacts.paths.length > 10 ? ` +${step.artifacts.paths.length - 10} more` : '';
+    lines.push(`      artifacts (attempt ${last.attempt}): ${step.artifacts.journaled
+      ? step.artifacts.paths.length === 0 ? 'none' : `${shown}${more}`
+      : 'none journaled (output was a JSON object)'}`);
+  }
+  if (wantTails && step.type === 'agent' && step.attempt > 0) {
+    for (const stream of ['stdout', 'stderr'] as const) {
+      const tail = step.tails?.[stream] ?? null;
+      if (tail === null) {
+        lines.push(`      ${stream} tail: no transcript on disk for attempt ${step.attempt}`);
+        continue;
+      }
+      lines.push(`      ${stream} tail (attempt ${tail.attempt}, last ${tail.lines.length} of ${tail.bytes} bytes):`);
+      for (const line of tail.lines) lines.push(`        ${safe(line)}`);
+    }
+  }
+  return lines;
+}

package/src/cli/step-failure.ts

@@ -108,28 +108,53 @@ export function inspectionHint(
  * it does not. A truncated render (the daemon caps at 2,000 chars and appends
  * a truncation note) will not parse; that falls through to the raw string,
  * which is still the account of what went wrong.
+ *
+ * An agent or llm completion now also carries `trajectory_tail.transcript`
+ * (agent-transcript.ts) on every attempt. That object is not process-shaped,
+ * so it must not shadow the render that is: the first candidate that carries
+ * an exit code or a tail wins. The digest contributes what only it has — the
+ * failure excerpt the worker picked out of the provider's frames, and the
+ * path of the transcript file.
  */
 function evidence(payload: Record<string, unknown>): Partial<StepFailedDetails> {
   const detail = record(payload['verification'])?.['detail'];
-  const structured = record(payload['output'])
-    ?? record(payload['trajectory_tail'])
-    ?? (typeof detail === 'string' ? parsed(detail) : undefined);
+  const candidates = [
+    record(payload['output']),
+    record(payload['trajectory_tail']),
+    typeof detail === 'string' ? parsed(detail) : undefined,
+  ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
+  const structured = candidates.find(processShaped) ?? candidates[0];
   const exitCode = structured?.['exit_code'];
   const stdout = structured?.['stdout_tail'];
   const stderr = structured?.['stderr_tail'];
-  const structuredShape = typeof exitCode === 'number'
-    || typeof stdout === 'string' || typeof stderr === 'string';
+  const structuredShape = structured !== undefined && processShaped(structured);
+  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
+  const failure = record(transcript?.['failure']);
+  const excerpt = failure?.['excerpt'];
+  const transcriptPath = record(transcript?.['file'])?.['path'];
+  // The excerpt is the worker's own pick of the failure; a `stderr` excerpt
+  // is the same bytes as `stderrTail`, so it is not printed twice.
+  const excerptDetail = typeof excerpt === 'string' && excerpt.length > 0
+    && !(failure?.['kind'] === 'stderr' && typeof stderr === 'string')
+    ? tail(excerpt) : undefined;
   return {
     ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
     ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: tail(stdout) } : {}),
     ...(typeof stderr === 'string' ? { stderrTail: tail(stderr) } : {}),
     // Keep the daemon's account only when it was NOT just a render of the
     // fields above — otherwise the same bytes print twice.
-    ...(typeof detail === 'string' && detail.length > 0 && !structuredShape
-      ? { detail: tail(detail) } : {}),
+    ...(excerptDetail !== undefined ? { detail: excerptDetail }
+      : typeof detail === 'string' && detail.length > 0 && !structuredShape
+        ? { detail: tail(detail) } : {}),
+    ...(typeof transcriptPath === 'string' && transcriptPath.length > 0 ? { transcriptPath } : {}),
   };
 }
 
+function processShaped(value: Record<string, unknown>): boolean {
+  return typeof value['exit_code'] === 'number'
+    || typeof value['stdout_tail'] === 'string' || typeof value['stderr_tail'] === 'string';
+}
+
 function parsed(value: string): Record<string, unknown> | undefined {
   try {
     return record(JSON.parse(value));

package/src/cli-commands.ts

@@ -265,6 +265,17 @@ export const CLI_VERBS = [
     ],
     variants: ['serve-webhook'],
   },
+  {
+    name: 'status',
+    description: 'Show a run’s steps, attempts, leases and last verdicts from its journal; offline, no daemon',
+    args: [{ name: 'run-id', description: 'Run to inspect; defaults to RELAYFLOW_RUN_ID inside a step', required: false }],
+    options: [
+      JSON_OPTION,
+      DATA_DIR_OPTION,
+      { flags: '--tail <n>', description: 'Lines of each agent attempt’s transcript tail to show' },
+    ],
+    variants: ['status'],
+  },
   {
     name: 'sync',
     description: 'Apply a hosted run’s code changes to a local tree (replaces `agent-relay cloud sync`)',

package/src/cli.ts

@@ -24,6 +24,8 @@ import { checkAuthoredTriggers } from './cli/check-triggers.js';
 import { parseWebhookArgs, runServeWebhook } from './cli/serve-webhook.js';
 import { runDirectFlow } from './cli/direct-run.js';
 import { parseReplayArgs, replayJournal, type ReplayArgs } from './cli/replay.js';
+import { parseStatusArgs, runStatus, type StatusArgs } from './cli/status.js';
+import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
@@ -59,6 +61,7 @@ type CliExitCode = 0 | 1 | 2 | 3;
 export type ParsedArgs =
   | { command: 'add'; value: string }
   | ReplayArgs
+  | StatusArgs
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
@@ -104,6 +107,7 @@ const USAGE = [
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
   'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
+  'flows status [--json] [--data-dir <dir>] [--tail <n>] [<run-id>]',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
 ].join('\n');
@@ -195,6 +199,9 @@ export async function runCli(
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
   if (parsed.command === 'replay') return replayJournal(parsed, io);
+  // Daemon-free like `check`: reads one journal file and nothing else, so it
+  // works inside a step of a run whose daemon is gone (kernel/DAEMON-LIFECYCLE.md §4).
+  if (parsed.command === 'status') return runStatus(parsed, io, { tails: transcriptTailSource() });
   if (parsed.command === 'answer') {
     const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
       ...(parsed.note === undefined ? {} : { note: parsed.note }),
@@ -498,6 +505,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === undefined || !CLI_VERB_NAMES.has(command)) return undefined;
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
+  if (command === 'status') return parseStatusArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
   if (command === 'deploy') {
     // The positional decides the form: an authored source deploys a hosted

package/src/failure-kinds.ts

@@ -67,6 +67,13 @@ export const CHECK_FAILURE_KINDS = [
  * `dollars_unmetered: true`, and cannot cross `maxDollars`; token limits still
  * apply. It replaced the `budget_missing_price` refusal (#421), which older
  * `flows check` reports may still show.
+ *
+ * `permissions_unenforced` names an agent step that declares `permissions`.
+ * Gate 1 validates the declaration and the compiled step spec records it, but
+ * nothing reads it to gate a file or network access — enforcement is gate 8
+ * (#442). Warning-only by design: the declaration stays legal and the flow
+ * still runs, but an author who wrote one must not be left believing it
+ * sandboxes the step.
  */
 export const PREFLIGHT_WARNING_KINDS = [
   'unprovable_effects',
@@ -74,6 +81,7 @@ export const PREFLIGHT_WARNING_KINDS = [
   'command_unprovable',
   'vacuous_gate',
   'budget_unmetered',
+  'permissions_unenforced',
 ] as const;
 
 /**
@@ -157,8 +165,14 @@ export interface StepFailedDetails {
   stdoutTail?: string;
   /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
   stderrTail?: string;
-  /** The daemon's own account, when it was not a render of the fields above. */
+  /**
+   * The daemon's own account when it was not a render of the fields above, or
+   * — preferred when present — the failure excerpt from the worker's
+   * transcript digest (`trajectory_tail.transcript.failure`).
+   */
   detail?: string;
+  /** The attempt's redacted `stream-json` transcript on disk, when the worker wrote one. */
+  transcriptPath?: string;
   /** A runnable `flows replay` invocation for this run. */
   hint?: string;
   /** The on-disk journal for this run, when the data dir is known. */

package/src/journal-reader.ts

@@ -28,7 +28,7 @@ export interface JournalEvent {
 }
 
 export type JournalReadFailure =
-  | 'invalid_run_id' | 'run_not_found' | 'step_not_found' | 'journal_read_failed';
+  | 'invalid_run_id' | 'run_not_found' | 'step_not_found' | 'journal_busy' | 'journal_read_failed';
 
 export class JournalReadError extends Error {
   constructor(readonly code: JournalReadFailure, message: string) {
@@ -82,7 +82,9 @@ export async function* walkJournal(
     if (before[1] !== undefined) await copyFile(`${source}-wal`, `${snapshot}-wal`, constants.COPYFILE_EXCL);
     const after = await Promise.all([fingerprint(source), fingerprint(`${source}-wal`)]);
     if (before.some((value, index) => value !== after[index])) {
-      throw new Error('Journal changed while taking the replay snapshot; retry replay.');
+      // Its own code: the journal is fine, a writer was mid-flight. A reader
+      // that can wait (`flows status`) retries on this and nothing else.
+      throw new JournalReadError('journal_busy', `Cannot read journal for run "${runId}": Journal changed while taking the snapshot; retry the command.`);
     }
     const file = await open(snapshot, 'r');
     try {

package/src/llm-worker.ts

@@ -9,6 +9,7 @@ import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
 import { jsonSchemaOutputError } from './json-schema.js';
+import { LLM_ERROR_MAX_BYTES, boundTranscriptDigest, boundedText, redactText } from './agent-transcript.js';
 
 /** Bare value-producing LLM dispatch, without agent workspace/recovery pins. */
 export class LlmWorker extends EventEmitter {
@@ -74,11 +75,21 @@ export class LlmWorker extends EventEmitter {
     }
     // Never submit schema-invalid JSON as a successful completion. The kernel
     // also runs its own gate before making output available to dependents.
+    //
+    // `error` is redacted and bounded: unbounded stderr in the tail made the
+    // kernel refuse the whole completion past 16 KiB. The digest rides beside
+    // it on every completion; an llm step has no data dir, so it has no file.
+    const transcript = completed.transcript === undefined ? undefined
+      : boundTranscriptDigest({ attempt: dispatch.attempt, exit_code: result.exit_code, ...completed.transcript });
+    const trajectoryTail = {
+      ...(reason === 'success' ? {} : { error: boundedText(redactText(detail), LLM_ERROR_MAX_BYTES).text }),
+      ...(transcript === undefined ? {} : { transcript }),
+    };
     await this.client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
       dispatch.idempotency_key, reason, {
         output,
         ...(usage !== undefined ? { usage } : {}),
-        ...(reason === 'success' ? {} : { trajectory_tail: { error: detail } }),
+        ...(Object.keys(trajectoryTail).length === 0 ? {} : { trajectory_tail: trajectoryTail }),
       });
   }
 }

package/src/permissions-preflight.ts

@@ -0,0 +1,53 @@
+import type { CompiledFlowSpec } from './compile.js';
+import type { PermissionsSpec } from './spec.js';
+import type { PreflightWarning } from './preflight.js';
+
+/** Declared fields, reported in this order so two runs read identically. */
+const PERMISSION_FIELDS = ['fileGlobs', 'networkAllowlist', 'accessPreset'] as const;
+
+/**
+ * An agent step's `permissions` block is accepted by gate 1, lowered to
+ * `file_globs` / `network_allowlist` / `access_preset`, carried in the kernel
+ * step spec and journalled with it. Nothing reads it to gate a file or network
+ * access: enforcement is gate 8 (#442). A spec that declares it therefore
+ * looks sandboxed and is not, and until this warning existed nothing said so
+ * at authoring time.
+ *
+ * Every defined declaration warns, including `{}` and empty arrays. SURFACE.md
+ * accepts those without inferring defaults, and an empty block is exactly as
+ * likely to read to an author as "a default sandbox applies". Omitting
+ * `permissions` stays silent — there is no belief to correct.
+ *
+ * Warning-only: `ok` is unaffected, the declaration stays legal, and no value
+ * is echoed back (a glob or host is often the least interesting part of the
+ * declaration and can be long). The message names which fields were declared
+ * so the author can find them, and nothing more.
+ */
+export function permissionsDiagnostics(flow: CompiledFlowSpec): PreflightWarning[] {
+  const warnings: PreflightWarning[] = [];
+  for (const step of flow.steps) {
+    if (step.type !== 'agent' || step.permissions === undefined) continue;
+    warnings.push({
+      severity: 'warning',
+      kind: 'permissions_unenforced',
+      stepId: step.id,
+      message: permissionsMessage(step.id, step.permissions),
+    });
+  }
+  return warnings;
+}
+
+function permissionsMessage(stepId: string, permissions: PermissionsSpec): string {
+  const declared = PERMISSION_FIELDS.filter((field) => permissions[field] !== undefined);
+  const fields = declared.length === 0 ? '' : ` (${declared.join(', ')})`;
+  // `readonly` is the one value whose entire meaning is a guarantee, so it is
+  // the one value worth naming: an author reading "cannot write" needs to be
+  // told, in the same breath, that today nothing stops a write.
+  const preset = permissions.accessPreset === 'readonly'
+    ? " accessPreset: 'readonly' does not prevent writes."
+    : '';
+  return `Step "${stepId}" declares permissions${fields}. `
+    + 'This declaration is validated and recorded with the step spec; it is not '
+    + 'currently enforced (gate 8 / #442). These permissions do not restrict file '
+    + `or network access.${preset}`;
+}

package/src/preflight.ts

@@ -4,6 +4,7 @@ import type { FlowSpec, StepSpec, TriggerSpec, McpServerConfig } from './spec.js
 import { McpError, openMcpSession, type McpDiagnostic } from './mcp-client.js';
 import { BudgetSyntaxError } from './budget.js';
 import { budgetDiagnostics } from './budget-preflight.js';
+import { permissionsDiagnostics } from './permissions-preflight.js';
 import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
@@ -223,6 +224,11 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   const resolutionByStep = new Map<string, CliResolution>();
   const cliProbeResults = new Map<string, CliProbeOutcome>();
 
+  // A pure fact about the compiled snapshot, collected before anything that
+  // can return early. An unresolved CLI, an unknown model or a bad scope all
+  // refuse below without probing, and the author should still be told that the
+  // permissions they declared on the same file are not enforced.
+  diagnostics.push(...permissionsDiagnostics(compiled));
   diagnostics.push(...scopeDiagnostics(compiled, options));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;

package/src/pty-sidechannel.ts

@@ -6,6 +6,13 @@ export interface SidechannelContext {
   dataDir: string;
   runId: string;
   stepId: string;
+  /**
+   * Which attempt this is. Names the per-attempt transcript file
+   * (`agent-transcript.ts`) and the transcript tails (`transcript-tail.ts`),
+   * and is exported into the agent's environment. Optional: without it there
+   * is no attempt to name, so neither file is written.
+   */
+  attempt?: number;
   onReady?: (path: string) => void;
   onDrive: () => void;
 }