peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/session/session-manager.js

@@ -0,0 +1,502 @@
+/**
+ * Session management service for Peaks artifact storage.
+ * Manages session lifecycle: creation, retrieval, and directory initialization.
+ *
+ * Sessions are automatically created when any skill is invoked.
+ * Each session gets a unique directory under .peaks/ with incrementing numbered files.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdir as mkdirAsync } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { ensureSession } from './session-binding-bridge.js';
+// As of slice 2026-06-05-peaks-runtime-layer the project-level session
+// binding lives under `.peaks/_runtime/session.json`. The legacy
+// `.peaks/.session.json` path is preserved as a read-only fallback for one
+// minor release so older CLI versions (or trees that have not been migrated
+// by `peaks workspace reconcile`) keep working without a forced re-init.
+const SESSION_FILE = join('_runtime', 'session.json');
+const LEGACY_SESSION_FILE = '.session.json';
+const META_FILE = 'session.json';
+function getLegacySessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', LEGACY_SESSION_FILE);
+}
+/**
+ * Canonicalize a project root path. Returns the realpath
+ * (resolving all symlinks — important on macOS where `/var`
+ * is a symlink to `/private/var`, and on the dev box where
+ * `/tmp` is the same `/private/var/folders/...` target as
+ * `/var/folders/...`). If the path does not exist (e.g. in
+ * tests that write the binding before the dir, or callers
+ * that pass a non-existent path), falls back to the
+ * `resolve()`d absolute form so the function NEVER throws.
+ */
+function canonicalizeProjectRoot(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Resolve a stored `projectRoot` value (from
+ * `.peaks/.session.json`) against the caller-passed
+ * `projectRoot`, then canonicalize. Handles two forms the
+ * legacy strict-equality check missed:
+ *
+ *   1. **Stored is relative** (e.g. `"."` when the binding
+ *      was written from inside the project dir). We resolve
+ *      it against the caller — if the caller's project root
+ *      is absolute, `path.resolve(caller, ".")` returns the
+ *      caller's absolute form, which then canonicalizes to
+ *      the caller's realpath.
+ *
+ *   2. **Both are absolute but the stored form is not
+ *      canonical** (e.g. `/var/folders/...` vs
+ *      `/private/var/folders/...` on macOS). Both canonicalize
+ *      to the same realpath.
+ *
+ * The combined check is the canonicalize-on-read contract.
+ */
+function resolveStoredAgainstCaller(stored, caller) {
+    const resolved = resolve(caller, stored); // if `stored` is absolute, returns `stored`; else joins with caller
+    return canonicalizeProjectRoot(resolved);
+}
+/**
+ * Generate a new session ID.
+ * Format: YYYY-MM-DD-session-<6位hex>
+ * Example: 2026-05-26-session-a3f8b1
+ */
+function generateSessionId() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const date = `${year}-${month}-${day}`;
+    const random = randomBytes(3).toString('hex'); // 6位hex
+    return `${date}-session-${random}`;
+}
+/**
+ * Get the path to the session file for a project. The canonical home is
+ * `.peaks/_runtime/session.json`; the legacy `.peaks/.session.json` is
+ * read-only fallback (see `readSessionFile`).
+ */
+function getSessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', SESSION_FILE);
+}
+/**
+ * Read existing session info from disk.
+ * Returns null if no session file exists or if it's invalid.
+ *
+ * Strict equality on `data.projectRoot === projectRoot` is
+ * preserved here on purpose: many other modules depend on
+ * the strict-equality semantics to test the "no session bound"
+ * code path. Changing the read semantics here would cascade
+ * into many test failures — out of scope for the progress
+ * rebind fix.
+ *
+ * The progress subcommands (which are the surface that
+ * actually breaks on the rebind bug) use
+ * `getSessionIdCanonical` instead, which does the
+ * canonicalize-on-read resolution the bug fix needs.
+ */
+function readSessionFile(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` so older CLI versions or pre-migration
+    // trees keep working. When both exist, the new path wins.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        if (data.sessionId && data.projectRoot === projectRoot) {
+            return data;
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Same as `readSessionFile` but canonicalizes BOTH the
+ * caller-passed and stored `projectRoot` before comparing.
+ * See `resolveStoredAgainstCaller` for the rules.
+ *
+ * Exported as `readSessionFileCanonical` so the new
+ * `getSessionIdCanonical` can use it; not part of the
+ * public API otherwise.
+ */
+function readSessionFileCanonical(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` for one minor release.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
+        if (data.sessionId &&
+            storedRaw !== null &&
+            resolveStoredAgainstCaller(storedRaw, projectRoot) === resolveStoredAgainstCaller(projectRoot, projectRoot)) {
+            return data;
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Write session info to disk at the canonical new path
+ * `.peaks/_runtime/session.json`. The `.peaks/_runtime/` directory is
+ * created on demand. The legacy `.peaks/.session.json` is NOT written by
+ * this slice; it is only read for back-compat.
+ */
+function writeSessionFile(projectRoot, info) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const dir = dirname(sessionFile);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
+}
+/**
+ * Drop the project-level session binding at the canonical
+ * `.peaks/_runtime/session.json` so the next `ensureSession()` call
+ * auto-generates a fresh session id. The on-disk session directory
+ * is left intact — rotating does NOT delete the user's data, it
+ * just unbinds the project from that session. Also drops the legacy
+ * `.peaks/.session.json` if present so a stale read from another
+ * tool cannot re-bind the project after rotation.
+ *
+ * Returns the id of the session that was unbound, or `null` if
+ * no binding was present. The caller is expected to do something
+ * with that — at minimum surface it in the CLI response so the
+ * user can find the directory again if they need to.
+ *
+ * Slice 008 (F22 fix): the read uses the canonicalize-on-read
+ * variant so a binding written with `projectRoot: "."` (relative
+ * form, anchored from inside the project dir) is still found when
+ * the caller passes the absolute realpath. Pre-F22 the
+ * strict-equality read returned null in that case, and rotate
+ * silently no-op'd (the CLI reported "no prior binding").
+ */
+export function rotateSessionBinding(projectRoot) {
+    const previous = readSessionFileCanonical(projectRoot);
+    if (previous === null) {
+        return null;
+    }
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (existsSync(sessionFile)) {
+        unlinkSync(sessionFile);
+    }
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    if (existsSync(legacyFile)) {
+        try {
+            unlinkSync(legacyFile);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best-effort: a stale legacy binding is not blocking
+        }
+    }
+    return previous.sessionId;
+}
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/_runtime/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export function setCurrentSessionBinding(projectRoot, sessionId) {
+    const info = {
+        sessionId,
+        createdAt: new Date().toISOString(),
+        projectRoot
+    };
+    writeSessionFile(projectRoot, info);
+    return info;
+}
+function getMetaFilePath(projectRoot, sessionId) {
+    // As of slice 2026-06-06-session-layout-canonicalize, the per-session
+    // `session.json` (the file written by `setSessionMeta`) lives at the
+    // canonical runtime home `.peaks/_runtime/<sid>/session.json`, NOT
+    // at the top-level `.peaks/_runtime/<sid>/session.json` (which would imply
+    // the legacy session-scoped layout and conflict with the workspace
+    // service's `_runtime/<sid>/` invariant). The migration in slice
+    // 003 moved any top-level meta files into the runtime home.
+    return join(projectRoot, '.peaks', '_runtime', sessionId, META_FILE);
+}
+function readSessionMeta(projectRoot, sessionId) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function writeSessionMeta(projectRoot, sessionId, meta) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    // As of slice 003, the meta file lives at `.peaks/_runtime/<sid>/session.json`.
+    // The parent dir of that file is the canonical runtime session dir.
+    const metaDir = dirname(metaPath);
+    if (!existsSync(metaDir)) {
+        mkdirSync(metaDir, { recursive: true });
+    }
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+}
+/**
+ * Read metadata for a specific session directory.
+ * Returns null if the session directory or its session.json does not exist.
+ */
+export function getSessionMeta(projectRoot, sessionId) {
+    return readSessionMeta(projectRoot, sessionId);
+}
+/**
+ * Write or update metadata for a session.  Fields besides sessionId and createdAt
+ * are merged on top of the current meta (partial update).
+ */
+export function setSessionMeta(projectRoot, sessionId, partial) {
+    const existing = readSessionMeta(projectRoot, sessionId);
+    const now = new Date().toISOString();
+    const meta = existing
+        ? { ...existing, ...partial, lastActivity: now }
+        : {
+            sessionId,
+            projectRoot,
+            createdAt: now,
+            ...partial,
+            lastActivity: now
+        };
+    writeSessionMeta(projectRoot, sessionId, meta);
+    return meta;
+}
+/**
+ * Set the display title for a session directory.
+ */
+export function setSessionTitle(projectRoot, sessionId, title) {
+    return setSessionMeta(projectRoot, sessionId, { title });
+}
+/**
+ * List all session directories under .peaks with their metadata.
+ * Returns sessions sorted by sessionId descending (most recent first).
+ *
+ * As of slice 2026-06-06-session-layout-canonicalize the session
+ * dirs live at the canonical runtime home `.peaks/_runtime/<sid>/`.
+ * The legacy top-level layout is read for back-compat (one minor
+ * release) but is not authoritative.
+ */
+export function listSessionMetas(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    const peaksRoot = join(projectRoot, '.peaks');
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const meta = readSessionMeta(projectRoot, name);
+            result.push(meta ?? { sessionId: name, projectRoot, createdAt: '' });
+        }
+    };
+    // Canonical home first, then the legacy top-level (back-compat).
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    result.sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+    return result;
+}
+/**
+ * Back-compat read for the legacy top-level meta file (the one that
+ * pre-slice 003 trees still have at `.peaks/_runtime/<sid>/session.json`).
+ * Kept as a separate helper so the canonical reader is the default.
+ */
+function readSessionMetaCompat(peaksRoot, sessionId) {
+    const metaPath = join(peaksRoot, sessionId, META_FILE);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+// `ensureSession` and `ensureSessionWithRotation` (plus the
+// `EnsureSessionOptions` / `EnsureSessionResult` types) moved to
+// `./session-binding-bridge.ts` in v2.18.0 to keep this file under
+// the Karpathy 800 LOC cap. The re-export below preserves the public
+// import path for the 5 external callers — see the bridge file header
+// for the rationale. Do NOT add new logic here.
+export { ensureSession, ensureSessionWithRotation } from './session-binding-bridge.js';
+/**
+ * Get the current session ID without creating a new one.
+ * Returns null if no session exists.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Session ID or null
+ */
+export function getSessionId(projectRoot) {
+    const info = readSessionFile(projectRoot);
+    return info?.sessionId ?? null;
+}
+/**
+ * Resolve the current session id with canonicalize-on-read
+ * semantics. This is the variant the progress subcommands
+ * (step / watch / start / close) use, because the legacy
+ * `getSessionId` returns null any time the stored
+ * `projectRoot` form differs from the caller-passed form
+ * (e.g. stored is "." from inside the project dir; caller
+ * is the absolute realpath). When `getSessionId` returns
+ * null, callers like `ensureSession` create a brand-new
+ * session and overwrite the binding — which is what the
+ * user observed as the "mid-dogfood rebind" bug.
+ *
+ * The fix is to canonicalize both sides of the compare
+ * (realpath, then optionally resolve relative stored
+ * against the caller's project root). The two forms of
+ * the same physical directory now compare equal, and the
+ * existing binding is found instead of being overwritten.
+ *
+ * Use this instead of `getSessionId` only when the
+ * caller is operating on a user-supplied `--project` flag
+ * and the binding may have been written by a CLI invocation
+ * that was running from inside the project dir (the common
+ * peaks-code / peaks-sop scenario). Other modules depend
+ * on the strict-equality semantics of `getSessionId` (the
+ * "no binding" fallback path is part of their contract),
+ * so this variant is opt-in.
+ */
+export function getSessionIdCanonical(projectRoot) {
+    const info = readSessionFileCanonical(projectRoot);
+    return info?.sessionId ?? null;
+}
+/**
+ * Get the absolute path to the current session directory.
+ * Creates the session if it doesn't exist.
+ *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/_runtime/<sid>/` is the back-compat read fallback only.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/_runtime/2026-05-26-session-a3f8b1")
+ */
+export async function getCurrentSessionDir(projectRoot) {
+    const sessionId = await ensureSession(projectRoot);
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+/**
+ * List all session directories in the .peaks folder.
+ * Returns session IDs (directory names) sorted by date.
+ *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/_runtime/<sid>/` is read for back-compat (one minor release) so
+ * pre-migration trees keep working.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Array of session IDs
+ */
+export function listSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    const peaksRoot = join(projectRoot, '.peaks');
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            result.push(name);
+        }
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    return result.sort().reverse();
+}
+/**
+ * Get the path to project-scan.md for the current session.
+ * Creates the session if it doesn't exist.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path to project-scan.md
+ */
+export async function getProjectScanPath(projectRoot) {
+    const sessionId = await ensureSession(projectRoot);
+    // As of slice 2026-06-05-change-id-as-unit-of-work the session dir
+    // is at the canonical runtime location (gitignored). The scan is a
+    // session-local artifact; it lives alongside the rest of the
+    // ephemeral state under `_runtime/`. The parent `rd/` subdir is
+    // created on demand so the first scanner call has a place to land
+    // (consistent with the legacy behavior pre-1.3.1).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'rd', 'project-scan.md');
+    await mkdirAsync(dirname(scanPath), { recursive: true });
+    return scanPath;
+}
+/**
+ * Check if project-scan.md exists for the current session.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns true if project-scan.md exists
+ */
+export function hasProjectScan(projectRoot) {
+    const info = readSessionFile(projectRoot);
+    if (!info)
+        return false;
+    // Canonical runtime location of the session dir (slice 2026-06-05).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', info.sessionId, 'rd', 'project-scan.md');
+    return existsSync(scanPath);
+}

