pi-mega-compact 0.20.3 → 0.20.5

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -15,6 +15,7 @@ import {
 	fetchVectorCortexQuery,
 	fetchVectorCortexReconstruct,
 	fetchVectorCortexPlans,
+	fetchVectorCortexRender,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
@@ -24,11 +25,15 @@ import {
 	type VectorCortexQueryView,
 	type VectorCortexReconstructView,
 	type VectorCortexPlansView,
+	type VectorCortexRenderView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
 import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
 import { Badge } from "../components/ui/badge";
+import { Metric } from "./VectorCortexMetric";
+import { VectorCortexRenderCard } from "./VectorCortexRenderCard";
+import { VectorCortexPlansCard } from "./VectorCortexPlansCard";
 
 function ModeChip({ mode, count }: { mode: string; count: number }): React.ReactElement {
 	return (
@@ -39,15 +44,6 @@ function ModeChip({ mode, count }: { mode: string; count: number }): React.React
 	);
 }
 
-function Metric({ label, value }: { label: string; value: string }): React.ReactElement {
-	return (
-		<div>
-			<div className="text-xs text-muted-foreground">{label}</div>
-			<div className="font-mono text-sm">{value}</div>
-		</div>
-	);
-}
-
 export default function VectorCortexTab(): React.ReactElement {
 	const [data, setData] = useState<VectorCortexEvaluationSummary | null>(null);
 	const [err, setError] = useState<string | null>(null);
@@ -60,6 +56,7 @@ export default function VectorCortexTab(): React.ReactElement {
 	const [shards, setShards] = useState<VectorCortexShardsView | null>(null);
 	const [reconstruct, setReconstruct] = useState<VectorCortexReconstructView | null>(null);
 	const [plans, setPlans] = useState<VectorCortexPlansView | null>(null);
+	const [render, setRender] = useState<VectorCortexRenderView | null>(null);
 
 	const poll = useCallback(() => {
 		fetchVectorCortexEvaluation()
@@ -89,6 +86,9 @@ export default function VectorCortexTab(): React.ReactElement {
 		fetchVectorCortexPlans().then(setPlans).catch(() => {
 			/* plan manifest card is best-effort (VC5A) */
 		});
+		fetchVectorCortexRender().then(setRender).catch(() => {
+			/* render conformance card is best-effort (VC5B) */
+		});
 	}, []);
 
 	useEffect(() => {
@@ -403,35 +403,8 @@ export default function VectorCortexTab(): React.ReactElement {
 					)}
 				</CardContent>
 			</Card>
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Plan Manifests (VC5A)</CardTitle>
-						{plans?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-					</div>
-				</CardHeader>
-				<CardContent>
-					{!plans?.enabled ? (
-						<div className="vc-empty">PromptDagV1 + budgeted planner disabled (VC5A off).</div>
-					) : (
-					<>
-						<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-							<Metric label="DAG fixtures" value={String(plans.dagCount)} />
-							<Metric label="Plan fixtures" value={String(plans.plannerCount)} />
-							<Metric label="Plans exposed" value={String(plans.plans.length)} />
-						</div>
-						<div className="mt-3 text-xs text-muted-foreground">
-							Reader-only plan manifests only — no session payloads or prompt text.
-							Per-run plan outputs are staged in-memory this sprint.
-						</div>
-					</>
-					)}
-				</CardContent>
-			</Card>
+			<VectorCortexPlansCard view={plans} />
+			<VectorCortexRenderCard view={render} />
 			<Card>
 				<CardHeader>
 					<div className="flex items-center justify-between">

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -182,3 +182,12 @@ export interface VectorCortexPlansView {
   plans: VectorCortexPlanManifest[];
   updatedAt: string;
 }
+
+/** Reader-only render + provider-profile view (VC5B). */
+export interface VectorCortexRenderView {
+  enabled: boolean;
+  renderCount: number;
+  providerCount: number;
+  knownProfiles: string[];
+  updatedAt: string;
+}

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -296,6 +296,26 @@ export interface VectorCortexPlansView {
   readonly updatedAt: string;
 }
 
+/**
+ * Reader-only render/profile view for GET /api/vector-cortex/render (VC5B).
+ * Reports the registered render (REN-001..) and provider-profile (PRO-001..)
+ * identifier counts + the known provider-profile keys. NEVER exposes rendered
+ * node bytes, prompt text, or the canonical outbound request (reader-only,
+ * SECURITY_PRIVACY: the exact ledger is not training data).
+ */
+export interface VectorCortexRenderView {
+  /** Whether the VC5B render + provider-profile flag is enabled. */
+  readonly enabled: boolean;
+  /** Count of registered render fixtures (REN-001..). */
+  readonly renderCount: number;
+  /** Count of registered provider-profile fixtures (PRO-001..). */
+  readonly providerCount: number;
+  /** Known base provider-profile keys (provider//model), reader-only. */
+  readonly knownProfiles: readonly string[];
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
 /**
  * Reader-only occurrence-ledger view for GET /api/vector-cortex/ledger (VC1B).
  * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -373,6 +373,12 @@ export const SETTINGS: ReadonlyArray<{
 				"Single-session DAG (PromptDagV1) + budgeted 0/1 portfolio planner: builds a stable Kahn-ordered DAG, computes the mandatory dependency/tool/anchor closure before optional selection, returns MANDATORY_CLOSURE_OVER_BUDGET with evidence preserved on overflow, and runs a utility-per-token portfolio that never exceeds the remaining budget. Framing is owned here, not in VC4C. OFF = byte-identical predecessor (VC4C).",
 				true,
 			),
+			boolDirect(
+				"MEGACOMPACT_VC5B",
+				"VC5B Validated Renderer + Provider Profiles",
+				"Validated prompt renderer: replays VC5A's stable Kahn order verbatim, preserves exact tool bytes (PREVENT-PI-002), places compacted context via the host before_agent_start prepend seam — never role:system (PREVENT-PI-003) — and SHA-256 hashes the entire canonical outbound request before provider invocation. Unknown provider/model cleanly bypasses to the predecessor prompt path. OFF = byte-identical predecessor (VC5A).",
+				true,
+			),
 		],
 	},
 	{

package/extensions/dashboard-server/routes-vector-cortex-render.ts

@@ -0,0 +1,49 @@
+/**
+ * dashboard-server/routes-vector-cortex-render.ts — VC5B render + provider-profile
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/render returning the registered render
+ * (REN-001..020) and provider-profile (PRO-001..015) identifier counts plus the
+ * known base provider-profile keys. NEVER exposes rendered node bytes, prompt
+ * text, or the canonical outbound request (reader-only, SECURITY_PRIVACY).
+ * Flag-gated on MEGACOMPACT_VC5B: `enabled:false` when off (byte-identical to
+ * the pre-VC5B predecessor).
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + profile keys only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC5B_ENABLED } from "../../src/config.js";
+import { REN_IDS } from "../../src/vector-cortex/render/types.js";
+import { PRO_IDS } from "../../src/vector-cortex/provider/types.js";
+import { KNOWN_PROVIDER_KEYS } from "../../src/vector-cortex/provider/registry.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexRenderView } from "./api-contracts/vector-cortex.js";
+
+/** Reader-only GET /api/vector-cortex/render (VC5B). */
+export function handleVectorCortexRender(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/render") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC5B_ENABLED();
+  const body: VectorCortexRenderView = {
+    enabled,
+    renderCount: enabled ? REN_IDS.length : 0,
+    providerCount: enabled ? PRO_IDS.length : 0,
+    knownProfiles: enabled ? KNOWN_PROVIDER_KEYS : [],
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes-vector-cortex.ts

@@ -23,3 +23,4 @@ export { handleVectorCortexShards } from "./routes-vector-cortex-shards.js";
 export { handleVectorCortexResidual } from "./routes-vector-cortex-residual.js";
 export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruct.js";
 export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";
+export { handleVectorCortexRender } from "./routes-vector-cortex-render.js";

package/extensions/dashboard-server/routes.ts

@@ -51,4 +51,5 @@ export {
 	handleVectorCortexResidual,
 	handleVectorCortexReconstruct,
 	handleVectorCortexPlans,
+	handleVectorCortexRender,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -67,6 +67,7 @@ import {
 	handleVectorCortexResidual,
 	handleVectorCortexReconstruct,
 	handleVectorCortexPlans,
+	handleVectorCortexRender,
 	handleStatic,
 } from "./routes.js";
 
@@ -236,15 +237,16 @@ export async function launchDashboardServer(
 		detectCrossRepoDrift,
 	});
 
-	// Bind host resolution: explicit MEGACOMPACT_DASHBOARD_HOST override wins;
-	// otherwise auto-bind to the Tailscale interface (tailnet access); fall back
-	// to loopback when Tailscale is absent. 0.0.0.0 means "all interfaces" and
-	// opts into permissive CORS below.
-	const host =
-		process.env.MEGACOMPACT_DASHBOARD_HOST ??
-		detectTailscaleIP() ??
-		"127.0.0.1";
+	// Bind host resolution. Default: ALL interfaces (0.0.0.0) so the dashboard
+	// is reachable on loopback (localhost — the launcher's health check + the
+	// local browser), the tailnet (Tailscale), and any LAN interface. The
+	// network-denial gate was removed (the user opted into open access);
+	// MEGACOMPACT_DASHBOARD_HOST overrides for anyone who wants to restrict to
+	// a single interface. The tailnet IP is still detected so we can surface it
+	// as the remote access address. 0.0.0.0 opts into permissive CORS below.
+	const host = process.env.MEGACOMPACT_DASHBOARD_HOST ?? "0.0.0.0";
 	const allInterfaces = host === "0.0.0.0";
+	const tailscaleIP = allInterfaces ? detectTailscaleIP() : null;
 
 	// guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard server (tailnet-local via Tailscale mesh or loopback); no remote outbound calls.
 	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
@@ -312,6 +314,7 @@ export async function launchDashboardServer(
 		if (handleVectorCortexResidual(req, res, ctx)) return;
 		if (handleVectorCortexReconstruct(req, res, ctx)) return;
 		if (handleVectorCortexPlans(req, res, ctx)) return;
+		if (handleVectorCortexRender(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 
@@ -336,27 +339,33 @@ export async function launchDashboardServer(
 			});
 
 			server.listen(port, host, () => {
-				// When bound to the loopback, keep the legacy localhost URL so the
-				// user's browser (which resolves localhost → ::1 or 127.0.0.1) works.
-				// When bound to a tailnet/tailscale IP, surface that address instead.
+				// Surface localhost for local reach (the launcher health-checks
+				// localhost + the local browser uses it), and — when bound to all
+				// interfaces with a tailnet present — also surface the tailnet
+				// address for remote devices on the mesh.
+				const localUrl = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: dashboard URL (loopback/all-interfaces, user-opted open access)
+				const tailnetUrl =
+					allInterfaces && tailscaleIP ? `http://${tailscaleIP}:${port}` : null; // guardrails-allow PREVENT-PI-004: dashboard URL (tailnet, user-opted open access)
 				const url =
 					host === "127.0.0.1"
-						? `http://localhost:${port}`
-						: `http://${host}:${port}`; // guardrails-allow PREVENT-PI-004: dashboard URL (tailnet-local via Tailscale mesh or loopback)
-				log("server running", { url, host });
+						? localUrl
+						: tailnetUrl ?? `http://${host}:${port}`;
+				log("server running", { url, host, tailnetUrl });
 				// eslint-disable-next-line no-console
-				console.log(`[mega-compact] dashboard server running: ${url}`);
+				console.log(
+					`[mega-compact] dashboard server running: ${url}` +
+						(tailnetUrl ? ` (also ${localUrl})` : ""),
+				);
 
-				// v0.8.2: also bind the IPv6 loopback (::1) when bound to the IPv4
-				// loopback. On many systems `localhost` resolves to ::1 first (see
-				// /etc/hosts), so an IPv4-only bind makes the browser hit ::1:port and
-				// get connection refused. PREVENT-PI-004 (loopback-only) means BOTH
-				// 127.0.0.1 and ::1. When bound to a tailscale/0.0.0.0 host, we do NOT
-				// bind ::1 — the tailnet address is what the user reaches. Non-fatal:
+				// v0.8.2: also bind the IPv6 loopback (::1) when localhost must work.
+				// On many systems `localhost` resolves to ::1 first (see /etc/hosts),
+				// so an IPv4-only bind makes the browser hit ::1:port and get refused.
+				// Bind ::1 for the explicit loopback bind AND the all-interfaces bind
+				// (a browser resolving localhost → ::1 must still connect). Non-fatal:
 				// IPv4-only hosts or a ::1 already in use just skip the mirror.
 				let v6: ReturnType<typeof createServer> | undefined;
 				const v4Handler = server.listeners("request")[0];
-				if (host === "127.0.0.1" && v4Handler) {
+				if ((host === "127.0.0.1" || allInterfaces) && v4Handler) {
 					v6 = createServer((r, s) =>
 						(v4Handler as (a: IncomingMessage, b: ServerResponse) => void).call(
 							server,

package/extensions/mega-context/vector-cortex.ts

@@ -0,0 +1,163 @@
+/**
+ * mega-context/vector-cortex.ts — VC5B delegation seam (the sprint's production
+ * ownership: `extensions/mega-context/vector-cortex.ts`).
+ *
+ * This is the ONLY extension-side surface VC5B owns. It delegates to the pi-
+ * agnostic `src/vector-cortex/render` + `src/vector-cortex/provider` logic and
+ * wires the two structured events the sprint emits:
+ *   - `vector_cortex_render_validated`  — a render passed validation and will be
+ *     prepended via the host `before_agent_start` systemPrompt seam.
+ *   - `vector_cortex_provider_bypassed` — an unknown provider/profile forced a
+ *     clean bypass (triad C, the predecessor prompt path).
+ *
+ * GUARDRAIL PREVENT-PI-003 (critical): the rendered compacted context is placed
+ * via the host `before_agent_start` systemPrompt PREPEND seam — it is NEVER
+ * emitted as a `role:"system"` conversation message. The renderer returns a
+ * `RenderManifestV1`, not a raw system-role payload; this seam composes the
+ * manifest's prepend into `event.systemPrompt`.
+ *
+ * The context handler (extensions/mega-events/context-handler.ts) is 228 lines
+ * (already a delegate shell) and under the extension hard limit, so NO split was
+ * required — VC5B delegates from here rather than modifying that handler.
+ *
+ * Pi runtime adapter: imports only pi runtime types + the VC5B logic. Flag-gated
+ * on `VC5B_ENABLED()`; flag OFF is byte-identical to the predecessor (VC5A state
+ * — the DAG/plan path), so this seam returns the host's unmodified systemPrompt.
+ */
+
+import type { ExtensionAPI, ExtensionContext, BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+
+import { VC5B_ENABLED } from "../../src/config/vector-cortex.js";
+import { resolveProviderProfile } from "../../src/vector-cortex/provider/registry.js";
+import { renderPrompt } from "../../src/vector-cortex/render/renderer.js";
+import { validateRender } from "../../src/vector-cortex/render/validator.js";
+import type { RenderInput, RenderManifestV1, CanonicalOutboundRequest } from "../../src/vector-cortex/render/types.js";
+import type { ProviderProfileBundle } from "../../src/vector-cortex/provider/types.js";
+
+/** An injected emit callback — the same (event, fields) shape as the src seams. */
+export type VectorCortexEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The VC5B seam result handed back to the before_agent_start handler. */
+export interface VectorCortexRenderOutcome {
+  readonly validated: boolean;
+  readonly bypassed: boolean;
+  readonly manifest: RenderManifestV1 | null;
+  /** The text to prepend to the host systemPrompt (empty when not VC5B). */
+  readonly systemPromptPrepend: string;
+  readonly triad: "A" | "B" | "C";
+}
+
+/**
+ * Run the full VC5B render+validate pipeline. Returns a structured outcome the
+ * `before_agent_start` handler composes into the host systemPrompt. On a clean
+ * bypass (unknown profile) it emits `vector_cortex_provider_bypassed` and the
+ * host uses the predecessor prompt path (triad C). On a validated render it
+ * emits `vector_cortex_render_validated` (triad A).
+ *
+ * All emits are best-effort and non-fatal; the flag gates zero observability
+ * writes when OFF (byte-identical to predecessor).
+ */
+export function runVectorCortexRender(
+  input: RenderInput,
+  emit?: VectorCortexEmit,
+): VectorCortexRenderOutcome {
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    try {
+      if (VC5B_ENABLED()) emit?.(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+
+  const rendered = renderPrompt(input);
+  if (!rendered.ok) {
+    // Clean bypass (unknown profile) or a hard order mismatch. Bypass emits the
+    // provider-bypassed event and defers to the predecessor prompt path.
+    fire("vector_cortex_provider_bypassed", {
+      code: rendered.code,
+      triad: rendered.triad,
+    });
+    return {
+      validated: false,
+      bypassed: true,
+      manifest: null,
+      systemPromptPrepend: "",
+      triad: rendered.triad,
+    };
+  }
+
+  // Validate the canonical request BEFORE invocation. The profile at validation
+  // time must match the manifest profile (the UNIQUE injection swaps it → C).
+  const sourceToolBytes = new Map<string, string>();
+  for (const t of rendered.request.tools) sourceToolBytes.set(t.id, t.bytes);
+  const pinnedToolLengths = new Map<string, number>();
+  for (const t of rendered.request.tools) {
+    pinnedToolLengths.set(t.id, Buffer.byteLength(t.bytes, "utf8"));
+  }
+  const check = validateRender(
+    rendered.manifest,
+    rendered.request,
+    input.profile,
+    sourceToolBytes,
+    pinnedToolLengths,
+  );
+
+  if (!check.ok) {
+    fire("vector_cortex_provider_bypassed", {
+      code: check.code,
+      triad: check.triad,
+    });
+    return {
+      validated: false,
+      bypassed: true,
+      manifest: rendered.manifest,
+      systemPromptPrepend: "",
+      triad: check.triad,
+    };
+  }
+
+  fire("vector_cortex_render_validated", {
+    profileId: rendered.manifest.profileId,
+    requestDigest: rendered.manifest.requestDigest,
+    nodeCount: rendered.manifest.nodeOrder.length,
+    triad: "A",
+  });
+  return {
+    validated: true,
+    bypassed: false,
+    manifest: rendered.manifest,
+    systemPromptPrepend: rendered.request.systemPromptPrepend,
+    triad: "A",
+  };
+}
+
+/**
+ * Register the VC5B `before_agent_start` prepend seam on the host. Flag OFF →
+ * byte-identical to the predecessor (returns the host's unmodified systemPrompt).
+ * The composed prepend is placed on the HOST systemPrompt, never as role:system.
+ */
+export function registerVectorCortexRender(
+  pi: ExtensionAPI,
+  _ctx: ExtensionContext,
+  emit?: VectorCortexEmit,
+): void {
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
+    if (!VC5B_ENABLED()) return; // byte-identical predecessor behavior
+    // The host supplies the active (provider, model) so the seam can resolve the
+    // profile. Until the host passes a render input, the seam stays inert.
+    const pending = (ctx as unknown as { megaCompactVectorCortexRender?: RenderInput }).megaCompactVectorCortexRender;
+    if (pending === undefined) return;
+    const outcome = runVectorCortexRender(pending, emit);
+    if (!outcome.validated) return; // bypass / mismatch → predecessor path
+    return { systemPrompt: `${event.systemPrompt}\n\n${outcome.systemPromptPrepend}` };
+  });
+}
+
+/** Resolve a provider profile by (provider, model) for the host to pass in. */
+export function resolveProfile(provider: string, model: string): ProviderProfileBundle | null {
+  const res = resolveProviderProfile(provider, model);
+  return res.ok ? res.bundle : null;
+}
+
+/** Re-export the core types the host adapter consumes (contract-first). */
+export type { RenderInput, RenderManifestV1, CanonicalOutboundRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -188,6 +188,19 @@ export const VC4C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC4C");
  */
 export const VC5A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5A");
 
+/**
+ * VC5B — validated prompt renderer + provider profiles. Default ON.
+ * `MEGACOMPACT_VC5B=0` disables and is byte-identical to the predecessor
+ * (VC5A): no render manifest is produced, no canonical request is hashed, the
+ * `vector_cortex_render_validated` / `vector_cortex_provider_bypassed` events are
+ * never emitted, and the prompt continues to be built by the predecessor VC5A
+ * DAG/plan path (its goldens are unchanged). The render/validate functions are
+ * PURE — flag OFF gates the reporter + dashboard seam, never the arithmetic.
+ * This flag MUST also be a dashboard SETTINGS toggle (visible in config UI, never
+ * in EXCLUDED_SETTINGS), mirroring VC4A/VC4B/VC4C/VC5A.
+ */
+export const VC5B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5B");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -167,6 +167,7 @@ export {
   VC4B_ENABLED,
   VC4C_ENABLED,
   VC5A_ENABLED,
+  VC5B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/store/sqlite/global-sessions.ts

@@ -82,9 +82,15 @@ export function recordSessionHeartbeat(
 	stateDir: string,
 	ctxWindow: number,
 	indexDir: string = getIndexDir(),
+	// Optional clock override for deterministic tests only. Production callers
+	// omit it → Date.now(), byte-identical behavior. The S39 prune test pins
+	// heartbeats to a known-old timestamp so pruneStaleSessions' Date.now()
+	// cutoff unambiguously exceeds them (no same-millisecond last_seen ==
+	// cutoff race that made pruned !== 2).
+	nowMs: number = Date.now(),
 ): void {
 	const db = openIndexStore(indexDir);
-	const now = Date.now();
+	const now = nowMs;
 	db.prepare(
 		`INSERT INTO session_heartbeats (pid, session_id, repo_root, state_dir, ctx_window, last_seen)
      VALUES (@pid, @session_id, @repo_root, @state_dir, @ctx_window, @last_seen)
@@ -127,9 +133,15 @@ export function appendTokenSample(
 	ctxWindow: number,
 	eventsLogPath: string | null,
 	indexDir: string = getIndexDir(),
+	// Optional clock override for deterministic tests only. Production callers
+	// omit it → falls back to Date.now(), byte-identical behavior. The S39
+	// timeseries test injects distinct timestamps so the per-ts totals map is
+	// not collapsed by same-millisecond sample coincidence (the pre-existing
+	// flake where 3 samples in one ms made totals.length == 1).
+	nowMs: number = Date.now(),
 ): void {
 	const db = openIndexStore(indexDir);
-	const now = Date.now();
+	const now = nowMs;
 	db.prepare(
 		`INSERT INTO token_samples (session_id, repo_root, tokens, percent, ctx_window, ts)
      VALUES (@session_id, @repo_root, @tokens, @percent, @ctx_window, @ts)`,