@bendyline/gezel-service 1.1.1 → 1.1.2

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as _bendyline_gezel from '@bendyline/gezel';
-import { NativeEngineResolveEvent, NativeEngineName, HistoryEvent, HistoryFilter, HistoryEntry, ProjectFileEntry, GezelConfig, GezelGender, Poppetje, GezelDetail, PendingGezelMessage, GezelSummary, ProviderName, RetrievalPolicy, ChatModelTuning, GezelTrait, ProjectLocalConfig, ImportProvenance, PendingImports, ProjectTypeOverlay, GezelFrontmatter, Project, ProjectIconId, ProjectDetail, FileReviewIssue, BoekwachterIssueStatus, BoekwachterIssueDismissalReason, ProjectManagedWorkspaceWritePolicy, ProjectNudgeConfig, ProjectTabVisibility, ProjectActivity, MeesterStatusReport, MeesterStatusState, ProjectGitHub, ChatSession, ChatSessionSummary, TimelineMessage, TerminalTimelineEntry, TerminalThread, TerminalThreadSummary, TerminalMessage, GezelGrowthState, Task, Question, TaskNote, ToolsetsScope, InstalledToolset, ToolsetConfig, CraftbookSummary, Craftbook, ProjectCraftbookProvenance, HookSpec, HookPhase, HookResult, ModelTier, ModelStyle, BehaviorId, ModelFamily, ChatMessageToolCall, SamplingBlock, CodexPermissionModeCompat, ModelFitnessTrigger, ModelFitnessRecord, ImageRecognition, RecognitionMode, RecognitionHealth, ImageModelPullEvent as ImageModelPullEvent$1, ModelInfo as ModelInfo$1, VideoAccelerator, ServiceRole, ResolvedDistributionPolicy, SessionParent, SessionLink, ChatSessionSource, ChatEvent, ChatEventEnvelope, AmbientDashboardResolution, AmbientDashboardTheme, AmbientDashboardDisplayTarget, AmbientDashboardStyle, AmbientDashboardState, PromptDraftStatus, PromptDraftSummary, PromptDraft, CreatePromptDraftRequest, PatchPromptDraftRequest, DuplicatePromptDraftRequest, OutlineFileResponse, FileContextResponse, FindSymbolResponse, ReadSymbolResponse, MapRepoResponse, SecurityScanResponse, ScanFindingsRequest, ScanFindingsResponse, SecurityFindingWire, MapAttackSurfaceResponse, ListDependenciesResponse, SecurityOverviewResponse, TraceTaintResponse, FileMapRequest, FileMapResponse, SearchCodeResponse, FileReviewResponse, ListFileIssuesRequest, ListFileIssuesResponse, BoekwachterIssue, SearchDocsResponse, SearchDocumentsResponse, ReadDocAsMarkdownResponse, SearchImagesResponse, FindSimilarImagesResponse, DescribeFolderResponse, FindEntityResponse, ListPeopleResponse, ListEntityMentionsResponse, KeurmeesterCaseRecord, TaskStatus, KeurmeesterTriggerKind, KeurmeesterAction, KeurmeesterCaseOutcome, GateCheck, TaskCraftbookStep, TaskCraftbookSource, CraftbookConnectorNeed, CreateTaskRequest, UpdateTaskRequest, TaskAssignee, NewCraftbookStep, StepPosition, UpdateTaskStepRequest, TaskNoteAuthor, TaskVariation, ScriptCapability, WorkspaceIndexStatus, IndexReadinessReport, ScriptScope, ScriptRunTrigger, ScriptRun, PreviewLogEntry, WorkspaceCommandIndex, WorkspaceSkillIndex, WorkspaceInstructionIndex, UnifiedSearchResult, RetrievalSource, SessionTurnPhase, SessionGpuTask, SessionTelemetry, AIEngagementMode, TurnCancelReason, ChatMessage, SessionDebugSnapshot, ExpectedDeliverable, FileTurnIntent, AppServeSiteStatus, AppServeStartRequest, AppServeStartResponse, ChannelStatus, ChannelName, CodexSetupStatusResponse, ConfigureCodexRequest, KeyedLock, ProjectConnectorBinding, DiffpackOrigin, DiffpackRecord, Diffpack, GildeUpdateStatusResponse, GitWorkingChange, GitFileDiffResponse, CodeReviewKind, GitLogEntry, GitCommitDetailResponse, GitSyncResponse, GitConflictFile, GitConflictVersionsResponse, TaskWaitState, CodeReviewRecord, CodeReview, GitHubPullSummary, GitHubPullDetail, GitHubPullFile, GitHubPullComment, KnowledgeUserRegistry, KnowledgeCatalogRef, KnowledgeInstallSourceKind, TrustedKnowledgeCoordinate, KnowledgeInstallEvent, ProjectKnowledgeCatalogs, KnowledgeEmbeddingProfile, KnowledgeInstallRequest, KnowledgeCatalogStatus, KnowledgeUpdateCandidate, KnowledgeAvailableCatalog, KnowledgeSemanticSearchMode, KnowledgeInstallJob, KnowledgeActiveInstall, IncompleteKnowledgeDownload, OpenCodeSetupStatusResponse, ConfigureOpenCodeRequest, InstallOpenCodePluginRequest, PiSetupStatusResponse, ConfigurePiRequest, InstallPiExtensionRequest, RenderImageRequest, ReportActionsResponse, FireReportActionResponse, ReportActionRecord, StorageJobKind, StorageJob, StorageJobPhase, SystemToolsetInstallEvent, SystemToolsetInstallSnapshot, NightShiftWindow, TerminalEventEnvelope, DiscoveredCommand, VSCodeSetupStatusResponse, ConfigureVSCodeRequest, ScriptMeta } from '@bendyline/gezel';
+import { NativeEngineResolveEvent, NativeEngineName, HistoryEvent, HistoryFilter, HistoryEntry, ProjectFileEntry, GezelConfig, GezelGender, Poppetje, GezelDetail, PendingGezelMessage, GezelSummary, ProviderName, RetrievalPolicy, ChatModelTuning, GezelTrait, ProjectLocalConfig, ImportProvenance, PendingImports, ProjectTypeOverlay, GezelFrontmatter, Project, ProjectIconId, ProjectDetail, FileReviewIssue, BoekwachterIssueStatus, BoekwachterIssueDismissalReason, ProjectManagedWorkspaceWritePolicy, ProjectNudgeConfig, ProjectTabVisibility, ProjectActivity, MeesterStatusReport, MeesterStatusState, ProjectGitHub, ChatSession, ChatSessionSummary, TimelineMessage, TerminalTimelineEntry, TerminalThread, TerminalThreadSummary, TerminalMessage, GezelGrowthState, Task, Question, TaskNote, ToolsetsScope, InstalledToolset, ToolsetConfig, CraftbookSummary, Craftbook, ProjectCraftbookProvenance, HookSpec, HookPhase, HookResult, ModelTier, ModelStyle, BehaviorId, ModelFamily, ChatMessageToolCall, SamplingBlock, CodexPermissionModeCompat, ModelFitnessTrigger, ModelFitnessRecord, ImageRecognition, RecognitionMode, RecognitionHealth, ImageModelPullEvent as ImageModelPullEvent$1, ModelInfo as ModelInfo$1, VideoAccelerator, ServiceRole, ResolvedDistributionPolicy, AppToolRelayEvent, RegisterAppToolsRequest, AppToolRelayCloseReason, AppToolDefinition, AppToolRelaySummary, AppToolCallResultRequest, SessionParent, SessionLink, ChatSessionSource, ChatEvent, ChatEventEnvelope, AmbientDashboardResolution, AmbientDashboardTheme, AmbientDashboardDisplayTarget, AmbientDashboardStyle, AmbientDashboardState, PromptDraftStatus, PromptDraftSummary, PromptDraft, CreatePromptDraftRequest, PatchPromptDraftRequest, DuplicatePromptDraftRequest, OutlineFileResponse, FileContextResponse, FindSymbolResponse, ReadSymbolResponse, MapRepoResponse, SecurityScanResponse, ScanFindingsRequest, ScanFindingsResponse, SecurityFindingWire, MapAttackSurfaceResponse, ListDependenciesResponse, SecurityOverviewResponse, TraceTaintResponse, FileMapRequest, FileMapResponse, SearchCodeResponse, FileReviewResponse, ListFileIssuesRequest, ListFileIssuesResponse, BoekwachterIssue, SearchDocsResponse, SearchDocumentsResponse, ReadDocAsMarkdownResponse, SearchImagesResponse, FindSimilarImagesResponse, DescribeFolderResponse, FindEntityResponse, ListPeopleResponse, ListEntityMentionsResponse, KeurmeesterCaseRecord, TaskStatus, KeurmeesterTriggerKind, KeurmeesterAction, KeurmeesterCaseOutcome, GateCheck, TaskCraftbookStep, TaskCraftbookSource, CraftbookConnectorNeed, CreateTaskRequest, UpdateTaskRequest, TaskAssignee, NewCraftbookStep, StepPosition, UpdateTaskStepRequest, TaskNoteAuthor, TaskVariation, ScriptCapability, WorkspaceIndexStatus, IndexReadinessReport, ScriptScope, ScriptRunTrigger, ScriptRun, PreviewLogEntry, WorkspaceCommandIndex, WorkspaceSkillIndex, WorkspaceInstructionIndex, UnifiedSearchResult, RetrievalSource, SessionTurnPhase, SessionGpuTask, SessionTelemetry, AIEngagementMode, TurnCancelReason, ChatMessage, SessionDebugSnapshot, ExpectedDeliverable, FileTurnIntent, TurnIntentPreviewRequest, TurnIntentPlan, AppServeSiteStatus, AppServeStartRequest, AppServeStartResponse, ChannelStatus, ChannelName, CodexSetupStatusResponse, ConfigureCodexRequest, KeyedLock, ProjectConnectorBinding, DiffpackOrigin, DiffpackRecord, Diffpack, GildeUpdateStatusResponse, GitWorkingChange, GitFileDiffResponse, CodeReviewKind, GitLogEntry, GitCommitDetailResponse, GitSyncResponse, GitConflictFile, GitConflictVersionsResponse, TaskWaitState, CodeReviewRecord, CodeReview, GitHubPullSummary, GitHubPullDetail, GitHubPullFile, GitHubPullComment, KnowledgeUserRegistry, KnowledgeCatalogRef, KnowledgeInstallSourceKind, TrustedKnowledgeCoordinate, KnowledgeInstallEvent, ProjectKnowledgeCatalogs, KnowledgeEmbeddingProfile, KnowledgeInstallRequest, KnowledgeCatalogStatus, KnowledgeUpdateCandidate, KnowledgeAvailableCatalog, KnowledgeSemanticSearchMode, KnowledgeInstallJob, KnowledgeActiveInstall, IncompleteKnowledgeDownload, OpenCodeSetupStatusResponse, ConfigureOpenCodeRequest, InstallOpenCodePluginRequest, PiSetupStatusResponse, ConfigurePiRequest, InstallPiExtensionRequest, RenderImageRequest, ReportActionsResponse, FireReportActionResponse, ReportActionRecord, StorageJobKind, StorageJob, StorageJobPhase, SystemToolsetInstallEvent, SystemToolsetInstallSnapshot, NightShiftWindow, TerminalEventEnvelope, DiscoveredCommand, VSCodeSetupStatusResponse, ConfigureVSCodeRequest, ScriptMeta } from '@bendyline/gezel';
 import { CatalogService } from '@bendyline/gezel-catalog';
 import { NativeBinaryName, GpuPanicRecord, DeviceHealthGate, DeviceSafetyPolicyInput, DeviceHealthStatusSnapshot } from '@bendyline/gezel/native';
 import { z } from 'zod';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { spawn, exec } from 'node:child_process';
 import { ServerType } from '@hono/node-server';
 import { ExternalFolders } from '@bendyline/gezel/paths';
@@ -58,7 +59,9 @@ type RunResult = {
     stdout: string;
     stderr: string;
 };
-type Runner = (cmd: string, args: string[]) => Promise<RunResult>;
+type Runner = (cmd: string, args: string[], options?: {
+    env: NodeJS.ProcessEnv;
+}) => Promise<RunResult>;
 interface VerifyOptions {
     policy: SignaturePolicy;
     /** Test seam — defaults to `process.platform`. */
@@ -197,6 +200,91 @@ declare class EngineBinaryRegistry {
     private broadcast;
 }
 
+/**
+ * The MCP server spec: what `McpBridge.start()` needs to bring up a session,
+ * plus the `kind` predicates. A leaf module on purpose — wrappers under
+ * `mcp-wrappers/` select on the spec, and the bridge imports the wrapper
+ * registry, so a wrapper that reached back into `mcp-bridge.ts` for these
+ * helpers formed an import cycle (`playwright-arg-validator` →
+ * `playwright-snapshot` → `mcp-bridge` → `mcp-wrappers/index` → the
+ * validator again, still initializing). Import spec helpers from here;
+ * `mcp-bridge.ts` re-exports them for its existing callers.
+ *
+ * Three flavors:
+ *
+ *   - **stdio** (default when `kind` is omitted) — spawn a local
+ *     subprocess and speak MCP over its pipes. The historical shape
+ *     and what every existing call site uses.
+ *   - **http** — connect to a hosted MCP server over HTTP (Streamable
+ *     HTTP for new servers, SSE for older ones). Headers (auth tokens,
+ *     custom keys) come from resolved toolset config the same way
+ *     subprocess env vars do for stdio.
+ *   - **in-memory** — an MCP server this daemon serves itself, over a
+ *     linked transport pair with no process and no socket. Used for tools a
+ *     connected app registered through the app-tool relay: the server half
+ *     forwards each call up that app's event stream. A bridge is still the
+ *     right shape for these because everything a tool surface needs —
+ *     timeouts, output caps, redaction, argument coercion, the unresolved
+ *     failure ledger, the `tool` chat event — already lives in the bridge
+ *     and pool rather than in any one transport.
+ *
+ * The discriminator is `kind`; a missing `kind` is treated as
+ * `'stdio'` so legacy `{command, args, env}` callers keep working.
+ */
+
+type McpServerSpec = StdioMcpServerSpec | HttpMcpServerSpec | InMemoryMcpServerSpec;
+interface StdioMcpServerSpec {
+    kind?: 'stdio';
+    /**
+     * Catalog toolset id this bridge speaks to, when it was spawned for an
+     * installed toolset. Wrappers select on this rather than sniffing the
+     * command line, because a managed system install spawns
+     * `node <home>/system-toolsets/@playwright__mcp@0.0.78/package/cli.js` —
+     * `installDirName` has slugified the `/` away, so the package name never
+     * appears in `command`/`args`. Sniffing there left every Playwright
+     * wrapper inert against the exact copy Gezel manages: the `file:`-URL
+     * rewrite never fired, and the local-preview posture advertised a browser
+     * surface nothing had pruned.
+     */
+    toolsetId?: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    /** Working directory for project-local/custom MCP servers. */
+    cwd?: string;
+}
+interface HttpMcpServerSpec {
+    kind: 'http';
+    /** Catalog toolset id — see {@link StdioMcpServerSpec.toolsetId}. */
+    toolsetId?: string;
+    /**
+     * `streamable-http` is the current MCP HTTP transport (one URL,
+     * POST for messages, optional GET for SSE stream + auto-reconnect).
+     * `sse` is the older two-endpoint variant — kept for back-compat
+     * with registry entries that still declare it.
+     */
+    transport: 'streamable-http' | 'sse';
+    url: string;
+    /**
+     * Headers attached to every request. Bearer tokens, API keys, etc.
+     * Resolved from toolset config + secrets at session-build time.
+     */
+    headers: Record<string, string>;
+}
+interface InMemoryMcpServerSpec {
+    kind: 'in-memory';
+    /** Catalog toolset id — see {@link StdioMcpServerSpec.toolsetId}. */
+    toolsetId?: string;
+    /** Short label for logs; never a secret. */
+    label: string;
+    /**
+     * Build the client half of a linked transport pair, with the server half
+     * already connected. Called once per bridge start, so a retry gets a fresh
+     * pair rather than a closed one.
+     */
+    connect: () => Transport;
+}
+
 /**
  * Append-only audit log. Explicit events live in per-scope JSONL files;
  * chat session entries are derived at query time from the existing
@@ -1134,8 +1222,14 @@ declare class Store {
      * deprecated field spread through newly written project files.
      */
     private writeProjectMeta;
-    /** Per-project lock serializing {@link touchProject}'s metadata bumps. */
-    private readonly touchChains;
+    /**
+     * Per-project lock shared by every project.json read-modify-write path.
+     * Settings, classification, roster bookkeeping, scheduler nudge state, and
+     * Git sync metadata can all land concurrently. Atomic file replacement
+     * prevents torn JSON, but only this full-cycle lock prevents a later writer
+     * from silently restoring the stale fields it read before another write.
+     */
+    private readonly projectUpdateLocks;
     touchProject(id: string): Promise<void>;
     /**
      * A project `workingDir` is settable by the model (via `update_project`)
@@ -1223,6 +1317,7 @@ declare class Store {
          */
         properties?: Record<string, string>;
     }): Promise<ProjectDetail>;
+    private updateProjectUnlocked;
     /**
      * Delete a project. Two tiers, because the user's own files must never be
      * destroyed silently:
@@ -1250,6 +1345,7 @@ declare class Store {
         removedWorkspace: boolean;
         workspaceSource: 'workingDir' | 'githubCheckout' | 'internal';
     }>;
+    private deleteProjectUnlocked;
     /**
      * Update the service-managed fields of `project.github`. When `patch.url`
      * is supplied, this may also create the link after an explicit clone path
@@ -1278,6 +1374,7 @@ declare class Store {
     }): Promise<{
         added: boolean;
     }>;
+    private addGezelToProjectUnlocked;
     /**
      * Remove a gezel from a project's `gezelIds` roster. Idempotent —
      * returns `{ removed: false }` when the gezel wasn't a member. Does
@@ -2023,7 +2120,9 @@ declare class Store {
      */
     listProjectCraftbooks(projectId: string): Promise<CraftbookSummary[]>;
     /** Resolve a project-local craftbook into the runtime `Craftbook` shape. */
-    getProjectCraftbook(projectId: string, id: string, version?: string): Promise<Craftbook | null>;
+    getProjectCraftbook(projectId: string, id: string, version?: string, options?: {
+        throwOnInvalid?: boolean;
+    }): Promise<Craftbook | null>;
     /** Persist a project-local craftbook (flat `.gezel/craftbooks/<id>/` layout). */
     writeProjectCraftbook(projectId: string, book: Craftbook): Promise<void>;
     /** Remove a project-local craftbook from the workspace. */
