supervisor

harn supervisor runs one bounded, read-only diagnostic process per coordination root. Core coordination, hooks, and Event Ledger V3 do not depend on it.

harn supervisor start
harn supervisor status
harn supervisor stop

What it observes

The supervisor runs several inexpensive collectors behind one process:

• machine and process CPU, memory, swap, age, and proven agent ownership;
• semantic reader, presence relay, governor, dashboard, and supervisor health;
• active hook processes whose agent ownership and exact entrypoint are both proven;
• bounded terminal hook receipts with internal outcome, duration, retry-worker count, and process RSS point samples;
• a 15-minute pressure history with 90 ten-second points;
• opened and resolved source-agnostic findings with compact referenced evidence; and
• incremental structured-log records for the live dashboard.

The log collector seeds a bounded recent window when it starts. After that it uses each structured-log family’s follow cursor and reads only complete appended records. A malformed family remains isolated from every healthy family.

agent-hook always exits zero so telemetry cannot break a host adapter. The operating-system exit code is therefore not a health signal. Each observable invocation writes one sanitized agent_hook.completed record with an internal outcome of completed, skipped, degraded, or faulted. It excludes raw payloads, commands, prompts, tool input and output, paths, and error messages. The supervisor keeps at most 50 recent receipts and 40 per-hook aggregates.

Completed hook RSS is a start and completion point sample for the hook process. It is not a process-tree peak or proof of a leak. The existing live hook rows remain the source for processes that are still running.

Lifecycle

harn web up and harn web start register the dashboard process as a consumer and ensure the supervisor is running. A demand-started supervisor exits after two minutes with no live dashboard consumer and no attributed agent process. Hooks or a later dashboard start can launch it again.

An explicit start uses the same demand behavior by default:

harn supervisor start --idle-exit-ms 120000

Use --keep-alive when an operator deliberately wants continuous local history without active agents or a dashboard:

harn supervisor start --keep-alive

The collection interval accepts 500 through 60,000 milliseconds and defaults to 2,000 milliseconds. The idle exit accepts 5,000 milliseconds through 24 hours. start waits for a live heartbeat, and stop writes a durable request before checking whether it can signal the same-host supervisor process.

Identity and build status

harn supervisor status includes the following fields under service:

Field	Meaning
generation	same, different, or unknown, from the recorded and current process start tokens
liveness	running, stopped, or unknown; an unreadable identity is unknown
running_build	The daemon’s recorded { version, revision }, or null when unavailable
installed_build	The CLI’s current { version, revision }
restart_needed	true when the builds differ or the running build is unknown
build_status	current, restart needed, or running build unknown; restart needed

The revision identifies the source Git commit, or npm-<version> for a published package. A running supervisor keeps its original build until it restarts. harn resources status and harn diagnostics also expose the supervisor’s generation and build status.

A record without a start token, or a failed token probe, produces unknown. Harnery refuses a second start while it cannot establish the existing supervisor’s identity. Run harn supervisor stop to write the durable stop request, then check status before starting it again.

stop rechecks the start token immediately before signaling. It sends nothing when the verdict is different or unknown; its response includes signal_sent and signal_verdict. The supervisor can still honor the durable stop request. The token check narrows the PID-reuse race but does not eliminate the interval between the check and the signal.

See ADR 0207 for the shared rule.

Bounded storage

Current projections live under .harnery/supervisor/:

.harnery/supervisor/
├── service.json
├── snapshot.json
├── history.json
├── findings.json
├── timelines/
├── explanations/
├── log-feed.json
├── hook-health.json
└── consumers/

The resource snapshot remains under .harnery/resources/snapshot.json so the daemon-free harn resources snapshot and dashboard share one contract. All supervisor files are reconstructable caches. They do not enter Event Ledger V3.

History keeps 90 points. Finding history keeps 100 opened or resolved transitions. Timelines, explanations, and evidence arrays have fixed entry limits. Live logs keep at most 100 records per registered family and use fixed read budgets. Hook health reports partial or unavailable capability when its bounded log evidence is truncated, malformed, or unreadable. Atomic private JSON writes prevent dashboard readers from seeing partial frames.

The completed-hook projection opens findings for degraded or faulted internal outcomes, completed invocations lasting at least 30 seconds, completed RSS samples of at least 512 MiB, and three retry workers inside five minutes. These thresholds only create evidence for inspection. They do not change hook or adapter behavior.

Authority boundary

The supervisor may observe, correlate, cache, and report. It may signal only its own process during an explicit stop. It cannot kill or renice another process, restart a service, call a model, execute governor work, write Event Ledger V3, or mutate agent lifecycle state.