@lumoai/cli 1.17.0 → 1.18.0

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".'
+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".'
 ---
 
 ## Prerequisites
@@ -30,6 +30,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `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)               |
+| `worktree add/rm/list` (local dev tooling)                                        | [references/worktree.md](references/worktree.md)               |
 
 ## Command catalog
 
@@ -99,6 +100,12 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `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
 
+**Worktrees (local dev tooling)** — see [worktree.md](references/worktree.md)
+
+- `lumo worktree add <LUM-N> [slug]` — scaffold `.worktrees/<LUM-N>` + node_modules symlink off origin/main; run from the main checkout
+- `lumo worktree rm <LUM-N> --yes` — remove a worktree (keeps the branch unless `--delete-branch`)
+- `lumo worktree list` — list `.worktrees/` worktrees (task id, branch, dirty, node_modules link)
+
 ## Core workflow
 
 Typical flow when a user says "help me with LUM-42":

package/assets/skill/references/sessions.md

@@ -49,6 +49,21 @@ What it does:
 
 **After attaching, always run `lumo task context <identifier>` to load the task background.**
 
+#### Overwriting an existing binding (LUM-266)
+
+Re-attaching a session that's already bound to a **different** task no longer silently clobbers the binding. The server returns the current binding instead of overwriting, and the CLI decides what to do:
+
+- **On a TTY** (a human running it directly): prompts `已绑定 LUM-X，覆盖为 LUM-Y? [y/N]`. Answering `y`/`yes` re-binds to `LUM-Y`; anything else (including bare Enter) cancels and leaves `LUM-X` bound.
+- **Off a TTY** (the usual agent case — `stdin` is not interactive): the command **refuses** and prints `Session already bound to LUM-X … Re-run with --force …` without overwriting. Exit code is `0` (a safe refusal, not an error).
+- **`--force`**: skips the prompt/refusal and overwrites unconditionally. Re-attaching to the **same** task is always a no-op re-bind (never prompts).
+
+```bash
+lumo session attach LUM-42            # already on LUM-7 → prompts (TTY) / refuses (agent)
+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`.
+
 ### Parallel sessions
 
 Each Claude Code session has its own `CLAUDE_CODE_SESSION_ID`. Two terminals running `claude code` and binding to different tasks will not interfere with each other — the bindings are scoped per session row server-side.

package/assets/skill/references/worktree.md

@@ -0,0 +1,60 @@
+# Worktrees
+
+Local dev tooling that scaffolds parallel git worktrees. Unlike every other
+`lumo` command, these do **not** touch the Lumo server — they shell out to git
+and the local filesystem. **Run `add` and `rm` from the main checkout**, not from
+inside a worktree (the node_modules symlink source and `.worktrees/` both live
+there); `list` is read-only and runnable from anywhere.
+
+## `lumo worktree add <LUM-N> [slug]`
+
+Creates `.worktrees/<LUM-N>[-slug]` on branch `lumo/<LUM-N>[-slug]`, branched off
+`origin/main` (after a fetch), and symlinks its `node_modules` to the main
+checkout so jest/tsc work immediately. With no slug, the dir and branch use the
+bare `LUM-N` form. Prints next-step guidance plus the two gotchas it can't fix
+for you (shared prisma client, jest cwd).
+
+```bash
+lumo worktree add LUM-267 worktree-scaffold   # → .worktrees/LUM-267-worktree-scaffold
+lumo worktree add LUM-267                      # → .worktrees/LUM-267
+lumo worktree add LUM-267 --base main          # branch off local main, skip fetch
+lumo worktree add LUM-267 --no-fetch           # branch off existing origin/main
+lumo worktree add LUM-267 --verify             # run npx jest baseline after setup
+```
+
+Flags: `--base <ref>` (branch off a ref other than origin/main; skips the
+fetch), `--no-fetch` (skip `git fetch origin main`), `--verify` (run `npx jest`
+in the new worktree). Errors if the target dir already exists; reuses the branch
+if it already exists (adds the worktree without `-b`).
+
+**The prisma gotcha it warns about:** the generated client lives in the shared
+(symlinked) `node_modules`, so a `prisma generate` in one worktree clobbers the
+client every parallel worktree depends on. Verify with jest (SWC mocks Prisma);
+do `generate + tsc` atomically once at the end.
+
+**The jest gotcha it warns about:** always run jest from the worktree root (`cd`
+in first) — `cli/` has no jest config, and running from the main checkout hits
+the `cli/package.json` haste collision and silently runs the wrong tests.
+
+## `lumo worktree rm <LUM-N>`
+
+Removes the worktree for a task. Requires `--yes`. Refuses a dirty worktree
+unless `--force`. Keeps the branch by default (it may hold unpushed work / an
+open PR); `--delete-branch` removes it with `git branch -d` (which itself
+refuses an unmerged branch).
+
+```bash
+lumo worktree rm LUM-267 --yes
+lumo worktree rm LUM-267 --yes --force            # discard uncommitted changes
+lumo worktree rm LUM-267 --yes --delete-branch    # also delete lumo/LUM-267…
+```
+
+## `lumo worktree list`
+
+Lists worktrees under `.worktrees/` with task id, branch, dirty state, and
+whether `node_modules` is symlinked (a `MISSING` link is the first thing to
+check when jest/tsc misbehaves). Read-only; runnable from anywhere in the repo.
+
+```bash
+lumo worktree list
+```

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

