Skip to content

feat(worktrees): migrate Worktrunk workflows to native Stax - #1163

Open
scottames wants to merge 2 commits into
mainfrom
codex/stax-native-worktrees
Open

scottames wants to merge 2 commits into
mainfrom
codex/stax-native-worktrees

Conversation

@scottames

@scottames scottames commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

What changed

Replace Worktrunk with native Stax worktree creation, selection and removal. hwtc branch now explicitly starts independent agent work from trunk, even when invoked inside a tracked feature branch; --base branch and --base @ select an explicit parent.

  • Preserve hw / hwt / hwtc, desktop space reuse, primary-space creation, project labels and the caller's directory. Retain legacy Herdr and Zellij workflows and the Graphite-only bridge without migrating unrelated Graphite functionality.
  • Keep sibling paths and existing checkouts/branch metadata. Work around Stax's ambiguous main selector and broken rich/JSON inventory in legacy .bare layouts using read-only Git discovery.
  • Use blocking Stax post_create setup: copy ignored regular files without overwriting destinations, optional thts init --no-agents --force, then conditional trunk check. Failures stop launch and leave the checkout available for repair.
  • Preserve git_status stack/path output and replace the worktree status pane. Fix stale response parsing in the already-disabled legacy Herdr split layout.

Removed

Worktrunk package/lock entry, Fish shell integration/completions, global config, Task/Agent columns, pane aliases, package/agent-skill references and custom Stax tracking/untracking hooks (including stax-post-remove.py). Chezmoi removal entries retire the deployed files. Historical changelog and release-note fixtures remain.

Safety tradeoffs / changed behavior

git_prune --apply now prunes stale bookkeeping only; it retains every live worktree and branch. Native Stax cleanup lacks age/activity guards, and stax wt rm --delete-branch does not reparent surviving children in the tested releases. Rather than reproduce another lifecycle manager or weaken safety, live removals are explicit through Stax and branches remain tracked.

Dry-run remains the default. Apply still requires a clean primary checkout on trunk, validates metadata, and pulls --ff-only. Stale entries have a fixed two-day floor; since native prune has no expiry argument, one young/unknown missing entry retains all stale entries. Staged or interrupted state blocks pruning. --min-age is removed.

Other changes:

  • Warm-slot recycling disabled to preserve stable branch/path identities.
  • Native picker selects existing worktrees; use hwtc instead of Worktrunk's Alt-c creation. Worktrunk-specific selectors such as pr:123 are not emulated.
  • Ignored-file seeding is a plain cold copy, skips symlinks, and does not implement .worktreeinclude. Project hooks can use targeted copies/dependency installers.
  • Hook failures leave the branch/worktree behind; re-entry does not retry post_create. Repair setup before opening the agent.
  • Native wtsc intentionally retains Stax's current-branch parenting semantics; use hwtc for independent agents.

Validation

  • 40 Python tests passed with actual Git, Fish 4.9.3 and the repository's pinned Stax 0.118.2.
  • 19 real-CLI worktree/cleanup tests passed on current Stax 0.120.0.
  • Four Fish suites passed: git status, Zellij worktrees, project labels and legacy Herdr workspace workflow.
  • Includes a real interactive Stax picker in a PTY; explicit/default parent selection; ordinary/bare layouts; existing checkout metadata preservation; hook/copy/setup failures; Graphite isolation; clean/default-branch/ff-only guards; dirty/locked/active retention; stale-entry age and staged-state protection; completions/abbreviations.
  • Changed Fish syntax, TOML parsing and git diff --check passed.
  • Trunk lint could not run: both normal and CI-mode attempts failed starting its local daemon (socket: Operation not permitted). No lint pass is claimed. Herdr/Zellij transports are mocked; live user sessions and macOS were not exercised.

Manual migration

See docs/worktrees.md for full behavior, upstream findings and migration steps. Review/deploy with chezmoi, restart Fish, and uninstall the now-unrequested Worktrunk package when satisfied. Keep existing checkouts and metadata; translate project-local Worktrunk hooks to stax.toml, export any Task/Agent values needed, and review any old warm slots. Repository-local Worktrunk state is not deleted automatically.

No chezmoi apply was run. Leave unmerged for review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant