@r1z4x/tezgah 1.7.0 → 1.8.3

package/bin/tezgah-task

@@ -10,6 +10,7 @@
   tezgah-task close <NNN|path> done|discarded [--resolved TEXT] move a plan to .tezgah/plans/done, deactivate it, remove merged worktrees
   tezgah-task tick <NNN|path> <n> [--undo]                   tick (or untick) Acceptance item n, counted from 1
   tezgah-task note <NNN|path> state|next "<text>"            replace the body of `## State` (the newest one) or `## Next`
+  tezgah-task spike <NNN|path> "<answer>"                    record the spike's answer (`spike_recorded:`)
   tezgah-task slice open --id ID [--kind agent|job] [--host H] [--agent A] [--brief TEXT|--brief-file F] [--parent P] [--cwd PATH]
                                                               record a delegated slice (a re-open counts one more attempt)
   tezgah-task slice done ID | slice stop ID [--class C]      close a slice record
@@ -20,16 +21,26 @@
   tezgah-task slice merge-plan [--base REF]                   the done slice branches in merge order, with their forecast conflicts
 
 The record is the plan file itself: `phase:` activates it, `allowed_paths:` is
-the scope a write has to stay inside, and at most one open plan carries a phase
-because `start` clears the others. The orchestrating session runs every command
+the scope a write has to stay inside, and `start` clears every other plan's
+phase - except, when the plan being started is held by a linked worktree on
+one of its `plan/NNN-...` branches (its declared `branch:` or a slice's),
+another plan held the same way
+whose allowlist shares no prefix with it: that plan keeps its phase, the gate
+holds a write in each worktree to that worktree's plan
+(`tezgah_task.branch_task`), and the main checkout reads the first phased plan
+no worktree holds, or no task when every one is held. `phase`, `allow` and `stop` run inside such a worktree act on
+its plan, and `allow` refuses a scope a held plan's allowlist could share; the
+body writers below and `close` run from any worktree too. The orchestrating
+session runs every command
 here itself as the work moves - the lifecycle is never handed back to the user -
 and this CLI is the record's only writer: the gate refuses a write to the plan
 file, because the checks below are made here and a retyped frontmatter would
 skip them. `phase implementation` (or `verification`) is what lets a write
 through, so the phase changes when the work reaches that point and not before.
-`tick` and `note` are the record's body writers for the same reason: they write
-an Acceptance box or the State/Next text on any open plan, active or not, keep
-the frontmatter but `updated:`, and commit nothing.
+`tick`, `note` and `spike` are the record's body writers for the same reason:
+they write an Acceptance box, the State/Next text or the spike's answer on any
+open plan, active or not, keep the rest of the frontmatter but `updated:`, and
+commit nothing.
 
 The allowlist is the plan's own: plan-add writes `allowed_paths:` when it
 creates the plan, and `start` without `--allow` keeps it. A writing phase with
@@ -43,7 +54,16 @@ project's HEAD it read) and `review_round:`, so the next round reads only
 `git diff <reviewed_sha>..HEAD`, and refuses a third round: the budget is two
 rounds per plan; `close NNN done` refuses a plan whose review is missing or not
 `approve`, unless both rounds are spent and `--resolved` records the fix the
-session made and the test that proves it. `close` on the active task clears its phase in the same write, then
+session made and the test that proves it. `close NNN done` also refuses, naming
+each by number, an unticked Acceptance item that carries no `UNMET: <reason>`
+(an item the owner accepted as not met); `--resolved` never lifts that, and
+`discarded` is not held to it. `close` on the active task clears its phase in the same write;
+`close NNN done` records `landed:`, the main checkout's HEAD, which a squash
+merge and a branch deletion cannot orphan the way they do `reviewed_sha:` -
+once the reviewed commit has landed there, else it warns and records none. The
+record moves to `done/` under the plans lock every record writer holds, and
+when `.tezgah` is a git repository of its own the move - those two paths and
+nothing else - is committed there as `plan: close NNN <slug>`. Then `close`
 removes each linked worktree whose branch has landed in HEAD, `main`, `master`
 or the remote's default branch (an ancestor of it, or a squash whose merge
 would change nothing) and which holds nothing else (no uncommitted or unknown
@@ -80,9 +100,10 @@ on a spawn call or by `slice open`, so a parent crash, an omp `/clear`, a quota
 stop or a model or host switch loses no slice. `reconcile` reads each open omp
 record's child transcript and closes the ones that ended, then prints one
 resume brief per open or stopped slice; `--prune` first runs the same worktree
-removal `close` does, deletes (`git branch -d`) every local branch that has
-landed and is checked out nowhere - never main, master or the current branch -
-and marks done each record whose branch landed with a commit of its own.
+removal `close` does, deletes (`git branch -D`, a squash merge counts) every
+local branch that has landed and is checked out nowhere - never main, master
+or the current branch - and marks done each record whose branch landed with a
+commit of its own.
 `resume` prints the host's native path first (omp `write agent://<id>` while
 the parent session lives, Claude `SendMessage`), then a brief any host or model
 can re-dispatch: the original brief plus the last commit, the branch and the
@@ -105,6 +126,7 @@ import glob
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 import time
@@ -112,7 +134,7 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_task as tt  # noqa: E402
-from tezgah_paths import say  # noqa: E402
+from tezgah_paths import project_top, say  # noqa: E402
 
 
 def repo_root(path):
@@ -122,7 +144,7 @@ def repo_root(path):
         out = subprocess.run(["git", "-C", path, "rev-parse", "--show-toplevel"],
                              capture_output=True, text=True)
         if out.returncode == 0 and out.stdout.strip():
-            return out.stdout.strip()
+            return project_top(out.stdout.strip())
     except OSError:
         pass
     return os.path.realpath(path)
@@ -168,9 +190,12 @@ def plan_path(root, ref):
 
 
 def active_here(root):
-    """The active task as every reader sees it - resolved by the module, so the
-    CLI and the gate cannot disagree about which plan is active."""
-    return tt.active(root, root)
+    """The active task, resolved by the module, so the CLI and the gate cannot
+    disagree about which plan is active. When every phased plan is held by its
+    worktree the gate holds the main checkout to none, and the CLI acts on the
+    first held one (`held`): the orchestrating session moves a held plan's
+    phase from the main checkout."""
+    return tt.active(root, root, held=True)
 
 
 def problems(items):
@@ -218,6 +243,15 @@ def allow_source(text):
     return allow, "any path in the repo (no allowlist)"
 
 
+def holder_of(path):
+    """The linked worktree holding the plan at `path` (`tt.plan_holders`: on the
+    plan's own branch), else None - the checkout its work, checkpoint and diff
+    live in."""
+    root = os.path.realpath(os.path.join(os.path.dirname(path), "..", "..", ".."))
+    return tt.plan_holders(root).get(
+        tt._plan_id(tt.frontmatter(read(path)), os.path.basename(path)))
+
+
 def checkpoint_state(value, path):
     """The checkpoint line `show` prints for a plan in `implementation`: the sha
     the work returns to, or the commit the phase waits for - named with the sha it
@@ -234,7 +268,10 @@ def checkpoint_state(value, path):
     state the phase is in."""
     sha = tt.checkpoint_sha(value)
     if sha:
-        root = repo_root(os.path.dirname(path) or ".")
+        # a plan held by its own worktree waits on that checkout's commit, the
+        # one the gate reads (tezgah_gate.checkpoint_reason)
+        holder = holder_of(path)
+        root = holder or repo_root(os.path.dirname(path) or ".")
         head = git_out(root, "rev-parse", "HEAD")
         listed = git_out(root, "status", "--porcelain")
         if not head or head != sha or not listed:
@@ -245,7 +282,7 @@ def checkpoint_state(value, path):
             print("  checkpoint: pending on %s - the tree held uncommitted changes "
                   "when the phase began, so this phase's writes are refused until "
                   "the commit that moves HEAD off it: %s"
-                  % (sha, tt.checkpoint_command(path)))
+                  % (sha, tt.checkpoint_command(path, holder)))
     elif value:
         print("  checkpoint: %s" % value)
     else:
@@ -373,7 +410,6 @@ def changed_lines(root, base):
 # tier"): (the file that marks the repo has it, the command), in run order.
 MERGE_CHECKS = (
     ("tests/impacted.py", "python3 tests/impacted.py --all"),
-    ("tests/neuter_matrix.py", "TEZGAH_E2E_STRICT=1 python3 tests/neuter_matrix.py"),
     ("bin/tezgah-docs", "python3 bin/tezgah-docs --citations"),
     ("bin/tezgah-docs", "python3 bin/tezgah-docs --clarity"),
     ("skills/plan-add/render_table.py",
@@ -399,6 +435,11 @@ def verification_steps(text, path):
     # the project, not the private repository `.tezgah` may hold
     root = os.path.realpath(os.path.join(os.path.dirname(path), "..", "..", ".."))
     reviewed = fields.get("reviewed_sha") or "(no commit)"
+    # a plan held by its own worktree is built on that branch: the review reads
+    # that checkout's diff
+    holder = holder_of(path)
+    where = holder or root
+    diff = "git -C %s diff" % shlex.quote(holder) if holder else "git diff"
     prior = fields.get("review_round") or ""
     rounds = int(prior) if prior.isdigit() else 0
     print("verification - required before this plan is done:")
@@ -430,21 +471,21 @@ def verification_steps(text, path):
     if rounds:
         print("  2. review round 2 (the last): each confirmed critical or major "
               "finding is fixed with a regression test that failed first; one "
-              "fresh tezgah-reviewer reads only the delta `git diff %s..HEAD`, the "
+              "fresh tezgah-reviewer reads only the delta `%s %s..HEAD`, the "
               "round-1 hunks and direct callers of the symbols it touches, and the "
               "test output above, and marks every round-1 finding closed or open; "
-              "it does not re-run the suite" % reviewed)
+              "it does not re-run the suite" % (diff, reviewed))
     else:
-        base = diff_base(root)
-        size = changed_lines(root, base)
+        base = diff_base(where)
+        size = changed_lines(where, base)
         print("  2. one review of the whole plan, at most %d rounds: spawn fresh "
               "tezgah-reviewer subagents in ONE message, each owning one dimension "
               "- correctness and contract, security, tests and performance - or one "
-              "file group of a large diff, over `git diff %s..HEAD` and the test "
+              "file group of a large diff, over `%s %s..HEAD` and the test "
               "output above, then merge their findings into one verdict. Under %d "
               "changed lines one reviewer reads every dimension (this diff: %s), "
               "unless the diff touches auth, secrets or a gate, which keeps a "
-              "security reviewer" % (REVIEW_ROUNDS, base, SMALL_DIFF,
+              "security reviewer" % (REVIEW_ROUNDS, diff, base, SMALL_DIFF,
                                      "unknown" if size is None else size))
         print("     only a confirmed critical or major finding is `changes` and "
               "opens round 2; a minor or suggestion one is fixed in the session "
@@ -474,7 +515,7 @@ def scope_problem(phase, allow, any_path):
 def cmd_start(args):
     if not args:
         return misuse("start needs a plan id or path")
-    root = repo_root(os.getcwd())
+    root = main_root(repo_root(os.getcwd()))
     path, problem = open_plan(args[0])
     phase = None
     allow = []
@@ -524,14 +565,25 @@ def cmd_start(args):
            or phase_problems(phase, text, path))
     if bad:
         return problems(bad)
-    fields.update(checkpoint_fields(root, phase))
+    holders = tt.plan_holders(root)
+    # the plan's own worktree, when one holds it: the gate reads the checkpoint
+    # against that checkout's HEAD and tree, so it is recorded from there
+    here = holders.get(tt._plan_id(tt.frontmatter(text), os.path.basename(path)))
+    fields.update(checkpoint_fields(here or root, phase))
     for other in plans(root):
         if other == path:
             continue
-        if tt.frontmatter(read(other)).get("phase"):
-            # one active task at a time: the plan that had the phase loses it
-            # here rather than both being active and the gate reading whichever
-            # sorts first
+        theirs = read(other)
+        front = tt.frontmatter(theirs)
+        if front.get("phase"):
+            if (here and tt._plan_id(front, os.path.basename(other)) in holders
+                    and not tt.scopes_overlap(tt.allowed_paths(theirs), allow)):
+                # both plans run in their own worktrees, on scopes that share no
+                # prefix: the other keeps its phase and the two run at once
+                continue
+            # otherwise one active task at a time: the plan that had the phase
+            # loses it here rather than both being active and the gate reading
+            # whichever sorts first
             bad = write_fields(other, phase="", updated=today())
             if bad:
                 return problems(bad)
@@ -563,10 +615,12 @@ def cmd_phase(args):
     granted = (any_path or tt.frontmatter(text).get("allowed_from")
                == ANY_PATH)
     bad = (scope_problem(phase, task["allowed_paths"], granted)
-           or phase_problems(phase, text, task["path"]))
+           or phase_problems(phase, text, task["path"])
+           or (held_overlap(root, task["id"], []) if any_path else []))
     if bad:
         return problems(bad)
-    fields.update(checkpoint_fields(root, phase))
+    where = task.get("worktree") or tt.plan_holders(main_root(root)).get(task["id"])
+    fields.update(checkpoint_fields(where or root, phase))
     bad = write_fields(task["path"], **fields)
     if bad:
         return problems(bad)
@@ -590,10 +644,14 @@ def cmd_allow(args):
         return misuse("allow takes globs, or --any-path alone to lift the scope")
     if not why:
         return misuse("allow takes --why \"<what in the plan reaches these paths>\"")
-    task = active_here(repo_root(os.getcwd()))
+    root = repo_root(os.getcwd())
+    task = active_here(root)
     if not task:
         return problems(["no active task to widen: start one with "
                          "`tezgah-task start <id> --phase P --allow GLOB`"])
+    bad = held_overlap(root, task["id"], args)
+    if bad:
+        return problems(bad)
     # --any-path replaces the list with an empty one, which reads as "any path in
     # the repo" - and the gate skips the scope check entirely then, so this is
     # the way back out of a scope that turned out to be too narrow. A flag and
@@ -619,11 +677,42 @@ def cmd_stop(args):
     return show(task["path"])
 
 
+def main_root(root):
+    """The main checkout of the repository `root` is a checkout of: the one that
+    keeps `.tezgah/plans`, so a command run in a plan's worktree finds them."""
+    from tezgah_paths import linked_main
+    return linked_main(root) or root
+
+
+def held_overlap(root, ident, scope):
+    """A problem line per phased plan other than `ident` that a linked worktree
+    holds and whose allowlist `scope` could share a file with: two plans running
+    at once are kept to disjoint scopes, which `start` checked and a widening
+    here must not undo. An empty `scope` is any path, so it meets every one."""
+    main = main_root(root)
+    holders = tt.plan_holders(main)
+    out = []
+    for other in plans(main):
+        text = read(other)
+        front = tt.frontmatter(text)
+        oid = tt._plan_id(front, os.path.basename(other))
+        if oid == ident or oid not in holders or front.get("phase") not in tt.TASK_PHASES:
+            continue
+        theirs = tt.allowed_paths(text)
+        if tt.scopes_overlap(theirs, scope):
+            out.append("scope %s overlaps plan %s's (%s), which runs at once in "
+                       "worktree %s: plans running side by side share no path "
+                       "prefix. Narrow the scope, or stop plan %s first"
+                       % (" ".join(scope) or "any path", oid,
+                          ", ".join(theirs) or "any path", holders[oid], oid))
+    return out
+
+
 def open_plan(ref):
     """(path, problem) for a plan under `.tezgah/plans/open/`: `tick` and `note`
     write past the gate, so they take no other file (review of plan 083, F4:
     `note README.md next ...` rewrote any markdown file with a Next section)."""
-    root = repo_root(os.getcwd())
+    root = main_root(repo_root(os.getcwd()))
     path, problem = plan_path(root, ref)
     if problem:
         return None, problem
@@ -642,16 +731,15 @@ def cmd_tick(args):
     path, problem = open_plan(args[0])
     if problem:
         return problems([problem])
-    items = tt.acceptance_items(read(path))
     n = int(args[1])
-    if not 1 <= n <= len(items):
-        return problems(["%s has %d Acceptance items, not an item %d"
-                         % (path, len(items), n)])
-    item = items[n - 1]
     try:
-        tt.set_box(path, item["line"], not undo)
+        # the item's line is found under the lock, where no writer can move it
+        item = tt.set_box(path, n, not undo)
     except OSError as exc:
         return problems(["cannot write %s: %s" % (path, exc)])
+    if item is None:
+        return problems(["%s has %d Acceptance items, not an item %d"
+                         % (path, len(tt.acceptance_items(read(path))), n)])
     bad = write_fields(path, updated=today())
     if bad:
         return problems(bad)
@@ -683,6 +771,23 @@ def cmd_note(args):
     return 0
 
 
+def cmd_spike(args):
+    """Record the spike's answer (`spike_recorded:`) on an open plan, active or
+    not: the gate refuses a direct write to the record, and `phase
+    implementation` refuses while the answer is missing (phase_problems)."""
+    answer = " ".join(args[1].split()) if len(args) == 2 else ""
+    if not answer:
+        return misuse('spike takes <NNN|path> "<answer: what the spike found, and where>"')
+    path, problem = open_plan(args[0])
+    if problem:
+        return problems([problem])
+    bad = write_fields(path, spike_recorded=answer, updated=today())
+    if bad:
+        return problems(bad)
+    print("%s: spike_recorded: %s" % (path, answer))
+    return 0
+
+
 def review_verdict(text):
     """The verdict of the plan's `review: <reviewer> <verdict> <date>` line, or
     None when it has none or names a verdict this CLI does not write."""
@@ -769,7 +874,11 @@ def cmd_review(args):
                                 int(since) if (since or "").isdigit() else 0)
         if bad:
             return problems(bad)
-    sha = (git_out(root, "rev-parse", "HEAD") or "")[:12]
+    # a plan held by its own worktree is built on that branch: its HEAD is the
+    # one the next round's diff starts from
+    ident = fields.get("id") or os.path.basename(path).split("-")[0]
+    where = tt.plan_holders(root).get(ident) or root
+    sha = (git_out(where, "rev-parse", "HEAD") or "")[:12]
     record = {"review": "%s %s %s" % (args[1], args[2], today()),
               "review_round": str(int(prior) + 1 if prior.isdigit() else 1),
               "updated": today()}
@@ -793,7 +902,7 @@ def cmd_close(args):
             return misuse("--resolved takes the fix and the test that proves it")
     if len(args) != 2 or args[1] not in ("done", "discarded"):
         return misuse("close takes <NNN|path> done|discarded [--resolved TEXT]")
-    root = repo_root(os.getcwd())
+    root = main_root(repo_root(os.getcwd()))
     path, problem = plan_path(root, args[0])
     if problem:
         return problems([problem])
@@ -801,6 +910,14 @@ def cmd_close(args):
         return problems(["%s is not under %s" % (path, open_dir(root))])
     text = read(path)
     ident = os.path.basename(path).split("-")[0]
+    unticked = tt.open_items(text) if args[1] == "done" else []
+    if unticked:
+        # a review (or --resolved) answers the diff, never the plan's own boxes
+        return problems(["%s item %d: %s" % (path, n, item["text"]) for n, item in unticked] + [
+            "%s has %d open Acceptance item(s): tick each one met with `tezgah-task "
+            "tick %s %d`, end an item the owner accepted as not met with `UNMET: "
+            "<reason, who accepted it>`, or `tezgah-task close %s discarded`"
+            % (path, len(unticked), ident, unticked[0][0], ident)])
     # closing the active task deactivates it in the same write: the plan leaves
     # open/ anyway, and a separate `stop` first was one more step for nobody
     fields = {"status": args[1], "updated": today()}
