@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/gjc-runtime/workflow-cli-common.ts

@@ -0,0 +1,30 @@
+export class CommandError extends Error {
+	constructor(
+		public readonly exitStatus: number,
+		message: string,
+	) {
+		super(message);
+		this.name = "CommandError";
+	}
+}
+
+export function flagValue(args: readonly string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	return index < 0 ? undefined : args[index + 1];
+}
+
+export function hasFlag(args: readonly string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+
+export function assertSafePathComponent(value: string, label: string): void {
+	if (!PATH_COMPONENT_RE.test(value) || value.includes("..")) {
+		throw new CommandError(2, `invalid path component for --${label}: ${value}`);
+	}
+}

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

@@ -1,5 +1,6 @@
 {
   "deep-interview": {
+    "canonicalOverrides": [],
     "graphLabel": "Deep Interview",
     "hudFields": [
       "current_phase",
@@ -10,6 +11,7 @@
       "topology"
     ],
     "initialState": "interviewing",
+    "phaseLock": [],
     "retention": [
       {
         "category": "state",
@@ -42,6 +44,14 @@
         "terminal": true
       }
     ],
+    "stopReleasingPhases": [
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "terminalStates": [
       "handoff",
       "complete"
@@ -318,6 +328,16 @@
     ]
   },
   "ralplan": {
+    "canonicalOverrides": [
+      "final",
+      "handoff",
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "graphLabel": "Ralplan",
     "hudFields": [
       "current_phase",
@@ -328,6 +348,16 @@
       "plan_path"
     ],
     "initialState": "planner",
+    "phaseLock": [
+      "final",
+      "handoff",
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "retention": [
       {
         "category": "state",
@@ -378,6 +408,14 @@
         "terminal": true
       }
     ],
+    "stopReleasingPhases": [
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "terminalStates": [
       "final",
       "handoff"
@@ -704,6 +742,7 @@
     ]
   },
   "team": {
+    "canonicalOverrides": [],
     "graphLabel": "Team",
     "hudFields": [
       "current_phase",
@@ -714,6 +753,7 @@
       "integration"
     ],
     "initialState": "starting",
+    "phaseLock": [],
     "retention": [
       {
         "category": "state",
@@ -774,6 +814,14 @@
         "terminal": true
       }
     ],
+    "stopReleasingPhases": [
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "terminalStates": [
       "complete",
       "failed",
@@ -1150,6 +1198,7 @@
     ]
   },
   "ultragoal": {
+    "canonicalOverrides": [],
     "graphLabel": "Ultragoal",
     "hudFields": [
       "current_phase",
@@ -1160,6 +1209,7 @@
       "brief_path"
     ],
     "initialState": "goal-planning",
+    "phaseLock": [],
     "retention": [
       {
         "category": "state",
@@ -1212,6 +1262,14 @@
         "terminal": true
       }
     ],
+    "stopReleasingPhases": [
+      "complete",
+      "completed",
+      "failed",
+      "cancelled",
+      "canceled",
+      "inactive"
+    ],
     "terminalStates": [
       "missing",
       "failed",

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

@@ -52,6 +52,9 @@ export interface SkillManifest {
 	retention: RetentionPolicy[];
 	hudFields: string[];
 	graphLabel: string;
+	stopReleasingPhases: readonly string[];
+	phaseLock: readonly string[];
+	canonicalOverrides: readonly string[];
 }
 
 const STATE_RETENTION: RetentionPolicy = { category: "state", keep: 1 };
@@ -116,6 +119,9 @@ function manifest(input: {
 	retention: RetentionPolicy[];
 	hudFields: string[];
 	graphLabel: string;
+	stopReleasingPhases?: readonly string[];
+	phaseLock?: readonly string[];
+	canonicalOverrides?: readonly string[];
 	initialState?: string;
 }): SkillManifest {
 	const staleInitialState = initialPhaseForSkill(input.skill);
@@ -131,6 +137,16 @@ function manifest(input: {
 		retention: input.retention,
 		hudFields: input.hudFields,
 		graphLabel: input.graphLabel,
+		stopReleasingPhases: input.stopReleasingPhases ?? [
+			"complete",
+			"completed",
+			"failed",
+			"cancelled",
+			"canceled",
+			"inactive",
+		],
+		phaseLock: input.phaseLock ?? [],
+		canonicalOverrides: input.canonicalOverrides ?? [],
 	};
 }
 
@@ -207,6 +223,8 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 		retention: [STATE_RETENTION, ARTIFACT_RETENTION, LEDGER_RETENTION, PRUNE_RETENTION, FORCE_RETENTION],
 		hudFields: ["current_phase", "mode", "run_id", "stage", "stage_n", "plan_path"],
 		graphLabel: "Ralplan",
+		phaseLock: ["final", "handoff", "complete", "completed", "failed", "cancelled", "canceled", "inactive"],
+		canonicalOverrides: ["final", "handoff", "complete", "completed", "failed", "cancelled", "canceled", "inactive"],
 	}),
 	ultragoal: manifest({
 		skill: "ultragoal",

package/src/goals/continuation-timeout-guard.ts

@@ -0,0 +1,79 @@
+export type ToolOutcomeKind = "timeout" | "success" | "other-error";
+
+export interface TimeoutToolOutcome {
+	toolName: string;
+	argsKey: string;
+	kind: ToolOutcomeKind;
+}
+
+export interface TimeoutHoldState {
+	heldSnapshotKey?: string;
+	fingerprint?: string;
+	streak: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function canonicalizeArgs(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(item => canonicalizeArgs(item));
+	}
+	if (isRecord(value)) {
+		const canonical: Record<string, unknown> = {};
+		for (const key of Object.keys(value).sort()) {
+			if (value[key] !== undefined) {
+				canonical[key] = canonicalizeArgs(value[key]);
+			}
+		}
+		return canonical;
+	}
+	return value;
+}
+
+export function toResultText(result: unknown): string {
+	if (typeof result === "string") return result;
+	if (!isRecord(result) || !Array.isArray(result.content)) return "";
+	return result.content
+		.filter(
+			(content): content is { type: "text"; text: string } =>
+				isRecord(content) && content.type === "text" && typeof content.text === "string",
+		)
+		.map(content => content.text)
+		.join("\n");
+}
+
+export function classifyToolOutcome(isError: unknown, text: string): ToolOutcomeKind {
+	if (isError !== true) return "success";
+	return /\btimed out\b|\btimeout\b/i.test(text) ? "timeout" : "other-error";
+}
+
+export function canonicalArgsKey(args: unknown): string {
+	return JSON.stringify(canonicalizeArgs(args ?? null)) ?? "null";
+}
+
+export function turnTimeoutFingerprint(outcomes: readonly TimeoutToolOutcome[]): string | null {
+	if (outcomes.length === 0 || outcomes.some(outcome => outcome.kind !== "timeout")) return null;
+	const [first] = outcomes;
+	if (!first || outcomes.some(outcome => outcome.toolName !== first.toolName || outcome.argsKey !== first.argsKey)) {
+		return null;
+	}
+	return `${first.toolName}\u0000${first.argsKey}`;
+}
+
+export function decideTimeoutHold(
+	prev: TimeoutHoldState,
+	turn: { snapshotKey: string; fingerprint: string | null },
+): { hold: boolean; next: TimeoutHoldState } {
+	if (turn.fingerprint === null) {
+		return { hold: false, next: { heldSnapshotKey: undefined, fingerprint: undefined, streak: 0 } };
+	}
+	const continues =
+		prev.streak >= 1 && prev.fingerprint === turn.fingerprint && prev.heldSnapshotKey === turn.snapshotKey;
+	const streak = continues ? prev.streak + 1 : 1;
+	return {
+		hold: streak >= 2,
+		next: { heldSnapshotKey: turn.snapshotKey, fingerprint: turn.fingerprint, streak },
+	};
+}

package/src/goals/runtime.ts

@@ -294,28 +294,30 @@ export class GoalRuntime {
 		await this.#withAccounting(() => this.#flushUsageLocked(currentUsage));
 	}
 
-	#createGoalState(objective: string): GoalModeState {
+	#createGoalState(input: { objective: string; provenance?: Goal["provenance"] }): GoalModeState {
 		const now = this.#now();
 		const goal: Goal = {
 			id: String(Snowflake.next()),
-			objective,
+			objective: input.objective,
 			status: "active",
 			tokensUsed: 0,
 			timeUsedSeconds: 0,
 			createdAt: now,
 			updatedAt: now,
+			...(input.provenance ? { provenance: input.provenance } : {}),
 		};
 		return { enabled: true, mode: "active", goal };
 	}
 
-	async createGoal(input: { objective: string }): Promise<GoalModeState> {
+	async createGoal(input: { objective: string; provenance?: Goal["provenance"] }): Promise<GoalModeState> {
 		const objective = validateGoalObjective(input.objective, "create");
 		return await this.#withAccounting(async () => {
 			const existing = this.#getStateClone();
 			if (existing?.goal && existing.goal.status !== "dropped" && existing.goal.status !== "complete") {
 				throw new Error("cannot create a new goal because this session already has a goal");
 			}
-			const state = this.#createGoalState(objective);
+			const state = this.#createGoalState({ objective, provenance: input.provenance ?? { source: "user" } });
+
 			this.#markActiveAccounting(state.goal);
 			await this.#commitState(state, { persist: "goal" });
 			return state;
@@ -330,7 +332,7 @@ export class GoalRuntime {
 				throw new Error("cannot replace goal because no goal is active");
 			}
 			await this.#flushUsageLocked();
-			const state = this.#createGoalState(objective);
+			const state = this.#createGoalState({ objective, provenance: { source: "user" } });
 			this.#markActiveAccounting(state.goal);
 			await this.#commitState(state, { persist: "goal" });
 			return state;

package/src/goals/state.ts

@@ -2,6 +2,8 @@ import type { UsageStatistics } from "../session/session-manager";
 
 export type GoalStatus = "active" | "paused" | "complete" | "dropped";
 
+export type GoalProvenance = { source: "ultragoal"; runId: string; goalId: string } | { source: "user" };
+
 export interface Goal {
 	id: string;
 	objective: string;
@@ -10,6 +12,7 @@ export interface Goal {
 	timeUsedSeconds: number;
 	createdAt: number;
 	updatedAt: number;
+	provenance?: GoalProvenance;
 }
 
 export interface GoalModeState {
@@ -47,6 +50,20 @@ export function normalizeGoal(candidate: unknown): Goal | null {
 	if (status !== "active" && status !== "paused" && status !== "complete" && status !== "dropped") {
 		return null;
 	}
+	const provenance = value.provenance;
+	if (
+		provenance !== undefined &&
+		(!provenance ||
+			typeof provenance !== "object" ||
+			((provenance as Record<string, unknown>).source === "ultragoal" &&
+				(typeof (provenance as Record<string, unknown>).runId !== "string" ||
+					typeof (provenance as Record<string, unknown>).goalId !== "string")) ||
+			((provenance as Record<string, unknown>).source !== "ultragoal" &&
+				(provenance as Record<string, unknown>).source !== "user"))
+	) {
+		return null;
+	}
+
 	return {
 		id: value.id,
 		objective: value.objective,
@@ -55,6 +72,7 @@ export function normalizeGoal(candidate: unknown): Goal | null {
 		timeUsedSeconds: value.timeUsedSeconds,
 		createdAt: value.createdAt,
 		updatedAt: value.updatedAt,
+		...(provenance ? { provenance: provenance as GoalProvenance } : {}),
 	};
 }
 

package/src/harness-control-plane/lifecycle-reconciliation.ts

@@ -0,0 +1,64 @@
+import type { Observation, SessionState } from "./types";
+
+export const OWNER_STARTUP_BLOCKER = "owner-died-before-first-prompt";
+
+export interface CompletedTerminalEvent {
+	cursor: number;
+	createdAt: string;
+	kind: string;
+}
+
+export function isOwnerLivenessBlocker(blocker: string): boolean {
+	return blocker === "detached-owner-not-live" || blocker.startsWith("owner-vanished:");
+}
+
+export function needsVanishedOwnerBlock(
+	state: SessionState,
+	observation: Observation,
+	completedTerminal: CompletedTerminalEvent | null,
+): boolean {
+	if (observation.ownerLive || state.lifecycle !== "observing") return false;
+	if (completedTerminal || observation.observedSignals.includes("completed")) return false;
+	return observation.observedSignals.some(
+		signal => signal === "prompt-accepted" || signal === "tool-call" || signal === "streaming",
+	);
+}
+
+export async function reconcileOwnerLifecycle(input: {
+	state: SessionState;
+	observation: Observation;
+	completedTerminal: CompletedTerminalEvent | null;
+	startupBlocked: boolean;
+	persist: (state: SessionState) => Promise<void>;
+	nowIso: () => string;
+}): Promise<SessionState> {
+	const { state, observation, completedTerminal } = input;
+	if (
+		completedTerminal &&
+		!observation.ownerLive &&
+		observation.gitDelta === "clean" &&
+		state.lifecycle !== "completed" &&
+		state.lifecycle !== "retired"
+	) {
+		state.lifecycle = "completed";
+		state.blockers = state.blockers.filter(blocker => !isOwnerLivenessBlocker(blocker));
+		state.updatedAt = input.nowIso();
+		await input.persist(state);
+	}
+	if (needsVanishedOwnerBlock(state, observation, completedTerminal)) {
+		const blocker = `owner-vanished:${observation.gitDelta}`;
+		state.lifecycle = "blocked";
+		state.blockers = state.blockers.includes(blocker) ? state.blockers : [...state.blockers, blocker];
+		state.updatedAt = input.nowIso();
+		await input.persist(state);
+	}
+	if (input.startupBlocked && state.lifecycle !== "completed" && state.lifecycle !== "retired") {
+		state.lifecycle = "blocked";
+		state.blockers = state.blockers.includes(OWNER_STARTUP_BLOCKER)
+			? state.blockers
+			: [...state.blockers, OWNER_STARTUP_BLOCKER];
+		state.updatedAt = input.nowIso();
+		await input.persist(state);
+	}
+	return state;
+}

package/src/harness-control-plane/phase-rollup.ts

@@ -1,12 +1,9 @@
 /**
- * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ * EXPERIMENTAL: Phase-boundary receipt rollup builder (receipt-of-receipts).
  *
- * At a harness lifecycle boundary, N child task receipts can be superseded by a
- * single `phase-rollup` receipt that preserves per-child pointers (id, status,
- * outputRef, sha256) plus aggregate ROI totals. The rollup is hash-sealed via
- * the standard receipt envelope and validated fail-closed like every other
- * family (see `validatePhaseRollup` in receipts.ts). Pure builder — no runtime
- * injection behavior is changed here.
+ * This builder is not wired into finalize or retire yet; child receipts remain
+ * authoritative until a lifecycle integration preserves their supersession
+ * semantics. It is retained for controlled integration experiments only.
  */
 import type { TaskResultReceipt } from "../task/receipt";
 import {

package/src/harness-control-plane/receipt-ingest.ts

@@ -1,3 +1,8 @@
+/**
+ * EXPERIMENTAL: Receipt ingestion is a pure evaluator and is not yet wired to
+ * finalize or retire lifecycle mutation. Callers must not treat its result as
+ * authoritative lifecycle persistence.
+ */
 import type { CompletionEvidence, ReceiptEnvelope, ReviewVerdictEvidence } from "./receipts";
 import { validateReceipt } from "./receipts";
 import { canTransition } from "./state-machine";

package/src/harness-control-plane/receipt-spool.ts

@@ -21,6 +21,46 @@ export interface ReceiptSpoolAppendResult {
 const receiptSpoolDirStorage = new AsyncLocalStorage<string | undefined>();
 const spoolQueues = new Map<string, Promise<void>>();
 const noop = (): void => undefined;
+
+interface ReceiptSpoolCursorCache {
+	mtimeMs: number;
+	size: number;
+	highest: bigint;
+}
+
+const cursorCache = new Map<string, ReceiptSpoolCursorCache>();
+let fullScanCount = 0;
+
+/** @internal Test-only instrumentation for steady-state spool scan coverage. */
+export function receiptSpoolFullScanCountForTesting(): number {
+	return fullScanCount;
+}
+
+/** @internal Test-only cache reset. */
+export function resetReceiptSpoolCursorCacheForTesting(): void {
+	cursorCache.clear();
+	fullScanCount = 0;
+}
+
+async function spoolStat(spoolFile: string): Promise<{ mtimeMs: number; size: number } | undefined> {
+	try {
+		const stats = await fs.stat(spoolFile);
+		return { mtimeMs: stats.mtimeMs, size: stats.size };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function sameSpoolRevision(a: ReceiptSpoolCursorCache, b: { mtimeMs: number; size: number }): boolean {
+	return a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+
+async function cacheHighestCursor(spoolFile: string, highest: bigint): Promise<void> {
+	const revision = await spoolStat(spoolFile);
+	if (revision) cursorCache.set(spoolFile, { ...revision, highest });
+}
+
 export async function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T> {
 	const trimmed = spoolDir.trim();
 	if (!trimmed) throw new Error("receipt_spool_dir_empty");
@@ -55,14 +95,16 @@ export function formatReceiptSpoolCursor(cursor: bigint): string {
 
 export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint> {
 	const spoolFile = receiptSpoolPath(spoolDir);
-	let raw: string;
-	try {
-		raw = await fs.readFile(spoolFile, "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0n;
-		throw error;
+	const revision = await spoolStat(spoolFile);
+	if (!revision) {
+		cursorCache.delete(spoolFile);
+		return 0n;
 	}
+	const cached = cursorCache.get(spoolFile);
+	if (cached && sameSpoolRevision(cached, revision)) return cached.highest;
 
+	fullScanCount++;
+	const raw = await fs.readFile(spoolFile, "utf8");
 	let highest = 0n;
 	for (const line of raw.split("\n")) {
 		const trimmed = line.trim();
@@ -72,9 +114,10 @@ export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<b
 			const cursor = parseCursor(parsed.cursor);
 			if (cursor !== undefined && cursor > highest) highest = cursor;
 		} catch {
-			// A crash may leave a torn tail; consumers skip malformed lines and so do we.
+			// A crash may leave a torn tail; a full scan ignores it and re-establishes the cache.
 		}
 	}
+	cursorCache.set(spoolFile, { ...revision, highest });
 	return highest;
 }
 
@@ -111,6 +154,7 @@ export async function appendReceiptToSpool(
 				} finally {
 					await handle.close();
 				}
+				await cacheHighestCursor(spoolFile, BigInt(cursor));
 				return { cursor, path: spoolFile };
 			},
 			{ staleMs: 30_000, retries: 100, retryDelayMs: 25 },