Merge pull request #36 from vitry/fix/zcode-conversation-progress-0163

fix: support ZCode 0.16.3 conversation progress

Author: vitry

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+- Fixed ZCode CLI 0.16.3 conversation progress compatibility: bounded initial, online-overflow, and recovery snapshots now establish silent sequence baselines; all five production delta operations are structurally accepted; and only validated tool/turn rows can emit bounded public progress. Online deltas require the exact exclusive baseline, and any overlap or ordinal/sequence gap fences further online progress until an authoritative snapshot or a recovery delta covering the trusted sequence resets it. Online frame state and watermarks now commit transactionally after asynchronous descriptions settle, so ignored frames cannot leak later tool summaries. Structurally accepted zero-event frames remain diagnostic-only and no longer suppress or stop snapshot fallback; only a frame with bounded public semantic progress establishes online health. Snapshot history, state patches, row text deltas, and removed-row content are never rendered, while fragments remain unsupported and fall back through the existing observational progress path.
 - Fixed terminal ZCode failure handling so failures are no longer replaced by `ZCODE_RESULT_MISSING`: failed and cancelled jobs remain queryable through `$zcode:result`, stored errors appear in result and status output, and natural-language result references without an ID select the latest finished owned job. This does not repair upstream provider SSE or network failures.
 - Added an instance-bound Rescue launcher rendered by the owned parent hook, so Root and child reuse one exact plugin-instance command instead of constructing companion paths. Installed and source-development namespaces remain intentionally isolated; `source-session-unproven` and unsafe-launcher failures are terminal with no setup retry or cross-instance redirect. Existing data locations remain unchanged, while the managed Role digest requires the normal owned upgrade through `$zcode:setup`.
 - Added exact stopped-child Rescue continuation: Root privately prepares the next bound turn and follows up the same stopped child, which reuses `invoke-prepared rescue` with no second `SubagentStart`; fresh work still creates a new child.

docs/superpowers/plans/2026-08-20-conversation-progress-incident-completion.md

@@ -0,0 +1,50 @@
+# Conversation Progress Incident Completion Plan
+
+**Goal:** Complete PR #36 so it fixes both the ZCode 0.16.3 conversation-frame incompatibility and the incident-specific fallback/state-integrity failures.
+
+**Constraints:** Preserve bounded parsing, sequence/recovery fencing, source/marketplace byte identity, and existing lifecycle behavior. A structurally accepted online frame is not semantically healthy until it emits at least one public progress event.
+
+## Task 1: Make online frame application transactional
+
+**Files:**
+- Modify: `scripts/lib/conversation-progress.mjs`
+- Modify: `marketplace/plugins/zcode/scripts/lib/conversation-progress.mjs`
+- Modify: `tests/conversation-progress.test.mjs`
+
+1. Add a regression test where an online frame mutates a tool state, then waits on an async path description while a gap/overflow is marked. Recover and complete the same tool; assert data from the ignored frame is never emitted and its watermark was not committed.
+2. Run the focused test and confirm it fails for the state leak.
+3. Stage online-frame row/tool state, public events, terminal state, and watermarks locally. Commit them only after all async descriptions finish and the frame is still admissible.
+4. Copy the implementation to the marketplace mirror and verify byte identity.
+5. Run `node --test tests/conversation-progress.test.mjs`.
+
+## Task 2: Keep fallback active until semantic online progress exists
+
+**Files:**
+- Modify: `scripts/lib/progress.mjs`
+- Modify: `marketplace/plugins/zcode/scripts/lib/progress.mjs`
+- Modify: `tests/progress.test.mjs`
+- Modify: `tests/integration/companion.test.mjs`
+
+1. Reverse the zero-event expectations: structurally accepted empty online frames still increment diagnostics but neither clean up an active snapshot fallback nor block compatibility-boundary activation.
+2. Add an incident-shaped regression: repeated sequence/row-shape rejects activate fallback; interleaved accepted empty online frames preserve heartbeat snapshot reads; the first nonempty online event exits fallback exactly once; later empty frames do not regress state.
+3. Run focused tests and confirm they fail before implementation.
+4. Track semantic online health separately from structural acceptance and use it for fallback activation/cleanup.
+5. Copy the implementation to the marketplace mirror and verify byte identity.
+6. Run `node --test tests/progress.test.mjs tests/integration/companion.test.mjs`.
+
+## Task 3: Align the design contract and changelog
+
+**Files:**
+- Modify: `docs/superpowers/specs/2026-08-15-rescue-forwarder-progress-compatibility-design.md`
+- Modify: `CHANGELOG.md`
+- Modify marketplace copies only where plugin contract tests require them.
+
+1. State that ignored online frames commit neither state nor watermarks.
+2. Distinguish structural acceptance from semantic health: only a nonempty bounded public event exits or permanently suppresses fallback.
+3. Document the incident regression and user-visible consequence.
+
+## Task 4: Independent review and verification
+
+1. Run independent spec and standards reviews against `origin/main...HEAD`; fix all blockers and repeat reviews.
+2. Run focused progress suites, `npm run check`, and `git diff --check origin/main...HEAD`.
+3. Push the existing PR branch, then watch all six GitHub Actions matrix checks to success. Diagnose, fix, and rerun if any check fails.

