@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/gjc-runtime/launch-worktree.ts

@@ -1,5 +1,6 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { shortenPath } from "../tools/render-utils";
 
@@ -61,6 +62,60 @@ function sanitizePathToken(value: string): string {
 	return `${prefix}-${digest}`;
 }
 
+/**
+ * Environment override for the directory that holds a repository's launch worktrees.
+ *
+ * The bucket is otherwise derived entirely from the repository path, so a machine that
+ * already keeps worktrees somewhere else — a dedicated volume, or a pre-existing
+ * `<repo>.worktrees` convention — has no way to say so and accumulates a second bucket
+ * beside the first.
+ */
+const WORKTREE_BUCKET_ENV = "GJC_WORKTREE_DIR";
+/**
+ * Expands to the repository directory name.
+ *
+ * A single exported value therefore stays repo-scoped across every checkout, which is
+ * what keeps two repositories that share a branch name from resolving to one worktree.
+ */
+const REPO_NAME_PLACEHOLDER = "{repo}";
+const DEFAULT_WORKTREE_BUCKET = `${REPO_NAME_PLACEHOLDER}.gajae-code-worktrees`;
+
+function expandHomePrefix(value: string, home: string, pathApi: typeof path.posix): string {
+	if (value === "~") return home;
+	return value.startsWith(`~${pathApi.sep}`) || value.startsWith("~/") ? pathApi.join(home, value.slice(2)) : value;
+}
+
+/**
+ * Pure core of {@link resolveWorktreeBucket}, exported for tests.
+ *
+ * Injecting the home directory and path implementation lets tests exercise
+ * Windows drive/UNC/separator semantics (`path.win32`) on any host.
+ */
+export function resolveWorktreeBucketForPath(
+	repoRoot: string,
+	envValue: string | undefined,
+	home: string,
+	pathApi: typeof path.posix,
+): string {
+	const configured = envValue?.trim();
+	const template = expandHomePrefix(configured || DEFAULT_WORKTREE_BUCKET, home, pathApi);
+	return pathApi.resolve(
+		pathApi.dirname(repoRoot),
+		template.replaceAll(REPO_NAME_PLACEHOLDER, pathApi.basename(repoRoot)),
+	);
+}
+
+/**
+ * Directory that holds this repository's launch worktrees.
+ *
+ * A relative override resolves against the repository's PARENT directory, matching the
+ * default's own shape, so `{repo}.worktrees` adopts an existing sibling bucket and
+ * `.worktrees` parks a hidden bucket beside the repository. An absolute override is used verbatim.
+ */
+function resolveWorktreeBucket(repoRoot: string): string {
+	return resolveWorktreeBucketForPath(repoRoot, process.env[WORKTREE_BUCKET_ENV], os.homedir(), path);
+}
+
 function resolveSourceBranchSlug(repoRoot: string, baseRef: string): string {
 	const branch = tryRunGit(repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
 	if (branch) return sanitizePathToken(branch);
@@ -322,9 +377,8 @@ export function planLaunchWorktree(
 	const baseRef = runGit(repoRoot, ["rev-parse", "HEAD"]);
 	const branchName = mode.detached ? null : mode.name;
 	if (branchName) validateBranchName(repoRoot, branchName);
-	const bucket = `${path.basename(repoRoot)}.gajae-code-worktrees`;
 	const worktreeSlug = mode.detached ? resolveSourceBranchSlug(repoRoot, baseRef) : sanitizePathToken(mode.name);
-	const worktreePath = path.join(path.dirname(repoRoot), bucket, worktreeSlug);
+	const worktreePath = path.join(resolveWorktreeBucket(repoRoot), worktreeSlug);
 	return { enabled: true, repoRoot, worktreePath, detached: mode.detached, baseRef, branchName };
 }
 

package/src/gjc-runtime/linux-proc.ts

@@ -12,6 +12,7 @@ import * as nodeFsSync from "node:fs";
 import * as nodeFs from "node:fs/promises";
 
 export interface LinuxProcStatIdentity {
+	state?: string;
 	startTime: string;
 	ttyDevice: string;
 }
@@ -40,7 +41,7 @@ function parseLinuxProcIdentity(stat: string | null | undefined): LinuxProcStatI
 	const ttyDevice = fields[4];
 	const startTime = fields[19];
 	if (!ttyDevice || !/^-?\d+$/.test(ttyDevice) || !/^\d+$/.test(startTime)) return null;
-	return { startTime, ttyDevice };
+	return { state: fields[0], startTime, ttyDevice };
 }
 
 function classifyProcReadError(error: unknown): Extract<LinuxProcPidProbeResult, { kind: "absent" | "unverifiable" }> {
@@ -60,6 +61,11 @@ export function parseLinuxProcTtyDevice(stat: string | null | undefined): string
 	return parseLinuxProcIdentity(stat)?.ttyDevice ?? null;
 }
 
+/** Parse field 3 (single-letter process state) from a `/proc/<pid>/stat` record. */
+export function parseLinuxProcState(stat: string | null | undefined): string | null {
+	return parseLinuxProcIdentity(stat)?.state ?? null;
+}
+
 export function probeLinuxProcPidSync(pid: number): LinuxProcPidProbeResult {
 	if (!Number.isSafeInteger(pid) || pid <= 0) return { kind: "unverifiable", reason: "invalid_pid" };
 	if (process.platform !== "linux") return { kind: "unverifiable", reason: "unsupported_platform" };

package/src/gjc-runtime/ralplan-runtime.ts

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import type { Dirent } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getConfigRootDir } from "@gajae-code/utils";
+import { isSettingsInitialized, Settings } from "../config/settings";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
@@ -43,6 +43,12 @@ import {
 import { probeGjcTeamAvailability } from "./team-runtime";
 import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
 import { getSkillManifest } from "./workflow-manifest";
+import {
+	resolveWorkflowSetting,
+	WorkflowSettingError,
+	type WorkflowSettingKey,
+	type WorkflowSettingParseResult,
+} from "./workflow-settings";
 /**
  * Native implementation of `gjc ralplan`.
  *
@@ -387,38 +393,69 @@ function parseMaxIterationsValue(value: unknown): number | null {
 	return parseBoundedPositiveInteger(value, RALPLAN_MAX_ITERATIONS_LIMIT);
 }
 
-async function readSettingsMaxIterations(settingsPath: string): Promise<number | null> {
+/** Adapt a nullable parser to the shared resolver's parse-result shape. */
+function workflowSettingParse<T>(
+	parse: (value: unknown) => T | null,
+	reason: string,
+): (value: unknown) => WorkflowSettingParseResult<T> {
+	return value => {
+		const parsed = parse(value);
+		return parsed === null ? { kind: "invalid", reason } : { kind: "valid", value: parsed };
+	};
+}
+
+/**
+ * Resolve a strict ralplan setting through the shared five-layer resolver.
+ * Malformed/invalid explicit sources in any layer/format fail closed (exit 2)
+ * and never fall through to a lower layer or the built-in default.
+ */
+async function resolveStrictRalplanSetting<T>(
+	cwd: string,
+	key: WorkflowSettingKey,
+	parse: (value: unknown) => WorkflowSettingParseResult<T>,
+	defaultValue: T,
+	agentDir?: string,
+): Promise<{ value: T; source: string }> {
 	try {
-		const raw = await Bun.file(settingsPath).text();
-		const parsed = JSON.parse(raw) as Record<string, unknown>;
-		const flat = parseMaxIterationsValue(parsed["gjc.ralplan.maxIterations"]);
-		if (flat !== null) return flat;
-		const gjc = parsed.gjc;
-		if (gjc && typeof gjc === "object") {
-			const ralplan = (gjc as Record<string, unknown>).ralplan;
-			if (ralplan && typeof ralplan === "object") {
-				return parseMaxIterationsValue((ralplan as Record<string, unknown>).maxIterations);
-			}
+		const resolution = await resolveWorkflowSetting(cwd, key, {
+			defaultValue,
+			parse,
+			invalidPolicy: "throw",
+			// The session's effective agent profile: an SDK session created with
+			// `createAgentSession({ agentDir })` resolves against that directory
+			// instead of the process-global default.
+			agentDir: agentDir ?? (isSettingsInitialized() ? Settings.instance.getAgentDir() : undefined),
+		});
+		return { value: resolution.value, source: resolution.source };
+	} catch (error) {
+		if (error instanceof WorkflowSettingError) {
+			throw new RalplanCommandError(2, `invalid ralplan settings at ${error.path}: ${error.reason}`);
 		}
-		return null;
-	} catch {
-		return null;
+		throw error;
 	}
 }
 
 /**
- * Resolve ralplan consensus iteration cap. Project `./.gjc/settings.json` overrides
- * user settings, else default 5.
+ * Resolve the ralplan consensus iteration cap through the shared resolver.
+ * Project `.gjc/config.yml` and `.gjc/settings.json` beat user layers.
  */
-export async function resolveRalplanMaxIterations(cwd: string): Promise<{ maxIterations: number; source: string }> {
-	const projectPath = path.join(gjcRoot(cwd), "settings.json");
-	const project = await readSettingsMaxIterations(projectPath);
-	if (project !== null) return { maxIterations: project, source: projectPath };
-	const userPath = path.join(getConfigRootDir(), "settings.json");
-	const user = await readSettingsMaxIterations(userPath);
-	if (user !== null) return { maxIterations: user, source: userPath };
-	return { maxIterations: RALPLAN_DEFAULT_MAX_ITERATIONS, source: "default" };
+export async function resolveRalplanMaxIterations(
+	cwd: string,
+	agentDir?: string,
+): Promise<{ maxIterations: number; source: string }> {
+	const { value, source } = await resolveStrictRalplanSetting(
+		cwd,
+		"gjc.ralplan.maxIterations",
+		workflowSettingParse(
+			parseMaxIterationsValue,
+			`expected gjc.ralplan.maxIterations to be an integer between 1 and ${RALPLAN_MAX_ITERATIONS_LIMIT}`,
+		),
+		RALPLAN_DEFAULT_MAX_ITERATIONS,
+		agentDir,
+	);
+	return { maxIterations: value, source };
 }
+
 function parseRalplanAutoHandoffTarget(value: unknown): RalplanAutoHandoffTarget | undefined {
 	return typeof value === "string" && RALPLAN_AUTO_HANDOFF_TARGETS.has(value as RalplanAutoHandoffTarget)
 		? (value as RalplanAutoHandoffTarget)
@@ -428,83 +465,29 @@ function parseRalplanAutoHandoffTarget(value: unknown): RalplanAutoHandoffTarget
 type RalplanAutoHandoffOptions = {
 	planningStuck?: boolean;
 	teamAvailabilityProbe?: () => { available: true } | { available: false; reason: string };
+	/** The session's effective agent directory (see resolveWorkflowSetting). */
+	agentDir?: string;
 };
 
-type RalplanAutoHandoffSetting =
-	| { kind: "absent" }
-	| { kind: "valid"; value: RalplanAutoHandoffTarget }
-	| { kind: "invalid"; reason: string };
-
-function parsePresentRalplanAutoHandoff(value: unknown): RalplanAutoHandoffSetting {
+function parsePresentRalplanAutoHandoff(value: unknown): WorkflowSettingParseResult<RalplanAutoHandoffTarget> {
 	const target = parseRalplanAutoHandoffTarget(value);
 	return target === undefined
-		? {
-				kind: "invalid",
-				reason: "expected gjc.ralplan.autoHandoff to be one of off, ultragoal, team",
-			}
+		? { kind: "invalid", reason: "expected gjc.ralplan.autoHandoff to be one of off, ultragoal, team" }
 		: { kind: "valid", value: target };
 }
 
-function parseRalplanAutoHandoffSettings(parsed: unknown): RalplanAutoHandoffSetting {
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "absent" };
-	const settings = parsed as Record<string, unknown>;
-	if (Object.hasOwn(settings, "gjc.ralplan.autoHandoff")) {
-		return parsePresentRalplanAutoHandoff(settings["gjc.ralplan.autoHandoff"]);
-	}
-	const gjc = settings.gjc;
-	if (!gjc || typeof gjc !== "object" || Array.isArray(gjc)) return { kind: "absent" };
-	const ralplan = (gjc as Record<string, unknown>).ralplan;
-	if (!ralplan || typeof ralplan !== "object" || Array.isArray(ralplan)) return { kind: "absent" };
-	const ralplanSettings = ralplan as Record<string, unknown>;
-	if (!Object.hasOwn(ralplanSettings, "autoHandoff")) return { kind: "absent" };
-	return parsePresentRalplanAutoHandoff(ralplanSettings.autoHandoff);
-}
-
-async function readSettingsAutoHandoff(settingsPath: string): Promise<RalplanAutoHandoffSetting> {
-	let raw: string;
-	try {
-		raw = await Bun.file(settingsPath).text();
-	} catch (error) {
-		if (getErrorCode(error) === "ENOENT") return { kind: "absent" };
-		return {
-			kind: "invalid",
-			reason: `unable to read settings: ${error instanceof Error ? error.message : String(error)}`,
-		};
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		return {
-			kind: "invalid",
-			reason: `malformed JSON: ${error instanceof Error ? error.message : String(error)}`,
-		};
-	}
-	return parseRalplanAutoHandoffSettings(parsed);
-}
-
 export async function resolveRalplanAutoHandoff(
 	cwd: string,
 	options: RalplanAutoHandoffOptions = {},
 ): Promise<RalplanAutoHandoffResolution> {
-	const projectPath = path.join(gjcRoot(cwd), "settings.json");
-	const project = await readSettingsAutoHandoff(projectPath);
-	if (project.kind === "invalid") {
-		throw new RalplanCommandError(2, `invalid ralplan settings at ${projectPath}: ${project.reason}`);
-	}
-	if (project.kind === "valid") {
-		return resolveRalplanAutoHandoffTarget(project.value, projectPath, options);
-	}
-	const userPath = path.join(getConfigRootDir(), "settings.json");
-	const user = await readSettingsAutoHandoff(userPath);
-	if (user.kind === "invalid") {
-		throw new RalplanCommandError(2, `invalid ralplan settings at ${userPath}: ${user.reason}`);
-	}
-	return resolveRalplanAutoHandoffTarget(
-		user.kind === "valid" ? user.value : "off",
-		user.kind === "valid" ? userPath : "default",
-		options,
+	const { value, source } = await resolveStrictRalplanSetting(
+		cwd,
+		"gjc.ralplan.autoHandoff",
+		parsePresentRalplanAutoHandoff,
+		"off",
+		options.agentDir,
 	);
+	return resolveRalplanAutoHandoffTarget(value, source, options);
 }
 
 function resolveRalplanAutoHandoffTarget(
@@ -533,78 +516,22 @@ function parseMaxReviewPassesPerLaneValue(value: unknown): number | null {
 	return parseBoundedPositiveInteger(value, RALPLAN_MAX_REVIEW_PASSES_PER_LANE_LIMIT);
 }
 
-type RalplanReviewPassesPerLaneSetting =
-	| { kind: "absent" }
-	| { kind: "valid"; value: number }
-	| { kind: "invalid"; reason: string };
-
-function parsePresentMaxReviewPassesPerLane(value: unknown): RalplanReviewPassesPerLaneSetting {
-	const parsed = parseMaxReviewPassesPerLaneValue(value);
-	return parsed === null
-		? {
-				kind: "invalid",
-				reason:
-					"expected gjc.ralplan.maxReviewPassesPerLane to be an integer between 1 and " +
-					RALPLAN_MAX_REVIEW_PASSES_PER_LANE_LIMIT,
-			}
-		: { kind: "valid", value: parsed };
-}
-
-function parseMaxReviewPassesPerLaneSettings(parsed: unknown): RalplanReviewPassesPerLaneSetting {
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "absent" };
-	const settings = parsed as Record<string, unknown>;
-	if (Object.hasOwn(settings, "gjc.ralplan.maxReviewPassesPerLane")) {
-		return parsePresentMaxReviewPassesPerLane(settings["gjc.ralplan.maxReviewPassesPerLane"]);
-	}
-	const gjc = settings.gjc;
-	if (!gjc || typeof gjc !== "object" || Array.isArray(gjc)) return { kind: "absent" };
-	const ralplan = (gjc as Record<string, unknown>).ralplan;
-	if (!ralplan || typeof ralplan !== "object" || Array.isArray(ralplan)) return { kind: "absent" };
-	const ralplanSettings = ralplan as Record<string, unknown>;
-	if (!Object.hasOwn(ralplanSettings, "maxReviewPassesPerLane")) return { kind: "absent" };
-	return parsePresentMaxReviewPassesPerLane(ralplanSettings.maxReviewPassesPerLane);
-}
-
-async function readSettingsMaxReviewPassesPerLane(settingsPath: string): Promise<RalplanReviewPassesPerLaneSetting> {
-	let raw: string;
-	try {
-		raw = await Bun.file(settingsPath).text();
-	} catch (error) {
-		if (getErrorCode(error) === "ENOENT") return { kind: "absent" };
-		return {
-			kind: "invalid",
-			reason: `unable to read settings: ${error instanceof Error ? error.message : String(error)}`,
-		};
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		return {
-			kind: "invalid",
-			reason: `malformed JSON: ${error instanceof Error ? error.message : String(error)}`,
-		};
-	}
-	return parseMaxReviewPassesPerLaneSettings(parsed);
-}
-
-/** Resolve the per-lane review-pass budget with project-over-user precedence. */
+/** Resolve the per-lane review-pass budget through the shared resolver. */
 export async function resolveRalplanMaxReviewPassesPerLane(
 	cwd: string,
+	agentDir?: string,
 ): Promise<{ maxReviewPassesPerLane: number; source: string }> {
-	const projectPath = path.join(gjcRoot(cwd), "settings.json");
-	const project = await readSettingsMaxReviewPassesPerLane(projectPath);
-	if (project.kind === "invalid") {
-		throw new RalplanCommandError(2, `invalid ralplan settings at ${projectPath}: ${project.reason}`);
-	}
-	if (project.kind === "valid") return { maxReviewPassesPerLane: project.value, source: projectPath };
-	const userPath = path.join(getConfigRootDir(), "settings.json");
-	const user = await readSettingsMaxReviewPassesPerLane(userPath);
-	if (user.kind === "invalid") {
-		throw new RalplanCommandError(2, `invalid ralplan settings at ${userPath}: ${user.reason}`);
-	}
-	if (user.kind === "valid") return { maxReviewPassesPerLane: user.value, source: userPath };
-	return { maxReviewPassesPerLane: RALPLAN_DEFAULT_MAX_REVIEW_PASSES_PER_LANE, source: "default" };
+	const { value, source } = await resolveStrictRalplanSetting(
+		cwd,
+		"gjc.ralplan.maxReviewPassesPerLane",
+		workflowSettingParse(
+			parseMaxReviewPassesPerLaneValue,
+			`expected gjc.ralplan.maxReviewPassesPerLane to be an integer between 1 and ${RALPLAN_MAX_REVIEW_PASSES_PER_LANE_LIMIT}`,
+		),
+		RALPLAN_DEFAULT_MAX_REVIEW_PASSES_PER_LANE,
+		agentDir,
+	);
+	return { maxReviewPassesPerLane: value, source };
 }
 
 function buildPlanningStuckResult(input: {
@@ -1915,7 +1842,11 @@ function buildIndexedReviewArtifacts(indexText: string | undefined): Map<string,
 	return map;
 }
 
-async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
+async function handleArtifactWrite(
+	args: readonly string[],
+	cwd: string,
+	agentDir?: string,
+): Promise<RalplanCommandResult> {
 	const resolved = await resolveArtifactArgs(args, cwd);
 	const persistedRoleState = parsePersistedRoleStateArgs(args, resolved.stage);
 	const laneVerdict = parseLaneVerdictArgs(args, resolved.stage, resolved.stageN);
@@ -2019,8 +1950,8 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	const [onDiskOpeners, onDiskLaneArtifacts, iterationLimit, laneLimit] = await Promise.all([
 		countRalplanOnDiskOpeners(cwd, resolved.sessionId, resolved.runId),
 		countRalplanOnDiskLaneArtifacts(cwd, resolved.sessionId, resolved.runId),
-		resolveRalplanMaxIterations(cwd),
-		resolveRalplanMaxReviewPassesPerLane(cwd),
+		resolveRalplanMaxIterations(cwd, agentDir),
+		resolveRalplanMaxReviewPassesPerLane(cwd, agentDir),
 	]);
 	const capDecision = evaluateRalplanIterationCap({
 		rows: indexLoad.rows,
@@ -2063,6 +1994,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		// state write. The ledger row below is the durable receipt for deduplicated
 		// retries; state is only a current-session projection.
 		autoHandoff = await resolveRalplanAutoHandoff(cwd, {
+			agentDir,
 			planningStuck: await readRalplanPlanningStuck(cwd, resolved.sessionId, resolved.runId),
 		});
 	}
@@ -2340,10 +2272,14 @@ async function handleDoctor(args: readonly string[], cwd: string): Promise<Ralpl
 
 /* -------------------------------- entry --------------------------------- */
 
-export async function runNativeRalplanCommand(args: string[], cwd = process.cwd()): Promise<RalplanCommandResult> {
+export async function runNativeRalplanCommand(
+	args: string[],
+	cwd = process.cwd(),
+	options: { agentDir?: string } = {},
+): Promise<RalplanCommandResult> {
 	try {
 		if (isRalplanDoctorInvocation(args)) return await handleDoctor(args, cwd);
-		if (isRalplanArtifactWriteInvocation(args)) return await handleArtifactWrite(args, cwd);
+		if (isRalplanArtifactWriteInvocation(args)) return await handleArtifactWrite(args, cwd, options.agentDir);
 		return await handleConsensusHandoff(args, cwd);
 	} catch (error) {
 		if (error instanceof CommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };