@relayflows/sdk 2.0.29 → 2.0.31

package/src/authored-worker-step.ts

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

package/src/bundle-extensions.ts

@@ -5,7 +5,7 @@ import { safePath, sha256 } from './bundle.js';
 import { findPluginProject } from './plugin-loader.js';
 import { parsePluginLock, readPluginLock, reconcileDeclaredExtensions, type PluginLock } from './plugin-lock.js';
 import { PluginError } from './plugin-manifest.js';
-import { pluginStoreDirectory, readStoredPluginFiles, verifyStoredPlugin } from './plugin-store.js';
+import { pluginStoreDirectory, readStoredPluginFiles } from './plugin-store.js';
 
 const EMPTY_LOCK: PluginLock = Object.freeze({ version: 2, plugins: Object.freeze([]) });
 
@@ -50,10 +50,11 @@ export async function verifyBundlePluginLock(bundle: string): Promise<void> {
       throw new Error(`lockfile.json: plugin name ${entry.name} is not a safe path component`);
     }
     const directory = join(bundle, 'plugins', entry.name);
-    await verifyStoredPlugin(directory, entry.digest);
-    let pluginManifest: Buffer;
-    try { pluginManifest = await readFile(join(directory, 'flows-plugin.json')); }
-    catch { throw new Error(`lockfile.json: plugin ${entry.name} is missing plugins/${entry.name}/flows-plugin.json`); }
+    const stored = await readStoredPluginFiles(directory, entry.digest);
+    const pluginManifest = stored.find(file => file.path === 'flows-plugin.json')?.data;
+    if (pluginManifest === undefined) {
+      throw new Error(`lockfile.json: plugin ${entry.name} is missing plugins/${entry.name}/flows-plugin.json`);
+    }
     if (sha256(pluginManifest) !== entry.manifestSha256) {
       throw new Error(`lockfile.json: plugin ${entry.name} flows-plugin.json does not match the lockfile manifest hash`);
     }

package/src/bundle.ts

@@ -2,6 +2,27 @@ import { createHash, createPrivateKey, createPublicKey, randomBytes, sign, verif
 import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import { canonicalize } from './canonical.js';
+import { appendIntrinsicArray } from './intrinsic-array.js';
+
+type Hash = ReturnType<typeof createHash>;
+const CREATE_HASH = createHash;
+const HASH_UPDATE = Function.prototype.call.bind(CREATE_HASH('sha256').update) as (
+  hash: Hash,
+  data: Uint8Array | string,
+) => Hash;
+const HASH_DIGEST = Function.prototype.call.bind(CREATE_HASH('sha256').digest) as (
+  hash: Hash,
+  encoding: 'hex',
+) => string;
+const STRING_INCLUDES = Function.prototype.call.bind(String.prototype.includes) as (
+  value: string, search: string,
+) => boolean;
+const STRING_SPLIT = Function.prototype.call.bind(String.prototype.split) as (
+  value: string, separator: string,
+) => string[];
+const TYPED_ARRAY_LENGTH = Function.prototype.call.bind(
+  Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype) as object, 'length')!.get!,
+) as (value: Uint8Array) => number;
 
 export interface BundleEntry { path: string; sha256: string; bytes: number }
 export interface BundleFile { path: string; data: Uint8Array | string; executable?: boolean }
@@ -15,14 +36,21 @@ export interface BundleOptions {
 }
 
 export function sha256(data: Uint8Array | string): string {
-  return createHash('sha256').update(data).digest('hex');
+  const hash = CREATE_HASH('sha256');
+  HASH_UPDATE(hash, data);
+  return HASH_DIGEST(hash, 'hex');
 }
 
 /** A bundle-relative path: no empty, `.`, or `..` component, no backslash, NUL, or drive colon. */
 export function safePath(path: string): boolean {
-  return path.length > 0 && !path.includes('\\') && !path.includes('\0')
-    && path.split('/').every(part => part !== '' && part !== '.' && part !== '..')
-    && !path.includes(':');
+  if (path.length === 0 || STRING_INCLUDES(path, '\\') || STRING_INCLUDES(path, '\0')
+    || STRING_INCLUDES(path, ':')) return false;
+  const parts = STRING_SPLIT(path, '/');
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index]!;
+    if (part === '' || part === '.' || part === '..') return false;
+  }
+  return true;
 }
 
 /**
@@ -31,9 +59,26 @@ export function safePath(path: string): boolean {
  * thing everywhere: the digest of `[{bytes,path,sha256}]`, sorted by path.
  */
 export function payloadManifest(files: readonly { path: string; data: Uint8Array }[]): string {
-  return canonicalize([...files]
-    .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
-    .map(file => ({ path: file.path, sha256: sha256(file.data), bytes: file.data.length })));
+  const sorted: { path: string; data: Uint8Array }[] = [];
+  for (let index = 0; index < files.length; index += 1) appendIntrinsicArray(sorted, files[index]!);
+  // Do not consult mutable Array prototype methods here. Authored base code
+  // executes in this process before hosted artifact staging, so a live
+  // sort/map lookup would let it substitute bytes or manifest records.
+  for (let index = 1; index < sorted.length; index += 1) {
+    const current = sorted[index]!;
+    let position = index;
+    while (position > 0 && sorted[position - 1]!.path > current.path) {
+      sorted[position] = sorted[position - 1]!;
+      position -= 1;
+    }
+    sorted[position] = current;
+  }
+  const entries: { path: string; sha256: string; bytes: number }[] = [];
+  for (let index = 0; index < sorted.length; index += 1) {
+    const file = sorted[index]!;
+    appendIntrinsicArray(entries, { path: file.path, sha256: sha256(file.data), bytes: TYPED_ARRAY_LENGTH(file.data) });
+  }
+  return canonicalize(entries);
 }
 
 /** Manifest and identity are envelopes, excluded to avoid circular hashing. */

