n2n-nexus 0.12.3 → 0.12.4

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.12.4] - 2026-10-30
+
+### Fixed
+
+- On Windows, a Codex conversation is woken while idle again. The background wait copy that the Stop `--wait` hook starts inherited the pipes Codex reads the hook's output from (Codex runs the hook through PowerShell), so Codex waited for them until the hook's timeout and ended the copy with the hook: the session never showed as `listening` and only saw messages at its next prompt or tool call. The copy is now started by PowerShell's `Start-Process`, which passes no handles on.
+
+### Changed
+
+- A wake the client reports as failed (`codex queue` returned an error or a non-zero exit) is logged in `host.log` when the host undoes it: the session, the wake and how many messages and notices are delivered again. Before, the undo and the retry left no trace.
+
 ## [0.12.3] - 2026-10-29
 
 ### Fixed

package/build/cli/hook.js

@@ -7,6 +7,7 @@
  * is silent: exit 0 with nothing on stdout, so the client carries on unaffected.
  */
 import { spawn } from "node:child_process";
+import path from "node:path";
 import { BACKGROUND_WAIT_EVENT, WAKE_RESULT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, SESSION_END_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, WAKE_RETRY_FIRST_DELAY_MS, WAKE_RETRY_MAX_DELAY_MS, noDaemonHint, isHookClient } from "../contract.js";
 import { NexusClient, NexusTransportError, REQUEST_TIMEOUT_CODE } from "../client/nexus-client.js";
 import { DISCOVER_ENDPOINT, configuredEndpoint, resolveEndpoint } from "../client/discovery.js";
@@ -162,7 +163,7 @@ async function runWait(argv) {
         if (client === "codex") {
             const { entryScript } = await import("./entry.js");
             const args = [entryScript(), "hook", "codex", "--wait", "--session", sessionId, ...(argValue(argv, "--endpoint") ? ["--endpoint", configured] : [])];
-            spawn(process.execPath, args, { detached: true, stdio: "ignore", windowsHide: true }).unref();
+            await startDetached(process.execPath, args);
             return 0;
         }
     }
@@ -189,6 +190,30 @@ async function runWait(argv) {
         await new Promise((resolve) => setTimeout(resolve, delay));
     }
 }
