@cerebriline/core 4.100.246 → 4.100.247

package/dist/extensions/composio/composio-meta-tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * In-chat authentication for Composio connectors.
+ *
+ * The Cline API creates a per-user Composio tool-router session scoped to the
+ * project's enabled auth configs (`POST /api/v1/connectors/meta-tools/sessions`)
+ * and returns the schemas of its allowlisted meta tools: COMPOSIO_SEARCH_TOOLS
+ * finds tools across those toolkits, COMPOSIO_MANAGE_CONNECTIONS returns a
+ * hosted Connect Link the agent surfaces in chat, COMPOSIO_WAIT_FOR_CONNECTIONS
+ * blocks until the user finishes, and COMPOSIO_MULTI_EXECUTE_TOOL runs the
+ * tools search found — no new session needed after connecting.
+ * Credentials never pass through Cline or the model — only the link does.
+ * Executions go back through the proxy with the session id
+ * (`POST /api/v1/connectors/meta-tools/{slug}/execute`), which checks that the
+ * session belongs to the caller.
+ */
+export declare const CONNECTORS_API_PATH = "/api/v1/connectors";
+export type ConnectorsAuth = {
+    baseUrl: string;
+    token: string;
+};
+export type ComposioMetaTool = {
+    slug: string;
+    name?: string;
+    description?: string;
+    input_parameters?: Record<string, unknown>;
+};
+export type ComposioMetaToolSession = {
+    sessionId: string;
+    tools: ComposioMetaTool[];
+};
+/**
+ * Creates a meta-tool session, or returns undefined when in-chat auth is
+ * unavailable: no connectable toolkits (404), a proxy without the endpoint, or
+ * any network failure. Callers then run without the meta tools.
+ */
+export declare function createComposioMetaToolSession(auth: ConnectorsAuth, options?: {
+    log?: (message: string) => void;
+}): Promise<ComposioMetaToolSession | undefined>;
+export declare function executeComposioMetaTool(auth: ConnectorsAuth, sessionId: string, slug: string, input: unknown): Promise<unknown>;

package/dist/extensions/composio/composio-tools-extension.d.ts

@@ -0,0 +1,13 @@
+import type { AgentExtension, BasicLogger } from "@cerebriline/shared";
+export declare function resolveComposioToolsStatePath(accountId: string): string;
+/**
+ * Builds the extension for the current connector state, or undefined when
+ * there is nothing to register (no state file, or no connected toolkit with
+ * tools) — sessions without connectors pay one file read.
+ *
+ * The state is read once here, at session-bootstrap time, so a session's
+ * tool set is frozen at start exactly like the previous plugin's was.
+ */
+export declare function createComposioToolsExtension(options?: {
+    logger?: BasicLogger;
+}): Promise<AgentExtension | undefined>;

package/dist/extensions/context/agentic-compaction.d.ts

@@ -25,7 +25,7 @@ export declare function buildAgenticSummaryInputBudget(options: {
 export declare const SUMMARIZER_SYSTEM_PROMPTS: {
     readonly tail: "You are re-telling your own recent work in your own voice, because the earlier part of your transcript is about to be discarded and what you write takes its place directly in front of the turns that remain. Match the prose of those turns. Keep every specific — names, paths, quoted wording, errors, numbers — that you would otherwise have to rediscover.";
     readonly full: "You write the state record for a working session of any kind. The transcript you are given is about to be discarded, so what you write is the only record that remains. Follow the requested structure exactly, section for section, and keep every specific — names, paths, quoted wording, errors, numbers — that whoever continues would otherwise have to rediscover.";
-    readonly retrospective: "You are assessing your own reasoning on work that is about to be discarded. This is judgement, not a record — what happened is written up separately. Be terse, and say only what you would want to know before starting the next hour of this task.";
+    readonly retrospective: "You are saying, in your own voice and in the present tense, how your work on this task is going, from your own reasoning on the part of it that is about to be discarded. This is what you think of it, not a record — what happened is written up separately. Plain prose, first person, short: only what you want in mind before the next hour of this task.";
 };
 /**
  * The model calls a compaction is about to make, counted before it makes them.

package/dist/extensions/context/cap-thoughts.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Thoughts the harness writes into the retrospective, in the model's voice.
+ *
+ * The retrospective is the model's own judgement of how the work went, and it
+ * is blind to the events that cost the most, because those are exactly the
+ * turns it never got to read: a reply discarded at the output limit takes its
+ * reasoning with it, a looped block is removed, a call nothing could parse
+ * never ran. The harness saw every one of them. So it says so, in the first
+ * person and the present tense like the text it sits in, as something the
+ * model has noticed about its own work -- and draws the one conclusion all of
+ * them share: the unit of work is too large.
+ *
+ * Measured on the runs this was built from (pandorum, 2026-10-10, v9-agentic):
+ * 13 replies discarded at the output limit, 21 unreadable calls and 4 looped
+ * turns across 22 sessions, nearly all on a turn that thought at length and
+ * then wrote one very large edit.
+ */
+import type { MessageWithMetadata } from "@cerebriline/shared";
+export interface CapEvents {
+    /** Replies thrown away because they ended at the output limit. */
+    outputLimit: number;
+    /** Turns whose reasoning ended because the thinking budget ran out. */
+    thinkingBudget: number;
+    /** Turns whose reasoning collapsed into repetition. */
+    loops: number;
+    /** Tool calls that came back as text and never ran. */
+    unreadableCalls: number;
+}
+/** Count the events since the last compaction, from what the messages carry. */
+export declare function countCapEvents(messages: readonly MessageWithMetadata[], budgetMessage?: string): CapEvents;
+/**
+ * The thought, or nothing when there is nothing to have noticed.
+ *
+ * One paragraph. It names what happened with its count, says what it cost,
+ * and ends on what to do instead -- smaller units, shorter reasoning, acting
+ * in sequence. The advice is the same whichever event fired, because the
+ * cause is.
+ */
+export declare function synthesizeCapThoughts(events: CapEvents): string | undefined;

package/dist/extensions/context/compaction-shared.d.ts

@@ -10,6 +10,14 @@ export declare const DEFAULT_MAX_INPUT_TOKENS = 128000;
 export declare const CONTEXT_WINDOW_INPUT_RATIO = 0.9;
 /** Compact once the transcript consumes this share of the usable input budget. */
 export declare const COMPACTION_TRIGGER_RATIO = 0.9;
+/**
+ * Upper bound on how far the provider's actual input count may scale the
+ * compaction budget down relative to the character-based estimate. Dense
+ * content realistically tokenizes ~2-3x denser than the 3-chars-per-token
+ * assumption; the cap stops a pathologically small estimate from collapsing
+ * the budget and compacting every turn.
+ */
+export declare const MAX_INPUT_UNDERESTIMATE_FACTOR = 4;
 export declare const DEFAULT_TARGET_RATIO = 0.7;
 export declare const DEFAULT_PRESERVE_RECENT_TOKENS = 20000;
 /**
@@ -314,6 +322,29 @@ export declare function collectUserRequests(messages: readonly MessageWithMetada
 export declare function findFirstUserMessageIndex(messages: MessageWithMetadata[]): number;
 export declare function findLastTurnStartIndex(messages: MessageWithMetadata[]): number;
 export declare function findLastAssistantIndex(messages: MessageWithMetadata[]): number;
+/** What the agent runtime stamps on a turn whose content it replaced. */
+export declare function isSpoiledTurn(message: MessageWithMetadata): boolean;
+/**
+ * The transcript without a spoiled turn at its end.
+ *
+ * A turn that looped in its reasoning, or wrote a tool call nothing could
+ * read, has already had that content replaced by a note. If it is also the
+ * last thing in the transcript when compaction runs, it is the newest message
+ * and so the first one the recency tail keeps -- and what the model then reads
+ * straight after its replay is a turn in which it did nothing but fail.
+ * Measured before the content was replaced at all (pandorum, 2026-10-10): an
+ * unreadable call survived the compaction it caused and was written again,
+ * unchanged, four more times.
+ *
+ * So the tail is the messages before it, and it is not summarised either:
+ * nothing happened in it. Only when the turn called nothing. A looped turn
+ * that still ended on a tool call did something, the call and its result are
+ * the record of that, and they stay.
+ *
+ * The reminders the harness appended in answer to the turn go with it. They
+ * describe a turn that is no longer there.
+ */
+export declare function withoutTrailingSpoiledTurn(messages: MessageWithMetadata[]): MessageWithMetadata[];
 export declare function findLatestSummaryIndex(messages: MessageWithMetadata[]): number;
 /**
  * The share of the material after a pinned prompt that a compaction folds when
@@ -524,7 +555,7 @@ export declare function buildSummaryRequest(options: {
  * behaviour it is meant to flag. Hence the ban on specifics -- those are in the
  * summary, and repeating them here spends the budget twice for one fact.
  */
-export declare const DEFAULT_THINKING_COMPACTION_PROMPT = "You are writing the retrospective that goes at the top of your own context after compaction. It is not a summary \u2014 what happened is written up separately, and repeating it here wastes the space this needs.\n\nYou are reading your own reasoning from the work about to be discarded, together with what each stretch of it produced: which tool calls landed, which were refused, which were retried unchanged, and which turns ran long.\n\nWrite the honest assessment. Be terse. Every line must be something you would want to know before starting the next hour of this task.\n\n## What worked\nApproaches that produced progress, stated as approaches rather than as events.\n\n## What did not\nApproaches that cost time and produced nothing. Name the failure mode: repeating an unchanged call, editing from a stale read, rewriting where narrowing would do, chasing a symptom.\n\n## Where the time went\nThe stretches that were expensive against what they achieved, including any turn where the reasoning ran long without converging.\n\n## Do differently\nWhat to do instead. Concrete enough to act on, short enough to remember.\n\nRules:\n- No file names, line numbers, code, identifiers or values. Those are in the summary. This is about method.\n- No narration of the sequence of events. Judgement only.\n- Leave out any section with nothing worth saying.\n- Terse throughout. A dozen short lines is a good retrospective; a page is a failed one.";
+export declare const DEFAULT_THINKING_COMPACTION_PROMPT = "You are writing down what you now think about how this work has been going. It goes back into your own context after compaction, beside the replay of what happened, and you will read it as your own thought \u2014 so write it as the thought you are having right now, not as a report on a session.\n\nYou are reading your own reasoning from the work about to be discarded, together with what each stretch of it produced: which tool calls landed, which were refused, which were retried unchanged, and which turns ran long.\n\nWrite in the **first person, present tense**, in plain prose, in the same voice as the replay. You are not assessing something finished: you are in the middle of the work and saying how it is going. No headings, no bullet lists, no preamble, no sign-off.\n\nSay, in whatever order the thought runs:\n\n- what is working \u2014 the approaches that are producing progress, as approaches rather than as events;\n- what is not \u2014 the approaches that cost time and produce nothing, with the failure named: repeating an unchanged call, editing from a stale read, rewriting where narrowing would do, chasing a symptom;\n- where the time is going \u2014 the stretches that are expensive against what they achieve, including any turn where the reasoning runs long without converging;\n- what you do differently from here \u2014 concrete enough to act on, short enough to remember.\n\nSentences that open the way these do are the right shape: \"What is working is \u2026\", \"What keeps costing me is \u2026\", \"Most of my time is going into \u2026\", \"From here I \u2026\".\n\nRules:\n- No file names, line numbers, code, identifiers or values. Those are in the replay. This is about method.\n- No narration of the sequence of events. What you think of it, not what happened.\n- Leave out anything with nothing worth saying.\n- Short. A dozen sentences is a good one; a page is a failed one.";
 export declare function buildThinkingSummaryRequest(options: {
     previousThinkingSummary?: string;
     reasoningText: string;
@@ -548,6 +579,35 @@ export declare function resolveSummarizerConfig(options: {
      */
     outputTokenCap?: number;
 }): ProviderConfig;
+/** The retrospective and what the harness adds to it, as one text. */
+export declare function composeRetrospective(thinkingSummary: string | undefined, harnessThoughts: string | undefined): string;
+/** Marks the synthetic turn below, for the code that has to recognise it. */
+export declare const COMPACTION_RETROSPECTIVE_KIND = "compaction_retrospective";
+export declare function isRetrospectiveTurn(message: MessageWithMetadata): boolean;
+/**
+ * The retrospective as a turn of the model's own, carried as its reasoning.
+ *
+ * As a text block in the summary it is something the model is told. The point
+ * of it is the opposite: that the model comes back from a compaction having
+ * already thought about how the work has been going -- including what the
+ * harness saw and it could not -- and acts on that as it acts on any thought
+ * of its own. That needs an assistant turn, because reasoning is only valid
+ * on one; a reasoning part on the summary itself, which has the user role,
+ * failed at the wire the first time it was tried.
+ *
+ * `pinnedReasoning` is what keeps it there. The replay policy sends back only
+ * the newest reasoning, and this turn stops being the newest on the very next
+ * request; the provider layer honours the pin where the server renders the
+ * field, and sends the same words as the turn's text where it does not, so
+ * the retrospective is never dropped and never sent as unsigned reasoning to
+ * an API that would refuse it.
+ *
+ * Only with a kept tail. A request cannot end on an assistant message, and a
+ * harness note appended after it would put a user turn between it and the
+ * model's next thought -- which, on the servers this is for, is exactly what
+ * removes earlier reasoning from the prompt.
+ */
+export declare function buildRetrospectiveTurn(text: string): MessageWithMetadata;
 export declare function buildSummaryMessage(options: {
     summary: string;
     fileOps: FileOperationSummary;
@@ -556,6 +616,21 @@ export declare function buildSummaryMessage(options: {
     generation?: number;
     /** The retrospective, prepended as this message's own reasoning. */
     thinkingSummary?: string;
+    /**
+     * What the harness adds to the retrospective in the model's own voice --
+     * see `synthesizeCapThoughts`.
+     *
+     * Shown with the retrospective and not stored as part of it: the next
+     * compaction hands `metadata.thinkingSummary` back as the previous
+     * retrospective, and a count of this generation's events fed into that
+     * would be restated as if it still described the work.
+     */
+    harnessThoughts?: string;
+    /**
+     * The retrospective travels in a turn of its own, as that turn's reasoning
+     * (see {@link buildRetrospectiveTurn}), so it is left out of this message.
+     */
+    retrospectiveAsTurn?: boolean;
     /**
      * The measured record of the tool calls being folded, appended after the
      * summary — see {@link renderToolLedger}.

package/dist/extensions/context/compaction.d.ts

@@ -1,6 +1,6 @@
-import { type PrepareTurnUsage } from "@cerebriline/shared";
+import { type MessageWithMetadata, type PrepareTurnUsage } from "@cerebriline/shared";
 import { type SessionCompactionState } from "../../session/models/session-compaction";
-import type { CoreCompactionContext, CoreCompactionMode, CoreSessionConfig } from "../../types/config";
+import type { CoreCompactionConfig, CoreCompactionContext, CoreCompactionMode, CoreSessionConfig } from "../../types/config";
 import { type CompactionJournal } from "./compaction-journal";
 export interface ContextPipelinePrepareTurnInput {
     agentId: string;
@@ -35,6 +35,25 @@ export interface ContextPipelinePrepareTurnInput {
      * (`compact_agents`). Runs as a manual compaction on this turn.
      */
     compactionRequested?: boolean;
+    /**
+     * Actual provider-reported input tokens for the previous request this run,
+     * used as a floor on the char-based estimate so dense content still triggers
+     * compaction. See AgentPrepareTurnContext.previousRequestInputTokens.
+     */
+    previousRequestInputTokens?: number;
+    /**
+     * The transcript as the session holds it, when a stage ahead of this one
+     * rewrote a message in `messages`.
+     *
+     * A saved compaction is matched to the transcript by a hash of everything
+     * it replaced. Hashed over a rewritten transcript, it matches only while
+     * the same rewrite is applied -- and the capped-thinking condenser rewrites
+     * the newest turn that reasoned, which is a different turn one request
+     * later. Measured on pandorum (2026-10-11): a compaction to 39,341 tokens,
+     * and the very next request sent all 83,853 again and compacted a second
+     * time. The hash is taken over this, which no stage rewrites.
+     */
+    sourceMessages?: CoreCompactionContext["messages"];
     emitStatusNotice?: (message: string, metadata?: Record<string, unknown>) => void;
     /**
      * Count what this preparation spent on the model. Every call of a
@@ -67,6 +86,8 @@ export interface ContextCompactionPrepareTurnOptions {
      * must never close the lead.
      */
     sideCallOf?: string;
+    /** Overrides layered over `config.compaction`. */
+    compaction?: Partial<CoreCompactionConfig>;
 }
 /**
  * The share of the *content* a compaction aims to leave behind.
@@ -86,6 +107,33 @@ export interface ContextCompactionPrepareTurnOptions {
  * has an answer for any window.
  */
 export declare const COMPACTION_TARGET_CONTENT_SHARE = 0.25;
+/**
+ * The most of the free content a recovery compaction may leave in place.
+ *
+ * A recovery runs because a reply did not fit, so what it leaves has to have
+ * room for one. Its target used to be capped only by the trigger, which is
+ * nine tenths of the window: measured (harness run 0428, 2026-10-11, window
+ * 85,106), each recovery left 53,345 tokens in the request, the retried turn
+ * wrote 22,361 and read a 6,000-token result, and the turn after that was cut
+ * off again -- three times running. Half the content leaves that turn its
+ * room; an ordinary compaction aims at a quarter.
+ */
+export declare const OVERFLOW_RECOVERY_CONTENT_SHARE = 0.5;
+/**
+ * A summarised recovery transcript, cut down to the recovery target.
+ *
+ * The summarising attempt keeps a tail of recent turns after its summary, and
+ * with a tail of large turns it comes back over the target. It used to be
+ * thrown away for that and basic compaction used in its place -- five model
+ * calls and about 200 seconds, three times in one run, for a transcript that
+ * had the work in it and none of the reasons. The summary is the part worth
+ * having, so the tail gives way instead: the leading compaction messages
+ * stay, and the tail keeps its newest turns for as long as they fit.
+ *
+ * `undefined` when there is no summary at the head or it does not fit by
+ * itself: then basic compaction is no worse and needs nothing checked.
+ */
+export declare function trimSummarisedTailToTarget(messages: readonly MessageWithMetadata[] | undefined, targetTokens: number, estimate: (message: MessageWithMetadata) => number): MessageWithMetadata[] | undefined;
 /**
  * How many tokens of transcript a compaction should leave.
  *
@@ -152,7 +200,27 @@ export declare function resolveMessageTargetOnTriggerScale(input: {
 export declare function scaleEstimateToObserved(estimate: number, estimateOfObserved: number, observed: number | undefined): number;
 /** Test seam: the latch is process-wide, so a suite has to be able to clear it. */
 export declare function resetStarvedOutputCapLatch(): void;
-export declare function createContextCompactionPrepareTurn(config: Pick<CoreSessionConfig, "providerConfig" | "providerId" | "modelId" | "compaction" | "logger" | "telemetry" | "sessionId"> & Partial<Pick<CoreSessionConfig, "thinking" | "reasoningEffort" | "thinkingBudgetTokens" | "temperature">>, options?: ContextCompactionPrepareTurnOptions): ((context: ContextPipelinePrepareTurnInput) => Promise<ContextPipelinePrepareTurnResult | undefined>) | undefined;
+export declare function createContextCompactionPrepareTurn(config: Pick<CoreSessionConfig, "providerConfig" | "providerId" | "modelId" | "apiKey" | "baseUrl" | "headers" | "compaction" | "logger" | "telemetry" | "sessionId"> & Partial<Pick<CoreSessionConfig, "thinking" | "reasoningEffort" | "thinkingBudgetTokens" | "temperature">>, options?: ContextCompactionPrepareTurnOptions): ((context: ContextPipelinePrepareTurnInput) => Promise<ContextPipelinePrepareTurnResult | undefined>) | undefined;
+/**
+ * Compaction policy for resuming a session imported from another coding agent.
+ * The imported transcript keeps that agent's tool names and input schemas
+ * verbatim, which a model continuing it may try to call, so the first turn
+ * folds the whole foreign history into a summary before the model request
+ * (manual mode, agentic strategy, nothing preserved but the new prompt).
+ * Runs regardless of the session's auto-compaction setting, tags its status
+ * notices with `importedFrom` so clients can label the wait, and on failure
+ * falls back to the raw transcript. It makes one attempt per session start
+ * (an aborted attempt does not count) and stands down once the working
+ * context already opens with a compaction summary, which is how a resumed
+ * sidecar presents; every other turn defers to `next`, the session's normal
+ * compaction (if any).
+ */
+export declare function createImportedHistoryCompactionPrepareTurn(input: {
+    config: Parameters<typeof createContextCompactionPrepareTurn>[0];
+    /** Source tool id from the session's `importedFrom` metadata. */
+    importedFrom: string;
+    next?: ContextPipelinePrepareTurn;
+}): ContextPipelinePrepareTurn;
 export declare function createCompactionStateAwarePrepareTurn(input: {
     compact?: ContextPipelinePrepareTurn;
     getState?: () => SessionCompactionState | undefined;
@@ -164,4 +232,8 @@ export declare function createCompactionStateAwarePrepareTurn(input: {
      * spuriously reject the write.
      */
     saveState?: (state: SessionCompactionState, sourceMessages: CoreCompactionContext["messages"]) => void | Promise<void>;
+    /** Told when a saved compaction no longer matches the transcript. */
+    logger?: {
+        log?: (message: string) => void;
+    };
 }): ContextPipelinePrepareTurn;

package/dist/extensions/mcp/client.d.ts

@@ -1,6 +1,6 @@
 import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { McpServerClientFactory } from "./types";
-export declare const DEFAULT_MCP_CONNECT_TIMEOUT_MS = 3000;
+export declare const DEFAULT_MCP_CONNECT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_HTTP_MCP_CONNECT_TIMEOUT_MS = 10000;
 export interface DefaultMcpServerClientFactoryOptions {
     settingsPath?: string;

package/dist/extensions/tools/definitions.d.ts

@@ -3,7 +3,7 @@
  *
  * Factory functions for creating the default tools.
  */
-import { type AgentTool, type ShellKind } from "@cerebriline/shared";
+import { type AgentTool } from "@cerebriline/shared";
 import { type QaCredential } from "./qa-credentials";
 import { type ApplyPatchInput, type AskQuestionInput, type AwkToolInput, type EditFileInput, type ExtractDocumentInput, type FetchWebContentInput, type GrepToolInput, type ReadFileRequest, type ReadFilesInput, type SearchCodebaseInput, type SedToolInput, type SkillsInput, type SubmitInput } from "./schemas";
 import type { ApplyPatchExecutor, AskQuestionExecutor, AwkExecutor, CreateDefaultToolsOptions, DefaultToolsConfig, EditorExecutor, ExtractDocumentExecutor, FileReadExecutor, GrepExecutor, SearchExecutor, SedExecutor, SemanticSearchExecutor, ShellExecutor, SkillsExecutorWithMetadata, ToolOperationResult, VerifySubmitExecutor, WebFetchExecutor } from "./types";
@@ -44,11 +44,11 @@ export declare function createReadFilesTool(executor: FileReadExecutor, config?:
 export declare function createSearchTool(executor: SearchExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "searchTimeoutMs">, semantic?: SemanticSearchExecutor["search"]): AgentTool<SearchCodebaseInput, ToolOperationResult[]>;
 /**
  * Build the run_commands tool description for the shell that will actually
- * execute the commands. The shell kind decides the syntax guidance (quoting,
- * sequencing, heredocs), and isWindows adds environment context for POSIX
- * shells running on a Windows host (e.g. Git Bash).
+ * execute the commands. Derive the edition and wrapper guidance from the
+ * same executable, without probing a version or adding volatile prompt text.
+ * isWindows describes the host, not the shell's edition.
  */
-export declare function buildRunCommandsDescription(shellKind: ShellKind, isWindows: boolean): string;
+export declare function buildRunCommandsDescription(shell: string, isWindows: boolean): string;
 /**
  * Create the run_commands shell tool for the current platform.
  *

package/dist/extensions/tools/executors/bash.d.ts

@@ -28,6 +28,32 @@ export declare class CommandExitError extends Error {
     readonly output: string;
     constructor(exitCode: number, output: string);
 }
+/** The process terminated without a numeric exit code, usually by signal. */
+export declare class CommandTerminationError extends Error {
+    readonly signal: NodeJS.Signals | null;
+    readonly output: string;
+    constructor(signal: NodeJS.Signals | null, output: string);
+}
+/**
+ * The shell process could not be started, so the command never ran and there
+ * is no exit code. `code` carries the operating system error libuv reported —
+ * `ENOENT`, `EACCES`, `EFTYPE` for a file that is not a valid executable — so
+ * a host can count "the shell is missing" separately from "the command
+ * failed" without parsing the message.
+ *
+ * `ENOENT` alone is ambiguous: spawn reports it both when the executable is
+ * not found and when the working directory no longer exists, with the same
+ * message. `missing` settles it by checking the directory at failure time, so
+ * "shell not on PATH" and "workspace folder gone" stay separately countable.
+ */
+export declare class CommandSpawnError extends Error {
+    readonly code: string | undefined;
+    /** For `ENOENT`, which path was absent. Undefined for every other code. */
+    readonly missing: "executable" | "cwd" | undefined;
+    constructor(cause: Error, options?: {
+        cwd?: string;
+    });
+}
 export interface ShellExecutorOptions {
     /**
      * Shell to use for execution

package/dist/extensions/tools/executors/index.d.ts

@@ -21,7 +21,7 @@ import { type WebFetchExecutorOptions } from "./web-fetch";
 export { type ApplyPatchExecutorOptions, computePatchChanges, createApplyPatchExecutor, type PatchFileChange, } from "./apply-patch";
 export { PATCH_MARKERS, PatchActionType } from "./apply-patch-parser";
 export { type AwkExecutorOptions, createAwkExecutor } from "./awk";
-export { CommandExitError, createShellExecutor, type ShellExecutorOptions, } from "./bash";
+export { CommandExitError, CommandSpawnError, CommandTerminationError, createShellExecutor, type ShellExecutorOptions, } from "./bash";
 export { DOCUMENT_EXTENSIONS } from "./document/formats";
 export { createDocumentExtractExecutor, DEFAULT_EXTRACTION_DIR, type DocumentExtractExecutorOptions, } from "./document-extract";
 export { createEditorExecutor, type EditorExecutorOptions } from "./editor";

package/dist/extensions/tools/index.d.ts

@@ -7,7 +7,7 @@ export { validateWithZod, zodToJsonSchema } from "@cerebriline/shared";
 export { createPlanModeCommandGuardExtension, PLAN_MODE_COMMAND_GUARD_EXTENSION_NAME, type PlanModeCommandGuardOptions, } from "./command-guard-extension";
 export { ALL_DEFAULT_TOOL_NAMES, DefaultToolNames } from "./constants";
 export { createApplyPatchTool, createAskQuestionTool, createAwkTool, createDefaultTools, createEditorTool, createExtractDocumentTool, createGrepTool, createReadFilesTool, createSearchTool, createSedTool, createShellTool, createSkillsTool, createSubmitAndExitTool, createWebFetchTool, } from "./definitions";
-export { type ApplyPatchExecutorOptions, type AwkExecutorOptions, CommandExitError, computePatchChanges, createApplyPatchExecutor, createAwkExecutor, createDefaultExecutors, createDefaultShellExecutor, createDocumentExtractExecutor, createEditorExecutor, createFileReadExecutor, createGrepExecutor, createReadReceipts, createSearchExecutor, createSedExecutor, createShellExecutor, createWebFetchExecutor, DEFAULT_EXTRACTION_DIR, type DefaultExecutorsOptions, DOCUMENT_EXTENSIONS, type DocumentExtractExecutorOptions, type EditorExecutorOptions, type FileReadExecutorOptions, type GrepExecutorOptions, PATCH_MARKERS, PatchActionType, type PatchFileChange, type ReadReceipts, RunCommandExecutionController, type RunningCommandRegistration, type SearchExecutorOptions, type SedExecutorOptions, type ShellExecutorOptions, type WebFetchExecutorOptions, } from "./executors/index";
+export { type ApplyPatchExecutorOptions, type AwkExecutorOptions, CommandExitError, CommandSpawnError, CommandTerminationError, computePatchChanges, createApplyPatchExecutor, createAwkExecutor, createDefaultExecutors, createDefaultShellExecutor, createDocumentExtractExecutor, createEditorExecutor, createFileReadExecutor, createGrepExecutor, createReadReceipts, createSearchExecutor, createSedExecutor, createShellExecutor, createWebFetchExecutor, DEFAULT_EXTRACTION_DIR, type DefaultExecutorsOptions, DOCUMENT_EXTENSIONS, type DocumentExtractExecutorOptions, type EditorExecutorOptions, type FileReadExecutorOptions, type GrepExecutorOptions, PATCH_MARKERS, PatchActionType, type PatchFileChange, type ReadReceipts, RunCommandExecutionController, type RunningCommandRegistration, type SearchExecutorOptions, type SedExecutorOptions, type ShellExecutorOptions, type WebFetchExecutorOptions, } from "./executors/index";
 export { MAX_COMMAND_OUTPUT_CHARS, MAX_READ_REFUSAL_CHARS, truncateCommandOutput, } from "./executors/output-limits";
 export { DEFAULT_MODEL_TOOL_ROUTING_RULES, resolveToolRoutingConfig, type ToolRoutingRule, } from "./model-tool-routing";
 export { createDefaultToolsWithPreset, createToolPoliciesWithPreset, resolveToolPresetName, type ToolPolicyPresetName, type ToolPresetName, ToolPresets, } from "./presets";

package/dist/extensions/tools/task-progress.d.ts

@@ -169,10 +169,28 @@ export interface TaskProgressTrackerOptions {
  * carried a checklist — a model that has stopped updating the list is exactly
  * the one that needs to see it again.
  */
+/**
+ * The nudge for a file changed outside the checklist.
+ *
+ * Two situations, one rule: a call that changes a file is work on a step, so
+ * if no step is open the list is wrong. Either there is no list at all, or the
+ * list says everything is done and the work has carried on. Measured over 22
+ * v9-agentic sessions (pandorum, 2026-10-10): 12 of the 15 that edited never
+ * sent a list; one sent a single item at its 5th call, ticked it at its 6th
+ * and made 7 of its 10 edits afterwards; another re-sent the same finished
+ * one-item list 16 times across five more edits.
+ *
+ * Reads never trigger it. A run that only looks may simply be finished.
+ */
+export declare function buildUntrackedEditNudge(kind: "missing" | "finished", path: string | undefined): string;
 export declare class TaskProgressTracker {
     private state;
     private callsSinceReminder;
     private writesSinceReminder;
+    /** Edits made since a list with an open step was last sent. */
+    private untrackedEdits;
+    /** A reminder waiting for the turn's tool calls to finish. */
+    private pending;
     private readonly reminderInterval;
     private readonly writeInterval;
     private readonly onUpdate;
@@ -202,6 +220,25 @@ export declare class TaskProgressTracker {
      * demonstrated it has the list, and echoing it straight back is pure cost.
      */
     recordToolCall(input: unknown, toolName?: string): string | undefined;
+    private hasItems;
+    private isFinished;
+    /**
+     * Count an edit made with no step open, and queue the nudge when one is due.
+     *
+     * The first such edit, then every `writeInterval` after it: said once it
+     * can be missed, said on every edit it is noise the model learns to skip.
+     */
+    private noteUntrackedEdit;
+    /**
+     * Hold a reminder for delivery after the turn's tool calls.
+     *
+     * For the reminders that could not be appended to a result because the
+     * result is not text. An untracked-edit nudge already waiting is kept: it
+     * is the more specific of the two.
+     */
+    queueReminder(reminder: string): void;
+    /** The reminder waiting to be delivered, cleared by the read. */
+    takePendingReminder(): string | undefined;
 }
 /**
  * Wrap a tool so its calls feed the tracker and its results carry reminders.

package/dist/extensions/tools/team/index.d.ts

@@ -11,6 +11,7 @@ export { type AgentProfileConnection, type AgentProviderConnection, buildConfigu
 export { type ConfiguredAgentDelegationResult, type ConfiguredAgentSummary, type DelegateToConfiguredAgentInput, delegateToConfiguredAgent, findConfiguredAgent, listConfiguredAgentSummaries, renderDelegationForTranscript, UnknownConfiguredAgentError, } from "./delegate-to-agent";
 export { type EngineEviction, engineEvictionCount, engineEvictions, recordEngineEviction, resetEngineEvictions, } from "./engine-evictions";
 export { isNodeUnreachable } from "./node-reachability";
+export { isDurableTeamEvent, shouldFlushTeamEventImmediately, TEAM_RUN_RESULT_TEXT_LIMIT, type TeamRunResultRecord, toPersistableTeamEvent, toTeamRunResultRecord, } from "./persistence-policy";
 export { buildTeamProgressSummary, toTeamProgressLifecycleEvent, } from "./projections";
 export * from "./runtime";
 export { isSessionAllocationFull, retryWhileSessionFull, } from "./session-window-retry";

package/dist/extensions/tools/team/multi-agent.d.ts

@@ -6,6 +6,25 @@
 import { type AgentConfig, type AgentEvent, type AgentResult, type AppendMissionLogInput, type AttachTeamOutcomeFragmentInput, type CreateTeamOutcomeInput, type CreateTeamTaskInput, type MissionLogEntry, type ReviewTeamOutcomeFragmentInput, type RouteToTeammateOptions, type TeamAgentSampling, type TeamMailboxMessage, type TeamMemberSnapshot, TeamMessageType, type TeammateLifecycleSpec, type TeamOutcome, type TeamOutcomeFragment, type TeamRunRecord, type TeamRunStatus, type TeamRuntimeSnapshot, type TeamRuntimeState, type TeamTask, type TeamTaskListItem, type TeamTaskStatus } from "@cerebriline/shared";
 import { SessionRuntime } from "../../../runtime/orchestration/session-runtime-orchestrator";
 import { type HandedRevision } from "./delegated-sandboxes";
+/**
+ * Incremental change set produced by `AgentTeamsRuntime.drainStateDelta()`.
+ * Only entities mutated since the previous drain are included, so the cost of
+ * persisting it is proportional to what changed, not to team history.
+ */
+export interface TeamRuntimeStateDelta {
+    teamId: string;
+    teamName: string;
+    /** When true, the store must drop all persisted entities before applying. */
+    reset: boolean;
+    /** Members are few and cheap; always included in full. */
+    members: TeamMemberSnapshot[];
+    tasks: TeamTask[];
+    mailbox: TeamMailboxMessage[];
+    missionLog: MissionLogEntry[];
+    runs: TeamRunRecord[];
+    outcomes: TeamOutcome[];
+    outcomeFragments: TeamOutcomeFragment[];
+}
 export { type AppendMissionLogInput, type AttachTeamOutcomeFragmentInput, type CreateTeamOutcomeInput, type CreateTeamTaskInput, type MissionLogEntry, type MissionLogKind, type ReviewTeamOutcomeFragmentInput, type RouteToTeammateOptions, type TeamMailboxMessage, type TeamMemberSnapshot, TeamMessageType, type TeammateLifecycleSpec, type TeamOutcome, type TeamOutcomeFragment, type TeamOutcomeFragmentStatus, type TeamOutcomeStatus, type TeamRunRecord, type TeamRunStatus, type TeamRuntimeSnapshot, type TeamRuntimeState, type TeamTask, type TeamTaskListItem, type TeamTaskStatus, } from "@cerebriline/shared";
 export interface TeamMemberConfig extends AgentConfig {
     role?: string;
@@ -123,6 +142,11 @@ export interface AgentTeamsRuntimeOptions {
     missionLogIntervalMs?: number;
     maxConcurrentRuns?: number;
     onTeamEvent?: (event: TeamEvent) => void;
+    /**
+     * Called when persisted state changes without a team event (mailbox read
+     * receipts, cleanup), so a persistence writer can schedule a flush.
+     */
+    onStateDirty?: () => void;
     /**
      * The teammates' private workspaces, when the host sandboxes them. A
      * teammate's toolset opens its workspace when it is spawned; the runtime
@@ -199,6 +223,7 @@ export declare class AgentTeamsRuntime {
     private readonly teamName;
     private readonly sessionId?;
     private readonly onTeamEvent?;
+    private readonly onStateDirty?;
     private readonly members;
     private readonly tasks;
     private readonly missionLog;
@@ -211,6 +236,7 @@ export declare class AgentTeamsRuntime {
     private outcomeCounter;
     private outcomeFragmentCounter;
     private readonly runs;
+    private dirty;
     private readonly runQueue;
     private queuedRunDispatchTimer;
     private readonly outcomes;
@@ -360,5 +386,27 @@ export declare class AgentTeamsRuntime {
     private formatProgressErrorActivity;
     private recordProgressStep;
     private buildMailboxNotification;
+    /**
+     * Record which persisted entity an event mutated. Every durable state
+     * change flows through `emitEvent`, so this is the single point that keeps
+     * the dirty set in sync with the in-memory maps.
+     */
+    private markDirtyFromEvent;
+    /** True when there are unpersisted changes. */
+    hasPendingStateDelta(): boolean;
+    /**
+     * Return entities mutated since the last drain and clear the dirty set.
+     * Ids whose entity no longer exists are skipped (a `reset` covers removal).
+     */
+    drainStateDelta(): TeamRuntimeStateDelta;
+    /**
+     * Put a drained delta back so a failed write is retried by the next flush.
+     * Entities are re-read at drain time, so only ids and the reset flag matter.
+     */
+    requeueStateDelta(delta: TeamRuntimeStateDelta): void;
+    private notifyStateDirty;
+    /** Mark the whole state dirty (used after hydrate/cleanup or a migration). */
+    markAllStateDirty(reset?: boolean): void;
+    private exportMembers;
     private emitEvent;
 }

package/dist/extensions/tools/team/persistence-policy.d.ts

@@ -0,0 +1,56 @@
+import { type AgentResult, type LegacyAgentUsage } from "@cerebriline/shared";
+import type { TeamEvent } from "./multi-agent";
+/**
+ * Persistence policy for team events.
+ *
+ * Team events fall into two classes:
+ * - **durable**: they mutate team state that must survive a restart
+ *   (tasks, mailbox, mission log, run lifecycle, outcomes, membership).
+ * - **telemetry**: high-frequency liveness signals (streamed agent chunks,
+ *   run heartbeats/activity). These are forwarded to live UIs only and are
+ *   never written to disk.
+ *
+ * The switch is exhaustive so adding a new `TeamMessageType` fails to compile
+ * until it is classified here.
+ */
+export declare function isDurableTeamEvent(event: TeamEvent): boolean;
+/**
+ * Durable events that should be flushed to storage immediately instead of
+ * waiting for the batch window: terminal run states and membership changes,
+ * where losing the write on a crash would leave recovery in a wrong state.
+ */
+export declare function shouldFlushTeamEventImmediately(event: TeamEvent): boolean;
+/**
+ * Compact form of an `AgentResult` kept on team run records. Contains exactly
+ * the fields consumed by run summaries; the full transcript (messages, tool
+ * calls) already lives in the teammate's session storage.
+ */
+export interface TeamRunResultRecord {
+    text: string;
+    iterations: number;
+    finishReason: AgentResult["finishReason"];
+    durationMs: number;
+    usage: LegacyAgentUsage;
+}
+/**
+ * Upstream's upper bound for final text kept on a run record (4,000 there).
+ *
+ * Not applied on this fork: the run record is where a teammate's answer comes
+ * from when the lead awaits it, and a long one is filed whole as a report the
+ * lead reads with `read_agent_report`. Cut here, the report ended at
+ * character 4,000 with "..." and said it was "the end of the report". The
+ * record still drops the transcript and the tool calls, which is where the
+ * size was.
+ */
+export declare const TEAM_RUN_RESULT_TEXT_LIMIT: number;
+/**
+ * Reduce a full (or legacy persisted) agent result to a `TeamRunResultRecord`.
+ * Accepts `unknown` because persisted rows written by older versions may hold
+ * a full `AgentResult` with dates serialized as strings.
+ */
+export declare function toTeamRunResultRecord(result: unknown): TeamRunResultRecord | undefined;
+/**
+ * Strip heavy payloads (full transcripts, tool calls) from an event before it
+ * is appended to the durable event log.
+ */
+export declare function toPersistableTeamEvent(event: TeamEvent): unknown;