@kentwynn/kgraph 0.2.36 → 0.2.38

package/dist/cli/commands/pack.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
 import { buildContextPack } from '../../context/context-pack.js';
 import { queryContext } from '../../context/context-query.js';
+import { getCurrentCommit, isGitRepo } from '../../scanner/git-utils.js';
 import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { listInboxNotes } from '../../storage/cognition-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
@@ -28,19 +29,51 @@ export function registerPackCommand(program) {
         const agent = options.agent ??
             command.getOptionValue('agent') ??
             findCommandOption(command, 'agent');
+        const [config, maps] = await Promise.all([
+            loadConfig(workspace),
+            readMaps(workspace),
+        ]);
+        const response = await queryContext(workspace, config, maps, task);
+        const pack = buildContextPack(response, budget, workspace.rootPath);
+        // P4: warn when maps are behind HEAD (user edited files without re-scanning)
+        if (await isGitRepo(workspace.rootPath)) {
+            const head = await getCurrentCommit(workspace.rootPath);
+            if (head &&
+                maps.fileMap.scannedAtCommit &&
+                maps.fileMap.scannedAtCommit !== head) {
+                pack.warnings = [
+                    `Maps are behind HEAD — run \`kgraph scan\` or \`kgraph "${task}"${agent ? ` --agent ${agent}` : ''}\` for accurate atom status. Knowledge freshness may be reduced.`,
+                    ...pack.warnings,
+                ];
+            }
+        }
+        // P1: warn when needs-review or stale atoms are served in context
+        const degradedAtoms = pack.items.filter((item) => item.kind === 'atom' &&
+            (item.data.status === 'needs-review' ||
+                item.data.status === 'stale'));
+        if (degradedAtoms.length > 0) {
+            const needsReview = degradedAtoms.filter((item) => item.data.status === 'needs-review').length;
+            const stale = degradedAtoms.filter((item) => item.data.status === 'stale').length;
+            const parts = [];
+            if (needsReview > 0)
+                parts.push(`${needsReview} needs-review`);
+            if (stale > 0)
+                parts.push(`${stale} stale`);
+            pack.warnings = [
+                ...pack.warnings,
+                `${parts.join(', ')} atom(s) in context may reflect outdated knowledge — run \`kgraph stale\` to inspect, or \`kgraph "${task}" --final${agent ? ` --agent ${agent}` : ''}\` to resolve.`,
+            ];
+        }
         if (agent) {
+            const omittedTokens = pack.omitted.reduce((sum, item) => sum + item.tokenEstimate, 0);
             await recordSessionEvent(workspace, {
                 agent: assertSessionAgent(agent),
                 type: 'context',
                 captureSource: 'automatic',
+                packUsedTokens: pack.usedTokens,
+                packOmittedTokens: omittedTokens,
             });
         }
-        const [config, maps] = await Promise.all([
-            loadConfig(workspace),
-            readMaps(workspace),
-        ]);
-        const response = await queryContext(workspace, config, maps, task);
-        const pack = buildContextPack(response, budget, workspace.rootPath);
         const pendingInboxFiles = (await listInboxNotes(workspace)).map((file) => path.relative(workspace.rootPath, file).split(path.sep).join('/'));
         if (pendingInboxFiles.length > 0) {
             pack.pendingInbox = {

package/dist/cli/commands/session.js

@@ -13,7 +13,9 @@ export function registerSessionCommand(program) {
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const report = await buildSessionReport(workspace);
-        console.log(options.json ? JSON.stringify(report, null, 2) : renderSessionReport(report));
+        console.log(options.json
+            ? JSON.stringify(report, null, 2)
+            : renderSessionReport(report));
     }));
     session
         .command('start')
@@ -112,10 +114,25 @@ export function renderSessionReport(report) {
     lines.push(`Repeated reads: ${report.repeatedReadCount}`);
     lines.push(`Estimated read tokens: ${report.estimatedReadTokens}`);
     lines.push(`Estimated repeated-read tokens: ${report.estimatedRepeatedReadTokens}`);
+    lines.push('');
+    lines.push('Pack Usage');
+    lines.push(`  Pack calls: ${report.packCallCount}`);
+    lines.push(`  Tokens used: ${report.totalPackUsedTokens}`);
+    lines.push(`  Tokens filtered: ${report.totalPackOmittedTokens}`);
+    if (report.packCallCount > 0 && report.totalPackOmittedTokens > 0) {
+        const total = report.totalPackUsedTokens + report.totalPackOmittedTokens;
+        const pct = Math.round((report.totalPackOmittedTokens / total) * 100);
+        lines.push(`  Filter rate: ${pct}% of candidate tokens excluded from context`);
+    }
     lines.push('', 'Top Repeated Reads');
     lines.push(...formatList(report.topRepeatedReads.map((item) => `- ${item.path} read ${item.count} times (~${item.estimatedTokens} tokens)`)));
     lines.push('', 'Recent Events');
-    lines.push(...formatList(report.recentEvents.map((event) => `- ${event.agent} ${event.type}${event.path ? ` ${event.path}` : ''} [${event.captureSource}]`)));
+    lines.push(...formatList(report.recentEvents.map((event) => {
+        const packInfo = event.packUsedTokens !== undefined
+            ? ` [used:${event.packUsedTokens} filtered:${event.packOmittedTokens ?? 0}]`
+            : '';
+        return `- ${event.agent} ${event.type}${event.path ? ` ${event.path}` : ''}${packInfo} [${event.captureSource}]`;
+    })));
     lines.push('', 'Recent Ledger');
     lines.push(...formatList(report.ledger.map((entry) => `- ${entry.agent} ${entry.readCount} reads, ${entry.writeCount} writes, ${entry.repeatedReadCount} repeated`)));
     lines.push('', 'Next');
@@ -144,7 +161,9 @@ function findCommandOption(command, name) {
     return undefined;
 }
 function normalizeSource(value) {
-    if (value === 'automatic' || value === 'agent-reported' || value === 'manual') {
+    if (value === 'automatic' ||
+        value === 'agent-reported' ||
+        value === 'manual') {
         return value;
     }
     throw new KGraphError('--source must be automatic, agent-reported, or manual.');
@@ -153,7 +172,9 @@ function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
 function sessionNextActions(report) {
-    if (report.readCount === 0 && report.writeCount === 0) {
+    if (report.packCallCount === 0 &&
+        report.readCount === 0 &&
+        report.writeCount === 0) {
         return [
             '- Start tracking with `kgraph session start --agent <name>`.',
             '- Record meaningful reads/writes with `kgraph session read <path> --agent <name>` and `kgraph session write <path> --agent <name>`.',

package/dist/cli/commands/visualize.js

@@ -2,10 +2,11 @@ import { exec } from 'node:child_process';
 import { createServer } from 'node:http';
 import { loadConfig } from '../../config/config.js';
 import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
+import { readSessionState } from '../../session/session-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { buildGraph } from '../../visualization/graph-builder.js';
-import { renderHtml } from '../../visualization/html-template.js';
+import { renderHtml, } from '../../visualization/html-template.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerVisualizeCommand(program) {
     program
@@ -22,14 +23,36 @@ export function registerVisualizeCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
-        const maps = await readMaps(workspace);
+        const [maps, sessionState] = await Promise.all([
+            readMaps(workspace),
+            readSessionState(workspace),
+        ]);
         const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
             fileMap: maps.fileMap,
             symbolMap: maps.symbolMap,
         });
         await loadConfig(workspace); // ensure workspace is valid
+        const contextEvents = sessionState.events.filter((e) => e.type === 'context');
+        const sessionVizData = sessionState.events.length > 0
+            ? {
+                activeAgents: Object.values(sessionState.active).map((a) => a.agent),
+                packCallCount: contextEvents.length,
+                totalPackUsedTokens: contextEvents.reduce((sum, e) => sum + (e.packUsedTokens ?? 0), 0),
+                totalPackOmittedTokens: contextEvents.reduce((sum, e) => sum + (e.packOmittedTokens ?? 0), 0),
+                readCount: sessionState.events.filter((e) => e.type === 'read')
+                    .length,
+                writeCount: sessionState.events.filter((e) => e.type === 'write').length,
+                contextEvents: contextEvents.map((e) => ({
+                    agent: e.agent,
+                    packUsedTokens: e.packUsedTokens ?? 0,
+                    packOmittedTokens: e.packOmittedTokens ?? 0,
+                    timestamp: e.timestamp,
+                    captureSource: e.captureSource,
+                })),
+            }
+            : undefined;
         const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, atoms);
-        const html = renderHtml(graphData, workspace.rootPath);
+        const html = renderHtml(graphData, workspace.rootPath, sessionVizData);
         await serveGraph(html, port, options.open);
     }));
 }

package/dist/context/ranking.js

@@ -14,7 +14,10 @@ export function rankByFields(query, items, fields) {
         for (const field of fields) {
             const value = field.value(item);
             const values = Array.isArray(value) ? value : value ? [value] : [];
-            const haystack = values.flatMap((value) => [value, splitIdentifier(value).join(' ')]).join(' ').toLowerCase();
+            const haystack = values
+                .flatMap((value) => [value, splitIdentifier(value).join(' ')])
+                .join(' ')
+                .toLowerCase();
             for (const token of tokens) {
                 if (haystack.includes(token)) {
                     const baseScore = field.name === 'path' || field.name === 'name'
@@ -36,7 +39,25 @@ export function rankByFields(query, items, fields) {
         .sort((a, b) => b.score - a.score);
 }
 function expandTokens(tokens) {
-    return [...new Set(tokens.flatMap((token) => [token, ...splitIdentifier(token)]))];
+    return [
+        ...new Set(tokens.flatMap((token) => {
+            const parts = [token, ...splitIdentifier(token)];
+            // Add prefix stems so "authentication" also matches "auth",
+            // "configuration" matches "config", etc. Only for longer tokens
+            // to avoid over-matching short words.
+            // Use a short 4-char stem (catches root prefixes like "auth", "conf", "init")
+            // and a half-length stem (catches "config" from "configuration", "authent" from
+            // "authentication"). Both are narrower than the full token so they find real matches
+            // without over-fetching.
+            if (token.length >= 8) {
+                parts.push(token.slice(0, 4));
+                const half = Math.floor(token.length * 0.5);
+                if (half > 4)
+                    parts.push(token.slice(0, half));
+            }
+            return parts;
+        })),
+    ];
 }
 function splitIdentifier(value) {
     return value

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

@@ -6,9 +6,16 @@ export const claudeCodeAdapter = {
     instructions: `## KGraph Workflow
 
 ${numberedWorkflow('claude-code', {
-        sessionQualifier: 'native hooks also report session activity when configured',
+        sessionQualifier: 'native hooks also report session activity automatically',
     })}
 `,
+    configFiles: [
+        {
+            path: '.claude/settings.json',
+            merge: mergeClaudeHooks,
+            remove: removeClaudeHooks,
+        },
+    ],
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
@@ -106,6 +113,88 @@ ${numberedWorkflow('claude-code')}
     ],
     obsoleteCommandFiles: [],
 };
+const KGRAPH_HOOK_MARKER = 'kgraph-session';
+const CLAUDE_HOOK_REGISTRATIONS = [
+    {
+        event: 'UserPromptSubmit',
+        entry: {
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-start.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'PreToolUse',
+        entry: {
+            matcher: 'Read',
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-pre-read.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'PostToolUse',
+        entry: {
+            matcher: 'Write|Edit|MultiEdit',
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-post-write.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'Stop',
+        entry: {
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-stop.cjs',
+                },
+            ],
+        },
+    },
+];
+function mergeClaudeHooks(existing) {
+    const settings = { ...existing };
+    const hooks = typeof settings.hooks === 'object' && settings.hooks !== null
+        ? { ...settings.hooks }
+        : {};
+    for (const { event, entry } of CLAUDE_HOOK_REGISTRATIONS) {
+        const entries = (hooks[event] ?? []);
+        const alreadyPresent = entries.some((e) => e.hooks.some((h) => h.command.includes(KGRAPH_HOOK_MARKER)));
+        if (!alreadyPresent) {
+            hooks[event] = [...entries, entry];
+        }
+    }
+    settings.hooks = hooks;
+    return settings;
+}
+function removeClaudeHooks(existing) {
+    if (typeof existing.hooks !== 'object' || existing.hooks === null)
+        return existing;
+    const settings = { ...existing };
+    const hooks = { ...settings.hooks };
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = hooks[event].filter((entry) => !entry.hooks.some((h) => h.command.includes(KGRAPH_HOOK_MARKER)));
+        if (hooks[event].length === 0) {
+            delete hooks[event];
+        }
+    }
+    if (Object.keys(hooks).length === 0) {
+        const { hooks: _removed, ...rest } = settings;
+        return rest;
+    }
+    settings.hooks = hooks;
+    return settings;
+}
 function hookScript(event) {
     const pathArg = event === 'read' || event === 'write'
         ? `const payload = readPayload();
@@ -113,6 +202,22 @@ const filePath = payload?.tool_input?.file_path || payload?.toolInput?.file_path
 if (!filePath) process.exit(0);
 args.push(filePath);`
         : '';
+    // On session end: run stale check first (refreshes atom statuses against current
+    // maps without needing a topic), then end the session with --conclude so any
+    // pending knowledge is captured. Both run regardless of each other's exit code.
+    if (event === 'end') {
+        return `#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+
+// P3: refresh atom statuses against current maps so needs-review/stale atoms
+// are up to date before the session ends. Output ignored — hook is silent.
+spawnSync('kgraph', ['stale', '--json'], { stdio: 'ignore' });
+
+// P2: end the session and trigger conclude so durable knowledge is captured.
+const result = spawnSync('kgraph', ['session', 'end', '--agent', 'claude-code', '--conclude', '--source', 'automatic'], { stdio: 'ignore' });
+process.exit(result.status || 0);
+`;
+    }
     return `#!/usr/bin/env node
 const { spawnSync } = require('node:child_process');
 

package/dist/integrations/adapters/cline.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { bulletWorkflow } from '../workflow-steps.js';
 export const clineAdapter = {
     name: 'cline',
@@ -7,4 +8,5 @@ export const clineAdapter = {
 
 ${bulletWorkflow('cline')}
 `,
+    commandFiles: agentSkillFiles('cline'),
 };

package/dist/integrations/adapters/cursor.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { bulletWorkflow } from '../workflow-steps.js';
 export const cursorAdapter = {
     name: 'cursor',
@@ -12,5 +13,6 @@ alwaysApply: true
 
 ${bulletWorkflow('cursor')}
 `,
+    commandFiles: agentSkillFiles('cursor'),
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/integrations/adapters/gemini.js

@@ -1,10 +1,13 @@
-import { bulletWorkflow } from '../workflow-steps.js';
+import { agentSkillFiles } from '../agent-skills.js';
+import { numberedWorkflow } from '../workflow-steps.js';
 export const geminiAdapter = {
     name: 'gemini',
     label: 'Gemini CLI',
     targetPath: 'GEMINI.md',
     instructions: `## KGraph Workflow
 
-${bulletWorkflow('gemini')}
+${numberedWorkflow('gemini')}
 `,
+    commandFiles: agentSkillFiles('gemini'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/adapters/windsurf.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { bulletWorkflow } from '../workflow-steps.js';
 export const windsurfAdapter = {
     name: 'windsurf',
@@ -7,4 +8,6 @@ export const windsurfAdapter = {
 
 ${bulletWorkflow('windsurf')}
 `,
+    commandFiles: agentSkillFiles('windsurf'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/instruction-blocks.js

@@ -54,7 +54,7 @@ export function renderContextPolicy(mode, agentName) {
         case 'always':
             return `Every chat in this repository must use the correct KGraph command before answering or exploring files. ${routing} For normal repo context, code navigation, debugging, review, or edits, run \`${packCommand}\`. If that pack reports pending inbox notes, run \`${rootCommand}\` or \`kgraph update\` before relying on history or newly captured atoms. Infer the topic from the user's message. This records a lightweight KGraph session context event for the agent. ${useResultBoundary}`;
         case 'manual':
-            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack. If the user explicitly asks for KGraph history, inbox/update, knowledge, or doctor, run that specific KGraph command instead of pack.';
+            return `Do not run KGraph automatically. Run \`${packCommand}\` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack. If the user explicitly asks for KGraph history, inbox/update, knowledge, or doctor, run that specific KGraph command instead of pack.`;
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':

package/dist/integrations/integration-registry.d.ts

@@ -5,12 +5,21 @@ export interface IntegrationAdapter {
     targetPath: string;
     instructions: string;
     commandFiles?: IntegrationCommandFile[];
+    configFiles?: IntegrationConfigFile[];
     obsoleteCommandFiles?: string[];
 }
 export interface IntegrationCommandFile {
     path: string;
     content: string;
 }
+export interface IntegrationConfigFile {
+    /** Repo-relative path to a JSON config file (e.g. `.claude/settings.json`). */
+    path: string;
+    /** Merge KGraph entries into the existing parsed JSON object and return the result. */
+    merge: (existing: Record<string, unknown>) => Record<string, unknown>;
+    /** Remove KGraph entries from the existing parsed JSON and return the result. */
+    remove: (existing: Record<string, unknown>) => Record<string, unknown>;
+}
 export declare function listIntegrationAdapters(): IntegrationAdapter[];
 export declare function getIntegrationAdapter(name: string): IntegrationAdapter;
 export declare function normalizeIntegrationNames(values: string[] | undefined): IntegrationName[];

package/dist/integrations/integration-store.js

@@ -32,6 +32,7 @@ export async function addIntegrations(workspace, names, mode = 'always') {
         if (mode === 'off') {
             await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
             await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+            await removeIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         }
         else {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode, adapter.name));
@@ -43,6 +44,7 @@ export async function addIntegrations(workspace, names, mode = 'always') {
             for (const file of adapter.commandFiles ?? []) {
                 writtenCommandFiles.add(file.path);
             }
+            await upsertIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         changed.push(next);
@@ -74,6 +76,7 @@ export async function removeIntegrations(workspace, names) {
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
         await removeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).filter((file) => !retainedPaths.has(file.path)));
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
+        await removeIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         removed.push(adapter.name);
     }
     config.integrations = config.integrations.filter((integration) => !removeNames.has(integration.name));
@@ -133,3 +136,42 @@ async function pruneEmptyParents(rootPath, startDir) {
         }
     }
 }
+async function upsertIntegrationConfigFiles(rootPath, configFiles) {
+    for (const configFile of configFiles) {
+        const fullPath = path.join(rootPath, configFile.path);
+        let existing = {};
+        if (await pathExists(fullPath)) {
+            try {
+                existing = JSON.parse(await readFile(fullPath, 'utf8'));
+            }
+            catch {
+                existing = {};
+            }
+        }
+        const next = configFile.merge(existing);
+        await mkdir(path.dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    }
+}
+async function removeIntegrationConfigFiles(rootPath, configFiles) {
+    for (const configFile of configFiles) {
+        const fullPath = path.join(rootPath, configFile.path);
+        if (!(await pathExists(fullPath)))
+            continue;
+        let existing = {};
+        try {
+            existing = JSON.parse(await readFile(fullPath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const next = configFile.remove(existing);
+        if (Object.keys(next).length === 0) {
+            await rm(fullPath, { force: true });
+            await pruneEmptyParents(rootPath, path.dirname(fullPath));
+        }
+        else {
+            await writeFile(fullPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        }
+    }
+}

package/dist/session/session-store.d.ts

@@ -11,5 +11,7 @@ export declare function recordSessionEvent(workspace: KGraphWorkspace, input: {
     path?: string;
     captureSource: SessionCaptureSource;
     fileMap?: FileMap;
+    packUsedTokens?: number;
+    packOmittedTokens?: number;
 }): Promise<SessionEvent>;
 export declare function buildSessionReport(workspace: KGraphWorkspace): Promise<SessionReport>;

package/dist/session/session-store.js

@@ -63,6 +63,12 @@ export async function recordSessionEvent(workspace, input) {
         ...(normalizedPath ? { path: normalizedPath } : {}),
         ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
         ...(repeated !== undefined ? { repeated } : {}),
+        ...(input.type === 'context' && input.packUsedTokens !== undefined
+            ? { packUsedTokens: input.packUsedTokens }
+            : {}),
+        ...(input.type === 'context' && input.packOmittedTokens !== undefined
+            ? { packOmittedTokens: input.packOmittedTokens }
+            : {}),
         captureSource: input.captureSource,
         timestamp: now,
     };
@@ -90,6 +96,7 @@ export async function buildSessionReport(workspace) {
     const readEvents = state.events.filter((event) => event.type === 'read');
     const writeEvents = state.events.filter((event) => event.type === 'write');
     const repeatedReads = readEvents.filter((event) => event.repeated);
+    const contextEvents = state.events.filter((event) => event.type === 'context');
     return {
         activeAgents: Object.values(state.active),
         readCount: readEvents.length,
@@ -97,6 +104,9 @@ export async function buildSessionReport(workspace) {
         repeatedReadCount: repeatedReads.length,
         estimatedReadTokens: sumTokens(readEvents),
         estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+        packCallCount: contextEvents.length,
+        totalPackUsedTokens: contextEvents.reduce((sum, e) => sum + (e.packUsedTokens ?? 0), 0),
+        totalPackOmittedTokens: contextEvents.reduce((sum, e) => sum + (e.packOmittedTokens ?? 0), 0),
         topRepeatedReads: topRepeatedReads(readEvents),
         recentEvents: state.events.slice(-10),
         ledger: ledger.slice(-10),

package/dist/types/session.d.ts

@@ -9,6 +9,8 @@ export interface SessionEvent {
     path?: string;
     tokenEstimate?: number;
     repeated?: boolean;
+    packUsedTokens?: number;
+    packOmittedTokens?: number;
     captureSource: SessionCaptureSource;
     timestamp: string;
 }
@@ -41,6 +43,9 @@ export interface SessionReport {
     repeatedReadCount: number;
     estimatedReadTokens: number;
     estimatedRepeatedReadTokens: number;
+    packCallCount: number;
+    totalPackUsedTokens: number;
+    totalPackOmittedTokens: number;
     topRepeatedReads: Array<{
         path: string;
         count: number;

package/dist/visualization/html-template.d.ts

@@ -1,2 +1,17 @@
 import type { GraphData } from './graph-builder.js';
-export declare function renderHtml(graphData: GraphData, rootPath: string): string;
+export interface SessionVizData {
+    activeAgents: string[];
+    packCallCount: number;
+    totalPackUsedTokens: number;
+    totalPackOmittedTokens: number;
+    readCount: number;
+    writeCount: number;
+    contextEvents: Array<{
+        agent: string;
+        packUsedTokens: number;
+        packOmittedTokens: number;
+        timestamp: string;
+        captureSource: string;
+    }>;
+}
+export declare function renderHtml(graphData: GraphData, rootPath: string, sessionData?: SessionVizData): string;

package/dist/visualization/html-template.js

@@ -1,8 +1,11 @@
-export function renderHtml(graphData, rootPath) {
+export function renderHtml(graphData, rootPath, sessionData) {
     const repoName = escAttr(rootPath.split(/[\\/]/).pop() ?? 'Repository');
     const { meta } = graphData;
     // Prevent </script> tag injection from embedded JSON
-    const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\\/script>');
+    const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\/script>');
+    const safeSessionData = sessionData
+        ? JSON.stringify(sessionData).replace(/<\/script>/gi, '<\/script>')
+        : null;
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -46,6 +49,31 @@ select:hover,button:hover{background:#475569}
 .li-dia{width:10px;height:10px;transform:rotate(45deg);flex-shrink:0;display:inline-block}
 .li-sep{width:1px;height:14px;background:#334155;flex-shrink:0}
 .li-head{font-size:11px;color:#475569;font-weight:700;letter-spacing:.04em}
+#session-panel{width:310px;background:#1e293b;border-left:1px solid #334155;display:none;flex-direction:column;overflow:hidden;flex-shrink:0}
+#session-panel.open{display:flex}
+#btn-session{color:#7dd3fc;border-color:#3b82f6}
+#btn-session.active,#btn-session:hover{background:#1e3a5f!important;color:#7dd3fc;border-color:#3b82f6}
+#sp-head{display:flex;align-items:center;padding:12px 14px;border-bottom:1px solid #334155;gap:8px;flex-shrink:0}
+#sp-title{font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:#7dd3fc;flex-shrink:0}
+#sp-agents{color:#475569;font-size:11px;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#sp-close2{background:none!important;border:none!important;color:#64748b;font-size:17px;line-height:1;cursor:pointer;padding:0 2px;flex-shrink:0;box-shadow:none}
+#sp-close2:hover{color:#e2e8f0}
+#sp-body{padding:14px;overflow-y:auto;flex:1;display:flex;flex-direction:column;gap:16px}
+.sp-summary{display:grid;grid-template-columns:1fr 1fr;gap:6px}
+.sp-metric{background:#0f172a;border:1px solid #334155;border-radius:5px;padding:8px 10px}
+.sp-metric-val{font-size:18px;font-weight:700;color:#f1f5f9;line-height:1;font-variant-numeric:tabular-nums}
+.sp-metric-val.accent{color:#7dd3fc}
+.sp-metric-lbl{font-size:10px;color:#64748b;margin-top:3px;text-transform:uppercase;letter-spacing:.05em}
+.sp-group-lbl{font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.07em;color:#475569;padding-bottom:6px;margin-bottom:2px;border-bottom:1px solid #1e293b}
+.sp-call-row{display:flex;align-items:center;gap:8px;padding:5px 0;border-bottom:1px solid #0f172a}
+.sp-call-row:last-child{border-bottom:none}
+.sp-call-time{font-size:10px;color:#475569;flex-shrink:0;width:44px}
+.sp-call-bar-wrap{flex:1;background:#0f172a;border-radius:2px;height:6px;overflow:hidden}
+.sp-call-bar{background:#3b82f6;height:100%;border-radius:2px;min-width:2px}
+.sp-call-toks{font-size:11px;color:#94a3b8;flex-shrink:0;width:60px;text-align:right}
+.sp-io-row{display:flex;gap:6px}
+.sp-io-box{flex:1;background:#0f172a;border:1px solid #334155;border-radius:5px;padding:8px 10px;text-align:center}
+.sp-io-val{font-size:18px;font-weight:700;color:#f1f5f9}.sp-io-lbl{font-size:10px;color:#64748b;margin-top:2px;text-transform:uppercase;letter-spacing:.05em}
 </style>
 </head>
 <body>
@@ -63,6 +91,7 @@ select:hover,button:hover{background:#475569}
     </select>
     <button id="btn-fit" title="Fit graph to viewport">\u229f Fit</button>
     <button id="btn-png" title="Download as PNG">\u2193 PNG</button>
+${sessionData ? `    <button id="btn-session" title="View session stats">\u26a1 Session</button>` : ''}
   </div>
 </div>
 <div id="main">
@@ -74,6 +103,16 @@ select:hover,button:hover{background:#475569}
     </div>
     <div id="sb-body"></div>
   </div>
+${sessionData
+        ? `  <div id="session-panel">
+    <div id="sp-head">
+      <span id="sp-title">\u26a1 Session</span>
+      <span id="sp-agents">${sessionData.activeAgents.length ? sessionData.activeAgents.join(' \xb7 ') : 'session recorded'}</span>
+      <button id="sp-close2" title="Close">\u00d7</button>
+    </div>
+    <div id="sp-body"></div>
+  </div>`
+        : ''}
 </div>
 <div id="legend">
   <span class="li-head">Files</span>
@@ -294,6 +333,8 @@ select:hover,button:hover{background:#475569}
     document.getElementById('sb-type').textContent = d.type === 'atom' ? 'Knowledge Atom' : 'File';
     document.getElementById('sb-body').innerHTML = d.type === 'atom' ? renderAtomPanel(d) : renderFilePanel(d);
     document.getElementById('sidebar').classList.add('open');
+    var sp = document.getElementById('session-panel');
+    if (sp) { sp.classList.remove('open'); var sb = document.getElementById('btn-session'); if (sb) { sb.classList.remove('active'); sessionPanelOpen = false; } }
   });
 
   cy.on('tap', function (evt) {
@@ -337,6 +378,83 @@ select:hover,button:hover{background:#475569}
     a.click();
     document.body.removeChild(a);
   });
+${safeSessionData
+        ? `
+  var SESSION_DATA = ${safeSessionData};
+  var sessionRendered = false;
+  var sessionPanelOpen = false;
+
+  function fmt(n) {
+    return n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n);
+  }
+
+  function renderSessionPanel() {
+    var d = SESSION_DATA;
+    var total = d.totalPackUsedTokens + d.totalPackOmittedTokens;
+    var filterRate = total > 0 ? Math.round((d.totalPackOmittedTokens / total) * 100) : 0;
+    var avgToks = d.packCallCount > 0 ? Math.round(d.totalPackUsedTokens / d.packCallCount) : 0;
+    var filterCell = filterRate > 0
+      ? '<div class="sp-metric"><div class="sp-metric-val accent">' + filterRate + '%</div><div class="sp-metric-lbl">Filtered</div></div>'
+      : '<div class="sp-metric"><div class="sp-metric-val" style="font-size:11px;color:#475569;line-height:1.4">None</div><div class="sp-metric-lbl">Filtered</div></div>';
+    var summaryHtml =
+      '<div class="sp-summary">' +
+      '<div class="sp-metric"><div class="sp-metric-val">' + d.packCallCount + '</div><div class="sp-metric-lbl">Pack calls</div></div>' +
+      '<div class="sp-metric"><div class="sp-metric-val accent">' + fmt(d.totalPackUsedTokens) + '</div><div class="sp-metric-lbl">Tokens used</div></div>' +
+      '<div class="sp-metric"><div class="sp-metric-val">' + fmt(avgToks) + '</div><div class="sp-metric-lbl">Avg / call</div></div>' +
+      filterCell +
+      '</div>';
+    var maxUsed = 0;
+    d.contextEvents.forEach(function (e) { if ((e.packUsedTokens || 0) > maxUsed) maxUsed = e.packUsedTokens || 0; });
+    var callRows = '';
+    if (d.contextEvents.length > 0) {
+      callRows = '<div><div class="sp-group-lbl">Pack calls (' + d.contextEvents.length + ')</div>';
+      d.contextEvents.forEach(function (e) {
+        var used = e.packUsedTokens || 0;
+        var filt = e.packOmittedTokens || 0;
+        var barPct = maxUsed > 0 ? Math.round(used / maxUsed * 100) : 100;
+        var ts = e.timestamp ? new Date(e.timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '';
+        var filtLabel = filt > 0 ? ' <span style="color:#ef4444">-' + fmt(filt) + '</span>' : '';
+        callRows +=
+          '<div class="sp-call-row">' +
+          '<span class="sp-call-time">' + esc(ts) + '</span>' +
+          '<div class="sp-call-bar-wrap"><div class="sp-call-bar" style="width:' + barPct + '%"></div></div>' +
+          '<span class="sp-call-toks">' + fmt(used) + filtLabel + '</span>' +
+          '</div>';
+      });
+      callRows += '</div>';
+    }
+    var ioHtml =
+      '<div><div class="sp-group-lbl">File access</div>' +
+      '<div class="sp-io-row">' +
+      '<div class="sp-io-box"><div class="sp-io-val">' + d.readCount + '</div><div class="sp-io-lbl">Reads</div></div>' +
+      '<div class="sp-io-box"><div class="sp-io-val">' + d.writeCount + '</div><div class="sp-io-lbl">Writes</div></div>' +
+      '</div></div>';
+    document.getElementById('sp-body').innerHTML = summaryHtml + callRows + ioHtml;
+  }
+
+  document.getElementById('btn-session').addEventListener('click', function () {
+    var panel = document.getElementById('session-panel');
+    sessionPanelOpen = !sessionPanelOpen;
+    if (sessionPanelOpen) {
+      panel.classList.add('open');
+      this.classList.add('active');
+      if (!sessionRendered) {
+        renderSessionPanel();
+        sessionRendered = true;
+      }
+    } else {
+      panel.classList.remove('open');
+      this.classList.remove('active');
+    }
+  });
+
+  document.getElementById('sp-close2').addEventListener('click', function () {
+    document.getElementById('session-panel').classList.remove('open');
+    document.getElementById('btn-session').classList.remove('active');
+    sessionPanelOpen = false;
+  });
+`
+        : ''}
 })();
 </script>
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {