@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/dist/shared/fingerprint-secret.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runner-held master secret for HITL approval fingerprints (Phase 2).
+ *
+ * The per-execution fingerprint key is derived from this secret + `execution_id`
+ * (see {@link file://./approval-fingerprint.ts} `deriveExecutionFingerprintKey`).
+ * Source precedence:
+ *
+ *  1. `STIGMER_RUNNER_HITL_SECRET` env var (UTF-8), when set — the only way to get
+ *     a key that is STABLE across runner processes/replicas. Required once a lease
+ *     becomes a cross-process bearer token (Phase 7); optional today.
+ *  2. A per-process random secret generated once at first use — sufficient for
+ *     Phase 2 because the fingerprint is recompute-and-compare WITHIN one runner
+ *     process for a given execution: the deep-agent gateway runs in-process, and
+ *     the Cursor key is written to and read from the per-session state file by the
+ *     same process. A process restart re-keys, which can only *re-ask* a pending
+ *     approval (fail-safe), never silently mis-authorize.
+ *
+ * The secret is never logged. The value is memoized so the per-process fallback
+ * stays stable for the lifetime of the process.
+ */
+import { type BinaryLike } from "node:crypto";
+/**
+ * Return the runner's HITL master secret (env-configured, else a stable
+ * per-process random fallback). Memoized.
+ */
+export declare function getRunnerHitlMasterSecret(): BinaryLike;

package/dist/shared/fingerprint-secret.js

@@ -0,0 +1,47 @@
+/**
+ * Runner-held master secret for HITL approval fingerprints (Phase 2).
+ *
+ * The per-execution fingerprint key is derived from this secret + `execution_id`
+ * (see {@link file://./approval-fingerprint.ts} `deriveExecutionFingerprintKey`).
+ * Source precedence:
+ *
+ *  1. `STIGMER_RUNNER_HITL_SECRET` env var (UTF-8), when set — the only way to get
+ *     a key that is STABLE across runner processes/replicas. Required once a lease
+ *     becomes a cross-process bearer token (Phase 7); optional today.
+ *  2. A per-process random secret generated once at first use — sufficient for
+ *     Phase 2 because the fingerprint is recompute-and-compare WITHIN one runner
+ *     process for a given execution: the deep-agent gateway runs in-process, and
+ *     the Cursor key is written to and read from the per-session state file by the
+ *     same process. A process restart re-keys, which can only *re-ask* a pending
+ *     approval (fail-safe), never silently mis-authorize.
+ *
+ * The secret is never logged. The value is memoized so the per-process fallback
+ * stays stable for the lifetime of the process.
+ */
+import { randomBytes } from "node:crypto";
+const ENV_VAR = "STIGMER_RUNNER_HITL_SECRET";
+let cached;
+let warned = false;
+/**
+ * Return the runner's HITL master secret (env-configured, else a stable
+ * per-process random fallback). Memoized.
+ */
+export function getRunnerHitlMasterSecret() {
+    if (cached)
+        return cached;
+    const fromEnv = process.env[ENV_VAR];
+    if (fromEnv && fromEnv.length > 0) {
+        cached = Buffer.from(fromEnv, "utf-8");
+        return cached;
+    }
+    cached = randomBytes(32);
+    if (!warned) {
+        warned = true;
+        console.warn(`[hitl-gateway] ${ENV_VAR} is not set; using a per-process random ` +
+            "fingerprint secret. Fingerprints are stable within this process only — " +
+            `set ${ENV_VAR} for a key stable across runner restarts/replicas ` +
+            "(required in Phase 7).");
+    }
+    return cached;
+}
+//# sourceMappingURL=fingerprint-secret.js.map

package/dist/shared/fingerprint-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint-secret.js","sourceRoot":"","sources":["../../src/shared/fingerprint-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAE3D,MAAM,OAAO,GAAG,4BAA4B,CAAC;AAE7C,IAAI,MAA0B,CAAC;AAC/B,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB;;;GAGG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,CAAC;QACd,OAAO,CAAC,IAAI,CACV,kBAAkB,OAAO,0CAA0C;YACnE,yEAAyE;YACzE,OAAO,OAAO,oDAAoD;YAClE,wBAAwB,CACzB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/shared/model-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Single construction point for LangChain chat models in the runner.
+ *
+ * This is the only place that translates a Stigmer registry model ID
+ * (dot-notation, e.g. "claude-haiku-4.5") into the provider's API model ID
+ * (e.g. "claude-haiku-4-5-20251001") before a client is built — so no
+ * activity can bypass the translation and 404 the provider.
+ *
+ * Layering: `llm-proxy.ts` stays pure routing utilities (no LangChain
+ * dependency); this module is the LangChain-aware layer above it that owns
+ * the resolve -> infer-provider -> strip-prefix -> proxy-wire -> construct
+ * sequence that used to be copy-pasted across every LLM activity.
+ */
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { type LlmProvider } from "./llm-proxy.js";
+export interface BuildChatModelOptions {
+    /** Registry id ("claude-haiku-4.5"), "provider:model", or a provider API id. */
+    readonly modelName: string;
+    /** When set, requests route through the Stigmer proxy at the provider path. */
+    readonly proxyEndpoint?: string;
+    readonly stigmerToken?: string;
+    /** Scope headers for proxy FGA/billing attribution. */
+    readonly headerScope?: {
+        executionId?: string;
+        mcpServerId?: string;
+        workflowExecutionId?: string;
+    };
+    /** Defaults to 0. */
+    readonly temperature?: number;
+    /**
+     * Pass-through only; intentionally no default. Anthropic requires a value,
+     * but callers differ (setup omits it, call-llm uses 4096), so the default
+     * stays the caller's decision to avoid silently changing behavior.
+     */
+    readonly maxTokens?: number;
+    readonly timeoutMs?: number;
+    readonly maxRetries?: number;
+}
+export interface BuiltChatModel {
+    readonly model: BaseChatModel;
+    readonly provider: LlmProvider;
+    /** The resolved id actually handed to the provider. */
+    readonly apiModelId: string;
+}
+/**
+ * Build a configured chat model, resolving the registry id to a provider API
+ * id first. The resolution MUST precede provider inference and prefix
+ * stripping — that ordering is the invariant each per-site copy kept dropping,
+ * surfacing as `404 model: claude-haiku-4.5` at the provider.
+ */
+export declare function buildChatModel(opts: BuildChatModelOptions): Promise<BuiltChatModel>;

package/dist/shared/model-client.js

@@ -0,0 +1,77 @@
+/**
+ * Single construction point for LangChain chat models in the runner.
+ *
+ * This is the only place that translates a Stigmer registry model ID
+ * (dot-notation, e.g. "claude-haiku-4.5") into the provider's API model ID
+ * (e.g. "claude-haiku-4-5-20251001") before a client is built — so no
+ * activity can bypass the translation and 404 the provider.
+ *
+ * Layering: `llm-proxy.ts` stays pure routing utilities (no LangChain
+ * dependency); this module is the LangChain-aware layer above it that owns
+ * the resolve -> infer-provider -> strip-prefix -> proxy-wire -> construct
+ * sequence that used to be copy-pasted across every LLM activity.
+ */
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+import { inferProvider, stripProviderPrefix, resolveProxyBaseUrl, buildProxyHeaders, } from "./llm-proxy.js";
+import { resolveToApiModelId } from "./model-registry.js";
+/**
+ * Build a configured chat model, resolving the registry id to a provider API
+ * id first. The resolution MUST precede provider inference and prefix
+ * stripping — that ordering is the invariant each per-site copy kept dropping,
+ * surfacing as `404 model: claude-haiku-4.5` at the provider.
+ */
+export async function buildChatModel(opts) {
+    const resolved = await resolveToApiModelId(opts.modelName);
+    const provider = inferProvider(resolved);
+    const apiModelId = stripProviderPrefix(resolved);
+    const baseUrl = opts.proxyEndpoint
+        ? resolveProxyBaseUrl(opts.proxyEndpoint, provider)
+        : undefined;
+    const headers = opts.proxyEndpoint && opts.stigmerToken
+        ? buildProxyHeaders(opts.stigmerToken, opts.headerScope ?? {})
+        : undefined;
+    // Proxy mode authenticates with the Stigmer token; direct mode falls back to
+    // the provider's own env-var key.
+    const apiKey = opts.proxyEndpoint
+        ? (opts.stigmerToken ?? "proxy-managed")
+        : provider === "openai"
+            ? (process.env.OPENAI_API_KEY ?? "")
+            : (process.env.ANTHROPIC_API_KEY ?? "");
+    const common = {
+        temperature: opts.temperature ?? 0,
+        apiKey,
+        ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
+        ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0, timeout: opts.timeoutMs } : {}),
+    };
+    // The two SDKs name the transport-override block differently (OpenAI:
+    // `configuration`, Anthropic: `clientOptions`) — encapsulating that here is
+    // the whole point, since the shape mismatch is where bugs used to hide.
+    const model = provider === "openai"
+        ? new ChatOpenAI({
+            model: apiModelId,
+            ...common,
+            ...(baseUrl || headers
+                ? {
+                    configuration: {
+                        ...(baseUrl ? { baseURL: baseUrl } : {}),
+                        ...(headers ? { defaultHeaders: headers } : {}),
+                    },
+                }
+                : {}),
+        })
+        : new ChatAnthropic({
+            model: apiModelId,
+            ...common,
+            ...(baseUrl || headers
+                ? {
+                    clientOptions: {
+                        ...(baseUrl ? { baseURL: baseUrl } : {}),
+                        ...(headers ? { defaultHeaders: headers } : {}),
+                    },
+                }
+                : {}),
+        });
+    return { model, provider, apiModelId };
+}
+//# sourceMappingURL=model-client.js.map

