@relayflows/sdk 2.0.30 → 2.0.32

package/src/cli/check.ts

@@ -1,22 +1,13 @@
 import { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment } from '../communication/preflight.js';
-import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
 import { accessSync, constants, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
-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 {
-  adapterIdentification,
-  authenticationProbe,
-  cliAdapterKind,
-  displayInvocation,
-  modelReadinessProbe,
-  type CliInvocation,
-} from '../cli-adapter.js';
-import { MODEL_ENV } from '../worker-cli.js';
+import { probeCli, resolveExecutable } from './cli-probe.js';
 import { modelNameError } from '../model-name.js';
 import type { FlowSpec } from '../spec.js';
 import type { McpServerConfig } from '../spec.js';
@@ -25,9 +16,9 @@ import type { StepGateInspection } from '../gate-contract.js';
 import type { CheckFailureKind, CheckWarningKind } from '../failure-kinds.js';
 import {
   preflight,
-  CliProbeError,
   type CliResolution,
   type CliProbeResult,
+  type CliProbeOutcome,
   type PreflightDiagnostic,
   type PreflightProbes,
 } from '../preflight.js';
@@ -117,6 +108,33 @@ export interface CheckExecution {
   flow?: FlowSpec;
 }
 
+/** Compatibility options accepted by older authored callers. */
+export interface AuthoredCheckOptions {
+  projectConfig?: ProjectConfig;
+  probeCache?: CliProbeOutcomeMap;
+  communicationChecked?: boolean;
+}
+
+type CliProbeOutcomeMap = Map<string, CliProbeOutcome>;
+
+/**
+ * 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 +142,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 +152,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,12 +182,29 @@ 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,
+  projectConfigOrOptions?: ProjectConfig | AuthoredCheckOptions,
+  invocation: CheckInvocation = {},
+  cliProbeCache?: Map<string, CliProbeOutcome>,
+): CheckExecution {
   const absolutePath = resolve(path);
   try {
+    const options = projectConfigOrOptions !== undefined
+      && ('projectConfig' in projectConfigOrOptions
+        || 'probeCache' in projectConfigOrOptions
+        || 'communicationChecked' in projectConfigOrOptions)
+      ? projectConfigOrOptions
+      : undefined;
+    const projectConfig = options !== undefined
+      ? options.projectConfig
+      : projectConfigOrOptions as ProjectConfig | undefined;
+    const effectiveProbeCache = cliProbeCache ?? options?.probeCache;
     const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
     const probes = systemProbes(dirname(absolutePath), config);
     const result = preflight(authoring, {
+      ...(effectiveProbeCache === undefined ? {} : { cliProbeCache: effectiveProbeCache }),
       projectCli: config.cli,
       projectConfigPath: config.path,
       projectSearchStart: dirname(absolutePath),
@@ -186,7 +221,7 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
         )
       : undefined;
     if (flow?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
-      try { checkCommunicationEnvironment(flow); }
+      try { if (options?.communicationChecked !== true) checkCommunicationEnvironment(flow); }
       catch (error) {
         result.ok = false;
         result.diagnostics.push({ severity: 'refusal', kind: 'probe_failed',
@@ -195,6 +230,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 +244,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 } : {}),
@@ -448,155 +490,6 @@ function canonicalCli(cli: string, directory: string): string {
   return resolve(directory, cli);
 }
 
-function probeCli(
-  cli: string,
-  directory: string,
-  model?: string,
-  execution?: 'managed',
-): CliProbeResult {
-  const executable = resolveExecutable(cli, directory);
-  if (executable === undefined) return { exists: false, authenticated: false };
-  const kind = cliAdapterKind(executable);
-  // Relay owns interactive CLI launch/injection. Its generic PTY path is not
-  // the headless wrapper protocol; do not demand that protocol from Gemini,
-  // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
-  if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
-    return { exists: true, supported: true, authenticated: 'unverified' };
-  }
-  const environment = execution === 'managed'
-    ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
-  const probe = (invocation: CliInvocation) => runProbe(executable, directory, invocation, environment);
-  const identification = adapterIdentification(kind);
-  const identified = probe(identification.invocation);
-  if (
-    identified.status !== 0
-    || (identification.expectedStdout !== undefined
-      && identified.stdout.trim() !== identification.expectedStdout)
-  ) {
-    return { exists: true, supported: false, authenticated: false };
-  }
-  const auth = authenticationProbe(kind);
-  const authCommand = displayInvocation(cli, auth);
-  if (model === undefined) {
-    return {
-      exists: true,
-      supported: true,
-      authenticated: probe(auth).status === 0,
-      authCommand,
-    };
-  }
-
-  const scoped = modelReadinessProbe(kind, model);
-  const modelCommand = displayInvocation(cli, scoped);
-  // A successful real provider round trip (or identified wrapper probe)
-  // proves both auth and exact-model access. On failure, run the adapter's
-  // actual auth command solely to classify auth vs model access truthfully.
-  if (probe(scoped).status === 0) {
-    return {
-      exists: true,
-      supported: true,
-      authenticated: true,
-      modelAvailable: true,
-      authCommand,
-      modelCommand,
-    };
-  }
-  const authProbe = probe(auth);
-  const authenticated = authProbe.status === 0;
-  return {
-    exists: true,
-    supported: true,
-    authenticated,
-    modelAvailable: false,
-    authCommand,
-    modelCommand,
-    // Only on failure: on success there is nothing to explain, and the output
-    // is the most identity-bearing thing this function touches.
-    ...(authenticated
-      ? {}
-      : {
-        authExitCode: authProbe.status,
-        authFailureDetail: redactProbeOutput(
-          `${authProbe.stderr}${authProbe.stdout}`,
-        ).trim().slice(0, 500),
-      }),
-  };
-}
-
-/**
- * Redact anything that looks like a credential or an account identifier.
- *
- * `auth status` output is diagnostic, but it is also the one place an account
- * email, org id or token fragment can appear. The point of surfacing it is to
- * say WHY a probe failed, which survives redaction; leaking an identity into a
- * refusal message that gets pasted into issues does not.
- */
-function redactProbeOutput(text: string): string {
-  return text
-    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
-    .replace(/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, '<redacted-token>')
-    .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
-}
-
-function runProbe(
-  executable: string,
-  directory: string,
-  invocation: CliInvocation,
-  environment: NodeJS.ProcessEnv = process.env,
-): { status: number | null; stdout: string; stderr: string } {
-  const env = { ...environment };
-  delete env[MODEL_ENV];
-  if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
-  const result = spawnSync(executable, invocation.args, {
-    cwd: directory,
-    encoding: 'utf8',
-    // stderr was 'ignore'. A failing `auth status` writes its reason there, so
-    // discarding it made every authentication refusal structurally
-    // undiagnosable: the refusal could say a probe exited non-zero and never
-    // what it said. Captured, then redacted at the point of use.
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: invocation.timeoutMs,
-    env,
-  });
-  const failure = classifySpawnFailure(result.error, result.signal, invocation.timeoutMs);
-  if (failure !== undefined) throw failure;
-  return {
-    status: result.status,
-    stdout: result.stdout,
-    stderr: result.stderr ?? '',
-  };
-}
-
-function resolveExecutable(command: string, directory: string): string | undefined {
-  if (command.includes('/') || isAbsolute(command)) {
-    const path = isAbsolute(command) ? command : resolve(directory, command);
-    try {
-      accessSync(path, constants.X_OK);
-      return path;
-    } catch {
-      return undefined;
-    }
-  }
-  const result = spawnSync('which', [command], { encoding: 'utf8', timeout: 5_000 });
-  const failure = classifySpawnFailure(result.error, result.signal, 5_000);
-  if (failure !== undefined) throw failure;
-  return result.status === 0 ? result.stdout.trim() : undefined;
-}
-
-function classifySpawnFailure(
-  error: Error | undefined,
-  signal: NodeJS.Signals | null,
-  timeoutMs: number,
-): CliProbeError | undefined {
-  if (error !== undefined) {
-    const detail = (error as NodeJS.ErrnoException).code === 'ETIMEDOUT'
-      ? `timeout:${timeoutMs}ms` as const
-      : 'spawn_failed' as const;
-    return new CliProbeError(detail);
-  }
-  return signal === null ? undefined : new CliProbeError(`signal:${signal}`);
-}
-
 function executableExists(command: string, directory: string): boolean {
   return resolveExecutable(command, directory) !== undefined;
 }

package/src/cli/cli-probe.ts

@@ -0,0 +1,194 @@
+import { accessSync, constants } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { execFile, spawnSync } from 'node:child_process';
+import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
+import { adapterIdentification, authenticationProbe, cliAdapterKind, displayInvocation,
+  modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
+import { MODEL_ENV } from '../worker-cli.js';
+import { CliProbeError, type CliProbeResult } from '../preflight.js';
+
+interface ProbeRequest {
+  executable: string;
+  directory: string;
+  invocation: CliInvocation;
+  environment: NodeJS.ProcessEnv;
+}
+interface ProbeOutput { status: number | null; stdout: string; stderr: string }
+
+/** One decision sequence; checking uses synchronous I/O, live flows yield the loop. */
+export function probeCli(...args: Parameters<typeof probeSequence>): CliProbeResult {
+  return driveSync(probeSequence(...args));
+}
+
+export async function probeCliAsync(...args: Parameters<typeof probeSequence>): Promise<CliProbeResult> {
+  const sequence = probeSequence(...args);
+  let next = sequence.next();
+  while (!next.done) next = sequence.next(await runProbeAsync(next.value));
+  return next.value;
+}
+
+export function resolveExecutable(command: string, directory: string): string | undefined {
+  return driveSync(executableSequence(command, directory));
+}
+
+function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
+  let next = sequence.next();
+  while (!next.done) {
+    const request = next.value;
+    const result = spawnSync(request.executable, request.invocation.args, {
+      ...probeOptions(request),
+      // Preserve the old synchronous probe contract: provider CLIs must not
+      // inherit a readable stdin that can block auth/identify probes.
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const failure = classifySpawnFailure(result.error, result.signal, request.invocation.timeoutMs);
+    if (failure !== undefined) throw failure;
+    next = sequence.next({ status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' });
+  }
+  return next.value;
+}
+
+function probeOptions({ directory, invocation, environment }: ProbeRequest) {
+  const env = { ...environment };
+  delete env[MODEL_ENV];
+  if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
+  return { cwd: directory, encoding: 'utf8' as const, timeout: invocation.timeoutMs,
+    maxBuffer: 1024 * 1024, env };
+}
+
+function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(request.executable, request.invocation.args, probeOptions(request),
+      (error, stdout, stderr) => {
+        // Numeric exit codes are probe results; launch, timeout, signal and buffer
+        // errors are failures to collect a fact, just as in the synchronous driver.
+        if (error?.killed && typeof error.code !== 'string') return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
+        const failure = classifySpawnFailure(
+          error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined,
+          error?.signal ?? null, request.invocation.timeoutMs);
+        if (failure !== undefined) return reject(failure);
+        resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+          stdout, stderr });
+      });
+    child.stdin?.end();
+  });
+}
+
+function* probeSequence(
+  cli: string,
+  directory: string,
+  model?: string,
+  execution?: 'managed',
+): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
+  const executable = yield* executableSequence(cli, directory);
+  if (executable === undefined) return { exists: false, authenticated: false };
+  const kind = cliAdapterKind(executable);
+  // Relay owns interactive CLI launch/injection. Its generic PTY path is not
+  // the headless wrapper protocol; do not demand that protocol from Gemini,
+  // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
+  if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
+    return { exists: true, supported: true, authenticated: 'unverified' };
+  }
+  const environment = execution === 'managed'
+    ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
+  const probe = (invocation: CliInvocation): ProbeRequest => ({ executable, directory, invocation, environment });
+  const identification = adapterIdentification(kind);
+  const identified = yield probe(identification.invocation);
+  if (
+    identified.status !== 0
+    || (identification.expectedStdout !== undefined
+      && identified.stdout.trim() !== identification.expectedStdout)
+  ) {
+    return { exists: true, supported: false, authenticated: false };
+  }
+  const auth = authenticationProbe(kind);
+  const authCommand = displayInvocation(cli, auth);
+  if (model === undefined) {
+    return {
+      exists: true,
+      supported: true,
+      authenticated: (yield probe(auth)).status === 0,
+      authCommand,
+    };
+  }
+
+  const scoped = modelReadinessProbe(kind, model);
+  const modelCommand = displayInvocation(cli, scoped);
+  // A successful real provider round trip (or identified wrapper probe)
+  // proves both auth and exact-model access. On failure, run the adapter's
+  // actual auth command solely to classify auth vs model access truthfully.
+  if ((yield probe(scoped)).status === 0) {
+    return {
+      exists: true,
+      supported: true,
+      authenticated: true,
+      modelAvailable: true,
+      authCommand,
+      modelCommand,
+    };
+  }
+  const authProbe = yield probe(auth);
+  const authenticated = authProbe.status === 0;
+  return {
+    exists: true,
+    supported: true,
+    authenticated,
+    modelAvailable: false,
+    authCommand,
+    modelCommand,
+    // Only on failure: on success there is nothing to explain, and the output
+    // is the most identity-bearing thing this function touches.
+    ...(authenticated
+      ? {}
+      : {
+        authExitCode: authProbe.status,
+        authFailureDetail: redactProbeOutput(
+          `${authProbe.stderr}${authProbe.stdout}`,
+        ).trim().slice(0, 500),
+      }),
+  };
+}
+
+/**
+ * Redact anything that looks like a credential or an account identifier.
+ *
+ * `auth status` output is diagnostic, but it is also the one place an account
+ * email, org id or token fragment can appear. The point of surfacing it is to
+ * say WHY a probe failed, which survives redaction; leaking an identity into a
+ * refusal message that gets pasted into issues does not.
+ */
+function redactProbeOutput(text: string): string {
+  return text
+    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
+    .replace(/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, '<redacted-token>')
+    .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
+}
+
+function* executableSequence(command: string, directory: string): Generator<ProbeRequest, string | undefined, ProbeOutput> {
+  if (command.includes('/') || isAbsolute(command)) {
+    const path = isAbsolute(command) ? command : resolve(directory, command);
+    try {
+      accessSync(path, constants.X_OK);
+      return path;
+    } catch {
+      return undefined;
+    }
+  }
+  const result = yield { executable: 'which', directory: process.cwd(),
+    invocation: { args: [command], timeoutMs: 5_000 }, environment: process.env };
+  return result.status === 0 ? result.stdout.trim() : undefined;
+}
+
+function classifySpawnFailure(
+  error: Error | undefined,
+  signal: NodeJS.Signals | null,
+  timeoutMs: number,
+): CliProbeError | undefined {
+  if (error !== undefined) {
+    const detail = (error as NodeJS.ErrnoException).code === 'ETIMEDOUT'
+      ? `timeout:${timeoutMs}ms` as const
+      : 'spawn_failed' as const;
+    return new CliProbeError(detail);
+  }
+  return signal === null ? undefined : new CliProbeError(`signal:${signal}`);
+}

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';
+}