@yangdcm/dsh-expert-team 1.1.0

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# @yangdcm/dsh-expert-team bundle patch.
+# Applied as a loader patch layer over the profile's composed tree. This bundle
+# contributes only HOST-plane rows (no agent-plane tool rows — those stay behind
+# the preset the session runs; the `standard` preset already exposes the
+# subagent/workflow/ralph/skill tools the team drives through).
+#
+# The team's orchestration brain is NOT code: it is the `expert-team` SKILL,
+# which the `/team` command copies into $DSH_HOME/skills (discovered by the
+# preset's `skill-filesystem`) and which the model loads via the `skill` tool.
+
+- insert:
+    # Host-plane command: `/team <task>` scaffolds the shared workspace run and
+    # enqueues one model-visible message that launches the team through the
+    # expert-team skill. Registered once, available to every session's `/` UI.
+    - id: expert-team-command
+      name: '@yangdcm/dsh-expert-team/command'
+
+    # Client-discovery marker row: dsh-client-modules scans Loader entries whose
+    # name is an EXACT package specifier for a `dsh.client` declaration. The
+    # command row above is a subpath (`.../command`), which the scanner skips, so
+    # we add a bundle-root row (exact `@yangdcm/dsh-expert-team`) that loads the
+    # inert `index` module purely so the live client overlay gets discovered.
+    - id: expert-team-bundle
+      name: '@yangdcm/dsh-expert-team'

package/lib/artifact-writer.js

@@ -0,0 +1,379 @@
+// 工件写入的**单一受控入口**（批 2-1 · L2-3 · 2-2 的共同载体）
+//
+// 为什么需要它（来自 ROI-REVIEW 的架构仲裁）：
+//   · 宿主**早就有**文件级 CAS：`@deepseek-ai/dsh-fs` 的
+//     `FsWriteIntent = {kind:'createIfAbsent'} | {kind:'replaceIfVersion', version}` 与
+//     `writeText(target, content, expected?)`，provider 在版本失配时报 `FS_STALE_VERSION`；
+//     `dsh-fs-observation-policy` 已挂在 `dsh-base`。
+//   · 而我方 `lib/command.js` 用 `node:fs/promises` **直写 30+ 处**，**绕过了这把现成的栅栏**。
+//   · ⇒ 所以「跨会话写仲裁」不是宿主级大工程，而是**我方写入路径的改造**。
+//
+// 本模块把改造所需的四件事收进一个入口，避免各写点各写一套：
+//   ① 版本栅栏（expected version → replaceIfVersion；失配走重试而非静默覆盖）
+//   ② **陈旧重试**（重读 → 重新基线 → 重试一次 → 仍失败才上抛）
+//      —— 缺这条时，加栅栏的净效果只是"把静默丢更新换成用户可见的失败"，属降级。
+//   ③ **范围硬排除**（L2-3）：默认禁写区一律拒绝，且**不是告警而是拒绝**
+//   ④ revision 记账：写入即自增，读到回退/跳变即 loud（拦不住 lead 用 write 工具直写，
+//      但能把"被别人改过"这件事变成可见事实）
+//
+// 设计约束：**不 import 任何宿主包**，只依赖注入的 `fsPort`，因此既能在宿主里跑（注入 `ctx.fs`），
+// 也能在纯 Node 测试里跑（注入本文件提供的 `nodeFsPort()`）。
+//
+// ⚠️ 一个真实陷阱（架构师实测）：`fs/write-intent` 是**工具层**（`dsh-tool-fs`）dispatch 的，
+//    **不是** `ctx.fs` 服务 dispatch 的。所以直连 `ctx.fs.writeText` 时**必须自己传 `expected`**，
+//    不能指望 intent 监听器替你算。
+
+import { readFile as nodeReadFile, writeFile as nodeWriteFile, stat as nodeStat, unlink as nodeUnlink } from 'node:fs/promises';
+
+/** 默认禁写区（L2-3）：密钥/凭据/版本库元数据/宿主配置 —— 命中即拒绝，不给"仅告警"的余地。 */
+export const DEFAULT_EXCLUSIONS = [
+  /(^|\/)\.env(\.|$)/i,
+  /(^|\/)\.git(\/|$)/i,
+  /(^|\/)\.ssh(\/|$)/i,
+  /(^|\/)id_(rsa|ed25519|ecdsa)$/i,
+  /(^|\/)\.npmrc$/i,
+  /(^|\/)\.netrc$/i,
+  /(^|\/)credentials(\.json)?$/i,
+  /(^|\/)secrets?(\/|$)/i,
+];
+
+/** 判断路径是否命中禁写区；返回命中的规则（无则 null）。 */
+export function scopeViolation(target, exclusions = DEFAULT_EXCLUSIONS) {
+  const p = String(target || '');
+  for (const re of exclusions) if (re.test(p)) return String(re);
+  return null;
+}
+
+/** 从文本里取出 revision（JSON 对象且含数字 revision 时）；取不到返回 null。 */
+export function readRevision(text) {
+  try {
+    const o = JSON.parse(text);
+    if (o && typeof o === 'object' && Number.isSafeInteger(o.revision)) return o.revision;
+  } catch { /* 非 JSON */ }
+  return null;
+}
+
+/**
+ * 纯 Node 的 fsPort（测试与"宿主不可用时的回退"用）。
+ * 它**自己实现**版本栅栏语义，以复现宿主 `replaceIfVersion` 的行为：
+ * `statVersion` 给出版本指纹，`writeText` 在 `intent.kind==='replaceIfVersion'` 且版本不符时抛 `FS_STALE_VERSION`。
+ */
+export function nodeFsPort() {
+  const versionOf = async (p) => {
+    try {
+      const st = await nodeStat(p);
+      return `${st.size}:${st.mtimeMs}`;
+    } catch {
+      return null; // 不存在
+    }
+  };
+  return {
+    kind: 'node:fs',
+    async readText(p) {
+      try { return await nodeReadFile(p, 'utf8'); } catch { return null; }
+    },
+    async statVersion(p) { return versionOf(p); },
+    async writeText(p, content, intent) {
+      if (intent && intent.kind === 'replaceIfVersion') {
+        const cur = await versionOf(p);
+        if (cur !== intent.version) {
+          const err = new Error(`FS_STALE_VERSION: ${p}`);
+          err.code = 'FS_STALE_VERSION';
+          throw err;
+        }
+      }
+      await nodeWriteFile(p, content);
+    },
+  };
+}
+
+/**
+ * 把宿主的 `ctx.fs` 适配成 fsPort。
+ * 注意 `expected` 必须由调用方给出（见文件头陷阱说明）。
+ */
+export function cordisFsPort(ctxFs) {
+  return {
+    kind: 'ctx.fs',
+    async readText(p) {
+      const t = await ctxFs.resolve(p);
+      try { return await ctxFs.readText(t); } catch { return null; }
+    },
+    async statVersion(p) {
+      try {
+        const t = await ctxFs.resolve(p);
+        const st = await ctxFs.stat(t);
+        return st && st.version != null ? String(st.version) : null;
+      } catch {
+        return null;
+      }
+    },
+    async writeText(p, content, intent) {
+      const t = await ctxFs.resolve(p);
+      return ctxFs.writeText(t, content, intent);
+    },
+  };
+}
+
+/**
+ * 内建 schema 告警（批 2-4 · L1-4′）。
+ *
+ * **只告警、不硬拒** —— 刻意如此：`listRuns` 对不合规的 STATE.json 是 catch 后静默跳过，
+ * 若写入侧硬拒，旧 run 会从 `/team status` 与浮层里**静默消失**，比"容忍脏数据"更糟。
+ *
+ * 它要修的是一类**已被实证的静默伤害**：本 run 自己的 `STATE.coverage` 曾被写成
+ * **角色名字符串数组**（`["pm","architect",…]`），而消费端用
+ * `Array.isArray(state.coverage) ? state.coverage : []` 兜底 ⇒ 渲染成一串空行，
+ * **生产端违约 + 消费端静默吞**，没有任何人被告知。
+ *
+ * 每个 guard 返回 `warnings: string[]`（空数组 = 合规），由 write() 经 `schema-warn` 事件上报。
+ */
+export const DEFAULT_SCHEMA_GUARDS = {
+  'STATE.json': (v) => {
+    const w = [];
+    if (v.coverage !== undefined) {
+      if (!Array.isArray(v.coverage)) w.push('coverage 应为数组（schema: [{constraint, tasks}]）');
+      else if (v.coverage.some((c) => c === null || typeof c !== 'object' || Array.isArray(c))) {
+        w.push('coverage 的元素应为对象 {constraint, tasks}；检测到非对象元素（下游会静默兜底并渲染空行）');
+      }
+    }
+    if (v.members !== undefined && !Array.isArray(v.members)) w.push('members 应为数组');
+    if (v.phase !== undefined && typeof v.phase !== 'string') w.push('phase 应为字符串');
+    if (v.status !== undefined && typeof v.status !== 'string') w.push('status 应为字符串');
+    if (v.planDiscarded !== undefined && (v.planDiscarded === null || typeof v.planDiscarded !== 'object')) {
+      w.push('planDiscarded 应为对象 {at, reason, goalKey}');
+    }
+    return w;
+  },
+  'TASKS.json': (v) => {
+    const w = [];
+    if (!Array.isArray(v.tasks)) w.push('tasks 应为数组');
+    else if (v.tasks.some((t) => t === null || typeof t !== 'object' || Array.isArray(t) || typeof t.id !== 'string' || !t.id)) {
+      w.push('tasks 的元素应为对象且带非空字符串 id');
+    }
+    return w;
+  },
+};
+
+/**
+ * 创建受控写入器。
+ * @param fsPort       注入口（`nodeFsPort()` 或 `cordisFsPort(ctx.fs)`）
+ * @param exclusions   禁写区规则（默认 DEFAULT_EXCLUSIONS）
+ * @param onEvent      可选事件回调（用于把重试/拒绝/schema 告警写进 RUN.log）
+ * @param schemaGuards 按**文件名**匹配的 schema 告警器（默认 DEFAULT_SCHEMA_GUARDS）；只告警不阻断
+ * @param identity     写入者身份（`() => ({sessionId, runId, role})` 或对象）；用于**归因**（批 2-3 · L1-3′）
+ */
+export function createArtifactWriter({ fsPort, exclusions = DEFAULT_EXCLUSIONS, onEvent = () => {}, schemaGuards = DEFAULT_SCHEMA_GUARDS, identity = null } = {}) {
+  if (!fsPort) throw new Error('createArtifactWriter 需要 fsPort');
+
+  /**
+   * 归因（批 2-3 · L1-3′）：直接闭合 ROI 评审里的
+   * **R-3「漂移不可归因：只能证明文件被改写，不能证明写入进程身份」**。
+   *
+   * 做法：
+   *   · 对象工件写入时附带 `_provenance = { writer, at }`（writer 来自 identity）；
+   *   · 每次写入前读回磁盘上的 `revision` 与 `_provenance.writer`：
+   *       - **revision 比本进程上次写的更小** ⇒ `revision-regression`（有人把文件回退了）
+   *       - **writer 与本进程身份不同** ⇒ `writer-changed`（别的写者动过）
+   *   · 两者都**只上报、不阻断**（与 schema 告警同一取向：宁可响亮，不要静默，但不要因此让 run 失败）。
+   *
+   * 注意：本进程内记忆（`lastWritten`）只覆盖**本进程**写过的目标；跨进程回退无法可靠判定
+   * ——所以 writer 变化才是跨进程归因的主要信号。
+   */
+  const lastWritten = new Map(); // target -> 本进程最后写入的 revision
+
+  // ── C1：跨进程互斥（advisory lock）─────────────────────────────────────
+  // 为什么需要：本进程内的 `revision`/`lastWritten` 只覆盖**本进程**；实测场景是**另一个 dsh
+  // 会话持续改写同一个工件**（两个进程各自有自己的 ARTIFACT 实例，互不感知）。
+  // 版本栅栏能拦住"别人已写完"，但拦不住"别人**正在**写" ⇒ 两个进程可以同时读到 rev N、
+  // 各自写、后写覆盖先写。这把**写入点**用一个 `<target>.etv-lock` 文件序列化：
+  //   · 拿不到锁 ⇒ 等待并重试（默认最多 ~5s），**不**静默覆盖；
+  //   · 锁文件超过 staleMs（默认 30s）视为"写者已死"⇒ 接管（进程崩溃不会永久死锁）；
+  //   · 超时仍拿不到 ⇒ 抛 `WRITE_LOCK_TIMEOUT`，让调用方知道"有别的写者在写"。
+  // 只锁**写入**，不锁读 —— 读不加锁，CAS 在写侧兜底（重试时重新基线）。
+  const WRITE_LOCK_STALE_MS = 30000;
+  const WRITE_LOCK_TIMEOUT_MS = 5000;
+  async function acquireWriteLock(target, { timeoutMs = WRITE_LOCK_TIMEOUT_MS, staleMs = WRITE_LOCK_STALE_MS } = {}) {
+    const lockPath = `${target}.etv-lock`;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      try {
+        await nodeWriteFile(lockPath, `${process.pid} ${Date.now()}`, { flag: 'wx' });
+        return { release: async () => { try { await nodeUnlink(lockPath); } catch { /* 已被别人接管 */ } } };
+      } catch (e) {
+        if (!e || e.code !== 'EEXIST') throw e;
+        try {
+          const st = await nodeStat(lockPath);
+          if (Date.now() - st.mtimeMs > staleMs) { try { await nodeUnlink(lockPath); } catch { /* best-effort */ } continue; }
+        } catch { continue; } // 读完就没了，重试
+        if (Date.now() > deadline) {
+          const err = new Error(`WRITE_LOCK_TIMEOUT: ${target}（超过 ${timeoutMs}ms 拿不到写锁 ⇒ 有别的写者正在写）`);
+          err.code = 'WRITE_LOCK_TIMEOUT';
+          throw err;
+        }
+        await new Promise((r) => setTimeout(r, 40));
+      }
+    }
+  }
+  const identityOf = () => {
+    try {
+      const id = typeof identity === 'function' ? identity() : identity;
+      return id && typeof id === 'object' ? id : null;
+    } catch {
+      return null;
+    }
+  };
+  const identityKey = () => {
+    const id = identityOf();
+    if (!id) return null;
+    return [id.sessionId || '', id.runId || '', id.role || ''].join('|');
+  };
+
+  /**
+   * 写入一个工件。
+   * @param target            目标路径
+   * @param content           字符串（原样写）或对象（会被 JSON 序列化，并自动维护 revision）
+   * @param expectedRevision  调用方认为的当前 revision；不符则走"重读→重基线→重试一次"
+   * @param maxAttempts       含首次的总尝试次数（默认 2 = 首次 + 重试一次）
+   * @returns {ok, revision, attempts, error?, code?, violation?, schemaWarnings?, provenance?}
+   */
+  async function write(target, content, { expectedRevision = null, maxAttempts = 2 } = {}) {
+    // ① 范围硬排除：先拦，不进入任何 IO
+    const violation = scopeViolation(target, exclusions);
+    if (violation) {
+      onEvent({ type: 'scope-denied', target, rule: violation });
+      return { ok: false, code: 'SCOPE_DENIED', violation, error: `拒绝写入禁写区（命中规则 ${violation}）：${target}` };
+    }
+
+    // C1：写入前持**跨进程锁**。CAS 能拦住"别人已写完"，拦不住"别人**正在**写"；
+    // 这里把写入序列化，让两个进程不会在同一窗口里同时 read-modify-write。
+    // 锁是 advisory 的：死锁由 staleMs 兜底（进程崩了别人也能接管），不会永久卡死。
+    // ⚠️ 只有真实的**本地文件系统**才锁：cordisFsPort 的 `resolve` 会把目标解析成
+    // `host://` 前缀（宿主虚拟路径），而锁用 nodeWriteFile 写的是**真实磁盘文件** —
+    // 在 cordis 路径上锁路径根本不存在，会让写入直接 ENOENT（此时锁由宿主版本栅栏兜底）。
+    const useLock = fsPort && fsPort.kind === 'node:fs';
+    if (!useLock) return writeOnce(target, content, { expectedRevision, maxAttempts });
+    const lock = await acquireWriteLock(target).catch((e) => {
+      // 拿不到锁（包括超时）不应让整个进程抛错 —— 把它变成写失败的**返回**，
+      // 与 write() 的其余失败形态（{ok:false, code}）一致，让调用方能正常处理。
+      return { lockError: e };
+    });
+    if (lock.lockError) {
+      const code = lock.lockError && lock.lockError.code === 'WRITE_LOCK_TIMEOUT' ? 'WRITE_LOCK_TIMEOUT' : 'LOCK_FAILED';
+      return { ok: false, code, error: String((lock.lockError && lock.lockError.message) || lock.lockError) };
+    }
+    try {
+      return await writeOnce(target, content, { expectedRevision, maxAttempts });
+    } finally {
+      await lock.release();
+    }
+  }
+
+  async function writeOnce(target, content, { expectedRevision = null, maxAttempts = 2 } = {}) {
+    // ⚠️ 只有**纯对象**才走"JSON 序列化 + revision + 归因"路径。
+    // 曾经的写法是 `typeof content === 'object'` —— 但 **Buffer / Uint8Array / Array 也是 object**，
+    // 于是模板拷贝（`readFile(url)` 不带编码返回 Buffer）会被 `{...buffer}` 展开成
+    // `{"0":123,"1":10,…}` 的字节表，**把模板文件写坏**（第 7 轮迁移时引入，第 12 轮由 schema 告警抓出）。
+    const isBufferLike = (typeof Buffer !== 'undefined' && Buffer.isBuffer(content)) || content instanceof Uint8Array;
+    const isObject = content !== null && typeof content === 'object' && !Array.isArray(content) && !isBufferLike;
+    let attempts = 0;
+    let lastErr = null;
+
+    for (let i = 0; i < Math.max(1, maxAttempts); i += 1) {
+      attempts += 1;
+      try {
+        // ② 读当前状态：版本指纹 + revision
+        const version = await fsPort.statVersion(target);
+        const currentText = await fsPort.readText(target);
+        const currentRev = readRevision(currentText);
+
+        // ③ revision 前置条件：只在**调用方显式声明**时才校验（避免首次创建时误报）
+        if (expectedRevision !== null && currentRev !== null && currentRev !== expectedRevision) {
+          onEvent({ type: 'revision-stale', target, expected: expectedRevision, actual: currentRev, attempt: attempts });
+          lastErr = Object.assign(new Error(`REVISION_STALE: ${target} 期望 ${expectedRevision} 实际 ${currentRev}`), { code: 'REVISION_STALE' });
+          continue; // 重读重试（下一轮会拿到新的 currentRev）
+        }
+
+        // ④ 组装内容：对象则自增 revision，并附带**归因**（批 2-3 · L1-3′）
+        let payload;
+        let nextRev = null;
+        let provenance = null;
+        if (isObject) {
+          nextRev = (currentRev === null ? 1 : currentRev + 1);
+          const me = identityKey();
+          // 归因检测（只上报、不阻断）：
+          //  · revision 回退：磁盘 revision 比本进程上次写的更小 ⇒ 有人把文件回退了
+          //  · writer 变化：磁盘上的 writer 与本进程身份不同 ⇒ 别的写者动过
+          const prevWritten = lastWritten.get(target);
+          if (prevWritten !== undefined && currentRev !== null && currentRev < prevWritten) {
+            onEvent({ type: 'revision-regression', target, lastWritten: prevWritten, onDisk: currentRev });
+          }
+          let onDiskWriter = null;
+          if (currentText) {
+            try { onDiskWriter = (JSON.parse(currentText) || {})._provenance?.writer ?? null; } catch { onDiskWriter = null; }
+          }
+          if (me && onDiskWriter && onDiskWriter !== me) {
+            onEvent({ type: 'writer-changed', target, onDiskWriter, me });
+          }
+          provenance = (me || onDiskWriter) ? { writer: me || onDiskWriter, at: new Date().toISOString() } : null;
+          const base = provenance ? { ...content, _provenance: provenance, revision: nextRev } : { ...content, revision: nextRev };
+          payload = JSON.stringify(base, null, 2) + '\n';
+        } else {
+          payload = String(content);
+        }
+
+        // ⑤ 版本栅栏写入
+        const intent = version === null ? { kind: 'createIfAbsent' } : { kind: 'replaceIfVersion', version };
+        await fsPort.writeText(target, payload, intent);
+        if (attempts > 1) onEvent({ type: 'write-retried', target, attempts });
+        // ⑤′ schema 告警（批 2-4 · L1-4′）：**写完才报、绝不阻断** —— 保证旧 run 不会因不合规而消失
+        const guard = isObject ? schemaGuards[String(target).split('/').pop()] : null;
+        let schemaWarnings = [];
+        if (typeof guard === 'function') {
+          try {
+            schemaWarnings = guard(content) || [];
+          } catch { schemaWarnings = []; }
+          for (const msg of schemaWarnings) onEvent({ type: 'schema-warn', target, message: msg });
+        }
+        // 记住本进程写过的 revision —— 供后续写入检测"回退"（批 2-3 归因）
+        if (isObject && nextRev !== null) lastWritten.set(target, nextRev);
+        return { ok: true, revision: nextRev, attempts, schemaWarnings, provenance };
+      } catch (e) {
+        lastErr = e;
+        const stale = e && (e.code === 'FS_STALE_VERSION' || /FS_STALE_VERSION/.test(String(e.message || '')));
+        onEvent({ type: stale ? 'version-stale' : 'write-error', target, attempt: attempts, error: String(e && e.message) });
+        if (!stale) break; // 非"陈旧"类错误：重试无意义，直接上抛
+      }
+    }
+
+    return {
+      ok: false,
+      code: (lastErr && lastErr.code) || 'WRITE_FAILED',
+      error: String(lastErr && lastErr.message ? lastErr.message : lastErr),
+      attempts,
+    };
+  }
+
+  /** 读取并返回 {text, revision}；文件不存在返回 {text:null, revision:null}。 */
+  async function read(target) {
+    const text = await fsPort.readText(target);
+    return { text, revision: readRevision(text) };
+  }
+
+  /**
+   * 同 `write`，但**失败即抛**。
+   * 迁移既有写入点时用它：原 `writeFile` 失败会抛，若换成不检查返回值的 `write`，
+   * 就会把"写失败"静默成"写成功"。迁移必须保持 loud。
+   */
+  async function must(target, content, opts = {}) {
+    const r = await write(target, content, opts);
+    if (!r.ok) {
+      const err = new Error(`工件写入失败[${r.code}] ${target}：${r.error}`);
+      err.code = r.code;
+      err.violation = r.violation;
+      throw err;
+    }
+    return r;
+  }
+
+  return { write, must, read, fsPort, exclusions, schemaGuards };
+}

