@gajae-code/coding-agent 0.12.6 → 0.12.8

package/src/sdk/bus/notification-service.ts

@@ -20,14 +20,25 @@ import type { Settings } from "../../config/settings";
 import { isProcessIncarnation, processIncarnation } from "../broker/process-incarnation";
 import {
 	getNotificationConfig,
-	isDiscordConfigured,
-	isGloballyConfigured,
-	isTelegramConfigured,
+	hasAnyCompleteProvider,
+	hasAnyEffectivelyEnabledProvider,
+	isDiscordComplete,
+	isProviderEffectivelyEnabled,
+	isSlackComplete,
+	isTelegramComplete,
 	maskToken,
 	type NotificationConfig,
+	type NotificationProvider,
+	type NotificationRuntime,
+	type ProviderResolution,
+	resolveNotificationProvider,
 	tokenFingerprint,
 } from "./config";
 import { type DaemonPaths, daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { DiscordLiveProvider } from "./discord-live-provider";
+import type { DiscordDiagnosticProvider } from "./discord-provider";
+import { SlackLiveProvider } from "./slack-live-provider";
+import type { SlackDiagnosticProvider } from "./slack-provider";
 import { type OwnerFreshnessSnapshot, readOwnerFreshnessSnapshot, type TelegramDaemonFs } from "./telegram-daemon";
 import { DAEMON_GENERATION } from "./telegram-daemon-contract";
 
@@ -52,6 +63,18 @@ export function sanitizeDiagnostic(text: string, token?: string): string {
 	return out.replace(TELEGRAM_TOKEN_PATTERN, "<redacted>");
 }
 
+function sanitizeProviderDiagnostic(text: string, cfg: NotificationConfig, provider: NotificationProvider): string {
+	const secrets =
+		provider === "telegram"
+			? [cfg.botToken]
+			: provider === "discord"
+				? [cfg.discord.botToken]
+				: [cfg.slack.botToken, cfg.slack.appToken];
+	let detail = text;
+	for (const secret of secrets) detail = sanitizeDiagnostic(detail, secret);
+	return detail;
+}
+
 /** Identity evidence required to remove precisely the endpoint that was inspected. */
 export interface NotificationEndpointFileIdentity {
 	dev: bigint;
@@ -161,6 +184,9 @@ export interface NotificationServiceDeps {
 	pidAlive?: (pid: number) => boolean;
 	fetchImpl?: typeof fetch;
 	apiBase?: string;
+	createDiscordDiagnostic?: (config: { applicationId: string; botToken: string }) => DiscordDiagnosticProvider;
+	createSlackDiagnostic?: (config: { appToken: string; botToken: string }) => SlackDiagnosticProvider;
+	providerRuntimeStatus?: (provider: NotificationProvider) => Promise<NotificationRuntime> | NotificationRuntime;
 }
 
 function defaultPidAlive(pid: number): boolean {
@@ -187,6 +213,12 @@ export interface AdapterConfigView {
 	botTokenMasked: string;
 	channel: string | undefined;
 	configured: boolean;
+	quarantined: boolean;
+	desiredEnabled: boolean;
+	desiredSource: ProviderResolution["desiredSource"];
+	effectiveEnabled: boolean;
+	issues: ProviderResolution["issues"];
+	runtime?: NotificationRuntime;
 }
 
 export interface NotificationStatusReport {
@@ -194,13 +226,30 @@ export interface NotificationStatusReport {
 	redact: boolean;
 	verbosity: "lean" | "verbose";
 	globallyConfigured: boolean;
+	anyProviderComplete: boolean;
+	anyProviderEffective: boolean;
 	telegram: AdapterConfigView & { tokenFingerprint: string | undefined };
 	discord: AdapterConfigView;
 	slack: AdapterConfigView;
 }
 
-function adapterConfigured(token: string | undefined, channel: string | undefined): boolean {
-	return Boolean(token?.trim()) && Boolean(channel?.trim());
+function adapterView(
+	cfg: NotificationConfig,
+	provider: NotificationProvider,
+	token: string | undefined,
+	channel: string | undefined,
+): AdapterConfigView {
+	const resolution = resolveNotificationProvider(cfg, provider);
+	return {
+		botTokenMasked: maskToken(token),
+		channel,
+		configured: resolution.configured,
+		quarantined: resolution.quarantined,
+		desiredEnabled: resolution.desiredEnabled,
+		desiredSource: resolution.desiredSource,
+		effectiveEnabled: resolution.effectiveEnabled,
+		issues: resolution.issues,
+	};
 }
 
 /** Build a secret-safe structured status snapshot from settings. */
@@ -210,43 +259,40 @@ export function buildNotificationStatusReport(settings: Settings): NotificationS
 		enabled: cfg.enabled,
 		redact: cfg.redact,
 		verbosity: cfg.verbosity,
-		globallyConfigured: isGloballyConfigured(cfg),
+		globallyConfigured: cfg.enabled && hasAnyCompleteProvider(cfg),
+		anyProviderComplete: hasAnyCompleteProvider(cfg),
+		anyProviderEffective: hasAnyEffectivelyEnabledProvider(cfg),
 		telegram: {
-			botTokenMasked: maskToken(cfg.botToken),
-			channel: cfg.chatId,
-			configured: isTelegramConfigured(cfg),
+			...adapterView(cfg, "telegram", cfg.botToken, cfg.chatId),
 			tokenFingerprint: cfg.botToken?.trim() ? tokenFingerprint(cfg.botToken) : undefined,
 		},
-		discord: {
-			botTokenMasked: maskToken(cfg.discord.botToken),
-			channel: cfg.discord.parentChannelId,
-			configured: isDiscordConfigured(cfg),
-		},
-		slack: {
-			botTokenMasked: maskToken(cfg.slack.botToken),
-			channel: cfg.slack.channelId,
-			configured: adapterConfigured(cfg.slack.botToken, cfg.slack.channelId),
-		},
+		discord: adapterView(cfg, "discord", cfg.discord.botToken, cfg.discord.parentChannelId),
+		slack: adapterView(cfg, "slack", cfg.slack.botToken, cfg.slack.channelId),
 	};
 }
 
 /** Render a status report as human-readable lines (no secrets). */
 export function formatNotificationStatusReport(report: NotificationStatusReport): string {
-	const yesNo = (v: boolean): string => (v ? "yes" : "no");
+	const yesNo = (value: boolean): string => (value ? "yes" : "no");
+	const provider = (name: NotificationProvider, view: AdapterConfigView): string[] => [
+		`  ${name}.configured: ${yesNo(view.configured)}`,
+		`  ${name}.needsRepair: ${yesNo(view.quarantined)}`,
+		`  ${name}.desired: ${view.desiredEnabled ? "on" : "off"} (${view.desiredSource})`,
+		`  ${name}.effective: ${yesNo(view.effectiveEnabled)}`,
+		`  ${name}.botToken: ${view.botTokenMasked}`,
+		`  ${name}.destination: ${view.channel ?? "(unset)"}`,
+	];
 	return [
 		"Notifications",
 		`  enabled: ${report.enabled}`,
-		`  globally configured: ${yesNo(report.globallyConfigured)}`,
+		`  any provider effective: ${yesNo(report.anyProviderEffective)}`,
+		`  any provider complete: ${yesNo(report.anyProviderComplete)}`,
 		`  redact: ${report.redact}`,
 		`  verbosity: ${report.verbosity}`,
-		`  telegram.botToken: ${report.telegram.botTokenMasked}`,
-		`  telegram.chatId: ${report.telegram.channel ?? "(unset)"}`,
+		...provider("telegram", report.telegram),
 		`  telegram.fingerprint: ${report.telegram.tokenFingerprint ?? "(unset)"}`,
-		`  telegram.configured: ${yesNo(report.telegram.configured)}`,
-		`  discord.botToken: ${report.discord.botTokenMasked}`,
-		`  discord.parentChannelId: ${report.discord.channel ?? "(unset)"}`,
-		`  slack.botToken: ${report.slack.botTokenMasked}`,
-		`  slack.channelId: ${report.slack.channel ?? "(unset)"}`,
+		...provider("discord", report.discord),
+		...provider("slack", report.slack),
 	].join("\n");
 }
 
@@ -508,6 +554,8 @@ export interface EndpointHealth {
 export interface NotificationHealthReport {
 	overall: HealthLevel;
 	configured: boolean;
+	provider?: NotificationProvider;
+	resolution?: ProviderResolution;
 	checks: HealthCheck[];
 	daemon: DaemonHealth;
 	endpoints: EndpointHealth;
@@ -518,20 +566,25 @@ export interface HealthOptions {
 	settings: Settings;
 	stateRoot?: string;
 	deps?: NotificationServiceDeps;
-	/** When true and Telegram is configured, probe the Bot API (getMe) for reachability. */
+	provider?: NotificationProvider;
+	/** When true, use the selected provider's REST-only diagnostic path. */
 	probe?: boolean;
+	signal?: AbortSignal;
 }
 
 async function probeTelegramReachability(
 	fetchImpl: typeof fetch,
 	apiBase: string,
 	token: string,
+	signal?: AbortSignal,
 ): Promise<{ ok: boolean; detail: string }> {
+	if (signal?.aborted) return { ok: false, detail: "Telegram probe cancelled." };
 	try {
 		const response = await fetchImpl(`${apiBase.replace(/\/$/, "")}/bot${token}/getMe`, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: "{}",
+			signal,
 		});
 		const payload = (await response.json().catch(() => undefined)) as
 			| { ok?: boolean; description?: string; result?: { username?: string } }
@@ -544,8 +597,78 @@ async function probeTelegramReachability(
 			ok: false,
 			detail: sanitizeDiagnostic(payload?.description ?? `Telegram getMe failed (HTTP ${response.status})`, token),
 		};
-	} catch (err) {
-		return { ok: false, detail: sanitizeDiagnostic(err instanceof Error ? err.message : "network error", token) };
+	} catch (error) {
+		if (signal?.aborted) return { ok: false, detail: "Telegram probe cancelled." };
+		return { ok: false, detail: sanitizeDiagnostic(error instanceof Error ? error.message : "network error", token) };
+	}
+}
+
+function effectiveProviders(cfg: NotificationConfig): NotificationProvider[] {
+	return (["telegram", "discord", "slack"] as const).filter(provider => isProviderEffectivelyEnabled(cfg, provider));
+}
+
+function selectNotificationProvider(
+	cfg: NotificationConfig,
+	requested: NotificationProvider | undefined,
+): NotificationProvider | undefined {
+	if (requested) return requested;
+	const effective = effectiveProviders(cfg);
+	return effective.length === 1 ? effective[0] : undefined;
+}
+
+async function probeSelectedProvider(
+	cfg: NotificationConfig,
+	provider: NotificationProvider,
+	deps: NotificationServiceDeps,
+	signal?: AbortSignal,
+): Promise<{ ok: boolean; detail: string }> {
+	try {
+		let result: { ok: boolean; detail: string };
+		if (provider === "telegram" && isTelegramComplete(cfg)) {
+			result = await probeTelegramReachability(
+				deps.fetchImpl ?? globalThis.fetch,
+				deps.apiBase ?? DEFAULT_API_BASE,
+				cfg.botToken,
+				signal,
+			);
+		} else if (provider === "discord" && isDiscordComplete(cfg)) {
+			const adapter =
+				deps.createDiscordDiagnostic?.({
+					applicationId: cfg.discord.applicationId,
+					botToken: cfg.discord.botToken,
+				}) ??
+				new DiscordLiveProvider({
+					applicationId: cfg.discord.applicationId,
+					botToken: cfg.discord.botToken,
+					fetchImpl: deps.fetchImpl,
+				});
+			result = await adapter.probeConfiguration(signal);
+		} else if (provider === "slack" && isSlackComplete(cfg)) {
+			const adapter =
+				deps.createSlackDiagnostic?.({ appToken: cfg.slack.appToken, botToken: cfg.slack.botToken }) ??
+				new SlackLiveProvider({
+					appToken: cfg.slack.appToken,
+					botToken: cfg.slack.botToken,
+					fetch: deps.fetchImpl,
+				});
+			const probe = await adapter.probeConfiguration(signal);
+			result =
+				probe.ok && (!probe.teamId || probe.teamId !== cfg.slack.workspaceId)
+					? { ok: false, detail: "Slack workspace identity does not match the configured workspace ID." }
+					: probe;
+		} else {
+			result = { ok: false, detail: `${provider} configuration is unavailable.` };
+		}
+		return { ...result, detail: sanitizeProviderDiagnostic(result.detail, cfg, provider) };
+	} catch (error) {
+		return {
+			ok: false,
+			detail: sanitizeProviderDiagnostic(
+				error instanceof Error ? error.message : `${provider} diagnostic failed.`,
+				cfg,
+				provider,
+			),
+		};
 	}
 }
 
@@ -563,11 +686,25 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 	const stateRoot = opts.stateRoot ?? defaultStateRoot();
 
 	const cfg: NotificationConfig = getNotificationConfig(opts.settings);
-	const configured = isGloballyConfigured(cfg);
-	const telegramConfigured = isTelegramConfigured(cfg);
+	const provider = selectNotificationProvider(cfg, opts.provider);
+	const resolution = provider ? resolveNotificationProvider(cfg, provider) : undefined;
+	const configured = resolution?.configured ?? hasAnyCompleteProvider(cfg);
+	const telegramConfigured = isTelegramComplete(cfg);
 	const checks: HealthCheck[] = [];
 
-	if (!cfg.enabled) {
+	if (provider && resolution?.quarantined) {
+		checks.push({ name: "config", level: "error", detail: `${provider} configuration needs repair` });
+	} else if (provider && !resolution?.configured) {
+		checks.push({ name: "config", level: "warn", detail: `${provider} is not fully configured` });
+	} else if (provider && !resolution?.desiredEnabled) {
+		checks.push({ name: "intent", level: "warn", detail: `${provider} desired intent is off` });
+	} else if (provider && !resolution?.effectiveEnabled) {
+		checks.push({
+			name: "config",
+			level: "warn",
+			detail: `${provider} is not effective while the global master is off`,
+		});
+	} else if (!cfg.enabled) {
 		checks.push({
 			name: "config",
 			level: "warn",
@@ -575,8 +712,24 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		});
 	} else if (!configured) {
 		checks.push({ name: "config", level: "warn", detail: "no notification adapter is fully configured" });
+	} else if (!provider && effectiveProviders(cfg).length === 0) {
+		checks.push({
+			name: "config",
+			level: "warn",
+			detail: "no configured provider currently has desired intent enabled",
+		});
+	} else if (!provider && effectiveProviders(cfg).length > 1) {
+		checks.push({
+			name: "selection",
+			level: "warn",
+			detail: "select a provider because multiple providers are effective",
+		});
 	} else {
-		checks.push({ name: "config", level: "ok", detail: "enabled with at least one configured adapter" });
+		checks.push({
+			name: "config",
+			level: "ok",
+			detail: provider ? `${provider} is effective` : "enabled with one configured adapter",
+		});
 	}
 
 	// Daemon ownership state (offline; corrupt or unreadable state degrades to a
@@ -612,26 +765,28 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		currentGeneration: DAEMON_GENERATION,
 		generationRelation: daemonGenerationRelation(state),
 	};
-	if (daemonStateUnreadable) {
-		checks.push({ name: "daemon", level: "warn", detail: "daemon ownership record is corrupt or unreadable" });
-	} else if (!state) {
-		checks.push({ name: "daemon", level: "ok", detail: "no daemon ownership record (none running)" });
-	} else if (!daemon.alive) {
-		checks.push({
-			name: "daemon",
-			level: "warn",
-			detail: `daemon owner pid ${daemon.pid} is not alive; run recovery to clear the stale lock`,
-		});
-	} else if (!daemon.heartbeatFresh) {
-		checks.push({ name: "daemon", level: "warn", detail: `daemon pid ${daemon.pid} heartbeat is stale` });
-	} else if (telegramConfigured && !daemon.identityMatches) {
-		checks.push({
-			name: "daemon",
-			level: "warn",
-			detail: "a live daemon owns a different bot token or chat id",
-		});
-	} else {
-		checks.push({ name: "daemon", level: "ok", detail: `daemon pid ${daemon.pid} alive with a fresh heartbeat` });
+	if (!provider || provider === "telegram") {
+		if (daemonStateUnreadable) {
+			checks.push({ name: "daemon", level: "warn", detail: "daemon ownership record is corrupt or unreadable" });
+		} else if (!state) {
+			checks.push({ name: "daemon", level: "ok", detail: "no daemon ownership record (none running)" });
+		} else if (!daemon.alive) {
+			checks.push({
+				name: "daemon",
+				level: "warn",
+				detail: `daemon owner pid ${daemon.pid} is not alive; run recovery to clear the stale lock`,
+			});
+		} else if (!daemon.heartbeatFresh) {
+			checks.push({ name: "daemon", level: "warn", detail: `daemon pid ${daemon.pid} heartbeat is stale` });
+		} else if (telegramConfigured && !daemon.identityMatches) {
+			checks.push({
+				name: "daemon",
+				level: "warn",
+				detail: "a live daemon owns a different bot token or chat id",
+			});
+		} else {
+			checks.push({ name: "daemon", level: "ok", detail: `daemon pid ${daemon.pid} alive with a fresh heartbeat` });
+		}
 	}
 
 	// Per-session endpoint discovery files.
@@ -667,54 +822,68 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		unknown: unknownEndpoints,
 		unreadable,
 	};
-	if (dead > 0 || unreadable > 0) {
-		checks.push({
-			name: "endpoints",
-			level: "warn",
-			detail: `${dead} dead / ${unreadable} unreadable of ${endpoints.total} endpoint file(s); run recovery`,
-		});
-	} else {
-		checks.push({
-			name: "endpoints",
-			level: "ok",
-			detail: `${live} live, ${unknownEndpoints} unverified endpoint file(s)`,
-		});
-	}
-	if (
-		telegramConfigured &&
-		daemon.present &&
-		daemon.alive &&
-		daemon.heartbeatFresh &&
-		daemon.identityMatches &&
-		!daemon.stopped &&
-		endpoints.total === 0
-	) {
-		checks.push({
-			name: "local_endpoint",
-			level: "warn",
-			detail:
-				"No local notification endpoint for this working directory. In this GJC terminal run /notify on; if it does not report notifications enabled, start a new local GJC session. Do not re-pair Telegram.",
-		});
+	if (!provider || provider === "telegram") {
+		if (dead > 0 || unreadable > 0) {
+			checks.push({
+				name: "endpoints",
+				level: "warn",
+				detail: `${dead} dead / ${unreadable} unreadable of ${endpoints.total} endpoint file(s); run recovery`,
+			});
+		} else {
+			checks.push({
+				name: "endpoints",
+				level: "ok",
+				detail: `${live} live, ${unknownEndpoints} unverified endpoint file(s)`,
+			});
+		}
+		if (
+			telegramConfigured &&
+			daemon.present &&
+			daemon.alive &&
+			daemon.heartbeatFresh &&
+			daemon.identityMatches &&
+			!daemon.stopped &&
+			endpoints.total === 0
+		) {
+			checks.push({
+				name: "local_endpoint",
+				level: "warn",
+				detail:
+					"No local notification endpoint for this working directory. In this GJC terminal run /notify on; if it does not report notifications enabled, start a new local GJC session. Do not re-pair Telegram.",
+			});
+		}
 	}
 
-	// Optional network reachability probe.
+	// Optional selected REST-only reachability probe.
 	let reachability = { probed: false, ok: false, detail: "not probed" };
-	if (opts.probe && telegramConfigured) {
-		const result = await probeTelegramReachability(
-			deps.fetchImpl ?? globalThis.fetch,
-			deps.apiBase ?? DEFAULT_API_BASE,
-			cfg.botToken,
-		);
-		reachability = { probed: true, ...result };
-		checks.push({
-			name: "reachability",
-			level: result.ok ? "ok" : "error",
-			detail: `Telegram: ${result.detail}`,
-		});
+	if (opts.probe) {
+		if (!provider) {
+			reachability = { probed: false, ok: false, detail: "provider selection required" };
+			checks.push({ name: "reachability", level: "error", detail: "provider selection required" });
+		} else if (!resolution?.configured || resolution.quarantined) {
+			reachability = { probed: false, ok: false, detail: `${provider} is unavailable` };
+			checks.push({ name: "reachability", level: "error", detail: `${provider} is unavailable` });
+		} else {
+			const result = await probeSelectedProvider(cfg, provider, deps, opts.signal);
+			reachability = { probed: true, ...result };
+			checks.push({
+				name: "reachability",
+				level: result.ok ? "ok" : "error",
+				detail: `${provider}: ${result.detail}`,
+			});
+		}
 	}
 
 	const overall = checks.reduce<HealthLevel>((acc, check) => worst(acc, check.level), "ok");
-	return { overall, configured, checks, daemon, endpoints, reachability };
+	return {
+		overall,
+		configured,
+		...(provider ? { provider, resolution } : {}),
+		checks,
+		daemon,
+		endpoints,
+		reachability,
+	};
 }
 
 /** Render a health report as human-readable lines (no secrets). */
@@ -731,66 +900,198 @@ export function formatNotificationHealthReport(report: NotificationHealthReport)
 
 export interface NotificationTestResult {
 	ok: boolean;
-	adapter: "telegram";
-	chatId: string | undefined;
+	adapter?: NotificationProvider;
+	destination?: string;
 	detail: string;
+	uncertain?: boolean;
 }
 
 export interface TestOptions {
 	settings: Settings;
 	deps?: NotificationServiceDeps;
+	provider?: NotificationProvider;
 	text?: string;
+	signal?: AbortSignal;
+}
+
+async function selectedProviderRuntimeReady(
+	provider: NotificationProvider,
+	deps: NotificationServiceDeps,
+): Promise<boolean> {
+	if (!deps.providerRuntimeStatus) return false;
+	const status = await deps.providerRuntimeStatus(provider);
+	return status === "ready" || status === "attached";
 }
 
-/** Send a one-off test notification through the configured Telegram adapter. */
+/** Send a one-off test through exactly one durable, effective provider. */
 export async function sendNotificationTest(opts: TestOptions): Promise<NotificationTestResult> {
 	const deps = opts.deps ?? {};
 	const cfg = getNotificationConfig(opts.settings);
-	if (!isTelegramConfigured(cfg)) {
+	const provider = selectNotificationProvider(cfg, opts.provider);
+	if (!provider) {
 		return {
 			ok: false,
-			adapter: "telegram",
-			chatId: cfg.chatId,
-			detail: "Telegram is not configured (need notifications.enabled + botToken + chatId). Run `gjc notify setup`.",
+			detail:
+				effectiveProviders(cfg).length === 0
+					? "No notification provider is effective. Configure and enable one provider first."
+					: "Multiple notification providers are effective; select one with --provider.",
 		};
 	}
-	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-	const apiBase = (deps.apiBase ?? DEFAULT_API_BASE).replace(/\/$/, "");
-	const text = opts.text ?? "GJC notifications test message. If you can read this, delivery works.";
-	try {
-		const response = await fetchImpl(`${apiBase}/bot${cfg.botToken}/sendMessage`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({ chat_id: cfg.chatId, text }),
-		});
-		const payload = (await response.json().catch(() => undefined)) as
-			| { ok?: boolean; description?: string }
-			| undefined;
-		if (response.ok && payload?.ok) {
-			return { ok: true, adapter: "telegram", chatId: cfg.chatId, detail: `delivered to chat ${cfg.chatId}` };
-		}
+	const resolution = resolveNotificationProvider(cfg, provider);
+	if (!resolution.effectiveEnabled) {
 		return {
 			ok: false,
-			adapter: "telegram",
-			chatId: cfg.chatId,
-			detail: sanitizeDiagnostic(
-				payload?.description ?? `Telegram sendMessage failed (HTTP ${response.status})`,
-				cfg.botToken,
-			),
+			adapter: provider,
+			detail: resolution.quarantined
+				? `${provider} configuration needs repair.`
+				: `${provider} is unavailable because configuration, desired intent, or the global master is off.`,
 		};
-	} catch (err) {
+	}
+	try {
+		if (!(await selectedProviderRuntimeReady(provider, deps))) {
+			return { ok: false, adapter: provider, detail: `${provider} runtime is not ready or attached.` };
+		}
+	} catch (error) {
 		return {
 			ok: false,
-			adapter: "telegram",
-			chatId: cfg.chatId,
-			detail: sanitizeDiagnostic(err instanceof Error ? err.message : "network error", cfg.botToken),
+			adapter: provider,
+			detail: sanitizeProviderDiagnostic(
+				error instanceof Error ? error.message : `${provider} runtime readiness check failed.`,
+				cfg,
+				provider,
+			),
 		};
 	}
+	if (opts.signal?.aborted)
+		return { ok: false, adapter: provider, detail: `${provider} notification test cancelled.` };
+	const text = opts.text ?? "GJC notifications test message. If you can read this, delivery works.";
+	if (provider === "telegram" && isTelegramComplete(cfg)) {
+		const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+		const apiBase = (deps.apiBase ?? DEFAULT_API_BASE).replace(/\/$/, "");
+		try {
+			const response = await fetchImpl(`${apiBase}/bot${cfg.botToken}/sendMessage`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ chat_id: cfg.chatId, text }),
+				signal: opts.signal,
+			});
+			const payload = (await response.json().catch(() => undefined)) as
+				| { ok?: boolean; description?: string; result?: { message_id?: unknown } }
+				| undefined;
+			const messageId = payload?.result?.message_id;
+			if (response.ok && payload?.ok === true && typeof messageId === "number" && Number.isSafeInteger(messageId)) {
+				return {
+					ok: true,
+					adapter: "telegram",
+					destination: cfg.chatId,
+					detail: `delivered to chat ${cfg.chatId}`,
+				};
+			}
+			const uncertain = response.ok && payload?.ok !== false;
+			return {
+				ok: false,
+				adapter: "telegram",
+				destination: cfg.chatId,
+				...(uncertain ? { uncertain: true } : {}),
+				detail: sanitizeDiagnostic(
+					uncertain
+						? "Telegram may have accepted the message but returned no usable message receipt."
+						: (payload?.description ?? `Telegram sendMessage failed (HTTP ${response.status})`),
+					cfg.botToken,
+				),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				adapter: "telegram",
+				destination: cfg.chatId,
+				uncertain: true,
+				detail: opts.signal?.aborted
+					? "Telegram notification delivery is uncertain because cancellation raced with dispatch."
+					: sanitizeDiagnostic(error instanceof Error ? error.message : "network error", cfg.botToken),
+			};
+		}
+	}
+	if (provider === "discord" && isDiscordComplete(cfg)) {
+		try {
+			const adapter =
+				deps.createDiscordDiagnostic?.({
+					applicationId: cfg.discord.applicationId,
+					botToken: cfg.discord.botToken,
+				}) ??
+				new DiscordLiveProvider({
+					applicationId: cfg.discord.applicationId,
+					botToken: cfg.discord.botToken,
+					fetchImpl: deps.fetchImpl,
+				});
+			const result = await adapter.sendOneShotTest({
+				channelId: cfg.discord.parentChannelId,
+				message: text,
+				signal: opts.signal,
+			});
+			return {
+				ok: result.ok,
+				adapter: "discord",
+				destination: cfg.discord.parentChannelId,
+				detail: sanitizeProviderDiagnostic(result.detail, cfg, "discord"),
+				...(result.uncertain ? { uncertain: true } : {}),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				adapter: "discord",
+				destination: cfg.discord.parentChannelId,
+				uncertain: true,
+				detail: sanitizeProviderDiagnostic(
+					error instanceof Error ? error.message : "Discord notification delivery failed.",
+					cfg,
+					"discord",
+				),
+			};
+		}
+	}
+	if (provider === "slack" && isSlackComplete(cfg)) {
+		try {
+			const adapter =
+				deps.createSlackDiagnostic?.({ appToken: cfg.slack.appToken, botToken: cfg.slack.botToken }) ??
+				new SlackLiveProvider({
+					appToken: cfg.slack.appToken,
+					botToken: cfg.slack.botToken,
+					fetch: deps.fetchImpl,
+				});
+			const result = await adapter.sendOneShotTest({
+				channel: cfg.slack.channelId,
+				message: text,
+				idempotencyKey: crypto.randomUUID(),
+				signal: opts.signal,
+			});
+			return {
+				ok: result.ok,
+				adapter: "slack",
+				destination: cfg.slack.channelId,
+				detail: sanitizeProviderDiagnostic(result.detail, cfg, "slack"),
+				...(result.uncertain ? { uncertain: true } : {}),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				adapter: "slack",
+				destination: cfg.slack.channelId,
+				uncertain: true,
+				detail: sanitizeProviderDiagnostic(
+					error instanceof Error ? error.message : "Slack notification delivery failed.",
+					cfg,
+					"slack",
+				),
+			};
+		}
+	}
+	return { ok: false, adapter: provider, detail: `${provider} configuration is unavailable.` };
 }
 
 /** Render a test result as a single human-readable line (no secrets). */
 export function formatNotificationTestResult(result: NotificationTestResult): string {
-	return `Notification test (${result.adapter}): ${result.ok ? "OK" : "FAILED"} — ${result.detail}`;
+	return `Notification test (${result.adapter ?? "unselected"}): ${result.ok ? "OK" : result.uncertain ? "UNCERTAIN" : "FAILED"} — ${result.detail}`;
 }
 
 // --- recovery -----------------------------------------------------------