@skrr-ai/cli 0.1.44 → 0.1.46

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

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr tasks promote` — settle a parallel group (B8).
+ *
+ * This is the destructive half of fork/race: fixing one branch as canonical
+ * CANCELS every live loser in the group. That is why it is its own verb with
+ * its own confirmation rather than a flag, and why the command prints what it
+ * cancelled rather than reporting only the winner.
+ */
+export default class TasksPromote extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        run: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'group-member': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/promote.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const task_extras_1 = require("../../lib/task-extras");
+const task_resolver_1 = require("../../lib/task-resolver");
+/**
+ * `skrr tasks promote` — settle a parallel group (B8).
+ *
+ * This is the destructive half of fork/race: fixing one branch as canonical
+ * CANCELS every live loser in the group. That is why it is its own verb with
+ * its own confirmation rather than a flag, and why the command prints what it
+ * cancelled rather than reporting only the winner.
+ */
+class TasksPromote extends base_command_1.BaseCommand {
+    static description = 'Fix one branch of a parallel run group as canonical and cancel the live losers (B8)';
+    static examples = [
+        '<%= config.bin %> tasks promote <task-id> --run <run-id>',
+        '<%= config.bin %> tasks promote <task-id> --run <run-id> --json',
+    ];
+    static args = {
+        id: core_1.Args.string({
+            description: 'Task ID; defaults to OVERSKY_SESSION_TASK_ID in task runtimes',
+            required: false,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the resolution as JSON' }),
+        task: core_1.Flags.string({ description: 'Task ID; overrides daemon runtime context' }),
+        run: core_1.Flags.string({
+            description: 'The run to make canonical — must be a member of the parallel group',
+            required: true,
+        }),
+        'group-member': core_1.Flags.string({
+            description: 'Any run in the group to address it by (default: the canonical run itself, which is ' +
+                'always a member)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksPromote);
+        let taskIdentity;
+        try {
+            taskIdentity = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.id, flagTask: flags.task });
+        }
+        catch (err) {
+            const failure = (0, task_resolver_1.taskResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: { suggestion: failure.suggestion, context: failure.details },
+            });
+        }
+        const taskId = taskIdentity.id;
+        // The route resolves the GROUP from the addressed run, then requires the
+        // canonical run to be a member of it. Addressing by the canonical run
+        // itself is always valid and is the obvious default.
+        const addressedRunId = flags['group-member'] ?? flags.run;
+        let result;
+        try {
+            result = await (0, task_extras_1.taskRunPromote)(taskId, addressedRunId, { canonicalRunId: flags.run });
+        }
+        catch (err) {
+            this.handleApiError(err, { subject: `Task ${taskId}` });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const r = result;
+        const cancelled = Array.isArray(r.cancelledRunIds) ? r.cancelledRunIds.map(String) : [];
+        this.log(`Canonical run: ${r.canonicalRunId ?? flags.run}`);
+        this.log(`Parallel group: ${r.groupId ?? '?'}`);
+        this.log(cancelled.length
+            ? `Cancelled ${cancelled.length} losing run(s): ${cancelled.join(', ')}`
+            : 'Cancelled no runs — every other branch had already finished.');
+    }
+}
+exports.default = TasksPromote;

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

@@ -16,6 +16,22 @@ export declare function formatRunExecutor(run: Record<string, unknown>): string;
  * list, always once something failed.
  */
 export declare function runNeedsFailureReason(run: Record<string, unknown>): boolean;
+/**
+ * The handover fields a run row may carry (execution-handover impl contracts):
+ *
+ *   `handover`      — the packet stamped on a run ADMITTED BY a handover; this
+ *                     run is the continuation, `packet.from.runId` is where it
+ *                     resumed from.
+ *   `handoverOffer` — the structured offer a retargetable terminal failure
+ *                     leaves behind (`{failureReason, resetAt?, actedRunId?}`).
+ *                     `actedRunId` means the offer was taken and names the
+ *                     continuation run.
+ *
+ * Both are absent on a server that predates them, so this returns null and the
+ * column below is rendered only when at least one row carries a marker — a
+ * healthy list against an older deployment pays and shows nothing.
+ */
+export declare function runHandoverMarker(run: Record<string, unknown>): string | null;
 /**
  * The run's OWN failure fields, when the server carries them.
  *

package/dist/commands/tasks/runs.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatRunExecutor = formatRunExecutor;
 exports.runNeedsFailureReason = runNeedsFailureReason;
+exports.runHandoverMarker = runHandoverMarker;
 exports.failureFromRun = failureFromRun;
 exports.renderRunFailures = renderRunFailures;
 const core_1 = require("@oclif/core");
@@ -46,6 +47,42 @@ function runNeedsFailureReason(run) {
         return true;
     return typeof run.errors === 'number' && run.errors > 0;
 }
+/**
+ * The handover fields a run row may carry (execution-handover impl contracts):
+ *
+ *   `handover`      — the packet stamped on a run ADMITTED BY a handover; this
+ *                     run is the continuation, `packet.from.runId` is where it
+ *                     resumed from.
+ *   `handoverOffer` — the structured offer a retargetable terminal failure
+ *                     leaves behind (`{failureReason, resetAt?, actedRunId?}`).
+ *                     `actedRunId` means the offer was taken and names the
+ *                     continuation run.
+ *
+ * Both are absent on a server that predates them, so this returns null and the
+ * column below is rendered only when at least one row carries a marker — a
+ * healthy list against an older deployment pays and shows nothing.
+ */
+function runHandoverMarker(run) {
+    const packet = run.handover;
+    if (packet && typeof packet === 'object') {
+        const from = packet.from;
+        const fromRun = from &&
+            typeof from === 'object' &&
+            typeof from.runId === 'string'
+            ? ` ← ${String(from.runId)}`
+            : '';
+        return `handover${fromRun}`;
+    }
+    const offer = run.handoverOffer;
+    if (offer && typeof offer === 'object') {
+        const o = offer;
+        if (o.actedRunId)
+            return `offer → ${String(o.actedRunId)}`;
+        const reason = typeof o.failureReason === 'string' ? o.failureReason : '';
+        return `offer${reason ? `:${reason}` : ''}`;
+    }
+    return null;
+}
 /**
  * The run's OWN failure fields, when the server carries them.
  *
@@ -151,13 +188,20 @@ class TasksRuns extends base_command_1.BaseCommand {
             this.log('No runs.');
             return;
         }
-        const rows = items.map((run) => ({
+        const markers = items.map(runHandoverMarker);
+        // The column exists only when a run carries a handover field — an older
+        // deployment sends neither, and an always-on column of '-' is noise.
+        const showHandover = markers.some(Boolean);
+        const rows = items.map((run, i) => ({
             runId: String(run.runId ?? run.id ?? run._id ?? '-'),
             status: String(run.status ?? '-'),
             executor: formatRunExecutor(run),
             started: run.startedAt ? (0, format_1.localTime)(run.startedAt) : '-',
             duration: run.durationMs != null ? `${run.durationMs}ms` : '-',
             tokens: String(run.totalTokens ?? run.tokens ?? '-'),
+            // Always present on the row so the record type stays uniform; the COLUMN
+            // is what is conditional.
+            handover: markers[i] ?? '-',
         }));
         (0, format_1.renderTable)(rows, [
             { key: 'runId', header: 'RUN ID' },
@@ -166,6 +210,7 @@ class TasksRuns extends base_command_1.BaseCommand {
             { key: 'started', header: 'STARTED' },
             { key: 'duration', header: 'DURATION' },
             { key: 'tokens', header: 'TOKENS' },
+            ...(showHandover ? [{ key: 'handover', header: 'HANDOVER' }] : []),
         ], (line) => this.log(line));
         // Only once something failed: a healthy list pays nothing for this.
         if (!unexplained)

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

@@ -20,6 +20,13 @@ export declare function taskPointerLines(t: Record<string, unknown>, ref: string
  * be read (or a label missing from it) degrades per entry rather than failing
  * the command or hiding the label.
  */
+/**
+ * The lines that say what a blocked Task is waiting on.
+ *
+ * Kept pure so the rule is testable without a network: the command fetches the
+ * newest `blocker` Update and hands its payload here.
+ */
+export declare function blockerDetailLines(detail: Record<string, unknown> | undefined): string[];
 export declare function labelsLine(labelIds?: string[], nameById?: Map<string, string>): string;
 /**
  * The `Executor:` value — who does this task, and whether anyone said so.
@@ -73,4 +80,20 @@ export default class TasksShow extends BaseCommand {
         'no-enrich': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * What a blocked Task is actually waiting on.
+     *
+     * The workflow tells an agent to record a typed `blocker` Update —
+     * `{cause, requiredAction, nextOwner}` — and only then move the Task to
+     * blocked. The move writes its own exceptional hold, whose summary is the
+     * `--reason` flag or the literal fallback `Task was marked blocked`, and that
+     * is what `Why:` prints. So the one line a reader looks at restated the
+     * status, while the thing the writer was told to record sat one command away
+     * in `tasks updates list` (OSK-10391).
+     *
+     * Read only for a blocked Task, and only the newest blocker Update. A failure
+     * here prints nothing: this decorates an answer the caller already has, and
+     * must never be the reason `tasks show` cannot answer at all.
+     */
+    private printBlockerDetail;
 }

package/dist/commands/tasks/show.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.taskPointerLines = taskPointerLines;
+exports.blockerDetailLines = blockerDetailLines;
 exports.labelsLine = labelsLine;
 exports.taskExecutorLabel = taskExecutorLabel;
 exports.taskFailureLines = taskFailureLines;
@@ -52,6 +53,29 @@ function taskPointerLines(t, ref, bin = 'skrr') {
  * be read (or a label missing from it) degrades per entry rather than failing
  * the command or hiding the label.
  */
+/**
+ * The lines that say what a blocked Task is waiting on.
+ *
+ * Kept pure so the rule is testable without a network: the command fetches the
+ * newest `blocker` Update and hands its payload here.
+ */
+function blockerDetailLines(detail) {
+    if (!detail)
+        return [];
+    const lines = [];
+    const cause = typeof detail.cause === 'string' ? detail.cause.trim() : '';
+    const required = typeof detail.requiredAction === 'string' ? detail.requiredAction.trim() : '';
+    const owner = detail.nextOwner;
+    if (cause)
+        lines.push(`Blocked on:  ${cause}`);
+    if (required)
+        lines.push(`Needs:       ${required}`);
+    if (owner && typeof owner.kind === 'string' && owner.kind) {
+        const who = typeof owner.userId === 'string' && owner.userId ? ` ${owner.userId}` : '';
+        lines.push(`Next owner:  ${owner.kind}${who}`);
+    }
+    return lines;
+}
 function labelsLine(labelIds, nameById) {
     const ids = (labelIds ?? []).filter((id) => typeof id === 'string' && id.length > 0);
     if (ids.length === 0)
@@ -370,6 +394,7 @@ class TasksShow extends base_command_1.BaseCommand {
         if (actionability) {
             this.log(`Next action: ${actionability.nextActor ?? '-'} · ${actionability.state ?? '-'} · ${actionability.reasonCode ?? '-'}`);
             this.log(`Why:         ${actionability.reason ?? '-'}`);
+            await this.printBlockerDetail(t, actionability);
         }
         const delivery = t.delivery;
         if (delivery?.prNumber || delivery?.prUrl || delivery?.branch) {
@@ -493,5 +518,39 @@ class TasksShow extends base_command_1.BaseCommand {
         for (const line of taskPointerLines(t, ref, this.config.bin))
             this.log(line);
     }
+    /**
+     * What a blocked Task is actually waiting on.
+     *
+     * The workflow tells an agent to record a typed `blocker` Update —
+     * `{cause, requiredAction, nextOwner}` — and only then move the Task to
+     * blocked. The move writes its own exceptional hold, whose summary is the
+     * `--reason` flag or the literal fallback `Task was marked blocked`, and that
+     * is what `Why:` prints. So the one line a reader looks at restated the
+     * status, while the thing the writer was told to record sat one command away
+     * in `tasks updates list` (OSK-10391).
+     *
+     * Read only for a blocked Task, and only the newest blocker Update. A failure
+     * here prints nothing: this decorates an answer the caller already has, and
+     * must never be the reason `tasks show` cannot answer at all.
+     */
+    async printBlockerDetail(task, actionability) {
+        const looksBlocked = String(task.status ?? '') === 'blocked' || actionability.reasonCode === 'exceptional_hold';
+        if (!looksBlocked) {
+            return;
+        }
+        try {
+            const updates = await data_provider_1.dataService.listTaskUpdates(String(task.id), {
+                limit: 1,
+                type: 'blocker',
+            });
+            const detail = updates?.data?.[0]?.data;
+            for (const line of blockerDetailLines(detail)) {
+                this.log(line);
+            }
+        }
+        catch {
+            // The status line above already answered the question this decorates.
+        }
+    }
 }
 exports.default = TasksShow;

package/dist/lib/agentic-stream.js

@@ -678,18 +678,51 @@ class AgenticStreamClient {
         if (this.closed)
             return;
         this.emit({ ...event, type: 'permission.requested' });
-        if (!this.options.approveTools || !process.stdin.isTTY || !this.socket) {
+        if (!this.options.approveTools || !this.socket) {
             if (event.toolUseId) {
                 this.socket?.emit('permission:deny', {
                     sessionId: this.options.sessionId,
                     toolUseId: event.toolUseId,
                     toolName: event.toolName,
-                    reason: 'CLI requires --approve-tools in an interactive terminal',
+                    reason: 'CLI was not started with --approve-tools',
                 });
             }
             this.emit({ ...event, type: 'permission.denied', reason: 'noninteractive_or_not_enabled' });
             return;
         }
+        /**
+         * With no terminal, `--approve-tools` IS the answer (OSK-10323).
+         *
+         * The flag used to be refused outside a TTY, and without it every
+         * permission-gated tool call was denied. So a scripted turn — the
+         * documented headless shape, `agents chat --prompt … --no-stream --json` —
+         * had `schedule_followup`, `followup_create`, `followup_list` and
+         * `followup_resolve` all rejected at the approval layer, and the agent
+         * reported its own tools as broken. No caller could answer, because the
+         * only way to answer needed a terminal.
+         *
+         * A person typing the flag is the consent, given once for this turn instead
+         * of once per call. That is a narrower grant than it sounds: it lasts one
+         * turn, it is written in the command the person ran, and every approval is
+         * announced on the stream (`auto: true`) rather than being silent. An
+         * explicit `input` still means a terminal is answering, and keeps the
+         * prompt.
+         */
+        const interactive = this.options.input !== undefined || Boolean(process.stdin.isTTY);
+        if (!interactive) {
+            this.socket.emit('permission:approve', {
+                sessionId: this.options.sessionId,
+                toolUseId: event.toolUseId,
+                toolName: event.toolName,
+            });
+            this.emit({
+                ...event,
+                type: 'permission.approved',
+                auto: true,
+                reason: 'approved by --approve-tools, which was given with no terminal to ask at',
+            });
+            return;
+        }
         const answer = await this.ask(`Allow tool ${event.toolName ?? 'unknown'}? [y/N] `);
         const approved = /^y(es)?$/i.test(answer.trim());
         this.socket.emit(approved ? 'permission:approve' : 'permission:deny', {
@@ -837,6 +870,12 @@ class AgenticStreamClient {
             output.write(`\n[${event.type}]\n`);
             this.renderedText = this.accumulated;
         }
+        else if (event.type === 'permission.approved' && event.auto === true) {
+            // Said out loud, because nobody was asked: the flag approved it, and a
+            // reader of this log should see which tools that covered (OSK-10323).
+            output.write(`\n[permission] ${String(event.toolName ?? 'unknown')} allowed by --approve-tools\n`);
+            this.renderedText = this.accumulated;
+        }
         else if (event.type === 'question.answered' && event.nonInteractive) {
             output.write('\n[question] no terminal to answer on, so the question was dismissed unanswered\n');
             this.renderedText = this.accumulated;

package/dist/lib/api-fetch.d.ts

@@ -30,7 +30,13 @@ export declare class ApiFetchError extends Error {
     readonly body?: string;
     readonly code?: string;
     readonly method?: string;
-    constructor(message: string, status: number, body?: string, code?: string, method?: string);
+    /**
+     * The server's `X-Request-ID` for the failing call, when it sent one. It is
+     * the id the server logs against, so a refusal can be looked up rather than
+     * attributed by guesswork — see `node-adapter.ts`.
+     */
+    readonly requestId?: string;
+    constructor(message: string, status: number, body?: string, code?: string, method?: string, requestId?: string);
 }
 /**
  * Call a skrr API endpoint with the current credential. Throws

package/dist/lib/api-fetch.js

@@ -54,13 +54,20 @@ class ApiFetchError extends Error {
     // (OSK-6765): `agents show` is a GET and had no body, and the advice was
     // impossible to follow.
     method;
-    constructor(message, status, body, code, method) {
+    /**
+     * The server's `X-Request-ID` for the failing call, when it sent one. It is
+     * the id the server logs against, so a refusal can be looked up rather than
+     * attributed by guesswork — see `node-adapter.ts`.
+     */
+    requestId;
+    constructor(message, status, body, code, method, requestId) {
         super(message);
         this.name = 'ApiFetchError';
         this.status = status;
         this.body = body;
         this.code = code;
         this.method = method;
+        this.requestId = requestId;
     }
 }
 exports.ApiFetchError = ApiFetchError;
@@ -209,7 +216,7 @@ async function apiFetch(pathOrUrl, opts = {}) {
         catch {
             /* ignore body read failures */
         }
-        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method);
+        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method, res.headers.get('x-request-id') || undefined);
     }
     // 204/205 carry no body by definition; an empty body has no content-type
     // worth judging. Neither is an error.

package/dist/lib/auth-core-init.js

@@ -35,7 +35,6 @@ exports.shouldUseAccessTokenForEnrollment = shouldUseAccessTokenForEnrollment;
  *     present — short-circuits silently on a fresh install before login.
  */
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const proper_lockfile_1 = __importDefault(require("proper-lockfile"));
 const auth_core_1 = require("@skrr-ai/auth-core");
@@ -86,7 +85,7 @@ async function prepareDedicatedRuntimeAuthGeneration(options = {}) {
     const machineUuid = String(options.machineUuid ?? process.env.SKRR_MACHINE_UUID ?? '').trim();
     if (!machineUuid.startsWith('dedicated-runtime:'))
         return false;
-    const configDir = options.configDir ?? node_path_1.default.join(node_os_1.default.homedir(), '.skrr');
+    const configDir = options.configDir ?? (0, auth_core_1.resolveConfigRoot)();
     node_fs_1.default.mkdirSync(configDir, { recursive: true, mode: 0o700 });
     const markerPath = node_path_1.default.join(configDir, DEDICATED_AUTH_GENERATION_MARKER);
     const release = await proper_lockfile_1.default.lock(configDir, {
@@ -145,7 +144,15 @@ function ensureAuthCoreConfigured() {
     (0, auth_core_1.configureAuthCore)({
         // Phase D: share the daemon's config root so auth.lock and the
         // needs-reauth flag are coordinated across binaries.
-        configDir: () => node_path_1.default.join(node_os_1.default.homedir(), '.skrr'),
+        //
+        // `resolveConfigRoot()`, not a fourth derivation of `~/.skrr`. This line
+        // used to compute the root itself and therefore ignored SKRR_CONFIG_DIR /
+        // OVERSKY_CONFIG_DIR — which `cli/src/lib/config.ts` honours — so an
+        // operator who relocated the root split the CLI's own credentials from its
+        // own config, and split both from the daemon, which honours it too. That is
+        // the exact defect `configRoot.ts` was written to end; see its header for
+        // the three times it was fixed locally and came back.
+        configDir: () => (0, auth_core_1.resolveConfigRoot)(),
         /**
          * The machine root, PINNED — never the active profile's directory.
          *
@@ -165,7 +172,7 @@ function ensureAuthCoreConfigured() {
          * Wired ahead of the profile work rather than with it, so the landmine is
          * gone before anything can step on it.
          */
-        machineConfigDir: () => node_path_1.default.join(node_os_1.default.homedir(), '.skrr'),
+        machineConfigDir: () => (0, auth_core_1.resolveConfigRoot)(),
         logger: cliLogger,
         killSwitches: {
             // CLI shares the same kill-switch surface as the daemon for ops parity.

package/dist/lib/code-handover.d.ts

@@ -41,6 +41,12 @@ export interface HandoverPromptInput {
     headSha?: string | null;
     recentCommits?: string | null;
     localWorkNotCarried: boolean;
+    /**
+     * A `renderSessionTranscript` block — the exported engine session, carried
+     * by `--carry-session`. Pre-rendered so this function stays a composer: it
+     * owns ordering, the renderer owns the envelope and the budget.
+     */
+    sessionTranscript?: string;
 }
 /**
  * Compose what the receiving agent reads.
@@ -51,6 +57,60 @@ export interface HandoverPromptInput {
  * is machine-collected context the agent would otherwise have to ask for.
  */
 export declare function composeHandoverPrompt(input: HandoverPromptInput): string;
+/** The contract envelope, read defensively — C2 pins the keys, not the innards. */
+export interface EngineSessionExport {
+    version?: unknown;
+    sessionId?: string;
+    messages?: unknown[];
+    /** Explicit, never inferred from length (C3). */
+    truncated?: boolean;
+    /** C4: anything the engine redacted, declared in the envelope. */
+    redactions?: unknown;
+}
+/**
+ * Parse the export envelope, or null when the output is not the contract —
+ * an engine that predates `session export` cannot produce `{version, messages[]}`.
+ */
+export declare function parseSessionExportEnvelope(stdout: string): EngineSessionExport | null;
+export type SessionExportFailureKind = 'unsupported' | 'unknown-session';
+/**
+ * Classify a failed `session export` spawn (an `execFileSync` throw).
+ *
+ * C6 makes an unknown session id a distinct outcome from a broken engine, and
+ * the distinction matters to the operator: "the engine predates the contract"
+ * is an upgrade, "that session is not there" is a different id. The contract
+ * does not pin exit codes, so the signal is the engine's own stderr — which is
+ * also what the refusal relays verbatim either way.
+ */
+export declare function classifySessionExportError(err: {
+    status?: number | null;
+    stderr?: string;
+    message?: string;
+}): {
+    kind: SessionExportFailureKind;
+    detail: string;
+};
+export interface SessionTranscriptRender {
+    /** The block to fold into the handover prompt. */
+    text: string;
+    carriedCount: number;
+    totalCount: number;
+    /** The engine declared the export itself incomplete (C3). */
+    engineTruncated: boolean;
+    /** This side dropped oldest messages to fit the prompt budget — declared. */
+    clipped: boolean;
+}
+/**
+ * Render the exported session into the handover prompt, bounded.
+ *
+ * `POST /api/cloud-coding/tasks` has no transcript field — `prompt` is the only
+ * channel that reaches the receiving agent (the zod schema strips unknown keys
+ * and caps prompt at 50000 chars). So the transcript rides inside the prompt,
+ * clipped from the FRONT: the recent tail is what continuation needs, and the
+ * clip is declared in the block itself, never inferred (C3's rule applied to
+ * our own truncation too).
+ */
+export declare function renderSessionTranscript(exported: EngineSessionExport, budget: number): SessionTranscriptRender;
 export interface AgentCandidate {
     id: string;
     name?: string;