fluffy-context 0.2.0 → 0.3.1

package/dist/src/cli/main.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { checkpoint, resume } from '../runtime/runtime.js';
+import { contextOrient } from '../agent/api.js';
+import { runClaudeCodeHook } from '../hooks/claude-code.js';
+import { inspectClaudeIntegration, installClaudeIntegration } from '../integrations/claude-code.js';
 import { doctor, status } from '../runtime/diagnostics.js';
 import { initProject } from '../runtime/init.js';
 import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend } from '../runtime/knowledge.js';
@@ -93,6 +96,46 @@ Options:
   --path <path>          Project path
   --context <id>         Context ID
   --max-chars <number>   Maximum summary characters`,
+    orient: `usage: ctx orient [query] [options]
+
+Prepare bounded task context from the current work, verified consensus, matching deadends, and open notes.
+
+Options:
+  --path <path>              Project path
+  --context <id>             Context ID
+  --scope <scope>            Exact consensus scope
+  --max-chars <number>       Maximum display characters
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)`,
+    agent: `usage: ctx agent serve
+
+Start an MCP stdio server for Agent integrations.
+
+Run "ctx agent serve --help" for details.`,
+    'agent serve': `usage: ctx agent serve
+
+Start an MCP stdio server exposing the context_orient tool.
+
+The server owns standard input/output; do not use it interactively.`,
+    hook: `usage: ctx hook claude-code session-start|user-prompt
+
+Run a Claude Code lifecycle hook. This command reads Hook JSON from standard input.`,
+    'hook claude-code': `usage: ctx hook claude-code session-start|user-prompt
+
+Emit best-effort, read-only phased Context guidance for Claude Code.`,
+    integrate: `usage: ctx integrate claude inspect|install [--path <path>] [--apply]
+
+Inspect or explicitly install project-local Claude Code hooks and MCP configuration.`,
+    'integrate claude': `usage: ctx integrate claude inspect|install [--path <path>] [--apply]
+
+Inspect configuration, or preview/install project-local Claude Code integration.`,
+    'integrate claude inspect': `usage: ctx integrate claude inspect [--path <path>]
+
+Report whether the project has the Claude Code hooks and MCP server configured.`,
+    'integrate claude install': `usage: ctx integrate claude install [--path <path>] [--apply]
+
+Preview configuration changes by default. Pass --apply to merge project-local .claude/settings.json and .mcp.json.`,
     status: `usage: ctx status [--path <path>]
 
 Show the initialized project and context index.`,
@@ -194,21 +237,28 @@ Options:
   --max-chars <number>   Maximum message characters`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|status|doctor|learn|knowledge|deadend|deadends|note|activity [options]
