envctl 1.6.4

envctl 1.6.4

envctl 1.6.4 is a patch release on top of 1.6.3. It hardens repository test reruns, keeps dashboard failure summaries useful again, refreshes runtime inventory contracts, and smooths a few planning and terminal edge cases that were still surfacing in the Python engine.

Why This Release Matters

1.6.3 improved the tmux-backed planning workflow, but a few operator-facing sharp edges still remained:

• failed-only repository test reruns could still pick the wrong repo root or reintroduce wrapper-only launcher variables into nested subprocesses
• dashboard test rows could lose the saved failure excerpt even though the summary artifact still existed
• the checked-in runtime inventory and gap-report contracts could drift behind the live command surface
• some planning and terminal flows still needed better defaults or more robust output handling

This patch release focuses on those correctness issues so the Python runtime stays aligned with the actual launcher, dashboard, and contract behavior users see.

Highlights

Failed-only repository reruns now stay on the live checkout path

• failed-only reruns now prefer the active RUN_REPO_ROOT when reconstructing repository test contexts
• action subprocesses no longer inherit wrapper-only launcher overrides that can interfere with nested bare envctl calls
• helper test subprocesses now preserve the supplied action environment instead of silently rebuilding from ambient shell state

Dashboard test summaries are informative again

• dashboard test rows continue to show the short summary artifact path
• failed test rows now render the saved failure excerpt consistently, including the failed test id and the key assertion detail

Runtime contracts match the live Python command surface again

• the runtime feature matrix and gap report were regenerated from the current Python inventory
• command inventory coverage now includes the expanded Python-owned inspection and worktree helpers reflected by the router and parity tests

Planning and terminal edge cases are steadier

• Codex tmux launches now use the intended default launch command path in planning flows
• process runner streaming tolerates malformed UTF-8 output without dropping progress or summary parsing
• interactive command recovery is more tolerant of escape-fragment noise in terminal input

Included Changes

• live-repo failed-only rerun targeting for repository unittest suites
• wrapper-env scrubbing for action subprocesses and helper test runners
• restored dashboard failed-summary excerpt rendering
• refreshed runtime feature matrix and gap report contracts
• Codex-first plan-agent launcher defaults and tmux launch normalization
• malformed UTF-8 tolerant process output decoding and spinner fallback hardening
• release metadata updated for 1.6.4

Operator Notes

• rerunning envctl test --failed --main now reuses the current repository checkout instead of stale copied runtime state
• dashboard tests: rows should include the short summary path plus the saved failure excerpt when a suite is failing
• release artifacts are expected under dist/ after building the package

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Summary

envctl 1.6.4 is a correctness-focused patch release. It makes repository test reruns and dashboard summaries more trustworthy, keeps runtime contracts aligned with the Python command surface, and smooths a few remaining planning and terminal edge cases.

envctl 1.6.3

envctl 1.6.3

envctl 1.6.3 is a patch release on top of 1.6.2. It tightens the tmux-backed planning workflow again: repeated plan launches can now reuse or intentionally fork worktree-scoped tmux sessions more predictably, headless guidance is clearer about when envctl reused an existing session, and the built-in /create_plan follow-up instructions now show the supported tmux launch commands instead of the older launcher env-var examples.

Why This Release Matters

1.6.2 fixed the biggest tmux planning regressions, but the operator flow still had rough edges:

• rerunning the same plan/workspace/CLI needed a clearer split between "attach to what already exists" and "create another tmux session on purpose"
• headless output showed the right commands, but it did not explicitly explain that envctl skipped creating a new session because one already existed
• /create_plan still documented stale launch examples and did not mention the supported --tmux, --opencode, or --tmux-new-session flow

This patch release keeps the worktree-scoped tmux model from 1.6.2, adds a real force-new-session path, and aligns the prompt/install guidance with the commands users can actually run.

Highlights

Existing tmux sessions can now be reused or intentionally forked

• tmux plan-agent sessions are scoped by worktree path and CLI, so Codex and OpenCode for the same worktree no longer collide
• rerunning the same plan/workspace/CLI in interactive mode prompts the operator to attach to the existing session or create a new suffixed session
• answering Enter, y, or yes now reliably attaches to the existing tmux session instead of accidentally launching another one
• --tmux-new-session forces creation of a new suffixed tmux session even in interactive mode and skips the attach prompt entirely

Headless mode gives clearer reuse instructions

