@bradheitmann/odin-sentinel 0.4.12 → 0.5.0

package/docs/adapters/herdr-adapter.md

@@ -0,0 +1,150 @@
+# herdr Adapter Specification
+
+## Overview
+
+herdr is a third-party Rust TUI agent multiplexer (herdr.dev) that runs inside
+any terminal and provides persistent background sessions with a rich NDJSON
+socket API. It is the **primary tier-3+ substrate** for SSH hosts, Linux
+agents, and non-Mac environments.
+
+herdr supports 14+ documented agent integrations as of 2026-06, and its
+persistent background session model means agent processes survive terminal
+disconnects.
+
+**SCP Capability Tier: 3+**
+
+---
+
+## LICENSE NOTE
+
+> **herdr is licensed under AGPL-3.0 with a commercial dual-license option.
+> Any future runtime adapter code included in a distributed package requires
+> legal review to confirm GPL compatibility with the host project's license
+> before distribution.**
+
+This document is documentation-only for the current release cycle. No herdr
+dependency has been added to the core protocol package. Legal review must be
+completed before any herdr adapter code is shipped in a distributed artifact.
+
+---
+
+## Capability Matrix
+
+| Capability   | Supported | Notes                                                    |
+|:-------------|:----------|:---------------------------------------------------------|
+| SEND         | Yes       | workspace/tab/pane/output NDJSON operations              |
+| ENTER_PROOF  | Yes       | `wait` operation confirms delivery                       |
+| READ_SCREEN  | Yes       | `pane/output` read operations                            |
+| WAIT_IDLE    | Yes       | `wait` operation on pane process state                   |
+| EVENTS       | Yes       | Persistent background session with NDJSON event stream   |
+| PERSISTENCE  | Yes       | Persistent background sessions survive disconnects       |
+| RECORDING    | No        | No structured evidence recording primitive               |
+
+---
+
+## NDJSON Socket API Reference
+
+herdr exposes a NDJSON socket API. Each request and response is a single
+JSON object on one line (newline-delimited). The socket path is configurable;
+the default is a Unix domain socket in the user's runtime directory.
+
+### SEND — workspace/tab/pane/output
+
+Send text to a pane inside a named workspace and tab:
+
+```json
+{"op": "pane/send", "workspace": "{workspace_id}", "tab": "{tab_id}", "pane": "{pane_id}", "text": "{text}"}
+```
+
+### ENTER_PROOF — wait
+
+Block until the pane reaches an idle or expected-output state:
+
+```json
+{"op": "wait", "workspace": "{workspace_id}", "tab": "{tab_id}", "pane": "{pane_id}", "condition": "idle"}
+```
+
+The response includes a timestamp and the pane's process state at the moment
+the wait condition was satisfied.
+
+### READ_SCREEN — pane/output
+
+Read the current visible output of a pane:
+
+```json
+{"op": "pane/output", "workspace": "{workspace_id}", "tab": "{tab_id}", "pane": "{pane_id}"}
+```
+
+### WAIT_IDLE — wait
+
+Same operation as ENTER_PROOF. The `wait` operation serves both synchronization
+and delivery-confirmation roles:
+
+```json
+{"op": "wait", "workspace": "{workspace_id}", "tab": "{tab_id}", "pane": "{pane_id}", "condition": "idle", "timeout_ms": 30000}
+```
+
+### EVENTS — persistent session event stream
+
+herdr maintains a persistent background session server. Subscribe to a pane's
+event stream to receive real-time output and state change notifications:
+
+```json
+{"op": "subscribe", "workspace": "{workspace_id}", "tab": "{tab_id}", "pane": "{pane_id}"}
+```
+
+Each event is emitted as one NDJSON line. This eliminates polling for
+output detection and state transitions.
+
+### PERSISTENCE
+
+herdr's background session model keeps agent processes alive after the
+originating terminal disconnects. Sessions are identified by workspace and
+tab IDs and can be reconnected from any terminal on the same host.
+
+This makes herdr suitable for long-running agent workloads on SSH hosts where
+terminal disconnects are expected.
+
+### RECORDING
+
+**Not supported.** herdr has no structured evidence recording primitive at the
+SCP adapter level. If recording is required, redirect pane output to a log file.
+
+---
+
+## Use Case
+
+herdr is the recommended substrate for:
+
+- **SSH hosts:** Agents running on remote Linux servers where cmux is not
+  available.
+- **Linux agents:** Non-Mac environments where a native macOS multiplexer
+  cannot be installed.
+- **Non-Mac CI/CD:** Governed agent runs in Linux containers or VMs.
+- **Distributed team setups:** Multiple operators connecting to the same
+  persistent agent sessions from different terminals.
+
+Its 14+ documented agent integrations and persistent session model make it
+the strongest available tier-3 substrate outside the macOS cmux ecosystem.
+
+---
+
+## Agent Integrations
+
+herdr ships with integrations for 14+ agent frameworks as of 2026-06. Refer
+to the herdr documentation at herdr.dev for the current integration catalog.
+The SCP adapter will target the core NDJSON socket API directly and is
+independent of the higher-level agent framework integrations.
+
+---
+
+## Implementation Status
+
+The runtime SCP adapter for herdr is **deferred**. Legal review of AGPL-3.0
+compatibility with the host project's license is required before any adapter
+code is distributed. This document specifies the NDJSON socket surface that the
+adapter will use when implemented.
+
+When the adapter is implemented, it will be released under a separate adapter
+package and will document the completed legal review outcome. The core package
+remains substrate-agnostic and carries no herdr dependency.

package/docs/adapters/minimux-adapter.md

@@ -0,0 +1,152 @@
+# minimux Adapter Specification
+
+## Overview
+
+minimux is a **headless Zig daemon** and the **highest-capability headless
+substrate** for the Supervised Completion Protocol (SCP). It exposes all seven
+capability flags through a JSON-RPC API, making it the only current substrate
+that reaches **tier 4**.
+
+minimux is designed purely for agent workloads. It is never the orchestrator
+and never a multiplexer for humans. Workers run in minimux sessions while a
+human-visible multiplexer (cmux, herdr, or similar) provides the operator view.
+
+**SCP Capability Tier: 4**
+
+---
+
+## PROTOTYPE STABILITY CAVEAT
+
+> **minimux v0.1.1 is prototype software. Protocol guarantees are not
+> production-hardened. Homebrew/npm distribution exists but the runtime adapter
+> for SCP is deferred to a later phase.**
+
+Do not use minimux for production governed-team runs until the runtime SCP
+adapter is complete and the stability caveat is lifted. This document is
+documentation-only for the current release cycle.
+
+---
+
+## Capability Matrix
+
+| Capability   | Supported | Notes                                                        |
+|:-------------|:----------|:-------------------------------------------------------------|
+| SEND         | Yes       | `pane.send` JSON-RPC method                                  |
+| ENTER_PROOF  | Yes       | `agent.wait_idle` delivery proof primitive                   |
+| READ_SCREEN  | Yes       | `pane.snapshot` structured snapshot                          |
+| WAIT_IDLE    | Yes       | `agent.wait_idle` blocks until the pane process is idle      |
+| EVENTS       | Yes       | `tap` method — live event stream per session/pane            |
+| PERSISTENCE  | Yes       | Append-only journal + atomic snapshot; kill-9 survivable     |
+| RECORDING    | Yes       | `recordings` evidence primitive                              |
+
+---
+
+## JSON-RPC Method Reference
+
+minimux communicates over a local JSON-RPC socket. All methods follow the
+standard JSON-RPC 2.0 envelope (`jsonrpc`, `method`, `params`, `id`).
+
+### SEND — `pane.send`
+
+Send text to a named pane in a session:
+
+```json
+{
+  "method": "pane.send",
+  "params": { "session": "{session_id}", "pane": "{pane_id}", "text": "{text}" }
+}
+```
+
+### ENTER_PROOF — `agent.wait_idle`
+
+Block until the target pane's process reaches an idle state and return a
+structured delivery proof:
+
+```json
+{
+  "method": "agent.wait_idle",
+  "params": { "session": "{session_id}", "pane": "{pane_id}", "timeout_ms": 30000 }
+}
+```
+
+The response includes a timestamp, process state, and a journal sequence number
+that serves as the delivery proof artifact.
+
+### READ_SCREEN — `pane.snapshot`
+
+Return a structured snapshot of the current pane content:
+
+```json
+{
+  "method": "pane.snapshot",
+  "params": { "session": "{session_id}", "pane": "{pane_id}" }
+}
+```
+
+The snapshot includes full scrollback within the journal window, process state,
+and the sequence number at the time of capture.
+
+### WAIT_IDLE — `agent.wait_idle`
+
+Same method as ENTER_PROOF. `agent.wait_idle` serves both the "wait until idle"
+and the "proof of delivery" roles because the idle gate is also the delivery
+confirmation boundary.
+
+### EVENTS — `tap`
+
+Subscribe to a live NDJSON event stream for a session or pane:
+
+```json
+{
+  "method": "tap",
+  "params": { "session": "{session_id}", "pane": "{pane_id}" }
+}
+```
+
+The stream emits one JSON object per line as events occur (input, output,
+process state changes, idle transitions). Use this for real-time supervision
+without polling.
+
+### PERSISTENCE
+
+minimux maintains an **append-only journal** and **atomic snapshots** for each
+session. If the daemon is killed (including `kill -9`), the journal is replayed
+on restart and the session state is recovered automatically.
+
+This is the only tier-4 persistence primitive in the current substrate catalog.
+
+### RECORDING — `recordings`
+
+Retrieve structured recording artifacts for a session or pane:
+
+```json
+{
+  "method": "recordings",
+  "params": { "session": "{session_id}", "pane": "{pane_id}", "from_seq": 0 }
+}
+```
+
+Recordings serve as evidence artifacts for audit trails and QA review.
+
+---
+
+## Positioning Note
+
+minimux is **never the orchestrator** and **never a multiplexer for humans**.
+
+Workers run inside minimux sessions. The human operator views the governed
+workspace through a human-visible multiplexer (cmux on macOS, herdr on Linux
+or SSH hosts). minimux provides the headless execution layer; the human-visible
+layer is a separate substrate.
+
+---
+
+## Implementation Status
+
+The runtime SCP adapter for minimux is **deferred**. This document specifies
+the JSON-RPC surface that the adapter will use when implemented. No minimux
+dependency has been added to the core protocol package.
+
+When the adapter is implemented, it will be released under a separate adapter
+package that lists minimux as a peer dependency. The core package remains
+substrate-agnostic.

