@r1z4x/tezgah 1.6.0 → 1.8.2

package/bin/tezgah-task

@@ -8,15 +8,39 @@
   tezgah-task status [--json]                                 the active task, then every open plan: progress, what it waits on, what can run at once
   tezgah-task review <NNN|path> <reviewer> approve|changes    record a fresh review's verdict
   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
+  tezgah-task slice reconcile [--prune]                       every open or stopped slice with its resume brief; --prune also removes landed worktrees and branches
+  tezgah-task slice resume ID                                 the native resume path, else a re-dispatch brief; marks the record resumed
+  tezgah-task slice stats [--window DAYS] [--json]            counts per status, failure class and host, and the RSI lever candidates
+  tezgah-task slice board [--parent P]                        the open sibling slices: what each owns, its worktree, branch and last commit
+  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`, `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
@@ -30,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
@@ -61,6 +94,31 @@ still HEAD and the tree is still dirty, so committing is the whole way out of it
 and the commit clears the refusal by itself; the per-file snapshots
 (bin/tezgah-rollback) are not one state to return to.
 
+`slice` keeps the slice journal (hooks/tezgah_task.py): one record per delegated
+slice under `.tezgah/slices/` of the main checkout, opened by the post-tool path
+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`, 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
+uncommitted files. `stats` flags a `class+host` signature at 3 events, or at 5%
+of a window holding 20 or more slices, and names its lever from a closed set.
+`board` lists the open slices one parent spawned - the session's own, or for a
+subagent its parent's - with the `Owns:` globs of each brief (the lease the
+gate holds siblings to), worktree, branch and last commit. `merge-plan` forecasts
+each done slice branch against `--base` (HEAD) and against the others with `git
+merge-tree`, leaves out a `merge=union` file such as CHANGELOG.md, and orders
+them with a branch touching MANIFEST or the citation baseline last, then fewest
+conflicts first; a branch merge-tree cannot forecast (git before 2.38, no shared
+history) is printed as `not judged` and the exit is 1. `review ... approve`
+is refused while a record whose id or agent is that reviewer is not done.
+
 Exit codes: 0 ok, 1 a refusal or a problem - one `FAIL <what>` line per problem,
 with nothing written - 2 misuse.
 """
@@ -68,6 +126,7 @@ import glob
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 import time
@@ -75,6 +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 project_top, say  # noqa: E402
 
 
 def repo_root(path):
@@ -84,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)
@@ -130,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):
@@ -180,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
@@ -196,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:
@@ -207,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:
@@ -331,6 +406,17 @@ def changed_lines(root, base):
     return sum(int(n) for n in re.findall(r"(\d+) (?:insertion|deletion)", stat))
 
 
+# The checks deferred out of the turn to the merge step (AGENTS.md "Checks, by
+# tier"): (the file that marks the repo has it, the command), in run order.
+MERGE_CHECKS = (
+    ("tests/impacted.py", "python3 tests/impacted.py --all"),
+    ("bin/tezgah-docs", "python3 bin/tezgah-docs --citations"),
+    ("bin/tezgah-docs", "python3 bin/tezgah-docs --clarity"),
+    ("skills/plan-add/render_table.py",
+     "python3 skills/plan-add/render_table.py --acceptance --strict"),
+)
+
+
 def verification_steps(text, path):
     """What the verification phase requires before the plan is done: the plan's
     own acceptance commands run once on the final tree, unpiped, and ONE review
@@ -349,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:")
@@ -358,8 +449,12 @@ def verification_steps(text, path):
           "no state go out as tool calls in ONE message, one suite run at a time:")
     for item in items or ["(the plan has no Acceptance items)"]:
         print("     - %s" % item)
-    if os.path.isfile(os.path.join(root, "tests", "impacted.py")):
-        print("     the one full run here is `python3 tests/impacted.py --all`")
+    # the deferred tier: never inside a turn, run once here at the merge step
+    deferred = [cmd for rel, cmd in MERGE_CHECKS
+                if os.path.isfile(os.path.join(root, rel))]
+    if deferred:
+        print("     the merge step's one run of the deferred checks: %s"
+              % ", ".join("`%s`" % c for c in deferred))
     if rounds and review_verdict(text) == "approve":
         print("  2. the review approved in round %d at %s: no further round"
               % (rounds, reviewed))
@@ -368,32 +463,35 @@ def verification_steps(text, path):
     if rounds >= REVIEW_ROUNDS:
         print("  2. the %d-round budget is spent: `tezgah-task review` refuses a "
               "third round. Fix a critical or major finding still confirmed "
-              "yourself, prove it with a test and close with `--resolved`; a "
-              "minor or suggestion one is recorded fix-later under the plan's "
-              "## State" % REVIEW_ROUNDS)
+              "yourself, prove it with a test and close with `--resolved`; fix a "
+              "minor or suggestion one now, or record it fix-later under the "
+              "plan's ## State only when it waits on a user decision (%s)"
+              % (REVIEW_ROUNDS, say()["decision"]))
         return
     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 recorded fix-later "
-              "under ## State and the verdict is `approve`")
+              "opens round 2; a minor or suggestion one is fixed in the session "
+              "without a new round, or recorded fix-later under ## State only "
+              "when it waits on a user decision (%s), and the verdict is "
+              "`approve`" % say()["decision"])
     print("  3. record its verdict: `tezgah-task review %s <reviewer> approve|changes`"
           " (records the reviewed sha);"
           " `tezgah-task close %s done` refuses without an approve" % (ident, ident))
@@ -417,8 +515,8 @@ 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())
-    path, problem = plan_path(root, args[0])
+    root = main_root(repo_root(os.getcwd()))
+    path, problem = open_plan(args[0])
     phase = None
     allow = []
     any_path = False
@@ -467,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)
@@ -506,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)
@@ -533,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
@@ -562,6 +677,117 @@ 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 = main_root(repo_root(os.getcwd()))
+    path, problem = plan_path(root, ref)
+    if problem:
+        return None, problem
+    if os.path.dirname(os.path.realpath(path)) != os.path.realpath(open_dir(root)):
+        return None, "%s is not an open plan under %s" % (path, open_dir(root))
+    return path, None
+
+
+def cmd_tick(args):
+    """Tick (or `--undo` untick) one Acceptance box: the plan's progress is the
+    session's to record, and the gate refuses a direct write to the record."""
+    undo = "--undo" in args
+    args = [a for a in args if a != "--undo"]
+    if len(args) != 2 or not args[1].isdigit():
+        return misuse("tick takes <NNN|path> <n> [--undo]")
+    path, problem = open_plan(args[0])
+    if problem:
+        return problems([problem])
+    n = int(args[1])
+    try:
+        # 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)
+    print("- [%s] %s" % (" " if undo else "x", item["text"]))
+    return 0
+
+
+NOTE_SECTIONS = {"state": "State", "next": "Next"}
+
+
+def cmd_note(args):
+    """Replace the plan's `## State` (the newest one) or `## Next` body."""
+    if len(args) != 3 or args[1] not in NOTE_SECTIONS or not args[2].strip():
+        return misuse('note takes <NNN|path> state|next "<text>"')
+    path, problem = open_plan(args[0])
+    if problem:
+        return problems([problem])
+    heading = NOTE_SECTIONS[args[1]]
+    try:
+        found = tt.set_section(path, heading, args[2])
+    except OSError as exc:
+        return problems(["cannot write %s: %s" % (path, exc)])
+    if not found:
+        return problems(["%s has no `## %s` section" % (path, heading)])
+    bad = write_fields(path, updated=today())
+    if bad:
+        return problems(bad)
+    print("%s: ## %s updated" % (path, heading))
+    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."""
@@ -575,15 +801,59 @@ def budget_spent(path, ident):
     return ("%s has spent its %d-round review budget: never a third round. Fix a "
             "critical or major finding still confirmed yourself and prove it with "
             "a test, then `tezgah-task close %s done --resolved \"<the fix and the "
-            "test that proves it>\"`; record a minor or suggestion one fix-later "
-            "under the plan's ## State; `close %s discarded` needs no review"
-            % (path, REVIEW_ROUNDS, ident, ident))
+            "test that proves it>\"`; fix a minor or suggestion one now, or record "
+            "it fix-later under the plan's ## State only when it waits on a "
+            "user decision (%s); `close %s discarded` needs no review"
+            % (path, REVIEW_ROUNDS, ident, say()["decision"], ident))
+
+
+def unfinished_review(root, reviewer, plan="", since=0):
+    """The refusal of an `approve` while a slice journal record whose id or agent
+    is `reviewer` is open, stopped or stale: a review slice that died on a
+    provider limit had its approve recorded anyway, and a NameError it would have
+    caught reached main (plan 078). A stale review is one whose end nobody saw,
+    which reads no more than a stopped one. The omp records are reconciled with
+    their transcripts first (`tt.pending`), so a review that finished reads as
+    done. A record that names the plan active when it opened counts only for
+    that `plan`; one that names none counts when it changed at or after `since`
+    (epoch seconds; the plan's checkpoint commit). A `resumed` record has handed
+    its work to the re-dispatch, whose own record is the one read. A record
+    spawned as `reviewer` under its own id (`Reviewer-<digest6>`,
+    `tt.open_slice`) counts too. Under TEZGAH_SESSION only this session's
+    records and unowned ones count, by id, agent or name alike: another
+    session's review is not this approve's. The refusal names the exact id,
+    which `slice resume` and `slice done` take from any session."""
+    from tezgah_paths import off
+    if off("slices-off"):
+        return []
+    tt.pending(root)
+    session = os.environ.get("TEZGAH_SESSION")
+
+    def named(rec):
+        return reviewer in (rec.get("id"), rec.get("agent"), rec.get("name")) and (
+            not session or rec.get("parent") in (session, "", None))
+
+    def ours(rec):
+        if rec.get("plan"):
+            return rec["plan"] == plan
+        return (_stamp(rec.get("updated")) or 0) >= since
+
+    return ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
+            "slice resume %s` and wait for that run; if the review was finished "
+            "another way, record it with `tezgah-task slice done %s` - an approve "
+            "from a review that did not finish reads nothing"
+            % (rec["id"], rec.get("status"),
+               (" (%s)" % rec["failure"]) if rec.get("failure") else "",
+               rec["id"], rec["id"])
+            for rec in tt.slices(root)
+            if rec.get("status") in ("open", "stopped", "stale")
+            and named(rec) and ours(rec)]
 
 
 def cmd_review(args):
     if len(args) != 3 or args[2] not in VERDICTS:
         return misuse("review takes <NNN|path> <reviewer> %s" % "|".join(VERDICTS))
-    path, problem = plan_path(repo_root(os.getcwd()), args[0])
+    path, problem = open_plan(args[0])
     if problem:
         return problems([problem])
     fields = tt.frontmatter(read(path))
@@ -593,7 +863,22 @@ def cmd_review(args):
     # the project's HEAD, never the private `.tezgah` repository's: the next
     # round's delta is `git diff <this>..HEAD` over the project
     root = os.path.realpath(os.path.join(os.path.dirname(path), "..", "..", ".."))
-    sha = (git_out(root, "rev-parse", "HEAD") or "")[:12]
+    if args[2] == "approve":
+        # the plan's checkpoint commit (a sha, or `pending <sha>`) dates the work
+        # this review is about; with none, every record counts
+        mark = (fields.get("checkpoint") or "").split()
+        since = (git_out(root, "log", "-1", "--format=%ct", mark[-1])
+                 if mark and mark[-1] != tt.CHECKPOINT_PENDING else None)
+        ident = fields.get("id") or os.path.basename(path).split("-")[0]
+        bad = unfinished_review(root, args[1], ident,
+                                int(since) if (since or "").isdigit() else 0)
+        if bad:
+            return problems(bad)
+    # 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()}
@@ -617,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])
@@ -625,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()}
@@ -643,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
@@ -716,18 +1064,42 @@ def _keeps(root, path, branch, bases, agents):
     return None
 
 
-def prune_worktrees(root):
+def landing_bases(root):
+    """The refs a branch's work counts as landed in, those that exist: HEAD,
+    main, master, and the remote's default branch too - a PR merged on the host
+    lands there first."""
+    return [b for b in ("HEAD", "main", "master", "origin/HEAD", "origin/main",
+                        "origin/master")
+            if git_out(root, "rev-parse", "-q", "--verify", b)]
+
+
+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 []
@@ -741,10 +1113,7 @@ def prune_worktrees(root):
                 for p in linked]
     orca = {os.path.realpath(r.get("path") or ""): r for r in rows or []
             if isinstance(r, dict)}
-    # the remote's default branch too: a PR merged on the host lands there first
-    bases = [b for b in ("HEAD", "main", "master", "origin/HEAD", "origin/main",
-                         "origin/master")
-             if git_out(root, "rev-parse", "-q", "--verify", b)]
+    bases = landing_bases(root)
     out = []
     for path in linked:
         branch = git_out(path, "symbolic-ref", "-q", "--short", "HEAD")
@@ -761,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
 
 
@@ -826,6 +1208,399 @@ def cmd_status(args):
     return 1 if bad else 0
 
 
+# ------------------------------------------------------------------ slice
+
+# The closed lever set a stats candidate is named from (the research line's
+# RSI loop): one file or mechanism per failure class, never prose.
+LEVERS = {"rate_limit": "hooks/tezgah_models.py fallback chain",
+          "quota": "hooks/tezgah_models.py fallback chain",
+          "cut_off": "per-slice deadline", "timeout": "per-slice deadline",
+          "aborted": "wip: commit cadence", "duplicate": "journal background jobs",
+          "error": "none (read the transcript)"}
+STATS_WINDOW = 14
+# A signature is a candidate at this many events, or at this share of the slices
+# in the window once the window holds STATS_SHARE_FLOOR slices: below that, one
+# event is already 5% and every stop would read as a pattern.
+STATS_EVENTS = 3
+STATS_SHARE = 0.05
+STATS_SHARE_FLOOR = 20
+
+
+def parse_options(args, valued, flags=()):
+    """(options, positionals, problem) for `args`: each `valued` option takes the
+    next argument, each flag stands alone, any other `--x` is a problem."""
+    opts, pos, i = {}, [], 0
+    while i < len(args):
+        arg = args[i]
+        if arg in valued:
+            if i + 1 >= len(args):
+                return None, None, "%s needs a value" % arg
+            opts[arg] = args[i + 1]
+            i += 2
+        elif arg in flags:
+            opts[arg] = True
+            i += 1
+        elif arg.startswith("--"):
+            return None, None, "unknown option %r" % arg
+        else:
+            pos.append(arg)
+            i += 1
+    return opts, pos, None
+
+
+def resume_text(root, rec):
+    """The way back into one record's work: the host's native path first (omp
+    `write agent://<id>` while the parent session lives, Claude `SendMessage`),
+    else a re-dispatch brief that runs on any host or model - the original brief
+    plus where the work stands (last commit, branch, uncommitted files)."""
+    sid = rec["id"]
+    lines = [tt.slice_line(rec)]
+    if rec.get("kind") == "job":
+        lines.append("  command: %s" % (rec.get("brief") or "(none recorded)"))
+        return "\n".join(lines)
+    tree = rec.get("worktree") or ""
+    cwd = rec.get("cwd") or ""
+    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)
+    native = {"omp": "`write agent://%s` (while omp session %s still runs)"
+                     % (sid, rec.get("parent") or "?"),
+              "claude": "`SendMessage` to %s" % sid if named else None}.get(rec.get("host"))
+    if native:
+        lines.append("  native: %s with: %s" % (native, resume))
+    provider = (" on another provider (`tezgah-route` names the tier; the same "
+                "account's limit would stop it again)"
+                if rec.get("failure") in ("quota", "rate_limit") else
+                " on any host or model")
+    lines.append("  %sre-dispatch%s with this brief:" % ("else " if native else "", provider))
+    lines.append(rec.get("brief") or "(no brief recorded)")
+    lines.append(resume)
+    return "\n".join(lines)
+
+
+def own_commits(root, rec):
+    """Does the record's branch carry a commit past the base it was opened on?
+    A branch still at its base is a slice that has not started, not one whose
+    work landed."""
+    base, branch = rec.get("base"), rec.get("branch")
+    if not base or not branch:
+        return False
+    count = git_out(root, "rev-list", "--count", "%s..%s" % (base, branch))
+    return bool(count) and count != "0"
+
+
+def prune_branches(root, bases):
+    """`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
+    nobody committed on is a slice not yet started) - never main, master or the
+    current branch. One line per branch it deletes or git refuses."""
+    current = git_out(root, "symbolic-ref", "-q", "--short", "HEAD")
+    held = {line[len("branch refs/heads/"):] for line in
+            (git_out(root, "worktree", "list", "--porcelain") or "").splitlines()
+            if line.startswith("branch refs/heads/")}
+    out = []
+    for row in (git_out(root, "for-each-ref", "--format=%(refname:short)\t%(upstream)",
+                        "refs/heads") or "").splitlines():
+        branch, _tab, upstream = row.partition("\t")
+        if branch in ("main", "master", current) or branch in held or upstream:
+            continue
+        log = git_out(root, "reflog", "show", "--format=%gs", "refs/heads/" + branch) or ""
+        if not any(entry.startswith(("commit:", "commit (amend):", "commit (initial):"))
+                   for entry in log.splitlines()):
+            continue
+        if not any(_landed(root, branch, b) for b in bases):
+            continue
+        out.append(drop_branch(root, branch) or "branch deleted: %s" % branch)
+    return out
+
+
+def _stamp(value):
+    """Seconds since the epoch of an ISO-8601 UTC record time, None when bad."""
+    import calendar
+    try:
+        return calendar.timegm(time.strptime(str(value), "%Y-%m-%dT%H:%M:%SZ"))
+    except ValueError:
+        return None
+
+
+def slice_stats(rows, window, now=None):
+    """Counts per status, failure class and host over the records updated in the
+    last `window` days, and the candidate signatures: `class+host`, one event per
+    record (the class it last stopped with) and `duplicate+host` per job record
+    run more than once, at STATS_EVENTS events or STATS_SHARE of the slices."""
+    from collections import Counter
+    cutoff = (time.time() if now is None else now) - window * 86400
+    picked = [r for r in rows if (_stamp(r.get("updated") or r.get("opened")) or 0) >= cutoff]
+    sigs = Counter()
+    for rec in picked:
+        host = rec.get("host") or "?"
+        if rec.get("failure") in LEVERS:
+            sigs[(rec["failure"], host)] += 1
+        if rec.get("kind") == "job" and int(rec.get("attempts") or 1) > 1:
+            sigs[("duplicate", host)] += 1
+    total = len(picked)
+    candidates = [{"signature": "%s+%s" % key, "events": n,
+                   "share": round(n / total, 3), "lever": LEVERS[key[0]]}
+                  for key, n in sorted(sigs.items(), key=lambda kv: (-kv[1], kv[0]))
+                  if n >= STATS_EVENTS
+                  or (total >= STATS_SHARE_FLOOR and n >= STATS_SHARE * total)]
+    return {"window_days": window, "slices": total,
+            "status": dict(Counter(r.get("status") or "?" for r in picked)),
+            "failure": dict(Counter(r["failure"] for r in picked if r.get("failure"))),
+            "host": dict(Counter(r.get("host") or "?" for r in picked)),
+            "candidates": candidates}
+
+
+def _counts(counter):
+    return ", ".join("%s %d" % kv for kv in sorted(counter.items())) or "none"
+
+
+# Files every slice appends to and only the integrator resolves (research
+# orchestrator-flow-audit S6, finding 8): a branch that touches one merges
+# after every branch that does not.
+HOTSPOTS = ("MANIFEST", "docs/citations-baseline.json")
+
+
+def merge_conflicts(root, ours, theirs):
+    """The files `git merge-tree` forecasts in conflict when `theirs` merges
+    into `ours`, minus the ones a `merge=union` attribute merges (CHANGELOG.md
+    here); None when git cannot answer (no such ref, git before 2.38)."""
+    try:
+        out = subprocess.run(["git", "-C", root, "merge-tree", "--write-tree",
+                              "--name-only", "--no-messages", ours, theirs],
+                             capture_output=True, text=True)
+    except OSError:
+        return None
+    if out.returncode not in (0, 1):
+        return None
+    files = sorted(set(out.stdout.split("\n\n")[0].splitlines()[1:]))
+    if not files:
+        return []
+    attrs = git_out(root, "check-attr", "merge", "--", *files) or ""
+    union = {line.rsplit(": merge: ", 1)[0] for line in attrs.splitlines()
+             if line.endswith(": merge: union")}
+    return [f for f in files if f not in union]
+
+
+def merge_plan(root, base):
+    """(lines, unjudged) for the done slices whose branch carries work `base`
+    lacks. The lines are the order to merge them: a branch touching no
+    HOTSPOTS first, then fewest forecast conflicts with `base`, then fewest
+    siblings it overlaps; each names its conflicting files and the siblings it
+    collides with. `unjudged` names each branch `git merge-tree` could not
+    forecast (git before 2.38, no shared history) instead of dropping it."""
+    branches = {}
+    for rec in tt.slices(root):
+        branch = rec.get("branch")
+        if (rec.get("status") == "done" and branch and branch not in branches
+                and own_commits(root, rec) and not _landed(root, branch, base)):
+            branches[branch] = rec
+    rows, unjudged = [], []
+    for branch, rec in branches.items():
+        mine = merge_conflicts(root, base, branch)
+        if mine is None:
+            unjudged.append("not judged: %s (slice %s): `git merge-tree --write-tree` "
+                            "could not forecast it against %s" % (branch, rec["id"], base))
+            continue
+        overlaps = {}
+        for other in branches:
+            files = merge_conflicts(root, other, branch) if other != branch else None
+            if files:
+                overlaps[other] = files
+        touched = (git_out(root, "diff", "--name-only", "%s...%s" % (base, branch))
+                   or "").splitlines()
+        hot = any(f in HOTSPOTS for f in touched)
+        rows.append(((hot, len(mine), len(overlaps), branch), rec, mine, overlaps))
+    rows.sort(key=lambda row: row[0])
+    out = []
+    for n, (key, rec, mine, overlaps) in enumerate(rows, 1):
+        line = "%d. %s (slice %s): %d conflict(s) with %s%s" % (
+            n, rec["branch"], rec["id"], len(mine), base,
+            ": " + ", ".join(mine) if mine else "")
+        for other, files in sorted(overlaps.items()):
+            line += "; overlaps %s on %s" % (other, ", ".join(files))
+        out.append(line + (" (touches a hotspot: the integrator merges it last)"
+                           if key[0] else ""))
+    return out, unjudged
+
+
+def board_parent():
+    """The parent whose slices `slice board` shows: the session in
+    TEZGAH_SESSION, or - read from a subagent - the parent that spawned it
+    (`tezgah_integrity.spawn_of`), so a slice sees its siblings; None, every
+    open slice, outside a session."""
+    session = os.environ.get("TEZGAH_SESSION")
+    if not session:
+        return None
+    try:
+        from tezgah_integrity import spawn_of
+        spawn = spawn_of(session)
+    except Exception:
+        spawn = None
+    return spawn[0] if spawn else session
+
+
+def cmd_slice(args):
+    usage = ("slice takes open|done|stop|reconcile|resume|stats|board|merge-plan "
+             "(open --id ID [--kind agent|job] [--host H] [--agent A] "
+             "[--brief TEXT|--brief-file F] [--parent P] [--cwd PATH]; done ID; stop ID "
+             "[--class C]; reconcile [--prune]; resume ID; stats [--window DAYS] "
+             "[--json]; board [--parent P]; merge-plan [--base REF])")
+    if not args:
+        return misuse(usage)
+    sub, rest = args[0], args[1:]
+    root = repo_root(os.getcwd())
+    if sub == "board":
+        opts, pos, bad = parse_options(rest, ("--parent",))
+        if bad or pos:
+            return misuse(bad or "slice board takes [--parent P] and nothing else")
+        lines = tt.board(root, opts.get("--parent") or board_parent())
+        print("\n".join(lines) if lines else "no open slice")
+        return 0
+    if sub == "merge-plan":
+        opts, pos, bad = parse_options(rest, ("--base",))
+        if bad or pos:
+            return misuse(bad or "slice merge-plan takes [--base REF] and nothing else")
+        base = opts.get("--base", "HEAD")
+        if git_out(root, "rev-parse", "-q", "--verify", base) is None:
+            return problems(["no revision %s in %s" % (base, root)])
+        lines, unjudged = merge_plan(root, base)
+        if lines or not unjudged:
+            print("\n".join(lines) if lines else "no done slice branch to merge into %s" % base)
+        for line in unjudged:
+            print(line)
+        return 1 if unjudged else 0
+    if sub == "open":
+        opts, pos, bad = parse_options(rest, ("--id", "--kind", "--host", "--agent",
+                                              "--brief", "--brief-file", "--parent",
+                                              "--cwd"))
+        if bad or pos:
+            return misuse(bad or "slice open takes options only (%r)" % pos[0])
+        if not opts.get("--id"):
+            return misuse("slice open needs --id ID")
+        if "--brief" in opts and "--brief-file" in opts:
+            return misuse("--brief and --brief-file contradict each other")
+        kind, host = opts.get("--kind", "agent"), opts.get("--host", "")
+        if kind not in tt.SLICE_KINDS:
+            return misuse("--kind is one of %s" % ", ".join(tt.SLICE_KINDS))
+        if host and host not in tt.SLICE_HOSTS:
+            return misuse("--host is one of %s" % ", ".join(tt.SLICE_HOSTS))
+        brief = opts.get("--brief", "")
+        if "--brief-file" in opts:
+            try:
+                brief = read(opts["--brief-file"])
+            except (OSError, UnicodeDecodeError) as exc:
+                return problems(["cannot read %s: %s" % (opts["--brief-file"], exc)])
+        try:
+            rec = tt.open_slice(root, opts["--id"], kind=kind, host=host,
+                                agent=opts.get("--agent", ""), brief=brief,
+                                parent=opts.get("--parent", ""),
+                                cwd=opts.get("--cwd") or os.getcwd())
+        except OSError as exc:
+            return problems(["cannot write the slice record: %s" % exc])
+        print("slice %s open (%s, attempt %d)%s" % (
+            rec["id"], rec["kind"], rec["attempts"],
+            " worktree %s on %s" % (rec["worktree"], rec["branch"] or "?")
+            if rec["worktree"] else ""))
+        return 0
+    if sub in ("done", "stop"):
+        opts, pos, bad = parse_options(rest, ("--class",) if sub == "stop" else ())
+        if bad or len(pos) != 1:
+            return misuse(bad or "slice %s takes one ID%s" % (
+                sub, " [--class C]" if sub == "stop" else ""))
+        failure = opts.get("--class", "")
+        if failure and failure not in tt.FAILURES:
+            return misuse("--class is one of %s" % ", ".join(tt.FAILURES))
+        status = "done" if sub == "done" else "stopped"
+        try:
+            found = tt.find_slice(root, pos[0], os.environ.get("TEZGAH_SESSION"))
+            rec = found and tt.close_slice(root, found["id"], status, failure)
+        except OSError as exc:
+            return problems(["cannot write the slice record: %s" % exc])
+        if not rec:
+            return problems(["no slice record %s under %s" % (pos[0], tt.slice_dir(root))])
+        print("slice %s %s%s" % (rec["id"], status,
+                                 " (%s)" % rec["failure"] if rec.get("failure") else ""))
+        return 0
+    if sub == "reconcile":
+        opts, pos, bad = parse_options(rest, (), ("--prune",))
+        if bad or pos:
+            return misuse(bad or "slice reconcile takes --prune and nothing else")
+        if opts.get("--prune"):
+            bases = landing_bases(root)
+            # read before the prune: a removed worktree takes its branch with it
+            landed = [rec for rec in tt.slices(root)
+                      if rec.get("status") != "done" and own_commits(root, rec)
+                      and any(_landed(root, rec["branch"], b) for b in bases)]
+            for line in prune_worktrees(root) + prune_branches(root, bases):
+                print(line)
+            for rec in landed:
+                tt.close_slice(root, rec["id"], "done")
+                print("slice %s done: %s landed" % (rec["id"], rec["branch"]))
+        rows = tt.pending(root)
+        if not rows:
+            print("no open or stopped slice")
+        for rec in rows:
+            print(resume_text(root, rec))
+        return 0
+    if sub == "resume":
+        if len(rest) != 1:
+            return misuse("slice resume takes one ID")
+        rec = tt.find_slice(root, rest[0], os.environ.get("TEZGAH_SESSION"))
+        if rec is None:
+            return problems(["no slice record %s under %s" % (rest[0], tt.slice_dir(root))])
+        print(resume_text(root, rec))
+        tt.close_slice(root, rec["id"], "resumed")
+        return 0
+    if sub == "stats":
+        opts, pos, bad = parse_options(rest, ("--window",), ("--json",))
+        if bad or pos:
+            return misuse(bad or "slice stats takes [--window DAYS] [--json]")
+        window = opts.get("--window", str(STATS_WINDOW))
+        if not window.isdigit() or int(window) < 1:
+            return misuse("--window takes a whole number of days")
+        stats = slice_stats(tt.slices(root), int(window))
+        if opts.get("--json"):
+            print(json.dumps(stats, indent=2, sort_keys=True))
+            return 0
+        print("slices in the last %d days: %d" % (stats["window_days"], stats["slices"]))
+        for key in ("status", "failure", "host"):
+            print("  %s: %s" % (key, _counts(stats[key])))
+        for row in stats["candidates"]:
+            print("candidate: %s - %d events (%d%% of slices) - lever: %s" % (
+                row["signature"], row["events"], round(row["share"] * 100), row["lever"]))
+        if not stats["candidates"]:
+            print("no signature at %d events or %d%% of the slices"
+                  % (STATS_EVENTS, round(STATS_SHARE * 100)))
+        return 0
+    return misuse(usage)
+
+
 def main(argv):
     if len(argv) < 2:
         print(__doc__, file=sys.stderr)
@@ -845,9 +1620,51 @@ def main(argv):
         return cmd_review(rest)
     if cmd == "close":
         return cmd_close(rest)
+    if cmd == "tick":
+        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)" % 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)