@gajae-code/coding-agent 0.2.5 → 0.3.0

package/src/harness-control-plane/storage.ts

@@ -0,0 +1,257 @@
+/**
+ * Session-scoped storage for the harness control plane.
+ *
+ * Layout (under the harness state root, default `<cwd>/.gjc/state/harness`):
+ *   sessions/<encoded-id>/state.json        lifecycle + handle (atomic)
+ *   sessions/<encoded-id>/lease.json         owner lease (M3)
+ *   sessions/<encoded-id>/events.jsonl       owner-only severity envelopes
+ *   sessions/<encoded-id>/receipts.jsonl     append-only receipt index
+ *   sessions/<encoded-id>/receipts/<family>/<receiptId>.json  immutable receipts
+ *   sessions/<encoded-id>/artifacts/...      diff/validation artifacts
+ *   sessions/<encoded-id>/gjc-session/       underlying gajae-code --session-dir
+ *
+ * Receipt files are immutable: re-writing an existing receipt id fails closed.
+ * JSON writes are atomic (temp + rename).
+ */
+import { createHash, randomBytes } from "node:crypto";
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const MAX_UNIX_SOCKET_PATH_BYTES = 100;
+
+interface SocketPathMetadata {
+	root: string;
+	sessionId: string;
+}
+
+function socketBase(env: NodeJS.ProcessEnv, allowOverride: boolean): { base: string; fromOverride: boolean } {
+	const override = env.GJC_HARNESS_SOCKET_DIR?.trim();
+	if (allowOverride && override) return { base: path.resolve(override), fromOverride: true };
+	return { base: path.join(os.tmpdir(), `gjch${process.getuid?.() ?? "u"}`), fromOverride: false };
+}
+
+function socketPathForBase(root: string, sessionId: string, base: string): string {
+	const digest = createHash("sha256").update(`${root}\0${sessionId}`).digest("hex");
+	fsSync.mkdirSync(base, { recursive: true });
+	for (const len of [16, 24, 32, 48, 64]) {
+		const stem = `c-${digest.slice(0, len)}`;
+		const metadataPath = path.join(base, `${stem}.json`);
+		const metadata: SocketPathMetadata = { root, sessionId };
+		try {
+			const existing = JSON.parse(fsSync.readFileSync(metadataPath, "utf8")) as SocketPathMetadata;
+			if (existing.root === root && existing.sessionId === sessionId) return path.join(base, `${stem}.sock`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			fsSync.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+			return path.join(base, `${stem}.sock`);
+		}
+	}
+	throw new StorageError(`socket_path_collision:${sessionId}`, "socket_path_collision");
+}
+
+export function controlSocketPath(root: string, sessionId: string, env: NodeJS.ProcessEnv = process.env): string {
+	assertSafeSessionId(sessionId);
+	let { base, fromOverride } = socketBase(env, true);
+	let finalPath = socketPathForBase(root, sessionId, base);
+	if (Buffer.byteLength(finalPath) > MAX_UNIX_SOCKET_PATH_BYTES && fromOverride) {
+		base = socketBase(env, false).base;
+		finalPath = socketPathForBase(root, sessionId, base);
+	}
+	const finalBytes = Buffer.byteLength(finalPath);
+	if (finalBytes > MAX_UNIX_SOCKET_PATH_BYTES) {
+		throw new StorageError(`socket_path_too_long:${finalBytes}`, "socket_path_too_long");
+	}
+	return finalPath;
+}
+
+export class StorageError extends Error {
+	constructor(
+		message: string,
+		readonly code: string,
+	) {
+		super(message);
+		this.name = "StorageError";
+	}
+}
+
+/** Resolve the harness state root from explicit value, env, or cwd default. */
+export function resolveHarnessRoot(opts?: { root?: string; cwd?: string; env?: NodeJS.ProcessEnv }): string {
+	const env = opts?.env ?? process.env;
+	if (opts?.root) return path.resolve(opts.root);
+	const fromEnv = env.GJC_HARNESS_STATE_ROOT;
+	if (fromEnv?.trim()) return path.resolve(fromEnv.trim());
+	return path.join(opts?.cwd ?? process.cwd(), ".gjc", "state", "harness");
+}
+
+export function assertSafeSessionId(id: string): void {
+	if (!SESSION_ID_RE.test(id)) {
+		throw new StorageError(`unsafe_session_id:${id}`, "unsafe_session_id");
+	}
+}
+
+export function generateSessionId(prefix = "h"): string {
+	const ts = new Date().toISOString().replace(/[:.]/g, "").replace("T", "-").slice(0, 15);
+	const rand = randomBytes(4).toString("hex");
+	return `${prefix}-${ts}-${rand}`;
+}
+
+export interface SessionPaths {
+	dir: string;
+	state: string;
+	lease: string;
+	events: string;
+	receiptsIndex: string;
+	receiptsDir: string;
+	artifactsDir: string;
+	controlSock: string;
+	controlFifo: string;
+	gjcSessionDir: string;
+}
+
+export function sessionPaths(root: string, sessionId: string): SessionPaths {
+	assertSafeSessionId(sessionId);
+	const dir = path.join(root, "sessions", sessionId);
+	return {
+		dir,
+		state: path.join(dir, "state.json"),
+		lease: path.join(dir, "lease.json"),
+		events: path.join(dir, "events.jsonl"),
+		receiptsIndex: path.join(dir, "receipts.jsonl"),
+		receiptsDir: path.join(dir, "receipts"),
+		artifactsDir: path.join(dir, "artifacts"),
+		controlSock: path.join(dir, "control.sock"),
+		controlFifo: path.join(dir, "control.fifo"),
+		gjcSessionDir: path.join(dir, "gjc-session"),
+	};
+}
+
+async function writeJsonAtomic(file: string, value: unknown): Promise<void> {
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-${randomBytes(4).toString("hex")}`;
+	await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+	await fs.rename(tmp, file);
+}
+
+async function readJson<T>(file: string): Promise<T | null> {
+	try {
+		const raw = await fs.readFile(file, "utf8");
+		return JSON.parse(raw) as T;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+export async function readSessionState(root: string, sessionId: string): Promise<SessionState | null> {
+	return readJson<SessionState>(sessionPaths(root, sessionId).state);
+}
+
+export async function writeSessionState(root: string, state: SessionState): Promise<void> {
+	const paths = sessionPaths(root, state.sessionId);
+	await fs.mkdir(paths.dir, { recursive: true });
+	await writeJsonAtomic(paths.state, state);
+}
+
+export async function sessionExists(root: string, sessionId: string): Promise<boolean> {
+	return (await readSessionState(root, sessionId)) !== null;
+}
+
+/** Append a single severity envelope to events.jsonl. Single-writer discipline is the owner's job (M3). */
+export async function appendEvent(root: string, sessionId: string, envelope: EventEnvelope): Promise<void> {
+	const paths = sessionPaths(root, sessionId);
+	await fs.mkdir(paths.dir, { recursive: true });
+	await fs.appendFile(paths.events, `${JSON.stringify(envelope)}\n`, "utf8");
+}
+
+/** Read events from cursor (exclusive). Tail-only: never mutates the log. */
+export async function readEvents(root: string, sessionId: string, fromCursor = 0): Promise<EventEnvelope[]> {
+	const paths = sessionPaths(root, sessionId);
+	let raw: string;
+	try {
+		raw = await fs.readFile(paths.events, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const out: EventEnvelope[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const env = JSON.parse(trimmed) as EventEnvelope;
+		if (env.cursor > fromCursor) out.push(env);
+	}
+	return out;
+}
+
+export interface ReceiptIndexEntry {
+	receiptId: string;
+	family: ReceiptFamily;
+	valid: boolean;
+	createdAt: string;
+	path: string;
+}
+
+/**
+ * Persist a receipt immutably. Fails closed if the receipt id already exists,
+ * then appends an index entry to receipts.jsonl.
+ */
+export async function writeReceiptImmutable(
+	root: string,
+	sessionId: string,
+	family: ReceiptFamily,
+	receiptId: string,
+	value: { receiptId: string; family: ReceiptFamily; valid: boolean; createdAt: string },
+): Promise<ReceiptIndexEntry> {
+	assertSafeSessionId(sessionId);
+	if (!SESSION_ID_RE.test(receiptId)) {
+		throw new StorageError(`unsafe_receipt_id:${receiptId}`, "unsafe_receipt_id");
+	}
+	const paths = sessionPaths(root, sessionId);
+	const familyDir = path.join(paths.receiptsDir, family);
+	const file = path.join(familyDir, `${receiptId}.json`);
+	await fs.mkdir(familyDir, { recursive: true });
+	try {
+		await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new StorageError(`receipt_immutable_conflict:${family}/${receiptId}`, "receipt_immutable_conflict");
+		}
+		throw error;
+	}
+	const entry: ReceiptIndexEntry = {
+		receiptId,
+		family,
+		valid: value.valid,
+		createdAt: value.createdAt,
+		path: file,
+	};
+	await fs.appendFile(paths.receiptsIndex, `${JSON.stringify(entry)}\n`, "utf8");
+	return entry;
+}
+
+export async function readReceiptIndex(
+	root: string,
+	sessionId: string,
+	family?: ReceiptFamily,
+): Promise<ReceiptIndexEntry[]> {
+	const paths = sessionPaths(root, sessionId);
+	let raw: string;
+	try {
+		raw = await fs.readFile(paths.receiptsIndex, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const out: ReceiptIndexEntry[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const entry = JSON.parse(trimmed) as ReceiptIndexEntry;
+		if (!family || entry.family === family) out.push(entry);
+	}
+	return out;
+}

package/src/harness-control-plane/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Core types for the gajae-code-native coding-harness operations control plane (v1).
+ *
+ * See the approved consensus plan at
+ * `.gjc/plans/ralplan/2026-06-02-0853-3e33/stage-02-revision.md` and the spec at
+ * `.gjc/specs/deep-interview-harness-control-plane.md`.
+ *
+ * v1 implements the gajae-code adapter only. omx/codex/remote/auth are deferred seams.
+ */
+
+/** Harnesses the control plane can operate. v1 implements `gajae-code` only. */
+export type Harness = "gajae-code" | "codex" | "omx";
+
+/** Lifecycle states of an operated session. */
+export type HarnessLifecycle =
+	| "new"
+	| "started"
+	| "submitted"
+	| "observing"
+	| "recovering"
+	| "validating"
+	| "finalizing"
+	| "completed"
+	| "blocked"
+	| "retired";
+
+/** Event severities emitted by the owner. */
+export type Severity = "info" | "warn" | "critical";
+
+/** Bounded git delta classification surfaced by `observe`. */
+export type GitDelta = "clean" | "dirty" | "zero-delta" | "unknown";
+
+/** Risk classification surfaced by `observe`. */
+export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "vanished-dirty";
+
+/** Deterministic recovery classifications. */
+export type RecoveryClassification =
+	| "continue"
+	| "send-enter"
+	| "reinject-prompt"
+	| "restart-clean"
+	| "restart-preserve-delta"
+	| "fallback-codex-exec"
+	| "human-check";
+
+/** Receipt families persisted under the session storage dir. */
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion";
+
+/** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
+export type HarnessVerb =
+	| "start"
+	| "submit"
+	| "observe"
+	| "classify"
+	| "recover"
+	| "validate"
+	| "finalize"
+	| "retire"
+	| "events"
+	| "monitor"
+	| "operate";
+
+/** Submission transports. */
+export type SubmitMode = "paste-buffer" | "stdin" | "file";
+
+/** A single entry in the forcing-function `nextAllowedActions` list. */
+export interface NextAllowedAction {
+	verb: HarnessVerb;
+	available: boolean;
+	/** Present when `available` is false; explains why the verb is currently disallowed. */
+	reason?: string;
+}
+
+/** Compact, model-facing view of session state included in every response. */
+export interface SessionStateView {
+	sessionId: string;
+	lifecycle: HarnessLifecycle;
+	harness: Harness;
+	ownerLive: boolean;
+	blockers: string[];
+}
+
+/**
+ * The universal contract: EVERY primitive response carries `{state, evidence, nextAllowedActions}`.
+ * `ok` is a transport-level convenience; semantic blocking is expressed via state + nextAllowedActions.
+ */
+export interface PrimitiveResponse<E = Record<string, unknown>> {
+	ok: boolean;
+	state: SessionStateView;
+	evidence: E;
+	nextAllowedActions: NextAllowedAction[];
+}
+
+/** Re-grabbable session handle returned by `start` / `operate`. */
+export interface SessionHandle {
+	sessionId: string;
+	harness: Harness;
+	repo: string | null;
+	workspace: string;
+	branch: string | null;
+	base: string | null;
+	issueOrPr: string | null;
+	processHandle: { kind: "runtime-owner"; ownerId: string | null; pid: number | null };
+	rpcHandle: { kind: "rpc-subprocess"; pid: number | null; sessionDir: string };
+	ownerHandle: { leasePath: string; endpoint: string | null; heartbeatAt: string | null };
+	routerHandle: { kind: "default-in-owner"; policy: string; eventsPath: string };
+	viewportHandle: { kind: "event-monitor"; tmuxSessionName: string | null; viewOnly: true };
+	startedAt: string;
+	updatedAt: string;
+}
+
+/** Persisted per-session record (state.json). */
+export interface SessionState {
+	schemaVersion: number;
+	sessionId: string;
+	lifecycle: HarnessLifecycle;
+	harness: Harness;
+	handle: SessionHandle;
+	/** Per-classification retry counters consumed by the recovery policy. */
+	retries: Record<string, number>;
+	blockers: string[];
+	createdAt: string;
+	updatedAt: string;
+}
+
+/** Bounded observed-signal vocabulary surfaced by `observe` (the owner only ever emits these). */
+export type ObservedSignal =
+	| "SessionStart"
+	| "prompt-accepted"
+	| "tool-call"
+	| "test-running"
+	| "commit-created"
+	| "completed"
+	| "error"
+	| "streaming"
+	| "idle";
+
+export const OBSERVED_SIGNALS: readonly ObservedSignal[] = [
+	"SessionStart",
+	"prompt-accepted",
+	"tool-call",
+	"test-running",
+	"commit-created",
+	"completed",
+	"error",
+	"streaming",
+	"idle",
+];
+
+/** Bounded observation surfaced by `observe` — never a raw pane/transcript dump. */
+export interface Observation {
+	lifecycle: HarnessLifecycle;
+	ownerLive: boolean;
+	cwd: string;
+	branch: string | null;
+	gitDelta: GitDelta;
+	lastActivityAt: string | null;
+	observedSignals: string[];
+	risk: RiskKind;
+	/** RPC subprocess liveness, distinct from owner-process/lease liveness. Optional for back-compat. */
+	rpcLive?: boolean;
+	/** ISO timestamp of the most recent RPC frame the owner observed, if any. */
+	rpcLastFrameAt?: string | null;
+}
+
+/** Input to the deterministic recovery classifier. */
+export interface ClassifyInput {
+	observation: Observation;
+	/** Remaining retry budget per classification family. */
+	retryBudget: RetryBudget;
+	/** Whether an accepted prompt was in flight when the owner/RPC was last seen. */
+	acceptedPromptActive?: boolean;
+}
+
+/** Default and supplied retry budgets. */
+export interface RetryBudget {
+	reinjectPrompt: number;
+	zeroDeltaVanish: number;
+	dirtyVanishPreserve: number;
+	validationRepair: number;
+}
+
+/** Result of the deterministic recovery classifier. */
+export interface RecoveryDecision {
+	classification: RecoveryClassification;
+	reason: string;
+	severity: Severity;
+	/** Whether executing the recommended action requires a live owner. */
+	ownerRequired: boolean;
+	/** Receipt family that MUST be valid before the action may proceed (e.g. `vanish`). */
+	requiredReceiptFamily: ReceiptFamily | null;
+}
+
+/** Severity-tagged event envelope written exclusively by the owner. */
+export interface EventEnvelope<E = Record<string, unknown>> {
+	eventId: string;
+	cursor: number;
+	createdAt: string;
+	severity: Severity;
+	kind: string;
+	state: SessionStateView;
+	evidence: E;
+	nextAllowedActions: NextAllowedAction[];
+	writer: { ownerId: string; leaseEpoch: number };
+}
+
+export const SESSION_SCHEMA_VERSION = 1 as const;
+
+export const DEFAULT_RETRY_BUDGET: RetryBudget = {
+	reinjectPrompt: 2,
+	zeroDeltaVanish: 1,
+	dirtyVanishPreserve: 1,
+	validationRepair: 2,
+};

package/src/hooks/skill-keywords.ts

@@ -1,3 +1,5 @@
+import { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+
 export interface SkillKeywordDefinition {
 	keyword: string;
 	skill: GjcWorkflowSkill;
@@ -5,9 +7,9 @@ export interface SkillKeywordDefinition {
 	guidance: string;
 }
 
-export const GJC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
+export const GJC_WORKFLOW_SKILLS = CANONICAL_GJC_WORKFLOW_SKILLS;
 
-export type GjcWorkflowSkill = (typeof GJC_WORKFLOW_SKILLS)[number];
+export type GjcWorkflowSkill = CanonicalGjcWorkflowSkill;
 
 export const GJC_SKILL_KEYWORD_DEFINITIONS: readonly SkillKeywordDefinition[] = [
 	{

package/src/hooks/skill-state.ts

@@ -1,9 +1,13 @@
-import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
+import { writeJsonAtomic } from "../gjc-runtime/state-writer";
 import { isUltragoalBypassPrompt, readUltragoalVerificationState } from "../gjc-runtime/ultragoal-guard";
 import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
-import type { SkillActiveEntry as CanonicalSkillActiveEntry, WorkflowHudSummary } from "../skill-state/active-state";
+import {
+	readVisibleSkillActiveState as readCanonicalVisibleSkillActiveState,
+	type SkillActiveEntry,
+	type SkillActiveState,
+} from "../skill-state/active-state";
 import {
 	compareSkillKeywordMatches,
 	GJC_SKILL_KEYWORD_DEFINITIONS,
@@ -74,35 +78,7 @@ export interface SkillKeywordMatch {
 	priority: number;
 }
 
-export interface SkillActiveEntry extends Omit<CanonicalSkillActiveEntry, "skill"> {
-	skill: GjcWorkflowSkill;
-	phase?: string;
-	active?: boolean;
-	activated_at?: string;
-	updated_at?: string;
-	session_id?: string;
-	thread_id?: string;
-	turn_id?: string;
-	hud?: WorkflowHudSummary;
-	stale?: boolean;
-}
-
-export interface SkillActiveState {
-	version: number;
-	active: boolean;
-	skill: GjcWorkflowSkill;
-	keyword: string;
-	phase: string;
-	activated_at: string;
-	updated_at: string;
-	source: "gjc-skill-state-hook";
-	session_id?: string;
-	thread_id?: string;
-	turn_id?: string;
-	initialized_mode?: GjcWorkflowSkill;
-	initialized_state_path?: string;
-	active_skills: SkillActiveEntry[];
-}
+export type { SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 
 export interface ModeState {
 	active?: boolean;
@@ -252,9 +228,11 @@ async function readJsonFile<T>(filePath: string): Promise<T | null> {
 	}
 }
 
-async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await Bun.write(filePath, `${JSON.stringify(value, null, 2)}\n`);
+async function writeJsonFile(filePath: string, value: unknown, cwd: string): Promise<void> {
+	await writeJsonAtomic(filePath, value, {
+		cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-hook" },
+	});
 }
 
 function entryMatchesContext(
@@ -272,7 +250,11 @@ function entryMatchesContext(
 
 function listActiveSkills(state: SkillActiveState | null): SkillActiveEntry[] {
 	if (!state?.active) return [];
-	return state.active_skills.filter(entry => entry.active !== false);
+	return (state.active_skills ?? []).filter(entry => entry.active !== false);
+}
+
+function isWorkflowActiveEntry(entry: SkillActiveEntry): entry is SkillActiveEntry & { skill: GjcWorkflowSkill } {
+	return isGjcWorkflowSkill(entry.skill);
 }
 
 export async function readVisibleSkillActiveState(
@@ -280,6 +262,7 @@ export async function readVisibleSkillActiveState(
 	sessionId?: string,
 	stateDir?: string,
 ): Promise<SkillActiveState | null> {
+	if (!stateDir) return await readCanonicalVisibleSkillActiveState(cwd, sessionId);
 	const resolvedStateDir = resolveGjcStateDir(cwd, stateDir);
 	if (sessionId) {
 		const sessionState = await readJsonFile<SkillActiveState>(skillStatePath(resolvedStateDir, sessionId));
@@ -337,10 +320,10 @@ export async function recordSkillActivation(input: RecordSkillActivationInput):
 		modeState.threshold_source = "default";
 	}
 
-	await writeJsonFile(initializedStatePath, modeState);
-	await writeJsonFile(skillStatePath(resolvedStateDir, input.sessionId), state);
+	await writeJsonFile(initializedStatePath, modeState, input.cwd);
+	await writeJsonFile(skillStatePath(resolvedStateDir, input.sessionId), state, input.cwd);
 	if (!input.sessionId) return state;
-	await writeJsonFile(skillStatePath(resolvedStateDir), state);
+	await writeJsonFile(skillStatePath(resolvedStateDir), state, input.cwd);
 	return state;
 }
 
@@ -432,9 +415,9 @@ export async function buildActiveUltragoalPromptContext(input: UserPromptSubmitS
 export async function buildSkillStopOutput(input: StopHookInput): Promise<Record<string, unknown> | null> {
 	const resolvedStateDir = resolveGjcStateDir(input.cwd, input.stateDir);
 	const skillState = await readVisibleSkillActiveState(input.cwd, input.sessionId, input.stateDir);
-	const activeEntries = listActiveSkills(skillState).filter(entry =>
-		skillState ? entryMatchesContext(entry, skillState, input.sessionId, input.threadId) : false,
-	);
+	const activeEntries = listActiveSkills(skillState)
+		.filter(isWorkflowActiveEntry)
+		.filter(entry => (skillState ? entryMatchesContext(entry, skillState, input.sessionId, input.threadId) : false));
 	if (!skillState || activeEntries.length === 0) return null;
 
 	for (const entry of activeEntries) {