docs/superpowers/specs/2026-08-09-rescue-native-subagent-progress-design.md

@@ -505,11 +505,13 @@ a fixed follow-up. Wait timeout/interruption tests prove no duplicate spawn.
 
 ### Progress
 
-Fixture tests feed initial and online conversation frames for Bash, Edit, Write,
-Read, Grep, Glob, WebSearch, unknown tools, success, failure, and terminal turn
-states. They cover 96-character shortening, multibyte bounds, controls, huge
-strings, duplicates, reordering, cross-session frames, path traversal, post-
-terminal events, and subscription fallback.
+Fixture tests feed initial, online-overflow, and recovery snapshots plus all five
+ZCode 0.16.3 delta operations for Bash, Edit, Write, Read, Grep, Glob, WebSearch,
+unknown tools, success, failure, and terminal turn states. They cover exclusive
+sequence baselines, 500-operation and one-MiB bounds, 64-event fanout,
+96-character shortening, multibyte bounds, controls, huge strings, duplicates,
+reordering, cross-session frames, path traversal, post-terminal events, and
+subscription fallback.
 
 Adversarial tests prove that reasoning, assistant drafts, tool output, file
 contents, environment data, capability-like strings outside approved command or

docs/superpowers/specs/2026-08-15-rescue-forwarder-progress-compatibility-design.md

@@ -141,27 +141,77 @@ The conversation describer changes from silent `null` rejection to an internal
 fixed rejection result. Valid-frame behavior and all existing public bounds stay
 unchanged.
 
+### ZCode 0.16.3 complete-frame compatibility
+
+The structural boundary accepts wire-version-3 complete frames with the exact
+outer topic and subscription binding. A bounded protocol-version-1 snapshot may
+arrive as an initial frame, an online overflow reset, or a recovery frame. Its
+session identity, log epoch, sequence, revision, and bounded 60-row window are
+validated, but its historical rows are never replayed or interpreted. The
+snapshot silently replaces the observational sequence and lifecycle baseline.
+
+Delta payloads follow ZCode 0.16.3's exclusive sequence baseline and accept at
+most 500 operations within the one-MiB complete-frame bound. The supported
+operations are `row.appended`, `row.upserted`, `row.removed`, `row.delta`, and
+`state.updated`. Only exact, allowlisted `toolCall` and `turnHeader` rows from
+append/upsert operations may produce public events. Removal updates local
+deduplication state silently; row text appends and state patches are bounded,
+validated, and ignored. No snapshot, patch, text append, unknown row, assistant
+draft, tool output, or historical terminal row is rendered. Public event fanout
+remains capped at 64 per frame and tracked lifecycle state at 256 rows.
+
+After any accepted baseline, a normal online delta must have the next logical
+ordinal and `fromSeq` exactly equal to the last accepted `toSeq`. Overlapping
+replays and ordinal or sequence gaps are rejected before applying operations;
+the rejected frame does not advance either trusted watermark. Further online
+deltas remain fenced until a valid recovery delivery or a bounded authoritative
+snapshot establishes a new baseline. An online overflow snapshot may reset from
+sequence zero while fenced.
+
+Online delta application is transactional across asynchronous path
+normalization. Tool and row lifecycle state, public events, terminal intent,
+and both trusted watermarks remain staged until every description has settled
+and the frame is still admissible. A gap, overflow, or terminal latch observed
+while a description is pending discards the entire staged frame, so a later
+recovery or terminal update cannot expose content from an ignored frame.
+
+A delta recovery is valid only when its range covers the last trusted sequence:
+`fromSeq` is no greater than the trusted `toSeq`, and its new `toSeq` does not
+move backward. A recovery range that begins after the trusted sequence leaves a
+hole, is rejected without advancing either watermark, and keeps recovery
+fencing active. An equal-sequence empty recovery remains a valid no-op baseline.
+
+Fragment frames remain unsupported. Their rejection is observational and uses
+the existing bounded session-snapshot fallback; it cannot affect authoritative
+completion, cancellation, or result handling.
+
 ### Compatibility state
 
 Each foreground Rescue progress reporter has one of four observational states:
 
 - `probing`: subscription may still produce a usable online frame;
