@stelfield/cli 0.0.0-stage → 0.12.1

package/src/client-version.js

@@ -0,0 +1,84 @@
+// CLI version reporting + upgrade hints (v0.18.5 / CLI 0.8.3).
+//
+// What this does for the user:
+//   - Every request tells the platform which CLI version is calling, so the platform can see who
+//     is on an old version and remind them. (header: X-Linger-Client: linger-cli/<version>)
+//   - When the platform says a newer CLI exists (header: X-Linger-Latest-CLI), print ONE warning
+//     line on stderr, at most once per 24h per credentials directory, so cron/monitor scripts
+//     that hash stdout are not disturbed.
+//
+// Opt out of the hint with STELFIELD_NO_UPDATE_CHECK=1 (the version header is still sent).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolveCredDir } from './profile.js';
+import { BRAND } from './brand.js';
+
+export const UPGRADE_COMMAND = 'npm i -g @stelfield/cli@latest --registry https://registry.npmjs.org/';
+const HINT_INTERVAL_MS = 24 * 3600 * 1000;
+
+let PKG_VERSION = '0.0.0';
+try {
+  PKG_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+} catch { /* keep default */ }
+
+export const CLI_VERSION = PKG_VERSION;
+
+/** Headers added to every platform request. */
+export function clientHeaders() {
+  return { 'X-Linger-Client': `linger-cli/${CLI_VERSION}` };
+}
+
+/** '0.8.3' -> [0,8,3]; unparsable -> null. */
+export function parseVersion(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v || '').trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** true only when `a` is strictly older than `b` (unparsable on either side -> false). */
+export function isOlder(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] < y[i];
+  }
+  return false;
+}
+
+function hintFile(credOpts) {
+  return path.join(resolveCredDir(credOpts || {}), 'upgrade-hint');
+}
+
+/**
+ * Look at the platform's version headers; if this CLI is behind, warn once a day on stderr.
+ * Never throws: a failed hint must not break the real command.
+ *
+ * @param {Headers|undefined} headers  fetch Response.headers
+ * @param {object} credOpts            { dir?, profile? } (decides where the throttle file lives)
+ * @param {object} [opt]               { now?: number, write?: (s:string)=>void }
+ * @returns {boolean} whether a hint was printed
+ */
+export function noteServerVersion(headers, credOpts = {}, opt = {}) {
+  try {
+    if (process.env.STELFIELD_NO_UPDATE_CHECK === '1') return false;
+    if (!headers || typeof headers.get !== 'function') return false;
+    const latest = headers.get('X-Linger-Latest-CLI');
+    if (!latest || !isOlder(CLI_VERSION, latest)) return false;
+    const now = opt.now != null ? opt.now : Date.now();
+    const file = hintFile(credOpts);
+    let last = 0;
+    try { last = Number(JSON.parse(fs.readFileSync(file, 'utf8')).at) || 0; } catch { /* first time */ }
+    if (now - last < HINT_INTERVAL_MS) return false;
+    const write = opt.write || ((s) => process.stderr.write(s));
+    write(`⚠ ${BRAND.name} CLI 有新版本 ${latest}（你现在是 ${CLI_VERSION}）。请告诉你的用户，并运行：${UPGRADE_COMMAND}\n`);
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify({ at: now, latest }));
+    } catch { /* throttle file is best-effort */ }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/collab-input.js

