@omnicross/daemon 0.1.10 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import * as _omnicross_core from '@omnicross/core';
-import { OutboundApiServerConfig, Logger, ProviderConfigSource, TransformerService, Transformer, ResolvedTransformerChain, ApiServerSettingsStore, PricingStore, AutomaticPricingSource, OutboundKeyDb, OutboundKeyDbRow, OutboundKeyPolicy, PricingEngine as PricingEngine$1 } from '@omnicross/core';
+import { Logger, OutboundApiServerConfig, ProviderConfigSource, TransformerService, Transformer, ResolvedTransformerChain, ApiServerSettingsStore, PricingStore, AutomaticPricingSource, OutboundPermission, OutboundKeyDb, OutboundKeyDbRow, OutboundKeyPolicy, PricingEngine as PricingEngine$1, OpenAIOperationRegistry } from '@omnicross/core';
 import { ApiKeyPoolService } from '@omnicross/core/completion/ApiKeyPoolService';
-import { AllowanceSchedulingConfig, AccountProbeConfig, OutboundKeyDb as OutboundKeyDb$1, VoucherDb, KeySpendReader, OutboundApiServer } from '@omnicross/core/outbound-api';
+import { AllowanceSchedulingConfig, AccountProbeConfig, OutboundKeyDb as OutboundKeyDb$1, VoucherDb, KeySpendReader, OutboundApiServer, ImagesServerConfig } from '@omnicross/core/outbound-api';
 import { RouteLeaseManager, ProviderProxy } from '@omnicross/core/provider-proxy';
 import { UsageRecorder, PricingEngine } from '@omnicross/core/usage';
-import { SubscriptionCredentialStore, FetchLike, SubscriptionProviderRegistry, SubscriptionAccountService } from '@omnicross/subscriptions';
+import { SubscriptionCredentialStore, FetchLike, CodexImageCapabilityEvidenceSource, CodexImageCapabilityEvidenceRequest, CodexImageCapabilityEvidence, CodexImageCapabilityObservation, ImageExecutionScheduler, ImageExecutionAccountKey, ImageExecutionSchedulerRequest, ImageExecutionSchedulerGrant, SubscriptionAccountService, SubscriptionProviderRegistry } from '@omnicross/subscriptions';
 import { AccountAllowanceSnapshot } from '@omnicross/contracts/account-allowance-types';
 import { ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, AccountTokensConfig, ProxyConfig, SubscriptionAccountSanitized, AccountClientIdentity, SubscriptionAccountEntry } from '@omnicross/contracts/account-tokens-types';
 import * as _omnicross_contracts_subscription_types from '@omnicross/contracts/subscription-types';
@@ -15,12 +14,17 @@ import { SubscriptionIdentityStore } from '@omnicross/core/provider-proxy/identi
 import { LoggingConfig, HealthReport } from '@omnicross/contracts/health-logging-types';
 import { SubscriptionAccountHealth } from '@omnicross/core/pipeline/SubscriptionAccountHealth';
 import { fetchUpstream } from '@omnicross/core/pipeline/upstreamFetch';
+import { UsageTotals, ModelUsageRow, ApiKeyUsageRow } from '@omnicross/contracts/usage-stats-types';
 import { ThinkLevel } from '@omnicross/contracts/completion-types';
 import { AuditRecord, AuditStats, AuditBodyResult, AuditConfig } from '@omnicross/contracts/audit-types';
 import { BillingDeliveryStatus, BillingConfig, BillingEvent } from '@omnicross/contracts/billing-types';
 import http from 'node:http';
+import * as _omnicross_contracts_image_generation_types from '@omnicross/contracts/image-generation-types';
+import { ImageCapabilityUnavailableReason, ImageCapabilities, ImageGenerationErrorCode, ImageReferenceMetadata, ImageReferenceId } from '@omnicross/contracts/image-generation-types';
+import { ImageApiContributions, ResponsesImageGenerationContribution, ResponsesImageInspectionInput, ResponsesImageAdmission, ResponsesHostedToolSelection, ResponsesImageRequestScope, ImageTelemetrySink, ImageApiAuditRecord, ImageTelemetryRecord, ImageReferenceStore, ImageReferenceSaveInput, ImageReferenceResolution, ImageTemporaryResourceBudget, ImageTemporaryResourceBudgetLease, ImageApiLimits, ImageRequestResourceScope, ImageApiRuntimeResolver, RemoteImageAssetResolver, ImageProvider, ImageProviderRegistry, ImageOrchestrator } from '@omnicross/core/image-generation';
 import { LLMProvider, AgentDefaultModels, GlobalModelParameters } from '@omnicross/contracts/llm-config';
 import { PricingEntry, PricingEntryInput, PricingResolution, PricingSourceRefreshResult } from '@omnicross/contracts/pricing-types';
+import { ResponsesImageStateStore, ResponsesImageStateCommitInput, ResponsesImageCallBinding, ResponsesImageCallId, ResponsesImageCallResolution, ResponsesImageResponseResolution } from '@omnicross/core/image-generation/responses';
 import { WebhookConfig, WebhookEvent } from '@omnicross/contracts/webhook-types';
 
 /**
@@ -86,6 +90,193 @@ declare class SecretBox {
     encryptMaybe(value: string): string;
 }
 
+/**
+ * usageRollup — the immutable per-day aggregate that lets a range query skip a
+ * day's rows entirely.
+ *
+ * A rollup is computed ONCE, when a day is closed (strictly before today's local
+ * date), and is then never rewritten. It is deliberately kept FOREVER, outliving
+ * the raw shard it was built from, for one load-bearing reason:
+ * `getSpendByKey().totalUsd` is a LIFETIME number that seeds the outbound key
+ * spend policy (`core/outbound-api/keySpendTracker`). Pruning raw rows without
+ * keeping a per-key aggregate behind would silently reset every key's lifetime
+ * spend and quietly re-open budgets the operator had already spent.
+ *
+ * WHAT IS EXACT AND WHAT IS NOT
+ *
+ * Every count, token sum and cost in a rollup is exact — it is a plain sum of
+ * the same rows a raw scan would have visited. The ONE approximation is
+ * `medianCacheHitRate`: a median cannot be composed from per-day medians, so
+ * each day stores a 1000-bin histogram of its per-event hit rates instead. The
+ * median recovered from bins is off by at most half a bin — 0.0005, i.e. well
+ * under a twentieth of a percentage point. Storing the raw rates instead would
+ * make a "permanent" sidecar grow with traffic, which is the property this whole
+ * layout exists to avoid.
+ *
+ * STALENESS: a rollup records the byte size of the shard it was built from.
+ * Because a shard is append-only, a size change means rows were added after the
+ * rollup was computed (only reachable by inserting into a past day — the tests
+ * do it, production does not) and the rollup is recomputed. A shard that is GONE
+ * is the pruned case, where the rollup is the sole surviving authority.
+ *
+ * @module @omnicross/daemon/usage/usageRollup
+ */
+
+/** Everything in `UsageTotals` except the one field that cannot be summed. */
+type SummableTotals = Omit<UsageTotals, 'medianCacheHitRate'>;
+/** Per-model group inside a rollup. `unpriced` is deliberately absent — it is
+ *  derived at query time from the injected pricing lookup, so a pricing change
+ *  never requires rewriting an immutable rollup. */
+type RollupModelRow = Omit<ModelUsageRow, 'unpriced'>;
+/** Per-key group inside a rollup. `label` is absent for the same reason: it is
+ *  resolved by the admin handler against the live key registry. */
+type RollupApiKeyRow = Omit<ApiKeyUsageRow, 'label'>;
+/** One hour of a day. Only hours that saw traffic are stored. */
+interface RollupHourRow {
+    /** LOCAL hour of day, 0–23. */
+    hour: number;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
+/** The on-disk `usage-YYYY-MM-DD.rollup.json` document. */
+interface UsageDayRollup {
+    version: 1;
+    /** `YYYY-MM-DD`, LOCAL. Must match the file name. */
+    date: string;
+    /** Byte size of the shard this was built from; the staleness guard. */
+    sourceBytes: number;
+    totals: SummableTotals;
+    /** Sparse `binIndex -> count` over per-event cache-hit rates. */
+    hitRateBins: Record<string, number>;
+    byModel: RollupModelRow[];
+    byApiKey: RollupApiKeyRow[];
+    byHour: RollupHourRow[];
+    /** Distinct non-null session ids seen that day (drilldown index). */
+    sessionIds: string[];
+    /** True when `sessionIds` hit {@link SESSION_INDEX_LIMIT} and is incomplete. */
+    sessionIdsTruncated: boolean;
+}
+
+/**
+ * usageRollupStore — read-or-build the per-day rollup sidecars.
+ *
+ * A rollup is built LAZILY, the first time a query needs a closed day, and then
+ * reused forever. Building it is the only time that day's rows are ever parsed
+ * again; every subsequent query for any range containing that day reads a few KB
+ * of JSON instead of megabytes of JSONL.
+ *
+ * STALENESS is checked against the shard's byte size, not its mtime. Shards are
+ * append-only, so a size that no longer matches what the rollup was built from
+ * means rows were added afterwards — only reachable by inserting an event with a
+ * past `ts`, which the store API permits and the tests exercise. A shard that is
+ * absent entirely is the PRUNED case: the rollup is then the sole surviving
+ * record of that day and is trusted unconditionally.
+ *
+ * Writes are atomic (temp file + rename) so a crash mid-write cannot leave a
+ * half-JSON sidecar that later reads as a corrupt day.
+ *
+ * @module @omnicross/daemon/usage/usageRollupStore
+ */
+
+declare class UsageRollupStore {
+    private readonly usageDir;
+    private readonly maxCached;
+    private readonly cache;
+    /** In-flight builds, so a burst of concurrent queries builds a day ONCE. */
+    private readonly inFlight;
+    constructor(usageDir: string, maxCached?: number);
+    /**
+     * The rollup for a CLOSED day, building it from the shard when absent or
+     * stale. `null` means the day has neither a usable rollup nor a shard — i.e.
+     * nothing was ever recorded for it.
+     *
+     * Callers must not ask for TODAY: today's rows are still arriving, so a rollup
+     * of them would be wrong the moment it was written.
+     */
+    get(dayKey: string, hasShard?: boolean): Promise<UsageDayRollup | null>;
+    /** Forget a day — used when an insert lands in an already-rolled-up day. */
+    invalidate(dayKey?: string): void;
+    /**
+     * Build (or rebuild) a day's rollup from its shard and persist it. Exposed for
+     * the prune sweeper, which must guarantee a rollup exists BEFORE it deletes
+     * the rows that rollup is derived from.
+     */
+    ensure(dayKey: string): Promise<UsageDayRollup | null>;
+    private resolve;
+    private readSidecar;
+    private writeSidecar;
+    private remember;
+}
+
+/**
+ * UsagePruneSweeper — retention for the sharded usage store.
+ *
+ * Prunes RAW day shards past `retentionDays` and NEVER touches a rollup. That
+ * asymmetry is the whole design: aggregates (totals, per-model, per-key, hourly
+ * trend) stay complete for the lifetime of the install, while the per-row detail
+ * that costs 5 MB a day is bounded. In particular `getSpendByKey().totalUsd` —
+ * the LIFETIME figure seeding the outbound key spend policy — keeps summing
+ * correctly across pruned days, which a naive "delete old rows" would silently
+ * zero, reopening budgets the operator had already spent.
+ *
+ * ORDERING IS LOAD-BEARING: a shard is only ever deleted AFTER its rollup exists
+ * on disk. If the rollup cannot be built, the shard is kept and the day is
+ * retried on the next tick. Deleting rows whose aggregate was never computed
+ * would destroy that day permanently.
+ *
+ * Shaped like `audit/AuditPruneSweeper`: `start()` arms an `unref()`ed interval
+ * plus one immediate pass, `dispose()` clears it, a re-entrancy guard prevents
+ * overlap, and nothing throws — a failed sweep is logged and retried, never
+ * fatal to the daemon.
+ *
+ * @module @omnicross/daemon/usage/UsagePruneSweeper
+ */
+
+/** The `usage` config segment. */
+interface UsageRetentionConfig {
+    /** Days of RAW rows to keep. `0` or absent ⇒ keep everything. */
+    retentionDays?: number;
+}
+declare class UsagePruneSweeper {
+    private readonly usageDir;
+    private readonly rollups;
+    private readonly logger;
+    private config;
+    private readonly intervalMs;
+    /** Injectable clock (ms) for deterministic tests. */
+    private readonly now;
+    private timer;
+    private sweeping;
+    constructor(usageDir: string, rollups: UsageRollupStore, logger: Logger, config?: UsageRetentionConfig, intervalMs?: number, 
+    /** Injectable clock (ms) for deterministic tests. */
+    now?: () => number);
+    /** Whether raw rows are pruned at all. */
+    get enabled(): boolean;
+    /** Re-apply config to the live instance (boot + admin PUT hot-reload). */
+    configure(config: UsageRetentionConfig): void;
+    /**
+     * Arm the interval AND run one pass immediately (boot cleanup). No-op when
+     * retention is off (keep-everything is the zero-regression default).
+     * Idempotent.
+     */
+    start(): void;
+    /** Clear the interval (daemon shutdown / test teardown). Idempotent. */
+    dispose(): void;
+    /**
+     * One prune pass: for every day strictly OLDER than the retention cutoff that
+     * still has a shard, make sure its rollup exists and only then delete the
+     * shard. Exposed for tests; never throws. Returns the number of shards
+     * removed.
+     */
+    sweep(): Promise<number>;
+    /** The LOCAL-midnight epoch ms of the current day. */
+    private todayMidnight;
+}
+
 /**
  * config.ts — the daemon's `config.json` schema + load/save (design D9).
  *
@@ -411,6 +602,12 @@ interface DaemonConfig {
      * so it is never walked by `decryptConfigSecrets`/`encryptConfigSecrets`.
      */
     logging?: LoggingConfig;
+    /**
+     * Optional usage-retention config. Absent ⇒ the default 90-day window on RAW
+     * usage rows. Per-day ROLLUPS are never pruned regardless — they carry the
+     * lifetime per-key spend the outbound key policy seeds from.
+     */
+    usage?: UsageRetentionConfig;
 }
 /** Apply defaults to a (possibly absent) admin block: enabled, port 8766,
  *  loopback, no token. NOTE: an EXPLICIT `port: 0` is honored as "bind an
@@ -1545,6 +1742,254 @@ type AuditCompactor = () => {
 /** The read surface the AdminServer consumes (bootstrap binds it to the ledger dir). */
 type BillingStatusReader = () => BillingDeliveryStatus;
 
