codemem 0.40.0-alpha.1 → 0.40.0

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, REF_BACKFILL_JOB, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, compareMemoryRoleReports, connect, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, planReplicationOpsAgePrune, projectMatchesFilter, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
+import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, REF_BACKFILL_JOB, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, clonePromptPackAttempt, compareMemoryRoleReports, connect, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getAttributionDiagnostics, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, planReplicationOpsAgePrune, projectMatchesFilter, promptPackArtifactFingerprint, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, recordPromptPackArtifacts, recordPromptPackTerminal, recordRetrievalSurface, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, resolveRetrievalSession, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, tryUpdateRetrievalDelivery, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
 import { Command, Option } from "commander";
 import omelette from "omelette";
+import { randomInt, randomUUID } from "node:crypto";
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, networkInterfaces } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
 import { styleText } from "node:util";
-import { randomInt, randomUUID } from "node:crypto";
 import * as p from "@clack/prompts";
 import { serve } from "@hono/node-server";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
@@ -287,11 +287,77 @@ function queryByFile(dbPath, relativePath, project, limit) {
 function resolveProject$1(payload) {
 	return resolveHookProject(typeof payload.cwd === "string" ? payload.cwd : null, payload.project);
 }
+function sourceSessionId(payload) {
+	const value = payload.session_id;
+	return typeof value === "string" && value.trim() ? value.trim() : null;
+}
 async function buildClaudeFileContext(payload, opts, deps = {}) {
 	if (envTruthy$3(process.env.CODEMEM_PLUGIN_IGNORE)) return continueResult$2();
-	if (!envNotDisabled$2(process.env.CODEMEM_FILE_CONTEXT || "1")) return continueResult$2();
 	const filePath = extractFilePath(payload);
 	if (!filePath) return continueResult$2();
+	const startedAt = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	const attemptId = (deps.createAttemptId ?? randomUUID)();
+	const resolveDb = deps.resolveDb ?? resolveDbPath;
+	let resolvedDbPath = null;
+	let activeStore = null;
+	const getStore = () => {
+		resolvedDbPath ??= resolveDb(resolveDbOpt(opts));
+		activeStore ??= (deps.createStore ?? ((dbPath) => new MemoryStore(dbPath)))(resolvedDbPath);
+		return activeStore;
+	};
+	const finish = (result) => {
+		try {
+			activeStore?.close();
+		} catch {}
+		activeStore = null;
+		return result;
+	};
+	const record = (attemptInput) => {
+		if (!envNotDisabled$2(process.env.CODEMEM_RETRIEVAL_LEDGER || "1")) return;
+		try {
+			resolvedDbPath ??= resolveDb(resolveDbOpt(opts));
+			const completedAt = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+			const ledgerInput = {
+				...attemptInput,
+				attemptId,
+				surface: "file_context",
+				trigger: "automatic",
+				startedAt: startedAt.toISOString(),
+				completedAt: completedAt.toISOString(),
+				latencyMs: Math.max(0, completedAt.getTime() - startedAt.getTime()),
+				recorderVersion: "claude-file-context-v1",
+				source: "claude",
+				streamId: sourceSessionId(payload),
+				sourceSessionId: sourceSessionId(payload),
+				mode: "claude_pre_tool_use_read"
+			};
+			if (deps.recordAttempt) deps.recordAttempt(resolvedDbPath, ledgerInput);
+			else {
+				const store = getStore();
+				recordRetrievalSurface(store.db, {
+					...ledgerInput,
+					sessionId: resolveRetrievalSession(store.db, "claude", ledgerInput.sourceSessionId)
+				});
+			}
+		} catch {}
+	};
+	const updateDelivery = (status) => {
+		if (!envNotDisabled$2(process.env.CODEMEM_RETRIEVAL_LEDGER || "1")) return;
+		try {
+			resolvedDbPath ??= resolveDb(resolveDbOpt(opts));
+			if (deps.updateDelivery) deps.updateDelivery(resolvedDbPath, attemptId, status);
+			else tryUpdateRetrievalDelivery(getStore().db, attemptId, status);
+		} catch {}
+	};
+	if (!envNotDisabled$2(process.env.CODEMEM_FILE_CONTEXT || "1")) {
+		record({
+			retrievalStatus: "skipped",
+			deliveryStatus: "not_attempted",
+			failureCode: "file_context_disabled",
+			failureStage: "configuration"
+		});
+		return finish(continueResult$2());
+	}
 	const cwd = typeof payload.cwd === "string" && payload.cwd.trim() ? payload.cwd : process.cwd();
 	const expandedPath = expandHome$3(filePath);
 	const absolutePath = isAbsolute(expandedPath) ? expandedPath : resolve(cwd, expandedPath);
@@ -299,38 +365,89 @@ async function buildClaudeFileContext(payload, opts, deps = {}) {
 	const escapesCwd = relativePath === ".." || relativePath.startsWith("../") || isAbsolute(relativePath);
 	if (!relativePath || escapesCwd) {
 		logHookEvent(`file_context.skip reason=outside_cwd path=${JSON.stringify(filePath)} cwd=${JSON.stringify(cwd)}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "skipped",
+			deliveryStatus: "not_attempted",
+			failureCode: "outside_cwd",
+			failureStage: "path_validation"
+		});
+		return finish(continueResult$2());
 	}
 	const minBytes = Number.parseInt(process.env.CODEMEM_FILE_CONTEXT_MIN_BYTES ?? `${FILE_GATE_MIN_BYTES}`, 10);
 	const minBytesEffective = Number.isFinite(minBytes) && minBytes >= 0 ? minBytes : FILE_GATE_MIN_BYTES;
 	const stat = (deps.statFile ?? statFile)(absolutePath);
 	if (!stat) {
 		logHookEvent(`file_context.skip reason=stat_failed path=${JSON.stringify(relativePath)}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "skipped",
+			deliveryStatus: "not_attempted",
+			failureCode: "stat_failed",
+			failureStage: "file_access",
+			repositoryPaths: [relativePath]
+		});
+		return finish(continueResult$2());
 	}
 	const bypassSizeGate = SMALL_FILE_BYPASS_PATTERNS.some((p) => p.test(relativePath));
 	if (stat.sizeBytes < minBytesEffective && !bypassSizeGate) {
 		logHookEvent(`file_context.skip reason=below_size_gate path=${JSON.stringify(relativePath)} size=${stat.sizeBytes} gate=${minBytesEffective}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "skipped",
+			deliveryStatus: "not_attempted",
+			failureCode: "below_size_gate",
+			failureStage: "size_gate",
+			repositoryPaths: [relativePath]
+		});
+		return finish(continueResult$2());
 	}
 	const project = resolveProject$1(payload);
-	const resolveDb = deps.resolveDb ?? resolveDbPath;
 	const queryFn = deps.queryByFile ?? queryByFile;
 	let rows = [];
 	try {
-		rows = queryFn(resolveDb(resolveDbOpt(opts)), relativePath, project, FETCH_LIMIT);
+		resolvedDbPath ??= resolveDb(resolveDbOpt(opts));
+		rows = deps.queryByFile ? queryFn(resolvedDbPath, relativePath, project, FETCH_LIMIT) : getStore().findByFile(relativePath, {
+			limit: FETCH_LIMIT,
+			...project ? { project } : {}
+		});
 	} catch (err) {
 		logHookEvent(`codemem claude-hook-file-context query failed: ${err instanceof Error ? err.message : String(err)}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "failed",
+			deliveryStatus: "not_attempted",
+			failureCode: "query_failed",
+			failureStage: "retrieval",
+			project,
+			filters: project ? { project } : void 0,
+			repositoryPaths: [relativePath]
+		});
+		return finish(continueResult$2());
 	}
 	if (rows.length === 0) {
 		logHookEvent(`file_context.skip reason=no_observations path=${JSON.stringify(relativePath)} project=${JSON.stringify(project ?? "")}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "no_results",
+			deliveryStatus: "not_attempted",
+			project,
+			filters: project ? { project } : void 0,
+			repositoryPaths: [relativePath]
+		});
+		return finish(continueResult$2());
 	}
 	const top = scoreAndDedupe(rows, relativePath, DISPLAY_LIMIT);
 	if (top.length === 0) {
 		logHookEvent(`file_context.skip reason=no_top_after_dedupe path=${JSON.stringify(relativePath)} candidates=${rows.length}`);
-		return continueResult$2();
+		record({
+			retrievalStatus: "succeeded",
+			deliveryStatus: "not_attempted",
+			candidateIds: rows.map((row) => row.id),
+			candidateCount: rows.length,
+			selectedIds: [],
+			failureCode: "no_top_after_dedupe",
+			failureStage: "selection",
+			project,
+			filters: project ? { project } : void 0,
+			repositoryPaths: [relativePath]
+		});
+		return finish(continueResult$2());
 	}
 	let staleness = null;
 	if (stat.mtimeMs > 0) {
@@ -343,13 +460,30 @@ async function buildClaudeFileContext(payload, opts, deps = {}) {
 			newestObservationMs
 		};
 	}
-	const timeline = formatTimeline(top, relativePath, staleness);
+	record({
+		retrievalStatus: "succeeded",
+		deliveryStatus: "not_attempted",
+		candidateIds: rows.map((row) => row.id),
+		candidateCount: rows.length,
+		selectedIds: top.map((row) => row.id),
+		project,
+		filters: project ? { project } : void 0,
+		repositoryPaths: [relativePath]
+	});
+	let timeline;
+	try {
+		timeline = formatTimeline(top, relativePath, staleness);
+	} catch {
+		updateDelivery("failed");
+		return finish(continueResult$2());
+	}
 	logHookEvent(`file_context.ok path=${JSON.stringify(relativePath)} candidates=${rows.length} surfaced=${top.length} project=${JSON.stringify(project ?? "")} stale=${staleness ? "true" : "false"}`);
-	return { hookSpecificOutput: {
+	updateDelivery("handed_off");
+	return finish({ hookSpecificOutput: {
 		hookEventName: "PreToolUse",
 		permissionDecision: "allow",
 		additionalContext: timeline
-	} };
+	} });
 }
 var claudeHookFileContextCmd = new Command("claude-hook-file-context").configureHelp(helpStyle).description("Return Claude PreToolUse:Read additionalContext from per-file observation timeline");
 addDbOption(claudeHookFileContextCmd);
@@ -4636,6 +4770,9 @@ function parseStrictPositiveId(value) {
 	const n = Number(value.trim());
 	return Number.isFinite(n) && n >= 1 && Number.isInteger(n) ? n : null;
 }
+function resolveOpenAIResponsesOverride(cliEnabled, configured) {
+	return cliEnabled === true ? true : configured;
+}
 function showMemoryAction(idStr, opts) {
 	const memoryId = parseStrictPositiveId(idStr);
 	if (memoryId === null) {
@@ -5063,10 +5200,11 @@ function createMemoryExtractionReplayCommand() {
 			const observerConfigWithOverrides = {
 				...observerConfig,
 				observerTemperature: observerTemperature ?? observerConfig.observerTemperature,
-				observerOpenAIUseResponses: opts.openaiResponses === true,
-				observerReasoningEffort: opts.reasoningEffort?.trim() || null,
-				observerReasoningSummary: opts.reasoningSummary?.trim() || null,
-				observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxTokens
+				observerOpenAIUseResponses: resolveOpenAIResponsesOverride(opts.openaiResponses, observerConfig.observerOpenAIUseResponses),
+				observerReasoningEffort: opts.reasoningEffort === void 0 ? observerConfig.observerReasoningEffort : opts.reasoningEffort.trim() || null,
+				observerReasoningSummary: opts.reasoningSummary === void 0 ? observerConfig.observerReasoningSummary : opts.reasoningSummary.trim() || null,
+				observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxOutputTokens ?? observerConfig.observerMaxTokens,
+				observerExplicitConfigKeys: maxOutputTokens === null ? observerConfig.observerExplicitConfigKeys : [...new Set([...observerConfig.observerExplicitConfigKeys ?? [], "observerMaxOutputTokens"])]
 			};
 			const observer = new ObserverClient(observerConfigWithOverrides);
 			const result = opts.observerTierRouting === true ? await replayBatchExtractionWithTierRouting(resolveDbOpt(opts), observerConfigWithOverrides, {
@@ -5139,6 +5277,15 @@ function reconcileExtractionBenchmarkStatus(input) {
 		initialQuality: input.initialQuality
 	};
 }
+function summarizeBenchmarkReasoning(runs, fallback) {
+	const source = runs[0] ?? fallback;
+	const reasoningEfforts = new Set(runs.map((run) => run.reasoningEffort));
+	const reasoningSummaries = new Set(runs.map((run) => run.reasoningSummary));
+	return {
+		reasoningEffort: reasoningEfforts.size > 1 ? "mixed" : source.reasoningEffort,
+		reasoningSummary: reasoningSummaries.size > 1 ? "mixed" : source.reasoningSummary
+	};
+}
 function createMemoryExtractionBenchmarkCommand() {
 	const cmd = new Command("extraction-benchmark").configureHelp(helpStyle).description("Run the formal extraction replay benchmark set and print a cost/quality scoreboard").requiredOption("--benchmark <id>", "benchmark profile id").option("--observer-provider <provider>", "override observer provider for this benchmark run").option("--observer-model <model>", "override observer model for this benchmark run").option("--observer-tier-routing", "use replay-only benchmark-backed observer tier routing").option("--openai-responses", "use OpenAI Responses API for this benchmark run").option("--reasoning-effort <level>", "set OpenAI reasoning.effort for this benchmark run (responses path)").option("--reasoning-summary <mode>", "set OpenAI reasoning.summary for this benchmark run (responses path)").option("--max-output-tokens <n>", "override OpenAI max_output_tokens for this benchmark run (responses path)").option("--observer-temperature <value>", "override observer temperature for this benchmark run").option("--transcript-budget <chars>", "override replay transcript budget in characters for this benchmark run").option("--repetitions <n>", "run every benchmark batch 1-10 times to measure model stability", "1");
 	addDbOption(cmd);
@@ -5170,10 +5317,11 @@ function createMemoryExtractionBenchmarkCommand() {
 				observerProvider: opts.observerProvider?.trim() || observerConfig.observerProvider,
 				observerModel: opts.observerModel?.trim() || observerConfig.observerModel,
 				observerTemperature: observerTemperature ?? observerConfig.observerTemperature,
-				observerOpenAIUseResponses: opts.openaiResponses === true,
-				observerReasoningEffort: opts.reasoningEffort?.trim() || null,
-				observerReasoningSummary: opts.reasoningSummary?.trim() || null,
-				observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxTokens
+				observerOpenAIUseResponses: resolveOpenAIResponsesOverride(opts.openaiResponses, observerConfig.observerOpenAIUseResponses),
+				observerReasoningEffort: opts.reasoningEffort === void 0 ? observerConfig.observerReasoningEffort : opts.reasoningEffort.trim() || null,
+				observerReasoningSummary: opts.reasoningSummary === void 0 ? observerConfig.observerReasoningSummary : opts.reasoningSummary.trim() || null,
+				observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxOutputTokens ?? observerConfig.observerMaxTokens,
+				observerExplicitConfigKeys: maxOutputTokens === null ? observerConfig.observerExplicitConfigKeys : [...new Set([...observerConfig.observerExplicitConfigKeys ?? [], "observerMaxOutputTokens"])]
 			};
 			const observer = new ObserverClient(observerConfigWithOverrides);
 			const runs = [];
@@ -5343,16 +5491,20 @@ function createMemoryExtractionBenchmarkCommand() {
 				})
 			};
 			const uniqueObserverKeys = Array.from(new Set(runs.map((run) => `${run.provider}::${run.model}::${run.transport}`)));
+			const benchmarkReasoning = summarizeBenchmarkReasoning(runs, {
+				reasoningEffort: observer.reasoningEffort,
+				reasoningSummary: observer.reasoningSummary
+			});
 			const observerSummary = opts.observerTierRouting === true ? {
 				provider: uniqueObserverKeys.length === 1 ? runs[0]?.provider ?? observer.provider : "mixed",
 				model: uniqueObserverKeys.length === 1 ? runs[0]?.model ?? observer.model : "mixed",
 				transport: uniqueObserverKeys.length === 1 ? runs[0]?.transport ?? "unknown" : "mixed",
 				tierRouting: true,
 				openaiUseResponses: uniqueObserverKeys.length === 1 ? runs[0]?.openaiUseResponses ?? observer.openaiUseResponses : null,
-				reasoningEffort: uniqueObserverKeys.length === 1 ? runs[0]?.reasoningEffort ?? observer.reasoningEffort : "mixed",
-				reasoningSummary: uniqueObserverKeys.length === 1 ? runs[0]?.reasoningSummary ?? observer.reasoningSummary : "mixed",
-				maxOutputTokens: uniqueObserverKeys.length === 1 ? runs[0]?.maxOutputTokens ?? observer.maxOutputTokens : null,
-				temperature: uniqueObserverKeys.length === 1 ? runs[0]?.temperature ?? observer.temperature : null,
+				reasoningEffort: benchmarkReasoning.reasoningEffort,
+				reasoningSummary: benchmarkReasoning.reasoningSummary,
+				maxOutputTokens: uniqueObserverKeys.length === 1 ? runs[0]?.maxOutputTokens ?? null : null,
+				temperature: uniqueObserverKeys.length === 1 ? runs[0]?.temperature ?? null : null,
 				transcriptBudget: transcriptBudget ?? null,
 				selectedObservers: uniqueObserverKeys
 			} : {
@@ -5361,10 +5513,10 @@ function createMemoryExtractionBenchmarkCommand() {
 				transport: runs[0]?.transport ?? observer.getStatus().runtime,
 				tierRouting: false,
 				openaiUseResponses: observer.openaiUseResponses,
-				reasoningEffort: observer.reasoningEffort,
-				reasoningSummary: observer.reasoningSummary,
-				maxOutputTokens: observer.maxOutputTokens,
-				temperature: observer.temperature,
+				reasoningEffort: benchmarkReasoning.reasoningEffort,
+				reasoningSummary: benchmarkReasoning.reasoningSummary,
+				maxOutputTokens: runs[0]?.maxOutputTokens ?? null,
+				temperature: runs[0]?.temperature ?? null,
 				transcriptBudget: transcriptBudget ?? null,
 				selectedObservers: uniqueObserverKeys
 			};
@@ -5390,10 +5542,10 @@ function createMemoryExtractionBenchmarkCommand() {
 				`Transport: ${observerSummary.transport}`,
 				`Tier routing: ${opts.observerTierRouting === true ? "yes" : "no"}`,
 				`OpenAI Responses: ${observerSummary.openaiUseResponses === null ? "mixed" : observerSummary.openaiUseResponses ? "yes" : "no"}`,
-				`Reasoning effort: ${observerSummary.reasoningEffort ?? "none"}`,
-				`Reasoning summary: ${observerSummary.reasoningSummary ?? "none"}`,
-				`Max output tokens: ${observerSummary.maxOutputTokens ?? "mixed"}`,
-				`Temperature: ${observerSummary.temperature ?? "mixed"}`,
+				`Reasoning effort: ${observerSummary.reasoningEffort ?? "not transmitted"}`,
+				`Reasoning summary: ${observerSummary.reasoningSummary ?? "not transmitted"}`,
+				`Max output tokens: ${observerSummary.transport === "codex_consumer" ? "not transmitted" : observerSummary.maxOutputTokens ?? "mixed"}`,
+				`Temperature: ${observerSummary.transport === "mixed" ? "mixed" : observerSummary.temperature ?? "not transmitted"}`,
 				`Transcript budget override: ${transcriptBudget ?? "default"}`,
 				`Repetitions: ${summary.repetitions}`,
 				`Shape-quality passes: ${summary.shapeQualityPasses}/${summary.shapeQualityTotal}`,
@@ -5511,6 +5663,127 @@ memoryCommand.addCommand(createMemoryRelinkReportCommand());
 memoryCommand.addCommand(createMemoryRelinkPlanCommand());
 //#endregion
 //#region src/commands/pack.ts
+var MAX_INTERNAL_LEDGER_INPUT_BYTES = 16 * 1024;
+var INTERNAL_LEDGER_INPUT_TIMEOUT_MS = 1e3;
+var FORBIDDEN_INTERNAL_KEYS = new Set([
+	"body",
+	"context",
+	"pack",
+	"pack_text",
+	"path",
+	"preview",
+	"prompt",
+	"query",
+	"raw_prompt",
+	"title"
+]);
+var INTERNAL_LEDGER_KEYS = new Set([
+	"action",
+	"attempt_id",
+	"started_at",
+	"source",
+	"stream_id",
+	"source_session_id",
+	"prompt_number",
+	"request_id",
+	"retrieval_status",
+	"delivery_status",
+	"failure_code",
+	"failure_stage",
+	"original_attempt_id"
+]);
+var INTERNAL_LEDGER_ACTIONS = new Set([
+	"record",
+	"delivery",
+	"cache_reuse"
+]);
+var INTERNAL_RETRIEVAL_STATUSES = new Set(["skipped", "failed"]);
+var INTERNAL_DELIVERY_STATUSES = new Set([
+	"handed_off",
+	"failed",
+	"unknown"
+]);
+async function readInternalLedgerPayload() {
+	const stdin = process.stdin;
+	if (stdin.isTTY) throw new PackUsageError("internal ledger metadata requires piped stdin JSON");
+	return parseInternalLedgerPayload(await new Promise((resolve, reject) => {
+		let value = "";
+		const cleanup = () => {
+			clearTimeout(timer);
+			stdin.off("data", onData);
+			stdin.off("end", onEnd);
+			stdin.off("error", onError);
+		};
+		const fail = (error) => {
+			cleanup();
+			stdin.pause();
+			reject(error);
+		};
+		const onData = (chunk) => {
+			value += String(chunk);
+			if (Buffer.byteLength(value, "utf8") > MAX_INTERNAL_LEDGER_INPUT_BYTES) fail(new PackUsageError("internal ledger metadata exceeds 16384 bytes"));
+		};
+		const onEnd = () => {
+			cleanup();
+			resolve(value);
+		};
+		const onError = (error) => fail(error);
+		const timer = setTimeout(() => fail(new PackUsageError("internal ledger metadata read timed out")), INTERNAL_LEDGER_INPUT_TIMEOUT_MS);
+		stdin.on("data", onData);
+		stdin.once("end", onEnd);
+		stdin.once("error", onError);
+	}));
+}
+function parseInternalLedgerPayload(raw) {
+	if (Buffer.byteLength(raw, "utf8") > MAX_INTERNAL_LEDGER_INPUT_BYTES) throw new PackUsageError("internal ledger metadata exceeds 16384 bytes");
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		throw new PackUsageError("internal ledger metadata must be valid JSON");
+	}
+	if (value == null || typeof value !== "object" || Array.isArray(value)) throw new PackUsageError("internal ledger metadata must be an object");
+	for (const key of Object.keys(value)) {
+		if (FORBIDDEN_INTERNAL_KEYS.has(key)) throw new PackUsageError(`internal ledger metadata rejects sensitive field: ${key}`);
+		if (!INTERNAL_LEDGER_KEYS.has(key)) throw new PackUsageError(`internal ledger metadata contains unsupported field: ${key}`);
+	}
+	const payload = value;
+	if (typeof payload.attempt_id !== "string") throw new PackUsageError("internal ledger metadata requires attempt_id");
+	if (payload.action != null && !INTERNAL_LEDGER_ACTIONS.has(payload.action)) throw new PackUsageError("internal ledger action is invalid");
+	if (payload.retrieval_status != null && !INTERNAL_RETRIEVAL_STATUSES.has(payload.retrieval_status)) throw new PackUsageError("internal ledger retrieval_status is invalid");
+	if (payload.delivery_status != null && !INTERNAL_DELIVERY_STATUSES.has(payload.delivery_status)) throw new PackUsageError("internal ledger delivery_status is invalid");
+	if (payload.prompt_number != null && (!Number.isInteger(payload.prompt_number) || payload.prompt_number < 0)) throw new PackUsageError("internal ledger prompt_number must be a non-negative integer");
+	for (const key of [
+		"started_at",
+		"source",
+		"stream_id",
+		"source_session_id",
+		"request_id",
+		"failure_code",
+		"failure_stage",
+		"original_attempt_id"
+	]) {
+		const field = payload[key];
+		if (field != null && (typeof field !== "string" || field.length > 512)) throw new PackUsageError(`internal ledger metadata field ${key} is invalid`);
+		if (typeof field === "string" && (posix.isAbsolute(field) || win32.isAbsolute(field))) throw new PackUsageError(`internal ledger metadata rejects absolute paths in field: ${key}`);
+	}
+	return payload;
+}
+function attemptMetadata(payload) {
+	return {
+		attemptId: payload.attempt_id,
+		startedAt: payload.started_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+		completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		source: payload.source ?? "opencode",
+		streamId: payload.stream_id ?? null,
+		sourceSessionId: payload.source_session_id ?? null,
+		promptNumber: payload.prompt_number ?? null,
+		requestId: payload.request_id ?? null
+	};
+}
+function handleInstrumentedPackLedger(db, payload, context, filters, artifacts) {
+	return recordPromptPackArtifacts(db, attemptMetadata(payload), context, filters, artifacts);
+}
 function describeCandidate(candidate) {
 	const scoreParts = [
 		candidate.scores.combined_score != null ? `combined=${candidate.scores.combined_score.toFixed(2)}` : null,
@@ -5584,24 +5857,46 @@ async function withStore(opts, errorCode, run) {
 async function packAction(context, opts) {
 	await withStore(opts, "pack_failed", async (store) => {
 		const { limit, budget, filters, renderOptions } = buildPackRequestOptions(opts, { envProject: process.env.CODEMEM_PROJECT });
-		const result = await store.buildMemoryPackAsync(context, limit, budget, filters, renderOptions);
-		if (opts.json) {
-			console.log(JSON.stringify(result, null, 2));
-			return;
-		}
-		p.intro(`Memory pack for "${context}"`);
-		if (result.items.length === 0) {
-			p.log.warn("No relevant memories found.");
-			p.outro("done");
+		let result;
+		if (opts.internalLedger) {
+			const artifacts = await store.buildMemoryPackWithTraceAsync(context, limit, budget, filters, renderOptions);
+			result = artifacts.response;
+			let artifactFingerprint;
+			try {
+				artifactFingerprint = promptPackArtifactFingerprint(store.db, context, filters, artifacts);
+			} catch {}
+			let ledgerOutcome;
+			try {
+				const ledgerPayload = await readInternalLedgerPayload();
+				ledgerOutcome = handleInstrumentedPackLedger(store.db, ledgerPayload, context, filters, artifacts);
+			} catch {}
+			emitPackResult(context, opts, result, artifactFingerprint, ledgerOutcome?.ok === false && ledgerOutcome.reason === "idempotency_conflict" ? ledgerOutcome : void 0);
 			return;
-		}
-		const metrics = result.metrics;
-		p.log.info(`${metrics.total_items} items, ~${metrics.pack_tokens} tokens` + (metrics.fallback_used ? " (fallback)" : "") + `  [fts:${metrics.sources.fts} sem:${metrics.sources.semantic} fuzzy:${metrics.sources.fuzzy}]`);
-		for (const item of result.items) p.log.step(`#${item.id}  ${item.kind}  ${item.title}`);
-		p.note(result.pack_text, "pack_text");
-		p.outro("done");
+		} else result = await store.buildMemoryPackAsync(context, limit, budget, filters, renderOptions);
+		emitPackResult(context, opts, result);
 	});
 }
