peaks-loop 4.0.37 → 4.0.39

package/dist/services/skills/hooks-settings-service.js

@@ -4,7 +4,7 @@ import { join, resolve } from 'node:path';
 import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
 import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
 import { getAdapter } from '../ide/ide-registry.js';
-import { resolveHookSpec, resolveHookEntries, resolveLegacySentinels, SUPERPOWERS_DENIED_SKILLS, formatSuperpowersDenyEntry, SUPERPOWERS_DENY_SENTINELS } from './hooks-codegate-superpowers.js';
+import { resolveHookSpec, resolveHookEntries, resolveLegacySentinels, SUPERPOWERS_DENIED_SKILLS, formatSuperpowersDenyEntry, SUPERPOWERS_DENY_SENTINELS, hasExternalGateExemptions, withExternalGateExemptions, withoutExternalGateExemptions } from './hooks-codegate-superpowers.js';
 export { HOOK_ENFORCE_SENTINEL, HOOK_CODE_GATE_SENTINEL, HOOK_CODE_GATE_MATCHER, HOOK_CODE_GATE_EVENT, HOOK_CODE_GATE_COMMAND, SUPERPOWERS_DENIED_SKILLS } from './hooks-codegate-superpowers.js';
 // --- Module-level defaults (claude-code) -----------------------------------
 // These exports remain for backward compat — tests and downstream callers
@@ -67,16 +67,30 @@ function resolveLocalSettingsPath(scope, ide, projectRoot) {
 function resolveHookTargets(scope, ide, projectRoot) {
     const sharedPath = resolveSettingsPath(scope, ide, projectRoot);
     const localPath = resolveLocalSettingsPath(scope, ide, projectRoot);
-    const shared = { settingsPath: sharedPath, entries: [] };
+    const wantsEnvExemptions = ide === 'claude-code';
     if (localPath === undefined || localPath === sharedPath) {
-        return [{ settingsPath: sharedPath, entries: [...resolveHookEntries(ide)] }];
+        // Global scope lands here: the user-level file is already machine-local,
+        // so it is the safe target (there is no sibling to prefer).
+        return [{ settingsPath: sharedPath, entries: [...resolveHookEntries(ide)], envExemptions: wantsEnvExemptions }];
     }
-    const local = { settingsPath: localPath, entries: [] };
+    const shared = { settingsPath: sharedPath, entries: [] };
+    const local = { settingsPath: localPath, entries: [], envExemptions: wantsEnvExemptions };
     for (const entry of resolveHookEntries(ide)) {
         (entry.machineLocal === true ? local : shared).entries.push(entry);
     }
     return [shared, local];
 }
+/** True when `target` already holds everything the install would write to it. */
+function targetIsSatisfied(target, allSentinels) {
+    const settings = readSettingsFile(target.settingsPath);
+    if (!shapeMatchesDesired(settings, target.entries, allSentinels))
+        return false;
+    return target.envExemptions !== true || hasExternalGateExemptions(settings);
+}
+/** Flatten the resolved targets into one `{ matcher, sentinel, settingsPath }` row per entry. */
+function describeEntryTargets(targets) {
+    return targets.flatMap((target) => target.entries.map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel, settingsPath: target.settingsPath })));
+}
 /** Read a settings file as an object, or `{}` when it does not exist yet. */
 function readSettingsFile(settingsPath) {
     return existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
@@ -307,11 +321,17 @@ export function planHookInstall(scope, projectRoot, options) {
         scope,
         settingsPath,
         exists,
-        alreadyInstalled: targets.every((t) => isInstalledForEntries(readSettingsFile(t.settingsPath), t.entries)),
+        // The env clause mirrors `applyHookInstall`'s: without it the dry-run would
+        // claim "nothing to do" about a file the install is going to write.
+        alreadyInstalled: targets.every((t) => {
+            const settings = readSettingsFile(t.settingsPath);
+            return isInstalledForEntries(settings, t.entries) && (t.envExemptions !== true || hasExternalGateExemptions(settings));
+        }),
         desiredCommand: spec.hookEnforceCommand,
         sentinel: spec.hookEnforceSentinel,
         matcher: spec.hookEnforceMatcher,
-        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {})
+        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {}),
+        entryTargets: describeEntryTargets(targets)
     };
 }
 /**
@@ -379,7 +399,10 @@ export function applyHookInstall(scope, projectRoot, options) {
     // as not-yet-installed, so the merge strips the stale entry on the
     // next install call. This is the only path that converges the file
     // on the new shape; pure presence-checks are insufficient.
-    const alreadyInstalled = targets.every((t) => shapeMatchesDesired(readSettingsFile(t.settingsPath), t.entries, allSentinels));
+    //
+    // The external-gate exemption is part of the desired shape too, so a project
+    // installed by a release that predates it still converges on upgrade.
+    const alreadyInstalled = targets.every((t) => targetIsSatisfied(t, allSentinels));
     const baseResult = {
         scope,
         settingsPath,
@@ -388,7 +411,8 @@ export function applyHookInstall(scope, projectRoot, options) {
         desiredCommand: spec.hookEnforceCommand,
         sentinel: spec.hookEnforceSentinel,
         matcher: spec.hookEnforceMatcher,
-        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {})
+        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {}),
+        entryTargets: describeEntryTargets(targets)
     };
     if (baseResult.alreadyInstalled) {
         return { ...baseResult, applied: false };
@@ -409,9 +433,14 @@ export function applyHookInstall(scope, projectRoot, options) {
     //
     // The `permissions.deny` block lives in the adapter's settings file
     // only (as it always has) — it is committed, so the deny list is
-    // shared; the machine-local file carries hook entries only.
+    // shared; the machine-local file carries hook entries plus, for Claude
+    // Code, the third-party gate exemptions (machine-local by the same
+    // argument as the hook `shell` pin).
     for (const target of targets) {
-        const next = withHooksInstalled(readSettingsFile(target.settingsPath), target.entries, allSentinels);
+        let next = withHooksInstalled(readSettingsFile(target.settingsPath), target.entries, allSentinels);
+        if (target.envExemptions === true) {
+            next = withExternalGateExemptions(next);
+        }
         const merged = target.settingsPath === settingsPath
             ? withTriggeredDenyList(withSuperpowersSkillDenylist(next))
             : next;
@@ -478,9 +507,13 @@ export function removeHookInstall(scope, projectRoot, options) {
         // trigger-style deny entries via withoutTriggeredDenyList. The
         // chain of helpers is order-independent (each is idempotent and
         // additive over the same set of peaks-managed entries).
-        const finalSettings = target.settingsPath === settingsPath
-            ? withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(nextSettings))
-            : nextSettings;
+        let finalSettings = nextSettings;
+        if (target.envExemptions === true) {
+            finalSettings = withoutExternalGateExemptions(finalSettings);
+        }
+        if (target.settingsPath === settingsPath) {
+            finalSettings = withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(finalSettings));
+        }
         atomicWriteJson(target.settingsPath, finalSettings);
     }
     return {

package/dist/services/web/playwright-loader.js

@@ -30,9 +30,9 @@
  */
 import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { npmExecCacheRoots } from '../../shared/npm-cache.js';
 import { isInsidePath } from '../../shared/path-utils.js';
 /**
  * Exact pin, no caret (tech-doc §3.2). AC2 is a BYTE-COUNT contract and the
@@ -88,7 +88,10 @@ export function resolvePlaywrightModule() {
  * exact pin exists to prevent.
  */
 function resolveFromNpxCache() {
-    for (const cacheRoot of npxCacheRoots()) {
+    // The roots themselves live in `shared/npm-cache.ts` — the exec cache has
+    // exactly one definition, shared with the OCR probe, so the two cannot
+    // disagree about what "already installed" means.
+    for (const cacheRoot of npmExecCacheRoots()) {
         for (const entry of safeReaddir(cacheRoot)) {
             const resolved = tryResolveFrom(join(cacheRoot, entry, 'node_modules'));
             if (resolved !== null) {
@@ -98,28 +101,6 @@ function resolveFromNpxCache() {
     }
     return null;
 }
-/**
- * `<npm cache>/_npx` candidates: the per-user defaults, and nothing else.
- *
- * `npm_config_cache` / `NPM_CONFIG_CACHE` used to be taken first "when
- * configured". They are not configuration this module may trust: under
- * `npm run`, npm exports the value a repo's own `.npmrc` chose, so a committed
- * `.npmrc` plus a committed `_npx`-shaped tree selected the package that
- * `import()` then executed (security review S2, reproduced). The default roots
- * below are where npm actually puts an `npx` cache.
- */
-function npxCacheRoots() {
-    const roots = [join(homedir(), '.npm', '_npx')];
-    if (process.platform === 'win32') {
-        for (const key of ['LOCALAPPDATA', 'APPDATA']) {
-            const base = process.env[key];
-            if (base !== undefined && base.length > 0) {
-                roots.push(join(base, 'npm-cache', '_npx'));
-            }
-        }
-    }
-    return roots;
-}
 /**
  * Resolve `playwright` as if from `moduleRoot`, and admit it only when it
  * passes `verifyPinnedPackage` against that same root. The anchor is what

package/dist/services/workflow/provision-dispatch-node.d.ts

@@ -0,0 +1,42 @@
+export interface ProvisionedDispatchNode {
+    readonly nodeId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    /** True when this call created the graph; false when it appended to one. */
+    readonly graphCreated: boolean;
+}
+/**
+ * Bind a dispatch to a graph node, creating the graph and the node when
+ * they do not exist yet.
+ *
+ * Why this exists. `--graph-node` was a `.requiredOption`, and the failure
+ * message told the caller to "Prepare a graph node via
+ * `peaks workflow node prepare` and re-run dispatch". That instruction was
+ * unwalkable:
+ *
+ *   - `workflow node prepare` never calls `writeGraph`, so the node it
+ *     reports is never persisted — it is printed into the envelope's
+ *     `graph` field (which is a single NODE, not a graph) and dropped;
+ *   - the graph that command reads must already exist, and no CLI verb
+ *     creates one.
+ *
+ * So the documented three-step ritual had no viable first step anywhere
+ * outside peaks-loop's own tree, while the flag itself guaranteed nothing:
+ * `dispatch-record-writer` treats the graph transition as best-effort and
+ * silently returns when the node is absent, and `PEAKS_GRAPH_NODE_NOT_PREPARED`
+ * is imported but never thrown on this path. A required parameter that is
+ * never validated, blocking every consumer project, is pure friction.
+ *
+ * Provisioning makes the binding cheap and real instead: the node exists
+ * from the first dispatch, so the transition in the record writer has
+ * something to find.
+ */
+export declare function provisionDispatchNode(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly role: string;
+    readonly workflowId?: string | undefined;
+    readonly graphRef?: string | undefined;
+    /** Injectable for tests; defaults to `Date.now()`. */
+    readonly now?: (() => number) | undefined;
+}): ProvisionedDispatchNode;

package/dist/services/workflow/provision-dispatch-node.js

@@ -0,0 +1,66 @@
+import { emptyGraph, readGraph, writeGraph, PEAKS_GRAPH_NOT_FOUND } from './workflow-graph-store.js';
+import { WORKFLOW_ID_REGEX } from './workflow-graph-types.js';
+/**
+ * Bind a dispatch to a graph node, creating the graph and the node when
+ * they do not exist yet.
+ *
+ * Why this exists. `--graph-node` was a `.requiredOption`, and the failure
+ * message told the caller to "Prepare a graph node via
+ * `peaks workflow node prepare` and re-run dispatch". That instruction was
+ * unwalkable:
+ *
+ *   - `workflow node prepare` never calls `writeGraph`, so the node it
+ *     reports is never persisted — it is printed into the envelope's
+ *     `graph` field (which is a single NODE, not a graph) and dropped;
+ *   - the graph that command reads must already exist, and no CLI verb
+ *     creates one.
+ *
+ * So the documented three-step ritual had no viable first step anywhere
+ * outside peaks-loop's own tree, while the flag itself guaranteed nothing:
+ * `dispatch-record-writer` treats the graph transition as best-effort and
+ * silently returns when the node is absent, and `PEAKS_GRAPH_NODE_NOT_PREPARED`
+ * is imported but never thrown on this path. A required parameter that is
+ * never validated, blocking every consumer project, is pure friction.
+ *
+ * Provisioning makes the binding cheap and real instead: the node exists
+ * from the first dispatch, so the transition in the record writer has
+ * something to find.
+ */
+export function provisionDispatchNode(input) {
+    // A caller-supplied workflowId is honoured only when it is well-formed;
+    // the option was previously ignored outright, so falling back is strictly
+    // additive, and the effective id is returned so the choice is visible.
+    const workflowId = typeof input.workflowId === 'string' && WORKFLOW_ID_REGEX.test(input.workflowId)
+        ? input.workflowId
+        : `dispatch-${input.sessionId}`;
+    const graphRef = input.graphRef ?? `graphs/${workflowId}.json`;
+    let graph;
+    let graphCreated = false;
+    try {
+        graph = readGraph({ projectRoot: input.projectRoot, sessionId: input.sessionId, graphRef, workflowId });
+    }
+    catch (err) {
+        if (err.code !== PEAKS_GRAPH_NOT_FOUND)
+            throw err;
+        // `emptyGraph` supplies the one terminal node `validateGraph` requires.
+        graph = emptyGraph({ workflowId, rootSkill: 'peaks-code' });
+        graphCreated = true;
+    }
+    const stamp = (input.now ?? Date.now)().toString(36);
+    const nodeId = `dispatch-${input.role}-${stamp}`;
+    const node = {
+        id: nodeId,
+        kind: 'dispatch',
+        label: `${input.role} dispatch`,
+        status: 'prepared',
+        dependsOn: [],
+    };
+    writeGraph({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        graphRef,
+        workflowId,
+        graph: { ...graph, nodes: [...graph.nodes, node] },
+    });
+    return { nodeId, workflowId, graphRef, graphCreated };
+}

package/dist/services/workspace/claude-settings-template.d.ts

@@ -75,14 +75,23 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *           string carries no shell-escaped payload at all and the handler
  *           can take the same platform `shell` pin as its siblings. The
  *           decision itself is a verbatim relocation — see that file.
+ *   1.7.0 — added the `env` block declaring Peaks' workspace tree exempt
+ *           from a THIRD-PARTY PreToolUse fact-forcing gate
+ *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
+ *           on-disk file to declare those exemptions too, so a project
+ *           installed by an earlier release refreshes once and converges.
  */
-export declare const TEMPLATE_VERSION = "1.6.0";
+export declare const TEMPLATE_VERSION = "1.7.0";
 /**
- * Compare two serialized template strings for semantic equivalence.
+ * Compare two serialized template strings for semantic equivalence: does the
+ * on-disk file already declare everything the generated template declares?
  *
  * Returns `true` iff both strings parse to objects whose
  * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) AND the
+ * on-disk `env` already carries every exemption the template declares (extra
+ * on-disk keys and extra globs are allowed — a user may exempt other trees,
+ * and a requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -120,6 +129,13 @@ type ClaudeSettingsLocal = {
     hooks: {
         PreToolUse: ClaudePreToolUseEntry[];
     };
+    /**
+     * Exemptions declared to the third-party PreToolUse gate peaks does not own
+     * (`EXTERNAL_GATE_EXEMPT_ENV`). They belong in THIS file because it is
+     * machine-local and gitignored: a third-party variable name in the committed
+     * shared `settings.json` would be pushed to every consumer of the project.
+     */
+    env: Record<string, string>;
 };
 /**
  * Build the full template object. The shape is the subset of Claude

package/dist/services/workspace/claude-settings-template.js

@@ -35,7 +35,7 @@
  */
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
+import { EXTERNAL_GATE_EXEMPT_ENV, hasExternalGateExemptions, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
  * Informational version of the offline template shape. Bumped when the
@@ -78,14 +78,23 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           string carries no shell-escaped payload at all and the handler
  *           can take the same platform `shell` pin as its siblings. The
  *           decision itself is a verbatim relocation — see that file.
+ *   1.7.0 — added the `env` block declaring Peaks' workspace tree exempt
+ *           from a THIRD-PARTY PreToolUse fact-forcing gate
+ *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
+ *           on-disk file to declare those exemptions too, so a project
+ *           installed by an earlier release refreshes once and converges.
  */
-export const TEMPLATE_VERSION = '1.6.0';
+export const TEMPLATE_VERSION = '1.7.0';
 /**
- * Compare two serialized template strings for semantic equivalence.
+ * Compare two serialized template strings for semantic equivalence: does the
+ * on-disk file already declare everything the generated template declares?
  *
  * Returns `true` iff both strings parse to objects whose
  * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) AND the
+ * on-disk `env` already carries every exemption the template declares (extra
+ * on-disk keys and extra globs are allowed — a user may exempt other trees,
+ * and a requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -127,7 +136,12 @@ export function templateContentMatches(generated, onDisk) {
             return false;
         }
     }
-    return true;
+    // A project installed by a release that predates a template-declared
+    // exemption still needs the refresh this comparator gates — otherwise the
+    // entry would only ever appear on a machine that re-ran `peaks hooks
+    // install`. `hasExternalGateExemptions` is the same predicate the installer
+    // uses, so the two writers cannot drift apart.
+    return hasExternalGateExemptions({ env: parsedOnDisk.env });
 }
 function isTemplateShape(value) {
     if (typeof value !== 'object' || value === null) {
@@ -234,6 +248,12 @@ export function buildClaudeSettingsLocalJson() {
     // the key entirely.
     const writeShell = resolveHookShell();
     return {
+        // Slice emit-gateguard-exemption — the third-party gate exemption. Peaks
+        // already bypasses its OWN fact-forcing gate for `.peaks/**` (the
+        // Write|Edit|MultiEdit handler below); this is the same intent declared in
+        // the currency an external PreToolUse gate reads. `peaks hooks install`
+        // merges the same row into this file, so the two writers agree.
+        env: { ...EXTERNAL_GATE_EXEMPT_ENV },
         hooks: {
             PreToolUse: [
                 {

package/dist/services/workspace/workspace-claude-settings-materializer.js

@@ -9,10 +9,37 @@
  * the parent module and calls into this sibling. Function signatures
  * and behaviour are unchanged (verbatim move).
  */
-import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { withExternalGateExemptions } from '../skills/hooks-codegate-superpowers.js';
 import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
+/** Read a file as text, or `undefined` when it cannot be read. */
+function readTextIfPresent(filePath) {
+    try {
+        return readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `env` object of a serialized settings file, or `undefined` when the file
+ * is malformed or has no `env` object. Tolerant on purpose: a bad on-disk file
+ * must not stop the materialization.
+ */
+function readEnvObject(serialized) {
+    try {
+        const parsed = JSON.parse(serialized);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const env = parsed.env;
+        return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The peaks-managed snippet appended to the consumer project's
  * `.peaks/.gitignore` so the local-only settings file never lands
@@ -32,6 +59,8 @@ const PEAKS_GITIGNORE_SNIPPET = [
     '# Gitignored so the init flow\'s drift-driven refresh does not show up as',
     '# "modified" in `git status` on every release bump. Recovery path: re-run',
     '# `peaks workspace init` to regenerate; or copy from peaks-loop source.',
+    '# Both patterns below are PROJECT-ROOT-relative, so this snippet must land',
+    '# in the root .gitignore — see `upsertPeaksGitignoreSnippet`.',
     '.peaks/.claude-settings-template.json',
     PEAKS_GITIGNORE_FOOTER,
     ''
@@ -66,7 +95,15 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
     const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
     const settingsPath = join(projectRoot, settingsRel);
     const template = buildClaudeSettingsLocalJson();
-    const serialized = JSON.stringify(template, null, 2) + '\n';
+    const fileExists = existsSync(settingsPath);
+    const existing = fileExists ? readTextIfPresent(settingsPath) : undefined;
+    // `.claude/settings.local.json` has a second writer: `peaks hooks install`
+    // unions the user's own exemption globs into `env`. Carry that value across
+    // the rewrite this function is about to do, or a refresh would silently
+    // drop someone else's exemptions. The template's own row is added on top, so
+    // the result is a union either way.
+    const onDiskEnv = existing === undefined ? undefined : readEnvObject(existing);
+    const serialized = JSON.stringify(withExternalGateExemptions(onDiskEnv === undefined ? template : { ...template, env: onDiskEnv }), null, 2) + '\n';
     // Always drop (or self-heal) a copy of the template under .peaks/
     // so the --no-claude-hooks recovery flow has a known source-of-truth
     // on disk. The file is gitignored by the snippet below.
@@ -84,27 +121,15 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
     // hooks-settings-service applies the safety check for the Bash
     // gate-enforce path).
     await mkdir(join(projectRoot, '.claude'), { recursive: true });
-    let action = 'written';
-    if (existsSync(settingsPath)) {
-        try {
-            const { readFile } = await import('node:fs/promises');
-            const existing = await readFile(settingsPath, 'utf8');
-            // Structural comparison (not a byte comparison): `peaks hooks
-            // install` also writes this file, through a different serializer, so
-            // an equal hooks tree must be recognized as current or every init
-            // would rewrite the file and drop the installer's entries.
-            if (templateContentMatches(serialized, existing)) {
-                action = 'already-current';
-            }
-            else {
-                action = 'refreshed';
-            }
-        }
-        catch {
-            // Treat any read failure as "needs refresh" so the consumer
-            // always ends up with a valid template on disk.
-            action = 'refreshed';
-        }
+    // An existing-but-unreadable file is treated as drifted, so the consumer
+    // always ends up with a valid template on disk.
+    let action = fileExists ? 'refreshed' : 'written';
+    // Structural comparison (not a byte comparison): `peaks hooks install` also
+    // writes this file, through a different serializer, so an equal hooks tree
+    // must be recognized as current or every init would rewrite the file and
+    // drop the installer's entries.
+    if (existing !== undefined && templateContentMatches(serialized, existing)) {
+        action = 'already-current';
     }
     if (action !== 'already-current') {
         await writeFile(settingsPath, serialized, 'utf8');
@@ -171,13 +196,70 @@ async function writeOfflineTemplateCopy(projectRoot, serialized) {
     return action;
 }
 /**
- * Append the peaks-managed `.claude/settings.local.json` snippet to
- * the consumer project's `.peaks/.gitignore`. Preserves any user-
- * managed entries above the snippet. Idempotent: re-running on a
- * project that already has the snippet is a no-op.
+ * Append the peaks-managed snippet to the consumer project's ROOT
+ * `.gitignore`. Preserves any user-managed entries above the snippet.
+ * Idempotent: re-running on a project that already has the snippet is a
+ * no-op.
+ *
+ * Root, not `.peaks/.gitignore`. A gitignore pattern containing a slash is
+ * anchored to the directory of the .gitignore that holds it, and both
+ * patterns here are project-root-relative. Written into `.peaks/.gitignore`
+ * they resolved to `.peaks/.claude/settings.local.json` and
+ * `.peaks/.peaks/.claude-settings-template.json` — matching nothing, in
+ * every project. The root-level `settings.local.json` entry could not be
+ * expressed from inside `.peaks/` at all, since gitignore has no `..`.
+ */
+/**
+ * The snippet's former home. Projects initialized before the move carry a
+ * managed block there that now matches nothing and is maintained by nobody —
+ * yet still announces itself as "do not edit by hand", which is worse than
+ * absent: a reader takes it for live configuration.
+ */
+const LEGACY_PEAKS_GITIGNORE_PATH = ['.peaks', '.gitignore'];
+/**
+ * Strip the managed block from its legacy home, preserving every line the
+ * user wrote. Idempotent; a no-op on projects that never had one.
+ *
+ * The file is deleted only when nothing remains. An empty `.peaks/.gitignore`
+ * left behind reads as "peaks put something here and stopped", which invites
+ * the next reader to guess.
+ *
+ * A malformed block (header without footer) is left untouched rather than
+ * guessed at — deleting a user's file to tidy our own mess is not a trade
+ * worth making.
  */
+async function stripLegacyPeaksGitignoreSnippet(projectRoot) {
+    const legacyPath = join(projectRoot, ...LEGACY_PEAKS_GITIGNORE_PATH);
+    if (!existsSync(legacyPath))
+        return;
+    let existing;
+    try {
+        existing = await readFile(legacyPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const start = existing.indexOf(PEAKS_GITIGNORE_HEADER);
+    if (start === -1)
+        return;
+    const footerAt = existing.indexOf(PEAKS_GITIGNORE_FOOTER, start);
+    if (footerAt === -1)
+        return;
+    const remainder = (existing.slice(0, start) + existing.slice(footerAt + PEAKS_GITIGNORE_FOOTER.length))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    if (remainder.length === 0) {
+        await rm(legacyPath, { force: true });
+        return;
+    }
+    await writeFile(legacyPath, `${remainder}\n`, 'utf8');
+}
 async function upsertPeaksGitignoreSnippet(projectRoot) {
-    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
+    // Migration first: the snippet used to live in `.peaks/.gitignore`, where
+    // its patterns silently matched nothing. Strip that copy before writing the
+    // one that works.
+    await stripLegacyPeaksGitignoreSnippet(projectRoot);
+    const gitignorePath = join(projectRoot, '.gitignore');
     await mkdir(join(projectRoot, '.peaks'), { recursive: true });
     let existing = '';
     if (existsSync(gitignorePath)) {

package/dist/shared/npm-cache.d.ts

@@ -0,0 +1,2 @@
+/** `<npm cache>/_npx` candidates: the per-user defaults, and nothing else. */
+export declare function npmExecCacheRoots(): string[];

package/dist/shared/npm-cache.js

@@ -0,0 +1,31 @@
+/**
+ * Where npm puts its per-user exec (`npx`) cache.
+ *
+ * This list lives in exactly ONE place on purpose: whoever resolves a package
+ * out of that cache (the Playwright loader `import()`s what it finds, the OCR
+ * probe reports it as installed) is answering the same question — "is this
+ * package already here?" — and a second copy of the roots is a second answer
+ * that would drift from this one.
+ *
+ * `npm_config_cache` / `NPM_CONFIG_CACHE` are deliberately NOT honoured: under
+ * `npm run`, npm exports the value a repo's own `.npmrc` chose, so trusting
+ * them lets a committed `.npmrc` select the tree that gets executed. The
+ * default roots below are where npm actually puts an `npx` cache.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** `<npm cache>/_npx` candidates: the per-user defaults, and nothing else. */
+export function npmExecCacheRoots() {
+    // Resolved per call, never at module load: callers that relocate the home
+    // (tests, and any future sandboxed run) must see the relocation.
+    const roots = [join(homedir(), '.npm', '_npx')];
+    if (process.platform === 'win32') {
+        for (const key of ['LOCALAPPDATA', 'APPDATA']) {
+            const base = process.env[key];
+            if (base !== undefined && base.length > 0) {
+                roots.push(join(base, 'npm-cache', '_npx'));
+            }
+        }
+    }
+    return roots;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.37",
+  "version": "4.0.39",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-mut": "0.1.35",
-    "peaks-loop-internal-runtime": "0.0.22",
-    "peaks-loop-shared-channel": "0.0.39",
-    "peaks-loop-shared": "0.0.71"
+    "peaks-loop-internal-runtime": "0.0.24",
+    "peaks-loop-shared-channel": "0.0.41",
+    "peaks-loop-shared": "0.0.73",
+    "peaks-loop-mut": "0.1.37"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-perf-audit/SKILL.md

@@ -12,6 +12,30 @@ metadata:
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
+it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
+are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
+which denies the edit. **A denial is not a failure and the tool is not broken — your edit
+was not applied.** Read the file, state the facts the gate asks for (importers, affected
+API, data schemas if any, the user's verbatim instruction), then retry the same operation.
+Do not switch tools, do not give up, do not retry blindly.
+<!-- /peaks:loop-hygiene -->
+
 # peaks-perf-audit
 
 > **Independent performance audit skill** — separate from `peaks-rd`'s