@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/cli/daemon-cli.ts

@@ -22,7 +22,7 @@ import {
 } from "../daemon/operator-contract";
 import { runChatDaemonInternal } from "../sdk/bus/chat-daemon-cli";
 
-export type DaemonCliAction = "list" | "status" | "stop" | "reload";
+export type DaemonCliAction = "list" | "status" | "stop" | "restart";
 export type DaemonInternalCliAction = "discord-internal" | "slack-internal";
 export type DaemonCommandAction = DaemonCliAction | DaemonInternalCliAction;
 
@@ -49,6 +49,7 @@ export interface DaemonCommandArgs {
 	gracefulTimeoutMs?: number;
 	killTimeoutMs?: number;
 	spawnIfStopped?: boolean;
+	allowDisabledNoop?: boolean;
 	smoke?: boolean;
 	ownerId?: string;
 	agentDir?: string;
@@ -59,6 +60,7 @@ export interface DaemonCommandArgs {
 export interface DaemonCommandDeps {
 	settings?: Settings;
 	controllers?: BuiltInDaemonController[];
+	setExitCode?: (code: number) => void;
 }
 
 const INTERNAL_ACTIONS: DaemonInternalCliAction[] = ["discord-internal", "slack-internal"];
@@ -147,15 +149,22 @@ export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonComma
 		killTimeoutMs: cmd.killTimeoutMs,
 		force: cmd.force,
 		spawnIfStopped: cmd.spawnIfStopped,
+		allowDisabledNoop: cmd.allowDisabledNoop,
 	};
 	const results: DaemonOperationResult[] = [];
 	for (const controller of controllers) {
-		results.push(cmd.action === "reload" ? await controller.reload(opts) : await controller.stop(opts));
+		results.push(cmd.action === "restart" ? await controller.reload(opts) : await controller.stop(opts));
 	}
 	if (cmd.json) {
 		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
 	} else {
 		process.stdout.write(`${results.map(formatDaemonResult).join("\n")}\n`);
 	}
-	if (results.some(r => !r.ok)) process.exitCode = DAEMON_EXIT.failure;
+	if (results.some(r => !r.ok))
+		(
+			deps.setExitCode ??
+			(code => {
+				process.exitCode = code;
+			})
+		)(DAEMON_EXIT.failure);
 }

package/src/cli/fast-help.ts

