@skrr-ai/cli 0.1.85 → 0.1.87

package/dist/lib/agentic-stream.d.ts

@@ -20,6 +20,12 @@ export type AgenticStreamResult = {
     responseMessageId?: string;
     text: string;
     status: 'completed' | 'aborted' | 'failed';
+    /**
+     * The run first failed as handed over (a deploy replaced the relaying server)
+     * and the machine's completed reply was then repaired onto the record
+     * (OSK-13543). Absent on every ordinary run.
+     */
+    repaired?: true;
     lastEvent?: AgenticStreamEvent;
 };
 /**
@@ -45,7 +51,82 @@ export type ReconciledTerminal = {
     text?: string;
     /** The recorded failure reason — `metadata.agentic.error` on the message. */
     error?: string;
+    /**
+     * The failure is a hand-over, not an ending (OSK-13543): the row is failed
+     * with {@link DAEMON_HANDOVER_REASON}, which the server itself treats as
+     * "outcome pending the machine's own turn-end".
+     */
+    handedOver?: boolean;
+};
+/**
+ * OSK-13517 / OSK-13543 — the one failure that is not an ending.
+ *
+ * A deploy replaced the server RELAYING a local-daemon turn while the daemon
+ * kept running it. The server saves the turn `error: true` with this reason
+ * (`metadata.agentic.errorSubtype`), keeps the conversation quarantined, and
+ * converges the row later from the machine's own turn-end: completed →
+ * repaired (`error: false`, `metadata.agentic.deliveryRepair`), anything else →
+ * settled failed (`errorSubtype: worker_replaced_daemon_failed`).
+ *
+ * Mirrors `WORKER_REPLACED_DAEMON_RUNNING_REASON` in
+ * `api/server/services/AgentWorker/workerReplacedNotice.js` and the code
+ * beside it in `daemonHandlers.js` / `conversationAdmissionClaim.js`; a parity
+ * spec reads those files so the two cannot drift.
+ */
+export declare const WORKER_REPLACED_CODE = "AGENT_WORKER_REPLACED";
+export declare const DAEMON_HANDOVER_REASON = "worker_replaced_daemon_running";
+/**
+ * Is this terminal event the hand-over failure, and nothing else?
+ *
+ * The server sends it on two paths with different shapes, so the reason is
+ * read wherever either puts it:
+ *   - the QueueEvents backstop (`queue.js`): `{code: 'AGENT_WORKER_REPLACED',
+ *     errorType: 'worker_replaced_daemon_running', errors}`;
+ *   - the worker's own result (`buildExecutionErrorEvent`): `errorType` and
+ *     `reason` both carry the daemon reason, `code` only when the result had one.
+ * The plain deploy failure shares the CODE (`errorType: 'worker_replaced'`, the
+ * turn really ended), so the code alone must never qualify, and a code that
+ * is present but different disqualifies.
+ */
+export declare function isDaemonHandoverFailure(event: Record<string, unknown> | null | undefined): boolean;
+/** What the durable record says about a handed-over turn, read while waiting. */
+export type HandoverReading = 
+/** Still failed with the hand-over reason, or not yet written: keep waiting. */
+{
+    state: 'pending';
+}
+/** The machine finished and the server repaired the row. */
+ | {
+    state: 'repaired';
+    text: string;
+    repairedAt?: string;
+}
+/** The machine's turn ended without finishing, and the server settled it so. */
+ | {
+    state: 'failed';
+    error: string;
+    text?: string;
+};
+export type HandoverWaitOptions = {
+    /** Read the persisted response message. A throw or null is "no evidence". */
+    read: () => Promise<HandoverReading | null>;
+    /** The response message the repair notification names. */
+    responseMessageId?: string;
+    conversationId?: string;
+    /** How long to wait for the machine's reply. 0 disables the wait. */
+    maxWaitMs: number;
+    /** Fallback re-read cadence when no notification arrives. Default 15s. */
+    pollIntervalMs?: number;
+    /**
+     * Where the human status line goes when stdout is reserved for the final
+     * result (`--no-stream`). Default stderr.
+     */
+    statusOutput?: NodeJS.WritableStream;
 };
+/** Default fallback re-read cadence while waiting on a handed-over turn. */
+export declare const HANDOVER_POLL_INTERVAL_MS = 15000;
+/** `600000` → `10m`, `90000` → `1m30s`, `45000` → `45s`. */
+export declare function formatWaitDuration(ms: number): string;
 /**
  * Write exactly one complete JSON value on one line.
  *
@@ -106,6 +187,12 @@ export type AgenticStreamOptions = {
      * owns that stream and its contract does not include diagnostics.
      */
     debug?: (line: string) => void;
+    /**
+     * OSK-13543 — wait for a handed-over local-daemon turn instead of ending on
+     * its failure. See {@link isDaemonHandoverFailure}. Omitted: today's
+     * behaviour, every `execution:error` settles the run at once.
+     */
+    awaitHandover?: HandoverWaitOptions;
     /** Silence before the first durable-record probe. Default 20s. */
     idleTerminalProbeMs?: number;
     /** How long to keep trying to attach before reporting a detach. Default 30s. */
@@ -493,6 +580,11 @@ export declare class AgenticStreamClient {
      * a reconciled detach report the real outcome instead of the detach.
      */
     private terminalResult;
+    /**
+     * A handed-over turn being waited on (OSK-13543): the failure event that
+     * started the wait, and the timers bounding it. Null otherwise.
+     */
+    private handover;
     private resolve;
     private reject;
     /** The terminal result, or null while the run is still in flight. */
@@ -542,6 +634,44 @@ export declare class AgenticStreamClient {
     probeTerminal(reason: string): Promise<boolean>;
     cancel(reason?: string): void;
     close(): void;
+    /**
+     * True while a handed-over turn is being waited on (OSK-13543). A Ctrl-C in
+     * this state stops the wait; it cannot cancel the machine's turn.
+     */
+    awaitingHandover(): boolean;
+    /**
+     * OSK-13543 — the run failed because a deploy replaced the server relaying a
+     * turn the machine is still running. That failure is the server's PROVISIONAL
+     * verdict: it keeps the conversation held and rewrites the row from the
+     * machine's own turn-end. Ending here told a CLI user "failed" about a turn
+     * whose answer the web showed ninety seconds later.
+     *
+     * So keep the stream, the user-room subscription and the envelope replay
+     * open, and settle on what the RECORD converges to: repaired → completed,
+     * settled failed → failed with the machine's reason, neither within the
+     * bound → the original failure. The record, not the notification, decides:
+     * a notification only says "read again", so a lost or duplicated one costs
+     * at most a poll interval.
+     *
+     * Returns false (and changes nothing) when the run cannot wait: no hand-over
+     * reader configured, a zero bound, or a run already settling.
+     */
+    private beginHandoverWait;
+    /** Ask the record again; coalesces with a read already in flight. */
+    private requestHandoverRead;
+    /** One read of the record. True when it settled the run. */
+    private readHandover;
+    /** The bound ran out: one last look, then the original failure. */
+    private expireHandover;
+    private stopHandoverTimers;
+    private endHandover;
+    /**
+     * The server's "this row was rewritten" notice (`lateDeliveryRepair`
+     * `notifyViewersMessageRewritten`), delivered to every socket of the user
+     * through the `user:<id>` room this socket joins on connect. A hint to read,
+     * never a verdict.
+     */
+    private onConversationUpdate;
     private debug;
     /**
      * Record a hole being passed over — the moment replay has given up on it.
@@ -622,6 +752,11 @@ export declare class AgenticStreamClient {
      */
     private emitToolEvent;
     private emit;
+    /**
+     * Human-mode lines for the hand-over wait. Returns true when the event is
+     * fully rendered here; false lets the ordinary rendering continue.
+     */
+    private renderHandoverStatus;
     private finish;
     private finishAfterReplay;
     /**

package/dist/lib/agentic-stream.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgenticStreamClient = exports.USER_CONNECTION_CAP_CODE = exports.CODEX_DECLINED_TOOL_OUTPUTS = exports.TYPE_AHEAD_DISCARD_MS = exports.NON_INTERACTIVE_QUESTION_DISMISSAL = void 0;
+exports.AgenticStreamClient = exports.USER_CONNECTION_CAP_CODE = exports.CODEX_DECLINED_TOOL_OUTPUTS = exports.TYPE_AHEAD_DISCARD_MS = exports.HANDOVER_POLL_INTERVAL_MS = exports.DAEMON_HANDOVER_REASON = exports.WORKER_REPLACED_CODE = exports.NON_INTERACTIVE_QUESTION_DISMISSAL = void 0;
+exports.isDaemonHandoverFailure = isDaemonHandoverFailure;
+exports.formatWaitDuration = formatWaitDuration;
 exports.writeJsonLine = writeJsonLine;
 exports.discardTypeAhead = discardTypeAhead;
 exports.describePermissionTarget = describePermissionTarget;
@@ -41,6 +43,54 @@ const dpop_auth_1 = require("./dpop-auth");
  */
 exports.NON_INTERACTIVE_QUESTION_DISMISSAL = 'No answer: this turn was started non-interactively (no terminal), so nobody can reply to ' +
     'questions. Proceed with your best judgement, or finish by stating exactly what you need.';
+/**
+ * OSK-13517 / OSK-13543 — the one failure that is not an ending.
+ *
+ * A deploy replaced the server RELAYING a local-daemon turn while the daemon
+ * kept running it. The server saves the turn `error: true` with this reason
+ * (`metadata.agentic.errorSubtype`), keeps the conversation quarantined, and
+ * converges the row later from the machine's own turn-end: completed →
+ * repaired (`error: false`, `metadata.agentic.deliveryRepair`), anything else →
+ * settled failed (`errorSubtype: worker_replaced_daemon_failed`).
+ *
+ * Mirrors `WORKER_REPLACED_DAEMON_RUNNING_REASON` in
+ * `api/server/services/AgentWorker/workerReplacedNotice.js` and the code
+ * beside it in `daemonHandlers.js` / `conversationAdmissionClaim.js`; a parity
+ * spec reads those files so the two cannot drift.
+ */
+exports.WORKER_REPLACED_CODE = 'AGENT_WORKER_REPLACED';
+exports.DAEMON_HANDOVER_REASON = 'worker_replaced_daemon_running';
+/**
+ * Is this terminal event the hand-over failure, and nothing else?
+ *
+ * The server sends it on two paths with different shapes, so the reason is
+ * read wherever either puts it:
+ *   - the QueueEvents backstop (`queue.js`): `{code: 'AGENT_WORKER_REPLACED',
+ *     errorType: 'worker_replaced_daemon_running', errors}`;
+ *   - the worker's own result (`buildExecutionErrorEvent`): `errorType` and
+ *     `reason` both carry the daemon reason, `code` only when the result had one.
+ * The plain deploy failure shares the CODE (`errorType: 'worker_replaced'`, the
+ * turn really ended), so the code alone must never qualify, and a code that
+ * is present but different disqualifies.
+ */
+function isDaemonHandoverFailure(event) {
+    if (!event)
+        return false;
+    if (event.code !== undefined && event.code !== exports.WORKER_REPLACED_CODE)
+        return false;
+    return [event.errorType, event.reason, event.daemonReason].includes(exports.DAEMON_HANDOVER_REASON);
+}
+/** Default fallback re-read cadence while waiting on a handed-over turn. */
+exports.HANDOVER_POLL_INTERVAL_MS = 15_000;
+/** `600000` → `10m`, `90000` → `1m30s`, `45000` → `45s`. */
+function formatWaitDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    if (!minutes)
+        return `${seconds}s`;
+    return seconds ? `${minutes}m${seconds}s` : `${minutes}m`;
+}
 /**
  * Write exactly one complete JSON value on one line.
  *
@@ -745,6 +795,11 @@ class AgenticStreamClient {
      * a reconciled detach report the real outcome instead of the detach.
      */
     terminalResult = null;
+    /**
+     * A handed-over turn being waited on (OSK-13543): the failure event that
+     * started the wait, and the timers bounding it. Null otherwise.
+     */
+    handover = null;
     resolve;
     reject;
     /** The terminal result, or null while the run is still in flight. */
@@ -833,6 +888,11 @@ class AgenticStreamClient {
             return;
         if (this.settled || this.closed)
             return;
+        // While a handed-over turn is waited on, the record reads `error: true` BY
+        // DESIGN — it is the failure being waited out. The generic probe would
+        // settle on exactly that; the hand-over reader owns the record instead.
+        if (this.handover)
+            return;
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
         this.idleTimer = setTimeout(() => void this.probeTerminal('idle'), this.options.idleTerminalProbeMs ?? 20_000);
@@ -846,7 +906,7 @@ class AgenticStreamClient {
      */
     async probeTerminal(reason) {
         const reconcile = this.options.reconcileTerminal;
-        if (!reconcile || this.settled || this.reconciling)
+        if (!reconcile || this.settled || this.reconciling || this.handover)
             return false;
         this.reconciling = true;
         let terminal = null;
@@ -866,6 +926,23 @@ class AgenticStreamClient {
             this.armIdleProbe();
             return false;
         }
+        // The stream never delivered the hand-over failure (joined late, or the
+        // frame was lost), but the record carries it: wait the same way. Not on a
+        // detach — the caller has already stopped watching and asks only what the
+        // record says now.
+        if (terminal.handedOver && reason !== 'detach') {
+            const begun = this.beginHandoverWait({
+                type: 'execution:error',
+                sessionId: this.options.sessionId,
+                code: exports.WORKER_REPLACED_CODE,
+                errorType: exports.DAEMON_HANDOVER_REASON,
+                reason: exports.DAEMON_HANDOVER_REASON,
+                reconciledFrom: 'durable_record',
+                ...(terminal.error ? { message: terminal.error, errors: [terminal.error] } : {}),
+            });
+            if (begun)
+                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
@@ -883,6 +960,11 @@ class AgenticStreamClient {
     cancel(reason = 'Interrupted by user') {
         if (this.settled || !this.socket)
             return;
+        // A handed-over turn has no relaying server left to carry an interrupt to
+        // the machine, so sending one would claim a cancel nothing performs. The
+        // caller stops WAITING instead ({@link awaitingHandover}).
+        if (this.handover)
+            return;
         this.cancelled = true;
         this.socket.emit('execution:interrupt', {
             sessionId: this.options.sessionId,
@@ -902,6 +984,7 @@ class AgenticStreamClient {
         if (this.replayTimer)
             clearTimeout(this.replayTimer);
         this.replayTimer = null;
+        this.stopHandoverTimers();
         this.pendingEnvelopes.clear();
         this.abandonConnectWait?.();
         const socket = this.socket;
@@ -923,6 +1006,189 @@ class AgenticStreamClient {
         this.readline?.close();
         this.readline = null;
     }
+    /**
+     * True while a handed-over turn is being waited on (OSK-13543). A Ctrl-C in
+     * this state stops the wait; it cannot cancel the machine's turn.
+     */
+    awaitingHandover() {
+        return this.handover !== null && !this.settled && !this.closed;
+    }
+    /**
+     * OSK-13543 — the run failed because a deploy replaced the server relaying a
+     * turn the machine is still running. That failure is the server's PROVISIONAL
+     * verdict: it keeps the conversation held and rewrites the row from the
+     * machine's own turn-end. Ending here told a CLI user "failed" about a turn
+     * whose answer the web showed ninety seconds later.
+     *
+     * So keep the stream, the user-room subscription and the envelope replay
+     * open, and settle on what the RECORD converges to: repaired → completed,
+     * settled failed → failed with the machine's reason, neither within the
+     * bound → the original failure. The record, not the notification, decides:
+     * a notification only says "read again", so a lost or duplicated one costs
+     * at most a poll interval.
+     *
+     * Returns false (and changes nothing) when the run cannot wait: no hand-over
+     * reader configured, a zero bound, or a run already settling.
+     */
+    beginHandoverWait(event) {
+        const opts = this.options.awaitHandover;
+        if (!opts || !(opts.maxWaitMs > 0))
+            return false;
+        if (this.settled || this.closed || this.finishingReplay || this.cancelled)
+            return false;
+        if (this.handover)
+            return true;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        const startedAt = Date.now();
+        // Deliberately NOT unref'd, for the reason `armIdleProbe` gives: an
+        // unsettled run is a reason to stay alive (OSK-10061).
+        const deadlineTimer = setTimeout(() => void this.expireHandover(), opts.maxWaitMs);
+        const pollTimer = setInterval(() => this.requestHandoverRead(), opts.pollIntervalMs ?? exports.HANDOVER_POLL_INTERVAL_MS);
+        this.handover = { event, startedAt, deadlineTimer, pollTimer, reading: null, readAgain: false };
+        const firstError = Array.isArray(event.errors) && typeof event.errors[0] === 'string'
+            ? event.errors[0]
+            : undefined;
+        const message = typeof event.message === 'string' && event.message ? event.message : firstError;
+        this.emit({
+            type: 'run.handed_over',
+            sessionId: this.options.sessionId,
+            code: exports.WORKER_REPLACED_CODE,
+            reason: exports.DAEMON_HANDOVER_REASON,
+            ...(message ? { message } : {}),
+            ...(opts.responseMessageId ? { responseMessageId: opts.responseMessageId } : {}),
+            waitMs: opts.maxWaitMs,
+            deadlineAt: new Date(startedAt + opts.maxWaitMs).toISOString(),
+        });
+        // The repair can land before the failure notice reaches us (the queue's
+        // backstop records and settles in one pass), so look once right away.
+        this.requestHandoverRead();
+        return true;
+    }
+    /** Ask the record again; coalesces with a read already in flight. */
+    requestHandoverRead() {
+        const handover = this.handover;
+        if (!handover || this.settled || this.closed)
+            return;
+        if (handover.reading) {
+            handover.readAgain = true;
+            return;
+        }
+        handover.reading = this.readHandover().finally(() => {
+            if (this.handover !== handover)
+                return;
+            handover.reading = null;
+            if (handover.readAgain) {
+                handover.readAgain = false;
+                this.requestHandoverRead();
+            }
+        });
+    }
+    /** One read of the record. True when it settled the run. */
+    async readHandover() {
+        const handover = this.handover;
+        const read = this.options.awaitHandover?.read;
+        if (!handover || !read)
+            return false;
+        let reading = null;
+        try {
+            reading = await read();
+        }
+        catch {
+            // A failed read is no evidence about the turn; the next trigger retries.
+            reading = null;
+        }
+        if (this.handover !== handover || this.settled || this.closed)
+            return false;
+        if (!reading || reading.state === 'pending')
+            return false;
+        const waitedMs = Date.now() - handover.startedAt;
+        this.endHandover();
+        if (reading.state === 'repaired') {
+            this.finish('completed', {
+                type: 'execution:complete',
+                sessionId: this.options.sessionId,
+                result: reading.text,
+                repaired: true,
+                repairedFrom: 'durable_record',
+                overturned: { code: exports.WORKER_REPLACED_CODE, reason: exports.DAEMON_HANDOVER_REASON },
+                waitedMs,
+                ...(reading.repairedAt ? { repairedAt: reading.repairedAt } : {}),
+            });
+            return true;
+        }
+        // The machine reported its own ending and the server settled the row on
+        // it. That sentence replaces the provisional "still working" one, which is
+        // now false; the original fields stay so a consumer keyed on them still
+        // matches.
+        this.finish('failed', {
+            ...handover.event,
+            message: reading.error,
+            errors: [reading.error],
+            ...(typeof reading.text === 'string' && reading.text ? { result: reading.text } : {}),
+            handover: { outcome: 'machine_failed', waitedMs },
+        });
+        return true;
+    }
+    /** The bound ran out: one last look, then the original failure. */
+    async expireHandover() {
+        const handover = this.handover;
+        if (!handover || this.settled || this.closed)
+            return;
+        if (handover.pollTimer)
+            clearInterval(handover.pollTimer);
+        handover.pollTimer = null;
+        handover.deadlineTimer = null;
+        if (handover.reading)
+            await handover.reading;
+        if (this.handover !== handover || this.settled || this.closed)
+            return;
+        if (await this.readHandover())
+            return;
+        if (this.handover !== handover || this.settled || this.closed)
+            return;
+        const waitedMs = Date.now() - handover.startedAt;
+        this.endHandover();
+        this.finish('failed', { ...handover.event, handover: { outcome: 'expired', waitedMs } });
+    }
+    stopHandoverTimers() {
+        if (!this.handover)
+            return;
+        if (this.handover.deadlineTimer)
+            clearTimeout(this.handover.deadlineTimer);
+        if (this.handover.pollTimer)
+            clearInterval(this.handover.pollTimer);
+        this.handover.deadlineTimer = null;
+        this.handover.pollTimer = null;
+    }
+    endHandover() {
+        this.stopHandoverTimers();
+        this.handover = null;
+    }
+    /**
+     * The server's "this row was rewritten" notice (`lateDeliveryRepair`
+     * `notifyViewersMessageRewritten`), delivered to every socket of the user
+     * through the `user:<id>` room this socket joins on connect. A hint to read,
+     * never a verdict.
+     */
+    onConversationUpdate(data) {
+        if (!this.handover || !data || data.messagesRepaired !== true)
+            return;
+        const opts = this.options.awaitHandover;
+        const messageId = typeof data.messageId === 'string' ? data.messageId : undefined;
+        const conversationId = typeof data.conversationId === 'string' ? data.conversationId : undefined;
+        // Narrowest identity both sides know. When neither is known, read anyway:
+        // a spare read is cheap and the record decides.
+        let ours = true;
+        if (messageId && opts?.responseMessageId)
+            ours = messageId === opts.responseMessageId;
+        else if (conversationId && opts?.conversationId)
+            ours = conversationId === opts.conversationId;
+        if (ours)
+            this.requestHandoverRead();
+    }
     debug(line) {
         try {
             (this.options.debug ?? defaultStreamDebug)(`session ${this.options.sessionId}: ${line}`);
@@ -1164,6 +1430,12 @@ class AgenticStreamClient {
             // seqs and would read as a gap that never happened.
             this.noteSeqGap(fresh);
             this.noteDaemonToolEnvelopes(fresh);
+            // The machine's own turn-end is what the server repairs or settles the
+            // row on; seeing it relayed is the moment the record is about to move.
+            if (this.handover &&
+                fresh.some((env) => env?.ev?.t === 'turn-end')) {
+                this.requestHandoverRead();
+            }
             const envelopeText = envelopesText(scoped);
             if (envelopeText) {
                 this.accumulated += envelopeText;
@@ -1198,6 +1470,9 @@ class AgenticStreamClient {
             socket.emit('session:join', this.sessionJoinPayload());
             this.emit({ type: 'transport.connected', sessionId: this.options.sessionId });
             void this.catchUpEnvelopes();
+            // A repair notice sent while the transport was down is gone for good.
+            if (this.handover)
+                this.requestHandoverRead();
         });
         socket.on('disconnect', (reason) => {
             this.transportDropped = true;
@@ -1294,22 +1569,42 @@ class AgenticStreamClient {
             if (this.firstTimeSeen('text.completed', key))
                 this.emit({ ...event, type: 'text.completed' });
         });
+        // While a handed-over turn is waited on, a terminal frame — a repeat of the
+        // hand-over failure through another room, or anything a later writer sends
+        // — is a reason to read the record, not a verdict of its own (OSK-13543).
         socket.on('execution:complete', (event) => {
-            if (match(event))
+            if (!match(event))
+                return;
+            if (this.handover)
+                this.requestHandoverRead();
+            else
                 this.finish('completed', event);
         });
         socket.on('execution:aborted', (event) => {
-            if (match(event))
+            if (!match(event))
+                return;
+            if (this.handover)
+                this.requestHandoverRead();
+            else
                 this.finish('aborted', event);
         });
         socket.on('execution:cancelled', (event) => {
-            if (match(event))
+            if (!match(event))
+                return;
+            if (this.handover)
+                this.requestHandoverRead();
+            else
                 this.finish('aborted', event);
         });
         socket.on('execution:error', (event) => {
-            if (match(event))
+            if (!match(event))
+                return;
+            if (this.handover)
+                this.requestHandoverRead();
+            else if (!(isDaemonHandoverFailure(event) && this.beginHandoverWait(event)))
                 this.finish('failed', event);
         });
+        socket.on('conversation:update', (data) => this.onConversationUpdate(data));
         socket.on('permission:request', (event) => {
             if (!match(event))
                 return;
@@ -1598,6 +1893,11 @@ class AgenticStreamClient {
         // Any event is proof the stream is alive; the watchdog only fires on real
         // silence.
         this.armIdleProbe();
+        // A handed-over turn can hold the terminal for minutes, so a person is told
+        // why — in every human mode. `--no-stream` reserves stdout for the final
+        // result, so there the line goes to stderr (OSK-13543).
+        if (!this.options.jsonl && this.renderHandoverStatus(event))
+            return;
         // 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)
@@ -1695,6 +1995,40 @@ class AgenticStreamClient {
             this.renderedText = this.accumulated;
         }
     }
+    /**
+     * Human-mode lines for the hand-over wait. Returns true when the event is
+     * fully rendered here; false lets the ordinary rendering continue.
+     */
+    renderHandoverStatus(event) {
+        const handover = event.handover;
+        const isStatus = event.type === 'run.handed_over' ||
+            (event.type === 'run.completed' && event.repaired === true) ||
+            (event.type === 'run.failed' && !!handover);
+        if (!isStatus)
+            return false;
+        const output = this.options.quiet
+            ? (this.options.awaitHandover?.statusOutput ?? process.stderr)
+            : (this.options.output ?? process.stdout);
+        if (event.type === 'run.handed_over') {
+            output.write('\n[machine] A platform update restarted the server relaying this turn, but your ' +
+                'machine is still working on it. Waiting up to ' +
+                `${formatWaitDuration(Number(event.waitMs) || 0)} for its reply ` +
+                '(Ctrl-C stops waiting; it does not stop your machine).\n');
+            this.renderedText = this.accumulated;
+            return true;
+        }
+        if (event.type === 'run.completed') {
+            output.write('[machine] Your machine finished the turn, and its full reply was recovered.\n');
+            return true;
+        }
+        if (handover?.outcome === 'expired') {
+            output.write(`\n[machine] No reply from your machine within ${formatWaitDuration(Number(this.options.awaitHandover?.maxWaitMs) || 0)}. If it finishes later, the reply is saved to the conversation.\n`);
+        }
+        else {
+            output.write('\n[machine] Your machine ended the turn without finishing it.\n');
+        }
+        return this.options.quiet === true;
+    }
     finish(status, event) {
         if (this.settled || this.finishingReplay)
             return;
@@ -1823,6 +2157,7 @@ class AgenticStreamClient {
             responseMessageId: this.responseMessageId,
             text: this.accumulated,
             status,
+            ...(status === 'completed' && event.repaired === true ? { repaired: true } : {}),
             lastEvent: event,
         };
         this.resolve(this.terminalResult);

package/dist/lib/auth-storage.d.ts

@@ -136,6 +136,10 @@ export declare function writeToBackend(bundle: AuthBundle, options?: WriteOption
  * auth-failure cleanup). Idempotent.
  */
 export declare function clearAllBackends(): void;
+export declare function takeResolvedKeychainRead(credential: {
+    token: string | null;
+    source: string;
+}, expectedServerOrigin: string): ReadResult | null;
 /**
  * The low-level backends, exposed for the credential resolver's
  * `readKeychainToken` / `readFileToken` slots. Internal callers should