ace-git-worktree 0.26.1 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51dd94ea8eeadcabd99be5d79ee88d9c536114637c58781d8ac8c8089243587
-  data.tar.gz: a8389cc335baa6559bf8ee4f88b167ceb90ca2c0669341f72f632f0c81968f40
+  metadata.gz: 3fbcf3673de821e4ed42fd7415a7cc0fa88fca4176d2d3cfbf7cff65e6d50332
+  data.tar.gz: ec88eedd7b9f6d3822835b70777e235a5581cacf3a413a98ee4a4bdd66eb5ae1
 SHA512:
-  metadata.gz: 8a65769172a854d95a44dd5d268ed14fd73a259b652978955139c7a5ac1f0653e7d78d47e5149dd17a90c9835f3281bf2fcf13111d67561e7458d5324b75f933
-  data.tar.gz: 7412edb73d8944f55c50b4fecb7fa8ca6e977cdcd59f2b4377fa5f823d5207bae36becfba4cc2d1a5305184d6d8acd526c530710e50fee2e507c5b114d85290c
+  metadata.gz: 8e3038cf6f5465be9074866bd6c174da7c79839fa94eb0e6abc902ea1f7300dc4fb511e6132a55841e92de594b0b9c89f9a8401de08020a37f7ae0baec512bf0
+  data.tar.gz: 73ee36beff2acc5bcda6d456db1715b95b3dc580193ce07acaab7e9ec89a591674756a456036d179b2ee30b4f054bd5a2d007e99c24b7f54e2b9f6423fac503a

data/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.1] - 2026-10-18
+
+### Changed
+
+- `list` table rows now print the full, never-truncated worktree path on its
+  own line under the row (indented to the `Commit` column) followed by a blank
+  separator line, replacing the truncated `Path` column. Every displayed path
+  is directly usable (`cd`, copy/paste); `--full` prints absolute paths.
+- `Changes` counts staged + unstaged + untracked files under `.ace-tasks/`;
+  untracked files outside the task tree are no longer scanned or counted.
+
+### Fixed
+
+- Large-repository listing performance: the deep untracked walk
+  (`--untracked-files=all`) dominated runtime and degraded further under
+  parallel probing (88 worktrees: ~18s). Probes now read tracked-only status
+  and run the deep `.ace-tasks/` untracked scan as a selective second round
+  for worktrees the cheap association tiers cannot resolve (~7s).
+- Task index lookups no longer re-`realpath` every task directory on every
+  lookup; canonical paths are resolved once per index.
+
+## [0.27.0] - 2026-10-17
+
+### Added
+
+- `ace-git-worktree list` now defaults to a compact active-worktree table: one
+  enriched row per worktree whose last commit or uncommitted changes fall inside
+  the activity window (`--active-within`, default `18h`), plus a two-line count
+  footer. Columns: Task, Branch, Age, Commit, Changes, PR, Path.
+- `--full` lists every worktree in the same columns with absolute, untruncated
+  paths; `--compact` is the explicit default and is mutually exclusive with
+  `--full`.
+- Name-independent task association with provenance: recorded task metadata,
+  the `_current` symlink, validated path/branch names, then task files modified
+  in the worktree (uncommitted first, then commits vs the primary branch
+  merge-base). Ambiguous inference renders `<id>+N` and exposes all candidates.
+- PR resolution through one bounded forge query per run: branch match, then HEAD
+  commit sha, then a unique task reference in the PR title/body.
+- Per-worktree probing in isolated forked children: at most 16 live children,
+  5 second per-probe budget, process-group kill on timeout, deterministic
+  `git worktree list` order, and a sequential fallback where `fork` is
+  unavailable. Probe failures render `?` without failing the command.
+- Width-aware table layout driven by `COLUMNS`/the terminal size: columns shrink
+  in priority order (Path, Commit, Branch) and Path/Commit drop on narrow
+  terminals; compact output never exceeds the detected width.
+- `--format json` additions per selected worktree: `task_id_source`, `task_ids`,
+  `active_within_window`, `last_commit`, `uncommitted`, and `pr` with `state`,
+  `draft`, and `matched_by`. Existing keys are unchanged.
+
+### Changed
+
+- `ace-git-worktree list` output is now the active-worktree table; the legacy
+  plain Task/Branch/Path/Status table and the `Summary:` block are gone.
+- Invalid `--active-within` values, mutually exclusive detail flags, and removed
+  flags fail with actionable one-line errors and a non-zero exit.
+
+### Removed
+
+- `--show-tasks`: the Task column is always present and association is always
+  inferred. Passing `--show-tasks` now fails as an unknown option (ADR-024, no
+  compatibility layer).
+
 ## [0.26.1] - 2026-10-10
 
 ### Fixed

