@tyroneross/bookmark 0.2.0 → 0.3.2

package/dist/registry.js

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+const REGISTRY_VERSION = '1.0.0';
+const MAX_ENTRIES = 500;
+/**
+ * Resolve a human-readable project name from a directory path.
+ *
+ * Resolution order:
+ * 1. package.json "name" field in cwd
+ * 2. basename of git repo root (walk up until .git is found)
+ * 3. basename of cwd — unless it's the home directory
+ * 4. Fallback: basename(cwd) regardless
+ */
+export function resolveProjectName(cwd) {
+    const home = homedir();
+    // 1. package.json name
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.name && pkg.name.trim()) {
+                // Strip scoped package prefix (@scope/name → name)
+                return pkg.name.replace(/^@[^/]+\//, '').trim();
+            }
+        }
+        catch {
+            // Fall through
+        }
+    }
+    // 2. Walk up looking for .git directory
+    let dir = cwd;
+    const root = dirname(home); // Stop before going above home's parent
+    while (dir && dir !== root && dir !== dirname(dir)) {
+        if (existsSync(join(dir, '.git'))) {
+            return basename(dir);
+        }
+        dir = dirname(dir);
+    }
+    // 3. Avoid returning home dir basename as the name
+    const cwdBase = basename(cwd);
+    if (cwd === home || cwdBase === basename(home)) {
+        return 'home';
+    }
+    return cwdBase;
+}
+export function getRegistryPath() {
+    return join(homedir(), '.bookmark', 'registry.json');
+}
+function ensureRegistryDir() {
+    const dir = join(homedir(), '.bookmark');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+export function loadRegistry() {
+    const path = getRegistryPath();
+    if (!existsSync(path)) {
+        return { version: REGISTRY_VERSION, last_updated: 0, snapshots: [] };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed.snapshots)
+            parsed.snapshots = [];
+        return parsed;
+    }
+    catch {
+        return { version: REGISTRY_VERSION, last_updated: 0, snapshots: [] };
+    }
+}
+function saveRegistry(registry) {
+    ensureRegistryDir();
+    registry.last_updated = Date.now();
+    writeFileSync(getRegistryPath(), JSON.stringify(registry, null, 2), 'utf-8');
+}
+export function appendToRegistry(snapshot, canonicalFile) {
+    try {
+        const registry = loadRegistry();
+        const entry = {
+            id: snapshot.snapshot_id,
+            timestamp: snapshot.timestamp,
+            trigger: snapshot.trigger,
+            project_path: snapshot.project_path,
+            project_name: resolveProjectName(snapshot.project_path),
+            canonical_file: canonicalFile,
+            files_changed_count: snapshot.files_changed.length,
+        };
+        // Dedupe by id, newest wins
+        registry.snapshots = [entry, ...registry.snapshots.filter(e => e.id !== entry.id)];
+        if (registry.snapshots.length > MAX_ENTRIES) {
+            registry.snapshots.length = MAX_ENTRIES;
+        }
+        registry.last_project = {
+            path: snapshot.project_path,
+            name: entry.project_name,
+            last_activity_at: snapshot.timestamp,
+        };
+        saveRegistry(registry);
+    }
+    catch {
+        // Never break capture for registry bookkeeping
+    }
+}
+export function touchLastProject(projectPath) {
+    try {
+        const registry = loadRegistry();
+        registry.last_project = {
+            path: projectPath,
+            name: resolveProjectName(projectPath),
+            last_activity_at: Date.now(),
+        };
+        saveRegistry(registry);
+    }
+    catch {
+        // Silent — never break restore for bookkeeping
+    }
+}
+export function findById(id) {
+    const registry = loadRegistry();
+    return registry.snapshots.find(e => e.id === id) ?? null;
+}
+export function getLastProject() {
+    return loadRegistry().last_project ?? null;
+}
+/** Prune entries whose canonical_file is missing. Lazy cleanup on read paths. */
+export function pruneStale() {
+    const registry = loadRegistry();
+    const live = registry.snapshots.filter(e => existsSync(e.canonical_file));
+    if (live.length !== registry.snapshots.length) {
+        registry.snapshots = live;
+        saveRegistry(registry);
+    }
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/restore/index.d.ts

@@ -7,7 +7,19 @@ export interface RestoreOptions {
 }
 /**
  * Generate restoration context for a SessionStart hook.
- * Returns a HookOutput with systemMessage containing the LATEST.md content.
+ *
+ * v0.4 adds:
+ *  1. BOOKMARK_IDENTITY parsing + repo_path validation
+ *  2. Home-scope pointer delegation to a canonical repo bookmark
+ *  3. Hard staleness block at 72h (instead of soft warning only)
+ *
+ * Cascade:
+ *  1. bookmark.context.md — if present and useful
+ *     1a. If identity scope=home + points_to_canonical, follow the pointer
+ *     1b. If identity scope=repo and path mismatch, prefix a warning
+ *     1c. If age >= STALENESS_HARD_BLOCK_HOURS, return staleness block
+ *  2. LATEST.md — file tracking fallback
+ *  3. Empty
  */
 export declare function restoreContext(options: RestoreOptions): HookOutput;
 //# sourceMappingURL=index.d.ts.map

package/dist/restore/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/restore/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAA6D,MAAM,aAAa,CAAC;AAEzG,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,UAAU,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CAoElE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/restore/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,UAAU,CAAC;CACjD;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CAqFlE"}

package/dist/restore/index.js

@@ -1,279 +1,180 @@
-import { existsSync } from 'node:fs';
-import { readLatestMd, loadLatestSnapshot, getSnapshotCount, loadSnapshotChain } from '../snapshot/storage.js';
+import { existsSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLatestMd, getSnapshotCount } from '../snapshot/storage.js';
 import { readContextMd } from '../trails/reader.js';
+import { parseIdentity, validateRepoIdentity, followPointer, } from '../trails/identity.js';
 import { loadState, saveState, resetForNewSession, incrementCompaction } from '../threshold/state.js';
 import { loadConfig, getStoragePath } from '../config.js';
+import { touchLastProject } from '../registry.js';
+/**
+ * Hours after which a bookmark is considered too stale to auto-restore.
+ * Below this threshold: restore with a soft warning.
+ * At or above: hard-block — return an empty context with guidance instead
+ * of risking a confident wrong start from stale content.
+ */
+const STALENESS_HARD_BLOCK_HOURS = 72;
+const STALENESS_SOFT_WARN_HOURS = 24;
 /**
  * Generate restoration context for a SessionStart hook.
- * Returns a HookOutput with systemMessage containing the LATEST.md content.
+ *
+ * v0.4 adds:
+ *  1. BOOKMARK_IDENTITY parsing + repo_path validation
+ *  2. Home-scope pointer delegation to a canonical repo bookmark
+ *  3. Hard staleness block at 72h (instead of soft warning only)
+ *
+ * Cascade:
+ *  1. bookmark.context.md — if present and useful
+ *     1a. If identity scope=home + points_to_canonical, follow the pointer
+ *     1b. If identity scope=repo and path mismatch, prefix a warning
+ *     1c. If age >= STALENESS_HARD_BLOCK_HOURS, return staleness block
+ *  2. LATEST.md — file tracking fallback
+ *  3. Empty
  */
 export function restoreContext(options) {
     const config = loadConfig(options.cwd);
     const storagePath = getStoragePath(options.cwd, config);
     const state = loadState(storagePath);
-    // Handle session state transitions
     handleSessionTransition(storagePath, state, options, config.thresholds);
-    // Check if restoration is needed
-    if (!config.restoreOnSessionStart) {
-        return {};
+    const stopRequestedPath = join(storagePath, '.stop-requested');
+    if (existsSync(stopRequestedPath)) {
+        try {
+            unlinkSync(stopRequestedPath);
+        }
+        catch { /* ignore */ }
     }
-    // On resume, context is likely intact — skip restoration
-    if (options.source === 'resume') {
+    if (!config.restoreOnSessionStart)
         return {};
-    }
-    // Check for existing snapshots
-    const snapshotCount = getSnapshotCount(storagePath);
-    if (snapshotCount === 0) {
-        // First run — tell Claude that bookmark is active
-        return {
-            systemMessage: '[Bookmark: Active — no snapshots yet. Snapshots will be captured automatically ' +
-                'before compaction, on 20-minute intervals, and at session end.]\n\n' +
-                'Briefly let the user know that Bookmark is active and will start capturing context snapshots automatically.',
-        };
-    }
-    // Read LATEST.md
-    const latestMd = readLatestMd(storagePath);
-    if (!latestMd) {
+    if (options.source === 'resume')
         return {};
-    }
-    if (options.format === 'json') {
-        const snapshot = loadLatestSnapshot(storagePath);
-        return {
-            systemMessage: JSON.stringify(snapshot, null, 2),
-        };
-    }
-    if (options.format === 'markdown') {
-        return {
-            systemMessage: latestMd,
-        };
-    }
-    // Default: system_message format — structured for fast LLM pickup
-    // Prefer trail-routed CONTEXT.md (compact trailhead with routing pointers)
-    const contextMd = readContextMd(storagePath);
-    if (contextMd) {
-        return { systemMessage: contextMd };
-    }
-    // Fallback: chain-aware restoration from raw snapshots
-    const chain = loadSnapshotChain(storagePath);
-    if (chain.length > 1) {
-        const merged = mergeSnapshotChain(chain);
-        return { systemMessage: buildChainRestoration(merged, chain.length, snapshotCount) };
-    }
-    const snapshot = loadLatestSnapshot(storagePath);
-    const systemMessage = snapshot
-        ? buildSmartRestoration(snapshot, snapshotCount)
-        : buildFallbackRestoration(latestMd, snapshotCount);
-    return { systemMessage };
-}
-/**
- * Merge a chain of snapshots into one unified context.
- * Chain is in chronological order (oldest first).
- *
- * Strategy:
- * - Intent/progress: Latest non-Unknown wins (most current)
- * - Files: Union by path, merge operations, sum line counts
- * - Decisions: Accumulate unique across chain, cap at 6
- * - Open items: Latest snapshot only (prior items are done or superseded)
- * - Sentiment: Latest non-neutral wins
- */
-function mergeSnapshotChain(chain) {
-    const latest = chain[chain.length - 1];
-    const oldest = chain[0];
-    // Intent/progress: walk backward, take first non-Unknown
-    let intent = 'Unknown';
-    let progress = 'Unknown';
-    let sentiment = 'neutral';
-    for (let i = chain.length - 1; i >= 0; i--) {
-        if (intent === 'Unknown' && chain[i].intent && chain[i].intent !== 'Unknown') {
-            intent = chain[i].intent;
-        }
-        if (progress === 'Unknown' && chain[i].progress && chain[i].progress !== 'Unknown') {
-            progress = chain[i].progress;
-        }
-        if (sentiment === 'neutral' && chain[i].user_sentiment && chain[i].user_sentiment !== 'neutral') {
-            sentiment = chain[i].user_sentiment;
-        }
-    }
-    // Files: merge by path across all snapshots
-    const fileMap = new Map();
-    for (const snap of chain) {
-        for (const f of snap.files_changed) {
-            const existing = fileMap.get(f.path);
-            if (existing) {
-                // Merge operations (union)
-                const ops = new Set([...existing.operations, ...f.operations]);
-                existing.operations = [...ops];
-                // Sum line counts
-                existing.lines_changed = (existing.lines_changed ?? 0) + (f.lines_changed ?? 0);
-            }
-            else {
-                fileMap.set(f.path, { ...f });
+    // Primary: bookmark.context.md with identity-aware handling
+    const rawContextMd = readContextMd(storagePath);
+    if (rawContextMd && isContextMdUseful(rawContextMd)) {
+        const contextPath = join(storagePath, 'bookmark.context.md');
+        const { identity, bodyWithoutIdentity } = parseIdentity(rawContextMd);
+        // 1a. Home-scope pointer? Follow it to the canonical repo bookmark.
+        if (identity?.scope === 'home') {
+            const target = followPointer(identity);
+            if (target) {
+                const targetAge = target.staleness_hours ?? 0;
+                if (targetAge >= STALENESS_HARD_BLOCK_HOURS) {
+                    trackRestore(storagePath, 0);
+                    return { systemMessage: buildHardStalenessMessage(target.canonical_path, targetAge) };
+                }
+                // Strip identity block from target content for cleaner display
+                const { bodyWithoutIdentity: targetBody } = parseIdentity(target.content);
+                const header = buildPointerFollowHeader(identity, target.canonical_path, targetAge);
+                const message = `${header}\n\n${targetBody}`;
+                trackRestore(storagePath, message.length);
+                if (identity.points_to_canonical) {
+                    touchLastProject(derivProjectFromCanonical(identity.points_to_canonical));
+                }
+                return { systemMessage: message };
             }
+            // Pointer target missing — fall through to present the pointer body itself
         }
-    }
-    // Decisions: accumulate unique across chain
-    const decisionSet = new Set();
-    const allDecisions = [];
-    for (const snap of chain) {
-        for (const d of snap.decisions) {
-            // Deduplicate by normalized prefix (first 60 chars, lowered)
-            const key = d.description.slice(0, 60).toLowerCase().trim();
-            if (!decisionSet.has(key)) {
-                decisionSet.add(key);
-                allDecisions.push(d);
-            }
+        // 1c. Hard staleness block
+        const ageHours = getAgeHours(contextPath);
+        if (ageHours !== null && ageHours >= STALENESS_HARD_BLOCK_HOURS) {
+            trackRestore(storagePath, 0);
+            return { systemMessage: buildHardStalenessMessage(contextPath, ageHours) };
         }
-    }
-    // Open items: latest snapshot only
-    const openItems = latest.open_items;
-    const files = [...fileMap.values()];
-    const totalLinesChanged = files.reduce((sum, f) => sum + (f.lines_changed ?? 0), 0);
-    return {
-        intent,
-        progress,
-        sentiment,
-        files,
-        decisions: allDecisions.slice(0, 6),
-        openItems,
-        projectPath: latest.project_path,
-        compactionCycle: latest.compaction_cycle,
-        totalLinesChanged,
-        chainSpan: { oldest: oldest.timestamp, newest: latest.timestamp },
-    };
+        // 1b. Path-mismatch warning for repo-scoped identities
+        const mismatchWarning = identity ? validateRepoIdentity(identity, options.cwd) : null;
+        // Soft staleness warning
+        const softWarning = ageHours !== null && ageHours >= STALENESS_SOFT_WARN_HOURS
+            ? `[Note: This bookmark context is ${ageHours}h old and may be outdated.]`
+            : null;
+        const prefixes = [mismatchWarning, softWarning].filter(Boolean).join('\n\n');
+        const message = prefixes ? `${prefixes}\n\n${bodyWithoutIdentity}` : bodyWithoutIdentity;
+        trackRestore(storagePath, message.length);
+        touchLastProject(options.cwd);
+        return { systemMessage: message };
+    }
+    if (rawContextMd) {
+        trackBoilerplateCaught(storagePath);
+    }
+    // Fallback: LATEST.md
+    const snapshotCount = getSnapshotCount(storagePath);
+    const latestMd = readLatestMd(storagePath);
+    if (latestMd) {
+        const message = buildFallbackRestoration(latestMd, snapshotCount);
+        trackRestore(storagePath, message.length);
+        touchLastProject(options.cwd);
+        return { systemMessage: message };
+    }
+    // No local bookmark and no LATEST.md — stay silent rather than inject
+    // another repo's context. The home-scope pointer at ~/.bookmark/bookmark.context.md
+    // is the supported way to redirect from an empty CWD to a canonical project.
+    return {};
 }
-/**
- * Build restoration from merged chain context.
- * Target: <600 tokens — covers multiple compaction cycles efficiently.
- */
-function buildChainRestoration(merged, chainLength, snapshotCount) {
-    const lines = [];
-    const spanMinutes = Math.round((merged.chainSpan.newest - merged.chainSpan.oldest) / 60000);
-    const spanStr = spanMinutes > 60
-        ? `${Math.round(spanMinutes / 60)}h ${spanMinutes % 60}m`
-        : `${spanMinutes}m`;
-    lines.push(`[Bookmark: Context recovered — ${chainLength} snapshots merged across ${spanStr}]`);
-    lines.push('');
-    // Intent
-    if (merged.intent !== 'Unknown') {
-        lines.push(`**User intent:** ${merged.intent}`);
-    }
-    // Progress
-    if (merged.progress !== 'Unknown') {
-        lines.push(`**Progress:** ${merged.progress}`);
-    }
-    // Sentiment
-    if (merged.sentiment !== 'neutral') {
-        lines.push(`**User feedback:** ${merged.sentiment}`);
-    }
-    lines.push('');
-    // Files — show cumulative work
-    if (merged.files.length > 0) {
-        lines.push(`**Files modified:** ${merged.files.length} files (~${merged.totalLinesChanged} lines total)`);
-        // Sort by lines changed descending — most important files first
-        const sorted = [...merged.files].sort((a, b) => (b.lines_changed ?? 0) - (a.lines_changed ?? 0));
-        for (const f of sorted.slice(0, 10)) {
-            const shortPath = f.path.includes(merged.projectPath)
-                ? f.path.slice(merged.projectPath.length).replace(/^\//, '')
-                : f.path;
-            const lc = f.lines_changed ? ` ~${f.lines_changed}L` : '';
-            lines.push(`- \`${shortPath}\` (${f.operations.join('/')}${lc})`);
-        }
-        if (merged.files.length > 10) {
-            lines.push(`- ...+${merged.files.length - 10} more`);
-        }
-        lines.push('');
-    }
-    // Decisions — accumulated across chain
-    if (merged.decisions.length > 0) {
-        lines.push('**Key decisions (across session):**');
-        for (const d of merged.decisions) {
-            lines.push(`- ${d.description.slice(0, 120)}`);
-        }
-        lines.push('');
-    }
-    // Open items — from latest snapshot only
-    if (merged.openItems.length > 0) {
-        lines.push('**Remaining:**');
-        for (const item of merged.openItems.slice(0, 4)) {
-            lines.push(`- ${item.description.slice(0, 120)}`);
-        }
-        lines.push('');
-    }
-    // Chain metadata
-    if (merged.compactionCycle > 0) {
-        lines.push(`> Compaction cycle ${merged.compactionCycle} — context compressed ${merged.compactionCycle} time(s), this merges all recovered state.`);
-    }
-    if (snapshotCount > chainLength) {
-        lines.push(`> ${snapshotCount} total snapshots. \`/bookmark:list\` for full history.`);
-    }
-    lines.push('');
-    lines.push('Resume working on the task above. Do not re-read files you already modified unless the user asks.');
-    return lines.join('\n');
+/** Derive the project path from a canonical bookmark.context.md path. */
+function derivProjectFromCanonical(canonicalPath) {
+    // .../<project>/.bookmark/bookmark.context.md → <project>
+    const marker = `/.bookmark/`;
+    const idx = canonicalPath.lastIndexOf(marker);
+    return idx > 0 ? canonicalPath.slice(0, idx) : canonicalPath;
 }
-// ─── Single Snapshot Restoration ───
-/**
- * Build a restoration message optimized for LLM context recovery.
- * Structured as a briefing: intent → progress → what changed → what's next.
- * Target: <500 tokens — every token here saves 10+ tokens of re-exploration.
- */
-function buildSmartRestoration(snapshot, snapshotCount) {
-    const lines = [];
-    lines.push('[Bookmark: Context recovered — pick up where you left off]');
-    lines.push('');
-    // Intent — what the user is trying to do
-    if (snapshot.intent && snapshot.intent !== 'Unknown') {
-        lines.push(`**User intent:** ${snapshot.intent}`);
-    }
-    // Progress — how far along
-    if (snapshot.progress && snapshot.progress !== 'Unknown') {
-        lines.push(`**Progress:** ${snapshot.progress}`);
-    }
-    // Sentiment — user's reaction to work so far
-    if (snapshot.user_sentiment && snapshot.user_sentiment !== 'neutral') {
-        lines.push(`**User feedback:** ${snapshot.user_sentiment}`);
-    }
-    lines.push('');
-    // Files changed — concrete work done
-    if (snapshot.files_changed.length > 0) {
-        const totalLines = snapshot.files_changed.reduce((sum, f) => sum + (f.lines_changed ?? 0), 0);
-        lines.push(`**Files modified:** ${snapshot.files_changed.length} files (~${totalLines} lines)`);
-        for (const f of snapshot.files_changed.slice(0, 8)) {
-            const shortPath = f.path.includes(snapshot.project_path)
-                ? f.path.slice(snapshot.project_path.length).replace(/^\//, '')
-                : f.path;
-            const lc = f.lines_changed ? ` ~${f.lines_changed}L` : '';
-            lines.push(`- \`${shortPath}\` (${f.operations.join('/')}${lc})`);
-        }
-        if (snapshot.files_changed.length > 8) {
-            lines.push(`- ...+${snapshot.files_changed.length - 8} more`);
-        }
-        lines.push('');
-    }
-    // Key decisions — only if LLM-extracted (high quality)
-    if (snapshot.decisions.length > 0) {
-        lines.push('**Key decisions:**');
-        for (const d of snapshot.decisions.slice(0, 4)) {
-            lines.push(`- ${d.description.slice(0, 120)}`);
-        }
-        lines.push('');
+/** Record a successful restore — chars injected / 4 ≈ tokens */
+function trackRestore(storagePath, charCount) {
+    try {
+        const state = loadState(storagePath);
+        state.restores_performed = (state.restores_performed ?? 0) + 1;
+        state.tokens_injected = (state.tokens_injected ?? 0) + Math.round(charCount / 4);
+        saveState(storagePath, state);
+    }
+    catch { /* never break restore for tracking */ }
+}
+function trackBoilerplateCaught(storagePath) {
+    try {
+        const state = loadState(storagePath);
+        state.boilerplate_caught = (state.boilerplate_caught ?? 0) + 1;
+        saveState(storagePath, state);
     }
-    // Open items — what's left
-    if (snapshot.open_items.length > 0) {
-        lines.push('**Remaining:**');
-        for (const item of snapshot.open_items.slice(0, 4)) {
-            lines.push(`- ${item.description.slice(0, 120)}`);
-        }
-        lines.push('');
+    catch { /* never break restore for tracking */ }
+}
+function isContextMdUseful(content) {
+    if (content.length < 200)
+        return false;
+    if (content.startsWith('[Bookmark Context') && !content.includes('## '))
+        return false;
+    const markers = ['## ', '**Task', '**Status', '**Progress', 'done', 'remaining', '- '];
+    return markers.some(m => content.includes(m));
+}
+function getAgeHours(path) {
+    try {
+        const mtime = statSync(path).mtimeMs;
+        return Math.round((Date.now() - mtime) / (1000 * 60 * 60));
     }
-    // Compaction chain info
-    if (snapshot.compaction_cycle > 0) {
-        lines.push(`> Compaction cycle ${snapshot.compaction_cycle} — context was compressed, this is the recovered state.`);
+    catch {
+        return null;
     }
-    if (snapshotCount > 1) {
-        lines.push(`> ${snapshotCount} snapshots in history. \`/bookmark:list\` for full chain.`);
+}
+function buildHardStalenessMessage(path, ageHours) {
+    return [
+        `[Bookmark: auto-restore BLOCKED — source is ${ageHours}h stale (threshold ${STALENESS_HARD_BLOCK_HOURS}h).]`,
+        '',
+        `The bookmark file at ${path} is too old to treat as current context.`,
+        'Stale auto-restore creates confident wrong starts — worse than no restore at all.',
+        '',
+        'To proceed, either:',
+        '- Run `/bookmark:list` and pick a specific snapshot explicitly',
+        '- Read the stale file manually if you still want its content: ' +
+            `\`cat "${path}"\``,
+        '- Ask the user what they were working on most recently',
+    ].join('\n');
+}
+function buildPointerFollowHeader(pointer, canonicalPath, ageHours) {
+    const lines = [
+        `[Bookmark: followed home-scope pointer → repo-scope bookmark]`,
+        '',
+        `Canonical file: ${canonicalPath}`,
+    ];
+    if (pointer.points_to_project) {
+        lines.push(`Project: ${pointer.points_to_project}`);
+    }
+    if (ageHours >= STALENESS_SOFT_WARN_HOURS) {
+        lines.push(`Age: ${ageHours}h (approaching staleness threshold of ${STALENESS_HARD_BLOCK_HOURS}h)`);
     }
-    lines.push('');
-    lines.push('Resume working on the task above. Do not re-read files you already modified unless the user asks.');
     return lines.join('\n');
 }
 function buildFallbackRestoration(latestMd, snapshotCount) {
@@ -294,16 +195,13 @@ function handleSessionTransition(storagePath, state, options, thresholds) {
     switch (source) {
         case 'startup':
         case 'clear':
-            // New session — reset compaction count
             updatedState = resetForNewSession(state, sessionId, thresholds);
             break;
         case 'compact':
-            // After compaction — increment compaction count
             updatedState = incrementCompaction(state, thresholds);
             updatedState.session_id = sessionId;
             break;
         case 'resume':
-            // Resuming — keep state, just update session ID if different
             updatedState = { ...state, session_id: sessionId, last_event_time: Date.now() };
             break;
         default: