✨ workflow supervision (herdr/terminal): view, steer, and hijack smithers agents inside herdr/terminal

[N0xMare]

What this does

Smithers 0.33.0 adds a fully degradable terminal supervision plane backed by herdr: a complete cockpit outline plus an adaptive set of node panes, with direct steer, approve/deny, and resumable hijack controls.

Smithers remains authoritative for execution, isolation, and durability. Herdr renders and relays; if it is absent, unreachable, or protocol-incompatible, optional mirror paths degrade safely and explicit mutating commands fail before making changes.

Feature surface

• Herdr mirror — one workspace per run, complete cockpit overview, adaptive node-tab cap, attention promotion for gates/failures/hijacks, and terminal outcome markers. Commands: smithers herdr status|attach|open|clean.
• Workflow supervisor (smithers supervisor, alias top) — gateway-first with a --direct local-store path, graph-primary outline, activity strip, and node/gate detail panes.
• Steer — durable instructions injected at the next agent generate() boundary, with atomic/idempotent SteerQueued publication and deterministic consumption/expiry.
• Hijack — resumably park a run and hand off the native agent session without racing sibling agents.
• First-class effort — derive at spawn, persist on attempts, and render through direct and gateway paths.
• Detached approval recovery — claim-fenced supervisor resume for approved and genuinely denied gates, including scoped runs that would previously be crowded out by a 500-row page.
• Post-failure autopsy classification — skip human-denied, cancelled, and quota-parked terminals.

Safety hardening in the refreshed head

• protocol mismatches are inspectable via herdr status but blocked before workspace/tab/pane mutations
• Herdr tabs are owned by exact agent identity, never by a presentation-label collision with a user's tab
• same-run workspace creation is coalesced and reconciled; a loser only closes the workspace it created
• NDJSON frames are byte-bounded and oversized peers are disconnected
• Claude settings containing folded secrets use private temporary files that are removed on success, failure, and partial construction
• Claude transcript CWD discovery reads a bounded 64 KB prefix instead of loading an arbitrarily large JSONL file
• steer row + event publication is one transaction and retries with the same steer ID are no-ops
• recorded steer migrations validate/repair their owned index and fail closed on incompatible table/name collisions

Migrations

No manual migration is required. The final merge order reserves:

• 0035_agent_checkpoints — owned by feat: add durable generic agent checkpoints #1449
• 0036_attempt_effort_column — this PR
• 0037_add_steers — this PR

Preview ledger IDs (0035_attempt_effort_column, 0036_add_steers) are preserved and converge safely to the official IDs.

Behavior changes to existing commands

1. smithers tail is now first-class; -n selects a node. Use smithers logs <run> -n N for event line count.
2. logs follows live runs only on a TTY unless -f is supplied.
3. A successful pause exits 0.
4. supervisor uses the workspace Gateway by default; --direct reads the local store.
5. Inside Herdr, monitor/UI commands and post-run HTML summaries print URLs instead of opening a browser. Override with SMITHERS_NO_BROWSER=0.

Merge order

This PR remains independently based on main, but should merge after #1463 → #1449 → #1461. The combined verification explicitly retained 0035_agent_checkpoints → 0036_attempt_effort_column → 0037_add_steers; generated declaration and llms conflicts should be regenerated during the final refresh.

Current verified head: 1f9a8039f37ee5739cb820f89a622494abaa4bb8.

Verification

• standalone Herdr package: 113 passed
• combined CLI/supervisor/protocol/hijack run: 34 passed
• testing scheduler/artifact suites: 91 passed standalone; 68 passed in the combined stack check
• DB: checkpoint persistence, migration repair, pre-limit approval query, SQLite atomicity, and PGlite/PostgreSQL atomicity all pass
• combined real engine steer runtime: 11 passed, including first start, retry, loop, ordering, expiry, rollback, interleaving, idempotency, and child-run addressing
• combined checkpoint persistence and completed-task fork/resume E2E pass
• agents, DB, engine, Herdr, CLI, and testing typechecks pass in the combined stack
• affected package builds, docs, llms, dependency boundaries, changed-file formatting, and diff checks pass

Baseline-only repository issues remain unchanged: root formatting reports 24 pre-existing files, the declaration gate reports pre-existing integrations declaration drift, and the standalone main-based branch lacks #1463's Effect 4 managed-runtime bridge. The combined stack verification passes those affected runtime paths.

Known limitations

• Mid-turn steer applies at the next generate() boundary, not between tool calls.
• Cross-process workspace creation can only reconcile after create because Herdr exposes no server-side idempotency key/CAS; a process crash in that narrow window can strand a duplicate.
• PostgreSQL outline ordering remains best-effort via ctid.
• supervisor failures exit 4 (still non-zero).

[refcell]

LGTM

[roninjin10]

Merged — with this, your full stack (#1463 → #1449 → #1461 → #1430) is on main. Polish applied on top of your commits with authorship preserved: rebased onto current main, migrations renumbered to 0039_attempt_effort_column / 0040_add_steers (with convergence tests for the preview ids), steer-finalization durability hardening, and herdr-absent degradation verified empirically — every suite passes with no herdr binary, and every failure path returns a structured error instead of crashing. Two known follow-ups we're tracking as issues rather than blocking the merge: the client pins herdr wire protocol 16 (herdr 0.7.3) while current herdr 0.8.0 speaks protocol 19, so supervision fails closed (HERDR_PROTOCOL_MISMATCH) against a fresh herdr install until the 16→19 port lands; and the packages/testing runtime dependency on smthrs creates a cycle with @smthrs/testing we plan to break via an optional peer dependency. Verified: full root gate set, 11 package suites, and the complete 252-batch CLI suite, all green. Thanks for a remarkably disciplined 273-file PR — the degradation contract made it reviewable.