genshin-mods 4.0.0 → 4.1.1

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "genshin-mods",
   "displayName": "Genshin Mods",
-  "description": "Five Claude Code mods under one band above the prompt: waypoints (the next steps, one press each), resin (cache, context, limits and cost, with warm, compact and a one-click handoff), veil (recording mode), commission (a goal's task list and clock) and ward (a question before editing a file another session just changed).",
+  "description": "Six Claude Code mods: five under one band above the prompt, waypoints (the next steps, one press each), resin (cache, context, limits and cost, with warm, compact and a one-click handoff), veil (recording mode), commission (a goal's task list and clock) and ward (a question before editing a file another session just changed), and a delegation guard that nudges a run of lookups toward a haiku agent.",
   "author": { "name": "Esposter", "url": "https://github.com/Esposter" },
   "homepage": "https://esposter.com/docs/infra/claude-interface/genshin-mods",
   "repository": "https://github.com/Esposter/Esposter",

package/README.md

@@ -5,13 +5,17 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-A Claude Code plugin of five mods 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 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.
 
 - **Waypoints** — after each answered turn, up to three next steps the session suggests, each a button that sends it as the next prompt.
-- **Resin** — the prompt cache's time left, the context window, the five-hour and weekly limits and the cost so far, with **Warm**, **Compact** and **Handoff**, and a toast before the cache goes cold.
+- **Resin** — the prompt cache's time left, the context window, the five-hour and weekly limits and the cost so far, with **Warm**, **Compact** and **Handoff**, a toast before the cache goes cold, and a usage reserve past four-fifths of a limit window, or past half of one spent ahead of an even pace, that has the session clean up on cheap agents, then wind down, until the window resets, refusing a workflow at launch meanwhile.
 - **Veil** — recording mode: emails, amounts, phone numbers and secrets shown as placeholders while the model still reads the real values.
 - **Commission** — a goal meter over the session's task list: the goal, tasks done, the share complete and the minutes since it started.
 - **Ward** — before an edit to a file another session changed in the last half hour, a question: proceed, move to a worktree, or cancel.
+- **Delegation guard** — every subagent launch not on haiku refused, a fork included, and after every third lookup in a row with no decision between them, a note on that call's result that the chain goes to a haiku agent as one bounded question.
+- **Disk-scan guard** — a Bash `find`, `du`, `grep -r` or `ls -R` that starts at `/`, a drive, `~` or a home folder is refused, with the known place to look for the file.
+- **Pulse** — keeps the machine watcher running from any session with the plugin, so its heartbeat and the machine's state keep being written.
+- **Whole-index guard** — while another session edits this checkout, a Bash `git add .`, `git add -A`, `git reset` with no path, `git stash`, `git checkout .` or `git clean` is refused, with the path-scoped form to use instead.
 
 ## Table of Contents
 
@@ -47,13 +51,14 @@ We highly recommend you take a look at the [documentation](https://esposter.com/
 
 Each mod is switched by its own slash command; bare, it flips, and the choice is kept across sessions:
 
-| Command                   | What it does                                                        |
-| :------------------------ | :------------------------------------------------------------------ |
-| `/waypoints [on \| off]`  | Suggests the next steps after each answered turn, or stops          |
-| `/resin [on \| off]`      | Shows the cache, context, limits and cost row and its warning toast |
-| `/veil [on \| off]`       | Turns recording mode on or off; off by default                      |
-| `/commission [on \| off]` | Shows the goal meter while a turn works through a task list         |
-| `/ward [on \| off]`       | Asks before an edit to a file another session just changed          |
+| Command                   | What it does                                                                                                                    |
+| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
+| `/waypoints [on \| off]`  | Suggests the next steps after each answered turn, or stops                                                                      |
+| `/resin [on \| off]`      | Shows the cache, context, limits and cost row and its warning toast                                                             |
+| `/veil [on \| off]`       | Turns recording mode on or off; off by default                                                                                  |
+| `/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                                                                                     |
+| `/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 |
 
 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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genshin-mods",
-  "version": "4.0.0",
-  "description": "A Claude Code plugin of five mods 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.",
+  "version": "4.1.1",
+  "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",
     "claude-code-plugin",
@@ -38,5 +38,5 @@
     "test": "vitest",
     "validate": "claude plugin validate ."
   },
-  "gitHead": "7667bc8c9a2b4e9dcacd6b845ee8cc9951250ae7"
+  "gitHead": "47b7795ab557d7731aa60588d0b9d1cdff243328"
 }

package/src/models/AgentLaunch.ts

@@ -0,0 +1,6 @@
+// The part of an agent launch the delegation guard reads: the model it runs on and the type that may be a fork, which
+// Inherits the parent's model whatever it names
+export interface AgentLaunch {
+  model?: string;
+  subagent_type?: string;
+}

package/src/models/DelegationCall.ts

@@ -0,0 +1,8 @@
+// The part of a tool call the lookup count reads: the tool, a shell command with its background flag, and the agent
+// A subagent's call names
+export interface DelegationCall {
+  agentId?: string;
+  command?: string;
+  run_in_background?: boolean;
+  tool: string;
+}

package/src/models/DelegationStep.ts

@@ -0,0 +1,7 @@
+// What one tool call does to the count of lookups in a row: a lookup adds one, a reset clears it, and a call that
+// Neither is, or a subagent's, leaves it as it was
+export enum DelegationStep {
+  Lookup = "Lookup",
+  Neutral = "Neutral",
+  Reset = "Reset",
+}

package/src/models/UsageWindow.ts

@@ -0,0 +1,10 @@
+export interface UsageWindow {
+  // The window's length, which its reset time is counted back from
+  durationMs: number;
+  // The usage line the window's maintenance tier starts at
+  maintenancePercentage: number;
+  // The window's name as the reserve's note spells it
+  name: string;
+  // The usage line the window's wind-down starts at
+  windDownPercentage: number;
+}

package/src/register.ts

@@ -2,14 +2,22 @@ import type { Register } from "claude-code";
 
 import { registerBand } from "./services/band/registerBand";
 import { registerCommission } from "./services/commission/registerCommission";
+import { registerDelegation } from "./services/delegation/registerDelegation";
+import { registerDiskScan } from "./services/diskScan/registerDiskScan";
 import { registerLifecycle } from "./services/registerLifecycle";
+import { registerReserveGate } from "./services/resin/registerReserveGate";
 import { registerVeil } from "./services/veil/registerVeil";
 import { registerWard } from "./services/ward/registerWard";
+import { registerWholeIndex } from "./services/ward/registerWholeIndex";
 
 export const register: Register = (on) => {
   registerBand(on);
   registerCommission(on);
+  registerDelegation(on);
+  registerDiskScan(on);
   registerLifecycle(on);
+  registerReserveGate(on);
   registerVeil(on);
   registerWard(on);
+  registerWholeIndex(on);
 };

package/src/services/InitialState.ts

@@ -4,11 +4,13 @@ import type { PluginState } from "claude-code";
 // The file that uses it, so each file makes its own and this is the one place their initials are written
 export const InitialState: PluginState["genshin-mods"] = {
   commission: { goal: "", openedAt: 0, tasks: [] },
-  enabledMods: { commission: true, resin: true, veil: false, ward: true, waypoints: true },
+  enabledMods: { commission: true, pulse: true, resin: true, veil: false, ward: true, waypoints: true },
   isCommissionExpanded: false,
   isHandingOff: false,
   lastCacheRequestAt: 0,
   lastPrompt: "",
+  lookupStreak: 0,
   now: 0,
+  reserveWindow: { isAheadOfPace: false, isWindDown: false, name: "", percentage: 0, resetsAt: "" },
   waypoints: [],
 };

package/src/services/ModDescriptionMap.ts

@@ -3,9 +3,10 @@ import type { EnabledMods } from "../../types";
 // Each mod's command, `/<name> [on|off]`, as the menu describes it
 export const ModDescriptionMap: Record<keyof EnabledMods, string> = {
   commission: "Show a goal's task list, how far it is and how long it has run.",
+  pulse: "Keep the machine watcher running.",
   resin: "Show the cache, context, limits and cost, with warm, compact and handoff.",
   veil: "Recording mode: show emails, amounts, phone numbers and secrets as placeholders.",
-  ward: "Ask before editing a file another session changed in the last half hour.",
+  ward: "Ask before editing a file another session changed in the last half hour, and refuse a whole-index git command while one shares the checkout.",
   waypoints: "Suggest the next steps after each answer, one press each.",
 };
 

package/src/services/constants.ts

@@ -4,8 +4,25 @@ export const ACCENT_COLOR = "#d3bc8e";
 export const CACHE_LIFETIME_MS: number = Temporal.Duration.from({ hours: 1 }).total("milliseconds");
 export const CACHE_LOW_MS: number = Temporal.Duration.from({ minutes: 10 }).total("milliseconds");
 export const CACHE_WARNING_MS: number = Temporal.Duration.from({ minutes: 5 }).total("milliseconds");
-export const CLOCK_TICK_MS: number = Temporal.Duration.from({ minutes: 1 }).total("milliseconds");
 export const USAGE_WARNING_PERCENTAGE = 80;
+// The usage lines each window's two tiers start at: the maintenance tier, then the wind-down
+export const FIVE_HOUR_MAINTENANCE_PERCENTAGE = 80;
+export const FIVE_HOUR_WIND_DOWN_PERCENTAGE = 90;
+export const WEEKLY_MAINTENANCE_PERCENTAGE = 80;
+export const WEEKLY_WIND_DOWN_PERCENTAGE = 90;
+// A window under this share is never read for its pace, since an early reading projects wildly
+export const PACE_FLOOR_PERCENTAGE = 50;
+// Each window's length, which its reset time is counted back from
+export const FIVE_HOUR_WINDOW_MS: number = Temporal.Duration.from({ hours: 5 }).total("milliseconds");
+export const WEEKLY_WINDOW_MS: number = Temporal.Duration.from({ hours: 168 }).total("milliseconds");
+// The only model a subagent launches on: the main session thinks, and everything it delegates runs on haiku
+export const AGENT_MODEL = "haiku";
+// What a launch on any other model, or a fork, is told instead
+// oxlint-disable-next-line typescript/no-inferrable-types -- `isolatedDeclarations` demands the annotation this template literal would otherwise infer
+export const AGENT_MODEL_REFUSAL: string = `A subagent runs on "${AGENT_MODEL}" alone: pass model "${AGENT_MODEL}", and never a fork, which runs on the session's own model. Work too judged for ${AGENT_MODEL} stays in the main session, and a spec ${AGENT_MODEL} cannot carry still has a call open.`;
+// What a workflow refused under a reserve is told to do instead, after the reserve's summary
+// oxlint-disable-next-line typescript/no-inferrable-types -- `isolatedDeclarations` demands the annotation this template literal would otherwise infer
+export const RESERVE_REFUSAL_INSTRUCTION: string = `Launch an agent with model "${AGENT_MODEL}" instead, for cleanup or a compute runner whose judgement is settled; otherwise write the unit down as a follow-up and leave it for after the reset.`;
 export const MAX_WAYPOINTS = 3;
 export const MAX_SHOWN_TASKS = 8;
 // Whole minutes as the band writes them, `12m`
@@ -24,3 +41,31 @@ export const HANDOFF_QUESTION =
 export const VEIL_SECTION_ID = "genshin-mods-veil";
 export const VEIL_SYSTEM_SECTION =
   "Recording mode is on: the screen is being recorded or shared. Never write an email address, a phone number, a money amount, an API key, a token or a password in a reply; write a placeholder such as [email], [phone], [amount] or [secret] instead, even when asked for the value. Tool calls still use the real values.";
+export const RESERVE_SECTION_ID = "genshin-mods-reserve";
+// The wind-down's section ends on this instruction, the same for every window so only the window and its reset time vary
+export const RESERVE_INSTRUCTION =
+  "Until it resets, start no new agent or workflow that writes code or designs; have each running one commit what builds and end on a handoff spec; commit and push the work in hand; write every open item down with what it takes to resume it cold (its paths, what is done, the calls made, the next step); clean up idle servers, shells and monitors; keep only long-running compute going.";
+// The maintenance tier's section ends on this instruction: the window's rest goes on cleanup a haiku agent can do cold
+export const MAINTENANCE_INSTRUCTION =
+  "Until it resets, start no new feature, design or proposal; spend the rest of the window on haiku agents for cleanup: fix the findings of a code review of this window's own recent commits, drain an open sweep ledger, bring the docs and skills in line with the code changed this window, fix CI's typecheck and lint reds, and land the refactors, simplifications and optimisations the compute queue's runs surfaced; write a finding that needs judgement down as a follow-up (the follow-ups plugin's capture skill) rather than deciding it on haiku; keep the compute queue's runners going.";
+// The tools that look something up, the tools that change files, and the shells whose command decides which it is
+export const LOOKUP_TOOLS: readonly string[] = ["Glob", "Grep", "Read", "WebFetch"];
+export const RESET_TOOLS: readonly string[] = ["Agent", "Edit", "NotebookEdit", "Write"];
+export const SHELL_TOOLS: readonly string[] = ["Bash", "PowerShell"];
+// The `export` and `cd` a session chains ahead of its command, each stripped as one leading segment
+// oxlint-disable-next-line typescript/no-inferrable-types -- `isolatedDeclarations` demands the annotation this pattern would otherwise infer
+export const LEADING_SEGMENT_REGEX: RegExp = /^\s*(?:export\s[^&;]*&&|cd\s[^&;]*&&|cd\s[^&;]*;)\s*/u;
+// The commands that only read, a whole first word each so `catalog` is not `cat`. No interpreter is one, since what
+// It runs may write as readily as read; PowerShell's cmdlets are matched in any case, as PowerShell matches them
+// oxlint-disable-next-line typescript/no-inferrable-types -- `isolatedDeclarations` demands the annotation this pattern would otherwise infer
+export const LOOKUP_COMMAND_REGEX: RegExp =
+  /^\s*(?:cat|sed|grep|rg|find|ls|head|tail|awk|wc|get-content|get-childitem|select-string|git\s+(?:show|log|diff)|gh\s+run\s+view)(?:\s|$)/iu;
+// Every third lookup in a row, the chain a haiku agent should answer as one bounded question
+export const DELEGATION_NUDGE_EVERY = 3;
+export const DELEGATION_NUDGE =
+  "Third lookup in a row with no decision between them: by the llm-delegation skill's hop rule this chain goes to a haiku agent as one bounded question.";
+// The repository's watcher, which the pulse runs as its child and reads the lines of
+export const MACHINE_WATCHER_SCRIPT = "scripts/src/machine/watch/index.ts";
+// How long after its watcher exits a session starts one again, so a session whose watcher found another's lock held takes
+// Over the watching once that watcher's session ends
+export const MACHINE_WATCHER_RETRY_MILLISECONDS: number = Temporal.Duration.from({ minutes: 1 }).total("milliseconds");

package/src/services/delegation/checkIsLookupCommand.ts

@@ -0,0 +1,11 @@
+import { LEADING_SEGMENT_REGEX, LOOKUP_COMMAND_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);
+};
+
+export const checkIsLookupCommand = (command: string): boolean =>
+  LOOKUP_COMMAND_REGEX.test(stripLeadingSegments(command));

package/src/services/delegation/getCallStep.ts

@@ -0,0 +1,16 @@
+import type { DelegationCall } from "../../models/DelegationCall";
+
+import { DelegationStep } from "../../models/DelegationStep";
+import { LOOKUP_TOOLS, RESET_TOOLS, SHELL_TOOLS } from "../constants";
+import { checkIsLookupCommand } from "./checkIsLookupCommand";
+
+// A subagent's calls, and a tool that is neither a lookup nor a reset, leave the main session's count alone. A shell
+// Command in the background is never a lookup: its output is not read in the turn it runs
+export const getCallStep = (call: DelegationCall): DelegationStep => {
+  if (call.agentId !== undefined) return DelegationStep.Neutral;
+  else if (LOOKUP_TOOLS.includes(call.tool)) return DelegationStep.Lookup;
+  else if (RESET_TOOLS.includes(call.tool)) return DelegationStep.Reset;
+  else if (!SHELL_TOOLS.includes(call.tool)) return DelegationStep.Neutral;
+  const isLookup = call.run_in_background !== true && checkIsLookupCommand(call.command || "");
+  return isLookup ? DelegationStep.Lookup : DelegationStep.Reset;
+};

package/src/services/delegation/getLaunchRefusal.ts

@@ -0,0 +1,8 @@
+import type { AgentLaunch } from "../../models/AgentLaunch";
+
+import { AGENT_MODEL, AGENT_MODEL_REFUSAL } from "../constants";
+
+// Why an agent launch is refused, or undefined when it runs on the one model a subagent may. A fork never does, since
+// It runs on the parent's model whatever it names
+export const getLaunchRefusal = (launch: AgentLaunch): string | undefined =>
+  launch.subagent_type === "fork" || launch.model !== AGENT_MODEL ? AGENT_MODEL_REFUSAL : undefined;

package/src/services/delegation/getNextStreak.ts

@@ -0,0 +1,8 @@
+import { DelegationStep } from "../../models/DelegationStep";
+
+// The lookups in a row after one call: a lookup adds one, a reset clears the run, and a neutral call keeps it
+export const getNextStreak = (streak: number, step: DelegationStep): number => {
+  if (step === DelegationStep.Lookup) return streak + 1;
+  else if (step === DelegationStep.Reset) return 0;
+  else return streak;
+};

package/src/services/delegation/getNudge.ts

@@ -0,0 +1,5 @@
+import { DELEGATION_NUDGE, DELEGATION_NUDGE_EVERY } from "../constants";
+
+// The nudge owed by a streak: on the third lookup in a row and every third after it
+export const getNudge = (streak: number): string | undefined =>
+  streak > 0 && streak % DELEGATION_NUDGE_EVERY === 0 ? DELEGATION_NUDGE : undefined;

package/src/services/delegation/registerDelegation.ts