@@ -2131,59 +2230,7 @@ type HookRunner = (hook: ActiveHook, ctx: {
         isError: boolean;
     };
 }) => Promise<HookResult>;
-/**
- * What `McpBridge.start()` needs to bring up a session. Two flavors:
- *
- *   - **stdio** (default when `kind` is omitted) — spawn a local
- *     subprocess and speak MCP over its pipes. The historical shape
- *     and what every existing call site uses.
- *   - **http** — connect to a hosted MCP server over HTTP (Streamable
- *     HTTP for new servers, SSE for older ones). Headers (auth tokens,
- *     custom keys) come from resolved toolset config the same way
- *     subprocess env vars do for stdio.
- *
- * The discriminator is `kind`; a missing `kind` is treated as
- * `'stdio'` so legacy `{command, args, env}` callers keep working.
- */
-type McpServerSpec = StdioMcpServerSpec | HttpMcpServerSpec;
-interface StdioMcpServerSpec {
-    kind?: 'stdio';
-    /**
-     * Catalog toolset id this bridge speaks to, when it was spawned for an
-     * installed toolset. Wrappers select on this rather than sniffing the
-     * command line, because a managed system install spawns
-     * `node <home>/system-toolsets/@playwright__mcp@0.0.78/package/cli.js` —
-     * `installDirName` has slugified the `/` away, so the package name never
-     * appears in `command`/`args`. Sniffing there left every Playwright
-     * wrapper inert against the exact copy Gezel manages: the `file:`-URL
-     * rewrite never fired, and the local-preview posture advertised a browser
-     * surface nothing had pruned.
-     */
-    toolsetId?: string;
-    command: string;
-    args: string[];
-    env: Record<string, string>;
-    /** Working directory for project-local/custom MCP servers. */
-    cwd?: string;
-}
-interface HttpMcpServerSpec {
-    kind: 'http';
-    /** Catalog toolset id — see {@link StdioMcpServerSpec.toolsetId}. */
-    toolsetId?: string;
-    /**
-     * `streamable-http` is the current MCP HTTP transport (one URL,
-     * POST for messages, optional GET for SSE stream + auto-reconnect).
-     * `sse` is the older two-endpoint variant — kept for back-compat
-     * with registry entries that still declare it.
-     */
-    transport: 'streamable-http' | 'sse';
-    url: string;
-    /**
-     * Headers attached to every request. Bearer tokens, API keys, etc.
-     * Resolved from toolset config + secrets at session-build time.
-     */
-    headers: Record<string, string>;
-}
+
 /** Shape of an OpenAI function tool (Responses API format). */
 interface OpenAIFunctionTool {
     type: 'function';
@@ -2503,6 +2550,12 @@ interface TurnCtx extends ModelCtx {
     userText: string;
     /** Tool calls that drained from the per-turn accumulator. */
     drained: ChatMessageToolCall[];
+    /**
+     * A preceding turn in this task-scoped session successfully read artifact
+     * evidence and persisted its complete result. Adjacent craftbook steps can
+     * deliberately review that replayed evidence without issuing the read again.
+     */
+    verifiedPriorArtifactRead?: boolean;
     /** Final assistant content for the just-completed turn. */
     assistantContent: string;
     /** How many continuation nudges have already fired in this user-initiated send. */
@@ -3588,15 +3641,18 @@ interface SessionOpts {
         error: unknown;
     }) => void;
     /**
-     * When present, the bridge pool filters its advertised tools to
-     * names in this set. Tools not in the set are hidden from the model
-     * (their JSON schemas are never serialized into requests) but the
-     * bridge can still call them if invoked by id. Driven by the
-     * `toolFilterMode` config + gezel role — see
-     * `chat/role-tool-filter.ts`. Unset means "advertise every tool"
-     * (pre-filter behavior).
+     * Role-derived ceiling on advertised and callable built-in tools.
+     * Third-party tools are unaffected by this set; an authored step's
+     * toolNamePolicy can constrain those too. The bridge pool retains a
+     * narrow append recovery exception for truncated write_file calls.
+     * See chat/role-tool-filter.ts. Unset adds no role-based restriction.
      */
     toolAllowlist?: Set<string>;
+    /** Authored step ceiling for all bridge tools, including third-party MCP tools. */
+    toolNamePolicy?: {
+        allow?: ReadonlySet<string>;
+        deny?: ReadonlySet<string>;
+    };
     /**
      * The chat manager classified this session's current turn as direct
      * file work and narrowed its tool surface accordingly. Local providers
@@ -3835,6 +3891,8 @@ interface ToolCallEvent {
      * into a short full response or a deterministic summary before persistence.
      */
     resultText?: string;
+    /** True when the bridge clipped the provider-visible text after the MCP tool returned. */
+    deliveredResultTruncated?: boolean;
     /**
      * Image artifacts the tool returned (Playwright `browser_*` screenshots,
      * etc.) — already written to disk by the bridge's image persister, paths
@@ -4828,6 +4886,15 @@ interface NativeEngineLifecycleSnapshot {
     unloadAt: number | null;
     idleTimeoutMs: number;
     releaseReason: 'idle' | 'memory-pressure' | null;
+    /**
+     * When the last start attempt failed, and why. Cleared by the next start
+     * that reaches ready. An engine that never started still holds its pool
+     * reservation, and no idle timer is armed for it (the timer is only ever
+     * reset by a RUNNING engine), so nothing would ever give that memory back
+     * — see `ProviderPool.sweepFailedStarts`.
+     */
+    startFailedAt?: number;
+    startFailure?: string;
 }
 
 interface ProviderBuilderArgs {
@@ -5023,6 +5090,31 @@ declare class ProviderPool {
     touch(key: string): void;
     /** Returns true if the pool currently holds an entry for `key`. */
     has(key: string): boolean;
+    /**
+     * Drop entries whose engine failed to start, releasing the budget they hold.
+     *
+     * The reservation is taken when the builder returns — before the engine
+     * process exists, because the engine starts lazily on the first turn. A
+     * start that then fails (memory admission refused, spawn error, panic
+     * guard) leaves an entry that owns its whole `residentBytes` while running
+     * nothing, and it is never reclaimed on its own: the idle timer that would
+     * eventually release it is only ever armed by an engine that reached
+     * `running`. Observed as a 9.7 GB reservation on a machine whose engine
+     * process count was zero, against an 11.2 GB budget.
+     *
+     * Eviction is the whole repair. The next `ensure` rebuilds, which re-plans
+     * the context window against memory as it stands then rather than handing
+     * back a provider that will fail the same way.
+     */
+    private sweepFailedStarts;
+    /**
+     * Evict pool entries whose supervised native child has already stopped.
+     * Their bytes are capacity guarantees, not physical residency. Keeping the
+     * wrapper cached is useful until another model actually needs that promise;
+     * a capacity denial is the pressure signal that makes the released entries
+     * expendable.
+     */
+    private reclaimReleasedReservations;
     /**
      * Immediately unload one resident engine, but only while it is idle.
      *
@@ -6184,6 +6276,8 @@ interface InstalledMlxModel {
     id: string;
     name: string;
     approxSizeBytes: number;
+    /** Cataloged fixed working set with KV excluded; measured values beat the fallback formula. */
+    residentBytes?: number;
     installedAt: string;
     /** Absolute path to the model directory the supervisor passes to `mlx_lm.server --model`. */
     modelDir: string;
@@ -6322,6 +6416,7 @@ interface MlxModelManagerOptions {
 }
 declare class MlxModelManager {
     private readonly modelsRoot;
+    private readonly viewsRoot;
     private readonly storageRoots;
     private readonly catalog;
     private readonly fetchImpl;
@@ -6792,6 +6887,13 @@ interface PairedRemote {
     tlsCertPem?: string;
     /** Scopes the server granted (currently `['remote-inference']`). */
     scopes: string[];
+    /**
+     * `gezelVersion` from the peer's `/v1/identity`, when it reported one.
+     * Absent for a peer too old to publish it. Read by the native-capacity
+     * authority check, which must know whether the broker deciding this
+     * machine's memory is the same build as the one asking.
+     */
+    gezelVersion?: string;
     pairedAt: number;
     /** Last time A successfully reached this server (in-memory unless flushed). */
     lastSeenAt?: number;
@@ -8918,6 +9020,144 @@ interface EngineContext {
     childProcessSpawn?: SpawnCapability;
 }
 
+/**
+ * One app's tools for one project, as a chat session sees them.
+ *
+ * Captured when a session builds its bridges, so a turn already in flight
+ * keeps the surface it was told about. `invoke` re-checks liveness against the
+ * registry, which is what keeps a captured binding from becoming a promise
+ * nobody can keep.
+ */
+interface AppToolBinding {
+    relayId: string;
+    appId: string;
+    appName?: string;
+    projectId: string;
+    gezelIds?: ReadonlySet<string>;
+    tools: readonly AppToolDefinition[];
+}
+/** Where relay events are written — an SSE response in production. */
+interface AppToolRelayStreamSink {
+    write(event: AppToolRelayEvent): void | Promise<void>;
+}
+type AppToolInvokeResult = Extract<AppToolCallResultRequest, {
+    ok: true;
+}> | {
+    ok: false;
+    error: string;
+};
+interface AppToolInvocation {
+    tool: string;
+    args: Record<string, unknown>;
+    sessionId: string;
+    gezelId: string;
+    projectId: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface AppToolRelayRegistryOptions {
+    graceMs?: number;
+    heartbeatMs?: number;
+    maxRelaysPerApp?: number;
+    maxPendingPerRelay?: number;
+    now?: () => number;
+    /** Called whenever a project's tool surface changed. */
+    onChange?: (projectId: string) => void;
+}
+/**
+ * Live registry of app-registered tools.
+ *
+ * Everything here is in-memory on purpose. A registration is a claim that the
+ * app is standing by to answer calls, and that claim cannot survive a restart
+ * of either side — a persisted one would advertise tools whose handler no
+ * longer exists, which the model experiences as a tool that accepts the call
+ * and then never returns.
+ */
+declare class AppToolRelayRegistry {
+    private readonly relays;
+    private readonly graceMs;
+    private readonly heartbeatMs;
+    private readonly maxRelaysPerApp;
+    private readonly maxPendingPerRelay;
+    private readonly now;
+    private readonly onChange?;
+    constructor(opts?: AppToolRelayRegistryOptions);
+    get limits(): {
+        graceMs: number;
+        heartbeatMs: number;
+        maxPendingCalls: number;
+    };
+    open(input: {
+        appId: string;
+        appName?: string;
+        label?: string;
+    }): {
+        relayId: string;
+    };
+    /** The relay's owning app, for route-level ownership checks. */
+    ownerOf(relayId: string): string | undefined;
+    has(relayId: string): boolean;
+    /**
+     * Attach an event stream. A second stream for the same relay supersedes the
+     * first: a half-open socket that the OS has not yet torn down must never be
+     * able to lock an app out of its own relay.
+     */
+    attachStream(relayId: string, sink: AppToolRelayStreamSink): {
+        detach: () => void;
+    };
+    detachStream(relayId: string): void;
+    register(relayId: string, request: RegisterAppToolsRequest): {
+        toolsetId: string;
+        registered: string[];
+    };
+    unregister(relayId: string, projectId?: string): void;
+    close(relayId: string, reason: AppToolRelayCloseReason): void;
+    closeAll(reason?: AppToolRelayCloseReason): void;
+    /**
+     * Bindings that apply to one session. A relay inside its grace window still
+     * counts: the tools are about to come back, and dropping them would rebuild
+     * the session's whole tool surface for a two-second socket blip.
+     */
+    listForSession(query: {
+        projectId: string;
+        gezelId: string;
+    }): AppToolBinding[];
+    /**
+     * Stable identity of a project's app-tool surface. The chat manager stores
+     * it on the live session and rebuilds when it moves, so tools registered
+     * after a session opened appear on the next turn.
+     */
+    fingerprint(projectId: string): string;
+    listRelays(filter?: {
+        appId?: string;
+    }): AppToolRelaySummary[];
+    /**
+     * Run one tool in the app and wait for its answer.
+     *
+     * Never queues against a disconnected app: the model is blocked on this
+     * call, so "the app is not connected" is a far better answer than a wait
+     * that ends in a timeout with the same information.
+     */
+    invoke(binding: AppToolBinding, call: AppToolInvocation): Promise<AppToolInvokeResult>;
+    /**
+     * Deliver an app's answer. A late answer for a call that already timed out
+     * reports `unknown` rather than being applied — the model has moved on, and
+     * silently accepting it would leave the app believing it was used.
+     */
+    resolveCall(relayId: string, callId: string, result: AppToolCallResultRequest): 'resolved' | 'unknown';
+    private require;
+    private findConflict;
+    private failPending;
+    /**
+     * Best-effort notification. A relay inside its grace window has no stream to
+     * write to, and that is not an error: the app is between connections, and
+     * its registration is deliberately still live. Only {@link invoke} needs a
+     * connected app, and it checks for one itself before emitting.
+     */
+    private emit;
+    private emitTo;
+}
+
 type SessionListener = (event: ChatEvent) => void;
 type EnvelopeListener = (envelope: ChatEventEnvelope) => void;
 interface PublishScope {
@@ -10688,6 +10928,16 @@ interface GateEvalDeps {
             at?: string;
         }>;
     }>;
+    /** Service-written successful artifact read ranges for the current task step. */
+    corpusReadEvidence?: () => Promise<{
+        observable: boolean;
+        slices: Array<{
+            path: string;
+            startLine: number;
+            endLine: number;
+            totalLines: number;
+        }>;
+    }>;
     /**
      * Run receipts for `commandEvidence`. The task manager scopes this to
      * the current task, step, and activation timestamp, reading the
@@ -10909,6 +11159,8 @@ type StepActivatedHook = (ctx: {
     newStep: TaskCraftbookStep;
     /** The step that was just completed (may equal newStep on loopback). */
     completedStep: TaskCraftbookStep;
+    /** A spawned task's first step is an entry, not a self-handoff. */
+    kind?: 'entry' | 'transition' | 'redispatch';
 }) => Promise<void> | void;
 /**
  * Fired when a completion gate re-activates a step but the model turn that
@@ -10948,6 +11200,12 @@ type TaskSettledHook = (ctx: {
     task: Task;
     outcome: 'complete' | 'canceled';
 }) => Promise<void> | void;
+/** Fired after the durable status changes, including draft activation. */
+type TaskStatusChangedHook = (ctx: {
+    projectId: string;
+    task: Task;
+    previousStatus: TaskStatus;
+}) => Promise<void> | void;
 type TaskNeedsHelpReason = 'gate_exhausted' | 'gate_plateau' | 'gate_unsatisfiable' | 'gate_infrastructure' | 'step_exit_infrastructure' | 'step_stalled' | 'budget_exhausted';
 /**
  * Fired when a task PAUSES FOR HELP — a gate budget spent, a plateau, an
@@ -11043,6 +11301,7 @@ declare class TaskManager {
     private onCurrentTurnStepReactivated?;
     private onTaskCreated?;
     private onTaskSettled?;
+    private onTaskStatusChanged?;
     private onTaskNeedsHelp?;
     private onConnectorPrep?;
     private readonly autoPreparedConnectorTypes;
@@ -11140,6 +11399,7 @@ declare class TaskManager {
     /** Register the task-created hook (script install lives here). */
     setTaskCreatedHook(fn: TaskCreatedHook): void;
     setTaskSettledHook(fn: TaskSettledHook): void;
+    setTaskStatusChangedHook(fn: TaskStatusChangedHook): void;
     setTaskNeedsHelpHook(fn: TaskNeedsHelpHook): void;
     /**
      * Wire the connector-prep hook — pulls a craftbook's declared connector
@@ -11163,6 +11423,7 @@ declare class TaskManager {
         detail: string;
     }): Promise<void>;
     private notifyTaskSettled;
+    private notifyTaskStatusChanged;
     /**
      * Wire the role resolver — turns a step's `suggestedRole` into a
      * concrete gezel id at step-activation time. When unset, role-based
@@ -11565,6 +11826,8 @@ declare class TaskManager {
     recordNightShiftSpawn(ref: string, dayKey: string): Promise<void>;
     describeAssignee: typeof describeAssignee;
     private requireTask;
+    private withEffectiveStatus;
+    private effectiveStatusFor;
 }
 
 /**
@@ -11779,6 +12042,8 @@ declare class ScriptRunner {
      * path, as does a version the catalog no longer serves.
      */
     private isProvenanceTrusted;
+    /** A model cannot grant trust by editing a script or supplying an invocation argument. */
+    private isCliTrustedSource;
     private vendorSdk;
     private runSandbox;
     private persistRun;
@@ -12381,6 +12646,12 @@ interface ChatManagerOptions {
     store: Store;
     events: ChatEventBus;
     memory: MemoryManager;
+    /**
+     * Live tools registered by connected apps (see app-tools/relay-registry).
+     * Optional so tests and headless embedders can omit it; absent simply
+     * means no app tools reach any session.
+     */
+    appToolRelays?: AppToolRelayRegistry;
     getPort: () => number;
     getToken: () => string;
     /**
@@ -12874,6 +13145,7 @@ declare class ChatManager extends LocalEngineRuntime {
     readonly usageTracker: UsageTracker;
     readonly telemetry: SessionTelemetryTracker;
     private telemetryGpuUnsub;
+    private readonly appToolRelays;
     constructor(opts: ChatManagerOptions);
     /** PUT /api/config calls this to keep the in-memory cache in sync. */
     setEngagementMode(mode: AIEngagementMode): void;
@@ -13169,8 +13441,13 @@ declare class ChatManager extends LocalEngineRuntime {
      *  background work (the boekwachter enrichment loop) that should never
      *  compete with live chat. */
     isAnyActive(): boolean;
-    /** True while a specific session is running or has an unstarted send. */
-    private isSessionTurnPending;
+    /**
+     * True while a specific session is running or has an unstarted send,
+     * including cold setup before its live state exists. Lifecycle callers
+     * must use this rather than listInflight(), whose display records require
+     * that state and can omit a turn while ensureState is still initializing.
+     */
+    isSessionTurnPending(sessionId: string): boolean;
     /**
      * Returns true when any session owned by `gezelId` has a turn in
      * flight right now, regardless of project. A gezel can only think
@@ -13378,6 +13655,8 @@ declare class ChatManager extends LocalEngineRuntime {
      * toolsets.
      */
     autoAllowedToolsForSession(sessionId: string): Promise<Set<string>>;
+    /** Runtime task read whose lifecycle includes recursive parent inheritance. */
+    private readEffectiveTask;
     /**
      * Snapshot what the model would receive on the next turn for this
      * session — exact system prompt + recent message thread + the
@@ -13541,8 +13820,15 @@ declare class ChatManager extends LocalEngineRuntime {
      */
     private resolveRoutedModelForHandoff;
     /**
-     * Spin up a fresh session for the next gezel in a task step handoff
-     * and kick off the first turn in the background. Used by
+     * Start the next gezel in a task step handoff and kick off its first turn
+     * in the background. A handoff to a different gezel opens a fresh session.
+     * Adjacent steps owned by the same gezel keep one task-scoped session so a
+     * deterministic evidence step (for example, opening an assigned patch)
+     * remains in context for the reasoning step that consumes it. The session
+     * is re-pinned and rebuilt only after the prior turn is idle, because each
+     * step may expose a different exact tool surface.
+     *
+     * Used by
      * `TaskManager.completeStep`'s auto-handoff hook so advancing a step
      * doesn't just flip state — it actually puts the assignee to work.
      *
@@ -13609,7 +13895,8 @@ declare class ChatManager extends LocalEngineRuntime {
     }>;
     /**
      * Lightweight "ping another gezel" path. Unlike `startHandoffSession`
-     * (which is anchored to a task + phase and always opens a fresh session),
+     * (which is anchored to a task + phase and opens a fresh session when the
+     * assignee changes),
      * `messageGezel` drops a message into the target gezel's *active* project
      * session via `ensureOrCreateSession`, so the continuity of their thread
      * is preserved. Internal task re-drives may also pass `taskRef` + `stepId`
@@ -14554,6 +14841,12 @@ declare class ChatManager extends LocalEngineRuntime {
     providerForGezel(gezelId: string, opts?: {
         nightShift?: boolean;
     }): Promise<ProviderName>;
+    /**
+     * Cheap, side-effect-free route preview for the composer. The send path
+     * recomputes the same plan authoritatively; this endpoint exists so users
+     * can see and tune the heuristic before committing the turn.
+     */
+    previewTurnIntent(input: TurnIntentPreviewRequest): Promise<TurnIntentPlan>;
     /**
      * Concurrent one-shot width for a provider: its queue's configured
      * concurrency once initialized (singleton or pooled local engine), else 1.
@@ -14850,6 +15143,18 @@ declare class ChatManager extends LocalEngineRuntime {
      */
     private resolveTurnLibraryRecall;
     private resolveTurnProjectRetrieval;
+    /** Identity of the app-tool surface for a project; '' when no app offers any. */
+    private appToolsFingerprint;
+    /**
+     * App-registered tools that apply to this session.
+     *
+     * Withheld from two kinds of session. A **visitor** session (app-serve) is
+     * an untrusted guest of the project and never sees any extra toolset. A
+     * provider that runs its own tool loop outside our bridge (Copilot, the CLI
+     * providers) cannot reach an in-process server at all, so offering the tools
+     * in its prompt would advertise names it could never call.
+     */
+    private appToolBindingsFor;
     private resolveUserPromptPrelude;
     /**
      * Get or build the live state for a session. On first use after process
@@ -14873,6 +15178,7 @@ declare class ChatManager extends LocalEngineRuntime {
     private scenarioFileRepairConstraintActive;
     private directFileWorkConstraintActive;
     private projectOrchestrationConstraintActive;
+    private exactCraftbookConstraintActive;
     private staleWorkspaceFileRequest;
     /**
      * After bridges spawn, re-render the system prompt's tools block
@@ -15420,12 +15726,13 @@ type FolderScope = 'documents' | 'gezels' | 'projects';
 
 type MoveJobStatus = 'queued' | 'running' | 'done' | 'error' | 'cancelled';
 type MoveJobPhase = 'scan' | 'backup' | 'copy' | 'verify' | 'swap' | 'cleanup' | 'prune';
+type FolderMovePolicy = 'overwrite-all' | 'skip-all' | 'use-destination';
 interface MoveJob {
     id: string;
     scope: FolderScope;
     sourcePath: string;
     destPath: string;
-    conflictPolicy: 'overwrite-all' | 'skip-all';
+    conflictPolicy: FolderMovePolicy;
     status: MoveJobStatus;
     phase?: MoveJobPhase;
     filesDone: number;
@@ -15446,6 +15753,9 @@ declare class JobManager {
     private readonly jobs;
     create(input: Pick<MoveJob, 'scope' | 'sourcePath' | 'destPath' | 'conflictPolicy'>): MoveJob;
     get(id: string): MoveJob | undefined;
+    /** Most recently created job, including its terminal state. The folders
+     *  settings view uses this to recover progress after it is remounted. */
+    latest(): MoveJob | undefined;
     /** True when at least one job is in `queued` or `running` state. The
      *  HTTP layer rejects new moves while a job is active to keep semantics
      *  simple — only one externalization in flight at a time. */
@@ -16209,6 +16519,25 @@ interface TaskRunnerDispatcher {
      * conservative one-wide admission fallback. Optional for test dispatchers.
      */
     ensureProvider?(name: ProviderName): Promise<LLMProvider | null>;
+    /**
+     * Read-only capacity for pool-routed local providers. Their model-specific
+     * provider queues are not addressable through `getProvider(name)`, but the
+     * resident pool can fold those queues into one provider-level summary.
+     */
+    getPooledProviderQueueSummary?(name: ProviderName): {
+        running: number;
+        runningBackground: number;
+        queuedInteractive: number;
+        queuedBackground: number;
+        backgroundConcurrency: number;
+        maxConcurrency: number;
+        active: Array<{
+            sessionId?: string;
+        }>;
+        pending: Array<{
+            sessionId?: string;
+        }>;
+    } | null;
 }
 interface TaskRunnerOptions {
     store: Store;
@@ -16281,6 +16610,14 @@ declare class TaskRunner {
     private readonly nightQuotaHold;
     private readonly pending;
     private readonly activeDispatches;
+    /**
+     * Child tasks admitted into one declarative-fanout cohort. Admission lasts
+     * for the child's whole task, not one step, so a two-step shard completes
+     * read → review before the scheduler opens another sibling and displaces
+     * its local-model prefix cache. Keyed by parent + provider because those
+     * are the resources whose live background width defines the window.
+     */
+    private readonly fanoutAdmissions;
     private nextId;
     /** Why `dispatchable` work isn't moving, as of the last tick. */
     private holdReason;
@@ -17317,6 +17654,8 @@ declare class KnowledgeManager {
         maxResults: number;
         projectId?: string;
     }): Promise<UnifiedSearchResult[]>;
+    /** A document the lexical arms named but no chunk carries: cite it with its lead paragraph. */
+    private toDocumentResult;
     /** A profile's query vector, or undefined when its model is unavailable (that group searches FTS). */
     private embedForProfile;
     private toResult;
@@ -18586,6 +18925,12 @@ interface OllamaEmulationController {
 interface ServiceContext extends EngineContext {
     store: Store;
     chatEvents: ChatEventBus;
+    /**
+     * Tools connected apps register at runtime and answer themselves. Lives in
+     * memory only: a registration is a claim the app is standing by, which no
+     * restart can carry across.
+     */
+    appToolRelays: AppToolRelayRegistry;
     chat: ChatManager;
     /** Iframe-shim runtime errors, looped back into chat preludes. */
     previewLog: PreviewLogBuffer;