package/lib/command-parse.js

@@ -0,0 +1,181 @@
+// 命令解析（B 线第 8 项 · `command-parse.js`）：`/team` 的**整个 CLI 面** —— 用法文本、
+// 命名 profile、以及把一行输入解析成 `{kind, …}` 的 `parseTeamCommand`。
+//
+// 为什么单独成模块：这三样是**同一件事的三面**（有哪些命令 / 命令怎么拼 / 输入怎么解析），
+// 以前散在 5000 行编排器的三处（相隔 150 行），改一条命令要跨好几段找三个地方。
+//
+// 边界：**这里只解析、不执行** —— 不碰 IO、不认识 `ctx`、不调用任何 handler；返回值只是
+// `{kind, …}`，由 `command.js` 的 switch 分发。所以它可以被纯单测（`command-parse.test.mjs`
+// 早就在用 `_live.parseTeamCommand` 做行为断言，这次搬家**一行都不用改**）。
+
+import { DEFAULT_ROLES } from './vocab.js';
+
+// Named multi-role profiles: preset roster + deliverable + a short note the lead reads.
+export const PROFILE_DEFS = {
+  delivery: { roles: DEFAULT_ROLES, deliverable: 'code+artifacts', note: '完整交付：澄清→调研→设计→实现→评审→测试→交付' },
+  review: { roles: ['pm', 'architect', 'researcher', 'reviewer', 'qa'], deliverable: 'artifacts-only', note: '只做设计与代码评审：出 REVIEW/TEST 工件，不改代码' },
+  design: { roles: ['pm', 'architect', 'researcher'], deliverable: 'artifacts-only', note: '只出规格与架构设计：Ultra Spec + 接口契约，不改代码' },
+  refactor: { roles: ['pm', 'architect', 'backend', 'reviewer', 'qa'], deliverable: 'code+artifacts', note: '重构：契约冻结→实现→评审→测试' },
+  research: { roles: ['pm', 'researcher', 'architect'], deliverable: 'artifacts-only', note: '调研：代码定位/依赖/存量约束 + 结论' },
+};
+export function resolveProfile(name, fallback) {
+  const d = PROFILE_DEFS[name];
+  if (!d) return fallback;
+  return { ...fallback, roles: d.roles, deliverable: d.deliverable, profileNote: d.note, profile: name };
+}
+export const USAGE = [
+  'Usage:',
+  '  /team <task>                       一句话组队（一次性，自动组队并交付）',
+  '  /team help                         显示本用法（等价：? / -h / --help）',
+  '  /team --persist <task>             启动持久化活团队（成员可反复指挥，跨会话恢复）',
+  '  /team --no-code <task>             只产出计划/评审/测试工件，不改代码',
+  '  /team --confirm <task>             大需求先确认：建 run 但**不自动派工**，面板点「执行」才开工',
+  '  /team --tier <档位> <task>         指定流程档位：快速档 / 标准档 / 严格档（不写则在浮层三选一，每次都问）',
+  '  /team tier <档位> [--run <run>]    运行中**升档**（快速档→标准档→严格档；不允许降档）',
+  '  /team rule <内容>                  立一条常驻规则（如「改完没问题就提交并推送」）；/team rules 查看',
+  '  /team --roles a,b,c <task>         指定/增补角色（覆盖默认编制）',
+  '  /team --name <runId> <task>        指定 runId（默认由任务文本 + HHMMSS 生成）',
+  '  /team --profile <name> <task>      套用命名模板（delivery|review|design|refactor|research）',
+  '  /team --allow-rebuild <task>       显式解锁「该目标已被丢弃」的自动重建拦截（会记入 RUN.log）',
+  '  ⚠ flags 一律写在 <task> **之前**（后置会被当成任务文本）',
+  '  /team status                       查看所有 run 的阶段、成员与模型计划（⚠违规实时可见）',
+  '  /team models [<run>]               查看每个角色的成本/模型计划（轻=快模型，重=顶配）',
+  '  /team canvas [<run>]               生成该 run 的可视化团队画布 (HTML)',
+  '  /team canvas --watch [<run>]       生成画布并轮询 host 状态接口实时刷新（live 版）',
+  '  /team learn                        聚合所有 run 的日志 → METRICS.md + 蒸馏经验到 LEARNINGS.md',
+  '  /team learn --deep                 再写一份 DEEP-LEARN.md（逐 run 的卡点清单 + 映射到的规则）',
+  '  /team index                        扫描本工程 → team/REPOWIKI.md 项目知识库（供角色检索）',
+  '  /team codeindex                    构建代码索引（符号/词频 → team/CODEINDEX.json，Qoder 式）',
+  '  /team search <关键词>              代码索引秒级搜索（路径 100 > 符号 60 > 高频词 20）',
+  '  /team devcontainer [--write]       生成可复现校验环境配置（按语言选镜像；--write 写入 .devcontainer/）',
+  '  /team migrate <run>                把旧 run 的 TASKS.json 升级到新 schema（启用质量门禁/自动调度）',
+  '  /team check [<run>]                状态机/质量门禁一致性校验（host 强制）',
+  '  /team detail [<run>]               单个 run 运行详情（目标/时间线/产物/首个失败点）',
+  '  /team limit <run> [--max-runs N] [--deadline YYYY-MM-DD] [--clear]  配额：次数/截止（超限后拒绝恢复并提示）',
+  '  /team task <id> <状态> [--run <run>]  快捷回写单任务状态（如 /team task B1 done --note 接口通过）',
+  '  /team resume <run>                 恢复/继续某个 run',
+  '  /team settle [<run>]               清算冷启动后「没人做」的在飞任务（→ pending + attempt+1 + 留痕）',
+  '  /team wait [<run>]                 查看在飞任务进展（不阻塞；无进展超 5 分钟会提示）',
+  '  /team clear [<run>]                清理一个或全部 run',
+].join('\n');
+
+// ── command parsing ────────────────────────────────────────────────────────
+
+export function parseTeamCommand(rawInput) {
+  const input = (rawInput ?? '').trim();
+  if (input.length === 0) return { kind: 'help' };
+  const lower = input.toLowerCase();
+  // ⚠️ `help` 必须有独立分支：旧实现只在**空输入**时返回 help，`/team help` 会穿过所有
+  // 子命令判断、落到最后的 `create` 分支，把 "help" 当成任务文本 ⇒ **建出一个
+  // runId 形如 `help-HHMMSS` 的空 run**。用户一按就中，且几乎不会自己发现。
+  if (lower === 'help' || lower === '?' || lower === '-h' || lower === '--help' || lower === '帮助') return { kind: 'help' };
+  if (lower === 'status') return { kind: 'status' };
+  if (lower === 'members') return { kind: 'members' };
+  if (lower === 'models') return { kind: 'models' };
+  if (lower.startsWith('models ')) return { kind: 'models', run: input.slice(7).trim() };
+  if (lower === 'task') return { kind: 'error', text: 'Usage: /team task <id> <状态> [--run <run>] [--note <原因>]' };
+  if (lower.startsWith('task ')) {
+    const parts = input.slice(5).trim().split(/\s+/);
+    let run = null, note = '';
+    const rest = parts.filter((p) => !p.startsWith('--'));
+    let i = parts.indexOf('--run'); if (i >= 0 && parts[i + 1]) run = parts[i + 1];
+    i = parts.indexOf('--note'); if (i >= 0 && parts[i + 1]) { note = parts.slice(i + 1).join(' '); }
+    return { kind: 'task', id: rest[0] || '', status: (rest[1] || '').toLowerCase(), run, note };
+  }
+  if (lower === 'learn') return { kind: 'learn', deep: false };
+  if (lower.startsWith('learn ')) return { kind: 'learn', deep: /--deep/.test(input) };
+  // G 线：`/team tier <档位> [--run <run>]` —— 只允许**升档**（跑不顺就降级等于用档位掩盖问题）。
+  if (lower === 'tier') return { kind: 'error', text: 'Usage: /team tier <档位> [--run <run>]（档位：快速档 / 标准档 / 严格档；只允许升档）' };
+  if (lower.startsWith('tier ')) {
+    const parts = input.slice(5).trim().split(/\s+/);
+    let run = null;
+    const ri = parts.indexOf('--run'); if (ri >= 0 && parts[ri + 1]) run = parts[ri + 1];
+    const rest = parts.filter((p) => !p.startsWith('--') && p !== run);
+    return { kind: 'tier', tier: rest[0] || '', run };
+  }
+  if (lower === 'board') return { kind: 'board' };
+  if (lower === 'detail') return { kind: 'detail' };
+  if (lower.startsWith('detail ')) return { kind: 'detail', run: input.slice(7).trim() };
+  if (lower === 'limit') return { kind: 'error', text: 'Usage: /team limit <run> --max-runs <N> | --deadline <YYYY-MM-DD> | --clear' };
+  if (lower.startsWith('limit ')) {
+    const parts = input.slice(6).trim().split(/\s+/);
+    let maxRuns = null, deadline = null, clear = false;
+    const rest = [];
+    for (let i = 0; i < parts.length; i++) {
+      if (parts[i] === '--max-runs' && parts[i + 1]) { maxRuns = Number(parts[i + 1]); i++; }
+      else if (parts[i] === '--deadline' && parts[i + 1]) { deadline = parts[i + 1]; i++; }
+      else if (parts[i] === '--clear') clear = true;
+      else rest.push(parts[i]);
+    }
+    return { kind: 'limit', run: rest[0] || '', maxRuns, deadline, clear };
+  }
+  if (lower === 'canvas') return { kind: 'canvas', watch: false };
+  if (lower.startsWith('canvas ')) {
+    const watch = /(^|\s)--watch(\s|$)/.test(input);
+    const run = input.slice(7).replace(/\s*--watch\s*/gi, '').trim();
+    return { kind: 'canvas', run, watch };
+  }
+  if (lower === 'clear') return { kind: 'clear' };
+  if (lower.startsWith('clear ')) return { kind: 'clear', run: input.slice(6).trim() };
+  // L3-2′ 可清算：显式清算冷启动后的搁浅任务（回 pending + attempt+1 + 留痕）
+  if (lower === 'settle') return { kind: 'settle', run: null };
+  if (lower.startsWith('settle ')) return { kind: 'settle', run: input.slice(7).trim() };
+  if (lower === 'index') return { kind: 'index' };
+  if (lower === 'codeindex') return { kind: 'codeindex' };
+  if (lower === 'search') return { kind: 'error', text: 'Usage: /team search <关键词>' };
+  if (lower.startsWith('search ')) return { kind: 'search', kw: input.slice(7).trim() };
+  if (lower === 'devcontainer') return { kind: 'devcontainer', write: false };
+  if (/^devcontainer\s+--write(\s+.*)?$/.test(input)) return { kind: 'devcontainer', write: true };
+  if (lower.startsWith('devcontainer ')) return { kind: 'devcontainer', write: /--write/.test(input) };
+  if (lower === 'check') return { kind: 'check' };
+  if (lower.startsWith('check ')) return { kind: 'check', run: input.slice(6).trim() };
+  if (lower === 'migrate') return { kind: 'error', text: 'Usage: /team migrate <run>' };
+  if (lower.startsWith('migrate ')) return { kind: 'migrate', run: input.slice(8).trim() };
+  if (lower === 'resume') return { kind: 'error', text: 'Usage: /team resume <run>' };
+  if (lower.startsWith('resume ')) return { kind: 'resume', run: input.slice(7).trim() };
+  if (lower === 'wait') return { kind: 'wait', run: '' };
+  if (lower.startsWith('wait ')) return { kind: 'wait', run: input.slice(5).trim() };
+  if (lower === 'rule' || lower === 'rules') return { kind: 'rules', action: 'list', rule: '' };
+  if (lower.startsWith('rule ')) return { kind: 'rules', action: 'add', rule: input.slice(5).trim() };
+  if (lower.startsWith('rules ')) return { kind: 'rules', action: 'add', rule: input.slice(6).trim() };
+
+  // Consume leading flags; everything after the last flag is the task text.
+  const tokens = input.split(/\s+/);
+  let i = 0;
+  let persist = false;
+  let noCode = false;
+  let roles = null;
+  let runName = null;
+  let profile = null;
+  let allowRebuild = false; // 批 0-3：显式解锁「该目标已被用户丢弃」的拦截
+  let confirm = false; // 大需求执行前询问：先建 run + 立待决，**不自动派工**，等用户拍板
+  let tierRaw = null; // G 线：显式 `--tier <快速档|标准档|严格档|quick|standard|strict>`
+  while (i < tokens.length && tokens[i].startsWith('--')) {
+    const flag = tokens[i];
+    if (flag === '--persist') persist = true;
+    else if (flag === '--no-code') noCode = true;
+    else if (flag === '--allow-rebuild') allowRebuild = true;
+    else if (flag.startsWith('--roles')) {
+      const eq = flag.indexOf('=');
+      if (eq >= 0) roles = flag.slice(eq + 1).split(',').map((s) => s.trim()).filter(Boolean);
+      else { i += 1; if (i < tokens.length) roles = tokens[i].split(',').map((s) => s.trim()).filter(Boolean); }
+    } else if (flag.startsWith('--name')) {
+      const eq = flag.indexOf('=');
+      if (eq >= 0) runName = flag.slice(eq + 1).trim();
+      else { i += 1; if (i < tokens.length) runName = tokens[i]; }
+    } else if (flag.startsWith('--profile')) {
+      const eq = flag.indexOf('=');
+      if (eq >= 0) profile = flag.slice(eq + 1).trim();
+      else { i += 1; if (i < tokens.length) profile = tokens[i]; }
+    } else if (flag.startsWith('--tier')) {
+      // 支持 `--tier=quick` 与 `--tier quick` 两种写法（与 --roles/--profile 一致）。
+      const eq = flag.indexOf('=');
+      if (eq >= 0) tierRaw = flag.slice(eq + 1).trim();
+      else { i += 1; if (i < tokens.length) tierRaw = tokens[i].trim(); }
+    } else if (flag === '--confirm') confirm = true;
+    i += 1;
+  }
+  const task = tokens.slice(i).join(' ').trim();
+  if (!task) return { kind: 'help' };
+  return { kind: 'create', task, persist, noCode, roles, runName, profile, allowRebuild, confirm, tierRaw };
+}