@gajae-code/coding-agent 0.6.4 → 0.7.0

package/src/session/session-dump-format.ts

@@ -47,13 +47,54 @@ function stripTypeBoxFields(obj: unknown): unknown {
 	return obj;
 }
 
+function escapeXmlAttribute(input: string): string {
+	return input.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeXmlText(input: string): string {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function decodeCodePoint(hex: string): string {
+	const codePoint = Number.parseInt(hex, 16);
+	if (
+		!Number.isFinite(codePoint) ||
+		codePoint < 0x20 ||
+		(codePoint >= 0x7f && codePoint <= 0x9f) ||
+		(codePoint >= 0xd800 && codePoint <= 0xdfff)
+	) {
+		return `\\u${hex}`;
+	}
+	return String.fromCharCode(codePoint);
+}
+
+function decodeUnicodeEscapeText(input: string): string {
+	return input
+		.replace(/\\\\u([0-9a-fA-F]{4})/g, (_match, hex: string) => decodeCodePoint(hex))
+		.replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex: string) => decodeCodePoint(hex));
+}
+
+function formatParameterValue(value: unknown): string {
+	const raw = typeof value === "string" ? value : (JSON.stringify(value, null, "\t") ?? "null");
+	return escapeXmlText(decodeUnicodeEscapeText(raw));
+}
+
 /** Serialize an object as XML parameter elements, one per key. */
 function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
 	const parts: string[] = [];
 	for (const [key, value] of Object.entries(args)) {
 		if (key === INTENT_FIELD) continue;
-		const text = typeof value === "string" ? value : JSON.stringify(value);
-		parts.push(`${indent}<parameter name="${key}">${text}</parameter>`);
+		const escapedKey = escapeXmlAttribute(key);
+		const text = formatParameterValue(value);
+		if (text.includes("\n")) {
+			const indentedText = text
+				.split("\n")
+				.map(line => `${indent}\t${line}`)
+				.join("\n");
+			parts.push(`${indent}<parameter name="${escapedKey}">\n${indentedText}\n${indent}</parameter>`);
+		} else {
+			parts.push(`${indent}<parameter name="${escapedKey}">${text}</parameter>`);
+		}
 	}
 	return parts.join("\n");
 }

package/src/session/session-manager.ts

@@ -28,6 +28,7 @@ import {
 	toError,
 } from "@gajae-code/utils";
 import { writeTextAtomic } from "../gjc-runtime/state-writer";
+import * as git from "../utils/git";
 import { ArtifactManager } from "./artifacts";
 import {
 	type BlobPutResult,
@@ -791,6 +792,25 @@ function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
 	write.catch(() => {});
 }
 