+/**
+ * Start a program that outlives this hook, with no stdio. On Windows it is
+ * started by PowerShell's Start-Process (ShellExecute), which passes no handles
+ * on: a process Node spawns inherits every inheritable handle of this one, and
+ * when Codex runs the hook through PowerShell (`commandWindows`) those include
+ * the pipes Codex reads the hook's output from. Codex then waits for the pipes
+ * until the hook's timeout and ends the wait copy with the hook.
+ */
+async function startDetached(file, args) {
+    if (process.platform !== "win32") {
+        spawn(file, args, { detached: true, stdio: "ignore", windowsHide: true }).unref();
+        return;
+    }
+    const literal = (s) => `'${s.replace(/'/g, "''")}'`;
+    // Start-Process joins -ArgumentList with spaces, so each argument is quoted for the command line itself.
+    const quoted = (s) => `"${s.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+    const command = `Start-Process -WindowStyle Hidden -FilePath ${literal(file)} -ArgumentList ${args.map((a) => literal(quoted(a))).join(",")}`;
+    const powershell = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    await new Promise((resolve, reject) => {
+        const launcher = spawn(powershell, ["-NoProfile", "-NonInteractive", "-Command", command], { stdio: "ignore", windowsHide: true });
+        launcher.on("error", reject);
+        launcher.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Start-Process exited with ${code}`))));
+    });
+}
 /** Run the hook command; resolves to exit code 0, or 2 when a background wait wakes a Claude conversation. */
 export async function runHook(argv) {
     if (argv.includes("--wait")) {

package/docs/ARCHITECTURE.md

@@ -92,7 +92,9 @@ turn ends ──▶ Stop hook (announces unread, or listens)
                                      │  session shows as "listening"
                                      ├─ new message ─▶ { wake: notification, dispatchId }
                                      │     Claude Code: asyncRewake hook exits 2, the notification starts a turn
-                                     │     Codex: detached process runs `codex queue --thread <id> --message <notification>`,
+                                     │     Codex: detached process (on Windows started by PowerShell's Start-Process, which
+                                     │       passes no handles on: a process Node spawns would inherit the hook's output pipes
+                                     │       and Codex would wait for them) runs `codex queue --thread <id> --message <notification>`,
                                      │       then reports POST /api/hook {WakeResult, dispatch_id, ok}
                                      ├─ any other event of the session ─▶ null (wait ends)
                                      └─ time runs out or host shuts down ─▶ { timeout: true } (ask again)
@@ -100,7 +102,7 @@ turn ends ──▶ Stop hook (announces unread, or listens)
 
 The background wait retries temporary connection failures within its original one-hour deadline; with `discover`, it looks up the host again. A normal cancellation (`output: null`) still ends the wait. Host and client must both include this recovery behavior for graceful host restarts to resume waiting.
 
-The wait never delivers while the session is `working` or while a listening Stop hook is waiting, so a message is announced once. When `codex queue` fails (an error or a non-zero exit), the Codex wait reports `ok: false` and the host undoes that wake: the messages and notices it announced count as not announced again, the session leaves `working` and the automatic turn is not counted; the wait then asks again after 1 s, doubling after each failure up to 5 minutes, and delivers them again. Any other event of the session before the report means the wake was delivered, and the report is ignored. Verified on Windows with the Claude desktop app and the Codex desktop app (2026-10-23): both directions wake an idle conversation within seconds. Known limits:
+The wait never delivers while the session is `working` or while a listening Stop hook is waiting, so a message is announced once. When `codex queue` fails (an error or a non-zero exit), the Codex wait reports `ok: false` and the host undoes that wake: the messages and notices it announced count as not announced again, the session leaves `working` and the automatic turn is not counted, and the failed wake is logged in `host.log` (the session, the wake and how many messages and notices are delivered again); the wait then asks again after 1 s, doubling after each failure up to 5 minutes, and delivers them again. Any other event of the session before the report means the wake was delivered, and the report is ignored. Verified on Windows with the Claude desktop app and the Codex desktop app (2026-10-23): both directions wake an idle conversation within seconds. Known limits:
 
 - Codex starts a queued turn only for a conversation loaded in the running Codex app. After Codex restarts, a conversation is loaded once the user opens it.
 - The Codex background wait ends when the Codex app quits, and starts again only when the conversation ends a turn. Messages sent meanwhile stay unread in the host (not in Codex's own queue) until the user next prompts that conversation.

package/docs/ARCHITECTURE_zh.md

@@ -92,15 +92,16 @@ Stop                           ◀── decision: block   ◀─┘  每次结
                                     │  等待期间会话显示为 "listening"
                                     ├─ 有新消息 ─▶ { wake: 通知, dispatchId }
                                     │     Claude Code：asyncRewake hook 以退出码 2 结束，通知开启新的一轮
-                                    │     Codex：独立后台进程执行 `codex queue --thread <id> --message <通知>`，
-                                    │       再回报 POST /api/hook {WakeResult, dispatch_id, ok}
+                                    │     Codex：独立后台进程（Windows 上由 PowerShell 的 Start-Process 启动，它不传递任何句柄：
+                                    │       Node 直接派生的进程会继承 hook 的输出管道，Codex 会一直等这些管道）执行
+                                    │       `codex queue --thread <id> --message <通知>`，再回报 POST /api/hook {WakeResult, dispatch_id, ok}
                                     ├─ 该会话有其他任何事件 ─▶ null（等待结束）
                                     └─ 时间到或 host 关闭 ─▶ { timeout: true }（再次请求）
 ```
 
 后台等待会在原有的一小时时限内重试临时连接故障；使用 `discover` 时重新查找 host。正常取消（`output: null`）仍结束等待。host 与客户端都需要包含这项恢复行为，才能在 host 正常重启后继续等待。
 
-会话处于 `working`，或者 listen 模式的 Stop hook 正在等待时，后台等待不会送达，所以同一条消息只提醒一次。`codex queue` 失败（出错或退出码非 0）时，Codex 的后台等待回报 `ok: false`，host 撤销这次唤醒：它提醒过的消息和通知重新算作未提醒，会话退出 `working`，这一轮不计入自动轮次；随后等待在 1 秒后重新请求（每失败一次间隔加倍，最长 5 分钟），再次送达它们。回报到达前该会话已有其他事件，说明唤醒已送达，回报被忽略。已在 Windows 上用 Claude 桌面应用和 Codex 桌面应用实测（2026-10-23）：两个方向都能在数秒内叫醒空闲的对话。已知限制：
+会话处于 `working`，或者 listen 模式的 Stop hook 正在等待时，后台等待不会送达，所以同一条消息只提醒一次。`codex queue` 失败（出错或退出码非 0）时，Codex 的后台等待回报 `ok: false`，host 撤销这次唤醒：它提醒过的消息和通知重新算作未提醒，会话退出 `working`，这一轮不计入自动轮次，失败的唤醒记入 `host.log`（会话、唤醒 ID、再次送达的消息和通知各有几条）；随后等待在 1 秒后重新请求（每失败一次间隔加倍，最长 5 分钟），再次送达它们。回报到达前该会话已有其他事件，说明唤醒已送达，回报被忽略。已在 Windows 上用 Claude 桌面应用和 Codex 桌面应用实测（2026-10-23）：两个方向都能在数秒内叫醒空闲的对话。已知限制：
 
 - Codex 只会为运行中的 Codex 应用里已加载的对话启动排队的一轮。Codex 重启后，用户点开对话才会加载。
 - Codex 的后台等待会随 Codex 应用退出而结束，要等该对话再结束一轮才会重新启动。这期间发来的消息留在 host 里为未读（不进入 Codex 自己的队列），直到用户下次在该对话里发消息。

package/docs/CHANGELOG_zh.md

@@ -4,6 +4,16 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [0.12.4] - 2026-10-30
+
+### 修复
+
+- Windows 上空闲的 Codex 对话重新能被叫醒。Stop `--wait` hook 启动的后台等待进程继承了 Codex 读取 hook 输出用的管道（Codex 通过 PowerShell 运行 hook），Codex 一直等这些管道直到 hook 超时，然后连等待进程一起结束：会话从不显示为 `listening`，只在下次输入或调用工具时才看到消息。现在等待进程由 PowerShell 的 `Start-Process` 启动，它不传递任何句柄。
+
+### 变更
+
+- 客户端回报失败的唤醒（`codex queue` 出错或退出码非 0）在 host 撤销它时记入 `host.log`：会话、唤醒 ID、再次送达的消息和通知各有几条。此前撤销和重试不留任何痕迹。
+
 ## [0.12.3] - 2026-10-29
 
 ### 修复

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-nexus",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration.",
   "main": "build/index.js",
   "type": "module",