package/src/canonical.ts

@@ -9,6 +9,15 @@
 
 import { createHash } from 'node:crypto';
 import { snapshotJsonValue, type JsonValue } from './json-value.js';
+import { appendIntrinsicArray } from './intrinsic-array.js';
+
+const ARRAY_IS_ARRAY = Array.isArray;
+const ARRAY_JOIN = Function.prototype.call.bind(Array.prototype.join) as (
+  array: readonly string[], separator?: string,
+) => string;
+const ARRAY_SORT = Function.prototype.call.bind(Array.prototype.sort) as <T>(array: T[]) => T[];
+const JSON_STRINGIFY = JSON.stringify;
+const OBJECT_KEYS = Object.keys;
 
 /**
  * Serialize a value as canonical JSON: object keys sorted recursively,
@@ -42,16 +51,21 @@ export function specHash(spec: unknown): string {
  */
 function serialize(value: JsonValue): string {
   if (value === null || typeof value !== 'object') {
-    return JSON.stringify(value);
+    return JSON_STRINGIFY(value);
   }
-  if (Array.isArray(value)) {
-    return '[' + value.map(serialize).join(',') + ']';
+  if (ARRAY_IS_ARRAY(value)) {
+    const items: string[] = [];
+    for (let index = 0; index < value.length; index += 1) appendIntrinsicArray(items, serialize(value[index]!));
+    return '[' + ARRAY_JOIN(items, ',') + ']';
   }
   const parts: string[] = [];
-  for (const key of Object.keys(value).sort()) {
+  const keys = OBJECT_KEYS(value);
+  ARRAY_SORT(keys);
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index]!;
     const child = value[key];
     if (child === undefined) continue;
-    parts.push(JSON.stringify(key) + ':' + serialize(child));
+    appendIntrinsicArray(parts, JSON_STRINGIFY(key) + ':' + serialize(child));
   }
-  return '{' + parts.join(',') + '}';
+  return '{' + ARRAY_JOIN(parts, ',') + '}';
 }

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

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

package/src/cli/check.ts

@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:pat
 import { spawnSync } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
