@iceinvein/agent-skills 0.23.5 → 0.23.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.23.5",
+  "version": "0.23.7",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -293,9 +293,9 @@
   },
   {
     "name": "sluice",
-    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
+    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.25.5"
+    "version": "0.26.1"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/references/status.md

@@ -29,14 +29,21 @@ bash <skill-dir>/scripts/status.sh close
 bash <skill-dir>/scripts/status.sh route deep
 bash <skill-dir>/scripts/status.sh verify -- bun test
 bash <skill-dir>/scripts/status.sh verify --none "docs only, nothing executes them"
+bash <skill-dir>/scripts/board.sh
+bash <skill-dir>/scripts/board.sh --watch 5
+bash <skill-dir>/scripts/board.sh --json
 ```
 
 `route` and `verify` are the two exceptions: neither needs a run.
 
-`route` reads and writes no state, and prints `sluice: <channel> channel` so
-the channel lands in the transcript as a tool input, which is kept as written
-where the announcement's prose may not be. `references/meter.md` says why that
-matters.
+`route` prints `sluice: <channel> channel` so the channel lands in the
+transcript as a tool input, which is kept as written where the announcement's
+prose may not be. `references/meter.md` says why that matters. It opens no run,
+but with a session id (`--session`, defaulting to `$CLAUDE_CODE_SESSION_ID`) it
+writes that session's entry on the board, because a route is the only sign a
+`fast` or `main` session leaves. With no id it writes nothing: there is nobody
+to name, and none is made up. Either way it exits 0 once the channel is
+printed, since the announcement is the part that matters.
 
 `verify -- <cmd>` runs the check from the tree's top level, passes a failing
 check's exit code through, and on a pass writes the tree's content digest to
@@ -483,6 +490,90 @@ cannot redirect. That is the same argument the channel announcement makes, and
 the statusline is where it holds for the hour after the announcement scrolled
 away.
 
+## Board
+
+Everything above answers from inside one worktree set. `scripts/board.sh`
+answers across the machine: every live `deep` run and every routed `fast` or
+`main` session, drawn once, or redrawn in place every two seconds (or every
+`<seconds>` given) with `--watch` until interrupted. `<seconds>` is a positive
+whole number read in base ten, leading zeros allowed (`05` is five, `08`
+eight); `0`, `00` or anything else exits 4. `--json` prints the combined state
+for another reader instead, with the counts the header shows, and does not
+combine with `--watch`.
+
+It reads an index of pointers, never copies, at `$SLUICE_BOARD_DIR`, else
+`$CLAUDE_CONFIG_DIR/sluice/board`, else `$HOME/.claude/sluice/board`; with none
+of the three set nothing is written and the board is empty. `runs/` holds one
+file per tree with a live run, naming the tree, and `sessions/<id>.json` one
+per routed session. `run.json` stays the single authority on a run, so the
+board can never show a stale copy of one. `SLUICE_BOARD_DIR` exists so the
+tests can point every script at a temporary directory and never touch the real
+board: the suite's preload sets it to a fresh one and makes every child a test
+spawns inherit it, since Bun hands a child spawned with no `env` the
+environment bun started with rather than the one the preload changed.
+
+`scripts/board-index.sh` is the only writer. `init` adds the run's pointer,
+`move` re-points it and `close` drops it. A task flip writes nothing to the
+board, because a plan's flips are many and each write is a process; the cost
+is that a run opened before the board existed stays off it until it is
+closed and a new one opened. `route` writes the session's
+entry as `working`, a later route in the same session overwriting it, so an
+escalation from `fast` to `main` shows as `main`. The Stop hook marks a `fast`
+or `main` entry `handed back` when it lets a stop through, and only then: a
+refused stop is the session still working. It marks a `deep` entry the same
+way when no run is live (the design stop before any run exists, the stop
+after `close`, a session that routed deep and never opened a run), and leaves
+it as it is while one is, since the board draws that run's bar for it. The
+run is found the way the hook's run guard finds one, taking the first in this
+order: a run in the stop's own tree, then the run found through the session's
+pointer at the main tree, then the tree's `run.at` forward, never the main
+tree's run read from a runless worktree. That first run counts as live only
+when it is the session's own: its `run.json` names that session. A run that
+names no session is no session's own, matching the board, which hides a
+session row only behind a run naming it. When it names none or another session,
+whether sitting in the stop's own tree or reached through the forward, or its
+`run.json` cannot be read, the entry is marked `handed back`, and no later run
+in the order is looked at. A failed
+board write is one
+`status.sh: note: board not updated: ...` line on stderr and never changes the
+command's result, because the board is a view across trees and not part of
+any run.
+
+The header counts each channel's working and handed-back work. A drawn run
+counts as working in its `run.json` channel: a `deep` run toward `N deep`
+alongside the working `deep` sessions, a `main` run toward `N main working`, a
+`fast` run toward `N fast working`. A run naming any other channel, or none,
+counts toward `deep`, since it still draws as a run's bar. `--json` `counts`
+holds the same numbers: `counts.working.<channel>` is that channel's working
+sessions plus its drawn runs (so `working.deep` includes the `deep` runs, where
+before it held the working `deep` sessions only and the header added the runs
+itself), and `counts.runs` is every run drawn, whatever its channel.
+
+A run block is `status.sh line --full` for its tree, unchanged, so it reads
+exactly as the statusline does. Blocked runs sort first, then those with a task
+active or in review, then the rest. A session row shows its channel, the tree's
+name and its state: `working` with the time since it was routed, `handed back`
+with the time since. The channel, name and state columns are padded to the
+widest value among that frame's session rows, two spaces apart, so the ages
+line up. Width is counted in characters of the drawn text (jq's count, so
+the same under a C locale), never colour codes. A wide glyph such as `日` that
+takes two terminal cells counts as one, so a row holding one draws a cell
+short; a name stored decomposed (a letter plus a combining accent, as some
+filesystems write paths) counts one column per code point, so it can draw a
+cell short too. A `deep` session row reads `handed back` once a turn ends with
+no run live for it, and otherwise stays `working` while its run's bar is
+drawn. A session of any channel whose id is a drawn run's `session` is not
+listed or counted again, so one piece of work is one row and one count. Session
+entries past a day since their last update are hidden, the same one-day line
+`show` uses for an idle run, and the next `init`, or `route` with a session
+id, removes them along with pointers to trees that no longer hold a run. An
+entry that cannot be read is skipped on its own, so one bad file costs one row
+rather than the board.
+
+The board writes nothing, so it takes no lock. It needs `jq` and exits 5
+without it, and 6 when the board cannot be read at all, because unlike the
+statusline it has somewhere to put an error.
+
 ## Friction
 
 "I know which task I'm on." You do, until this session is summarised. The file

package/skills/sluice/scripts/board-index.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# sluice board index: which trees hold a live run and which sessions are
+# routed where, kept in one place so a board can list them without walking
+# every worktree on the machine.
+#
+#   board-index.sh run-add <tree>
+#   board-index.sh run-drop <tree>
+#   board-index.sh session <id> <fast|main|deep> <tree>
+#   board-index.sh handback <id> [--keep-deep]
+#   board-index.sh prune
+#
+# The root is $SLUICE_BOARD_DIR, else $CLAUDE_CONFIG_DIR/sluice/board, else
+# $HOME/.claude/sluice/board. With none of the three set there is nowhere safe
+# to write, so every verb exits 0 having written nothing. Runs live at
+# <root>/runs/<key>, one line naming the tree, where <key> is the tree with %
+# encoded as %25 and / as %2F. Sessions live at <root>/sessions/<id>.json.
+#
+# `--keep-deep` is for a stop while the session's run is live: the board draws
+# that run's bar for a deep session, so its entry stays as it is.
+#
+# Exit: 0 ok, 1 could not write, 4 bad arguments, 5 jq missing.
+
+set -u
+
+err() { echo "board-index.sh: $*" >&2; }
+
+usage() {
+	echo "usage: board-index.sh run-add <tree> | run-drop <tree> | session <id> <fast|main|deep> <tree> | handback <id> [--keep-deep] | prune" >&2
+	exit 4
+}
+
+now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+key() {
+	local k="${1//%/%25}"
+	echo "${k//\//%2F}"
+}
+
+# Writes $2 to $1 through a temp file so a reader never sees half an entry. The
+# temp is dotted so the runs/* and sessions/*.json globs never match it. Never
+# call this on the right of a pipe: its exit would end only the subshell.
+put() {
+	local tmp
+	tmp="$(dirname "$1")/.$(basename "$1").tmp.$$"
+	if ! { printf '%s\n' "$2" >"$tmp"; } 2>/dev/null || ! mv "$tmp" "$1" 2>/dev/null; then
+		rm -f "$tmp"
+		err "could not write $1"
+		exit 1
+	fi
+}
+
+need_jq() {
+	command -v jq >/dev/null 2>&1 || { err "jq is required"; exit 5; }
+}
+
+verb="${1:-}"
+[ $# -gt 0 ] && shift
+case "$verb" in
+	run-add|run-drop) [ $# -eq 1 ] || usage ;;
+	handback)
+		[ $# -eq 1 ] || { [ $# -eq 2 ] && [ "$2" = --keep-deep ]; } || usage
+		;;
+	session) [ $# -eq 3 ] || usage ;;
+	prune) [ $# -eq 0 ] || usage ;;
+	*) usage ;;
+esac
+
+if [ -n "${SLUICE_BOARD_DIR:-}" ]; then
+	ROOT="$SLUICE_BOARD_DIR"
+elif [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+	ROOT="$CLAUDE_CONFIG_DIR/sluice/board"
+elif [ -n "${HOME:-}" ]; then
+	ROOT="$HOME/.claude/sluice/board"
+else
+	exit 0
+fi
+
+case "$verb" in
+	run-add)
+		[ -n "$1" ] || exit 0
+		path="$ROOT/runs/$(key "$1")"
+		mkdir -p "$ROOT/runs" 2>/dev/null || { err "could not write $path"; exit 1; }
+		put "$path" "$1"
+		;;
+	run-drop)
+		[ -n "$1" ] || exit 0
+		path="$ROOT/runs/$(key "$1")"
+		# Checked rather than read off rm's status: GNU rm -f takes "not a
+		# directory" for "nothing there" and exits 0 where BSD rm fails.
+		for dir in "$ROOT" "$ROOT/runs"; do
+			[ ! -e "$dir" ] || [ -d "$dir" ] || { err "could not remove $path"; exit 1; }
+		done
+		rm -f "$path" 2>/dev/null && [ ! -e "$path" ] || { err "could not remove $path"; exit 1; }
+		;;
+	session)
+		id="$1" channel="$2" tree="$3"
+		case "$id" in
+			*/*|.*) err "bad session id: $id"; exit 4 ;;
+		esac
+		case "$channel" in
+			fast|main|deep) ;;
+			*) err "unknown channel: $channel"; exit 4 ;;
+		esac
+		[ -n "$id" ] && [ -n "$tree" ] || exit 0
+		need_jq
+		path="$ROOT/sessions/$id.json"
+		mkdir -p "$ROOT/sessions" 2>/dev/null || { err "could not write $path"; exit 1; }
+		t="$(now)"
+		entry="$(jq -n --arg s "$id" --arg c "$channel" --arg tr "$tree" --arg t "$t" \
+			'{session: $s, channel: $c, tree: $tr, routed: $t, state: "working", updated: $t}')"
+		put "$path" "$entry"
+		;;
+	handback)
+		id="$1" keep_deep="${2:-}"
+		case "$id" in
+			''|*/*|.*) exit 0 ;;
+		esac
+		path="$ROOT/sessions/$id.json"
+		[ -f "$path" ] || exit 0
+		need_jq
+		channel="$(jq -r '.channel' "$path" 2>/dev/null)" || exit 0
+		[ -n "$keep_deep" ] && [ "$channel" = deep ] && exit 0
+		updated="$(jq --arg t "$(now)" '.state = "handed back" | .updated = $t' "$path")" || exit 0
+		put "$path" "$updated"
+		;;
+	prune)
+		need_jq
+		# The builtin read rather than a process per pointer, because prune runs
+		# on every init and route and pointers pile up; read whole, so a tree
+		# path holding a newline still names its tree. read -d '' stops at EOF
+		# with a non-zero status, so a failed open is told from a short read by
+		# whether the file is readable; a pointer that cannot be read is kept.
+		for f in "$ROOT"/runs/*; do
+			[ -f "$f" ] || continue
+			tree=""
+			{ IFS= read -r -d '' tree; } 2>/dev/null <"$f" || [ -n "$tree" ] || [ -r "$f" ] || continue
+			tree="${tree%$'\n'}"
+			[ -f "$tree/.sluice/run.json" ] || rm -f "$f"
+		done
+		# One jq for every session rather than one each, because prune runs on
+		# every route and a jq per file made each route slower than the last day
+		# of sessions. Contents go on stdin as NUL-separated name and contents
+		# records, as board.sh feeds them, so no count of files meets the argv
+		# limit. Anything unreadable or unparseable comes back to be removed.
+		for f in "$ROOT"/sessions/*.json; do
+			[ -f "$f" ] || continue
+			entry=""
+			{ IFS= read -r -d '' entry; } 2>/dev/null <"$f"
+			printf '%s\0%s\0' "$f" "$entry"
+		done | jq -R -s -j '
+			(split("\u0000") | .[:-1]) as $p
+			| range(0; $p | length; 2)
+			| select(($p[. + 1] | try (fromjson | (now - (.updated | fromdateiso8601)) <= 86400) catch false) != true)
+			| $p[.] + "\u0000"
+		' 2>/dev/null | while IFS= read -r -d '' f; do
+			rm -f "$f"
+		done
+		;;
+esac
+exit 0

package/skills/sluice/scripts/board.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+# sluice board: every live run and every routed session on the machine, drawn
+# from the board index so nobody has to walk the worktrees to find them.
+#
+#   board.sh [--json] [--watch [<seconds>]]
+#
+# --json prints the combined state instead of drawing it. --watch redraws every
+# <seconds> (default 2) until interrupted. The index is read, never written.
+# The root is $SLUICE_BOARD_DIR, else $CLAUDE_CONFIG_DIR/sluice/board, else
+# $HOME/.claude/sluice/board; with none of the three set the index is empty.
+#
+# Exit: 0 ok, 4 bad arguments, 5 jq missing, 6 the board could not be read.
+
+set -u
+
+err() { echo "board.sh: $*" >&2; }
+
+usage() {
+	echo "usage: board.sh [--json] [--watch [<seconds>]]" >&2
+	exit 4
+}
+
+json=0 watch=0 interval=2
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--json) json=1; shift ;;
+		--watch)
+			watch=1
+			shift
+			case "${1:-}" in
+				''|--*) ;;
+				*) interval="$1"; shift ;;
+			esac
+			;;
+		*) usage ;;
+	esac
+done
+# Leading zeros are stripped as text rather than through $((10#...)), which
+# would wrap a long run of digits into some other number.
+seconds="$interval"
+while case "$seconds" in 0?*) true ;; *) false ;; esac; do
+	seconds="${seconds#0}"
+done
+case "$seconds" in
+	''|0|*[!0-9]*) err "--watch needs a positive whole number of seconds, not $interval"; exit 4 ;;
+esac
+interval="$seconds"
+if [ "$watch" = 1 ] && [ "$json" = 1 ]; then
+	err "--watch and --json do not combine"
+	exit 4
+fi
+
+command -v jq >/dev/null 2>&1 || { err "jq is required"; exit 5; }
+
+if [ -n "${SLUICE_BOARD_DIR:-}" ]; then
+	ROOT="$SLUICE_BOARD_DIR"
+elif [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+	ROOT="$CLAUDE_CONFIG_DIR/sluice/board"
+elif [ -n "${HOME:-}" ]; then
+	ROOT="$HOME/.claude/sluice/board"
+else
+	ROOT=""
+fi
+
+ESC="$(printf '\033')"
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+	colour=1
+else
+	colour=0
+fi
+
+paint() { # <sgr> <text>
+	if [ "$colour" = 1 ]; then
+		printf '%s[%sm%s%s[0m' "$ESC" "$1" "$2" "$ESC"
+	else
+		printf '%s' "$2"
+	fi
+}
+
+# The board polls for hours while runs close and sessions are pruned under it,
+# so each file is read into a variable first and skipped when that read fails,
+# and jq gets contents rather than paths that may be gone by the time it opens
+# them. The read is the builtin, so a frame spawns no process per file. TREES
+# keeps each run's path by index, so a path holding a newline or a tab reaches
+# status.sh whole rather than through a line-split read. KEYS and VALUES are
+# the records emit hands jq. Returns 1 when the root, runs/ or sessions/
+# exists but cannot be listed: one not yet created is empty, since nothing has
+# been written there, but one that cannot be read would draw as nothing running
+# when it may hold every run on the machine.
+gather() {
+	local n=0 f tree run entry d
+	TREES=()
+	KEYS=()
+	VALUES=()
+	[ -n "$ROOT" ] || return 0
+	for d in "$ROOT" "$ROOT/runs" "$ROOT/sessions"; do
+		if [ -e "$d" ] || [ -L "$d" ]; then
+			[ -d "$d" ] && [ -r "$d" ] && [ -x "$d" ] || return 1
+		fi
+	done
+	for f in "$ROOT"/runs/*; do
+		[ -f "$f" ] || continue
+		# read -d '' stops at EOF with a non-zero status, so a short read is told
+		# from a failed open by whether anything arrived.
+		tree=""
+		{ IFS= read -r -d '' tree || [ -n "$tree" ]; } 2>/dev/null <"$f" || continue
+		tree="${tree%$'\n'}"
+		[ -n "$tree" ] || continue
+		run=""
+		{ IFS= read -r -d '' run || [ -n "$run" ]; } 2>/dev/null <"$tree/.sluice/run.json" || continue
+		TREES[$n]="$tree"
+		KEYS+=("t$n" "r$n")
+		VALUES+=("$tree" "$run")
+		n=$((n + 1))
+	done
+	n=0
+	for f in "$ROOT"/sessions/*.json; do
+		[ -f "$f" ] || continue
+		entry=""
+		{ IFS= read -r -d '' entry || [ -n "$entry" ]; } 2>/dev/null <"$f" || continue
+		KEYS+=("s$n")
+		VALUES+=("$entry")
+		n=$((n + 1))
+	done
+}
+
+# Contents go to jq on stdin as NUL-separated key and value records rather than
+# as arguments, so no file's size runs into the argv limit. JSON text never
+# holds a NUL, and a tree path cannot.
+emit() {
+	local i=0
+	while [ "$i" -lt "${#KEYS[@]}" ]; do
+		printf '%s\0%s\0' "${KEYS[$i]}" "${VALUES[$i]}"
+		i=$((i + 1))
+	done
+}
+
+combine() { # [jq filter appended to COMBINE]
+	emit | jq -R -s --arg home "${HOME:-}" "$COMBINE${1:-}" 2>/dev/null
+}
+
+# Builds {board, order, lines}: board is what --json prints, order the runs to
+# draw as "<index into TREES>\t<name>\t<path as shown>", lines the session rows.
+# Those fields are joined rather than put through @tsv, which escapes a
+# backslash that read -r then keeps, so a name would draw doubled; clean has
+# already dropped every tab and newline a field could hold. Session rows are
+# padded here because jq counts a string in characters whatever the locale,
+# where bash under C counts bytes and would push a row holding café out of line.
+# A wide CJK glyph still counts as one, so a row holding one draws a cell short.
+# Each entry is evaluated on its own inside try, so one with an odd shape costs
+# only itself, and the counts are taken from the same filtered list the rows
+# are drawn from.
+COMBINE='
+	def clean: if type == "string" then gsub("[\u0000-\u001f\u007f]"; "") else . end;
+	def base: split("/") | map(select(. != "")) | last // "/";
+	def age($t): ((now - ($t | fromdateiso8601)) / 60 | floor | if . < 0 then 0 else . end)
+		| if . < 60 then "\(.)m" else "\(. / 60 | floor)h\(. % 60)m" end;
+	def need(cond; why): if cond then . else error(why) end;
+	(split("\u0000") | .[:-1]) as $parts
+	| ([range(0; $parts | length; 2) | {key: $parts[.], value: $parts[. + 1]}] | from_entries) as $n
+	| [$n | keys[] | select(test("^t[0-9]+$")) | ltrimstr("t") | tonumber
+		| . as $i
+		| try (
+			$n["r\($i)"] | fromjson
+			| need(type == "object"; "not a run")
+			| need((.tasks | type) == "array"; "no tasks")
+			| need(all(.tasks[]; type == "object" and (.status | type) == "string"); "odd tasks")
+			| {i: $i, tree: $n["t\($i)"], run: .,
+				rank: (if any(.tasks[]; .status == "blocked") then 0
+					elif any(.tasks[]; .status == "active" or .status == "review") then 1
+					else 2 end),
+				t: (.updated // .started | fromdateiso8601)}
+		) catch empty]
+	| reduce .[] as $r ([]; if any(.[]; .tree == $r.tree) then . else . + [$r] end)
+	| sort_by([.rank, -.t])
+	| . as $runs
+	| [$runs[].run.session | strings] as $taken
+	| [$n | keys[] | select(test("^s[0-9]+$")) | $n[.]
+		| try (
+			fromjson
+			| need(type == "object"; "not an entry")
+			| with_entries(.value |= clean)
+			| need((.tree | type) == "string" and .tree != ""; "no tree")
+			| need(.channel == "fast" or .channel == "main" or .channel == "deep"; "bad channel")
+			| need(.state == "working" or .state == "handed back"; "bad state")
+			| (.updated | fromdateiso8601) as $t
+			| select(now - $t <= 86400)
+			| select(.session as $s | $taken | index([$s]) | not)
+			| {entry: ., t: $t, cells: [.channel, (.tree | base), .state,
+				(if .state == "working" then "◷ \(age(.routed))" else "\(age(.updated)) ago" end)]}
+		) catch empty]
+	| sort_by(-.t)
+	| . as $sessions
+	| [range(0; 3) as $k | [$sessions[].cells[$k] | length] | max // 0] as $widths
+	| def pad($w): . + (" " * ($w - length));
+	# A run of any other channel still draws as a run, the bar deep runs draw, so
+	# it is counted with them rather than vanishing from the header.
+	def channel: if . == "fast" or . == "main" then . else "deep" end;
+	def tally($state): reduce ("fast", "main", "deep") as $c ({}; .[$c] =
+		([$sessions[] | select(.entry.channel == $c and .entry.state == $state)] | length)
+		+ (if $state == "working" then [$runs[] | select(.run.channel | channel == $c)] | length else 0 end));
+	{board: {runs: [$runs[] | {tree, run}], sessions: [$sessions[].entry],
+			counts: {runs: ($runs | length), working: tally("working"), handed_back: tally("handed back")}},
+		order: [$runs[] | (.tree | clean) as $c | [.i, ($c | base),
+			(if $home != "" and $c == $home then "~"
+				elif $home != "" and ($c | startswith($home + "/")) then "~" + ($c | ltrimstr($home))
+				else $c end)] | map(tostring) | join("\t")],
+		lines: [$sessions[].cells | [range(0; 3) as $k | .[$k] | pad($widths[$k])] + [.[3]] | join("\t")]}
+'
+
+# Prints the frame, or returns 1 having printed nothing when the state could
+# not be built at all. Colour is painted here and stripped by the caller, once
+# per frame, when it is off.
+render() {
+	local s tag a b c d e f head first=1
+	gather || return 1
+	s="$(combine)" && [ -n "$s" ] || return 1
+	while IFS="$TAB" read -r tag a b c d e f; do
+		case "$tag" in
+			counts)
+				head=""
+				[ "$a" -gt 0 ] && head="$head · $a deep"
+				[ "$b" -gt 0 ] && head="$head · $b deep handed back"
+				[ "$c" -gt 0 ] && head="$head · $c fast working"
+				[ "$d" -gt 0 ] && head="$head · $d fast handed back"
+				[ "$e" -gt 0 ] && head="$head · $e main working"
+				[ "$f" -gt 0 ] && head="$head · $f main handed back"
+				[ -n "$head" ] || head=" · nothing running"
+				paint 1 sluice
+				printf '%s  ' "$head"
+				paint 2 "$CLOCK"
+				echo
+				;;
+			run)
+				echo
+				paint 1 "$b"
+				printf '  '
+				paint 2 "$c"
+				echo
+				bash "$SCRIPTS/status.sh" line --full --dir "${TREES[$a]}" 2>/dev/null
+				;;
+			session)
+				if [ "$first" = 1 ]; then
+					echo
+					first=0
+				fi
+				paint 1 "$a"
+				printf '  %s  %s  ' "$b" "$c"
+				paint 2 "$d"
+				echo
+				;;
+		esac
+	done <<EOF
+$(jq -r '
+	(.board.counts | ["counts", .working.deep, .handed_back.deep, .working.fast, .handed_back.fast, .working.main, .handed_back.main] | @tsv),
+	("run\t" + .order[]),
+	("session\t" + .lines[])' <<<"$s")
+EOF
+	return 0
+}
+
+UNREADABLE="could not read the board"
+TAB="$(printf '\t')"
+SCRIPTS="$(dirname "$0")"
+STRIP="s/$ESC\[[0-9;]*m//g"
+[ "$colour" = 1 ] && STRIP=""
+
+if [ "$json" = 1 ]; then
+	gather || { err "$UNREADABLE"; exit 6; }
+	combine ' | .board' || { err "$UNREADABLE"; exit 6; }
+	exit 0
+fi
+
+if [ "$watch" = 0 ]; then
+	CLOCK="$(date +%H:%M:%S)"
+	frame="$(render)" || { err "$UNREADABLE"; exit 6; }
+	printf '%s\n' "$frame" | sed "$STRIP"
+	exit 0
+fi
+
+sleeper=""
+restore() {
+	[ -n "$sleeper" ] && kill "$sleeper" 2>/dev/null
+	printf '%s[?25h' "$ESC"
+}
+trap restore EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+printf '%s[?25l%s[2J' "$ESC" "$ESC"
+while :; do
+	CLOCK="$(date +%H:%M:%S)"
+	frame="$(render)" || frame="board.sh: $UNREADABLE"
+	# Each line clears its own tail, so a row shorter than the one it overwrites
+	# leaves nothing of the old one behind. No newline after the last row: one
+	# there scrolls a frame as tall as the terminal on every redraw.
+	frame="$(printf '%s\n' "$frame" | sed -e "$STRIP" -e "s/\$/$ESC[K/")"
+	printf '%s[H%s%s[J' "$ESC" "$frame" "$ESC"
+	# Backgrounded so a signal ends the wait at once rather than after the sleep.
+	sleep "$interval" &
+	sleeper=$!
+	wait "$sleeper"
+	sleeper=""
+done

package/skills/sluice/scripts/status.sh

@@ -48,6 +48,15 @@
 # naming the tree the run is in, so that session finds its run from the main
 # tree however many other runs the set holds.
 #
+# `init` adds the run's tree to the machine's board index through
+# board-index.sh, `move` re-points it, and `close` drops it; a task flip
+# leaves the index alone. `route`
+# with a session id writes that session's entry (no id, nothing written).
+# `init`, and `route` with a session id, sweep the index of dead entries. The
+# sweep is best effort and silent, so only a run-add, run-drop or session
+# write that fails costs a note: one `status.sh: note: board not updated: ...`
+# line on stderr, never the command's result. scripts/board.sh draws the index.
+#
 # A flag value may not begin with `--`: unchecked, an omitted value silently
 # becomes the next flag and the field holds a flag name.
 
@@ -386,10 +395,27 @@ if [ "$SUB" = "line" ]; then
 	exit 0
 fi
 
+# The board is a view across every tree, not part of any run, so a board that
+# cannot be written costs a line on stderr and never the command's own result.
+# board-index.sh's own complaint is folded into the note, so a failure reads as
+# one line rather than two that look like separate problems.
+board_index() { # <verb> [args...]
+	local msg
+	msg="$(bash "$(dirname "$0")/board-index.sh" "$@" 2>&1 >/dev/null)" && return 0
+	msg="${msg//board-index.sh: /}"
+	err "note: board not updated: ${msg//$'\n'/; }"
+}
+
+# Pruning only tidies what the board reads, which skips dead entries anyway.
+board_prune() {
+	bash "$(dirname "$0")/board-index.sh" prune >/dev/null 2>&1 || true
+}
+
 # Exists to put the channel into the transcript verbatim, as a command that
-# ran, which run-stats and the stop guard read back. So it touches no state:
-# a route is called before any run is opened, and fast opens none at all. For
-# the same reason it runs ahead of the jq check below, which only state needs.
+# ran, which run-stats and the stop guard read back. It opens no run, since a
+# route is called before any run is opened and fast opens none at all, but with
+# a session id known it writes that session's entry on the board. It still runs
+# ahead of the jq check below, because the announcement must work without jq.
 # Bypass is refused because it is no code change, and a marker for it would
 # read back as a routed change that never happened.
 if [ "$SUB" = "route" ]; then
@@ -400,6 +426,14 @@ if [ "$SUB" = "route" ]; then
 	[ "$ROUTE" != "bypass" ] || { err "bypass is no code change, so there is nothing to route; just answer"; exit 4; }
 	in_set "$ROUTE" "$ROUTE_CHANNELS" || { err "unknown channel: $ROUTE (one of: $ROUTE_CHANNELS)"; exit 4; }
 	echo "sluice: $ROUTE channel"
+	# A route is the only sign a fast or main session leaves, so the board learns
+	# of it here. With no session id there is nobody to name, and none is made up.
+	if [ -n "$SESSION" ]; then
+		ROUTE_TREE="$(git -C "$ORIG_DIR" rev-parse --show-toplevel 2>/dev/null)"
+		[ -n "$ROUTE_TREE" ] || ROUTE_TREE="$(cd "$ORIG_DIR" 2>/dev/null && pwd -P)"
+		board_prune
+		board_index session "$SESSION" "$ROUTE" "$ROUTE_TREE"
+	fi
 	exit 0
 fi
 
@@ -904,6 +938,10 @@ case "$SUB" in
 			done
 		fi
 
+		# Opening a run is a rare enough moment to sweep the board of runs and
+		# sessions that ended without saying so.
+		board_prune
+
 		jq -n \
 			--arg topic "$TOPIC" \
 			--arg channel "$CHANNEL" \
@@ -917,6 +955,9 @@ case "$SUB" in
 			+ (if $session == "" then {} else {session: $session} end)
 			+ {tasks: []}
 		' | write_state || exit $?
+		# Here and in move only, not on every write: a flip spawning a board
+		# write was what a plan of sixty tasks paid sixty times over.
+		board_index run-add "$(cd "$DIR" && pwd -P)"
 
 		POINTER_TREE="$(main_tree "$DIR")"
 		if [ -n "$SESSION" ] && [ -n "$POINTER_TREE" ] && [ -d "$POINTER_TREE" ] \
@@ -1326,6 +1367,10 @@ case "$SUB" in
 			exit 3
 		fi
 		mv "$STATE" "$DEST_STATE" || { err "could not move $STATE to $DEST_STATE"; exit 1; }
+		# Only once the state has arrived, so the board never loses a run that
+		# failed to move.
+		board_index run-drop "$(cd "$DIR" && pwd -P)"
+		board_index run-add "$TO"
 
 		# After the state has arrived, never before: a note pointing at a run
 		# that never got there is worse than no note, being indistinguishable
@@ -1407,6 +1452,8 @@ case "$SUB" in
 			n=$((n + 1))
 		done
 		mv "$STATE" "$dest" || { err "could not archive $STATE"; exit 1; }
+		# After the archive, so a close that failed leaves the run on the board.
+		board_index run-drop "$(cd "$DIR" && pwd -P)"
 
 		# A note naming this tree has outlived the run it forwarded to. Left
 		# behind, it does not go quiet: the next run opened in this tree inherits

package/skills/sluice/scripts/stop-guard.sh

@@ -62,6 +62,106 @@ if [ -n "$input" ]; then
 	sid="$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null || true)"
 	transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
 fi
+
+# The run the session's own tree answers for, and only that: the state beside
+# it, or the state it forwarded into a worktree when `move` sent the run on
+# without the session. status.sh also lets a tree with no run of its own read
+# the main worktree's, and that one is not taken here: a Stop in such a tree may
+# be an unrelated session, and a remedy printed to it would reach into somebody
+# else's run.
+#
+# The forward is read here rather than left to status.sh's resolution because
+# the two questions differ. Resolution answers "which run can this tree read",
+# which is the right question for a render and the wrong one for a refusal. The
+# tree named in the note is then passed as `--dir`, so what follows asks about
+# one named tree and carries no layout knowledge of its own.
+#
+# The run this session opened in a worktree it never entered is its own too,
+# found through the pointer `init` left at the main tree, and it comes ahead of
+# the forward: the forward names whichever run was moved last, which with
+# several controllers in the main tree may be another session's.
+#
+# Sets top to the stop's tree and run_tree to the tree holding that run, or
+# leaves run_tree empty when there is none. One function for the run guard and
+# the board, so the run that keeps a deep session off the board is the run the
+# guard would refuse over.
+top=""
+run_tree=""
+resolved=""
+resolve_run_tree() {
+	local main session_tree="" forward=""
+	resolved=1
+	run_tree=""
+	top="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)"
+	[ -n "$top" ] || top="$cwd"
+	case "$sid" in
+		"" | */* | .*) ;;
+		*)
+			main="$(git -C "$cwd" worktree list --porcelain 2>/dev/null | sed -n '1s/^worktree //p')"
+			[ -n "$main" ] && [ -f "$main/.sluice/sessions/$sid" ] \
+				&& IFS= read -r session_tree <"$main/.sluice/sessions/$sid" 2>/dev/null
+			if [ -z "$session_tree" ] || [ ! -f "$session_tree/.sluice/run.json" ] \
+				|| [ "$(jq -r '.session // empty' "$session_tree/.sluice/run.json" 2>/dev/null)" != "$sid" ]; then
+				session_tree=""
+			fi
+			;;
+	esac
+	if [ -f "$top/.sluice/run.json" ]; then
+		run_tree="$top"
+	elif [ -n "$session_tree" ]; then
+		run_tree="$session_tree"
+	elif [ -f "$top/.sluice/run.at" ]; then
+		IFS= read -r forward <"$top/.sluice/run.at" 2>/dev/null || return 0
+		# A note outliving the run it named is stale, not a run to refuse a stop over.
+		[ -n "$forward" ] && [ -f "$forward/.sluice/run.json" ] || return 0
+		run_tree="$forward"
+	fi
+}
+
+# A stop let through is the session handing back, so the board marks it. A
+# trap rather than a call before each exit: the hook lets a stop through from
+# a dozen places, and a new one added later is covered without anyone having
+# to remember the board. Every block decision sets refused first, since a
+# refused stop is the session still working. The board's output and failure
+# are dropped: stdout carries the decision, and the hook always exits 0.
+#
+# A deep session whose run is live keeps its entry, because the board draws the
+# run's bar for it. Whether the run is live is asked here rather than taken
+# from the run guard, since most exits come before the guard runs, and a deep
+# session mid-run must not read as handed back on any of them. Resolving costs
+# git calls on every stop, so it is skipped for a session with no entry, and
+# not repeated when the run guard already did it.
+#
+# The run resolved is only the one this tree can reach, which through a forward
+# or a shared tree may be another session's; that run's bar is not this
+# session's work, so the entry is kept only for a run that names this session.
+# A run naming no session is no session's own, as the board draws it, and a
+# state file that cannot be read names nobody it can be kept for.
+refused=""
+board_handback() {
+	local keep="" root owner
+	[ -z "$refused" ] && [ -n "$sid" ] || return 0
+	case "$sid" in */* | .*) return 0 ;; esac
+	# Must match the root board-index.sh and board.sh resolve.
+	if [ -n "${SLUICE_BOARD_DIR:-}" ]; then
+		root="$SLUICE_BOARD_DIR"
+	elif [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+		root="$CLAUDE_CONFIG_DIR/sluice/board"
+	elif [ -n "${HOME:-}" ]; then
+		root="$HOME/.claude/sluice/board"
+	else
+		return 0
+	fi
+	[ -f "$root/sessions/$sid.json" ] || return 0
+	[ -n "$resolved" ] || resolve_run_tree
+	if [ -n "$run_tree" ] && owner="$(jq -r '.session // empty' "$run_tree/.sluice/run.json" 2>/dev/null)" \
+		&& [ "$owner" = "$sid" ]; then
+		keep="--keep-deep"
+	fi
+	bash "$here/board-index.sh" handback "$sid" $keep >/dev/null 2>&1 || true
+}
+trap board_handback EXIT
+
 [ "$active" = "true" ] && exit 0
 [ -d "$cwd" ] || exit 0
 
@@ -175,6 +275,7 @@ entry_nudge() {
 
 	mkdir -p "$root/nudged" 2>/dev/null || true
 	: >"$root/nudged/$sid" 2>/dev/null || true
+	refused=1
 	jq -n '{
 		decision: "block",
 		reason: "sluice: this session has changed the tree since it opened and no channel was ever announced, so the work is running with none of the rules that its shape calls for and nothing to meter it from. Invoke the sluice skill now, route what you have been doing, and say which channel it is. If it genuinely changed nothing you own (a scratch file, or an edit that was not yours), say so and stop; this will not ask twice."
@@ -225,6 +326,7 @@ verify_gate() {
 	[ -f "$moved_tree/.sluice/verified" ] && recorded="$(sed -n '1p' "$moved_tree/.sluice/verified" 2>/dev/null)"
 	[ "$recorded" = "$now" ] && return 0
 
+	refused=1
 	jq -n --arg channel "$channel" '{
 		decision: "block",
 		reason: ("sluice: this \($channel) session has changed the tree and no passing check is recorded against it as it stands now, so the handback would carry a change nothing has proved. Run the check that proves it through the recorder: status.sh verify -- <cmd> (the tests, the build, whatever exercises this change). If no check can cover it (docs, config), record why: status.sh verify --none \"<reason>\". Then hand back.")
@@ -305,6 +407,7 @@ test_gate() {
 
 	# Paths land in a reason the harness prints, so control bytes are stripped
 	# as the run guard strips them from the topic and tree.
+	refused=1
 	jq -n --arg paths "$missing" --arg base "$base" '{
 		decision: "block",
 		reason: ("sluice: this session changed existing tests in a way that asks less of the code (an edited or removed assertion, a deleted test, a skip or focus marker), and nothing records why: "
@@ -320,50 +423,9 @@ fi
 
 [ -f "$STATUS" ] || exit 0
 
-# The run the session's own tree answers for, and only that: the state beside
-# it, or the state it forwarded into a worktree when `move` sent the run on
-# without the session. status.sh also lets a tree with no run of its own read
-# the main worktree's, and that one is not taken here: a Stop in such a tree may
-# be an unrelated session, and a remedy printed to it would reach into somebody
-# else's run.
-#
-# The forward is read here rather than left to status.sh's resolution because
-# the two questions differ. Resolution answers "which run can this tree read",
-# which is the right question for a render and the wrong one for a refusal. The
-# tree named in the note is then passed as `--dir`, so what follows asks about
-# one named tree and carries no layout knowledge of its own.
-#
-# The run this session opened in a worktree it never entered is its own too,
-# found through the pointer `init` left at the main tree, and it comes ahead of
-# the forward: the forward names whichever run was moved last, which with
-# several controllers in the main tree may be another session's.
-top="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)"
-[ -n "$top" ] || top="$cwd"
-session_tree=""
-case "$sid" in
-	"" | */* | .*) ;;
-	*)
-		main="$(git -C "$cwd" worktree list --porcelain 2>/dev/null | sed -n '1s/^worktree //p')"
-		[ -n "$main" ] && [ -f "$main/.sluice/sessions/$sid" ] \
-			&& IFS= read -r session_tree <"$main/.sluice/sessions/$sid" 2>/dev/null
-		if [ -z "$session_tree" ] || [ ! -f "$session_tree/.sluice/run.json" ] \
-			|| [ "$(jq -r '.session // empty' "$session_tree/.sluice/run.json" 2>/dev/null)" != "$sid" ]; then
-			session_tree=""
-		fi
-		;;
-esac
-if [ -f "$top/.sluice/run.json" ]; then
-	tree="$top"
-elif [ -n "$session_tree" ]; then
-	tree="$session_tree"
-elif [ -f "$top/.sluice/run.at" ]; then
-	tree=""
-	IFS= read -r tree <"$top/.sluice/run.at" 2>/dev/null || exit 0
-	# A note outliving the run it named is stale, not a run to refuse a stop over.
-	[ -n "$tree" ] && [ -f "$tree/.sluice/run.json" ] || exit 0
-else
-	exit 0
-fi
+resolve_run_tree
+[ -n "$run_tree" ] || exit 0
+tree="$run_tree"
 
 run="$(bash "$STATUS" show --json --dir "$tree" 2>/dev/null)" || exit 0
 [ -n "$run" ] || exit 0
@@ -413,6 +475,7 @@ verdict="$(printf '%s' "$run" | jq -c --argjson now "$(date -u +%s)" --arg tree
 # anyone into. What replaces it is the step `move` could not take -- the session
 # following the run -- because a controller guarded here is a controller sitting
 # in the tree its own run left.
+refused=1
 printf '%s' "$verdict" | jq 2>/dev/null '{
 	decision: "block",
 	reason: ("sluice: the deep run \(.topic) is \(.progress) done with tasks still to go and nothing marked blocked or paused, so ending the turn here hands a live run back with nothing for your partner to decide. Still open: \(.open)."

package/skills/sluice/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "sluice",
-  "version": "0.25.5",
-  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
+  "version": "0.26.1",
+  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [