@gajae-code/coding-agent 0.4.2 → 0.4.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -50,12 +50,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.4.2",
-		"@gajae-code/agent-core": "0.4.2",
-		"@gajae-code/ai": "0.4.2",
-		"@gajae-code/natives": "0.4.2",
-		"@gajae-code/tui": "0.4.2",
-		"@gajae-code/utils": "0.4.2",
+		"@gajae-code/stats": "0.4.4",
+		"@gajae-code/agent-core": "0.4.4",
+		"@gajae-code/ai": "0.4.4",
+		"@gajae-code/natives": "0.4.4",
+		"@gajae-code/tui": "0.4.4",
+		"@gajae-code/utils": "0.4.4",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/async/job-manager.ts

@@ -1,11 +1,12 @@
 import { logger } from "@gajae-code/utils";
-import type { AgentSource } from "../task/types";
+import type { AgentProgress, AgentSource } from "../task/types";
 
 const DELIVERY_RETRY_BASE_MS = 500;
 const DELIVERY_RETRY_MAX_MS = 30_000;
 const DELIVERY_RETRY_JITTER_MS = 200;
 const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_RUNNING_JOBS = 15;
+const MONITOR_TOMBSTONE_TTL_MS = 5 * 60_000;
 
 export interface AsyncJob {
 	id: string;
@@ -120,6 +121,27 @@ export interface AsyncJobDeliveryState {
 	pendingJobIds: string[];
 }
 
+export interface AsyncJobLifecycleCleanup {
+	onCancel?: (job: AsyncJob) => void;
+	onTerminal?: (job: AsyncJob) => void;
+	onEvict?: (job: AsyncJob) => void;
+	/**
+	 * Idempotent residual cleanup invoked by a post-eviction tombstone purge
+	 * (e.g. a late `job cancel` after the job left the registry). Kept distinct
+	 * from the at-most-once lifecycle phases so a tombstone purge never has to
+	 * re-invoke a phase hook. Must be safe to call repeatedly.
+	 */
+	onTombstonePurge?: (job: AsyncJob) => void;
+}
+
+export interface MonitorTombstone {
+	jobId: string;
+	ownerId?: string;
+	status: AsyncJob["status"];
+	expiresAt: number;
+	purge: () => unknown;
+}
+
 export interface AsyncJobRegisterOptions {
 	id?: string;
 	/** Registry id of the agent that owns this job; used to scope cancelAll. */
@@ -127,6 +149,7 @@ export interface AsyncJobRegisterOptions {
 	/** Structured metadata for tool-specific control surfaces. */
 	metadata?: AsyncJobMetadata;
 	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+	lifecycle?: AsyncJobLifecycleCleanup;
 }
 
 /**
@@ -214,6 +237,9 @@ export class AsyncJobManager {
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
 	readonly #outputState = new Map<string, AsyncJobOutputState>();
 	readonly #ownerCleanups = new Map<string, Set<() => void>>();
+	readonly #lifecycles = new Map<string, AsyncJobLifecycleCleanup>();
+	readonly #lifecyclePhases = new Map<string, Set<"cancel" | "terminal" | "evict">>();
+	readonly #monitorTombstones = new Map<string, MonitorTombstone>();
 	readonly #outputRetentionBytes = DEFAULT_JOB_OUTPUT_RETENTION_BYTES;
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
@@ -222,6 +248,7 @@ export class AsyncJobManager {
 	#disposed = false;
 	readonly #subagentRecords = new Map<string, SubagentRecord>();
 	readonly #liveHandles = new Map<string, SubagentLiveHandle>();
+	readonly #subagentProgress = new Map<string, AgentProgress>();
 	readonly #resumeQueue: ResumeQueueEntry[] = [];
 	#resumeSeq = 0;
 	#resumeRunner?: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
@@ -292,6 +319,7 @@ export class AsyncJobManager {
 			);
 		}
 
+		this.#expireMonitorTombstones();
 		const id = this.#resolveJobId(options?.id);
 		this.#suppressedDeliveries.delete(id);
 		const abortController = new AbortController();
@@ -308,6 +336,7 @@ export class AsyncJobManager {
 			ownerId: options?.ownerId,
 			metadata: options?.metadata,
 		};
+		if (options?.lifecycle) this.#lifecycles.set(id, options.lifecycle);
 
 		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
 			if (!options?.onProgress) return;
@@ -325,8 +354,10 @@ export class AsyncJobManager {
 				const result = await run({ jobId: id, signal: abortController.signal, reportProgress });
 				const outcome: SubagentRunOutcome =
 					typeof result === "string" ? { kind: "completed", text: result } : result;
+
 				if (job.status === "cancelled") {
 					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
+					this.#runLifecycle(id, "terminal");
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
@@ -342,20 +373,24 @@ export class AsyncJobManager {
 					this.#drainResumeQueue();
 					return;
 				}
+
 				job.status = "completed";
 				job.resultText = outcome.text;
 				this.#enqueueDelivery(id, outcome.text);
+				this.#runLifecycle(id, "terminal");
 				this.#scheduleEviction(id);
 				this.#markRecordTerminal(id, "completed");
 				this.#drainResumeQueue();
 			} catch (error) {
 				if (job.status === "cancelled") {
 					job.errorText = error instanceof Error ? error.message : String(error);
+					this.#runLifecycle(id, "terminal");
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
 					return;
 				}
+				this.#runLifecycle(id, "terminal");
 				const errorText = error instanceof Error ? error.message : String(error);
 				job.status = "failed";
 				job.errorText = errorText;
@@ -381,6 +416,7 @@ export class AsyncJobManager {
 		if (!job) return false;
 		if (filter?.ownerId && job.ownerId !== filter.ownerId) return false;
 		if (job.status === "paused") {
+			this.#runLifecycle(id, "cancel");
 			// Paused jobs have no running promise to abort; transition directly.
 			// The session file is kept, so the record stays resumable by id.
 			job.status = "cancelled";
@@ -390,12 +426,76 @@ export class AsyncJobManager {
 			return true;
 		}
 		if (job.status !== "running") return false;
+		this.#runLifecycle(id, "cancel");
 		job.status = "cancelled";
 		job.abortController.abort();
-		this.#scheduleEviction(id);
 		return true;
 	}
 
+	#runLifecycle(jobId: string, phase: "cancel" | "terminal" | "evict"): void {
+		const fired = this.#lifecyclePhases.get(jobId) ?? new Set<"cancel" | "terminal" | "evict">();
+		if (fired.has(phase)) return;
+		fired.add(phase);
+		this.#lifecyclePhases.set(jobId, fired);
+		const lifecycle = this.#lifecycles.get(jobId);
+		const job = this.#jobs.get(jobId);
+		if (!lifecycle || !job) return;
+		try {
+			if (phase === "cancel") lifecycle.onCancel?.(job);
+			else if (phase === "terminal") lifecycle.onTerminal?.(job);
+			else lifecycle.onEvict?.(job);
+		} catch (error) {
+			logger.warn("Async job lifecycle cleanup failed", {
+				jobId,
+				phase,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	#expireMonitorTombstones(): void {
+		const now = Date.now();
+		for (const [jobId, tombstone] of this.#monitorTombstones) {
+			if (tombstone.expiresAt <= now) this.#monitorTombstones.delete(jobId);
+		}
+	}
+
+	#recordMonitorTombstone(jobId: string): void {
+		const job = this.#jobs.get(jobId);
+		if (!job?.metadata?.monitor) return;
+		const lifecycle = this.#lifecycles.get(jobId);
+		this.#monitorTombstones.set(jobId, {
+			jobId,
+			ownerId: job.ownerId,
+			status: job.status,
+			expiresAt: Date.now() + MONITOR_TOMBSTONE_TTL_MS,
+			purge: () => (lifecycle?.onTombstonePurge ?? lifecycle?.onEvict)?.(job),
+		});
+	}
+
+	getMonitorTombstone(jobId: string, filter?: AsyncJobFilter): MonitorTombstone | undefined {
+		this.#expireMonitorTombstones();
+		const tombstone = this.#monitorTombstones.get(jobId);
+		if (!tombstone) return undefined;
+		if (filter?.ownerId && tombstone.ownerId !== filter.ownerId) return undefined;
+		return tombstone;
+	}
+
+	purgeMonitorTombstone(jobId: string, filter?: AsyncJobFilter): { found: boolean; status?: AsyncJob["status"] } {
+		const tombstone = this.getMonitorTombstone(jobId, filter);
+		if (!tombstone) return { found: false };
+		this.#monitorTombstones.delete(jobId);
+		try {
+			tombstone.purge();
+		} catch (error) {
+			logger.warn("Monitor tombstone purge failed", {
+				jobId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		return { found: true, status: tombstone.status };
+	}
+
 	// ── Subagent control plane (pause / resume / steer support) ──────────
 
 	/** Register or replace the canonical record for a subagent. */
@@ -432,6 +532,38 @@ export class AsyncJobManager {
 		this.#liveHandles.delete(subagentId);
 	}
 
+	/**
+	 * Retain the latest live `AgentProgress` for a subagent (deep-cloned so later
+	 * mutation of the live object cannot corrupt retained state). Read by the
+	 * `subagent` await panel; cleared on terminal/cancel/purge/dispose.
+	 *
+	 * Ignored for ids without a canonical `SubagentRecord` (e.g. foreground/inline
+	 * task runs that share the executor path) so the map only holds detached
+	 * subagent progress and never accumulates untracked foreground task state.
+	 */
+	recordSubagentProgress(subagentId: string, progress: AgentProgress): void {
+		if (!this.#subagentRecords.has(subagentId)) return;
+		this.#subagentProgress.set(subagentId, structuredClone(progress));
+	}
+
+	getSubagentProgress(subagentId: string): AgentProgress | undefined {
+		return this.#subagentProgress.get(subagentId);
+	}
+
+	/**
+	 * True only when a live, in-session progress producer exists for this id: a
+	 * canonical registered record with a live handle or an in-memory running job.
+	 * False for `SubagentTool` backward-compat job synthesis and resumed-from-disk
+	 * records, which have no live producer to stream from.
+	 */
+	hasLiveSubagent(subagentId: string, filter?: AsyncJobFilter): boolean {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return false;
+		if (this.#liveHandles.has(rec.subagentId)) return true;
+		const job = rec.currentJobId ? this.#jobs.get(rec.currentJobId) : undefined;
+		return job?.status === "running";
+	}
+
 	/** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
 	setResumeRunner(
 		runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined,
@@ -462,6 +594,7 @@ export class AsyncJobManager {
 		if (rec) {
 			rec.status = "paused";
 			this.#liveHandles.delete(rec.subagentId);
+			this.#subagentProgress.delete(rec.subagentId);
 		}
 	}
 
@@ -470,6 +603,7 @@ export class AsyncJobManager {
 		if (!rec) return;
 		rec.status = status;
 		this.#liveHandles.delete(rec.subagentId);
+		this.#subagentProgress.delete(rec.subagentId);
 	}
 
 	/** Request a graceful safe-boundary pause of a running subagent. */
@@ -527,6 +661,9 @@ export class AsyncJobManager {
 		message?: string,
 	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; reason?: string } {
 		const prevJobId = rec.currentJobId;
+		// Clear any retained progress from the previous run so a resumed subagent
+		// never renders the prior run's tool/output as live before it emits again.
+		this.#subagentProgress.delete(rec.subagentId);
 		const newJobId = this.#resumeRunner?.(rec.subagentId, message, this.#resumeDescriptors.get(rec.subagentId));
 		if (!newJobId) return { ok: false, reason: "resume_failed" };
 		if (prevJobId && prevJobId !== newJobId) rec.historicalJobIds.push(prevJobId);
@@ -564,6 +701,7 @@ export class AsyncJobManager {
 			}
 			rec.status = "cancelled";
 			this.#liveHandles.delete(rec.subagentId);
+			this.#subagentProgress.delete(rec.subagentId);
 			this.#drainResumeQueue();
 			return true;
 		}
@@ -572,6 +710,7 @@ export class AsyncJobManager {
 			if (idx !== -1) this.#resumeQueue.splice(idx, 1);
 			rec.status = "cancelled";
 			rec.queued = undefined;
+			this.#subagentProgress.delete(rec.subagentId);
 			return true;
 		}
 		return false;
@@ -586,6 +725,7 @@ export class AsyncJobManager {
 				this.#liveHandles.delete(sid);
 				this.#resumeDescriptors.delete(sid);
 				this.#subagentRecords.delete(sid);
+				this.#subagentProgress.delete(sid);
 			}
 		}
 	}
@@ -836,6 +976,7 @@ export class AsyncJobManager {
 	 */
 	cancelAll(filter?: AsyncJobFilter): void {
 		for (const job of this.getRunningJobs(filter)) {
+			this.#runLifecycle(job.id, "cancel");
 			job.status = "cancelled";
 			job.abortController.abort();
 			this.#scheduleEviction(job.id);
@@ -898,6 +1039,17 @@ export class AsyncJobManager {
 		// manager. Errors in cleanup callbacks are logged but never escalated.
 		this.runOwnerCleanups();
 		this.cancelAll();
+		for (const tombstone of this.#monitorTombstones.values()) {
+			try {
+				tombstone.purge();
+			} catch (error) {
+				logger.warn("Monitor tombstone purge failed during dispose", {
+					jobId: tombstone.jobId,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		this.#monitorTombstones.clear();
 		await this.waitForAll();
 		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
 		this.#clearEvictionTimers();
@@ -910,6 +1062,7 @@ export class AsyncJobManager {
 		this.#ownerCleanups.clear();
 		this.#subagentRecords.clear();
 		this.#liveHandles.clear();
+		this.#subagentProgress.clear();
 		this.#resumeDescriptors.clear();
 		this.#resumeQueue.length = 0;
 		this.#notifyChange();
@@ -945,7 +1098,11 @@ export class AsyncJobManager {
 	#scheduleEviction(jobId: string): void {
 		this.#notifyChange();
 		if (this.#retentionMs <= 0) {
+			this.#recordMonitorTombstone(jobId);
+			this.#runLifecycle(jobId, "evict");
 			this.#jobs.delete(jobId);
+			this.#lifecycles.delete(jobId);
+			this.#lifecyclePhases.delete(jobId);
 			this.#suppressedDeliveries.delete(jobId);
 			this.#watchedJobs.delete(jobId);
 			this.#outputState.delete(jobId);
@@ -957,7 +1114,11 @@ export class AsyncJobManager {
 		}
 		const timer = setTimeout(() => {
 			this.#evictionTimers.delete(jobId);
+			this.#recordMonitorTombstone(jobId);
+			this.#runLifecycle(jobId, "evict");
 			this.#jobs.delete(jobId);
+			this.#lifecycles.delete(jobId);
+			this.#lifecyclePhases.delete(jobId);
 			this.#suppressedDeliveries.delete(jobId);
 			this.#watchedJobs.delete(jobId);
 			this.#outputState.delete(jobId);

package/src/cli/setup-cli.ts

@@ -14,6 +14,12 @@ import {
 	readGjcManagedCodexHooksStatus,
 } from "../hooks/codex-native-hooks-config";
 import { theme } from "../modes/theme/theme";
+import {
+	formatHermesSetupResult,
+	type HermesSetupFlags,
+	hermesSetupExitCode,
+	runHermesSetup,
+} from "../setup/hermes-setup";
 import {
 	addApiCompatibleProvider,
 	formatProviderPresetList,
@@ -21,7 +27,7 @@ import {
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
 
-export type SetupComponent = "defaults" | "hooks" | "provider" | "python" | "stt";
+export type SetupComponent = "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
 
 export interface SetupCommandArgs {
 	component: SetupComponent;
@@ -36,10 +42,23 @@ export interface SetupCommandArgs {
 		apiKeyEnv?: string;
 		model?: string[];
 		modelsPath?: string;
+		smoke?: boolean;
+		install?: boolean;
+		root?: string[];
+		repo?: string;
+		profile?: string;
+		sessionCommand?: string;
+		stateRoot?: string;
+		mutation?: string[];
+		artifactByteCap?: string;
+		serverKey?: string;
+		gjcCommand?: string;
+		target?: string;
+		profileDir?: string;
 	};
 }
 
-const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "python", "stt"];
+const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
@@ -88,6 +107,32 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.check = true;
 		} else if (arg === "--force" || arg === "-f") {
 			flags.force = true;
+		} else if (arg === "--smoke") {
+			flags.smoke = true;
+		} else if (arg === "--install") {
+			flags.install = true;
+		} else if (arg === "--root") {
+			flags.root = [...(flags.root ?? []), args[++i] ?? ""];
+		} else if (arg === "--repo") {
+			flags.repo = args[++i];
+		} else if (arg === "--profile") {
+			flags.profile = args[++i];
+		} else if (arg === "--session-command") {
+			flags.sessionCommand = args[++i];
+		} else if (arg === "--state-root") {
+			flags.stateRoot = args[++i];
+		} else if (arg === "--mutation") {
+			flags.mutation = [...(flags.mutation ?? []), args[++i] ?? ""];
+		} else if (arg === "--artifact-byte-cap") {
+			flags.artifactByteCap = args[++i];
+		} else if (arg === "--server-key") {
+			flags.serverKey = args[++i];
+		} else if (arg === "--gjc-command") {
+			flags.gjcCommand = args[++i];
+		} else if (arg === "--target") {
+			flags.target = args[++i];
+		} else if (arg === "--profile-dir") {
+			flags.profileDir = args[++i];
 		} else if (arg === "--compat") {
 			flags.compat = args[++i];
 		} else if (arg === "--preset") {
@@ -177,6 +222,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "defaults":
 			await handleDefaultsSetup(cmd.flags);
 			break;
+		case "hermes":
+			await handleHermesSetup(cmd.flags);
+			break;
 		case "hooks":
 			await handleHooksSetup(cmd.flags);
 			break;
@@ -192,6 +240,26 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 	}
 }
 
+async function handleHermesSetup(flags: HermesSetupFlags): Promise<void> {
+	try {
+		const result = await runHermesSetup(flags);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(`${chalk.green(`${theme.status.success} Hermes MCP setup ready`)}\n`);
+		process.stdout.write(`${chalk.dim(formatHermesSetupResult(result))}\n`);
+	} 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} Hermes MCP setup failed`)}\n`);
+			process.stderr.write(`${chalk.dim(message)}\n`);
+		}
+		process.exit(hermesSetupExitCode(error));
+	}
+}
 async function handleProviderSetup(flags: {
 	json?: boolean;
 	force?: boolean;
@@ -410,6 +478,7 @@ ${chalk.bold("Usage:")}
 
 ${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
   provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
@@ -421,6 +490,11 @@ ${chalk.bold("Provider example:")}
   ${APP_NAME} setup provider --preset glm
   MY_PROVIDER_KEY=sk-... ${APP_NAME} setup provider --compat openai --provider my-oai --base-url https://api.example.com/v1 --api-key-env MY_PROVIDER_KEY --model gpt-example
 
+${chalk.bold("Hermes example:")}
+  ${APP_NAME} setup hermes --root /path/to/repo
+  ${APP_NAME} setup hermes --root /path/to/repo --profile my-bot --repo gajae-code --profile-dir /path/to/hermes/profile --install
+  ${APP_NAME} setup hermes --root /path/to/repo --session-command "gjc --model <provider/model>"
+
 ${chalk.bold("Options:")}
   -c, --check       Check if dependencies are installed without installing
   -f, --force       Overwrite existing default workflow skill files
@@ -432,6 +506,15 @@ ${chalk.bold("Options:")}
   --api-key-env     Read provider API key from this environment variable
   --model, --models Model id to add (repeat or comma-separate)
   --models-path     Override models config path
+  --smoke           Run Hermes MCP setup smoke checks
+  --install         Install generated Hermes setup files
+  --root            Allowed Hermes MCP workdir/artifact root (repeatable)
+  --profile         Hermes MCP profile namespace
+  --repo            Hermes MCP repo namespace
+  --session-command Explicit GJC session command; omitted by default
+  --mutation        Hermes MCP mutation classes: sessions,questions,reports,all
+  --target          Hermes config file target for config-only install
+  --profile-dir     Hermes profile directory for full setup install
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Install bundled GJC default workflow skills
@@ -439,6 +522,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup defaults --check Check bundled GJC default workflow skills are installed
   ${APP_NAME} setup hooks            Install native Codex skill-state hooks
   ${APP_NAME} setup hooks --check    Check native Codex skill-state hooks
+  ${APP_NAME} setup hermes           Render a model-agnostic Hermes MCP setup preview
   ${APP_NAME} setup python           Install Python execution dependencies
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available

package/src/cli.ts

@@ -36,10 +36,12 @@ const commands: CommandEntry[] = [
 	{ name: "skills", load: () => import("./commands/skills").then(m => m.default) },
 	{ name: "session", load: () => import("./commands/session").then(m => m.default) },
 	{ name: "harness", load: () => import("./commands/harness").then(m => m.default) },
+	{ name: "coordinator", load: () => import("./commands/coordinator").then(m => m.default) },
 	{ name: "team", load: () => import("./commands/team").then(m => m.default) },
 	{ name: "ultragoal", load: () => import("./commands/ultragoal").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{
 		name: "contribute-pr",
 		aliases: ["contribution-prep"],

package/src/commands/coordinator.ts

@@ -0,0 +1,70 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+
+function coordinatorContractPayload(): {
+	ok: true;
+	server: { name: string; protocolVersion: string };
+	readOnly: true;
+	tools: string[];
+} {
+	return {
+		ok: true,
+		server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+		readOnly: true,
+		tools: [...COORDINATOR_MCP_TOOL_NAMES],
+	};
+}
+
+export default class Coordinator extends Command {
+	static description = "Inspect GJC coordinator MCP bridge contracts";
+	static strict = false;
+
+	static args = {
+		action: Args.string({ description: "Action to run (check or tools)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Coordinator);
+		const action = args.action ?? "check";
+		if (action !== "check" && action !== "tools") {
+			const payload = { ok: false, reason: "unknown_coordinator_subcommand", subcommand: action };
+			if (flags.json) writeJson(payload);
+			else
+				process.stderr.write(`unknown_coordinator_subcommand:${action}
+`);
+			process.exit(1);
+		}
+
+		const payload = coordinatorContractPayload();
+		if (flags.json) {
+			writeJson(action === "tools" ? { ok: true, tools: payload.tools } : payload);
+			return;
+		}
+		if (action === "tools") {
+			for (const tool of payload.tools)
+				process.stdout.write(`${tool}
+`);
+			return;
+		}
+		process.stdout.write(
+			`server: ${payload.server.name}
+protocol: ${payload.server.protocolVersion}
+readOnly: true
+tools: ${payload.tools.length}
+`,
+		);
+	}
+}

package/src/commands/mcp-serve.ts

@@ -0,0 +1,62 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function validateMcpServeSubcommandForTest(server: string | undefined): void {
+	if (server !== "coordinator") throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
+}
+
+export default class McpServe extends Command {
+	static description = "Serve GJC MCP compatibility bridges";
+	static strict = false;
+
+	static args = {
+		server: Args.string({ description: "MCP server to run (coordinator)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+		check: Flags.boolean({ description: "Validate server configuration and print a smoke summary", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(McpServe);
+		const server = args.server ?? "";
+		try {
+			validateMcpServeSubcommandForTest(server);
+		} catch (error) {
+			const subcommand = server;
+			if (flags.json) {
+				writeJson({ ok: false, reason: "unknown_mcp_serve_subcommand", subcommand });
+			} else {
+				process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			}
+			return;
+		}
+
+		if (flags.check) {
+			const payload = {
+				ok: true,
+				server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+				readOnly: true,
+				tools: [...COORDINATOR_MCP_TOOL_NAMES],
+			};
+			if (flags.json) writeJson(payload);
+			else
+				process.stdout.write(
+					`server: ${payload.server.name}\nprotocol: ${payload.server.protocolVersion}\ntools: ${payload.tools.length}\n`,
+				);
+			return;
+		}
+
+		await runCoordinatorMcpStdio();
+	}
+}