@bendyline/gezel-inference 1.0.3 → 1.0.5

package/dist/providers/image/types.d.ts

@@ -0,0 +1,237 @@
+import type { ImageAspectRatio, ImageModelAuxiliaryRole, ImageQuality } from '@bendyline/gezel';
+export type { ImageModelAuxiliaryRole } from '@bendyline/gezel';
+/**
+ * ImageProvider — the service-side abstraction for local image generation.
+ *
+ * Mirrors the role `LLMProvider` plays for text. Deliberately simpler:
+ * image gen is one-shot rather than session-based, so there is no
+ * `createSession`/`sendAndWait` stream — just a single `generate` call
+ * that returns a PNG buffer plus metadata.
+ *
+ * Implementations today:
+ *   - `MockImageProvider` — deterministic 1x1 PNG for tests and
+ *     GEZEL_MOCK_PROVIDER=1 flows.
+ *   - `StableDiffusionCppProvider` — talks to a `sd-server` binary over HTTP.
+ */
+/**
+ * One source image for editing / reference-driven generation, after
+ * the route has resolved any artifact paths to bytes. Provider sees
+ * a uniform `{ data: Buffer; mimeType }` shape.
+ */
+export interface ImageInputBytes {
+    data: Buffer;
+    mimeType: string;
+}
+/**
+ * Where a local generation is. sd-server loads weights lazily inside the
+ * first request after a launch, so `loading_model` happens mid-request, and
+ * its tiled VAE decode prints a progress bar of its own after sampling.
+ */
+export type ImageGenerationPhase = 'queued' | 'loading_model' | 'sampling' | 'decoding';
+/**
+ * Progress info reported mid-generate by providers that can observe
+ * per-step advancement. Today only the local sd-cpp provider emits
+ * these (parsed from sd-server's `|==> | 3/20 - 18.20s/it` stdout).
+ * Cloud providers stay silent — their HTTP APIs are one-shot, with
+ * no streaming step counter to surface.
+ *
+ * `step`/`totalSteps` count within the phase: tensors loaded while
+ * `loading_model`, sampling steps while `sampling`, tiles while `decoding`.
+ * Both are 0 while `queued`. A consumer that only draws a sampling bar
+ * reads events whose `phase` is `sampling` or absent.
+ */
+export interface ImageGenerationProgress {
+    /** Unit the engine just completed in this phase (1-indexed). */
+    step: number;
+    /** Units in this phase. */
+    totalSteps: number;
+    /** Wall-clock seconds for the most recent step, when reported. */
+    secondsPerStep?: number;
+    /** Absent from providers that only report sampling. */
+    phase?: ImageGenerationPhase;
+}
+export interface ImageGenerationInput {
+    prompt: string;
+    negativePrompt?: string;
+    /** Manifest id of the model to use. Provider falls back to its default. */
+    model?: string;
+    width?: number;
+    height?: number;
+    /**
+     * The shape and size tier the caller asked for. Local engines render the
+     * pixels the route already resolved from these; cloud providers map them
+     * to their own aspect ratios and size tiers, which explicit pixels
+     * override.
+     */
+    aspectRatio?: ImageAspectRatio;
+    quality?: ImageQuality;
+    steps?: number;
+    seed?: number;
+    /**
+     * Source images for image editing / reference-driven generation.
+     * Cloud providers accept multiple; sd-cpp's img2img path uses the
+     * first only (the others are dropped with a warning).
+     */
+    inputImages?: ImageInputBytes[];
+    /** Img2img strength (0 = keep source, 1 = ignore source). sd-cpp only. */
+    strength?: number;
+    /**
+     * Optional callback fired as the engine advances through sampling
+     * steps. Today only the local sd-cpp provider emits these; cloud
+     * providers ignore the field. Errors thrown from the callback are
+     * swallowed so a buggy listener can't take down a generation.
+     */
+    onProgress?: (progress: ImageGenerationProgress) => void;
+    /**
+     * Cancels the generation. A queued request leaves without touching the
+     * engine. sd-server cannot interrupt a render it has started, and keeps
+     * rendering after its client disconnects, so the local provider stops the
+     * engine process instead; the next generation pays a fresh weight load.
+     */
+    signal?: AbortSignal;
+}
+/** The caller's signal aborted the generation. */
+export declare class ImageGenerationCancelledError extends Error {
+    readonly code = "image_generation_cancelled";
+    constructor();
+}
+/**
+ * The engine could not fit the render into graphics memory. sd-server plans
+ * placement at launch and can misjudge free memory held by another engine;
+ * it then fails at the first sampling step with a bare "no results".
+ */
+export declare class ImageCapacityError extends Error {
+    readonly code = "image_capacity";
+    constructor(detail?: string);
+}
+export interface ImageGenerationMeta {
+    model: string;
+    seed: number;
+    steps: number;
+    widthPx: number;
+    heightPx: number;
+    durationMs: number;
+    /**
+     * Set when `inputImages` were supplied but the resolved model does not
+     * support img2img — the provider dropped the sources and generated from
+     * the prompt alone. Mirrors the core wire schema so the route can
+     * forward it untouched.
+     */
+    img2imgSkippedReason?: string;
+    /** Provider limits or adjustments to the requested image settings. */
+    settingsNotes?: string[];
+}
+export interface ImageGenerationOutput {
+    png: Buffer;
+    meta: ImageGenerationMeta;
+}
+export interface InstalledImageModelInfo {
+    id: string;
+    name: string;
+    approxSizeBytes: number;
+    installedAt: string;
+    /** Loading shape recorded at pull time; absent on pre-capability installs. */
+    weightsKind?: 'checkpoint' | 'diffusion-model';
+    /** Explicit catalog capability recorded at pull time; absent → resolve via the ladder. */
+    supportsImg2Img?: boolean;
+}
+export type ImageModelPullEvent = {
+    type: 'progress';
+    bytesWritten: number;
+    totalBytes?: number;
+}
+/**
+ * Surfaced when the shared `downloadWithRetry` helper hit a transient
+ * network error and is about to try again. The UI can render
+ * "Connection lost — retrying in 4s (attempt 3/5)…" instead of a
+ * fatal error banner. `reason` is already a user-friendly sentence;
+ * don't wrap it.
+ */
+ | {
+    type: 'retrying';
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+} | {
+    type: 'error';
+    error: string;
+} | {
+    type: 'done';
+    id: string;
+};
+export interface ImageModelAuxiliaryPullSpec {
+    role: ImageModelAuxiliaryRole;
+    downloadUrl: string;
+    sha256: string;
+    approxSizeBytes: number;
+}
+export interface ImageModelPullSpec {
+    downloadUrl: string;
+    sha256: string;
+    approxSizeBytes: number;
+    /** Human-readable name copied into the local metadata. */
+    name: string;
+    /**
+     * `checkpoint` — single-file (SD 1.x / SDXL / SD3.5 safetensors). The
+     * supervisor passes `--model <weights>` at sd-server launch.
+     * `diffusion-model` — unet-only (FLUX / SD3 GGUF); supervisor passes
+     * `--diffusion-model <weights>` plus one `--<role>` flag per aux file.
+     */
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    /**
+     * Explicit img2img capability from the catalog manifest, persisted
+     * into the installed metadata so local state stays self-describing
+     * even if the catalog entry later disappears. Absent when the catalog
+     * didn't declare it — resolution falls back to the assessment map +
+     * weights-kind default.
+     */
+    supportsImg2Img?: boolean;
+    /** Auxiliary files (VAE, text encoders) downloaded alongside the unet. */
+    auxiliaryFiles: ImageModelAuxiliaryPullSpec[];
+}
+export interface ImageEngineHealth {
+    /**
+     * `ok` — the engine is reachable and ready to accept generation requests.
+     * `unreachable` — the configured engine URL is not responding (no
+     *   process listening, network error, etc).
+     * `not-configured` — no engine binary or URL is wired up; the provider
+     *   would fall back to a default loopback URL that nothing is going to
+     *   answer. UI surfaces this distinctly so the user gets actionable
+     *   guidance rather than a generic "unreachable" state.
+     */
+    status: 'ok' | 'unreachable' | 'not-configured';
+    /** Resolved base URL the provider is pointed at, for diagnostic display. */
+    baseUrl: string;
+    /** Free-form reason when `status !== 'ok'`. */
+    error?: string;
+}
+export interface ImageProvider {
+    readonly name: string;
+    generate(input: ImageGenerationInput): Promise<ImageGenerationOutput>;
+    listInstalledModels(): Promise<InstalledImageModelInfo[]>;
+    /**
+     * The model a generate that names none will use. Callers that look up
+     * per-model defaults (the route's recommended steps) must ask this rather
+     * than guess, or the defaults of one model are applied to another.
+     * Providers without a local default omit it.
+     */
+    resolveDefaultModelId?(): Promise<string | undefined>;
+    /**
+     * Stream the install of one catalog model. When `signal` is supplied
+     * and aborts mid-download, providers should leave any `.partial` file
+     * in place so a follow-up pull resumes via Range requests — disconnect
+     * ≠ delete. Cloud providers ignore the field.
+     */
+    pullModel(id: string, spec: ImageModelPullSpec, signal?: AbortSignal): AsyncIterable<ImageModelPullEvent>;
+    deleteModel(id: string): Promise<void>;
+    /**
+     * Probe the underlying engine for reachability without doing real
+     * work. Implementations should be fast (sub-second) and never throw
+     * — return `unreachable` / `not-configured` instead. Called by the
+     * Settings UI to render an honest readiness pill.
+     */
+    health(): Promise<ImageEngineHealth>;
+    /** Best-effort shutdown of any backing engine. Called when the service stops. */
+    shutdown?(): Promise<void>;
+}