+/**
+ * Two paths belong to linked worktrees of the same repository when they share a
+ * git common dir but resolve to different git dirs (i.e. one is a `git worktree`
+ * of the other). `--worktree` sessions run from such a linked worktree, so a
+ * `--continue` from the main checkout should still resolve their breadcrumb.
+ */
+function isLinkedWorktreePeer(a: string, b: string): boolean {
+	const ra = git.repo.resolveSync(a);
+	const rb = git.repo.resolveSync(b);
+	if (ra === null || rb === null) return false;
+	// Canonicalize: a worktree's commondir is stored as an absolute path that may
+	// differ from the main checkout only by a symlink prefix (e.g. macOS
+	// /tmp -> /private/tmp), so compare resolved-equivalent paths.
+	return (
+		resolveEquivalentPath(ra.commonDir) === resolveEquivalentPath(rb.commonDir) &&
+		resolveEquivalentPath(ra.gitDir) !== resolveEquivalentPath(rb.gitDir)
+	);
+}
+
 /**
  * Read the terminal breadcrumb for the current terminal, scoped to a cwd.
  * Returns the session file path if it exists and matches the cwd, null otherwise.
@@ -808,8 +828,12 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 		const breadcrumbCwd = lines[0];
 		const sessionFile = lines[1];
 
-		// Only return if cwd matches (user might have cd'd)
-		if (path.resolve(breadcrumbCwd) !== path.resolve(cwd)) return null;
+		// Honor the breadcrumb when the cwd matches, or when it points to a linked
+		// worktree of the same repository (e.g. a `--worktree` session resumed from
+		// the main checkout). A genuinely different project is still ignored.
+		if (path.resolve(breadcrumbCwd) !== path.resolve(cwd) && !isLinkedWorktreePeer(breadcrumbCwd, cwd)) {
+			return null;
+		}
 
 		// Verify the session file still exists
 		const stat = fs.statSync(sessionFile, { throwIfNoEntry: false });
@@ -4010,12 +4034,22 @@ export class SessionManager {
 		// Prefer terminal-scoped breadcrumb (handles concurrent sessions correctly)
 		const terminalSession = await readTerminalBreadcrumb(cwd);
 		const mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
-		const manager = new SessionManager(cwd, dir, true, storage);
 		if (mostRecent) {
+			// Adopt the resumed session's recorded cwd and its own directory. A
+			// `--worktree` session lives in a linked worktree whose path differs from
+			// the invocation cwd; binding the manager (and HUD) to `cwd` would leave
+			// it on the main checkout instead of the worktree it was created in.
+			const header = (await loadEntriesFromFile(mostRecent, storage)).find(e => e.type === "session") as
+				| SessionHeader
+				| undefined;
+			const resumeCwd = header?.cwd || cwd;
+			const resumeDir = sessionDir ?? path.resolve(mostRecent, "..");
+			const manager = new SessionManager(resumeCwd, resumeDir, true, storage);
 			await manager.#initSessionFile(mostRecent);
-		} else {
-			manager.#initNewSession();
+			return manager;
 		}
+		const manager = new SessionManager(cwd, dir, true, storage);
+		manager.#initNewSession();
 		return manager;
 	}
 

package/src/setup/credential-auto-import.ts

@@ -0,0 +1,258 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {
+	AuthCredential,
+	AuthCredentialIfAbsentReason,
+	AuthCredentialIfAbsentSnapshotResult,
+	AuthStorage,
+} from "@gajae-code/ai";
+import { getAgentDir, logger, VERSION } from "@gajae-code/utils";
+import type { ModelRegistry } from "../config/model-registry";
+
+import {
+	type CredentialDiscoveryResult,
+	type CredentialOrigin,
+	type DiscoveryOptions,
+	discoverExternalCredentials,
+	EXTERNAL_PROVIDER_LABELS,
+	type ExternalProvider,
+	filterAutoImportOAuthCredentials,
+	formatCredentialSummary,
+	type ImportableCredential,
+} from "./credential-import";
+
+export const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING =
+	"Refreshing in gjc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+
+export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+
+const CREDENTIAL_AUTO_IMPORT_STATE_FILENAME = "credential-auto-import-state.json";
+
+interface CredentialAutoImportStateFile {
+	lastImportVersion?: unknown;
+}
+
+export function getCredentialAutoImportStatePath(agentDir: string = getAgentDir()): string {
+	return path.join(agentDir, CREDENTIAL_AUTO_IMPORT_STATE_FILENAME);
+}
+
+export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+	try {
+		const raw = await fs.readFile(getCredentialAutoImportStatePath(agentDir), "utf-8");
+		const parsed = JSON.parse(raw) as CredentialAutoImportStateFile;
+		return typeof parsed.lastImportVersion === "string" ? parsed.lastImportVersion : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+	try {
+		const statePath = getCredentialAutoImportStatePath(agentDir);
+		await fs.mkdir(path.dirname(statePath), { recursive: true });
+		await fs.writeFile(statePath, `${JSON.stringify({ lastImportVersion: version })}\n`);
+		return true;
+	} catch (error: unknown) {
+		logger.warn("Failed to persist credential auto-import state", { error });
+		return false;
+	}
+}
+
+export enum CredentialAutoImportFailureClass {
+	DiscoveryUnavailable = "discovery-unavailable",
+	SourceUnreadable = "source-unreadable",
+	SourceMalformed = "source-malformed",
+	KeychainDenied = "keychain-denied",
+	WriteInvalid = "write-invalid",
+	WriteConflict = "write-conflict",
+	BrokerUnavailable = "broker-unavailable",
+	BrokerUnsupported = "broker-unsupported",
+	Unknown = "unknown",
+}
+
+export interface CredentialAutoImportSkipped {
+	credential: ImportableCredential;
+	reason: AuthCredentialIfAbsentReason;
+	entries: AuthCredentialIfAbsentSnapshotResult["entries"];
+}
+
+export interface CredentialAutoImportFailure {
+	credential?: ImportableCredential;
+	origin?: CredentialOrigin;
+	source?: string;
+	failureClass: CredentialAutoImportFailureClass;
+}
+
+export interface CredentialAutoImportResult {
+	imported: ImportableCredential[];
+	skipped: CredentialAutoImportSkipped[];
+	failures: CredentialAutoImportFailure[];
+	discovered: boolean;
+	discovery?: CredentialDiscoveryResult;
+	globalDiscoveryFailure?: CredentialAutoImportFailure;
+}
+
+export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
+
+export interface CredentialAutoImportOptions {
+	authStorage: CredentialAutoImportAuthStorage;
+	discover?: (options?: DiscoveryOptions) => Promise<CredentialDiscoveryResult>;
+	discoveryOptions?: DiscoveryOptions;
+	trigger: CredentialAutoImportTrigger;
+	sourceLabel?: CredentialAutoImportSourceLabel;
+}
+
+function classifyDiscoverySkip(reason: string, origin: CredentialOrigin): CredentialAutoImportFailureClass {
+	const lower = reason.toLowerCase();
+	if (
+		origin === "claude-code-keychain" &&
+		(lower.includes("eacces") || lower.includes("eperm") || lower.includes("denied"))
+	) {
+		return CredentialAutoImportFailureClass.KeychainDenied;
+	}
+	if (lower.includes("malformed")) return CredentialAutoImportFailureClass.SourceMalformed;
+	if (lower.includes("unreadable")) return CredentialAutoImportFailureClass.SourceUnreadable;
+	return CredentialAutoImportFailureClass.Unknown;
+}
+
+function classifyWriteFailure(error: unknown): CredentialAutoImportFailureClass {
+	const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+	if (message.includes("invalid")) return CredentialAutoImportFailureClass.WriteInvalid;
+	if (message.includes("conflict") || message.includes("constraint"))
+		return CredentialAutoImportFailureClass.WriteConflict;
+	if (
+		message.includes("broker") &&
+		(message.includes("unsupported") || message.includes("404") || message.includes("501"))
+	) {
+		return CredentialAutoImportFailureClass.BrokerUnsupported;
+	}
+	if (message.includes("broker") || message.includes("fetch") || message.includes("network")) {
+		return CredentialAutoImportFailureClass.BrokerUnavailable;
+	}
+	return CredentialAutoImportFailureClass.Unknown;
+}
+
+export async function runExternalCredentialAutoImport({
+	authStorage,
+	discover = discoverExternalCredentials,
+	discoveryOptions,
+}: CredentialAutoImportOptions): Promise<CredentialAutoImportResult> {
+	let discovery: CredentialDiscoveryResult;
+	try {
+		discovery = await discover(discoveryOptions);
+	} catch {
+		const globalDiscoveryFailure = { failureClass: CredentialAutoImportFailureClass.DiscoveryUnavailable };
+		return {
+			imported: [],
+			skipped: [],
+			failures: [globalDiscoveryFailure],
+			discovered: false,
+			globalDiscoveryFailure,
+		};
+	}
+
+	const candidates = filterAutoImportOAuthCredentials(discovery.importable);
+	const failures: CredentialAutoImportFailure[] = discovery.skipped.map(skip => ({
+		origin: skip.origin,
+		source: skip.source,
+		failureClass: classifyDiscoverySkip(skip.reason, skip.origin),
+	}));
+	const imported: ImportableCredential[] = [];
+	const skipped: CredentialAutoImportSkipped[] = [];
+	const importIfAbsent = authStorage.importCredentialIfAbsent;
+
+	for (const credential of candidates) {
+		try {
+			const outcome = await importIfAbsent.call(
+				authStorage,
+				credential.provider,
+				credential.credential as AuthCredential,
+			);
+			if (outcome.inserted === true) {
+				imported.push(credential);
+			} else {
+				skipped.push({ credential, reason: outcome.reason, entries: outcome.entries });
+			}
+		} catch (error) {
+			failures.push({ credential, failureClass: classifyWriteFailure(error) });
+		}
+	}
+
+	return { imported, skipped, failures, discovered: true, discovery };
+}
+
+export function buildCredentialAutoImportNotice(
+	result: Pick<CredentialAutoImportResult, "imported">,
+): string | undefined {
+	if (result.imported.length === 0) return undefined;
+	const providers = [
+		...new Set(result.imported.map(c => EXTERNAL_PROVIDER_LABELS[c.provider as ExternalProvider] ?? c.provider)),
+	];
+	const success = `Imported ${result.imported.length} external OAuth credential(s) into gjc: ${providers.join(", ")}.`;
+	return `${success}\n${CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING}`;
+}
+
+export function formatCredentialAutoImportResult(result: CredentialAutoImportResult): string[] {
+	const lines: string[] = [];
+	for (const credential of result.imported) lines.push(`imported ${formatCredentialSummary(credential)}`);
+	for (const skip of result.skipped) lines.push(`skipped ${skip.credential.source}: ${skip.reason}`);
+	for (const failure of result.failures) {
+		const label = failure.credential?.source ?? failure.source ?? "external credential discovery";
+		lines.push(`failed ${label}: ${failure.failureClass}`);
+	}
+	return lines;
+}
+
+export interface CredentialImportMarkerStore {
+	read: () => Promise<string | undefined> | string | undefined;
+	write: (version: string) => Promise<boolean> | boolean;
+}
+
+export interface StartupCredentialAutoImportOptions {
+	authStorage: CredentialAutoImportOptions["authStorage"];
+	modelRegistry: Pick<ModelRegistry, "refresh">;
+	discover?: CredentialAutoImportOptions["discover"];
+	version?: string;
+	agentDir?: string;
+	markerStore?: CredentialImportMarkerStore;
+}
+
+export async function runStartupCredentialAutoImportIfNeeded({
+	authStorage: activeAuthStorage,
+	modelRegistry: activeModelRegistry,
+	discover,
+	version = VERSION,
+	agentDir,
+	markerStore,
+}: StartupCredentialAutoImportOptions): Promise<string | undefined> {
+	const store = markerStore ?? {
+		read: () => readCredentialImportMarker(agentDir),
+		write: (nextVersion: string) => writeCredentialImportMarker(nextVersion, agentDir),
+	};
+	const lastVersion = await store.read();
+	if (lastVersion === version) {
+		// Steady state: user already completed this version's auto-import gate. Skip all file/Keychain reads.
+		return undefined;
+	}
+
+	const result = await runExternalCredentialAutoImport({
+		authStorage: activeAuthStorage,
+		discover,
+		trigger: "startup",
+	});
+	if (!result.discovered) {
+		return undefined;
+	}
+
+	const candidates = filterAutoImportOAuthCredentials(result.discovery?.importable ?? []);
+	if (candidates.length > 0 && result.imported.length === 0 && result.skipped.length === 0) {
+		return undefined;
+	}
+	await store.write(version);
+
+	if (result.imported.length > 0) {
+		await activeModelRegistry.refresh("offline");
+	}
+	return buildCredentialAutoImportNotice(result);
+}

package/src/setup/credential-import.ts

@@ -25,6 +25,11 @@ export type ExternalProvider = "anthropic" | "openai-codex";
 /** Where a discovered credential came from. */
 export type CredentialOrigin = "claude-code-file" | "claude-code-keychain" | "codex-file";
 
+export const AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS: Record<ExternalProvider, ReadonlySet<CredentialOrigin>> = {
+	anthropic: new Set<CredentialOrigin>(["claude-code-file", "claude-code-keychain"]),
+	"openai-codex": new Set<CredentialOrigin>(["codex-file"]),
+};
+
 /** Human labels for providers, used in redacted summaries. */
 export const EXTERNAL_PROVIDER_LABELS: Record<ExternalProvider, string> = {
 	anthropic: "Claude (Anthropic)",
@@ -408,6 +413,18 @@ export function formatDiscoverySummary(result: CredentialDiscoveryResult): strin
 	return lines;
 }
 
+export function isAutoImportOAuthCredential(credential: ImportableCredential): boolean {
+	return (
+		AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS[credential.provider]?.has(credential.origin) === true &&
+		credential.kind === "oauth" &&
+		credential.credential.type === "oauth"
+	);
+}
+
+export function filterAutoImportOAuthCredentials(credentials: readonly ImportableCredential[]): ImportableCredential[] {
+	return credentials.filter(isAutoImportOAuthCredential);
+}
+
 /**
  * Persist discovered credentials via `upsert`. Each credential is imported
  * independently; a failure on one is recorded without aborting the rest.

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -15,6 +15,16 @@ These instructions teach a Hermes-style coordinator how to operate GJC through t
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
 7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
 
+## Prefer high-level delegation
+
+When the goal is to hand GJC a whole workflow rather than micro-manage one prompt, prefer the first-class delegate tools over manual `{{TOOL_PREFIX}}_start_session` + `{{TOOL_PREFIX}}_send_prompt` sequencing:
+
+- `gjc_delegate_plan` — run consensus planning (`/skill:ralplan`) to a pending-approval plan.
+- `gjc_delegate_execute` — run execution (`/skill:ultragoal`) to completion with verification.
+- `gjc_delegate_team` — run parallel team execution (`/skill:team`) with internal tmux workers.
+
+Each delegate starts (or reuses) a session, sends one workflow-tagged turn, and returns a durable `turn_id`. Pass `cwd` and `task`; set `allow_mutation: true` only when the bridge startup mutation class is enabled and the user has approved changes. Poll the returned `turn_id` with `{{TOOL_PREFIX}}_await_turn` or watch for the `delegation.started` event, exactly as with `send_prompt`. Drop to the manual start/send tools only for fine-grained control the delegate tools do not cover.
+
 ## Event watch
 
 `{{TOOL_PREFIX}}_watch_events` is a bounded long-poll read tool. Call it with `after_seq` set to the last stored sequence number, optional `session_id` or `event_types`, `timeout_ms` up to 30000, and `limit` up to 100. Store the returned `latest_seq` before the next wait. A timeout with no events is not failure; call again or use the turn/status read tools for a snapshot.

package/src/setup/hermes-setup.ts

@@ -404,7 +404,7 @@ async function installConfig(spec: CoordinatorSetupSpec, force: boolean): Promis
 
 async function runSmoke(spec: CoordinatorSetupSpec): Promise<HermesSetupResult["smoke"]> {
 	const requiredTools = [...COORDINATOR_MCP_TOOL_NAMES];
-	const server = createCoordinatorMcpServer({ env: {} });
+	const server = createCoordinatorMcpServer({ env: renderHermesServerBlock(spec).env as NodeJS.ProcessEnv });
 	const listed = await server.handleJsonRpc({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} });
 	const listedResult = isRecord(listed.result) ? listed.result : {};
 	const tools = Array.isArray(listedResult.tools) ? listedResult.tools : [];

package/src/setup/host-plugin-setup.ts

@@ -0,0 +1,142 @@
+/**
+ * Host plugin setup for `gjc setup claude` and `gjc setup codex`.
+ *
+ * Renders install guidance and a fail-closed coordinator MCP config preview for
+ * the canonical generated plugin bundle under `plugins/`. This is intentionally
+ * render-only and fail-closed: the workdir allowlist is scoped to the project
+ * root and no mutation class is enabled until the user opts in.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getProjectDir } from "@gajae-code/utils";
+
+export type HostPluginKind = "claude" | "codex";
+
+export interface HostPluginSetupFlags {
+	json?: boolean;
+	check?: boolean;
+	root?: string[];
+	repo?: string;
+}
+
+export interface HostPluginSetupResult {
+	ok: true;
+	host: HostPluginKind;
+	mode: "render";
+	gated: boolean;
+	pluginPath: string;
+	manifestPath: string;
+	marketplacePath: string;
+	installGuidance: string[];
+	coordinatorConfigPreview: {
+		command: string;
+		args: string[];
+		env: Record<string, string>;
+	};
+	mutationPolicy: string;
+	notes: string[];
+	check?: { ok: boolean; checked: string[]; missing: string[] };
+}
+
+const NAMESPACE_LABEL = "gajae-code-plugin";
+
+function resolveProjectRoot(flags: HostPluginSetupFlags): string {
+	const explicit = flags.root?.find(root => root.trim().length > 0);
+	return explicit ? path.resolve(explicit) : getProjectDir();
+}
+
+function verifyBundleFiles(files: string[]): { ok: boolean; checked: string[]; missing: string[] } {
+	const missing = files.filter(file => !fs.existsSync(file));
+	return { ok: missing.length === 0, checked: files, missing };
+}
+
+export function buildHostPluginSetup(host: HostPluginKind, flags: HostPluginSetupFlags = {}): HostPluginSetupResult {
+	const projectRoot = resolveProjectRoot(flags);
+	const marketplaceRoot = path.join(projectRoot, "plugins");
+	const pluginDir = path.join(marketplaceRoot, "gajae-code");
+	const repo = flags.repo && flags.repo.trim().length > 0 ? flags.repo.trim() : NAMESPACE_LABEL;
+
+	// Concrete, fail-closed env: workdir allowlist is the project root, no mutations.
+	const env: Record<string, string> = {
+		GJC_COORDINATOR_MCP_WORKDIR_ROOTS: projectRoot,
+		GJC_COORDINATOR_MCP_REPO: repo,
+		GJC_COORDINATOR_MCP_SESSION_COMMAND: "gjc --worktree",
+	};
+
+	if (host === "claude") {
+		const manifestPath = path.join(pluginDir, ".claude-plugin", "plugin.json");
+		const marketplacePath = path.join(marketplaceRoot, ".claude-plugin", "marketplace.json");
+		return {
+			ok: true,
+			host,
+			mode: "render",
+			gated: false,
+			pluginPath: marketplaceRoot,
+			manifestPath,
+			marketplacePath,
+			installGuidance: [
+				`Add the local marketplace: /plugin marketplace add ${marketplaceRoot}`,
+				"Install the plugin: /plugin install gajae-code",
+				"Then call gjc_delegate_plan / gjc_delegate_execute / gjc_delegate_team from Claude Code.",
+			],
+			coordinatorConfigPreview: { command: "gjc", args: ["mcp-serve", "coordinator"], env },
+			mutationPolicy:
+				"Fail-closed: delegation is read-only until you set GJC_COORDINATOR_MCP_MUTATIONS=sessions and pass allow_mutation:true per call.",
+			notes: [],
+			...(flags.check
+				? { check: verifyBundleFiles([manifestPath, marketplacePath, path.join(pluginDir, ".mcp.json")]) }
+				: {}),
+		};
+	}
+
+	// Codex: verified installable on Codex CLI 0.139.0 via the local marketplace smoke.
+	const manifestPath = path.join(pluginDir, ".codex-plugin", "plugin.json");
+	const marketplacePath = path.join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+	return {
+		ok: true,
+		host,
+		mode: "render",
+		gated: false,
+		pluginPath: marketplaceRoot,
+		manifestPath,
+		marketplacePath,
+		installGuidance: [
+			`Add the local marketplace: codex plugin marketplace add ${marketplaceRoot}`,
+			"Install the plugin: codex plugin add gajae-code@gajae-code-local",
+			"Then call gjc_delegate_plan / gjc_delegate_execute / gjc_delegate_team from Codex.",
+		],
+		coordinatorConfigPreview: { command: "gjc", args: ["mcp-serve", "coordinator"], env },
+		mutationPolicy:
+			"Fail-closed: delegation is read-only until you set GJC_COORDINATOR_MCP_MUTATIONS=sessions and pass allow_mutation:true per call.",
+		notes: [
+			"Verified on Codex CLI 0.139.0: marketplace add + plugin add install the plugin (enabled) and `codex mcp list` registers gjc-coordinator with the fail-closed env.",
+			"The bundled .codex.mcp.json workdir root is host-neutral; `gjc setup codex` renders a concrete root, and operators should re-run the local marketplace smoke on their target Codex version.",
+		],
+		...(flags.check
+			? {
+					check: verifyBundleFiles([
+						manifestPath,
+						marketplacePath,
+						path.join(pluginDir, ".codex.mcp.json"),
+						path.join(pluginDir, "skills", "gjc-delegation", "SKILL.md"),
+					]),
+				}
+			: {}),
+	};
+}
+
+export function formatHostPluginSetup(result: HostPluginSetupResult): string {
+	const lines: string[] = [];
+	lines.push(`host: ${result.host}${result.gated ? " (gated on versioned smoke)" : ""}`);
+	lines.push(`plugin: ${result.pluginPath}`);
+	lines.push("install:");
+	for (const step of result.installGuidance) lines.push(`  - ${step}`);
+	lines.push(`mcp: ${result.coordinatorConfigPreview.command} ${result.coordinatorConfigPreview.args.join(" ")}`);
+	lines.push(
+		`  GJC_COORDINATOR_MCP_WORKDIR_ROOTS=${result.coordinatorConfigPreview.env.GJC_COORDINATOR_MCP_WORKDIR_ROOTS}`,
+	);
+	lines.push(result.mutationPolicy);
+	for (const note of result.notes) lines.push(`note: ${note}`);
+	return lines.join("\n");
+}