v0.12.0

capcom — v0.12.0 — 2026-10-27

This release makes Tree locks safer to share between sessions and worktrees, lets the issue outline be filtered, and turns index and lock failures into messages that say what to do next.

Breaking changes

• Lock records no longer hold the token in the clear — a lock record now stores only a fingerprint of the Lock token, so reading the lock directory tells you who holds the lock but not how to act as them. An older capcom in the same clone cannot match the new record and treats it as held by another session. What to do: upgrade every capcom that works in the clone; if an older one is stuck, clear the lock with capcom lock break. Records written by older versions still work and are converted the next time the lock is touched or resumed.
• --plan takes a plan name, not a path — capcom create --plan and capcom update --plan now refuse (exit 1) a value that is absolute, contains / or \, or is . or .., and the message lists your plans directories. What to do: pass the plan's file name alone, with or without .md; --plan "" still clears it, and a name found in no plans directory is still saved, now with a warning.
• --json on a bare command group is a usage error — running capcom, capcom know, capcom dep, capcom lock or capcom related with --json and no subcommand now fails with <command> does not support --json and exit 2, instead of printing help and exiting 0. What to do: name a subcommand, or use --help to see the help.
• The AGENTS.md block needs a refresh — the Tree lock paragraph that capcom agents writes now explains that the lock is a signal, not a barrier: writes are never refused, but they warn and name the holder. Until you refresh it, capcom check and capcom agents --check report your existing block as out of date. What to do: run capcom agents once after upgrading.

New

• list --tree now filters — capcom list --tree combines with --status, --category, --label, --no-label, --type, --priority, --plan, --planned and --unplanned, keeping each matching issue together with its parents; a parent shown only for context ends with [context] (and "context": true in --json). Only --limit still cannot be combined with --tree.
• Writes tell you when another session holds the worktree — create, update, log, close, reopen, moves, removals, dependency and Note edits, and fmt or agents without --check still succeed, but now warn locked by <holder> (<purpose>) …; if it is yours, carry on when the Tree lock is held for something else. Writing the issue you started yourself, and start, finish and the lock commands, stay quiet.
• finish --keep-lock hands you the next command — it now prints the Lock token and its next: line spells out capcom start <next> --token <token>, so you can carry the lock straight on to the next issue (TOKEN= in --kv, lock.token in --json). A plain capcom start refused as locked now suggests the same --token form.
• prime --json reports whether this worktree is free — its data gains a worktree entry with the worktree's key, its lock state (free, held, stale, invalid or unreadable) and the same advice as the text's this worktree: line.

Improved

• Large stores list faster — list, ready, next, search and the other commands that read many issues now fetch them from the index in a fixed handful of reads instead of several per issue, so a store with thousands of issues answers noticeably sooner; output is unchanged.
• "Planned" means the plan file exists — capcom prime and ready/next --planned/--unplanned count an issue as planned only when its plan names a file in one of your plans directories. list --planned/--unplanned still go by whether the plan field is set, and their help now says so.
• Checking a lock no longer writes to disk — capcom lock check, capcom lock status, capcom prime and the terminal UI no longer create .git/capcom/locks/ or a guard file just to read the lock. On a read-only lock directory, lock check now answers 0 or 3 from the record instead of failing with exit 1.
• A busy index explains itself — when another command such as capcom reindex holds the index past the five-second wait, commands now fail with the index is busy: … retry when it finishes instead of a raw database is locked (SQLITE_BUSY) error, and capcom prime no longer advises a reindex for it.
• A damaged lock record points to the fix — lock check, lock acquire, lock touch, lock release and start meeting a lock record that cannot be read now fail with the lock record cannot be read and the hint capcom lock status, then capcom lock break, in text and --json.
• Warning when frontmatter comments are dropped — editing, moving or removing an issue or Note whose frontmatter contains a YAML comment now warns frontmatter comments are not kept; capcom writes frontmatter in canonical form, instead of losing the comment silently.
• Tree and dependency JSON match the text — list --tree --json now includes each parent's children progress (total, closed) and the more count of a --depth cut, and dep list --json marks an issue shown as (see above) with repeat: true and carries more.

Fixed

• Removed worktrees no longer leave their lock behind — a lock left by a linked worktree that was removed, or removed and re-created at the same path, now counts as free: capcom lock check exits 0 and lock acquire or start takes it over with a new token. lock status and prime show such a lock as free (orphaned record of a removed worktree), with "orphaned": true in --json.
• Moving an issue or Note keeps Note Refs valid — capcom mv and capcom know mv now rewrite every Note Ref that pointed at the moved file or anything under it, keeping any #symbol, so capcom check no longer fails on stale Refs afterwards. Both commands list the Notes they changed as refs_rewritten (REFS_REWRITTEN= in --kv).
• capcom reindex repairs a corrupt index — it now deletes a damaged index.db with its -wal and -shm files and builds a fresh one, where it used to fail on the bad file; other commands meeting a corrupt index fail with the hint capcom reindex.
• Edits that keep a file's size and timestamp are no longer missed — the index now also notices a change that leaves a file's size and modification time as they were, so list, show and search show the new content. The index rebuilds itself once on the first command after upgrading.
• A lock from a fast clock no longer sticks — a Tree lock whose heartbeat is dated more than one TTL in the future now counts as stale, so capcom lock acquire --take-stale can take it over, and the locked error no longer shows negative ages.
• Resuming a lock under a new purpose retires the old one — capcom lock acquire --purpose <new> --token <token> or capcom start <id> --token <token> now moves the lock to the new purpose, so a session still using the old purpose is refused as locked (exit 3) instead of taking the lock back.

Docs & install

• Search help covers Chinese, Japanese and Korean text — capcom search --help and capcom know search --help now explain that a run of CJK characters without spaces counts as one word, so 登录超时问题 is found by the whole run and not by 登录.
• Corrected examples — the --ref example in the README and in capcom know add --help now points at a file that exists, and the terminal UI guide no longer shows a fixed capcom version in its sample screen.