From 7c2957e777a85b8ad97f3b9491e3fa9bbd341deb Mon Sep 17 00:00:00 2001
From: "Doink (OpenClaw)" <charlie+doink@kindo.ai>
Date: Mon, 9 Mar 2026 14:37:35 -0700
Subject: [PATCH 1/2] docs: audit and align documentation with current codebase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: add missing launch options (--file, --max-file-size,
  --callback-session, --callback-agent, --worktree, --branch),
  fix hook timeout (60s → 300s), rewrite fuse section as generic
  (remove Kind-specific references per ADR-003), fix Prometheus
  metrics (fuses_fired_total → fuses_expired_total, remove
  kind_clusters_deleted_total), update project structure (remove
  merge.ts, add ACP adapter files), add Codex ACP / generic ACP /
  Pi Rust adapter sections, add webhook documentation, update
  architecture description for stateless daemon model
- CHANGELOG: add v1.6.0 entry (ACP adoption, webhooks, callback
  metadata, spawn ENOENT retry)
- Decision 001: update status Proposal → Implemented, mark matrix
  files as shipped, update adapter count
- Decision 004: update status Proposed → Accepted (Phases 1-3
  implemented in v1.4.0), label old architecture as "Previous",
  mark migration phases 1-3 as complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  17 ++
 README.md                                     | 147 +++++++++++++-----
 .../001-parallel-multi-adapter-launch.md      |   9 +-
 docs/decisions/004-stateless-daemon-core.md   |  14 +-
 4 files changed, 133 insertions(+), 54 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9148776..70983d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-03-09
+
+### Added
+
+- Phase 1 ACP adoption — Codex adapter via ACP transport (#125, #127)
+- Lifecycle webhooks for `session.stopped` payloads (#123)
+- Callback metadata (`--callback-session`, `--callback-agent`) for orchestration (#123)
+- Spawn ENOENT retry for adapter launch resilience (#123)
+
+### Fixed
+
+- Webhook emit numeric `exit_status` + compatible HMAC headers (#128)
+
+### Docs
+
+- ADR-001: adopt ACP as primary agent interface (#126)
+
 ## [1.5.0] - 2026-02-26
 
 ### Added
diff --git a/README.md b/README.md
index 6471e37..ce21d8f 100644
--- a/README.md
+++ b/README.md
@@ -4,18 +4,11 @@ Universal interface for supervising coding agents. Launch, monitor, resume, inte
 
 agentctl reads from native sources (Claude Code's `~/.claude/` directory, Pi's `~/.pi/` directory, running processes) and provides a standard control plane to list, inspect, stop, launch, and resume agent sessions. It never replicates state — it reads what's actually happening.
 
-## Layer Model
+## Design Philosophy
 
-| Layer | Role |
-|-------|------|
-| **agentctl** | Read/control interface. Discovers sessions, emits lifecycle events. |
-| **OrgLoop** | Routes lifecycle events to mechanical reactions (cluster fuse, notifications). |
-| **OpenClaw** | Reasoning layer. Makes judgment calls about what to do. |
+agentctl intentionally does **not** maintain its own session registry — it reads native agent sources and cross-references running processes. The daemon tracks only launch metadata, directory locks, and fuse timers. This keeps agentctl grounded in what is actually running, not a shadow copy that drifts out of date.
 
-agentctl intentionally does **not**:
-- Maintain its own session registry (reads native sources)
-- Have a hook/reaction system (that's OrgLoop)
-- Make judgment calls about what to do (that's OpenClaw)
+agentctl provides lightweight operational hooks (lifecycle hooks, webhooks) for reacting to session events, but leaves higher-level judgment — what to do about a failed run, whether to retry, how to route work — to systems above it.
 
 ## Why agentctl?
 
@@ -23,7 +16,7 @@ You can use `claude code` (or any agent CLI) directly — agentctl is not a repl
 
 The practical value is simple: launch work, see what's running, resume interrupted sessions, stop the ones that went sideways, and compare outcomes across adapters without learning a different control surface for each one. That operator UX matters whether the supervisor is a human juggling multiple sessions or another agent coordinating work on your behalf.
 
-What it adds today: session discovery across running agents, lifecycle tracking that persists session info even after processes exit, a daemon with directory locks to prevent duplicate launches on the same working directory, fuse timers for automated resource cleanup, and a standard interface that works the same regardless of which coding agent is underneath. The adapter model means support for additional agent runtimes can be added without changing the CLI or daemon interface.
+What it adds today: session discovery across running agents, lifecycle tracking that persists session info even after processes exit, a daemon with directory locks to prevent duplicate launches on the same working directory, fuse timers for automated resource cleanup, webhooks for external integrations, and a standard interface that works the same regardless of which coding agent is underneath. The adapter model means support for additional agent runtimes can be added without changing the CLI or daemon interface.
 
 The bigger idea is modest but useful: agentctl is a universal control plane for coding agents. It focuses on the operational layer — launch, monitor, resume, interrupt, compare — while leaving native execution to each adapter and higher-level judgment to systems above it.
 
@@ -65,6 +58,9 @@ agentctl launch -p "Read the spec and implement phase 2"
 # Launch in a specific directory
 agentctl launch -p "Fix the auth bug" --cwd ~/code/mono
 
+# Launch with context files
+agentctl launch -p "Implement the feature" --file spec.md --file examples.ts
+
 # Launch a new Pi session
 agentctl launch pi -p "Refactor the auth module"
 
@@ -149,8 +145,9 @@ Array values in `model` are expanded via cross-product.
 
 ```bash
 agentctl list [options]
-  --adapter <name>     Filter by adapter (claude-code, codex, opencode, pi, pi-rust, openclaw)
+  --adapter <name>     Filter by adapter (claude-code, codex, codex-acp, opencode, pi, pi-rust, openclaw)
   --status <status>    Filter by status (running|stopped|idle|error)
+  --group <id>         Filter by launch group (e.g. g-a1b2c3)
   -a, --all            Include stopped sessions (last 7 days)
   --json               Output as JSON
 
@@ -158,18 +155,29 @@ agentctl status <id> [options]
   --adapter <name>     Adapter to use
   --json               Output as JSON
 
-agentctl peek|logs <id> [options]
+agentctl peek <id> [options]
   -n, --lines <n>      Number of recent messages (default: 20)
   --adapter <name>     Adapter to use
 
+agentctl logs <id> [options]
+  -n, --lines <n>      Number of recent messages (default: 50)
+  --adapter <name>     Adapter to use
+
 agentctl launch [adapter] [options]
   -p, --prompt <text>  Prompt to send (required)
   --spec <path>        Spec file path
+  --file <path>        File to include in context (repeatable)
+  --max-file-size <b>  Max file size in bytes (default: 51200)
   --cwd <dir>          Working directory (default: current directory)
   --model <model>      Model to use (e.g. sonnet, opus)
   --adapter <name>     Adapter to launch (repeatable for parallel launch)
   --matrix <file>      YAML matrix file for advanced sweep launch
-  --group <id>         Filter by launch group (for list command)
+  --worktree <repo>    Auto-create git worktree for isolation
+  --branch <name>      Branch name for worktree
+  --on-create <script> Hook: run after session created
+  --on-complete <script> Hook: run after session completes
+  --callback-session <key>  Callback session key for orchestration
+  --callback-agent <id>     Callback agent ID for orchestration
   --force              Override directory locks
 
 When `--cwd` is omitted, the agent launches in the current working directory (`$PWD`). This means you should either `cd` into the target project first or pass `--cwd` explicitly. Launching from an unrelated directory (e.g. `~`) will start the agent in the wrong place.
@@ -186,6 +194,9 @@ agentctl resume <id> <message> [options]
 # Example: resume a stopped session with a follow-up instruction
 agentctl resume abc123 "fix the failing tests and re-run the suite"
 
+agentctl prune
+# Remove dead/stale sessions from daemon state
+
 agentctl events [options]
   --json               Output as NDJSON (default)
 ```
@@ -257,20 +268,48 @@ Hook scripts receive context via environment variables:
 | `AGENTCTL_GROUP` | Launch group ID (in parallel launches) |
 | `AGENTCTL_MODEL` | Model name (when specified) |
 
-Hooks run with a 60-second timeout. If a hook fails, its stderr is printed but execution continues.
+Hooks run with a 300-second (5-minute) timeout. If a hook fails, an error is thrown with the failure details.
 
-### Fuse Timers
+### Webhooks
+
+The daemon can POST a JSON payload to a configured URL whenever a session stops. Configure via environment variables or `~/.agentctl/config.json`:
+
+| Source | Variable / Key |
+|--------|---------------|
+| Env var | `AGENTCTL_WEBHOOK_URL` |
+| Env var | `AGENTCTL_WEBHOOK_SECRET` |
+| Config  | `webhook_url` |
+| Config  | `webhook_secret` |
 
-Fuse timers provide automatic cleanup of [Kind](https://kind.sigs.k8s.io/) Kubernetes clusters tied to coding sessions. When a session exits, agentctl starts a countdown timer. If no new session starts in the same worktree directory before the timer expires, the associated Kind cluster is deleted to free resources.
+Environment variables take precedence over config file values. When a secret is configured, the request includes HMAC-SHA256 signatures in the `X-Agentctl-Signature`, `X-Signature`, and `X-Hub-Signature-256` headers.
+
+Payload shape:
+
+```json
+{
+  "hook_type": "session.stopped",
+  "session_id": "abc123...",
+  "adapter": "claude-code",
+  "duration_seconds": 340,
+  "exit_status": 0,
+  "summary": "Implement the caching layer...",
+  "meta": {},
+  "timestamp": "2026-03-01T12:00:00.000Z"
+}
+```
+
+### Fuse Timers
 
-This is useful when running agents in worktree-per-branch workflows where each branch has its own Kind cluster (e.g. `kindo-charlie-<branch>`). Without fuse timers, forgotten clusters accumulate and waste resources.
+Fuse timers are directory-scoped TTL timers with configurable on-expire actions. When set, a fuse starts a countdown for a given directory. If the timer expires, it can run a shell script, POST to a webhook, or emit a named event.
 
 **How it works:**
 
-1. Agent session exits in a worktree directory (e.g. `~/code/mono-my-feature`)
-2. agentctl derives the cluster name (`kindo-charlie-my-feature`) and starts a fuse timer
-3. If the timer expires (default: configured at daemon startup), the cluster is deleted via `kind delete cluster`
-4. If a new session starts in the same directory before expiry, the fuse is cancelled
+1. A fuse is set for a directory with a TTL (default: 10 minutes)
+2. Optionally, on-expire actions are configured (script, webhook, and/or event)
+3. If the timer expires, the configured actions fire
+4. If the fuse is extended or cancelled before expiry, actions don't fire
+
+Fuse timers are generic and not tied to any specific infrastructure. Consumers (OrgLoop, scripts, webhooks) decide what actions to take on expiry.
 
 ```bash
 # List active fuse timers
@@ -281,14 +320,16 @@ agentctl fuses [options]
 Example output:
 
 ```
-Directory             Cluster                     Expires In
-~/code/mono-feat-x    kindo-charlie-feat-x        12m
-~/code/mono-hotfix    kindo-charlie-hotfix        45m
+Directory                   Expires In
+~/code/mono-feat-x          12m
+~/code/mono-hotfix          45m
 ```
 
 ### Daemon
 
-The daemon provides session tracking, directory locks, fuse timers, and Prometheus metrics. In practice, it's what makes agentctl feel like a reliable supervision surface instead of a thin command wrapper. It auto-starts on first `agentctl` command.
+The daemon provides session tracking, directory locks, fuse timers, webhooks, and Prometheus metrics. It auto-starts on first `agentctl` command and runs under a supervisor that automatically restarts it on crash with exponential backoff.
+
+Set `AGENTCTL_NO_DAEMON=1` to skip the daemon entirely and use direct adapter mode.
 
 ```bash
 agentctl daemon start [options]
@@ -310,34 +351,34 @@ Metrics are exposed at `http://localhost:9200/metrics` in Prometheus text format
 `agentctl events` streams session lifecycle events as NDJSON (newline-delimited JSON). Each line is a self-contained JSON object:
 
 ```json
-{"type":"session.started","adapter":"claude-code","sessionId":"abc123...","timestamp":"2025-06-15T10:30:00.000Z","session":{...}}
-{"type":"session.stopped","adapter":"claude-code","sessionId":"abc123...","timestamp":"2025-06-15T11:00:00.000Z","session":{...}}
-{"type":"session.idle","adapter":"claude-code","sessionId":"def456...","timestamp":"2025-06-15T11:05:00.000Z","session":{...}}
+{"type":"session.started","adapter":"claude-code","sessionId":"abc123...","timestamp":"2026-03-01T10:30:00.000Z","session":{...}}
+{"type":"session.stopped","adapter":"claude-code","sessionId":"abc123...","timestamp":"2026-03-01T11:00:00.000Z","session":{...}}
+{"type":"session.idle","adapter":"claude-code","sessionId":"def456...","timestamp":"2026-03-01T11:05:00.000Z","session":{...}}
 ```
 
 Event types: `session.started`, `session.stopped`, `session.idle`, `session.error`.
 
 The `session` field contains the full session object (id, adapter, status, cwd, model, prompt, tokens, etc.).
 
-**Piping events into OrgLoop (or similar event routers):**
+**Piping events to external systems:**
 
 ```bash
-# Pipe lifecycle events to OrgLoop's webhook endpoint
+# Pipe lifecycle events to a webhook endpoint
 agentctl events | while IFS= read -r event; do
-  curl -s -X POST https://orgloop.example.com/hooks/agentctl \
+  curl -s -X POST https://example.com/hooks/agentctl \
     -H "Content-Type: application/json" \
     -d "$event"
 done
 
 # Or use a persistent pipe with jq filtering
 agentctl events | jq -c 'select(.type == "session.stopped")' | while IFS= read -r event; do
-  curl -s -X POST https://orgloop.example.com/hooks/session-ended \
+  curl -s -X POST https://example.com/hooks/session-ended \
     -H "Content-Type: application/json" \
     -d "$event"
 done
 ```
 
-This pattern works with any webhook-based system — OrgLoop, Zapier, n8n, or a custom event router. The NDJSON format is compatible with standard Unix tools (`jq`, `grep`, `awk`) for filtering and transformation.
+This pattern works with any webhook-based system — Zapier, n8n, or a custom event router. The NDJSON format is compatible with standard Unix tools (`jq`, `grep`, `awk`) for filtering and transformation.
 
 ## Prometheus Metrics
 
@@ -356,8 +397,7 @@ The daemon exposes metrics at `http://localhost:9200/metrics` in Prometheus text
 | Metric | Labels | Description |
 |--------|--------|-------------|
 | `agentctl_sessions_total` | `status="completed"\|"failed"\|"stopped"` | Total sessions by final status |
-| `agentctl_fuses_fired_total` | — | Total fuse timers that fired (clusters deleted) |
-| `agentctl_kind_clusters_deleted_total` | — | Total Kind clusters deleted by fuse timers |
+| `agentctl_fuses_expired_total` | — | Total fuse timers that expired |
 
 ### Histogram
 
@@ -376,9 +416,9 @@ scrape_configs:
 
 ## Architecture
 
-agentctl is structured in three layers: the **CLI** is the operator interface, the **daemon** provides persistent supervision state (session tracking, directory locks, fuse timers, Prometheus metrics), and **adapters** bridge to specific agent runtimes. The CLI communicates with the daemon over a Unix socket at `~/.agentctl/agentctl.sock`.
+agentctl is structured in three layers: the **CLI** is the operator interface, the **daemon** provides persistent supervision state (launch metadata, directory locks, fuse timers, webhooks, Prometheus metrics), and **adapters** bridge to specific agent runtimes. The CLI communicates with the daemon over a Unix socket at `~/.agentctl/agentctl.sock`.
 
-All session state is derived from native sources — agentctl never maintains its own session registry. The Claude Code adapter reads `~/.claude/projects/` and cross-references running processes; the Pi adapter reads `~/.pi/agent/sessions/` JSONL files; other adapters connect to their respective APIs. This keeps agentctl grounded in what is actually running, not a shadow copy that drifts out of date.
+Session state is derived from native adapter sources — `session.list` fans out `discover()` to all adapters in parallel and merges the results with daemon-held launch metadata (prompts, groups, specs). The daemon tracks only what it launched; adapters are the source of truth for session lifecycle. This keeps agentctl grounded in what is actually running, not a shadow copy that drifts out of date.
 
 ## Adapters
 
@@ -424,6 +464,27 @@ Launch uses Pi's print mode (`pi -p "prompt"`) for headless execution. Resume la
 
 Requires the `pi` binary (npm: `@mariozechner/pi-coding-agent`) to be available on PATH.
 
+### Pi Rust
+
+Reads session data from `~/.pi/agent/sessions/` and cross-references with running `pi_agent_rust` processes. Same discovery pattern as the Pi adapter but targeting the Rust implementation.
+
+### Codex ACP
+
+Connects to Codex via the Agent Client Protocol (ACP) transport. Instead of PTY management and session-file scraping, this adapter delegates launch, resume, and lifecycle to ACP using the `@agentclientprotocol/sdk`. This is the first ACP-backed adapter and serves as a reference for migrating other adapters to ACP (see [ADR-001](docs/adr/adr-001-agentctl-adopts-acp.md)).
+
+```bash
+agentctl launch codex-acp -p "implement the feature"
+```
+
+### Generic ACP Adapter
+
+The `src/adapters/acp/` directory provides a reusable ACP adapter that can back any ACP-compatible agent runtime. It includes:
+
+- **AcpClient** — spawns an ACP-compatible agent binary, connects via stdio, and manages the JSON-RPC session
+- **AcpAdapter** — implements the `AgentAdapter` interface on top of `AcpClient`, translating between ACP sessions and agentctl's session model
+
+New agent runtimes with ACP bridges can be added with minimal configuration rather than writing a full bespoke adapter.
+
 ### OpenClaw
 
 Connects to the OpenClaw gateway via WebSocket RPC. Read-only — sessions are managed through the gateway.
@@ -489,17 +550,19 @@ src/
   matrix-parser.ts               # YAML matrix file parser + cross-product expansion
   worktree.ts                    # Git worktree create/list/clean
   hooks.ts                       # Lifecycle hook runner
-  merge.ts                       # Git commit/push/PR for sessions
   adapters/claude-code.ts        # Claude Code adapter
   adapters/codex.ts              # Codex CLI adapter
+  adapters/codex-acp.ts          # Codex via ACP transport
+  adapters/acp/acp-client.ts     # Generic ACP client (spawns agent, manages connection)
+  adapters/acp/acp-adapter.ts    # Generic ACP-backed AgentAdapter implementation
   adapters/openclaw.ts           # OpenClaw gateway adapter
   adapters/opencode.ts           # OpenCode adapter
   adapters/pi.ts                 # Pi coding agent adapter
   adapters/pi-rust.ts            # Pi Rust adapter
-  daemon/server.ts               # Daemon: Unix socket server + HTTP metrics
-  daemon/session-tracker.ts      # Session lifecycle tracking
+  daemon/server.ts               # Daemon: Unix socket server + HTTP metrics + webhooks
+  daemon/session-tracker.ts      # Launch metadata tracking and reconciliation
   daemon/lock-manager.ts         # Directory locks
-  daemon/fuse-engine.ts          # Kind cluster fuse timers
+  daemon/fuse-engine.ts          # Generic directory-scoped TTL fuse timers
   daemon/metrics.ts              # Prometheus metrics registry
   daemon/state.ts                # State persistence
   daemon/launchagent.ts          # macOS LaunchAgent plist generator
diff --git a/docs/decisions/001-parallel-multi-adapter-launch.md b/docs/decisions/001-parallel-multi-adapter-launch.md
index ad66ea2..0bfcc74 100644
--- a/docs/decisions/001-parallel-multi-adapter-launch.md
+++ b/docs/decisions/001-parallel-multi-adapter-launch.md
@@ -1,7 +1,7 @@
 # agentctl: Parallel Multi-Adapter Launch
 
 **Date:** 2026-02-22
-**Status:** Proposal (v3)
+**Status:** Implemented (v1.2.0)
 **Inspiration:** [dmux](https://github.com/standardagents/dmux) by Justin Schroeder (FormKit)
 
 ---
@@ -108,7 +108,7 @@ Adapter + model combos only. Covers 90% of use cases. Clean, composable, no new
 agentctl launch --adapter A --model M1 --adapter A --model M2 --adapter B -p "..."
 ```
 
-**Tier 2 — Matrix file (future, if needed)**
+**Tier 2 — Matrix file (shipped in v1.2.0)**
 For advanced sweeps, a YAML config that defines the matrix:
 
 ```yaml
@@ -128,7 +128,7 @@ matrix:
 agentctl launch --matrix agentctl-matrix.yaml
 ```
 
-This generates the cross-product and launches all variants. But this is explicitly **backlogged** — we build it only if the CLI tier proves insufficient and there's real demand for sweeps.
+This generates the cross-product and launches all variants.
 
 **The key insight:** we don't need to design the matrix interface now. The group/worktree/parallel-launch infrastructure is the same regardless. Tier 2 is just a different way to generate the launch list.
 
@@ -297,7 +297,6 @@ Each worktree gets its own lock. No special group-awareness needed — the exist
 
 ### Backlog
 - AI-generated branch names (weak model)
-- Matrix file (`--matrix config.yaml`) for advanced sweeps
 - Multi-project groups
 - Per-adapter statistics / historical tracking
 
@@ -308,4 +307,4 @@ Each worktree gets its own lock. No special group-awareness needed — the exist
 - [dmux repo](https://github.com/standardagents/dmux)
 - [workmux](https://github.com/raine/workmux) — similar concept
 - [Tweet from @jpschroeder](https://x.com/jpschroeder/status/2024507517359788224)
-- agentctl existing: `src/worktree.ts`, `src/hooks.ts`, lock manager, session tracker, 6 adapters
+- agentctl existing: `src/worktree.ts`, `src/hooks.ts`, lock manager, session tracker, 7+ adapters (claude-code, codex, codex-acp, opencode, pi, pi-rust, openclaw, generic ACP)
diff --git a/docs/decisions/004-stateless-daemon-core.md b/docs/decisions/004-stateless-daemon-core.md
index 63f3075..1f27b5f 100644
--- a/docs/decisions/004-stateless-daemon-core.md
+++ b/docs/decisions/004-stateless-daemon-core.md
@@ -1,6 +1,6 @@
 # ADR 004: Stateless Daemon Core
 
-**Status:** Proposed  
+**Status:** Accepted (Phases 1-3 implemented in v1.4.0)  
 **Date:** 2026-02-24  
 **Author:** Doink (OpenClaw)  
 **Related:** [#51](https://github.com/orgloop/agentctl/issues/51)
@@ -15,7 +15,7 @@ The daemon maintains a `state.json` session registry that mirrors every session
 
 The daemon acts as a **session database** when it should be a **stateless multiplexer**.
 
-## Current Architecture
+## Previous Architecture (before v1.4.0)
 
 ```
 CLI → daemon → StateManager (state.json)
@@ -62,7 +62,7 @@ The adapter interface is **already correct** — `discover()` returns ground tru
 
 All adapters implement the full interface. All are mature. The gap isn't adapter quality — it's the daemon's misuse of adapter output.
 
-## Proposed Architecture: Stateless Core
+## Implemented Architecture: Stateless Core
 
 ```
 CLI → daemon → fan-out to adapters → merge → return
@@ -140,22 +140,22 @@ The lock model is actually fine. The bug (#51) where locks accumulated was becau
 
 ## Migration Path
 
-### Phase 1: Fix the immediate bug (quick)
+### Phase 1: Fix the immediate bug ✅
 - In `poll()`, track which adapter IDs were returned by `discover()`. Sessions in state whose adapter succeeded but whose ID wasn't returned → mark stopped + autoUnlock.
 - This stops the accumulation without architectural change.
 
-### Phase 2: Make `session.list` adapter-first (medium)
+### Phase 2: Make `session.list` adapter-first ✅
 - Change `session.list` handler to fan out `discover()` to adapters
 - Enrich with daemon launch metadata (prompt, group, spec)
 - Keep `StateManager.sessions` as a **write-through cache** for launch metadata only
 - Remove the 5s polling loop
 
-### Phase 3: Clean up (small)
+### Phase 3: Clean up ✅
 - Remove `SessionTracker.poll()`, `reapStaleEntries()`, all pruning code
 - Simplify `StateManager` to only persist launch metadata, locks, fuses
 - Remove `state.json` session entries (or reduce to launch-metadata-only)
 
-### Phase 4: Separate launch metadata from session state
+### Phase 4: Separate launch metadata from session state (not started)
 - New `launches.json` (small, ~10 entries) replaces sessions in `state.json`
 - `state.json` becomes locks + fuses only
 - Clean separation of concerns

From 5328b6222fcf9602302fc22dfe30ecc219bec544 Mon Sep 17 00:00:00 2001
From: "Doink (OpenClaw)" <charlie+doink@kindo.ai>
Date: Mon, 9 Mar 2026 14:46:41 -0700
Subject: [PATCH 2/2] docs: fix changelog dates, env var prefixes, and complete
 audit alignment

- Fix CHANGELOG version dates to match actual git tags (v1.6.0=2026-03-06,
  v1.5.2=2026-03-02, v1.5.1=2026-02-27, v1.5.0=2026-02-25)
- Fix AGENTS.md hook env vars to use correct AGENTCTL_ prefix
- Add missing files to AGENTS.md project structure (supervisor, webhook,
  file-context, utils)
- Backfill CHANGELOG entries for v1.5.1, v1.5.2, v1.6.0
- Move post-v1.6.0 work into [Unreleased] section
- Update README: AgentAdapter interface, config file docs, directory
  structure, supervisor.pid, and release workflow description

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 AGENTS.md    | 12 ++++++++++--
 CHANGELOG.md | 35 ++++++++++++++++++++++++++++++++---
 README.md    | 44 ++++++++++++++++++++++++++++++++++++--------
 3 files changed, 78 insertions(+), 13 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5f17ba5..2ad6a7f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,15 +36,23 @@ npm run lint:fix   # biome check --write
 - `src/launch-orchestrator.ts` — Parallel multi-adapter launch orchestration (group IDs, worktree creation, parallel dispatch)
 - `src/matrix-parser.ts` — YAML matrix file parser + cross-product expansion for sweep launches
 - `src/worktree.ts` — Git worktree create/list/clean utilities
-- `src/hooks.ts` — Lifecycle hook runner (env vars: SESSION_ID, CWD, ADAPTER, BRANCH, EXIT_CODE, GROUP, MODEL)
+- `src/hooks.ts` — Lifecycle hook runner (env vars: AGENTCTL_SESSION_ID, AGENTCTL_CWD, AGENTCTL_ADAPTER, AGENTCTL_BRANCH, AGENTCTL_EXIT_CODE, AGENTCTL_GROUP, AGENTCTL_MODEL)
 - `src/cli.ts` — CLI entry point (commander)
 - `src/daemon/server.ts` — Daemon: Unix socket server + HTTP metrics
+- `src/daemon/supervisor.ts` — Daemon supervisor (auto-restart on crash)
 - `src/daemon/session-tracker.ts` — Session lifecycle tracking
 - `src/daemon/lock-manager.ts` — Auto + manual directory locks
 - `src/daemon/fuse-engine.ts` — Generic directory-scoped TTL fuse timers with configurable on-expire actions
+- `src/daemon/webhook.ts` — Webhook event emission (session.stopped)
 - `src/daemon/metrics.ts` — Prometheus metrics registry
 - `src/daemon/state.ts` — State persistence layer
 - `src/client/daemon-client.ts` — Unix socket client for CLI
+- `src/file-context.ts` — File context builder (--file/--spec flags)
+- `src/utils/config.ts` — Configuration loading (~/.agentctl/config.json)
+- `src/utils/resolve-binary.ts` — Binary path resolution
+- `src/utils/prompt-file.ts` — Prompt file handling (large prompts via temp files)
+- `src/utils/spawn-with-retry.ts` — Spawn with ENOENT retry
+- `src/utils/display.ts` — Display formatting utilities
 - `src/migration/migrate-locks.ts` — Migration from ~/.openclaw/locks
 
 ## Conventions
@@ -65,7 +73,7 @@ npm run lint:fix   # biome check --write
 ./scripts/release.sh [patch|minor|major]
 ```
 
-Bumps version, builds, tags, and runs `npm link`. No npm publish (local tool).
+Bumps version, builds, and pushes release branch. Tag push triggers npm publish via GitHub Actions. See RELEASING.md for full workflow.
 
 ## CI
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70983d8..deec9c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,24 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [1.6.0] - 2026-03-09
-
 ### Added
 
 - Phase 1 ACP adoption — Codex adapter via ACP transport (#125, #127)
 - Lifecycle webhooks for `session.stopped` payloads (#123)
 - Callback metadata (`--callback-session`, `--callback-agent`) for orchestration (#123)
 - Spawn ENOENT retry for adapter launch resilience (#123)
+- Complete stateless daemon core — eliminate remaining shadow state (#117)
 
 ### Fixed
 
+- Eliminate pending- session IDs — resolve real ID at launch (#131)
 - Webhook emit numeric `exit_status` + compatible HMAC headers (#128)
+- Eliminate daemon-env.json — derive env at spawn time (#119)
+- Update resolve-binary util (#121)
 
 ### Docs
 
 - ADR-001: adopt ACP as primary agent interface (#126)
 
-## [1.5.0] - 2026-02-26
+## [1.6.0] - 2026-03-06
+
+### Added
+
+- `--file` flag to include context files in launch prompts (#95)
+- Use `history.jsonl` for Claude Code discover(), batch `lsof` calls (#96)
+
+### Fixed
+
+- Insert `--` separator before positional prompt args in codex/opencode/pi-rust (#106)
+- Peek/status timeout on opencode sessions (#100)
+- Use temp file for large prompts instead of CLI args (#101)
+
+## [1.5.2] - 2026-03-02
+
+### Fixed
+
+- OpenCode detach, matrix prompt override, persistent config defaults (#87)
+- Worktree slug collisions, pi-rust `--provider`/`--append-system-prompt` (#83)
+- Pass `--model` flag when launching OpenCode (#79)
+
+## [1.5.1] - 2026-02-27
+
+### Fixed
+
+- Resolve P0+P1 launcher/docs regressions (#76)
+
+## [1.5.0] - 2026-02-25
 
 ### Added
 
diff --git a/README.md b/README.md
index ce21d8f..adc318c 100644
--- a/README.md
+++ b/README.md
@@ -309,7 +309,7 @@ Fuse timers are directory-scoped TTL timers with configurable on-expire actions.
 3. If the timer expires, the configured actions fire
 4. If the fuse is extended or cancelled before expiry, actions don't fire
 
-Fuse timers are generic and not tied to any specific infrastructure. Consumers (OrgLoop, scripts, webhooks) decide what actions to take on expiry.
+Fuse timers are generic and not tied to any specific infrastructure. Consumers decide what actions to take on expiry.
 
 ```bash
 # List active fuse timers
@@ -498,6 +498,8 @@ Implement the `AgentAdapter` interface:
 ```typescript
 interface AgentAdapter {
   id: string;
+  discover(): Promise<DiscoveredSession[]>;
+  isAlive(sessionId: string): Promise<boolean>;
   list(opts?: ListOpts): Promise<AgentSession[]>;
   peek(sessionId: string, opts?: PeekOpts): Promise<string>;
   status(sessionId: string): Promise<AgentSession>;
@@ -508,21 +510,39 @@ interface AgentAdapter {
 }
 ```
 
+The key methods are `discover()` (ground-truth session state from the adapter's runtime) and `isAlive()` (lightweight liveness check). The `list()` method delegates to `discover()` with filtering.
+
 ## Configuration
 
 agentctl stores daemon state in `~/.agentctl/`:
 
 ```
 ~/.agentctl/
+  config.json            # Persistent config defaults (optional)
   agentctl.sock          # Unix socket for CLI ↔ daemon communication
   agentctl.pid           # Daemon PID file
-  state.json             # Session tracking state
+  supervisor.pid         # Supervisor PID file
+  state.json             # Launch metadata
   locks.json             # Directory locks
   fuses.json             # Fuse timers
   daemon.stdout.log      # Daemon stdout
   daemon.stderr.log      # Daemon stderr
 ```
 
+### Config File
+
+`~/.agentctl/config.json` provides persistent defaults that CLI flags override:
+
+```json
+{
+  "adapter": "claude-code",
+  "model": "claude-sonnet-4-5",
+  "cwd": "~/code/mono",
+  "webhook_url": "https://example.com/hooks/agentctl",
+  "webhook_secret": "your-hmac-secret"
+}
+```
+
 ## Development
 
 ```bash
@@ -545,28 +565,36 @@ npm run lint          # biome check
 ```
 src/
   cli.ts                         # CLI entry point (commander)
-  core/types.ts                  # Core interfaces
+  core/types.ts                  # Core interfaces (AgentAdapter, DiscoveredSession, etc.)
   launch-orchestrator.ts         # Parallel multi-adapter launch orchestration
   matrix-parser.ts               # YAML matrix file parser + cross-product expansion
   worktree.ts                    # Git worktree create/list/clean
   hooks.ts                       # Lifecycle hook runner
+  file-context.ts                # File context builder (--file/--spec)
   adapters/claude-code.ts        # Claude Code adapter
   adapters/codex.ts              # Codex CLI adapter
   adapters/codex-acp.ts          # Codex via ACP transport
-  adapters/acp/acp-client.ts     # Generic ACP client (spawns agent, manages connection)
-  adapters/acp/acp-adapter.ts    # Generic ACP-backed AgentAdapter implementation
+  adapters/acp/acp-client.ts     # Generic ACP client
+  adapters/acp/acp-adapter.ts    # Generic ACP-backed AgentAdapter
   adapters/openclaw.ts           # OpenClaw gateway adapter
   adapters/opencode.ts           # OpenCode adapter
   adapters/pi.ts                 # Pi coding agent adapter
   adapters/pi-rust.ts            # Pi Rust adapter
-  daemon/server.ts               # Daemon: Unix socket server + HTTP metrics + webhooks
+  daemon/server.ts               # Daemon: Unix socket server + HTTP metrics
+  daemon/supervisor.ts           # Daemon supervisor (auto-restart on crash)
   daemon/session-tracker.ts      # Launch metadata tracking and reconciliation
-  daemon/lock-manager.ts         # Directory locks
-  daemon/fuse-engine.ts          # Generic directory-scoped TTL fuse timers
+  daemon/lock-manager.ts         # Auto + manual directory locks
+  daemon/fuse-engine.ts          # Directory-scoped TTL fuse timers
+  daemon/webhook.ts              # Webhook event emission
   daemon/metrics.ts              # Prometheus metrics registry
   daemon/state.ts                # State persistence
   daemon/launchagent.ts          # macOS LaunchAgent plist generator
   client/daemon-client.ts        # Unix socket client
+  utils/config.ts                # Configuration loading
+  utils/display.ts               # Display formatting utilities
+  utils/resolve-binary.ts        # Binary path resolution
+  utils/prompt-file.ts           # Prompt file handling (large prompts)
+  utils/spawn-with-retry.ts      # Spawn with ENOENT retry
   migration/migrate-locks.ts     # Migration from legacy locks
 ```