@gajae-code/coding-agent 0.4.4 → 0.5.0

package/src/cursor.ts

@@ -160,8 +160,35 @@ function formatMcpToolErrorMessage(toolName: string, availableTools: string[]):
 	return `MCP tool "${toolName}" not found. Available tools: ${list}`;
 }
 
+/**
+ * Cursor's wire protocol carries shell timeouts in milliseconds — the
+ * model-facing parameter is `block_until_ms`, and `ShellArgs.hard_timeout` is
+ * likewise documented in ms — while the bash tool's `timeout` is seconds.
+ * Passing the raw value through made a requested 30 s wait (30000 ms) arrive
+ * as 30000 s and clamp to the 3600 s ceiling, i.e. an accidental 1-hour
+ * timeout on a blocking command. Convert, rounding sub-second values up to 1 s
+ * so a tiny requested wait does not collapse to "no timeout".
+ */
+function shellTimeoutSeconds(timeout: number | undefined): number | undefined {
+	if (!timeout || timeout <= 0) return undefined;
+	return Math.max(1, Math.ceil(timeout / 1000));
+}
+
 export class CursorExecHandlers implements ICursorExecHandlers {
-	constructor(private options: CursorExecBridgeOptions) {}
+	constructor(private options: CursorExecBridgeOptions) {
+		// Bind every native handler so methods stay instance-safe when invoked
+		// detached/unbound by the Cursor provider (e.g. `const read = handlers.read`).
+		// Without this, `this.#optionsForCall()` throws "undefined is not an object".
+		this.read = this.read.bind(this);
+		this.ls = this.ls.bind(this);
+		this.grep = this.grep.bind(this);
+		this.write = this.write.bind(this);
+		this.delete = this.delete.bind(this);
+		this.shell = this.shell.bind(this);
+		this.shellStream = this.shellStream.bind(this);
+		this.diagnostics = this.diagnostics.bind(this);
+		this.mcp = this.mcp.bind(this);
+	}
 
 	#optionsForCall(): CursorExecBridgeOptions {
 		return {
@@ -185,9 +212,24 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 
 	async grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
+		// Cursor's native Glob tool arrives as a grep exec with a glob but no content
+		// pattern. The search tool requires a non-empty pattern, so an empty pattern
+		// means "list files matching this glob" — route that to find instead of
+		// throwing "Pattern must not be empty".
+		const pattern = typeof args.pattern === "string" ? args.pattern : "";
+		if (pattern.trim().length === 0) {
+			if (args.glob) {
+				const globPath = `${args.path || "."}/${args.glob}`;
+				return executeTool(this.#optionsForCall(), "find", toolCallId, { paths: [globPath] });
+			}
+			const result = buildToolErrorResult(
+				"Cursor grep request rejected: pattern must not be empty. Provide a non-empty search pattern.",
+			);
+			return createToolResultMessage(toolCallId, "search", result, true);
+		}
 		const searchPath = args.glob ? `${args.path || "."}/${args.glob}` : args.path || ".";
 		const toolResultMessage = await executeTool(this.#optionsForCall(), "search", toolCallId, {
-			pattern: args.pattern,
+			pattern,
 			paths: [searchPath],
 			i: args.caseInsensitive || undefined,
 		});
@@ -212,7 +254,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 
 	async shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0]) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
-		const timeoutSeconds = args.timeout && args.timeout > 0 ? args.timeout : undefined;
+		const timeoutSeconds = shellTimeoutSeconds(args.timeout);
 		const toolResultMessage = await executeTool(this.#optionsForCall(), "bash", toolCallId, {
 			command: args.command,
 			cwd: args.workingDirectory || undefined,
@@ -234,7 +276,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 			return createToolResultMessage(toolCallId, toolName, result, true);
 		}
 
