dsh-plugin-orchd 0.1.0 → 0.1.1

package/lib/git-times.js

@@ -0,0 +1,240 @@
+/**
+ * 只读 git 时间采集：给看板的默认排序提供「最近动作时间」与「合并时间」。
+ *
+ * 为什么需要它（FR-5.4 修订，2026-10-29）：默认排序改为——
+ *   · 活跃任务（pending / claimed / done / in_review）按「最近一次动作」由近到远；
+ *   · 终态任务（completed / cancelled）按「合并进 main 的时间」由近到远。
+ * 但引擎的 `status --all` 与 `status <id>` **都不返回时间字段**（只有 task_id / name /
+ * status / module / attempt_count / source / claimed_by，外加可选的 review_phase /
+ * revive_marker），唯一带精确时间戳的是账本事件流（`_ledger.sqlite3`），而插件按 A2
+ * 不直读账本。所以这里走 git 侧的两个**近似**来源：
+ *
+ *   ① 活跃任务 → `task/<id>` 分支的 tip 时间。任务还在推进时分支还在（终态回收才会删
+ *      分支与 worktree），tip 提交时间就是「最近一次动作」的最佳近似。
+ *   ② 终态任务 → 主分支上的合并提交时间（`Merge branch 'task/<id>'`）。分支已被回收，
+ *      合并提交是唯一留下的时间戳。
+ *
+ * 两处已知盲区（默认排序把它们兜底到本组最后，**不臆造时间**）：
+ *   · 尚未 claim 的 pending：还没有 `task/<id>` 分支；
+ *   · cancelled：多半从未合并，没有合并提交。squash / 直推进主分支的形态同样拿不到
+ *     合并提交（不猜）。
+ *
+ * 只读纪律（与引擎调用面同一口径，docs/03 第 8 节）：
+ *   · **只跑 `GIT_READONLY_INVOCATIONS` 里那两条固定只读命令**，参数里不含任务 id、
+ *     不含任何项目数据 —— 没有命令拼接面；
+ *   · 不写工作区、不动索引、不 fetch（纯本地查询）；
+ *   · 子进程 env 只保留运行必需项，不注入任何身份变量。
+ */
+
+import { spawn } from 'node:child_process'
+
+/** ① 活跃任务的 `task/*` 分支 tip 时间（`--sort=-committerdate`：第一份即最新）。 */
+const BRANCH_TIP_ARGS = Object.freeze([
+  'for-each-ref',
+  '--sort=-committerdate',
+  '--format=%(committerdate:iso-strict)%09%(refname:short)',
+  'refs/heads/task'
+])
+
+/** ② 主分支上的合并提交（`-n` 上限够覆盖几百个终态任务的合并历史）。 */
+const MERGE_COMMIT_ARGS = Object.freeze([
+  'log',
+  '--merges',
+  '--format=%cI%09%s',
+  '-n',
+  '4000'
+])
+
+/**
+ * 允许执行的 git 调用面（**唯一来源**：实现从它取参数，测试按它做静态断言）。
+ * 想加新调用必须先改这里 —— 与引擎白名单同一个 fail-closed 思路。
+ */
+export const GIT_READONLY_INVOCATIONS = Object.freeze([
+  Object.freeze({ name: 'branch-tips', args: BRANCH_TIP_ARGS }),
+  Object.freeze({ name: 'merge-commits', args: MERGE_COMMIT_ARGS })
+])
+
+/** 子进程 env 白名单：git 只读查询的最小集合（PATH 必需，Windows 还要 SystemRoot）。 */
+export const GIT_CHILD_ENV_KEYS = Object.freeze(['PATH', 'SystemRoot', 'SystemDrive', 'TEMP', 'TMP'])
+
+/** 采集结果的空形态（git 不可用 / 非 git 项目 / 超时都返回它，只是 `reason` 不同）。 */
+const EMPTY_TIMES = Object.freeze({ branchTimes: {}, mergeTimes: {} })
+
+/**
+ * 子进程 env：白名单式构造，绝不把宿主变量（尤其是身份类）带下去。
+ * @param {Record<string, string|undefined>} [source]
+ */
+export function buildGitChildEnv(source = process.env) {
+  const env = {}
+  for (const key of GIT_CHILD_ENV_KEYS) {
+    const value = source[key]
+    if (typeof value === 'string' && value !== '') env[key] = value
+  }
+  return env
+}
+
+/**
+ * `task/<id>` 或 `task/<line>/<id>` → 任务 id（多线取最后一段；id 自身不含 `/`）。
+ * 非任务分支（main / feature/... ）→ null。
+ * @param {string} refName
+ * @returns {string|null}
+ */
+export function parseTaskBranchRef(refName) {
+  if (typeof refName !== 'string') return null
+  const match = /^task\/(.+)$/.exec(refName.trim())
+  if (match === null) return null
+  const segments = match[1].split('/')
+  const id = segments[segments.length - 1].trim()
+  return id === '' ? null : id
+}
+
+/**
+ * 合并提交标题 → 任务 id。只认 `Merge branch 'task/<id>'`（可带 ` into <branch>` 尾巴）。
+ * @param {string} subject
+ * @returns {string|null}
+ */
+export function parseMergeSubject(subject) {
+  if (typeof subject !== 'string') return null
+  const match = /Merge branch 'task\/([^']+)'/.exec(subject)
+  if (match === null) return null
+  const segments = match[1].split('/')
+  const id = segments[segments.length - 1].trim()
+  return id === '' ? null : id
+}
+
+/** ISO 时间的最小形状校验（`iso-strict` / `%cI` 都是 `<date>T<time>` 开头）。 */
+function looksLikeIso(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)
+}
+
+/** 按第一个制表符切开 `--format` 的两列（时间 + 后续列）。 */
+function splitColumns(line) {
+  // 双保险：`%x09` 这种写法在部分 git/环境上会被**原样带出**成字面量 `%09`
+  // （2026-10-29 实测踩到：GIT 2.56 + execFileSync 走 argv 时），先归一成真分隔符，
+  // 免得整个时间层静默变空。
+  const text = line.trim().replace(/%0?9/g, '\t')
+  if (text === '') return null
+  const index = text.indexOf('\t')
+  if (index < 0) return null
+  const when = text.slice(0, index).trim()
+  const rest = text.slice(index + 1).trim()
+  if (rest === '' || !looksLikeIso(when)) return null
+  return { when, rest }
+}
+
+/**
+ * 跑一条 git 只读命令。失败/超时都**不抛错**（排序降级即可，不能因为 git 坏了让面板挂）。
+ * @param {readonly string[]} args
+ * @param {{ cwd: string, timeoutMs: number, spawnImpl: Function }} options
+ */
+export function runGitReadonly(args, { cwd, timeoutMs = 8000, spawnImpl = spawn }) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawnImpl('git', [...args], {
+        cwd,
+        windowsHide: true,
+        env: buildGitChildEnv(),
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+    } catch (error) {
+      resolve({ ok: false, reason: 'git-spawn-failed', stdout: '', stderr: String(error) })
+      return
+    }
+
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let timedOut = false
+
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      try {
+        child.kill()
+      } catch {
+        /* 忽略：可能已退出 */
+      }
+    }, Math.max(1, timeoutMs))
+
+    // 刻意**不**设 setEncoding：按 Buffer 收集后统一 utf8 解码，
+    // 免得子进程（git）输出编码受宿主 locale 影响（中文提交信息会乱码）。
+    const chunks = []
+    const errChunks = []
+    child.stdout.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))))
+    child.stderr.on('data', (chunk) => errChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))))
+
+    child.on('error', (error) => {
+      finish({ ok: false, reason: 'git-spawn-failed', stdout: '', stderr: String(error) })
+    })
+
+    child.on('close', (code) => {
+      stdout = Buffer.concat(chunks).toString('utf8')
+      stderr = Buffer.concat(errChunks).toString('utf8')
+      if (timedOut) {
+        finish({ ok: false, reason: 'git-timeout', stdout, stderr })
+        return
+      }
+      if (code !== 0) {
+        // 非 git 仓库在这里表现得最典型（exit 128 + "not a git repository"）
+        finish({ ok: false, reason: 'git-failed', code, stdout, stderr })
+        return
+      }
+      finish({ ok: true, reason: null, code: 0, stdout, stderr })
+    })
+  })
+}
+
+/**
+ * 采集 git 时间层。
+ *
+ * @param {object} options
+ * @param {string} options.worktree 主工作树（git 仓库根）
+ * @param {number} [options.timeoutMs]
+ * @param {Function} [options.spawnImpl] 仅供测试注入
+ * @returns {Promise<{ available: boolean, reason: string|null, branchTimes: Record<string,string>, mergeTimes: Record<string,string> }>}
+ */
+export async function collectGitTimes({ worktree, timeoutMs = 8000, spawnImpl = spawn } = {}) {
+  if (typeof worktree !== 'string' || worktree === '') {
+    return { available: false, reason: 'no-worktree', ...EMPTY_TIMES }
+  }
+
+  const [branch, merge] = await Promise.all([
+    runGitReadonly(BRANCH_TIP_ARGS, { cwd: worktree, timeoutMs, spawnImpl }),
+    runGitReadonly(MERGE_COMMIT_ARGS, { cwd: worktree, timeoutMs, spawnImpl })
+  ])
+
+  if (branch.ok !== true && merge.ok !== true) {
+    return { available: false, reason: branch.reason ?? merge.reason ?? 'git-failed', ...EMPTY_TIMES }
+  }
+
+  const branchTimes = {}
+  if (branch.ok === true) {
+    for (const line of branch.stdout.split('\n')) {
+      const columns = splitColumns(line)
+      if (columns === null) continue
+      const id = parseTaskBranchRef(columns.rest)
+      // 已按 committerdate 倒序：同一任务分支只留第一次出现（= 最新）
+      if (id !== null && branchTimes[id] === undefined) branchTimes[id] = columns.when
+    }
+  }
+
+  const mergeTimes = {}
+  if (merge.ok === true) {
+    for (const line of merge.stdout.split('\n')) {
+      const columns = splitColumns(line)
+      if (columns === null) continue
+      const id = parseMergeSubject(columns.rest)
+      // `log` 也是新→旧：同一任务只留最近一次合并
+      if (id !== null && mergeTimes[id] === undefined) mergeTimes[id] = columns.when
+    }
+  }
+
+  return { available: true, reason: null, branchTimes, mergeTimes }
+}

