@gajae-code/coding-agent 0.18.7 → 0.18.9

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

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import type * as nodeFs from "node:fs";
 import { constants as fsConstants, type Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
@@ -89,6 +90,7 @@ export interface WorkflowTransactionJournal {
 	callee?: CanonicalGjcWorkflowSkill;
 	paths: string[];
 	steps: string[];
+	approval_audit_offset?: number;
 }
 
 export type StateWritePolicy = "source" | "cache";
@@ -308,19 +310,33 @@ export function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, com
 	return envelope as T;
 }
 
-export async function detectWorkflowEnvelopeIntegrityMismatch(
-	filePath: string,
-): Promise<WorkflowEnvelopeIntegrityMismatch | undefined> {
-	const current = await readJsonIfPresent(filePath);
-	if (!current || typeof current !== "object" || Array.isArray(current)) return undefined;
-	const receipt = (current as Record<string, unknown>).receipt;
+export type WorkflowEnvelopeChecksumStatus = "absent" | "match" | "mismatch";
+
+/** Compare a parsed envelope to its writer-stamped `content_sha256`, when one is present. */
+export function workflowEnvelopeChecksumStatus(value: unknown): WorkflowEnvelopeChecksumStatus {
+	const checksum = workflowEnvelopeChecksumPair(value);
+	if (!checksum) return "absent";
+	return checksum.actual === checksum.expected ? "match" : "mismatch";
+}
+
+function workflowEnvelopeChecksumPair(value: unknown): { expected: string; actual: string } | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const receipt = (value as Record<string, unknown>).receipt;
 	if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return undefined;
 	const checksum = (receipt as Record<string, unknown>).content_sha256;
 	if (!checksum || typeof checksum !== "object" || Array.isArray(checksum)) return undefined;
 	const expected = (checksum as Record<string, unknown>).value;
 	if (typeof expected !== "string" || !expected) return undefined;
-	const actual = workflowEnvelopeContentSha256(current);
-	return actual === expected ? undefined : { path: filePath, expected, actual };
+	return { expected, actual: workflowEnvelopeContentSha256(value) };
+}
+
+export async function detectWorkflowEnvelopeIntegrityMismatch(
+	filePath: string,
+): Promise<WorkflowEnvelopeIntegrityMismatch | undefined> {
+	const current = await readJsonIfPresent(filePath);
+	const checksum = workflowEnvelopeChecksumPair(current);
+	if (!checksum || checksum.actual === checksum.expected) return undefined;
+	return { path: filePath, expected: checksum.expected, actual: checksum.actual };
 }
 
 function safeString(value: unknown): string {
@@ -1368,9 +1384,16 @@ export async function removeActiveEntry(
 	);
 }
 
