@gajae-code/coding-agent 0.2.0 → 0.2.2

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -11,7 +11,7 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 
 ## Purpose
 
-`ultragoal` turns a brief into repo-native artifacts and then drives a GJC goal safely through the named goal tools: `get_goal`, `create_goal`, and `update_goal`. New plans default to a stable pointer-style aggregate GJC goal for the whole durable plan in `.gjc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while GJC tracks G001/G002 story progress in the ledger. Ultragoal does not call `/goal clear`; before multiple sequential ultragoal runs in one session/thread, manually run `/goal clear` in the UI so the previous completed aggregate goal does not block or confuse the next `create_goal`.
+`ultragoal` turns a brief into repo-native artifacts and then drives a GJC goal safely through the unified `goal` tool. New plans default to a stable pointer-style aggregate GJC goal for the whole durable plan in `.gjc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while GJC tracks G001/G002 story progress in the ledger. Ultragoal does not call `/goal clear`; before multiple sequential ultragoal runs in one session/thread, manually run `/goal clear` in the UI so the previous completed aggregate goal does not block or confuse the next `goal({"op":"create"})`.
 
 - `.gjc/ultragoal/brief.md`
 - `.gjc/ultragoal/goals.json`
@@ -30,21 +30,20 @@ gjc ultragoal create-goals --brief "<brief>"
 gjc ultragoal create-goals --brief-file <path>
 gjc ultragoal complete-goals
 gjc ultragoal complete-goals --retry-failed
-gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
+gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>
 gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
-gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --gjc-goal-json <active-get-goal-json-or-path>
+gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --gjc-goal-json <active-goal-get-json-or-path>
 ```
 
 Use these exact goal-tool calls for the inline goal state:
 
 ```json
-get_goal({})
-create_goal({"objective":"<printed aggregate or per-story objective>"})
-update_goal({"status":"complete"})
+goal({"op":"get"})
+goal({"op":"create","objective":"<printed aggregate or per-story objective>"})
+goal({"op":"complete"})
 ```
 
-`get_goal`, `create_goal`, and `update_goal` share the same session goal state as `/goal`; prefer these named tools inside Ultragoal because they produce JSON snapshots for ledger reconciliation.
-
+The unified `goal` tool shares the same session goal state as `/goal`; use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation.
 
 ## Create goals
 
@@ -61,17 +60,17 @@ Loop until `gjc ultragoal status` reports all goals complete:
 
 1. Run `gjc ultragoal complete-goals`.
 2. Read the printed handoff.
-3. Call `get_goal({})`.
-4. If no active GJC goal exists, call `create_goal({"objective":"<printed payload objective>"})` with the printed payload. In aggregate mode, if the same aggregate objective is already active, continue the current GJC story without creating a new GJC goal.
+3. Call `goal({"op":"get"})`.
+4. If no active GJC goal exists, call `goal({"op":"create","objective":"<printed payload objective>"})` with the printed payload. In aggregate mode, if the same aggregate objective is already active, continue the current GJC story without creating a new GJC goal.
 5. Complete the current GJC story only.
 6. Run a completion audit against the story objective and real artifacts/tests.
-7. Before any `--status complete` checkpoint, run the mandatory final cleanup/review gate below. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint each story with a fresh `get_goal({})` snapshot whose aggregate objective is still `active`. On the final story, use the same fresh active snapshot to create the final aggregate receipt first; only after that receipt exists may `update_goal({"status":"complete"})` run.
+7. Before any `--status complete` checkpoint, run the mandatory final cleanup/review gate below. In aggregate mode, do **not** call `goal({"op":"complete"})` for intermediate stories; checkpoint each story with a fresh `goal({"op":"get"})` snapshot whose aggregate objective is still `active`. On the final story, use the same fresh active snapshot to create the final aggregate receipt first; only after that receipt exists may `goal({"op":"complete"})` run.
 8. Checkpoint the durable ledger with that fresh active snapshot. Complete checkpoints require `--quality-gate-json`; the runtime hook rejects closure without a clean architect review:
-   `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get_goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>`
+   `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>`
 9. If blocked or failed, checkpoint failure:
    `gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
 11. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
