memarium 0.13.1

package/dist/src/content-project-inference.js

@@ -0,0 +1,185 @@
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { cachedProjectSlug } from "./project-identity.js";
+/**
+ * Content-based project inference.
+ *
+ * Claude Code groups jsonl files by cwd at session-start. When the user
+ * `cd`s into a different project mid-session, or runs `claude` in the wrong
+ * directory by accident (e.g. opens it in `chromium-src` but spends the
+ * whole session editing files in `edge-memarium`), the session is filed
+ * under the wrong project. The user's intent — "this conversation is about
+ * memarium" — disagrees with the cwd label.
+ *
+ * We recover intent by scanning the session's tool-use blocks for absolute
+ * file paths the assistant actually touched (Read / Write / Edit / Bash),
+ * mapping each path to a project root, and picking the dominant one. If
+ * one project owns ≥ MIN_CONFIDENCE of all path mentions, we override the
+ * cwd-derived project with the inferred one.
+ *
+ * We DO NOT scan message text for paths — that produces too many false
+ * positives (e.g. "the chromium codebase has a similar pattern in
+ * /chromium/src/foo.cc" mentioned as reference, not as work). Tool-use
+ * inputs reflect actual edits/reads, which is the signal we want.
+ */
+export const MIN_CONFIDENCE = 0.7;
+export const MIN_PATH_HITS = 5;
+/**
+ * Decode a Claude project-dir name back to its filesystem path prefix.
+ *
+ *   "-Users-me-edge-memvc"  →  "/Users/me/edge/memvc"
+ *
+ * Note this is one-way and lossy — Claude itself uses the same encoding so
+ * actual hyphens in path components become indistinguishable from `/`.
+ * That ambiguity is fine for our use: we only need the prefix to match the
+ * common case `/Users/<u>/<dir>/...`, where hyphens-in-names are rare.
+ */
+function decodeProjectDirName(name) {
+    if (!name.startsWith("-"))
+        return name;
+    return "/" + name.slice(1).replace(/-/g, "/");
+}
+/**
+ * Build the list of "known project roots" by listing `~/.claude/projects/`.
+ * Returns just the `{ path }`s, sorted longest-prefix-first so a path like
+ * `/Users/u/edge/memvc/.claude/worktrees/foo` matches the worktree subdir
+ * before falling back to the parent project. The (remote-based) slug is
+ * resolved lazily — only for the root a path actually matches — so listing
+ * roots never spawns `git` for projects the session didn't touch (#41 review).
+ */
+export function listKnownProjectRoots(projectsDir = join(homedir(), ".claude", "projects")) {
+    let entries;
+    try {
+        entries = readdirSync(projectsDir);
+    }
+    catch {
+        return [];
+    }
+    const out = entries.map((name) => ({ path: decodeProjectDirName(name) }));
+    out.sort((a, b) => b.path.length - a.path.length);
+    return out;
+}
+/**
+ * Match an absolute path to a known project root, or fall back to
+ * deriving a slug from the path's parent component. The slug is the stable
+ * remote-based identity (cached); a path slug only when there's no git remote.
+ *
+ *   "/Users/me/edge/memvc/src/foo.ts"  →  "github.com-..."/"edge-memvc"  (matched)
+ *   "/Users/me/edge/random/file.ts"    →  slug from parent (no root match)
+ *   "/etc/hosts"                       →  null (non-project)
+ */
+export function pathToProjectSlug(absPath, roots) {
+    if (!absPath || !absPath.startsWith("/"))
+        return null;
+    for (const r of roots) {
+        if (absPath === r.path || absPath.startsWith(r.path + "/"))
+            return cachedProjectSlug(r.path);
+    }
+    // Fallback: derive a slug from the directory the touched file lives in.
+    const lastSlash = absPath.lastIndexOf("/");
+    if (lastSlash <= 0)
+        return null;
+    const dir = absPath.slice(0, lastSlash);
+    // Reject obvious non-project dirs BEFORE resolving identity (skip the git spawn).
+    if (dir.startsWith("/tmp/") || dir.startsWith("/private/tmp/") ||
+        dir.startsWith("/etc") || dir.startsWith("/usr") || dir.startsWith("/var") ||
+        dir.startsWith("/System") || dir.startsWith("/opt"))
+        return null;
+    // Resolve through the SAME remote-first identity as known roots (#41 review):
+    // an inferred-override target that's a git repo gets its stable remote slug,
+    // not a path slug from a different namespace that would re-split the project.
+    const slug = cachedProjectSlug(dir);
+    if (slug === "home" || slug === "root")
+        return null;
+    return slug;
+}
+/**
+ * Pull every plausible absolute path out of the message's raw tool-use
+ * blocks. Returns deduplicated paths per message — repeated reads of the
+ * same file count once per message, not N times — to avoid a single noisy
+ * Read loop dominating the tally.
+ */
+export function extractPathsFromMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        const raw = m.raw;
+        const content = raw?.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        const seen = new Set();
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type !== "tool_use")
+                continue;
+            const inp = b.input ?? {};
+            const name = b.name ?? "";
+            if (name === "Read" || name === "Write" || name === "Edit" || name === "NotebookEdit") {
+                const fp = inp.file_path ?? inp.notebook_path;
+                if (typeof fp === "string" && fp.startsWith("/"))
+                    seen.add(fp);
+            }
+            else if (name === "Bash") {
+                const cmd = inp.command;
+                if (typeof cmd === "string") {
+                    // Greedy match for absolute-path-looking tokens. Stops at whitespace
+                    // or shell metacharacters; tolerates dots/dashes/underscores.
+                    for (const m2 of cmd.matchAll(/\/[A-Za-z0-9._\-/]+(?:\.[A-Za-z0-9]+)?/g)) {
+                        const p = m2[0];
+                        // Skip very short hits (likely "/" or "/x") and obvious URL paths.
+                        if (p.length < 6)
+                            continue;
+                        if (cmd.includes("http://" + p) || cmd.includes("https://" + p))
+                            continue;
+                        seen.add(p);
+                    }
+                }
+            }
+            else if (name === "Glob" || name === "Grep") {
+                const pat = inp.path ?? inp.pattern;
+                if (typeof pat === "string" && pat.startsWith("/"))
+                    seen.add(pat);
+            }
+        }
+        for (const p of seen)
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * Run inference on a session's messages. Returns the inferred project slug
+ * and confidence. Caller decides whether to override based on the policy
+ * (e.g. inferred != cwd-project AND confidence >= MIN_CONFIDENCE).
+ */
+export function inferProjectFromContent(messages, roots = listKnownProjectRoots()) {
+    const paths = extractPathsFromMessages(messages);
+    const counts = {};
+    let totalHits = 0;
+    for (const p of paths) {
+        const slug = pathToProjectSlug(p, roots);
+        if (!slug)
+            continue;
+        counts[slug] = (counts[slug] ?? 0) + 1;
+        totalHits++;
+    }
+    if (totalHits < MIN_PATH_HITS) {
+        return { inferredProject: null, confidence: 0, totalHits, perProject: counts };
+    }
+    let topSlug = "";
+    let topCount = 0;
+    for (const [slug, c] of Object.entries(counts)) {
+        if (c > topCount) {
+            topCount = c;
+            topSlug = slug;
+        }
+    }
+    const confidence = topCount / totalHits;
+    return {
+        inferredProject: confidence >= MIN_CONFIDENCE ? topSlug : null,
+        confidence,
+        totalHits,
+        perProject: counts,
+    };
+}

package/dist/src/device.js

@@ -0,0 +1,47 @@
+import { hostname } from "node:os";
+/**
+ * Make `raw` safe for use as a git branch name.
+ * Keeps [A-Za-z0-9._-]; replaces everything else with '-'; collapses runs of '-';
+ * trims leading/trailing '-' or '.'; caps length at 60.
+ * Falls back to "device" if empty after sanitize.
+ */
+export function sanitizeBranchName(raw) {
+    let s = raw.replace(/[^A-Za-z0-9._-]/g, "-");
+    s = s.replace(/-+/g, "-");
+    s = s.replace(/\.+/g, ".");
+    s = s.replace(/^[-.]+|[-.]+$/g, "");
+    if (s.length === 0)
+        return "device";
+    if (s.length > 60)
+        s = s.slice(0, 60).replace(/[-.]+$/, "");
+    if (s.endsWith(".lock"))
+        s = s.slice(0, -5).replace(/[-.]+$/, "");
+    if (s.length === 0)
+        return "device";
+    return s;
+}
+export function deviceBranchFromHostname() {
+    return sanitizeBranchName(hostname());
+}
+/**
+ * Heuristic: does the given branch name look like it came from macOS's
+ * volatile hostname (mDNS in home wifi, corporate DHCP-given names on VPN,
+ * iPhone tethering, etc.)? Used by the init wizard and doctor to nudge users
+ * toward a stable physical-label name like "mini2" instead of letting their
+ * spool grow a new device branch each time they change networks.
+ *
+ * Conservative: returns true (stable-looking) by default; we only flag
+ * patterns we've actually seen drift in dogfood:
+ *   - ends in `.local`               (Bonjour / mDNS, changes when DHCP renames host)
+ *   - matches a fully-qualified DNS name (contains a `.` followed by 2+
+ *     letters as a TLD) — e.g. `MIS-EV2-BB1.surfacescenarios.org`,
+ *     `host42.corp.example.com`. These come from corp DHCP and rotate.
+ */
+export function isStableDeviceName(name) {
+    if (name.endsWith(".local"))
+        return false;
+    // FQDN-ish: contains `.`, ends in `.<letters>{2+}` (the TLD).
+    if (/\.[A-Za-z]{2,}$/.test(name))
+        return false;
+    return true;
+}