@@ -819,19 +936,74 @@ def cmd_close(args):
             return problems(["%s records no approving review: a fresh reviewer reads "
                              "the diff, then `tezgah-task review %s <reviewer> approve`"
                              % (path, ident)])
+    landed = landed_head(root, text, path) if args[1] == "done" else None
+    if landed:
+        fields["landed"] = landed
+    elif args[1] == "done":
+        print("warning: %s's reviewed work is not in %s's HEAD yet, so no `landed:` "
+              "recorded" % (ident, root))
     target = os.path.join(root, ".tezgah", "plans", "done", os.path.basename(path))
-    bad = write_fields(path, **fields)
-    if bad:
-        return problems(bad)
     try:
-        os.makedirs(os.path.dirname(target), exist_ok=True)
-        os.replace(path, target)
+        tt.close_record(path, target, **fields)
     except OSError as exc:
-        return problems(["cannot move %s: %s" % (path, exc)])
+        return problems(["cannot close %s: %s" % (path, exc)])
     print("moved %s -> %s" % (path, target))
-    for line in prune_worktrees(root):
+    name = tt.slug(path)
+    line, committed = commit_close(root, os.path.basename(path), "plan: close %s %s"
+                                   % (ident, name.partition("-")[2] or name))
+    if line:
         print(line)
-    return 0
+    # the checkout this runs in stays, even when it is a landed plan worktree:
+    # removing it would pull the session's own cwd from under it
+    for line in prune_worktrees(root, keep=repo_root(os.getcwd())):
+        print(line)
+    return 0 if committed else 1
+
+
+def landed_head(root, text, path):
+    """The main checkout's HEAD when the plan's work is in it, else None.
+    reviewed_sha names a worktree HEAD that a squash merge and a branch
+    deletion leave in no branch, so `landed` names the commit the work is in.
+    It is recorded only when the reviewed commit - else the plan's declared
+    `branch:`, else `plan/<slug>` - has landed there (`_landed`: an ancestor,
+    or a squash whose merge changes nothing). A `close done` before the merge
+    would name a commit without the work (review of plan 097, F7)."""
+    front = tt.frontmatter(text)
+    for ref in (front.get("reviewed_sha"), front.get("branch"), "plan/" + tt.slug(path)):
+        if ref and git_out(root, "rev-parse", "-q", "--verify", ref + "^{commit}"):
+            return git_out(root, "rev-parse", "HEAD") if _landed(root, ref, "HEAD") else None
+    return None
+
+
+def commit_close(root, name, message):
+    """Commit the closed record's move - `plans/open/<name>` to
+    `plans/done/<name>`, and nothing else the owner staged - in the private
+    `.tezgah` repository: (the line to print, committed). No line and True when
+    `.tezgah` is no repository of its own, where git would answer for the
+    project around it. A failed commit - a lock `ws_git` waited out in vain -
+    is False, so close exits 1: the record has moved, its commit is owed."""
+    from tezgah_paths import ws_git
+    ws = os.path.realpath(os.path.join(root, ".tezgah"))
+    top = git_out(ws, "rev-parse", "--show-toplevel")
+    if not top or os.path.realpath(top) != ws:
+        return None, True
+    paths = ["plans/done/" + name]
+    if git_out(ws, "ls-files", "--", "plans/open/" + name):
+        paths.insert(0, "plans/open/" + name)
+    try:
+        done = ws_git(root, "add", "--", paths[-1])
+        if not done.returncode:
+            done = ws_git(root, "commit", "-q", "-m", message, "--", *paths)
+        error = ((done.stderr or done.stdout).strip() or "git exited %d" % done.returncode
+                 if done.returncode else "")
+    except OSError as exc:
+        error = str(exc)
+    if error:
+        return ("close not committed in %s: %s\n  the record moved; commit it with "
+                "`git -C %s add -- %s && git -C %s commit -m %r -- %s`"
+                % (ws, error, ws, paths[-1], ws, message, " ".join(paths)), False)
+    return ("committed %s in %s at %s" % (" ".join(paths), ws, git_out(
+        ws, "rev-parse", "--short=12", "HEAD")), True)
 
 
 # Ignored output a slice regenerates on its own. Any other ignored path - an
@@ -901,18 +1073,33 @@ def landing_bases(root):
             if git_out(root, "rev-parse", "-q", "--verify", b)]
 
 
-def prune_worktrees(root):
+def drop_branch(root, branch):
+    """`git branch -D` a branch `_landed` proved is in a landing base - `-d`
+    refuses a squash- or rebase-merged one, whose commits are in no base. None
+    once it is gone, else the line saying it stays and why."""
+    if not git_out(root, "rev-parse", "-q", "--verify", "refs/heads/" + branch):
+        return None
+    done = subprocess.run(["git", "-C", root, "branch", "-D", branch],
+                          capture_output=True, text=True)
+    if done.returncode == 0:
+        return None
+    return ("branch kept: %s (`git branch -D %s` refused: %s)"
+            % (branch, branch, ((done.stderr or "").strip().splitlines() or ["?"])[0]))
+
+
+def prune_worktrees(root, keep=None):
     """Remove every linked worktree of the repository whose branch has landed and
     which holds nothing else, so a closed plan leaves no checkout behind; one line
     per linked worktree, removed or kept with the reason. The main checkout and
-    the one `close` runs in always stay. Under Orca the removal is Orca's (its
-    card, terminals and merged branch go with it), else `git worktree remove`
-    and a safe `git branch -d`. When Orca is installed but does not answer, its
-    agents cannot be checked, so every worktree stays."""
+    the one `close` runs in (`keep`, else `root`) always stay. Under Orca the
+    removal is Orca's (its card, terminals and merged branch go with it), else
+    `git worktree remove`; the landed branch is then deleted (`drop_branch`), a
+    refusal printed. When Orca is installed but does not answer, its agents
+    cannot be checked, so every worktree stays."""
     import tezgah_orca
     from tezgah_paths import worktrees
     found = worktrees(root)
-    here = os.path.realpath(root)
+    here = os.path.realpath(keep or root)
     linked = [p for p in found[1:] if p != here]
     if not linked:
         return []
@@ -943,11 +1130,24 @@ def prune_worktrees(root):
             else:
                 gone = git_out(root, "worktree", "remove", path) is not None
                 how = "git worktree remove %s" % path
-                if gone:
-                    git_out(root, "branch", "-d", branch)
             why = None if gone else "`%s` failed; run it and report its error" % how
         out.append("worktree %s: %s (%s)" % ("kept" if why else "removed", path,
                                              why or branch))
+        if why is None:
+            # Orca removes the checkout but git may still list it, and git
+            # refuses to delete a branch a listed worktree holds
+            git_out(root, "worktree", "prune")
+            # _keeps answered None, so the branch landed: a squash merge too
+            kept = drop_branch(root, branch)
+            if kept:
+                out.append(kept)
+            # its work landed and the checkout is gone: a record still open on it
+            # would be offered for resume in a worktree that no longer exists
+            for rec in tt.slices(root):
+                if rec.get("worktree") == path and rec.get("status") in ("open", "stopped", "stale"):
+                    tt.close_slice(root, rec["id"], "done")
+                    out.append("slice %s done: worktree %s removed, %s landed"
+                               % (rec["id"], path, branch))
     return out
 
 
@@ -1060,16 +1260,28 @@ def resume_text(root, rec):
         return "\n".join(lines)
     tree = rec.get("worktree") or ""
     cwd = rec.get("cwd") or ""
-    where = (tree if tree and os.path.isdir(tree) else
-             cwd if cwd and os.path.isdir(cwd) else root)
-    last = git_out(where, "log", "-1", "--format=%h %s") or "(none)"
-    branch = (rec.get("branch") or git_out(where, "symbolic-ref", "-q", "--short", "HEAD")
-              or "(detached HEAD)")
-    # the journal's own directory is not the slice's work, ignored or not
-    dirty = [line[3:] for line in (git_out(where, "status", "--porcelain") or "").splitlines()
-             if not line[3:].startswith(".tezgah")]
-    resume = ("Resume: last commit %s on %s; uncommitted: %s; continue from there, "
-              "do not redo committed steps" % (last, branch, ", ".join(dirty) or "none"))
+    if tree and not os.path.isdir(tree):
+        # the checkout was removed: the main checkout's HEAD is not the slice's
+        # last commit, so say what is known instead of naming the wrong one
+        branch = rec.get("branch") or ""
+        sha = git_out(root, "rev-parse", "-q", "--short", "--verify",
+                      "refs/heads/" + branch) if branch else None
+        resume = ("Resume: worktree %s no longer exists; branch %s %s. If its work "
+                  "landed, close this record with `tezgah-task slice done %s`; else "
+                  "re-dispatch in a new worktree%s"
+                  % (tree, branch or "(none recorded)",
+                     "is at %s" % sha if sha else "no longer exists", sid,
+                     " from %s" % branch if sha else ""))
+    else:
+        where = cwd if not tree and cwd and os.path.isdir(cwd) else tree or root
+        last = git_out(where, "log", "-1", "--format=%h %s") or "(none)"
+        branch = (rec.get("branch") or git_out(where, "symbolic-ref", "-q", "--short", "HEAD")
+                  or "(detached HEAD)")
+        # the journal's own directory is not the slice's work, ignored or not
+        dirty = [line[3:] for line in (git_out(where, "status", "--porcelain") or "").splitlines()
+                 if not line[3:].startswith(".tezgah")]
+        resume = ("Resume: last commit %s on %s; uncommitted: %s; continue from there, "
+                  "do not redo committed steps" % (last, branch, ", ".join(dirty) or "none"))
     # a Claude record named by a 12-hex brief digest addresses no agent: no
     # SendMessage line for it, only the re-dispatch
     named = not re.fullmatch(r"[0-9a-f]{12}", sid)
@@ -1100,7 +1312,8 @@ def own_commits(root, rec):
 
 
 def prune_branches(root, bases):
-    """`git branch -d` every local branch whose work landed in `bases`, that no
+    """`git branch -D` every local branch whose work landed in `bases` (`_landed`,
+    a squash merge too), that no
     worktree has checked out, that tracks no upstream (a long-lived branch such
     as `develop` tracks one) and that carries a commit of its own (its reflog
     names one, the guard `_keeps` applies to a worktree: a pre-created branch
@@ -1122,11 +1335,7 @@ def prune_branches(root, bases):
             continue
         if not any(_landed(root, branch, b) for b in bases):
             continue
-        done = subprocess.run(["git", "-C", root, "branch", "-d", branch],
-                              capture_output=True, text=True)
-        out.append("branch deleted: %s" % branch if done.returncode == 0 else
-                   "branch kept: %s (`git branch -d %s` refused: %s)"
-                   % (branch, branch, (done.stderr.strip().splitlines() or ["?"])[0]))
+        out.append(drop_branch(root, branch) or "branch deleted: %s" % branch)
     return out
 
 
@@ -1415,11 +1624,47 @@ def main(argv):
         return cmd_tick(rest)
     if cmd == "note":
         return cmd_note(rest)
+    if cmd == "spike":
+        return cmd_spike(rest)
     if cmd == "slice":
         return cmd_slice(rest)
     return misuse("unknown command %r (start, phase, allow, stop, status, review, "
-                  "close, tick, note, slice)" % cmd)
+                  "close, tick, note, spike, slice)" % cmd)
+
+
+class ReaderMayLeave:
+    """sys.stdout for a reader that may leave early (`tezgah-task stop | head
+    -1`): a write or flush that meets the closed pipe points fd 1 at devnull
+    and carries on, so main always finishes its work and returns its own code,
+    buffered or not (PYTHONUNBUFFERED=1 meets the pipe at every print). A
+    wrapper rather than SIGPIPE's default, which kills the process by signal
+    (status 141) mid-write."""
+
+    def __init__(self, stream):
+        self._stream = stream
+
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+    def _gone(self):
+        os.dup2(os.open(os.devnull, os.O_WRONLY), self._stream.fileno())
+
+    def write(self, text):
+        try:
+            return self._stream.write(text)
+        except BrokenPipeError:
+            self._gone()
+            return len(text)
+
+    def flush(self):
+        try:
+            self._stream.flush()
+        except BrokenPipeError:
+            self._gone()
 
 
 if __name__ == "__main__":
-    sys.exit(main(sys.argv))
+    sys.stdout = ReaderMayLeave(sys.stdout)
+    code = main(sys.argv)
+    sys.stdout.flush()  # here, not in the interpreter's exit flush, which would print the EPIPE
+    sys.exit(code)