[zpyoung]

	Files	Added	Deleted	Net
Test	220	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​51712	$\color{#cf222e}{\Huge{\mathbf{−}}}$​31	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​51681
Prod	481	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​69274	$\color{#cf222e}{\Huge{\mathbf{−}}}$​2620	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​66654

ELI5

Heimdall is a supervisor that lives inside Orca and keeps working on something after you look away. You give it a job — "babysit this pull request until it's mergeable" or "get this goal done to this quality bar" — and it wakes up on its own schedule, checks what changed, decides the next step, and sends coding agents to do the work. Plain code makes every safety decision; the AI agents only do the parts that need judgment.

What Changed

Before: Orca could run agents, but a person had to keep checking on them, decide what came next, and restart work when something failed or a review came back.

After: a new Heimdall page in the sidebar lists every watcher, what it is doing, and what it is waiting on. There are two kinds of watcher:

• PR Sitter (hosted-review) — armed from a worktree's Checks panel. It watches a GitHub or GitLab pull request, fixes failing checks and review comments, resolves merge conflicts, and stops to ask when a decision needs a human.
• Objective — created from the Heimdall page. A planner agent breaks a goal into tasks and a reviewer checks the plan before anything runs. Workers then run in isolated git worktrees, in parallel where the plan allows. Each result is checked against the acceptance criteria before it is merged and landed.

Mechanism. One kernel in the main process owns everything that has to be right:

• Scheduling and leases: when each watcher wakes, and which Orca instance currently owns it.
• Budgets and stop rules: how much time and how many turns each watcher may spend.
• Capability gates: every action is checked against what the watcher is allowed to do before it runs.
• Ledger: an append-only record of every event, kept in its own SQLite database.

Agents are dispatched through Orca's existing orchestration and terminal machinery. They report back through files that the kernel reads defensively and validates before trusting.

Remote hosts are supported: work runs where the workspace lives, git commands on SSH hosts go through a strict relay allowlist, and losing contact is never treated as "the process died". The remote wire protocol changes are additive and capability-negotiated, so older clients keep working.

All code sits in fork-heimdall/, fork-heimdall-objective/ and fork-hosted-review-sitter/ directories and is declared in config/fork-ownership.json. Upstream files carry only one-line registration seams. The operating manual is docs/reference/heimdall-watcher.md.

The last two commits remove duplication found by an audit of the branch. That covers unused exports, store methods used only by tests, and swaps to upstream helpers (mapWithConcurrency, getErrorCode, settleWithinMs, isFullGitObjectId). It also adds one shared SQLite lifecycle class and one transaction helper, a single hardened report-file reader, and shared test fixtures. They cut about 1,000 lines with no intended behavior change. The one deliberate fix: landing-git-state.ts used to accept 41–63-character strings as git object IDs.

Why

Long-running agent work fails in the gaps between runs: nobody notices a red check, a review sits unanswered, a half-finished task is never retried. The alternative was to let an agent loop on its own. We rejected it because an agent that decides its own next step can also decide to skip a safety check.

Splitting the work keeps safety auditable and testable without a model in the loop. Deterministic code owns scheduling, gating and stopping, and agents only supply judgment. Keeping everything in fork directories with declared seams lets upstream syncs merge cleanly.

Linked Issue

N/A — issues are disabled on this repository.

Visual Proof

Not attached yet. This adds UI: the Heimdall sidebar page, the objective enrollment sheet and detail view, and the PR Sitter panel in the Checks sidebar. Screenshots need to be added before merge.

Testing

• pnpm typecheck:node, typecheck:web and typecheck:cli pass.

• All fork test suites pass in the remote sandbox: 407 files and 3,964 tests across main, shared, relay, renderer, CLI and the RPC methods.

• The full unit lane has failures outside this feature's code (terminal pane, browser, sidebar, timeouts). One known failure is from this branch: fork-localization-catalogs.test.ts still expects 16 English catalogs, but the branch registers 19. It is filed in the ledger and not fixed here.

• Tested locally on macOS; objective runs are logged under docs/heimdall-runs/. Linux and Windows are not tested manually.

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

AI Disclosure

Written with Claude Code (Claude models). The final cleanup pass used Claude Opus with Sonnet subagents. It included an audit, a verification pass that tried to disprove each finding, and a behavior review of the refactor.

Review

Known items to resolve before merge:

• 1cc57e0efb adds temporary [DBG-*] console.warn logging to the terminal-wait probe (orca-runtime-start-tui-idle-visible-read-probe.ts, runtime-terminal-wait.ts). Remove it once the readiness investigation ends.
• The branch history includes a wip: commit.
• The fork-localization catalog-count test described under Testing.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Ensure no issues in: Security, Cross-platoform support (Linux, Windows, Mac), Remote SSH, Mobile, general backwards compatibility, performance

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[greptile-apps]

Confidence Score: 3/5

[High risk] Adds new Heimdall watcher system with CLI, runtime, and test infrastructure.

The PR is not ready to merge while post-turn Claude waits time out and the localization test fails; the repository comment requirement also needs to be met.

Findings

1.  Claude post-turn idle times out ▶
2.  Catalog count test fails ▶
3.  Lease writes expose partial records ▶
4.  Test selection silently ignored ▶
5.  Temporary terminal logging remains ▶
6.  Comment is overly verbose ▶

Summary

The PR adds a Heimdall kernel and UI for durable PR and objective watchers, with remote fleet routing, lease-backed scheduling, guarded agent work, and landing evidence.

• The Claude idle-after-turn path and the localization test need correction before merge.
• Lease publication, sandbox selection behavior, and temporary terminal diagnostics need follow-up.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  UI[Heimdall UI or CLI] --> K[Watcher kernel]
  K --> L[Lease and ledger]
  K --> S[PR sitter]
  K --> O[Objective planner and workers]
  S --> F[GitHub or GitLab]
  O --> G[Checked git landing]
  K --> R[Remote host routing]

Loading

_{Reviews (1) · Last reviewed commit: "Centralize Heimdall persistence and repo..."}

[zpyoung]

@greptile-apps Fixing. Will be in the next commit

[greptile-apps]

Thanks — I’ll re-check the affected paths in the next commit, including the idle timeout, catalog-count test, lease publication, test selection, and temporary logging findings.