@cerebriline/core 4.100.246 → 4.100.248

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;

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

@@ -2,5 +2,5 @@ export { type AgentSlotGate, type AgentSlotGateRegistry, agentEndpointKey, agent
 export { buildDelegatedAgentConfig, createDelegatedAgent, createDelegatedAgentConfigProvider, type DelegatedAgentConfigProvider, type DelegatedAgentConnectionConfig, type DelegatedAgentKind, type DelegatedAgentRuntimeConfig, type DelegatedPrepareTurnTarget, } from "./delegated-agent";
 export { buildSubagentLayout, pinConversationHead, SUBAGENT_BASE_PROMPT, type SubagentKnowledge, type SubagentLayout, } from "./subagent-layout";
 export { createSpawnAgentTool, type SpawnAgentInput, type SpawnAgentOutput, type SpawnAgentToolConfig, type SubAgentEndContext, type SubAgentStartContext, } from "./spawn-agent-tool";
-export { type AgentTask, AgentTeam, AgentTeamsRuntime, type AgentTeamsRuntimeOptions, createAgentTeam, createWorkerReviewerTeam, type SpawnTeammateOptions, type TaskResult, type TeamEvent, type TeamMemberConfig, } from "./multi-agent";
+export { type AgentTask, AgentTeam, AgentTeamsRuntime, type AgentTeamsRuntimeOptions, createAgentTeam, createWorkerReviewerTeam, type SpawnTeammateOptions, type TaskResult, type TeamEvent, type TeamMemberConfig, type TeamRuntimeStateDelta, } from "./multi-agent";
 export { type BootstrapAgentTeamsOptions, type BootstrapAgentTeamsResult, bootstrapAgentTeams, type CreateAgentTeamsToolsOptions, createAgentTeamsTools, reviveTeamStateDates, sanitizeTeamName, type TeamTeammateRuntimeConfig, } from "./team-tools";

package/dist/extensions/tools/team/sanitize-team-name.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Normalizes a team name into a safe storage key: lowercase, runs of
+ * disallowed characters collapsed to `-`, leading/trailing `-` trimmed.
+ */
+export declare function sanitizeTeamName(name: string): string;

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

@@ -1,3 +1,4 @@
+export { sanitizeTeamName } from "./sanitize-team-name";
 import { type AgentTool, type TeamTeammateSpec } from "@cerebriline/shared";
 import { type DelegatedAgentConfigProvider, type DelegatedAgentRuntimeConfig } from "./delegated-agent";
 import type { AgentTeamsRuntime } from "./multi-agent";
@@ -53,4 +54,3 @@ export declare const TEAMMATE_TEAM_TOOL_NAMES: ReadonlySet<string>;
 export declare function bootstrapAgentTeams(options: BootstrapAgentTeamsOptions): BootstrapAgentTeamsResult;
 export declare function createAgentTeamsTools(options: CreateAgentTeamsToolsOptions): AgentTool[];
 export { reviveTeamStateDates } from "./team-state-dates";
-export declare function sanitizeTeamName(name: string): string;

package/dist/hooks/checkpoint-hooks.d.ts

@@ -1,5 +1,20 @@
-import type { AgentHooks, BasicLogger } from "@cerebriline/shared";
+import type { AgentHooks, BasicLogger, ITelemetryService } from "@cerebriline/shared";
 export declare function isCheckpointStashMessage(message: string): boolean;
+/**
+ * Per-session scratch directory holding the persistent `GIT_INDEX_FILE` used
+ * to snapshot untracked files. Persisting the index across turns lets git's
+ * stat cache skip re-reading (and re-hashing) untracked files that have not
+ * changed since the previous checkpoint — without it, every turn re-hashes
+ * every untracked byte in the workspace.
+ *
+ * Lives under the user's Cline data dir (never the world-shared OS tmpdir:
+ * the index and pathspec files enumerate workspace paths) and is keyed by a
+ * hash of cwd + session id: hashing avoids sanitization collisions between
+ * distinct ids, and folding in cwd keeps a session restored against a
+ * different workspace from inheriting a foreign index. Removed by
+ * `deleteCheckpointRefs` and by the age-based reaper.
+ */
+export declare function checkpointScratchDir(cwd: string, sessionId: string): string;
 export interface CheckpointEntry {
     ref: string;
     createdAt: number;
@@ -26,6 +41,13 @@ type CreateCheckpointHooksOptions = {
         sessionId: string;
         runCount: number;
     }) => Promise<CheckpointEntry | undefined> | CheckpointEntry | undefined;
+    /**
+     * Emits one `checkpoint.snapshot` event per built-in snapshot attempt so
+     * snapshot cost and degradations (HEAD fallbacks, skipped turns) are
+     * observable in the field, not only in local logs. Properties carry
+     * outcome and duration — never file paths or contents.
+     */
+    telemetry?: Pick<ITelemetryService, "capture">;
 };
 /**
  * Deletes all private git refs under refs/cline/checkpoints/{sessionId}/ that

package/dist/hooks/hook-file-hooks.d.ts

@@ -1,4 +1,19 @@
 import type { AgentExtension, AgentHooks, BasicLogger, WorkspaceInfo } from "@cerebriline/shared";
+import { type HookEventName } from "./subprocess";
+/**
+ * Reports how long a fire-and-forget hook actually ran, once per hook. Hosts
+ * use it to learn the real runtime distribution of detached hooks —
+ * unmeasurable while nothing awaits them — before deciding to run any of them
+ * blocking. `exited: false` is a censored observation (the hook was still
+ * running after the observation window, so it ran at least `durationMs`),
+ * which is what keeps the sample from covering only hooks that finish.
+ */
+export type HookRuntimeObserver = (event: {
+    hookName: HookEventName;
+    durationMs: number;
+    exitCode: number | null;
+    exited: boolean;
+}) => void;
 type HookRuntimeOptions = {
     cwd: string;
     workspacePath: string;
@@ -7,6 +22,18 @@ type HookRuntimeOptions = {
     toolCallTimeoutMs?: number;
     /** Keep asynchronous hooks attached until exit. Intended for deterministic tests. */
     detachAsyncHooks?: boolean;
+    /**
+     * Run agent_start/agent_resume hooks blocking, honoring their control
+     * output (cancel, contextModification). Off by default: these hooks have
+     * always been fire-and-forget with stdio ignored, so an existing
+     * long-running script would otherwise stall every run start until the
+     * timeout. A host that flips this on must tell hook authors that
+     * long-running run-start hooks need to background themselves (spawn a
+     * detached child and exit).
+     */
+    blockingRunStartHooks?: boolean;
+    /** Observes how long detached hooks run. See {@link HookRuntimeObserver}. */
+    onHookRuntime?: HookRuntimeObserver;
     /** Structured git + path metadata forwarded into every hook payload. */
     workspaceInfo?: WorkspaceInfo;
 };

package/dist/hooks/subprocess-runner.d.ts

@@ -9,6 +9,29 @@ export interface RunSubprocessEventOptions {
         pid?: number;
         detached: boolean;
     }) => void;
+    /**
+     * Reports a detached hook's runtime exactly once. The run never waits on
+     * this: detached hooks are fire-and-forget by contract, and this only
+     * observes them so hosts can measure how long they actually take.
+     *
+     * `exited: true` means the hook finished and `durationMs` is its runtime.
+     * `exited: false` is a censored observation: the hook was still running
+     * after the observation window, and `durationMs` is that window, so read
+     * it as "ran at least this long" and count these separately — the
+     * case that matters most, since those are the hooks that would stall a
+     * blocking run. Without it the sample would only contain hooks that
+     * finished.
+     *
+     * Nothing is reported if the parent exits before either happens.
+     */
+    onDetachedSettled?: (event: {
+        command: string[];
+        durationMs: number;
+        exitCode: number | null;
+        exited: boolean;
+    }) => void;
+    /** Overrides the censoring window for `onDetachedSettled`. */
+    detachedObservationMs?: number;
 }
 export interface RunSubprocessEventResult {
     exitCode: number | null;

package/dist/hooks/subprocess.d.ts

@@ -49,6 +49,16 @@ export interface SubprocessHooksOptions {
     workspaceInfo?: WorkspaceInfo;
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
+    /**
+     * Run agent_start/agent_resume hooks blocking, honoring their control
+     * output (cancel, contextModification). Off by default: these hooks have
+     * always been fire-and-forget with stdio ignored, so an existing
+     * long-running script would otherwise stall every run start until the
+     * timeout. A host that flips this on must tell hook authors that
+     * long-running run-start hooks need to background themselves (spawn a
+     * detached child and exit).
+     */
+    blockingRunStartHooks?: boolean;
     onDispatchError?: (error: Error, payload: HookEventPayload) => void;
     onDispatch?: (event: {
         payload: HookEventPayload;

package/dist/hub/client/index.d.ts

@@ -1,13 +1,33 @@
 import { type HubClientRegistration, type HubCommandEnvelope, type HubEventEnvelope, type HubReplyEnvelope } from "@cerebriline/shared";
 import { type HubOwnerContext } from "../discovery";
+type HubCommandOptions = {
+    timeoutMs?: number | null;
+    /** Synchronous local guard, checked after connection before each dispatch. */
+    beforeDispatch?: () => void;
+    /** Observes this attempt's correlation id after the local guard, before sending.
+     * Dispatch alone does not confirm that the server accepted the command. */
+    onDispatch?: (requestId: string) => void;
+};
 export interface HubClientOptions {
     url: string;
     clientId?: string;
     clientType?: string;
     displayName?: string;
+    /** Version reported to the hub; defaults to the @cline/core version. */
+    clientVersion?: string;
+    /** Additional registration metadata; version and pid are owned by the client. */
+    metadata?: Record<string, unknown>;
     workspaceRoot?: string;
     cwd?: string;
+    /** Hub token sent with the `cline-hub-auth.*` WebSocket subprotocol. */
     authToken?: string;
+    /**
+     * Resolves HTTP headers for each new WebSocket, including reconnects.
+     * This Node-only transport option is mutually exclusive with `authToken`.
+     * Resolver failures are surfaced by `connect()` and `getConnectionError()`;
+     * `Sec-WebSocket-Protocol` must be configured through `authToken` instead.
+     */
+    resolveConnectionHeaders?: () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
     capabilities?: HubClientRegistration["capabilities"];
 }
 export interface LocalHubResolutionOptions {
@@ -15,6 +35,11 @@ export interface LocalHubResolutionOptions {
     strategy?: "prefer-hub" | "require-hub";
     workspaceRoot?: string;
     cwd?: string;
+    /**
+     * Called with the error when starting a detached Hub fails. The function
+     * still resolves `undefined` in that case; this lets a caller report why.
+     */
+    onStartupError?: (error: unknown) => void;
 }
 export type HubTransportErrorCode = "hub_connect_timeout" | "hub_connect_failed" | "hub_connection_closed" | "hub_connection_not_open";
 export declare class HubTransportError extends Error {
@@ -36,6 +61,19 @@ export declare class HubCommandError extends Error {
 }
 export declare function isHubCommandTimeoutError(error: unknown, command?: HubCommandEnvelope["command"]): boolean;
 export declare function rememberRecoverableLocalHubUrl(url: string, authToken?: string): string;
+/**
+ * Keep a local hub's token for the connections this process makes to it,
+ * without marking the hub as one this process may restart.
+ *
+ * A hub on an explicit endpoint (`CLINE_HUB_PORT`, or a host/port the caller
+ * passed) is not "recoverable", and that used to mean its token was not kept
+ * either. The caller that had just started it got back a URL, connected with
+ * no token and was refused: "WebSocket connection to
+ * 'ws://127.0.0.1:25499/hub' failed: Connection ended", on every first start
+ * (solidPC and eleven2go, 2026-10-11, three of three). The second start
+ * worked because it found the discovery record, which carries the token.
+ */
+export declare function rememberLocalHubAuthToken(url: string, authToken?: string): void;
 export declare class NodeHubClient {
     private readonly options;
     private socket;
@@ -57,6 +95,7 @@ export declare class NodeHubClient {
     private reconnectTimer;
     private reconnectAttempt;
     private closedByClient;
+    private connectGeneration;
     private lastCloseError;
     private sawSocketClose;
     private registered;
@@ -68,12 +107,11 @@ export declare class NodeHubClient {
     getConnectionError(): HubTransportError | null;
     updateCapabilities(capabilities: NonNullable<HubClientRegistration["capabilities"]>): Promise<void>;
     connect(): Promise<void>;
+    private openSocket;
     subscribe(listener: (event: HubEventEnvelope) => void, options?: {
         sessionId?: string;
     }): () => void;
-    command(command: HubCommandEnvelope["command"], payload?: Record<string, unknown>, sessionId?: string, options?: {
-        timeoutMs?: number | null;
-    }): Promise<HubReplyEnvelope>;
+    command(command: HubCommandEnvelope["command"], payload?: Record<string, unknown>, sessionId?: string, options?: HubCommandOptions): Promise<HubReplyEnvelope>;
     private commandOnce;
     private recoverLocalHubTransport;
     private hasActiveSubscriptions;
@@ -144,3 +182,4 @@ export declare function restartLocalHubIfIdleAfterStartupTimeout(options: {
     workspaceRoot?: string;
     cwd?: string;
 }): Promise<string | undefined>;
+export {};

package/dist/hub/client/session-client.d.ts

@@ -56,11 +56,8 @@ export interface HubTeamProgressHandlers {
     onError?: (error: Error) => void;
 }
 export declare class HubSessionClient {
-    private readonly options;
     private readonly client;
-    private metadataApplied;
     constructor(options: HubSessionClientOptions);
-    private ensureMetadataApplied;
     connect(): Promise<void>;
     private taskCommand;
     close(): void;

package/dist/hub/daemon/bind-diagnostics.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Best-effort description of who holds the Hub port when the daemon dies with
+ * `EADDRINUSE`. The daemon takes the owner instance lock before binding, so an
+ * occupant on the port is never a live Hub for this owner; these details tell
+ * us what it actually is (an older pre-lock Hub, a leaked handle, another
+ * owner context, or an unrelated program) so the fix can target that case.
+ */
+import type { TelemetryProperties } from "@cerebriline/shared";
+/** `lsof -Fpc` emits `p<pid>` then `c<command>` per process. */
+export declare function parseLsofOwners(output: string): string[];
+/** Telemetry context for a `hub.daemon.startup` failure caused by `EADDRINUSE`. */
+export declare function describeAddressInUse(error: unknown, endpoint: {
+    host: string;
+    port: number;
+    pathname: string;
+}): Promise<TelemetryProperties>;