package/dist/services/session/session-resume-service.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `peaks session resume` — slice 011.
+ *
+ * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
+ * emits a structured markdown "resume context" block the skill can
+ * prepend to its own prompt. The output is LLM-friendly: stable
+ * headings, monospace paths, and bullet lists — easy for the model to
+ * scan and reason about.
+ */
+import { type CheckpointSnapshot } from './session-checkpoint-service.js';
+export interface ResumeOptions {
+    /** Absolute path to a checkpoint JSON file. */
+    checkpointPath: string;
+    /** Optional "now" reference for relative-time rendering. */
+    now?: () => Date;
+}
+export interface ResumeContext {
+    /** Stable markdown block, suitable for prepending to a skill prompt. */
+    markdown: string;
+    snapshot: CheckpointSnapshot;
+    sourcePath: string;
+    checkpointAgeMs: number | null;
+    relativeAgeLabel: string;
+}
+export declare function buildResumeContext(options: ResumeOptions): ResumeContext;

package/dist/services/session/session-resume-service.js

@@ -0,0 +1,101 @@
+/**
+ * `peaks session resume` — slice 011.
+ *
+ * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
+ * emits a structured markdown "resume context" block the skill can
+ * prepend to its own prompt. The output is LLM-friendly: stable
+ * headings, monospace paths, and bullet lists — easy for the model to
+ * scan and reason about.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, sep } from 'node:path';
+import { readCheckpoint } from './session-checkpoint-service.js';
+function toPosix(p) {
+    return p.split(sep).join('/');
+}
+function formatRelativeAge(ms) {
+    if (ms < 0)
+        return 'in the future';
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s ago`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.floor(hr / 24);
+    if (day < 30)
+        return `${day}d ago`;
+    const month = Math.floor(day / 30);
+    return `${month}mo ago`;
+}
+function renderSection(title, items) {
+    if (items.length === 0) {
+        return `### ${title}\n\n_(none)_\n`;
+    }
+    return `### ${title}\n\n${items.map((i) => `- ${i}`).join('\n')}\n`;
+}
+export function buildResumeContext(options) {
+    const path = options.checkpointPath;
+    if (!existsSync(path)) {
+        throw new Error(`RESUME_NOT_FOUND: checkpoint file not found: ${path}`);
+    }
+    try {
+        readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`RESUME_READ_FAILED: cannot read checkpoint: ${message}`);
+    }
+    const snapshot = readCheckpoint(path);
+    const now = (options.now ?? (() => new Date()))();
+    let ageMs = null;
+    let relativeAgeLabel = 'unknown age';
+    try {
+        const created = new Date(snapshot.createdAt);
+        if (!Number.isNaN(created.getTime())) {
+            ageMs = now.getTime() - created.getTime();
+            relativeAgeLabel = formatRelativeAge(ageMs);
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // leave defaults
+    }
+    const lines = [];
+    lines.push('## Resume context (from checkpoint)');
+    lines.push('');
+    lines.push(`- Source: \`${toPosix(path)}\``);
+    lines.push(`- Checkpoint basename: \`${basename(path)}\``);
+    lines.push(`- Session id: \`${snapshot.sessionId}\``);
+    lines.push(`- Captured at: \`${snapshot.createdAt}\``);
+    lines.push(`- Last session activity: \`${snapshot.lastActivity}\``);
+    lines.push(`- Reason: \`${snapshot.reason}\``);
+    lines.push(`- Relative age: **${relativeAgeLabel}**`);
+    lines.push('');
+    lines.push('### Current plan');
+    lines.push('');
+    lines.push(snapshot.currentPlan.trim().length > 0 ? snapshot.currentPlan : '_(none)_');
+    lines.push('');
+    lines.push(renderSection('Open questions', snapshot.openQuestions));
+    lines.push(renderSection('Recent decisions', snapshot.recentDecisions));
+    lines.push(renderSection('Recent artifact paths', snapshot.recentArtifactPaths));
+    lines.push(renderSection('Todo state', snapshot.todoState));
+    lines.push(renderSection('Active skills', snapshot.skillsActive));
+    if (snapshot.gitStatus.trim().length > 0) {
+        lines.push('### Git status');
+        lines.push('');
+        lines.push('```');
+        lines.push(snapshot.gitStatus.trim());
+        lines.push('```');
+        lines.push('');
+    }
+    return {
+        markdown: lines.join('\n'),
+        snapshot,
+        sourcePath: toPosix(path),
+        checkpointAgeMs: ageMs,
+        relativeAgeLabel
+    };
+}