@gajae-code/coding-agent 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [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
+
+- 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.
+
 ## [0.2.5] - 2026-06-02
 
 ### Added

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

@@ -2,7 +2,7 @@ import type { AgentSource } from "../task/types";
 export interface AsyncJob {
     id: string;
     type: "bash" | "task";
-    status: "running" | "completed" | "failed" | "cancelled";
+    status: "running" | "completed" | "failed" | "cancelled" | "paused";
     startTime: number;
     label: string;
     abortController: AbortController;
@@ -26,6 +26,63 @@ 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
+ * non-terminal and non-delivering: the run suspended at a safe boundary and the
+ * subagent can be resumed from its persisted sessionFile. `completed` always
+ * wins a race with a late pause because the run returns it once it has actually
+ * finished.
+ */
+export type SubagentRunOutcome = {
+    kind: "completed";
+    text: string;
+} | {
+    kind: "paused";
+    note?: string;
+};
+/** Canonical lifecycle of a subagent across pause/resume cycles. */
+export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
+/**
+ * Live, executor-owned control handle for a RUNNING subagent. Registered when a
+ * subagent run starts and removed on pause/terminal so a paused subagent retains
+ * no live `AgentSession` reference (leak-free).
+ */
+export interface SubagentLiveHandle {
+    /** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
+    requestPause(): void;
+    /** Inject a steering message into the live session. */
+    injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn"): Promise<void>;
+}
+/**
+ * Canonical, stable-id-keyed record for a subagent. Survives `AsyncJob`
+ * eviction so resume stays addressable by subagent id, and is the single source
+ * of truth for control-plane status and identity.
+ */
+export interface SubagentRecord {
+    subagentId: string;
+    ownerId?: string;
+    /** Current live/last AsyncJob id; null while queued with no active job. */
+    currentJobId: string | null;
+    historicalJobIds: string[];
+    status: SubagentLifecycle;
+    sessionFile: string | null;
+    /** False for ephemeral sessions (no persistent artifacts dir). */
+    resumable: boolean;
+    queued?: {
+        ownerId?: string;
+        seq: number;
+        message?: string;
+        createdAt: number;
+    };
+}
+/** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
+export interface ResumeDescriptor {
+    subagentId: string;
+    ownerId?: string;
+    data: unknown;
 }
 export interface AsyncJobManagerOptions {
     onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
@@ -84,17 +141,49 @@ 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;
         reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
-    }) => Promise<string>, options?: AsyncJobRegisterOptions): string;
+    }) => Promise<string | SubagentRunOutcome>, options?: AsyncJobRegisterOptions): string;
     /**
      * Cancel a single job by id. When `filter.ownerId` is set and does not
      * match the job's owner, the call is treated as not-found (returns false)
      * so cross-agent cancellation is rejected at the manager level.
      */
     cancel(id: string, filter?: AsyncJobFilter): boolean;
+    /** Register or replace the canonical record for a subagent. */
+    registerSubagentRecord(record: SubagentRecord): void;
+    getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined;
+    getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[];
+    registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void;
+    getLiveHandle(subagentId: string): SubagentLiveHandle | undefined;
+    removeLiveHandle(subagentId: string): void;
+    /** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
+    setResumeRunner(runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined): void;
+    registerResumeDescriptor(descriptor: ResumeDescriptor): void;
+    getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined;
+    /** Request a graceful safe-boundary pause of a running subagent. */
+    pauseSubagent(subagentId: string, filter?: AsyncJobFilter): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        reason?: string;
+    };
+    /** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+    resumeSubagent(subagentId: string, filter?: AsyncJobFilter, message?: string): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        jobId?: string;
+        queued?: boolean;
+        reason?: string;
+    };
+    /** Cancel a subagent by stable id across running/paused/queued states (keeps the session file). */
+    cancelSubagent(subagentId: string, filter?: AsyncJobFilter): boolean;
     getJob(id: string): AsyncJob | undefined;
     getRunningJobs(filter?: AsyncJobFilter): AsyncJob[];
     getRecentJobs(limit?: number, filter?: AsyncJobFilter): AsyncJob[];

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/commands/harness.d.ts

@@ -0,0 +1,37 @@
+import { Command } from "@gajae-code/utils/cli";
+export default class Harness extends Command {
+    #private;
+    static description: string;
+    static strict: boolean;
+    static args: {
+        verb: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: true;
+        };
+    };
+    static flags: {
+        input: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            default: string;
+        };
+        session: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            char: string;
+            description: string;
+        };
+        cursor: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            default: string;
+        };
+        follow: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

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;
@@ -74,6 +74,7 @@ interface StringDef {
 interface NumberDef {
     type: "number";
     default: number;
+    validate?: (value: number) => boolean;
     ui?: UiNumber;
 }
 interface EnumDef<T extends readonly string[]> {
@@ -200,6 +201,11 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "array";
         readonly default: string[];
     };
+    readonly "gjc.deepInterview.ambiguityThreshold": {
+        readonly type: "number";
+        readonly default: 0.05;
+        readonly validate: (value: number) => boolean;
+    };
     readonly "theme.dark": {
         readonly type: "string";
         readonly default: "red-claw";
@@ -2691,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";
@@ -2756,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/config/settings.d.ts

@@ -54,6 +54,8 @@ export declare class Settings {
      * Returns the merged value from global + project + overrides, or the default.
      */
     get<P extends SettingPath>(path: P): SettingValue<P>;
+    /** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
+    has(path: SettingPath): boolean;
     /**
      * Set a setting value (sync).
      * Updates global settings and queues a background save.

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

@@ -0,0 +1,6 @@
+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/extensibility/custom-tools/types.d.ts

@@ -98,6 +98,7 @@ export type CustomToolSessionEvent = {
     maxAttempts: number;
     delayMs: number;
     errorMessage: string;
+    unbounded?: boolean;
 } | {
     reason: "auto_retry_end";
     success: boolean;

package/dist/types/extensibility/extensions/types.d.ts

@@ -56,6 +56,12 @@ export interface ExtensionUIDialogOptions {
      * hint; non-TUI bridges (RPC, ACP) drop it and do not serialize it.
      */
     wrapFocused?: boolean;
+    /**
+     * For interactive TUI select dialogs, cap the title/prompt area to this
+     * many rows and let PageUp/PageDown scroll that prompt locally. This is a
+     * select-only rendering hint; non-TUI bridges drop it and do not serialize it.
+     */
+    scrollTitleRows?: number;
 }
 /** Raw terminal input listener for extensions. */
 export type TerminalInputHandler = (data: string) => {

package/dist/types/extensibility/shared-events.d.ts

@@ -180,6 +180,7 @@ export interface AutoRetryStartEvent {
     maxAttempts: number;
     delayMs: number;
     errorMessage: string;
+    unbounded?: boolean;
 }
 /** Fired when auto-retry ends */
 export interface AutoRetryEndEvent {

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-graph.d.ts

@@ -0,0 +1,4 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export type StateGraphSkill = CanonicalGjcWorkflowSkill | "all";
+export type StateGraphFormat = "ascii" | "mermaid" | "dot";
+export declare function renderStateGraph(skill: StateGraphSkill, format?: string): string;

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

@@ -0,0 +1,33 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export interface NormalizeLegacyStateResult {
+    state: Record<string, unknown>;
+    changed: boolean;
+}
+export interface MigrateAndPersistLegacyStateArgs {
+    cwd: string;
+    skill: string;
+    statePath: string;
+    sessionId?: string;
+}
+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.
+ *
+ * Readers that need compatibility with old on-disk workflow state shapes must call
+ * this in-memory helper and must never call `migrateAndPersistLegacyState`. The
+ * persist variant is reserved for explicit state migration commands because it is
+ * the only path allowed to write normalized upgrades back to `.gjc/state/**`.
+ */
+export declare function normalizeLegacyState(raw: Record<string, unknown>, skill: string): NormalizeLegacyStateResult;
+export declare function migrateAndPersistLegacyState(args: MigrateAndPersistLegacyStateArgs): Promise<MigrateAndPersistLegacyStateResult>;

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

@@ -0,0 +1,65 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import type { SkillManifest } from "./workflow-manifest";
+export declare const STATE_FIELD_ALLOWLIST: readonly ["skill", "phase", "current_phase", "next", "active", "status", "fresh", "fresh_until", "receipt", "artifact_path", "plan_path", "spec_path", "run_id", "stage", "stage_n", "session_id", "updated_at", "handoff_to", "handoff_from", "counts", "hud"];
+export type StateProjectionField = (typeof STATE_FIELD_ALLOWLIST)[number];
+export interface StateStatusSummary {
+    skill: CanonicalGjcWorkflowSkill;
+    phase: string;
+    active: boolean;
+    fresh: boolean;
+    fresh_until?: string;
+    next: string[];
+    receipt_status: string;
+    storage_path: string;
+}
+export declare function compactProjectStateJson(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): Record<string, unknown>;
+export declare function projectStateFields(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, fields: readonly StateProjectionField[]): Record<string, unknown>;
+export declare function buildStateStatusSummary(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, storagePath: string): StateStatusSummary;
+export declare function renderStateStatusLine(summary: StateStatusSummary): string;
+export declare function renderContractMarkdown(skill: CanonicalGjcWorkflowSkill, contract: unknown): string;
+export declare function renderHistoryMarkdown(history: {
+    entries: unknown[];
+    limit: number;
+    since?: string;
+    truncated: boolean;
+}): string;
+export declare function renderUltragoalStatusMarkdown(summary: {
+    exists: boolean;
+    status: string;
+    paths: {
+        goalsPath: string;
+        ledgerPath?: string;
+    };
+    gjcObjective?: string;
+    currentGoal?: {
+        id: string;
+        status: string;
+        title?: string;
+        objective?: string;
+    };
+    counts: Record<string, number>;
+    goals: unknown[];
+}): string;
+export declare function renderTeamStatusMarkdown(snapshot: {
+    team_name: string;
+    phase: string;
+    tmux_target?: string;
+    tmux_session?: string;
+    state_dir: string;
+    task_total: number;
+    task_counts: Record<string, number>;
+    workers: Array<{
+        id: string;
+        status: string;
+    }>;
+    notification_summary?: {
+        total: number;
+        replay_eligible: number;
+        by_state: Record<string, number>;
+    };
+    integration_by_worker?: Record<string, {
+        status?: string;
+        conflict_files?: string[];
+    }>;
+}): string;
+export declare function renderStateMarkdown(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): string;

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

@@ -1,3 +1,4 @@
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 /**
  * Native implementation of the `gjc state read|write|clear` command surface.
  *
@@ -10,4 +11,5 @@ export interface StateCommandResult {
     stdout?: string;
     stderr?: string;
 }
+export declare function readWorkflowStateJson(cwd: string, skill: CanonicalGjcWorkflowSkill, sessionId?: string): Promise<Record<string, unknown>>;
 export declare function runNativeStateCommand(args: string[], cwd?: string): Promise<StateCommandResult>;