@optima-chat/dev-skills 0.16.6 → 0.16.8

package/.codex/skills/yzsgo-e2e/pull_wire.py

@@ -169,6 +169,19 @@ def render_conversation(conv, resps, deref, idx):
                         res_ids.add(b.get("tool_use_id"))
     dangling = [(u, n) for u, n in use_ids.items() if u not in res_ids]
 
+    # 末 response 状态：审查靠它判「最终回复能不能核」。缺失时**必须显式标注**，
+    # 否则 transcript 静默停在末条 user 消息（常是超长 tool_result 截断处），
+    # 会被误读成「响应被截断吞了」（上游 #102 真根因：不是截断，是末 req 无 response 记录）。
+    lastresp = resps.get(last["callId"])
+    if not lastresp:
+        last_state = "⚠️ 末 request 无 response 记录（生成中断/未落盘/末轮是 continuation）——最终回复不可核"
+    elif lastresp.get("kind") == "error":
+        last_state = "⚠️ 末 response 是 error：" + json.dumps(deref(lastresp.get("error") or {}), ensure_ascii=False)[:160]
+    elif (lastresp.get("finalMessage") or {}).get("stopReason") == "max_tokens":
+        last_state = "⚠️ 末 response stop_reason=max_tokens（回复被截断，可能未说完）"
+    else:
+        last_state = "有（正常 response）"
+
     L = [f"# 对话 #{idx}  {ts0}",
          "", f"**prompt**: {prompt[:200]}", "",
          "## 事实卡（代码算的确定信息）",
@@ -176,9 +189,9 @@ def render_conversation(conv, resps, deref, idx):
          f"- error 响应 {len(errs)}" + (f"：{[json.dumps(deref(e.get('error') or {}),ensure_ascii=False)[:120] for e in errs]}" if errs else ""),
          f"- stop_reason=max_tokens 的响应 {maxtok}",
          f"- 悬空 tool_use（无匹配 result）{len(dangling)}: {dangling[:5]}",
+         f"- 末 response: {last_state}",
          "", "## 完整 transcript（末 req 全历史 + 末 response）", ""]
-    # 末 response 拼到历史尾
-    lastresp = resps.get(last["callId"])
+    # 末 response 拼到历史尾（仅 response 类才有 finalMessage 内容可拼）
     if lastresp and lastresp.get("kind") == "response":
         fm = lastresp.get("finalMessage") or {}
         msgs.append({"role": "assistant", "content": fm.get("content", [])})
@@ -190,8 +203,15 @@ def render_conversation(conv, resps, deref, idx):
             L.append("    " + _clip(c, CAP_TEXT))
         elif isinstance(c, list):
             for b in c:
-                L.append(render_block(b, deref))
-    return prompt, ts0, len(errs), len(dangling), "\n".join(L)
+                try:
+                    L.append(render_block(b, deref))
+                except Exception as e:  # 单个块渲染失败不该中断后续消息（上游 #102 加固）
+                    L.append(f"    [渲染失败 {type(e).__name__}: {str(e)[:80]}]")
+    # transcript 结尾显式收口——末 response 非正常时补一行，让审查者绝不把静默结束当完整
+    resp_ok = bool(lastresp and lastresp.get("kind") == "response")
+    if not resp_ok:
+        L.append(f"\n--- [transcript 结束] {last_state} ---")
+    return prompt, ts0, len(errs), len(dangling), resp_ok, "\n".join(L)
 
 
 def render_all(wire_root, out):
@@ -214,10 +234,10 @@ def render_all(wire_root, out):
         index.append(f"\n## session `{sid}` — {len(convs)} 对话 / {len(reqs)} req\n")
         for conv in convs:
             gidx += 1
-            prompt, ts0, n_err, n_dang, md = render_conversation(conv, resps, deref, gidx)
+            prompt, ts0, n_err, n_dang, resp_ok, md = render_conversation(conv, resps, deref, gidx)
             fn = f"{gidx:03d}.md"
             open(os.path.join(conv_dir, fn), "w", encoding="utf-8").write(md)
