@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/async/support.ts

@@ -1,31 +1,6 @@
-import * as path from "node:path";
-import { resolveEquivalentPath } from "@gajae-code/utils";
 import type { Settings } from "../config/settings";
 
 export function isBackgroundJobSupportEnabled(settings: Pick<Settings, "get">): boolean {
 	void settings;
 	return true;
 }
-
-/**
- * Single source of truth for the AsyncJobManager endpoint key.
- *
- * A session with an explicit provider session id is keyed by (provider id,
- * transcript path); everything else is keyed by its logical session id. The
- * transcript component is canonicalized so a path alias — symlink, `..`
- * segment, or unresolved relative path — cannot register the manager under one
- * key at construction and look it up under another across a session-identity
- * transition, stranding ownership.
- *
- * Both the SDK constructor and AgentSession's transition rekeying must derive
- * the key here; duplicating the shape lets the two drift apart silently.
- */
-export function asyncJobEndpointId(
-	providerSessionId: string | undefined,
-	sessionId: string,
-	sessionFile: string | undefined,
-): string {
-	return providerSessionId !== undefined && sessionFile !== undefined
-		? JSON.stringify(["async-job-endpoint", providerSessionId, resolveEquivalentPath(path.resolve(sessionFile))])
-		: sessionId;
-}

package/src/capability/index.ts

@@ -22,6 +22,7 @@ import {
 } from "@gajae-code/utils";
 
 import type { Settings } from "../config/settings";
