allod change begin --resume: pick up an existing agent branch #229

New issue

Closed

opened 2026-09-27 01:14:54 +01:00 by allod-agent · 0 comments

allod-agent commented

2026-09-27 01:14:54 +01:00

Member

allod change begin --resume <description> <repo> picks up an agent/<description> branch that already exists on origin, so a session asked to continue another session's branch gets a worktree the same way it gets a fresh one instead of rebuilding begin's layout by hand.

Primary goals:

One command to resume — allod change begin --resume <description> <repo> creates a worktree under ~/changes on a local agent/<description> that tracks origin/agent/<description>, and prints the path, exactly as -d does for a new branch.
record and submit work from the path — the resumed worktree carries the same allod-change-branch handoff file that begin -d writes, so the rest of the change flow needs no special case.
Refuse the ambiguous cases — --resume dies when the branch does not exist on origin, when it already exists locally or is checked out in another worktree, and when -d is also given; the existing -d behavior is unchanged and still refuses a branch that exists.
Documented — allod change begin usage text and docs/ name the flag beside -d.

Current state and specifics

begin -d always cuts a new branch from the default branch and refuses to reuse one. cmd/allod/change.go:131 dies with "branch already exists locally" and cmd/allod/change.go:134 with "branch already exists on origin"; there is no flag that takes the second case as the intended starting point. The worktree is created at cmd/allod/change.go:154 with git worktree add <path> -b <branch> origin/<base>, and cmd/allod/change.go:162 writes the branch name to <git-dir>/allod-change-branch, which record and submit read.

A session that has to continue an existing branch currently mirrors that by hand:

path=$(mktemp -d ~/changes/<repo-slug>-<description>-XXXXXX)
git -C <repo> worktree add "$path" -b agent/<description> origin/agent/<description>
echo agent/<description> > "$(git -C "$path" rev-parse --path-format=absolute --git-dir)/allod-change-branch"

That works, but it is three git commands a reader has to know about, it bypasses the tool's own checks, and it is exactly the manual sequence agent-behavior.md says a project tool should replace. It came up on the allod/nexus#66 rename, where the branch had been started by one session and finished by another.

Default: --resume reuses the -d code path with the start point switched from origin/<default> to origin/agent/<description> and the "exists on origin" check inverted into a requirement. It does not fetch anything beyond the git fetch origin begin already runs, does not rebase, and does not touch the shared checkout.

Scope

In scope: the flag, its refusals, the handoff file, usage text and docs, and tests in the existing change test suite covering resume of an existing branch, refusal when the branch is missing on origin, and refusal when -d and --resume are combined. Out of scope: resuming a branch that has diverged from origin locally, and any change to record, submit, list, or cleanup.

`allod change begin --resume <description> <repo>` picks up an `agent/<description>` branch that already exists on origin, so a session asked to continue another session's branch gets a worktree the same way it gets a fresh one instead of rebuilding `begin`'s layout by hand. Primary goals: - **One command to resume** — `allod change begin --resume <description> <repo>` creates a worktree under `~/changes` on a local `agent/<description>` that tracks `origin/agent/<description>`, and prints the path, exactly as `-d` does for a new branch. - **`record` and `submit` work from the path** — the resumed worktree carries the same `allod-change-branch` handoff file that `begin -d` writes, so the rest of the `change` flow needs no special case. - **Refuse the ambiguous cases** — `--resume` dies when the branch does not exist on origin, when it already exists locally or is checked out in another worktree, and when `-d` is also given; the existing `-d` behavior is unchanged and still refuses a branch that exists. - **Documented** — `allod change begin` usage text and `docs/` name the flag beside `-d`. ### Current state and specifics `begin -d` always cuts a new branch from the default branch and refuses to reuse one. `cmd/allod/change.go:131` dies with "branch already exists locally" and `cmd/allod/change.go:134` with "branch already exists on origin"; there is no flag that takes the second case as the intended starting point. The worktree is created at `cmd/allod/change.go:154` with `git worktree add <path> -b <branch> origin/<base>`, and `cmd/allod/change.go:162` writes the branch name to `<git-dir>/allod-change-branch`, which `record` and `submit` read. A session that has to continue an existing branch currently mirrors that by hand: ``` path=$(mktemp -d ~/changes/<repo-slug>-<description>-XXXXXX) git -C <repo> worktree add "$path" -b agent/<description> origin/agent/<description> echo agent/<description> > "$(git -C "$path" rev-parse --path-format=absolute --git-dir)/allod-change-branch" ``` That works, but it is three git commands a reader has to know about, it bypasses the tool's own checks, and it is exactly the manual sequence `agent-behavior.md` says a project tool should replace. It came up on the `allod/nexus#66` rename, where the branch had been started by one session and finished by another. Default: `--resume` reuses the `-d` code path with the start point switched from `origin/<default>` to `origin/agent/<description>` and the "exists on origin" check inverted into a requirement. It does not fetch anything beyond the `git fetch origin` `begin` already runs, does not rebase, and does not touch the shared checkout. ### Scope In scope: the flag, its refusals, the handoff file, usage text and docs, and tests in the existing `change` test suite covering resume of an existing branch, refusal when the branch is missing on origin, and refusal when `-d` and `--resume` are combined. Out of scope: resuming a branch that has diverged from origin locally, and any change to `record`, `submit`, `list`, or `cleanup`.

allod-agent referenced this issue from a pull request that will close it,

2026-09-27 01:23:25 +01:00

change begin: add --resume for an existing agent branch #230

allod-agent referenced this issue from a commit

2026-09-27 01:23:26 +01:00

change begin: add --resume for an existing agent branch