@lumoai/cli 1.19.0 → 1.20.1

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lumo
-description: 'Use the Lumo CLI to load task context, manage session bindings, and run tasks / projects / milestones / sprints / docs / memory from the terminal. Activate when: the user mentions a Lumo task identifier (LUM-42 etc.), asks to load task background/context, wants to bind/check/detach a Claude Code session''s task, is about to start work on a task, or wants to create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, or memory. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "which task", "what task am I on", "work on LUM", "session wrap", "wrap up session", "进度评论", "卡住检测", "create task", "new task", "file a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "update task", "change task status", "rename task", "reassign task", "mark task as done", "lumo next", "next task", "what should I work on", "推荐下一个任务", "list projects", "what projects", "milestone", "里程碑", "list/create/update/delete/show milestone", "set milestone", "attach/unbind milestone", "tasks in milestone", "search milestones", "find milestone", "milestone health", "at-risk", "overdue", "archive/unarchive milestone", "归档里程碑", "milestone summary", "里程碑复盘", "reorder/move milestone", "排序里程碑", "milestone add/remove", "挂任务到里程碑", "auth login", "log in", "logout", "sign out", "switch account", "whoami", "who am I", "current workspace", "登录", "切换账号", "create/update/list/show/delete doc", "write doc", "写文档", "新建文档", "修改文档", "查看文档", "bind/unbind doc", "把文档关联到任务", "doc scope", "personal/workspace doc", "tag", "add/remove tag", "标签", "share/unshare doc", "分享文档", "doc share-list", "viewer/editor/manager", "doc tree", "doc move", "move/reparent doc", "移动文档", "sprint", "冲刺", "迭代", "create/list/show/update/delete sprint", "start/close sprint", "开始/关闭冲刺", "add to sprint", "active sprints", "sprint summary", "冲刺总结", "把任务挂到冲刺", "sprint health", "sprint risk", "is this sprint at risk", "冲刺风险", "冲刺健康度", "sprint blockers", "冲刺阻塞", "lumo update", "upgrade lumo", "升级 lumo", "new lumo version", "lumo setup", "install lumo skill/hooks", "wire up lumo", "set up lumo", "安装 lumo", "配置 lumo", "task artifact", "artifact add/list/show/update/rm", "spec artifact", "record/attach spec", "attach plan", "记录 spec", "查看 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design, "memory", "记忆", "remember", "record a memory", "记一条", "promote memory", "promote to project", "沉淀", "task/project memory", "retrieval", "取全文", "拉全文", "task slack show", "看 thread", "show slack thread", "task web show", "web 正文", "task figma context", "figma metadata", "task comments list", "list comments", "看评论", "task pr show", "查看 PR", "show pr", "PR 详情", "import google doc", "sync google doc", "google drive", "doc import-gdoc", "doc sync", "导入/同步 google 文档", "mark blocked", "blocked tag", "标记 blocked", "stuck", "repeatedly failing", "worktree", "git worktree", "并行 worktree", "scaffold worktree", "新建 worktree", "node_modules 软链", "worktree 隔离", "lumo worktree add/rm/list".'
+description: 'Use the Lumo CLI to load task context, manage session bindings, and run tasks / projects / milestones / sprints / docs / memory from the terminal. Activate when: the user mentions a Lumo task identifier (LUM-42 etc.), asks to load task background/context, wants to bind/check/detach a Claude Code session''s task, is about to start work on a task, or wants to create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, or memory. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "which task", "what task am I on", "work on LUM", "session wrap", "wrap up session", "进度评论", "卡住检测", "fragment usage vote", "mark used fragments", "which fragments did I use", "--used", "上下文使用投票", "标记用过的记忆", "create task", "new task", "file a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "update task", "change task status", "rename task", "reassign task", "mark task as done", "lumo next", "next task", "what should I work on", "推荐下一个任务", "list projects", "what projects", "milestone", "里程碑", "list/create/update/delete/show milestone", "set milestone", "attach/unbind milestone", "tasks in milestone", "search milestones", "find milestone", "milestone health", "at-risk", "overdue", "archive/unarchive milestone", "归档里程碑", "milestone summary", "里程碑复盘", "reorder/move milestone", "排序里程碑", "milestone add/remove", "挂任务到里程碑", "auth login", "log in", "logout", "sign out", "switch account", "whoami", "who am I", "current workspace", "登录", "切换账号", "create/update/list/show/delete doc", "write doc", "写文档", "新建文档", "修改文档", "查看文档", "bind/unbind doc", "把文档关联到任务", "doc scope", "personal/workspace doc", "tag", "add/remove tag", "标签", "share/unshare doc", "分享文档", "doc share-list", "viewer/editor/manager", "doc tree", "doc move", "move/reparent doc", "移动文档", "sprint", "冲刺", "迭代", "create/list/show/update/delete sprint", "start/close sprint", "开始/关闭冲刺", "add to sprint", "active sprints", "sprint summary", "冲刺总结", "把任务挂到冲刺", "sprint health", "sprint risk", "is this sprint at risk", "冲刺风险", "冲刺健康度", "sprint blockers", "冲刺阻塞", "lumo update", "upgrade lumo", "升级 lumo", "new lumo version", "lumo setup", "install lumo skill/hooks", "wire up lumo", "set up lumo", "安装 lumo", "配置 lumo", "task artifact", "artifact add/list/show/update/rm", "spec artifact", "record/attach spec", "attach plan", "记录 spec", "查看 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design, "memory", "记忆", "remember", "record a memory", "记一条", "promote memory", "promote to project", "沉淀", "task/project memory", "retrieval", "取全文", "拉全文", "task slack show", "看 thread", "show slack thread", "task web show", "web 正文", "task figma context", "figma metadata", "task comments list", "list comments", "看评论", "task pr show", "查看 PR", "show pr", "PR 详情", "import google doc", "sync google doc", "google drive", "doc import-gdoc", "doc sync", "导入/同步 google 文档", "mark blocked", "blocked tag", "标记 blocked", "stuck", "repeatedly failing", "worktree", "git worktree", "并行 worktree", "scaffold worktree", "新建 worktree", "node_modules 软链", "worktree 隔离", "lumo worktree add/rm/list", "task lineage", "lineage", "causal trail", "审计", "因果链", "成本归因", "trace context", "--signal", "usage signal health", "auto usage audit", "自动使用审计", "signal-health".'
 ---
 
 ## Prerequisites
