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(hooks): hand the agent the lineage at session start
Eren0fe1f323411d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9cfbd5a..1d4df02 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added- `codelineage log [dir]` prints the recorded lineage like `git log --graph --oneline`, newest first: per message its short hash, `mN`, time, title, `↩` returns and commit tags, a branch's first message with the branch title, and a header line per session (title, epoch, time span). `--session <id|prefix>` narrows to one session, `-n <count>` limits the messages, `--branches` prints only the branch summaries (title, asked, outcome, open) and `--json` prints the model. `codelineage show <ref> [dir]` prints one message — session, time, parent and children as refs, returns, the branch it sits in with that branch's summary, decisions, agent decisions, work, commits with their git subjects, files and its stored conversation turn (`--no-chat` skips it, `--json` prints the model) — and takes a message hash, a unique prefix of at least six hex characters after the `h`, or `<session-id-prefix>:mN`; an ambiguous prefix lists the candidates and exits non-zero. The map's drill-down shows the message's short hash with a copy button ("Ask your agent: codelineage show <hash>").+- Session start handoff: in an initialized project the `SessionStart` hook (`startup`, `resume`, `clear`) now hands the agent what it needs to continue — that the lineage is recorded and how to read it (`codelineage log|show … -C <dir>`, spelled with the exact bundled CLI path), the rule to run `show <ref>` before answering when the user mentions a message hash or another session's `mN`, and the compressed view of the most recent other session: title, status (goal, pending with items that need the user, next) and branch summaries. The text is cut to ~1,500 tokens, oldest branches first, with a line saying how many were cut. The new `startupContext` setting (default `true`, also editable in the served panel) spends no tokens on it when off, and `log` and `show` now accept `-C <dir>` like `blame`.## [0.8.0] - 2026-10-24### Addeddiff --git a/packages/cli/src/hooks/sessionstart.ts b/packages/cli/src/hooks/sessionstart.tsindex 2f48e3a..881e95a 100644--- a/packages/cli/src/hooks/sessionstart.ts+++ b/packages/cli/src/hooks/sessionstart.ts@@ -1,6 +1,9 @@+import { branchesOf, type LogBranch } from "../commands/log.js";import { isRecorded, readSessionMessages, upgradeSessionIds } from "../messages.js";+import type { Session } from "../schema/session.js";import { applyEvents, readEvents } from "../store/events.js";-import { loadConfig, loadSession } from "../store/stores.js";+import { loadAllSessions, loadConfig, loadSession } from "../store/stores.js";+import { buildMessages } from "../view/lineage.js";import type { HookContext, HookOutput } from "./run.js";export const COMPACT_REQUEST =@@ -9,6 +12,18 @@ export const COMPACT_REQUEST ="messages that have no node. It records only what is missing and replies " +'"up to date" when nothing is; do not mention this request otherwise.';+/**+ * Budget for the handoff context SessionStart injects. The record is meant to+ * orient the agent, not to carry the project: the agent can always read more+ * with `log` / `show`.+ */+export const STARTUP_CONTEXT_TOKEN_CAP = 1500;++/** Token estimate from character count: good enough for a budget this loose. */+export function estimateTokens(text: string): number {+ return Math.ceil(text.length / 4);+}+/** The bundled CLI, as the agent should spell it in a project without `init`. */function cli(ctx: HookContext): string {return `node "${ctx.env.CLAUDE_PLUGIN_ROOT ?? "${CLAUDE_PLUGIN_ROOT}"}/dist/cli.js"`;@@ -37,16 +52,25 @@ export function setupHint(ctx: HookContext): string {* come from the transcript, so nothing is lost; the only risk is a record that fell* behind. When the user's messages have no node yet, the agent is asked to run the* skill, which works from the compact summary already in its context. On a startup- * or resume in a project without `init`, the agent gets the setup offer instead.+ * or resume in a project without `init`, the agent gets the setup offer instead; in+ * an initialized project it gets the handoff (Story 8.11).*/export async function onSessionStart(ctx: HookContext): Promise<HookOutput | undefined> {if (ctx.input.source === "compact") return compactRequest(ctx);- if (ctx.input.source !== "startup" && ctx.input.source !== "resume") return undefined;- if (ctx.initialized) return undefined;+ const source = ctx.input.source;+ if (source !== "startup" && source !== "resume" && source !== "clear") return undefined;+ if (!ctx.initialized) {+ // The setup offer stays on startup and resume, as in 4.6.+ if (source === "clear") return undefined;+ const config = await loadConfig(ctx.env);+ // "Don't ask again in this project" lives outside the project.+ if (config.setupHintOff.includes(ctx.root)) return undefined;+ return additionalContext(setupHint(ctx));+ }const config = await loadConfig(ctx.env);- // "Don't ask again in this project" lives outside the project.- if (config.setupHintOff.includes(ctx.root)) return undefined;- return additionalContext(setupHint(ctx));+ // SessionStart runs inside the chat's startup budget: opt out and it is silent.+ if (!config.startupContext) return undefined;+ return additionalContext(await startupContext(ctx));}function additionalContext(text: string): HookOutput {@@ -67,3 +91,109 @@ async function compactRequest(ctx: HookContext): Promise<HookOutput | undefined>if (messages.every((message) => isRecorded(recorded, message))) return undefined;return additionalContext(COMPACT_REQUEST);}++/** One line of prose, however the record stored it. */+function oneLine(text: string): string {+ return text.replace(/\s+/g, " ").trim();+}++function clip(text: string, max: number): string {+ return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;+}++/**+ * What the agent needs to continue the project: where the lineage lives, how to+ * read it, and the compressed view of the last session before this one.+ */+async function startupContext(ctx: HookContext): Promise<string> {+ const command = cli(ctx);+ const header =+ `codelineage records this project's lineage (one node per user message, hanging from the ` ++ `message it reacts to, grouped in sessions with branch summaries). Read it with ` ++ `\`${command} log -C "${ctx.root}"\` and one message with ` ++ `\`${command} show <ref> -C "${ctx.root}"\` (a ref is a message hash, an h+hex prefix of ` ++ `six or more characters, or <session-id>:mN). When the user mentions a message hash or ` ++ `another session's mN, run show before answering.`;++ const sessions = await loadAllSessions(ctx.root, () => {});+ const previous = mostRecentOtherSession(sessions, ctx.sessionId);+ if (previous === undefined) return header;++ const events = await readEvents(ctx.root, previous.sessionId);+ const messages = buildMessages(applyEvents(previous.nodes, events));+ return composeStartupContext(header, previous, branchesOf(previous.sessionId, messages));+}++/** The session with the newest activity, ignoring this one. */+export function mostRecentOtherSession(+ sessions: readonly Session[],+ sessionId: string,+): Session | undefined {+ return sessions+ .filter((session) => session.sessionId !== sessionId)+ .sort(+ (a, b) =>+ b.updatedAt.localeCompare(a.updatedAt) ||+ b.startedAt.localeCompare(a.startedAt) ||+ a.sessionId.localeCompare(b.sessionId),+ )[0];+}++/** The handoff text under the token cap; the oldest branches are cut first. */+export function composeStartupContext(+ header: string,+ session: Session,+ branches: readonly LogBranch[],+): string {+ const head = [header, "", ...statusLines(session)];+ const blocks = branches.map(branchLines);+ const cutNote = (cut: number): string[] =>+ cut === 0+ ? []+ : [+ ` … ${cut} older branch summar${cut === 1 ? "y" : "ies"} cut; ` ++ "read them with `log --branches`.",+ ];++ const render = (kept: string[][], cut: number): string =>+ [...head, ...kept.flat(), ...cutNote(cut)].join("\n");++ const kept = [...blocks];+ let cut = 0;+ while (kept.length > 0 && estimateTokens(render(kept, cut)) > STARTUP_CONTEXT_TOKEN_CAP) {+ // `branchesOf` is in send order, so the first block is the oldest branch.+ kept.shift();+ cut += 1;+ }+ const text = render(kept, cut);+ if (estimateTokens(text) <= STARTUP_CONTEXT_TOKEN_CAP) return text;+ // Only reachable with a huge status block; keep the budget anyway.+ return `${text.slice(0, STARTUP_CONTEXT_TOKEN_CAP * 4 - 2).trimEnd()}…`;+}++/** Session title, goal, pending items and next step — the "squash message". */+function statusLines(session: Session): string[] {+ const title = session.title.trim() === "" ? session.sessionId : clip(oneLine(session.title), 120);+ const lines = [`Earlier session: ${title} (${session.sessionId})`];+ const { goal, pending, next } = session.status;+ if (goal.trim() !== "") lines.push(` goal: ${clip(oneLine(goal), 400)}`);+ const shown = pending.slice(0, 5);+ for (const item of shown) {+ const needsUser = item.needsUser ? " (needs the user)" : "";+ lines.push(` pending: ${clip(oneLine(item.text), 200)}${needsUser}`);+ }+ if (pending.length > shown.length)+ lines.push(` pending: … ${pending.length - shown.length} more`);+ if (next.trim() !== "") lines.push(` next: ${clip(oneLine(next), 400)}`);+ return lines;+}++function branchLines(branch: LogBranch): string[] {+ const count = `${branch.count} message${branch.count === 1 ? "" : "s"}`;+ return [+ ` ╭ ${clip(oneLine(branch.title), 80)} ${branch.start.label}–${branch.end.label}, ${count}`,+ ` asked: ${clip(oneLine(branch.asked), 300)}`,+ ` outcome: ${clip(oneLine(branch.outcome), 600)}`,+ ` open: ${branch.open.trim() === "" ? "—" : clip(oneLine(branch.open), 300)}`,+ ];+}diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.tsindex 609a00a..8b9e637 100644--- a/packages/cli/src/program.ts+++ b/packages/cli/src/program.ts@@ -113,6 +113,7 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =.command("log").description("print the recorded lineage, newest first").argument("[dir]", "project directory", ".")+ .option("-C, --dir <dir>", "project directory (same as the positional)").option("--session <id>", "only this session (id or prefix)").option("-n, --number <count>", "at most this many messages", positiveCount).option("--branches", "only the branch summaries (the compressed view)")@@ -121,10 +122,16 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =run(async (dir: string,- opts: { session?: string; number?: number; branches?: boolean; json?: boolean },+ opts: {+ dir?: string;+ session?: string;+ number?: number;+ branches?: boolean;+ json?: boolean;+ },) => {await log({- dir,+ dir: opts.dir ?? dir,io: makeIo(false),session: opts.session,limit: opts.number,@@ -140,15 +147,22 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =.description("print one recorded message by hash or <session-id>:mN").argument("<ref>", "message hash or <session-id-prefix>:mN").argument("[dir]", "project directory", ".")+ .option("-C, --dir <dir>", "project directory (same as the positional)").option("--no-chat", "leave out the conversation turn").option("--json", "print JSON instead of text").action(- run(async (ref: string, dir: string, opts: { chat?: boolean; json?: boolean }) => {- const io = makeIo(false);- const model = await show({ dir, ref, io, chat: opts.chat !== false });- if (opts.json === true) io.out(JSON.stringify(model, null, 2));- else for (const line of formatShow(model)) io.out(line);- }),+ run(+ async (+ ref: string,+ dir: string,+ opts: { dir?: string; chat?: boolean; json?: boolean },+ ) => {+ const io = makeIo(false);+ const model = await show({ dir: opts.dir ?? dir, ref, io, chat: opts.chat !== false });+ if (opts.json === true) io.out(JSON.stringify(model, null, 2));+ else for (const line of formatShow(model)) io.out(line);+ },+ ),);programdiff --git a/packages/cli/src/schema/config.ts b/packages/cli/src/schema/config.tsindex 4200b93..64c42d8 100644--- a/packages/cli/src/schema/config.ts+++ b/packages/cli/src/schema/config.ts@@ -16,6 +16,11 @@ export const Config = z.object({* summary is the outer layer and the drill-down already shows the reply.*/messageSummaries: z.boolean().default(false),+ /**+ * Whether SessionStart hands the agent the lineage of the previous session and+ * how to read the record (`log` / `show`). On by default; costs only tokens.+ */+ startupContext: z.boolean().default(true),/** Port the local map server binds on `127.0.0.1`. */serverPort: z.int().min(1).max(65535).default(4747),/** Default for new projects; `init` asks per repo. */diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.tsindex d6fb84c..e161968 100644--- a/packages/cli/src/view/model.ts+++ b/packages/cli/src/view/model.ts@@ -30,6 +30,7 @@ export const TOKEN_META_NAME = "codelineage-token";*/export const PANEL_EDITABLE_KEYS = ["messageSummaries",+ "startupContext","language","updateEveryTurns","sessionEndCatchUp",@@ -235,6 +236,7 @@ export interface PanelSettings {sessionEndCatchUp: boolean;catchUpModel: string;messageSummaries: boolean;+ startupContext: boolean;gitPolicy: "ignore" | "commit";agents: string[];}diff --git a/packages/cli/src/view/panel.ts b/packages/cli/src/view/panel.tsindex 164a32b..fb22b29 100644--- a/packages/cli/src/view/panel.ts+++ b/packages/cli/src/view/panel.ts@@ -95,6 +95,7 @@ export async function buildPanel(opts: PanelOptions): Promise<PanelViewModel> {sessionEndCatchUp: config.sessionEndCatchUp,catchUpModel: config.catchUpModel,messageSummaries: config.messageSummaries,+ startupContext: config.startupContext,gitPolicy: config.gitPolicy,agents: config.agents,},diff --git a/packages/cli/test/config-epoch.test.ts b/packages/cli/test/config-epoch.test.tsindex d1fbbbf..07227fc 100644--- a/packages/cli/test/config-epoch.test.ts+++ b/packages/cli/test/config-epoch.test.ts@@ -23,6 +23,7 @@ describe("config", () => {expect(io.lines).toContain("updateEveryTurns = 5");expect(io.lines).toContain('catchUpModel = "haiku"');expect(io.lines).toContain("messageSummaries = false");+ expect(io.lines).toContain("startupContext = true");await configGet("gitPolicy", io);expect(io.lines.at(-1)).toBe('"ignore"');});@@ -34,6 +35,7 @@ describe("config", () => {await configSet("language", "Turkish", io);await configSet("catchUpModel", "sonnet", io);await configSet("messageSummaries", "true", io);+ await configSet("startupContext", "false", io);await configSet("agents", "claude-code, codex", io);expect(await loadConfig(env)).toMatchObject({updateEveryTurns: 3,@@ -41,6 +43,7 @@ describe("config", () => {language: "Turkish",catchUpModel: "sonnet",messageSummaries: true,+ startupContext: false,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 6e39611..6776019 100644--- a/packages/cli/test/hooks.test.ts+++ b/packages/cli/test/hooks.test.ts@@ -6,8 +6,15 @@ import { configHintOff, configHintOn, configSet } from "../src/commands/config.jimport { init } from "../src/commands/init.js";import { sessionWrite } from "../src/commands/session.js";import { runHook, spawnDetachedProcess } from "../src/hooks/run.js";-import { COMPACT_REQUEST } from "../src/hooks/sessionstart.js";+import {+ COMPACT_REQUEST,+ composeStartupContext,+ estimateTokens,+ mostRecentOtherSession,+ STARTUP_CONTEXT_TOKEN_CAP,+} from "../src/hooks/sessionstart.js";import { countTurn, UPDATE_REQUEST } from "../src/hooks/stop.js";+import type { Session, Status } from "../src/schema/session.js";import { projectPaths } from "../src/store/paths.js";import { envFor, fakeIo, T0, tempDir } from "./helpers.js";@@ -37,6 +44,40 @@ describe("countTurn", () => {});});+describe("session start handoff", () => {+ const session = (id: string, startedAt: string, updatedAt: string): Session => ({+ schema: 1,+ sessionId: id,+ agent: "claude-code",+ title: id,+ epoch: null,+ startedAt,+ updatedAt,+ status: { goal: "", done: [], pending: [], next: "" },+ nodes: [],+ });++ it("picks the session with the newest activity, not this one", () => {+ const older = session("old", "2026-10-20T10:00:00.000Z", "2026-10-20T11:00:00.000Z");+ const newer = session("new", "2026-10-19T10:00:00.000Z", "2026-10-21T11:00:00.000Z");+ expect(mostRecentOtherSession([older, newer], "mine")?.sessionId).toBe("new");+ expect(mostRecentOtherSession([older, newer], "new")?.sessionId).toBe("old");+ // Ties fall back to the later start and then the id, so the pick is stable.+ const tied = session("b", "2026-10-21T12:00:00.000Z", "2026-10-21T11:00:00.000Z");+ expect(mostRecentOtherSession([older, newer, tied], "mine")?.sessionId).toBe("b");+ const sameStart = session("a", "2026-10-19T10:00:00.000Z", "2026-10-21T11:00:00.000Z");+ expect(mostRecentOtherSession([newer, sameStart], "mine")?.sessionId).toBe("a");+ expect(mostRecentOtherSession([newer], "new")).toBeUndefined();+ });++ it("truncates even when there are no branches to cut", () => {+ const huge = "x".repeat(STARTUP_CONTEXT_TOKEN_CAP * 4 + 100);+ const text = composeStartupContext(huge, session("s", T0, T0), []);+ expect(estimateTokens(text)).toBeLessThanOrEqual(STARTUP_CONTEXT_TOKEN_CAP);+ expect(text.endsWith("…")).toBe(true);+ });+});+describe("runHook", () => {let dir: string;let root: string;@@ -57,8 +98,8 @@ describe("runHook", () => {},);- const sessionStart = (source: string, e = env) =>- runHook("sessionstart", JSON.stringify({ session_id: "s1", cwd: root, source }), e, T0, (l) =>+ const sessionStart = (source: string, e = env, id = "s1") =>+ runHook("sessionstart", JSON.stringify({ session_id: id, cwd: root, source }), e, T0, (l) =>debug.push(l),);@@ -107,13 +148,110 @@ describe("runHook", () => {);expect(await sessionStart("clear")).toBeUndefined();expect(await sessionStart("startup", { ...env, CODELINEAGE_DISABLE: "1" })).toBeUndefined();+ expect(+ JSON.parse((await sessionStart("startup")) ?? "").hookSpecificOutput.additionalContext,+ ).not.toContain("records this project's lineage");expect(existsSync(join(root, ".codelineage"))).toBe(false);});- it("stays quiet about setup after init", async () => {+ it("replaces the setup offer with the lineage handoff after init", async () => {+ await initialized(2);+ const context = async (source: string) => {+ const out = JSON.parse((await sessionStart(source)) ?? "");+ return out.hookSpecificOutput.additionalContext as string;+ };+ // No earlier session yet: only the "how to read it" line.+ expect(await context("startup")).toContain("codelineage records this project's lineage");+ expect(await context("resume")).toContain(`log -C "${root}"`);+ expect(await context("clear")).toContain("run show before answering");+ });++ const earlierSession = async (+ nodes: unknown[],+ status: Status = { goal: "", done: [], pending: [], next: "" },+ ) =>+ sessionWrite({ dir: root }, fakeIo(env), async () =>+ JSON.stringify({ sessionId: "s0", title: "Earlier work", status, nodes }),+ );++ const startupText = async () =>+ JSON.parse((await sessionStart("startup")) ?? "").hookSpecificOutput+ .additionalContext as string;++ it("hands over the previous session's status and branch summaries at startup", async () => {+ await initialized(2);+ await earlierSession(+ [+ {+ id: "m1",+ kind: "message",+ title: "Start",+ at: "2026-10-21T09:00:00.000Z",+ branch: {+ title: "Setup",+ asked: "how do we start",+ outcome: "scaffold ready",+ open: "tests",+ },+ },+ { id: "m2", kind: "message", title: "Next", parent: "m1", at: "2026-10-21T09:10:00.000Z" },+ ],+ {+ goal: "ship the map",+ done: [],+ pending: [+ { text: "choose a port", needsUser: true },+ { text: "p2", needsUser: false },+ { text: "p3", needsUser: false },+ { text: "p4", needsUser: false },+ { text: "p5", needsUser: false },+ { text: "p6", needsUser: false },+ ],+ next: "write tests",+ },+ );+ const text = await startupText();+ expect(text).toContain(`log -C "${root}"`);+ expect(text).toContain(`show <ref> -C "${root}"`);+ expect(text).toContain("Earlier session: Earlier work (s0)");+ expect(text).toContain("goal: ship the map");+ expect(text).toContain("pending: choose a port (needs the user)");+ expect(text).toContain("pending: … 1 more");+ expect(text).toContain("next: write tests");+ expect(text).toContain("╭ Setup m1–m2, 2 messages");+ expect(text).toContain("asked: how do we start");+ expect(text).toContain("outcome: scaffold ready");+ });++ it("cuts the oldest branches from the handoff to stay under the token cap", async () => {+ await initialized(2);+ const nodes = Array.from({ length: 12 }, (_, i) => ({+ id: `m${i + 1}`,+ kind: "message",+ title: `M${i + 1}`,+ at: `2026-10-21T09:${String(i).padStart(2, "0")}:00.000Z`,+ ...(i === 0 ? {} : { parent: `m${i}` }),+ branch: {+ title: `Branch ${i + 1}`,+ asked: `asked ${i + 1} ${"a".repeat(250)}`,+ outcome: "o".repeat(580),+ open: "",+ },+ }));+ await earlierSession(nodes);+ const text = await startupText();+ expect(estimateTokens(text)).toBeLessThanOrEqual(STARTUP_CONTEXT_TOKEN_CAP);+ expect(text).toMatch(/older branch summar(y|ies) cut/);+ expect(text).toContain("╭ Branch 12");+ expect(text).not.toContain("╭ Branch 1 ");+ });++ it("stays quiet at session start when startupContext is off", async () => {await initialized(2);+ await configSet("startupContext", "false", fakeIo(env));expect(await sessionStart("startup")).toBeUndefined();expect(await sessionStart("resume")).toBeUndefined();+ expect(await sessionStart("clear")).toBeUndefined();});it("silences the setup hint per project with hint-off and undoes it with hint-on", async () => {@@ -240,13 +378,11 @@ describe("runHook", () => {expect(await sessionStart("compact")).toBeUndefined();});- it("stays quiet for other sources, without a transcript and when disabled", async () => {+ it("stays quiet for unknown sources, without a transcript and when disabled", async () => {await initialized(2);expect(await sessionStart("compact")).toBeUndefined();await transcript([typed("first", 1)]);- expect(await sessionStart("startup")).toBeUndefined();- expect(await sessionStart("resume")).toBeUndefined();- expect(await sessionStart("clear")).toBeUndefined();+ expect(await sessionStart("elsewhere")).toBeUndefined();expect(await sessionStart("compact", { ...env, CODELINEAGE_DISABLE: "1" })).toBeUndefined();});diff --git a/packages/cli/test/panel.test.ts b/packages/cli/test/panel.test.tsindex c86b9a2..a97df2e 100644--- a/packages/cli/test/panel.test.ts+++ b/packages/cli/test/panel.test.ts@@ -86,6 +86,7 @@ describe("buildPanel", () => {sessionEndCatchUp: true,catchUpModel: "haiku",messageSummaries: false,+ startupContext: true,gitPolicy: "ignore",agents: ["claude-code"],},diff --git a/packages/cli/test/server.test.ts b/packages/cli/test/server.test.tsindex 2f01869..8e7ca3c 100644--- a/packages/cli/test/server.test.ts+++ b/packages/cli/test/server.test.ts@@ -321,6 +321,10 @@ describe("settings write", () => {expect(JSON.parse(reply.body)).toEqual({ ok: true, key: "messageSummaries", value: true });expect((await loadConfig(env)).messageSummaries).toBe(true);+ const handoff = await configWrite(server, token, { key: "startupContext", value: false });+ expect(handoff.status).toBe(200);+ expect((await loadConfig(env)).startupContext).toBe(false);+const panel = globalPaths(env).panel;const deadline = Date.now() + 3000;let html = "";diff --git a/packages/template/src/Panel.tsx b/packages/template/src/Panel.tsxindex 50e8297..2ca5f1c 100644--- a/packages/template/src/Panel.tsx+++ b/packages/template/src/Panel.tsx@@ -17,6 +17,7 @@ interface EditableSpec {/** The keys the panel may change (Story 8.9); the server enforces the same list. */const EDITABLE: EditableSpec[] = [{ key: "messageSummaries", label: "Message summaries", kind: "boolean" },+ { key: "startupContext", label: "Lineage at session start", kind: "boolean" },{ key: "language", label: "Language", kind: "text" },{ key: "updateEveryTurns", label: "Update every turns", kind: "number" },{ key: "sessionEndCatchUp", label: "Catch up on session end", kind: "boolean" },diff --git a/specs/codelineage-mvp.md b/specs/codelineage-mvp.mdindex 47d9f44..d05bf67 100644--- a/specs/codelineage-mvp.md+++ b/specs/codelineage-mvp.md@@ -213,6 +213,17 @@ Behavior verified against the Claude Code hooks docs (2026-10-21):- Verified (Claude Code 2.1.300, Linux): a child started from SessionEnd with`spawn(…, { detached: true, stdio: "ignore" }).unref()` outlives both the hookand Claude Code exiting, and is reparented to the init process.+- **Session start handoff.** In an initialized project, SessionStart on `startup`,+ `resume` or `clear` (not `compact`) gives the agent what it needs to continue+ without a hand-written note: one paragraph saying that the lineage is recorded and+ how to read it (`node "<plugin>/dist/cli.js" log|show … -C "<dir>"`, exact paths),+ the rule to run `show <ref>` before answering when the user mentions a message hash+ or another session's `mN`, then the compressed view of the most recent session other+ than this one — its title, status (`goal`, `pending` with items that need the user,+ `next`) and branch summaries. The text stays under ~1,500 tokens: the oldest+ branches are cut first and a line says how many were cut. Setting:+ `startupContext` (on by default; off spends no tokens on it). It replaces+ hand-written handoff files for the common case; existing ones are left alone.- **Before `init`:** if `.codelineage/` does not exist, all hooks are no-ops, exceptthat SessionStart on `startup` or `resume` injects a one-line offer: the agent sayscodelineage is not set up here and sets it up only when the user asks. Setup happens@@ -247,8 +258,8 @@ Each update costs agent tokens (the user's subscription or API usage).| `codelineage build [dir]` | Regenerates `lineage.html` and `panel.html` || `codelineage open [dir]` | Builds, then opens the map (or the panel if no dir is given) through the local map server, starting it in the background if it is not running. The open page refreshes itself whenever the map is rebuilt, keeping the selected branch, unfolded branches, scroll and zoom. Falls back to opening the file when the server cannot start. || `codelineage blame <file>[:<line>]` | Follows git blame (or `git log` for a whole file) back to the messages whose record lists those commits; prints each commit, session, message, summary and the map URL that opens that message. Says so plainly when no record knows the code. |-| `codelineage log [dir]` | Prints the lineage like `git log --graph --oneline`, newest first: per message its short hash, `mN`, time, title, `↩` returns and commit tags, a branch's first message with the branch title, and a header line per session (title, epoch, time span). `--session <id\|prefix>` narrows to one session, `-n <count>` limits the messages, `--branches` prints only the branch summaries (title, asked, outcome, open — the compressed view), and `--json` prints the model. Plain text; no colour when not a TTY. |-| `codelineage show <ref> [dir]` | Prints one message: hash, `mN`, session, time, parent and children (as refs), `links`, the branch it belongs to with that branch's summary, decisions (`decidedBy`, `why`, `alternatives`), agent decisions, work, commits with their git subjects, files, then its conversation turn from the store (`--no-chat` skips it; `--json` prints the model). A `<ref>` is a message hash or any unique prefix of at least six hex characters after the `h`, or `<session-id-prefix>:mN`; an ambiguous prefix lists the candidates and exits non-zero, an unknown one says so plainly. |+| `codelineage log [dir]` | Prints the lineage like `git log --graph --oneline`, newest first: per message its short hash, `mN`, time, title, `↩` returns and commit tags, a branch's first message with the branch title, and a header line per session (title, epoch, time span). `-C <dir>` works instead of the positional, `--session <id\|prefix>` narrows to one session, `-n <count>` limits the messages, `--branches` prints only the branch summaries (title, asked, outcome, open — the compressed view), and `--json` prints the model. Plain text; no colour when not a TTY. |+| `codelineage show <ref> [dir]` | Prints one message: hash, `mN`, session, time, parent and children (as refs), `links`, the branch it belongs to with that branch's summary, decisions (`decidedBy`, `why`, `alternatives`), agent decisions, work, commits with their git subjects, files, then its conversation turn from the store (`-C <dir>` works instead of the positional; `--no-chat` skips the turn; `--json` prints the model). A `<ref>` is a message hash or any unique prefix of at least six hex characters after the `h`, or `<session-id-prefix>:mN`; an ambiguous prefix lists the candidates and exits non-zero, an unknown one says so plainly. || `codelineage epoch add <id> <title>` | Adds an epoch (locked write) || `codelineage config get/set <key> [value]` | Reads or changes settings || `codelineage config hint-off [dir]` | Stops the SessionStart setup offer in that project ("don't ask again") |@@ -279,11 +290,13 @@ Each update costs agent tokens (the user's subscription or API usage).Settings in `config.json`: `language`, `updateEveryTurns`, `sessionEndCatchUp`,`catchUpModel` (model for the headless catch-up and backfill, default `haiku`),`messageSummaries` (write a per-message summary; default `false`),+`startupContext` (give the agent the previous session's lineage at session start;+default `true`),`serverPort` (local map server, default 4747),`gitPolicy`, `agents`, `setupHintOff` (project roots where the SessionStart setupoffer stays silent). The panel may change `language`, `updateEveryTurns`,-`sessionEndCatchUp`, `catchUpModel` and `messageSummaries` over the local server;-everything else stays on `codelineage config set`.+`sessionEndCatchUp`, `catchUpModel`, `messageSummaries` and `startupContext` over the+local server; everything else stays on `codelineage config set`.## Privacy