@gajae-code/coding-agent 0.6.4 → 0.7.0

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

@@ -12,6 +12,8 @@ import {
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
 import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
+import { modeStatePath, sessionPlansDir } from "./session-layout";
+import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
 import { runNativeStateCommand } from "./state-runtime";
 import {
@@ -169,18 +171,15 @@ interface ResolvedArtifactArgs {
 	stageN: number;
 	runId: string;
 	artifact: string;
-	sessionId: string | undefined;
+	sessionId: string;
 	json: boolean;
 }
 
-function ralplanStatePath(cwd: string, sessionId: string | undefined): string {
-	const stateDir = sessionId
-		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(sessionId))
-		: path.join(cwd, ".gjc", "state");
-	return path.join(stateDir, "ralplan-state.json");
+function ralplanStatePath(cwd: string, sessionId: string): string {
+	return modeStatePath(cwd, sessionId, "ralplan");
 }
 
-async function readActiveRunId(cwd: string, sessionId: string | undefined): Promise<string | undefined> {
+async function readActiveRunId(cwd: string, sessionId: string): Promise<string | undefined> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "absent") return undefined;
@@ -221,12 +220,7 @@ function advanceCurrentPhase(existingPhase: unknown, stage: RalplanStage): strin
 	return stage;
 }
 
-async function persistActiveRunId(
-	cwd: string,
-	sessionId: string | undefined,
-	runId: string,
-	stage: RalplanStage,
-): Promise<void> {
+async function persistActiveRunId(cwd: string, sessionId: string, runId: string, stage: RalplanStage): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt") {
@@ -261,7 +255,7 @@ async function persistActiveRunId(
 	await writeWorkflowEnvelopeAtomic(statePath, existing, {
 		cwd,
 		receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan persist-run-id", sessionId },
-		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan", sessionId },
 	});
 }
 
@@ -384,11 +378,7 @@ function plannerStatePayload(update: PlannerStateUpdate): Record<string, unknown
  * audit/routing hint only — it records what the caller has already proven and is
  * NOT a durable cross-process subagent registry.
  */
-async function applyPlannerStateUpdate(
-	cwd: string,
-	sessionId: string | undefined,
-	update: PlannerStateUpdate,
-): Promise<void> {
+async function applyPlannerStateUpdate(cwd: string, sessionId: string, update: PlannerStateUpdate): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt") {
@@ -407,7 +397,7 @@ async function applyPlannerStateUpdate(
 	await writeWorkflowEnvelopeAtomic(statePath, existing, {
 		cwd,
 		receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan planner-state", sessionId },
-		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan", sessionId },
 	});
 }
 
@@ -423,9 +413,13 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 		throw new RalplanCommandError(2, "--artifact is required for ralplan --write");
 	}
 
-	const sessionIdRaw = flagValue(args, "--session-id")?.trim();
-	const sessionId = sessionIdRaw || undefined;
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const session = resolveGjcSessionForWrite(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		envSessionId: process.env.GJC_SESSION_ID,
+	});
+	const sessionId = session.gjcSessionId;
+	assertSafePathComponent(sessionId, "session-id");
+	const sessionIdRaw = sessionId;
 
 	// Precedence for run_id:
 	//   1. explicit --run-id flag
@@ -469,13 +463,19 @@ async function persistArtifact(
 	content: string,
 	sha256: string,
 ): Promise<PersistedArtifact> {
-	const runDir = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId);
+	const runDir = path.join(sessionPlansDir(cwd, resolved.sessionId), "ralplan", resolved.runId);
 
 	const fileName = `stage-${pad2(resolved.stageN)}-${resolved.stage}.md`;
 	const filePath = path.join(runDir, fileName);
 	await writeArtifact(filePath, content, {
 		cwd,
-		audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+		audit: {
+			category: "artifact",
+			verb: "write",
+			owner: "gjc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 	});
 
 	const createdAt = new Date().toISOString();
@@ -488,7 +488,13 @@ async function persistArtifact(
 	};
 	await appendJsonlIdempotent(path.join(runDir, "index.jsonl"), indexEntry, {
 		cwd,
-		audit: { category: "ledger", verb: "append", owner: "gjc-runtime", skill: "ralplan" },
+		audit: {
+			category: "ledger",
+			verb: "append",
+			owner: "gjc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 		key: ralplanIndexKey,
 	});
 
@@ -497,7 +503,13 @@ async function persistArtifact(
 		pendingApprovalPath = path.join(runDir, "pending-approval.md");
 		await writeArtifact(pendingApprovalPath, content, {
 			cwd,
-			audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+			audit: {
+				category: "artifact",
+				verb: "write",
+				owner: "gjc-runtime",
+				skill: "ralplan",
+				sessionId: resolved.sessionId,
+			},
 		});
 	}
 
@@ -528,11 +540,12 @@ interface ExistingStageArtifact {
  */
 async function findExistingStageArtifact(
 	cwd: string,
+	sessionId: string,
 	runId: string,
 	stage: RalplanStage,
 	stageN: number,
 ): Promise<ExistingStageArtifact | undefined> {
-	const indexPath = path.join(cwd, ".gjc", "plans", "ralplan", runId, "index.jsonl");
+	const indexPath = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId, "index.jsonl");
 	let text: string;
 	try {
 		text = await fs.readFile(indexPath, "utf8");
@@ -566,9 +579,9 @@ async function findExistingStageArtifact(
  * Read and parse the run's `index.jsonl` rows. Best-effort: returns [] when the
  * file is absent or unreadable so HUD sync never fails on a missing index.
  */
-async function readRalplanIndexRows(cwd: string, runId: string): Promise<RalplanIndexRow[]> {
+async function readRalplanIndexRows(cwd: string, sessionId: string, runId: string): Promise<RalplanIndexRow[]> {
 	try {
-		const indexPath = path.join(cwd, ".gjc", "plans", "ralplan", runId, "index.jsonl");
+		const indexPath = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId, "index.jsonl");
 		const text = await fs.readFile(indexPath, "utf8");
 		const rows: RalplanIndexRow[] = [];
 		for (const line of text.split(/\r?\n/)) {
@@ -583,7 +596,7 @@ async function readRalplanIndexRows(cwd: string, runId: string): Promise<Ralplan
 
 async function syncRalplanHud(options: {
 	cwd: string;
-	sessionId?: string;
+	sessionId: string;
 	stage: string;
 	pendingApproval: boolean;
 	iteration?: number;
@@ -612,11 +625,12 @@ async function buildRalplanHud(options: {
 	iteration?: number;
 	latestSummary?: string;
 	runId?: string;
+	sessionId?: string;
 }) {
 	let iterationFromIndex: number | undefined;
 	let stages: string | undefined;
-	if (options.runId) {
-		const rows = await readRalplanIndexRows(options.cwd, options.runId);
+	if (options.runId && options.sessionId) {
+		const rows = await readRalplanIndexRows(options.cwd, options.sessionId, options.runId);
 		if (rows.length > 0) {
 			const summary = summarizeRalplanIndex(rows);
 			iterationFromIndex = summary.iteration;
@@ -643,7 +657,13 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	// Duplicate-write guard: a second `--write` for the same (stage, stage_n) must not
 	// silently clobber the artifact or append a duplicate ledger row. Classify before any
 	// state mutation so a conflict never regresses run-state phase.
-	const existingArtifact = await findExistingStageArtifact(cwd, resolved.runId, resolved.stage, resolved.stageN);
+	const existingArtifact = await findExistingStageArtifact(
+		cwd,
+		resolved.sessionId,
+		resolved.runId,
+		resolved.stage,
+		resolved.stageN,
+	);
 	if (existingArtifact) {
 		if (existingArtifact.sha256 !== sha256) {
 			throw new RalplanCommandError(
@@ -660,6 +680,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	if (plannerState) {
 		await applyPlannerStateUpdate(cwd, resolved.sessionId, plannerState);
 	}
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: persisted.path });
 	await syncRalplanHud({
 		cwd,
 		sessionId: resolved.sessionId,
@@ -706,7 +727,12 @@ function buildDeduplicatedResult(
 		deduplicated: true,
 	};
 	if (resolved.stage === "final") {
-		payload.pending_approval_path = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId, "pending-approval.md");
+		payload.pending_approval_path = path.join(
+			sessionPlansDir(cwd, resolved.sessionId),
+			"ralplan",
+			resolved.runId,
+			"pending-approval.md",
+		);
 	}
 	const stdout = resolved.json
 		? `${JSON.stringify(payload, null, 2)}\n`
@@ -721,7 +747,7 @@ interface ConsensusHandoffArgs {
 	deliberate: boolean;
 	architectKind?: string;
 	criticKind?: string;
-	sessionId?: string;
+	sessionId: string;
 	task: string;
 	json: boolean;
 }
@@ -747,7 +773,7 @@ function extractPositionalTask(args: readonly string[]): string {
 	return parts.join(" ").trim();
 }
 
-function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
+function resolveConsensusArgs(args: readonly string[], cwd: string): ConsensusHandoffArgs {
 	const architectKind = flagValue(args, "--architect")?.trim() || undefined;
 	if (architectKind && !KNOWN_ARCHITECT_KINDS.has(architectKind)) {
 		throw new RalplanCommandError(
@@ -762,8 +788,12 @@ function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
 			`unknown --critic kind: ${criticKind}. Expected one of: ${[...KNOWN_CRITIC_KINDS].join(", ")}.`,
 		);
 	}
-	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const session = resolveGjcSessionForWrite(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		envSessionId: process.env.GJC_SESSION_ID,
+	});
+	const sessionId = session.gjcSessionId;
+	assertSafePathComponent(sessionId, "session-id");
 	const task = extractPositionalTask(args);
 	return {
 		interactive: hasFlag(args, "--interactive"),
@@ -776,19 +806,11 @@ function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
 	};
 }
 
-function encodeSessionSegment(value: string): string {
-	return encodeURIComponent(value).replaceAll(".", "%2E");
-}
-
 async function seedRalplanState(
 	cwd: string,
 	resolved: ConsensusHandoffArgs,
 ): Promise<{ statePath: string; runId: string }> {
-	const stateDir = resolved.sessionId
-		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
-		: path.join(cwd, ".gjc", "state");
-
-	const statePath = path.join(stateDir, "ralplan-state.json");
+	const statePath = ralplanStatePath(cwd, resolved.sessionId);
 	// Reuse an existing run id when present so a re-invocation of `gjc ralplan "task"` doesn't
 	// orphan in-progress artifacts under a fresh run id.
 	const existingRunId = await readActiveRunId(cwd, resolved.sessionId);
@@ -818,13 +840,20 @@ async function seedRalplanState(
 			command: "gjc ralplan seed",
 			sessionId: resolved.sessionId,
 		},
-		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+		audit: {
+			category: "state",
+			verb: "write",
+			owner: "gjc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 	});
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: statePath });
 	return { statePath, runId };
 }
 
 async function handleConsensusHandoff(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
-	const resolved = resolveConsensusArgs(args);
+	const resolved = resolveConsensusArgs(args, cwd);
 	if (!resolved.task) {
 		throw new RalplanCommandError(2, 'gjc ralplan requires a task description, e.g. `gjc ralplan "<task>"`.');
 	}

package/src/gjc-runtime/session-layout.ts

@@ -0,0 +1,180 @@
+/**
+ * Pure path layout for session-scoped GJC workflow state.
+ *
+ * Every generated/runtime artifact for a GJC session lives under
+ * `<cwd>/.gjc/_session-{encodedSessionId}/...`. The `_session-` prefix is what
+ * discriminates a session directory from shared, user-authored/installed config
+ * (settings.json, secrets.yml, agents/, gjc-plugins/, agent/, python-env/, user
+ * skills/commands), which always stays at the `.gjc/` root.
+ *
+ * This module is PURE and acyclic: every export is a deterministic function of
+ * its arguments. It never reads `process.env` and never touches the filesystem.
+ * Session resolution (flag/payload/env/latest-activity-marker) and any
+ * filesystem scanning live in `session-resolution.ts`, the boundary module.
+ */
+import * as path from "node:path";
+
+export const GJC_DIR = ".gjc";
+export const GJC_SESSION_PREFIX = "_session-";
+export const GJC_SESSION_ACTIVITY_FILE = ".session-activity.json";
+
+/** Source that produced a resolved GJC session id, for audit/diagnostics. */
+export type GjcSessionSource = "flag" | "payload" | "env" | "latest";
+
+export interface GjcSessionContext {
+	gjcSessionId: string;
+	sessionRoot: string;
+	source: GjcSessionSource;
+}
+
+/**
+ * Encode a session id into a single safe path segment. Matches the historical
+ * encoding used across the runtimes so ids round-trip identically:
+ * `encodeURIComponent` plus dot-escaping (dots are legal in filenames but we
+ * avoid `.`/`..` traversal ambiguity).
+ */
+export function encodeSessionSegment(value: string): string {
+	return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+
+/** Inverse of {@link encodeSessionSegment}. */
+export function decodeSessionSegment(segment: string): string {
+	return decodeURIComponent(segment.replaceAll("%2E", "."));
+}
+
+/** Throw when a session id is missing or blank; never let blank suppress callers. */
+export function assertNonEmptyGjcSessionId(value: string | undefined, source: string): asserts value is string {
+	if (typeof value !== "string" || value.trim() === "") {
+		throw new Error(`a non-empty GJC session id is required (${source})`);
+	}
+}
+
+/**
+ * Assert a value is safe to use as a single path segment: non-blank and free of
+ * path separators or `.`/`..` traversal. Use for already-safe identifiers
+ * (skill modes, slugs) where we want identical filenames but fail closed on
+ * traversal rather than silently normalizing out of the intended directory.
+ */
+export function assertSafePathComponent(value: string, label: string): void {
+	const trimmed = value.trim();
+	if (trimmed === "") throw new Error(`${label} is required`);
+	if (trimmed === "." || trimmed === ".." || /[/\\]/.test(trimmed)) {
+		throw new Error(`${label} must be a safe path component (no separators or traversal): ${value}`);
+	}
+}
+
+/** The shared `.gjc/` root (holds shared config; never session-scoped). */
+export function gjcRoot(cwd: string): string {
+	return path.join(cwd, GJC_DIR);
+}
+
+/** The per-session root directory: `<cwd>/.gjc/_session-{encodedId}`. */
+export function sessionRoot(cwd: string, gjcSessionId: string): string {
+	assertNonEmptyGjcSessionId(gjcSessionId, "sessionRoot");
+	return path.join(gjcRoot(cwd), `${GJC_SESSION_PREFIX}${encodeSessionSegment(gjcSessionId)}`);
+}
+
+/** Directory name (no path) for a session id, e.g. `_session-abc`. */
+export function sessionDirName(gjcSessionId: string): string {
+	assertNonEmptyGjcSessionId(gjcSessionId, "sessionDirName");
+	return `${GJC_SESSION_PREFIX}${encodeSessionSegment(gjcSessionId)}`;
+}
+
+/** Return the decoded session id for a `_session-*` directory name, else undefined. */
+export function sessionIdFromDirName(name: string): string | undefined {
+	if (!name.startsWith(GJC_SESSION_PREFIX)) return undefined;
+	const suffix = name.slice(GJC_SESSION_PREFIX.length);
+	if (suffix === "") return undefined;
+	let decoded: string;
+	try {
+		decoded = decodeSessionSegment(suffix);
+	} catch {
+		return undefined;
+	}
+	return decoded.trim() === "" ? undefined : decoded;
+}
+
+/** Authoritative per-session activity marker path. */
+export function sessionActivityPath(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), GJC_SESSION_ACTIVITY_FILE);
+}
+
+// ---- Top-level per-category subdir resolvers ----
+
+export function sessionStateDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "state");
+}
+export function sessionSpecsDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "specs");
+}
+export function sessionPlansDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "plans");
+}
+export function sessionUltragoalDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "ultragoal");
+}
+export function sessionAuditDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "audit");
+}
+export function sessionReportsDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "reports");
+}
+export function sessionLogsDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "logs");
+}
+export function sessionRuntimeDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "runtime");
+}
+export function sessionRlmDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionRoot(cwd, gjcSessionId), "rlm");
+}
+
+// ---- Nested resolvers under <sessionRoot>/state ----
+
+export function activeStateDir(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "active");
+}
+export function activeSnapshotPath(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "skill-active-state.json");
+}
+export function activeEntryPath(cwd: string, gjcSessionId: string, skill: string): string {
+	const normalized = skill.trim();
+	if (normalized === "") throw new Error("skill is required");
+	return path.join(activeStateDir(cwd, gjcSessionId), `${encodeSessionSegment(normalized)}.json`);
+}
+export function modeStatePath(cwd: string, gjcSessionId: string, mode: string): string {
+	const normalized = mode.trim();
+	assertSafePathComponent(normalized, "mode");
+	return path.join(sessionStateDir(cwd, gjcSessionId), `${normalized}-state.json`);
+}
+export function auditPath(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "audit.jsonl");
+}
+export function transactionJournalPath(cwd: string, gjcSessionId: string, mutationId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "transactions", `${encodeSessionSegment(mutationId)}.json`);
+}
+export function teamStateRoot(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "team");
+}
+export function workflowGatePath(cwd: string, gjcSessionId: string, gateId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "workflow-gates", `${encodeSessionSegment(gateId)}.json`);
+}
+export function harnessStateRoot(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "harness");
+}
+export function coordinatorMcpStateRoot(cwd: string, gjcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, gjcSessionId), "coordinator-mcp");
+}
+
+// ---- Nested resolvers under other top-level categories ----
+
+export function tmuxRuntimeSessionPath(cwd: string, gjcSessionId: string, slug: string): string {
+	const normalized = slug.trim();
+	assertSafePathComponent(normalized, "slug");
+	return path.join(sessionRuntimeDir(cwd, gjcSessionId), "tmux-sessions", `${normalized}.json`);
+}
+export function rlmArtifactRoot(cwd: string, gjcSessionId: string, rlmSessionId: string): string {
+	const normalized = rlmSessionId.trim();
+	if (normalized === "") throw new Error("rlmSessionId is required");
+	return path.join(sessionRlmDir(cwd, gjcSessionId), encodeSessionSegment(normalized));
+}