@gajae-code/coding-agent 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-28
+
+### Added
+
+- Added scoped GJC tmux profile handling for `gjc --tmux` and `gjc team` sessions without mutating global tmux configuration.
+- Added GJC team integration hardening for worker turn-end integration requests, auto-rebase/auto-merge conflict surfacing, protected checkpoint classification, and leader/worker-visible integration summaries.
+- Added Node 20 release baseline validation to the release/check surface.
+
+### Changed
+
+- Clarified the public workflow contract so `deep-interview` and `ralplan` are invoked through `/skill:<name>`, while `gjc ultragoal` and `gjc team` remain native runtime commands.
+- Updated the README hero image and Discord community invite.
+
+### Fixed
+
+- Restored Ultragoal completion receipt export/generation validation and completion gates.
+- Fixed workflow bridge guidance and tests so private compatibility bridge commands are not advertised as public skill-loading paths.
+
 ## [0.1.3] - 2026-05-28
 
 ### Changed

package/dist/types/commands/gjc-runtime-bridge.d.ts

@@ -1,6 +1,30 @@
+import { type WorkflowHudSummary } from "../skill-state/active-state";
+export declare const WORKFLOW_HUD_PROTOCOL = "workflow-hud-summary-v1";
 export interface GjcRuntimeBridgeResult {
     status: number;
     error?: string;
 }
+export interface WorkflowHudBridgePayload {
+    version: 1;
+    skill: string;
+    phase?: string;
+    active?: boolean;
+    session_id?: string;
+    thread_id?: string;
+    turn_id?: string;
+    hud: WorkflowHudSummary;
+}
+export interface GjcRuntimeHudBridgeResult extends GjcRuntimeBridgeResult {
+    hudPayload?: WorkflowHudBridgePayload;
+}
+export interface GjcRuntimeHudBridgeOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    sidecarSkill: string;
+    onHudPayload?: (payload: WorkflowHudBridgePayload) => Promise<void> | void;
+    pollIntervalMs?: number;
+}
+export declare function normalizeWorkflowHudBridgePayload(raw: unknown, expectedSkill: string): WorkflowHudBridgePayload | null;
 export declare function runGjcRuntimeBridge(endpoint: string, args: string[], env?: NodeJS.ProcessEnv): GjcRuntimeBridgeResult;
+export declare function runGjcRuntimeBridgeWithHudSidecar(endpoint: string, args: string[], options: GjcRuntimeHudBridgeOptions): Promise<GjcRuntimeHudBridgeResult>;
 export declare function runBridgedRuntimeEndpoint(endpoint: string, args: string[]): Promise<void>;

package/dist/types/gjc-runtime/launch-tmux.d.ts

@@ -3,6 +3,8 @@ export declare const GJC_DEFAULT_TMUX_SESSION = "gajae_code";
 export declare const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
 export declare const GJC_LAUNCH_POLICY_ENV = "GJC_LAUNCH_POLICY";
 export declare const GJC_TMUX_COMMAND_ENV = "GJC_TMUX_COMMAND";
+export declare const GJC_TMUX_PROFILE_ENV = "GJC_TMUX_PROFILE";
+export declare const GJC_TMUX_MOUSE_ENV = "GJC_MOUSE";
 interface TtyState {
     stdin: boolean;
     stdout: boolean;
@@ -40,6 +42,27 @@ export interface TmuxLaunchPlan {
     newSessionArgs: string[];
     attachSessionArgs: string[];
 }
+export interface GjcTmuxProfileCommand {
+    description: string;
+    args: string[];
+}
+export interface GjcTmuxProfileResult {
+    skipped: boolean;
+    commands: GjcTmuxProfileCommand[];
+    failures: Array<{
+        command: GjcTmuxProfileCommand;
+        stderr?: string;
+    }>;
+}
+export interface GjcTmuxProfileContext {
+    tmuxCommand: string;
+    target: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    spawnSync?: TmuxSpawnSync;
+}
+export declare function buildGjcTmuxProfileCommands(target: string, env?: NodeJS.ProcessEnv): GjcTmuxProfileCommand[];
+export declare function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProfileResult;
 export declare function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaunchPlan | undefined;
 export declare function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean;
 export {};

package/dist/types/gjc-runtime/team-runtime.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowHudSummary } from "../skill-state/active-state";
 export type GjcTeamPhase = "starting" | "running" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
 export type GjcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
