@stelfield/cli 0.0.0-stage → 0.12.0

package/src/oauth.js

@@ -0,0 +1,327 @@
+// OAuth 授权码 + PKCE + 本机回环登录流程（M3 实装 · M4/M5 加固）。
+//
+// 整条登录链（RFC 7636 PKCE + RFC 8252 本机回环）：
+//   1. 本机起一个临时 HTTP server（端口由系统随机分配）接授权回调
+//   2. 生成 PKCE 暗号 + state 防伪标记
+//   3. 打开默认浏览器到 Linger 授权确认页（/oauth/authorize）
+//   4. 用户在浏览器点「允许」→ 平台把浏览器跳回本机临时地址、带回授权码
+//   5. 本机 server 收到授权码 → 关掉自己
+//   6. 拿授权码 + 暗号原文向平台换 token（POST /oauth/token）
+//   7. token 存到本机 ~/.stelfield/credentials
+//
+// 设计原则：纯函数（buildAuthorizeUrl / exchangeToken）单独可测；
+//   带副作用的部分（起 server / 开浏览器）做成可注入，便于将来端到端测试。
+
+import { BRAND } from "./brand.js";
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+
+import { generateVerifier, challengeFromVerifier, generateState } from './pkce.js';
+import { saveCredentials, loadCredentials } from './credentials.js';
+import { CALLBACK_HTML_SUCCESS, CALLBACK_HTML_ERROR, CALLBACK_HTML_MISSING } from './callback-pages.js';
+
+/**
+ * 从 JWT access token 解出 agent_id（无需验签·只取 payload）。
+ *
+ * M1 契约：access token JWT payload 里 agent_id 字段名 = `agent_id`。
+ * 解析失败 → 返回 null，不 crash（首次接入时 token 可能不含此字段）。
+ *
+ * @param {string} token  JWT 字符串
+ * @returns {string|null}
+ */
+export function decodeAgentId(token) {
+  try {
+    const payloadB64 = token.split('.')[1];
+    if (!payloadB64) return null;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+    return payload.agent_id || null;
+  } catch {
+    return null;
+  }
+}
+
+// M5 预注册 client_id（已在平台 oauth_clients 表预注册，无需动态注册）。
+export const POC_CLIENT_ID = 'linger-cli';
+
+// 本机回环回调路径（与平台白名单登记的 path 必须一致 · 只端口可变）。
+const CALLBACK_PATH = '/callback';
+
+/**
+ * 拼装 Linger 授权确认页地址（/oauth/authorize）。纯字符串，无副作用。
+ *
+ * @param {string} baseUrl 平台基础地址（已去尾斜杠）
+ * @param {object} p { clientId, redirectUri, codeChallenge, state, scope?, agentId? }
+ *   agentId: 本机已有 agent_id 时传入，让后端复用该 agent（续命流程，不新建）。
+ * @returns {string} 完整授权页 URL
+ */
+export function buildAuthorizeUrl(baseUrl, p) {
+  const url = new URL(`${baseUrl}/oauth/authorize`);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', p.clientId);
+  url.searchParams.set('redirect_uri', p.redirectUri);
+  url.searchParams.set('code_challenge', p.codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('state', p.state);
+  url.searchParams.set('scope', p.scope || 'platform');
+  // M1 契约：带回本机已知的 agent_id，后端校验归属后复用（不新建）
+  if (p.agentId) {
+    url.searchParams.set('agent_id', p.agentId);
+  }
+  return url.toString();
+}
+
+/**
+ * 用授权码 + PKCE 暗号原文向平台换 token（POST /oauth/token）。
+ *
+ * 按 OAuth 2.0 §4.1.3 发 application/x-www-form-urlencoded（后端真实客户端口径）。
+ *
+ * @returns {Promise<object>} 平台返回的 token 对象 { access_token, refresh_token, ... }
+ * @throws {Error} 换码失败（HTTP 非 2xx 或网络错误）
+ */
+export async function exchangeToken(baseUrl, { code, codeVerifier, redirectUri, clientId }) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: codeVerifier,
+  });
+
+  const resp = await fetch(`${baseUrl}/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+
+  const text = await resp.text();
+  if (!resp.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text);
+      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
+    } catch {
+      /* 非 JSON 错误体，原样用 */
+    }
+    throw new Error(`换取登录凭证失败（${resp.status}）：${msg}`);
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * 在本机起一个临时 HTTP server 接授权回调。端口由系统随机分配（port 0）。
+ *
+ * @param {object} [opts] { host?, port? } —— 仅测试用：覆盖监听 host/端口以强制 bind 失败回归；
+ *   生产默认 127.0.0.1:0（OS 随机分配空闲端口·天然无冲突）
+ * @returns {Promise<{ port, redirectUri, waitForCode, close }>}
+ *   - port: 系统分配的随机端口
+ *   - redirectUri: http://127.0.0.1:{port}/callback（拼授权请求用）
+ *   - waitForCode(): Promise<string> —— 等浏览器回调拿到授权码（或 state/error）
+ *   - close(): 关 server
+ */
+export function startLoopbackServer({ host = '127.0.0.1', port = 0 } = {}) {
+  let resolveCode, rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+
+  // 外层 startup Promise 的 reject + 启动状态标记（bind 失败投递用·见 server.on('error')）
+  let rejectStartup;
+  let started = false;
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, 'http://127.0.0.1');
+    if (u.pathname !== CALLBACK_PATH) {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Not Found');
+      return;
+    }
+    const code = u.searchParams.get('code');
+    const error = u.searchParams.get('error');
+    const state = u.searchParams.get('state');
+
+    // 给浏览器一个「可以关掉这个标签页了」的极简页面
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    if (error) {
+      res.end(CALLBACK_HTML_ERROR);
+      rejectCode(new Error(`用户未授权或授权被拒绝：${error}`));
+    } else if (code) {
+      res.end(CALLBACK_HTML_SUCCESS);
+      resolveCode({ code, state });
+    } else {
+      res.end(CALLBACK_HTML_MISSING);
+      rejectCode(new Error('回调地址未带授权码'));
+    }
+  });
+
+  // B 组加固（bug-m5-cli-001 修正）：bind 失败（EADDRINUSE 等）必须让
+  // `await startLoopbackServer()` 立即失败、不静默挂起。按启动阶段区分投递目标：
+  //   - 启动阶段出错（started=false）→ reject 外层 startup Promise（await 处抛错）
+  //   - 启动后运行期出错（started=true）→ reject 内层 codePromise（waitForCode 处抛错）
+  // 两路互斥，避免「reject 了 codePromise 却无人 await」导致 unhandledRejection 逃逸。
+  server.on('error', (err) => {
+    const e = new Error(
+      `本机临时服务启动失败（${err.message}）。端口可能被占用，请重试 stelfield auth login，`
+      + `或加 --no-wait 在能打开浏览器的机器上完成授权。`
+    );
+    if (!started && rejectStartup) {
+      rejectStartup(e);
+    } else {
+      rejectCode(e);
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    rejectStartup = reject;
+    // 监听 host:port（默认 127.0.0.1:0 系统随机分配端口·本机回环）
+    server.listen(port, host, () => {
+      started = true;
+      const port = server.address().port;
+      resolve({
+        port,
+        redirectUri: `http://127.0.0.1:${port}${CALLBACK_PATH}`,
+        waitForCode: () => codePromise,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+/**
+ * 尽力打开系统默认浏览器到指定 URL（跨平台·零依赖）。
+ * 打不开不致命：调用方会把 URL 打印出来让用户手动复制。
+ */
+export function openBrowser(url) {
+  let cmd, args;
+  if (process.platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (process.platform === 'win32') {
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {}); // 命令不存在等 → 忽略（调用方已打印 URL）
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 执行 `stelfield auth login` 全流程。
+ *
+ * @param {object} opts
+ *   - baseUrl: 平台地址
+ *   - noWait: true → 只准备好回环 + 打印授权 URL 就返回（对齐飞书 --no-wait，给 agent 用），
+ *             不阻塞等浏览器；调用方负责后续。返回 { url, redirectUri, server, verifier, state }。
+ *   - credDir: 凭证目录覆盖（测试用）
+ *   - log: 输出函数（默认 console.log，便于测试静默）
+ *   - timeoutMs: 等浏览器回调的超时（默认 5 分钟）
+ * @returns {Promise<object>} noWait=false → 存好的 credentials；noWait=true → 上述准备态对象
+ */
+export async function runAuthLogin(opts = {}) {
+  const {
+    baseUrl,
+    noWait = false,
+    credDir,
+    profile,          // --profile：同机多 Agent 时每个 Agent 一份独立凭证目录
+    log = console.log,
+    timeoutMs = 5 * 60 * 1000,
+    clientId = POC_CLIENT_ID,
+  } = opts;
+
+  const verifier = generateVerifier();
+  const challenge = challengeFromVerifier(verifier);
+  const state = generateState();
+
+  // M1 契约：读取本机已有 agent_id，带入授权请求让后端复用该 agent（续命流程）。
+  // 首次接入 / 凭证不存在 → agentId 为 null → 后端新建 agent（接新流程）。
+  // 目录优先级：credDir（测试/显式） > --profile > STELFIELD_CONFIG_DIR > ~/.stelfield
+  const credOpts = credDir ? { dir: credDir } : { profile };
+  const existingCreds = loadCredentials(credOpts);
+  const existingAgentId = existingCreds?.agent_id || null;
+
+  const server = await startLoopbackServer();
+  const authUrl = buildAuthorizeUrl(baseUrl, {
+    clientId,
+    redirectUri: server.redirectUri,
+    codeChallenge: challenge,
+    state,
+    scope: 'platform',
+    agentId: existingAgentId,   // null 时 buildAuthorizeUrl 不会加此参数
+  });
+
+  if (noWait) {
+    // --no-wait：给 agent 用 —— 不开浏览器、不阻塞，只把授权 URL 交出去。
+    // 注意：此模式下回环 server 仍在监听，调用方需自行驱动 waitForCode + 换码 + close。
+    log(authUrl);
+    return { url: authUrl, redirectUri: server.redirectUri, server, verifier, state, clientId, baseUrl };
+  }
+
+  // 交互模式：打开浏览器 + 阻塞等回调
+  log(`正在打开浏览器完成 ${BRAND.name} 授权…`);
+  log(`如果浏览器没有自动打开，请手动访问：\n${authUrl}\n`);
+  openBrowser(authUrl);
+
+  // 超时保护：用户关了浏览器没授权 → 不静默挂起。
+  // B 组加固：
+  //   1. timer.unref()：让计时器不阻止进程退出（即使 timer 未 clear，进程也能正常退）。
+  //   2. clearTimeout(timerId)：成功/失败后主动清掉计时器（双重保险）。
+  let timerId;
+  const timeout = new Promise((_, rej) => {
+    timerId = setTimeout(
+      () => rej(new Error(
+        '等待授权超时（5 分钟内未完成）。\n'
+        + '• 如果当前环境无法打开浏览器，请加 --no-wait 参数（打印授权 URL 让你在别处完成）。\n'
+        + '• 或换一台能打开浏览器的机器重试 stelfield auth login。'
+      )),
+      timeoutMs
+    );
+    // unref：计时器不阻止进程退出（Node 进程事件循环里不会因为这个 timer 还在跑就不退出）
+    timerId.unref();
+  });
+
+  let codeResult;
+  try {
+    codeResult = await Promise.race([server.waitForCode(), timeout]);
+  } finally {
+    // 无论成功还是失败，都清掉超时计时器（double-unref）
+    clearTimeout(timerId);
+    await server.close();
+  }
+
+  // 校验 state 一致（防回调被伪造）
+  if (codeResult.state && codeResult.state !== state) {
+    throw new Error('授权回调的防伪标记不匹配，已中止（安全保护）。');
+  }
+
+  log('授权成功，正在换取登录凭证…');
+  const tokenObj = await exchangeToken(baseUrl, {
+    code: codeResult.code,
+    codeVerifier: verifier,
+    redirectUri: server.redirectUri,
+    clientId,
+  });
+
+  // M1 契约：从 access token JWT payload 解出 agent_id，落盘到凭证文件。
+  //   - 首次接入：后端新建 agent → access token 含新 agent_id
+  //   - 续命：后端复用旧 agent → access token 含同一 agent_id
+  // 解析失败（非标准 JWT 或旧版本后端）→ 保留 existingAgentId（不覆盖）。
+  const decodedAgentId = decodeAgentId(tokenObj.access_token);
+  const agentId = decodedAgentId || existingAgentId;
+
+  const creds = { ...tokenObj, base_url: baseUrl };
+  if (agentId) creds.agent_id = agentId;  // 有 agent_id 才写入（不写 null）
+
+  const file = saveCredentials(creds, credOpts);
+  log('✓ 绑定成功，你的 Agent 已接入 Linger。');
+  log(`  在主页查看你的 Agent：${baseUrl}`);
+  log(`  凭证已保存到 ${file}`);
+  return creds;
+}

package/src/pkce.js

@@ -0,0 +1,47 @@
+// PKCE（RFC 7636）+ state 生成。纯算法、无网络、无副作用。
+//
+// 命令行登录用「授权码 + PKCE」流程：
+//   1. 本地随机生成一段 verifier（暗号原文）
+//   2. 算出它的 S256 摘要 challenge（暗号摘要），随授权请求发给平台
+//   3. 换码时把 verifier 原文发回平台，平台重算摘要核对 → 防授权码被中途截走盗用
+//
+// ⚠ challenge 算法必须与 Linger 后端口径分毫不差：
+//   后端（a2a-backend/app/routes/oauth.py _handle_authorization_code）：
+//     base64url( sha256(verifier) ) 去掉结尾 '=' 补位。
+
+import crypto from 'node:crypto';
+
+/** base64url 编码（无 padding）：把 + / 换成 - _，去掉结尾的 =。 */
+function base64url(buf) {
+  return buf
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * 生成 PKCE code_verifier（暗号原文）。
+ * RFC 7636 §4.1：43~128 个 unreserved 字符。
+ * 32 字节随机 → base64url 后约 43 字符，落在合规区间。
+ */
+export function generateVerifier() {
+  return base64url(crypto.randomBytes(32));
+}
+
+/**
+ * 由 verifier 算出 S256 code_challenge（暗号摘要）。
+ * 必须与后端口径一致：base64url(sha256(verifier))，无 padding。
+ */
+export function challengeFromVerifier(verifier) {
+  const digest = crypto.createHash('sha256').update(verifier).digest();
+  return base64url(digest);
+}
+
+/**
+ * 生成 OAuth state（防伪标记 · 防登录回调被人伪造/CSRF）。
+ * 16 字节随机 → base64url。
+ */
+export function generateState() {
+  return base64url(crypto.randomBytes(16));
+}

package/src/poll-state.js

@@ -0,0 +1,88 @@
+// 盯单游标（cursor）持久化：记住"stelfield poll 上次看到哪条消息了"。
+//
+// 为什么单独建文件、不塞进 credentials.js：
+//   游标不是凭证（不涉及登录身份），是"消费进度"，职责边界不同，混在一起
+//   容易让人误以为"游标丢了 = 要重新登录"（实际上游标丢了只是重新从头看一遍）。
+//
+// 存储路径：{STELFIELD_CONFIG_DIR}/poll-cursor（与 credentials 文件同目录）。
+// 目录优先级与 credentials.js 的 credDir() 完全一致（三级回退：opts.dir > STELFIELD_CONFIG_DIR > ~/.stelfield），
+// 保证"同一个 agent 的凭证和游标存在同一个地方"、"不同 agent 的凭证和游标都物理隔离"。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFile } from './atomic-write.js';
+import { resolveCredDir } from './profile.js';
+
+/** 凭证/游标目录解析（与 credentials.js::credDir 同一份实现 · 含 --profile 支持）。 */
+function credDir(opts = {}) {
+  return resolveCredDir(opts);
+}
+
+/** 游标文件完整路径（{目录}/poll-cursor）。 */
+export function cursorPath(opts = {}) {
+  return path.join(credDir(opts), 'poll-cursor');
+}
+
+/**
+ * 读取上次落盘的游标。
+ * 文件不存在 / 内容非法（非整数）→ 返回 0（视为首次运行，从头开始）。
+ *
+ * @param {object} opts { dir? }
+ * @returns {number}
+ */
+export function readCursor(opts = {}) {
+  const file = cursorPath(opts);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return 0; // 文件不存在 / 读不了 → 首次运行
+  }
+  const n = parseInt(raw.trim(), 10);
+  return Number.isFinite(n) ? n : 0; // 内容损坏 → 当作首次运行，不炸命令
+}
+
+/**
+ * 写回最新游标（原子写：temp+rename，防进程被杀导致半写损坏）。
+ *
+ * @param {number} cursor 最新游标值（服务端返回的 next_cursor）
+ * @param {object} opts { dir? }
+ */
+export function writeCursor(cursor, opts = {}) {
+  const file = cursorPath(opts);
+  atomicWriteFile(file, String(cursor), 0o600);
+  return file;
+}
+
+// ── 平台建议的下次最早来看的时间（poll 响应里的 next_poll_after）──
+//
+// 平台忙的时候，会在「没有新动静」的回复里建议 Agent 过一会儿再来。这里把「最早可以再发请求的时刻」记在本机，
+// cron 每次启动都是全新进程，只能靠文件续接。没到时间就直接不发请求（零网络、零 token）。
+// 文件不存在 / 内容损坏 = 没有建议，照常发请求。
+
+/** 建议等待时间文件路径（{目录}/poll-next-at，内容是毫秒时间戳）。 */
+export function nextPollPath(opts = {}) {
+  return path.join(credDir(opts), 'poll-next-at');
+}
+
+/** 读取「最早可以再看」的毫秒时间戳；没有或损坏返回 0。 */
+export function readNextPollAt(opts = {}) {
+  try {
+    const n = parseInt(fs.readFileSync(nextPollPath(opts), 'utf8').trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** 写入（atMs 为毫秒时间戳）或清除（传 0 / null）建议时间。写失败不影响 poll 本身。 */
+export function writeNextPollAt(atMs, opts = {}) {
+  const file = nextPollPath(opts);
+  try {
+    if (!atMs) {
+      try { fs.unlinkSync(file); } catch { /* 本来就没有 */ }
+      return;
+    }
+    atomicWriteFile(file, String(Math.round(atMs)), 0o600);
+  } catch { /* 记不下来就当没有建议 */ }
+}

package/src/probe.js

@@ -0,0 +1,155 @@
+// Environment hints for `stelfield auth login --code` (v0.24.0).
+//
+// What this does for the user:
+//   When your Agent asks to be connected, Linger would like to guess which Agent product it is, so the
+//   confirmation page can say "this looks like X" and catch a wrong pick. The guess uses two very small
+//   facts about this machine, and nothing else:
+//     1. whether certain environment variables EXIST (the names come from the platform's list)
+//     2. the program name of the process that started this command (up to 4 levels up)
+//
+// Hard rules (PRD BR-8.3):
+//   - We only check whether an environment variable name is present. We NEVER read, print or send its value.
+//   - We never collect directories, command-line arguments, other processes, user names or machine names.
+//   - The name lists come from the server (GET /api/v1/agent-connect/probe); this file contains no product
+//     names. If the list cannot be fetched, detection is simply skipped and the login still works.
+
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+
+import { clientHeaders } from './client-version.js';
+
+const PROBE_PATH = '/api/v1/agent-connect/probe';
+const PROBE_TIMEOUT_MS = 5000;
+const PS_TIMEOUT_MS = 1000;
+const MAX_PARENT_LEVELS = 4;
+const MAX_TAGS = 20;
+// Only names that look like plain identifiers are ever looked up (defensive: the list comes from a server).
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const PROC_NAME_RE = /^[A-Za-z0-9._+-]{1,64}$/;
+
+/**
+ * Fetch the recognition list from the platform. Never throws.
+ *
+ * @param {string} baseUrl platform base URL (no trailing slash)
+ * @param {object} [opts] { fetchImpl?, timeoutMs? }
+ * @returns {Promise<{version:any, env_names:string[], process_names:string[], legacy_login:(boolean|null)}|null>}
+ *   null when the platform could not be reached or answered with something unusable.
+ *   legacy_login is null when the platform did not say (old backend).
+ */
+export async function fetchProbe(baseUrl, opts = {}) {
+  const { fetchImpl = fetch, timeoutMs = PROBE_TIMEOUT_MS } = opts;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  try {
+    const resp = await fetchImpl(`${baseUrl}${PROBE_PATH}`, {
+      method: 'GET',
+      headers: { ...clientHeaders() },
+      signal: ac.signal,
+    });
+    if (!resp.ok) return null;
+    const body = JSON.parse(await resp.text());
+    if (!body || typeof body !== 'object') return null;
+    const strList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+    return {
+      version: body.version ?? null,
+      env_names: strList(body.env_names),
+      process_names: strList(body.process_names),
+      legacy_login: typeof body.legacy_login === 'boolean' ? body.legacy_login : null,
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Which of the listed environment variable names exist? Returns names only, never values.
+ *
+ * @param {string[]} names list from the platform
+ * @param {object} [env] defaults to process.env
+ * @returns {string[]} the subset of `names` that are present
+ */
+export function detectEnvTags(names, env = process.env) {
+  const out = [];
+  for (const name of names || []) {
+    if (out.length >= MAX_TAGS) break;
+    if (typeof name !== 'string' || !ENV_NAME_RE.test(name)) continue;
+    // `in` answers "is the key there?" without reading the value.
+    if (name in env && !out.includes(name)) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Default way to look at one process: ask `ps` for its parent pid and program name.
+ * Unix-like systems only; anywhere else (or on any failure) returns null.
+ *
+ * @param {number} pid
+ * @returns {Promise<{ppid:number, comm:string}|null>}
+ */
+export function psLookup(pid) {
+  if (process.platform === 'win32') return Promise.resolve(null);
+  return new Promise((resolve) => {
+    try {
+      execFile('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { timeout: PS_TIMEOUT_MS }, (error, stdout) => {
+        if (error) return resolve(null);
+        const m = /^\s*(\d+)\s+(.+?)\s*$/m.exec(String(stdout));
+        if (!m) return resolve(null);
+        resolve({ ppid: Number(m[1]), comm: m[2] });
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * Which of the listed program names appear among our parent processes (up to 4 levels)?
+ * Only the program's base name is compared; nothing else about the processes is kept.
+ *
+ * @param {string[]} names list from the platform
+ * @param {object} [opts] { startPid?, lookup?: (pid)=>Promise<{ppid,comm}|null> }
+ * @returns {Promise<string[]>} the subset of `names` seen among the parents (original spelling from the list)
+ */
+export async function detectProcessTags(names, opts = {}) {
+  const { startPid = process.ppid, lookup = psLookup } = opts;
+  const wanted = new Map();
+  for (const n of names || []) {
+    if (typeof n === 'string' && PROC_NAME_RE.test(n)) wanted.set(n.toLowerCase(), n);
+  }
+  if (wanted.size === 0) return [];
+  const out = [];
+  let pid = startPid;
+  for (let level = 0; level < MAX_PARENT_LEVELS; level++) {
+    if (!Number.isInteger(pid) || pid <= 1) break;
+    let info = null;
+    try {
+      info = await lookup(pid);
+    } catch {
+      info = null;
+    }
+    if (!info) break;
+    // comm may be a full path on macOS and may carry a leading "-" for login shells
+    const base = path.basename(String(info.comm || '')).replace(/^-/, '').replace(/\.exe$/i, '').toLowerCase();
+    const hit = wanted.get(base);
+    if (hit && !out.includes(hit)) out.push(hit);
+    pid = info.ppid;
+  }
+  return out.slice(0, MAX_TAGS);
+}
+
+/**
+ * Run both checks against a fetched list. A missing list means "skip detection".
+ *
+ * @param {object|null} probe result of fetchProbe
+ * @param {object} [opts] { env?, lookup?, startPid? }
+ * @returns {Promise<{env_tags:string[], process_tags:string[]}>}
+ */
+export async function collectTags(probe, opts = {}) {
+  if (!probe) return { env_tags: [], process_tags: [] };
+  const env_tags = detectEnvTags(probe.env_names, opts.env || process.env);
+  const process_tags = await detectProcessTags(probe.process_names, { lookup: opts.lookup, startPid: opts.startPid });
+  return { env_tags, process_tags };
+}