@gajae-code/coding-agent 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-06-14
+
+### Added
+
+- `gjc --mode rpc` registers each live session in a cross-process registry (`<agent-dir>/rpc-sessions/<id>.json`) on start and removes it on shutdown, so other processes can enumerate running RPC sessions. The Python `gjc_rpc` client exposes `list_sessions()` / `RpcClient.list_sessions()` returning typed `SessionHandle`s and reaps records whose owning process is gone (issue 10; foundation for reattach/issue 09).
+- `gjc --mode rpc --listen <socket-path>` runs a persistent Unix-domain-socket RPC server: the `AgentSession` outlives client disconnects (no stdin-EOF teardown) and a client can disconnect and reconnect to the same live session over the socket. The session is registered with `transport: "socket"` and the socket path as its `endpoint`, so it is discoverable/attachable via the registry. The stdio path is unchanged (frame output routes through a swappable sink shared by both transports) (issue 09).
+
+### Fixed
+
+- Subagent/job status panels now freeze a job's elapsed timer the moment it stops running (`completed`/`failed`/`cancelled`/`paused`) instead of counting up against `Date.now()` forever. `AsyncJob` records an `endTime` on the first terminal/pause transition and a shared `jobElapsedMs` helper backs the `subagent` panel, the `job` tool, `/jobs`, and the command-controller job line, so a finished subagent stops at its real duration while siblings keep ticking.
+- RPC control-plane hardening (from dogfooding `gjc --mode rpc`): `dispatchRpcCommand` now wraps the command switch so failures return a correlated response carrying the request `id` and the real command name, instead of dropping the id and mislabeling handler exceptions as `parse`; `set_thinking_level`/`set_steering_mode`/`set_follow_up_mode`/`set_interrupt_mode` validate their inputs and reject out-of-contract values instead of silently corrupting session state; `negotiate_unattended` rejects unknown scopes/action classes with `invalid_unattended_declaration` and merges the mandatory `prompt` scope plus its `command.prompt` action floor into the accepted grant (so prompt/`workflow_gate_response` are never locked out); and read-only/control RPC commands no longer consume the unattended `max_tool_calls` budget while wall-time enforcement is preserved. `docs/rpc.md`'s first `workflow_gate` example now matches the canonical `RpcWorkflowGate` shape.
+- RPC mode no longer head-of-line-blocks control/cancellation commands behind a long-running command: the stdin loop now dispatches ordered commands through a serial chain (so causal order is preserved — e.g. `get_state` after `bash` still observes the bash result) without blocking the reader, and routes `abort`/`abort_bash`/`abort_retry` on an immediate fast lane so they reach in-flight work. `abort_bash` can now cancel a running `bash`, and a slow `compact`/`handoff`/`login` no longer freezes the whole control plane. Shutdown drains in-flight commands (bounded) so their responses are still emitted on stdin EOF.
+- Counted active prompts and agent-initiated custom messages in pre-prompt context maintenance so background task notifications trigger compaction before they can overflow the next model request.
+- Bounded monitor task-notification payloads to a compact tail window while preserving full background job output for job inspection.
+
+### Changed
+
+- Expanded coordinator MCP coordination status into a canonical polling snapshot for sessions, session states, turns, questions, reports, and bounded event summaries, and documented that Hermes/coordinator consumption is polling/await rather than push subscription.
+
 ## [0.5.0] - 2026-06-13
 
 ### Fixed

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

@@ -4,6 +4,13 @@ export interface AsyncJob {
     type: "bash" | "task";
     status: "running" | "completed" | "failed" | "cancelled" | "paused";
     startTime: number;
+    /**
+     * Wall-clock ms when the job left the `running` state (completed, failed,
+     * cancelled, or paused). Undefined while running. Frozen on the first
+     * terminal/pause transition so elapsed-time renderers stop counting once a
+     * job is no longer active instead of growing forever against `Date.now()`.
+     */
+    endTime?: number;
     label: string;
     abortController: AbortController;
     promise: Promise<void>;
@@ -18,6 +25,13 @@ export interface AsyncJob {
      */
     ownerId?: string;
 }
+/**
+ * Elapsed wall-clock ms for a job, frozen once it stops running. While the job
+ * is active (`endTime` undefined) this counts against `now`; after it stops it
+ * returns the fixed `endTime - startTime` span so status renderers do not keep
+ * incrementing a completed job's timer.
+ */
+export declare function jobElapsedMs(job: Pick<AsyncJob, "startTime" | "endTime">, now?: number): number;
 export interface AsyncJobMetadata {
     subagent?: {
         id: string;
@@ -77,6 +91,12 @@ export interface SubagentRecord {
         message?: string;
         createdAt: number;
     };
+    /** Resolved model the subagent was asked to use, e.g. "openai-codex/gpt-5.5". */
+    requestedModel?: string;
+    /** Model actually used after auth fallback (#985); equals requestedModel when no fallback. */
+    effectiveModel?: string;
+    /** True when the requested model lacked credentials and the subagent fell back to the parent model. */
+    modelFellBack?: boolean;
 }
 /** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
 export interface ResumeDescriptor {
@@ -184,6 +204,12 @@ export declare class AsyncJobManager {
     };
     /** Register or replace the canonical record for a subagent. */
     registerSubagentRecord(record: SubagentRecord): void;
+    /** Patch model metadata onto an existing subagent record (best-effort; no-op if unknown). */
+    updateSubagentModel(subagentId: string, model: {
+        requestedModel?: string;
+        effectiveModel?: string;
+        modelFellBack?: boolean;
+    }): void;
     getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined;
     getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[];
     registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void;

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

@@ -24,6 +24,7 @@ export interface Args {
     mode?: Mode;
     noSession?: boolean;
     sessionDir?: string;
+    rpcListen?: string;
     providerSessionId?: string;
     fork?: string;
     models?: string[];

package/dist/types/cli/list-models.d.ts

@@ -1,4 +1,5 @@
 import type { ModelRegistry } from "../config/model-registry";
+import { type ExtensionFactory } from "../extensibility/extensions";
 /**
  * List available models, optionally filtered by search pattern
  */
@@ -11,6 +12,11 @@ export interface RunListModelsOptions {
     cwd: string;
     /** CLI-supplied extension paths (e.g. from `-e <path>`). */
     additionalExtensionPaths?: string[];
+    /** In-process extension factories to load without filesystem discovery. */
+    extensionFactories?: Array<{
+        factory: ExtensionFactory;
+        name: string;
+    }>;
     /** Extension paths configured under `extensions:` in user settings. */
     settingsExtensions?: string[];
     /** Disabled extension ids from settings (`disabledExtensions`). */

package/dist/types/commands/gc.d.ts

@@ -0,0 +1,26 @@
+import { Command } from "@gajae-code/utils/cli";
+export default class Gc extends Command {
+    static description: string;
+    static strict: boolean;
+    static flags: {
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+        prune: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        "dry-run": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/types/config/file-lock-gc.d.ts

@@ -0,0 +1,5 @@
+/**
+ * GC adapter for config file-locks (`<file>.lock` dirs holding `{pid, timestamp}`).
+ */
+import type { GcStoreAdapter } from "../gjc-runtime/gc-runtime";
+export declare const fileLocksGcAdapter: GcStoreAdapter;

package/dist/types/config/file-lock.d.ts

@@ -3,4 +3,11 @@ export interface FileLockOptions {
     retries?: number;
     retryDelayMs?: number;
 }
+/** @internal */
+export declare function readFileLockInfoForGc(lockDir: string): Promise<{
+    pid: number;
+    timestamp: number;
+} | null>;
+/** @internal */
+export declare function removeFileLockDirForGc(lockDir: string): Promise<void>;
 export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/types/coordinator/contract.d.ts

@@ -1,4 +1,4 @@
 export declare const COORDINATOR_MCP_PROTOCOL_VERSION = "2024-11-05";
 export declare const COORDINATOR_MCP_SERVER_NAME = "gjc-coordinator-mcp";
-export declare const COORDINATOR_MCP_TOOL_NAMES: readonly ["gjc_coordinator_list_sessions", "gjc_coordinator_read_status", "gjc_coordinator_read_tail", "gjc_coordinator_list_questions", "gjc_coordinator_list_artifacts", "gjc_coordinator_read_artifact", "gjc_coordinator_read_coordination_status", "gjc_coordinator_register_session", "gjc_coordinator_start_session", "gjc_coordinator_send_prompt", "gjc_coordinator_submit_question_answer", "gjc_coordinator_read_turn", "gjc_coordinator_await_turn", "gjc_coordinator_report_status"];
+export declare const COORDINATOR_MCP_TOOL_NAMES: readonly ["gjc_coordinator_list_sessions", "gjc_coordinator_read_status", "gjc_coordinator_read_tail", "gjc_coordinator_list_questions", "gjc_coordinator_list_artifacts", "gjc_coordinator_read_artifact", "gjc_coordinator_read_coordination_status", "gjc_coordinator_watch_events", "gjc_coordinator_register_session", "gjc_coordinator_start_session", "gjc_coordinator_send_prompt", "gjc_coordinator_submit_question_answer", "gjc_coordinator_read_turn", "gjc_coordinator_await_turn", "gjc_coordinator_report_status"];
 export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/dist/types/defaults/gjc/extensions/grok-build/index.d.ts

@@ -0,0 +1 @@
+export { default } from "../grok-cli-vendor/src/index.js";

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/index.d.ts

@@ -0,0 +1 @@
+export { default } from './provider/register.js';

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/models/catalog.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Model definitions for Grok CLI's API.
+ */
+export interface GrokCliModelConfig {
+    id: string;
+    name: string;
+    reasoning: boolean;
+    input: ('text' | 'image')[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    /** Models that don't support reasoning.effort get a thinkingLevelMap. */
+    thinkingLevelMap?: Record<string, string | null>;
+}
+export declare function supportsReasoningEffort(modelId: string): boolean;
+/**
+ * Resolve the active model list. If `GJC_GROK_CLI_MODELS` is set,
+ * it filters/reorders the fallback list; unknown IDs get sensible defaults.
+ */
+export declare function resolveModels(): GrokCliModelConfig[];

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/payload/sanitize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Payload sanitization for xAI's Responses API via cli-chat-proxy.grok.com.
+ *
+ * xAI's endpoint has quirks compared to stock OpenAI:
+ *   - Replayed or encrypted `reasoning` items in input cause 400 errors.
+ *   - `reasoning.effort` is only supported on a subset of models.
+ *   - Empty-string content items cause validation failures.
+ *   - `function_call_output.output` cannot contain image arrays.
+ *   - `image_url` parts must be normalized to `input_image` with data URIs.
+ *   - Local image paths must be resolved to base64 data URIs.
+ *   - xAI rejects `role: "developer"` and `role: "system"` in the input
+ *     array; these must be moved to top-level `instructions`.
+ *   - xAI uses `text.format` instead of OpenAI's `response_format`.
+ *   - xAI uses `prompt_cache_key` for conversation caching.
+ *   - xAI doesn't support `prompt_cache_retention`.
+ *
+ * Additional Grok CLI-specific behavior:
+ *   - Adds x-grok-* headers for client identification
+ *   - Uses prompt_cache_key for session affinity
+ */
+/**
+ * Sanitize a provider request payload for xAI's Responses API via
+ * cli-chat-proxy.grok.com.
+ *
+ * Returns the modified payload.  Mutates the input in place for efficiency.
+ */
+export declare function sanitizePayload(params: Record<string, unknown>, modelId: string, sessionId: string | undefined, cwd: string): Record<string, unknown>;

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/provider/billing.d.ts

@@ -0,0 +1,8 @@
+interface BillingUsage {
+    monthlyLimit: number;
+    used: number;
+    billingPeriodEnd: string;
+}
+export declare function fetchBillingUsage(token: string): Promise<BillingUsage>;
+export declare function formatQuota(usage: BillingUsage | undefined): string[];
+export {};

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/provider/register.d.ts

@@ -0,0 +1,5 @@
+/**
+ * GJC Grok Build provider — SuperGrok OAuth + cli-chat-proxy models.
+ */
+import type { ExtensionAPI } from '@gajae-code/coding-agent';
+export default function registerGrokCli(api: ExtensionAPI): void;

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/provider/stream.d.ts

@@ -0,0 +1,10 @@
+import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from '@gajae-code/ai';
+/**
+ * Stream function that adds Grok CLI-specific headers to requests.
+ *
+ * GJC Grok Build extension sends cli-chat-proxy headers (see agent.models.grok-cli.yml):
+ *   - x-grok-conv-id: <session/conversation ID>
+ *   - x-grok-model-override: <model ID>
+ *   - x-xai-token-auth: xai-grok-cli
+ */
+export declare function streamGrokCli(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/provider/usage.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@gajae-code/coding-agent';
+export declare function registerUsageCommand(api: Pick<ExtensionAPI, 'registerCommand'>): void;

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/shared/base-url.d.ts

@@ -0,0 +1,2 @@
+export declare function getBaseUrl(): string;
+export declare function isGrokBuildBaseUrlOverrideIgnored(): boolean;

package/dist/types/defaults/gjc/extensions/grok-cli-vendor/src/shared/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed error for xAI OAuth failures.
+ *
+ * Codes allow the login flow and stream handlers to distinguish
+ * retryable failures (network) from fatal ones (revoked refresh token).
+ */
+export declare class XaiOAuthError extends Error {
+    readonly code: string;
+    readonly reloginRequired: boolean;
+    constructor(message: string, code: string, reloginRequired?: boolean);
+}
+/** Well-known error codes. */
+export declare const XaiErrorCode: {
+    /** OIDC discovery failed (network, invalid response). */
+    readonly DISCOVERY_FAILED: 'discovery_failed';
+    /** Discovery endpoint returned a non-xAI origin. */
+    readonly DISCOVERY_INVALID_ORIGIN: 'discovery_invalid_origin';
+    /** Authorization was denied or errored in the browser. */
+    readonly AUTHORIZATION_FAILED: 'authorization_failed';
+    /** CSRF state mismatch between request and callback. */
+    readonly STATE_MISMATCH: 'state_mismatch';
+    /** Callback did not include an authorization code. */
+    readonly CODE_MISSING: 'code_missing';
+    /** Token exchange failed (network, invalid response). */
+    readonly TOKEN_EXCHANGE_FAILED: 'token_exchange_failed';
+    /** Token exchange returned an invalid payload. */
+    readonly TOKEN_EXCHANGE_INVALID: 'token_exchange_invalid';
+    /** Refresh token is missing or empty. */
+    readonly REFRESH_MISSING: 'refresh_missing';
+    /** Token refresh failed (expired, revoked). */
+    readonly REFRESH_FAILED: 'refresh_failed';
+    /** No credentials stored. */
+    readonly AUTH_MISSING: 'auth_missing';
+    /** Loopback callback server could not bind. */
+    readonly CALLBACK_BIND_FAILED: 'callback_bind_failed';
+    /** Loopback callback timed out. */
+    readonly CALLBACK_TIMEOUT: 'callback_timeout';
+};

package/dist/types/defaults/gjc-grok-cli.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionFactory } from "../extensibility/extensions/types";
+export declare const BUNDLED_GROK_BUILD_EXTENSION_ID = "bundled:grok-build";
+export declare function getBundledGrokBuildExtensionFactory(): ExtensionFactory;
+export declare function getBundledGrokCliModelDefaults(): string;
+export declare function assertBundledGrokCliDefaults(): Promise<void>;

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

@@ -3,6 +3,7 @@
  */
 export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from "../slash-commands";
 export { discoverAndLoadExtensions, ExtensionRuntimeNotInitializedError, loadExtensionFromFactory, loadExtensions, } from "./loader";
+export * from "./prefix-command-bridge";
 export * from "./runner";
 export * from "./types";
 export * from "./wrapper";

package/dist/types/extensibility/extensions/prefix-command-bridge.d.ts

@@ -0,0 +1,35 @@
+import { type ExecResult } from "../../exec/exec";
+import type { ExtensionContext, InputEvent, InputEventResult } from "./types";
+export declare const OOO_BRIDGE_RECURSION_ENV = "_OUROBOROS_GJC_BRIDGE_DEPTH";
+export declare const OOO_BRIDGE_CONTINUE_EXIT_CODE = 78;
+export declare const OOO_BRIDGE_TIMEOUT_ENV = "OUROBOROS_GJC_BRIDGE_TIMEOUT_MS";
+export interface ExactPrefixCommandBridgeOptions {
+    /** Bare command prefix to intercept, without trailing whitespace. */
+    prefix: string;
+    /** Command executable to run when the prefix matches. */
+    command: string;
+    /** Arguments inserted before the intercepted input text. */
+    args?: string[];
+    /** Environment variable used as the recursion-depth guard. */
+    recursionEnv?: string;
+    /** Exit code that maps to extension pass-through instead of handled input. */
+    continueExitCode?: number;
+    /** Optional dispatch timeout in milliseconds. */
+    timeout?: number;
+    /** Dispatch implementation. Defaults to the shared command executor in the extension context cwd. */
+    dispatch?: (command: string, args: string[], ctx: ExtensionContext, options: {
+        timeout?: number;
+    }) => Promise<ExecResult>;
+}
+/**
+ * Build an extension `input` handler for an exact-prefix command bridge.
+ *
+ * Matching input is passed to `command` as `args + [event.text]`. A zero exit code
+ * handles the input, `continueExitCode` returns pass-through, and any other
+ * non-zero exit code surfaces an error and handles the input so the failed
+ * command is not forwarded to the model. The recursion
+ * guard prevents extension-originated or nested dispatch from re-entering the
+ * bridge while the child command runs.
+ */
+export declare function createExactPrefixCommandBridge(options: ExactPrefixCommandBridgeOptions): (event: InputEvent, ctx: ExtensionContext) => Promise<InputEventResult>;
+export declare function createOuroborosOooBridge(): (event: InputEvent, ctx: ExtensionContext) => Promise<InputEventResult>;

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

@@ -0,0 +1,103 @@
+import { type DeepInterviewEstablishedFact, type DeepInterviewRoundRecord, type DeepInterviewStateEnvelope, type DeepInterviewTriggerMetadata } from "./deep-interview-state";
+export * from "./deep-interview-state";
+/**
+ * Runtime-owned deep-interview round recorder (conflict-aware scoring support).
+ *
+ * Ownership boundary (per the approved consensus plan): this module owns durable
+ * round-record semantics — stable identity, append-or-merge, lifecycle, compact
+ * reads, replay detection, and the pure scored-transition validator. Callers such
+ * as the `ask` tool only resolve an answer and invoke these helpers; they never
+ * compute state paths, merge records, or write `.gjc` files directly. All writes
+ * go through the sanctioned state-writer (`writeWorkflowEnvelopeAtomic`).
+ */
+export interface DeepInterviewAnswerInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    questionText: string;
+    component?: string;
+    dimension?: string;
+    ambiguity?: number;
+    selectedOptions?: string[];
+    customInput?: string;
+}
+export interface DeepInterviewScoringInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    scores: Record<string, number>;
+    ambiguity: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export type AppendOrMergeAction = "created" | "noop" | "replaced";
+export interface AppendOrMergeResult {
+    rounds: DeepInterviewRoundRecord[];
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}
+export interface DeepInterviewCompactState {
+    threshold?: number;
+    threshold_source?: string;
+    current_ambiguity?: number;
+    topology_summary?: {
+        active: number;
+        deferred: number;
+        components: string[];
+    };
+    established_facts: DeepInterviewEstablishedFact[];
+    unresolved_triggers: DeepInterviewTriggerMetadata[];
+    recent_scored_rounds: DeepInterviewRoundRecord[];
+    pending_shells: DeepInterviewRoundRecord[];
+}
+export interface TransitionValidationResult {
+    ok: boolean;
+    violations: string[];
+}
+export declare function buildAnswerShell(input: DeepInterviewAnswerInput, now?: string): DeepInterviewRoundRecord;
+/**
+ * Append-or-merge by `round_key`. Exactly one record per key:
+ * - no existing record -> append (`created`);
+ * - identical question_hash + answer_hash -> deterministic no-op (`noop`);
+ * - same key, different hashes -> deterministic replacement of the prior shell
+ *   (`replaced`); the prior answer for that key is superseded and lifecycle resets.
+ */
+export declare function appendOrMergeRound(rounds: readonly DeepInterviewRoundRecord[], shell: DeepInterviewRoundRecord): AppendOrMergeResult;
+/**
+ * Merge scoring output into the existing record for the derived key, transitioning
+ * it to `scored`. Never appends a second record for the same key; if no shell exists
+ * yet (scoring without a prior ask), a scored record is created so data is not lost.
+ */
+export declare function enrichRoundWithScoring(rounds: readonly DeepInterviewRoundRecord[], input: DeepInterviewScoringInput, now?: string): {
+    rounds: DeepInterviewRoundRecord[];
+    record: DeepInterviewRoundRecord;
+};
+/**
+ * Bidirectional invariant: if `next` carries an `active` trigger, the affected
+ * dimension must not improve and overall ambiguity must rise vs the prior scored
+ * round. `disputed`/`unresolved` triggers are exempt but must carry a rationale.
+ */
+export declare function validateDeepInterviewScoredTransition(prior: DeepInterviewRoundRecord | undefined, next: DeepInterviewRoundRecord): TransitionValidationResult;
+/** Back-compat wrapper: normalize a deep-interview envelope to its canonical nested shape. */
+export declare function ensureDeepInterviewStateShape(value: unknown): DeepInterviewStateEnvelope;
+export declare function projectCompactState(value: unknown, options?: {
+    lastN?: number;
+}): DeepInterviewCompactState;
+/** Record an `answered` shell for one round (append-or-merge by durable key). */
+export declare function appendOrMergeDeepInterviewRound(cwd: string, statePath: string, input: DeepInterviewAnswerInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}>;
+/** Merge scoring output into the same round record, transitioning to `scored`. */
+export declare function enrichDeepInterviewRoundScoring(cwd: string, statePath: string, input: DeepInterviewScoringInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    record: DeepInterviewRoundRecord;
+}>;
+/** Compact projection so callers read a slice instead of the full transcript. */
+export declare function readDeepInterviewStateCompact(statePath: string, options?: {
+    lastN?: number;
+}): Promise<DeepInterviewCompactState>;

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

@@ -1,3 +1,4 @@
+export * from "./deep-interview-recorder";
 /**
  * Native implementation of `gjc deep-interview`.
  *
@@ -12,6 +13,7 @@ export interface DeepInterviewCommandResult {
     stdout?: string;
     stderr?: string;
 }
+export declare function deepInterviewStatePath(cwd: string, sessionId: string | undefined): string;
 export interface ResolvedDeepInterviewSpecWriteArgs {
     stage: "final";
     slug: string;

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

@@ -0,0 +1,112 @@
+/**
+ * Pure, dependency-free foundation for deep-interview state shape.
+ *
+ * Ownership boundary (per the approved consensus plan): this leaf module owns the
+ * canonical persisted shape (interview data nested under `state`), durable round
+ * identity/hashing, lossless legacy normalization, and the deep-interview-specific
+ * envelope/round merge used by every writer (`deep-interview-recorder`,
+ * `state-runtime` write/reconcile, seed, and handoff). It MUST NOT import the
+ * active-state, state-writer, CLI runtime, or filesystem so it stays cycle-free and
+ * trivially testable.
+ */
+export type DeepInterviewRoundLifecycle = "answered" | "pending_scoring" | "scored";
+export type DeepInterviewTriggerKind = "A" | "B" | "C" | "D";
+/** `active` triggers must satisfy the bidirectional invariant; disputed/unresolved are exempt with rationale. */
+export type DeepInterviewTriggerStatus = "active" | "disputed" | "unresolved";
+export interface DeepInterviewEstablishedFact {
+    id: string;
+    statement: string;
+    round: number;
+    component?: string;
+    dimension?: string;
+    evidence?: string;
+    disputed: boolean;
+}
+export interface DeepInterviewTriggerMetadata {
+    kind: DeepInterviewTriggerKind;
+    name: string;
+    status: DeepInterviewTriggerStatus;
+    component: string;
+    dimension: string;
+    priorDimensionScore?: number;
+    newDimensionScore?: number;
+    priorAmbiguity?: number;
+    newAmbiguity?: number;
+    evidence?: string;
+    contradictedFactId?: string;
+    /** Required when status is `disputed` or `unresolved` to exempt the invariant. */
+    rationale?: string;
+}
+export interface DeepInterviewRoundRecord {
+    round_key: string;
+    round_id?: string;
+    round: number;
+    question_id?: string;
+    question_text?: string;
+    question_hash: string;
+    answer_hash: string;
+    selected_options?: string[];
+    custom_input?: string;
+    component?: string;
+    dimension?: string;
+    ambiguity_at_ask?: number;
+    lifecycle: DeepInterviewRoundLifecycle;
+    answered_at: string;
+    scored_at?: string;
+    scores?: Record<string, number>;
+    ambiguity?: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export interface DeepInterviewStateEnvelope {
+    threshold?: number;
+    threshold_source?: string;
+    state?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function hashContent(value: string): string;
+export declare function questionHash(questionText: string): string;
+export declare function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string;
+/**
+ * Durable round identity. Prefer `interview_id + round_id`; fall back to
+ * `interview_id + round + question.id` when no caller-supplied `round_id` exists.
+ */
+export declare function deriveRoundKey(interviewId: string | undefined, input: {
+    round_id?: string;
+    round: number;
+    questionId?: string;
+}): string;
+/**
+ * Canonicalize a deep-interview envelope: interview data nested under `state`,
+ * legacy flattened fields hoisted in losslessly, transcript duplicates removed
+ * from the top level, and `rounds`/`established_facts` guaranteed to be arrays.
+ *
+ * Idempotent: a canonical envelope is returned unchanged in shape. Never deletes
+ * unknown envelope or nested fields, and never mutates the input.
+ */
+export declare function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewStateEnvelope;
+/**
+ * Lossless, idempotent merge of two round arrays.
+ *
+ * - Records sharing a durable key (`round_key`, or synthesized from
+ *   `round_id`/`question_id`) merge into one, preferring scored over answered.
+ * - Records without any durable identity are preserved verbatim; an exact
+ *   duplicate is skipped so repeated writes stay idempotent, but distinct records
+ *   are never collapsed.
+ *
+ * Deliberate refinement of the approved plan: rather than mutating opaque legacy
+ * records with synthetic `legacy:<index>` keys, they are preserved verbatim with
+ * exact-duplicate dedupe. This satisfies the plan's intent (lossless, idempotent,
+ * never collapse distinct rounds) without rewriting user-supplied round objects,
+ * and keeps free-form extension preservation intact. Recorder-produced records
+ * always carry a `round_key`, so the synthetic path is unnecessary in practice.
+ */
+export declare function mergeDeepInterviewRounds(existing: readonly Record<string, unknown>[], incoming: readonly Record<string, unknown>[]): Record<string, unknown>[];
+/**
+ * Deep-interview-specific envelope merge. Unlike the generic shallow null-delete
+ * merge, this keeps interview data nested under `state`, never deletes `state`,
+ * and merges `rounds` losslessly by durable key so a partial write (e.g. a
+ * scoring update) cannot drop recorder-written transcript history.
+ */
+export declare function mergeDeepInterviewEnvelope(existing: unknown, incoming: unknown, options?: {
+    replace?: boolean;
+}): DeepInterviewStateEnvelope;

package/dist/types/gjc-runtime/gc-render.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Text rendering for `gjc gc` reports. JSON output is produced directly in
+ * `gc-runtime.ts`; this module owns the human-readable grouped report.
+ */
+import type { GcReport } from "./gc-runtime";
+export declare function buildGcReportText(report: GcReport): string;