-export async function readActiveEntries(
+/**
+ * Read every per-skill active entry. Unreadable JSON propagates; a parsed record
+ * that is not a skill entry (not an object, or without a `skill`) is skipped, or
+ * rejected when `strict` is set so status-bearing readers can tell an existing
+ * but unusable authoritative entry apart from a deleted one.
+ */
+async function readActiveEntriesFromDir(
 	cwd: string,
-	sessionScope?: string | ActiveSessionScope,
+	sessionScope: string | ActiveSessionScope | undefined,
+	strict: boolean,
 ): Promise<SkillActiveEntry[]> {
 	const dir = activeStateDir(path.resolve(cwd), sessionScope);
 	let names: string[];
@@ -1383,15 +1406,38 @@ export async function readActiveEntries(
 	const entries: SkillActiveEntry[] = [];
 	for (const name of names.sort()) {
 		if (!name.endsWith(".json")) continue;
-		const raw = await readJsonIfPresent(path.join(dir, name));
-		if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
-		const skill = safeString((raw as SkillActiveEntry).skill).trim();
-		if (!skill) continue;
+		const filePath = path.join(dir, name);
+		const raw = await readJsonIfPresent(filePath);
+		if (raw === undefined) continue;
+		const skill = isPlainObject(raw) ? safeString(raw.skill).trim() : "";
+		if (!skill) {
+			if (strict) throw new Error(`active entry at ${filePath} is not a skill entry record`);
+			continue;
+		}
 		entries.push(raw as SkillActiveEntry);
 	}
 	return entries;
 }
 
+export async function readActiveEntries(
+	cwd: string,
+	sessionScope?: string | ActiveSessionScope,
+): Promise<SkillActiveEntry[]> {
+	return readActiveEntriesFromDir(cwd, sessionScope, false);
+}
+
+/**
+ * Failure-observable counterpart of `readActiveEntries`: an entry file that exists
+ * but holds no usable skill entry throws instead of being skipped, so its absence
+ * from the result always means the entry does not exist.
+ */
+export async function readActiveEntriesStrict(
+	cwd: string,
+	sessionScope?: string | ActiveSessionScope,
+): Promise<SkillActiveEntry[]> {
+	return readActiveEntriesFromDir(cwd, sessionScope, true);
+}
+
 export async function rebuildActiveSnapshot(
 	cwd: string,
 	sessionScope?: string | ActiveSessionScope,
@@ -1559,6 +1605,7 @@ export async function appendAuditEntry(
 	cwd: string,
 	sessionIdOrEntry: string | AuditEntry,
 	maybeEntry?: AuditEntry,
+	options: { lockHeld?: boolean; beforeAppend?: (offset: number) => Promise<unknown> } = {},
 ): Promise<string> {
 	const sessionId =
 		typeof sessionIdOrEntry === "string"
@@ -1568,8 +1615,50 @@ export async function appendAuditEntry(
 	const entry = typeof sessionIdOrEntry === "string" ? maybeEntry : sessionIdOrEntry;
 	if (!entry) throw new Error("audit entry is required");
 	const filePath = resolveGjcTarget(layoutAuditPath(cwd, sessionId), cwd);
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf-8");
+	const append = async () => {
+		await fs.mkdir(path.dirname(filePath), { recursive: true });
+		let initialStat: nodeFs.BigIntStats | undefined;
+		try {
+			initialStat = await fs.lstat(filePath, { bigint: true });
+			if (initialStat.isSymbolicLink() || !initialStat.isFile()) throw new Error("audit path is not a regular file");
+		} catch (error) {
+			if (!isErrno(error, "ENOENT")) throw error;
+		}
+		const flags = initialStat
+			? fsConstants.O_WRONLY |
+				fsConstants.O_APPEND |
+				(process.platform === "win32" ? 0 : (fsConstants.O_NOFOLLOW ?? 0))
+			: fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_EXCL;
+		let handle: fs.FileHandle | undefined;
+		try {
+			handle = await fs.open(filePath, flags, 0o600);
+			const openedStat = await handle.stat({ bigint: true });
+			const pathStat = await fs.lstat(filePath, { bigint: true });
+			const sameObject = (left: nodeFs.BigIntStats, right: nodeFs.BigIntStats) =>
+				left.dev === right.dev && left.ino === right.ino && left.nlink === right.nlink;
+			if (
+				openedStat.isSymbolicLink() ||
+				!openedStat.isFile() ||
+				pathStat.isSymbolicLink() ||
+				!pathStat.isFile() ||
+				(initialStat !== undefined && !sameObject(initialStat, openedStat)) ||
+				!sameObject(openedStat, pathStat)
+			)
+				throw new Error("audit path identity changed before append");
+			if (openedStat.size > BigInt(Number.MAX_SAFE_INTEGER))
+				throw new Error("audit path is too large to append safely");
+			await options.beforeAppend?.(Number(openedStat.size));
+			await handle.writeFile(`${JSON.stringify(entry)}\n`, "utf-8");
+			await handle.sync();
+			const afterPathStat = await fs.lstat(filePath, { bigint: true });
+			if (afterPathStat.isSymbolicLink() || !sameObject(openedStat, afterPathStat))
+				throw new Error("audit path identity changed during append");
+		} finally {
+			await handle?.close();
+		}
+	};
+	if (options.lockHeld) await append();
+	else await withWorkflowStateLock(filePath, append, { cwd });
 	return filePath;
 }
 

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

@@ -63,11 +63,14 @@ export function envDisabled(value: string | undefined): boolean {
  * 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` 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.
+ * An operator `GJC_TMUX_COMMAND` is honored on every platform. A value that
+ * matches the project dotenv snapshot, including a dynamic declaration, is
+ * ignored so a repository cannot choose the binary, and the resolver uses the
+ * same default as when the variable is unset. 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,

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

@@ -1275,13 +1275,25 @@ export async function createUltragoalPlan(input: {
 	return plan;
 }
 
-function chooseNextGoal(plan: UltragoalPlan, retryFailed: boolean): UltragoalGoal | undefined {
+/**
+ * Scheduler order shared with read-only projections: active, then pending, then failed
+ * only when the caller explicitly opts into retrying failed goals. Blocked,
+ * review_blocked, complete, and superseded goals are never schedulable.
+ */
+export function selectNextSchedulableGoal<T extends { status: UltragoalGoalStatus }>(
+	goals: readonly T[],
+	retryFailed: boolean,
+): T | undefined {
 	return (
-		plan.goals.find(goal => goal.status === "active") ??
-		plan.goals.find(goal => goal.status === "pending") ??
-		(retryFailed ? plan.goals.find(goal => goal.status === "failed") : undefined)
+		goals.find(goal => goal.status === "active") ??
+		goals.find(goal => goal.status === "pending") ??
+		(retryFailed ? goals.find(goal => goal.status === "failed") : undefined)
 	);
 }
+
+function chooseNextGoal(plan: UltragoalPlan, retryFailed: boolean): UltragoalGoal | undefined {
+	return selectNextSchedulableGoal(plan.goals, retryFailed);
+}
 export interface UltragoalRunCompletionState {
 	requiredGoals: UltragoalGoal[];
 	incompleteGoals: UltragoalGoal[];

package/src/gjc-runtime/workflow-manifest.generated.json

@@ -174,16 +174,7 @@
           "clear",
           "contract",
           "handoff",
-          "doctor",
-          "kickoff",
-          "write-spec",
-          "write-artifact",
-          "stage",
-          "check",
-          "apply",
-          "discard",
-          "read",
-          "write"
+          "doctor"
         ],
         "name": "session-id",
         "type": "string"
@@ -414,6 +405,11 @@
         "to": "handoff",
         "verb": "write-spec"
       },
+      {
+        "from": "interviewing",
+        "to": "handoff",
+        "verb": "crystallize"
+      },
       {
         "from": "handoff",
         "to": "complete",
@@ -426,14 +422,6 @@
       }
     ],
     "typedArgs": [
-      {
-        "appliesToVerbs": [
-          "write",
-          "api"
-        ],
-        "name": "input",
-        "type": "string"
-      },
       {
         "appliesToVerbs": [
           "read",
@@ -462,13 +450,10 @@
           "doctor",
           "kickoff",
           "write-spec",
-          "write-artifact",
           "stage",
           "check",
           "apply",
-          "discard",
-          "read",
-          "write"
+          "discard"
         ],
         "name": "session-id",
         "type": "string"
@@ -556,6 +541,13 @@
         "name": "deep",
         "type": "boolean"
       },
+      {
+        "appliesToVerbs": [
+          "kickoff"
+        ],
+        "name": "trace",
+        "type": "boolean"
+      },
       {
         "appliesToVerbs": [
           "kickoff"
@@ -587,6 +579,14 @@
         "name": "slug",
         "type": "string"
       },
+      {
+        "appliesToVerbs": [
+          "crystallize"
+        ],
+        "name": "slug",
+        "required": true,
+        "type": "string"
+      },
       {
         "appliesToVerbs": [
           "write-spec"
@@ -614,7 +614,16 @@
       },
       {
         "appliesToVerbs": [
+          "write-spec"
+        ],
+        "name": "force",
+        "type": "boolean"
+      },
+      {
+        "appliesToVerbs": [
+          "kickoff",
           "write-spec",
+          "crystallize",
           "stage",
           "check",
           "apply",
@@ -622,20 +631,47 @@
           "read",
           "write",
           "clear",
-          "handoff"
+          "handoff",
+          "approve-execution"
         ],
         "name": "json",
         "type": "boolean"
       },
       {
         "appliesToVerbs": [
+          "api"
+        ],
+        "name": "input",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "write",
           "stage",
-          "write"
+          "crystallize"
         ],
         "name": "input",
         "required": true,
         "type": "string"
       },
+      {
+        "appliesToVerbs": [
+          "approve-execution"
+        ],
+        "enumValues": [
+          "deep-interview"
+        ],
+        "name": "mode",
+        "type": "enum"
+      },
+      {
+        "appliesToVerbs": [
+          "crystallize",
+          "approve-execution"
+        ],
+        "name": "session-id",
+        "type": "string"
+      },
       {
         "appliesToVerbs": [
           "write"
@@ -701,6 +737,10 @@
         "name": "write-spec",
         "surface": "command-flag"
       },
+      {
+        "name": "crystallize",
+        "surface": "command-flag"
+      },
       {
         "name": "stage",
         "surface": "command-positional"
@@ -733,6 +773,10 @@
         "name": "handoff",
         "surface": "command-positional"
       },
+      {
+        "name": "approve-execution",
+        "surface": "command-positional"
+      },
       {
         "name": "graph",
         "planned": true,
@@ -1017,14 +1061,7 @@
           "handoff",
           "doctor",
           "kickoff",
-          "write-spec",
-          "write-artifact",
-          "stage",
-          "check",
-          "apply",
-          "discard",
-          "read",
-          "write"
+          "write-artifact"
         ],
         "name": "session-id",
         "type": "string"
@@ -1403,16 +1440,7 @@
           "clear",
           "contract",
           "handoff",
-          "doctor",
-          "kickoff",
-          "write-spec",
-          "write-artifact",
-          "stage",
-          "check",
-          "apply",
-          "discard",
-          "read",
-          "write"
+          "doctor"
         ],
         "name": "session-id",
         "type": "string"

package/src/gjc-runtime/workflow-manifest.ts

@@ -70,22 +70,16 @@ const PLANNED_ADMIN_VERBS = ["graph", "prune", "migrate", "force-overwrite"] as
 
 const COMMON_TYPED_ARGS: TypedArgSpec[] = [
 	{ name: "input", type: "string", appliesToVerbs: ["write", "api"] },
-	{ name: "mode", type: "enum", enumValues: [...CANONICAL_GJC_WORKFLOW_SKILLS], appliesToVerbs: [...STATE_VERBS] },
+	{
+		name: "mode",
+		type: "enum",
+		enumValues: [...CANONICAL_GJC_WORKFLOW_SKILLS],
+		appliesToVerbs: [...STATE_VERBS],
+	},
 	{
 		name: "session-id",
 		type: "string",
-		appliesToVerbs: [
-			...STATE_VERBS,
-			"kickoff",
-			"write-spec",
-			"write-artifact",
-			"stage",
-			"check",
-			"apply",
-			"discard",
-			"read",
-			"write",
-		],
+		appliesToVerbs: [...STATE_VERBS, "kickoff", "write-spec", "write-artifact", "stage", "check", "apply", "discard"],
 	},
 	{ name: "thread-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
 	{ name: "turn-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
@@ -137,9 +131,18 @@ function manifest(input: {
 	phaseLock?: readonly string[];
 	canonicalOverrides?: readonly string[];
 	initialState?: string;
+	commonTypedArgs?: TypedArgSpec[];
 }): SkillManifest {
 	const staleInitialState = initialPhaseForSkill(input.skill);
 	const initialState = input.initialState ?? staleInitialState;
+	const supportedVerbs = new Set([...input.verbs.map(item => item.name), "api"]);
+	const typedArgs = [...(input.commonTypedArgs ?? COMMON_TYPED_ARGS), ...(input.typedArgs ?? [])]
+		.map(argument =>
+			argument.appliesToVerbs === undefined
+				? argument
+				: { ...argument, appliesToVerbs: argument.appliesToVerbs.filter(verb => supportedVerbs.has(verb)) },
+		)
+		.filter(argument => argument.appliesToVerbs === undefined || argument.appliesToVerbs.length > 0);
 	return {
 		skill: input.skill,
 		states: input.states.map(item => state(item, initialState, input.terminalStates)),
@@ -147,7 +150,7 @@ function manifest(input: {
 		terminalStates: input.terminalStates,
 		transitions: input.transitions,
 		verbs: input.verbs,
-		typedArgs: [...COMMON_TYPED_ARGS, ...(input.typedArgs ?? [])],
+		typedArgs,
 		retention: input.retention,
 		hudFields: input.hudFields,
 		graphLabel: input.graphLabel,
@@ -171,32 +174,63 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 		terminalStates: ["handoff", "complete"],
 		transitions: [
 			{ from: "interviewing", to: "handoff", verb: "write-spec" },
+			{ from: "interviewing", to: "handoff", verb: "crystallize" },
 			{ from: "handoff", to: "complete", verb: "clear" },
 			{ from: "interviewing", to: "complete", verb: "clear" },
 		],
 		verbs: [
 			...stateVerbs(),
-			...flagVerbs(["kickoff", "write-spec"]),
-			...positionalVerbs(["stage", "check", "apply", "discard", "read", "write", "clear", "handoff"]),
+			...flagVerbs(["kickoff", "write-spec", "crystallize"]),
+			...positionalVerbs([
+				"stage",
+				"check",
+				"apply",
+				"discard",
+				"read",
+				"write",
+				"clear",
+				"handoff",
+				"approve-execution",
+			]),
 			...plannedVerbs(PLANNED_ADMIN_VERBS),
 		],
+		commonTypedArgs: COMMON_TYPED_ARGS.filter(argument => argument.name !== "input"),
 		typedArgs: [
 			{ name: "quick", type: "boolean", appliesToVerbs: ["kickoff"] },
 			{ name: "standard", type: "boolean", appliesToVerbs: ["kickoff"] },
 			{ name: "deep", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "trace", type: "boolean", appliesToVerbs: ["kickoff"] },
 			{ name: "threshold", type: "number", appliesToVerbs: ["kickoff"] },
 			{ name: "threshold-source", type: "string", appliesToVerbs: ["kickoff"] },
 			{ name: "stage", type: "enum", enumValues: ["final"], appliesToVerbs: ["write-spec"] },
 			{ name: "slug", type: "string", appliesToVerbs: ["write-spec"] },
+			{ name: "slug", type: "string", required: true, appliesToVerbs: ["crystallize"] },
 			{ name: "spec", type: "string", required: true, appliesToVerbs: ["write-spec"] },
 			{ name: "handoff", type: "enum", enumValues: ["ralplan"], appliesToVerbs: ["write-spec"] },
 			{ name: "deliberate", type: "boolean", appliesToVerbs: ["write-spec"] },
+			{ name: "force", type: "boolean", appliesToVerbs: ["write-spec"] },
 			{
 				name: "json",
 				type: "boolean",
-				appliesToVerbs: ["write-spec", "stage", "check", "apply", "discard", "read", "write", "clear", "handoff"],
+				appliesToVerbs: [
+					"kickoff",
+					"write-spec",
+					"crystallize",
+					"stage",
+					"check",
+					"apply",
+					"discard",
+					"read",
+					"write",
+					"clear",
+					"handoff",
+					"approve-execution",
+				],
 			},
-			{ name: "input", type: "string", required: true, appliesToVerbs: ["stage", "write"] },
+			{ name: "input", type: "string", appliesToVerbs: ["api"] },
+			{ name: "input", type: "string", required: true, appliesToVerbs: ["write", "stage", "crystallize"] },
+			{ name: "mode", type: "enum", enumValues: ["deep-interview"], appliesToVerbs: ["approve-execution"] },
+			{ name: "session-id", type: "string", appliesToVerbs: ["crystallize", "approve-execution"] },
 			{ name: "reset", type: "boolean", appliesToVerbs: ["write"] },
 			{
 				name: "for",
@@ -523,9 +557,8 @@ export function listVerbs(skill: CanonicalGjcWorkflowSkill): string[] {
 }
 
 export function typedArgsFor(skill: CanonicalGjcWorkflowSkill, verb: string): TypedArgSpec[] {
-	return WORKFLOW_MANIFEST[skill].typedArgs.filter(
-		arg => arg.appliesToVerbs === undefined || arg.appliesToVerbs.includes(verb),
-	);
+	const manifest = WORKFLOW_MANIFEST[skill];
+	return manifest.typedArgs.filter(arg => arg.appliesToVerbs === undefined || arg.appliesToVerbs.includes(verb));
 }
 
 function stableSort(value: unknown): unknown {

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

@@ -142,6 +142,7 @@ export async function operate(goal: string, opts: OperateOptions): Promise<Opera
 				lifecycle = "finalizing";
 				break;
 			}
+			lifecycle = accepted ? "observing" : "submitted";
 			continue;
 		}
 
@@ -182,11 +183,18 @@ export async function operate(goal: string, opts: OperateOptions): Promise<Opera
 		return { completed: false, lifecycle, iterations, classifications, vanishReceiptIds, blockers };
 	}
 
-	// B3: never finalize on loop-exhaustion — require an explicit observed completion.
+	// An observation budget bounds this invocation, not the work itself. Keep active
+	// sessions nonterminal so a caller can resume observation without treating a slow
+	// but healthy owner as a failure. Completion still requires an explicit signal.
 	if (lifecycle !== "finalizing") {
-		blockers.push("no-observed-completion");
-		await emit("critical", "operate_blocked", { blockers });
-		return { completed: false, lifecycle: "blocked", iterations, classifications, vanishReceiptIds, blockers };
+		await emit("info", "operate_observation_window_ended", {
+			lifecycle,
+			iterations,
+			lastClassification: classifications.at(-1) ?? null,
+			completionObserved: false,
+			resumeWith: "observe",
+		});
+		return { completed: false, lifecycle, iterations, classifications, vanishReceiptIds, blockers };
 	}
 
 	const finalize = await runFinalize({

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

@@ -809,7 +809,11 @@ export class RuntimeOwner {
 			evidence: Record<string, unknown>,
 		): Promise<void> => {
 			if (signal.aborted) return;
-			if (kind === "operate_blocked" || kind === "operate_finalized") {
+			if (kind === "operate_observation_window_ended") {
+				const lifecycle = evidence.lifecycle === "submitted" ? "submitted" : "observing";
+				const persisted = await this.#persistValidationLifecycle(signal, lifecycle, []);
+				if (!persisted.persisted) return;
+			} else if (kind === "operate_blocked" || kind === "operate_finalized") {
 				const lifecycle = kind === "operate_finalized" && evidence.completed === true ? "completed" : "blocked";
 				const blockers = Array.isArray(evidence.blockers)
 					? evidence.blockers.filter((blocker): blocker is string => typeof blocker === "string")