package/dist/src/digest/manifest.js

@@ -0,0 +1,121 @@
+/** Cap on commits / files_touched / candidate_decisions to bound frontmatter
+ *  size. files_touched dominates volume — a long debugging session can hit
+ *  Read on 500+ files; we keep first-seen 200, which covers the dense
+ *  early-session exploration without exploding YAML parse cost. */
+const FILES_CAP = 200;
+const COMMITS_CAP = 100;
+const DECISIONS_CAP = 20;
+/** Heuristic regex for "user signaled a decision here." Intentionally narrow
+ *  — false positives waste the digest skill's attention more than false
+ *  negatives. The skill is told these are candidates, not facts. */
+const DECISION_RE = /(我决定|我们决定|最后采用|最后用|let'?s go with|decided to|going with|ok merged|merged it|ship it as)/i;
+/** Match `git commit … -m "msg"` / `-m 'msg'` / heredoc commits. We also
+ *  catch `git tag -a vX.Y.Z -m "…"` and bare `git tag <ver>` since releases
+ *  matter for the digest. `git push` is excluded — it's procedural, not a
+ *  decision point. */
+const GIT_COMMIT_RE = /\bgit\s+commit\b[^\n]*?-m\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|(\S+))/;
+const GIT_COMMIT_HEREDOC_RE = /\bgit\s+commit\b[^\n]*?-m\s+"\$\(cat\s+<<\s*'?(\w+)'?[\r\n]+([\s\S]*?)[\r\n]+\1\s*\)"/;
+const GIT_TAG_RE = /\bgit\s+tag\b(?:[^\n]*?-(?:a|s)\s+)?\s*(v[\w.\-+]+)(?:[^\n]*?-m\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'))?/;
+/** Tools whose input.file_path contributes to files_touched. */
+const FILE_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/**
+ * Extract a mechanical-facts SessionManifest from already-extracted
+ * SessionMessages. Pure function — no I/O.
+ *
+ * @param messages SessionMessage[] in chronological order.
+ * @param messageLineOffsets parallel array where messageLineOffsets[i] is the
+ *   line number of the i-th message's `## User`/`## Assistant` heading in
+ *   the final rendered md. Used to populate `line` fields so consumers can
+ *   `Read offset:line` to jump straight to the source turn.
+ */
+export function extractManifest(messages, messageLineOffsets) {
+    const tools_used = {};
+    const commits = [];
+    const filesSeen = new Set();
+    const files_touched = [];
+    const candidate_decisions = [];
+    let user_turns = 0;
+    let assistant_turns = 0;
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        const line = messageLineOffsets[i] ?? 0;
+        if (m.role === "user")
+            user_turns++;
+        else if (m.role === "assistant")
+            assistant_turns++;
+        // Decision heuristic: user text only (assistants don't make decisions).
+        if (m.role === "user" && m.text && DECISION_RE.test(m.text) && candidate_decisions.length < DECISIONS_CAP) {
+            candidate_decisions.push({ line, preview: previewOf(m.text, 100) });
+        }
+        for (const b of m.contentBlocks ?? []) {
+            if (b.type !== "tool_use")
+                continue;
+            tools_used[b.name] = (tools_used[b.name] ?? 0) + 1;
+            if (FILE_TOOLS.has(b.name)) {
+                const fp = readFilePath(b);
+                if (fp && !filesSeen.has(fp) && files_touched.length < FILES_CAP) {
+                    filesSeen.add(fp);
+                    files_touched.push(fp);
+                }
+            }
+            if (b.name === "Bash" && commits.length < COMMITS_CAP) {
+                const cmd = readBashCommand(b);
+                if (cmd) {
+                    const c = parseCommit(cmd);
+                    if (c)
+                        commits.push({ ...c, line });
+                    else {
+                        const t = parseTag(cmd);
+                        if (t)
+                            commits.push({ ...t, line });
+                    }
+                }
+            }
+        }
+    }
+    return {
+        user_turns,
+        assistant_turns,
+        tools_used,
+        commits,
+        files_touched,
+        candidate_decisions,
+    };
+}
+function readFilePath(b) {
+    const input = b.input;
+    if (!input || typeof input !== "object")
+        return null;
+    return typeof input.file_path === "string" ? input.file_path : null;
+}
+function readBashCommand(b) {
+    const input = b.input;
+    if (!input || typeof input !== "object")
+        return null;
+    return typeof input.command === "string" ? input.command : null;
+}
+function parseCommit(cmd) {
+    const h = cmd.match(GIT_COMMIT_HEREDOC_RE);
+    if (h) {
+        const body = (h[2] ?? "").trim();
+        const firstLine = body.split("\n", 1)[0].trim();
+        return firstLine ? { sha: "", msg: firstLine } : null;
+    }
+    const m = cmd.match(GIT_COMMIT_RE);
+    if (!m)
+        return null;
+    const msg = (m[1] ?? m[2] ?? m[3] ?? "").trim();
+    return msg ? { sha: "", msg } : null;
+}
+function parseTag(cmd) {
+    const m = cmd.match(GIT_TAG_RE);
+    if (!m)
+        return null;
+    const tag = m[1];
+    const msg = (m[2] ?? m[3] ?? "").trim();
+    return { sha: tag, msg: msg || `tag ${tag}` };
+}
+function previewOf(text, max) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > max ? collapsed.slice(0, max - 1) + "…" : collapsed;
+}

package/dist/src/digest/project-filter.js

@@ -0,0 +1,32 @@
+/**
+ * Heuristic: a path is a "real project" if it's a developer working directory,
+ * not a worktree, electron data dir, or transient workspace path.
+ *
+ * Rejects:
+ *   - paths containing /.worktrees-*
+ *   - paths ending in *.code-workspace, *-workspace.json (workspace fragments)
+ *   - paths ending in -workspaceStorage (VSCode workspaceStorage hash dirs)
+ *   - empty / "root" / "home"
+ *   - long-numeric-prefixed slugs (10+ digit run, e.g. workspaceStorage timestamps)
+ *   - 20+ pure-hex strings (workspaceStorage hashes)
+ *
+ * This is a heuristic — it's allowed to be wrong in edge cases. Goal: clean
+ * the obviously-junk projects out of book/ TOC.
+ */
+export function isRealProjectPath(slugOrPath) {
+    if (!slugOrPath || slugOrPath === "root" || slugOrPath === "home")
+        return false;
+    const lower = slugOrPath.toLowerCase();
+    if (lower.includes(".worktrees-"))
+        return false;
+    if (lower.endsWith(".code-workspace") || lower.endsWith("-workspacestorage"))
+        return false;
+    if (lower.endsWith("-workspace.json"))
+        return false;
+    // Reject pure-numeric / 32-hex-like pseudo-IDs masquerading as project names
+    if (/^\d{10,}/.test(slugOrPath))
+        return false;
+    if (/^[a-f0-9]{20,}$/.test(slugOrPath))
+        return false;
+    return true;
+}

package/dist/src/digest/session-signal.js