package/docs/adapters/plain-terminal.md

@@ -0,0 +1,80 @@
+# Plain Terminal Adapter Specification
+
+## Overview
+
+A plain terminal (SSH tty, serial console, bare shell, or any environment
+without a multiplexer) is the **lowest-capability substrate** for the
+Supervised Completion Protocol (SCP). Only SEND is available.
+
+There is no feedback channel. The agent cannot confirm delivery. The PM cannot
+observe screen content. Polling is impossible. Governance obligations that
+require tier >= 1 cannot be met in a plain terminal environment.
+
+**SCP Capability Tier: 0**
+
+---
+
+## Capability Matrix
+
+| Capability   | Supported     | Notes                                               |
+|:-------------|:--------------|:----------------------------------------------------|
+| SEND         | Yes           | Write to stdin or the tty device                    |
+| ENTER_PROOF  | NOT SUPPORTED | No screen capture; delivery cannot be confirmed     |
+| READ_SCREEN  | NOT SUPPORTED | No capture-pane or equivalent primitive             |
+| WAIT_IDLE    | NOT SUPPORTED | No idle-detection mechanism                         |
+| EVENTS       | NOT SUPPORTED | No hook system or event stream                      |
+| PERSISTENCE  | NOT SUPPORTED | No session journal or crash-recovery primitive      |
+| RECORDING    | NOT SUPPORTED | No structured evidence recording primitive          |
+
+---
+
+## Limitations
+
+A plain terminal provides write-only access to the agent process. The
+supervisor has no visibility into what the agent has received, processed, or
+output. Specifically:
+
+- **No delivery confirmation:** Once a string is sent to stdin, there is no
+  mechanism to verify the agent received or acted on it.
+- **No screen observation:** The PM cannot read the agent's output without an
+  out-of-band channel (log file, sidecar process, etc.).
+- **No idle detection:** The supervisor cannot determine when the agent has
+  finished responding.
+- **No event callbacks:** There is no hook or notification system to signal
+  state transitions.
+- **No persistence:** If the terminal session ends, all state is lost. There
+  is no journal to replay.
+- **No recording:** There is no structured artifact capturing the agent's
+  activity for later review.
+
+---
+
+## Use Case
+
+A plain terminal is the **fallback surface of last resort** for bootstrapping
+in environments where no multiplexer is available. It is appropriate only when:
+
+1. No multiplexer (tmux, cmux, minimux, herdr) can be installed on the host.
+2. The operation does not require delivery confirmation, screen observation,
+   or governed supervision.
+3. The operator accepts that governance obligations requiring tier >= 1 cannot
+   be met and takes responsibility for out-of-band status verification.
+
+Typical scenarios: initial provisioning of a new host before a multiplexer is
+installed; serial console access to an embedded device; a minimal container
+environment where process namespace restrictions prevent multiplexer operation.
+
+---
+
+## Operator Responsibilities
+
+Because the SCP adapter cannot observe the agent, the operator must:
+
+- Use out-of-band channels (log files, sidecar processes, application metrics)
+  to verify agent activity.
+- Accept that no boot receipt, delivery proof, or wake-state report can be
+  generated for this tier.
+- Treat the plain terminal session as ungoverned and document the exception
+  in the session record.
+
+Promote the substrate to tier >= 1 (tmux) as soon as the environment permits.