@@ -0,0 +1,46 @@
+import type { EngineInterface, On } from "claude-code";
+
+import { atom, update } from "claude-code";
+
+import type { DelegationCall } from "../../models/DelegationCall";
+
+import { DelegationStep } from "../../models/DelegationStep";
+import { InitialState } from "../InitialState";
+import { getCallStep } from "./getCallStep";
+import { getLaunchRefusal } from "./getLaunchRefusal";
+import { getNextStreak } from "./getNextStreak";
+import { getNudge } from "./getNudge";
+
+const lookupStreakAtom = atom({ key: "lookupStreak", plugin: "genshin-mods" } as const, InitialState.lookupStreak);
+
+// The count is one update, so calls the model sends in one batch each see the count the call before them left. The
+// Nudge is the count's, and a neutral call earns none
+const countCall = async ($: EngineInterface, call: DelegationCall): Promise<string | undefined> => {
+  const step = getCallStep(call);
+  if (step === DelegationStep.Neutral) return undefined;
+  const streak = await update($, lookupStreakAtom, (value) => getNextStreak(value, step));
+  return step === DelegationStep.Lookup ? getNudge(streak) : undefined;
+};
+
+// Any failure lets the call through, as the ward's does: a count that blocked on its own failure would block every
+// Call after it. `next` is replay-safe here, so a call the hook had already counted is not run twice
+const letCallThrough = <E, R>(_$: EngineInterface, e: E, next: (e: E) => R): R => next(e);
+
+export const registerDelegation = (on: On): void => {
+  // An agent launch on any model but haiku is refused before it counts. A nudge rides on the call's own result as
+  // Context the model reads after it, and never blocks the call
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on(
+    "tool.call",
+    { tool: ["Agent", "Bash", "Edit", "Glob", "Grep", "NotebookEdit", "PowerShell", "Read", "WebFetch", "Write"] },
+    async ($, e, next) => {
+      const refusal = e.tool === "Agent" ? getLaunchRefusal(e) : undefined;
+      if (refusal !== undefined) return { deny: refusal };
+      const nudge = await countCall($, e);
+      const result = await next(e);
+      return nudge !== undefined && result.deny === undefined
+        ? { ...result, context: [...(result.context ?? []), nudge] }
+        : result;
+    },
+  ).catch(letCallThrough);
+};

package/src/services/diskScan/getDiskScanRefusal.ts

@@ -0,0 +1,85 @@
+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));
+
+// A flag group holding r or R: `-R`, `-rn`, `-lR`, `--recursive`
+const isRecursiveFlag = (token: string) => /^-[a-zA-Z]*[rR]/u.test(token) || token === "--recursive";
+
+// The ls flag recurses on the capital R alone, since its lowercase r sorts in reverse
+const isUpperRecursiveFlag = (token: string) => /^-[a-zA-Z]*R/u.test(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) => isUpperRecursiveFlag(arg)) && args.some((arg) => isRoot(arg)) ? name : undefined;
+  const { flags, paths } = readGrepArguments(args);
+  return flags.some((flag) => isRecursiveFlag(flag)) && paths.some((path) => isRoot(path)) ? name : undefined;
+};
+
+const getScanCommandRefusal: CommandRefusal = (name, args) =>
+  SCAN_COMMANDS.has(name) ? getScanRefusal(name, args) : undefined;
+
+// 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 =>
+  getShellRefusal(command, getScanCommandRefusal);
+
+// 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[] = [
+  "- 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;",
+  "- `~/.claude/genshin-persona`, for the voice;",
+  "- 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/registerDiskScan.ts

@@ -0,0 +1,17 @@
+import type { EngineInterface, On } from "claude-code";
+
+import { getDenyReason, 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
+const letCommandThrough = <E, R>(_$: EngineInterface, e: E, next: (e: E) => R): R => next(e);
+
+// A Bash command that scans from a root or a home folder is refused before it runs: the scan reads the whole disk for
+// A file whose home is known, and the rule is cheapest enforced at the call itself
+export const registerDiskScan = (on: On): void => {
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: "Bash" }, (_$, e, next) => {
+    const refusal = getDiskScanRefusal(e.command);
+    return refusal === undefined ? next(e) : { deny: getDenyReason(refusal) };
+  }).catch(letCommandThrough);
+};

package/src/services/registerLifecycle.ts

@@ -4,10 +4,22 @@ import { atom, read, update } from "claude-code";
 
 import type { EnabledMods } from "../../types";
 
-import { CACHE_WARNING_MS, CLOCK_TICK_MS, VEIL_SECTION_ID, VEIL_SYSTEM_SECTION, WAYPOINTS_QUESTION } from "./constants";
+import {
+  CACHE_WARNING_MS,
+  MACHINE_WATCHER_RETRY_MILLISECONDS,
+  MACHINE_WATCHER_SCRIPT,
+  RESERVE_SECTION_ID,
+  VEIL_SECTION_ID,
+  VEIL_SYSTEM_SECTION,
+  WAYPOINTS_QUESTION,
+} from "./constants";
 import { InitialState } from "./InitialState";
 import { ModDescriptionMap, ModNames } from "./ModDescriptionMap";
 import { getCacheRemainingMs } from "./resin/getCacheRemainingMs";
+import { getCacheWarningDelayMs } from "./resin/getCacheWarningDelayMs";
+import { getReserveSummary } from "./resin/getReserveSummary";
+import { getReserveWindow } from "./resin/getReserveWindow";
+import { reserveText } from "./resin/reserveText";
 import { parseWaypoints } from "./waypoints/parseWaypoints";
 
 const commissionAtom = atom({ key: "commission", plugin: "genshin-mods" } as const, InitialState.commission);
@@ -21,7 +33,9 @@ const lastCacheRequestAtAtom = atom(
   { key: "lastCacheRequestAt", plugin: "genshin-mods" } as const,
   InitialState.lastCacheRequestAt,
 );
+const lookupStreakAtom = atom({ key: "lookupStreak", plugin: "genshin-mods" } as const, InitialState.lookupStreak);
 const nowAtom = atom({ key: "now", plugin: "genshin-mods" } as const, InitialState.now);
+const reserveWindowAtom = atom({ key: "reserveWindow", plugin: "genshin-mods" } as const, InitialState.reserveWindow);
 const waypointsAtom = atom({ key: "waypoints", plugin: "genshin-mods" } as const, InitialState.waypoints);
 
 // The events a plugin may hook once with no matcher, each hooked here for every mod, with the commands that switch