• when a matching tmux session already exists, headless output now states that envctl reused the existing plan/workspace/CLI session instead of silently implying a fresh launch
• the printed new session: command now includes --tmux-new-session --headless, so copying that command really creates another tmux session instead of redisplaying the existing attach guidance

/create_plan follow-up commands now match the supported launcher surface

• the built-in create_plan template now shows repo-scoped tmux launch commands such as envctl --plan <selector> --tmux and envctl --plan <selector> --tmux --opencode
• the template now documents --tmux-new-session for users who want another tmux session without being prompted
• the both option is still supported, but it is now documented as two separate envctl invocations run one after the other rather than one imaginary combined CLI mode

Included Changes

• parser support for --tmux-new-session
• worktree-and-CLI-scoped tmux session naming plus suffixed -2, -3, ... creation for explicit new-session launches
• interactive attach/create prompting that defaults to attach and honors y/yes/Enter
• clearer headless reuse output with real force-new follow-up commands
• updated create_plan prompt-install template coverage for the supported tmux launcher commands
• release metadata updated for 1.6.3

Operator Notes

• use envctl --plan <selector> --tmux for Codex-backed tmux launches
• use envctl --plan <selector> --tmux --opencode for OpenCode-backed tmux launches
• use --tmux-new-session when you explicitly want another tmux session for the same plan/workspace/CLI without being prompted
• when selecting both from a prompt-driven follow-up, envctl should be run twice behind the scenes: once for Codex and once for OpenCode

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Summary

envctl 1.6.3 is a focused tmux planning polish release. It makes repeated plan launches more predictable, makes headless reuse messaging more explicit, and keeps the built-in planning prompt guidance aligned with the commands envctl actually supports.

1.6.2

Release 1.6.2

1.6.1

Release 1.6.1

1.6.0

envctl 1.6.0

envctl 1.6.0 is a minor release on top of 1.5.0. It ships the workflow and safety improvements that landed after the 1.5.0 tag: stronger tmux/OpenCode planning defaults, clearer headless-vs-interactive plan follow-up behavior, inline dashboard AI session and run guidance, prompt-contract upgrades for implementation and plan flows, and a commit-safety fallback that keeps envctl-local artifacts out of user commits even when Git excludes are missing.

This release stays at a minor bump because the post-1.5.0 range adds new user-facing planning, dashboard, and prompt workflow surface rather than only patching previously shipped internals.

Why This Release Matters

The 1.5.0 line expanded envctl's workflow surface. 1.6.0 makes that workflow more complete and more trustworthy:

• tmux-backed AI planning and review flows now behave more like the product presents them, especially for OpenCode direct prompting and session handling
• dashboard AI affordances are clearer: users can see the live tmux attach surface for a running AI session or the exact command needed to launch one, but never both at the same time
• plan follow-up messaging now separates headless auto-run from interactive/manual execution and keeps attach instructions explicit when envctl launches the tmux session for the user
• shipped prompt templates now carry stronger execution contracts around end-of-task PR creation, CLI choice, cycle selection, and attach guidance
• envctl-managed local artifacts are safer because the commit path itself now refuses to stage them, even if the user’s Git excludes are incomplete

Highlights

Tmux/OpenCode planning and session workflow improvements

Planning flows now align better with the live tmux/OpenCode runtime model.

• tmux is the default plan-agent transport
• Opencode is the default AI CLI for plan-agent launch flows
• OpenCode direct prompting is now the default for tmux-backed plan-agent launches
• tmux plan runs no longer auto-attach by default, while attach instructions remain available when relevant
• session management and persistence now support richer dashboard/session workflows and explicit attach/kill handling

Dashboard AI visibility and launch guidance

The interactive dashboard now presents AI session state and launch guidance more cleanly.

• per-project AI session rows use worktree-aware tmux matching instead of loose name heuristics
• attached state is determined from the active tmux session and pane path rather than only by session name
• the dashboard shows either:
  • a live AI session attach row, or
  • a Run AI launch command row
    but not both at the same time
• Run AI commands now match the supported interactive launch contract: envctl --plan <selector> --tmux

Headless plan clarity and follow-up contract

Headless plan mode now behaves more truthfully and with less noise.

• headless plan follow-up output now centers on session_id, attach, and kill information rather than dropping into the interactive dashboard path in the changed startup flows
• generated follow-up guidance no longer misuses --headless for user-facing interactive/tmux launch commands
• startup follow-up text now distinguishes interactive/manual execution explicitly instead of implying the same command shape for every mode

Prompt-contract upgrades for implementation and planning

The shipped prompts now better encode the intended workflow.

• implement_task now requires PR creation/update only at the very end of the implementation task, after implementation, tests, and commit are complete
• implement_task also explicitly includes PR status in the final response contract
• create_plan now offers AI CLI choice across:
  • codex
  • opencode
  • both
• when Codex is involved, create_plan now asks for Codex cycle count
• when the user chooses headless auto-run, create_plan now says envctl will print the attach command after launch so the user can attach to the tmux session

Commit safety for envctl-local artifacts

envctl now has a stronger safety fallback for local-only files.

• envctl still maintains the existing global Git-excludes strategy for envctl-managed local artifacts
• in addition, envctl commit / envctl pr no longer rely on that alone
• commit flow now inspects git status --porcelain --untracked-files=all, skips protected envctl-local artifacts from staging, and fails fast if those files are already staged
• protected files include:
  • .envctl*
  • MAIN_TASK.md
  • OLD_TASK_*.md
  • trees/
  • trees-*

Included Changes

Major areas covered in this release:

• tmux/OpenCode planning defaults and direct-prompt behavior improvements
• session history, attach/kill UX, and dashboard session visibility refinements
• per-project dashboard AI attach/run guidance with mutually exclusive row behavior
• headless plan output and follow-up command-contract cleanup
• prompt-template upgrades for implement_task and create_plan
• stronger commit-time protection for envctl-managed local artifacts
• focused docs/tests/runtime alignment for release and packaging metadata

Operator Notes

• No data migration or manual config migration is required for this release.
• Teams using tmux-backed planning flows should see clearer session behavior and less ambiguity about how to attach or rerun manually.
• Users who rely on envctl-generated local task/state files should be better protected from accidentally committing those artifacts through envctl-managed commit/PR flows.
• Prompt-driven planning and implementation loops now carry stronger workflow guardrails, especially around CLI choice, PR ordering, and attach guidance.

Artifacts

This release publishes:

• source-tagged GitHub release metadata
• envctl-1.6.0.tar.gz
• envctl-1.6.0-py3-none-any.whl

Upgrade Note

If you are already using envctl, the most visible changes in 1.6.0 are:

• clearer tmux/OpenCode session and attach behavior during planning and dashboard flows
• a cleaner dashboard AI presentation that separates live session attach from launch commands
• more truthful headless-vs-interactive follow-up guidance after plan creation
• stronger built-in prompt instructions for end-of-task PR creation and CLI/cycle selection
• safer envctl-managed commit/PR flows around .envctl*, task files, and worktree-local artifacts

Summary

envctl 1.6.0 turns the planning, dashboard, prompt, and release-adjacent workflows into a tighter, more truthful system. The release makes tmux/OpenCode behavior easier to reason about, keeps AI/session affordances clearer, hardens the prompt contracts that drive implementation and planning, and adds a meaningful safety net so envctl-local artifacts stay out of user commits.

envctl 1.5.0

envctl 1.5.0

envctl 1.5.0 is a minor release on top of 1.4.1. It ships the user-facing workflow additions and runtime hardening that landed after the 1.4.1 tag: clickable local path links across the terminal UI, a dedicated finalize_task prompt flow, optional origin-side review launch after dashboard review, stronger target-scoped backend env isolation, and more resilient source-checkout/runtime bootstrap behavior.

This release is a minor instead of a patch because the post-1.4.1 range adds new operator-facing and prompt-driven workflow surface rather than only correcting previously shipped behavior.

Why This Release Matters

The 1.4.1 line focused on hotfixes. 1.5.0 turns the work that followed into a broader workflow upgrade:

• AI-assisted implementation loops now have an explicit completion preset and a smoother path into origin-side review
• terminal output can expose clickable local file paths across the main interactive surfaces without changing machine-readable output
• backend env resolution is more trustworthy for both startup and native migrate flows in multi-worktree repos
• source-checkout execution is more robust when runtime dependencies or import-path precedence would previously cause confusing failures
• the active runtime/docs/release contract is now fully aligned around the Python engine rather than legacy shell-era behavior

Highlights

Workflow completion and origin-side review

Planning and review loops gained new user-facing workflow support.