data/docs/getting-started.md

@@ -53,10 +53,13 @@ This keeps your shell history simple while avoiding hard-coded worktree paths.
 List worktrees with task context when you want a quick overview:
 
 ```bash
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 ```
 
-Use `--search auth` or `--format json` later when you want filtering or machine-readable output.
+The default view shows only worktrees active in the last 18 hours, with task,
+age, last commit, uncommitted changes, and PR context. Use `--full` for an
+exhaustive listing, `--active-within 3d` for a wider window, `--search auth` to
+filter, or `--format json` for machine-readable output.
 
 ## 4. Create a PR Worktree
 
@@ -102,7 +105,7 @@ Add hooks, auto-push, terminal launch, or PR automation only after the basic cre
 | Create a task worktree | `ace-git-worktree create --task 081` |
 | Create a PR worktree | `ace-git-worktree create --pr 26` |
 | Switch into a worktree | `cd "$(ace-git-worktree switch 081)"` |
-| List worktrees with task info | `ace-git-worktree list --show-tasks` |
+| List active worktrees with task info | `ace-git-worktree list` |
 | Remove a task worktree | `ace-git-worktree remove --task 081` |
 | Preview stale cleanup | `ace-git-worktree prune --dry-run` |
 
@@ -128,7 +131,7 @@ ace-git-worktree list
 ### Task filtering behavior
 
 ```bash
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 ace-git-worktree list --task-associated
 ace-git-worktree list --no-task-associated
 ```

data/docs/usage.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-git-worktree CLI Usage Reference
 purpose: Command reference for ace-git-worktree
 ace-docs:
-  last-updated: 2026-04-14
-  last-checked: 2026-03-22
+  last-updated: 2026-10-17
+  last-checked: 2026-10-17
 ---
 
 # ace-git-worktree CLI Usage Reference
@@ -38,7 +38,7 @@ Create a task worktree, list active worktrees, and resolve the path for shell na
 
 ```bash
 ace-git-worktree create --task 081
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 ace-git-worktree switch 081
 ```
 
@@ -62,14 +62,14 @@ Success looks like a new worktree directory exists and `switch` returns a path y
 
 ```bash
 ace-git-worktree create --task 081
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 ```
 
 **Expected output:**
 
 ```text
 Created task worktree and branch for 081
-... task.081 appears in the worktree list ...
+... task 081 appears in the active worktree table ...
 ```
 
 **Next steps:** Run `cd "$(ace-git-worktree switch 081)"` to move into the new worktree.
@@ -143,7 +143,7 @@ ace-git-worktree cleanup --target main --apply --approved-digest <sha256-digest>
 **Commands:**
 
 ```bash
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 ace-git-worktree list --task-associated
 ace-git-worktree list --no-task-associated
 ```
@@ -151,9 +151,50 @@ ace-git-worktree list --no-task-associated
 **Expected output:**
 
 ```text
-... --show-tasks includes task metadata ...
-... --task-associated excludes the main worktree ...
-... --no-task-associated shows main/non-task entries only ...
+... the default view lists only worktrees active in the last 18h ...
+... --task-associated keeps only worktrees with a resolved task id ...
+... --no-task-associated shows only worktrees without a task id ...
+```
+
+### Scenario 4: Find Work Without Meaningful Worktree Names
+
+**Goal:** A worktree created by another tool has a path/branch that names no
+task. Still identify its task and PR.
+
+**Commands:**
+
+```bash
+ace-git-worktree list
+ace-git-worktree list --format json
+```
+
+**Expected output:**
+
+```text
+... the Task cell shows the task whose .ace-tasks files were modified there ...
+... `ace-git-worktree list --format json` reports task_id_source=task_files ...
+```
+
+The PR cell resolves by branch name, then by HEAD commit, then by a unique task
+reference in the PR title/body; `null`/`-` means no match. The JSON entry exposes
+`pr.matched_by` (`branch`, `head_sha`, or `task_reference`).
+
+### Scenario 5: Exhaustive Listing and Custom Window
+
+**Goal:** Inspect every worktree, or widen the activity window after a weekend.
+
+**Commands:**
+
+```bash
+ace-git-worktree list --full
+ace-git-worktree list --active-within 3d
+```
+
+**Expected output:**
+
+```text
+... --full lists every worktree with absolute paths ...
+... --active-within 3d reads "Active worktrees (last 3d) -- N of M:" ...
 ```
 
 ### Scenario 5: Remove by Task and Delete Branch
@@ -216,33 +257,121 @@ ace-git-worktree create --task 081 --dry-run
 
 ### `ace-git-worktree list`
 
-List active worktrees with optional task metadata and filters.
+List worktrees as an active-worktree table with task, activity, dirty-state, and
+PR context. By default only worktrees active inside the activity window are
+rows; everything else is collapsed into counts.
 
 ```bash
 ace-git-worktree list
-ace-git-worktree list --show-tasks
+ace-git-worktree list --full
+ace-git-worktree list --active-within 3d
 ace-git-worktree list --format json
+ace-git-worktree list --task-associated
 ace-git-worktree list --search auth
 ```
 
 **Options:**
 
-* `--format` - Output format: `table`, `json`, or `simple`
-* `--show-tasks` - Include task associations
-* `--task-associated` - Show only task-associated worktrees
-* `--no-task-associated` - Show only non-task worktrees
-* `--usable` - Show only usable worktrees
-* `--search` - Filter by branch-name pattern
-* `-q`, `--quiet` - Suppress non-essential output
+* `--compact` - Active worktrees only (the default; mutually exclusive with `--full`)
+* `--full` - List every worktree in the same columns with absolute paths
+* `--active-within <duration>` - Activity window: `30m`, `18h`, `2d`, or a bare
+  integer (hours). Default `18h`. Invalid, empty, zero, or negative values fail
+  with a non-zero exit.
+* `--format` - Output format: `table` (default), `json`, or `simple`
+* `--task-associated` / `--no-task-associated` - Filter by resolved task id
+* `--usable` / `--no-usable` - Filter by usable (not bare/detached) state
+* `--search <pattern>` - Filter by branch-name pattern
+* `-q`, `--quiet` - Suppress the count footer
 * `-v`, `--verbose` - Show verbose output
 * `-d`, `--debug` - Show debug output
 
-**Minimal JSON contract (`--format json`):**
+There is no `--show-tasks` flag: the Task column is always present and task
+association is always inferred.
+
+**Default output shape:**
+
+```text
+Active worktrees (last 18h) -- 3 of 88:
+Task   Branch                       Age  Commit                    Changes  PR
+---------------------------------------------------------------------------------------
+k9y    codex/r3-bounded-convergence  17h  feat(review): define bo…        2  #142 draft
+                                         ~/Ps/ace/.ace-wt/codex-r3-bounded-convergence
+
+-      codex/ei9-campaign-join        8m  feat(ace-assign): compl…        -  -
+                                         ~/Ps/ace/.ace-wt/ei9-campaign-composition-join
+
+Inactive: 85  (use --full to list all)
+Task-associated: 14    Usable: 71    Recent branches without worktrees: 4
+```
 
