feat(durable-journal): harden append strictness, invariants, and chaos coverage

Author: tryingET

AGENTS.md

@@ -737,6 +737,37 @@ function sendWithStdioBackpressure(
 
 ---
 
+## ADR-0019: Durable Command Journal Foundation
+
+**Status:** Accepted (2026-03-02)
+
+Full ADR: `docs/adr/0019-durable-command-journal-foundation.md`
+
+### The Invariant
+
+> Explicit client-provided command IDs must remain deterministic across process restarts.
+
+### Foundation Rules
+
+1. **Append lifecycle durably** - `command_accepted`, `command_started`, `command_finished` are persisted in append-only JSONL when `durableJournal.enabled=true`
+2. **Per-lane monotonic sequence** - each record carries `laneSequence`, resumed from max seen value during startup rehydration
+3. **Recover in-flight explicitly** - explicit IDs left in accepted/started state at crash are deterministically marked failed and written as synthetic recovery `command_finished` records
+4. **Conservative schema policy** - malformed or unsupported schema versions are skipped and counted; no implicit migration in foundation
+5. **Bound observability payloads** - startup recovery and history query responses are bounded with truncation metadata
+6. **Explicit append strictness policy** - `durableJournal.appendFailurePolicy` controls behavior (`best_effort` vs `fail_closed`)
+7. **Redaction hooks at durability seams** - `durableJournal.redaction.beforePersist` and `.beforeExport` support policy-driven data minimization
+
+### Key Properties
+
+1. **Feature-flagged rollout** - defaults off (`durableJournal.enabled=false`) for rollback safety
+2. **Replay continuity** - recovered explicit outcomes are rehydrated into replay store before serving commands
+3. **Failure-path observability** - `get_startup_recovery` and `get_command_history` remain usable for diagnostics when append strict mode latches durable state failed
+4. **Bounded introspection** - `get_command_history` provides filtered journal access (session filter, command ID, time window) with capped response size
+5. **Retention + compaction scaffold** - `durableJournal.retention.{maxEntries,maxAgeMs,maxBytes}` prunes stale terminal outcomes while preserving in-flight recovery semantics
+6. **Chaos-hardened malformed handling** - partial/truncated lines are safely skipped during recovery and compaction without corrupting retained replay semantics
+
+---
+
 ## Pattern: Settled Flag for Promise Races
 
 **Status:** Accepted (2026-02-28)
@@ -1138,10 +1169,10 @@ Fuzz test coverage:
 ### Running All Tests
 
 ```bash
-npm test                    # 83 unit tests
-npm run test:integration   # 26 integration tests
-npm run test:fuzz          # 17 fuzz tests
-# Module tests (141 total)
+npm test                    # Main test suite
+npm run test:integration   # Integration tests
+npm run test:fuzz          # Fuzz tests
+# Module tests
 node --experimental-vm-modules dist/test-command-classification.js
 node --experimental-vm-modules dist/test-session-version-store.js
 node --experimental-vm-modules dist/test-command-replay-store.js

PROTOCOL.md

@@ -156,13 +156,14 @@ Optional fields:
 Server emits these event families:
 
 1. `server_ready`
-2. `server_shutdown`
-3. `session_created`
-4. `session_deleted`
-5. `event` (session-scoped AgentSession event)
-6. `command_accepted`
-7. `command_started`
-8. `command_finished`
+2. `startup_recovery_summary` (convenience; endpoint-first flow remains canonical)
+3. `server_shutdown`
+4. `session_created`
+5. `session_deleted`
+6. `event` (session-scoped AgentSession event)
+7. `command_accepted`
+8. `command_started`
+9. `command_finished`
 
 ### 6.1 Session-scoped AgentSession events
 
@@ -337,7 +338,7 @@ Conformant clients:
 
 1. No global total ordering (lane determinism only).
 2. Timeout does not prove cancellation completed.
-3. Durable replay beyond process lifetime is partially implemented behind a feature flag (`durableJournal.enabled`); full history/replay APIs remain Level 4 work.
+3. Durable replay beyond process lifetime is feature-flagged (`durableJournal.enabled`). `get_command_history` is available for bounded journal introspection; deterministic replay/export tooling remains Level 4 work.
 
 ---
 
@@ -360,7 +361,39 @@ Emitted on connection before any other messages. Announces server capabilities.
 
 Clients SHOULD check `protocolVersion` for compatibility.
 
-### 16.2 `server_shutdown`
+### 16.2 `startup_recovery_summary`
+
+Optional convenience event carrying the same payload schema as `get_startup_recovery`.
+
+By default, servers MAY redact sensitive fields in this event (for example: `journalPath`, `initializationError`, `recoveredOutcomeIds`, `recoveredInFlight`). Full diagnostics remain available via explicit `get_startup_recovery` requests.
+
+```json
+{
+  "type": "startup_recovery_summary",
+  "data": {
+    "enabled": true,
+    "initialized": true,
+    "initState": "ready",
+    "initializationError": "Initialization failed (details redacted; call get_startup_recovery for full diagnostics)",
+    "journalPath": "[redacted]",
+    "schemaVersion": 1,
+    "entriesScanned": 0,
+    "malformedEntries": 0,
+    "unsupportedVersionEntries": 0,
+    "recoveredOutcomes": 0,
+    "recoveredOutcomeIds": [],
+    "recoveredOutcomeIdsTruncated": false,
+    "recoveredInFlightFailures": 0,
+    "recoveredInFlight": [],
+    "recoveredInFlightTruncated": false,
+    "maxItemsReturned": 100
+  }
+}
+```
+
+This event is advisory. Clients SHOULD continue using `get_startup_recovery` as the canonical endpoint. Deployments that need full event detail can opt in via server configuration (`PiServerOptions.startupRecoverySummaryEvent.includeSensitiveData = true`).
+
+### 16.3 `server_shutdown`
 
 Emitted before server closes. Clients should expect connection termination.
 
@@ -388,11 +421,35 @@ Emitted before server closes. Clients should expect connection termination.
 | `switch_session` | Subscribe to session | `{ sessionInfo }` |
 | `get_metrics` | Server metrics | See `get_metrics` response |
 | `health_check` | Health status | `{ healthy, issues, hasOpenCircuit, hasOpenBashCircuit }` |
+| `get_startup_recovery` | Startup durable-journal recovery summary | `{ enabled, initialized, initState, initializationError?, journalPath, schemaVersion, entriesScanned, malformedEntries, unsupportedVersionEntries, recoveredOutcomes, recoveredOutcomeIds, recoveredOutcomeIdsTruncated, recoveredInFlightFailures, recoveredInFlight, recoveredInFlightTruncated, maxItemsReturned }` |
+| `get_command_history` | Bounded durable journal history query (ADR-0019) | `{ enabled, initialized, initState, initializationError?, journalPath, schemaVersion, filters, entries, returned, truncated, maxItemsReturned, maxItemsAllowed }` |
 | `list_stored_sessions` | List persisted sessions (ADR-0007) | `{ sessions: StoredSessionInfo[] }` |
 | `load_session` | Load session from disk (ADR-0007) | `{ sessionId, sessionInfo }` |
 
 > **Note:** `delete_session` unloads the session from server memory but does NOT delete the session file from disk. The session can be reloaded later via `load_session` or discovered via `list_stored_sessions`.
 
+#### `get_command_history` request fields
+
+```json
+{
+  "type": "get_command_history",
+  "sessionIdFilter": "session-123",
+  "commandId": "cmd-42",
+  "fromTimestamp": 1772412000000,
+  "toTimestamp": 1772415600000,
+  "limit": 100
+}
+```
+
+- `sessionIdFilter` (optional): exact match on journal entry `sessionId`
+- `commandId` (optional): exact match on journal entry command ID
+- `fromTimestamp` / `toTimestamp` (optional): inclusive time bounds on `recordedAt`
+- `limit` (optional): max entries returned (default `100`, hard max `500`)
+
+Entries are returned in append order and may be truncated when `limit` is reached.
+Servers MAY also apply internal scan guardrails (line/time budget) and set `truncated: true`
+when the query exceeds those bounds.
+
 ### 17.2 Session commands (require `sessionId`)
 
 **Discovery:**

README.md

@@ -142,11 +142,11 @@ npm install
 npm run build
 
 # Run tests
-npm test                    # Unit tests (83)
-npm run test:integration    # Integration tests (26)
-npm run test:fuzz           # Fuzz tests (17)
+npm test                    # Main test suite
+npm run test:integration    # Integration tests
+npm run test:fuzz           # Fuzz tests
 
-# Module tests (141)
+# Module tests
 node --experimental-vm-modules dist/test-command-classification.js
 node --experimental-vm-modules dist/test-session-version-store.js
 node --experimental-vm-modules dist/test-command-replay-store.js

ROADMAP.md

@@ -100,7 +100,7 @@ Each unchecked item requires an **owner**, an **acceptance test**, and a **decis
 ### L4.2 Crash recovery model
 - [ ] Rehydrate journal on startup
 - [ ] Classify pre-crash in-flight commands (`recoverable` / `failed`) with explicit reason
-- [ ] Expose recovery summary event/endpoint
+- [x] Expose recovery summary event/endpoint
 
 **Owner:** TBD
 
@@ -113,7 +113,7 @@ Each unchecked item requires an **owner**, an **acceptance test**, and a **decis
 
 ### L4.3 Replay and trace extraction
 - [ ] Deterministic replay mode for audit/debug
-- [ ] `get_command_history` API (session, commandId, time-window filters)
+- [x] `get_command_history` API (session, commandId, time-window filters; bounded response)
 - [ ] Redaction-aware export path for incident reports
 
 **Owner:** TBD
@@ -126,9 +126,9 @@ Each unchecked item requires an **owner**, an **acceptance test**, and a **decis
 - Replay placement: in-process feature vs offline tool
 
 ### L4.4 Retention, compaction, privacy controls
-- [ ] Retention policy (time + size)
-- [ ] Compaction that preserves replay correctness
-- [ ] PII redaction hooks before persistence/export
+- [x] Retention policy (time + size)
+- [x] Compaction that preserves replay correctness for retained outcomes + in-flight recovery
+- [x] PII redaction hooks before persistence/export
 
 **Owner:** TBD
 

docs/adr/0019-durable-command-journal-foundation.md

@@ -89,10 +89,18 @@ This preserves rollback safety while validating operational behavior.
 
 ## Follow-up work
 
-- retention + compaction with replay-equivalence guarantees
+- ✅ recovery summary endpoint (`get_startup_recovery`) in protocol surface
+- ✅ recovery summary startup event (`startup_recovery_summary`) in protocol surface (convenience; endpoint remains canonical)
+- ✅ bounded history query endpoint (`get_command_history`) with session/command/time filters
+- ✅ retention + compaction foundation (`durableJournal.retention` with maxEntries/maxAgeMs/maxBytes), preserving retained replay + in-flight recovery semantics
+- ✅ single-writer lock file enforcement to prevent multi-process compaction/append races on one journal path
+- ✅ bounded history-query scan guardrails (line/time budget) to avoid unbounded server-lane scans
+- ✅ append write-failure strictness policy (`durableJournal.appendFailurePolicy`: `best_effort` / `fail_closed`)
+- ✅ redaction hooks for persistence/export surfaces (`durableJournal.redaction.beforePersist` / `beforeExport`)
+- ✅ chaos coverage for malformed/partial journal lines around recovery + compaction
 - optional SQLite backend evaluation (decision gate revisit)
-- recovery summary endpoint/event in protocol surface
 - schema migration tooling and fixtures
+- deterministic replay/export tooling for incident workflows
 
 ## References