@skrr-ai/cli 0.1.86 → 0.1.87

package/bin/run.js

@@ -1,5 +1,16 @@
 #!/usr/bin/env node
 
+// Reuse V8's compiled code for this CLI's modules across runs. Every command
+// compiles oclif plus a 2.4MB vendored data-provider bundle before it can do
+// anything; with the cache that compile step is read back instead (Node >= 22.1;
+// a no-op on older Node and on Bun, and NODE_DISABLE_COMPILE_CACHE=1 turns it
+// off). The cache is keyed by file content, so a stale entry is never used.
+try {
+  require('node:module').enableCompileCache?.();
+} catch {
+  /* an optimisation must never be the reason a command cannot start */
+}
+
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { findAlternateCli, missingLocalCommandBuild } = require('./dev-fallback');

package/dist/base-command.js

@@ -512,6 +512,7 @@ class BaseCommand extends core_1.Command {
             const fresh = await (0, refresh_1.ensureFreshCliCredential)({
                 credential: this.resolvedCredential,
                 bareMode: this.bareMode,
+                reuseResolvedRead: true,
             });
             if (fresh.credential.token) {
                 this.resolvedCredential = fresh.credential;

package/dist/commands/agents/chat.d.ts

@@ -1,6 +1,6 @@
 import { dataService } from '@skrr-ai/data-provider';
 import { BaseCommand } from '../../base-command';
-import { type AgenticStreamResult, type ReconciledTerminal } from '../../lib/agentic-stream';
+import { type AgenticStreamResult, type HandoverReading, type ReconciledTerminal } from '../../lib/agentic-stream';
 /**
  * Exit code for a run the USER stopped watching, by pressing Ctrl-C.
  *
@@ -73,6 +73,62 @@ export declare function interruptedDetachMessage(input: {
  * because a long tool call is silence, not a failure.
  */
 export declare function reconcileTerminalFromMessages(messages: ReadonlyArray<Record<string, unknown>>, responseMessageId?: string): ReconciledTerminal | null;
+/**
+ * Where a handed-over turn stands, read off its response message (OSK-13543).
+ *
+ * The server converges such a row to exactly one of two states, and only
+ * those two end the wait:
+ *
+ *   - REPAIRED — `error` cleared and `metadata.agentic.deliveryRepair` written,
+ *     by `sessionMessagePersister.repairDeliveryFailedMessage` on the machine's
+ *     completed turn-end. The repair record is required, not just `error:
+ *     false`: before the failure is saved a row can read `unfinished: false,
+ *     error: false` from a daemon flush that never writes `error`, and calling
+ *     that a success is the lie `recordHandedOverTurn` exists to prevent.
+ *   - SETTLED FAILED — still `error: true`, but no longer carrying the
+ *     hand-over reason (`lateDeliveryRepair.settleHandedOverFailure` moves it to
+ *     `worker_replaced_daemon_failed` with the machine's own reason).
+ *
+ * Everything else — still failed with the hand-over reason, not yet written,
+ * not found — is `pending`. Pure, so the mapping is testable without a socket.
+ */
+export declare function handoverStateFromMessages(messages: ReadonlyArray<Record<string, unknown>>, responseMessageId?: string): HandoverReading;
+/**
+ * How long `agents chat` waits for a handed-over turn by default (OSK-13543).
+ *
+ * Bounded above by the server's own hold: it quarantines the conversation for
+ * the worker job timeout plus a margin (30m + 5m, `conversationAdmissionClaim`)
+ * and after that stops treating the turn as possibly running, so waiting longer
+ * cannot observe anything the server would still act on. The default is well
+ * below that, because the cost of expiring is small and recoverable — the
+ * repair still lands on the record and `skrr messages list` shows it — while
+ * the cost of holding a terminal or a script is paid every minute. Ten minutes
+ * covers the repair observed in production (~90s after the failure) many times
+ * over and the long tail of a turn that was mid tool-call when the deploy hit.
+ */
+export declare const DEFAULT_HANDOVER_WAIT_SECONDS = 600;
+/** The server's hold for a handed-over turn: 30m job timeout + 5m lease margin. */
+export declare const MAX_HANDOVER_WAIT_SECONDS: number;
+/**
+ * What to say when Ctrl-C stops a hand-over wait. There is nothing to cancel
+ * through — the server relaying the turn is gone — so the honest statement is
+ * that the CLI stopped watching and the machine may still finish.
+ */
+export declare function handoverInterruptMessage(input: {
+    sessionId: string;
+    conversationId?: string | null;
+}): string;
+/**
+ * What one Ctrl-C does, by state. Exported so the decision is testable
+ * without delivering a signal:
+ *   - waiting on a handed-over turn → stop waiting at once (no cancel exists);
+ *   - first interrupt of a live run → request a cancel, wait the grace;
+ *   - any later interrupt → detach now.
+ */
+export declare function interruptAction(input: {
+    interrupts: number;
+    awaitingHandover: boolean;
+}): 'stop-handover-wait' | 'cancel' | 'detach';
 /**
  * How to look at a turn the CLI is no longer watching.
  *
@@ -168,6 +224,7 @@ export default class AgentsChat extends BaseCommand {
         quick: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         jsonl: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'repair-wait': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
         'approve-tools': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'permission-mode': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'local-skill': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/agents/chat.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STREAM_LOST_EXIT_CODE = exports.DETACH_EXIT_CODE = void 0;
+exports.MAX_HANDOVER_WAIT_SECONDS = exports.DEFAULT_HANDOVER_WAIT_SECONDS = exports.STREAM_LOST_EXIT_CODE = exports.DETACH_EXIT_CODE = void 0;
 exports.streamedResultExitCode = streamedResultExitCode;
 exports.interruptedDetachMessage = interruptedDetachMessage;
 exports.reconcileTerminalFromMessages = reconcileTerminalFromMessages;
+exports.handoverStateFromMessages = handoverStateFromMessages;
+exports.handoverInterruptMessage = handoverInterruptMessage;
+exports.interruptAction = interruptAction;
 exports.inspectTurnCommand = inspectTurnCommand;
 exports.noOutputFailureMessage = noOutputFailureMessage;
 exports.noStreamJsonPayload = noStreamJsonPayload;
@@ -110,6 +113,9 @@ function reconcileTerminalFromMessages(messages, responseMessageId) {
             // The reason exists on the row; it simply never reached the surface. Say
             // it, rather than the transport error that masked it (OSK-7595).
             error: failure.reason ?? 'The run failed. No reason was recorded on the message.',
+            // Provisional, not final: the server rewrites this row from the
+            // machine's own turn-end (OSK-13543).
+            ...(agenticErrorSubtype(row) === agentic_stream_1.DAEMON_HANDOVER_REASON ? { handedOver: true } : {}),
         };
     }
     const text = typeof row.text === 'string' ? row.text : '';
@@ -120,6 +126,101 @@ function reconcileTerminalFromMessages(messages, responseMessageId) {
         return { status: 'completed', text };
     return null;
 }
+function agenticRecord(row) {
+    const metadata = row.metadata;
+    if (!metadata || typeof metadata !== 'object')
+        return null;
+    const agentic = metadata.agentic;
+    return agentic && typeof agentic === 'object' ? agentic : null;
+}
+function agenticErrorSubtype(row) {
+    const subtype = agenticRecord(row)?.errorSubtype;
+    return typeof subtype === 'string' ? subtype : undefined;
+}
+/**
+ * Where a handed-over turn stands, read off its response message (OSK-13543).
+ *
+ * The server converges such a row to exactly one of two states, and only
+ * those two end the wait:
+ *
+ *   - REPAIRED — `error` cleared and `metadata.agentic.deliveryRepair` written,
+ *     by `sessionMessagePersister.repairDeliveryFailedMessage` on the machine's
+ *     completed turn-end. The repair record is required, not just `error:
+ *     false`: before the failure is saved a row can read `unfinished: false,
+ *     error: false` from a daemon flush that never writes `error`, and calling
+ *     that a success is the lie `recordHandedOverTurn` exists to prevent.
+ *   - SETTLED FAILED — still `error: true`, but no longer carrying the
+ *     hand-over reason (`lateDeliveryRepair.settleHandedOverFailure` moves it to
+ *     `worker_replaced_daemon_failed` with the machine's own reason).
+ *
+ * Everything else — still failed with the hand-over reason, not yet written,
+ * not found — is `pending`. Pure, so the mapping is testable without a socket.
+ */
+function handoverStateFromMessages(messages, responseMessageId) {
+    const row = (responseMessageId && messages.find((m) => m?.messageId === responseMessageId)) ||
+        (!responseMessageId && [...messages].reverse().find((m) => m && m.isCreatedByUser === false));
+    if (!row)
+        return { state: 'pending' };
+    const failure = (0, data_provider_1.resolveMessageFailure)(row);
+    if (failure) {
+        if (agenticErrorSubtype(row) === agentic_stream_1.DAEMON_HANDOVER_REASON)
+            return { state: 'pending' };
+        return {
+            state: 'failed',
+            error: failure.reason ?? 'The run failed. No reason was recorded on the message.',
+            ...(failure.answer ? { text: failure.answer } : {}),
+        };
+    }
+    const repair = agenticRecord(row)?.deliveryRepair;
+    if (!repair || typeof repair !== 'object')
+        return { state: 'pending' };
+    // JSON over the wire makes this an ISO string; anything else is not shown.
+    const repairedAt = typeof repair.repairedAt === 'string' ? repair.repairedAt : undefined;
+    return {
+        state: 'repaired',
+        text: typeof row.text === 'string' ? row.text : '',
+        ...(repairedAt ? { repairedAt } : {}),
+    };
+}
+/**
+ * How long `agents chat` waits for a handed-over turn by default (OSK-13543).
+ *
+ * Bounded above by the server's own hold: it quarantines the conversation for
+ * the worker job timeout plus a margin (30m + 5m, `conversationAdmissionClaim`)
+ * and after that stops treating the turn as possibly running, so waiting longer
+ * cannot observe anything the server would still act on. The default is well
+ * below that, because the cost of expiring is small and recoverable — the
+ * repair still lands on the record and `skrr messages list` shows it — while
+ * the cost of holding a terminal or a script is paid every minute. Ten minutes
+ * covers the repair observed in production (~90s after the failure) many times
+ * over and the long tail of a turn that was mid tool-call when the deploy hit.
+ */
+exports.DEFAULT_HANDOVER_WAIT_SECONDS = 600;
+/** The server's hold for a handed-over turn: 30m job timeout + 5m lease margin. */
+exports.MAX_HANDOVER_WAIT_SECONDS = 35 * 60;
+/**
+ * What to say when Ctrl-C stops a hand-over wait. There is nothing to cancel
+ * through — the server relaying the turn is gone — so the honest statement is
+ * that the CLI stopped watching and the machine may still finish.
+ */
+function handoverInterruptMessage(input) {
+    return (`Stopped waiting for run ${input.sessionId}. A platform update had restarted the server ` +
+        'relaying it, and your machine MAY STILL BE WORKING on it: if it finishes, its reply is ' +
+        'saved to the conversation. Nothing was cancelled. ' +
+        `Check with: ${inspectTurnCommand(input.conversationId)}`);
+}
+/**
+ * What one Ctrl-C does, by state. Exported so the decision is testable
+ * without delivering a signal:
+ *   - waiting on a handed-over turn → stop waiting at once (no cancel exists);
+ *   - first interrupt of a live run → request a cancel, wait the grace;
+ *   - any later interrupt → detach now.
+ */
+function interruptAction(input) {
+    if (input.awaitingHandover)
+        return 'stop-handover-wait';
+    return input.interrupts === 1 ? 'cancel' : 'detach';
+}
 /**
  * How to look at a turn the CLI is no longer watching.
  *
@@ -158,6 +259,9 @@ function noStreamJsonPayload(input) {
         conversationId,
         responseMessageId: result.responseMessageId,
         status: result.status,
+        // The run first failed as handed over and the machine's reply was then
+        // repaired onto the record (OSK-13543).
+        ...(result.repaired ? { repaired: true } : {}),
         response: result.text,
         // The model a local harness reported running (OSK-12111). Absent on a
         // cloud turn and on a harness that reports none.
@@ -279,11 +383,30 @@ class AgentsChat extends base_command_1.BaseCommand {
                 'conversation; `message` says why. A `permission.resolved` says ' +
                 'how a local harness permission request was decided: `decidedBy` in words, and ' +
                 '`basis` — `person` (with `surface`), `mode` (with `mode`), `policy` or ' +
-                '`session-grant` — beside the wire `by`.',
+                '`session-grant` — beside the wire `by`. When a platform update restarts the server ' +
+                'relaying a turn your machine is still running, the run does not end at that failure: ' +
+                '`run.handed_over` (`code: "AGENT_WORKER_REPLACED"`, `reason: ' +
+                '"worker_replaced_daemon_running"`, `waitMs`, `deadlineAt`) says the CLI is waiting, ' +
+                'then exactly one terminal event follows — `run.completed` with `repaired: true` and ' +
+                '`result` (then `run.result` with `status: "completed"`, `repaired: true`, exit 0) when ' +
+                'the machine finished; `run.failed` with `handover.outcome: "machine_failed"` and the ' +
+                'machine\'s reason when it did not; or `run.failed` with `handover.outcome: "expired"` ' +
+                'and the original failure when --repair-wait ran out (exit 1 for both). Ctrl-C during ' +
+                'the wait emits `run.detached` with `handedOver: true` and exits 130.',
         }),
         json: core_1.Flags.boolean({
             description: 'Emit the final one-shot response as JSON (use with --no-stream)',
         }),
+        'repair-wait': core_1.Flags.integer({
+            description: 'Seconds to keep waiting when a platform update restarts the server relaying a turn ' +
+                'your machine is still running. The server repairs the reply onto the conversation ' +
+                'when the machine finishes, and the CLI prints it and exits 0; if the wait runs out ' +
+                'the original failure is reported. 0 ends at the failure immediately. At most the ' +
+                `server's own hold for such a turn (${exports.MAX_HANDOVER_WAIT_SECONDS}s).`,
+            default: exports.DEFAULT_HANDOVER_WAIT_SECONDS,
+            min: 0,
+            max: exports.MAX_HANDOVER_WAIT_SECONDS,
+        }),
         'approve-tools': core_1.Flags.boolean({
             description: 'Allow this turn to use permission-gated tools. In a terminal it asks per call; ' +
                 'with no terminal the flag itself is the approval for this turn, and each one is ' +
@@ -409,6 +532,15 @@ class AgentsChat extends base_command_1.BaseCommand {
         if (flags.conversation && flags['thread-root']) {
             this.error('--conversation and --thread-root are mutually exclusive.', { exit: 2 });
         }
+        // The agent read that picks the turn's default workspace depends on nothing
+        // below, so it starts now and runs beside the `--thread-root`, `--task` and
+        // `--local-skill` reads instead of after them (each is a full round trip).
+        // Only the LOOKUP starts here: the default is committed just before the
+        // turn, so those reads still go out without a workspace header, as before.
+        // `--quick` never consulted it. Never rejects.
+        const homeWorkspace = flags.quick
+            ? null
+            : (0, agent_home_workspace_1.lookupAgentHomeWorkspaceDefault)(args.agentId, (agentId) => data_provider_1.dataService.getAgentById({ agent_id: agentId }));
         let threadConversationId = flags.conversation;
         if (flags['thread-root']) {
             try {
@@ -522,7 +654,7 @@ class AgentsChat extends base_command_1.BaseCommand {
         const prompt = localSkills
             ? (0, local_skills_1.withSkillInvocations)(flags.prompt, localSkills.refs)
             : flags.prompt;
-        await (0, agent_home_workspace_1.applyAgentHomeWorkspaceDefault)(args.agentId, (agentId) => data_provider_1.dataService.getAgentById({ agent_id: agentId }));
+        (0, agent_home_workspace_1.commitAgentHomeWorkspaceDefault)(await homeWorkspace);
         let started;
         try {
             started = await data_provider_1.dataService.startAgenticChat({
@@ -593,6 +725,21 @@ class AgentsChat extends base_command_1.BaseCommand {
                 return reconcileTerminalFromMessages(messages, started.responseMessageId);
             }
             : undefined;
+        // OSK-13543 — a turn handed over on a deploy is waited out against the same
+        // record. Without a conversation there is no record to read, so no wait.
+        const awaitHandover = conversationId
+            ? {
+                read: async () => {
+                    const messages = (await data_provider_1.dataService.getMessagesByConvoId(conversationId));
+                    if (!Array.isArray(messages))
+                        return null;
+                    return handoverStateFromMessages(messages, started.responseMessageId);
+                },
+                responseMessageId: started.responseMessageId,
+                conversationId,
+                maxWaitMs: (flags['repair-wait'] ?? exports.DEFAULT_HANDOVER_WAIT_SECONDS) * 1000,
+            }
+            : undefined;
         const client = new agentic_stream_1.AgenticStreamClient({
             baseURL: this.cliConfig.baseURL,
             token: this.resolvedCredential.token,
@@ -602,6 +749,7 @@ class AgentsChat extends base_command_1.BaseCommand {
             quiet,
             approveTools: flags['approve-tools'],
             reconcileTerminal,
+            awaitHandover,
             replayEnvelopes: (from) => (0, api_fetch_1.apiFetch)(`/api/agentic/sessions/${encodeURIComponent(started.sessionId)}/envelopes?from=${from}&limit=500`, { credential: this.resolvedCredential, signal: AbortSignal.timeout(5000) }),
         });
         // OSK-2938 — Ctrl-C must be bounded, visible, and honest about what it
@@ -636,7 +784,35 @@ class AgentsChat extends base_command_1.BaseCommand {
         let graceTimer = null;
         const onInterrupt = () => {
             interrupts += 1;
-            if (interrupts === 1) {
+            const action = interruptAction({ interrupts, awaitingHandover: client.awaitingHandover() });
+            if (action === 'stop-handover-wait') {
+                // Nothing to cancel and nothing to grace-wait for: stop at once.
+                if (!forcedDetachAnnounced) {
+                    forcedDetachAnnounced = true;
+                    const message = handoverInterruptMessage({
+                        sessionId: started.sessionId,
+                        conversationId: started.conversationId,
+                    });
+                    if (flags.jsonl) {
+                        (0, node_fs_1.writeSync)(process.stdout.fd, `${JSON.stringify({
+                            type: 'run.detached',
+                            sessionId: started.sessionId,
+                            conversationId: started.conversationId,
+                            interrupted: true,
+                            handedOver: true,
+                            message,
+                        })}\n`);
+                    }
+                    else {
+                        (0, node_fs_1.writeSync)(process.stderr.fd, `\n${message}\n`);
+                    }
+                    process.exitCode = exports.DETACH_EXIT_CODE;
+                }
+                client.close();
+                detach?.();
+                return;
+            }
+            if (action === 'cancel') {
                 client.cancel();
                 if (!flags.jsonl) {
                     this.log(`\nCancelling run ${started.sessionId}… (waiting up to ${CANCEL_GRACE_MS / 1000}s; ` +

package/dist/lib/agent-home-workspace.d.ts

@@ -17,3 +17,22 @@
 export declare function applyAgentHomeWorkspaceDefault(agentId: string, lookup: (agentId: string) => Promise<{
     workspaceId?: string | null;
 } | null | undefined>, env?: NodeJS.ProcessEnv): Promise<string | null>;
+/**
+ * The read half of `applyAgentHomeWorkspaceDefault`: the workspace a turn
+ * would default to, WITHOUT setting it.
+ *
+ * Split so `agents chat` can start the agent read at the same time as its
+ * other pre-flight reads (`--task`, `--thread-root`, `--local-skill`) instead
+ * of after them — each is a full round trip — while those reads still go out
+ * exactly as before, with no workspace header. The default is committed only
+ * right before the turn is started.
+ */
+export declare function lookupAgentHomeWorkspaceDefault(agentId: string, lookup: (agentId: string) => Promise<{
+    workspaceId?: string | null;
+} | null | undefined>, env?: NodeJS.ProcessEnv): Promise<string | null>;
+/**
+ * The write half: apply a looked-up default, unless something chose a
+ * workspace in the meantime (that choice still wins) or this is an autonomous
+ * Agent process.
+ */
+export declare function commitAgentHomeWorkspaceDefault(workspaceId: string | null, env?: NodeJS.ProcessEnv): string | null;

package/dist/lib/agent-home-workspace.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyAgentHomeWorkspaceDefault = applyAgentHomeWorkspaceDefault;
+exports.lookupAgentHomeWorkspaceDefault = lookupAgentHomeWorkspaceDefault;
+exports.commitAgentHomeWorkspaceDefault = commitAgentHomeWorkspaceDefault;
 /**
  * The workspace an `agents chat` turn runs in when the caller named none.
  *
@@ -18,6 +20,19 @@ exports.applyAgentHomeWorkspaceDefault = applyAgentHomeWorkspaceDefault;
  * daemon session.
  */
 async function applyAgentHomeWorkspaceDefault(agentId, lookup, env = process.env) {
+    return commitAgentHomeWorkspaceDefault(await lookupAgentHomeWorkspaceDefault(agentId, lookup, env), env);
+}
+/**
+ * The read half of `applyAgentHomeWorkspaceDefault`: the workspace a turn
+ * would default to, WITHOUT setting it.
+ *
+ * Split so `agents chat` can start the agent read at the same time as its
+ * other pre-flight reads (`--task`, `--thread-root`, `--local-skill`) instead
+ * of after them — each is a full round trip — while those reads still go out
+ * exactly as before, with no workspace header. The default is committed only
+ * right before the turn is started.
+ */
+async function lookupAgentHomeWorkspaceDefault(agentId, lookup, env = process.env) {
     if (env.OVERSKY_AUTONOMOUS_SESSION === '1')
         return null;
     if (env.OVERSKY_WORKSPACE_ID?.trim())
@@ -32,8 +47,20 @@ async function applyAgentHomeWorkspaceDefault(agentId, lookup, env = process.env
         return null;
     }
     const workspaceId = typeof agent?.workspaceId === 'string' ? agent.workspaceId.trim() : '';
+    return workspaceId || null;
+}
+/**
+ * The write half: apply a looked-up default, unless something chose a
+ * workspace in the meantime (that choice still wins) or this is an autonomous
+ * Agent process.
+ */
+function commitAgentHomeWorkspaceDefault(workspaceId, env = process.env) {
     if (!workspaceId)
         return null;
+    if (env.OVERSKY_AUTONOMOUS_SESSION === '1')
+        return null;
+    if (env.OVERSKY_WORKSPACE_ID?.trim())
+        return null;
     env.OVERSKY_WORKSPACE_ID = workspaceId;
     return workspaceId;
 }

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;
     /**