+import { agentWorkerDiagnostics } from './check-worker-surface.js';
 import { helperReady } from '../yaml-helper-effect.js';
 import { flowRequirements, type FlowRequirements } from '../flow-requirements.js';
 import {
@@ -117,6 +118,24 @@ export interface CheckExecution {
   flow?: FlowSpec;
 }
 
+/**
+ * Facts about the *caller*, not about the spec, that change which diagnostics
+ * apply. Preflight stays a pure function of the spec plus environment probes;
+ * anything that depends on how the flow is about to be invoked opts in here.
+ */
+export interface CheckInvocation {
+  /**
+   * Report `agent_worker_unresolved` when the spec has `agent` steps.
+   *
+   * Only `flows check` sets this. `flows run` attaches its own worker under
+   * `--local-agent` and knows the answer, `flows build` and `flows deploy`
+   * check a spec that will run elsewhere, and an SDK caller that reaches
+   * `checkAuthoredFlow` directly is generally running a worker already —
+   * warning any of them would be noise about a question they have answered.
+   */
+  warnUnresolvedAgentWorker?: boolean;
+}
+
 export class CheckFailure extends Error {
   constructor(readonly kind: CheckFailureKind, message: string) {
     super(message);
@@ -124,7 +143,7 @@ export class CheckFailure extends Error {
 }
 
 /** Validate and preflight one working-tree spec without starting a run. */
-export function checkFlow(path: string): CheckExecution {
+export function checkFlow(path: string, invocation: CheckInvocation = {}): CheckExecution {
   const absolutePath = resolve(path);
   try {
     const source = readFlowSource(absolutePath);
@@ -134,7 +153,7 @@ export function checkFlow(path: string): CheckExecution {
       : [];
     let execution: CheckExecution;
     try {
-      execution = checkAuthoredFlow(readFlow(source, absolutePath), path);
+      execution = checkAuthoredFlow(readFlow(source, absolutePath), path, undefined, invocation);
     } catch (error) {
       if (!(error instanceof CheckFailure)) throw error;
       execution = { report: inputFailureReport(error, path) };
@@ -164,7 +183,12 @@ function safeRequirements(authoring: FlowSpec, projectCli: string | undefined):
 }
 
 /** Preflight a validated authored flow through the same path as YAML/JSON. */
-export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConfig?: ProjectConfig): CheckExecution {
+export function checkAuthoredFlow(
+  authoring: FlowSpec,
+  path: string,
+  projectConfig?: ProjectConfig,
+  invocation: CheckInvocation = {},
+): CheckExecution {
   const absolutePath = resolve(path);
   try {
     const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
@@ -195,6 +219,13 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
       result.diagnostics.push({ severity: 'warning', kind: 'budget_unmetered',
         message: 'Managed communication sessions do not report token or dollar usage. Budget ceilings cannot bound their spend; communication.timeoutMs bounds their duration.' });
     }
+    // Reported whatever preflight concluded. An environment refusal (a missing
+    // CLI, an unknown model) is fixed and rerun; the worker question is still
+    // open on the next pass, and staying silent about it here is what made an
+    // author meet it one dead run at a time.
+    const workerSurface = invocation.warnUnresolvedAgentWorker === true
+      ? agentWorkerDiagnostics(authoring)
+      : [];
     return {
       report: {
         ok: result.ok,
@@ -202,7 +233,7 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
         ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
         gates: result.gates,
         resolutions: result.resolutions,
-        diagnostics: result.diagnostics,
+        diagnostics: [...result.diagnostics, ...workerSurface],
         requirements: safeRequirements(authoring, config.cli),
       },
       ...(result.ok && flow !== undefined ? { flow } : {}),

package/src/cli/cloud-format.ts

@@ -0,0 +1,82 @@
+// The cells every hosted-run page is built from.
+//
+// Moved out of `cli/cloud-read.ts` verbatim when the live views (`--watch`,
+// `--follow`) needed the same formatting: the run list, the status page and
+// the watched page must render a count, a cost and an instant identically, or
+// a reader would have to learn which verb they were looking at first.
+//
+// Depends on nothing in `cli/` but `formatDuration`, so every other Cloud CLI
+// module can import it without an import cycle.
+
+import { formatDuration } from './status.js';
+
+export function thousands(value: number): string {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+}
+
+export function dollars(value: number): string {
+  return `$${value.toFixed(6).replace(/0+$/u, '').replace(/\.$/u, '')}`;
+}
+
+/** Agent- and flow-authored names cannot inject terminal control sequences. */
+export function safe(text: string): string {
+  return text.replace(/[\u0000-\u001F\u007F-\u009F]/gu, '?');
+}
+
+/**
+ * Render a run's `error` as readable lines rather than one control-char smear.
+ *
+ * Cloud stores the runner's terminal output in this field, newlines and all, so
+ * passing it through `safe()` alone turns a 200-line tail into a single line of
+ * `?` separators. Long runs are dominated by lease renewals — one line every
+ * 10s for the life of every agent step, differing only in the deadline — which
+ * are worth counting, not reading.
+ *
+ * Collapsing is deliberately narrow: two adjacent lines merge only when they
+ * are character-for-character identical once a trailing integer is masked. A
+ * shared prefix is NOT line identity — runner lines put the step name, reason
+ * or message after a long fixed prefix, so collapsing on a prefix would hide
+ * distinct diagnostics behind a similarity count. The final line never
+ * collapses into an earlier one, because that is where the failure is.
+ */
+const TRAILING_NUMBER = /\d+(?=\D{0,2}$)/u;
+
+export function errorLines(text: string, indent: string): string[] {
+  const raw = text.split(/\r\n|\r|\n/u).map((line) => line.trimEnd()).filter((line) => line !== '');
+  if (raw.length === 0) return [];
+
+  const key = (line: string): string => line.replace(TRAILING_NUMBER, '#');
+  const collapsed: { line: string; count: number }[] = [];
+  raw.forEach((line, index) => {
+    const previous = collapsed.at(-1);
+    const isLast = index === raw.length - 1;
+    if (previous !== undefined && !isLast && key(previous.line) === key(line)) previous.count += 1;
+    else collapsed.push({ line, count: 1 });
+  });
+
+  const rendered = collapsed.map(({ line, count }) =>
+    count === 1 ? safe(line) : `${safe(line)}  (${count} times, differing only in a number)`);
+
+  const HEAD = 2;
+  const TAIL = 12;
+  if (rendered.length <= HEAD + TAIL + 1) return rendered.map((line) => `${indent}${line}`);
+  const elided = rendered.length - HEAD - TAIL;
+  return [
+    ...rendered.slice(0, HEAD),
+    `… ${elided} more line${elided === 1 ? '' : 's'} (full text: --json)`,
+    ...rendered.slice(-TAIL),
+  ].map((line) => `${indent}${line}`);
+}
+
+/** ISO-8601 to the second: a list column, not a timestamp to do arithmetic on. */
+export function instant(value: string | null): string {
+  if (value === null) return 'unknown';
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString().replace(/\.\d{3}Z$/u, 'Z') : 'unknown';
+}
+
+export function ago(value: string | null, now: number): string {
+  if (value === null) return 'unknown';
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? `${formatDuration(now - parsed)} ago` : 'unknown';
+}