@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/sdk/broker/startup-budget.ts

@@ -3,6 +3,14 @@ export const DEFAULT_READINESS_TIMEOUT_MS = 10_000;
 export const MIN_READINESS_TIMEOUT_MS = 4_000;
 export const MAX_READINESS_TIMEOUT_MS = 60_000;
 
+/** Bounded git worktree add/reuse window; independent of child semantic readiness. */
+export const DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS = 30_000;
+export const MIN_PREPARATION_TIMEOUT_MS = 1_000;
+export const MAX_PREPARATION_TIMEOUT_MS = 120_000;
+
+/** Bounded workspace install window; independent of child semantic readiness. */
+export const DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS = 30_000;
+
 export function isValidReadinessTimeoutMs(value: unknown): value is number {
 	return (
 		typeof value === "number" &&
@@ -12,7 +20,17 @@ export function isValidReadinessTimeoutMs(value: unknown): value is number {
 	);
 }
 
+export function isValidPreparationTimeoutMs(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		value >= MIN_PREPARATION_TIMEOUT_MS &&
+		value <= MAX_PREPARATION_TIMEOUT_MS
+	);
+}
+
 export const READINESS_TIMEOUT_INVALID_MESSAGE = `readinessTimeoutMs must be an integer between ${MIN_READINESS_TIMEOUT_MS} and ${MAX_READINESS_TIMEOUT_MS}.`;