package/docs/adapters/tmux-adapter.md

@@ -0,0 +1,150 @@
+# tmux Adapter Specification
+
+## Overview
+
+tmux is a **tier-2 substrate** for the Supervised Completion Protocol (SCP).
+It provides SEND, ENTER_PROOF, READ_SCREEN, and WAIT_IDLE — a solid mid-tier
+capability set sufficient for governed agent supervision when screen capture and
+idle-wait primitives are required.
+
+tmux does **not** have an event hook system comparable to a native GUI
+multiplexer, so all observation must be done via polling rather than
+event-driven interrupts.
+
+**SCP Capability Tier: 2**
+
+---
+
+## Capability Matrix
+
+| Capability   | Supported | Notes                                           |
+|:-------------|:----------|:------------------------------------------------|
+| SEND         | Yes       | `tmux send-keys -t {pane} {text} Enter`         |
+| ENTER_PROOF  | Partial   | Send Enter then verify via capture-pane          |
+| READ_SCREEN  | Yes       | `tmux capture-pane -p -t {pane}` (text snapshot)|
+| WAIT_IDLE    | Yes       | `tmux wait-for {event_name}` blocks until fired |
+| EVENTS       | No        | No hook system; polling required                |
+| PERSISTENCE  | No        | Sessions survive disconnect but no agent journal|
+| RECORDING    | No        | No structured evidence primitive                |
+
+---
+
+## Command Reference
+
+### SEND
+
+Send text to a pane. Use `send-keys` for arbitrary text; include `Enter`
+to submit the line:
+
+```
+tmux send-keys -t {session}:{window}.{pane} "{text}" Enter
+```
+
+Pane targets use tmux's `%N` numeric pane IDs or `session:window.pane` syntax.
+
+### ENTER_PROOF (Partial)
+
+tmux has no native delivery-proof primitive. The pattern is:
+
+1. Send the command with `Enter`.
+2. Poll `capture-pane` until the expected prompt or output appears.
+3. Record the capture result as the delivery artifact.
+
+This is probabilistic rather than cryptographic; it satisfies tier-2 proof
+requirements but not tier-4 journal-level guarantees.
+
+```
+tmux send-keys -t {pane} "{command}" Enter
+# then poll:
+tmux capture-pane -p -t {pane}
+```
+
+### READ_SCREEN
+
+Capture the visible text content of a pane as a UTF-8 string:
+
+```
+tmux capture-pane -p -t {pane}
+```
+
+Requires tmux 2.0 or later for the `-p` (print to stdout) flag.
+
+For history beyond the visible viewport:
+
+```
+tmux capture-pane -p -S -{history-lines} -t {pane}
+```
+
+### WAIT_IDLE
+
+Block until a named event fires. The event must be signalled by a shell
+command or wrapper running inside the target pane:
+
+```
+tmux wait-for {event_name}
+# signal from inside the pane:
+tmux wait-for -S {event_name}
+```
+
+`wait-for` is suitable for synchronizing after long-running commands when
+the inner process can call `tmux wait-for -S`.
+
+### EVENTS
+
+**Not supported.** tmux has no hook API comparable to a native multiplexer's
+`set-hook` or `notify` system. Supervision logic must poll `capture-pane`
+at a fixed interval; event-driven scheduling is not available.
+
+### PERSISTENCE
+
+**Not supported at the SCP adapter level.** tmux sessions survive disconnects,
+but there is no append-only journal, atomic snapshot, or crash-recovery
+primitive accessible to the SCP adapter.
+
+### RECORDING
+
+**Not supported.** tmux has no structured evidence recording primitive. If
+recording is required, redirect output to a log file from within the shell
+session.
+
+---
+
+## Minimum Version Requirements
+
+| Requirement      | Minimum |
+|:-----------------|:--------|
+| tmux             | 2.0     |
+| `capture-pane -p`| tmux 2.0|
+| `wait-for`       | tmux 2.2|
+| `%N` pane IDs    | tmux 1.6|
+
+---
+
+## odin-watch Integration Pattern
+
+The `TmuxBackend` uses `capture-pane -p` to read pane state. Because EVENTS
+is not supported, the backend operates in **polling mode only**:
+
+1. Read pane content via `capture-pane -p -t {pane}`.
+2. Hash the output to detect changes (`screen_hash`, `screen_changed`).
+3. If the content matches an idle or completion marker, update `WakeState`.
+4. Sleep for the configured `pollIntervalSeconds` and repeat.
+
+There is no interrupt mechanism. The poller must run at a fixed cadence.
+Recommended polling interval: 15–30 seconds for routine supervision;
+5 seconds for time-sensitive gates.
+
+---
+
+## Limitations
+
+- **No EVENTS:** All observation is poll-based. The backend cannot be
+  notified of state changes; it must check on a timer.
+- **No PERSISTENCE:** If the odin-watch process restarts, no journal is
+  available to reconstruct prior state. The backend must re-scan pane
+  content from scratch.
+- **ENTER_PROOF is probabilistic:** Delivery confirmation relies on
+  recognizing expected output in a subsequent `capture-pane`, not on a
+  cryptographic or journal-level proof.
+- **Pane content is ephemeral:** The terminal scrollback is finite;
+  long-running sessions may lose history unless piped to a file.

package/docs/guides/quick-start.md

@@ -32,19 +32,19 @@ step. You are still in control.
 Recommended zero-install path:
 
 ```bash
-pnpm dlx --package @bradheitmann/odin-sentinel@0.4.12 odin-sentinel-mcp
+pnpm dlx --package @bradheitmann/odin-sentinel@0.5.0 odin-sentinel-mcp
 ```
 
 Supported npm global install:
 
 ```bash
-npm i -g @bradheitmann/odin-sentinel@0.4.12
+npm i -g @bradheitmann/odin-sentinel@0.5.0
 ```
 
 Supported npx zero-install path:
 
 ```bash
-npx -y -p @bradheitmann/odin-sentinel@0.4.12 odin-sentinel-mcp
+npx -y -p @bradheitmann/odin-sentinel@0.5.0 odin-sentinel-mcp
 ```
 
 ## 3. Configure MCP
@@ -57,7 +57,7 @@ harness after editing config.
   "mcpServers": {
     "odin-sentinel": {
       "command": "pnpm",
-      "args": ["dlx", "--package", "@bradheitmann/odin-sentinel@0.4.12", "odin-sentinel-mcp"]
+      "args": ["dlx", "--package", "@bradheitmann/odin-sentinel@0.5.0", "odin-sentinel-mcp"]
     }
   }
 }
