@relayflows/sdk 2.0.21 → 2.0.23

package/dist/redact.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Scrub secret env values and known token shapes out of `text`.
+ *
+ * An env value is replaced by `[redacted:<NAME>]` so the reader learns which
+ * variable leaked without learning its value. Token shapes are replaced by
+ * `[redacted]`; header and `NAME=value` shapes keep their name.
+ */
+export declare function redact(text: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The relay-transport error scrub `worker-cli.ts` has always applied: the two
+ * relay credential names by exact match, at any length, spelled `[redacted]`.
+ * Everything `redact` adds is applied after, so the historical output for
+ * those two names and the token pattern is unchanged.
+ */
+export declare function redactRelayError(message: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AA4EA;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAQjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAM9F"}

package/dist/redact.js

@@ -0,0 +1,104 @@
+// Redaction for free text an agent-facing surface may print.
+//
+// `flows status` renders gate `detail`, transcript tails and error messages
+// to a process that may be an agent, in a sandbox whose stdout is captured.
+// A direct agent inherits the worker's whole environment (worker-cli.ts), so
+// anything the operator exported can be echoed back into that text. This
+// module is the one place that decides what never reaches the page.
+//
+// Applied to free text only. Identifiers — run ids, step ids, hashes and env
+// NAMES — are never rewritten, so the view stays greppable.
+/** Env names whose values are treated as secret when they are long enough. */
+const SECRET_NAME = /TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH/i;
+/** Shorter values are flags and modes (`AUTH_MODE=off`), not material. */
+const MIN_SECRET_LENGTH = 8;
+/**
+ * Token shapes replaced wholesale. The first is the relay token family
+ * `redactRelayError` in worker-cli.ts already scrubbed; the rest are the
+ * bearer, header and vendor shapes a gate render can carry.
+ */
+const TOKEN_PATTERNS = [
+    /\b(?:at|rk|nt|ot|br|arr)_(?:live_)?[A-Za-z0-9_-]+/g,
+    /\bsk-[A-Za-z0-9_-]{16,}/g,
+    /\bghp_[A-Za-z0-9]{20,}/g,
+    /\bxox[abp]-[A-Za-z0-9-]+/g,
+];
+/**
+ * Header and assignment shapes: keep the name (and an auth scheme), replace
+ * the value. A value already replaced by an earlier pass is left as it is,
+ * so the reader still sees which env name it came from.
+ */
+const NAMED_VALUE_PATTERNS = [
+    /\b(authorization:\s*(?:\w+\s+)?)(?!\[redacted)\S+/gi,
+    /\b(Bearer\s+)(?!\[redacted)\S+/g,
+    /\b(x-callback-token:\s*)(?!\[redacted)\S+/gi,
+    /\b(x-nightcto-evidence-token:\s*)(?!\[redacted)\S+/gi,
+    /\b([A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD)=)(?!\[redacted)\S+/gi,
+];
+/**
+ * Credential fields in serialized JSON. A gate detail or a transcript line
+ * often carries a request or config body, where the value is an opaque string
+ * that matches no vendor token shape and — for anything this process did not
+ * export — no environment value either: `{"authToken":"opaque-secret"}` went
+ * through untouched. The field name is kept, so the reader knows what was cut.
+ *
+ * Quoted string values only — including escaped ones: a serialized private
+ * key or nested JSON reaches these fields as `\n` and `\"`, and a value
+ * class that stopped at the first backslash left every one of them intact.
+ * Only where the field NAME ends in a credential noun. Containing one is not enough: `monkey` and `keyboard` are
+ * ordinary fields, so the name is split on separators and camelCase humps and
+ * the last word decides.
+ */
+const JSON_STRING_FIELD = /("([A-Za-z0-9_.\-]{1,64})"\s*:\s*")(?!\[redacted)((?:[^"\\]|\\.){4,})(")/g;
+const CREDENTIAL_NOUN = /^(?:token|secret|key|password|passwd|credential|cookie)s?$/i;
+function isCredentialName(name) {
+    if (name.toLowerCase() === 'authorization')
+        return true;
+    const words = name.split(/[_\-.]+/).flatMap((word) => word.split(/(?<=[a-z0-9])(?=[A-Z])/u));
+    const last = words.at(-1);
+    return last !== undefined && CREDENTIAL_NOUN.test(last);
+}
+/** Secret env values, longest first so a value that contains another is replaced whole. */
+function secretEnvValues(env) {
+    const secrets = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (typeof value !== 'string' || value.length < MIN_SECRET_LENGTH)
+            continue;
+        if (SECRET_NAME.test(name))
+            secrets.push([name, value]);
+    }
+    return secrets.sort((a, b) => b[1].length - a[1].length);
+}
+/**
+ * Scrub secret env values and known token shapes out of `text`.
+ *
+ * An env value is replaced by `[redacted:<NAME>]` so the reader learns which
+ * variable leaked without learning its value. Token shapes are replaced by
+ * `[redacted]`; header and `NAME=value` shapes keep their name.
+ */
+export function redact(text, env = process.env) {
+    let out = text;
+    for (const [name, value] of secretEnvValues(env))
+        out = out.replaceAll(value, `[redacted:${name}]`);
+    for (const pattern of TOKEN_PATTERNS)
+        out = out.replace(pattern, '[redacted]');
+    for (const pattern of NAMED_VALUE_PATTERNS)
+        out = out.replace(pattern, '$1[redacted]');
+    out = out.replace(JSON_STRING_FIELD, (match, open, name, _value, close) => isCredentialName(name) ? `${open}[redacted]${close}` : match);
+    return out;
+}
+/**
+ * The relay-transport error scrub `worker-cli.ts` has always applied: the two
+ * relay credential names by exact match, at any length, spelled `[redacted]`.
+ * Everything `redact` adds is applied after, so the historical output for
+ * those two names and the token pattern is unchanged.
+ */
+export function redactRelayError(message, env = process.env) {
+    for (const key of ['RELAY_AGENT_TOKEN', 'RELAY_API_KEY']) {
+        const secret = env[key];
+        if (secret)
+            message = message.replaceAll(secret, '[redacted]');
+    }
+    return redact(message, env);
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

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

package/dist/run-state.d.ts

@@ -0,0 +1,124 @@
+import type { JournalEvent } from './journal-reader.js';
+export type RunStatus = 'running' | 'parked' | 'completed' | 'failed' | 'cancelling' | 'cancelled';
+/** `StepState` variant names from state.rs, snake_case. */
+export type StepStateName = 'pending' | 'runnable' | 'running' | 'backoff' | 'waiting' | 'needs_human' | 'done';
+export interface Spend {
+    tokens_in: number;
+    tokens_out: number;
+    /** Decimal string, as the journal stores it; never a float. */
+    dollars: string;
+    dollars_unmetered: boolean;
+}
+export interface StepCounts {
+    total: number;
+    done: number;
+    running: number;
+    /** `pending` and `runnable` both: neither has started an attempt. */
+    pending: number;
+    backoff: number;
+    waiting: number;
+    needs_human: number;
+}
+/**
+ * The part of the attempt's journaled transcript digest (flows#491, written to
+ * `trajectory_tail.transcript`) that a status view shows. Not the whole digest:
+ * the tool roster and per-call excerpts are the transcript file's job, and this
+ * view has to stay small and greppable. Every string here was redacted when the
+ * digest was built and is redacted again on the way out.
+ */
+export interface AttemptTranscript {
+    /** Where the full per-attempt transcript is, so a reader can go and open it. */
+    path: string | null;
+    bytes: number | null;
+    truncated: boolean;
+    model: string | null;
+    num_turns: number | null;
+    total_cost_usd: number | null;
+    tool_calls: number | null;
+    /** Why the attempt failed, as the digest recorded it; already bounded. */
+    failure: {
+        kind: string;
+        excerpt: string;
+    } | null;
+}
+export interface LastAttempt {
+    attempt: number;
+    completion_reason: string;
+    disposition: string;
+    verification: {
+        gate: string;
+        verdict: string;
+        detail: string;
+    } | null;
+    human_intervention: boolean;
+    /** Count only; the refs carry surface paths and idempotency keys. */
+    effects: number;
+    ended_at_ms: number;
+    /** Null when the attempt journaled no digest — an llm step, or a pre-#491 run. */
+    transcript: AttemptTranscript | null;
+}
+export interface StepView {
+    id: string;
+    type: string;
+    state: StepStateName;
+    attempt: number;
+    max_iterations: number | null;
+    started_at_ms: number | null;
+    elapsed_ms: number | null;
+    lease: {
+        deadline_ms: number;
+        overdue_ms: number;
+    } | null;
+    backoff_until_ms: number | null;
+    wait: {
+        wait_id: string;
+        kind: 'human' | 'event' | 'timer';
+        timeout_at_ms: number | null;
+    } | null;
+    last_attempt: LastAttempt | null;
+    /**
+     * Why this step finished, once it is `done`. Separate from `last_attempt`
+     * because an epoch summary carries `steps_done[id].completionReason`
+     * (kernel `entry.rs` `StepDoneSummary`) but no attempt record — so after a
+     * compaction this is the only place the fact survives. Dependency readiness
+     * and the failure glyph both read this, never `last_attempt`.
+     */
+    completion_reason: string | null;
+    /** Paths the worker journaled for the last attempt, when its output carried them. */
+    artifacts: {
+        paths: string[];
+        journaled: boolean;
+    };
+}
+export interface RunView {
+    run_id: string;
+    name: string;
+    status: RunStatus;
+    completion_reason: string | null;
+    spawned_at_ms: number;
+    now_ms: number;
+    spend: Spend;
+    counts: StepCounts;
+    steps: StepView[];
+}
+export declare class RunStateError extends Error {
+    constructor(message: string);
+}
+/**
+ * Sum two decimal dollar strings exactly, at whatever scale they carry — the
+ * kernel's budget fold (`relayflowd-core/src/state/budget.rs`) aligns every
+ * fractional digit before adding, and it accepts arbitrary precision. Scaling
+ * to a fixed six fractional digits dropped a charge of `0.0000001` to zero, so
+ * `flows status` underreported spend the kernel had totalled exactly.
+ *
+ * A value that is not a decimal number is left out of the sum rather than
+ * counted as zero, and the caller is told by `malformed`.
+ */
+export declare function addDollars(left: string, right: string): string;
+/**
+ * Fold journal events, in sequence order, into a {@link RunView} as of
+ * `now_ms`. Throws {@link RunStateError} on a journal the kernel would also
+ * refuse (no `run.spawned` first, an unknown step).
+ */
+export declare function foldRunState(events: readonly JournalEvent[], now_ms: number): RunView;
+//# sourceMappingURL=run-state.d.ts.map

package/dist/run-state.d.ts.map

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

package/dist/run-state.js

@@ -0,0 +1,368 @@
+// Pure fold of a run's journal into the view `flows status` renders.
+//
+// Mirrors the kernel's `RunState::fold` (kernel/relayflowd-core/src/state.rs)
+// transition for transition, but keeps only what a status view needs: step
+// state, attempt, lease, backoff, wait, the last completion's verdict, and
+// spend. Nothing here reads a prompt, an input binding, an output body, a
+// wake context or a pin — the model has no field for them, so their absence
+// from the rendered view is structural rather than a matter of care.
+//
+// No I/O, no clock: the caller passes `now_ms`, so a test folds a hand-built
+// journal against a fixed instant and asserts exact elapsed and overdue values.
+export class RunStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RunStateError';
+    }
+}
+function payloadOf(event) {
+    return event.payload !== null && typeof event.payload === 'object' && !Array.isArray(event.payload)
+        ? event.payload : {};
+}
+function integer(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) ? value : null;
+}
+function text(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+/**
+ * Sum two decimal dollar strings exactly, at whatever scale they carry — the
+ * kernel's budget fold (`relayflowd-core/src/state/budget.rs`) aligns every
+ * fractional digit before adding, and it accepts arbitrary precision. Scaling
+ * to a fixed six fractional digits dropped a charge of `0.0000001` to zero, so
+ * `flows status` underreported spend the kernel had totalled exactly.
+ *
+ * A value that is not a decimal number is left out of the sum rather than
+ * counted as zero, and the caller is told by `malformed`.
+ */
+export function addDollars(left, right) {
+    const parsed = [left, right].map((value) => /^\d+(?:\.\d+)?$/.test(value) ? value : null);
+    const usable = parsed.filter((value) => value !== null);
+    if (usable.length === 0)
+        return '0';
+    if (usable.length === 1)
+        return normalizeDollars(usable[0]);
+    const scale = Math.max(...usable.map((value) => (value.split('.')[1] ?? '').length));
+    const scaled = usable.map((value) => {
+        const [whole, fraction = ''] = value.split('.');
+        return BigInt(`${whole}${fraction.padEnd(scale, '0')}`);
+    });
+    return fromScaled(scaled[0] + scaled[1], scale);
+}
+/** `12.3400` -> `12.34`, `0.000` -> `0`; the journal's own spelling otherwise. */
+function normalizeDollars(value) {
+    const [whole, fraction = ''] = value.split('.');
+    return fromScaled(BigInt(`${whole}${fraction}`), fraction.length);
+}
+function fromScaled(total, scale) {
+    if (scale === 0)
+        return String(total);
+    const digits = String(total).padStart(scale + 1, '0');
+    const whole = digits.slice(0, digits.length - scale);
+    const fraction = digits.slice(digits.length - scale).replace(/0+$/, '');
+    return fraction.length === 0 ? whole : `${whole}.${fraction}`;
+}
+/**
+ * Reduce `trajectory_tail.transcript` (the digest flows#491 journals) to the
+ * handful of facts a status view shows. Every field is taken defensively: the
+ * journal is evidence written by a worker that may predate this reader, so a
+ * missing or wrong-typed field becomes null rather than throwing.
+ */
+function attemptTranscript(trajectoryTail) {
+    // Arrays are objects too, and a malformed digest is exactly the shape that
+    // would otherwise reach the view as `{ kind: 'unknown', excerpt: '' }`.
+    const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    const digest = object(object(trajectoryTail)?.['transcript']);
+    if (digest === null)
+        return null;
+    const file = object(digest['file']) ?? {};
+    const result = object(digest['result']) ?? {};
+    const tools = object(digest['tools']) ?? {};
+    const failure = object(digest['failure']);
+    return {
+        path: typeof file['path'] === 'string' ? file['path'] : null,
+        bytes: integer(file['bytes_kept']),
+        truncated: file['truncated'] === true,
+        model: typeof result['model'] === 'string' ? result['model'] : null,
+        num_turns: integer(result['num_turns']),
+        total_cost_usd: typeof result['total_cost_usd'] === 'number' && Number.isFinite(result['total_cost_usd'])
+            ? result['total_cost_usd'] : null,
+        tool_calls: integer(tools['total_calls']),
+        failure: failure === null ? null : {
+            kind: text(failure['kind'], 'unknown'),
+            excerpt: text(failure['excerpt']),
+        },
+    };
+}
+function addSpend(total, charge) {
+    const budget = charge !== null && typeof charge === 'object' ? charge : {};
+    return {
+        tokens_in: total.tokens_in + (integer(budget['tokens_in']) ?? 0),
+        tokens_out: total.tokens_out + (integer(budget['tokens_out']) ?? 0),
+        dollars: addDollars(total.dollars, text(budget['dollars'], '0')),
+        dollars_unmetered: total.dollars_unmetered || budget['dollars_unmetered'] === true,
+    };
+}
+const ZERO_SPEND = { tokens_in: 0, tokens_out: 0, dollars: '0', dollars_unmetered: false };
+function freshStep(id, type, maxIterations, dependsOn) {
+    return {
+        depends_on: dependsOn,
+        view: {
+            id, type, state: 'pending', attempt: 0, max_iterations: maxIterations,
+            started_at_ms: null, elapsed_ms: null, lease: null, backoff_until_ms: null, wait: null,
+            last_attempt: null, completion_reason: null, artifacts: { paths: [], journaled: false },
+        },
+    };
+}
+/** Leave the transient facts of one state behind when entering another. */
+function enter(view, state) {
+    view.state = state;
+    view.lease = null;
+    view.backoff_until_ms = null;
+    view.wait = null;
+}
+function artifactsOf(output) {
+    // worker.ts journals `artifacts` inside the CliResult wrapper only when the
+    // agent's stdout was not a JSON object; on the JSON path the author's
+    // object is the output and carries no such key.
+    if (output === null || typeof output !== 'object' || Array.isArray(output))
+        return { paths: [], journaled: false };
+    const paths = output['artifacts'];
+    if (!Array.isArray(paths) || !paths.every((path) => typeof path === 'string'))
+        return { paths: [], journaled: false };
+    return { paths: [...paths], journaled: true };
+}
+/**
+ * Fold journal events, in sequence order, into a {@link RunView} as of
+ * `now_ms`. Throws {@link RunStateError} on a journal the kernel would also
+ * refuse (no `run.spawned` first, an unknown step).
+ */
+export function foldRunState(events, now_ms) {
+    const first = events[0];
+    if (first === undefined || first.entry_type !== 'run.spawned') {
+        throw new RunStateError('Journal does not begin with run.spawned.');
+    }
+    const spawned = payloadOf(first);
+    const spec = spawned['spec'] !== null && typeof spawned['spec'] === 'object' ? spawned['spec'] : {};
+    const declared = Array.isArray(spec['steps']) ? spec['steps'] : [];
+    const steps = new Map();
+    for (const entry of declared) {
+        const step = entry !== null && typeof entry === 'object' ? entry : {};
+        const id = text(step['id']);
+        if (id.length === 0)
+            throw new RunStateError('Spec step without an id.');
+        const dependsOn = Array.isArray(step['depends_on']) ? step['depends_on'].filter((d) => typeof d === 'string') : [];
+        steps.set(id, freshStep(id, text(step['type'], 'unknown'), integer(step['max_iterations']), dependsOn));
+    }
+    const budget = spec['budget'] !== null && typeof spec['budget'] === 'object' ? spec['budget'] : {};
+    // An authored child run carries its parent's totals so ceilings hold across
+    // the family (state.rs `prior_spend`); the view reports the same running total.
+    let spend = addSpend(ZERO_SPEND, budget['prior_spend']);
+    let completion = null;
+    let cancelRequested = false;
+    const stepOf = (event) => {
+        if (event.step_id === null)
+            throw new RunStateError(`Entry seq ${event.seq} (${event.entry_type}) names no step.`);
+        const step = steps.get(event.step_id);
+        if (step === undefined)
+            throw new RunStateError(`Entry seq ${event.seq} names unknown step ${JSON.stringify(event.step_id)}.`);
+        return step.view;
+    };
+    for (const event of events.slice(1)) {
+        const payload = payloadOf(event);
+        switch (event.entry_type) {
+            case 'step.attempt.started': {
+                const view = stepOf(event);
+                const attempt = event.attempt ?? view.attempt;
+                view.attempt = Math.max(view.attempt, attempt);
+                view.max_iterations = integer(payload['max_iterations']) ?? view.max_iterations;
+                view.started_at_ms = event.at_ms;
+                enter(view, 'running');
+                const deadline = integer(payload['lease_deadline_ms']) ?? event.at_ms;
+                view.lease = { deadline_ms: deadline, overdue_ms: 0 };
+                break;
+            }
+            case 'step.completed': {
+                const view = stepOf(event);
+                const attempt = event.attempt ?? view.attempt;
+                view.attempt = Math.max(view.attempt, attempt);
+                spend = addSpend(spend, payload['budget']);
+                const verification = payload['verification'] !== null && typeof payload['verification'] === 'object'
+                    ? payload['verification'] : undefined;
+                view.last_attempt = {
+                    attempt,
+                    completion_reason: text(payload['completionReason'], 'unknown'),
+                    disposition: text(payload['disposition'], 'unknown'),
+                    verification: verification === undefined ? null : {
+                        gate: text(verification['gate']), verdict: text(verification['verdict']), detail: text(verification['detail']),
+                    },
+                    human_intervention: payload['human_intervention'] === true,
+                    effects: Array.isArray(payload['effects']) ? payload['effects'].length : 0,
+                    ended_at_ms: event.at_ms,
+                    transcript: attemptTranscript(payload['trajectory_tail']),
+                };
+                view.artifacts = artifactsOf(payload['output']);
+                const disposition = payload['disposition'];
+                if (disposition === 'retry') {
+                    enter(view, 'backoff');
+                    view.backoff_until_ms = integer(payload['next_attempt_at_ms']) ?? event.at_ms;
+                }
+                else if (disposition === 'park') {
+                    enter(view, 'needs_human');
+                    view.wait = { wait_id: `park-${view.id}-${attempt}`, kind: 'human', timeout_at_ms: null };
+                }
+                else {
+                    enter(view, 'done');
+                    view.completion_reason = view.last_attempt.completion_reason;
+                }
+                break;
+            }
+            case 'sleep.until': {
+                const view = stepOf(event);
+                enter(view, 'backoff');
+                view.backoff_until_ms = integer(payload['wake_at_ms']) ?? event.at_ms;
+                break;
+            }
+            case 'wait.event': {
+                const view = stepOf(event);
+                enter(view, 'waiting');
+                view.wait = { wait_id: text(payload['wait_id']), kind: 'event', timeout_at_ms: integer(payload['timeout_at_ms']) };
+                break;
+            }
+            case 'wait.human': {
+                const view = stepOf(event);
+                enter(view, 'needs_human');
+                view.wait = { wait_id: text(payload['wait_id']), kind: 'human', timeout_at_ms: integer(payload['timeout_at_ms']) };
+                break;
+            }
+            case 'wait.completed': {
+                const view = stepOf(event);
+                if (payload['completionReason'] === 'canceled') {
+                    enter(view, 'done');
+                    view.last_attempt = view.last_attempt ?? {
+                        attempt: view.attempt, completion_reason: 'canceled', disposition: 'step_done',
+                        verification: null, human_intervention: false, effects: 0, ended_at_ms: event.at_ms,
+                        transcript: null,
+                    };
+                    view.completion_reason = 'canceled';
+                }
+                else {
+                    enter(view, 'runnable');
+                }
+                break;
+            }
+            case 'epoch.summary': {
+                // A new epoch restarts every step (state.rs `apply_epoch`); the
+                // summary then restores the ones it carries forward.
+                for (const step of steps.values()) {
+                    const { id, type, max_iterations } = step.view;
+                    step.view = freshStep(id, type, max_iterations, step.depends_on).view;
+                }
+                spend = addSpend(ZERO_SPEND, payload['budget_spent']);
+                const done = payload['steps_done'] !== null && typeof payload['steps_done'] === 'object' ? payload['steps_done'] : {};
+                for (const [id, summary] of Object.entries(done)) {
+                    const view = steps.get(id)?.view;
+                    if (view === undefined)
+                        throw new RunStateError(`Epoch summary names unknown step ${JSON.stringify(id)}.`);
+                    enter(view, 'done');
+                    // `StepDoneSummary` (kernel entry.rs) carries `completionReason` and
+                    // nothing else about the attempt. Keep the reason, which dependency
+                    // readiness and the glyph need; invent no attempt record around it.
+                    const facts = summary !== null && typeof summary === 'object' ? summary : {};
+                    view.completion_reason = text(facts['completionReason'], 'unknown');
+                }
+                const open = payload['steps_open'] !== null && typeof payload['steps_open'] === 'object' ? payload['steps_open'] : {};
+                for (const [id, summary] of Object.entries(open)) {
+                    const view = steps.get(id)?.view;
+                    if (view === undefined)
+                        throw new RunStateError(`Epoch summary names unknown step ${JSON.stringify(id)}.`);
+                    const facts = summary !== null && typeof summary === 'object' ? summary : {};
+                    view.attempt = integer(facts['attempt']) ?? 0;
+                    const state = facts['state'];
+                    if (state === 'running') {
+                        enter(view, 'running');
+                        // The summary carries no original attempt start, and the kernel
+                        // does not track one. Stamping the epoch's own time here made the
+                        // live `attempt-<n>.*.tail` header look stale to
+                        // `readTranscriptTail` and restarted elapsed at the compaction.
+                        // Unknown is the honest value: elapsed goes unrendered and the
+                        // tail's staleness check is skipped rather than failed.
+                        view.started_at_ms = null;
+                        view.lease = { deadline_ms: integer(facts['lease_deadline_ms']) ?? event.at_ms, overdue_ms: 0 };
+                    }
+                    else if (state === 'backoff') {
+                        enter(view, 'backoff');
+                        view.backoff_until_ms = integer(facts['wake_at_ms']) ?? event.at_ms;
+                    }
+                    else if (state === 'needs_human') {
+                        enter(view, 'needs_human');
+                        view.wait = { wait_id: `epoch-${integer(payload['epoch']) ?? 0}-${id}`, kind: 'human', timeout_at_ms: null };
+                    }
+                    else if (state === 'waiting') {
+                        enter(view, 'waiting');
+                        view.wait = { wait_id: text(facts['wait_id']), kind: 'event', timeout_at_ms: null };
+                    }
+                }
+                break;
+            }
+            case 'run.completed':
+                completion = text(payload['completionReason'], 'unknown');
+                spend = addSpend(ZERO_SPEND, payload['budget_total']);
+                break;
+            case 'run.cancel.requested':
+                cancelRequested = true;
+                break;
+            default:
+                // Routing, subscriptions, channels, streams, effects, memory and
+                // segment records change nothing a status view shows.
+                break;
+        }
+    }
+    // state.rs `refresh_runnable`: a pending step whose dependencies all
+    // succeeded is runnable, whether or not a worker has picked it up.
+    for (const step of steps.values()) {
+        if (step.view.state !== 'pending')
+            continue;
+        const ready = step.depends_on.every((dependency) => {
+            const upstream = steps.get(dependency)?.view;
+            return upstream?.state === 'done' && upstream.completion_reason === 'success';
+        });
+        if (ready)
+            step.view.state = 'runnable';
+    }
+    const views = [];
+    const counts = { total: 0, done: 0, running: 0, pending: 0, backoff: 0, waiting: 0, needs_human: 0 };
+    for (const { view } of steps.values()) {
+        if (view.started_at_ms !== null) {
+            // `ended_at_ms` belongs to the attempt that ended. A retry, wait or
+            // sleep starts a newer attempt whose `started_at_ms` is later than that,
+            // and measuring to the older end clamped a live wait's elapsed to zero.
+            const ended = view.last_attempt?.ended_at_ms ?? null;
+            const end = ended === null || ended < view.started_at_ms ? now_ms : ended;
+            view.elapsed_ms = Math.max(0, (view.state === 'running' ? now_ms : end) - view.started_at_ms);
+        }
+        if (view.lease !== null)
+            view.lease.overdue_ms = Math.max(0, now_ms - view.lease.deadline_ms);
+        counts.total += 1;
+        if (view.state === 'pending' || view.state === 'runnable')
+            counts.pending += 1;
+        else
+            counts[view.state] += 1;
+        views.push(view);
+    }
+    const status = completion === null
+        ? cancelRequested ? 'cancelling' : counts.needs_human > 0 ? 'parked' : 'running'
+        : completion === 'success' ? 'completed' : completion === 'canceled' ? 'cancelled' : 'failed';
+    return {
+        run_id: first.run_id,
+        name: text(spec['name'], first.run_id),
+        status,
+        completion_reason: completion,
+        spawned_at_ms: first.at_ms,
+        now_ms,
+        spend,
+        counts,
+        steps: views,
+    };
+}
+//# sourceMappingURL=run-state.js.map