@gajae-code/coding-agent 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-05
+### Added
+
+- Added opt-in crash diagnostics for subprocess failures, with a shared crash taxonomy/report writer, bash/Python/LSP/DAP crash notices, and a native Rust panic-report hook gated by `GJC_NATIVE_CRASH_DIAGNOSTICS` / `GJC_CRASH_DIAGNOSTICS`.
+- Started the GJC backend bridge foundation with a shared agent-wire protocol module, event envelopes, RPC command scope matrix, UI request broker, typed unsupported UI results, a guarded `--mode bridge` handshake surface, and RPC mode dispatch refactored onto the shared command dispatcher.
+- Documented the experimental `--mode bridge` protocol in `docs/bridge.md` and the `GJC_BRIDGE_*` environment variables in `docs/environment-variables.md` (TLS-mandatory startup, bearer auth, coarse command scopes with a `prompt` floor, single live `AgentSession` per process, bounded event-stream replay with `reset`, and the semantic-not-pixel UI capability matrix), and added bridge event-stream/idempotency regression tests plus a docs-conformance check that pins the docs against the protocol version, scope/command catalog, negotiated capabilities/frame types, and unsupported UI surfaces. The bridge protocol/SDK are experimental (`BRIDGE_PROTOCOL_VERSION` 1) and may change in additive, version-negotiated ways.
+
+### Fixed
+
+- Made opt-in crash diagnostics create/chmod report directories to `0700` and report files to `0600` so captured command, cwd, and stderr previews are private even under a permissive umask.
+- Scoped `agent://` and `artifact://` resolution to the caller's artifacts directory plus explicitly authorized parent/child tree directories, removed registry-wide live-session lookup/enumeration, and made missing agent-output metadata sidecars fail closed.
+- Fail-closed experimental bridge session endpoints by default for 0.3.1: events, commands, controller ownership, UI responses, host tool results, and host URI results are disabled unless an internal endpoint matrix explicitly enables them; only health/help and the authenticated handshake remain available, with the handshake advertising no enabled session surface by default.
+- Render terminal-pasted clipboard image temp paths as compact `[image N]` prompt placeholders while attaching the image payload, instead of inserting raw `/var/folders/.../clipboard-*.png` path text.
+- Preserved `gjc harness` `owner-vanished:*` blockers when a replacement owner becomes live so unrecovered prior-owner evidence remains visible until explicit recovery or terminal completion evidence; only safe startup liveness false-negatives such as `detached-owner-not-live` are auto-cleared.
+- Fixed the interactive agent unexpectedly stopping after automatic context maintenance instead of resuming the in-flight task. Post-compaction continuation now schedules exactly one source per completion (overflow retry → queued messages → synthetic auto-continue prompt), the threshold/handoff auto-continue prompt skips a redundant pre-send compaction check, overflow retry strips only the context-overflow failed turn (never normal/aborted/silent-abort tails), and non-resumable or superseded continuations log a structured reason instead of stranding the session.
+- Fixed the native Stop skill-state hook letting active GJC workflow skills stop prematurely. The Stop hook no longer treats a missing/unreadable mode-state file as terminal for handoff workflows, and handoff skills (`deep-interview`, `ralplan`) now keep blocking Stop even in the `handoff` phase until they are demoted (`active:false`) or cleared, so they always end by offering the next handoff step via the ask tool. Non-handoff skills (`team`, `ultragoal`) retain the fail-open safety valve when their mode-state file is corrupt or invalid.
+
 ## [0.3.0] - 2026-06-03
 
 ### Added
@@ -9,6 +26,7 @@
 - Added runtime-enforced Ultragoal executor QA/red-team evidence matrices for completion checkpoints, with plan-first contract coverage, user-surface evidence, adversarial cases, artifact references, scoped Executor red-team guidance, and focused rejection tests for shallow or contradictory QA evidence.
 ### Fixed
 
+- Made `gjc harness observe` preserve completed RPC owner evidence after the owner exits, including a `completedOwnerExited` diagnostic and durable terminal-result cursor.
 - Clarified that `gjc team` requires an existing tmux-backed leader session from `gjc --tmux`, with actionable help, docs, and failure text.
 - Kept deep-interview ask options visible for long prompts by adding an opt-in scrollable selector title panel with selector-local `PageUp`/`PageDown` prompt scrolling, while leaving normal ask dialogs and global keybinding configuration unchanged.
 

package/dist/types/async/job-manager.d.ts

@@ -26,6 +26,8 @@ export interface AsyncJobMetadata {
         description?: string;
         assignment?: string;
     };
+    /** True when this bash job was started by the `monitor` tool (vs plain async bash). */
+    monitor?: boolean;
 }
 /**
  * Typed outcome a subagent task run may produce. A `paused` outcome is
@@ -139,6 +141,11 @@ export declare class AsyncJobManager {
     /** Reset the process-global instance. Test-only. */
     static resetForTests(): void;
     constructor(options: AsyncJobManagerOptions);
+    /**
+     * Subscribe to live-job-set change events. Returns an unsubscribe function.
+     * Listener errors are isolated so one bad subscriber cannot break others.
+     */
+    onChange(cb: () => void): () => void;
     register(type: "bash" | "task", label: string, run: (ctx: {
         jobId: string;
         signal: AbortSignal;

package/dist/types/cli/args.d.ts

@@ -2,7 +2,7 @@
  * CLI argument parsing and help display
  */
 import { type Effort } from "@gajae-code/ai";
-export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui";
+export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui" | "bridge";
 export interface Args {
     cwd?: string;
     allowHome?: boolean;

package/dist/types/commands/deep-interview.d.ts

@@ -39,6 +39,9 @@ export default class DeepInterview extends Command {
         deliberate: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
         };
+        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
         json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
         };

package/dist/types/config/keybindings.d.ts

@@ -26,6 +26,7 @@ interface AppKeybindings {
     "app.session.fork": true;
     "app.session.resume": true;
     "app.session.observe": true;
+    "app.jobs.open": true;
     "app.session.togglePath": true;
     "app.session.toggleSort": true;
     "app.session.rename": true;
@@ -258,6 +259,10 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+s";
         readonly description: "Observe subagent sessions";
     };
+    readonly "app.jobs.open": {
+        readonly defaultKeys: "alt+j";
+        readonly description: "Open monitor/cron jobs overlay";
+    };
     readonly "app.session.togglePath": {
         readonly defaultKeys: "ctrl+p";
         readonly description: "Toggle session path display";

package/dist/types/config/settings-schema.d.ts

@@ -24,7 +24,7 @@ export declare const TAB_METADATA: Record<SettingTab, {
     icon: `tab.${string}`;
 }>;
 /** Status line segment identifiers */
-export type StatusLineSegmentId = "gajae" | "pi" | "model" | "mode" | "path" | "git" | "pr" | "subagents" | "token_in" | "token_out" | "token_total" | "token_rate" | "cost" | "context_pct" | "context_total" | "time_spent" | "time" | "session" | "hostname" | "cache_read" | "cache_write" | "session_name" | "usage";
+export type StatusLineSegmentId = "gajae" | "pi" | "model" | "mode" | "path" | "git" | "pr" | "subagents" | "jobs" | "token_in" | "token_out" | "token_total" | "token_rate" | "cost" | "context_pct" | "context_total" | "time_spent" | "time" | "session" | "hostname" | "cache_read" | "cache_write" | "session_name" | "usage";
 /** Submenu choice metadata. */
 export type SubmenuOption<V extends string = string> = {
     value: V;
@@ -2697,11 +2697,11 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "task.maxConcurrency": {
         readonly type: "number";
-        readonly default: 32;
+        readonly default: 8;
         readonly ui: {
             readonly tab: "tasks";
             readonly label: "Max Concurrent Tasks";
-            readonly description: "Concurrent limit for subagents";
+            readonly description: "Safer concurrent limit for subagents; higher fan-out still requires an explicit plan above 4 tasks.";
             readonly options: readonly [{
                 readonly value: "0";
                 readonly label: "Unlimited";
@@ -2762,7 +2762,7 @@ export declare const SETTINGS_SCHEMA: {
         readonly ui: {
             readonly tab: "tasks";
             readonly label: "Fork Context Max Tokens";
-            readonly description: "Approximate token cap for fork-context seeds. 0 uses 25% of the target model context window.";
+            readonly description: "Approximate token cap for explicit full fork-context seeds. 0 uses 15% of the target model context window, with a 15k fallback when the window is unknown.";
         };
     };
     readonly "task.maxRecursionDepth": {

package/dist/types/debug/crash-diagnostics.d.ts

@@ -0,0 +1,45 @@
+export type CrashProcessKind = "bash" | "python" | "lsp" | "dap" | "mcp" | "browser" | "worker" | "native" | "unknown";
+export type CrashClass = "clean_exit" | "non_zero_exit" | "signal_exit" | "timeout" | "cancelled" | "spawn_error" | "protocol_exit" | "native_panic" | "unknown";
+export interface CrashClassificationInput {
+    kind: CrashProcessKind;
+    command?: string[];
+    exitCode?: number | null;
+    signal?: string | null;
+    cancelled?: boolean;
+    timedOut?: boolean;
+    spawnError?: unknown;
+    stderr?: string;
+    protocol?: string;
+}
+export interface CrashClassification {
+    kind: CrashProcessKind;
+    class: CrashClass;
+    crashed: boolean;
+    exitCode: number | null;
+    signal: string | null;
+    command?: string[];
+    protocol?: string;
+    reason: string;
+}
+export interface CrashReport extends CrashClassification {
+    schemaVersion: 1;
+    createdAt: string;
+    pid: number;
+    cwd: string;
+    stderrPreview?: string;
+    spawnError?: string;
+}
+export interface CrashReportWriteResult {
+    report: CrashReport;
+    path: string | null;
+    enabled: boolean;
+}
+export declare function crashDiagnosticsEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function getCrashDiagnosticsDirectory(env?: NodeJS.ProcessEnv): string;
+export declare function classifyProcessCrash(input: CrashClassificationInput): CrashClassification;
+export declare function writeCrashReport(input: CrashClassificationInput, options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+}): Promise<CrashReportWriteResult>;
+export declare function formatCrashDiagnosticNotice(result: CrashReportWriteResult): string | null;

package/dist/types/debug/runtime-gauges.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Current runtime owner counts, keyed by `<owner>.<resource>`. Extend as more
+ * owners (Python kernels, LSP clients, browser tabs, async jobs, streaming
+ * queues) expose count getters.
+ */
+export declare function getRuntimeResourceCounts(): Record<string, number>;

package/dist/types/deep-interview/render-middleware.d.ts

@@ -2,4 +2,5 @@ import { type Component } from "@gajae-code/tui";
 import { type Theme } from "../modes/theme/theme";
 export declare function renderDeepInterviewAssistantText(text: string, uiTheme: Theme): Component | null;
 export declare function renderDeepInterviewAskQuestion(question: string, uiTheme: Theme): Component | null;
+export declare function isDeepInterviewAskQuestion(question: string): boolean;
 export declare function formatDeepInterviewSelectorPrompt(question: string): string | null;

package/dist/types/eval/py/executor.d.ts

@@ -52,6 +52,8 @@ export interface PythonExecutorOptions {
 }
 export interface PythonKernelExecutor {
     execute: (code: string, options?: KernelExecuteOptions) => Promise<KernelExecuteResult>;
+    getExitCode?: () => number | null;
+    peekStderr?: () => string;
 }
 export interface PythonResult {
     /** Combined stdout + stderr output (sanitized, possibly truncated) */

package/dist/types/eval/py/kernel.d.ts

@@ -55,6 +55,8 @@ export declare class PythonKernel {
     private constructor();
     static start(options: KernelStartOptions): Promise<PythonKernel>;
     isAlive(): boolean;
+    getExitCode(): number | null;
+    peekStderr(): string;
     execute(code: string, options?: KernelExecuteOptions): Promise<KernelExecuteResult>;
     interrupt(): Promise<void>;
     shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult>;

package/dist/types/exec/bash-executor.d.ts

@@ -43,6 +43,16 @@ export interface BashResult {
     outputBytes: number;
     artifactId?: string;
 }
+/** Number of persistent shell sessions currently retained (owner gauge). */
+export declare function getShellSessionCount(): number;
+/**
+ * Dispose all persistent shell sessions: abort in-flight work and drop the
+ * strong references so the native shells can be finalized. Healthy persistent
+ * sessions are otherwise retained for the whole process lifetime (MEM-7). This
+ * is registered as a postmortem cleanup so shutdown/signals release native
+ * shell resources, and is also callable directly (e.g. on owner teardown).
+ */
+export declare function disposeAllShellSessions(): Promise<void>;
 /** Translate `ShellMinimizerSettings` into native `MinimizerOptions`, or `undefined` when disabled. */
 export declare function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerOptions | undefined;
 export declare function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult>;

package/dist/types/gjc-runtime/cli-write-receipt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI write/mutation receipt shaping (Workstream B, v4).
+ *
+ * `CliWriteReceipt` is the compact **stdout presentation** returned by a GJC
+ * mutation command. It carries only routing/audit fields a caller needs; it
+ * NEVER echoes the persisted body (full `state` envelope, ultragoal `plan`,
+ * team task body, ralplan `task`, etc.) — echoing those back is a redundant
+ * token leak because the caller already has the content it just wrote.
+ *
+ * This is intentionally a *separate* concept from the persisted
+ * `WorkflowStateReceipt` (the on-disk envelope `receipt` integrity field).
+ * Do NOT use `CliWriteReceipt` as a persistence schema or validate persisted
+ * envelopes against it.
+ */
+export interface CliWriteReceipt {
+    ok: boolean;
+    [field: string]: unknown;
+}
+/**
+ * Serialize a write/mutation receipt to compact stdout JSON.
+ * `undefined` fields are dropped so optional routing fields stay absent
+ * rather than serialized as `null`.
+ */
+export declare function renderCliWriteReceipt(receipt: Record<string, unknown>): string;

package/dist/types/gjc-runtime/deep-interview-runtime.d.ts

@@ -20,6 +20,7 @@ export interface ResolvedDeepInterviewSpecWriteArgs {
     json: boolean;
     deliberate: boolean;
     handoff?: "ralplan";
+    force: boolean;
 }
 export interface PersistedDeepInterviewSpec {
     slug: string;

package/dist/types/gjc-runtime/state-migrations.d.ts

@@ -1,3 +1,4 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 export interface NormalizeLegacyStateResult {
     state: Record<string, unknown>;
     changed: boolean;
@@ -12,6 +13,14 @@ export interface MigrateAndPersistLegacyStateResult {
     migrated: boolean;
     path: string;
 }
+export interface MigrateWorkflowStateResult {
+    state: Record<string, unknown>;
+    fromVersion: number;
+    toVersion: number;
+    changed: boolean;
+}
+export type WorkflowStateMigration = (state: Record<string, unknown>, skill: CanonicalGjcWorkflowSkill) => Record<string, unknown>;
+export declare function migrateWorkflowState(raw: Record<string, unknown>, skill: string): MigrateWorkflowStateResult;
 /**
  * Pure legacy state normalizer for background/internal readers.
  *

package/dist/types/gjc-runtime/state-schema.d.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+export declare const WorkflowStateContentChecksumSchema: z.ZodObject<{
+    algorithm: z.ZodLiteral<"sha256">;
+    value: z.ZodString;
+    covered_path: z.ZodString;
+    computed_at: z.ZodString;
+}, z.core.$loose>;
+/** Lenient receipt schema for reads (mirrors WorkflowStateReceipt). */
+export declare const WorkflowStateReceiptSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    owner: z.ZodEnum<{
+        "gjc-hook": "gjc-hook";
+        "gjc-runtime": "gjc-runtime";
+        "gjc-state-cli": "gjc-state-cli";
+    }>;
+    command: z.ZodString;
+    state_path: z.ZodString;
+    storage_path: z.ZodString;
+    mutated_at: z.ZodString;
+    fresh_until: z.ZodString;
+    status: z.ZodEnum<{
+        fresh: "fresh";
+        stale: "stale";
+    }>;
+    mutation_id: z.ZodString;
+    verb: z.ZodOptional<z.ZodString>;
+    from_phase: z.ZodOptional<z.ZodString>;
+    to_phase: z.ZodOptional<z.ZodString>;
+    forced: z.ZodOptional<z.ZodBoolean>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content_sha256: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        value: z.ZodString;
+        covered_path: z.ZodString;
+        computed_at: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Lenient envelope schema for reads. Every non-structural field optional. */
+export declare const WorkflowStateEnvelopeSchema: z.ZodObject<{
+    skill: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    current_phase: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNumber>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    receipt: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        verb: z.ZodOptional<z.ZodString>;
+        from_phase: z.ZodOptional<z.ZodString>;
+        to_phase: z.ZodOptional<z.ZodString>;
+        forced: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content_sha256: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * Strict receipt required on WRITE (post checksum-stamping). Anchored to the
+ * fields the sanctioned writer emits — `content_sha256` is REQUIRED here.
+ */
+export declare const RequiredWorkflowStateReceiptSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    owner: z.ZodEnum<{
+        "gjc-hook": "gjc-hook";
+        "gjc-runtime": "gjc-runtime";
+        "gjc-state-cli": "gjc-state-cli";
+    }>;
+    command: z.ZodString;
+    state_path: z.ZodString;
+    storage_path: z.ZodString;
+    mutated_at: z.ZodString;
+    fresh_until: z.ZodString;
+    status: z.ZodEnum<{
+        fresh: "fresh";
+        stale: "stale";
+    }>;
+    mutation_id: z.ZodString;
+    content_sha256: z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        value: z.ZodString;
+        covered_path: z.ZodString;
+        computed_at: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/**
+ * Write-side fail-closed gate: the serialized on-disk envelope must satisfy
+ * this after checksum stamping. Anchored to current sanctioned-writer output.
+ */
+export declare const RequiredOnWriteEnvelopeSchema: z.ZodObject<{
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    version: z.ZodLiteral<2>;
+    updated_at: z.ZodString;
+    current_phase: z.ZodString;
+    active: z.ZodBoolean;
+    receipt: z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        content_sha256: z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** Per-skill mode state consumed by hooks / the mutation guard. */
+export declare const ModeStateSchema: z.ZodObject<{
+    active: z.ZodOptional<z.ZodBoolean>;
+    current_phase: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    handoff_from: z.ZodOptional<z.ZodString>;
+    handoff_to: z.ZodOptional<z.ZodString>;
+    handoff_at: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const SkillActiveEntrySchema: z.ZodObject<{
+    skill: z.ZodString;
+    phase: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    activated_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    stale: z.ZodOptional<z.ZodBoolean>;
+    handoff_from: z.ZodOptional<z.ZodString>;
+    handoff_to: z.ZodOptional<z.ZodString>;
+    handoff_at: z.ZodOptional<z.ZodString>;
+    receipt: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        verb: z.ZodOptional<z.ZodString>;
+        from_phase: z.ZodOptional<z.ZodString>;
+        to_phase: z.ZodOptional<z.ZodString>;
+        forced: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content_sha256: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export declare const SkillActiveStateSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodNumber>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    skill: z.ZodOptional<z.ZodString>;
+    keyword: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodString>;
+    activated_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    active_skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        skill: z.ZodString;
+        phase: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        activated_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<z.ZodString>;
+        session_id: z.ZodOptional<z.ZodString>;
+        thread_id: z.ZodOptional<z.ZodString>;
+        turn_id: z.ZodOptional<z.ZodString>;
+        stale: z.ZodOptional<z.ZodBoolean>;
+        handoff_from: z.ZodOptional<z.ZodString>;
+        handoff_to: z.ZodOptional<z.ZodString>;
+        handoff_at: z.ZodOptional<z.ZodString>;
+        receipt: z.ZodOptional<z.ZodObject<{
+            version: z.ZodNumber;
+            skill: z.ZodEnum<{
+                "deep-interview": "deep-interview";
+                ralplan: "ralplan";
+                team: "team";
+                ultragoal: "ultragoal";
+            }>;
+            owner: z.ZodEnum<{
+                "gjc-hook": "gjc-hook";
+                "gjc-runtime": "gjc-runtime";
+                "gjc-state-cli": "gjc-state-cli";
+            }>;
+            command: z.ZodString;
+            state_path: z.ZodString;
+            storage_path: z.ZodString;
+            mutated_at: z.ZodString;
+            fresh_until: z.ZodString;
+            status: z.ZodEnum<{
+                fresh: "fresh";
+                stale: "stale";
+            }>;
+            mutation_id: z.ZodString;
+            verb: z.ZodOptional<z.ZodString>;
+            from_phase: z.ZodOptional<z.ZodString>;
+            to_phase: z.ZodOptional<z.ZodString>;
+            forced: z.ZodOptional<z.ZodBoolean>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            content_sha256: z.ZodOptional<z.ZodObject<{
+                algorithm: z.ZodLiteral<"sha256">;
+                value: z.ZodString;
+                covered_path: z.ZodString;
+                computed_at: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+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;
+};
+/**
+ * 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 declare function readGjcJson<T>(filePath: string, schema: z.ZodType<T>): Promise<ReadGjcJsonResult<T> | null>;

package/dist/types/gjc-runtime/state-writer.d.ts

@@ -93,6 +93,16 @@ export declare class AlreadyExistsError extends Error {
     readonly path: string;
     constructor(path: string);
 }
+export type StrictMutationReadResult = {
+    kind: "absent";
+} | {
+    kind: "corrupt";
+    error: string;
+} | {
+    kind: "valid";
+    value: Record<string, unknown>;
+};
+export declare function readExistingStateForMutation(filePath: string): Promise<StrictMutationReadResult>;
 export declare function workflowEnvelopeContentSha256(value: unknown): string;
 export declare function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt?: string): T;
 export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string): Promise<WorkflowEnvelopeIntegrityMismatch | undefined>;

package/dist/types/gjc-runtime/workflow-command-ref.d.ts

@@ -0,0 +1,43 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export type CommandRefVisibility = "public" | "hidden" | "planned";
+export type CommandRefIncludeWhen = "implemented-only" | "planned";
+export interface CommandRefCommand {
+    tokens: string[];
+    rendered: string;
+    visibility: CommandRefVisibility;
+    includeWhen: CommandRefIncludeWhen;
+    note?: string;
+}
+export interface CommandRefExample {
+    label?: string;
+    bytes: string;
+}
+export interface CommandRefBridge {
+    from: string;
+    to: string;
+    rendered: string;
+}
+export interface CommandRefBlock {
+    skill: CanonicalGjcWorkflowSkill;
+    blockId: string;
+    sourcePath: string;
+    renderOrder: number;
+    markers: {
+        start: string;
+        end: string;
+    };
+    commands: CommandRefCommand[];
+    examples: CommandRefExample[];
+    aliasesAndBridges: CommandRefBridge[];
+    notes: string[];
+}
+export interface RenderedCommandRefBlock {
+    skill: CanonicalGjcWorkflowSkill;
+    blockId: string;
+    markers: CommandRefBlock["markers"];
+    bytes: string;
+}
+export declare const WORKFLOW_COMMAND_REF_BLOCKS: readonly CommandRefBlock[];
+export declare function listCommandRefBlocks(skill?: CanonicalGjcWorkflowSkill): CommandRefBlock[];
+export declare function renderCommandRefBlock(skill: CanonicalGjcWorkflowSkill, blockId?: string): RenderedCommandRefBlock;
+export declare function isCanonicalGjcWorkflowSkill(value: string): value is CanonicalGjcWorkflowSkill;