@@ -143,7 +144,7 @@ export interface GjcTeamMailboxMessage {
 export declare function resolveGjcTeamWorkerCli(env?: NodeJS.ProcessEnv): GjcTeamWorkerCli;
 export declare function resolveGjcTeamWorkerCliPlan(workerCount: number, env?: NodeJS.ProcessEnv): GjcTeamWorkerCli[];
 export declare function translateGjcWorkerLaunchArgsForCli(workerCli: GjcTeamWorkerCli, args: string[]): string[];
-interface GjcTeamEvent {
+export interface GjcTeamEvent {
     event_id: string;
     ts: string;
     type: string;
@@ -164,12 +165,45 @@ interface WorkerHeartbeatFile {
     turn_count: number;
     alive: boolean;
 }
+export interface GjcWorkerIntegrationAttemptRequestResult {
+    requested: boolean;
+    reason: "requested" | "not_worker" | "missing_worktree" | "no_changes" | "deduped" | "git_error";
+    worker?: string;
+    team_name?: string;
+    fingerprint?: string;
+    head?: string | null;
+    status?: GjcWorkerCheckpointClassification["kind"];
+}
 export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "read-worker-heartbeat", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
 export declare function resolveGjcTeamStateRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
 export declare function resolveGjcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv): string;
+export type GjcWorkerCheckpointClassification = {
+    kind: "clean";
+    files: string[];
+} | {
+    kind: "eligible";
+    files: string[];
+} | {
+    kind: "protected_only";
+    files: string[];
+} | {
+    kind: "conflicted";
+    files: string[];
+} | {
+    kind: "git_error";
+    files: string[];
+    detail: string;
+};
+export declare function classifyGjcTeamCheckpointFiles(files: string[]): {
+    eligible: string[];
+    protected: string[];
+};
+export declare function classifyWorkerCheckpointStatus(cwd: string): GjcWorkerCheckpointClassification;
 export declare function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTeamSnapshot>;
 export declare function readGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
+export declare function requestGjcWorkerIntegrationAttempt(cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcWorkerIntegrationAttemptRequestResult>;
+export declare function buildTeamHudSummary(snapshot: GjcTeamSnapshot, latestEvent?: GjcTeamEvent, latestMessage?: GjcTeamMailboxMessage): Promise<WorkflowHudSummary>;
 export declare function monitorGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
 export declare function listGjcTeams(cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot[]>;
 export declare function shutdownGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;

package/dist/types/gjc-runtime/ultragoal-runtime.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowHudSummary } from "../skill-state/active-state";
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
 export interface UltragoalGoal {
@@ -34,6 +35,7 @@ export interface UltragoalCompletionVerification {
     gjcGoalMode: UltragoalGjcGoalMode;
     gjcObjective: string;
     qualityGateHash: string;
+    gjcGoalSnapshotHash: string;
     planGeneration: string;
     basis: {
         planHashBeforeCheckpoint: string;
@@ -77,8 +79,21 @@ interface JsonObject {
 export declare function hashStructuredValue(value: unknown): string;
 export declare function getUltragoalPaths(cwd: string): UltragoalPaths;
 export declare function readUltragoalLedger(cwd: string): Promise<UltragoalLedgerEvent[]>;
+export declare function computeUltragoalPlanGeneration(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receiptKind: UltragoalReceiptKind;
+    beforeStatus: UltragoalGoalStatus;
+    excludeEventId?: string;
+    targetGoalUpdatedAt?: string;
+}): {
+    planGeneration: string;
+    basis: UltragoalCompletionVerification["basis"];
+};
 export declare function readUltragoalPlan(cwd: string): Promise<UltragoalPlan | null>;
 export declare function getUltragoalStatus(cwd: string): Promise<UltragoalStatusSummary>;
+export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
 export declare function createUltragoalPlan(input: {
     cwd: string;
     brief: string;
@@ -92,16 +107,6 @@ export declare function startNextUltragoalGoal(input: {
     goal?: UltragoalGoal;
     allComplete: boolean;
 }>;
-export declare function computeUltragoalPlanGeneration(input: {
-    plan: UltragoalPlan;
-    ledger: readonly UltragoalLedgerEvent[];
-    goal: UltragoalGoal;
-    receiptKind: UltragoalReceiptKind;
-    beforeStatus: UltragoalGoalStatus;
-    excludeEventId?: string;
-}): UltragoalCompletionVerification["basis"] & {
-    planGeneration: string;
-};
 export declare function checkpointUltragoalGoal(input: {
     cwd: string;
     goalId: string;

package/dist/types/hooks/skill-state.d.ts

@@ -1,4 +1,5 @@
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
+import type { SkillActiveEntry as CanonicalSkillActiveEntry, WorkflowHudSummary } from "../skill-state/active-state";
 import { type GjcWorkflowSkill } from "./skill-keywords";
 export declare const GJC_STATE_DIR = ".gjc/state";
 export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
@@ -13,7 +14,7 @@ export interface SkillKeywordMatch {
     skill: GjcWorkflowSkill;
     priority: number;
 }
-export interface SkillActiveEntry {
+export interface SkillActiveEntry extends Omit<CanonicalSkillActiveEntry, "skill"> {
     skill: GjcWorkflowSkill;
     phase?: string;
     active?: boolean;
@@ -22,6 +23,8 @@ export interface SkillActiveEntry {
     session_id?: string;
     thread_id?: string;
     turn_id?: string;
+    hud?: WorkflowHudSummary;
+    stale?: boolean;
 }
 export interface SkillActiveState {
     version: number;

package/dist/types/skill-state/active-state.d.ts

@@ -2,6 +2,21 @@ export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
 export declare const SKILL_ACTIVE_STALE_MS: number;
 export declare const CANONICAL_GJC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
 export type CanonicalGjcWorkflowSkill = (typeof CANONICAL_GJC_WORKFLOW_SKILLS)[number];
+export type WorkflowHudSeverity = "info" | "warning" | "blocked" | "error" | "success";
+export interface WorkflowHudChip {
+    label: string;
+    value?: string;
+    priority?: number;
+    severity?: WorkflowHudSeverity;
+}
+export interface WorkflowHudSummary {
+    version: 1;
+    summary?: string;
+    chips?: WorkflowHudChip[];
+    details?: WorkflowHudChip[];
+    severity?: WorkflowHudSeverity;
+    updated_at?: string;
+}
 export interface SkillActiveEntry {
     skill: string;
     phase?: string;
@@ -11,6 +26,8 @@ export interface SkillActiveEntry {
     session_id?: string;
     thread_id?: string;
     turn_id?: string;
+    hud?: WorkflowHudSummary;
+    stale?: boolean;
 }
 export interface SkillActiveState {
     version?: number;
@@ -41,7 +58,9 @@ export interface SyncSkillActiveStateOptions {
     turnId?: string;
     nowIso?: string;
     source?: string;
+    hud?: WorkflowHudSummary;
 }
+export declare function normalizeWorkflowHudSummary(raw: unknown): WorkflowHudSummary | undefined;
 export declare function isCanonicalGjcWorkflowSkill(skill: string): skill is CanonicalGjcWorkflowSkill;
 export declare function listActiveSkills(raw: unknown): SkillActiveEntry[];
 export declare function normalizeSkillActiveState(raw: unknown): SkillActiveState | null;

package/dist/types/skill-state/workflow-hud.d.ts

@@ -0,0 +1,62 @@
+import type { WorkflowHudSummary } from "./active-state";
+interface DeepInterviewHudState {
+    phase?: string;
+    ambiguity?: number;
+    threshold?: number;
+    roundCount?: number;
+    targetComponent?: string;
+    weakestDimension?: string;
+    specStatus?: string;
+    updatedAt?: string;
+}
+interface RalplanHudState {
+    stage?: string;
+    waiting?: string;
+    iteration?: number;
+    verdict?: string;
+    latestSummary?: string;
+    pendingApproval?: boolean;
+    updatedAt?: string;
+}
+interface UltragoalLikeGoal {
+    id: string;
+    title: string;
+    status: string;
+}
+interface UltragoalHudState {
+    status: string;
+    currentGoal?: UltragoalLikeGoal;
+    counts: Record<string, number>;
+    goals: UltragoalLikeGoal[];
+    latestLedgerEvent?: {
+        event?: string;
+        goalId?: string;
+        timestamp?: string;
+    };
+    updatedAt?: string;
+}
+interface TeamHudWorker {
+    id: string;
+    status?: string;
+}
+interface TeamHudState {
+    phase: string;
+    task_total: number;
+    task_counts: Record<string, number>;
+    workers: TeamHudWorker[];
+    updated_at?: string;
+    latestEvent?: {
+        type?: string;
+        worker?: string;
+        message?: string;
+    };
+    latestMessage?: {
+        from_worker?: string;
+        body?: string;
+    };
+}
+export declare function buildDeepInterviewHudSummary(state: DeepInterviewHudState): WorkflowHudSummary;
+export declare function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSummary;
+export declare function buildUltragoalHudSummary(state: UltragoalHudState): WorkflowHudSummary;
+export declare function buildTeamHudSummary(state: TeamHudState): WorkflowHudSummary;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.1.3",
+	"version": "0.2.0",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -48,12 +48,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.1.3",
-		"@gajae-code/agent-core": "0.1.3",
-		"@gajae-code/ai": "0.1.3",
-		"@gajae-code/natives": "0.1.3",
-		"@gajae-code/tui": "0.1.3",
-		"@gajae-code/utils": "0.1.3",
+		"@gajae-code/stats": "0.2.0",
+		"@gajae-code/agent-core": "0.2.0",
+		"@gajae-code/ai": "0.2.0",
+		"@gajae-code/natives": "0.2.0",
+		"@gajae-code/tui": "0.2.0",
+		"@gajae-code/utils": "0.2.0",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/commands/deep-interview.ts

@@ -1,5 +1,6 @@
 import { Command } from "@gajae-code/utils/cli";
-import { runBridgedRuntimeEndpoint } from "./gjc-runtime-bridge";
+import { syncSkillActiveState } from "../skill-state/active-state";
+import { runGjcRuntimeBridgeWithHudSidecar } from "./gjc-runtime-bridge";
 
 export default class DeepInterview extends Command {
 	static description = "Run private GJC deep-interview workflow commands";
@@ -7,6 +8,24 @@ export default class DeepInterview extends Command {
 	static examples = ["$ gjc deep-interview --help"];
 
 	async run(): Promise<void> {
-		await runBridgedRuntimeEndpoint("deep-interview", this.argv);
+		const cwd = process.cwd();
+		const result = await runGjcRuntimeBridgeWithHudSidecar("deep-interview", this.argv, {
+			cwd,
+			sidecarSkill: "deep-interview",
+			onHudPayload: payload =>
+				syncSkillActiveState({
+					cwd,
+					skill: "deep-interview",
+					active: payload.active ?? true,
+					phase: payload.phase,
+					sessionId: payload.session_id,
+					threadId: payload.thread_id,
+					turnId: payload.turn_id,
+					hud: payload.hud,
+					source: "gjc-runtime-bridge",
+				}),
+		});
+		if (result.error) process.stderr.write(`${result.error}\n`);
+		process.exitCode = result.status;
 	}
 }

package/src/commands/gjc-runtime-bridge.ts

@@ -1,15 +1,46 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { normalizeWorkflowHudSummary, type WorkflowHudSummary } from "../skill-state/active-state";
 
 const BRIDGE_ENV = "GJC_RUNTIME_BINARY";
 const LEGACY_BRIDGE_ENV = "GJC_LEGACY_RUNTIME_BINARY";
 const GUARD_ENV = "GJC_RUNTIME_BRIDGE_ACTIVE";
+export const WORKFLOW_HUD_PROTOCOL = "workflow-hud-summary-v1";
 
 export interface GjcRuntimeBridgeResult {
 	status: number;
 	error?: string;
 }
 
+const SKILL_ENTRYPOINT_ENDPOINTS = new Set(["deep-interview", "ralplan"]);
+
+export interface WorkflowHudBridgePayload {
+	version: 1;
+	skill: string;
+	phase?: string;
+	active?: boolean;
+	session_id?: string;
+	thread_id?: string;
+	turn_id?: string;
+	hud: WorkflowHudSummary;
+}
+
+export interface GjcRuntimeHudBridgeResult extends GjcRuntimeBridgeResult {
+	hudPayload?: WorkflowHudBridgePayload;
+}
+
+export interface GjcRuntimeHudBridgeOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	sidecarSkill: string;
+	onHudPayload?: (payload: WorkflowHudBridgePayload) => Promise<void> | void;
+	pollIntervalMs?: number;
+}
+
 function candidateBinaries(env: NodeJS.ProcessEnv): string[] {
 	return [env[BRIDGE_ENV], env[LEGACY_BRIDGE_ENV]].filter(
 		(value): value is string => typeof value === "string" && value.trim().length > 0,
@@ -24,6 +55,61 @@ function canAttempt(command: string): boolean {
 	return !isPathLike(command) || existsSync(command);
 }
 
+function unavailableBridgeResult(
+	endpoint: string,
+	env: NodeJS.ProcessEnv,
+	attempted: string[],
+): GjcRuntimeBridgeResult {
+	const configured = [env[BRIDGE_ENV], env[LEGACY_BRIDGE_ENV]].filter(Boolean).join(", ");
+	const guidance = SKILL_ENTRYPOINT_ENDPOINTS.has(endpoint)
+		? `Inside a GJC agent session, invoke /skill:${endpoint} instead so the bundled skill is loaded directly.`
+		: `Configure ${BRIDGE_ENV} with a GJC-compatible private runtime binary for the ${endpoint} endpoint.`;
+	return {
+		status: 1,
+		error: [
+			`gjc ${endpoint} is a private runtime bridge command.`,
+			guidance,
+			`Only private runtime deployments should call this bridge command; configure them with ${BRIDGE_ENV}.`,
+			configured
+				? `Configured runtime candidates failed: ${configured}.`
+				: "No private GJC runtime binary was configured.",
+			attempted.length > 0 ? `Attempted: ${attempted.join(", ")}.` : undefined,
+		]
+			.filter(Boolean)
+			.join("\n"),
+	};
+}
+
+export function normalizeWorkflowHudBridgePayload(
+	raw: unknown,
+	expectedSkill: string,
+): WorkflowHudBridgePayload | null {
+	if (!raw || typeof raw !== "object") return null;
+	const record = raw as Record<string, unknown>;
+	if (record.version !== 1 || record.skill !== expectedSkill) return null;
+	const hud = normalizeWorkflowHudSummary(record.hud);
+	if (!hud) return null;
+	return {
+		version: 1,
+		skill: expectedSkill,
+		phase: typeof record.phase === "string" && record.phase.trim() ? record.phase.trim() : undefined,
+		active: typeof record.active === "boolean" ? record.active : undefined,
+		session_id:
+			typeof record.session_id === "string" && record.session_id.trim() ? record.session_id.trim() : undefined,
+		thread_id: typeof record.thread_id === "string" && record.thread_id.trim() ? record.thread_id.trim() : undefined,
+		turn_id: typeof record.turn_id === "string" && record.turn_id.trim() ? record.turn_id.trim() : undefined,
+		hud,
+	};
+}
+
+async function readHudPayload(sidecarPath: string, expectedSkill: string): Promise<WorkflowHudBridgePayload | null> {
+	try {
+		return normalizeWorkflowHudBridgePayload(JSON.parse(await Bun.file(sidecarPath).text()), expectedSkill);
+	} catch {
+		return null;
+	}
+}
+
 export function runGjcRuntimeBridge(
 	endpoint: string,
 	args: string[],
@@ -58,20 +144,80 @@ export function runGjcRuntimeBridge(
 		return { status: child.status ?? (child.signal ? 1 : 0) };
 	}
 
-	const configured = [env[BRIDGE_ENV], env[LEGACY_BRIDGE_ENV]].filter(Boolean).join(", ");
-	return {
-		status: 1,
-		error: [
-			`gjc ${endpoint} requires the private GJC runtime endpoint implementation.`,
-			`Set ${BRIDGE_ENV} to a GJC-compatible runtime binary.`,
-			configured
-				? `Configured runtime candidates failed: ${configured}.`
-				: "No gjc runtime binary was found on PATH.",
-			attempted.length > 0 ? `Attempted: ${attempted.join(", ")}.` : undefined,
-		]
-			.filter(Boolean)
-			.join("\n"),
-	};
+	return unavailableBridgeResult(endpoint, env, attempted);
+}
+
+export async function runGjcRuntimeBridgeWithHudSidecar(
+	endpoint: string,
+	args: string[],
+	options: GjcRuntimeHudBridgeOptions,
+): Promise<GjcRuntimeHudBridgeResult> {
+	const env = options.env ?? process.env;
+	if (env[GUARD_ENV] === "1") return { status: 1, error: `Refusing recursive gjc runtime bridge for ${endpoint}.` };
+
+	const attempted: string[] = [];
+	for (const binary of candidateBinaries(env)) {
+		const command = binary.trim();
+		if (!canAttempt(command)) continue;
+		attempted.push(command);
+		const sidecarDir = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-workflow-hud-"));
+		const sidecarPath = path.join(sidecarDir, `${options.sidecarSkill}-${randomUUID()}.json`);
+		let latestPayload: WorkflowHudBridgePayload | undefined;
+		let lastRaw = "";
+		const publishPayload = async (): Promise<void> => {
+			let raw = "";
+			try {
+				raw = await Bun.file(sidecarPath).text();
+			} catch {
+				return;
+			}
+			if (!raw || raw === lastRaw) return;
+			lastRaw = raw;
+			const payload = await readHudPayload(sidecarPath, options.sidecarSkill);
+			if (!payload) return;
+			latestPayload = payload;
+			try {
+				await options.onHudPayload?.(payload);
+			} catch {
+				// HUD sidecar sync is best-effort and must not change child command semantics.
+			}
+		};
+		try {
+			const child = spawn(command, [endpoint, ...args], {
+				cwd: options.cwd,
+				stdio: "inherit",
+				env: {
+					...env,
+					[GUARD_ENV]: "1",
+					GJC_WORKFLOW_HUD_PROTOCOL: WORKFLOW_HUD_PROTOCOL,
+					GJC_WORKFLOW_HUD_SIDECAR: sidecarPath,
+					GJC_WORKFLOW_HUD_SKILL: options.sidecarSkill,
+				},
+			});
+			const interval = setInterval(() => {
+				void publishPayload();
+			}, options.pollIntervalMs ?? 100);
+			const exit = Promise.withResolvers<{ status: number; error?: string; code?: string }>();
+			child.on("error", error => {
+				const fsError = error as NodeJS.ErrnoException;
+				exit.resolve({ status: 1, error: error.message, code: fsError.code });
+			});
+			child.on("exit", (code, signal) => exit.resolve({ status: code ?? (signal ? 1 : 0) }));
+			const result = await exit.promise;
+			clearInterval(interval);
+			await publishPayload();
+			if (result.code === "ENOENT") continue;
+			return {
+				status: result.status,
+				...(result.error ? { error: result.error } : {}),
+				...(latestPayload ? { hudPayload: latestPayload } : {}),
+			};
+		} finally {
+			await fs.rm(sidecarDir, { recursive: true, force: true });
+		}
+	}
+
+	return unavailableBridgeResult(endpoint, env, attempted);
 }
 
 export async function runBridgedRuntimeEndpoint(endpoint: string, args: string[]): Promise<void> {

package/src/commands/ralplan.ts

@@ -1,5 +1,6 @@
 import { Command } from "@gajae-code/utils/cli";
-import { runBridgedRuntimeEndpoint } from "./gjc-runtime-bridge";
+import { syncSkillActiveState } from "../skill-state/active-state";
+import { runGjcRuntimeBridgeWithHudSidecar } from "./gjc-runtime-bridge";
 
 export default class Ralplan extends Command {
 	static description = "Run private GJC RALPLAN workflow commands";
@@ -7,6 +8,24 @@ export default class Ralplan extends Command {
 	static examples = ["$ gjc ralplan --help"];
 
 	async run(): Promise<void> {
-		await runBridgedRuntimeEndpoint("ralplan", this.argv);
+		const cwd = process.cwd();
+		const result = await runGjcRuntimeBridgeWithHudSidecar("ralplan", this.argv, {
+			cwd,
+			sidecarSkill: "ralplan",
+			onHudPayload: payload =>
+				syncSkillActiveState({
+					cwd,
+					skill: "ralplan",
+					active: payload.active ?? true,
+					phase: payload.phase,
+					sessionId: payload.session_id,
+					threadId: payload.thread_id,
+					turnId: payload.turn_id,
+					hud: payload.hud,
+					source: "gjc-runtime-bridge",
+				}),
+		});
+		if (result.error) process.stderr.write(`${result.error}\n`);
+		process.exitCode = result.status;
 	}
 }