@gajae-code/coding-agent 0.3.0 → 0.3.2

package/src/gjc-runtime/state-schema.ts

@@ -0,0 +1,192 @@
+/**
+ * Canonical zod schemas for GJC workflow state (Workstream A, v4).
+ *
+ * Schemas are **lenient/additive** (`.passthrough()`): unknown keys are
+ * preserved, non-anchored fields are optional. This upholds the binding v2
+ * read contract — reads never reject evolving/old state. The strict
+ * `RequiredOnWriteEnvelopeSchema` is the WRITE-side gate (fail-closed), anchored
+ * to exactly what the sanctioned writer emits.
+ *
+ * These schemas describe the persisted `WorkflowStateReceipt`/envelope; they are
+ * a distinct concept from the `CliWriteReceipt` stdout presentation type.
+ */
+import * as fs from "node:fs/promises";
+import { z } from "zod";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-version";
+
+const CANONICAL_GJC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
+const skillEnum = z.enum([...CANONICAL_GJC_WORKFLOW_SKILLS]);
+const ownerEnum = z.enum(["gjc-state-cli", "gjc-runtime", "gjc-hook"]);
+const receiptStatusEnum = z.enum(["fresh", "stale"]);
+
+export const WorkflowStateContentChecksumSchema = z
+	.object({
+		algorithm: z.literal("sha256"),
+		value: z.string(),
+		covered_path: z.string(),
+		computed_at: z.string(),
+	})
+	.passthrough();
+
+/** Lenient receipt schema for reads (mirrors WorkflowStateReceipt). */
+export const WorkflowStateReceiptSchema = z
+	.object({
+		version: z.number(),
+		skill: skillEnum,
+		owner: ownerEnum,
+		command: z.string(),
+		state_path: z.string(),
+		storage_path: z.string(),
+		mutated_at: z.string(),
+		fresh_until: z.string(),
+		status: receiptStatusEnum,
+		mutation_id: z.string(),
+		verb: z.string().optional(),
+		from_phase: z.string().optional(),
+		to_phase: z.string().optional(),
+		forced: z.boolean().optional(),
+		paths: z.array(z.string()).optional(),
+		content_sha256: WorkflowStateContentChecksumSchema.optional(),
+	})
+	.passthrough();
+
+/** Lenient envelope schema for reads. Every non-structural field optional. */
+export const WorkflowStateEnvelopeSchema = z
+	.object({
+		skill: z.string().optional(),
+		active: z.boolean().optional(),
+		current_phase: z.string().optional(),
+		version: z.number().optional(),
+		updated_at: z.string().optional(),
+		session_id: z.string().optional(),
+		receipt: WorkflowStateReceiptSchema.optional(),
+	})
+	.passthrough();
+
+/**
+ * Strict receipt required on WRITE (post checksum-stamping). Anchored to the
+ * fields the sanctioned writer emits — `content_sha256` is REQUIRED here.
+ */
+export const RequiredWorkflowStateReceiptSchema = z
+	.object({
+		version: z.number(),
+		skill: skillEnum,
+		owner: ownerEnum,
+		command: z.string(),
+		state_path: z.string(),
+		storage_path: z.string(),
+		mutated_at: z.string(),
+		fresh_until: z.string(),
+		status: receiptStatusEnum,
+		mutation_id: z.string(),
+		content_sha256: WorkflowStateContentChecksumSchema,
+	})
+	.passthrough();
+
+/**
+ * Write-side fail-closed gate: the serialized on-disk envelope must satisfy
+ * this after checksum stamping. Anchored to current sanctioned-writer output.
+ */
+export const RequiredOnWriteEnvelopeSchema = z
+	.object({
+		skill: skillEnum,
+		version: z.literal(WORKFLOW_STATE_VERSION),
+		updated_at: z.string(),
+		current_phase: z.string(),
+		active: z.boolean(),
+		receipt: RequiredWorkflowStateReceiptSchema,
+	})
+	.passthrough();
+
+/** Per-skill mode state consumed by hooks / the mutation guard. */
+export const ModeStateSchema = z
+	.object({
+		active: z.boolean().optional(),
+		current_phase: z.string().optional(),
+		skill: z.string().optional(),
+		session_id: z.string().optional(),
+		thread_id: z.string().optional(),
+		cwd: z.string().optional(),
+		updated_at: z.string().optional(),
+		handoff_from: z.string().optional(),
+		handoff_to: z.string().optional(),
+		handoff_at: z.string().optional(),
+	})
+	.passthrough();
+
+export const SkillActiveEntrySchema = z
+	.object({
+		skill: z.string(),
+		phase: z.string().optional(),
+		active: z.boolean().optional(),
+		activated_at: z.string().optional(),
+		updated_at: z.string().optional(),
+		session_id: z.string().optional(),
+		thread_id: z.string().optional(),
+		turn_id: z.string().optional(),
+		stale: z.boolean().optional(),
+		handoff_from: z.string().optional(),
+		handoff_to: z.string().optional(),
+		handoff_at: z.string().optional(),
+		receipt: WorkflowStateReceiptSchema.optional(),
+	})
+	.passthrough();
+
+export const SkillActiveStateSchema = z
+	.object({
+		version: z.number().optional(),
+		active: z.boolean().optional(),
+		skill: z.string().optional(),
+		keyword: z.string().optional(),
+		phase: z.string().optional(),
+		activated_at: z.string().optional(),
+		updated_at: z.string().optional(),
+		source: z.string().optional(),
+		session_id: z.string().optional(),
+		thread_id: z.string().optional(),
+		turn_id: z.string().optional(),
+		active_skills: z.array(SkillActiveEntrySchema).optional(),
+	})
+	.passthrough();
+
+export type WorkflowStateEnvelope = z.infer<typeof WorkflowStateEnvelopeSchema>;
+export type RequiredOnWriteEnvelope = z.infer<typeof RequiredOnWriteEnvelopeSchema>;
+export type ModeStateParsed = z.infer<typeof ModeStateSchema>;
+export type SkillActiveStateParsed = z.infer<typeof SkillActiveStateSchema>;
+
+/**
+ * Validated read result.
+ * - `null`        → file absent (ENOENT); callers treat as no state.
+ * - `{ok:true}`   → parsed + schema-valid.
+ * - `{ok:false}`  → present but unparseable or schema-invalid. Callers fail
+ *                   OPEN (normalize/log), never crash — preserving v2 reads.
+ */
+export type ReadGjcJsonResult<T> = { ok: true; value: T; raw: unknown } | { ok: false; error: string; raw: unknown };
+
+function isEnoent(error: unknown): boolean {
+	return Boolean(error) && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+/**
+ * Parse + schema-validate a `.gjc` JSON file at the read boundary.
+ * Returns `null` when the file is absent. Fail-open: an invalid file yields
+ * `{ ok: false }` with the raw value attached so the caller can normalize/log.
+ */
+export async function readGjcJson<T>(filePath: string, schema: z.ZodType<T>): Promise<ReadGjcJsonResult<T> | null> {
+	let text: string;
+	try {
+		text = await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		return { ok: false, error: `read error: ${(error as Error).message}`, raw: undefined };
+	}
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (error) {
+		return { ok: false, error: `invalid JSON: ${(error as Error).message}`, raw: text };
+	}
+	const parsed = schema.safeParse(raw);
+	if (parsed.success) return { ok: true, value: parsed.data, raw };
+	return { ok: false, error: parsed.error.message, raw };
+}

package/src/gjc-runtime/state-writer.ts

@@ -9,6 +9,7 @@ import {
 	type WorkflowStateMutationOwner,
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
+import { RequiredOnWriteEnvelopeSchema } from "./state-schema";
 
 /**
  * Sole sanctioned project `.gjc/**` writer module (gate G1).
@@ -131,6 +132,27 @@ export class AlreadyExistsError extends Error {
 	}
 }
 
+export type StrictMutationReadResult =
+	| { kind: "absent" }
+	| { kind: "corrupt"; error: string }
+	| { kind: "valid"; value: Record<string, unknown> };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export async function readExistingStateForMutation(filePath: string): Promise<StrictMutationReadResult> {
+	try {
+		const raw = await fs.readFile(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (isPlainObject(parsed)) return { kind: "valid", value: parsed };
+		return { kind: "corrupt", error: "state file must contain a JSON object" };
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return { kind: "absent" };
+		return { kind: "corrupt", error: err.message };
+	}
+}
 function isErrno(error: unknown, code: string): boolean {
 	return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === code;
 }
@@ -357,7 +379,16 @@ export async function writeWorkflowEnvelopeAtomic(
 ): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
 	const withReceipt = withWorkflowReceipt(value, buildReceipt(options));
-	await atomicWrite(filePath, jsonText(stampWorkflowEnvelopeChecksum(withReceipt, filePath)));
+	const stamped = stampWorkflowEnvelopeChecksum(withReceipt, filePath);
+	const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
+	if (!parsed.success) {
+		throw new Error(
+			`Refusing to write invalid workflow state envelope to ${filePath}: ${parsed.error.issues
+				.map(issue => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+				.join("; ")}`,
+		);
+	}
+	await atomicWrite(filePath, jsonText(stamped));
 	await maybeAudit(filePath, options);
 	return filePath;
 }

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

@@ -3,6 +3,8 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 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 {
 	AlreadyExistsError,
@@ -13,6 +15,7 @@ import {
 	removeFileAudited,
 	writeJsonAtomic,
 	writeReport,
+	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import { GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE } from "./tmux-common";
 
@@ -283,6 +286,55 @@ export interface GjcTeamMailboxMessage {
 	idempotency_key?: string;
 }
 
+function taskReceiptFields(teamName: string, task: GjcTeamTask): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		task_id: task.id,
+		status: task.status,
+		owner: task.owner,
+		worker_id: task.claim?.owner ?? task.owner ?? task.assignee,
+	};
+}
+
+function mailboxMessageReceiptFields(teamName: string, message: GjcTeamMailboxMessage): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		message_id: message.message_id,
+		from_worker: message.from_worker,
+		to_worker: message.to_worker,
+		delivered: Boolean(message.delivered_at),
+		notified: Boolean(message.notified_at),
+		delivered_at: message.delivered_at,
+		notified_at: message.notified_at,
+	};
+}
+
+function notificationReceiptFields(notification: GjcTeamNotification): Record<string, unknown> {
+	return {
+		team_name: notification.team_name,
+		notification_id: notification.id,
+		recipient: notification.recipient,
+		source_type: notification.source.type,
+		source_id: notification.source.id,
+		delivery_state: notification.delivery_state,
+		pane_attempt_result: notification.pane_attempt_result,
+		pane_attempt_reason: notification.pane_attempt_reason,
+		replay_count: notification.replay_count,
+	};
+}
+
+function notificationSummaryReceipt(
+	teamName: string,
+	result: { notifications: GjcTeamNotification[]; summary: GjcTeamNotificationSummary },
+): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		notification_ids: result.notifications.map(notification => notification.id),
+		delivery_states: result.notifications.map(notification => notification.delivery_state),
+		summary: result.summary,
+	};
+}
+
 interface FsError {
 	code?: string;
 }
@@ -950,11 +1002,11 @@ function teamModeStatePath(): string {
 export async function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot, cwd = process.cwd()): Promise<void> {
 	const active = snapshot.phase !== "complete" && snapshot.phase !== "cancelled";
 	const updatedAt = now();
-	await writeJsonAtomic(
+	await writeWorkflowEnvelopeAtomic(
 		teamModeStatePath(),
 		{
 			skill: "team",
-			version: 1,
+			version: WORKFLOW_STATE_VERSION,
 			active,
 			current_phase: snapshot.phase,
 			team_name: snapshot.team_name,
@@ -3746,121 +3798,142 @@ export async function executeGjcTeamApiOperation(
 			return { tasks: await listGjcTeamTasks(teamName, cwd, env) };
 		case "read-task":
 			return { task: await readGjcTeamTask(teamName, String(input.task_id ?? input.taskId), cwd, env) };
-		case "create-task":
-			return {
-				task: await createGjcTeamTask(
-					teamName,
-					String(input.subject ?? "Task"),
-					String(input.description ?? ""),
-					cwd,
-					env,
-					taskMetadataFromInput(input, true),
-				),
-			};
-		case "update-task":
-			return {
-				task: await updateGjcTeamTask(
-					teamName,
-					String(input.task_id ?? input.taskId),
-					{
-						subject: typeof input.subject === "string" ? input.subject : undefined,
-						description: typeof input.description === "string" ? input.description : undefined,
-						...taskMetadataFromInput(input),
-					},
-					cwd,
-					env,
-				),
-			};
+		case "create-task": {
+			const task = await createGjcTeamTask(
+				teamName,
+				String(input.subject ?? "Task"),
+				String(input.description ?? ""),
+				cwd,
+				env,
+				taskMetadataFromInput(input, true),
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task) };
+		}
+		case "update-task": {
+			const task = await updateGjcTeamTask(
+				teamName,
+				String(input.task_id ?? input.taskId),
+				{
+					subject: typeof input.subject === "string" ? input.subject : undefined,
+					description: typeof input.description === "string" ? input.description : undefined,
+					...taskMetadataFromInput(input),
+				},
+				cwd,
+				env,
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task) };
+		}
 		case "claim-task": {
 			const requestedTaskId = input.task_id ?? input.taskId;
-			return claimGjcTeamTask(
+			const result = await claimGjcTeamTask(
 				teamName,
 				worker,
 				cwd,
 				env,
 				typeof requestedTaskId === "string" ? requestedTaskId : undefined,
 			);
+			return {
+				ok: result.ok,
+				reason: result.reason,
+				team_name: teamName,
+				worker_id: result.worker_id ?? worker,
+				...(result.task ? taskReceiptFields(teamName, result.task) : {}),
+				claim_token: result.claim_token,
+			};
 		}
 		case "transition-task":
-		case "transition-task-status":
+		case "transition-task-status": {
+			const task = await transitionGjcTeamTaskStatus(
+				teamName,
+				String(input.task_id ?? input.taskId),
+				parseGjcTeamTaskStatus(input.to ?? input.status),
+				cwd,
+				env,
+				typeof input.claim_token === "string" ? input.claim_token : undefined,
+				explicitWorker,
+				input.completion_evidence ?? input.completionEvidence,
+			);
 			return {
 				ok: true,
-				task: await transitionGjcTeamTaskStatus(
-					teamName,
-					String(input.task_id ?? input.taskId),
-					parseGjcTeamTaskStatus(input.to ?? input.status),
-					cwd,
-					env,
-					typeof input.claim_token === "string" ? input.claim_token : undefined,
-					explicitWorker,
-					input.completion_evidence ?? input.completionEvidence,
-				),
+				...taskReceiptFields(teamName, task),
+				worker_id: explicitWorker ?? task.owner ?? task.assignee,
 			};
-		case "release-task-claim":
+		}
+		case "release-task-claim": {
+			const task = await releaseGjcTeamTaskClaim(
+				teamName,
+				String(input.task_id),
+				String(input.claim_token),
+				worker,
+				cwd,
+				env,
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task), worker_id: worker };
+		}
+		case "send-message": {
+			const message = await sendGjcTeamMessage(
+				teamName,
+				String(input.from_worker),
+				String(input.to_worker),
+				String(input.body),
+				cwd,
+				env,
+				typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
+		case "broadcast": {
+			const messages = await broadcastGjcTeamMessage(
+				teamName,
+				String(input.from_worker),
+				String(input.body),
+				cwd,
+				env,
+				typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
+			);
 			return {
 				ok: true,
-				task: await releaseGjcTeamTaskClaim(
-					teamName,
-					String(input.task_id),
-					String(input.claim_token),
-					worker,
-					cwd,
-					env,
-				),
-			};
-		case "send-message":
-			return {
-				message: await sendGjcTeamMessage(
-					teamName,
-					String(input.from_worker),
-					String(input.to_worker),
-					String(input.body),
-					cwd,
-					env,
-					typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
-				),
-			};
-		case "broadcast":
-			return {
-				messages: await broadcastGjcTeamMessage(
-					teamName,
-					String(input.from_worker),
-					String(input.body),
-					cwd,
-					env,
-					typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
-				),
+				team_name: teamName,
+				message_ids: messages.map(message => message.message_id),
+				delivery_states: messages.map(message => ({
+					message_id: message.message_id,
+					to_worker: message.to_worker,
+					delivered: Boolean(message.delivered_at),
+					notified: Boolean(message.notified_at),
+				})),
 			};
+		}
 		case "mailbox-list":
 			return { messages: await listGjcTeamMailbox(teamName, worker, cwd, env) };
-		case "mailbox-mark-delivered":
-			return {
-				message: await markGjcTeamMailboxMessage(
-					teamName,
-					worker,
-					String(input.message_id),
-					"delivered_at",
-					cwd,
-					env,
-				),
-			};
-		case "mailbox-mark-notified":
-			return {
-				message: await markGjcTeamMailboxMessage(
-					teamName,
-					worker,
-					String(input.message_id),
-					"notified_at",
-					cwd,
-					env,
-				),
-			};
+		case "mailbox-mark-delivered": {
+			const message = await markGjcTeamMailboxMessage(
+				teamName,
+				worker,
+				String(input.message_id),
+				"delivered_at",
+				cwd,
+				env,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
+		case "mailbox-mark-notified": {
+			const message = await markGjcTeamMailboxMessage(
+				teamName,
+				worker,
+				String(input.message_id),
+				"notified_at",
+				cwd,
+				env,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
 		case "notification-list": {
 			const dir = await findTeamDir(teamName, cwd, env);
 			const config = await readConfig(dir);
 			await reconcileTeamNotifications(dir, config);
 			const notifications = await listNotificationRecords(dir);
-			return { notifications, summary: summarizeNotifications(notifications) };
+			const result = { notifications, summary: summarizeNotifications(notifications) };
+			return notificationSummaryReceipt(teamName, result);
 		}
 		case "notification-read":
 			return {
@@ -3870,20 +3943,19 @@ export async function executeGjcTeamApiOperation(
 				),
 			};
 		case "notification-replay":
-			return replayGjcTeamNotifications(teamName, cwd, env);
+			return notificationSummaryReceipt(teamName, await replayGjcTeamNotifications(teamName, cwd, env));
 		case "notification-mark-pane-attempt": {
 			const dir = await findTeamDir(teamName, cwd, env);
 			const notification = await readNotificationRecord(dir, String(input.notification_id));
-			return {
-				notification: await writeNotificationRecord(dir, {
-					...notification,
-					delivery_state: parsePaneAttemptResult(String(input.result ?? "failed")),
-					pane_attempt_result: parsePaneAttemptResult(String(input.result ?? "failed")),
-					pane_attempt_reason: String(input.reason ?? "manual_api"),
-					pane_attempt_at: now(),
-					updated_at: now(),
-				}),
-			};
+			const updated = await writeNotificationRecord(dir, {
+				...notification,
+				delivery_state: parsePaneAttemptResult(String(input.result ?? "failed")),
+				pane_attempt_result: parsePaneAttemptResult(String(input.result ?? "failed")),
+				pane_attempt_reason: String(input.reason ?? "manual_api"),
+				pane_attempt_at: now(),
+				updated_at: now(),
+			});
+			return { ok: true, ...notificationReceiptFields(updated) };
 		}
 		case "worker-startup-ack":
 			return writeGjcWorkerStartupAck(teamName, worker, cwd, env, input);