mixdog 0.9.20 → 0.9.22

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/agent/orchestrator/tools/bash-session.mjs

@@ -40,7 +40,7 @@ import { spawn } from 'node:child_process';
 import * as nodeUtil from 'node:util';
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { invalidateBuiltinResultCache, analyzeShellCommandEffects, preflightShellLargeFileProbe } from './builtin.mjs';
+import { invalidateBuiltinResultCache, analyzeShellCommandEffects } from './builtin.mjs';
 import { markCodeGraphDirtyPaths, drainCodeGraphCache } from './code-graph-state.mjs';
 import { maybeRewriteWmicProcessCommand } from './shell-policy.mjs';
 import { _maybeEncodePowerShellCommand } from './shell-command.mjs';
@@ -51,13 +51,15 @@ import { startChildGuardian } from '../../../shared/child-guardian.mjs';
 
 globalThis.__mixdogBashSessionRuntimeLoaded = true;
 
-// Default 600 s (10 min), max 1800 s. Aligned with the one-shot bash tool's
-// 600 s default (builtin/bash-tool.mjs); the persistent shell carries
-// longer-running pipelines (build/test/install) than one-shot calls, so a
-// 120 s default left those workflows timing out at 2 min. Per-call `timeout`
-// still overrides, capped at MAX_TIMEOUT_MS.
-const DEFAULT_TIMEOUT_MS = 600_000;
-const MAX_TIMEOUT_MS = 1_800_000;
+// Claude Code parity (refs/claude-code src/utils/timeouts.ts): default 120 s
+// (2 min), max 600 s (10 min), BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS
+// env overrides (max floored at default). Matches the one-shot bash tool
+// (builtin/bash-tool.mjs); per-call `timeout` still overrides, capped at
+// MAX_TIMEOUT_MS.
+const _envDefaultTimeout = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
+const DEFAULT_TIMEOUT_MS = _envDefaultTimeout > 0 ? _envDefaultTimeout : 120_000;
+const _envMaxTimeout = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
+const MAX_TIMEOUT_MS = Math.max(_envMaxTimeout > 0 ? _envMaxTimeout : 600_000, DEFAULT_TIMEOUT_MS);
 const IDLE_TIMEOUT_MS = 5 * 60_000;
 const MAX_SESSIONS = 10;
 const STDERR_DRAIN_MS = 25;
@@ -643,8 +645,6 @@ async function bash_session(args, cwd = process.cwd(), opts = {}) {
         }
         return requestedCwd;
     })();
-    const largeProbe = await preflightShellLargeFileProbe(command, baseCwd);
-    if (largeProbe) return `Error: ${largeProbe.message}`;
     const rawTimeout = typeof args?.timeout === 'number' ? args.timeout : DEFAULT_TIMEOUT_MS;
     const timeoutMs = rawTimeout;
     const effectiveTimeout = Math.min(Math.max(timeoutMs, 1), wmicRewrite?.timeoutMs || MAX_TIMEOUT_MS);

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -21,7 +21,6 @@ import {
 import {
     analyzeShellCommandEffects,
     foregroundLongCommandHint,
-    preflightShellLargeFileProbe,
 } from './shell-analysis.mjs';
 import {
     cancelBackgroundTask,
@@ -201,8 +200,6 @@ export async function executeBashTool(args, workDir, options = {}) {
         return _execPolicyBlock;
     }
 
-    const largeProbe = await preflightShellLargeFileProbe(command, bashWorkDir);
-    if (largeProbe) return `Error: ${largeProbe.message}`;
     let shellEffects;
     try {
         shellEffects = await analyzeShellCommandEffects(command, bashWorkDir);
@@ -211,9 +208,14 @@ export async function executeBashTool(args, workDir, options = {}) {
     }
     // Keep foreground commands on a long tool-owned timeout. The MCP dispatch
     // layer must not add a shorter fallback ceiling when timeout is omitted.
-    const DEFAULT_BASH_TIMEOUT_MS = 600_000;
-    const DEFAULT_BACKGROUND_BASH_TIMEOUT_MS = 600_000;
-    const MAX_BASH_TIMEOUT_MS = 1_800_000;
+    // Claude Code parity (refs/claude-code src/utils/timeouts.ts): default
+    // 120 s (2 min), max 600 s (10 min); BASH_DEFAULT_TIMEOUT_MS /
+    // BASH_MAX_TIMEOUT_MS env overrides, max floored at default.
+    const _envDefaultTimeout = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
+    const DEFAULT_BASH_TIMEOUT_MS = _envDefaultTimeout > 0 ? _envDefaultTimeout : 120_000;
+    const DEFAULT_BACKGROUND_BASH_TIMEOUT_MS = DEFAULT_BASH_TIMEOUT_MS;
+    const _envMaxTimeout = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
+    const MAX_BASH_TIMEOUT_MS = Math.max(_envMaxTimeout > 0 ? _envMaxTimeout : 600_000, DEFAULT_BASH_TIMEOUT_MS);
     const defaultTimeoutMs = runInBackground
         ? DEFAULT_BACKGROUND_BASH_TIMEOUT_MS
         : DEFAULT_BASH_TIMEOUT_MS;

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -12,6 +12,19 @@ import {
     executionModeSchemaDescription,
 } from '../../../../shared/background-tasks.mjs';
 
+// Shell timeout envelope surfaced in the tool schema. Mirrors Claude Code:
+// default 120 s / max 600 s, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS
+// env overrides, max floored at default. Keep in sync with
+// builtin/bash-tool.mjs and bash-session.mjs.
+function _shellDefaultTimeoutMs() {
+    const parsed = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
+    return parsed > 0 ? parsed : 120_000;
+}
+function _shellMaxTimeoutMs() {
+    const parsed = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
+    return Math.max(parsed > 0 ? parsed : 600_000, _shellDefaultTimeoutMs());
+}
+
 export const BUILTIN_TOOLS = [
     {
         name: 'read',
@@ -59,7 +72,7 @@ export const BUILTIN_TOOLS = [
             properties: {
                 command: { type: 'string', description: 'Command.' },
                 cwd: { type: 'string', description: 'Working directory. Persists across shell calls in a session — omit to reuse the previous command\'s directory (e.g. after cd); pass an absolute path to change it.' },
-                timeout: { type: 'number', description: 'Timeout ms.' },
+                timeout: { type: 'number', description: `Timeout ms. Default ${_shellDefaultTimeoutMs()} (${_shellDefaultTimeoutMs() / 60000} min); long-running commands may raise it up to ${_shellMaxTimeoutMs()} (${_shellMaxTimeoutMs() / 60000} min).` },
                 merge_stderr: { type: 'boolean', description: 'Merge stderr.' },
                 mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
                 shell: { type: 'string', enum: ['bash', 'powershell'], description: 'Force shell. Windows defaults to PowerShell; bash = Git Bash/POSIX.' },

package/src/runtime/agent/orchestrator/tools/patch/orchestrator.mjs

@@ -25,7 +25,7 @@ import {
 } from './paths.mjs';
 import { ensureNativePatchBinaryAvailable } from './native-server.mjs';
 import { assertPathReachable } from '../builtin/fs-reachability.mjs';
-import { dispatchNativePatch } from './dispatch.mjs';
+import { dispatchNativePatch, dispatchJsPatchEntries } from './dispatch.mjs';
 import { normalizeOutputPath } from '../builtin.mjs';
 import {
   planV4ARenameSections,
@@ -242,17 +242,12 @@ async function apply_patch(args, cwd, options = {}) {
     }
     const insideEntries = entries.filter((entry) => !isResolvedPathOutsideBase(entry.fullPath, basePath));
     const outsideEntries = entries.filter((entry) => isResolvedPathOutsideBase(entry.fullPath, basePath));
-    if (outsideEntries.length > 0) {
-      const rels = outsideEntries.map((e) => normalizeOutputPath(e.fullPath || e.displayPath || '(unknown)')).join(', ');
-      return wrapPatchMutationOutput(
-        `Error: apply_patch target resolves outside base path (../ or absolute not allowed): ${rels}`,
-        mutationPlan,
-        { backend: 'native-patch' },
-      );
-    }
     const parsedInside = (parsed || []).filter(
       (entry) => !isResolvedPathOutsideBase(parsedEntryResolvedPath(entry, basePath), basePath),
     );
+    const backend = outsideEntries.length > 0
+      ? (insideEntries.length > 0 ? 'native+js-patch' : 'js-patch')
+      : 'native-patch';
     const resultParts = [];
     if (insideEntries.length > 0) {
       const nativePatchStr = rewriteHeaderPaths(renderParsedUnifiedPatch(parsedInside), headerRewrites);
@@ -268,11 +263,26 @@ async function apply_patch(args, cwd, options = {}) {
         parsed: parsedInside,
       });
       if (isPatchErrorText(nativeResult)) {
-        if (resultParts.length > 0) return wrapPatchMutationOutput(nativeResult, mutationPlan, { backend: 'native-patch' });
-        return wrapPatchMutationOutput(nativeResult, mutationPlan, { backend: 'native-patch' });
+        return wrapPatchMutationOutput(nativeResult, mutationPlan, { backend });
       }
       resultParts.push(nativeResult);
     }
+    if (outsideEntries.length > 0) {
+      // Out-of-base targets are applied via the JS dispatcher (no base-path
+      // confinement); write permission is enforced at the hook layer.
+      const jsResult = await dispatchJsPatchEntries({
+        rows: outsideEntries,
+        parsed,
+        basePath,
+        dryRun,
+        fuzzy,
+        readStateScope,
+      });
+      if (isPatchErrorText(jsResult)) {
+        return wrapPatchMutationOutput(jsResult, mutationPlan, { backend });
+      }
+      resultParts.push(jsResult);
+    }
     let combined = resultParts.join('\n');
     const renameLines = formatV4ARenameSuccessLines(v4aRenameResults);
     if (renameLines.length > 0 && !isPatchErrorText(combined)) {
@@ -287,9 +297,9 @@ async function apply_patch(args, cwd, options = {}) {
         `hunk-level rejected (rejectPartial=false, V4A): ${rejectedV4AHunks.length}`,
         ...rejectedV4AHunks.map((r) => `  REJECT ${r.file || '(unknown)'} — ${String(r.reason || '').split(';')[0].trim()}`),
       ];
-      return wrapPatchMutationOutput(`${combined}\n${tail.join('\n')}`, mutationPlan, { backend: 'native-patch' });
+      return wrapPatchMutationOutput(`${combined}\n${tail.join('\n')}`, mutationPlan, { backend });
     }
-    return wrapPatchMutationOutput(combined, mutationPlan, { backend: 'native-patch' });
+    return wrapPatchMutationOutput(combined, mutationPlan, { backend });
   }));
 }
 

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);