Runtime Execution and Supervision
Dispatch-prompt construction, adapter routing and capability/fleet preflight, sandboxes, the runtime process runner with its Windows guardian, and supervision, recovery, settlement, usage capture, Tool Guard arming and shadow loop watchdog over native runtime events.
Depends on: Artifact Schemas (25), Mission Lifecycle and Artifact Store (20), Observability, Accounting and Reporting (6), Runtime Adapters and In-Runtime Extensions (5), Run Control and Team Coordination (5), Verification, Review and Promotion (3)
Used by: Runtime Adapters and In-Runtime Extensions (88), Observability, Accounting and Reporting (11), CLI Entry, Build and Project Tooling (9), Run Control and Team Coordination (8), Verification, Review and Promotion (5), Mission Lifecycle and Artifact Store (1), Mission Control TUI (1)
(Numbers are distinct file-to-file dependencies.)
| File | Summary | Key symbols |
|---|---|---|
src/harness/auto-route.ts |
Adapter auto-routing: deterministic Level 0 selection of the cheapest adapter satisfying mission runtime requirements, combined with a bounded Level 1 TypeSafe/JEV semantic recommendation, plus explain and summary formatters and decision receipts. | chooseAdapter, formatAutoRouteExplain, chooseSemanticRoute, formatSemanticRouteSummary |
src/harness/capabilities.ts |
Preflight capability enforcement that matches a mission’s required capability tags against the selected runtime adapter’s manifest, with error, warn, or off severity for run, dry-run, and run-all. | loadMissionFile, matchRuntimeCapabilities, formatCapabilityWarnLine, formatNoManifestWarnLine, formatCapabilityBypassLine, enforceCapabilities, assertRuntimeCapabilities |
src/harness/diff-capture.ts |
Shared diff capture helper for every runtime adapter that combines git diff with no-index diffs for untracked files, excluding harness bookkeeping, and retries transient git failures once. | execGit, diffCaptureFailureRecord, captureDiffWithUntracked |
src/harness/dispatch-context.ts |
Single shared builder for the pre-inlined mission dispatch prompt used by all runtime adapters, including the capped project brief, verified hive facts, workflow profile, and the final-message sentinel instruction. | capProjectFacts, loadProjectFacts, isProjectBriefEnabled, buildDispatchContext |
src/harness/fleet-policy.ts |
Fleet spend authorization that decides whether a model may run on a given adapter and role according to the project’s fleet policy, refusing runs before any process spawns. | decideFleetAdmission, assignedRoute, loadFleetPolicy, authorizedFleetAdapters, assertFleetAdmission |
src/harness/guard-arming.ts |
Pre-launch arming check for the tool guard that runs the runtime’s real hook against the run’s policy with two synthetic probes (an allowed read and a denied write), logging to a dedicated arm log and producing a policy stop receipt on failure. | defaultRunHookCommand, interpretSubprocessOutput, invokeSubprocessHook, invokeExtensionHook, readArmLog, armGuard, guardArmStopReceipt |
src/harness/loop-probe.ts |
Shadow-only loop probe that projects native event streams into a window of completed tool calls, computes deterministic loop signals, and asks a fixed question set of a provider without acting on the answer. | withForwardSlashes, relativeDisplayPath, firstPathValue, projectTarget, containsDenialText, projectStatus, projectActivity, deterministicLoopSignals, … |
src/harness/loop-watchdog.ts |
Shadow-only loop watchdog that periodically projects the native event stream, evaluates the loop probe, and records what it would have advised as advisory decision receipts without ever stopping a run. | toAnswers, resolveLoopWatchdogMode, createLoopWatchdog |
src/harness/native-tool-result.ts |
Decides whether a native tool-completion event reports a failure across runtime families, using structured error and exit fields before falling back to result text. | nativeToolFailure |
src/harness/render-prompt.ts |
Renders the canonical mission prompt text from a DispatchContext, preserving legacy section order and adding constraints, acceptance criteria and memory blocks. | renderPrompt |
src/harness/runtime-attempt.ts |
Claims an immutable runtime attempt identity by writing a marker in the run directory and best-effort registering the run in the project-root live-run registry. | claimRuntimeAttempt |
src/harness/runtime-command.ts |
Resolves how to invoke a runtime CLI so Node entrypoints and npm-installed shims run directly without passing arguments through cmd.exe on Windows. | resolveRuntimeCommand |
src/harness/runtime-config-overrides.ts |
Merges mission-level runtime_config_overrides with CLI-provided overrides (CLI wins) and parses the –runtime-config-overrides JSON flag with operator-friendly errors. | mergeRuntimeConfigOverrides, parseRuntimeConfigOverridesJson |
src/harness/runtime-events.ts |
Handles runtime cancellation artifacts: synchronously appends runtime.cancelled events and finalizes a cancelled run’s result, session, runs index and canonical mirrors with independent best-effort writes. | resolveRunId, readRuntimeSession, readRuntimeResult, appendRuntimeCancelledEvent, cancelledResult, cancelledSession, writeRunTerminalArtifacts, updateRunIndex, … |
src/harness/runtime-final-message.ts |
Defines the runtime-final-message capture protocol (UH-28): a prompt instruction asking the model to end with a tagged fenced block, and an extractor for the last such block. | runtimeFinalMessageInstruction, extractRuntimeFinalMessageSentinel |
src/harness/runtime-process.ts |
Core runtime process runner: launches a runtime worker (with a Windows guardian job when needed), captures output live, feeds supervision, run digest and loop watchdog, handles cancellation and settles the run. | writeGuardianConfig, prepareWindowsGuardian, runRuntimeProcess |
src/harness/runtime-recovery.ts |
Bounded runtime recovery and steering: resume budget accounting, steer request/record persistence, recovery prompts and the recovery loop that resumes native sessions after stops or operator steers. | resumeConsumesBudget, remainingResumeBudget, steerNotes, prepareRuntimeResume, readSteerRequest, recordSteerNotApplied, readSteerRecord, markAttemptSteered, … |
src/harness/runtime-requirements.ts |
Matches a mission’s runtime_requirements (network, shell, fs write, cost class) against adapter capability declarations and asserts eligibility. | resolveRuntimeRequirements, toolsSatisfyRequirements, evaluateAdapterEligibility, matchRuntimeRequirements, assertRuntimeRequirements |
src/harness/runtime-settlement.ts |
Settlement reconciliation: confirms guardian owner-loss receipts, settles native budget caps (including deadline grace), and reconciles runtime-result.yaml against the runtime-control.json receipt. | reconcileRuntimeSettlement, settleNativeCap, reconcileNativeCapSettlement, reconcileRuntimeResultControl |
src/harness/runtime-snapshot.ts |
Publishes immutable, content-addressed snapshots of built Tool Guard hooks and their import closure into a per-user cache so live runs survive rebuilds. | commonAncestor, layoutRootOf, importSpecifiers, resolveRelativeFile, resolvePackageRoot, walkFiles, collectClosure, verifySnapshot, … |
src/harness/runtime-supervision.ts |
Runtime supervision over native events: terminal failure and budget-cap detection, route verification, Tool Guard evidence and denial accounting, protected-root shell mutation checks, and stall/deadline/thinking watchdogs. | thinkingEventType, nativeRuntimeEvent, runtimeTerminalFailure, nativeTerminalStopReason, nativeTerminalBudgetCap, nativeRuntimeRoute, nativeDelegatedRoutes, delegatedRouteMismatch, … |
src/harness/runtime-turns.ts |
Counts conversation turns in parsed runtime event streams for supported runtimes such as Claude Code and ACP. | countRuntimeTurns |
src/harness/sandbox-backends.ts |
Sandbox backend abstraction with git worktree, local directory clone and OpenSandbox container backends that materialize, tear down and report dirty state of isolated working copies. | runGit, serializedWorktreeAdd, GitWorktreeBackend, DirectoryBackend, tryReadOpenSandboxConfig, parseLifecycleTimeoutMs, ContainerBackend, runOpenSandboxCommand, … |
src/harness/sandbox.ts |
Sandbox lifecycle orchestrator: create, list, status, discard and repair sandboxes with a lock-serialized sandboxes index, exclusive file locks with stale-owner breaking, mission seeding and mission-root routing. | listSandboxIndexLockBreaks, assertSafeSandboxId, readLockOwnerToken, breakStaleLock, acquireExclusiveFileLock, withSandboxesIndexMutation, createSandbox, listSandboxes, … |
src/harness/tool-guard.ts |
Runtime tool-call guard that classifies agent tool invocations (shell, write, read, agent-spawn tools) and denies writes outside the worker root, git mutations, deletes, package installs, network or agent clients, protected-root or hive access, guard tampering and containment escapes, parsing shell commands for redirections, cd changes, substitutions and variable assignments. | splitSegments, substitutions, agentClientInvoked, containmentEscapeInvoked, assignments, resolveToken, redirectionTargets, commandBody, … |
src/harness/usage.ts |
Token-usage capture for runtime events: estimates tokens from text, extracts real usage from OpenAI- and Anthropic-style usage objects, builds runtime.usage events, aggregates complete accounting facts across runs and prices usage against configured model pricing. | estimateUsage, isUsageNumber, usageFromOpenAI, usageFromAnthropic, buildUsageEvent, aggregateRuntimeUsage, estimateConfiguredCost |
src/harness/windows-job.cs |
C# Windows guardian compiled at runtime that launches a worker inside a Job Object with memory limits and kill-on-close, optionally attaches a windowless pseudoconsole, feeds stdin, watches for a parent-loss or stop file, and writes peak memory and accounting data as atomic JSON. | UHJob, WriteStdin, TryPseudoconsole, Run, WriteAtomicJson, Main |
src/harness/windows-job.ps1 |
Tiny PowerShell helper that compiles the C# Windows Job Object guardian source into a console executable via Add-Type; the detached native guardian, not PowerShell, owns the job. |