• install-prompts now ships a dedicated finalize_task prompt preset for slash-command driven completion flows
• queued plan-agent cycles now reserve /prompts:finalize_task for the final queued handoff instead of using the same follow-up prompt throughout
• interactive dashboard review can optionally open one origin-side AI review tab after a successful single-worktree review
• origin-side review launches now carry the original plan/provenance context through the shared launcher path so the follow-up review starts from the right scope
• continue_task guidance was clarified for the truly complete case so the prompt does not imply more implementation work remains when the prior iteration is already done

Clickable local path links across terminal output

Human-facing CLI output can now emit clickable local file links across the main runtime surfaces.

• dashboard, action, runtime, config, doctor, startup-warning, prompt-install, planning/worktree, command-loop, and test-summary output paths now share one hyperlink policy
• trailing punctuation is excluded from link targets and remote URLs such as https://... are not misidentified as local paths
• ENVCTL_UI_HYPERLINK_MODE=auto|on|off controls hyperlink behavior explicitly
• JSON output and persisted artifacts remain raw text rather than OSC-8 encoded output

Target-scoped backend env isolation

Backend env selection is now more reliable across startup and native action flows.

• startup bootstrap and native envctl migrate now share one backend env-resolution contract
• inherited backend-sensitive shell variables are scrubbed before target-scoped env merge so one worktree does not accidentally pick up another target's database settings
• relative backend and frontend override paths follow the documented target-root / repo-root resolution contract, including ambiguity detection and service-local fallback behavior
• startup migration warnings and migrate failures keep env-source diagnostics so operators can see which env-file path won

Runtime bootstrap and Python-only contract hardening

Source-checkout execution and contributor validation are more deterministic.

• commands now bootstrap required runtime dependencies before deeper runtime use, improving failure behavior when optional UI/runtime packages are missing
• raw repo-root unittest discovery works without PYTHONPATH=python
• repo-local test/bootstrap and ./bin/envctl source-wrapper execution now prefer this checkout even if a foreign envctl_engine package appears earlier on PYTHONPATH
• release/readiness ownership, docs, and active plan references now align to the Python runtime contract rather than the retired shell domain
• legacy harness-only TTY env guards were removed in favor of real terminal-state detection

Included Changes

Major areas covered in this release:

• new finalize_task prompt preset and updated queued plan-agent follow-up semantics
• optional post-review origin tab launch for interactive dashboard review
• origin-review provenance/original-plan handling improvements
• clickable local path rendering across human-facing terminal output with ENVCTL_UI_HYPERLINK_MODE
• startup and native migrate backend env isolation plus frontend override-path contract documentation
• dependency bootstrap-before-use hardening for source-checkout/runtime entrypoints
• repo-root bootstrap precedence fixes for raw unittest discovery and ./bin/envctl
• Python-only runtime/release-governance cleanup and validation-contract alignment
• prompt and docs refinements around completion-state and contributor runtime guidance

Operator Notes

• No data migration or manual config migration is required for this release.
• ENVCTL_UI_HYPERLINK_MODE is optional; the default auto mode remains conservative and terminal-dependent.
• Teams using worktree-specific backend env files should see migrate and startup behave more consistently under conflicting parent-shell env settings.
• Contributors running source-checkout commands should see fewer import-path and bootstrap failures when local or foreign PYTHONPATH entries are present.

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Upgrade Note

If you are already using envctl, the most visible changes in 1.5.0 are:

• a built-in finalize_task prompt flow for the last step of queued implementation cycles
• an optional origin-side review tab after successful single-worktree dashboard review
• clickable local file-path links across the main human-facing CLI and dashboard surfaces
• stronger worktree-scoped backend env selection for startup and native migrate
• more reliable source-checkout behavior for repo-root unittest discovery and ./bin/envctl

Summary

envctl 1.5.0 expands the workflow surface while tightening the runtime edges underneath it. The release adds new prompt/review/UI capabilities, makes environment selection and bootstrap behavior more trustworthy, and keeps the contributor/release contract aligned with the Python runtime that the product now ships.

envctl 1.4.1

envctl 1.4.1

envctl 1.4.1 is a cumulative patch release on top of 1.4.0. It ships the set of runtime and workflow fixes that landed after the 1.4.0 tag: safer prompt guidance for continuing work, startup-parity fixes for native migrate actions, stronger interrupt cleanup for envctl-managed test runs, and more reliable Codex plan-agent/cmux behavior.

This release stays at a patch bump because the work since 1.4.0 is corrective and hardening-oriented. The changes tighten already-shipped workflows instead of introducing a new advertised feature line.

Why This Hotfix Matters

The post-1.4.0 fixes all close gaps between the workflows envctl presents and the workflows it actually executes under stress.

• continue-task prompts now make users audit committed divergence from the originating branch, not only local dirty state
• native migrate actions inherit the same backend env and dependency projection assumptions as startup paths
• interrupted envctl-managed test runs clean up detached child suites instead of leaving stray processes behind
• Codex plan-agent cycles and starter-surface reuse now behave deterministically in real cmux-backed launches
• canonical release validation now ignores historical managed worktree copies and keeps the runtime feature inventory aligned with the shipped codex-tmux command

Highlights

Prompt provenance and divergence audit

The shipped continue_task prompt now tells users to inspect committed divergence from the originating branch or ref in addition to staged, unstaged, and untracked worktree changes.

• prompt guidance now calls out provenance and merge-base review explicitly
• prompt-install regression coverage locks the contract so installed templates stay aligned

Native migrate actions now match startup env behavior

envctl migrate now reuses the same backend env-file resolution and dependency URL projection that startup paths already use.

• migrate actions can populate DATABASE_URL and REDIS_URL from saved run state when available
• explicit override database settings still keep precedence
• missing-env failures now explain the contract more clearly
• docs were updated across commands, configuration, and troubleshooting guidance

Safer interrupt handling for envctl-managed tests

Interrupted test runs now terminate envctl-started suite process groups and cancel queued work before surfacing the controlled interrupt exit path.

• sequential and parallel suite interrupts both clean up child process groups
• failed-only manifests and summaries avoid partial interrupt-corrupted output
• dashboard and CLI flows share the same stricter interrupt semantics

Plan-agent and cmux reliability fixes

The Codex plan-agent path now handles cycle aliases and starter-surface reuse more consistently.

• the CYCLES alias is carried through config, inspection, and queued follow-up launch paths
• headless bootstrap keeps late runtime events long enough to preserve queued plan-agent behavior
• starter-surface parsing now accepts only unique numeric surface:<n> handles, preventing false ambiguity when cmux repeats tokens
• planning and AI playbook docs were updated to reflect the live behavior

Release-validation contract fixes

The repo’s canonical validation lane is now less sensitive to local workspace history and command-inventory drift.

• pytest -q is scoped to the repository’s authoritative tests/ tree instead of recursing into managed historical worktrees under trees/
• the runtime feature inventory now includes the shipped codex-tmux command, keeping generated contract artifacts aligned with the actual router surface

Included Changes

Major areas covered in this release:

• continue-task prompt provenance audit for committed divergence
• migrate action env parity with startup and saved dependency projection
• interrupt-safe cleanup for envctl-managed test suites
• Codex plan-agent cycle alias and late-event persistence fixes
• stricter cmux starter-surface parsing and duplicate-handle handling
• canonical pytest collection scoped to the repo test suite instead of managed worktree copies
• runtime feature inventory alignment for the shipped codex-tmux utility command
• focused docs, changelog evidence, and regression coverage across prompt, action, planning, runtime, and dashboard paths

Operator Notes

• No data migration or manual config migration is required for this release.
• Operators using migrate through envctl should see fewer missing-env failures and behavior that matches runtime startup expectations.
• Teams relying on frequent Ctrl+C during long-running envctl test orchestration should see less leftover process cleanup work after interrupts.

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Upgrade Note

If you are already using envctl, the most visible changes in 1.4.1 are:

• continue_task now asks for branch-origin divergence review before resuming work
• migrate inherits the backend env wiring users already expect from startup
• interrupted test runs are less likely to leave child pytest or vitest processes behind
• queued Codex planning flows behave more predictably when cycle aliases or repeated cmux surface handles are involved
• repo-local release validation no longer trips over historical worktree mirrors when running the canonical pytest lane

Summary

envctl 1.4.1 makes the released workflow surface more truthful and less fragile. It focuses on prompt safety, migrate-path correctness, interrupt cleanup, and deterministic plan-agent behavior without changing the overall product model introduced in 1.4.0.

envctl 1.4.0

envctl 1.4.0

envctl 1.4.0 is a minor release focused on AI-assisted planning and review workflows. It turns the post-1.3.3 work on main into a shipped release: prompt installation is safer, worktree review has a dedicated preset, plan-agent launches are cleaner in cmux, nested tree layouts behave correctly, and Codex-backed tmux flows now have first-class runtime support.

This release is a minor instead of a hotfix because it adds new user-facing workflow surface rather than only correcting shipped behavior. The biggest changes are new prompt and runtime capabilities for planning, implementation, and review loops across local repos and generated worktrees.

Highlights

Prompt installation and origin-side review workflow

Prompt installation is now safer and more automation-friendly.

• repeat install-prompts runs overwrite in place after approval instead of creating .bak-* prompt siblings
• --yes and --force can pre-approve overwrites for non-interactive runs
• non-TTY and --json flows now fail cleanly when overwrite approval is required
• a new review_worktree_imp preset lets users review an implementation worktree while treating the current repo as the unedited baseline
• prompt installation now defaults to all available presets, including the new review path

Better cmux planning behavior

Planning flows gained a cleaner and more reliable cmux experience.

• newly created plan-agent workspaces now reuse the starter surface when that surface is unambiguous instead of leaving an extra duplicate tab behind
• launch diagnostics distinguish reused starter surfaces from newly created ones
• nested custom trees layouts such as work/trees now resolve flat feature roots correctly across discovery, setup, and runtime startup metadata

Codex tmux runtime support

envctl now ships an explicit Codex tmux workflow path for queued plan and implementation work.

• runtime command routing includes Codex tmux support for utility-command driven workflows
• PR action handling is stricter about dirty worktrees before PR creation
• planning artifacts are archived more consistently into todo/done/ while active plans are carried forward

Included Changes

Major areas covered in this release:

• prompt overwrite confirmation and clean non-interactive failure handling
• new review_worktree_imp prompt preset for origin-side worktree review
• prompt installation defaults expanded to the full preset inventory
• starter-surface reuse for newly created cmux plan-agent workspaces
• nested flat-worktree parity for custom TREES_DIR_NAME layouts
• Codex tmux workflow support in the runtime command path
• tighter PR-action handling around dirty worktrees
• docs and regression coverage updates for the new prompt, planning, and runtime paths

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Upgrade Note

If you are already using envctl, the most visible changes in 1.4.0 are:

• installed AI prompt commands no longer accumulate .bak-* duplicates on normal overwrite flows
• worktree review now has a built-in origin-side preset instead of requiring ad hoc prompt setup
• cmux-backed --plan launches are cleaner when envctl has to create the target workspace
• repositories using nested custom trees roots behave correctly during worktree discovery and startup
• Codex tmux workflows can now be launched through the supported runtime path

Summary

envctl 1.4.0 ships the next layer of AI-assisted repo workflow support. It makes prompt installation safer, review and planning flows more deliberate, and Codex/cmux runtime integration more capable without changing the core local-environment model.

envctl 1.3.3

envctl 1.3.3

envctl 1.3.3 is a cumulative patch release on top of 1.3.2. It includes the release-gate hotfix that made the branch shipable again, but it also carries the broader set of workflow, planning, startup, config, and dashboard improvements already present on current main.

This release is about making the shipped surface and the release surface line up. Since 1.3.2, main picked up substantial product work: safer startup reuse, plan-agent launch support, a repo-local commit ledger, global-ignore handling for envctl-owned artifacts, and a dashboard PR dirty-worktree preflight. The immediate release blocker was the gate’s false-positive --version parity failure plus a stale parity manifest timestamp, but the release itself is broader than those two fixes.

Why This Hotfix Matters

Release gates are only useful when they fail for real product issues.

1.3.3 closes two places where the release surface was noisier than the product:

• the shipability gate could fail because docs mentioned launcher-owned --version while the runtime parser intentionally does not own that flag
• the checked-in parity manifest had become stale enough to trip freshness enforcement during release work

It also publishes the larger body of work that already landed on main after 1.3.2.

Highlights

Release-gate flag parity fix

The release gate now treats --version the same way the parser parity tests already do: as a launcher-owned documented flag that should not be required in the runtime parser token list.

• --version remains documented and supported
• runtime command inventory still stays unchanged
• shipability no longer fails on a false parser/docs mismatch

Refreshed parity manifest collateral

The checked-in parity manifest timestamp is refreshed so freshness validation reflects the current repo state instead of stale generated metadata.

• release gate freshness checks become actionable again
• no runtime command behavior changes are introduced by the manifest refresh

Startup reuse and planning improvements

Current main includes broader workflow improvements beyond the release-gate fix.