-   `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks create_goal in this thread>" --gjc-goal-json <get_goal-json-or-path>`
+   `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks goal create in this thread>" --gjc-goal-json <goal-get-json-or-path>`
 12. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
 
 ## Dynamic steering
@@ -104,7 +103,6 @@ Steering invariants:
 
 UserPromptSubmit uses the same steering API only for structured directives such as `GJC_ULTRAGOAL_STEER: { ... }`, `gjc.ultragoal.steer: { ... }`, or `gjc ultragoal steer: { ... }`. Normal prose does not mutate state, and repeated prompt-submit directives dedupe by prompt signature or idempotency key.
 
-
 ## Role-agent delegation guidance
 
 Ultragoal execution should use GJC's bundled role-agent roster when a durable story is large enough to benefit from delegation:
@@ -126,10 +124,10 @@ For large subgoals with independent slices, the Ultragoal leader must spawn para
 
 Use ultragoal and team together for a durable Ultragoal story that benefits from one visible tmux worker session. Ultragoal remains leader-owned: `.gjc/ultragoal/goals.json` stores the story plan and `.gjc/ultragoal/ledger.jsonl` stores checkpoints. Team is the single-worker tmux execution engine and returns task/evidence status to the leader.
 
-The leader checkpoints Ultragoal from Team evidence with a fresh `get_goal` snapshot:
+The leader checkpoints Ultragoal from Team evidence with a fresh `goal({"op":"get"})` snapshot:
 
 ```sh
-gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .gjc/ultragoal and <id>>" --gjc-goal-json <fresh-get_goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
+gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .gjc/ultragoal and <id>>" --gjc-goal-json <fresh-goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>
 ```
 
 Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Workers must not run `gjc ultragoal checkpoint`; checkpoint authority stays with the leader after worker tasks are terminal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden goal mutation.
@@ -142,7 +140,7 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
 2. Run a cleanup/refactor review pass on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
 3. Rerun verification after the cleaner pass.
 4. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, or non-empty blockers are non-clean.
-5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+5. If review is non-clean, do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
 
 1. Run targeted implementation verification for the story.
 2. Delegate an `architect` review covering all three lanes:
@@ -150,12 +148,12 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - product-side: user-visible behavior, acceptance criteria, edge cases, regressions.
    - code-side: maintainability, tests, integration points, and unsafe shortcuts.
 3. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path.
-4. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `update_goal`. Record durable blocker work instead:
+4. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
    ```sh
-   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<architect/executor findings>" --gjc-goal-json <active-get-goal-json-or-path>
+   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<architect/executor findings>" --gjc-goal-json <active-goal-get-json-or-path>
    ```
 5. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
-6. Only after the loop is clean, checkpoint the story as complete with a structured quality gate and a fresh active `get_goal` snapshot. The checkpoint creates a receipt; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before `update_goal({"status":"complete"})` is allowed.
+6. Only after the loop is clean, checkpoint the story as complete with a structured quality gate and a fresh active `goal({"op":"get"})` snapshot. The checkpoint creates a receipt; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before `goal({"op":"complete"})` is allowed.
 
 The native `checkpoint --status complete` command rejects missing or shallow gates. `--quality-gate-json` must include:
 
@@ -197,10 +195,10 @@ Receipts are freshness-scoped:
 ## Constraints
 
 - The shell command cannot directly invoke interactive `/goal`; it emits a model-facing handoff for the active GJC agent.
-- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; use only the named goal-tool surface: `get_goal`, `create_goal`, and `update_goal`.
+- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; use only the unified goal-tool surface: `goal({"op":"get"})`, `goal({"op":"create"})`, and `goal({"op":"complete"})`.
 - After a completed aggregate ultragoal run, clear the goal manually with `/goal clear` before starting another ultragoal run in the same session/thread.