-- Output is valid JSON (`array` or object containing worktree entries).
-- Each entry includes a stable path/identity surface usable by scripts (`path` and `branch` fields).
-- Task-associated entries expose `task_id`.
-- Non-task entries either omit `task_id` or set it to `null`.
+Each worktree renders as three lines: the aligned columns, the
+never-truncated path (indented to the `Commit` column, `$HOME` shortened to
+`~` in compact mode, absolute with `--full`), and a blank separator line, so
+every displayed path is directly usable (`cd`, copy/paste).
+
+**Activity:** a worktree is active when the last commit reachable from its
+checked-out HEAD is inside the window **or** it has uncommitted changes
+(staged, unstaged, or untracked under `.ace-tasks/`). Bare worktrees are never
+active. Filters apply before the active/inactive split, so the header and
+footer counts always describe the filtered set. `Recent branches without
+worktrees` is branch-based and is not affected by worktree filters.
+
+**Columns:**
+
+* `Task` - resolved short task id; `<id>+N` when N additional candidate tasks
+  were inferred from modified task files; `-` when unresolved.
+* `Branch` - checked-out branch (middle-elided when truncated); `detached`.
+* `Age` - last commit age in one unit (`8m`, `3h`, `9d`, `3w`, `2mo`, `1y`);
+  `never` when the branch has no commits; future timestamps render `0m`.
+* `Commit` - last commit subject, right-truncated with `…`.
+* `Changes` - uncommitted file count (staged + unstaged + untracked files
+  under `.ace-tasks/`); `-` when clean. Untracked files outside the task tree
+  are not scanned: the deep untracked walk dominates listing time on large
+  repositories, and stray artifacts are not an activity signal.
+* `PR` - `#N` (open), `#N draft`, `#N merged`, `#N closed`, or `-`.
+
+**Task association (name-independent), in precedence order:**
+
+1. recorded task metadata (`worktree.path` / `worktree.branch`);
+2. the `_current` symlink resolving under `.ace-tasks/`;
+3. a validated path/branch name extraction (rejected when it names no task);
+4. task files modified in the worktree (uncommitted first, then commits relative
+   to the merge-base with the primary worktree's branch). The dominant task wins
+   (most changed task files; lexicographic tie-break), rendered `<id>+N`.
+
+**PR resolution:** one bounded forge query per run. A PR is matched by branch
+name, then by HEAD commit sha, then by a unique task reference in the PR
+title/body. Unconfigured/offline forges render `-` and never fail the command.
+
+**Width behavior:** the table targets `120` columns, shrinks `Commit`, then
+`Branch` down to their minimums, and drops `Commit` on very narrow terminals.
+Width comes from `COLUMNS`, else the terminal size, else `120`. Path lines are
+never truncated; `--full` is exempt from truncation entirely.
+
+**Probe isolation and performance:** each worktree is probed in its own forked
+child process (one child per worktree, at most 16 alive, hard 5 second budget
+per probe). The probe reads only cheap signals: HEAD metadata, tracked changes
+(`git status --untracked-files=no`), committed task-file diffs, and the
+`_current` symlink. The expensive deep untracked scan of `.ace-tasks/` runs as
+a selective second round, only for worktrees the cheap association tiers could
+not resolve. Probe results are ordered by `git worktree list` order, so output
+is deterministic; a failed or timed-out probe renders `?` in `Age`/`Commit`/
+`Changes` while the rest of the table renders and the command exits 0. Where
+`fork` is unavailable, probes run sequentially with the same timeouts.
+
+**JSON contract (`--format json`):**
+
+- Output is a top-level array of every selected (post-filter) worktree.
+- Existing keys stay unchanged (`path`, `branch`, `commit`, `task_id`, `bare`,
+  `detached`, `created_at`, `usable`, `task_associated`, `exists`, `empty`).
+- Added keys: `task_id_source` (`metadata|symlink|path|branch|task_files|null`),
+  `task_ids` (all candidates), `active_within_window` (boolean),
+  `last_commit` (`sha`, `age_hours`, `committed_at`, `subject`), `uncommitted`
+  (`staged`, `unstaged`, `untracked`, `total`), and `pr` (`number`, `state` in
+  `open|merged|closed`, `draft`, `matched_by` in
+  `branch|head_sha|task_reference`).
+- Absent sub-objects are `null` rather than omitted. Detail flags do not change
+  JSON output.
 
 ### `ace-git-worktree switch [IDENTIFIER]`
 
@@ -477,7 +606,7 @@ fall back to another provider.
 **Solution:**
 
 ```bash
-ace-git-worktree list --show-tasks
+ace-git-worktree list --full
 ```
 
 Confirm the identifier matches a task ID, branch name, directory name, or path shown in the current worktree list.

data/handbook/agents/worktree.ag.md

@@ -50,8 +50,8 @@ A specialized agent for managing git worktrees with task-aware automation. Handl
 # Create worktree for feature branch
 @worktree create feature-branch
 
-# List all worktrees
-@worktree list --show-tasks
+# List active worktrees (last 18h) with task context
+@worktree list
 
 # Switch to worktree
 @worktree switch feature-branch
@@ -106,10 +106,14 @@ The worktree agent accepts standard CLI parameters:
 - `--no-commit`: Skip committing task changes
 
 ### list
+- `--compact`: Active worktrees only (default)
+- `--full`: List every worktree (including inactive) with absolute paths
+- `--active-within <duration>`: Activity window (`30m`, `18h`, `2d`, or bare hours; default 18h)
 - `--format <format>`: Output format (table, json, simple)
-- `--show-tasks`: Include task associations
-- `--task-associated`: Filter by task association
-- `--search <pattern>`: Filter by search pattern
+- `--task-associated` / `--no-task-associated`: Filter by resolved task id
+- `--usable` / `--no-usable`: Filter by usability
+- `--search <pattern>`: Filter by branch-name pattern
+- `-q`, `--quiet`: Suppress the count footer
 
 ### switch
 - `identifier`: Worktree identifier (task ID, branch name, directory, path)
@@ -179,7 +183,7 @@ The worktree agent provides deterministic output suitable for AI automation:
 WORKTREE_PATH=$(ace-git-worktree switch 081)
 
 # Get worktree status as JSON
-STATUS=$(ace-git-worktree list --format json --show-tasks)
+STATUS=$(ace-git-worktree list --format json)
 
 # Create worktree and verify creation
 RESULT=$(ace-git-worktree create --task 081 --dry-run --format json)

data/handbook/workflow-instructions/git/worktree-create.wf.md

@@ -86,7 +86,7 @@ ace-git-worktree create feature-branch --path ~/dev-work
 
 ```bash
 # List all worktrees
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 
 # Switch to the worktree
 cd $(ace-git-worktree switch 081)
@@ -218,7 +218,7 @@ ace-git-worktree list --task-associated
 ace-git-worktree prune --cleanup-directories
 
 # Get status in JSON for scripts
-ace-git-worktree list --format json --show-tasks
+ace-git-worktree list --format json
 ```
 
 ## Error Handling
@@ -244,7 +244,7 @@ RESULT=$(ace-git-worktree create --task 081 --dry-run --format json)
 echo "$RESULT" | jq '.worktree_path'
 
 # List worktrees with task associations
-STATUS=$(ace-git-worktree list --format json --show-tasks)
+STATUS=$(ace-git-worktree list --format json)
 echo "$STATUS" | jq '.worktrees[] | select(.task_associated == true)'
 ```
 

data/handbook/workflow-instructions/git/worktree-manage.wf.md

@@ -35,7 +35,7 @@ $action: Management action (list, switch, remove, prune)
 ace-git-worktree list
 
 # List with task associations
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 
 # List in different formats
 ace-git-worktree list --format json
@@ -158,10 +158,10 @@ ace-git-worktree config --show
 
 ```bash
 # Get worktree status for all tasks
-ace-git-worktree list --format json --show-tasks | jq '.worktrees'
+ace-git-worktree list --format json | jq '.[]'
 
 # Count worktrees by type
-ace-git-worktree list --show-tasks | grep "Task" | wc -l
+ace-git-worktree list --full | grep -c "Task"
 
 # Find worktrees with specific patterns
 ace-git-worktree list --search "bug" --format simple
@@ -184,7 +184,7 @@ ace-git-worktree list | grep -v "bare\|detached"
 
 ```bash
 # Get comprehensive status
-ace-git-worktree list --show-tasks --format json
+ace-git-worktree list --format json
 
 # Check specific worktree
 ace-git-worktree switch 081 --verbose
@@ -199,7 +199,7 @@ ace-git-worktree config --validate
 
 ```bash
 # Get all worktrees as JSON
-WORKTREES=$(ace-git-worktree list --format json --show-tasks)
+WORKTREES=$(ace-git-worktree list --format json)
 
 # Extract specific information
 echo "$WORKTREES" | jq '.worktrees[] | select(.task_id == "081")'
@@ -311,7 +311,7 @@ fi
 
 # 1. Check current worktree status
 echo "=== Current Worktree Status ==="
-ace-git-worktree list --show-tasks --format simple
+ace-git-worktree list --format simple
 
 # 2. Clean up if needed
 echo "=== Cleanup Check ==="

data/handbook/workflow-instructions/git/worktree.wf.md

@@ -72,7 +72,7 @@ ace-git-worktree create feature-branch --no-mise-trust
 ace-git-worktree list
 
 # Show task associations
-ace-git-worktree list --show-tasks
+ace-git-worktree list
 
 # Filter by task association
 ace-git-worktree list --task-associated
@@ -170,7 +170,7 @@ git:
 
 ### list
 - `--format <format>`: Output format (table, json, simple)
-- `--show-tasks`: Include task associations
+- `--full`: List every worktree (including inactive) with absolute paths
 - `--task-associated`: Filter by task association
 - `--search <pattern>`: Filter by search pattern
 

data/lib/ace/git/worktree/atoms/duration_parser.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Worktree
+      module Atoms
+        # Parses the `--active-within` activity window into hours.
+        #
+        # Accepted forms: `Nm` (minutes), `Nh` (hours), `Nd` (days), and bare
+        # integers (interpreted as hours). The canonical label echoes the
+        # operator's unit so the table header reads the way it was requested
+        # (`3d` -> "3d", `5` -> "5h").
+        #
+        # @example Parse a window
+        #   DurationParser.parse("18h") # => {hours: 18.0, label: "18h"}
+        #   DurationParser.parse("90m") # => {hours: 1.5, label: "90m"}
+        #   DurationParser.parse("5")   # => {hours: 5.0, label: "5h"}
+        #
+        # @example Invalid window
+        #   DurationParser.parse("abc") # raises ArgumentError
+        module DurationParser
+          # Default activity window label
+          DEFAULT_LABEL = "18h"
+
+          # Accepted duration shape: positive integer + optional unit
+          PATTERN = /\A(\d+)([mhd])?\z/
+
+          class << self
+            # Default activity window in hours (no unit = hours follows).
+            # @return [Hash] parsed default window
+            def default
+              parse(DEFAULT_LABEL)
+            end
+
+            # Parse a duration string into hours.
+            #
+            # @param value [String, nil] raw CLI value
+            # @return [Hash] `{hours: Float, label: String}`
+            # @raise [ArgumentError] when the value is empty, zero, negative, or
+            #   not one of the accepted forms
+            def parse(value)
+              raw = value.to_s.strip
+              raise invalid_duration(value) if raw.empty?
+
+              match = PATTERN.match(raw)
+              raise invalid_duration(value) unless match
+
+              amount = Integer(match[1], 10)
+              unit = match[2]
+              raise invalid_duration(value) if amount <= 0
+
+              {hours: hours_for(amount, unit), label: "#{amount}#{display_unit(unit)}"}
+            end
+
+            private
+
+            # @return [Float] duration expressed in hours
+            def hours_for(amount, unit)
+              case unit
+              when "m" then amount / 60.0
+              when "d" then amount * 24.0
+              else amount.to_f # "h" or bare integer
+              end
+            end
+
+            # @return [String] unit to echo back (bare integers render as hours)
+            def display_unit(unit)
+              unit || "h"
+            end
+
+            def invalid_duration(value)
+              ArgumentError.new(
+                "invalid duration '#{value}'. Use forms like 30m, 18h, 2d, or bare hours."
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end