release: v0.6.31 comprehensive review remediation

.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
   },
   "metadata": {
     "description": "Polycli host adapters for Claude Code and related agent CLIs",
-    "version": "0.6.30"
+    "version": "0.6.31"
   },
   "plugins": [
     {
       "name": "polycli",
       "description": "Claude Code adapter for the shared polycli companion",
-      "version": "0.6.30",
+      "version": "0.6.31",
       "source": "./plugins/polycli"
     }
   ]

.github/plugin/marketplace.json

@@ -5,13 +5,13 @@
   },
   "metadata": {
     "description": "Polycli marketplace for GitHub Copilot CLI",
-    "version": "0.6.30"
+    "version": "0.6.31"
   },
   "plugins": [
     {
       "name": "polycli-copilot",
       "description": "Run the shared polycli companion from GitHub Copilot CLI",
-      "version": "0.6.30",
+      "version": "0.6.31",
       "source": "./plugins/polycli-copilot"
     }
   ]

.github/workflows/ci.yml

@@ -32,12 +32,12 @@ jobs:
       - name: Audit dependencies
         run: npm audit --audit-level=moderate
 
-      - name: Run tests
-        run: npm test
-
       - name: Validate generated bundles
         run: npm run validate:bundles
 
+      - name: Run tests
+        run: npm test
+
       - name: Validate fixture metadata
         run: npm run validate:fixtures
 

CHANGELOG.md

@@ -6,6 +6,14 @@ Separate from `docs/release.md` (release-focused) and `docs/archive/session-memo
 
 ---
 
+## 2026-07-15 — Codex — release: v0.6.31 candidate (review remediation)
+
+- Closed all 14 confirmed findings from the v0.6.30 comprehensive review: truthful no-diff/background JSON v2 results, strict provider target disambiguation, accurate TUI effects, active-job visibility, ledger preview redaction, safe prompt transport, structured session identity, and canonical typed failures.
+- Hardened provider process lifecycle with bounded stdout/stderr capture, POSIX process-group termination and escalation, simulated deadline-aware Windows `taskkill` coverage, and exactly-once settlement even when `close` is missing or termination fails. Native Windows execution was not available; streaming paths retain a direct-child fallback there.
+- Made background cancellation and SessionEnd recoverable: cancellation intent remains active until a verified stop, start failures use a private recovery sidecar, terminal ledger/state publication is ordered, and worker/cancel races cannot publish late provider material.
+- Added a source-derived, read-only generated-artifact freshness gate that runs before any in-place bundle rebuild in CI and `release:check`; rebuilt all five companion bundles from current source.
+- Prepared host/OpenCode/terminal `0.6.31` and `@bbingz/polycli-utils` `1.0.5`; `@bbingz/polycli-timing` remains `1.0.2` and `@bbingz/polycli-runtime` remains private.
+
 ## 2026-07-15 — Codex — release: v0.6.30 published
 
 - Published and registry-verified `@bbingz/polycli@0.6.30` (`latest`, registry time `2026-07-15T08:55:13.583Z`, shasum `882e134363d70545c15e060a8da6c1274a2aa1e7`), `@bbingz/polycli-utils@1.0.4` (`2026-07-15T08:51:16.560Z`, `f89c94947199f4d9d61ec6eddca889bb83a95ec4`), and `@bbingz/polycli-opencode@0.6.30` (`2026-07-15T08:55:44.359Z`, `9f71767156d2278f3f9bbe0cadc3fd1c90ae289f`). `@bbingz/polycli-timing@1.0.2` was unchanged and not republished.

docs/release-notes-v0.6.31.md

@@ -0,0 +1,55 @@
+# polycli v0.6.31
+
+Review-remediation patch on top of `v0.6.30`. This release closes every confirmed issue from the post-release comprehensive review while preserving the Path B boundary: provider adapters remain flat and explicit, the runtime package remains private, and no provider protocol framework is introduced.
+
+## What changed
+
+### Truthful CLI and observation contracts
+
+- A no-change background review now returns the real skipped result instead of a synthetic `job.started` record with no job.
+- `setup` and `health` reject ambiguous positional-plus-flag provider targets before provider, auth, or state access.
+- TUI agent-context effects now disclose local recovery-state writes; default status keeps all active jobs visible while bounding terminal history.
+- Every persisted ledger preview is sanitized at the storage boundary.
+
+### Bounded provider execution and safe prompt transport
+
+- On POSIX, timeout, abort, decoder overflow, termination failure, and missing-close paths now terminate or escalate the provider process group and settle exactly once with a canonical typed error. Windows streaming paths retain a direct-child termination fallback.
+- Aggregate stdout and stderr capture are independently bounded while total byte counts remain available for diagnostics.
+- Claude and Gemini move oversized prompts to verified stdin transport. Argv-only providers reject unsafe command lines before spawn with typed `argument_list_too_long` guidance; review input is still unlimited unless the caller explicitly chooses `--max-diff-bytes`.
+- Claude, Copilot, OpenCode, and Qwen no longer promote arbitrary UUIDs from answer prose into provider session identity.
+
+### Recoverable background lifecycle
+
+- Cancellation persists a non-terminal intent and publishes `cancelled` only after worker identity is verified and the worker is stopped.
+- SessionEnd delegates to the authoritative cancel path under one deadline that also bounds state/ledger locks, process identity probes, and Windows `taskkill` calls.
+- Config, log, open, and spawn failures use a private recovery sidecar so a transient pre-envelope failure cannot leave a permanent pidless queued job.
+- Worker, cancellation, and terminal-ledger races preserve one complete terminal pair and clean owned runtime/config/recovery artifacts before terminal state becomes observable.
+
+### Reproducible generated artifacts
+
+- `validate:bundles` now renders expected bundles and terminal metadata from source with esbuild `write:false`, then compares every tracked artifact byte-for-byte without overwriting it.
+- GitHub CI and `release:check` run that freshness gate before `npm test`, which performs the in-place build.
+- A regression test changes source while all five tracked bundles remain mutually identical and proves the pre-build validator rejects them.
+
+## Compatibility
+
+- Existing public `--json` payloads remain compatible; JSON v2 stays opt-in.
+- Default review collection remains unbounded; only explicit `--max-diff-bytes` truncates input.
+- `@bbingz/polycli-runtime` remains private and provider modules remain flat.
+- Host plugins, OpenCode, and terminal CLI move to `0.6.31`; `@bbingz/polycli-utils` moves to `1.0.5`; `@bbingz/polycli-timing` remains `1.0.2`.
+
+## Verification
+
+- Five scoped implementation groups each passed independent spec-compliance and code-quality review.
+- The local full suite passed: 906 tests, 906 passed, 0 failed.
+- `npm run release:check` passed source-derived bundle freshness, strict fixture freshness, manifests, host maps, Codex guidance, installed-CLI review flag drift, both Claude plugin validations, and all npm package dry-runs.
+- Native Windows execution was not available. Windows argv budgeting and `taskkill`/deadline branches were covered by deterministic simulation; only POSIX process-group and live process-tree behavior received native execution coverage.
+- PR CI and publication evidence are recorded before the GitHub release is created.
+
+## Release artifacts
+
+- GitHub release: `v0.6.31`
+- npm: `@bbingz/polycli@0.6.31`
+- npm: `@bbingz/polycli-opencode@0.6.31`
+- npm: `@bbingz/polycli-utils@1.0.5`
+- unchanged npm package: `@bbingz/polycli-timing@1.0.2`

docs/release.md

@@ -82,8 +82,8 @@ npm run release:check
 
 `release:check` includes:
 
-- `npm test`, which rebuilds plugin bundles before running package, runtime, plugin, and release-script tests
-- `npm run validate:bundles`
+- `npm run validate:bundles`, a read-only source-derived freshness gate that runs before any in-place build
+- `npm test`, which then rebuilds plugin bundles before running package, runtime, plugin, and release-script tests
 - `npm run validate:fixtures`
 - `npm run check:fixture-freshness -- --strict`
 - `npm run validate:manifests`
@@ -175,4 +175,4 @@ npm install -g @bbingz/polycli
 polycli health --json
 ```
 
-The terminal package re-uses the same `polycli-companion.bundle.mjs` that every host adapter ships, so `npm run build:plugins` must succeed before publishing — `validate:bundles` confirms the five companion bundle copies are byte-identical.
+The terminal package re-uses the same `polycli-companion.bundle.mjs` that every host adapter ships. Before publishing, `validate:bundles` independently renders the expected outputs from source without writing them and compares all five bundle copies plus generated terminal metadata byte-for-byte; `npm run build:plugins` is the only in-place writer.

docs/roadmap.md

@@ -42,7 +42,7 @@ Status: closed as an active guardrail. CI, release publication, npm registry sta
 
 Current guardrails:
 
-- `npm run validate:bundles` checks that all five generated companion bundles are byte-identical after `npm test` rebuilds them.
+- `npm run validate:bundles` independently renders source-derived expected bytes and checks all five companion bundles plus generated terminal metadata before `npm test` can rebuild them in place.
 - `npm run validate:fixtures` checks real runtime fixture metadata has provider/name/capturedAt/version/argv/expected response fields, matching stream captures, and required success fixtures for every parser-backed provider.
 - `npm run validate:manifests` keeps host plugin versions and marketplace entries aligned.
 - `npm run validate:host-map` keeps host command docs and registered command surfaces aligned.

packages/polycli-runtime/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "dependencies": {
     "@bbingz/polycli-timing": "1.0.2",
-    "@bbingz/polycli-utils": "1.0.4"
+    "@bbingz/polycli-utils": "1.0.5"
   },
   "exports": {
     ".": "./src/index.js"

packages/polycli-runtime/src/agy.js

@@ -219,9 +219,11 @@ export function runAgyPromptStreaming({
     const parsed = parseAgyTextResult(result.stdout);
     const filteredStderr = stripAgyBenignStderr(result.stderr);
     const hasVisibleText = Boolean(parsed.response.trim());
-    const error = result.ok
-      ? (hasVisibleText ? null : "agy produced no visible text")
-      : (filteredStderr.trim() || result.error);
+    const error = !result.ok && result.errorCode
+      ? result.error
+      : (result.ok
+          ? (hasVisibleText ? null : "agy produced no visible text")
+          : (filteredStderr.trim() || result.error));
     return {
       ...result,
       ...parsed,
@@ -230,7 +232,7 @@ export function runAgyPromptStreaming({
       model: model ?? defaultModel ?? DEFAULT_AGY_MODEL,
       ok: result.ok && hasVisibleText,
       error,
-      errorCode: classifyProviderFailure(error, { provider: "agy" }),
+      errorCode: result.errorCode ?? classifyProviderFailure(error, { provider: "agy" }),
     };
   });
 }