@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/{notifications → sdk/bus}/notification-service.ts

@@ -12,9 +12,10 @@
  */
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
-import type { Settings } from "../config/settings";
+import type { Settings } from "../../config/settings";
 import {
 	getNotificationConfig,
+	isDiscordConfigured,
 	isGloballyConfigured,
 	isTelegramConfigured,
 	maskToken,
@@ -22,7 +23,7 @@ import {
 	tokenFingerprint,
 } from "./config";
 import { type DaemonPaths, daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
-import type { DaemonState } from "./telegram-daemon";
+import { DAEMON_GENERATION } from "./telegram-daemon-contract";
 
 const DEFAULT_API_BASE = "https://api.telegram.org";
 
@@ -139,8 +140,8 @@ export function buildNotificationStatusReport(settings: Settings): NotificationS
 		},
 		discord: {
 			botTokenMasked: maskToken(cfg.discord.botToken),
-			channel: cfg.discord.channelId,
-			configured: adapterConfigured(cfg.discord.botToken, cfg.discord.channelId),
+			channel: cfg.discord.parentChannelId,
+			configured: isDiscordConfigured(cfg),
 		},
 		slack: {
 			botTokenMasked: maskToken(cfg.slack.botToken),
@@ -164,7 +165,7 @@ export function formatNotificationStatusReport(report: NotificationStatusReport)
 		`  telegram.fingerprint: ${report.telegram.tokenFingerprint ?? "(unset)"}`,
 		`  telegram.configured: ${yesNo(report.telegram.configured)}`,
 		`  discord.botToken: ${report.discord.botTokenMasked}`,
-		`  discord.channelId: ${report.discord.channel ?? "(unset)"}`,
+		`  discord.parentChannelId: ${report.discord.channel ?? "(unset)"}`,
 		`  slack.botToken: ${report.slack.botTokenMasked}`,
 		`  slack.channelId: ${report.slack.channel ?? "(unset)"}`,
 	].join("\n");
@@ -215,7 +216,36 @@ async function readEndpointView(fs: NotificationServiceFs, file: string): Promis
 	};
 }
 
-function parseDaemonState(raw: string): DaemonState | undefined {
+interface NormalizedDaemonState {
+	pid: number;
+	ownerId: string;
+	tokenFingerprint: string | undefined;
+	chatId: string | undefined;
+	startedAt: number | undefined;
+	heartbeatAt: number | undefined;
+	stoppedAt: number | undefined;
+	roots: string[] | undefined;
+	generation: number | undefined;
+	generationStatus: "missing" | "valid" | "invalid";
+}
+
+function finiteNonNegativeNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function safePositiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function safeNonNegativeInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+	return Array.isArray(value) && value.every(item => typeof item === "string") ? value : undefined;
+}
+
+function parseDaemonState(raw: string): NormalizedDaemonState | undefined {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(raw);
@@ -224,11 +254,33 @@ function parseDaemonState(raw: string): DaemonState | undefined {
 	}
 	if (!parsed || typeof parsed !== "object") return undefined;
 	const rec = parsed as Record<string, unknown>;
-	if (typeof rec.pid !== "number" || typeof rec.ownerId !== "string") return undefined;
-	return parsed as DaemonState;
+	const pid = safePositiveInteger(rec.pid);
+	if (pid === undefined || typeof rec.ownerId !== "string" || rec.ownerId.length === 0) return undefined;
+
+	const generation = safeNonNegativeInteger(rec.generation);
+	const generationStatus = !Object.hasOwn(rec, "generation")
+		? "missing"
+		: generation === undefined
+			? "invalid"
+			: "valid";
+	return {
+		pid,
+		ownerId: rec.ownerId,
+		tokenFingerprint: typeof rec.tokenFingerprint === "string" ? rec.tokenFingerprint : undefined,
+		chatId: typeof rec.chatId === "string" ? rec.chatId : undefined,
+		startedAt: finiteNonNegativeNumber(rec.startedAt),
+		heartbeatAt: finiteNonNegativeNumber(rec.heartbeatAt),
+		stoppedAt: finiteNonNegativeNumber(rec.stoppedAt),
+		roots: stringArray(rec.roots),
+		generation,
+		generationStatus,
+	};
 }
 