• startup can safely reuse matching runs instead of rebuilding state unnecessarily
• plan execution gained cmux-backed plan-agent launch support
• shipped prompt templates now include an implement_plan path and updated planning guidance

Commit, config, and dashboard workflow updates

Several day-to-day operator paths also moved forward after 1.3.2.

• envctl commit now uses a repo-local .envctl-commit-message.md pointer ledger for default commit messages
• envctl-owned local artifacts moved from repo ignore mutation to Git global excludes management
• dashboard PR flow now detects dirty selected worktrees and offers an explicit commit/do-nothing preflight
• dashboard failed-test handling now writes one stable artifact path with cleaner failure output

Included Changes

Major areas covered in this release:

• release-gate documented-flag parity alignment for launcher-owned --version
• regression coverage for the release-gate --version exception
• refreshed contracts/python_engine_parity_manifest.json
• startup run-reuse safety improvements
• cmux-backed planning and plan-agent launch support
• repo-local commit ledger defaults for envctl commit
• Git global excludes handling for envctl-owned local artifacts
• dashboard dirty-worktree PR confirmation flow
• dashboard failed-test artifact cleanup and quieter failure rendering
• release metadata updates for 1.3.3

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Upgrade Note

If you are already using envctl, the most visible changes in 1.3.3 are:

• release/readiness validation stops failing on the shipped launcher-owned --version contract
• startup and resume behavior are less wasteful when a compatible run already exists
• plan workflows can launch through the newer cmux-backed agent path
• default commit-message handling now comes from the repo-local envctl ledger
• dashboard PR creation handles dirty worktrees with an explicit preflight instead of forcing manual cleanup first

Summary

envctl 1.3.3 fixes the release-engineering blocker that made the branch look less shipable than it really was, and it publishes the broader set of product changes already merged into main after 1.3.2. The result is both a truthful release gate and a materially improved day-to-day workflow surface.

envctl 1.3.2

envctl 1.3.2

envctl 1.3.2 is a hotfix release focused on command-surface correctness and release workflow polish. It adds a proper launcher-owned --version path, keeps installed and source-wrapper version reporting aligned, and fixes a PR-title regression in the dashboard commit/PR flow.

This release is about trust at the boundaries: the boundary between launcher and runtime, the boundary between installed and source-checkout invocation, and the boundary between the task you are implementing and the title envctl derives when it opens a PR.

Why This Hotfix Matters

envctl should answer basic identity and release questions immediately.

1.3.2 closes two places where that broke down:

• users could not ask envctl for its version without depending on runtime/bootstrap behavior
• dashboard PR creation could derive a bad title from a markdown subheading instead of the actual task title

Highlights

Launcher-owned version reporting

envctl --version is now a supported launcher-level flag.

• works for the installed command and for ./bin/envctl
• does not require repo detection, .envctl, or runtime startup
• prefers installed package metadata and falls back to source pyproject.toml only when needed
• keeps runtime command inventory unchanged

Installed/source parity and packaging coverage

The release surface now proves the version contract in the same places users hit it.

• editable-install smoke covers envctl --version
• regular-install smoke covers envctl --version
• explicit wrapper-path smoke covers ./bin/envctl --version
• docs now treat --version as a normal install and troubleshooting verification step

PR title derivation fix

Dashboard PR creation now derives titles from the task title instead of inheriting bad markdown headings.

• PR titles prefer the MAIN_TASK.md H1 when available
• changelog-backed commit messages skip markdown subsection headings such as ### Scope
• the dashboard commit + pr path no longer produces PR titles like ### Scope

Included Changes

Major areas covered in this hotfix:

• launcher-owned --version support
• installed/source wrapper version parity
• packaging and launcher smoke coverage for version reporting
• install/troubleshooting/reference doc updates for --version
• PR-title and changelog-subject derivation hardening
• validation/docs/inventory contract alignment for the new launcher flag

Artifacts

This release publishes:

• wheel distribution
• source distribution

After build, the artifacts are expected under dist/.

Upgrade Note

If you are already using envctl, the most visible changes in 1.3.2 are:

• envctl --version now works immediately in installed and source-wrapper contexts
• install verification docs now point at envctl --version
• dashboard-created PRs use the task title instead of markdown subsection headings

Summary

envctl 1.3.2 makes the CLI more legible and the release workflow more trustworthy. The hotfix focuses on version reporting that behaves correctly before runtime startup, and PR automation that reflects the real task title users expect.