@lumoai/cli 1.27.0 → 1.29.0

package/dist/cli/src/commands/doc-section-edit.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSectionEditLine = formatSectionEditLine;
+exports.docPatch = docPatch;
+exports.docAppend = docAppend;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_input_1 = require("../lib/doc-input");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
+function formatSectionEditLine(args) {
+    const escaped = (0, sanitize_1.sanitizeField)(args.title).replace(/"/g, '\\"');
+    const target = args.sectionHeading
+        ? ` § "${(0, sanitize_1.sanitizeField)(args.sectionHeading)}"`
+        : ' (document end)';
+    const rev = args.revision !== null ? `  revision ${args.revision}` : '';
+    return `${args.verb} ${args.id} "${escaped}"${target}${rev}`;
+}
+async function docSectionEdit(mode, reference, opts) {
+    const cmd = mode === 'replace' ? 'patch' : 'append';
+    if (!reference) {
+        console.error(`Error: missing <doc>. Usage: lumo doc ${cmd} <doc> ${mode === 'replace' ? '--section <heading>' : '[--section <heading>]'} [--content <md> | --file <path> | stdin] [--if-revision <n>]`);
+        return 1;
+    }
+    if (mode === 'replace' && (!opts.section || opts.section.trim() === '')) {
+        console.error('Error: --section <heading> is required for doc patch');
+        return 1;
+    }
+    let ifRevision;
+    if (opts.ifRevision !== undefined) {
+        if (!/^\d+$/.test(opts.ifRevision)) {
+            console.error(`Error: --if-revision must be a non-negative integer (got "${opts.ifRevision}")`);
+            return 1;
+        }
+        ifRevision = Number(opts.ifRevision);
+    }
+    const content = await (0, doc_input_1.resolveDocContent)({
+        content: opts.content,
+        file: opts.file,
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+        readStdin: doc_input_1.readStdinToString,
+        readFile: doc_input_1.readFileUtf8,
+    });
+    if (content.kind === 'error') {
+        console.error(`Error: ${content.message}`);
+        return 1;
+    }
+    if (content.kind === 'none') {
+        console.error(`Error: doc ${cmd} needs content — pass --content, --file, or pipe stdin`);
+        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 id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
+    if (!id) {
+        console.error(`Error: Document not found: ${reference}`);
+        return 1;
+    }
+    const body = {
+        mode,
+        contentMarkdown: content.markdown,
+    };
+    if (opts.section !== undefined && opts.section.trim() !== '') {
+        body.section = opts.section;
+    }
+    if (ifRevision !== undefined)
+        body.ifRevision = ifRevision;
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}/section`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch {
+            // non-JSON error body — print as-is
+        }
+        if (res.status === 409) {
+            console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}), rebase your edit on it, then retry with --if-revision <current>.`);
+            return 1;
+        }
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(message)}`);
+        return 1;
+    }
+    const { document } = (await res.json());
+    console.log(formatSectionEditLine({
+        verb: mode === 'replace' ? 'Patched' : 'Appended to',
+        id: document.id,
+        title: document.title,
+        sectionHeading: document.sectionHeading ?? opts.section ?? null,
+        revision: typeof document.contentRevision === 'number'
+            ? document.contentRevision
+            : null,
+    }));
+}
+function docPatch(reference, opts) {
+    return docSectionEdit('replace', reference, opts);
+}
+function docAppend(reference, opts) {
+    return docSectionEdit('append', reference, opts);
+}

package/dist/cli/src/commands/doc-show.js

@@ -5,6 +5,7 @@ exports.docShow = docShow;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const markdown_tiptap_1 = require("../lib/markdown-tiptap");
+const markdown_sections_1 = require("../lib/markdown-sections");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
 const sanitize_1 = require("../lib/sanitize");
 function scopeLabel(s) {
@@ -22,6 +23,7 @@ function formatShowOutput(vm) {
         `Project: ${vm.projectName ? (0, sanitize_1.sanitizeField)(vm.projectName) : '-'}`,
         `Created: ${vm.createdAt}`,
         `Updated: ${vm.updatedAt}`,
+        `Revision: ${vm.revision ?? '-'}`,
         `Mentioned tasks: ${vm.mentionedTasks.length ? vm.mentionedTasks.join(', ') : '-'}`,
     ];
     const header = lines.join('\n');
@@ -29,7 +31,11 @@ function formatShowOutput(vm) {
 }
 async function docShow(reference, opts = {}) {
     if (!reference) {
-        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw]');
+        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw | --section <heading>]');
+        return 1;
+    }
+    if (opts.raw && opts.section !== undefined) {
+        console.error('Error: --raw and --section are mutually exclusive (--raw prints the whole source)');
         return 1;
     }
     const creds = (0, config_1.readCredentials)();
@@ -73,6 +79,46 @@ async function docShow(reference, opts = {}) {
             return 1;
         }
         process.stdout.write(d.sourceMarkdown);
+        // Revision goes to stderr so stdout stays a byte-pure edit base while
+        // the agent still sees the number to pass back as --if-revision.
+        if (typeof d.contentRevision === 'number') {
+            console.error(`Revision: ${d.contentRevision}`);
+        }
+        return;
+    }
+    if (opts.section !== undefined) {
+        // Section reads slice the stored markdown source — same no-fallback rule
+        // as --raw: a rendered-output slice would not be a legal edit base.
+        if (typeof d.sourceMarkdown !== 'string') {
+            console.error(`Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
+                `or predates markdown source storage), so --section cannot slice it. ` +
+                `Rebuild a base first: run \`lumo doc show ${d.id}\`, reconstruct the markdown ` +
+                `faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\`.`);
+            return 1;
+        }
+        const match = (0, markdown_sections_1.findSection)(d.sourceMarkdown, opts.section);
+        if (match.kind === 'not-found') {
+            const list = match.available
+                .slice(0, 30)
+                .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)}`)
+                .join('\n');
+            console.error(`Error: section not found: "${opts.section}". Available headings:\n${list || '  (none)'}`);
+            return 1;
+        }
+        if (match.kind === 'ambiguous') {
+            const list = match.candidates
+                .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)} (line ${s.line + 1})`)
+                .join('\n');
+            console.error(`Error: section "${opts.section}" is ambiguous — ${match.candidates.length} headings match:\n${list}\n` +
+                `Disambiguate by depth, e.g. --section "${'#'.repeat(match.candidates[0].depth)} ${match.candidates[0].heading}"`);
+            return 1;
+        }
+        // Byte-faithful slice, verbatim on stdout (legal patch base); revision on
+        // stderr for the follow-up `doc patch --if-revision`.
+        process.stdout.write((0, markdown_sections_1.extractSection)(d.sourceMarkdown, match.section));
+        if (typeof d.contentRevision === 'number') {
+            console.error(`Revision: ${d.contentRevision}`);
+        }
         return;
     }
     // Server returns `contentMarkdown` derived from the HTML body (LUM-83+).
@@ -110,6 +156,7 @@ async function docShow(reference, opts = {}) {
         projectName: d.project?.name ?? null,
         createdAt: d.createdAt ?? '',
         updatedAt: d.updatedAt ?? '',
+        revision: typeof d.contentRevision === 'number' ? d.contentRevision : null,
         mentionedTasks,
         bodyMarkdown: body,
     }));

package/dist/cli/src/commands/doc-update.js

@@ -75,6 +75,13 @@ async function docUpdate(reference, opts) {
     }
     if (content.kind === 'ok')
         body.contentMarkdown = content.markdown;
+    if (opts.ifRevision !== undefined) {
+        if (!/^\d+$/.test(opts.ifRevision)) {
+            console.error(`Error: --if-revision must be a non-negative integer (got "${opts.ifRevision}")`);
+            return 1;
+        }
+        body.ifRevision = Number(opts.ifRevision);
+    }
     // Resolve tag refs into ids
     const deps = { apiUrl, token: creds.token };
     let tagIds;
@@ -107,7 +114,8 @@ async function docUpdate(reference, opts) {
         body.addTagIds = addTagIds;
     if (removeTagIds !== undefined)
         body.removeTagIds = removeTagIds;
-    if (Object.keys(body).length === 0) {
+    // --if-revision is a precondition, not a field — alone it's not an update.
+    if (Object.keys(body).filter(k => k !== 'ifRevision').length === 0) {
         console.error('Error: no fields to update — provide at least one flag');
         return 1;
     }
@@ -122,6 +130,19 @@ async function docUpdate(reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
+        if (res.status === 409 && opts.ifRevision !== undefined) {
+            let message = text;
+            try {
+                message = JSON.parse(text).error ?? text;
+            }
+            catch {
+                // non-JSON error body — print as-is
+            }
+            console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: re-read the doc (lumo doc show ${reference} --raw), rebase your edit ` +
+                `on the current source, then retry with --if-revision <current>.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }

package/dist/cli/src/index.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = void 0;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -108,6 +109,7 @@ const doc_sync_1 = require("./commands/doc-sync");
 const doc_update_1 = require("./commands/doc-update");
 const doc_show_1 = require("./commands/doc-show");
 const doc_diff_1 = require("./commands/doc-diff");
+const doc_section_edit_1 = require("./commands/doc-section-edit");
 const doc_list_1 = require("./commands/doc-list");
 const doc_delete_1 = require("./commands/doc-delete");
 const doc_bind_1 = require("./commands/doc-bind");
@@ -123,9 +125,16 @@ 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");
+// Introspection mode: tooling (scripts/analysis grammar extraction) imports
+// this module to walk the registered commander tree without running the CLI.
+// Skips package.json resolution (which assumes the compiled dist/ layout),
+// update checks, local-state cleanup, and parseAsync. Never set for real runs.
+const isIntrospect = process.env.LUMO_CLI_INTROSPECT === '1';
 // Resolve package.json relative to __dirname so this works regardless of how
 // deep the compiled output ends up (flat dist/ or nested dist/cli/src/).
-const pkg = require(path.resolve(__dirname, '../../..', 'package.json'));
+const pkg = isIntrospect
+    ? { name: '@lumoai/cli', version: '0.0.0-introspect' }
+    : require(path.resolve(__dirname, '../../..', 'package.json'));
 // Detached background-refresh worker: re-entry point for the spawn() in
 // maybeRefreshInBackground(). Fetches latest, writes cache, exits — skipping
 // commander.parseAsync() below.
@@ -135,7 +144,7 @@ if (isUpdateCheckWorker) {
         .catch(() => { })
         .finally(() => process.exit(0));
 }
-else {
+else if (!isIntrospect) {
     (0, update_check_1.printUpdateNoticeIfAny)(pkg.name, pkg.version);
     (0, update_check_1.maybeRefreshInBackground)(pkg.name);
 }
@@ -143,8 +152,7 @@ else {
 // is now server-authoritative; the legacy global pointer and the
 // per-session sentinel directory are both obsolete. Failures are
 // swallowed so a permission glitch doesn't prevent CLI invocation.
-;
-(() => {
+if (!isIntrospect) {
     const dir = process.env.LUMO_CONFIG_DIR || path.join(os.homedir(), '.lumo');
     try {
         fs.rmSync(path.join(dir, 'current-task.json'), { force: true });
@@ -154,7 +162,7 @@ else {
         fs.rmSync(path.join(dir, 'sessions'), { recursive: true, force: true });
     }
     catch { }
-})();
+}
 const collect = (val, acc) => [...acc, val];
 function wrap(fn) {
     return async (...args) => {
@@ -179,6 +187,7 @@ const program = new commander_1.Command()
     // created via .command() inherit these settings.
     .showSuggestionAfterError(true)
     .showHelpAfterError('(run the command with --help to list its valid flags and arguments)');
+exports.program = program;
 const auth = program.command('auth').description('Manage Lumo authentication');
 auth
     .command('login')
@@ -663,12 +672,30 @@ doc
     .option('--add-tag-id <cuid>', 'Add tag by id (repeatable)', collect, [])
     .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, [])
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show); mismatch fails with a 409 conflict')
     .action(wrap((reference, opts) => (0, doc_update_1.docUpdate)(reference, opts)));
 doc
     .command('show <doc>')
-    .description('Show document header and body (doc = title or cuid). --raw prints the byte-identical markdown source of the last markdown upload (a legal edit base); it errors when no markdown source is stored instead of falling back to the lossy HTML→markdown render.')
+    .description('Show document header and body (doc = title or cuid). --raw prints the byte-identical markdown source of the last markdown upload (a legal edit base); it errors when no markdown source is stored instead of falling back to the lossy HTML→markdown render. --section <heading> prints just that section of the markdown source (revision goes to stderr).')
     .option('--raw', 'Print the stored markdown source verbatim (no header); errors if absent')
+    .option('--section <heading>', 'Print one heading-addressed section of the markdown source (prefix with #… to pin depth, e.g. "## Status")')
     .action(wrap((reference, opts) => (0, doc_show_1.docShow)(reference, opts)));
+doc
+    .command('patch <doc>')
+    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten.')
+    .requiredOption('--section <heading>', 'Heading of the section to replace (prefix with #… to pin depth)')
+    .option('--content <text>', 'New section content (inline markdown)')
+    .option('--file <path>', 'New section content from file')
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .action(wrap((reference, opts) => (0, doc_section_edit_1.docPatch)(reference, opts)));
+doc
+    .command('append <doc>')
+    .description('Append markdown at the end of a heading-addressed section (before the next same-or-higher heading), or at the document end when --section is omitted. Pure insertion — no existing byte is modified — which makes it the safest write for running logs/ledgers. 409 on concurrent edits.')
+    .option('--section <heading>', 'Heading of the section to append into (omit to append at the document end)')
+    .option('--content <text>', 'Content to append (inline markdown)')
+    .option('--file <path>', 'Content to append from file')
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .action(wrap((reference, opts) => (0, doc_section_edit_1.docAppend)(reference, opts)));
 doc
     .command('diff <doc>')
     .description('Compare the server-side markdown source against a local file. Exit 0 when byte-identical, 1 with a unified diff when divergent. Requires the doc to have a stored markdown source.')
@@ -883,7 +910,7 @@ for (const [slug, description] of HOOK_SUBCOMMANDS) {
         .option('--agent <token>', 'Coding agent that owns this session (e.g. claude-code, codex). Baked in by `lumo setup --agent`.')
         .action(wrap((opts) => (0, hook_1.hookCommand)(slug, opts.agent)));
 }
-if (!isUpdateCheckWorker) {
+if (!isUpdateCheckWorker && !isIntrospect) {
     program.parseAsync(process.argv).catch(err => {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Error: ${(0, sanitize_1.sanitizeField)(msg)}`);

package/dist/cli/src/lib/git-task.js

@@ -1,24 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchTaskIdentifier = matchTaskIdentifier;
+exports.matchTaskIdentifier = void 0;
 exports.extractTaskFromGit = extractTaskFromGit;
 const child_process_1 = require("child_process");
+const task_identifier_1 = require("../../../shared/src/task-identifier");
+Object.defineProperty(exports, "matchTaskIdentifier", { enumerable: true, get: function () { return task_identifier_1.matchTaskIdentifier; } });
 /**
  * How many recent commit subjects to scan when the branch name carries no
  * task id (e.g. on a generic feature branch or detached HEAD).
  */
 const DEFAULT_COMMIT_DEPTH = 20;
-const TASK_RE = /LUM-(\d+)/i;
-/**
- * Pull the first `LUM-<n>` token out of arbitrary text (a branch name or a
- * commit subject) and normalize it to upper case. Returns null when no task
- * id is present. The leading `-` in the pattern means the bare word `lumo`
- * never matches.
- */
-function matchTaskIdentifier(text) {
-    const m = text.match(TASK_RE);
-    return m ? `LUM-${m[1]}` : null;
-}
 /**
  * Run a git subcommand and return trimmed stdout, or '' on any failure
  * (non-zero exit, spawn error, not a repository, timeout). Never throws.
@@ -41,17 +32,18 @@ function gitOutput(args, cwd) {
 /**
  * Infer the task to work on from local git: prefer the current branch name
  * (e.g. `lumo/LUM-145-...`), then fall back to the most recent commit
- * subjects (e.g. `... [LUM-145]`). Returns null when nothing matches —
- * detached HEAD (branch reads `HEAD`), a non-lumo branch with no tagged
- * commits, or a directory that is not a git repository all degrade to null.
+ * subjects (e.g. `... [LUM-145]`). Any team prefix matches (SPEC-12 as much
+ * as LUM-145). Returns null when nothing matches — detached HEAD (branch
+ * reads `HEAD`), a branch with no identifier and no tagged commits, or a
+ * directory that is not a git repository all degrade to null.
  */
 function extractTaskFromGit(cwd, commitDepth = DEFAULT_COMMIT_DEPTH) {
     const branch = gitOutput(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
-    const fromBranch = matchTaskIdentifier(branch);
+    const fromBranch = (0, task_identifier_1.matchTaskIdentifier)(branch);
     if (fromBranch)
         return { identifier: fromBranch, source: 'branch' };
     const log = gitOutput(['log', '-n', String(commitDepth), '--format=%s'], cwd);
-    const fromLog = matchTaskIdentifier(log);
+    const fromLog = (0, task_identifier_1.matchTaskIdentifier)(log);
     if (fromLog)
         return { identifier: fromLog, source: 'commit' };
     return null;

package/dist/cli/src/lib/markdown-sections.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSectionQuery = exports.appendToSection = exports.replaceSection = exports.extractSection = exports.findSection = exports.listSections = void 0;
+// Single source of truth lives in shared/src/markdown-sections.ts (LUM-409) —
+// the CLI must slice sections exactly like the server does.
+var markdown_sections_1 = require("../../../shared/src/markdown-sections");
+Object.defineProperty(exports, "listSections", { enumerable: true, get: function () { return markdown_sections_1.listSections; } });
+Object.defineProperty(exports, "findSection", { enumerable: true, get: function () { return markdown_sections_1.findSection; } });
+Object.defineProperty(exports, "extractSection", { enumerable: true, get: function () { return markdown_sections_1.extractSection; } });
+Object.defineProperty(exports, "replaceSection", { enumerable: true, get: function () { return markdown_sections_1.replaceSection; } });
+Object.defineProperty(exports, "appendToSection", { enumerable: true, get: function () { return markdown_sections_1.appendToSection; } });
+Object.defineProperty(exports, "parseSectionQuery", { enumerable: true, get: function () { return markdown_sections_1.parseSectionQuery; } });

package/dist/shared/src/markdown-sections.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSections = listSections;
+exports.parseSectionQuery = parseSectionQuery;
+exports.findSection = findSection;
+exports.extractSection = extractSection;
+exports.replaceSection = replaceSection;
+exports.appendToSection = appendToSection;
+const markdown_it_1 = __importDefault(require("markdown-it"));
+/**
+ * Heading-addressed section slicing over a markdown source string (LUM-409).
+ *
+ * Single source of truth shared by the documents service (server-side
+ * section patch/append) and the CLI (`doc show --section`) so both sides
+ * agree byte-for-byte on where a section starts and ends.
+ *
+ * All offsets are character offsets into the ORIGINAL source string — slices
+ * are taken with `src.slice(...)`, never re-serialized, so everything
+ * outside an edited section survives byte-identical. Headings are located
+ * with markdown-it block tokens (not a regex) so `#` lines inside fenced
+ * code blocks or blockquotes are never mistaken for section boundaries.
+ */
+const md = new markdown_it_1.default({ html: false, linkify: true, breaks: false });
+/**
+ * Start offsets of each line, splitting on the same newline shapes
+ * markdown-it normalizes before tokenizing (`\r\n` / `\r` / `\n`), so a
+ * token's `map` line number indexes this array directly.
+ */
+function computeLineStarts(src) {
+    const starts = [0];
+    for (let i = 0; i < src.length; i++) {
+        const ch = src.charCodeAt(i);
+        if (ch === 13 /* \r */) {
+            if (src.charCodeAt(i + 1) === 10 /* \n */)
+                i++;
+            starts.push(i + 1);
+        }
+        else if (ch === 10 /* \n */) {
+            starts.push(i + 1);
+        }
+    }
+    return starts;
+}
+/** List every top-level heading-addressed section of a markdown source. */
+function listSections(src) {
+    if (!src)
+        return [];
+    const tokens = md.parse(src, {});
+    const lineStarts = computeLineStarts(src);
+    const heads = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        // level === 0 keeps headings nested inside blockquotes/lists from
+        // becoming section boundaries.
+        if (t?.type === 'heading_open' && t.map && t.level === 0) {
+            const inline = tokens[i + 1];
+            heads.push({
+                depth: Number(t.tag.slice(1)),
+                text: (inline?.type === 'inline' ? inline.content : '').trim(),
+                line: t.map[0],
+            });
+        }
+    }
+    return heads.map((h, idx) => {
+        let end = src.length;
+        for (let j = idx + 1; j < heads.length; j++) {
+            const next = heads[j];
+            if (next && next.depth <= h.depth) {
+                end = lineStarts[next.line] ?? src.length;
+                break;
+            }
+        }
+        return {
+            heading: h.text,
+            depth: h.depth,
+            line: h.line,
+            startOffset: lineStarts[h.line] ?? 0,
+            endOffset: end,
+        };
+    });
+}
+/**
+ * Parse a `--section` query. A leading `#`-run constrains the heading depth
+ * (`"## Status"` only matches h2 headings titled "Status"), which is how a
+ * caller disambiguates same-text headings at different levels.
+ */
+function parseSectionQuery(raw) {
+    const m = /^(#{1,6})\s+(.*)$/.exec(raw.trim());
+    if (m)
+        return { text: (m[2] ?? '').trim(), depth: (m[1] ?? '').length };
+    return { text: raw.trim() };
+}
+/**
+ * Locate a section by heading text. Exact match first, then a
+ * case-insensitive pass; more than one hit in the winning pass is reported
+ * as ambiguous rather than silently picking one.
+ */
+function findSection(src, query) {
+    const q = parseSectionQuery(query);
+    const sections = listSections(src);
+    const pool = q.depth !== undefined ? sections.filter(s => s.depth === q.depth) : sections;
+    let matches = pool.filter(s => s.heading === q.text);
+    if (matches.length === 0) {
+        const lower = q.text.toLowerCase();
+        matches = pool.filter(s => s.heading.toLowerCase() === lower);
+    }
+    const first = matches[0];
+    if (matches.length === 1 && first)
+        return { kind: 'found', section: first };
+    if (matches.length === 0)
+        return { kind: 'not-found', available: sections };
+    return { kind: 'ambiguous', candidates: matches };
+}
+/** Byte-faithful slice of one section (heading line through section end). */
+function extractSection(src, section) {
+    return src.slice(section.startOffset, section.endOffset);
+}
+function stripOuterNewlines(text) {
+    return text.replace(/^[\r\n]+/, '').replace(/[\r\n]+$/, '');
+}
+/**
+ * Replace one section (heading included) with `newText`, verbatim. Bytes
+ * before `startOffset` and from `endOffset` on are carried over untouched;
+ * only the new block's trailing newlines are padded so a following heading
+ * still starts at the beginning of a line with a blank line before it.
+ */
+function replaceSection(src, section, newText) {
+    const before = src.slice(0, section.startOffset);
+    const after = src.slice(section.endOffset);
+    let block = newText;
+    if (after.length > 0 && block.length > 0 && !block.endsWith('\n\n')) {
+        block = block.replace(/\n*$/, '\n\n');
+    }
+    return before + block + after;
+}
+/**
+ * Insert `text` at the end of a section (or at the end of the document when
+ * `section` is null). Pure insertion: every pre-existing byte is preserved;
+ * only separator newlines around the new chunk are added as needed.
+ */
+function appendToSection(src, section, text) {
+    const insertAt = section ? section.endOffset : src.length;
+    const before = src.slice(0, insertAt);
+    const after = src.slice(insertAt);
+    const chunk = stripOuterNewlines(text);
+    if (chunk.length === 0)
+        return src;
+    let lead = '';
+    if (before.length > 0) {
+        if (before.endsWith('\n\n'))
+            lead = '';
+        else if (before.endsWith('\n') || before.endsWith('\r'))
+            lead = '\n';
+        else
+            lead = '\n\n';
+    }
+    const tail = after.length > 0 ? '\n\n' : '\n';
+    return before + lead + chunk + tail + after;
+}

package/dist/shared/src/task-identifier.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_IDENTIFIER_PATTERN = void 0;
+exports.matchTaskIdentifier = matchTaskIdentifier;
+/**
+ * Single source of truth for the task-identifier pattern (LUM-419).
+ *
+ * Consumed by both sides so they cannot drift:
+ *   - server: lib/integrations/github/branch.ts (webhook branch → task linking)
+ *   - CLI:    cli/src/lib/git-task.ts (session-start git-suggest)
+ *
+ * A task identifier is `<TEAM>-<n>` where TEAM is the team's configured
+ * prefix (`Team.identifier`, 1–10 letters) — e.g. LUM-419, SPEC-123. The
+ * prefix is NOT hardcoded to any one team.
+ */
+exports.TASK_IDENTIFIER_PATTERN = String.raw `\b([A-Za-z]{1,10}-\d+)\b`;
+/**
+ * Acronym-number tokens that match the identifier shape but are never task
+ * ids. Commit subjects routinely contain these ("fix UTF-8 handling",
+ * "use SHA-256"), so the matcher skips them instead of suggesting a bogus
+ * session attach. Compared against the uppercased prefix segment.
+ */
+const NON_TASK_PREFIXES = new Set([
+    'AES',
+    'CVE',
+    'GPT',
+    'HTTP',
+    'ISO',
+    'RFC',
+    'RSA',
+    'SHA',
+    'TLS',
+    'UTF',
+]);
+/**
+ * Extract the first task identifier from arbitrary text (a branch name or a
+ * commit subject), normalized to upper case. Tokens whose prefix is a known
+ * non-task acronym (UTF-8, SHA-256, …) are skipped; later genuine matches in
+ * the same text still win. Returns null when nothing matches.
+ */
+function matchTaskIdentifier(text) {
+    const re = new RegExp(exports.TASK_IDENTIFIER_PATTERN, 'g');
+    for (const m of text.matchAll(re)) {
+        const identifier = m[1].toUpperCase();
+        const prefix = identifier.slice(0, identifier.lastIndexOf('-'));
+        if (NON_TASK_PREFIXES.has(prefix))
+            continue;
+        return identifier;
+    }
+    return null;
+}

package/package.json

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