+import { resolveGlobalUserSkillLinkTrust, resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { clearCache as clearFsCache, findRepoRoot, cacheStats as fsCacheStats, invalidate as invalidateFs } from "./fs";
 import type {
 	Capability,
@@ -73,6 +74,17 @@ const EXPLICIT_HOME_PROVIDER_ROOTS = [
 
 const ANCESTOR_SCOPED_PROJECT_PROVIDERS = new Set(["agents", "agents-md", "cline"]);
 
+function resolveExternalUserSkillSymlinkTrust(settings: Settings | undefined): boolean {
+	const userOwnedTrust = resolveGlobalUserSkillLinkTrust({
+		trustUserSkills:
+			typeof settings?.getGlobal === "function" ? settings.getGlobal("skills.trustUserSkills") : undefined,
+		enablePiUser: typeof settings?.getGlobal === "function" ? settings.getGlobal("skills.enablePiUser") : undefined,
+	});
+	const effectiveScopeTrust =
+		typeof settings?.getGroup === "function" ? resolveSkillScopeTrust(settings.getGroup("skills"), "user") : true;
+	return userOwnedTrust && effectiveScopeTrust;
+}
+
 function isWithinOrEqual(root: string, candidate: string): boolean {
 	const relative = path.relative(root, candidate);
 	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
@@ -413,6 +425,7 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 	const ordinaryOptions: LoadOptions = options.isolatedHome ? { ...options, isolatedHome: false } : options;
 	const cwd = ordinaryOptions.cwd ?? getProjectDir();
 	const home = getTrustedHomeDir();
+	const activeSettings = ordinaryOptions.settings ?? settingsByCwd.get(path.normalize(cwd));
 	const userAgentDir = ordinaryOptions.agentDir ? path.resolve(ordinaryOptions.agentDir) : getAgentDir();
 	const profileAuthority =
 		ordinaryOptions.profileAuthority ??
@@ -429,6 +442,7 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 		repoRoot,
 		isolatedHome: false,
 		settings: ordinaryOptions.settings,
+		allowExternalUserSkillSymlinks: resolveExternalUserSkillSymlinkTrust(activeSettings),
 		bypassCache: ordinaryOptions.bypassCache,
 	};
 	const providers = filterProviders(capability, ordinaryOptions);
@@ -521,6 +535,7 @@ export async function loadCapabilityForHome<T>(
 		isolatedHome,
 		homeIdentity,
 		settings: isolatedOptions.settings,
+		allowExternalUserSkillSymlinks: resolveExternalUserSkillSymlinkTrust(isolatedOptions.settings),
 	};
 
 	return await loadImpl(capability, providers, ctx, isolatedOptions);

package/src/capability/mcp.ts

@@ -41,6 +41,8 @@ export interface MCPServer {
 	url?: string;
 	/** HTTP headers (for HTTP transport) */
 	headers?: Record<string, string>;
+	/** Persisted public-network requirement for an HTTP MCP endpoint. */
+	publicNetwork?: boolean;
 	/** Authentication configuration */
 	auth?: {
 		type: "oauth" | "apikey";

package/src/capability/skill.ts

@@ -41,6 +41,8 @@ export interface Skill {
 	name: string;
 	/** Absolute path to skill file */
 	path: string;
+	/** Lexical path used to discover the file, preserving symlink provenance for management operations. */
+	discoveryPath?: string;
 	/** Skill content (markdown) */
 	/** Lazily load the markdown body when the caller needs prompt content. */
 	loadContent?: () => Promise<string>;

package/src/capability/types.ts

@@ -44,6 +44,8 @@ export interface LoadContext {
 	bypassCache?: boolean;
 	/** Owning session settings for provider policy decisions. */
 	settings?: Settings;
+	/** User-owned permission to follow skill links outside a user scan root. */
+	allowExternalUserSkillSymlinks?: boolean;
 }
 
 /**

package/src/cli/auth-broker-cli.ts

@@ -467,7 +467,7 @@ async function runImport(flags: AuthBrokerCommandArgs["flags"]): Promise<void> {
 	if (!target) {
 		throw new Error("Usage: gjc auth-broker import <file|dir> [--provider=<id>] [--include-disabled] [--dry-run]");
 	}
-	const resolvedTarget = path.resolve(target.startsWith("~") ? target.replace(/^~/, os.homedir()) : target);
+	const resolvedTarget = path.resolve(target.startsWith("~") ? target.replace(/^~/, () => os.homedir()) : target);
 	const { entries, skipped } = await loadImportPlan(resolvedTarget, flags.provider, flags.includeDisabled === true);
 
 	if (flags.json) {

package/src/cli/customize-doctor.ts

@@ -32,7 +32,7 @@ import { type SlashCommand, slashCommandCapability } from "../capability/slash-c
 import { type CustomTool, toolCapability } from "../capability/tool";
 import type { Capability, LoadContext, LoadResult, SourceMeta } from "../capability/types";
 import { Settings, type Settings as SettingsInstance } from "../config/settings";
-import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
+import { resolveGlobalUserSkillLinkTrust, resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { getEmbeddedDefaultGjcSkills } from "../defaults/gjc-defaults";
 import { initializeWithSettings, loadCapability } from "../discovery";
 import { inspectClaudeConvention } from "../discovery/claude";
@@ -683,6 +683,10 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 			...activeSettings.getGroup("skills"),
 			cwd,
 			disabledExtensions: activeSettings.get("disabledExtensions"),
+			allowExternalUserSkillSymlinks: resolveGlobalUserSkillLinkTrust({
+				trustUserSkills: activeSettings.getGlobal("skills.trustUserSkills"),
+				enablePiUser: activeSettings.getGlobal("skills.enablePiUser"),
+			}),
 		});
 		for (const skill of result.skills) loadedNames.add(getSkillFilesystemIdentity(skill.name));
 	}
@@ -798,7 +802,16 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 	for (const dir of [...customDirs].sort()) {
 		const scan = await scanSkillsFromDir(
 			{ cwd, home: os.homedir(), repoRoot: null },
-			{ dir: expandTilde(dir), providerId: "custom", level: "user", requireDescription: true },
+			{
+				dir: expandTilde(dir),
+				providerId: "custom",
+				level: "user",
+				requireDescription: true,
+				allowExternalUserSkillSymlinks: resolveGlobalUserSkillLinkTrust({
+					trustUserSkills: activeSettings.getGlobal("skills.trustUserSkills"),
+					enablePiUser: activeSettings.getGlobal("skills.enablePiUser"),
+				}),
+			},
 		);
 		for (const skill of scan.items) {
 			const base: Omit<CustomizeDoctorItem, "status" | "reason" | "detail" | "remediation"> = {

package/src/cli/doctor/repairs.ts

@@ -954,7 +954,10 @@ export async function executeSelectedDoctorRepair(
 					},
 					afterChecks,
 				};
-			const preEffect = outcome.kind === "owner_unavailable" || outcome.kind === "prepare_refused";
+			const preEffect =
+				outcome.kind === "owner_unavailable" ||
+				outcome.kind === "prepare_refused" ||
+				outcome.kind === "attach_only_refused";
 			return {
 				repair: {
 					...plan,

package/src/cli/doctor-supervisor.ts

@@ -74,6 +74,9 @@ const WORKER_ENV_KEYS = [
 	"XDG_DATA_HOME",
 	"XDG_STATE_HOME",
 	"XDG_CACHE_HOME",
+	// SDK_BROKER_AUTOSTART_ENV (sdk/broker/ensure.ts), kept literal so this supervisor stays
+	// import-light. A supervisor-owned broker must stay unrestartable from the doctor worker.
+	"GJC_SDK_BROKER_AUTOSTART",
 ] as const;
 
 const COMPILED = /(?:\/\$bunfs\/|\/~BUN\/|\/%7EBUN\/)/i.test(import.meta.url);

package/src/cli/public-command-errors.ts

@@ -20,6 +20,7 @@ export type PublicFailureKind =
 	| "timeout"
 	| "wait_timeout"
 	| "uncertain_after_send"
+	| "busy"
 	| "daemon_unhealthy"
 	| "daemon_stale"
 	| "daemon_mixed"
@@ -100,6 +101,10 @@ export const PUBLIC_COMMAND_DIAGNOSTICS = {
 		"The macOS open-file limit is below the recommended minimum; increase it before starting additional concurrent work.",
 	sdk_resource_gone:
 		"The requested resource is not available from this session endpoint; this reports absent resource state, not an empty result.",
+	sdk_unknown_operation:
+		"The --op value is not a known SDK operation id for this command. Per-session control ids include turn.prompt, turn.steer, turn.follow_up, turn.abort and turn.abort_and_prompt.",
+	sdk_scope_requires_repository:
+		"The selected session-list scope requires a Git repository. Run inside a checkout, pass --repo <path>, or use --scope cwd or --scope all.",
 	router_cleanup_failed: "SDK session Router cleanup failed.",
 	broker_cleanup_failed: "SDK broker client cleanup failed.",
 	// The broker reports this code from several distinct causes, so the text names none
@@ -162,6 +167,7 @@ const messages: Record<PublicFailureKind, string> = {
 	timeout: "The operation timed out; its outcome requires reconciliation.",
 	wait_timeout: "Waiting timed out after the operation was accepted. Do not replay it.",
 	uncertain_after_send: "The request was sent but its outcome is uncertain. Reconcile before any replay.",
+	busy: "The session is running a turn and refused the request.",
 	daemon_unhealthy: "The selected daemon is unhealthy.",
 	daemon_stale: "The selected daemon has stale runtime state.",
 	daemon_mixed: "Some daemon targets failed. Do not repeat mutations that already succeeded.",
@@ -282,6 +288,9 @@ export function classifyPublicCommandFailure(
 	else if (kind === "uncertain_after_send") {
 		category = "uncertain";
 		outcomeCertainty = "unknown";
+	} else if (kind === "busy") {
+		category = "unavailable";
+		if (outcomeCertainty === "not-applied") retryability = "yes";
 	} else if (
 		[
 			"unavailable",
@@ -325,7 +334,18 @@ export function classifyPublicCommandFailure(
 			nextSteps.push(step("Wait for the existing restart to finish, then inspect status; do not restart again."));
 		const session = references.find(ref => ref.kind === "sessionId");
 		const operation = references.find(ref => ref.kind === "operationRef");
-		if (
+		if (kind === "busy" && canonical[0] === "sdk" && outcomeCertainty === "not-applied") {
+			// A refused-before-execution request has no operation record to reconcile:
+			// point at the busy turn instead of a status lookup that can only say unknown.
+			nextSteps.push(
+				step(
+					"Steer the active turn with `sdk session raw control <sessionId> --op turn.steer`, or wait until the session is idle before sending again.",
+					session && executableValue(session.value)
+						? ["sdk", "session", "inspect", session.value]
+						: ["sdk", "session", "list"],
+				),
+			);
+		} else if (
 			canonical[0] === "sdk" &&
 			session &&
 			operation &&

package/src/cli/public-command-registry.ts

@@ -81,6 +81,9 @@ const argument = (description: string, extra: Partial<PublicArgumentDescriptor>
 	...extra,
 });
 const agentDir = stringFlag("SDK broker/state directory (default: the configured agent directory).");
+const attachOnly = booleanFlag(
+	"Attach only to a live SDK broker; never start, retire or restart one (same as GJC_SDK_BROKER_AUTOSTART=0).",
+);
 const repo = stringFlag("Workspace directory for scope or saved-session resolution (default: current directory).");
 const exactSessionRepo = stringFlag(
 	"Accepted for compatibility only; ignored because the exact session ID selects the broker target.",
@@ -187,7 +190,8 @@ function node(path: string, input: NodeInput): PublicCommandDescriptor {
 		examples: [{ syntax: example ?? `gjc ${path} --help --json`, executable: false }],
 	};
 }
-const sessionFlags = { "agent-dir": agentDir };
+const guideFlags = { "agent-dir": agentDir };
+const sessionFlags = { "agent-dir": agentDir, "attach-only": attachOnly };
 const observeDaemonFlags = {
 	all: booleanFlag("Target all registered daemon kinds."),
 	verbose: booleanFlag("Show runtime detail and the full roots list.", { char: "v" }),
@@ -212,7 +216,7 @@ const daemonArgs = {
 export const PUBLIC_COMMANDS: readonly PublicCommandDescriptor[] = [
 	node("sdk", {
 		description: "Discover SDK transports, sessions, search, spawn and advisory guides.",
-		children: ["serve", "search", "spawn", "session", "guides"],
+		children: ["serve", "broker", "search", "spawn", "session", "guides"],
 		syntax: "<command>",
 		constraints: [
 			"A public child command is required unless requesting help or root evidence retrieval.",
@@ -242,6 +246,24 @@ export const PUBLIC_COMMANDS: readonly PublicCommandDescriptor[] = [
 		],
 		example: "gjc sdk serve --stdio",
 	}),
+	node("sdk broker", {
+		description: "Run the SDK broker under an external supervisor.",
+		children: ["run"],
+		syntax: "<command>",
+	}),
+	node("sdk broker run", {
+		description:
+			"Run the SDK broker in the foreground for a supervisor (systemd, launchd); stable contract, never detaches.",
+		flags: { "agent-dir": agentDir },
+		syntax: "[--agent-dir <dir>]",
+		risk: "Owns the broker for the agent directory; clients should run attach-only (GJC_SDK_BROKER_AUTOSTART=0) so they never start a competing one.",
+		constraints: [
+			"Stays in the foreground until SIGTERM or SIGINT, stops gracefully, then exits with the signal status (143 or 130).",
+			"Exits 1 without serving when another live broker owns the agent directory (it never retires it) or startup fails.",
+			"Exits 1 if it loses its discovery root or cannot renew its heartbeat while serving; a broker.shutdown request exits 0.",
+		],
+		example: "gjc sdk broker run --agent-dir ~/.gjc/agent",
+	}),
 	node("sdk search", {
 		description: "Search broker-visible sessions in an exact repo, pwd or global scope.",
 		syntax: "[--scope repo|pwd|global] [--repo <dir>] [--limit <N>] [--cursor <cursor>]",
@@ -442,7 +464,7 @@ export const PUBLIC_COMMANDS: readonly PublicCommandDescriptor[] = [
 	node("sdk guides refresh", {
 		description: "Fetch and verify an allowlisted HTTPS guide manifest and advisory cache.",
 		flags: {
-			...sessionFlags,
+			...guideFlags,
 			url: stringFlag("HTTPS allowlisted manifest URL.", { required: true }),
 			"timeout-ms": positive("Bounded refresh timeout in milliseconds."),
 		},
@@ -451,14 +473,14 @@ export const PUBLIC_COMMANDS: readonly PublicCommandDescriptor[] = [
 			"A fallback cache or bundled selection is an operational refresh failure, not online refresh success.",
 		],
 	}),
-	node("sdk guides list", { description: "List guides from the verified advisory selection.", flags: sessionFlags }),
+	node("sdk guides list", { description: "List guides from the verified advisory selection.", flags: guideFlags }),
 	node("sdk guides show", {
 		description: "Read a verified guide by ID.",
 		args: { guideId: argument("Exact guide ID from guides list.") },
-		flags: sessionFlags,
+		flags: guideFlags,
 		syntax: "<guideId>",
 	}),
-	node("sdk guides status", { description: "Report guide cache and selection status.", flags: sessionFlags }),
+	node("sdk guides status", { description: "Report guide cache and selection status.", flags: guideFlags }),
 	node("sdk guides trust", { description: "Show the static guide trust policy; no refresh or cache mutation." }),
 	node("daemon", {
 		description: "Manage Telegram, Discord and Slack background daemons, not the SDK broker.",

package/src/cli/setup-cli.ts

@@ -766,7 +766,7 @@ async function confirmImport(count: number): Promise<boolean> {
 }
 
 /**
- * Discover existing Claude Code / Codex CLI credentials and import them into the
+ * Discover existing Claude Code / Codex CLI / Kiro CLI credentials and import them into the
  * gjc credential store after a redacted preview + confirmation. Falls back to
  * manual-setup guidance when nothing importable is found.
  */
@@ -834,7 +834,7 @@ export async function handleCredentialsSetup(
 			for (const line of formatDiscoverySummary(filteredResult)) process.stdout.write(`  ${line}\n`);
 			process.stdout.write(
 				chalk.yellow(
-					`\nNo importable Claude/Codex credentials found. Continue with manual setup:\n` +
+					`\nNo importable Claude/Codex/Kiro CLI credentials found. Continue with manual setup:\n` +
 						`  ${APP_NAME} setup provider   (add an API-compatible provider)\n` +
 						`  ${APP_NAME} (then /login)     (interactive OAuth/subscription login)\n`,
 				),
@@ -930,7 +930,7 @@ ${chalk.bold("Components:")}
   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)
-  credentials Optional: import existing Claude Code / Codex CLI credentials
+  credentials Optional: import existing Claude Code / Codex CLI / Kiro CLI credentials
 
 
 ${chalk.bold("Provider example:")}
@@ -998,7 +998,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available
   ${APP_NAME} setup python --check   Check if Python execution is available
-  ${APP_NAME} setup credentials      Discover & import existing Claude/Codex credentials
+  ${APP_NAME} setup credentials      Discover & import existing Claude/Codex/Kiro CLI 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

package/src/cli/skills-cli.ts

@@ -3,6 +3,7 @@
  * filesystem-discovered custom skills.
  */
 import { Settings } from "../config/settings";
+import { resolveGlobalUserSkillLinkTrust } from "../config/skill-settings-defaults";
 import {
 	DEFAULT_GJC_DEFINITION_NAMES,
 	type EmbeddedDefaultGjcSkill,
@@ -111,6 +112,10 @@ export async function runSkillsCommand(cmd: SkillsCommandArgs): Promise<void> {
 					...settings.getGroup("skills"),
 					disabledExtensions: settings.get("disabledExtensions"),
 				},
+				allowExternalUserSkillSymlinks: resolveGlobalUserSkillLinkTrust({
+					trustUserSkills: settings.getGlobal("skills.trustUserSkills"),
+					enablePiUser: settings.getGlobal("skills.enablePiUser"),
+				}),
 			});
 			if (cmd.flags?.json) {
 				writeJson({

package/src/commands/deep-interview.ts

@@ -7,37 +7,71 @@ export default class DeepInterview extends Command {
 
 All deep-interview state operations go through this command — no gjc state needed:
   read                Print the persisted envelope, revision, content sha, and any pending draft
-  write               One-shot incremental JSON merge into state (--reset replaces; the locked
-                      intent contract survives a reset)
-  stage               Stage one JSON transition draft (--for <transition> --input '<json>'|@file)
+  write               One-shot incremental JSON merge into state; required --input '<json>'|@file
+                      must use the {"state":{...}} shape (--reset replaces; the locked intent
+                      contract survives a reset)
+  kickoff             Seed an interviewing session; --trace and --json are supported alongside
+                      --quick|--standard|--deep
+  write-spec          Persist a final spec through --write; --force only overwrites corrupt state
+  stage               Stage one JSON transition draft; required --for <transition> and --input
+                      '<json>'|@file use the {"state":{...}} shape
   check               Dry-run the staged draft against current state (same merge apply performs)
   apply               Commit the staged draft with runtime-owned revision+sha CAS
   discard             Remove the pending draft
   clear               Clear deep-interview state for the session (lifecycle passthrough)
+  approve-execution   Record the user's separate, explicit approval for a ready canonical Crystal
   handoff             Hand off to the next workflow skill (lifecycle passthrough)
+  --crystallize       Promote a bounded authenticated conversation snapshot into a versioned
+                      Crystal; required --input '<crystallize JSON>'|@file and --slug <slug>
+
+Crystallize input must be a JSON object with these required fields (optional prior, removed_ids,
+resolved_open_gaps, resolved_conflicts, and their anchors may extend the object):
+  {"snapshot":{"revision":N,"start":N,"end":N,"digest":"<sha256>","messages":[...]},
+   "current_revision":N,"items":[{"id":"...","kind":"goal|constraint|decision|acceptance_criterion|non_goal",
+   "classification":"confirmed|inferred|disputed","statement":"...","anchor":{"message_index":N,"quote":"..."}}],
+   "open_gaps":[],"conflicts":[]}
+Confirmed items require a verbatim user anchor; inferred/disputed items must not be treated as
+confirmed. The raw --input payload is bounded to 1 MiB; items are capped at 128 and each text
+field at 10,000 characters, and snapshot messages must be contiguous, ordered, and cover
+start..end (maximum 200 messages). The
+digest/current_revision must match the live authenticated transcript. A ready Crystal persists as
+deep-interview-<slug>-v<spec_version>.md;
+needs-questions, stale, or superseded Crystal input does not publish a spec. Crystallize always
+leaves execution_approval as not-approved; approve-execution is a separate explicit transition.
 
 Ambiguity is runtime-owned: apply/write derive current_ambiguity from the latest valid scored
 round and clamp it to the deterministic floor. Sessions resolve from --session-id, payload
-session_id, or GJC_SESSION_ID.`;
+session_id, or GJC_SESSION_ID. A relative GJC_SESSION_FILE is resolved against the requested
+workspace cwd, never the process launch directory.`;
 	static strict = false;
 	static flags = {
 		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
 		standard: Flags.boolean({ description: "Seed a standard deep-interview run" }),
 		deep: Flags.boolean({ description: "Seed a deep deep-interview run" }),
+		crystallize: Flags.boolean({ description: "Crystallize a bounded conversation snapshot into a versioned spec" }),
 		trace: Flags.boolean({ description: "Run a bounded trace evidence pre-step before interview questions" }),
 		threshold: Flags.string({ description: "Override ambiguity threshold for kickoff" }),
 		"threshold-source": Flags.string({ description: "Describe the threshold override source" }),
 		"session-id": Flags.string({
 			description: "Route state/spec handoff through a session-scoped .gjc/_session-{sessionid} directory",
 		}),
-		input: Flags.string({ description: "JSON payload (or @file) for the write/stage verbs" }),
+		input: Flags.string({
+			description:
+				'Required JSON object (or @file): generic api uses --input; write/stage use {"state":{...}}; crystallize uses snapshot/current_revision/items; payload <=1 MiB',
+		}),
 		for: Flags.string({
 			description: "Transition for stage: initialize-context | record-round | update-facts | merge-state",
 		}),
 		reset: Flags.boolean({ description: "With write: replace state instead of incremental merge" }),
-		write: Flags.boolean({ description: "Persist a final deep-interview spec through the sanctioned GJC CLI/API" }),
+		write: Flags.boolean({
+			description:
+				"Persist a final deep-interview spec through the sanctioned GJC CLI/API (requires --spec; positional write requires --input)",
+		}),
 		stage: Flags.string({ description: 'Spec stage for --write (currently "final")' }),
-		slug: Flags.string({ description: "Safe slug for .gjc/_session-{sessionid}/specs/deep-interview-<slug>.md" }),
+		slug: Flags.string({
+			description:
+				"Required with --crystallize; safe slug for .gjc/_session-{sessionid}/specs/deep-interview-<slug>.md",
+		}),
 		spec: Flags.string({ description: "Final spec markdown or a path to the final spec markdown" }),
 		handoff: Flags.string({ description: 'After --write, hand off to a workflow target (currently "ralplan")' }),
 		deliberate: Flags.boolean({
@@ -48,13 +82,18 @@ session_id, or GJC_SESSION_ID.`;
 	};
 	static examples = [
 		'$ gjc deep-interview --trace --standard "<idea>"',
+		'$ gjc deep-interview --trace --standard "<idea>" --json',
 		"$ gjc deep-interview read --json",
-		'$ gjc deep-interview write --input \'{"state":{"threshold":0.05}}\' --json',
+		'$ gjc deep-interview write --input \'{"state":{"threshold":0.05,"threshold_source":"default"}}\' --json',
 		'$ gjc deep-interview stage --for record-round --input \'{"state":{"rounds":[{"round":1,"round_key":"r1"}]}}\' --json',
 		"$ gjc deep-interview check --json",
 		"$ gjc deep-interview apply --json",
+		"$ gjc deep-interview approve-execution --json",
 		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --force",
 		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
+		'$ gjc deep-interview --crystallize --input \'{"snapshot":{"revision":1,"start":0,"end":0,"digest":"<64-hex-sha256>","messages":[{"index":0,"role":"user","content":"Build audit reports"}]},"current_revision":1,"items":[{"id":"goal:reports","kind":"goal","classification":"confirmed","statement":"Build audit reports","anchor":{"message_index":0,"quote":"Build audit reports"}}],"open_gaps":[],"conflicts":[]}\' --slug audit-reports --json',
+		"$ gjc deep-interview --crystallize --input @conversation.json --slug my-feature --json",
 	];
 
 	async run(): Promise<void> {

package/src/commands/mcp-serve.ts

@@ -7,6 +7,7 @@ import {
 } from "../coordinator/contract";
 import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
 import { type BrokerDiscovery, readBrokerDiscovery } from "../sdk/broker/discovery";
+import { SDK_BROKER_AUTOSTART_ENV } from "../sdk/broker/ensure";
 import { UnsupportedStateVersionError } from "../sdk/broker/state-version";
 import { runSdkMcpStdio, SDK_MCP_TOOL_NAMES } from "../sdk/mcp/server";
 
@@ -104,6 +105,10 @@ export default class McpServe extends Command {
 	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 }),
+		"attach-only": Flags.boolean({
+			description: "Attach only to a live SDK broker; never start one (same as GJC_SDK_BROKER_AUTOSTART=0)",
+			default: false,
+		}),
 	};
 
 	async run(): Promise<void> {
@@ -122,6 +127,8 @@ export default class McpServe extends Command {
 			return;
 		}
 
+		if (flags["attach-only"]) process.env[SDK_BROKER_AUTOSTART_ENV] = "0";
+
 		if (flags.check) {
 			if (!flags.json) {
 				const serverName = server === "sdk" ? "gjc-sdk-mcp" : COORDINATOR_MCP_SERVER_NAME;