-		const timeoutSeconds = args.timeout && args.timeout > 0 ? args.timeout : undefined;
+		const timeoutSeconds = shellTimeoutSeconds(args.timeout);
 		const toolArgs: Record<string, unknown> = {
 			command: args.command,
 			cwd: args.workingDirectory || undefined,

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

@@ -306,8 +306,9 @@ Worker protocol:
 
 Useful runtime env vars:
 
-- `GJC_TEAM_TMUX_COMMAND`
-  - tmux binary/command override (default `tmux`)
+- `GJC_TMUX_COMMAND` / `GJC_TEAM_TMUX_COMMAND`
+  - tmux binary/command override (default `tmux`). `GJC_TMUX_COMMAND` applies to every GJC tmux flow; `GJC_TEAM_TMUX_COMMAND` is honored as an alias by the team path. Both resolve through the same resolver, so the team leader and `gjc session ...` always target the same multiplexer.
+  - Multiplexer support boundary: GJC-managed sessions and the team leader are detected via tmux user options (`@gjc-profile`, written with `set-option` and read back with `show-options` / `list-sessions -F`). A provider must round-trip those user options to be supported. Real tmux works. Alternative multiplexers such as psmux on Windows do not reliably persist tmux user options yet, so `gjc session status` reports `gjc_tmux_session_untagged` (the session exists in the multiplexer but is not GJC-tagged) and team startup rejects the leader as `unmanaged_tmux_session`. The Windows-native psmux path is therefore not fully supported; use real tmux for GJC-managed session and team flows.
 - `GJC_TEAM_WORKER_COMMAND`
   - worker command override (default resolves to active GJC entrypoint or `gjc`)
 - `GJC_TEAM_STATE_ROOT`

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

@@ -120,9 +120,15 @@ Examples:
 
 ```sh
 gjc ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "Validate the blocker and report evidence." --evidence "log/test output" --rationale "The blocker changes the safe execution order." --json
-gjc ultragoal steer --directive-json ./steering.json --json
+gjc ultragoal steer --kind split_subgoal --goal-id G002 --replacements-json '[{"title":"Fix parser","objective":"Resolve parser blocker."},{"title":"Verify parser","objective":"Run focused parser verification."}]' --evidence "Implementation split found two separable risks" --rationale "Splitting keeps each sub-goal independently verifiable." --json
+gjc ultragoal steer --kind reorder_pending --order-json '["G003","G002"]' --evidence "Dependency order changed after investigation" --rationale "G003 must land before G002 can proceed safely." --json
+gjc ultragoal steer --kind revise_pending_wording --goal-id G002 --title "Clarify blocker story" --evidence "The current title hides the actual blocker" --rationale "Clear wording keeps the ledger auditable." --json
+gjc ultragoal steer --kind annotate_ledger --evidence "User changed release ordering at runtime" --rationale "The aggregate objective is unchanged, but the execution history needs an audit note." --json
+gjc ultragoal steer --kind mark_blocked_superseded --goal-id G004 --evidence "The blocked work is no longer required because replacement evidence covers it" --rationale "No replacement sub-goal is needed; superseding only the blocked sub-goal unblocks final completion without changing the aggregate objective." --json
 ```
 
+`--directive-json` and UserPromptSubmit structured steering are planned/deferred routing surfaces, not part of the native typed `--kind` CLI path described above.
+
 Steering invariants:
 
 - Do not edit the aggregate goal objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.gjc/ultragoal/goals.json` and `.gjc/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
@@ -131,7 +137,7 @@ Steering invariants:
 - Superseded goals remain in `goals.json` with steering metadata and are skipped for scheduling.
 - Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.
 
-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.
+UserPromptSubmit structured steering directives are a planned/deferred routing surface. Normal prose does not mutate state.
 
 ## Role-agent delegation guidance
 

package/src/export/html/index.ts

@@ -150,15 +150,19 @@ export async function exportFromFile(inputPath: string, options?: ExportOptions
 		throw err;
 	}
 
-	const sessionData: SessionData = {
-		header: sm.getHeader(),
-		entries: sm.getEntries(),
-		leafId: sm.getLeafId(),
-	};
+	try {
+		const sessionData: SessionData = {
+			header: sm.getHeader(),
+			entries: sm.getEntries(),
+			leafId: sm.getLeafId(),
+		};
 
-	const html = await generateHtml(sessionData, opts.themeName);
-	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(inputPath, ".jsonl")}.html`;
+		const html = await generateHtml(sessionData, opts.themeName);
+		const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(inputPath, ".jsonl")}.html`;
 
-	await Bun.write(outputPath, html);
-	return outputPath;
+		await Bun.write(outputPath, html);
+		return outputPath;
+	} finally {
+		await sm.close();
+	}
 }

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

@@ -140,6 +140,17 @@ function readWorktreeEntryFromPath(repoRoot: string, worktreePath: string): GitW
 	return { path: path.resolve(worktreePath), head, branchRef, detached: !branchRef };
 }
 
+function resolveCanonicalRepoRoot(cwd: string): string {
+	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	const commonDir = tryRunGit(repoRoot, ["rev-parse", "--git-common-dir"]);
+	if (!commonDir) return repoRoot;
+	const resolvedCommonDir = path.resolve(repoRoot, commonDir);
+	if (path.basename(resolvedCommonDir) !== ".git") return repoRoot;
+	const ownerRoot = path.dirname(resolvedCommonDir);
+	if (tryRunGit(ownerRoot, ["rev-parse", "--is-inside-work-tree"]) !== "true") return repoRoot;
+	return ownerRoot;
+}
+
 function isWorktreeDirty(worktreePath: string): boolean {
 	return runGit(worktreePath, ["status", "--porcelain"]).length > 0;
 }
@@ -187,7 +198,7 @@ export function planLaunchWorktree(
 	mode: GjcLaunchWorktreeMode,
 ): GjcLaunchWorktreePlan | { enabled: false } {
 	if (!mode.enabled) return { enabled: false };
-	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	const repoRoot = resolveCanonicalRepoRoot(cwd);
 	const baseRef = runGit(repoRoot, ["rev-parse", "HEAD"]);
 	const branchName = mode.detached ? null : mode.name;
 	if (branchName) validateBranchName(repoRoot, branchName);

package/src/gjc-runtime/session-state-sidecar.ts

@@ -30,6 +30,33 @@ function lastAssistant(messages: unknown[] | undefined): AssistantMessage | unde
 	return undefined;
 }
 
+function assistantText(assistant: AssistantMessage | undefined): string | null {
+	if (!assistant) return null;
+	const text = assistant.content
+		.filter(part => part.type === "text")
+		.map(part => part.text)
+		.join("\n")
+		.trim();
+	return text.length > 0 ? text : null;
+}
+
+function finalResponseForEvent(event: RuntimeStateEvent): {
+	text: string | null;
+	format: "markdown";
+	source: "agent_end";
+	artifact_path: null;
+	truncated: false;
+} | null {
+	if (event.type !== "agent_end") return null;
+	return {
+		text: assistantText(lastAssistant(event.messages)),
+		format: "markdown",
+		source: "agent_end",
+		artifact_path: null,
+		truncated: false,
+	};
+}
+
 function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
 	if (event.type === "agent_start" || event.type === "turn_start") return "running";
 	if (event.type === "agent_end") {
@@ -55,6 +82,7 @@ export async function persistCoordinatorRuntimeStateFromEvent(
 	} catch {
 		previous = {};
 	}
+	const finalResponse = finalResponseForEvent(event);
 	const payload = {
 		schema_version: 1,
 		session_id: process.env[GJC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId,
@@ -69,6 +97,16 @@ export async function persistCoordinatorRuntimeStateFromEvent(
 		event: event.type,
 		cwd: context.cwd,
 		session_file: context.sessionFile ?? null,
+		...(finalResponse ? { final_response: finalResponse } : {}),
+		...(state === "errored"
+			? {
+					error: {
+						code: "agent_error",
+						message: lastAssistant(event.messages)?.errorMessage ?? "agent_error",
+						recoverable: true,
+					},
+				}
+			: {}),
 	};
 	try {
 		await fs.mkdir(path.dirname(stateFile), { recursive: true });

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

@@ -5,7 +5,7 @@ import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildTeamHudSummary as buildWorkflowTeamHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 
-import { applyGjcTmuxProfile } from "./launch-tmux";
+import { applyGjcTmuxProfile, GJC_TMUX_LAUNCHED_ENV } from "./launch-tmux";
 import {
 	AlreadyExistsError,
 	appendJsonl as appendJsonlAudited,
@@ -17,7 +17,12 @@ import {
 	writeReport,
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
-import { GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE } from "./tmux-common";
+import {
+	buildGjcTmuxUntaggedSessionHint,
+	GJC_TMUX_PROFILE_OPTION,
+	GJC_TMUX_PROFILE_VALUE,
+	resolveGjcTmuxCommand,
+} from "./tmux-common";
 
 export type GjcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
@@ -1622,9 +1627,6 @@ async function ensureWorkerWorktree(
 	};
 }
 
-export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): string {
-	return env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
-}
 function buildTeamTmuxLeaderRequirementMessage(detail?: string): string {
 	const suffix = detail?.trim() ? `:${detail.trim()}` : "";
 	return `gjc_team_requires_tmux_leader: run \`gjc --tmux\` first, then run \`gjc team ...\` inside that tmux-backed leader session, or use \`gjc team --dry-run\` for state-only smoke tests${suffix}`;
@@ -1641,6 +1643,17 @@ function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): stri
 	return result.stdout.toString().trim();
 }
 
+function retagGjcLaunchedTmuxSession(tmuxCommand: string, sessionName: string): boolean {
+	const result = Bun.spawnSync(
+		[tmuxCommand, "set-option", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE],
+		{
+			stdout: "pipe",
+			stderr: "pipe",
+		},
+	);
+	return result.exitCode === 0;
+}
+
 function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEnv): GjcTmuxLeaderContext {
 	const paneTarget = env.TMUX_PANE?.trim();
 	const args = paneTarget
@@ -1652,8 +1665,21 @@ function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEn
 	const [sessionName = "", windowIndex = ""] = sessionAndWindow.split(":");
 	if (!sessionName || !windowIndex || !leaderPaneId.startsWith("%"))
 		throw new Error(buildTeamTmuxLeaderRequirementMessage(`invalid_tmux_context:${result.stdout.toString().trim()}`));
-	if (readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE)
-		throw new Error(buildTeamTmuxLeaderRequirementMessage(`unmanaged_tmux_session:${sessionName}`));
+	if (readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE) {
+		// Self-heal: a pane launched through `gjc --tmux` exports
+		// GJC_TMUX_LAUNCHED=1, but the session can lose (or never receive) the
+		// @gjc-profile user-option tag when startup attach fails mid-way or the
+		// registry write races. That stranded-but-genuinely-GJC leader pane
+		// previously hard-failed as unmanaged_tmux_session; re-tag it instead.
+		const launchedByGjc = env[GJC_TMUX_LAUNCHED_ENV] === "1";
+		const retagged = launchedByGjc && retagGjcLaunchedTmuxSession(tmuxCommand, sessionName);
+		if (!retagged || readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE)
+			throw new Error(
+				buildTeamTmuxLeaderRequirementMessage(
+					`unmanaged_tmux_session:${sessionName} — ${buildGjcTmuxUntaggedSessionHint(tmuxCommand)}`,
+				),
+			);
+	}
 	return { sessionName, windowIndex, leaderPaneId, target: `${sessionName}:${windowIndex}` };
 }
 export function resolveGjcWorkerCommand(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): string {

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

@@ -32,6 +32,21 @@ export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): str
 	return env[GJC_TMUX_COMMAND_ENV]?.trim() || env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
 }
 
+export const GJC_TMUX_UNTAGGED_REASON = "gjc_tmux_session_untagged";
+
+export function buildGjcTmuxUntaggedSessionHint(tmuxCommand: string): string {
+	return (
+		`the active multiplexer "${tmuxCommand}" lists this session but did not return GJC's ${GJC_TMUX_PROFILE_OPTION} ownership tag; ` +
+		"GJC-managed sessions and `gjc team` require a tmux provider that round-trips tmux user options. " +
+		"Alternative multiplexers such as psmux on Windows do not persist user options yet, so the Windows-native psmux path is not fully supported; " +
+		"use real tmux for GJC-managed session and team flows."
+	);
+}
+
+export function buildGjcTmuxUntaggedSessionError(sessionName: string, tmuxCommand: string): string {
+	return `${GJC_TMUX_UNTAGGED_REASON}:${sessionName} — ${buildGjcTmuxUntaggedSessionHint(tmuxCommand)}`;
+}
+
 export function sanitizeTmuxToken(value: string): string {
 	return (
 		value

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

@@ -1,6 +1,7 @@
 import {
 	buildGjcTmuxProfileCommands,
 	buildGjcTmuxSessionName,
+	buildGjcTmuxUntaggedSessionError,
 	GJC_TMUX_BRANCH_OPTION,
 	GJC_TMUX_BRANCH_SLUG_OPTION,
 	GJC_TMUX_PROFILE_OPTION,
@@ -73,17 +74,10 @@ function parseSessionLine(line: string): GjcTmuxSessionStatus | null {
 	};
 }
 
-function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
+function runListSessions(format: string, env: NodeJS.ProcessEnv = process.env): string[] {
 	let output = "";
 	try {
-		output = runTmux(
-			[
-				"list-sessions",
-				"-F",
-				`#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}\t#{${GJC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{${GJC_TMUX_BRANCH_OPTION}}\t#{${GJC_TMUX_BRANCH_SLUG_OPTION}}\t#{${GJC_TMUX_PROJECT_OPTION}}`,
-			],
-			env,
-		);
+		output = runTmux(["list-sessions", "-F", format], env);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		if (message.includes("no server running") || message.includes("failed to connect to server")) return [];
@@ -95,6 +89,17 @@ function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
 		.filter(Boolean);
 }
 
+function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
+	return runListSessions(
+		`#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}\t#{${GJC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{${GJC_TMUX_BRANCH_OPTION}}\t#{${GJC_TMUX_BRANCH_SLUG_OPTION}}\t#{${GJC_TMUX_PROJECT_OPTION}}`,
+		env,
+	);
+}
+
+function listRawTmuxSessionNames(env: NodeJS.ProcessEnv = process.env): string[] {
+	return runListSessions("#{session_name}", env).map(line => line.split("\t")[0] ?? line);
+}
+
 export function listGjcTmuxSessions(env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionStatus[] {
 	return listSessionLines(env)
 		.map(parseSessionLine)
@@ -114,8 +119,11 @@ export function findGjcTmuxSessionByBranch(
 
 export function statusGjcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionStatus {
 	const session = listGjcTmuxSessions(env).find(candidate => candidate.name === sessionName);
-	if (!session) throw new Error(`gjc_tmux_session_not_found:${sessionName}`);
-	return session;
+	if (session) return session;
+	if (listRawTmuxSessionNames(env).includes(sessionName)) {
+		throw new Error(buildGjcTmuxUntaggedSessionError(sessionName, resolveGjcTmuxCommand(env)));
+	}
+	throw new Error(`gjc_tmux_session_not_found:${sessionName}`);
 }
 
 export function createGjcTmuxSession(env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionStatus {