@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/commands/sdk.ts

@@ -8,6 +8,7 @@ import type { Args as ParsedArgs } from "../cli/args";
 import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
+import { initTheme } from "../modes/theme/theme";
 import { ACP_MCP_REQUEST_TIMEOUT_MS, ACP_MCP_STARTUP_HEADROOM_MS } from "../sdk/acp/mcp";
 import { Broker } from "../sdk/broker/broker";
 import { readBrokerDiscovery } from "../sdk/broker/discovery";
@@ -510,6 +511,12 @@ export async function runSessionHost(
 			throw await registrationFailure(error);
 		}
 
+		try {
+			await initTheme(false);
+		} catch (error) {
+			throw await registrationFailure(error);
+		}
+
 		// The longer MCP startup ceiling is scoped to ACP lifecycle launches only:
 		// it applies when this request actually carried `mcpServers`. Ordinary
 		// CLI/SDK `mcpConfigPath` consumers keep the manager's short default.
@@ -518,8 +525,8 @@ export async function runSessionHost(
 		// Inside it, the throw would be caught, reclassified as
 		// `registration`/`failed`, and written a second time, losing the
 		// `startup`/`pending` outcome the readiness cutoff is supposed to report.
-		// Session-manager open and MCP config write already consumed part of the
-		// budget, so re-read the clock here rather than reusing the earlier check.
+		// Session-manager open, MCP config write, and theme initialization already
+		// consumed part of the budget, so re-read the clock here.
 		let mcpStartupTimeoutMs: number | undefined;
 		if (mcpConfigPath !== undefined) {
 			const remaining = request.semanticReadyDeadlineAt - now() - ACP_MCP_STARTUP_HEADROOM_MS;
@@ -606,9 +613,43 @@ export async function runSessionHost(
 		})();
 		return failureRollback;
 	};
