@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/session/session-manager.ts

@@ -27,6 +27,7 @@ import {
 	Snowflake,
 	toError,
 } from "@gajae-code/utils";
+import { writeTextAtomic } from "../gjc-runtime/state-writer";
 import { ArtifactManager } from "./artifacts";
 import {
 	type BlobPutResult,
@@ -56,6 +57,10 @@ import type { SessionStorage, SessionStorageWriter } from "./session-storage";
 import { FileSessionStorage, MemorySessionStorage } from "./session-storage";
 
 export const CURRENT_SESSION_VERSION = 3;
+function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
+	const relative = path.relative(path.join(path.resolve(cwd), ".gjc"), path.resolve(targetPath));
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
 
 export interface SessionHeader {
 	type: "session";
@@ -384,6 +389,7 @@ const migratedSessionRoots = new Set<string>();
  * Best effort: callers decide whether migration failures should surface.
  */
 function migrateSessionDirPath(oldPath: string, newPath: string): void {
+	// Session-dir lifecycle migration: moves/removes whole directories, not file content writes.
 	const existing = fs.statSync(newPath, { throwIfNoEntry: false });
 	if (existing?.isDirectory()) {
 		for (const file of fs.readdirSync(oldPath)) {
@@ -752,7 +758,13 @@ function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
 	const breadcrumbFile = path.join(breadcrumbDir, terminalId);
 	const content = `${cwd}\n${sessionFile}\n`;
 	// Best-effort — don't break session creation if breadcrumb fails
-	Bun.write(breadcrumbFile, content).catch(() => {});
+	const write = isUnderProjectGjc(cwd, breadcrumbFile)
+		? writeTextAtomic(breadcrumbFile, content, {
+				cwd,
+				audit: { category: "artifact", verb: "write", owner: "gjc-runtime" },
+			})
+		: Bun.write(breadcrumbFile, content);
+	write.catch(() => {});
 }
 
 /**

package/src/skill-state/active-state.ts

@@ -1,5 +1,10 @@
-import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import {
+	type ActiveSessionScope,
+	rebuildActiveSnapshot,
+	removeActiveEntry,
+	writeActiveEntry,
+} from "../gjc-runtime/state-writer";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 
 export const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
@@ -56,6 +61,8 @@ export interface SkillActiveState {
 	session_id?: string;
 	thread_id?: string;
 	turn_id?: string;
+	initialized_mode?: CanonicalGjcWorkflowSkill;
+	initialized_state_path?: string;
 	active_skills?: SkillActiveEntry[];
 	[key: string]: unknown;
 }
@@ -286,14 +293,6 @@ export function getSkillActiveStatePaths(cwd: string, sessionId?: string): Skill
 	};
 }
 
-async function readStateFile(filePath: string): Promise<SkillActiveState | null> {
-	try {
-		return normalizeSkillActiveState(JSON.parse(await Bun.file(filePath).text()));
-	} catch {
-		return null;
-	}
-}
-
 /**
  * Raw read for handoff mutations. Returns the *unnormalized* parsed object so
  * inactive entries remain visible to `rawActiveEntries` — `normalizeSkillActiveState`
@@ -516,15 +515,41 @@ export async function readVisibleSkillActiveState(cwd: string, sessionId?: strin
 	};
 }
 
-async function writeStateFile(filePath: string, state: SkillActiveState): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await Bun.write(filePath, `${JSON.stringify(state, null, 2)}\n`);
+function activeStateWriterAudit(verb: string) {
+	return { category: "state" as const, verb, owner: "gjc-runtime" as const };
+}
+
+async function persistActiveEntry(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	if (entry.active === false) {
+		await removeActiveEntry(cwd, sessionScope, entry.skill, {
+			cwd,
+			audit: activeStateWriterAudit("remove-active-entry"),
+		});
+	} else {
+		await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
+			cwd,
+			audit: activeStateWriterAudit("write-active-entry"),
+		});
+	}
 }
 
-function upsertEntry(entries: SkillActiveEntry[], entry: SkillActiveEntry, active: boolean): SkillActiveEntry[] {
-	const key = entryKey(entry);
-	const retained = entries.filter(candidate => entryKey(candidate) !== key);
-	return active ? [...retained, entry] : retained;
+async function writeHandoffEntry(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
+		cwd,
+		audit: activeStateWriterAudit("write-active-entry"),
+	});
+}
+
+async function rebuildActiveState(cwd: string, sessionScope?: ActiveSessionScope): Promise<void> {
+	await rebuildActiveSnapshot(cwd, sessionScope, { cwd, audit: activeStateWriterAudit("rebuild-active-snapshot") });
 }
 
 export async function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void> {
@@ -545,36 +570,13 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 		...(hud ? { hud } : {}),
 		...(options.receipt ? { receipt: options.receipt } : {}),
 	};
-	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, options.sessionId);
-	const rootState = (await readStateFile(rootPath)) ?? { version: 1, active_skills: [] };
-	const rootEntries = upsertEntry(listActiveSkills(rootState), entry, options.active);
-	const nextRoot: SkillActiveState = {
-		...rootState,
-		version: 1,
-		active: rootEntries.length > 0,
-		skill: rootEntries[0]?.skill ?? "",
-		phase: rootEntries[0]?.phase ?? "",
-		updated_at: nowIso,
-		source: options.source,
-		active_skills: rootEntries,
-	};
-	await writeStateFile(rootPath, nextRoot);
+	await persistActiveEntry(options.cwd, undefined, entry);
+	await rebuildActiveState(options.cwd);
 
-	if (!sessionPath) return;
-	const sessionState = (await readStateFile(sessionPath)) ?? { version: 1, active_skills: [] };
-	const sessionEntries = upsertEntry(listActiveSkills(sessionState), entry, options.active);
-	const nextSession: SkillActiveState = {
-		...sessionState,
-		version: 1,
-		active: sessionEntries.length > 0,
-		skill: sessionEntries[0]?.skill ?? "",
-		phase: sessionEntries[0]?.phase ?? "",
-		session_id: options.sessionId,
-		updated_at: nowIso,
-		source: options.source,
-		active_skills: sessionEntries,
-	};
-	await writeStateFile(sessionPath, nextSession);
+	if (!options.sessionId) return;
+	const sessionScope = { sessionId: options.sessionId };
+	await persistActiveEntry(options.cwd, sessionScope, entry);
+	await rebuildActiveState(options.cwd, sessionScope);
 }
 
 export interface ApplyHandoffOptions {
@@ -604,6 +606,7 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 	const sessionId = options.callee.sessionId ?? options.caller.sessionId;
 	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
 	const readState = (filePath: string) => readRawActiveStateForHandoff(filePath, options.strict === true);
+	await Promise.all([readState(rootPath), ...(sessionPath ? [readState(sessionPath)] : [])]);
 
 	// A skill can hold more than one visible row in this session's scope — e.g.
 	// it was seeded without a session id (rendered globally) and is now handed
@@ -637,33 +640,23 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 			: callerEntry;
 		return [...kept, mergedCaller, calleeEntry];
 	};
-	const buildNextState = (
+	const writeEntries = async (
+		sessionScope: ActiveSessionScope | undefined,
 		prior: SkillActiveState | null,
-		entries: SkillActiveEntry[],
-		scope: "session" | "root",
-	): SkillActiveState => {
-		const visible = entries.filter(e => e.active !== false);
-		return {
-			...(prior ?? {}),
-			version: 1,
-			active: visible.length > 0,
-			skill: visible[0]?.skill ?? "",
-			phase: visible[0]?.phase ?? "",
-			...(scope === "session" ? { session_id: sessionId } : {}),
-			updated_at: nowIso,
-			source: options.callee.source ?? options.caller.source,
-			active_skills: entries,
-		};
+	): Promise<void> => {
+		const nextEntries = applyEntries(rawActiveEntries(prior));
+		for (const entry of nextEntries) {
+			await writeHandoffEntry(options.cwd, sessionScope, entry);
+		}
+		await rebuildActiveState(options.cwd, sessionScope);
 	};
 
 	if (sessionPath) {
 		const prior = await readState(sessionPath);
-		const next = buildNextState(prior, applyEntries(rawActiveEntries(prior)), "session");
-		await writeStateFile(sessionPath, next);
+		await writeEntries({ sessionId }, prior);
 	}
 	const priorRoot = await readState(rootPath);
-	const nextRoot = buildNextState(priorRoot, applyEntries(rawActiveEntries(priorRoot)), "root");
-	await writeStateFile(rootPath, nextRoot);
+	await writeEntries(undefined, priorRoot);
 }
 
 function buildSyncEntry(options: SyncSkillActiveStateOptions, nowIso: string): SkillActiveEntry {

package/src/skill-state/deep-interview-mutation-guard.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import type { AgentTool } from "@gajae-code/agent-core";
 import { expandApplyPatchToEntries } from "../edit/modes/apply-patch";
+import { ModeStateSchema } from "../gjc-runtime/state-schema";
 import { LocalProtocolHandler, resolveLocalUrlToPath } from "../internal-urls/local-protocol";
 import { resolveToCwd } from "../tools/path-utils";
 import { ToolError } from "../tools/tool-errors";
@@ -14,12 +15,16 @@ import {
 export const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE =
 	"Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `gjc deep-interview --write --stage final` or hand off to an execution phase.";
 export const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE =
-	"Workflow state JSON is runtime-owned. Use `gjc state <skill> read|write --input '<json>'` for deep-interview, ralplan, ultragoal, and team. Planning artifacts under `.gjc/specs/` and `.gjc/plans/` remain allowed.";
+	".gjc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.gjc/**`; use the sanctioned `gjc` CLI instead.";
 
-const BLOCKED_TOOL_NAMES = new Set(["edit", "write", "ast_edit"]);
+const BLOCKED_TOOL_NAMES = new Set(["edit", "write", "ast_edit", "bash"]);
 const ARCHIVE_OR_SQLITE_BASE_RE = /^(.+?\.(?:tar\.gz|sqlite3|sqlite|db3|zip|tgz|tar|db))(?:$|:)/i;
 const INTERNAL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 const VIM_FILE_SWITCH_RE = /^\s*:(?:e|e!|edit|edit!)(?:\s+([^<\r\n]+))?(?:<CR>|\r|\n|$)/i;
+const BASH_TOKEN_RE = /'[^']*'|"(?:\\.|[^"\\])*"|\S+/g;
+const BASH_REDIRECT_RE = /^(?:\d*)>>?$/;
+const BASH_HEREDOC_RE = /^(?:\d*)<<-?$/;
+const BASH_MUTATION_COMMANDS = new Set(["rm", "mv", "cp", "touch", "mkdir", "ln", "tee"]);
 
 type ToolWithEditMode = AgentTool & {
 	mode?: unknown;
@@ -72,19 +77,37 @@ function modeStatePath(cwd: string, skill: string, sessionId?: string): string {
 	return path.join(stateDir, fileName);
 }
 
-async function readJsonFile<T>(filePath: string): Promise<T | null> {
+function warnInvalidModeState(filePath: string, error: string): void {
+	console.warn(`gjc skill-state: invalid mode-state at ${filePath}: ${error}`);
+}
+
+async function readValidatedModeState(filePath: string): Promise<ModeState | null> {
+	let raw: string;
 	try {
-		return JSON.parse(await Bun.file(filePath).text()) as T;
+		raw = await Bun.file(filePath).text();
 	} catch {
 		return null;
 	}
+	let state: ModeState;
+	try {
+		state = JSON.parse(raw) as ModeState;
+	} catch (error) {
+		warnInvalidModeState(filePath, `invalid JSON: ${(error as Error).message}`);
+		return null;
+	}
+	const parsed = ModeStateSchema.safeParse(state);
+	if (!parsed.success) {
+		warnInvalidModeState(filePath, parsed.error.message);
+		return null;
+	}
+	return state;
 }
 async function readVisibleModeState(cwd: string, skill: string, sessionId?: string): Promise<ModeState | null> {
 	if (sessionId) {
-		const sessionState = await readJsonFile<ModeState>(modeStatePath(cwd, skill, sessionId));
+		const sessionState = await readValidatedModeState(modeStatePath(cwd, skill, sessionId));
 		if (sessionState) return sessionState;
 	}
-	return await readJsonFile<ModeState>(modeStatePath(cwd, skill));
+	return await readValidatedModeState(modeStatePath(cwd, skill));
 }
 
 function isTerminalModeState(state: ModeState | null): boolean {
@@ -219,10 +242,75 @@ function extractEditTargets(args: unknown, tool: ToolWithEditMode): ExtractedTar
 	return targets;
 }
 
+function extractBashTargets(args: unknown): ExtractedTargets {
+	const record = getRecord(args);
+	const command = safeString(record?.command).trim();
+	const targets: ExtractedTargets = { paths: [], unknown: false };
+	if (!command) {
+		targets.unknown = true;
+		return targets;
+	}
+	if (/^gjc(?:\s|$)/.test(command)) return targets;
+
+	const tokens = command.match(BASH_TOKEN_RE)?.map(unquoteBashToken) ?? [];
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index] ?? "";
+		if (BASH_REDIRECT_RE.test(token)) {
+			addPath(targets, tokens[index + 1]);
+			index++;
+			continue;
+		}
+		const redirectMatch = token.match(/^(?:\d*)>>?(.+)$/);
+		if (redirectMatch?.[1]) {
+			addPath(targets, redirectMatch[1]);
+			continue;
+		}
+		if (BASH_HEREDOC_RE.test(token)) {
+			addPath(targets, tokens[index + 1]);
+			index++;
+			continue;
+		}
+		const heredocMatch = token.match(/^(?:\d*)<<-?(.+)$/);
+		if (heredocMatch?.[1]) {
+			addPath(targets, heredocMatch[1]);
+			continue;
+		}
+		if (isMutationBashCommand(tokens, index)) {
+			for (let targetIndex = index + 1; targetIndex < tokens.length; targetIndex++) {
+				const target = tokens[targetIndex] ?? "";
+				if (isBashCommandBoundary(target)) break;
+				if (target.startsWith("-")) continue;
+				addPath(targets, target);
+			}
+		}
+	}
+	return targets;
+}
+
+function unquoteBashToken(token: string): string {
+	if (token.length < 2) return token;
+	const quote = token[0];
+	if ((quote === "'" || quote === '"') && token.at(-1) === quote) return token.slice(1, -1);
+	return token;
+}
+
+function isBashCommandBoundary(token: string): boolean {
+	return [";", "&&", "||", "|"].includes(token);
+}
+
+function isMutationBashCommand(tokens: string[], index: number): boolean {
+	const token = path.basename(tokens[index] ?? "");
+	if (BASH_MUTATION_COMMANDS.has(token)) return true;
+	if (token !== "sed") return false;
+	const next = tokens[index + 1] ?? "";
+	return next === "-i" || next.startsWith("-i") || next.includes("i");
+}
+
 function extractTargets(tool: ToolWithEditMode, args: unknown): ExtractedTargets {
 	if (tool.name === "write") return extractWriteTargets(args);
 	if (tool.name === "ast_edit") return extractAstEditTargets(args);
 	if (tool.name === "edit") return extractEditTargets(args, tool);
+	if (tool.name === "bash") return extractBashTargets(args);
 	return { paths: [], unknown: true };
 }
 
@@ -289,6 +377,14 @@ function isAllowlistedPath(cwd: string, rawPath: string): boolean {
 	if (segments?.[0] !== ".gjc") return false;
 	return segments[1] === "specs" || segments[1] === "plans";
 }
+function isBlockedGjcPath(cwd: string, rawPath: string): boolean {
+	const segments = relativeGjcSegments(cwd, rawPath);
+	return segments?.[0] === ".gjc";
+}
+
+function hasBlockedGjcTarget(cwd: string, targets: ExtractedTargets): boolean {
+	return targets.paths.some(rawPath => isBlockedGjcPath(cwd, rawPath));
+}
 
 function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean {
 	return (
@@ -315,18 +411,16 @@ export async function getDeepInterviewMutationDecision(
 ): Promise<DeepInterviewMutationDecision> {
 	if (!BLOCKED_TOOL_NAMES.has(input.tool.name)) return { blocked: false, targets: [] };
 	const targets = extractTargets(input.tool, input.args);
-	if (input.enforceWorkflowState !== false) {
+	if (input.enforceWorkflowState !== false && hasBlockedGjcTarget(input.cwd, targets)) {
 		const stateSkill = firstBlockedWorkflowStateSkill(input.cwd, targets);
-		if (stateSkill) {
-			const command = sanctionedWorkflowStateCommand(stateSkill);
-			return {
-				blocked: true,
-				message: `${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`,
-				targets: targets.paths,
-				reason: "workflow-state-target",
-				command,
-			};
-		}
+		const command = stateSkill ? sanctionedWorkflowStateCommand(stateSkill) : "gjc <workflow-command>";
+		return {
+			blocked: true,
+			message: `${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`,
+			targets: targets.paths,
+			reason: stateSkill ? "workflow-state-target" : "gjc-target",
+			command,
+		};
 	}
 	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) {
 		return { blocked: false, targets: [] };
@@ -340,6 +434,9 @@ export async function getDeepInterviewMutationDecision(
 			reason: "unknown-target",
 		};
 	}
+	if (input.tool.name === "bash") {
+		return { blocked: false, targets: targets.paths };
+	}
 	return {
 		blocked: true,
 		message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,

package/src/skill-state/initial-phase.ts

@@ -13,5 +13,7 @@ import type { CanonicalGjcWorkflowSkill } from "./active-state";
 export function initialPhaseForSkill(skill: CanonicalGjcWorkflowSkill | string): string {
 	if (skill === "deep-interview") return "interviewing";
 	if (skill === "ultragoal") return "goal-planning";
+	if (skill === "ralplan") return "planner";
+	if (skill === "team") return "starting";
 	return "planning";
 }

package/src/skill-state/workflow-state-contract.ts

@@ -1,14 +1,24 @@
 import * as path from "node:path";
 import { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill, SKILL_ACTIVE_STATE_FILE } from "./active-state";
+import { WORKFLOW_STATE_RECEIPT_FRESH_MS, WORKFLOW_STATE_RECEIPT_VERSION } from "./workflow-state-version";
 
-export type { CanonicalGjcWorkflowSkill };
-
-export const WORKFLOW_STATE_RECEIPT_VERSION = 1;
-export const WORKFLOW_STATE_RECEIPT_FRESH_MS = 30 * 60 * 1000;
+export {
+	WORKFLOW_STATE_RECEIPT_FRESH_MS,
+	WORKFLOW_STATE_RECEIPT_VERSION,
+	WORKFLOW_STATE_VERSION,
+} from "./workflow-state-version";
 
+export type { CanonicalGjcWorkflowSkill };
 export type WorkflowStateMutationOwner = "gjc-state-cli" | "gjc-runtime" | "gjc-hook";
 export type WorkflowStateReceiptStatus = "fresh" | "stale";
 
+export interface WorkflowStateContentChecksum {
+	algorithm: "sha256";
+	value: string;
+	covered_path: string;
+	computed_at: string;
+}
+
 export interface WorkflowStateReceipt {
 	version: 1;
 	skill: CanonicalGjcWorkflowSkill;
@@ -20,6 +30,25 @@ export interface WorkflowStateReceipt {
 	fresh_until: string;
 	status: WorkflowStateReceiptStatus;
 	mutation_id: string;
+	verb?: string;
+	from_phase?: string;
+	to_phase?: string;
+	forced?: boolean;
+	paths?: string[];
+	content_sha256?: WorkflowStateContentChecksum;
+}
+
+export interface AuditEntry {
+	ts: string;
+	skill?: string;
+	category: string;
+	verb: string;
+	owner: WorkflowStateMutationOwner;
+	mutation_id: string;
+	from_phase?: string;
+	to_phase?: string;
+	forced: boolean;
+	paths: string[];
 }
 
 function safeString(value: unknown): string {

package/src/skill-state/workflow-state-version.ts

@@ -0,0 +1,3 @@
+export const WORKFLOW_STATE_RECEIPT_VERSION = 1;
+export const WORKFLOW_STATE_VERSION = 2;
+export const WORKFLOW_STATE_RECEIPT_FRESH_MS = 30 * 60 * 1000;

package/src/slash-commands/builtin-registry.ts

@@ -586,6 +586,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "monitors",
+		description: "Open the monitor/cron jobs overlay",
+		handleTui: (_command, runtime) => {
+			runtime.ctx.showJobsOverlay();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "tree",
 		description: "Navigate session tree (switch branches)",