@@ -30,7 +44,11 @@ const waypointsAtom = atom({ key: "waypoints", plugin: "genshin-mods" } as const
 let warnedLastCacheRequestAt = 0;
 let isTurnRunning = false;
 
-const tick = async ($: EngineInterface) => {
+// The cache goes cold at a known instant, so its warning is one timer armed for that instant at each turn's end, from the
+// Request that last read or wrote the cache, rather than a check on a clock. The timer warns once for that request, and
+// Stands down while a turn runs, since that turn's end arms it again. A timer left from an earlier turn finds the cache
+// Renewed and does nothing more than the warning it would have given
+const warnCache = async ($: EngineInterface) => {
   const now = await $.clock.now();
   await update($, nowAtom, () => now);
   const lastCacheRequestAt = await read($, lastCacheRequestAtAtom);
@@ -48,11 +66,42 @@ const tick = async ($: EngineInterface) => {
   $.ui.toast("The prompt cache goes cold in five minutes: warm it, compact or hand off from the band.");
 };
 
+const armCacheWarning = async ($: EngineInterface) => {
+  const delayMs = getCacheWarningDelayMs(await read($, lastCacheRequestAtAtom), await $.clock.now());
+  if (delayMs === undefined) return;
+
+  $.clock.after(delayMs, () => {
+    // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and every call in the warning resolves
+    warnCache($);
+  });
+};
+
 const suggestWaypoints = async ($: EngineInterface) => {
   const answer = await $.model.fork({ prompt: WAYPOINTS_QUESTION });
   if (answer.isAnswered) await update($, waypointsAtom, () => parseWaypoints(answer.text));
 };
 
+// Keeps the machine watcher running as this session's child. The watcher writes the machine's state, holds its lock and
+// Pushes its heartbeat, so its output is read only to keep the child's pipe drained. A watcher exits at once while another
+// Session's holds the machine's lock, so each exit starts the watcher again after a wait, and the session that outlives the
+// One watching takes the watching over
+const watchPulse = async ($: EngineInterface) => {
+  if (!(await read($, enabledModsAtom)).pulse) return;
+
+  const cwd = await $.session.cwd();
+  if (!(await $.fs.exists(`${cwd}/${MACHINE_WATCHER_SCRIPT}`))) return;
+
+  // oxlint-disable-next-line no-underscore-dangle -- The chunks are discarded, and the binding is only the loop's syntax
+  for await (const _chunk of $.process.spawn({ argv: ["pnpm", "ai:machine:watch"], cwd })) {
+    // The watcher's output is discarded, since nothing in the session reads it
+  }
+
+  $.clock.after(MACHINE_WATCHER_RETRY_MILLISECONDS, () => {
+    // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and the watcher's run settles as its process exits
+    watchPulse($);
+  });
+};
+
 const closeCommission = async ($: EngineInterface) => {
   await update($, commissionAtom, () => InitialState.commission);
   await update($, isCommissionExpandedAtom, () => InitialState.isCommissionExpanded);
@@ -79,11 +128,7 @@ export const registerLifecycle = (on: On): void => {
         $.command.register({ argumentHint: "[on|off]", description: ModDescriptionMap[name], name }),
       ),
     );
-    // oxlint-disable-next-line unicorn/no-array-method-this-argument -- The engine's clock, not Array.prototype.every
-    $.clock.every(CLOCK_TICK_MS, () => {
-      // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and every call in the tick resolves
-      tick($);
-    });
+    watchPulse($);
     return next(e);
   });
 
@@ -100,21 +145,29 @@ export const registerLifecycle = (on: On): void => {
   });
 
   // The prompt is kept as the goal of a commission this turn may open, and a commission whose every task is done has
-  // Shown its finished row since the last turn ended, so it closes as the person moves on
+  // Shown its finished row since the last turn ended, so it closes as the person moves on. A new prompt also starts
+  // The lookup count again, since the lookups of the last turn are not the chain of this one
   on("prompt.submit", async ($, e, next) => {
     await update($, waypointsAtom, () => InitialState.waypoints);
+    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($);
     return next(e);
   });
 
