@skrr-ai/cli 0.1.21 → 0.1.23

package/dist/commands/tasks/timeline.js

@@ -5,7 +5,6 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const format_1 = require("../../lib/format");
-const tasks_1 = require("../../lib/tasks");
 /**
  * `<action> (<k=v ...>)`, or just the preview when there is nothing to add.
  *
@@ -14,11 +13,11 @@ const tasks_1 = require("../../lib/tasks");
  */
 function withDetails(item) {
     const preview = String(item.preview ?? '-');
-    const details = (0, format_1.formatCell)(item.details, '');
+    const details = (0, format_1.formatCell)(item.data ?? item.details, '');
     return details ? `${preview} (${details})` : preview;
 }
 class TasksTimeline extends base_command_1.BaseCommand {
-    static description = 'Show the unified task timeline: work log, comments, lifecycle, and execution';
+    static description = 'Show the immutable multi-actor Task Activity timeline';
     static args = {
         id: core_1.Args.string({ description: 'Task ID', required: true, ignoreStdin: true }),
     };
@@ -26,16 +25,9 @@ class TasksTimeline extends base_command_1.BaseCommand {
         json: core_1.Flags.boolean({ description: 'Output JSON' }),
         limit: core_1.Flags.integer({ default: 50 }),
         cursor: core_1.Flags.string(),
-        // `--kind` names a typed WORK-EVENT kind, not one of the timeline's four
-        // sources. Undeclared and undescribed, it read like a source filter and
-        // silently accepted anything; the server now refuses an unknown kind, and
-        // declaring the options here refuses a typo before it costs a round trip.
-        kind: core_1.Flags.string({
-            description: 'Show only work events of this kind (excludes comments, lifecycle, execution)',
-            options: [...tasks_1.TASK_WORK_EVENT_KINDS],
-        }),
-        run: core_1.Flags.string(),
-        actor: core_1.Flags.string({ options: ['user', 'agent', 'system'] }),
+        type: core_1.Flags.string({ description: 'Exact Activity event type, e.g. task.result.submitted' }),
+        execution: core_1.Flags.string({ description: 'Bounded Task execution id' }),
+        actor: core_1.Flags.string({ options: ['human', 'agent', 'system', 'integration'] }),
     };
     async run() {
         this.requireAuth();
@@ -45,8 +37,8 @@ class TasksTimeline extends base_command_1.BaseCommand {
             result = await data_provider_1.dataService.getTaskTimeline(args.id, {
                 limit: flags.limit,
                 cursor: flags.cursor,
-                kind: flags.kind,
-                runId: flags.run,
+                type: flags.type,
+                executionId: flags.execution,
                 actor: flags.actor,
             });
         }
@@ -61,12 +53,7 @@ class TasksTimeline extends base_command_1.BaseCommand {
             time: String(item.occurredAt ?? '-')
                 .replace('T', ' ')
                 .slice(0, 19),
-            // A work event's own kind is the thing you came to see. Showing the
-            // source alone collapsed blocker, decision, checkpoint and evidence
-            // into one indistinguishable `work_event`.
-            source: item.eventKind
-                ? `${String(item.kind ?? '-')}:${String(item.eventKind)}`
-                : String(item.kind ?? '-'),
+            source: String(item.type ?? '-'),
             actor: String(item.actor?.kind ?? '-'),
             // A lifecycle row's preview is the bare action, so `status_changed`
             // appeared three times in a row without ever naming a status. The
@@ -75,13 +62,13 @@ class TasksTimeline extends base_command_1.BaseCommand {
             // substituted: the action is still what happened, `details` is what
             // it happened to.
             detail: (0, format_1.truncate)(withDetails(item), 90),
-            run: String(item.runId ?? '-'),
+            run: String(item.executionId ?? '-'),
         })), [
             { key: 'time', header: 'TIME' },
             { key: 'source', header: 'SOURCE' },
             { key: 'actor', header: 'ACTOR' },
             { key: 'detail', header: 'DETAIL', maxWidth: 90 },
-            { key: 'run', header: 'RUN', maxWidth: 24 },
+            { key: 'run', header: 'EXECUTION', maxWidth: 24 },
         ], (line) => this.log(line));
         if (result.next_cursor)
             this.log(`Next page: --cursor ${result.next_cursor}`);