package/dist/shared/model-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-client.js","sourceRoot":"","sources":["../../src/shared/model-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAiC1D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAA2B;IAC9D,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAEjD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa;QAChC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC;QACnD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,YAAY;QACrD,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9D,CAAC,CAAC,SAAS,CAAC;IAEd,6EAA6E;IAC7E,kCAAkC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa;QAC/B,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,IAAI,eAAe,CAAC;QACxC,CAAC,CAAC,QAAQ,KAAK,QAAQ;YACrB,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;YACpC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAG;QACb,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC;QAClC,MAAM;QACN,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzF,CAAC;IAEF,sEAAsE;IACtE,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,KAAK,GAAkB,QAAQ,KAAK,QAAQ;QAChD,CAAC,CAAC,IAAI,UAAU,CAAC;YACb,KAAK,EAAE,UAAU;YACjB,GAAG,MAAM;YACT,GAAG,CAAC,OAAO,IAAI,OAAO;gBACpB,CAAC,CAAC;oBACE,aAAa,EAAE;wBACb,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACxC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAChD;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;QACJ,CAAC,CAAC,IAAI,aAAa,CAAC;YAChB,KAAK,EAAE,UAAU;YACjB,GAAG,MAAM;YACT,GAAG,CAAC,OAAO,IAAI,OAAO;gBACpB,CAAC,CAAC;oBACE,aAAa,EAAE;wBACb,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACxC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAChD;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;IAEP,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AACzC,CAAC"}

