feat(acp): add Herdr-owned production runtime path

.env.example

@@ -80,18 +80,24 @@ TENDWIRE_STORE_MAINTENANCE_CADENCE_SECONDS=3600
 # Optional stable host label for the local machine.
 # TENDWIRE_HOST_ID=my-host
 
-# Optional Herdr binary and timeout overrides. Turn-adapter reads use the same
-# timeout.
+# Optional Herdr binary and timeout overrides. Herdr supplies worker/pane
+# lifecycle and owns ACP endpoints; it is not an agent transcript transport.
+# Initial socket reconciliation has a separate whole-startup budget so a
+# multi-call inventory can exceed one RPC without weakening normal deadlines.
 # TENDWIRE_HERDR_BIN=herdr
 TENDWIRE_HERDR_TIMEOUT_SECONDS=1.0
+TENDWIRE_HERDR_INITIAL_RECONCILE_TIMEOUT_SECONDS=120.0
 
-# Daemon-owned turn-ingestion cadence and dedicated worker pool. Defaults are
-# 2.0 seconds and 4 workers; the worker count cannot exceed
-# TENDWIRE_MAX_WORKERS. The internal refresh queue is fixed at 64.
-TENDWIRE_TURN_REFRESH_INTERVAL_SECONDS=2.0
-TENDWIRE_TURN_REFRESH_WORKERS=4
-# Compatibility flag: legacy|dual|shadow|observed all use the observed model.
-TENDWIRE_TURN_MODEL=observed
+# ACP is required for every supported agent. The daemon fails closed when a
+# worker lacks a healthy Herdr-owned ACP endpoint; there is no transcript,
+# shadow, preferred, or fallback mode. Stable ACP v1 does not distinguish raw
+# reasoning from summaries. The safe
+# default discards thought chunks. `private_summary` is an explicit trusted-
+# adapter convention; `private_all` retains all thoughts for local diagnostics.
+TENDWIRE_ACP_THOUGHT_POLICY=disabled
+TENDWIRE_ACP_REQUEST_TIMEOUT_SECONDS=30
+TENDWIRE_ACP_SHUTDOWN_TIMEOUT_SECONDS=5
+TENDWIRE_ACP_MAX_FRAME_BYTES=8388608
 
 # Process-local bounded LRU for repeated public-text sanitization. Set to 0 to
 # disable; values above 65536 are capped. The default covers typical retained

README.md

@@ -29,11 +29,12 @@ background daemon; use [INSTALL.md](INSTALL.md) for persistent service setup.
 
 ## Relationship to Herdr, Herdres, and connectors
 
-Herdr is the only concrete runtime backend documented here. Tendwire can observe
-Herdr through the conservative CLI one-shot path or, when explicitly enabled,
-through the Herdr socket/event backend. Both paths normalize Herdr state into
-neutral Tendwire spaces, workers, attention, turns, pending interactions,
-command results, connector jobs, and backend health.
+Herdr supplies workspace, pane, and worker lifecycle plus ownership of private
+ACP endpoints. Tendwire can observe that lifecycle through the conservative CLI
+one-shot path or the Herdr socket/event backend. ACP is required for supported
+agent semantics and commands; Herdr is not used to read transcripts or inject
+pane input. The authority and privacy split is defined in
+[docs/acp-migration.md](docs/acp-migration.md).
 
 Herdres can use Tendwire as its source/control plane while Herdres remains the
 Telegram connector. Tendwire owns Herdr observation, private bindings,
@@ -175,6 +176,11 @@ not expose raw backend argv. The Herdr binary path, data directory, and database
 path expand `~`; each Herdr probe uses `TENDWIRE_HERDR_TIMEOUT_SECONDS` or
 `--herdr-timeout` when set, defaulting to 5.0 seconds.
 
+Socket-daemon startup waits up to
+`TENDWIRE_HERDR_INITIAL_RECONCILE_TIMEOUT_SECONDS` (default `120.0`) for the
+entire initial reconciliation. This startup-only budget does not change the
+normal per-RPC `TENDWIRE_HERDR_TIMEOUT_SECONDS` deadline.
+
 When Herdr 0.7.0 is present, the adapter first tries the no-flag JSON envelopes
 (`herdr workspace list`, `herdr agent list`) that wrap records under
 `result.workspaces` and `result.agents`, then keeps `--json` list variants as a
