@codemem/server 0.44.0-alpha.1 → 0.44.0

package/dist/index.js

@@ -1,14 +1,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
-import { ACCESS_CLEANUP_OP_TYPE, CODEMEM_CONFIG_ENV_OVERRIDES, CoordinatorReciprocalApprovalRequestChangedError, DEFAULT_TIME_WINDOW_S, LEGACY_SHARED_REVIEW_SCOPE_ID, LOCAL_DEFAULT_SCOPE_ID, LOCAL_SYNC_CAPABILITY, LOCAL_SYNC_FEATURES, LegacyTeamSetupAdditiveConvergenceError, MemoryStore, PROMPT_TRANSPORT_PROTOCOL_RANGE, RawEventIngestValidationError, RecipientPolicyEdgeRequestError, RecipientPolicyTeamRenameError, SCOPE_MEMBERSHIP_REVOCATION_LIMITATION, SYNC_AUTHORIZATION_REFRESH_HEADER, SYNC_CAPABILITY_HEADER, SYNC_FEATURES_HEADER, SYNC_SCOPE_QUERY_PARAM, VERSION, VERSION as VERSION$1, VIEWER_IDENTITY_TARGET_KEYS, VIEWER_SERVICE_DISCRIMINATOR, addSyncScopeToBoundary, analyzeProjectScopeMappingChangeGuardrails, applyLegacyTeamSetupCompletionManifest, applyLegacyTeamSetupCompletionManifestAndReturnActivation, applyReplicationOps, areLegacyTeamSetupCompletionPolicyFactsAdditivelyCompatible, buildAuthHeaders, buildBaseUrl, buildDirectPeerAuthHeaders, buildFilterClausesWithContext, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, buildViewerIdentityTarget, canonicalCoordinatorLegacyTeamCompletionManifestJson, canonicalMemoryKind, canonicalWorkspaceIdentity, claimRecipientPolicyActorMutations, claimRecipientPolicyPublicationMutation, cleanupNonces, clearLegacyTeamSetupDeviceDecision, clonePromptPackAttempt, coerceObserverCommand, commitDeviceIdentityBindings, commitRecipientPolicyEdges, containLegacyTeamSetupCompletionConflict, coordinatorArchiveGroupAction, coordinatorCreateAddDeviceInviteAction, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateLegacyTeamCompletionAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnableDeviceAction, coordinatorGetLegacyTeamCompletionAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListConsumedTeamInvitesAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListLegacyTeamCompletionsAction, coordinatorListReviewedRecipientInviteEvidenceAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorRenameGroupAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorStatusSnapshot, coordinatorUnarchiveGroupAction, coordinatorUpdateScopeAction, countShareableProjectMemories, createCoordinatorReciprocalApproval, decodeInvitePayload, defaultSpaceScopeIdForGroup, deleteProjectScopeSettingsMapping, deriveLegacyTeamSetupCompletionManifest, detectInstallKind, deterministicPolicyTeamId, diagnoseStalePeerReceivedRows, discoverLegacyTeamCandidates, ensureDeviceIdentity, executeShareProvisioning, extractInvitePayload, extractReplicationOps, filterReplicationOpsForSyncWithStatus, fingerprintPublicKey, formatHostPort, friendlyDeviceName, fromJson, getCodememConfigPath, getCodememEnvOverrides, getCoordinatorEnrollmentReconciliationIssueSummary, getCoordinatorGroupPreference, getLegacyTeamSetupDraft, getRecipientPolicyAuthorityState, getSemanticIndexDiagnostics, getSyncResetState, getUpdateStatus, ingestRawEvents, inspectFreshLegacyTeamSetupActivation, inspectLegacyTeamSetupActivation, inviteTokenDigest, isLegacyTeamCandidateSelectable, isLegacyTeamSetupProjectMappingIdentity, isPeerTrustBindingCompatible, isProjectSyncEnablementError, isScopedSyncCapability, legacyTeamCandidateId, legacyTeamCandidateProjectInventory, legacyTeamCanonicalProjectRef, legacyTeamDeviceRef, legacyTeamResolvedProjectRef, legacyTeamSetupApiErrorCode, listAuthorizedScopesForPeer, listCoordinatorJoinRequests, listDeviceIdentityInventory, listInboundScopeRejections, listLegacyRecipientPolicyProjections, listMaintenanceJobs, listObserverProviderOptions, listPerPeerScopeSyncState, listProjectScopeCandidates, listProjectScopeInventory, listProjectScopeSettingsMappings, listRecipientPolicyIntent, listRecipientPolicyReview, listSharingDomainSettingsScopes, loadMemorySnapshotPageForPeer, loadReplicationOpsForPeer, lookupCoordinatorPeers, mergeAddresses, migrateRecipientPolicyIntent, negotiateSyncCapability, normalizeAddress, normalizeHumanPresentationName, normalizeSyncCapability, normalizeSyncFeatures, normalizeTeammateName, parseAcceptedProjectIntent, parsePositiveMemoryId, parseReassignScopePayload, parseRecipientPolicyEdgeCommitRequest, parseStrictInteger, parseSyncScopeRequest, persistShareOperation, personalScopeGrantStatusForPeer, planShareOperation, previewDeviceIdentityBindings, previewLegacyTeamSetupActivation, previewRecipientPolicyEdges, previewRecipientPolicyOnboarding, previewRecipientPolicyOnboardingFromReviewedIntent, probeAvailableCredentials, projectShareLifecycle, promptPackArtifactFingerprint, readCodememConfigFile, readCoordinatorSyncConfig, reassignProjectScopeInventoryProject, recipientInviteAuthoritativeIdentityId, recipientPolicyDigest, recipientReviewedIntentDigest, reconcileCoordinatorEnrollmentSnapshot, reconcileRecipientPolicyProject, reconcileShareOperationAcceptance, reconstructLegacyTeamSetupCompletionManifest, recordHighestObservedDirectSignatureVersion, recordNonce, recordPromptPackArtifacts, recordPromptPackTerminal, refreshAuthorizedCoordinatorPeerTrust, refreshConfiguredScopeMembershipCache, refreshLegacyTeamCandidate, rejectInboundScopeFailures, renameRecipientPolicyTeam, replayLegacyTeamSetupActivation, requestJson, requireLegacyTeamSetupAccessDeltaWithinLimit, resolveDbPath, resolveProject, resolveRecipientPolicyReview, resolveRecipientPolicyReviewBulk, runSyncPass, schema, serializeRecipientPolicyCoordinatorGroupMutation, serializeRecipientPolicyPublicationMutation, serializeRecipientPolicyTeamMutation, setLegacyTeamSetupDeviceAssignment, setLegacyTeamSetupDeviceDecision, setLegacyTeamSetupProjectMapping, summarizeInboundScopeRejections, supportsSyncFeature, syncScopeResetRequiredPayload, tryUpdateRetrievalDelivery, updatePeerAddresses, upsertCoordinatorGroupPreference, upsertProjectScopeSettingsMapping, validateLegacyTeamSetupCompletionManifest, validateLegacyTeamSetupCompletionManifestBinding, verifyDirectPeerSignature, verifyRecipientReviewedIntent, verifySignature, writeCodememConfigFile } from "@codemem/core";
+import { ACCESS_CLEANUP_OP_TYPE, CODEMEM_CONFIG_ENV_OVERRIDES, CoordinatorReciprocalApprovalRequestChangedError, DEFAULT_TIME_WINDOW_S, LEGACY_SHARED_REVIEW_SCOPE_ID, LOCAL_DEFAULT_SCOPE_ID, LOCAL_SYNC_CAPABILITY, LOCAL_SYNC_FEATURES, LegacyTeamSetupAdditiveConvergenceError, LegacyTeamSetupRosterCapacityError, MemoryStore, PROMPT_TRANSPORT_PROTOCOL_RANGE, RawEventIngestValidationError, RecipientPolicyEdgeRequestError, RecipientPolicyTeamRenameError, RemoteCoordinatorRequestError, SCOPE_MEMBERSHIP_REVOCATION_LIMITATION, SYNC_AUTHORIZATION_REFRESH_HEADER, SYNC_CAPABILITY_HEADER, SYNC_FEATURES_HEADER, SYNC_SCOPE_QUERY_PARAM, VERSION, VERSION as VERSION$1, VIEWER_IDENTITY_TARGET_KEYS, VIEWER_SERVICE_DISCRIMINATOR, addSyncScopeToBoundary, analyzeProjectScopeMappingChangeGuardrails, applyLegacyTeamSetupCompletionManifest, applyLegacyTeamSetupCompletionManifestAndReturnActivation, applyReplicationOps, areLegacyTeamSetupCompletionPolicyFactsAdditivelyCompatible, automaticRecallHealth, buildAuthHeaders, buildBaseUrl, buildDirectPeerAuthHeaders, buildFilterClausesWithContext, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, buildViewerIdentityTarget, canonicalCoordinatorLegacyTeamCompletionManifestJson, canonicalMemoryKind, canonicalWorkspaceIdentity, claimRecipientPolicyActorMutations, claimRecipientPolicyPublicationMutation, cleanupNonces, clearLegacyTeamSetupDeviceDecision, clonePromptPackAttempt, coerceObserverCommand, commitDeviceIdentityBindings, commitRecipientPolicyEdges, containLegacyTeamSetupCompletionConflict, coordinatorArchiveGroupAction, coordinatorCreateAddDeviceInviteAction, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateLegacyTeamCompletionAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnableDeviceAction, coordinatorGetLegacyTeamCompletionAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListConsumedTeamInvitesAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListLegacyTeamCompletionsAction, coordinatorListReviewedRecipientInviteEvidenceAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorRenameGroupAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorStatusSnapshot, coordinatorUnarchiveGroupAction, coordinatorUpdateScopeAction, countShareableProjectMemories, createCoordinatorReciprocalApproval, decodeInvitePayload, defaultSpaceScopeIdForGroup, deleteProjectScopeSettingsMapping, deriveLegacyTeamSetupCompletionManifest, detectInstallKind, deterministicPolicyTeamId, diagnoseStalePeerReceivedRows, discoverLegacyTeamCandidates, ensureDeviceIdentity, executeShareProvisioning, extractInvitePayload, extractReplicationOps, filterReplicationOpsForSyncWithStatus, fingerprintPublicKey, formatHostPort, friendlyDeviceName, fromJson, getCodememConfigPath, getCodememEnvOverrides, getCoordinatorEnrollmentReconciliationIssueSummary, getCoordinatorGroupPreference, getLegacyTeamSetupDraft, getRecipientPolicyAuthorityState, getSemanticIndexDiagnostics, getSyncResetState, getUpdateStatus, ingestRawEvents, inspectFreshLegacyTeamSetupActivation, inspectLegacyTeamSetupActivation, inviteTokenDigest, isAutomaticRecallMeasurement, isLegacyTeamCandidateSelectable, isLegacyTeamSetupProjectMappingIdentity, isPeerTrustBindingCompatible, isProjectSyncEnablementError, isScopedSyncCapability, legacyTeamCandidateId, legacyTeamCandidateProjectInventory, legacyTeamCanonicalProjectRef, legacyTeamDeviceRef, legacyTeamResolvedProjectRef, legacyTeamSetupApiErrorCode, listAuthorizedScopesForPeer, listCoordinatorJoinRequests, listDeviceIdentityInventory, listInboundScopeRejections, listLegacyRecipientPolicyProjections, listMaintenanceJobs, listObserverProviderOptions, listPerPeerScopeSyncState, listProjectScopeCandidates, listProjectScopeInventory, listProjectScopeSettingsMappings, listRecipientPolicyIntent, listRecipientPolicyReview, listSharingDomainSettingsScopes, loadMemorySnapshotPageForPeer, loadReplicationOpsForPeer, lookupCoordinatorPeers, mergeAddresses, migrateRecipientPolicyIntent, negotiateSyncCapability, normalizeAddress, normalizeHumanPresentationName, normalizeSyncCapability, normalizeSyncFeatures, normalizeTeammateName, parseAcceptedProjectIntent, parsePositiveMemoryId, parseReassignScopePayload, parseRecipientPolicyEdgeCommitRequest, parseStrictInteger, parseSyncScopeRequest, persistShareOperation, personalScopeGrantStatusForPeer, planShareOperation, previewDeviceIdentityBindings, previewLegacyTeamSetupActivation, previewRecipientPolicyEdges, previewRecipientPolicyOnboarding, previewRecipientPolicyOnboardingFromReviewedIntent, probeAvailableCredentials, projectShareLifecycle, promptPackArtifactFingerprint, readCodememConfigFile, readCoordinatorSyncConfig, reassignProjectScopeInventoryProject, recipientInviteAuthoritativeIdentityId, recipientPolicyDigest, recipientReviewedIntentDigest, reconcileCoordinatorEnrollmentSnapshot, reconcileRecipientPolicyProject, reconcileShareOperationAcceptance, reconstructLegacyTeamSetupCompletionManifest, recordAutomaticRecall, recordHighestObservedDirectSignatureVersion, recordNonce, recordPromptPackArtifacts, recordPromptPackTerminal, refreshAuthorizedCoordinatorPeerTrust, refreshConfiguredScopeMembershipCache, refreshLegacyTeamCandidate, rejectInboundScopeFailures, renameRecipientPolicyTeam, replayLegacyTeamSetupActivation, requestJson, requireLegacyTeamSetupAccessDeltaWithinLimit, resolveDbPath, resolveProject, resolveRecipientPolicyReview, resolveRecipientPolicyReviewBulk, runSyncPass, schema, serializeRecipientPolicyCoordinatorGroupMutation, serializeRecipientPolicyPublicationMutation, serializeRecipientPolicyTeamMutation, setLegacyTeamSetupDeviceAssignment, setLegacyTeamSetupDeviceDecision, setLegacyTeamSetupProjectMapping, summarizeInboundScopeRejections, summaryLikeSqlPredicate, supportsSyncFeature, syncScopeResetRequiredPayload, tryUpdateRetrievalDelivery, updatePeerAddresses, upsertCoordinatorGroupPreference, upsertProjectScopeSettingsMapping, validateLegacyTeamSetupCompletionManifest, validateLegacyTeamSetupCompletionManifestBinding, verifyDirectPeerSignature, verifyRecipientReviewedIntent, verifySignature, writeCodememConfigFile } from "@codemem/core";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
 import { RateLimiter } from "limiter";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID } from "node:crypto";
 import { and, count, desc, eq, inArray, max, ne } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 import { homedir, hostname, networkInterfaces } from "node:os";