+function emitPackResult(context, opts, result, ledgerArtifactFingerprint, ledgerOutcome) {
+	if (opts.json) {
+		console.log(JSON.stringify({
+			...result,
+			...ledgerArtifactFingerprint ? { ledger_artifact_fingerprint: ledgerArtifactFingerprint } : {},
+			...ledgerOutcome ? { ledger_outcome: ledgerOutcome } : {}
+		}, null, 2));
+		return;
+	}
+	p.intro(`Memory pack for "${context}"`);
+	if (result.items.length === 0) {
+		p.log.warn("No relevant memories found.");
+		p.outro("done");
+		return;
+	}
+	const metrics = result.metrics;
+	p.log.info(`${metrics.total_items} items, ~${metrics.pack_tokens} tokens` + (metrics.fallback_used ? " (fallback)" : "") + `  [fts:${metrics.sources.fts} sem:${metrics.sources.semantic} fuzzy:${metrics.sources.fuzzy}]`);
+	for (const item of result.items) p.log.step(`#${item.id}  ${item.kind}  ${item.title}`);
+	p.note(result.pack_text, "pack_text");
+	p.outro("done");
+}
 async function traceAction(context, opts) {
 	await withStore(opts, "pack_trace_failed", async (store) => {
 		const { limit, budget, filters, renderOptions } = buildPackRequestOptions(opts, { envProject: process.env.CODEMEM_PROJECT });
@@ -5614,6 +5909,7 @@ async function traceAction(context, opts) {
 	});
 }
 var packCmd = addPackRequestOptions(new Command("pack").enablePositionalOptions().configureHelp(helpStyle).description("Build a context-aware memory pack").argument("<context>", "context string to search for"));
+packCmd.addOption(new Option("--internal-ledger").hideHelp());
 addDbOption(packCmd);
 addJsonOption(packCmd);
 packCmd.action(packAction);
@@ -5623,6 +5919,38 @@ addJsonOption(traceCmd);
 traceCmd.action(traceAction);
 packCmd.addCommand(traceCmd);
 var packCommand = packCmd;
+function handlePromptPackLedger(db, payload) {
+	const metadata = attemptMetadata(payload);
+	if (payload.action === "delivery") {
+		const status = payload.delivery_status;
+		if (!status) throw new PackUsageError("delivery action requires delivery_status");
+		const outcome = tryUpdateRetrievalDelivery(db, payload.attempt_id, status);
+		if (!outcome.ok) throw new Error(outcome.reason);
+		return outcome.value;
+	}
+	if (payload.action === "cache_reuse") {
+		if (!payload.original_attempt_id) throw new PackUsageError("cache_reuse action requires original_attempt_id");
+		const outcome = clonePromptPackAttempt(db, payload.original_attempt_id, metadata);
+		if (!outcome.ok) throw new Error(outcome.reason);
+		return outcome.value;
+	}
+	if (payload.action === "record") {
+		if (!payload.retrieval_status || !payload.failure_code || !payload.failure_stage) throw new PackUsageError("record action requires retrieval_status, failure_code, and failure_stage");
+		const outcome = recordPromptPackTerminal(db, metadata, payload.retrieval_status, payload.failure_code, payload.failure_stage);
+		if (!outcome.ok) throw new Error(outcome.reason);
+		return outcome.value;
+	}
+	throw new PackUsageError("internal ledger action is invalid");
+}
+async function promptPackLedgerAction(opts) {
+	await withStore(opts, "prompt_pack_ledger_failed", async (store) => {
+		const payload = await readInternalLedgerPayload();
+		handlePromptPackLedger(store.db, payload);
+	});
+}
+var ledgerCmd = new Command("prompt-pack-ledger").description("Record internal prompt-pack lifecycle metadata").action(promptPackLedgerAction);
+addDbOption(ledgerCmd);
+var promptPackLedgerCommand = ledgerCmd;
 //#endregion
 //#region src/commands/recent.ts
 var cmd = new Command("recent").configureHelp(helpStyle).description("Show recent memories").option("--limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind");
@@ -6134,10 +6462,20 @@ function sqliteVecFailureDiagnostics(error, dbPath) {
 }
 async function runServeCoordinatorMaintenance(store, dependencies) {
 	const projectShares = await dependencies.advancePendingProjectShares(store, { limit: 3 });
+	const coordinatorEnrollment = await dependencies.reconcileConfiguredCoordinatorEnrollment(store);
+	const enrollmentIssues = coordinatorEnrollment.issues ?? 0;
+	const recipientPolicies = await dependencies.reconcileRecipientPolicyProjects(store, { limit: 3 });
 	if (projectShares.failed > 0) throw new Error(`share operation maintenance failed for ${projectShares.failed} of ${projectShares.processed} operations`);
+	if (coordinatorEnrollment.failedGroups > 0 || enrollmentIssues > 0) {
+		const groupLabel = coordinatorEnrollment.failedGroups === 1 ? "group" : "groups";
+		const issueLabel = enrollmentIssues === 1 ? "issue" : "issues";
+		throw new Error(`coordinator enrollment maintenance failed for ${coordinatorEnrollment.failedGroups} ${groupLabel} with ${enrollmentIssues} reconciliation ${issueLabel}`);
+	}
+	if (recipientPolicies.failed > 0) throw new Error(`recipient policy maintenance failed for ${recipientPolicies.failed} of ${recipientPolicies.processed} projects`);
 	return {
 		projectShares,
-		recipientPolicies: await dependencies.reconcileRecipientPolicyProjects(store, { limit: 3 })
+		coordinatorEnrollment,
+		recipientPolicies
 	};
 }
 async function startBackgroundViewer(invocation) {
@@ -6172,7 +6510,7 @@ async function startBackgroundViewer(invocation) {
 	p.outro(`Viewer started in background (pid ${child.pid}) at http://${invocation.host}:${invocation.port}`);
 }
 async function startForegroundViewer(invocation) {
-	const { advancePendingProjectShares, createApp, createSyncApp, closeStore, getStore, reconcileRecipientPolicyProjects } = await import("@codemem/server");
+	const { advancePendingProjectShares, createApp, createSyncApp, closeStore, getStore, reconcileConfiguredCoordinatorEnrollment, reconcileRecipientPolicyProjects } = await import("@codemem/server");
 	const { serve } = await import("@hono/node-server");
 	if (invocation.dbPath) process.env.CODEMEM_DB = invocation.dbPath;
 	if (invocation.configPath) process.env.CODEMEM_CONFIG = invocation.configPath;
@@ -6266,6 +6604,7 @@ async function startForegroundViewer(invocation) {
 					onAfterCoordinatorRefresh: async () => {
 						await runServeCoordinatorMaintenance(store, {
 							advancePendingProjectShares,
+							reconcileConfiguredCoordinatorEnrollment,
 							reconcileRecipientPolicyProjects
 						});
 					},
@@ -6875,9 +7214,38 @@ function fmtTokens(n) {
 var statsCmd = new Command("stats").configureHelp(helpStyle).description("Show database statistics");
 addDbOption(statsCmd);
 addJsonOption(statsCmd);
+statsCmd.addOption(new Option("-a, --attribution", "show local retrieval attribution diagnostics"));
+function renderAttributionDiagnostics(report) {
+	const evidence = report.evidenceCompleteness;
+	return [
+		"Retrieval attribution diagnostics (local, bounded)",
+		`Lifecycle: ${report.lifecycle.requestedAttempts} requested, ${report.lifecycle.selectedAttempts} selected, ${report.lifecycle.handedOffAttempts} handed off`,
+		`Exposures: ${report.lifecycle.selectedExposures} selected, ${report.lifecycle.handedOffExposures} handed off`,
+		`Evidence: ${[
+			`${evidence.assessedAttempts} assessed`,
+			`${evidence.unassessedAttempts} unassessed`,
+			`${evidence.assessedKnownAttempts} known`,
+			`${evidence.assessedUnknownAttempts} unknown`,
+			`${evidence.assessmentStatusIndeterminateAttempts} status indeterminate`,
+			`${evidence.assessmentDetailsIncompleteAttempts} details incomplete`,
+			`${evidence.assessmentRowsInvalid} invalid rows`,
+			`${evidence.assessmentRowsOmittedByLimit} omitted by limit`
+		].join(", ")}`,
+		`Latency: ${report.overhead.latencySampleCount} samples, ${report.overhead.averageLatencyMs ?? "unknown"} ms average`,
+		`Steering: ${report.sourceLocationSteering.assessmentCount} source-location assessments, ${report.sourceLocationSteering.matchedPathCount} matched paths`,
+		`Findings: ${report.findings.stale} stale, ${report.findings.harmful} harmful`,
+		"Limitations:",
+		...report.limitations.map((limitation) => `- ${limitation}`)
+	].join("\n");
+}
 var statsCommand = statsCmd.action((opts) => {
 	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
+		if (opts.attribution) {
+			const report = getAttributionDiagnostics(store.db);
+			console.log(opts.json ? JSON.stringify(report, null, 2) : renderAttributionDiagnostics(report));
+			return;
+		}
 		const result = store.stats();
 		if (opts.json) {
 			console.log(JSON.stringify(result, null, 2));
@@ -7981,6 +8349,7 @@ program.addCommand(embedCommand);
 program.addCommand(recentCommand);
 program.addCommand(searchCommand);
 program.addCommand(packCommand);
+program.addCommand(promptPackLedgerCommand, { hidden: true });
 program.addCommand(showMemoryCommand, { hidden: true });
 program.addCommand(forgetMemoryCommand, { hidden: true });
 program.addCommand(rememberMemoryCommand, { hidden: true });