@@ -29,7 +29,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `doc*`                                                                            | [references/docs.md](references/docs.md)                       |
 | `sprint*`                                                                         | [references/sprints.md](references/sprints.md)                 |
 | `task/project memory`, `memory promote/rm`                                        | [references/memory.md](references/memory.md)                   |
-| `session attach/status/detach/wrap`, auto-bind, Layer-2 review                    | [references/sessions.md](references/sessions.md)               |
+| `session attach/status/detach/wrap`, git-suggest on start, Layer-2 review         | [references/sessions.md](references/sessions.md)               |
 | `worktree add/rm/list` (local dev tooling)                                        | [references/worktree.md](references/worktree.md)               |
 
 ## Command catalog
@@ -49,6 +49,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task figma context <id> <linkId>` — Figma link metadata (v1)
 - `lumo task comments list <id>` — full comment thread (read-only; ≠ `task comment`)
 - `lumo task pr show <id> <number>` — synced PR metadata (v1)
+- `lumo task lineage <id>` — show the causal trail: fragments that fed the task + each one's outcome + the run's token/loop cost (read-only audit view); `lumo task lineage <id> --signal` also appends workspace-level usage signal-health (used distribution, per-session variance, used-vs-base merge rate)
 
 **Tasks** — see [tasks.md](references/tasks.md)
 
@@ -97,8 +98,8 @@ The command catalog below is a **map**: it lists every command grouped by domain
 
 - `lumo session attach <id>` — bind this session to a task (then run `task context`)
 - `lumo session status` / `lumo session detach` — show / clear binding
-- `lumo session wrap [--yes] [--dry-run]` — end-of-session panel: progress comment + memory review + blocked-tag prompt
-- Auto-bind at session start + Layer-2 project-memory review — see the reference
+- `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — end-of-session panel: progress comment + memory review + fragment-usage vote (`--used`, LUM-300) + blocked-tag prompt. Usage is now also audited automatically when a task reaches DONE (evidence-gated, true-only — confident fragments marked used, the rest left NULL); `session wrap --used` remains the manual override and takes precedence for a session.
+- Git-suggest at session start (suggests `session attach`, never auto-binds) + Layer-2 project-memory review — see the reference
 
 **Worktrees (local dev tooling)** — see [worktree.md](references/worktree.md)
 
@@ -115,4 +116,4 @@ Typical flow when a user says "help me with LUM-42":
 3. Review unresolved items, PR-review todos, and the task description
 4. Begin working on the task
 
-**Auto-bind:** session-start may already bind the task from the git branch / recent commits and print `已自动绑定 LUM-N …`. If the user says "不是"/"不对"/"wrong task", run `lumo session detach` (then `session attach <LUM-N>` if they name the right one). See [sessions.md](references/sessions.md) for the full session-start behavior.
+**Git-suggest at start:** when the session is unbound, session-start may infer the task from the git branch / recent commits and print a suggestion — `检测到 LUM-N … 运行 lumo session attach LUM-N 绑定。` — **without** binding. Confirm it's the right task, then run `lumo session attach <LUM-N>` yourself (binding only happens on an explicit attach). See [sessions.md](references/sessions.md) for the full session-start behavior.

package/assets/skill/references/memory.md

@@ -44,7 +44,7 @@ developer could learn from the source, git log, or docs. When unsure, don't.
 
 ### Which category
 
-- `trap` — a pitfall. Describe the PROBLEM ONLY (`--trigger`, `--outcome`); put any fix in a separate `procedural`.
+- `trap` — a pitfall. Describe the problem (`--trigger`, `--outcome`); put a **one-line fix** inline via `--workaround`. Only when the fix is a genuine multi-step workflow, omit `--workaround` and add a separate `procedural` instead — never both (a `procedural` that just restates a trap's `--workaround` is a double-write).
 - `decision` — an engineering decision (`--what` + `--why`, optional `--alternatives`/`--implications`).
 - `convention` — a team rule (`--rule` + `--applies` = where it applies).
 - `procedural` — a reusable workflow (`--workflow` + `--trigger` + `--step`…).

package/assets/skill/references/sessions.md

@@ -2,26 +2,28 @@
 
 ## Session Management
 
-### Auto-bind at session start (from local git)
+### Suggest-on-start from local git (no auto-bind)
 
 When a session starts **without** a bound task, the `session-start` hook tries to
-infer the task from local git before falling back to the "请告诉我任务编号" prompt:
+infer the task from local git so it can **suggest** one — it never binds for you
+(LUM-302):
 
 - It reads the **current branch name** first (e.g. `lumo/LUM-145-...`), then the
   **most recent commit subjects** (e.g. `... [LUM-145]`), extracting the first
   `LUM-<n>`.
-- On a hit it binds the session to that task automatically (same `bind-task`
-  endpoint as `session attach`) and prints a single line:
-  `已自动绑定 LUM-145 - <title>（依据分支名/最近 commit）。如果不对，回复"不是"我就帮你解绑。`
-  The freshly-bound task's memory is injected too.
+- On a hit it prints a single suggestion line and stops — the session stays
+  **unbound** and no context is injected yet:
+  `检测到 LUM-145（依据分支名/最近 commit）。运行 lumo session attach LUM-145 绑定。`
+  No task title is shown here because nothing was fetched; the title, memory,
+  and PR-review todos appear only once you actually attach.
 - No match (detached HEAD, a non-lumo branch with no tagged commits, not a git
-  repo) or a failed bind (unknown task) → it degrades silently to the normal
-  unbound prompt.
+  repo) → it degrades to the normal unbound prompt.
 