@@ -545,9 +551,10 @@ variables:
 | `snapshot_retention_count` | `TENDWIRE_SNAPSHOT_RETENTION_COUNT` | `4096` | positive integer; includes each host's latest row |
 | `snapshot_maintenance_batch_size` | `TENDWIRE_SNAPSHOT_MAINTENANCE_BATCH_SIZE` | `100` | integer from 1 through 1000 |
 | `store_maintenance_cadence_seconds` | `TENDWIRE_STORE_MAINTENANCE_CADENCE_SECONDS` | `3600` | positive integer |
-| `turn_refresh_interval_seconds` | `TENDWIRE_TURN_REFRESH_INTERVAL_SECONDS` | `2.0` | finite positive float |
-| `turn_refresh_workers` | `TENDWIRE_TURN_REFRESH_WORKERS` | `4` | integer from 1 through 32 and no greater than `max_workers` |
-| `turn_model` | `TENDWIRE_TURN_MODEL` | `observed` | `observed`; `legacy`, `dual`, and `shadow` are deprecated aliases with identical observed behavior |
+| `acp_thought_policy` | `TENDWIRE_ACP_THOUGHT_POLICY` | `disabled` | `disabled`, `private_summary`, or `private_all`; never a public-delivery grant |
+| `acp_request_timeout_seconds` | `TENDWIRE_ACP_REQUEST_TIMEOUT_SECONDS` | `30.0` | finite positive float |
+| `acp_shutdown_timeout_seconds` | `TENDWIRE_ACP_SHUTDOWN_TIMEOUT_SECONDS` | `5.0` | finite positive float |
+| `acp_max_frame_bytes` | `TENDWIRE_ACP_MAX_FRAME_BYTES` | `8388608` | integer from 1 through 67108864 |
 
 The socket/event backend uses `event_debounce_seconds` for event batching and
 `reconcile_interval_seconds` for bounded periodic full reconciles. Set
@@ -560,6 +567,34 @@ snapshot/projections instead of publishing a truncated authoritative snapshot.
 Incremental events that would add workers over the cap are ignored with the
 same public-safe degraded evidence.
 
+The stock daemon requires ACP for supported agents. It uses Herdr's private
+`agent.acp_endpoint` contract and accepts only workers explicitly marked
+`acp_owned_ready`; ordinary PTY workers are never attached as sidecars. A
+missing or unhealthy ACP endpoint degrades daemon health and fails command
+submission closed. There is no transcript-reader scheduler, shadow/preferred
+mode, or PTY fallback.
+Production ACP uses a bounded per-worker permission broker. It publishes only
+the sanitized tool title and numeric choices (option label and kind) through
+the durable pending-decision surface; ACP option IDs, arguments, session IDs,
+and adapter metadata remain private. `answer_decision` is fenced to the exact
+worker binding, ACP session, and Herdr generation. A command is accepted only
+after the complete JSON-RPC permission-response frame is written. Missing or
+retired ACP authority fails closed without falling back to PTY input, and
+concurrent answers can produce at most one response. None of this makes agent
+thoughts public: thought events remain private diagnostic data unless a
+separate, explicit sanitized projection is introduced.
+
+Store maintenance retires expired structured agent-event payloads in bounded
+batches using `event_retention_days`. Compact identity tombstones remain so a
+replayed source event cannot be reinserted or silently change content after its
+private payload has expired. Due automatic daemon maintenance performs the same
+host-scoped retirement as explicit `store cleanup`, using a metadata-only scan
+that does not load private payloads. Tombstones intentionally retain bounded
+per-event hashes and opaque identity only; they are not a recoverable copy of the
+removed payload. Their count is permanent and grows with distinct source-event
+identities. SQLite secure deletion is best-effort page hygiene, not a promise of
+immediate physical erasure across WAL/checkpoints, snapshots, or backups.
+
 Snapshot history defaults are sized for a five-minute observation rhythm:
 $14 \times 24 \times 12 = 4032$ observations, while the 4096-row count
 ceiling (including the latest row) leaves 64 rows of headroom. This is a
@@ -1466,10 +1501,6 @@ metadata and does not change observation-derived turn identity, turn-list order,
 Goal 10 delivery, or Herdres consumption. Lazy and periodic settlement cover
 both submission-first and observation-first arrival order.
 
-`TENDWIRE_TURN_MODEL` remains accepted for rollout compatibility. `legacy`,
-`dual`, and `shadow` emit a warning and use the same observation-authoritative
-behavior as `observed`.
-
 `disposition`, not `status` alone, is the receipt-authority and finality
 contract:
 

docs/acp-adapter-probe.md

@@ -0,0 +1,67 @@
+# Black-box ACP adapter initialization probe
+
+Tendwire treats an ACP adapter as a separately installed executable. The
+adapter is not vendored, imported, rebased, or coupled to a repository layout.
+Run the initialization probe after installing or upgrading any adapter and
+before promoting that executable into the Tendwire runtime:
+
+```console
+python -m tendwire.backends.acp_probe -- /absolute/path/to/adapter adapter-arg
+```
+
+The command starts the supplied argv directly without a shell, negotiates ACP
+v1 capabilities on a fresh process, closes the process, prints one bounded JSON
+object, and exits zero only when negotiation and shutdown succeed. Use
+`--timeout`, `--close-timeout`, and an absolute `--cwd` before the `--` marker
+when needed. Probe timeouts have hard upper bounds.
+
+The probe scope is deliberately limited to `initialize`. It does not create a
+session, send a prompt, spend model tokens, or claim that the adapter actually
+implements ACP's mandatory baseline session methods. The output contains fixed
+booleans for optional capabilities advertised by the agent, bounded counts for
+schema-valid authentication methods and `_meta` capability-extension
+namespaces, a process-reaped flag, and a fixed failure category. It never
+contains:
+
+- adapter argv or executable paths;
+- working directories or environment values;
+- stderr, exception text, or raw JSON-RPC payloads;
+- agent-provided names, versions, extension names, or extension values;
+- session IDs, messages, thoughts, tool data, plans, or authentication values.
+
+Example successful shape:
+
+```json
+{
+  "authentication": {"method_count": 0, "method_count_capped": false},
+  "advertised_capabilities": {
+    "additional_directories": true,
+    "auth_logout": false,
+    "mcp_http": false,
+    "mcp_sse": false,
+    "prompt_audio": false,
+    "prompt_embedded_context": false,
+    "prompt_image": false,
+    "session_close": true,
+    "session_delete": true,
+    "session_list": true,
+    "session_load": true,
+    "session_resume": true
+  },
+  "initialization_compatible": true,
+  "extensions": {"capability_count": 0, "capability_count_capped": false},
+  "failure": null,
+  "probe_scope": "initialize",
+  "process_reaped": true,
+  "protocol_version": 1,
+  "schema_version": 2
+}
+```
+
+An initialization-incompatible result exits with status 1 and reports only one
+of these stable categories: `invalid_configuration`, `launch_failed`, `timeout`,
+`protocol_version`, `protocol_error`, `transport_error`, `shutdown_failed`, or
+`internal_error`. Keep the previously proven executable available for rollback;
+the probe validates initialization and advertised capability parsing, not
+account authentication, mandatory baseline method behavior, or a stateful agent
+session.

docs/acp-migration.md

@@ -0,0 +1,106 @@
+# ACP-required architecture
+
+ACP is Tendwire's required semantic and command protocol for every supported
+agent. This is a release boundary, not a runtime rollout switch: rollback means
+deploying an earlier release. There are no legacy, shadow, preferred, dual, or
+fallback modes in the daemon.
+
+## Authority split
+
+| Concern | Authority |
+| --- | --- |
+| Workspace, pane, worker lifecycle, and ACP endpoint ownership | Herdr |
+| Public stable worker identity | Tendwire's authenticated Herdr projection |
+| Agent session, messages, tools, plans, usage, and permissions | ACP |
+| Durable journal, public turn projection, privacy, and finality | Tendwire |
+| Command idempotency and uncertain outcomes | Tendwire receipts |
+| Connector retry and delivery state | Tendwire outbox |
+| Telegram presentation | Herdres |
+
+Herdr is not a transcript or command-input transport. Tendwire consumes its
+worker/pane lifecycle events, verifies the worker generation, and asks it to
+mint a one-shot private ACP endpoint. A supported worker without an explicitly
+Herdr-owned healthy ACP endpoint is unavailable and degrades ACP health.
+
+An ACP `sessionId`, endpoint ticket, adapter command, terminal ID, and pane ID
+are private. Tendwire binds the session to the current private worker binding
+and rejects updates or commands after that generation moves, expires, or is
+replaced.
+
+## Runtime and protocol boundary
+
+The daemon supervises one ACP worker session for each eligible Herdr worker.
+The supervisor owns reconciliation, generation fencing, reconnect, console
+exchange, and command routing. The worker session owns initialize, session
+open/load/resume, update draining, permission handling, cancellation, and
+bounded shutdown. The bounded connection owns subprocess I/O, JSON-RPC request
+correlation, framing limits, stderr limits, and backpressure.
+
+Tendwire uses the official `agent-client-protocol` Python package for generated
+ACP schemas and validation. Tendwire retains its bounded stdio connection
+because its hard frame-size, queue, write-deadline, shutdown, and privacy
+requirements are stricter than the upstream convenience transport. Adapter
+executables remain separately installed and replaceable; no adapter source tree
+is imported or vendored.
+
+Before every prompt and during reconciliation, Tendwire verifies Herdr's
+non-mutating ACP status for the exact worker generation. Reconnect always asks
+Herdr for a fresh one-shot endpoint. A missing route fails before receipt
+reservation; a failure after the durable `send_started` boundary is terminally
+uncertain and is never retried through another transport.
+
+## Durable projection and privacy
+
+The structured journal accepts user and agent messages, thoughts, tool calls,
+tool updates, plans, usage, session information, and private extension/control
+updates. Producer identity and raw ACP payloads are retained only on the
+private side. The public turn projection remains deliberately narrower and
+continues to drive finality and connector eligibility.
+
+`TENDWIRE_ACP_THOUGHT_POLICY` controls private thought retention:
+
+- `disabled` discards thoughts before persistence.
+- `private_summary` retains only updates carrying Tendwire's exact trusted
+  summary marker.
+- `private_all` retains raw thought chunks for explicit local diagnostics.
+
+No thought policy grants public or outbox delivery. Raw reasoning, tool input,
+tool output, session IDs, paths, terminal data, and adapter metadata must remain
+outside every public API and connector payload.
+
+ACP permission requests use the durable pending-decision projection. Only a
+sanitized title and numbered public choices are exposed. The private option ID,
+tool call, arguments, ACP session, and metadata remain behind the boundary.
+`answer_decision` is fenced to the exact worker binding and generation and is
+accepted only after the full JSON-RPC response frame is written.
+
+## Retention and replay
+
+`event_retention_days` bounds private structured-event payloads. Cleanup
+replaces expired payloads with compact identity tombstones so exact replays
+remain idempotent and conflicting producer-identity reuse fails closed.
+Tombstones preserve only bounded replay evidence and authority time; they are
+not recoverable event content.
+
+Tendwire continues to own durable command receipts and its neutral connector
+outbox. ACP adapter restarts therefore do not erase accepted-command evidence,
+turn finality, acknowledgement state, or delivery retries.
+
+## Release and conformance gates
+
+An ACP-required release must pass:
+
+- initialization and official-schema validation against each supported
+  adapter;
+- new/load/resume, prompt, steering, cancellation, and permission flows;
+- generation fencing and reconnect with freshly minted Herdr endpoints;
+- no missing or duplicated user/final messages across adapter restarts;
+- deterministic replay deduplication and exactly-once final projection;
+- complete tool and plan lifecycle after cancellation or permission denial;
+- absence of raw thoughts, tool payloads, session IDs, and terminal data from
+  public APIs and the outbox;
+- durable receipt behavior at every pre-send and post-send failure boundary;
+- exact worker continuity across Herdr pane moves and agent recreation.
+
+If a release fails these gates, roll back the release. Do not reintroduce a
+runtime fallback mode.