@bendyline/gezel-service 0.1.0 → 1.0.1

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, 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, 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 { 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 { ServerType } from '@hono/node-server';
 import { CatalogService } from '@bendyline/gezel-catalog';
 import { ExternalFolders } from '@bendyline/gezel/paths';
@@ -287,8 +287,39 @@ interface ProjectFindingLifecycleEntry {
     resolvedAt?: string;
 }
 type ProjectFindingLifecycle = Record<string, ProjectFindingLifecycleEntry>;
+interface ProjectBoekwachterIssueRecord extends FileReviewIssue {
+    id: string;
+    ref: string;
+    fingerprint: string;
+    path: string;
+    status: BoekwachterIssueStatus;
+    taskRef?: string;
+    dismissalReason?: BoekwachterIssueDismissalReason;
+    createdAt: string;
+    lastSeenAt: string;
+    lastSeenContentHash: string;
+    lastCheckedAt?: string;
+    lastCheckedContentHash?: string;
+    seenAt?: string;
+    resolvedAt?: string;
+    dismissedAt?: string;
+}
+interface BoekwachterReviewObservation {
+    path: string;
+    contentHash: string;
+    issues: FileReviewIssue[];
+}
 interface StoreOptions {
     home: string;
+    /**
+     * Whether `home` is private to one OS user. On Unix these homes are created
+     * and repaired as 0700 so ordinary 0644 state files remain unreachable to
+     * other local accounts. System/machine homes must opt out because their
+     * installer-managed runtime discovery is intentionally shared.
+     *
+     * Defaults to true. Production system-scope stores opt out explicitly.
+     */
+    privateUserHome?: boolean;
     /**
      * Optional history recorder. When set, the Store emits audit events after
      * successful writes (create/rename/update/delete for gezels + projects +
@@ -348,6 +379,8 @@ declare class Store {
     private readonly external?;
     /** True for a `machine-engine` broker: engines and models, no product state. */
     private readonly engineOnly;
+    /** Whether the Store owns a home private to the current OS account. */
+    private readonly privateUserHome;
     private readonly poppetjes;
     private readonly documents;
     private readonly artifacts;
@@ -355,6 +388,7 @@ declare class Store {
     private readonly taskFiles;
     private projectCreationTail;
     private readonly findingLifecycleLocks;
+    private readonly boekwachterIssueLocks;
     /**
      * Notified after every session persist/delete — the single choke point all
      * ChatManager write paths funnel through, so a subscriber sees every
@@ -835,7 +869,31 @@ declare class Store {
     settleProjectFindingsForTask(id: string, taskRef: string, outcome: 'complete' | 'canceled'): Promise<number>;
     /** Remove lifecycle rows after a completed scan proves a finding is gone. */
     reconcileProjectFindingLifecycle(id: string, liveFingerprints: Set<string>): Promise<void>;
+    /**
+     * Materialize current review output into durable BW records. Review rows are
+     * disposable and content-hash keyed; these records intentionally are not.
+     */
+    observeProjectBoekwachterReviews(id: string, observations: readonly BoekwachterReviewObservation[]): Promise<void>;
+    listProjectBoekwachterIssues(id: string): Promise<ProjectBoekwachterIssueRecord[]>;
+    getProjectBoekwachterIssue(id: string, ref: string): Promise<ProjectBoekwachterIssueRecord | null>;
+    updateProjectBoekwachterIssue(id: string, ref: string, patch: {
+        status?: BoekwachterIssueStatus;
+        seen?: boolean;
+        taskRef?: string;
+        dismissalReason?: BoekwachterIssueDismissalReason;
+    }): Promise<ProjectBoekwachterIssueRecord | null>;
+    settleProjectBoekwachterIssuesForTask(id: string, taskRef: string, outcome: 'complete' | 'canceled'): Promise<number>;
+    private readProjectBoekwachterIssuesFile;
+    private writeProjectBoekwachterIssuesFile;
+    private withBoekwachterIssueLock;
     private withFindingLifecycleLock;
+    /**
+     * Persist project metadata through one compatibility boundary. Any write to
+     * a legacy project transparently replaces `allowGezelWrites` with the named
+     * managed-write policy, so old input remains readable without letting the
+     * deprecated field spread through newly written project files.
+     */
+    private writeProjectMeta;
     touchProject(id: string): Promise<void>;
     /**
      * A project `workingDir` is settable by the model (via `update_project`)
@@ -869,8 +927,11 @@ declare class Store {
         } | null;
         /** External-data connector bindings — `null` clears them. */
         connectors?: _bendyline_gezel.ProjectConnectorBinding[] | null;
+        managedWorkspaceWritePolicy?: ProjectManagedWorkspaceWritePolicy;
+        /** @deprecated Compatibility input; translated into the named policy. */
         allowGezelWrites?: boolean;
         codexPermissionMode?: _bendyline_gezel.CodexPermissionMode;
+        claudePermissionMode?: _bendyline_gezel.ClaudePermissionMode;
         /** Replaces the stored per-project ambient nudge override. */
         nudgeConfig?: ProjectNudgeConfig;
         /** Replaces the optional project-tab visibility overrides. */
@@ -1179,13 +1240,13 @@ declare class Store {
     /**
      * Gate mutations. Uses the same {@link resolveWorkspaceDir} as the
      * read path, then applies the per-project writability contract
-     * (`projectWorkspaceWritable` in core):
+     * (`projectManagedWorkspaceWritable` in core):
      *
      *   - `internal` / `githubCheckout`: writable unless the project
-     *     explicitly set `allowGezelWrites: false` (the per-project
+     *     explicitly set the managed-write policy to `deny` (the per-project
      *     "edits off" switch — gezel-initiated writes only; app-internal
      *     `.gezel` bookkeeping and user-initiated writes stay exempt).
-     *   - `workingDir`: writable iff `allowGezelWrites === true`. The
+     *   - `workingDir`: writable iff the managed-write policy is `allow`. The
      *     user has to explicitly opt gezels into mutating their own folder.
      *
      * The global security policy deliberately does not factor in — the
@@ -1208,7 +1269,7 @@ declare class Store {
         external: boolean;
     } | {
         ok: false;
-        reason: 'missing-flag-external' | 'disabled-by-project';
+        reason: 'external-consent-required' | 'disabled-by-project';
         workingDir: string;
     }>;
     statProjectWorkspacePath(id: string, filePath: string): Promise<{
@@ -2589,10 +2650,18 @@ interface ProviderUsage {
     quotaBuckets: QuotaBucket[];
     todayTurns: number;
     todayTokensIn: number;
+    /**
+     * Portion of `todayTokensIn` the provider reported as prompt-cache reads.
+     * Zero both when nothing was cached and when the provider reports no
+     * breakdown (e.g. Copilot) — absence of data and absence of hits are
+     * indistinguishable here, so render 0 as "no cache info", not "0% hit".
+     */
+    todayTokensCached: number;
     todayTokensOut: number;
     todayCost: number;
     totalTurns: number;
     totalTokensIn: number;
+    totalTokensCached: number;
     totalTokensOut: number;
     totalCost: number;
     /**
@@ -2844,7 +2913,7 @@ declare class ProviderQueue {
     private readonly affinityWindowMs;
     private readonly maxWaitMs;
     /** See {@link ProviderQueueOptions.ambientQuietMs}. 0 = gate off. */
-    private readonly ambientQuietMs;
+    readonly ambientQuietMs: number;
     /**
      * Last time NON-ambient work touched this queue (enqueue, dispatch,
      * or release — any lane). Initialized to construction time so a
@@ -4853,18 +4922,36 @@ declare class ModelFitnessManager {
 }
 
 /**
- * Per-file semantic enrichment (the boekwachter's unit of work): produce an
- * optional one-paragraph summary via a local LLM, build embeddable chunks, and
- * store their vectors. Embeddings run locally (transformers.js) and are the
- * always-on part; the LLM summary is best-effort (skipped when no local model
- * is configured). Hash-gated by the caller via `filesNeedingEnrichment`.
- *
- * Deps are injected so this is unit-testable without a real model:
- *   - `summarize(prompt)` → summary text, or '' to skip (e.g. no LLM)
- *   - `embed(texts)`      → one vector per text
+ * Who produced an LLM-written index row. Output-only bookkeeping — never an
+ * input to model routing. Absent fields stay NULL (rows written before the
+ * v10 migration, or deps built without a boekwachter) and renderers degrade
+ * to whatever segments exist.
  */
+interface IndexProvenance {
+    provider?: string;
+    gezelId?: string;
+    gezelName?: string;
+    appVersion?: string;
+}
+
+interface AiShadowProducers {
+    /** Absolute image path → markdown body (description + OCR), null when unavailable. */
+    describeImage?: (absPath: string) => Promise<{
+        body: string;
+        model?: string;
+    } | null>;
+    /** Absolute audio path → markdown transcript body, null when unavailable. */
+    transcribeAudio?: (absPath: string) => Promise<{
+        body: string;
+        model?: string;
+    } | null>;
+}
+interface AiShadowDeps extends AiShadowProducers {
+    provenance?: IndexProvenance;
+}
+
 interface EnrichDeps {
-    summarize: (prompt: string) => Promise<string>;
+    summarize: (prompt: string) => Promise<EnrichCompletionResult>;
     embed: (texts: string[]) => Promise<number[][]>;
     model?: string;
     /**
@@ -4873,14 +4960,50 @@ interface EnrichDeps {
      * output tokens than a 2-3 sentence summary. Absent when no local model is
      * configured; the review pass skips entirely then.
      */
-    review?: (prompt: string) => Promise<string>;
+    review?: (prompt: string) => Promise<EnrichCompletionResult>;
+    /**
+     * Default/primary attribution for legacy bare-string completions and
+     * non-completion work. Runtime completions carry their own actual target so
+     * a fallback can override this per result. Output-only, never a routing
+     * input.
+     */
+    provenance?: IndexProvenance;
+    /**
+     * Live concurrent-one-shot width of the resolved target's queue. Full
+     * drives dispatch this many per-file scans at once instead of one; the
+     * value is re-read as slots free because a lazily-initialized provider
+     * reports 1 until its first call spins it up.
+     */
+    oneShotWidth?: () => number;
 }
+/**
+ * One LLM completion plus the identity that actually produced it. Hand-built
+ * deps may still return a bare string; consumers resolve those through the
+ * deps-level defaults for backwards compatibility. Runtime deps always return
+ * this richer shape so a policy fallback cannot inherit the primary target's
+ * provenance.
+ */
+interface EnrichCompletion {
+    text: string;
+    model: string;
+    provenance?: IndexProvenance;
+}
+type EnrichCompletionResult = string | EnrichCompletion;
 
 interface AreaPassResult {
     areasUpdated: number;
     architectureUpdated: boolean;
 }
 
+interface ArtifactsIndexStats {
+    /** Markdown records the walk saw (post-skip rules). */
+    files: number;
+    /** Records whose content was (re)ingested this pass. */
+    indexed: number;
+    /** Rows pruned because their record vanished. */
+    removed: number;
+}
+
 interface ContentIndexStats {
     scanned: number;
     changed: number;
@@ -4897,13 +5020,39 @@ interface ResolvedRubric {
     source: 'builtin' | 'override';
 }
 
+/**
+ * Pool options for the AI passes. `concurrency` is the live width of the
+ * summarizer target's queue (full drives pass it; background stays serial).
+ * `drain` switches a call from "one fixed batch" to "run to empty": the
+ * work-list is re-queried as slots open so the pool never sits idle at a
+ * batch tail. `shouldStop` (the indexing job's pause switch) is checked and
+ * `onProgress` fired at each refill — the same cadence the caller's old
+ * per-batch loop provided.
+ */
+interface EnrichDriveOpts {
+    concurrency?: () => number;
+    drain?: {
+        shouldStop?: () => Promise<boolean> | boolean;
+        onProgress?: (progress: {
+            files: number;
+        }) => void;
+    };
+}
 declare class ContentIndex {
     private readonly store;
     private readonly home;
     /** Per-project village-file stores (they cache last-written content so
      *  no-change builds skip touching the user's repo). */
     private readonly cityStores;
-    constructor(store: Store, home: string);
+    /** Debounce window for {@link refreshArtifacts}; tests shrink it. */
+    private readonly artifactsDebounceMs;
+    /** Per-project pending artifacts pass — calls within the window join it. */
+    private readonly artifactsRefreshPending;
+    /** Per-project settle of the last dispatched pass, so passes never overlap. */
+    private readonly artifactsRefreshLast;
+    constructor(store: Store, home: string, opts?: {
+        artifactsDebounceMs?: number;
+    });
     private cityStoreFor;
     /** Bring the project's content index up to date. Called by the indexer tick. */
     refresh(projectId: string): Promise<ContentIndexStats | null>;
@@ -4974,13 +5123,26 @@ declare class ContentIndex {
         summarized: number;
         embedded: number;
         pending: number;
+        skipped: number;
+        shadowsPending: number;
         embedModel?: string;
     } | null>;
-    enrich(projectId: string, deps: EnrichDeps, limit?: number): Promise<{
+    enrich(projectId: string, deps: EnrichDeps, limit?: number, opts?: EnrichDriveOpts): Promise<{
         files: number;
         summarized: number;
         embedded: number;
     } | null>;
+    /**
+     * Run one batch of the AI-shadow tier: describe images / transcribe audio
+     * into `artifacts/shadow/` sidecars. Runs BEFORE the summary tier so a
+     * produced shadow immediately joins the enrichment work-list. No-op when
+     * neither producer is wired (no vision model / no STT configured).
+     */
+    aiShadows(projectId: string, deps: AiShadowDeps, limit?: number): Promise<{
+        files: number;
+        produced: number;
+        called: number;
+    } | null>;
     /**
      * Cheap existence probe — true when a content index db is on disk for
      * this project. File-stat only; never opens (an open would CREATE the
@@ -5008,7 +5170,7 @@ declare class ContentIndex {
      * whole night budget in timeouts). Rubrics can be injected (one resolve per
      * manager tick; also the test seam). Null when no index exists.
      */
-    review(projectId: string, deps: EnrichDeps, limit?: number, rubrics?: Map<string, ResolvedRubric>): Promise<{
+    review(projectId: string, deps: EnrichDeps, limit?: number, rubrics?: Map<string, ResolvedRubric>, opts?: EnrichDriveOpts): Promise<{
         files: number;
         reviewed: number;
     } | null>;
@@ -5023,8 +5185,41 @@ declare class ContentIndex {
     fileReview(projectId: string, relPath: string): Promise<FileReviewResponse>;
     /** Flat issue query across current-hash reviews (`list_file_issues` tool). */
     listFileIssues(projectId: string, req: ListFileIssuesRequest): Promise<ListFileIssuesResponse>;
+    getBoekwachterIssue(projectId: string, ref: string): Promise<BoekwachterIssue | null>;
+    updateBoekwachterIssue(projectId: string, ref: string, patch: {
+        status?: BoekwachterIssueStatus;
+        seen?: boolean;
+        taskRef?: string;
+        dismissalReason?: BoekwachterIssueDismissalReason;
+    }): Promise<BoekwachterIssue | null>;
+    settleBoekwachterIssuesForTask(projectId: string, taskRef: string, outcome: 'complete' | 'canceled'): Promise<number>;
+    private boekwachterIssuesForPath;
     searchDocs(projectId: string, query: string, maxResults?: number): Promise<SearchDocsResponse>;
     readDocAsMarkdown(projectId: string, relPath: string): Promise<ReadDocAsMarkdownResponse>;
+    /**
+     * Schedule a rebuild of the project's artifacts-corpus index. Debounced per
+     * project: calls landing within the window join the same pass, so a burst
+     * of connector syncs costs one walk; passes for a project never overlap.
+     * This is the only artifacts-index method that CREATES the database.
+     */
+    refreshArtifacts(projectId: string): Promise<ArtifactsIndexStats | null>;
+    /** Docs-FTS over the project's artifacts corpora. Empty until a refresh has built the index. */
+    searchArtifacts(projectId: string, query: string, maxResults?: number): Promise<{
+        results: Array<{
+            path: string;
+            lineStart: number;
+            snippet: string;
+        }>;
+        truncated: boolean;
+    }>;
+    /** Indexed artifact record paths (artifacts-relative), for the search catalog. */
+    listArtifactIndexFiles(projectId: string, cap?: number): Promise<string[]>;
+    /**
+     * Open the artifacts-corpus collection for a READ. Stat-first — opening a
+     * missing db would create it (same discipline as {@link hasIndex}), so pure
+     * reads return null until {@link refreshArtifacts} has built one.
+     */
+    private openArtifacts;
     searchImages(projectId: string, query: string, maxResults?: number): Promise<SearchImagesResponse>;
     findSimilarImages(projectId: string, relPath: string, maxResults?: number): Promise<FindSimilarImagesResponse>;
     describeFolder(projectId: string, prefix?: string): Promise<DescribeFolderResponse>;
@@ -7378,6 +7573,17 @@ interface IncompleteModelDownload {
      *  stray files left without one). */
     hasPartial: boolean;
 }
+/** Inventory row for a model directory whose manifest exists but is not
+ * loadable by the current engine manager. */
+interface UnrecognizedModelInfo {
+    id: string;
+    name?: string;
+    bytes: number;
+    updatedAt: string;
+    reason: string;
+    canUpdate: boolean;
+    readOnly?: boolean;
+}
 /**
  * An incomplete download enriched with per-engine catalog context. Managers
  * return this from `listIncomplete()`; the route serializes it as-is.
@@ -7585,6 +7791,9 @@ declare class MlxModelManager {
      * In-flight installs are excluded. See {@link LlamaCppModelManager.listIncomplete}.
      */
     listIncomplete(): Promise<IncompleteModelDownloadInfo[]>;
+    /** Management-only inventory for MLX directories whose manifest exists
+     * but no longer matches the current installed-manifest contract. */
+    listUnrecognized(): Promise<UnrecognizedModelInfo[]>;
     resolveDefaultModel(): Promise<InstalledMlxModel | null>;
     resolveDefaultModelPath(): Promise<string | null>;
     resolveModel(id: string): Promise<InstalledMlxModel | null>;
@@ -8010,6 +8219,15 @@ declare class LlamaCppModelManager {
      * delete-only for stale ids. In-flight installs are excluded.
      */
     listIncomplete(): Promise<IncompleteModelDownloadInfo[]>;
+    /**
+     * Model directories that do have a manifest, but whose metadata cannot be
+     * loaded by this build. These used to disappear from every inventory
+     * surface: `listInstalled()` correctly refused to run them, while the
+     * incomplete-download scan correctly ignored anything with a manifest.
+     * Keep that safety boundary, but return a management-only row so Settings
+     * can update a known catalog id or explicitly remove the held bytes.
+     */
+    listUnrecognized(): Promise<UnrecognizedModelInfo[]>;
     /**
      * Path of the first installed model, or null when none exist. Phase 2
      * uses this to pick a default `--model` arg for the supervised
@@ -9289,6 +9507,12 @@ declare class ChatManager {
         projectId?: string;
         expectedDeliverable?: ExpectedDeliverable;
     }): Promise<ChatSession>;
+    /**
+     * Resolve the active session for one exact task step. Scheduler re-drives
+     * use this path so task tools inherit GEZEL_TASK_REF / GEZEL_STEP_ID and
+     * continue the original work thread instead of landing in lobby chat.
+     */
+    private ensureOrCreateTaskSession;
     /** Late-bind the fitness manager (see the field's docblock). */
     setModelFitness(manager: ModelFitnessManager): void;
     /**
@@ -9388,7 +9612,8 @@ declare class ChatManager {
      * (which is anchored to a task + phase and always opens a fresh session),
      * `messageGezel` drops a message into the target gezel's *active* project
      * session via `ensureOrCreateSession`, so the continuity of their thread
-     * is preserved.
+     * is preserved. Internal task re-drives may also pass `taskRef` + `stepId`
+     * to resume that exact task-step session with its MCP context intact.
      *
      * When the target's turn completes, its reply is injected back into the
      * sender's session as its own handoff-styled message (role=user, `from`
@@ -9408,6 +9633,10 @@ declare class ChatManager {
         toGezelIdOrName: string;
         projectId?: string;
         text: string;
+        /** Internal task context for scheduler re-drives. */
+        taskRef?: string;
+        /** Exact step paired with taskRef when re-driving task work. */
+        stepId?: string;
         /**
          * Provider-queue lane for the target's reply turn. Defaults to
          * `interactive`. The scheduler passes `background` for ambient
@@ -10170,6 +10399,15 @@ declare class ChatManager {
          * "memory extraction".
          */
         jobLabel?: string;
+        /**
+         * Per-call catalog tuning profile. Used by tightly-scoped utility work
+         * whose inference shape differs from the owning gezel's conversational
+         * default (for example, index summaries should use an `instruct`
+         * profile rather than spend their deadline on hidden reasoning).
+         * The profile keeps its catalog-authored sampling/output allowance;
+         * this option does not impose an extra token cap.
+         */
+        tuningProfileId?: string;
         /**
          * Truly-deferrable housekeeping (memory extraction, icon/about
          * generation, index enrichment, digests). On local engine queues
@@ -10229,6 +10467,15 @@ declare class ChatManager {
     }): Promise<ProviderName>;
     /** Return the provider if it has already been initialized; never creates one. */
     getProviderIfReady(name: ProviderName): LLMProvider | null;
+    /**
+     * Concurrent one-shot width for a provider: its queue's configured
+     * concurrency once initialized (singleton or pooled local engine), else 1.
+     * Bulk callers (index drives) dispatch width-many one-shots to keep the
+     * queue full — the queue still arbitrates its interactive/background lanes.
+     * Live value: an uninitialized provider reports 1 and widens after the
+     * first call spins it up, so callers should re-read between dispatches.
+     */
+    oneShotQueueWidth(name: ProviderName): number;
     /**
      * Snapshot of the Claude CLI worker pool, enriched with gezel + project
      * display names so the UI pill can render "Maya · Atari Adventure
@@ -10622,6 +10869,14 @@ declare class ChatManager {
      */
     opts?: {
         allowUninstalled?: boolean;
+        /**
+         * Price the model as the only resident engine. Inventory/catalog rows
+         * answer "can this model run on this device?", so their estimate must
+         * not change merely because another model happens to be warm. Actual
+         * launch admission keeps the default live-reservation behavior and may
+         * evict an idle model (or report that a busy one is blocking the swap).
+         */
+        standalone?: boolean;
     }): Promise<{
         contextWindow?: number;
         plannedResidentBytes?: number;
@@ -10717,6 +10972,8 @@ declare class ChatManager {
     private immediateFileWriteConstraintActive;
     /** Resolve the mode that a Codex CLI session will actually receive. */
     private resolveCodexPermissionMode;
+    /** Resolve the mode that a Claude CLI session will actually receive. */
+    private resolveClaudePermissionMode;
     /**
      * D4 clamp-lifetime derivation for the rebuild check: read the
      * session's active step (step-scoped sessions only) and combine with
@@ -11125,7 +11382,7 @@ declare class ConnectorManager {
         code: string;
     }): Promise<ProjectConnectorBinding>;
     private gcPendingOAuth;
-    /** Remove a binding + its stored credential. */
+    /** Remove a binding + its stored credential (and its origin allowlist entry). */
     unbind(project: ProjectDetail, bindingId: string): Promise<void>;
     status(project: ProjectDetail): Promise<ConnectorStatus>;
     /**
@@ -11139,6 +11396,13 @@ declare class ConnectorManager {
     }): Promise<BindingSyncResult>;
     /** Sync every enabled binding on a project (drives the sync manager). */
     syncProject(project: ProjectDetail): Promise<BindingSyncResult[]>;
+    /**
+     * Idempotent sync-time heal for the origin allowlist: bindings created
+     * before their type declared `allowedOrigins` (or before this write path
+     * existed) get the entry on their next sync, with no migration step.
+     * Called under the project lock.
+     */
+    private ensureDeclaredOrigins;
     /** The per-binding sync body — always called under the project lock. */
     private syncBindingInner;
     /**
@@ -11924,6 +12188,13 @@ interface TaskRunnerOptions {
      * to "always pending" (only the active-shift gate applies).
      */
     isNightShiftPending?: (task: Task) => boolean;
+    /**
+     * True while the night-shift index catch-up sweep runs. Night-shift
+     * handoffs stay held on the queue until it finishes, so batch work starts
+     * against a current static + AI index instead of racing the indexer for
+     * the engine. Defaults to never-active.
+     */
+    isIndexCatchUpActive?: () => boolean;
 }
 declare class TaskRunner {
     private readonly store;
@@ -11932,6 +12203,7 @@ declare class TaskRunner {
     private readonly now;
     private readonly isNightShiftActive;
     private readonly isNightShiftPending;
+    private readonly isIndexCatchUpActive;
     private readonly pending;
     private readonly activeDispatches;
     private nextId;
@@ -12108,6 +12380,13 @@ declare class WorkspaceIndexManager {
      *   - on-mount of the Commands panel when status is `never`
      */
     refresh(projectId: string): Promise<WorkspaceIndexStatus>;
+    /**
+     * Like {@link refresh}, but awaits the whole scan (structural pass + the
+     * content-index refresh it drives). For callers that sequence work on a
+     * CURRENT index — the on-demand enrichment drive and the night-shift
+     * catch-up must not summarize/review against yesterday's file list.
+     */
+    refreshAndWait(projectId: string): Promise<WorkspaceIndexStatus>;
     /**
      * Periodic tick: pick the highest-priority stale project and index
      * exactly one. One project per tick keeps the loop bounded; with a
@@ -12599,6 +12878,39 @@ interface IndexEnrichmentManagerOptions {
     events?: Pick<ChatEventBus, 'publishGlobalEvent'>;
     /** Test seam; production resolves the role from each project's roster. */
     resolveBoekwachter?: (projectId: string) => Promise<GezelDetail | null>;
+    /**
+     * AI-shadow producers (vision describe / STT transcribe). Absent when the
+     * install has neither capability; the shadow tier is skipped entirely then.
+     */
+    shadowProducers?: AiShadowProducers;
+    /** Audit log for the once-per-wave `project.index.reviewed` drain event. */
+    history?: {
+        log: (event: Omit<HistoryEvent, 'id' | 'at'> & {
+            at?: string;
+            id?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Awaitable structural refresh (WorkspaceIndexManager.refreshAndWait) run
+     * at the head of every drive so the AI tiers see current files. When
+     * absent (tests), the drive falls back to `contentIndex.refresh` directly.
+     */
+    refreshStatic?: (projectId: string) => Promise<unknown>;
+}
+/**
+ * On-demand drive intensity:
+ *   - `background` — start now (skip the idle wait) but stay polite: ambient
+ *     one-shots that the local engine holds behind live chat, day-size
+ *     batches.
+ *   - `full` — occupy the engine: non-ambient one-shots that compete like any
+ *     interactive work, night-size batches, run to drain without yielding.
+ * Both honor the indexing job's pause switch between batches.
+ */
+type DriveIntensity = 'background' | 'full';
+interface DriveOptions {
+    intensity: DriveIntensity;
+    /** Run the review tier after summaries drain (default true). */
+    reviews?: boolean;
 }
 declare class IndexEnrichmentManager {
     private readonly store;
@@ -12612,6 +12924,13 @@ declare class IndexEnrichmentManager {
     private readonly isPaused;
     private readonly events;
     private readonly resolveBoekwachter;
+    private readonly shadowProducers;
+    private readonly history;
+    private readonly refreshStatic;
+    /** In-flight on-demand drives, one per project (joiners get the same run). */
+    private readonly drives;
+    /** Nonzero while a night-shift catch-up sweep is holding task dispatch. */
+    private catchUpRuns;
     private startupTimer;
     private tickTimer;
     private running;
@@ -12621,6 +12940,42 @@ declare class IndexEnrichmentManager {
     stop(): void;
     /** Live, durable-for-the-tick status consumed by the Night Shift menu. */
     getActivity(): IndexEnrichmentActivity | null;
+    /**
+     * Emit the once-per-wave `project.index.reviewed` audit event: only on the
+     * transition where this tick stored reviews AND the queue is now empty.
+     * Per-file events would flood the ~150-kind flat log (day batches alone
+     * would emit dozens per sweep); the drain is the meaningful moment.
+     */
+    private logReviewDrain;
+    /**
+     * True while a night-shift catch-up sweep runs — the TaskRunner holds
+     * night-shift task dispatch on it so batch work starts against a current
+     * index, per the explicit "index first, then tasks" activation contract.
+     */
+    isCatchUpActive(): boolean;
+    /** True while an on-demand drive is running (optionally for one project). */
+    isDriving(projectId?: string): boolean;
+    /** Mode of the drive running for a project, or null when idle. */
+    driveMode(projectId: string): DriveIntensity | null;
+    /**
+     * Start an on-demand drive for one project: static refresh first, then the
+     * AI tiers (shadows → summaries → areas → reviews) to drain. Returns
+     * immediately; progress flows over the usual `index_progress` events and
+     * `/index/status` polling. One drive per project — a second request joins
+     * the running one.
+     */
+    drive(projectId: string, opts: DriveOptions): {
+        started: boolean;
+        alreadyRunning: boolean;
+    };
+    /**
+     * Bring every indexing-enabled project's static AND AI index up to date,
+     * sequentially at full intensity — the night-shift activation sweep. The
+     * catch-up flag is raised synchronously so a caller that kicks this (not
+     * awaited) and then wakes the TaskRunner still gets the dispatch hold.
+     */
+    catchUpAll(): Promise<void>;
+    private runDrive;
     /** Exposed for tests: run one batch ignoring the timers (still idle-gated). */
     tick(): Promise<void>;
     private isIdle;