@iceinvein/agent-skills 0.17.0 → 0.18.1

package/dist/cli/index.js

@@ -302,6 +302,20 @@ function validateManifest(data) {
     if (a.claudeStopScript !== undefined && typeof a.claudeStopScript !== "string") {
       return { ok: false, error: "'activation.claudeStopScript' must be a string" };
     }
+    if (a.claudeStatuslineScript !== undefined && typeof a.claudeStatuslineScript !== "string") {
+      return { ok: false, error: "'activation.claudeStatuslineScript' must be a string" };
+    }
+    const claudeBundleRoot = d.install.claude?.bundleRoot;
+    if (claudeBundleRoot === undefined) {
+      for (const field of ["claudeHookScript", "claudeStopScript", "claudeStatuslineScript"]) {
+        if (a[field] !== undefined) {
+          return {
+            ok: false,
+            error: `'activation.${field}' is resolved against 'install.claude.bundleRoot', which is not set`
+          };
+        }
+      }
+    }
   }
   return { ok: true, manifest: d };
 }
@@ -570,6 +584,49 @@ async function unwireStopHook(settingsPath, skillName) {
   await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
 `);
 }
+function statusLineCommand(scriptPath) {
+  return `if [ -f ${shq(scriptPath)} ]; then bash ${shq(scriptPath)}; fi`;
+}
+function ownsStatusLine(command, skillName, scriptPath) {
+  if (typeof command !== "string")
+    return false;
+  if (scriptPath !== undefined && command === statusLineCommand(scriptPath))
+    return true;
+  const shape = /^if \[ -f '(.*)' \]; then bash '(.*)'; fi$/.exec(command);
+  if (shape === null || shape[1] !== shape[2])
+    return false;
+  return shape[1].includes(`/skills/${skillName}/`);
+}
+async function wireStatusLine(settingsPath, skillName, scriptPath) {
+  let settings = {};
+  if (existsSync2(settingsPath)) {
+    settings = await Bun.file(settingsPath).json();
+  }
+  const existing = settings.statusLine;
+  if (existing !== undefined && existing !== null) {
+    if (!ownsStatusLine(existing?.command, skillName, scriptPath))
+      return;
+  }
+  const command = statusLineCommand(scriptPath);
+  if (existing?.type === "command" && existing?.command === command)
+    return;
+  settings.statusLine = { type: "command", command };
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
+async function unwireStatusLine(settingsPath, skillName, scriptPath) {
+  if (!existsSync2(settingsPath))
+    return;
+  const settings = await Bun.file(settingsPath).json();
+  if (settings.statusLine === undefined || settings.statusLine === null)
+    return;
+  if (!ownsStatusLine(settings.statusLine?.command, skillName, scriptPath))
+    return;
+  delete settings.statusLine;
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
 var claudeAdapter = {
   name: "claude",
   async install(cwd, manifest, files, activation) {
@@ -639,6 +696,13 @@ var claudeAdapter = {
         installed.push(".claude/settings.json");
       }
     }
+    if (activation === "global" && manifest.activation?.claudeStatuslineScript && config.bundleRoot) {
+      const settingsPath = join2(cwd, ".claude/settings.json");
+      await wireStatusLine(settingsPath, manifest.name, join2(cwd, config.bundleRoot, manifest.activation.claudeStatuslineScript));
+      if (!installed.includes(".claude/settings.json")) {
+        installed.push(".claude/settings.json");
+      }
+    }
     if (config.postinstall && config.bundleRoot) {
       const scriptPath = join2(cwd, config.bundleRoot, config.postinstall);
       const result = runScript(scriptPath, join2(cwd, config.bundleRoot));
@@ -704,6 +768,9 @@ var claudeAdapter = {
     if (manifest.activation?.claudeStopScript) {
       await unwireStopHook(join2(cwd, ".claude/settings.json"), manifest.name);
     }
+    if (manifest.activation?.claudeStatuslineScript && config.bundleRoot) {
+      await unwireStatusLine(join2(cwd, ".claude/settings.json"), manifest.name, join2(cwd, config.bundleRoot, manifest.activation.claudeStatuslineScript));
+    }
   }
 };
 
@@ -1143,8 +1210,9 @@ async function removeSkill(cwd, skillName) {
       const fullPath = join7(cwd, file);
       if (existsSync6(fullPath)) {
         await unwireSessionStartHook(fullPath, skillName);
+        await unwireStatusLine(fullPath, skillName);
       }
-      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, only removing '${skillName}'s SessionStart hook from it; any MCP server entries it owns were not touched.`);
+      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, removing '${skillName}'s SessionStart hook and status line from it; any MCP server entries it owns were not touched.`);
       continue;
     }
     const fullPath = join7(cwd, file);
@@ -1236,8 +1304,9 @@ async function removeSkill2(cwd, skillName) {
       const fullPath = join8(cwd, file);
       if (existsSync7(fullPath)) {
         await unwireSessionStartHook(fullPath, skillName);
+        await unwireStatusLine(fullPath, skillName);
       }
-      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, only removing '${skillName}'s SessionStart hook from it; any MCP server entries it owns were not touched.`);
+      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, removing '${skillName}'s SessionStart hook and status line from it; any MCP server entries it owns were not touched.`);
       continue;
     }
     const fullPath = join8(cwd, file);

package/package.json

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

package/skills/index.json

@@ -283,7 +283,7 @@
     "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 seven 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. Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.18.0"
+    "version": "0.19.1"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/references/deep-channel.md

@@ -180,8 +180,15 @@ your sign-off and Task 1 begins.
 **Review.** Name the tasks the table below sends to a reviewer, each with the
 trigger that qualified it, and say how many of the rest skip with a ledger
 line. Then offer the choice: dispatch a reviewer at each of them, dispatch
-only at tier 3, or hand back with those tasks listed as
-review outstanding. The options are what makes the cost legible.
+only at tier 3, or hand back with the whole tier table skipped. The options are
+what makes the cost legible.
+
+Whichever comes back, record it with `status.sh preflight --review`. That row is
+what turns the tasks it skips into a coverage level rather than a debt: the count
+stays, because the code is the same either way, but `show`, the bar and `close`
+then name it as the level your partner chose. Unrecorded,
+the same tasks read as unreviewed to the end of the run, which is a nag about a
+decision that was already made. `references/status.md` has the two readings.
 "Four of nine need a reviewer" is a decision your partner can price; "I will
 review where appropriate" is not.
 
@@ -251,9 +258,10 @@ intending to, and the questions are still cheap here and unaskable an hour from
 now.
 
 A session that forbids subagents does not skip this; it changes what the
-review options are. Skipping it is how "review outstanding" first appears in
+review options are. Skipping it is how the unreviewed count first appears in
 the closing summary, at the one moment your partner can no longer do anything
-about it.
+about it, and with no answer on file it stays worded as a debt rather than as
+the level anyone chose.
 
 ## Dispatch rules
 
@@ -285,8 +293,10 @@ reads the run state rather than the plan: it sees what has actually landed.
   implementer back into them. `done --commit <sha> --reviewed` when the review
   clears, or `done --commit <sha>` alone for a tier 0 task, which was owed a
   stat read and no dispatch, and for a task whose dispatch pre-flight declined;
-  the debt count counts the second kind and not the first. That state outlives
-  compaction; your memory doesn't.
+  the count counts the second kind and not the first. A declined dispatch is
+  meant to show up there, because the count describes the artifact rather than
+  the decision, and the recorded pre-flight answer is what makes it read as
+  coverage rather than debt. That state outlives compaction; your memory doesn't.
 - Each task goes to a fresh agent carrying the brief below and nothing this
   session accumulated. What you hold is yours to hold, not theirs.
 - **The run never ends a turn between pre-flight and the handback.** A
@@ -405,9 +415,10 @@ One thing does not change: the work still owes a review. Reading your own diff
 is not one, and the table below still names which tasks needed the stronger
 tier. Name those tasks at pre-flight, not at handback, so the choice of what
 to do about them is still open: shrink the plan, take the flip on its own, or
-accept the gap knowingly. Whatever is left then gets listed as review
-outstanding rather than review passed, and twice is the cap on saying so here
-too: `references/review.md` has that rule. A `deep` run that ships with nobody
+accept the gap knowingly. Record the answer with `preflight --review` and say at
+the handback what was covered and how, rather than claiming those tasks passed a
+review; twice is the cap on saying so here too, and `references/review.md` has
+that rule. A `deep` run that ships with nobody
 having read it has become a `fast` run with a design document attached, and
 your partner is entitled to know that while it can still change the plan.
 
@@ -471,12 +482,17 @@ dispatch, the tasks are interleaved rather than ordered, and reordering them
 is cheaper than reviewing them.
 
 **Mark each review with `status.sh task <id> --reviewed` when it comes back.**
-What that buys is a count of what this table promised and nobody delivered: tasks
-that are done, that qualified for a dispatch, and that carry no mark. `show` and
-the statusline both carry it from the moment it exists, which is the whole point.
-Unmarked, the count sits permanently non-zero and stops being a signal, and
-"review outstanding" goes back to first appearing in the closing summary, at the
-one moment your partner can no longer do anything about it.
+What that buys is a count of the tasks this table sent to a reviewer and nobody
+marked: done, qualified for a dispatch, and carrying no mark. `show` and the
+statusline both carry it from the moment it exists, which is the whole point.
+Unmarked, the count sits permanently non-zero and stops being a signal, and it
+goes back to first appearing in the closing summary, at the one moment your
+partner can no longer do anything about it.
+
+With the pre-flight answer on file the same count is the coverage this run
+bought, worded as such and drawn dim. Without it the count is a debt and stays in
+the warning colour. Neither wording shrinks it: what changes is whether the
+number reads as spent or as owed.
 
 Reviews are reads, so they are always parallel. Every review a wave earned
 goes out in one message, and they run while the next wave's implementers work:

package/skills/sluice/references/finish.md

@@ -43,12 +43,16 @@ the one list of them. In order:
 2. The ledger, `scripts/run-stats.sh --tests "<that result>"`, pasted
    unedited. `references/meter.md`
 3. In `deep`, `status.sh show`, pasted, so "four of nine, task five blocked,
-   two unreviewed, final review pending" is on the page rather than in your
-   account of it. `references/status.md`
+   two done at tier 1+ with no dispatch, final review pending" is on the page
+   rather than in your account of it. `references/status.md`
 4. One clause on review: dispatched and clear, dispatched with findings still
    open, or not dispatched and why. In `deep` that clause covers the per-task
-   tiers and the final review separately, because the debt count carries one
-   and not the other.
+   tiers and the final review separately, because the count carries one and not
+   the other. Where pre-flight priced the level, say what was covered and how,
+   not that review is outstanding: "reviewed at the level you chose, a
+   controller stat read plus the final whole-plan pass rather than a per-task
+   dispatch" is the accurate line, and it is a coverage level rather than a
+   debt. Where nothing was priced, it is a debt and says so.
 5. The three options, and nothing after them.
 
 A `deep` run closes when the work stops being yours to act on: after a local

package/skills/sluice/references/status.md

@@ -36,16 +36,20 @@ worktree>` finds nothing. Statuses
 are `todo`, `active`, `review`, `done` and `blocked`. A new id needs `--name`;
 after that every call is a bare flip, so keeping it current costs one command
 per transition rather than a paragraph. `close` archives the run under
