autowonder 0.2.162 → 0.2.164

package/README.md

@@ -6,13 +6,26 @@ AutoWonder 本地 agent runtime。安装后启动 daemon，持续轮询本地 as
 
 ```bash
 # Qoder CLI（模型使用 provider model ID；Context Window 使用固定档位）
-npx -y autowonder@0.2.162 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.164 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.162 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
+npx -y autowonder@0.2.164 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
 ```
 
-`connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。客户端只支持通过 Qoder 系列 CLI 启动（`qoder` 对应 `qodercli`，`qodercn` 对应 `qodercn`），其他 `--provider` 取值会在启动 daemon 前直接报错拦截并提示 `Unsupported provider`。选择 Qoder 时需要 Node.js 20+；runtime 会在缺少 `qodercli` 时自动通过 npm 安装，并在尚未登录时打开 Qoder 浏览器登录。runtime 会继承当前用户的 HOME、环境变量和 CLI 登录状态。
+`connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。客户端只支持通过 Qoder 系列 CLI 启动（`qoder` 对应 `qodercli`，`qodercn` 对应 `qodercn`），其他 `--provider` 取值会在启动 daemon 前直接报错拦截并提示 `Unsupported provider`。选择 Qoder CLI 或 Qoder CLI CN 时需要 Node.js 20+；runtime 会在缺少对应 CLI 时自动通过 npm 安装，并在尚未登录时打开浏览器登录。runtime 会继承当前用户的 HOME、环境变量和 CLI 登录状态。
+
+### Qoder 系列 Access Token 认证
+
+以下认证规则同时适用于 `connect --provider qoder` 和 `connect --provider qodercn`。runtime 启动时按以下顺序选择认证方式：
+
+1. 对应 provider 的命令行参数：`qoder` 使用 `--QODER_PERSONAL_ACCESS_TOKEN`，`qodercn` 使用 `--QODERCN_PERSONAL_ACCESS_TOKEN`；两者都支持 `--KEY=<token>` 和 `--KEY <token>` 形式。
+2. 当前进程中对应的原生环境变量：`QODER_PERSONAL_ACCESS_TOKEN` 或 `QODERCN_PERSONAL_ACCESS_TOKEN`。
+3. 执行器绑定的数字员工当前在线版本中对应的同名 Platform 环境变量。
+4. 均未配置时，沿用现有的浏览器 OAuth 登录。
+
+runtime 启动时始终只拉取一次 Platform 环境变量快照，即使已有本地参数或环境变量也不会跳过；拉取或鉴权失败会直接导致启动失败，不会静默降级。命令行参数或当前进程环境变量提供的 token 会按启动需要保留给 daemon；Platform 预取的 token 仅临时用于启动认证，不会保留在 daemon 环境中。实际任务或 conversation 派发时，仍沿用现有机制注入并覆盖最新的 Platform 环境变量快照。
+
+出于安全考虑，命令行 token 可能出现在 shell 历史和操作系统进程列表中，建议优先使用环境变量或 Platform 绑定。
 
 `connect` 和 `start` 都要求 Qoder CLI / Qoder CLI CN 版本至少为 `1.1.50`。检测到旧版或无法解析的版本时，runtime 会对当前优先选中的用户 CLI 执行内置 `update`，原位升级到最新版并再次强校验；升级失败或升级后仍不满足最低版本时拒绝启动 daemon。所有 Qoder 系列子进程（普通任务、conversation、warm 会话、恢复回退、命令与模型探测）都会强制注入固定的 `QODER_INTEGRATION_ID`，调用方环境不能覆盖该流量归因标识。
 
@@ -76,8 +89,6 @@ daemon 建立连接时和每次心跳定时检查时发出的 `HEARTBEAT` 帧都
 
 标准安装还支持服务端把整批执行机升级到指定的**已发布版本**（不再依赖各台机器安装时选定的版本），能力位为 `EXECUTOR_UPDATE_V1`。服务端下发 `EXECUTOR_UPGRADE`（带 `executorId`、`requestId`、ISO UTC `issuedAt` 与 `targetVersion`），本机只接受 `executorId` 与自身一致、`requestId` 非空且不超过 80 字符、`issuedAt` 在前后 1 分钟以内、且 `targetVersion` 为三段纯数字正式版的请求。升级按 `accepted` → `downloading` → `draining` → `applying` → `success` 逐阶段回执 `EXECUTOR_UPGRADE_RESULT`（含 `requestId`、`phase` 与该进程启动时的 `currentVersion`；新版本以下一个进程的首次心跳为准），失败则以 `failed` 帧带上错误原因——目标版本不受支持、请求过期、本机构建不支持远端升级等都会显式回执而不是静默丢弃。registry 按请求的版本号解析元数据并要求返回值与请求版本严格一致；请求版本低于当前版本时拒绝执行（服务端升级永不回滚整批执行机），已缓存但版本不符的候选不会被采用。`requestId` 会跨 re-exec 传递，服务端重放的同一请求不会触发第二次升级；同一 `requestId` 同时只允许一次尝试在飞，失败后可重试。升级复用既有的接单闸门、完整性校验、候选 self-check、安装事务与回滚。对执行机用户无新增参数或环境变量。
 
-同一批 `HEARTBEAT` 帧还会声明派单清单能力位 `dispatch_inventory_v1` 并带上权威派单清单：`ownedDispatchIds` 是本机仍持有的全部非终态派单（含启动恢复候选，完整时上限 1000），`runningDispatchIds` 是其中正在占用执行槽位的子集（上限 50，且每个 running 必须同时 owned），`dispatchInventoryReady` 只有在启动恢复完成后才为 `true`。清单不完整时不会把 owned 集合当成完整视图下发，而是回执 `dispatchInventoryError`（`OWNED_DISPATCH_LIMIT_EXCEEDED`）并保持 `dispatchInventoryReady=false`，只发布完整的 running 子集，由服务端按失败关闭处理；清单快照只绑定当前 WebSocket 会话，旧连接不能覆盖接替它的 runtime。普通任务与启动恢复任务的暂停共用同一个 pause broker，暂停时发布带持久化 checkpoint 回执的 `TASK_PAUSED` 帧。该协议没有调度降级路径：服务端会拒绝并关闭未声明 `dispatch_inventory_v1` 的 runtime 连接，因此升级本客户端要先于部署配套服务端。对执行机用户无新增参数或环境变量。
-
 ## 任务环境变量快照
 
 平台可在派单（`dispatch` 帧）与会话回合（`CONVERSATION_TURN` 帧）里附带任务级环境变量快照（`environmentVariables`），经已认证的执行器 WebSocket 下发；runtime 会把快照叠加到 provider 子进程环境之上，任务按平台下发的取值运行。同名变量按不区分大小写的方式覆盖，保证同一任务在 Linux/macOS 与 Windows 上取值一致。
@@ -121,7 +132,7 @@ mv "$queue/.assignment.tmp" "$queue/assignment.json"
 也可以直接提交到本地 API：
 
 ```bash
-npx -y autowonder@0.2.162 dispatch ./assignment.json
+npx -y autowonder@0.2.164 dispatch ./assignment.json
 ```
 
 ## 上传工单附件
@@ -129,7 +140,7 @@ npx -y autowonder@0.2.162 dispatch ./assignment.json
 把本地需求/设计文档直接上传到工单，避免在会话里传递大文件：
 
 ```bash
-npx -y autowonder@0.2.162 workitem upload --server-url <autowonder-server-url> --workitem-id <id> --file <filepath-1> --file <filepath-2> --json
+npx -y autowonder@0.2.164 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）。
@@ -139,7 +150,7 @@ npx -y autowonder@0.2.162 workitem upload --server-url <autowonder-server-url> -
 把工单上已有的需求/设计文档下载到本地目录，再用本地文件工具阅读，避免把大文件或二进制附件搬进会话上下文：
 
 ```bash
-npx -y autowonder@0.2.162 workitem download --server-url <autowonder-server-url> --workitem-id <id> --file <name-or-id> --output-dir <dir> --json
+npx -y autowonder@0.2.164 workitem download --server-url <autowonder-server-url> --workitem-id <id> --file <name-or-id> --output-dir <dir> --json
 ```
 
 下载令牌通过 MCP 工具 `autowonder.workitem_cli_download_token` 签发（与上传令牌相互独立），经 `--token` 或 `AUTOWONDER_DOWNLOAD_TOKEN` 环境变量传入。`--file` 可重复指定文档名或 artifact id，省略则下载该工单的全部附件；`--output-dir` 默认为当前目录；`--json` 输出机器可读结果，含每个文件的 `id`、`name`、`path`、`size`。退出码约定与 `workitem upload` 相同（401→3、403→4、404→5、409→6、413→7、其他 4xx→8、网络/重定向→9）。
@@ -149,7 +160,7 @@ npx -y autowonder@0.2.162 workitem download --server-url <autowonder-server-url>
 把需求/设计文档上传到 7x24 定时任务，用法与工单附件一致（同一套上传令牌与预检规则）：
 
 ```bash
-npx -y autowonder@0.2.162 scheduled-task upload --server-url <autowonder-server-url> --scheduled-task-id <id> --file <filepath-1> --file <filepath-2> --json
+npx -y autowonder@0.2.164 scheduled-task upload --server-url <autowonder-server-url> --scheduled-task-id <id> --file <filepath-1> --file <filepath-2> --json
 ```
 
 上传令牌同样通过 `autowonder.workitem_cli_upload_token` 签发（令牌为用户级，对当前可修改的任意定时任务生效），经 `--token` 或 `AUTOWONDER_UPLOAD_TOKEN` 传入；退出码约定与 `workitem upload` 相同。
@@ -157,8 +168,8 @@ npx -y autowonder@0.2.162 scheduled-task upload --server-url <autowonder-server-
 ## 管理 daemon
 
 ```bash
-npx -y autowonder@0.2.162 status
-npx -y autowonder@0.2.162 stop
+npx -y autowonder@0.2.164 status
+npx -y autowonder@0.2.164 stop
 ```
 
 默认 API 是 `http://127.0.0.1:34989`，日志位于 `~/.autowonder/daemon.log`。npm 包不包含任何 agent、MCP 或服务端凭证。
@@ -166,7 +177,7 @@ npx -y autowonder@0.2.162 stop
 ## 调试
 
 ```bash
-npx -y autowonder@0.2.162 connect ... --debug
+npx -y autowonder@0.2.164 connect ... --debug
 ```
 
 `--debug` 会让 CLI 以 `AUTOWONDER_DEBUG=1` 启动 daemon，把完整的 daemon 与 agent 活动（runtime 事件流、provider 事件解码、重试退避与会话门等待、空闲时的阻塞点）同时输出到控制台和会话调试日志。调试日志不做脱敏，仅用于本机排障；不传 `--debug` 时该环境变量不会注入。

package/bin/cli.js

@@ -15,6 +15,7 @@ const {
   findQoderExecutable,
   isQoderFamilyProvider,
 } = require("./qoder-bootstrap");
+const { fetchExecutorEnvironment } = require("./executor-environment");
 
 const VERSION = require("../package.json").version;
 const AUTOWONDER_HOME = path.join(os.homedir(), ".autowonder");
