mixdog 0.9.20 → 0.9.21

package/src/runtime/agent/orchestrator/providers/grok-oauth.mjs

@@ -308,10 +308,7 @@ export function forgetGrokOAuthCredentials() {
 }
 
 let _refreshInFlight = null;
-async function refreshTokens(tokens) {
-    if (!tokens?.refresh_token) {
-        throw new Error('[grok-oauth] refresh token not available — open /providers in mixdog to sign in again');
-    }
+async function _postRefresh(tokens) {
     const tokenEndpoint = tokens.token_endpoint
         ? assertTrustedXaiEndpoint(tokens.token_endpoint, 'token endpoint')
         : (await fetchDiscovery()).token_endpoint;
@@ -365,6 +362,34 @@ async function refreshTokens(tokens) {
     }
 }
 
+// 16 mixdog processes share one grok-oauth.json and xAI rotates refresh
+// tokens single-use. Re-read the store immediately before the network POST so
+// a peer's just-completed rotation is adopted instead of spending our
+// (now-stale) refresh_token; on invalid_grant, re-read once and retry with a
+// peer-rotated refresh_token before propagating.
+async function refreshTokens(tokens, { force = false } = {}) {
+    if (!tokens?.refresh_token) {
+        throw new Error('[grok-oauth] refresh token not available — open /providers in mixdog to sign in again');
+    }
+    const disk = _loadOwnTokens();
+    const validAfter = Date.now() + (force ? 0 : TOKEN_REFRESH_SKEW_MS);
+    if (disk?.access_token && disk.access_token !== tokens.access_token
+        && (!disk.expires_at || disk.expires_at >= validAfter)) {
+        return disk;
+    }
+    try {
+        return await _postRefresh(tokens);
+    } catch (err) {
+        if (err?.isInvalidGrant) {
+            const rotated = _loadOwnTokens();
+            if (rotated?.refresh_token && rotated.refresh_token !== tokens.refresh_token) {
+                return await _postRefresh(rotated);
+            }
+        }
+        throw err;
+    }
+}
+
 // --- Model catalog cache (24h disk TTL) ---
 const _modelCache = makeModelCache({
     fileName: 'grok-oauth-models.json',
@@ -530,6 +555,9 @@ export class GrokOAuthProvider {
     tokens = null;
     _inner = null;
     _innerKey = null;
+    // Grace window after a non-force refresh failure: keep serving the current
+    // still-valid access_token instead of thrashing the shared refresh_token.
+    _refreshFallbackUntil = 0;
 
     constructor(config) {
         this.config = config || {};
@@ -553,15 +581,44 @@ export class GrokOAuthProvider {
             if (disk?.access_token) this.tokens = disk;
             this._lastDiskScan = ownM;
         }
+        if (!forceRefresh && this._refreshFallbackUntil > Date.now() && this.tokens?.access_token
+            && (!this.tokens.expires_at || this.tokens.expires_at > Date.now())) {
+            return this.tokens;
+        }
         const expiring = this.tokens.expires_at
             && this.tokens.expires_at < Date.now() + TOKEN_REFRESH_SKEW_MS;
         if (forceRefresh || expiring) {
-            if (_refreshInFlight) {
-                this.tokens = await _refreshInFlight;
-            } else {
-                _refreshInFlight = refreshTokens(this.tokens)
-                    .finally(() => { _refreshInFlight = null; });
-                this.tokens = await _refreshInFlight;
+            const currentToken = this.tokens?.access_token || null;
+            try {
+                if (_refreshInFlight) {
+                    const shared = await _refreshInFlight;
+                    this.tokens = shared;
+                    // A forced caller must not accept a shared non-force result
+                    // that merely handed back its own prior token: start a fresh
+                    // forced refresh instead (mirror openai-oauth).
+                    if (forceRefresh && shared?.access_token === currentToken) {
+                        if (!_refreshInFlight) {
+                            _refreshInFlight = refreshTokens(this.tokens, { force: true })
+                                .finally(() => { _refreshInFlight = null; });
+                        }
+                        this.tokens = await _refreshInFlight;
+                    }
+                } else {
+                    _refreshInFlight = refreshTokens(this.tokens, { force: forceRefresh })
+                        .finally(() => { _refreshInFlight = null; });
+                    this.tokens = await _refreshInFlight;
+                }
+                this._refreshFallbackUntil = 0;
+            } catch (err) {
+                // Non-force failure while the current token is still valid: serve
+                // it under a grace window rather than throwing (mirror openai-oauth).
+                if (!forceRefresh && currentToken
+                    && (!this.tokens?.expires_at || this.tokens.expires_at > Date.now())) {
+                    this._refreshFallbackUntil = Date.now() + TOKEN_REFRESH_SKEW_MS;
+                    process.stderr.write(`[grok-oauth] Refresh failed (${String(err?.message || err).slice(0, 120)}); using still-valid current token\n`);
+                    return this.tokens;
+                }
+                throw err;
             }
         }
         return this.tokens;

package/src/runtime/agent/orchestrator/providers/openai-compat.mjs

@@ -173,6 +173,9 @@ export class OpenAICompatProvider {
             return await this._doSend(messages, model, tools, sendOpts);
         } catch (err) {
             if (err.message && (err.message.includes('401') || err.message.includes('403'))) {
+                if (err.liveTextEmitted === true || err.emittedToolCall === true || err.unsafeToRetry === true) {
+                    throw err;
+                }
                 process.stderr.write(`[provider] Auth error, re-reading config...\n`);
                 this.reloadApiKey();
                 return await this._doSend(messages, model, tools, sendOpts);

package/src/runtime/agent/orchestrator/providers/openai-oauth-http-sse.mjs

@@ -27,6 +27,13 @@ import { createLeakGuard, createToolCallDedupe, dedupeToolCallList } from './ant
 import { customToolCallFromResponseItem } from './custom-tool-wire.mjs';
 import { CODEX_OAUTH_ORIGINATOR, CODEX_RESPONSES_URL, _displayCodexModel } from './openai-oauth.mjs';
 
+// Public OpenAI Responses API endpoint for the api-key `openai` provider.
+// The openai-direct WS transport hits the same origin (openai-ws-pool
+// OPENAI_WS_URL = wss://api.openai.com/v1/responses); this HTTP/SSE fallback
+// mirrors it so OpenAIDirectProvider can fall back off WebSocket like
+// openai-oauth. Same Responses SSE wire format, only endpoint + auth differ.
+const OPENAI_DIRECT_RESPONSES_URL = 'https://api.openai.com/v1/responses';
+
 export function _envFlag(name, fallback = true) {
     const raw = process.env[name];
     if (raw == null || raw === '') return fallback;
@@ -116,6 +123,18 @@ function _pushOutputTextAnnotations(part, citations, citationKeys) {
 }
 
 function _buildOpenAIHttpFallbackHeaders({ auth, cacheKey }) {
+    if (auth?.type === 'openai-direct') {
+        // Public API-key auth: Bearer <OPENAI_API_KEY>, no chatgpt-account-id /
+        // originator (mirrors openai-ws-pool _buildHandshakeHeaders' direct
+        // branch). session_id anchors are an OAuth-backend behavior, so omit
+        // them — the public API keys its prefix cache off body.prompt_cache_key.
+        return {
+            Authorization: `Bearer ${auth.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
+            'x-client-request-id': randomBytes(16).toString('hex'),
+        };
+    }
     const headers = {
         Authorization: `Bearer ${auth.access_token}`,
         'Content-Type': 'application/json',
@@ -189,10 +208,13 @@ export async function sendViaHttpSse({
     );
     const headers = _buildOpenAIHttpFallbackHeaders({ auth, cacheKey });
     const fetchStartedAt = Date.now();
+    const responsesUrl = auth?.type === 'openai-direct'
+        ? OPENAI_DIRECT_RESPONSES_URL
+        : CODEX_RESPONSES_URL;
     let response;
     try {
         try { onStageChange?.('requesting'); } catch {}
-        response = await fetchFn(CODEX_RESPONSES_URL, {
+        response = await fetchFn(responsesUrl, {
             method: 'POST',
             headers,
             body: JSON.stringify(body),
@@ -304,6 +326,17 @@ export async function sendViaHttpSse({
     // a second attempt.
     let emittedText = false;
 
+    // Tool-emit invariant (mirrors emittedText, WS path's emittedToolCall): set
+    // once onToolCall has actually dispatched a call. A failure afterwards is
+    // non-retryable — the side-effecting tool already ran, and any upstream
+    // retry/fallback would double-execute it. Stamped onto errors below so
+    // shouldFallbackTransport / the WS auth-retry gate refuse to reissue.
+    let emittedToolCall = false;
+    const _stampToolSafety = (err) => {
+        if (emittedToolCall && err) { try { err.emittedToolCall = true; err.unsafeToRetry = true; } catch {} }
+        return err;
+    };
+
     // Single-emit guard for tool calls (matches the WS path's
     // emittedToolCall intent). The HTTP/SSE event stream can surface the
     // same function_call across multiple frames — response.function_call_arguments.done,
@@ -324,6 +357,7 @@ export async function sendViaHttpSse({
         if (emittedToolCallIds.has(call.id)) return;
         emittedToolCallIds.add(call.id);
         if (!_toolDedupe.shouldDispatch(call.name, call.arguments)) return;
+        emittedToolCall = true;
         try { onToolCall?.(call); } catch {}
     };
 
@@ -676,6 +710,9 @@ export async function sendViaHttpSse({
         // Live-text invariant: once a non-empty chunk has been relayed it
         // cannot be withdrawn — flag the error so no upstream layer retries.
         if (emittedText && err) { try { err.liveTextEmitted = true; err.unsafeToRetry = true; } catch {} }
+        // Tool-emit invariant: an error after a dispatched tool call must not
+        // reissue the turn (double-execution). Stamp emittedToolCall too.
+        _stampToolSafety(err);
         throw err;
     } finally {
         _clearSemanticIdle();
@@ -688,10 +725,10 @@ export async function sendViaHttpSse({
 
     const unresolved = toolCalls.find(t => t._pendingItemId);
     if (unresolved) {
-        throw new Error(`OpenAI OAuth HTTP fallback function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`);
+        throw _stampToolSafety(new Error(`OpenAI OAuth HTTP fallback function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`));
     }
     if (!completed && !content && !toolCalls.length) {
-        throw new Error('OpenAI OAuth HTTP fallback ended before response.completed');
+        throw _stampToolSafety(new Error('OpenAI OAuth HTTP fallback ended before response.completed'));
     }
 
     const liveModel = model || useModel;

package/src/runtime/agent/orchestrator/providers/openai-ws.mjs

@@ -16,6 +16,9 @@ import { sendViaWebSocket } from './openai-oauth-ws.mjs';
 import { buildRequestBody } from './openai-oauth.mjs';
 import { enrichModels } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
+import { sendViaHttpSse, _envFlag } from './openai-oauth-http-sse.mjs';
+import { shouldFallbackTransport } from './retry-classifier.mjs';
+import { loadConfig } from '../config.mjs';
 import {
     resolveProviderCacheKey,
     resolveProviderPromptCacheLane,
@@ -52,6 +55,23 @@ export class OpenAIDirectProvider {
         if (!k) throw new Error('OPENAI_API_KEY not configured (providers.openai.apiKey)');
         return k;
     }
+    // Auth-recovery mirror of openai-compat.reloadApiKey: on a 401/403 the key
+    // was likely rotated in config after this provider instance was built, so
+    // re-read providers.openai.apiKey from disk before the single retry.
+    // Returns the fresh key (or null if none) — no client to rebuild here since
+    // the WS/HTTP transports take the key per-call via the `auth` object.
+    reloadApiKey() {
+        try {
+            const freshConfig = loadConfig();
+            const cfg = freshConfig.providers?.openai;
+            const newKey = cfg?.apiKey || this.config.apiKey;
+            if (newKey) {
+                this.config = { ...(this.config || {}), ...(cfg || {}), apiKey: newKey };
+                return newKey;
+            }
+        } catch { /* best effort */ }
+        return null;
+    }
     async send(messages, model, tools, sendOpts) {
         const opts = sendOpts || {};
         const onStageChange = typeof opts.onStageChange === 'function' ? opts.onStageChange : null;
@@ -109,10 +129,8 @@ export class OpenAIDirectProvider {
         const cacheKey = body.prompt_cache_key || resolveProviderCacheKey(opts, 'openai');
         const iteration = Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null;
         const auth = { type: 'openai-direct', apiKey };
-        return sendViaWebSocket({
-            auth,
+        const common = {
             body,
-            sendOpts: opts,
             onStreamDelta,
             onToolCall,
             onTextDelta,
@@ -122,8 +140,60 @@ export class OpenAIDirectProvider {
             cacheKey,
             iteration,
             useModel,
+        };
+        const dispatchWs = (a) => sendViaWebSocket({
+            ...common,
+            auth: a,
+            sendOpts: opts,
             displayModel: (id) => id,
         });
+        // WS→HTTP/SSE fallback mirrors the openai-oauth wrapper: the shared
+        // HTTP transport now accepts auth.type==='openai-direct' (public
+        // Responses endpoint + Bearer <apiKey>), so the api-key provider gets
+        // the same envelope. Gate via shouldFallbackTransport (denies
+        // 401/403/404/429 + liveTextEmitted/emittedToolCall/unsafeToRetry).
+        const httpFallbackEnabled = _envFlag('MIXDOG_OPENAI_HTTP_FALLBACK', true);
+        const dispatchHttp = (a) => {
+            if (!process.env.MIXDOG_QUIET_PROVIDER_LOG) {
+                process.stderr.write('[openai-ws] WebSocket unhealthy; falling back to HTTP/SSE\n');
+            }
+            return sendViaHttpSse({ ...common, auth: a, opts, fetchFn: opts._fetchFn });
+        };
+        try {
+            return await dispatchWs(auth);
+        } catch (err) {
+            const status = err?.httpStatus;
+            // Live-text/tool invariant: never reissue a turn that already
+            // relayed visible output or dispatched a tool call.
+            const unsafeToRetry = err?.liveTextEmitted === true
+                || err?.emittedToolCall === true
+                || err?.unsafeToRetry === true;
+            // (1) 401/403 → reload apiKey from config and retry once over WS.
+            //     shouldFallbackTransport denies 401/403, so this branch owns
+            //     its own guard.
+            if ((status === 401 || status === 403) && !unsafeToRetry) {
+                process.stderr.write(`[openai-ws] ${status} — reloading apiKey and retrying once\n`);
+                const freshKey = this.reloadApiKey();
+                if (freshKey) {
+                    const retryAuth = { type: 'openai-direct', apiKey: freshKey };
+                    try {
+                        return await dispatchWs(retryAuth);
+                    } catch (retryErr) {
+                        if (shouldFallbackTransport(retryErr, { signal: externalSignal, enabled: httpFallbackEnabled })) {
+                            return await dispatchHttp(retryAuth);
+                        }
+                        throw retryErr;
+                    }
+                }
+                throw err;
+            }
+            // (2) WS transport failure → HTTP/SSE fallback (predicate handles
+            //     the safety denies).
+            if (shouldFallbackTransport(err, { signal: externalSignal, enabled: httpFallbackEnabled })) {
+                return await dispatchHttp(auth);
+            }
+            throw err;
+        }
     }
     async listModels() {
         try {

package/src/runtime/channels/lib/owned-runtime.mjs

@@ -10,6 +10,7 @@ import {
   releaseOwnedChannelLocks,
   clearActiveInstance,
   probeActiveOwner,
+  RUNTIME_ROOT,
 } from "./runtime-paths.mjs";
 // Owned-runtime lifecycle extracted from channels/index.mjs (behavior-
 // preserving): bridge-ownership claim/refresh/loss, backend connect/disconnect,
@@ -52,11 +53,49 @@ export function createOwnedRuntime({
   let bridgeOwnershipRefreshInFlight = null;
   let bridgeOwnershipTimer = null;
   let _memoryDrainTimer = null;
+  // Event-driven ownership signal: an fs.watch on the runtime dir fires the
+  // ownership refresh the instant active-instance.json changes (a newer owner
+  // claims, or the owner releases/clears it), instead of waiting up to 3s for
+  // the poll tick. This shrinks the double-owner window on takeover (the old
+  // owner observes owned=false and tears down in ms) and signals ownership
+  // loss to contenders immediately on release. The 3s timer stays as fallback.
+  let activeInstanceWatcher = null;
+  let _activeInstanceWatchDebounce = null;
+  function armActiveInstanceWatcher() {
+    if (activeInstanceWatcher) return;
+    try {
+      activeInstanceWatcher = fs.watch(RUNTIME_ROOT, { persistent: false }, (_event, filename) => {
+        if (filename && filename !== 'active-instance.json') return;
+        // Coalesce the burst of events an atomic rename/truncate emits.
+        if (_activeInstanceWatchDebounce) return;
+        _activeInstanceWatchDebounce = setTimeout(() => {
+          _activeInstanceWatchDebounce = null;
+          refreshBridgeOwnershipSafe();
+        }, 50);
+        _activeInstanceWatchDebounce.unref?.();
+      });
+      // fs.watch emits 'error' (and an unhandled one CRASHES the worker) when
+      // the watched dir is removed or the handle is invalidated (common on
+      // Windows). Close the dead handle and fall back to the 3s poll, which is
+      // still armed — the event signal is a latency optimization, never the
+      // sole ownership mechanism.
+      activeInstanceWatcher.on('error', (err) => {
+        process.stderr.write(`[ownership] active-instance watch error, falling back to poll: ${err?.message || err}\n`);
+        clearActiveInstanceWatcher();
+      });
+      activeInstanceWatcher.unref?.();
+    } catch { activeInstanceWatcher = null; }
+  }
+  function clearActiveInstanceWatcher() {
+    if (_activeInstanceWatchDebounce) { clearTimeout(_activeInstanceWatchDebounce); _activeInstanceWatchDebounce = null; }
+    if (activeInstanceWatcher) { try { activeInstanceWatcher.close(); } catch {} activeInstanceWatcher = null; }
+  }
   function clearBridgeOwnershipTimer() {
     if (bridgeOwnershipTimer) {
       clearInterval(bridgeOwnershipTimer);
       bridgeOwnershipTimer = null;
     }
+    clearActiveInstanceWatcher();
   }
 function shouldStartEventPipelineRuntime() {
   return getConfig().webhook?.enabled === true || (Array.isArray(getConfig().events?.rules) && getConfig().events.rules.length > 0);
@@ -176,6 +215,9 @@ async function startOwnedRuntime(options = {}) {
   // both-backends-live window.
   const startingBackend = getBackend();
   const claimAfterReady = options.claimAfterReady === true;
+  // Auto-start intent: claim the seat ONLY if it is vacant/stale (never steal a
+  // live owner). Threaded from worker start() (MIXDOG_REMOTE_INTENT=auto).
+  const claimIfVacant = options.claimIfVacant === true;
   // Single-holder correctness: the seat is claimed BEFORE getBackend().connect(),
   // never after. The old make-before-break (claim-after-ready) boot left two
   // gateways connected and contending during the multi-second connect window;
@@ -190,8 +232,29 @@ async function startOwnedRuntime(options = {}) {
   // leave it stuck true and permanently block every future ownership attempt.
   try {
     if (claimAfterReady) {
-      refreshActiveInstance(instanceId, { backendReady: false });
-      logOwnership("boot claim (pre-connect, last-wins)");
+      if (claimIfVacant) {
+        // Auto-start claim-if-vacant. Probe first: a live owner other than us
+        // holds the seat -> back off SILENTLY (no claim, no acquire notify) so
+        // this session stays non-remote. Then claim atomically via the
+        // onlyIfVacant CAS (guards the probe->write TOCTOU: a live owner landing
+        // in that gap aborts the write, leaving the seat untouched).
+        const probe = probeActiveOwner();
+        if (probe.status === 'live' && probe.state?.instanceId && probe.state.instanceId !== instanceId) {
+          bridgeRuntimeStarting = false;
+          logOwnership("autostart backoff (live owner holds seat)");
+          return;
+        }
+        const casResult = refreshActiveInstance(instanceId, { backendReady: false }, { onlyIfVacant: true, timeoutMs: 0 });
+        if (casResult?.instanceId !== instanceId) {
+          bridgeRuntimeStarting = false;
+          logOwnership("autostart backoff (seat claimed by newer owner)");
+          return;
+        }
+        logOwnership("boot claim (pre-connect, claim-if-vacant)");
+      } else {
+        refreshActiveInstance(instanceId, { backendReady: false });
+        logOwnership("boot claim (pre-connect, last-wins)");
+      }
     } else {
       // Try-once (timeoutMs:0): a refresh-path re-acquire must never block on
       // the active-instance lock. Contention throws → caught below and treated
@@ -289,11 +352,18 @@ async function startOwnedRuntime(options = {}) {
       return;
     }
     setBridgeRuntimeConnected(true);
-    if (claimAfterReady) {
-      // First confirmed ownership at boot — tell the parent it holds the seat
-      // exactly once (heartbeat/refresh re-pin ownership but never re-enter).
-      notifyRemoteAcquired();
-    }
+    // Fresh confirmed ownership — tell the parent it holds the seat so it flips
+    // remote ON. Reached ONLY on a not-connected -> connected transition (the
+    // top-of-fn early-return skips already-connected re-ticks), so this fires
+    // exactly once per acquire and covers EVERY win path, not just boot:
+    //   - explicit/auto boot claim (claimAfterReady),
+    //   - the deferred claim when a bridge timer's refreshBridgeOwnership()
+    //     claims a seat vacated by a departing owner (finding 1).
+    // The parent's acquired handler is idempotent (no-op when already remote),
+    // so notifying post-connect — never pre-connect — means a connect FAILURE
+    // below leaves the parent non-remote instead of stuck remote-with-no-bridge
+    // (finding 2).
+    notifyRemoteAcquired();
     // initProviders must complete before scheduler.start() — otherwise the
     // scheduler's first fire can land before the registry is populated and
     // return `Provider "<name>" not found or not enabled`. The previous
@@ -402,15 +472,28 @@ function armBridgeOwnershipTimer() {
     refreshBridgeOwnershipSafe();
   }, 3e3);
   bridgeOwnershipTimer.unref?.();
+  // Arm the event-driven signal alongside the poll fallback.
+  armActiveInstanceWatcher();
+}
+// Guarded IPC send to the parent: no-ops when there is no channel or it is
+// already disconnected, and swallows both the synchronous throw and the async
+// error-callback path of ERR_IPC_CHANNEL_CLOSED (channel closing between the
+// connected check and delivery). Log-and-continue — never crash the worker.
+function sendToParent(message) {
+  if (!process.send || process.connected === false) return;
+  try {
+    process.send(message, undefined, undefined, err => {
+      if (err) process.stderr.write(`[channels] parent IPC send failed: ${err?.message || err}\n`);
+    });
+  } catch (err) {
+    process.stderr.write(`[channels] parent IPC send threw: ${err?.message || err}\n`);
+  }
 }
 // Tell the parent session that this worker LOST the bridge seat to a newer
 // remote session (last-wins). The parent flips its remote mode OFF entirely —
 // exactly one session holds remote; losers fully release, no handover.
 function notifyRemoteSuperseded() {
-  if (!process.send) return;
-  try {
-    process.send({ type: 'notify', method: 'notifications/mixdog/remote', params: { state: 'superseded' } });
-  } catch {}
+  sendToParent({ type: 'notify', method: 'notifications/mixdog/remote', params: { state: 'superseded' } });
 }
 // Symmetric to notifyRemoteSuperseded: tell the parent session this worker
 // ACQUIRED the bridge seat so it flips remote mode ON (badge/transcript writer).
@@ -419,10 +502,7 @@ function notifyRemoteSuperseded() {
 // transition (boot make-before-break, activate when not already owned) — never
 // on a heartbeat refresh — so the parent's idempotent handler sees it once.
 function notifyRemoteAcquired() {
-  if (!process.send) return;
-  try {
-    process.send({ type: 'notify', method: 'notifications/mixdog/remote', params: { state: 'acquired' } });
-  } catch {}
+  sendToParent({ type: 'notify', method: 'notifications/mixdog/remote', params: { state: 'acquired' } });
 }
 async function refreshBridgeOwnership(options = {}) {
   // Coalesce concurrent callers onto the in-flight refresh so getBackend() tool

package/src/runtime/channels/lib/runtime-paths.mjs

@@ -279,6 +279,14 @@ function refreshActiveInstance(instanceId, meta, options) {
     if (options?.onlyIfOwned && (!prev?.instanceId || prev.instanceId !== instanceId)) {
       return undefined;
     }
+    // CAS guard (opt-in via options.onlyIfVacant): auto-start claim-if-vacant.
+    // Abort the write when a live (non-stale) owner OTHER than us already holds
+    // the seat — an auto-start must never steal from a live owner. A stale/dead
+    // prior owner leaves prev=null above, so it does NOT block the claim; an
+    // absent seat (prev=null) is claimable too.
+    if (options?.onlyIfVacant && prev?.instanceId && prev.instanceId !== instanceId) {
+      return undefined;
+    }
     // Drop stale fields (pid/startedAt) written by older server versions.
     const { pid: _legacyPid, startedAt: _legacyStartedAt, ...prevRest } = prev ?? {};
     const identity = buildRuntimeIdentity();
@@ -393,18 +401,21 @@ function refreshActiveInstance(instanceId, meta, options) {
         }
       }
     }
-    // Worker-owned seat: when THIS process is the channels worker and it is
-    // the seat owner (no distinct TUI/supervisor Lead — ownerLeadPid resolves
-    // to our own pid), keep ui_heartbeat_at fresh. A headless worker never
-    // runs the TUI render loop, so an inherited heartbeat (written by a prior
-    // TUI session and carried forward in prevRest) would otherwise go stale at
-    // UI_HEARTBEAT_STALE_MS and falsely flag a live worker-owned seat. A
-    // TUI-owned seat has a distinct supervisor (ownerLeadPid !== our pid), so
-    // this branch is a no-op there and TUI staleness is preserved.
+    // Headless worker-owned seat: THIS process is the channels worker AND no
+    // distinct terminal lead owns the seat (ownerLeadPid resolves to our own
+    // pid). A worker never runs the TUI render loop, so it owns no heartbeat —
+    // it must NOT keep refreshing a ui_heartbeat_at it does not own. An
+    // inherited value (written by a prior TUI session, carried forward in
+    // prevRest) would otherwise be perpetually renewed here and falsely mask a
+    // dead render loop, so DROP it and let pid-only judgment stand.
+    // When a distinct terminal lead owns the seat (ownerLeadPid !== our pid),
+    // this branch is a no-op: the TUI's own heartbeat is carried forward
+    // untouched, so a stale (zombie) render loop still evicts the seat even
+    // while the worker pid is alive.
     const workerOwnsSeat = process.env.MIXDOG_WORKER_MODE === "1"
       && identity.ownerLeadPid === process.pid;
     if (workerOwnsSeat) {
-      next.ui_heartbeat_at = Date.now();
+      delete next.ui_heartbeat_at;
     }
     return { ...preservedExtra, ...next };
   }, writeOpts);

package/src/runtime/channels/lib/worker-main.mjs

@@ -687,7 +687,13 @@ async function start() {
   // takeover" second claim (double reconnect) is gone.
   const _bindingReadyStart = Date.now();
   try {
-    await startOwnedRuntime({ restoreBinding: true, claimAfterReady: true });
+    // Boot claim intent (published by the parent via env before this fork):
+    //   explicit (/remote, --remote) -> last-wins force-takeover.
+    //   auto (config/delayed autoStart) -> claim-if-vacant: take the seat only
+    //   when no live owner holds it, otherwise back off silently (no claim, no
+    //   acquire notify) so a live owner is never stolen.
+    const autoStartClaim = process.env.MIXDOG_REMOTE_INTENT === 'auto';
+    await startOwnedRuntime({ restoreBinding: true, claimAfterReady: true, claimIfVacant: autoStartClaim });
     bindingReadyStatus = "resolved";
     dropTrace("bindingReady.resolve", { elapsedMs: Date.now() - _bindingReadyStart, status: bindingReadyStatus });
     _bindingReadyResolve(true);

package/src/runtime/memory/index.mjs

@@ -164,6 +164,88 @@ function touchDaemonIdleTimer(reason = 'activity') {
   _idleShutdownTimer.unref?.()
 }
 
+// ── Connected-client tracking + prompt shutdown ───────────────────────────
+// The daemon is shared by multiple proxy clients (TUI host + channels worker,
+// potentially several sessions). Each client registers/deregisters over HTTP
+// (see /client/register, /client/deregister in lib/http-router.mjs). When the
+// last client goes away we arm a short grace timer (default 10s) so a quick
+// reconnect keeps the daemon warm, but an actually-closed CLI reaps the daemon
+// in seconds instead of waiting out the 10-minute idle TTL (kept as backstop).
+const MEMORY_CLIENT_GRACE_MS = Math.max(0, Number(process.env.MIXDOG_MEMORY_CLIENT_GRACE_MS) || 10_000)
+const _connectedClients = new Map() // clientPid -> lastSeenMs
+let _everHadClient = false
+let _clientGraceTimer = null
+let _clientSweepTimer = null
+
+function _clientShutdownEnabled() {
+  return MEMORY_DAEMON_MODE && MEMORY_CLIENT_GRACE_MS > 0
+}
+
+function pruneDeadClients() {
+  for (const pid of [..._connectedClients.keys()]) {
+    if (!_isPidAliveLocal(pid)) _connectedClients.delete(pid)
+  }
+}
+
+function cancelClientGrace() {
+  if (_clientGraceTimer) {
+    try { clearTimeout(_clientGraceTimer) } catch {}
+    _clientGraceTimer = null
+  }
+}
+
+function armClientGrace(reason = 'last client gone') {
+  if (!_clientShutdownEnabled() || _clientGraceTimer) return
+  _clientGraceTimer = setTimeout(() => {
+    _clientGraceTimer = null
+    pruneDeadClients()
+    if (_connectedClients.size > 0) return
+    __mixdogMemoryLog(`[memory-service] daemon client grace elapsed (${reason}); shutting down\n`)
+    stop()
+      .then(() => process.exit(0))
+      .catch((e) => {
+        __mixdogMemoryLog(`[memory-service] daemon client-grace shutdown failed: ${e?.message || e}\n`)
+        process.exit(1)
+      })
+  }, MEMORY_CLIENT_GRACE_MS)
+  _clientGraceTimer.unref?.()
+}
+
+function startClientSweep() {
+  if (_clientSweepTimer || !_clientShutdownEnabled()) return
+  // Reap clients that died without deregistering so a crashed CLI still frees
+  // the daemon in grace-scale time rather than waiting for the idle TTL.
+  const interval = Math.max(1000, Math.min(MEMORY_CLIENT_GRACE_MS, 5000))
+  _clientSweepTimer = setInterval(() => {
+    pruneDeadClients()
+    if (_everHadClient && _connectedClients.size === 0) armClientGrace('all clients gone (sweep)')
+  }, interval)
+  _clientSweepTimer.unref?.()
+}
+
+function registerClient(clientPid) {
+  const pid = parsePositivePid(clientPid)
+  if (!pid) return true
+  // Reject registration once shutdown has begun. stop() sets _stopPromise
+  // synchronously (before its first await) and, in daemon mode, always ends
+  // in process.exit — so a daemon that is draining will never revive. Signal
+  // the proxy (via a distinct 503) to respawn a fresh daemon instead of
+  // binding to this dying one, which would fail the subsequent /api/tool.
+  if (_stopPromise) return false
+  _connectedClients.set(pid, Date.now())
+  _everHadClient = true
+  cancelClientGrace()
+  startClientSweep()
+  return true
+}
+
+function deregisterClient(clientPid) {
+  const pid = parsePositivePid(clientPid)
+  if (pid) _connectedClients.delete(pid)
+  pruneDeadClients()
+  if (_everHadClient && _connectedClients.size === 0) armClientGrace('last client deregistered')
+}
+
 function advertiseMemoryPort(boundPort, attempt = 0) {
   if (!Number.isFinite(boundPort) || boundPort <= 0) return
   _currentAdvertisedPort = boundPort
@@ -660,6 +742,9 @@ const _httpRouter = createHttpRouter({
   handleMemoryAction,
   handleToolCall,
   stop,
+  registerClient,
+  deregisterClient,
+  getDraining: () => _stopPromise != null,
   getCycle1CallLlm,
   getTraceDb: () => _traceDb,
   setTraceDb: (v) => { _traceDb = v },
@@ -720,6 +805,11 @@ export async function stop() {
       try { clearTimeout(_idleShutdownTimer) } catch {}
       _idleShutdownTimer = null
     }
+    cancelClientGrace()
+    if (_clientSweepTimer) {
+      try { clearInterval(_clientSweepTimer) } catch {}
+      _clientSweepTimer = null
+    }
     await stopLlmWorker()
     resetHttpListenErrorHandler()
     if (_httpBoundPort != null || _httpReadyPromise) {