-  // While the veil is on, the model is told to write placeholders too, so a reply never holds a value to hide
+  // While the veil is on, the model is told to write placeholders too, so a reply never holds a value to hide. While a
+  // Usage reserve holds and the resin mod is on, the model is told what the reserve's tier asks until the window resets,
+  // Which it may have done since the last measurement
   on("prompt.compose", async ($, e, next) => {
     const result = await next(e);
-    if ((await read($, enabledModsAtom)).veil)
-      return { sections: [...result.sections, { id: VEIL_SECTION_ID, scope: "session", text: VEIL_SYSTEM_SECTION }] };
-    else return result;
+    const { resin, veil } = await read($, enabledModsAtom);
+    const reserveWindow = await read($, reserveWindowAtom);
+    const sections = [...result.sections];
+    if (veil) sections.push({ id: VEIL_SECTION_ID, scope: "session", text: VEIL_SYSTEM_SECTION });
+    if (resin && reserveWindow.name && Date.parse(reserveWindow.resetsAt) > (await $.clock.now()))
+      sections.push({ id: RESERVE_SECTION_ID, scope: "session", text: reserveText(reserveWindow) });
+    return { sections };
   });
 
   on("turn.start", (_$, e, next) => {
@@ -144,6 +197,7 @@ export const registerLifecycle = (on: On): void => {
 
     const now = await $.clock.now();
     await update($, nowAtom, () => now);
+    await armCacheWarning($);
     if (e.reason === "answer" && (await read($, enabledModsAtom)).waypoints)
       $.clock.after(0, () => {
         // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and a fork resolves every outcome rather than rejecting
@@ -151,4 +205,22 @@ export const registerLifecycle = (on: On): void => {
       });
     return result;
   });
+
+  // The reserve is read off each measurement: it starts at the first window past a tier's line and lifts at the
+  // Measurement a window's reset raises, which finds none. The toast names the window once, as the reserve starts, and
+  // Again as its maintenance tier is raised to the wind-down
+  on("session.measure", async ($, e, next) => {
+    const now = await $.clock.now();
+    const reserveWindow = getReserveWindow(e.rateLimits, now);
+    const previousReserveWindow = await read($, reserveWindowAtom);
+    await update($, reserveWindowAtom, () => reserveWindow ?? InitialState.reserveWindow);
+    if (
+      reserveWindow &&
+      (!previousReserveWindow.name || (reserveWindow.isWindDown && !previousReserveWindow.isWindDown)) &&
+      (await read($, enabledModsAtom)).resin
+    )
+      $.ui.toast(`${getReserveSummary(reserveWindow)}.`);
+
+    return next(e);
+  });
 };

package/src/services/resin/RateLimitKindUsageWindowMap.ts

@@ -0,0 +1,27 @@
+import type { UsageWindow } from "../../models/UsageWindow";
+
+import {
+  FIVE_HOUR_MAINTENANCE_PERCENTAGE,
+  FIVE_HOUR_WIND_DOWN_PERCENTAGE,
+  FIVE_HOUR_WINDOW_MS,
+  WEEKLY_MAINTENANCE_PERCENTAGE,
+  WEEKLY_WIND_DOWN_PERCENTAGE,
+  WEEKLY_WINDOW_MS,
+} from "../constants";
+
+// The rate-limit windows a reserve is read off, five-hour before weekly, so the five-hour one is the one named when both
+// Have passed a line of the same tier
+export const RateLimitKindUsageWindowMap: Record<string, UsageWindow> = {
+  five_hour: {
+    durationMs: FIVE_HOUR_WINDOW_MS,
+    maintenancePercentage: FIVE_HOUR_MAINTENANCE_PERCENTAGE,
+    name: "five-hour",
+    windDownPercentage: FIVE_HOUR_WIND_DOWN_PERCENTAGE,
+  },
+  seven_day: {
+    durationMs: WEEKLY_WINDOW_MS,
+    maintenancePercentage: WEEKLY_MAINTENANCE_PERCENTAGE,
+    name: "weekly",
+    windDownPercentage: WEEKLY_WIND_DOWN_PERCENTAGE,
+  },
+};

package/src/services/resin/formatResetsAt.ts

@@ -0,0 +1,3 @@
+// The reset time as the reader's own clock spells it, such as `Oct 8, 2026, 5:00 PM`
+export const formatResetsAt = (resetsAt: string): string =>
+  Temporal.Instant.from(resetsAt).toLocaleString("en", { dateStyle: "medium", timeStyle: "short" });

package/src/services/resin/getCacheWarningDelayMs.ts

@@ -0,0 +1,7 @@
+import { CACHE_WARNING_MS } from "../constants";
+import { getCacheRemainingMs } from "./getCacheRemainingMs";
+
+// How long from `now` until the cache warning is due: the instant the cache goes cold less the warning margin.
+// Nothing is due while no request has read or written the cache, and a deadline already past the margin is due at once
+export const getCacheWarningDelayMs = (lastCacheRequestAt: number, now: number): number | undefined =>
+  lastCacheRequestAt > 0 ? Math.max(0, getCacheRemainingMs(lastCacheRequestAt, now) - CACHE_WARNING_MS) : undefined;

package/src/services/resin/getReserveSummary.ts

@@ -0,0 +1,8 @@
+import type { ReserveWindow } from "../../../types";
+
+import { formatResetsAt } from "./formatResetsAt";
+
+// The sentence a reserve opens with, naming its tier, window, the usage line that window has passed and its reset time,
+// Which the system section and the toast both say
+export const getReserveSummary = ({ isAheadOfPace, isWindDown, name, percentage, resetsAt }: ReserveWindow): string =>
+  `${isWindDown ? "Usage reserve" : "Usage maintenance"}: the ${name} usage window has passed ${percentage}%${isAheadOfPace ? " ahead of an even pace" : ""} and resets at ${formatResetsAt(resetsAt)}`;

package/src/services/resin/getReserveWindow.ts

@@ -0,0 +1,32 @@
+import type { SessionRateLimit } from "claude-code";
+
+import type { ReserveWindow } from "../../../types";
+
+import { PACE_FLOOR_PERCENTAGE } from "../constants";
+import { RateLimitKindUsageWindowMap } from "./RateLimitKindUsageWindowMap";
+
+// Each window a reserve is read off, five-hour before weekly, so the five-hour one is the one named when both have
+// Passed a line of the same tier. A window is read once past its maintenance line, or once half of its allowance is
+// Spent ahead of an even pace, the share of its length that has elapsed; the wind-down line is read as well. A window
+// The engine gives no reset time for is skipped, since the reserve is named by that time and lifts at it
+export const getReserveWindow = (rateLimits: SessionRateLimit[], now: number): ReserveWindow | undefined => {
+  const reserveWindows: ReserveWindow[] = [];
+  for (const [kind, { durationMs, maintenancePercentage, name, windDownPercentage }] of Object.entries(
+    RateLimitKindUsageWindowMap,
+  )) {
+    const rateLimit = rateLimits.find((limit) => limit.kind === kind);
+    if (rateLimit?.resetsAt === undefined) continue;
+    const isWindDown = rateLimit.percentUsed >= windDownPercentage;
+    const isPastMaintenance = rateLimit.percentUsed >= maintenancePercentage;
+    const elapsedPercentage = 100 * (1 - (Date.parse(rateLimit.resetsAt) - now) / durationMs);
+    const isAheadOfPace =
+      !isPastMaintenance && rateLimit.percentUsed >= PACE_FLOOR_PERCENTAGE && rateLimit.percentUsed > elapsedPercentage;
+    if (!isPastMaintenance && !isAheadOfPace) continue;
+    let percentage = PACE_FLOOR_PERCENTAGE;
+    if (isWindDown) percentage = windDownPercentage;
+    else if (isPastMaintenance) percentage = maintenancePercentage;
+    reserveWindows.push({ isAheadOfPace, isWindDown, name, percentage, resetsAt: rateLimit.resetsAt });
+  }
+
+  return reserveWindows.find(({ isWindDown }) => isWindDown) ?? reserveWindows[0];
+};

package/src/services/resin/registerReserveGate.ts

@@ -0,0 +1,27 @@
+import type { EngineInterface, On } from "claude-code";
+
+import { atom, read } from "claude-code";
+
+import { RESERVE_REFUSAL_INSTRUCTION } from "../constants";
+import { InitialState } from "../InitialState";
+import { getReserveSummary } from "./getReserveSummary";
+
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+const reserveWindowAtom = atom({ key: "reserveWindow", plugin: "genshin-mods" } as const, InitialState.reserveWindow);
+
+// Any failure lets the launch through, as the ward's does: a gate that blocked on its own failure would block every
+// Launch after it. `next` is replay-safe here, so a launch the hook had already decided is not run twice
+const letLaunchThrough = <E, R>(_$: EngineInterface, e: E, next: (e: E) => R): R => next(e);
+
+export const registerReserveGate = (on: On): void => {
+  // The section only describes the reserve, and a workflow already launched never reads it, so the launch itself is
+  // Refused while the reserve holds, past the window's reset too, which the next measurement is yet to read. An agent
+  // Launch is the delegation guard's, which refuses one on any model but haiku whether or not a reserve holds
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: ["Workflow"] }, async ($, e, next) => {
+    if (!(await read($, enabledModsAtom)).resin) return next(e);
+    const reserveWindow = await read($, reserveWindowAtom);
+    if (!reserveWindow.name || Date.parse(reserveWindow.resetsAt) <= (await $.clock.now())) return next(e);
+    return { deny: `${getReserveSummary(reserveWindow)}. ${RESERVE_REFUSAL_INSTRUCTION}` };
+  }).catch(letLaunchThrough);
+};

