mixdog 0.9.67 → 0.9.69

package/src/runtime/shared/schedule-session-run.mjs

@@ -10,6 +10,8 @@ import { loadConfig } from '../agent/orchestrator/config.mjs';
 import { createSession } from '../agent/orchestrator/session/manager/session-lifecycle.mjs';
 import { askSession } from '../agent/orchestrator/session/manager/ask-session.mjs';
 import { parseScheduleModelRef } from './schedule-model-ref.mjs';
+import { automationWorkflowOpts } from './automation-workflow.mjs';
+import { automationPromptContent } from './automation-attachments.mjs';
 
 /** Resolve schedule.model into a {provider,model,effort?,fast?} route. */
 function scheduleRouteFromModelRef(modelRef, config = null) {
@@ -43,6 +45,9 @@ export async function runScheduleSession(schedule, { config = null, prompt: prom
   }
   const route = scheduleRouteFromModelRef(schedule.model, config);
   const cwd = schedule.cwd ? String(schedule.cwd) : null;
+  // Every fire is a fresh New task (user decision): one prompt, the
+  // schedule's model/workflow/project, a brand-new session in the sidebar
+  // Automations section (newest per name wins there).
   const session = createSession({
     provider: route.provider,
     model: route.model,
@@ -51,13 +56,17 @@ export async function runScheduleSession(schedule, { config = null, prompt: prom
     owner: 'user',
     sourceType: 'schedule',
     sourceName: schedule.name,
+    sourceDelivery: schedule.delivery || null,
     ...(cwd ? { cwd } : {}),
     desktopSession: cwd
       ? { classification: 'project', projectPath: cwd }
       : { classification: 'task', projectPath: null },
+    ...automationWorkflowOpts(schedule.workflow),
   });
   // The user message is the schedule's instructions verbatim: the desktop
   // title/preview derive from it, so no "[Scheduled task: …]" header noise.
-  const result = await askSession(session.id, prompt, null, null, cwd || undefined);
+  // Stored attachments ride along as composer-style content parts.
+  const content = automationPromptContent(prompt, schedule.attachments);
+  const result = await askSession(session.id, content, null, null, cwd || undefined);
   return { sessionId: session.id, result: String(result?.content || '') };
 }

package/src/runtime/shared/schedules-db.mjs

@@ -33,6 +33,9 @@ CREATE TABLE IF NOT EXISTS scheduler.schedules (
   channel_id     text,
   model          text,
   cwd            text,
+  workflow       text,
+  attachments    jsonb,
+  delivery       text,
   prompt         text NOT NULL,
   enabled        boolean NOT NULL DEFAULT true,
   status         text NOT NULL DEFAULT 'active' CHECK (status IN ('active','done')),
@@ -45,6 +48,9 @@ CREATE TABLE IF NOT EXISTS scheduler.schedules (
   CONSTRAINT schedules_when_xor CHECK ((when_at IS NOT NULL) <> (when_cron IS NOT NULL))
 );
 ALTER TABLE scheduler.schedules ADD COLUMN IF NOT EXISTS cwd text;
+ALTER TABLE scheduler.schedules ADD COLUMN IF NOT EXISTS workflow text;
+ALTER TABLE scheduler.schedules ADD COLUMN IF NOT EXISTS attachments jsonb;
+ALTER TABLE scheduler.schedules ADD COLUMN IF NOT EXISTS delivery text;
 `;
 
 async function getDb(dataDir = resolvePluginData()) {
@@ -82,6 +88,9 @@ function rowToDef(row) {
     channelId:     row.channel_id,
     model:         row.model,
     cwd:           row.cwd,
+    workflow:      row.workflow,
+    attachments:   row.attachments || null,
+    delivery:      row.delivery || null,
     prompt:        row.prompt,
     enabled:       row.enabled,
     status:        row.status,
@@ -94,7 +103,7 @@ function rowToDef(row) {
   };
 }
 
-const COLS = 'name, description, when_at, when_cron, timezone, target, channel_id, model, cwd, prompt, enabled, status, last_fired_at, next_fire_at, deferred_until, skipped_until, created_at, updated_at';
+const COLS = 'name, description, when_at, when_cron, timezone, target, channel_id, model, cwd, workflow, attachments, delivery, prompt, enabled, status, last_fired_at, next_fire_at, deferred_until, skipped_until, created_at, updated_at';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -130,6 +139,9 @@ export async function upsertSchedule(def, { dataDir } = {}) {
     def.channelId ?? null,
     def.model ?? null,
     def.cwd ?? null,
+    def.workflow ?? null,
+    def.attachments ? JSON.stringify(def.attachments) : null,
+    def.delivery ?? null,
     def.prompt,
     def.enabled ?? true,
     def.status ?? 'active',
@@ -137,8 +149,8 @@ export async function upsertSchedule(def, { dataDir } = {}) {
   ];
   const { rows } = await db.query(
     `INSERT INTO scheduler.schedules
-       (name, description, when_at, when_cron, timezone, target, channel_id, model, cwd, prompt, enabled, status, next_fire_at)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
+       (name, description, when_at, when_cron, timezone, target, channel_id, model, cwd, workflow, attachments, delivery, prompt, enabled, status, next_fire_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16)
      ON CONFLICT (name) DO UPDATE SET
        description  = EXCLUDED.description,
        when_at      = EXCLUDED.when_at,
@@ -148,6 +160,9 @@ export async function upsertSchedule(def, { dataDir } = {}) {
        channel_id   = EXCLUDED.channel_id,
        model        = EXCLUDED.model,
        cwd          = EXCLUDED.cwd,
+       workflow     = EXCLUDED.workflow,
+       attachments  = EXCLUDED.attachments,
+       delivery     = EXCLUDED.delivery,
        prompt       = EXCLUDED.prompt,
        enabled      = EXCLUDED.enabled,
        next_fire_at = EXCLUDED.next_fire_at,

package/src/runtime/shared/webhook-session-run.mjs

@@ -0,0 +1,57 @@
+/**
+ * Run an inbound webhook as a VISIBLE Mixdog session (schedules parity, user
+ * decision): no Lead-context injection, no channel forward — every fire is a
+ * fresh New task with the endpoint's prompt/model/workflow/project, owned by
+ * 'user' + sourceType 'webhook' (sidebar Automations section, newest per
+ * name). Invoked from the channels worker's webhook dispatch.
+ */
+import { loadConfig } from '../agent/orchestrator/config.mjs';
+import { createSession } from '../agent/orchestrator/session/manager/session-lifecycle.mjs';
+import { askSession } from '../agent/orchestrator/session/manager/ask-session.mjs';
+import { parseScheduleModelRef } from './schedule-model-ref.mjs';
+import { automationWorkflowOpts } from './automation-workflow.mjs';
+import { automationPromptContent } from './automation-attachments.mjs';
+
+/** Endpoint model ref wins; the maintenance.webhook route is the fallback. */
+function webhookRoute(modelRef) {
+  if (modelRef) {
+    const ref = parseScheduleModelRef(modelRef);
+    if (ref && typeof ref === 'object') return ref;
+  }
+  const cfg = loadConfig({ secrets: false });
+  const maintenance = cfg?.maintenance?.webhook;
+  if (maintenance?.provider && maintenance?.model) {
+    return { provider: maintenance.provider, model: maintenance.model };
+  }
+  throw new Error('webhook run has no model: set one on the endpoint or configure maintenance.webhook');
+}
+
+export async function runWebhookSession({ name, model = null, prompt, cwd = null, workflow = null, attachments = null, delivery = null }) {
+  const endpoint = String(name || '').trim();
+  const body = String(prompt || '').trim();
+  if (!endpoint) throw new Error('runWebhookSession: endpoint name required');
+  if (!body) throw new Error(`webhook "${endpoint}" has no prompt body`);
+  const route = webhookRoute(model);
+  const projectCwd = cwd ? String(cwd) : null;
+  const session = createSession({
+    provider: route.provider,
+    model: route.model,
+    ...(route.effort ? { effort: route.effort } : {}),
+    ...(route.fast === true ? { fast: true } : {}),
+    owner: 'user',
+    sourceType: 'webhook',
+    sourceName: endpoint,
+    sourceDelivery: delivery || null,
+    ...(projectCwd ? { cwd: projectCwd } : {}),
+    desktopSession: projectCwd
+      ? { classification: 'project', projectPath: projectCwd }
+      : { classification: 'task', projectPath: null },
+    ...automationWorkflowOpts(workflow),
+  });
+  // The user message leads with the endpoint's instructions, so Recent titles
+  // read as the user-authored intent rather than payload noise.
+  // Stored attachments ride along as composer-style content parts.
+  const content = automationPromptContent(body, attachments);
+  const result = await askSession(session.id, content, null, null, projectCwd || undefined);
+  return { sessionId: session.id, result: String(result?.content || '') };
+}

package/src/runtime/shared/webhooks-db.mjs

@@ -40,6 +40,10 @@ CREATE TABLE IF NOT EXISTS webhooks.endpoints (
   created_at   timestamptz NOT NULL DEFAULT now(),
   updated_at   timestamptz NOT NULL DEFAULT now()
 );
+ALTER TABLE webhooks.endpoints ADD COLUMN IF NOT EXISTS cwd text;
+ALTER TABLE webhooks.endpoints ADD COLUMN IF NOT EXISTS workflow text;
+ALTER TABLE webhooks.endpoints ADD COLUMN IF NOT EXISTS attachments jsonb;
+ALTER TABLE webhooks.endpoints ADD COLUMN IF NOT EXISTS delivery text;
 CREATE TABLE IF NOT EXISTS webhooks.deliveries (
   endpoint        text NOT NULL,
   delivery_id     text NOT NULL,
@@ -77,7 +81,7 @@ async function getDb(dataDir = resolvePluginData()) {
 // Row <-> def mapping
 // ---------------------------------------------------------------------------
 
-const ENDPOINT_COLS = 'name, description, channel_id, role, model, parser, secret, instructions, enabled, created_at, updated_at';
+const ENDPOINT_COLS = 'name, description, channel_id, role, model, parser, secret, cwd, workflow, attachments, delivery, instructions, enabled, created_at, updated_at';
 
 function rowToEndpoint(row) {
   if (!row) return null;
@@ -88,6 +92,10 @@ function rowToEndpoint(row) {
     role:         row.role,
     model:        row.model,
     parser:       row.parser,
+    cwd:          row.cwd,
+    workflow:     row.workflow,
+    attachments:  row.attachments || null,
+    delivery:     row.delivery || null,
     // Never project the plaintext secret through list/load config paths;
     // callers get a presence flag and must fetch the value via
     // readEndpointSecret (the single, explicit secret-read path).
@@ -165,13 +173,17 @@ export async function upsertEndpoint(def, { dataDir } = {}) {
     def.model ?? null,
     def.parser ?? null,
     def.secret ?? null,
+    def.cwd ?? null,
+    def.workflow ?? null,
+    def.attachments ? JSON.stringify(def.attachments) : null,
+    def.delivery ?? null,
     def.instructions ?? '',
     def.enabled ?? true,
   ];
   const { rows } = await db.query(
     `INSERT INTO webhooks.endpoints
-       (name, description, channel_id, role, model, parser, secret, instructions, enabled)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+       (name, description, channel_id, role, model, parser, secret, cwd, workflow, attachments, delivery, instructions, enabled)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
      ON CONFLICT (name) DO UPDATE SET
        description  = EXCLUDED.description,
        channel_id   = EXCLUDED.channel_id,
@@ -179,6 +191,10 @@ export async function upsertEndpoint(def, { dataDir } = {}) {
        model        = EXCLUDED.model,
        parser       = EXCLUDED.parser,
        secret       = EXCLUDED.secret,
+       cwd          = EXCLUDED.cwd,
+       workflow     = EXCLUDED.workflow,
+       attachments  = EXCLUDED.attachments,
+       delivery     = EXCLUDED.delivery,
        instructions = EXCLUDED.instructions,
        enabled      = EXCLUDED.enabled,
        updated_at   = now()

package/src/session-runtime/channel-config-api.mjs

@@ -17,7 +17,7 @@ import { runScheduleSession } from '../runtime/shared/schedule-session-run.mjs';
 // API object; the mutating admin helpers are imported directly here and the
 // runtime injects only the closure-owned callbacks (backend flush, channel
 // worker handle, soft reload).
-export function createChannelConfigApi({ flushBackendSave, channels, reloadChannelsSoon }) {
+export function createChannelConfigApi({ flushBackendSave, channels, reloadChannelsSoon, ensureAutomationRuntime = () => {} }) {
   return {
     async getChannelSetup() {
       // Flush a pending debounced backend switch first so setup readers
@@ -42,6 +42,10 @@ export function createChannelConfigApi({ flushBackendSave, channels, reloadChann
     async saveSchedule(entry) {
       const result = await saveSchedule(entry);
       reloadChannelsSoon();
+      // First automation created while the app is already running: the boot-
+      // time autostart check has passed, so kick the worker start path now
+      // (no-op when it is already up).
+      ensureAutomationRuntime();
       return result;
     },
     async deleteSchedule(name) {
@@ -52,11 +56,13 @@ export function createChannelConfigApi({ flushBackendSave, channels, reloadChann
     async setScheduleEnabled(name, enabled) {
       const result = await setScheduleEnabled(name, enabled);
       reloadChannelsSoon();
+      if (enabled !== false) ensureAutomationRuntime();
       return result;
     },
     async saveWebhook(entry) {
       const result = await saveWebhook(entry);
       reloadChannelsSoon();
+      ensureAutomationRuntime();
       return result;
     },
     async deleteWebhook(name) {
@@ -67,6 +73,7 @@ export function createChannelConfigApi({ flushBackendSave, channels, reloadChann
     async setWebhookEnabled(name, enabled) {
       const result = await setWebhookEnabled(name, enabled);
       reloadChannelsSoon();
+      if (enabled !== false) ensureAutomationRuntime();
       return result;
     },
     // Read-only secret fetch for the webhook editor; no worker reload.

package/src/session-runtime/lifecycle-api.mjs

@@ -69,6 +69,9 @@ export function createLifecycleApi(deps) {
       // Recent / TUI resume next to lead sessions instead of hiding like
       // agent dispatches.
       || sourceType === 'schedule'
+      // Webhook fires run as visible sessions too (user decision: no Lead
+      // injection — the session row IS the notification).
+      || sourceType === 'webhook'
       || (!sourceType && !sourceName && !isAgentOwner(owner));
     if (!leadish) return null;
     const rawPreview = s.preview || '';
@@ -106,6 +109,10 @@ export function createLifecycleApi(deps) {
       // after a turn had already finished.
       heartbeatAt: Number(heartbeatMtimes.get(s.id)) || 0,
       desktopSession: s.desktopSession || null,
+      // Automation origin: lets the desktop group schedule/webhook runner
+      // sessions under the sidebar Automations section instead of Recent.
+      sourceType: sourceType || null,
+      sourceName: clean(s.sourceName || '') || null,
     };
     }).filter(Boolean);
   };

package/src/session-runtime/memory-daemon-probe.mjs

@@ -0,0 +1,61 @@
+// Eager memory-daemon boot for remote sessions. The channels worker forwards
+// transcript ingests to the memory HTTP service, so its port must be published
+// (and actually listening) before the worker sends its first ingest — otherwise
+// early channel traffic finds no port and gets buffered. Extracted from
+// runtime-core's startRemote, which now just fires it.
+import * as httpMod from 'node:http';
+
+const HEALTH_ATTEMPTS = 30;
+const HEALTH_RETRY_MS = 500;
+const HEALTH_TIMEOUT_MS = 1500;
+
+function healthOk(port) {
+  return new Promise((resolve) => {
+    const request = httpMod.request(
+      { hostname: '127.0.0.1', port, path: '/health', timeout: HEALTH_TIMEOUT_MS },
+      (response) => {
+        let body = '';
+        response.on('data', (chunk) => { body += chunk; });
+        response.on('end', () => {
+          try { resolve(JSON.parse(body)?.status === 'ok'); } catch { resolve(false); }
+        });
+      },
+    );
+    request.on('error', () => resolve(false));
+    request.on('timeout', () => { request.destroy(); resolve(false); });
+    request.end();
+  });
+}
+
+/** Detached, never throws: resolving the module only hands back a handle, so
+ *  this awaits start() and then polls /health until the daemon is provably
+ *  reachable (or the failure is profiled). */
+export function startMemoryDaemonEagerly({ getMemoryModule, bootProfile }) {
+  void (async () => {
+    try {
+      // Yield one tick first: the module resolve + daemon fork below is a long
+      // synchronous chain that would otherwise starve Ink's queued render and
+      // keypress handling.
+      await new Promise((resolve) => setImmediate(resolve));
+      const module = await getMemoryModule();
+      const started = typeof module?.start === 'function' ? await module.start() : null;
+      const port = started?.port;
+      if (!port) {
+        bootProfile('channels:memory-eager-init-failed', { error: 'no port from start()' });
+        return;
+      }
+      for (let attempt = 0; attempt < HEALTH_ATTEMPTS; attempt += 1) {
+        try {
+          if (await healthOk(port)) {
+            bootProfile('channels:memory-eager-init-ready', { port });
+            return;
+          }
+        } catch { /* probe failure is retried below */ }
+        await new Promise((resolve) => setTimeout(resolve, HEALTH_RETRY_MS));
+      }
+      bootProfile('channels:memory-eager-init-failed', { error: `health not ok after retries (port ${port})` });
+    } catch (error) {
+      bootProfile('channels:memory-eager-init-failed', { error: error?.message || String(error) });
+    }
+  })();
+}

package/src/session-runtime/model-capabilities.mjs

@@ -103,6 +103,8 @@ export function fastPreferenceFor(config, provider, model) {
   if (!key) return false;
   const saved = config?.modelSettings?.[key];
   if (saved && typeof saved === 'object' && hasOwn(saved, 'fast')) return saved.fast === true;
+  // Pre-modelSettings configs kept the preference in a parallel `fastModels`
+  // map. Reading it keeps those installs working; nothing writes it anymore.
   return config?.fastModels?.[key] === true;
 }
 
@@ -118,11 +120,11 @@ export function saveModelSettings(cfgMod, route, { fastCapable = true, baseConfi
   else nextSetting.fast = false;
   modelSettings[key] = nextSetting;
 
-  // Legacy compatibility: keep fastModels true entries for old readers, but
-  // let modelSettings.fast=false override them in new readers.
+  // modelSettings is the single source of truth for the fast preference; the
+  // stale mirror in `fastModels` is dropped for the key being written so the
+  // two can never disagree.
   const fastModels = { ...(nextConfig.fastModels || {}) };
-  if (nextSetting.fast === true) fastModels[key] = true;
-  else delete fastModels[key];
+  delete fastModels[key];
 
   const savedConfig = { ...nextConfig, modelSettings, fastModels };
   cfgMod.saveConfig(savedConfig);

package/src/session-runtime/notification-bus.mjs

@@ -0,0 +1,82 @@
+// Runtime notification fan-out. A notification reaches listeners (TUI/API) and,
+// for terminal tool completions, may also be mirrored into the session's
+// pending queue so the model sees it next turn. The delivered registry keeps
+// those two paths from double-injecting the same completion.
+import { modelVisibleToolCompletionMessage } from '../runtime/shared/tool-execution-contract.mjs';
+import { markCompletionEntry } from '../runtime/agent/orchestrator/session/manager/pending-messages.mjs';
+import {
+  isDeliveredCompletion,
+  logDuplicateSkip,
+  recordDeliveredCompletion,
+} from '../runtime/agent/orchestrator/session/manager/delivered-completions.mjs';
+import { shouldMirrorCompletionToPendingQueue } from './runtime-tool-routing.mjs';
+
+export function createNotificationBus({ listeners, mgr }) {
+  function emitRuntimeNotification(content, meta = {}) {
+    const text = String(content || '').trim();
+    if (!text) return { handled: false, modelVisibleDelivered: false };
+    const event = { content: text, meta: meta && typeof meta === 'object' ? meta : {} };
+    let handled = false;
+    for (const listener of [...listeners]) {
+      try {
+        if (listener(event) === true) handled = true;
+      } catch { /* a broken listener never blocks the rest */ }
+    }
+    // EXPLICIT model-visible ack: only the TUI execution-ui path sets
+    // event.modelVisibleDelivered when it enqueues the body into the active
+    // loop. A display-only listener returning true is NOT that ack.
+    return { handled, modelVisibleDelivered: event.modelVisibleDelivered === true };
+  }
+
+  // Enqueue the model-visible twin unless it was already delivered; returns
+  // true when the caller may treat the completion as delivered.
+  function enqueueCompletion(callerSessionId, text, meta, path) {
+    const visible = modelVisibleToolCompletionMessage(text, meta);
+    // Non-completion notifications yield '' here and are never queued.
+    if (!visible) return false;
+    if (isDeliveredCompletion({ executionId: meta?.execution_id, text: visible })) {
+      // Delivered + ACKed on the TUI path: suppress the duplicate but report
+      // DELIVERED so the caller stops retrying.
+      logDuplicateSkip(path, { executionId: meta?.execution_id, text: visible });
+      return true;
+    }
+    return mgr.enqueuePendingMessage(callerSessionId, markCompletionEntry(visible)) > 0;
+  }
+
+  function notifyFnForSession(callerSessionId) {
+    return (text, meta = {}) => {
+      const { handled, modelVisibleDelivered } = emitRuntimeNotification(text, meta);
+      let enqueued = false;
+      // Record the TUI delivery so a racing enqueue in THIS process (background
+      // reconcile / fallback / notify) skips instead of double-injecting.
+      if (modelVisibleDelivered) {
+        try {
+          recordDeliveredCompletion({
+            executionId: meta?.execution_id,
+            text: modelVisibleToolCompletionMessage(text, meta),
+          });
+        } catch { /* registry is best-effort */ }
+      }
+      // TUI sessions consume raw envelopes for UI cards, but those are
+      // internal-only in pending drain: mirror the model-visible twin unless the
+      // TUI explicitly acked it.
+      if (shouldMirrorCompletionToPendingQueue({
+        callerSessionId,
+        modelVisibleDelivered,
+        hasEnqueue: typeof mgr.enqueuePendingMessage === 'function',
+        text,
+        meta,
+      })) {
+        try { enqueued = enqueueCompletion(callerSessionId, text, meta, 'mirror'); } catch { /* best-effort */ }
+      }
+      // Headless/API listeners may exist without consuming the event: keep the
+      // fallback enqueue for an otherwise unhandled completion.
+      if (!enqueued && !handled && callerSessionId && typeof mgr.enqueuePendingMessage === 'function') {
+        try { enqueued = enqueueCompletion(callerSessionId, text, meta, 'fallback'); } catch { /* best-effort */ }
+      }
+      return enqueued || handled;
+    };
+  }
+
+  return { emitRuntimeNotification, notifyFnForSession };
+}

package/src/session-runtime/provider-auth-api.mjs

@@ -24,6 +24,8 @@ export function createProviderAuthApi({
   displayConfig,
   reloadFullConfig,
   awaitKeychainPrewarm,
+  isKeychainPrewarmReady = () => true,
+  hasProviderSetupCached = () => true,
   invalidateProviderCaches,
   warmProviderModelCache,
   refreshProviderCatalogs,
@@ -56,8 +58,21 @@ export function createProviderAuthApi({
       return renderProviderStatus(displayConfig());
     },
     async getProviderSetup(options = {}) {
-      await awaitKeychainPrewarm();
       const force = options?.force === true || options?.refresh === true;
+      // An unforced read never blocks: the authoritative setup waits on the OS
+      // keychain AND probes local provider ports, which together take seconds on
+      // a cold start and used to stall the whole settings sweep behind it. Serve
+      // the no-secrets snapshot until the real one is cached — flagged, so the
+      // caller shows "checking" instead of a wrong "not connected" — and let the
+      // scheduled warmup publish the authoritative result for the next read.
+      if (!force && (!isKeychainPrewarmReady() || !hasProviderSetupCached())) {
+        const quick = await cachedProviderSetup({ quick: true });
+        void Promise.resolve(awaitKeychainPrewarm())
+          .then(() => cachedProviderSetup({}))
+          .catch(() => {});
+        return { ...quick, pendingSecrets: !isKeychainPrewarmReady() };
+      }
+      await awaitKeychainPrewarm();
       if (force) reloadFullConfig();
       return await cachedProviderSetup({ force });
     },

package/src/session-runtime/provider-usage.mjs

@@ -118,6 +118,9 @@ export function createProviderUsage({
   return {
     refreshStatuslineUsageSnapshot,
     cachedProviderSetup,
+    // True once a secrets-aware setup is cached: callers that must not block
+    // (settings hydration) can serve the quick snapshot until then.
+    hasProviderSetupCached: () => Boolean(caches.providerSetupCache.setup),
     getUsageDashboard,
   };
 }