@gajae-code/coding-agent 0.7.3 → 0.7.5

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

@@ -1,3 +1,6 @@
+import type { ResolvedTmuxBinary } from "./psmux-detect";
+import { resolveGjcTmuxBinary } from "./psmux-detect";
+
 export const GJC_DEFAULT_TMUX_SESSION = "gajae_code";
 export const GJC_TMUX_SESSION_PREFIX = `${GJC_DEFAULT_TMUX_SESSION}_`;
 export const GJC_TMUX_COMMAND_ENV = "GJC_TMUX_COMMAND";
@@ -11,6 +14,7 @@ export const GJC_TMUX_PROJECT_OPTION = "@gjc-project";
 export const GJC_TMUX_SESSION_ID_OPTION = "@gjc-session-id";
 export const GJC_TMUX_SESSION_STATE_FILE_OPTION = "@gjc-session-state-file";
 export const GJC_TMUX_VERSION_OPTION = "@gjc-version";
+export const GJC_PSMUX_PROFILE_FORCE_ENV = "GJC_PSMUX_PROFILE_FORCE";
 
 export interface GjcTmuxProfileCommand {
 	description: string;
@@ -31,10 +35,33 @@ export function envDisabled(value: string | undefined): boolean {
 	return normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no";
 }
 
-export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): string {
-	return env[GJC_TMUX_COMMAND_ENV]?.trim() || env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
+/**
+ * Resolve the tmux (or tmux-compatible multiplexer) command GJC should invoke.
+ *
+ * This is the shared entry point used by every GJC code path that needs to talk
+ * to a multiplexer: `gjc --tmux` planning, `gjc session ...`, `gjc team ...`,
+ * the lifecycle controller, and the harness resident owner. Routing all of
+ * them through the same resolver means a single `GJC_TMUX_COMMAND` override or
+ * a single Windows psmux / pmux detection wins for the whole process — the
+ * failure mode where `gjc --tmux` creates a psmux-backed session and then
+ * `gjc session status` fails because it queries literal `tmux` is closed off.
+ *
+ * Explicit `GJC_TMUX_COMMAND` / `GJC_TEAM_TMUX_COMMAND` overrides are honored on
+ * every platform. On native Windows without an override the resolver walks
+ * `psmux`, then `pmux`, then `tmux` and uses the first binary present on PATH.
+ * On POSIX the resolver returns `tmux` (the historical default) and only
+ * falls through to the platform-aware walker if the caller opts in.
+ */
+export function resolveGjcTmuxCommand(
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	return resolveGjcTmuxBinary({ env, platform }).command;
 }
 
+export type { PsmuxProbe, ResolvedTmuxBinary, ResolveGjcTmuxBinaryOptions } from "./psmux-detect";
+export { clearPsmuxDetectionCache, detectPsmux, probePsmux, resolveGjcTmuxBinary } from "./psmux-detect";
+
 /**
  * Build the exact-session target for tmux *option* commands
  * (`show-options` / `set-option`) and `display-message -t`.
@@ -45,7 +72,17 @@ export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): str
  * keeps the exact-session match while giving tmux the window-qualified target
  * those commands require. See gajae-code#580.
  */
-export function buildGjcTmuxExactOptionTarget(sessionName: string): string {
+export function buildGjcTmuxExactOptionTarget(
+	sessionName: string,
+	opts: { env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; binary?: ResolvedTmuxBinary } = {},
+): string {
+	const binary = opts.binary ?? resolveGjcTmuxBinary({ env: opts.env, platform: opts.platform });
+	// psmux 3.3.0 rejects the tmux `=NAME` exact-session prefix for option
+	// commands ("no server running on session '=NAME'"); bare `NAME` and
+	// window-qualified `NAME:` both work. tmux 3.6a needs the
+	// window-qualified `=NAME:` to resolve the session for option
+	// commands (gajae-code#580).
+	if (binary.isPsmux) return sessionName;
 	return `=${sessionName}:`;
 }
 
@@ -146,6 +183,16 @@ export function buildGjcTmuxRequiredProfileCommands(
 	return commands;
 }
 
+/**
+ * Keys whose set-option / set-window-option round-trip is unreliable on psmux
+ * 3.3.0. psmux does not support the tmux `set-window-option` command at all
+ * (it reports "unknown command: set-window-option") and silently drops several
+ * `set-option` keys. The list lives here so every code path that tags a tmux
+ * session (gjc --tmux planning, gjc session create, gjc team bootstrap)
+ * applies the same filter.
+ */
+const PSMUX_UNSUPPORTED_PROFILE_KEYS = new Set(["mouse", "set-clipboard", "mode-style"]);
+
 export function buildGjcTmuxProfileCommands(
 	target: string,
 	env: NodeJS.ProcessEnv = process.env,
@@ -157,6 +204,7 @@ export function buildGjcTmuxProfileCommands(
 		sessionStateFile?: string | null;
 		version?: string | null;
 	} = {},
+	opts: { platform?: NodeJS.Platform; tmuxCommand?: string } = {},
 ): GjcTmuxProfileCommand[] {
 	const commands = buildGjcTmuxRequiredProfileCommands(target, metadata);
 	if (envDisabled(env[GJC_TMUX_PROFILE_ENV])) return commands;
@@ -172,6 +220,40 @@ export function buildGjcTmuxProfileCommands(
 			description: "enable tmux mouse scrolling",
 			args: ["set-option", "-t", target, "mouse", "on"],
 		});
+	// psmux does not implement set-window-option and historically drops
+	// mouse / set-clipboard / mode-style. Filter the UX profile commands
+	// centrally so every code path that tags a session (gjc --tmux planning,
+	// gjc session create, gjc team bootstrap) drops the same set. The
+	// GJC_PSMUX_PROFILE_FORCE override lets the operator opt back in when
+	// running on a psmux build that has caught up. The ownership-tag
+	// round-trip (set-option @gjc-*) is never filtered, since gjc session /
+	// gjc team rely on it.
+	// The filter is opt-in: callers that explicitly pass `opts.tmuxCommand`
+	// name a psmux-class multiplexer (psmux / pmux) when they want the UX
+	// profile filtered. Auto-detect on Windows hosts where psmux happens
+	// to be on PATH would silently change the test output for every caller
+	// that does not pin the multiplexer, so we require the caller to opt
+	// in by naming the multiplexer. GJC_PSMUX_PROFILE_FORCE re-enables
+	// the UX profile commands when a psmux build catches up.
+	const tmuxName = (opts.tmuxCommand ?? "").toLowerCase();
+	const isPsmuxClass =
+		tmuxName === "psmux" ||
+		tmuxName === "pmux" ||
+		tmuxName.endsWith("/psmux") ||
+		tmuxName.endsWith("/pmux") ||
+		tmuxName.endsWith("\\psmux") ||
+		tmuxName.endsWith("\\pmux");
+	const dropUx = isPsmuxClass && !envDisabled(env[GJC_PSMUX_PROFILE_FORCE_ENV]);
+	if (dropUx) {
+		return commands.filter(command => {
+			const flag = command.args[0];
+			const key = command.args[command.args.length - 2];
+			return !(
+				PSMUX_UNSUPPORTED_PROFILE_KEYS.has(String(key)) &&
+				(flag === "set-option" || flag === "set-window-option")
+			);
+		});
+	}
 	return commands;
 }
 

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

@@ -1,3 +1,4 @@
+import { resolveGjcTmuxBinary } from "./psmux-detect";
 import {
 	buildGjcTmuxExactOptionTarget,
 	buildGjcTmuxProfileCommands,
@@ -128,10 +129,29 @@ function runListSessions(format: string, env: NodeJS.ProcessEnv = process.env):
 		}
 		throw error;
 	}
-	return output
+	const lines = output
 		.split("\n")
 		.map(line => line.trim())
 		.filter(Boolean);
+	// psmux 3.3.0 silently ignores the tmux `-F` format flag and returns its
+	// default `name: N windows (created ...)` shape. Detect that case and
+	// synthesize a tab-separated row so downstream parseSessionLine /
+	// hydrateSessionFromExactOptions can recover the @gjc-* ownership tags
+	// via follow-up show-options calls. Without this fallback gjc session
+	// list / status return an empty list on psmux even when sessions exist.
+	if (lines.length > 0 && !lines[0].includes("\t")) {
+		const binary = resolveGjcTmuxBinary({ env });
+		if (binary.isPsmux) {
+			return lines.map(line => {
+				const match = line.match(/^([^:]+):\s*(\d+)\s+windows?\s+\(created\s+([^)]+)\)/);
+				if (!match) return line;
+				const [, name, windows, created] = match;
+				const createdEpoch = String(Math.floor(new Date(`${created} UTC`).getTime() / 1000) || 0);
+				return [name, windows, "0", createdEpoch, "", "", "0", "", "", "", "", "", "", ""].join("\t");
+			});
+		}
+	}
+	return lines;
 }
 
 function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
@@ -221,7 +241,13 @@ export function statusGjcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv
 export function createGjcTmuxSession(env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionStatus {
 	const tmuxCommand = resolveGjcTmuxCommand(env);
 	const sessionName = buildGjcTmuxSessionName(env);
-	const command = "exec env GJC_TMUX_LAUNCHED=1 gjc";
+	// Build a shell-bootstrap command appropriate for the host shell. Psmux on
+	// Windows runs the new-session command through PowerShell, so we use the
+	// $env:VAR = ... assignment form there. POSIX keeps the historical exec
+	// env form so the launched gjc inherits GJC_TMUX_LAUNCHED without leaking
+	// into the parent tmux server.
+	const platform = process.platform;
+	const command = platform === "win32" ? "$env:GJC_TMUX_LAUNCHED = '1'; gjc" : "exec env GJC_TMUX_LAUNCHED=1 gjc";
 	const created = Bun.spawnSync([tmuxCommand, "new-session", "-d", "-s", sessionName, command], {
 		stdout: "pipe",
 		stderr: "pipe",
@@ -229,7 +255,14 @@ export function createGjcTmuxSession(env: NodeJS.ProcessEnv = process.env): GjcT
 	});
 	if (created.exitCode !== 0) throw new Error(created.stderr.toString().trim() || "gjc_tmux_session_create_failed");
 	try {
-		for (const profileCommand of buildGjcTmuxProfileCommands(sessionName, env)) {
+		// psmux 3.3.0 rejects the tmux `=NAME` exact-session prefix for option
+		// commands, so the target is the bare session name on psmux and the
+		// window-qualified `=NAME:` on tmux. The ownership-tag round-trip
+		// (set-option @gjc-*) is preserved on both; only the UX profile commands
+		// (mouse / set-clipboard / mode-style / set-window-option) get filtered
+		// by buildGjcTmuxProfileCommands when the active binary is psmux.
+		const target = buildGjcTmuxExactOptionTarget(sessionName, { env });
+		for (const profileCommand of buildGjcTmuxProfileCommands(target, env, {}, { tmuxCommand })) {
 			runTmux(profileCommand.args, env);
 		}
 	} catch (error) {
@@ -240,18 +273,43 @@ export function createGjcTmuxSession(env: NodeJS.ProcessEnv = process.env): GjcT
 }
 
 function readProfileForExactTarget(sessionName: string, env: NodeJS.ProcessEnv): string {
-	return runTmux(
-		["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), GJC_TMUX_PROFILE_OPTION],
+	const raw = runTmux(
+		["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName, { env }), GJC_TMUX_PROFILE_OPTION],
 		env,
 	).trim();
+	// tmux returns just the value; psmux returns `key value`. Strip the
+	// leading key on psmux so the GJC_TMUX_PROFILE_VALUE equality check
+	// against "1" works the same on both.
+	if (raw && resolveGjcTmuxBinary({ env }).isPsmux) {
+		const tokens = raw.split(/\s+/).filter(Boolean);
+		return tokens[tokens.length - 1] ?? raw;
+	}
+	return raw;
 }
 
 function readExactOptionForGc(sessionName: string, option: string, env: NodeJS.ProcessEnv): string | undefined {
 	try {
-		return (
-			runTmux(["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), option], env).trim() ||
-			undefined
-		);
+		const raw = runTmux(
+			["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName, { env }), option],
+			env,
+		).trim();
+		if (!raw) return undefined;
+		// tmux returns just the option value (e.g. `1` for @gjc-profile).
+		// psmux 3.3.0 returns `key value` (or `key "value with space"` for
+		// @gjc-branch etc.). On psmux, parse the last token and strip any
+		// surrounding double quotes so both shapes resolve to the same value.
+		if (resolveGjcTmuxBinary({ env }).isPsmux) {
+			// Prefer the last whitespace-separated token. If the value is
+			// quoted, find the matching close-quote and slice.
+			const lastQuote = raw.lastIndexOf('"');
+			if (lastQuote > 0 && raw[lastQuote - 1] !== "\\") {
+				const firstQuote = raw.lastIndexOf('"', lastQuote - 1);
+				if (firstQuote > 0) return raw.slice(firstQuote + 1, lastQuote);
+			}
+			const tokens = raw.split(/\s+/).filter(Boolean);
+			return tokens[tokens.length - 1];
+		}
+		return raw;
 	} catch {
 		return undefined;
 	}
@@ -306,6 +364,50 @@ export function removeGjcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv
 	return session;
 }
 
+/**
+ * Force-close a GJC-managed tmux session, even if a live pane is attached.
+ *
+ * This is the lifecycle-control counterpart to {@link removeGjcTmuxSession}: it
+ * intentionally does NOT refuse live/attached panes (hard-kill is the contract),
+ * but it keeps every safety check so it can only ever kill a genuinely
+ * GJC-managed session:
+ * - re-reads the exact tmux profile immediately before kill (never a non-GJC
+ *   session, even one that collides by name);
+ * - when `expectedSessionId` is given, requires the `@gjc-session-id` tag match;
+ * - when `expectedStateFile` is given, requires the `@gjc-session-state-file`
+ *   tag match.
+ *
+ * Returns the prior status (for audit). Throws a tagged error otherwise:
+ * `gjc_tmux_session_not_found`, `gjc_tmux_session_not_managed`,
+ * `gjc_tmux_session_id_mismatch`, or `gjc_tmux_session_state_file_mismatch`.
+ */
+export function forceCloseGjcTmuxSession(
+	sessionName: string,
+	env: NodeJS.ProcessEnv = process.env,
+	expectedSessionId?: string,
+	expectedStateFile?: string,
+): GjcTmuxSessionStatus {
+	const session = statusGjcTmuxSession(sessionName, env);
+	if (readProfileForExactTarget(session.name, env) !== GJC_TMUX_PROFILE_VALUE) {
+		throw new Error(`gjc_tmux_session_not_managed:${sessionName}`);
+	}
+	if (expectedSessionId !== undefined) {
+		const actual = readExactOptionForGc(session.name, GJC_TMUX_SESSION_ID_OPTION, env);
+		if (actual !== expectedSessionId) {
+			throw new Error(`gjc_tmux_session_id_mismatch:${sessionName}`);
+		}
+	}
+	if (expectedStateFile !== undefined) {
+		const actual = readExactOptionForGc(session.name, GJC_TMUX_SESSION_STATE_FILE_OPTION, env);
+		if (actual !== expectedStateFile) {
+			throw new Error(`gjc_tmux_session_state_file_mismatch:${sessionName}`);
+		}
+	}
+	// Intentionally NOT refusing live/attached panes — force-close is hard-kill.
+	runTmux(["kill-session", "-t", `=${session.name}`], env);
+	return session;
+}
+
 export function attachGjcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv = process.env): never {
 	const session = statusGjcTmuxSession(sessionName, env);
 	const tmuxCommand = resolveGjcTmuxCommand(env);

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

@@ -1,11 +1,12 @@
 import * as crypto from "node:crypto";
 import * as path from "node:path";
 import { inflateSync } from "node:zlib";
-
+import { normalizeGoal } from "../goals/state";
+import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
-import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
+import { DEFAULT_ULTRAGOAL_OBJECTIVE, GJC_SESSION_FILE_ENV } from "./goal-mode-request";
 import { gjcRoot, sessionUltragoalDir } from "./session-layout";
 import { resolveGjcSessionForRead, resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
@@ -831,6 +832,14 @@ function normalizedEvidenceKind(row: JsonObject): string {
 function evidenceKindMatches(kind: string, words: string[]): boolean {
 	return words.some(word => kind.includes(word));
 }
+function formatActualArtifactKinds(artifactIds: string[], kinds: string[]): string {
+	if (artifactIds.length === 0) return "none";
+	return artifactIds.map((id, index) => `${id}=${kinds[index] ?? "<missing-kind>"}`).join(", ");
+}
+
+function formatExpectedKindWords(words: string[]): string {
+	return words.map(word => `"${word}"`).join(", ");
+}
 
 type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
 
@@ -899,9 +908,18 @@ function categorizeComputerChangePath(value: string): UltragoalChangeCategory {
 }
 
 function isComputerControlSurfaceCategory(category: UltragoalChangeCategory): boolean {
-	return (
-		category === "code" || category === "generated-binding" || category === "tool" || category === "settings-registry"
-	);
+	// The computer-use red-team suite is conditional, not universal (see the
+	// ultragoal SKILL): require it only when the change actually touches
+	// computer-control source — the computer tool (`tool`), its settings/registry
+	// wiring (`settings-registry`), or computer Rust (`code`). A bare regeneration
+	// of the SHARED native binding (`generated-binding`: packages/natives/native/
+	// index.{d.ts,js}) is NOT by itself a computer-use change: that file is
+	// generated from Rust, so any real computer-use behavior change must also
+	// touch one of the categories above and will still trigger the suite. Treating
+	// the regenerated aggregate binding as a computer surface forced the suite on
+	// unrelated features (e.g. notifications), which the SKILL explicitly warns
+	// against, so it is excluded here.
+	return category === "code" || category === "tool" || category === "settings-registry";
 }
 
 function isComputerControlSurfaceChangePath(row: UltragoalChangeSetPath): boolean {
@@ -967,7 +985,7 @@ function validateSurfaceArtifactCompatibility(
 		const hasVisual = kinds.some(kind => evidenceKindMatches(kind, ["screenshot", "image", "visual"]));
 		if (!hasBrowser || !hasVisual) {
 			throw new Error(
-				`qualityGate ${fieldName} for GUI/web surfaces must reference browser automation plus screenshot or image-verdict artifacts`,
+				`qualityGate ${fieldName} for GUI/web surfaces must reference browser automation plus screenshot or image-verdict artifacts; surface "${surface}" expected one artifact kind containing one of ${formatExpectedKindWords(["browser", "playwright", "pandawright", "automation"])} and one containing one of ${formatExpectedKindWords(["screenshot", "image", "visual"])}; actual artifact kinds: ${formatActualArtifactKinds(artifactIds, kinds)}`,
 			);
 		}
 		return;
@@ -994,7 +1012,7 @@ function validateSurfaceArtifactCompatibility(
 		const expected = surfaceFamilies[family];
 		if (!kinds.some(kind => evidenceKindMatches(kind, expected.evidence))) {
 			throw new Error(
-				`qualityGate ${fieldName} for ${expected.label} surfaces must reference compatible artifact kinds`,
+				`qualityGate ${fieldName} for ${expected.label} surfaces must reference compatible artifact kinds; surface "${surface}" expected at least one artifact kind containing one of ${formatExpectedKindWords(expected.evidence)}; actual artifact kinds: ${formatActualArtifactKinds(artifactIds, kinds)}`,
 			);
 		}
 	}
@@ -1490,6 +1508,20 @@ function isAllowedCliReplayCommand(command: readonly string[]): boolean {
 	if (executable === "gjc") return args.length === 1 && ["read", "status"].includes(args[0] ?? "");
 	return false;
 }
+function summarizeBlockedCliReplayCommand(command: readonly string[]): string {
+	const executable = command[0] ? basenameCommand(command[0]) : "<missing>";
+	const argCount = Math.max(0, command.length - 1);
+	return `${JSON.stringify(executable)} with ${argCount} arg${argCount === 1 ? "" : "s"}`;
+}
+
+function cliReplayAllowlistDescription(): string {
+	return [
+		'`bun --version`, `node --version`, or deterministic `bun/node -e "console.log(...)"`',
+		"`npm|pnpm|yarn --version` or `npm|pnpm|yarn list`",
+		"read-only `git status|rev-parse|merge-base|diff|show|log` with safe args",
+		"`gjc read` or `gjc status`",
+	].join("; ");
+}
 
 function resolveCliReplayCommand(command: string[]): string[] {
 	if (basenameCommand(command[0]!) === "bun") return [process.execPath, ...command.slice(1)];
@@ -1578,8 +1610,11 @@ function parseCliReplayRecord(
 	if (!command) throw new Error(`qualityGate ${fieldName}.command must be a non-empty string array`);
 	if (record.replaySafe !== true)
 		throw new Error(`qualityGate ${fieldName}.replaySafe must be true before CLI replay executes`);
-	if (!isAllowedCliReplayCommand(command))
-		throw new Error(`qualityGate ${fieldName}.command is not in the conservative CLI replay allowlist`);
+	if (!isAllowedCliReplayCommand(command)) {
+		throw new Error(
+			`qualityGate ${fieldName}.command is not in the conservative CLI replay allowlist; command ${summarizeBlockedCliReplayCommand(command)} is blocked. Allowed replay commands: ${cliReplayAllowlistDescription()}. For other commands, provide audited replayExempt metadata with reasonCode, reason, approvedBy, and fallbackArtifactRefs that point to a structurally valid fallback artifact.`,
+		);
+	}
 	if (record.normalization !== undefined && record.normalization !== "default") {
 		throw new Error(`qualityGate ${fieldName}.normalization must be default when provided`);
 	}
@@ -2231,6 +2266,28 @@ function snapshotUpdatedAtMilliseconds(value: unknown): number | null {
 	const parsed = Date.parse(trimmed);
 	return Number.isFinite(parsed) ? parsed : null;
 }
+
+function singleSessionLeafId(entries: readonly SessionEntry[]): string | undefined {
+	if (entries.length === 0) return undefined;
+	const parentIds = new Set(
+		entries.map(entry => entry.parentId).filter((parentId): parentId is string => typeof parentId === "string"),
+	);
+	const leafIds = entries.map(entry => entry.id).filter(id => !parentIds.has(id));
+	return leafIds.length === 1 ? leafIds[0] : undefined;
+}
+
+async function readCurrentSessionGjcGoalSnapshot(): Promise<unknown | undefined> {
+	const sessionFile = process.env[GJC_SESSION_FILE_ENV]?.trim();
+	if (!sessionFile) return undefined;
+	const fileEntries = await loadEntriesFromFile(sessionFile);
+	const entries = fileEntries.filter((entry): entry is SessionEntry => entry.type !== "session");
+	const leafId = singleSessionLeafId(entries);
+	if (!leafId) return undefined;
+	const context = buildSessionContext(entries, leafId);
+	if (context.mode !== "goal" && context.mode !== "goal_paused") return undefined;
+	const goal = normalizeGoal(context.modeData?.goal);
+	return goal ? { goal } : undefined;
+}
 async function readGjcGoalSnapshot(input: {
 	cwd: string;
 	value: string | undefined;
@@ -2240,13 +2297,15 @@ async function readGjcGoalSnapshot(input: {
 	errorPrefix: string;
 	allowCompletedLegacyBlocker?: boolean;
 }): Promise<unknown> {
-	if (!input.value?.trim()) {
+	const snapshot = input.value?.trim()
+		? await readStructuredValue(input.cwd, input.value)
+		: await readCurrentSessionGjcGoalSnapshot();
+	if (snapshot === undefined) {
 		if (!input.required) return undefined;
 		throw new Error(
-			`${input.errorPrefix} require --gjc-goal-json from a fresh active goal({"op":"get"}) snapshot; this is the GJC goal-mode receipt, not the .gjc/ultragoal/goals.json goal record`,
+			`${input.errorPrefix} require an active GJC goal-mode snapshot from the current session or --gjc-goal-json; this is the GJC goal-mode receipt, not the .gjc/ultragoal/goals.json goal record`,
 		);
 	}
-	const snapshot = await readStructuredValue(input.cwd, input.value);
 	const snapshotObject = qualityGateObject(snapshot);
 	const detailsObject = qualityGateObject(snapshotObject?.details);
 	const goalObject = qualityGateObject(snapshotObject?.goal) ?? qualityGateObject(detailsObject?.goal);
@@ -3331,18 +3390,19 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 			"      --status=<value>             pending|active|complete|failed|blocked|review_blocked|superseded",
 			"      --evidence=<value>           Completion or checkpoint evidence text",
 			"      --quality-gate-json=<value>  JSON string or path for complete checkpoints",
-			'      --gjc-goal-json=<value>      JSON string or path containing the current goal({"op":"get"}) snapshot',
+			"      --gjc-goal-json=<value>      Optional JSON/path override for current goal snapshot; omitted complete checkpoints read current session goal state",
 			"      --json                       Output a machine-readable receipt",
 			"",
 			"COMPLETE CHECKPOINT RECEIPTS",
 			"  --quality-gate-json must be an object with architectReview, executorQa, and iteration.",
 			"  executorQa.contractCoverage[] rows require an obligation field; description is not a substitute.",
-			'  --gjc-goal-json must contain the active GJC goal-mode snapshot from goal({"op":"get"}), not the .gjc/ultragoal/goals.json goal record.',
+			"  Complete checkpoints use the current session's active GJC goal-mode snapshot when --gjc-goal-json is omitted.",
+			"  Explicit --gjc-goal-json values must contain an active GJC goal-mode snapshot, not the .gjc/ultragoal/goals.json goal record.",
 			"  goal.updatedAt may be epoch milliseconds or an ISO timestamp and must be fresh.",
 			"",
 			"EXAMPLES",
 			'  $ gjc ultragoal checkpoint --goal-id G001 --status blocked --evidence "waiting on review"',
-			'  $ gjc ultragoal checkpoint --goal-id G001 --status complete --evidence "tests passed" --gjc-goal-json ./goal.json --quality-gate-json ./quality-gate.json --json',
+			'  $ gjc ultragoal checkpoint --goal-id G001 --status complete --evidence "tests passed" --quality-gate-json ./quality-gate.json --json',
 			"",
 		].join("\n");
 	}