package/lib/ideas.js

@@ -15,6 +15,12 @@
  *   3. **归档不能当状态分布用**：`IDEAS-archive.md` 543 KB / 372 个 `## `，其中 311 条仍写着
  *      `pending`——归档保留原文，`status` 是**历史值**（AC-13.1/13.9）。
  *
+ * 状态词表（引擎 2026-10-23 调整后）：`study` / `questioning` / `pending` / `covered`。
+ *   · `taskified` 已正名为 `covered`（语义：被既有任务覆盖 / 撞车并入，待归档）；
+ *   · `dropped` 已从活跃台账下线（「放弃」改由 `idea close --reason` 一次离场归档）。
+ * 老引擎写下的 `taskified` / `dropped` 会按未知状态走降级路径（原文进 `extra`），
+ *   不静默改写、不猜测映射。
+ *
  * 只读：本模块只读文件，不写任何东西（FR-10 / FR-13.8）。
  */
 
@@ -23,47 +29,50 @@ import { createReadStream, statSync } from 'node:fs'
 const IDEAS_FILENAME = 'IDEAS.md'
 const ARCHIVE_FILENAME = 'IDEAS-archive.md'
 
-/** 引擎定义的 5 个状态（不得自造）。 */
-export const IDEA_STATUSES = Object.freeze(['study', 'questioning', 'pending', 'taskified', 'dropped'])
+/**
+ * 引擎定义的 4 个状态（不得自造）。
+ *
+ * `covered` 取代旧词 `taskified`：**只**表示「撞车并入已有任务，待归档」，
+ * **不是**「已注册 / 已立任务」的标记（引擎 `rules/intake.md` ①）。
+ * 旧的 `dropped` 已从活跃台账下线（引擎 `task-intake-exit-verb-close`）。
+ */
+export const IDEA_STATUSES = Object.freeze(['study', 'questioning', 'pending', 'covered'])
 
 /**
- * 「在等谁」由 status 派生，**不是引擎字段**（FR-13.4）。
+ * 派生桶（**不是引擎状态**）：任务定义层有 `source`/`additional_sources` 指向该想法。
+ *
+ * 为什么必须单列：`status` 只表达摄入/裁决态。被非终态任务引用的条目按 E025
+ * **必须保持 `pending`**，所以「已转任务」只能由定义层溯源推出（FR-13.3b）。
+ * 它不能复用 `covered`——`covered` 是「撞车并入已有任务」，两者语义不同。
+ */
+export const IDEA_CONVERTED_STATUS = 'converted'
+
+/** 统计条与行标签使用的展示桶：4 个引擎状态 + 1 个派生桶（顺序按生命周期）。 */
+export const IDEA_DISPLAY_STATUSES = Object.freeze([
+  'study', 'questioning', 'pending', IDEA_CONVERTED_STATUS, 'covered'
+])
+
+/**
+ * 「在等谁」由展示桶派生，**不是引擎字段**（FR-13.4）。
  * 徽章数 = 等用户的那两个状态之和，不是总条目数（FR-13.2）。
+ *
+ * `covered` / `converted` 都已有人接手（并入既有任务 / 已拆出新任务），故为 `none`。
  */
 export const IDEA_OWNER = Object.freeze({
   study: 'user',
   questioning: 'user',
   pending: 'agent',
-  taskified: 'none',
-  dropped: 'none'
+  [IDEA_CONVERTED_STATUS]: 'none',
+  covered: 'none'
 })
 
