@cerebriline/core 4.100.245 → 4.100.247

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/extensions/tools/types.d.ts

@@ -62,7 +62,15 @@ export interface SemanticSearchExecutor {
      * indexed. One host serves many workspaces, so the answer is per folder.
      */
     available(cwd: string): boolean;
-    search(query: string, cwd: string, context: AgentToolContext): Promise<string>;
+    search(query: string, cwd: string, context: AgentToolContext, options?: SemanticSearchOptions): Promise<string>;
+}
+export interface SemanticSearchOptions {
+    /**
+     * Read a file of the folder as the caller sees it, by absolute path. A
+     * delegated agent works on its own copy: the lines a passage is on are the
+     * lines of that copy, not of the lead's file.
+     */
+    readFile?: (absolutePath: string) => Promise<string | undefined>;
 }
 /**
  * Per-call execution options for a shell executor.

package/dist/extensions/tools/web-scrape-tool.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `web_scrape`: the web through a Firecrawl endpoint.
+ *
+ * Two shapes of one tool. The librarian's looks at the web to choose what a
+ * book is made from: search, map, read. The general one is offered to any
+ * task when the user turns "Only for the librarian" off, and adds what a task
+ * outside the Library needs: a crawl that saves a site into the workspace.
+ * By default that is the site itself -- every page as it was served and as
+ * the browser rendered it, with the stylesheets, scripts, pictures and fonts
+ * it uses -- beside a markdown reading of each page; `content: "text"` keeps
+ * the markdown alone, for notes.
+ *
+ * The lead's only: it is not in `DELEGATED_HOST_TOOLS`, so a delegated agent,
+ * whose writes go through its overlay, is never handed a tool that writes to
+ * the workspace directly.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import type { LibraryScrapeConfig } from "./library-tools";
+export { cleanLink, linkCensus, pageFileName } from "./web-site-crawl";
+export declare const WEB_SCRAPE_TOOL_NAME = "web_scrape";
+export declare const NO_SCRAPER = "Web scraping is not set up for this session. The user sets the endpoint under Settings > Features and allows it in the API configuration; do not call this again in this task.";
+export interface WebScrapeToolOptions {
+    /** The folder saved pages are written under. */
+    cwd: string;
+    /** The endpoint and its limits, read on every call. Undefined: not set up. */
+    getScrape: () => LibraryScrapeConfig | undefined;
+    /** What stops the tool before the endpoint is asked, said to the model. */
+    unavailable?: () => string | undefined;
+    /** The general tool: `crawl`, and `save_to`. @default false, the librarian's */
+    general?: boolean;
+    onError?: (message: string, error: unknown) => void;
+    /**
+     * A text file the tool wrote, by absolute path. The host forgets what it
+     * knew of the file, so a later read is not told that something outside the
+     * session changed it.
+     */
+    onWrote?: (file: string) => void;
+}
+/** `target` under `cwd`, or nothing when it would leave the folder. */
+export declare function workspacePath(cwd: string, target: string): string | undefined;
+export declare function createWebScrapeTool(options: WebScrapeToolOptions): AgentTool;
+/**
+ * The general tool, when scraping is set up, allowed, and not kept for the
+ * librarian. Decided at session start, like every other tool list; the
+ * endpoint itself is read again on every call.
+ */
+export declare function createWebScrapeTools(options: Omit<WebScrapeToolOptions, "general"> & {
+    log?: (message: string) => void;
+}): AgentTool[];

package/dist/extensions/tools/web-site-crawl.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A site crawled into a folder of the workspace, and continued later.
+ *
+ * The folder keeps a record of the crawl (`.scrape.json`): the pages read
+ * and where each was saved, the files fetched, the pages that are linked and
+ * were not read, and the files a limit left out. A later crawl into the same
+ * folder with `resume` reads only what is missing -- the pages from that
+ * list, one by one through the endpoint, and the files not yet on disk --
+ * and nothing that is already there.
+ *
+ * Every limit that stopped something is said at the top of the result, as an
+ * alert the model is told to pass on: the user set those limits, and only
+ * the user can raise them.
+ */
+import { type ScrapedPage } from "../../services/retrieval/firecrawl";
+import type { LibraryScrapeConfig } from "./library-tools";
+export declare function plural(count: number, one: string, many?: string): string;
+/** An http(s) address without its fragment, or nothing. */
+export declare function cleanLink(link: string): string | undefined;
+/**
+ * A page's file under the crawl's folder: its host and path, with what a
+ * file name cannot hold replaced, so two pages of a site never collide and
+ * the folder reads like the site.
+ */
+export declare function pageFileName(url: string, taken: Set<string>): string;
+export declare function pageFile(page: ScrapedPage): string;
+/**
+ * Where the links of the pages read lead: pages of the same site that were
+ * not read, and other sites. It is what tells "the site has no more pages"
+ * from "the crawl stopped short" -- the two read the same from a page count.
+ */
+export declare function linkCensus(pages: readonly ScrapedPage[], start: string): {
+    unread: string[];
+    elsewhere: string[];
+};
+export declare function sitesLine(hosts: readonly string[], most?: number): string;
+/** The record a crawl leaves in its folder. */
+export declare const SITE_RECORD_FILE = ".scrape.json";
+export interface SiteRecord {
+    version: 1;
+    /** The address the crawl started from. */
+    url: string;
+    content: "site" | "text";
+    wholeSite: boolean;
+    include: string[];
+    exclude: string[];
+    /** Pages read, by address. */
+    pages: Record<string, {
+        title?: string;
+        markdown: string;
+        characters: number;
+        served?: string;
+        rendered?: string;
+    }>;
+    /** Files fetched, by address. */
+    assets: Record<string, {
+        file: string;
+        bytes: number;
+    }>;
+    /** Pages of the site that are linked and were not read. */
+    unread: string[];
+    /** Files a limit left out. */
+    assetsLeft: string[];
+    /** Files that could not be fetched, with the reason. */
+    failed: Record<string, string>;
+    /** Pages that could not be read, with the reason. */
+    failedPages: Record<string, string>;
+}
+export interface CrawlToFolderRequest {
+    scrape: LibraryScrapeConfig;
+    url: string;
+    /** The folder, absolute. */
+    target: string;
+    /** The folder as the model named it, for the result. */
+    folder: string;
+    limit?: number;
+    depth?: number;
+    include: string[];
+    exclude: string[];
+    wholeSite?: boolean;
+    content?: "site" | "text";
+    resume: boolean;
+    signal?: AbortSignal;
+    emit?: (status: string) => void;
+    /** A text file the crawl wrote or rewrote, by absolute path. */
+    wrote?: (file: string) => void;
+    /** The crawl stopped at a limit of the user's; see `reportStoppedForUser`. */
+    stopped?: (reason: string) => void;
+}
+/**
+ * Whether a link is one this crawl reads: the same site, below the starting
+ * address unless the whole site was asked for, and through the path filters.
+ */
+export declare function inCrawlScope(link: string, record: Pick<SiteRecord, "url" | "wholeSite" | "include" | "exclude">): boolean;
+/** Crawl a site into a folder, or continue the crawl that is there. */
+export declare function crawlToFolder(request: CrawlToFolderRequest): Promise<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 {
@@ -57,6 +82,7 @@ export declare class NodeHubClient {
     private reconnectTimer;
     private reconnectAttempt;
     private closedByClient;
+    private connectGeneration;
     private lastCloseError;
     private sawSocketClose;
     private registered;
@@ -68,12 +94,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 +169,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>;