mixdog 1.2.4 → 1.2.6

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

@@ -4,6 +4,7 @@
 import { refreshKeychainStatus, retryKeychain } from '../../runtime/shared/config.mjs';
 import { keychainIssueFor } from '../services/provider-admin.mjs';
 import { modelProxyClientMode } from '../../runtime/shared/model-proxy-mode.mjs';
+import { providerCatalogFailure } from '../../runtime/agent/orchestrator/providers/catalog-failures.mjs';
 
 // The keyring alert must reflect the live state (it can lock or unlock while a
 // cached setup is served), so overlay it on every ready read.
@@ -14,6 +15,22 @@ function withLiveKeychain(setup) {
   return keychain ? { ...rest, keychain } : rest;
 }
 
+// A provider whose model list failed says why on its row (`catalogError`), so a
+// view never shows its empty list as if nothing were wrong. Overlaid on every
+// read like the keyring alert: the cached setup predates the failure.
+export function withCatalogErrors(setup) {
+  if (!setup || typeof setup !== 'object') return setup;
+  const out = { ...setup };
+  for (const group of ['api', 'oauth', 'local']) {
+    if (!Array.isArray(setup[group])) continue;
+    out[group] = setup[group].map((row) => {
+      const { message, errorKind } = providerCatalogFailure(row?.id) ?? {};
+      return message ? { ...row, catalogError: { message, errorKind } } : row;
+    });
+  }
+  return out;
+}
+
 export function createSetupApi({
   awaitKeychainPrewarm,
   isKeychainPrewarmReady,
@@ -41,7 +58,7 @@ export function createSetupApi({
         void Promise.resolve(awaitKeychainPrewarm())
           .then(() => cachedProviderSetup({}))
           .catch(() => {});
-        return { ...quick, pendingSecrets: !isKeychainPrewarmReady() };
+        return withCatalogErrors({ ...quick, pendingSecrets: !isKeychainPrewarmReady() });
       }
       await awaitKeychainPrewarm();
       // A keyring the user has since unlocked: rebuild the setup that was cached
@@ -53,7 +70,7 @@ export function createSetupApi({
       // `recheckKeychain` (window focus) skips the snapshot TTL.
       const changed = await refreshKeychainStatus({ force: options?.recheckKeychain === true });
       if (changed) reloadFullConfig();
-      return withLiveKeychain(await cachedProviderSetup({ force: force || recovered || changed }));
+      return withCatalogErrors(withLiveKeychain(await cachedProviderSetup({ force: force || recovered || changed })));
     },
     async getUsageDashboard(options = {}) {
       return await getUsageDashboard(options);

package/src/session-runtime/provider-catalog-cache.mjs

@@ -1,52 +1,128 @@
 // Provider registries are process-global. Share raw catalog rows across
 // sessions, while each session owns its saved-settings projection.
-let sharedCatalogRevision = -1;
+//
+// One slow or offline provider must not hold, or force a reload of, everyone
+// else's rows. Each provider's model list runs through catalog-deadline.mjs:
+// bounded per provider (a timed-out list becomes an error entry and is
+// aborted where listModels honors `{ signal }`), and single-flight per
+// provider until the underlying work settles. When some but not all providers
+// answer, the answered entries are kept for the catalog state, and each
+// failed entry carries a process-wide `retryAt`: non-forced reads by any
+// session reuse the partial answer and ask a missing provider again only once
+// its backoff passed. Forced reads ask every provider. A load where every
+// provider failed is never kept, so it stays immediately retryable. A
+// provider whose previous list ignored its deadline and is still running is
+// not asked at all (catalog-deadline.mjs): it gets a timed-out entry at
+// once, with the same backoff, until that list settles.
+//
+// The catalog state is the registry revision plus a local epoch that
+// invalidateSharedProviderCatalog() bumps on auth/account changes, so rows
+// listed under the previous account are never served again.
+import {
+  boundedProviderCatalogOp,
+  bumpProviderCatalogGeneration,
+  PROVIDER_CATALOG_TIMEOUT_MS,
+} from '../runtime/agent/orchestrator/providers/catalog-deadline.mjs';
+
+export { PROVIDER_CATALOG_TIMEOUT_MS };
+
+/** Backoff before a provider missing from a partial catalog is asked again. */
+export const PROVIDER_CATALOG_RETRY_MS = 30_000;
+
+let catalogEpoch = 0;
+let sharedCatalogKey = null;
 let sharedCatalogEntries = null;
+let sharedPartialKey = null;
+let sharedPartialEntries = null;
 let sharedCatalogPromise = null;
-let sharedCatalogPromiseRevision = -1;
+let sharedCatalogPromiseKey = null;
+let sharedCatalogPromiseForced = false;
 
 export function catalogRevision(registry) {
   const value = Number(registry?.providerCatalogRevision?.());
   return Number.isFinite(value) ? value : 0;
 }
 
-export async function sharedProviderCatalog(registry) {
-  const revision = catalogRevision(registry);
-  if (sharedCatalogRevision === revision && Array.isArray(sharedCatalogEntries)) {
+const catalogKey = (registry) => `${catalogRevision(registry)}:${catalogEpoch}`;
+
+/** Drops every shared entry (complete or partial) and opens a new epoch: the
+ *  next read asks every provider again. Called on auth/account changes. */
+export function invalidateSharedProviderCatalog() {
+  catalogEpoch += 1;
+  // Pending refreshes and lists of the previous account, of either kind, must
+  // not block or fail the new account's work.
+  bumpProviderCatalogGeneration();
+  sharedCatalogKey = null;
+  sharedCatalogEntries = null;
+  sharedPartialKey = null;
+  sharedPartialEntries = null;
+}
+
+const answered = (entry) => !Object.hasOwn(entry, 'error');
+
+async function providerEntry(name, provider, timeoutMs, epoch) {
+  if (typeof provider?.listModels !== 'function') return { name, models: [], ms: 0 };
+  const startedAt = performance.now();
+  const outcome = await boundedProviderCatalogOp({
+    name,
+    provider,
+    kind: 'list',
+    run: (signal) => provider.listModels({ signal }),
+    timeoutMs,
+    epoch,
+  });
+  const ms = performance.now() - startedAt;
+  if (outcome.error) {
+    return { name, models: [], error: outcome.error, ms, retryAt: Date.now() + PROVIDER_CATALOG_RETRY_MS };
+  }
+  return { name, models: Array.isArray(outcome.value) ? outcome.value : [], ms };
+}
+
+export async function sharedProviderCatalog(registry, { force = false, timeoutMs = PROVIDER_CATALOG_TIMEOUT_MS } = {}) {
+  const key = catalogKey(registry);
+  if (!force && sharedCatalogKey === key && Array.isArray(sharedCatalogEntries)) {
     return sharedCatalogEntries;
   }
-  if (sharedCatalogPromise && sharedCatalogPromiseRevision === revision) {
+  if (sharedCatalogPromise && sharedCatalogPromiseKey === key && (sharedCatalogPromiseForced || !force)) {
     return await sharedCatalogPromise;
   }
+  const kept = new Map();
+  if (!force && sharedPartialKey === key) {
+    const now = Date.now();
+    for (const entry of sharedPartialEntries) {
+      if (answered(entry) || now < entry.retryAt) kept.set(entry.name, entry);
+    }
+  }
   const providers = [...registry.getAllProviders()];
-  sharedCatalogPromiseRevision = revision;
+  // Every missing provider is still inside its backoff: the partial answer is
+  // the answer, without asking anyone.
+  if (providers.length > 0 && providers.every(([name]) => kept.has(name))) {
+    return providers.map(([name]) => kept.get(name));
+  }
+  // A pending list from an older catalog state (revision or account epoch) is
+  // not joined: its answer may describe the previous catalog.
+  const epoch = key;
+  sharedCatalogPromiseKey = key;
+  sharedCatalogPromiseForced = force;
   const request = Promise.all(
-    providers.map(async ([name, provider]) => {
-      if (typeof provider?.listModels !== 'function') return { name, models: [], ms: 0 };
-      const startedAt = performance.now();
-      try {
-        const models = await provider.listModels();
-        return { name, models: Array.isArray(models) ? models : [], ms: performance.now() - startedAt };
-      } catch (error) {
-        return { name, models: [], error, ms: performance.now() - startedAt };
-      }
-    })
+    providers.map(([name, provider]) => kept.get(name) || providerEntry(name, provider, timeoutMs, epoch))
   )
     .then((entries) => {
-      if (
-        sharedCatalogPromise === request &&
-        catalogRevision(registry) === revision &&
-        entries.every((entry) => !Object.hasOwn(entry, 'error'))
-      ) {
-        sharedCatalogRevision = revision;
-        sharedCatalogEntries = entries;
+      if (sharedCatalogPromise === request && catalogKey(registry) === key) {
+        const complete = entries.every(answered);
+        const partial = !complete && entries.some(answered);
+        sharedCatalogKey = complete ? key : null;
+        sharedCatalogEntries = complete ? entries : null;
+        sharedPartialKey = partial ? key : null;
+        sharedPartialEntries = partial ? entries : null;
       }
       return entries;
     })
     .finally(() => {
       if (sharedCatalogPromise === request) {
         sharedCatalogPromise = null;
-        sharedCatalogPromiseRevision = -1;
+        sharedCatalogPromiseKey = null;
+        sharedCatalogPromiseForced = false;
       }
     });
   sharedCatalogPromise = request;

package/src/session-runtime/provider-models/catalog-load.mjs

@@ -17,6 +17,7 @@ export function createCatalogLoader({
   ensureFullConfig,
   awaitKeychainPrewarm,
   ensureProvidersReady,
+  providerTimeoutMs,
 }) {
   function rowsForEntry({ name, models, error, ms }) {
     const out = [];
@@ -76,7 +77,10 @@ export function createCatalogLoader({
   }
 
   /** `request` ({ seq }) identifies the caller's load; `request.complete`
-   *  reports whether every provider answered. */
+   *  reports whether every provider answered, `request.missing` names the
+   *  providers that failed or timed out, `request.partial` marks a load
+   *  where some but not all providers answered, and `request.retryAt` is when
+   *  the first missing provider may be asked again. */
   return async function loadProviderModelsFresh({ forceRefresh = false, loadSecrets = true, request = null } = {}) {
     const startedAt = performance.now();
     profile('load:start', { forceRefresh, loadSecrets });
@@ -93,8 +97,15 @@ export function createCatalogLoader({
     // forward only for the still-current request, never for a superseded load.
     if (ownsLoad) request.seq = caches.providerModelsLoadSeq;
     const seq = request?.seq ?? caches.providerModelsLoadSeq;
-    const catalogEntries = await sharedProviderCatalog(reg());
-    if (request) request.complete = catalogEntries.every((entry) => !Object.hasOwn(entry, 'error'));
+    const catalogEntries = await sharedProviderCatalog(reg(), { force: forceRefresh, timeoutMs: providerTimeoutMs });
+    if (request) {
+      const failed = catalogEntries.filter((entry) => Object.hasOwn(entry, 'error'));
+      request.missing = failed.map((entry) => entry.name);
+      request.complete = failed.length === 0;
+      request.partial = !request.complete && failed.length < catalogEntries.length;
+      // The shared, process-wide backoff of the soonest missing provider.
+      request.retryAt = request.partial ? Math.min(...failed.map((entry) => entry.retryAt)) : null;
+    }
     const results = [];
     const seen = new Set();
     for (const row of catalogEntries.flatMap(rowsForEntry)) {

package/src/session-runtime/provider-models/row-hydration.mjs

@@ -69,6 +69,10 @@ export function hydrateProviderModelRow(cfg, row) {
     savedModelParameters: saved.modelParameters || {},
     savedContextPercent: Number(saved.contextPercent) || undefined,
     savedContextTokens: Number(saved.contextTokens) || undefined,
+    // Model management: an explicit /model visibility choice and the favorite
+    // mark (absent = the picker's default listing, not a favorite).
+    ...(typeof saved.hidden === 'boolean' ? { savedHidden: saved.hidden } : {}),
+    ...(saved.favorite === true ? { favorite: true } : {}),
   };
 }
 

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

@@ -10,6 +10,7 @@
 //   row-hydration      — saved model settings layered onto catalog rows
 //   web-search-catalog — the native web-search model list
 //   catalog-load       — one authoritative provider catalog load
+import { PROVIDER_CATALOG_RETRY_MS } from './provider-catalog-cache.mjs';
 import { createCatalogLoader } from './provider-models/catalog-load.mjs';
 import { createModelMetaIndex, modelMetaKey } from './provider-models/model-meta.mjs';
 import { createRowHydration } from './provider-models/row-hydration.mjs';
@@ -19,6 +20,25 @@ const PROVIDER_MODELS_PROFILE_ENABLED = /^(1|true|yes|on)$/i.test(
   String(process.env.MIXDOG_PROVIDER_MODELS_PROFILE || process.env.MIXDOG_BOOT_PROFILE || '')
 );
 
+/** How long a partial catalog (some provider failed or timed out) is served
+ *  as-is before a read retries the missing providers in the background. The
+ *  backoff is process-wide (provider-catalog-cache.mjs), not per session. */
+export const PARTIAL_CATALOG_RETRY_MS = PROVIDER_CATALOG_RETRY_MS;
+
+/** Rows of a partial answer say so explicitly, on quick and full reads alike:
+ *  `catalogPartial`, the `catalogMissing` providers and `catalogRetryAt`
+ *  (epoch ms) after which a reader should ask again. Complete answers carry
+ *  none of these. */
+function withCatalogState(models, partial) {
+  if (!partial) return models;
+  return models.map((row) => ({
+    ...row,
+    catalogPartial: true,
+    catalogMissing: [...partial.missing],
+    catalogRetryAt: partial.retryAt,
+  }));
+}
+
 export function createProviderModels({
   caches,
   modelMetaByRoute,
@@ -37,6 +57,8 @@ export function createProviderModels({
   scheduleProviderModelWarmup,
   // Quick-row helpers wired in after createQuickModelRows resolves.
   quickHelpers,
+  // Per-provider model-list bound; defaults to PROVIDER_CATALOG_TIMEOUT_MS.
+  providerCatalogTimeoutMs,
 }) {
   const config = () => getConfig();
   const route = () => getRoute();
@@ -66,17 +88,56 @@ export function createProviderModels({
     collectProviderModels,
     ...readiness,
   });
-  const loadProviderModelsFresh = createCatalogLoader({ caches, config, reg, meta, rows, profile, ...readiness });
+  const loadProviderModelsFresh = createCatalogLoader({
+    caches,
+    config,
+    reg,
+    meta,
+    rows,
+    profile,
+    providerTimeoutMs: providerCatalogTimeoutMs,
+    ...readiness,
+  });
+
+  // Partial-catalog state of a loaded rows array, for readers that joined the
+  // shared load instead of reading the adopted cache.
+  const partialLoads = new WeakMap();
+  const partialOf = (request) => (request.partial ? { missing: request.missing, retryAt: request.retryAt } : null);
 
   function adoptProviderModelCache(models, request, loadSecrets = true) {
     const revision = meta.syncCatalogRevision();
-    // No-secrets and failed loads may be partial. Keep them retryable rather
-    // than turning a transient failure into an authoritative empty catalog.
-    if (request.seq === caches.providerModelsLoadSeq && loadSecrets && request.complete) {
-      caches.providerModelsCache = { models, at: Date.now(), revision };
+    const partial = partialOf(request);
+    if (partial) partialLoads.set(models, partial);
+    if (request.seq !== caches.providerModelsLoadSeq || !loadSecrets) return;
+    const at = Date.now();
+    if (request.complete) {
+      caches.providerModelsCache = { models, at, revision };
+    } else if (partial) {
+      // Some providers answered. Serving that answer beats reloading every
+      // provider on each read while one is down; it stays marked partial and
+      // its missing providers are retried once the shared backoff passes. A
+      // no-secrets, empty or all-failed load stays uncached and retryable
+      // rather than becoming an authoritative empty catalog.
+      caches.providerModelsCache = { models, at, revision, partial: true, ...partial };
     }
   }
 
+  /** Background refill of a partial catalog: only its missing providers are
+   *  asked again (provider-catalog-cache keeps the ones that answered, and
+   *  holds back providers still inside the shared backoff), and readers keep
+   *  the partial rows until the refill lands. */
+  function refillPartialCatalog(cached) {
+    if (!cached.partial || Date.now() < cached.retryAt || caches.providerModelsPromise) return;
+    profile('partial:retry', { missing: cached.missing.join(',') });
+    startSharedLoad({
+      loadSecrets: true,
+      onFailed: (err) => {
+        profile('partial:retry-failed', { error: err instanceof Error ? err.message : String(err) });
+        return cached.models;
+      },
+    });
+  }
+
   /** The shared in-flight load every concurrent reader joins. `onFailed`, when
    *  given, is part of the shared promise so joiners see its value too;
    *  `caches.providerModelsPromise` is cleared once it settles so a later read
@@ -97,13 +158,17 @@ export function createProviderModels({
 
   async function collectProviderModels({ force = false, quick = false } = {}) {
     meta.syncCatalogRevision();
-    if (!force && Array.isArray(caches.providerModelsCache.models)) {
-      const models = rows.providerModelsFromCacheRows(caches.providerModelsCache.models);
+    const cached = caches.providerModelsCache;
+    if (!force && Array.isArray(cached.models)) {
+      refillPartialCatalog(cached);
+      const models = rows.providerModelsFromCacheRows(cached.models);
       // A quick read answered from the loaded catalog already IS the full
       // catalog. Saying so lets a caller skip the full read it would otherwise
       // follow up with (a phone paid the whole catalog twice at boot). Only
       // this answer carries the mark: a full read is complete by definition,
-      // and an unmarked quick answer keeps meaning "follow up".
+      // and an unmarked quick answer keeps meaning "follow up". A partial
+      // catalog is never marked complete; it carries its partial state.
+      if (cached.partial) return withCatalogState(models, cached);
       return quick ? models.map((row) => ({ ...row, catalogComplete: true })) : models;
     }
     if (!force && quick) {
@@ -117,10 +182,11 @@ export function createProviderModels({
       const request = { seq: ++caches.providerModelsLoadSeq };
       const models = await loadProviderModelsFresh({ forceRefresh: true, loadSecrets: true, request });
       adoptProviderModelCache(models, request);
-      return rows.providerModelsFromCacheRows(models);
+      return withCatalogState(rows.providerModelsFromCacheRows(models), partialOf(request));
     }
     if (!caches.providerModelsPromise) startSharedLoad({ loadSecrets: true });
-    return rows.providerModelsFromCacheRows(await caches.providerModelsPromise);
+    const loaded = await caches.providerModelsPromise;
+    return withCatalogState(rows.providerModelsFromCacheRows(loaded), partialLoads.get(loaded));
   }
 
   function warmProviderModelCache({ loadSecrets = false } = {}) {

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

@@ -5,6 +5,7 @@
 // registry import and the provider-models factory resolve after this gate is
 // created, while ensureProvidersReady only reaches them on demand.
 import { bootProfile } from './boot-profile.mjs';
+import { invalidateSharedProviderCatalog } from './provider-catalog-cache.mjs';
 import { providerInitCacheKey } from './provider-init-key.mjs';
 
 const KEYCHAIN_PREWARM_WAIT_MS = 5000;
@@ -52,6 +53,9 @@ export function createProviderReadiness({ rt, keychain, getReg, getWarmProviderM
   const providerInitPromises = new Map();
 
   function invalidateProviderCaches(options = {}) {
+    // Auth/account/config changes alter what providers list: the process-wide
+    // catalog (partial rows and retry backoffs included) starts a new epoch.
+    invalidateSharedProviderCatalog();
     Object.assign(providerModelCaches, emptyModelCaches());
     providerModelCaches.providerModelsLoadSeq += 1;
     Object.assign(providerUsageCaches, emptyUsageCaches());

package/src/session-runtime/services/agent-tool/close-flow.mjs

@@ -8,6 +8,7 @@ import {
 import { agentScope, clean, clearAgentStatuslineRoute } from './helpers.mjs';
 import { isLeadPoolAgent } from './worker-rows.mjs';
 import { createCloseAll } from './close-flow/close-all.mjs';
+import { closeManagedSession } from '../../lifecycle/shared.mjs';
 
 const CLOSE_REASON = 'cancelled by agent close';
 
@@ -68,7 +69,7 @@ export function createCloseFlow({ mgr, registry, views }) {
     // below is an idempotent no-op fallback once terminal.
     // Closing a runtime cancels its work; only explicit session deletion
     // may tombstone the conversation.
-    const ok = await mgr.closeSession(sessionId, 'cli-agent-close', { tombstone: false });
+    const ok = await closeManagedSession(mgr, sessionId, 'cli-agent-close', { tombstone: false });
     if (task?.taskId) cancelBackgroundTask(task.taskId, CLOSE_REASON);
     // Drop the row only once the cancellation is DURABLY recorded: a failed
     // close that still forgot the row would leave no cancelled state behind.

package/src/session-runtime/services/agent-tool/job-views/agent-list.mjs

@@ -76,13 +76,21 @@ export function createAgentList({ mgr, refreshTagsFromSessions, agentSessionEntr
   return function list({ scanSessions = false, context = {}, includeTerminal = false } = {}) {
     refreshTagsFromSessions({ scanSessions, context });
     const now = Date.now();
-    const rows = agentSessionEntries({ scanSessions, context }).map(({ tag, session, indexRow }) =>
+    const rows = agentSessionEntries({ scanSessions, context }).map(({ tag, session, indexRow, loaded }) =>
       agentRow({
         tag,
         session,
         indexRow,
         runtime: mgr.getSessionRuntime?.(session.id),
-        progress: progress.sessionProgressExtras(session.id, session.agent || null, now),
+        // A tag-bound entry is the getSession answer itself; an index row or
+        // a scanned summary is only a projection and still reads the session.
+        progress: progress.sessionProgressExtras(
+          session.id,
+          session.agent || null,
+          now,
+          null,
+          loaded ? { loaded: session } : {}
+        ),
         now,
       })
     );

package/src/session-runtime/services/agent-tool/job-views/session-progress.mjs

@@ -58,9 +58,16 @@ export function liveAgentStatusRow(row) {
 }
 
 export function createSessionProgress({ mgr }) {
-  function sessionProgressExtras(sessionId, role, now = Date.now(), taskStatus = null) {
+  /** `loaded`: the caller's own getSession(sessionId) answer from this same
+   *  read, so the session is not loaded a second time. */
+  function sessionProgressExtras(sessionId, role, now = Date.now(), taskStatus = null, { loaded } = {}) {
     if (!sessionId) return {};
-    const session = mgr.getSession(sessionId);
+    // Only the session's status is read here: the manager's stamp-validated
+    // status lookup spares a whole-transcript read per idle worker per pulse.
+    let sessionStatus;
+    if (loaded !== undefined) sessionStatus = loaded?.status || null;
+    else if (typeof mgr.loadSessionStatus === 'function') sessionStatus = mgr.loadSessionStatus(sessionId) || null;
+    else sessionStatus = mgr.getSession(sessionId)?.status || null;
     const runtime = mgr.getSessionRuntime?.(sessionId) || null;
     const snapshot =
       typeof mgr.getSessionProgressSnapshot === 'function' ? mgr.getSessionProgressSnapshot(sessionId) : null;
@@ -72,8 +79,8 @@ export function createSessionProgress({ mgr }) {
       typeof mgr.getSessionPendingMessageDepth === 'function' ? mgr.getSessionPendingMessageDepth(sessionId) : null;
     return buildAgentTaskProgressFields({
       now,
-      sessionStatus: session?.status || null,
-      runtimeStage: runtime?.stage || snapshot?.stage || session?.status || null,
+      sessionStatus,
+      runtimeStage: runtime?.stage || snapshot?.stage || sessionStatus,
       snapshot,
       runtime,
       policy,
@@ -96,6 +103,8 @@ export function createSessionProgress({ mgr }) {
       stage: progress.worker_stage || runtime?.stage || status,
       // Additive: present only while the worker's turn waits on a user approval.
       ...(runtime?.awaitingUser ? { awaitingUser: runtime.awaitingUser } : {}),
+      // Additive: present only while the worker's turn sits in `task wait`.
+      ...(runtime?.taskWaits > 0 ? { awaitingTask: 'wait' } : {}),
       clientHostPid: session.clientHostPid || null,
       lastStreamDeltaAt: runtime?.lastStreamDeltaAt ? new Date(runtime.lastStreamDeltaAt).toISOString() : null,
       ...progress,

package/src/session-runtime/services/agent-tool/notify.mjs

@@ -9,7 +9,7 @@ import {
 import { clean } from './helpers.mjs';
 import { createEarlyCompletionNotice } from './notify/early-completion.mjs';
 
-export function createNotify(mgr, { notifySessionCompletion } = {}) {
+export function createNotify(mgr, { notifySessionCompletion, onWorkerCompletionQueued = null } = {}) {
   function enqueueCompletionMessage(sessionId, text, meta = {}) {
     const target = clean(sessionId);
     if (!target || typeof mgr.enqueuePendingMessage !== 'function') return false;
@@ -28,8 +28,8 @@ export function createNotify(mgr, { notifySessionCompletion } = {}) {
         logDuplicateSkip('notify-enqueue', { executionId: meta?.execution_id, text: visible });
         return true;
       }
-      // Mark this as a deferred completion/task notification so a later session
-      // resume drops it rather than replaying it out-of-order (owner decision).
+      // Mark this as a completion/task notification: delivery dedupes it by
+      // execution id, and it stays queued (durably) until the model gets it.
       return Boolean(
         mgr.enqueuePendingMessage(
           target,
@@ -67,7 +67,18 @@ export function createNotify(mgr, { notifySessionCompletion } = {}) {
       // appear as a second Lead-level completion card. Agent task completion
       // has its own owner delivery path below; only that terminal handoff
       // crosses the parent boundary.
-      return workerId ? enqueueCompletionMessage(workerId, text, meta) : false;
+      if (!workerId) return false;
+      const queued = enqueueCompletionMessage(workerId, text, meta);
+      // A busy worker takes the completion at its next tool boundary; an idle
+      // one is woken so the result reaches it now, not at its next message.
+      if (queued && typeof onWorkerCompletionQueued === 'function') {
+        setImmediate(() => {
+          try {
+            onWorkerCompletionQueued(workerId);
+          } catch {}
+        });
+      }
+      return queued;
     };
   }