mixdog 0.7.17 → 0.7.18

package/src/agent/orchestrator/session/loop.mjs

@@ -8,7 +8,7 @@ import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
 import { collectSkillsCached, loadSkillContent } from '../context/collect.mjs';
 import { traceBridgeLoop, traceBridgeTool, traceBridgeTrim, estimateProviderPayloadBytes, messagePrefixHash } from '../bridge-trace.mjs';
 import { markSessionToolCall, updateSessionStage, SessionClosedError, getSessionAbortSignal } from './manager.mjs';
-import { trimMessages, estimateRequestReserveTokens } from './trim.mjs';
+import { trimMessages, estimateMessagesTokens, estimateRequestReserveTokens } from './trim.mjs';
 import { isContextOverflowError } from '../providers/retry-classifier.mjs';
 import { classifyBashFileLookupCommand, stripSoftWarns } from '../tool-loop-guard.mjs';
 import { maybeOffloadToolResult } from './tool-result-offload.mjs';
@@ -145,7 +145,7 @@ const _require = createRequire(import.meta.url);
 const _hooksLib = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../hooks/lib/permission-evaluator.cjs');
 const { evaluatePermission: _evaluatePermission } = _require(_hooksLib);
 const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
-const SAFETY_TRIM_PERCENT = 0.90;
+const SAFETY_TRIM_PERCENT = 1.00;
 // Stricter budget used for the one-shot retry after a provider rejects a send
 // with a context-window-exceeded error. 0.60×contextWindow forces older
 // non-system / non-latest turns to drop hard so the retry fits even when the
@@ -154,6 +154,47 @@ const SAFETY_TRIM_PERCENT = 0.90;
 // retry block around provider.send below.
 const OVERFLOW_RETRY_TRIM_PERCENT = 0.60;
 
+function estimateMessagesTokensSafe(messages) {
+    try { return estimateMessagesTokens(messages); }
+    catch { return null; }
+}
+
+class BridgeContextOverflowError extends Error {
+    constructor({ stage, sessionId, provider, model, contextWindow, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+        const target = [provider, model].filter(Boolean).join('/') || 'target model';
+        const causeMsg = cause && cause.message ? `: ${cause.message}` : '';
+        super(
+            `bridge context overflow (${target}, stage=${stage || 'trim'}): ` +
+            `latest turn cannot fit target context budget=${budgetTokens ?? 'unknown'} ` +
+            `reserve=${reserveTokens ?? 'unknown'} contextWindow=${contextWindow ?? 'unknown'} ` +
+            `messageTokensEst=${messageTokensEst ?? 'unknown'}${causeMsg}`,
+        );
+        this.name = 'BridgeContextOverflowError';
+        this.code = 'BRIDGE_CONTEXT_OVERFLOW';
+        this.sessionId = sessionId || null;
+        this.provider = provider || null;
+        this.model = model || null;
+        this.contextWindow = contextWindow ?? null;
+        this.budgetTokens = budgetTokens ?? null;
+        this.reserveTokens = reserveTokens ?? null;
+        this.messageTokensEst = messageTokensEst ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+function bridgeContextOverflowError({ stage, sessionId, sessionRef, model, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+    return new BridgeContextOverflowError({
+        stage,
+        sessionId,
+        provider: sessionRef?.provider || null,
+        model: sessionRef?.model || model || null,
+        contextWindow: sessionRef?.contextWindow ?? null,
+        budgetTokens,
+        reserveTokens,
+        messageTokensEst,
+    }, cause);
+}
+
 // Cache-hit results always inline the cached body. The earlier size-gated
 // `[cache-hit-ref]` branch confused bridge workers whose context did not
 // contain the referenced prior tool_result, triggering shell-cat detours.
@@ -719,7 +760,41 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             const beforeCount = messages.length;
             let beforeBytes = null;
             try { beforeBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8'); } catch { beforeBytes = null; }
-            const trimmed = trimMessages(messages, safetyBudget, { reserveTokens });
+            const messageTokensEst = estimateMessagesTokensSafe(messages);
+            let trimmed;
+            try {
+                trimmed = trimMessages(messages, safetyBudget, { reserveTokens });
+            } catch (trimErr) {
+                traceBridgeTrim({
+                    sessionId,
+                    iteration: iterations + 1,
+                    stage: 'pre_send',
+                    prune_count: 0,
+                    trim_changed: false,
+                    input_prefix_hash: messagePrefixHash(messages),
+                    before_count: beforeCount,
+                    after_count: messages.length,
+                    before_bytes: beforeBytes,
+                    after_bytes: beforeBytes,
+                    context_window: sessionRef.contextWindow,
+                    budget_tokens: safetyBudget,
+                    reserve_tokens: reserveTokens,
+                    message_tokens_est: messageTokensEst,
+                    provider: sessionRef.provider,
+                    model: sessionRef.model || model,
+                    error: trimErr && trimErr.message ? trimErr.message : String(trimErr),
+                    error_code: 'BRIDGE_CONTEXT_OVERFLOW',
+                });
+                throw bridgeContextOverflowError({
+                    stage: 'pre_send',
+                    sessionId,
+                    sessionRef,
+                    model,
+                    budgetTokens: safetyBudget,
+                    reserveTokens,
+                    messageTokensEst,
+                }, trimErr);
+            }
             const trimChanged = messagesArrayChanged(messages, trimmed);
             const pruneCount = Math.max(beforeCount - trimmed.length, 0);
             if (trimChanged) {
@@ -742,6 +817,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             traceBridgeTrim({
                 sessionId,
                 iteration: iterations + 1,
+                stage: 'pre_send',
                 prune_count: pruneCount,
                 trim_changed: trimChanged,
                 input_prefix_hash: messagePrefixHash(messages),
@@ -749,6 +825,12 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 after_count: messages.length,
                 before_bytes: beforeBytes,
                 after_bytes: afterBytes,
+                context_window: sessionRef.contextWindow,
+                budget_tokens: safetyBudget,
+                reserve_tokens: reserveTokens,
+                message_tokens_est: messageTokensEst,
+                provider: sessionRef.provider,
+                model: sessionRef.model || model,
             });
         }
         const nextIteration = iterations + 1;
@@ -875,9 +957,68 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             }
             const overflowBudget = Math.floor(sessionRef.contextWindow * OVERFLOW_RETRY_TRIM_PERCENT);
             const overflowReserve = estimateRequestReserveTokens(sendTools.length ? sendTools : tools);
-            const retrimmed = trimMessages(messages, overflowBudget, { reserveTokens: overflowReserve });
+            const beforeCount = messages.length;
+            let beforeBytes = null;
+            try { beforeBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8'); } catch { beforeBytes = null; }
+            const messageTokensEst = estimateMessagesTokensSafe(messages);
+            let retrimmed;
+            try {
+                retrimmed = trimMessages(messages, overflowBudget, { reserveTokens: overflowReserve });
+            } catch (trimErr) {
+                traceBridgeTrim({
+                    sessionId,
+                    iteration: nextIteration,
+                    stage: 'overflow_retry',
+                    prune_count: 0,
+                    trim_changed: false,
+                    input_prefix_hash: messagePrefixHash(messages),
+                    before_count: beforeCount,
+                    after_count: messages.length,
+                    before_bytes: beforeBytes,
+                    after_bytes: beforeBytes,
+                    context_window: sessionRef.contextWindow,
+                    budget_tokens: overflowBudget,
+                    reserve_tokens: overflowReserve,
+                    message_tokens_est: messageTokensEst,
+                    provider: sessionRef.provider,
+                    model: sessionRef.model || model,
+                    error: trimErr && trimErr.message ? trimErr.message : String(trimErr),
+                    error_code: 'BRIDGE_CONTEXT_OVERFLOW',
+                });
+                throw bridgeContextOverflowError({
+                    stage: 'overflow_retry',
+                    sessionId,
+                    sessionRef,
+                    model,
+                    budgetTokens: overflowBudget,
+                    reserveTokens: overflowReserve,
+                    messageTokensEst,
+                }, trimErr);
+            }
+            const trimChanged = messagesArrayChanged(messages, retrimmed);
+            const pruneCount = Math.max(beforeCount - retrimmed.length, 0);
             messages.length = 0;
             messages.push(...retrimmed);
+            let afterBytes = null;
+            try { afterBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8'); } catch { afterBytes = null; }
+            traceBridgeTrim({
+                sessionId,
+                iteration: nextIteration,
+                stage: 'overflow_retry',
+                prune_count: pruneCount,
+                trim_changed: trimChanged,
+                input_prefix_hash: messagePrefixHash(messages),
+                before_count: beforeCount,
+                after_count: messages.length,
+                before_bytes: beforeBytes,
+                after_bytes: afterBytes,
+                context_window: sessionRef.contextWindow,
+                budget_tokens: overflowBudget,
+                reserve_tokens: overflowReserve,
+                message_tokens_est: messageTokensEst,
+                provider: sessionRef.provider,
+                model: sessionRef.model || model,
+            });
             // The transcript prefix changed; the server-side conversation anchor
             // (previous_response_id / WS continuation) is now invalid. Drop
             // providerState so the retry starts a fresh chain instead of

package/src/agent/orchestrator/session/trim.mjs

@@ -18,7 +18,7 @@ function messageEstimateText(m) {
 function estimateMessageTokens(m) {
     return estimateTokens(messageEstimateText(m)) + 4;
 }
-function estimateMessagesTokens(messages) {
+export function estimateMessagesTokens(messages) {
     return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
 }
 

package/src/agent/orchestrator/tools/builtin/arg-guard.mjs

@@ -67,6 +67,35 @@ function isNonEmptyString(v) {
     return typeof v === 'string' && v.length > 0;
 }
 
+function hasMeaningfulWriteSingle(a) {
+    return (isNonEmptyString(a?.path) || isNonEmptyString(a?.file_path))
+        && hasOwn(a, 'content')
+        && typeof a.content === 'string';
+}
+
+function isInertWriteEntry(w) {
+    return w && typeof w === 'object'
+        && !isNonEmptyString(w.path)
+        && !isNonEmptyString(w.file_path)
+        && (!hasOwn(w, 'content') || w.content === '');
+}
+
+function hasMeaningfulEditSingle(a) {
+    return hasOwn(a, 'old_string')
+        && hasOwn(a, 'new_string')
+        && isNonEmptyString(a.old_string)
+        && typeof a.new_string === 'string';
+}
+
+function isInertEditEntry(e) {
+    return e && typeof e === 'object'
+        && !isNonEmptyString(e.path)
+        && !isNonEmptyString(e.file_path)
+        && (!hasOwn(e, 'old_string') || e.old_string === '')
+        && (!hasOwn(e, 'new_string') || e.new_string === '')
+        && (!hasOwn(e, 'replace_all') || e.replace_all === false || e.replace_all === null || e.replace_all === undefined);
+}
+
 function isStringOrStringArray(v) {
     if (typeof v === 'string') return true;
     if (!Array.isArray(v) || v.length === 0) return false;
@@ -216,8 +245,11 @@ function guardEdit(a) {
     if (op === 'rename') {
         return guardRename(a);
     }
-    const hasSingle = hasOwn(a, 'old_string') && hasOwn(a, 'new_string');
-    const hasBatch = hasOwn(a, 'edits') && Array.isArray(a.edits) && a.edits.length > 0;
+    if (Array.isArray(a.edits)) {
+        a.edits = a.edits.filter((e) => !isInertEditEntry(e));
+    }
+    const hasSingle = hasMeaningfulEditSingle(a);
+    const hasBatch = Array.isArray(a.edits) && a.edits.length > 0;
     if (hasSingle && hasBatch) {
         return 'Error: edit requires either (old_string + new_string) OR edits[], not both';
     }
@@ -231,16 +263,39 @@ function guardEdit(a) {
         if (typeof a.old_string !== 'string') {
             return `Error: edit arg "old_string" must be a string (got ${describeType(a.old_string)})`;
         }
+        if (a.old_string.length === 0) {
+            return 'Error: edit arg "old_string" must be non-empty';
+        }
         if (typeof a.new_string !== 'string') {
             return `Error: edit arg "new_string" must be a string (got ${describeType(a.new_string)})`;
         }
     }
+    if (hasBatch) {
+        for (let i = 0; i < a.edits.length; i++) {
+            const e = a.edits[i];
+            if (!e || typeof e !== 'object') {
+                return `Error: edit edits[${i}] must be an object with old_string + new_string`;
+            }
+            if (typeof e.old_string !== 'string') {
+                return `Error: edit edits[${i}].old_string must be a string (got ${describeType(e.old_string)})`;
+            }
+            if (e.old_string.length === 0) {
+                return `Error: edit edits[${i}].old_string must be non-empty`;
+            }
+            if (typeof e.new_string !== 'string') {
+                return `Error: edit edits[${i}].new_string must be a string (got ${describeType(e.new_string)})`;
+            }
+        }
+    }
     return null;
 }
 
 function guardWrite(a) {
-    const hasSingle = (hasOwn(a, 'path') || hasOwn(a, 'file_path')) && hasOwn(a, 'content');
-    const hasBatch = hasOwn(a, 'writes') && Array.isArray(a.writes) && a.writes.length > 0;
+    if (Array.isArray(a.writes)) {
+        a.writes = a.writes.filter((w) => !isInertWriteEntry(w));
+    }
+    const hasSingle = hasMeaningfulWriteSingle(a);
+    const hasBatch = Array.isArray(a.writes) && a.writes.length > 0;
     if (hasSingle && hasBatch) {
         return 'Error: write requires either (path + content) OR writes[], not both';
     }
@@ -265,8 +320,9 @@ function guardWrite(a) {
             if (!w || typeof w !== 'object') {
                 return `Error: write writes[${i}] must be an object with path + content`;
             }
-            if (typeof w.path !== 'string' || !w.path) {
-                return `Error: write writes[${i}].path must be a non-empty string (got ${describeType(w.path)})`;
+            const p = hasOwn(w, 'path') ? w.path : w.file_path;
+            if (typeof p !== 'string' || !p) {
+                return `Error: write writes[${i}].path must be a non-empty string (got ${describeType(p)})`;
             }
             if (typeof w.content !== 'string') {
                 return `Error: write writes[${i}].content must be a string (got ${describeType(w.content)})`;

package/src/agent/orchestrator/tools/graph-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.17",
+  "version": "0.7.18",
   "_comment": "Rewritten by .github/workflows/graph-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-graph binary on the GitHub release. A local cargo build under native/mixdog-graph/target/release always takes precedence at runtime. (v0.5.236 entries were filled manually after CI's commit step hit detached HEAD; the workflow now checks out ref: main so future releases self-update.)",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-darwin-arm64",
-      "sha256": "53f45f8373000fb55ccb49f9b03af0275ca2a663f924b68ee8ded4535e14445a"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-arm64",
+      "sha256": "34653a7cdf457295c4835fa9819627e9690c323b6012e6f571259478406bbe04"
     },
     "darwin-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-darwin-x64",
-      "sha256": "347dc5e1b39dfc33ae07e01319b085c1f1ee775a70be1ac09f7b0d2954b36591"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-x64",
+      "sha256": "1c0648ed8a1b9fd2d8bc44d85b91262cb11e0773d2280d6ec351ee1ff1c579f0"
     },
     "linux-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-linux-arm64",
-      "sha256": "7648be2c4bc89bef837b4843639a9ab38c382ba103518ad52d4439587521542f"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-graph-linux-arm64",
+      "sha256": "71c9d69125b97e93466e5a5613c00db2d797c1f25cc4237e776225574c5f6970"
     },
     "linux-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-linux-x64",
-      "sha256": "6e5a1b548c69c3a51170eb11c769985be7ca7029ede2597b19304c8dc106eded"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-graph-linux-x64",
+      "sha256": "4800a7ac77b777ddb5862f252cdc00b55230455921e0c58416d7a77b120604a7"
     },
     "win32-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-win32-x64.exe",
-      "sha256": "cd263b6bfd3d7371857f498fb53d1d67b4b4cc06dd4d9855408337390a56cee2"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-graph-win32-x64.exe",
+      "sha256": "1d0d62f5b78965c7d5b05ebc7cf7bdef1a3e14cc2600aa205ca762e56c446934"
     }
   }
 }

package/src/agent/orchestrator/tools/patch-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.17",
+  "version": "0.7.18",
   "_comment": "Rewritten by .github/workflows/patch-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-patch binary on the GitHub release. A local cargo build under native/mixdog-patch/target/release always takes precedence; otherwise the binary is fetched per this manifest into the data dir (apply is native-only — no JS apply engine).",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-darwin-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-patch-darwin-arm64",
       "sha256": "836a0b60a443b0a6a8c1bbe24d15a79ed70ee92c2f0fbc05374c4e9ed2536415"
     },
     "darwin-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-darwin-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-patch-darwin-x64",
       "sha256": "cab10c4e1e8b72d3958241dffdff764712ed74f4861d105bafa8258961215c98"
     },
     "linux-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-linux-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-patch-linux-arm64",
       "sha256": "a90c32ce3417a7d853f2723f82f3613cf2cd030fe885cf710cfc9f8e4b193264"
     },
     "linux-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-linux-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-patch-linux-x64",
       "sha256": "0fea40ab98acd35bfb47515756024d1882a2abbaddce8a0b51642d20ac405577"
     },
     "win32-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-win32-x64.exe",
-      "sha256": "af92ae25c2434f9b2999df0186e11f6a8802d70bcbc4b91290cfd92f3e143466"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.18/mixdog-patch-win32-x64.exe",
+      "sha256": "cf2f28f8b410a5b0b6deb500fbb332be7cba11adee4340c3433212327b14412c"
     }
   }
 }

package/src/agent/tool-defs.mjs

@@ -13,6 +13,13 @@ export const TOOL_DEFS = [
     description: 'List models.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'gateway_select_model',
+    title: 'Select Gateway Model',
+    annotations: { title: 'Select Gateway Model', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    description: 'Interactively choose how the mixdog gateway routes Claude Code\'s main model. The first choice follows Claude Code\'s own current /model setting (including effort/fast where available); the rest list enabled providers + models. On selection, writes the gateway target/mode (+ enables the gateway module) — live on the next gateway request, no restart. If the client does not support elicitation, it falls back to listing the models and tells you to run /mixdog:model. Opt-in: only runs when you invoke it.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
   {
     name: 'explore',
     title: 'Explore',
@@ -70,7 +77,7 @@ export const TOOL_DEFS = [
     title: 'Bridge to External Model',
     annotations: { title: 'Bridge to External Model', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, bridgeHidden: true },
     description: 'Unified worker session control. type selects the action (default "spawn"). '
-      + 'spawn: dispatch a detached worker — requires role + message (alias: prompt); optional tag names the session for later send/close (auto "<role><n>" if omitted). '
+      + 'spawn: dispatch a detached worker — requires role + prompt; optional tag names the session for later send/close (auto "<role><n>" if omitted). '
       + 'send: resume a worker by tag (or raw sess_ id) — requires tag + message. To CONTINUE the same task on the same files/context — fix rounds, re-reviews, iterative refinement, or any follow-up — PREFER reusing the original tag over a new spawn: it preserves the worker\'s transcript + file context + change history, so it is faster, cheaper (the prompt cache stays warm), and more accurate than re-discovering from scratch. The return\'s respawned flag = false when the live session continued (context kept), true when a closed/cold tag was respawned fresh (context reset). '
       + 'close: stop a worker — requires tag. '
       + 'list: enumerate active worker sessions with stage/staleness — no args (optional role/status filter).',
@@ -80,8 +87,8 @@ export const TOOL_DEFS = [
         type: { type: 'string', enum: ['spawn', 'send', 'close', 'list'], description: 'Action discriminator. Default "spawn".' },
         role: { type: 'string', description: 'Worker role (from user-workflow). Required for spawn; optional filter for list.' },
         tag: { type: 'string', description: 'Stable session handle. spawn: optional name; send/close: required target (tag or raw sess_ id).' },
-        message: { type: 'string', description: 'Brief for spawn / follow-up for send. `prompt` is accepted as an alias on spawn. A spawn brief must state: goal+why, mode (write-code vs research-only), anchor (file:line/symbol/command), and done (output shape + stop condition).' },
-        prompt: { type: 'string', description: 'Alias of message for spawn (backward compat).' },
+        message: { type: 'string', description: 'Follow-up text for send. For spawn, use prompt. A spawn brief must state: goal+why, mode (write-code vs research-only), anchor (file:line/symbol/command), and done (output shape + stop condition).' },
+        prompt: { type: 'string', description: 'Brief for spawn. Prefer this over message; must contain non-whitespace content unless file/ref is provided.' },
         status: { type: 'string', description: 'list: optional status filter (e.g. running, idle, error).' },
         provider: { type: 'string', description: 'spawn: override the worker provider.' },
         model: { type: 'string', description: 'spawn: override the worker model.' },

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

@@ -193,6 +193,9 @@ function writeActiveInstance(state) {
   writeJsonFile(ACTIVE_INSTANCE_FILE, state);
 }
 function buildActiveInstanceState(instanceId, meta) {
+  const gatewayMeta = Object.fromEntries(
+    Object.entries(meta || {}).filter(([k]) => k.startsWith('gateway_'))
+  );
   return {
     instanceId,
     ...buildRuntimeIdentity(),
@@ -202,10 +205,11 @@ function buildActiveInstanceState(instanceId, meta) {
     turnEndFile: getTurnEndPath(instanceId),
     statusFile: getStatusPath(instanceId),
     ...meta?.channelId ? { channelId: meta.channelId } : {},
-    ...meta?.transcriptPath ? { transcriptPath: meta.transcriptPath } : {},
-    ...meta?.httpPort ? { httpPort: meta.httpPort } : {},
-    ...meta?.memory_port ? { memory_port: meta.memory_port } : {},
-    ...typeof meta?.backendReady === "boolean" ? { backendReady: meta.backendReady } : {}
+      ...meta?.transcriptPath ? { transcriptPath: meta.transcriptPath } : {},
+      ...meta?.httpPort ? { httpPort: meta.httpPort } : {},
+      ...meta?.memory_port ? { memory_port: meta.memory_port } : {},
+      ...gatewayMeta,
+      ...typeof meta?.backendReady === "boolean" ? { backendReady: meta.backendReady } : {}
   };
 }
 function refreshActiveInstance(instanceId, meta) {
@@ -229,6 +233,9 @@ function refreshActiveInstance(instanceId, meta) {
       && prevServerPid === identity.server_pid
       && Number.isFinite(prevServerStartedAt)
     ) ? prevServerStartedAt : Date.now();
+    const gatewayMeta = Object.fromEntries(
+      Object.entries(meta || {}).filter(([k]) => k.startsWith('gateway_'))
+    );
     const next = {
       ...(prev?.instanceId === instanceId ? prevRest : buildActiveInstanceState(instanceId)),
       ...identity,
@@ -238,6 +245,7 @@ function refreshActiveInstance(instanceId, meta) {
       ...meta?.transcriptPath ? { transcriptPath: meta.transcriptPath } : {},
       ...meta?.httpPort ? { httpPort: meta.httpPort } : {},
       ...meta?.memory_port ? { memory_port: meta.memory_port } : {},
+      ...gatewayMeta,
       ...typeof meta?.backendReady === "boolean" ? { backendReady: meta.backendReady } : {},
     };
     if (typeof meta?.transcriptPath === "string" && meta.transcriptPath) {
@@ -283,6 +291,33 @@ function refreshActiveInstance(instanceId, meta) {
         preservedExtra.memory_server_pid = prevMemoryServerPid;
       }
     }
+    // gateway_port follows the same preservation rule as memory_port: the
+    // gateway child advertises itself independently, and active-owner
+    // heartbeats must not erase that discovery record while its owning
+    // server-main process is still alive.
+    const prevGatewayServerPid = parsePositivePid(prevForPreserve?.gateway_server_pid);
+    const prevGatewayOwnerAlive = (() => {
+      if (prevGatewayServerPid === null) return false;
+      try {
+        process.kill(prevGatewayServerPid, 0);
+        return true;
+      } catch (e) {
+        if (e && e.code === "ESRCH") return false;
+        return true;
+      }
+    })();
+    const sameGatewayAdvertiser =
+      prevGatewayServerPid !== null &&
+      identity.server_pid !== null &&
+      prevGatewayServerPid === identity.server_pid;
+    if (sameGatewayAdvertiser || prevGatewayOwnerAlive) {
+      if (prevForPreserve && Object.prototype.hasOwnProperty.call(prevForPreserve, 'gateway_port')) {
+        for (const [key, value] of Object.entries(prevForPreserve)) {
+          if (key.startsWith('gateway_')) preservedExtra[key] = value;
+        }
+        preservedExtra.gateway_server_pid = prevGatewayServerPid;
+      }
+    }
     return { ...preservedExtra, ...next };
   }, { compact: true, fsyncDir: true });
 }