-            flag = (" ⚠️err" if n_err else "") + (" ⚠️dangling" if n_dang else "")
+            flag = (" ⚠️err" if n_err else "") + (" ⚠️dangling" if n_dang else "") + ("" if resp_ok else " ⚠️无末response")
             index.append(f"- [{fn}](conversations/{fn}) [{len(conv):>2} req] {prompt[:64]}{flag}")
     idxpath = os.path.join(out, "index.md")
     open(idxpath, "w", encoding="utf-8").write("\n".join(index))
@@ -278,9 +298,20 @@ def _ts_key(ts):
         return None
 
 
-def locate_conversation(index, started_ts, first_message):
+def locate_conversation(index, started_ts, first_message, session_id=None):
     """按 (started_ts, first_message) 定位本次对话；禁用 ls -t。规则见 plan Task 3 Interfaces。
-    时间比较先把两侧 ISO（Z / +00:00、小数位宽不同）归一成 datetime，避免依赖字典序=数值序的脆弱假设。"""
+    时间比较先把两侧 ISO（Z / +00:00、小数位宽不同）归一成 datetime，避免依赖字典序=数值序的脆弱假设。
+
+    `session_id`（2026-09-09 起，鸭嘴兽支持并发任务后）：驱动侧现在知道自己跑在**哪个 gateway
+    session** 上（一 tab 一 session，wire 目录名就是 sessionId），传进来就先把候选缩到该 session。
+    这是**确定性**定位，比 (时间, 首句) 的启发式可靠得多 —— 同一句 prompt 重跑多次时，
+    启发式只能靠时间戳挑，而并发跑的多个会话时间戳本来就交叠。
+    传了但该 session 在索引里一条都没有（wire 还没落盘/TTL 过期/拉的账号不对）→ **不回退**到
+    全局启发式：那样会安静地定位到别的 session 的对话，比返回 None 更糟。"""
+    if session_id:
+        index = [it for it in index if it.get("sid") == session_id]
+        if not index:
+            return None
     key = (first_message or "").strip()[:40]
     cands = []
     for it in index:

package/.codex/skills/yzsgo-e2e/run_e2e.py

@@ -85,7 +85,15 @@ def main():
 
     started_ts = _utc_now()
     answers = _parse_answers(args.answer)
+    # attach() 默认就自己开 tab 独占一个 gateway session（"auto" 档）。两个好处——
+    #  ① 不去抢用户已经开着的 chat tab（抢了会互相串台，见 chat_driver 模块 docstring）；
+    #  ② 拿到确定的 sessionId，后面按它**确定性**定位 wire 对话，不靠 (时间,首句) 猜。
+    # 该环境 multi-tab 没开（flag 默认关，cn-stage 未验）时 auto 档自己会降级复用已有 tab
+    # 并打 warn —— 单 driver 复用是安全的，功能不减，只是 wire 定位退回启发式。
     d = chat_driver.ChatDriver().attach()
+    session_id = d.session_id      # attach 后立刻取：放在 try 里的话，中途抛异常会留下未绑定名
+    if not d.tab_isolated:
+        print("[warn] 未能独占 tab（该环境 multi-tab 未开）—— wire 定位退回 (时间,首句) 启发式")
     try:
         d.new_conversation()
         turns = []
@@ -99,13 +107,17 @@ def main():
     wire_root = pull_wire.pull(args.user, since_days=args.since, out=args.out)
     meta = {"env": args.env, "started_ts": started_ts, "first_message": args.message[0],
             "expect": args.expect, "issue_repo": args.issue_repo, "turns": turns,
+            "session_id": session_id,      # 本轮跑在哪个 gateway session（= wire 目录名）
             "located": None, "located_reason": None}
     wrote_prepped = False
     if not wire_root:
         meta["located_reason"] = "no_wire_session"
     if wire_root:
         index = pull_wire.emit_conversation_index(wire_root)
-        hit = pull_wire.locate_conversation(index, started_ts, args.message[0])
+        hit = pull_wire.locate_conversation(index, started_ts, args.message[0],
+                                            session_id=session_id)
+        if session_id and not hit:
+            meta["located_reason"] = f"session {session_id} 在 wire 索引里没有对话（未落盘/TTL 过期/账号不对）"
         meta["located"] = hit
         if hit:
             sdir = os.path.join(wire_root, hit["sid"])
@@ -117,7 +129,10 @@ def main():
             convs = pull_wire.segment(reqs, deref)
             conv = select_conversation_in_session(convs, deref, hit)
             if conv is not None:
-                _, _, _, _, wire_md = pull_wire.render_conversation(conv, resps, deref, hit["gidx"])
+                # 6 元返回（上游 #102 起多了 resp_ok）：末 response 不正常时 wire_md 结尾已显式收口，
+                # 但 meta 也记一份，报告层不必去 grep transcript 才知道「最终回复不可核」。
+                _, _, _, _, resp_ok, wire_md = pull_wire.render_conversation(conv, resps, deref, hit["gidx"])
+                meta["wire_last_response_ok"] = resp_ok
                 prepped = prep_conversation.merge_browser_evidence(wire_md, turns)
                 with open(os.path.join(args.out, "prepped.md"), "w", encoding="utf-8") as f:
                     f.write(prepped)

package/AGENTS.md

@@ -7,7 +7,7 @@ This repository provides shared development skills and CLI helpers for Optima en
 Prefer the installed CLI tools over reimplementing long shell workflows:
 
 - `optima-query-db <service> "<sql>" [environment]`
-- `optima-show-env <service> <stage|prod> [options]`
+- `optima-show-env <service> <stage|prod|cn-prod|cn-stage> [options]`
 - `optima-generate-test-token [options]`
 - `optima-grant-subscription <email> [options]`
 - `optima-grant-credits <email|phone|userId> --credits <n> [options]`

package/bin/cli.js

@@ -32,8 +32,8 @@ switch (command) {
     log('Available Commands:', 'yellow');
     log('  optima-query-db <service> "<sql>" [env]              Query database', 'cyan');
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
-    log('  optima-verify-health <service> [--env cn|prod|all]   Probe L1-L5 上线健康', 'cyan');
-    log('  optima-generate-test-token [--env production]        Generate test token', 'cyan');
+    log('  optima-verify-health <service> [--env stage|prod|cn-prod|cn-stage|all]  Probe L1-L5 上线健康', 'cyan');
+    log('  optima-generate-test-token [--env ci|stage|prod|cn-prod|cn-stage]       Generate test token', 'cyan');
     log('  optima-grant-credits <email|phone|userId> --credits <n> [--env] Grant credits (bonus, 30d)', 'cyan');
     log('  optima-grant-subscription <email|phone|userId> --plan <p> [--env] Grant subscription', 'cyan');
     log('  optima-logs <service> [--env] [--since] [--grep] [-n]  View logs (cn=SLS 直连/aws=CloudWatch)', 'cyan');
@@ -41,7 +41,7 @@ switch (command) {
     log('  /restart-ecs <service> [env]                         Restart ECS service (skill)', 'cyan');
 
     log('\nSupported Services:', 'yellow');
-    log('  commerce-backend  user-auth  mcp-host  agentic-chat  optima-logistics', 'cyan');
+    log('  commerce-backend  user-auth  agentic-chat  optima-logistics', 'cyan');
     log('  session-gateway  optima-scout  billing  browser-backend  optima-generation', 'cyan');
 
     log('\nEnvironments:', 'yellow');

package/bin/helpers/billing-http.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { fetchInfisicalSecret } from './infisical-secrets';
 import { getInfisicalConfig, getInfisicalToken, getCnInfisicalToken, getCnSecrets, resolveUserId } from './db-utils';
 
@@ -149,8 +149,17 @@ export function getServiceToken(env: string, scope?: string): string {
   const effectiveScope = scope ?? (isCn ? CN_PROD_TOKEN_SCOPE : undefined);
   const scopeParam = effectiveScope ? `&scope=${encodeURIComponent(effectiveScope)}` : '';
   const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
-  const response = execSync(
-    `curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`,
+  // execFileSync + 参数数组（不经 shell）：Windows cmd.exe 不认单引号，shell 拼出的
+  // `-d '${body}'` 会被拆碎、curl 收到垃圾参数直接退出（#92）。数组传参绕开 shell、
+  // 跨平台一致；函数保持同步。
+  const response = execFileSync(
+    'curl',
+    [
+      '-s', '-X', 'POST',
+      `${authUrl}/api/v1/oauth/token`,
+      '-H', 'Content-Type: application/x-www-form-urlencoded',
+      '-d', body,
+    ],
     { encoding: 'utf-8' },
   );
 

package/bin/helpers/db-utils.ts

@@ -81,11 +81,14 @@ export function getInfisicalConfig(): InfisicalConfig {
 }
 
 export function getInfisicalToken(config: InfisicalConfig): string {
-  const response = execSync(
-    `curl -s -X POST "${config.url}/api/v1/auth/universal-auth/login" -H "Content-Type: application/json" -d '{"clientId": "${config.clientId}", "clientSecret": "${config.clientSecret}"}'`,
-    { encoding: 'utf-8' }
-  );
-  return JSON.parse(response).accessToken;
+  // 复用 curlJson（execFileSync + 参数数组、不经 shell）：Windows cmd.exe 不认单引号，
+  // 原来 shell 拼的 `-d '{...}'` JSON body 会被拆碎、curl 收垃圾参数直接退出（#92）。
+  // cn 路径早已用 curlJson，这里对齐；函数保持同步（调用方无需改 async）。
+  return curlJson([
+    '-X', 'POST', `${config.url}/api/v1/auth/universal-auth/login`,
+    '-H', 'Content-Type: application/json',
+    '-d', JSON.stringify({ clientId: config.clientId, clientSecret: config.clientSecret }),
+  ]).accessToken;
 }
 
 export function getInfisicalSecrets(config: InfisicalConfig, token: string, environment: string, secretPath: string): Record<string, string> {

package/bin/helpers/entitlement/grant.ts

@@ -1,12 +1,14 @@
 import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 import { resolveTargetUser } from '../grant-subscription';
+import { operatorActorId } from '../operator';
 
 interface GrantArgs {
   identifier: string;
   productKey: string;
   justification: string;
   yes: boolean;
+  operator?: string;
   env: string;
 }
 
@@ -21,6 +23,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
@@ -35,6 +38,7 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
       case '--product-key': out.productKey = next; i++; break;
       case '--justification': out.justification = next; i++; break;
       case '--yes': out.yes = true; break;
+      case '--operator': out.operator = next; i++; break;
       case '--env': out.env = next; i++; break;
       default:
         if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
@@ -67,6 +71,7 @@ export async function runGrant(argv: string[]): Promise<void> {
     userId,
     productKey: args.productKey,
     justification: args.justification,
+    actorUserId: operatorActorId(args.operator ?? null),
   });
   console.log(`✓ Granted entitlement (HTTP ${res.status}):`);
   console.log(JSON.stringify(res.body, null, 2));

package/bin/helpers/entitlement/revoke.ts

@@ -1,12 +1,14 @@
 import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 import { resolveTargetUser } from '../grant-subscription';
+import { operatorActorId } from '../operator';
 
 interface RevokeArgs {
   identifier: string;
   productKey: string;
   reason: string;
   yes: boolean;
+  operator?: string;
   env: string;
 }
 
@@ -28,6 +30,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
@@ -43,6 +46,7 @@ error pointing to the right reversal flow.`);
       case '--product-key': out.productKey = next; i++; break;
       case '--reason': out.reason = next; i++; break;
       case '--yes': out.yes = true; break;
+      case '--operator': out.operator = next; i++; break;
       case '--env': out.env = next; i++; break;
       default:
         if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
@@ -111,6 +115,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
     entitlementId: target.id,
     refundReason: args.reason,
     refundAmountCents: 0,
+    actorUserId: operatorActorId(args.operator ?? null),
   });
   console.log(`✓ Revoked entitlement (HTTP ${res.status}):`);
   console.log(JSON.stringify(res.body, null, 2));

package/bin/helpers/generate-test-token.ts

@@ -88,6 +88,41 @@ async function httpRequest<T>(url: string, options: RequestInit = {}): Promise<T
   return response.json() as Promise<T>;
 }
 
+/**
+ * 判定「账号/商户已存在」——吃 httpRequest 抛出的 `HTTP <status>: <body>` message。
+ *
+ * 两条腿各自对应一个真实来源（user-auth / commerce-backend 是同一套代码跑在 AWS 与
+ * cn 两侧，响应形态一致；下列均为 2026-08-13 直查 origin/main 坐实）：
+ *
+ * - **文案腿** `^HTTP 4xx` 且 `already (exists|registered)`
+ *   · user-auth 注册已注册邮箱 → 400 "Email already registered"
+ *     （user-auth `app/services/user.py`）。**这就是 #78 的病灶**：旧判定只认
+ *     "already exists"，措辞对不上 ⇒ cn 侧 `--email` 复用已有账号必挂。
+ *     实测 cn-prod 响应体：{"error":"Email already registered","status_code":400}
+ *   · commerce-backend 重复建 merchant profile → 400 "Merchant profile already
+ *     exists. Use PUT ..."（commerce-backend `src/api/merchants.py`）
+ *   · 🔴 必须同时是 4xx：5xx 是服务端故障，body 里恰好带着这些词也不能吞 —— 否则
+ *     `POST /api/merchants/me` 的 502/503 会被报成 ℹ already exists，一路打印到
+ *     「✅ Test token generated successfully!」+ Merchant ID: N/A、exit 0。
+ * - **状态码腿** `^HTTP 409`
+ *   · 本工具只调 `POST /api/v1/auth/register/merchant` 与 `POST /api/merchants/me`
+ *     两个端点。**register/merchant 这条路径上唯一的 409** 是企业席位：
+ *     account_type == ENTERPRISE_SEAT → 409 detail "email_bound_to_seat"。
+ *     🔴 **该文案既不含 exists 也不含 registered，所以这条腿不是历史遗留、
+ *     是席位场景的唯一命中路径，别删。**
+ *     ⚠️ 「这条路径上唯一」的限定不是废话：user-auth 全仓有 20+ 处 409
+ *     （referral / internal-sms / teams / admin），措辞各异且语义完全不同
+ *     （如 `claim_in_progress` 是并发冲突）。给本工具接新端点时别想当然沿用本判定，
+ *     否则会把并发冲突静默吞成「已存在」。
+ *
+ * 锚 `^HTTP 409` 而不是 issue 建议的 `\b(409|400)\b`：后者会把 body 里夹带的数字当
+ * 状态码，把真故障（500 而 body 里提到 409）静默吞成「已存在」；而 400 本身太泛
+ * （参数校验失败也是 400），单凭它放行等于吞掉一切请求错误 —— 400 一律交给文案腿判。
+ */
+export function isAlreadyExistsError(message: string): boolean {
+  return /^HTTP 409\b/.test(message) || (/^HTTP 4\d\d\b/.test(message) && /already (exists|registered)/i.test(message));
+}
+
 async function registerMerchant(
   email: string,
   password: string,
@@ -112,7 +147,7 @@ async function registerMerchant(
     console.log(`✓ Merchant registered successfully (ID: ${result.user_id ?? (result as any).id})`);
     return result;
   } catch (error: any) {
-    if (error.message.includes('409') || error.message.includes('already exists')) {
+    if (isAlreadyExistsError(error.message)) {
       console.log(`ℹ Merchant already exists, proceeding to login...`);
       return { email, user_id: '', role: 'merchant', is_active: true, created_at: '', updated_at: '' };
     }
@@ -167,7 +202,7 @@ async function setupMerchantProfile(token: string, businessName: string, config:
     console.log(`✓ Merchant profile setup complete (ID: ${result.merchant_id})`);
     return result;
   } catch (error: any) {
-    if (error.message.includes('409') || error.message.includes('already exists')) {
+    if (isAlreadyExistsError(error.message)) {
       console.log(`ℹ Merchant profile already exists`);
       return { merchant_id: '', business_name: businessName, user_id: '' };
     }
@@ -311,4 +346,6 @@ Example:
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}

package/bin/helpers/grant-credits.ts

@@ -10,6 +10,7 @@
 import { basename } from 'path';
 import { randomUUID } from 'crypto';
 import { callBilling, validateEnvCnProd } from './billing-http';
+import { operatorActorId } from './operator';
 import { resolveTargetUser } from './grant-subscription';
 
 const CREDITS_PER_USD = 700;
@@ -19,6 +20,7 @@ interface Parsed {
   credits: number | null;
   amountUsd: number | null;
   description: string | null;
+  operator: string | null;
   env: string;
 }
 
@@ -36,6 +38,7 @@ Options:
   --credits <n>         Credits to grant (integer >= 1). Primary unit.
   --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
   --description <text>  Description for audit trail (optional)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help            Show this help
 
@@ -50,12 +53,14 @@ Examples:
   let credits: number | null = null;
   let amountUsd: number | null = null;
   let description: string | null = null;
+  let operator: string | null = null;
   let env = 'stage';
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--credits' && args[i + 1]) { credits = parseInt(args[++i], 10); }
     else if (args[i] === '--amount' && args[i + 1]) { amountUsd = parseFloat(args[++i]); }
     else if (args[i] === '--description' && args[i + 1]) { description = args[++i]; }
+    else if (args[i] === '--operator' && args[i + 1]) { operator = args[++i]; }
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
@@ -74,7 +79,7 @@ Examples:
   }
   validateEnvCnProd(env);
 
-  return { identifier, credits, amountUsd, description, env };
+  return { identifier, credits, amountUsd, description, operator, env };
 }
 
 async function main() {
@@ -83,7 +88,7 @@ async function main() {
     console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
   }
 
-  const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+  const { identifier, credits, amountUsd, description, operator, env } = parseArgs(process.argv.slice(2));
 
   const creditsDisplay = credits ?? Math.round((amountUsd as number) * CREDITS_PER_USD);
   console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
@@ -105,6 +110,7 @@ async function main() {
       userId,
       ...amountField,
       description: description ?? undefined,
+      actorUserId: operatorActorId(operator),
       idempotencyKey: `dev-skills-grant:${randomUUID()}`,
     },
   );

package/bin/helpers/grant-subscription.ts

@@ -11,6 +11,7 @@ import {
   getUserById,
   validateEnvCnProd,
 } from './billing-http';
+import { operatorActorId } from './operator';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -76,7 +77,7 @@ const PLANS_BY_ENV: Record<string, string[]> = {
   'cn-stage': ['trial', 'starter', 'pro', 'enterprise', 'free'],
 };
 
-function parseArgs(args: string[]): { identifier: string; plan: string; months: number; env: string } {
+function parseArgs(args: string[]): { identifier: string; plan: string; months: number; operator: string | null; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     console.log(`Usage: optima-grant-subscription <email|phone|userId> [options]
 
@@ -85,6 +86,7 @@ Options:
                     cn-prod/cn-stage additionally allow: free
                     (legacy *-cn ids are accepted and normalized to canonical)
   --months <n>      Duration in months (default: 1)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>       Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help        Show this help`);
     process.exit(0);
@@ -93,11 +95,13 @@ Options:
   const identifier = args[0];
   let plan: string | null = null;
   let months = 1;
+  let operator: string | null = null;
   let env = 'stage';
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--plan' && args[i + 1]) { plan = args[++i]; }
     else if (args[i] === '--months' && args[i + 1]) { months = parseInt(args[++i], 10); }
+    else if (args[i] === '--operator' && args[i + 1]) { operator = args[++i]; }
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
@@ -113,7 +117,7 @@ Options:
   }
   if (months < 1) { console.error('Months must be >= 1'); process.exit(1); }
 
-  return { identifier, plan, months, env };
+  return { identifier, plan, months, operator, env };
 }
 
 /**
@@ -181,7 +185,7 @@ export async function resolveTargetUser(
 }
 
 async function main() {
-  const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
+  const { identifier, plan, months, operator, env } = parseArgs(process.argv.slice(2));
 
   console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${classifyIdentifier(identifier)}) for ${months} month(s) [${env.toUpperCase()}]\n`);
 
@@ -198,7 +202,7 @@ async function main() {
     weeklyTokenLimit: number;
     expiresAt: string;
     warning?: string;
-  }>(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months });
+  }>(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months, actorUserId: operatorActorId(operator) });
 
   console.log(`✓ Subscription ${body.subscriptionId} (${body.planId})`);
   console.log(`✓ Credits: ${body.credits.toLocaleString()} (expires ${body.expiresAt})`);

package/bin/helpers/operator.ts

@@ -0,0 +1,9 @@
+import { userInfo } from 'os';
+
+// #429（Owner 拍板 3）：CLI 发放族自报操作者——informational，billing 信任 allowlist client
+// 自述（actor 不参与授权）；不带 --operator 时回退本机用户名。缺省链最终兜底在 billing
+// 侧（channel=client_id）。格式：dev-skills:<name>。
+export function operatorActorId(operatorFlag?: string | null): string {
+  const name = (operatorFlag ?? '').trim() || userInfo().username;
+  return `dev-skills:${name}`;
+}