-`.sluice/archive/`, prints one line saying what it archived, progress, review
-debt and whether the final review landed, and frees the tree for the next one.
+`.sluice/archive/`, prints one line saying what it archived, progress, how many
+tasks shipped without a dispatch and whether the final review landed, and frees
+the tree for the next one.
 
 The controller writes every row. An implementer reports its SHA in its reply
 and touches nothing under `.sluice/`; the brief in `references/deep-channel.md`
 says so to it. `active` is the dispatch, `review` is the commit in and a
 reviewer out, with the task's paths still held because a finding may send the
 implementer back into them, and `done` is the end: with `--reviewed` when a
-review cleared it, without when the tier owed one and pre-flight declined it,
-which is the row the debt count counts.
+review cleared it, without when the tier qualified for one and pre-flight
+declined it, which is the row the no-dispatch count counts. Declining is meant
+to show up there: the count describes the artifact, not the decision, and a
+chosen skip that erased itself would leave a number that only ever recorded
+accidents.
 
 A task going `active` with no `--base` takes the HEAD of the tree the command
 is pointed at, `--dir` if given and the current tree otherwise, once; a base
@@ -148,8 +152,8 @@ have gone that way. Those are different claims.
 ## Reading it back
 
 `show` prints the whole run: channel, topic, how many tasks are done, the plan
-and record paths, how long it has sat idle once that passes a day, the review
-debt, the final review, the pre-flight answers, and a row per task with its
+and record paths, how long it has sat idle once that passes a day, the tasks
+that shipped without a dispatch, the final review, the pre-flight answers, and a row per task with its
 base, commit, tier and model. Run it after compaction instead of reconstructing the
 run from what you remember, and run it in the message that hands the work back,
 where "four of nine, task five blocked" is a fact your partner can act on.
@@ -170,9 +174,9 @@ from what the whole bar would occupy, gaps included, rather than from the task
 count: keyed off the count alone the schedule was not monotonic, and thirty tasks
 at two cells each ran wider than twelve at three.
 
-**A done task still owed a review trails the review glyph**, `▰▰▨` against
-`▰▰▰`. Debt then reads in position rather than only as a count at the end of the
-row, which is the difference between knowing how much there is and knowing where.
+**A done task that got no dispatch trails the review glyph**, `▰▰▨` against
+`▰▰▰`. The gap then reads in position rather than only as a count at the end of
+the row, which is the difference between knowing how much there is and knowing where.
 Tier 0 was never owed a dispatch, so it reads as plainly done. On a plan long
 enough to narrow cells to one, there is no trailing cell to give up and the
 positional reading stops: the count in the third row is then the only carrier,
@@ -186,16 +190,40 @@ flips and `import` clears a stale one, so the bar is only ever asked to draw the
 single legal case.
 
 The third row carries the progress count, whichever task wants attention, and the
-review debt. A blocked task displaces the active one there, being the one of the
-two worth interrupting for, and a `+n` follows when more than one task shares that
-state, since a plan running four wide has four actives by design.
+no-dispatch count. A blocked task displaces the active one there, being the one of
+the two worth interrupting for, and a `+n` follows when more than one task shares
+that state, since a plan running four wide has four actives by design.
 
 Mark a review with `task <id> --reviewed` when a reviewer comes back. What that
-buys is the debt count: a task that is done, that the tier table owed a dispatch,
-and that nobody marked. Tier 0 is excluded, having only ever been owed a stat
-read. Without it "review outstanding" first appears in the closing summary, at
-the one moment your partner can no longer do anything about it, and `show` and
-the statusline both carry it from the moment it exists.
+buys is the count: a task that is done, that the tier table qualified for a
+dispatch, and that nobody marked. Tier 0 is excluded, having only ever been owed
+a stat read. Without it that count first appears in the closing summary, at the
+one moment your partner can no longer do anything about it, and `show` and the
+statusline both carry it from the moment it exists.
+
+## Coverage against debt
+
+The same count reads two ways, and which one it gets turns on whether
+`preflight --review` has an answer on file.
+
+With an answer, the level was priced at the stop and the tasks it skipped were
+spent rather than forgotten. `show` calls it `coverage`, with the answer itself
+on the `pre-flight` row three lines below rather than repeated beside the count;
+the bar says `⟲ 9 at the chosen level` dim rather than in the warning colour, and
+`close` says `9 at the chosen review level`. That is a fact about how
+far review reached, not a thing still to do, and a run that keeps calling it
+outstanding is nagging your partner about a decision they already made.
+
+With no answer on file, nobody priced anything. `show` calls it `unreviewed`, the
+bar and `close` say the same, and the warning colour stays: the dispatches the
+tier table promised are genuinely owed, and the absence of a pre-flight answer is
+the evidence that nobody weighed them.
+
+What never changes is the number. Nine tasks that shipped without a second pair
+of eyes carry the same risk whether the skip was chosen or forgotten, and the
+count is there to say how far coverage reached. Erasing a chosen skip would turn
+it into a measure of diligence, which is not what anyone reads it for. So the
+word moves and the number does not.
 
 ## The next wave
 
@@ -272,6 +300,24 @@ session unguarded for the rest of the run.
 statusline carry it, and `resume` clears it. A pause with no reason is refused,
 since the reason is the only thing that separates a pause from a stall.
 
+## Free text
+
+Every value a command stores is later drawn onto a terminal: by the statusline,
+by `show`, by the SessionStart hook and by the stop guard's refusal. A control
+character in one is not text there, it is an instruction the terminal obeys, and
+task names are model-written and routinely pasted out of issue titles. `ESC[2J`
+in a name clears the screen on every render for as long as the run is open; a
+carriage return walks the cursor back over the row just drawn.
+
+So every flag value is refused if it carries one, with exit 4 naming the flag,
+rather than being quietly stripped: a name that is not the name the caller
+passed is its own surprise, and no legitimate value has ever needed a control
+byte. `plan.sh import` writes task names through the same door and inherits it.
+
+The renders drop them as well. State written before the check existed, or edited
+by hand, is an input like any other, and the only control bytes a render should
+emit are the colour sequences it writes itself.
+
 ## Statusline
 
 This is the part that makes a run visible without anyone asking. Give it rows of
@@ -279,20 +325,11 @@ its own rather than a segment among the badges: it then costs nothing when no ru
 is live and contends with nothing for width when one is, which is what lets the
 bar be wide and the task carry its name rather than only its number.
 
-Capture it wherever the statusline command builds its other lines, keyed off the
-state file existing so a session with no run spawns no process at all:
+Capture it wherever the statusline command builds its other lines, passing the
+directory the session is in and nothing else:
 
 ```bash
-sluice_line=""
-if [ -n "$cwd" ] && { [ -f "$cwd/.sluice/run.json" ] || [ -f "$cwd/.git" ]; }; then
-  for sluice_sh in "$cwd/.claude/skills/sluice/scripts/status.sh" \
-                   "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/sluice/scripts/status.sh" \
-                   "$HOME/.claude/skills/sluice/scripts/status.sh"; do
-    [ -f "$sluice_sh" ] || continue
-    sluice_line=$(bash "$sluice_sh" line --full --dir "$cwd" 2>/dev/null)
-    break
-  done
-fi
+sluice_line=$(bash "$HOME/.claude/skills/sluice/scripts/statusline.sh" --dir "$cwd" 2>/dev/null)
 ```
 
 then print it last, after whatever else the command emits:
@@ -301,22 +338,46 @@ then print it last, after whatever else the command emits:
 if [ -n "$sluice_line" ]; then printf '%s\n' "$sluice_line"; fi
 ```
 
-The gate is two tests because a linked worktree may hold no state file of its
-own and still belong to a set with a run: there `.git` is a regular file naming
-the tree it was cut from, and the script falls back to that tree. A worktree
-with its own run passes the first test. In a tree with no run and no worktree
-behind it `.git` is a directory, so both tests fail and no process is spawned,
-which is the property the gate is for.
+`$cwd` is `workspace.current_dir` from the JSON the harness sends on stdin.
+Substitute the install path: `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` where a
+session may set one, or `$cwd/.claude/skills/sluice/scripts/statusline.sh` for a
+project-local install.
+
+Those two lines are the whole contract, and they are deliberately empty of
+judgement. Whether a run is visible from a given directory is a question about
+this skill's layout, and the answer has moved twice: once when the run anchored
+on the worktree set, once when a deep run began opening inside the implementer
+worktree. Both times a caller carrying the test went stale and stopped drawing
+without saying so, which is indistinguishable from no run being live. A caller
+that contributes only a path cannot go stale, and every install brings
+`statusline.sh` up to date behind it.
+
+`scripts/statusline.sh` holds what used to sit in the caller: it resolves the
+directory it was given, walks up looking for a state file or a worktree marker,
+stops at an ordinary tree root or at `$HOME` with neither, and dispatches to
+`status.sh line --full` only when there is something to draw. The walk is what
+lets a session sitting in a subdirectory see the run in its tree, which testing
+the session's own directory alone never did, and it resolves symlinks first
+because a linked directory's lexical parents lead away from the tree rather than
+up it.
+
+It answers only whether a run might be visible from here, never where one is.
+`status.sh` stays the single authority on that, and is handed the directory the
+caller passed rather than the one the walk stopped at. A gate that were ever
+narrower than the resolution behind it would blank the bar on a run that
+resolves perfectly well, which is the failure this whole arrangement exists to
+end, so it errs permissive: a wasted spawn is the acceptable direction.
+
+The gate is kept rather than dropped because it costs about 8ms against the 33ms
+an ungated `status.sh` pays to work out there is no run, and the common case on
+any machine is a tree with no run at all. Depth barely moves it, 7.7ms stopping
+at a `.git` directory against 8.4ms walking to the root, because 5.4ms of that
+is the bash spawn and the walk itself forks nothing.
 
 `if` rather than `[ ... ] &&`: as the last command of a statusline script the
 short form makes it exit 1 on every render with no run live, which is the common
 case. `%s` rather than `%b`: the render already carries real escape bytes, and
-`%b` would reinterpret a backslash inside a task name. `$cwd` is
-`workspace.current_dir` from the JSON the harness sends on stdin. The configured
-config dir is read before the default because a session started with
-`CLAUDE_CONFIG_DIR` set installs the skill there, which is the one place a
-`$HOME/.claude` lookup will not find it; the two paths collapse to one when the
-variable is unset, at the price of a second `[ -f ]`. It renders as:
+`%b` would reinterpret a backslash inside a task name. It renders as:
 
 ```
 ⧗ deep · sluice-cross-harness   ◷ 38m
@@ -324,6 +385,25 @@ variable is unset, at the price of a second `[ -f ]`. It renders as:
   2/9 done · !T6 model tiers rather than model names +1 · ⟲ 1 unreviewed
 ```
 
+On a machine with no status line at all there is nothing to paste into, so the
+install claims the empty `statusLine` slot and points it at
+`scripts/statusline-command.sh`, a complete command that reads the harness JSON
+on stdin and draws the run and nothing else. A slot already holding someone
+else's command is never touched, on install or on removal, and the one the
+install claimed is given back when the skill is removed, including on the
+removal path that has no manifest to read.
+
+Three things make claiming a single shared slot safe. The command is written
+guarded by its own script's existence, as the hook commands are, so a bundle
+that moved leaves the bar silent rather than running a path that is gone on
+every keystroke. Ownership is matched on the whole command and never as a
+substring, so a command with ours composed into it belongs to whoever composed
+it and is left whole. And the path it matches carries the skill's own directory,
+so the second skill to declare a statusline cannot take the first one's slot on
+install or delete it on removal. That is why the bundled
+command draws no prompt of its own: it exists for the empty slot, not to compete
+for a full one, so with no run live it prints nothing rather than an empty row.
+
 The colour comes out of the script rather than being applied by the caller,
 because the mapping from state to colour belongs next to the state. A caller that
 coloured the line itself would have to re-derive each cell's meaning from its

package/skills/sluice/scripts/postinstall.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Postinstall: tell whoever just installed the skill how to put the run on their
+# status bar, and touch nothing.
+#
+# Wiring it automatically would mean finding their statusline script, and the
+# only thing settings.json holds is the shell command that runs it
+# (`bash "$HOME/.claude/statusline-command.sh"`). Recovering a path from that is
+# parsing a shell string and hoping, on a file the installer never created. So
+# this prints the two lines and leaves the editing to a person.
+#
+# Runs with the bundle root as its working directory, which puts settings.json
+# two levels up whether the install went to $HOME/.claude or to a
+# $CLAUDE_CONFIG_DIR somewhere else. Always exits 0: a postinstall that fails
+# reports an error against an install that in fact succeeded.
+
+set -uo pipefail
+
+BUNDLE="$PWD"
+SETTINGS="$BUNDLE/../../settings.json"
+RENDER="$BUNDLE/scripts/statusline.sh"
+
+[ -f "$SETTINGS" ] || exit 0
+[ -f "$RENDER" ] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Nothing is said to someone with no statusline configured. Either the install
+# claimed the empty slot, in which case the branch below reports it, or this is
+# a session-mode install that wires nothing, in which case there is no file to
+# paste into and no instruction worth printing.
+CONFIGURED="$(jq -r '.statusLine.command // empty' "$SETTINGS" 2>/dev/null || true)"
+[ -n "$CONFIGURED" ] || exit 0
+
+RENDER="$(cd "$(dirname "$RENDER")" && pwd)/$(basename "$RENDER")"
+
+# The slot points at the bundled command: the install claimed it and there is
+# nothing for anyone to paste. Say so rather than print instructions that would
+# have them edit a file they do not have.
+case "$CONFIGURED" in
+	*skills/sluice/scripts/statusline-command.sh*)
+		echo
+		echo "sluice: your status line now shows a live run. It draws nothing until one"
+		echo "is open, and uninstalling gives the setting back."
+		exit 0
+		;;
+esac
+
+cat <<EOF
+
+sluice: to show a live run on your status line, add these to your statusline
+command. The first goes wherever it builds its other lines, the second last of
+all, after everything else it prints:
+
+  sluice_line=\$(bash "$RENDER" --dir "\$cwd" 2>/dev/null)
+
+  if [ -n "\$sluice_line" ]; then printf '%s\\n' "\$sluice_line"; fi
+
+\$cwd is workspace.current_dir from the JSON the harness sends on stdin. Those
+two lines carry no knowledge of where a run lives, so they stay correct as this
+skill changes; every install updates the script behind them.
+EOF

package/skills/sluice/scripts/status.sh

@@ -60,6 +60,16 @@ need_value() { # <flag> <remaining $#> <candidate>
 	case "$3" in
 		--*) err "$1 needs a value, but the next argument is the flag $3"; exit 4 ;;
 	esac
+	# Every value this script stores is later drawn onto a terminal, by the
+	# statusline, by `show` and by the SessionStart hook. A control byte in one is
+	# not text there, it is a command the terminal obeys: ESC[2J clears the screen
+	# on every render for as long as the run is open, and a carriage return walks
+	# the cursor back over the row just drawn. Refused rather than stripped,
+	# because a name that is not the name the caller passed is its own surprise,
+	# and no legitimate value has ever needed one.
+	case "$3" in
+		*[[:cntrl:]]*) err "$1 value contains a control character, which a terminal would act on rather than print"; exit 4 ;;
+	esac
 }
 
 # A word from a space-separated set. Keeps validation in one place so every
@@ -171,24 +181,31 @@ if [ "$SUB" = "line" ]; then
 	jq -r \
 		--argjson now "$(date -u +%s)" \
 		--arg esc "$(printf '\033')" '
+		# The state file is an input like any other: it predates the check on the
+		# way in, or was hand-edited, so what it holds is not known to be drawable.
+		# Everything this render emits deliberately is an SGR colour sequence, so any
+		# other control byte reaching the terminal came from the state, and is dropped
+		# here rather than obeyed.
+		def clean: if type == "string" then gsub("[\u0000-\u001f\u007f]"; "") else . end;
 		def paint($c; $t): "\($esc)[\($c)m\($t)\($esc)[0m";
 		def join_parts: map(select(. != null and . != "")) | join(" \($esc)[2m·\($esc)[0m ");
-		# Done splits in two. A task that is done and was owed a review nobody has
-		# marked keeps the done shape but trails the review glyph, so the debt reads
-		# in position rather than only as a count. Tier 0 was never owed a dispatch,
-		# so it is plainly done.
-		def cellgroup($w):
+		# Done splits in two. A task that is done and got no dispatch keeps the done
+		# shape but trails the review glyph, so where the gap is reads in position
+		# rather than only as a count. Tier 0 was never owed a dispatch, so it is
+		# plainly done. $mark is the marker colour: a level pre-flight chose is a
+		# fact about coverage and draws dim, one nobody priced is a warning.
+		def cellgroup($w; $mark):
 			(.status == "done"
 			 and (.tier // 0) >= 1
-			 and (.reviewed // false) == false) as $owed
+			 and (.reviewed // false) == false) as $nodispatch
 			| (if   .status == "done"    then ["32", "▰"]
 			   elif .status == "active"  then ["96", "◈"]
 			   elif .status == "review"  then ["33", "▨"]
 			   elif .status == "blocked" then ["91", "▮"]
 			   else ["2", "▱"]
 			   end) as $s
-			| if $owed and $w > 1
-			  then paint($s[0]; ($s[1] * ($w - 1))) + paint("33"; "▨")
+			| if $nodispatch and $w > 1
+			  then paint($s[0]; ($s[1] * ($w - 1))) + paint($mark; "▨")
 			  else paint($s[0]; ($s[1] * $w))
 			  end;
 
@@ -203,7 +220,12 @@ if [ "$SUB" = "line" ]; then
 		   else 1 end) as $w
 		| (if $w > 1 then " " else "" end) as $gap
 		| ([.tasks[]? | select(.status == "done")] | length) as $done
-		| ([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $debt
+		| ([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $nodispatch
+		# A pre-flight review answer on file means the stop happened and the level
+		# was priced, so the tasks it skipped were spent rather than forgotten. The
+		# count is the same either way, because the gap in the code is the same; the
+		# word is not, and "unreviewed" on a level someone chose reads as a nag.
+		| (((.preflight.review // "") | length) > 0) as $priced
 		| [.tasks[]? | select(.status == "blocked")] as $blockedAll
 		| [.tasks[]? | select(.status == "active")] as $activeAll
 		| ($blockedAll | first) as $blocked
@@ -230,7 +252,7 @@ if [ "$SUB" = "line" ]; then
 		     end) as $idle
 		| ( paint("1;96"; "⧗") + " "
 		    + ([ paint("1;96"; (.channel // "?")),
-		         paint("2"; (.topic // ""))
+		         paint("2"; (.topic // "" | clean))
 		       ] | join_parts)
 		    + (if $clock == "" then "" else "   " + paint("2"; $clock) end)
 		    + (if $idle == "" then "" else " " + paint("2"; "·") + " " + paint("33"; $idle) end)
@@ -241,14 +263,17 @@ if [ "$SUB" = "line" ]; then
 		  # what the flip means, and a name in the header could not say it.
 		  ( "  " + ([ .tasks[]?
 		              | (if .flips then paint("95"; "┃") + $gap else "" end)
-		                + cellgroup($w)
+		                + cellgroup($w; (if $priced then "2" else "33" end))
 		            ] | join($gap)) ),
 		  ( "  " + ([ paint("1"; "\($done)/\(.tasks | length)") + " done",
-		              (if   $blocked then paint("1;91"; "!T\($blocked.id) \($blocked.name // "")")
-		               elif $active  then paint("96"; "▸T\($active.id)") + " " + ($active.name // "")
+		              (if   $blocked then paint("1;91"; "!T\($blocked.id) \($blocked.name // "" | clean)")
+		               elif $active  then paint("96"; "▸T\($active.id)") + " " + ($active.name // "" | clean)
 		               else "" end)
 		              + (if $attn > 1 then paint("2"; " +\($attn - 1)") else "" end),
-		              (if $debt > 0 then paint("33"; "⟲ \($debt) unreviewed") else "" end)
+		              (if $nodispatch == 0 then ""
+		               elif $priced then paint("2"; "⟲ \($nodispatch) at the chosen level")
+		               else paint("33"; "⟲ \($nodispatch) unreviewed")
+		               end)
 		            ] | join_parts)
 		  )
 	' "$STATE" 2>/dev/null || exit 0
@@ -562,7 +587,12 @@ case "$SUB" in
 		# than silently reading as the whole value.
 		jq -r --argjson now "$(date -u +%s)" '
 			def dash: if . == null or . == "" then "-" else . end;
-			def cell($w): tostring
+			# Same reason as the statusline render: state written before the check
+			# on the way in, or edited by hand, holds bytes a terminal would act on
+			# rather than print. Every table cell passes through `cell`, so the
+			# table is covered there; the lines built outside it clean their own.
+			def clean: if type == "string" then gsub("[\u0000-\u001f\u007f]"; "") else . end;
+			def cell($w): tostring | clean
 				| if length > $w then .[0:$w - 1] + "…"
 				  else . + (" " * ($w - length))
 				  end;
@@ -570,9 +600,9 @@ case "$SUB" in
 			                      ($c[3] | cell(9)), ($c[4] | cell(9)), ($c[5] | cell(4)),
 			                      $c[6]] | join(" "));
 			([.tasks[]? | select(.status == "done")] | length) as $done
-			| ["sluice \(.channel) · \(.topic) · \($done)/\(.tasks | length) done"]
-			+ ["plan          \(.plan | dash)"]
-			+ ["record        \(.record | dash)"]
+			| ["sluice \(.channel | clean) · \(.topic | clean) · \($done)/\(.tasks | length) done"]
+			+ ["plan          \(.plan | dash | clean)"]
+			+ ["record        \(.record | dash | clean)"]
 			# Past a day since the last write the run is idle, and that is said
 			# here because a stale run blocks the next init and nothing else
 			# would name it.
@@ -585,13 +615,22 @@ case "$SUB" in
 			            else ["idle          \($h / 24 | floor)d\($h % 24)h since the last write"]
 			            end
 			     end)
-			+ (if .paused then ["paused        \(.paused)"] else [] end)
-			+ (([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $debt
-			   | if $debt == 0 then [] else ["unreviewed    \($debt) done, owed a review the tier table promised"] end)
+			+ (if .paused then ["paused        \(.paused | clean)"] else [] end)
+			# Same count, two readings. A pre-flight review answer on file says the
+			# level was priced at the stop, so what it skipped is the coverage of this
+			# run. With no answer on file nobody priced anything and the dispatches in
+			# the tier table are still owed. The answer itself is not repeated here:
+			# the pre-flight row below carries it, three lines down.
+			+ (([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $nodispatch
+			   | if $nodispatch == 0 then []
+			     elif ((.preflight.review // "") | length) > 0
+			     then ["coverage      \($nodispatch) done at tier 1+, no dispatch"]
+			     else ["unreviewed    \($nodispatch) done at tier 1+, owed a review and no pre-flight answer"]
+			     end)
 			+ ["final review  " + (if .final_review then "done" else "pending" end)]
 			+ ["pre-flight    " + (
 				if (.preflight // {} | length) == 0 then "not recorded"
-				else [(.preflight | to_entries[] | "\(.key)=\(.value)")] | join("; ")
+				else [(.preflight | to_entries[] | "\(.key | clean)=\(.value | clean)")] | join("; ")
 				end)]
 			+ [""]
 			+ [row(["id", "status", "task", "base", "commit", "tier", "model"])]
@@ -772,9 +811,13 @@ case "$SUB" in
 		# allowed to stop the archive.
 		summary="$(jq -r '
 			([.tasks[]? | select(.status == "done")] | length) as $done
-			| ([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $debt
+			| ([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $nodispatch
+			| (((.preflight.review // "") | length) > 0) as $priced
 			| [ "closed \(.topic // "run"): \($done)/\(.tasks | length) done",
-			    (if $debt > 0 then "\($debt) unreviewed" else empty end),
+			    (if   $nodispatch == 0 then empty
+			     elif $priced then "\($nodispatch) at the chosen review level"
+			     else "\($nodispatch) unreviewed"
+			     end),
 			    "final review \(if .final_review then "done" else "pending" end)"
 			  ] | join(" · ")
 		' "$STATE" 2>/dev/null || true)"

package/skills/sluice/scripts/statusline-command.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# A complete statusline command, for a machine that had none.
+#
+# `statusline.sh` takes a directory; the harness delivers one as JSON on stdin.
+# This bridges the two, and it is what settings.json can be pointed at directly:
+#
+#   "statusLine": { "type": "command", "command": "bash '<this file>'" }
+#
+# It draws the live run and nothing else. Anyone who wants a prompt as well
+# already has a statusline of their own, and the install refuses to overwrite
+# one: this file exists for the empty slot, not to compete for a full one. So
+# with no run live it prints nothing at all rather than an empty row.
+#
+# Always exits 0 in silence on anything it cannot render, for the same reason
+# statusline.sh does: a status bar draws on every keystroke and has nowhere to
+# put an error.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+RENDER="$here/statusline.sh"
+
+[ -f "$RENDER" ] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Bounded, and skipped on a terminal. The harness closes stdin after the JSON,
+# so a read to EOF returns, but nothing here enforces that: read from a pipe
+# nobody closes and an unbounded read hangs, which on a status bar is a bar that
+# never draws and on a hand-run check is a frozen terminal with no explanation.
+# `read` is a builtin, so the bound costs no fork against the gate's budget.
+[ -t 0 ] && exit 0
+input=""
+IFS= read -r -d "" -t 2 input || true
+[ -n "$input" ] || exit 0
+
+# `cwd` is the older spelling of the same field and both are still sent, so it
+# is a fallback rather than a bug. Neither present is not an error worth a row:
+# it means this is not the JSON we were written against.
+dir="$(printf '%s' "$input" | jq -r '.workspace.current_dir // .cwd // empty' 2>/dev/null || true)"
+[ -n "$dir" ] || exit 0
+
+bash "$RENDER" --dir "$dir" 2>/dev/null || exit 0

package/skills/sluice/scripts/statusline.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Statusline render: the whole sluice contribution to a status bar, behind one
+# call. The caller passes the directory the session is in and prints whatever
+# comes back.
+#
+#   statusline.sh [--dir <path>]
+#
+# --dir defaults to $PWD. Always exits 0 in silence on anything it cannot
+# render: a status bar draws on every keystroke and has nowhere to put an error,
+# so a message here would be permanent clutter rather than a report anyone acts
+# on.
+#
+# Why this exists as its own script rather than as a snippet in the caller.
+# Whether a run is visible from a given directory is a question about sluice's
+# own layout, and the answer has changed twice: once when the run anchored on
+# the worktree set, once when a deep run began opening inside the implementer
+# worktree. Each time, a caller carrying the test went stale and simply stopped
+# drawing, silently, because silence is also what it looks like when no run is
+# live. Callers now contribute a path and nothing else, and every install brings
+# this file up to date behind them.
+#
+# The gate is still here rather than dropped: measured on this machine, it costs
+# about 8ms against the 33ms an ungated status.sh pays to work out there is no
+# run, and the common case on any machine is a tree with no run at all. Depth
+# barely moves it -- 7.7ms stopping at a .git directory, 8.4ms walking to the
+# root -- because the bash spawn is 5.4ms of it and the walk forks nothing.
+# It answers only "might a run be visible from here", never "where is it":
+# status.sh stays the single authority on resolution, and this stays a
+# deliberately over-permissive filter in front of it. A filter that were ever
+# narrower than status.sh would blank the bar on a run the code behind it can
+# render, which is the whole class of bug this file exists to end.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+STATUS="$here/status.sh"
+
+DIR="$PWD"
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--dir)
+			# An omitted value would silently make the next flag the directory.
+			[ $# -ge 2 ] && [ "${2#--}" = "$2" ] || exit 0
+			DIR="$2"
+			shift 2
+			;;
+		*) exit 0 ;;
+	esac
+done
+
+[ -d "$DIR" ] || exit 0
+[ -f "$STATUS" ] || exit 0
+
+# Is a run reachable from here at all? Walk up rather than test $DIR alone: a
+# session sitting in a subdirectory of the tree is as entitled to the render as
+# one sitting at its root, and testing only $DIR was a second way for the bar to
+# go blank on a live run.
+#
+# Resolve physically first. A directory reached through a symlink has lexical
+# parents that are not its real ones, and climbing those walks away from the
+# repo instead of up it -- a blank bar on a run status.sh resolves perfectly
+# well, which is this file's own failure mode turned on a new input. `cd`
+# failing here means the path is gone or unreadable, and there is nothing to
+# draw for it.
+d="$(cd "$DIR" 2>/dev/null && pwd -P)" || exit 0
+[ -n "$d" ] || exit 0
+
+# Four answers end the walk. A state file is a run, wherever it was found. A
+# `.git` that is a regular file is a linked worktree or a submodule, which may
+# hold no state of its own and still belong to a set that does, so it is a maybe
+# and status.sh resolves it. A `.git` that is a directory is the top of an
+# ordinary tree with no state beside it, which is a no. So is reaching $HOME:
+# without that stop, one forgotten ~/.sluice/run.json would put a status.sh
+# spawn on every keystroke of every session outside a repo, for a run that
+# resolves to nothing.
+#
+# `${d%/*}` rather than `dirname`, which is not a builtin: a fork per level
+# would put the gate's cost in the same range as the render it is avoiding.
+while :; do
+	[ -f "$d/.sluice/run.json" ] && break
+	[ -f "$d/.git" ] && break
+	[ -d "$d/.git" ] && exit 0
+	[ "$d" = "${HOME:-}" ] && exit 0
+	[ "$d" = "/" ] && exit 0
+	d="${d%/*}"
+	[ -n "$d" ] || d="/"
+done
+
+# $DIR, not the $d the walk stopped at: $d is where the filter gave up looking,
+# which is not the same question as where the run is. status.sh anchors on the
+# worktree set and is the only thing that decides that.
+#
+# `line --full` is silent on everything it cannot read, a missing jq and an
+# unreadable state file included, and exits 0 either way. The render arrives
+# already coloured: the mapping from state to colour belongs next to the state,
+# and a caller that applied it would have to re-derive each cell's meaning from
+# its glyph.
+rendered="$(bash "$STATUS" line --full --dir "$DIR" 2>/dev/null)" || exit 0
+[ -n "$rendered" ] || exit 0
+printf '%s\n' "$rendered"

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

@@ -84,7 +84,11 @@ verdict="$(printf '%s' "$run" | jq -c --argjson now "$(date -u +%s)" '
 	  # A run nobody has written to for a day is a stale run, not a live one;
 	  # refusing its stop would press an abandoned plan on whoever opened here.
 	  elif $idle_h >= 24 then {block: false}
-	  else {block: true, progress: "\($done)/\($t | length)", topic: (.topic // "run")}
+	  # The topic lands in a reason the harness prints, so a control byte in it
+	  # would be acted on by the terminal rather than read. State written before
+	  # status.sh refused those, or edited by hand, can still hold one.
+	  else {block: true, progress: "\($done)/\($t | length)",
+	        topic: (.topic // "run" | gsub("[\u0000-\u001f\u007f]"; ""))}
 	  end
 ' 2>/dev/null)" || exit 0
 

package/skills/sluice/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "sluice",
-  "version": "0.18.0",
+  "version": "0.19.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 seven 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. Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",
@@ -19,7 +19,8 @@
   "install": {
     "claude": {
       "prompt": ".claude/skills/sluice/SKILL.md",
-      "bundleRoot": ".claude/skills/sluice"
+      "bundleRoot": ".claude/skills/sluice",
+      "postinstall": "scripts/postinstall.sh"
     }
   },
   "activation": {
@@ -30,6 +31,7 @@
     "default": "global",
     "claudeHookDirective": "Before acting on a request that changes code, pick a sluice channel and state which one.",
     "claudeHookScript": "scripts/session-start.sh",
-    "claudeStopScript": "scripts/stop-guard.sh"
+    "claudeStopScript": "scripts/stop-guard.sh",
+    "claudeStatuslineScript": "scripts/statusline-command.sh"
   }
 }