+    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
 function print(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+async function stdin() {
+    let value = '';
+    for await (const chunk of process.stdin)
+        value += chunk.toString();
+    return value;
+}
 function printHelp(args) {
     const command = args[0];
     if (!command) {
         process.stdout.write(`${usage()}\n`);
         return true;
     }
-    const key = args[1] === 'verify' || args[1] === 'add' || args[1] === 'list' || args[1] === 'discover' ? `${command} ${args[1]}` : command;
-    const help = HELP[key];
+    const key = args[1] === 'verify' || args[1] === 'add' || args[1] === 'list' || args[1] === 'discover' || args[1] === 'serve' || args[1] === 'claude' ? `${command} ${args[1]}` : command;
+    const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
+    const help = HELP[nestedKey];
     if (!help)
         return false;
     if (args.includes('--help')) {
@@ -265,6 +315,50 @@ async function run(args) {
             validatePositionals(positionals(args.slice(1), ['--path', '--context', '--max-chars']), 0, HELP.resume);
             print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
             return;
+        case 'orient': {
+            const valueOptions = ['--path', '--context', '--scope', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            const query = positionals(args.slice(1), valueOptions);
+            validatePositionals(query, 1, HELP.orient);
+            print(await contextOrient(target, {
+                contextId: option(args, '--context'),
+                query: query[0],
+                scope: option(args, '--scope'),
+                maxChars: numericOption(args, '--max-chars', 4000),
+                knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                deadendLimit: numericOption(args, '--deadend-limit', 10),
+                noteLimit: numericOption(args, '--note-limit', 20),
+            }));
+            return;
+        }
+        case 'agent':
+            if (args[1] !== 'serve')
+                throw new Error(HELP.agent);
+            validateOptions(args.slice(2), [], []);
+            validatePositionals(positionals(args.slice(2), []), 0, HELP['agent serve']);
+            await import('../mcp/main.js');
+            return;
+        case 'hook': {
+            if (args[1] !== 'claude-code' || !['session-start', 'user-prompt'].includes(args[2]))
+                throw new Error(HELP['hook claude-code']);
+            validateOptions(args.slice(3), [], []);
+            validatePositionals(positionals(args.slice(3), []), 0, HELP['hook claude-code']);
+            process.stdout.write(await runClaudeCodeHook(args[2], await stdin()));
+            return;
+        }
+        case 'integrate': {
+            if (args[1] !== 'claude' || !['inspect', 'install'].includes(args[2]))
+                throw new Error(HELP['integrate claude']);
+            const valueOptions = ['--path'];
+            const allowed = args[2] === 'install' ? [...valueOptions, '--apply'] : valueOptions;
+            validateOptions(args.slice(3), allowed, valueOptions);
+            validatePositionals(positionals(args.slice(3), valueOptions), 0, HELP[`integrate claude ${args[2]}`]);
+            if (args[2] === 'inspect')
+                print(await inspectClaudeIntegration(target));
+            else
+                print(await installClaudeIntegration(target, args.includes('--apply')));
+            return;
+        }
         case 'status':
             validateOptions(args.slice(1), ['--path'], ['--path']);
             validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.status);

package/dist/src/git/git-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { GitState } from '../runtime/types.js';
+export declare function readGitState(projectRoot: string): Promise<GitState>;

package/dist/src/hooks/claude-code.d.ts

@@ -0,0 +1 @@
+export declare function runClaudeCodeHook(event: 'session-start' | 'user-prompt', raw: string): Promise<string>;

package/dist/src/hooks/claude-code.js

@@ -0,0 +1,84 @@
+import { contextOrient } from '../agent/api.js';
+const HOOK_RESPONSE = '{}\n';
+function text(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function compact(value, maxChars) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= maxChars ? normalized : `${normalized.slice(0, maxChars - 1)}…`;
+}
+function lines(label, values, limit) {
+    return values.slice(0, limit).map((value) => `- ${label}: ${compact(value, 240)}`);
+}
+function readyContext(result) {
+    const content = [
+        `当前 Context：${compact(result.context.title, 160)}`,
+        `进度：${compact(result.resumeSummary.progressSummary, 360)}`,
+        ...lines('待办', result.resumeSummary.pendingTasks, 4),
+        ...lines('决策', result.resumeSummary.decisions, 3),
+        ...lines('风险', result.resumeSummary.risks, 3),
+        ...result.knowledge.hits.slice(0, 5).map((hit) => `- 已验证知识：${compact(hit.knowledge.statement, 240)}`),
+        ...result.deadends.hits.slice(0, 3).map((hit) => `- 已验证死路（避免）：${compact(hit.deadend.attempt, 180)}；${compact(hit.deadend.reason, 180)}`),
+        ...result.notes.slice(0, 8).map((note) => `- 开放 Note：${compact(note.message, 220)}`),
+    ];
+    if (result.truncated)
+        content.push('- 上下文已按预算截断；需要时使用 context_orient 或 ctx orient 进一步查询。');
+    return content;
+}
+function sessionContext(result) {
+    const phases = [
+        '开发阶段：Orient → Plan → Implement → Verify → Handoff。',
+        '先基于以下上下文明确计划；实现中记录重要观察/决策/阻塞为 ctx note；验证后显式 ctx checkpoint，总结完成、待办、决策和风险。不要自动保存 Snapshot。',
+    ];
+    if (result.status === 'no_context') {
+        phases.push('当前没有可恢复的 Context。开始有意义的工作后，使用 ctx checkpoint 创建一个。');
+    }
+    else {
+        phases.push(...readyContext(result));
+    }
+    return phases.join('\n');
+}
+function promptContext(result) {
+    const phases = [
+        '开发阶段：Implement → Verify → Handoff。',
+        '实现时用 ctx note 记录重要观察、决策或阻塞；完成后运行适用的验证。阶段结束时显式 ctx checkpoint（可 --absorb-notes），不要由 Hook 自动保存。',
+    ];
+    if (result.status === 'no_context') {
+        phases.push('当前没有可恢复的 Context；如果这项工作会继续，先建立 checkpoint。');
+    }
+    else {
+        phases.push(...readyContext(result));
+    }
+    return phases.join('\n');
+}
+async function parseInput(raw) {
+    try {
+        const value = JSON.parse(raw);
+        return value !== null && typeof value === 'object' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runClaudeCodeHook(event, raw) {
+    const input = await parseInput(raw);
+    if (!input)
+        return HOOK_RESPONSE;
+    try {
+        const cwd = text(input.cwd);
+        const result = event === 'session-start'
+            ? await contextOrient(cwd, { maxChars: 1200, noteLimit: 8 })
+            : await contextOrient(cwd, {
+                query: compact(text(input.prompt) ?? '', 500) || undefined,
+                maxChars: 1800,
+                knowledgeLimit: 5,
+                deadendLimit: 3,
+                noteLimit: 8,
+            });
+        const additionalContext = event === 'session-start' ? sessionContext(result) : promptContext(result);
+        return `${JSON.stringify({ additionalContext })}\n`;
+    }
+    catch {
+        return HOOK_RESPONSE;
+    }
+}

package/dist/src/integrations/claude-code.d.ts

@@ -0,0 +1,19 @@
+export interface ClaudeIntegrationStatus {
+    projectRoot: string;
+    initialized: boolean;
+    settingsPath: string;
+    mcpPath: string;
+    settingsExists: boolean;
+    mcpExists: boolean;
+    sessionStartInstalled: boolean;
+    userPromptInstalled: boolean;
+    mcpInstalled: boolean;
+    mcpConflict: boolean;
+    installationNeeded: boolean;
+}
+export interface ClaudeIntegrationInstallResult extends ClaudeIntegrationStatus {
+    applied: boolean;
+    targetFiles: string[];
+}
+export declare function inspectClaudeIntegration(startPath: string | undefined): Promise<ClaudeIntegrationStatus>;
+export declare function installClaudeIntegration(startPath: string | undefined, apply: boolean): Promise<ClaudeIntegrationInstallResult>;

package/dist/src/integrations/claude-code.js

@@ -0,0 +1,145 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { isRecord, readJson } from '../storage/json-store.js';
+import { manifestPath } from '../storage/layout.js';
+const cliPath = fileURLToPath(new URL('../cli/main.js', import.meta.url));
+const cliCommand = `"${process.execPath}" "${cliPath}"`;
+const HOOK_COMMANDS = {
+    sessionStart: `${cliCommand} hook claude-code session-start`,
+    userPrompt: `${cliCommand} hook claude-code user-prompt`,
+};
+const LEGACY_HOOK_COMMANDS = {
+    sessionStart: 'ctx hook claude-code session-start',
+    userPrompt: 'ctx hook claude-code user-prompt',
+};
+const MCP_SERVER = { command: process.execPath, args: [cliPath, 'agent', 'serve'] };
+const LEGACY_MCP_SERVER = { command: 'ctx', args: ['agent', 'serve'] };
+function object(value) {
+    return isRecord(value) ? { ...value } : {};
+}
+function hookInstalled(value, command) {
+    if (!Array.isArray(value))
+        return false;
+    return value.some((group) => isRecord(group)
+        && Array.isArray(group.hooks)
+        && group.hooks.some((hook) => isRecord(hook) && hook.type === 'command' && hook.command === command));
+}
+function addHook(value, command, legacyCommand) {
+    const groups = Array.isArray(value) ? value.filter(isRecord).map((group) => ({ ...group })) : [];
+    if (hookInstalled(groups, command))
+        return groups;
+    let replaced = false;
+    const updated = groups.map((group) => ({
+        ...group,
+        hooks: Array.isArray(group.hooks)
+            ? group.hooks.map((hook) => {
+                if (!isRecord(hook) || hook.type !== 'command' || hook.command !== legacyCommand)
+                    return hook;
+                replaced = true;
+                return { ...hook, command };
+            })
+            : group.hooks,
+    }));
+    return replaced ? updated : [...updated, { hooks: [{ type: 'command', command }] }];
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadObject(filePath) {
+    if (!await exists(filePath))
+        return {};
+    return readJson(filePath, isRecord);
+}
+function validateConfig(settings, mcp) {
+    if (settings.hooks !== undefined && !isRecord(settings.hooks))
+        throw new Error('Claude Code settings hooks must be an object');
+    const hooks = object(settings.hooks);
+    for (const event of ['SessionStart', 'UserPromptSubmit']) {
+        if (hooks[event] !== undefined && !Array.isArray(hooks[event]))
+            throw new Error(`Claude Code ${event} hooks must be an array`);
+    }
+    if (mcp.mcpServers !== undefined && !isRecord(mcp.mcpServers))
+        throw new Error('Claude Code MCP servers must be an object');
+}
+function mcpInstalled(value, server = MCP_SERVER) {
+    return isRecord(value)
+        && value.command === server.command
+        && Array.isArray(value.args)
+        && value.args.length === server.args.length
+        && value.args.every((item, index) => item === server.args[index]);
+}
+function status(projectRoot, settingsPath, mcpPath, settings, mcp, settingsExists, mcpExists, initialized) {
+    const hooks = object(settings.hooks);
+    const sessionStartInstalled = hookInstalled(hooks.SessionStart, HOOK_COMMANDS.sessionStart);
+    const userPromptInstalled = hookInstalled(hooks.UserPromptSubmit, HOOK_COMMANDS.userPrompt);
+    const mcpServers = object(mcp.mcpServers);
+    const configuredMcp = mcpServers['fluffy-context'];
+    const installed = mcpInstalled(configuredMcp);
+    const mcpConflict = configuredMcp !== undefined && !installed && !mcpInstalled(configuredMcp, LEGACY_MCP_SERVER);
+    return {
+        projectRoot,
+        initialized,
+        settingsPath,
+        mcpPath,
+        settingsExists,
+        mcpExists,
+        sessionStartInstalled,
+        userPromptInstalled,
+        mcpInstalled: installed,
+        mcpConflict,
+        installationNeeded: !sessionStartInstalled || !userPromptInstalled || !installed,
+    };
+}
+async function inspect(projectRoot) {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    const mcpPath = path.join(projectRoot, '.mcp.json');
+    const [settingsExists, mcpExists, initialized] = await Promise.all([
+        exists(settingsPath),
+        exists(mcpPath),
+        exists(manifestPath(projectRoot)),
+    ]);
+    const [settings, mcp] = await Promise.all([loadObject(settingsPath), loadObject(mcpPath)]);
+    validateConfig(settings, mcp);
+    return { status: status(projectRoot, settingsPath, mcpPath, settings, mcp, settingsExists, mcpExists, initialized), settings, mcp };
+}
+export async function inspectClaudeIntegration(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return (await inspect(projectRoot)).status;
+}
+export async function installClaudeIntegration(startPath, apply) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const inspected = await inspect(projectRoot);
+    const targetFiles = [inspected.status.settingsPath, inspected.status.mcpPath];
+    if (!apply || !inspected.status.installationNeeded)
+        return { ...inspected.status, applied: false, targetFiles };
+    if (inspected.status.mcpConflict)
+        throw new Error('existing fluffy-context MCP server configuration conflicts with the generated integration');
+    const settingsHooks = object(inspected.settings.hooks);
+    const settings = {
+        ...inspected.settings,
+        hooks: {
+            ...settingsHooks,
+            SessionStart: addHook(settingsHooks.SessionStart, HOOK_COMMANDS.sessionStart, LEGACY_HOOK_COMMANDS.sessionStart),
+            UserPromptSubmit: addHook(settingsHooks.UserPromptSubmit, HOOK_COMMANDS.userPrompt, LEGACY_HOOK_COMMANDS.userPrompt),
+        },
+    };
+    const mcpServers = object(inspected.mcp.mcpServers);
+    const mcp = {
+        ...inspected.mcp,
+        mcpServers: { ...mcpServers, 'fluffy-context': MCP_SERVER },
+    };
+    await Promise.all([
+        atomicWriteJson(inspected.status.settingsPath, settings),
+        atomicWriteJson(inspected.status.mcpPath, mcp),
+    ]);
+    return { ...(await inspect(projectRoot)).status, applied: true, targetFiles };
+}

package/dist/src/mcp/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/mcp/main.js

@@ -0,0 +1,5 @@
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createMcpServer } from './server.js';
+serveStdio(createMcpServer, {
+    onerror: (error) => process.stderr.write(`MCP server error: ${error.message}\n`),
+});

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/server';
+export declare function createMcpServer(): McpServer;

package/dist/src/mcp/server.js

@@ -0,0 +1,40 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { contextOrient } from '../agent/api.js';
+import { VERSION } from '../version.js';
+const orientInput = z.object({
+    path: z.string().optional(),
+    contextId: z.string().optional(),
+    query: z.string().optional(),
+    scope: z.string().optional(),
+    maxChars: z.int().nonnegative().optional(),
+    knowledgeLimit: z.int().nonnegative().optional(),
+    deadendLimit: z.int().nonnegative().optional(),
+    noteLimit: z.int().nonnegative().optional(),
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createMcpServer() {
+    const server = new McpServer({ name: 'fluffy-context', version: VERSION });
+    server.registerTool('context_orient', {
+        title: 'Orient context',
+        description: 'Load bounded, read-only task context with verified consensus and open notes.',
+        inputSchema: orientInput,
+    }, async ({ path, ...options }) => {
+        try {
+            const result = await contextOrient(path, options);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `context_orient failed: ${errorMessage(error)}` }],
+            };
+        }
+    });
+    return server;
+}

package/dist/src/project/project-resolver.d.ts

@@ -0,0 +1 @@
+export declare function resolveProjectRoot(startPath?: string): Promise<string>;

package/dist/src/runtime/diagnostics.d.ts

@@ -0,0 +1,6 @@
+export declare function status(startPath?: string): Promise<Record<string, unknown>>;
+export declare function doctor(startPath?: string): Promise<{
+    healthy: boolean;
+    projectRoot: string;
+    checks: string[];
+}>;

package/dist/src/runtime/init.d.ts

@@ -0,0 +1,7 @@
+import type { Manifest } from './types.js';
+export interface InitResult {
+    projectRoot: string;
+    alreadyInitialized: boolean;
+}
+export declare function initProject(startPath?: string): Promise<InitResult>;
+export declare function loadManifest(projectRoot: string): Promise<Manifest>;

package/dist/src/runtime/knowledge.d.ts

@@ -0,0 +1,9 @@
+import type { Deadend, DeadendDiscoverOptions, DeadendDiscoveryResult, DeadendInput, Knowledge, KnowledgeDiscoverOptions, KnowledgeDiscoveryResult, KnowledgeInput } from './types.js';
+export declare function learnKnowledge(startPath: string | undefined, statement: string, scopeOrInput?: string | KnowledgeInput): Promise<Knowledge>;
+export declare function listKnowledge(startPath?: string, includeUnverified?: boolean): Promise<Knowledge[]>;
+export declare function discoverKnowledge(startPath: string | undefined, query: string, options?: KnowledgeDiscoverOptions): Promise<KnowledgeDiscoveryResult>;
+export declare function verifyKnowledge(startPath: string | undefined, knowledgeId: string): Promise<Knowledge>;
+export declare function recordDeadend(startPath: string | undefined, attempt: string, reason: string, scopeOrInput?: string | DeadendInput): Promise<Deadend>;
+export declare function listDeadends(startPath?: string, includeUnverified?: boolean): Promise<Deadend[]>;
+export declare function discoverDeadends(startPath: string | undefined, query: string, options?: DeadendDiscoverOptions): Promise<DeadendDiscoveryResult>;
+export declare function verifyDeadend(startPath: string | undefined, deadendId: string): Promise<Deadend>;

package/dist/src/runtime/notes.d.ts

@@ -0,0 +1,6 @@
+import type { ActivityQuery, ActivityResult, Note, NoteInput, NoteQuery } from './types.js';
+export declare function addNote(startPath: string | undefined, message: string, input?: NoteInput): Promise<Note>;
+export declare function listNotes(startPath: string | undefined, query?: NoteQuery): Promise<Note[]>;
+export declare function listActivity(startPath: string | undefined, query?: ActivityQuery): Promise<ActivityResult>;
+export declare function absorbNotes(startPath: string | undefined, contextId: string, snapshotId: string): Promise<number>;
+export declare function isValidNote(value: unknown): value is Note;

package/dist/src/runtime/runtime.d.ts

@@ -0,0 +1,11 @@
+import type { CheckpointInput, CheckpointResult, IndexFile, ResumeResult, StructuredContext } from './types.js';
+export interface CheckpointOptions {
+    minSaveIntervalMs?: number;
+}
+export declare function rebuildSnapshot(projectRoot: string, contextId: string, snapshotId: string, seen?: Set<string>): Promise<StructuredContext>;
+export declare function rebuildIndex(projectRoot: string, persist?: boolean): Promise<IndexFile>;
+export declare function checkpoint(startPath: string | undefined, input: CheckpointInput, options?: CheckpointOptions): Promise<CheckpointResult>;
+export interface ResumeOptions {
+    touchLastUsedAt?: boolean;
+}
+export declare function resume(startPath?: string, contextId?: string, maxChars?: number, options?: ResumeOptions): Promise<ResumeResult>;

package/dist/src/runtime/runtime.js

@@ -310,11 +310,11 @@ export async function checkpoint(startPath, input, options = {}) {
         return { status: 'saved', context: updatedContext, snapshot };
     });
 }
-export async function resume(startPath, contextId, maxChars = 4000) {
+export async function resume(startPath, contextId, maxChars = 4000, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     await loadManifest(projectRoot);
     const git = await readGitState(projectRoot);
-    const index = await rebuildIndex(projectRoot);
+    const index = await rebuildIndex(projectRoot, options.touchLastUsedAt !== false);
     const candidates = index.contexts
         .filter((entry) => !contextId || entry.contextId === contextId)
         .filter((entry) => ['active', 'stable'].includes(entry.status))
@@ -328,8 +328,10 @@ export async function resume(startPath, contextId, maxChars = 4000) {
     const snapshot = await loadSnapshot(projectRoot, candidate.contextId, context.currentSnapshotId);
     const content = await rebuildSnapshot(projectRoot, candidate.contextId, snapshot.snapshotId);
     const drift = context.branch !== git.branch || context.commit !== git.commit;
-    context.lastUsedAt = new Date().toISOString();
-    await atomicWriteJson(contextMetadataPath(projectRoot, context.id), context);
+    if (options.touchLastUsedAt !== false) {
+        context.lastUsedAt = new Date().toISOString();
+        await atomicWriteJson(contextMetadataPath(projectRoot, context.id), context);
+    }
     const budget = { remaining: Math.max(0, maxChars) };
     const resumeSummary = {
         progressSummary: limited(content.progressSummary, budget.remaining),