@@ -0,0 +1,106 @@
+const SIGNAL_CATEGORIES = {
+    debugging: ["bug", "error", "fix", "debug", "root cause", "traceback", "broken", "问题", "修复"],
+    architecture: ["architecture", "design", "pattern", "trade-off", "decision", "approach", "架构", "设计"],
+    discovery: ["learned", "discovered", "insight", "gotcha", "trap", "pitfall", "trick", "发现", "陷阱", "关键"],
+    reasoning: ["because", "instead of", "rather than", "why", "the reason", "原因", "所以", "因为"],
+    evaluation: ["review", "evaluate", "score", "verdict", "assessment", "评估", "审查"],
+};
+/**
+ * Detect a "memarium meta-session" — the user invoking the /memarium skill
+ * itself, which produces a session whose entire content is the digest
+ * pipeline (memarium prepare/publish/etc.) rather than real engineering
+ * work. These have zero chronicle value (they're self-referential noise)
+ * so prepare filters them out before the LLM ever sees them.
+ *
+ * Signals (any one is enough):
+ *   - first user message starts with "/memarium"
+ *   - first user message starts with "/loop /memarium" (looped invocations)
+ *   - first user message references the SKILL.md by path
+ */
+export function isMemariumMetaSession(mdBody) {
+    const userTexts = extractUserTexts(mdBody);
+    const first = (userTexts[0] ?? "").trimStart();
+    if (/^\/memarium(\b|$)/i.test(first))
+        return true;
+    if (/^\/loop\s+\/memarium(\b|$)/i.test(first))
+        return true;
+    if (first.includes("skills/memarium/SKILL.md"))
+        return true;
+    return false;
+}
+/**
+ * Extract per-session signals from a rendered session .md body.
+ * Pure; no IO.
+ *
+ * The .md body is produced by `src/writer.ts` and looks like:
+ *   # <displayName>
+ *   **Tool:** ... etc
+ *   ---
+ *   ## User _(timestamp)_
+ *   <text>
+ *   ## Assistant _(timestamp)_
+ *   <text>
+ *   ## User _(timestamp)_
+ *   ...
+ *
+ * We extract user-message text only (assistant is too noisy for a topic preview).
+ */
+export function extractSessionSignals(mdBody) {
+    const userTexts = extractUserTexts(mdBody);
+    const joined = userTexts.join(" ").replace(/\s+/g, " ").trim();
+    const titleSrc = userTexts[0] ?? "";
+    const titleClean = titleSrc.replace(/\s+/g, " ").trim();
+    const title = titleClean.length > 80 ? titleClean.slice(0, 80) : titleClean;
+    const preview = joined.length > 300 ? joined.slice(0, 300) + "…" : joined;
+    const score = scoreText(joined, userTexts.join(" ").length, mdBody.length);
+    return { title, preview, insightScore: score };
+}
+/** Pull text from every "## User" block. Stops at the next "## " heading. */
+function extractUserTexts(md) {
+    const out = [];
+    const lines = md.split("\n");
+    let inUser = false;
+    let buf = [];
+    for (const line of lines) {
+        if (/^## User\b/.test(line)) {
+            if (buf.length > 0) {
+                out.push(buf.join("\n").trim());
+                buf = [];
+            }
+            inUser = true;
+            continue;
+        }
+        if (/^## /.test(line)) {
+            if (inUser && buf.length > 0) {
+                out.push(buf.join("\n").trim());
+                buf = [];
+            }
+            inUser = false;
+            continue;
+        }
+        if (inUser)
+            buf.push(line);
+    }
+    if (inUser && buf.length > 0)
+        out.push(buf.join("\n").trim());
+    return out.filter((s) => s.length > 0);
+}
+function scoreText(joinedLower, userTextLen, totalLen) {
+    if (!joinedLower)
+        return 0;
+    const lower = joinedLower.toLowerCase();
+    let categoryHits = 0;
+    let totalHits = 0;
+    for (const keywords of Object.values(SIGNAL_CATEGORIES)) {
+        const hits = keywords.filter((kw) => lower.includes(kw)).length;
+        if (hits > 0) {
+            categoryHits++;
+            totalHits += hits;
+        }
+    }
+    if (categoryHits < 2)
+        return 0.1;
+    const userRatio = userTextLen / Math.max(totalLen, 1);
+    const score = (categoryHits / 5) * 0.4 + (totalHits / 15) * 0.3 + userRatio * 0.3;
+    return Math.min(1.0, score);
+}

package/dist/src/digest/toc.js