package/src/services/resin/reserveText.ts

@@ -0,0 +1,9 @@
+import type { ReserveWindow } from "../../../types";
+
+import { MAINTENANCE_INSTRUCTION, RESERVE_INSTRUCTION } from "../constants";
+import { getReserveSummary } from "./getReserveSummary";
+
+// The system section the reserve adds: its summary and the instruction of its tier are the only parts that vary, so the
+// Text holds still for as long as the tier does
+export const reserveText = (reserveWindow: ReserveWindow): string =>
+  `${getReserveSummary(reserveWindow)}. ${reserveWindow.isWindDown ? RESERVE_INSTRUCTION : MAINTENANCE_INSTRUCTION}`;

package/src/services/shell/getShellRefusal.ts

@@ -0,0 +1,85 @@
+import { joinDirectory } from "./joinDirectory";
+
+// 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;
+
+// A segment runs up to a separator outside quotes, so a quoted argument such as a `bash -c` command stays whole
+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>(
+  command: string,
+  getRefusal: CommandRefusal<T>,
+  depth = 0,
+  startDirectory = "",
+): T | undefined => {
+  if (depth < MAX_NESTING_DEPTH)
+    for (const body of [
+      ...getDollarSubstitutionBodies(command),
+      ...Array.from(command.matchAll(BACKTICK_SUBSTITUTION_REGEX), (match) => match.groups?.body ?? ""),
+    ]) {
+      const nested = getShellRefusal(body, getRefusal, depth + 1, startDirectory);
+      if (nested !== undefined) return nested;
+    }
+  let directory = startDirectory;
+  for (const segment of command.match(SEGMENT_REGEX) ?? []) {
+    const tokens = tokenize(segment);
+    const [commandName, target] = tokens;
+    if (commandName === "cd" && target !== undefined && !target.startsWith("~") && !target.startsWith("-"))
+      directory = joinDirectory(directory, target);
+    for (const [index, token] of tokens.entries()) {
+      const name = token.split(PATH_SEPARATOR_REGEX).pop() ?? "";
+      const refusal = getRefusal(name, tokens.slice(index + 1), directory);
+      if (refusal !== undefined) return refusal;
+      const previous = tokens[index - 1];
+      if (depth < MAX_NESTING_DEPTH && previous !== undefined && SHELL_FLAG_REGEX.test(previous) && /\s/u.test(token)) {
+        const nested = getShellRefusal(token, getRefusal, depth + 1, directory);
+        if (nested !== undefined) return nested;
+      }
+    }
+  }
+  return undefined;
+};

package/src/services/shell/joinDirectory.ts

@@ -0,0 +1,17 @@
+const ROOT_REGEX = /^(?:[a-zA-Z]:)?[/\\]/u;
+const SEPARATOR_REGEX = /[/\\]/u;
+
+// The folder `next` names from `base`: `next` itself where it is absolute, else the two joined, each `.` dropped and
+// Each `..` taking the folder before it, so a path read off a command compares with the paths the ward records
+export const joinDirectory = (base: string, next: string): string => {
+  if (next === "") return base;
+  const path = ROOT_REGEX.test(next) || base === "" ? next : `${base}/${next}`;
+  const root = ROOT_REGEX.exec(path)?.[0] ?? "";
+  const segments: string[] = [];
+  for (const segment of path.slice(root.length).split(SEPARATOR_REGEX))
+    if (segment === "" || segment === ".") continue;
+    else if (segment !== "..") segments.push(segment);
+    else if (segments.length > 0 && segments.at(-1) !== "..") segments.pop();
+    else if (root === "") segments.push(segment);
+  return `${root.replaceAll("\\", "/")}${segments.join("/")}`;
+};

package/src/services/ward/getCheckoutPeer.ts

@@ -0,0 +1,21 @@
+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();
+
+// 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
+export const getCheckoutPeer = (
+  records: Record<string, WardRecord>,
+  checkoutRoot: string,
+  sessionId: string,
+  now: number,
+): string | undefined => {
+  const root = `${getComparablePath(checkoutRoot)}/`;
+  return Object.entries(records).find(
+    ([path, record]) =>
+      getComparablePath(path).startsWith(root) && getCollidingRecord(record, sessionId, now) !== undefined,
+  )?.[0];
+};

package/src/services/ward/getParentFolder.ts

@@ -0,0 +1,5 @@
+// The folder above `folder`, undefined at a root
+export const getParentFolder = (folder: string): string | undefined => {
+  const parent = folder.replace(/[/\\][^/\\]*$/u, "");
+  return parent === folder || parent === "" ? undefined : parent;
+};

package/src/services/ward/getRecordsPath.ts

@@ -0,0 +1,3 @@
+// One file every session on the machine reads afresh, beside the persona's state, so an edit made a moment ago in
+// Another session is always seen
+export const getRecordsPath = (home: string): string => `${home}/.claude/genshin-mods/ward.json`;

package/src/services/ward/getWholeIndexRefusal.ts

@@ -0,0 +1,127 @@
+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 };
+};
+
+// 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/parseRecords.ts

@@ -0,0 +1,5 @@
+import type { WardRecord } from "../../../types";
+
+export const parseRecords = (text: string): Record<string, WardRecord> =>
+  // oxlint-disable-next-line no-restricted-properties -- The records hold numbers and ids, no date, and a mod cannot import the shared reviver
+  JSON.parse(text) as Record<string, WardRecord>;

package/src/services/ward/registerWard.ts

@@ -7,23 +7,20 @@ import type { WardRecord } from "../../../types";
 import { WardAnswer, WardAnswers } from "../../models/WardAnswer";
 import { InitialState } from "../InitialState";
 import { getCollidingRecord } from "./getCollidingRecord";