-/**
- * 活跃层可能出现的状态。
- *
- * ⚠ 为什么不是全部 5 个：`taskified` / `dropped` 的条目已被引擎**移入归档文件**
- * （`IDEAS-archive.md`），而归档按 FR-13.12 不进默认加载路径（参考项目实测 543 KB / 373 条）。
- * 因此这两个筛选在活跃列表上必然恒为 0——把恒 0 的筛选摆出来只会让人以为坏了
- * （用户实测反馈：「已经立任务的条目，为什么没有出现在已转任务中？」）。
- * 它们的数量由归档分类计数回答（见 `scanArchiveFile` 的 `byStatus`，FR-13.7）。
- *
- * 另外注意：**归档件里的 `- status:` 是入档历史值**，引擎明确「不改写 status」
- * （`rules/intake.md`：归档面的语义是「已消费」而非某个状态值）。
- */
-export const IDEA_ACTIVE_STATUSES = Object.freeze(['study', 'questioning', 'pending'])
-
-/** 活跃层里的「终态」：已转任务 / 已丢弃（不再算活跃）。 */
-export const IDEA_TERMINAL_STATUSES = Object.freeze(['taskified', 'dropped'])
-
-/** 归档里值得单独露出来的两个终态（FR-13.7 的分类计数）。 */
-export const IDEA_ARCHIVE_TERMINAL_STATUSES = Object.freeze(['taskified', 'dropped'])
 
 /**
  * 从任务定义层建「想法 id → 任务 id[]」的溯源索引（FR-13.3b / docs/03 E025）。
  *
  * 为什么必须靠定义层：**`status` 不是「是否已立任务」的标记**。引擎 `rules/intake.md` 明确：
  *   · `source: idea:<id>` 的条目在任务非终态期间**必须保持 `pending`**（E025 硬约束）；
- *   · `taskified` **并非「已注册」语义**，只服务「撞车并入已有任务」。
+ *   · `covered` **并非「已注册」语义**，只服务「撞车并入已有任务」。
  * 实测 `phase-workflow-engineering` 在 `IDEAS.md` 里写着 `pending`（这是**正确**的，
  * 它的 3 个任务都未终态），但定义层已有 3 个 `source: idea:phase-workflow-engineering`。
  * 只看 status 的话，这条已经立成任务的想法会被算进「活跃 / 待拆解」（用户实测发现）。
@@ -100,23 +109,27 @@ export function buildIdeaTaskIndex(tasks) {
 }
 
 /**
- * 把「定义层溯源」叠加到条目上，得到**有效状态**：
- * 只要这个想法 id 在任务定义层出现过，就算已转任务（覆盖字面上的 `pending`）。
+ * 把「定义层溯源」叠加到条目上，得到**展示桶**（不改写引擎的 `status`）。
+ *
+ * 只要这个想法 id 在任务定义层出现过，就额外标记 `converted: true` 并把
+ * `displayStatus` 置为派生桶 `converted`；`status` / `rawStatus` 仍是文件里的字面值
+ * （被非终态任务引用的条目按 E025 必须保持 `pending`，这不是滞后）。
  *
  * @param {object[]} entries `mergeIdeasList` 的结果
  * @param {Map<string, string[]>} ideaTaskIndex `buildIdeaTaskIndex` 的结果
  */
