git:20260918.609bdce to git:20260919.6153de1

# Gitmoot

Gitmoot is a local-first coordinator for AI agents working across repositories,

goals, reviews, pull request comments, daemon jobs, branch locks, agent

templates (read-only installed data), current-chat prompt import,

multi-agent orchestration (the Orchestra delegations DAG), heartbeat schedules,

declared multi-stage pipelines, an outbound event stream, and Codex, Claude Code,

Kimi Code, omp, or shell runtime workflows.

This file is the machine-readable index of the Gitmoot docs — agents should

start here, then open [`llms-full.txt`](https://gitmoot.io/llms-full.txt) for the

full expanded context.

Native review verdicts return `changes_requested` to the requester's org role

by default. Unattended implement fix dispatch is a durable per-PR opt-in.

Findings ledger obligations follow commit ancestry, not pull request number alone.

Quoted-only diagnostics from a failed review remain job failures rather than code

findings; locator-backed or executed findings still enter the ledger.

A pull request that changes the `**Current mode:` marker in `AGENTS.md` is held

until an exact-head reconciliation row exists:

`[workload-mode-reconciliation repo=<owner/repo> pr=<n> head=<40-char reviewed head> mode=<THROUGHPUT|STEADY|DRAIN> decision_note=<note id|none>]`.

The decision itself is an append-only `[operating-mode repo=<owner/repo> mode=<mode>]`

note; `decision_note=none` means the PR is the decision. The newest decision

wins, an unreadable one supersedes rather than reading as absent, and a hold is

retryable and bounded by the gate `timeout` or 24h from the episode's start.

## Start Here

- [Introduction](https://gitmoot.io/docs/intro): What Gitmoot is and when to use it.

- [Install](https://gitmoot.io/docs/getting-started/install): Install and verify Gitmoot.

- [Quick Start](https://gitmoot.io/docs/getting-started/quick-start): Ask an agent to install Gitmoot, register a repo, start a planner, and route work.

- [Troubleshooting](https://gitmoot.io/docs/operations/troubleshooting): Diagnose daemon, job, runtime, sandbox, credential, and review failures, including daemon-owned Go/runtime staging and explicit exit-126 behavior for unavailable read-only-seat commands.

- [PR Comment Workflow](https://gitmoot.io/docs/workflows/pr-comment-workflow): Route auditable work from GitHub comments — `/gitmoot` commands, bare `@agent` mentions, and resuming paused orchestrations.

- [Review Agent Workflow](https://gitmoot.io/docs/workflows/review-agent-workflow): Register a strict review-only agent and route PR reviews to it; local CLI and native engine dispatch refuse a homogeneous succeeded decision at the unchanged exact head, emit `review_loop_detected`, and never serve the prior verdict as a cached result.

- [Review Agent Workflow](https://gitmoot.io/docs/workflows/review-agent-workflow): Register a strict review-only agent, pair local reviews with an implementation-capable `--lead`, refuse invalid fix routing before spending a review session, run engine-requested fixes in fail-closed independent writable per-job clones, and apply global or per-repository blocking severity so sub-threshold findings remain visible without restarting the fix loop.

- [Coordinator Recipes Workflow](https://gitmoot.io/docs/workflows/coordinator-recipes-workflow): One-command orchestras via `orchestrate --recipe review-panel|verifier` with ephemeral workers.

- [Run Jobs In Parallel On A Repo](https://gitmoot.io/docs/workflows/parallel-jobs-workflow): Use `--parallel N` (or `--workers N`, now auto-`pool`) to run a repo's queued jobs N-wide; the two serialization layers (checkout lock + runtime session lock); per-job exact-head review worktrees, writable on-branch review-fix clones, and committed-tip ask isolation; SIGHUP warm reload, per-repo `max_parallel`, the `[admission]` host budget, and `[github]` ETag polling, adaptive idle cadence, local call accounting, and secondary-rate-limit backoff.

- [Heartbeat Schedules Workflow](https://gitmoot.io/docs/workflows/heartbeat-schedules-workflow): Recurring agent work — `gitmoot agent heartbeat add` enqueues an ask/review (read-only) or policy-gated implement job on an interval, with an optional per-heartbeat `--runtime` override.

- [Pipelines Workflow](https://gitmoot.io/docs/workflows/pipelines-workflow): Run a fixed DAG of shell or managed-agent stages; publish/list/pull reviewable pipeline bundles through a private-by-default GitHub catalog with no-op republish diffs, or export/import the same directory offline. Opt-in shell-only service exposure adds bounded typed schemas, reserved env-only input delivery, random run ids, atomic rate/concurrency admission, detached worktrees, offline store-outcome proofs, authenticated delivery of proof-bound `out/` artifacts, and sanitized public digest-only receipts; the authenticated listener remains loopback-only by default. Pipeline-scoped secrets retain deny-by-default `env_keys`, shared key grants, and proxied loopback leases. Off by default.

## Concepts

- [Local-First Coordination](https://gitmoot.io/docs/concepts/local-first-coordination): Why state lives in local SQLite and GitHub stays the audit surface.

- [Agents, Agent Templates, Jobs, And Locks](https://gitmoot.io/docs/concepts/agents-templates-jobs-locks): The core object model — agent identities, template snapshots, job lifecycle, and the three lock kinds.

## Dashboard

- [Dashboard Overview](https://gitmoot.io/docs/dashboard/overview): The read-only live web dashboard (`gitmoot dashboard --web [--addr host:port]`) over the local store — launching, the URL route table including `/comms`, shared fleet-activity SSE, auto-refresh cadences (12s polls, 15s runs, SSE per-run graph), mobile support, operator-visible private data, and the localhost-default/no-auth security model.

- [Dashboard Views](https://gitmoot.io/docs/dashboard/views): Overview and Org distinguish live Herdr sessions from engine jobs, decorate the preserved role tree with task/status/turn detail, and label no-session, source-down, and filter-empty states; Comms is the read-only org escalation inbox with complete unresolved-workflow discovery, note deep links, filters, and CLI-only resolution via `gitmoot org escalate resolve`; the reference also covers Graph, Galaxy, Jobs, Pipelines, Workflows, Agents, Charts, Health, and Attention.

## References

- [CLI Reference](https://gitmoot.io/docs/reference/cli): Commands for install, home/config, daemon operations (including stale advertised-log detection and the systemd journal fallback), org chart/status rendering the provider's last completed turn with absent-is-not-zero semantics, per-repo `staged_review_verdict_agent` declaring which agent runs a staged review verdict stage with no default and no fallback, watched repos, dashboard, agents (including `agent show`'s unchanged `runtime_ref` field plus additive pinned-session and last-successful-use metadata), orchestrate, org role registry/escalation/recycle, safe org seat creation with optional create-now-bind-later roles, canonical stable pane-id persistence from literal ids or unique exact labels, creator-inherited parent/scope, and opt-in merge authority, deterministic doctor warnings for absent or stale org-role activity using `org_role_presence.last_seen_at` and configured `recycle_after`, exact-head bounded `org await review` fact subscriptions with atomic subscribe-and-recheck, queryable expiry, and delivery-only addressed wakes, downward-only directives with `send`/`ack`/`cancel`/`done` carrying three distinct disciplines — ack by the target or an ancestor, cancel by the sender, and done restricted to the target SUBTREE so an ancestor cannot certify work it commissioned — with `done` ending the obligation's TTL nudges, per-phase finite directive nudge ladders whose completion phase ends in a typed org:directive-exhausted marker note plus a row stamp, so a terminal ladder stays discoverable in the workflow journal, population-sized TTL sweep windows, durable coalesced nag delivery, and Claude quota-unavailable dispatch holds, Herdr-observed archived-seat roster exclusion at one choke-point (chart, status, health, sweeps, nudge ladders, presence) with parked directives and a stale-observation doctor warning, pipelines, jobs, locks, goals, including parent-linked session jobs with explicit caller-reported model/token evidence, fail-closed per-job exact-head worktrees for local review dispatch, authoritative post-agent delivery visibility (`delivery_status`), explicitly non-authoritative review visibility (`review_status` plus exact `head_sha`) graded `reported` for session journals and `observed` for sampled daemon-descendant liveness of dispatched review worktrees, durable bounded read-only-worktree diff capture for terminal background asks/reviews (`read_only_worktree_diff` plus explicit truncation/failure metadata), identity-safe recorded runtime PID liveness (`runtime_process_active`) and the doctor's hard ghost-job alarm, `workflow show`'s newest-100 default window and explicit truncation metadata, opt-in `[transcripts]` retention, and single/bulk `job transcript --export jsonl` trajectory export with atomic `0600` output and mandatory best-effort redaction. Queued jobs whose deferral reason is already recorded render it in `job list`, `job show` and `job watch` rather than as a bare `queued` row, including the withheld-by-another-job cause, a retry time that reads as unknown when absent rather than as a zero time, and `held_reason`/`held_next_retry_at`/`held_suggested_action` in `job watch --json`.

- [Daemon-owned organization reviews](https://gitmoot.io/docs/reference/cli): `agent review` and review-resolved `agent run` with `--org-role` queue for daemon ownership by default so the reviewer survives its caller exiting; `--foreground` is the explicit review-only opt-out.

- [Review router](https://gitmoot.io/docs/reference/cli#review-router): `gitmoot review request --pr N` is the front door for an independent review. Gitmoot picks a review-only agent scoped to the repo, runs it on omp with the purpose's ordered `[review_router]` model pool, claims `(repo, PR, exact head, purpose)` atomically so concurrent requesters attach to one job and a saved verdict is never reviewed twice, and subscribes the requesting org role to the exact-head verdict so the wake fires from the job's own persistence with decision, findings count, executed-check count and evidence - independently of gate advancement. A provider quota or auth failure before any verdict advances to the next pool model immediately (`review_model_fallback`); a verdict never changes the model. `gitmoot review status --pr N` lists every review job with head, model, verdict, evidence and hold reason.

- [Findings ledger obligations at a head](https://gitmoot.io/docs/reference/cli#asking-what-the-gate-still-demands): `gitmoot findings --repo owner/repo --pr N --at-head <sha>` prints the obligations the MERGE GATE would still demand at that head, which is a different question from the row listing's STATE column and is not derivable from it: an open finding recorded at an earlier head is still an obligation at a later one, and an answered finding becomes mandatory again when the diff since the answer touches its relevance keys. It calls LedgerObligationsAtHead through LedgerResolvers.ScopeFor, the same constructor the review brief and the merge gate share, so the CLI cannot answer differently from the thing that blocks; it carries the repository's findings_consumption declaration, so an advisory repository is reported as waived rather than blocked; and it prints `degraded:` notes derived from the resolvers that actually exist, including beside an empty list, because a missing resolver makes the answer silently under-report.

- [Change a registered agent's policy in place](https://gitmoot.io/docs/reference/cli#agent-policy-change-a-registered-agents-autonomy-policy-in-place): `gitmoot agent policy <name> --policy <value>` writes every plane that can become effective - the agents row AND any same-name agent_instances row, in one transaction, because agent remove deletes only the former and a survivor would re-widen a tightened agent - because `agent type set --policy` writes only the config plane and most registered agents have no config section. When a config type exists both planes are written and each is reported. Failure is all-or-nothing, enforced by a held transaction: both planes can authorise dispatch on their own, so the rows update, the config write runs as a barrier, and the commit lands only if it succeeded - a failure rolls back every plane rather than leaving a widened grant behind. A same-name agent_instances row is written too, because agent remove deletes only the agents row and a survivor would re-widen a tightened agent. `agent type show` exits NON-ZERO on a known cross-plane divergence or when the effective policy cannot be determined, and prints policy_effective beside the config policy.

- [Merged pull requests with unresolved obligations](https://gitmoot.io/docs/reference/cli#finding-merged-pull-requests-that-still-carry-obligations): `gitmoot findings --merged-unresolved` lists pull requests that MERGED while still carrying unresolved findings at their branch head. It is the UNION of the gate's own LedgerObligationsAtHead obligations and findings whose latest observation at that exact head is still open, which the gate's dischargedAtHead step deliberately removes; the report contains every gate obligation and may add exact-head-open findings; with none of those the two sets coincide. WAIVED reflects CURRENT findings_consumption read at report time, not a merge-time authorization. It keys on the BRANCH HEAD and never the merge commit, because every merge here is a squash and the ledger holds zero observations at merge commits against 19 at branch heads; keying on the merge commit fails silently as either an always-empty report or an always-inflated one. It prints what it scanned so an empty result is falsifiable, reports a pull request the forge cannot answer for as degraded rather than clearing it, and marks rows WAIVED where the repository declares findings_consumption = advisory.

- [Bridge](https://gitmoot.io/docs/reference/bridge): Authenticated localhost HTTP endpoint for external automation, including bounded string-map pipeline run payloads; token file auth and loopback-only default.

- [Runtime Adapters](https://gitmoot.io/docs/reference/runtime-adapters): Codex, Claude Code, Kimi Code, omp, shell, and future runtimes; lazy tri-state installed-CLI contract preflight (`supported`, blocking `unsupported`, fail-open recorded `unknown`) with executable-identity update detection and doctor visibility; warn-only adapter-derived permission-policy argv visibility (`applied`, `widened`, `not-applied`, `unresolved`) with a home-store fleet ratchet and nullable completion-effect capture attached to the same observation; the full omp contract (stateless fresh-session-per-job with the no-resume rationale, parse-derived success because exit 0 is not success, retry/terminal-state rules, summed per-message usage, policy-derived explicit `--approval-mode`, broker-backed read-only seats, execution-grounded upstream-provider family evidence with missing evidence failing closed, curated routing-plumbing environment); the config-driven metadata registry (`gitmoot runtime list`, `[runtimes.<name>]` overrides).

- [Runtime Ambient Credential Hygiene](https://gitmoot.io/docs/reference/credentials): Runtime credential custody — off-by-default child-environment curation with the exact allowlist and runtime exceptions, ambient GitHub credential denial or explicit inheritance, single-file Claude runtime auth, the loopback Claude model gateway (per-job placeholder tokens), and the named-key keychain: a metadata-only registry plus per-pipeline grants with own-key override, injected or configured `proxied` delivery (fixed-origin loopback leases, per-request grant re-check, revocation fail-closed), names-only audit, and the honest limits of each layer.

- [Execution Backend Selection](https://gitmoot.io/docs/reference/remote-exec): The `[remote_exec]` execution-backend seam — daemon jobs on `local` run in a job-scoped detached worktree, optional configured `local_uid`/`local_gid` drops agent-command privileges without a root fallback, `local_root` supports a traversable instance location, implement changes return transactionally with daemon-owned imports before result observation, cancel/destroy/reap own the instance lifecycle, a per-job `exec_backend` payload field overrides config, and unknown values fail loudly; distinct from Landlock local confinement.

- [Result Contract](https://gitmoot.io/docs/reference/result-contract): gitmoot_result shape, the delegations DAG (Orchestration), continuation, and termination bounds.

- [Event Stream](https://gitmoot.io/docs/reference/event-stream): The `[events]` webhook contract and opt-in organization event-rule Herdr wakes — addressed-by-default and observer rule scopes, `rule set-scope`, doctor coverage warnings for directed event kinds, job.finished/failed/blocked/needs_attention/deferred, candidate.*, durable `org.input_pending` re-nudges, direction-aware organization questions (ancestor escalation or descendant ask), escalation resolutions addressed back to their asker, coalesced addressed-note `org.reply` wakes, and delivery-only exact-targeted `org.fact` wakes backed by a SQL outbox, schema_version 1.

- [Codex And Claude Plugins](https://gitmoot.io/docs/plugins/codex-claude): Plugin discovery and runtime skill setup.

- [Troubleshooting](https://gitmoot.io/docs/operations/troubleshooting): Diagnose GitHub auth, bug reports, runtimes, agent templates, remotes, permissions, daemon lifecycle and stale advertised logs, stuck/deferred jobs, locks, delegation-worktree disk leaks and safe terminal-owner relief, transient merge deferrals while branch jobs are active, and the `gitmoot/merge-gate` status that marks a head the gate has not cleared. Read-only review seats select a Go installation from the daemon `PATH` that satisfies the effective `go.work` and checkout-root `go.mod`, stage an immutable daemon-owned copy, and pin `GOROOT`, `PATH`, `GOTOOLCHAIN=local`, and `GOWORK`; external workfiles receive file-only reads, and unsatisfied or unsafe selection fails through the exit-126 stub. A declared real review records `seat_toolchain_unavailable`; host-specific staging diagnostics also appear on daemon stderr.

- [Beta Smoke Tests](https://gitmoot.io/docs/operations/beta-smoke-tests): Deterministic smoke checklists for release validation.

- [Docs Deployment](https://gitmoot.io/docs/operations/deployment): How the docs site itself is built and published.

- [Release Notes](https://gitmoot.io/docs/release-notes/v0.9.1.3): Latest release (v0.9.1.3) — **the brain changelog**: an append-only `memory_events` journal records every fact mutation in-transaction (edits keep the previous content), browsable from the new `/brain` Graph|Changelog dashboard view (day-grouped live feed, before/after diffs, fact biographies, deep links) and from `gitmoot memory log` (+ idempotent `backfill` seeding history from existing tombstones). Plus keychain-secured pipeline credentials (registry, per-pipeline grants, proxied keys, env_file/env_keys injection), transcript retention with trajectory JSONL export, produce-stage `reads:` allowlists, and daemon reliability fixes (runtime-session lease heartbeats, checkout self-heal).

- [v0.8.7 Release Notes](https://gitmoot.io/docs/release-notes/v0.8.7): first-class Pipelines: a declared DAG of shell-runtime stages the daemon advances on demand or on a schedule, off by default (`gitmoot pipeline add|run|resume`), with an advancer cadence decoupled from repo-poll backoff and a committed-tip note on read-only top-level isolation (#681/#694/#700/#699). Reliability batch: reviews **re-sync** to a newer PR head instead of failing on a head-SHA mismatch (#691); GitHub API calls share a process-wide budget with adaptive secondary-rate-limit backoff (#692); blocked jobs record their `needs` as **resumable gates** — `gitmoot job gates`/`gates clear` satisfy them and auto-resume on the last clear (#693); full-chain E2Es cover the batch (#695).. Polish: product-style README (#688); dashboard moose logo + favicon (#689).

- [v0.8.6 Release Notes](https://gitmoot.io/docs/release-notes/v0.8.6): Codex token usage captured correctly for every session shape (#658/#661/#662/#664/#669); memory confirmed pool fills from ordinary jobs (#647); session jobs `job open/close/record` (#660/#676); daemon boot_id reboot recovery (#668); config-driven runtime metadata registry (#674/#679); dashboard Learning section (#672/#677/#680).

- [Review phase profiles](https://gitmoot.io/docs/reference/cli#where-a-reviews-wall-time-went-phase_profile): every review job emits one `phase_profile` job event per attempt recording where its wall time went - per-bucket command time (test/build/vcs/mixed/other), the union-based `covered_ms`, `residual_ms` (no command in flight), and `overlap_ms` for concurrent commands, so `covered + residual == wall` exactly. Buckets include `unknown`, which is a REFUSAL for shell syntax the cheap lexer does not implement (substitutions, heredocs, subshells, unterminated quotes, and interpreter options outside a measured per-shell grammar, whose execution effect, argument form, value domain and ordering are modelled per option, plus per-wrapper option grammars whose operand domains are derived from the installed binaries rather than asserted, forms where two installed implementations disagree, and shell options whose effect depends on runtime state (an ENABLED restricted mode, errexit chains) which fail closed while their valid unrestricted forms still classify) rather than a leftover category - its time still counts in `covered_ms`. Read `coverage` first: `opaque_runtime` means the runtime emits no tool events (Claude), so zero commands is a blind spot rather than a measurement.

- [Raw SKILL.md](https://gitmoot.io/SKILL.md): Agent skill entrypoint.

- [Full LLM Context](https://gitmoot.io/llms-full.txt): Expanded Markdown context for agents.

- [GitHub Repository](https://github.com/gitmoot/gitmoot): Source code and releases.