package/dist/commands/tasks/updates/add.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../../base-command';
+export default class TasksUpdatesAdd extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        task: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        type: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        summary: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        data: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        resume: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'spec-version': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        supersedes: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        reference: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/updates/add.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const outbox_1 = require("../../../lib/outbox");
+const task_resolver_1 = require("../../../lib/task-resolver");
+const api_fetch_1 = require("../../../lib/api-fetch");
+const session_task_endpoints_1 = require("../../../lib/session-task-endpoints");
+function parseJsonObject(value, label) {
+    if (!value)
+        return undefined;
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return parsed;
+}
+class TasksUpdatesAdd extends base_command_1.BaseCommand {
+    static description = 'Record a meaningful Task Update, optionally with recovery state';
+    static examples = [
+        '<%= config.bin %> tasks updates add <task> --type progress --summary "Migration review complete" --data \'{"completedSinceLast":["Checked migrations 001-014"],"nextActions":["Review authorization"]}\'',
+        '<%= config.bin %> tasks updates add <task> --type decision --summary "Use a resource object" --data \'{"decision":"Use WorkResource","rationale":"Identity must survive URL changes"}\'',
+    ];
+    static args = {
+        task: core_1.Args.string({ required: false, ignoreStdin: true, description: 'Task id or ref' }),
+    };
+    static flags = {
+        task: core_1.Flags.string({ description: 'Task id; overrides runtime context' }),
+        type: core_1.Flags.string({
+            required: true,
+            options: ['progress', 'finding', 'decision', 'blocker', 'verification'],
+            description: 'What changed in the shared understanding of the Task',
+        }),
+        summary: core_1.Flags.string({ required: true, description: 'One sentence saying what became true' }),
+        data: core_1.Flags.string({ required: true, description: 'Kind-specific JSON payload' }),
+        resume: core_1.Flags.string({
+            description: 'JSON recovery snapshot; requires --run-id and is committed with the Update',
+        }),
+        'run-id': core_1.Flags.string({ description: 'Canonical Task Run that performed this work' }),
+        'spec-version': core_1.Flags.integer({
+            description: 'Task specification version this Update concerns',
+        }),
+        supersedes: core_1.Flags.string({ description: 'Update id this correction supersedes' }),
+        reference: core_1.Flags.string({ multiple: true, description: 'Reference as <kind>:<id-or-uri>' }),
+        'idempotency-key': core_1.Flags.string({ description: 'Stable retry key for this exact Update' }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksUpdatesAdd);
+        const task = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.task, flagTask: flags.task });
+        let data;
+        let resume;
+        try {
+            data = parseJsonObject(flags.data, '--data');
+            resume = parseJsonObject(flags.resume, '--resume');
+        }
+        catch (error) {
+            this.error(error.message, { exit: 1 });
+        }
+        const references = (flags.reference || []).map((raw) => {
+            const split = raw.indexOf(':');
+            if (split < 1)
+                this.error('--reference must be <kind>:<id-or-uri>', { exit: 1 });
+            const kind = raw.slice(0, split);
+            const value = raw.slice(split + 1);
+            return /^https?:|^file:/.test(value) ? { kind, uri: value } : { kind, id: value };
+        });
+        const idempotencyKey = flags['idempotency-key'] ||
+            (0, outbox_1.idempotencyKeyFor)('task-update', task.id, JSON.stringify({ type: flags.type, summary: flags.summary, data, resume }));
+        let result;
+        try {
+            const payload = {
+                type: flags.type,
+                summary: flags.summary,
+                data,
+                runId: flags['run-id'],
+                expectedSpecVersion: flags['spec-version'],
+                references,
+                supersedesUpdateId: flags.supersedes,
+                resume: resume,
+                idempotencyKey,
+            };
+            const sessionPath = await (0, session_task_endpoints_1.sessionScopedTaskPath)('update');
+            result = sessionPath
+                ? await (0, api_fetch_1.apiFetch)(sessionPath, {
+                    method: 'POST',
+                    body: payload,
+                })
+                : await data_provider_1.dataService.appendTaskUpdate({ taskId: task.id, data: payload });
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        this.log(`Recorded ${flags.type} Update on ${task.id}${result?.resumePoint ? ' with a Resume Point' : ''}.`);
+    }
+}
+exports.default = TasksUpdatesAdd;