@@ -8,6 +8,7 @@ export function getExtraHelpText(): string {
   ${APP_NAME} session              - List, inspect, create, remove, or attach sessions
   ${APP_NAME} state                - Inspect or manage persisted GJC state
   ${APP_NAME} auth-broker         - Manage the auth-broker (credential vault)
+  ${APP_NAME} accounts             - List, check, pin, and remove stored OAuth accounts
   ${APP_NAME} auth-gateway        - Run an auth-gateway forward proxy
   ${APP_NAME} harness              - Run harness control-plane commands
   ${APP_NAME} coordinator          - Manage coordinator/runtime coordination helpers

package/src/cli/mcp-cli.ts

@@ -2,12 +2,24 @@
  * Direct MCP server registration CLI helpers.
  *
  * This surface only writes explicit user-provided server definitions to GJC's
- * own MCP config. It never imports or inherits live configs from other agents.
+ * own native MCP config (project `./.gjc/mcp.json` or user `~/.gjc/agent/mcp.json`)
+ * through the canonical scope-aware reader/writer. It never imports or inherits
+ * live configs from other agents. Registrations written here are consumed by
+ * ordinary standalone sessions at startup (conventional autoload) unless
+ * disabled or opted out via `--no-mcp`.
  */
-import { getMCPConfigPath, getProjectDir } from "@gajae-code/utils";
-import { getMCPServer, readMCPConfigFile, removeMCPServer, upsertMCPServer } from "../runtime-mcp/config-writer";
+import { getProjectDir } from "@gajae-code/utils";
 import { redactMCPEndpoint } from "../runtime-mcp/redaction";
-import type { MCPConfigFile, MCPServerConfig } from "../runtime-mcp/types";
+import {
+	getScopeMCPServer,
+	type MCPConfigScope,
+	readScopeDisabledServers,
+	readScopeMCPConfig,
+	removeScopeMCPServer,
+	resolveScopeMCPConfigPath,
+	upsertScopeMCPServer,
+} from "../runtime-mcp/scope-config";
+import type { MCPServerConfig } from "../runtime-mcp/types";
 
 export type MCPAction = "add" | "list" | "remove";
 
@@ -35,35 +47,62 @@ export interface MCPCommandArgs {
 export class MCPArgsError extends Error {}
 
 interface ScopedPath {
-	scope: "user" | "project";
+	scope: MCPConfigScope;
 	path: string;
 }
 
-interface RuntimeDisclosure {
-	runtimeStatus: "storage-only";
-	runtimeLoadedByStandalone: false;
-	runtimeNote: string;
-}
+/** Runtime status of a stored registration for conventional autoload. */
+type AutoloadStatus = "autoload" | "autoload-off" | "disabled";
 
 interface RedactedServerEntry {
 	name: string;
 	config: MCPServerConfig;
 }
 
-interface RuntimeRedactedServerEntry extends RedactedServerEntry, RuntimeDisclosure {}
+interface RuntimeServerEntry extends RedactedServerEntry {
+	scope: "user" | "project";
+	path: string;
+	/** Whether ordinary standalone sessions load this registration at startup. */
+	runtimeStatus: AutoloadStatus;
+	/** Human-readable explanation of the runtime status. */
+	runtimeNote: string;
+}
 
 const REDACTED = "<redacted>";
 const SENSITIVE_KEY_PATTERN =
 	/(?:token|secret|key|credential|password|passwd|pwd|authorization|auth|bearer|cookie|session)/i;
-const STORAGE_ONLY_RUNTIME_DISCLOSURE: RuntimeDisclosure = {
-	runtimeStatus: "storage-only",
-	runtimeLoadedByStandalone: false,
-	runtimeNote: "Stored MCP registrations are not loaded by normal standalone gjc sessions today.",
-};
+
+/**
+ * Compute the conventional-autoload status of a stored server.
+ *
+ * - `autoload-off`: the server opted out of startup connection via `autoload: false`.
+ * - `disabled`: the server is disabled via `enabled: false` or the `disabledServers` list.
+ * - `autoload`: connected by ordinary standalone sessions at startup.
+ */
+export function computeAutoloadStatus(
+	name: string,
+	config: MCPServerConfig,
+	disabledServers: ReadonlySet<string>,
+): AutoloadStatus {
+	if (config.enabled === false || disabledServers.has(name)) return "disabled";
+	if (config.autoload === false) return "autoload-off";
+	return "autoload";
+}
+
+function autoloadStatusNote(status: AutoloadStatus): string {
+	switch (status) {
+		case "autoload":
+			return "Loaded by ordinary standalone gjc sessions at startup.";
+		case "autoload-off":
+			return "Configured but not auto-loaded at startup (autoload: false); connect on demand via /mcp.";
+		case "disabled":
+			return "Disabled; not loaded by sessions. Re-enable to autoload.";
+	}
+}
 
 function resolvePath(args: MCPCommandArgs): ScopedPath {
-	const scope = args.flags.project ? "project" : "user";
-	return { scope, path: getMCPConfigPath(scope, args.cwd ?? getProjectDir()) };
+	const scope: MCPConfigScope = args.flags.project ? "project" : "user";
+	return { scope, path: resolveScopeMCPConfigPath(scope, args.cwd ?? getProjectDir()) };
 }
 
 function parsePairs(values: string[] | undefined, label: string): Record<string, string> | undefined {
@@ -211,14 +250,32 @@ export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig
 	return redacted;
 }
 
-function withRuntimeDisclosure<T extends object>(value: T): T & RuntimeDisclosure {
-	return { ...value, ...STORAGE_ONLY_RUNTIME_DISCLOSURE };
+function withRuntimeDisclosure<T extends object>(
+	value: T,
+	status: AutoloadStatus,
+): T & { runtimeStatus: AutoloadStatus; runtimeNote: string } {
+	return { ...value, runtimeStatus: status, runtimeNote: autoloadStatusNote(status) };
 }
 
-function collectEntries(config: MCPConfigFile): RuntimeRedactedServerEntry[] {
-	return Object.entries(config.mcpServers ?? {})
+async function collectEntries(scoped: ScopedPath, cwd?: string): Promise<RuntimeServerEntry[]> {
+	const [config, disabled] = await Promise.all([
+		readScopeMCPConfig(scoped.scope, cwd),
+		readScopeDisabledServers(scoped.scope, cwd),
+	]);
+	const disabledSet = new Set(disabled);
+	return Object.entries(config.config.mcpServers ?? {})
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, serverConfig]) => withRuntimeDisclosure({ name, config: redactMCPServerConfig(serverConfig) }));
+		.map(([name, serverConfig]) => {
+			const runtimeStatus = computeAutoloadStatus(name, serverConfig, disabledSet);
+			return {
+				name,
+				scope: scoped.scope,
+				path: scoped.path,
+				runtimeStatus,
+				runtimeNote: autoloadStatusNote(runtimeStatus),
+				config: redactMCPServerConfig(serverConfig),
+			};
+		});
 }
 
 function writeJson(value: unknown): void {
@@ -241,78 +298,89 @@ function renderDetails(entry: RedactedServerEntry): string {
 async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 	if (!args.name) throw new MCPArgsError("`gjc mcp add` requires a server name.");
 	const config = buildServerConfig(args);
-	const result = await upsertMCPServer(scoped.path, args.name, config, { force: args.flags.force });
+	const { result, config: storedConfig } = await upsertScopeMCPServer(
+		scoped.scope,
+		args.name,
+		config,
+		{
+			force: args.flags.force,
+		},
+		args.cwd,
+	);
 	const redacted = redactMCPServerConfig(config);
+	const disabled = new Set(storedConfig.disabledServers ?? (await readScopeDisabledServers(scoped.scope, args.cwd)));
+	const runtimeStatus = computeAutoloadStatus(args.name, config, disabled);
 	if (args.flags.json) {
 		writeJson(
-			withRuntimeDisclosure({
-				action: "add",
-				status: result.status,
-				name: args.name,
-				scope: scoped.scope,
-				path: scoped.path,
-				config: redacted,
-			}),
+			withRuntimeDisclosure(
+				{
+					action: "add",
+					status: result.status,
+					name: args.name,
+					scope: scoped.scope,
+					path: scoped.path,
+					config: redacted,
+				},
+				runtimeStatus,
+			),
 		);
 		return;
 	}
 	if (result.status === "skipped") {
 		process.stdout.write(
 			`MCP server "${args.name}" already exists in ${scoped.scope} config. Pass --force to overwrite. ` +
-				"Status: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n",
+				`Runtime: ${autoloadStatusNote(runtimeStatus)}\n`,
 		);
 		return;
 	}
 	process.stdout.write(
-		`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
+		`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\n` +
+			`Runtime: ${autoloadStatusNote(runtimeStatus)}\n`,
 	);
 }
 
 async function runList(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
-	const config = await readMCPConfigFile(scoped.path);
-	const entries = collectEntries(config);
+	const entries = await collectEntries(scoped, args.cwd);
 	if (args.flags.json) {
-		writeJson(withRuntimeDisclosure({ action: "list", scope: scoped.scope, path: scoped.path, servers: entries }));
+		writeJson({
+			action: "list",
+			scope: scoped.scope,
+			path: scoped.path,
+			servers: entries,
+		});
 		return;
 	}
 	if (entries.length === 0) {
-		process.stdout.write(
-			`No MCP servers registered in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
-		);
+		process.stdout.write(`No MCP servers registered in ${scoped.scope} config: ${scoped.path}\n`);
 		return;
 	}
-	process.stdout.write(
-		`MCP servers in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
-	);
+	process.stdout.write(`MCP servers in ${scoped.scope} config: ${scoped.path}\n`);
 	for (const entry of entries) {
 		process.stdout.write(`${renderDetails(entry)}\n`);
+		process.stdout.write(`Runtime: ${entry.runtimeNote}\n`);
 	}
 }
 
 async function runRemove(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 	if (!args.name) throw new MCPArgsError("`gjc mcp remove` requires a server name.");
-	const existing = await getMCPServer(scoped.path, args.name);
-	if (!existing) {
+	const existing = await getScopeMCPServer(scoped.scope, args.name, args.cwd);
+	if (!existing.config) {
 		throw new MCPArgsError(`MCP server "${args.name}" not found in ${scoped.scope} config.`);
 	}
-	await removeMCPServer(scoped.path, args.name);
-	const entry = { name: args.name, config: redactMCPServerConfig(existing) };
+	await removeScopeMCPServer(scoped.scope, args.name, args.cwd);
+	const entry = { name: args.name, config: redactMCPServerConfig(existing.config) };
 	if (args.flags.json) {
-		writeJson(
-			withRuntimeDisclosure({
-				action: "remove",
-				status: "removed",
-				name: args.name,
-				scope: scoped.scope,
-				path: scoped.path,
-				removed: entry,
-			}),
-		);
+		writeJson({
+			action: "remove",
+			status: "removed",
+			name: args.name,
+			scope: scoped.scope,
+			path: scoped.path,
+			removed: entry,
+		});
 		return;
 	}
-	process.stdout.write(
-		`Removed MCP server "${args.name}" from ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
-	);
+	process.stdout.write(`Removed MCP server "${args.name}" from ${scoped.scope} config: ${scoped.path}\n`);
 	process.stdout.write(`${renderDetails(entry)}\n`);
 }
 

package/src/cli/notify-cli.ts

@@ -7,7 +7,6 @@ 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,
@@ -15,7 +14,6 @@ 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,
@@ -56,6 +54,8 @@ import {
 	type TelegramSetupPreflight,
 	type TelegramSetupTimers,
 } from "../sdk/bus/telegram-setup";
+import { SessionRouter } from "../sdk/router";
+import type { ActivatedPreparedSession } from "../sdk/session-activation";
 
 export type NotifyAction =
 	| "setup"
@@ -548,12 +548,7 @@ async function runTelegramSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps)
 				reconnect: async () =>
 					deps.ensureTelegramDaemon
 						? await deps.ensureTelegramDaemon(settings)