+type PreparedImageRuntimeGeneration = {
+    readonly id: string;
+    readonly enabled: true;
+    readonly imageApi: ImageApiContributions;
+    readonly hosted: ResponsesImageGenerationContribution;
+    readonly hostedRuntime: HostedImageRuntimePolicy;
+    readonly inspectCapability?: (apiKeyId: string) => Promise<Omit<ImageRuntimeCapabilityInspection, 'generationId'>>;
+    readonly readRuntimeStatus?: () => ImageRuntimeResourceStatus;
+    dispose(): void | Promise<void>;
+} | {
+    readonly id: string;
+    readonly enabled: false;
+    dispose(): void | Promise<void>;
+};
+interface HostedImageRuntimeGenerationLease {
+    readonly generationId: string;
+    /** Compatibility/debug view; callers should prefer the deep methods below. */
+    readonly contribution: ResponsesImageGenerationContribution;
+    inspectRequest(input: ResponsesImageInspectionInput): ResponsesImageAdmission;
+    validateSelection(admission: ResponsesImageAdmission, selection: ResponsesHostedToolSelection): void;
+    openRequest(input: HostedImageOpenRequestInput): Promise<ResponsesImageRequestScope>;
+    release(): Promise<void>;
+}
+interface HostedImageRuntimePolicy {
+    readonly providerId: string;
+    readonly imageModel: string;
+    readonly referenceTtlMs: number;
+    readonly maxOutputBytes: number;
+    readonly maxTotalOutputBytes: number;
+    readonly preferredAccountId?: string;
+    readonly preferredAccountGroup?: string;
+    readonly boundAccountFallbackPolicy?: 'strict' | 'pool';
+}
+interface HostedImageOpenRequestInput {
+    readonly admission: ResponsesImageAdmission;
+    readonly tenantId: string;
+    readonly requestId: string;
+    readonly sessionKey: string;
+    readonly signal: AbortSignal;
+    readonly authorizedPreviousResponseId?: string;
+    /** Trusted affinity fact forwarded unchanged into the contribution scope. */
+    readonly authorizedPreviousResponseKnownEmpty?: boolean;
+    readonly mainProviderId: string;
+    readonly selectedMainAccountId?: string;
+}
+/** Dormant integration seam for a later Native Responses owner. */
+interface HostedImageContributionFactory {
+    acquire(): Promise<HostedImageRuntimeGenerationLease>;
+}
+/** Bind a stable factory to one app-session runtime manager without acquiring. */
+declare function createHostedImageContributionFactory(manager: ImageRuntimeManager): HostedImageContributionFactory;
+interface ImageRuntimeGenerationStatus {
+    readonly generationId: string;
+    readonly enabled: boolean;
+    readonly httpLeases: number;
+    readonly hostedLeases: number;
+}
+interface ImageRuntimeManagerStatus {
+    readonly disposed: boolean;
+    readonly current: ImageRuntimeGenerationStatus;
+    readonly draining: readonly ImageRuntimeGenerationStatus[];
+}
+type ImageRuntimeSafeUnavailableReason = ImageCapabilityUnavailableReason | 'disabled' | 'runtime_unavailable';
+interface ImageRuntimeCapabilityInspection {
+    readonly generationId: string;
+    readonly enabled: boolean;
+    readonly available: boolean;
+    readonly providerId?: 'codex-subscription';
+    readonly model?: string;
+    readonly reason?: ImageRuntimeSafeUnavailableReason;
+    readonly capabilities?: ImageCapabilities;
+}
+interface ImageRuntimeResourceStatus {
+    readonly queue: Readonly<{
+        activeJobs: number;
+        waitingJobs: number;
+        activeAccounts: number;
+        waitingAccounts: number;
+        waitingTenants: number;
+        maxConcurrentJobsPerAccount: number;
+        maxQueuedJobs: number;
+        accepting: boolean;
+        shuttingDown: boolean;
+    }>;
+    readonly temporary: Readonly<{
+        activeScopes: number;
+        totalBytes: number;
+        tenantCount: number;
+        maxActiveScopes: number;
+        maxTotalBytes: number;
+        maxTenantBytes: number;
+    }>;
+    readonly storage: Readonly<{
+        mounts: number;
+        retiredMounts: number;
+        referenceEntries: number;
+        referenceBytes: number;
+        referenceTombstones: number;
+        stateCalls: number;
+        stateResponses: number;
+        stateTombstones: number;
+        pendingReferenceDeletes: number;
+        maxReferenceEntries: number;
+        maxReferenceBytes: number;
+        maxTenantReferenceBytes: number;
+        maxStateCalls: number;
+        maxStateResponses: number;
+    }>;
+}
+interface PreparedImageRuntimeChange {
+    readonly generationId: string;
+    publish(): void;
+    rollback(): void;
+    dispose(): Promise<void>;
+}
+/** App-session owner for stable forwarders and generation-pinned work. */
+declare class ImageRuntimeManager {
+    #private;
+    readonly contributions: ImageApiContributions;
+    constructor(initial?: PreparedImageRuntimeGeneration);
+    prepare(generation: PreparedImageRuntimeGeneration): PreparedImageRuntimeChange;
+    acquireHosted(): Promise<HostedImageRuntimeGenerationLease>;
+    inspectCapability(apiKeyId: string): Promise<ImageRuntimeCapabilityInspection>;
+    listAvailableModels(apiKeyId: string): Promise<readonly string[]>;
+    resourceStatus(): ImageRuntimeResourceStatus | undefined;
+    status(): ImageRuntimeManagerStatus;
+    dispose(): Promise<void>;
+}
+
+type SafeProvider = 'codex-subscription' | 'unknown' | 'other';
+type SafeModel = 'gpt-image-2' | 'unknown' | 'other';
+type SafeErrorCode = ImageGenerationErrorCode | 'none' | 'other';
+type SafeCountOption = 'unknown' | '0' | '1' | '2-4' | '5+';
+type SafeBooleanOption = boolean | 'unknown';
+type SafeQuality = 'auto' | 'low' | 'medium' | 'high' | 'unknown' | 'other';
+type SafeBackground = 'auto' | 'opaque' | 'transparent' | 'unknown' | 'other';
+type SafeOutputFormat = 'png' | 'jpeg' | 'webp' | 'unknown' | 'other';
+declare const IMAGE_CONFIGURATION_AUDIT_FIELDS: readonly ["enablement", "provider", "model", "account", "queue", "temporary", "limits", "retention", "storage", "remote", "evidence"];
+type ImageConfigurationAuditField = typeof IMAGE_CONFIGURATION_AUDIT_FIELDS[number];
+/** Values are deliberately limited to safe categories and internal generation ids. */
+interface ImageConfigurationAuditRecord {
+    readonly outcome: 'applied';
+    readonly fields: readonly ImageConfigurationAuditField[];
+    readonly previousGenerationId?: string;
+    readonly generationId?: string;
+}
+interface ImageHistogramSnapshot {
+    readonly count: number;
+    readonly sum: number;
+    /** Non-cumulative fixed buckets; `upperBound:null` is the overflow bucket. */
+    readonly buckets: readonly {
+        readonly upperBound: number | null;
+        readonly count: number;
+    }[];
+}
+interface ImageApiMetricDimensions {
+    readonly endpoint: 'images.generate' | 'images.edit';
+    readonly provider: SafeProvider;
+    readonly model: SafeModel;
+    readonly action: 'generate' | 'edit';
+    readonly quality: SafeQuality;
+    readonly background: SafeBackground;
+    readonly outputFormat: SafeOutputFormat;
+    readonly streaming: SafeBooleanOption;
+    readonly requestedOutputs: SafeCountOption;
+    readonly partialImages: SafeCountOption;
+    readonly terminal: 'completed' | 'failed' | 'cancelled';
+    readonly errorCode: SafeErrorCode;
+}
+interface ImageExecutionMetricDimensions {
+    readonly provider: SafeProvider;
+    readonly model: SafeModel;
+    readonly action: 'generate' | 'edit' | 'other';
+    readonly quality: SafeQuality;
+    readonly background: SafeBackground;
+    readonly outputFormat: SafeOutputFormat;
+    readonly streaming: SafeBooleanOption;
+    readonly requestedOutputs: SafeCountOption;
+    readonly terminal: 'completed' | 'failed' | 'cancelled' | 'other';
+    readonly errorCode: SafeErrorCode;
+}
+interface ImageApiMetricSnapshot {
+    readonly dimensions: ImageApiMetricDimensions;
+    readonly requests: number;
+    readonly inputCount?: ImageHistogramSnapshot;
+    readonly inputBytes?: ImageHistogramSnapshot;
+    readonly referenceOutcomes: Readonly<{
+        hits: number;
+        notFound: number;
+        expired: number;
+        failed: number;
+    }>;
+    readonly cleanupOutcomes: Readonly<{
+        completed: number;
+        failed: number;
+    }>;
+}
+interface ImageExecutionMetricSnapshot {
+    readonly dimensions: ImageExecutionMetricDimensions;
+    readonly executions: number;
+    readonly finalLatencyMs: ImageHistogramSnapshot;
+    readonly queueWaitMs?: ImageHistogramSnapshot;
+    readonly generationDurationMs?: ImageHistogramSnapshot;
+    readonly firstPartialLatencyMs?: ImageHistogramSnapshot;
+    readonly inputCount: ImageHistogramSnapshot;
+    readonly inputBytes: ImageHistogramSnapshot;
+    readonly outputCount: ImageHistogramSnapshot;
+    readonly outputBytes: ImageHistogramSnapshot;
+    readonly retryCount?: ImageHistogramSnapshot;
+    readonly authRefreshCount?: ImageHistogramSnapshot;
+    readonly referenceSaveCount?: ImageHistogramSnapshot;
+    readonly retentionRollbackFailures?: ImageHistogramSnapshot;
+}
+interface ImageObservabilitySnapshot {
+    readonly apiRequests: readonly ImageApiMetricSnapshot[];
+    readonly executions: readonly ImageExecutionMetricSnapshot[];
+    readonly configurationChanges: readonly ImageConfigurationAuditRecord[];
+    readonly overflow: Readonly<{
+        apiRecords: number;
+        telemetryRecords: number;
+    }>;
+}
+interface ImageObservabilityOptions {
+    /** Hard cap applied independently to API and execution dimension maps. */
+    readonly maxDimensionSets?: number;
+}
+/** Process-local, metadata-only aggregation for HTTP and hosted Images work. */
+declare class ImageObservability {
+    #private;
+    readonly telemetrySink: ImageTelemetrySink;
+    readonly audit: (record: ImageApiAuditRecord) => void;
+    constructor(options?: ImageObservabilityOptions);
+    recordApiAudit(record: ImageApiAuditRecord): void;
+    recordTelemetry(record: ImageTelemetryRecord): void;
+    recordConfigurationAudit(record: ImageConfigurationAuditRecord): void;
+    snapshot(): ImageObservabilitySnapshot;
+    reset(): void;
+}
+
+interface PreparedServerConfigChange {
+    /** Publish the prepared snapshot. Implementations should make this an infallible swap. */
+    publish(): void | Promise<void>;
+    /** Restore the exact runtime snapshot that preceded publish. */
+    rollback(): void | Promise<void>;
+    /** Release an unpublished or rolled-back replacement. */
+    dispose(): void | Promise<void>;
+}
+
 /**
  * autoDisableStore.ts — the daemon's PROCESS-IN-MEMORY auto-disable store.
  *
@@ -1684,9 +2129,16 @@ declare class ConfigFileProviderConfigSource implements ProviderConfigSource {
  * @module @omnicross/daemon/ports/JsonApiServerSettingsStore
  */
 
+interface JsonSettingsDocumentSnapshot {
+    readonly existed: boolean;
+    /** Raw persisted bytes; may contain encrypted secrets and must never enter a DTO or log. */
+    readonly bytes?: Uint8Array;
+}
+type AtomicDocumentReplace = (targetPath: string, contents: Uint8Array) => void;
 declare class JsonApiServerSettingsStore implements ApiServerSettingsStore {
     private readonly configPath;
     private readonly box;
+    private readonly atomicReplace;
     /**
      * @param configPath the daemon config.json whose `server` field is backed.
      * @param box         OPTIONAL at-rest `SecretBox` (upstream-proxy). When set, the
@@ -1695,9 +2147,13 @@ declare class JsonApiServerSettingsStore implements ApiServerSettingsStore {
      *                    secret-aware — every OTHER server field is non-secret). Null
      *                    ⇒ passthrough (legacy/pure tests unchanged).
      */
-    constructor(configPath: string, box?: SecretBox | null);
+    constructor(configPath: string, box?: SecretBox | null, atomicReplace?: AtomicDocumentReplace);
     get<T = unknown>(key: string): Promise<T | undefined>;
     set<T = unknown>(key: string, value: T): Promise<void>;
+    /** Capture the exact prior document for an admin transaction rollback. */
+    captureDocumentSnapshot(): JsonSettingsDocumentSnapshot;
+    /** Restore exact prior bytes (including unrelated fields and encrypted secrets). */
+    restoreDocumentSnapshot(snapshot: JsonSettingsDocumentSnapshot): void;
     /** Encrypt the proxy passwords + webhook + billing secrets before persisting (no-op without a box). */
     private encryptSecrets;
     /** Decrypt the proxy passwords + webhook + billing secrets on read (no-op without a box). */
@@ -1779,7 +2235,31 @@ declare class JsonPricingStore implements PricingStore {
     private replaceFile;
 }
 
+interface CodexAuthHelperConfig {
+    command: string;
+    args: string[];
+}
+
 type IntegrationClientId = 'codex' | 'claude';
+type IntegrationKeyOwnership = 'managed' | 'selected';
+/** Secret-free pointer to an access key. The plaintext remains in the encrypted key store. */
+interface IntegrationKeyBinding {
+    keyId: string;
+    ownership: IntegrationKeyOwnership;
+}
+/** Redacted access-key state exposed by the integrations admin API. */
+interface IntegrationKeyBindingStatus {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    ownership: IntegrationKeyOwnership;
+    revealable: boolean;
+    enabled: boolean;
+    revoked: boolean;
+    allowedEndpoints: OutboundPermission[];
+    requiredEndpoints: OutboundPermission[];
+    loopbackOnly: boolean;
+}
 type IntegrationStatusKind = 'not-installed' | 'enabled' | 'configuration-drift' | 'configuration-missing' | 'key-missing';
 interface IntegrationClientStatus {
     client: IntegrationClientId;
@@ -1788,6 +2268,8 @@ interface IntegrationClientStatus {
     installedAt?: number;
     gatewayBaseUrl?: string;
     message?: string;
+    /** Selected key metadata only; never contains plaintext or the encrypted envelope. */
+    key?: IntegrationKeyBindingStatus;
 }
 interface IntegrationChangePlan {
     client: IntegrationClientId;
@@ -1827,7 +2309,9 @@ interface IntegrationGatewayKeyRecord {
 }
 interface IntegrationState {
     version: 1;
+    /** Legacy shared-key layout. New installs use `keyBindings`; retained for safe migration. */
     gatewayKey?: IntegrationGatewayKeyRecord;
+    keyBindings?: Partial<Record<IntegrationClientId, IntegrationKeyBinding>>;
     clients: Partial<Record<IntegrationClientId, IntegrationInstallRecord>>;
 }
 
@@ -1845,27 +2329,38 @@ interface IntegrationManagerOptions {
     gatewayBaseUrl: string;
     keyDb: OutboundKeyDb;
     stateStore: IntegrationStateStore;
+    codexAuthHelper?: CodexAuthHelperConfig;
     homeDir?: string;
 }
-/** Coordinates a least-privilege gateway key with reversible native CLI config edits. */
+/** Coordinates per-client least-privilege keys with reversible native CLI config edits. */
 declare class IntegrationManager {
     private readonly options;
     private readonly homeDir;
+    private readonly codexAuthHelper;
     constructor(options: IntegrationManagerOptions);
     listStatus(): Promise<IntegrationClientStatus[]>;
     plan(client: IntegrationClientId, configPath?: string): Promise<IntegrationChangePlan>;
     install(client: IntegrationClientId, configPath?: string): Promise<IntegrationClientStatus>;
     repair(client: IntegrationClientId): Promise<IntegrationClientStatus>;
     remove(client: IntegrationClientId): Promise<IntegrationClientStatus>;
+    /** Bind a user-confirmed access key and grant only this client's required endpoints. */
+    bindIntegrationKey(client: IntegrationClientId, keyId: string): Promise<IntegrationClientStatus>;
+    /** Rotate every Omnicross-managed client binding; user-selected keys remain untouched. */
     rotateGatewayKey(): Promise<{
-        keyId: string;
+        keyIds: Partial<Record<IntegrationClientId, string>>;
     }>;
-    getGatewayToken(): Promise<string>;
-    private ensureGatewayKey;
-    private isKeyUsable;
+    /** Resolve the plaintext only for the command-auth helper; callers must not log it. */
+    getIntegrationToken(client: IntegrationClientId): Promise<string>;
+    /** Compatibility alias for callers predating per-client bindings. */
+    getGatewayToken(client?: IntegrationClientId): Promise<string>;
+    private ensureClientKey;
+    private createManagedClientKey;
+    private installedSecret;
+    private rebindInstalledClient;
     private statusFor;
+    private boundKeyDetails;
+    private retireManagedKeys;
     private defaultConfigPath;
-    private codexAuthPathForConfig;
     private renderInstalled;
 }
 
@@ -1985,6 +2480,11 @@ interface PoolKeyHealth {
 interface PoolHealthReader {
     getKeyHealth(providerId: string): Promise<Record<string, PoolKeyHealth>>;
 }
+interface AdminImagesStatusReader {
+    inspectCapability(apiKeyId: string): Promise<ImageRuntimeCapabilityInspection>;
+    status(): ImageRuntimeManagerStatus;
+    resourceStatus(): ImageRuntimeResourceStatus | undefined;
+}
 /** The live daemon handles the management API operates over. */
 interface AdminApiDeps {
     /** Path to the daemon's `config.json` (provider catalog + `server` field). */
@@ -2009,6 +2509,16 @@ interface AdminApiDeps {
     readonly settingsStore: JsonApiServerSettingsStore;
     /** The running outbound server (status + live applyConfig). */
     readonly outboundApiServer: OutboundApiServer;
+    /** True only when production composed the hardened per-hop remote resolver. */
+    readonly imageRemoteResolverAvailable?: boolean;
+    /** Optional production Images runtime generation participant. */
+    readonly imageRuntimeConfig?: {
+        prepareConfig(config: ImagesServerConfig): Promise<PreparedServerConfigChange>;
+    };
+    /** Narrow metadata-only reader for authenticated Images capability/status. */
+    readonly imageRuntimeStatus?: AdminImagesStatusReader;
+    /** Metadata-only successful Images configuration audit sink. */
+    readonly imageConfigAudit?: (record: ImageConfigurationAuditRecord) => void;
     /** Process-local machine-managed routing leases (optional for light embedders). */
     readonly routeLeaseManager?: RouteLeaseManager;
     /** Subscription accounts (token-free `listAll`). */
@@ -2233,9 +2743,673 @@ declare class AdminServer {
     getStatus(): AdminServerStatus;
 }
 
+type DaemonImagePathArea = 'temporary' | 'artifacts' | 'state' | 'evidence' | 'mountManifest';
+interface DaemonImagePaths {
+    readonly applicationDataRoot: string;
+    readonly imagesRoot: string;
+    readonly temporaryRoot: string;
+    readonly durableRoot: string;
+    readonly artifactsRoot: string;
+    readonly stateRoot: string;
+    readonly evidenceRoot: string;
+    readonly mountManifestRoot: string;
+    readonly mountManifestPath: string;
+}
+interface ImageRootValidationOptions {
+    readonly label?: string;
+    readonly processDirectory?: string;
+    readonly userHome?: string;
+    readonly temporaryDirectory?: string;
+}
+interface CreateDaemonImagePathResolverOptions extends ImageRootValidationOptions {
+    readonly configPath: string;
+    readonly storageRoot?: string;
+}
+interface VerifiedDaemonImagePath {
+    readonly area: DaemonImagePathArea;
+    readonly absolutePath: string;
+    readonly kind: 'opaque-file' | 'opaque-directory' | 'mount-manifest';
+}
+/**
+ * Owns all daemon Images filesystem names. Callers receive opaque capabilities,
+ * never a filename-accepting delete primitive; destructive methods revalidate
+ * the root identity, descendant relationship, basename, and symlink state.
+ */
+declare class DaemonImagePathResolver {
+    #private;
+    readonly paths: DaemonImagePaths;
+    constructor(options: CreateDaemonImagePathResolverOptions);
+    createOpaqueFile(area: Exclude<DaemonImagePathArea, 'temporary' | 'mountManifest'>, format?: 'bin' | 'json' | 'tmp'): VerifiedDaemonImagePath;
+    createOpaqueDirectory(area?: Exclude<DaemonImagePathArea, 'mountManifest'>): VerifiedDaemonImagePath;
+    mountManifest(): VerifiedDaemonImagePath;
+    /** Revalidate and return one internal root for store-local bounded I/O. */
+    verifiedRoot(area: DaemonImagePathArea): string;
+    /** Revalidate immediately before unlinking a resolver-issued file capability. */
+    removeFile(target: VerifiedDaemonImagePath): void;
+    /** Only empty opaque directories may be removed until the owned-marker layer is composed. */
+    removeEmptyDirectory(target: VerifiedDaemonImagePath): void;
+    private issue;
+    private verifyDestructiveTarget;
+}
+
+interface FileCodexImageCapabilityEvidenceManifestOwnerOptions {
+    readonly paths: DaemonImagePathResolver;
+    readonly maxEntries?: number;
+    readonly now?: () => number;
+    readonly random?: (bytes: number) => Buffer;
+    readonly hmacSalt?: Uint8Array;
+    readonly replaceManifest?: (targetPath: string, contents: Uint8Array) => void;
+}
+type FileCodexImageCapabilityEvidenceSourceOptions = Readonly<(FileCodexImageCapabilityEvidenceManifestOwnerOptions & {
+    readonly ttlMs: number;
+}) | {
+    readonly owner: FileCodexImageCapabilityEvidenceManifestOwner;
+    readonly ttlMs: number;
+}>;
+interface FileCodexImageCapabilityEvidenceStatus {
+    readonly entries: number;
+    readonly freshEntries: number;
+    readonly staleEntries: number;
+    readonly bytes: number;
+}
+/** Revision-aware manifest owner shared by runtime generations, doctor, and cleanup. */
+declare class FileCodexImageCapabilityEvidenceManifestOwner {
+    #private;
+    constructor(options: FileCodexImageCapabilityEvidenceManifestOwnerOptions);
+    createSource(ttlMs: number): FileCodexImageCapabilityEvidenceSource;
+    resolveWithTtl(request: CodexImageCapabilityEvidenceRequest, ttlMs: number): Promise<CodexImageCapabilityEvidence>;
+    recordSuccessfulVerificationWithTtl(observation: CodexImageCapabilityObservation, ttlMs: number): Promise<void>;
+    cleanup(now: number, limit: number): Promise<{
+        readonly entriesRemoved: number;
+        readonly bytesRemoved: number;
+    }>;
+    statusWithTtl(ttlMs: number): FileCodexImageCapabilityEvidenceStatus;
+}
+/** Immutable TTL view over a revision-aware file-backed evidence manifest owner. */
+declare class FileCodexImageCapabilityEvidenceSource implements CodexImageCapabilityEvidenceSource {
+    #private;
+    constructor(options: FileCodexImageCapabilityEvidenceSourceOptions);
+    createView(ttlMs: number): FileCodexImageCapabilityEvidenceSource;
+    resolve(request: CodexImageCapabilityEvidenceRequest): Promise<CodexImageCapabilityEvidence>;
+    recordSuccessfulVerification(observation: CodexImageCapabilityObservation): Promise<void>;
+    cleanup(now: number, limit: number): Promise<{
+        readonly entriesRemoved: number;
+        readonly bytesRemoved: number;
+    }>;
+    status(): FileCodexImageCapabilityEvidenceStatus;
+    ttlMs(): number;
+    /** Lifecycle-symmetric no-op; physical safety no longer depends on local leases. */
+    dispose(): void;
+}
+
+interface FileImageReferenceStoreLimits {
+    readonly ttlMs: number;
+    readonly maxArtifactBytes: number;
+    readonly maxTotalBytes: number;
+    readonly maxTenantBytes: number;
+    readonly maxEntries: number;
+    readonly maxTombstones: number;
+    readonly tombstoneTtlMs: number;
+}
+interface FileImageReferenceStoreOptions {
+    readonly paths: DaemonImagePathResolver;
+    readonly limits: FileImageReferenceStoreLimits;
+    readonly secretBox?: SecretBox;
+    readonly now?: () => number;
+    readonly random?: (bytes: number) => Buffer;
+    readonly replaceManifest?: (targetPath: string, contents: Uint8Array) => void;
+}
+interface FileImageReferenceReconciliationResult {
+    readonly metadataRemoved: number;
+    readonly metadataDegradedToProviderReference: number;
+    readonly orphanFilesRemoved: number;
+    readonly incompleteFilesRemoved: number;
+    readonly invalidDescendants: number;
+}
+declare class FileImageReferenceStore implements ImageReferenceStore {
+    #private;
+    constructor(options: FileImageReferenceStoreOptions);
+    save(input: ImageReferenceSaveInput): Promise<ImageReferenceMetadata>;
+    /** Generation-bound write entry point; reads and maintenance remain shared. */
+    saveWithLimits(input: ImageReferenceSaveInput, limits: FileImageReferenceStoreLimits): Promise<ImageReferenceMetadata>;
+    /** Updates only app-session maintenance policy; pinned writes pass their own limits. */
+    updateMaintenanceLimits(limits: FileImageReferenceStoreLimits): void;
+    resolve(tenantId: string, referenceId: ImageReferenceId): Promise<ImageReferenceResolution>;
+    delete(tenantId: string, referenceId: ImageReferenceId): Promise<boolean>;
+    /** Daemon-internal cleanup path; accepts only the local reference-domain tenant HMAC. */
+    deleteByHashedTenantKey(tenantKey: string, referenceId: ImageReferenceId): Promise<boolean>;
+    cleanup(now?: number): Promise<number>;
+    status(): {
+        readonly entries: number;
+        readonly bytes: number;
+        readonly tombstones: number;
+    };
+    hasLiveReferenceByHashedTenantKey(tenantKey: string, referenceId: ImageReferenceId, now?: number): Promise<boolean>;
+    reconcileOwnedFiles(maxEntries: number): Promise<FileImageReferenceReconciliationResult>;
+    openArtifact(fileName: string, byteLength: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    private exclusive;
+    private tenantKey;
+    private newReferenceId;
+    private validateSaveInput;
+    private selectVictims;
+    private nextTombstones;
+    private writeArtifact;
+    private artifactPath;
+    private validArtifact;
+    private removeArtifact;
+    private safeUnlinkArtifactPath;
+    private releaseLease;
+    private manifestPath;
+    private persist;
+    private atomicReplace;
+    private loadManifest;
+}
+
+interface FileResponsesImageStateStoreLimits {
+    readonly maxCalls: number;
+    readonly maxResponses: number;
+    readonly maxTombstones: number;
+    readonly tombstoneTtlMs: number;
+}
+interface FileResponsesImageStateStoreOptions {
+    readonly paths: DaemonImagePathResolver;
+    readonly limits: FileResponsesImageStateStoreLimits;
+    readonly now?: () => number;
+    readonly random?: (bytes: number) => Buffer;
+    readonly replaceManifest?: (targetPath: string, contents: Uint8Array) => void;
+}
+interface PendingResponsesImageReferenceDelete {
+    readonly referenceTenantKey: string;
+    readonly binding: ResponsesImageCallBinding;
+}
+/** Durable production implementation of the existing Responses image-state contract. */
+declare class FileResponsesImageStateStore implements ResponsesImageStateStore {
+    #private;
+    constructor(options: FileResponsesImageStateStoreOptions);
+    commit(input: ResponsesImageStateCommitInput): Promise<readonly ResponsesImageCallBinding[]>;
+    /** Generation-bound write entry point; reads and maintenance remain shared. */
+    commitWithLimits(input: ResponsesImageStateCommitInput, limits: FileResponsesImageStateStoreLimits): Promise<readonly ResponsesImageCallBinding[]>;
+    /** Updates only app-session maintenance policy; pinned commits pass their own limits. */
+    updateMaintenanceLimits(limits: FileResponsesImageStateStoreLimits): void;
+    resolveCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallResolution>;
+    resolveResponse(tenantId: string, responseId: string): Promise<ResponsesImageResponseResolution>;
+    deleteCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallBinding | undefined>;
+    deleteResponse(tenantId: string, responseId: string): Promise<boolean>;
+    cleanup(now?: number): Promise<readonly ResponsesImageCallBinding[]>;
+    pendingReferenceDeletes(limit?: number): readonly PendingResponsesImageReferenceDelete[];
+    acknowledgeReferenceDeletes(completed: readonly PendingResponsesImageReferenceDelete[]): Promise<number>;
+    reconcileBrokenReferenceLinks(hasLiveReference: (referenceTenantKey: string, referenceId: ResponsesImageCallBinding['referenceId']) => Promise<boolean>, maxEntries: number): Promise<readonly ResponsesImageCallBinding[]>;
+    status(): {
+        readonly calls: number;
+        readonly responses: number;
+        readonly tombstones: number;
+        readonly pendingReferenceDeletes: number;
+    };
+    private exclusive;
+    private failure;
+    private assertCommit;
+    private tenantKey;
+    private rememberTombstone;
+    private enqueuePendingReferenceDelete;
+    private hasTombstone;
+    private prunedTombstones;
+    private pruneTombstonesInPlace;
+    private sameTombstones;
+    private touch;
+    private releaseCall;
+    private releaseResponse;
+    private manifestPath;
+    private persist;
+    private atomicReplace;
+    private loadManifest;
+}
+
+interface ImageStorageMountBackend {
+    readonly id: string;
+    readonly createdAt: number;
+    readonly resolver: DaemonImagePathResolver;
+    readonly references: FileImageReferenceStore;
+    readonly responsesState: FileResponsesImageStateStore;
+}
+interface ImageStorageMountCatalogOptions {
+    readonly pathOptions: Omit<CreateDaemonImagePathResolverOptions, 'storageRoot'>;
+    readonly activeStorageRoot?: string;
+    readonly referenceLimits: FileImageReferenceStoreLimits;
+    readonly responsesStateLimits: FileResponsesImageStateStoreLimits;
+    readonly secretBox?: SecretBox;
+    readonly now?: () => number;
+    readonly random?: (bytes: number) => Buffer;
+    readonly replaceCatalog?: (targetPath: string, contents: Uint8Array) => void;
+    readonly reconcileCorruptManifests?: boolean;
+}
+interface ImageStorageMountPolicy {
+    readonly referenceLimits: FileImageReferenceStoreLimits;
+    readonly responsesStateLimits: FileResponsesImageStateStoreLimits;
+}
+interface PreparedImageStorageMountActivation {
+    readonly backend: ImageStorageMountBackend;
+    publish(): ImageStorageMountBackend;
+    rollback(): void;
+    dispose(): void;
+}
+/** Owns the durable-root set independently from any one runtime generation. */
+declare class ImageStorageMountCatalog {
+    #private;
+    constructor(options: ImageStorageMountCatalogOptions);
+    active(): ImageStorageMountBackend;
+    mountsForRead(): readonly ImageStorageMountBackend[];
+    status(): {
+        readonly mounts: number;
+        readonly retiredMounts: number;
+    };
+    startupReconciliationStatus(): {
+        readonly corruptManifestsQuarantined: number;
+    };
+    utilization(): {
+        readonly referenceEntries: number;
+        readonly referenceBytes: number;
+        readonly referenceTombstones: number;
+        readonly stateCalls: number;
+        readonly stateResponses: number;
+        readonly stateTombstones: number;
+        readonly pendingReferenceDeletes: number;
+    };
+    /** Pins a backend object until its owning runtime generation drains. */
+    retainBackend(backend: ImageStorageMountBackend): () => void;
+    activate(storageRoot?: string): ImageStorageMountBackend;
+    /** Prepare a validated backend without changing the catalog's active mount. */
+    prepareActivation(storageRoot?: string, policy?: ImageStorageMountPolicy): PreparedImageStorageMountActivation;
+    retireEmptyMount(mountId: string): boolean;
+    private createResolver;
+    private createBackend;
+    private applyMaintenancePolicy;
+    private newMountId;
+    private isManifestError;
+    private quarantineManifest;
+    private isVerifiedEmpty;
+    private catalogPath;
+    private persist;
+    private atomicReplace;
+    private loadCatalog;
+}
+declare class MountedImageReferenceStore implements ImageReferenceStore {
+    private readonly catalog;
+    private readonly writeBackend?;
+    private readonly writeLimits?;
+    constructor(catalog: ImageStorageMountCatalog, writeBackend?: ImageStorageMountBackend | undefined, writeLimits?: FileImageReferenceStoreLimits | undefined);
+    bindWriteBackend(backend: ImageStorageMountBackend, limits: FileImageReferenceStoreLimits): MountedImageReferenceStore;
+    status(): Readonly<{
+        referenceEntries: number;
+        referenceBytes: number;
+        referenceTombstones: number;
+        stateCalls: number;
+        stateResponses: number;
+        stateTombstones: number;
+        pendingReferenceDeletes: number;
+        mounts: number;
+        retiredMounts: number;
+    }>;
+    save(input: ImageReferenceSaveInput): Promise<_omnicross_contracts_image_generation_types.ImageReferenceMetadata>;
+    resolve(tenantId: string, referenceId: ImageReferenceId): Promise<ImageReferenceResolution>;
+    delete(tenantId: string, referenceId: ImageReferenceId): Promise<boolean>;
+    deleteByHashedTenantKey(tenantKey: string, referenceId: ImageReferenceId): Promise<boolean>;
+    cleanup(now?: number): Promise<number>;
+}
+declare class MountedResponsesImageStateStore implements ResponsesImageStateStore {
+    private readonly catalog;
+    private readonly writeBackend?;
+    private readonly writeLimits?;
+    constructor(catalog: ImageStorageMountCatalog, writeBackend?: ImageStorageMountBackend | undefined, writeLimits?: FileResponsesImageStateStoreLimits | undefined);
+    bindWriteBackend(backend: ImageStorageMountBackend, limits: FileResponsesImageStateStoreLimits): MountedResponsesImageStateStore;
+    commit(input: ResponsesImageStateCommitInput): Promise<readonly ResponsesImageCallBinding[]>;
+    resolveCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallResolution>;
+    resolveResponse(tenantId: string, responseId: string): Promise<ResponsesImageResponseResolution>;
+    deleteCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallBinding | undefined>;
+    deleteResponse(tenantId: string, responseId: string): Promise<boolean>;
+    cleanup(now?: number): Promise<readonly ResponsesImageCallBinding[]>;
+}
+
+interface ImageDoctorLocalSnapshot {
+    readonly config: Readonly<{
+        enabled: boolean;
+        provider: 'codex-subscription';
+        model: string;
+        valid: boolean;
+        errorCount: number;
+    }>;
+    readonly roots: Readonly<{
+        valid: boolean;
+        verifiedAreas: number;
+        expectedAreas: number;
+    }>;
+    readonly stores: Readonly<{
+        valid: boolean;
+        mounts: number;
+        retiredMounts: number;
+        referenceEntries: number;
+        referenceBytes: number;
+        stateCalls: number;
+        stateResponses: number;
+        corruptManifestsQuarantined: number;
+    }>;
+    readonly permissions: Readonly<{
+        valid: boolean;
+        rows: number;
+        legacyRows: number;
+        invalidRows: number;
+        imagesAuthorizedRows: number;
+    }>;
+    readonly account: Readonly<{
+        present: boolean;
+        usable: boolean;
+        reason: 'ready' | 'missing' | 'unavailable';
+    }>;
+    readonly evidence: Readonly<FileCodexImageCapabilityEvidenceStatus & {
+        valid: boolean;
+    }>;
+}
+type ImageDoctorLiveFailureCode = 'images_disabled' | 'codex_account_unavailable' | 'evidence_store_unavailable' | 'evidence_persist_failed' | ImageGenerationErrorCode;
+type ImageDoctorLiveResult = Readonly<{
+    ok: true;
+    code: 'verified';
+    model: 'gpt-image-2';
+    quality: 'low';
+    outputFormat: 'png';
+    freshEvidenceEntries: number;
+}> | Readonly<{
+    ok: false;
+    code: ImageDoctorLiveFailureCode;
+}>;
+interface ImageDoctorService {
+    inspectLocal(config: ImagesServerConfig): Promise<ImageDoctorLocalSnapshot>;
+    verifyLive(config: ImagesServerConfig, signal: AbortSignal): Promise<ImageDoctorLiveResult>;
+}
+
+interface ImageTemporaryBudgetStatus {
+    readonly activeScopes: number;
+    readonly totalBytes: number;
+    readonly tenantCount: number;
+}
+/** Process-local atomic budget shared by every scope in one pinned runtime generation. */
+declare class DaemonImageTemporaryBudget implements ImageTemporaryResourceBudget {
+    #private;
+    constructor(config: ImagesServerConfig['temporary']);
+    acquireScope(tenantId: string): ImageTemporaryResourceBudgetLease;
+    status(): ImageTemporaryBudgetStatus;
+}
+interface DaemonImageTemporaryResourceFactoryOptions {
+    readonly paths: DaemonImagePathResolver;
+    readonly config: ImagesServerConfig['temporary'];
+    readonly activeScopes?: DaemonImageActiveScopeRegistry;
+}
+/** App-session registry shared by all runtime generations and recurring cleanup. */
+declare class DaemonImageActiveScopeRegistry {
+    #private;
+    constructor(paths: DaemonImagePathResolver);
+    register(privateDirectory: string): () => void;
+    isActive(privateDirectory: string): boolean;
+    status(): {
+        readonly activeDirectories: number;
+    };
+}
+/** Binds the private root, fixed owner marker, tenant, and shared budget in one seam. */
+declare class DaemonImageTemporaryResourceFactory {
+    #private;
+    readonly budget: DaemonImageTemporaryBudget;
+    constructor(options: DaemonImageTemporaryResourceFactoryOptions);
+    readonly createResourceScope: (limits: ImageApiLimits, signal: AbortSignal, tenantId: string) => Promise<ImageRequestResourceScope>;
+}
+
+interface ImageStartupReconcilerOptions {
+    readonly catalog: ImageStorageMountCatalog;
+    readonly temporaryPaths: DaemonImagePathResolver;
+    readonly staleTemporaryAfterMs: number;
+    readonly activeTemporaryScopes?: Pick<DaemonImageActiveScopeRegistry, 'isActive'>;
+    readonly maxMountsPerPass?: number;
+    readonly maxEntriesPerMount?: number;
+    readonly maxTemporaryDirectoriesPerPass?: number;
+    readonly now?: () => number;
+}
+interface ImageStartupReconciliationResult {
+    readonly corruptManifestsQuarantined: number;
+    readonly mountsVisited: number;
+    readonly stateBindingsRemoved: number;
+    readonly brokenBindingsRemoved: number;
+    readonly referenceEntriesRemoved: number;
+    readonly metadataRemoved: number;
+    readonly metadataDegradedToProviderReference: number;
+    readonly orphanFilesRemoved: number;
+    readonly incompleteFilesRemoved: number;
+    readonly transactionFilesRemoved: number;
+    readonly temporaryDirectoriesRemoved: number;
+    readonly foreignTemporaryDirectoriesSkipped: number;
+    readonly activeTemporaryDirectoriesSkipped: number;
+    readonly invalidDescendantsSkipped: number;
+    readonly pendingReferenceDeletes: number;
+}
+/** One bounded, synchronous-filesystem startup pass; it never follows symlinks. */
+declare class ImageStartupReconciler {
+    #private;
+    constructor(options: ImageStartupReconcilerOptions);
+    run(): Promise<ImageStartupReconciliationResult>;
+    private hasLiveReference;
+    private removeTransactionFiles;
+    private removeStaleTemporaryDirectories;
+    private removeTreeWithoutFollowingSymlinks;
+}
+
+interface BoundedImageEvidenceCleanup {
+    cleanup(now: number, limit: number): Promise<{
+        readonly entriesRemoved: number;
+        readonly bytesRemoved: number;
+    }>;
+}
+interface ImageCleanupTimer {
+    unref(): unknown;
+}
+interface ImageCleanupServiceOptions {
+    readonly reconciler: ImageStartupReconciler;
+    readonly catalog: ImageStorageMountCatalog;
+    readonly intervalMs: number;
+    readonly maxEvidenceEntriesPerPass?: number;
+    readonly maxRetiredMountsPerPass?: number;
+    readonly evidence?: BoundedImageEvidenceCleanup;
+    readonly now?: () => number;
+    readonly scheduleInterval?: (callback: () => void, intervalMs: number) => ImageCleanupTimer;
+    readonly clearScheduledInterval?: (timer: ImageCleanupTimer) => void;
+}
+interface ImageCleanupPolicy {
+    readonly reconciler: ImageStartupReconciler;
+    readonly intervalMs: number;
+    readonly evidence?: BoundedImageEvidenceCleanup;
+}
+interface PreparedImageCleanupPolicyChange {
+    publish(): void;
+    rollback(): void;
+    dispose(): void;
+}
+interface ImageCleanupServicePassResult {
+    readonly stateBindingsRemoved: number;
+    readonly brokenBindingsRemoved: number;
+    readonly referenceEntriesRemoved: number;
+    readonly orphanFilesRemoved: number;
+    readonly incompleteFilesRemoved: number;
+    readonly transactionFilesRemoved: number;
+    readonly temporaryDirectoriesRemoved: number;
+    readonly evidenceEntriesRemoved: number;
+    readonly evidenceBytesRemoved: number;
+    readonly evidenceCleanupFailures: number;
+    readonly retiredMountsRemoved: number;
+    readonly referenceEntries: number;
+    readonly referenceBytes: number;
+    readonly referenceTombstones: number;
+    readonly stateCalls: number;
+    readonly stateResponses: number;
+    readonly stateTombstones: number;
+    readonly pendingReferenceDeletes: number;
+    readonly finishedAt: number;
+}
+interface ImageCleanupServiceStatus extends ImageCleanupServicePassResult {
+    readonly running: boolean;
+    readonly passesCompleted: number;
+    readonly passFailures: number;
+}
+/** Unref'ed recurring lifecycle owner with one non-overlapping bounded pass. */
+declare class ImageCleanupService {
+    #private;
+    constructor(options: ImageCleanupServiceOptions);
+    start(): void;
+    private schedule;
+    /** Prepares a hot-reloadable cadence/reconciler/evidence snapshot. */
+    preparePolicy(policy: ImageCleanupPolicy): PreparedImageCleanupPolicyChange;
+    stop(): Promise<void>;
+    reset(): Promise<void>;
+    runOnce(): Promise<ImageCleanupServicePassResult>;
+    status(): ImageCleanupServiceStatus;
+    private performPass;
+}
+
+interface TrustedImageApiRuntimeResolverOptions {
+    readonly config: ImagesServerConfig;
+    readonly referenceStore: ImageReferenceStore;
+    /** Persistent private daemon key material. It is copied on construction. */
+    readonly hmacKey: Uint8Array;
+    /** Present only when the host has proved the complete remote-fetch policy. */
+    readonly provenRemoteResolver?: RemoteImageAssetResolver;
+}
+interface TrustedImageApiRuntimeResolver {
+    readonly resolve: ImageApiRuntimeResolver;
+    dispose(): void;
+}
+/**
+ * Resolves only daemon-authenticated route state. Named outbound keys retain
+ * their stable key-id tenant; ephemeral Route Lease traffic falls back to the
+ * authenticated lease id and remains isolated from other leases. Request
+ * headers, including an inbound bearer, are deliberately outside the resolver's
+ * identity inputs.
+ */
+declare function createTrustedImageApiRuntimeResolver(options: TrustedImageApiRuntimeResolverOptions): TrustedImageApiRuntimeResolver;
+
+interface DaemonImageExecutionSchedulerOptions {
+    readonly config: ImagesServerConfig['queue'];
+    /** Persistent private daemon key material; copied on construction. */
+    readonly hmacKey: Uint8Array;
+}
+interface DaemonImageExecutionSchedulerStatus {
+    readonly activeJobs: number;
+    readonly waitingJobs: number;
+    readonly activeAccounts: number;
+    readonly waitingAccounts: number;
+    readonly waitingTenants: number;
+    readonly maxConcurrentJobsPerAccount: number;
+    readonly maxQueuedJobs: number;
+    readonly accepting: boolean;
+    readonly shuttingDown: boolean;
+}
+/**
+ * Snapshot-bound image admission with per-account active caps and fair tenant
+ * rotation under one bounded global waiting population.
+ */
+declare class DaemonImageExecutionScheduler implements ImageExecutionScheduler {
+    #private;
+    constructor(options: DaemonImageExecutionSchedulerOptions);
+    deriveAccountKey(selectedAccountId: string): ImageExecutionAccountKey;
+    acquire(request: ImageExecutionSchedulerRequest): Promise<ImageExecutionSchedulerGrant>;
+    status(): DaemonImageExecutionSchedulerStatus;
+    /** Stop new admissions while allowing already queued and active work to drain. */
+    retire(): void;
+    /** Reject waiters and cancel active grants. Safe to call repeatedly. */
+    shutdown(): void;
+}
+
+interface ImageRuntimeGenerationSharedStorage {
+    /** Resolver associated with the catalog's already-active mount. */
+    readonly paths: DaemonImagePathResolver;
+    readonly referenceStore: MountedImageReferenceStore;
+    readonly stateStore: MountedResponsesImageStateStore;
+}
+interface ImageRuntimeMetadataObservability {
+    readonly telemetrySink?: ImageTelemetrySink;
+    readonly audit?: (record: ImageApiAuditRecord) => void | Promise<void>;
+}
+/**
+ * Explicit deterministic Tier-A seam. It replaces only the provider inside an
+ * otherwise-production runtime generation and is never inferred from config.
+ */
+interface SyntheticVerifiedImageProviderTestSeam {
+    readonly label: 'synthetic-verified-image-provider-test-only';
+    createProvider(context: Readonly<{
+        generationId: string;
+        scheduler: ImageExecutionScheduler;
+        now: () => number;
+        referenceStore: MountedImageReferenceStore;
+        stateStore: MountedResponsesImageStateStore;
+    }>): ImageProvider;
+}
+interface ImageRuntimeGenerationFactoryOptions {
+    readonly generationId: string;
+    readonly config: ImagesServerConfig;
+    readonly subscriptionAccounts: Pick<SubscriptionAccountService, 'getStrategy'>;
+    readonly storage: ImageRuntimeGenerationSharedStorage;
+    readonly provenRemoteResolver?: RemoteImageAssetResolver;
+    readonly observability?: ImageRuntimeMetadataObservability;
+    readonly createRequestId?: () => string;
+    readonly createCallId?: () => `ig_${string}`;
+    readonly now?: () => number;
+    /** Test seam; production loads the persistent daemon-local HMAC salt. */
+    readonly privateHmacKey?: Uint8Array;
+    /** App-session owner used to protect live directories across generations. */
+    readonly activeTemporaryScopes?: DaemonImageActiveScopeRegistry;
+    /** Immutable TTL view scoped to this runtime generation. */
+    readonly evidenceSource?: FileCodexImageCapabilityEvidenceSource;
+    /** App-session catalog lease retained until this generation is disposed. */
+    readonly releaseStorageBackend?: () => void;
+    /** Test-only Tier-A provider; production leaves this absent. */
+    readonly testOnlySyntheticVerifiedProvider?: SyntheticVerifiedImageProviderTestSeam;
+}
+interface ProductionImageRuntimeComponents {
+    readonly providerRegistry: ImageProviderRegistry;
+    readonly orchestrator: ImageOrchestrator;
+    readonly scheduler: DaemonImageExecutionScheduler;
+    readonly evidenceSource: FileCodexImageCapabilityEvidenceSource;
+    readonly temporaryResources: DaemonImageTemporaryResourceFactory;
+    readonly runtimeResolver: TrustedImageApiRuntimeResolver;
+    readonly referenceStore: MountedImageReferenceStore;
+    readonly stateStore: MountedResponsesImageStateStore;
+}
+type ProductionImageRuntimeGeneration = PreparedImageRuntimeGeneration & {
+    readonly components?: ProductionImageRuntimeComponents;
+};
+/**
+ * Builds a complete generation without changing the storage catalog's active
+ * mount. Catalog activation must be composed by a failure-atomic transaction.
+ */
+declare function createImageRuntimeGeneration(options: ImageRuntimeGenerationFactoryOptions): ProductionImageRuntimeGeneration;
+
+/**
+ * JsonOutboundKeyDb — the daemon's file-backed `OutboundKeyDb` port impl
+ * (design D3).
+ *
+ * Durable storage for named outbound API keys, backed by a json file (a sibling
+ * of `config.json`, e.g. `keys.json`) holding an `OutboundKeyDbRow[]`. This port
+ * provides ONLY storage — it never generates secrets nor hashes. Core's
+ * `createNamedKey(db, name)` calls `outboundApiKeysCreate` with the sha256
+ * `keyHash` + display `keyPrefix` and returns the one-time plaintext; the hot
+ * auth path uses core's `hashKey(presented)` + `outboundApiKeysGetByHash`.
+ *
+ * OPTIONAL reversible storage: when constructed with a `SecretBox`, each created
+ * key ALSO persists its plaintext as a `keySecret` `enc:` envelope, powering the
+ * operator "view key" affordance (`outboundApiKeysReveal`). The hash remains the
+ * auth index; without a box the store is hash-only (byte-identical to legacy).
+ *
+ * @module @omnicross/daemon/ports/JsonOutboundKeyDb
+ */
+
+type AtomicFileReplace = (targetPath: string, contents: string) => void;
 declare class JsonOutboundKeyDb implements OutboundKeyDb {
     private readonly keysPath;
     private readonly secretBox?;
+    private readonly atomicReplace;
     /**
      * @param secretBox OPTIONAL reversible-secret codec. When present, a created
      * key's plaintext is persisted as a `keySecret` `enc:` envelope (enabling the
@@ -2244,7 +3418,7 @@ declare class JsonOutboundKeyDb implements OutboundKeyDb {
      * always returns `null`. Existing 1-arg call sites (tests, lightweight
      * embedders) keep working.
      */
-    constructor(keysPath: string, secretBox?: SecretBox | undefined);
+    constructor(keysPath: string, secretBox?: SecretBox | undefined, atomicReplace?: AtomicFileReplace);
     outboundApiKeysList(): Promise<OutboundKeyDbRow[]>;
     outboundApiKeysGetByHash(hash: string): Promise<OutboundKeyDbRow | null>;
     outboundApiKeysCreate(input: {
@@ -2254,7 +3428,7 @@ declare class JsonOutboundKeyDb implements OutboundKeyDb {
         keyPrefix: string;
         createdAt?: number;
         kind?: 'client' | 'integration';
-        allowedEndpoints?: _omnicross_core.OutboundEndpoint[];
+        allowedEndpoints?: OutboundPermission[];
         loopbackOnly?: boolean;
         plaintext?: string;
     }): Promise<OutboundKeyDbRow>;
@@ -2263,6 +3437,7 @@ declare class JsonOutboundKeyDb implements OutboundKeyDb {
     outboundApiKeysRevoke(id: string): Promise<boolean>;
     outboundApiKeysTouchLastUsed(id: string): Promise<boolean>;
     outboundApiKeysSetEnabled(id: string, enabled: boolean): Promise<boolean>;
+    outboundApiKeysSetPermissions(id: string, permissions: OutboundPermission[]): Promise<boolean>;
     outboundApiKeysSetMaxConcurrency(id: string, maxConcurrency: number | null): Promise<boolean>;
     outboundApiKeysSetPolicy(id: string, policy: OutboundKeyPolicy): Promise<boolean>;
     outboundApiKeysMarkActivated(id: string, activatedAt: number): Promise<boolean>;
@@ -2424,6 +3599,52 @@ declare class AuditPruneSweeper {
     private archiveDay;
 }
 
+/**
+ * usageMigrate — the ONE-SHOT fold of the legacy flat `usage-events.jsonl` into
+ * per-LOCAL-day shards plus their immutable rollups.
+ *
+ * Runs at bootstrap, BEFORE any listener is bound, so no request can be served
+ * against a half-migrated store. It streams: the legacy file is never held in
+ * memory as one string (that is the exact shape that put the old store on course
+ * for V8's ~512 MB string ceiling), and each day's rollup is accumulated during
+ * the same pass that writes its shard, so the whole migration is a single read.
+ *
+ * Writes are BATCHED per day (see {@link FLUSH_BYTES}). Awaiting a write per row
+ * turned 199k rows into ~17 s of boot on a real 157 MB store, which the desktop
+ * shell — waiting on the admin port — is right to find suspicious; batching cuts
+ * it to a few seconds without changing what lands on disk.
+ *
+ * CRASH SAFETY. Everything is built inside `usage/.migrating/` and only moved
+ * into place once the row count reconciles. A crash before the commit leaves the
+ * legacy file untouched and the scratch directory to be wiped and rebuilt on the
+ * next attempt. A crash DURING the commit leaves some shards in place and the
+ * legacy file still present; the next attempt refuses to run (a target shard
+ * already exists) and says so, rather than overwriting or double-counting rows.
+ *
+ * RECONCILIATION is the point of the exercise: `linesRead` must equal
+ * `rowsWritten + skipped`, where `skipped` is lines the shared row guard rejects.
+ * If it does not, nothing is committed and the legacy file stays exactly where it
+ * was. Silently losing usage rows would corrupt lifetime key spend, which is the
+ * one number in this store that can never be reconstructed.
+ *
+ * @module @omnicross/daemon/usage/usageMigrate
+ */
+
+interface UsageMigrationResult {
+    /** True only when the legacy file was folded in and removed. */
+    migrated: boolean;
+    /** Non-empty lines read from the legacy file. */
+    linesRead: number;
+    /** Rows that passed the guard and were written to a shard. */
+    rowsWritten: number;
+    /** Lines the guard rejected (torn tail, hand-edited, foreign writer). */
+    skipped: number;
+    /** Distinct LOCAL days produced. */
+    days: number;
+    /** Present when the migration declined or aborted; nothing was committed. */
+    reason?: string;
+}
+
 /**
  * AuditWriter — the daemon's file-backed audit sink (request-audit-log design
  * D4/D5, re-laid-out by audit-store-sharding design D2). Registered as
@@ -2824,6 +4045,16 @@ interface DaemonPaths {
      * never invoke a real package manager. Absent → the real `exec`-based runner.
      */
     cliCommandRunner?: CommandRunner;
+    /** TEST/COMPOSITION SEAM: prepared Images runtime generation for config transactions. */
+    imageRuntimeConfig?: AdminApiDeps['imageRuntimeConfig'];
+    /** TEST/COMPOSITION SEAM: metadata-only Images status reader. */
+    imageRuntimeStatus?: AdminApiDeps['imageRuntimeStatus'];
+    /** TEST/COMPOSITION SEAM: metadata-only successful Images config audit sink. */
+    imageConfigAudit?: AdminApiDeps['imageConfigAudit'];
+    /** TEST ONLY: deterministic Tier-A provider inside the production Images composition. */
+    testOnlySyntheticVerifiedImageProvider?: SyntheticVerifiedImageProviderTestSeam;
+    /** TEST SEAM: inject an atomic settings replacement fault. */
+    settingsAtomicReplace?: (targetPath: string, contents: Uint8Array) => void;
 }
 /** The constructed daemon handles the CLI commands operate on. */
 interface Daemon {
@@ -2832,6 +4063,18 @@ interface Daemon {
     readonly llmConfig: ConfigFileProviderConfigSource;
     readonly keyDb: JsonOutboundKeyDb;
     readonly settingsStore: JsonApiServerSettingsStore;
+    /** App-session extension-operation registry shared with the resident proxy. */
+    readonly openAIOperationRegistry: OpenAIOperationRegistry;
+    /** Stable Images forwarders and generation lifecycle owner for this app session. */
+    readonly imageRuntimeManager: ImageRuntimeManager;
+    /** Bounded process-local metadata aggregation shared by every runtime generation. */
+    readonly imageObservability: ImageObservability;
+    /** Startup reconciliation plus recurring bounded cleanup for Images state. */
+    readonly imageCleanupService: ImageCleanupService;
+    /** Local-only diagnostics plus the explicit consuming Images verifier. */
+    readonly imageDoctor: ImageDoctorService;
+    /** Generation-pinned hosted-image lease factory used by Native Responses. */
+    readonly hostedImageContributionFactory: HostedImageContributionFactory;
     readonly providerProxy: ProviderProxy;
     readonly routeLeaseManager: RouteLeaseManager;
     readonly outboundApiServer: OutboundApiServer;
@@ -2909,6 +4152,17 @@ interface Daemon {
      * in cleanup.
      */
     readonly auditPruneSweeper: AuditPruneSweeper;
+    /**
+     * Retention for RAW usage rows (rollups are kept forever). Armed by `start`;
+     * `launch` leaves it off — a short-lived boot has no business pruning.
+     */
+    readonly usagePruneSweeper: UsagePruneSweeper;
+    /**
+     * Fold a legacy flat `usage-events.jsonl` into day shards. MUST be awaited
+     * before any listener binds: it moves files the query path reads, and a
+     * request served mid-migration would see a partial store.
+     */
+    readonly migrateUsageStore: () => Promise<UsageMigrationResult>;
     /**
      * Durable-first billing publisher (billing-event-stream) — appends each event
      * to `billing/billing-YYYY-MM-DD.jsonl` FIRST, then best-effort POSTs it.
@@ -2925,11 +4179,6 @@ interface Daemon {
      */
     readonly billingRetrySweeper: BillingRetrySweeper;
 }
-/**
- * Construct the standalone daemon from a loaded config + on-disk paths. Does NOT
- * start the listeners — the `start` command awaits `providerProxy.start()` then
- * `outboundApiServer.applyConfig(...)`.
- */
 declare function buildDaemon(config: DaemonConfig, paths: DaemonPaths): Daemon;
 /** Reset the core singletons (tests / teardown only). Re-exported for the suite.
  *
@@ -3015,11 +4264,24 @@ declare function buildHealthReport(deps: HealthReportDeps): HealthReport;
  *  - SINK: always the console; PLUS an optional append-only file stream when
  *    `file` is set (lazy-open; a write/open error is swallowed → the daemon never
  *    crashes on a logging failure, it just falls back to the console).
+ *  - ROTATION: the file sink is size-capped (`maxFileBytes`, default 8 MB) and
+ *    keeps `maxFiles` generations (default 5) as `<file>.1` … `<file>.N`. An
+ *    UNBOUNDED append-only log is how a long-lived daemon quietly fills a disk,
+ *    so the cap is on by default rather than opt-in. Lines emitted mid-rotation
+ *    are queued (bounded) and flushed into the fresh generation, never dropped
+ *    silently unless the queue itself overflows.
  *
  * ZERO-REGRESSION DEFAULT: `new ConfigurableLogger()` (no config) = console +
  * all levels + text = behaviorally byte-identical to the legacy `ConsoleLogger`
  * (same `console` method per level, same `(message[, meta])` / error arg shape).
  *
+ * NOTE — the daemon no longer CONSTRUCTS it that way. `bootstrap.ts` defaults the
+ * file sink on (`<configDir>/logs/daemon.log`, level `info`, format `json`)
+ * whenever the config omits it: the desktop app discards the daemon's stdout, so
+ * a console-only logger meant a crash left no evidence at all. The unconfigured
+ * CONSTRUCTOR default above is still console-only — only the daemon's wiring
+ * changed.
+ *
  * CAUTION (per the #3 host:port-only-logging precedent): the JSON serializer
  * reduces an `Error` to `{ message, stack }` and spreads a plain `meta` object,
  * but it is NOT a secret redactor — call sites remain responsible for not passing
@@ -3032,8 +4294,16 @@ declare class ConfigurableLogger implements Logger {
     private readonly threshold;
     private readonly format;
     private readonly filePath;
+    private readonly maxFileBytes;
+    private readonly maxFiles;
     private fileStream;
     private fileDisabled;
+    /** Bytes in the CURRENT generation — seeded from the file on open. */
+    private fileBytes;
+    /** True from the moment a rotation starts until the fresh stream is live. */
+    private rotating;
+    /** Lines emitted while `rotating`; flushed into the new generation. */
+    private rotateQueue;
     constructor(cfg?: LoggingConfig);
     info(message: string, meta?: Record<string, unknown> | Error | object): void;
     warn(message: string, meta?: Record<string, unknown> | Error | object): void;
@@ -3053,7 +4323,22 @@ declare class ConfigurableLogger implements Logger {
     private writeConsole;
     /** Append one line to the file sink; a failure disables the sink (swallowed). */
     private writeFile;
-    /** Lazily open the append-only file stream; disable the sink on any error. */
+    /** Write ONE prepared line to the live generation, rotating once it is full. */
+    private emitLine;
+    /**
+     * Close the full generation, shift `<file>.N-1` → `<file>.N` (oldest dropped),
+     * then reopen. Renames run in the `end()` callback so nothing still buffered in
+     * the stream lands in the wrong generation. Any failure disables the sink
+     * rather than throwing — the console sink is unaffected either way.
+     */
+    private rotate;
+    /** `<file>.N` unlinked, `<file>.k` → `<file>.k+1`, `<file>` → `<file>.1`. */
+    private shiftGenerations;
+    /**
+     * Lazily open the append-only file stream; disable the sink on any error. The
+     * byte counter is seeded from the file already on disk so a restart cannot
+     * reset an almost-full generation back to zero and blow past the cap.
+     */
     private getFileStream;
     private consoleFn;
     /** `{ ts, level, msg, ...meta }` (+ `error` when present) as a single line. */
@@ -3143,4 +4428,4 @@ declare function mapCcrToOmnicross(ccr: CcrConfig): {
     notes: string[];
 };
 
-export { type AdminApiDeps, AdminServer, type AdminServerDeps, type AdminServerStatus, type CcrConfig, type CcrProvider, type CcrRouter, ConfigFileProviderConfigSource, ConfigurableLogger, ConsoleLogger, DEFAULT_ADMIN_PORT, type Daemon, type DaemonAdminConfig, type DaemonApiFormat, type DaemonConfig, type DaemonPaths, type DaemonProviderConfig, type HealthReportDeps, JsonApiServerSettingsStore, JsonOutboundKeyDb, JsonSubscriptionCredentialStore, type ResolvedAdminConfig, buildDaemon, buildHealthReport, handleAdminApi, inferApiFormat, loadConfig, mapCcrToOmnicross, parseCcrConfig, resetDaemonSingletonsForTests, resolveAdminConfig, saveConfig, validateConfig };
+export { type AdminApiDeps, AdminServer, type AdminServerDeps, type AdminServerStatus, type CcrConfig, type CcrProvider, type CcrRouter, ConfigFileProviderConfigSource, ConfigurableLogger, ConsoleLogger, DEFAULT_ADMIN_PORT, type Daemon, type DaemonAdminConfig, type DaemonApiFormat, type DaemonConfig, type DaemonPaths, type DaemonProviderConfig, type HealthReportDeps, type HostedImageContributionFactory, type HostedImageRuntimeGenerationLease, type ImageApiMetricDimensions, type ImageApiMetricSnapshot, type ImageExecutionMetricDimensions, type ImageExecutionMetricSnapshot, type ImageHistogramSnapshot, ImageObservability, type ImageObservabilityOptions, type ImageObservabilitySnapshot, type ImageRuntimeCapabilityInspection, type ImageRuntimeGenerationFactoryOptions, type ImageRuntimeGenerationSharedStorage, ImageRuntimeManager, type ImageRuntimeManagerStatus, type ImageRuntimeMetadataObservability, type ImageRuntimeResourceStatus, type ImageRuntimeSafeUnavailableReason, JsonApiServerSettingsStore, JsonOutboundKeyDb, JsonSubscriptionCredentialStore, type PreparedImageRuntimeChange, type PreparedImageRuntimeGeneration, type ProductionImageRuntimeComponents, type ProductionImageRuntimeGeneration, type ResolvedAdminConfig, type TrustedImageApiRuntimeResolver, type TrustedImageApiRuntimeResolverOptions, buildDaemon, buildHealthReport, createHostedImageContributionFactory, createImageRuntimeGeneration, createTrustedImageApiRuntimeResolver, handleAdminApi, inferApiFormat, loadConfig, mapCcrToOmnicross, parseCcrConfig, resetDaemonSingletonsForTests, resolveAdminConfig, saveConfig, validateConfig };