@@ -4,6 +4,7 @@ exports.sessionAttach = sessionAttach;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const sanitize_1 = require("../lib/sanitize");
+const line_prompt_1 = require("../lib/line-prompt");
 /**
  * `lumo session attach <identifier>` — bind the currently-running
  * Claude Code session to a task.
@@ -14,8 +15,15 @@ const sanitize_1 = require("../lib/sanitize");
  *
  * The binding lives entirely on the server (`Session.taskId`); subsequent
  * hooks read it back via the session row. The CLI keeps no local sentinel.
+ *
+ * Re-binding a session that's already attached to a *different* task no
+ * longer silently clobbers `Session.taskId` (LUM-266): the server returns
+ * the current binding and we confirm before overwriting —
+ *   - `--force` skips the prompt and overwrites directly;
+ *   - on a TTY we ask `已绑定 LUM-X，覆盖为 LUM-Y? [y/N]`;
+ *   - off a TTY (the usual agent case) we refuse and point at `--force`.
  */
-async function sessionAttach(identifier) {
+async function sessionAttach(identifier, options = {}) {
     if (!identifier) {
         console.error('Error: missing <identifier>. Usage: lumo session attach <LUM-42>');
         return 1;
@@ -33,48 +41,79 @@ async function sessionAttach(identifier) {
     }
     const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
     const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/sessions/${encodeURIComponent(sessionId)}/bind-task`;
-    let res;
-    try {
-        res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${creds.token}`,
-            },
-            body: JSON.stringify({ taskIdentifier: identifier }),
-        });
-    }
-    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) {
-        let message = 'Not found';
+    const bind = async (force) => {
+        let res;
         try {
-            const body = (await res.json());
-            if (body.error)
-                message = body.error;
+            res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${creds.token}`,
+                },
+                body: JSON.stringify({ taskIdentifier: identifier, force }),
+            });
         }
-        catch {
-            // fall through
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+            return { ok: false, code: 1 };
         }
-        console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
-        return 1;
+        if (res.status === 401) {
+            console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+            return { ok: false, code: 1 };
+        }
+        if (res.status === 404) {
+            let message = 'Not found';
+            try {
+                const data = (await res.json());
+                if (data.error)
+                    message = data.error;
+            }
+            catch {
+                // fall through
+            }
+            console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
+            return { ok: false, code: 1 };
+        }
+        if (!res.ok) {
+            console.error(`Error: bind-task failed (HTTP ${res.status})`);
+            return { ok: false, code: 1 };
+        }
+        return { ok: true, body: (await res.json()) };
+    };
+    // First attempt. `--force` overwrites unconditionally; otherwise the server
+    // may answer `already-bound` so we can confirm before clobbering.
+    const first = await bind(options.force === true);
+    if (!first.ok)
+        return first.code;
+    let body = first.body;
+    if (body.status === 'already-bound') {
+        // Reached only when not forced (force=true would have overwritten).
+        if (!process.stdin.isTTY) {
+            console.error(`Session already bound to ${body.currentTaskIdentifier} "${(0, sanitize_1.sanitizeField)(body.currentTaskTitle)}". ` +
+                `Not overwriting. Re-run with --force to switch to ${identifier} ` +
+                '(or run `lumo session detach` first).');
+            return 0;
+        }
+        const answer = await (0, line_prompt_1.promptLine)(`已绑定 ${body.currentTaskIdentifier}，覆盖为 ${identifier}? [y/N] `);
+        if (!/^y(es)?$/i.test(answer)) {
+            console.log(`已取消，仍绑定 ${body.currentTaskIdentifier}。`);
+            return 0;
+        }
+        const second = await bind(true);
+        if (!second.ok)
+            return second.code;
+        body = second.body;
     }
-    if (!res.ok) {
-        console.error(`Error: bind-task failed (HTTP ${res.status})`);
+    if (body.status === 'already-bound') {
+        // Defensive: a forced bind should never report already-bound.
+        console.error(`Error: bind did not take effect (still bound to ${body.currentTaskIdentifier}).`);
         return 1;
     }
-    const result = (await res.json());
-    console.log(`Attached session ${sessionId} to ${result.taskIdentifier} "${(0, sanitize_1.sanitizeField)(result.taskTitle)}"`);
-    console.log(`Re-tagged ${result.retaggedEventCount} previously-untagged event${result.retaggedEventCount === 1 ? '' : 's'} in this session.`);
-    if (result.memorySection !== '') {
+    console.log(`Attached session ${sessionId} to ${body.taskIdentifier} "${(0, sanitize_1.sanitizeField)(body.taskTitle)}"`);
+    console.log(`Re-tagged ${body.retaggedEventCount} previously-untagged event${body.retaggedEventCount === 1 ? '' : 's'} in this session.`);
+    if (body.memorySection !== '') {
         console.log('');
-        console.log((0, sanitize_1.sanitizeField)(result.memorySection));
+        console.log((0, sanitize_1.sanitizeField)(body.memorySection));
     }
 }

package/dist/cli/src/commands/worktree-add.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktreeAdd = worktreeAdd;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const worktree_1 = require("../lib/worktree");
+function printGuidance(dir, branch) {
+    console.log('');
+    console.log(`✓ Worktree ready: ${dir}`);
+    console.log(`  branch:        ${branch}`);
+    console.log(`  node_modules:  symlinked to main checkout`);
+    console.log('');
+    console.log('Next:');
+    console.log(`  cd ${dir}`);
+    console.log('');
+    console.log('Gotchas baked into this worktree:');
+    console.log('  • prisma: the generated client is SHARED via the node_modules symlink.');
+    console.log("          Don't run `prisma generate` mid-work across parallel worktrees;");
+    console.log('          verify with jest, and do generate+tsc atomically once at the end.');
+    console.log('  • jest:   always run it from INSIDE this worktree (cd first), or the');
+    console.log('          cli/package.json haste collision silently runs the wrong tests.');
+}
+async function worktreeAdd(rawId, slug, opts) {
+    const taskId = (0, worktree_1.normalizeTaskId)(rawId);
+    if (!taskId) {
+        console.error(`Error: "${rawId}" is not a task id (expected LUM-N or N)`);
+        return 1;
+    }
+    if (!(0, worktree_1.isMainCheckout)()) {
+        console.error('Error: run `lumo worktree add` from the main checkout, not inside a worktree');
+        return 1;
+    }
+    const root = (0, worktree_1.getRepoRoot)();
+    const branch = (0, worktree_1.deriveBranchName)(taskId, slug);
+    const dir = path.join(root, '.worktrees', (0, worktree_1.deriveWorktreeDirName)(taskId, slug));
+    if (fs.existsSync(dir)) {
+        console.error(`Error: ${dir} already exists — remove it first or pick a different slug`);
+        return 1;
+    }
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    const base = opts.base ?? 'origin/main';
+    if (!opts.noFetch && !opts.base) {
+        console.log('Fetching origin/main …');
+        if ((0, worktree_1.runGit)(['fetch', 'origin', 'main'], root).status !== 0) {
+            console.error(`Warning: git fetch failed; branching off the existing local ${base} (may be stale)`);
+        }
+    }
+    const branchExists = (0, worktree_1.runGit)(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], root)
+        .status === 0;
+    const addArgs = branchExists
+        ? ['worktree', 'add', dir, branch]
+        : ['worktree', 'add', dir, '-b', branch, base];
+    const added = (0, worktree_1.runGit)(addArgs, root);
+    if (added.status !== 0) {
+        console.error(`Error: ${(added.stderr || '').trim() || 'git worktree add failed'}`);
+        return 1;
+    }
+    const srcModules = path.join(root, 'node_modules');
+    if (fs.existsSync(srcModules)) {
+        fs.symlinkSync(srcModules, path.join(dir, 'node_modules'));
+    }
+    else {
+        console.log('Warning: main checkout has no node_modules; run `npm install` there, then symlink manually');
+    }
+    printGuidance(dir, branch);
+    if (opts.verify) {
+        console.log('Running baseline jest …');
+        const j = (0, child_process_1.spawnSync)('npx', ['jest'], { cwd: dir, stdio: 'inherit' });
+        if (j.status !== 0) {
+            console.error('Warning: baseline jest did not pass cleanly');
+        }
+    }
+    return 0;
+}

package/dist/cli/src/commands/worktree-list.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktreeList = worktreeList;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const worktree_1 = require("../lib/worktree");
+const git_task_1 = require("../lib/git-task");
+function nodeModulesLinked(dir) {
+    try {
+        return fs.lstatSync(path.join(dir, 'node_modules')).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Pull a LUM-N from a worktree dir basename or its branch, else '—'. */
+function taskIdOf(dirBase, branch) {
+    return ((0, git_task_1.matchTaskIdentifier)(dirBase) ??
+        (branch ? (0, git_task_1.matchTaskIdentifier)(branch) : null) ??
+        '—');
+}
+async function worktreeList() {
+    const mainRoot = path.dirname((0, worktree_1.getGitCommonDir)());
+    const worktreesDir = path.join(mainRoot, '.worktrees');
+    const entries = (0, worktree_1.parseWorktreePorcelain)((0, worktree_1.gitOutput)(['worktree', 'list', '--porcelain'], mainRoot)).filter(e => e.path.startsWith(worktreesDir + path.sep));
+    if (entries.length === 0) {
+        console.log('(no worktrees under .worktrees/)');
+        return 0;
+    }
+    for (const e of entries) {
+        const base = path.basename(e.path);
+        const id = taskIdOf(base, e.branch);
+        const dirty = (0, worktree_1.gitOutput)(['status', '--porcelain'], e.path).length > 0
+            ? 'dirty'
+            : 'clean';
+        const nm = nodeModulesLinked(e.path) ? 'linked' : 'MISSING';
+        console.log(`${id}\t${e.branch ?? '(detached)'}\t${dirty}\tnode_modules:${nm}\t${e.path}`);
+    }
+    return 0;
+}

package/dist/cli/src/commands/worktree-rm.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktreeRm = worktreeRm;
+const worktree_1 = require("../lib/worktree");
+async function worktreeRm(rawId, opts) {
+    const taskId = (0, worktree_1.normalizeTaskId)(rawId);
+    if (!taskId) {
+        console.error(`Error: "${rawId}" is not a task id (expected LUM-N or N)`);
+        return 1;
+    }
+    if (!(0, worktree_1.isMainCheckout)()) {
+        console.error('Error: run `lumo worktree rm` from the main checkout, not inside a worktree');
+        return 1;
+    }
+    const root = (0, worktree_1.getRepoRoot)();
+    const entries = (0, worktree_1.parseWorktreePorcelain)((0, worktree_1.gitOutput)(['worktree', 'list', '--porcelain'], root));
+    const target = (0, worktree_1.findWorktreeByTaskId)(entries, taskId);
+    if (!target) {
+        console.error(`Error: no worktree found for ${taskId}`);
+        return 1;
+    }
+    if (!opts.yes) {
+        console.error(`Error: refusing to remove ${target.path} without --yes (destructive)`);
+        return 1;
+    }
+    const dirty = (0, worktree_1.gitOutput)(['status', '--porcelain'], target.path).length > 0;
+    if (dirty && !opts.force) {
+        console.error(`Error: ${target.path} has uncommitted changes — pass --force to remove anyway`);
+        return 1;
+    }
+    const removeArgs = dirty && opts.force
+        ? ['worktree', 'remove', '--force', target.path]
+        : ['worktree', 'remove', target.path];
+    const removed = (0, worktree_1.runGit)(removeArgs, root);
+    if (removed.status !== 0) {
+        console.error(`Error: ${(removed.stderr || '').trim() || 'git worktree remove failed'}`);
+        return 1;
+    }
+    console.log(`✓ Removed worktree ${target.path}`);
+    if (opts.deleteBranch && target.branch) {
+        const del = (0, worktree_1.runGit)(['branch', '-d', target.branch], root);
+        if (del.status !== 0) {
+            console.error(`Warning: could not delete branch ${target.branch}: ${(del.stderr || '').trim()}`);
+        }
+        else {
+            console.log(`✓ Deleted branch ${target.branch}`);
+        }
+    }
+    else if (target.branch) {
+        console.log(`  branch ${target.branch} kept (use --delete-branch to remove)`);
+    }
+    return 0;
+}

package/dist/cli/src/index.js

@@ -111,6 +111,9 @@ const doc_share_list_1 = require("./commands/doc-share-list");
 const doc_move_1 = require("./commands/doc-move");
 const update_1 = require("./commands/update");
 const setup_1 = require("./commands/setup");
+const worktree_add_1 = require("./commands/worktree-add");
+const worktree_rm_1 = require("./commands/worktree-rm");
+const worktree_list_1 = require("./commands/worktree-list");
 const update_check_1 = require("./lib/update-check");
 const sanitize_1 = require("./lib/sanitize");
 // Resolve package.json relative to __dirname so this works regardless of how
@@ -199,8 +202,9 @@ const session = program
     .description('Manage per-terminal coding-session context');
 session
     .command('attach <identifier>')
-    .description('Attach the currently-running Claude Code session (CLAUDE_CODE_SESSION_ID) to a task. Sets Session.taskId server-side and re-tags untagged hook events.')
-    .action(wrap(identifier => (0, session_attach_1.sessionAttach)(identifier)));
+    .description('Attach the currently-running Claude Code session (CLAUDE_CODE_SESSION_ID) to a task. Sets Session.taskId server-side and re-tags untagged hook events. If the session is already bound to a different task, confirms before overwriting (use --force to skip).')
+    .option('--force', 'Overwrite an existing binding to a different task without confirmation (skips the [y/N] prompt).')
+    .action(wrap((identifier, options) => (0, session_attach_1.sessionAttach)(identifier, options)));
 session
     .command('status')
     .description('Show the task currently bound to this Claude Code session (or "no task" if none).')
@@ -654,6 +658,34 @@ task
     .option('--remove-tag <name>', 'Remove tag by name (repeatable). Unknown names are find-or-create, so prefer --remove-tag-id to avoid orphan rows.', collect, [])
     .option('--remove-tag-id <cuid>', 'Remove tag by id (repeatable). Unknown ids are a no-op.', collect, [])
     .action(wrap((identifier, options) => (0, task_update_1.taskUpdate)(identifier, options)));
+const worktree = program
+    .command('worktree')
+    .description('Scaffold, remove, and list parallel git worktrees under .worktrees/ (node_modules symlink + prisma/jest gotcha guidance). Local dev tooling; run from the main checkout.');
+worktree
+    .command('add <identifier> [slug]')
+    .description('Create a worktree at .worktrees/<LUM-N>[-slug] on branch lumo/<LUM-N>[-slug] off origin/main, symlink node_modules to the main checkout, and print prisma/jest guidance. Run from the main checkout.')
+    .option('--base <ref>', 'Branch off this ref instead of origin/main (skips fetch)')
+    .option('--no-fetch', 'Do not `git fetch origin main` before branching')
+    .option('--verify', 'Run `npx jest` in the new worktree to confirm a clean baseline')
+    .action(wrap((identifier, slug, options) => {
+    const o = options;
+    return (0, worktree_add_1.worktreeAdd)(identifier, slug, {
+        base: o.base,
+        noFetch: o.fetch === false,
+        verify: o.verify,
+    });
+}));
+worktree
+    .command('rm <identifier>')
+    .description('Remove the worktree for a task (git worktree remove). Requires --yes. Refuses a dirty worktree unless --force. Keeps the branch unless --delete-branch.')
+    .option('--yes', 'Confirm removal (required, no interactive prompt)')
+    .option('--force', 'Remove even with uncommitted changes')
+    .option('--delete-branch', 'Also delete the branch (git branch -d; refuses if unmerged)')
+    .action(wrap((identifier, options) => (0, worktree_rm_1.worktreeRm)(identifier, options)));
+worktree
+    .command('list')
+    .description('List worktrees under .worktrees/: task id, branch, dirty state, and whether node_modules is symlinked.')
+    .action(wrap(() => (0, worktree_list_1.worktreeList)()));
 // Claude Code invokes `lumo hook <type>` per tool call, so these handlers
 // must never crash the caller. Two invariants keep us safe:
 //   1. `hookCommand` is stderr-silent and never throws (it catches internally

package/dist/cli/src/lib/worktree.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTaskId = normalizeTaskId;
+exports.slugify = slugify;
+exports.deriveBranchName = deriveBranchName;
+exports.deriveWorktreeDirName = deriveWorktreeDirName;
+exports.parseWorktreePorcelain = parseWorktreePorcelain;
+exports.findWorktreeByTaskId = findWorktreeByTaskId;
+exports.runGit = runGit;
+exports.gitOutput = gitOutput;
+exports.getGitDir = getGitDir;
+exports.getGitCommonDir = getGitCommonDir;
+exports.isMainCheckout = isMainCheckout;
+exports.getRepoRoot = getRepoRoot;
+/**
+ * Normalize a user-supplied task reference to canonical `LUM-<n>` form.
+ * Accepts `LUM-267`, `lum-267`, and bare `267`. Returns null for anything
+ * that is not a recognizable task id.
+ */
+function normalizeTaskId(input) {
+    const trimmed = input.trim();
+    const prefixed = trimmed.match(/^lum-?(\d+)$/i);
+    if (prefixed)
+        return `LUM-${prefixed[1]}`;
+    const bare = trimmed.match(/^(\d+)$/);
+    if (bare)
+        return `LUM-${bare[1]}`;
+    return null;
+}
+/**
+ * Turn an arbitrary human slug into a branch/dir-safe segment: lowercase,
+ * non-alphanumeric runs collapse to a single dash, leading/trailing dashes
+ * stripped.
+ */
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** `lumo/LUM-267` or `lumo/LUM-267-<slug>`. */
+function deriveBranchName(taskId, slug) {
+    const s = slug ? slugify(slug) : '';
+    return s ? `lumo/${taskId}-${s}` : `lumo/${taskId}`;
+}
+/** `.worktrees/` dir basename: `LUM-267` or `LUM-267-<slug>`. */
+function deriveWorktreeDirName(taskId, slug) {
+    const s = slug ? slugify(slug) : '';
+    return s ? `${taskId}-${s}` : taskId;
+}
+const path = __importStar(require("path"));
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ * Records are separated by blank lines; a detached worktree has a `detached`
+ * line instead of `branch`. Tolerates a final record with no trailing blank.
+ */
+function parseWorktreePorcelain(output) {
+    const entries = [];
+    let cur = null;
+    const flush = () => {
+        if (cur)
+            entries.push(cur);
+        cur = null;
+    };
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            flush();
+            cur = { path: line.slice('worktree '.length), head: '', branch: null };
+        }
+        else if (!cur) {
+            continue;
+        }
+        else if (line.startsWith('HEAD ')) {
+            cur.head = line.slice('HEAD '.length);
+        }
+        else if (line.startsWith('branch ')) {
+            cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        }
+        else if (line === '') {
+            flush();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Find the worktree belonging to a task id. Matches either the branch
+ * (`lumo/LUM-267` exactly or `lumo/LUM-267-*`) or the directory basename
+ * (`LUM-267` exactly or `LUM-267-*`).
+ */
+function findWorktreeByTaskId(entries, taskId) {
+    return (entries.find(e => {
+        const base = path.basename(e.path);
+        const branchMatch = e.branch === `lumo/${taskId}` ||
+            (e.branch?.startsWith(`lumo/${taskId}-`) ?? false);
+        const dirMatch = base === taskId || base.startsWith(`${taskId}-`);
+        return branchMatch || dirMatch;
+    }) ?? null);
+}
+const child_process_1 = require("child_process");
+/** Low-level git runner — returns the raw spawn result, never throws on exit. */
+function runGit(args, cwd) {
+    // 120s is a safety net against a genuine hang (e.g. an index.lock deadlock),
+    // NOT a tight bound: this wrapper runs legitimately-slow ops like `git fetch`
+    // and `git worktree add`, which must not be killed prematurely. On timeout
+    // spawnSync populates `r.error`, which gitOutput already rethrows.
+    return (0, child_process_1.spawnSync)('git', args, { cwd, encoding: 'utf8', timeout: 120_000 });
+}
+/**
+ * Run git and return trimmed stdout; THROWS with stderr on non-zero exit or
+ * spawn error. NOTE: unlike the same-named `gitOutput` in `cli/src/lib/git-task.ts`
+ * (which swallows failures and returns `''`), this one surfaces failures by
+ * throwing — callers must handle/expect the throw.
+ */
+function gitOutput(args, cwd) {
+    const r = runGit(args, cwd);
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0) {
+        throw new Error((r.stderr || '').trim() || `git ${args.join(' ')} failed`);
+    }
+    return (r.stdout ?? '').trim();
+}
+/** Absolute path to the worktree-local `.git` (file or dir). */
+function getGitDir(cwd) {
+    return gitOutput(['rev-parse', '--absolute-git-dir'], cwd);
+}
+/** Absolute path to the shared `.git` (same as git-dir in the main checkout). */
+function getGitCommonDir(cwd) {
+    const common = gitOutput(['rev-parse', '--git-common-dir'], cwd);
+    return path.resolve(cwd ?? process.cwd(), common);
+}
+/** True only in the main checkout (git-dir === common-dir). */
+function isMainCheckout(cwd) {
+    return getGitDir(cwd) === getGitCommonDir(cwd);
+}
+/** Absolute repo root of the current working tree. */
+function getRepoRoot(cwd) {
+    return gitOutput(['rev-parse', '--show-toplevel'], cwd);
+}

package/package.json

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