@gajae-code/coding-agent 0.2.5 → 0.3.0

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

@@ -2,6 +2,8 @@ import type { WorkflowHudSummary } from "../skill-state/active-state";
 export type GjcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
 export type GjcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
+export type GjcTeamWorkerLifecycleState = "starting" | "ready" | "working" | "draining" | "stopped" | "failed" | "unknown";
+export type GjcTeamShutdownMode = "graceful" | "force" | "abort";
 export declare const GJC_TEAM_DEFAULT_WORKERS = 3;
 export declare const GJC_TEAM_MAX_WORKERS = 20;
 export type GjcTeamWorkerCli = "gjc";
@@ -33,6 +35,25 @@ export interface GjcTeamTaskClaim {
     token: string;
     leased_until: string;
 }
+export type GjcTeamTaskCompletionEvidenceKind = "command" | "inspection" | "artifact";
+export type GjcTeamTaskCompletionEvidenceStatus = "passed" | "failed" | "not_run" | "verified" | "rejected";
+export interface GjcTeamTaskCompletionEvidenceItem {
+    kind: GjcTeamTaskCompletionEvidenceKind;
+    status: GjcTeamTaskCompletionEvidenceStatus;
+    summary: string;
+    command?: string;
+    artifact?: string;
+    location?: string;
+    output?: string;
+}
+export interface GjcTeamTaskCompletionEvidence {
+    summary: string;
+    items: GjcTeamTaskCompletionEvidenceItem[];
+    files?: string[];
+    notes?: string;
+    recorded_by: string;
+    recorded_at: string;
+}
 export interface GjcTeamTask {
     id: string;
     subject: string;
@@ -43,9 +64,13 @@ export interface GjcTeamTask {
     assignee?: string;
     owner?: string;
     result?: string;
+    completion_evidence?: GjcTeamTaskCompletionEvidence;
     error?: string;
     blocked_by?: string[];
     depends_on?: string[];
+    lane?: string;
+    required_role?: string;
+    allowed_roles?: string[];
     version: number;
     claim?: GjcTeamTaskClaim;
     created_at: string;
@@ -102,6 +127,22 @@ export interface GjcTeamMonitorSnapshot {
     integration_by_worker: Record<string, GjcTeamWorkerIntegrationState>;
     updated_at: string;
 }
+export interface GjcTeamWorkerLifecycle {
+    worker: string;
+    lifecycle_state: GjcTeamWorkerLifecycleState;
+    worker_status_state: GjcWorkerStatusState;
+    pane_id?: string;
+    pid?: number;
+    started_at?: string;
+    updated_at: string;
+    stopped_at?: string;
+    stop_reason?: string;
+    shutdown_request_id?: string;
+    shutdown_requested_at?: string;
+    shutdown_acknowledged_at?: string;
+    shutdown_ack_status?: string;
+    shutdown_mode?: GjcTeamShutdownMode;
+}
 export type GjcTeamNotificationDeliveryState = "pending" | "sent" | "queued" | "deferred" | "failed" | "delivered" | "acknowledged";
 export type GjcTeamPaneAttemptResult = "sent" | "queued" | "deferred" | "failed";
 export interface GjcTeamNotification {
@@ -139,9 +180,13 @@ export interface GjcTeamSnapshot {
     task_counts: Record<GjcTeamTaskStatus, number>;
     workers: GjcTeamWorker[];
     integration_by_worker?: Record<string, GjcTeamWorkerIntegrationState>;
+    worker_lifecycle_by_id: Record<string, GjcTeamWorkerLifecycle>;
     notification_summary: GjcTeamNotificationSummary;
     updated_at: string;
 }
+export interface GjcTeamSnapshotOptions {
+    reconcileNotifications?: boolean;
+}
 export interface GjcTeamStartOptions {
     workerCount: number;
     agentType: string;
@@ -159,6 +204,16 @@ export interface GjcTeamApiClaimResult {
     claim_token?: string;
     reason?: string;
 }
+export type GjcTeamLivenessRecoveryReason = "claim_expired" | "stale_heartbeat" | "missing_pane" | "worker_lifecycle_failed" | "worker_lifecycle_stopped";
+export interface GjcTeamRecoveredClaim {
+    task_id: string;
+    worker: string;
+    reasons: GjcTeamLivenessRecoveryReason[];
+}
+export interface GjcTeamLivenessRecoveryResult {
+    recovered_claims: GjcTeamRecoveredClaim[];
+    stale_workers: Record<string, GjcTeamLivenessRecoveryReason[]>;
+}
 export interface GjcTeamMailboxMessage {
     message_id: string;
     from_worker: string;
@@ -181,6 +236,19 @@ export interface GjcTeamEvent {
     message?: string;
     data?: Record<string, unknown>;
 }
+export interface GjcTeamTraceEvent {
+    schema_version: 1;
+    trace_id: string;
+    span_id: string;
+    source_event_id: string;
+    event_type: string;
+    ts: string;
+    worker?: string;
+    task_id?: string;
+    message?: string;
+    evidence_refs?: string[];
+    data?: Record<string, unknown>;
+}
 interface WorkerStatusFile {
     state: GjcWorkerStatusState;
     current_task_id?: string;
@@ -202,8 +270,11 @@ export interface GjcWorkerIntegrationAttemptRequestResult {
     head?: string | null;
     status?: GjcWorkerCheckpointClassification["kind"];
 }
-export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "read-worker-heartbeat", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
+export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "update-worker-status", "read-worker-heartbeat", "recover-stale-claims", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "read-traces", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
 export declare function resolveGjcTeamStateRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
+export declare function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot, cwd?: string): Promise<void>;
+export declare function recoverGjcTeamStaleClaims(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamLivenessRecoveryResult>;
+type GjcTeamTaskMetadataInput = Partial<Pick<GjcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
 export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
 export declare function resolveGjcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export type GjcWorkerCheckpointClassification = {
@@ -229,7 +300,8 @@ export declare function classifyGjcTeamCheckpointFiles(files: string[]): {
 };
 export declare function classifyWorkerCheckpointStatus(cwd: string): GjcWorkerCheckpointClassification;
 export declare function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTeamSnapshot>;
-export declare function readGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
+export declare function readGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv, options?: GjcTeamSnapshotOptions): Promise<GjcTeamSnapshot>;
+export declare function monitorGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
 export declare function requestGjcWorkerIntegrationAttempt(cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcWorkerIntegrationAttemptRequestResult>;
 export declare function buildTeamHudSummary(snapshot: GjcTeamSnapshot, latestEvent?: GjcTeamEvent, latestMessage?: GjcTeamMailboxMessage): Promise<WorkflowHudSummary>;
 export declare function monitorGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
@@ -237,11 +309,11 @@ export declare function listGjcTeams(cwd?: string, env?: NodeJS.ProcessEnv): Pro
 export declare function shutdownGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
 export declare function listGjcTeamTasks(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask[]>;
 export declare function readGjcTeamTask(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
-export declare function createGjcTeamTask(teamName: string, subject: string, description: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
-export declare function updateGjcTeamTask(teamName: string, taskId: string, updates: Partial<Pick<GjcTeamTask, "subject" | "description" | "blocked_by" | "depends_on">>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
+export declare function createGjcTeamTask(teamName: string, subject: string, description: string, cwd?: string, env?: NodeJS.ProcessEnv, taskOptions?: GjcTeamTaskMetadataInput): Promise<GjcTeamTask>;
+export declare function updateGjcTeamTask(teamName: string, taskId: string, updates: Partial<Pick<GjcTeamTask, "subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles">>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
 export declare function claimGjcTeamTask(teamName: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv, taskId?: string): Promise<GjcTeamApiClaimResult>;
-export declare function transitionGjcTeamTaskStatus(teamName: string, taskId: string, status: GjcTeamTaskStatus, cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, workerId?: string, evidence?: string): Promise<GjcTeamTask>;
-export declare function transitionGjcTeamTask(teamName: string, taskId: string, status: GjcTeamTaskStatus | "complete", cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string): Promise<GjcTeamTask>;
+export declare function transitionGjcTeamTaskStatus(teamName: string, taskId: string, status: GjcTeamTaskStatus, cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, workerId?: string, completionEvidenceInput?: unknown): Promise<GjcTeamTask>;
+export declare function transitionGjcTeamTask(teamName: string, taskId: string, status: GjcTeamTaskStatus | "complete", cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, completionEvidenceInput?: unknown): Promise<GjcTeamTask>;
 export declare function releaseGjcTeamTaskClaim(teamName: string, taskId: string, claimToken: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
 export declare function replayGjcTeamNotifications(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
     notifications: GjcTeamNotification[];
@@ -252,6 +324,7 @@ export declare function broadcastGjcTeamMessage(teamName: string, fromWorker: st
 export declare function listGjcTeamMailbox(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamMailboxMessage[]>;
 export declare function markGjcTeamMailboxMessage(teamName: string, worker: string, messageId: string, field: "delivered_at" | "notified_at", cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamMailboxMessage>;
 export declare function readGjcWorkerStatus(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerStatusFile>;
+export declare function updateGjcWorkerStatus(teamName: string, worker: string, status: GjcWorkerStatusState, cwd?: string, env?: NodeJS.ProcessEnv, currentTaskId?: string, reason?: string): Promise<WorkerStatusFile>;
 export declare function readGjcWorkerHeartbeat(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile | null>;
 export declare function updateGjcWorkerHeartbeat(teamName: string, worker: string, heartbeat: WorkerHeartbeatFile, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile>;
 export declare function writeGjcWorkerInbox(teamName: string, worker: string, content: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
@@ -259,6 +332,7 @@ export declare function writeGjcWorkerInbox(teamName: string, worker: string, co
 }>;
 export declare function writeGjcWorkerIdentity(teamName: string, worker: GjcTeamWorker, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamWorker>;
 export declare function readGjcTeamEvents(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamEvent[]>;
+export declare function readGjcTeamTraces(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTraceEvent[]>;
 export declare function appendGjcTeamEvent(teamName: string, type: string, worker?: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamEvent>;
 export declare function awaitGjcTeamEvent(teamName: string, _timeoutMs?: number, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
     status: "event" | "timeout";
@@ -268,7 +342,7 @@ export declare function writeGjcMonitorSnapshot(teamName: string, snapshot: unkn
 export declare function readGjcMonitorSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
 export declare function writeGjcTaskApproval(teamName: string, taskId: string, approval: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
 export declare function readGjcTaskApproval(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
-export declare function writeGjcShutdownRequest(teamName: string, worker: string, requestedBy: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
+export declare function writeGjcShutdownRequest(teamName: string, worker: string, requestedBy: string, cwd?: string, env?: NodeJS.ProcessEnv, requestId?: string, mode?: GjcTeamShutdownMode, requestedAt?: string): Promise<Record<string, unknown>>;
 export declare function readGjcShutdownAck(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
 export declare function executeGjcTeamApiOperation(operation: string, input: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
 export declare function parseTeamLaunchArgs(argv: string[]): GjcTeamStartOptions;

package/dist/types/gjc-runtime/workflow-manifest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TypeScript is the authoritative source of truth for GJC workflow manifests.
+ * Any JSON manifest projection is derived from this module and must never be
+ * hand-edited.
+ */
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export interface WorkflowState {
+    id: string;
+    initial?: boolean;
+    terminal?: boolean;
+}
+export interface WorkflowTransition {
+    from: string;
+    to: string;
+    verb: string;
+}
+export interface WorkflowVerb {
+    name: string;
+    planned?: boolean;
+    /** Invocation surface that exposes this verb in the real CLI parser. */
+    surface?: "state-action" | "command-positional" | "command-flag";
+}
+export interface TypedArgSpec {
+    name: string;
+    type: "string" | "number" | "boolean" | "enum" | "object";
+    enumValues?: string[];
+    required?: boolean;
+    appliesToVerbs?: string[];
+    planned?: boolean;
+}
+export interface RetentionPolicy {
+    category: string;
+    keep?: number;
+    maxAgeDays?: number;
+}
+export interface SkillManifest {
+    skill: CanonicalGjcWorkflowSkill;
+    states: WorkflowState[];
+    initialState: string;
+    terminalStates: string[];
+    transitions: WorkflowTransition[];
+    verbs: WorkflowVerb[];
+    typedArgs: TypedArgSpec[];
+    retention: RetentionPolicy[];
+    hudFields: string[];
+    graphLabel: string;
+}
+export declare const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>;
+export declare function getSkillManifest(skill: CanonicalGjcWorkflowSkill): SkillManifest;
+export declare function isKnownWorkflowState(skill: CanonicalGjcWorkflowSkill, state: string): boolean;
+export declare function isValidTransition(skill: CanonicalGjcWorkflowSkill, from: string, to: string): boolean;
+export declare function listVerbs(skill: CanonicalGjcWorkflowSkill): string[];
+export declare function typedArgsFor(skill: CanonicalGjcWorkflowSkill, verb: string): TypedArgSpec[];
+export declare function serializeManifestProjection(): string;

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

@@ -0,0 +1,13 @@
+/**
+ * Deterministic recovery classifier (pure).
+ *
+ * Maps a bounded {@link Observation} + remaining retry budget to exactly one
+ * {@link RecoveryDecision}. Encodes the plan's hard data-loss invariants:
+ *   - dirty deltas are NEVER `restart-clean`; they map to `restart-preserve-delta`.
+ *   - unknown deltas are NEVER destructive; they map to `human-check`.
+ *   - a deleted/mismatched worktree maps to `human-check` (never recreate over unknown data).
+ * `send-enter` is intentionally never emitted: it is unsupported for the gajae-code
+ * RPC adapter in v1 (no blind key injection).
+ */
+import type { ClassifyInput, RecoveryDecision } from "./types";
+export declare function classifyRecovery(input: ClassifyInput): RecoveryDecision;

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

@@ -0,0 +1,30 @@
+/**
+ * Per-session control endpoint — a Unix domain socket served by the RuntimeOwner so
+ * stateless `gjc harness` CLI calls can route owner-routed primitives (submit, observe,
+ * recover, retire) to the live owner. One JSON request line in, one JSON response line out.
+ *
+ * The owner is the only listener; clients connect per call. When no socket is reachable
+ * the caller falls back to the no-owner behavior (read-only observe, owner-not-live submit).
+ *
+ * FIFO fallback (for platforms/paths where AF_UNIX is unavailable or path-length limited)
+ * is a documented seam tracked as an ADR follow-up.
+ */
+export interface EndpointRequest {
+    verb: string;
+    input: Record<string, unknown>;
+}
+export type EndpointHandler = (req: EndpointRequest) => Promise<unknown>;
+export declare class ControlServer {
+    #private;
+    readonly socketPath: string;
+    private readonly handler;
+    constructor(socketPath: string, handler: EndpointHandler);
+    listen(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class EndpointUnreachableError extends Error {
+    readonly socketPath: string;
+    constructor(socketPath: string);
+}
+/** Call the owner's control endpoint. Rejects with {@link EndpointUnreachableError} when no owner listens. */
+export declare function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs?: number): Promise<unknown>;

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

@@ -0,0 +1,47 @@
+export interface ValidationCommandSpec {
+    name: string;
+    command: string;
+}
+export interface ValidationRun {
+    exactCommand: string;
+    cwd: string;
+    exitStatus: number;
+    pass: boolean;
+}
+export interface FinalizeChecks {
+    runValidation(spec: ValidationCommandSpec): Promise<ValidationRun>;
+    resolveCommit(): Promise<string | null>;
+    commitOnBranch(commit: string, branch: string): Promise<boolean>;
+    prOrIssue(): Promise<{
+        prUrl: string | null;
+        issueArtifact: string | null;
+    }>;
+}
+export interface FinalizeOptions {
+    root: string;
+    sessionId: string;
+    workspace: string;
+    branch: string;
+    requireTests?: boolean;
+    requireCommit?: boolean;
+    requirePr?: boolean;
+    validationCommands?: ValidationCommandSpec[];
+    checks: FinalizeChecks;
+    clock?: () => number;
+}
+export interface FinalizeResult {
+    completed: boolean;
+    receiptPath: string | null;
+    validation: {
+        name: string;
+        valid: boolean;
+        exitStatus: number;
+    }[];
+    commitHash: string | null;
+    prUrl: string | null;
+    issueArtifact: string | null;
+    blockers: string[];
+}
+export declare function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult>;
+/** Real checks: git for commit/branch, gh for PR, Bun.spawn for validation commands. */
+export declare function defaultFinalizeChecks(workspace: string): FinalizeChecks;

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

@@ -0,0 +1,29 @@
+/**
+ * Pure mapping from `gjc --mode rpc` event frames (docs/rpc.md) to bounded owner event kinds
+ * and {@link ObservedSignal}s. The owner feeds raw frames through this mapper and emits the
+ * result via its single-writer #emit — the mapper itself performs NO IO and NO appends.
+ *
+ * Hard rule: evidence is BOUNDED — only ids, names, categories, statuses, cursors, timestamps,
+ * and short codes/messages. Never assistant text, message deltas, command output, or raw args.
+ */
+import type { ObservedSignal } from "./types";
+export interface MappedFrame {
+    /** Owner event kind (rpc_*). */
+    kind: string;
+    /** Bounded observed signal, or null when the frame carries no user-facing signal. */
+    signal: ObservedSignal | null;
+    /** Bounded evidence — ids/names/statuses/cursors/timestamps/short codes only. */
+    evidence: Record<string, unknown>;
+    /** Severity for the emitted event. */
+    severity: "info" | "warn" | "critical";
+    /** Never-drop frames (must be enqueued in order, never coalesced away). */
+    semantic: boolean;
+    /** Coalescing key for high-frequency non-semantic frames (message id / tool id); null otherwise. */
+    coalesceKey: string | null;
+}
+export declare function isTestRunnerTool(toolName?: unknown, command?: unknown): boolean;
+/**
+ * Map a single RPC frame. Returns null for frames that carry no observability value
+ * (or that the adapter handles itself: `ready`, `response`).
+ */
+export declare function mapRpcFrame(frame: Record<string, unknown>): MappedFrame | null;

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

@@ -0,0 +1,35 @@
+import { type FinalizeChecks, type FinalizeResult, type ValidationCommandSpec } from "./finalize";
+import { type PreserveResult } from "./preserve";
+import { type HarnessRpc } from "./rpc-adapter";
+import { type HarnessLifecycle, type Observation, type RecoveryClassification, type RetryBudget, type Severity } from "./types";
+export interface OperateOptions {
+    root: string;
+    sessionId: string;
+    workspace: string;
+    branch: string;
+    rpc: HarnessRpc;
+    /** Factory used to (re)create the RPC subprocess on restart recovery. Defaults to reusing `rpc`. */
+    rpcFactory?: () => HarnessRpc;
+    /** Bounded observation provider (scripted in tests; real = git + rpc state). */
+    observe: () => Promise<Observation>;
+    /** Real dirty-worktree preservation; injectable for tests. Defaults to git stash/diff capture. */
+    preserve?: (workspace: string) => PreserveResult;
+    finalizeChecks: FinalizeChecks;
+    validationCommands?: ValidationCommandSpec[];
+    retryBudget?: Partial<RetryBudget>;
+    acceptanceTimeoutMs?: number;
+    maxIterations?: number;
+    /** Injected event emitter. Production owner calls must pass the lease-guarded single-writer #emit. */
+    emit: (severity: Severity, kind: string, evidence: Record<string, unknown>) => Promise<void>;
+    clock?: () => number;
+}
+export interface OperateResult {
+    completed: boolean;
+    lifecycle: HarnessLifecycle;
+    iterations: number;
+    classifications: RecoveryClassification[];
+    vanishReceiptIds: string[];
+    finalize?: FinalizeResult;
+    blockers: string[];
+}
+export declare function operate(goal: string, opts: OperateOptions): Promise<OperateResult>;

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

@@ -0,0 +1,46 @@
+/**
+ * RuntimeOwner — the detached per-session process that makes live control honest.
+ *
+ * Responsibilities:
+ *  - hold the {@link SessionLease} (single writer),
+ *  - own the {@link HarnessRpc} subprocess (injected; real `GajaeCodeRpc` in prod, fake in tests),
+ *  - serve owner-routed primitives over the {@link ControlServer} endpoint,
+ *  - be the SOLE writer of the severity event stream,
+ *  - heartbeat the lease.
+ *
+ * Stateless `gjc harness` CLI calls reach the owner via {@link resolveOwner} + the endpoint.
+ */
+import { type FinalizeChecks, type ValidationCommandSpec } from "./finalize";
+import type { HarnessRpc } from "./rpc-adapter";
+import { type SessionLease } from "./session-lease";
+export interface OwnerOptions {
+    root: string;
+    sessionId: string;
+    rpc: HarnessRpc;
+    ownerId?: string;
+    ttlMs?: number;
+    heartbeatMs?: number;
+    acceptanceTimeoutMs?: number;
+    clock?: () => number;
+    finalizeChecks?: FinalizeChecks;
+    validationCommands?: ValidationCommandSpec[];
+}
+export interface OwnerStartInfo {
+    ownerId: string;
+    socketPath: string;
+    leaseEpoch: number;
+}
+export declare class RuntimeOwner {
+    #private;
+    readonly ownerId: string;
+    constructor(opts: OwnerOptions);
+    start(): Promise<OwnerStartInfo>;
+    stop(): Promise<void>;
+}
+export interface ResolvedOwner {
+    live: boolean;
+    socketPath: string | null;
+    lease: SessionLease | null;
+}
+/** Determine whether a live owner currently holds the session (for CLI routing). */
+export declare function resolveOwner(root: string, sessionId: string): Promise<ResolvedOwner>;

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

@@ -0,0 +1,19 @@
+import type { GitDelta } from "./types";
+export interface UntrackedEntry {
+    path: string;
+    size: number;
+    sha256: string;
+}
+export interface PreserveResult {
+    gitDelta: GitDelta;
+    trackedDiff: string;
+    trackedDiffSha256: string;
+    untrackedManifest: UntrackedEntry[];
+    stashRef: string | null;
+    snapshotComplete: boolean;
+}
+/**
+ * Capture + snapshot a (possibly dirty) worktree without mutating it. Safe to call on a clean
+ * tree (returns empty evidence). Never deletes, resets, or cleans.
+ */
+export declare function preserveDirtyWorktree(workspace: string): PreserveResult;

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

@@ -0,0 +1,88 @@
+import type { GitDelta, ReceiptFamily, RecoveryClassification } from "./types";
+export interface ReceiptSubject {
+    workspace: string;
+    branch: string | null;
+    head: string | null;
+    commit: string | null;
+}
+export interface ReceiptEnvelope<E = Record<string, unknown>> {
+    receiptId: string;
+    schemaVersion: number;
+    sessionId: string;
+    family: ReceiptFamily;
+    valid: boolean;
+    createdAt: string;
+    source: string;
+    subject: ReceiptSubject;
+    evidence: E;
+    /** Hashes of out-of-line artifacts (diff patches, validation logs) folded into the receipt hash. */
+    artifactHashes: Record<string, string>;
+    sha256: string;
+}
+export declare const RECEIPT_SCHEMA_VERSION: 1;
+export declare function sha256Hex(input: string): string;
+export interface BuildReceiptInput<E> {
+    receiptId: string;
+    sessionId: string;
+    family: ReceiptFamily;
+    source: string;
+    subject: ReceiptSubject;
+    evidence: E;
+    artifactHashes?: Record<string, string>;
+    createdAt?: string;
+    valid?: boolean;
+}
+export declare function buildReceipt<E>(input: BuildReceiptInput<E>): ReceiptEnvelope<E>;
+export interface ValidationOutcome {
+    valid: boolean;
+    reasons: string[];
+}
+/** Recompute the hash and run structural family checks. Fail-closed. */
+export declare function validateReceipt(receipt: ReceiptEnvelope<unknown>): ValidationOutcome;
+export interface VanishEvidence {
+    classification: RecoveryClassification;
+    gitDelta: GitDelta;
+    gitStatusPorcelain: string;
+    untrackedManifest: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    preservation: "snapshot" | "stash" | "block";
+    stashRef: string | null;
+    snapshotComplete: boolean;
+    forbiddenActions: string[];
+}
+export interface PromptAcceptanceEvidence {
+    promptSha256: string;
+    rpcCommandId: string;
+    preSubmitState: {
+        isStreaming: boolean;
+        steeringQueueDepth: number;
+        followupQueueDepth: number;
+    };
+    preSubmitCursor: number;
+    agentStartCursor: number;
+    acceptedAt: string;
+    singleFlight: true;
+}
+export interface ValidationEvidence {
+    command: string;
+    exactCommand: string;
+    cwd: string;
+    exitStatus: number;
+    pass: boolean;
+    commitUnderTest: string | null;
+}
+export interface CompletionEvidence {
+    finalCommit: string;
+    branch: string;
+    prUrl: string | null;
+    issueArtifact: string | null;
+    requiredValidationReceiptIds: string[];
+    finalLifecycle: string;
+    finalizedAt: string;
+    blockers: 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

@@ -0,0 +1,66 @@
+export interface RpcStateSnapshot {
+    isStreaming: boolean;
+    steeringQueueDepth: number;
+    followupQueueDepth: number;
+}
+/** Abstract handle to a live gajae-code RPC session. */
+export interface HarnessRpc {
+    getState(): Promise<RpcStateSnapshot>;
+    /** Send a prompt; resolves with the RPC command id and whether it was acked. Does NOT await agent_start. */
+    sendPrompt(prompt: string): Promise<{
+        commandId: string;
+        ack: boolean;
+    }>;
+    /** Monotonic count of events observed so far (the acceptance cursor). */
+    eventCursor(): number;
+    /** Resolve when an `agent_start` event arrives strictly after `afterCursor`, else null on timeout. */
+    waitForAgentStart(afterCursor: number, timeoutMs: number): Promise<{
+        cursor: number;
+    } | null>;
+    close(): Promise<void>;
+    /** Subscribe to parsed event frames (non-ready, non-response), fired AFTER the cursor advances. Returns unsubscribe. */
+    onEventFrame?(listener: (frame: Record<string, unknown>) => void): () => void;
+    /** Whether the underlying RPC subprocess is still alive. */
+    isLive?(): boolean;
+    /** ISO timestamp of the last observed event frame, or null. */
+    lastFrameAt?(): string | null;
+}
+export interface AcceptanceResult {
+    accepted: boolean;
+    reason: string;
+    commandId: string | null;
+    preSubmitCursor: number;
+    agentStartCursor: number | null;
+    preSubmitState: RpcStateSnapshot;
+}
+/**
+ * Single-flight acceptance: idle + empty-queue pre-state, ack, then the NEXT
+ * `agent_start` after the pre-submit cursor within `timeoutMs`.
+ */
+export declare function singleFlightAccept(rpc: HarnessRpc, prompt: string, timeoutMs: number): Promise<AcceptanceResult>;
+/**
+ * Real adapter: spawns `gjc --mode rpc --session-dir <dir>` and speaks the JSONL
+ * protocol from docs/rpc.md. Verified end-to-end in the M10 suite.
+ */
+export declare class GajaeCodeRpc implements HarnessRpc {
+    #private;
+    constructor(opts: {
+        sessionDir: string;
+        command?: string[];
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    onEventFrame(listener: (frame: Record<string, unknown>) => void): () => void;
+    isLive(): boolean;
+    lastFrameAt(): string | null;
+    getState(): Promise<RpcStateSnapshot>;
+    sendPrompt(prompt: string): Promise<{
+        commandId: string;
+        ack: boolean;
+    }>;
+    eventCursor(): number;
+    waitForAgentStart(afterCursor: number, timeoutMs: number): Promise<{
+        cursor: number;
+    } | null>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * v1 seams (M11). The control plane is harness-agnostic by design, but v1 ships ONLY the
+ * gajae-code adapter. Other harnesses and transports are explicit, designed-not-built seams
+ * that fail closed with a clear `seam_unsupported_in_v1` signal rather than silently degrading.
+ */
+import type { Harness } from "./types";
+export declare const SUPPORTED_HARNESSES: readonly Harness[];
+export declare const DEFERRED_SEAMS: readonly ["codex-adapter", "omx-adapter", "remote-transport", "global-daemon", "capability-token-auth", "web-viewer", "fleet-control-plane", "rich-tui-coview"];
+export type DeferredSeam = (typeof DEFERRED_SEAMS)[number];
+export declare function isHarnessSupported(harness: string): harness is Harness;
+export interface UnsupportedSeamResult {
+    ok: false;
+    error: string;
+    evidence: {
+        seam: true;
+        name: string;
+        supported: readonly Harness[];
+        deferred: readonly string[];
+    };
+}
+export declare function unsupportedSeam(name: string): UnsupportedSeamResult;