genshin-mods 4.4.0 → 4.5.0

package/README.md

@@ -5,7 +5,19 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-A Claude Code plugin of mods: five drawn as one band above the prompt, in the session character's colour (the next steps one press away, what the session is spending with a one-press handoff, recording mode, a goal's task list and clock, and a question before editing a file another session just changed), a delegation guard that refuses any subagent not on haiku and nudges a run of lookups toward a haiku agent, a disk-scan guard that refuses a Bash scan from a root or a home folder, and a whole-index guard that refuses a git command over the whole index while another session shares the checkout.
+A Claude Code plugin of mods. Five mods draw one band above the prompt, in the session character's colour:
+
+- waypoints: the next steps, one press away
+- what the session is spending, with a one-press handoff
+- recording mode
+- a goal's task list and clock
+- a question before an edit to a file that another session just changed
+
+Three guards also run:
+
+- a delegation guard that refuses any subagent not on haiku, and nudges a run of lookups toward a haiku agent
+- a disk-scan guard that refuses a Bash scan from a root or a home folder
+- a whole-index guard that refuses a git command over the whole index while another session shares the checkout
 
 Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/genshin-mods).
 
@@ -19,22 +31,29 @@ Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
-This repository is a Claude Code plugin marketplace named `esposter`:
+This repository is a Claude Code plugin marketplace named `esposter`. Add it, then install the plugin:
 
 ```bash
 claude plugin marketplace add Esposter/Esposter
 claude plugin install genshin-mods@esposter
 ```
 
-`/sins` scores with [TypeSafe](https://typesafe.ai), so it needs a key: the plugin's `typesafe_key` option, the same option [`genshin-persona`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-persona) has, or the `TYPESAFE_API_KEY` variable when the option is empty:
+`/sins` scores with [TypeSafe](https://typesafe.ai). It needs a key. Set the key with one of these:
+
+- the plugin's `typesafe_key` option, the same option as [`genshin-persona`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-persona)
+- the `TYPESAFE_API_KEY` variable, when the option is empty
+
+Set the option at install:
 
 ```bash
 claude plugin install genshin-mods@esposter --config typesafe_key=<key>
 ```
 
-A clone of this repository needs neither command: `.agents/settings.json` enables the plugin at project scope once you trust the repository. With [`genshin-persona`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-persona) installed beside it, the band takes the session character's colour; without it, the game's interface gold.
+A clone of this repository needs neither command. Once you trust the repository, `.agents/settings.json` enables the plugin at project scope.
+
+With [`genshin-persona`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-persona) installed too, the band takes the session character's colour. Without it, the band uses the game's interface gold.
 
-Developing the plugin from a checkout loads the directory itself, with the installed copy disabled so only one of them answers:
+To develop the plugin from a checkout, run these commands in order. They disable the installed copy, so only one copy answers:
 
 ```bash
 claude plugin disable genshin-mods@esposter
@@ -43,19 +62,25 @@ claude --plugin-dir packages/genshin-mods
 
 ## <a name="commands">⌨️ Commands</a>
 
-Each mod is switched by its own slash command; bare, it flips, and the choice is kept across sessions:
-
-| Command                   | What it does                                                                                                                    |
-| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
-| `/commission [on \| off]` | Shows the goal meter while a turn works through a task list                                                                     |
-| `/pulse [on \| off]`      | Keeps the machine watcher running, or stops                                                                                     |
-| `/resin [on \| off]`      | Shows the cache, context, limits and cost row and its warning toast                                                             |
-| `/sins [on \| off]`       | Scores each prompt's seven sins with TypeSafe, drawn as bars in a pane; needs the `typesafe_key` option or `TYPESAFE_API_KEY`   |
-| `/veil [on \| off]`       | Turns recording mode on or off; off by default                                                                                  |
-| `/ward [on \| off]`       | Asks before an edit to a file another session just changed, and refuses a whole-index git command while one shares the checkout |
-| `/waypoints [on \| off]`  | Suggests the next steps after each answered turn, or stops                                                                      |
-
-With the band focused (a click or `ctrl+x tab`), `w`, `c` and `h` warm, compact and hand off, `1` to `3` send a waypoint and `g` opens or closes the whole task list.
+Each mod has its own slash command. With no argument, the command flips the mod. The choice is kept across sessions:
+
+| Command                   | What it does                                                                                                                                |
+| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/commission [on \| off]` | Shows the goal meter while a turn works through a task list                                                                                 |
+| `/pulse [on \| off]`      | Keeps the machine watcher running, or stops                                                                                                 |
+| `/resin [on \| off]`      | Shows the cache, context, limits and cost row and its warning toast                                                                         |
+| `/sins [on \| off]`       | Scores each prompt's seven sins with TypeSafe, drawn as bars in a pane. Needs the `typesafe_key` option or `TYPESAFE_API_KEY`               |
+| `/veil [on \| off]`       | Turns recording mode on or off; off by default                                                                                              |
+| `/ward [on \| off]`       | Asks before an edit to a file another session just changed, and refuses a whole-index git command while another session shares the checkout |
+| `/waypoints [on \| off]`  | Suggests the next steps after each answered turn, or stops                                                                                  |
+
+Focus the band with a click or `ctrl+x tab`. Then press:
+
+- `w`: warm
+- `c`: compact
+- `h`: hand off
+- `1` to `3`: send a waypoint
+- `g`: open or close the whole task list
 
 ## <a name="license">⚖️ License</a>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genshin-mods",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "A Claude Code plugin of mods: five under one band above the prompt (the next steps, the cache and usage with a one-click handoff, recording mode, a goal's task list and a question before editing a file another session just changed) a delegation guard that nudges a run of lookups toward a haiku agent, a disk-scan guard that refuses a Bash scan from a root or a home folder, and a whole-index guard that refuses a git command over the whole index while another session shares the checkout.",
   "keywords": [
     "claude-code",
@@ -36,5 +36,5 @@
     "test": "vitest",
     "validate": "claude plugin validate ."
   },
-  "gitHead": "e1a416c4b91da69cc2aa259b50a4d656f204d272"
+  "gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
 }

package/src/models/CommandRefusal.ts

@@ -0,0 +1,3 @@
+// The refusal for a command's name, the arguments after it and the folder it runs in from the session's ("" for the
+// Session's own), undefined when the command is not one the guard reads
+export type CommandRefusal<T = string> = (name: string, args: string[], directory: string) => T | undefined;

package/src/services/band/getCommissionSummary.ts

@@ -1,12 +1,13 @@
 import type { Commission } from "../../../types";
 
+import { TaskStatus } from "../../models/TaskStatus";
 import { MINUTE_FORMATTER } from "../constants";
 
 const PERCENT_FORMATTER = new Intl.NumberFormat("en", { style: "percent" });
 
 // `goal · 3 of 4 · 75% · 12m`, the clock counting whole minutes from the commission's opening
 export const getCommissionSummary = ({ goal, openedAt, tasks }: Commission, now: number): string => {
-  const done = tasks.filter(({ status }) => status === "completed").length;
+  const done = tasks.filter(({ status }) => status === TaskStatus.Completed).length;
   const elapsedMinutes = Math.floor(
     Temporal.Duration.from({ milliseconds: Math.max(0, now - openedAt) }).total("minutes"),
   );

package/src/services/commission/foldTaskCall.ts

@@ -1,6 +1,7 @@
 import type { CommissionTask } from "../../../types";
 import type { TaskCall } from "../../models/TaskCall";
 
+import { TaskStatus } from "../../models/TaskStatus";
 import { TaskTool } from "../../models/TaskTool";
 
 const DELETED_STATUS = "deleted";
@@ -8,7 +9,7 @@ const DELETED_STATUS = "deleted";
 export const foldTaskCall = (tasks: CommissionTask[], call: TaskCall): CommissionTask[] => {
   switch (call.tool) {
     case TaskTool.TaskCreate:
-      return [...tasks, { id: call.id, status: "pending", subject: call.subject }];
+      return [...tasks, { id: call.id, status: TaskStatus.Pending, subject: call.subject }];
     case TaskTool.TaskUpdate: {
       const { id, status, subject } = call;
       if (status === DELETED_STATUS) return tasks.filter((task) => task.id !== id);

package/src/services/delegation/checkIsLookupCommand.ts

@@ -1,11 +1,5 @@
-import { LEADING_SEGMENT_REGEX, LOOKUP_COMMAND_REGEX, WRITING_LOOKUP_REGEX } from "../constants";
-
-// A session chains `export` and `cd` ahead of its real command, so each leading segment is stripped before the
-// Command's first word is read
-const stripLeadingSegments = (command: string): string => {
-  const rest = command.replace(LEADING_SEGMENT_REGEX, "");
-  return rest === command ? command : stripLeadingSegments(rest);
-};
+import { LOOKUP_COMMAND_REGEX, WRITING_LOOKUP_REGEX } from "../constants";
+import { stripLeadingSegments } from "./stripLeadingSegments";
 
 export const checkIsLookupCommand = (command: string): boolean => {
   const rest = stripLeadingSegments(command);

package/src/services/delegation/stripLeadingSegments.ts

@@ -0,0 +1,8 @@
+import { LEADING_SEGMENT_REGEX } from "../constants";
+
+// A session chains `export` and `cd` ahead of its real command, so each leading segment is stripped before the
+// Command's first word is read
+export const stripLeadingSegments = (command: string): string => {
+  const rest = command.replace(LEADING_SEGMENT_REGEX, "");
+  return rest === command ? command : stripLeadingSegments(rest);
+};

package/src/services/diskScan/getDenyReason.ts

@@ -0,0 +1,7 @@
+import { KNOWN_HOME_LINES } from "./getDiskScanRefusal";
+
+export const getDenyReason = (scanName: string): string =>
+  [
+    `Refused: ${scanName} scans from a root or a home folder, which reads the whole disk for a file whose home is known, and costs minutes of CPU and disk for every agent running. Look where the file lives instead:`,
+    ...KNOWN_HOME_LINES,
+  ].join("\n");

package/src/services/diskScan/getDiskScanRefusal.ts

@@ -1,75 +1,5 @@
-import type { CommandRefusal } from "../shell/getShellRefusal";
-
 import { getShellRefusal } from "../shell/getShellRefusal";
-
-// A root in any spelling is a folder whose scan reads the whole disk: the drive's folders, the users' folders and the
-// Home folder by name, once Windows drive letters and backslashes are read as Git Bash's `/c/...` form
-const ROOT_REGEX =
-  /^(?:\/[a-z]?|\/(?:c\/)?Users(?:\/[^/]+)?|\/home(?:\/[^/]+)?|~|\$HOME|\$\{HOME\}|\$USERPROFILE|%USERPROFILE%)$/u;
-
-const SCAN_COMMANDS: ReadonlySet<string> = new Set(["du", "find", "grep", "ls"]);
-
-// Backslashes become slashes, a drive letter becomes its `/c` folder, and a trailing glob and slash go, so "C:\", "/c/",
-// "C:/" and "/c/*" all name "/c": a folder's glob expands to its entries, whose scan reads the whole folder
-const normalizePath = (token: string) => {
-  const slashed = token.replaceAll("\\", "/");
-  const path = /^[A-Za-z]:/u.test(slashed) ? `/${slashed.charAt(0).toLowerCase()}${slashed.slice(2)}` : slashed;
-  return path.replace(/(?<=\/)\*$/u, "").replace(/(?<=.)\/+$/u, "");
-};
-
-const isRoot = (token: string) => ROOT_REGEX.test(normalizePath(token));
-
-// The long form `--recursive`, which getopt also takes as any prefix of it from `--rec` on, since `--re` names two options
-const isRecursiveLongFlag = (token: string) => token.startsWith("--rec") && "recursive".startsWith(token.slice(2));
-
-// A flag group holding the scan's recursive letter, or the long form: grep takes r or R (`-R`, `-rn`, `-lR`), and ls takes
-// The capital R alone, since its lowercase r sorts in reverse
-const GREP_RECURSIVE_FLAG_REGEX = /^-[a-zA-Z]*[rR]/u;
-const LS_RECURSIVE_FLAG_REGEX = /^-[a-zA-Z]*R/u;
-const isRecursiveFlag = (token: string, shortFlagRegex: RegExp) =>
-  shortFlagRegex.test(token) || isRecursiveLongFlag(token);
-
-// A flag that gives grep its pattern as the next argument, or as the rest of the same one
-const SEPARATE_PATTERN_FLAG_REGEX = /^-[a-zA-Z]*[ef]$|^--(?:regexp|file)$/u;
-const ATTACHED_PATTERN_FLAG_REGEX = /^-[a-zA-Z]*[ef].|^--(?:regexp|file)=/u;
-
-// Grep's flags and search paths: a pattern flag's operand is its pattern and never a flag or a path, every argument
-// After a `--` is a positional one, and with no pattern flag the first positional argument is the pattern
-const readGrepArguments = (args: string[]): { flags: string[]; paths: string[] } => {
-  const flags: string[] = [];
-  const positionals: string[] = [];
-  let hasPatternFlag = false;
-  let isPatternOperand = false;
-  let isOptionEnd = false;
-  for (const arg of args)
-    if (isPatternOperand) isPatternOperand = false;
-    else if (isOptionEnd || !arg.startsWith("-")) positionals.push(arg);
-    else if (arg === "--") isOptionEnd = true;
-    else {
-      flags.push(arg);
-      if (SEPARATE_PATTERN_FLAG_REGEX.test(arg)) {
-        hasPatternFlag = true;
-        isPatternOperand = true;
-      } else if (ATTACHED_PATTERN_FLAG_REGEX.test(arg)) hasPatternFlag = true;
-    }
-  return { flags, paths: hasPatternFlag ? positionals : positionals.slice(1) };
-};
-
-// The scan's name when its arguments start it from a root, undefined when they do not
-const getScanRefusal = (name: string, args: string[]): string | undefined => {
-  if (name === "find" || name === "du") return args.some((arg) => isRoot(arg)) ? name : undefined;
-  if (name === "ls")
-    return args.some((arg) => isRecursiveFlag(arg, LS_RECURSIVE_FLAG_REGEX)) && args.some((arg) => isRoot(arg))
-      ? name
-      : undefined;
-  const { flags, paths } = readGrepArguments(args);
-  return flags.some((flag) => isRecursiveFlag(flag, GREP_RECURSIVE_FLAG_REGEX)) && paths.some((path) => isRoot(path))
-    ? name
-    : undefined;
-};
-
-const getScanCommandRefusal: CommandRefusal = (name, args) =>
-  SCAN_COMMANDS.has(name) ? getScanRefusal(name, args) : undefined;
+import { getScanCommandRefusal } from "./getScanCommandRefusal";
 
 // The scan a Bash command runs from a root or a home folder, named by its command, undefined for every other command
 export const getDiskScanRefusal = (command: string): string | undefined =>
@@ -77,7 +7,7 @@ export const getDiskScanRefusal = (command: string): string | undefined =>
 
 // The known homes the refusal names. The mod ships without @esposter/shared, so the product's name is spelled here
 // As the folder it is on the person's disk
-const KNOWN_HOME_LINES: string[] = [
+export const KNOWN_HOME_LINES: string[] = [
   "- the repo, searched with `rg` or `git grep` (both skip node_modules);",
   // oxlint-disable-next-line naming/no-site-name-literal -- A path on the person's disk, which a package shipped without @esposter/shared cannot derive from SITE_NAME
   "- `~/Esposter/genshin-parity`, for game data and captures;",
@@ -85,9 +15,3 @@ const KNOWN_HOME_LINES: string[] = [
   "- a pinned tool (FFmpeg, yt-dlp) through `resolvePinnedTool`;",
   "- a package through `require.resolve` from the package that depends on it.",
 ];
-
-export const getDenyReason = (scanName: string): string =>
-  [
-    `Refused: ${scanName} scans from a root or a home folder, which reads the whole disk for a file whose home is known, and costs minutes of CPU and disk for every agent running. Look where the file lives instead:`,
-    ...KNOWN_HOME_LINES,
-  ].join("\n");

package/src/services/diskScan/getScanCommandRefusal.ts

@@ -0,0 +1,8 @@
+import type { CommandRefusal } from "../../models/CommandRefusal";
+
+import { getScanRefusal } from "./getScanRefusal";
+
+const SCAN_COMMANDS: ReadonlySet<string> = new Set(["du", "find", "grep", "ls"]);
+
+export const getScanCommandRefusal: CommandRefusal = (name, args) =>
+  SCAN_COMMANDS.has(name) ? getScanRefusal(name, args) : undefined;

package/src/services/diskScan/getScanRefusal.ts

@@ -0,0 +1,21 @@
+import { isRecursiveFlag } from "./isRecursiveFlag";
+import { isRoot } from "./isRoot";
+import { readGrepArguments } from "./readGrepArguments";
+
+// A flag group holding the scan's recursive letter, or the long form: grep takes r or R (`-R`, `-rn`, `-lR`), and ls takes
+// The capital R alone, since its lowercase r sorts in reverse
+const GREP_RECURSIVE_FLAG_REGEX = /^-[a-zA-Z]*[rR]/u;
+const LS_RECURSIVE_FLAG_REGEX = /^-[a-zA-Z]*R/u;
+
+// The scan's name when its arguments start it from a root, undefined when they do not
+export const getScanRefusal = (name: string, args: string[]): string | undefined => {
+  if (name === "find" || name === "du") return args.some((arg) => isRoot(arg)) ? name : undefined;
+  if (name === "ls")
+    return args.some((arg) => isRecursiveFlag(arg, LS_RECURSIVE_FLAG_REGEX)) && args.some((arg) => isRoot(arg))
+      ? name
+      : undefined;
+  const { flags, paths } = readGrepArguments(args);
+  return flags.some((flag) => isRecursiveFlag(flag, GREP_RECURSIVE_FLAG_REGEX)) && paths.some((path) => isRoot(path))
+    ? name
+    : undefined;
+};

package/src/services/diskScan/isRecursiveFlag.ts

@@ -0,0 +1,4 @@
+import { isRecursiveLongFlag } from "./isRecursiveLongFlag";
+
+export const isRecursiveFlag = (token: string, shortFlagRegex: RegExp) =>
+  shortFlagRegex.test(token) || isRecursiveLongFlag(token);

package/src/services/diskScan/isRecursiveLongFlag.ts

@@ -0,0 +1,3 @@
+// The long form `--recursive`, which getopt also takes as any prefix of it from `--rec` on, since `--re` names two options
+export const isRecursiveLongFlag = (token: string) =>
+  token.startsWith("--rec") && "recursive".startsWith(token.slice(2));

package/src/services/diskScan/isRoot.ts

@@ -0,0 +1,8 @@
+import { normalizePath } from "./normalizePath";
+
+// A root in any spelling is a folder whose scan reads the whole disk: the drive's folders, the users' folders and the
+// Home folder by name, once Windows drive letters and backslashes are read as Git Bash's `/c/...` form
+const ROOT_REGEX =
+  /^(?:\/[a-z]?|\/(?:c\/)?Users(?:\/[^/]+)?|\/home(?:\/[^/]+)?|~|\$HOME|\$\{HOME\}|\$USERPROFILE|%USERPROFILE%)$/u;
+
+export const isRoot = (token: string) => ROOT_REGEX.test(normalizePath(token));

package/src/services/diskScan/normalizePath.ts

@@ -0,0 +1,7 @@
+// Backslashes become slashes, a drive letter becomes its `/c` folder, and a trailing glob and slash go, so "C:\", "/c/",
+// "C:/" and "/c/*" all name "/c": a folder's glob expands to its entries, whose scan reads the whole folder
+export const normalizePath = (token: string) => {
+  const slashed = token.replaceAll("\\", "/");
+  const path = /^[A-Za-z]:/u.test(slashed) ? `/${slashed.charAt(0).toLowerCase()}${slashed.slice(2)}` : slashed;
+  return path.replace(/(?<=\/)\*$/u, "").replace(/(?<=.)\/+$/u, "");
+};

package/src/services/diskScan/readGrepArguments.ts

@@ -0,0 +1,25 @@
+// A flag that gives grep its pattern as the next argument, or as the rest of the same one
+const SEPARATE_PATTERN_FLAG_REGEX = /^-[a-zA-Z]*[ef]$|^--(?:regexp|file)$/u;
+const ATTACHED_PATTERN_FLAG_REGEX = /^-[a-zA-Z]*[ef].|^--(?:regexp|file)=/u;
+
+// Grep's flags and search paths: a pattern flag's operand is its pattern and never a flag or a path, every argument
+// After a `--` is a positional one, and with no pattern flag the first positional argument is the pattern
+export const readGrepArguments = (args: string[]): { flags: string[]; paths: string[] } => {
+  const flags: string[] = [];
+  const positionals: string[] = [];
+  let hasPatternFlag = false;
+  let isPatternOperand = false;
+  let isOptionEnd = false;
+  for (const arg of args)
+    if (isPatternOperand) isPatternOperand = false;
+    else if (isOptionEnd || !arg.startsWith("-")) positionals.push(arg);
+    else if (arg === "--") isOptionEnd = true;
+    else {
+      flags.push(arg);
+      if (SEPARATE_PATTERN_FLAG_REGEX.test(arg)) {
+        hasPatternFlag = true;
+        isPatternOperand = true;
+      } else if (ATTACHED_PATTERN_FLAG_REGEX.test(arg)) hasPatternFlag = true;
+    }
+  return { flags, paths: hasPatternFlag ? positionals : positionals.slice(1) };
+};

package/src/services/diskScan/registerDiskScan.ts

@@ -1,6 +1,7 @@
 import type { EngineInterface, On } from "claude-code";
 
-import { getDenyReason, getDiskScanRefusal } from "./getDiskScanRefusal";
+import { getDenyReason } from "./getDenyReason";
+import { getDiskScanRefusal } from "./getDiskScanRefusal";
 
 // Any failure lets the command through, as the ward's and the delegation guard's do: a guard that blocked on its own
 // Failure would block every command after it

package/src/services/registerLifecycle.ts

@@ -4,7 +4,9 @@ import { atom, read, update } from "claude-code";
 
 import type { EnabledMods } from "../../types";
 
+import { ModName } from "../models/ModName";
 import { SinStatusKind } from "../models/SinStatusKind";
+import { TaskStatus } from "../models/TaskStatus";
 import {
   CACHE_WARNING_MS,
   MACHINE_WATCHER_RETRY_MILLISECONDS,
@@ -175,7 +177,7 @@ export const registerLifecycle = (on: On, typeSafeKey: string): void => {
       const current = await read($, enabledModsAtom);
       const isNext = argument ? argument === "on" : !current[name];
       // Sins scores only with a TypeSafe key, so turning it on without one is refused and its value is left as it was
-      if (name === "sins" && isNext) {
+      if (name === ModName.Sins && isNext) {
         const key = await readTypeSafeKey($, typeSafeKey);
         if (!key)
           return { text: "Sins needs a TypeSafe key: set the typesafe_key option, or TYPESAFE_API_KEY, first." };
@@ -221,7 +223,7 @@ export const registerLifecycle = (on: On, typeSafeKey: string): void => {
     await update($, lookupStreakAtom, () => InitialState.lookupStreak);
     await update($, lastPromptAtom, () => e.text);
     const { tasks } = await read($, commissionAtom);
-    if (tasks.length > 0 && tasks.every(({ status }) => status === "completed")) await closeCommission($);
+    if (tasks.length > 0 && tasks.every(({ status }) => status === TaskStatus.Completed)) await closeCommission($);
     $.clock.after(0, () => {
       runDetached(() => scoreSins($, e.text, typeSafeKey));
     });

package/src/services/shell/getDollarSubstitutionBodies.ts

@@ -0,0 +1,25 @@
+// The bodies of a command's `$(…)` substitutions, which run even inside double quotes: each runs to the parenthesis
+// Closing it, past any a quote or a backslash holds, so a body such as `find / -name '(x)'` is read whole. A
+// Substitution inside a body is the body's own, read when the body is
+export const getDollarSubstitutionBodies = (command: string): string[] => {
+  const bodies: string[] = [];
+  let start = command.indexOf("$(");
+  while (start !== -1) {
+    let depth = 1;
+    let quote = "";
+    let index = start + 2;
+    for (; index < command.length && depth > 0; index++) {
+      const character = command[index];
+      if (character === "\\" && quote !== "'") index++;
+      else if (quote !== "") {
+        if (character === quote) quote = "";
+      } else if (character === '"' || character === "'") quote = character;
+      else if (character === "(") depth++;
+      else if (character === ")") depth--;
+    }
+    if (depth > 0) break;
+    bodies.push(command.slice(start + 2, index - 1));
+    start = command.indexOf("$(", index);
+  }
+  return bodies;
+};

package/src/services/shell/getShellRefusal.ts

@@ -1,4 +1,8 @@
+import type { CommandRefusal } from "../../models/CommandRefusal";
+
+import { getDollarSubstitutionBodies } from "./getDollarSubstitutionBodies";
 import { joinDirectory } from "./joinDirectory";
+import { tokenize } from "./tokenize";
 
 // A shell command passed as one argument (`bash -c "…"`) is read again on its own, to this depth at most
 const MAX_NESTING_DEPTH = 3;
@@ -8,46 +12,8 @@ const SEGMENT_REGEX = /(?:"[^"]*"|'[^']*'|[^\n"&'();`|])+/gu;
 // A backtick substitution runs even inside double quotes, so its body is read again on its own
 const BACKTICK_SUBSTITUTION_REGEX = /`(?<body>[^`]*)`/gu;
 const SHELL_FLAG_REGEX = /^-[a-zA-Z]*c$|^eval$/u;
-const TOKEN_REGEX = /"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>\S+)/gu;
 const PATH_SEPARATOR_REGEX = /[/\\]/u;
 
-// The refusal for a command's name, the arguments after it and the folder it runs in from the session's ("" for the
-// Session's own), undefined when the command is not one the guard reads
-export type CommandRefusal<T = string> = (name: string, args: string[], directory: string) => T | undefined;
-
-// A quoted argument keeps its inner spaces, so a shell command passed as one argument is read again on its own
-const tokenize = (segment: string) =>
-  Array.from(
-    segment.matchAll(TOKEN_REGEX),
-    (match) => match.groups?.double ?? match.groups?.single ?? match.groups?.bare ?? "",
-  );
-
-// The bodies of a command's `$(…)` substitutions, which run even inside double quotes: each runs to the parenthesis
-// Closing it, past any a quote or a backslash holds, so a body such as `find / -name '(x)'` is read whole. A
-// Substitution inside a body is the body's own, read when the body is
-const getDollarSubstitutionBodies = (command: string): string[] => {
-  const bodies: string[] = [];
-  let start = command.indexOf("$(");
-  while (start !== -1) {
-    let depth = 1;
-    let quote = "";
-    let index = start + 2;
-    for (; index < command.length && depth > 0; index++) {
-      const character = command[index];
-      if (character === "\\" && quote !== "'") index++;
-      else if (quote !== "") {
-        if (character === quote) quote = "";
-      } else if (character === '"' || character === "'") quote = character;
-      else if (character === "(") depth++;
-      else if (character === ")") depth--;
-    }
-    if (depth > 0) break;
-    bodies.push(command.slice(start + 2, index - 1));
-    start = command.indexOf("$(", index);
-  }
-  return bodies;
-};
-
 // The refusal of the first command in a Bash command that the given reader refuses, undefined when none does. A `cd`
 // Moves every command after it in the line; one to a home folder or back to the last is not followed
 export const getShellRefusal = <T = string>(

package/src/services/shell/tokenize.ts

@@ -0,0 +1,8 @@
+const TOKEN_REGEX = /"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>\S+)/gu;
+
+// A quoted argument keeps its inner spaces, so a shell command passed as one argument is read again on its own
+export const tokenize = (segment: string) =>
+  Array.from(
+    segment.matchAll(TOKEN_REGEX),
+    (match) => match.groups?.double ?? match.groups?.single ?? match.groups?.bare ?? "",
+  );

package/src/services/ward/getAddRefusal.ts

@@ -0,0 +1,14 @@
+import { isWholeCheckout } from "./isWholeCheckout";
+import { splitArguments } from "./splitArguments";
+
+const ADD_ALL_FLAGS: ReadonlySet<string> = new Set(["--all", "--update", "-A", "-u"]);
+
+// `add .`, `add -A` and `add -N` over every path reach a peer's work, while a named path does not
+export const getAddRefusal = (args: string[]): string | undefined => {
+  const { flags, operands } = splitArguments(args);
+  if (isWholeCheckout(operands)) return "git add .";
+  const allFlag = flags.find((flag) => ADD_ALL_FLAGS.has(flag));
+  if (allFlag !== undefined && operands.length === 0) return `git add ${allFlag}`;
+  const isIntentToAdd = flags.some((flag) => flag === "-N" || flag === "--intent-to-add");
+  return isIntentToAdd && operands.length === 0 ? "git add -N" : undefined;
+};

package/src/services/ward/getCheckoutPeer.ts

@@ -1,9 +1,7 @@
 import type { WardRecord } from "../../../types";
 
 import { getCollidingRecord } from "./getCollidingRecord";
-
-// Windows paths compare as one spelling: forward slashes, lowercase, since the file system ignores case
-const getComparablePath = (path: string) => path.replaceAll("\\", "/").toLowerCase();
+import { getComparablePath } from "./getComparablePath";
 
 // The edited path of another session's record inside this checkout, undefined when no other session in the window
 // Shares it, so a checkout alone with its session is never refused

package/src/services/ward/getCheckoutRefusal.ts

@@ -0,0 +1,6 @@
+import { isWholeCheckout } from "./isWholeCheckout";
+import { splitArguments } from "./splitArguments";
+
+// `checkout .` and `checkout -- .` overwrite every path's working tree copy, a peer's edits included
+export const getCheckoutRefusal = (args: string[]): string | undefined =>
+  isWholeCheckout(splitArguments(args).operands) ? "git checkout ." : undefined;

package/src/services/ward/getCleanRefusal.ts

@@ -0,0 +1,8 @@
+import { splitArguments } from "./splitArguments";
+
+// A clean deletes every untracked file, a peer's new ones included; a dry run lists them and is allowed
+export const getCleanRefusal = (args: string[]): string | undefined => {
+  const { flags } = splitArguments(args);
+  const isDryRun = flags.some((flag) => flag === "--dry-run" || (!flag.startsWith("--") && flag.includes("n")));
+  return isDryRun ? undefined : "git clean";
+};

package/src/services/ward/getComparablePath.ts

@@ -0,0 +1,2 @@
+// Windows paths compare as one spelling: forward slashes, lowercase, since the file system ignores case
+export const getComparablePath = (path: string) => path.replaceAll("\\", "/").toLowerCase();

package/src/services/ward/getGitRefusal.ts

@@ -0,0 +1,32 @@
+import type { CommandRefusal } from "../../models/CommandRefusal";
+
+import { joinDirectory } from "../shell/joinDirectory";
+import { getAddRefusal } from "./getAddRefusal";
+import { getCheckoutRefusal } from "./getCheckoutRefusal";
+import { getCleanRefusal } from "./getCleanRefusal";
+import { getResetRefusal } from "./getResetRefusal";
+import { getRestoreRefusal } from "./getRestoreRefusal";
+import { getStashRefusal } from "./getStashRefusal";
+import { getSubcommand } from "./getSubcommand";
+
+const GIT_NAMES: ReadonlySet<string> = new Set(["git", "git.exe"]);
+
+const WHOLE_INDEX_REFUSALS: ReadonlyMap<string, (args: string[]) => string | undefined> = new Map([
+  ["add", getAddRefusal],
+  ["checkout", getCheckoutRefusal],
+  ["clean", getCleanRefusal],
+  ["reset", getResetRefusal],
+  ["restore", getRestoreRefusal],
+  ["stash", getStashRefusal],
+]);
+
+// The form refused and the folder git runs in, from the session's ("" for the session's own): the folder a `cd` before
+// It moved to, then each of its `-C` folders
+export const getGitRefusal: CommandRefusal<{ directory: string; form: string }> = (name, args, directory) => {
+  if (!GIT_NAMES.has(name)) return undefined;
+  const subcommand = getSubcommand(args);
+  const form = WHOLE_INDEX_REFUSALS.get(subcommand.name)?.(subcommand.arguments);
+  return form === undefined
+    ? undefined
+    : { directory: subcommand.directories.reduce((base, next) => joinDirectory(base, next), directory), form };
+};

package/src/services/ward/getResetRefusal.ts

@@ -0,0 +1,19 @@
+import { isWholeCheckout } from "./isWholeCheckout";
+import { splitArguments } from "./splitArguments";
+
+// The reset modes that touch the working tree or the index beyond HEAD, so a reset with one of them is not a commit move
+const RESET_INDEX_MODES: ReadonlySet<string> = new Set(["--hard", "--keep", "--merge", "--mixed"]);
+
+// A reset that names a path is path-scoped: after `--`, or as a second operand with none, since git reads the first
+// As a commit or a path and every one after it as a path. The checkout's own pathspec names no commit, so it is the
+// Whole checkout in either place. A lone operand may be a commit, so it is refused, and a reset that moves HEAD alone
+// With `--soft` leaves the index as it is; every other reset rewrites the index to HEAD or the working tree, a peer's
+// Staged entries included
+export const getResetRefusal = (args: string[]): string | undefined => {
+  const { after, flags, hasSeparator, operands } = splitArguments(args);
+  if (isWholeCheckout(hasSeparator ? after : operands)) return "git reset -- .";
+  const paths = hasSeparator ? after : operands.slice(1);
+  if (paths.length > 0) return undefined;
+  const isSoftOnly = flags.includes("--soft") && !flags.some((flag) => RESET_INDEX_MODES.has(flag));
+  return isSoftOnly ? undefined : "git reset";
+};

package/src/services/ward/getRestoreRefusal.ts

@@ -0,0 +1,10 @@
+import { isWholeCheckout } from "./isWholeCheckout";
+import { splitArguments } from "./splitArguments";
+
+// `restore .` rewrites every path, staged or in the working tree, so the staged form is refused as the plain one is
+export const getRestoreRefusal = (args: string[]): string | undefined => {
+  const { flags, operands } = splitArguments(args);
+  if (!isWholeCheckout(operands)) return undefined;
+  const isStaged = flags.some((flag) => flag === "--staged" || flag === "-S");
+  return `git restore ${isStaged ? "--staged " : ""}.`;
+};

package/src/services/ward/getStashRefusal.ts

@@ -0,0 +1,2 @@
+// A stash in any form sets a peer's work aside, which is why the git skill never runs one
+export const getStashRefusal = (): string => "git stash";

package/src/services/ward/getSubcommand.ts

@@ -0,0 +1,16 @@
+import { isFlag } from "./isFlag";
+
+// The options git takes before its subcommand, each with its value as the next word
+const GIT_VALUE_OPTIONS: ReadonlySet<string> = new Set(["--git-dir", "--namespace", "--work-tree", "-C", "-c"]);
+
+// The subcommand past the options git takes before it, the arguments after the subcommand, and the folders its `-C`
+// Options name, each from the one before
+export const getSubcommand = (args: string[]) => {
+  const directories: string[] = [];
+  let index = 0;
+  while (index < args.length && isFlag(args[index] ?? "")) {
+    if (args[index] === "-C") directories.push(args[index + 1] ?? "");
+    index += GIT_VALUE_OPTIONS.has(args[index] ?? "") ? 2 : 1;
+  }
+  return { arguments: args.slice(index + 1), directories, name: args[index] ?? "" };
+};

package/src/services/ward/getWholeIndexDenyReason.ts

@@ -0,0 +1,9 @@
+// The path-scoped forms that do the same job for the paths the session touched, named for the person's shared checkout
+export const getWholeIndexDenyReason = (form: string, peerPath: string): string =>
+  [
+    `Refused: \`${form}\` reaches the staged and working changes of another session in this checkout, which is editing ${peerPath} now. Name the paths you touched instead:`,
+    "- `git add <path>` to stage them;",
+    "- `git reset -- <path>` to unstage them;",
+    '- `git commit -m "…" -- <path>` to commit only them.',
+    "The git skill's rule (`.agents/skills/git/SKILL.md`) owns the whole-index list.",
+  ].join("\n");

package/src/services/ward/getWholeIndexRefusal.ts

@@ -1,127 +1,7 @@
-import type { CommandRefusal } from "../shell/getShellRefusal";
-
 import { getShellRefusal } from "../shell/getShellRefusal";
-import { joinDirectory } from "../shell/joinDirectory";
-
-const GIT_NAMES: ReadonlySet<string> = new Set(["git", "git.exe"]);
-
-// The options git takes before its subcommand, each with its value as the next word
-const GIT_VALUE_OPTIONS: ReadonlySet<string> = new Set(["-C", "-c"]);
-
-// The reset modes that touch the working tree or the index beyond HEAD, so a reset with one of them is not a commit move
-const RESET_INDEX_MODES: ReadonlySet<string> = new Set(["--hard", "--keep", "--merge", "--mixed"]);
-
-const ADD_ALL_FLAGS: ReadonlySet<string> = new Set(["--all", "--update", "-A", "-u"]);
-
-// The pathspecs git reads as every path of the checkout, from its root or the folder the command runs in
-const WHOLE_CHECKOUT_PATHSPECS: ReadonlySet<string> = new Set([".", "./", ":/", ":/."]);
-
-const isFlag = (arg: string) => arg.startsWith("-");
-
-const isWholeCheckout = (operands: string[]) => operands.some((operand) => WHOLE_CHECKOUT_PATHSPECS.has(operand));
-
-// The flags, the words before a `--` and the words after it, so a path is read whether or not git was given a separator
-const splitArguments = (args: string[]) => {
-  const separator = args.indexOf("--");
-  const before = separator === -1 ? args : args.slice(0, separator);
-  const after = separator === -1 ? [] : args.slice(separator + 1);
-  return {
-    after,
-    flags: before.filter((arg) => isFlag(arg)),
-    hasSeparator: separator !== -1,
-    operands: [...before.filter((arg) => !isFlag(arg)), ...after],
-  };
-};
-
-// The subcommand past the options git takes before it, the arguments after the subcommand, and the folders its `-C`
-// Options name, each from the one before
-const getSubcommand = (args: string[]) => {
-  const directories: string[] = [];
-  let index = 0;
-  while (index < args.length && isFlag(args[index] ?? "")) {
-    if (args[index] === "-C") directories.push(args[index + 1] ?? "");
-    index += GIT_VALUE_OPTIONS.has(args[index] ?? "") ? 2 : 1;
-  }
-  return { arguments: args.slice(index + 1), directories, name: args[index] ?? "" };
-};
-
-// `add .`, `add -A` and `add -N` over every path reach a peer's work, while a named path does not
-const getAddRefusal = (args: string[]): string | undefined => {
-  const { flags, operands } = splitArguments(args);
-  if (isWholeCheckout(operands)) return "git add .";
-  const allFlag = flags.find((flag) => ADD_ALL_FLAGS.has(flag));
-  if (allFlag !== undefined && operands.length === 0) return `git add ${allFlag}`;
-  const isIntentToAdd = flags.some((flag) => flag === "-N" || flag === "--intent-to-add");
-  return isIntentToAdd && operands.length === 0 ? "git add -N" : undefined;
-};
-
-// A reset that names a path is path-scoped: after `--`, or as a second operand with none, since git reads the first
-// As a commit or a path and every one after it as a path. The checkout's own pathspec names no commit, so it is the
-// Whole checkout in either place. A lone operand may be a commit, so it is refused, and a reset that moves HEAD alone
-// With `--soft` leaves the index as it is; every other reset rewrites the index to HEAD or the working tree, a peer's
-// Staged entries included
-const getResetRefusal = (args: string[]): string | undefined => {
-  const { after, flags, hasSeparator, operands } = splitArguments(args);
-  if (isWholeCheckout(hasSeparator ? after : operands)) return "git reset -- .";
-  const paths = hasSeparator ? after : operands.slice(1);
-  if (paths.length > 0) return undefined;
-  const isSoftOnly = flags.includes("--soft") && !flags.some((flag) => RESET_INDEX_MODES.has(flag));
-  return isSoftOnly ? undefined : "git reset";
-};
-
-// `restore .` rewrites every path, staged or in the working tree, so the staged form is refused as the plain one is
-const getRestoreRefusal = (args: string[]): string | undefined => {
-  const { flags, operands } = splitArguments(args);
-  if (!isWholeCheckout(operands)) return undefined;
-  const isStaged = flags.some((flag) => flag === "--staged" || flag === "-S");
-  return `git restore ${isStaged ? "--staged " : ""}.`;
-};
-
-// A stash in any form sets a peer's work aside, which is why the git skill never runs one
-const getStashRefusal = (): string => "git stash";
-
-// `checkout .` and `checkout -- .` overwrite every path's working tree copy, a peer's edits included
-const getCheckoutRefusal = (args: string[]): string | undefined =>
-  isWholeCheckout(splitArguments(args).operands) ? "git checkout ." : undefined;
-
-// A clean deletes every untracked file, a peer's new ones included; a dry run lists them and is allowed
-const getCleanRefusal = (args: string[]): string | undefined => {
-  const { flags } = splitArguments(args);
-  const isDryRun = flags.some((flag) => flag === "--dry-run" || (!flag.startsWith("--") && flag.includes("n")));
-  return isDryRun ? undefined : "git clean";
-};
-
-const WHOLE_INDEX_REFUSALS: ReadonlyMap<string, (args: string[]) => string | undefined> = new Map([
-  ["add", getAddRefusal],
-  ["checkout", getCheckoutRefusal],
-  ["clean", getCleanRefusal],
-  ["reset", getResetRefusal],
-  ["restore", getRestoreRefusal],
-  ["stash", getStashRefusal],
-]);
-
-// The form refused and the folder git runs in, from the session's ("" for the session's own): the folder a `cd` before
-// It moved to, then each of its `-C` folders
-const getGitRefusal: CommandRefusal<{ directory: string; form: string }> = (name, args, directory) => {
-  if (!GIT_NAMES.has(name)) return undefined;
-  const subcommand = getSubcommand(args);
-  const form = WHOLE_INDEX_REFUSALS.get(subcommand.name)?.(subcommand.arguments);
-  return form === undefined
-    ? undefined
-    : { directory: subcommand.directories.reduce((base, next) => joinDirectory(base, next), directory), form };
-};
+import { getGitRefusal } from "./getGitRefusal";
 
 // The whole-index git form a Bash command runs, named as the form it is, with the folder it runs in, undefined for a
 // Path-scoped or read-only command
 export const getWholeIndexRefusal = (command: string): undefined | { directory: string; form: string } =>
   getShellRefusal(command, getGitRefusal);
-
-// The path-scoped forms that do the same job for the paths the session touched, named for the person's shared checkout
-export const getWholeIndexDenyReason = (form: string, peerPath: string): string =>
-  [
-    `Refused: \`${form}\` reaches the staged and working changes of another session in this checkout, which is editing ${peerPath} now. Name the paths you touched instead:`,
-    "- `git add <path>` to stage them;",
-    "- `git reset -- <path>` to unstage them;",
-    '- `git commit -m "…" -- <path>` to commit only them.',
-    "The git skill's rule (`.agents/skills/git/SKILL.md`) owns the whole-index list.",
-  ].join("\n");

package/src/services/ward/isFlag.ts

@@ -0,0 +1 @@
+export const isFlag = (arg: string) => arg.startsWith("-");

package/src/services/ward/isWholeCheckout.ts

@@ -0,0 +1,5 @@
+// The pathspecs git reads as every path of the checkout, from its root or the folder the command runs in
+const WHOLE_CHECKOUT_PATHSPECS: ReadonlySet<string> = new Set([".", "./", ":/", ":/."]);
+
+export const isWholeCheckout = (operands: string[]) =>
+  operands.some((operand) => WHOLE_CHECKOUT_PATHSPECS.has(operand));

package/src/services/ward/registerWholeIndex.ts

@@ -6,7 +6,8 @@ import { InitialState } from "../InitialState";
 import { joinDirectory } from "../shell/joinDirectory";
 import { getCheckoutPeer } from "./getCheckoutPeer";
 import { getParentFolder } from "./getParentFolder";
-import { getWholeIndexDenyReason, getWholeIndexRefusal } from "./getWholeIndexRefusal";
+import { getWholeIndexDenyReason } from "./getWholeIndexDenyReason";
+import { getWholeIndexRefusal } from "./getWholeIndexRefusal";
 import { readRecords } from "./readRecords";
 import { resolveRecordsPath } from "./resolveRecordsPath";
 

package/src/services/ward/splitArguments.ts

@@ -0,0 +1,14 @@
+import { isFlag } from "./isFlag";
+
+// The flags, the words before a `--` and the words after it, so a path is read whether or not git was given a separator
+export const splitArguments = (args: string[]) => {
+  const separator = args.indexOf("--");
+  const before = separator === -1 ? args : args.slice(0, separator);
+  const after = separator === -1 ? [] : args.slice(separator + 1);
+  return {
+    after,
+    flags: before.filter((arg) => isFlag(arg)),
+    hasSeparator: separator !== -1,
+    operands: [...before.filter((arg) => !isFlag(arg)), ...after],
+  };
+};