@@ -329,13 +330,32 @@ function buildFromSource() {
 // ─── Commands ────────────────────────────────────────────────────────
 
 async function cmdConnect(args) {
-  const flags = parseFlags(args, ["ws-url", "token", "executor-id", "provider", "name", "max-tasks", "model", "reasoning-effort", "context-window", "memory-mode", "settings", "workspace-root", "token-aware-enable"]);
+  const normalizedArgs = args.flatMap((arg) => {
+    for (const key of ["QODER_PERSONAL_ACCESS_TOKEN", "QODERCN_PERSONAL_ACCESS_TOKEN"]) {
+      const prefix = `--${key}=`;
+      if (arg.startsWith(prefix)) return [`--${key}`, arg.slice(prefix.length)];
+    }
+    return [arg];
+  });
+  const flags = parseFlags(normalizedArgs, ["ws-url", "token", "executor-id", "provider", "name", "max-tasks", "model", "reasoning-effort", "context-window", "memory-mode", "settings", "workspace-root", "token-aware-enable", "QODER_PERSONAL_ACCESS_TOKEN", "QODERCN_PERSONAL_ACCESS_TOKEN"]);
+
+  const requestedAccessTokenEnv = flags.provider === "qodercn"
+    ? "QODERCN_PERSONAL_ACCESS_TOKEN"
+    : "QODER_PERSONAL_ACCESS_TOKEN";
+  const hasRequestedAccessToken = Object.prototype.hasOwnProperty.call(flags, requestedAccessTokenEnv);
+
+  if (
+    hasRequestedAccessToken &&
+    (flags[requestedAccessTokenEnv] === "true" || !flags[requestedAccessTokenEnv].trim())
+  ) {
+    error(`--${requestedAccessTokenEnv} requires a non-empty value`);
+    process.exit(1);
+  }
 
   if (!flags["ws-url"] || !flags.token || !flags["executor-id"]) {
     error("Usage: autowonder connect --ws-url <url> --token <token> --executor-id <id> [--provider qoder|qodercn] [--workspace-root <path>]");
     process.exit(1);
   }
-
   const requestedProvider = flags.provider;
   if (requestedProvider) assertSupportedProvider(requestedProvider);
   if (isQoderFamilyProvider(requestedProvider) && !validateQoderOptions(flags)) process.exit(1);
@@ -347,7 +367,55 @@ async function cmdConnect(args) {
     process.exit(1);
   }
   assertSupportedProvider(provider);
-  if (isQoderFamilyProvider(provider) && !(await ensureQoderReady(provider, { debug: Boolean(flags.debug) }))) process.exit(1);
+  let selectedAccessTokenEnv = "";
+  let hasExplicitAccessToken = false;
+  let inheritedAccessToken;
+  if (isQoderFamilyProvider(provider)) {
+    selectedAccessTokenEnv = provider === "qodercn"
+      ? "QODERCN_PERSONAL_ACCESS_TOKEN"
+      : "QODER_PERSONAL_ACCESS_TOKEN";
+    hasExplicitAccessToken = Object.prototype.hasOwnProperty.call(flags, selectedAccessTokenEnv);
+    const inheritedAccessTokenPresent = Object.prototype.hasOwnProperty.call(process.env, selectedAccessTokenEnv);
+    inheritedAccessToken = process.env[selectedAccessTokenEnv];
+    const nodeVersion = process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_NODE_VERSION
+      ? process.env.AUTOWONDER_TEST_NODE_VERSION
+      : process.versions.node;
+    const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
+    if (!Number.isInteger(nodeMajor) || nodeMajor < 20) {
+      const displayName = provider === "qodercn" ? "Qoder CLI CN" : "Qoder CLI";
+      error(`${displayName} requires Node.js 20 or newer; current version is ${nodeVersion}. Upgrade Node.js and retry.`);
+      process.exit(1);
+    }
+
+    const fetchOptions = {
+      wsUrl: flags["ws-url"],
+      executorId: flags["executor-id"],
+      executorToken: flags.token,
+    };
+    if (process.env.NODE_ENV === "test" && process.env.AUTOWONDER_TEST_EXECUTOR_ENVIRONMENT_TIMEOUT_MS) {
+      fetchOptions.timeoutMs = Number.parseInt(process.env.AUTOWONDER_TEST_EXECUTOR_ENVIRONMENT_TIMEOUT_MS, 10) || 1;
+    }
+    const platformEnvironment = await fetchExecutorEnvironment(fetchOptions);
+    const candidates = [
+      hasExplicitAccessToken ? flags[selectedAccessTokenEnv] : "",
+      inheritedAccessToken,
+      platformEnvironment[selectedAccessTokenEnv],
+    ];
+    const selectedQoderToken = candidates.find((value) => typeof value === "string" && value.trim());
+    const ignoredBlankInheritedToken = inheritedAccessTokenPresent && !selectedQoderToken;
+    if (ignoredBlankInheritedToken) delete process.env[selectedAccessTokenEnv];
+    let qoderReady = false;
+    try {
+      qoderReady = await ensureQoderReady(provider, {
+        debug: Boolean(flags.debug),
+        authenticationMode: selectedQoderToken ? "access_token" : "oauth",
+        accessToken: selectedQoderToken || null,
+      });
+    } finally {
+      if (ignoredBlankInheritedToken) process.env[selectedAccessTokenEnv] = inheritedAccessToken;
+    }
+    if (!qoderReady) 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
@@ -429,6 +497,12 @@ async function cmdConnect(args) {
   if (flags["context-window"]) env.AUTOWONDER_CONTEXT_WINDOW = flags["context-window"];
   if (config.claudeSettingsPath) env.AUTOWONDER_CLAUDE_SETTINGS = config.claudeSettingsPath;
   if (flags.debug) env.AUTOWONDER_DEBUG = "1";
+  if (isQoderFamilyProvider(provider) && hasExplicitAccessToken) {
+    env[selectedAccessTokenEnv] = flags[selectedAccessTokenEnv];
+  } else if (isQoderFamilyProvider(provider)
+    && !(typeof inheritedAccessToken === "string" && inheritedAccessToken.trim())) {
+    delete env[selectedAccessTokenEnv];
+  }
 
   // --token-aware-enable: start token-proxy as a sidecar (bypass, non-blocking)
   let tokenProxyChild = null;

package/bin/executor-environment.js

@@ -0,0 +1,86 @@
+"use strict";
+
+class ExecutorEnvironmentError extends Error {}
+
+function executorEnvironmentURL(wsUrl, executorId) {
+  let url;
+  try {
+    url = new URL(wsUrl);
+  } catch {
+    throw new Error("Invalid executor WebSocket URL");
+  }
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  } else {
+    throw new Error(`Unsupported executor WebSocket protocol: ${url.protocol}`);
+  }
+
+  url.pathname = `/api/daemon/executors/${encodeURIComponent(executorId)}/environment-variables`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+async function fetchExecutorEnvironment({ wsUrl, executorId, executorToken, timeoutMs = 5000 }) {
+  const url = executorEnvironmentURL(wsUrl, executorId);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${executorToken}`,
+        Accept: "application/json",
+      },
+      cache: "no-store",
+      redirect: "error",
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      if (response.body) {
+        try {
+          await response.body.cancel();
+        } catch {}
+      }
+      throw new ExecutorEnvironmentError(`Executor environment request failed with status ${response.status}`);
+    }
+
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      if (controller.signal.aborted) {
+        throw new ExecutorEnvironmentError(`Executor environment request timed out after ${timeoutMs}ms`);
+      }
+      throw new ExecutorEnvironmentError("Invalid executor environment response");
+    }
+
+    if (
+      body === null ||
+      typeof body !== "object" ||
+      Array.isArray(body) ||
+      body.environmentVariables === null ||
+      typeof body.environmentVariables !== "object" ||
+      Array.isArray(body.environmentVariables) ||
+      Object.values(body.environmentVariables).some((value) => typeof value !== "string")
+    ) {
+      throw new ExecutorEnvironmentError("Invalid executor environment response");
+    }
+
+    return { ...body.environmentVariables };
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new Error(`Executor environment request timed out after ${timeoutMs}ms`);
+    }
+    if (error instanceof ExecutorEnvironmentError) throw error;
+    throw new Error("Failed to fetch executor environment");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = { executorEnvironmentURL, fetchExecutorEnvironment };

package/bin/qoder-bootstrap.js

@@ -46,6 +46,7 @@ const QODER_FAMILY_PROFILES = {
     managedDirName: "qoder-cli",
     managedConfigRootName: "qoder-home",
     configDirEnv: "QODER_CONFIG_DIR",
+    accessTokenEnv: "QODER_PERSONAL_ACCESS_TOKEN",
     defaultConfigRootName: ".qoder",
     managedBinName: "qodercli",
     windowsShimName: "qodercli.cmd",
@@ -63,6 +64,7 @@ const QODER_FAMILY_PROFILES = {
     managedDirName: "qoder-cn-cli",
     managedConfigRootName: "qoder-cn-home",
     configDirEnv: "QODERCN_CONFIG_DIR",
+    accessTokenEnv: "QODERCN_PERSONAL_ACCESS_TOKEN",
     defaultConfigRootName: ".qoder-cn",
     managedBinName: "qodercn",
     windowsShimName: "qodercn.cmd",
@@ -671,12 +673,24 @@ function cliUnusableReason(probe) {
 // 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 probeEnv = { ...process.env, [profile.configDirEnv]: configRoot };
+  const hasPrivateAccessToken = typeof options.accessToken === "string" && Boolean(options.accessToken.trim());
+  if (Object.prototype.hasOwnProperty.call(options, "accessToken")) {
+    if (hasPrivateAccessToken) {
+      probeEnv[profile.accessTokenEnv] = options.accessToken;
+    } else {
+      delete probeEnv[profile.accessTokenEnv];
+    }
+  }
   const result = spawnQoderSync(executable, ["--list-models"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
     timeout: 20000,
+    // Keep the trusted timeout runner in the probe path so timed-out Qoder
+    // descendants are reclaimed. This invocation is the only one whose child
+    // environment receives a private flag/platform token.
     treeTimeout: true,
-    env: { ...process.env, [profile.configDirEnv]: configRoot },
+    env: probeEnv,
   });
   const probe = {
     ok: result.status === 0 && Boolean((result.stdout || "").trim()),
@@ -739,6 +753,29 @@ function inspectQoderHealth(profile, executable, configRoot, options = {}) {
   return verdict("ready", "");
 }
 
+// Access-token authentication is independent of the OAuth credential store.
+// Keep probe output private because a failed CLI may echo the supplied token in
+// its diagnostics, and require two successes to establish stable readiness.
+function inspectQoderAccessToken(profile, executable, configRoot, options = {}) {
+  const probeOptions = { ...options, debug: false };
+  const probeOne = probeQoderAuth(profile, executable, configRoot, probeOptions);
+  if (isCliUnusable(probeOne)) {
+    return { state: "cli_unusable", reason: cliUnusableReason(probeOne) };
+  }
+  if (!probeOne.ok) {
+    return { state: "token_unusable", reason: "the access token authentication probe failed" };
+  }
+
+  const probeTwo = probeQoderAuth(profile, executable, configRoot, probeOptions);
+  if (isCliUnusable(probeTwo)) {
+    return { state: "cli_unusable", reason: cliUnusableReason(probeTwo) };
+  }
+  if (!probeTwo.ok) {
+    return { state: "token_unusable", reason: "the second access token authentication probe failed" };
+  }
+  return { state: "ready", reason: "" };
+}
+
 function describeMachineId(read) {
   if (read.unreadable) return `unreadable (${read.unreadable})`;
   return read.present ? read.value : "absent";
@@ -900,6 +937,9 @@ function finishQoderReady(profile, provider, executable, version, configRoot, ro
 async function ensureQoderReady(provider, options = {}) {
   const profile = QODER_FAMILY_PROFILES[provider];
   const inspectOptions = { debug: Boolean(options.debug) };
+  if (Object.prototype.hasOwnProperty.call(options, "accessToken")) {
+    inspectOptions.accessToken = options.accessToken;
+  }
 
   const nodeVersion = qoderNodeVersion();
   const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
@@ -926,11 +966,27 @@ async function ensureQoderReady(provider, options = {}) {
   let version = versionGate.version;
 
   const paths = qoderPaths(profile);
-  const selection = selectQoderConfigRoot(profile, executable, inspectOptions);
+  const explicitConfigRoot = process.env[profile.configDirEnv];
+  const selection = options.authenticationMode === "access_token"
+    ? (explicitConfigRoot
+      ? { root: resolveUserPath(explicitConfigRoot), source: "explicit" }
+      : fs.existsSync(paths.managedConfigRoot)
+        ? { root: paths.managedConfigRoot, source: "managed" }
+        : { root: paths.defaultConfigRoot, source: "default" })
+    : selectQoderConfigRoot(profile, executable, inspectOptions);
   let configRoot = selection.root;
   let rootSource = selection.source;
   applyQoderConfigRoot(profile, rootSource, configRoot);
 
+  if (options.authenticationMode === "access_token") {
+    const tokenVerdict = inspectQoderAccessToken(profile, executable, configRoot, inspectOptions);
+    if (tokenVerdict.state === "ready") {
+      return finishQoderReady(profile, provider, executable, version, configRoot, rootSource);
+    }
+    error(`${profile.displayName} access token authentication failed (${tokenVerdict.reason}).`);
+    return false;
+  }
+
   const previous = readQoderState(profile)[provider] || null;
   const identityChanged = Boolean(previous
     && (previous.resolvedPath !== executable || previous.version !== version));
@@ -1036,6 +1092,7 @@ module.exports = {
   ensureQoderReady,
   findInInstallDirs,
   findQoderExecutable,
+  inspectQoderAccessToken,
   inspectQoderHealth,
   installQoderCLIUnlocked,
   isQoderFamilyProvider,

package/package.json

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