@gajae-code/coding-agent 0.3.2 → 0.4.1

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

@@ -1,4 +1,8 @@
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+interface ResolveHarnessSessionRootOptions {
+    expectedWorkspace?: string;
+}
+export declare function canonicalWorkspacePath(workspace: string): string;
 export declare const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 export declare function controlSocketPath(root: string, sessionId: string, env?: NodeJS.ProcessEnv): string;
 export declare class StorageError extends Error {
@@ -27,6 +31,8 @@ export interface SessionPaths {
 }
 export declare function sessionPaths(root: string, sessionId: string): SessionPaths;
 export declare function readSessionState(root: string, sessionId: string): Promise<SessionState | null>;
+export declare function rememberHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function resolveHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv, options?: ResolveHarnessSessionRootOptions): Promise<string>;
 export declare function writeSessionState(root: string, state: SessionState): Promise<void>;
 export declare function sessionExists(root: string, sessionId: string): Promise<boolean>;
 /** Append a single severity envelope to events.jsonl. Single-writer discipline is the owner's job (M3). */
@@ -51,3 +57,4 @@ export declare function writeReceiptImmutable(root: string, sessionId: string, f
     createdAt: string;
 }): Promise<ReceiptIndexEntry>;
 export declare function readReceiptIndex(root: string, sessionId: string, family?: ReceiptFamily): Promise<ReceiptIndexEntry[]>;
+export {};

package/dist/types/lsp/client.d.ts

@@ -4,6 +4,7 @@ import type { LspClient, ServerConfig } from "./types";
  * @param ms - Timeout in milliseconds, or null/undefined to disable
  */
 export declare function setIdleTimeout(ms: number | null | undefined): void;
+export declare function isIdleCheckerActiveForTests(): boolean;
 /** Timeout for warmup initialize requests (5 seconds) */
 export declare const WARMUP_TIMEOUT_MS = 5000;
 /**

package/dist/types/modes/bridge/bridge-mode.d.ts

@@ -7,6 +7,7 @@ import { RpcHostUriBridge } from "../shared/agent-wire/host-uri-bridge";
 import { type BridgeCommandScope } from "../shared/agent-wire/scopes";
 import { UiRequestBroker } from "../shared/agent-wire/ui-request-broker";
 import type { BridgeUiResult } from "../shared/agent-wire/ui-result";
+import { UnattendedSessionControlPlane } from "../shared/agent-wire/unattended-session";
 import { type BridgePermissionRequestPayload } from "./bridge-client-bridge";
 import { type BridgeUiRequestPayload } from "./bridge-ui-context";
 import { BridgeEventStream } from "./event-stream";
@@ -30,6 +31,7 @@ interface BridgeFetchHandlerOptions {
     hostToolBridge?: RpcHostToolBridge;
     hostUriBridge?: RpcHostUriBridge;
     endpointMatrix?: Partial<BridgeEndpointMatrix>;
+    unattendedControlPlane?: UnattendedSessionControlPlane;
 }
 interface BridgeIdempotencyRecord {
     route: string;

package/dist/types/modes/prompt-action-autocomplete.d.ts

@@ -1,5 +1,5 @@
-import { type AutocompleteItem, type AutocompleteProvider, type SlashCommand } from "@gajae-code/tui";
-import { type KeybindingsManager } from "../config/keybindings";
+import type { AutocompleteItem, AutocompleteProvider, SlashCommand } from "@gajae-code/tui";
+import type { KeybindingsManager } from "../config/keybindings";
 interface PromptActionDefinition {
     id: string;
     label: string;

package/dist/types/modes/rpc/rpc-client.d.ts

@@ -8,7 +8,7 @@ import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type { ImageContent, Model } from "@gajae-code/ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { SessionStats } from "../../session/agent-session";
-import type { RpcHandoffResult, RpcHostToolDefinition, RpcSessionState } from "./rpc-types";
+import type { RpcExtensionUIRequest, RpcHandoffResult, RpcHostToolDefinition, RpcSessionState, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGate, RpcWorkflowGateResolution } from "./rpc-types";
 export interface RpcClientOptions {
     /** Path to the CLI entry point (default: searches for dist/cli.js) */
     cliPath?: string;
@@ -60,6 +60,24 @@ export declare class RpcClient {
      * Subscribe to agent events.
      */
     onEvent(listener: RpcEventListener): () => void;
+    /**
+     * Subscribe to workflow lifecycle gates emitted by RPC mode.
+     */
+    onWorkflowGate(listener: (gate: RpcWorkflowGate) => void): () => void;
+    /**
+     * Answer a workflow lifecycle gate and wait for the server resolution envelope.
+     */
+    respondGate(gateId: string, answer: unknown, idempotencyKey?: string): Promise<RpcWorkflowGateResolution>;
+    /**
+     * Subscribe to extension UI requests emitted by the server (e.g. select /
+     * input / editor / confirm). Returns an unsubscribe function.
+     */
+    onExtensionUiRequest(listener: (req: RpcExtensionUIRequest) => void): () => void;
+    /**
+     * Enter unattended mode by declaring budget + scopes + action allowlist.
+     * Returns the accepted declaration, or rejects (fail-closed) on refusal.
+     */
+    negotiateUnattended(declaration: RpcUnattendedDeclaration): Promise<RpcUnattendedAccepted>;
     /**
      * Get collected stderr output (useful for debugging).
      */

package/dist/types/modes/rpc/rpc-types.d.ts

@@ -145,7 +145,14 @@ export type RpcCommand = {
     id?: string;
     type: "login";
     providerId: string;
-};
+} | {
+    id?: string;
+    type: "negotiate_unattended";
+    declaration: RpcUnattendedDeclaration;
+} | ({
+    id?: string;
+    type: "workflow_gate_response";
+} & RpcWorkflowGateResponse);
 export interface RpcSessionState {
     model?: Model;
     thinkingLevel: ThinkingLevel | undefined;
@@ -411,12 +418,24 @@ export type RpcResponse = {
     data: {
         providerId: string;
     };
+} | {
+    id?: string;
+    type: "response";
+    command: "negotiate_unattended";
+    success: true;
+    data: RpcUnattendedAccepted;
+} | {
+    id?: string;
+    type: "response";
+    command: "workflow_gate_response";
+    success: true;
+    data: RpcWorkflowGateResolution;
 } | {
     id?: string;
     type: "response";
     command: string;
     success: false;
-    error: string;
+    error: string | object;
 };
 /** Emitted when an extension needs user input */
 export type RpcExtensionUIRequest = {
@@ -584,3 +603,161 @@ export type RpcExtensionUIResponse = {
     timedOut?: boolean;
 };
 export type RpcCommandType = RpcCommand["type"];
+/**
+ * Lifecycle stages that emit machine-addressable gates. v1 is single-agent;
+ * `team` parallel execution over RPC is deferred, so it is intentionally absent
+ * from this union. Gate construction rejects any other stage value.
+ */
+export type RpcWorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export declare const RESERVED_WORKFLOW_STAGES: readonly string[];
+export type RpcWorkflowGateKind = "question" | "approval" | "execution";
+/**
+ * The documented JSON Schema 2020-12 subset supported by the gate validator.
+ * Schemas containing any keyword outside this shape are rejected at gate
+ * construction time so the server never advertises a schema it cannot validate.
+ */
+export interface RpcJsonSchema {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, RpcJsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | RpcJsonSchema;
+    items?: RpcJsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+    oneOf?: RpcJsonSchema[];
+    anyOf?: RpcJsonSchema[];
+}
+export interface RpcWorkflowGateOption {
+    value: unknown;
+    label: string;
+    description?: string;
+}
+export interface RpcWorkflowGateContext {
+    title?: string;
+    prompt?: string;
+    summary?: string;
+    stage_state?: Record<string, unknown>;
+    artifact_refs?: Array<{
+        kind: string;
+        path?: string;
+        sha256?: string;
+    }>;
+    language?: string;
+}
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface RpcWorkflowGate {
+    type: "workflow_gate";
+    /** Run-scoped, monotonic, stable id (e.g. `wg_<run>_<stage>_000001`). */
+    gate_id: string;
+    stage: RpcWorkflowStage;
+    kind: RpcWorkflowGateKind;
+    schema: RpcJsonSchema;
+    /** Canonical hash of `schema`; advertised hash must equal server validation hash. */
+    schema_hash: string;
+    options?: RpcWorkflowGateOption[];
+    context: RpcWorkflowGateContext;
+    created_at: string;
+    required: true;
+}
+/** Inbound: the agent's answer to a workflow gate. */
+export interface RpcWorkflowGateResponse {
+    gate_id: string;
+    answer: unknown;
+    /** Optional idempotency key; same key + body returns the cached resolution. */
+    idempotency_key?: string;
+}
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface RpcWorkflowGateResolution {
+    gate_id: string;
+    status: "accepted" | "rejected";
+    answer_hash: string;
+    resolved_at: string;
+    /** Present only when `status === "rejected"`. */
+    error?: RpcWorkflowGateValidationError;
+}
+/** Typed error shape for schema validation failures (#315 acceptance). */
+export interface RpcWorkflowGateValidationError {
+    code: "invalid_workflow_gate_answer";
+    gate_id: string;
+    schema_hash: string;
+    errors: Array<{
+        path: string;
+        keyword: string;
+        message: string;
+        expected?: unknown;
+    }>;
+}
+export interface RpcUnattendedBudget {
+    max_tokens: number;
+    max_tool_calls: number;
+    max_wall_time_ms: number;
+    max_cost_usd: number;
+}
+export interface RpcUnattendedDeclaration {
+    /** Identity of the operating external agent, recorded in the audit trail. */
+    actor: string;
+    budget: RpcUnattendedBudget;
+    /** Coarse command scopes the agent may use (maps to BridgeCommandScope). */
+    scopes: string[];
+    /** Action classes the agent is allowed to perform (default-deny otherwise). */
+    action_allowlist: string[];
+}
+export interface RpcUnattendedAccepted {
+    run_id: string;
+    actor: string;
+    budget: RpcUnattendedBudget;
+    scopes: string[];
+    action_allowlist: string[];
+    accepted_at: string;
+}
+export type RpcBudgetMetric = "tokens" | "tool_calls" | "wall_time" | "cost";
+/** Typed payload emitted when a declared budget cap is breached (#318). */
+export interface RpcBudgetExceeded {
+    code: "budget_exceeded";
+    metric: RpcBudgetMetric;
+    limit: number;
+    observed: number;
+    /** The accounting phase that detected the breach. */
+    phase: string;
+    run_id: string;
+    session_id?: string;
+    /** `aborting` = breach detected, async abort initiated; settled status follows in audit. */
+    abort_status: "aborting" | "aborted" | "abort_failed";
+}
+export type RpcUnattendedRefusalCode = "unattended_not_negotiated" | "incomplete_budget" | "unsupported_budget_metric" | "invalid_unattended_declaration" | "unattended_aborted";
+/** Typed refusal emitted when unattended mode cannot start or continue (fail-closed). */
+export interface RpcUnattendedRefused {
+    code: RpcUnattendedRefusalCode;
+    message: string;
+}
+/** v1 action taxonomy: every authorized operation maps to one of these classes. */
+export type RpcUnattendedActionClass = "command.prompt" | "command.control" | "command.bash" | "command.export" | "command.session" | "command.model" | "command.message_read" | "command.host_tools" | "command.host_uri" | "command.admin" | "bash.readonly" | "bash.mutating" | "bash.destructive" | "git.force_push" | "file.delete" | "file.write" | "host_tool.invoke" | "host_uri.read" | "host_uri.write" | "auth.login";
+/** Typed error when a command's coarse scope is not in the declared allowlist. */
+export interface RpcScopeDenied {
+    code: "scope_denied";
+    scope: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    /** Always true: enforcement happens before the side effect runs. */
+    pre_side_effect: true;
+}
+/** Typed error when an action class is not in the declared allowlist (default-deny). */
+export interface RpcActionDenied {
+    code: "action_denied";
+    action: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    pre_side_effect: true;
+}

package/dist/types/modes/shared/agent-wire/approval-gate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ralplan approval + ultragoal execution gate mapping (#317).
+ *
+ * Maps the two human-gated lifecycle decisions onto `workflow_gate` events:
+ *  - ralplan `pending approval` -> `workflow_gate` { kind: "approval" } whose
+ *    answer is one of approve / request-changes / reject (+ optional comments);
+ *  - ultragoal execution sign-off -> `workflow_gate` { kind: "execution" } whose
+ *    answer is approve / decline (+ optional reason).
+ *
+ * Gates remain mandatory; the external agent substitutes for the human at the
+ * answer boundary only. Declining / requesting changes is honored and is NEVER
+ * silently treated as approval.
+ *
+ * This is the pure mapping primitive; routing ralplan/ultragoal through it when
+ * an unattended controller + gate broker are attached is wired with the transport
+ * in #321 and exercised end-to-end by #323.
+ */
+import type { RpcWorkflowGateContext } from "../../rpc/rpc-types";
+import type { OpenGateInput } from "./workflow-gate-broker";
+export type ApprovalDecision = "approve" | "request-changes" | "reject";
+export type ExecutionDecision = "approve" | "decline";
+export interface ApprovalGateAnswer {
+    decision: ApprovalDecision;
+    comments?: string;
+}
+export interface ExecutionGateAnswer {
+    decision: ExecutionDecision;
+    reason?: string;
+}
+export interface ApprovalGateResult {
+    approved: boolean;
+    decision: ApprovalDecision;
+    comments?: string;
+}
+export interface ExecutionGateResult {
+    approved: boolean;
+    decision: ExecutionDecision;
+    reason?: string;
+}
+export declare class ApprovalGateError extends Error {
+    readonly code: "invalid_answer_shape" | "unknown_decision" | "missing_comments";
+    constructor(code: "invalid_answer_shape" | "unknown_decision" | "missing_comments", message: string);
+}
+/** Build the ralplan `pending approval` -> `workflow_gate { kind: "approval" }` open-input. */
+export declare function approvalGate(context?: RpcWorkflowGateContext): OpenGateInput;
+/** Build the ultragoal execution sign-off -> `workflow_gate { kind: "execution" }` open-input. */
+export declare function executionGate(context?: RpcWorkflowGateContext): OpenGateInput;
+/**
+ * Decode a ralplan approval answer. `request-changes` requires comments and is
+ * NEVER treated as approval; only an explicit `approve` advances.
+ */
+export declare function decodeApproval(answer: unknown): ApprovalGateResult;
+/**
+ * Decode an ultragoal execution answer. Only an explicit `approve` advances;
+ * `decline` is honored and never silently approved.
+ */
+export declare function decodeExecution(answer: unknown): ExecutionGateResult;

package/dist/types/modes/shared/agent-wire/command-dispatch.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool } from "@gajae-code/agent-core";
 import type { ExtensionUIContext } from "../../../extensibility/extensions";
 import type { AgentSession } from "../../../session/agent-session";
-import type { RpcCommand, RpcExtensionUIRequest, RpcHostToolDefinition, RpcHostUriSchemeDefinition, RpcResponse } from "../../rpc/rpc-types";
+import type { RpcCommand, RpcExtensionUIRequest, RpcHostToolDefinition, RpcHostUriSchemeDefinition, RpcResponse, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGateResolution, RpcWorkflowGateResponse } from "../../rpc/rpc-types";
 export type RpcCommandDispatchOutput = (obj: RpcResponse | RpcExtensionUIRequest | object) => void;
 export interface RpcHostToolRegistry {
     setTools(tools: RpcHostToolDefinition[]): AgentTool[];
@@ -9,12 +9,27 @@ export interface RpcHostToolRegistry {
 export interface RpcHostUriRegistry {
     setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[];
 }
+/**
+ * Optional unattended control plane wired into RPC dispatch (#318/#319/#323).
+ * When present, `negotiate_unattended` and `workflow_gate_response` route here
+ * instead of falling through to the unknown-command path.
+ */
+export interface RpcUnattendedControlPlane {
+    /** Enter unattended mode (fail-closed); throws an Error on refusal. */
+    negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted;
+    /** Resolve a pending workflow gate with the agent's answer. */
+    resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+    isUnattended?(): boolean;
+    preflightCommand?(command: RpcCommand): void;
+    reconcileUsage?(phase?: string): void;
+}
 export interface RpcCommandDispatchContext {
     session: AgentSession;
     output: RpcCommandDispatchOutput;
     hostToolRegistry: RpcHostToolRegistry;
     hostUriRegistry: RpcHostUriRegistry;
     createUiContext: () => Pick<ExtensionUIContext, "notify">;
+    unattendedControlPlane?: RpcUnattendedControlPlane;
 }
 export declare function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): RpcHostToolDefinition[];
 export declare function dispatchRpcCommand(command: RpcCommand, context: RpcCommandDispatchContext): Promise<RpcResponse>;

package/dist/types/modes/shared/agent-wire/deep-interview-gate.d.ts

@@ -0,0 +1,47 @@
+import type { OpenGateInput } from "./workflow-gate-broker";
+/** "Other (type your own)" sentinel, mirroring the interactive ask tool. */
+export declare const GATE_OTHER_OPTION = "Other (type your own)";
+export interface AskGateQuestion {
+    id: string;
+    question: string;
+    options: Array<{
+        label: string;
+    }>;
+    multi?: boolean;
+    recommended?: number;
+}
+export interface AskGateResult {
+    id: string;
+    question: string;
+    options: string[];
+    multi: boolean;
+    selectedOptions: string[];
+    customInput?: string;
+}
+/**
+ * The answer shape an agent returns for a deep-interview question gate.
+ *
+ * `selected` are picked option labels; free text is conveyed by `other: true`
+ * plus `custom`, encoded separately from `selected` so a real option whose label
+ * happens to equal the display sentinel can never collide with the free-text path.
+ */
+export interface DeepInterviewGateAnswer {
+    selected: string[];
+    other?: boolean;
+    custom?: string;
+}
+export declare class DeepInterviewGateError extends Error {
+    readonly code: "invalid_answer_shape" | "unknown_option" | "multi_not_allowed" | "missing_custom" | "empty_selection" | "duplicate_selection";
+    constructor(code: "invalid_answer_shape" | "unknown_option" | "multi_not_allowed" | "missing_custom" | "empty_selection" | "duplicate_selection", message: string);
+}
+/** Build the `workflow_gate` open-input for one deep-interview question. */
+export declare function questionToGate(question: AskGateQuestion): OpenGateInput;
+/**
+ * Decode a gate answer into the QuestionResult the interactive path produces.
+ * Selections are de-duplicated (the interactive UI stores them in a Set), and
+ * free text is taken from `other`/`custom`. Throws DeepInterviewGateError on a
+ * semantically invalid answer.
+ */
+export declare function gateAnswerToResult(question: AskGateQuestion, answer: unknown): AskGateResult;
+/** Convenience: map a batch of ask questions to gate open-inputs. */
+export declare function questionsToGates(questions: AskGateQuestion[]): OpenGateInput[];

package/dist/types/modes/shared/agent-wire/event-envelope.d.ts

@@ -22,3 +22,10 @@ export declare class BridgeFrameSequencer {
 }
 /** Serialize a single `AgentSessionEvent` into an `event` wire frame. */
 export declare function toBridgeEventFrame(event: AgentSessionEvent, sequencer: BridgeFrameSequencer): BridgeEventFrame;
+/**
+ * Serialize a `workflow_gate` event into a sequenced wire frame (#321). The
+ * gate_id is stamped as the correlation id so the answer (posted to the
+ * ui-responses endpoint) can be matched, and the monotonic `seq` gives replay
+ * while `frame_id` + gate_id give idempotency.
+ */
+export declare function toBridgeWorkflowGateFrame(gate: import("../../rpc/rpc-types").RpcWorkflowGate, sequencer: BridgeFrameSequencer): import("./protocol").BridgeWorkflowGateFrame;

package/dist/types/modes/shared/agent-wire/handshake.d.ts

@@ -1,6 +1,7 @@
+import type { RpcUnattendedDeclaration } from "../../rpc/rpc-types";
 import { BRIDGE_PROTOCOL_VERSION, type BridgeFrameType } from "./protocol";
 import type { BridgeCommandScope } from "./scopes";
-export type BridgeCapability = "events" | "prompt" | "permission" | "elicitation" | "ui.declarative" | "ui.editor" | "ui.terminal_input" | "host_tools" | "host_uri" | "client_bridge.read_text_file" | "client_bridge.write_text_file" | "client_bridge.create_terminal";
+export type BridgeCapability = "events" | "prompt" | "permission" | "elicitation" | "ui.declarative" | "ui.editor" | "ui.terminal_input" | "host_tools" | "host_uri" | "client_bridge.read_text_file" | "client_bridge.write_text_file" | "client_bridge.create_terminal" | "workflow_gate";
 export interface BridgeProtocolRange {
     min: number;
     max: number;
@@ -10,6 +11,8 @@ export interface BridgeHandshakeRequest {
     capabilities: BridgeCapability[];
     requested_scopes: BridgeCommandScope[];
     last_seq?: number;
+    /** Optional unattended declaration (budget + scope + action allowlist) for #318/#319. */
+    unattended?: RpcUnattendedDeclaration;
 }
 export interface BridgeEndpointDescriptor {
     events: string;
@@ -29,6 +32,10 @@ export interface BridgeHandshakeAccepted {
     unsupported: BridgeCapability[];
     endpoints: BridgeEndpointDescriptor;
     frame_types: BridgeFrameType[];
+    /** Echoed unattended declaration when one was supplied and accepted (#321). */
+    accepted_unattended?: RpcUnattendedDeclaration;
+    /** Server-side accepted unattended mode after live negotiation, not just declaration echo. */
+    unattended_active?: boolean;
 }
 export interface BridgeHandshakeRejected {
     status: "rejected";
@@ -36,6 +43,8 @@ export interface BridgeHandshakeRejected {
     message: string;
 }
 export type BridgeHandshakeResponse = BridgeHandshakeAccepted | BridgeHandshakeRejected;
+/** Shape-validate an optional unattended declaration carried on the handshake. */
+export declare function isUnattendedDeclarationShape(value: unknown): value is RpcUnattendedDeclaration;
 export declare function isBridgeHandshakeRequest(value: unknown): value is BridgeHandshakeRequest;
 export declare function negotiateBridgeHandshake(request: BridgeHandshakeRequest, server: {
     sessionId: string;
@@ -43,4 +52,5 @@ export declare function negotiateBridgeHandshake(request: BridgeHandshakeRequest
     scopes: readonly BridgeCommandScope[];
     endpoints: BridgeEndpointDescriptor;
     frameTypes: readonly BridgeFrameType[];
+    acceptedUnattended?: RpcUnattendedDeclaration;
 }): BridgeHandshakeResponse;

package/dist/types/modes/shared/agent-wire/protocol.d.ts

@@ -15,7 +15,7 @@ export type AgentSessionEventType = AgentSessionEvent["type"];
 /** Every agent-session event type, derived from the exhaustive registry. */
 export declare const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[];
 /** Top-level frame categories carried over any bridge transport. */
-export type BridgeFrameType = "ready" | "event" | "response" | "ui_request" | "permission_request" | "host_tool_call" | "host_uri_request" | "reset" | "error";
+export type BridgeFrameType = "ready" | "event" | "response" | "ui_request" | "permission_request" | "host_tool_call" | "host_uri_request" | "reset" | "workflow_gate" | "error";
 /**
  * Universal frame envelope. Every frame on every transport carries these
  * fields so clients can order (`seq`), resume (`seq` cursor), and correlate
@@ -42,3 +42,5 @@ export interface BridgeEventPayload {
 }
 /** An `AgentSessionEvent` serialized into a versioned wire frame. */
 export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;
+/** A `workflow_gate` event serialized into a versioned wire frame (#321). */
+export type BridgeWorkflowGateFrame = BridgeFrameEnvelope<"workflow_gate", import("../../rpc/rpc-types").RpcWorkflowGate>;

package/dist/types/modes/shared/agent-wire/responses.d.ts

@@ -1,4 +1,4 @@
 /** Shared RPC-compatible response helpers for agent-wire consumers. */
 import type { RpcCommand, RpcResponse } from "../../rpc/rpc-types";
 export declare function rpcSuccess<T extends RpcCommand["type"]>(id: string | undefined, command: T, data?: object | null): RpcResponse;
-export declare function rpcError(id: string | undefined, command: string, message: string): RpcResponse;
+export declare function rpcError(id: string | undefined, command: string, error: string | object): RpcResponse;

package/dist/types/modes/shared/agent-wire/unattended-action-policy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unattended action taxonomy + classifier (#319).
+ *
+ * Maps coarse command scopes and concrete bash commands onto the v1 action
+ * taxonomy so the controller can authorize (default-deny) BEFORE any side effect.
+ *
+ * The classifier is deliberately FAIL-CLOSED for shell evasion:
+ *  - nested execution via `$(...)`, backticks, and `<(...)` / `>(...)` is
+ *    extracted and classified recursively, so a destructive command hidden in a
+ *    substitution cannot masquerade as the harmless outer command;
+ *  - statements are split on newlines and `; && || | &`, so a second
+ *    (destructive) command on another line is classified too;
+ *  - leading environment assignments and wrappers (`sudo`, `env`, `command`,
+ *    `xargs`, …) are stripped/followed to the effective command;
+ *  - anything that is not provably read-only escalates to at least
+ *    `bash.mutating`, and clearly destructive forms escalate further, so an
+ *    undeclared destructive action is denied rather than silently allowed.
+ */
+import type { RpcUnattendedActionClass } from "../../rpc/rpc-types";
+import type { BridgeCommandScope } from "./scopes";
+/** Coarse command scope -> `command.<scope>` action class. */
+export declare function actionClassForScope(scope: BridgeCommandScope): RpcUnattendedActionClass;
+/**
+ * Classify a (possibly compound / nested) bash command into the most severe
+ * action class across all statements and nested substitutions. Fail-closed.
+ */
+export declare function classifyBashAction(command: string): RpcUnattendedActionClass;

package/dist/types/modes/shared/agent-wire/unattended-audit.d.ts

@@ -0,0 +1,68 @@
+import type { RpcBudgetExceeded, RpcWorkflowGateKind, RpcWorkflowStage } from "../../rpc/rpc-types";
+export declare const AUDIT_SCHEMA_VERSION = 1;
+export declare const AUDIT_CATEGORY = "unattended_lifecycle";
+export type AuditOutcome = "accepted" | "rejected" | "denied" | "exceeded" | "aborted" | "info";
+export interface AuditRecord {
+    event_id: string;
+    schema_version: number;
+    category: typeof AUDIT_CATEGORY;
+    run_id: string;
+    session_id?: string;
+    actor?: string;
+    timestamp: string;
+    event: string;
+    outcome: AuditOutcome;
+    dedupe_key: string;
+    gate_id?: string;
+    stage?: RpcWorkflowStage;
+    kind?: RpcWorkflowGateKind;
+    scope?: string;
+    action?: string;
+    budget?: RpcBudgetExceeded;
+    /** Full answer (omitted when redaction is enabled). */
+    answer?: unknown;
+    answer_hash?: string;
+    error?: unknown;
+}
+export interface AuditQuery {
+    run_id?: string;
+    session_id?: string;
+    actor?: string;
+    gate_id?: string;
+    outcome?: AuditOutcome;
+    event?: string;
+    since?: string;
+    until?: string;
+}
+export interface AuditLogOptions {
+    /** When true, gate answers are stored as hash + summary only. */
+    redactAnswers?: boolean;
+    /** Injectable id/clock for deterministic tests. */
+    now?(): number;
+    nextId?(): string;
+}
+export declare function defaultAuditPath(runId: string, root?: string): string;
+/** Append-only audit log writer + reader for one unattended run. */
+export declare class UnattendedAuditLog {
+    private readonly filePath;
+    private readonly seen;
+    private readonly now;
+    private readonly nextId;
+    private readonly redactAnswers;
+    constructor(filePath: string, options?: AuditLogOptions);
+    /**
+     * Append a record. Returns the written record, or `null` if a record with the
+     * same dedupe_key was already written (exactly-once).
+     */
+    record(input: Omit<AuditRecord, "event_id" | "schema_version" | "category" | "timestamp">): AuditRecord | null;
+    /** Append one line and fsync it for crash durability. */
+    private appendDurable;
+    /** Read every record (fail-closed: a corrupt line throws rather than silently dropping). */
+    readAll(): AuditRecord[];
+    /** Query records with filters (run/session/actor/gate/outcome/event + time window). */
+    query(filter?: AuditQuery): AuditRecord[];
+    /** Export the full trail as an array (for `get_unattended_audit`). */
+    export(filter?: AuditQuery): AuditRecord[];
+}
+/** SHA-256 of the canonical JSON of an answer (matches the gate broker's hash). */
+export declare function answerHash(answer: unknown): string;