+	const sessionEndpointPath = path.join(request.stateRoot, "sdk", `${request.sessionId}.json`);
+	const exitAfterSessionDisposal = async (): Promise<void> => {
+		await disposeSession();
+		let failure: SdkStartupFailure | undefined;
+		try {
+			const endpoint = JSON.parse(await fs.readFile(sessionEndpointPath, "utf8")) as {
+				pid?: unknown;
+				sessionId?: unknown;
+			};
+			if (endpoint.pid === process.pid && endpoint.sessionId === request.sessionId)
+				failure = {
+					phase: "startup",
+					reason: "failed",
+					message: `SDK host endpoint remained after graceful shutdown: ${request.sessionId}`,
+				};
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+				failure = {
+					phase: "startup",
+					reason: "failed",
+					message: `SDK host endpoint cleanup could not be verified: ${request.sessionId}`,
+				};
+			}
+		}
+		if (failure) {
+			process.exitCode = 1;
+			process.stderr.write(`${failure.message}\n`);
+			await writeFailure(failure, rollback.result).catch(() => {});
+		}
+		process.exit(process.exitCode ?? 0);
+	};
+	let stopping = false;
 	const stop = () => {
 		if (capability.result?.status === "started") {
-			void disposeSession().finally(() => process.exit(0));
+			if (stopping) return;
+			stopping = true;
+			void exitAfterSessionDisposal();
 			return;
 		}
 		const failure = capability.normalizeFailure("startup", "failed", "SDK lifecycle host terminated.");
@@ -733,50 +774,45 @@ class SdkServeHelp extends Command {
 
 class SdkSessionHelp extends Command {
 	static description =
-		"Manage SDK sessions: `gjc sdk session list|inspect|send|status|tail|elevate`, or the explicit raw hatch `gjc sdk session raw control|query|global`. The session CLI is broker-bound, credential-free by default, and elevation approval requires an attended operator.";
+		"Manage SDK sessions: `gjc sdk session list|inspect|send|status|tail`, or the explicit raw hatch `gjc sdk session raw control|query|global`. The session CLI is broker-bound and credential-free.";
 	static args = {
 		verb: Args.string({
 			description: "Session verb",
 			required: false,
-			options: ["list", "inspect", "send", "status", "tail", "elevate", "raw"],
+			options: ["list", "inspect", "send", "status", "tail", "raw"],
 		}),
 		target: Args.string({
 			description: "Session id (or the raw kind control|query|global for `raw`)",
 			required: false,
 		}),
-		opRef: Args.string({ description: "Operation reference to report on (status only)", required: false }),
+		opRef: Args.string({
+			description: "Operation reference for status, or session id for raw control/query",
+			required: false,
+		}),
 	};
 	static flags = {
 		"agent-dir": Flags.string({ description: "SDK broker state directory" }),
-		json: Flags.boolean({ description: "Emit JSON output (default for SDK session commands)" }),
 		repo: Flags.string({
 			description: "Workspace directory for saved-session resolution (default: current directory)",
 		}),
 		op: Flags.string({ description: "Raw control or global operation" }),
 		query: Flags.string({ description: "Raw query name" }),
-		kind: Flags.string({ description: "Elevation operation kind (control|global)", options: ["control", "global"] }),
 		"json-input": Flags.string({ description: "SDK request JSON object" }),
 		"json-input-file": Flags.string({ description: "Read SDK request JSON from a 0600 file" }),
 		"json-input-stdin": Flags.boolean({ description: "Read SDK request JSON from standard input" }),
 		"idempotency-key": Flags.string({ description: "Caller idempotency key required for SDK lifecycle globals" }),
-		"elevation-request-id": Flags.string({ description: "Approved elevation grant id for allowlisted raw controls" }),
 		confirm: Flags.boolean({ description: "Confirm a destructive SDK control operation" }),
 		cursor: Flags.string({
-			description:
-				"Raw query continuation cursor, or a saved checkpoint token to resume tail from (re-minted per connection)",
+			description: "Raw query continuation cursor, or a saved checkpoint token to resume tail from",
 		}),
-		"show-endpoint-credential": Flags.boolean({ description: "Allow session.get_endpoint secret output" }),
-		yes: Flags.boolean({ description: "Confirm endpoint credential output on a TTY" }),
 		text: Flags.string({ description: "Prompt text for send (alternative to --json-input)" }),
 		"op-ref": Flags.string({ description: "Operation reference for send (defaults to a generated ULID)" }),
 		wait: Flags.boolean({
-			description: "send --wait: poll turn.prompt_status until terminal or the wait window elapses (never cancels)",
+			description: "send --wait: poll turn.result with kind=prompt until terminal or the wait window elapses",
 		}),
 		"timeout-ms": Flags.string({ description: "Wait window for send --wait, status, and live tail follow" }),
-		strict: Flags.boolean({ description: "tail --strict: fail closed (exit 1 retention_gap) on retention gaps" }),
-		"until-idle": Flags.boolean({
-			description: "tail --until-idle: exit once the observed event stream reaches a terminal turn state",
-		}),
+		strict: Flags.boolean({ description: "tail --strict: fail closed on retention gaps" }),
+		"until-idle": Flags.boolean({ description: "tail --until-idle: exit after an observed terminal turn state" }),
 		"all-events": Flags.boolean({ description: "tail --all-events: include every event-ring kind" }),
 	};
 	async run(): Promise<void> {}
@@ -791,7 +827,6 @@ class SdkSessionCommand extends Command {
 		const verb = args.verb;
 		const target = args.target;
 		const flagRec = flags as Record<string, unknown>;
-		const timeoutMs = parsePositiveTimeout(flagRec["timeout-ms"] as string | undefined, "--timeout-ms");
 		await runSdkSessionCli({
 			action: verb,
 			...(verb === "raw"
@@ -809,13 +844,9 @@ class SdkSessionCommand extends Command {
 			jsonInputStdin: Boolean(flagRec["json-input-stdin"]),
 			confirm: Boolean(flagRec.confirm),
 			idempotencyKey: flagRec["idempotency-key"] as string | undefined,
-			elevationRequestId: flagRec["elevation-request-id"] as string | undefined,
-			operationKind: flagRec.kind as "control" | "global" | undefined,
 			cursor: flagRec.cursor as string | undefined,
-			showEndpointCredential: Boolean(flagRec["show-endpoint-credential"]),
-			yes: Boolean(flagRec.yes),
 			wait: Boolean(flagRec.wait),
-			timeoutMs,
+			timeoutMs: parsePositiveTimeout(flagRec["timeout-ms"] as string | undefined, "--timeout-ms"),
 			strict: Boolean(flagRec.strict),
 			untilIdle: Boolean(flagRec["until-idle"]),
 			allEvents: Boolean(flagRec["all-events"]),
@@ -832,7 +863,7 @@ class SdkGuidesHelp extends Command {
 		guideId: Args.string({ required: false, description: "Guide id for show" }),
 	};
 	static flags = {
-		"agent-dir": Flags.string({ description: "SDK broker state directory" }),
+		"agent-dir": Flags.string({ description: "SDK state directory for the verified guide cache" }),
 		url: Flags.string({ description: "HTTPS allowlisted manifest URL for refresh" }),
 		"timeout-ms": Flags.string({ description: "Bounded refresh timeout in milliseconds" }),
 	};
@@ -886,13 +917,11 @@ export default class Sdk extends Command {
 			return;
 		}
 		if (action === "session") {
-			const instance = new SdkSessionCommand(this.argv.slice(1), this.config);
-			await instance.run();
+			await new SdkSessionCommand(this.argv.slice(1), this.config).run();
 			return;
 		}
 		if (action === "guides") {
-			const instance = new SdkGuidesCommand(this.argv.slice(1), this.config);
-			await instance.run();
+			await new SdkGuidesCommand(this.argv.slice(1), this.config).run();
 			return;
 		}
 		if (action === "serve") {
@@ -917,22 +946,26 @@ export default class Sdk extends Command {
 		try {
 			await broker.start();
 		} catch (error) {
-			// Surface why this detached broker failed before discovery: the caller
-			// spawns with stdio ignored, so the durable marker is the only channel.
+			// This process spawns detached with stdio ignored (see ensure.ts), so the
+			// durable marker is the only channel the caller has to see why start()
+			// failed instead of a bare exit code (#3963).
 			await writeBrokerStartupFailureMarker(agentDir, {
 				reason: error instanceof Error ? error.message : String(error),
 				exitCode: 1,
 				signal: null,
+				pid: process.pid,
 			});
 			throw error;
 		}
 		if (!broker.ownsDiscovery) {
 			// Another broker owns discovery; this process exits cleanly (code 0) as
-			// the race loser. Record why so the caller can diagnose a missing winner.
+			// the race loser. Record why so a caller polling for a winner that never
+			// appears can diagnose the loss instead of seeing only a bare exit 0.
 			await writeBrokerStartupFailureMarker(agentDir, {
 				reason: "Another broker owns the lock/discovery; this broker exited as the race loser.",
 				exitCode: 0,
 				signal: null,
+				pid: process.pid,
 			});
 			return;
 		}

package/src/commands/setup.ts

@@ -12,6 +12,7 @@ const COMPONENTS: SetupComponent[] = [
 	"defaults",
 	"hermes",
 	"hooks",
+	"paseo",
 	"provider",
 	"python",
 	"stt",
@@ -59,6 +60,8 @@ export default class Setup extends Command {
 		"api-key-env": Flags.string({ description: "Read provider API key from this environment variable" }),
 		model: Flags.string({ description: "Model id to add (repeat or comma-separate)", multiple: true }),
 		"models-path": Flags.string({ description: "Override models config path" }),
+		remove: Flags.boolean({ description: "Roll back the Paseo registration GJC created" }),
+		mpreset: Flags.string({ description: "Register an additional gjc-<preset> Paseo provider" }),
 		yes: Flags.boolean({ char: "y", description: "Import discovered credentials without an interactive prompt" }),
 		"dry-run": Flags.boolean({ description: "Preview discovered credentials without importing" }),
 	};
@@ -93,6 +96,8 @@ export default class Setup extends Command {
 				gjcCommand: flags["gjc-command"],
 				target: flags.target,
 				profileDir: flags["profile-dir"],
+				remove: flags.remove,
+				mpreset: flags.mpreset,
 				yes: flags.yes,
 				dryRun: flags["dry-run"],
 			},

package/src/commands/skills.ts

@@ -1,13 +1,13 @@
 /**
- * Inspect bundled workflow skills.
+ * Inspect bundled workflow skills and filesystem-discovered custom skills.
  */
 import { Args, Command, Flags, renderCommandHelp } from "@gajae-code/utils/cli";
 import { runSkillsCommand, type SkillsAction, type SkillsCommandArgs } from "../cli/skills-cli";
 
-const ACTIONS: SkillsAction[] = ["list", "read"];
+const ACTIONS: SkillsAction[] = ["list", "read", "discover"];
 
 export default class Skills extends Command {
-	static description = "Inspect bundled GJC workflow skills";
+	static description = "Inspect bundled GJC workflow skills and discover custom filesystem skills";
 
 	static args = {
 		action: Args.string({
@@ -23,12 +23,19 @@ export default class Skills extends Command {
 
 	static flags = {
 		json: Flags.boolean({ description: "Output JSON" }),
+		source: Flags.string({
+			description: "Scope for discover: all, project, or user",
+			options: ["all", "project", "user"],
+			default: "all",
+		}),
 	};
 
 	static examples = [
 		"# List bundled workflow skills\n  gjc skills list",
 		"# Read an embedded workflow skill without requiring .gjc files\n  gjc skills read ultragoal",
 		"# Machine-readable embedded skill content\n  gjc skills read ralplan --json",
+		"# Show filesystem-discovered skills (project and user) with diagnostics\n  gjc skills discover",
+		"# Show only project-scope skills (project .gjc/skills locations)\n  gjc skills discover --source project --json",
 	];
 
 	async run(): Promise<void> {
@@ -41,7 +48,10 @@ export default class Skills extends Command {
 		const cmd: SkillsCommandArgs = {
 			action: args.action as SkillsAction,
 			name: args.name,
-			flags: { json: flags.json },
+			flags: {
+				json: flags.json,
+				source: (flags.source as "all" | "project" | "user" | undefined) ?? "all",
+			},
 		};
 		await runSkillsCommand(cmd);
 	}

package/src/commands/ultragoal.ts

@@ -1,4 +1,5 @@
-import { Command } from "@gajae-code/utils/cli";
+import { Command, renderCommandHelp } from "@gajae-code/utils/cli";
+import { ensureWorkflowSettingsMigrated } from "../config/settings";
 import {
 	GJC_SESSION_FILE_ENV,
 	GJC_SESSION_ID_ENV,
@@ -16,6 +17,14 @@ export default class Ultragoal extends Command {
 	static delegateHelp = true;
 
 	async run(): Promise<void> {
+		// A read-only help request must not perform the workflow-settings
+		// migration (which can create/drain agent.db, write config.yml, and
+		// retire legacy settings.json): render help before the trigger.
+		if (this.argv.includes("--help") || this.argv.includes("-h")) {
+			renderCommandHelp("gjc", "ultragoal", Ultragoal);
+			return;
+		}
+		await ensureWorkflowSettingsMigrated(process.cwd());
 		const isReviewStart = this.argv.includes("review") && this.argv.includes("review-start");
 		const shouldActivateGoalMode = isUltragoalCreateGoalsInvocation(this.argv);
 		const result = await runNativeUltragoalCommand(this.argv);

package/src/commands/update.ts

@@ -2,10 +2,15 @@
  * Check for and install updates.
  */
 import { getProjectDir } from "@gajae-code/utils";
-import { Command, Flags } from "@gajae-code/utils/cli";
-import { runUpdateCommand } from "../cli/update-cli";
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import { runManagedNotifyRecovery, runUpdateCommand } from "../cli/update-cli";
 import { Settings } from "../config/settings";
-import { isUpdateChannel, UPDATE_CHANNELS, type UpdateChannel } from "../config/update-channel";
+import {
+	isUpdateChannel,
+	resolveMachineLocalUpdateChannel,
+	UPDATE_CHANNELS,
+	type UpdateChannel,
+} from "../config/update-channel";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Update extends Command {
@@ -19,8 +24,20 @@ export default class Update extends Command {
 		}),
 	};
 
+	static args = {
+		action: Args.string({
+			description: "Internal post-update recovery action (update-recovery)",
+			required: false,
+			options: ["update-recovery"],
+		}),
+	};
+
 	async run(): Promise<void> {
-		const { flags } = await this.parse(Update);
+		const { args, flags } = await this.parse(Update);
+		if (args.action === "update-recovery") {
+			await runManagedNotifyRecovery({});
+			return;
+		}
 		let channel: UpdateChannel | undefined;
 		if (flags.channel !== undefined) {
 			if (!isUpdateChannel(flags.channel)) {
@@ -32,17 +49,11 @@ export default class Update extends Command {
 			channel = flags.channel;
 		} else {
 			const settings = await Settings.init({ cwd: getProjectDir() });
-			const configured = settings.get("startup.updateChannel");
-			if (isUpdateChannel(configured)) {
-				channel = configured;
-			} else {
-				// A hand-edited invalid value degrades to the schema default instead of
-				// leaking into output or the registry lookup.
-				process.stderr.write(
-					`Ignoring invalid startup.updateChannel "${configured}". Expected one of: ${UPDATE_CHANNELS.join(", ")}; using stable.\n`,
-				);
-				channel = "stable";
-			}
+			// Update selection is machine-local: a project `.gjc/config.yml`
+			// startup.updateChannel override must never silently pick the
+			// global release channel, so read the user/global layer only and
+			// fall back to the stable schema default when it is unset.
+			channel = resolveMachineLocalUpdateChannel(settings);
 		}
 		await initTheme();
 		await runUpdateCommand({ force: flags.force, check: flags.check, channel });

package/src/config/atomic-yaml-patch-worker.ts

@@ -0,0 +1,57 @@
+import * as nodeWorkerThreads from "node:worker_threads";
+import type { NativeExactFileIdentity, NativeExactUnlinkResult, NativeNoReplaceResult } from "@gajae-code/natives";
+import { exactReplacePath, linkNoReplacePath, renameNoReplacePath } from "@gajae-code/natives";
+
+export type AtomicYamlNativeWorkerRequest =
+	| {
+			operation: "exact-replace";
+			sourcePath: string;
+			destinationPath: string;
+			expectedSource: NativeExactFileIdentity;
+			expectedDestination: NativeExactFileIdentity;
+	  }
+	| {
+			operation: "no-replace";
+			sourcePath: string;
+			destinationPath: string;
+	  }
+	| {
+			operation: "no-replace-link";
+			sourcePath: string;
+			destinationPath: string;
+	  };
+
+export type AtomicYamlNativeWorkerResponse =
+	| { type: "result"; result: NativeExactUnlinkResult | NativeNoReplaceResult }
+	| { type: "error"; name?: string; message: string; stack?: string };
+
+const { parentPort } = nodeWorkerThreads;
+if (!parentPort) throw new Error("atomic YAML native worker: missing parentPort");
+
+const port = parentPort;
+port.once("message", (request: AtomicYamlNativeWorkerRequest) => {
+	try {
+		const result =
+			request.operation === "exact-replace"
+				? exactReplacePath(
+						request.sourcePath,
+						request.destinationPath,
+						request.expectedSource,
+						request.expectedDestination,
+					)
+				: request.operation === "no-replace-link"
+					? linkNoReplacePath(request.sourcePath, request.destinationPath)
+					: renameNoReplacePath(request.sourcePath, request.destinationPath);
+		port.postMessage({ type: "result", result } satisfies AtomicYamlNativeWorkerResponse);
+	} catch (error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		port.postMessage({
+			type: "error",
+			name: failure.name,
+			message: failure.message,
+			stack: failure.stack,
+		} satisfies AtomicYamlNativeWorkerResponse);
+	} finally {
+		port.close();
+	}
+});