@webpieces/ai-hook-rules 0.4.509 → 0.4.511

package/src/core/rules/stale-main-message.d.ts

@@ -15,6 +15,18 @@
  * fails loudly without touching anything.
  */
 export declare class StaleMainMessage {
+    private readonly treeRoot;
+    /**
+     * `treeRoot` is the tree the guard JUDGED (which is NOT the shell's cwd when the command carried
+     * a leading `cd`). Pass it and the cure is rendered as `cd <treeRoot> && git pull …`, naming the
+     * directory outright.
+     *
+     * WHY that matters here specifically: in the field this guard told an agent working in a worktree
+     * to `git pull` — which, run from wherever the next tool call happened to start, meant pulling the
+     * PRIMARY CLONE, a tree that agent had been explicitly instructed not to touch. A remedy must
+     * never mutate a tree other than the one the command targeted, and naming it is how you ensure it.
+     */
+    constructor(treeRoot?: string);
     private common;
     forReads(behindCount: string): string;
     /**

package/src/core/rules/stale-main-message.js

@@ -18,15 +18,31 @@ exports.StaleMainMessage = void 0;
  * fails loudly without touching anything.
  */
 class StaleMainMessage {
+    treeRoot;
+    /**
+     * `treeRoot` is the tree the guard JUDGED (which is NOT the shell's cwd when the command carried
+     * a leading `cd`). Pass it and the cure is rendered as `cd <treeRoot> && git pull …`, naming the
+     * directory outright.
+     *
+     * WHY that matters here specifically: in the field this guard told an agent working in a worktree
+     * to `git pull` — which, run from wherever the next tool call happened to start, meant pulling the
+     * PRIMARY CLONE, a tree that agent had been explicitly instructed not to touch. A remedy must
+     * never mutate a tree other than the one the command targeted, and naming it is how you ensure it.
+     */
+    constructor(treeRoot = '') {
+        this.treeRoot = treeRoot;
+    }
     // The diagnosis + cure. Identical for both guards — the part that must never drift.
     common(behindCount) {
+        const pull = 'git pull --ff-only origin main';
         return [
             `You are on main and main is ${behindCount} commit(s) behind origin/main.`,
+            ...(this.treeRoot !== '' ? [`Evaluated against: ${this.treeRoot}  (branch main)`] : []),
             'Anything you read here is STALE, and every plan built from it is built on code that no',
             'longer exists upstream.',
             '',
             'Run exactly this, then retry:',
-            '  git pull --ff-only origin main',
+            `  ${this.treeRoot !== '' ? `cd ${this.treeRoot} && ${pull}` : pull}`,
             '',
             'If that fatals with "Cannot fast-forward to multiple branches", .git/FETCH_HEAD holds a',
             'duplicate entry — clear it with `git fetch --prune origin main`, then pull again.',

package/src/core/rules/stale-main-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"stale-main-message.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/stale-main-message.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,gBAAgB;IACzB,oFAAoF;IAC5E,MAAM,CAAC,WAAmB;QAC9B,OAAO;YACH,+BAA+B,WAAW,gCAAgC;YAC1E,wFAAwF;YACxF,yBAAyB;YACzB,EAAE;YACF,+BAA+B;YAC/B,kCAAkC;YAClC,EAAE;YACF,yFAAyF;YACzF,mFAAmF;SACtF,CAAC;IACN,CAAC;IAED,QAAQ,CAAC,WAAmB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;YACnC,EAAE;YACF,uCAAuC;YACvC,2FAA2F;YAC3F,mDAAmD;YACnD,oEAAoE;YACpE,0FAA0F;SAC7F,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,WAAmB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;YACnC,EAAE;YACF,yFAAyF;YACzF,wFAAwF;YACxF,yFAAyF;YACzF,yFAAyF;YACzF,EAAE;YACF,qDAAqD;YACrD,wFAAwF;YACxF,uFAAuF;YACvF,sGAAsG;YACtG,uGAAuG;SAC1G,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;CACJ;AA/CD,4CA+CC","sourcesContent":["/**\n * The \"you are on a stale main\" text, shared by the TWO guards that detect the state from the same\n * cached signal (`MainSyncStatus.localMain` vs `originMain`):\n *\n *   - read-stale-guard        blocks the Read tool     → {@link StaleMainMessage.forReads}\n *   - stale-main-bash-guard   blocks content-read Bash → {@link StaleMainMessage.forBash}\n *\n * One source of truth on purpose (same reason as MergedBranchMessage): the cure is an instruction the\n * AI follows literally, so two drifting copies mean two behaviors for one repo state. Only the\n * \"what is still allowed\" tail differs, because the two guards block different tools.\n *\n * The cure is `--ff-only` deliberately. A plain `git pull` on a stale main can start a MERGE, which\n * is the one thing redirect-how-to-merge-main exists to keep an AI away from; `--ff-only` either\n * fast-forwards (the case here, since the block only fires when the tree is clean and behind) or\n * fails loudly without touching anything.\n */\nexport class StaleMainMessage {\n    // The diagnosis + cure. Identical for both guards — the part that must never drift.\n    private common(behindCount: string): string[] {\n        return [\n            `You are on main and main is ${behindCount} commit(s) behind origin/main.`,\n            'Anything you read here is STALE, and every plan built from it is built on code that no',\n            'longer exists upstream.',\n            '',\n            'Run exactly this, then retry:',\n            '  git pull --ff-only origin main',\n            '',\n            'If that fatals with \"Cannot fast-forward to multiple branches\", .git/FETCH_HEAD holds a',\n            'duplicate entry — clear it with `git fetch --prune origin main`, then pull again.',\n        ];\n    }\n\n    forReads(behindCount: string): string {\n        return this.common(behindCount).concat([\n            '',\n            'Still allowed while this block is up:',\n            '  - Bash that does not read repo files: builds, tests, installs, the pull itself, and all',\n            '    git/gh METADATA (status|log|diff|show|branch)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n        ]).join('\\n');\n    }\n\n    /**\n     * The Bash variant. stale-main-bash-guard blocks only CONTENT reads, so the message has to say\n     * which shell is still open — an agent that reads \"Bash blocked\" and believes the whole shell is\n     * gone will not run the cure, which is itself a Bash command.\n     */\n    forBash(behindCount: string): string {\n        return this.common(behindCount).concat([\n            '',\n            'This command was blocked because it reads FILE CONTENT out of the stale tree (cat/grep/',\n            'ls/find/sed/awk/git grep/git show <rev>:<path>). That is how stale bytes get into your',\n            'context and quietly poison everything you conclude — the incident behind this guard had',\n            'an agent describing a CI workflow set that was missing a whole workflow added upstream.',\n            '',\n            'Still allowed right now (the cure is one of these):',\n            '  - git pull/fetch, installs, upgrades, builds, tests, every other non-reading command',\n            '  - git/gh METADATA: status, log, diff, show <rev>, branch, rev-list, gh pr list|view',\n            '  - reads against the CURRENT upstream tree: git show origin/main:<path>, git grep <pat> origin/main',\n            '  - all Write/Edit, and reading webpieces.config.json (set stale-main-bash-guard mode OFF to disable)',\n        ]).join('\\n');\n    }\n}\n"]}
+{"version":3,"file":"stale-main-message.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/stale-main-message.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,gBAAgB;IAWI;IAV7B;;;;;;;;;OASG;IACH,YAA6B,WAAmB,EAAE;QAArB,aAAQ,GAAR,QAAQ,CAAa;IAAG,CAAC;IAEtD,oFAAoF;IAC5E,MAAM,CAAC,WAAmB;QAC9B,MAAM,IAAI,GAAG,gCAAgC,CAAC;QAC9C,OAAO;YACH,+BAA+B,WAAW,gCAAgC;YAC1E,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,sBAAsB,IAAI,CAAC,QAAQ,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,wFAAwF;YACxF,yBAAyB;YACzB,EAAE;YACF,+BAA+B;YAC/B,KAAK,IAAI,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE;YACrE,EAAE;YACF,yFAAyF;YACzF,mFAAmF;SACtF,CAAC;IACN,CAAC;IAED,QAAQ,CAAC,WAAmB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;YACnC,EAAE;YACF,uCAAuC;YACvC,2FAA2F;YAC3F,mDAAmD;YACnD,oEAAoE;YACpE,0FAA0F;SAC7F,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,WAAmB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;YACnC,EAAE;YACF,yFAAyF;YACzF,wFAAwF;YACxF,yFAAyF;YACzF,yFAAyF;YACzF,EAAE;YACF,qDAAqD;YACrD,wFAAwF;YACxF,uFAAuF;YACvF,sGAAsG;YACtG,uGAAuG;SAC1G,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;CACJ;AA7DD,4CA6DC","sourcesContent":["/**\n * The \"you are on a stale main\" text, shared by the TWO guards that detect the state from the same\n * cached signal (`MainSyncStatus.localMain` vs `originMain`):\n *\n *   - read-stale-guard        blocks the Read tool     → {@link StaleMainMessage.forReads}\n *   - stale-main-bash-guard   blocks content-read Bash → {@link StaleMainMessage.forBash}\n *\n * One source of truth on purpose (same reason as MergedBranchMessage): the cure is an instruction the\n * AI follows literally, so two drifting copies mean two behaviors for one repo state. Only the\n * \"what is still allowed\" tail differs, because the two guards block different tools.\n *\n * The cure is `--ff-only` deliberately. A plain `git pull` on a stale main can start a MERGE, which\n * is the one thing redirect-how-to-merge-main exists to keep an AI away from; `--ff-only` either\n * fast-forwards (the case here, since the block only fires when the tree is clean and behind) or\n * fails loudly without touching anything.\n */\nexport class StaleMainMessage {\n    /**\n     * `treeRoot` is the tree the guard JUDGED (which is NOT the shell's cwd when the command carried\n     * a leading `cd`). Pass it and the cure is rendered as `cd <treeRoot> && git pull …`, naming the\n     * directory outright.\n     *\n     * WHY that matters here specifically: in the field this guard told an agent working in a worktree\n     * to `git pull` — which, run from wherever the next tool call happened to start, meant pulling the\n     * PRIMARY CLONE, a tree that agent had been explicitly instructed not to touch. A remedy must\n     * never mutate a tree other than the one the command targeted, and naming it is how you ensure it.\n     */\n    constructor(private readonly treeRoot: string = '') {}\n\n    // The diagnosis + cure. Identical for both guards — the part that must never drift.\n    private common(behindCount: string): string[] {\n        const pull = 'git pull --ff-only origin main';\n        return [\n            `You are on main and main is ${behindCount} commit(s) behind origin/main.`,\n            ...(this.treeRoot !== '' ? [`Evaluated against: ${this.treeRoot}  (branch main)`] : []),\n            'Anything you read here is STALE, and every plan built from it is built on code that no',\n            'longer exists upstream.',\n            '',\n            'Run exactly this, then retry:',\n            `  ${this.treeRoot !== '' ? `cd ${this.treeRoot} && ${pull}` : pull}`,\n            '',\n            'If that fatals with \"Cannot fast-forward to multiple branches\", .git/FETCH_HEAD holds a',\n            'duplicate entry — clear it with `git fetch --prune origin main`, then pull again.',\n        ];\n    }\n\n    forReads(behindCount: string): string {\n        return this.common(behindCount).concat([\n            '',\n            'Still allowed while this block is up:',\n            '  - Bash that does not read repo files: builds, tests, installs, the pull itself, and all',\n            '    git/gh METADATA (status|log|diff|show|branch)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n        ]).join('\\n');\n    }\n\n    /**\n     * The Bash variant. stale-main-bash-guard blocks only CONTENT reads, so the message has to say\n     * which shell is still open — an agent that reads \"Bash blocked\" and believes the whole shell is\n     * gone will not run the cure, which is itself a Bash command.\n     */\n    forBash(behindCount: string): string {\n        return this.common(behindCount).concat([\n            '',\n            'This command was blocked because it reads FILE CONTENT out of the stale tree (cat/grep/',\n            'ls/find/sed/awk/git grep/git show <rev>:<path>). That is how stale bytes get into your',\n            'context and quietly poison everything you conclude — the incident behind this guard had',\n            'an agent describing a CI workflow set that was missing a whole workflow added upstream.',\n            '',\n            'Still allowed right now (the cure is one of these):',\n            '  - git pull/fetch, installs, upgrades, builds, tests, every other non-reading command',\n            '  - git/gh METADATA: status, log, diff, show <rev>, branch, rev-list, gh pr list|view',\n            '  - reads against the CURRENT upstream tree: git show origin/main:<path>, git grep <pat> origin/main',\n            '  - all Write/Edit, and reading webpieces.config.json (set stale-main-bash-guard mode OFF to disable)',\n        ]).join('\\n');\n    }\n}\n"]}

package/src/core/rules/tree-recovery.d.ts

@@ -22,9 +22,25 @@
  */
 export type TreeKind = 'worktree' | 'branch' | 'unknown';
 export declare class TreeRecovery {
+    private readonly treeRoot;
     private readonly worktrees;
+    /**
+     * `treeRoot` is the tree the guard JUDGED. When it is given, every command below is rendered as
+     * `cd <treeRoot> && <command>`.
+     *
+     * WHY: a Bash tool call does NOT persist `cd` between calls, so an agent working in a linked
+     * worktree starts every call back in the primary clone. A bare `git fetch origin main` therefore
+     * runs against the WRONG tree — and in the field a guard prescribed `git pull` in a primary clone
+     * the agent had been explicitly forbidden to touch. Naming the directory in the command itself is
+     * the only form that is correct no matter where the next tool call starts. A leading `cd <path> &&`
+     * cannot change what a command does to a repo, so the guards accept it.
+     *
+     * Empty (the default) renders the bare commands, for callers with no root to name.
+     */
+    constructor(treeRoot?: string);
     /** The kind of tree rooted at `root`, for callers that have a workspace root and no other info. */
     kindOf(root: string): TreeKind;
+    private at;
     /**
      * Start fresh off current main. Both forms base explicitly on `origin/main` — the only base that
      * works from ANY tree (branch-creation-guard allows it unconditionally for that reason).

package/src/core/rules/tree-recovery.js

@@ -3,11 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TreeRecovery = void 0;
 const rules_config_1 = require("@webpieces/rules-config");
 class TreeRecovery {
+    treeRoot;
     worktrees = new rules_config_1.WorktreeService();
+    /**
+     * `treeRoot` is the tree the guard JUDGED. When it is given, every command below is rendered as
+     * `cd <treeRoot> && <command>`.
+     *
+     * WHY: a Bash tool call does NOT persist `cd` between calls, so an agent working in a linked
+     * worktree starts every call back in the primary clone. A bare `git fetch origin main` therefore
+     * runs against the WRONG tree — and in the field a guard prescribed `git pull` in a primary clone
+     * the agent had been explicitly forbidden to touch. Naming the directory in the command itself is
+     * the only form that is correct no matter where the next tool call starts. A leading `cd <path> &&`
+     * cannot change what a command does to a repo, so the guards accept it.
+     *
+     * Empty (the default) renders the bare commands, for callers with no root to name.
+     */
+    constructor(treeRoot = '') {
+        this.treeRoot = treeRoot;
+    }
     /** The kind of tree rooted at `root`, for callers that have a workspace root and no other info. */
     kindOf(root) {
         return this.worktrees.isLinkedWorktree(root) ? 'worktree' : 'branch';
     }
+    // Render one command in the form that survives a tool call: `cd <root> && <command>`.
+    at(command) {
+        return this.treeRoot === '' ? command : `cd ${this.treeRoot} && ${command}`;
+    }
     /**
      * Start fresh off current main. Both forms base explicitly on `origin/main` — the only base that
      * works from ANY tree (branch-creation-guard allows it unconditionally for that reason).
@@ -21,12 +42,12 @@ class TreeRecovery {
             ? '<feature-dir>'
             : newBranchName.replace(/\//g, '-');
         const branchForm = [
-            '  git fetch origin main',
-            `  git checkout -b ${newBranchName} origin/main`,
+            `  ${this.at('git fetch origin main')}`,
+            `  ${this.at(`git checkout -b ${newBranchName} origin/main`)}`,
         ];
         const worktreeForm = [
-            '  git fetch origin main',
-            `  git worktree add ../${dir} -b ${newBranchName} origin/main`,
+            `  ${this.at('git fetch origin main')}`,
+            `  ${this.at(`git worktree add ../${dir} -b ${newBranchName} origin/main`)}`,
         ];
         if (kind === 'worktree') {
             return [
@@ -68,7 +89,7 @@ class TreeRecovery {
      * delete ordering is the part that has to be exactly right.
      */
     cleanupSteps(kind, branch, worktreePath = '<worktree-dir>') {
-        const branchForm = '  git checkout main && git pull origin main && pnpm wp-cleanup';
+        const branchForm = `  ${this.at('git checkout main && git pull origin main && pnpm wp-cleanup')}`;
         const worktreeForm = `  git worktree prune && git worktree remove ${worktreePath} && git branch -D ${branch}`;
         if (kind === 'worktree') {
             return [
@@ -95,8 +116,8 @@ class TreeRecovery {
      * you need to then branch off `origin/main`.
      */
     updateMainSteps(kind) {
-        const branchForm = '  git checkout main && git pull origin main';
-        const worktreeForm = '  git fetch origin main        (then work off origin/main)';
+        const branchForm = `  ${this.at('git checkout main && git pull origin main')}`;
+        const worktreeForm = `  ${this.at('git fetch origin main')}        (then work off origin/main)`;
         if (kind === 'worktree') {
             return [
                 'You are in a linked worktree — `git checkout main` fatals here (main is checked out in',

package/src/core/rules/tree-recovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree-recovery.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/tree-recovery.ts"],"names":[],"mappings":";;;AAAA,0DAA0D;AA0B1D,MAAa,YAAY;IACJ,SAAS,GAAG,IAAI,8BAAe,EAAE,CAAC;IAEnD,mGAAmG;IACnG,MAAM,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzE,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,IAAc,EAAE,gBAAwB,sBAAsB;QAC1E,6FAA6F;QAC7F,8FAA8F;QAC9F,8FAA8F;QAC9F,yDAAyD;QACzD,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC;YACnC,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG;YACf,yBAAyB;YACzB,qBAAqB,aAAa,cAAc;SACnD,CAAC;QACF,MAAM,YAAY,GAAG;YACjB,yBAAyB;YACzB,yBAAyB,GAAG,OAAO,aAAa,cAAc;SACjE,CAAC;QAEF,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACtB,OAAO;gBACH,wFAAwF;gBACxF,6DAA6D;gBAC7D,GAAG,YAAY;aAClB,CAAC;QACN,CAAC;QACD,6FAA6F;QAC7F,iFAAiF;QACjF,8FAA8F;QAC9F,0FAA0F;QAC1F,0FAA0F;QAC1F,qCAAqC;QACrC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpB,OAAO,CAAC,+EAA+E,EAAE,GAAG,UAAU,CAAC,CAAC;QAC5G,CAAC;QACD,OAAO;YACH,qEAAqE;YACrE,2BAA2B;YAC3B,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YACxD,8DAA8D;YAC9D,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;SAC7D,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,IAAc,EAAE,MAAc,EAAE,eAAuB,gBAAgB;QAChF,MAAM,UAAU,GAAG,gEAAgE,CAAC;QACpF,MAAM,YAAY,GACd,+CAA+C,YAAY,qBAAqB,MAAM,EAAE,CAAC;QAE7F,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACtB,OAAO;gBACH,wFAAwF;gBACxF,8EAA8E;gBAC9E,YAAY;aACf,CAAC;QACN,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpB,OAAO,CAAC,6BAA6B,EAAE,UAAU,CAAC,CAAC;QACvD,CAAC;QACD,OAAO;YACH,kDAAkD;YAClD,2BAA2B;YAC3B,KAAK,UAAU,EAAE;YACjB,0FAA0F;YAC1F,yCAAyC;YACzC,KAAK,YAAY,EAAE;SACtB,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,IAAc;QAC1B,MAAM,UAAU,GAAG,6CAA6C,CAAC;QACjE,MAAM,YAAY,GAAG,4DAA4D,CAAC;QAElF,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACtB,OAAO;gBACH,wFAAwF;gBACxF,6DAA6D;gBAC7D,YAAY;aACf,CAAC;QACN,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpB,OAAO,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QACxC,CAAC;QACD,OAAO;YACH,qDAAqD;YACrD,2BAA2B;YAC3B,KAAK,UAAU,EAAE;YACjB,8DAA8D;YAC9D,KAAK,YAAY,EAAE;SACtB,CAAC;IACN,CAAC;CACJ;AAzHD,oCAyHC","sourcesContent":["import { WorktreeService } from '@webpieces/rules-config';\n\n/**\n * Renders the \"get onto a healthy tree\" commands, in the flavour of the tree the AI is standing in.\n *\n * WHY this exists: the SAME recovery advice takes different commands in a linked worktree than in\n * the primary clone, and getting it wrong is not a cosmetic problem — the AI runs these strings\n * literally:\n *\n *   - `git checkout main` FATALS in a linked worktree (\"main is already checked out at <primary>\"),\n *     so any message that recommends it burns a turn and then strands the agent.\n *   - a dead linked worktree is reaped with prune → remove → `git branch -D`, in that exact order,\n *     because git flatly refuses to delete a branch a worktree still holds. `git branch -d` alone\n *     just fails.\n *\n * Four guards used to hand-write these two forms independently (feature-branch-guard,\n * read-stale-guard, pr-merge-guard, redirect-how-to-merge-main), so they drifted. This is the one\n * place they come from now.\n *\n * The `TreeKind` contract, and why UNKNOWN prints BOTH: detection is a cheap local probe that can\n * fail (see WorktreeService.isLinkedWorktree). When we KNOW, we print exactly the one command that\n * works there — no menu for the AI to mis-pick from. When we do NOT know, we print both, clearly\n * labelled, because a labelled choice is recoverable and a confidently-wrong command is not.\n */\nexport type TreeKind = 'worktree' | 'branch' | 'unknown';\n\nexport class TreeRecovery {\n    private readonly worktrees = new WorktreeService();\n\n    /** The kind of tree rooted at `root`, for callers that have a workspace root and no other info. */\n    kindOf(root: string): TreeKind {\n        return this.worktrees.isLinkedWorktree(root) ? 'worktree' : 'branch';\n    }\n\n    /**\n     * Start fresh off current main. Both forms base explicitly on `origin/main` — the only base that\n     * works from ANY tree (branch-creation-guard allows it unconditionally for that reason).\n     */\n    freshStartSteps(kind: TreeKind, newBranchName: string = '<new-feature-branch>'): string[] {\n        // The worktree DIRECTORY cannot carry the branch's slashes. When the branch name is itself a\n        // placeholder the AI must fill in, keep the directory a readable placeholder too — sanitizing\n        // `<new-feature-branch>` produced `../-new-feature-branch-`, which reads like a real path and\n        // is exactly the kind of thing an agent pastes verbatim.\n        const dir = newBranchName.includes('<')\n            ? '<feature-dir>'\n            : newBranchName.replace(/\\//g, '-');\n        const branchForm = [\n            '  git fetch origin main',\n            `  git checkout -b ${newBranchName} origin/main`,\n        ];\n        const worktreeForm = [\n            '  git fetch origin main',\n            `  git worktree add ../${dir} -b ${newBranchName} origin/main`,\n        ];\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree (`git checkout main` fatals here — main is checked out in',\n                'the primary clone). Start the new work in its own worktree:',\n                ...worktreeForm,\n            ];\n        }\n        // The primary clone. NO \"never `git checkout main`\" here: that is a WORKTREE-only truth, and\n        // printing it in the primary clone forbids the shortest exit off a merged branch\n        // (`git checkout main && git pull origin main && pnpm wp-cleanup` — the exact command a human\n        // had to hand an agent that had wedged itself following this very message). Branching off\n        // origin/main is still what we RECOMMEND, because it works from any tree; it is no longer\n        // dressed up as the only legal move.\n        if (kind === 'branch') {\n            return ['Start fresh — branch off origin/main (works from here and from any worktree):', ...branchForm];\n        }\n        return [\n            'Start fresh off origin/main. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            ...branchForm.map((line: string): string => `  ${line}`),\n            '  - in a linked worktree (`git checkout main` fatals there):',\n            ...worktreeForm.map((line: string): string => `  ${line}`),\n        ];\n    }\n\n    /**\n     * Reap the tree you just finished with. The worktree order is load-bearing: prune clears\n     * worktrees whose directory is already gone (`git worktree remove` FAILS on those), and the\n     * branch delete must come LAST because git refuses to delete a branch a worktree still holds.\n     *\n     * The BRANCH form ends in `pnpm wp-cleanup`, not `git branch -d <branch>`. An agent reads a bare\n     * `-d`/`-D` as destructive and stops to ask permission, so the branch survives the turn and local\n     * branches pile up — the exact failure this whole cleanup path exists to prevent. wp-cleanup is\n     * one named command that deletes only provably-dead branches (and reaps every OTHER dead one at\n     * the same time), so it is safe to allowlist and never needs a judgement call.\n     *\n     * The WORKTREE form still spells out git commands: wp-cleanup deliberately reaps parked branches\n     * only — a worktree-held branch is spared — so it cannot do this job, and the prune → remove →\n     * delete ordering is the part that has to be exactly right.\n     */\n    cleanupSteps(kind: TreeKind, branch: string, worktreePath: string = '<worktree-dir>'): string[] {\n        const branchForm = '  git checkout main && git pull origin main && pnpm wp-cleanup';\n        const worktreeForm =\n            `  git worktree prune && git worktree remove ${worktreePath} && git branch -D ${branch}`;\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree — remove the worktree first, then the branch (git refuses',\n                'to delete a branch a worktree still holds). Run this from the PRIMARY clone:',\n                worktreeForm,\n            ];\n        }\n        if (kind === 'branch') {\n            return ['Clean up the merged branch:', branchForm];\n        }\n        return [\n            'Clean up. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            `  ${branchForm}`,\n            '  - for a linked worktree (run from the primary clone; `git branch -d` alone fails while',\n            '    a worktree still holds the branch):',\n            `  ${worktreeForm}`,\n        ];\n    }\n\n    /**\n     * Bring main up to date. In a linked worktree there is nothing to check out — `main` lives in\n     * the primary clone — so the update is a plain fetch of the remote-tracking ref, which is all\n     * you need to then branch off `origin/main`.\n     */\n    updateMainSteps(kind: TreeKind): string[] {\n        const branchForm = '  git checkout main && git pull origin main';\n        const worktreeForm = '  git fetch origin main        (then work off origin/main)';\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree — `git checkout main` fatals here (main is checked out in',\n                'the primary clone). Update the remote-tracking ref instead:',\n                worktreeForm,\n            ];\n        }\n        if (kind === 'branch') {\n            return ['Update main:', branchForm];\n        }\n        return [\n            'Update main. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            `  ${branchForm}`,\n            '  - in a linked worktree (`git checkout main` fatals there):',\n            `  ${worktreeForm}`,\n        ];\n    }\n}\n"]}
+{"version":3,"file":"tree-recovery.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/tree-recovery.ts"],"names":[],"mappings":"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","sourcesContent":["import { WorktreeService } from '@webpieces/rules-config';\n\n/**\n * Renders the \"get onto a healthy tree\" commands, in the flavour of the tree the AI is standing in.\n *\n * WHY this exists: the SAME recovery advice takes different commands in a linked worktree than in\n * the primary clone, and getting it wrong is not a cosmetic problem — the AI runs these strings\n * literally:\n *\n *   - `git checkout main` FATALS in a linked worktree (\"main is already checked out at <primary>\"),\n *     so any message that recommends it burns a turn and then strands the agent.\n *   - a dead linked worktree is reaped with prune → remove → `git branch -D`, in that exact order,\n *     because git flatly refuses to delete a branch a worktree still holds. `git branch -d` alone\n *     just fails.\n *\n * Four guards used to hand-write these two forms independently (feature-branch-guard,\n * read-stale-guard, pr-merge-guard, redirect-how-to-merge-main), so they drifted. This is the one\n * place they come from now.\n *\n * The `TreeKind` contract, and why UNKNOWN prints BOTH: detection is a cheap local probe that can\n * fail (see WorktreeService.isLinkedWorktree). When we KNOW, we print exactly the one command that\n * works there — no menu for the AI to mis-pick from. When we do NOT know, we print both, clearly\n * labelled, because a labelled choice is recoverable and a confidently-wrong command is not.\n */\nexport type TreeKind = 'worktree' | 'branch' | 'unknown';\n\nexport class TreeRecovery {\n    private readonly worktrees = new WorktreeService();\n\n    /**\n     * `treeRoot` is the tree the guard JUDGED. When it is given, every command below is rendered as\n     * `cd <treeRoot> && <command>`.\n     *\n     * WHY: a Bash tool call does NOT persist `cd` between calls, so an agent working in a linked\n     * worktree starts every call back in the primary clone. A bare `git fetch origin main` therefore\n     * runs against the WRONG tree — and in the field a guard prescribed `git pull` in a primary clone\n     * the agent had been explicitly forbidden to touch. Naming the directory in the command itself is\n     * the only form that is correct no matter where the next tool call starts. A leading `cd <path> &&`\n     * cannot change what a command does to a repo, so the guards accept it.\n     *\n     * Empty (the default) renders the bare commands, for callers with no root to name.\n     */\n    constructor(private readonly treeRoot: string = '') {}\n\n    /** The kind of tree rooted at `root`, for callers that have a workspace root and no other info. */\n    kindOf(root: string): TreeKind {\n        return this.worktrees.isLinkedWorktree(root) ? 'worktree' : 'branch';\n    }\n\n    // Render one command in the form that survives a tool call: `cd <root> && <command>`.\n    private at(command: string): string {\n        return this.treeRoot === '' ? command : `cd ${this.treeRoot} && ${command}`;\n    }\n\n    /**\n     * Start fresh off current main. Both forms base explicitly on `origin/main` — the only base that\n     * works from ANY tree (branch-creation-guard allows it unconditionally for that reason).\n     */\n    freshStartSteps(kind: TreeKind, newBranchName: string = '<new-feature-branch>'): string[] {\n        // The worktree DIRECTORY cannot carry the branch's slashes. When the branch name is itself a\n        // placeholder the AI must fill in, keep the directory a readable placeholder too — sanitizing\n        // `<new-feature-branch>` produced `../-new-feature-branch-`, which reads like a real path and\n        // is exactly the kind of thing an agent pastes verbatim.\n        const dir = newBranchName.includes('<')\n            ? '<feature-dir>'\n            : newBranchName.replace(/\\//g, '-');\n        const branchForm = [\n            `  ${this.at('git fetch origin main')}`,\n            `  ${this.at(`git checkout -b ${newBranchName} origin/main`)}`,\n        ];\n        const worktreeForm = [\n            `  ${this.at('git fetch origin main')}`,\n            `  ${this.at(`git worktree add ../${dir} -b ${newBranchName} origin/main`)}`,\n        ];\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree (`git checkout main` fatals here — main is checked out in',\n                'the primary clone). Start the new work in its own worktree:',\n                ...worktreeForm,\n            ];\n        }\n        // The primary clone. NO \"never `git checkout main`\" here: that is a WORKTREE-only truth, and\n        // printing it in the primary clone forbids the shortest exit off a merged branch\n        // (`git checkout main && git pull origin main && pnpm wp-cleanup` — the exact command a human\n        // had to hand an agent that had wedged itself following this very message). Branching off\n        // origin/main is still what we RECOMMEND, because it works from any tree; it is no longer\n        // dressed up as the only legal move.\n        if (kind === 'branch') {\n            return ['Start fresh — branch off origin/main (works from here and from any worktree):', ...branchForm];\n        }\n        return [\n            'Start fresh off origin/main. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            ...branchForm.map((line: string): string => `  ${line}`),\n            '  - in a linked worktree (`git checkout main` fatals there):',\n            ...worktreeForm.map((line: string): string => `  ${line}`),\n        ];\n    }\n\n    /**\n     * Reap the tree you just finished with. The worktree order is load-bearing: prune clears\n     * worktrees whose directory is already gone (`git worktree remove` FAILS on those), and the\n     * branch delete must come LAST because git refuses to delete a branch a worktree still holds.\n     *\n     * The BRANCH form ends in `pnpm wp-cleanup`, not `git branch -d <branch>`. An agent reads a bare\n     * `-d`/`-D` as destructive and stops to ask permission, so the branch survives the turn and local\n     * branches pile up — the exact failure this whole cleanup path exists to prevent. wp-cleanup is\n     * one named command that deletes only provably-dead branches (and reaps every OTHER dead one at\n     * the same time), so it is safe to allowlist and never needs a judgement call.\n     *\n     * The WORKTREE form still spells out git commands: wp-cleanup deliberately reaps parked branches\n     * only — a worktree-held branch is spared — so it cannot do this job, and the prune → remove →\n     * delete ordering is the part that has to be exactly right.\n     */\n    cleanupSteps(kind: TreeKind, branch: string, worktreePath: string = '<worktree-dir>'): string[] {\n        const branchForm = `  ${this.at('git checkout main && git pull origin main && pnpm wp-cleanup')}`;\n        const worktreeForm =\n            `  git worktree prune && git worktree remove ${worktreePath} && git branch -D ${branch}`;\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree — remove the worktree first, then the branch (git refuses',\n                'to delete a branch a worktree still holds). Run this from the PRIMARY clone:',\n                worktreeForm,\n            ];\n        }\n        if (kind === 'branch') {\n            return ['Clean up the merged branch:', branchForm];\n        }\n        return [\n            'Clean up. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            `  ${branchForm}`,\n            '  - for a linked worktree (run from the primary clone; `git branch -d` alone fails while',\n            '    a worktree still holds the branch):',\n            `  ${worktreeForm}`,\n        ];\n    }\n\n    /**\n     * Bring main up to date. In a linked worktree there is nothing to check out — `main` lives in\n     * the primary clone — so the update is a plain fetch of the remote-tracking ref, which is all\n     * you need to then branch off `origin/main`.\n     */\n    updateMainSteps(kind: TreeKind): string[] {\n        const branchForm = `  ${this.at('git checkout main && git pull origin main')}`;\n        const worktreeForm = `  ${this.at('git fetch origin main')}        (then work off origin/main)`;\n\n        if (kind === 'worktree') {\n            return [\n                'You are in a linked worktree — `git checkout main` fatals here (main is checked out in',\n                'the primary clone). Update the remote-tracking ref instead:',\n                worktreeForm,\n            ];\n        }\n        if (kind === 'branch') {\n            return ['Update main:', branchForm];\n        }\n        return [\n            'Update main. Pick the form for the tree you are in:',\n            '  - in the primary clone:',\n            `  ${branchForm}`,\n            '  - in a linked worktree (`git checkout main` fatals there):',\n            `  ${worktreeForm}`,\n        ];\n    }\n}\n"]}

package/src/core/runner.js

@@ -9,16 +9,16 @@ exports.runRead = runRead;
 exports.runRuleCheck = runRuleCheck;
 const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("path"));
-const child_process_1 = require("child_process");
 const rules_config_1 = require("@webpieces/rules-config");
 const build_context_1 = require("./build-context");
-const command_scan_1 = require("./command-scan");
+const effective_tree_1 = require("./effective-tree");
 const load_rules_1 = require("./load-rules");
 const match_rule_1 = require("./rules/match-rule");
 const main_sync_refresh_1 = require("./main-sync-refresh");
 const decision_log_1 = require("./decision-log");
 const to_error_1 = require("./to-error");
 const report_1 = require("./report");
+const read_only_inspection_1 = require("./read-only-inspection");
 const shim_1 = require("../bin/shim");
 const types_1 = require("./types");
 // Restrict loaded rules to the category this hook invocation runs. The two split hooks each pass a
@@ -42,46 +42,12 @@ function filterByExcludedPaths(rules, relativePath, ex) {
         return !patterns.some((p) => (0, load_rules_1.globMatches)(p, relativePath));
     });
 }
-// The git repo root of `cwd`, or null if cwd is not in a git repo / git is unavailable. This is the
-// repo-boundary signal: the guards only govern commands whose repo IS the one this webpieces.config
-// governs; a command run inside a nested clone (different git root) is out of scope.
-function gitToplevel(cwd) {
-    const r = (0, child_process_1.spawnSync)('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
-    return r.status === 0 ? (r.stdout ?? '').trim() : null;
-}
-// True when `cwd` sits inside a git repo OTHER than the one `workspaceRoot` governs (a nested clone).
-// Not in a git repo / git unavailable (null) is NOT foreign — it falls through to the normal guards.
-// webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
-function isForeignGitRepo(cwd, workspaceRoot) {
-    const gitRoot = gitToplevel(cwd);
-    return gitRoot !== null && path.resolve(gitRoot) !== path.resolve(workspaceRoot);
-}
-// The cwd a command actually runs from, resolving a LEADING run of `cd`/`pushd` in the command itself.
-// PreToolUse fires BEFORE the command runs, so the shell's `cwd` is the pre-`cd` directory; a command
-// like `cd repositories/clone && git push` really executes in `repositories/clone`. Every git-boundary
-// and excludePaths decision must key off THIS directory, not the pre-`cd` one, or a nested clone is
-// judged against the outer repo.
-//
-// ONLY a leading run of cd/pushd counts. Once a non-cd command appears it has ALREADY run in the
-// current dir, so a later cd must not retroactively pull it out of scope — otherwise a trailing
-// `... && cd <exempt-tree>` would exempt the WHOLE line, smuggling a root-level `git push` past the
-// guards. `cd a && cd b && git …` (leading run) resolves left to right, matching the shell.
-//
-// Reuses CommandScanner so quoting is handled exactly as the guards handle it: `echo "cd sub && git
-// push"` is ONE opaque segment whose first word is `echo`, so the quoted `cd` is never picked up —
-// the prose/quoted `cd` cannot be weaponised into a scope escape.
+// The cwd a command actually runs from, after its own leading `cd`/`pushd` run. Thin delegate kept
+// for the callers (and specs) that only need the directory; the full tree classification — primary
+// clone vs linked worktree vs nested clone vs outside any repo — is EffectiveTreeResolver.resolve().
 // webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
 function effectiveBashCwd(command, cwd) {
-    const scanner = new command_scan_1.CommandScanner();
-    let effective = cwd;
-    for (const segment of scanner.commandSegments(command)) {
-        const words = scanner.words(segment);
-        if (words[0] !== 'cd' && words[0] !== 'pushd')
-            break;
-        if (words[1] !== undefined)
-            effective = path.resolve(effective, words[1]);
-    }
-    return effective;
+    return new effective_tree_1.EffectiveTreeResolver().effectiveCwd(command, cwd);
 }
 // A git or gh invocation anywhere in the command (start, or after a ;/&&/|| separator or pipe).
 const GIT_OR_GH_RE = /(?:^|[;&|]\s*)(?:git|gh)\b/;
@@ -168,9 +134,9 @@ function runRead(filePath, cwd, mode = 'all') {
     if (loaded.configPath === null)
         return null;
     const workspaceRoot = path.dirname(loaded.configPath);
-    // Same git-repo-boundary governance as bash: a read inside a different clone is out of scope.
-    const gitRoot = gitToplevel(cwd);
-    if (gitRoot !== null && path.resolve(gitRoot) !== path.resolve(workspaceRoot))
+    // Same git-repo-boundary governance as bash, through the SAME resolver: a read inside a different
+    // clone is out of scope. (No command to parse here, so the shell cwd IS the effective cwd.)
+    if (new effective_tree_1.EffectiveTreeResolver().resolve('', cwd, workspaceRoot).kind === 'foreign')
         return null;
     const relativePath = path.relative(workspaceRoot, filePath);
     const all = (0, load_rules_1.loadRules)(loaded.rulesConfig, workspaceRoot);
@@ -188,52 +154,99 @@ function runRead(filePath, cwd, mode = 'all') {
 // binary doesn't know yet) makes loadAndValidate() throw and would deny `pnpm install` — the very
 // command that updates the validator (deadlock). Mirrors the fail-closed shim's INSTALLER_ALLOW_ERE
 // (missing-bin case); INSTALLER_ALLOW_JS is its locked JS twin. Match is tight (`pnpm install` /
-// `npm i` + `--flags` only, no chaining) so `pnpm install && rm -rf /` still falls to the guards.
+// `npm i` + `--flags`, plus an optional LEADING `cd <path> &&` so the cure is typable from a
+// worktree) so `pnpm install && rm -rf /` still falls to the guards.
 function isInstallerCommand(command) {
     return shim_1.INSTALLER_ALLOW_JS.test(command.trim());
 }
-// Force-to-root: git/gh commands must run from the repo root, where the guards can reason about git
-// state coherently. Fires ONLY when the shell is STUCK in a governed subdir — the shell persists in a
-// subdir (raw `cwd`) AND the command does not `cd` back to the root (`effectiveCwd`). A command that
-// explicitly cd's to the root runs at the root, so it is judged by the normal guards, never here:
-// without the effectiveCwd condition, `cd <root> && git push` from a nested clone was force-to-root
-// blocked while advising the very `cd <root>` it just ran (the self-contradicting dead-end this fixes).
-// Returns null when there is nothing to block.
+// Force-to-root: git/gh commands must run from the repo root of the tree they act on, where the guards
+// can reason about git state coherently. Fires ONLY when the shell is STUCK in a governed subdir — the
+// shell persists in a subdir AND the command does not `cd` to a tree root (`tree.root`, which is the
+// linked worktree's root when the command cd's into one). A command that explicitly cd's to a root is
+// judged by the normal guards, never here.
+//
+// The remedy is emitted as ONE runnable line, `cd <root> && <the original command>`, because `cd` does
+// not persist between tool calls: telling the agent to "cd first, then re-run" costs a turn and the
+// next call starts back in the old directory anyway. The bare-`cd` advice is what made this guard
+// print the very command it had just rejected.
 // webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
-function gitFromSubdirBlock(command, cwd, effectiveCwd, workspaceRoot) {
-    const atRoot = path.resolve(cwd) === path.resolve(workspaceRoot);
-    const cdsToRoot = path.resolve(effectiveCwd) === path.resolve(workspaceRoot);
-    if (!isGitOrGhCommand(command) || atRoot || cdsToRoot)
+function gitFromSubdirBlock(command, tree) {
+    const shellAtRoot = path.resolve(tree.shellCwd) === path.resolve(tree.root);
+    const cdsToRoot = path.resolve(tree.effectiveCwd) === path.resolve(tree.root);
+    if (!isGitOrGhCommand(command) || shellAtRoot || cdsToRoot)
         return null;
     const report = `❌ Run git/gh commands from the repo root, not a subdirectory.\n` +
-        `   You are in: ${cwd}\n` +
-        `   cd to the repo root first:  cd ${workspaceRoot}\n` +
-        `   Then re-run your command. (The webpieces guards evaluate the repo's git state at its root.)`;
-    (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision('force-to-root', 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'BLOCK', 'git/gh from subdir'));
+        `   You are in: ${tree.shellCwd}\n` +
+        `   Judged against: ${tree.root}\n` +
+        `   Run EXACTLY this instead (one line — \`cd\` does NOT persist between tool calls):\n` +
+        `     ${(0, effective_tree_1.atRoot)(tree.root, command)}\n` +
+        `   A leading \`cd <path> &&\` is ACCEPTED by the guards — it cannot change what the command\n` +
+        `   does to the repo. (The webpieces guards evaluate the repo's git state at its root.)`;
+    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('force-to-root', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'git/gh from subdir'));
     return new types_1.BlockedResult(report);
 }
+// The installer bypass's audit line. Anchored at the repo root that owns `.webpieces` — RepoRootFinder
+// (config-walk-up first, then git toplevel) is the authority for that, and it is correct in a linked
+// worktree because each worktree checks out its own webpieces.config.json. This runs BEFORE
+// loadAndValidate, which is why it resolves the root itself rather than using workspaceRoot.
+// webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
+function logInstallerBypass(command, cwd) {
+    const root = new rules_config_1.RepoRootFinder().resolveRepoRoot(cwd);
+    (0, decision_log_1.logGuardDecision)(root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(root), 'ALLOW', 'installer bypass (always allowed)'));
+}
+/**
+ * Load the config for the bash path — but do NOT let an unloadable config trap the tools needed to
+ * repair it.
+ *
+ * loadAndValidate throws an InformAiError when webpieces.config.json is unparseable (a real syntax
+ * error, or leftover `<<<<<<< HEAD` markers mid-merge) or fails validation. That throw propagates to
+ * the hook adapter, which fails CLOSED and denies the command — correct for work, since a config that
+ * did not load means no guards ran. But it denied `cat`/`grep`/`sed -n` on webpieces.config.json too,
+ * i.e. it blocked the only way to see the problem it was reporting. Observed live, twice.
+ *
+ * So: on a load failure, a provably-inert INSPECTION command is allowed through (returns null, "no
+ * block"), matching the escape hatch every other layer already grants this file. Everything else —
+ * every write, every git/gh command, every build — still hits the same hard failure as before. The
+ * bypass cannot be widened by accident; see ReadOnlyInspectionScan for how narrow "inert" is.
+ *
+ * Returns the loaded config, or null meaning "allow this command without guards".
+ */
+// webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
+function loadConfigOrAllowInspection(command, cwd) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrown unchanged unless the command is provably inert
+    try {
+        return (0, rules_config_1.loadAndValidate)(cwd);
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        if (error instanceof types_1.InformAiError && new read_only_inspection_1.ReadOnlyInspectionScan().isReadOnlyInspection(command)) {
+            return null;
+        }
+        throw error;
+    }
+}
 function runBashInternal(command, cwd, mode) {
     if (isInstallerCommand(command)) {
-        // Anchor the audit-log write at the repo root that owns `.webpieces` (config-walk-up first,
-        // then git toplevel) so a bypass logged from a subdir/nested clone never scatters a stray
-        // `.webpieces` tree. This runs before loadAndValidate, so resolveRepoRoot (not workspaceRoot).
-        const root = new rules_config_1.RepoRootFinder().resolveRepoRoot(cwd);
-        (0, decision_log_1.logGuardDecision)(root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(root), 'ALLOW', 'installer bypass (always allowed)'));
+        logInstallerBypass(command, cwd);
         return null;
     }
-    const loaded = (0, rules_config_1.loadAndValidate)(cwd);
+    const loaded = loadConfigOrAllowInspection(command, cwd);
+    // null = the config would not load AND this command only inspects → allow, see the helper.
+    if (loaded === null)
+        return null;
     if (loaded.configPath === null)
         return new types_1.BlockedResult(CONFIG_MISSING_REPORT);
     const workspaceRoot = path.dirname(loaded.configPath);
-    // The directory the command actually runs from (after any in-command `cd`), not the pre-`cd`
-    // shell cwd. Both the git-boundary check and the excludePaths filter below key off this, so a
-    // self-contained `cd <nested clone> && …` is judged against the clone, not the outer repo.
-    const effectiveCwd = effectiveBashCwd(command, cwd);
+    // WHICH TREE does this command act on? Not necessarily the shell's cwd — an agent working in a
+    // linked worktree writes `cd <worktree> && …` because `cd` does not persist between tool calls.
+    // ONE resolver answers this for the guards AND for force-to-root below, so the two can never
+    // disagree about which tree you are in.
+    const tree = new effective_tree_1.EffectiveTreeResolver().resolve(command, cwd, workspaceRoot);
     // Git-repo-boundary governance: the command runs inside a DIFFERENT git repo than this
     // webpieces.config governs (e.g. a clone under repositories/). Out of scope → allow, hands-off.
-    // Intentional, not a silent hole. (The hook always runs via $CLAUDE_PROJECT_DIR, so this is where
-    // out-of-scope work is let through deliberately instead of the old accidental 127.)
-    if (isForeignGitRepo(effectiveCwd, workspaceRoot)) {
+    // Intentional, not a silent hole. A LINKED WORKTREE of this repo is deliberately NOT foreign — it
+    // is the same project, so the guards run against THAT tree's branch and cache.
+    if (tree.kind === 'foreign') {
         (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'ALLOW', 'foreign git repo (out of scope)'));
         return null;
     }
@@ -241,21 +254,22 @@ function runBashInternal(command, cwd, mode) {
     // cwd sits under an excluded tree (e.g. repositories/**) drops the whole guard set — matching how
     // runInternal/runRead treat file paths. The relative path is '' when there is no `cd` (root), which
     // matches no exclusion glob, so a plain command at the repo root is unaffected.
-    const rules = filterByExcludedPaths(filterByMode((0, load_rules_1.loadRules)(loaded.rulesConfig, workspaceRoot), mode), path.relative(workspaceRoot, effectiveCwd), loaded.excludePaths);
+    const rules = filterByExcludedPaths(filterByMode((0, load_rules_1.loadRules)(loaded.rulesConfig, workspaceRoot), mode), path.relative(workspaceRoot, tree.effectiveCwd), loaded.excludePaths);
     if (rules.length === 0)
         return null;
     const outOfSync = checkConfigSync(rules, loaded.rulesConfig);
     if (outOfSync)
         return outOfSync;
-    const subdirBlock = gitFromSubdirBlock(command, cwd, effectiveCwd, workspaceRoot);
+    const subdirBlock = gitFromSubdirBlock(command, tree);
     if (subdirBlock)
         return subdirBlock;
     // Keep the feature-branch-guard cache warm on EVERY command (not just Write/Edit): the AI runs
     // far more bash than edits, so refreshing here means the guard's next file-edit check reads a
     // fresh status. Detached + fire-and-forget — never blocks the command. Only when the guard is
     // loaded (guards/all mode) and enabled, so a project that opted out never triggers git fetches.
-    maybeRefreshMainSync(rules, workspaceRoot);
-    const ctx = (0, build_context_1.buildBashContext)(command, workspaceRoot);
+    // Keyed on the JUDGED tree, so a worktree's cache is refreshed rather than the primary clone's.
+    maybeRefreshMainSync(rules, tree.root);
+    const ctx = (0, build_context_1.buildBashContext)(command, tree);
     const groups = runBashRules(rules, ctx);
     if (groups.length === 0) {
         // Record the ALLOW only for git/gh commands — the operations the bash guards actually reason
@@ -263,12 +277,12 @@ function runBashInternal(command, cwd, mode) {
         // focused (the whole point of the log is "why did/didn't a guard fire?"). Blocks are always
         // logged below.
         if (/\b(?:git|gh)\b/.test(command)) {
-            (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'ALLOW', 'no bash-guard block'));
+            (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'ALLOW', 'no bash-guard block'));
         }
         return null;
     }
     const ruleNames = groups.map((g) => g.ruleName).join(',');
-    (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision(ruleNames, 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'BLOCK', 'bash-guard block'));
+    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision(ruleNames, 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'bash-guard block'));
     const report = (0, report_1.formatReport)(commandLabel(command), groups, report_1.BASH_SUBJECT) + exemptTreesHint(groups, loaded.excludePaths.guards);
     return new types_1.BlockedResult(report);
 }