ai-runtime-engine 2.7.0 → 2.8.0

package/dist/agents/worker.js

@@ -21,8 +21,24 @@ import { flattenClamp } from '../util/flatten.js';
 import { admitFindings, contractFailed } from './admit.js';
 import { executionCoverage } from './finding.js';
 import { AGENT_TASK_PROJECTION, nextAgentTaskId } from './task.js';
+import { hashOf } from '../util/hash.js';
+import { validatePlan } from '../orchestration/plan.js';
 /** How much of a step input may reach the inner prompt. It is model-authored, and it is fenced. */
 export const AGENT_INPUT_MAX = 1000;
+/** Inner observations persisted per task. The record lives in a JSON file that is rewritten every
+ *  commit, so this is a durability bound, not a display one. Beyond it, the count is kept and the
+ *  content dropped — an honest "there was more" rather than a silently short list. */
+export const INNER_OBS_MAX = 20;
+/** Admission rejections kept per task. They accumulate across attempts and are rewritten every commit. */
+export const DIAGNOSTICS_KEPT = 50;
+/**
+ * What makes a step THIS step. Plan step ids (`s1`, `auto1`) are model-authored and recur across
+ * replans, so binding a persisted record by id alone would hand one step's completed inner work to a
+ * different step that happens to share its id — same agent, different input, silently wrong findings.
+ */
+export function stepIdentity(step) {
+    return hashOf({ agent: step.agent, description: step.description, input: step.input ?? null });
+}
 /** Raised by the metered facade when an agent tries to exceed its reservation. */
 class AgentCallBudgetError extends Error {
     constructor() {
@@ -32,19 +48,49 @@ class AgentCallBudgetError extends Error {
 }
 export async function runAgentTask(step, envelope, definition, deps) {
     const now = deps.clock.now();
-    const record = {
+    // Computed from what is TRUE NOW, so a persisted record can be compared against the run it is about
+    // to be reused in. Reading them off the resumed record instead would compare a value with itself.
+    const defHash = hashOf(definition);
+    const envHash = hashOf(envelope);
+    const record = deps.resume ?? {
+        v: 1,
         agentTaskId: nextAgentTaskId(now),
         agentId: envelope.agentId,
         stepId: step.id,
         state: 'created',
         createdAt: now,
+        updatedAt: now,
+        provenance: deps.provenance,
+        // The three identity hashes. They are computed HERE, at the only place a task is minted, so a
+        // resumed record can be compared against the run it is about to be reused in (Phase 3.5).
+        agentDefHash: defHash,
+        envelopeHash: envHash,
+        stepInputHash: stepIdentity(step),
+        attempt: 1,
+        innerCompletedSteps: [],
+        innerObservations: [],
+        innerObservationsOmitted: 0,
         innerSteps: { total: 0, succeeded: 0 },
+        callsReserved: envelope.reservation,
         callsUsed: 0,
+        callsRefunded: 0,
         toolCallsUsed: 0,
         findings: [],
         diagnostics: [],
     };
+    if (deps.resume) {
+        // A resumed record starts a NEW attempt: findings it mints are namespaced by the attempt number, so
+        // they can never collide with findings already on the record from the attempt that was interrupted.
+        record.attempt += 1;
+        // The stamp must describe the LATEST interruption, so it is cleared on promotion, not left to age.
+        delete record.interruption;
+        // The question has been answered (or the task is being retried); either way it is no longer pending,
+        // and leaving it set would re-elect this task as the run's wait on the very next commit.
+        delete record.pendingInner;
+    }
     record.state = 'queued';
+    record.updatedAt = deps.clock.now();
+    deps.onRecord?.(record);
     // (2) A child controller, so a parent abort reaches the inner run and nothing else does.
     const child = new AbortController();
     const onParentAbort = () => child.abort();
@@ -56,10 +102,15 @@ export async function runAgentTask(step, envelope, definition, deps) {
     const expired = () => deps.clock.now() > deadline;
     // (3) THE METERED FACADE. Prototype-delegating, so it IS an AI (assignable to SkillContext.ai) while
     // owning `run`. The count increments BEFORE the await, so a failed inner call is still charged.
+    // Prior spend carries across a resume: the reservation is the ceiling for the TASK, not per attempt,
+    // so a task that already burned 2 of 3 calls before a crash gets 1 more, not 3.
+    const priorCalls = deps.resume?.callsUsed ?? 0;
+    const priorToolCalls = deps.resume?.toolCallsUsed ?? 0;
     let calls = 0;
+    const spent = () => priorCalls + calls;
     const metered = Object.create(deps.ai);
     metered.run = async (req) => {
-        if (calls >= envelope.reservation)
+        if (spent() >= envelope.reservation)
             throw new AgentCallBudgetError();
         calls += 1;
         return deps.ai.run(req);
@@ -71,8 +122,12 @@ export async function runAgentTask(step, envelope, definition, deps) {
         deps.parentSignal?.removeEventListener('abort', onParentAbort);
         record.state = state;
         record.endedAt = deps.clock.now();
-        record.callsUsed = calls;
-        record.toolCallsUsed = toolCalls;
+        record.updatedAt = record.endedAt;
+        record.callsUsed = priorCalls + calls;
+        record.toolCallsUsed = priorToolCalls + toolCalls;
+        // Derived, for reporting only. The real refund is that the executor charges what was SPENT, so the
+        // unspent part of the reservation is simply never charged — there is no ledger to get wrong.
+        record.callsRefunded = Math.max(0, record.callsReserved - record.callsUsed);
         if (failure)
             record.failure = failure;
         const row = AGENT_TASK_PROJECTION[state];
@@ -88,6 +143,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
             ...(state === 'completed' ? { output: `${envelope.agentId}: ${record.innerSteps.succeeded}/${record.innerSteps.total} inner step(s), ${record.findings.length} finding(s)` } : {}),
         };
         deps.emit?.({ type: 'agent.task.completed', record });
+        deps.onRecord?.(record);
         return { observation, record };
     };
     // (12) A parent abort is a cancel or a pause; both project to the same observation, and the record
@@ -108,13 +164,15 @@ export async function runAgentTask(step, envelope, definition, deps) {
         return preempted;
     record.state = 'running';
     record.startedAt = deps.clock.now();
+    record.updatedAt = record.startedAt;
     deps.emit?.({ type: 'agent.task.started', record });
+    deps.onRecord?.(record);
     // (6) THE TOOL SEAM - defense in depth behind narrowEnvelope. Always a structured denial, never a
     // throw: the tool contract is that a refusal is visible.
     const innerCallTool = async (id, input) => {
         if (!envelope.tools.includes(id))
             return { ok: false, error: { code: 'PERMISSION', message: `'${flattenClamp(id, 40)}' is not in this agent's catalog` } };
-        if (toolCalls + 1 > envelope.maxToolCalls)
+        if (priorToolCalls + toolCalls + 1 > envelope.maxToolCalls)
             return { ok: false, error: { code: 'PERMISSION', message: `agent tool-call budget exhausted (${envelope.maxToolCalls})` } };
         if (expired())
             return { ok: false, error: { code: 'TIMEOUT', message: 'agent time budget exhausted' } };
@@ -127,20 +185,59 @@ export async function runAgentTask(step, envelope, definition, deps) {
     const innerGoal = [
         envelope.objective,
         wrapUntrusted(`agent-input:${envelope.agentId}`, flattenClamp(JSON.stringify(step.input ?? null), AGENT_INPUT_MAX)),
+        // The answer to THIS task's own question, routed here rather than appended to the outer goal —
+        // appending it there would replan the outer plan and discard every sibling agent's work.
+        ...(deps.resumeAnswer ? [wrapUntrusted(`agent-answer:${envelope.agentId}`, flattenClamp(deps.resumeAnswer, AGENT_INPUT_MAX))] : []),
     ].join('\n\n');
-    let planned;
-    try {
-        planned = await generatePlan({ goal: innerGoal, ai: metered, skills: deps.skills, tools: envelope.tools, agents: [], version: 1, ...(envelope.routing ? { routing: envelope.routing } : {}) });
-    }
-    catch (err) {
-        if (err instanceof AgentCallBudgetError)
-            return finish('failed', { code: 'agent-call-budget', message: err.message });
-        return finish('failed', { code: 'agent-failed', message: flattenClamp(err instanceof Error ? err.message : String(err), 160) });
+    // A persisted inner plan is REUSED rather than regenerated — that is what makes a resume cheap and
+    // what stops completed inner work being redone. It is still re-validated against the envelope's
+    // catalog first: the plan came off disk, and `validatePlan` is the membership gate for every plan,
+    // resumed or fresh. A plan that no longer validates is discarded, not repaired.
+    let innerPlan;
+    const identical = deps.resume ? deps.resume.envelopeHash === envHash && deps.resume.agentDefHash === defHash : false;
+    // An ANSWER changes what the plan should be — that is the entire point of having asked — so a task
+    // being resumed with one always re-plans rather than replaying the plan made before the question.
+    if (deps.resume?.innerPlan && identical && !deps.resumeAnswer) {
+        const check = validatePlan(deps.resume.innerPlan, { skills: envelope.skills, tools: envelope.tools, agents: [] });
+        if (check.ok)
+            innerPlan = deps.resume.innerPlan;
     }
-    if (!planned.plan) {
-        return finish('failed', { code: 'agent-failed', message: flattenClamp(planned.error ?? planned.clarification ?? 'the agent could not form a plan', 160) });
+    // The record now belongs to THIS run: an edited definition or a re-narrowed envelope invalidates the
+    // old plan (handled above) but not the task, so the hashes move forward with it.
+    record.agentDefHash = defHash;
+    record.envelopeHash = envHash;
+    if (!innerPlan) {
+        let planned;
+        try {
+            planned = await generatePlan({ goal: innerGoal, ai: metered, skills: deps.skills, tools: envelope.tools, agents: [], version: 1, ...(envelope.routing ? { routing: envelope.routing } : {}) });
+        }
+        catch (err) {
+            if (err instanceof AgentCallBudgetError)
+                return finish('failed', { code: 'agent-call-budget', message: err.message });
+            return finish('failed', { code: 'agent-failed', message: flattenClamp(err instanceof Error ? err.message : String(err), 160) });
+        }
+        if (planned.clarification) {
+            // The one inner wait that exists: the planner needs an answer. The task stays RESUMABLE and the
+            // step stays pending — this is not a failure, and it must not fail the branch.
+            record.pendingInner = { kind: 'clarification', question: flattenClamp(planned.clarification, 240), at: deps.clock.now() };
+            return finish('waiting_for_clarification', { code: 'agent-waiting', message: record.pendingInner.question });
+        }
+        if (!planned.plan) {
+            return finish('failed', { code: 'agent-failed', message: flattenClamp(planned.error ?? 'the agent could not form a plan', 160) });
+        }
+        innerPlan = planned.plan;
+        // A REGENERATED plan has new step ids. Carrying the discarded plan's completed ids into its skip
+        // set would mark steps `succeeded` that never ran — the dangerous direction of a resume, since the
+        // work is silently not done rather than merely done twice.
+        record.innerCompletedSteps = [];
+        record.innerObservations = [];
+        record.innerObservationsOmitted = 0;
     }
-    record.innerPlanVersion = planned.plan.version;
+    record.innerPlan = innerPlan;
+    record.innerPlanVersion = innerPlan.version;
+    // The plan exists and nothing has run: a crash from here on resumes against a real inner plan.
+    record.updatedAt = deps.clock.now();
+    deps.onRecord?.(record);
     const aborted = abortedNow();
     if (aborted)
         return aborted;
@@ -150,7 +247,22 @@ export async function runAgentTask(step, envelope, definition, deps) {
     // a skill's own model calls, which a wave gate cannot see.
     let inner;
     try {
-        inner = await executePlan(planned.plan, {
+        inner = await executePlan(innerPlan, {
+            skip: new Set(record.innerCompletedSteps),
+            // THE seam that makes inner work survive a crash. Everything between `running` and `finish()` was
+            // otherwise invisible to disk, so a resumed task had nothing to skip and re-ran the whole inner plan.
+            onProgress: (snap) => {
+                record.innerPlan = snap.plan;
+                record.innerCompletedSteps = snap.plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                const room = INNER_OBS_MAX - record.innerObservations.length;
+                if (room > 0)
+                    record.innerObservations.push(...snap.observations.slice(0, room));
+                record.innerObservationsOmitted += Math.max(0, snap.observations.length - Math.max(0, room));
+                record.callsUsed = priorCalls + calls;
+                record.toolCallsUsed = priorToolCalls + toolCalls;
+                record.updatedAt = deps.clock.now();
+                deps.onRecord?.(record);
+            },
             runSkill: async (id, i) => {
                 const out = await deps.runSkill(id, i, { permissions: envelope.permissions, signal: child.signal, ai: metered });
                 skillResults.push({ stepId: id, result: out.result, validation: out.validation });
@@ -171,6 +283,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
         return finish('failed', { code: 'agent-failed', message: flattenClamp(err instanceof Error ? err.message : String(err), 160) });
     }
     record.innerSteps = { total: inner.plan.steps.length, succeeded: inner.plan.steps.filter((s) => s.status === 'succeeded').length };
+    record.innerCompletedSteps = inner.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
     const afterRun = abortedNow();
     if (afterRun)
         return afterRun;
@@ -239,8 +352,16 @@ export async function runAgentTask(step, envelope, definition, deps) {
         provenance: deps.provenance,
         now: deps.clock.now(),
     });
-    record.findings = [...denials, ...admission.admitted];
-    record.diagnostics = admission.rejected;
+    // MERGE, never assign. A resumed attempt that admits fewer findings than the interrupted one would
+    // otherwise drop the earlier ones on the floor — and observations already committed to disk reference
+    // them by id. Attempt >1 namespaces its ids so the two attempts can never collide.
+    const mint = (f) => (record.attempt > 1 ? { ...f, id: `${f.id}@a${record.attempt}` } : f);
+    const fresh = [...denials, ...admission.admitted].map(mint);
+    const seenFinding = new Set(record.findings.map((f) => f.id));
+    record.findings = [...record.findings, ...fresh.filter((f) => !seenFinding.has(f.id))];
+    // Bounded: diagnostics accumulate across attempts, and every one of them is rewritten to disk on
+    // every commit. Keeping the most recent is the useful half.
+    record.diagnostics = [...record.diagnostics, ...admission.rejected].slice(-DIAGNOSTICS_KEPT);
     if (contractFailed(admission)) {
         return finish('failed', { code: 'finding-contract', message: 'the agent did not satisfy its declared output contract' });
     }

package/dist/cli/cli.js

@@ -21,7 +21,7 @@ import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestC
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.7.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.8.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.

package/dist/cli/interactive/lanes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Multi-lane agent display (Phase 3.6) — concurrent agent steps as live rows in the REPL.
+ *
+ * PURE BY CONSTRUCTION. Nothing here reads `process.stdout`, a clock, or an environment variable: the
+ * terminal width, whether colour is on, and every value rendered are parameters. That is what makes a
+ * terminal feature testable offline and deterministically, and it is the rule to keep — the moment this
+ * module reads the real terminal, its tests start describing the machine they ran on.
+ *
+ * WRAPPING IS MADE IMPOSSIBLE RATHER THAN HANDLED. In-place rewriting works by moving the cursor up N
+ * rows, which is only correct while one logical line occupies exactly one physical row. So every line is
+ * clamped to `cols - 1`: no line ever reaches the final column, nothing wraps, and the arithmetic is
+ * exact. Lines are built as plain text, clamped, and styled last, so the clamp never has to count
+ * invisible escape bytes.
+ */
+import type { RuntimeEvent } from '../../runtime/events.js';
+export interface AgentLane {
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    /** `running` covers started + progress; the terminal states come from the completion event. */
+    state: 'running' | 'completed' | 'failed' | 'cancelled' | 'waiting';
+    succeeded: number;
+    total: number;
+    callsUsed: number;
+    findings: number;
+}
+/** Display width in terminal columns, not code units. */
+export declare function displayWidth(text: string): number;
+/** Truncate to `cols` display columns, never splitting a surrogate pair or half a wide glyph. */
+export declare function sliceColumns(text: string, cols: number): string;
+/**
+ * Accumulates agent lanes from the event stream. Insertion-ordered, so lanes do not jump around between
+ * frames — a display that reorders itself is unreadable even when every value in it is right.
+ */
+export declare class LaneSet {
+    private readonly lanes;
+    /**
+     * Fold one event in. Returns the lane it touched, or `undefined` for an event that is not an agent
+     * event — a lane rather than a boolean, so the caller neither re-narrows the event nor looks the lane
+     * up a second time.
+     */
+    observe(event: RuntimeEvent): AgentLane | undefined;
+    list(): AgentLane[];
+    /** True once at least one lane exists and none is still in flight. */
+    settled(): boolean;
+    clear(): void;
+}
+/**
+ * Render the lanes as one line each. `tick` animates the running marker; it is a parameter rather than a
+ * timer so a test can render frame 3 without waiting for it.
+ */
+export declare function laneLines(lanes: AgentLane[], opts: {
+    cols: number;
+    colors: boolean;
+    tick: number;
+}): string[];
+/**
+ * Rewrite an owned region of the terminal in place, returning the bytes to write.
+ *
+ * `prevRows === 0` opens the region at the cursor's current line. Otherwise the cursor is assumed to be
+ * on the region's LAST row (which is where this function always leaves it) and walks up from there.
+ *
+ * The cursor never ends on a fresh line below the frame: a trailing newline on the terminal's last row
+ * scrolls the viewport, and the next frame's `cursorUp` would then land one row high and duplicate the
+ * region on every tick, forever.
+ */
+export declare function frameDiff(prevRows: number, lines: string[], enabled: boolean): string;
+/** How many rows `frameDiff` will have left behind — the `prevRows` for the next call. */
+export declare function frameRows(lines: string[]): number;

package/dist/cli/interactive/lanes.js

@@ -0,0 +1,181 @@
+/**
+ * Multi-lane agent display (Phase 3.6) — concurrent agent steps as live rows in the REPL.
+ *
+ * PURE BY CONSTRUCTION. Nothing here reads `process.stdout`, a clock, or an environment variable: the
+ * terminal width, whether colour is on, and every value rendered are parameters. That is what makes a
+ * terminal feature testable offline and deterministically, and it is the rule to keep — the moment this
+ * module reads the real terminal, its tests start describing the machine they ran on.
+ *
+ * WRAPPING IS MADE IMPOSSIBLE RATHER THAN HANDLED. In-place rewriting works by moving the cursor up N
+ * rows, which is only correct while one logical line occupies exactly one physical row. So every line is
+ * clamped to `cols - 1`: no line ever reaches the final column, nothing wraps, and the arithmetic is
+ * exact. Lines are built as plain text, clamped, and styled last, so the clamp never has to count
+ * invisible escape bytes.
+ */
+import { style, SPINNER_FRAMES } from './ansi.js';
+import { flattenClamp } from '../../util/flatten.js';
+const CLEAR_LINE = '\x1b[2K';
+/**
+ * East Asian Wide and Fullwidth code points, which a terminal draws in TWO columns. The no-wrap
+ * invariant is stated in COLUMNS, so counting UTF-16 code units would let a CJK step id — and step ids
+ * are model-authored — produce a line that measures 79 and draws 95, wrapping and breaking every
+ * cursor-up that follows it.
+ */
+function isWide(cp) {
+    return ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, punctuation
+        (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana .. CJK compatibility
+        (cp >= 0x3400 && cp <= 0x4dbf) ||
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK unified ideographs
+        (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xf900 && cp <= 0xfaff) ||
+        (cp >= 0xfe30 && cp <= 0xfe6f) ||
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1f64f) || // emoji
+        (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+        (cp >= 0x20000 && cp <= 0x3fffd));
+}
+/** Display width in terminal columns, not code units. */
+export function displayWidth(text) {
+    let n = 0;
+    for (const ch of text)
+        n += isWide(ch.codePointAt(0)) ? 2 : 1;
+    return n;
+}
+/** Truncate to `cols` display columns, never splitting a surrogate pair or half a wide glyph. */
+export function sliceColumns(text, cols) {
+    let out = '';
+    let used = 0;
+    for (const ch of text) {
+        const w = isWide(ch.codePointAt(0)) ? 2 : 1;
+        if (used + w > cols)
+            break;
+        out += ch;
+        used += w;
+    }
+    return out;
+}
+const cursorUp = (n) => (n > 0 ? `\x1b[${n}A` : '');
+/** Which lane state an agent-task state projects onto. Anything unrecognised reads as still running. */
+function laneState(state) {
+    if (state === 'completed' || state === 'failed' || state === 'cancelled')
+        return state;
+    if (state.startsWith('waiting'))
+        return 'waiting';
+    return 'running';
+}
+/**
+ * Accumulates agent lanes from the event stream. Insertion-ordered, so lanes do not jump around between
+ * frames — a display that reorders itself is unreadable even when every value in it is right.
+ */
+export class LaneSet {
+    lanes = new Map();
+    /**
+     * Fold one event in. Returns the lane it touched, or `undefined` for an event that is not an agent
+     * event — a lane rather than a boolean, so the caller neither re-narrows the event nor looks the lane
+     * up a second time.
+     */
+    observe(event) {
+        if (!event.type.startsWith('agent.task.'))
+            return undefined;
+        const e = event;
+        const existing = this.lanes.get(e.agentTaskId);
+        const lane = existing ?? {
+            agentTaskId: e.agentTaskId,
+            agentId: e.agentId,
+            stepId: e.stepId,
+            state: 'running',
+            succeeded: 0,
+            total: 0,
+            callsUsed: 0,
+            findings: 0,
+        };
+        if ('innerSteps' in e) {
+            lane.total = e.innerSteps.total;
+            lane.succeeded = e.innerSteps.succeeded;
+        }
+        if ('callsUsed' in e)
+            lane.callsUsed = e.callsUsed;
+        if ('findings' in e)
+            lane.findings = e.findings;
+        if ('state' in e)
+            lane.state = laneState(e.state);
+        this.lanes.set(e.agentTaskId, lane);
+        return lane;
+    }
+    list() {
+        return [...this.lanes.values()];
+    }
+    /** True once at least one lane exists and none is still in flight. */
+    settled() {
+        const all = this.list();
+        return all.length > 0 && all.every((l) => l.state !== 'running');
+    }
+    clear() {
+        this.lanes.clear();
+    }
+}
+const MARK = { running: '', completed: '✓', failed: '✗', cancelled: '−', waiting: '?' };
+const TINT = {
+    running: 'cyan',
+    completed: 'green',
+    failed: 'red',
+    cancelled: 'gray',
+    waiting: 'yellow',
+};
+/**
+ * Render the lanes as one line each. `tick` animates the running marker; it is a parameter rather than a
+ * timer so a test can render frame 3 without waiting for it.
+ */
+export function laneLines(lanes, opts) {
+    // `|| 80` not `?? 80`: a pty can report ZERO columns, and zero is not nullish. And the floor is 1,
+    // not 20 — raising the width for a narrow terminal MAKES it wrap, which is the failure this clamp
+    // exists to prevent.
+    const width = Math.max(1, (opts.cols || 80) - 1);
+    return lanes.map((l) => {
+        const mark = l.state === 'running' ? SPINNER_FRAMES[opts.tick % SPINNER_FRAMES.length] : MARK[l.state];
+        const progress = l.total > 0 ? `${l.succeeded}/${l.total}` : '…';
+        const found = l.findings > 0 ? `, ${l.findings} finding(s)` : '';
+        // Built plain, clamped, THEN styled — so the clamp never counts escape bytes.
+        const plain = `  ${mark} ${flattenClamp(l.agentId, 24)} @ ${flattenClamp(l.stepId, 16)}  ${progress} step(s), ${l.callsUsed} call(s)${found}`;
+        return style(sliceColumns(plain, width), TINT[l.state], opts.colors);
+    });
+}
+/**
+ * Rewrite an owned region of the terminal in place, returning the bytes to write.
+ *
+ * `prevRows === 0` opens the region at the cursor's current line. Otherwise the cursor is assumed to be
+ * on the region's LAST row (which is where this function always leaves it) and walks up from there.
+ *
+ * The cursor never ends on a fresh line below the frame: a trailing newline on the terminal's last row
+ * scrolls the viewport, and the next frame's `cursorUp` would then land one row high and duplicate the
+ * region on every tick, forever.
+ */
+export function frameDiff(prevRows, lines, enabled) {
+    if (!enabled)
+        return '';
+    const rows = Math.max(prevRows, lines.length);
+    if (rows === 0)
+        return '';
+    let out = '\r';
+    if (prevRows > 0)
+        out += cursorUp(prevRows - 1);
+    for (let i = 0; i < rows; i += 1) {
+        out += CLEAR_LINE + (lines[i] ?? '');
+        if (i < rows - 1)
+            out += '\n';
+    }
+    // Drew fewer rows than last time: the cursor sits on a cleared row below the frame, so walk back up
+    // to the real last line, keeping the "cursor is on the last row" invariant true for the next call.
+    // CLOSING the region (`lines` empty) has no last line, so the target is the region's TOP row — which
+    // is one higher than the shrink case, and the reason this is `max(1, …)` rather than `lines.length`.
+    if (rows > lines.length)
+        out += `\r${cursorUp(rows - Math.max(1, lines.length))}`;
+    return out;
+}
+/** How many rows `frameDiff` will have left behind — the `prevRows` for the next call. */
+export function frameRows(lines) {
+    return lines.length;
+}