package/dist/shared/plan-artifact.js

@@ -69,14 +69,12 @@ export async function publishPlanArtifact(opts) {
         const contentHash = createHash("sha256").update(content).digest("hex");
         const storageKey = `artifacts/${executionId}/${PLAN_ARTIFACT_NAME}`;
         await artifactStorage.upload(storageKey, content, "text/markdown");
-        const downloadUrl = await artifactStorage.getDownloadUrl(storageKey);
         const artifact = create(ExecutionArtifactSchema, {
             name: PLAN_ARTIFACT_NAME,
             sandboxPath: PLAN_ARTIFACT_SANDBOX_PATH,
             kind: ExecutionArtifactKind.FILE,
             sizeBytes: BigInt(content.length),
             storageKey,
-            downloadUrl,
             createdAt: utcTimestamp(),
             contentHash,
         });

package/dist/shared/plan-artifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-artifact.js","sourceRoot":"","sources":["../../src/shared/plan-artifact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-artifact.js","sourceRoot":"","sources":["../../src/shared/plan-artifact.ts"],"names":[],"mappings":"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"}

package/dist/shared/status-offload.d.ts

@@ -3,8 +3,10 @@
  *
  * Tool outputs (an MCP screenshot's base64 image, a giant accessibility-tree
  * dump, a multi-MB shell log, a huge file write) are stored inline in
- * `ToolCall.result`/`args_preview`, which live in `status.messages` and are
- * re-serialized whole on every `persistStatus` -> `updateStatus` gRPC call.
+ * `ToolCall.result`/`args_preview`, which live in `status.messages` AND in
+ * each `status.sub_agent_executions[].messages` (a delegated tool call's
+ * result is just as unbounded), and are re-serialized whole on every
+ * `persistStatus` -> `updateStatus` gRPC call.
  * Left unchecked, a single large result pushes the message past the server's
  * 4 MiB gRPC receive cap; the call fails with `resource_exhausted`, progress
  * stops persisting, and the live UI freezes mid-execution.
@@ -20,12 +22,22 @@
  *      Idempotent and content-hash-deduped so the throttled, repeated persists
  *      (and result re-inflation by mergeToolCallEvent) upload each blob once.
  *
- *   2. enforceStatusSizeLimit — an aggregate, type-agnostic backstop that runs
+ *   2. offloadCandidateChangesToFit — an aggregate, storage-backed step for the
+ *      file-review ledger: if the status still exceeds the soft cap after (1),
+ *      it offloads the largest still-inline captured before/after bodies to
+ *      retrievable refs (biggest-first) until it fits, so a captured file stays
+ *      REVIEWABLE (the UI lazily fetches the ref) instead of being dropped. The
+ *      persisted body is a display projection — reconcile sources bytes from the
+ *      git refs / CAS manifest, never this body — so this is correctness-neutral.
+ *
+ *   3. enforceStatusSizeLimit — an aggregate, type-agnostic backstop that runs
  *      even when no artifact storage is available: if the encoded status still
  *      exceeds a soft cap (comfortably under 4 MiB), it elides the largest
- *      remaining inline fields in place until the payload fits.
+ *      remaining inline fields in place until the payload fits. For file-review
+ *      bodies this is the LAST resort (no storage, or (2) could not free enough):
+ *      the body is dropped and the file marked SIZE_ELIDED / incomplete.
  *
- * Both operate ONLY on what is persisted/streamed; the agent's working context
+ * All operate ONLY on what is persisted/streamed; the agent's working context
  * is managed by the harness/SDK separately, so reasoning is unaffected.
  */
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
@@ -37,6 +49,13 @@ import type { ArtifactStorage } from "./artifact-storage.js";
  * even a handful of large-but-sub-threshold results cannot aggregate past it.
  */
 export declare const INLINE_TOOL_OUTPUT_MAX_BYTES: number;
+/**
+ * A single FileChange before/after body larger than this is offloaded to
+ * artifact storage. Smaller than the 256 KiB tool-output cap because a file
+ * change can carry two bodies (before + after) per change and several changes
+ * per tool call, so the aggregate would otherwise climb quickly.
+ */
+export declare const INLINE_FILE_CONTENT_MAX_BYTES: number;
 /** Head of an offloaded text result kept inline for an at-a-glance preview. */
 export declare const TEXT_PREVIEW_HEAD_CHARS = 4000;
 /**
@@ -49,21 +68,44 @@ export declare const STATUS_PAYLOAD_SOFT_LIMIT_BYTES: number;
  * large, to maximize the chance the retry succeeds.
  */
 export declare const STATUS_PAYLOAD_HARD_LIMIT_BYTES: number;
+/**
+ * Marker left in place of an aggregate-elided inline field. Exported so the
+ * resume-time exact-apply resolver can recognize (and refuse to write) an elided
+ * body rather than corrupting a file with the marker text — the lossy elision is
+ * the one case where the exact approved bytes are unrecoverable and exact-apply
+ * must fall back. The two sides cannot drift because they share this constant.
+ */
+export declare const ELISION_MARKER = "[output elided to keep status under the size limit]";
 export interface ToolOutputOffloadContext {
     readonly artifactStorage: ArtifactStorage;
     readonly executionId: string;
     /** Override the per-result byte threshold (tests use a small value). */
     readonly maxInlineBytes?: number;
+    /** Override the per-file-content-body byte threshold (tests use a small value). */
+    readonly maxInlineFileBytes?: number;
 }
 interface ImagePayload {
     readonly base64: string;
     readonly mimeType: string;
 }
 /**
- * Best-effort extraction of an inline base64 image from a tool result string.
- * Handles a raw data URL, MCP image content blocks ({type:"image", data,
- * mimeType}) and OpenAI-style image_url blocks. Returns null for non-image or
- * unparseable results so the caller falls back to text offload.
+ * Best-effort extraction of an inline image from a tool result string.
+ *
+ * An MCP tool that returns an image (e.g. a computer-use screenshot) must be
+ * lifted into a renderable `ToolCallOutputRef`; otherwise it persists as text
+ * and the UI shows raw JSON / "view full output" instead of the picture. The
+ * image can arrive in many wrappers depending on the harness and whether the
+ * result was pre-serialized, so detection looks for an UNAMBIGUOUS image signal
+ * rather than a fixed envelope position:
+ *
+ *   1. a `data:image/*;base64,...` URL anywhere in the string, then
+ *   2. a recognized image block at any depth of a JSON result
+ *      (see {@link imageFromBlock}).
+ *
+ * Returns null for non-image or unparseable results so the caller falls back to
+ * text offload. It deliberately does NOT treat a bare base64 string with no
+ * image marker as an image — that would misclassify legitimate large text
+ * (logs, base64-encoded files) as pictures.
  */
 export declare function detectImagePayload(result: string): ImagePayload | null;
 /**
@@ -71,8 +113,40 @@ export declare function detectImagePayload(result: string): ImagePayload | null;
  * replacing the inline value with a short head + ToolCallOutputRef. Per-tool
  * failures fall back to an inline truncation (a bounded result beats a failed
  * persist) and never throw, so a storage hiccup cannot fail the execution.
+ *
+ * File-review before/after bodies (on the CANDIDATE_CAPTURED ledger events) are
+ * offloaded in the same pass — a tool can produce a small result yet a large
+ * captured diff. A file-review offload failure is non-fatal — the body stays
+ * inline and the aggregate backstop (enforceStatusSizeLimit) drops it if needed.
  */
 export declare function offloadOversizedToolOutputs(status: AgentExecutionStatus, ctx: ToolOutputOffloadContext): Promise<void>;
+/**
+ * Aggregate-budget offload of file-review candidate bodies (async, storage-backed).
+ *
+ * The per-item pass ({@link offloadOversizedToolOutputs}) only offloads a body
+ * over {@link INLINE_FILE_CONTENT_MAX_BYTES}; many mid-sized captured files (each
+ * under that per-file cap) can still sum the whole status past the soft limit.
+ * Rather than let the storage-less backstop ({@link enforceStatusSizeLimit}) DROP
+ * those bodies — which sets `diff_complete=false` and blocks approval, turning a
+ * reviewable change discard-only — this step offloads the largest still-inline
+ * captured bodies to retrievable refs (biggest-first) until the status fits. The
+ * review UI then lazily fetches each ref via getArtifactContent exactly as it
+ * already does for a >128 KiB file, and the change stays reviewable
+ * (`diff_complete` is untouched, so the set rollup is unchanged).
+ *
+ * Correctness: the persisted before/after body is a DISPLAY projection —
+ * reconcile sources the approved bytes from the pinned git refs / CAS manifest
+ * and verifies them against the enforcement digests (`before_sha256`/
+ * `after_sha256`), never this body (see {@link ../filereview/capture.js}). So
+ * converting a body to a ref (or, in the backstop, dropping it) cannot change
+ * what is applied on approval.
+ *
+ * Non-fatal per side: a storage failure leaves that body inline for the backstop
+ * to drop. Returns true if any body was offloaded. Called only for a status that
+ * actually carries file-review events (the caller guards on that), and a no-op
+ * (single encode) when the status already fits.
+ */
+export declare function offloadCandidateChangesToFit(status: AgentExecutionStatus, ctx: ToolOutputOffloadContext, softLimitBytes?: number): Promise<boolean>;
 /**
  * Aggregate, type-agnostic backstop. If the encoded status exceeds
  * `softLimitBytes`, elide the largest inline tool fields (and, as a last