-**Agent guidance:** if the user responds "不是" / "不对" / "wrong task" to an
-auto-bind line, run `lumo session detach` to clear the binding (then `session
-attach <LUM-N>` if they name the right one). No detach is needed when the
-auto-bound task is correct.
+**Agent guidance:** when you see a suggestion line, confirm the inferred task is
+the one the user wants, then run `lumo session attach <LUM-N>` (followed by
+`lumo task context <LUM-N>` to load the background). `session attach` is the
+**only** path that binds — there is nothing to "undo" if the inference is wrong;
+just attach the correct task instead.
 
 ### Layer 2 project-memory review at session start
 
@@ -62,7 +64,7 @@ lumo session attach LUM-42            # already on LUM-7 → prompts (TTY) / ref
 lumo session attach LUM-42 --force    # overwrite without confirmation
 ```
 
-**Agent guidance:** when `session attach` reports the session is already bound to a different task, **ask the user** whether to switch before re-running with `--force`. Don't auto-`--force` — the existing binding may be intentional (e.g. an auto-bind from the branch name). Alternatively run `lumo session detach` first, then a clean `session attach`.
+**Agent guidance:** when `session attach` reports the session is already bound to a different task, **ask the user** whether to switch before re-running with `--force`. Don't auto-`--force` — the existing binding may be intentional (e.g. a manual attach the user ran earlier). Alternatively run `lumo session detach` first, then a clean `session attach`.
 
 ### Parallel sessions
 
@@ -88,9 +90,9 @@ lumo session detach
 
 When to suggest: the user wants to stop tagging the current session with the active task (e.g., switching to unrelated exploratory work without binding to a different task).
 
-### `lumo session wrap [--yes] [--dry-run]` — wrap-up panel: progress comment + memory review + blocked-tag prompt
+### `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — wrap-up panel: progress comment + memory review + fragment-usage vote + blocked-tag prompt
 
-Session-end wrap-up panel with **three sections, run in order**:
+Session-end wrap-up panel with **four sections, run in order**:
 
 **1. 进度评论** — reads back the current Claude Code session's per-turn
 `turnSummary` rows (the one-line Chinese summaries written each STOP), aggregates
@@ -110,7 +112,21 @@ Out-of-range indices are ignored. Deletes/promotes run server-side, scoped to
 memories this session created (you can't touch other sessions' memories through
 this panel). With no new memories the section prints "(无内容)" and does nothing.
 