-						: await ensureTelegramDaemonRunningDetailed({
-								settings,
-								cwd: process.cwd(),
-								sessionId: `notify-cli-${process.pid}`,
-								registerRoot: false,
-							}),
+						: await ensureTelegramDaemonRunningDetailed({ settings }),
 				persistInactive: async marker => await persistTelegramActivationMarker(settings, marker),
 				clearInactive: async marker => await clearTelegramActivationMarker(settings, marker),
 				marker: activationMarker,
@@ -929,11 +924,10 @@ async function runActivateThread(cmd: NotifyCommandArgs, deps: NotifyCommandDeps
 	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,
-			}));
+		(async (input: { settings: Settings; sessionId: string }) => {
+			const router = new SessionRouter({ agentDir: input.settings.getAgentDir() });
+			return await router.activatePreparedSession(input.sessionId);
+		});
 	const activated = await activate({ settings: await getSettings(deps), sessionId });
 	process.stdout.write(`${formatActivatedSession(activated)}\n`);
 }
@@ -987,7 +981,7 @@ ${chalk.bold("Examples:")}
   ${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
+  GJC uses Telegram private-chat topics for coordinator/lifecycle sessions only. Setup verifies the bot
   capability via getMe.has_topics_enabled. Enable Threaded Mode in @BotFather > Bot Settings
   > Threads Settings; bots cannot toggle it through the Bot API. If Telegram refuses topic
   creation at runtime, GJC delivers flat to the paired private chat with outbound notifications

package/src/cli/root-flags.ts

@@ -16,9 +16,17 @@ export const ROOT_LAUNCH_FLAGS = {
 		description:
 			"Stored credential selector: email:<addr>, id:<n>, account:<id>, project:<id>, or provider/email:<addr>",
 	}),
+	"prefer-credential": Flags.string({
+		description:
+			"Preferred stored credential with quota fallback: email:<addr>, id:<n>, account:<id>, project:<id>, or provider/id:<n>",
+	}),
 	"system-prompt": Flags.string({ description: "System prompt (default: coding assistant prompt)" }),
 	"append-system-prompt": Flags.string({ description: "Append text or file contents to the system prompt" }),
 	"mcp-config": Flags.string({ description: "Tools-only MCP config file (absolute path)" }),
+	"no-mcp": Flags.boolean({
+		description:
+			"Disable conventional MCP autoload (native user ~/.gjc/agent/mcp.json and project .gjc/mcp.json registrations)",
+	}),
 	"clipboard-transport": Flags.string({
 		description: "Clipboard transport: auto (default), native, osc52, or ssh",
 		options: ["auto", "native", "osc52", "ssh"],

package/src/cli/setup-cli.ts

@@ -30,6 +30,14 @@ import {
 	runHermesSetup,
 } from "../setup/hermes-setup";
 import { buildHostPluginSetup, formatHostPluginSetup, type HostPluginKind } from "../setup/host-plugin-setup";
+import {
+	type PaseoSetupFlags,
+	type PaseoSetupOutcome,
+	PaseoSetupUsageError,
+	runPaseoSetup,
+} from "../setup/paseo/paseo-setup";
+import { checkExitCode } from "../setup/paseo/result-types";
+import { createDefaultPaseoSetupDependencies } from "../setup/paseo/setup-deps";
 import {
 	addApiCompatibleProvider,
 	formatProviderPresetList,
@@ -44,6 +52,7 @@ export type SetupComponent =
 	| "defaults"
 	| "hermes"
 	| "hooks"
+	| "paseo"
 	| "provider"
 	| "python"
 	| "stt";
@@ -67,6 +76,8 @@ export interface SetupCommandArgs {
 		repo?: string;
 		profile?: string;
 		sessionCommand?: string;
+		remove?: boolean;
+		mpreset?: string;
 		noWorktree?: boolean;
 		worktreeName?: string;
 		stateRoot?: string;
@@ -89,11 +100,31 @@ const VALID_COMPONENTS: SetupComponent[] = [
 	"defaults",
 	"hermes",
 	"hooks",
+	"paseo",
 	"provider",
 	"python",
 	"stt",
 ];
 
+/**
+ * Flags introduced by the `paseo` component.
+ *
+ * Deliberately narrow: `--check`, `--json`, and `--force` are pre-existing
+ * shared setup flags and are NOT relabeled here, so no other component's
+ * behavior changes.
+ */
+const PASEO_ONLY_FLAGS: readonly (keyof SetupCommandArgs["flags"])[] = ["remove", "mpreset"];
+
+function rejectPaseoFlagsOutsidePaseo(component: SetupComponent, flags: SetupCommandArgs["flags"]): void {
+	if (component === "paseo") return;
+	const offending = PASEO_ONLY_FLAGS.filter(flag => flags[flag] !== undefined);
+	if (offending.length === 0) return;
+	const flagList = offending.map(flag => `--${flag}`);
+	process.stderr.write(`${chalk.red(`${flagList.join(", ")} require the explicit \`paseo\` component.`)}\n`);
+	process.stderr.write(`${chalk.dim(`Run: ${APP_NAME} setup paseo ${flagList.join(" ")}`)}\n`);
+	process.exit(1);
+}
+
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
 		flags.compat !== undefined ||
@@ -194,6 +225,10 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.model = [...(flags.model ?? []), args[++i] ?? ""];
 		} else if (arg === "--models-path") {
 			flags.modelsPath = args[++i];
+		} else if (arg === "--remove") {
+			flags.remove = true;
+		} else if (arg === "--mpreset") {
+			flags.mpreset = args[++i];
 		} else if (!componentSeen && VALID_COMPONENTS.includes(arg as SetupComponent)) {
 			component = arg as SetupComponent;
 			componentSeen = true;
@@ -205,6 +240,7 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 	}
 
 	rejectProviderFlagsOutsideProvider(component, flags);
+	rejectPaseoFlagsOutsidePaseo(component, flags);
 
 	return {
 		component,
@@ -262,6 +298,7 @@ async function checkPythonSetup(): Promise<PythonCheckResult> {
  */
 export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 	rejectProviderFlagsOutsideProvider(cmd.component, cmd.flags);
+	rejectPaseoFlagsOutsidePaseo(cmd.component, cmd.flags);
 	switch (cmd.component) {
 		case "claude":
 			handleHostPluginSetup("claude", cmd.flags);
@@ -278,6 +315,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "hooks":
 			await handleHooksSetup(cmd.flags);
 			break;
+		case "paseo":
+			await handlePaseoSetup(cmd.flags);
+			break;
 		case "provider":
 			await handleProviderSetup(cmd.flags);
 			break;
@@ -382,6 +422,105 @@ async function handleProviderSetup(flags: {
 	}
 }
 
+/**
+ * Register GJC with Paseo, diagnose that registration, or roll it back.
+ *
+ * Every write target belongs to another application, so failures are reported
+ * rather than worked around: a refusal here means the user's files were left
+ * exactly as they were.
+ */
+async function handlePaseoSetup(flags: SetupCommandArgs["flags"]): Promise<void> {
+	const paseoFlags: PaseoSetupFlags = {
+		check: flags.check,
+		json: flags.json,
+		force: flags.force,
+		remove: flags.remove,
+		mpreset: flags.mpreset,
+	};
+	try {
+		const outcome = await runPaseoSetup(paseoFlags, createDefaultPaseoSetupDependencies());
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(outcome.result, null, 2)}\n`);
+			process.exitCode = paseoExitCode(outcome);
+			return;
+		}
+		writePaseoHumanOutput(outcome);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		} else {
+			process.stderr.write(`${chalk.red(`${theme.status.error} Paseo setup failed`)}\n`);
+			process.stderr.write(`${chalk.dim(message)}\n`);
+		}
+		process.exit(error instanceof PaseoSetupUsageError ? 2 : 1);
+	}
+}
+
+function paseoExitCode(outcome: PaseoSetupOutcome): number {
+	if (outcome.kind === "check") return checkExitCode(outcome.result);
+	if (outcome.kind === "install") return outcome.result.outcome === "installed" ? 0 : 1;
+	return outcome.result.outcome === "partial-removal" ? 1 : 0;
+}
+
+function writePaseoHumanOutput(outcome: PaseoSetupOutcome): void {
+	if (outcome.kind === "check") {
+		const result = outcome.result;
+		switch (result.status) {
+			case "drift":
+				process.stderr.write(`${chalk.red(`${theme.status.error} Paseo setup has drifted`)}\n`);
+				for (const reason of result.reasons) {
+					process.stderr.write(`${chalk.dim(`  ${reason.code}: ${reason.subject} -- ${reason.detail}`)}\n`);
+				}
+				process.exitCode = 1;
+				return;
+			case "stale":
+				process.stdout.write(`${chalk.yellow(`${theme.status.warning} Paseo has not picked up the change yet`)}\n`);
+				if (result.guidance) process.stdout.write(`${chalk.dim(result.guidance)}\n`);
+				return;
+			case "skipped":
+				process.stdout.write(`${chalk.green(`${theme.status.success} Paseo setup files are correct`)}\n`);
+				process.stdout.write(
+					`${chalk.dim("The Paseo daemon did not respond, so its live provider list was not verified.")}\n`,
+				);
+				return;
+			case "pass":
+				process.stdout.write(`${chalk.green(`${theme.status.success} GJC is registered with Paseo`)}\n`);
+				return;
+		}
+	}
+
+	if (outcome.kind === "install") {
+		if (outcome.result.outcome === "installed") {
+			process.stdout.write(`${chalk.green(`${theme.status.success} GJC registered with Paseo`)}\n`);
+			for (const entry of outcome.result.changed) process.stdout.write(`${chalk.dim(`  updated ${entry}`)}\n`);
+			process.stdout.write(
+				`${chalk.dim("Restart the Paseo daemon when convenient so it picks up the new provider.")}\n`,
+			);
+			return;
+		}
+		process.stderr.write(`${chalk.red(`${theme.status.error} Paseo setup did not complete`)}\n`);
+		process.stderr.write(`${chalk.dim(outcome.result.evidence.detail)}\n`);
+		process.exitCode = 1;
+		return;
+	}
+
+	switch (outcome.result.outcome) {
+		case "removed":
+			process.stdout.write(`${chalk.green(`${theme.status.success} GJC unregistered from Paseo`)}\n`);
+			for (const entry of outcome.result.removed) process.stdout.write(`${chalk.dim(`  reverted ${entry}`)}\n`);
+			return;
+		case "nothing-to-remove":
+			process.stdout.write(`${chalk.dim("GJC has nothing recorded to remove from Paseo.")}\n`);
+			return;
+		case "partial-removal":
+			process.stderr.write(`${chalk.red(`${theme.status.error} Paseo removal did not complete`)}\n`);
+			process.stderr.write(`${chalk.dim(outcome.result.evidence.detail)}\n`);
+			process.exitCode = 1;
+			return;
+	}
+}
+
 async function handleHooksSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
 	const hooksPath = getDefaultCodexHooksPath();
 	const existingContent = await Bun.file(hooksPath)
@@ -724,6 +863,7 @@ ${chalk.bold("Components:")}
   defaults  Install bundled GJC default workflow skills (default)
   hermes   Optional: render/install a Hermes MCP bridge setup package
   hooks     Optional: install GJC native Codex UserPromptSubmit/Stop skill-state hooks
+  paseo     Optional: register GJC as a Paseo ACP provider and bridge Paseo's skills
   provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
   stt       Optional: install speech-to-text dependencies (openai-whisper, recording tools)
@@ -770,6 +910,8 @@ ${chalk.bold("Options:")}
   --dry-run         Preview discovered credentials without importing (credentials)
   -y, --yes         Import discovered credentials without an interactive prompt (credentials)
   --keychain        Include Claude macOS Keychain when discovering credentials
+  --remove          Roll back the Paseo registration GJC created (paseo)
+  --mpreset         Register an additional gjc-<preset> Paseo provider (paseo)
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Install bundled GJC default workflow skills
@@ -785,5 +927,8 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup credentials      Discover & import existing Claude/Codex credentials
   ${APP_NAME} setup credentials --dry-run  Preview importable credentials (redacted)
   ${APP_NAME} setup credentials --yes      Import without an interactive prompt
+  ${APP_NAME} setup paseo            Register GJC as a Paseo ACP provider
+  ${APP_NAME} setup paseo --check    Diagnose the Paseo registration
+  ${APP_NAME} setup paseo --remove   Roll back the Paseo registration
 `);
 }