-export function applyConvertedStatus(entries, ideaTaskIndex) {
+export function attachConvertedTasks(entries, ideaTaskIndex) {
   return entries.map((entry) => {
     const convertedTasks = typeof entry.id === 'string' ? (ideaTaskIndex.get(entry.id) ?? []) : []
     const converted = convertedTasks.length > 0
+    const displayStatus = converted ? IDEA_CONVERTED_STATUS : entry.status
     return {
       ...entry,
-      rawStatus: entry.status,
+      rawStatus: entry.rawStatus ?? entry.status,
       convertedTasks,
-      // 有效状态：定义层说已经立成任务，就不再算「待拆解」
-      // （status 按引擎语义只表达摄入/裁决态，不表达「已立任务」）
-      status: converted ? 'taskified' : entry.status
+      converted,
+      displayStatus,
+      owner: displayStatus === null ? 'none' : (IDEA_OWNER[displayStatus] ?? 'none')
     }
   })
 }
@@ -278,39 +291,48 @@ function finalizeEntry(raw) {
   }
 }
 
-/** 汇总计数 + 徽章数（FR-13.2）。 */
+/**
+ * 汇总计数 + 徽章数（FR-13.2）。
+ *
+ * `byStatus` 按**展示桶**计数：4 个引擎状态 + 派生桶 `converted`（已转任务）。
+ * 已转任务的条目不会同时计入 `pending`，因此三分区闭合：
+ *   `全部 = 活跃 + 已转任务 + 已覆盖`（未知状态另计，不进分区）
+ *   `活跃 = 论证中 + 待补充 + 待拆解`
+ * `covered` 不计入活跃：它表示「已并入既有任务，待用户 close 归档」。
+ */
 export function summarizeIdeas(entries) {
   const byStatus = {}
-  for (const status of IDEA_STATUSES) byStatus[status] = 0
+  for (const status of IDEA_DISPLAY_STATUSES) byStatus[status] = 0
   let unknown = 0
   for (const entry of entries) {
-    if (entry.status === null) unknown += 1
-    else byStatus[entry.status] += 1
+    const display = entry.displayStatus ?? (entry.converted === true ? IDEA_CONVERTED_STATUS : entry.status)
+    if (display === null || display === undefined || byStatus[display] === undefined) unknown += 1
+    else byStatus[display] += 1
   }
   return {
     byStatus,
     unknown,
     needsUser: byStatus.study + byStatus.questioning,
     total: entries.length,
-    /** 活跃 = 活跃层里**尚未转成任务**的条目（FR-13.6b；已扣除定义层已立任务的） */
-    active: entries.filter((entry) => !IDEA_TERMINAL_STATUSES.includes(entry.status)).length,
+    /** 活跃 = 尚未转成任务、也未被覆盖的条目（FR-13.6b） */
+    active: byStatus.study + byStatus.questioning + byStatus.pending,
     /** 已转任务（活跃层内）—— 由定义层溯源推出，不是归档计数 */
-    converted: entries.filter((entry) => entry.status === 'taskified').length,
-    /** 已丢弃（活跃层内）—— 与 converted 同属「离队」 */
-    dropped: entries.filter((entry) => entry.status === 'dropped').length
+    converted: byStatus[IDEA_CONVERTED_STATUS],
+    /** 已覆盖（活跃层内）—— 撞车并入既有任务，待 close 归档 */
+    covered: byStatus.covered
   }
 }
 
 /**
  * 统计条要渲染的芯片状态集合（FR-13.6）。
  *
- * 固定为**全部 5 个想法状态**（0 值可点，FR-5.9），因为统计条必须能完整表达三分区：
- *   `全部 = 活跃 + 已转任务 + 已丢弃`，其中 `活跃 = 论证中 + 待补充 + 待拆解`。
+ * 固定为**全部展示桶**（0 值可点，FR-5.9），因为统计条必须能完整表达三分区：
+ *   `全部 = 活跃 + 已转任务 + 已覆盖`，其中 `活跃 = 论证中 + 待补充 + 待拆解`。
  * 早先试过「只显示实际出现过的状态」以避免恒 0 芯片，但那会让分区在界面上不闭合
- * （例如 已丢弃 缺失时看不出 0 是「没有」还是「没显示」）——用户要求分区自洽，故固定。
+ * （例如 已覆盖 缺失时看不出 0 是「没有」还是「没显示」）——用户要求分区自洽，故固定。
  */
 export function ideaStripStatuses() {
-  return [...IDEA_STATUSES]
+  return [...IDEA_DISPLAY_STATUSES]
 }
 
 /**
@@ -338,7 +360,7 @@ export function scanArchiveFile(filePath, onError) {
     const ids = []
     /** @type {Record<string, number>} */
     const byStatus = {}
