@h-rig/contracts 0.0.6-alpha.17 → 0.0.6-alpha.170

package/dist/src/run-read-model.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Run read-model capability vocabulary.
+ *
+ * This file defines the contracts-only service seam that run-owner plugins can
+ * provide to CLI, cockpit, supervisor, and doctor surfaces. The OMP session is
+ * the journal source of truth: read-model implementations must key projections
+ * by the canonical run id/session id (`runId === sessionId`). Dispatch handles,
+ * worktree paths, and relay metadata are metadata only, never identity keys.
+ *
+ * Pure: types + one branded id, no folding, defaults, coercion, IO, or provider
+ * implementation.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RigStatsData } from "./cli-output";
+import type { RunDiscoveryFilter } from "./run-discovery";
+import type { RunJournalProjection } from "./run-journal";
+import type { RunRegistryRunProjection } from "./run-registry-backbone";
+import type { RigRunTimelineEntry } from "./run-timeline";
+import type { RunRecord, UnifiedInboxRequest } from "./run-record";
+import type { RunInboxResolutionInit, RunSessionCustomEntry } from "./run-session-journal";
+import type { TaskRecord } from "./task-source";
+export type RunReadModelSource = RunRecord["source"] | "all";
+export type RunReadModelRunSelector = {
+    /** Exact run id/session id, task id, or unique run-id prefix chosen by the caller. */
+    readonly id: string;
+    /** Prefer interpreting `id` as this kind when the caller already knows it. */
+    readonly kind?: "run-id" | "task-id" | "run-id-prefix" | "any";
+};
+export interface RunReadModelListInput {
+    readonly projectRoot: string;
+    readonly taskId?: string | null;
+    readonly source?: RunReadModelSource;
+    readonly includeInactive?: boolean;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelGetInput {
+    readonly projectRoot: string;
+    readonly selector: RunReadModelRunSelector;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelProjectionInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly sessionPath?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelRegistryProjectionInput {
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly folded: RunJournalProjection;
+    /** Raw run-session custom entries; providers own timeline extraction from them. */
+    readonly entries: readonly RunSessionCustomEntry[];
+    readonly title: string;
+    readonly joinLink?: string | null;
+    readonly webLink?: string | null;
+    readonly relayUrl?: string | null;
+    readonly sessionPath?: string | null;
+    readonly cwd?: string | null;
+    readonly collabCwd?: string | null;
+    readonly dispatchHandle?: string | null;
+    readonly timelineLimit?: number;
+    /** Optional caller-supplied timeline for compatibility; providers should prefer entries. */
+    readonly timeline?: readonly RigRunTimelineEntry[];
+}
+export interface RunReadModelDetailsInput extends RunReadModelGetInput {
+    readonly includeLogs?: boolean;
+    readonly includeSourceTask?: boolean;
+}
+export interface RunReadModelInboxInput {
+    readonly projectRoot: string;
+    readonly kind?: "approval" | "input" | "all";
+    readonly runId?: string | null;
+    readonly taskId?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelStatsInput {
+    readonly projectRoot: string;
+    /** ISO timestamp lower bound, or null for all-time. */
+    readonly since?: string | null;
+    /** Optional caller-supplied records, used when the surface already listed runs. */
+    readonly runs?: readonly RunRecord[];
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelInspectRowsInput {
+    readonly projectRoot: string;
+    readonly runs?: readonly RunRecord[];
+    readonly pendingInbox?: number | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelControlTargetInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly taskId?: string | null;
+    readonly purpose?: "attach" | "steer" | "stop" | "pause" | "resume" | "resolve-inbox";
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export type RunReadModelControl = {
+    readonly kind: "steer";
+    readonly message: string;
+} | {
+    readonly kind: "stop";
+    readonly reason: string;
+} | {
+    readonly kind: "pause";
+} | {
+    readonly kind: "resume";
+};
+export interface RunReadModelControlInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly control: RunReadModelControl;
+    readonly requestedBy?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelControlResult {
+    readonly runId: string;
+    readonly kind: RunReadModelControl["kind"];
+    readonly status: "delivered" | "not-found" | "not-live" | "unsupported";
+    readonly delivered: boolean;
+    readonly detail?: string | null;
+}
+export interface RunReadModelInboxResolutionInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly resolution: RunInboxResolutionInit;
+    readonly requestedBy?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelRemoveRegistryEntryInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+}
+export interface RunReadModelRemoveRegistryEntryResult {
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly removed: boolean;
+}
+export interface RunReadModelInboxCounts {
+    readonly approvals: number;
+    readonly inputs: number;
+    readonly total: number;
+}
+export interface RunReadModelInboxRecord {
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly status: "pending";
+    readonly title: string;
+    readonly body?: string | null;
+    readonly prompt: string;
+    readonly requestedAt: string | null;
+    readonly payload: unknown;
+    readonly source: "run";
+}
+export interface RunReadModelInboxResolutionResult {
+    readonly runId: string;
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly status: "resolved" | "not-found" | "not-live" | "unsupported";
+    readonly delivered: boolean;
+    readonly detail?: string | null;
+}
+export interface RunReadModelControlTarget {
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly sessionId: string | null;
+    readonly sessionPath: string | null;
+    readonly joinLink: string | null;
+    readonly webLink: string | null;
+    readonly relayUrl: string | null;
+    readonly collabCwd: string | null;
+    readonly live: boolean;
+    readonly stale: boolean;
+    readonly canDeliver: boolean;
+    readonly reason?: string | null;
+}
+export type RunReadModelStats = RigStatsData;
+export type RunReadModelStatusPhase = "starting" | "active" | "waiting" | "paused" | "needs-attention" | "completed" | "failed" | "stopped" | "unknown";
+export type RunReadModelStatusRole = "success" | "action-yellow" | "active-cyan" | "failure" | "muted" | "neutral";
+export interface RunReadModelRunClassification {
+    readonly status: string;
+    readonly phase: RunReadModelStatusPhase;
+    readonly role: RunReadModelStatusRole;
+    readonly rank: number;
+    readonly isActive: boolean;
+    readonly isTerminal: boolean;
+    readonly isNeedsAttention: boolean;
+}
+export interface RunReadModelInspectRow {
+    readonly id: string;
+    readonly label: string;
+    readonly currentValue: string;
+    readonly values?: readonly string[];
+    readonly heading?: boolean;
+    readonly description?: string;
+}
+export interface RunReadModelFailureSummary {
+    readonly kind: string;
+    readonly summary: string;
+    readonly detail?: string | null;
+    readonly retryable?: boolean | null;
+}
+export interface RunReadModelDetails {
+    readonly run: RunRecord;
+    readonly projection: RunJournalProjection;
+    readonly pendingInbox: readonly UnifiedInboxRequest[];
+    readonly inboxCounts: RunReadModelInboxCounts;
+    readonly sourceTask?: TaskRecord | null;
+    readonly sessionEntries?: readonly RunSessionCustomEntry[];
+    readonly failures: readonly RunReadModelFailureSummary[];
+    readonly logs: readonly string[];
+}
+export interface RunReadModelInspectResult {
+    readonly details: RunReadModelDetails;
+    readonly classification: RunReadModelRunClassification;
+    readonly rows: readonly RunReadModelInspectRow[];
+}
+/**
+ * Multi-method run read-model service capability.
+ *
+ * Providers own the executable discovery/folding/classification/control-target
+ * lookup. Consumers depend only on this contracts vocabulary and resolve the
+ * provider through the typed capability seam.
+ */
+export interface RunReadModelService {
+    readonly listRuns: (input: RunReadModelListInput) => Promise<readonly RunRecord[]>;
+    readonly getRun: (input: RunReadModelGetInput) => Promise<RunRecord | null>;
+    readonly getRunProjection: (input: RunReadModelProjectionInput) => Promise<RunJournalProjection | null>;
+    readonly buildRegistryProjection: (input: RunReadModelRegistryProjectionInput) => RunRegistryRunProjection;
+    readonly getRunDetails: (input: RunReadModelDetailsInput) => Promise<RunReadModelDetails | null>;
+    readonly inspectRun: (input: RunReadModelDetailsInput) => Promise<RunReadModelInspectResult | null>;
+    readonly listInboxRecords: (input: RunReadModelInboxInput) => Promise<readonly RunReadModelInboxRecord[]>;
+    readonly getInboxCounts: (input: RunReadModelInboxInput) => Promise<RunReadModelInboxCounts>;
+    readonly resolveInboxRequest: (input: RunReadModelInboxResolutionInput) => Promise<RunReadModelInboxResolutionResult>;
+    readonly getStats: (input: RunReadModelStatsInput) => Promise<RunReadModelStats>;
+    readonly getInspectRows: (input: RunReadModelInspectRowsInput) => Promise<readonly RunReadModelInspectRow[]>;
+    readonly deliverControl: (input: RunReadModelControlInput) => Promise<RunReadModelControlResult>;
+    readonly classifyRun: (run: RunRecord) => RunReadModelRunClassification;
+    readonly resolveControlTarget: (input: RunReadModelControlTargetInput) => Promise<RunReadModelControlTarget | null>;
+    readonly removeRunRegistryEntry: (input: RunReadModelRemoveRegistryEntryInput) => Promise<RunReadModelRemoveRegistryEntryResult>;
+}
+/** Stable id string for the run read-model service capability. */
+export declare const RUN_READ_MODEL_CAPABILITY_ID = "rig.runs.read-model";
+/**
+ * Branded run read-model capability id. `defineCapability(RUN_READ_MODEL)`
+ * (provider and consumers independently) resolves to a `RunReadModelService`.
+ */
+export declare const RUN_READ_MODEL: CapabilityId<RunReadModelService>;

package/dist/src/run-read-model.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/run-read-model.ts
+var RUN_READ_MODEL_CAPABILITY_ID = "rig.runs.read-model";
+var RUN_READ_MODEL = makeCapabilityId(RUN_READ_MODEL_CAPABILITY_ID);
+export {
+  RUN_READ_MODEL_CAPABILITY_ID,
+  RUN_READ_MODEL
+};

package/dist/src/run-record.d.ts

@@ -0,0 +1,45 @@
+import type { RunJournalProjection } from "./run-journal";
+import type { RigRunTimelineEntry } from "./run-timeline";
+export type UnifiedInboxRequest = {
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly title: string;
+    readonly body?: string | null;
+    readonly options?: readonly string[];
+    readonly requestedAt: string | null;
+    readonly source: "run";
+};
+/** Unified operator-facing run record shared by CLI, cockpit, relay, and client projection logic. */
+export interface RunRecord {
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly title: string;
+    /** RunStatus from the folded journal, or a liveness-derived fallback. */
+    readonly status: string;
+    readonly source: "local" | "remote";
+    /** True when the run is currently discoverable (registry heartbeat or local host). */
+    readonly live: boolean;
+    readonly stale: boolean;
+    readonly startedAt: string | null;
+    readonly updatedAt: string | null;
+    readonly completedAt: string | null;
+    readonly joinLink: string | null;
+    readonly webLink: string | null;
+    readonly relayUrl: string | null;
+    readonly sessionPath: string | null;
+    readonly prUrl: string | null;
+    readonly worktreePath: string | null;
+    readonly pendingApprovals: number;
+    readonly pendingInputs: number;
+    readonly steeringCount: number;
+    readonly stallCount: number;
+    readonly errorSummary?: string | null;
+    /** Timeline entries folded from the same OMP session custom entries as the journal. */
+    readonly timeline: RigRunTimelineEntry[];
+    /** Pending rig.run.* approvals/inputs only; rig.workflow.inbox.* is intentionally dead. */
+    readonly inbox: UnifiedInboxRequest[];
+    /** Live collab cwd when present in registry/discovery. */
+    readonly collabCwd: string | null;
+    /** The full folded journal (empty projection when no journal was readable). */
+    readonly projection: RunJournalProjection;
+}

package/dist/src/run-record.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/run-registry-backbone.d.ts

@@ -0,0 +1,56 @@
+import type { CapabilityId } from "./capability-id";
+import type { RigWorkflowOwner } from "./workflow-journal";
+import type { RunRecord } from "./run-record";
+import type { RunStatus } from "./runtime";
+/**
+ * cap:run-registry-backbone — transport-owned relay/registry room publication.
+ *
+ * The transport plugin owns the concrete @rig/relay-registry client. Run workers
+ * publish journal-derived projections through this structural seam so the worker
+ * lifecycle engine does not import the relay-registry implementation package.
+ */
+export declare const RUN_REGISTRY_BACKBONE_CAPABILITY_ID = "transport.run-registry-backbone";
+export type RunRegistryOwner = RigWorkflowOwner;
+export type RunRegistryStatus = RunStatus | "starting" | "waiting-input";
+export type RunRegistryRunProjection = Pick<RunRecord, "runId" | "taskId" | "title" | "status" | "source" | "startedAt" | "updatedAt" | "completedAt" | "joinLink" | "webLink" | "relayUrl" | "sessionPath" | "prUrl" | "worktreePath" | "pendingApprovals" | "pendingInputs" | "steeringCount" | "stallCount" | "errorSummary" | "timeline" | "collabCwd"> & {
+    readonly cwd?: string | null;
+    readonly dispatchHandle?: string | null;
+};
+export interface RunRegistryRegisterRoomInput {
+    readonly roomId: string;
+    readonly owner: RunRegistryOwner;
+    readonly repo: string;
+    readonly title: string;
+    readonly status: RunRegistryStatus;
+    readonly joinLink: string;
+    readonly webLink: string;
+    readonly relayUrl: string;
+    readonly startedAt: string;
+    readonly cwd?: string;
+    readonly sessionPath?: string;
+    readonly pid?: number;
+    readonly projection?: RunRegistryRunProjection;
+}
+export interface RunRegistryClient {
+    readonly registerRoom: (room: RunRegistryRegisterRoomInput) => Promise<unknown>;
+    readonly heartbeatRoom: (roomId: string, status: RunRegistryStatus, projection?: RunRegistryRunProjection) => Promise<unknown>;
+    readonly removeRoom: (roomId: string) => Promise<boolean>;
+}
+export interface RunWorkerProjectionConnection {
+    readonly ready: Promise<void>;
+    push(projection: RunRegistryRunProjection): void;
+    close(): void;
+}
+export interface RunRegistryBackboneService {
+    readonly createRegistryClient: (options: {
+        readonly baseUrl: string;
+        readonly namespaceKey: string;
+    }) => RunRegistryClient;
+    readonly connectWorkerProjection: (options: {
+        readonly baseUrl: string;
+        readonly namespaceKey: string;
+        readonly runId: string;
+    }) => RunWorkerProjectionConnection;
+    readonly coerceRegistryStatus: (value: unknown, fallback: RunRegistryStatus) => RunRegistryStatus;
+}
+export declare const RUN_REGISTRY_BACKBONE: CapabilityId<RunRegistryBackboneService>;

package/dist/src/run-registry-backbone.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/run-registry-backbone.ts
+var RUN_REGISTRY_BACKBONE_CAPABILITY_ID = "transport.run-registry-backbone";
+var RUN_REGISTRY_BACKBONE = makeCapabilityId(RUN_REGISTRY_BACKBONE_CAPABILITY_ID);
+export {
+  RUN_REGISTRY_BACKBONE_CAPABILITY_ID,
+  RUN_REGISTRY_BACKBONE
+};

package/dist/src/run-session-journal.d.ts

@@ -0,0 +1,69 @@
+import { type RunJournalEvent } from "./run-journal";
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type RunJournalEventInit = DistributiveOmit<RunJournalEvent, "v" | "seq" | "at" | "runId">;
+export declare const RIG_RUN_STATUS_CHANGED = "rig.run.status-changed";
+export declare const RIG_RUN_RECORD_PATCH = "rig.run.record-patch";
+export declare const RIG_RUN_TIMELINE_ENTRY = "rig.run.timeline-entry";
+export declare const RIG_RUN_LOG_ENTRY = "rig.run.log-entry";
+export declare const RIG_RUN_APPROVAL_REQUESTED = "rig.run.approval-requested";
+export declare const RIG_RUN_APPROVAL_RESOLVED = "rig.run.approval-resolved";
+export declare const RIG_RUN_INPUT_REQUESTED = "rig.run.input-requested";
+export declare const RIG_RUN_INPUT_RESOLVED = "rig.run.input-resolved";
+export declare const RIG_RUN_STEERING = "rig.run.steering";
+export declare const RIG_RUN_ADOPTED = "rig.run.adopted";
+export declare const RIG_RUN_STALL_DETECTED = "rig.run.stall-detected";
+export declare const RIG_RUN_CLOSEOUT_PHASE = "rig.run.closeout-phase";
+export declare const RIG_RUN_PIPELINE_RESOLVED = "rig.run.pipeline-resolved";
+export declare const RIG_RUN_STAGE_OUTCOME = "rig.run.stage-outcome";
+export declare const RIG_STOP_SENTINEL = "<<RIG_STOP";
+export declare const RIG_STOP_SENTINEL_END = ">>";
+export declare const RIG_PAUSE_SENTINEL = "<<RIG_PAUSE";
+export declare const RIG_RESUME_SENTINEL = "<<RIG_RESUME";
+export declare const RIG_CONTROL_SENTINEL_END = ">>";
+export type RunInboxResolutionSentinel = {
+    kind: "approval";
+    requestId: string;
+    decision: "approve" | "reject";
+    note?: string | null;
+    requestedBy: string | null;
+} | {
+    kind: "input";
+    requestId: string;
+    answers: Record<string, string>;
+    requestedBy: string | null;
+};
+export declare const RIG_INBOX_RESOLUTION_SENTINEL = "<<RIG_INBOX_RESOLUTION";
+export type RunInboxResolutionInit = {
+    kind: "approval";
+    requestId: string;
+    decision: "approve" | "reject";
+    note?: string | null;
+} | {
+    kind: "input";
+    requestId: string;
+    answers: Record<string, string>;
+};
+export declare const CUSTOM_TYPE_FOR: {
+    readonly "status-changed": "rig.run.status-changed";
+    readonly "record-patch": "rig.run.record-patch";
+    readonly "timeline-entry": "rig.run.timeline-entry";
+    readonly "log-entry": "rig.run.log-entry";
+    readonly "approval-requested": "rig.run.approval-requested";
+    readonly "approval-resolved": "rig.run.approval-resolved";
+    readonly "input-requested": "rig.run.input-requested";
+    readonly "input-resolved": "rig.run.input-resolved";
+    readonly steering: "rig.run.steering";
+    readonly adopted: "rig.run.adopted";
+    readonly "stall-detected": "rig.run.stall-detected";
+    readonly "closeout-phase": "rig.run.closeout-phase";
+    readonly "pipeline-resolved": "rig.run.pipeline-resolved";
+    readonly "stage-outcome": "rig.run.stage-outcome";
+};
+export type RunSessionCustomType = (typeof CUSTOM_TYPE_FOR)[RunJournalEvent["type"]];
+export declare const TYPE_FOR_CUSTOM: Readonly<Record<RunSessionCustomType, RunJournalEvent["type"]>>;
+export type RunSessionCustomEntry = {
+    type: string;
+    customType?: string;
+    data?: unknown;
+};
+export {};

package/dist/src/run-session-journal.js

@@ -0,0 +1,78 @@
+// @bun
+// packages/contracts/src/run-session-journal.ts
+var RIG_RUN_STATUS_CHANGED = "rig.run.status-changed";
+var RIG_RUN_RECORD_PATCH = "rig.run.record-patch";
+var RIG_RUN_TIMELINE_ENTRY = "rig.run.timeline-entry";
+var RIG_RUN_LOG_ENTRY = "rig.run.log-entry";
+var RIG_RUN_APPROVAL_REQUESTED = "rig.run.approval-requested";
+var RIG_RUN_APPROVAL_RESOLVED = "rig.run.approval-resolved";
+var RIG_RUN_INPUT_REQUESTED = "rig.run.input-requested";
+var RIG_RUN_INPUT_RESOLVED = "rig.run.input-resolved";
+var RIG_RUN_STEERING = "rig.run.steering";
+var RIG_RUN_ADOPTED = "rig.run.adopted";
+var RIG_RUN_STALL_DETECTED = "rig.run.stall-detected";
+var RIG_RUN_CLOSEOUT_PHASE = "rig.run.closeout-phase";
+var RIG_RUN_PIPELINE_RESOLVED = "rig.run.pipeline-resolved";
+var RIG_RUN_STAGE_OUTCOME = "rig.run.stage-outcome";
+var RIG_STOP_SENTINEL = "<<RIG_STOP";
+var RIG_STOP_SENTINEL_END = ">>";
+var RIG_PAUSE_SENTINEL = "<<RIG_PAUSE";
+var RIG_RESUME_SENTINEL = "<<RIG_RESUME";
+var RIG_CONTROL_SENTINEL_END = ">>";
+var RIG_INBOX_RESOLUTION_SENTINEL = "<<RIG_INBOX_RESOLUTION";
+var CUSTOM_TYPE_FOR = {
+  "status-changed": RIG_RUN_STATUS_CHANGED,
+  "record-patch": RIG_RUN_RECORD_PATCH,
+  "timeline-entry": RIG_RUN_TIMELINE_ENTRY,
+  "log-entry": RIG_RUN_LOG_ENTRY,
+  "approval-requested": RIG_RUN_APPROVAL_REQUESTED,
+  "approval-resolved": RIG_RUN_APPROVAL_RESOLVED,
+  "input-requested": RIG_RUN_INPUT_REQUESTED,
+  "input-resolved": RIG_RUN_INPUT_RESOLVED,
+  steering: RIG_RUN_STEERING,
+  adopted: RIG_RUN_ADOPTED,
+  "stall-detected": RIG_RUN_STALL_DETECTED,
+  "closeout-phase": RIG_RUN_CLOSEOUT_PHASE,
+  "pipeline-resolved": RIG_RUN_PIPELINE_RESOLVED,
+  "stage-outcome": RIG_RUN_STAGE_OUTCOME
+};
+var TYPE_FOR_CUSTOM = {
+  [RIG_RUN_STATUS_CHANGED]: "status-changed",
+  [RIG_RUN_RECORD_PATCH]: "record-patch",
+  [RIG_RUN_TIMELINE_ENTRY]: "timeline-entry",
+  [RIG_RUN_LOG_ENTRY]: "log-entry",
+  [RIG_RUN_APPROVAL_REQUESTED]: "approval-requested",
+  [RIG_RUN_APPROVAL_RESOLVED]: "approval-resolved",
+  [RIG_RUN_INPUT_REQUESTED]: "input-requested",
+  [RIG_RUN_INPUT_RESOLVED]: "input-resolved",
+  [RIG_RUN_STEERING]: "steering",
+  [RIG_RUN_ADOPTED]: "adopted",
+  [RIG_RUN_STALL_DETECTED]: "stall-detected",
+  [RIG_RUN_CLOSEOUT_PHASE]: "closeout-phase",
+  [RIG_RUN_PIPELINE_RESOLVED]: "pipeline-resolved",
+  [RIG_RUN_STAGE_OUTCOME]: "stage-outcome"
+};
+export {
+  TYPE_FOR_CUSTOM,
+  RIG_STOP_SENTINEL_END,
+  RIG_STOP_SENTINEL,
+  RIG_RUN_TIMELINE_ENTRY,
+  RIG_RUN_STEERING,
+  RIG_RUN_STATUS_CHANGED,
+  RIG_RUN_STALL_DETECTED,
+  RIG_RUN_STAGE_OUTCOME,
+  RIG_RUN_RECORD_PATCH,
+  RIG_RUN_PIPELINE_RESOLVED,
+  RIG_RUN_LOG_ENTRY,
+  RIG_RUN_INPUT_RESOLVED,
+  RIG_RUN_INPUT_REQUESTED,
+  RIG_RUN_CLOSEOUT_PHASE,
+  RIG_RUN_APPROVAL_RESOLVED,
+  RIG_RUN_APPROVAL_REQUESTED,
+  RIG_RUN_ADOPTED,
+  RIG_RESUME_SENTINEL,
+  RIG_PAUSE_SENTINEL,
+  RIG_INBOX_RESOLUTION_SENTINEL,
+  RIG_CONTROL_SENTINEL_END,
+  CUSTOM_TYPE_FOR
+};

package/dist/src/run-status.d.ts

@@ -0,0 +1,10 @@
+/** Operator-facing active-run classification.
+ *
+ * The canonical run-journal vocabulary intentionally keeps `needs-attention` as
+ * non-terminal so resume/steer/closeout state machines can still act on it.
+ * OpenTUI/task projections need a narrower meaning: only runs that are actively
+ * occupying a task slot should render as the task's active run. Legacy/closeout
+ * statuses from older authority files are treated conservatively as inactive so
+ * merged/closed runs do not pin task rows forever.
+ */
+export declare const OPERATOR_INACTIVE_RUN_STATUSES: ReadonlySet<string>;

package/dist/src/run-status.js

@@ -0,0 +1,27 @@
+// @bun
+// packages/contracts/src/run-status.ts
+var OPERATOR_INACTIVE_RUN_STATUSES = new Set([
+  "completed",
+  "complete",
+  "done",
+  "success",
+  "succeeded",
+  "passed",
+  "failed",
+  "failure",
+  "error",
+  "errored",
+  "stopped",
+  "cancelled",
+  "canceled",
+  "aborted",
+  "abort",
+  "merged",
+  "closed",
+  "skipped",
+  "needs-attention",
+  "needs_attention"
+]);
+export {
+  OPERATOR_INACTIVE_RUN_STATUSES
+};

package/dist/src/run-timeline.d.ts

@@ -0,0 +1,7 @@
+export type RigRunTimelineEntry = {
+    at: string | null;
+    type: string;
+    stage?: string | null;
+    status?: string | null;
+    detail?: string | null;
+};

package/dist/src/run-timeline.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/runtime-task-context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure runtime-task-context data shapes.
+ *
+ * These are behaviour-free data types describing the per-task runtime context
+ * the substrate materializes and threads to agents and capabilities. They carry
+ * no logic and import nothing but the sibling `RuntimeBrowserContext` contract,
+ * so they belong in the neutral contracts layer (exactly like `memory.ts` /
+ * `lifecycle-capabilities.ts`).
+ *
+ * The fs-backed loaders/serializers that PRODUCE and VALIDATE these shapes stay
+ * in `@rig/runtime/control-plane/runtime/context.ts`, which re-exports these
+ * types for back-compat so existing `import … from ".../runtime/context"` sites
+ * are unaffected.
+ */
+import type { RuntimeBrowserContext } from "./browser";
+/** Retrieval weighting for shared-memory recall; pure config data. */
+export type RuntimeMemoryRetrievalConfig = {
+    topK: number;
+    lexicalWeight: number;
+    vectorWeight: number;
+    recencyWeight: number;
+    confidenceWeight: number;
+};
+/** The materialized shared-memory context handed to a runtime task. */
+export type RuntimeMemoryContext = {
+    canonicalPath: string;
+    canonicalRef: string;
+    canonicalBaseOid?: string;
+    hydratedPath: string;
+    createdFresh: boolean;
+    retrieval: RuntimeMemoryRetrievalConfig;
+};
+/** The source-task contract fields a runtime task carries through. */
+export type RuntimeSourceTaskContract = {
+    id: string;
+    title?: string;
+    description?: string;
+    body?: string;
+    acceptanceCriteria?: string;
+    acceptance_criteria?: string;
+    sourceIssueId?: string;
+    status?: string;
+    issueType?: string;
+    role?: string;
+    externalRef?: string;
+    scope?: string[];
+    validation?: string[];
+    validators?: string[];
+    labels?: string[];
+};
+/** The fully-resolved per-task runtime context. */
+export type RuntimeTaskContext = {
+    runtimeId: string;
+    taskId: string;
+    role: string;
+    scopes: string[];
+    validation: string[];
+    sourceTask?: RuntimeSourceTaskContract;
+    browser?: RuntimeBrowserContext;
+    workspaceDir: string;
+    artifactRoot?: string;
+    hostProjectRoot?: string;
+    monorepoMainRoot?: string;
+    monorepoBaseRef?: string;
+    monorepoBaseCommit?: string;
+    initialHeadCommits?: {
+        project?: string;
+        monorepo?: string;
+    };
+    initialDirtyFiles?: {
+        project?: string[];
+        monorepo?: string[];
+    };
+    stateDir: string;
+    logsDir: string;
+    sessionDir: string;
+    sessionFile: string;
+    policyFile: string;
+    binDir: string;
+    createdAt: string;
+    memory?: RuntimeMemoryContext;
+};

package/dist/src/runtime-task-context.js

@@ -0,0 +1 @@
+// @bun