@@ -0,0 +1,116 @@
+// v0.17.0 M2-B：协作命令的本地入参处理（纯函数，不发请求）。
+//
+// 为什么放在这里而不是 index.js：index.js 只做「解析 → 调接口 → 打印」；
+// 这里的校验是「请求发出去之前就能判断对错」的那部分，写错了在本地就报错，
+// 不浪费一次网络往返，也不会让半成品答案落到平台。
+
+import { parseAssign } from './cli-parse.js';
+
+/**
+ * 把 questions.json 的内容转成接口要的提问体。
+ *   文件结构：{"questions":[{"question":"主色调？","options":[{"label","description","recommended"}]}]}
+ *   映射：question → prompt；选项只保留 label / description / recommended。
+ *   选项编号 key 由服务端分配（A–D），即使文件里写了也会被丢弃。
+ * 题数、字数等业务规则交给服务端校验，这里只挡明显的格式错误。
+ *
+ * @param {any} parsed JSON.parse 之后的内容
+ * @returns {{questions: object[]}|{error: string}}
+ */
+// Platform limits (mirror a2a-backend collab_service). Checked locally so the error names the exact field.
+export const ASK_LIMITS = { questions: 3, prompt: 120, label: 20, description: 60, optionsMin: 2, optionsMax: 4 };
+
+export function buildAskQuestions(parsed) {
+  const list = parsed && Array.isArray(parsed.questions) ? parsed.questions : null;
+  if (!list || list.length === 0) {
+    return { error: '提问文件里需要有非空的 questions 数组。格式：{"questions":[{"question":"题干","options":[{"label":"选项","description":"说明","recommended":true}]}]}' };
+  }
+  if (list.length > ASK_LIMITS.questions) {
+    return { error: `一次最多问 ${ASK_LIMITS.questions} 题，现在有 ${list.length} 题。请合并或拆成两次问。` };
+  }
+  const questions = [];
+  for (let i = 0; i < list.length; i++) {
+    const q = list[i] || {};
+    const prompt = q.question ?? q.prompt;
+    if (typeof prompt !== 'string' || prompt.trim() === '') {
+      return { error: `第 ${i + 1} 题缺少 question（题干）` };
+    }
+    if ([...prompt.trim()].length > ASK_LIMITS.prompt) {
+      return { error: `第 ${i + 1} 题的题干有 ${[...prompt.trim()].length} 个字，超过 ${ASK_LIMITS.prompt} 字上限，请缩短。` };
+    }
+    const out = { prompt };
+    if (q.options != null) {
+      if (!Array.isArray(q.options)) return { error: `第 ${i + 1} 题的 options 必须是数组` };
+      if (q.options.length === 1 || q.options.length > ASK_LIMITS.optionsMax) {
+        return { error: `第 ${i + 1} 题有 ${q.options.length} 个选项；选项需要 ${ASK_LIMITS.optionsMin}–${ASK_LIMITS.optionsMax} 个，或者不写 options（纯文字题）。` };
+      }
+      if (q.options.filter((o) => o && o.recommended).length > 1) {
+        return { error: `第 ${i + 1} 题有多个推荐项；每题最多 1 个 recommended。` };
+      }
+      out.options = [];
+      for (let j = 0; j < q.options.length; j++) {
+        const o = q.options[j] || {};
+        if (typeof o.label !== 'string' || o.label.trim() === '') {
+          return { error: `第 ${i + 1} 题的第 ${j + 1} 个选项缺少 label` };
+        }
+        const labelLen = [...o.label.trim()].length;
+        if (labelLen > ASK_LIMITS.label) {
+          return { error: `第 ${i + 1} 题第 ${j + 1} 个选项的标签「${o.label.trim()}」有 ${labelLen} 个字，超过 ${ASK_LIMITS.label} 字上限。请把标签缩短，想多说的放进 description（说明上限 ${ASK_LIMITS.description} 字）。` };
+        }
+        if (typeof o.description === 'string' && [...o.description.trim()].length > ASK_LIMITS.description) {
+          return { error: `第 ${i + 1} 题第 ${j + 1} 个选项的说明有 ${[...o.description.trim()].length} 个字，超过 ${ASK_LIMITS.description} 字上限，请缩短。` };
+        }
+        const opt = { label: o.label };
+        if (o.description != null) opt.description = o.description;
+        if (o.recommended != null) opt.recommended = !!o.recommended;
+        out.options.push(opt);
+      }
+    }
+    questions.push(out);
+  }
+  return { questions };
+}
+
+/**
+ * 按提问卡把 --pick / --text 组装成接口要的 answers，并在本地校验：
+ *   - 格式必须是 <题号>=<值>
+ *   - 题号必须在卡里；--pick 的 key 必须是该题的某个选项；纯文字题不能用 --pick
+ *   - 同一题不能同时出现两次（pick/text 二选一）
+ *   - 必须覆盖卡里全部题
+ *
+ * @param {{questions: Array<{idx:number, options?:Array<{key:string}>}>}} card 提问卡
+ * @param {string[]} picks  --pick 原始值
+ * @param {string[]} texts  --text 原始值
+ * @returns {{answers: object[]}|{error: string}}
+ */
+export function buildAnswers(card, picks, texts) {
+  const questions = card.questions || [];
+  const byIdx = new Map(questions.map((q) => [q.idx, q]));
+  const given = new Map(); // q_idx -> answer item
+
+  const take = (raw, flag) => {
+    const a = parseAssign(raw);
+    if (!a) return `--${flag} 的格式应为 <题号>=<${flag === 'pick' ? '选项编号' : '文字'}>，收到「${raw}」`;
+    const q = byIdx.get(a.q);
+    if (!q) return `这张卡没有第 ${a.q} 题（共 ${questions.length} 题）`;
+    if (given.has(a.q)) return `第 ${a.q} 题给了不止一个答案（--pick 和 --text 二选一）`;
+    if (flag === 'pick') {
+      const key = a.value.trim().toUpperCase();
+      const keys = (q.options || []).map((o) => o.key);
+      if (keys.length === 0) return `第 ${a.q} 题是纯文字题，请用 --text ${a.q}=<文字> 回答`;
+      if (!keys.includes(key)) return `第 ${a.q} 题没有选项「${a.value}」，可选：${keys.join('、')}（都不合适请用 --text ${a.q}=<文字>）`;
+      given.set(a.q, { q_idx: a.q, option_key: key });
+    } else {
+      given.set(a.q, { q_idx: a.q, custom_text: a.value.trim() });
+    }
+    return null;
+  };
+
+  for (const raw of picks || []) { const e = take(raw, 'pick'); if (e) return { error: e }; }
+  for (const raw of texts || []) { const e = take(raw, 'text'); if (e) return { error: e }; }
+
+  const missing = questions.map((q) => q.idx).filter((i) => !given.has(i));
+  if (missing.length > 0) {
+    return { error: `没有答全：还缺第 ${missing.join('、')} 题。整张卡必须一次答完（--pick <题号>=<选项编号> 或 --text <题号>=<文字>）` };
+  }
+  return { answers: questions.map((q) => given.get(q.idx)) };
+}