+export const PREPARATION_TIMEOUT_INVALID_MESSAGE = `worktreePreparationTimeoutMs and dependencyPreparationTimeoutMs must be integers between ${MIN_PREPARATION_TIMEOUT_MS} and ${MAX_PREPARATION_TIMEOUT_MS}.`;
 /**
  * Sleep until the duration elapses or the caller cancels the wait. Queue admission
  * uses this so a granted or refused waiter does not retain its cutoff timer for the
@@ -77,6 +95,10 @@ export function lifecycleStartupBudgetMs(requestedReadinessTimeoutMs: number): n
  * rather than left unextended: the broker queues it for exactly as long as one that
  * asked, so the common path would otherwise fail client-side while the broker runs
  * the startup to a durably persisted terminal result.
+ *
+ * Worktree launches add independent preparation budgets so git add / install cannot
+ * cut the caller while the broker still owns the request. One-arg
+ * {@link lifecycleStartupBudgetMs} stays queue+readiness for no-worktree callers.
  */
 export function lifecycleRequestTimeoutMs(operation: string, input: Record<string, unknown>): number | undefined {
 	const deadlineFields = [
@@ -97,7 +119,127 @@ export function lifecycleRequestTimeoutMs(operation: string, input: Record<strin
 		if (requested !== undefined && !isValidReadinessTimeoutMs(requested)) return undefined;
 		supplied = requested as number | undefined;
 	}
-	if (isStartupLifecycleOperation(operation))
-		return lifecycleStartupBudgetMs(supplied ?? DEFAULT_READINESS_TIMEOUT_MS) + CALLER_DEADLINE_SLACK_MS;
+	if (isStartupLifecycleOperation(operation)) {
+		const readiness = supplied ?? DEFAULT_READINESS_TIMEOUT_MS;
+		const preparation = preparationBudgetMs(input);
+		if (preparation === undefined) return undefined;
+		return lifecycleStartupBudgetMs(readiness) + preparation + CALLER_DEADLINE_SLACK_MS;
+	}
 	return supplied === undefined ? undefined : supplied + CALLER_DEADLINE_SLACK_MS;
 }
+
+function recordEnabled(value: unknown): boolean {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		(value as Record<string, unknown>).enabled === true
+	);
+}
+
+function worktreeNamePresent(value: unknown): boolean {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const name = (value as Record<string, unknown>).name;
+	return typeof name === "string" && name.length > 0;
+}
+
+/**
+ * True when this request will run named or detached worktree preparation.
+ * Coordinator nests the selector at `target.worktree`; Direct/lifecycle service
+ * put `worktree` on the mutation target itself; broker serialization also
+ * accepts `{ worktree: { name } }` without `enabled`.
+ */
+export function lifecycleRequestHasWorktree(input: Record<string, unknown>): boolean {
+	const nested = input.target;
+	if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+		const nestedWorktree = (nested as Record<string, unknown>).worktree;
+		if (recordEnabled(nestedWorktree) || worktreeNamePresent(nestedWorktree)) return true;
+	}
+	const worktree = input.worktree;
+	if (worktree === true) return true;
+	return recordEnabled(worktree) || worktreeNamePresent(worktree);
+}
+
+function readPreparationTimeout(
+	input: Record<string, unknown>,
+	key: "worktreePreparationTimeoutMs" | "dependencyPreparationTimeoutMs",
+): number | undefined | "invalid" {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	return isValidPreparationTimeoutMs(value) ? value : "invalid";
+}
+
+/**
+ * Sum of worktree and dependency preparation budgets, or 0 when the request
+ * has no worktree. Returns `undefined` when an explicit prep field is present
+ * but invalid so callers fail closed instead of silently dropping prep time.
+ */
+export function preparationBudgetMs(input: Record<string, unknown>): number | undefined {
+	const worktreeTimeout = readPreparationTimeout(input, "worktreePreparationTimeoutMs");
+	const dependencyTimeout = readPreparationTimeout(input, "dependencyPreparationTimeoutMs");
+	if (worktreeTimeout === "invalid" || dependencyTimeout === "invalid") return undefined;
+	if (!lifecycleRequestHasWorktree(input)) return 0;
+	return (
+		(worktreeTimeout ?? DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS) +
+		(dependencyTimeout ?? DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS)
+	);
+}
+
+export interface LifecycleOuterDeadlines {
+	admittedAt: number;
+	worktreePrepTimeoutMs: number;
+	dependencyPrepTimeoutMs: number;
+	requestedReadinessTimeoutMs: number;
+	worktreePreparationDeadlineAt: number;
+	lifecycleCleanupDeadlineAt: number;
+}
+
+/**
+ * Whole-request outer deadlines for a worktree launch. Child semantic readiness
+ * is still derived later at prepSucceededAt. Dependency start is sequential:
+ * callers clip remaining dep budget against `lifecycleCleanupDeadlineAt`
+ * after worktreeDoneAt.
+ */
+export function deriveLifecycleOuterDeadlines(input: {
+	admittedAt: number;
+	worktreePrepTimeoutMs: number;
+	dependencyPrepTimeoutMs: number;
+	requestedReadinessTimeoutMs: number;
+}): LifecycleOuterDeadlines {
+	const { admittedAt, worktreePrepTimeoutMs, dependencyPrepTimeoutMs, requestedReadinessTimeoutMs } = input;
+	if (
+		!Number.isSafeInteger(admittedAt) ||
+		!isValidPreparationTimeoutMs(worktreePrepTimeoutMs) ||
+		!isValidPreparationTimeoutMs(dependencyPrepTimeoutMs) ||
+		!isValidReadinessTimeoutMs(requestedReadinessTimeoutMs)
+	) {
+		throw new Error("Lifecycle outer timing values must be safe integers in the approved ranges.");
+	}
+	const worktreePreparationDeadlineAt = admittedAt + worktreePrepTimeoutMs;
+	const lifecycleCleanupDeadlineAt =
+		admittedAt + worktreePrepTimeoutMs + dependencyPrepTimeoutMs + requestedReadinessTimeoutMs;
+	if (!Number.isSafeInteger(worktreePreparationDeadlineAt) || !Number.isSafeInteger(lifecycleCleanupDeadlineAt)) {
+		throw new Error("Lifecycle outer timing values overflow the safe integer range.");
+	}
+	return {
+		admittedAt,
+		worktreePrepTimeoutMs,
+		dependencyPrepTimeoutMs,
+		requestedReadinessTimeoutMs,
+		worktreePreparationDeadlineAt,
+		lifecycleCleanupDeadlineAt,
+	};
+}
+
+export function readPreparationTimeouts(
+	input: Record<string, unknown>,
+): { ok: true; worktreePrepTimeoutMs: number; dependencyPrepTimeoutMs: number } | { ok: false } {
+	const worktreeTimeout = readPreparationTimeout(input, "worktreePreparationTimeoutMs");
+	const dependencyTimeout = readPreparationTimeout(input, "dependencyPreparationTimeoutMs");
+	if (worktreeTimeout === "invalid" || dependencyTimeout === "invalid") return { ok: false };
+	return {
+		ok: true,
+		worktreePrepTimeoutMs: worktreeTimeout ?? DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS,
+		dependencyPrepTimeoutMs: dependencyTimeout ?? DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS,
+	};
+}

package/src/sdk/broker/state-version.ts

@@ -1,15 +1,23 @@
 export const SDK_STATE_VERSION = 1;
 
-// The session-index snapshot carries its own format version, independent of the shared
-// SDK_STATE_VERSION used by discovery, the lifecycle ledger, and per-event records.
-// Version 2 snapshots relax the on-disk schema to allow gaps in indexSeq (compaction
-// drops terminal+dead sessions and superseded heartbeats), so an older broker must
-// hard-fail rather than silently fall back to a truncated log. Version 3 snapshots may
-// additionally carry composite-identity events (hostIncarnation, activity checkpoints,
-// session_deleted tombstones) and retention-compacted sessions; v2 (and v1) snapshots
-// remain readable. Bumping only this constant keeps the broker protocol untouched.
-export const SESSION_INDEX_SNAPSHOT_VERSION = 3;
+// The session-index snapshot and event log share one format version. Version 4
+// requires SessionLocatorV2 (`cwd`, `worktreeRoot`, `stateRoot`) on every
+// retained row. New v4 events force older brokers to fail closed before they
+// misread `cwd` as the former `repo`; pre-v4 snapshots remain readable only to
+// quarantine legacy rows.
+export const SESSION_INDEX_SNAPSHOT_VERSION = 4;
+export const SESSION_INDEX_EVENT_VERSION = SESSION_INDEX_SNAPSHOT_VERSION;
 
+/**
+ * Thrown when a persisted SDK state file carries a version this build does not
+ * support. `assertSupportedStateVersion` fences only generic SDK state (broker
+ * discovery, lifecycle-ledger rows, guide cache meta) whose current format is
+ * exactly `SDK_STATE_VERSION`. Session-index files carry their own versions
+ * (see `assertSupportedSessionIndexEventVersion` and
+ * `assertSupportedSnapshotVersion`) and MUST NOT be validated with the generic
+ * guard — a supported v4 index row would crash with "maximum supported version
+ * is 1" (#5181).
+ */
 export class UnsupportedStateVersionError extends Error {
 	readonly code = "unsupported_state_version";
 
@@ -25,6 +33,13 @@ export class UnsupportedStateVersionError extends Error {
 	}
 }
 
+/**
+ * Generic SDK-state fence: rejects any version above `SDK_STATE_VERSION`.
+ * ONLY for generic state whose current format is exactly `SDK_STATE_VERSION`
+ * (broker discovery `broker.json`, lifecycle-ledger rows, guide cache meta).
+ * Never validate session-index rows or snapshots with this guard — they have
+ * dedicated version fences and currently accept v4 (#5181).
+ */
 export function assertSupportedStateVersion(file: string, value: unknown): void {
 	if (!value || typeof value !== "object") return;
 	const record = value as { version?: unknown; stateVersion?: unknown };
@@ -35,11 +50,25 @@ export function assertSupportedStateVersion(file: string, value: unknown): void
 	}
 }
 
-// Fences the session-index snapshot format independently of SDK_STATE_VERSION. An older
-// broker (whose SESSION_INDEX_SNAPSHOT_VERSION is below 3) trips assertSupportedStateVersion
-// on a version-3 snapshot and refuses to start; a current broker accepts the legacy
-// contiguous format (version 1), the gapped version-2 format, and the version-3 format
-// with composite-identity events.
+/** Rejects session-index events outside the known legacy and current formats. */
+export function assertSupportedSessionIndexEventVersion(file: string, value: unknown): void {
+	if (!value || typeof value !== "object") return;
+	const record = value as { version?: unknown; stateVersion?: unknown };
+	for (const version of [record.version, record.stateVersion]) {
+		if (
+			typeof version === "number" &&
+			Number.isFinite(version) &&
+			version !== SDK_STATE_VERSION &&
+			version !== SESSION_INDEX_EVENT_VERSION
+		) {
+			throw new UnsupportedStateVersionError(file, version, SESSION_INDEX_EVENT_VERSION);
+		}
+	}
+}
+
+// Fences future session-index snapshot formats. Locator-v2 row validation below
+// rejects legacy `repo` rows without translating them, while snapshots predating
+// v4 remain readable solely to quarantine those rows with a re-register diagnostic.
 export function assertSupportedSnapshotVersion(file: string, value: unknown): void {
 	if (!value || typeof value !== "object") return;
 	const record = value as { version?: unknown; stateVersion?: unknown };

package/src/sdk/broker/transport.ts

@@ -19,6 +19,7 @@ const BROKER_OPERATIONS = new Set([
 	"session.control",
 	"broker.lookup_lifecycle",
 	"model.resolve",
+	"session.spawn",
 ]);
 type RequestInput = Record<string, unknown>;
 type BrokerRequest = {

package/src/sdk/broker/worktree-occupancy.ts

@@ -0,0 +1,90 @@
+/**
+ * Which session currently holds a GJC-managed worktree.
+ *
+ * Both launch paths need this answer and must not disagree about it: the broker
+ * refuses a lifecycle launch into an occupied worktree, and the interactive
+ * `gjc --worktree` launch refuses for the same reason. Keeping one predicate —
+ * and one definition of "still running" — here prevents the two from drifting
+ * into different notions of liveness.
+ */
+
+import type * as NativeBindings from "@gajae-code/natives";
+import { resolveEquivalentPath } from "@gajae-code/utils";
+import { probeLinuxProcPidSync } from "../../gjc-runtime/linux-proc";
+import { processIncarnation } from "./process-incarnation";
+import type { IndexedSession } from "./session-index";
+
+function nativeLifecycle(): typeof NativeBindings {
+	return require("@gajae-code/natives") as typeof NativeBindings;
+}
+
+export type ProcessObservation = "alive" | "exited" | "uncertain";
+
+/** Only ESRCH or a changed, readable incarnation proves the owned process exited. */
+export function observeProcess(
+	pid: number,
+	expectedIncarnation: string | undefined,
+	readIncarnation: (pid: number) => string | undefined = processIncarnation,
+): ProcessObservation {
+	if (process.platform === "win32") {
+		try {
+			const reference = nativeLifecycle().Process.fromPid(pid);
+			if (reference?.status() !== "running") return "exited";
+		} catch {
+			return "uncertain";
+		}
+		if (!expectedIncarnation) return "uncertain";
+		const actualIncarnation = readIncarnation(pid);
+		if (!actualIncarnation) return "uncertain";
+		return actualIncarnation === expectedIncarnation ? "alive" : "exited";
+	}
+	try {
+		process.kill(pid, 0);
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ESRCH" ? "exited" : "uncertain";
+	}
+	if (process.platform === "linux") {
+		const probe = probeLinuxProcPidSync(pid);
+		if (probe.kind === "live" && probe.state === "Z" && expectedIncarnation === `linux:${probe.startTime}`)
+			return "exited";
+	}
+	if (!expectedIncarnation) return "uncertain";
+	const actualIncarnation = readIncarnation(pid);
+	if (!actualIncarnation) return "uncertain";
+	return actualIncarnation === expectedIncarnation ? "alive" : "exited";
+}
+
+/**
+ * The id of a session still occupying `worktreePath`, or null when it is free.
+ *
+ * `ensureLaunchWorktree` reuses an existing worktree without asking whether
+ * anyone is in it, and an unnamed launch derives its directory deterministically
+ * from the repository's current branch. Two concurrent sessions in one
+ * repository therefore land in the same checkout and overwrite each other's
+ * files with no error.
+ *
+ * Only a process observed as definitively exited releases the worktree.
+ * `uncertain` counts as occupied: refusing a launch is recoverable by picking
+ * another worktree name, whereas two live sessions sharing a checkout corrupts
+ * work already done.
+ */
+export function worktreeOccupant(
+	sessions: readonly IndexedSession[],
+	worktreePath: string,
+	observe: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation = observeProcess,
+): string | null {
+	// Session locators retain the canonical Git worktree root separately from the
+	// session cwd. A host may start below that root, and a launch plan may arrive
+	// through a symlink, so compare the root identity rather than the cwd spelling.
+	const target = resolveEquivalentPath(worktreePath);
+	for (const session of sessions) {
+		const sessionWorktreeRoot = session.locator.worktreeRoot;
+		if (session.terminal || typeof sessionWorktreeRoot !== "string" || sessionWorktreeRoot.length === 0) continue;
+		if (resolveEquivalentPath(sessionWorktreeRoot) !== target) continue;
+		// `live` is heartbeat-derived and can be stale. Only positive process-exit
+		// evidence releases a matching retained session's worktree.
+		if (observe(session.pid, session.hostIncarnation ?? session.processIncarnation) === "exited") continue;
+		return session.sessionId;
+	}
+	return null;
+}

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

@@ -130,10 +130,13 @@ export type ChatDaemonAction = "stop" | "reload";
  * session-index lock every 2s; staleness retirement moved to a 30s sweep and
  * lease heartbeats no longer force an authority reconcile. A pre-upgrade owner
  * would retain the old hot polling loop, so replacement is required.
+ * Discord generation 72 / Slack generation 75 serialize same-generation
+ * successor attachment admission behind predecessor provider retirement, so a
+ * pre-upgrade owner cannot retain the queue race fixed by #5120.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 71,
-	slack: 74,
+	discord: 73,
+	slack: 77,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { logger } from "@gajae-code/utils";
 import { SdkClientError } from "../client/client";
 import { SESSION_PREPARED_EVENT } from "../host/host";
 
@@ -258,7 +259,11 @@ export class ChatDaemonRuntime {
 	readonly #router: SessionRouter;
 	readonly #attachments = new Map<string, SessionAttachment>();
 	readonly #cleanupWork = new Map<string, Promise<void>>();
+	readonly #retirementWork = new Map<string, Promise<void>>();
 	readonly #attachmentBarriers = new Map<string, Promise<void>>();
+	readonly #cleanupFailures = new Map<string, unknown>();
+	#replayReady: Promise<void> = Promise.resolve();
+	#stopping = false;
 	#discord: DiscordNotificationDaemon | undefined;
 	#slack: SlackNotificationDaemon | undefined;
 	#presentation: NotificationPresentationEngine | undefined;
@@ -275,18 +280,40 @@ export class ChatDaemonRuntime {
 				...deps.routerDeps,
 				onFrame: async (attachment, frame) => await this.#handleFrame(attachment, frame),
 				onAttachment: async attachment => this.#onAttachment(attachment),
+				onReplayReady: async () => await this.#replayReady,
 				onSessionRemoved: async (attachment, reason) => await this.#onSessionRemoved(attachment, reason),
 			},
 		});
 	}
 
 	async start(): Promise<void> {
-		if (this.#cleanupWork.size > 0) {
+		const replayReady = Promise.withResolvers<void>();
+		this.#replayReady = replayReady.promise;
+		// Startup can fail before any attachment observes the replay barrier. Mark
+		// the rejection handled without changing what actual waiters observe.
+		void this.#replayReady.catch(() => undefined);
+		if (this.#cleanupWork.size > 0 || this.#retirementWork.size > 0) {
+			const retirements = [...this.#retirementWork.entries()];
+			const cleanup = [...this.#cleanupWork.values()];
+			const retirement = retirements.map(([, work]) => work);
 			const settled = await Promise.race([
-				Promise.allSettled([...this.#cleanupWork.values()]).then(() => true),
+				Promise.all([Promise.allSettled(cleanup), Promise.allSettled(retirement)]).then(() => true),
 				Bun.sleep(5_000).then(() => false),
 			]);
 			if (!settled) throw new Error("Prior provider cleanup did not settle before chat daemon restart.");
+			const failures = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled(retirement)]);
+			const rejected = failures
+				.flat()
+				.filter((result): result is PromiseRejectedResult => result.status === "rejected");
+			if (rejected.length > 0) {
+				logger.warn(`SDK chat daemon retained ${rejected.length} prior cleanup failure(s) for recovery.`);
+			}
+			for (const [sessionId, work] of retirements)
+				if (this.#retirementWork.get(sessionId) === work && !rejected.some(result => result.status === "rejected"))
+					this.#retirementWork.delete(sessionId);
+			for (const [sessionId, work] of [...this.#cleanupWork.entries()])
+				if (work !== undefined && !rejected.some(result => result.status === "rejected"))
+					this.#cleanupWork.delete(sessionId);
 		}
 		this.#attachments.clear();
 		const retainedProvider =
@@ -301,8 +328,10 @@ export class ChatDaemonRuntime {
 			try {
 				await this.#router.start();
 				await retainedProvider.start();
+				replayReady.resolve();
 				return;
 			} catch (error) {
+				replayReady.reject(error);
 				await this.#router.stop().catch(() => undefined);
 				throw error;
 			}
@@ -363,7 +392,9 @@ export class ChatDaemonRuntime {
 			await this.#router.start();
 			if (this.#discord) await this.#discord.start();
 			if (this.#slack) await this.#slack.start();
+			replayReady.resolve();
 		} catch (error) {
+			replayReady.reject(error);
 			await this.stop();
 			throw error;
 		}
@@ -379,6 +410,20 @@ export class ChatDaemonRuntime {
 	}
 
 	async stop(): Promise<void> {
+		this.#stopping = true;
+		let routerError: unknown;
+		try {
+			await this.#router.stop();
+		} catch (error) {
+			routerError = error;
+		}
+		const cleanupDrain = Promise.allSettled([...this.#cleanupWork.values(), ...this.#retirementWork.values()]);
+		const cleanupSettled = await Promise.race([cleanupDrain.then(() => true), Bun.sleep(5_000).then(() => false)]);
+		const cleanupResults = cleanupSettled
+			? await cleanupDrain
+			: [{ status: "rejected" as const, reason: new Error("Provider cleanup exceeded shutdown drain.") }];
+		if (!cleanupSettled)
+			logger.warn("SDK chat daemon cleanup exceeded the shutdown drain; provider stop will invalidate it.");
 		const providerResults = await Promise.allSettled([this.#discord?.stop(), this.#slack?.stop()]);
 		const discordRestartBlocked = this.#discord?.restartBlocked() ?? false;
 		const slackRestartBlocked = this.#slack?.restartBlocked() ?? false;
@@ -388,10 +433,12 @@ export class ChatDaemonRuntime {
 			this.#presentation = undefined;
 			this.#transportHealthy = undefined;
 		}
-		await this.#router.stop();
-		const failures = providerResults.filter(
-			(result): result is PromiseRejectedResult => result.status === "rejected",
-		);
+		this.#stopping = false;
+		const failures = [
+			...(routerError === undefined ? [] : [{ status: "rejected" as const, reason: routerError }]),
+			...cleanupResults,
+			...providerResults,
+		].filter((result): result is PromiseRejectedResult => result.status === "rejected");
 		if (failures.length > 0)
 			throw new AggregateError(
 				failures.map(result => result.reason),
@@ -428,9 +475,34 @@ export class ChatDaemonRuntime {
 		const discord = this.#discord;
 		const slack = this.#slack;
 		const barrier = (async () => {
-			await this.#cleanupWork.get(attachment.sessionId)?.catch(() => undefined);
-			await discord?.recoverCleanup(attachment.sessionId, attachment.generation);
-			await slack?.recoverCleanup(attachment.sessionId, attachment.generation);
+			const retirement = this.#retirementWork.get(attachment.sessionId);
+			let retirementFailure: unknown;
+			if (retirement) {
+				try {
+					await retirement;
+				} catch (error) {
+					retirementFailure = error;
+					logger.warn(`SDK chat daemon retirement cleanup failed before successor attachment: ${String(error)}`);
+				}
+			}
+			const cleanup = this.#cleanupWork.get(attachment.sessionId);
+			if (cleanup) await cleanup.catch(error => logger.warn(`SDK cleanup retry pending: ${String(error)}`));
+			const [discordRecovered, slackRecovered] = await Promise.all([
+				discord?.recoverCleanup(attachment.sessionId, attachment.generation, attachment.authorityId) ?? true,
+				slack?.recoverCleanup(attachment.sessionId, attachment.generation, attachment.authorityId) ?? true,
+			]);
+			if (!discordRecovered || !slackRecovered)
+				throw new Error("successor_attachment_blocked_until_retirement_is_verified");
+			if (cleanup !== undefined && this.#cleanupWork.get(attachment.sessionId) === cleanup) {
+				this.#cleanupWork.delete(attachment.sessionId);
+				this.#cleanupFailures.delete(attachment.sessionId);
+			}
+			if (
+				retirementFailure !== undefined &&
+				retirement &&
+				this.#retirementWork.get(attachment.sessionId) === retirement
+			)
+				this.#retirementWork.delete(attachment.sessionId);
 		})();
 		this.#attachmentBarriers.set(attachment.sessionId, barrier);
 		try {
@@ -451,11 +523,41 @@ export class ChatDaemonRuntime {
 	): Promise<void> {
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
 		if (reason === "replaced_same_generation") {
-			await this.#discord?.retireAttachment(attachment.sessionId, attachment.generation);
-			await this.#slack?.retireAttachment(attachment.sessionId, attachment.generation);
+			const retirement = this.#trackRetirement(attachment);
+			this.#attachments.delete(attachment.sessionId);
+			await retirement;
+			return;
 		}
 		this.#attachments.delete(attachment.sessionId);
-		if (reason === "removed") await this.#trackCleanup(attachment);
+		if (reason === "removed" && !this.#stopping) await this.#trackCleanup(attachment);
+	}
+
+	#trackRetirement(attachment: SessionAttachment): Promise<void> {
+		const sessionId = attachment.sessionId;
+		const discord = this.#discord;
+		const slack = this.#slack;
+		const previous = this.#retirementWork.get(sessionId);
+		const work = (
+			previous
+				? previous.catch(error => {
+						this.#cleanupFailures.set(sessionId, error);
+					})
+				: Promise.resolve()
+		).then(async () => {
+			// Capture the predecessor providers before stop() can clear the runtime
+			// fields. The successor barrier owns this promise until every retirement
+			// waiter settles, even when takeover overlaps worker shutdown.
+			await discord?.retireAttachment(sessionId, attachment.generation);
+			await slack?.retireAttachment(sessionId, attachment.generation);
+		});
+		this.#retirementWork.set(sessionId, work);
+		void work.then(
+			() => {
+				if (this.#retirementWork.get(sessionId) === work) this.#retirementWork.delete(sessionId);
+			},
+			() => undefined,
+		);
+		return work;
 	}
 
 	async #handleFrame(attachment: SessionAttachment, correlated: CorrelatedFrame): Promise<void> {
@@ -476,7 +578,10 @@ export class ChatDaemonRuntime {
 		}
 		if (name === SESSION_PREPARED_EVENT || bodyType === SESSION_PREPARED_EVENT) return;
 		if (name === "session_ready") {
-			if (correlated.generation !== attachment.generation) return;
+			// The attachment itself is the endpoint-generation authority. An
+			// unpositioned session_ready frame deliberately carries no ring
+			// generation; reject only an explicit, conflicting Router-owned value.
+			if (correlated.generation !== undefined && correlated.generation !== attachment.generation) return;
 			await this.#resume(
 				sessionId,
 				attachment.generation,
@@ -519,7 +624,7 @@ export class ChatDaemonRuntime {
 			await this.#slack.notify(
 				sessionId,
 				content,
-				notification.type === "action_needed" ? notification.id : undefined,
+				notification.type === "action_needed" && notification.kind === "ask" ? notification.id : undefined,
 				attachment.generation,
 				publicationId,
 			);
@@ -528,13 +633,26 @@ export class ChatDaemonRuntime {
 	#trackCleanup(attachment: SessionAttachment): Promise<void> {
 		const sessionId = attachment.sessionId;
 		const previous = this.#cleanupWork.get(sessionId);
-		const work = (previous ? previous.catch(() => undefined) : Promise.resolve()).then(async () => {
+		const work = (
+			previous
+				? previous.catch(error => {
+						this.#cleanupFailures.set(sessionId, error);
+					})
+				: Promise.resolve()
+		).then(async () => {
 			await this.#closeProviders(attachment);
 		});
 		this.#cleanupWork.set(sessionId, work);
-		return work.finally(() => {
-			if (this.#cleanupWork.get(sessionId) === work) this.#cleanupWork.delete(sessionId);
-		});
+		void work.then(
+			() => {
+				if (this.#cleanupWork.get(sessionId) === work) {
+					this.#cleanupWork.delete(sessionId);
+					this.#cleanupFailures.delete(sessionId);
+				}
+			},
+			() => undefined,
+		);
+		return work;
 	}
 	async #closeProviders(attachment: SessionAttachment): Promise<void> {
 		const discord = this.#discord;