autowonder 0.2.136 → 0.2.138

package/README.md

@@ -6,16 +6,16 @@ AutoWonder 本地 agent runtime。安装后启动 daemon，持续轮询本地 as
 
 ```bash
 # Qoder CLI（模型使用 provider model ID；Context Window 使用固定档位）
-npx -y autowonder@0.2.136 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qoder --model qmodel_latest --reasoning-effort medium --context-window 260000
+npx -y autowonder@0.2.138 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qoder --model qmodel_latest --reasoning-effort medium --context-window 260000
 
 # Qoder CLI CN
-npx -y autowonder@0.2.136 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
+npx -y autowonder@0.2.138 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
 
 # Claude Code
-npx -y autowonder@0.2.136 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider claude
+npx -y autowonder@0.2.138 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider claude
 
 # Codex CLI
-npx -y autowonder@0.2.136 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider codex --model gpt-5.5 --reasoning-effort medium
+npx -y autowonder@0.2.138 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider codex --model gpt-5.5 --reasoning-effort medium
 ```
 
 `connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。选择 Qoder 时需要 Node.js 20+；runtime 会在缺少 `qodercli` 时自动通过 npm 安装，并在尚未登录时打开 Qoder 浏览器登录。Claude Code 和 Codex CLI 仍需提前安装并登录。runtime 会继承当前用户的 HOME、环境变量和 CLI 登录状态。
@@ -62,7 +62,7 @@ mv "$queue/.assignment.tmp" "$queue/assignment.json"
 也可以直接提交到本地 API：
 
 ```bash
-npx -y autowonder@0.2.136 dispatch ./assignment.json
+npx -y autowonder@0.2.138 dispatch ./assignment.json
 ```
 
 ## 上传工单附件
@@ -70,7 +70,7 @@ npx -y autowonder@0.2.136 dispatch ./assignment.json
 把本地需求/设计文档直接上传到工单，避免在会话里传递大文件：
 
 ```bash
-npx -y autowonder@0.2.136 workitem upload --server-url <autowonder-server-url> --workitem-id <id> --file <filepath-1> --file <filepath-2> --json
+npx -y autowonder@0.2.138 workitem upload --server-url <autowonder-server-url> --workitem-id <id> --file <filepath-1> --file <filepath-2> --json
 ```
 
 上传令牌通过 MCP 工具 `autowonder.workitem_cli_upload_token` 签发，经 `--token` 或 `AUTOWONDER_UPLOAD_TOKEN` 环境变量传入。`--file` 可重复指定多个文件；`--json` 输出机器可读结果。失败时按错误类型返回不同退出码（401→3、403→4、404→5、409→6、413→7、其他 4xx→8、网络/重定向→9）。
@@ -78,8 +78,8 @@ npx -y autowonder@0.2.136 workitem upload --server-url <autowonder-server-url> -
 ## 管理 daemon
 
 ```bash
-npx -y autowonder@0.2.136 status
-npx -y autowonder@0.2.136 stop
+npx -y autowonder@0.2.138 status
+npx -y autowonder@0.2.138 stop
 ```
 
 默认 API 是 `http://127.0.0.1:34989`，日志位于 `~/.autowonder/daemon.log`。npm 包不包含任何 agent、MCP 或服务端凭证。
@@ -87,7 +87,7 @@ npx -y autowonder@0.2.136 stop
 ## 调试
 
 ```bash
-npx -y autowonder@0.2.136 connect ... --debug
+npx -y autowonder@0.2.138 connect ... --debug
 ```
 
 `--debug` 会让 CLI 以 `AUTOWONDER_DEBUG=1` 启动 daemon，把完整的 daemon 与 agent 活动（runtime 事件流、provider 事件解码、重试退避与会话门等待、空闲时的阻塞点）同时输出到控制台和会话调试日志。调试日志不做脱敏，仅用于本机排障；不传 `--debug` 时该环境变量不会注入。

package/bin/cli.js

@@ -9,6 +9,13 @@ const os = require("os");
 const https = require("https");
 const http = require("http");
 
+const { ensureDir, error, findOnPath, log, resolveUserPath } = require("./shared");
+const {
+  ensureQoderReady,
+  findQoderExecutable,
+  isQoderFamilyProvider,
+} = require("./qoder-bootstrap");
+
 const VERSION = require("../package.json").version;
 const AUTOWONDER_HOME = path.join(os.homedir(), ".autowonder");
 const BIN_DIR = path.join(AUTOWONDER_HOME, "bin");
@@ -23,47 +30,6 @@ const CONFIG_PATH = path.join(AUTOWONDER_HOME, "config.json");
 const PID_PATH = path.join(AUTOWONDER_HOME, "daemon.pid");
 const STATE_PATH = path.join(AUTOWONDER_HOME, "daemon-state.json");
 const LOG_PATH = path.join(AUTOWONDER_HOME, "daemon.log");
-const MANAGED_QODER_DIR = path.join(AUTOWONDER_HOME, "qoder-cli");
-const MANAGED_QODERCN_DIR = path.join(AUTOWONDER_HOME, "qoder-cn-cli");
-
-// qoder and qodercn are two distinct provider identities that share the same
-// bootstrap flow. Each identity keeps its own executable, npm package, managed
-// install dir and env override so the two CLIs never shadow each other.
-const QODER_FAMILY_PROFILES = {
-  qoder: {
-    displayName: "Qoder CLI",
-    executable: "qodercli",
-    envVar: "AUTOWONDER_QODER_CLI",
-    npmPackage: "@qoder-ai/qodercli@latest",
-    managedDir: MANAGED_QODER_DIR,
-    managedBinName: "qodercli",
-    windowsShimName: "qodercli.cmd",
-    unixCandidates: [
-      path.join(os.homedir(), ".local", "bin", "qodercli"),
-      path.join(os.homedir(), ".qoder", "bin", "qodercli", "qodercli"),
-    ],
-  },
-  qodercn: {
-    displayName: "Qoder CLI CN",
-    executable: "qodercn",
-    envVar: "AUTOWONDER_QODERCN_CLI",
-    npmPackage: "@qodercn-ai/qoderclicn@latest",
-    managedDir: MANAGED_QODERCN_DIR,
-    managedBinName: "qodercn",
-    windowsShimName: "qodercn.cmd",
-    unixCandidates: [
-      path.join(os.homedir(), ".local", "bin", "qodercn"),
-    ],
-  },
-};
-
-function profileForExecutable(name) {
-  return Object.values(QODER_FAMILY_PROFILES).find((profile) => profile.executable === name) || null;
-}
-
-function isQoderFamilyProvider(provider) {
-  return provider === "qoder" || provider === "qodercn";
-}
 
 const BINARY_BASE_URL = process.env.AUTOWONDER_BINARY_URL || "";
 const SOURCE_REPO = process.env.AUTOWONDER_SOURCE_REPO || "";
@@ -78,172 +44,14 @@ function safeChmod(filePath, mode) {
 
 // ─── Helpers ─────────────────────────────────────────────────────────
 
-function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true });
-}
-
-function log(msg) {
-  console.log(`\x1b[36m[autowonder]\x1b[0m ${msg}`);
-}
-
-function error(msg) {
-  console.error(`\x1b[31m[autowonder]\x1b[0m ${msg}`);
-}
-
 function detectProvider() {
   const providers = [];
-  if (findExecutable("claude")) providers.push("claude");
-  if (findExecutable("codex")) providers.push("codex");
-  if (findExecutable("qodercli")) providers.push("qoder");
+  if (findOnPath("claude")) providers.push("claude");
+  if (findOnPath("codex")) providers.push("codex");
+  if (findQoderExecutable("qoder")) providers.push("qoder");
   return providers;
 }
 
-function findExecutable(name) {
-  const profile = profileForExecutable(name);
-  if (profile && process.env[profile.envVar]) {
-    const configured = resolveUserPath(process.env[profile.envVar]);
-    try { fs.accessSync(configured, fs.constants.X_OK); return configured; } catch {}
-  }
-  const finder = process.platform === "win32" ? "where" : "which";
-  const found = spawnSync(finder, [name], { encoding: "utf8", timeout: 3000 });
-  if (found.status === 0) {
-    const first = (found.stdout || "").split(/\r?\n/).map((value) => value.trim()).find(Boolean);
-    if (first) return first;
-  }
-  if (profile && process.platform !== "win32") {
-    const candidates = [
-      path.join(profile.managedDir, "node_modules", ".bin", profile.managedBinName),
-      ...profile.unixCandidates,
-    ];
-    for (const candidate of candidates) {
-      try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch {}
-    }
-  }
-  if (profile && process.platform === "win32") {
-    const candidate = path.join(profile.managedDir, "node_modules", ".bin", profile.windowsShimName);
-    try { fs.accessSync(candidate, fs.constants.F_OK); return candidate; } catch {}
-  }
-  return "";
-}
-
-function spawnQoderSync(executable, args, options = {}) {
-  // npm exposes package binaries as .cmd shims on Windows. CreateProcess
-  // cannot execute those shims directly, so let ComSpec resolve them.
-  return spawnSync(executable, args, { ...options, shell: IS_WIN32 });
-}
-
-function qoderAuthenticated(executable) {
-  const result = spawnQoderSync(executable, ["--list-models"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 20000,
-  });
-  return result.status === 0 && Boolean((result.stdout || "").trim());
-}
-
-function installQoderCLI(provider) {
-  const profile = QODER_FAMILY_PROFILES[provider];
-  log(`${profile.displayName} is not installed. Installing ${profile.npmPackage}...`);
-  const args = [
-    "install", "--prefix", profile.managedDir, profile.npmPackage, "--no-audit", "--no-fund",
-  ];
-  // npm is a .cmd shim on Windows. When launched by npx, npm_execpath points
-  // at npm-cli.js, which Node can execute directly without cmd.exe quoting.
-  const runNpm = (npmArgs) => IS_WIN32 && process.env.npm_execpath
-    ? spawnSync(process.execPath, [process.env.npm_execpath, ...npmArgs], { stdio: "inherit" })
-    : spawnSync("npm", npmArgs, { stdio: "inherit" });
-  let result = runNpm(args);
-  if (result.status !== 0 && IS_WIN32) {
-    log(`Default npm registry failed; retrying ${profile.displayName} installation with npmmirror...`);
-    result = runNpm([...args, "--registry", "https://registry.npmmirror.com"]);
-  }
-  if (result.status !== 0) {
-    const detail = result.error?.message || (result.signal ? `signal ${result.signal}` : `exit status ${result.status}`);
-    error(`Failed to install ${profile.displayName} into ${profile.managedDir}: ${detail}`);
-    return "";
-  }
-  const executable = findExecutable(profile.executable);
-  if (!executable) error(`${profile.displayName} was installed but ${profile.executable} is not available on PATH.`);
-  return executable;
-}
-
-function qoderNodeVersion() {
-  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_NODE_VERSION) {
-    return process.env.AUTOWONDER_TEST_NODE_VERSION;
-  }
-  return process.versions.node;
-}
-
-const QODER_AUTH_RECHECK_TIMEOUT_MS = 3 * 60 * 1000;
-
-function qoderAuthRecheckTimeoutMs() {
-  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_TIMEOUT_MS) {
-    return Number.parseInt(process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_TIMEOUT_MS, 10) || 1;
-  }
-  return QODER_AUTH_RECHECK_TIMEOUT_MS;
-}
-
-function qoderAuthRecheckDelayMs() {
-  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_DELAY_MS) {
-    return Number.parseInt(process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_DELAY_MS, 10) || 0;
-  }
-  return 3000;
-}
-
-// Credentials written by `qodercli login` may not be readable immediately,
-// so the post-login authentication check retries before declaring failure.
-async function qoderAuthenticatedAfterLogin(executable) {
-  const deadline = Date.now() + qoderAuthRecheckTimeoutMs();
-  while (true) {
-    if (qoderAuthenticated(executable)) return true;
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) return false;
-    log("Waiting for Qoder login to finish...");
-    await new Promise((resolve) => setTimeout(resolve, Math.min(qoderAuthRecheckDelayMs(), remainingMs)));
-  }
-}
-
-function qoderLoginCommand(executable) {
-  const quoted = `'${executable.replace(/'/g, "''")}'`;
-  return IS_WIN32 ? `& ${quoted} login` : `${quoted} login`;
-}
-
-async function ensureQoderReady(provider) {
-  if (process.env.AUTOWONDER_SKIP_QODER_BOOTSTRAP === "1") return true;
-  const profile = QODER_FAMILY_PROFILES[provider];
-  const nodeVersion = qoderNodeVersion();
-  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
-  if (!Number.isInteger(nodeMajor) || nodeMajor < 20) {
-    error(`${profile.displayName} requires Node.js 20 or newer; current version is ${nodeVersion}. Upgrade Node.js and retry.`);
-    return false;
-  }
-  let executable = findExecutable(profile.executable);
-  if (!executable) executable = installQoderCLI(provider);
-  if (!executable) return false;
-  if (!qoderAuthenticated(executable)) {
-    log(`${profile.displayName} login is required. Opening browser login...`);
-    const login = spawnQoderSync(executable, ["login"], { stdio: "inherit" });
-    if (login.status !== 0) {
-      const detail = login.error?.message || `exit status ${login.status}`;
-      error(`Qoder login command failed: ${detail}`);
-      error(`Run ${qoderLoginCommand(executable)} and retry.`);
-      return false;
-    }
-    if (!(await qoderAuthenticatedAfterLogin(executable))) {
-      error(`Qoder login did not complete. Run ${qoderLoginCommand(executable)} and retry.`);
-      return false;
-    }
-  }
-  process.env[profile.envVar] = executable;
-  const executableDir = path.dirname(executable);
-  const pathEntries = (process.env.PATH || "").split(path.delimiter);
-  if (!pathEntries.includes(executableDir)) {
-    process.env.PATH = `${executableDir}${path.delimiter}${process.env.PATH || ""}`;
-  }
-  log(`${profile.displayName} is installed and authenticated.`);
-  return true;
-}
-
 const QODER_MODELS = new Set([
   "auto", "ultimate", "performance", "efficient", "lite", "cmodel",
   "qmodel_preview", "qmodel_latest", "qmodel", "kmodel_latest", "kmodel",
@@ -539,7 +347,7 @@ async function cmdConnect(args) {
     error(`No agent CLI detected. Install one of: claude, codex, qodercli`);
     process.exit(1);
   }
-  if (isQoderFamilyProvider(provider) && !(await ensureQoderReady(provider))) process.exit(1);
+  if (isQoderFamilyProvider(provider) && !(await ensureQoderReady(provider, { debug: Boolean(flags.debug) }))) process.exit(1);
 
   // A version-pinned npx command must always run the binary bundled with that package.
   // Windows locks a running .exe. Its versioned path is immutable, so another
@@ -625,14 +433,6 @@ async function cmdConnect(args) {
   process.on("SIGTERM", () => { child.kill("SIGTERM"); });
 }
 
-function resolveUserPath(value) {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/") || value.startsWith("~\\")) {
-    return path.resolve(os.homedir(), value.slice(2));
-  }
-  return path.resolve(value);
-}
-
 async function cmdStart(args) {
   const flags = parseFlags(args, ["provider", "max-tasks", "addr"]);
 

package/bin/qoder-bootstrap.js

@@ -0,0 +1,578 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const { ensureDir, error, findOnPath, log, resolveUserPath } = require("./shared");
+
+const IS_WIN32 = process.platform === "win32";
+
+// qoder and qodercn are two distinct provider identities that share the same
+// bootstrap flow. Each identity keeps its own executable, npm package, managed
+// install dir, managed config root and env overrides so the two CLIs never
+// shadow each other.
+const QODER_FAMILY_PROFILES = {
+  qoder: {
+    displayName: "Qoder CLI",
+    executable: "qodercli",
+    envVar: "AUTOWONDER_QODER_CLI",
+    npmPackage: "@qoder-ai/qodercli@latest",
+    managedDirName: "qoder-cli",
+    managedConfigRootName: "qoder-home",
+    configDirEnv: "QODER_CONFIG_DIR",
+    defaultConfigRootName: ".qoder",
+    managedBinName: "qodercli",
+    windowsShimName: "qodercli.cmd",
+    unixCandidateRelPaths: [
+      [".local", "bin", "qodercli"],
+      [".qoder", "bin", "qodercli", "qodercli"],
+    ],
+  },
+  qodercn: {
+    displayName: "Qoder CLI CN",
+    executable: "qodercn",
+    envVar: "AUTOWONDER_QODERCN_CLI",
+    npmPackage: "@qodercn-ai/qoderclicn@latest",
+    managedDirName: "qoder-cn-cli",
+    managedConfigRootName: "qoder-cn-home",
+    configDirEnv: "QODERCN_CONFIG_DIR",
+    defaultConfigRootName: ".qoder-cn",
+    managedBinName: "qodercn",
+    windowsShimName: "qodercn.cmd",
+    unixCandidateRelPaths: [[".local", "bin", "qodercn"]],
+  },
+};
+
+// Paths are derived per call instead of at module load so in-process tests can
+// relocate HOME between cases.
+function qoderPaths(profile) {
+  const home = os.homedir();
+  const autowonderHome = path.join(home, ".autowonder");
+  return {
+    managedDir: path.join(autowonderHome, profile.managedDirName),
+    managedConfigRoot: path.join(autowonderHome, profile.managedConfigRootName),
+    defaultConfigRoot: path.join(home, profile.defaultConfigRootName),
+    statePath: path.join(autowonderHome, "qoder-cli-state.json"),
+    unixCandidates: profile.unixCandidateRelPaths.map((parts) => path.join(home, ...parts)),
+  };
+}
+
+function isQoderFamilyProvider(provider) {
+  return provider === "qoder" || provider === "qodercn";
+}
+
+function spawnQoderSync(executable, args, options = {}) {
+  // npm exposes package binaries as .cmd shims on Windows. CreateProcess
+  // cannot execute those shims directly, so let ComSpec resolve them.
+  return spawnSync(executable, args, { ...options, shell: IS_WIN32 });
+}
+
+function findQoderExecutable(provider) {
+  const profile = QODER_FAMILY_PROFILES[provider];
+  const paths = qoderPaths(profile);
+  const configured = process.env[profile.envVar];
+  if (configured) {
+    const resolved = resolveUserPath(configured);
+    try {
+      fs.accessSync(resolved, fs.constants.X_OK);
+      return resolved;
+    } catch {
+      error(`${profile.envVar} points at ${resolved}, which is not executable; falling back to PATH.`);
+    }
+  }
+  const onPath = findOnPath(profile.executable);
+  if (onPath) return onPath;
+  if (IS_WIN32) {
+    const shim = path.join(paths.managedDir, "node_modules", ".bin", profile.windowsShimName);
+    try { fs.accessSync(shim, fs.constants.F_OK); return shim; } catch {}
+    return "";
+  }
+  const candidates = [
+    path.join(paths.managedDir, "node_modules", ".bin", profile.managedBinName),
+    ...paths.unixCandidates,
+  ];
+  for (const candidate of candidates) {
+    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch {}
+  }
+  return "";
+}
+
+function installQoderCLI(provider) {
+  const profile = QODER_FAMILY_PROFILES[provider];
+  const managedDir = qoderPaths(profile).managedDir;
+  log(`${profile.displayName} is not installed. Installing ${profile.npmPackage}...`);
+  const args = [
+    "install", "--prefix", managedDir, profile.npmPackage, "--no-audit", "--no-fund",
+  ];
+  // npm is a .cmd shim on Windows. When launched by npx, npm_execpath points
+  // at npm-cli.js, which Node can execute directly without cmd.exe quoting.
+  const runNpm = (npmArgs) => IS_WIN32 && process.env.npm_execpath
+    ? spawnSync(process.execPath, [process.env.npm_execpath, ...npmArgs], { stdio: "inherit" })
+    : spawnSync("npm", npmArgs, { stdio: "inherit" });
+  let result = runNpm(args);
+  if (result.status !== 0 && IS_WIN32) {
+    log(`Default npm registry failed; retrying ${profile.displayName} installation with npmmirror...`);
+    result = runNpm([...args, "--registry", "https://registry.npmmirror.com"]);
+  }
+  if (result.status !== 0) {
+    const detail = result.error?.message || (result.signal ? `signal ${result.signal}` : `exit status ${result.status}`);
+    error(`Failed to install ${profile.displayName} into ${managedDir}: ${detail}`);
+    return "";
+  }
+  const executable = findQoderExecutable(provider);
+  if (!executable) error(`${profile.displayName} was installed but ${profile.executable} is not available on PATH.`);
+  return executable;
+}
+
+const MACHINE_ID_REL_PATH = path.join(".auth", "machine_id");
+const CREDENTIAL_REL_PATH = path.join(".auth", "user");
+
+// The version is captured for diagnostics and identity comparison only. No
+// control-flow decision anywhere in this module reads it.
+function qoderBinaryVersion(executable) {
+  const result = spawnQoderSync(executable, ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 20000,
+  });
+  // stdout wins so a warning on stderr cannot masquerade as the version and
+  // make the identity comparison see a change that did not happen.
+  const firstLine = (stream) => (stream || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  return firstLine(result.stdout) || firstLine(result.stderr) || "unknown";
+}
+
+// A missing or unreadable record means "no history", never a bootstrap failure.
+function readQoderState(profile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(qoderPaths(profile).statePath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch { return {}; }
+}
+
+function writeQoderState(profile, provider, entry) {
+  const statePath = qoderPaths(profile).statePath;
+  const state = readQoderState(profile);
+  state[provider] = entry;
+  try {
+    ensureDir(path.dirname(statePath));
+    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  } catch {}
+}
+
+function readMachineId(configRoot) {
+  try {
+    return { present: true, value: fs.readFileSync(path.join(configRoot, MACHINE_ID_REL_PATH), "utf8").trim() };
+  } catch (err) {
+    if (err.code === "ENOENT") return { present: false, value: "" };
+    return { present: false, value: "", unreadable: err.code || String(err) };
+  }
+}
+
+// Probes the nearest existing ancestor rather than creating the root, so merely
+// inspecting a root leaves it absent — rung D promises it did not touch the
+// customer's own configuration.
+function configRootWritable(configRoot) {
+  let target = configRoot;
+  while (!fs.existsSync(target)) {
+    const parent = path.dirname(target);
+    if (parent === target) return false;
+    target = parent;
+  }
+  const probe = path.join(target, `.autowonder-probe-${process.pid}`);
+  try {
+    fs.writeFileSync(probe, "probe");
+    fs.unlinkSync(probe);
+    return true;
+  } catch { return false; }
+}
+
+function machineIdDrift(before, after) {
+  if (after.unreadable) return `${MACHINE_ID_REL_PATH} became unreadable (${after.unreadable})`;
+  if (before.present && !after.present) return `${MACHINE_ID_REL_PATH} disappeared while probing authentication`;
+  if (before.present && after.present && before.value !== after.value) {
+    return `${MACHINE_ID_REL_PATH} changed while probing authentication (${before.value} -> ${after.value})`;
+  }
+  // An absent id becoming present is the CLI's legal first write.
+  return "";
+}
+
+// 126 is "found but not executable", 127 is the shell's "not found", and
+// cmd.exe reports the same miss as 9009. All three mean the binary is broken
+// rather than unauthenticated, which is what sends rung B to reinstall it.
+function isCliUnusable(probe) {
+  if (probe.spawnError) return true;
+  if (probe.status === null || probe.status === undefined) return true;
+  if (IS_WIN32 && probe.status === 9009) return true;
+  return probe.status === 126 || probe.status === 127;
+}
+
+function cliUnusableReason(probe) {
+  if (probe.spawnError) return `the CLI could not be started: ${probe.spawnError}`;
+  if (probe.status === null || probe.status === undefined) return "the CLI did not exit (timed out or was signalled)";
+  return `the CLI exited with status ${probe.status}, which is not an authentication failure`;
+}
+
+// `--list-models` is the cheapest command that requires valid credentials, so
+// exit 0 with non-empty stdout is the authentication oracle. Probes always run
+// against the config root under evaluation, otherwise the verdict would
+// describe whatever root the ambient environment points at.
+function probeQoderAuth(profile, executable, configRoot, options = {}) {
+  const result = spawnQoderSync(executable, ["--list-models"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 20000,
+    env: { ...process.env, [profile.configDirEnv]: configRoot },
+  });
+  const probe = {
+    ok: result.status === 0 && Boolean((result.stdout || "").trim()),
+    status: result.status === undefined ? null : result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim(),
+    spawnError: result.error ? result.error.message : "",
+  };
+  if (options.debug) {
+    log(`[qoder] probe ${executable} --list-models (${profile.configDirEnv}=${configRoot}) -> status=${probe.status} stdout=${probe.stdout || "<empty>"} stderr=${probe.stderr || "<empty>"}`);
+  }
+  return probe;
+}
+
+function inspectQoderHealth(profile, executable, configRoot, options = {}) {
+  const probes = [];
+  const machineIds = [];
+  const verdict = (state, reason) => ({ state, reason, configRoot, probes, machineIds });
+
+  if (!configRootWritable(configRoot)) {
+    return verdict("store_unusable", `the configuration root is not writable: ${configRoot}`);
+  }
+
+  const first = readMachineId(configRoot);
+  machineIds.push(first);
+  if (options.debug) log(`[qoder] ${MACHINE_ID_REL_PATH} #1 -> ${describeMachineId(first)}`);
+  if (first.unreadable) {
+    return verdict("store_unusable", `${MACHINE_ID_REL_PATH} exists but cannot be read (${first.unreadable})`);
+  }
+
+  const probeOne = probeQoderAuth(profile, executable, configRoot, options);
+  probes.push(probeOne);
+  if (isCliUnusable(probeOne)) return verdict("cli_unusable", cliUnusableReason(probeOne));
+
+  const second = readMachineId(configRoot);
+  machineIds.push(second);
+  if (options.debug) log(`[qoder] ${MACHINE_ID_REL_PATH} #2 -> ${describeMachineId(second)}`);
+  const driftOne = machineIdDrift(first, second);
+  if (driftOne) return verdict("store_unusable", driftOne);
+
+  if (!probeOne.ok) {
+    return verdict("needs_login", probeOne.stderr || `the authentication probe exited with status ${probeOne.status}`);
+  }
+
+  // A single probe always succeeds right after login, so only a second one can
+  // expose a credential store that is usable exactly once.
+  const probeTwo = probeQoderAuth(profile, executable, configRoot, options);
+  probes.push(probeTwo);
+  if (isCliUnusable(probeTwo)) return verdict("cli_unusable", cliUnusableReason(probeTwo));
+
+  const third = readMachineId(configRoot);
+  machineIds.push(third);
+  if (options.debug) log(`[qoder] ${MACHINE_ID_REL_PATH} #3 -> ${describeMachineId(third)}`);
+  const driftTwo = machineIdDrift(second, third);
+  if (driftTwo) return verdict("store_unusable", driftTwo);
+
+  if (!probeTwo.ok) {
+    return verdict("needs_login", probeTwo.stderr || `the second authentication probe exited with status ${probeTwo.status}`);
+  }
+  return verdict("ready", "");
+}
+
+function describeMachineId(read) {
+  if (read.unreadable) return `unreadable (${read.unreadable})`;
+  return read.present ? read.value : "absent";
+}
+
+// The managed root existing and being healthy is itself the record that a
+// previous run already migrated; no extra state file is involved.
+function selectQoderConfigRoot(profile, executable, options = {}) {
+  const paths = qoderPaths(profile);
+  const explicit = process.env[profile.configDirEnv];
+  if (explicit) return { root: resolveUserPath(explicit), source: "explicit" };
+  if (fs.existsSync(paths.managedConfigRoot)) {
+    const verdict = inspectQoderHealth(profile, executable, paths.managedConfigRoot, options);
+    if (verdict.state === "ready") return { root: paths.managedConfigRoot, source: "managed", verdict };
+  }
+  return { root: paths.defaultConfigRoot, source: "default" };
+}
+
+// Explicit roots are never overwritten; managed and default roots are exported
+// so the daemon and every task it spawns inherit the same root.
+function applyQoderConfigRoot(profile, source, configRoot) {
+  if (source === "explicit") return;
+  process.env[profile.configDirEnv] = configRoot;
+}
+
+function qoderNodeVersion() {
+  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_NODE_VERSION) {
+    return process.env.AUTOWONDER_TEST_NODE_VERSION;
+  }
+  return process.versions.node;
+}
+
+const QODER_AUTH_RECHECK_TIMEOUT_MS = 3 * 60 * 1000;
+
+function qoderAuthRecheckTimeoutMs() {
+  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_TIMEOUT_MS) {
+    return Number.parseInt(process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_TIMEOUT_MS, 10) || 1;
+  }
+  return QODER_AUTH_RECHECK_TIMEOUT_MS;
+}
+
+function qoderAuthRecheckDelayMs() {
+  if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_DELAY_MS) {
+    return Number.parseInt(process.env.AUTOWONDER_TEST_QODER_AUTH_RECHECK_DELAY_MS, 10) || 0;
+  }
+  return 3000;
+}
+
+function qoderLoginCommand(executable) {
+  const quoted = `'${executable.replace(/'/g, "''")}'`;
+  return IS_WIN32 ? `& ${quoted} login` : `${quoted} login`;
+}
+
+const QODER_STATE_LABELS = {
+  ready: "credentials are usable",
+  needs_login: "an interactive login is required",
+  store_unusable: "the credential store cannot be used",
+  cli_unusable: "the CLI itself cannot run",
+};
+
+function credentialMtimeMs(credentialPath) {
+  try { return fs.statSync(credentialPath).mtimeMs; } catch { return null; }
+}
+
+// A human needs time to finish the browser flow, so keep waiting while the
+// credential file is still unwritten. Once it lands and is still unusable,
+// waiting longer cannot help.
+async function waitForQoderLogin(profile, executable, configRoot, options = {}, baselineMtime) {
+  const startedAt = Date.now();
+  const deadline = startedAt + qoderAuthRecheckTimeoutMs();
+  const credentialPath = path.join(configRoot, CREDENTIAL_REL_PATH);
+  if (baselineMtime === undefined) baselineMtime = credentialMtimeMs(credentialPath);
+  while (true) {
+    const verdict = inspectQoderHealth(profile, executable, configRoot, options);
+    if (verdict.state !== "needs_login") return verdict;
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) return verdict;
+    const currentMtime = credentialMtimeMs(credentialPath);
+    const written = currentMtime !== null && currentMtime !== baselineMtime;
+    const qualifier = written ? "credentials written, still not usable" : "credentials not written yet";
+    const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
+    log(`Waiting for Qoder login to finish... (${elapsedSeconds}s elapsed, ${qualifier})`);
+    await new Promise((resolve) => setTimeout(resolve, Math.min(qoderAuthRecheckDelayMs(), remainingMs)));
+  }
+}
+
+function latestQoderRunLog(configRoot) {
+  const runsDir = path.join(configRoot, "logs", "runs");
+  try {
+    const entries = fs.readdirSync(runsDir).sort();
+    if (!entries.length) return `${runsDir} (no runs recorded)`;
+    return path.join(runsDir, entries[entries.length - 1]);
+  } catch { return `${runsDir} (unavailable)`; }
+}
+
+function reportQoderDiagnostics(profile, info) {
+  const { executable, version, configRoot, rootSource, verdict, identityChanged, previous } = info;
+  error(`--- ${profile.displayName} bootstrap diagnostics ---`);
+  error(`executable      : ${executable}`);
+  error(`version         : ${version}`);
+  error(`config root     : ${configRoot} (${rootSource})`);
+  error(`verdict         : ${verdict.state} - ${verdict.reason || "no further detail"}`);
+  if (identityChanged && previous) {
+    error(`previous binary : ${previous.resolvedPath} @ ${previous.version} (config root ${previous.configRoot})`);
+  }
+  (verdict.machineIds || []).forEach((read, index) => {
+    error(`machine_id #${index + 1}   : ${describeMachineId(read)}`);
+  });
+  (verdict.probes || []).slice(-2).forEach((probe, index) => {
+    error(`probe ${index + 1} status : ${probe.status}${probe.spawnError ? ` (${probe.spawnError})` : ""}`);
+    error(`probe ${index + 1} stdout : ${probe.stdout || "<empty>"}`);
+    error(`probe ${index + 1} stderr : ${probe.stderr || "<empty>"}`);
+  });
+  error(`cli run logs    : ${latestQoderRunLog(configRoot)}`);
+  error("Next step:");
+  error(`  ${profile.configDirEnv}=${configRoot} ${qoderLoginCommand(executable)}`);
+}
+
+function runQoderLogin(profile, executable, configRoot) {
+  const login = spawnQoderSync(executable, ["login"], {
+    stdio: "inherit",
+    env: { ...process.env, [profile.configDirEnv]: configRoot },
+  });
+  if (login.status === 0) return true;
+  const detail = login.error?.message || `exit status ${login.status}`;
+  error(`Qoder login command failed: ${detail}`);
+  error(`Run ${qoderLoginCommand(executable)} and retry.`);
+  return false;
+}
+
+// The credential mtime baseline must be sampled before login runs: the command
+// can write the file before it exits, and a baseline taken afterwards would
+// report that fresh write as "not written yet".
+async function loginThenWait(profile, executable, configRoot, options) {
+  const baselineMtime = credentialMtimeMs(path.join(configRoot, CREDENTIAL_REL_PATH));
+  if (!runQoderLogin(profile, executable, configRoot)) return null;
+  return waitForQoderLogin(profile, executable, configRoot, options, baselineMtime);
+}
+
+function finishQoderReady(profile, provider, executable, version, configRoot, rootSource) {
+  writeQoderState(profile, provider, { resolvedPath: executable, version, configRoot });
+  process.env[profile.envVar] = executable;
+  const executableDir = path.dirname(executable);
+  const pathEntries = (process.env.PATH || "").split(path.delimiter);
+  if (!pathEntries.includes(executableDir)) {
+    process.env.PATH = `${executableDir}${path.delimiter}${process.env.PATH || ""}`;
+  }
+  log(`${profile.displayName} is installed and authenticated (${executable}, config root ${configRoot} [${rootSource}]).`);
+  return true;
+}
+
+async function ensureQoderReady(provider, options = {}) {
+  if (process.env.AUTOWONDER_SKIP_QODER_BOOTSTRAP === "1") return true;
+  const profile = QODER_FAMILY_PROFILES[provider];
+  const inspectOptions = { debug: Boolean(options.debug) };
+
+  const nodeVersion = qoderNodeVersion();
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
+  if (!Number.isInteger(nodeMajor) || nodeMajor < 20) {
+    error(`${profile.displayName} requires Node.js 20 or newer; current version is ${nodeVersion}. Upgrade Node.js and retry.`);
+    return false;
+  }
+
+  // Never anchored to a version: the customer's own binary always wins, and the
+  // managed copy only serves machines that have none.
+  let executable = findQoderExecutable(provider);
+  // A fresh install spends the single npm budget, so the rungs below must not
+  // reinstall the package that just landed.
+  let refreshed = false;
+  if (!executable) {
+    executable = installQoderCLI(provider);
+    refreshed = true;
+  }
+  if (!executable) return false;
+  let version = qoderBinaryVersion(executable);
+
+  const paths = qoderPaths(profile);
+  const selection = selectQoderConfigRoot(profile, executable, inspectOptions);
+  let configRoot = selection.root;
+  let rootSource = selection.source;
+  applyQoderConfigRoot(profile, rootSource, configRoot);
+
+  const previous = readQoderState(profile)[provider] || null;
+  const identityChanged = Boolean(previous
+    && (previous.resolvedPath !== executable || previous.version !== version));
+
+  // A — already healthy.
+  let verdict = selection.verdict || inspectQoderHealth(profile, executable, configRoot, inspectOptions);
+  const diagnostics = () => reportQoderDiagnostics(profile, {
+    executable, version, configRoot, rootSource, verdict, identityChanged, previous,
+  });
+
+  if (verdict.state === "ready") {
+    return finishQoderReady(profile, provider, executable, version, configRoot, rootSource);
+  }
+
+  if (process.env.AUTOWONDER_QODER_NO_SELF_HEAL === "1") {
+    error(`${profile.displayName} is not ready (${QODER_STATE_LABELS[verdict.state]}) and self-healing is disabled by AUTOWONDER_QODER_NO_SELF_HEAL=1.`);
+    diagnostics();
+    return false;
+  }
+
+  const managedCopy = executable.startsWith(`${paths.managedDir}${path.sep}`);
+
+  // B — a managed copy that cannot run at all gets refreshed once.
+  if (verdict.state === "cli_unusable" && managedCopy && !refreshed) {
+    log(`${profile.displayName} cannot run (${verdict.reason}). Refreshing the managed installation...`);
+    refreshed = true;
+    const reinstalled = installQoderCLI(provider);
+    if (reinstalled) {
+      executable = reinstalled;
+      version = qoderBinaryVersion(executable);
+      verdict = inspectQoderHealth(profile, executable, configRoot, inspectOptions);
+      if (verdict.state === "ready") {
+        return finishQoderReady(profile, provider, executable, version, configRoot, rootSource);
+      }
+    }
+  }
+
+  // C — one interactive login in the selected root. Most customers end here.
+  if (verdict.state === "needs_login") {
+    if (identityChanged) {
+      log(`${profile.displayName} executable changed (was ${previous.resolvedPath} @ ${previous.version}, now ${executable} @ ${version}); one login is needed to rebuild credentials.`);
+    }
+    log(`${profile.displayName} login is required (${verdict.reason || "no usable credentials"}). Opening browser login...`);
+    const settled = await loginThenWait(profile, executable, configRoot, inspectOptions);
+    if (settled) {
+      verdict = settled;
+      if (verdict.state === "ready") {
+        return finishQoderReady(profile, provider, executable, version, configRoot, rootSource);
+      }
+    } else {
+      verdict = { state: "needs_login", reason: "the login command failed", configRoot, probes: [], machineIds: [] };
+    }
+  }
+
+  // D — migrate to an isolated managed configuration root and log in there.
+  if (verdict.state !== "cli_unusable") {
+    if (rootSource === "explicit") {
+      error(`${profile.displayName} cannot use the configuration root set through ${profile.configDirEnv} (${configRoot}): ${verdict.reason}`);
+      error(`Point ${profile.configDirEnv} at a usable directory, or unset it so autowonder can manage one, then retry.`);
+      diagnostics();
+      return false;
+    }
+    if (managedCopy && !refreshed) {
+      log(`Refreshing the managed ${profile.displayName} installation before retrying with an isolated configuration root...`);
+      refreshed = true;
+      const reinstalled = installQoderCLI(provider);
+      if (reinstalled) {
+        executable = reinstalled;
+        version = qoderBinaryVersion(executable);
+      }
+    }
+    log(`${profile.displayName} credentials under ${configRoot} are not usable (${verdict.reason}).`);
+    configRoot = paths.managedConfigRoot;
+    rootSource = "managed";
+    log(`Switching to an isolated configuration root: ${configRoot}`);
+    log(`Your own ${profile.displayName} configuration was not modified.`);
+    ensureDir(configRoot);
+    applyQoderConfigRoot(profile, rootSource, configRoot);
+    const settled = await loginThenWait(profile, executable, configRoot, inspectOptions);
+    if (settled) {
+      verdict = settled;
+      if (verdict.state === "ready") {
+        return finishQoderReady(profile, provider, executable, version, configRoot, rootSource);
+      }
+    }
+  }
+
+  // E — stop guessing and hand the operator the facts.
+  error(`${profile.displayName} could not be brought to a usable state (${QODER_STATE_LABELS[verdict.state]}). Run ${qoderLoginCommand(executable)} and retry.`);
+  diagnostics();
+  return false;
+}
+
+module.exports = {
+  QODER_FAMILY_PROFILES,
+  ensureQoderReady,
+  findQoderExecutable,
+  inspectQoderHealth,
+  isQoderFamilyProvider,
+  qoderBinaryVersion,
+  qoderPaths,
+  readQoderState,
+  reportQoderDiagnostics,
+  selectQoderConfigRoot,
+  spawnQoderSync,
+  waitForQoderLogin,
+  writeQoderState,
+};

package/bin/shared.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function log(msg) {
+  console.log(`\x1b[36m[autowonder]\x1b[0m ${msg}`);
+}
+
+function error(msg) {
+  console.error(`\x1b[31m[autowonder]\x1b[0m ${msg}`);
+}
+
+function resolveUserPath(value) {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.resolve(os.homedir(), value.slice(2));
+  }
+  return path.resolve(value);
+}
+
+function findOnPath(name) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const found = spawnSync(finder, [name], { encoding: "utf8", timeout: 3000 });
+  if (found.status !== 0) return "";
+  return (found.stdout || "").split(/\r?\n/).map((value) => value.trim()).find(Boolean) || "";
+}
+
+module.exports = { ensureDir, error, findOnPath, log, resolveUserPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autowonder",
-  "version": "0.2.136",
+  "version": "0.2.138",
   "description": "AutoWonder local runtime — execute AI agent dispatch packages on your machine",
   "bin": {
     "autowonder": "bin/cli.js"