CHANGELOG.md

Changelog

• Fixed Rescue routing so persisted children continue only through one exact binding and fresh work always gets a new child.

All notable changes follow Semantic Versioning.

Unreleased

• Fixed pre-running Rescue continuation failures so a locked compare-and-swap restores the exact prior binding while retaining the failed attempt. Claimed leases remain fenced, crash retries converge across binding-first publication, legacy migration semantics stay unchanged, and the strict historical repair CLI remains operator-only and outside package and marketplace artifacts.
• Fixed a cold resumed ZCode session by lazily reading the bounded effective CLI provider configuration only after the exact warning, applying one ephemeral session/updateRuntimeModelConfig, and proving recovery with one session/read before effort and one send. Warm resumes do not read config; credentials are neither cached nor persisted; invalid config remains bounded while genuine AppServer rejection stays authoritative; and recovery never retries resume, falls back, resends, or replaces the session.
• Fixed direct status/result/cancel and job creators to use one lifecycle-authoritative job partition across origin, exact target, and later turns, without scanning, merging, or expanding explicit-ID ownership.
• Added compact SessionStart rehydration of the same instance-bound Rescue launcher within the existing context limit, without minting authority; ordinary sources remain generic and unsafe provenance remains a fixed error.
• Fixed the ambiguity between multiple usable Rescue bindings by letting Root retain the canonical task_name path returned by spawn_agent and prepare it privately. The version-3 {agentPath} selector narrows exact-parent discovery while the host child ID stays internal to the plugin and must still match the durable child-ID/path binding. Public --resume stays argument-free, and all original session, permission, workspace, operation, generation, and job checks still apply. Version 2's pair remains read compatibility only and is never emitted by new flows. A targetless request with multiple usable bindings remains ambiguous and must fail closed. The conservative limit of one active writable Rescue per canonical workspace is unchanged; this does not add same-workspace writable concurrency.
• Fixed exact Rescue binding migration: only one complete v1/v2 closed/session-ended binding may migrate, independent app-server notLoaded is accepted only with the complete exact join, and /root/zcode_rescue_task_2 resumes its original non-empty zcodeSessionId without base/latest fallback. Jobs-only and host-only adoption are rejected; ambiguity and contradictory evidence fail closed before mutation or RPC.
• Changed fresh Rescue so it always parent-replans and collision-free spawns a new child, which creates one new ZCode session. It never reactivates, follows, or replaces an old child; existing sibling bindings remain unchanged.
• Narrowed SessionEnd preservation to exact completed/no-active-attempt bindings and exact v1/v2 session-ended candidates. Confirmed exact active cancellation may close only that operation; unacknowledged stop retains the guard. Foreground/background response loss recovers through status/result and durable artifacts with one accepted send and no resend, while the stale-stop final guard prevents a losing cancellation from stopping or closing a newer operation.
• Fixed ordinary default or explorer subagents aborting an otherwise valid Rescue continuation with EXECUTOR_ROLE_UNAPPROVED: ordinary rows are now occupancy-only, while an exact bound ordinal Rescue child remains eligible for resume. Generic default Rescue compatibility still requires its exact real executor provenance.
• Fixed restored empty-preview Codex children disappearing from Rescue collision planning: preparation now uses the exact parent relationship query, treats host-only rows as occupancy without granting follow-up authority, and fails closed when that API is unsupported instead of retrying or guessing a colliding spawn.
• Added persisted stopped Rescue child recovery before replacement spawn: the plugin restores the original Codex thread and history by joining sanitized app-server identity with private executor provenance, rejoins already active children, and never treats age or a name/path collision as authority.
• Restored compatibility with the legacy PR #39 Rescue route: after origin-to-worktree binding, a child launched or resumed from the conversation root can resolve the immutable execution target. This qualification does not broaden authority beyond that bound target.
• Added compatible Rescue worktree late binding: lifecycle proof retains the origin workspace while the first trusted prepare automatically and immutably binds one execution workspace from the same canonical Git common-dir, without manual handoff. Role preview and children cannot claim; unrelated repositories fail closed; Root Stop, a new prompt, and SessionEnd revoke or replace authority before target cleanup.
• Accepted ZCode CLI 0.16.3's captured initial empty-session revision and pre-turn settings snapshots while retaining exact empty-state, event-sequence, identity, workspace, and activity checks. Real qualification now proves two visible responses through each turn's exact persisted user-root parent chain when the CLI remaps request input IDs.
• Removed the plugin-defined ordinary Rescue completion deadline while retaining finite request, review-gate, qualification, caller credential, and one-shot preparation budgets. Active parent authority is now hook-lifecycle-bound; same-parent-turn continuation replaces consumed preparation generation 1 with an executor-bound generation 2, follows up the exact stopped child, and reuses the exact binding and ZCode session. Root Stop, replacement prompts, SessionEnd, explicit cancellation, SIGINT, and SIGTERM remain authoritative boundaries. Role readiness now distinguishes caller-unavailable and inspection-unavailable from managed setup states; existing owned Roles require the normal one-time setup upgrade.
• Added private durable per-job human-readable logs that retain the complete accepted safe semantic-progress history while job previews remain bounded to four entries. Exact-owner detailed status displays the private absolute path; compact, foreign, sibling-session, sidecar, relay, and terminal surfaces remain path-free, with no new log command or retention lifecycle.
• 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.
• Added automatic proactive Rescue routing alongside explicit $zcode:rescue, with authoritative explicit choices, semantic objective normalization, active-child rejoin, and no --auto flag. Root now performs a raw TTY readiness handshake and sends one LF-terminated frame over private stdin without EOF into exact-bound, expiring, single-consume prepared state; task-blind named and generic children run only invoke-prepared rescue.
• Added cc-style semantic progress in the selected Rescue child and fixed coarse root liveness relays without exposing raw PTY data, child stderr, tool output, file contents, reasoning, credentials, or capabilities. Progress remains observational: only the original foreground terminal exit and final stdout prove completion. The child also supports an exact bound no-argument status sidecar through zcode status, $zcode:status, or /zcode:status without selecting or replacing the foreground job.
• Added deterministic installed Codex 0.147 captured-rollout qualification for both the named Role and generic fallback, independently covering yielded foreground and same-child choice continuations; authenticated live qualification still reports only the route Codex actually selected.
• Added task-independent Rescue child display names with bounded sibling-collision ordinals. Display identity contains no business objective or task text and remains a navigation-only invariant that does not grant, prove, or remove Rescue authorization.
• Added #24 neutral forwarding hooks, #25 attached-yield continuation on the same running handle, and #26 fixed-shape structural progress probes with detailed status limited to the exact owner.
• Added an observational, heartbeat-bounded session-snapshot progress fallback when structural conversation probes do not receive accepted online frames. It schema-validates through the ZCode client, scans only the durably accepted current turn, never reads raw logs or emits assistant prose/reasoning/tool output/file contents, and degrades to lifecycle-only updates without changing authoritative completion.
• Stopped writing the Codex host's hide_spawn_agent_metadata flag; one setup now reconciles the managed Role and safely removes only a legacy false proved by complete numeric-v1 ownership evidence.
• Added a packaged bilingual manual-uninstall guide for receipt-gated Role/config cleanup while retaining durable jobs, results, progress, logs, and history by default.
• Fixed $zcode:setup managed Role reconciliation with Codex 0.147 effective configuration, which normalizes an otherwise exact Role registration with nickname_candidates = null.
• Fixed local cachebuster reinstallations so SemVer build metadata keeps the installed plugin's marketplace-qualified data root valid.
• Fixed installed $zcode:* skills failing with DATA_ROOT_REQUIRED when Codex does not inject PLUGIN_DATA into ordinary skill commands.
• Added marketplace-qualified plugin-data discovery and a restart-safe $zcode:setup bootstrap that configures the data directory as a writable root before persisting state.
• Added ZCode CLI 0.16.1 compatibility for runtime-preference server requests with string IDs.
• Improved $zcode:setup guidance when the ZCode CLI has no model provider configured, including the distinction between Desktop and CLI settings and API-key providers that do not require OAuth.
• Added foreground activity output, a 20-second heartbeat, and durable status previews for long-running ZCode work.
• Added bounded foreground SIGINT and SIGTERM handling: the plugin cancels before session creation or sends session/stop only to the exact persisted ZCode session, while background jobs continue until completion or explicit cancellation with $zcode:cancel.
• Added safe orphan settlement through best-effort SessionEnd handling and a reservation-time crash fallback while preserving owner-only access. A broker-unavailable orphan with a free worker lease is archived as failed and releases the writable guard; an unacknowledged stop on a reachable control channel still retains the guard.
• Added a digest-backed managed zcode-rescue Role, one isolated native child for foreground Rescue and same-child choices, bounded semantic progress, parent-output isolation, unchanged production-owned background authorization, and opt-in installed Codex 0.147 qualification coverage for steering, acknowledged cancellation, and durable loss recovery.
• Hardened marketplace publication to require an exact clean source commit, build from an isolated detached worktree after its own lockfile-driven npm ci --ignore-scripts, record the dependency-lock hash, verify the complete bundled runtime, reject canonical or symlink output overlap, and atomically publish only a complete staged snapshot.
• Strengthened installed Codex 0.147 qualification with fail-closed runtime identity negatives, exact child semantic-progress evidence, private production capability verification, and an explicit scoped observation when the noninteractive harness cannot expose TUI events.
• Restored ZCODE_REAL_E2E_MODEL as the canonical real qualification model variable; the deprecated ZCODE_REAL_MODEL alias is accepted only when it does not conflict.
• Kept the package version at 0.1.0 for these Unreleased behavior changes.

0.1.0 - 2026-08-06

• Added eight native $zcode:* skills for review, adversarial review, Rescue, Transfer, job inspection, cancellation, and setup.
• Added direct ZCode Protocol sessions, model and effort selection, imported Codex history, durable owner-scoped jobs, single-use background execution, and strict permission routing.
• Added Codex lifecycle hooks, optional Stop review gate, a publishable vitry marketplace snapshot, marketplace hook trust setup, cross-platform fake peers, packed production installation checks, and opt-in macOS real-ZCode qualification.