@skrr-ai/cli 0.1.22 → 0.1.23

package/dist/lib/agentic-stream.js

@@ -1,15 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgenticStreamClient = void 0;
+exports.AgenticStreamClient = exports.USER_CONNECTION_CAP_CODE = void 0;
+exports.writeJsonLine = writeJsonLine;
 exports.envelopesText = envelopesText;
 exports.envelopeKey = envelopeKey;
 exports.unseenEnvelopes = unseenEnvelopes;
+exports.projectDaemonToolEvents = projectDaemonToolEvents;
+exports.renderableDelta = renderableDelta;
+exports.transportRefusal = transportRefusal;
+exports.transportRefusalMessage = transportRefusalMessage;
+exports.attachDeadlineFor = attachDeadlineFor;
+exports.jitteredRetryDelay = jitteredRetryDelay;
+exports.detectSeqGap = detectSeqGap;
+exports.seqGapNotice = seqGapNotice;
 exports.toWebSocketOrigin = toWebSocketOrigin;
 const node_readline_1 = require("node:readline");
 const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const config_1 = require("./config");
 const publicEndpoints_generated_1 = require("./publicEndpoints.generated");
+/**
+ * Write exactly one complete JSON value on one line.
+ *
+ * `--jsonl` is the mode automation parses, and its whole contract is one JSON
+ * value per physical line. Two things break that if the line is composed by
+ * hand: a raw newline inside a string (a multi-line agent answer or tool
+ * output) splits one record across many unparseable lines, and routing the line
+ * through oclif's `this.log` puts it through `util.format`, which rewrites `%s`
+ * / `%d` / `%j` sequences that appear in ordinary shell output. `JSON.stringify`
+ * escapes the first and this helper avoids the second by writing to the stream
+ * directly, so every JSONL line in the CLI is produced in one place and cannot
+ * drift (OSK-7629).
+ */
+function writeJsonLine(output, value) {
+    output.write(`${JSON.stringify(value) ?? 'null'}\n`);
+}
 /**
  * Small Node-side adapter for the existing Agentic Socket.IO contract.
  * It deliberately normalizes only lifecycle/text/tool events; the server's
@@ -86,6 +111,162 @@ function unseenEnvelopes(event, seen) {
     }
     return fresh;
 }
+/**
+ * Project daemon `tool-call-start` / `tool-call-end` envelopes into the same
+ * `tool.started` / `tool.completed` events a cloud run emits.
+ *
+ * The CLI used to emit tool events only for cloud-executed turns: a run on a
+ * local harness produced three shell commands and ZERO tool events, in both
+ * `--jsonl` and the human rendering, while the envelopes carrying them arrived
+ * intact inside `session:output` (OSK-7730). Automation counting tool calls
+ * concluded a local run used no tools; a human watching one saw nothing at all
+ * while commands ran on their own machine (OSK-7773 is the same absence on the
+ * web). The harness a turn lands on is a routing decision and must not change
+ * the event vocabulary.
+ *
+ * `tool-call-end` carries no tool name, so the name is correlated on `call`
+ * (the tool-use id) through `namesByCall`, which the caller keeps for the life
+ * of the run. The pairing is unambiguous within a turn.
+ */
+function projectDaemonToolEvents(envelopes, namesByCall) {
+    const out = [];
+    for (const envelope of envelopes) {
+        const ev = envelope?.ev;
+        if (!ev || typeof ev.t !== 'string')
+            continue;
+        const call = typeof ev.call === 'string' ? ev.call : undefined;
+        if (ev.t === 'tool-call-start') {
+            const name = typeof ev.name === 'string' ? ev.name : undefined;
+            if (call && name)
+                namesByCall.set(call, name);
+            out.push({
+                type: 'tool.started',
+                ...(call ? { toolUseId: call } : {}),
+                ...(name ? { toolName: name } : {}),
+                ...(ev.args !== undefined ? { toolInput: ev.args } : {}),
+            });
+        }
+        else if (ev.t === 'tool-call-end') {
+            const name = call ? namesByCall.get(call) : undefined;
+            out.push({
+                type: 'tool.completed',
+                ...(call ? { toolUseId: call } : {}),
+                ...(name ? { toolName: name } : {}),
+                ...(ev.output !== undefined ? { toolResponse: ev.output } : {}),
+                ...(typeof ev.status === 'string' ? { status: ev.status } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The part of a cumulative snapshot that has not been shown yet.
+ *
+ * The stream carries CUMULATIVE text, and the plain renderer used to redraw
+ * each snapshot after a bare carriage return. `\r` returns the cursor to column
+ * 0 of the CURRENT line only — it cannot rewind past a newline — so the repaint
+ * was correct exactly while the answer was one line, and every snapshot after
+ * the model's first `\n` stranded the previous snapshot's earlier lines on
+ * screen. One two-line answer printed its first paragraph sixteen times
+ * (OSK-7731); another printed the answer twice and fused it into tokens the
+ * agent never wrote, `HOSTHOST=e2b.local` (OSK-7701).
+ *
+ * Printing only the new suffix needs no cursor control at all, which also makes
+ * it correct when stdout is a file or a pipe — where nothing consumes `\r` and
+ * the redirected capture looked worse than the screen.
+ *
+ * Returns the text to append, and the new "already shown" watermark. A snapshot
+ * that is not an extension of what was shown (a stream reset, or a server that
+ * rewrote the answer) is emitted whole on a fresh line rather than diffed.
+ */
+function renderableDelta(shown, snapshot) {
+    if (snapshot === shown)
+        return { append: '', shown };
+    if (snapshot.startsWith(shown))
+        return { append: snapshot.slice(shown.length), shown: snapshot };
+    return { append: `\n${snapshot}`, shown: snapshot };
+}
+/** The user-connection cap, as `userConnectionTracking.js` names it. */
+exports.USER_CONNECTION_CAP_CODE = 'user_connection_cap';
+function positiveInt(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+function transportRefusal(error) {
+    const data = error?.data;
+    if (!data || typeof data !== 'object')
+        return { retryable: false };
+    const code = typeof data.code === 'string' && data.code ? data.code : undefined;
+    const connectionClass = typeof data.connectionClass === 'string' && data.connectionClass
+        ? data.connectionClass
+        : undefined;
+    return {
+        ...(code ? { code } : {}),
+        ...(connectionClass ? { connectionClass } : {}),
+        ...(positiveInt(data.limit) !== undefined ? { limit: positiveInt(data.limit) } : {}),
+        ...(positiveInt(data.retryAfterMs) !== undefined
+            ? { retryAfterMs: positiveInt(data.retryAfterMs) }
+            : {}),
+        // Only an explicit `true`. An unknown refusal must not be retried forever.
+        retryable: data.retryable === true,
+    };
+}
+/**
+ * The sentence a person can act on, built from whatever the refusal carried.
+ *
+ * Degrades one clause at a time: an older server that sends no `data` still
+ * gets its own message back unchanged, which is exactly today's behaviour and
+ * no worse.
+ */
+function transportRefusalMessage(message, refusal) {
+    const parts = [String(message || 'The stream was refused').trim()];
+    if (refusal.limit !== undefined) {
+        parts.push(`The limit is ${refusal.limit} concurrent ${refusal.connectionClass ?? 'client'} connection${refusal.limit === 1 ? '' : 's'} per account, shared by every open \`skrr\` session and browser tab you have.`);
+    }
+    if (refusal.retryAfterMs !== undefined) {
+        parts.push(`Retrying in ${Math.round(refusal.retryAfterMs / 1000)}s.`);
+    }
+    else if (refusal.retryable) {
+        parts.push('Retrying.');
+    }
+    // The fact that matters most and was never said: the run is already accepted.
+    parts.push('The run was already accepted and keeps executing either way.');
+    return parts.join(' ');
+}
+/**
+ * How long a refusal is worth waiting out.
+ *
+ * The default 30s attach deadline is exactly the server's own
+ * `WS_USER_CAP_RETRY_AFTER_MS`, so a client honouring the retry contract on the
+ * default budget gives up in the same instant it is allowed to try again. The
+ * window is widened to cover the retry plus a connect, and only when the server
+ * named a delay.
+ */
+function attachDeadlineFor(timeoutMs, refusal) {
+    if (!refusal.retryable || refusal.retryAfterMs === undefined)
+        return timeoutMs;
+    return Math.max(timeoutMs, refusal.retryAfterMs + 15_000);
+}
+/** Jitter, so a fleet refused together does not return together. */
+function jitteredRetryDelay(retryAfterMs, random = Math.random) {
+    return Math.round(retryAfterMs * (1 + random() * 0.25));
+}
+function detectSeqGap(highestApplied, incoming) {
+    if (!Number.isFinite(incoming) || incoming <= 0)
+        return null;
+    // The FIRST envelope is a gap when it is not seq 1 — that is the reported
+    // case, and a `> highestApplied + 1` test alone would miss it, because
+    // nothing has been applied yet.
+    if (incoming <= highestApplied + 1)
+        return null;
+    return { from: highestApplied + 1, to: incoming - 1 };
+}
+function seqGapNotice(gap) {
+    const count = gap.to - gap.from + 1;
+    return (`[${count} stream chunk${count === 1 ? '' : 's'} (seq ${gap.from}` +
+        `${count === 1 ? '' : `-${gap.to}`}) never arrived — the text above is incomplete. ` +
+        'The full answer is in the persisted message and in run.result.]');
+}
 class AgenticStreamClient {
     options;
     socket = null;
@@ -94,13 +275,48 @@ class AgenticStreamClient {
     settled = false;
     closed = false;
     accumulated = '';
+    /** Highest envelope `__seq` folded into `accumulated`, for gap detection. */
+    highestSeq = 0;
+    reportedGap = false;
     // Envelope keys already applied, so a re-delivered `session:output` frame is
     // not appended twice (OSK-4834). Cleared on `execution:stream-reset`.
     seenEnvelopes = new Set();
+    /**
+     * Lifecycle events already emitted, by their own identity (OSK-7632/7689/7709).
+     *
+     * `session:output` envelopes are deduped by `envelopeKey`, but the lifecycle
+     * events do not ride an envelope and were exempt: one turn delivered
+     * `run.started` four times byte-identically (76% of a 70KB stream), and one
+     * Bash execution arrived as four `tool.started` events sharing one
+     * `toolUseId`. Anything counting tool calls from the stream — a timeline, a
+     * usage display, an audit log — reported four sandbox commands where one ran.
+     * The server fans one broadcast to several rooms the client is in, so the
+     * repeat count varies run to run and cannot be inferred by a consumer.
+     */
+    seenLifecycle = new Set();
+    /** `call` → tool name, so a daemon `tool-call-end` can be named (OSK-7730). */
+    toolNamesByCall = new Map();
+    /** Text already written to the terminal, for suffix-only rendering. */
+    renderedText = '';
+    idleTimer = null;
+    reconciling = false;
     responseMessageId;
     lastEvent;
+    /**
+     * The terminal result, once there is one.
+     *
+     * `run()`'s promise is the normal way to read it, but a caller that raced
+     * `run()` against its own detach has already discarded that promise by the
+     * time {@link probeTerminal} settles it. Keeping the value here is what lets
+     * a reconciled detach report the real outcome instead of the detach.
+     */
+    terminalResult = null;
     resolve;
     reject;
+    /** The terminal result, or null while the run is still in flight. */
+    settledResult() {
+        return this.terminalResult;
+    }
     constructor(options) {
         this.options = options;
     }
@@ -131,8 +347,71 @@ class AgenticStreamClient {
         await this.waitForConnect();
         this.socket.emit('session:join', { sessionId: this.options.sessionId });
         this.emit({ type: 'session.joined', sessionId: this.options.sessionId });
+        this.armIdleProbe();
         return result;
     }
+    /**
+     * (Re)start the silence watchdog that asks the durable record what happened.
+     *
+     * Armed on join and reset by every event, so it only fires when the stream
+     * has actually gone quiet. A probe that finds the turn still running re-arms
+     * rather than giving up — a 200-second tool call is silence, not a failure —
+     * so the cost of being wrong is one cheap read, while the cost of not asking
+     * was an interactive session that never returned.
+     */
+    armIdleProbe() {
+        if (!this.options.reconcileTerminal)
+            return;
+        if (this.settled || this.closed)
+            return;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => void this.probeTerminal('idle'), this.options.idleTerminalProbeMs ?? 20_000);
+        this.idleTimer.unref?.();
+    }
+    /**
+     * Settle from the durable record, if it has reached a terminal state.
+     *
+     * Public so the caller can force one before declaring a detach: a run that
+     * finished 13 seconds ago must not be reported as "may still be executing"
+     * (OSK-7660).
+     */
+    async probeTerminal(reason) {
+        const reconcile = this.options.reconcileTerminal;
+        if (!reconcile || this.settled || this.reconciling)
+            return false;
+        this.reconciling = true;
+        let terminal = null;
+        try {
+            terminal = await reconcile();
+        }
+        catch {
+            // A failed probe is not evidence about the run. Keep waiting.
+            terminal = null;
+        }
+        finally {
+            this.reconciling = false;
+        }
+        if (this.settled)
+            return true;
+        if (!terminal) {
+            this.armIdleProbe();
+            return false;
+        }
+        // The record is the witness the stream refused to be, so say so: the
+        // recorded reason is exactly what "the surface shows nothing at all" cost
+        // the reader (OSK-7595 — the CLI reported a transport error while the run's
+        // own recorded failure said something else entirely).
+        this.finish(terminal.status === 'failed' ? 'failed' : 'completed', {
+            type: 'run.reconciled',
+            sessionId: this.options.sessionId,
+            reconciledFrom: 'durable_record',
+            reason,
+            ...(terminal.error ? { message: terminal.error, error: terminal.error } : {}),
+            ...(typeof terminal.text === 'string' ? { result: terminal.text } : {}),
+        });
+        return true;
+    }
     cancel(reason = 'Interrupted by user') {
         if (this.settled || !this.socket)
             return;
@@ -148,6 +427,10 @@ class AgenticStreamClient {
         if (this.closed)
             return;
         this.closed = true;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
         const socket = this.socket;
         this.socket = null;
         // Stop dispatch BEFORE tearing anything down. socket.io can deliver a
@@ -167,6 +450,34 @@ class AgenticStreamClient {
         this.readline?.close();
         this.readline = null;
     }
+    /**
+     * Report the first hole in the live envelope sequence, once.
+     *
+     * Once, not per gap: a stream that has already lost its beginning tends to
+     * lose more, and one honest sentence is the useful form of that. The terminal
+     * result is authoritative and reconciled separately, so this never changes
+     * what the run reports — only what the reader is told while it is happening.
+     */
+    reportSeqGap(envelopes) {
+        for (const envelope of envelopes) {
+            const seq = Number(envelope?.__seq);
+            if (!Number.isFinite(seq) || seq <= 0)
+                continue;
+            const gap = detectSeqGap(this.highestSeq, seq);
+            if (gap && !this.reportedGap) {
+                this.reportedGap = true;
+                this.emit({
+                    type: 'stream.gap',
+                    sessionId: this.options.sessionId,
+                    fromSeq: gap.from,
+                    toSeq: gap.to,
+                    message: seqGapNotice(gap),
+                });
+            }
+            if (seq > this.highestSeq)
+                this.highestSeq = seq;
+        }
+    }
     installHandlers() {
         const socket = this.socket;
         const match = (event) => !event.sessionId || event.sessionId === this.options.sessionId;
@@ -175,19 +486,35 @@ class AgenticStreamClient {
             this.emit({ type: 'transport.connected', sessionId: this.options.sessionId });
         });
         socket.on('disconnect', (reason) => {
-            if (!this.settled)
-                this.emit({ type: 'transport.disconnected', sessionId: this.options.sessionId, reason });
+            if (this.settled)
+                return;
+            this.emit({ type: 'transport.disconnected', sessionId: this.options.sessionId, reason });
+            // Losing the view is not evidence the run stopped — but it IS the moment
+            // to ask the record, because a turn refused at admission publishes its
+            // reason there and nowhere else.
+            void this.probeTerminal('transport_disconnected');
         });
         socket.on('connect_error', (error) => {
-            if (!this.settled)
-                this.emit({
-                    type: 'transport.error',
-                    sessionId: this.options.sessionId,
-                    message: error.message,
-                });
+            if (this.settled)
+                return;
+            // Everything the server said, not just the sentence (OSK-7663).
+            const refusal = transportRefusal(error);
+            this.emit({
+                type: 'transport.error',
+                sessionId: this.options.sessionId,
+                message: transportRefusalMessage(error.message, refusal),
+                ...(refusal.code ? { code: refusal.code } : {}),
+                ...(refusal.limit !== undefined ? { limit: refusal.limit } : {}),
+                ...(refusal.retryAfterMs !== undefined ? { retryAfterMs: refusal.retryAfterMs } : {}),
+                ...(refusal.connectionClass ? { connectionClass: refusal.connectionClass } : {}),
+                retryable: refusal.retryable,
+            });
+            void this.probeTerminal('transport_error');
         });
         socket.on('session:init', (event) => {
-            if (match(event))
+            // One run starts once. The server fans this to several rooms the client
+            // has joined, and the repeats are byte-identical (OSK-7689/7709).
+            if (match(event) && this.firstTimeSeen('run.started', this.options.sessionId))
                 this.emit({ ...event, type: 'run.started' });
         });
         socket.on('message:stream', (event) => {
@@ -228,11 +555,20 @@ class AgenticStreamClient {
                 if (fresh.length === 0)
                     return; // a pure re-delivery — drop it whole
                 const scoped = { ...event, envelopes: fresh };
+                // Say what never arrived, once, before folding this batch in
+                // (OSK-7631). Checked against the FRESH set: a re-delivery carries old
+                // seqs and would read as a gap that never happened.
+                this.reportSeqGap(fresh);
                 const envelopeText = envelopesText(scoped);
                 if (envelopeText) {
                     this.accumulated += envelopeText;
                     this.emit({ ...scoped, type: 'text.delta', text: this.accumulated });
                 }
+                // A daemon-routed turn carries its tool calls HERE and nowhere else.
+                // Projecting them gives both execution paths one vocabulary (OSK-7730).
+                for (const projected of projectDaemonToolEvents(fresh, this.toolNamesByCall)) {
+                    this.emitToolEvent({ ...projected, sessionId: this.options.sessionId });
+                }
                 this.emit({ ...scoped, type: 'session.output' });
                 return;
             }
@@ -240,11 +576,11 @@ class AgenticStreamClient {
         });
         socket.on('tool:start', (event) => {
             if (match(event))
-                this.emit({ ...event, type: 'tool.started' });
+                this.emitToolEvent({ ...event, type: 'tool.started' });
         });
         socket.on('tool:end', (event) => {
             if (match(event))
-                this.emit({ ...event, type: 'tool.completed' });
+                this.emitToolEvent({ ...event, type: 'tool.completed' });
         });
         socket.on('execution:enqueue', (event) => {
             if (match(event))
@@ -254,13 +590,23 @@ class AgenticStreamClient {
             if (!match(event))
                 return;
             this.accumulated = '';
+            this.renderedText = '';
+            // Seqs restart with the stream, so a fresh low seq is not a gap.
+            this.highestSeq = 0;
+            this.reportedGap = false;
             // A reset restarts the stream, so envelope seqs may repeat; forget the
             // seen keys or the fresh post-reset text would be deduped away (OSK-4834).
             this.seenEnvelopes.clear();
+            this.seenLifecycle.clear();
             this.emit({ ...event, type: 'text.reset' });
         });
         socket.on('message:stream-end', (event) => {
-            if (match(event))
+            if (!match(event))
+                return;
+            // Byte-identical repeats, including `endedAt` (OSK-7689). Key on the
+            // message the stream ended for, falling back to the session.
+            const key = String(event.messageId ?? event.endedAt ?? this.options.sessionId);
+            if (this.firstTimeSeen('text.completed', key))
                 this.emit({ ...event, type: 'text.completed' });
         });
         socket.on('execution:complete', (event) => {
@@ -349,32 +695,83 @@ class AgenticStreamClient {
         }
         return new Promise((resolve) => this.readline.question(prompt, resolve));
     }
+    /**
+     * True the first time this (kind, identity) pair is seen; false afterwards.
+     * The identity is the event's OWN — a tool-use id, a message id — never a
+     * position in the stream, because the repeat count varies run to run.
+     */
+    firstTimeSeen(kind, identity) {
+        if (!identity)
+            return true; // no identity to dedupe on — treat as new
+        const key = `${kind}|${identity}`;
+        if (this.seenLifecycle.has(key))
+            return false;
+        this.seenLifecycle.add(key);
+        return true;
+    }
+    /**
+     * Emit a tool event once per tool invocation.
+     *
+     * Deduped on `toolUseId`, which both paths carry and which is the invocation's
+     * real identity: four byte-identical `tool.started` events for one Bash call
+     * all shared it (OSK-7632). An event with no id cannot be deduped and is
+     * passed through, preserving prior behaviour.
+     */
+    emitToolEvent(event) {
+        const id = typeof event.toolUseId === 'string' ? event.toolUseId : undefined;
+        if (!this.firstTimeSeen(String(event.type), id))
+            return;
+        this.emit(event);
+    }
     emit(event) {
         this.lastEvent = event;
         this.options.onEvent?.(event);
+        // Any event is proof the stream is alive; the watchdog only fires on real
+        // silence.
+        this.armIdleProbe();
         // Accumulation and `onEvent` still run — only the incremental rendering is
         // suppressed, so a quiet run is the same turn with a different display.
         if (this.options.quiet)
             return;
+        const output = this.options.output ?? process.stdout;
         if (this.options.jsonl) {
-            (this.options.output ?? process.stdout).write(`${JSON.stringify(event)}\n`);
+            writeJsonLine(output, event);
             return;
         }
-        const output = this.options.output ?? process.stdout;
         if (event.type === 'text.delta' && typeof event.text === 'string') {
-            output.write(`\r${event.text}`);
+            // Print what is NEW. See `renderableDelta` — the old `\r` repaint could
+            // not rewind past a newline, so a multi-line answer was reprinted once
+            // per snapshot and its blocks fused (OSK-7701, OSK-7731).
+            const { append, shown } = renderableDelta(this.renderedText, event.text);
+            this.renderedText = shown;
+            if (append)
+                output.write(append);
         }
         else if (event.type === 'tool.started') {
             output.write(`\n[tool] ${String(event.toolName ?? 'unknown')}\n`);
+            // The banner moved the cursor to a fresh line, so nothing of the answer
+            // is on screen after it: the next snapshot must be printed from where the
+            // text left off, not from column 0 of a line that no longer holds it.
+            this.renderedText = this.accumulated;
         }
         else if (event.type === 'tool.completed') {
             output.write(`[tool completed] ${String(event.toolName ?? 'unknown')}\n`);
+            this.renderedText = this.accumulated;
+        }
+        else if (event.type === 'stream.gap') {
+            // Said WHILE READING, which is the only moment it helps: a truncated
+            // live answer looks like a complete short answer, and by the terminal
+            // event the reader has already believed it (OSK-7631).
+            output.write(`\n${String(event.message ?? '')}\n`);
+            this.renderedText = this.accumulated;
         }
         else if (event.type === 'transport.disconnected') {
             output.write(`\n[reconnecting] ${String(event.reason ?? '')}\n`);
+            this.renderedText = this.accumulated;
         }
         else if (event.type === 'permission.requested' || event.type === 'question.requested') {
             output.write(`\n[${event.type}]\n`);
+            this.renderedText = this.accumulated;
         }
     }
     finish(status, event) {
@@ -393,26 +790,41 @@ class AgenticStreamClient {
         // agent's actual final message rather than however much of it arrived in
         // time.
         const finalText = typeof event.result === 'string' ? event.result : '';
-        if (finalText && finalText !== this.accumulated) {
-            const hadPartial = this.accumulated.length > 0;
+        // …EXCEPT when it is a strict suffix of what we accumulated.
+        //
+        // On the cloud path `result` carries only the LAST text block, not the fold
+        // of all of them: an answer that spoke, ran three tools, then spoke again
+        // arrived complete in the stream and in the database, and `run.result`
+        // dropped the opening block the user had explicitly asked for — reporting
+        // `status: completed` (OSK-7703). A single-part answer hides it entirely,
+        // because with one block the last block IS the answer. Taking the longer of
+        // the two when one contains the other is right for both defects: the
+        // truncated-stream case (result longer) and the last-block case
+        // (accumulation longer).
+        const accumulationIsSuperset = finalText.length > 0 &&
+            this.accumulated.length > finalText.length &&
+            this.accumulated.endsWith(finalText);
+        if (finalText && finalText !== this.accumulated && !accumulationIsSuperset) {
             this.accumulated = finalText;
-            // Repaint the line so the terminal ends on the whole answer instead of
-            // the fragment the last delta happened to leave there.
-            if (!this.options.quiet && !this.options.jsonl && hadPartial) {
-                (this.options.output ?? process.stdout).write(`\r${finalText}`);
-            }
         }
-        if (!this.options.quiet && !this.options.jsonl && this.accumulated)
-            (this.options.output ?? process.stdout).write('\n');
+        if (!this.options.quiet && !this.options.jsonl && this.accumulated) {
+            const output = this.options.output ?? process.stdout;
+            const { append, shown } = renderableDelta(this.renderedText, this.accumulated);
+            this.renderedText = shown;
+            if (append)
+                output.write(append);
+            output.write('\n');
+        }
         this.emit({ ...event, type: `run.${status}` });
         this.close();
-        this.resolve({
+        this.terminalResult = {
             sessionId: this.options.sessionId,
             responseMessageId: this.responseMessageId,
             text: this.accumulated,
             status,
             lastEvent: event,
-        });
+        };
+        this.resolve(this.terminalResult);
     }
     /**
      * OSK-2944 — a transient connect failure must not end an ACCEPTED run.
@@ -436,21 +848,66 @@ class AgenticStreamClient {
         return new Promise((resolve, reject) => {
             const socket = this.socket;
             let lastError = null;
-            const timer = setTimeout(() => {
-                cleanup();
-                reject(Object.assign(new Error(`Could not attach to the run stream within ${Math.round(timeoutMs / 1000)}s` +
-                    `${lastError ? `: ${lastError.message}` : ''}`), { code: 'STREAM_ATTACH_TIMEOUT', lastError }));
-            }, timeoutMs);
+            let deadline = timeoutMs;
+            let retryTimer = null;
+            let retried = false;
+            let timer = armDeadline(deadline);
+            function armDeadline(ms) {
+                const handle = setTimeout(() => {
+                    cleanup();
+                    reject(Object.assign(new Error(`Could not attach to the run stream within ${Math.round(ms / 1000)}s` +
+                        `${lastError ? `: ${lastError.message}` : ''}`), { code: 'STREAM_ATTACH_TIMEOUT', lastError }));
+                }, ms);
+                handle.unref?.();
+                return handle;
+            }
             const onConnect = () => {
                 cleanup();
                 resolve();
             };
-            // Report and keep waiting — socket.io is already retrying underneath.
             const onError = (error) => {
                 lastError = error;
+                // ── HONOUR THE RETRY CONTRACT (OSK-7583/7588/7604/7663) ─────────────
+                //
+                // "socket.io is already retrying underneath" is true for a TRANSPORT
+                // failure and false for a MIDDLEWARE refusal, which is what the
+                // connection cap is: `userConnectionTracking.js` says so in its own
+                // words — Socket.IO destroys a socket that fails middleware and does
+                // not reconnect it, and every first-party client is expected to
+                // schedule one retry after the stated delay, jittered. The CLI was not
+                // one, so a cap refusal ended an accepted run and the user never saw an
+                // answer the server had already produced.
+                //
+                // ONE retry, on the server's own clock, and only when it said the
+                // refusal was retryable.
+                const refusal = transportRefusal(error);
+                if (!refusal.retryable || refusal.retryAfterMs === undefined || retried)
+                    return;
+                retried = true;
+                // The default deadline IS the server's retry delay, so without widening
+                // it the client gives up in the same instant it is allowed to try.
+                const widened = attachDeadlineFor(deadline, refusal);
+                if (widened > deadline) {
+                    clearTimeout(timer);
+                    deadline = widened;
+                    timer = armDeadline(deadline);
+                }
+                retryTimer = setTimeout(() => {
+                    retryTimer = null;
+                    try {
+                        socket.connect();
+                    }
+                    catch {
+                        // The deadline above is the backstop; a failed reconnect attempt
+                        // must not reject here and turn a pause into a failure.
+                    }
+                }, jitteredRetryDelay(refusal.retryAfterMs));
+                retryTimer.unref?.();
             };
             const cleanup = () => {
                 clearTimeout(timer);
+                if (retryTimer)
+                    clearTimeout(retryTimer);
                 socket.off('connect', onConnect);
                 socket.off('connect_error', onError);
             };