package/dist/commands/tasks/updates/list.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../../base-command';
+export default class TasksUpdatesList extends BaseCommand {
+    static description: string;
+    static args: {
+        task: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        type: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/updates/list.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const task_resolver_1 = require("../../../lib/task-resolver");
+function authorLabel(update) {
+    const actor = update.authoredBy || {};
+    if (actor.kind === 'agent')
+        return `Agent ${actor.agentId}`;
+    if (actor.kind === 'human')
+        return `Human ${actor.userId}`;
+    if (actor.kind === 'integration')
+        return `Integration ${actor.provider}`;
+    return `System ${actor.service || ''}`.trim();
+}
+class TasksUpdatesList extends base_command_1.BaseCommand {
+    static description = 'List meaningful Task Updates (not tool-call telemetry)';
+    static args = {
+        task: core_1.Args.string({ required: false, ignoreStdin: true, description: 'Task id or ref' }),
+    };
+    static flags = {
+        task: core_1.Flags.string({ description: 'Task id; overrides runtime context' }),
+        type: core_1.Flags.string({
+            options: ['progress', 'finding', 'decision', 'blocker', 'verification', 'ready_for_review'],
+        }),
+        limit: core_1.Flags.integer({ default: 50, min: 1, max: 100 }),
+        cursor: core_1.Flags.string({ description: 'Opaque cursor returned by the previous page' }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksUpdatesList);
+        const task = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.task, flagTask: flags.task });
+        let result;
+        try {
+            result = await data_provider_1.dataService.listTaskUpdates(task.id, {
+                limit: flags.limit,
+                cursor: flags.cursor,
+                type: flags.type,
+            });
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        if (!result?.data.length)
+            return this.log('No Updates recorded.');
+        for (const update of result.data) {
+            this.log(`${update.occurredAt} · ${update.type} · ${authorLabel(update)}\n${update.summary}`);
+        }
+        if (result.nextCursor)
+            this.log(`Next cursor: ${result.nextCursor}`);
+    }
+}
+exports.default = TasksUpdatesList;

package/dist/commands/tasks/waive.d.ts

@@ -11,6 +11,7 @@ import { BaseCommand } from '../../base-command';
  * indistinguishable from having forgotten.
  */
 export default class TasksWaive extends BaseCommand {
+    static hidden: boolean;
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/tasks/waive.js

@@ -15,7 +15,8 @@ const base_command_1 = require("../../base-command");
  * indistinguishable from having forgotten.
  */
 class TasksWaive extends base_command_1.BaseCommand {
-    static description = 'Waive an expectation, with a stated reason';
+    static hidden = true;
+    static description = 'Compatibility alias for `tasks expectations assess --decision waived`';
     static examples = [
         '<%= config.bin %> tasks waive <task-id> c1 --reason "superseded by OSK-7000"',
     ];

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

@@ -10,6 +10,44 @@ export type AgenticStreamResult = {
     status: 'completed' | 'aborted' | 'failed';
     lastEvent?: AgenticStreamEvent;
 };
+/**
+ * What the DURABLE record says about a turn, when the stream will not say it.
+ *
+ * A run refused during admission is written straight onto the response message
+ * (`error: true`, the reason in `metadata.agentic.error`) and the session
+ * stream is never closed — so a subscriber that has already emitted
+ * `session.joined` waits forever for a terminal event that will not come. Two
+ * independent probes measured that as a client that produces no output and does
+ * not exit, for a run the server had decided in 89ms and 451ms respectively
+ * (OSK-7624, OSK-7635, OSK-7720, OSK-7735). The mirror image is a turn that
+ * finished 13 seconds before the client gave up and declared it "may still be
+ * executing" (OSK-7660).
+ *
+ * The fix on this side of the wire is to stop treating the stream as the only
+ * witness: when it goes quiet, ask the record. `reconcileTerminal` is that
+ * question, supplied by the caller so this module keeps no API dependency.
+ */
+export type ReconciledTerminal = {
+    status: 'completed' | 'failed';
+    /** The answer as persisted, when there is one. */
+    text?: string;
+    /** The recorded failure reason — `metadata.agentic.error` on the message. */
+    error?: string;
+};
+/**
+ * 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).
+ */
+export declare function writeJsonLine(output: NodeJS.WritableStream, value: unknown): void;
 export type AgenticStreamOptions = {
     baseURL: string;
     token: string;
@@ -29,6 +67,18 @@ export type AgenticStreamOptions = {
      * suppressed, so the caller prints the final result itself.
      */
     quiet?: boolean;
+    /**
+     * Ask the durable record what happened, when the stream stops talking.
+     *
+     * Called after {@link AgenticStreamOptions.idleTerminalProbeMs} of silence
+     * and again on transport loss. Returning a terminal settles the run with it;
+     * returning null re-arms the watchdog, so a genuinely long tool call keeps
+     * waiting. Omitting the callback keeps the pre-existing behaviour of trusting
+     * the stream alone.
+     */
+    reconcileTerminal?: () => Promise<ReconciledTerminal | null>;
+    /** Silence before the first durable-record probe. Default 20s. */
+    idleTerminalProbeMs?: number;
 };
 /**
  * Small Node-side adapter for the existing Agentic Socket.IO contract.
@@ -63,6 +113,138 @@ export declare function envelopeKey(envelope: unknown): string | null;
  * empty array — the caller drops it as a pure re-delivery (OSK-4834).
  */
 export declare function unseenEnvelopes(event: AgenticStreamEvent, seen: Set<string>): unknown[];
+/** A tool event in the CLI's own vocabulary, however the turn was routed. */
+export type ProjectedToolEvent = {
+    type: 'tool.started' | 'tool.completed';
+    toolUseId?: string;
+    toolName?: string;
+    toolInput?: unknown;
+    toolResponse?: unknown;
+    status?: string;
+};
+/**
+ * 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.
+ */
+export declare function projectDaemonToolEvents(envelopes: unknown[], namesByCall: Map<string, string>): ProjectedToolEvent[];
+/**
+ * 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.
+ */
+export declare function renderableDelta(shown: string, snapshot: string): {
+    append: string;
+    shown: string;
+};
+/**
+ * WHAT THE SERVER ACTUALLY SAID when it refused the socket.
+ *
+ * OSK-7583 / OSK-7588 / OSK-7604 / OSK-7663 — four findings, one experience:
+ * `skrr agents chat` printed three envelopes and no answer, and the only
+ * explanation was "Too many concurrent connections for this account". No limit,
+ * no current count, no retry-after, and no way to tell whether the cap is 2 or
+ * 50 or whether waiting ten seconds helps. The run itself succeeded server-side
+ * every time; the only thing that failed was the user's ability to see it.
+ *
+ * Every one of those facts was already on the wire.
+ * `websocket/userConnectionTracking.js` attaches
+ * `{code, retryAfterMs, retryable, connectionClass, limit}` to the refusal, and
+ * Socket.IO delivers it to the client as `err.data`. The CLI read `err.message`
+ * and dropped the rest.
+ *
+ * The retry is not an embellishment either — it is a contract the server states
+ * in its own words: *"Socket.IO destroys a socket that fails middleware and
+ * does NOT reconnect it, so a client that ignores this stays disconnected until
+ * the page is reloaded. Every first-party client is expected to schedule one
+ * retry after this delay, jittered."* The CLI was not honouring it, which is why
+ * a refusal was terminal rather than a pause.
+ */
+export type TransportRefusal = {
+    code?: string;
+    limit?: number;
+    retryAfterMs?: number;
+    connectionClass?: string;
+    retryable: boolean;
+};
+/** The user-connection cap, as `userConnectionTracking.js` names it. */
+export declare const USER_CONNECTION_CAP_CODE = "user_connection_cap";
+export declare function transportRefusal(error: unknown): TransportRefusal;
+/**
+ * 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.
+ */
+export declare function transportRefusalMessage(message: string, refusal: TransportRefusal): string;
+/**
+ * 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.
+ */
+export declare function attachDeadlineFor(timeoutMs: number, refusal: TransportRefusal): number;
+/** Jitter, so a fleet refused together does not return together. */
+export declare function jitteredRetryDelay(retryAfterMs: number, random?: () => number): number;
+/**
+ * WHAT THE LIVE STREAM DID NOT DELIVER.
+ *
+ * OSK-7631 — a cloud Agent Worker turn streamed only `__seq 3`. Seq 1 and 2
+ * were never sent: no gap marker, no error, no retransmit. A user watching live
+ * saw the answer to "output the numbers 1 through 60" begin at "33", while the
+ * persisted message held all sixty. The direction is the exact mirror of
+ * OSK-7573, where the stream is right and the durable copy loses text — and it
+ * is the more dangerous of the two to leave silent, because a truncated live
+ * answer looks like a complete short answer.
+ *
+ * The web client already detects this (`client_envelope_seq_gap_detected_total`)
+ * and rehydrates the missing range from the envelope ring. The CLI had neither
+ * the detection nor the backfill, so the only correction it could make was at
+ * the terminal — which it does: `run.result` and the persisted message are
+ * authoritative and already correct here. What was missing was any admission,
+ * WHILE READING, that the text on screen is not all of it.
+ *
+ * Tracks the highest seq applied and reports the first gap. Deliberately does
+ * not try to reconstruct: a client that guesses at missing text is worse than
+ * one that says it is missing.
+ */
+export type SeqGap = {
+    from: number;
+    to: number;
+};
+export declare function detectSeqGap(highestApplied: number, incoming: number): SeqGap | null;
+export declare function seqGapNotice(gap: SeqGap): string;
 export declare class AgenticStreamClient {
     private readonly options;
     private socket;
@@ -71,19 +253,94 @@ export declare class AgenticStreamClient {
     private settled;
     private closed;
     private accumulated;
+    /** Highest envelope `__seq` folded into `accumulated`, for gap detection. */
+    private highestSeq;
+    private reportedGap;
     private readonly seenEnvelopes;
+    /**
+     * 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.
+     */
+    private readonly seenLifecycle;
+    /** `call` → tool name, so a daemon `tool-call-end` can be named (OSK-7730). */
+    private readonly toolNamesByCall;
+    /** Text already written to the terminal, for suffix-only rendering. */
+    private renderedText;
+    private idleTimer;
+    private reconciling;
     private responseMessageId;
     private 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.
+     */
+    private terminalResult;
     private resolve;
     private reject;
+    /** The terminal result, or null while the run is still in flight. */
+    settledResult(): AgenticStreamResult | null;
     constructor(options: AgenticStreamOptions);
     run(): Promise<AgenticStreamResult>;
+    /**
+     * (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.
+     */
+    private armIdleProbe;
+    /**
+     * 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).
+     */
+    probeTerminal(reason: string): Promise<boolean>;
     cancel(reason?: string): void;
     close(): void;
+    /**
+     * 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.
+     */
+    private reportSeqGap;
     private installHandlers;
     private handlePermission;
     private handleQuestion;
     private ask;
+    /**
+     * 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.
+     */
+    private firstTimeSeen;
+    /**
+     * 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.
+     */
+    private emitToolEvent;
     private emit;
     private finish;
     /**