-    /** @type {Record<string, string>} 小节 id → 该小节字面 status（判定「已丢弃」要用） */
+    /** @type {Record<string, string>} 小节 id → 该小节字面 status（判定「历史已放弃」要用） */
     const statusById = {}
     /** 当前小节的 id / 首个 status（小节只有第一个 `- id:` / `- status:` 算数） */
     let sectionId = null
@@ -428,34 +450,37 @@ export function scanArchiveFile(filePath, onError) {
  * `pending`——按字面分组会把它们全算成「没立任务」，而其中 287 条在任务池里有引用。
  *
  * 分组（互斥，合计 = `count`）：
- *   已转任务   任务池（`source` ∪ `additional_sources`）引用了该 id
- *   已丢弃     未被引用，且字面 status = dropped
- *   未立任务   未被引用，也不是 dropped（人工裁决「已消费」离场）
- *   无法对照   小节缺 `- id:`，无从判断（实测存量 20 条）
+ *   已转任务   converted       任务池（`source` ∪ `additional_sources`）引用了该 id
+ *   历史已放弃 legacyDropped   未被引用，且字面 status = dropped（**旧词表遗留数据**）
+ *   未立任务   untasked        未被引用（人工 `idea close` 裁决离场，含 covered/pending/study）
+ *   无法对照   noId            小节缺 `- id:`，无从判断（实测存量 20 条）
+ *
+ * ⚠ `dropped` 已从引擎词表下线，分组里的 `legacyDropped` 只统计**入档历史值**，
+ * 不代表当前状态机还有这个状态。
  *
  * @param {{count: number, ids: string[], noIdCount: number, statusById?: Record<string, string>}} scan `scanArchiveFile` 的结果
  * @param {Map<string, string[]>} ideaTaskIndex `buildIdeaTaskIndex` 的结果
  * @param {Record<string, string>} [statusByIdOverride] 覆盖 scan 里的 id → 字面 status（测试用）
  */
 export function classifyArchive(scan, ideaTaskIndex, statusByIdOverride) {
-  // 「已丢弃」要按**归档件自己的**字面 status 判（不能拿 IDEAS.md 的状态表来查，那是活跃层文件）
+  // 「历史已放弃」要按**归档件自己的**字面 status 判（不能拿 IDEAS.md 的状态表来查，那是活跃层文件）
   const statusById = statusByIdOverride ?? scan.statusById ?? {}
-  let taskified = 0
-  let dropped = 0
+  let converted = 0
+  let legacyDropped = 0
   let untasked = 0
   for (const id of scan.ids ?? []) {
     if (ideaTaskIndex instanceof Map && ideaTaskIndex.has(id)) {
-      taskified += 1
+      converted += 1
       continue
     }
-    if (statusById[id] === 'dropped') dropped += 1
+    if (statusById[id] === 'dropped') legacyDropped += 1
     else untasked += 1
   }
   const noId = Math.max(0, scan.count - (scan.ids?.length ?? 0))
   return {
     total: scan.count,
-    taskified,
-    dropped,
+    converted,
+    legacyDropped,
     untasked,
     noId: Math.max(noId, scan.noIdCount ?? 0)
   }

package/lib/master.js

@@ -36,15 +36,17 @@ export function launcherOf(root) {
   return join(orchdDirOf(root), LAUNCHER_FILENAME)
 }
 
-/**
- * 安装痕迹判定（T6 的定稿）：项目根下存在 「.orchd」 目录即算「有痕迹」。
- * 不把 junction/符号链接排除在外——参考项目的 「.orchd」 正是指向真实目录的 junction。
- * @param {string} root
- * @returns {boolean}
- */
-export function hasInstallationTrace(root) {
-  return isDirectory(orchdDirOf(root))
-}
+// ── 安装痕迹不再是独立的判定步骤 ────────────────────────────────────────────
+//
+// 历史坑（根因治理前）：这里曾导出 `hasInstallationTrace(root)`（= 「根下有没有 `.orchd`」）
+// 作为 `detect` 的第 ① 步，而 `resolveLayout` 又自带一套容器主工作树自动探测。两条路径对
+// 「痕迹在哪」的口径不一致 → 每出现一种新布局形态就得在其中一条上补特例、另一条漏掉
+// （junction / 根空 `.orchd` / 根**无** `.orchd` / 子目录标记），于是来回打补丁：
+// 「3DViewer 空 `.orchd`」修过一次，「容器根连 `.orchd` 都没有」又漏一次。
+//
+// 现在把「是否接入 + 主工作树/定义文件在哪」**收敛为唯一真源**：`resolveLayout`。
+// 它返回的 `no-installation` 就是「根与子工作树都没有安装痕迹」这唯一一种结论，
+// `detect` 只消费它，不再有任何独立的痕迹判定。
 
 /**
  * 自动探测「容器布局的主工作树」（FR-2.2 补充，用户实测驱动）。
@@ -127,7 +129,17 @@ function findContainerWorktree(root) {
 }
 
 /**
- * 解析布局并推导三套路径。
+ * 布局发现 —— 「是否接入 orchd」与「主工作树/定义文件在哪」的**唯一真源**。
+ *
+ * 所有布局形态（junction / 根空 `.orchd` / 根**无** `.orchd` / 子目录标记 / 标记与实际工作树
+ * 不一致）都在**这一个函数**里收敛；`detect` 只消费它的结论，不再另判安装痕迹（历史坑见上方注释）。
+ *
+ * 三种结论：
+ *   · resolved         → `ok:true`，带 kind / mainWorktree / masterPath / storeHint
+ *   · broken           → `ok:false`，reason ∈ { layout-marker-mismatch, layout-unresolved }
+ *   · no-installation  → `ok:false`，reason = no-installation  ← detect 据此判 not_installed
+ *
+ * 三套路径：
  *
  * 「」「
  * container → mainWorktree = json.main_worktree
@@ -137,19 +149,28 @@ function findContainerWorktree(root) {
  *           → mainWorktree = root
  *             masterPath   = <root>/.orchd/_master.json
  *             storeHint    = <root>/.orchd
- * 探针兜底：masterPath 不存在则试另一分支候选；都失败 → layout-unresolved
+ * 探针兜底：主候选 masterPath 不存在则试另一分支候选
+*
+* 探针兜底后，扫一层非隐藏子目录找容器主工作树（见 findContainerWorktree）：
+*   找到（自述 container / 有 _master.json / 有 __main__.py）→ container
+*   找不到时再看根自己有没有 `.orchd`：
+*     有（哪怕空目录）→ flat（是否 uninitialized 交给 detect 的定义层判定）
+*     没有           → no-installation（根与子工作树都没有痕迹）
+* container 标记下两边 master 都不在 → layout-unresolved
  * 「」「
  *
  * @param {string} root 项目根（可能是容器根）
- * @param {{ probeFallback?: boolean }} [options] probeFallback=false 时跳过探针兜底（纯逻辑测试用）
- * @returns {{ ok: true, kind: 'container'|'flat', mainWorktree: string, masterPath: string, storeHint: string,
- *            markerPath: string, markerRead: boolean, markerError?: string, note?: string }
- *          | { ok: false, reason: 'layout-unresolved', detail: object }}
+* @param {{ probeFallback?: boolean }} [options] probeFallback=false 时跳过探针兜底与自动探测（纯逻辑测试用）
+* @returns {{ ok: true, kind: 'container'|'flat', mainWorktree: string, masterPath: string, storeHint: string,
+*            containerRoot: string|null, markerPath: string, markerRead: boolean, markerError?: string, note?: string }
+*          | { ok: false, reason: 'layout-marker-mismatch'|'layout-unresolved'|'no-installation', detail: object }}
  */
 export function resolveLayout(root, options = {}) {
   const probeFallback = options.probeFallback !== false
   const rootCanonical = canonicalPath(root)
   const markerPath = layoutFileOf(rootCanonical)
+  // 「根自己有没有 .orchd」是区分 flat 与 no-installation 的唯一依据（即原 hasInstallationTrace 的语义）。
+  const rootHasOrchd = isDirectory(orchdDirOf(rootCanonical))
 
   let marker
   let markerRead = false
@@ -167,6 +188,10 @@ export function resolveLayout(root, options = {}) {
       ok: true,
       kind,
       mainWorktree: worktree,
+      // 容器根 = 主工作树的父目录（仅 container 布局有意义，flat 下为 null）。
+      // 用途：引擎可能装在容器根的 `.orchd/`（主工作树只有定义层），启动器定位要能回退过去
+      // —— 见 `orchd-cli.js::resolveLauncherPath`。
+      containerRoot: kind === 'container' ? dirname(worktree) : null,
       masterPath: join(orchdDir, MASTER_FILENAME),
       storeHint: kind === 'container' ? join(dirname(worktree), '.orchd-runtime') : orchdDir,
       markerPath,
@@ -223,9 +248,9 @@ export function resolveLayout(root, options = {}) {
     }
   }
 
-  // ⚠ 根上**没有容器标记**（`alternate === null`）且根也没有定义文件时：
-  //   再扫一层子目录找容器主工作树——这正是「容器根的 .orchd/ 是空的、标记只在 main/ 下」
-  //   那种项目（用户实测识别不出来）。根上有标记时以标记为准，不在这里改判。
+  // ⚠ 根上**没有容器标记**（`alternate === null`）时：先扫一层子目录找容器主工作树
+  //   （「容器根的标记只在 main/ 下」这种项目——不论根自己有没有 `.orchd` 都要找）。
+  //   找不到时再看根自己有没有 `.orchd`，决定是 flat 还是「未接入」。
   if (alternate === null) {
     const auto = findContainerWorktree(rootCanonical)
     if (auto !== null) {
@@ -235,23 +260,36 @@ export function resolveLayout(root, options = {}) {
         markerRead: auto.markerRead
       }
     }
-  }
 
-  if (alternate !== null) {
+    // 探测不到主工作树：根有 `.orchd`（哪怕空目录）→ flat（装了没初始化，交给 detect 判）；
+    // 根连 `.orchd` 都没有 → 根与子工作树都没有痕迹 → 未接入。
+    if (rootHasOrchd) return primary
+
     return {
       ok: false,
-      reason: 'layout-unresolved',
+      reason: 'no-installation',
       detail: {
         root: rootCanonical,
         markerPath,
         markerRead,
         ...(markerError === undefined ? {} : { markerError }),
-        triedMasterPaths: [primary.masterPath, alternate.masterPath]
+        hint: 'no .orchd directory at the project root and no container main worktree found under it'
       }
     }
   }
 
-  return primary
+  // container 标记在，但两边候选都没有主工作树的定义文件 → 布局无法收敛
+  return {
+    ok: false,
+    reason: 'layout-unresolved',
+    detail: {
+      root: rootCanonical,
+      markerPath,
+      markerRead,
+      ...(markerError === undefined ? {} : { markerError }),
+      triedMasterPaths: [primary.masterPath, alternate.masterPath]
+    }
+  }
 }
 
 /**