@gajae-code/coding-agent 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [0.4.5] - 2026-06-12
+
+### Added
+
+- Added a dim `(ctrl+s to observe sessions)` discoverability hint under the `subagent` await panel header while any awaited subagent is still running, pointing to the full session observer overlay; the hint shows in both collapsed and expanded states and disappears once no subagent is running.
+- Added a `phase-rollup` receipt family (receipt-of-receipts) to the harness control plane: a hash-sealed rollup that supersedes N child task receipts at a lifecycle boundary, preserving per-child `{id, status, outputUri, outputSha256, receiptSha256, tokens, costTotal, clonedTokens, lowRoi}` pointers plus aggregate ROI totals, with a pure deterministic builder (`buildPhaseRollupReceipt`) and fail-closed semantic validation.
+- Added a pure receipt-ingestion fast path (`ingestReceipts`): fail-closed batch validation + lifecycle transition computation via the existing state machine, plus a deterministic model-facing digest hard-capped at 280 chars — groundwork for LLM-free receipt routing.
+- Added advisory spawn-ROI reconciliation (`reconcileSpawnRoi`) and deterministic fork-context mode advice (`adviseForkContextMode`) surfaced in task receipts without changing task success semantics.
+- Added the Grok Build provider contract design document.
+
+### Changed
+
+- Reduced compiled CLI startup and native bundle pressure with default-small grammar loading, tokenizer tiering, and compiled fast-help paths.
+- Preserved dev/main release metadata and changelog consistency for the 0.4.5 lockstep release.
+
+### Fixed
+
+- Kept the unified `goal` tool registered and active by default whenever `goal.enabled` is true, including explicit tool subsets and `gjc ultragoal create-goals` arming flows.
+- Restored no-argument `gjc` interactive startup instead of launching help.
+- Rendered and executed Cursor-native tool calls, including detached/native handler paths and empty-pattern composer grep guards.
+- Tool-output pruning no longer rewrites already-sent provider-facing history mid prompt-cache epoch and now persists pruned message updates back into canonical session storage.
+- Preserved provider abort root causes in the final TUI abort label, kept replay rendering idempotent, and added a `PI_STREAM_IDLE_TIMEOUT_MS` remediation hint when stream idle watchdogs fire.
+- Hardened harness owner recovery/finalize paths and submit-prompt-file handling.
+
+## [0.4.4] - 2026-06-10
+
+### Added
+
+- Made coordinator turns event-backed, adding an MCP coordinator server and the `gjc coordinator` / `gjc mcp-serve` commands backed by durable turn/session state (#479).
+- Surfaced awaited sub-agent live streaming status in the await panel (#475).
+
+### Changed
+
+- Refreshed the README brand images (#477).
+
+### Fixed
+
+- Persisted ralplan role-agent artifacts via the CLI, returning receipt-only output to the caller (#474).
+- Collected the `ask` tool "Other" custom input inline below the option list (#476).
+
 ## [0.4.3] - 2026-06-10
 
 ### Added
@@ -17,9 +57,11 @@
 ### Changed
 
 - Added conservative `timeout-minutes` values to all CI workflow jobs to prevent indefinite hangs.
+- Made coordinator MCP turn waiting state-backed by durable turn/session files, with runtime session sidecar updates for running/completed/error states and Meeseeks guidance that avoids fixed sleep/capture-pane loops.
 
 ### Fixed
 
+- Failed stale coordinator turns quickly when their recorded tmux session is gone, clearing active-turn state instead of burning await timeouts.
 - Improved the grep limit-reached message to show the current limit value and suggest using `--limit` for more results.
 - Passed the active model's `maxTokens` (reserved completion budget) into the auto-compaction threshold and context-usage reserve so prompt packing reserves output for large-window models, keeping the safe input budget below the total context window (e.g. ~272K for a 400K/128K model) instead of filling the whole window ([#442](https://github.com/Yeachan-Heo/gajae-code/issues/442)).
 - Fixed a `gjc harness` recovery deadlock where a session created by `start` without `--detach` (persisted as `started` with no owner lease/endpoint) could never get a live owner: `recover` refused to spawn one because no prior endpoint existed, while `start` reported `session-already-exists`. `recover` now bootstraps a fresh owner for a never-started session (no lease, no endpoint, no owner-run evidence) without writing a misleading `vanish` receipt, reported via `bootstrappedOwner: true`. Bootstrap is independent of the vanish classifier's `ownerRequired` verdict (nothing has vanished), so a session started in a non-git workspace (git delta `unknown`) is recovered too, while a deleted worktree is still refused (#421).

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

@@ -1,4 +1,4 @@
-import type { AgentSource } from "../task/types";
+import type { AgentProgress, AgentSource } from "../task/types";
 export interface AsyncJob {
     id: string;
     type: "bash" | "task";
@@ -189,6 +189,24 @@ export declare class AsyncJobManager {
     registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void;
     getLiveHandle(subagentId: string): SubagentLiveHandle | undefined;
     removeLiveHandle(subagentId: string): void;
+    /**
+     * Retain the latest live `AgentProgress` for a subagent (deep-cloned so later
+     * mutation of the live object cannot corrupt retained state). Read by the
+     * `subagent` await panel; cleared on terminal/cancel/purge/dispose.
+     *
+     * Ignored for ids without a canonical `SubagentRecord` (e.g. foreground/inline
+     * task runs that share the executor path) so the map only holds detached
+     * subagent progress and never accumulates untracked foreground task state.
+     */
+    recordSubagentProgress(subagentId: string, progress: AgentProgress): void;
+    getSubagentProgress(subagentId: string): AgentProgress | undefined;
+    /**
+     * True only when a live, in-session progress producer exists for this id: a
+     * canonical registered record with a live handle or an in-memory running job.
+     * False for `SubagentTool` backward-compat job synthesis and resumed-from-disk
+     * records, which have no live producer to stream from.
+     */
+    hasLiveSubagent(subagentId: string, filter?: AsyncJobFilter): boolean;
     /** 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;

package/dist/types/cli/fast-help.d.ts

@@ -0,0 +1 @@
+export declare function getExtraHelpText(): string;

package/dist/types/cli/setup-cli.d.ts

@@ -1,4 +1,4 @@
-export type SetupComponent = "defaults" | "hooks" | "provider" | "python" | "stt";
+export type SetupComponent = "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
 export interface SetupCommandArgs {
     component: SetupComponent;
     flags: {
@@ -12,6 +12,21 @@ export interface SetupCommandArgs {
         apiKeyEnv?: string;
         model?: string[];
         modelsPath?: string;
+        smoke?: boolean;
+        install?: boolean;
+        root?: string[];
+        repo?: string;
+        profile?: string;
+        sessionCommand?: string;
+        noWorktree?: boolean;
+        worktreeName?: string;
+        stateRoot?: string;
+        mutation?: string[];
+        artifactByteCap?: string;
+        serverKey?: string;
+        gjcCommand?: string;
+        target?: string;
+        profileDir?: string;
     };
 }
 /**

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

@@ -0,0 +1,19 @@
+import { Command } from "@gajae-code/utils/cli";
+export default class Coordinator extends Command {
+    static description: string;
+    static strict: boolean;
+    static args: {
+        action: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+        };
+    };
+    static flags: {
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    run(): Promise<void>;
+}

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

@@ -14,6 +14,9 @@ export default class Harness extends Command {
             description: string;
             default: string;
         };
+        "prompt-file": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
         session: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             char: string;
             description: string;

package/dist/types/commands/mcp-serve.d.ts

@@ -0,0 +1,24 @@
+import { Command } from "@gajae-code/utils/cli";
+export declare function validateMcpServeSubcommandForTest(server: string | undefined): void;
+export default class McpServe extends Command {
+    static description: string;
+    static strict: boolean;
+    static args: {
+        server: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+        };
+    };
+    static flags: {
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+        check: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+    };
+    run(): Promise<void>;
+}

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

@@ -24,6 +24,53 @@ export default class Setup extends Command {
         json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
         };
+        smoke: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        install: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        root: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        repo: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        profile: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "session-command": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "no-worktree": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "worktree-name": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "state-root": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        mutation: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        "artifact-byte-cap": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "server-key": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "gjc-command": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        target: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "profile-dir": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
         preset: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

package/dist/types/config/model-registry.d.ts

@@ -70,6 +70,7 @@ export declare const ModelsConfigFile: ConfigFile<{
             allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
             requiresAssistantContentForToolCalls?: boolean | undefined;
             supportsToolChoice?: boolean | undefined;
+            supportsForcedToolChoice?: boolean | undefined;
             disableReasoningOnForcedToolChoice?: boolean | undefined;
             disableReasoningOnToolChoice?: boolean | undefined;
             thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
@@ -145,6 +146,7 @@ export declare const ModelsConfigFile: ConfigFile<{
                 allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
                 requiresAssistantContentForToolCalls?: boolean | undefined;
                 supportsToolChoice?: boolean | undefined;
+                supportsForcedToolChoice?: boolean | undefined;
                 disableReasoningOnForcedToolChoice?: boolean | undefined;
                 disableReasoningOnToolChoice?: boolean | undefined;
                 thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
@@ -216,6 +218,7 @@ export declare const ModelsConfigFile: ConfigFile<{
                 allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
                 requiresAssistantContentForToolCalls?: boolean | undefined;
                 supportsToolChoice?: boolean | undefined;
+                supportsForcedToolChoice?: boolean | undefined;
                 disableReasoningOnForcedToolChoice?: boolean | undefined;
                 disableReasoningOnToolChoice?: boolean | undefined;
                 thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;

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

@@ -30,6 +30,7 @@ export declare const OpenAICompatSchema: z.ZodObject<{
     allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
     requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
     supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+    supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
     disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
     disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
     thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -182,6 +183,7 @@ export declare const ModelOverrideSchema: z.ZodObject<{
         allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
         requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
         supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+        supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
         disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
         disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
         thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -288,6 +290,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
             allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
             requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
             supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+            supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
             disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
             disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
             thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -442,6 +445,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
                 allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+                supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
                 thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -575,6 +579,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
                 allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+                supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
                 thinkingFormat: z.ZodOptional<z.ZodEnum<{

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

@@ -0,0 +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 type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/dist/types/coordinator-mcp/policy.d.ts

@@ -0,0 +1,24 @@
+export type CoordinatorMutationClass = "sessions" | "questions" | "reports";
+export interface CoordinatorNamespace {
+    profile: string | null;
+    repo: string | null;
+}
+export interface CoordinatorMcpConfig {
+    allowedRoots: string[];
+    mutationClasses: Set<CoordinatorMutationClass>;
+    artifactByteCap: number;
+    namespace: CoordinatorNamespace;
+    stateRoot: string;
+    sessionCommand: string | null;
+}
+export interface CoordinatorMutationRequest {
+    allow_mutation?: boolean;
+}
+export declare function buildCoordinatorMcpConfig(env?: NodeJS.ProcessEnv): CoordinatorMcpConfig;
+export declare function assertCoordinatorWorkdir(config: CoordinatorMcpConfig, cwd: unknown): Promise<string>;
+export declare function assertCoordinatorArtifactPath(config: CoordinatorMcpConfig, artifactPath: unknown): Promise<{
+    path: string;
+    byteCap: number;
+}>;
+export declare function requireCoordinatorMutation(config: CoordinatorMcpConfig, mutationClass: CoordinatorMutationClass, request: CoordinatorMutationRequest): void;
+export declare function coordinatorNamespacePath(config: CoordinatorMcpConfig): string;

package/dist/types/coordinator-mcp/safety.d.ts

@@ -0,0 +1,26 @@
+import { type CoordinatorMutationClass } from "./policy";
+export declare const COORDINATOR_MUTATION_CLASSES: readonly ["sessions", "questions", "reports"];
+export type { CoordinatorMutationClass };
+export interface CoordinatorSafetyConfig {
+    allowedRoots: string[];
+    artifactMaxBytes: number;
+    enabledMutationClasses: Set<CoordinatorMutationClass>;
+    repo?: string;
+    profile?: string;
+}
+export interface CoordinatorSafetyPolicy {
+    config: CoordinatorSafetyConfig;
+    resolveWorkdir(input: unknown): Promise<string>;
+    resolveArtifactPath(input: unknown): Promise<string>;
+    assertMutationAllowed(mutationClass: CoordinatorMutationClass, args: Record<string, unknown>): {
+        ok: true;
+    } | CoordinatorFailure;
+}
+export interface CoordinatorFailure {
+    ok: false;
+    reason: string;
+    [key: string]: unknown;
+}
+export declare function createCoordinatorSafetyPolicy(options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<CoordinatorSafetyPolicy>;

package/dist/types/coordinator-mcp/server.d.ts

@@ -0,0 +1,58 @@
+import { COORDINATOR_MCP_PROTOCOL_VERSION, COORDINATOR_MCP_SERVER_NAME, COORDINATOR_MCP_TOOL_NAMES, type CoordinatorToolName } from "../coordinator/contract";
+import { type CoordinatorMcpConfig } from "./policy";
+export type { CoordinatorToolName };
+export { COORDINATOR_MCP_PROTOCOL_VERSION, COORDINATOR_MCP_SERVER_NAME, COORDINATOR_MCP_TOOL_NAMES };
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+type JsonRpcResult = any;
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: JsonRpcResult;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface SessionStartInput {
+    cwd: string;
+    prompt?: string;
+    namespace: {
+        profile: string | null;
+        repo: string | null;
+    };
+    worktree: true;
+}
+interface CoordinatorServices {
+    listSessions?: () => unknown[] | Promise<unknown[]>;
+    startSession?: (input: SessionStartInput) => unknown | Promise<unknown>;
+    commandRunner?: (command: string[]) => Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+interface CoordinatorMcpServerOptions {
+    env?: NodeJS.ProcessEnv;
+    services?: CoordinatorServices;
+}
+interface LegacyHandlerOptions {
+    env?: NodeJS.ProcessEnv;
+    createSession?: () => unknown;
+}
+export declare function readCoordinatorArtifact(config: CoordinatorMcpConfig, args: {
+    path: unknown;
+}): Promise<Record<string, unknown>>;
+export declare function createCoordinatorMcpServer(options?: CoordinatorMcpServerOptions): {
+    config: CoordinatorMcpConfig;
+    callTool: (name: string, args?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    handleJsonRpc: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
+    handle: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
+};
+export declare function handleCoordinatorMcpRequest(request: JsonRpcRequest, options?: LegacyHandlerOptions): Promise<JsonRpcResponse>;
+export declare function runCoordinatorMcpStdio(options?: CoordinatorMcpServerOptions): Promise<void>;

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

@@ -62,6 +62,19 @@ export interface ExtensionUIDialogOptions {
      * select-only rendering hint; non-TUI bridges drop it and do not serialize it.
      */
     scrollTitleRows?: number;
+    /**
+     * For interactive TUI select dialogs, handle the option with `optionLabel`
+     * inline: selecting it keeps the title and option list on screen and opens
+     * a free-text input below the list. Submitting calls `onSubmit` with the
+     * typed text and resolves the select with `optionLabel`; Escape returns to
+     * option selection. Non-TUI bridges (RPC, ACP) drop it; callers must keep
+     * a fallback path for selects that resolve `optionLabel` without invoking
+     * `onSubmit`.
+     */
+    customInput?: {
+        optionLabel: string;
+        onSubmit: (text: string) => void;
+    };
 }
 /** Raw terminal input listener for extensions. */
 export type TerminalInputHandler = (data: string) => {

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

@@ -0,0 +1,13 @@
+export declare const GJC_COORDINATOR_SESSION_STATE_FILE_ENV = "GJC_COORDINATOR_SESSION_STATE_FILE";
+export declare const GJC_COORDINATOR_SESSION_ID_ENV = "GJC_COORDINATOR_SESSION_ID";
+interface RuntimeStateEvent {
+    type: string;
+    messages?: unknown[];
+}
+interface RuntimeStateContext {
+    sessionId: string;
+    cwd: string;
+    sessionFile?: string | null;
+}
+export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext): Promise<void>;
+export {};

package/dist/types/harness-control-plane/finalize.d.ts

@@ -30,6 +30,11 @@ export interface FinalizeOptions {
     reviewOnly?: boolean;
     /** Operator/loop-supplied terminal review verdict (closed vocabulary). */
     verdict?: string | null;
+    /**
+     * Final assistant text from the live RPC owner, used to extract a closed-vocabulary verdict
+     * for review-only sessions when no explicit {@link verdict} is supplied. Never persisted raw.
+     */
+    assistantText?: string | null;
     /** Bounded PR/issue reference for the review target (e.g. "PR-414"). Never resolved from the live repo. */
     prTarget?: string | null;
     validationCommands?: ValidationCommandSpec[];

package/dist/types/harness-control-plane/phase-rollup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ *
+ * At a harness lifecycle boundary, N child task receipts can be superseded by a
+ * single `phase-rollup` receipt that preserves per-child pointers (id, status,
+ * outputRef, sha256) plus aggregate ROI totals. The rollup is hash-sealed via
+ * the standard receipt envelope and validated fail-closed like every other
+ * family (see `validatePhaseRollup` in receipts.ts). Pure builder — no runtime
+ * injection behavior is changed here.
+ */
+import type { TaskResultReceipt } from "../task/receipt";
+import { type BuildReceiptInput, type PhaseRollupEvidence, type ReceiptEnvelope } from "./receipts";
+export interface BuildPhaseRollupInput {
+    receiptId: string;
+    sessionId: string;
+    source: string;
+    subject: BuildReceiptInput<PhaseRollupEvidence>["subject"];
+    phase: string;
+    children: readonly TaskResultReceipt[];
+    /** Supply for deterministic output; defaults to now. */
+    createdAt?: string;
+}
+export declare function buildPhaseRollupReceipt(input: BuildPhaseRollupInput): ReceiptEnvelope<PhaseRollupEvidence>;

package/dist/types/harness-control-plane/receipt-ingest.d.ts

@@ -0,0 +1,19 @@
+import type { ReceiptEnvelope } from "./receipts";
+import type { HarnessLifecycle, ReceiptFamily, SessionState } from "./types";
+export declare const RECEIPT_DIGEST_MAX_CHARS = 280;
+export declare const RECEIPT_FAMILY_LIFECYCLE_TARGETS: Partial<Record<ReceiptFamily, HarnessLifecycle>>;
+export interface ReceiptIngestResult {
+    accepted: ReceiptEnvelope<unknown>[];
+    rejected: {
+        receipt: ReceiptEnvelope<unknown>;
+        reasons: string[];
+    }[];
+    transitions: {
+        from: HarnessLifecycle;
+        to: HarnessLifecycle;
+        receiptId: string;
+    }[];
+    finalLifecycle: HarnessLifecycle;
+    digest: string;
+}
+export declare function ingestReceipts(state: SessionState, receipts: readonly ReceiptEnvelope<unknown>[]): ReceiptIngestResult;

package/dist/types/harness-control-plane/receipts.d.ts

@@ -20,6 +20,8 @@ export interface ReceiptEnvelope<E = Record<string, unknown>> {
     sha256: string;
 }
 export declare const RECEIPT_SCHEMA_VERSION: 1;
+/** Deterministic stringify with sorted keys (stable hash basis). */
+export declare function canonicalJson(value: unknown): string;
 export declare function sha256Hex(input: string): string;
 export interface BuildReceiptInput<E> {
     receiptId: string;
@@ -90,6 +92,10 @@ export interface ReviewVerdictEvidence {
     finalizedAt: string;
     /** Bounded summary code/reference for the verdict; never raw assistant text. */
     summaryRef: string | null;
+    /** Where the verdict came from: explicit operator input or extracted from final assistant text. */
+    verdictSource?: "input" | "assistant";
+    /** sha256 of the assistant text the verdict was extracted from, when sourced from the agent. */
+    assistantDigest?: string | null;
 }
 export interface ReviewFailureEvidence {
     /** Machine-actionable reason the review produced no terminal verdict. */
@@ -98,6 +104,46 @@ export interface ReviewFailureEvidence {
     failedAt: string;
     /** Routing hint for the operator/fallback path. */
     fallback: string;
+    /** sha256 of the assistant text examined for a verdict, when one was available. */
+    assistantDigest?: string | null;
+    /** Bounded, whitespace-collapsed assistant summary (never an unbounded transcript dump). */
+    assistantSummary?: string | null;
 }
+/** Pointer back to one superseded child task receipt. */
+export interface PhaseRollupChildPointer {
+    id: string;
+    status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+    /** Artifact URI holding the child's full output, when available. */
+    outputUri: string | null;
+    /** Content hash of the child's output artifact, when available. */
+    outputSha256: string | null;
+    /** Hash of the child receipt itself (canonical JSON), for staleness checks. */
+    receiptSha256: string;
+    /**
+     * Per-child ROI accounting carried into the rollup so the aggregate totals
+     * below are recomputable/verifiable from child evidence (not self-reported).
+     * `tokens` is the child's effective token count; cost/cloned are null when
+     * the child reported no such accounting.
+     */
+    tokens: number;
+    costTotal: number | null;
+    clonedTokens: number | null;
+    lowRoi: boolean;
+}
+export interface PhaseRollupEvidence {
+    /** Harness lifecycle boundary this rollup was emitted at. */
+    phase: string;
+    children: PhaseRollupChildPointer[];
+    aggregate: {
+        childCount: number;
+        completed: number;
+        failed: number;
+        totalTokens: number;
+        totalCostTotal: number | null;
+        totalClonedTokens: number | null;
+        lowRoiChildIds: string[];
+    };
+}
+export declare function validatePhaseRollup(e: PhaseRollupEvidence): string[];
 /** Classifications that MUST have a valid `vanish` receipt before the action proceeds. */
 export declare function requiresVanishBeforeAction(classification: RecoveryClassification): boolean;

package/dist/types/harness-control-plane/rpc-adapter.d.ts

@@ -24,6 +24,8 @@ export interface HarnessRpc {
     isLive?(): boolean;
     /** ISO timestamp of the last observed event frame, or null. */
     lastFrameAt?(): string | null;
+    /** Final assistant text from the live session (for review-verdict extraction); null when unavailable. */
+    getLastAssistantText?(): Promise<string | null>;
 }
 export interface AcceptanceResult {
     accepted: boolean;
@@ -54,6 +56,7 @@ export declare class GajaeCodeRpc implements HarnessRpc {
     isLive(): boolean;
     lastFrameAt(): string | null;
     getState(): Promise<RpcStateSnapshot>;
+    getLastAssistantText(): Promise<string | null>;
     sendPrompt(prompt: string): Promise<{
         commandId: string;
         ack: boolean;

package/dist/types/harness-control-plane/types.d.ts

@@ -16,6 +16,14 @@ export type SessionMode = "implement" | "review";
 export type ReviewVerdict = "APPROVE_MERGE_READY" | "REQUEST_CHANGES" | "OWNER_CONFIRMATION_REQUIRED";
 export declare const REVIEW_VERDICTS: readonly ReviewVerdict[];
 export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;
+/**
+ * Extract a single closed-vocabulary review verdict from free-form assistant text.
+ *
+ * Scans for canonical verdict tokens (and accepted aliases) as whole words and returns the
+ * LAST occurrence — the agent's final stated decision wins over any earlier mention. Returns
+ * null when no allowed token is present, so the finalizer fails closed on a missing verdict.
+ */
+export declare function extractReviewVerdict(text: string | null | undefined): ReviewVerdict | null;
 /** Lifecycle states of an operated session. */
 export type HarnessLifecycle = "new" | "started" | "submitted" | "observing" | "recovering" | "validating" | "finalizing" | "completed" | "blocked" | "retired";
 /** Event severities emitted by the owner. */
@@ -27,7 +35,7 @@ export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "
 /** Deterministic recovery classifications. */
 export type RecoveryClassification = "continue" | "send-enter" | "reinject-prompt" | "restart-clean" | "restart-preserve-delta" | "fallback-codex-exec" | "human-check";
 /** Receipt families persisted under the session storage dir. */
-export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure";
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure" | "phase-rollup";
 /** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
 export type HarnessVerb = "start" | "submit" | "observe" | "classify" | "recover" | "validate" | "finalize" | "retire" | "events" | "monitor" | "operate";
 /** Submission transports. */

package/dist/types/main.d.ts

@@ -7,7 +7,7 @@
 import type { Args } from "./cli/args";
 import { ModelRegistry } from "./config/model-registry";
 import { Settings } from "./config/settings";
-import { InteractiveMode, runAcpMode } from "./modes";
+import type { InteractiveMode } from "./modes/interactive-mode";
 import type { SubmittedUserInput } from "./modes/types";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
@@ -51,7 +51,7 @@ export declare function createAcpSessionFactory(args: AcpSessionFactoryOptions):
 interface RunRootCommandDependencies {
     createAgentSession?: typeof createAgentSession;
     discoverAuthStorage?: typeof discoverAuthStorage;
-    runAcpMode?: typeof runAcpMode;
+    runAcpMode?: (createSession: AcpSessionFactory) => Promise<void>;
     settings?: Settings;
 }
 export declare function runRootCommand(parsed: Args, rawArgs: string[], deps?: RunRootCommandDependencies): Promise<void>;