-- Never call `create_goal` when `get_goal` reports a different active goal.
-- Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
-- In aggregate mode, intermediate and final story checkpoints require a matching `active` GJC goal snapshot; the final story checkpoint creates the final aggregate receipt before `update_goal({"status":"complete"})` may reconcile the inline goal state.
-- Completion checkpoints require read-only goal snapshot reconciliation: pass fresh `get_goal` JSON/path with `--gjc-goal-json`; shell commands and hooks must not mutate goal state.
+- Never call `goal({"op":"create"})` when `goal({"op":"get"})` reports a different active goal.
+- Never call `goal({"op":"complete"})` unless the aggregate run or legacy per-story goal is actually complete.
+- In aggregate mode, intermediate and final story checkpoints require a matching `active` GJC goal snapshot; the final story checkpoint creates the final aggregate receipt before `goal({"op":"complete"})` may reconcile the inline goal state.
+- Completion checkpoints require read-only goal snapshot reconciliation: pass fresh `goal({"op":"get"})` JSON/path with `--gjc-goal-json`; shell commands and hooks must not mutate goal state.
 - Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.

package/src/eval/py/prelude.py

@@ -431,7 +431,7 @@ if "__gjc_prelude_loaded__" not in globals():
             return data.get("value")
 
     class _ToolProxy:
-        """`tool.<name>(args)` proxy mirroring the JS runtime bridge."""
+        """`tool.<name>(args)` proxy mirroring the JS session tool API."""
 
         __slots__ = ("_base", "_token", "_session")
 

package/src/gjc-runtime/deep-interview-runtime.ts

@@ -0,0 +1,279 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { syncSkillActiveState } from "../skill-state/active-state";
+import { buildDeepInterviewHudSummary } from "../skill-state/workflow-hud";
+
+/**
+ * Native implementation of `gjc deep-interview`.
+ *
+ * The CLI itself does not run the Socratic interview; that lives inside the `/skill:deep-interview`
+ * skill executed by the agent. This handler validates the documented argument-hint surface
+ * (`[--quick|--standard|--deep] <idea>`), seeds `.gjc/state/deep-interview-state.json`, and
+ * updates the shared HUD rail via `syncSkillActiveState` so the active interview is visible to
+ * the TUI.
+ */
+
+export interface DeepInterviewCommandResult {
+	status: number;
+	stdout?: string;
+	stderr?: string;
+}
+
+const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+
+const DEFAULT_AMBIGUITY_THRESHOLD = 0.05;
+
+const RESOLUTION_THRESHOLDS = {
+	quick: 0.6,
+	standard: 0.5,
+	deep: 0.35,
+} as const;
+
+type DeepInterviewResolution = keyof typeof RESOLUTION_THRESHOLDS;
+
+class DeepInterviewCommandError extends Error {
+	constructor(
+		public readonly exitStatus: number,
+		message: string,
+	) {
+		super(message);
+		this.name = "DeepInterviewCommandError";
+	}
+}
+
+const VALUE_FLAGS = new Set(["--session-id", "--threshold", "--threshold-source"]);
+
+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);
+}
+
+function assertSafePathComponent(value: string, label: string): void {
+	if (!PATH_COMPONENT_RE.test(value) || value.includes("..")) {
+		throw new DeepInterviewCommandError(2, `invalid path component for --${label}: ${value}`);
+	}
+}
+
+function encodeSessionSegment(value: string): string {
+	return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+
+interface ResolvedDeepInterviewArgs {
+	resolution: DeepInterviewResolution;
+	threshold: number;
+	thresholdSource: string;
+	sessionId?: string;
+	idea: string;
+	json: boolean;
+}
+
+async function readSettingsAmbiguityThreshold(
+	settingsPath: string,
+): Promise<{ threshold: number; source: string } | undefined> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(settingsPath, "utf-8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return undefined;
+		return undefined;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	const candidate = (parsed as { gjc?: { deepInterview?: { ambiguityThreshold?: unknown } } })?.gjc?.deepInterview
+		?.ambiguityThreshold;
+	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1) {
+		return undefined;
+	}
+	return { threshold: candidate, source: settingsPath };
+}
+
+async function resolveConfiguredAmbiguityThreshold(
+	cwd: string,
+): Promise<{ threshold: number; source: string } | undefined> {
+	const projectSettings = path.join(cwd, ".gjc", "settings.json");
+	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
+	if (projectValue) return projectValue;
+	const configDir = process.env.GJC_CONFIG_DIR?.trim() || path.join(os.homedir(), ".gjc");
+	const userSettings = path.join(configDir, "settings.json");
+	return await readSettingsAmbiguityThreshold(userSettings);
+}
+
+async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): Promise<ResolvedDeepInterviewArgs> {
+	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
+	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+
+	const explicitResolutions = (["quick", "standard", "deep"] as const).filter(name => hasFlag(args, `--${name}`));
+	if (explicitResolutions.length > 1) {
+		throw new DeepInterviewCommandError(2, "pass at most one of --quick, --standard, --deep");
+	}
+	const resolution: DeepInterviewResolution | undefined = explicitResolutions[0];
+
+	// Precedence: --threshold > settings.json (project then user) > resolution flag default > 0.05.
+	let threshold: number = DEFAULT_AMBIGUITY_THRESHOLD;
+	let thresholdSource = "default";
+	const thresholdOverride = flagValue(args, "--threshold");
+	if (thresholdOverride !== undefined) {
+		const parsed = Number(thresholdOverride);
+		if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+			throw new DeepInterviewCommandError(
+				2,
+				`invalid --threshold: ${thresholdOverride}. Expected 0 < threshold <= 1.`,
+			);
+		}
+		threshold = parsed;
+		thresholdSource = flagValue(args, "--threshold-source")?.trim() || "flag:--threshold";
+	} else {
+		const configured = await resolveConfiguredAmbiguityThreshold(cwd);
+		if (configured) {
+			threshold = configured.threshold;
+			thresholdSource = configured.source;
+		} else if (resolution) {
+			threshold = RESOLUTION_THRESHOLDS[resolution];
+			thresholdSource = `flag:--${resolution}`;
+		}
+	}
+
+	const ideaParts: string[] = [];
+	let skipNext = false;
+	for (const arg of args) {
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (VALUE_FLAGS.has(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (arg === "--quick" || arg === "--standard" || arg === "--deep" || arg === "--json") continue;
+		if (arg.startsWith("-")) {
+			throw new DeepInterviewCommandError(2, `unknown flag for gjc deep-interview: ${arg}`);
+		}
+		ideaParts.push(arg);
+	}
+	const idea = ideaParts.join(" ").trim();
+	const effectiveResolution: DeepInterviewResolution = resolution ?? "standard";
+	return {
+		resolution: effectiveResolution,
+		threshold,
+		thresholdSource,
+		sessionId,
+		idea,
+		json: hasFlag(args, "--json"),
+	};
+}
+
+async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepInterviewArgs): Promise<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, "deep-interview-state.json");
+	const now = new Date().toISOString();
+	const payload: Record<string, unknown> = {
+		active: true,
+		current_phase: "interviewing",
+		skill: "deep-interview",
+		resolution: resolved.resolution,
+		threshold: resolved.threshold,
+		threshold_source: resolved.thresholdSource,
+		state: {
+			initial_idea: resolved.idea,
+			rounds: [],
+			current_ambiguity: 1.0,
+			threshold: resolved.threshold,
+			threshold_source: resolved.thresholdSource,
+		},
+		updated_at: now,
+	};
+	if (resolved.sessionId) payload.session_id = resolved.sessionId;
+	await fs.writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+	return statePath;
+}
+
+async function syncDeepInterviewHud(options: {
+	cwd: string;
+	sessionId?: string;
+	phase: string;
+	ambiguity?: number;
+	threshold?: number;
+	roundCount?: number;
+	specStatus?: string;
+}): Promise<void> {
+	try {
+		await syncSkillActiveState({
+			cwd: options.cwd,
+			skill: "deep-interview",
+			active: options.phase !== "complete",
+			phase: options.phase,
+			sessionId: options.sessionId,
+			source: "gjc-deep-interview-native",
+			hud: buildDeepInterviewHudSummary({
+				phase: options.phase,
+				ambiguity: options.ambiguity,
+				threshold: options.threshold,
+				roundCount: options.roundCount,
+				specStatus: options.specStatus,
+				updatedAt: new Date().toISOString(),
+			}),
+		});
+	} catch {
+		// HUD sync is best-effort and must not change command semantics.
+	}
+}
+
+export async function runNativeDeepInterviewCommand(
+	args: string[],
+	cwd = process.cwd(),
+): Promise<DeepInterviewCommandResult> {
+	try {
+		const resolved = await resolveDeepInterviewArgs(args, cwd);
+		if (!resolved.idea) {
+			throw new DeepInterviewCommandError(
+				2,
+				'gjc deep-interview requires an idea, e.g. `gjc deep-interview "<idea>"`.',
+			);
+		}
+		const statePath = await seedDeepInterviewState(cwd, resolved);
+		await syncDeepInterviewHud({
+			cwd,
+			sessionId: resolved.sessionId,
+			phase: "interviewing",
+			ambiguity: 1,
+			threshold: resolved.threshold,
+			roundCount: 0,
+		});
+
+		const summary = {
+			skill: "deep-interview",
+			resolution: resolved.resolution,
+			threshold: resolved.threshold,
+			threshold_source: resolved.thresholdSource,
+			idea: resolved.idea,
+			state_path: statePath,
+			handoff: "Run `/skill:deep-interview` inside the GJC agent to drive the Socratic interview loop.",
+		};
+		const stdout = resolved.json
+			? `${JSON.stringify(summary, null, 2)}\n`
+			: [
+					`Seeded deep-interview ${resolved.resolution} run at ${statePath}.`,
+					`Threshold: ${(resolved.threshold * 100).toFixed(0)}% (source: ${resolved.thresholdSource}).`,
+					"Run `/skill:deep-interview` inside the GJC agent to execute the interview.",
+					"",
+				].join("\n");
+		return { status: 0, stdout };
+	} catch (error) {
+		if (error instanceof DeepInterviewCommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
+		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
+	}
+}

package/src/gjc-runtime/goal-mode-request.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Snowflake } from "@gajae-code/utils";
-import type { Goal, GoalModeState } from "../goals/state";
+import { type Goal, type GoalModeState, normalizeGoal } from "../goals/state";
 import {
 	buildSessionContext,
 	loadEntriesFromFile,
@@ -94,24 +94,7 @@ export async function writePendingGoalModeRequest(input: {
 }
 
 function goalFromModeData(modeData: Record<string, unknown> | undefined): Goal | null {
-	const candidate = modeData?.goal;
-	if (typeof candidate !== "object" || candidate === null) return null;
-	const goal = candidate as Partial<Goal>;
-	if (
-		typeof goal.id !== "string" ||
-		typeof goal.objective !== "string" ||
-		typeof goal.status !== "string" ||
-		typeof goal.tokensUsed !== "number" ||
-		typeof goal.timeUsedSeconds !== "number" ||
-		typeof goal.createdAt !== "number" ||
-		typeof goal.updatedAt !== "number"
-	) {
-		return null;
-	}
-	if (!["active", "paused", "budget-limited", "complete", "dropped"].includes(goal.status)) {
-		return null;
-	}
-	return goal as Goal;
+	return normalizeGoal(modeData?.goal);
 }
 
 function isNonTerminalGoal(goal: Goal | null): goal is Goal {

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;
 }