@gajae-code/coding-agent 0.12.11 → 0.12.12

package/dist/types/utils/npm-registry.d.ts

@@ -0,0 +1,71 @@
+export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+export type NpmConfigOrigin = "env" | "user" | "global";
+/** Which package manager will run the install this check is gating. */
+export type Installer = "bun" | "npm";
+/** Injection points so tests never read the real environment. */
+export interface NpmRegistryEnvironment {
+    /** Manager that will perform the install; decides Bun-vs-npm config priority. */
+    installer?: Installer;
+    /** Resolves an executable on PATH; used to locate npm's effective prefix. */
+    whichExecutable?: (name: string) => string | undefined;
+    /** Defaults to `$credentialEnv`, which excludes the caller's `cwd/.env`. */
+    lookupEnv?: (name: string) => string | undefined;
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+    readFile?: (filePath: string) => Promise<string | undefined>;
+}
+export interface ResolvedNpmRegistry {
+    registry: string;
+    headers: Record<string, string>;
+    origin: NpmConfigOrigin | "default";
+    /** Where the value came from, e.g. `$npm_config_registry` or `~/.npmrc`. */
+    source: string;
+    /** Config files that exist but could not be read. */
+    warnings: string[];
+}
+export interface LatestPackageVersion {
+    version: string;
+    registry: string;
+    /** Config problems that did not stop the lookup but changed its outcome. */
+    warnings: string[];
+}
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    json: () => Promise<unknown>;
+}
+export type FetchLike = (input: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<FetchResponseLike>;
+export interface NpmRegistryLookupOptions extends NpmRegistryEnvironment {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+/** Thrown when a registry is configured but unusable, so it is never silently ignored. */
+export declare class NpmRegistryConfigError extends Error {
+}
+/**
+ * Parse an `.npmrc` into raw key/value pairs. Later duplicates win, as in npm.
+ *
+ * @internal Exported for tests; production code goes through `resolveNpmRegistry`.
+ */
+export declare function parseNpmrc(contents: string, lookupEnv?: (name: string) => string | undefined): Map<string, string>;
+/**
+ * Build the credential lookup keys npm calls "nerf darts": `//host/path/`,
+ * walking up one path segment at a time until the bare host.
+ *
+ * @internal Exported for tests; production code goes through `resolveNpmRegistry`.
+ */
+export declare function credentialPrefixes(registry: string): string[];
+/** Resolve the registry npm/bun would use for `packageName`, with credentials attached. */
+export declare function resolveNpmRegistry(packageName: string, environment?: NpmRegistryEnvironment): Promise<ResolvedNpmRegistry>;
+/**
+ * Registries can live under a path prefix, so join by string rather than `new URL`.
+ *
+ * @internal Exported for tests; production code goes through `fetchLatestPackageVersion`.
+ */
+export declare function buildRegistryPackageUrl(registry: string, packageName: string, spec?: string): string;
+/** Fetch the latest published version of `packageName` from the configured registry. */
+export declare function fetchLatestPackageVersion(packageName: string, options?: NpmRegistryLookupOptions): Promise<LatestPackageVersion>;

package/examples/extensions/README.md

@@ -14,6 +14,39 @@ mkdir -p .gjc/extensions
 cp packages/coding-agent/examples/extensions/pirate.ts .gjc/extensions/
 ```
 
+### Enable the Ouroboros `ooo` bridge
+
+Install the version-pinned Ouroboros `v0.50.7` MCP profile, then configure its GJC runtime:
+
+```bash
+uv tool install 'ouroboros-ai[mcp]==0.50.7'
+ouroboros setup --runtime gjc
+```
+
+`pipx install 'ouroboros-ai[mcp]==0.50.7'` is the equivalent pipx installation. Do not pipe a mutable branch installer into a shell. Pin source audits to commit `cb658aa819bfabafecbbe91bc36327f10691171b`. The [v0.50.7 release](https://github.com/Q00/ouroboros/releases/tag/v0.50.7) publishes `ouroboros_ai-0.50.7-py3-none-any.whl` with SHA-256 `df42f4ef10e032f2edc3249534bf91e8612dee789dfc3517895a9eb2df7f82c4`; verify downloaded release assets before installing them.
+
+Ouroboros setup installs its own managed bridge. Replace that file with this standalone GJC bridge, which preserves the interview session across serialized follow-up answers, disposes it on GJC session switches, and drops queued predecessor-session starts. Download the example from immutable GJC commit `4311fefd49e9c6781c4d1111b8dd3f758e7d8974` and verify it before installation:
+
+```bash
+curl -fL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/4311fefd49e9c6781c4d1111b8dd3f758e7d8974/packages/coding-agent/examples/extensions/ooo-bridge.ts -o /tmp/gjc-ooo-bridge.ts
+shasum -a 256 /tmp/gjc-ooo-bridge.ts
+mkdir -p "${HOME}/${GJC_CONFIG_DIR:-.gjc}/agent/extensions/ouroboros-ooo-bridge" && cp /tmp/gjc-ooo-bridge.ts "${HOME}/${GJC_CONFIG_DIR:-.gjc}/agent/extensions/ouroboros-ooo-bridge/index.ts"
+```
+
+The `shasum` output must match `2b0e1e25ac145331f112da629076875542db6f6e63c3c17adcd6770a4dcaf7bd` before the copy. The file has no runtime package imports and uses the host API injected by GJC, so compiled binaries do not require a peer `node_modules` directory beside the installation.
+
+For a project-only installation, copy the same verified file to `.gjc/extensions/ouroboros-ooo-bridge/index.ts`. Start a new GJC session after installation, then enter:
+
+```text
+ooo interview "I want to build a task management CLI"
+```
+
+The first question is rendered in GJC. While that interview remains active, ordinary interactive input is sent as the answer with the same Ouroboros session ID; completion clears the correlation and returns subsequent ordinary prompts to GJC. Other `ooo ...` commands continue through `ouroboros dispatch --runtime gjc`, including exit-code `78` pass-through.
+
+Set `OUROBOROS_CLI=/absolute/path/to/ouroboros` when the executable is outside `PATH`. Missing executable, MCP startup, and dispatch failures produce an error notification for the claimed input without preventing GJC startup or ordinary prompts.
+
+This external path is separate from GJC's native `/skill:deep-interview`: the native skill runs GJC's bundled interview workflow, while `ooo interview` delegates to the installed Ouroboros MCP interview tool.
+
 ## Examples
 
 ### Custom Tools & API
@@ -39,10 +72,11 @@ cp packages/coding-agent/examples/extensions/pirate.ts .gjc/extensions/
 
 ### External Dependencies
 
-| Extension         | Description                                                               |
-| ----------------- | ------------------------------------------------------------------------- |
-| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
-| `with-deps/`      | Extension with its own package.json and dependencies                      |
+| Extension         | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution)    |
+| `ooo-bridge.ts`   | Opt-in `ooo ...` input bridge to the installed Ouroboros CLI and MCP runtime |
+| `with-deps/`      | Extension with its own package.json and dependencies                         |
 
 ## Writing Extensions
 

package/examples/extensions/ooo-bridge.ts

@@ -0,0 +1,15 @@
+interface OooBridgeExtensionAPI {
+	pi: unknown;
+	on(event: "input" | "session_switch", handler: (event: unknown, context: unknown) => unknown): void;
+}
+
+interface OooBridgeHost {
+	createOuroborosOooBridge(): ((event: unknown, context: unknown) => unknown) & { reset(): Promise<void> };
+}
+
+export default function (pi: OooBridgeExtensionAPI) {
+	const host = pi.pi as OooBridgeHost;
+	const bridge = host.createOuroborosOooBridge();
+	pi.on("input", bridge);
+	pi.on("session_switch", () => bridge.reset());
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.12.11",
+	"version": "0.12.12",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -53,13 +53,13 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.12.11",
-		"@gajae-code/agent-core": "0.12.11",
-		"@gajae-code/ai": "0.12.11",
-		"@gajae-code/bridge-client": "0.12.11",
-		"@gajae-code/natives": "0.12.11",
-		"@gajae-code/tui": "0.12.11",
-		"@gajae-code/utils": "0.12.11",
+		"@gajae-code/stats": "0.12.12",
+		"@gajae-code/agent-core": "0.12.12",
+		"@gajae-code/ai": "0.12.12",
+		"@gajae-code/bridge-client": "0.12.12",
+		"@gajae-code/natives": "0.12.12",
+		"@gajae-code/tui": "0.12.12",
+		"@gajae-code/utils": "0.12.12",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/generate-sdk-operation-inventory.ts

@@ -37,6 +37,8 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"agent_session:constructor": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:registerToolSessionCleanup":
 		"internal tool lifecycle cleanup registration, not a user-facing SDK control seam",
+	"agent_session:registerToolSessionTransitionCleanup":
+		"internal tool transition cleanup registration for shared artifact-manager ownership, not a user-facing SDK control seam",
 	"agent_session:nextToolChoice": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:setForcedToolChoice": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:getActiveSkillState": "internal accessor/plumbing, not a user-facing control seam",
@@ -66,6 +68,8 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"agent_session:closeWriterStrict": "internal ACP lifecycle teardown plumbing, not a user-facing control seam",
 	"agent_session:disposeChildSubprocesses": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:waitForIdle": "internal accessor/plumbing, not a user-facing control seam",
+	"agent_session:extendStartupTurnBarrier":
+		"internal CLI startup-readiness fence composition, not a user-facing SDK control seam",
 	"agent_session:awaitPendingContextTransformations":
 		"internal context-transformation lifecycle barrier, not a user-facing SDK control seam",
 	"agent_session:drainAsyncJobDeliveriesForAcp": "internal accessor/plumbing, not a user-facing control seam",

package/src/async/job-manager.ts

@@ -463,6 +463,7 @@ export class AsyncJobManager {
 	readonly #terminalWaits = new Map<string, TerminalWaitState>();
 	#waitSeq = 0;
 	readonly #publishedTerminalGenerations = new Set<string>();
+	readonly #settledJobIds = new Set<string>();
 	#jobGenerationSeq = 0;
 	readonly #liveHandles = new Map<string, SubagentLiveHandle>();
 	readonly #subagentProgress = new Map<string, AgentProgress>();
@@ -820,6 +821,7 @@ export class AsyncJobManager {
 
 		this.#expireMonitorTombstones();
 		const id = this.#resolveJobId(options?.id);
+		this.#settledJobIds.delete(id);
 		const abortController = new AbortController();
 		const startTime = Date.now();
 
@@ -919,7 +921,9 @@ export class AsyncJobManager {
 				this.#scheduleEviction(id);
 				this.#drainResumeQueue();
 			}
-		})();
+		})().finally(() => {
+			this.#settledJobIds.add(id);
+		});
 
 		this.#jobs.set(id, job);
 		this.#notifyChange();
@@ -1218,6 +1222,8 @@ export class AsyncJobManager {
 			) {
 				continue;
 			}
+			if (job.status === "cancelled" && this.#settledJobIds.has(job.id) && !this.#subagentRecords.has(subagentId))
+				continue;
 			if (!targets.has(subagentId)) {
 				targets.set(subagentId, { subagentId, jobId: job.id, source: "metadata_job" });
 			}
@@ -1298,7 +1304,7 @@ export class AsyncJobManager {
 				lease.targets.map(target => target.subagentId),
 			);
 		}
-		if (state.phase === "proved" && state.proof) return state.proof;
+		if (state.phase === "proved" && state.proof?.confirmed) return state.proof;
 		state.phase = "proving";
 		const settled = new Set<string>();
 		const promises: Promise<void>[] = [];
@@ -2064,6 +2070,7 @@ export class AsyncJobManager {
 		this.#purgeTerminalSubagentStateForJob(jobId);
 		const job = this.#jobs.get(jobId);
 		this.#jobs.delete(jobId);
+		this.#settledJobIds.delete(jobId);
 		this.#lifecycles.delete(jobId);
 		this.#lifecyclePhases.delete(jobId);
 		this.#deadLetteredDeliveries.delete(jobId);

package/src/cli/notify-cli.ts

@@ -7,6 +7,7 @@ import { createInterface } from "node:readline/promises";
 import { APP_NAME } from "@gajae-code/utils/dirs";
 import chalk from "chalk";
 import { Settings, type SettingsAtomicPatch } from "../config/settings";
+import { SessionIndex } from "../sdk/broker/session-index";
 import {
 	ChatDaemonController,
 	type EnsureChatDaemonResult,
@@ -14,6 +15,7 @@ import {
 	ensureSlackDaemon,
 } from "../sdk/bus/chat-daemon-control";
 import { getNotificationConfig, maskToken, tokenFingerprint } from "../sdk/bus/config";
+import { type ActivatedPreparedSession, activatePreparedSession } from "../sdk/bus/existing-thread-readiness";
 import {
 	clearTelegramActivationMarker,
 	createTelegramActivationMarker,
@@ -36,6 +38,12 @@ import {
 	sanitizeDiagnostic,
 	sendNotificationTest,
 } from "../sdk/bus/notification-service";
+import {
+	type BoundSlackThread,
+	bindConfiguredSlackThread,
+	isBoundedSlackRootTs,
+	SlackThreadBindingError,
+} from "../sdk/bus/slack-thread-binding";
 import {
 	type EnsureTelegramDaemonDetailedResult,
 	ensureTelegramDaemonRunningDetailed,
@@ -49,7 +57,15 @@ import {
 	type TelegramSetupTimers,
 } from "../sdk/bus/telegram-setup";
 
-export type NotifyAction = "setup" | "status" | "health" | "test" | "recovery" | "daemon-internal";
+export type NotifyAction =
+	| "setup"
+	| "status"
+	| "health"
+	| "test"
+	| "recovery"
+	| "bind-thread"
+	| "activate-thread"
+	| "daemon-internal";
 export type NotifySetupProvider = "telegram" | "discord" | "slack";
 
 export interface NotifyCommandArgs {
@@ -72,6 +88,8 @@ export interface NotifyCommandArgs {
 	forceDaemonLock?: boolean;
 	probe?: boolean;
 	message?: string;
+	sessionId?: string;
+	threadTs?: string;
 }
 
 export interface NotifyCommandDeps {
@@ -99,6 +117,8 @@ export interface NotifyCommandDeps {
 	setupPidIncarnation?: (pid: number) => string | undefined;
 	ensureProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<EnsureChatDaemonResult>;
 	ensureTelegramDaemon?: (settings: Settings) => Promise<EnsureTelegramDaemonDetailedResult>;
+	bindSlackThread?: (input: { settings: Settings; sessionId: string; threadTs: string }) => Promise<BoundSlackThread>;
+	activatePreparedSession?: (input: { settings: Settings; sessionId: string }) => Promise<ActivatedPreparedSession>;
 }
 
 export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
@@ -200,6 +220,23 @@ export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
 			? { action, rawArgs: args.slice(2), forceDaemonLock: flags.get("--force-daemon-lock") === true }
 			: undefined;
 	}
+	if (action === "bind-thread") {
+		const rest = args.slice(2);
+		const flags = parseFlags(rest, new Set(["--session-id", "--thread-ts"]), new Set());
+		if (!flags) return undefined;
+		const sessionId = flags.get("--session-id");
+		const threadTs = flags.get("--thread-ts");
+		if (typeof sessionId !== "string" || typeof threadTs !== "string") return undefined;
+		return { action, rawArgs: rest, sessionId, threadTs };
+	}
+	if (action === "activate-thread") {
+		const rest = args.slice(2);
+		const flags = parseFlags(rest, new Set(["--session-id"]), new Set());
+		if (!flags) return undefined;
+		const sessionId = flags.get("--session-id");
+		if (typeof sessionId !== "string") return undefined;
+		return { action, rawArgs: rest, sessionId };
+	}
 	if (action === "daemon-internal") {
 		return {
 			action,
@@ -232,6 +269,12 @@ export async function runNotifyCommand(cmd: NotifyCommandArgs, deps: NotifyComma
 		case "recovery":
 			await runRecovery(deps, cmd.forceDaemonLock);
 			return;
+		case "bind-thread":
+			await runBindThread(cmd, deps);
+			return;
+		case "activate-thread":
+			await runActivateThread(cmd, deps);
+			return;
 		case "daemon-internal":
 			if (cmd.smoke) {
 				await runDaemonInternal(["--smoke"]);
@@ -457,6 +500,7 @@ async function runTelegramSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps)
 		process.stdout.write(`Using provided chat id ${result.chatId} (non-interactive).\n`);
 	}
 	let settingsCommitted = false;
+	let commitAttempted = false;
 	try {
 		const proposedIdentity = deps.setupPreflight
 			? proposedIdentityFromSetupPreflight(deps.setupPreflight, token.trim(), result.chatId)
@@ -480,6 +524,7 @@ async function runTelegramSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps)
 			{ path: "notifications.telegram.enabled", op: "set", value: true },
 		];
 		if (deps.setupRedact ?? cmd.redact) patches.push({ path: "notifications.redact", op: "set", value: true });
+		commitAttempted = true;
 		const receipt = await settings.commitAtomicBatch(patches);
 		settingsCommitted = true;
 		const activationMarker = createTelegramActivationMarker({
@@ -534,8 +579,24 @@ async function runTelegramSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps)
 		receipt.discard();
 	} catch (error) {
 		const detail = sanitizeDiagnostic(error instanceof Error ? error.message : "unknown persistence failure", token);
+		// The wording must describe what a follow-up `notify status` will show. A failure
+		// raised after the durable write landed — including one raised from inside the
+		// commit itself — must not claim the settings were not persisted, or the operator
+		// walks away believing Telegram is off while the daemon is armed for that token.
+		// Observed state wins; the code-path flag is only the fallback for an unreadable read.
+		const observed = telegramIntentIsPersisted(settings, token.trim(), result.chatId);
+		const persisted = observed ?? settingsCommitted;
+		// A commit that was entered and then failed, whose durable state is also unreadable,
+		// is genuinely undecided: `commitAtomicBatch` can persist and still throw. Claiming
+		// either outcome would be a guess, so say so and point at the authoritative check.
+		if (!persisted && observed === undefined && commitAttempted) {
+			throw new Error(
+				"Telegram notification settings may or may not have been saved, and the stored configuration could not be read; " +
+					`run \`gjc notify status\` before retrying: ${detail}`,
+			);
+		}
 		throw new Error(
-			settingsCommitted
+			persisted
 				? `Telegram notification settings were saved, but activation or recovery failed: ${detail}`
 				: `Unable to persist and activate Telegram notification settings: ${detail}`,
 		);
@@ -545,6 +606,26 @@ async function runTelegramSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps)
 	);
 }
 
+/**
+ * Whether the durable settings already carry the Telegram intent this setup run attempted to
+ * write: the same identity *and* the enabled state it would have produced. Matching the token
+ * and chat id alone is not enough — a previously disabled configuration can already hold both,
+ * and a commit that fails before enabling Telegram has persisted nothing new.
+ *
+ * Returns `undefined` when the durable state cannot be observed, so the caller can fall back
+ * instead of reporting a state nobody read.
+ */
+function telegramIntentIsPersisted(settings: Settings, botToken: string, chatId: string): boolean | undefined {
+	try {
+		const cfg = getNotificationConfig(settings);
+		return (
+			cfg.enabled === true && cfg.telegram?.enabled === true && cfg.botToken === botToken && cfg.chatId === chatId
+		);
+	} catch {
+		return undefined;
+	}
+}
+
 function proposedIdentityFromSetupPreflight(
 	preflight: TelegramSetupPreflight,
 	botToken: string,
@@ -728,6 +809,143 @@ async function runRecovery(deps: NotifyCommandDeps, forceDaemonLock = false): Pr
 	process.stdout.write(`${formatNotificationRecoveryReport(report)}\n`);
 }
 
+/** Target and credential inputs stay owned by `notify setup`; binding never re-routes a session elsewhere. */
+const BIND_THREAD_REJECTED_INPUTS: readonly (keyof NotifyCommandArgs)[] = [
+	"provider",
+	"token",
+	"chatId",
+	"discordBotToken",
+	"discordApplicationId",
+	"discordGuildId",
+	"discordParentChannelId",
+	"slackBotToken",
+	"slackAppToken",
+	"slackWorkspaceId",
+	"slackChannelId",
+	"slackAuthorizedUserId",
+	"message",
+	"probe",
+	"redact",
+	"forceDaemonLock",
+	"smoke",
+];
+
+export interface BindThreadInvocation {
+	sessionId: string;
+	threadTs: string;
+}
+
+/**
+ * Enforce the exact `bind-thread` grammar at every entrypoint.
+ *
+ * The command accepts only a session and a root; a positional argument, an
+ * unrelated notify flag, or a target/credential input is a rejection rather than
+ * something silently ignored, so no other invocation shape can reach the
+ * binding authority.
+ */
+export function assertStrictBindThreadInvocation(cmd: NotifyCommandArgs): BindThreadInvocation {
+	const rejected = BIND_THREAD_REJECTED_INPUTS.filter(key => {
+		const value = cmd[key];
+		return value !== undefined && value !== false && value !== "";
+	});
+	if (rejected.length > 0)
+		throw new Error(
+			`notify bind-thread accepts only --session-id and --thread-ts (rejected: ${rejected.join(", ")}).`,
+		);
+	const { sessionId, threadTs } = cmd;
+	if (!sessionId || !threadTs) throw new Error("notify bind-thread requires --session-id and --thread-ts.");
+	const allowed = new Set(["--session-id", sessionId, "--thread-ts", threadTs]);
+	const stray = cmd.rawArgs.filter(token => !allowed.has(token));
+	if (stray.length > 0)
+		throw new Error(`notify bind-thread does not accept additional arguments (rejected: ${stray.join(", ")}).`);
+	if (!isBoundedSlackRootTs(threadTs))
+		throw new SlackThreadBindingError(
+			"invalid_root",
+			"Slack root timestamp must be a bounded <seconds>.<fraction> message timestamp.",
+		);
+	return { sessionId, threadTs };
+}
+
+/** Adopt an existing Slack thread for a live session; the operator supplies only session and root identity. */
+async function runBindThread(cmd: NotifyCommandArgs, deps: NotifyCommandDeps): Promise<void> {
+	const { sessionId, threadTs } = assertStrictBindThreadInvocation(cmd);
+	const bind = deps.bindSlackThread ?? (input => bindConfiguredSlackThread(input));
+	const bound = await bind({ settings: await getSettings(deps), sessionId, threadTs });
+	process.stdout.write(`${formatBoundSlackThread(bound)}\n`);
+}
+
+/** Confirmation carries identifiers only: no tokens, message bodies, or control secrets. */
+export function formatBoundSlackThread(bound: BoundSlackThread): string {
+	return [
+		`${chalk.green("Bound")} Slack thread for session ${bound.sessionId}`,
+		`  session generation: ${bound.endpointGeneration}`,
+		`  workspace/channel:  ${bound.teamId}/${bound.channelId}`,
+		`  thread root:        ${bound.rootTs}`,
+		`  daemon owner:       ${bound.ownerId} (generation ${bound.daemonGeneration})`,
+	].join("\n");
+}
+
+/** Activation carries only a session; a root or target here is a rejection, not an override. */
+const ACTIVATE_THREAD_REJECTED_INPUTS: readonly (keyof NotifyCommandArgs)[] = [
+	...BIND_THREAD_REJECTED_INPUTS,
+	"threadTs",
+];
+
+export interface ActivateThreadInvocation {
+	sessionId: string;
+}
+
+/**
+ * Enforce the exact `activate-thread` grammar at every entrypoint.
+ *
+ * Activation names one prepared session and nothing else: the root it adopts is
+ * already the applied binding, so a supplied root, target, or credential is a
+ * rejection rather than something silently ignored.
+ */
+export function assertStrictActivateThreadInvocation(cmd: NotifyCommandArgs): ActivateThreadInvocation {
+	const rejected = ACTIVATE_THREAD_REJECTED_INPUTS.filter(key => {
+		const value = cmd[key];
+		return value !== undefined && value !== false && value !== "";
+	});
+	if (rejected.length > 0)
+		throw new Error(`notify activate-thread accepts only --session-id (rejected: ${rejected.join(", ")}).`);
+	const { sessionId } = cmd;
+	if (!sessionId) throw new Error("notify activate-thread requires --session-id.");
+	const allowed = new Set(["--session-id", sessionId]);
+	const stray = cmd.rawArgs.filter(token => !allowed.has(token));
+	if (stray.length > 0)
+		throw new Error(`notify activate-thread does not accept additional arguments (rejected: ${stray.join(", ")}).`);
+	return { sessionId };
+}
+
+/**
+ * Publish the readiness a prepared session withheld.
+ *
+ * The session's own host owns the decision: this command only proves discovery
+ * authority and asks it to activate, so activation before a binding exists is
+ * refused by the session rather than forced by the operator.
+ */
+async function runActivateThread(cmd: NotifyCommandArgs, deps: NotifyCommandDeps): Promise<void> {
+	const { sessionId } = assertStrictActivateThreadInvocation(cmd);
+	const activate =
+		deps.activatePreparedSession ??
+		(async (input: { settings: Settings; sessionId: string }) =>
+			await activatePreparedSession({
+				sessionIndex: await new SessionIndex(input.settings.getAgentDir()).open(),
+				sessionId: input.sessionId,
+			}));
+	const activated = await activate({ settings: await getSettings(deps), sessionId });
+	process.stdout.write(`${formatActivatedSession(activated)}\n`);
+}
+
+/** Confirmation carries identifiers only: no endpoints, tokens, or thread content. */
+export function formatActivatedSession(activated: ActivatedPreparedSession): string {
+	return [
+		`${chalk.green("Activated")} session ${activated.sessionId} (${activated.status})`,
+		`  session generation: ${activated.endpointGeneration}`,
+	].join("\n");
+}
+
 export function printNotifyHelp(): void {
 	process.stdout.write(`${chalk.bold(`${APP_NAME} notify`)} - Configure Telegram, Discord, or Slack notifications
 
@@ -744,6 +962,8 @@ ${chalk.bold("Usage:")}
   ${APP_NAME} notify health [--provider telegram|discord|slack] [--probe]
   ${APP_NAME} notify test [--provider telegram|discord|slack] [--message <text>]
   ${APP_NAME} notify recovery [--force-daemon-lock]
+  ${APP_NAME} notify bind-thread --session-id <sessionId> --thread-ts <rootTs>
+  ${APP_NAME} notify activate-thread --session-id <sessionId>
 
 ${chalk.bold("Subcommands:")}
   setup     Pair Telegram or atomically save and activate complete Discord/Slack settings
@@ -751,6 +971,8 @@ ${chalk.bold("Subcommands:")}
   health    Report selected provider state; --probe uses REST only and never opens Gateway/Socket Mode
   test      Send a one-off test through one selected or uniquely effective provider
   recovery  Clear dead-owner daemon locks and stale per-session endpoint files (never touches a live owner); --force-daemon-lock retries only with the same fail-closed dead-owner proof
+  bind-thread      Adopt an existing Slack thread as a live session's root; target and credentials come from setup only
+  activate-thread  Publish the readiness a prepared session withheld once its thread binding is applied
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} notify setup
@@ -761,6 +983,8 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} notify health --provider discord --probe
   ${APP_NAME} notify test --provider slack --message "hello from gjc"
   ${APP_NAME} notify recovery
+  ${APP_NAME} notify bind-thread --session-id 01J... --thread-ts 1785573662.132329
+  ${APP_NAME} notify activate-thread --session-id 01J...
 
 ${chalk.bold("Threaded Mode:")}
   GJC uses Telegram private-chat topics for per-session threads. Setup verifies the bot