@codemem/server 0.44.0-alpha.1 → 0.44.0-beta.1

package/dist/index.js

@@ -1,6 +1,6 @@
 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, 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 { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
@@ -2922,10 +2922,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 +3001,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 +3891,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 +3954,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 +3997,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 +4023,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 +4050,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?.();