@@ -90,10 +90,10 @@ Zero-install smoke test:
 
 ```bash
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' \
-  | pnpm dlx --package @bradheitmann/odin-sentinel@0.4.12 odin-sentinel-mcp
+  | pnpm dlx --package @bradheitmann/odin-sentinel@0.5.0 odin-sentinel-mcp
 ```
 
-Expect `serverInfo.name = odin-sentinel` and `serverInfo.version = 0.4.12`.
+Expect `serverInfo.name = odin-sentinel` and `serverInfo.version = 0.5.0`.
 Minimum compatible child MCP version: `0.4.5`.
 
 ## 6. Auth And Provider Readiness
@@ -191,7 +191,7 @@ occupants until readiness passes or EXEC PM records a waiver/substitution.
 | Skill missing | Install the native skill where supported or use `odin.get_bootstrap_skill` as full prompt fallback. |
 | Auth/login required | Ask the user to provision the provider; verify status without printing secrets. |
 | Permission prompt | Stop and route to PM/user; do not bypass silently. |
-| Stale MCP version | Use a pinned `@bradheitmann/odin-sentinel@0.4.12` command, restart host, and confirm `0.4.12`. |
+| Stale MCP version | Use a pinned `@bradheitmann/odin-sentinel@0.5.0` command, restart host, and confirm `0.5.0`. |
 | Local inference stall | Require visible content within timeout; endpoint-only success is insufficient. |
 | Role refusal | Mark the role `NON_GOVERNED_ONE_SHOT_ONLY` unless MCP/skill/full protocol proof is established. |
 | Missing governed uptake proof | Treat as `FIXABLE_BLOCKED` (MCP/skill presence is not uptake): capture and verify a governed-context proof with `scripts/protocol/verify-governed-context.mjs`. |

package/docs/guides/quickstart-prompts.md

@@ -13,7 +13,7 @@ Set up @bradheitmann/odin-sentinel for this machine.
 Rules:
 - Detect first; install only missing prerequisites.
 - Required runtime: Node.js >=22.13.0.
-- Install or use @bradheitmann/odin-sentinel@0.4.12.
+- Install or use @bradheitmann/odin-sentinel@0.5.0.
 - Configure only MCP hosts that already exist on this machine.
 - Do not ask me to paste API keys, tokens, or OAuth values.
 - Verify provider/auth status without printing secret values.
@@ -22,9 +22,9 @@ Rules:
 - Print configured hosts, skipped hosts, package version, and warnings.
 
 Smoke test:
-printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' | odin-sentinel-mcp
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' | pnpm dlx --package @bradheitmann/odin-sentinel@0.5.0 odin-sentinel-mcp
 
-Expected version: 0.4.12.
+Expected version: 0.5.0.
 ```
 
 Restart any host whose MCP config changed.
@@ -37,7 +37,7 @@ Open CMUX first. Paste into the agent that will act as EXEC PM.
 You are A/EXEC-PM. Bootstrap a Sentinel Coordination Protocol governed team in this CMUX workspace.
 
 Procedure:
-1. Call odin.get_version and confirm version 0.4.12 or newer.
+1. Call odin.get_version and confirm version 0.5.0 or newer.
 2. Call odin.get_bootstrap_skill and read the public SCP contract.
 3. Confirm CMUX is active and you are in the same workspace as the team slots.
 4. Compute the target layout with odin.compute_surface_layout using profile=human_cmux_quad.