opencode-thrum-pro 0.1.0

package/assets/skills/coordinator-assessing-agent-completion/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: coordinator-assessing-agent-completion
+description: "Use when deciding which live agents are FINISHED and can be stood down - finding obsolete agents, idle agents, agents nobody is waiting on, agents still running after their work landed, reaping candidates, tidying up the fleet, 'who can I shut down', 'which agents are done', auditing a box before a deploy or restart - AND when reducing the worktree count or reaping/freeing worktrees to relieve load (too many worktrees, the identity or collision scan timing out, tmux create or launches failing, 'reduce the worktree count', 'reap dead worktrees'), because a worktree is an agent's home and reaping one is an agent-lifecycle decision, never disk cleanup. Produces a candidate list from the transcript plus a DIRECT-OBSERVATION liveness check (live tmux pane / ppid, not a snapshot-presence proxy), never a kill list."
+---
+
+# Assessing Whether an Agent Is Finished — and Whether a Worktree Is Safe to Reap
+
+`thrum tmux connect` tells you which agents are **alive**. Nothing tells you which
+are **alive but done**. This is that second question.
+
+**This produces INFORMATION. You make the judgment call.**
+
+The scan ranks and quotes; it does not conclude. It has no flag that reaps,
+kills, or changes a phase, and it must not grow one — a script that recommends
+standing an agent down is read as having decided, and its phrasing then carries
+weight its evidence does not.
+
+Apply the gate and containment checks below and reach your own
+conclusion. Destructive steps still follow the standing reap preconditions and
+pacing rules; nothing here shortcuts them.
+
+## The instruments, in order of trust
+
+| Question | Instrument |
+|---|---|
+| Is it alive? | `thrum tmux connect < /dev/null` · `tmux list-sessions` |
+| What did it last say? | its transcript JSONL — **the primary signal** |
+| How long has it been quiet? | transcript mtime — **weak, see below** |
+| What is it waiting for? | its own last message, read as prose |
+
+**Do NOT use `thrum team`, `thrum agent list`, `phase`, or `last_seen_at` for any
+of this.** They are stale, and they fail toward
+reporting a live agent as absent.
+
+## Locating an agent's transcript
+
+The project directory is the agent's worktree path with `/` and `.` replaced by `-`:
+
+```
+/Users/<you>/.thrum/worktrees/thrum/<session>
+  -> ~/.claude/projects/-Users-<you>--thrum-worktrees-thrum-<session>/*.jsonl
+```
+
+Newest `.jsonl` by mtime is the live session. Records carry `timestamp`, `type`,
+and `message.content`.
+
+## The scan
+
+```bash
+thrum tmux connect < /dev/null | awk 'NR>1 && $1 ~ /^[0-9]+$/ {print $2"|"$3}'
+```
+gives `session|@agent` for every alive agent. For each, open the newest transcript
+and take the last record of `type == "assistant"` with a non-empty text block.
+That text is the signal.
+
+## Reading the signal
+
+**Terminal-state language** — the agent declaring it holds nothing:
+
+> *standing by* · *standing down* · *task done* · *idle* · *no further action* ·
+> *completion report sent* · *held pending X* · *inbox clear, nothing to act on*
+
+**Not terminal**: a question to another agent, a partial result, a stated next
+step, an error it has not resolved.
+
+## ⚠️ Two false positives the phrase match produces, both measured
+
+The scan is a **pre-filter**. It matches anywhere in the last message, which
+catches two agents that are not finished:
+
+1. **A long active report that happens to contain a terminal phrase mid-text.**
+   The agent is mid-work; the phrase is describing something else.
+2. **A freshly-primed agent.** *"Inbox empty; standing by"* is part of its prime,
+   not a completion. Check its session start — minutes old means it just woke.
+
+⇒ **Read the END of the message, not a keyword hit.** A finished agent's last
+sentence IS the terminal statement; a working agent's merely contains one.
+
+## 🔴 THE GATE — an agent saying it is finished is not evidence that it is
+
+**Name what it is waiting for, then prove that thing is dead or landed.**
+
+*"Held pending the coordinator merge"* is finished only if the merge landed or was
+abandoned. If the merge is still queued, the agent is **correctly** waiting and
+reaping it destroys live context that nobody else holds.
+
+**If you cannot name the blocker, it is not a candidate.**
+
+## Containment, before anything is stood down
+
+- branch pushed, or no commits to lose
+- no only-copy untracked state: `git -C <wt> status --porcelain --untracked-files=all --ignored -- .thrum` — **both flags**; the narrow form returns a false zero
+- no restart snapshot under `<worktree>/.thrum/restart/` — a snapshot means a
+  sleeping agent that expects to wake with its context
+
+## Reaping many worktrees at once — the batch path
+
+The single-agent gate above still governs EACH worktree; batching changes only how you
+GATHER the evidence and EXECUTE, never the judgment.
+
+**Gather with read-only examiner sub-agents.** For dozens of candidates, partition them
+across background sub-agents that examine each worktree read-only and RETURN a verdict —
+they never reap. Per worktree each reports: sleeping-agent marker present?; branch
+containment (ancestor of trunk / pushed / UNMERGED-with-commit-list); only-copy authored
+content (docs/plans/specs, undelivered reports, restart snapshots), ignoring regenerable
+dirt (`scripts/thrum-*.sh`, `.thrum/redirect`, `runtime_config.json`). Fence them READ-ONLY
+(no checkout/reset/stash/clean/rebase/commit/push, no `worktree remove`, no `agent delete`,
+no `rm`). You consolidate and decide.
+
+**Cross-check the reap set against the live + sleeping roster before ANY deletion** — one
+protected agent in the set aborts the batch. Build the exclusion from the live-pid set +
+sleeping set + locked worktrees, not from names.
+
+**Salvage only-copy state FIRST, and diff by NAME.** Copy with `cp -a`, then compare source
+vs salvage with `find -type f | sort` (set-diff by NAME) BEFORE trusting per-file `cmp` — a
+flat copy of two same-basename files (e.g. `.thrum/restart/<a>.md` and
+`.thrum/context/<a>.md`) silently clobbers one, and `cmp` on what copied passes clean. Give
+salvaged files distinct names and land the salvage somewhere durable (the main repo, not
+`/private/tmp`).
+
+## 🔴 The reap is worktree-removal-only — and TEST every step on ONE item first
+
+**`thrum agent delete --force` is REFUSED by the CAS guard on a stale agent with an empty
+`agent_pid_start_time`** (*"expected-state premise is required … refusing rather than treating
+an empty/never-read premise as a match"*). `--force` does NOT bypass it; the guard is
+correct. So the reap that actually frees load is **`git worktree remove --force <path>`** —
+the delete best-effort-fails and leaves a **benign orphan DB row**, which you LEAVE (filtered
+at query per the fleet ruling; never `agent cleanup --force` to tidy them).
+
+⚠️ **After a large reap you may see a `DeadAgentSweeper` skip alert + elevated write-RPC
+latency — do NOT assume the reap caused it.** This box carries a standing single-writer
+contention condition (one serialized write conn, `SetMaxOpenConns(1)`) that spikes write-RPC
+latency recurrently and **reap-independently**. A large reap is at most ONE coincident spike: stranding dozens of stale
+agents (worktreeless, empty `pid_start_time` → always "due") stretches the sweep's
+evidence-gathering run-length (that is what `held=` measures — a run duration, mostly off-lock
+syscalls, not a lock hold or a deadlock; the skip is correct, the guard releases via `defer`),
+but it drives almost no writes of its own. The
+discriminator that it is contention and not poison: `write_pool in_use=0`,
+`selfheal_write_poison_detected=0`. **So do not chase the reap as the lever** — pacing/batching
+large reaps is mild hygiene at best (it trims run-length and a little pressure), a restart is
+transient relief only, and the durable fix is **writer-decontention**, owned by the
+daemon-perf agent. Symptom to recognize (reads and `daemon status` stay ~0.5s while
+`status --self` climbs — writes slow, not reads): hand it to the daemon-perf owner, don't
+re-diagnose the internals yourself.
+
+**Before running any batched destructive loop, run it on ONE item and verify the EFFECT**
+(agent gone from the registry / worktree gone from `git worktree list` and disk), not just
+the exit code. A batch can fail wholesale for a reason a single test surfaces instantly — a
+minimal-`PATH` loop/background context where `git`/`thrum`/`sleep` are `command not found`
+(set `PATH` explicitly or use absolute paths); a `read` that collapses a leading empty field.
+Batched worktree removal is also SLOW on a loaded box (seconds each) — run it in the
+background or in chunks, never one 2-minute foreground loop.
+
+## ⚠️ Idle time is corrupted by your own traffic
+
+A coordinator broadcast resets every recipient's transcript mtime. After any
+fleet-wide message, **every agent reads as freshly active** and the idle column
+is meaningless for hours.
+
+⇒ **Rank by the last message's CONTENT, not by elapsed time.** A nudged-then-idle
+agent re-states that it is standing by, so the content signal survives what the
+timing signal does not.
+
+## ⚠️ Two absences that are not evidence
+
+- **No transcript** does not mean no agent. Alive agents exist with no transcript
+  directory.
+- **Absent from `connect`** means only "no tmux session on THIS box". `connect` is
+  box-local; remote agents can never appear in it.
+
+## Idle-gopls RAM reclaim
+
+Once you've classified an agent as idle, its `gopls` process (if any) is a
+second, independent reclaim candidate — an idle agent's gopls is dead weight
+sitting in RAM.
+
+`scripts/reap-idle-gopls.sh` matches each running `gopls` process to its
+owning agent (ppid chain → tmux pane_pid → `thrum team --json` session) and
+uses `tmux_state` as a cheap first-pass filter — anything not idle by that
+signal is skipped outright. That filter is bounded, not authoritative: it
+does not replace this skill's own idle/finished judgment, which still comes
+from the transcript per the rules above. Run the script alongside the scan
+above, apply the same transcript-based gate to whatever it surfaces, and
+fold the result into a single combined table: idle agent · gopls PID ·
+RSS-MB.
+
+- Killing an idle agent's gopls is a no-op — it respawns on the agent's next
+  LSP request. Never destructive to the agent itself.
+- **NEVER kill a pool or active-worker gopls.** The script excludes by ROLE
+  (orchestrator, gate, coordinator, brainstormer, researcher — the roles
+  that are never reap targets) plus the non-idle-state skip above, plus one
+  named exception for a role-uncovered pool agent. It also runs a canary
+  self-check before printing anything: if it can't prove the exclusion still
+  resolves correctly, it aborts loudly instead of printing a kill-list.
+  Do not override or bypass any of this.
+- Same framing as the rest of this skill: the script **produces information,
+  you decide**. It is read-only and dry-run — it prints a kill-list, it never
+  kills anything.
+
+## Why this fails dangerously if you skip the gate
+
+The failure direction is **false-GONE**: concluding a live agent is finished. It
+authorises abandonment, and **nobody audits an agent nobody believes exists**, so
+the error has no natural discovery path. A false-ALIVE costs one wasted check.
+Prefer it.

package/assets/skills/coordinator-assessing-agent-completion/scan.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Rank alive agents by whether their last message reads as terminal.
+
+This is an INFORMATION source. It ranks and quotes; it does not conclude, and it
+deliberately has no flag that reaps, kills, or changes a phase. The reading agent
+makes the judgment call using the gate and containment checks in SKILL.md.
+
+Usage:
+    thrum tmux connect < /dev/null | python3 scan.py [worktree-root]
+
+Reads `session|@agent` lines on stdin (see SKILL.md for the awk that produces
+them). Default worktree root is ~/.thrum/worktrees/thrum.
+"""
+
+import datetime
+import glob
+import json
+import os
+import re
+import sys
+
+# Phrases an agent uses to declare it holds nothing. Matching one makes an agent
+# a CANDIDATE, never a decision -- the blocker check in SKILL.md is what decides.
+TERMINAL = (
+    "standing by", "standing down", "stand down", "task done", "no further action",
+    "nothing to add", "nothing further", "completion report sent", "inbox is clear",
+    "inbox clear", "no action needed", "no reply needed", "idle", "held pending",
+    "awaiting", "nothing owed", "work is complete", "done and reported",
+)
+
+
+def slug(path):
+    """Claude Code's project-dir naming: every character that is
+    not [A-Za-z0-9] becomes '-' -- not just '/' and '.'.
+    Mirrors Claude Code's own path-encoding algorithm exactly for ASCII input -- must stay byte-for-byte in sync with it.
+    """
+    return re.sub(r"[^A-Za-z0-9]", "-", path)
+
+
+def last_assistant_text(path):
+    """Last non-empty assistant text block, or '' if none."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return ""
+    for line in reversed(lines):
+        try:
+            rec = json.loads(line)
+        except ValueError:
+            continue
+        if rec.get("type") != "assistant":
+            continue
+        for block in rec.get("message", {}).get("content", []):
+            if isinstance(block, dict) and block.get("type") == "text":
+                text = " ".join(block.get("text", "").split())
+                if text:
+                    return text
+    return ""
+
+
+def main():
+    root = sys.argv[1] if len(sys.argv) > 1 else os.path.expanduser(
+        "~/.thrum/worktrees/thrum")
+    projects = os.path.expanduser("~/.claude/projects")
+    now = datetime.datetime.now(datetime.timezone.utc)
+
+    rows, no_transcript = [], []
+    for line in sys.stdin:
+        line = line.strip()
+        if "|" not in line:
+            continue
+        session, agent = line.split("|", 1)
+        files = glob.glob(os.path.join(projects, slug(os.path.join(root, session)), "*.jsonl"))
+        if not files:
+            # NOT evidence the agent is gone -- see SKILL.md.
+            no_transcript.append(agent)
+            continue
+        newest = max(files, key=os.path.getmtime)
+        mtime = datetime.datetime.fromtimestamp(os.path.getmtime(newest),
+                                                datetime.timezone.utc)
+        text = last_assistant_text(newest)
+        low = text.lower()
+        hits = [p for p in TERMINAL if p in low]
+        rows.append(((now - mtime).total_seconds() / 3600.0, agent, hits, text))
+
+    rows.sort(key=lambda r: (not r[2], -r[0]))
+
+    print(f"alive with transcripts: {len(rows)}   no transcript: {len(no_transcript)}")
+    print("\nLAST MESSAGE READS AS TERMINAL -- an observation, not a recommendation.")
+    print("Name each one's blocker and prove it dead before concluding. See SKILL.md.\n")
+    any_candidate = False
+    for idle, agent, hits, text in rows:
+        if not hits:
+            continue
+        any_candidate = True
+        print(f"  {agent:<28} idle {idle:5.1f}h  [{', '.join(hits)}]")
+        print(f"    {text[:150]}")
+    if not any_candidate:
+        print("  (none)")
+
+    print("\nNOT terminal -- still working or mid-exchange:")
+    for idle, agent, hits, _ in rows:
+        if not hits:
+            print(f"  {agent:<28} idle {idle:5.1f}h")
+
+    if no_transcript:
+        print("\nNo transcript found (NOT evidence of absence):")
+        for agent in no_transcript:
+            print(f"  {agent}")
+
+    print("\nIdle hours are unreliable after any fleet broadcast -- your own "
+          "traffic resets every recipient's clock. Rank by content, not time.")
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/coordinator-branch-split-on-block/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: coordinator-branch-split-on-block
+description: "Use when a Pass-3 merge gate (hotpath, philosophy) or dual review BLOCKS on ONE concern of a branch that bundles multiple independent concerns, while the other concern(s) are clean - on a live multi-writer shared branch. Walks the split-land-recut sequence - separate the blocked concern from the clean one(s), land the clean half first, re-cut the blocked half onto the now-moved base, and verify the dropped commits are NOT ancestors of the re-cut tip before re-gating and merging."
+---
+
+# Coordinator: Branch-Split When One Concern Blocks a Multi-Concern Branch
+
+## When to use
+
+- A Pass-3 dual merge-gate (`coordinator-hotpath-merge-gate` or
+  `coordinator-philosophy-merge-gate`) — or dual review — **BLOCKS on one
+  identifiable concern** of a branch, while the branch also carries one or
+  more genuinely independent, unrelated concerns that are clean.
+- The clean concern(s) are ready to land on their own merits and gain nothing
+  from waiting on the blocked concern's fix.
+- The branch lives on a **live multi-writer shared branch** — other
+  coordinators/agents are also pushing, so the base moves under you and a
+  naive re-cut needs an explicit safety check, not just a rebase.
+
+**Don't use when:**
+
+- The BLOCK concern and the "clean" concern actually share code or intent —
+  if splitting would require cherry-picking around interdependent commits,
+  this is not an independent-concerns split; fix the blocker in place
+  instead.
+- Only one concern exists on the branch. A single-concern BLOCK just goes
+  back to the implementer normally — there is nothing to separate.
+
+## The split decision
+
+When a gate names a BLOCKING finding scoped to one part of the diff, and the
+rest of the diff is unrelated to that finding, split the branch into:
+
+- **The clean half** — the concern(s) with zero BLOCKING findings.
+- **The blocked half** — the concern the gate flagged.
+
+State the split explicitly in the merge report before doing anything else:
+name which commits belong to which half. If a commit touches both concerns,
+that commit belongs to the blocked half (never guess a commit apart) or the
+split isn't clean enough to attempt this play.
+
+## Land the clean half first
+
+Do not hold the clean half hostage to the blocked half's fix cycle. Route the
+clean half through its own merge report to the merge-king (coordinators
+never self-merge) and get it merged **first**. This advances the mainline
+tip by the clean half's commits.
+
+## Re-cut the blocked half onto the now-moved base
+
+> **This is not the banned rebase.** The project-wide ban (see
+> `coordinator-dispatching-work` and `orchestrate` — "merge forward, never
+> rebase") targets rebasing a still-live, in-flight branch onto a moved base
+> as the pre-MERGE-READY sync step: a stale-local-ref rebase there can
+> silently revert commits landed since your last fetch, with no check
+> catching it. The re-cut below is a different operation on a different
+> object — you are not syncing an existing branch, you are **building a new
+> branch from scratch** out of only the blocked half's own unpushed commits,
+> and the operation is made safe by an explicit invariant check (below), not
+> by care alone. Rebasing (or cherry-picking) a branch's own local, unpushed
+> commits onto a fresh base during a deliberate re-cut is legitimate; do not
+> "fix" this section by replacing it with merge-forward.
+
+Once the clean half is merged, the blocked half must be **re-cut** — not
+merely rebased — onto the new tip, so it carries **only its own commits**,
+not a copy of the clean half's commits riding along from the original
+branch-off point. Concretely: create the new branch from the merged tip
+(the clean half's merge SHA, announced by SHA unprompted, per base-mover
+discipline), then cherry-pick or rebase only the blocked half's own commits
+onto it. The goal state is a
+branch whose full commit range is exactly "the blocked concern's fix,"
+nothing else.
+
+## The not-ancestor invariant — the load-bearing check
+
+**Pin exactly which SHAs are the "dropped set" — this is the detail the check
+lives or dies on.** The dropped set is the clean half's commits **as they
+existed on the original pre-split bundled branch** — their ORIGINAL SHAs,
+before the clean half was landed. It is **not** the clean half's merged
+form: landing the clean half can rewrite its commits (a rebase, a squash, a
+merge-time correction), which mints **new, distinct git objects** with new
+SHAs. Those merged-form SHAs are *expected*, *correct* ancestors of the
+re-cut tip, because construction branched the re-cut FROM the merged tip —
+seeing them as ancestors is not a failure, it's the point.
+
+**After re-cutting, verify the ORIGINAL pre-split SHAs of the clean half's
+commits are NOT ancestors of the re-cut branch's tip:**
+
+```bash
+git merge-base --is-ancestor <original-pre-split-clean-half-sha> <recut-blocked-tip>
+# exit 1 (NOT an ancestor) is the PASS condition
+```
+
+Run this for every commit in the dropped set (the original pre-split SHAs),
+not just the first one — and never substitute the merged-form SHAs here, or
+the check inverts and fails a safe re-cut.
+
+**Why this is the check that matters:** the risk isn't that the re-cut tip
+descends from the clean half's *landed* fix — it must, by construction. The
+risk is that the re-cut branch was built sloppily (e.g. a naive rebase of
+the whole original bundle instead of a cherry-pick of only the blocked
+half's commits) and ended up carrying the clean half's **original,
+pre-correction commit objects** as ancestors alongside the merged tip. If
+that happens, merging the re-cut branch feeds those original objects into a
+future merge-base calculation on the same files, and git's three-way merge
+can resolve back toward the older, pre-correction content — silently
+reverting whatever the clean half's merge fixed. There is no conflict, no
+warning, no gate that catches this by construction: the merge just succeeds
+and quietly re-applies the older version. Verification (ancestry) has a
+shelf life, and re-deriving it AT THIS SPECIFIC HANDOFF (the re-cut) is not
+optional.
+
+Run the check at **re-cut time** and again immediately before the merge-king
+executes the re-cut branch's merge (the base can move again in between on a
+live shared branch — re-run, don't relay a stale result).
+
+## Three-pass re-gate on the re-cut branch
+
+The re-cut branch is a new artifact (different base, different commit set)
+and gets a full re-gate, not a diff-against-the-old-gate. Follow the
+three-pass order, in order:
+
+1. **UNFRAMED first** — no defect brief, read the full changed functions,
+   flag anything nobody asked about. Run this before the other two; a
+   framed pass run first anchors every subsequent pass to the same blind
+   spot.
+2. **CODE-DERIVED enumeration** — terms and symbols pulled from the code
+   itself (not from the original defect description), enumerate every call
+   site / consumer.
+3. **BY-EFFECT** — assert the specific defect the original BLOCK named
+   cannot occur, phrased as a checkable behavior. Example from the worked
+   case: "an inconclusive liveness probe produces neither a tombstone nor a
+   repair" — a concrete, testable claim, not "the fix looks right."
+
+A code-derived enumeration is not a substitute for the unframed pass — it is
+still aimed at symbols the code review chose to look at. Both are required.
+
+## Hold the implementer's retirement until BOTH halves merge
+
+Do not retire (agent.delete / worktree teardown) the implementer who owns
+this work until **both** the clean half and the blocked half have merged.
+The implementer's context on the blocked half's fix is exactly what the
+three-pass re-gate cycle needs if it surfaces further findings; retiring
+early forces a cold restart mid-fix-cycle.
+
+## Gate that closes it
+
+Both halves merged, both efficacy rows recorded (one row per merged branch,
+not one row for the original bundled branch), the not-ancestor invariant's
+PASS result is part of the merge report the merge-king relied on (not
+asserted after the fact).
+
+## See also
+
+- `coordinator-hotpath-merge-gate` / `coordinator-philosophy-merge-gate` —
+  the Pass-3 gates whose BLOCK verdict triggers this play.
+- `coordinator-running-review-cycles` — the dual-review cycle that may also
+  originate a scoped BLOCK this play applies to.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session about branch-splitting, capture it
+via the `coordinator-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create`
+shape.