@gajae-code/coding-agent 0.2.1 → 0.2.3

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

@@ -1,12 +1,30 @@
 import * as path from "node:path";
 import type { Args } from "../cli/args";
+import {
+	buildGjcTmuxProfileCommands,
+	buildGjcTmuxSessionName,
+	buildGjcTmuxSessionSlug,
+	GJC_DEFAULT_TMUX_SESSION,
+	GJC_TMUX_COMMAND_ENV,
+	GJC_TMUX_MOUSE_ENV,
+	GJC_TMUX_PROFILE_ENV,
+	GJC_TMUX_SESSION_PREFIX,
+	type GjcTmuxProfileCommand,
+	resolveGjcTmuxCommand,
+} from "./tmux-common";
+import { findGjcTmuxSessionByBranch } from "./tmux-sessions";
+
+export {
+	buildGjcTmuxProfileCommands,
+	GJC_DEFAULT_TMUX_SESSION,
+	GJC_TMUX_COMMAND_ENV,
+	GJC_TMUX_MOUSE_ENV,
+	GJC_TMUX_PROFILE_ENV,
+	GJC_TMUX_SESSION_PREFIX,
+};
 
-export const GJC_DEFAULT_TMUX_SESSION = "gajae_code";
 export const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
 export const GJC_LAUNCH_POLICY_ENV = "GJC_LAUNCH_POLICY";
-export const GJC_TMUX_COMMAND_ENV = "GJC_TMUX_COMMAND";
-export const GJC_TMUX_PROFILE_ENV = "GJC_TMUX_PROFILE";
-export const GJC_TMUX_MOUSE_ENV = "GJC_MOUSE";
 
 type LaunchPolicy = "direct" | "tmux";
 
@@ -26,6 +44,10 @@ export interface TmuxLaunchContext {
 	tty?: TtyState;
 	spawnSync?: TmuxSpawnSync;
 	tmuxAvailable?: boolean;
+	worktreeBranch?: string | null;
+	currentBranch?: string | null;
+	existingBranchSessionName?: string | null;
+	project?: string | null;
 }
 
 export interface TmuxSpawnResult {
@@ -50,12 +72,9 @@ export interface TmuxLaunchPlan {
 	cwd: string;
 	innerCommand: string;
 	newSessionArgs: string[];
-	attachSessionArgs: string[];
-}
-
-export interface GjcTmuxProfileCommand {
-	description: string;
-	args: string[];
+	branch?: string | null;
+	attachSessionName?: string;
+	project?: string | null;
 }
 
 export interface GjcTmuxProfileResult {
@@ -70,6 +89,9 @@ export interface GjcTmuxProfileContext {
 	cwd?: string;
 	env?: NodeJS.ProcessEnv;
 	spawnSync?: TmuxSpawnSync;
+	branch?: string | null;
+	branchSlug?: string | null;
+	project?: string | null;
 }
 
 interface CommandResolutionContext {
@@ -103,35 +125,14 @@ function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-function envDisabled(value: string | undefined): boolean {
-	const normalized = value?.trim().toLowerCase();
-	return normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no";
-}
-
-export function buildGjcTmuxProfileCommands(
-	target: string,
-	env: NodeJS.ProcessEnv = process.env,
-): GjcTmuxProfileCommand[] {
-	if (envDisabled(env[GJC_TMUX_PROFILE_ENV])) return [];
-	const commands: GjcTmuxProfileCommand[] = [
-		{ description: "mark GJC tmux ownership", args: ["set-option", "-t", target, "@gjc-profile", "1"] },
-		{ description: "enable tmux clipboard integration", args: ["set-option", "-t", target, "set-clipboard", "on"] },
-		{
-			description: "make copy-mode selection readable",
-			args: ["set-window-option", "-t", target, "mode-style", "fg=colour231,bg=colour60"],
-		},
-	];
-	if (!envDisabled(env[GJC_TMUX_MOUSE_ENV]))
-		commands.unshift({
-			description: "enable tmux mouse scrolling",
-			args: ["set-option", "-t", target, "mouse", "on"],
-		});
-	return commands;
-}
-
 export function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProfileResult {
 	const env = context.env ?? process.env;
-	const commands = buildGjcTmuxProfileCommands(context.target, env);
+	const branchSlug = context.branch ? buildGjcTmuxSessionSlug(context.branch) : (context.branchSlug ?? null);
+	const commands = buildGjcTmuxProfileCommands(context.target, env, {
+		branch: context.branch ?? null,
+		branchSlug,
+		project: context.project ?? null,
+	});
 	if (commands.length === 0) return { skipped: true, commands: [], failures: [] };
 	const spawnSync = context.spawnSync ?? defaultSpawnSync;
 	const cwd = context.cwd ?? process.cwd();
@@ -160,6 +161,25 @@ function buildInnerCommand(context: CommandResolutionContext, rawArgs: string[])
 	return `exec env ${GJC_TMUX_LAUNCHED_ENV}=1 ${quoted}`;
 }
 
+function readCurrentBranch(cwd: string): string | null {
+	try {
+		const result = Bun.spawnSync(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (result.exitCode !== 0) return null;
+		const branch = result.stdout.toString().trim();
+		return branch || null;
+	} catch {
+		return null;
+	}
+}
+
+function cleanupCreatedTmuxSession(plan: TmuxLaunchPlan, spawnSync: TmuxSpawnSync, options: TmuxSpawnOptions): void {
+	spawnSync(plan.tmuxCommand, ["kill-session", "-t", `=${plan.sessionName}`], options);
+}
+
 export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaunchPlan | undefined {
 	const env = context.env ?? process.env;
 	const policy = parseLaunchPolicy(env);
@@ -171,10 +191,18 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	if (policy === "tmux" && !isInteractiveRootLaunch(context.parsed, tty)) return undefined;
 
 	const cwd = context.cwd ?? process.cwd();
-	const sessionName = env.GJC_TMUX_SESSION?.trim() || GJC_DEFAULT_TMUX_SESSION;
-	const tmuxCommand = env[GJC_TMUX_COMMAND_ENV]?.trim() || "tmux";
+	const branch = context.worktreeBranch ?? context.currentBranch ?? readCurrentBranch(cwd);
+	const project = context.project ?? cwd;
+	const sessionName = buildGjcTmuxSessionName(env, { branch });
+	const tmuxCommand = resolveGjcTmuxCommand(env);
 	const tmuxAvailable = context.tmuxAvailable ?? Bun.which(tmuxCommand) !== null;
 	if (!tmuxAvailable) return undefined;
+	const existingBranchSessionName =
+		"existingBranchSessionName" in context
+			? (context.existingBranchSessionName ?? undefined)
+			: context.worktreeBranch
+				? findGjcTmuxSessionByBranch(context.worktreeBranch, env, project)?.name
+				: undefined;
 	const innerCommand = buildInnerCommand(
 		{
 			cwd,
@@ -189,7 +217,9 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 		cwd,
 		innerCommand,
 		newSessionArgs: ["new-session", "-d", "-s", sessionName, "-c", cwd, innerCommand],
-		attachSessionArgs: ["attach-session", "-t", sessionName],
+		branch,
+		project,
+		attachSessionName: existingBranchSessionName,
 	};
 }
 
@@ -217,17 +247,27 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		stdout: "inherit",
 		stderr: "inherit",
 	};
+	if (plan.attachSessionName) {
+		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
+		return attached.exitCode === 0;
+	}
 	const created = spawnSync(plan.tmuxCommand, plan.newSessionArgs, options);
 	if (created.exitCode === 0) {
-		applyGjcTmuxProfile({
+		const profile = applyGjcTmuxProfile({
 			tmuxCommand: plan.tmuxCommand,
 			target: plan.sessionName,
 			cwd: plan.cwd,
 			env,
 			spawnSync,
+			branch: plan.branch,
+			project: plan.project,
 		});
+		if (profile.failures.length > 0) {
+			cleanupCreatedTmuxSession(plan, spawnSync, options);
+			return false;
+		}
 	}
-	const attached = spawnSync(plan.tmuxCommand, plan.attachSessionArgs, options);
-	if (created.exitCode === 0) return attached.exitCode === 0;
+	if (created.exitCode !== 0) return false;
+	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
 	return attached.exitCode === 0;
 }

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

@@ -0,0 +1,460 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { syncSkillActiveState } from "../skill-state/active-state";
+import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
+
+/**
+ * Native implementation of `gjc ralplan`.
+ *
+ * Two invocation shapes are handled natively:
+ *
+ * 1. **Consensus handoff**: `gjc ralplan [--interactive] [--deliberate] [--architect <kind>]
+ *    [--critic <kind>] [--session-id <id>] "<task>"` validates the documented flag surface,
+ *    seeds `.gjc/state/ralplan-state.json`, and updates the shared HUD rail via
+ *    `syncSkillActiveState`. The CLI never *runs* the Planner / Architect / Critic loop itself —
+ *    that lives in the bundled `/skill:ralplan` skill — but it accepts every documented flag so
+ *    scripted users see a useful response and the active run is visible to the TUI.
+ *
+ * 2. **Artifact write**: `gjc ralplan --write --stage <type> --stage_n <N> --artifact
+ *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
+ *    / Critic / revision / ADR / final markdown under `.gjc/plans/ralplan/<run-id>/`, maintains
+ *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
+ *    the HUD chip to reflect the latest persisted stage.
+ */
+
+export interface RalplanCommandResult {
+	status: number;
+	stdout?: string;
+	stderr?: string;
+}
+
+const KNOWN_STAGES = ["planner", "architect", "critic", "revision", "adr", "final"] as const;
+type RalplanStage = (typeof KNOWN_STAGES)[number];
+
+const KNOWN_ARCHITECT_KINDS = new Set(["openai-code"]);
+const KNOWN_CRITIC_KINDS = new Set(["openai-code"]);
+
+const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+
+class RalplanCommandError extends Error {
+	constructor(
+		public readonly exitStatus: number,
+		message: string,
+	) {
+		super(message);
+		this.name = "RalplanCommandError";
+	}
+}
+
+const VALUE_FLAGS = new Set([
+	"--stage",
+	"--stage_n",
+	"--artifact",
+	"--run-id",
+	"--session-id",
+	"--architect",
+	"--critic",
+]);
+
+function flagValue(args: readonly string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	if (index < 0) return undefined;
+	return args[index + 1];
+}
+
+function hasFlag(args: readonly string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+export function isRalplanArtifactWriteInvocation(args: readonly string[]): boolean {
+	return hasFlag(args, "--write");
+}
+
+function assertSafePathComponent(value: string, label: string): void {
+	if (!PATH_COMPONENT_RE.test(value) || value.includes("..")) {
+		throw new RalplanCommandError(2, `invalid path component for --${label}: ${value}`);
+	}
+}
+
+function assertKnownStage(stage: string): asserts stage is RalplanStage {
+	if (!(KNOWN_STAGES as readonly string[]).includes(stage)) {
+		throw new RalplanCommandError(2, `unknown --stage: ${stage}. Expected one of: ${KNOWN_STAGES.join(", ")}.`);
+	}
+}
+
+function parseStageN(raw: string | undefined): number {
+	if (!raw) throw new RalplanCommandError(2, "--stage_n is required");
+	if (!/^[1-9][0-9]{0,2}$/.test(raw)) {
+		throw new RalplanCommandError(2, `invalid --stage_n: ${raw}. Expected integer 1..999.`);
+	}
+	const value = Number.parseInt(raw, 10);
+	if (value < 1 || value > 999) {
+		throw new RalplanCommandError(2, `invalid --stage_n: ${raw}. Expected integer 1..999.`);
+	}
+	return value;
+}
+
+function pad2(value: number): string {
+	return value.toString().padStart(2, "0");
+}
+
+function defaultRunId(now: Date = new Date()): string {
+	const yyyy = now.getUTCFullYear().toString().padStart(4, "0");
+	const mm = (now.getUTCMonth() + 1).toString().padStart(2, "0");
+	const dd = now.getUTCDate().toString().padStart(2, "0");
+	const hh = now.getUTCHours().toString().padStart(2, "0");
+	const min = now.getUTCMinutes().toString().padStart(2, "0");
+	const suffix = randomBytes(2).toString("hex");
+	return `${yyyy}-${mm}-${dd}-${hh}${min}-${suffix}`;
+}
+
+async function resolveArtifactContent(rawArtifact: string, cwd: string): Promise<string> {
+	const candidate = path.isAbsolute(rawArtifact) ? rawArtifact : path.resolve(cwd, rawArtifact);
+	try {
+		const stat = await fs.stat(candidate);
+		if (stat.isFile()) return await fs.readFile(candidate, "utf-8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code !== "ENOENT" && err.code !== "ENOTDIR") {
+			throw new RalplanCommandError(2, `failed to read --artifact ${candidate}: ${err.message}`);
+		}
+	}
+	return rawArtifact;
+}
+
+/* ------------------------------ artifact write ------------------------------ */
+
+interface ResolvedArtifactArgs {
+	stage: RalplanStage;
+	stageN: number;
+	runId: string;
+	artifact: string;
+	sessionId: string | undefined;
+	json: boolean;
+}
+
+function ralplanStatePath(cwd: string, sessionId: string | undefined): string {
+	const stateDir = sessionId
+		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(sessionId))
+		: path.join(cwd, ".gjc", "state");
+	return path.join(stateDir, "ralplan-state.json");
+}
+
+async function readActiveRunId(cwd: string, sessionId: string | undefined): Promise<string | undefined> {
+	try {
+		const raw = await fs.readFile(ralplanStatePath(cwd, sessionId), "utf-8");
+		const parsed = JSON.parse(raw) as { run_id?: unknown };
+		const candidate = typeof parsed.run_id === "string" ? parsed.run_id.trim() : "";
+		if (!candidate) return undefined;
+		assertSafePathComponent(candidate, "run-id");
+		return candidate;
+	} catch {
+		return undefined;
+	}
+}
+
+async function persistActiveRunId(cwd: string, sessionId: string | undefined, runId: string): Promise<void> {
+	const statePath = ralplanStatePath(cwd, sessionId);
+	let existing: Record<string, unknown> = {};
+	try {
+		const raw = await fs.readFile(statePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			existing = parsed as Record<string, unknown>;
+		}
+	} catch {
+		// fresh receipt; fall through to create
+	}
+	if (existing.run_id === runId) return;
+	existing.run_id = runId;
+	if (typeof existing.skill !== "string") existing.skill = "ralplan";
+	if (typeof existing.active !== "boolean") existing.active = true;
+	existing.updated_at = new Date().toISOString();
+	await fs.mkdir(path.dirname(statePath), { recursive: true });
+	await fs.writeFile(statePath, `${JSON.stringify(existing, null, 2)}\n`);
+}
+
+async function resolveArtifactArgs(args: readonly string[], cwd: string): Promise<ResolvedArtifactArgs> {
+	const stage = flagValue(args, "--stage");
+	if (!stage) throw new RalplanCommandError(2, "--stage is required for ralplan --write");
+	assertKnownStage(stage);
+
+	const stageN = parseStageN(flagValue(args, "--stage_n"));
+
+	const rawArtifact = flagValue(args, "--artifact");
+	if (rawArtifact === undefined || rawArtifact === "") {
+		throw new RalplanCommandError(2, "--artifact is required for ralplan --write");
+	}
+
+	const sessionIdRaw = flagValue(args, "--session-id")?.trim();
+	const sessionId = sessionIdRaw || undefined;
+	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+
+	// Precedence for run_id:
+	//   1. explicit --run-id flag
+	//   2. existing run_id field in .gjc/state[/sessions/<id>]/ralplan-state.json
+	//   3. explicit --session-id flag (use as run id)
+	//   4. freshly generated default run id
+	const explicitRunId = flagValue(args, "--run-id")?.trim();
+	const runId = explicitRunId || (await readActiveRunId(cwd, sessionId)) || sessionIdRaw || defaultRunId();
+	assertSafePathComponent(runId, "run-id");
+	// Persist the active run id so later writes in the same loop land in the same directory.
+	await persistActiveRunId(cwd, sessionId, runId);
+
+	const artifact = await resolveArtifactContent(rawArtifact, cwd);
+	return { stage: stage as RalplanStage, stageN, runId, artifact, sessionId, json: hasFlag(args, "--json") };
+}
+
+interface PersistedArtifact {
+	runId: string;
+	path: string;
+	stage: RalplanStage;
+	stageN: number;
+	sha256: string;
+	createdAt: string;
+	pendingApprovalPath?: string;
+}
+
+async function persistArtifact(resolved: ResolvedArtifactArgs, cwd: string): Promise<PersistedArtifact> {
+	const runDir = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId);
+	await fs.mkdir(runDir, { recursive: true });
+	const fileName = `stage-${pad2(resolved.stageN)}-${resolved.stage}.md`;
+	const filePath = path.join(runDir, fileName);
+	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
+	await fs.writeFile(filePath, content);
+
+	const sha256 = createHash("sha256").update(content).digest("hex");
+	const createdAt = new Date().toISOString();
+	const indexLine = `${JSON.stringify({
+		stage: resolved.stage,
+		stage_n: resolved.stageN,
+		path: filePath,
+		created_at: createdAt,
+		sha256,
+	})}\n`;
+	await fs.appendFile(path.join(runDir, "index.jsonl"), indexLine);
+
+	let pendingApprovalPath: string | undefined;
+	if (resolved.stage === "final") {
+		pendingApprovalPath = path.join(runDir, "pending-approval.md");
+		await fs.writeFile(pendingApprovalPath, content);
+	}
+
+	return {
+		runId: resolved.runId,
+		path: filePath,
+		stage: resolved.stage,
+		stageN: resolved.stageN,
+		sha256,
+		createdAt,
+		pendingApprovalPath,
+	};
+}
+
+async function syncRalplanHud(options: {
+	cwd: string;
+	sessionId?: string;
+	stage: string;
+	pendingApproval: boolean;
+	iteration?: number;
+	latestSummary?: string;
+}): Promise<void> {
+	try {
+		await syncSkillActiveState({
+			cwd: options.cwd,
+			skill: "ralplan",
+			active: !options.pendingApproval || options.stage === "final",
+			phase: options.stage,
+			sessionId: options.sessionId,
+			source: "gjc-ralplan-native",
+			hud: buildRalplanHudSummary({
+				stage: options.stage,
+				iteration: options.iteration,
+				pendingApproval: options.pendingApproval,
+				latestSummary: options.latestSummary,
+				updatedAt: new Date().toISOString(),
+			}),
+		});
+	} catch {
+		// HUD sync is best-effort and must not change command semantics.
+	}
+}
+
+async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
+	const resolved = await resolveArtifactArgs(args, cwd);
+	const persisted = await persistArtifact(resolved, cwd);
+	await syncRalplanHud({
+		cwd,
+		sessionId: resolved.sessionId,
+		stage: persisted.stage,
+		pendingApproval: persisted.stage === "final",
+		iteration: persisted.stageN,
+		latestSummary: `persisted ${persisted.stage} stage ${persisted.stageN}`,
+	});
+	const payload: Record<string, unknown> = {
+		run_id: persisted.runId,
+		path: persisted.path,
+		stage: persisted.stage,
+		stage_n: persisted.stageN,
+		sha256: persisted.sha256,
+		created_at: persisted.createdAt,
+	};
+	if (persisted.pendingApprovalPath) payload.pending_approval_path = persisted.pendingApprovalPath;
+	const stdout = resolved.json
+		? `${JSON.stringify(payload, null, 2)}\n`
+		: `Persisted ralplan ${persisted.stage} stage ${persisted.stageN} at ${persisted.path}.\n`;
+	return { status: 0, stdout };
+}
+
+/* -------------------------------- handoff -------------------------------- */
+
+interface ConsensusHandoffArgs {
+	interactive: boolean;
+	deliberate: boolean;
+	architectKind?: string;
+	criticKind?: string;
+	sessionId?: string;
+	task: string;
+	json: boolean;
+}
+
+function extractPositionalTask(args: readonly string[]): string {
+	const parts: string[] = [];
+	let skipNext = false;
+	for (const arg of args) {
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (VALUE_FLAGS.has(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (arg === "--interactive" || arg === "--deliberate" || arg === "--write" || arg === "--json") continue;
+		if (arg.startsWith("-")) {
+			throw new RalplanCommandError(2, `unknown flag for gjc ralplan: ${arg}`);
+		}
+		parts.push(arg);
+	}
+	return parts.join(" ").trim();
+}
+
+function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
+	const architectKind = flagValue(args, "--architect")?.trim() || undefined;
+	if (architectKind && !KNOWN_ARCHITECT_KINDS.has(architectKind)) {
+		throw new RalplanCommandError(
+			2,
+			`unknown --architect kind: ${architectKind}. Expected one of: ${[...KNOWN_ARCHITECT_KINDS].join(", ")}.`,
+		);
+	}
+	const criticKind = flagValue(args, "--critic")?.trim() || undefined;
+	if (criticKind && !KNOWN_CRITIC_KINDS.has(criticKind)) {
+		throw new RalplanCommandError(
+			2,
+			`unknown --critic kind: ${criticKind}. Expected one of: ${[...KNOWN_CRITIC_KINDS].join(", ")}.`,
+		);
+	}
+	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
+	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const task = extractPositionalTask(args);
+	return {
+		interactive: hasFlag(args, "--interactive"),
+		deliberate: hasFlag(args, "--deliberate"),
+		architectKind,
+		criticKind,
+		sessionId,
+		task,
+		json: hasFlag(args, "--json"),
+	};
+}
+
+function encodeSessionSegment(value: string): string {
+	return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+
+async function seedRalplanState(
+	cwd: string,
+	resolved: ConsensusHandoffArgs,
+): Promise<{ statePath: string; runId: string }> {
+	const stateDir = resolved.sessionId
+		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
+		: path.join(cwd, ".gjc", "state");
+	await fs.mkdir(stateDir, { recursive: true });
+	const statePath = path.join(stateDir, "ralplan-state.json");
+	// Reuse an existing run id when present so a re-invocation of `gjc ralplan "task"` doesn't
+	// orphan in-progress artifacts under a fresh run id.
+	const existingRunId = await readActiveRunId(cwd, resolved.sessionId);
+	const runId = existingRunId ?? resolved.sessionId ?? defaultRunId();
+	assertSafePathComponent(runId, "run-id");
+	const now = new Date().toISOString();
+	const payload: Record<string, unknown> = {
+		active: true,
+		current_phase: "planner",
+		skill: "ralplan",
+		mode: resolved.deliberate ? "deliberate" : "short",
+		interactive: resolved.interactive,
+		task: resolved.task,
+		run_id: runId,
+		updated_at: now,
+	};
+	if (resolved.architectKind) payload.architect_kind = resolved.architectKind;
+	if (resolved.criticKind) payload.critic_kind = resolved.criticKind;
+	if (resolved.sessionId) payload.session_id = resolved.sessionId;
+	await fs.writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+	return { statePath, runId };
+}
+
+async function handleConsensusHandoff(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
+	const resolved = resolveConsensusArgs(args);
+	if (!resolved.task) {
+		throw new RalplanCommandError(2, 'gjc ralplan requires a task description, e.g. `gjc ralplan "<task>"`.');
+	}
+	const { statePath, runId } = await seedRalplanState(cwd, resolved);
+	const mode = resolved.deliberate ? "deliberate" : "short";
+	await syncRalplanHud({
+		cwd,
+		sessionId: resolved.sessionId,
+		stage: "planner",
+		pendingApproval: false,
+		iteration: 1,
+		latestSummary: `${mode} run · ${resolved.interactive ? "interactive" : "automated"}`,
+	});
+
+	const summary = {
+		skill: "ralplan",
+		mode,
+		interactive: resolved.interactive,
+		architect: resolved.architectKind ?? "default",
+		critic: resolved.criticKind ?? "default",
+		task: resolved.task,
+		state_path: statePath,
+		run_id: runId,
+		handoff: "Run `/skill:ralplan` inside the GJC agent to drive the Planner / Architect / Critic consensus loop.",
+	};
+	const stdout = resolved.json
+		? `${JSON.stringify(summary, null, 2)}\n`
+		: [
+				`Seeded ralplan ${summary.mode} run (${resolved.interactive ? "interactive" : "automated"}) at ${statePath}.`,
+				`Active run_id: ${runId}`,
+				resolved.architectKind ? `Architect: ${resolved.architectKind}` : undefined,
+				resolved.criticKind ? `Critic: ${resolved.criticKind}` : undefined,
+				"Run `/skill:ralplan` inside the GJC agent to execute the consensus loop.",
+				"",
+			]
+				.filter((line): line is string => Boolean(line))
+				.join("\n");
+	return { status: 0, stdout };
+}
+
+/* -------------------------------- entry --------------------------------- */
+
+export async function runNativeRalplanCommand(args: string[], cwd = process.cwd()): Promise<RalplanCommandResult> {
+	try {
+		if (isRalplanArtifactWriteInvocation(args)) return await handleArtifactWrite(args, cwd);
+		return await handleConsensusHandoff(args, cwd);
+	} catch (error) {
+		if (error instanceof RalplanCommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
+		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
+	}
+}