@@ -0,0 +1,127 @@
+/** Min length of sanitized user text to qualify as a "real" prompt (vs. a
+ *  tool_result wrapper). Matches the writer's existing sanitizer gate. */
+const USER_TEXT_MIN = 50;
+/** Min length of an assistant's plain text reply (no tool_use) to count as
+ *  a substantive "voice" turn worth listing in the TOC. Below this, the
+ *  message is usually "OK", "done", or a brief acknowledgement. */
+const ASSISTANT_TEXT_MIN = 200;
+/** Bash sub-commands that signal a noteworthy VCS event. `git push` excluded:
+ *  it's procedural, and we already capture the underlying commit/tag. */
+const GIT_NOTEWORTHY_RE = /\bgit\s+(commit|tag)\b/;
+/** Tools that materially mutate the repo. */
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/**
+ * Build an importance-based TOC. Tool-result-only turns are skipped; what
+ * remains is real user prompts, file edits, commits, and substantive
+ * assistant replies. Markers reflect what makes a turn noteworthy (a turn
+ * may have multiple).
+ *
+ * @param messages SessionMessage[] in chronological order.
+ * @param messageLineOffsets parallel array: messageLineOffsets[i] is the line
+ *   number of message i's `## User`/`## Assistant` heading in the final
+ *   rendered md. Consumers `Read offset:line` to jump straight to the turn.
+ */
+export function buildTocEntries(messages, messageLineOffsets) {
+    const out = [];
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        const markers = computeMarkers(m);
+        if (!markers)
+            continue;
+        out.push({
+            turn: i + 1,
+            timestamp: m.timestamp ?? "",
+            markers,
+            preview: computePreview(m),
+            line: messageLineOffsets[i] ?? 0,
+        });
+    }
+    return out;
+}
+function computeMarkers(m) {
+    const marks = [];
+    if (m.role === "user" && m.text && m.text.length >= USER_TEXT_MIN) {
+        marks.push("🧑");
+    }
+    if (m.role === "assistant") {
+        let hasEdit = false;
+        let hasCommit = false;
+        for (const b of m.contentBlocks ?? []) {
+            if (b.type !== "tool_use")
+                continue;
+            if (EDIT_TOOLS.has(b.name))
+                hasEdit = true;
+            if (b.name === "Bash") {
+                const cmd = readCommand(b);
+                if (cmd && GIT_NOTEWORTHY_RE.test(cmd))
+                    hasCommit = true;
+            }
+        }
+        if (hasCommit)
+            marks.push("💾");
+        if (hasEdit)
+            marks.push("✏️");
+        // Substantive text reply (no tool calls dominating it): a real "voice"
+        // turn. We check after edit/commit so the markers stack naturally.
+        if (m.text && m.text.length >= ASSISTANT_TEXT_MIN && !hasEdit && !hasCommit) {
+            marks.push("🤖");
+        }
+    }
+    return marks.join("");
+}
+function computePreview(m) {
+    // Prefer user/assistant text. For tool-only turns, summarize the actions.
+    if (m.text)
+        return previewOf(m.text, 100);
+    const actions = [];
+    for (const b of m.contentBlocks ?? []) {
+        if (b.type !== "tool_use")
+            continue;
+        if (EDIT_TOOLS.has(b.name)) {
+            const fp = b.input?.file_path;
+            if (typeof fp === "string")
+                actions.push(`${b.name} ${fp}`);
+            else
+                actions.push(b.name);
+        }
+        else if (b.name === "Bash") {
+            const cmd = readCommand(b);
+            if (cmd) {
+                const firstLine = cmd.split("\n", 1)[0].trim();
+                actions.push(firstLine);
+            }
+        }
+        if (actions.length >= 2)
+            break;
+    }
+    return previewOf(actions.join(" · "), 100);
+}
+function readCommand(b) {
+    const input = b.input;
+    if (!input || typeof input !== "object")
+        return null;
+    return typeof input.command === "string" ? input.command : null;
+}
+function previewOf(text, max) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > max ? collapsed.slice(0, max - 1) + "…" : collapsed;
+}
+/** Render the TOC as a markdown block ready to embed in the final md.
+ *  Returns "" if no entries (e.g. session is entirely tool noise). */
+export function renderTocMarkdown(entries) {
+    if (entries.length === 0)
+        return "";
+    const header = `# Table of Contents\n\n` +
+        `Importance-based — real user turns (≥${USER_TEXT_MIN} chars), file edits, commits, and substantive assistant replies. Tool-result-only turns omitted.\n\n` +
+        `| # | Time | Marker | Preview | Line |\n` +
+        `|---|------|--------|---------|------|`;
+    const rows = entries.map((e) => {
+        const time = e.timestamp ? e.timestamp.slice(5, 16).replace("T", " ") : "—";
+        const preview = escapeTableCell(e.preview);
+        return `| ${e.turn} | ${time} | ${e.markers} | ${preview} | →L${e.line} |`;
+    });
+    return [header, ...rows].join("\n");
+}
+function escapeTableCell(s) {
+    return s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}