@zq-silk/yui 1.1.0 → 1.1.2

package/README.md

@@ -43,7 +43,7 @@ not from terminal windows you juggle or details you have to remember.
 ## Quick start
 
 You need Linux x64 (glibc) or macOS (x64 or Apple Silicon), Git, tmux, and
-Node.js `^20.17.0`, `^22.9.0` or `^24.0.0`. On macOS install tmux with
+Node.js `^20.17.0`, `^22.9.0`, `^24.0.0` or `^26.0.0`. On macOS install tmux with
 `brew install tmux`. For the simplest setup, have Codex CLI or Claude Code CLI
 installed and ready to use with your own account. Yui coordinates those
 Agents; it does not supply model access.

package/dist/doctor/doctor.js

@@ -1,6 +1,7 @@
 import { accessSync, constants, existsSync, lstatSync, realpathSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import Database from "better-sqlite3";
+import { inspectPty } from "./ptyProbe.js";
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { operationalAgentEnvironment } from "../agent/launchEnvironment.js";
 import { resolveTmuxBin } from "../config/yuiConfig.js";
@@ -137,6 +138,7 @@ async function inspectDoctor(env, executor) {
             controller,
             ...(domain === undefined ? [] : [domain]),
             ...toolChecks,
+            ...inspectPty(),
             ...agentChecks,
             ...review.checks
         ],

package/dist/doctor/ptyProbe.js

@@ -0,0 +1,74 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+/** Native loading and spawn happen outside Doctor: a native abort cannot kill the CLI. */
+export function inspectPty(options = {}) {
+    const started = Date.now();
+    const checks = [];
+    const major = Number(process.versions.node.split(".")[0]);
+    if (![20, 22, 24, 26].includes(major)) {
+        checks.push({
+            name: "pty Node runtime", status: "unsupported",
+            detail: `Node ${process.versions.node} is outside Yui's supported Node 20/22/24/26 range; this is not evidence of a helper permission failure.`
+        });
+    }
+    let entry;
+    let identity;
+    try {
+        const require = createRequire(options.requireFrom ?? import.meta.url);
+        entry = require.resolve("node-pty");
+        const manifest = require.resolve("node-pty/package.json");
+        const version = JSON.parse(readFileSync(manifest, "utf8")).version;
+        identity = `node-pty ${version}; entry=${entry}; package=${manifest}`;
+    }
+    catch (error) {
+        return [...checks, {
+                name: "node-pty",
+                status: error.code === "MODULE_NOT_FOUND" ? "missing" : "invalid",
+                detail: `Dependency resolution failed: ${String(error)}`
+            }];
+    }
+    const timeoutMs = options.timeoutMs ?? 1_500;
+    const result = spawnSync(process.execPath, [
+        fileURLToPath(new URL("./ptyProbeChild.js", import.meta.url)),
+        entry, String(options.probeTimeoutMs ?? 750)
+    ], {
+        // No NODE_OPTIONS, shell startup files, preload hooks or user configuration.
+        env: { PATH: "/usr/bin:/bin", LANG: "C" },
+        cwd: "/",
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: 64 * 1024
+    });
+    for (const line of (result.stdout ?? "").split("\n").filter(Boolean)) {
+        try {
+            const check = JSON.parse(line);
+            if (["node-pty", "pty helper", "pty spawn"].includes(check.name)
+                && ["ok", "missing", "invalid"].includes(check.status)
+                && typeof check.detail === "string") {
+                checks.push({ ...check, detail: `${identity}; ${check.detail}` });
+            }
+        }
+        catch { /* Native diagnostics on stdout are retained below on failure. */ }
+    }
+    const completed = checks.some(check => check.name === "pty spawn")
+        || checks.some(check => check.status !== "ok" && check.name !== "pty Node runtime");
+    if (result.error || result.signal || result.status !== 0 || !completed) {
+        const timedOut = result.error?.code === "ETIMEDOUT";
+        // A partial success line is not success if the isolated process failed to finish.
+        for (let i = 0; i < checks.length; i += 1) {
+            if (checks[i].name === "pty spawn" && checks[i].status === "ok") {
+                checks[i] = { ...checks[i], status: "invalid", detail: `${checks[i].detail}; isolated probe did not finish successfully` };
+            }
+        }
+        checks.push({
+            name: "pty probe", status: "invalid",
+            detail: `${identity}; ${timedOut ? `timeout after ${timeoutMs}ms` : "isolated probe failed"}; exit=${result.status} signal=${result.signal}; ${result.error?.message ?? ""} ${(result.stderr || result.stdout || "").trim()}`
+        });
+    }
+    return checks.map(check => ({
+        ...check, detail: `${check.detail}; elapsed=${Date.now() - started}ms`
+    }));
+}

package/dist/doctor/ptyProbeChild.js

@@ -0,0 +1,90 @@
+import { accessSync, constants, statSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+const require = createRequire(import.meta.url);
+const entry = process.argv[2];
+const timeoutMs = Number(process.argv[3]);
+const report = (check) => writeSync(1, `${JSON.stringify(check)}\n`);
+const errorDetail = (error) => error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+async function probe() {
+    let pty;
+    try {
+        pty = require(entry);
+        if (typeof pty.spawn !== "function")
+            throw new Error("node-pty does not expose spawn");
+        report({ name: "node-pty", status: "ok", detail: "native module loaded" });
+    }
+    catch (error) {
+        report({
+            name: "node-pty", status: "invalid",
+            detail: `native load failed: ${errorDetail(error)}. If installation reported blocked lifecycle scripts, review npm allow-scripts separately; no install files were changed.`
+        });
+        return;
+    }
+    if (process.platform === "darwin") {
+        // The pinned node-pty selects build/Release, build/Debug or prebuilds.
+        // Inspect the module it actually loaded, not the first helper that exists.
+        const native = Object.keys(require.cache).find(path => basename(path) === "pty.node");
+        if (!native) {
+            report({ name: "pty helper", status: "invalid", detail: "Cannot identify the loaded pty.node; helper path is unverified." });
+            return;
+        }
+        const helper = join(dirname(native), "spawn-helper");
+        let mode = "unknown";
+        try {
+            mode = (statSync(helper).mode & 0o7777).toString(8).padStart(4, "0");
+            accessSync(helper, constants.X_OK);
+            report({ name: "pty helper", status: "ok", detail: `helper=${helper}; mode=${mode}; executable by current user` });
+        }
+        catch (error) {
+            const code = error.code;
+            report({
+                name: "pty helper", status: code === "ENOENT" ? "missing" : "invalid",
+                detail: `helper=${helper}; mode=${mode}; ${code === "EACCES" ? "permission denied for current user" : "helper check failed"}: ${errorDetail(error)}`
+            });
+            return;
+        }
+    }
+    await new Promise(resolve => {
+        const marker = "yui-pty-probe-ok";
+        let terminal;
+        let output = "";
+        let finished = false;
+        const finish = (status, detail, kill = false) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (kill && terminal) {
+                try {
+                    terminal.kill("SIGKILL");
+                }
+                catch (error) {
+                    detail += `; cleanup: ${errorDetail(error)}`;
+                }
+            }
+            report({ name: "pty spawn", status, detail });
+            resolve();
+        };
+        const timer = setTimeout(() => finish("invalid", `timeout after ${timeoutMs}ms waiting for output and normal exit`, true), timeoutMs);
+        try {
+            // Absolute, fixed executable; no shell, Node preloads, Agent or account access.
+            terminal = pty.spawn("/bin/echo", [marker], {
+                name: "xterm", cols: 80, rows: 24, cwd: "/",
+                env: { PATH: "/usr/bin:/bin", LANG: "C" }
+            });
+            terminal.onData(data => { output = (output + data).slice(-4096); });
+            terminal.onExit(({ exitCode, signal }) => {
+                const ok = exitCode === 0 && !signal && output.replace(/\r/g, "").trim() === marker;
+                finish(ok ? "ok" : "invalid", `${ok ? "expected output and normal exit confirmed (PTY dependency only; Web Terminal and Provider protocols unverified)" : "unexpected output or exit"}; exit=${exitCode}; signal=${signal ?? 0}; output=${JSON.stringify(output)}`);
+            });
+        }
+        catch (error) {
+            finish("invalid", `spawn failed: ${errorDetail(error)}`, true);
+        }
+    });
+}
+await probe();
+// node-pty's native watcher can retain handles; the fixed child has exited, or
+// was explicitly killed on failure. The parent also bounds native hangs/aborts.
+process.exit(0);

package/docs/testing/verification-levels.md

@@ -101,6 +101,8 @@ do not add prose-matching tests or claim model validation from static checks.
 `ci.yml` runs core plus one assembled-package normal-path smoke per supported
 platform (Linux x64, Mac Intel and Apple Silicon) on every PR, without another
 lint or broad regression suite.
+Linux runs on Node 24 and 26; release fresh-install smoke covers Node 20, 22,
+24 and 26 on all three platforms.
 `node scripts/smoke-runtime-package.mjs --assembled .release-stage` exercises
 the actual CLI/Controller/Host/SQLite and isolated tmux, replacing only the
 external Provider with a deterministic fixture. It covers setup, durable input
@@ -118,6 +120,14 @@ freshly installed package through
 artifact and provenance boundaries. This validates runtime integration, not
 real-model behavior. Pure contract and safety tests remain in `test/core`;
 production wiring is exercised here rather than only through mocked ports.
+The native dependency check launches a fixed local program through PTY and
+requires its output and normal exit. Installed-package smoke explicitly checks
+default Doctor's PTY results using dependencies resolved from the consumer.
+On macOS it also tests a disposable copy with a non-executable spawn-helper:
+Doctor must report the selected helper path and permissions without repairing it.
+Doctor's isolated PTY probe waits up to 750 ms for output/exit, with a 1.5-second
+outer native-process limit, and reports elapsed time. Existing Agent/Controller
+diagnostics have their own costs; this is not a one-second whole-Doctor guarantee.
 The package smoke also checks unconditional status identity and update-owned
 resource/identity capture through the assembled package. Real lifecycle children
 stop the exact Controller and restore its captured launch identity while their

package/docs/testing/verification-levels.zh-CN.md

@@ -74,6 +74,8 @@ package-start 检查跟随已安装树中的本地 Skill 引用，包括跨 Role
 
 `ci.yml` 在每个 PR 上构建一次，运行 core 及一个组装包正常链路检查，不重复 lint，
 也不增加宽泛回归套件。
+Linux CI 在 Node 24 和 26 上运行；发布时的全新安装 smoke 覆盖三个平台上的
+Node 20、22、24 和 26。
 `node scripts/smoke-runtime-package.mjs --assembled .release-stage` 经过真实
 CLI/Controller/Host/SQLite 与隔离 tmux，仅用确定性夹具替换外部 Provider。它验证
 setup、输入跨重启持久化及幂等、scratch 激活、原生结果入库、完成后保留会话、
@@ -85,6 +87,12 @@ setup、输入跨重启持久化及幂等、scratch 激活、原生结果入库
 npm bin、依赖、受支持 Node 版本、产物和 provenance 边界。这证明运行时集成，不证明
 真实模型行为。纯契约与安全检查保留在 `test/core`，生产组件组装在这里验证，
 不只依赖模拟端口。
+原生依赖检查必须通过 PTY 启动固定本地程序，确认输出和正常退出。安装包 smoke
+明确断言默认 Doctor 的 PTY 检查成功，并从消费者安装目录解析依赖。macOS 还会
+在可丢弃的依赖副本中移除 spawn-helper 执行权限，验证 Doctor 报出实际 helper
+路径和权限原因且不自动修复。Doctor 的隔离 PTY 探针等待输出／退出最多 750 ms，
+外层原生进程限制为 1.5 秒，并报告耗时；原有 Agent／Controller 检查另有成本，
+这不是整个 Doctor 一秒内返回的保证。
 组装包检查还验证固定身份输出，以及升级侧通过组装包采集资源和精确 Controller 身份，
 并在父进程持有交接锁时，通过真实生命周期子进程停止精确 Controller、恢复其已捕获的
 启动身份。无关调用仍被锁阻止，锁保持由父进程持有，持久输入不变；

package/i18n/README.zh-CN.md

@@ -41,7 +41,7 @@ npm 包包含 Linux x64、Mac Intel 和 Apple Silicon 的 Yui 预编译程序。
 同一份包在三个平台验证后发布，运行时只选择对应平台的程序。
 
 需要 Linux x64 / glibc 或 macOS（x64 或 Apple Silicon）、Git、tmux，以及
-Node.js `^20.17.0`、`^22.9.0` 或 `^24.0.0`。macOS 上可用
+Node.js `^20.17.0`、`^22.9.0`、`^24.0.0` 或 `^26.0.0`。macOS 上可用
 `brew install tmux` 安装 tmux。最简单的方式是先安装 Codex CLI 或 Claude
 Code CLI，并确保它已经可以使用你自己的账号正常工作。Yui 负责协调 Agent，
 不提供模型访问额度。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": "^20.17.0 || ^22.9.0 || ^24.0.0"
+    "node": "^20.17.0 || ^22.9.0 || ^24.0.0 || ^26.0.0"
   },
   "os": [
     "linux",
@@ -49,7 +49,7 @@
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.11.1",
-    "node-pty": "^1.1.0",
+    "node-pty": "1.2.0-beta.15",
     "smol-toml": "1.8.0",
     "ws": "^8.21.1"
   }