-import { createHash, randomUUID } from "node:crypto";
 //#region src/middleware.ts
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
 	"127.0.0.1",
@@ -513,6 +513,363 @@ function configRoutes(opts = {}) {
 	return app;
 }
 //#endregion
+//#region src/routes/diagnostics.ts
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 100;
+var CURSOR_KEY = randomBytes(32);
+var DIAGNOSTIC_SEVERITIES = [
+	"info",
+	"warning",
+	"error"
+];
+var DIAGNOSTIC_SUBSYSTEMS = [
+	"viewer",
+	"observer",
+	"capture",
+	"sync",
+	"storage",
+	"maintenance"
+];
+function opaqueId(kind, sourceId) {
+	return createHash("sha256").update(`${kind}\0${String(sourceId)}`).digest("base64url").slice(0, 22);
+}
+function encodeCursor(event) {
+	const iv = randomBytes(12);
+	const cipher = createCipheriv("aes-256-gcm", CURSOR_KEY, iv);
+	const plaintext = JSON.stringify({
+		occurredAt: event.occurred_at,
+		orderKey: event.orderKey
+	});
+	const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	return Buffer.concat([
+		iv,
+		cipher.getAuthTag(),
+		encrypted
+	]).toString("base64url");
+}
+function parseCursor(raw) {
+	if (!raw) return null;
+	try {
+		const encoded = Buffer.from(raw, "base64url");
+		if (encoded.length < 29) return "invalid";
+		const decipher = createDecipheriv("aes-256-gcm", CURSOR_KEY, encoded.subarray(0, 12));
+		decipher.setAuthTag(encoded.subarray(12, 28));
+		const plaintext = Buffer.concat([decipher.update(encoded.subarray(28)), decipher.final()]).toString("utf8");
+		const parsed = JSON.parse(plaintext);
+		if (typeof parsed.occurredAt !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9:.+-]+Z$/.test(parsed.occurredAt) || !Number.isFinite(Date.parse(parsed.occurredAt))) return "invalid";
+		if (typeof parsed.orderKey !== "string" || parsed.orderKey.length < 3 || parsed.orderKey.length > 2048) return "invalid";
+		return {
+			occurredAt: parsed.occurredAt,
+			orderKey: parsed.orderKey
+		};
+	} catch {
+		return "invalid";
+	}
+}
+function parseLimit(raw) {
+	if (raw == null || raw === "") return DEFAULT_LIMIT;
+	if (!/^\d+$/.test(raw)) return "invalid";
+	const parsed = Number(raw);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) return "invalid";
+	return Math.min(parsed, MAX_LIMIT);
+}
+function parseFilter(raw, allowed) {
+	if (raw == null) return new Set(allowed);
+	const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+	if (!values.length || values.some((value) => !allowed.includes(value))) return "invalid";
+	return new Set(values);
+}
+function parseTechnical(raw) {
+	if (raw == null || raw === "0") return false;
+	if (raw === "1") return true;
+	return "invalid";
+}
+function technicalDetail(available, text, include) {
+	if (!available) return { available: false };
+	return include ? {
+		available: true,
+		text: text.slice(0, 2e3)
+	} : { available: true };
+}
+var SYNC_OCCURRED_AT_SQL = "CASE WHEN finished_at IS NULL THEN started_at ELSE finished_at END";
+function syncSelect(options) {
+	if (!options.subsystems.has("sync")) return null;
+	const predicates = [];
+	if (!options.severities.has("info")) predicates.push("ok = 0");
+	if (!options.severities.has("error")) predicates.push("ok <> 0");
+	if (!options.severities.has("info") && !options.severities.has("error")) return null;
+	if (options.cursor) predicates.push(`(${SYNC_OCCURRED_AT_SQL} < @cursorOccurredAt OR
+			(${SYNC_OCCURRED_AT_SQL} = @cursorOccurredAt AND
+			's:' || printf('%020d', id) < @cursorOrderKey))`);
+	return `SELECT 'sync' AS source_type, id AS source_id,
+		's:' || printf('%020d', id) AS order_key,
+		${SYNC_OCCURRED_AT_SQL} AS occurred_at,
+		CASE WHEN ok <> 0 THEN 'succeeded' ELSE 'failed' END AS status,
+		ops_in AS metric_a, ops_out AS metric_b,
+		CASE
+			WHEN lower(error) LIKE '%auth%' OR lower(error) LIKE '%unauthorized%' THEN 'authentication'
+			WHEN lower(error) LIKE '%timeout%' OR lower(error) LIKE '%timed out%' THEN 'timeout'
+			WHEN lower(error) LIKE '%version%' OR lower(error) LIKE '%capability%' THEN 'compatibility'
+			WHEN lower(error) LIKE '%connect%' OR lower(error) LIKE '%network%'
+				OR lower(error) LIKE '%dns%' THEN 'connectivity'
+			ELSE 'unspecified'
+		END AS category
+		FROM sync_attempts ${predicates.length ? `WHERE ${predicates.join(" AND ")}` : ""}
+		ORDER BY ${SYNC_OCCURRED_AT_SQL} DESC, id DESC
+		LIMIT @sourceLimit`;
+}
+function observerSelect(options) {
+	if (!options.severities.has("error")) return null;
+	const observer = options.subsystems.has("observer");
+	const capture = options.subsystems.has("capture");
+	if (!observer && !capture) return null;
+	let providerFilter = "";
+	if (observer && !capture) providerFilter = "AND observer_provider IS NOT NULL";
+	if (capture && !observer) providerFilter = "AND observer_provider IS NULL";
+	const cursorFilter = options.cursor ? `AND (updated_at < @cursorOccurredAt OR
+			(updated_at = @cursorOccurredAt AND
+			'o:' || printf('%020d', id) < @cursorOrderKey))` : "";
+	return [
+		"error",
+		"failed",
+		"gave_up"
+	].map((status) => `SELECT * FROM (
+				SELECT
+					CASE WHEN observer_provider IS NULL THEN 'capture_failure' ELSE 'observer' END AS source_type,
+					id AS source_id, 'o:' || printf('%020d', id) AS order_key,
+					updated_at AS occurred_at, status, attempt_count AS metric_a,
+					NULL AS metric_b,
+					CASE
+						WHEN lower(COALESCE(observer_error_code, error_type)) LIKE '%auth%' THEN 'authentication'
+						WHEN lower(COALESCE(observer_error_code, error_type)) LIKE '%rate%'
+							OR lower(COALESCE(observer_error_code, error_type)) LIKE '%limit%' THEN 'rate limit'
+						WHEN lower(COALESCE(observer_error_code, error_type)) LIKE '%timeout%' THEN 'timeout'
+						WHEN lower(COALESCE(observer_error_code, error_type)) LIKE '%schema%'
+							OR lower(COALESCE(observer_error_code, error_type)) LIKE '%parse%' THEN 'response format'
+						ELSE 'unspecified'
+					END AS category
+				FROM raw_event_flush_batches
+				WHERE status = '${status}' ${providerFilter} ${cursorFilter}
+				ORDER BY updated_at DESC, id DESC
+				LIMIT @sourceLimit
+			)`).join(" UNION ALL ");
+}
+function maintenanceSelect(options) {
+	if (!options.subsystems.has("maintenance")) return null;
+	const statuses = [];
+	if (options.severities.has("info")) statuses.push("'pending'", "'running'");
+	if (options.severities.has("warning")) statuses.push("'cancelled'");
+	if (options.severities.has("error")) statuses.push("'failed'");
+	if (!statuses.length) return null;
+	return `SELECT 'maintenance' AS source_type, kind AS source_id,
+		'm:' || hex(kind) AS order_key, updated_at AS occurred_at,
+		status, progress_current AS metric_a, progress_total AS metric_b,
+		NULL AS category
+		FROM maintenance_jobs WHERE status IN (${statuses.join(", ")})`;
+}
+function backlogSelect(options) {
+	if (!options.subsystems.has("capture")) return null;
+	const warning = options.severities.has("warning");
+	const error = options.severities.has("error");
+	if (!warning && !error) return null;
+	let having = "pending >= 200";
+	if (!warning) having = "pending >= 1000";
+	if (!error) having = "pending >= 200 AND pending < 1000";
+	return `WITH candidate_sessions AS MATERIALIZED (
+			SELECT source, stream_id, last_flushed_event_seq, updated_at
+			FROM raw_event_sessions
+			WHERE last_received_event_seq > last_flushed_event_seq
+			ORDER BY updated_at DESC
+			LIMIT 1001
+		), bounded_sessions AS MATERIALIZED (
+			SELECT source, stream_id, last_flushed_event_seq, updated_at
+			FROM candidate_sessions
+			ORDER BY updated_at DESC
+			LIMIT 1000
+		), retained_sessions AS MATERIALIZED (
+			SELECT updated_at,
+				(SELECT COUNT(*) FROM raw_events AS events
+					WHERE events.source = sessions.source
+						AND events.stream_id = sessions.stream_id
+						AND events.event_seq > sessions.last_flushed_event_seq) AS pending
+			FROM bounded_sessions AS sessions
+		)
+		SELECT 'backlog' AS source_type, 0 AS source_id,
+		'b:' || printf('%020d', 0) AS order_key, occurred_at,
+		CASE WHEN pending >= 1000 THEN 'error' ELSE 'warning' END AS status,
+		pending AS metric_a, sessions AS metric_b,
+		CASE WHEN candidate_count > 1000 THEN 'capped' ELSE NULL END AS category
+		FROM (
+			SELECT MAX(updated_at) AS occurred_at,
+				SUM(pending) AS pending,
+				COUNT(*) FILTER (WHERE pending > 0) AS sessions,
+				(SELECT COUNT(*) FROM candidate_sessions) AS candidate_count
+			FROM retained_sessions
+			WHERE pending > 0
+		) WHERE ${having}`;
+}
+function sourceSelects(options) {
+	return [
+		syncSelect(options),
+		observerSelect(options),
+		maintenanceSelect(options),
+		backlogSelect(options)
+	].filter((select) => select != null);
+}
+function boundedSourceSelect(select, hasCursor) {
+	return `SELECT * FROM (
+		SELECT * FROM (${select})
+		${hasCursor ? "WHERE occurred_at < @cursorOccurredAt OR (occurred_at = @cursorOccurredAt AND order_key < @cursorOrderKey)" : ""}
+		ORDER BY occurred_at DESC, order_key DESC
+		LIMIT @sourceLimit
+	)`;
+}
+function loadSourceRows(store, options) {
+	const selects = sourceSelects(options);
+	if (!selects.length) return [];
+	const boundedSelects = selects.map((select) => boundedSourceSelect(select, options.cursor != null));
+	const params = {
+		resultLimit: options.limit + 1,
+		sourceLimit: options.limit + 1
+	};
+	if (options.cursor) {
+		params.cursorOccurredAt = options.cursor.occurredAt;
+		params.cursorOrderKey = options.cursor.orderKey;
+	}
+	return store.db.prepare(`SELECT * FROM (${boundedSelects.join(" UNION ALL ")})
+			 ORDER BY occurred_at DESC, order_key DESC
+			 LIMIT @resultLimit`).all(params);
+}
+function syncEvent(row, includeTechnical) {
+	const succeeded = row.status === "succeeded";
+	const opsIn = Number(row.metric_a ?? 0);
+	const opsOut = Number(row.metric_b ?? 0);
+	const category = row.category ?? "unspecified";
+	return {
+		id: opaqueId("sync-attempt", row.source_id),
+		orderKey: row.order_key,
+		occurred_at: row.occurred_at,
+		severity: succeeded ? "info" : "error",
+		subsystem: "sync",
+		code: succeeded ? "sync_attempt_succeeded" : "sync_attempt_failed",
+		message: succeeded ? "A sync attempt completed." : "A sync attempt failed before all work completed.",
+		recovery: succeeded ? void 0 : {
+			label: "Open advanced sync diagnostics",
+			href: "#advanced/sync/diagnostics"
+		},
+		technical_detail: technicalDetail(true, succeeded ? `${opsIn} inbound and ${opsOut} outbound operations.` : `Failure category: ${category}. ${opsIn} inbound and ${opsOut} outbound operations.`, includeTechnical)
+	};
+}
+function failureEvent(row, includeTechnical) {
+	const subsystem = row.source_type === "observer" ? "observer" : "capture";
+	const attempts = Math.max(0, Number(row.metric_a ?? 0));
+	const gaveUp = row.status === "gave_up";
+	return {
+		id: opaqueId("processing-failure", row.source_id),
+		orderKey: row.order_key,
+		occurred_at: row.occurred_at,
+		severity: "error",
+		subsystem,
+		code: `${subsystem}_flush_${gaveUp ? "gave_up" : "failed"}`,
+		message: gaveUp ? "Processing stopped after all retry attempts were exhausted." : "Processing failed and queued events are waiting for retry.",
+		recovery: {
+			label: "Open Health",
+			href: "#health"
+		},
+		technical_detail: technicalDetail(true, `Failure category: ${row.category ?? "unspecified"}. Attempts: ${attempts}.`, includeTechnical)
+	};
+}
+function maintenanceEvent(row, includeTechnical) {
+	let severity = "info";
+	let code = "maintenance_job_active";
+	let message = "A background maintenance task is active.";
+	if (row.status === "failed") {
+		severity = "error";
+		code = "maintenance_job_failed";
+		message = "A background maintenance task failed.";
+	} else if (row.status === "cancelled") {
+		severity = "warning";
+		code = "maintenance_job_cancelled";
+		message = "A background maintenance task was cancelled.";
+	}
+	const total = row.metric_b == null ? "unknown" : String(row.metric_b);
+	return {
+		id: opaqueId("maintenance", row.source_id),
+		orderKey: row.order_key,
+		occurred_at: row.occurred_at,
+		severity,
+		subsystem: "maintenance",
+		code,
+		message,
+		recovery: severity === "error" ? {
+			label: "Open Health",
+			href: "#health"
+		} : void 0,
+		technical_detail: technicalDetail(true, `Progress: ${Number(row.metric_a ?? 0)} of ${total}.`, includeTechnical)
+	};
+}
+function backlogEvent(row, includeTechnical) {
+	const severity = row.status === "error" ? "error" : "warning";
+	const pending = Number(row.metric_a ?? 0);
+	const sessions = Number(row.metric_b ?? 0);
+	const countPrefix = row.category === "capped" ? "At least " : "";
+	const sessionLabel = sessions === 1 ? "session" : "sessions";
+	return {
+		id: opaqueId("capture-backlog", 0),
+		orderKey: row.order_key,
+		occurred_at: row.occurred_at,
+		severity,
+		subsystem: "capture",
+		code: severity === "error" ? "capture_backlog_high" : "capture_backlog_growing",
+		message: severity === "error" ? "The capture queue has a high pending backlog." : "The capture queue is growing and may need attention.",
+		recovery: {
+			label: "Open Health",
+			href: "#health"
+		},
+		technical_detail: technicalDetail(true, `${countPrefix}${pending} pending events across ${sessions} ${sessionLabel}.`, includeTechnical)
+	};
+}
+function collectEvents(store, options) {
+	return loadSourceRows(store, options).map((row) => {
+		if (row.source_type === "sync") return syncEvent(row, options.includeTechnical);
+		if (row.source_type === "maintenance") return maintenanceEvent(row, options.includeTechnical);
+		if (row.source_type === "backlog") return backlogEvent(row, options.includeTechnical);
+		return failureEvent(row, options.includeTechnical);
+	});
+}
+function diagnosticsRoutes(getStore) {
+	const app = new Hono();
+	app.get("/api/diagnostics/events", (c) => {
+		const limit = parseLimit(c.req.query("limit"));
+		const cursor = parseCursor(c.req.query("cursor"));
+		const severities = parseFilter(c.req.query("severity"), DIAGNOSTIC_SEVERITIES);
+		const subsystems = parseFilter(c.req.query("subsystem"), DIAGNOSTIC_SUBSYSTEMS);
+		const includeTechnical = parseTechnical(c.req.query("includeTechnical"));
+		if (limit === "invalid" || cursor === "invalid" || severities === "invalid" || subsystems === "invalid" || includeTechnical === "invalid") return c.json({ error: "invalid_diagnostics_query" }, 400);
+		const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const events = collectEvents(getStore(), {
+			cursor,
+			includeTechnical,
+			limit,
+			severities,
+			subsystems
+		});
+		const orderedItems = events.slice(0, limit);
+		const items = orderedItems.map(({ orderKey: _orderKey, ...event }) => event);
+		const lastItem = orderedItems.at(-1);
+		const nextCursor = events.length > limit && lastItem ? encodeCursor(lastItem) : null;
+		c.header("Cache-Control", "no-store");
+		return c.json({
+			contract_version: 1,
+			items,
+			next_cursor: nextCursor,
+			redacted: true,
+			generated_at: generatedAt
+		});
+	});
+	return app;
+}
+//#endregion
 //#region src/routes/health.ts
 function databaseReachable(getStore) {
 	try {
@@ -801,18 +1158,6 @@ function countVisibleMemoryRows(store, filters) {
 	const row = store.db.prepare(`SELECT COUNT(*) AS total FROM ${from} WHERE ${clauses.join(" AND ")}`).get(...filterResult.params);
 	return Number(row?.total ?? 0);
 }
-function summaryLikeSqlPredicate() {
-	return `(
-		LOWER(TRIM(COALESCE(memory_items.kind, ''))) = 'session_summary'
-		OR (
-			json_valid(COALESCE(memory_items.metadata_json, ''))
-			AND (
-				COALESCE(json_type(memory_items.metadata_json, '$.is_summary') = 'true', 0)
-				OR LOWER(TRIM(COALESCE(json_extract(memory_items.metadata_json, '$.source'), ''))) = 'observer_summary'
-			)
-		)
-	)`;
-}
 function memorySearchSql(query) {
 	const textClause = `INSTR(codemem_casefold(
 		COALESCE(memory_items.title, '') || CHAR(10) ||
@@ -1351,9 +1696,12 @@ var PACK_KEYS = /* @__PURE__ */ new Set([
 	"compact_detail_count",
 	"db_path",
 	"identity_target",
-	"attempt"
+	"attempt",
+	"automatic_context"
 ]);
 var LEDGER_KEYS = /* @__PURE__ */ new Set([
+	"automatic_recall",
+	"evaluation_key",
 	"action",
 	"attempt_id",
 	"started_at",
@@ -1459,6 +1807,48 @@ function attemptMetadata(payload) {
 		requestId: payload.request_id ?? null
 	};
 }
+function validateAutomaticContext(value) {
+	if (value === null) return null;
+	if (!isRecord(value)) return "automatic_context must be an object or null";
+	for (const key of Object.keys(value)) if (key !== "source" && key !== "host_session_id") return `automatic_context contains unsupported field: ${key}`;
+	const source = value.source;
+	const hostSessionId = value.host_session_id;
+	if (typeof source !== "string" || !source.trim() || source.length > 64) return "automatic_context source is invalid";
+	if (typeof hostSessionId !== "string" || !hostSessionId.trim() || hostSessionId.length > MAX_METADATA_FIELD_CHARS || isAbsolutePath(hostSessionId)) return "automatic_context host_session_id is invalid";
+	return {
+		source: source.trim(),
+		hostSessionId: hostSessionId.trim()
+	};
+}
+function resolveRequestAutomaticContext(value, attempt) {
+	if (Object.hasOwn(value, "automatic_context")) return validateAutomaticContext(value.automatic_context);
+	if (!attempt) return void 0;
+	const source = typeof attempt.source === "string" ? attempt.source.trim().toLowerCase() : "";
+	if (source && source !== "opencode") return void 0;
+	const hostSessionId = attempt.source_session_id;
+	if (source === "opencode" && typeof hostSessionId === "string" && hostSessionId.trim()) return {
+		source,
+		hostSessionId: hostSessionId.trim()
+	};
+	return null;
+}
+function packRenderOptions(value) {
+	if (value.compact == null && value.compact_detail_count == null) return void 0;
+	return {
+		compact: value.compact === true || value.compact_detail_count != null,
+		...value.compact_detail_count != null ? { compactDetailCount: value.compact_detail_count } : {}
+	};
+}
+function packRequestArgs(request) {
+	return [
+		request.context,
+		request.limit,
+		request.tokenBudget,
+		request.filters,
+		request.renderOptions,
+		request.automaticContext
+	];
+}
 function validatePackRequest(value) {
 	if (!isRecord(value)) return "request body must be an object";
 	for (const key of Object.keys(value)) if (!PACK_KEYS.has(key)) return `request body contains unsupported field: ${key}`;
@@ -1490,6 +1880,8 @@ function validatePackRequest(value) {
 		if (attemptError) return attemptError;
 		attempt = value.attempt;
 	}
+	const automaticContext = resolveRequestAutomaticContext(value, attempt);
+	if (typeof automaticContext === "string") return automaticContext;
 	const filters = {};
 	if (value.all_projects !== true) {
 		const envProject = process.env.CODEMEM_PROJECT?.trim() || null;
@@ -1499,18 +1891,14 @@ function validatePackRequest(value) {
 		if (project) filters.project = project;
 	}
 	if (workingSetFiles.length > 0) filters.working_set_paths = workingSetFiles;
-	let renderOptions;
-	if (value.compact != null || value.compact_detail_count != null) renderOptions = {
-		compact: value.compact === true || value.compact_detail_count != null,
-		...value.compact_detail_count != null ? { compactDetailCount: value.compact_detail_count } : {}
-	};
 	return {
 		context,
 		limit,
 		tokenBudget,
 		filters,
-		renderOptions,
-		attempt
+		renderOptions: packRenderOptions(value),
+		attempt,
+		automaticContext
 	};
 }
 function ledgerFailureStatus(reason) {
@@ -1519,19 +1907,37 @@ function ledgerFailureStatus(reason) {
 	if (reason === "storage_unavailable") return 503;
 	return 400;
 }
+function dispatchRecallMeasurement(store, payload) {
+	const action = payload.action;
+	if (payload.automatic_recall === void 0 && action !== "recall") return null;
+	const isValidMeasurement = isAutomaticRecallMeasurement(payload.automatic_recall) && typeof payload.evaluation_key === "string" && /^[a-f0-9]{64}$/.test(payload.evaluation_key);
+	if (action === "delivery") {
+		if (!isValidMeasurement) return null;
+		try {
+			recordAutomaticRecall(store.db, payload.attempt_id, payload.evaluation_key, payload.automatic_recall);
+		} catch {}
+		return null;
+	}
+	if (action !== "recall" || !isValidMeasurement) return "invalid automatic recall measurement";
+	return recordAutomaticRecall(store.db, payload.attempt_id, payload.evaluation_key, payload.automatic_recall);
+}
 function dispatchLedger(store, payload) {
 	const action = payload.action;
-	if (action !== "record" && action !== "delivery" && action !== "cache_reuse") return "ledger action is invalid";
 	const metadata = attemptMetadata(payload);
 	if (action === "delivery") {
 		const status = payload.delivery_status;
 		if (status !== "handed_off" && status !== "failed" && status !== "unknown") return "delivery action requires a valid delivery_status";
-		return tryUpdateRetrievalDelivery(store.db, metadata.attemptId, status);
+		const outcome = tryUpdateRetrievalDelivery(store.db, metadata.attemptId, status);
+		if (outcome.ok) dispatchRecallMeasurement(store, payload);
+		return outcome;
 	}
+	const measurement = dispatchRecallMeasurement(store, payload);
+	if (measurement !== null) return measurement;
 	if (action === "cache_reuse") {
 		if (typeof payload.original_attempt_id !== "string" || !payload.original_attempt_id) return "cache_reuse action requires original_attempt_id";
 		return clonePromptPackAttempt(store.db, payload.original_attempt_id, metadata);
 	}
+	if (action !== "record") return "ledger action is invalid";
 	if (payload.retrieval_status !== "skipped" && payload.retrieval_status !== "failed" || typeof payload.failure_code !== "string" || !payload.failure_code || typeof payload.failure_stage !== "string" || !payload.failure_stage) return "record action requires retrieval_status, failure_code, and failure_stage";
 	return recordPromptPackTerminal(store.db, metadata, payload.retrieval_status, payload.failure_code, payload.failure_stage);
 }
@@ -1568,10 +1974,10 @@ function packTransportRoutes(getStore) {
 			const target = validateViewerTarget(store, parsed, { requireCurrentIdentity: true });
 			if (!target.ok) return c.json(target.body, target.status);
 			if (!request.attempt) {
-				const pack = await store.buildMemoryPackAsync(request.context, request.limit, request.tokenBudget, request.filters, request.renderOptions);
+				const pack = await store.buildMemoryPackAsync(...packRequestArgs(request));
 				return c.json(pack);
 			}
-			const artifacts = await store.buildMemoryPackWithTraceAsync(request.context, request.limit, request.tokenBudget, request.filters, request.renderOptions);
+			const artifacts = await store.buildMemoryPackWithTraceAsync(...packRequestArgs(request));
 			let ledgerArtifactFingerprint;
 			try {
 				ledgerArtifactFingerprint = promptPackArtifactFingerprint(store.db, request.context, request.filters, artifacts);
@@ -2128,7 +2534,7 @@ function statsRoutes(getStore) {
 			error: job.error
 		}));
 		return c.json({
-			...store.stats(),
+			...healthStats(store),
 			viewer_pid: process.pid,
 			maintenance_jobs: surfacedJobs
 		});
@@ -2193,6 +2599,15 @@ function statsRoutes(getStore) {
 	});
 	return app;
 }
+function healthStats(store) {
+	return {
+		...store.stats(),
+		automatic_recall: automaticRecallHealth(store.db, {
+			actorId: store.actorId,
+			deviceId: store.deviceId
+		})
+	};
+}
 //#endregion
 //#region src/routes/team-setup-view.ts
 var enabled = {
@@ -2922,10 +3337,10 @@ function projectMappingChoices(store) {
 			excludePeerReceived: true
 		}).filter((candidate) => !candidate.read_only && isLegacyTeamSetupProjectMappingIdentity(candidate.workspace_identity, store.db));
 	} catch (error) {
-		if (error instanceof Error && (error.message === "project_scope_candidate_scan_too_large" || error.message === "project_scope_candidate_metadata_too_large")) throw new Error("legacy_team_setup_roster_too_large");
+		if (error instanceof Error && (error.message === "project_scope_candidate_scan_too_large" || error.message === "project_scope_candidate_metadata_too_large")) throw new LocalProjectScanBudgetError(error);
 		throw error;
 	}
-	if (candidates.length > MAX_PROJECT_MAPPING_CHOICES) throw new Error("legacy_team_setup_roster_too_large");
+	if (candidates.length > MAX_PROJECT_MAPPING_CHOICES) throw new LocalProjectScanBudgetError();
 	return candidates.map((candidate) => ({
 		projectIdentity: candidate.workspace_identity,
 		sourceDisplayName: candidate.display_project
@@ -3001,6 +3416,156 @@ function completionApiError(error) {
 	const code = legacyTeamSetupApiErrorCode(error);
 	return code === "team_setup_failed" ? "team_setup_completion_unavailable" : code;
 }
+var TeamSetupFinishError = class extends Error {
+	reason;
+	alreadyLogged;
+	constructor(code, reason, alreadyLogged, cause) {
+		super(code, cause === void 0 ? void 0 : { cause });
+		this.reason = reason;
+		this.alreadyLogged = alreadyLogged;
+		this.name = "TeamSetupFinishError";
+	}
+};
+/**
+* The generic `legacy_team_setup_roster_too_large` string is thrown by ten
+* sites for unrelated limits (coordinator roster size, draft device count,
+* local project choices). Only the local project-candidate scan is a
+* "this device's history is too large" condition, so it carries a distinct
+* type. The message is kept identical so the frozen API-code mapping and every
+* existing caller that matches on it are unchanged.
+*/
+var LocalProjectScanBudgetError = class extends Error {
+	constructor(cause) {
+		super("legacy_team_setup_roster_too_large", cause === void 0 ? void 0 : { cause });
+		this.name = "LocalProjectScanBudgetError";
+	}
+};
+/**
+* Remote error codes the finish path can legitimately receive from the
+* coordinator. Anything else — including identifier-shaped values, which a
+* hostile or misconfigured upstream could use to smuggle a credential through
+* a JSON `error` field — is reduced to a fixed classification before logging.
+* A shape check is not an allowlist; only this set is echoed verbatim.
+*/
+var LOGGABLE_REMOTE_ERROR_CODES = /* @__PURE__ */ new Set([
+	"body_too_large",
+	"completion_manifest_invalid",
+	"completion_manifest_unavailable",
+	"completion_not_found",
+	"completion_query_invalid",
+	"group_archived",
+	"group_id_and_candidate_ref_required",
+	"group_not_found",
+	"invalid_json",
+	"missing_admin_header",
+	"not_found",
+	"rate_limited",
+	"response_too_large",
+	"unauthorized"
+]);
+function loggableRemoteCode(code) {
+	if (LOGGABLE_REMOTE_ERROR_CODES.has(code)) return code;
+	if (code.startsWith("non_json_response")) return "non_json_response";
+	return "unclassified_remote_error";
+}
+/**
+* Local causes the finish path can produce. Same allowlist discipline as
+* remote codes: everything else, including transport messages that embed the
+* target URL, is classified rather than echoed.
+*/
+var LOGGABLE_LOCAL_CAUSES = /* @__PURE__ */ new Set([
+	"completion_conflict",
+	"legacy_team_setup_roster_too_large",
+	"project_scope_candidate_metadata_too_large",
+	"project_scope_candidate_scan_too_large",
+	"team_setup_completion_conflict",
+	"team_setup_completion_invalid",
+	"team_setup_completion_unavailable",
+	"team_setup_confirmation_stale",
+	"team_setup_roster_unavailable"
+]);
+function loggableLocalCause(error) {
+	if (LOGGABLE_LOCAL_CAUSES.has(error.message)) return error.message;
+	if (error.name === "AbortError" || error.name === "TimeoutError") return error.name;
+	if (/fetch failed/iu.test(error.message)) return "fetch_failed";
+	if (/timed out|timeout/iu.test(error.message)) return "timed_out";
+	return `unclassified_error:${error.name || "Error"}`;
+}
+function errorChain(error) {
+	const chain = [];
+	let current = error;
+	while (current && !chain.includes(current)) {
+		chain.push(current);
+		current = current instanceof Error ? current.cause : void 0;
+	}
+	return chain;
+}
+function remoteFailureReason(remote, fallback) {
+	if (remote.status === 404 && (remote.code === "not_found" || remote.code.startsWith("non_json"))) return "coordinator_route_missing";
+	if (remote.status === 400 && remote.code === "completion_manifest_invalid") return "coordinator_rejected_manifest";
+	return fallback;
+}
+function teamSetupFinishFailureDetails(error) {
+	const chain = errorChain(error);
+	const wrapper = chain.find((item) => item instanceof TeamSetupFinishError);
+	const remote = chain.find((item) => item instanceof RemoteCoordinatorRequestError);
+	if (remote) {
+		const reason = remoteFailureReason(remote, wrapper?.reason);
+		return {
+			...reason ? { reason } : {},
+			cause: "remote coordinator request failed",
+			status: remote.status,
+			code: loggableRemoteCode(remote.code)
+		};
+	}
+	if (chain.some((item) => item instanceof LegacyTeamSetupRosterCapacityError || item instanceof LocalProjectScanBudgetError)) return {
+		reason: "local_candidate_scan_budget_exceeded",
+		cause: "local project candidate scan exceeded budget"
+	};
+	const errorCause = chain.find((item) => item instanceof Error && !(item instanceof TeamSetupFinishError));
+	const cause = errorCause ? loggableLocalCause(errorCause) : "unclassified_non_error";
+	if (wrapper?.reason) return {
+		reason: wrapper.reason,
+		cause
+	};
+	if (errorCause && (errorCause.name === "AbortError" || errorCause.name === "TimeoutError" || /fetch failed|timed out|timeout/iu.test(errorCause.message))) return {
+		reason: "coordinator_unreachable",
+		cause
+	};
+	return { cause };
+}
+function warnTeamSetupFinishFailure(error, details, context) {
+	if (errorChain(error).some((item) => item instanceof TeamSetupFinishError && item.alreadyLogged)) return;
+	const safe = (value) => {
+		let sanitized = String(value).replace(/[\r\n\t]+/gu, " ");
+		for (const secret of context.redactValues ?? []) if (secret) sanitized = sanitized.replaceAll(secret, "[redacted]");
+		return sanitized.replace(/https?:\/\/[^\s]+/giu, (value) => {
+			try {
+				const url = new URL(value);
+				return `${url.protocol}//${url.host}`;
+			} catch {
+				return "[redacted-url]";
+			}
+		});
+	};
+	const fields = [
+		`candidateRef=${safe(context.candidateRef)}`,
+		`attemptId=${safe(context.attemptId)}`,
+		`apiCode=${safe(context.apiCode)}`,
+		`cause=${safe(details.cause)}`,
+		...details.reason ? [`reason=${safe(details.reason)}`] : [],
+		...details.status == null ? [] : [`status=${safe(details.status)}`],
+		...details.code == null ? [] : [`code=${safe(details.code)}`]
+	];
+	console.warn(`[team-setup finish] ${fields.join(" ")}`);
+}
+function finishErrorResponse(code, details) {
+	const reason = details.reason;
+	return reason ? {
+		error: code,
+		reason
+	} : { error: code };
+}
 async function parseBoundedJsonObject(c) {
 	if (c.req.header("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") return { ok: false };
 	const lengthHeader = c.req.header("content-length");
@@ -3741,6 +4306,7 @@ function teamSetupRoutes(options) {
 		let releaseMutation;
 		let releasePublicationMutation;
 		let releaseActorMutations;
+		let finishLogRedactValues = [];
 		try {
 			const store = options.getStore();
 			const draft = getLegacyTeamSetupDraft(store.db, candidateRef);
@@ -3803,8 +4369,9 @@ function teamSetupRoutes(options) {
 				if (!completionDependencies || !authorization) throw new Error("team_setup_completion_unavailable");
 				if (!authorizesGroup(authorization, group)) throw new Error("team_setup_completion_invalid");
 				const { config, remoteUrl } = authorization;
+				finishLogRedactValues = [config.syncCoordinatorAdminSecret];
 				const freshGroup = await loadFreshGroupSnapshot(group, remoteUrl, publicationDeadlineMs);
-				if (!freshGroup) throw new Error("team_setup_roster_unavailable");
+				if (!freshGroup) throw new TeamSetupFinishError("team_setup_roster_unavailable", "coordinator_roster_unavailable", false, /* @__PURE__ */ new Error("coordinator roster unavailable"));
 				if (!stillAuthorizesGroup(authorization, group)) throw new Error("team_setup_completion_invalid");
 				const projectInventory = legacyTeamCandidateProjectInventory(store.db, projectionOptions(store), candidateRef);
 				const freshPreview = inspectFreshLegacyTeamSetupActivation(store.db, {
@@ -3845,8 +4412,17 @@ function teamSetupRoutes(options) {
 					if (canonicalCoordinatorLegacyTeamCompletionManifestJson(canonicalManifest) !== canonicalCoordinatorLegacyTeamCompletionManifestJson(proposedManifest)) throw new Error("team_setup_completion_conflict");
 				} catch (error) {
 					const code = completionApiError(error);
+					const details = teamSetupFinishFailureDetails(error);
 					const getCompletion = completionDependencies.get;
-					if (code !== "team_setup_completion_conflict" || !getCompletion) throw new Error(code);
+					if (code !== "team_setup_completion_conflict" || !getCompletion) {
+						warnTeamSetupFinishFailure(error, details, {
+							candidateRef,
+							attemptId,
+							apiCode: code,
+							redactValues: finishLogRedactValues
+						});
+						throw new TeamSetupFinishError(code, details.reason, true, error);
+					}
 					try {
 						const existing = await retryTransientCoordinatorRead((attemptTimeoutS) => getCompletion({
 							groupId: group.groupId,
@@ -3862,17 +4438,17 @@ function teamSetupRoutes(options) {
 						});
 						if (canonicalManifest.finish_digest !== proposedManifest.finish_digest) throw new Error("team_setup_completion_conflict");
 					} catch (recoveryError) {
-						throw new Error(completionApiError(recoveryError));
+						throw new TeamSetupFinishError(completionApiError(recoveryError), teamSetupFinishFailureDetails(recoveryError).reason, false, recoveryError);
 					}
 				}
 				let postPublicationGroup;
 				try {
 					postPublicationGroup = await loadFreshGroupSnapshot(group, remoteUrl, publicationDeadlineMs);
 				} catch (error) {
-					if (legacyTeamSetupApiErrorCode(error) === "team_setup_completion_invalid") throw new Error("team_setup_roster_unavailable");
+					if (legacyTeamSetupApiErrorCode(error) === "team_setup_completion_invalid") throw new TeamSetupFinishError("team_setup_roster_unavailable", "coordinator_roster_unavailable", false, error);
 					throw error;
 				}
-				if (!postPublicationGroup) throw new Error("team_setup_roster_unavailable");
+				if (!postPublicationGroup) throw new TeamSetupFinishError("team_setup_roster_unavailable", "coordinator_roster_unavailable", false, /* @__PURE__ */ new Error("coordinator roster unavailable"));
 				const result = await applyLegacyTeamSetupCompletionManifestAndReturnActivation(store.db, {
 					coordinatorId: group.coordinatorId,
 					groupId: group.groupId,
@@ -3889,7 +4465,14 @@ function teamSetupRoutes(options) {
 			}));
 		} catch (error) {
 			const code = apiErrorCode(error);
-			return c.json({ error: code }, errorStatus$1(code));
+			const details = teamSetupFinishFailureDetails(error);
+			warnTeamSetupFinishFailure(error, details, {
+				candidateRef,
+				attemptId,
+				apiCode: code,
+				redactValues: finishLogRedactValues
+			});
+			return c.json(finishErrorResponse(code, details), errorStatus$1(code));
 		} finally {
 			releaseActorMutations?.();
 			releasePublicationMutation?.();
@@ -10033,6 +10616,26 @@ function closeStore() {
 	sharedStore?.close();
 	sharedStore = null;
 }
+function registerStaticRoutes(app) {
+	const staticRoot = process.env.CODEMEM_VIEWER_STATIC_DIR ?? join(import.meta.dirname ?? ".", "../static");
+	app.use("/assets/*", async (c, next) => {
+		c.header("Cache-Control", "no-cache");
+		await next();
+	});
+	app.use("/assets/*", serveStatic({
+		root: staticRoot,
+		rewriteRequestPath: (path) => path.replace(/^\/assets/, ""),
+		precompressed: true
+	}));
+	const indexPath = join(staticRoot, "index.html");
+	if (!existsSync(indexPath)) throw new Error(`Viewer assets missing at ${indexPath}. Run \`pnpm build\` from the repo root before starting the viewer.`);
+	const indexHtml = readFileSync(indexPath, "utf-8");
+	app.get("*", (c) => {
+		if (c.req.path.startsWith("/api/")) return c.json({ error: "not found" }, 404);
+		c.header("Cache-Control", "no-store");
+		return c.html(indexHtml);
+	});
+}
 function createApp(opts) {
 	const storeFactory = opts?.storeFactory ?? getStore;
 	const sweeper = opts?.sweeper ?? null;
@@ -10043,6 +10646,7 @@ function createApp(opts) {
 	app.use("*", preflightHandler());
 	app.use("*", originGuard({ unsafeGetPathPrefixes: [TEAM_SETUP_ROUTE_PREFIX] }));
 	app.route("/", healthRoutes(storeFactory));
+	app.route("/", diagnosticsRoutes(storeFactory));
 	app.route("/", statsRoutes(storeFactory));
 	app.route("/", memoryRoutes(storeFactory));
 	app.route("/", packTransportRoutes(storeFactory));
@@ -10069,24 +10673,7 @@ function createApp(opts) {
 		}
 	}));
 	app.route("/", updateStatusRoutes({ getUpdateStatus: opts?.getUpdateStatus }));
-	const staticRoot = process.env.CODEMEM_VIEWER_STATIC_DIR ?? join(import.meta.dirname ?? ".", "../static");
-	app.use("/assets/*", async (c, next) => {
-		c.header("Cache-Control", "no-cache");
-		await next();
-	});
-	app.use("/assets/*", serveStatic({
-		root: staticRoot,
-		rewriteRequestPath: (path) => path.replace(/^\/assets/, ""),
-		precompressed: true
-	}));
-	const indexPath = join(staticRoot, "index.html");
-	if (!existsSync(indexPath)) throw new Error(`Viewer assets missing at ${indexPath}. Run \`pnpm build\` from the repo root before starting the viewer.`);
-	const indexHtml = readFileSync(indexPath, "utf-8");
-	app.get("*", (c) => {
-		if (c.req.path.startsWith("/api/")) return c.json({ error: "not found" }, 404);
-		c.header("Cache-Control", "no-store");
-		return c.html(indexHtml);
-	});
+	registerStaticRoutes(app);
 	return app;
 }
 /**