-- `online`: at least one usable online frame has been accepted;
+- `online`: at least one accepted online frame emitted a bounded public semantic
+  event;
 - `snapshot-fallback`: no usable semantic frame was available by the first
   heartbeat boundary, or a bounded rejected-frame threshold was reached; or
 - `lifecycle-only`: both semantic frames and snapshot fallback are unavailable.
 
 Initial snapshots do not switch the reporter to `online` because historical
-activity must not suppress fallback for the current turn. Once an online frame
-is accepted, snapshot polling stops. State changes do not affect the
-authoritative completion wait.
+activity must not suppress fallback for the current turn. Structural acceptance
+still increments `acceptedOnline` for diagnostics, but an accepted frame with no
+public events is not evidence of usable progress: it neither exits nor blocks
+snapshot fallback, and it leaves `probing`, `snapshot-fallback`, or
+`lifecycle-only` unchanged. The first accepted online frame with at least one
+bounded public event switches the reporter to `online` and stops snapshot
+polling exactly once; later empty frames do not regress that state. State changes
+do not affect the authoritative completion wait.
 
 ### Bounded session snapshot fallback
 
-At the first heartbeat boundary with no accepted online frame, the reporter
-reads the same session through the existing authenticated client. While fallback
-is active, it repeats at most once per heartbeat interval. Only one read may be
-in flight, and a read that has not settled is not duplicated.
+At the first heartbeat boundary with no semantically usable online frame, the
+reporter reads the same session through the existing authenticated client.
+While fallback is active, it repeats at most once per heartbeat interval. Only
+one read may be in flight, and a read that has not settled is not duplicated.
 
 Snapshot processing uses the existing schema-validated session response and the
 accepted current-turn boundary. It ignores messages that existed before send

marketplace/plugins/zcode/CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+- Fixed ZCode CLI 0.16.3 conversation progress compatibility: bounded initial, online-overflow, and recovery snapshots now establish silent sequence baselines; all five production delta operations are structurally accepted; and only validated tool/turn rows can emit bounded public progress. Online deltas require the exact exclusive baseline, and any overlap or ordinal/sequence gap fences further online progress until an authoritative snapshot or a recovery delta covering the trusted sequence resets it. Online frame state and watermarks now commit transactionally after asynchronous descriptions settle, so ignored frames cannot leak later tool summaries. Structurally accepted zero-event frames remain diagnostic-only and no longer suppress or stop snapshot fallback; only a frame with bounded public semantic progress establishes online health. Snapshot history, state patches, row text deltas, and removed-row content are never rendered, while fragments remain unsupported and fall back through the existing observational progress path.
 - Fixed terminal ZCode failure handling so failures are no longer replaced by `ZCODE_RESULT_MISSING`: failed and cancelled jobs remain queryable through `$zcode:result`, stored errors appear in result and status output, and natural-language result references without an ID select the latest finished owned job. This does not repair upstream provider SSE or network failures.
 - Added an instance-bound Rescue launcher rendered by the owned parent hook, so Root and child reuse one exact plugin-instance command instead of constructing companion paths. Installed and source-development namespaces remain intentionally isolated; `source-session-unproven` and unsafe-launcher failures are terminal with no setup retry or cross-instance redirect. Existing data locations remain unchanged, while the managed Role digest requires the normal owned upgrade through `$zcode:setup`.
 - Added exact stopped-child Rescue continuation: Root privately prepares the next bound turn and follows up the same stopped child, which reuses `invoke-prepared rescue` with no second `SubagentStart`; fresh work still creates a new child.