@lumenflow/cli 4.23.0 → 5.0.0

package/packs/agent-runtime/remote-controls/operations.ts

@@ -0,0 +1,399 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// WU-2733 (INIT-060 Phase 3, ADR-013 §1 + §6):
+// Real kernel-side implementations for the six remote-control
+// operations. Each operation:
+//   1. Loads/mutates RemoteControlSessionState via the sidecar store
+//      (so state survives process restarts).
+//   2. Emits the ADR-013-governed event via the supplied sink
+//      (turn_aborted / autonomy_changed / tool_called).
+//   3. Returns a result that adheres to RemoteControlPort.
+//
+// No auto-wu:recover. recovery_action is always a hint; ADR-013 §1
+// safety lock is preserved.
+
+import { randomUUID } from 'node:crypto';
+import {
+  buildToolCalledEvent,
+  buildTurnAbortedEvent,
+  buildAutonomyChangedEvent,
+  emitAgentRuntimeEvent,
+  type AgentRuntimeCleanupStatus,
+  type AgentRuntimeEventSink,
+} from '../turn-lifecycle-events.js';
+import {
+  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES,
+  type AbortTurnInvocationResult,
+  type AgentRuntimeRemoteControlToolName,
+  type RemoteControlInvocationResult,
+} from './types.js';
+import type { AbortTurnInvocationInput, RemoteControlInvocationInput } from './port.js';
+import {
+  AGENT_RUNTIME_AUTONOMY_LEVELS,
+  AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES,
+  type AgentRuntimeAutonomyLevel,
+  type RemoteControlStateStore,
+} from './state-store.js';
+
+/**
+ * Observed turn index emitted in remote-control tool_called events.
+ * The real kernel runtime increments a per-turn counter; remote-control
+ * invocations happen OUTSIDE an active turn (that is precisely their
+ * purpose), so we emit 0 to signal "not tied to a turn index". This
+ * mirrors the mock adapter's constant for wire parity.
+ */
+const REMOTE_CONTROL_TURN_INDEX = 0;
+
+export interface RemoteControlOperationContext {
+  store: RemoteControlStateStore;
+  eventSink?: AgentRuntimeEventSink;
+  now: () => string;
+}
+
+function resolveSessionId(input: string | undefined): string | null {
+  if (input !== undefined && input.trim().length > 0) {
+    return input;
+  }
+  return null;
+}
+
+function emitToolCalled(
+  ctx: RemoteControlOperationContext,
+  toolName: AgentRuntimeRemoteControlToolName,
+  sessionId: string,
+): void {
+  emitAgentRuntimeEvent(
+    ctx.eventSink,
+    buildToolCalledEvent({
+      session_id: sessionId,
+      turn_index: REMOTE_CONTROL_TURN_INDEX,
+      tool_name: toolName,
+      tool_call_id: randomUUID(),
+    }),
+  );
+}
+
+function requireSessionId(
+  toolName: AgentRuntimeRemoteControlToolName,
+  input: string | undefined,
+): string {
+  const resolved = resolveSessionId(input);
+  if (!resolved) {
+    throw new Error(`Remote-control tool "${toolName}" requires a non-empty session_id input.`);
+  }
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// pause_turn
+// ---------------------------------------------------------------------------
+
+/**
+ * Soft-pause marker honoured at the next checkpoint. The running turn
+ * (if any) observes the marker via a state load and suspends gracefully.
+ * Re-pausing an already-paused session is idempotent — we refresh the
+ * reason+timestamp without toggling.
+ */
+export async function pauseTurn(
+  input: RemoteControlInvocationInput & { reason?: string | null },
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  const sessionId = requireSessionId(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN,
+    input.session_id,
+  );
+  const now = ctx.now();
+  const state = await ctx.store.loadOrDefault(sessionId, now);
+  const reason = typeof input.reason === 'string' ? input.reason : null;
+  await ctx.store.save({
+    ...state,
+    pause: {
+      paused: true,
+      paused_at: now,
+      resumed_at: null,
+      reason,
+    },
+    updated_at: now,
+  });
+  emitToolCalled(ctx, AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN, sessionId);
+  return {
+    status: 'ok',
+    tool_name: AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN,
+    session_id: sessionId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resume_workflow
+// ---------------------------------------------------------------------------
+
+/**
+ * Clears the pause marker so the next checkpoint observer advances the
+ * workflow. Does NOT re-enter the agent loop — the pauser/scheduler
+ * resumes the session on its next poll. Emits tool_called for audit.
+ */
+export async function resumeWorkflow(
+  input: RemoteControlInvocationInput,
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  const sessionId = requireSessionId(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW,
+    input.session_id,
+  );
+  const now = ctx.now();
+  const state = await ctx.store.loadOrDefault(sessionId, now);
+  await ctx.store.save({
+    ...state,
+    pause: {
+      paused: false,
+      paused_at: state.pause.paused_at,
+      resumed_at: now,
+      reason: state.pause.reason,
+    },
+    updated_at: now,
+  });
+  emitToolCalled(ctx, AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW, sessionId);
+  return {
+    status: 'ok',
+    tool_name: AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW,
+    session_id: sessionId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// abort_turn (ADR-013 §1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Hard-aborts the current turn and records the cleanup_status +
+ * recovery_action per ADR-013 §1:
+ *   - 'clean'           — no prior mutations; recovery_action = null
+ *   - 'partial'         — inflight approvals existed; recovery_action
+ *                         is a prose hint
+ *   - 'needs_recovery'  — abort interrupted a mid-flight approval with
+ *                         the abort ordered while paused; operator must
+ *                         run `wu:recover`
+ *
+ * NEVER auto-triggers wu:recover. The returned recovery_action is a
+ * hint cloud renders in the conductor UI (§1 safety lock).
+ */
+export async function abortTurn(
+  input: AbortTurnInvocationInput,
+  ctx: RemoteControlOperationContext,
+): Promise<AbortTurnInvocationResult> {
+  const sessionId = requireSessionId(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
+    input.session_id,
+  );
+  const now = ctx.now();
+  const state = await ctx.store.loadOrDefault(sessionId, now);
+  const { cleanup_status, recovery_action } = classifyAbort(state);
+  const reason =
+    typeof input.reason === 'string' && input.reason.trim().length > 0
+      ? input.reason
+      : 'operator-requested';
+  await ctx.store.save({
+    ...state,
+    abort: {
+      aborted: true,
+      aborted_at: now,
+      cleanup_status,
+      recovery_action,
+      reason,
+    },
+    pause: state.pause,
+    updated_at: now,
+  });
+
+  // ADR-013 §1: emit turn_aborted carrying the cleanup contract.
+  emitAgentRuntimeEvent(
+    ctx.eventSink,
+    buildTurnAbortedEvent({
+      session_id: sessionId,
+      turn_index: REMOTE_CONTROL_TURN_INDEX,
+      cleanup_status,
+      recovery_action,
+      reason,
+    }),
+  );
+  // ADR-013 §6: emit tool_called for audit of the governance surface.
+  emitToolCalled(ctx, AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN, sessionId);
+
+  return {
+    status: 'ok',
+    tool_name: AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
+    session_id: sessionId,
+    cleanup_status,
+    recovery_action,
+  };
+}
+
+interface AbortClassification {
+  cleanup_status: AgentRuntimeCleanupStatus;
+  recovery_action: string | null;
+}
+
+/**
+ * Decide cleanup_status per ADR-013 §1 abort table.
+ *
+ * - Fresh/unused session state → 'clean'; no mutations occurred.
+ * - Paused session with ≥1 inflight approval → 'needs_recovery'; state
+ *   may be inconsistent because an approval was mid-flight when pause
+ *   landed and the operator ordered an abort on top.
+ * - Either "paused" OR "inflight approvals" alone → 'partial'; the
+ *   session is self-consistent but has uncommitted work.
+ */
+function classifyAbort(state: {
+  pause: { paused: boolean };
+  inflight_approvals: readonly unknown[];
+}): AbortClassification {
+  const hasInflight = state.inflight_approvals.length > 0;
+  const isPaused = state.pause.paused;
+
+  if (!hasInflight && !isPaused) {
+    return { cleanup_status: 'clean', recovery_action: null };
+  }
+  if (hasInflight && isPaused) {
+    return {
+      cleanup_status: 'needs_recovery',
+      recovery_action:
+        'Run `pnpm wu:recover --session ${session}` to reconcile the paused session with pending approval state.',
+    };
+  }
+  if (hasInflight) {
+    return {
+      cleanup_status: 'partial',
+      recovery_action:
+        'Review inflight approvals in the conductor UI; re-run `wu:prep` after the approval is cleared.',
+    };
+  }
+  return {
+    cleanup_status: 'partial',
+    recovery_action:
+      'Session was paused when the abort landed; review the paused continuation before resuming.',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// elevate_autonomy / lower_autonomy
+// ---------------------------------------------------------------------------
+
+function autonomyIndex(level: AgentRuntimeAutonomyLevel): number {
+  return AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES.indexOf(level);
+}
+
+function nextAutonomyLevel(
+  current: AgentRuntimeAutonomyLevel,
+  direction: 'elevate' | 'lower',
+): AgentRuntimeAutonomyLevel {
+  const index = autonomyIndex(current);
+  const delta = direction === 'elevate' ? 1 : -1;
+  const candidate = index + delta;
+  if (candidate < 0 || candidate >= AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES.length) {
+    return current;
+  }
+  return AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES[candidate] ?? current;
+}
+
+async function transitionAutonomy(
+  toolName: AgentRuntimeRemoteControlToolName,
+  direction: 'elevate' | 'lower',
+  input: RemoteControlInvocationInput & { reason?: string | null },
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  const sessionId = requireSessionId(toolName, input.session_id);
+  const now = ctx.now();
+  const state = await ctx.store.loadOrDefault(sessionId, now);
+  const previousLevel = state.autonomy_level;
+  const newLevel = nextAutonomyLevel(previousLevel, direction);
+  await ctx.store.save({
+    ...state,
+    autonomy_level: newLevel,
+    updated_at: now,
+  });
+
+  // §6 governance — record BOTH autonomy_changed AND tool_called.
+  emitAgentRuntimeEvent(
+    ctx.eventSink,
+    buildAutonomyChangedEvent({
+      session_id: sessionId,
+      previous_level: previousLevel,
+      new_level: newLevel,
+      direction,
+      reason: typeof input.reason === 'string' ? input.reason : null,
+    }),
+  );
+  emitToolCalled(ctx, toolName, sessionId);
+
+  return {
+    status: 'ok',
+    tool_name: toolName,
+    session_id: sessionId,
+  };
+}
+
+export async function elevateAutonomy(
+  input: RemoteControlInvocationInput & { reason?: string | null },
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  return transitionAutonomy(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY,
+    'elevate',
+    input,
+    ctx,
+  );
+}
+
+export async function lowerAutonomy(
+  input: RemoteControlInvocationInput & { reason?: string | null },
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  return transitionAutonomy(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY,
+    'lower',
+    input,
+    ctx,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// approve_inflight
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves the oldest pending in-flight approval for a session. The
+ * approval queue lives inside RemoteControlSessionState; workflow-level
+ * approval gating remains the orchestration module's responsibility —
+ * this tool only clears the queue entry so the workflow observer sees
+ * the approval as satisfied.
+ *
+ * If there are no pending approvals, we still emit tool_called and
+ * return `status: 'ok'` — the operator's click is auditable even when
+ * it was a no-op race against an auto-resolved approval.
+ */
+export async function approveInflight(
+  input: RemoteControlInvocationInput,
+  ctx: RemoteControlOperationContext,
+): Promise<RemoteControlInvocationResult> {
+  const sessionId = requireSessionId(
+    AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT,
+    input.session_id,
+  );
+  const now = ctx.now();
+  const state = await ctx.store.loadOrDefault(sessionId, now);
+  const [, ...remaining] = state.inflight_approvals;
+  await ctx.store.save({
+    ...state,
+    inflight_approvals: remaining,
+    updated_at: now,
+  });
+  emitToolCalled(ctx, AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT, sessionId);
+  return {
+    status: 'ok',
+    tool_name: AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT,
+    session_id: sessionId,
+  };
+}
+
+export { AGENT_RUNTIME_AUTONOMY_LEVELS };

package/packs/agent-runtime/remote-controls/port.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// WU-2732 (INIT-060 Phase 3, ADR-013 §6 governance surface):
+// Port interface for the six remote-control tools. Both the mock
+// tracer-bullet adapter (this WU) and the real kernel-side adapter
+// (WU-2733) implement this port — so the real impl lands without
+// changing the wire contract. This mirrors ADR-013's ChannelBridge
+// port pattern (single port, multiple adapters).
+
+import type { AbortTurnInvocationResult, RemoteControlInvocationResult } from './types.js';
+
+/**
+ * Minimum input shape every remote-control tool accepts. The session
+ * identifier is the load-bearing field: it pins which agent-runtime
+ * session the command targets. Real impls in WU-2733 will extend this
+ * with per-tool specific fields (e.g. autonomy level for elevate);
+ * extensions MUST be additive to preserve the wire contract.
+ */
+export interface RemoteControlInvocationInput {
+  session_id?: string;
+}
+
+export interface AbortTurnInvocationInput extends RemoteControlInvocationInput {
+  /**
+   * Operator-supplied reason surfaced in the emitted
+   * `agent-runtime:turn_aborted` event in the real impl. The mock
+   * tracer-bullet records this for round-trip verification but does
+   * not emit the event (WU-2733 wires the real emission per
+   * ADR-013 §1 abort table).
+   */
+  reason?: string;
+}
+
+/**
+ * Remote-control port. The six methods correspond 1:1 to the six
+ * manifest-declared tool names. Keeping them as separate methods (not
+ * a single `invoke(name, input)` dispatcher) lets TypeScript enforce
+ * per-tool input/output types at the call site.
+ */
+export interface RemoteControlPort {
+  resumeWorkflow(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
+  pauseTurn(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
+  abortTurn(input: AbortTurnInvocationInput): Promise<AbortTurnInvocationResult>;
+  elevateAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
+  lowerAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
+  approveInflight(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
+}

package/packs/agent-runtime/remote-controls/state-store.ts

@@ -0,0 +1,258 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// WU-2733 (INIT-060 Phase 3, ADR-013 §1 abort + §6 governance):
+// Sidecar persistence for remote-control session state (pause marker,
+// autonomy level, abort record, inflight approval handle). Kept
+// separate from the core orchestration workflow state store so the
+// existing strict schema validator doesn't need schema-version bumps
+// and so remote-control operations remain independently observable
+// via a dedicated on-disk artefact (`.agent-runtime/remote-controls/`).
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const REMOTE_CONTROL_STATE_DIRECTORY = path.join('.agent-runtime', 'remote-controls');
+
+/** Canonical autonomy bands. Declaration order = low→high. */
+export const AGENT_RUNTIME_AUTONOMY_LEVELS = {
+  MANUAL: 'manual',
+  ASSISTED: 'assisted',
+  AUTO: 'auto',
+} as const;
+
+export type AgentRuntimeAutonomyLevel =
+  (typeof AGENT_RUNTIME_AUTONOMY_LEVELS)[keyof typeof AGENT_RUNTIME_AUTONOMY_LEVELS];
+
+export const AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES = [
+  AGENT_RUNTIME_AUTONOMY_LEVELS.MANUAL,
+  AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED,
+  AGENT_RUNTIME_AUTONOMY_LEVELS.AUTO,
+] as const satisfies readonly AgentRuntimeAutonomyLevel[];
+
+export const DEFAULT_AUTONOMY_LEVEL: AgentRuntimeAutonomyLevel =
+  AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED;
+
+export interface RemoteControlPauseState {
+  paused: boolean;
+  paused_at: string | null;
+  resumed_at: string | null;
+  reason: string | null;
+}
+
+export interface RemoteControlAbortState {
+  aborted: boolean;
+  aborted_at: string | null;
+  cleanup_status: 'clean' | 'partial' | 'needs_recovery' | null;
+  recovery_action: string | null;
+  reason: string | null;
+}
+
+export interface RemoteControlInflightApproval {
+  request_id: string;
+  tool_name: string;
+  requested_at: string;
+}
+
+export interface RemoteControlSessionState {
+  schema_version: 1;
+  session_id: string;
+  autonomy_level: AgentRuntimeAutonomyLevel;
+  pause: RemoteControlPauseState;
+  abort: RemoteControlAbortState;
+  inflight_approvals: RemoteControlInflightApproval[];
+  updated_at: string;
+}
+
+const SCHEMA_VERSION_V1 = 1 as const;
+
+export interface RemoteControlStateStore {
+  load(sessionId: string): Promise<RemoteControlSessionState | null>;
+  save(state: RemoteControlSessionState): Promise<void>;
+  loadOrDefault(sessionId: string, now: string): Promise<RemoteControlSessionState>;
+}
+
+export interface CreateRemoteControlStateStoreInput {
+  workspaceRoot: string;
+}
+
+export function createRemoteControlStateStore(
+  input: CreateRemoteControlStateStoreInput,
+): RemoteControlStateStore {
+  const stateRoot = path.join(input.workspaceRoot, REMOTE_CONTROL_STATE_DIRECTORY);
+
+  async function load(sessionId: string): Promise<RemoteControlSessionState | null> {
+    const filePath = sessionFile(stateRoot, sessionId);
+    try {
+      const raw = await readFile(filePath, 'utf8');
+      return parseState(JSON.parse(raw), filePath);
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async function save(state: RemoteControlSessionState): Promise<void> {
+    const filePath = sessionFile(stateRoot, state.session_id);
+    await mkdir(stateRoot, { recursive: true });
+    await writeFile(filePath, JSON.stringify(state), 'utf8');
+  }
+
+  async function loadOrDefault(sessionId: string, now: string): Promise<RemoteControlSessionState> {
+    const existing = await load(sessionId);
+    if (existing) {
+      return existing;
+    }
+    return buildDefaultState(sessionId, now);
+  }
+
+  return { load, save, loadOrDefault };
+}
+
+export function buildDefaultState(sessionId: string, now: string): RemoteControlSessionState {
+  return {
+    schema_version: SCHEMA_VERSION_V1,
+    session_id: sessionId,
+    autonomy_level: DEFAULT_AUTONOMY_LEVEL,
+    pause: {
+      paused: false,
+      paused_at: null,
+      resumed_at: null,
+      reason: null,
+    },
+    abort: {
+      aborted: false,
+      aborted_at: null,
+      cleanup_status: null,
+      recovery_action: null,
+      reason: null,
+    },
+    inflight_approvals: [],
+    updated_at: now,
+  };
+}
+
+function sessionFile(stateRoot: string, sessionId: string): string {
+  return path.join(stateRoot, `${sessionId}.json`);
+}
+
+function parseState(value: unknown, filePath: string): RemoteControlSessionState {
+  if (value === null || typeof value !== 'object') {
+    throw new Error(
+      `Failed to parse remote-control state at ${filePath}: expected an object payload.`,
+    );
+  }
+  const record = value as Record<string, unknown>;
+  if (record.schema_version !== SCHEMA_VERSION_V1) {
+    throw new Error(
+      `Failed to parse remote-control state at ${filePath}: unsupported schema_version "${String(record.schema_version)}".`,
+    );
+  }
+  const sessionId = requireString(record.session_id, `${filePath}.session_id`);
+  const autonomyLevel = requireAutonomyLevel(record.autonomy_level, `${filePath}.autonomy_level`);
+  const pause = parsePauseState(record.pause, `${filePath}.pause`);
+  const abort = parseAbortState(record.abort, `${filePath}.abort`);
+  const inflightApprovals = parseInflightApprovals(
+    record.inflight_approvals,
+    `${filePath}.inflight_approvals`,
+  );
+  const updatedAt = requireString(record.updated_at, `${filePath}.updated_at`);
+  return {
+    schema_version: SCHEMA_VERSION_V1,
+    session_id: sessionId,
+    autonomy_level: autonomyLevel,
+    pause,
+    abort,
+    inflight_approvals: inflightApprovals,
+    updated_at: updatedAt,
+  };
+}
+
+function parsePauseState(value: unknown, filePath: string): RemoteControlPauseState {
+  if (value === null || typeof value !== 'object') {
+    throw new Error(`Failed to parse remote-control state at ${filePath}: expected pause object.`);
+  }
+  const record = value as Record<string, unknown>;
+  return {
+    paused: typeof record.paused === 'boolean' ? record.paused : false,
+    paused_at: typeof record.paused_at === 'string' ? record.paused_at : null,
+    resumed_at: typeof record.resumed_at === 'string' ? record.resumed_at : null,
+    reason: typeof record.reason === 'string' ? record.reason : null,
+  };
+}
+
+function parseAbortState(value: unknown, filePath: string): RemoteControlAbortState {
+  if (value === null || typeof value !== 'object') {
+    throw new Error(`Failed to parse remote-control state at ${filePath}: expected abort object.`);
+  }
+  const record = value as Record<string, unknown>;
+  const cleanupStatus = record.cleanup_status;
+  return {
+    aborted: typeof record.aborted === 'boolean' ? record.aborted : false,
+    aborted_at: typeof record.aborted_at === 'string' ? record.aborted_at : null,
+    cleanup_status:
+      cleanupStatus === 'clean' || cleanupStatus === 'partial' || cleanupStatus === 'needs_recovery'
+        ? cleanupStatus
+        : null,
+    recovery_action: typeof record.recovery_action === 'string' ? record.recovery_action : null,
+    reason: typeof record.reason === 'string' ? record.reason : null,
+  };
+}
+
+function parseInflightApprovals(value: unknown, filePath: string): RemoteControlInflightApproval[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry, index) => parseInflightApproval(entry, `${filePath}[${index}]`))
+    .filter((entry): entry is RemoteControlInflightApproval => entry !== null);
+}
+
+function parseInflightApproval(
+  value: unknown,
+  filePath: string,
+): RemoteControlInflightApproval | null {
+  if (value === null || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.request_id !== 'string' ||
+    typeof record.tool_name !== 'string' ||
+    typeof record.requested_at !== 'string'
+  ) {
+    throw new Error(
+      `Failed to parse remote-control state at ${filePath}: malformed inflight approval entry.`,
+    );
+  }
+  return {
+    request_id: record.request_id,
+    tool_name: record.tool_name,
+    requested_at: record.requested_at,
+  };
+}
+
+function requireString(value: unknown, filePath: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `Failed to parse remote-control state at ${filePath}: expected a non-empty string.`,
+    );
+  }
+  return value;
+}
+
+function requireAutonomyLevel(value: unknown, filePath: string): AgentRuntimeAutonomyLevel {
+  if (
+    value === AGENT_RUNTIME_AUTONOMY_LEVELS.MANUAL ||
+    value === AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED ||
+    value === AGENT_RUNTIME_AUTONOMY_LEVELS.AUTO
+  ) {
+    return value;
+  }
+  throw new Error(
+    `Failed to parse remote-control state at ${filePath}: unknown autonomy level "${String(value)}".`,
+  );
+}