-async function readDaemonStateFile(fs: NotificationServiceFs, file: string): Promise<DaemonState | undefined> {
+async function readDaemonStateFile(
+	fs: NotificationServiceFs,
+	file: string,
+): Promise<NormalizedDaemonState | undefined> {
 	try {
 		return parseDaemonState(await fs.readFile(file, "utf8"));
 	} catch {
@@ -262,8 +314,28 @@ export interface DaemonHealth {
 	heartbeatFresh: boolean;
 	identityMatches: boolean;
 	stopped: boolean;
+	heartbeatAt: number | undefined;
+	heartbeatAgeMs: number | undefined;
+	generation: number | undefined;
+	currentGeneration: number;
+	generationRelation: DaemonGenerationRelation;
+}
+
+export type DaemonGenerationRelation = "pre_generation" | "older" | "current" | "newer" | "unknown";
+
+function daemonGenerationRelation(state: NormalizedDaemonState | undefined): DaemonGenerationRelation {
+	if (!state) return "unknown";
+	if (state.generationStatus === "missing") return "pre_generation";
+	if (state.generation === undefined) return "unknown";
+	if (state.generation < DAEMON_GENERATION) return "older";
+	if (state.generation === DAEMON_GENERATION) return "current";
+	return "newer";
 }
 
+function displayHeartbeatAgeMs(now: number, heartbeatAt: number): number | undefined {
+	const age = now - heartbeatAt;
+	return Number.isFinite(age) ? Math.max(0, age) : undefined;
+}
 export interface EndpointHealth {
 	total: number;
 	live: number;
@@ -349,18 +421,24 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 	// Daemon ownership state (offline; read the persisted state file directly).
 	const paths = daemonPaths(opts.settings.getAgentDir());
 	const state = await readDaemonStateFile(fs, paths.state);
+	const heartbeatAt = state?.heartbeatAt;
 	const daemon: DaemonHealth = {
 		present: Boolean(state),
 		ownerId: state?.ownerId,
 		pid: state?.pid,
 		alive: state ? pidAlive(state.pid) : false,
-		heartbeatFresh: state ? now - state.heartbeatAt <= HEARTBEAT_TTL_MS : false,
+		heartbeatFresh: heartbeatAt !== undefined ? now - heartbeatAt <= HEARTBEAT_TTL_MS : false,
 		identityMatches:
 			Boolean(state) &&
 			telegramConfigured &&
 			state?.tokenFingerprint === tokenFingerprint(cfg.botToken) &&
 			state?.chatId === cfg.chatId,
-		stopped: typeof state?.stoppedAt === "number",
+		stopped: state?.stoppedAt !== undefined,
+		heartbeatAt,
+		heartbeatAgeMs: heartbeatAt === undefined ? undefined : displayHeartbeatAgeMs(now, heartbeatAt),
+		generation: state?.generation,
+		currentGeneration: DAEMON_GENERATION,
+		generationRelation: daemonGenerationRelation(state),
 	};
 	if (!state) {
 		checks.push({ name: "daemon", level: "ok", detail: "no daemon ownership record (none running)" });
@@ -421,6 +499,22 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 			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.
 	let reachability = { probed: false, ok: false, detail: "not probed" };
@@ -566,7 +660,7 @@ async function removeDeadOwnerLock(
 	fs: NotificationServiceFs,
 	paths: DaemonPaths,
 	pidAlive: (pid: number) => boolean,
-	expected: DaemonState,
+	expected: NormalizedDaemonState,
 ): Promise<"cleared" | "contended" | "superseded" | "now-alive" | "unlink-failed"> {
 	if (!(await fs.createExclusive(paths.steal))) return "contended";
 	try {

package/src/sdk/bus/session-control.ts

@@ -0,0 +1,333 @@
+import {
+	getCurrentTelegramActivationMarker,
+	isSessionNotificationsEnabled,
+	isTelegramConfigured,
+	type NotificationConfig,
+} from "./config";
+
+/** Minimal session-manager surface shared by extension, TUI, and headless hosts. */
+export interface NotificationSessionContext {
+	sessionManager: {
+		getCwd(): string;
+		getSessionId(): string;
+	};
+}
+
+/** A snapshot of the current session, resolved from the session manager per operation. */
+export interface BoundNotificationSession<Context extends NotificationSessionContext = NotificationSessionContext> {
+	readonly context: Context;
+	readonly cwd: string;
+	readonly sessionId: string;
+	unbind(): void;
+}
+
+export type NotificationEndpointStartResult = "started" | "already" | "disabled" | "failed";
+export type TelegramDaemonPreflightResult = "ready" | "blocked_identity";
+
+/**
+ * The endpoint implementation is deliberately injected. The controller owns
+ * policy and session-local state while the extension continues to own its
+ * concrete NotificationServer resources.
+ */
+export interface NotificationSessionRuntime<Context extends NotificationSessionContext = NotificationSessionContext> {
+	isRunning(binding: BoundNotificationSession<Context>): boolean;
+	start(binding: BoundNotificationSession<Context>): Promise<NotificationEndpointStartResult>;
+	stop(binding: BoundNotificationSession<Context>): Promise<boolean>;
+	/**
+	 * Proves the complete Telegram owner identity before a generic endpoint can
+	 * emit a frame. `blocked_identity` is fail-closed and starts nothing.
+	 */
+	ensureTelegramDaemon?(binding: BoundNotificationSession<Context>): Promise<TelegramDaemonPreflightResult>;
+}
+
+export interface NotificationSessionStatus {
+	eligible: boolean;
+	locallyEnabled: boolean;
+	effectiveEnabled: boolean;
+	running: boolean;
+	environment: "off" | "explicit" | "token" | "default";
+}
+
+export interface NotificationSessionReconcileResult {
+	outcome: NotificationEndpointStartResult | "stopped";
+	status: NotificationSessionStatus;
+}
+
+export interface NotificationSessionControllerOptions {
+	/** Gate A result, resolved once by the SDK from the canonical host predicate. */
+	eligible: boolean;
+	/** Reads the global-only, schema-default-resolved notification configuration. */
+	getConfig(): NotificationConfig;
+	/** Kept as a reference so test and embedding hosts can supply their own environment. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Shared owner of notification session policy.
+ *
+ * Gate A is captured at creation. Gate B is evaluated for each session
+ * operation with `isSessionNotificationsEnabled`. Gate C verifies complete
+ * Telegram ownership before a generic endpoint is allowed to start.
+ */
+export class NotificationSessionController {
+	readonly #eligible: boolean;
+	readonly #getConfig: () => NotificationConfig;
+	readonly #env: NodeJS.ProcessEnv;
+	readonly #disabledSessions = new Set<string>();
+	/** Sessions held inactive after a post-commit foreign daemon identity race. */
+	readonly #blockedRuntimeSessions = new Set<string>();
+	/** Sessions closed during host shutdown; no queued operation may restart them. */
+	readonly #shuttingDownSessions = new Set<string>();
+	/** Serializes endpoint mutations for each bound session snapshot. */
+	readonly #sessionOperations = new Map<string, Promise<void>>();
+	#runtime: NotificationSessionRuntime<NotificationSessionContext> | undefined;
+
+	constructor(options: NotificationSessionControllerOptions) {
+		this.#eligible = options.eligible;
+		this.#getConfig = options.getConfig;
+		this.#env = options.env ?? process.env;
+	}
+
+	/** Attach the concrete generic endpoint implementation used by this host. */
+	attachRuntime<Context extends NotificationSessionContext>(runtime: NotificationSessionRuntime<Context>): () => void {
+		const attached = runtime as unknown as NotificationSessionRuntime<NotificationSessionContext>;
+		this.#runtime = attached;
+		return () => {
+			if (this.#runtime === attached) this.#runtime = undefined;
+		};
+	}
+
+	/**
+	 * Bind a fresh session snapshot. Callers should not cache it: cwd and session
+	 * id may change on `/new`, fork, or resume.
+	 */
+	bind<Context extends NotificationSessionContext>(context: Context): BoundNotificationSession<Context> {
+		let bound = true;
+		const getCwd = context.sessionManager.getCwd;
+		const cwd =
+			typeof getCwd === "function" ? getCwd.call(context.sessionManager) : (context as { cwd?: unknown }).cwd;
+		if (typeof cwd !== "string" || cwd.length === 0) {
+			throw new Error("Notification session context does not expose a cwd.");
+		}
+		return {
+			cwd,
+			sessionId: context.sessionManager.getSessionId(),
+			unbind: () => {
+				bound = false;
+			},
+			get context() {
+				if (!bound) throw new Error("Notification session binding has been released.");
+				return context;
+			},
+		};
+	}
+
+	/** Preserve session-local safety state and pending-operation ownership across a session rekey. */
+	rekeySession(previousSessionId: string, nextSessionId: string): void {
+		if (previousSessionId === nextSessionId) return;
+		if (this.#disabledSessions.delete(previousSessionId)) this.#disabledSessions.add(nextSessionId);
+		if (this.#blockedRuntimeSessions.delete(previousSessionId)) this.#blockedRuntimeSessions.add(nextSessionId);
+		if (this.#shuttingDownSessions.delete(previousSessionId)) this.#shuttingDownSessions.add(nextSessionId);
+
+		const previousOperation = this.#sessionOperations.get(previousSessionId);
+		if (!previousOperation) return;
+		const nextOperation = this.#sessionOperations.get(nextSessionId);
+		const completion = nextOperation ? previousOperation.then(() => nextOperation) : previousOperation;
+		this.#sessionOperations.delete(previousSessionId);
+		this.#sessionOperations.set(nextSessionId, completion);
+		void completion.then(() => {
+			if (this.#sessionOperations.get(nextSessionId) === completion) {
+				this.#sessionOperations.delete(nextSessionId);
+			}
+		});
+	}
+
+	query<Context extends NotificationSessionContext>(context: Context): NotificationSessionStatus {
+		const binding = this.bind(context);
+		try {
+			return this.#query(binding);
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	/** Stop the current endpoint during host shutdown without changing local preference. */
+	async stopCurrentSession<Context extends NotificationSessionContext>(context: Context): Promise<boolean> {
+		const binding = this.bind(context);
+		try {
+			// Set this before joining the queue so an in-flight start self-stops before
+			// shutdown resolves, and no later operation can restart this session.
+			this.#shuttingDownSessions.add(binding.sessionId);
+			return await this.#enqueue(binding, async () => {
+				const runtime = this.#runtime as NotificationSessionRuntime<Context> | undefined;
+				return runtime?.isRunning(binding) ? await runtime.stop(binding) : false;
+			});
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	/**
+	 * Hold this session's endpoint inactive after a foreign-daemon identity race.
+	 * The block remains until an explicit same-identity reconnect or CAS restore clears it.
+	 */
+	async enterBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<boolean> {
+		const binding = this.bind(context);
+		try {
+			return await this.#enqueue(binding, async () => {
+				const runtime = this.#runtime as NotificationSessionRuntime<Context> | undefined;
+				const stopped = runtime?.isRunning(binding) ? await runtime.stop(binding) : false;
+				this.#blockedRuntimeSessions.add(binding.sessionId);
+				return stopped;
+			});
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	/** Clear a block only after the caller has verified a safe same-identity reconnect or restore. */
+	async clearBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<void> {
+		const binding = this.bind(context);
+		try {
+			await this.#enqueue(binding, async () => {
+				this.#blockedRuntimeSessions.delete(binding.sessionId);
+			});
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	async setLocalEnabled<Context extends NotificationSessionContext>(
+		context: Context,
+		enabled: boolean,
+	): Promise<NotificationSessionReconcileResult> {
+		const binding = this.bind(context);
+		try {
+			return await this.#enqueue(binding, async () => {
+				if (enabled) {
+					this.#disabledSessions.delete(binding.sessionId);
+					this.#shuttingDownSessions.delete(binding.sessionId);
+				} else {
+					this.#disabledSessions.add(binding.sessionId);
+				}
+				return await this.#reconcile(binding);
+			});
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	async reconcileCurrentSession<Context extends NotificationSessionContext>(
+		context: Context,
+	): Promise<NotificationSessionReconcileResult> {
+		const binding = this.bind(context);
+		try {
+			return await this.#enqueue(binding, () => this.#reconcile(binding));
+		} finally {
+			binding.unbind();
+		}
+	}
+
+	async #reconcile<Context extends NotificationSessionContext>(
+		binding: BoundNotificationSession<Context>,
+	): Promise<NotificationSessionReconcileResult> {
+		const cfg = this.#getConfig();
+		const runtime = this.#runtime as NotificationSessionRuntime<Context> | undefined;
+		const status = this.#status(binding, cfg, runtime);
+		if (!status.effectiveEnabled) {
+			if (runtime && status.running) await runtime.stop(binding);
+			return { outcome: status.running ? "stopped" : "disabled", status: this.#status(binding, cfg, runtime) };
+		}
+
+		if (!runtime) return { outcome: "disabled", status };
+		if (getCurrentTelegramActivationMarker(cfg)) {
+			if (runtime.isRunning(binding)) await runtime.stop(binding);
+			this.#blockedRuntimeSessions.add(binding.sessionId);
+			return { outcome: "disabled", status: this.#status(binding, cfg, runtime) };
+		}
+		if (isTelegramConfigured(cfg)) {
+			try {
+				const ensured = await runtime.ensureTelegramDaemon?.(binding);
+				if (ensured !== "ready") {
+					if (runtime.isRunning(binding)) await runtime.stop(binding);
+					this.#blockedRuntimeSessions.add(binding.sessionId);
+					return { outcome: "disabled", status: this.#status(binding, cfg, runtime) };
+				}
+			} catch {
+				if (runtime.isRunning(binding)) await runtime.stop(binding);
+				this.#blockedRuntimeSessions.add(binding.sessionId);
+				return { outcome: "failed", status: this.#status(binding, cfg, runtime) };
+			}
+		}
+
+		const current = this.#status(binding, cfg, runtime);
+		if (!current.effectiveEnabled) {
+			if (current.running) await runtime.stop(binding);
+			return { outcome: current.running ? "stopped" : "disabled", status: this.#status(binding, cfg, runtime) };
+		}
+		const outcome = current.running ? "already" : await runtime.start(binding);
+		const afterStart = this.#status(binding, cfg, runtime);
+		if (!afterStart.effectiveEnabled) {
+			if (afterStart.running) await runtime.stop(binding);
+			return { outcome: afterStart.running ? "stopped" : "disabled", status: this.#status(binding, cfg, runtime) };
+		}
+		return { outcome, status: this.#status(binding, cfg, runtime) };
+	}
+
+	#enqueue<Context extends NotificationSessionContext, Result>(
+		binding: BoundNotificationSession<Context>,
+		operation: () => Promise<Result>,
+	): Promise<Result> {
+		const previous = this.#sessionOperations.get(binding.sessionId) ?? Promise.resolve();
+		const result = previous.then(operation, operation);
+		const completion = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		this.#sessionOperations.set(binding.sessionId, completion);
+		void completion.then(() => {
+			if (this.#sessionOperations.get(binding.sessionId) === completion) {
+				this.#sessionOperations.delete(binding.sessionId);
+			}
+		});
+		return result;
+	}
+
+	#query<Context extends NotificationSessionContext>(
+		binding: BoundNotificationSession<Context>,
+	): NotificationSessionStatus {
+		const cfg = this.#getConfig();
+		return this.#status(binding, cfg, this.#runtime as NotificationSessionRuntime<Context> | undefined);
+	}
+
+	#status<Context extends NotificationSessionContext>(
+		binding: BoundNotificationSession<Context>,
+		cfg: NotificationConfig,
+		runtime: NotificationSessionRuntime<Context> | undefined,
+	): NotificationSessionStatus {
+		const locallyEnabled = !this.#disabledSessions.has(binding.sessionId);
+		const blockedRuntime = this.#blockedRuntimeSessions.has(binding.sessionId);
+		const shuttingDown = this.#shuttingDownSessions.has(binding.sessionId);
+		const effectiveEnabled =
+			!blockedRuntime &&
+			!shuttingDown &&
+			!getCurrentTelegramActivationMarker(cfg) &&
+			this.#eligible &&
+			isSessionNotificationsEnabled({ cfg, env: this.#env, sessionDisabled: !locallyEnabled });
+		const environment =
+			this.#env.GJC_NOTIFICATIONS === "0"
+				? "off"
+				: this.#env.GJC_NOTIFICATIONS === "1"
+					? "explicit"
+					: this.#env.GJC_NOTIFICATIONS_TOKEN
+						? "token"
+						: "default";
+		return {
+			eligible: this.#eligible,
+			locallyEnabled,
+			effectiveEnabled,
+			running: runtime?.isRunning(binding) ?? false,
+			environment,
+		};
+	}
+}

package/src/sdk/bus/slack-conversation.ts

@@ -0,0 +1,74 @@
+import { boundedDedupe, type ConversationRecord } from "./conversation-store";
+
+export interface SlackInboundDispatchReceipt {
+	key: string;
+	eventId: string;
+	interactionId: string;
+	retryKey: string;
+	eventContext?: string;
+	kind: "action" | "command";
+	actionId?: string;
+	/** The endpoint generation and SDK effect captured before Socket Mode ACK. */
+	endpointGeneration: number;
+	/** Identifier of the protected journal payload; mappings never retain message bodies. */
+	effectId: string;
+	idempotencyKey: string;
+}
+
+export type SlackConversationState = "absent" | "posting_root" | "active" | "closed_marker" | "resumed_root" | "error";
+
+/** Durable Slack mapping. It contains identifiers and receipt metadata only; protected journal effects own message bodies. */
+export interface SlackConversation extends ConversationRecord {
+	state: SlackConversationState;
+	teamId: string;
+	channelId: string;
+	rootTs?: string;
+	sessionId?: string;
+	endpointGeneration?: number;
+	clientMsgId?: string;
+	/** Exclusive, expiring authority for provider reconciliation/publication of the root intent. */
+	rootPublicationOwner?: string;
+	rootPublicationLeaseExpiresAt?: number;
+	/** Monotonic fencing token; stale root publishers may not commit after takeover. */
+	rootPublicationFence?: number;
+
+	/** Exclusive, expiring authority for provider reconciliation/publication of the outbound action intent. */
+	outboundActionOwner?: string;
+	outboundActionLeaseExpiresAt?: number;
+	/** Monotonic fencing token; stale action publishers may not commit after takeover. */
+	outboundActionFence?: number;
+	/** Action authority only; action bodies and endpoint credentials are never persisted. */
+	pendingActionId?: string;
+	/** Durable, unpublished action intent. The action body is supplied only by the caller. */
+	outboundActionId?: string;
+	outboundActionClientMsgId?: string;
+	lastError?: string;
+	updatedAt: number;
+	seenEventIds: string[];
+	seenContextIds: string[];
+	seenRetryKeys: string[];
+	seenInteractionIds: string[];
+	/** Durable inbound effect identifiers. The protected journal owns replay payloads. */
+	inboundDispatches?: SlackInboundDispatchReceipt[];
+}
+
+export function slackConversationKey(input: { teamId: string; channelId: string; rootTs: string }): string {
+	return `${input.teamId}:${input.channelId}:${input.rootTs}`;
+}
+
+export function normalizeSlackConversation(record: SlackConversation): SlackConversation {
+	const inboundDispatches = record.inboundDispatches ?? [];
+	return {
+		...record,
+		seenEventIds: boundedDedupe(record.seenEventIds),
+		seenContextIds: boundedDedupe(record.seenContextIds),
+		seenRetryKeys: boundedDedupe(record.seenRetryKeys),
+		seenInteractionIds: boundedDedupe(record.seenInteractionIds),
+		// Replay lifecycle and terminal retention are journal-owned; mappings retain identifiers.
+		inboundDispatches,
+	};
+}
+
+export function acceptsSlackInbound(record: SlackConversation, rootTs: string, endpointGeneration: number): boolean {
+	return record.state === "active" && record.rootTs === rootTs && record.endpointGeneration === endpointGeneration;
+}