@oneharness/sdk 0.6.9 → 0.6.11

package/dist/generated/contracts.d.ts

@@ -1,3 +1,52 @@
+/**
+ * One control request the run handled, recorded in the report so a consumer
+ * can tell an interrupted turn from one that simply ended.
+ *
+ * A sum type discriminated by `outcome`, so a record can never say "served,
+ * and here is the refusal reason": the reason exists exactly when there was a
+ * refusal. Serialized flat — `{"outcome":"served","verb":…,"at":…}` /
+ * `{"outcome":"refused","verb":…,"at":…,"reason":…}`.
+ */
+export type ControlEvent = {
+    /**
+     * When the request was handled.
+     */
+    at: string;
+    outcome: "served";
+    /**
+     * Whether a redirection was committed with the abort. Omitted when it
+     * was a plain stop, so an older consumer reads the same record it
+     * always did.
+     */
+    redirected?: boolean | undefined;
+    /**
+     * The verb requested.
+     */
+    verb: "interrupt";
+    [k: string]: unknown;
+} | {
+    at: UtcInstant;
+    outcome: "refused";
+    reason: ControlReason;
+    verb: ControlVerb;
+    [k: string]: unknown;
+};
+/**
+ * An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.
+ */
+export type UtcInstant = string;
+/**
+ * Why a control request could not be served. Distinct reasons because a
+ * supervisor reacts differently to each: `unsupported` is permanent for the
+ * harness, `not_running` means the dispatch is gone, `no_active_turn` means
+ * the run is alive but between turns.
+ */
+export type ControlReason = "unsupported" | "no_active_turn" | "not_running";
+/**
+ * The control verb a supervisor sends. Only `interrupt` exists today; the
+ * frame's `v` is what leaves room for `steer` later.
+ */
+export type ControlVerb = "interrupt";
 export type ToolCallStatus = "completed" | "failed" | "timeout" | "interrupted";
 /**
  * How a normalized tool interval was obtained.
@@ -7,13 +56,14 @@ export type TimingSource = "provider_measured" | "stdout_observed";
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * How a harness emits its result, which decides how `text` is extracted.
  *
@@ -79,6 +129,14 @@ export interface RunReport {
      * project last); empty under `--no-config` or when none exist.
      */
     config_files: string[];
+    /**
+     * Out-of-band turn control for this run (`--control`), or `null` when none
+     * was requested — which is every ordinary run. It records the socket a
+     * separate `oneharness interrupt` process could address, the harness
+     * mechanism behind it, and each request served, so a consumer can tell an
+     * interrupted turn from one that simply ended.
+     */
+    control: ControlReport | null;
     dry_run: boolean;
     /**
      * Fallback-mode metadata when this run drove the selected harnesses in
@@ -189,6 +247,25 @@ export interface BatchReport {
     strategy: "speed" | "min-tokens";
     [k: string]: unknown;
 }
+/**
+ * The run report's `control` block: where the socket lived, which mechanism
+ * backed it, and every request served over the run's lifetime.
+ */
+export interface ControlReport {
+    /**
+     * Every control request served, in order.
+     */
+    interrupts: ControlEvent[];
+    /**
+     * The harness mechanism backing it.
+     */
+    mechanism: "claude-control-request" | "codex-app-server" | "opencode-http" | "acp-cancel" | "crush-http";
+    /**
+     * Absolute path of the socket this run listened on.
+     */
+    socket: string;
+    [k: string]: unknown;
+}
 /**
  * Metadata for a fallback run (harnesses tried in priority order until one
  * runs). Present on [`RunReport::fallback`] only in that mode. The per-harness
@@ -274,7 +351,7 @@ export interface RunResult {
      * Best-effort failure reason; `null` when unclassified. Distinct from
      * `status`, which records oneharness's relationship to the process. Two
      * families: coarse reasons for a non-zero run (`auth`, `rate_limit`,
-     * `model_not_found`, `quota`), and `tool_deferred` — a run that exited
+     * `model_not_found`, `quota`, `session_not_found`), and `tool_deferred` — a run that exited
      * *cleanly* but only deferred a builtin tool call instead of executing it
      * (Claude Code bridge/managed deployments), so it did no useful work. The
      * deferred case is the only `failure_kind` that can appear on a `status: ok`

package/dist/generated/history-line.d.ts

@@ -6,7 +6,7 @@ export type HistoryLine = ({
     harness: string;
     harness_id?: string | null | undefined;
     run_id: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     type: "event";
     variant?: string | null | undefined;
     [k: string]: unknown;
@@ -27,7 +27,7 @@ export type HistoryLine = ({
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | "1.4" | undefined;
+    schema_version?: "1.3" | "1.4" | "1.5" | undefined;
     [k: string]: unknown;
 } & ({
     status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
@@ -39,7 +39,13 @@ export type HistoryLine = ({
     status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
     [k: string]: unknown;
 } | {
-    schema_version?: "1.4" | undefined;
+    schema_version?: "1.4" | "1.5" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | null | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.5" | undefined;
     [k: string]: unknown;
 }) & ({
     duration_ms: number;
@@ -62,7 +68,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at: string;
@@ -97,7 +103,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at: string;
@@ -132,7 +138,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
@@ -167,7 +173,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
@@ -202,7 +208,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.3" | "1.4";
+    schema_version: "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at: string;
@@ -237,7 +243,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
@@ -261,13 +267,14 @@ export type TimingSource = "provider_measured" | "stdout_observed";
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * The unified approval mode, from least to most autonomy. A harness may not
  * support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the

package/dist/generated/history-records.d.ts

@@ -93,7 +93,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -323,7 +323,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -415,7 +415,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -507,7 +507,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -599,7 +599,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3" | "1.4";
+    schema_version: "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -944,13 +944,14 @@ export type TimingSource = "provider_measured" | "stdout_observed";
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * The outcome of attempting to run one harness.
  */
@@ -960,7 +961,7 @@ export type HistoryRecords = (({
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | "1.4" | undefined;
+    schema_version?: "1.3" | "1.4" | "1.5" | undefined;
     [k: string]: unknown;
 } & ({
     status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
@@ -972,7 +973,13 @@ export type HistoryRecords = (({
     status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
     [k: string]: unknown;
 } | {
-    schema_version?: "1.4" | undefined;
+    schema_version?: "1.4" | "1.5" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | null | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.5" | undefined;
     [k: string]: unknown;
 }) & HistoryRecord)[];
 /**

package/dist/generated/history-stream-envelope.d.ts

@@ -14,7 +14,7 @@ export type HistoryStreamEnvelope = {
         [k: string]: unknown;
     } | ({
         error: string;
-        schema_version?: "1.3" | "1.4" | undefined;
+        schema_version?: "1.3" | "1.4" | "1.5" | undefined;
         [k: string]: unknown;
     } & ({
         status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
@@ -26,7 +26,13 @@ export type HistoryStreamEnvelope = {
         status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
         [k: string]: unknown;
     } | {
-        schema_version?: "1.4" | undefined;
+        schema_version?: "1.4" | "1.5" | undefined;
+        [k: string]: unknown;
+    }) & ({
+        failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | null | undefined;
+        [k: string]: unknown;
+    } | {
+        schema_version?: "1.5" | undefined;
         [k: string]: unknown;
     }) & HistoryRecord;
     type: "record";
@@ -131,7 +137,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -361,7 +367,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -453,7 +459,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -545,7 +551,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -637,7 +643,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3" | "1.4";
+    schema_version: "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -982,13 +988,14 @@ export type TimingSource = "provider_measured" | "stdout_observed";
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * The outcome of attempting to run one harness.
  */
@@ -998,7 +1005,7 @@ export type HistoryEventLine = {
     harness: string;
     harness_id?: string | null | undefined;
     run_id: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {

package/dist/generated/history.d.ts

@@ -8,7 +8,7 @@ export type HistoryRecord = ({
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | "1.4" | undefined;
+    schema_version?: "1.3" | "1.4" | "1.5" | undefined;
     [k: string]: unknown;
 } & ({
     status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
@@ -20,7 +20,13 @@ export type HistoryRecord = ({
     status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
     [k: string]: unknown;
 } | {
-    schema_version?: "1.4" | undefined;
+    schema_version?: "1.4" | "1.5" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | null | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.5" | undefined;
     [k: string]: unknown;
 }) & ({
     duration_ms: number;
@@ -117,7 +123,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -347,7 +353,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -439,7 +445,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -531,7 +537,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3" | "1.4";
+    schema_version: "1.2" | "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -623,7 +629,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3" | "1.4";
+    schema_version: "1.3" | "1.4" | "1.5";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -968,13 +974,14 @@ export type TimingSource = "provider_measured" | "stdout_observed";
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * The outcome of attempting to run one harness.
  */

package/dist/generated/registry.d.ts

@@ -1,3 +1,13 @@
+/**
+ * How a harness accepts an out-of-band interrupt for an in-flight turn.
+ *
+ * Registry data on [`crate::domain::harness::HarnessSpec::control`], sourced
+ * from a live interrupt against the real CLI — never guessed. `None` there
+ * means `oneharness interrupt` is a loud usage error for the harness, never a
+ * silent no-op: a supervisor that is told "ok" while the turn keeps running is
+ * worse off than one told the lever does not exist.
+ */
+export type ControlShape = "claude-control-request" | "codex-app-server" | "opencode-http" | "acp-cancel" | "crush-http";
 /**
  * The unified approval mode, from least to most autonomy. A harness may not
  * support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the
@@ -19,6 +29,13 @@ export interface ListReport {
     [k: string]: unknown;
 }
 export interface HarnessInfo {
+    /**
+     * How `run --control` + `oneharness interrupt` abort an in-flight turn on
+     * this harness (the mechanism id), or `null` when it has no out-of-band
+     * turn control at all — in which case `--control` is a loud usage error for
+     * it, never a socket that reports success while the turn keeps running.
+     */
+    control: ControlShape | null;
     default_bin: string;
     display: string;
     /**

package/dist/generated/run-stream-envelope.d.ts

@@ -20,17 +20,67 @@ export type ToolCallStatus = "completed" | "failed" | "timeout" | "interrupted";
  * How a normalized tool interval was obtained.
  */
 export type TimingSource = "provider_measured" | "stdout_observed";
+/**
+ * One control request the run handled, recorded in the report so a consumer
+ * can tell an interrupted turn from one that simply ended.
+ *
+ * A sum type discriminated by `outcome`, so a record can never say "served,
+ * and here is the refusal reason": the reason exists exactly when there was a
+ * refusal. Serialized flat — `{"outcome":"served","verb":…,"at":…}` /
+ * `{"outcome":"refused","verb":…,"at":…,"reason":…}`.
+ */
+export type ControlEvent = {
+    /**
+     * When the request was handled.
+     */
+    at: string;
+    outcome: "served";
+    /**
+     * Whether a redirection was committed with the abort. Omitted when it
+     * was a plain stop, so an older consumer reads the same record it
+     * always did.
+     */
+    redirected?: boolean | undefined;
+    /**
+     * The verb requested.
+     */
+    verb: "interrupt";
+    [k: string]: unknown;
+} | {
+    at: UtcInstant;
+    outcome: "refused";
+    reason: ControlReason;
+    verb: ControlVerb;
+    [k: string]: unknown;
+};
+/**
+ * An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.
+ */
+export type UtcInstant = string;
+/**
+ * Why a control request could not be served. Distinct reasons because a
+ * supervisor reacts differently to each: `unsupported` is permanent for the
+ * harness, `not_running` means the dispatch is gone, `no_active_turn` means
+ * the run is alive but between turns.
+ */
+export type ControlReason = "unsupported" | "no_active_turn" | "not_running";
+/**
+ * The control verb a supervisor sends. Only `interrupt` exists today; the
+ * frame's `v` is what leaves room for `steer` later.
+ */
+export type ControlVerb = "interrupt";
 /**
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
  * value: serialized as the snake_case token a consumer reads in the report
- * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
- * wire shape is unchanged — modeling it as an enum keeps a misspelled or
- * invalid kind unrepresentable and gives every producer/consumer (classifier,
- * `is_failure`, the fallback fall-through rule, the report, history) one
- * definition to share instead of scattered string literals.
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `session_not_found`,
+ * `tool_deferred`), so the wire shape is unchanged — modeling it as an enum
+ * keeps a misspelled or invalid kind unrepresentable and gives every
+ * producer/consumer (classifier, `is_failure`, the fallback fall-through rule,
+ * the report, history) one definition to share instead of scattered string
+ * literals.
  */
-export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred";
 /**
  * How a harness emits its result, which decides how `text` is extracted.
  *
@@ -153,6 +203,14 @@ export interface RunReport {
      * project last); empty under `--no-config` or when none exist.
      */
     config_files: string[];
+    /**
+     * Out-of-band turn control for this run (`--control`), or `null` when none
+     * was requested — which is every ordinary run. It records the socket a
+     * separate `oneharness interrupt` process could address, the harness
+     * mechanism behind it, and each request served, so a consumer can tell an
+     * interrupted turn from one that simply ended.
+     */
+    control: ControlReport | null;
     dry_run: boolean;
     /**
      * Fallback-mode metadata when this run drove the selected harnesses in
@@ -263,6 +321,25 @@ export interface BatchReport {
     strategy: "speed" | "min-tokens";
     [k: string]: unknown;
 }
+/**
+ * The run report's `control` block: where the socket lived, which mechanism
+ * backed it, and every request served over the run's lifetime.
+ */
+export interface ControlReport {
+    /**
+     * Every control request served, in order.
+     */
+    interrupts: ControlEvent[];
+    /**
+     * The harness mechanism backing it.
+     */
+    mechanism: "claude-control-request" | "codex-app-server" | "opencode-http" | "acp-cancel" | "crush-http";
+    /**
+     * Absolute path of the socket this run listened on.
+     */
+    socket: string;
+    [k: string]: unknown;
+}
 /**
  * Metadata for a fallback run (harnesses tried in priority order until one
  * runs). Present on [`RunReport::fallback`] only in that mode. The per-harness
@@ -348,7 +425,7 @@ export interface RunResult {
      * Best-effort failure reason; `null` when unclassified. Distinct from
      * `status`, which records oneharness's relationship to the process. Two
      * families: coarse reasons for a non-zero run (`auth`, `rate_limit`,
-     * `model_not_found`, `quota`), and `tool_deferred` — a run that exited
+     * `model_not_found`, `quota`, `session_not_found`), and `tool_deferred` — a run that exited
      * *cleanly* but only deferred a builtin tool call instead of executing it
      * (Claude Code bridge/managed deployments), so it did no useful work. The
      * deferred case is the only `failure_kind` that can appear on a `status: ok`