+import { getRecordsPath } from "./getRecordsPath";
 import { getRecordsWithEdit } from "./getRecordsWithEdit";
+import { parseRecords } from "./parseRecords";
 
 const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
 const AGE_FORMATTER = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
 
-// One file every session on the machine reads afresh, beside the persona's state, so an edit made a moment ago in
-// Another session is always seen
-const readRecordsPath = async ($: EngineInterface) => {
-  const home = (await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "";
-  return `${home}/.claude/genshin-mods/ward.json`;
-};
+// The records file under the person's home folder, the home read from this file's own environment lookup
+const resolveRecordsPath = async ($: EngineInterface): Promise<string> =>
+  getRecordsPath((await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "");
 
+// The records as the file holds them, none when it does not yet exist
 const readRecords = async ($: EngineInterface, path: string): Promise<Record<string, WardRecord>> =>
-  (await $.fs.exists(path))
-    ? // oxlint-disable-next-line no-restricted-properties -- The records hold numbers and ids, no date, and a mod cannot import the shared reviver
-      (JSON.parse(await $.fs.read(path)) as Record<string, WardRecord>)
-    : {};
+  (await $.fs.exists(path)) ? parseRecords(await $.fs.read(path)) : {};
 
 // Before the edit: the question, when another session's record calls for one. After it: the edit recorded
 const ward = async (
@@ -32,7 +29,7 @@ const ward = async (
   proceed: () => Promise<ToolCallResult>,
 ): Promise<ToolCallResult> => {
   if (!(await read($, enabledModsAtom)).ward) return proceed();
-  const recordsPath = await readRecordsPath($);
+  const recordsPath = await resolveRecordsPath($);
   const sessionId = await $.session.id();
   const now = await $.clock.now();
   const collision = getCollidingRecord((await readRecords($, recordsPath))[path], sessionId, now);

package/src/services/ward/registerWholeIndex.ts

@@ -0,0 +1,59 @@
+import type { EngineInterface, On, ToolCallResult } from "claude-code";
+
+import { atom, read } from "claude-code";
+
+import type { WardRecord } from "../../../types";
+
+import { InitialState } from "../InitialState";
+import { joinDirectory } from "../shell/joinDirectory";
+import { getCheckoutPeer } from "./getCheckoutPeer";
+import { getParentFolder } from "./getParentFolder";
+import { getRecordsPath } from "./getRecordsPath";
+import { getWholeIndexDenyReason, getWholeIndexRefusal } from "./getWholeIndexRefusal";
+import { parseRecords } from "./parseRecords";
+
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+
+// The records file under the person's home folder, the home read from this file's own environment lookup
+const resolveRecordsPath = async ($: EngineInterface): Promise<string> =>
+  getRecordsPath((await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "");
+
+// The records as the file holds them, none when it does not yet exist
+const readRecords = async ($: EngineInterface, path: string): Promise<Record<string, WardRecord>> =>
+  (await $.fs.exists(path)) ? parseRecords(await $.fs.read(path)) : {};
+
+// The nearest folder at or above `folder` holding a `.git`, a worktree's file included, undefined when none does
+const findCheckoutRoot = async ($: EngineInterface, folder: string): Promise<string | undefined> => {
+  if (await $.fs.exists(`${folder}/.git`)) return folder;
+  const parent = getParentFolder(folder);
+  return parent === undefined ? undefined : findCheckoutRoot($, parent);
+};
+
+// The checkout a session's git commands run in: the folder with the `.git`, or the session's own folder where none is
+const getCheckoutRoot = async ($: EngineInterface, cwd: string): Promise<string> =>
+  (await findCheckoutRoot($, cwd)) ?? cwd;
+
+// A whole-index git command is refused while the ward's records show another session editing the checkout it runs in,
+// The session's folder moved by a `cd` before it and by its `-C`. With the Ward off nothing is recorded, so there is no
+// Peer to see and the command runs
+const wholeIndex = async (
+  $: EngineInterface,
+  command: string,
+  proceed: () => Promise<ToolCallResult>,
+): Promise<ToolCallResult> => {
+  const refusal = getWholeIndexRefusal(command);
+  if (refusal === undefined || !(await read($, enabledModsAtom)).ward) return proceed();
+  const records = await readRecords($, await resolveRecordsPath($));
+  const checkoutRoot = await getCheckoutRoot($, joinDirectory(await $.session.cwd(), refusal.directory));
+  const peerPath = getCheckoutPeer(records, checkoutRoot, await $.session.id(), await $.clock.now());
+  return peerPath === undefined ? proceed() : { deny: getWholeIndexDenyReason(refusal.form, peerPath) };
+};
+
+// Any failure lets the command through, as the disk-scan guard's does: a guard that blocked on its own failure would
+// Block every command after it
+const letCommandThrough = <E, R>(_$: EngineInterface, e: E, next: (e: E) => R): R => next(e);
+
+export const registerWholeIndex = (on: On): void => {
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: "Bash" }, ($, e, next) => wholeIndex($, e.command, () => next(e))).catch(letCommandThrough);
+};

package/types/index.d.ts

@@ -16,12 +16,24 @@ export interface CommissionTask {
 // Which mods are on, each switched by its own command and kept in the store as one record
 export interface EnabledMods {
   commission: boolean;
+  pulse: boolean;
   resin: boolean;
   veil: boolean;
   ward: boolean;
   waypoints: boolean;
 }
 
+// The rate-limit window past a usage line, named as its section spells it, the line it has passed, whether that line is
+// The wind-down rather than the maintenance tier, whether the tier was entered by spending ahead of an even pace rather
+// Than by the window's maintenance line, and when it resets; `""` in the name is the absent reserve
+export interface ReserveWindow {
+  isAheadOfPace: boolean;
+  isWindDown: boolean;
+  name: string;
+  percentage: number;
+  resetsAt: string;
+}
+
 export interface WardRecord {
   editedAt: number;
   sessionId: string;
@@ -36,7 +48,9 @@ declare module "claude-code" {
       isHandingOff: boolean;
       lastCacheRequestAt: number;
       lastPrompt: string;
+      lookupStreak: number;
       now: number;
+      reserveWindow: ReserveWindow;
       waypoints: string[];
     };
   }