package/dist/providers/image/types.js

@@ -0,0 +1,20 @@
+/** The caller's signal aborted the generation. */
+export class ImageGenerationCancelledError extends Error {
+    code = 'image_generation_cancelled';
+    constructor() {
+        super('Image generation was cancelled');
+        this.name = 'ImageGenerationCancelledError';
+    }
+}
+/**
+ * The engine could not fit the render into graphics memory. sd-server plans
+ * placement at launch and can misjudge free memory held by another engine;
+ * it then fails at the first sampling step with a bare "no results".
+ */
+export class ImageCapacityError extends Error {
+    code = 'image_capacity';
+    constructor(detail) {
+        super(`Not enough graphics memory to render this image${detail ? ` (${detail})` : ''}. Close other models or try a smaller size.`);
+        this.name = 'ImageCapacityError';
+    }
+}

package/dist/providers/llama-cpp/backend-health.d.ts

@@ -11,6 +11,13 @@
  */
 import type { LlamaCppBackendHealthResponse } from '@bendyline/gezel';
 import type { GpuUnused } from './gpu-startup-watch.js';
+type MissingRuntimeState = NonNullable<LlamaCppBackendHealthResponse['missingRuntime']>;
+/**
+ * Windows: whether this PC can load the runtime every engine imports, read from
+ * the first engine binary discovery found. One is enough: they all link the
+ * same runtime.
+ */
+export declare function readMissingRuntime(now?: number, platform?: NodeJS.Platform): MissingRuntimeState | null;
 /** Record what the latest start of a build found; null clears it. */
 export declare function noteGpuStartup(verdict: GpuUnused | null, now?: Date): void;
 export declare function noteHostOutOfMemory(input: {

package/dist/providers/llama-cpp/backend-health.js

@@ -9,7 +9,44 @@
  * Process-wide like the backend env it sits beside: every llama provider in
  * this process launches the same build.
  */
-import { readLlamaCudaBlocker } from '@bendyline/gezel/native';
+import { missingMachineRuntime, readLlamaCudaBlocker, vcRedistributableUrl, } from '@bendyline/gezel/native';
+/**
+ * Reading an engine's import tables takes tens of milliseconds of synchronous
+ * file reads, and the answer only changes when someone installs the runtime.
+ */
+const RUNTIME_CHECK_TTL_MS = 60_000;
+let runtimeCheck = null;
+/**
+ * Windows: whether this PC can load the runtime every engine imports, read from
+ * the first engine binary discovery found. One is enough: they all link the
+ * same runtime.
+ */
+export function readMissingRuntime(now = Date.now(), platform = process.platform) {
+    if (platform !== 'win32')
+        return null;
+    const binary = [
+        process.env.GEZEL_LLAMA_SERVER_BIN,
+        process.env.GEZEL_SD_SERVER_BIN,
+        process.env.GEZEL_WHISPER_SERVER_BIN,
+    ].find((path) => Boolean(path));
+    if (!binary)
+        return null;
+    if (runtimeCheck?.binary === binary && now - runtimeCheck.at < RUNTIME_CHECK_TTL_MS) {
+        return runtimeCheck.value;
+    }
+    const failure = missingMachineRuntime(binary, process.env);
+    const arch = failure?.arch === 'arm64' || failure?.arch === 'x64' ? failure.arch : null;
+    const value = failure && arch
+        ? {
+            arch,
+            dll: failure.dll ?? 'VCRUNTIME140.dll',
+            downloadUrl: vcRedistributableUrl(arch),
+            detail: `${binary}: ${failure.reason}`,
+        }
+        : null;
+    runtimeCheck = { binary, at: now, value };
+    return value;
+}
 let gpuUnused = null;
 let outOfMemory = null;
 /** Record what the latest start of a build found; null clears it. */
@@ -51,14 +88,17 @@ export function llamaBackendHealthView() {
     // A verdict about a build the process has since moved off (a quarantine
     // fallback, a lifted quarantine) no longer describes what runs.
     const unused = gpuUnused && gpuUnused.backend === running ? gpuUnused : null;
+    const missingRuntime = readMissingRuntime();
     return {
         ...(running ? { running } : {}),
         ...(cudaBlocker ? { cudaBlocker } : {}),
         ...(unused ? { gpuUnused: unused } : {}),
+        ...(missingRuntime ? { missingRuntime } : {}),
         ...(outOfMemory ? { outOfMemory } : {}),
     };
 }
 export function __resetLlamaBackendHealthForTest() {
     gpuUnused = null;
     outOfMemory = null;
+    runtimeCheck = null;
 }

package/dist/providers/mlx/provider.js

@@ -1497,11 +1497,21 @@ class MlxSession extends StreamingSessionBase {
                         // Paused mid-reply: the stream stops until the chat ahead is
                         // served. The reply so far stays on screen; the pill says why.
                         const detail = engineHoldLabelFor(queue);
-                        this.emitEnginePhase({ provider: 'mlx', phase: 'generating', detail });
+                        this.emitEnginePhase({
+                            provider: 'mlx',
+                            phase: 'generating',
+                            detail,
+                            hold: 'yielding',
+                        });
                         return;
                     }
                     const detail = this.engineHold.begin(queue, opts?.queue?.onQueueWait);
-                    this.emitEnginePhase({ provider: 'mlx', phase: 'prefill', detail });
+                    this.emitEnginePhase({
+                        provider: 'mlx',
+                        phase: 'prefill',
+                        detail,
+                        hold: queue.state === 'paused' ? 'yielding' : 'behind',
+                    });
                 };
                 // Anchored at request dispatch: only work the engine did while THIS
                 // turn was already waiting can explain why it never got a first byte.
@@ -2666,7 +2676,7 @@ class MlxSession extends StreamingSessionBase {
                         // tool result makes the success unambiguous; the STOP
                         // instruction is the closing emphasis, not the framing.
                         projectMacroInterceptCount++;
-                        output = `✓ The project was successfully created on your earlier \`${startedProjectOrJobThisTurn.tool}\` call this turn — kickoff is complete and the lead is on it.\n\nOriginal result:\n${startedProjectOrJobThisTurn.firstResult}\n\nSTOP — do NOT emit any more tool calls this turn. Each project-start call creates a real project, lead, and kickoff task; repeating the macro would create duplicates. END YOUR TURN NOW with a one-sentence summary to the user (e.g. "Project is on it — the voorman is leading"). The lead handles the work from here.`;
+                        output = `✓ The project was successfully created on your earlier \`${startedProjectOrJobThisTurn.tool}\` call this turn — kickoff is complete and the lead is on it.\n\nOriginal result:\n${startedProjectOrJobThisTurn.firstResult}\n\nSTOP — do NOT emit any more tool calls this turn. Each project-start call creates a real project, lead, and kickoff task; repeating the macro would create duplicates. END YOUR TURN NOW with a one-sentence summary to the user (e.g. "Project is underway — the crew lead is on it"). The lead handles the work from here.`;
                         if (projectMacroInterceptCount >= PROJECT_MACRO_INTERCEPT_CAP) {
                             forceProjectMacroBail = {
                                 closingText: deriveProjectMacroClosing(startedProjectOrJobThisTurn.firstResult),

package/dist/providers/native/supervisor.d.ts

@@ -289,6 +289,14 @@ export declare class NativeEngineSupervisor {
     private currentOomKills;
     private readonly logListeners;
     private recentStarts;
+    /**
+     * The {@link recentStarts} entry for the child running now. A child that
+     * became ready and was then stopped on purpose (idle, memory pressure, a
+     * model swap) was not a crash, so its start is returned to the budget.
+     * Otherwise an engine asked to swap models or yield memory three times in
+     * a minute would refuse the fourth start as a crash loop.
+     */
+    private currentStartAt;
     private lastUsedAt;
     /**
      * The same mark on the awake clock. Every idle/pressure DECISION reads this

package/dist/providers/native/supervisor.js

@@ -25,7 +25,7 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { awakeNow, createLogger } from '@bendyline/gezel';
 import { listProcessSnapshots } from '@bendyline/gezel-client/node';
-import { windowsHeadlessSpawnOptions } from '@bendyline/gezel/native';
+import { diagnoseDllLoadFailure, windowsHeadlessSpawnOptions } from '@bendyline/gezel/native';
 import { acquireNativeCapacity, } from './device-capacity.js';
 const log = createLogger('native');
 /**
@@ -204,6 +204,14 @@ export class NativeEngineSupervisor {
     // swallowed so a buggy parser can't take down the supervisor.
     logListeners = new Set();
     recentStarts = [];
+    /**
+     * The {@link recentStarts} entry for the child running now. A child that
+     * became ready and was then stopped on purpose (idle, memory pressure, a
+     * model swap) was not a crash, so its start is returned to the budget.
+     * Otherwise an engine asked to swap models or yield memory three times in
+     * a minute would refuse the fourth start as a crash loop.
+     */
+    currentStartAt;
     lastUsedAt = 0;
     /**
      * The same mark on the awake clock. Every idle/pressure DECISION reads this
@@ -485,7 +493,11 @@ export class NativeEngineSupervisor {
         const { child } = this.state;
         if (this.state.kind === 'running' && reason !== 'health-restart') {
             await this.runBeforeStop(reason, this.state.launch.baseUrl);
+            const index = this.currentStartAt === undefined ? -1 : this.recentStarts.indexOf(this.currentStartAt);
+            if (index >= 0)
+                this.recentStarts.splice(index, 1);
         }
+        this.currentStartAt = undefined;
         this.pressureDeadlineAt = undefined;
         this.expectedExitReason = reason;
         this.state = { kind: 'stopped' };
@@ -581,7 +593,9 @@ export class NativeEngineSupervisor {
                 }
             });
         }
-        this.recentStarts.push(Date.now());
+        const startedAt = Date.now();
+        this.recentStarts.push(startedAt);
+        this.currentStartAt = startedAt;
         let child;
         try {
             child = this.spawn(launch.command, launch.args, {
@@ -1021,6 +1035,21 @@ export class NativeEngineSupervisor {
         // shortage, and the GPU-to-RAM ladder those lines trigger cannot help
         // when RAM is what ran out.
         const oomKilled = signal === 'SIGKILL' && !expected ? this.oomKillsSince(this.currentOomKills) : null;
+        // Windows reports a DLL the engine could not load only as a status, before
+        // the engine prints a word. Name the DLL. A missing machine-wide runtime is
+        // a panic of its own, so no build is quarantined for it (missing-dll.ts).
+        const dllFailure = process.platform === 'win32' &&
+            priorState.kind === 'starting' &&
+            !expected &&
+            !this.currentReachedReady &&
+            !this.currentPanic
+            ? diagnoseDllLoadFailure(code, priorState.launch.command, {
+                ...process.env,
+                ...(priorState.launch.env ?? {}),
+            })
+            : null;
+        if (dllFailure)
+            this.onLog(`${this.logPrefix} startup DLL check: ${dllFailure.reason}`);
         const panic = oomKilled
             ? {
                 kind: 'host-out-of-memory',
@@ -1032,7 +1061,9 @@ export class NativeEngineSupervisor {
                         kind: 'illegal-instruction',
                         line: 'engine terminated by SIGILL (illegal instruction) with no diagnostic output',
                     }
-                    : undefined));
+                    : dllFailure?.machineWide
+                        ? { kind: 'missing-runtime', line: dllFailure.summary }
+                        : undefined));
         const snapshot = {
             incidentId: `native-${pid ?? 'unknown'}-${exitedAt}`,
             ...(pid !== undefined ? { pid } : {}),
@@ -1045,6 +1076,15 @@ export class NativeEngineSupervisor {
             reachedReady: this.currentReachedReady,
             ...(expectedReason ? { expectedReason } : {}),
             ...(panic ? { panicKind: panic.kind, panicLine: panic.line } : {}),
+            ...(dllFailure
+                ? {
+                    dllLoadFailure: {
+                        kind: dllFailure.kind,
+                        ...(dllFailure.dll ? { dll: dllFailure.dll } : {}),
+                        summary: dllFailure.summary,
+                    },
+                }
+                : {}),
             outputTail: this.currentOutput,
             ...(this.currentDiagnostics ? { diagnostics: { ...this.currentDiagnostics } } : {}),
         };
@@ -1105,7 +1145,15 @@ export class NativeEngineSupervisor {
         // call wins because it lands first (the classifier sees the leaf
         // exception line slightly before the kernel reports the exit).
         if (this.startupAbort && priorState.kind === 'starting') {
-            this.startupAbort.abort(new Error(`${this.logPrefix} child exited (code=${code} signal=${signal ?? 'none'}) before becoming ready`));
+            this.startupAbort.abort(dllFailure
+                ? Object.assign(new Error(`${this.logPrefix} could not start: ${dllFailure.summary}`), {
+                    // The engine never came up, and the summary says what to do, so
+                    // callers pass it through unchanged.
+                    code: ENGINE_LAUNCH_ERROR_CODE,
+                    isActionable: true,
+                    ...(panic?.kind === 'missing-runtime' ? { panicKind: panic.kind } : {}),
+                })
+                : new Error(`${this.logPrefix} child exited (code=${code} signal=${signal ?? 'none'}) before becoming ready`));
         }
         this.state = { kind: 'stopped' };
     }

package/dist/providers/project-macro-loop-bail.js

@@ -6,12 +6,14 @@ export const PROJECT_MACRO_FAILURE_CAP = 2;
 /** Derive a concise user-facing closing from a successful kickoff result. */
 export function deriveProjectMacroClosing(firstResult) {
     const projectMatch = firstResult.match(/Started (?:project|job) "([^"]+)"/);
-    const leadMatch = firstResult.match(/Recruited (\S+) as (voorman|builder|lead)/i);
+    // "voorman" is what results said before the crew lead was renamed.
+    const leadMatch = firstResult.match(/Recruited (\S+) as (crew lead|voorman|builder|lead)/i);
     const projectName = projectMatch?.[1];
     const leadName = leadMatch?.[1];
-    const leadRole = leadMatch?.[2];
+    const leadRole = leadMatch?.[2]?.toLowerCase();
     if (projectName && leadName) {
-        const trailer = leadRole === 'voorman' ? ' is leading the crew' : ' is on it';
+        const crewLead = leadRole === 'crew lead' || leadRole === 'voorman';
+        const trailer = crewLead ? ' is leading the crew' : ' is on it';
         return `Project "${projectName}" is kicked off — ${leadName}${trailer}. You can watch their work surface in this thread.`;
     }
     if (projectName) {

package/dist/providers/provider-lifecycle.d.ts

@@ -0,0 +1,21 @@
+interface Provider {
+    shutdown?(): Promise<void>;
+}
+/**
+ * Owns one lazy provider generation. Reset and broker retirement close admission
+ * before waiting for an in-flight build and admitted work. A failed shutdown
+ * retains its generation for retry; no replacement can leak past it.
+ */
+export declare class ProviderLifecycle<T extends Provider> {
+    private readonly operations;
+    private generation?;
+    private transition?;
+    private brokerRetired;
+    constructor(operations: ReadonlySet<PropertyKey>);
+    current(build: () => Promise<T>, retireWithBroker?: boolean): Promise<T>;
+    reset(): Promise<void>;
+    /** Permanent for native generations; user-owned cloud providers remain usable. */
+    retireForMachineBroker(): Promise<void>;
+    private drain;
+}
+export {};

package/dist/providers/provider-lifecycle.js

@@ -0,0 +1,83 @@
+import { ProviderRetirementGate, trackProviderOperations } from './retirement-gate.js';
+/**
+ * Owns one lazy provider generation. Reset and broker retirement close admission
+ * before waiting for an in-flight build and admitted work. A failed shutdown
+ * retains its generation for retry; no replacement can leak past it.
+ */
+export class ProviderLifecycle {
+    operations;
+    generation;
+    transition;
+    brokerRetired = false;
+    constructor(operations) {
+        this.operations = operations;
+    }
+    async current(build, retireWithBroker = true) {
+        if (retireWithBroker && this.brokerRetired)
+            throw new Error('local provider retired after machine engine adoption');
+        if (this.transition) {
+            await this.transition;
+            return this.current(build, retireWithBroker);
+        }
+        if (this.generation?.closed) {
+            await this.reset();
+            return this.current(build, retireWithBroker);
+        }
+        if (this.generation)
+            return this.generation.build;
+        const gate = new ProviderRetirementGate();
+        const generation = {
+            gate,
+            closed: false,
+            retireWithBroker,
+            build: Promise.resolve()
+                .then(build)
+                .then((provider) => {
+                generation.provider = provider;
+                return trackProviderOperations(provider, gate, this.operations);
+            })
+                .catch((error) => {
+                if (this.generation === generation)
+                    this.generation = undefined;
+                throw error;
+            }),
+        };
+        this.generation = generation;
+        return generation.build;
+    }
+    reset() {
+        return this.drain('local provider retired during reset; obtain the current provider');
+    }
+    /** Permanent for native generations; user-owned cloud providers remain usable. */
+    retireForMachineBroker() {
+        this.brokerRetired = true;
+        if (this.generation && !this.generation.retireWithBroker)
+            return Promise.resolve();
+        return this.drain();
+    }
+    drain(message) {
+        if (this.transition)
+            return this.transition;
+        const generation = this.generation;
+        if (!generation)
+            return Promise.resolve();
+        generation.closed = true;
+        generation.gate.beginRetirement(message);
+        const run = (async () => {
+            // A failed build produced no provider to shut down. Its caller still
+            // receives the build error, while retirement can finish successfully.
+            await generation.build.catch(() => { });
+            await generation.gate.waitForIdle();
+            await generation.provider?.shutdown?.();
+            if (this.generation === generation)
+                this.generation = undefined;
+        })();
+        this.transition = run;
+        const clear = () => {
+            if (this.transition === run)
+                this.transition = undefined;
+        };
+        void run.then(clear, clear);
+        return run;
+    }
+}

package/dist/providers/retirement-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tracks long-running provider operations while a machine-engine adoption is
+ * retiring the user daemon's local provider. The gate closes before draining:
+ * callers that already hold a provider reference cannot start a second local
+ * operation after the broker has become authoritative.
+ */
+export declare class ProviderRetirementGate {
+    private retiring;
+    private retirementMessage;
+    private active;
+    private readonly idleWaiters;
+    beginRetirement(message?: string): void;
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    waitForIdle(): Promise<void>;
+}
+/**
+ * Wrap only the operations which can own a native engine. Management calls
+ * remain direct, and shutdown is deliberately not counted as user work.
+ */
+export declare function trackProviderOperations<T extends object>(provider: T, gate: ProviderRetirementGate, operationNames: ReadonlySet<PropertyKey>): T;