fluffy-context 0.7.2 → 0.7.7

package/dist/src/agent/api.d.ts

@@ -1,10 +1,16 @@
+import { type UsageInterface } from '../cognition/usage.js';
+import { type UsageReport, type UsageReportOptions } from '../cognition/usage-report.js';
 import type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, CheckpointInput, ContextSearchOptions, ContextSearchResult } from '../runtime/types.js';
 import type { ContextOrientOptions, ContextOrientResult, ContextUseInput } from './types.js';
+import type { ContextExpandInput, ContextExpandResult, ContextCompileOptions, ContextManifest } from '../compiler/types.js';
 export declare function saveContext(startPath: string | undefined, input: CheckpointInput, options?: {
     minSaveIntervalMs?: number;
 }): Promise<AgentSaveResult>;
-export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions): Promise<AgentLoadResult>;
-export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions): Promise<ContextOrientResult>;
+export declare function contextExpand(startPath: string | undefined, input: ContextExpandInput, interfaceName?: UsageInterface): Promise<ContextExpandResult>;
+export declare function contextCompile(startPath: string | undefined, options?: ContextCompileOptions, interfaceName?: UsageInterface): Promise<ContextManifest>;
+export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions, interfaceName?: UsageInterface): Promise<AgentLoadResult>;
+export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions, interfaceName?: UsageInterface | null): Promise<ContextOrientResult>;
+export declare function contextUsageReport(startPath: string | undefined, options?: UsageReportOptions): Promise<UsageReport>;
 export declare function recordContextUse(startPath: string | undefined, input: ContextUseInput): Promise<{
     recorded: boolean;
     eventId: string;

package/dist/src/agent/api.js

@@ -8,6 +8,10 @@ import { selectV2Orientation } from '../cognition/orient.js';
 import { discoverV2Deadends, discoverV2Knowledge } from '../cognition/retrieval.js';
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
+import { expandContext } from '../compiler/expand.js';
+import { compileContext } from '../compiler/compile.js';
+import { withUsageTelemetry } from '../cognition/usage.js';
+import { buildUsageReport } from '../cognition/usage-report.js';
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -138,147 +142,163 @@ export async function saveContext(startPath, input, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     return { projectRoot, result: await checkpoint(projectRoot, input, options) };
 }
-export async function loadContext(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
-    const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
-    const verifiedDeadends = await listDeadends(projectRoot);
-    return {
-        projectRoot,
-        context: result.context,
-        snapshot: result.snapshot,
-        resumeSummary: result.resumeSummary,
-        ...(options.includeDetails ? { details: result.details } : {}),
-        knowledge,
-        verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
-    };
+export async function contextExpand(startPath, input, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'expand', 'agent', input, () => resolveProjectRoot(startPath).then((projectRoot) => expandContext(projectRoot, input)), interfaceName);
 }
-export async function contextOrient(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const query = options.query === undefined ? null : options.query.trim();
-    if (query === '')
-        throw new Error('context orient query must not be empty');
-    let loaded;
-    try {
-        const v2 = await selectV2Orientation(projectRoot, options.contextId);
-        loaded = v2
-            ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
-            : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === 'no active context found') {
-            return {
-                status: 'no_context',
-                projectRoot,
-                query,
-                context: null,
-                snapshot: null,
-                resumeSummary: null,
-                knowledge: emptyKnowledge(query ?? ''),
-                deadends: emptyDeadends(query ?? ''),
-                notes: [],
-                truncated: false,
-                explanation: {
-                    mode: 'v1-fallback',
-                    selection: 'v1',
-                    retrieval: { knowledge: {}, deadends: {} },
-                    truncation: { summary: false, knowledge: false, deadends: false, notes: false },
-                },
-            };
+export async function contextCompile(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'compile', 'agent', options, () => compileContext(startPath, options), interfaceName);
+}
+export async function loadContext(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'resume', 'agent', options, async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
+        const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+        const verifiedDeadends = await listDeadends(projectRoot);
+        return {
+            projectRoot,
+            context: result.context,
+            snapshot: result.snapshot,
+            resumeSummary: result.resumeSummary,
+            ...(options.includeDetails ? { details: result.details } : {}),
+            knowledge,
+            verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
+        };
+    }, interfaceName);
+}
+export async function contextOrient(startPath, options = {}, interfaceName = 'agent') {
+    const action = async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const query = options.query === undefined ? null : options.query.trim();
+        if (query === '')
+            throw new Error('context orient query must not be empty');
+        let loaded;
+        try {
+            const v2 = await selectV2Orientation(projectRoot, options.contextId);
+            loaded = v2
+                ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
+                : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
         }
-        throw error;
-    }
-    const v2 = await selectV2Orientation(projectRoot, options.contextId);
-    const notes = (await listNotes(projectRoot, {
-        contextId: loaded.context.id,
-        openOnly: true,
-        limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
-        maxChars: options.maxChars ?? 4000,
-    })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
-    const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.knowledgeLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.deadendLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const applicableKnowledge = query === null
-        ? emptyKnowledge('')
-        : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+        catch (error) {
+            if (error instanceof Error && error.message === 'no active context found') {
+                return {
+                    status: 'no_context',
+                    projectRoot,
+                    query,
+                    context: null,
+                    snapshot: null,
+                    resumeSummary: null,
+                    knowledge: emptyKnowledge(query ?? ''),
+                    deadends: emptyDeadends(query ?? ''),
+                    notes: [],
+                    truncated: false,
+                    explanation: {
+                        mode: 'v1-fallback',
+                        selection: 'v1',
+                        retrieval: { knowledge: {}, deadends: {} },
+                        truncation: { summary: false, knowledge: false, deadends: false, notes: false },
+                    },
+                };
+            }
+            throw error;
+        }
+        const v2 = await selectV2Orientation(projectRoot, options.contextId);
+        const notes = (await listNotes(projectRoot, {
+            contextId: loaded.context.id,
+            openOnly: true,
+            limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
+            maxChars: options.maxChars ?? 4000,
+        })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
+        const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.knowledgeLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const applicableDeadends = query === null
-        ? emptyDeadends('')
-        : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+        const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
-    const resumeSummary = {
-        progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
-        lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
-        completed: limitedList(loaded.resumeSummary.completed, budget),
-        pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
-        decisions: limitedList(loaded.resumeSummary.decisions, budget),
-        risks: limitedList(loaded.resumeSummary.risks, budget),
-        relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
-        branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
-    };
-    const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
-        || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
-        || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
-        || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
-        || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
-        || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
-        || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
-    const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
-    const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
-    const limitedNotesResult = limitNotes(notes, budget);
-    return {
-        status: 'ready',
-        projectRoot,
-        query,
-        context: {
-            id: loaded.context.id,
-            title: loaded.context.title,
-            status: loaded.context.status,
-            branch: loaded.context.branch,
-            commit: loaded.context.commit,
-            updatedAt: loaded.context.updatedAt,
-        },
-        snapshot: {
-            snapshotId: loaded.snapshot.snapshotId,
-            mode: loaded.snapshot.mode,
-            createdAt: loaded.snapshot.createdAt,
-            branch: loaded.snapshot.branch,
-            commit: loaded.snapshot.commit,
-        },
-        resumeSummary,
-        knowledge: limitedKnowledgeResult.result,
-        deadends: limitedDeadendResult.result,
-        notes: limitedNotesResult.notes,
-        truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
-        explanation: {
-            mode: v2 ? 'v2' : 'v1-fallback',
-            selection: v2?.selection ?? 'v1',
-            retrieval: {
-                knowledge: v2Knowledge?.exclusions ?? {},
-                deadends: v2Deadends?.exclusions ?? {},
+        const applicableKnowledge = query === null
+            ? emptyKnowledge('')
+            : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+                scope: options.scope,
+                limit: options.knowledgeLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const applicableDeadends = query === null
+            ? emptyDeadends('')
+            : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+                scope: options.scope,
+                limit: options.deadendLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
+        const resumeSummary = {
+            progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
+            lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
+            completed: limitedList(loaded.resumeSummary.completed, budget),
+            pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
+            decisions: limitedList(loaded.resumeSummary.decisions, budget),
+            risks: limitedList(loaded.resumeSummary.risks, budget),
+            relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
+            branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
+        };
+        const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
+            || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
+            || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
+            || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
+            || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
+            || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
+            || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
+        const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
+        const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
+        const limitedNotesResult = limitNotes(notes, budget);
+        return {
+            status: 'ready',
+            projectRoot,
+            query,
+            context: {
+                id: loaded.context.id,
+                title: loaded.context.title,
+                status: loaded.context.status,
+                branch: loaded.context.branch,
+                commit: loaded.context.commit,
+                updatedAt: loaded.context.updatedAt,
+            },
+            snapshot: {
+                snapshotId: loaded.snapshot.snapshotId,
+                mode: loaded.snapshot.mode,
+                createdAt: loaded.snapshot.createdAt,
+                branch: loaded.snapshot.branch,
+                commit: loaded.snapshot.commit,
             },
-            truncation: {
-                summary: resumeTruncated,
-                knowledge: limitedKnowledgeResult.truncated,
-                deadends: limitedDeadendResult.truncated,
-                notes: limitedNotesResult.truncated,
+            resumeSummary,
+            knowledge: limitedKnowledgeResult.result,
+            deadends: limitedDeadendResult.result,
+            notes: limitedNotesResult.notes,
+            truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
+            explanation: {
+                mode: v2 ? 'v2' : 'v1-fallback',
+                selection: v2?.selection ?? 'v1',
+                retrieval: {
+                    knowledge: v2Knowledge?.exclusions ?? {},
+                    deadends: v2Deadends?.exclusions ?? {},
+                },
+                truncation: {
+                    summary: resumeTruncated,
+                    knowledge: limitedKnowledgeResult.truncated,
+                    deadends: limitedDeadendResult.truncated,
+                    notes: limitedNotesResult.truncated,
+                },
             },
-        },
+        };
     };
+    return interfaceName === null
+        ? action()
+        : withUsageTelemetry(startPath, 'orient', 'agent', options, action, interfaceName);
+}
+export async function contextUsageReport(startPath, options = {}) {
+    return buildUsageReport(startPath, options);
 }
 export async function recordContextUse(startPath, input) {
     return recordUse(startPath, input);

package/dist/src/agent/index.d.ts

@@ -1,5 +1,7 @@
 export * from './api.js';
 export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
-export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';
+export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';
+export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExpandInput, ContextExpandLevel, ContextExpandResult, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextLevel, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';

package/dist/src/agent/index.js

@@ -1,2 +1,4 @@
 export * from './api.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
+export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';

package/dist/src/cli/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { checkpoint, resume } from '../runtime/runtime.js';
-import { contextOrient } from '../agent/api.js';
-import { compileContext } from '../compiler/compile.js';
+import { checkpoint } from '../runtime/runtime.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, loadContext } from '../agent/api.js';
+import { formatUsageReport } from '../cognition/usage-report.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
 import { verifyJournal } from '../cognition/journal.js';
@@ -81,6 +81,34 @@ Initialize the local .context runtime layout. Re-running init is safe.
 
 Options:
   --path <path>  Project path`,
+    usage: `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
+    'usage report': `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
     checkpoint: `usage: ctx checkpoint [options]
 
 Save structured work state as a baseline or incremental snapshot.
@@ -131,6 +159,27 @@ Options:
   --knowledge-limit <number> Maximum knowledge matches (default: 10)
   --deadend-limit <number>   Maximum deadend matches (default: 10)
   --note-limit <number>      Maximum open notes (default: 20)
+  --activity-limit <number>  Maximum recent activity groups (default: 20)`,
+    expand: `usage: ctx expand [options]
+
+Expand one selected compiler candidate without writing project state.
+
+Options:
+  --path <path>              Project path
+  --manifest-hash <hash>     Manifest identity hash from ctx compile
+  --candidate-id <id>        Selected candidate ID
+  --item-hash <hash>         Selected item hash
+  --level <level>            structured|evidence
+  --max-chars <number>       Maximum expanded characters
+  --compile-max-chars <number> Original compile budget (default: 4000)
+  --context <id>             Context ID
+  --query <text>             Original compile query
+  --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
+  --scope <scope>            Exact consensus scope
+  --paths <paths>            Comma-separated project-relative paths
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)
   --activity-limit <number>  Maximum recent activity groups (default: 20)`,
     agent: `usage: ctx agent serve
 
@@ -139,7 +188,7 @@ 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.
+Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, context_usage_report, and context_checkpoint tools.
 
 The server owns standard input/output; do not use it interactively.`,
     hook: `usage: ctx hook claude-code session-start|user-prompt
@@ -341,7 +390,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|compile|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -370,7 +419,7 @@ function printHelp(args) {
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
         || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
-        || (command === 'filesystem' && ['enable', 'disable', 'status'].includes(args[1]));
+        || (command === 'usage' && args[1] === 'report');
     const key = nested ? `${command} ${args[1]}` : command;
     const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
     const help = HELP[nestedKey];
@@ -428,7 +477,7 @@ async function run(args) {
         case 'resume':
             validateOptions(args.slice(1), ['--path', '--context', '--max-chars'], ['--path', '--context', '--max-chars']);
             validatePositionals(positionals(args.slice(1), ['--path', '--context', '--max-chars']), 0, HELP.resume);
-            print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
+            print(await loadContext(target, { contextId: option(args, '--context'), maxChars: numericOption(args, '--max-chars', 4000) }, 'cli'));
             return;
         case 'orient': {
             const valueOptions = ['--path', '--context', '--scope', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit'];
@@ -444,7 +493,7 @@ async function run(args) {
                 knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
-            }));
+            }, 'cli'));
             return;
         }
         case 'compile': {
@@ -452,7 +501,7 @@ async function run(args) {
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const query = positionals(args.slice(1), valueOptions);
             validatePositionals(query, 1, HELP.compile);
-            print(await compileContext(target, {
+            print(await contextCompile(target, {
                 contextId: option(args, '--context'),
                 query: query[0],
                 scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
@@ -463,9 +512,63 @@ async function run(args) {
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
                 activityLimit: numericOption(args, '--activity-limit', 20),
+            }, 'cli'));
+            return;
+        }
+        case 'expand': {
+            const valueOptions = ['--path', '--manifest-hash', '--candidate-id', '--item-hash', '--level', '--max-chars', '--compile-max-chars', '--context', '--query', '--scenario', '--scope', '--paths', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(1), valueOptions), 0, HELP.expand);
+            const level = enumOption(args, '--level', ['structured', 'evidence']);
+            if (!level)
+                throw new Error('--level is required');
+            const manifestHash = option(args, '--manifest-hash');
+            if (!manifestHash)
+                throw new Error('--manifest-hash is required');
+            const compileMaxChars = numericOption(args, '--compile-max-chars', 4000);
+            await ensureRuntimeForSession(target, { source: 'cli', timeoutMs: 1_000 }).catch(() => undefined);
+            print(await contextExpand(target, {
+                manifestHash,
+                candidateId: option(args, '--candidate-id'),
+                itemHash: option(args, '--item-hash'),
+                level: level,
+                maxChars: option(args, '--max-chars') === undefined ? undefined : numericOption(args, '--max-chars', 0),
+                compile: {
+                    contextId: option(args, '--context'),
+                    query: option(args, '--query'),
+                    scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
+                    scope: option(args, '--scope'),
+                    paths: listOption(args, '--paths'),
+                    maxChars: compileMaxChars,
+                    knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                    deadendLimit: numericOption(args, '--deadend-limit', 10),
+                    noteLimit: numericOption(args, '--note-limit', 20),
+                    activityLimit: numericOption(args, '--activity-limit', 20),
+                },
             }));
             return;
         }
+        case 'usage': {
+            if (args[1] !== 'report')
+                throw new Error(HELP.usage);
+            const valueOptions = ['--path', '--since', '--until', '--days', '--month', '--granularity', '--format', '--baseline-tokens', '--baseline-source'];
+            validateOptions(args.slice(2), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(2), valueOptions), 0, HELP['usage report']);
+            const report = await contextUsageReport(target, {
+                since: option(args, '--since'),
+                until: option(args, '--until'),
+                days: option(args, '--days') === undefined ? undefined : numericOption(args, '--days', 30),
+                month: option(args, '--month'),
+                granularity: enumOption(args, '--granularity', ['day', 'week', 'month']),
+                baselineTokens: option(args, '--baseline-tokens') === undefined ? undefined : numericOption(args, '--baseline-tokens', 0),
+                baselineSource: enumOption(args, '--baseline-source', ['manual', 'recorded-control']),
+            });
+            if (enumOption(args, '--format', ['json', 'ascii']) === 'ascii')
+                process.stdout.write(formatUsageReport(report));
+            else
+                print(report);
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);

package/dist/src/cognition/journal.js

@@ -11,9 +11,10 @@ const eventTypes = new Set([
     'context.checkpoint.imported', 'context.state.recorded', 'note.recorded', 'note.resolved', 'note.absorbed',
     'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
     'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected', 'record.used',
+    'usage.operation.completed',
     'projection.advanced', 'projection.failed',
 ]);
-const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'agent', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -55,6 +56,33 @@ function validGitAnchor(value) {
 function validIsoDate(value) {
     return typeof value === 'string' && Number.isFinite(Date.parse(value));
 }
+function validatePayloadBoundary(input) {
+    const payload = input.payload;
+    if (input.type === 'host.prompt.submitted' && (typeof payload.intent !== 'string' || payload.intent.trim().length === 0)) {
+        throw new Error('host prompt intent must not be empty');
+    }
+    if (['note.recorded', 'note.resolved', 'note.absorbed'].includes(input.type)) {
+        const record = payload.record;
+        if (!isRecord(record) || typeof record.message !== 'string' || record.message.trim().length === 0)
+            throw new Error('note message must not be empty');
+    }
+    if (input.type === 'usage.operation.completed') {
+        const requiredNumbers = ['durationMs', 'inputChars', 'outputChars', 'inputBytes', 'outputBytes', 'estimatedInputTokens', 'estimatedOutputTokens'];
+        if (payload.operation !== 'orient' && payload.operation !== 'compile' && payload.operation !== 'expand' && payload.operation !== 'resume')
+            throw new Error('invalid usage operation');
+        if (payload.interface !== 'cli' && payload.interface !== 'mcp' && payload.interface !== 'agent' && payload.interface !== 'hook')
+            throw new Error('invalid usage interface');
+        if (typeof payload.success !== 'boolean' || payload.estimatedMethod !== 'chars-div-four' || requiredNumbers.some((key) => typeof payload[key] !== 'number' || !Number.isFinite(payload[key]) || payload[key] < 0))
+            throw new Error('invalid usage telemetry payload');
+        if (!payload.success && typeof payload.errorClass !== 'string')
+            throw new Error('usage errors require an error class');
+    }
+    if (input.type === 'workspace.paths.changed') {
+        const changes = payload.changes;
+        if (!Array.isArray(changes) || changes.length === 0)
+            throw new Error('workspace activity must contain changes');
+    }
+}
 function validateEventShape(event, projectId, file, line) {
     if (!isRecord(event)
         || event.schemaVersion !== 2
@@ -140,6 +168,7 @@ export async function verifyJournal(startPath) {
     return readJournal(startPath, { allowPartialTail: false });
 }
 export async function appendEvent(startPath, input) {
+    validatePayloadBoundary(input);
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-journal.lock`, async () => {
         await recoverPartialTail(projectRoot);

package/dist/src/cognition/types.d.ts

@@ -1,6 +1,6 @@
 export declare const COGNITION_LAYOUT_VERSION: "event-journal-v2";
-export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'git-observer' | 'fs-observer' | 'migration';
-export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'projection.advanced' | 'projection.failed';
+export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'agent' | 'git-observer' | 'fs-observer' | 'migration';
+export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'usage.operation.completed' | 'projection.advanced' | 'projection.failed';
 export interface CognitionGitAnchor {
     worktreeId: string | null;
     branch: string | null;
@@ -67,6 +67,20 @@ export interface CognitionUseFeedback {
     entityId: string;
     outcome: 'used';
 }
+export interface UsageOperationCompletedPayload {
+    operation: 'orient' | 'compile' | 'expand' | 'resume';
+    interface: 'cli' | 'mcp' | 'agent' | 'hook';
+    success: boolean;
+    durationMs: number;
+    inputChars: number;
+    outputChars: number;
+    inputBytes: number;
+    outputBytes: number;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedMethod: 'chars-div-four';
+    errorClass?: string;
+}
 export interface CognitionRetrievalEntry {
     entity: 'knowledge' | 'deadend';
     entityId: string;