oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/host-service/routec-matrix-storage-adapter.mjs

@@ -13,6 +13,7 @@ import {
 } from "fs";
 import { basename, dirname, join } from "path";
 import { homedir } from "os";
+import { routeCMatrixJsonStoragePath } from "./routec-matrix-storage-paths.mjs";
 import {
   getRouteCMatrixActorByKey,
   getRouteCMatrixActorByUserId,
@@ -26,14 +27,20 @@ import {
 } from "./tool-event-transfer-projection.mjs";
 import { ROUTEC_TOOL_EVENT_DETAIL_SELECTED_DETAIL_LIMIT_BYTES } from "./tool-event-detail-store.mjs";
 import { readCompletedTurnFinalMessageNeighborsFromSQLite } from "./completed-turn-navigation.mjs";
+import {
+  decorateMatrixEventsWithCompletedTurnProjection,
+  MATRIX_COMPLETED_TURN_PROJECTION_KEY,
+} from "./completed-turn-service.mjs";
 import {
   MATRIX_SQLITE_SCHEMA_VERSION,
+  routeCMatrixSQLiteRoomReadContextDB,
   exportSQLiteStoreObject,
   getLastRouteCMatrixSQLiteMigrationProof,
   getRouteCMatrixSQLiteStorageHealth,
   getRouteCMatrixSQLiteStoragePath,
   insertRouteCMatrixSQLiteTxnMapping,
   openRouteCMatrixSQLiteStore,
+  openRouteCMatrixSQLiteReadOnlyStore,
   readRouteCMatrixSQLiteContiguousSemanticEvents,
   readRouteCMatrixSQLiteContextWindow,
   readRouteCMatrixSQLiteCurrentStateSince,
@@ -45,6 +52,7 @@ import {
   readRouteCMatrixSQLiteMessagesWindow,
   readRouteCMatrixSQLiteLatestPreviewRows,
   readRouteCMatrixSQLiteLatestTimelineSeq,
+  readRouteCMatrixSQLiteLatestTimelineSeqs,
   readRouteCMatrixSQLiteNextStreamSeq,
   readRouteCMatrixSQLiteRoom,
   readRouteCMatrixSQLiteStateEvent,
@@ -904,16 +912,8 @@ function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function stackRootFromConfigDir() {
-  return basename(CONFIG_DIR) === "host" ? dirname(CONFIG_DIR) : CONFIG_DIR;
-}
-
 export function getRouteCMatrixStoragePath() {
-  const configured = process.env.OYSTERUN_ROUTEC_MATRIX_STORAGE_PATH;
-  if (typeof configured === "string" && configured.trim()) {
-    return configured.trim();
-  }
-  return join(stackRootFromConfigDir(), "matrix", "homeserver.db");
+  return routeCMatrixJsonStoragePath(CONFIG_DIR, process.env.OYSTERUN_ROUTEC_MATRIX_STORAGE_PATH);
 }
 
 export function getRouteCMatrixStorageDeltaPath(
@@ -2292,7 +2292,37 @@ function ensureRoomInStore(store, binding) {
   return room;
 }
 
+const transcriptReadOnlyScope = new AsyncLocalStorage();
+
+// Synchronous adapter consumers share one read-only DB and one bound room.
+// No cached writable opener, schema initializer, or room creator is used.
+export function withRouteCMatrixTranscriptReadOnly({ binding }, read) {
+  requireBinding(binding);
+  const db = openRouteCMatrixSQLiteReadOnlyStore({ jsonStoragePath: getRouteCMatrixStoragePath() });
+  try {
+    const room = readRouteCMatrixSQLiteRoom(db, { roomId: binding.matrix_room_id });
+    if (!room) {
+      const error = new Error("Durable Matrix transcript room is unavailable");
+      error.code = "MATRIX_TRANSCRIPT_ROOM_UNAVAILABLE";
+      throw error;
+    }
+    if (room.host_session_id !== binding.host_session_id || room.host_agent_id !== binding.host_agent_id) {
+      const error = new Error("Durable Matrix transcript room ownership does not match binding");
+      error.code = "MATRIX_TRANSCRIPT_BINDING_MISMATCH";
+      throw error;
+    }
+    validateBoundRoomRecord(room, binding);
+    return transcriptReadOnlyScope.run({ db, roomId: binding.matrix_room_id }, () => {
+      const result = read();
+      if (result?.then) throw new Error("Transcript read-only scope requires synchronous reads");
+      return result;
+    });
+  } finally { db.close(); }
+}
+
 function openRouteCMatrixAdapterSQLiteStore() {
+  const scope = transcriptReadOnlyScope.getStore();
+  if (scope) return scope.db;
   return openRouteCMatrixSQLiteStore({
     jsonStoragePath: getRouteCMatrixStoragePath(),
   });
@@ -2426,12 +2456,14 @@ export function getRouteCMatrixRoomTimelineReplaySourceProof({
   };
 }
 
-export function readRouteCMatrixRoomLatestPreviewCheckpoint({ binding }) {
+export function readRouteCMatrixRoomLatestPreviewCheckpoint({ binding, readContext = null }) {
   requireBinding(binding);
-  const db = openRouteCMatrixAdapterSQLiteStore();
+  const db = readContext === null ? openRouteCMatrixAdapterSQLiteStore()
+    : routeCMatrixSQLiteRoomReadContextDB(readContext, binding.matrix_room_id);
   return {
     latest_committed_seq: readRouteCMatrixSQLiteLatestTimelineSeq(db, {
       roomId: binding.matrix_room_id,
+      readContext,
     }),
     dedicated_preview_query: true,
     full_transcript_pagination_used: false,
@@ -2440,11 +2472,29 @@ export function readRouteCMatrixRoomLatestPreviewCheckpoint({ binding }) {
   };
 }
 
-export function readRouteCMatrixRoomLatestPreviewRows({ binding, limit = 20 }) {
-  requireBinding(binding);
+export function readRouteCMatrixRoomLatestPreviewCheckpoints({ bindings }) {
+  const selected = [];
+  const seen = new Set();
+  for (const binding of Array.isArray(bindings) ? bindings : []) {
+    requireBinding(binding);
+    if (!seen.has(binding.matrix_room_id)) {
+      seen.add(binding.matrix_room_id);
+      selected.push(binding);
+    }
+  }
   const db = openRouteCMatrixAdapterSQLiteStore();
+  return readRouteCMatrixSQLiteLatestTimelineSeqs(db, {
+    roomIds: selected.map((binding) => binding.matrix_room_id),
+  });
+}
+
+export function readRouteCMatrixRoomLatestPreviewRows({ binding, limit = 20, readContext = null }) {
+  requireBinding(binding);
+  const db = readContext === null ? openRouteCMatrixAdapterSQLiteStore()
+    : routeCMatrixSQLiteRoomReadContextDB(readContext, binding.matrix_room_id);
   const rows = readRouteCMatrixSQLiteLatestPreviewRows(db, {
     roomId: binding.matrix_room_id,
+    readContext,
     limit,
   });
   return {
@@ -2477,7 +2527,11 @@ export function readRouteCMatrixRoomTimelinePreview({
   });
   const countLimited = candidates.length > normalizedLimit;
   const preBudgetChunk = candidates.slice(0, normalizedLimit).reverse();
-  const preBudgetClientEvents = preBudgetChunk.map(eventForClientMatrixRead);
+  const preBudgetClientEvents = eventsForClientMatrixRead(
+    db,
+    preBudgetChunk,
+    binding
+  );
   const budgeted = selectNewestClientEventsWithinTransferBudget({
     rawEvents: preBudgetChunk,
     clientEvents: preBudgetClientEvents,
@@ -3335,6 +3389,100 @@ function eventForClientMatrixRead(event) {
   return clientEvent;
 }
 
+function eventsForClientMatrixRead(db, events, binding) {
+  const clientEvents = events.map(eventForClientMatrixRead);
+  return decorateMatrixEventsWithCompletedTurnProjection(db, clientEvents, {
+    roomId: binding.matrix_room_id,
+    hostSessionId: binding.host_session_id,
+    getSession: (sessionId) =>
+      sessionId === binding.host_session_id
+        ? {
+            id: binding.host_session_id,
+            sessionName: binding.host_session_name,
+          }
+        : null,
+  });
+}
+
+function parseMatrixObject(value) {
+  if (isObject(value)) return value;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return isObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function completedAssistantRecoveryEventIds(clientEvents) {
+  const loadedEventIds = new Set(
+    clientEvents
+      .map((event) => normalizeNonEmptyString(event?.event_id))
+      .filter(Boolean)
+  );
+  const recoveryEventIds = [];
+  for (const event of clientEvents) {
+    const unsigned = parseMatrixObject(event?.unsigned);
+    const projection = unsigned[MATRIX_COMPLETED_TURN_PROJECTION_KEY];
+    if (
+      !isObject(projection) ||
+      projection.schema !== "local_turn_completion.v1" ||
+      projection.successful !== true ||
+      projection.conflict === true
+    ) {
+      continue;
+    }
+    const eventId = normalizeNonEmptyString(projection.final_assistant_event_id);
+    if (!eventId || loadedEventIds.has(eventId)) continue;
+    loadedEventIds.add(eventId);
+    recoveryEventIds.push(eventId);
+  }
+  return recoveryEventIds;
+}
+
+function recoverCompletedAssistantSyncCompanions({
+  db,
+  binding,
+  rawEvents,
+  clientEvents,
+}) {
+  const recoveredRawEvents = [];
+  for (const eventId of completedAssistantRecoveryEventIds(clientEvents)) {
+    const event = readRouteCMatrixSQLiteEvent(db, {
+      roomId: binding.matrix_room_id,
+      eventId,
+    });
+    const content = parseMatrixObject(event?.content_json ?? event?.content);
+    const semantic = content[OYSTERUN_SEMANTIC_NAMESPACE];
+    if (
+      !event ||
+      event.type !== "m.room.message" ||
+      !isObject(semantic) ||
+      semantic.semantic_type !== "message.assistant" ||
+      content.delta === true
+    ) {
+      continue;
+    }
+    recoveredRawEvents.push(event);
+  }
+  if (recoveredRawEvents.length === 0) {
+    return { rawEvents, clientEvents, recoveredCount: 0 };
+  }
+  const byEventId = new Map();
+  for (const event of [...rawEvents, ...recoveredRawEvents]) {
+    byEventId.set(event.event_id, event);
+  }
+  const mergedRawEvents = [...byEventId.values()].sort(
+    (left, right) => eventStreamSeq(left) - eventStreamSeq(right)
+  );
+  return {
+    rawEvents: mergedRawEvents,
+    clientEvents: eventsForClientMatrixRead(db, mergedRawEvents, binding),
+    recoveredCount: mergedRawEvents.length - rawEvents.length,
+  };
+}
+
 function summarizeClientTransferBytes(clientEvents) {
   const eventByteCounts = clientEvents
     .map((event) => safeJsonByteLength(event))
@@ -4199,6 +4347,8 @@ function selectMessagesChunk({ events, startSeq, toSeq, direction, limit }) {
 }
 
 function applyMessagesTransferBudgetToWindow({
+  db,
+  binding,
   chunk,
   countLimited,
   startSeq,
@@ -4206,7 +4356,7 @@ function applyMessagesTransferBudgetToWindow({
   direction,
   budgetBytes = P135_MATRIX_CLIENT_TRANSFER_BUDGET_BYTES,
 }) {
-  const clientEvents = chunk.map(eventForClientMatrixRead);
+  const clientEvents = eventsForClientMatrixRead(db, chunk, binding);
   const selectedRaw = [];
   const selectedClient = [];
   const selectedByteCounts = [];
@@ -4392,6 +4542,10 @@ function clientTransferBudgetProof({
     messages_gap_fill_direction: timeline.limited ? "b" : null,
     p117_current_since_long_poll_preserved: true,
     p131_projection_boundary_preserved: true,
+    completed_assistant_recovery_count:
+      transferBudget?.completedAssistantRecoveryCount ?? 0,
+    completed_assistant_recovery_contract:
+      "successful_completed_turn_final_assistant_companion_v1",
     p82_large_tool_spillover_boundary_preserved: true,
     foundation_pass_claimed: false,
   };
@@ -4461,15 +4615,41 @@ function buildSyncBody({
     sinceSeq,
     limited: sqliteTimeline.limited,
   });
-  const initialClientTimelineEvents = initialTimeline.events.map(eventForClient);
-  const {
-    timeline,
-    clientEvents: clientTimelineEvents,
-    transferBudget,
-  } = applyTransferBudgetToSyncTimeline({
+  const initialClientTimelineEvents = eventsForClientMatrixRead(
+    db,
+    initialTimeline.events,
+    binding
+  );
+  const budgetedTimeline = applyTransferBudgetToSyncTimeline({
     timeline: initialTimeline,
     clientEvents: initialClientTimelineEvents,
   });
+  const completionRecovery = recoverCompletedAssistantSyncCompanions({
+    db,
+    binding,
+    rawEvents: budgetedTimeline.timeline.events,
+    clientEvents: budgetedTimeline.clientEvents,
+  });
+  const timeline =
+    completionRecovery.recoveredCount > 0
+      ? {
+          ...budgetedTimeline.timeline,
+          events: completionRecovery.rawEvents,
+          oldestReturnedSeq: eventSeqOrNull(completionRecovery.rawEvents[0]),
+          newestReturnedSeq: eventSeqOrNull(
+            completionRecovery.rawEvents.at(-1)
+          ),
+          prevBatchSeq:
+            eventSeqOrNull(completionRecovery.rawEvents[0]) ??
+            budgetedTimeline.timeline.prevBatchSeq,
+          budgetMode: `${budgetedTimeline.timeline.budgetMode}_completed_assistant_recovery`,
+        }
+      : budgetedTimeline.timeline;
+  const clientTimelineEvents = completionRecovery.clientEvents;
+  const transferBudget = {
+    ...budgetedTimeline.transferBudget,
+    completedAssistantRecoveryCount: completionRecovery.recoveredCount,
+  };
   const memberships = roomMembershipEvents(binding, room);
   const stateEvents = sinceSeq === null
     ? roomStateEvents(binding, room)
@@ -4595,7 +4775,7 @@ function readEvent({ binding, eventId }) {
   if (!event) {
     return null;
   }
-  return eventForClient(event);
+  return eventsForClientMatrixRead(db, [event], binding)[0];
 }
 
 export function readRouteCMatrixEvent({ binding, eventId }) {
@@ -4630,6 +4810,8 @@ export function readRouteCMatrixRoomMessages({
     limit: normalizedLimit,
   });
   const selected = applyMessagesTransferBudgetToWindow({
+    db,
+    binding,
     chunk: window.chunk,
     countLimited: window.countLimited,
     startSeq,
@@ -4771,9 +4953,9 @@ export function readRouteCMatrixRoomContext({
     start,
     end,
     state: roomStateEvents(binding, room),
-    events_before: beforeRaw.map(eventForClientMatrixRead),
-    events_after: afterRaw.map(eventForClientMatrixRead),
-    event: eventForClientMatrixRead(targetEvent),
+    events_before: eventsForClientMatrixRead(db, beforeRaw, binding),
+    events_after: eventsForClientMatrixRead(db, afterRaw, binding),
+    event: eventsForClientMatrixRead(db, [targetEvent], binding)[0],
     ...(diagnosticsEnabled
       ? {
           routec_context_focus_proof: {
@@ -4914,6 +5096,7 @@ export async function handleRouteCMatrixStorageRequest({
 }) {
   const effectiveBinding = binding || {
     host_session_id: tokenRecord?.host_session_id,
+    host_session_name: tokenRecord?.host_session_name,
     host_agent_id: tokenRecord?.host_agent_id,
     matrix_room_id: tokenRecord?.matrix_room_id,
     matrix_user_id: tokenRecord?.matrix_user_id,

package/host-service/routec-matrix-storage-paths.mjs

@@ -0,0 +1,12 @@
+import { basename, dirname, join } from "node:path";
+
+// Pure path contract shared by storage and lifecycle ownership inspection.
+export function routeCMatrixJsonStoragePath(configDir, configuredPath) {
+  if (typeof configuredPath === "string" && configuredPath.trim()) return configuredPath.trim();
+  const stackRoot = basename(configDir) === "host" ? dirname(configDir) : configDir;
+  return join(stackRoot, "matrix", "homeserver.db");
+}
+
+export function routeCMatrixSQLiteStoragePath(jsonStoragePath) {
+  return join(dirname(jsonStoragePath), "homeserver.sqlite");
+}

package/host-service/routec-request-delay-window.mjs

@@ -0,0 +1,55 @@
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+
+export function createRouteCRequestDelayWindowController({
+  createMonitor = () => monitorEventLoopDelay({ resolution: 10 }),
+  now = () => new Date(),
+  performanceNow = () => performance.now(),
+} = {}) {
+  let activeWindow = null;
+
+  function sync(logPath) {
+    if (!logPath) {
+      activeWindow?.monitor.disable();
+      activeWindow = null;
+      return null;
+    }
+    if (activeWindow?.logPath === logPath) return activeWindow;
+
+    activeWindow?.monitor.disable();
+    const monitor = createMonitor();
+    monitor.enable();
+    activeWindow = {
+      logPath,
+      monitor,
+      startedAt: now(),
+      startedPerformanceMs: performanceNow(),
+    };
+    return activeWindow;
+  }
+
+  function snapshot(window = activeWindow) {
+    if (!window) return null;
+    const count = window.monitor.count;
+    const milliseconds = (nanoseconds) =>
+      count > 0 && Number.isFinite(nanoseconds)
+        ? Number((nanoseconds / 1_000_000).toFixed(3))
+        : null;
+    return {
+      monitor: "node_perf_hooks_monitor_event_loop_delay",
+      resolution_ms: 10,
+      window_started_at: window.startedAt.toISOString(),
+      window_elapsed_ms: Number(
+        (performanceNow() - window.startedPerformanceMs).toFixed(3)
+      ),
+      samples: count,
+      min_ms: milliseconds(window.monitor.min),
+      max_ms: milliseconds(window.monitor.max),
+      mean_ms: milliseconds(window.monitor.mean),
+      p50_ms: milliseconds(window.monitor.percentile(50)),
+      p95_ms: milliseconds(window.monitor.percentile(95)),
+      p99_ms: milliseconds(window.monitor.percentile(99)),
+    };
+  }
+
+  return { sync, snapshot };
+}

package/host-service/scheduler-acp-provider-runner.mjs

@@ -2,8 +2,9 @@ import { randomUUID } from "crypto";
 import { ClaudeCodeAdapter } from "./adapters/claude-code-adapter.mjs";
 import { readConfig } from "./config.mjs";
 import { getConfiguredProviderCommand } from "./provider-registry.mjs";
+import { DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS } from "./scheduler-run-timeout-policy.mjs";
 
-const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS * 1000;
 const DEFAULT_GRACEFUL_EXIT_MS = 5_000;
 const DEFAULT_FORCED_EXIT_MS = 2_000;
 const MAX_CAPTURE_CHARS = 24_000;

package/host-service/scheduler-direct-provider-runner.mjs

@@ -8,8 +8,12 @@ import {
   getConfiguredProviderCommand,
   isConfiguredCommandAvailable,
 } from "./provider-registry.mjs";
+import { DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS } from "./scheduler-run-timeout-policy.mjs";
 
-const DEFAULT_SCHEDULER_DIRECT_RUN_TIMEOUT_MS = 30 * 60 * 1000;
+const DEFAULT_SCHEDULER_DIRECT_RUN_TIMEOUT_MS =
+  DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS * 1000;
+const DEFAULT_GRACEFUL_EXIT_MS = 5_000;
+const DEFAULT_FORCED_EXIT_MS = 2_000;
 const MAX_CAPTURE_CHARS = 24_000;
 const MAX_SUMMARY_CHARS = 700;
 
@@ -208,6 +212,9 @@ export async function runSchedulerDirectProviderCommand({
   redactionValues = [],
   spawnFn = spawn,
   timeoutMs = DEFAULT_SCHEDULER_DIRECT_RUN_TIMEOUT_MS,
+  gracefulExitMs = DEFAULT_GRACEFUL_EXIT_MS,
+  forcedExitMs = DEFAULT_FORCED_EXIT_MS,
+  signal: abortSignal = null,
 } = {}) {
   const provider = requireString(runtime?.provider, "provider");
   const resolvedCwd = requireString(cwd, "cwd");
@@ -227,12 +234,15 @@ export async function runSchedulerDirectProviderCommand({
     let stdoutTruncated = false;
     let stderrTruncated = false;
     let settled = false;
+    let terminalReason = null;
+    let childExited = false;
     let timeout = null;
     let child;
     const finish = (result) => {
       if (settled) return;
       settled = true;
       if (timeout) clearTimeout(timeout);
+      abortSignal?.removeEventListener?.("abort", onAbort);
       const safeStdout = redactText(stdout, redactionTokens);
       const safeStderr = redactText(stderr, redactionTokens);
       resolve({
@@ -248,6 +258,11 @@ export async function runSchedulerDirectProviderCommand({
         stdout_truncated: stdoutTruncated,
         stderr_truncated: stderrTruncated,
         redacted_sensitive_env: redactionTokens.length > 0,
+        lifecycle_state: result.ok
+          ? "succeeded"
+          : result.error_summary || result.signal || "failed",
+        provider_process_exited: childExited,
+        provider_force_killed: result.provider_force_killed === true,
         log_summary: buildSummary({
           commandLabel,
           exitCode: result.exit_code,
@@ -257,6 +272,50 @@ export async function runSchedulerDirectProviderCommand({
         }),
       });
     };
+    const waitForExit = (waitMs) => {
+      if (childExited) return Promise.resolve(true);
+      return new Promise((resolve) => {
+        let done = false;
+        const complete = (value) => {
+          if (done) return;
+          done = true;
+          clearTimeout(waitTimer);
+          child?.off?.("close", onExit);
+          child?.off?.("exit", onExit);
+          resolve(value);
+        };
+        const onExit = () => complete(true);
+        const waitTimer = setTimeout(() => complete(childExited), waitMs);
+        child?.on?.("close", onExit);
+        child?.on?.("exit", onExit);
+      });
+    };
+    const terminate = async (reason) => {
+      if (settled || terminalReason) return;
+      terminalReason = reason;
+      child?.kill?.("SIGTERM");
+      let forceKilled = false;
+      let exited = await waitForExit(gracefulExitMs);
+      if (!exited) {
+        forceKilled = true;
+        child?.kill?.("SIGKILL");
+        exited = await waitForExit(forcedExitMs);
+      }
+      finish({
+        ok: false,
+        exit_code: null,
+        signal: reason === "timeout" ? "timeout" : "cancelled",
+        error_summary: exited
+          ? reason === "timeout"
+            ? "scheduler_provider_run_timed_out"
+            : "scheduler_provider_run_cancelled"
+          : "scheduler_provider_cleanup_failed",
+        provider_force_killed: forceKilled,
+      });
+    };
+    const onAbort = () => {
+      void terminate("cancelled");
+    };
     try {
       child = spawnFn(command, args, {
         cwd: resolvedCwd,
@@ -290,6 +349,8 @@ export async function runSchedulerDirectProviderCommand({
       reject(err);
     });
     child.on("close", (code, signal) => {
+      childExited = true;
+      if (terminalReason) return;
       finish({
         ok: code === 0,
         exit_code: typeof code === "number" ? code : null,
@@ -297,21 +358,22 @@ export async function runSchedulerDirectProviderCommand({
       });
     });
     child.on("exit", (code, signal) => {
+      childExited = true;
+      if (terminalReason) return;
       finish({
         ok: code === 0,
         exit_code: typeof code === "number" ? code : null,
         signal: signal || null,
       });
     });
-    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+    if (abortSignal?.aborted) {
+      onAbort();
+    } else {
+      abortSignal?.addEventListener?.("abort", onAbort, { once: true });
+    }
+    if (!terminalReason && Number.isFinite(timeoutMs) && timeoutMs > 0) {
       timeout = setTimeout(() => {
-        if (settled) return;
-        child.kill?.("SIGTERM");
-        finish({
-          ok: false,
-          exit_code: null,
-          signal: "timeout",
-        });
+        void terminate("timeout");
       }, timeoutMs);
       timeout.unref?.();
     }

package/host-service/scheduler-run-timeout-policy.mjs

@@ -0,0 +1,85 @@
+export const DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS = 60 * 60;
+export const MIN_SCHEDULER_RUN_TIMEOUT_SECONDS = 60;
+export const MAX_SCHEDULER_RUN_TIMEOUT_SECONDS = 24 * 60 * 60;
+
+function contractError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function normalizeSchedulerRunTimeoutSeconds(
+  value,
+  { fieldName = "run_timeout_seconds" } = {}
+) {
+  if (!Number.isInteger(value)) {
+    throw contractError(
+      "scheduler_run_timeout_invalid",
+      `${fieldName} must be a whole number of seconds`
+    );
+  }
+  if (
+    value < MIN_SCHEDULER_RUN_TIMEOUT_SECONDS ||
+    value > MAX_SCHEDULER_RUN_TIMEOUT_SECONDS
+  ) {
+    throw contractError(
+      "scheduler_run_timeout_out_of_range",
+      `${fieldName} must be between ${MIN_SCHEDULER_RUN_TIMEOUT_SECONDS} and ${MAX_SCHEDULER_RUN_TIMEOUT_SECONDS} seconds`
+    );
+  }
+  return value;
+}
+
+export function resolveSchedulerRunTimeout(
+  value,
+  { present = value !== undefined, source = null } = {}
+) {
+  if (!present) {
+    return {
+      seconds: DEFAULT_SCHEDULER_RUN_TIMEOUT_SECONDS,
+      source: source || "default_missing",
+      explicit: false,
+    };
+  }
+  const seconds = normalizeSchedulerRunTimeoutSeconds(value);
+  const normalizedSource = ["default", "default_missing"].includes(source)
+    ? source
+    : "explicit";
+  return {
+    seconds,
+    source: normalizedSource,
+    explicit: normalizedSource === "explicit",
+  };
+}
+
+export function parseSchedulerRunTimeoutDuration(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw contractError(
+      "scheduler_run_timeout_invalid",
+      "--run-timeout requires a finite duration such as 15m, 2h, or 3600s"
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (["unlimited", "none", "infinite", "infinity", "no-limit"].includes(normalized)) {
+    throw contractError(
+      "scheduler_run_timeout_unlimited_forbidden",
+      "Scheduler run timeout must be finite; unlimited is not supported"
+    );
+  }
+  const match = normalized.match(/^([0-9]+)(s|m|h)$/);
+  if (!match) {
+    throw contractError(
+      "scheduler_run_timeout_invalid",
+      "--run-timeout must be a whole-number duration using s, m, or h"
+    );
+  }
+  const amount = Number(match[1]);
+  const multiplier = match[2] === "h" ? 3600 : match[2] === "m" ? 60 : 1;
+  return normalizeSchedulerRunTimeoutSeconds(amount * multiplier, {
+    fieldName: "--run-timeout",
+  });
+}
+
+export function schedulerRunTimeoutMilliseconds(value, options = {}) {
+  return resolveSchedulerRunTimeout(value, options).seconds * 1000;
+}