@iceinvein/agent-skills 0.23.4 → 0.23.7

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