dominds 1.25.18 → 1.26.0

package/dist/server/dominds-self-update-restart-helper.js

@@ -0,0 +1,305 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const net_1 = __importDefault(require("net"));
+const time_1 = require("@longrun-ai/kernel/utils/time");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function readString(value, key) {
+    const candidate = value[key];
+    if (typeof candidate !== 'string' || candidate.trim() === '') {
+        throw new Error(`Invalid Dominds restart helper payload: ${key} must be a non-empty string`);
+    }
+    return candidate;
+}
+function readNumber(value, key) {
+    const candidate = value[key];
+    if (typeof candidate !== 'number' || !Number.isFinite(candidate)) {
+        throw new Error(`Invalid Dominds restart helper payload: ${key} must be a finite number`);
+    }
+    return candidate;
+}
+function readPositiveInteger(value, key) {
+    const candidate = readNumber(value, key);
+    if (!Number.isInteger(candidate) || candidate <= 0) {
+        throw new Error(`Invalid Dominds restart helper payload: ${key} must be a positive integer`);
+    }
+    return candidate;
+}
+function readPort(value, key) {
+    const candidate = readPositiveInteger(value, key);
+    if (candidate > 65535) {
+        throw new Error(`Invalid Dominds restart helper payload: ${key} must be <= 65535`);
+    }
+    return candidate;
+}
+function parsePayload(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new Error('Missing Dominds restart helper payload');
+    }
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error('Invalid Dominds restart helper payload: expected an object');
+    }
+    const args = parsed['args'];
+    if (!isStringArray(args)) {
+        throw new Error('Invalid Dominds restart helper payload: args must be a string array');
+    }
+    const stdioMode = parsed['stdioMode'];
+    if (stdioMode !== 'inherit' && stdioMode !== 'ignore') {
+        throw new Error('Invalid Dominds restart helper payload: stdioMode must be inherit or ignore');
+    }
+    return {
+        command: readString(parsed, 'command'),
+        args,
+        cwd: readString(parsed, 'cwd'),
+        host: readString(parsed, 'host'),
+        port: readPort(parsed, 'port'),
+        retiringPid: readPositiveInteger(parsed, 'retiringPid'),
+        forceKillAfterMs: readPositiveInteger(parsed, 'forceKillAfterMs'),
+        probeIntervalMs: readPositiveInteger(parsed, 'probeIntervalMs'),
+        portReleaseTimeoutMs: readPositiveInteger(parsed, 'portReleaseTimeoutMs'),
+        stdioMode,
+        traceFile: readString(parsed, 'traceFile'),
+        debugDir: readString(parsed, 'debugDir'),
+    };
+}
+function trace(payload, event, details = {}) {
+    const record = {
+        ...details,
+        event,
+        capturedAt: (0, time_1.formatUnifiedTimestamp)(new Date()),
+        helperPid: process.pid,
+        platform: process.platform,
+    };
+    try {
+        fs_1.default.mkdirSync(payload.debugDir, { recursive: true });
+        fs_1.default.appendFileSync(payload.traceFile, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to write Dominds restart helper trace: ${message}`);
+    }
+}
+function isPortBusy(payload) {
+    return new Promise((resolve) => {
+        const socket = net_1.default.createConnection({ host: payload.host, port: payload.port });
+        let settled = false;
+        const finish = (busy) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(busy);
+        };
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(1000, () => finish(true));
+    });
+}
+function getErrorCode(error) {
+    return isRecord(error) && typeof error['code'] === 'string' ? error['code'] : '';
+}
+function assertValidRetiringPid(payload) {
+    if (!Number.isInteger(payload.retiringPid) || payload.retiringPid <= 0) {
+        throw new Error(`Invalid retiring Dominds pid for restart: ${String(payload.retiringPid)}`);
+    }
+    if (payload.retiringPid === process.pid) {
+        throw new Error(`Refusing to kill restart helper pid ${String(process.pid)}`);
+    }
+}
+function isRetiringProcessAlive(payload) {
+    assertValidRetiringPid(payload);
+    try {
+        process.kill(payload.retiringPid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === 'ESRCH')
+            return false;
+        if (code === 'EPERM')
+            return true;
+        throw error;
+    }
+}
+async function delayMs(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function waitForRetiringProcessExit(payload, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isRetiringProcessAlive(payload))
+            return true;
+        await delayMs(payload.probeIntervalMs);
+    }
+    return false;
+}
+async function waitForPortReleaseUntil(payload, deadline) {
+    let consecutiveReady = 0;
+    while (Date.now() < deadline) {
+        if (!(await isPortBusy(payload))) {
+            consecutiveReady += 1;
+            if (consecutiveReady >= 2)
+                return true;
+        }
+        else {
+            consecutiveReady = 0;
+        }
+        await delayMs(payload.probeIntervalMs);
+    }
+    return false;
+}
+async function runBestEffortKiller(payload, command, args) {
+    await new Promise((resolve) => {
+        trace(payload, 'helper.force_kill.spawn', { command, args });
+        const killer = (0, child_process_1.spawn)(command, [...args], {
+            stdio: payload.stdioMode,
+            windowsHide: payload.stdioMode !== 'inherit',
+        });
+        killer.once('error', (error) => {
+            trace(payload, 'helper.force_kill.error', { message: error.message });
+            resolve();
+        });
+        killer.once('exit', (code, signal) => {
+            trace(payload, 'helper.force_kill.exit', { code, signal });
+            resolve();
+        });
+    });
+}
+async function forceKillRetiringProcess(payload) {
+    assertValidRetiringPid(payload);
+    try {
+        process.kill(payload.retiringPid, 'SIGKILL');
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === 'ESRCH')
+            return;
+        if (process.platform !== 'win32')
+            throw error;
+    }
+    if (process.platform === 'win32') {
+        await runBestEffortKiller(payload, 'taskkill.exe', ['/PID', String(payload.retiringPid), '/F']);
+    }
+}
+async function runRestartHelper(payload) {
+    const detached = payload.stdioMode !== 'inherit';
+    trace(payload, 'helper.start', {
+        command: payload.command,
+        args: payload.args,
+        cwd: payload.cwd,
+        host: payload.host,
+        port: payload.port,
+        retiringPid: payload.retiringPid,
+        detached,
+        stdioMode: payload.stdioMode,
+        forceKillAfterMs: payload.forceKillAfterMs,
+        portReleaseTimeoutMs: payload.portReleaseTimeoutMs,
+        probeIntervalMs: payload.probeIntervalMs,
+    });
+    const forceKillDeadline = Date.now() + payload.forceKillAfterMs;
+    trace(payload, 'helper.wait_retiring_process_exit.start', {
+        retiringPid: payload.retiringPid,
+        timeoutMs: payload.forceKillAfterMs,
+    });
+    const exitedGracefully = await waitForRetiringProcessExit(payload, payload.forceKillAfterMs);
+    trace(payload, 'helper.wait_retiring_process_exit.finish', {
+        retiringPid: payload.retiringPid,
+        exited: exitedGracefully,
+    });
+    if (!exitedGracefully) {
+        trace(payload, 'helper.force_kill.start', { retiringPid: payload.retiringPid });
+        await forceKillRetiringProcess(payload);
+        trace(payload, 'helper.force_kill.finish', { retiringPid: payload.retiringPid });
+        trace(payload, 'helper.wait_retiring_process_exit_after_kill.start', {
+            retiringPid: payload.retiringPid,
+            timeoutMs: payload.portReleaseTimeoutMs,
+        });
+        const exitedAfterKill = await waitForRetiringProcessExit(payload, payload.portReleaseTimeoutMs);
+        trace(payload, 'helper.wait_retiring_process_exit_after_kill.finish', {
+            retiringPid: payload.retiringPid,
+            exited: exitedAfterKill,
+        });
+        if (!exitedAfterKill) {
+            throw new Error(`Dominds retiring process is still alive after force-killing pid ${String(payload.retiringPid)}`);
+        }
+    }
+    const portReleaseDeadline = Math.max(forceKillDeadline, Date.now() + payload.portReleaseTimeoutMs);
+    trace(payload, 'helper.wait_port_release.start', {
+        host: payload.host,
+        port: payload.port,
+        deadlineMsFromNow: portReleaseDeadline - Date.now(),
+    });
+    const portReleased = await waitForPortReleaseUntil(payload, portReleaseDeadline);
+    trace(payload, 'helper.wait_port_release.finish', {
+        host: payload.host,
+        port: payload.port,
+        released: portReleased,
+    });
+    if (!portReleased) {
+        throw new Error(`Dominds restart port is still busy after retiring pid ${String(payload.retiringPid)} exited; port=${String(payload.host)}:${String(payload.port)}`);
+    }
+    trace(payload, 'helper.spawn_new_process.start', {
+        command: payload.command,
+        args: payload.args,
+        cwd: payload.cwd,
+        detached,
+        stdioMode: payload.stdioMode,
+    });
+    const child = (0, child_process_1.spawn)(payload.command, [...payload.args], {
+        cwd: payload.cwd,
+        env: process.env,
+        detached,
+        stdio: payload.stdioMode,
+        shell: false,
+        windowsHide: payload.stdioMode !== 'inherit',
+    });
+    if (detached)
+        child.unref();
+    await new Promise((resolve, reject) => {
+        child.once('error', (error) => {
+            trace(payload, 'helper.spawn_new_process.error', {
+                command: payload.command,
+                args: payload.args,
+                cwd: payload.cwd,
+                message: error.message,
+                stack: error.stack ?? null,
+            });
+            reject(error);
+        });
+        child.once('spawn', resolve);
+    });
+    trace(payload, 'helper.spawn_new_process.finish', { childPid: child.pid ?? null });
+    trace(payload, 'helper.exit', { code: 0 });
+}
+async function main() {
+    let payload = null;
+    try {
+        payload = parsePayload(process.argv[2]);
+        await runRestartHelper(payload);
+        process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? (error.stack ?? null) : null;
+        if (payload !== null) {
+            trace(payload, 'helper.error', { message, stack });
+        }
+        console.error(message);
+        process.exit(1);
+    }
+}
+if (require.main === module) {
+    void main();
+}

package/dist/server/dominds-self-update.js

@@ -10,6 +10,7 @@ exports.getDomindsSelfUpdateStatus = getDomindsSelfUpdateStatus;
 exports.installLatestDominds = installLatestDominds;
 exports.restartDomindsIntoLatest = restartDomindsIntoLatest;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const time_1 = require("@longrun-ai/kernel/utils/time");
@@ -43,6 +44,7 @@ let restartPromise = null;
 let restartState = IDLE_RESTART_STATE;
 let installFailureObservation = null;
 let broadcastStatusUpdate = null;
+let activeRestartTraceFile = null;
 function normalizeVersionString(value) {
     return value.trim().replace(/^v/i, '');
 }
@@ -101,6 +103,55 @@ function normalizeComparablePath(value) {
     const normalized = path_1.default.normalize(value);
     return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
+function sanitizeDebugFileSegment(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return sanitized.length > 0 ? sanitized.slice(0, 80) : 'unknown';
+}
+function buildRestartTraceContext() {
+    const capturedAt = (0, time_1.formatUnifiedTimestamp)(new Date());
+    const debugDir = path_1.default.resolve(process.cwd(), '.dialogs', 'debug');
+    const traceFile = path_1.default.join(debugDir, [
+        'dominds-self-update-restart',
+        sanitizeDebugFileSegment(capturedAt),
+        String(process.pid),
+        `${(0, crypto_1.randomUUID)()}.jsonl`,
+    ].join('-'));
+    return { debugDir, traceFile };
+}
+function getRestartHelperEntrypoint() {
+    return path_1.default.resolve(__dirname, 'dominds-self-update-restart-helper.js');
+}
+async function appendRestartTrace(trace, event, details = {}) {
+    const payload = {
+        ...details,
+        event,
+        capturedAt: (0, time_1.formatUnifiedTimestamp)(new Date()),
+        pid: process.pid,
+        platform: process.platform,
+        rtwsRootAbs: process.cwd(),
+    };
+    await promises_1.default.mkdir(trace.debugDir, { recursive: true });
+    await promises_1.default.appendFile(trace.traceFile, `${JSON.stringify(payload)}\n`, 'utf-8');
+}
+function appendRestartTraceSoon(trace, event, details = {}) {
+    void appendRestartTrace(trace, event, details).catch((error) => {
+        log.warn('Failed to write Dominds restart trace', error, {
+            traceFile: trace.traceFile,
+            event,
+        });
+    });
+}
+async function appendRestartTraceBestEffort(trace, event, details = {}) {
+    try {
+        await appendRestartTrace(trace, event, details);
+    }
+    catch (error) {
+        log.warn('Failed to write Dominds restart trace', error, {
+            traceFile: trace.traceFile,
+            event,
+        });
+    }
+}
 async function getComparableRealPath(absPath) {
     try {
         return normalizeComparablePath(await promises_1.default.realpath(absPath));
@@ -1331,9 +1382,11 @@ async function installLatestDominds() {
     publishStatusUpdateSoon();
     return await getDomindsSelfUpdateStatus();
 }
-function spawnDetachedRestartHelper(params) {
+async function spawnDetachedRestartHelper(params) {
     const stdioMode = getRestartHelperStdio();
-    const helperPayload = JSON.stringify({
+    const helperEntrypoint = getRestartHelperEntrypoint();
+    await promises_1.default.access(helperEntrypoint);
+    const helperPayload = {
         command: params.command,
         args: [...params.args],
         cwd: params.cwd,
@@ -1344,145 +1397,88 @@ function spawnDetachedRestartHelper(params) {
         probeIntervalMs: RESTART_PORT_PROBE_INTERVAL_MS,
         portReleaseTimeoutMs: RESTART_PORT_RELEASE_TIMEOUT_MS,
         stdioMode,
-    });
-    const helperScript = [
-        "const net = require('net');",
-        "const { spawn } = require('child_process');",
-        'const payload = JSON.parse(process.argv[1]);',
-        'const detached = payload.stdioMode !== "inherit";',
-        'function isPortBusy() {',
-        '  return new Promise((resolve) => {',
-        '    const socket = net.createConnection({ host: payload.host, port: payload.port });',
-        '    let settled = false;',
-        '    const finish = (busy) => {',
-        '      if (settled) return;',
-        '      settled = true;',
-        '      socket.destroy();',
-        '      resolve(busy);',
-        '    };',
-        '    socket.once("connect", () => finish(true));',
-        '    socket.once("error", () => finish(false));',
-        '    socket.setTimeout(1000, () => finish(true));',
-        '  });',
-        '}',
-        'function getErrorCode(error) {',
-        '  return error && typeof error === "object" && typeof error.code === "string" ? error.code : "";',
-        '}',
-        'function assertValidRetiringPid() {',
-        '  if (!Number.isInteger(payload.retiringPid) || payload.retiringPid <= 0) {',
-        '    throw new Error(`Invalid retiring Dominds pid for restart: ${String(payload.retiringPid)}`);',
-        '  }',
-        '  if (payload.retiringPid === process.pid) {',
-        '    throw new Error(`Refusing to kill restart helper pid ${String(process.pid)}`);',
-        '  }',
-        '}',
-        'function isRetiringProcessAlive() {',
-        '  assertValidRetiringPid();',
-        '  try {',
-        '    process.kill(payload.retiringPid, 0);',
-        '    return true;',
-        '  } catch (error) {',
-        '    const code = getErrorCode(error);',
-        '    if (code === "ESRCH") return false;',
-        '    if (code === "EPERM") return true;',
-        '    throw error;',
-        '  }',
-        '}',
-        'async function waitForRetiringProcessExit(timeoutMs) {',
-        '  const deadline = Date.now() + timeoutMs;',
-        '  while (Date.now() < deadline) {',
-        '    if (!isRetiringProcessAlive()) return true;',
-        '    await new Promise((resolve) => setTimeout(resolve, payload.probeIntervalMs));',
-        '  }',
-        '  return false;',
-        '}',
-        'async function waitForPortReleaseUntil(deadline) {',
-        '  let consecutiveReady = 0;',
-        '  while (Date.now() < deadline) {',
-        '    if (!(await isPortBusy())) {',
-        '      consecutiveReady += 1;',
-        '      if (consecutiveReady >= 2) return true;',
-        '    } else {',
-        '      consecutiveReady = 0;',
-        '    }',
-        '    await new Promise((resolve) => setTimeout(resolve, payload.probeIntervalMs));',
-        '  }',
-        '  return false;',
-        '}',
-        'function runBestEffortKiller(command, args) {',
-        '  return new Promise((resolve) => {',
-        '    const killer = spawn(command, args, { stdio: payload.stdioMode, windowsHide: payload.stdioMode !== "inherit" });',
-        "    killer.once('error', () => resolve());",
-        "    killer.once('exit', () => resolve());",
-        '  });',
-        '}',
-        'async function forceKillRetiringProcess() {',
-        '  assertValidRetiringPid();',
-        '  try {',
-        "    process.kill(payload.retiringPid, 'SIGKILL');",
-        '  } catch (error) {',
-        '    const code = getErrorCode(error);',
-        '    if (code === "ESRCH") return;',
-        '    if (process.platform !== "win32") throw error;',
-        '  }',
-        '  if (process.platform === "win32") {',
-        "    await runBestEffortKiller('taskkill.exe', ['/PID', String(payload.retiringPid), '/F']);",
-        '  }',
-        '}',
-        '(async () => {',
-        '  try {',
-        '    const forceKillDeadline = Date.now() + payload.forceKillAfterMs;',
-        '    const exitedGracefully = await waitForRetiringProcessExit(payload.forceKillAfterMs);',
-        '    if (!exitedGracefully) {',
-        '      await forceKillRetiringProcess();',
-        '      const exitedAfterKill = await waitForRetiringProcessExit(payload.portReleaseTimeoutMs);',
-        '      if (!exitedAfterKill) {',
-        '        throw new Error(`Dominds retiring process is still alive after force-killing pid ${String(payload.retiringPid)}`);',
-        '      }',
-        '    }',
-        '    const portReleaseDeadline = Math.max(forceKillDeadline, Date.now() + payload.portReleaseTimeoutMs);',
-        '    const portReleased = await waitForPortReleaseUntil(portReleaseDeadline);',
-        '    if (!portReleased) {',
-        '      throw new Error(`Dominds restart port is still busy after retiring pid ${String(payload.retiringPid)} exited; port=${String(payload.host)}:${String(payload.port)}`);',
-        '    }',
-        '    const child = spawn(payload.command, payload.args, { cwd: payload.cwd, env: process.env, detached, stdio: payload.stdioMode, shell: false, windowsHide: payload.stdioMode !== "inherit" });',
-        '    if (detached) child.unref();',
-        '    await new Promise((resolve, reject) => {',
-        "      child.once('error', reject);",
-        "      child.once('spawn', resolve);",
-        '    });',
-        '    process.exit(0);',
-        '  } catch (error) {',
-        '    console.error(error instanceof Error ? error.message : String(error));',
-        '    process.exit(1);',
-        '  }',
-        '})();',
-    ].join('\n');
-    const helper = (0, child_process_1.spawn)(process.execPath, ['-e', helperScript, helperPayload], {
+        traceFile: params.trace.traceFile,
+        debugDir: params.trace.debugDir,
+    };
+    const helper = (0, child_process_1.spawn)(process.execPath, [helperEntrypoint, JSON.stringify(helperPayload)], {
         cwd: params.cwd,
         env: process.env,
         detached: stdioMode !== 'inherit',
         stdio: stdioMode,
         windowsHide: stdioMode !== 'inherit',
     });
+    const helperPid = typeof helper.pid === 'number' ? helper.pid : null;
+    const helperSpawned = new Promise((resolve, reject) => {
+        helper.once('spawn', () => {
+            appendRestartTraceSoon(params.trace, 'parent.helper_spawn_event', {
+                helperPid,
+            });
+            resolve(helperPid);
+        });
+        helper.once('error', (error) => {
+            appendRestartTraceSoon(params.trace, 'parent.helper_error_event', {
+                message: error.message,
+                stack: error.stack ?? null,
+            });
+            reject(error);
+        });
+    });
+    helper.once('exit', (code, signal) => {
+        appendRestartTraceSoon(params.trace, 'parent.helper_exit_event', {
+            code,
+            signal,
+        });
+    });
     if (stdioMode !== 'inherit') {
         helper.unref();
     }
+    return await helperSpawned;
 }
 async function stopAndExitForRestart() {
     const cfg = assertRuntimeConfig();
+    const trace = activeRestartTraceFile === null
+        ? null
+        : { debugDir: path_1.default.dirname(activeRestartTraceFile), traceFile: activeRestartTraceFile };
     let stopSettled = false;
-    void cfg
+    if (trace !== null) {
+        await appendRestartTraceBestEffort(trace, 'parent.stop_and_exit.start', {
+            host: cfg.host,
+            port: cfg.port,
+            exitGraceMs: RESTART_EXIT_GRACE_MS,
+        });
+    }
+    const stopPromise = cfg
         .stopServer()
         .then(() => {
         stopSettled = true;
+        if (trace !== null) {
+            return appendRestartTraceBestEffort(trace, 'parent.stop_server.finish', {
+                host: cfg.host,
+                port: cfg.port,
+            });
+        }
+        return undefined;
     })
         .catch((error) => {
         stopSettled = true;
+        if (trace !== null) {
+            return appendRestartTraceBestEffort(trace, 'parent.stop_server.error', {
+                host: cfg.host,
+                port: cfg.port,
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? (error.stack ?? null) : null,
+            }).then(() => {
+                log.error('Failed to stop Dominds HTTP server during restart grace window', error, {
+                    host: cfg.host,
+                    port: cfg.port,
+                });
+            });
+        }
         log.error('Failed to stop Dominds HTTP server during restart grace window', error, {
             host: cfg.host,
             port: cfg.port,
         });
+        return undefined;
     });
     cfg.closeWebSocketClients();
     await delayMs(RESTART_EXIT_GRACE_MS);
@@ -1493,6 +1489,17 @@ async function stopAndExitForRestart() {
             graceMs: RESTART_EXIT_GRACE_MS,
         });
     }
+    if (trace !== null) {
+        if (stopSettled) {
+            await stopPromise;
+        }
+        await appendRestartTraceBestEffort(trace, 'parent.process_exit', {
+            host: cfg.host,
+            port: cfg.port,
+            stopSettled,
+            code: 0,
+        });
+    }
     process.exit(0);
 }
 async function restartDomindsIntoLatest() {
@@ -1529,24 +1536,59 @@ async function restartDomindsIntoLatest() {
         }
         restartState = { kind: 'restarting', targetVersion: status.targetVersion };
         publishStatusUpdateSoon();
+        const restartCwd = process.cwd();
+        const trace = buildRestartTraceContext();
+        activeRestartTraceFile = trace.traceFile;
         try {
-            spawnDetachedRestartHelper({
+            await appendRestartTraceBestEffort(trace, 'parent.restart_requested', {
+                runKind,
+                currentVersion: status.currentVersion,
+                targetVersion: status.targetVersion,
+                launchCommand: launchSpec.command,
+                launchArgs: launchSpec.args,
+                restartCwd,
+                host: cfg.host,
+                port: cfg.port,
+                traceFile: trace.traceFile,
+            });
+            const helperPid = await spawnDetachedRestartHelper({
                 command: launchSpec.command,
                 args: launchSpec.args,
-                cwd: PROCESS_START_CWD,
+                cwd: restartCwd,
+                host: cfg.host,
+                port: cfg.port,
+                trace,
+            });
+            await appendRestartTraceBestEffort(trace, 'parent.helper_spawned', {
+                helperPid,
+                retiringPid: process.pid,
                 host: cfg.host,
                 port: cfg.port,
             });
+            log.info('Dominds restart helper spawned', undefined, {
+                helperPid,
+                traceFile: trace.traceFile,
+            });
             setImmediate(() => {
                 void stopAndExitForRestart().catch((error) => {
+                    void appendRestartTraceBestEffort(trace, 'parent.stop_and_exit.error', {
+                        message: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? (error.stack ?? null) : null,
+                    });
                     log.error('Failed to stop Dominds server during restart', error);
                     restartState = previousRestartRequiredState ?? IDLE_RESTART_STATE;
+                    activeRestartTraceFile = null;
                     publishStatusUpdateSoon();
                 });
             });
         }
         catch (error) {
+            await appendRestartTraceBestEffort(trace, 'parent.restart_error', {
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? (error.stack ?? null) : null,
+            });
             restartState = previousRestartRequiredState ?? IDLE_RESTART_STATE;
+            activeRestartTraceFile = null;
             publishStatusUpdateSoon();
             throw error;
         }

package/dist/server/network-hosts.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeNetworkHost(host: string): string;
+export declare function isLanHttpsHost(host: string): boolean;
+export declare function resolveHttpUrlHostForBindHost(bindHost: string): string;
+export declare function resolveLanHttpsHostsForBindHost(bindHost: string): Promise<readonly string[]>;
+export declare function resolveDefaultLanHttpsHosts(): Promise<readonly string[]>;