gitflash 0.7.0.beta1 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8466fec203a9fdd7ac08e721fb0bb624fb8f486e68f9b369660e5d369e717ad
-  data.tar.gz: 53243a2e0dc1d5877bd5541999fec636e89ac882b9af78d84790ef32be3e12cb
+  metadata.gz: cf03db9e16e9f006dae9721b8ba1b16faf97218d98ea53768ff27b1b3c017069
+  data.tar.gz: a369a61204dd224d254b53b00488f5dbab9f344b1dfad49e17762caf575e8d59
 SHA512:
-  metadata.gz: 27b78d4baac19b15a9f6bef731cc0ec3622ee5c51a2ee82ab9f20a63a5f50d6ecedb3c4f1651d0849eae970f5a66c20480272d0bf00b0284e8434f1893805901
-  data.tar.gz: 1c1f6e76de4e2f67fb7c1c591e9569d8578a96cad8cc9e58ff75fd9448abaa8ead4e7b96cef519d6a4a991e75299e07eaafcc8d060896b8742b9c7f4ec4b93f5
+  metadata.gz: 66c9f53118048f0071f77952c9d59d761ced1af71bbb19f829e08b84e6fbfbf7f09f13ce440fe6cadfae97ffd9f377a540153d0caa19e1ede8aaa40d9ecfc161
+  data.tar.gz: e93052d61297e1e36c15a601a5bc8f6d0053145ceb3f613d45a418457321691999f400a48715cf1a7654b313cb68902854015e23ef9142a345d419b9591667e9

data/CHANGELOG.md

@@ -87,3 +87,62 @@ Beta of the parallel agent work release. Install with `gem install gitflash --pr
 - The Claude Code hook also runs after Bash commands (`PostToolUse`): branches created with plain git (`checkout -b`, `switch -c`, `branch NAME`, `worktree add`) are marked as agent work. `hook install` adds it, so run it again after upgrading; `hook status` reports whether marking is on. A gitflash hook under a matcher that does not cover Bash no longer counts as installed
 - JSON schema: new commands `clean`, `mark`, `pick` and `worktree ...`, error codes `invalid_config`, `unknown_worktree`, `protected_worktree` and `conflict`, the `owner` field, and `recreate_worktree` in the `undo` plan
 - Author names from other branches are shown with control characters escaped in `pick` output
+
+## [0.7.0.beta2] - 2026-10-08
+
+Second beta of the parallel agent work release: the `pick` branch list, a quieter `hook claude` and a round of security fixes on top of beta1. Install with `gem install gitflash --pre`. If you installed the hook before, run `gitflash hook install` again. Needs git 2.36 or newer.
+
+- `pick` without a source branch shows a list of the other local branches in a terminal, as `checkout` does; without a terminal the source is still required
+- `hook claude` is no longer listed in `gitflash hook` help (it is run by Claude Code, not by hand; `gitflash hook help claude` still describes it) and prints a short note instead of waiting for input when run in a terminal. The `hook` line in `gitflash help` now says it installs and checks the Claude Code hooks
+- Security hardening, from a CodeRabbit scan of the repository:
+  - Snapshots save untracked files whose names look like Git pathspec magic (`:(exclude)*`) or start or end with a space; before, such a name could drop other files from the snapshot. `Repo#toplevel` and the git readers keep whitespace at the end of a path
+  - Confirmation prompts show control characters in paths as escapes, as other output does
+  - `protected` branch patterns of the user file and the repository file add up; a repository can protect more branches but can no longer remove the ones the user protects
+  - `worktree_dir` may only use `%<repo>s` and `%<branch>s` and is limited to 512 characters (anything else is `invalid_config`); a format width such as `%<repo>999999999s` could exhaust memory
+  - `pick --continue --dry-run` only shows the plan
+  - `pick` reads `git log -z` with one field per line, so a commit message cannot forge entries in the list, and only commits found by `git rev-list` are offered
+  - The git runner never hands a lone string to a shell
+  - The Claude hook in `ask` mode asks also when no snapshot could be saved, notices bundled branch flags (`git branch -qD x`), `git clean -i`, and commands inside `bash -c`, `sh -c` and `eval`, and marks a branch as agent work only if it did not exist before the command
+  - `hook install` refuses to write `.claude` settings through a symbolic link in the repository (the user scope may be a link)
+  - `docs/map/_meta/check.rb` and `sync-twins.sh` do not follow links, read files over 2 MB, or print raw file names
+  - Output keeps a path from the repository on one line: a newline or tab in a worktree path is shown as an escape, so it cannot forge a row in the confirmation text, the list or the menus. `Repo#toplevel` and the git readers remove only git's final newline, not a carriage return that ends the path
+  - When a command touches several directories the hook tells Claude one `gitflash undo` command per snapshot; a failure to record branches never stops the snapshot; the record directory is refused unless it is a real directory only the user can use
+  - A literal backslash in a path is shown doubled, so a path with a newline and a path with the characters backslash and n stay two different choices in the `wt remove` menu
+  - The hook marks a branch the command deleted and created again (`git branch -D x && git switch -c x`) as agent work: the record keeps a branch's creation stamp, not only its name
+
+## [0.7.0.beta3] - 2026-10-25
+
+Third beta of the parallel agent work release: the fixes of a security review of the repository (issues #34 to #54), each reviewed before merging. Install with `gem install gitflash --pre`. Needs git 2.36 or newer.
+
+Some behaviour changes, so check scripts and agent instructions that call gitflash:
+
+- `gc`, and `wt remove` / `wt clean` of a worktree with ignored files, are no longer confirmed by `--yes`: pass `--confirm TOKEN` with the token the refusal names
+- `gc --older-than` takes a whole number of days, 1 or more
+- `mark` without `--owner` marks the branch as `human` when stdin is a terminal
+- `clean` and `delete` also protect `develop`, `development`, `trunk` and `release/*`
+- A repository's `worktree_dir` must stay next to the repository; set other places in `~/.config/gitflash.yml`
+- Usage errors exit with 2 and, with `--json`, print the JSON envelope
+
+The changes:
+
+- The Claude hook no longer lets a command through when it fails in `ask` or `deny` mode: an error now asks the user or blocks the command, with the reason. A snapshot that fails no longer stops `ask` mode from asking, and `cd ~unknownuser` or `git -C ~unknownuser` no longer makes the hook fail (#34)
+- The Claude hook snapshots the directory Claude runs in when a `cd` or `git -C` path is decided by the shell (`cd "$(git rev-parse --show-toplevel)"`, `cd "$REPO"`, `cd -`); before, it looked for a directory with that literal name and saved nothing. It says that directory was a guess and may not be the repository the command changes, and it tells the agent about every risky command it could not snapshot, in snapshot mode too, instead of staying silent (#35)
+- The Claude hook sees git commands inside shell syntax: after `if`, `then`, `do`, `while`, `!` and the like, inside `$(...)`, `<(...)` and backticks, and after a quote escaped with a backslash (`echo "a\"b"; git reset --hard`). Quotes are followed as the shell does, and a command nested deeper than three levels counts as risky instead of being skipped. Before, `deny` mode let these through and snapshot mode saved nothing (#36)
+- The Claude hook sees git behind wrappers with options (`sudo -u me`, `env -i`, `/usr/bin/env`, `timeout 5`, `nice -n 5`, `xargs`, `find -exec`), expands git aliases (`-c alias.x=...` and the repository's `alias.*`, including `!` aliases), snapshots the repository that `--work-tree`, `--git-dir`, `GIT_WORK_TREE` or `GIT_DIR` names, follows `pushd`, and no longer takes a redirection such as `> out` for a branch name. When a command deletes branches it does not name, the snapshot keeps every branch instead of none (#37)
+- The Claude hook snapshots before more commands that lose work: `git rm -f`, `git checkout-index -f`, `git read-tree -u --reset`, `git reflog expire` and `delete`, `git gc --prune=now`, `git prune`, `git push . :branch`, `git update-ref --stdin`, `git worktree remove` without `--force` (it still deletes ignored files), and `git clean` without `-f` when `clean.requireForce` is false (#38)
+- `gc --older-than` takes a whole number of days, 1 or more. Before, `0` or a negative value selected every snapshot, including the newest, and a fraction such as `0.5` selected snapshots older than that part of a day (#39)
+- `hook install` keeps the installed mode when run without `--mode`; before, running it again (as the upgrade note says) silently turned `ask` or `deny` back into `snapshot`. A weaker `--mode` now needs `--downgrade`, and the result reports `mode` and `previous_mode` (#40)
+- The Claude hook no longer suggests that `gitflash undo` brings everything back: for `git clean -x`/`-X` and `git worktree remove` it names the ignored files that will be deleted (no snapshot saves them), and it names untracked files over 50 MB that a snapshot left out (#41)
+- `--yes` no longer confirms a change `gitflash undo` cannot revert. `gc` (which deletes snapshots) now fails with `confirmation_required` and a `confirm_token` in the error; re-run with `--confirm TOKEN` to make that exact change, or type the token in a terminal. The token is made from the plan, so it never confirms a different change (#42)
+- `wt remove` and `wt clean` no longer delete ignored files (`.env`, local databases) on `--yes` alone: when a chosen worktree has ignored files, which no snapshot saves, confirming needs `--confirm TOKEN`, as for `gc` (#43)
+- `undo` without an ID restores the latest snapshot taken in the current worktree, not the newest one in the repository, which can belong to another agent working in a parallel worktree. The plan shows the snapshot's `reason` (#44)
+- `clean` and `delete` also protect `develop`, `development`, `trunk` and `release/*`, so a git-flow `develop` merged into `main` is no longer deleted. When the repository has a remote but no `origin/HEAD`, `clean` warns that the default branch was guessed (#45)
+- `--json` prints the envelope for every error of the commands that use it (all but `schema` and `version`, which print their own output). An unexpected error is reported as `failed` (exit 1) instead of a stack trace. A bad option or unknown command is `invalid_usage` with exit 2, as the README says, instead of Thor's text and exit 1. A damaged snapshot ref is skipped with a warning instead of breaking every command that takes a snapshot. Settings whose root is not an object, or that cannot be read, are `invalid_settings`. A path with an unknown `~user` is a usage error (#46)
+- Snapshots read from refs are checked before use: one whose ref name does not match its id, or that holds a commit id that is not a full SHA, an invalid branch name or a relative worktree path, is skipped with a warning. Snapshots are ordered by the time they were taken, not by ref name, so a planted ref cannot become the default for `undo` (#48)
+- A worktree argument that is one worktree's path and another worktree's branch is refused as ambiguous instead of picking whichever is listed first (#52)
+- `mark` without `--owner` marks the branch as `human` when stdin is a terminal and as `agent` otherwise (agents and scripts without a terminal; a script run from a terminal should pass `--owner agent`). Before, a person running `gitflash mark` to claim a branch marked it as agent work, which `clean --agent --force` deletes (#50)
+- A repository's `.gitflash.yml` can no longer place worktrees anywhere on disk: its `worktree_dir` must be a relative path that stays next to the repository (no absolute path, `~` or climbing above the repository's parent), and `worktree_dir` in `~/.config/gitflash.yml` now wins over the repository's (#47)
+- New `snapshot_exclude` setting: untracked files whose path or name matches (for example `*.pem`, `.env*`) are never copied into snapshots, and are listed as `excluded_files`. The README now explains that snapshots copy every untracked file that is not ignored into git objects (#49)
+- `protected` patterns accept `{a,b}` alternatives, and a pattern that could never match a branch (a space at either end, a control character, `~`, `^`, `:` or `\`, `..` outside a `{a,b}` alternative, or an empty one) is `invalid_config` instead of silently protecting nothing (#51)
+- `hook install` writes the settings file in one step (a temporary file renamed into place), keeps its permissions and a dotfiles link, and refuses a `hooks` value it cannot add to. A crash while writing can no longer leave a broken settings file that Claude Code would ignore, together with your permission rules (#53)
+- CI: every GitHub Action is pinned to a commit SHA, checkout no longer keeps the token in the git config, and Dependabot proposes updates to the pins (#54)

data/README.md

@@ -24,7 +24,7 @@ Or install it yourself as:
 
     $ gem install gitflash
 
-Prerelease versions such as `0.7.0.beta1` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta1'` in a Gemfile.
+Prerelease versions such as `0.7.0.beta3` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta3'` in a Gemfile.
 
 ## Requirements
 
@@ -38,16 +38,16 @@ Run `gitflash` inside a git repository to get a list with the available commands
 | --- | --- |
 | `gitflash branches` | List local branches with last commit, upstream status and merge status. Filter with `--merged`, `--gone` or `--stale DAYS` |
 | `gitflash checkout [BRANCH]` | Check out a branch, or pick one from a list |
-| `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current, default, `main` and `master` branches are protected. Unmerged branches are kept unless you pass `--force` |
+| `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current and default branch, `main`, `master`, `develop`, `development`, `trunk` and `release/*` are protected. Unmerged branches are kept unless you pass `--force` |
 | `gitflash reset [COMMIT]` | Reset to a commit, or pick one of the latest 100. Mixed by default; `--soft` keeps changes staged, `--hard` discards them after confirmation |
-| `gitflash mark [BRANCH...]` | Mark branches as agent (default) or human work, or `--clear` the mark. Without a branch it marks the current one. Use it for branches made with plain git so `clean --agent` can find them |
-| `gitflash clean` | Delete merged branches and branches whose upstream is gone, with a snapshot first. `--stale [DAYS]` and `--agent` add stale and agent-created branches; unmerged ones are kept unless `--force`. Protected: current, default, `main`, `master`, `protected` in `.gitflash.yml`, branches checked out in a worktree |
+| `gitflash mark [BRANCH...]` | Mark branches as agent or human work (default: human when stdin is a terminal, agent otherwise; a script run from a terminal should pass `--owner agent`), or `--clear` the mark. Without a branch it marks the current one. Use it for branches made with plain git so `clean --agent` can find them |
+| `gitflash clean` | Delete merged branches and branches whose upstream is gone, with a snapshot first. `--stale [DAYS]` and `--agent` add stale and agent-created branches; unmerged ones are kept unless `--force`. Protected: current, default, `main`, `master`, `develop`, `development`, `trunk`, `release/*`, `protected` in `.gitflash.yml`, branches checked out in a worktree |
 | `gitflash worktree` (`wt`) `list`, `add`, `remove`, `clean`, `prune`, `lock`, `unlock`, `move` | Worktrees for parallel agent work, with absolute paths in `--json` (see below) |
-| `gitflash pick SOURCE [SHA...]` | Cherry-pick commits from another branch: `--list` shows what is missing here, `--continue`, `--skip` and `--abort` handle conflicts |
-| `gitflash undo [SNAPSHOT]` | Restore a snapshot, the latest by default: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
+| `gitflash pick [SOURCE] [SHA...]` | Cherry-pick commits from another branch (pick SOURCE from a list when you omit it): `--list` shows what is missing here, `--continue`, `--skip` and `--abort` handle conflicts |
+| `gitflash undo [SNAPSHOT]` | Restore a snapshot, by default the latest one taken in this worktree: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
 | `gitflash snapshot` | Save the current state on request (`--scope`, `--message`) |
 | `gitflash snapshots` | List snapshots, newest first |
-| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`) |
+| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`, at least 1) |
 | `gitflash hook install` | Protect plain git commands run by Claude Code and mark the branches it creates (see below) |
 | `gitflash hook status` | Show whether the hook protects Claude Code sessions in the current directory |
 | `gitflash schema` | Print the JSON Schema of the `--json` output |
@@ -57,18 +57,21 @@ Run `gitflash` inside a git repository to get a list with the available commands
 
 `gitflash wt add feature` creates a worktree (default `../<repo>.worktrees/feature`) and marks a new branch as agent work. For a branch made with plain git, run `gitflash mark` on it (no argument marks the current branch). `gitflash wt list --json` gives every worktree's absolute path, branch, dirty state, ahead/behind, merge status, lock state and owner, so an agent never has to switch directories.
 
-`gitflash wt remove` and `gitflash wt clean` save a snapshot first, and `gitflash undo` adds the worktree back with its branch and uncommitted files. Ignored files (`.env`, `node_modules`) are not saved: the plan lists them before they are deleted. A worktree with an untracked file over 50 MB is not removed.
+`gitflash wt remove` and `gitflash wt clean` save a snapshot first, and `gitflash undo` adds the worktree back with its branch and uncommitted files. Ignored files (`.env`, `node_modules`) are not saved: the plan lists them before they are deleted, and removing a worktree that has some needs `--confirm TOKEN` (the token the refusal names) instead of `--yes`. A worktree with an untracked file over 50 MB is not removed.
 
 `gitflash pick other-branch --list` lists the commits missing here (a commit whose patch is already here is marked `=`). `gitflash pick other-branch SHA... --yes` applies them oldest first with `-x`. On a conflict it stops and lists the files; resolve them and run `gitflash pick --continue`, or `--skip` / `--abort`.
 
-Settings live in `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins):
+Settings live in `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins, except for `worktree_dir`, where your own file wins; a repository's `worktree_dir` must be a relative path that stays next to the repository):
 
 ```yaml
-protected: ["release/*"]   # branch patterns clean and delete never touch
+protected: ["release/*", "hotfix/{a,b}"]   # branch patterns clean and delete never touch; both files add up
 stale_days: 30             # used by --stale without a number
-worktree_dir: "../%<repo>s.worktrees/%<branch>s"
+worktree_dir: "../%<repo>s.worktrees/%<branch>s"   # only these two placeholders, up to 512 characters
+snapshot_exclude: ["*.pem", ".env*", "secrets"]   # untracked files snapshots never copy (a directory covers all below it); both files add up
 ```
 
+Snapshots copy every untracked file that is not ignored (up to 50 MB) into git objects under `refs/gitflash/snapshots/`. A stray secret that is not in `.gitignore` is copied too, and a `git push --mirror` or a `refs/*` refspec would publish it. Ignore such files, or list them in `snapshot_exclude`; files left out this way cannot be restored by `gitflash undo`.
+
 ### Undo
 
 Before every change it makes, gitflash saves a snapshot: branches, HEAD, tracked, staged and untracked files, and stash entries. Snapshots are plain git objects under `refs/gitflash/snapshots/`; the working tree is never touched while saving. Git's own `revert` and `reflog` cover committed work; snapshots also cover what git never recorded: uncommitted and untracked files, deleted branches (git deletes their reflog) and dropped stashes.
@@ -91,9 +94,9 @@ Agents often run git directly. Claude Code's own checkpoints do not cover change
 gitflash hook install
 ```
 
-Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them.
+Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them. If the hook itself fails, `ask` mode still asks and `deny` mode blocks the command.
 
-The same install adds a second hook that runs after a command: when the agent creates a branch with plain git (`git checkout -b`, `git switch -c`, `git branch NAME`, `git worktree add`), gitflash marks it as agent work, so `gitflash clean --agent` can find it. Only new, unmarked branches are marked, and `gitflash mark BRANCH --owner human` changes it. If you installed the hook with an earlier version, run `gitflash hook install` again to add it; `gitflash hook status` says whether branch marking is on.
+The same install adds a second hook that runs after a command: when the agent creates a branch with plain git (`git checkout -b`, `git switch -c`, `git branch NAME`, `git worktree add`), gitflash marks it as agent work, so `gitflash clean --agent` can find it. Only new, unmarked branches are marked, and `gitflash mark BRANCH --owner human` changes it. If you installed the hook with an earlier version, run `gitflash hook install` again to add it (the installed `--mode` is kept; a weaker mode needs `--downgrade`); `gitflash hook status` says whether branch marking is on.
 
 Where the hook goes, following Claude Code's own rules:
 
@@ -125,6 +128,7 @@ Without a terminal (for example in a script, CI or an AI coding agent), gitflash
 
 - A command that needs a list selection fails with exit code 2 and says which argument to pass.
 - A destructive action (`delete`, `reset --hard`) fails with exit code 2 and returns the plan unless you pass `--yes`.
+- A change `gitflash undo` cannot revert (`gc`, which deletes snapshots, and `wt remove` or `wt clean` of a worktree with ignored files) is not covered by `--yes`: it fails with exit code 2 and names a token (with `--json`, the plan and `error.confirm_token`; `--dry-run` shows the plan as text). Re-run with `--confirm TOKEN` to make that exact change; in a terminal you type the token instead.
 
 With `--json`, every command prints one object in the same envelope, defined in [schema/v1.json](schema/v1.json) (also printed by `gitflash schema`):
 

data/command_descriptions.yml

@@ -26,7 +26,8 @@ delete:
   short: 'Delete branches'
   long: |
     Deletes the given BRANCHES. Without them, presents a list with the local branches
-    (without the current, default, main or master branch): press `space` to choose
+    (without the current and default branch or main, master, develop, development, trunk and
+    release/*): press `space` to choose
     branches and `enter` to confirm. Without a terminal, BRANCHES are required.
 
     Branches with unmerged changes are kept unless --force is given.
@@ -48,7 +49,7 @@ reset:
     confirmation; pass --yes to skip it, which is required without a terminal.
 
 undo:
-  short: 'Restore a snapshot (the latest by default)'
+  short: 'Restore a snapshot (the latest of this worktree by default)'
   long: |
     Restores the parts of the repository a snapshot saved: deleted or moved branches,
     HEAD, tracked, staged and untracked files, and dropped stash entries. Only parts that
@@ -57,6 +58,12 @@ undo:
     gitflash saves a snapshot before every change it makes, and the agent hook saves one
     before destructive git commands. List them with `gitflash snapshots`.
 
+    Without SNAPSHOT it restores the latest snapshot taken in this worktree. All worktrees of
+    a repository share the snapshots, so the newest one may belong to another agent's
+    worktree. To restore one of those, run `gitflash undo ID` in the worktree it was taken in;
+    here an ID from elsewhere works only for a snapshot that saved branches alone. The plan
+    shows the snapshot's reason.
+
     The current state is saved as a new snapshot first, so an undo can itself be undone.
     Asks for confirmation; pass --yes to skip it (required without a terminal) or
     --dry-run to only show the plan.
@@ -83,8 +90,10 @@ clean:
       --stale [DAYS] no commits for DAYS days (default: `stale_days` setting, 30)
       --agent        created by an agent (marked by `gitflash wt add`)
 
-    Never selected: the current and default branch, main, master, `protected` branches from
-    .gitflash.yml, and branches checked out in any worktree. Unmerged branches are kept unless
+    Never selected: the current and default branch, main, master, develop, development, trunk,
+    release/*, `protected` branches from .gitflash.yml, and branches checked out in any
+    worktree. With an origin remote but no origin/HEAD the default branch is guessed, and
+    the plan warns about it. Unmerged branches are kept unless
     --force is given. Every chosen branch lists why it was chosen.
 
     Asks for confirmation; pass --yes to skip it (required without a terminal), or --dry-run.
@@ -98,7 +107,9 @@ worktree_remove:
 
     Each removal saves a snapshot first, including uncommitted and untracked files. Ignored
     files (build output, dependencies, .env) are not saved: the plan and the confirmation list
-    them, since removal deletes them for good. A worktree with an untracked file over 50 MB
+    them, since removal deletes them for good, and --yes is not enough to confirm that: pass
+    --confirm TOKEN with the token the refusal names (error.confirm_token in --json), or
+    type it in a terminal. A worktree with an untracked file over 50 MB
     is not removed, because the snapshot cannot hold it. `gitflash undo ID` brings the
     directory, its branch and the saved files back.
 
@@ -110,6 +121,10 @@ pick:
   long: |
     Moves fixes between branches, for example between agent branches.
 
+    Without SOURCE, a terminal shows a list of the other local branches to choose from (use the
+    arrow keys, type to search, `enter` to choose and `ctrl+c` to cancel). Without a terminal,
+    SOURCE is required.
+
     `gitflash pick SOURCE --list` lists the commits of SOURCE that are not on the current branch
     yet, oldest first, with SHA, subject, author, date and a diff summary. A commit whose change
     is already here (the same patch under another SHA) is marked `=` (`applied` in JSON) and is
@@ -138,8 +153,11 @@ mark:
     created. The mark is the git config key `branch.<name>.gitflash-owner` and disappears with
     the branch.
 
-    Without BRANCH the current branch is marked. The owner is `agent` unless --owner human is
-    given; --clear removes the mark. A branch without a mark counts as human work.
+    Without BRANCH the current branch is marked. Without --owner the owner is `human` when you
+    run it in a terminal and `agent` when stdin is not a terminal (agents, CI), so a person
+    never marks their own branch as one `clean --agent` deletes; a script run from a terminal
+    should pass --owner agent; --clear removes the mark. A
+    branch without a mark counts as human work.
 
     `gitflash wt add` marks the branches it creates. Use `gitflash mark` for branches made with
     plain git, for example at the start of an agent session: `gitflash mark`.

data/lib/gitflash/atomic_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Gitflash
+  # Replaces a file in one step: the text goes to a temporary file next to it, which is then
+  # renamed into place, so a crash never leaves half a file. The file keeps its permissions,
+  # and a symbolic link (dotfiles) is followed, so the link stays and its target changes.
+  module AtomicFile
+    module_function
+
+    def write(path, text)
+      path = link_target(path) if File.symlink?(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      file = Tempfile.create(['.gitflash', File.extname(path)], File.dirname(path))
+      replace(file, path, text)
+    end
+
+    # Where a link points, also when that file does not exist yet: the link's directory and the
+    # target's directory are resolved, the file name is kept
+    def link_target(path)
+      target = File.expand_path(File.readlink(path), File.dirname(path))
+      return File.realpath(target) if File.exist?(target)
+
+      File.join(File.realpath(File.dirname(target)), File.basename(target))
+    end
+
+    def replace(file, path, text)
+      file.write(text)
+      file.flush
+      file.fsync
+      file.close
+      File.chmod(File.stat(path).mode & 0o7777, file.path) if File.exist?(path)
+      File.rename(file.path, path)
+    ensure
+      FileUtils.rm_f(file.path) if file && File.exist?(file.path)
+    end
+  end
+end

data/lib/gitflash/cherry_pick/log_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Gitflash
+  class CherryPick
+    # Reads the output of `git log -z --shortstat --format=FORMAT` into Candidate records.
+    #
+    # One field per line: a subject or an author name cannot hold a newline, and `-z` ends each
+    # commit with a NUL, which text cannot hold either, so the framing is unambiguous whatever a
+    # commit message says. Git prints the fields of a commit, a NUL, the stat of that commit and
+    # the fields of the next one. So chunk 0 holds the fields of commit 0, chunk i the stat of
+    # commit i-1 and the fields of commit i, and the last chunk only a stat.
+    module LogParser
+      FORMAT = '%m%n%H%n%s%n%an%n%cI'
+      FIELDS = 5
+
+      module_function
+
+      def parse(output)
+        chunks = output.split("\0", -1)
+        stats = stats_of(chunks)
+        fields = chunks[0...-1].map { |chunk| chunk.lines(chomp: true).last(FIELDS) }
+        fields.each_with_index.filter_map do |row, index|
+          candidate(row, stats[index + 1]) if row.size == FIELDS
+        end
+      end
+
+      def stats_of(chunks)
+        last = chunks.size - 1
+        chunks.each_with_index.map { |chunk, index| stat_part(chunk, index == last) }
+      end
+
+      # The part of a chunk before the fields of the next commit; the last chunk is all stat
+      def stat_part(chunk, last)
+        last ? chunk : chunk.lines(chomp: true)[0...-FIELDS].to_a.join("\n")
+      end
+
+      def candidate(row, stat_text)
+        mark, sha, subject, author, date = row
+        files, insertions, deletions = stat(stat_text)
+        Candidate.new(sha: sha, subject: subject, author: author, date: date,
+                      applied: mark == '=', files: files, insertions: insertions,
+                      deletions: deletions)
+      end
+
+      # [files, insertions, deletions] from a line such as
+      # " 2 files changed, 3 insertions(+), 1 deletion(-)". Split on commas and spaces, with no
+      # regular expression, so a long run of digits in the text costs only its own length.
+      def stat(text)
+        line = text.to_s.lines.map(&:strip).reject(&:empty?).last.to_s
+        counts = { 'file' => 0, 'insertion' => 0, 'deletion' => 0 }
+        line.split(',').each { |part| tally(counts, part) }
+        counts.values
+      end
+
+      def tally(counts, part)
+        count, label = part.strip.split(' ', 2)
+        number = Integer(count, 10, exception: false)
+        kind = counts.keys.find { |name| label.to_s.start_with?(name) }
+        counts[kind] = number if number && kind
+      end
+    end
+  end
+end

data/lib/gitflash/cherry_pick.rb

@@ -19,9 +19,6 @@ module Gitflash
     # The state of an unfinished pick: files with conflicts and the commits still to apply
     Progress = Data.define(:conflicted, :remaining, :current)
 
-    RECORD = "\x1e"
-    SEPARATOR = "\x1f"
-    FORMAT = ['%m', '%H', '%s', '%an', '%cI'].join(SEPARATOR)
     ENV_NO_EDITOR = { 'GIT_EDITOR' => 'true', 'GIT_SEQUENCE_EDITOR' => 'true' }.freeze
 
     def initialize(bash: Git::BashCommand)
@@ -38,10 +35,11 @@ module Gitflash
     # Commits of `source_ref` that are not merges, oldest first, each marked as applied when an
     # equivalent change (same patch) is already on HEAD
     def candidates(source_ref)
-      output = @bash.exec('git', 'log', '--left-right', '--cherry-mark', '--right-only',
-                          '--no-merges', '--reverse', '--shortstat', "--format=#{RECORD}#{FORMAT}",
+      output = @bash.exec('git', 'log', '-z', '--left-right', '--cherry-mark', '--right-only',
+                          '--no-merges', '--reverse', '--shortstat', "--format=#{LogParser::FORMAT}",
                           "HEAD...#{source_ref}", '--')
-      output.split(RECORD).reject { |record| record.strip.empty? }.map { |record| parse(record) }
+      eligible = eligible_shas(source_ref)
+      LogParser.parse(output).select { |candidate| eligible.include?(candidate.sha) }.uniq(&:sha)
     end
 
     # Applies the commits (full shas, in the given order) with `git cherry-pick`.
@@ -70,18 +68,12 @@ module Gitflash
 
     private
 
-    def parse(record)
-      line, *rest = record.split("\n", 2)
-      mark, sha, subject, author, date = line.split(SEPARATOR, 5)
-      files, insertions, deletions = stat(rest.first.to_s)
-      Candidate.new(sha: sha, subject: subject.to_s, author: author, date: date,
-                    applied: mark == '=', files: files, insertions: insertions,
-                    deletions: deletions)
-    end
-
-    def stat(text)
-      [text[/(\d+) files? changed/, 1], text[/(\d+) insertions?\(\+\)/, 1],
-       text[/(\d+) deletions?\(-\)/, 1]].map(&:to_i)
+    # The commits of the source that are not merges and not on HEAD, listed by git without any
+    # text a commit author controls. A commit message holding the separators of the log format
+    # could forge extra records; only SHAs found here become candidates.
+    def eligible_shas(source_ref)
+      @bash.exec('git', 'rev-list', '--right-only', '--no-merges', "HEAD...#{source_ref}", '--')
+           .lines(chomp: true).to_set
     end
 
     def conflicted_files

data/lib/gitflash/cli.rb

@@ -9,6 +9,18 @@ module Gitflash
 
     SCHEMA_PATH = File.expand_path('../../schema/v1.json', __dir__)
 
+    # Thor reports a bad option or argument as text with exit 1. It is a usage error, so it
+    # exits with 2, and with --json it is printed in the JSON envelope like every other error.
+    def self.start(given_args = ARGV, config = {})
+      config[:shell] ||= Thor::Base.shell.new
+      dispatch(nil, given_args.dup, nil, config)
+    rescue Thor::Error => e
+      UsageReport.new(given_args).print(e)
+      exit(2)
+    rescue Errno::EPIPE
+      nil
+    end
+
     def self.exit_on_failure?
       true
     end
@@ -16,7 +28,10 @@ module Gitflash
     class_option :json, type: :boolean, default: false,
                         desc: 'Print JSON instead of text; never prompts'
     class_option :yes, type: :boolean, aliases: '-y', default: false,
-                       desc: 'Skip confirmation prompts'
+                       desc: 'Skip confirmation prompts for changes gitflash undo can revert'
+    class_option :confirm, type: :string, banner: 'TOKEN',
+                           desc: 'Confirm a change gitflash undo cannot revert, with the token ' \
+                                 'from its plan'
     class_option :dry_run, type: :boolean, default: false,
                            desc: 'Show what would happen without changing anything'
 
@@ -45,7 +60,8 @@ module Gitflash
 
     desc 'mark [BRANCH...]', descriptions.mark.short
     long_desc descriptions.mark.long
-    option :owner, type: :string, enum: Ownership::OWNERS, desc: 'agent (default) or human'
+    option :owner, type: :string, enum: Ownership::OWNERS,
+                   desc: 'agent or human (default: human in a terminal, agent otherwise)'
     option :clear, type: :boolean, default: false, desc: 'Remove the mark'
     def mark(*branches)
       run_command('mark', Commands::Mark, *branches)
@@ -93,13 +109,20 @@ module Gitflash
     end
 
     desc 'gc', 'Delete old snapshots'
-    option :older_than, type: :numeric, banner: 'DAYS',
-                        desc: 'Delete snapshots older than DAYS days (default 30)'
+    long_desc <<~TEXT
+      Deletes snapshots older than --older-than DAYS (default 30). gitflash undo cannot bring a
+      deleted snapshot back, so --yes is not enough: without a terminal gc stops and names a
+      token (with --json also the plan and error.confirm_token); re-run with --confirm TOKEN to
+      delete exactly those snapshots. In a terminal you type the token. Pass --dry-run to see the
+      snapshots it would delete.
+    TEXT
+    option :older_than, type: :string, banner: 'DAYS',
+                        desc: 'Delete snapshots older than DAYS days, at least 1 (default 30)'
     def gc
       run_command('gc', Commands::Gc)
     end
 
-    desc 'hook SUBCOMMAND', 'Agent hooks: claude (run the hook), install (register it)'
+    desc 'hook SUBCOMMAND', 'Claude Code hooks: install them and check they are active'
     subcommand 'hook', HookCli
 
     desc 'pick [SOURCE] [SHA...]', descriptions.pick.short

data/lib/gitflash/command_runner.rb

@@ -14,10 +14,21 @@ module Gitflash
     rescue Error => e
       ui.error(e)
       exit(e.exit_code)
+    rescue StandardError => e
+      report_unexpected(ui, name, e)
+    end
+
+    # Anything else still gets the envelope, so a script reading --json is never left with a
+    # stack trace
+    def report_unexpected(ui, name, error)
+      unexpected = Error.new("#{name} failed unexpectedly: #{error.message} (#{error.class})")
+      ui.error(unexpected)
+      exit(unexpected.exit_code)
     end
 
     def build_ui(name)
-      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
+      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run],
+             confirm: options[:confirm])
     end
   end
 end

data/lib/gitflash/commands/base.rb

@@ -14,6 +14,9 @@ module Gitflash
 
       attr_reader :repo, :ui, :options
 
+      # A path from the repository, kept on one line of the output
+      def shown(path) = TerminalText.line(path)
+
       def require_interactive!(message)
         usage_error!('input_required', message) unless ui.interactive?
       end

data/lib/gitflash/commands/clean.rb

@@ -29,7 +29,34 @@ module Gitflash
       end
 
       def build_plan(names)
-        super.merge(reasons: @reasons.slice(*names), skipped: @skipped)
+        plan = super.merge(reasons: @reasons.slice(*names), skipped: @skipped)
+        warning ? plan.merge(warning: warning) : plan
+      end
+
+      def summary(names)
+        warning ? "#{super}\n\nNote: #{warning}" : super
+      end
+
+      # Without origin/HEAD, "merged" means merged into a local main or master, which may not be
+      # the branch the team ships from
+      def warning
+        return @warning if defined?(@warning)
+
+        @warning = if default_branch_guessed?
+                     'origin/HEAD is not set, so gitflash guessed the default branch ' \
+                       "(#{repo.default_branch || 'none'}). Run `git remote set-head origin " \
+                       '--auto` so merged branches are judged against the right one.'
+                   end
+      end
+
+      # An origin remote but no origin/HEAD: the default branch came from a local main or master
+      def default_branch_guessed?
+        _out, _err, set = Git::BashCommand.capture('git', 'symbolic-ref', '--quiet',
+                                                   "#{Repo::REMOTE_HEAD}HEAD")
+        return false if set
+
+        remotes, _err, = Git::BashCommand.capture('git', 'remote')
+        remotes.split.include?('origin')
       end
 
       def skipped_row(candidate)
@@ -38,6 +65,7 @@ module Gitflash
 
       def nothing_to_clean
         plan = { branches: [], force: force?, reasons: {}, skipped: @skipped }
+        plan[:warning] = warning if warning
         ui.report(status: 'noop', plan: plan, result: { deleted: [], failed: [] },
                   text: @skipped.empty? ? 'Nothing to clean' : skipped_text)
       end

data/lib/gitflash/commands/gc.rb

@@ -2,13 +2,14 @@
 
 module Gitflash
   module Commands
-    # Deletes snapshots older than --older-than DAYS (default 30). Git frees their objects at
-    # its next garbage collection.
+    # Deletes snapshots older than --older-than DAYS (default 30, at least 1). Git frees their
+    # objects at its next garbage collection. A whole number of days is required: 0 or a
+    # negative number would select every snapshot, including the one just taken.
     class Gc < Base
       DEFAULT_DAYS = 30
 
       def call
-        days = options[:older_than] || DEFAULT_DAYS
+        days = older_than_days
         old = older_than(days)
         plan = { older_than_days: days, snapshots: old.map(&:id) }
         return nothing(plan) if old.empty?
@@ -18,9 +19,23 @@ module Gitflash
 
       private
 
+      def older_than_days
+        value = options[:older_than]
+        return DEFAULT_DAYS if value.nil?
+
+        days = Integer(value.to_s, 10, exception: false)
+        return days if days&.positive?
+
+        usage_error!('invalid_options',
+                     "--older-than needs a whole number of days, 1 or more, got '#{value}'")
+      end
+
       def delete(plan, text)
         return planned(plan, "Would delete #{text}") if ui.dry_run?
-        return cancelled(plan) unless ui.confirm?("You are about to delete #{text}", plan: plan)
+
+        # Deleted snapshots are gone for good: no snapshot of the snapshots is kept
+        summary = "You are about to delete #{text}"
+        return cancelled(plan) unless ui.confirm?(summary, plan: plan, irreversible: true)
 
         plan[:snapshots].each { |id| snapshots.delete(id) }
         ui.report(status: 'done', plan: plan, result: { deleted: plan[:snapshots] },