@lumoai/cli 1.20.0 → 1.20.2

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", "进度评论", "卡住检测", "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".'
+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
@@ -49,7 +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>` — 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)
 
@@ -98,7 +98,7 @@ 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] [--used <indices>]` — end-of-session panel: progress comment + memory review + fragment-usage vote (`--used`, LUM-300) + blocked-tag prompt
+- `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)

package/assets/skill/references/memory.md

@@ -34,6 +34,28 @@ When the session is bound (`lumo session attach <LUM-N>`), omit the identifier:
 `lumo task memory add --category trap --trigger ... --outcome ...` records onto
 the bound task; `lumo project memory add ...` records onto its project.
 
+### Reconcile-on-write & deduplication
+
+`memory add` does **not** unconditionally insert a new row. Before writing it:
+
+1. Retrieves the nearest existing memories in the store (embedding similarity).
+2. If a near-duplicate is found — including a **cross-language match** (e.g. you
+   supply content in Chinese but an equivalent English memory already exists) —
+   an LLM decides the outcome; otherwise the new memory is inserted directly.
+
+The command prints **one** of these outcome lines:
+
+| Output line | Meaning |
+|---|---|
+| `Added <CATEGORY> <SCOPE> memory …` | No near-duplicate found; stored as a new row. |
+| `Merged into existing memory <id> (near-duplicate) …` | Near-duplicate found; the existing row was refined/updated in-place (UPDATE). |
+| `Superseded an existing memory; new version <id> …` | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
+| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP). |
+
+Content is **always normalized to English** before storing — the memory store has
+a single canonical language. If you supply text in another language the CLI
+translates it automatically; the stored memory will be in English.
+
 ### When to record a memory (worthiness)
 
 Record only knowledge that is **invisible in the codebase** — the _why_ behind a
@@ -44,7 +66,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/task-context.md

@@ -114,14 +114,14 @@ lumo task pr show LUM-42 128
 Read-only audit view over the task's `LineageEdge` rows. Given a task
 identifier (`LUM-N`), prints the causal trail:
 
-- **Totals banner** — distinct runs/sessions, fragment count, edge count,
+- **Totals banner** — distinct sessions, fragment count, edge count,
   total tokens (input/output/cache split) and loops, and the outcome
   distribution.
-- **One block per run/session** — the group's cost shown **once** (token/loop),
+- **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 run/session (a run that injected many fragments is
+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.
 

package/dist/cli/src/commands/memory-project-add.js

@@ -82,5 +82,27 @@ async function memoryProjectAdd(refArg, options) {
         console.error(m ? `Error: ${(0, sanitize_1.sanitizeField)(m)}` : `Error: memory add failed (HTTP ${res.status})`);
         return 1;
     }
-    process.stdout.write(`Added ${built.category} PROJECT memory${echoSuffix}\n`);
+    let outcome = 'ADD';
+    let memId = '';
+    try {
+        const b = (await res.json());
+        if (typeof b.outcome === 'string')
+            outcome = b.outcome;
+        if (b.memory && typeof b.memory.id === 'string')
+            memId = b.memory.id;
+    }
+    catch { /* keep defaults */ }
+    switch (outcome) {
+        case 'NOOP':
+            process.stdout.write(`Skipped — duplicate of existing memory ${memId}, nothing written${echoSuffix}\n`);
+            break;
+        case 'UPDATE':
+            process.stdout.write(`Merged into existing memory ${memId} (near-duplicate)${echoSuffix}\n`);
+            break;
+        case 'SUPERSEDE':
+            process.stdout.write(`Superseded an existing memory; new version ${memId}${echoSuffix}\n`);
+            break;
+        default:
+            process.stdout.write(`Added ${built.category} PROJECT memory${echoSuffix}\n`);
+    }
 }

package/dist/cli/src/commands/memory-task-add.js

@@ -93,7 +93,29 @@ async function memoryTaskAdd(identifierArg, options) {
         console.error(m ? `Error: ${(0, sanitize_1.sanitizeField)(m)}` : `Error: memory add failed (HTTP ${res.status})`);
         return 1;
     }
-    process.stdout.write(`Added ${built.category} memory to ${identifier}` +
-        `${identifierArg ? '' : ' (from bound session)'}\n` +
-        'Tip: only useful for this task? If it generalizes, use `lumo project memory add` or `lumo memory promote` later.\n');
+    const boundSuffix = identifierArg ? '' : ' (from bound session)';
+    let outcome = 'ADD';
+    let memId = '';
+    try {
+        const b = (await res.json());
+        if (typeof b.outcome === 'string')
+            outcome = b.outcome;
+        if (b.memory && typeof b.memory.id === 'string')
+            memId = b.memory.id;
+    }
+    catch { /* keep defaults */ }
+    switch (outcome) {
+        case 'NOOP':
+            process.stdout.write(`Skipped — duplicate of existing memory ${memId}, nothing written${boundSuffix}\n`);
+            break;
+        case 'UPDATE':
+            process.stdout.write(`Merged into existing memory ${memId} (near-duplicate)${boundSuffix}\n`);
+            break;
+        case 'SUPERSEDE':
+            process.stdout.write(`Superseded an existing memory; new version ${memId}${boundSuffix}\n`);
+            break;
+        default:
+            process.stdout.write(`Added ${built.category} memory to ${identifier}${boundSuffix}\n` +
+                'Tip: only useful for this task? If it generalizes, use `lumo project memory add` or `lumo memory promote` later.\n');
+    }
 }

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

@@ -2,10 +2,11 @@
 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) {
+async function taskLineage(identifier, opts) {
     if (!identifier) {
         console.error('Error: missing <identifier>. Usage: lumo task lineage <LUM-42>');
         return 1;
@@ -42,6 +43,26 @@ async function taskLineage(identifier) {
     }
     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) {
@@ -64,6 +85,9 @@ function fragmentOutcomeCounts(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.
@@ -75,7 +99,7 @@ function formatLineageMarkdown(data) {
     lines.push('');
     if (data.groups.length === 0) {
         lines.push('_No lineage edges recorded yet. Lineage is captured when a ' +
-            "session-bound run consumes this task's context; once that happens " +
+            "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('');
@@ -104,10 +128,23 @@ function formatLineageMarkdown(data) {
         }
         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(`- [${f.outcome}] ${f.fragmentType} — ${(0, sanitize_1.sanitizeField)(f.sourceLabel)}`);
+            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/index.js

@@ -313,7 +313,8 @@ taskPr
 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")
-    .action(wrap(id => (0, task_lineage_1.taskLineage)(id)));
+    .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/transcript-usage.js

@@ -2,31 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sumTranscriptUsage = sumTranscriptUsage;
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 function asNumber(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : 0;
 }
 /**
- * Read a Claude Code transcript JSONL and sum `message.usage` across all
- * 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.
+ * Sum `message.usage` across all (non-synthetic) assistant entries of one
+ * transcript JSONL file into the shared accumulators. Returns true if at
+ * least one real usage entry was seen. Never throws.
  */
-function sumTranscriptUsage(transcriptPath) {
+function accumulateFileUsage(path, total, byModel) {
     let text;
     try {
-        text = (0, node_fs_1.readFileSync)(transcriptPath, 'utf8');
+        text = (0, node_fs_1.readFileSync)(path, 'utf8');
     }
     catch {
-        return null;
+        return false;
     }
-    const byModel = {};
-    const total = {
-        inputTokens: 0,
-        outputTokens: 0,
-        cacheReadTokens: 0,
-        cacheCreationTokens: 0,
-    };
     let seen = false;
     for (const raw of text.split('\n')) {
         const line = raw.trim();
@@ -73,5 +65,46 @@ function sumTranscriptUsage(transcriptPath) {
         m.cacheCreation += cacheCreation;
         byModel[model] = m;
     }
+    return seen;
+}
+/**
+ * Subagent (Task tool) turns are NOT in the main transcript — Claude Code
+ * writes them to sibling files at `<dir>/<sessionId>/subagents/agent-*.jsonl`.
+ * Resolve those for a main transcript path. Best-effort: returns [] when the
+ * directory is missing or unreadable. Never throws.
+ */
+function listSubagentTranscripts(transcriptPath) {
+    if (!transcriptPath.endsWith('.jsonl'))
+        return [];
+    const subagentsDir = (0, node_path_1.join)(transcriptPath.slice(0, -'.jsonl'.length), 'subagents');
+    try {
+        return (0, node_fs_1.readdirSync)(subagentsDir)
+            .filter(name => name.startsWith('agent-') && name.endsWith('.jsonl'))
+            .map(name => (0, node_path_1.join)(subagentsDir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read a Claude Code transcript JSONL — plus any subagent transcripts under
+ * `<dir>/<sessionId>/subagents/agent-*.jsonl` — and sum `message.usage`
+ * across all (non-synthetic) assistant entries, grouped by `message.model`
+ * -> cumulative session totals. Entries with no model string bucket under
+ * "unknown". Best-effort: returns null if nothing readable has real
+ * assistant usage. Never throws.
+ */
+function sumTranscriptUsage(transcriptPath) {
+    const byModel = {};
+    const total = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+    };
+    let seen = accumulateFileUsage(transcriptPath, total, byModel);
+    for (const path of listSubagentTranscripts(transcriptPath)) {
+        seen = accumulateFileUsage(path, total, byModel) || seen;
+    }
     return seen ? { total, byModel } : null;
 }

package/package.json

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