@gajae-code/coding-agent 0.12.11 → 0.12.12

package/src/sdk/bus/chat-daemon-control.ts

@@ -51,11 +51,15 @@ export type ChatDaemonAction = "stop" | "reload";
  * Discord generation 24 / slack generation 23 apply provider-completeness and
  * effective-enable admission to chat daemon lifecycle controls. Discord
  * generation 25 / slack generation 24 apply identity-bound exact replacement
- * cleanup shared by managed-session and daemon filesystem authority.
+ * cleanup shared by managed-session and daemon filesystem authority. Discord
+ * generation 26 / slack generation 25 add the in-place operator command channel:
+ * an owner serves per-request commands inside its own serving loop and answers
+ * them against an exact owner tuple, so an owner at an earlier generation may
+ * not serve or answer a request captured against this contract.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 25,
-	slack: 24,
+	discord: 26,
+	slack: 25,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {
@@ -279,6 +283,15 @@ export function chatDaemonPaths(
 	};
 }
 
+/**
+ * Configuration fingerprint that identifies which settings a daemon owner was
+ * started for. `undefined` means the current settings cannot configure that
+ * transport at all, so no owner can be authorized against them.
+ */
+export function chatDaemonIdentity(settings: Settings, kind: ChatDaemonKind): string | undefined {
+	return identityFor(settings, kind);
+}
+
 function identityFor(settings: Settings, kind: ChatDaemonKind): string | undefined {
 	const cfg = getNotificationConfig(settings);
 	if (kind === "discord") {

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -4,17 +4,26 @@ import * as path from "node:path";
 import { type IndexedSession, SessionIndex } from "../broker/session-index";
 import { SdkClient, SdkClientError } from "../client/client";
 import { readSdkBrokerDiscovery, readSdkSessionEndpoint, type SdkSessionEndpoint } from "../client/discovery";
+import { SESSION_PREPARED_EVENT } from "../host/host";
 
 import { createDiscordAdapter, createSlackAdapter } from "./chat-adapters";
 import { type ChatTransport, projectChatCommandOutcome, sendAuthorizedChatOperation } from "./chat-command-policy";
+import type { ChatDaemonCommandBindInput, ChatDaemonCommandOutcome } from "./chat-daemon-command-channel";
 import type { ChatDaemonKind } from "./chat-daemon-control";
+import { isControlPlaneFrameType } from "./control-plane-frames";
 import { type DiscordEndpointBinding, DiscordEndpointBindingError, DiscordNotificationDaemon } from "./discord-daemon";
 import { DiscordLiveProvider } from "./discord-live-provider";
 import type { DiscordProvider } from "./discord-provider";
 import { type NotificationEvent, NotificationPresentationEngine } from "./engine";
-import { type SlackEndpoint, SlackEndpointBindingError, SlackNotificationDaemon } from "./slack-daemon";
+import {
+	type SlackBindingAuthority,
+	type SlackEndpoint,
+	SlackEndpointBindingError,
+	SlackNotificationDaemon,
+} from "./slack-daemon";
 import { SlackLiveProvider } from "./slack-live-provider";
 import { SlackProvider, type SlackProviderClient } from "./slack-provider";
+import { resolveSessionBindingAuthority, SlackThreadBindingError } from "./slack-thread-binding";
 
 export interface ChatDaemonRuntimeConfig {
 	identity: string;
@@ -77,29 +86,187 @@ type AttachedSession = Readonly<{
 	dispose: () => void;
 }>;
 
-function notificationFrame(frame: Record<string, unknown>): Record<string, unknown> {
-	const payload = frame.type === "event" ? frame.payload : undefined;
+/**
+ * The lifecycle signals that decide whether a chat root exists at all. They are
+ * the only event names that close, resume, or withhold a session's publication,
+ * so their identity may never be assembled from two disagreeing representations
+ * of one frame.
+ */
+const LIFECYCLE_EVENT_NAMES: ReadonlySet<string> = new Set([
+	SESSION_PREPARED_EVENT,
+	"session_ready",
+	"session_closed",
+	"session_terminated",
+]);
+
+function isLifecycleEvent(name: string | undefined): boolean {
+	return name !== undefined && LIFECYCLE_EVENT_NAMES.has(name);
+}
+
+/**
+ * Names whose presence obliges a frame to mean exactly one thing. Lifecycle
+ * signals decide whether a chat root exists at all; control-plane
+ * discriminants may never be presented at all. Either identity appearing on
+ * only one of a frame's two representations is a smuggling attempt, not an
+ * event.
+ */
+function isReservedIdentity(name: string | undefined): boolean {
+	return isLifecycleEvent(name) || isControlPlaneFrameType(name);
+}
+
+/** One delivered frame reduced to a single event identity. */
+type CorrelatedFrame = Readonly<{
+	/** The event body a notification is projected from. */
+	body: Record<string, unknown>;
+	name: string | undefined;
+	sessionId: string | undefined;
+	generation: number | undefined;
+}>;
+
+function eventPayload(frame: Record<string, unknown>): Record<string, unknown> | undefined {
+	if (frame.type !== "event") return undefined;
+	const payload = frame.payload;
 	return payload && typeof payload === "object" && !Array.isArray(payload)
 		? (payload as Record<string, unknown>)
-		: frame;
+		: undefined;
 }
 
-function eventName(frame: Record<string, unknown>, normalized: Record<string, unknown>): string | undefined {
-	if (frame.type === "event") {
-		if (typeof frame.name === "string") return frame.name;
-		if (typeof frame.kind === "string") return frame.kind;
-	}
-	return typeof normalized.type === "string" ? normalized.type : undefined;
+function readEventName(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
 }
 
-function sessionIdFrom(frame: Record<string, unknown>): string | undefined {
-	return typeof frame.sessionId === "string" && frame.sessionId ? frame.sessionId : undefined;
+function readSessionId(value: unknown): string | undefined {
+	return typeof value === "string" && value ? value : undefined;
 }
 
-function generationFrom(frame: Record<string, unknown>): number | undefined {
-	return typeof frame.generation === "number" && Number.isSafeInteger(frame.generation) && frame.generation >= 0
-		? frame.generation
-		: undefined;
+function readGeneration(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/**
+ * What one representation of a frame states about an identity it owns.
+ *
+ * `absent` means the representation does not own the property at all. `invalid`
+ * means it owns the property while stating something that cannot be that
+ * identity — which is not the same thing, because reading an invalid duplicate
+ * as absent silently promotes the other representation to sole authority over a
+ * frame that stated two.
+ */
+type IdentityClaim<T> = Readonly<{ state: "absent" } | { state: "invalid" } | { state: "stated"; value: T }>;
+
+const ABSENT_IDENTITY: IdentityClaim<never> = { state: "absent" };
+
+/**
+ * Read one representation's claim about `key`.
+ *
+ * Ownership of the property is the claim, never its value: a representation
+ * that owns `key` has stated it, so `undefined` is a malformed statement rather
+ * than silence. Value equality cannot tell the two apart, and treating an owned
+ * `undefined` as absence is exactly what lets a frame state one identity twice
+ * while only one of the two is ever checked.
+ */
+function identityClaim<T>(
+	frame: Record<string, unknown> | undefined,
+	key: "sessionId" | "generation" | "name" | "kind",
+	read: (value: unknown) => T | undefined,
+): IdentityClaim<T> {
+	if (!frame || !Object.hasOwn(frame, key)) return ABSENT_IDENTITY;
+	const value = read(frame[key]);
+	return value === undefined ? { state: "invalid" } : { state: "stated", value };
+}
+
+/**
+ * Reduce one identity stated by both representations of a frame to one value.
+ *
+ * A duplicated identity is a single authority tuple: when both sides supply it
+ * they must both be well-typed and equal, whatever the event's class. A claim
+ * that cannot be the identity it names is never reconciled at all — on either
+ * side, and whether or not the other side stated anything — because the only
+ * alternative is to let the frame proceed under an identity it contradicted. A
+ * single-sided identity is read from the side that supplied it, so ordinary
+ * wrappers that carry the identity only on the envelope stay compatible.
+ */
+function reconcileIdentity<T>(
+	envelope: IdentityClaim<T>,
+	payload: IdentityClaim<T>,
+): Readonly<{ ok: true; value: T | undefined } | { ok: false }> {
+	if (envelope.state === "invalid" || payload.state === "invalid") return { ok: false };
+	if (envelope.state === "absent") return { ok: true, value: payload.state === "stated" ? payload.value : undefined };
+	if (payload.state === "absent") return { ok: true, value: envelope.value };
+	return envelope.value === payload.value ? { ok: true, value: envelope.value } : { ok: false };
+}
+
+/**
+ * Reduce the two spellings of one event envelope's identity to a single name.
+ *
+ * `name` and `kind` are aliases, not two authorities: the host emits ordinary
+ * frames as `{ kind: <payload.type>, payload }` and lifecycle signals as
+ * `{ name: <lifecycle>, … }`, so a frame that owns only one is read from that
+ * one. Owning both obliges them to be well-typed and exactly equal. Preferring
+ * either alias would let a benign transport name clear lifecycle and
+ * control-plane filtering while the other spelling carries the reserved
+ * identity — `control_response`, `session_closed`, `event_replay_result` — that
+ * a later step consumes.
+ */
+function envelopeEventName(
+	frame: Record<string, unknown>,
+): Readonly<{ ok: true; value: string | undefined } | { ok: false }> {
+	if (frame.type !== "event") return { ok: true, value: undefined };
+	return reconcileIdentity(identityClaim(frame, "name", readEventName), identityClaim(frame, "kind", readEventName));
+}
+
+/**
+ * Reduce one delivered frame to a single event identity, or reject it whole.
+ *
+ * An event envelope and its payload are two representations of one event, never
+ * two authorities. The host emits ordinary frames as `{ kind: <payload.type>,
+ * payload }` and lifecycle signals unwrapped as `{ name: <lifecycle>,
+ * sessionId, generation }`, so a frame that names a different session, a
+ * different generation, or a different lifecycle identity in each representation
+ * is malformed. Correlating first is what stops the envelope from clearing one
+ * filter while the payload supplies the identity a later step consumes.
+ *
+ * Different semantic layers stay legal: an ordinary transport envelope may name
+ * `notification` while its payload carries an unrelated event `type`. A reserved
+ * identity — a lifecycle signal or a control-plane discriminant — on either side
+ * additionally obliges both sides to agree on the event name, and a duplicated
+ * session or generation is read from the single side that supplied it.
+ *
+ * The envelope's own `name`/`kind` aliases are reduced first, before the payload
+ * is projected at all, so a frame whose two spellings disagree is inert ahead of
+ * every filter and every mutation rather than after one of them.
+ */
+function correlateFrame(frame: Record<string, unknown>): CorrelatedFrame | undefined {
+	const envelopeName = envelopeEventName(frame);
+	if (!envelopeName.ok) return undefined;
+	const payload = eventPayload(frame);
+	const body = payload ?? frame;
+	const sessionId = reconcileIdentity(
+		identityClaim(frame, "sessionId", readSessionId),
+		identityClaim(payload, "sessionId", readSessionId),
+	);
+	if (!sessionId.ok) return undefined;
+	const bodyName = typeof body.type === "string" ? body.type : undefined;
+	// A reserved marker on either side must be the frame's whole identity: an
+	// envelope that says something else is smuggling a lifecycle signal past
+	// lifecycle filtering, or a control-plane body past control-plane filtering.
+	if (
+		payload &&
+		envelopeName.value !== bodyName &&
+		(isReservedIdentity(envelopeName.value) || isReservedIdentity(bodyName))
+	)
+		return undefined;
+	const generation = reconcileIdentity(
+		identityClaim(frame, "generation", readGeneration),
+		identityClaim(payload, "generation", readGeneration),
+	);
+	if (!generation.ok) return undefined;
+	return {
+		body,
+		name: envelopeName.value ?? bodyName,
+		sessionId: sessionId.value,
+		generation: generation.value,
+	};
 }
 
 /**
@@ -197,6 +364,7 @@ export class ChatDaemonRuntime {
 					};
 				},
 				resolveEndpoint: async sessionId => await this.resolveEndpoint(sessionId),
+				resolveBindingAuthority: async sessionId => await this.#slackBindingAuthority(sessionId),
 				onCommand: async (sessionId, content, endpoint, idempotencyKey) => {
 					const attached = this.#sessions.get(sessionId);
 					if (
@@ -342,6 +510,54 @@ export class ChatDaemonRuntime {
 		const attached = this.#sessions.get(sessionId);
 		return attached ? { ...attached.endpoint, generation: attached.generation } : null;
 	}
+
+	/**
+	 * Exact authority for adopting an existing root: the runtime must currently
+	 * hold this session's attachment, the index must still list it as live and
+	 * non-terminal with an intact replay, and its discovery endpoint must be
+	 * readable, non-stale, and owned by the indexed host pid at the same
+	 * generation. Re-reading the attachment afterwards rejects a session that
+	 * detached or rolled while the index and endpoint were being consulted.
+	 */
+	async #slackBindingAuthority(sessionId: string): Promise<SlackBindingAuthority | undefined> {
+		const attached = this.#sessions.get(sessionId);
+		if (!attached) return undefined;
+		const authority = await resolveSessionBindingAuthority({ sessionIndex: this.#index, sessionId });
+		if (!authority || authority.endpointGeneration !== attached.generation) return undefined;
+		if (this.#sessions.get(sessionId) !== attached) return undefined;
+		return { sessionId, endpointGeneration: attached.generation };
+	}
+
+	/**
+	 * Adopt an operator-supplied Slack root for one attached session. Returns a
+	 * machine-readable rejection instead of throwing so the daemon control plane
+	 * can answer without exposing internal failure detail.
+	 */
+	async bindExistingRoot(request: ChatDaemonCommandBindInput): Promise<ChatDaemonCommandOutcome> {
+		const slack = this.#slack;
+		if (!slack) return { ok: false, certainty: "rejected", code: "target_not_configured" };
+		try {
+			const bound = await slack.bindExistingRoot(request.sessionId, request.rootTs, request.commitAuthority);
+			if (!bound.rootTs || bound.endpointGeneration === undefined)
+				return { ok: false, certainty: "rejected", code: "binding_failed" };
+			return {
+				ok: true,
+				sessionId: request.sessionId,
+				endpointGeneration: bound.endpointGeneration,
+				teamId: bound.teamId,
+				channelId: bound.channelId,
+				rootTs: bound.rootTs,
+			};
+		} catch (error) {
+			// `binding_outcome_unknown` is the store's typed statement that the
+			// mapping may already be applied. It must travel as an indeterminate
+			// outcome, never as a rejection the operator could act on.
+			const code = error instanceof SlackThreadBindingError ? error.code : "binding_failed";
+			return code === "binding_outcome_unknown"
+				? { ok: false, certainty: "unknown", code }
+				: { ok: false, certainty: "rejected", code };
+		}
+	}
 	#discordEndpoint(sessionId: string): DiscordEndpointBinding | null {
 		const attached = this.#sessions.get(sessionId);
 		if (!attached) return null;
@@ -378,18 +594,38 @@ export class ChatDaemonRuntime {
 	}
 	private async handleFrame(attached: AttachedSession, frame: Record<string, unknown>): Promise<void> {
 		if (this.#sessions.get(attached.sessionId) !== attached) return;
-		const normalizedFrame = notificationFrame(frame);
+		// Correlate before anything is acted on. A frame whose envelope and payload
+		// disagree on session, lifecycle identity, or lifecycle generation is not a
+		// usable event, so it is dropped whole — no close, resume, notify, resolve,
+		// root, or mapping mutation — on the replay path and the live path alike.
+		const correlated = correlateFrame(frame);
+		if (!correlated) return;
+		const normalizedFrame = correlated.body;
+		// The SDK's own request/response traffic arrives on this same observer:
+		// `SdkClient` settles a pending request and still forwards that frame to
+		// every handler. A protocol answer carries no user-visible content, so it
+		// is dropped here — ahead of presentation fanout and of every root,
+		// mapping, resume, close, and action mutation — on both delivery paths.
+		// Its nested payload is discarded with it and never reprojected.
+		const bodyType = typeof normalizedFrame.type === "string" ? normalizedFrame.type : undefined;
+		if (isControlPlaneFrameType(correlated.name) || isControlPlaneFrameType(bodyType)) return;
 		if (normalizedFrame.type === "turn_stream" && normalizedFrame.phase === "live") return;
-		const frameSessionId = sessionIdFrom(normalizedFrame) ?? sessionIdFrom(frame);
-		if (frameSessionId !== undefined && frameSessionId !== attached.sessionId) return;
+		if (correlated.sessionId !== undefined && correlated.sessionId !== attached.sessionId) return;
 		const sessionId = attached.sessionId;
-		const name = eventName(frame, normalizedFrame);
+		const name = correlated.name;
 		if (name === "session_closed" || name === "session_terminated") {
 			await this.close(sessionId);
 			return;
 		}
+		// `session_prepared` is control-plane evidence only: the session holds
+		// endpoint authority while deliberately withholding readiness. It carries no
+		// user-visible content and must never create or adopt a root, notify, or
+		// resume — at this attachment's generation or any other. Foreign session ids
+		// are already rejected above, so every prepared frame is inert here, and a
+		// stale or foreign one cannot mutate state either.
+		if (name === SESSION_PREPARED_EVENT || bodyType === SESSION_PREPARED_EVENT) return;
 		if (name === "session_ready") {
-			if (generationFrom(frame) !== attached.generation) return;
+			if (correlated.generation !== attached.generation) return;
 			await this.resume(sessionId, attached.generation, "GJC session ready.");
 			return;
 		}

package/src/sdk/bus/control-plane-frames.ts

@@ -0,0 +1,51 @@
+/**
+ * Typed control-plane discriminants that must never reach chat presentation.
+ *
+ * A chat daemon observes one session socket for user-visible events, but that
+ * socket also carries the SDK's own request/response traffic: `SdkClient`
+ * settles a pending request from an inbound frame and still forwards the very
+ * same frame to every `onFrame` observer. A runtime that projects unknown frame
+ * types into a generic notification therefore renders protocol answers — most
+ * visibly `GJC event replay result` — as chat content, and a chat transport
+ * with no mapping for that session publishes it as a brand-new root.
+ *
+ * Membership is exact, typed, and closed. It is never inferred from a `_result`
+ * or `_response` suffix: ordinary public frames are free to be named anything,
+ * and a fuzzy rule would silently swallow real user content. Every entry below
+ * names the source authority that emits it and the code path that proves it can
+ * be delivered to a chat daemon's frame observer.
+ *
+ * In scope (proven reachable at the chat-daemon session-client seam):
+ * - `event_replay_result` — `SessionSdkHost` (`sdk/host/host.ts`) answers the
+ *   `event_replay` request that `ChatDaemonRuntime.attach()` issues on every
+ *   attachment, so every attached session receives exactly this frame.
+ * - `control_response` — the same host's answer to the `control_request` that
+ *   `ChatDaemonRuntime` sends for an authorized `/sdk control …` command, and
+ *   the endpoint-stale refusal the session runtime writes for a fenced
+ *   connection.
+ * - `query_response` — the host's answer to the matching `query_request`, and
+ *   the same endpoint-stale refusal path.
+ * - `hello` — `ServerMessage::Hello` from the native session server
+ *   (`crates/gjc-sdk/src/protocol.rs`), sent to every connection at accept time
+ *   and re-observed by frame handlers whenever the client reconnects and
+ *   adopts a new connection id.
+ *
+ * Deliberately out of scope — typed server→client frames that exist but are
+ * unicast only to a connection that issued a request a chat daemon never
+ * sends, so no source path delivers them here: `session_activate_result`,
+ * `register_provider_result`, `lease_state`, `reverse_response`,
+ * `reverse_request`, `reverse_cancel`, `global_response`, `pong`, and
+ * `transport_error`. Add one only together with the source path that proves it
+ * reaches this seam.
+ */
+export const CONTROL_PLANE_FRAME_TYPES: ReadonlySet<string> = new Set([
+	"event_replay_result",
+	"control_response",
+	"query_response",
+	"hello",
+]);
+
+/** Whether an exact frame/event discriminant is protocol-only control plane. */
+export function isControlPlaneFrameType(name: string | undefined): boolean {
+	return name !== undefined && CONTROL_PLANE_FRAME_TYPES.has(name);
+}

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

@@ -164,10 +164,38 @@ export class ConversationStore<T extends ConversationRecord> {
 
 	/** Apply a synchronous update under the mapping lock, retrying no stale state. */
 	async transact(key: string, update: (current: T | undefined) => T | undefined): Promise<T | undefined> {
+		return await this.transactWithSnapshot(key, current => update(current));
+	}
+
+	/**
+	 * Apply one key update while atomically observing every mapping in the same
+	 * store snapshot. The observation and the write share the cross-process file
+	 * lock, so a caller can enforce uniqueness constraints that span keys.
+	 *
+	 * The update may be asynchronous so a caller can re-prove local authority
+	 * (process, endpoint, or session state) inside the lock, immediately before
+	 * its commit; returning `current` unchanged aborts without any mutation. It
+	 * must never perform a remote/network call while holding the lock: the lock
+	 * is a short fence, not a place to wait on a provider.
+	 *
+	 * Authority proven by the update is the last proof before the atomic
+	 * replacement. Authority that rolls after it is an ordinary lifecycle event:
+	 * the mapping records the endpoint generation it was proven under, so a newer
+	 * generation fences it through the same monotonic compare-and-swap every
+	 * other writer uses.
+	 */
+	async transactWithSnapshot(
+		key: string,
+		update: (
+			current: T | undefined,
+			conversations: Readonly<Record<string, T>>,
+		) => T | undefined | Promise<T | undefined>,
+	): Promise<T | undefined> {
 		return this.#withLock(async () => {
 			const document = await this.#readDocument();
 			const current = document.conversations[key];
-			const next = update(current);
+			const snapshot: Readonly<Record<string, T>> = Object.freeze({ ...document.conversations });
+			const next = await update(current, snapshot);
 			if (!next || next === current) return current;
 			const expectedGeneration = current?.generation;
 			const expectedNext = (expectedGeneration ?? 0) + 1;

package/src/sdk/bus/existing-thread-readiness.ts

@@ -0,0 +1,155 @@
+/**
+ * The prepare → bind → activate lifecycle for adopting an existing chat root.
+ *
+ * Stock startup publishes a session's readiness immediately, so the running
+ * chat daemon surfaces the session and creates its own root before an operator
+ * could ever name an existing one. A session that opts in is *prepared*
+ * instead: its id, endpoint, and broker registration are discoverable authority
+ * while readiness stays withheld, which leaves exactly one root claim for
+ * `gjc notify bind-thread` to fill. Activation then publishes readiness once,
+ * and the daemon adopts the bound root instead of replacing it.
+ *
+ * Nothing here mutates a mapping. The gate only reads the daemon-owned store to
+ * prove a binding exists, and the activation client only asks the session's own
+ * host to publish the readiness it withheld.
+ */
+
+import type { SessionIndex } from "../broker/session-index";
+import { SdkClient } from "../client/client";
+import type { SdkSessionEndpoint, SdkSessionEndpointScope } from "../client/discovery";
+import type { SessionActivationGate } from "../host";
+import {
+	type ActivatedPreparedSession,
+	type PreparedSessionActivationClient,
+	requestPreparedSessionActivation,
+	SessionActivationError,
+} from "../session-activation";
+import type { ConversationStore } from "./conversation-store";
+import type { SlackConversation } from "./slack-conversation";
+import { resolveSessionBindingAuthority } from "./slack-thread-binding";
+
+/** Explicit, session-scoped opt-in for withholding readiness until a root is bound. */
+export const EXISTING_THREAD_BIND_ENV = "GJC_NOTIFY_BIND_EXISTING_THREAD";
+
+/**
+ * Existing-thread binding is opt-in, and only the exact value `1` opts in.
+ *
+ * Every other value — absent, empty, `0`, or anything truthy-looking — keeps
+ * the stock immediate-readiness contract, so no session silently loses its
+ * root publication because of an ambiguous environment.
+ */
+export function isExistingThreadBindingRequested(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[EXISTING_THREAD_BIND_ENV] === "1";
+}
+
+export interface SlackBindingActivationInput {
+	store: ConversationStore<SlackConversation>;
+	teamId: string;
+	channelId: string;
+}
+
+/**
+ * Authorize activation only against an applied binding for this exact session.
+ *
+ * The proof is the daemon-owned mapping itself: an active record for this
+ * session, in the configured workspace and channel, carrying a root and the
+ * exact endpoint generation being activated. A missing, foreign, or
+ * stale-generation mapping is a refusal, and an unreadable store raises so the
+ * caller reports unavailable authority instead of an authorization.
+ */
+export function createSlackBindingActivationGate(input: SlackBindingActivationInput): SessionActivationGate {
+	return async ({ sessionId, generation }) => {
+		const document = await input.store.load();
+		return Object.values(document.conversations).some(
+			record =>
+				record.state === "active" &&
+				record.sessionId === sessionId &&
+				record.teamId === input.teamId &&
+				record.channelId === input.channelId &&
+				typeof record.rootTs === "string" &&
+				record.rootTs.length > 0 &&
+				record.endpointGeneration === generation,
+		);
+	};
+}
+
+export type {
+	ActivatedPreparedSession,
+	PreparedSessionActivationClient,
+	SessionActivationErrorCode,
+} from "../session-activation";
+export { requestPreparedSessionActivation, SessionActivationError } from "../session-activation";
+
+export interface PreparedSessionActivationInput {
+	sessionIndex: SessionIndex;
+	sessionId: string;
+}
+
+export interface PreparedSessionActivationDeps {
+	readEndpoint?: (
+		repo: string,
+		sessionId: string,
+		scope?: SdkSessionEndpointScope,
+	) => Promise<SdkSessionEndpoint | null>;
+	connect?: (endpoint: { url: string; token: string }) => Promise<PreparedSessionActivationClient>;
+}
+
+/**
+ * Ask a prepared session to publish the readiness it withheld.
+ *
+ * The same discovery authority the binding requires is resolved first, so an
+ * unindexed, terminated, or endpoint-rolled session is refused before any
+ * connection is opened. The request names the exact session and endpoint
+ * generation, and the answer is accepted only when it proves both, so a
+ * replacement session can never be activated in place of the requested one.
+ * Activation is idempotent: an exact retry answers `already` without a second
+ * readiness signal.
+ */
+export async function activatePreparedSession(
+	input: PreparedSessionActivationInput,
+	deps: PreparedSessionActivationDeps = {},
+): Promise<ActivatedPreparedSession> {
+	const authority = await resolveSessionBindingAuthority({
+		sessionIndex: input.sessionIndex,
+		sessionId: input.sessionId,
+		...(deps.readEndpoint ? { readEndpoint: deps.readEndpoint } : {}),
+	});
+	if (!authority)
+		throw new SessionActivationError(
+			"session_not_live",
+			"Session activation requires an exact live session endpoint.",
+		);
+	// Deliberately not a second discovery read. The authority proof is bound to
+	// one endpoint file, verified by pid and mtime at one scope; re-resolving here
+	// could connect to a replacement process whose endpoint generation repeats,
+	// and the generation carried below could not tell the two apart.
+	const endpoint = authority.endpoint;
+	if (!endpoint.url || !endpoint.token)
+		throw new SessionActivationError(
+			"session_not_live",
+			"Session activation requires a readable session discovery endpoint.",
+		);
+	let client: PreparedSessionActivationClient;
+	try {
+		client = await (deps.connect ?? defaultActivationClient)({ url: endpoint.url, token: endpoint.token });
+	} catch {
+		// Nothing was ever sent, so no activation can have been applied.
+		throw new SessionActivationError("activation_unavailable", "The session endpoint could not be reached.");
+	}
+	try {
+		return await requestPreparedSessionActivation(client, input.sessionId, authority.endpointGeneration);
+	} finally {
+		await client.close().catch(() => undefined);
+	}
+}
+
+async function defaultActivationClient(endpoint: {
+	url: string;
+	token: string;
+}): Promise<PreparedSessionActivationClient> {
+	const client = await SdkClient.connect(endpoint.url, endpoint.token, { reconnectAttempts: 0 });
+	return {
+		request: async frame => (await client.request(frame)) as Record<string, unknown>,
+		close: async () => await client.close(),
+	};
+}