@iceinvein/agent-skills 0.15.1 → 0.17.0

package/dist/cli/index.js

@@ -299,6 +299,9 @@ function validateManifest(data) {
     if (a.claudeHookScript !== undefined && typeof a.claudeHookScript !== "string") {
       return { ok: false, error: "'activation.claudeHookScript' must be a string" };
     }
+    if (a.claudeStopScript !== undefined && typeof a.claudeStopScript !== "string") {
+      return { ok: false, error: "'activation.claudeStopScript' must be a string" };
+    }
   }
   return { ok: true, manifest: d };
 }
@@ -522,6 +525,51 @@ async function unwireSessionStartHook(settingsPath, skillName, directive) {
   await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
 `);
 }
+async function wireStopHook(settingsPath, skillName, scriptPath) {
+  let settings = {};
+  if (existsSync2(settingsPath)) {
+    settings = await Bun.file(settingsPath).json();
+  }
+  if (!settings.hooks)
+    settings.hooks = {};
+  if (!settings.hooks.Stop)
+    settings.hooks.Stop = [];
+  const command = `if [ -f ${shq(scriptPath)} ]; then bash ${shq(scriptPath)}; fi`;
+  let found = false;
+  for (const group of settings.hooks.Stop) {
+    for (const hook of group.hooks ?? []) {
+      if (hook.skill !== skillName)
+        continue;
+      found = true;
+      hook.command = command;
+    }
+  }
+  if (!found) {
+    settings.hooks.Stop.push({ hooks: [{ type: "command", command, skill: skillName }] });
+  }
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
+async function unwireStopHook(settingsPath, skillName) {
+  if (!existsSync2(settingsPath))
+    return;
+  const settings = await Bun.file(settingsPath).json();
+  const stop = settings.hooks?.Stop;
+  if (!stop)
+    return;
+  const filtered = stop.map((group) => ({ hooks: (group.hooks ?? []).filter((h) => h.skill !== skillName) })).filter((group) => group.hooks.length > 0);
+  if (filtered.length === 0) {
+    delete settings.hooks.Stop;
+  } else {
+    settings.hooks.Stop = filtered;
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
 var claudeAdapter = {
   name: "claude",
   async install(cwd, manifest, files, activation) {
@@ -584,6 +632,13 @@ var claudeAdapter = {
         installed.push(".claude/settings.json");
       }
     }
+    if (activation === "global" && manifest.activation?.claudeStopScript && config.bundleRoot) {
+      const settingsPath = join2(cwd, ".claude/settings.json");
+      await wireStopHook(settingsPath, manifest.name, join2(cwd, config.bundleRoot, manifest.activation.claudeStopScript));
+      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));
@@ -646,6 +701,9 @@ var claudeAdapter = {
       const settingsPath = join2(cwd, ".claude/settings.json");
       await unwireSessionStartHook(settingsPath, manifest.name, manifest.activation.claudeHookDirective);
     }
+    if (manifest.activation?.claudeStopScript) {
+      await unwireStopHook(join2(cwd, ".claude/settings.json"), manifest.name);
+    }
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "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.16.1"
+    "version": "0.18.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -155,7 +155,9 @@ there at all, which `references/deep-channel.md` handles separately. Review that
 turns out to be missing is only actionable while the plan can still change.
 
 All three answers go into `run.json` and the run record before Task 1's first
-edit, the answer in the first and the reason in the second. Those rows are what
+edit, the answer in the first and the reason in the second, and both files
+open inside the worktree once it is cut, not in the main tree before it
+exists. Those rows are what
 discharge pre-flight, not the approval: one reply arrives for several
 obligations, so a "yes" with no rows behind it signed off the plan and nothing
 else.
@@ -167,9 +169,14 @@ something, not quietly ship without one, and the run ends: `status.sh final`
 when the plan's own review clears, `status.sh close` once the work is no longer
 yours to act on, after a local merge, when the branch is left as it stands, or
 when an open PR lands, not when it opens. A run left open reads as live to the
-statusline and blocks the next one. The SessionStart hook prints a live run at every session start,
-compaction and resume included, so a run you did not start is one you were
-shown, not one you have to remember.
+statusline and blocks the next one. The SessionStart hook prints a live run at
+every session start, compaction and resume included, so a run you did not
+start is one you were shown, not one you have to remember. A Stop hook refuses,
+once per turn, to end a turn while a `deep` run in this tree is past pre-flight
+with tasks still to go and nothing `blocked` or paused:
+`references/deep-channel.md` says why a run never ends a turn between
+pre-flight and the handback, and `status.sh pause --reason` is how one stands
+still on purpose.
 
 ## Conflicts
 

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

@@ -89,9 +89,14 @@ in follows from who has to read it.
 and commit, its tier, its `Model` mark and its `Flips` line, and the answers
 pre-flight settled. `scripts/status.sh` writes and reads it, and
 `references/status.md` carries the commands and the statusline segment that
-makes a run visible without anyone asking. Open it with `init` when you open the
-record, seed the rows with `scripts/plan.sh import <plan>` rather than typing a
-command per task, then flip each task as it moves. It carries the ids, the names,
+makes a run visible without anyone asking. Open it with `init` when you open
+the record, which is after pre-flight and inside the tree the work runs in, the
+worktree when pre-flight bought one: a run opened in the main tree before the
+worktree exists lives where every later session's `init` collides with it, and
+that session cannot tell an abandoned run from yours. One already stranded
+there moves with `status.sh move --to <worktree>`. Seed the rows with
+`scripts/plan.sh import <plan>` rather than typing a command per task, then
+flip each task as it moves. It carries the ids, the names,
 the flip, the model marks and the tiers, the last of these floored off `Touches`
 and the contract graph rather than guessed. Import is safe to re-run: a status, a
 review mark or a ratified model already recorded is left alone and a tier is only
@@ -144,10 +149,11 @@ mode has exited and the plan is written. One enforced gate does not collapse two
 stops into one; it only makes the first of them hold.
 
 **The harness's plan file is not the artifact.** It belongs to the mode and not
-to the run. On approval, write the design to `docs/specs/YYYY-MM-DD-<topic>.md`,
-the plan to `docs/plans/YYYY-MM-DD-<topic>.md`, and open the run record and
-`run.json`. Those are the durable files, the ones a session resuming next week
-reads, and none of them is the one you drafted in.
+to the run. On approval, write the design to `docs/specs/YYYY-MM-DD-<topic>.md`
+and the plan to `docs/plans/YYYY-MM-DD-<topic>.md`. The run record and
+`run.json` open after pre-flight, in the tree the work runs in, for the reason
+the run record section gives. Those are the durable files, the ones a session
+resuming next week reads, and none of them is the one you drafted in.
 
 Where plan mode is unavailable, the prose stop is what you have and it is the
 same stop: end the turn on the design and let the next instruction start the
@@ -215,9 +221,27 @@ is the declared schedule the dispatch rules reject.
 If one of the two has only one live answer, say which and ask the other. A stop
 down to a single question is still a stop.
 
-**Write the answers down before Task 1's first edit.** Both files:
-`status.sh preflight` for the answers, the run record for the reason each one
-went that way. That pair is what discharges pre-flight, rather than the
+**Write the answers down before Task 1's first edit, in the tree the work runs
+in.** The order on the instruction that follows the stop: cut the worktree
+first, when that was the answer, through the harness's worktree tool. A fresh
+worktree branches from the remote's default branch, so nothing uncommitted or
+unpushed in the main tree comes across, and `docs/` may not exist there yet.
+Move the design and plan into it yourself, each into its own directory since
+the two share a basename and one `mv` into one directory would leave the plan
+where the design was:
+
+```
+mkdir -p <worktree>/docs/specs <worktree>/docs/plans
+mv docs/specs/YYYY-MM-DD-<topic>.md <worktree>/docs/specs/
+mv docs/plans/YYYY-MM-DD-<topic>.md <worktree>/docs/plans/
+```
+
+The main tree is then clean and the worktree holds the only copy. Then `init`,
+`plan.sh import` and `status.sh preflight` from inside it; then the record
+with the reason each answer went that way; then commit design, plan and record
+there, on the branch the work is on rather than on master. Both files carry the
+answers: `status.sh preflight` for what was decided, the run record for why.
+That pair is what discharges pre-flight, rather than the
 approval you got, and the distinction is the whole point: a stop
 that carries the plan and pre-flight together has one reply for two obligations,
 so a bare "yes" satisfies the plan and leaves no trace either way of the
@@ -265,6 +289,22 @@ reads the run state rather than the plan: it sees what has actually landed.
   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
+  message with no tool call in it ends the turn, whatever it says, and a run
+  handed back that way stands still until your partner notices, which
+  overnight is the next morning. So an announcement rides in the same message
+  as the dispatch it announces, a wave's completion is followed in the same
+  message by `status.sh ready` and the next dispatch, and "T4 goes next" is
+  never the last thing a message says. The turns that do end are the two
+  stops, a task marked `blocked` because it genuinely needs your partner, and
+  the handback. Everything else that has to wait on them goes through one of
+  those two doors: a finding still open after three review rounds marks its
+  task `blocked`, and re-dispatching it flips the row back to `active` when
+  your partner has answered; a mid-run request for a dispatch, or a
+  show-or-say offer, is a pause, `status.sh pause --reason "<why>"`, so the reason is on disk and
+  the Stop hook lets you go, with `resume` when it moves again. The hook
+  refuses once per turn and then lets the next attempt through, so it is a
+  nudge with the state in it rather than a wall: the rule is yours to keep.
 - **Label the dispatch `T<n>: <task name>`.** The harness lists running agents
   under whatever label the dispatch gave them, so labelled by task that list
   reads as the plan and labelled anything else it reads as a row of anonymous
@@ -293,9 +333,11 @@ reads the run state rather than the plan: it sees what has actually landed.
 - Isolate the workspace before a multi-task plan: the harness's worktree
   tool, not `git worktree` yourself. Implementing straight onto main or
   master needs your partner's say-so, which pre-flight is where you got, and
-  it forecloses concurrent implementers for the whole run. The run state
-  follows the set rather than the tree, so a worktree cut after the plan still
-  reads the rows the plan seeded and flips them where you are watching.
+  it forecloses concurrent implementers for the whole run. Cut it before the
+  run opens, so the state lives in it. A worktree cut after `init` still reads
+  the main tree's run, so nothing breaks for you, but the run stays in the main
+  tree where the next session to start a `deep` run finds it blocking `init`;
+  `status.sh move --to <worktree>` puts it where it belongs.
 - **The agent that built the task commits it**, once its own tests pass, and
   only the paths in its `Touches`. Never `git add -A`: the tree is shared, and
   on a branch you did not isolate it holds work that is not this task's. The

package/skills/sluice/references/review.md

@@ -37,7 +37,8 @@ offer, so neither is that pass.
 Send findings back to the agent that wrote the code: it already holds the
 task and its reasoning, memory you would otherwise rebuild. Three rounds is
 the cap, and a finding still open when the third one ends is structural, not
-local, so stop there and hand it to your partner.
+local, so stop there and hand it to your partner; in `deep`, mark the task
+`blocked` first, which is what lets that stop through.
 
 Receiving a finding: check it against the codebase before acting, and argue
 back with specifics when it is wrong. Agreeing just to move things along is

package/skills/sluice/references/show-or-say.md

@@ -3,7 +3,8 @@
 This is never offered at the start. What triggers it is a specific moment in
 the conversation: a question arrives that turns on how something looks rather
 than on what it means. Offer then, in a message carrying nothing else, and
-wait. Plenty of conversations never raise such a question, and in those the
+wait; inside a `deep` run, `status.sh pause --reason` first, since the Stop
+hook otherwise reads that wait as a stalled run. Plenty of conversations never raise such a question, and in those the
 offer is simply never made.
 
 Apply the test to each question rather than deciding once: could you settle

package/skills/sluice/references/status.md

@@ -21,13 +21,18 @@ bash <skill-dir>/scripts/status.sh preflight --review "tier 3 only" --model "6 o
 bash <skill-dir>/scripts/status.sh show
 bash <skill-dir>/scripts/status.sh ready
 bash <skill-dir>/scripts/status.sh final
+bash <skill-dir>/scripts/status.sh move --to <worktree>
+bash <skill-dir>/scripts/status.sh pause --reason "waiting on the API key"
+bash <skill-dir>/scripts/status.sh resume
 bash <skill-dir>/scripts/status.sh line --full
 bash <skill-dir>/scripts/status.sh close
 ```
 
-`--dir <path>` reads another tree, which is what the statusline uses; it names
-a tree in the set rather than a state file, so a worktree resolves to the same
-run as the tree it was cut from. Statuses
+`--dir <path>` reads another tree, which is what the statusline uses. A tree
+with a run of its own is read as itself; one with none resolves to the main
+worktree of its set, which is the tree a worktree is cut from and not the
+controller's own worktree, so once the run lives there `--dir <implementer
+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
@@ -44,8 +49,16 @@ which is the row the debt count counts.
 
 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
-already on the row is kept. Pass `--base` when the implementer's tree is
-neither.
+already on the row is kept. Issued from the controller's tree that is the
+controller's HEAD, which is what an implementer worktree cut from that branch
+starts at, so the default is right at dispatch. Where the implementer's tree
+has moved on, pass `--base $(git -C <implementer worktree> rev-parse --short
+HEAD)` rather than `--dir` that tree: with the run in your worktree, `--dir`
+pointed at the implementer's resolves to the main tree and finds no run.
+
+`init` reports any other run live in a tree of the same set, without refusing:
+two sessions in two worktrees is legal, and a run stranded in the main tree
+beside a fresh one in a worktree looks the same until someone says so.
 
 Every write stamps `updated`. Past a day since the last one, `show` and the
 statusline both say how long the run has sat idle, because a finished plan
@@ -69,37 +82,35 @@ that `.gitignore` if you want a run tracked; it is only written when absent.
 
 ## Worktrees
 
-Ignoring itself is what makes the run invisible to a worktree unless something
-is done about it, and a `deep` run makes worktrees after the plan is written:
-`git worktree add` gives the implementer a clean checkout, and an ignored
-directory is not in a checkout. Read from the tree it was called in, the run
-the plan seeded would be absent from every implementer, `init` there would
-start a second run nothing else reads, and the worktree would take that state
-with it when it went.
-
-So a tree with no run of its own anchors on the main worktree of its set, and
-the set's run covers it: the statusline renders the controller's run in every
-implementer's window, and a flip issued from any of those trees lands where
-every other one is watching. A tree's own run comes first, though. `init`
-always lands in the tree it is given, and every other command reads that
-tree's state when it has one, so two sessions working independently in two
-worktrees of one repo each keep their own run and neither is shown the
-other's. Anchored unconditionally, as this once was, the first `init` in the
-set took over every other session's statusline and refused every other `init`.
-A submodule anchors on its own checkout, not the superproject's, and a
-directory that is no git work tree keeps its run exactly where it sits.
+The run lives with the controller: in the worktree the work runs in when
+pre-flight bought one, in the main tree otherwise. Implementers never read or
+write it, the controller flips every row, so nothing an implementer does
+depends on seeing the run from its own worktree, and two sessions working
+independently in two worktrees of one repo each keep their own run with
+neither shown the other's.
+
+`init` therefore always lands in the tree it is given, and every other command
+reads that tree's own state when it has one. A tree with none falls back to the
+main worktree of its set, which is what keeps a session working before this
+rule existed, run in the main tree and worktree cut afterwards, reading the run
+it started. That run stays in the main tree, where it blocks the next
+session's `init`; `move --to <worktree>` relocates it, refusing a destination
+that already holds a run or that is not a work tree of the same repository. A
+submodule anchors on its own checkout, not the superproject's, and a directory
+that is no git work tree keeps its run exactly where it sits.
 
 One file for several writers is one file to contend on, so `init`, `task`,
-`preflight`, `final` and `close` take a lock first: two flips issued at the
-same moment from different trees would otherwise have the later write built on
-a snapshot taken before the earlier one landed, dropping that row without
-saying so. The lock
+`preflight`, `final`, `pause`, `resume`, `close` and `move` take a lock first, `move` taking the
+destination tree's as well as its own: two flips issued at the same moment
+from different trees would otherwise have the later write built on a snapshot
+taken before the earlier one landed, dropping that row without saying so. The lock
 carries its holder's pid, so a killed run is broken through rather than waited
 out. Reads take nothing, state being installed through a rename, which is what
 keeps `line` cheap enough to render on.
 
 Open it with `init` when you open the run record, at the same point and for the
-same reason, then seed the rows with `plan.sh import <plan>` rather than a
+same reason, and in the same tree: after pre-flight, inside the worktree when
+one was bought. Then seed the rows with `plan.sh import <plan>` rather than a
 command per task. The ids, names, the flip, the `Model` marks and the tiers are
 all fixed the moment the plan is written and are already in the file, so typing
 them again is transcription with a chance of error in it.
@@ -234,6 +245,33 @@ start, that a run not being continued was left open and wants `close`. A tree
 with no run prints nothing. The reading-back rule above still stands; this is
 the harness doing it at the one moment memory has just been cut.
 
+## On stopping
+
+`scripts/stop-guard.sh` is the Stop hook a global install wires. When the model
+tries to end its turn it reads the run in the session's own tree, the git
+top level of the session's working directory, and refuses, with a reason, when
+a `deep` run there is past pre-flight, has tasks still `todo`, `active` or
+`review`, and nothing is `blocked` or paused. The reason says what to do
+instead: dispatch the next wave in the same message, mark the task that needs
+your partner `blocked`, `pause --reason` and say so, or `close` a run that is
+not this session's work. Every real stop is let through: no run in the
+session's tree (the main-tree fallback other commands use is not taken here,
+since a Stop in a runless worktree may be an unrelated session), a channel
+other than `deep`, pre-flight not yet recorded, a blocked task, a paused run,
+every task done, a run idle for a day, and a turn where the harness says a
+stop hook already fired, which is what keeps it from looping. That last rule
+means it refuses once per turn and lets the next attempt through: a nudge, not
+a wall. The gate keys on the git top level of the session's working
+directory and nothing else, so the run has to live in the tree the session
+works in: open it after the worktree is cut, or `move` it there and then enter
+that worktree, since `move` relocates the run and not the session, and a run
+moved out from under a session still sitting in the main tree leaves that
+session unguarded for the rest of the run.
+
+`pause --reason <text>` records why a run is standing still; `show` and the
+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.
+
 ## Statusline
 
 This is the part that makes a run visible without anyone asking. Give it rows of
@@ -263,11 +301,12 @@ 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 holds no state file of its own:
-there `.git` is a regular file naming the tree it was cut from, and the script
-resolves the run from it. 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.
+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.
 
 `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

package/skills/sluice/scripts/status.sh

@@ -16,6 +16,9 @@
 #   status.sh show [--json]
 #   status.sh ready
 #   status.sh final
+#   status.sh move --to <tree>
+#   status.sh pause --reason <text>
+#   status.sh resume
 #   status.sh line [--full]
 #   status.sh close
 #
@@ -24,7 +27,8 @@
 # directory ignores itself, so no project needs a .gitignore line for it.
 #
 # Exit: 0 ok, 1 the state could not be written, 2 no live run, 3 a run is
-# already live, 4 bad arguments, 5 jq missing, 6 the state file is unreadable.
+# already live (here, or at move's destination), 4 bad arguments, 5 jq missing,
+# 6 the state file is unreadable.
 # `line` is exempt and always exits 0 in silence, because a statusline renders
 # on every keystroke and has nowhere to put an error.
 #
@@ -40,7 +44,7 @@ err() { echo "status.sh: $*" >&2; }
 
 usage() {
 	echo "usage:" >&2
-	sed -n '/^#   status.sh init/,/^# 5 jq missing/p' "$0" | sed 's/^# \{0,2\}//' >&2
+	sed -n '/^#   status.sh init/,/unreadable\.$/p' "$0" | sed 's/^# \{0,2\}//' >&2
 }
 
 # A flag's value has to be checked before `shift 2`, not after. Bash refuses to
@@ -146,7 +150,8 @@ if [ "$SUB" = "line" ]; then
 			    (.channel // "?"),
 			    "\($done)/\(.tasks | length)",
 			    ([.tasks[]? | select(.status == "active") | "▸T\(.id)"] | first // empty),
-			    ([.tasks[]? | select(.status == "blocked") | "!T\(.id)"] | first // empty)
+			    ([.tasks[]? | select(.status == "blocked") | "!T\(.id)"] | first // empty),
+			    (if .paused then "paused" else empty end)
 			  ] | join(" ")
 		' "$STATE" 2>/dev/null || exit 0
 		exit 0
@@ -229,6 +234,7 @@ if [ "$SUB" = "line" ]; then
 		       ] | join_parts)
 		    + (if $clock == "" then "" else "   " + paint("2"; $clock) end)
 		    + (if $idle == "" then "" else " " + paint("2"; "·") + " " + paint("33"; $idle) end)
+		    + (if .paused then " " + paint("2"; "·") + " " + paint("33"; "paused") else "" end)
 		  ),
 		  # The flip is drawn as a rule before its task: everything left of it is
 		  # inert and safe to leave landed, everything right of it is not. That is
@@ -269,9 +275,9 @@ require_readable() {
 # runs in having to add a line to its own .gitignore. `*` matches the .gitignore
 # file too, so the whole directory drops out of `git status`. An existing file is
 # left alone, and a tree that refuses the write still gets its run.
-mk_dir() { # <directory to create under .sluice>
+mk_dir() { # <directory to create under .sluice> [<tree whose .sluice it is, default $DIR>]
 	mkdir -p "$1" || { err "could not create $1"; exit 1; }
-	local ignore="$DIR/.sluice/.gitignore"
+	local ignore="${2:-$DIR}/.sluice/.gitignore"
 	[ -e "$ignore" ] || printf '*\n' >"$ignore" 2>/dev/null || true
 }
 
@@ -313,30 +319,31 @@ write_state() {
 # later one. A lock whose holder is gone is broken rather than waited out, and
 # one whose holder is alive is waited on for a bounded time and then reported,
 # because a command that hangs in a status bar is worse than one that fails.
-lock_taken=0
+# `move` spans two trees and holds both locks, so the locks taken are a list.
+LOCKS_TAKEN=()
 release_lock() {
-	[ "$lock_taken" -eq 1 ] || return 0
-	rm -rf "$LOCK"
-	lock_taken=0
+	local l
+	for l in "${LOCKS_TAKEN[@]+"${LOCKS_TAKEN[@]}"}"; do rm -rf "$l"; done
+	LOCKS_TAKEN=()
 }
 
-take_lock() {
-	local waited=0 holder
-	while ! mkdir "$LOCK" 2>/dev/null; do
-		holder="$(cat "$LOCK/pid" 2>/dev/null)"
+take_lock() { # [<lock path>, default the run's own]
+	local lock="${1:-$LOCK}" waited=0 holder
+	while ! mkdir "$lock" 2>/dev/null; do
+		holder="$(cat "$lock/pid" 2>/dev/null)"
 		if [ -n "$holder" ] && ! kill -0 "$holder" 2>/dev/null; then
-			rm -rf "$LOCK"
+			rm -rf "$lock"
 			continue
 		fi
 		if [ "$waited" -ge 100 ]; then
-			err "another sluice command has held $LOCK for 10s; remove it if nothing is running"
+			err "another sluice command has held $lock for 10s; remove it if nothing is running"
 			exit 1
 		fi
 		sleep 0.1
 		waited=$((waited + 1))
 	done
-	printf '%s\n' "$$" >"$LOCK/pid" 2>/dev/null || true
-	lock_taken=1
+	printf '%s\n' "$$" >"$lock/pid" 2>/dev/null || true
+	LOCKS_TAKEN+=("$lock")
 	trap release_lock EXIT INT TERM
 }
 
@@ -361,10 +368,25 @@ case "$SUB" in
 		take_lock
 		if [ -f "$STATE" ] && [ "$FORCE" -eq 0 ]; then
 			live="$(jq -r '.topic // "?"' "$STATE" 2>/dev/null || echo "?")"
-			err "a run is already live (topic: $live); pass --force to replace it"
+			err "a run is already live (topic: $live). If it is yours and your work runs in a worktree, put it there: status.sh move --to <worktree>. If it is another session's, leave it and start yours from your own worktree. If it is finished, status.sh close; --force replaces it"
 			exit 3
 		fi
 
+		# Other trees in the set may hold runs of their own, legitimately or as
+		# one stranded before its session moved into a worktree. Said, never
+		# refused: the session starting here cannot tell which, and the one that
+		# can is the owner.
+		if [ "$(git -C "$DIR" rev-parse --is-inside-work-tree 2>/dev/null)" = "true" ]; then
+			here="$(cd "$DIR" && pwd -P)"
+			git -C "$DIR" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | while IFS= read -r tree; do
+				[ -d "$tree" ] || continue
+				[ "$(cd "$tree" && pwd -P)" != "$here" ] || continue
+				[ -f "$tree/.sluice/run.json" ] || continue
+				other="$(jq -r '.topic // "?"' "$tree/.sluice/run.json" 2>/dev/null || echo "?")"
+				err "note: another run is live in $tree (topic: $other); if it is this work stranded before a worktree was cut, move it there instead"
+			done
+		fi
+
 		jq -n \
 			--arg topic "$TOPIC" \
 			--arg channel "$CHANNEL" \
@@ -563,6 +585,7 @@ 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)
 			+ ["final review  " + (if .final_review then "done" else "pending" end)]
@@ -664,6 +687,80 @@ case "$SUB" in
 		jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.final_review = $now' "$STATE" | write_state
 		;;
 
+	pause)
+		REASON=""
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--reason) need_value --reason $# "${2-}"; REASON="$2"; shift 2 ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+		[ -n "$REASON" ] || { err "pause needs --reason <text>: a pause nobody can read the reason for is a stall"; exit 4; }
+		require_run
+		take_lock
+		require_readable
+
+		# A deliberate handback mid-run, which the stop guard otherwise refuses.
+		# The reason is the whole point: it is what the partner reads in `show`
+		# and what the next session reads to know why the run is standing still.
+		jq --arg reason "$REASON" '.paused = $reason' "$STATE" | write_state
+		;;
+
+	resume)
+		[ $# -eq 0 ] || { err "resume takes no arguments"; exit 4; }
+		require_run
+		take_lock
+		require_readable
+		jq 'del(.paused)' "$STATE" | write_state
+		;;
+
+	move)
+		TO=""
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--to) need_value --to $# "${2-}"; TO="$2"; shift 2 ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+		[ -n "$TO" ] || { err "move needs --to <tree>"; exit 4; }
+		[ -d "$TO" ] || { err "no such directory: $TO"; exit 4; }
+		TO="$(cd "$TO" && pwd -P)"
+		require_run
+
+		# The destination is taken as given rather than anchored: the whole point
+		# is to put the run in one particular tree, the controller's worktree,
+		# which anchoring would resolve straight back to the main tree it is
+		# leaving. It does have to be a work tree of the same set: a typo would
+		# otherwise strand the run at a path no command issued from the tree
+		# resolves, and the only way back is knowing where it went.
+		src_common="$(git -C "$DIR" rev-parse --git-common-dir 2>/dev/null)"
+		dst_common="$(git -C "$TO" rev-parse --git-common-dir 2>/dev/null)"
+		dst_top="$(git -C "$TO" rev-parse --show-toplevel 2>/dev/null)"
+		if [ -n "$src_common" ]; then
+			src_common="$(cd "$DIR" && cd "$src_common" 2>/dev/null && pwd -P)"
+			dst_common="$([ -n "$dst_common" ] && cd "$TO" && cd "$dst_common" 2>/dev/null && pwd -P)"
+			if [ -z "$dst_common" ] || [ "$dst_common" != "$src_common" ] || [ "$dst_top" != "$TO" ]; then
+				err "$TO is not a work tree of the same repository as $(cd "$DIR" && pwd -P); move only relocates a run between trees of one set"
+				exit 4
+			fi
+		fi
+		[ "$TO" != "$(cd "$DIR" && pwd -P)" ] || { err "the run is already in $TO"; exit 4; }
+
+		# Both trees' locks: a racing init in the destination takes that tree's
+		# lock, not this one's, and the mv would land on top of what it wrote.
+		take_lock
+		mk_dir "$TO/.sluice" "$TO"
+		take_lock "$TO/.sluice/run.lock"
+		DEST_STATE="$TO/.sluice/run.json"
+		if [ -f "$DEST_STATE" ]; then
+			there="$(jq -r '.topic // "?"' "$DEST_STATE" 2>/dev/null || echo "?")"
+			err "a run is already live in $TO (topic: $there); close it there first"
+			exit 3
+		fi
+		mv "$STATE" "$DEST_STATE" || { err "could not move $STATE to $DEST_STATE"; exit 1; }
+		echo "moved $(jq -r '.topic // "run"' "$DEST_STATE" 2>/dev/null || echo run) to $TO"
+		;;
+
 	close)
 		[ $# -eq 0 ] || { err "close takes no arguments"; exit 4; }
 		require_run

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Stop hook: refuse to end the turn in the middle of a deep run.
+#
+# A turn ends the moment a message carries no tool call, and a run handed back
+# that way has nothing in it for the partner to decide: it just stands still
+# until they notice, which overnight is the next morning. So when a deep run is
+# past pre-flight, has tasks still to go, and nothing is marked blocked or
+# paused, the stop is refused with a reason saying what to do instead.
+#
+# Every stop that is a real stop is let through: no run, a channel other than
+# deep, pre-flight not yet answered (that stop is owed), a blocked task, a run
+# paused on purpose with `status.sh pause --reason`, every task done (the
+# handback), a run idle for a day, a run that lives in another tree than the
+# session's, and any attempt where the harness says a stop hook already fired
+# this turn, which is what keeps this from looping. One refusal per turn, then:
+# a nudge with the state in it rather than a wall.
+#
+# Reads the harness's stop JSON on stdin for `cwd` and `stop_hook_active`. To
+# refuse, prints {"decision":"block","reason":...} on stdout. Always exits 0.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+STATUS="$here/status.sh"
+
+# jq first: without it nothing below can run, and the stdin read that follows
+# has a worst case worth not paying for nothing.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Byte-wise and bounded, for the reason session-start.sh gives: bash 3.2 drops
+# a timed-out partial read, and an inherited open stdin must not hang the stop.
+input=""
+n=0
+if [ ! -t 0 ]; then
+	while IFS= read -r -n 1 -t 2 c; do
+		if [ -z "$c" ]; then input="$input
+"; else input="$input$c"; fi
+		# Appending a byte at a time is quadratic, and -t bounds each byte rather
+		# than the total. Real stop JSON is under a kilobyte; past this the input
+		# is not the harness's and is not worth reading on.
+		n=$((n + 1))
+		[ "$n" -lt 65536 ] || break
+	done
+fi
+
+cwd="$PWD"
+active="false"
+if [ -n "$input" ]; then
+	got="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+	[ -n "$got" ] && cwd="$got"
+	active="$(printf '%s' "$input" | jq -r '.stop_hook_active // false' 2>/dev/null || echo false)"
+fi
+[ "$active" = "true" ] && exit 0
+[ -d "$cwd" ] || exit 0
+[ -f "$STATUS" ] || exit 0
+
+# The session's own tree, and only that. status.sh lets a tree with no run of
+# its own read the main worktree's, for a controller that moved after init; a
+# Stop in such a tree may be an unrelated session, and a remedy printed to it
+# would reach into somebody else's run. So the run has to sit in the tree the
+# session's cwd belongs to, or there is nothing here to guard.
+top="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)"
+[ -n "$top" ] || top="$cwd"
+[ -f "$top/.sluice/run.json" ] || exit 0
+
+run="$(bash "$STATUS" show --json --dir "$top" 2>/dev/null)" || exit 0
+[ -n "$run" ] || exit 0
+
+# One JSON object out, read back with jq: the topic is user text, and word
+# splitting it would truncate at the first space and glob on the rest.
+verdict="$(printf '%s' "$run" | jq -c --argjson now "$(date -u +%s)" '
+	(.tasks // []) as $t
+	| ([$t[] | select(.status == "done")] | length) as $done
+	| ([$t[] | select(.status == "blocked")] | length) as $blocked
+	| ([$t[] | select(.status == "todo" or .status == "active" or .status == "review")] | length) as $open
+	| ((.updated // .started // "" | try fromdateiso8601 catch 0) as $u
+	   | if $u == 0 then 0 else (($now - $u) / 3600 | floor) end) as $idle_h
+	| if (.channel // "") != "deep" then {block: false}
+	  elif ((.preflight // {}) | length) == 0 then {block: false}
+	  elif .paused then {block: false}
+	  elif ($t | length) == 0 then {block: false}
+	  elif $blocked > 0 then {block: false}
+	  elif $open == 0 then {block: false}
+	  # 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")}
+	  end
+' 2>/dev/null)" || exit 0
+
+[ "$(printf '%s' "$verdict" | jq -r '.block' 2>/dev/null)" = "true" ] || exit 0
+
+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. Continue: run status.sh ready and dispatch the next wave in this same message. If a task genuinely needs them, mark it: status.sh task <id> --status blocked. If the run has to stand still for a reason, record it: status.sh pause --reason \"<why>\", then say so and stop. If this run is not the work you were asked to do, it was left open: status.sh close.")
+}'
+exit 0

package/skills/sluice/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "sluice",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "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",
@@ -29,6 +29,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"
+    "claudeHookScript": "scripts/session-start.sh",
+    "claudeStopScript": "scripts/stop-guard.sh"
   }
 }