Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(plugin): catch up on unrecorded messages at session end
Eren213e7b4c0c44
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ac59b4a..3dea12a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- SessionEnd catch-up: when a session ends with user messages that have no node yet, the `SessionEnd` hook starts a detached `codelineage backfill <session-id> --tail` and returns at once; the child reads those messages with the agent's replies, runs `claude -p --safe-mode --no-session-persistence` with the skill's record rules on `catchUpModel` (default `haiku`) and passes the answer through `session write` (validation, redaction, transcript times, rebuild). The tail is not stored, so a dead child is retried from the transcript next time. With `sessionEndCatchUp` off no tokens are spent, and the map shows "N messages not recorded" on that session.- SessionStart setup hint: on `startup` or `resume` in a project without `.codelineage/`, the plugin offers setup to the agent (it says codelineage is not set up and sets it up only when the user asks, running the bundled `init` with the answers), and the hint notes that a plugin update reaches a running session only after `/reload-plugins` or a new chat. `codelineage config hint-off [dir]` silences the hint in that project ("don't ask again", kept in the global `setupHintOff` list, keyed by the main checkout so a worktree is covered) and `codelineage config hint-on [dir] [--all]` turns it back on. `CODELINEAGE_DISABLE=1` still silences every hook.- Compaction safety net: SessionStart with `source: "compact"` reads the transcript and, when user messages have no lineage node yet, asks the agent through `additionalContext` to run `/codelineage:lineage` (compaction keeps every transcript line, so nothing is lost and no snapshot is taken). `session show` also adds a `transcriptWarning` when the transcript has user lines but none reads as a message, so a Claude Code format change is noticed instead of silently recording nothing.- The map shows the conversation: a message's drill-down has the message as the user wrote it and the agent's written replies (tool output left out, tool use counted in one line), with buttons to step to the previous or next message across topics. `build` reads it from the Claude Code transcript into `lineage.html` only, which is never committed; session files still hold no raw text. Long entries open folded; a deleted transcript is said so.diff --git a/packages/cli/hooks/hooks.json b/packages/cli/hooks/hooks.jsonindex e7701fa..06431f3 100644--- a/packages/cli/hooks/hooks.json+++ b/packages/cli/hooks/hooks.json@@ -23,6 +23,18 @@}]}+ ],+ "SessionEnd": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "node",+ "args": ["${CLAUDE_PLUGIN_ROOT}/dist/cli.js", "hook", "sessionend"],+ "timeout": 5+ }+ ]+ }]}}diff --git a/packages/cli/src/commands/backfill.ts b/packages/cli/src/commands/backfill.tsnew file mode 100644index 0000000..ddcc67d--- /dev/null+++ b/packages/cli/src/commands/backfill.ts@@ -0,0 +1,214 @@+import { spawn } from "node:child_process";+import { CliError, type Io } from "../io.js";+import type { Session } from "../schema/session.js";+import { LockBusyError, withLock } from "../store/lock.js";+import { projectPaths } from "../store/paths.js";+import { resolveProjectRoot } from "../store/root.js";+import { loadConfig, loadProject, loadSession } from "../store/stores.js";+import { type ChatTurn, findTranscript, readConversation } from "../transcript.js";+import { sessionWrite } from "./session.js";++/** How much of one message or reply goes into the prompt. */+const TEXT_LIMIT = 1500;++/** Keeps the prompt finite; the summary only needs the gist of a long paste. */+function cut(text: string): string {+ return text.length <= TEXT_LIMIT ? text : `${text.slice(0, TEXT_LIMIT)}…`;+}++/** One unrecorded message with the agent's replies and tool counts after it. */+function turnBlock(turn: ChatTurn): string {+ const agent =+ turn.replies.length === 0 ? "(no written reply)" : turn.replies.map(cut).join("\n\n");+ const { commands, other } = turn.tools;+ const tools = `${commands} command(s), ${turn.tools.files.length} file(s) edited, ${other} other tool call(s)`;+ return [+ `### ${turn.id} · ${turn.at}`,+ `USER: ${cut(turn.text)}`,+ `AGENT: ${agent}`,+ `TOOLS: ${tools}`,+ ].join("\n");+}++function recordPart(record: Session | undefined): string {+ if (!record || record.nodes.length === 0) return "The record has no nodes yet.";+ const lines = record.nodes.map(+ (node) => `- ${node.id} (${node.kind}) parent=${node.parent ?? "null"}: ${node.title}`,+ );+ return `The record so far (reuse these topic ids):\n${lines.join("\n")}`;+}++function rules(language: string): string {+ const writing = language === "auto" ? "the conversation's language" : language;+ return [+ "Rules (from the codelineage lineage skill):",+ '- Send one "message" node for every message below, with the id exactly as given; skip none, even a short "ok".',+ '- kind is "message". title: a few words in the user\'s own wording. summary: one or two sentences on what came of it.',+ '- parent: the id of the topic it belongs to. Reuse a topic id from the record below; otherwise add a "phase" topic with a short slug id and parent null.',+ '- When the message itself made a decision (the user asked for it, picked an option or approved a proposal): decidedBy ("user" or "agreed"), the reason in why, and the options not taken in alternatives [{"option": "...", "why": "..."}].',+ '- The agent\'s work goes inside the message node that caused it, never in nodes of its own: work (short items), agentDecisions ([{"title": "...", "why": "...", "alternatives": [...]}]), commits (short hashes) and files (a few paths).',+ '- Never send "at"; the CLI takes each message\'s time from the transcript.',+ "- Replace the whole status (goal, done, pending [{text, needsUser}], next) when it changed; otherwise leave it out.",+ "- Record decisions and reasons, never secrets, credentials, personal data, file contents or command output.",+ `- Write titles and text in ${writing}; JSON keys stay in English.`,+ ].join("\n");+}++/**+ * The one prompt the headless catch-up gets: the skill's record rules, the+ * record so topics can be reused, and the unrecorded messages themselves.+ */+export function catchUpPrompt(+ turns: ChatTurn[],+ record: Session | undefined,+ sessionId: string,+ language: string,+): string {+ return [+ "You add the missing part of a codelineage lineage record, a map of the user's messages.",+ "Below are the user's messages that have no node yet, each followed by the agent's written replies and a count of its tool calls.",+ "",+ rules(language),+ "",+ recordPart(record),+ "",+ "Messages to record:",+ turns.map(turnBlock).join("\n\n"),+ "",+ `Return only one JSON object, no commentary and no code fences: {"sessionId": ${JSON.stringify(+ sessionId,+ )}, "nodes": [...], "status": {...}}`,+ ].join("\n");+}++/** The text inside Claude Code's `--output-format json` envelope. */+export function resultText(stdout: string): string {+ let envelope: unknown;+ try {+ envelope = JSON.parse(stdout);+ } catch {+ throw new CliError("claude did not print valid JSON");+ }+ const result = (envelope as { result?: unknown }).result;+ if (typeof result !== "string") throw new CliError("claude returned no result text");+ return result;+}++/** The agent's answer as a JSON object, tolerating a code fence around it. */+export function agentRecord(text: string): Record<string, unknown> {+ const cleaned = text+ .trim()+ .replace(/^```(?:json)?\s*/, "")+ .replace(/\s*```$/, "");+ let parsed: unknown;+ try {+ parsed = JSON.parse(cleaned);+ } catch {+ throw new CliError("the agent did not return a JSON record");+ }+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))+ throw new CliError("the agent did not return a JSON object");+ return parsed as Record<string, unknown>;+}++/** The headless agent must not fire our own hooks or leave a transcript. */+export function headlessEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {+ return { ...process.env, ...env, CODELINEAGE_DISABLE: "1" };+}++function claudeBin(): string {+ return process.platform === "win32" ? "claude.cmd" : "claude";+}++/**+ * Runs the agent once, headless and without session persistence, with the prompt+ * on stdin. Resolves with stdout; a missing binary or a failed run rejects.+ */+function runClaude(prompt: string, model: string, env: NodeJS.ProcessEnv): Promise<string> {+ return new Promise((resolve, reject) => {+ const child = spawn(+ claudeBin(),+ [+ "-p",+ "--safe-mode",+ "--no-session-persistence",+ "--model",+ model,+ "--output-format",+ "json",+ ],+ { env: headlessEnv(env), stdio: ["pipe", "pipe", "pipe"] },+ );+ let out = "";+ let err = "";+ // The child may exit before reading the prompt; that write error is not ours.+ child.stdin.on("error", () => {});+ child.stdout.setEncoding("utf8").on("data", (chunk: string) => {+ out += chunk;+ });+ child.stderr.setEncoding("utf8").on("data", (chunk: string) => {+ err += chunk;+ });+ child.on("error", (error) => {+ reject(new CliError(`could not run claude: ${error.message}`));+ });+ child.on("close", (code) => {+ if (code === 0) resolve(out);+ else reject(new CliError(`claude exited with ${code}: ${err.trim() || "no output"}`));+ });+ child.stdin.end(prompt);+ });+}++/** The user messages of a session that have no node yet, oldest first. */+async function missingTurns(+ root: string,+ sessionId: string,+ env: NodeJS.ProcessEnv,+): Promise<ChatTurn[]> {+ const file = await findTranscript(sessionId, env);+ if (!file) return [];+ const turns = await readConversation(file);+ const loaded = await loadSession(root, sessionId);+ const recorded = new Set(loaded.found && loaded.ok ? loaded.data.nodes.map((n) => n.id) : []);+ return turns.filter((turn) => !recorded.has(turn.id));+}++/**+ * `codelineage backfill <session-id> --tail`: records the user messages a session+ * never got to, by running the agent headless with the skill's rules and passing+ * its answer through `session write` (validation, redaction, stamping, build).+ * A busy session lock means another catch-up already runs, which is not an error.+ */+export async function backfillTail(dir: string, sessionId: string, io: Io): Promise<void> {+ const { root } = await resolveProjectRoot(dir);+ const project = await loadProject(root);+ if (!project.found)+ throw new CliError(`${root} is not initialized; run \`codelineage init\` first`);+ if (!project.ok) throw new CliError(project.error);++ let turns: ChatTurn[] | undefined;+ try {+ turns = await withLock(+ projectPaths(root).lock(`session-${sessionId}`),+ () => missingTurns(root, sessionId, io.env),+ { timeoutMs: 0 },+ );+ } catch (err) {+ if (!(err instanceof LockBusyError)) throw err;+ io.out(`catch-up already running for ${sessionId}`);+ return;+ }+ if (turns.length === 0) {+ io.out(`session ${sessionId} has nothing to catch up`);+ return;+ }++ const config = await loadConfig(io.env);+ const loaded = await loadSession(root, sessionId);+ const record = loaded.found && loaded.ok ? loaded.data : undefined;+ const prompt = catchUpPrompt(turns, record, sessionId, config.language);+ const stdout = await runClaude(prompt, config.catchUpModel, io.env);+ const payload = { ...agentRecord(resultText(stdout)), sessionId };+ await sessionWrite({ dir: root }, io, async () => JSON.stringify(payload));+}diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.tsindex c46aef3..6288f6c 100644--- a/packages/cli/src/commands/build.ts+++ b/packages/cli/src/commands/build.ts@@ -4,8 +4,8 @@ import type { Session } from "../schema/session.js";import { atomicWrite } from "../store/fs.js";import { projectPaths } from "../store/paths.js";import { resolveProjectRoot } from "../store/root.js";-import { loadAllSessions, loadProject } from "../store/stores.js";-import { type ChatTurn, displayTurn, readConversation } from "../transcript.js";+import { loadAllSessions, loadConfig, loadProject } from "../store/stores.js";+import { type ChatTurn, displayTurn, readConversation, readUserMessages } from "../transcript.js";import { buildViewModel, embedViewModel } from "../view/lineage.js";import type { LineageViewModel } from "../view/model.js";import { buildPanel } from "../view/panel.js";@@ -50,6 +50,32 @@ async function readChats(return chats;}+/**+ * User messages with no node, per session, counted from the transcripts. The+ * SessionEnd hook normally records them; while the catch-up is off this count is+ * the only sign. An unreadable transcript is skipped, never failing the build.+ */+export async function countUnrecorded(+ sessions: Session[],+ transcripts: ReadonlyMap<string, string>,+): Promise<Map<string, number>> {+ const counts = new Map<string, number>();+ for (const session of sessions) {+ const file = transcripts.get(session.sessionId);+ if (!file) continue;+ let messages;+ try {+ messages = await readUserMessages(file);+ } catch {+ continue;+ }+ const recorded = new Set(session.nodes.map((node) => node.id));+ const missing = messages.filter((message) => !recorded.has(message.id)).length;+ if (missing > 0) counts.set(session.sessionId, missing);+ }+ return counts;+}+/*** Rebuilds `.codelineage/lineage.html` from `project.json` and every session file,* then refreshes the global panel. One unreadable session is a warning, never a@@ -67,6 +93,7 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModelconst paths = projectPaths(root);const sessions = await loadAllSessions(root, io.warn);const transcripts = await collectTranscripts(io.env);+ const config = await loadConfig(io.env);const model = buildViewModel({project: project.data,sessions,@@ -74,6 +101,9 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModelgeneratedAt: io.now(),transcripts: new Set(transcripts.keys()),chats: await readChats(sessions, transcripts, root, io),+ // With the catch-up on, the hook records the tail at session end, so the+ // count would only be a stale warning about work already scheduled.+ unrecorded: config.sessionEndCatchUp ? undefined : await countUnrecorded(sessions, transcripts),});// The skill already avoids secrets; this is the safety net before rendering.const redacted = redactDeep(model);diff --git a/packages/cli/src/hooks/run.ts b/packages/cli/src/hooks/run.tsindex 60ed87a..3562607 100644--- a/packages/cli/src/hooks/run.ts+++ b/packages/cli/src/hooks/run.ts@@ -1,8 +1,11 @@+import { spawn } from "node:child_process";import { existsSync } from "node:fs";+import { fileURLToPath } from "node:url";import { z } from "zod";import { Slug } from "../schema/common.js";import { projectPaths } from "../store/paths.js";import { resolveProjectRoot } from "../store/root.js";+import { onSessionEnd } from "./sessionend.js";import { onSessionStart } from "./sessionstart.js";import { onStop } from "./stop.js";@@ -25,17 +28,40 @@ export interface HookContext {initialized: boolean;env: NodeJS.ProcessEnv;now: string;+ /** Starts the detached catch-up (`node <cli> <args>`); never waited for. */+ spawnDetached: (args: string[]) => void;}export type HookOutput = Record<string, unknown>;+/** Test seams for the effects a hook leaves behind. */+export interface HookDeps {+ /** The CLI file a detached child runs; defaults to the running script. */+ cli?: string;+ /** Starts the detached process; tests observe instead of spawning. */+ spawnDetached?: (cli: string, args: string[], env: NodeJS.ProcessEnv) => void;+}+const HANDLERS: Record<string, (ctx: HookContext) => Promise<HookOutput | undefined>> = {stop: onStop,sessionstart: onSessionStart,+ sessionend: onSessionEnd,};export const HOOK_EVENTS = Object.keys(HANDLERS);+/**+ * Starts `node <cli> <args>` detached, with capture disabled in the child so it+ * cannot fire these hooks again. The hook returns at once.+ */+export function spawnDetachedProcess(cli: string, args: string[], env: NodeJS.ProcessEnv): void {+ spawn(process.execPath, [cli, ...args], {+ detached: true,+ stdio: "ignore",+ env: { ...env, CODELINEAGE_DISABLE: "1" },+ }).unref();+}+/*** Runs one hook and returns what to print on stdout, if anything. A hook must* never break the user's session, so every failure ends in silence; the reason@@ -47,6 +73,7 @@ export async function runHook(env: NodeJS.ProcessEnv,now: string,debug: (line: string) => void,+ deps: HookDeps = {},): Promise<string | undefined> {try {if (env.CODELINEAGE_DISABLE === "1") return undefined;@@ -60,7 +87,18 @@ export async function runHook(// Before `init` every hook is a no-op except SessionStart, which offers setup;// projects are never registered here.if (!initialized && handler !== onSessionStart) return undefined;- const out = await handler({ input, sessionId: input.session_id, root, initialized, env, now });+ const cli = deps.cli ?? process.argv[1] ?? fileURLToPath(import.meta.url);+ const startCatchUp = (args: string[]) =>+ (deps.spawnDetached ?? spawnDetachedProcess)(cli, args, env);+ const out = await handler({+ input,+ sessionId: input.session_id,+ root,+ initialized,+ env,+ now,+ spawnDetached: startCatchUp,+ });return out === undefined ? undefined : JSON.stringify(out);} catch (err) {debug(`codelineage ${event} hook: ${(err as Error).message}`);diff --git a/packages/cli/src/hooks/sessionend.ts b/packages/cli/src/hooks/sessionend.tsnew file mode 100644index 0000000..dd8f7ad--- /dev/null+++ b/packages/cli/src/hooks/sessionend.ts@@ -0,0 +1,28 @@+import { loadConfig, loadSession } from "../store/stores.js";+import { findTranscript, readConversation } from "../transcript.js";+import type { HookContext } from "./run.js";++/**+ * SessionEnd hook. SessionEnd cannot make the agent act and hook commands get a+ * 1.5 s budget, so this only starts the detached catch-up and returns. The tail+ * is not stored: the catch-up reads whatever messages still have no node, so a+ * child that dies is retried when the session is opened next.+ */+export async function onSessionEnd(ctx: HookContext): Promise<undefined> {+ if (!ctx.initialized) return undefined;+ const config = await loadConfig(ctx.env);+ if (!config.sessionEndCatchUp) return undefined;+ const file = await findTranscript(ctx.sessionId, ctx.env);+ if (!file) return undefined;+ let turns;+ try {+ turns = await readConversation(file);+ } catch {+ return undefined;+ }+ const record = await loadSession(ctx.root, ctx.sessionId);+ const recorded = new Set(record.found && record.ok ? record.data.nodes.map((n) => n.id) : []);+ if (turns.every((turn) => recorded.has(turn.id))) return undefined;+ ctx.spawnDetached(["backfill", ctx.sessionId, "--tail", "-C", ctx.root]);+ return undefined;+}diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.tsindex ae2a98c..5dff0da 100644--- a/packages/cli/src/program.ts+++ b/packages/cli/src/program.ts@@ -1,5 +1,6 @@import { Command, InvalidArgumentError, Option } from "commander";import pkg from "../package.json" with { type: "json" };+import { backfillTail } from "./commands/backfill.js";import { buildProject } from "./commands/build.js";import {configGet,@@ -132,6 +133,22 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =),);+ program+ .command("backfill")+ .description("record the user messages a session has not summarized yet")+ .argument("<session-id>", "session id")+ .option("-C, --dir <dir>", "project directory", ".")+ .option("--tail", "only this session's messages that have no node yet")+ .action(+ run(async (sessionId: string, opts: { dir: string; tail?: boolean }) => {+ if (opts.tail !== true)+ throw new CliError(+ "backfill of past sessions is not available yet; run `codelineage backfill <session-id> --tail`",+ );+ await backfillTail(opts.dir, sessionId, makeIo(false));+ }),+ );+const epoch = program.command("epoch").description("manage epochs (features, epics)");epoch.command("add")diff --git a/packages/cli/src/schema/config.ts b/packages/cli/src/schema/config.tsindex 61c6fd9..cc58438 100644--- a/packages/cli/src/schema/config.ts+++ b/packages/cli/src/schema/config.ts@@ -9,6 +9,8 @@ export const Config = z.object({language: z.string().min(1).max(32).default("auto"),updateEveryTurns: z.int().min(1).max(100).default(5),sessionEndCatchUp: z.boolean().default(true),+ /** Model for the headless catch-up (SessionEnd) and, later, backfill. */+ catchUpModel: z.string().trim().min(1).max(64).default("haiku"),/** Default for new projects; `init` asks per repo. */gitPolicy: z.enum(["ignore", "commit"]).default("ignore"),agents: z.array(z.string().min(1)).default(["claude-code"]),diff --git a/packages/cli/src/view/lineage.ts b/packages/cli/src/view/lineage.tsindex b34e719..0ae8b70 100644--- a/packages/cli/src/view/lineage.ts+++ b/packages/cli/src/view/lineage.ts@@ -154,6 +154,7 @@ function toViewSession(session: Session,transcripts?: ReadonlySet<string>,chat?: ViewChatTurn[],+ unrecorded?: number,): ViewSession {return {sessionId: session.sessionId,@@ -168,6 +169,7 @@ function toViewSession(// record is shown as resumable rather than pretending the transcript is gone.transcriptAvailable: transcripts === undefined ? true : transcripts.has(session.sessionId),...(session.worktree ? { worktree: session.worktree } : {}),+ ...(unrecorded ? { unrecordedMessages: unrecorded } : {}),...(chat ? { chat } : {}),};}@@ -187,6 +189,8 @@ export interface ViewModelInput {transcripts?: ReadonlySet<string>;/** Each session's conversation from its transcript, shown in the drill-down. */chats?: ReadonlyMap<string, ViewChatTurn[]>;+ /** Unrecorded message counts, shown while the catch-up is off. */+ unrecorded?: ReadonlyMap<string, number> | undefined;}/**@@ -201,7 +205,12 @@ export function buildViewModel(input: ViewModelInput): LineageViewModel {const sessions = [...input.sessions].sort(byStartedAt);for (const session of sessions) {- const view = toViewSession(session, input.transcripts, input.chats?.get(session.sessionId));+ const view = toViewSession(+ session,+ input.transcripts,+ input.chats?.get(session.sessionId),+ input.unrecorded?.get(session.sessionId),+ );const bucket = session.epoch === null ? undefined : buckets.get(session.epoch);(bucket ?? unassigned).push(view);}diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.tsindex 3f2ecd7..f90a421 100644--- a/packages/cli/src/view/model.ts+++ b/packages/cli/src/view/model.ts@@ -84,6 +84,11 @@ export interface ViewSession {transcriptAvailable: boolean;/** The linked git worktree the session ran in, if any. */worktree?: { path: string; branch: string | null };+ /**+ * User messages the record does not hold yet, counted from the transcript at+ * build time. Only set while the SessionEnd catch-up is off.+ */+ unrecordedMessages?: number;/*** The conversation, for sessions that record messages and still have their* transcript. It lives only in the generated page, never in the session file.diff --git a/packages/cli/test/backfill.test.ts b/packages/cli/test/backfill.test.tsnew file mode 100644index 0000000..c601d8c--- /dev/null+++ b/packages/cli/test/backfill.test.ts@@ -0,0 +1,245 @@+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { beforeEach, describe, expect, it } from "vitest";+import {+ agentRecord,+ backfillTail,+ catchUpPrompt,+ headlessEnv,+ resultText,+} from "../src/commands/backfill.js";+import { init } from "../src/commands/init.js";+import { sessionWrite } from "../src/commands/session.js";+import type { Session } from "../src/schema/session.js";+import { projectPaths } from "../src/store/paths.js";+import { loadSession } from "../src/store/stores.js";+import type { ChatTurn } from "../src/transcript.js";+import { envFor, fakeIo, T0, tempDir } from "./helpers.js";++let dir: string;+let root: string;++beforeEach(async () => {+ dir = await tempDir();+ root = join(dir, "proj");+ await mkdir(root);+});++/** A transcript for session s1, under the fake Claude home. */+async function transcript(lines: unknown[]): Promise<void> {+ const folder = join(envFor(dir).CLAUDE_CONFIG_DIR ?? "", "projects", "proj");+ await mkdir(folder, { recursive: true });+ await writeFile(join(folder, "s1.jsonl"), `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`);+}++const typed = (text: string, minute: number) => ({+ type: "user",+ timestamp: `2026-10-23T10:0${minute}:00.000Z`,+ message: { role: "user", content: text },+});++/** Puts a fake `claude` first on PATH and returns the env that finds it. */+async function fakeClaude(script: string, path: string): Promise<NodeJS.ProcessEnv> {+ const bin = join(path, "bin");+ await mkdir(bin, { recursive: true });+ const file = join(bin, "claude");+ await writeFile(file, `#!/usr/bin/env node\n${script}\n`);+ await chmod(file, 0o755);+ return { ...envFor(dir), PATH: `${bin}:${process.env.PATH ?? ""}` };+}++/** Reads stdin, keeps the prompt for inspection and prints a result envelope. */+function printing(result: string): string {+ return `+process.stdin.setEncoding("utf8");+let input = "";+process.stdin.on("data", (chunk) => { input += chunk; });+process.stdin.on("end", async () => {+ const fs = await import("node:fs");+ fs.writeFileSync(${JSON.stringify(join(dir, "prompt.txt"))}, input);+ process.stdout.write(JSON.stringify({ type: "result", subtype: "success", result: ${JSON.stringify(result)} }));+});`;+}++const GOOD = JSON.stringify({+ status: { goal: "Ship 4.7", done: [], pending: [], next: "release" },+ nodes: [+ { id: "topic", kind: "phase", parent: null, title: "Catch-up" },+ { id: "m2", kind: "message", parent: "topic", title: "Second", summary: "Recorded it" },+ ],+});++async function initialized(env: NodeJS.ProcessEnv): Promise<void> {+ await init(root, { name: "proj", retention: "keep", language: "auto" }, fakeIo(env));+}++const record = async (): Promise<Session | undefined> => {+ const loaded = await loadSession(root, "s1");+ return loaded.found && loaded.ok ? loaded.data : undefined;+};++describe("catchUpPrompt", () => {+ const turn: ChatTurn = {+ id: "m7",+ at: T0,+ text: "x".repeat(2000),+ replies: [],+ tools: { commands: 0, files: [], other: 0 },+ };++ it("includes the rules, a cut message and an empty record", () => {+ const prompt = catchUpPrompt([turn], undefined, "s1", "Turkish");+ expect(prompt).toContain("The record has no nodes yet.");+ expect(prompt).toContain("titles and text in Turkish");+ expect(prompt).toContain("(no written reply)");+ expect(prompt).toContain("…");+ expect(prompt).toContain('{"sessionId": "s1", "nodes": [...]');+ });++ it("lists the existing topics, the replies and the tool counts", () => {+ const prompt = catchUpPrompt(+ [{ ...turn, replies: ["ok"], tools: { commands: 1, files: ["a.ts"], other: 2 } }],+ {+ schema: 1,+ sessionId: "s1",+ agent: "claude-code",+ title: "",+ epoch: null,+ startedAt: T0,+ updatedAt: T0,+ status: { goal: "", done: [], pending: [], next: "" },+ nodes: [{ id: "topic", parent: null, kind: "phase", title: "Topic" }],+ },+ "s1",+ "auto",+ );+ expect(prompt).toContain("parent=null: Topic");+ expect(prompt).toContain("AGENT: ok");+ expect(prompt).toContain("1 command(s), 1 file(s) edited, 2 other tool call(s)");+ expect(prompt).toContain("the conversation's language");+ });+});++describe("headless output", () => {+ it("reads the result text out of the envelope", () => {+ expect(resultText(JSON.stringify({ result: "x" }))).toBe("x");+ expect(() => resultText("nope")).toThrow(/valid JSON/);+ expect(() => resultText("{}")).toThrow(/no result text/);+ });++ it("accepts an object, with or without a code fence, and rejects the rest", () => {+ expect(agentRecord('{"a":1}')).toEqual({ a: 1 });+ expect(agentRecord('```json\n{"a":1}\n```')).toEqual({ a: 1 });+ expect(() => agentRecord("not json")).toThrow(/JSON record/);+ expect(() => agentRecord("[1]")).toThrow(/JSON object/);+ });++ it("turns capture off in the headless run", () => {+ expect(headlessEnv({ PATH: "/bin" })).toMatchObject({+ PATH: "/bin",+ CODELINEAGE_DISABLE: "1",+ });+ });+});++describe("backfill --tail", () => {+ it("records the missing messages through session write and rebuilds the map", async () => {+ const env = await fakeClaude(printing(GOOD), dir);+ await initialized(env);+ await transcript([typed("first", 1), typed("second", 2)]);+ await sessionWrite({ dir: root }, fakeIo(env), async () =>+ JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),+ );++ const io = fakeIo(env);+ await backfillTail(root, "s1", io);+ const saved = await record();+ expect(saved?.nodes.map((n) => n.id)).toEqual(expect.arrayContaining(["m1", "topic", "m2"]));+ // The time comes from the transcript, not from the agent.+ expect(saved?.nodes.find((n) => n.id === "m2")).toMatchObject({+ at: "2026-10-23T10:02:00.000Z",+ summary: "Recorded it",+ });+ expect(io.lines).toContain("Saved session s1 (3 nodes)");++ const prompt = await readFile(join(dir, "prompt.txt"), "utf8");+ expect(prompt).toContain("USER: second");+ expect(prompt).toContain('"sessionId": "s1"');+ expect(prompt).toContain("- m1 (message) parent=null: First");+ expect(prompt).toContain("the conversation's language");+ });++ it("does nothing when there is no transcript or nothing missing", async () => {+ const env = envFor(dir);+ await initialized(env);+ const io = fakeIo(env);+ await backfillTail(root, "s1", io);+ expect(io.lines).toEqual(["session s1 has nothing to catch up"]);++ await transcript([typed("first", 1)]);+ await sessionWrite({ dir: root }, fakeIo(env), async () =>+ JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),+ );+ const again = fakeIo(env);+ await backfillTail(root, "s1", again);+ expect(again.lines).toEqual(["session s1 has nothing to catch up"]);+ });++ it("exits quietly when another catch-up holds the session lock", async () => {+ const env = envFor(dir);+ await initialized(env);+ await transcript([typed("first", 1)]);+ const lock = projectPaths(root).lock("session-s1");+ await mkdir(lock, { recursive: true });+ await writeFile(join(lock, "owner"), String(process.pid));++ const io = fakeIo(env);+ await backfillTail(root, "s1", io);+ expect(io.lines).toEqual(["catch-up already running for s1"]);+ expect(await record()).toBeUndefined();+ });++ it("rejects an answer that is not a JSON record and leaves the record alone", async () => {+ const env = await fakeClaude(printing("not json"), dir);+ await initialized(env);+ await transcript([typed("first", 1)]);+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/JSON record/);+ expect(await record()).toBeUndefined();+ });++ it("reports a failed headless run with its stderr and keeps the record", async () => {+ const env = await fakeClaude('process.stderr.write("boom"); process.exit(3);', dir);+ await initialized(env);+ await transcript([typed("first", 1)]);+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(+ /claude exited with 3: boom/,+ );+ expect(await record()).toBeUndefined();+ });++ it("reports a missing claude binary", async () => {+ const empty = join(dir, "empty");+ await mkdir(empty);+ const env = { ...envFor(dir), PATH: empty };+ await initialized(env);+ await transcript([typed("first", 1)]);+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/could not run claude/);+ });++ it("refuses an uninitialized or unreadable project", async () => {+ const env = envFor(dir);+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/not initialized/);+ await mkdir(join(root, ".codelineage"), { recursive: true });+ await writeFile(join(root, ".codelineage", "project.json"), "{nope");+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/invalid JSON/);+ });++ it("propagates a lock that cannot be created", async () => {+ const env = envFor(dir);+ await initialized(env);+ await transcript([typed("first", 1)]);+ await rm(projectPaths(root).locks, { recursive: true, force: true });+ await writeFile(projectPaths(root).locks, "not a directory");+ await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow();+ });+});diff --git a/packages/cli/test/build.test.ts b/packages/cli/test/build.test.tsindex 5e3cfde..757dfce 100644--- a/packages/cli/test/build.test.ts+++ b/packages/cli/test/build.test.ts@@ -2,7 +2,8 @@ import { existsSync } from "node:fs";import { mkdir, readFile, rm, writeFile } from "node:fs/promises";import { join } from "node:path";import { beforeEach, describe, expect, it } from "vitest";-import { buildProject } from "../src/commands/build.js";+import { buildProject, countUnrecorded } from "../src/commands/build.js";+import { configSet } from "../src/commands/config.js";import { epochAdd } from "../src/commands/epoch.js";import { init } from "../src/commands/init.js";import { sessionWrite } from "../src/commands/session.js";@@ -485,6 +486,48 @@ describe("codelineage build", () => {expect(await readFile(paths().session("s1"), "utf8")).not.toContain("Fix the card");});+ it("counts unrecorded messages only while the catch-up is off", async () => {+ const folder = join(dir, "claude", "projects", "-proj");+ await mkdir(folder, { recursive: true });+ const lines = [+ { type: "user", timestamp: T0, message: { content: "one" } },+ { type: "user", timestamp: "2026-01-02T00:00:00.000Z", message: { content: "two" } },+ ];+ await writeFile(join(folder, "s1.jsonl"), lines.map((l) => JSON.stringify(l)).join("\n"));+ await saveSession(+ "s1",+ session({+ sessionId: "s1",+ epoch: "e1",+ nodes: [node("m1", "message", "One", null, { at: T0 })],+ }),+ );+ // A session with no transcript must not break the count.+ await saveSession("s2", session({ sessionId: "s2", epoch: "e1" }));++ const on = await buildProject({ dir: root, io, templateHtml: TEMPLATE, quiet: true });+ const recorded = (model: typeof on) =>+ model.epochs[0]?.sessions.find((s) => s.sessionId === "s1");+ expect(recorded(on)).not.toHaveProperty("unrecordedMessages");++ await configSet("sessionEndCatchUp", "false", fakeIo(envFor(dir)));+ const off = await buildProject({ dir: root, io, templateHtml: TEMPLATE, quiet: true });+ expect(recorded(off)?.unrecordedMessages).toBe(1);+ expect(off.epochs[0]?.sessions.find((s) => s.sessionId === "s2")).not.toHaveProperty(+ "unrecordedMessages",+ );+ });++ it("ignores a transcript that cannot be read while counting", async () => {+ const folder = join(dir, "claude", "projects", "-proj");+ await mkdir(join(folder, "s1.jsonl"), { recursive: true });+ const counts = await countUnrecorded(+ [session({ sessionId: "s1" })],+ new Map([["s1", join(folder, "s1.jsonl")]]),+ );+ expect(counts.size).toBe(0);+ });+it("builds without printing when quiet and survives a missing sessions directory", async () => {await rm(paths().sessions, { recursive: true });await buildProject({ dir: root, io, templateHtml: TEMPLATE, quiet: true });diff --git a/packages/cli/test/config-epoch.test.ts b/packages/cli/test/config-epoch.test.tsindex d053b39..97bddbb 100644--- a/packages/cli/test/config-epoch.test.ts+++ b/packages/cli/test/config-epoch.test.ts@@ -21,6 +21,7 @@ describe("config", () => {const io = fakeIo(env);await configGet(undefined, io);expect(io.lines).toContain("updateEveryTurns = 5");+ expect(io.lines).toContain('catchUpModel = "haiku"');await configGet("gitPolicy", io);expect(io.lines.at(-1)).toBe('"ignore"');});@@ -30,11 +31,13 @@ describe("config", () => {await configSet("updateEveryTurns", "3", io);await configSet("sessionEndCatchUp", "false", io);await configSet("language", "Turkish", io);+ await configSet("catchUpModel", "sonnet", io);await configSet("agents", "claude-code, codex", io);expect(await loadConfig(env)).toMatchObject({updateEveryTurns: 3,sessionEndCatchUp: false,language: "Turkish",+ catchUpModel: "sonnet",agents: ["claude-code", "codex"],});await configSet("agents", '["claude-code"]', io);diff --git a/packages/cli/test/hooks.test.ts b/packages/cli/test/hooks.test.tsindex 91220d9..f992c84 100644--- a/packages/cli/test/hooks.test.ts+++ b/packages/cli/test/hooks.test.ts@@ -5,7 +5,7 @@ import { beforeEach, describe, expect, it } from "vitest";import { configHintOff, configHintOn, configSet } from "../src/commands/config.js";import { init } from "../src/commands/init.js";import { sessionWrite } from "../src/commands/session.js";-import { runHook } from "../src/hooks/run.js";+import { runHook, spawnDetachedProcess } from "../src/hooks/run.js";import { COMPACT_REQUEST } from "../src/hooks/sessionstart.js";import { countTurn, UPDATE_REQUEST } from "../src/hooks/stop.js";import { projectPaths } from "../src/store/paths.js";@@ -42,6 +42,7 @@ describe("runHook", () => {let root: string;let env: NodeJS.ProcessEnv;let debug: string[];+ let spawned: string[][];const stop = (extra: Record<string, unknown> = {}, e = env) =>runHook("stop", JSON.stringify({ session_id: "s1", cwd: root, ...extra }), e, T0, (l) =>@@ -53,12 +54,27 @@ describe("runHook", () => {debug.push(l),);+ // The catch-up itself is covered by backfill.test.ts; here we only see the spawn.+ const sessionEnd = (e = env) =>+ runHook(+ "sessionend",+ JSON.stringify({ session_id: "s1", cwd: root }),+ e,+ T0,+ (l) => debug.push(l),+ {+ cli: "/plugin/dist/cli.js",+ spawnDetached: (cli, args) => spawned.push([cli, ...args]),+ },+ );+beforeEach(async () => {dir = await tempDir();root = join(dir, "proj");await mkdir(root);env = envFor(dir);debug = [];+ spawned = [];});const initialized = async (everyTurns: number) => {@@ -236,6 +252,60 @@ describe("runHook", () => {expect(await sessionStart("compact")).toBeUndefined();});+ it("spawns the detached catch-up at session end when messages have no node", async () => {+ await initialized(2);+ await transcript([typed("first", 1)]);+ expect(await sessionEnd()).toBeUndefined();+ expect(spawned).toEqual([["/plugin/dist/cli.js", "backfill", "s1", "--tail", "-C", root]]);+ });++ it("does not spawn at session end when everything is recorded or catch-up is off", async () => {+ await initialized(2);+ await transcript([typed("first", 1)]);+ await sessionWrite({ dir: root }, fakeIo(env), async () =>+ JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),+ );+ expect(await sessionEnd()).toBeUndefined();+ expect(spawned).toEqual([]);++ await transcript([typed("second", 2)]);+ await configSet("sessionEndCatchUp", "false", fakeIo(env));+ expect(await sessionEnd()).toBeUndefined();+ expect(spawned).toEqual([]);+ });++ it("stays quiet at session end without a readable transcript or before init", async () => {+ await initialized(2);+ expect(await sessionEnd()).toBeUndefined();+ // A directory where the transcript should be: found, but reading it fails.+ await mkdir(join(env.CLAUDE_CONFIG_DIR ?? "", "projects", "proj", "s1.jsonl"), {+ recursive: true,+ });+ expect(await sessionEnd()).toBeUndefined();+ expect(spawned).toEqual([]);++ const fresh = await tempDir();+ const freshRoot = join(fresh, "proj");+ await mkdir(freshRoot);+ const freshSpawned: string[][] = [];+ expect(+ await runHook(+ "sessionend",+ JSON.stringify({ session_id: "s1", cwd: freshRoot }),+ envFor(fresh),+ T0,+ () => {},+ { spawnDetached: (cli, args) => freshSpawned.push([cli, ...args]) },+ ),+ ).toBeUndefined();+ expect(freshSpawned).toEqual([]);+ });++ it("starts the detached child with capture disabled", () => {+ // /dev/null exits at once; this exercises the real spawn path without a CLI.+ expect(() => spawnDetachedProcess("/dev/null", [], env)).not.toThrow();+ });+it("stays silent when disabled, for unknown events and for bad input", async () => {await initialized(1);expect(await stop({}, { ...env, CODELINEAGE_DISABLE: "1" })).toBeUndefined();diff --git a/packages/cli/test/program-commands.test.ts b/packages/cli/test/program-commands.test.tsindex cbc92cb..43738cf 100644--- a/packages/cli/test/program-commands.test.ts+++ b/packages/cli/test/program-commands.test.ts@@ -91,6 +91,13 @@ describe("commands through the CLI", () => {expect((await loadConfig(io.env)).setupHintOff).toEqual([]);});+ it("runs backfill --tail and refuses backfill without it", async () => {+ await cli("init", root, "--yes", "--retention", "keep");+ expect(await cli("backfill", "s1")).toMatch(/--tail/);+ expect(await cli("backfill", "s1", "--tail", "-C", root)).toBe("");+ expect(io.lines.at(-1)).toBe("session s1 has nothing to catch up");+ });+it("runs session write from a file", async () => {await cli("init", root, "--yes", "--retention", "keep");const f = join(dir, "s.json");diff --git a/packages/template/src/SidePanel.tsx b/packages/template/src/SidePanel.tsxindex 4540e4e..3ba6ef9 100644--- a/packages/template/src/SidePanel.tsx+++ b/packages/template/src/SidePanel.tsx@@ -140,6 +140,13 @@ function SessionSummary({ model, session }: { model: LineageViewModel; session:<Field label="Started">{formatTime(session.startedAt)}</Field><Field label="Updated">{formatTime(session.updatedAt)}</Field><WorktreeField session={session} />+ {session.unrecordedMessages ? (+ <Field label="Not recorded">+ {session.unrecordedMessages} message+ {session.unrecordedMessages === 1 ? "" : "s"} not recorded (the SessionEnd catch-up is+ off)+ </Field>+ ) : null}</dl><ResumeRow model={model} session={session} /></>