-**3. 卡住检测 (blocked-tag prompt, LUM-153)** — if the **same kind of failure
+**3. 上下文使用投票 (fragment-usage vote, LUM-300)** — lists the context
+fragments this session **consumed** (its lineage edges: memory / slack / web /
+figma / PR / review-todo / session), numbered from 1 with a content snippet
+label. The agent records which it **actually used** via
+`lumo session wrap --used <indices>` (1-based, comma/space separated; `--used
+none` = used nothing). Voted fragments get `used=true`, the rest of the
+session's fragments `used=false`. **Without `--used` the section only lists the
+candidates and writes nothing** (edges stay `null` = not voted — honest, not
+"unused"). A session that already voted (`usedAt` set) is skipped. **Why:** it
+upgrades the flywheel signal from "co-loaded" (constant, no information) to
+"actually used" (varies → discriminative); `task context` then prefers each
+fragment's usage-based merge rate, falling back to the weaker presence rate when
+usage samples are thin. With no consumed fragments the section prints "(无内容)".
+
+**4. 卡住检测 (blocked-tag prompt, LUM-153)** — if the **same kind of failure
 recurred ≥ 3 times** in this session (server-aggregated from
 `POST_TOOL_USE_FAILURE` events grouped by tool name, plus `STOP_FAILURE`
 turn-level failures), the section surfaces the dominant failure (`卡在 <tool>
@@ -128,11 +144,18 @@ suggestion and moves on rather than silently flipping board state. When there's
 nothing to prompt, the section prints "(无内容)".
 
 ```bash
-lumo session wrap            # interactive: preview each section, choose per-section
-lumo session wrap --yes      # progress posted + memories kept; blocked tag NOT auto-applied (needs interactive y)
-lumo session wrap --dry-run  # print all drafts only; never posts, never mutates, never advances watermarks
+lumo session wrap                  # interactive: preview each section, choose per-section
+lumo session wrap --yes            # progress posted + memories kept; blocked tag NOT auto-applied (needs interactive y)
+lumo session wrap --yes --used 1,3 # also record fragments 1 & 3 as used (the rest used=false)
+lumo session wrap --used none      # record that none of the injected fragments were used
+lumo session wrap --dry-run        # print all drafts only; never posts, never mutates, never advances watermarks
 ```
 
+The usage vote is a two-step flow for agents: run `lumo session wrap` once to
+see the numbered fragment list, decide which you actually used, then re-run with
+`--used <indices>`. Re-running is safe — the other sections are watermark-guarded
+(progress won't double-post, reviewed memories won't re-list).
+
 - Requires `$CLAUDE_CODE_SESSION_ID` (must run inside Claude Code) and a bound
   task (`lumo session attach <LUM-N>` first). With no bound task or no new turn
   summaries, the 进度评论 section prints "(无内容)" and posts nothing.

package/assets/skill/references/task-context.md

@@ -22,6 +22,7 @@ The command prints a markdown document to stdout containing:
 5. **Previous sessions** — ordered newest-first, each with:
    - A headline summary of what was done
    - Unresolved items (carry-over TODOs from that session)
+6. **飞轮信号 · 历史 merge 贡献** — appended at the very end. For each context fragment with enough history, a one-line historical merge-contribution signal (e.g. `出现在 5 个已闭合任务·4 merged (80%)`), computed from accumulated lineage edges. Denominator = distinct tasks where the fragment appeared with a resolved (non-UNKNOWN) outcome; only fragments with ≥3 such tasks are shown (cold-start gate), so the block is often absent early on. This is **historical correlation, not causation** — don't read it as a prediction.
 
 ### How to use the context
 
@@ -107,3 +108,28 @@ require the GitHub integration, so the command ends with a `note:` saying so.
 ```bash
 lumo task pr show LUM-42 128
 ```
+
+## `lumo task lineage <id>`
+
+Read-only audit view over the task's `LineageEdge` rows. Given a task
+identifier (`LUM-N`), prints the causal trail:
+
+- **Totals banner** — distinct sessions, fragment count, edge count,
+  total tokens (input/output/cache split) and loops, and the outcome
+  distribution.
+- **One block per session** — the group's cost shown **once** (token/loop),
+  the date it consumed context, then each context fragment as
+  `[OUTCOME] TYPE — <source label>`, plus a per-group outcome summary.
+
+Cost is attributed once per session (a session that injected many fragments is
+not double-counted). Fragment ids are canonical — MEMORY fragments survive
+consolidation drift.
+
+**Cold start:** a task with no edges prints a friendly note (lineage is captured
+when a session-bound run consumes the task's context), not an error.
+
+**When to suggest:** the user wants to audit "what context did the AI actually
+use, and what did it cost" for a task / merged PR — CFO / compliance / trust
+narratives.
+
+Entry point is the task identifier only; PR-number lookup is a future addition.

package/dist/cli/src/commands/session-wrap.js

@@ -5,16 +5,18 @@ const config_1 = require("../lib/config");
 const wrap_panel_1 = require("../lib/wrap-panel");
 const progress_comment_section_1 = require("./wrap/progress-comment-section");
 const memory_review_section_1 = require("./wrap/memory-review-section");
+const fragment_usage_section_1 = require("./wrap/fragment-usage-section");
 const blocked_prompt_section_1 = require("./wrap/blocked-prompt-section");
 /**
  * `lumo session wrap [--yes] [--dry-run]`
  *
- * Session-end wrap-up panel with three sections, run in order: (1) draft a
+ * Session-end wrap-up panel with four sections, run in order: (1) draft a
  * progress comment from this session's unposted turnSummaries and post it
  * (after y/e/s confirmation) to the bound task; (2) review the Layer1 memories
  * this session sedimented — keep/delete/promote, deduped by a per-session
- * watermark; (3) if the session repeatedly hit the same failure, prompt whether
- * to flag the bound task with a `blocked` tag (LUM-153, prompt-only).
+ * watermark; (3) vote which injected context fragments were actually used
+ * (LUM-300, via `--used`); (4) if the session repeatedly hit the same failure,
+ * prompt whether to flag the bound task with a `blocked` tag (LUM-153).
  */
 async function sessionWrap(options) {
     const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
@@ -31,6 +33,7 @@ async function sessionWrap(options) {
     const sections = [
         new progress_comment_section_1.ProgressCommentSection({ creds, sessionId }),
         new memory_review_section_1.MemoryReviewSection({ creds, sessionId }),
+        new fragment_usage_section_1.FragmentUsageSection({ creds, sessionId, used: options.used }),
         new blocked_prompt_section_1.BlockedPromptSection({ creds, sessionId }),
     ];
     await (0, wrap_panel_1.runWrapPanel)(sections, {

package/dist/cli/src/commands/task-context.js

@@ -114,21 +114,28 @@ function formatTaskContextMarkdown(data, now) {
         lines.push('');
         lines.push('_No prior coding sessions for this task._');
         lines.push('');
-        return lines.join('\n');
     }
-    lines.push(`## Previous Sessions (${data.sessions.length})`);
-    lines.push('');
-    for (const s of data.sessions) {
-        const shortId = s.id.slice(0, 8);
-        const ago = (0, format_1.relativeTime)(new Date(s.lastActivityAt), now);
-        const dur = (0, format_1.formatDuration)(s.durationMs);
-        lines.push(`### Session ${shortId} · ${ago} · ${dur}`);
-        lines.push(`**Summary**: ${(0, sanitize_1.sanitizeField)(s.headline)}`);
-        if (s.unresolved.length > 0) {
-            lines.push('**Unresolved**:');
-            for (const u of s.unresolved)
-                lines.push(`- ${(0, sanitize_1.sanitizeField)(u)}`);
+    else {
+        lines.push(`## Previous Sessions (${data.sessions.length})`);
+        lines.push('');
+        for (const s of data.sessions) {
+            const shortId = s.id.slice(0, 8);
+            const ago = (0, format_1.relativeTime)(new Date(s.lastActivityAt), now);
+            const dur = (0, format_1.formatDuration)(s.durationMs);
+            lines.push(`### Session ${shortId} · ${ago} · ${dur}`);
+            lines.push(`**Summary**: ${(0, sanitize_1.sanitizeField)(s.headline)}`);
+            if (s.unresolved.length > 0) {
+                lines.push('**Unresolved**:');
+                for (const u of s.unresolved)
+                    lines.push(`- ${(0, sanitize_1.sanitizeField)(u)}`);
+            }
+            lines.push('');
         }
+    }
+    // Flywheel signal goes last so it reads as a closing "historical payoff"
+    // footer (LUM-278). Server returns "" below the cold-start floor.
+    if (data.lineageSection && data.lineageSection.trim().length > 0) {
+        lines.push((0, sanitize_1.sanitizeField)(data.lineageSection.trimEnd()));
         lines.push('');
     }
     return lines.join('\n');

package/dist/cli/src/commands/task-lineage.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskLineage = taskLineage;
+exports.formatLineageMarkdown = formatLineageMarkdown;
+exports.formatSignalHealth = formatSignalHealth;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+async function taskLineage(identifier, opts) {
+    if (!identifier) {
+        console.error('Error: missing <identifier>. Usage: lumo task lineage <LUM-42>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/tasks/lineage/${encodeURIComponent(identifier)}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        console.error(`Error: task ${identifier} not found in workspace ${creds.workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: lineage fetch failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const data = (await res.json());
+    process.stdout.write(formatLineageMarkdown(data));
+    if (opts?.signal) {
+        const signalUrl = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/lineage/signal`;
+        let signalRes;
+        try {
+            signalRes = await fetch(signalUrl, {
+                headers: { Authorization: `Bearer ${creds.token}` },
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Warning: could not fetch signal health (${msg})\n`);
+            return;
+        }
+        if (!signalRes.ok) {
+            process.stderr.write(`Warning: signal health fetch failed (HTTP ${signalRes.status})\n`);
+            return;
+        }
+        const signalJson = (await signalRes.json());
+        process.stdout.write('\n' + formatSignalHealth(signalJson) + '\n');
+    }
+}
+/** Deterministic thousands separator (no locale dependency, test-stable). */
+function groupThousands(n) {
+    return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+const OUTCOME_ORDER = ['MERGED', 'REWORKED', 'REJECTED', 'UNKNOWN'];
+/** "2 MERGED · 1 UNKNOWN", fixed order, zeros omitted. */
+function outcomeSummary(counts) {
+    const parts = OUTCOME_ORDER.filter(o => counts[o] > 0).map(o => `${counts[o]} ${o}`);
+    return parts.join(' · ');
+}
+function fragmentOutcomeCounts(fragments) {
+    const c = {
+        MERGED: 0,
+        REJECTED: 0,
+        REWORKED: 0,
+        UNKNOWN: 0,
+    };
+    for (const f of fragments)
+        c[f.outcome] += 1;
+    return c;
+}
+function usageMarker(used) {
+    return used === true ? '✓' : used === false ? '✗' : '·';
+}
+/**
+ * Render a LineageResponse as the audit-facing markdown trail. Pure function
+ * (no clock / env) so the CLI output is deterministic and unit-testable.
+ */
+function formatLineageMarkdown(data) {
+    const lines = [];
+    lines.push(`# Lineage: ${data.task.identifier} — ${(0, sanitize_1.sanitizeField)(data.task.title)}`);
+    lines.push(`**Status**: ${data.task.status}`);
+    lines.push('');
+    if (data.groups.length === 0) {
+        lines.push('_No lineage edges recorded yet. Lineage is captured when a ' +
+            "bound session consumes this task's context; once that happens " +
+            '(and a PR merges / the task closes), the causal trail and its cost ' +
+            'will appear here._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    const t = data.totals;
+    lines.push('## Totals');
+    lines.push(`- Runs/sessions: ${t.runCount}`);
+    lines.push(`- Fragments: ${t.fragmentCount}`);
+    lines.push(`- Edges: ${t.edgeCount}`);
+    lines.push(`- Tokens: ${groupThousands(t.tokens.total)} ` +
+        `(in ${groupThousands(t.tokens.input)} · out ${groupThousands(t.tokens.output)} · ` +
+        `cache-read ${groupThousands(t.tokens.cacheRead)} · cache-create ${groupThousands(t.tokens.cacheCreation)})`);
+    lines.push(`- Loops: ${t.loopCount}`);
+    const totalsOutcome = outcomeSummary(t.outcomes);
+    if (totalsOutcome)
+        lines.push(`- Outcomes: ${totalsOutcome}`);
+    lines.push('');
+    for (const g of data.groups) {
+        lines.push(`## ${(0, sanitize_1.sanitizeField)(g.label)} · ${g.includedAt.slice(0, 10)}`);
+        if (g.cost) {
+            lines.push(`**Cost**: ${groupThousands(g.cost.total)} tokens · ${g.cost.loopCount} loops`);
+        }
+        else {
+            lines.push('**Cost**: (no captured cost)');
+        }
+        const summary = outcomeSummary(fragmentOutcomeCounts(g.fragments));
+        lines.push(`**Fragments** (${g.fragments.length}${summary ? `: ${summary}` : ''}):`);
+        lines.push('_✓ used · · abstained · ✗ unused (manual)_');
+        for (const f of g.fragments) {
+            lines.push(`- ${usageMarker(f.used)} [${f.outcome}] ${f.fragmentType} — ${(0, sanitize_1.sanitizeField)(f.sourceLabel)}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatSignalHealth(h) {
+    const lines = ['', '## Signal health'];
+    lines.push(`- Distribution: used ${h.distribution.used} · null ${h.distribution.abstained} · false ${h.distribution.unused}`);
+    lines.push(`- Per-session variance: ${h.perSessionVariance.toFixed(2)} (${h.votedSessions} voted sessions)`);
+    if (h.usedMergeRate !== null && h.baseMergeRate !== null) {
+        lines.push(`- Used × outcome: merge-rate(used) ${Math.round(h.usedMergeRate * 100)}% vs base ${Math.round(h.baseMergeRate * 100)}%`);
+    }
+    else {
+        lines.push('- Used × outcome: insufficient resolved tasks');
+    }
+    return lines.join('\n');
+}

package/dist/cli/src/commands/wrap/fragment-usage-section.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FragmentUsageSection = void 0;
+exports.parseUsedHandles = parseUsedHandles;
+const sanitize_1 = require("../../lib/sanitize");
+const fragment_usage_api_1 = require("../../lib/fragment-usage-api");
+/** Parse "1,3 5" → 0-based indices. "none" → []. */
+function parseUsedHandles(spec) {
+    if (spec.trim().toLowerCase() === 'none')
+        return [];
+    return spec
+        .split(/[\s,]+/)
+        .map(s => s.trim())
+        .filter(Boolean)
+        .map(s => parseInt(s, 10) - 1)
+        .filter(n => Number.isInteger(n) && n >= 0);
+}
+/**
+ * Wrap-panel section (LUM-300) that lists the context fragments this session
+ * consumed and records the agent's vote on which it actually used. Voting is
+ * non-interactive: the agent passes `lumo session wrap --used <indices>` (or
+ * `--used none`). Without `--used`, the section just lists candidates and writes
+ * nothing — edges stay null (honest "not voted"). Already-voted sessions skip.
+ */
+class FragmentUsageSection {
+    deps;
+    title = '上下文使用投票';
+    draft = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async prepare() {
+        this.draft = await (0, fragment_usage_api_1.fetchUsageDraft)(this.deps.creds, this.deps.sessionId);
+        return this.draft.candidates.length > 0;
+    }
+    async run(opts) {
+        const draft = this.draft;
+        if (!draft || draft.candidates.length === 0)
+            return;
+        if (draft.alreadyVoted) {
+            process.stdout.write('本 session 已投票,跳过。\n');
+            return;
+        }
+        process.stdout.write('本次会话注入的 context fragment:\n');
+        draft.candidates.forEach((c, i) => {
+            process.stdout.write(`  [${i + 1}] ${(0, sanitize_1.sanitizeField)(c.label)}\n`);
+        });
+        if (opts.dryRun) {
+            process.stdout.write('(dry-run,未改动)\n');
+            return;
+        }
+        if (this.deps.used === undefined) {
+            process.stdout.write('用 `lumo session wrap --used <序号>`(或 `--used none`)记录你实际用到的 fragment。\n');
+            return;
+        }
+        const idx = parseUsedHandles(this.deps.used);
+        const inRange = (n) => n >= 0 && n < draft.candidates.length;
+        const usedRefs = idx.filter(inRange).map(i => ({
+            fragmentType: draft.candidates[i].fragmentType,
+            fragmentId: draft.candidates[i].fragmentId,
+        }));
+        const { used, unused } = await (0, fragment_usage_api_1.applyFragmentUsage)(this.deps.creds, this.deps.sessionId, { usedRefs });
+        process.stdout.write(`已记录:用过 ${used} 个,未用 ${unused} 个。\n`);
+    }
+}
+exports.FragmentUsageSection = FragmentUsageSection;

package/dist/cli/src/index.js

@@ -73,6 +73,7 @@ const task_web_show_1 = require("./commands/task-web-show");
 const task_figma_context_1 = require("./commands/task-figma-context");
 const task_comment_list_1 = require("./commands/task-comment-list");
 const task_pr_show_1 = require("./commands/task-pr-show");
+const task_lineage_1 = require("./commands/task-lineage");
 const project_list_1 = require("./commands/project-list");
 const milestone_list_1 = require("./commands/milestone-list");
 const milestone_create_1 = require("./commands/milestone-create");
@@ -218,6 +219,7 @@ session
     .description("Session-end wrap-up: draft a progress comment from this session's turn summaries and post it to the bound task after confirmation.")
     .option('-y, --yes', 'Post the drafted comment without prompting (agent-friendly)')
     .option('--dry-run', 'Print the draft but do not post or advance the watermark')
+    .option('--used <indices>', 'Mark which injected context fragments you actually used (1-based indices, comma/space separated; "none" for all-unused). Omit to skip recording.')
     .action(wrap(options => (0, session_wrap_1.sessionWrap)(options)));
 const task = program
     .command('task')
@@ -308,6 +310,11 @@ taskPr
     .command('show <identifier> <number>')
     .description('Show the synced PR record (diff/review comments when available)')
     .action(wrap((id, num) => (0, task_pr_show_1.taskPrShow)(id, num)));
+task
+    .command('lineage <identifier>')
+    .description("Show the causal trail: which context fragments fed this task, each fragment's outcome, and the token/loop cost of the run that consumed it")
+    .option('--signal', 'Append usage-signal health section (fetches /api/lineage/signal)')
+    .action(wrap((id, options) => (0, task_lineage_1.taskLineage)(id, options)));
 const taskMemory = task
     .command('memory')
     .description('View and record memories scoped to a task');

package/dist/cli/src/lib/fragment-usage-api.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchUsageDraft = fetchUsageDraft;
+exports.applyFragmentUsage = applyFragmentUsage;
+const api_1 = require("./api");
+function base(creds) {
+    return (0, api_1.trimTrailingSlash)((0, api_1.resolveAuthedApiUrl)(creds.apiUrl));
+}
+/** GET the fragment-usage draft (this session's injected fragments). */
+async function fetchUsageDraft(creds, sessionId) {
+    const url = `${base(creds)}/api/sessions/${encodeURIComponent(sessionId)}/fragment-usage`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (res.status === 401)
+        throw new Error('API key invalid or revoked. Run `lumo auth login`.');
+    if (!res.ok)
+        throw new Error(`usage draft fetch failed (HTTP ${res.status})`);
+    return (await res.json());
+}
+/** POST the usage vote (used refs). Throws the server message on non-2xx. */
+async function applyFragmentUsage(creds, sessionId, payload) {
+    const url = `${base(creds)}/api/sessions/${encodeURIComponent(sessionId)}/fragment-usage`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+    });
+    if (res.status === 401)
+        throw new Error('API key invalid or revoked. Run `lumo auth login`.');
+    if (!res.ok) {
+        let serverMsg = null;
+        try {
+            const errBody = (await res.json());
+            if (typeof errBody.error === 'string')
+                serverMsg = errBody.error;
+        }
+        catch {
+            // body wasn't JSON
+        }
+        throw new Error(serverMsg ?? `usage vote failed (HTTP ${res.status})`);
+    }
+    return (await res.json());
+}

package/dist/cli/src/lib/hook-runner.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatHookStdoutLines = formatHookStdoutLines;
-exports.formatAutoBindLine = formatAutoBindLine;
+exports.formatSuggestLine = formatSuggestLine;
 exports.resolveSessionStartStdout = resolveSessionStartStdout;
 exports.augmentBodyWithUsage = augmentBodyWithUsage;
 exports.runHook = runHook;
@@ -178,22 +178,26 @@ function sessionContextEnvelope(parts) {
     });
 }
 /**
- * The single status line printed after a successful auto-bind. Explains which
- * git signal (branch name vs recent commit) it relied on and how to undo it.
+ * The single line printed when a task is inferred from local git at session
+ * start. We deliberately do NOT bind — we point the user at the explicit
+ * `lumo session attach` so binding stays a confirmed, manual action. The basis
+ * (branch name vs recent commit) is shown so the inference is auditable. No
+ * task title is available here because nothing was fetched; the title and
+ * context surface only once the user actually attaches.
  */
-function formatAutoBindLine(sessionId, match, result) {
+function formatSuggestLine(sessionId, match) {
     const basis = match.source === 'branch' ? '分支名' : '最近 commit';
-    const identifier = result.taskIdentifier ?? match.identifier;
-    return `[Lumo] session_id=${sessionId} | 已自动绑定 ${identifier} - ${(0, sanitize_1.sanitizeField)(result.taskTitle ?? '')}（依据${basis}）。如果不对，回复"不是"我就帮你解绑。`;
+    return `[Lumo] session_id=${sessionId} | 检测到 ${match.identifier}（依据${basis}）。运行 lumo session attach ${match.identifier} 绑定。`;
 }
 /**
- * Build the stdout lines for a session-start response, including the LUM-145
- * auto-bind behavior: when the server reports no binding, infer the task from
- * local git and bind it; on a hit, print the auto-bind line (plus the freshly
- * bound task's memory). Falls back to the unbound prompt when nothing matches
- * or the bind fails. Bound sessions reuse the existing formatting.
+ * Build the stdout lines for a session-start response. When the server reports
+ * the session is already bound, reuse the bound formatting (status line +
+ * injected context). When it's unbound, infer the task from local git and — on
+ * a hit — print a one-line *suggestion* to run `lumo session attach` (LUM-302:
+ * detect-and-suggest, never auto-bind). No match falls back to the generic
+ * unbound prompt.
  */
-async function resolveSessionStartStdout(responseBody, deps, now = new Date()) {
+function resolveSessionStartStdout(responseBody, deps, now = new Date()) {
     if (responseBody == null || typeof responseBody !== 'object')
         return [];
     const body = responseBody;
@@ -209,58 +213,7 @@ async function resolveSessionStartStdout(responseBody, deps, now = new Date()) {
     const match = deps.extractTask();
     if (!match)
         return [unboundPromptLine(sessionId)];
-    const result = await deps.bindTask(sessionId, match.identifier);
-    if (!result.ok)
-        return [unboundPromptLine(sessionId)];
-    const lines = [formatAutoBindLine(sessionId, match, result)];
-    const card = renderRecoveryCard(result.previousSession, result.taskIdentifier ?? match.identifier, now);
-    // bind-task only returns memory + previousSession (not reviewTodosSection) —
-    // the auto-bind endpoint never built PR-review todos. Keep that scope here;
-    // surfacing review todos on the auto-bind path is a separate change.
-    const envelope = sessionContextEnvelope([card, result.memorySection]);
-    if (envelope)
-        lines.push(envelope);
-    return lines;
-}
-/**
- * POST the inferred task binding to the same `bind-task` endpoint that
- * `lumo session attach` uses. Guarded by the same short timeout as the hook
- * POST so the extra round trip can never make session-start hang. Any
- * failure (404 unknown task, network, timeout, non-2xx) returns
- * `{ ok: false }`, which routes the caller back to the unbound prompt.
- */
-async function postBindTask(sessionId, identifier, token, apiUrl) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-    try {
-        const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/sessions/${encodeURIComponent(sessionId)}/bind-task`;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${token}`,
-            },
-            body: JSON.stringify({ taskIdentifier: identifier }),
-            signal: controller.signal,
-        });
-        if (!res.ok)
-            return { ok: false };
-        const body = (await res.json());
-        return {
-            ok: true,
-            taskIdentifier: body.taskIdentifier,
-            taskTitle: body.taskTitle,
-            memorySection: body.memorySection,
-            previousSession: body.previousSession ?? undefined,
-        };
-    }
-    catch (err) {
-        (0, hook_log_1.logHookError)('[session-start] auto-bind', err);
-        return { ok: false };
-    }
-    finally {
-        clearTimeout(timer);
-    }
+    return [formatSuggestLine(sessionId, match)];
 }
 /**
  * For stop/stop-failure hooks, read the transcript named in the payload and
@@ -285,7 +238,10 @@ function augmentBodyWithUsage(path, body) {
     const usage = (0, transcript_usage_1.sumTranscriptUsage)(transcriptPath);
     if (!usage)
         return body;
-    return JSON.stringify({ ...parsed, _lumo_usage: usage });
+    return JSON.stringify({
+        ...parsed,
+        _lumo_usage: { ...usage.total, byModel: usage.byModel },
+    });
 }
 /**
  * POST the hook body to /api/hooks/<path> with a short timeout. All errors
@@ -348,16 +304,15 @@ async function runHookWithBody(path, body, agentToken) {
             }
             else if (path === 'session-start' || path === 'pre-tool-use') {
                 // Paths that turn the response body into stdout for Claude Code:
-                //   session-start → bind status + injected context (incl. LUM-145
-                //                   auto-bind from local git when unbound)
+                //   session-start → bind status + injected context, or (when unbound)
+                //                   a LUM-302 suggest line inferred from local git
                 //   pre-tool-use  → parallel-edit collision warning (LUM-150 ③)
                 // Only after a 2xx so a transient server failure emits nothing.
                 try {
                     const responseBody = await res.json();
                     const lines = path === 'session-start'
-                        ? await resolveSessionStartStdout(responseBody, {
+                        ? resolveSessionStartStdout(responseBody, {
                             extractTask: () => (0, git_task_1.extractTaskFromGit)(),
-                            bindTask: (sessionId, identifier) => postBindTask(sessionId, identifier, creds.token, apiUrl),
                         })
                         : formatHookStdoutLines(path, responseBody);
                     for (const line of lines) {

package/dist/cli/src/lib/transcript-usage.js

@@ -7,8 +7,10 @@ function asNumber(v) {
 }
 /**
  * Read a Claude Code transcript JSONL and sum `message.usage` across all
- * assistant entries -> cumulative session token totals. Best-effort: returns
- * null if the file can't be read or has no assistant usage. Never throws.
+ * assistant entries, grouped by `message.model` -> cumulative session totals.
+ * `<synthetic>` entries (local injections with no API cost) are skipped.
+ * Entries with no model string bucket under "unknown". Best-effort: returns
+ * null if the file can't be read or has no real assistant usage. Never throws.
  */
 function sumTranscriptUsage(transcriptPath) {
     let text;
@@ -18,6 +20,7 @@ function sumTranscriptUsage(transcriptPath) {
     catch {
         return null;
     }
+    const byModel = {};
     const total = {
         inputTokens: 0,
         outputTokens: 0,
@@ -44,11 +47,31 @@ function sumTranscriptUsage(transcriptPath) {
         const usage = o.message?.usage;
         if (!usage)
             continue;
+        const model = typeof o.message?.model === 'string' && o.message.model.length > 0
+            ? o.message.model
+            : 'unknown';
+        if (model === '<synthetic>')
+            continue;
         seen = true;
-        total.inputTokens += asNumber(usage.input_tokens);
-        total.outputTokens += asNumber(usage.output_tokens);
-        total.cacheReadTokens += asNumber(usage.cache_read_input_tokens);
-        total.cacheCreationTokens += asNumber(usage.cache_creation_input_tokens);
+        const input = asNumber(usage.input_tokens);
+        const output = asNumber(usage.output_tokens);
+        const cacheRead = asNumber(usage.cache_read_input_tokens);
+        const cacheCreation = asNumber(usage.cache_creation_input_tokens);
+        total.inputTokens += input;
+        total.outputTokens += output;
+        total.cacheReadTokens += cacheRead;
+        total.cacheCreationTokens += cacheCreation;
+        const m = byModel[model] ?? {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheCreation: 0,
+        };
+        m.input += input;
+        m.output += output;
+        m.cacheRead += cacheRead;
+        m.cacheCreation += cacheCreation;
+        byModel[model] = m;
     }
-    return seen ? total : null;
+    return seen ? { total, byModel } : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.19.0",
+  "version": "1.20.1",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",