dominds 1.25.18 → 1.25.19

package/dist/bootstrap/rtws-cli.d.ts

@@ -4,5 +4,4 @@ export type RtwsCliParseResult = Readonly<{
 }>;
 export declare function extractGlobalRtwsChdir(params: Readonly<{
     argv: ReadonlyArray<string>;
-    baseCwd: string;
 }>): RtwsCliParseResult;

package/dist/bootstrap/rtws-cli.js

@@ -38,6 +38,12 @@ const path = __importStar(require("path"));
 function extractGlobalRtwsChdir(params) {
     let chdir;
     const out = [];
+    const readAbsoluteChdir = (argName, value) => {
+        if (!path.isAbsolute(value)) {
+            throw new Error(`${argName} requires an absolute directory path: ${value}`);
+        }
+        return value;
+    };
     for (let i = 0; i < params.argv.length; i++) {
         const arg = params.argv[i];
         if (arg === '--') {
@@ -49,7 +55,7 @@ function extractGlobalRtwsChdir(params) {
             if (typeof next !== 'string' || next.length === 0 || next === '--') {
                 throw new Error(`${arg} requires a directory argument`);
             }
-            chdir = path.isAbsolute(next) ? next : path.resolve(params.baseCwd, next);
+            chdir = readAbsoluteChdir(arg, next);
             i++;
             continue;
         }
@@ -57,14 +63,14 @@ function extractGlobalRtwsChdir(params) {
             const value = arg.slice('--cwd='.length);
             if (value.length === 0)
                 throw new Error(`--cwd requires a directory argument`);
-            chdir = path.isAbsolute(value) ? value : path.resolve(params.baseCwd, value);
+            chdir = readAbsoluteChdir('--cwd', value);
             continue;
         }
         if (arg.startsWith('--chdir=')) {
             const value = arg.slice('--chdir='.length);
             if (value.length === 0)
                 throw new Error(`--chdir requires a directory argument`);
-            chdir = path.isAbsolute(value) ? value : path.resolve(params.baseCwd, value);
+            chdir = readAbsoluteChdir('--chdir', value);
             continue;
         }
         out.push(arg);

package/dist/cli/create.d.ts

@@ -8,7 +8,7 @@
  *
  * Notes:
  * - Template can be a short name (resolved via DOMINDS_TEMPLATE_BASE) or a git URL.
- * - rtws directory is `process.cwd()`. Use 'dominds -C <dir> create ...' to create under another base dir.
+ * - rtws directory is `process.cwd()`. Use 'dominds -C <abs-dir> create ...' to create under another base dir.
  */
 declare function main(argv?: readonly string[]): Promise<void>;
 export { main };

package/dist/cli/create.js

@@ -9,7 +9,7 @@
  *
  * Notes:
  * - Template can be a short name (resolved via DOMINDS_TEMPLATE_BASE) or a git URL.
- * - rtws directory is `process.cwd()`. Use 'dominds -C <dir> create ...' to create under another base dir.
+ * - rtws directory is `process.cwd()`. Use 'dominds -C <abs-dir> create ...' to create under another base dir.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;

package/dist/cli/read.js

@@ -59,7 +59,7 @@ function printUsage() {
     console.log('`--audit` runs prompt audit via hidden teammate @fuxi using default LLM config (skips when unavailable), and also includes static toolset checks (registry vs `.minds/mcp.yaml` declarations).');
     console.log('When <member-id> is omitted, reads all visible team members.');
     console.log('');
-    console.log("Note: rtws (runtime workspace) directory is `process.cwd()`. Use 'dominds -C <dir> read' to run in another rtws.");
+    console.log("Note: rtws (runtime workspace) directory is `process.cwd()`. Use 'dominds -C <abs-dir> read' to run in another rtws.");
     console.log('');
     console.log('Examples:');
     console.log('  dominds read                    # Read all team members');

package/dist/cli/tui.js

@@ -76,7 +76,7 @@ function showHelp() {
     console.log('');
     console.log('Start or continue a dialog with an AI team member using a Taskdoc.');
     console.log('');
-    console.log("Note: rtws (runtime workspace) directory is `process.cwd()`. Use 'dominds -C <dir> tui ...' to run in another rtws.");
+    console.log("Note: rtws (runtime workspace) directory is `process.cwd()`. Use 'dominds -C <abs-dir> tui ...' to run in another rtws.");
     console.log('');
     console.log('Arguments:');
     console.log('  <taskdoc-path>    Path to Taskdoc (required for dialog)');

package/dist/cli/webui.js

@@ -30,7 +30,7 @@ Usage:
   dominds webui [options]
 
 Note:
-  rtws (runtime workspace) directory is \`process.cwd()\`. Use 'dominds -C <dir> webui' to run in another rtws.
+  rtws (runtime workspace) directory is \`process.cwd()\`. Use 'dominds -C <abs-dir> webui' to run in another rtws.
 
 Options:
   -p, --port <port>    Port to listen on. Bare port is strict; suffix + tries higher ports; suffix - tries lower ports.

package/dist/cli.js

@@ -107,10 +107,10 @@ function printHelp() {
 Dominds CLI - AI-driven DevOps framework with persistent memory
 
 Usage:
-  dominds [-C <dir>] [subcommand] [options]
+  dominds [-C <abs-dir>] [subcommand] [options]
 
 Global Options:
-  -C <dir>            Change to runtime workspace directory (rtws) before running
+  -C <abs-dir>        Change to absolute runtime workspace directory (rtws) before running
 
 Subcommands:
   webui [options]    Start WebUI server (default)
@@ -133,7 +133,7 @@ Subcommands:
 Examples:
   dominds                    # Start WebUI server (default)
   dominds webui              # Start WebUI server
-  dominds -C ./my-ws webui   # Start in specific rtws
+  dominds -C /path/to/my-ws webui # Start in specific rtws
   dominds tui --help         # Show TUI help
   dominds run task.tsk       # Run task dialog
   dominds read               # Read team configuration
@@ -159,10 +159,9 @@ function printVersion() {
     }
 }
 async function main(argv = process.argv.slice(2)) {
-    const baseCwd = process.cwd();
     let parsed;
     try {
-        parsed = (0, rtws_cli_1.extractGlobalRtwsChdir)({ argv, baseCwd });
+        parsed = (0, rtws_cli_1.extractGlobalRtwsChdir)({ argv });
     }
     catch (err) {
         console.error('Error:', err instanceof Error ? err.message : String(err));
@@ -173,10 +172,7 @@ async function main(argv = process.argv.slice(2)) {
     if (args.length === 0) {
         if (parsed.chdir) {
             try {
-                const absoluteRtwsRoot = path.isAbsolute(parsed.chdir)
-                    ? parsed.chdir
-                    : path.resolve(baseCwd, parsed.chdir);
-                process.chdir(absoluteRtwsRoot);
+                process.chdir(parsed.chdir);
             }
             catch (err) {
                 console.error(`Error: failed to change directory to '${parsed.chdir}':`, err);
@@ -222,10 +218,7 @@ async function main(argv = process.argv.slice(2)) {
     if (!shouldSkipRtwsSetup) {
         if (parsed.chdir) {
             try {
-                const absoluteRtwsRoot = path.isAbsolute(parsed.chdir)
-                    ? parsed.chdir
-                    : path.resolve(baseCwd, parsed.chdir);
-                process.chdir(absoluteRtwsRoot);
+                process.chdir(parsed.chdir);
             }
             catch (err) {
                 console.error(`Error: failed to change directory to '${parsed.chdir}':`, err);

package/dist/docs/cli-usage.md

@@ -4,7 +4,7 @@ Chinese version: [中文版](./cli-usage.zh.md)
 
 The `dominds` CLI provides a unified entry point, but the **primary interaction experience is the Web UI** (the default `dominds` command). This guide focuses on the Web UI workflow.
 
-> Note: In this document, **rtws (runtime workspace)** refers to the runtime root directory Dominds uses (by default `process.cwd()`, switchable via `-C <dir>`).
+> Note: In this document, **rtws (runtime workspace)** refers to the runtime root directory Dominds uses (by default `process.cwd()`, switchable via `-C <abs-dir>`; `-C` only accepts absolute paths).
 
 > Note: `dominds tui` / `dominds run` are currently reserved subcommand names and do not have a stable implementation yet. As a result, this guide does not document TUI options or detailed usage.
 
@@ -49,7 +49,7 @@ dominds webui [options]
 
 # Common: choose port / rtws
 dominds webui -p 8080
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # Minds reader: inspect team configuration
 dominds read [options] [member-id]
@@ -83,7 +83,7 @@ Start the web-based user interface for the current rtws. This provides a graphic
 
 - `-p, --port <port>` - Port to listen on; a bare port binds strictly, suffix `+` tries higher ports, and suffix `-` tries lower ports (omitting `--port` is equivalent to `5666-`)
 - `-h, --host <host>` - Host to bind to (default: localhost)
-- `-C, --cwd <dir>` - Change to rtws directory before starting
+- `-C, --cwd <abs-dir>` - Change to rtws directory before starting; absolute paths only
 - `--help` - Show help message
 
 **Examples:**
@@ -92,7 +92,7 @@ Start the web-based user interface for the current rtws. This provides a graphic
 dominds
 dominds webui -p 8080
 dominds webui -p 8080+
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 ```
 
 **Common use cases:**
@@ -122,7 +122,7 @@ Read and inspect agent prompts/configuration for the rtws. This is commonly used
 
 **Options:**
 
-- `-C, --cwd <dir>` - Change to rtws directory before reading
+- `-C, --cwd <abs-dir>` - Change to rtws directory before reading; absolute paths only
 - `--only-prompt` - Show only system prompts
 - `--only-mem` - Show only memory
 - `--help` - Show help message
@@ -132,7 +132,7 @@ Read and inspect agent prompts/configuration for the rtws. This is commonly used
 ```bash
 dominds read
 dominds read developer
-dominds read -C ./my-rtws
+dominds read -C /path/to/my-rtws
 dominds read --only-prompt
 dominds read --only-mem
 ```
@@ -190,7 +190,7 @@ dominds
 dominds webui -p 8080
 
 # 3) Start in a specific rtws
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # 4) Inspect current team/rtws configuration
 dominds read

package/dist/docs/cli-usage.zh.md

@@ -4,7 +4,7 @@
 
 `dominds` 提供统一的命令行入口，但**主要交互界面是 Web UI**（默认命令 `dominds`）。本文档以 Web UI 工作流为主。
 
-> 注：本文统一使用 **rtws（运行时工作区）** 表示 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <dir>` 切换）。
+> 注：本文统一使用 **rtws（运行时工作区）** 表示 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <abs-dir>` 切换；`-C` 只接受绝对路径）。
 
 > 说明：`dominds tui` / `dominds run` 相关功能目前尚未提供稳定实现（子命令名保留用于未来规划），因此本指南不再展开 TUI 的命令选项与用法细节。
 
@@ -49,7 +49,7 @@ dominds webui [options]
 
 # 常用：指定端口 / rtws
 dominds webui -p 8080
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # Minds 阅读器：分析团队配置
 dominds read [options] [member-id]
@@ -83,7 +83,7 @@ dominds webui [options]
 
 - `-p, --port <port>` - 监听端口；裸端口严格绑定，后缀 `+` 向更大端口自动尝试，后缀 `-` 向更小端口自动尝试（未指定时等价于 `5666-`）
 - `-h, --host <host>` - 绑定的主机（默认：localhost）
-- `-C, --cwd <dir>` - 启动前更改 rtws 目录
+- `-C, --cwd <abs-dir>` - 启动前更改 rtws 目录；只接受绝对路径
 - `--help` - 显示帮助消息
 
 **示例：**
@@ -99,7 +99,7 @@ dominds webui -p 8080
 dominds webui -p 8080+
 
 # 在特定 rtws 启动 Web UI
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 ```
 
 **常见用途：**
@@ -129,7 +129,7 @@ dominds read [options] [member-id]
 
 **选项：**
 
-- `-C, --cwd <dir>` - 读取前更改 rtws 目录
+- `-C, --cwd <abs-dir>` - 读取前更改 rtws 目录；只接受绝对路径
 - `--only-prompt` - 仅显示系统提示词
 - `--only-mem` - 仅显示内存
 - `--help` - 显示帮助消息
@@ -139,7 +139,7 @@ dominds read [options] [member-id]
 ```bash
 dominds read
 dominds read developer
-dominds read -C ./my-rtws
+dominds read -C /path/to/my-rtws
 dominds read --only-prompt
 dominds read --only-mem
 ```
@@ -204,7 +204,7 @@ dominds
 dominds webui -p 8080
 
 # 3) 在特定 rtws 启动
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # 4) 查看/核对当前团队配置
 dominds read

package/dist/docs/dialog-persistence.md

@@ -4,7 +4,7 @@ Chinese version: [中文版](./dialog-persistence.zh.md)
 
 This document describes the persistence layer and storage mechanisms for the Dominds dialog system, including file system conventions, data structures, and storage patterns.
 
-> Note: In this document, **rtws (runtime workspace)** refers to Dominds' runtime root directory (by default `process.cwd()`, switchable via `-C <dir>`).
+> Note: In this document, **rtws (runtime workspace)** refers to Dominds' runtime root directory (by default `process.cwd()`, switchable via `-C <abs-dir>`; `-C` only accepts absolute paths).
 
 ## Current Implementation Status
 

package/dist/docs/dominds-terminology.md

@@ -264,8 +264,8 @@ Example / 示例（概念）:
 
 ### rtws（运行时工作区）
 
-- EN: **rtws** (runtime workspace) is the directory Dominds treats as its runtime root (by default it is `process.cwd()`, and can be changed via `-C <dir>`). Files like `.minds/` and `.dialogs/` live under the rtws.
-- ZH: **rtws（运行时工作区）**是 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <dir>` 切换）。诸如 `.minds/`、`.dialogs/` 等运行态目录均位于 rtws 下。
+- EN: **rtws** (runtime workspace) is the directory Dominds treats as its runtime root (by default it is `process.cwd()`, and can be changed via `-C <abs-dir>`; `-C` only accepts absolute paths). Files like `.minds/` and `.dialogs/` live under the rtws.
+- ZH: **rtws（运行时工作区）**是 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <abs-dir>` 切换；`-C` 只接受绝对路径）。诸如 `.minds/`、`.dialogs/` 等运行态目录均位于 rtws 下。
 
 - EN: Wording rule: when the meaning is **rtws**, prefer writing “rtws (runtime workspace)” (or just “rtws” after the first mention) rather than the ambiguous generic “workspace”.
 - ZH: 用词规则：当语义指向 **rtws** 时，优先写“rtws（运行时工作区）”（或在已定义后只写“rtws”），避免在对外提示/文档中只写“工作区”从而与其他语境的 workspace/workdir 混淆。

package/dist/server/dominds-self-update-restart-helper.d.ts

@@ -0,0 +1,15 @@
+export type RestartHelperStdioMode = 'inherit' | 'ignore';
+export type RestartHelperPayload = Readonly<{
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    host: string;
+    port: number;
+    retiringPid: number;
+    forceKillAfterMs: number;
+    probeIntervalMs: number;
+    portReleaseTimeoutMs: number;
+    stdioMode: RestartHelperStdioMode;
+    traceFile: string;
+    debugDir: string;
+}>;

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.js

@@ -287,13 +287,14 @@ async function main() {
     // Handle working directory change from -C flag
     const wsDir = cliArgs['C'];
     if (wsDir) {
-        // Resolve to absolute path before changing directory
-        const absoluteWsDir = path.isAbsolute(wsDir) ? wsDir : path.resolve(process.cwd(), wsDir);
+        if (!path.isAbsolute(wsDir)) {
+            throw new Error(`-C requires an absolute directory path: ${wsDir}`);
+        }
         try {
             process.chdir(wsDir);
         }
         catch (err) {
-            log.warn(`Failed to change working directory to ${wsDir}:`, err);
+            throw new Error(`Failed to change working directory to ${wsDir}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     // Get port, host, and mode from CLI args

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominds",
-  "version": "1.25.18",
+  "version": "1.25.19",
   "description": "Dominds CLI and aggregation shell for the LongRun AI kernel/runtime packages.",
   "type": "commonjs",
   "publishConfig": {