magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
2 min read

worktree-remove

A deny rule by default: it refuses removing a worktree magus cannot prove holds nothing that would be lost, and names what to run instead.

What it catches

Removing a worktree magus cannot prove holds nothing that would be lost.

Why

A worktree may be where another session is working right now, and what it holds may exist nowhere else. git worktree remove passes only when every condition holds: the path is a linked worktree of this repository (per git worktree list), not the main one and not the checkout the session runs in; it has no modified, staged or untracked files (ignored files do not count); every commit its HEAD carries is on a remote-tracking ref or the base branch, or every path those commits changed reads the same in the HEAD of the session's own checkout, so a cherry-pick under a new id counts, whatever state the job taken in it ended in; no live job was taken in it, and an exited one serves magus job wait <id>; and it is not locked, unless the session is the root and spawned that worktree's worker for a job that ended pass or fail, as its own spawn record shows. That lock is the one thing -f -f reaches past, and a plain removal of such a worktree is served the git worktree remove -f -f <path> line; a magus checkout lock never is. git worktree unlock is judged by the same conditions but the lock, since an unlocked worktree has nothing else stopping its removal. The refusal names each failed condition and the command that inspects it, and --force changes nothing else. Removal cannot be undone, so a fact that cannot be read refuses too: an unreadable job store, a line that does not parse, a path that is not a literal word, a removal inside a conditional or behind a wrapper. git worktree prune passes, since it only clears records of directories already gone, and git worktree remove --help and -h, alone on the line, print usage and pass. jj workspace forget stays refused: the jj driver cannot yet report a workspace's registration or which of its commits are published, so nothing proves a forget loses nothing.

Default and override

By default this rule takes the decision deny. A workspace sets it by name, in its root magusfile, to deny, advise or off:

magus\guard.builtins({"worktree-remove": "advise"})

A loosening takes effect once it is committed; a tightening applies at once.

Seeing it

A verdict names its rule in brackets, which is how you got here:

deny [worktree-remove]: ...

A workspace that sets this rule to advise sees advise [worktree-remove]: ... instead.

magus describe rule worktree-remove prints the same entry at a terminal, and magus describe rules lists every rule this workspace enforces.

See also

ReferencePages in this section. background-left: an agent finishing while shell commands it ran in the background are still runningA deny rule by default: it refuses an agent finishing while shell commands it ran in the background are still running, and names what to run instead. human-only: a magus run reaching a human_only target: the person is asked, a leased worker refusedA deny rule by default: it refuses a magus run reaching a human_only target: the person is asked, a leased worker refused, and names what to run instead. lease-vcs: a worker lease mutating version control, or committing outside its own branch and checkoutA deny rule by default: it refuses a worker lease mutating version control, or committing outside its own branch and checkout, and names what to run instead.
guardrulesworktree-removedeny
Last updated (29d8b3de)
Earlier changes on this page (5)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace in full.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. Magusfile in full.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Agent

A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent in full.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it. Session in full.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Conventions

Placeholders

Angle brackets mark a value you replace with your own; never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.