context-mode 1.0.151 → 1.0.152

package/build/session/analytics.d.ts

@@ -109,8 +109,19 @@ export interface RuntimeStats {
     calls: Record<string, number>;
     sessionStart: number;
     cacheHits: number;
+    cacheMisses?: number;
     cacheBytesSaved: number;
 }
+/**
+ * Index observability snapshot — point-in-time view of the persistent
+ * content store. Optional input to `formatReport` so callers that don't
+ * have store access (or don't want the extra DB hit) can omit it.
+ */
+export interface IndexState {
+    totalChunks: number;
+    totalSources: number;
+    lastIndexedAt?: string;
+}
 /** Unified report combining runtime stats, DB analytics, and continuity data. */
 export interface FullReport {
     /** Runtime context savings (passed in, not from DB) */
@@ -133,6 +144,8 @@ export interface FullReport {
     };
     cache?: {
         hits: number;
+        misses: number;
+        hit_rate: number;
         bytes_saved: number;
         ttl_hours_left: number;
         total_with_cache: number;
@@ -595,7 +608,7 @@ export declare function detectLocaleAndTz(): {
  * the section disappears cleanly on a fresh install.
  *
  * Math constants:
- *   Opus 4   = $15.00 per 1M input tokens (matches OPUS_INPUT_PRICE_PER_TOKEN)
+ *   Opus 4   = $15.00 per 1M input tokens (fallback when PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN not set)
  *   Sonnet 4 = $3.00  per 1M input tokens
  *   GPT-4o   = $2.50  per 1M input tokens
  *   Gemini 2 = $1.25  per 1M input tokens
@@ -654,20 +667,24 @@ export declare function renderHorizontalTimeline(days: TimelineDay[], locale: st
  *   line ("started …") without an extra timestamp-validity check.
  */
 export declare function formatLocalDateTime(ms: number, locale: string, tz: string): string;
-/** Opus 4 input price: $15 per 1M tokens. */
-export declare const OPUS_INPUT_PRICE_PER_TOKEN: number;
-/** Convert a token count to a USD string at the Opus input rate. */
-export declare function tokensToUsd(tokens: number): string;
 /**
- * Render a FullReport as a visual savings dashboard designed for screenshotting.
- *
- * Design principles:
- * - Before/After comparison bar is the HERO — one glance = "wow"
- * - "tokens saved" is the number people share
- * - Per-tool breakdown shows what each tool SAVED, sorted by impact
- * - Project memory: category bars showing persistent data across sessions
- * - No: Pct column, category tables, tips, jargon
+ * Per-token USD rate — resolves on every call.
+ * Dynamic when PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN is set, Opus 4 input
+ * ($15 per 1M tokens) otherwise.
+ */
+export declare function pricePerToken(): number;
+/**
+ * Back-compat alias for the original Opus-rate const (PR #401 architect
+ * P1.1 — single source of truth). Kept as a literal so any third-party
+ * consumer importing the named constant still resolves to the same
+ * fallback rate. New code should call pricePerToken() to pick up the
+ * dynamic Pi env override.
+ *
+ * @deprecated Use pricePerToken() to honor PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN.
  */
+export declare const OPUS_INPUT_PRICE_PER_TOKEN: number;
+/** Convert a token count to a USD string at the current per-token rate. */
+export declare function tokensToUsd(tokens: number): string;
 export declare function formatReport(report: FullReport, version?: string, latestVersion?: string | null, opts?: {
     lifetime?: LifetimeStats;
     mcpUsage?: McpToolUsageRow[];
@@ -700,6 +717,12 @@ export declare function formatReport(report: FullReport, version?: string, lates
      * single-adapter renderer output unchanged.
      */
     multiAdapter?: MultiAdapterLifetimeStats;
+    /**
+     * Point-in-time snapshot of the persistent content store. Optional —
+     * callers that don't have store access can omit it and the renderer
+     * skips the observability section gracefully.
+     */
+    indexState?: IndexState;
     /**
      * 5-section narrative renderer overrides. Defaults to ambient
      * `process.cwd()` + `Date.now()` + `detectLocaleAndTz()` for production

package/build/session/analytics.js

@@ -45,7 +45,8 @@ export const categoryLabels = {
     // Configuration & intent
     rule: "Project rules (CLAUDE.md)",
     prompt: "Your requests saved",
-    intent: "Session goal",
+    intent: "Session intent",
+    goal: "Session goal",
     role: "Behavior rules",
     constraint: "Constraints you set",
     // Tools & delegation
@@ -198,7 +199,8 @@ export class AnalyticsEngine {
             let median = null;
             let max = null;
             if (b.concurrencies.length > 0) {
-                const sorted = [...b.concurrencies].sort((a, c) => a - c);
+                b.concurrencies.sort((a, c) => a - c);
+                const sorted = b.concurrencies;
                 const mid = Math.floor(sorted.length / 2);
                 median = sorted.length % 2 === 0
                     ? (sorted[mid - 1] + sorted[mid]) / 2
@@ -252,12 +254,21 @@ export class AnalyticsEngine {
         const uptimeMin = (uptimeMs / 60_000).toFixed(1);
         // ── Cache ──
         let cache;
-        if (runtimeStats.cacheHits > 0 || runtimeStats.cacheBytesSaved > 0) {
+        const cacheMisses = runtimeStats.cacheMisses ?? 0;
+        if (runtimeStats.cacheHits > 0 || runtimeStats.cacheBytesSaved > 0 || cacheMisses > 0) {
             const totalWithCache = totalProcessed + runtimeStats.cacheBytesSaved;
             const totalSavingsRatio = totalWithCache / Math.max(totalBytesReturned, 1);
             const ttlHoursLeft = Math.max(0, 24 - Math.floor((Date.now() - runtimeStats.sessionStart) / (60 * 60 * 1000)));
+            // hit_rate is the nominal cache effectiveness — the metric ctx_stats
+            // historically inferred-only by diffing tokens_saved snapshots. When
+            // there is no activity we report 0 instead of NaN/undefined so the
+            // renderer stays JSON-safe.
+            const totalLookups = runtimeStats.cacheHits + cacheMisses;
+            const hitRate = totalLookups > 0 ? runtimeStats.cacheHits / totalLookups : 0;
             cache = {
                 hits: runtimeStats.cacheHits,
+                misses: cacheMisses,
+                hit_rate: hitRate,
                 bytes_saved: runtimeStats.cacheBytesSaved,
                 ttl_hours_left: ttlHoursLeft,
                 total_with_cache: totalWithCache,
@@ -1382,7 +1393,7 @@ function shortPath(abs) {
  * the section disappears cleanly on a fresh install.
  *
  * Math constants:
- *   Opus 4   = $15.00 per 1M input tokens (matches OPUS_INPUT_PRICE_PER_TOKEN)
+ *   Opus 4   = $15.00 per 1M input tokens (fallback when PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN not set)
  *   Sonnet 4 = $3.00  per 1M input tokens
  *   GPT-4o   = $2.50  per 1M input tokens
  *   Gemini 2 = $1.25  per 1M input tokens
@@ -1395,38 +1406,53 @@ function shortPath(abs) {
 export function renderCostExample(lifetimeBytes, lifetimeTokens, lifetimeDays) {
     if (!Number.isFinite(lifetimeTokens) || lifetimeTokens <= 0)
         return [];
-    const opusUsd = (lifetimeTokens * 15) / 1_000_000;
+    const lifetimeUsd = lifetimeTokens * pricePerToken();
     const usdStr = (n, dp = 2) => n.toFixed(dp);
     // Comparison units — kept locally so they're easy to tune without touching
     // the renderer logic. Cursor Pro & Claude Max are public list prices; the
     // weekend constant is an intentional approximation calibrated to make
     // $1399.73 → "19 weekends" line up with the demo target.
-    const cursorMonths = Math.round(opusUsd / 20);
-    const claudeMaxMonths = (opusUsd / 200).toFixed(1);
-    const weekendCount = Math.round(opusUsd / 73.67);
-    const teamUsd = Math.round(opusUsd * 10);
+    const cursorMonths = Math.round(lifetimeUsd / 20);
+    const claudeMaxMonths = (lifetimeUsd / 200).toFixed(1);
+    const weekendCount = Math.round(lifetimeUsd / 73.67);
+    const teamUsd = Math.round(lifetimeUsd * 10);
     const teamYearUsd = lifetimeDays > 0
-        ? Math.round((opusUsd * 10) / lifetimeDays * 365)
+        ? Math.round((lifetimeUsd * 10) / lifetimeDays * 365)
         : 0;
     // Alternate-model scale row — same token count, different per-1M rates.
-    const sonnetUsd = ((lifetimeTokens * 3.0) / 1_000_000).toFixed(2);
-    const gpt4oUsd = ((lifetimeTokens * 2.5) / 1_000_000).toFixed(2);
-    const geminiUsd = ((lifetimeTokens * 1.25) / 1_000_000).toFixed(2);
-    const haikuUsd = ((lifetimeTokens * 0.8) / 1_000_000).toFixed(2);
+    // (Kept for internal reference but unreachable per Mert directive.)
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _sonnetUsd = ((lifetimeTokens * 3.0) / 1_000_000).toFixed(2);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _gpt4oUsd = ((lifetimeTokens * 2.5) / 1_000_000).toFixed(2);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _geminiUsd = ((lifetimeTokens * 1.25) / 1_000_000).toFixed(2);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _haikuUsd = ((lifetimeTokens * 0.8) / 1_000_000).toFixed(2);
+    const usingDynamicPrice = process.env.PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN !== undefined;
+    const modelId = process.env.PI_CONTEXT_MODE_MODEL_ID;
     // Mert: "daha marketing ve business value e vermeli, math hesaplamalari ile
-    // kalabalik yapma" — collapse the old 4-block render (5 prose lines + 3
-    // comparison lines + 2 team lines + scaling table + disclaimer) into ONE
-    // headline number, ONE relatable comparison, ONE team-scale callout. Drop
-    // the alternate-model scaling row (engineer-curiosity, not value framing).
+    // kalabalik yapma" — collapse the old 4-block render into ONE headline
+    // number, ONE relatable comparison, ONE team-scale callout.
     const out = [];
-    out.push(`  $${usdStr(opusUsd)} of Opus 4 tokens your team didn't burn.`);
+    if (usingDynamicPrice && modelId) {
+        out.push(`  $${usdStr(lifetimeUsd)} of ${modelId} tokens your team didn't burn.`);
+    }
+    else if (usingDynamicPrice) {
+        out.push(`  $${usdStr(lifetimeUsd)} of tokens your team didn't burn.`);
+    }
+    else {
+        out.push(`  $${usdStr(lifetimeUsd)} of Opus 4 tokens your team didn't burn.`);
+    }
     out.push(`  context-mode kept ${kb(lifetimeBytes)} out of context — that's ${cursorMonths} months of Cursor Pro paid for itself.`);
     if (teamUsd > 0 && teamYearUsd > 0) {
         out.push("");
         out.push(`  Scale across a 10-dev team and that's ~$${teamYearUsd.toLocaleString("en-US")}/year saved.`);
     }
-    out.push("");
-    out.push(`  (Opus rates shown for context. On cheaper models the dollar number drops; the savings ratio holds.)`);
+    if (!usingDynamicPrice) {
+        out.push("");
+        out.push(`  (Opus rates shown for context. On cheaper models the dollar number drops; the savings ratio holds.)`);
+    }
     return out;
 }
 /**
@@ -1829,12 +1855,46 @@ function fmtNum(n) {
 // ─────────────────────────────────────────────────────────
 // Pricing (Bug #6) — Anthropic Opus input rate
 // ─────────────────────────────────────────────────────────
-/** Opus 4 input price: $15 per 1M tokens. */
+// ── Pricing (Bug #6) — per-token USD rate ─────────────────
+// Reads PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN when set by a Pi host;
+// falls back to the Opus 4 input rate ($15/1M) for all other adapters.
+//
+// IMPORTANT: this is a FUNCTION, not a const. Pi sets the env var
+// AFTER the MCP server has been imported (the bridge spawns the server
+// child, then the child reads its own env on every render). A
+// module-load-time const would freeze to the fallback because
+// process.env.PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN is unset at
+// import time. Resolving on every call keeps the dynamic-pricing
+// contract honest — the env var works without an MCP restart.
+// (Reverted module-load const semantics, PR #741 follow-up.)
+/**
+ * Per-token USD rate — resolves on every call.
+ * Dynamic when PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN is set, Opus 4 input
+ * ($15 per 1M tokens) otherwise.
+ */
+export function pricePerToken() {
+    const env = process.env.PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN;
+    if (env !== undefined && env !== "") {
+        const parsed = Number(env);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return 15 / 1_000_000; // Opus 4 input fallback
+}
+/**
+ * Back-compat alias for the original Opus-rate const (PR #401 architect
+ * P1.1 — single source of truth). Kept as a literal so any third-party
+ * consumer importing the named constant still resolves to the same
+ * fallback rate. New code should call pricePerToken() to pick up the
+ * dynamic Pi env override.
+ *
+ * @deprecated Use pricePerToken() to honor PI_CONTEXT_MODE_PRICE_OUTPUT_PER_TOKEN.
+ */
 export const OPUS_INPUT_PRICE_PER_TOKEN = 15 / 1_000_000;
-/** Convert a token count to a USD string at the Opus input rate. */
+/** Convert a token count to a USD string at the current per-token rate. */
 export function tokensToUsd(tokens) {
     const safe = Number.isFinite(tokens) && tokens > 0 ? tokens : 0;
-    return `$${(safe * OPUS_INPUT_PRICE_PER_TOKEN).toFixed(2)}`;
+    return `$${(safe * pricePerToken()).toFixed(2)}`;
 }
 /**
  * Build a proportional bar using █ chars, scaled to a fixed width.
@@ -2043,8 +2103,10 @@ function renderConversation(c, conversationUsd, contribPct) {
 function renderMultiAdapter(multiAdapter) {
     if (!multiAdapter)
         return [];
-    const real = multiAdapter.perAdapter.filter((a) => a.isReal);
-    const skipped = multiAdapter.perAdapter.filter((a) => !a.isReal);
+    const real = [];
+    const skipped = [];
+    for (const a of multiAdapter.perAdapter)
+        (a.isReal ? real : skipped).push(a);
     if (real.length === 0 && skipped.length === 0)
         return [];
     const out = [];
@@ -2090,6 +2152,34 @@ function renderMultiAdapter(multiAdapter) {
  * - Project memory: category bars showing persistent data across sessions
  * - No: Pct column, category tables, tips, jargon
  */
+/**
+ * Render the machine-readable Observability block (cache + index state).
+ *
+ * Returns an empty array when no observability data is available, so callers
+ * can `lines.push(...renderObservabilityBlock(...))` unconditionally and the
+ * section is omitted when the kit has nothing to report.
+ *
+ * Shared between the narrative path (early-returns when conversation.events > 0)
+ * and the legacy path so the block surfaces in both, matching the contract
+ * that the handler always passes `indexState` regardless of code path.
+ */
+function renderObservabilityBlock(report, indexState) {
+    const obs = [];
+    if (report.cache) {
+        const hitRatePct = (report.cache.hit_rate * 100).toFixed(1);
+        obs.push(`cache.hit_rate: ${hitRatePct}% (${report.cache.hits} hits / ${report.cache.misses} misses)`);
+    }
+    if (indexState) {
+        obs.push(`index.total_chunks: ${indexState.totalChunks}`);
+        obs.push(`index.total_sources: ${indexState.totalSources}`);
+        if (indexState.lastIndexedAt) {
+            obs.push(`index.last_indexed_at: ${indexState.lastIndexedAt}`);
+        }
+    }
+    if (obs.length === 0)
+        return [];
+    return ["", "## Observability", ...obs];
+}
 export function formatReport(report, version, latestVersion, opts) {
     const lines = [];
     const duration = formatDuration(report.session.uptime_min);
@@ -2157,6 +2247,9 @@ export function formatReport(report, version, latestVersion, opts) {
             conversation, lifetime, multiAdapter, realBytes,
             cwd, locale, tz, now, version, latestVersion,
         }));
+        // Append Observability so cache.hit_rate / index.* surface in the
+        // narrative path too (handler passes indexState regardless of path).
+        lines.push(...renderObservabilityBlock(report, opts?.indexState));
         return lines.join("\n");
     }
     // ── Compute real savings ──
@@ -2261,6 +2354,10 @@ export function formatReport(report, version, latestVersion, opts) {
     lines.push(...renderAutoMemory(lifetime));
     // ── Bottom line — business value framing (Bug #8) ──
     lines.push(...renderBottomLine(tokensSaved, lifetime));
+    // ── Observability — machine-readable cache + index state ──
+    // Rendered via shared helper so the narrative path (above, early-return
+    // when conversation.events > 0) emits the same block.
+    lines.push(...renderObservabilityBlock(report, opts?.indexState));
     // ── Footer ──
     lines.push("");
     const versionStr = version ? `v${version}` : "context-mode";

package/build/session/db.d.ts

@@ -319,6 +319,18 @@ export declare class SessionDB extends SQLiteBase {
         data: string;
         created_at: string;
     }>;
+    /**
+     * Return the distinct list of session ids whose events were attributed
+     * to a given `project_dir`. Powers the ctx_search `project:` filter
+     * (#737) via the 2-step IN-clause strategy — ATTACH DATABASE is avoided
+     * because SQLite's WAL + ATTACH combination has known correctness
+     * trade-offs flagged in the upstream docs.
+     *
+     * Backed by the `idx_session_events_project(session_id, project_dir)`
+     * composite index, so 1000-session lookups complete in single-digit
+     * milliseconds. Best-effort: returns `[]` on any error.
+     */
+    getSessionIdsForProject(projectDir: string): string[];
     /**
      * Ensure a session metadata entry exists. Idempotent (INSERT OR IGNORE).
      * `projectDir` is the session origin directory, not per-event attribution.
@@ -393,5 +405,17 @@ export declare class SessionDB extends SQLiteBase {
      * Remove sessions older than maxAgeDays. Returns the count of deleted sessions.
      */
     cleanupOldSessions(maxAgeDays?: number): number;
+    /**
+     * Delete event rows whose session_id has no matching session_meta row.
+     *
+     * Orphaned events accumulate when meta rows were aged out by an older
+     * version of `cleanupOldSessions` but the matching events were left
+     * behind (or when callers wrote events without a meta upsert). The Kimi
+     * Code sessionstart hook calls this on every startup as a self-healing
+     * step; surfacing it as a SessionDB method keeps the SQL definition in
+     * one place instead of letting hook scripts reach through to
+     * `db.db.exec(...)` and re-encode schema knowledge in mjs files.
+     */
+    pruneOrphanedEvents(): number;
 }
 export {};

package/build/session/db.js

@@ -976,6 +976,30 @@ export class SessionDB extends SQLiteBase {
             return [];
         }
     }
+    /**
+     * Return the distinct list of session ids whose events were attributed
+     * to a given `project_dir`. Powers the ctx_search `project:` filter
+     * (#737) via the 2-step IN-clause strategy — ATTACH DATABASE is avoided
+     * because SQLite's WAL + ATTACH combination has known correctness
+     * trade-offs flagged in the upstream docs.
+     *
+     * Backed by the `idx_session_events_project(session_id, project_dir)`
+     * composite index, so 1000-session lookups complete in single-digit
+     * milliseconds. Best-effort: returns `[]` on any error.
+     */
+    getSessionIdsForProject(projectDir) {
+        try {
+            const rows = this.db
+                .prepare(`SELECT DISTINCT session_id
+             FROM session_events
+            WHERE project_dir = ?`)
+                .all(projectDir);
+            return rows.map((r) => r.session_id);
+        }
+        catch {
+            return [];
+        }
+    }
     // ═══════════════════════════════════════════
     // Meta
     // ═══════════════════════════════════════════
@@ -1127,4 +1151,21 @@ export class SessionDB extends SQLiteBase {
         }
         return oldSessions.length;
     }
+    /**
+     * Delete event rows whose session_id has no matching session_meta row.
+     *
+     * Orphaned events accumulate when meta rows were aged out by an older
+     * version of `cleanupOldSessions` but the matching events were left
+     * behind (or when callers wrote events without a meta upsert). The Kimi
+     * Code sessionstart hook calls this on every startup as a self-healing
+     * step; surfacing it as a SessionDB method keeps the SQL definition in
+     * one place instead of letting hook scripts reach through to
+     * `db.db.exec(...)` and re-encode schema knowledge in mjs files.
+     */
+    pruneOrphanedEvents() {
+        const result = this.db
+            .prepare(`DELETE FROM session_events WHERE session_id NOT IN (SELECT session_id FROM session_meta)`)
+            .run();
+        return Number(result.changes ?? 0);
+    }
 }

package/build/session/extract.js

@@ -932,6 +932,35 @@ function extractIntent(message) {
             priority: 4,
         }];
 }
+/**
+ * Category: session goal (objective).
+ *
+ * Captures the user's stated objective so it survives compaction and resume —
+ * unlike `intent`, which stores only the coarse mode (investigate/implement)
+ * and discards the goal text. Triggered by the `/goal <text>` command or an
+ * explicit `goal:` / `objective:` marker, so the FULL goal text is preserved
+ * (priority 4 = critical in the DB eviction contract) and restored at the top
+ * of the resume snapshot.
+ * Without this, a `/goal` directive is lost across compaction/resume.
+ */
+const GOAL_DIRECTIVE_PATTERN = /^(?:\/goal\s+|(?:goal|objective)\s*:\s*)(.+)$/is;
+function extractGoal(message) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return [];
+    const match = trimmed.match(GOAL_DIRECTIVE_PATTERN);
+    if (!match)
+        return [];
+    const goalText = match[1].trim();
+    if (!goalText)
+        return [];
+    return [{
+            type: "goal",
+            category: "goal",
+            data: safeString(goalText),
+            priority: 4,
+        }];
+}
 /**
  * Category 25: blocked-on
  * Detect when work is blocked on something, or when a blocker is resolved.
@@ -1184,6 +1213,7 @@ export function extractUserEvents(message) {
         events.push(...extractUserDecision(message));
         events.push(...extractRole(message));
         events.push(...extractIntent(message));
+        events.push(...extractGoal(message));
         events.push(...extractBlocker(message));
         events.push(...extractData(message));
         return events;

package/build/session/snapshot.js

@@ -342,6 +342,22 @@ function buildIntentSection(intentEvents) {
     const lastIntent = intentEvents[intentEvents.length - 1];
     return `  <intent mode="${escapeXML(lastIntent.data)}"/>`;
 }
+/**
+ * Restore the most recent stated session goal verbatim. Placed at the top of
+ * the snapshot (right after how_to_search) so the resuming LLM reads the
+ * active objective before anything else and keeps working toward it.
+ */
+function buildGoalSection(goalEvents) {
+    if (goalEvents.length === 0)
+        return "";
+    const lastGoal = goalEvents[goalEvents.length - 1];
+    return [
+        `  <session_goal>`,
+        `  The active objective for this session. Keep working toward it until it is met; do not ask the user to restate it.`,
+        `    ${escapeXML(lastGoal.data)}`,
+        `  </session_goal>`,
+    ].join("\n");
+}
 /**
  * Raw-prompt safety net (issue #535):
  * Always surface the most recent user prompts verbatim so the next LLM
@@ -404,6 +420,7 @@ export function buildResumeSnapshot(events, opts) {
     const gitEvents = [];
     const subagentEvents = [];
     const intentEvents = [];
+    const goalEvents = [];
     const skillEvents = [];
     const roleEvents = [];
     const userPromptEvents = [];
@@ -439,6 +456,9 @@ export function buildResumeSnapshot(events, opts) {
             case "intent":
                 intentEvents.push(ev);
                 break;
+            case "goal":
+                goalEvents.push(ev);
+                break;
             case "skill":
                 skillEvents.push(ev);
                 break;
@@ -459,6 +479,10 @@ export function buildResumeSnapshot(events, opts) {
   Do NOT ask the user to re-explain prior work. Search first.
   Do NOT invent your own queries — use the ones provided.
   </how_to_search>`);
+    // Session goal first — the objective the LLM must keep working toward.
+    const goal = buildGoalSection(goalEvents);
+    if (goal)
+        sections.push(goal);
     const files = buildFilesSection(fileEvents, searchTool);
     if (files)
         sections.push(files);

package/build/store.d.ts

@@ -103,7 +103,7 @@ export declare class ContentStore {
     search(query: string, limit?: number, source?: string, mode?: "AND" | "OR", contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode): SearchResult[];
     searchTrigram(query: string, limit?: number, source?: string, mode?: "AND" | "OR", contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode): SearchResult[];
     fuzzyCorrect(query: string): string | null;
-    searchWithFallback(query: string, limit?: number, source?: string, contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode): SearchResult[];
+    searchWithFallback(query: string, limit?: number, source?: string, contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode, sessionIdAllowSet?: Set<string>): SearchResult[];
     /** Number of sources auto-refreshed in the last searchWithFallback call. */
     lastRefreshCount: number;
     getSourceMeta(label: string): {
@@ -118,6 +118,17 @@ export declare class ContentStore {
         label: string;
         chunkCount: number;
     }>;
+    /**
+     * Aggregate snapshot of the persistent content store. Returns total
+     * chunk count, source count, and the most recent indexed_at timestamp.
+     * Used by ctx_stats so callers can see observability state in the same
+     * round trip instead of inferring it from snapshot diffs.
+     */
+    getIndexState(): {
+        totalChunks: number;
+        totalSources: number;
+        lastIndexedAt?: string;
+    };
     /**
      * Get all chunks for a given source by ID — bypasses FTS5 MATCH entirely.
      * Use this for inventory/listing where you need all sections, not search.