Run Control and Team Coordination
Live-run registry and operator controls (kill, wait, steer, cancel, intervention ledger) plus multi-run orchestration: dependency-ordered queue, team worker waves with resource admission, staged workflows, cross-runtime run-all, matched-budget experiments and the shared hive knowledge store.
Depends on: Mission Lifecycle and Artifact Store (26), Artifact Schemas (22), Observability, Accounting and Reporting (10), Runtime Execution and Supervision (8), Runtime Adapters and In-Runtime Extensions (3), Verification, Review and Promotion (2)
Used by: Runtime Execution and Supervision (5), Verification, Review and Promotion (5), CLI Entry, Build and Project Tooling (3), Observability, Accounting and Reporting (2), Mission Lifecycle and Artifact Store (1)
(Numbers are distinct file-to-file dependencies.)
| File | Summary | Key symbols |
|---|---|---|
src/harness/experiment.ts |
Matched-budget experiment engine that seeds a deterministic search/held-out task split, interleaves arms across attempts, runs them through an injected runner under budget limits, and summarizes arm comparisons into a markdown report. | experimentSpecPath, experimentArtifactsDir, mulberry32, splitTasks, planExperiment, loadExperiment, loadExperimentRuns, runExperiment, … |
src/harness/hive-root.ts |
Resolves the project that owns .harness state for a directory, so team worker worktrees and sandboxes nested inside another project’s .harness share its hive. | mainCheckoutRoot, harnessOwnerRoot, harnessHiveDir, hasMainCheckout |
src/harness/hive.ts |
Shared hive knowledge store of items, hash-chained facts, and unproven claims, with evidence hashing, chain verification, fact selection, and safe rendering of verified facts into mission prompts. | hiveDir, hiveItemsPath, hiveFactsPath, hiveClaimsPath, readHive, readHiveItems, readHiveFacts, readHiveClaims, … |
src/harness/interventions.ts |
Hash-chained intervention ledger recording every moment a run needed correction (steer, kill, review, settlement, replace), with landing, owner confirmation, predecessor import, summaries, and formatting. | ledgerDir, interventionsPath, harnessRootFor, generateInterventionId, buildIntervention, appendIntervention, verifyLedgerChain, recordIntervention, … |
src/harness/kill.ts |
Implements uh kill: resolves run selectors against live runs, stops controllers and owned process trees, settles orphaned runs, marks team state cancelled, and reports proof that native processes are gone. | KillError, defaultProcessKiller, assertValidSelector, resolveKillTargets, sharedControllerPids, writeControl, baseEntry, settleOrphanedRun, … |
src/harness/live-runs.ts |
Project-root registry of in-flight runtime attempts under .harness/live-runs, combined with a bounded scan for runtime-control files to discover runs, compute liveness verdicts, list process trees, and back uh ps. | liveRunsDir, findProjectRoot, teamFromArtifactRoot, isSettled, heartbeatAgeMs, registerLiveRun, settleLiveRun, claimLiveRun, … |
src/harness/mission-cancel.ts |
Cancels in-flight mission runs either through the Hermes plugin HTTP API or locally by resolving the run’s owning artifact root and writing a cancellation request. | MissionCancelError, defaultPluginApiBase, cancelMissionRunViaPlugin, runRootForRecord, resolveRunRoot, cancelLocalMissionRun |
src/harness/queue.ts |
UH queue scheduler: launches missions in dependency order under an orchestrator cap and free-memory floor, settles each entry from recorded run artifacts (never child exit), and persists resumable state under .harness/queue. | queueDir, queueStatePath, loadQueueFile, readQueueState, resolveCliEntry, mapWaitReport, settleRunFromRecords, createQueueLauncher, … |
src/harness/run-all.ts |
Cross-runtime QA harness (UH-56) that fans a mission across several runtimes in separate sandboxes, groups outcomes by diff hash and renders a markdown comparison report. | runMissionAcrossRuntimes, compareRuntimeOutcomes, renderRuntimeComparisonMarkdown, persistRuntimeComparison |
src/harness/runtime-resources.ts |
Memory and cost admission for team workers: resolves per-worker memory from recorded peaks, computes concurrency, and admits bounded waves across teams with a per-project lock and reservations. | workerAdmissionDir, workerAdmissionLockPath, resolveTeamResources, recordedWorkerPeakMb, workerConcurrency, mapBounded, decideAdmission, admitAcrossTeams, … |
src/harness/steer.ts |
UH steer and resume: resolves a run, validates it is resumable and steerable, writes steer requests for live controllers, or cancels and resumes the native session with the operator’s message, recording lineage links. | runtimeSupportsResume, UnsupportedResumeError, resolveAdapterRoot, resolveResumableRun, assertResumableRuntime, assertSteerable, resolveLineageRuns, assertNoLiveInLineage, … |
src/harness/team-run.ts |
Team mission runtime (UH-72) that plans N adapter-bound workers in dedicated git worktrees, runs them under resource waves, integrates their branches through a leader worktree, verifies the integrated result, and persists canonical team state, salvage records and an integration report. | runGit, prepareLongPaths, checkWorktreePathLength, resolveWorkerCommitScope, planTeamRun, resolveTeamWorkerArtifactRoot, resolveWorkerContract, deriveWorkerPacket, … |
src/harness/wait.ts |
Implements uh wait: resolves run, mission or team selectors against the live-run registry with uh kill semantics, then polls until every matched run is settled or orphaned or a timeout passes, reporting per-run outcomes without signalling any process. | WaitError, assertValidSelector, resolveWaitTargets, classifyRun, waitForRuns, formatWaitReport |
src/harness/workflow.ts |
Staged workflow profile runner (UH-73) that drives a mission through Plan, PRD, Execute, Verify and Fix phases, dispatching to a single adapter or fanning Execute out via runTeamMission, and bounding the Verify-Fix loop by max_iterations. | runStagedWorkflow, runPlanOrPrd, runSinglePhase, runVerifyPhase, runFixPhase, renderVerifyReport, finalize, stagedArtifactPath |