@bendyline/gezel-service 1.0.5 → 1.0.6

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _bendyline_gezel from '@bendyline/gezel';
-import { HistoryEvent, HistoryFilter, HistoryEntry, GezelGender, Poppetje, ProjectFileEntry, GezelDetail, GezelConfig, GezelSummary, ProviderName, ChatModelTuning, GezelTrait, ProjectLocalConfig, ImportProvenance, PendingImports, GezelFrontmatter, Project, 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, ChannelStatus, ChannelName, ChatEvent, ChatEventEnvelope, HookSpec, HookPhase, HookResult, ModelTier, ModelStyle, BehaviorId, ModelFamily, ChatMessageToolCall, SamplingBlock, CodexPermissionModeCompat, ModelFitnessTrigger, ModelFitnessRecord, OutlineFileResponse, FileContextResponse, FindSymbolResponse, ReadSymbolResponse, MapRepoResponse, SecurityScanResponse, ScanFindingsRequest, ScanFindingsResponse, SecurityFindingWire, MapAttackSurfaceResponse, ListDependenciesResponse, SecurityOverviewResponse, TraceTaintResponse, FileMapRequest, FileMapResponse, SearchCodeResponse, FileReviewResponse, ListFileIssuesRequest, ListFileIssuesResponse, BoekwachterIssue, SearchDocsResponse, ReadDocAsMarkdownResponse, SearchImagesResponse, FindSimilarImagesResponse, DescribeFolderResponse, FindEntityResponse, ListEntityMentionsResponse, KeurmeesterCaseRecord, TaskStatus, KeurmeesterTriggerKind, KeurmeesterAction, KeurmeesterCaseOutcome, GateCheck, TaskCraftbookStep, TaskCraftbookSource, CraftbookConnectorNeed, CreateTaskRequest, UpdateTaskRequest, TaskAssignee, NewCraftbookStep, StepPosition, UpdateTaskStepRequest, TaskNoteAuthor, TaskVariation, ScriptCapability, ScriptScope, ScriptRunTrigger, ScriptRun, NativeEngineResolveEvent, NativeEngineName, ImageRecognition, RecognitionMode, RecognitionHealth, PreviewLogEntry, SessionGpuTask, SessionTelemetry, AIEngagementMode, ChatMessage, SessionDebugSnapshot, ExpectedDeliverable, CodexSetupStatusResponse, ConfigureCodexRequest, ProjectConnectorBinding, GildeUpdateStatusResponse, GitWorkingChange, GitFileDiffResponse, CodeReviewKind, GitLogEntry, GitCommitDetailResponse, GitSyncResponse, GitConflictFile, GitConflictVersionsResponse, WorkspaceIndexStatus, WorkspaceCommandIndex, WorkspaceSkillIndex, WorkspaceInstructionIndex, CodeReviewRecord, CodeReview, GitHubPullSummary, GitHubPullDetail, GitHubPullFile, GitHubPullComment, ImageModelPullEvent as ImageModelPullEvent$1, VideoAccelerator, RenderImageRequest, ReportActionsResponse, FireReportActionResponse, ReportActionRecord, UnifiedSearchResult, SystemToolsetInstallEvent, SystemToolsetInstallSnapshot, NightShiftWindow, TerminalEventEnvelope, DiscoveredCommand, ServiceRole, ScriptMeta } from '@bendyline/gezel';
+import { ChatSessionSource, ChatEvent, ChatEventEnvelope, HistoryEvent, HistoryFilter, HistoryEntry, ProjectFileEntry, GezelGender, Poppetje, GezelDetail, GezelConfig, GezelSummary, ProviderName, ChatModelTuning, GezelTrait, ProjectLocalConfig, ImportProvenance, PendingImports, 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, AmbientDashboardResolution, AmbientDashboardTheme, AmbientDashboardDisplayTarget, AmbientDashboardStyle, AmbientDashboardState, ChannelStatus, ChannelName, HookSpec, HookPhase, HookResult, ModelTier, ModelStyle, BehaviorId, ModelFamily, ChatMessageToolCall, SamplingBlock, CodexPermissionModeCompat, ModelFitnessTrigger, ModelFitnessRecord, 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, ListEntityMentionsResponse, KeurmeesterCaseRecord, TaskStatus, KeurmeesterTriggerKind, KeurmeesterAction, KeurmeesterCaseOutcome, GateCheck, TaskCraftbookStep, TaskCraftbookSource, CraftbookConnectorNeed, CreateTaskRequest, UpdateTaskRequest, TaskAssignee, NewCraftbookStep, StepPosition, UpdateTaskStepRequest, TaskNoteAuthor, TaskVariation, ScriptCapability, ScriptScope, ScriptRunTrigger, ScriptRun, NativeEngineResolveEvent, NativeEngineName, ImageRecognition, RecognitionMode, RecognitionHealth, PreviewLogEntry, SessionGpuTask, SessionTelemetry, AIEngagementMode, ChatMessage, SessionDebugSnapshot, ExpectedDeliverable, CodexSetupStatusResponse, ConfigureCodexRequest, ProjectConnectorBinding, GildeUpdateStatusResponse, GitWorkingChange, GitFileDiffResponse, CodeReviewKind, GitLogEntry, GitCommitDetailResponse, GitSyncResponse, GitConflictFile, GitConflictVersionsResponse, WorkspaceIndexStatus, WorkspaceCommandIndex, WorkspaceSkillIndex, WorkspaceInstructionIndex, CodeReviewRecord, CodeReview, GitHubPullSummary, GitHubPullDetail, GitHubPullFile, GitHubPullComment, OpenCodeSetupStatusResponse, ConfigureOpenCodeRequest, InstallOpenCodePluginRequest, PiSetupStatusResponse, ConfigurePiRequest, InstallPiExtensionRequest, ImageModelPullEvent as ImageModelPullEvent$1, VideoAccelerator, RenderImageRequest, ReportActionsResponse, FireReportActionResponse, ReportActionRecord, UnifiedSearchResult, StorageJobKind, StorageJob, StorageJobPhase, SystemToolsetInstallEvent, SystemToolsetInstallSnapshot, NightShiftWindow, TerminalEventEnvelope, DiscoveredCommand, VSCodeSetupStatusResponse, ConfigureVSCodeRequest, ServiceRole, ScriptMeta } from '@bendyline/gezel';
 import { ServerType } from '@hono/node-server';
 import { CatalogService } from '@bendyline/gezel-catalog';
 import { ExternalFolders } from '@bendyline/gezel/paths';
@@ -38,21 +38,97 @@ interface LoopbackCert {
     fingerprintBase64: string;
 }
 
+type SessionListener = (event: ChatEvent) => void;
+type EnvelopeListener = (envelope: ChatEventEnvelope) => void;
+interface PublishScope {
+    sessionId: string;
+    gezelId: string;
+    projectId: string;
+    sessionSource?: ChatSessionSource;
+}
 /**
- * Process-wide debug flag.
+ * Per-session chat event bus, plus project-scoped and global fan-out for the
+ * interleaved timeline UI. Each `publish` reaches three subscriber sets:
  *
- * Subsystems hold a shared reference and read `isEnabled()` at the
- * point of logging so a config flip — via `PUT /api/config` —
- * propagates instantly without re-spawning anything. The flag never
- * touches disk itself; the source of truth is `GezelConfig.debugMode`
- * in `~/.gezel/config.json`, re-read on service boot and on every
- * config PUT.
+ *   1. Listeners on this session — bare `ChatEvent`. Get the recent history
+ *      replayed when they subscribe (so a late session-scoped subscriber can
+ *      catch up on the in-flight message). Cleared on `done`.
+ *   2. Listeners on this project — `ChatEventEnvelope` with sessionId/
+ *      gezelId/projectId. Also get the history replayed for any in-flight
+ *      sessions in this project, so a user who tabs away mid-stream and back
+ *      doesn't lose the partial text + tools accumulated during the gap.
+ *   3. Global listeners — `ChatEventEnvelope`. Same replay semantics across
+ *      every in-flight session anywhere.
+ *
+ * History is bus-side only: cleared on `done` so completed turns don't get
+ * re-delivered when a new subscriber connects after the fact.
+ *
+ * If a send truly cannot resolve its session record, it does not know the
+ * gezelId/projectId and publishes session-scoped via `publishSessionOnly`.
+ * Once a record is known, even provider-start failures use `publish` so
+ * project/global clients receive the error.
  */
-declare class DebugFlag {
-    private _enabled;
-    constructor(initial?: boolean);
-    isEnabled(): boolean;
-    set(next: boolean): void;
+declare class ChatEventBus {
+    private readonly sessionBuses;
+    private readonly projectListeners;
+    private readonly gezelListeners;
+    private readonly globalListeners;
+    publish(scope: PublishScope, event: ChatEvent): void;
+    /**
+     * Publish to the session bus only. Used when the manager's early-fail path
+     * doesn't know the gezel/project to envelope (the session record itself
+     * couldn't be loaded). Project + global subscribers never see these.
+     */
+    publishSessionOnly(sessionId: string, event: ChatEvent): void;
+    /**
+     * Publish a project-scoped lifecycle event that has no originating
+     * turn — e.g. `project_created`. Fans out to the project's listeners
+     * and all global listeners, but is deliberately NOT recorded in any
+     * session history: these are one-shot signals, not part of a
+     * replayable transcript, so a subscriber that reconnects later must
+     * not see them re-fired (unlike `publish`, which seeds `deliverToSession`
+     * history that replays until the turn's `done`). `sessionId`/`gezelId`
+     * are empty — the consumers that care (the sidebar refresh bridge)
+     * key off the event payload, not the envelope scope.
+     */
+    publishProjectEvent(projectId: string, event: ChatEvent): void;
+    /**
+     * Publish a project-less global lifecycle event — e.g. `night_shift`.
+     * Reaches only the global listeners (the Meester timeline SSE the UI
+     * subscribes to via `subscribeAll`); like `publishProjectEvent` it is
+     * not recorded in any session history, so reconnecting subscribers do
+     * not see it re-fired. The envelope scope fields are all empty;
+     * consumers key off the event payload.
+     */
+    publishGlobalEvent(event: ChatEvent): void;
+    subscribe(sessionId: string, listener: SessionListener): () => void;
+    subscribeProject(projectId: string, listener: EnvelopeListener): () => void;
+    subscribeGezel(gezelId: string, listener: EnvelopeListener): () => void;
+    subscribeAll(listener: EnvelopeListener): () => void;
+    private deliverToSession;
+    /**
+     * Append an event to a session's replay history, keeping the buffer
+     * lossless for the content that matters. Two rules:
+     *
+     *   1. Transient status pulses (`heartbeat`, `wire_pulse`) are delivered
+     *      live but never recorded — they carry no replayable content, and a
+     *      reasoning-heavy local-model turn emits enough of them to evict
+     *      real deltas out of the 500-event cap.
+     *   2. Adjacent `delta` events coalesce into one entry. A five-minute
+     *      thinking turn streams thousands of per-token deltas; stored
+     *      individually they blow past the cap and the earliest thinking is
+     *      silently dropped on replay. Merged, a text run costs one slot no
+     *      matter how long it streamed. The stored entry is a fresh object —
+     *      the original event was already handed to live listeners and must
+     *      not be mutated.
+     */
+    private recordInHistory;
+    private ensureSession;
+    private cleanupSession;
+    private pruneIdleSessions;
+    private safeDeliver;
+    /** Lightweight observability hook used by tests and diagnostics. */
+    activeSessionCount(): number;
 }
 
 /**
@@ -123,6 +199,18 @@ declare class HistoryManager {
     private sessionMatchesQuery;
 }
 
+interface WalkDirResult {
+    entries: ProjectFileEntry[];
+    /** True when `maxEntries` or `maxDepth` dropped part of the tree. */
+    truncated: boolean;
+}
+
+/** Who is writing. Absent means the person, editing in the app. */
+interface DocumentWriteActor {
+    gezelId?: string;
+    sessionId?: string;
+}
+
 /**
  * Shared format + parser for the daily memory markdown files
  * (`memories/daily/YYYY-MM-DD.md`). These files are the memory system's
@@ -224,12 +312,6 @@ interface JournalContext {
     sessionId?: string;
 }
 
-interface WalkDirResult {
-    entries: ProjectFileEntry[];
-    /** True when `maxEntries` or `maxDepth` dropped part of the tree. */
-    truncated: boolean;
-}
-
 type ProjectArtifactResolveResult = {
     kind: 'found';
     content: string;
@@ -327,6 +409,11 @@ interface StoreOptions {
      * history can construct a bare Store.
      */
     history?: HistoryManager;
+    /**
+     * Test seam: shorten the document-edit audit's quiet window so a test can
+     * observe a sitting close without waiting minutes.
+     */
+    auditQuietWindowMs?: number;
     /**
      * Per-scope external roots, captured at boot from
      * `config.json#externalFolders`. When set, the Store routes reads/
@@ -365,7 +452,8 @@ interface SessionChangeEvent {
     sessionId: string;
 }
 interface DocumentChangeEvent {
-    type: 'write' | 'delete';
+    /** `mkdir` carries no content — listeners that index files skip it. */
+    type: 'write' | 'delete' | 'mkdir';
     path: string;
 }
 interface GezelChangeEvent {
@@ -396,8 +484,8 @@ declare class Store {
      * enqueue-only and never throw work back into the write path.
      */
     private readonly sessionListeners;
-    /** Notified on every document write/delete, including overwrites (which
-     *  emit no history event). Same enqueue-only contract as session listeners. */
+    /** Notified on every document write/delete, including overwrites. Same
+     *  enqueue-only contract as session listeners. */
     private readonly documentListeners;
     /** Notified after a shared gezel has been fully created and is listable.
      *  Project-local gezels use a separate Store path and intentionally do not
@@ -535,6 +623,37 @@ declare class Store {
      */
     private migrateLegacyTemperatureField;
     ensureDefaultProject(): Promise<void>;
+    /**
+     * Ensure the canonical `shared` project exists and points at the resolved
+     * documents root. Its workspace IS the shared document library, so every
+     * per-project service (content index, shadow conversion, enrichment,
+     * watcher, search) reaches the library without a parallel pipeline.
+     *
+     * The library folder is user-owned and possibly cloud-synced, so nothing
+     * here writes into it beyond the one starter document on a first run.
+     *
+     * Returns whether it created the project, so boot can do the one-shot
+     * roster wiring (Boekwachter) exactly once.
+     */
+    ensureSharedProject(): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /**
+     * Id of the shared library project, or null when it does not exist yet
+     * (machine-engine role, or a boot that has not reached the ensure).
+     * Callers that need the library's index — document search, recall — go
+     * through this rather than assuming the default id.
+     */
+    sharedProjectId(): Promise<string | null>;
+    private createSharedProject;
+    /**
+     * One starter document, and only when the library is empty — an explanation
+     * a first-run user can read and edit, not a file we re-create after they
+     * delete it.
+     */
+    private seedSharedLibraryStarterDoc;
+    private backfillSharedProjectDocs;
     /**
      * Seed the curated catch-all docs on installs whose `default` project
      * predates them. Only writes a doc that is genuinely absent — an existing
@@ -545,9 +664,18 @@ declare class Store {
     /**
      * Ensure `config.meesterGezelId` points at a valid gezel. Order of preference:
      *   1. Existing pointer → a live gezel: no-op.
-     *   2. Any other gezels exist: auto-pick the first alphabetically.
-     *   3. No gezels at all: create a fresh Meester with a random name and the
+     *   2. A gezel whose role is already Meester: designate it.
+     *   3. Any other gezels exist: auto-pick the first alphabetically.
+     *   4. No gezels at all: create a fresh Meester with a random name and the
      *      curated about.md from packages/service/src/meester/prompt.ts.
+     *
+     * Step 2 exists because the roster is sorted by name, so taking the first
+     * entry crowned whoever sorted earliest — a Klerk named Ilse ahead of a real
+     * Meester named Ulrike. The badge is only half the job: a Meester's power is
+     * its curated about.md teaching the team-management tools, which a Klerk
+     * does not have, so the front door silently lost its abilities. Reachable
+     * whenever the pointer goes stale (a deleted gezel, a restored backup) and
+     * on any install that mounts a machine-shared roster.
      */
     ensureDefaultMeester(): Promise<void>;
     /**
@@ -835,6 +963,8 @@ declare class Store {
     createProject(input: {
         name: string;
         description?: string;
+        /** Explicit maker's-mark override; missing inherits from the project type. */
+        icon?: ProjectIconId;
         /** Written to documents/about.md at creation. */
         about?: string;
         /** Written to documents/missionObjectives.md at creation. */
@@ -916,6 +1046,8 @@ declare class Store {
     updateProject(id: string, patch: {
         name?: string;
         description?: string;
+        /** Explicit maker's-mark override; null resumes type inheritance. */
+        icon?: ProjectIconId | null;
         workingDir?: string | null;
         voormanGezelId?: string | null;
         voormanAutoAssignedAt?: string;
@@ -1071,14 +1203,21 @@ declare class Store {
     writeProjectDoc(id: string, name: string, content: string): Promise<void>;
     private tryGetProjectMeta;
     projectArtifactsDir(id: string): string;
-    listProjectArtifacts(id: string, subpath?: string): Promise<ProjectFileEntry[]>;
+    listProjectArtifacts(id: string, subpath?: string, opts?: {
+        includeHidden?: boolean;
+    }): Promise<ProjectFileEntry[]>;
     listProjectArtifactsRecursive(id: string, opts?: {
         withStats?: boolean;
+        includeHidden?: boolean;
+        subpath?: string;
     }): Promise<ProjectFileEntry[]>;
     listProjectArtifactsRecursiveDetailed(id: string, opts?: {
         withStats?: boolean;
+        includeHidden?: boolean;
+        subpath?: string;
     }): Promise<WalkDirResult>;
     readProjectArtifact(id: string, filePath: string): Promise<string | null>;
+    projectArtifactSize(id: string, filePath: string): Promise<number | null>;
     /**
      * Read an artifact as raw bytes plus a MIME type guess (from the file
      * extension). Used by binary consumers — e.g. the image-layer resolver
@@ -1166,6 +1305,11 @@ declare class Store {
         createOnly?: boolean;
     }): Promise<string>;
     deleteProjectArtifact(id: string, filePath: string): Promise<void>;
+    createProjectArtifactFolder(id: string, folderPath: string): Promise<string>;
+    renameProjectArtifactPath(id: string, fromPath: string, toPath: string): Promise<{
+        fromPath: string;
+        toPath: string;
+    }>;
     private sessionImagesDir;
     /** Relative path used inside chat-message markdown, e.g. "images/abc.png". */
     private sessionImageRelPath;
@@ -1224,11 +1368,28 @@ declare class Store {
      */
     private resolveWorkspaceDir;
     projectWorkspaceDir(id: string): Promise<string>;
-    listProjectWorkspace(id: string, subpath?: string): Promise<ProjectFileEntry[]>;
-    listProjectWorkspaceRecursive(id: string): Promise<ProjectFileEntry[]>;
-    /** Recursive listing plus the truncation flag, for surfaces that must
-     *  tell the user/model when the walker's entry cap dropped files. */
-    listProjectWorkspaceRecursiveDetailed(id: string): Promise<WalkDirResult>;
+    listProjectWorkspace(id: string, subpath?: string, opts?: {
+        includeHidden?: boolean;
+    }): Promise<ProjectFileEntry[]>;
+    listProjectWorkspaceRecursive(id: string, opts?: {
+        withStats?: boolean;
+        includeHidden?: boolean;
+        subpath?: string;
+    }): Promise<ProjectFileEntry[]>;
+    /**
+     * Recursive listing plus the truncation flag, for surfaces that must tell
+     * the user/model when the walker's entry cap dropped files.
+     *
+     * `subpath` roots the walk instead of post-filtering it, so a caller asking
+     * for one folder is not competing with the whole workspace for the entry
+     * budget — the same contract as the artifacts twin. Entry paths stay
+     * workspace-root-relative, so results remain directly readable.
+     */
+    listProjectWorkspaceRecursiveDetailed(id: string, opts?: {
+        withStats?: boolean;
+        includeHidden?: boolean;
+        subpath?: string;
+    }): Promise<WalkDirResult>;
     listProjectWorkspaceHtmlPages(id: string): Promise<ProjectFileEntry[]>;
     readProjectWorkspaceFile(id: string, filePath: string): Promise<string | null>;
     /**
@@ -1397,7 +1558,18 @@ declare class Store {
     documentsDir(): string;
     listDocuments(subpath?: string): Promise<ProjectFileEntry[]>;
     listDocumentsRecursive(): Promise<ProjectFileEntry[]>;
+    /** Close any in-flight document-edit audit windows (service shutdown). */
+    flushDocumentAudit(): Promise<void>;
+    readDocumentAsMarkdown(filePath: string): Promise<{
+        content: string;
+        converted: boolean;
+    } | null>;
+    listDocumentsRecursiveDetailed(opts?: {
+        withStats?: boolean;
+        includeHidden?: boolean;
+    }): Promise<WalkDirResult>;
     readDocument(filePath: string): Promise<string | null>;
+    documentSize(filePath: string): Promise<number | null>;
     /**
      * Read a shared-library document sidecar as raw bytes. Native document
      * media export uses this for images, narration, and embedded clips while
@@ -1407,7 +1579,7 @@ declare class Store {
         data: Buffer;
         mimeType: string;
     } | null>;
-    writeDocument(filePath: string, content: string): Promise<void>;
+    writeDocument(filePath: string, content: string, actor?: DocumentWriteActor): Promise<void>;
     /**
      * Binary sibling of `writeDocument` — same dir, same path-traversal
      * guard, but writes raw bytes. Powers the squisq editor's Files panel
@@ -1415,7 +1587,7 @@ declare class Store {
      * document.
      */
     writeDocumentBinary(filePath: string, data: Uint8Array): Promise<void>;
-    deleteDocument(filePath: string): Promise<void>;
+    deleteDocument(filePath: string, actor?: DocumentWriteActor): Promise<void>;
     createDocumentFolder(folderPath: string): Promise<void>;
     renameDocument(fromPath: string, toPath: string): Promise<void>;
     writeSession(session: ChatSession): Promise<void>;
@@ -1477,6 +1649,13 @@ declare class Store {
         limit: number;
         before?: string;
         includeArchived?: boolean;
+        /**
+         * Indexed workspace paths for a project, used to recognize workspace
+         * files an assistant reply named in prose. Supplied by the caller
+         * because the listing's owner (`WorkspaceIndexManager`) is built on top
+         * of this Store. Omit it and the backfill sees artifacts only.
+         */
+        workspaceFiles?: (projectId: string) => Promise<readonly string[]>;
     }): Promise<{
         messages: TimelineMessage[];
         hasMore: boolean;
@@ -1695,6 +1874,156 @@ declare class Store {
     writeProjectCraftbookProvenance(projectId: string, id: string, prov: ProjectCraftbookProvenance): Promise<void>;
 }
 
+interface ActivityTrackerOptions {
+    store: Store;
+    history: HistoryManager;
+    chatEvents: ChatEventBus;
+    now?: () => number;
+    persistThresholdMs?: number;
+}
+declare class ActivityTracker {
+    private readonly store;
+    private readonly history;
+    private readonly chatEvents;
+    private readonly now;
+    private readonly persistThresholdMs;
+    /** Newest observed stamp per project (ms epoch). */
+    private readonly latest;
+    /** Stamp last written to (or read from) disk per project. */
+    private readonly persisted;
+    /** Projects whose on-disk stamp has been loaded into `persisted`. */
+    private readonly loads;
+    private readonly writing;
+    private unsubs;
+    constructor(opts: ActivityTrackerOptions);
+    start(): void;
+    stop(): Promise<void>;
+    stamp(projectId: string, atMs: number): void;
+    /**
+     * Newest known activity for a project — max of the in-memory stamp
+     * and the on-disk one (loaded once). Null when the project has never
+     * been observed.
+     */
+    lastActivityAt(projectId: string): Promise<string | null>;
+    /** Persist every stamp that is newer than its on-disk value. */
+    flush(): Promise<void>;
+    private maybePersist;
+    private write;
+    private ensureLoaded;
+}
+
+/**
+ * Render an LLM-authored squisq dashboard document to a PNG via
+ * squisq-cli's canonical dashboard renderer, on the service's managed
+ * Chromium. The doc is pure markdown from the meester — no media — so
+ * the content container is an empty read-only stub.
+ */
+interface RenderAmbientDashboardOptions {
+    home: string;
+    markdown: string;
+    outputPath: string;
+    resolution: AmbientDashboardResolution;
+    /** User-selected Squisq theme; overrides any model-authored frontmatter. */
+    themeId: AmbientDashboardTheme;
+    /** Full primary-display canvas plus its OS-chrome-safe content rectangle. */
+    displayTarget?: AmbientDashboardDisplayTarget;
+    style: AmbientDashboardStyle;
+    /** Title-band fallback when the doc's frontmatter has none. */
+    documentTitle: string;
+    signal?: AbortSignal;
+}
+interface RenderAmbientDashboardResult {
+    outputPath: string;
+    width: number;
+    height: number;
+    /** Top-level block count of the parsed doc — the cell count. */
+    blocks: number;
+}
+type AmbientDashboardRenderer = (opts: RenderAmbientDashboardOptions) => Promise<RenderAmbientDashboardResult>;
+
+type DashboardOneShot = (prompt: string, timeoutMs: number, opts: {
+    gezelId: string;
+    jobLabel: string;
+    tuningProfileId: 'instruct';
+    lane: 'interactive' | 'background';
+    ambient: boolean;
+}) => Promise<string>;
+interface AmbientDashboardGeneratorOptions {
+    home: string;
+    store: Store;
+    history: HistoryManager;
+    activity: ActivityTracker;
+    oneShot: DashboardOneShot;
+    renderer?: AmbientDashboardRenderer;
+    /** Night shift counts as "scheduled work allowed". */
+    isNightShiftActive?: () => boolean;
+    isChatActive?: () => boolean;
+    events?: Pick<ChatEventBus, 'publishGlobalEvent'>;
+    intervalMs?: number;
+    startupDelayMs?: number;
+    now?: () => Date;
+}
+declare class AmbientDashboardGenerator {
+    private readonly home;
+    private readonly store;
+    private readonly history;
+    private readonly activity;
+    private readonly oneShot;
+    private readonly renderer;
+    private readonly isNightShiftActive;
+    private readonly isChatActive;
+    private readonly events?;
+    private readonly intervalMs;
+    private readonly startupDelayMs;
+    private readonly now;
+    private startupTimer;
+    private sweepTimer;
+    private running;
+    constructor(opts: AmbientDashboardGeneratorOptions);
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    readState(): Promise<AmbientDashboardState>;
+    /** One automatic pass through the full gating chain. Exposed for tests. */
+    sweep(): Promise<boolean>;
+    /**
+     * User-requested run. Bypasses the throttle and change gates — only
+     * the enabled/meester/engagement floor applies.
+     */
+    runNow(): Promise<boolean>;
+    private generate;
+    /**
+     * A failed run still advances `lastRunAt` — a chronically-failing
+     * model must not retry every sweep. The input hash only advances on
+     * success, so the next allowed run retries the same input.
+     */
+    private writeState;
+    private collectCandidates;
+    /**
+     * Keep the newest `keep` dated PNGs. Only `dashboard-*.png` files are
+     * eligible — never `latest.png`, the applier's `applied-*.png` slots,
+     * or the state files. Stray temp files from a crashed render go too.
+     */
+    private prune;
+}
+
+/**
+ * Process-wide debug flag.
+ *
+ * Subsystems hold a shared reference and read `isEnabled()` at the
+ * point of logging so a config flip — via `PUT /api/config` —
+ * propagates instantly without re-spawning anything. The flag never
+ * touches disk itself; the source of truth is `GezelConfig.debugMode`
+ * in `~/.gezel/config.json`, re-read on service boot and on every
+ * config PUT.
+ */
+declare class DebugFlag {
+    private _enabled;
+    constructor(initial?: boolean);
+    isEnabled(): boolean;
+    set(next: boolean): void;
+}
+
 /**
  * SecretStore — the one place secrets (API tokens, webhook keys, OAuth
  * access tokens) live at rest. Two implementations ship:
@@ -1762,118 +2091,26 @@ interface SendOptions {
  */
 declare class ChannelManager {
     private readonly store;
-    private readonly secrets;
-    private readonly history;
-    private readonly debug;
-    private readonly channels;
-    private started;
-    constructor(opts: ChannelManagerOpts);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    /**
-     * Called by the config PUT handler when `channels.*` changed. Tears
-     * down every channel and rebuilds from the new config — cheap while
-     * only webhook (stateless) lives here.
-     */
-    reconfigure(): Promise<void>;
-    list(): Promise<ChannelStatus[]>;
-    send(message: string, opts?: SendOptions): Promise<SendResult & {
-        channel?: ChannelName;
-    }>;
-    private defaultChannel;
-    private applyConfig;
-}
-
-type SessionListener = (event: ChatEvent) => void;
-type EnvelopeListener = (envelope: ChatEventEnvelope) => void;
-interface PublishScope {
-    sessionId: string;
-    gezelId: string;
-    projectId: string;
-}
-/**
- * Per-session chat event bus, plus project-scoped and global fan-out for the
- * interleaved timeline UI. Each `publish` reaches three subscriber sets:
- *
- *   1. Listeners on this session — bare `ChatEvent`. Get the recent history
- *      replayed when they subscribe (so a late session-scoped subscriber can
- *      catch up on the in-flight message). Cleared on `done`.
- *   2. Listeners on this project — `ChatEventEnvelope` with sessionId/
- *      gezelId/projectId. Also get the history replayed for any in-flight
- *      sessions in this project, so a user who tabs away mid-stream and back
- *      doesn't lose the partial text + tools accumulated during the gap.
- *   3. Global listeners — `ChatEventEnvelope`. Same replay semantics across
- *      every in-flight session anywhere.
- *
- * History is bus-side only: cleared on `done` so completed turns don't get
- * re-delivered when a new subscriber connects after the fact.
- *
- * If a send truly cannot resolve its session record, it does not know the
- * gezelId/projectId and publishes session-scoped via `publishSessionOnly`.
- * Once a record is known, even provider-start failures use `publish` so
- * project/global clients receive the error.
- */
-declare class ChatEventBus {
-    private readonly sessionBuses;
-    private readonly projectListeners;
-    private readonly gezelListeners;
-    private readonly globalListeners;
-    publish(scope: PublishScope, event: ChatEvent): void;
-    /**
-     * Publish to the session bus only. Used when the manager's early-fail path
-     * doesn't know the gezel/project to envelope (the session record itself
-     * couldn't be loaded). Project + global subscribers never see these.
-     */
-    publishSessionOnly(sessionId: string, event: ChatEvent): void;
-    /**
-     * Publish a project-scoped lifecycle event that has no originating
-     * turn — e.g. `project_created`. Fans out to the project's listeners
-     * and all global listeners, but is deliberately NOT recorded in any
-     * session history: these are one-shot signals, not part of a
-     * replayable transcript, so a subscriber that reconnects later must
-     * not see them re-fired (unlike `publish`, which seeds `deliverToSession`
-     * history that replays until the turn's `done`). `sessionId`/`gezelId`
-     * are empty — the consumers that care (the sidebar refresh bridge)
-     * key off the event payload, not the envelope scope.
-     */
-    publishProjectEvent(projectId: string, event: ChatEvent): void;
-    /**
-     * Publish a project-less global lifecycle event — e.g. `night_shift`.
-     * Reaches only the global listeners (the Meester timeline SSE the UI
-     * subscribes to via `subscribeAll`); like `publishProjectEvent` it is
-     * not recorded in any session history, so reconnecting subscribers do
-     * not see it re-fired. The envelope scope fields are all empty;
-     * consumers key off the event payload.
-     */
-    publishGlobalEvent(event: ChatEvent): void;
-    subscribe(sessionId: string, listener: SessionListener): () => void;
-    subscribeProject(projectId: string, listener: EnvelopeListener): () => void;
-    subscribeGezel(gezelId: string, listener: EnvelopeListener): () => void;
-    subscribeAll(listener: EnvelopeListener): () => void;
-    private deliverToSession;
-    /**
-     * Append an event to a session's replay history, keeping the buffer
-     * lossless for the content that matters. Two rules:
-     *
-     *   1. Transient status pulses (`heartbeat`, `wire_pulse`) are delivered
-     *      live but never recorded — they carry no replayable content, and a
-     *      reasoning-heavy local-model turn emits enough of them to evict
-     *      real deltas out of the 500-event cap.
-     *   2. Adjacent `delta` events coalesce into one entry. A five-minute
-     *      thinking turn streams thousands of per-token deltas; stored
-     *      individually they blow past the cap and the earliest thinking is
-     *      silently dropped on replay. Merged, a text run costs one slot no
-     *      matter how long it streamed. The stored entry is a fresh object —
-     *      the original event was already handed to live listeners and must
-     *      not be mutated.
+    private readonly secrets;
+    private readonly history;
+    private readonly debug;
+    private readonly channels;
+    private started;
+    constructor(opts: ChannelManagerOpts);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Called by the config PUT handler when `channels.*` changed. Tears
+     * down every channel and rebuilds from the new config — cheap while
+     * only webhook (stateless) lives here.
      */
-    private recordInHistory;
-    private ensureSession;
-    private cleanupSession;
-    private pruneIdleSessions;
-    private safeDeliver;
-    /** Lightweight observability hook used by tests and diagnostics. */
-    activeSessionCount(): number;
+    reconfigure(): Promise<void>;
+    list(): Promise<ChannelStatus[]>;
+    send(message: string, opts?: SendOptions): Promise<SendResult & {
+        channel?: ChannelName;
+    }>;
+    private defaultChannel;
+    private applyConfig;
 }
 
 /**
@@ -1986,6 +2223,18 @@ type HookRunner = (hook: ActiveHook, ctx: {
 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>;
@@ -1994,6 +2243,8 @@ interface StdioMcpServerSpec {
 }
 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).
@@ -2282,6 +2533,20 @@ interface PromptCtx extends ModelCtx {
     isMeester: boolean;
     /** The gezel's about.md content (already loaded). */
     about: string;
+    /**
+     * Tool names actually wired for this session (post-allowlist).
+     *
+     * A behavior whose whole point is "reach for tool X instead of tool Y"
+     * must gate on this and return null when X is absent. The rendered block
+     * is also passed through `filterPromptToolDirectives`, but that pass is
+     * lexical: it drops a line only when the line reads as a directive, and
+     * "write a small Node script and execute it — `derive_file(...)`" does
+     * not match, so the block survived intact on a roster with no execution
+     * tool at all and prescribed a remedy the session could not perform.
+     * Positive gating here is the reliable half; the lexical filter is the
+     * backstop for phrasings a behavior author did not anticipate.
+     */
+    availableToolNames: ReadonlySet<string>;
 }
 /**
  * Context for per-turn hooks: {@link Behavior.userPromptPrelude} and
@@ -2311,6 +2576,17 @@ interface TurnCtx extends ModelCtx {
     assistantContent: string;
     /** How many continuation nudges have already fired in this user-initiated send. */
     continuationCount: number;
+    /**
+     * Shared-library documents matching THIS turn's message, resolved before
+     * the prelude hooks run (they are synchronous; the search is not).
+     * Populated only for user-origin turns, and only with matches strong
+     * enough to be worth the tokens — usually absent.
+     */
+    libraryRecall?: ReadonlyArray<{
+        path: string;
+        snippet: string;
+        score: number;
+    }>;
 }
 /**
  * Verdict returned by {@link Behavior.postTurnDetector} when a
@@ -2655,6 +2931,18 @@ interface QuotaBucket {
     overage: number;
     resetDate?: string;
 }
+interface UsageTurn {
+    model: string;
+    inputTokens: number;
+    /** Portion of `inputTokens` served from the provider's prompt cache; absent when unreported. */
+    cachedInputTokens?: number;
+    outputTokens: number;
+    cost: number;
+    durationMs: number;
+    /** Engine-reported decode rate for this turn; absent when unreported. */
+    outputTokensPerSec?: number;
+    at: string;
+}
 interface ProviderUsage {
     /** Non-empty only for providers that report account quota windows. */
     quotaBuckets: QuotaBucket[];
@@ -2685,8 +2973,30 @@ interface ProviderUsage {
      * "n/a" rather than zero.
      */
     medianOutputTokensPerSec: number | null;
+    /**
+     * The same median decode rate split per model, for the turns that reported
+     * one. A 27B and a 4B averaged together is a number describing nothing, and
+     * the question a user actually asks — "how fast is this model on my machine"
+     * — is per model. Sorted fastest first; empty for providers that report no
+     * throughput at all.
+     *
+     * This is the durable half of the speed story: it spans every session the
+     * daemon has served, so it is still there when a page reloads mid-turn and
+     * the client-side rolling window is empty.
+     */
+    modelSpeeds: ModelSpeed[];
+    /** Most recently completed turn, retained independently of the UI's rolling window. */
+    lastTurn: UsageTurn | null;
     lastUpdated: string | null;
 }
+/** Per-model decode-rate rollup inside {@link ProviderUsage}. */
+interface ModelSpeed {
+    model: string;
+    /** Median engine-reported decode rate across this model's turns. */
+    medianOutputTokensPerSec: number;
+    /** Turns that contributed a rate — not the model's total turn count. */
+    turns: number;
+}
 interface UsageSummary {
     providers: {
         copilot?: ProviderUsage;
@@ -2715,6 +3025,8 @@ declare class UsageTracker {
      * those windows without inventing a zero-token turn or skewing totals.
      */
     recordQuotaBuckets(provider: ProviderName, buckets: QuotaBucket[], at?: string): void;
+    /** Latest quota buckets recorded for `provider`; empty when never reported. */
+    quotaBucketsFor(provider: ProviderName): QuotaBucket[];
     summary(): UsageSummary;
     private ensure;
 }
@@ -2767,7 +3079,7 @@ type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORTS)[number];
  * — no wasted work. Already-running entries abort normally via the
  * same signal.
  *
- * ## Ambient admission control (single-lane engine protection)
+ * ## Ambient admission control (foreground-capacity protection)
  *
  * On a local engine, a housekeeping turn (scheduler nudge, memory
  * extraction, icon/about generation) occupies the GPU for minutes.
@@ -2777,17 +3089,19 @@ type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORTS)[number];
  * engine is idle while the user READS, ambient work sneaks in, and
  * the user's move then waits out a 3-minute nudge turn).
  *
- * When `ambientQuietMs > 0`, entries marked `ambient: true` dispatch
- * only when BOTH hold: no non-ambient work is running or pending, and
- * no non-ambient activity (enqueue, dispatch, or release, any lane)
- * happened within the last `ambientQuietMs`. Reading time counts as
- * engagement: page reactions and tool-loop turns are non-ambient, so
- * an active game holds the gate closed between moves. Ambient entries
- * are exempt from the anti-starvation guard while gated — deferring
- * them indefinitely during active use is the feature, not a bug; they
- * run when the user steps away. The gate never touches non-ambient
- * work, so mid-turn compaction (which a foreground turn awaits) and
- * user-facing background turns are unaffected.
+ * When an engine has more than one interactive slot, ambient work may
+ * use otherwise-idle capacity immediately, but only while at least one
+ * physical slot stays free for a newly-arriving foreground chat. On a
+ * single-slot engine — or once a multi-slot engine reaches that protected
+ * headroom — entries marked `ambient: true` dispatch only when BOTH hold:
+ * no non-ambient work is running or pending, and no non-ambient activity
+ * (enqueue, dispatch, or release, any lane) happened within the last
+ * `ambientQuietMs`. Reading time counts as engagement: page reactions and
+ * tool-loop turns are non-ambient, so an active game holds the gate closed
+ * between moves when there is no safe spare capacity. Ambient entries are
+ * exempt from the anti-starvation guard while gated. The gate never touches
+ * non-ambient work, so mid-turn compaction (which a foreground turn awaits)
+ * and user-facing background turns are unaffected.
  */
 type Lane = 'interactive' | 'background';
 interface EnqueueRequest {
@@ -2796,9 +3110,10 @@ interface EnqueueRequest {
      * Marks truly-deferrable housekeeping (scheduler nudges, memory
      * extraction, icon/about generation, digests, night-shift chores).
      * When the queue was built with {@link ProviderQueueOptions.ambientQuietMs},
-     * ambient entries dispatch only after a quiet window with no
-     * NON-ambient activity — see "Ambient admission control" in the
-     * class header. Distinct from `lane: 'background'`: background
+     * ambient entries use safe spare capacity immediately, or otherwise
+     * wait for a quiet window with no NON-ambient activity — see "Ambient
+     * admission control" in the class header. Distinct from `lane:
+     * 'background'`: background
      * covers anything that shouldn't cut in front of a typed chat turn,
      * which includes user-facing work (checkers page reactions, mid-turn
      * compaction a foreground turn awaits) that must NEVER be held.
@@ -2905,10 +3220,12 @@ interface ProviderQueueOptions {
     maxWaitMs?: number;
     /**
      * Quiet window for ambient admission control — see the class header.
-     * Entries marked `ambient: true` dispatch only after this many ms
-     * with no non-ambient activity (and none running or pending). 0 or
-     * unset disables the gate (ambient entries behave like plain
-     * background). Local single-GPU engines pass
+     * On a multi-slot engine, entries marked `ambient: true` may dispatch
+     * sooner while one physical foreground slot remains protected. Once
+     * that headroom is reached, they wait for this many ms with no
+     * non-ambient activity (and none running or pending). 0 or unset
+     * disables the gate (ambient entries behave like plain background).
+     * Local single-GPU engines pass
      * {@link defaultAmbientQuietMs}; cloud queues leave it off.
      */
     ambientQuietMs?: number;
@@ -2974,6 +3291,14 @@ declare class ProviderQueue {
      */
     describe(): {
         running: number;
+        /**
+         * In-flight slots split by lane. `running` alone cannot answer "how
+         * many conversations are live right now?" — a queue holding nothing
+         * but index-enrichment one-shots still reports `running: 1`, which
+         * the pill used to render as "1 running" beside a chat-shaped noun.
+         */
+        runningInteractive: number;
+        runningBackground: number;
         queuedInteractive: number;
         queuedBackground: number;
         /** Pending ambient entries currently held by the admission gate. */
@@ -3037,9 +3362,15 @@ declare class ProviderQueue {
      */
     private maybeScheduleAmbientRecheck;
     /**
-     * True when ambient entries may dispatch: gate disabled, or no
-     * non-ambient work anywhere on the queue AND the quiet window has
-     * fully elapsed since the last non-ambient activity.
+     * True when ambient entries may dispatch.
+     *
+     * A multi-slot engine may spend spare capacity immediately while keeping
+     * one of its physical interactive slots unused. `running` is deliberately
+     * compared with `interactiveConcurrency - 1`, rather than with the queue's
+     * total `concurrency`: local queues carry one extra logical background lane
+     * for deadlock-breaking one-shots, but that lane is not another native KV
+     * slot. Once protected headroom is exhausted, the ordinary quiet-window
+     * rule applies.
      */
     private ambientGateOpen;
     /**
@@ -3817,9 +4148,10 @@ interface LLMSession {
     onDelta(handler: (chunk: string) => void): () => void;
     /**
      * Subscribe to live private-reasoning deltas, streamed separately from
-     * the visible reply so they never enter the committed body or the
-     * external API-compat forwarders. Optional — only providers with a
-     * distinct reasoning channel (llama-cpp/ds4) fire it.
+     * the visible reply so they never enter the committed body. API-compat
+     * forwarders omit this private channel unless their client contract opts
+     * in explicitly. Optional — only providers with a distinct reasoning
+     * channel (llama-cpp/ds4) fire it.
      */
     onReasoningDelta?(handler: (chunk: string) => void): () => void;
     onUsage(handler: (usage: TurnUsage) => void): () => void;
@@ -3844,7 +4176,7 @@ interface LLMSession {
      * calls arrive whole (Ollama) or run server-side (Copilot, OpenAI)
      * leave it undefined.
      */
-    onToolArgsDelta?(handler: (name: string, chunk: string) => void): () => void;
+    onToolArgsDelta?(handler: (name: string, chunk: string, meta?: ToolArgsDeltaMeta) => void): () => void;
     /**
      * Optional: subscribe to phase-announcement events. Currently only
      * `CopilotSession` emits these (SDK `assistant.intent` events from
@@ -3971,6 +4303,13 @@ interface ExternalToolCall {
     name: string;
     arguments: string;
 }
+/** Identity attached to a live structured tool-argument fragment. */
+interface ToolArgsDeltaMeta {
+    /** OpenAI-compatible position within the assistant's tool_calls array. */
+    index?: number;
+    /** Provider-supplied call id, normally present on the first fragment. */
+    id?: string;
+}
 /**
  * Context describing one would-be batch member, passed to
  * {@link BatchCapability.admit} so an engine can make a live headroom
@@ -4399,11 +4738,14 @@ declare class CapacityBroker {
     /**
      * Fallback estimate when a catalog entry lacks `residentBytes`.
      * Used by callers building reservation requests from
-     * `approxSizeBytes`. Multipliers reflect typical working-set
-     * footprint vs. on-disk size at default context.
+     * `approxSizeBytes`. Reflects the working-set footprint vs. on-disk
+     * size WITHOUT any KV — every caller prices KV explicitly on top.
      *
-     * llama.cpp at Q4_K_M with 8K ctx: ~1.20 × on-disk.
-     * MLX at 4bit with 8K ctx: ~1.30 × on-disk (KV grows faster).
+     * llama.cpp: see {@link estimateLlamaCppResidentBytes}. Pass `mmprojBytes`
+     * for a multimodal model — `approxSizeBytes` counts the weights alone, and
+     * the projector plus its vision buffers is 1.7 GB on a 30B.
+     * MLX: see {@link estimateMlxResidentBytes}. MLX needs no equivalent — its
+     * vision tower is inside the same safetensors set `approxSizeBytes` sums.
      *
      * ds4 is special: it streams MoE experts from SSD, so its resident
      * working set is bounded by the configured expert-cache budget + KV +
@@ -4412,7 +4754,9 @@ declare class CapacityBroker {
      * conservative streaming working set so a 64GB box is never told an
      * 87GB DeepSeek-V4 model "can't fit" (which is the whole point of ds4).
      */
-    static estimateResidentBytes(engine: LocalProviderName, approxSizeBytes: number): number;
+    static estimateResidentBytes(engine: LocalProviderName, approxSizeBytes: number, opts?: {
+        mmprojBytes?: number;
+    }): number;
 }
 
 /**
@@ -4581,6 +4925,9 @@ interface PoolSnapshot {
  */
 interface PooledQueueSummary {
     running: number;
+    /** See {@link ProviderQueue.describe}. Summed across replicas like `running`. */
+    runningInteractive: number;
+    runningBackground: number;
     queuedInteractive: number;
     queuedBackground: number;
     /** Pending ambient entries held by the admission gate across replicas. */
@@ -4663,6 +5010,18 @@ declare class ProviderPool {
      * Returns false when the engine has already gone away.
      */
     unloadIdle(key: string): Promise<boolean>;
+    /**
+     * Unload every resident engine that is idle right now, leaving busy ones
+     * running. Returns the keys that stayed resident because they were serving
+     * a turn — the caller reports them; the ordinary LRU / idle-retention path
+     * collects them once they go quiet.
+     *
+     * This is what a live config reset uses. {@link shutdown} is the other
+     * shape — it force-evicts busy engines too — and is only correct when the
+     * process is going away (service shutdown, emergency stop), because a
+     * forced eviction kills whatever turn is streaming.
+     */
+    releaseIdle(): Promise<string[]>;
     /**
      * Evict a specific entry. Awaits the provider's `shutdown` so the
      * disk-cache flush (Tier 1 prior plan) completes before the broker
@@ -5191,6 +5550,17 @@ declare class ContentIndex {
         stale: number;
         pending: number;
     } | null>;
+    /**
+     * Indexing work this project recorded in `[since, until)` — summaries,
+     * reviews, and AI shadows, from the tiers' own stamps. Null when the
+     * project has no index (or it's momentarily unavailable); callers tally
+     * across projects and treat that as "nothing to add", never as zero work.
+     */
+    workCountsSince(projectId: string, since: string, until: string): Promise<{
+        summarized: number;
+        reviewed: number;
+        described: number;
+    } | null>;
     /** One file's boekwachter review (`file_review` tool). */
     fileReview(projectId: string, relPath: string): Promise<FileReviewResponse>;
     /** Flat issue query across current-hash reviews (`list_file_issues` tool). */
@@ -5205,6 +5575,28 @@ declare class ContentIndex {
     settleBoekwachterIssuesForTask(projectId: string, taskRef: string, outcome: 'complete' | 'canceled'): Promise<number>;
     private boekwachterIssuesForPath;
     searchDocs(projectId: string, query: string, maxResults?: number): Promise<SearchDocsResponse>;
+    /**
+     * Content search over the shared document library.
+     *
+     * The library is a project, so this is the ordinary hybrid searcher
+     * (embeddings + keyword) reshaped to document identity: callers name a
+     * document by the path the user filed it under, never by the converted
+     * markdown the snippet happened to come from. That mapping is why this
+     * exists rather than callers using `searchCode` directly.
+     */
+    searchLibrary(projectId: string, query: string, opts?: {
+        maxResults?: number;
+        queryVector?: number[];
+    }): Promise<SearchDocumentsResponse>;
+    /**
+     * One-line descriptions for library documents, keyed by path.
+     *
+     * Two sources, in precedence order: the document's own frontmatter
+     * `description`/`title` — the user said what this is, so nothing should
+     * outrank it — then the Boekwachter's generated summary. Absent entries
+     * simply have no description; a listing renders the bare path.
+     */
+    libraryDescriptions(projectId: string): Promise<Map<string, string>>;
     readDocAsMarkdown(projectId: string, relPath: string): Promise<ReadDocAsMarkdownResponse>;
     /**
      * Schedule a rebuild of the project's artifacts-corpus index. Debounced per
@@ -5787,6 +6179,19 @@ interface GateCheckOutcome {
     detail: string;
     /** Machine evidence preserved from the rich CheckResults (arrays sliced to ≤10). */
     evidence?: Record<string, unknown>;
+    /**
+     * Discrete items this check still wants, for checks that count in items
+     * at all (unread corpus records, uncovered paths). Folded into the
+     * plateau signature, which is what lets a gate a craftbook is DESIGNED
+     * to fail repeatedly — a bounded batch loop — read as progress instead
+     * of a stall while the count falls.
+     *
+     * Only set this where the count is deterministic for a given
+     * deliverable: a number that jitters on identical content would reset
+     * the ladder forever and hide a real plateau. Leaving it unset keeps
+     * the legacy identity-only behavior exactly.
+     */
+    remaining?: number;
 }
 interface GateCheckResult {
     pass: boolean;
@@ -5874,11 +6279,17 @@ declare function gateCheckLabel(c: GateCheck): string;
  *   stage 3 — stop: pause with the full attempt trail as diagnosis.
  *
  * The plateau signature hashes failing-check IDENTITY (GateCheckOutcome
- * labels), not prose and not content bytes: byte churn with an unmoved
- * failure set IS the plateau (the eval harness's retryLoopSniffKey
- * lesson), while clearing any single check changes the signature and
- * resets the ladder. Kill-switch: GEZEL_DISABLE_GATE_ESCALATION=1
- * restores the legacy quiet-damper behavior.
+ * labels) plus any outstanding-item count those checks report, not prose
+ * and not content bytes: byte churn with an unmoved failure set IS the
+ * plateau (the eval harness's retryLoopSniffKey lesson), while clearing a
+ * check — or covering more of what a counting check still wants — changes
+ * the signature and resets the ladder. The count matters because some
+ * craftbooks are DESIGNED to fail a gate repeatedly (bounded batch loops
+ * over a corpus too large for one context); identity alone cannot tell
+ * those from a stall, and calling them a stall pushes the assignee toward
+ * the smallest edit that clears the check rather than the work.
+ * Kill-switch: GEZEL_DISABLE_GATE_ESCALATION=1 restores the legacy
+ * quiet-damper behavior.
  */
 
 type EscalationStage = 0 | 1 | 2 | 3;
@@ -6436,14 +6847,18 @@ declare class TaskManager {
      */
     private runCompletionGate;
     /**
-     * A rejected gate is unsatisfiable when a FAILING check reads the
-     * workspace tree while gezel workspace writes are off for the project
-     * (gate scripts always read the workspace, so a script rejection
-     * qualifies too). Returns the workspace files the failing checks name
-     * (possibly empty), or null when the gate is repairable. Drawer-only
-     * failures stay repairable — the artifacts drawer is deliberately
-     * exempt from the writes-off policy.
+     * True when EVERY one of `tasks` is parked on a step that owes a
+     * workspace file managed writes can't produce. Lets the ambient nudger
+     * tell a genuinely stuck writes-off project from one doing artifact-only
+     * work — the drawer is exempt from the writes-off policy, so a nightly
+     * report or a review still completes there and its voorman still wants
+     * the check-in.
+     *
+     * Conservative by construction: an empty list, a task with no active
+     * step, or any step whose deliverable is satisfiable all answer `false`.
+     * We only claim "blocked" on positive evidence for every task.
      */
+    allActiveStepsBlockedByWorkspaceWrites(projectId: string, tasks: Task[]): Promise<boolean>;
     /**
      * The workspace files a step must produce that no assignee is able to
      * write. The proactive twin of {@link unsatisfiableWorkspaceGateFiles}:
@@ -6464,6 +6879,22 @@ declare class TaskManager {
      * must skip the handoff — dispatching a gezel here cannot succeed.
      */
     private pauseIfStepUnsatisfiable;
+    /**
+     * A rejected gate is unsatisfiable when a FAILING check reads the
+     * workspace tree while gezel workspace writes are off for the project.
+     * Returns the workspace files the failing checks name (possibly empty),
+     * or null when the gate is repairable. Drawer-only failures stay
+     * repairable — the artifacts drawer is deliberately exempt from the
+     * writes-off policy.
+     *
+     * A gate SCRIPT names no file, so it is judged by what the step itself
+     * owes: unwinnable only when the step's own deliverable is a workspace
+     * file nobody can write. Counting every script rejection as a
+     * workspace-write failure misread the note-only gate on Pull Request
+     * Review's scope step — the note was written correctly and the real
+     * fault was elsewhere, but the task paused telling the user to enable
+     * workspace writes, which would have changed nothing.
+     */
     private unsatisfiableWorkspaceGateFiles;
     /**
      * Gate-driven loop-back: re-activate `targetId` WITHOUT completing the
@@ -6471,6 +6902,11 @@ declare class TaskManager {
      * hook even when the target IS the gated step itself — `onReject:
      * <self>` deliberately produces a fresh activation + handoff session
      * each rejection (the loop shape that carries small models).
+     *
+     * A fresh SESSION is not a fresh BUDGET, though: when the route points
+     * back at the gated step, the rejection count has to survive the
+     * re-activation or `maxAttempts` is unreachable and the loop never
+     * escalates. See the self-loop carve-out in {@link bumpStepActivation}.
      */
     private reactivateStepForGate;
     /**
@@ -6847,6 +7283,12 @@ declare class EngineRouter {
      * Provider is fixed to the caller's chosen engine.
      */
     reconcileClones(provider: LocalProviderName, target: Record<string, number>): Promise<void>;
+    /**
+     * Unload every resident replica that is not mid-turn. Returns the keys left
+     * resident because they were busy. Used by a live config reset, which needs
+     * the memory back but must not sever work in flight.
+     */
+    releaseIdle(): Promise<string[]>;
     /** Unload one resident replica immediately, provided it is still idle. */
     unloadIdle(provider: LocalProviderName, modelId: string, replicaIdx: number): Promise<boolean>;
     snapshot(): PoolSnapshot;
@@ -7609,6 +8051,35 @@ interface ModelBundleSource {
     catalogVersion?: string;
 }
 
+/**
+ * "Is a newer build of this model available?" — asked of the payload, not of
+ * the version string.
+ *
+ * Both engine managers (llama.cpp/ds4 and MLX) and the chat manager's
+ * per-session staleness notice used to answer this by comparing the installed
+ * `catalogVersion` to the catalog's current one. That flags every catalog
+ * edit, including the metadata-only ones the runtime has already picked up,
+ * and the only remedy any surface offers is a multi-gigabyte re-download. Here
+ * the version difference is the *trigger* for a check, and
+ * {@link comparePayloadIdentity} is the answer.
+ *
+ * When the payload turns out to be unchanged we record that finding in the
+ * install manifest (a `payloadFingerprint`) so later checks are a string
+ * compare. `catalogVersion` is deliberately left alone: it means "the version
+ * whose description these bytes were downloaded against", which is what the
+ * `.gezmodel` exporter pins and what model-fitness records compare, and
+ * rewriting it would silently invalidate both.
+ */
+
+interface ModelUpdateStatus {
+    /** True only when the catalog's payload differs from the copy on disk. */
+    updateAvailable: boolean;
+    /** The catalog's current version, when it differs from the installed one. */
+    availableVersion?: string;
+    /** Why, in one sentence — surfaced in the model manager's tooltip. */
+    reason?: string;
+}
+
 interface IncompleteModelDownload {
     id: string;
     /** Total bytes on disk across the directory (payload + `.partial`). */
@@ -7711,6 +8182,19 @@ interface InstalledMlxModel {
      * Delete that can only fail.
      */
     readOnly?: boolean;
+    /**
+     * True when the catalog now describes a different PAYLOAD than the one on
+     * disk — different repo, file list, or hashes. A version bump that only
+     * edits metadata (tuning, sizing hints, wording) deliberately does not set
+     * this: the runtime resolves that live from the catalog, so there is nothing
+     * for the user to download. Computed server-side in
+     * {@link MlxModelManager.listInstalled} so every surface agrees.
+     */
+    updateAvailable?: boolean;
+    /** The catalog's current version, when it differs from the installed one. */
+    availableVersion?: string;
+    /** What changed, in one sentence, for the model manager's tooltip. */
+    updateReason?: string;
 }
 /**
  * Snapshot of an in-flight MLX install — same shape as
@@ -7830,6 +8314,19 @@ declare class MlxModelManager {
     constructor(opts: MlxModelManagerOptions);
     getActiveInstalls(): MlxActiveInstallSnapshot[];
     listInstalled(): Promise<InstalledMlxModel[]>;
+    /**
+     * Whether a genuinely newer build of one installed model exists. Null when
+     * the id isn't installed for MLX. Shared with the chat manager's
+     * per-session staleness notice so a user is never told to re-download for a
+     * change that only touched metadata.
+     */
+    getUpdateStatus(id: string): Promise<ModelUpdateStatus | null>;
+    /**
+     * Compare one installed copy against the live catalog. The catalog lookup
+     * runs for every model on every inventory poll; the manifest re-read only
+     * happens for the few whose version actually moved.
+     */
+    private evaluateDrift;
     /**
      * List incomplete MLX downloads — directories that hold bytes but no
      * `manifest.json`, so they never surface in {@link listInstalled}. Tagged
@@ -7877,6 +8374,14 @@ declare class MlxModelManager {
      *                  worker owns the error.
      */
     private downloadFileConcurrent;
+    /**
+     * Files the plan asks for that are already on disk as exactly the bytes the
+     * catalog pins, keyed by filename with the digest to carry forward. See
+     * {@link LlamaCppModelManager.planReusableFiles} — same trust model: a
+     * digest this install recorded after verifying it, plus a file still at its
+     * pinned length, is identity.
+     */
+    private planReusableFiles;
     /** Warn once per model directory per process, then stay quiet. */
     private warnSkip;
     private loadInstalled;
@@ -8058,6 +8563,15 @@ interface InstalledLlamaCppModel {
      * video inputs on llama-server. Absent → text-only model.
      */
     mmprojPath?: string;
+    /**
+     * On-disk size of {@link mmprojPath}, read from the file rather than the
+     * manifest. `approxSizeBytes` does NOT include the projector — the value
+     * recorded at install time is the weights alone whenever the payload was
+     * adopted or resumed rather than freshly downloaded — so every memory
+     * estimate has to add this explicitly or it under-reserves a vision model
+     * by the projector plus its compute buffers (1.7 GB on muse-glimmer).
+     */
+    mmprojSizeBytes?: number;
     /**
      * Absolute path to a speculative-decoding companion GGUF, when the
      * catalog ships one. The launcher forwards it as
@@ -8096,15 +8610,20 @@ interface InstalledLlamaCppModel {
      */
     readOnly?: boolean;
     /**
-     * True when the catalog now ships a different version than the one this
-     * model was downloaded against — a newer build is available. Lets the
-     * model manager offer "Update" (re-download + replace in place) instead
-     * of forcing the user to delete and re-fetch. Computed in
+     * True when the catalog now describes a different PAYLOAD than the one on
+     * disk — a newer build whose bytes this copy does not have. Lets the model
+     * manager offer "Update" (fetch what differs, replace in place) instead of
+     * forcing the user to delete and re-fetch. A catalog version bump that
+     * leaves the files alone (retuning, sizing hints, wording) deliberately
+     * does not set this: the runtime resolves that metadata live, so there is
+     * nothing for the user to download. Computed in
      * {@link LlamaCppModelManager.listInstalled} against the live catalog.
      */
     updateAvailable?: boolean;
     /** The catalog's current version, when it differs from the installed one. */
     availableVersion?: string;
+    /** What changed, in one sentence, for the model manager's tooltip. */
+    updateReason?: string;
 }
 type InstallEvent = {
     type: 'progress';
@@ -8300,6 +8819,19 @@ declare class LlamaCppModelManager {
      * needs the `contextWindow` to set `--ctx-size` correctly.
      */
     resolveModel(id: string): Promise<InstalledLlamaCppModel | null>;
+    /**
+     * Whether a genuinely newer build of one installed model exists. Null when
+     * the id isn't installed for this engine. Shared with the chat manager's
+     * per-session staleness notice so a user is never told to re-download for a
+     * change that only touched metadata.
+     */
+    getUpdateStatus(id: string): Promise<ModelUpdateStatus | null>;
+    /**
+     * Compare one installed copy against the live catalog. The catalog lookup
+     * runs for every model on every inventory poll; the manifest re-read only
+     * happens for the few whose version actually moved.
+     */
+    private evaluateDrift;
     delete(id: string): Promise<void>;
     /** Provider-owned snapshot used by the streaming `.gezmodel` exporter. */
     getModelBundleSource(id: string): Promise<ModelBundleSource>;
@@ -8335,6 +8867,19 @@ declare class LlamaCppModelManager {
      * cleanup with each early `return` and silently rot.
      */
     private runInstall;
+    /**
+     * Files the plan asks for that are already on disk as exactly the bytes the
+     * catalog pins, keyed by filename with the digest to carry forward.
+     *
+     * An update usually rotates one thing — a quant, one shard, an added draft
+     * companion — and re-fetching the rest is pure waste. The install manifest
+     * records a sha256 for every file it published, each verified against the
+     * catalog when it landed; where that digest equals the pin we are about to
+     * download and the file is still its full length, the bytes on disk ARE the
+     * bytes we would fetch. Same trust model as the shared-store adoption cache:
+     * a recorded digest plus an unchanged stat is identity.
+     */
+    private planReusableFiles;
     /** Warn once per model directory per process, then stay quiet. */
     private warnSkip;
     private loadInstalled;
@@ -8436,6 +8981,55 @@ interface RemotesRegistry {
     touch(remoteId: string): void;
 }
 
+interface ExternalTranscriptToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+interface ExternalTranscriptMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: ExternalTranscriptToolCall[];
+    toolCallId?: string;
+}
+interface BeginExternalConversationInput {
+    sourceId: string;
+    sourceName: string;
+    externalConversationId: string;
+    workingDirectory?: string;
+    projectHint?: string;
+    gezelId: string;
+    providerName: ProviderName;
+    model?: string;
+    messages: ExternalTranscriptMessage[];
+    /** Effective prompt and tool roster that were actually supplied this request. */
+    effectiveSystemMessage: string;
+    toolNames: string[];
+    /** Receipt block injected into the model-facing final tool result, when any. */
+    actionLedger?: string;
+}
+interface ResolveExternalConversationInput {
+    sourceId: string;
+    gezelId: string;
+    messages: ExternalTranscriptMessage[];
+    /** Unique id for a genuinely new thread, normally the caller's request id. */
+    fallbackExternalConversationId: string;
+}
+interface ExternalConversationFinish {
+    content: string;
+    reasoning?: string;
+    finishReason: 'stop' | 'tool_calls' | 'length';
+}
+interface ExternalConversationTurn {
+    sessionId: string;
+    projectId: string;
+    onContentDelta(content: string): void;
+    onReasoningDelta(content: string): void;
+    onToolArgsDelta(name: string, content: string): void;
+    finish(result: ExternalConversationFinish): Promise<void>;
+    fail(error: unknown): Promise<void>;
+}
+
 /**
  * In-memory per-session progress telemetry. Counts the live signals the
  * chat layer already observes — streamed deltas, wire pulses, heartbeats,
@@ -8523,6 +9117,17 @@ interface TaskBudgetSnapshot {
     inputTokens: number;
 }
 
+/**
+ * The slice of `WorkspaceIndexManager` the reference parser needs. Narrowed
+ * to a structural type so the dependency stays one-way — the indexer already
+ * takes this manager, and importing its class here would close the loop.
+ */
+interface WorkspaceFileSource {
+    readFiles(projectId: string): Promise<Array<{
+        path: string;
+    }>>;
+}
+
 type TurnMessageOrigin = 'direct-user' | 'question-answer' | 'cross-gezel' | 'background-nudge' | 'system';
 interface GateScriptDiagnostic {
     scriptName: string;
@@ -8994,6 +9599,7 @@ declare class ChatManager {
     private readonly activeMemoryExtractions;
     private readonly store;
     private readonly events;
+    private readonly externalConversations;
     private readonly memory;
     private readonly historyManager?;
     private readonly catalog;
@@ -9065,6 +9671,22 @@ declare class ChatManager {
      */
     setContentIndex(index: ContentIndex): void;
     private contentIndexRef?;
+    /**
+     * Workspace file index, used to recognize workspace paths an assistant
+     * reply named in prose. Injected by `service.ts` after both exist (the
+     * indexer takes this manager as a dependency, so the wiring points both
+     * ways). When unset — unit tests, and any project the indexer has not
+     * reached — the reference parser sees artifacts only, which is exactly
+     * its pre-workspace behavior.
+     */
+    setWorkspaceIndex(index: WorkspaceFileSource): void;
+    private workspaceIndexRef?;
+    /**
+     * The project's indexed workspace paths. Reads the indexer's persisted
+     * listing rather than walking the tree — a turn must never pay for a
+     * recursive stat of a repo checkout just to linkify a filename.
+     */
+    private workspaceInventory;
     /**
      * Wire the Keurmeester supervision engine. Set by `service.ts` after
      * both exist (the KeurmeesterManager needs `oneShotCompletion`, so
@@ -9112,6 +9734,39 @@ declare class ChatManager {
      */
     private resolveEffectiveContextWindow;
     private resolveEffectiveSessionModel;
+    /** The on-device model store backing a local provider, when one is wired. */
+    private localModelStore;
+    /** Dead pins already repinned this process, keyed `provider\0deadModelId`. */
+    private readonly repinnedDeadDefaults;
+    /**
+     * Substitute an installed model for a local model id the engine cannot
+     * serve.
+     *
+     * A `config.defaultModel` pin can name weights that never landed — first-run
+     * pins the hardware recommendation *before* the download, so an abandoned
+     * multi-gigabyte fetch leaves the install pointing at a phantom model. The
+     * pooled-router path catches that with `ModelNotInstalledError`, but the
+     * machine-engine path forwards whatever string it is handed straight to the
+     * broker, which answers `model_not_loaded` on every turn including the
+     * background one-shots. Chat is then dead until someone edits config.json by
+     * hand, because the Settings picker that would fix it stays hidden while
+     * fewer than two models are installed.
+     *
+     * Deliberately additive: with nothing installed to fall back to, the id
+     * passes through unchanged so the existing downstream errors (and the
+     * first-run download banner) behave exactly as before. We only intervene
+     * when we have something strictly better to offer.
+     */
+    private ensureServableLocalModel;
+    /**
+     * Persist a substitution when the dead id was the install default, so the
+     * repair outlives the turn and Settings, the engine pill, and the session
+     * switcher stop disagreeing about which model is in play. A dead value that
+     * came from gezel frontmatter or a capability route is substituted for this
+     * turn but left in place — rewriting someone's explicit pin is a bigger
+     * decision than keeping chat alive.
+     */
+    private repinDeadDefaultModel;
     /**
      * List the chat models a paired server offers, namespaced for A
      * (`remote:<remoteId>/<model>`). Used by the model picker. Returns [] if the
@@ -9206,10 +9861,19 @@ declare class ChatManager {
         projectId: string;
         createdAt: string;
         title: string;
-        providerName: "remote" | "llama-cpp" | "mlx" | "copilot" | "openai" | "anthropic" | "anthropic-cli" | "codex-cli" | "ollama" | "ds4";
+        providerName: "mlx" | "ds4" | "llama-cpp" | "ollama" | "copilot" | "openai" | "anthropic" | "anthropic-cli" | "codex-cli" | "remote";
         lastActivityAt: string;
         taskRef?: string | undefined;
         stepId?: string | undefined;
+        source?: {
+            kind: "external";
+            appId: string;
+            appName: string;
+            externalConversationId: string;
+            readOnly: true;
+            workingDirectory?: string | undefined;
+            projectHint?: string | undefined;
+        } | undefined;
         model?: string | undefined;
         archived?: boolean | undefined;
         lastTurnError?: string | undefined;
@@ -9461,6 +10125,13 @@ declare class ChatManager {
      */
     interruptWithMessage(sessionId: string, userText: string): Promise<ChatMessage>;
     getSessionRecord(sessionId: string): Promise<ChatSession | null>;
+    /**
+     * Begin one request in a caller-owned conversation loop (Pi, OpenCode, or VS Code).
+     * The recorder reconciles the caller's authoritative transcript into a
+     * read-only Gezel session and returns live-event hooks for this response.
+     */
+    beginExternalConversation(input: BeginExternalConversationInput): Promise<ExternalConversationTurn>;
+    resolveExternalConversationId(input: ResolveExternalConversationInput): Promise<string>;
     /**
      * The set of tool names a session's active craftbook pre-authorizes
      * (its `autoAllow` toolsets' tools). The Claude-CLI permission broker
@@ -9489,11 +10160,10 @@ declare class ChatManager {
      * effort). Surfaced via `GET /api/sessions/:id/debug` and consumed
      * by the UI's debug-mode "copy debug bundle" button.
      *
-     * This re-runs `buildSessionOpts` rather than reading whatever was
-     * captured at session-creation time — the *current* prompt is what
-     * matters when an engineer is investigating "why did the model do
-     * X right now". Recent edits to the gezel's about, project context,
-     * or local-model-tuning rules show up immediately.
+     * Native sessions re-run `buildSessionOpts` because the *current* prompt
+     * matters when investigating "why did the model do X right now". External
+     * mirrors instead surface the latest captured caller-owned request; a native
+     * Gezel prompt reconstructed later is not execution evidence for that loop.
      *
      * `atMessageTimestamp`: when set (ISO string from `ChatMessage.at`),
      * slice messages whose `at <= atMessageTimestamp` so the bundle
@@ -9512,8 +10182,26 @@ declare class ChatManager {
      * test teardown (or a graceful process exit) races them.
      */
     trackBackground(promise: Promise<unknown>): void;
-    /** Await every currently-tracked background promise, then return. */
-    drainBackground(): Promise<void>;
+    /**
+     * Await every currently-tracked background promise, then return.
+     *
+     * Bounded, because every caller is a shutdown path and the work being
+     * awaited can legitimately take minutes. A first run creates the Meester
+     * and kicks off its about.md + icon generation; if the configured provider
+     * cannot answer — no credential, a cold cloud session — those one-shots sit
+     * on their own 120s budget while this loop waits. Unbounded, that stalls
+     * `service.stop()`, and neither the Electron quit coordinator nor an
+     * embedded caller imposes a deadline of its own, so the window simply hangs.
+     * Wild-caught as an intermittent 60s teardown timeout in
+     * `security-compliance.spec.ts` once its home stopped inheriting a
+     * machine-shared roster and started genuinely provisioning a Meester.
+     *
+     * Abandoning a task is safe here: these are fire-and-forget writes whose
+     * own error handling already runs independently of this await. The warning
+     * names the count so a real shutdown stall stays diagnosable instead of
+     * looking like a clean exit.
+     */
+    drainBackground(timeoutMs?: number): Promise<void>;
     createSession(args: {
         gezelId: string;
         projectId?: string;
@@ -10362,9 +11050,22 @@ declare class ChatManager {
      * Tear down cached sessions, tool bridges, and provider engines so the
      * next session picks up new config.
      *
-     * Default (hard) mode tears down everything immediately — correct for
-     * credential / provider / endpoint changes, where the old engine state
-     * is unusable and must go now.
+     * Default (hard) mode disconnects every session and disposes every tool
+     * bridge immediately — correct for credential / provider / endpoint /
+     * security-boundary changes, where the old session state and the old MCP
+     * children are unusable and must go now.
+     *
+     * What it does NOT do is kill resident local engines. A pooled engine is
+     * a model process keyed by (provider, modelId, replica): it carries no
+     * credentials and no tool surface, so no config change makes the *process*
+     * unsafe — only the sessions and bridges around it. `engines: 'force'`
+     * (service shutdown, emergency stop) force-evicts the pool without waiting
+     * for in-flight turns; the default `'release-idle'` frees every engine
+     * that is not mid-turn and leaves busy ones to the pool's ordinary
+     * LRU/idle lifecycle. Wild-caught: flipping the security posture in
+     * Settings force-killed both resident 27B models, and a background
+     * craftbook turn four minutes into its first step died with "the
+     * on-device engine dropped the connection", which reads as a crash.
      *
      * `deferBusy` mode is for pure model-preference changes (default chat
      * model, reasoning effort), where the only thing that needs to flow
@@ -10382,6 +11083,8 @@ declare class ChatManager {
     resetClient(opts?: {
         deferBusy?: boolean;
         restoreSeededProviders?: boolean;
+        /** See method doc. Defaults to `'release-idle'` — never severs a live turn. */
+        engines?: 'release-idle' | 'force';
     }): Promise<void>;
     /**
      * Stop admitting work and actively unwind every live turn while the HTTP
@@ -10481,6 +11184,8 @@ declare class ChatManager {
          * expansion) — those must keep today's plain-background behavior.
          */
         ambient?: boolean;
+        /** Override the background default for explicitly user-awaited utility work. */
+        lane?: Lane;
         /**
          * Live streaming hooks for callers that surface progress (the
          * transform dialog's metacommentary feed). `onDelta` is the
@@ -10568,6 +11273,12 @@ declare class ChatManager {
      * immediately). No-op when the session isn't mid-turn.
      */
     recordSessionIntent(scope: PublishScope, label: string): void;
+    /**
+     * External sessions never enter `states`, so the ordinary post-send memory
+     * hook cannot see them. Re-read their durable transcript and use the same
+     * cadence, ambient lane, cursor, and debounce policy as first-party chats.
+     */
+    private scheduleExternalMemoryExtraction;
     /**
      * Whether the post-turn memory extraction should fire now. The
      * cadence depends on how heavyweight the provider's one-shot path
@@ -10666,6 +11377,20 @@ declare class ChatManager {
      * a test seam) and is deliberately left alone.
      */
     private shutdownOwnedEngineRouter;
+    /**
+     * Free the memory a live reset can free without severing anything: evict
+     * every resident engine that is idle right now and leave the rest to the
+     * pool's ordinary lifecycle. The router itself stays — dropping it while an
+     * engine is still serving a turn would orphan that process outside the
+     * broker's accounting, which is the reason the old path force-killed
+     * everything instead.
+     *
+     * An explicitly injected {@link engineRouter} remains caller-owned and is
+     * left alone, same rule as {@link shutdownOwnedEngineRouter}. A router
+     * whose construction is still in flight owns no resident engines yet, so
+     * this deliberately does not await it.
+     */
+    private releaseIdleOwnedEngines;
     /**
      * Resolve (or build) the router. Returns `null` only when no local
      * provider is wired up at all (cloud-only installs); production
@@ -10892,8 +11617,17 @@ declare class ChatManager {
      * pool replica. This is the broker-side half of remote admission: focusing a
      * chat needs the live memory clamp so the user daemon can size its prompt,
      * but it must not load the model or evict somebody else's resident engine.
-     */
-    previewContextWindowForModel(name: LocalProviderName, modelId: string): Promise<number | undefined>;
+     *
+     * `standalone` is for callers writing the answer somewhere durable rather
+     * than spending it on one turn. Live pricing charges the model for whatever
+     * else happens to be resident, so a preview taken while another engine is
+     * warm collapses to the local context floor — fine for a decision
+     * made and discarded in the same second, wrong for a config file read back
+     * days later. See {@link previewLocalEnginePlan}'s `standalone` note.
+     */
+    previewContextWindowForModel(name: LocalProviderName, modelId: string, opts?: {
+        standalone?: boolean;
+    }): Promise<number | undefined>;
     /**
      * Reservations held by models OTHER than the one being previewed.
      *
@@ -11025,6 +11759,20 @@ declare class ChatManager {
      * could do — so the launch config, not the catalog tag, is the source.
      */
     private resolveTurnVisionContext;
+    /**
+     * Shared-library documents bearing on THIS message.
+     *
+     * The turn-1 recall snapshot is frozen for the session (per the KV-cache
+     * rationale on `record.recall`), so a topic that arrives later — "what's
+     * our refund policy" on turn eight — would otherwise reach the model with
+     * no retrieval at all. This runs on the user-message channel instead,
+     * where per-turn content belongs.
+     *
+     * Quiet by construction: real user turns only, a high score floor, and a
+     * per-session dedupe so the same document is offered once and then left
+     * alone. No hits means no prelude and no tokens.
+     */
+    private resolveTurnLibraryRecall;
     private resolveUserPromptPrelude;
     /**
      * Get or build the live state for a session. On first use after process
@@ -12073,6 +12821,23 @@ declare class GitManager {
     private withLock;
 }
 
+type QuotaReserveRule = 'overall' | 'per-day';
+/** Why one bucket failed the reserve check (provider attached by the gate). */
+interface QuotaReserveViolation {
+    /** Provider bucket id that tripped the reserve (e.g. "premium_interactions"). */
+    bucket: string;
+    /** Derived remaining, 0-100, one decimal. */
+    remainingPercent: number;
+    /** Effective floor that triggered the hold, 0-100, one decimal. */
+    floorPercent: number;
+    /** Which enabled rule produced the winning floor ('overall' on ties). */
+    rule: QuotaReserveRule;
+    resetDate?: string;
+}
+interface QuotaReserveHold extends QuotaReserveViolation {
+    provider: ProviderName;
+}
+
 /**
  * TaskRunner
  *
@@ -12157,8 +12922,12 @@ interface PendingHandoff {
      * activated during the day is filed as scheduled work immediately,
      * rather than counting as a backlog item for the up-to-one-tick window
      * before the first `tick` reads it back off disk.
+     *
+     * `'night-quota'` — the shift is ON but this handoff's resolved provider
+     * is inside the configured cloud quota reserve; re-checked every tick so
+     * a mid-window quota reset releases it.
      */
-    heldFor?: 'night-shift' | 'provider-busy';
+    heldFor?: 'night-shift' | 'night-quota' | 'provider-busy';
 }
 /** One side of the pending split — see {@link TaskRunner.snapshot}. */
 interface TaskHandoffBucket {
@@ -12262,6 +13031,13 @@ interface TaskRunnerOptions {
      * the engine. Defaults to never-active.
      */
     isIndexCatchUpActive?: () => boolean;
+    /**
+     * Quota-reserve verdict for a night handoff's resolved provider. A
+     * non-null hold keeps the handoff on the queue (`heldFor: 'night-quota'`)
+     * without touching in-flight turns — admission-only, like every other
+     * gate here. Defaults to always-allow.
+     */
+    nightQuotaHold?: (provider: ProviderName) => Promise<QuotaReserveHold | null>;
 }
 declare class TaskRunner {
     private readonly store;
@@ -12271,6 +13047,7 @@ declare class TaskRunner {
     private readonly isNightShiftActive;
     private readonly isNightShiftPending;
     private readonly isIndexCatchUpActive;
+    private readonly nightQuotaHold;
     private readonly pending;
     private readonly activeDispatches;
     private nextId;
@@ -12403,6 +13180,14 @@ declare class WorkspaceIndexManager {
     /** Per-project promise chain so two concurrent scans on the same
      *  project serialize rather than racing on the disk. */
     private readonly locks;
+    /**
+     * Parsed `files.json` per project, revalidated against the file's own
+     * mtime + size so it can never go stale. `files.json` runs to megabytes
+     * on a real checkout and its readers are all hot — terminal path
+     * autocomplete on every keystroke, the chat reference parser on every
+     * turn, the timeline backfill on every page.
+     */
+    private readonly filesCache;
     private startupTimer;
     private tickTimer;
     constructor(opts: WorkspaceIndexManagerOptions);
@@ -12440,7 +13225,7 @@ declare class WorkspaceIndexManager {
      * autocomplete. The index stores files only, so directories are derived:
      * each match collapses to its next path segment after the prefix — a
      * directory (trailing `/`, so the user can descend) or the full file path.
-     * Reads the cached file list (capped at ~500 by the indexer).
+     * Reads the cached file list (capped at 20,000 files by the indexer).
      * Case-insensitive prefix; deduped; capped.
      */
     searchWorkspaceFiles(projectId: string, prefix: string, limit?: number): Promise<string[]>;
@@ -12486,6 +13271,7 @@ declare class WorkspaceIndexManager {
     private readMetaFromDisk;
     private isStale;
     private mruIndex;
+    private isSharedLibrary;
     /**
      * Missing preserves the historical indexed-by-default behavior. Reads the
      * live project each time so toggling the setting takes effect without a
@@ -13085,6 +13871,7 @@ declare class IndexEnrichmentManager {
      * awaited) and then wakes the TaskRunner still gets the dispatch hold.
      */
     catchUpAll(): Promise<void>;
+    private isSharedLibrary;
     private runDrive;
     /** Exposed for tests: run one batch ignoring the timers (still idle-gated). */
     tick(): Promise<void>;
@@ -13104,17 +13891,11 @@ interface SessionSearchHit {
     lastActivityAt: string;
     archived: boolean;
 }
-interface DocumentSearchHit {
-    path: string;
-    lineStart: number;
-    snippet: string;
-}
 interface GlobalIndexStatus {
     available: boolean;
     sessions: number;
     history: number;
     historyBackfilledAt: string | null;
-    documents: number;
 }
 declare class GlobalIndex {
     private readonly home;
@@ -13130,7 +13911,6 @@ declare class GlobalIndex {
      * falls back to the JSONL scan.
      */
     searchHistory(filter?: HistoryFilter): Promise<HistoryEvent[] | null>;
-    searchDocuments(q: string, maxResults?: number): Promise<DocumentSearchHit[]>;
     status(): Promise<GlobalIndexStatus>;
 }
 
@@ -13151,44 +13931,6 @@ declare class IndexingJobControl {
     private noteAuthor;
 }
 
-interface ActivityTrackerOptions {
-    store: Store;
-    history: HistoryManager;
-    chatEvents: ChatEventBus;
-    now?: () => number;
-    persistThresholdMs?: number;
-}
-declare class ActivityTracker {
-    private readonly store;
-    private readonly history;
-    private readonly chatEvents;
-    private readonly now;
-    private readonly persistThresholdMs;
-    /** Newest observed stamp per project (ms epoch). */
-    private readonly latest;
-    /** Stamp last written to (or read from) disk per project. */
-    private readonly persisted;
-    /** Projects whose on-disk stamp has been loaded into `persisted`. */
-    private readonly loads;
-    private readonly writing;
-    private unsubs;
-    constructor(opts: ActivityTrackerOptions);
-    start(): void;
-    stop(): Promise<void>;
-    stamp(projectId: string, atMs: number): void;
-    /**
-     * Newest known activity for a project — max of the in-memory stamp
-     * and the on-disk one (loaded once). Null when the project has never
-     * been observed.
-     */
-    lastActivityAt(projectId: string): Promise<string | null>;
-    /** Persist every stamp that is newer than its on-disk value. */
-    flush(): Promise<void>;
-    private maybePersist;
-    private write;
-    private ensureLoaded;
-}
-
 type StatusOneShot = (prompt: string, timeoutMs: number, opts: {
     gezelId: string;
     jobLabel: string;
@@ -13439,6 +14181,26 @@ interface ChatModelInstallRegistries {
     mlx: MlxChatInstallRegistry;
 }
 
+interface OpenCodeSetupManager {
+    status(): Promise<OpenCodeSetupStatusResponse>;
+    configure(input: ConfigureOpenCodeRequest): Promise<OpenCodeSetupStatusResponse>;
+    installPlugin(input: InstallOpenCodePluginRequest): Promise<OpenCodeSetupStatusResponse>;
+    removePlugin(): Promise<OpenCodeSetupStatusResponse>;
+    remove(): Promise<OpenCodeSetupStatusResponse>;
+    reconcile(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+interface PiSetupManager {
+    status(): Promise<PiSetupStatusResponse>;
+    configure(input: ConfigurePiRequest): Promise<PiSetupStatusResponse>;
+    installExtension(input: InstallPiExtensionRequest): Promise<PiSetupStatusResponse>;
+    removeExtension(): Promise<PiSetupStatusResponse>;
+    remove(): Promise<PiSetupStatusResponse>;
+    reconcile(): Promise<void>;
+    stop(): Promise<void>;
+}
+
 /**
  * AudioProvider — service-side abstractions for speech-to-text (STT)
  * and text-to-speech (TTS).
@@ -14145,6 +14907,11 @@ interface InstalledVideoModelInfo {
     name: string;
     approxSizeBytes: number;
     installedAt: string;
+    /**
+     * True when the model lives in the read-only machine asset store, so
+     * `deleteModel` would refuse it and the UI must not offer Delete.
+     */
+    readOnly?: boolean;
 }
 /**
  * Multi-file pull progress. Mirrors `MlxInstallEvent` (video models are
@@ -14592,6 +15359,36 @@ declare class SearchService {
     private merge;
 }
 
+/**
+ * Tracks the one storage operation allowed to run at a time.
+ *
+ * Cleanup, backup, and restore all walk and rewrite the same directories, so
+ * running two at once means one job measuring or archiving a tree the other
+ * is deleting. The HTTP layer rejects a second start rather than trying to
+ * interleave them, matching how the folder-move worker guards itself.
+ */
+declare class StorageJobManager {
+    private readonly jobs;
+    create(kind: StorageJobKind, totals?: {
+        totalItems?: number;
+        totalBytes?: number;
+    }): StorageJob;
+    get(id: string): StorageJob | undefined;
+    hasActive(): boolean;
+    /**
+     * Ask the worker to stop at its next item boundary. Deletion is not undone
+     * — whatever already went is gone — so this bounds the damage rather than
+     * reversing it, and the job still reports what it freed.
+     */
+    requestCancel(id: string): boolean;
+    update(id: string, patch: Partial<StorageJob>): void;
+    setPhase(id: string, phase: StorageJobPhase, currentLabel?: string): void;
+    finish(id: string, outcome: {
+        error?: string;
+        cancelled?: boolean;
+    }): void;
+}
+
 /**
  * The pinned system-toolset list.
  *
@@ -14880,6 +15677,24 @@ interface NightShiftManagerOptions {
     intervalMs?: number;
     /** Clock override for tests. */
     now?: () => Date;
+    /** Quota-reserve verdicts (NightShiftQuotaGate); absent = never hold. */
+    quotaGate?: {
+        holdFor(provider: ProviderName): Promise<QuotaReserveHold | null>;
+    };
+    /**
+     * Night-aware provider resolution — the same `chat.providerForGezel`
+     * closure the runner's dispatcher uses, so classification here and
+     * admission there cannot disagree. Absent = the gate never applies.
+     */
+    resolveProviderName?: (gezelId: string, opts?: {
+        nightShift?: boolean;
+    }) => Promise<ProviderName>;
+}
+/** Why pending night work is parked, summarized for status surfaces. */
+interface NightShiftQuotaHoldStatus {
+    heldTaskCount: number;
+    /** One reason per affected provider. */
+    reasons: QuotaReserveHold[];
 }
 /**
  * Owns the Night Shift ON/OFF state. Lifecycle mirrors `TaskScheduler` /
@@ -14893,6 +15708,12 @@ interface NightShiftManagerOptions {
  *     pending night-shift tasks remain, then reverts to scheduled logic.
  *   - SCHEDULED: outside the window → off (latch cleared); window open but
  *     no pending work → latch off for the rest of THIS window; otherwise on.
+ *   - QUOTA-HELD: pending work whose resolved provider is inside the cloud
+ *     quota reserve doesn't keep a shift alive. All pending work held →
+ *     off WITHOUT latching (parked, not drained) so a mid-window quota
+ *     reset re-activates on a later tick; a manual request survives the
+ *     hold and resumes by itself. `quotaHoldStatus()` names the parked
+ *     state for the UI.
  *
  * Consumers read `isActive()` synchronously: `TaskRunner` (dispatch gating
  * + priority), `TaskScheduler` (cron-spawn gating), `IndexEnrichmentManager`
@@ -14904,10 +15725,14 @@ declare class NightShiftManager {
     private readonly events;
     private readonly intervalMs;
     private readonly now;
+    private readonly quotaGate?;
+    private readonly resolveProviderName?;
     private timer;
     private ticking;
     private active;
     private src;
+    /** When the running shift began; null while nothing is running. */
+    private startedAt;
     /** Window key we've drained-and-latched off for; cleared next window. */
     private latchedOffForWindowKey;
     /** Whether a manual ("go to lunch") shift has been requested. */
@@ -14920,11 +15745,44 @@ declare class NightShiftManager {
     private enabled;
     /** Window config from the last tick — drives the synchronous day-key. */
     private window;
+    /** Quota-reserve hold summary from the last tick; null when nothing is held. */
+    private quotaHold;
+    /** Refs of pending night tasks the quota reserve is holding, per last tick. */
+    private quotaHeldRefs;
     constructor(opts: NightShiftManagerOptions);
     start(): void;
     stop(): void;
     isActive(): boolean;
     source(): NightShiftSource;
+    /**
+     * When the running shift began, or null when nothing is running. This is
+     * the ON edge, not the window's opening hour: a scheduled shift starts on
+     * the tick that turned it on, which is later than `startHour` whenever the
+     * machine was asleep or the work only arrived mid-window. A shift that
+     * changes source mid-run (a scheduled window taking over from a manual
+     * one) keeps its original start — it never stopped running.
+     */
+    startedAtIso(): string | null;
+    /**
+     * The scheduled window status surfaces name: the one open right now, else
+     * the next one due. Null while the feature is switched off — nothing is
+     * scheduled, so there is no window to name. Uses the window config cached
+     * from the last tick.
+     */
+    windowBounds(): {
+        start: string;
+        end: string;
+        open: boolean;
+    } | null;
+    /**
+     * Why pending night work is parked by the cloud quota reserve, as of the
+     * last tick — null when nothing is held. Non-null both while the shift
+     * runs with a subset held (mixed providers) and while it sits fully
+     * parked (active=false, no latch) waiting for a quota window to reset.
+     */
+    quotaHoldStatus(): NightShiftQuotaHoldStatus | null;
+    /** Refs of the pending night tasks currently held by the quota reserve. */
+    quotaHeldTaskRefs(): ReadonlySet<string>;
     /**
      * Whether the configured nightly window is open right now — used by the
      * scheduler to confine a night-shift cron host's spawning to the window
@@ -14995,8 +15853,15 @@ declare class NightShiftManager {
      * exposes the same set for the UI's "what's the shift doing?" panel.
      */
     listPendingTasks(): Promise<Task[]>;
-    /** True if any active night-shift task still has work to do `todayKey`. */
-    private hasPendingNightShiftTasks;
+    /**
+     * Partition pending night tasks into dispatchable vs quota-held using
+     * the same provider resolution the runner's dispatcher applies (night
+     * override included). Optimistic on every failure path: a task whose
+     * owner or provider can't resolve counts dispatchable — the runner
+     * drops it later, and counting it held would wrongly deactivate the
+     * shift. Verdicts are memoized per provider per pass.
+     */
+    private classifyPending;
     /** Active night-shift tasks pending `todayKey`, in `manager.list` order. */
     private pendingNightShiftTasks;
     /** Single transition chokepoint: diff, broadcast, log. */
@@ -15509,6 +16374,14 @@ declare class TerminalManager {
     private collectListingFileReferences;
 }
 
+interface VSCodeSetupManager {
+    status(): Promise<VSCodeSetupStatusResponse>;
+    configure(input: ConfigureVSCodeRequest): Promise<VSCodeSetupStatusResponse>;
+    remove(): Promise<VSCodeSetupStatusResponse>;
+    reconcile(): Promise<void>;
+    stop(): Promise<void>;
+}
+
 interface OllamaEmulationStatus {
     listening: boolean;
     port?: number;
@@ -15550,6 +16423,12 @@ interface ServiceContext {
      * manual run.
      */
     meesterStatus: MeesterStatusGenerator;
+    /**
+     * The meester's ambient dashboard (PNG workshop snapshots under
+     * `~/.gezel/ambient/`). In context so `/api/ambient-dashboard` can
+     * report status and kick manual runs.
+     */
+    ambientDashboard: AmbientDashboardGenerator;
     scriptRunner: ScriptRunner;
     catalog: CatalogService;
     /**
@@ -15713,6 +16592,12 @@ interface ServiceContext {
     ollamaEmulation: OllamaEmulationController;
     /** Gezel-owned Codex profile, credential, and loopback bridge lifecycle. */
     codexSetup: CodexSetupManager;
+    /** Gezel-owned OpenCode config, credential, and loopback bridge lifecycle. */
+    opencodeSetup: OpenCodeSetupManager;
+    /** Gezel-owned pi extension, model list, credential, and loopback bridge lifecycle. */
+    piSetup: PiSetupManager;
+    /** VS Code custom endpoint, scoped credential, profile merge, and bridge lifecycle. */
+    vscodeSetup: VSCodeSetupManager;
     /**
      * Hex SHA-256 of the daemon's current TLS cert DER, when serving HTTPS.
      * `/v1/identity` signs this with the device identity key so a paired client
@@ -15743,6 +16628,13 @@ interface ServiceContext {
      *  (the worker writes a sentinel file so the next boot can detect a
      *  crashed mid-move). */
     folderJobs: JobManager;
+    /** In-memory tracker for the one storage cleanup/backup/restore job that
+     *  may run at a time. Same lifetime as `folderJobs`, and mutually
+     *  exclusive with it — both rewrite the same directories. */
+    storageJobs: StorageJobManager;
+    /** Drop the cached model inventory after cleanup deletes model files, so
+     *  listings stop advertising models that are no longer on disk. */
+    invalidateModelsCache?: (provider?: ProviderName) => void;
     /** Background workspace indexer: commands + files + token index. */
     workspaceIndex: WorkspaceIndexManager;
     /** Content index (code/doc intelligence) backing the code-intel MCP tools. */
@@ -15847,6 +16739,16 @@ interface StartServiceOptions {
     codexHome?: string;
     /** Exact Codex bridge port override (`0` = ephemeral); production derives one from `home`. */
     codexBridgePort?: number;
+    /** Exact OpenCode bridge port override (`0` = ephemeral); production derives one from `home`. */
+    opencodeBridgePort?: number;
+    /** Override pi's fixed loopback bridge port. Tests bind ephemeral ports. */
+    piBridgePort?: number;
+    /** Override pi's own agent directory. Tests must never write to a real one. */
+    piAgentDir?: string;
+    /** Override VS Code's fixed loopback bridge port. Tests bind ephemeral ports. */
+    vscodeBridgePort?: number;
+    /** Override VS Code's User/profile directory. Tests must never write to a real one. */
+    vscodeUserDir?: string;
 }
 interface RunningService {
     context: ServiceContext;