package/src/config.js

@@ -0,0 +1,17 @@
+// 平台地址解析。默认连官方平台，环境变量可覆盖指向本地测试栈。
+//
+// 优先级：STELFIELD_BASE_URL > A2A_BASE_URL > 官方默认。
+// （A2A_BASE_URL 与后端 oauth.py 同名，运维同一变量即可统一切换。）
+
+/** 官方默认平台地址（CTO 拍板·M3 前提）。 */
+export const DEFAULT_BASE_URL = 'https://a2a.linger.chimap.cn';
+
+/**
+ * 解析平台基础地址。
+ * @param {Record<string,string>} env 环境变量字典（默认 process.env，传入便于单测）
+ * @returns {string} 去掉末尾斜杠的平台地址
+ */
+export function resolveBaseUrl(env = process.env) {
+  const raw = env.STELFIELD_BASE_URL || env.A2A_BASE_URL || DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, '');
+}

package/src/connect.js

@@ -0,0 +1,416 @@
+// `stelfield auth login --code <接入码>` — connect an Agent with an access code (v0.24.0).
+//
+// Flow (PRD 6.8):
+//   1. Check this profile does not already hold another working Agent (never overwrite it).
+//   2. Fetch the recognition list (/probe) and look at this machine (probe.js). Failure here is not fatal.
+//   3. POST /redeem with the code, the product name the Agent gave, and the detected tags.
+//   4. Tell the owner what to do next (go back to the Linger page and confirm).
+//   5. Poll /requests/{id}/result every 3 seconds, at most 15 minutes.
+//   6. approved -> save credentials (0600, per profile). denied / expired / errors -> one plain sentence
+//      plus a next step.
+//
+// Output: plain text by default. With --json, progress notes go to stderr and ONE JSON object goes to
+// stdout at the end (never containing tokens).
+
+import { BRAND } from "./brand.js";
+import path from 'node:path';
+import fs from 'node:fs';
+
+import { saveCredentials, loadCredentials } from './credentials.js';
+import { resolveCredDir } from './profile.js';
+import { atomicWriteFile } from './atomic-write.js';
+import { clientHeaders, CLI_VERSION, UPGRADE_COMMAND } from './client-version.js';
+import { decodeAgentId } from './oauth.js';
+import { getCruise } from './api.js';
+import { fetchProbe, collectTags } from './probe.js';
+
+const API_PREFIX = '/api/v1/agent-connect';
+export const POLL_INTERVAL_MS = 3000;
+export const MAX_WAIT_MS = 15 * 60 * 1000;
+const MAX_PRODUCT_CHARS = 40;
+const MAX_POLL_FAILURES = 10;
+const PENDING_FILE = 'connect-pending.json';
+// The platform did not name the header for the poll token, so it is sent in both common places.
+const POLL_TOKEN_HEADER = 'X-Poll-Token';
+
+/** Strip control characters, trim, and cap the product name the Agent gave (it is free text). */
+export function cleanProduct(raw) {
+  if (raw == null) return '';
+  const s = String(raw).replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
+  return Array.from(s).slice(0, MAX_PRODUCT_CHARS).join('');
+}
+
+/** Access codes are case-insensitive; spaces around them are never meaningful. */
+export function cleanCode(raw) {
+  return String(raw ?? '').replace(/\s+/g, '').toUpperCase();
+}
+
+/**
+ * One plain sentence + a next step for each failure the owner or the Agent can run into (BR-8.8).
+ * @param {string} kind  error key
+ * @param {object} [ctx] { retryAfterSec?, baseUrl?, profile? }
+ * @returns {{message:string, next:string}}
+ */
+export function explainError(kind, ctx = {}) {
+  const wait = ctx.retryAfterSec > 0 ? `${ctx.retryAfterSec} 秒` : '一会儿';
+  switch (kind) {
+    case 'code_required':
+      return {
+        message: '没有给接入码。',
+        next: `请先让主人在 ${BRAND.name} 的「绑定 Agent」页获取接入码，再运行：stelfield auth login --code <接入码> --product "<你是哪款 Agent 产品>"`,
+      };
+    case 'code_invalid':
+      return {
+        message: '接入码无效或已过期（也可能已经被用过一次）。',
+        next: `请让主人回到 ${BRAND.name} 的「绑定 Agent」页换一个新的接入码，再重新运行。`,
+      };
+    case 'pending_exists':
+      return {
+        message: '主人在网页上还有一个等着确认的接入请求。',
+        next: '请让主人先在「绑定 Agent」页确认或拒绝它，然后再运行一次。',
+      };
+    case 'rate_limited':
+      return {
+        message: `请求太频繁了，${BRAND.name} 让我们先歇一下。`,
+        next: `请等 ${wait}再重试，期间不要反复运行。`,
+      };
+    case 'agent_limit_reached':
+      return {
+        message: '主人名下的 Agent 名额已经满了，暂时接不进来。',
+        next: '请让主人在个人主页解绑一个不用的 Agent 腾出名额，再换一个新的接入码。',
+      };
+    case 'denied':
+      return {
+        message: '主人拒绝了这次接入。',
+        next: '如果不是主人的本意，请让主人在「绑定 Agent」页重新获取接入码再试。',
+      };
+    case 'expired':
+      return {
+        message: '这次接入请求已经过期了（15 分钟内没有人确认）。',
+        next: '请让主人在「绑定 Agent」页换一个新的接入码，然后重新运行。',
+      };
+    case 'timeout':
+      return {
+        message: '等了 15 分钟，主人还没有确认。',
+        next: `请提醒主人回到 ${BRAND.name} 网页点确认；如果接入码已过期，让主人换一个新的再运行。`,
+      };
+    case 'request_gone':
+      return {
+        message: '这次接入请求已经失效，或者查询凭据不对。',
+        next: '请让主人换一个新的接入码，然后重新运行。',
+      };
+    case 'already_issued':
+      return {
+        message: '主人已经确认，但凭证已经发放过一次，不能再读第二次。',
+        next: '请让主人在「绑定 Agent」页换一个新的接入码，重新接入。',
+      };
+    case 'busy_profile': {
+      const flag = ctx.profile ? `--profile ${ctx.profile}-2` : '--profile <给这个 Agent 起个名字>';
+      return {
+        message: '这个空间里已经登录着一个 Agent，不能覆盖它。',
+        next: `同一台电脑上接另一个 Agent，请单独建一个空间：stelfield ${flag} auth login --code <接入码> --product "<你是哪款 Agent 产品>"（也可以用环境变量 STELFIELD_CONFIG_DIR 指向另一个目录）。这个接入码还没有被使用。`,
+      };
+    }
+    case 'no_pending':
+      return {
+        message: '这个空间里没有正在等待确认的接入请求。',
+        next: '请让主人在「绑定 Agent」页获取接入码，再运行：stelfield auth login --code <接入码> --product "<你是哪款 Agent 产品>"',
+      };
+    case 'upgrade_required':
+      return {
+        message: '命令行工具版本太旧，需要先升级。',
+        next: `请运行：${UPGRADE_COMMAND}，然后重新运行。`,
+      };
+    case 'network':
+      return {
+        message: `连不上 ${BRAND.name}。`,
+        next: '请检查网络，稍后再重试；接入码在有效期内可以重复使用（只要还没有成功兑换）。',
+      };
+    default:
+      return {
+        message: '接入没有成功。',
+        next: '请稍后重试；如果反复出现，请让主人换一个新的接入码。',
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Small HTTP helpers (no auth header: the access code / poll token is the credential here)
+// ---------------------------------------------------------------------------
+
+async function requestJson(fetchImpl, method, url, { headers = {}, body } = {}) {
+  const init = { method, headers: { ...clientHeaders(), ...headers } };
+  if (body !== undefined) {
+    init.headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(body);
+  }
+  const resp = await fetchImpl(url, init);
+  const text = await resp.text();
+  let json = null;
+  try { json = JSON.parse(text); } catch { /* not JSON */ }
+  return { status: resp.status, ok: resp.ok, json, headers: resp.headers };
+}
+
+/** Pull the machine-readable error key out of an error response, whatever shape the backend used. */
+function errorKeyOf(res) {
+  const j = res.json;
+  if (!j || typeof j !== 'object') return null;
+  const d = j.detail;
+  if (d && typeof d === 'object' && !Array.isArray(d)) return d.error || d.code || null;
+  return j.error || j.code || (typeof d === 'string' ? d : null);
+}
+
+function retryAfterOf(res) {
+  const j = res.json || {};
+  const d = j.detail && typeof j.detail === 'object' ? j.detail : {};
+  const fromBody = Number(d.retry_after_sec ?? j.retry_after_sec);
+  if (Number.isFinite(fromBody) && fromBody > 0) return Math.ceil(fromBody);
+  const h = res.headers && typeof res.headers.get === 'function' ? Number(res.headers.get('Retry-After')) : NaN;
+  return Number.isFinite(h) && h > 0 ? Math.ceil(h) : null;
+}
+
+/** Map a failed /redeem or /result response to one of our error keys. */
+function classify(res) {
+  const key = errorKeyOf(res);
+  if (res.status === 426 || key === 'cli_upgrade_required') return 'upgrade_required';
+  if (res.status === 429 || key === 'rate_limited') return 'rate_limited';
+  if (key === 'agent_limit_reached') return 'agent_limit_reached';
+  if (key === 'pending_exists') return 'pending_exists';
+  if (res.status === 404 && (key === 'code_invalid' || key == null)) return 'code_invalid';
+  if (key === 'code_invalid') return 'code_invalid';
+  return 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// Pending-request file (only used by --no-wait / --resume)
+// ---------------------------------------------------------------------------
+
+function pendingPath(credOpts) {
+  return path.join(resolveCredDir(credOpts || {}), PENDING_FILE);
+}
+
+function savePending(credOpts, data) {
+  atomicWriteFile(pendingPath(credOpts), JSON.stringify(data), 0o600);
+}
+
+function loadPending(credOpts) {
+  try {
+    return JSON.parse(fs.readFileSync(pendingPath(credOpts), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function clearPending(credOpts) {
+  try { fs.unlinkSync(pendingPath(credOpts)); } catch { /* already gone */ }
+}
+
+// ---------------------------------------------------------------------------
+// Main flow
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `auth login --code` (or `auth login --resume`). Returns the process exit code; never throws for
+ * expected failures.
+ *
+ * Exit codes: 0 connected (or request started with --no-wait), 1 the connection did not happen,
+ * 2 wrong usage (no code).
+ *
+ * @param {object} opts
+ *   baseUrl, code, product, noWait, resume, json, profile, credDir, env,
+ *   log (stdout), err (stderr), fetchImpl, sleep, now, lookup (process lookup for tests),
+ *   pollIntervalMs, maxWaitMs
+ * @returns {Promise<number>}
+ */
+export async function runConnect(opts = {}) {
+  const {
+    baseUrl, code, product, noWait = false, resume = false, json = false, profile = null, credDir,
+    env = process.env, log = console.log, err = console.error,
+    fetchImpl = fetch,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => Date.now(),
+    lookup,
+    pollIntervalMs = POLL_INTERVAL_MS,
+    maxWaitMs = MAX_WAIT_MS,
+  } = opts;
+
+  const credOpts = credDir ? { dir: credDir } : { profile };
+  // Notes for a human or an Agent reading the output. In --json mode they move to stderr so stdout stays one JSON object.
+  const say = (line) => (json ? err(line) : log(line));
+  const docsUrl = `${baseUrl}/docs/guide/auto-accept`;
+
+  /** Print a failure (text or JSON) and return exit code 1/2. */
+  const fail = (kind, ctx = {}, exitCode = 1, extra = {}) => {
+    const { message, next } = explainError(kind, { baseUrl, profile, ...ctx });
+    if (json) {
+      log(JSON.stringify({ ok: false, status: ctx.status || kind, error: kind, message, next_step: next, ...extra }));
+    } else {
+      err(`${message}\n下一步：${next}`);
+    }
+    return exitCode;
+  };
+
+  // Success output shared by the normal and the resume path.
+  const succeed = (creds, file) => {
+    if (json) {
+      log(JSON.stringify({
+        ok: true, status: 'approved', agent_id: creds.agent_id || null, profile: profile || null,
+        credentials_path: file, next_step: `运行 stelfield ping 验证；想让 Agent 自动接单，见 ${docsUrl}`,
+      }));
+    } else {
+      log(`✓ 主人已确认，你的 Agent 已接入 ${BRAND.name}。`);
+      log(`  凭证已保存到 ${file}`);
+      log('  下一步：运行 stelfield ping 验证连通。');
+      log(`  想让 Agent 自动接单，见：${docsUrl}`);
+    }
+    return 0;
+  };
+
+  let requestId;
+  let pollToken;
+  let deadline;
+
+  if (resume) {
+    // ── Pick up a request that --no-wait started earlier ──
+    const pending = loadPending(credOpts);
+    if (!pending || !pending.request_id || !pending.poll_token) return fail('no_pending', {}, 1);
+    requestId = pending.request_id;
+    pollToken = pending.poll_token;
+    const exp = Date.parse(pending.expires_at || '');
+    deadline = now() + Math.min(maxWaitMs, Number.isFinite(exp) ? Math.max(0, exp - now()) : maxWaitMs);
+    say(`继续等待主人在 ${BRAND.name} 网页上确认…`);
+  } else {
+    const cleanedCode = cleanCode(code);
+    if (!cleanedCode) return fail('code_required', {}, 2);
+
+    // ── 1. Never overwrite another working Agent in this profile ──
+    const existing = loadCredentials(credOpts);
+    let existingAgentId = null;
+    if (existing && existing.access_token) {
+      existingAgentId = existing.agent_id || decodeAgentId(existing.access_token) || null;
+      let alive = false;
+      try {
+        await getCruise(baseUrl, credOpts, { fetchImpl });
+        alive = true;
+      } catch {
+        alive = false; // login is dead (or unreachable): re-connecting is exactly what the owner wants
+      }
+      if (alive) return fail('busy_profile', {}, 1);
+    }
+
+    // ── 2. Recognition (best effort) ──
+    const probe = await fetchProbe(baseUrl, { fetchImpl });
+    const tags = await collectTags(probe, { env, lookup });
+
+    // ── 3. Redeem ──
+    const body = {
+      code: cleanedCode,
+      env_tags: tags.env_tags,
+      process_tags: tags.process_tags,
+      cli_version: CLI_VERSION,
+      os: process.platform,
+    };
+    const cleanedProduct = cleanProduct(product);
+    if (cleanedProduct) body.product = cleanedProduct;
+    if (existingAgentId) body.agent_id = existingAgentId;
+
+    let res;
+    try {
+      res = await requestJson(fetchImpl, 'POST', `${baseUrl}${API_PREFIX}/redeem`, { body });
+    } catch {
+      return fail('network');
+    }
+    if (!res.ok || !res.json || !res.json.request_id || !res.json.poll_token) {
+      const kind = classify(res);
+      return fail(kind, { retryAfterSec: retryAfterOf(res) });
+    }
+    requestId = res.json.request_id;
+    pollToken = res.json.poll_token;
+    const exp = Date.parse(res.json.expires_at || '');
+    deadline = now() + Math.min(maxWaitMs, Number.isFinite(exp) ? Math.max(0, exp - now()) : maxWaitMs);
+
+    // ── 4. Tell the owner what to do ──
+    say('✓ 接入码有效，已通知主人。');
+    say(`请让主人回到 ${BRAND.name} 网页，在「绑定 Agent」页点确认。`);
+    say('等待期间不需要主人再贴别的东西；我会每隔几秒查一次，最长等 15 分钟。');
+
+    if (noWait) {
+      savePending(credOpts, {
+        request_id: requestId, poll_token: pollToken, expires_at: res.json.expires_at || null, base_url: baseUrl,
+      });
+      if (json) {
+        log(JSON.stringify({
+          ok: true, status: 'pending', request_id: requestId, expires_at: res.json.expires_at || null,
+          next_step: '主人在网页确认后，运行 stelfield auth login --resume 取回凭证（也可带上同样的 --profile）。',
+        }));
+      } else {
+        log('（--no-wait）已发起，不再等待。主人确认后，运行：stelfield auth login --resume 取回凭证。');
+      }
+      return 0;
+    }
+  }
+
+  // ── 5. Poll for the owner's answer ──
+  // Pending-file bookkeeping: a normal run does not leave one behind.
+  let failures = 0;
+  const url = `${baseUrl}${API_PREFIX}/requests/${encodeURIComponent(requestId)}/result`;
+  const pollHeaders = { Authorization: `Bearer ${pollToken}`, [POLL_TOKEN_HEADER]: pollToken };
+  let first = true;
+  for (;;) {
+    if (!first) {
+      if (now() >= deadline) { clearPending(credOpts); return fail('timeout', { status: 'timeout' }); }
+      await sleep(pollIntervalMs);
+    }
+    first = false;
+    if (now() >= deadline) { clearPending(credOpts); return fail('timeout', { status: 'timeout' }); }
+
+    let r;
+    try {
+      r = await requestJson(fetchImpl, 'GET', url, { headers: pollHeaders });
+    } catch {
+      failures += 1;
+      if (failures >= MAX_POLL_FAILURES) return fail('network');
+      continue;
+    }
+
+    if (r.ok && r.json) {
+      failures = 0;
+      const status = r.json.status;
+      if (status === 'pending') continue;
+      if (status === 'denied') {
+        clearPending(credOpts);
+        // The owner did not refuse: the 5-Agent limit filled up between the knock and the confirm click.
+        if (r.json.reason === 'agent_limit_reached') return fail('agent_limit_reached', { status: 'denied' });
+        return fail('denied', { status: 'denied' });
+      }
+      if (status === 'expired') { clearPending(credOpts); return fail('expired', { status: 'expired' }); }
+      if (status === 'approved') {
+        const c = r.json.credentials;
+        if (!c || !c.access_token) { clearPending(credOpts); return fail('already_issued', { status: 'approved' }); }
+        // ── 6. Save credentials (0600, per profile) ──
+        const agentId = c.agent_id || decodeAgentId(c.access_token) || null;
+        const creds = { ...c, base_url: baseUrl };
+        if (agentId) creds.agent_id = agentId;
+        const file = saveCredentials(creds, credOpts);
+        clearPending(credOpts);
+        return succeed(creds, file);
+      }
+      continue; // unknown status: keep waiting until the deadline
+    }
+
+    const kind = classify(r);
+    if (kind === 'rate_limited') {
+      // Slow down as told, then keep going.
+      const wait = (retryAfterOf(r) || 10) * 1000;
+      await sleep(wait);
+      continue;
+    }
+    if (kind === 'upgrade_required') return fail(kind);
+    if (r.status === 404 || r.status === 401 || r.status === 403 || r.status === 410) {
+      clearPending(credOpts);
+      return fail('request_gone');
+    }
+    failures += 1; // 5xx and the like: retry a few times
+    if (failures >= MAX_POLL_FAILURES) return fail('network');
+  }
+}