peaks-loop 4.0.37 → 4.0.39

package/dist/services/lint/ocr-18-acquire.js

@@ -0,0 +1,350 @@
+/**
+ * OCR 1.8.x acquisition — the ONE step that is allowed to install the reviewer.
+ *
+ * ## Why this exists as its own module
+ *
+ * `detect-ocr-18` is a *read-only probe*, but it used to produce its answer by
+ * running `npx --package <pin> -- ocr version`, which INSTALLS the package when
+ * it is not already cached. Dogfooding 4.0.38: a window titled `npm i @…`
+ * appeared on the user's desktop, opened by a command whose own help text says
+ * "Read-only probe". The probe no longer spawns at all (see
+ * `detect-ocr-18.ts`); the install it was performing as a side effect lives
+ * HERE, where it is explicit, named, and on the human's channel — the same
+ * split `peaks web status` (probe) / `peaks web install` (acquire) already
+ * uses, and whose discipline this module mirrors rather than reinvents.
+ *
+ * ## Visibility is the requirement, not a nicety
+ *
+ * The user's words: *"最起码可以看到进度"* — at minimum the progress must be
+ * visible. So the installer's stdio is INHERITED, never piped-and-dropped and
+ * never detached: npm's own progress lands on the terminal the caller is
+ * already watching. Two consequences, both deliberate:
+ *
+ *   - **`windowsHide: true` is not the opposite of visibility.** It stops
+ *     Windows from allocating a NEW console window; inherited stdio keeps
+ *     writing to the console that already exists. The window in the bug report
+ *     was *new*; the progress is *inherited*. `detached: true` is deliberately
+ *     absent — a silent background install is exactly what was rejected.
+ *   - **In `--json` mode the child's STDOUT is dropped** (`'ignore'`) so npm's
+ *     output cannot corrupt the JSON envelope `printResult` writes to stdout,
+ *     while its STDERR stays inherited — npm puts progress and warnings there,
+ *     so the wait is still explained on screen. Human mode inherits both.
+ *
+ * ## Shell preference — and why this is NOT `resolveHookShell`
+ *
+ * Order: **Git Bash, then PowerShell, then a plain spawn with no shell.**
+ *
+ * Slice `4637baa8` pinned the *hook* shell to PowerShell on Windows, and it is
+ * still right: a hook fires on every Bash tool call, and MSYS2's bash
+ * force-allocates its own console window, so the hook must avoid bash. An
+ * ACQUISITION is the opposite case — it runs once, takes seconds, and the user
+ * wants to watch it.
+ *
+ * **The two preferences are not a contradiction waiting to be "reconciled" —
+ * they answer two different questions** ("run constantly, be invisible" vs
+ * "run once, be visible"). Changing `resolveHookShell` to this order would put
+ * a console window back on every tool call; changing this order to match the
+ * hook would take away the shell the user explicitly asked for
+ * (*"优先使用git bash没有才是powershell"*). Leave both alone.
+ *
+ * The Git Bash half is NOT re-implemented: `probeShell`
+ * (`src/services/env/shell-probe.ts`) already owns the lookup (the
+ * `PEAKS_GIT_BASH` pin, the default install paths, the `where bash` PATH
+ * sweep) and already refuses to fall back silently. This module adds the
+ * PowerShell step and keeps `probeShell`'s refusal visible: the resolution
+ * carries a `note` naming the shell that was used and, when it is not the
+ * first choice, why it is not. Silently using a different shell is how this
+ * confusion started.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { probeShell } from '../env/shell-probe.js';
+import { isProcessAlive } from '../web/daemon-registry.js';
+import { resolveNpxInvocation } from './npx-resolver.js';
+import { OCR_18_PACKAGE } from './ocr-multilang-adapter.js';
+/**
+ * The network wait, named BEFORE it starts and never skipped silently.
+ *
+ * The size is not quoted as a figure the way `INSTALL_SIZE_WARNING` quotes
+ * chromium's 704 MiB: this package's download size is not measured here, and a
+ * guessed number in a warning is worse than no number. What the user needs to
+ * know before the block is that this touches the network and is one-time.
+ */
+export const ACQUIRE_NETWORK_WARNING = `fetching ${OCR_18_PACKAGE} from the npm registry (needs network, one time)`;
+/**
+ * A held lock older than this is reclaimed even if its owner is alive.
+ * Deliberately longer than `ACQUIRE_TIMEOUT_MS`, so a timed-out install still
+ * owns its lock while it winds down.
+ */
+const ACQUIRE_LOCK_STALE_MS = 30 * 60_000;
+/**
+ * A blocking `spawnSync` needs a ceiling or "never hang" is not true. The
+ * package is far smaller than chromium, so this is the web installer's 20 min
+ * cut down; the child is killed at this point and a partial fetch is recovered
+ * by simply running the verb again (npm exec is idempotent).
+ */
+const ACQUIRE_TIMEOUT_MS = 10 * 60_000;
+/** 0600 mirrors the web install lock's reasoning: ours, and nobody else's. */
+const LOCK_FILE_MODE = 0o600;
+/**
+ * `<homedir>/.peaks/ocr/install.lock` — the OCR acquisition lock.
+ *
+ * MACHINE-GLOBAL, like the web install lock and for the same reason: what it
+ * guards is npm's per-user exec cache (`~/.npm/_npx`, `%LOCALAPPDATA%
+ * \npm-cache\_npx`), which every project and every session of this user
+ * shares. A per-project lock would serialize nothing.
+ */
+export function ocrAcquireLockPath() {
+    return join(homedir(), '.peaks', 'ocr', 'install.lock');
+}
+/**
+ * Take the OCR acquire lock (O_EXCL create), reclaiming a STALE one — dead
+ * owner, unreadable body, or older than `ACQUIRE_LOCK_STALE_MS`. `false` when
+ * another process holds a live lock.
+ *
+ * Same protocol as `web-install-service.acquireInstallLock`, deliberately
+ * including the R15 detail that **the reclaim is a rename, not an unlink**:
+ * `O_EXCL` serializes the create only if the removal before it cannot be
+ * replayed against a fresh file — `A unlink → A create → B unlink (A's FRESH
+ * lock) → B create` leaves both holders. A file can only be moved once, so
+ * exactly one reclaimer wins and the create that follows decides.
+ *
+ * The two copies are not shared because the web module's lock is bound to its
+ * own artifact root and this change does not reach into it. If a third
+ * acquirer appears, lift the pair into a shared helper with a lock-path
+ * parameter rather than writing a third copy.
+ */
+export function acquireOcrLock() {
+    const target = ocrAcquireLockPath();
+    mkdirSync(dirname(target), { recursive: true });
+    if (tryCreateLock(target)) {
+        return ownsLock(target);
+    }
+    if (isLiveLock(readLock(target))) {
+        return false;
+    }
+    const claim = `${target}.reclaim-${String(process.pid)}`;
+    try {
+        renameSync(target, claim);
+    }
+    catch {
+        // Another reclaimer moved it first (ENOENT), or it cannot be moved.
+        return false;
+    }
+    if (isLiveLock(readLock(claim))) {
+        // We moved a lock a racer had just legitimately (re)created: put it back
+        // rather than steal a lock its owner is already installing under.
+        try {
+            renameSync(claim, target);
+        }
+        catch {
+            try {
+                unlinkSync(claim);
+            }
+            catch {
+                // Nothing left to clean up.
+            }
+        }
+        return false;
+    }
+    try {
+        unlinkSync(claim);
+    }
+    catch {
+        // Already gone; the create below is the decider.
+    }
+    return tryCreateLock(target) && ownsLock(target);
+}
+/** Release the OCR acquire lock, but only when this process is its owner. */
+export function releaseOcrLock() {
+    const target = ocrAcquireLockPath();
+    const existing = readLock(target);
+    // An UNREADABLE body is not proof of ownership, so it is left alone: the
+    // worst case is one `ACQUIRE_LOCK_STALE_MS` wait, where unlinking a racer's
+    // half-written `wx` create would hand its lock to whoever asked next.
+    if (existing === null || existing.pid !== process.pid) {
+        return;
+    }
+    try {
+        unlinkSync(target);
+    }
+    catch {
+        // Already released (or never held).
+    }
+}
+function isLiveLock(body) {
+    return body !== null && isProcessAlive(body.pid) && Date.now() - Date.parse(body.startedAt) <= ACQUIRE_LOCK_STALE_MS;
+}
+function ownsLock(target) {
+    return readLock(target)?.pid === process.pid;
+}
+function tryCreateLock(target) {
+    const body = { pid: process.pid, startedAt: new Date().toISOString() };
+    try {
+        writeFileSync(target, JSON.stringify(body), { flag: 'wx', encoding: 'utf8', mode: LOCK_FILE_MODE });
+        return true;
+    }
+    catch {
+        // `EEXIST` (held) and any other write failure both mean "not acquired".
+        return false;
+    }
+}
+function readLock(target) {
+    try {
+        const parsed = JSON.parse(readFileSync(target, 'utf8'));
+        const { pid, startedAt } = parsed;
+        if (typeof pid !== 'number' || typeof startedAt !== 'string') {
+            return null;
+        }
+        return { pid, startedAt };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the shell the acquisition runs through: Git Bash → PowerShell →
+ * no shell. Never throws, and never returns a shell without a `note`.
+ */
+export async function resolveAcquireShell(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const probeFile = options.probeFile ?? existsSync;
+    const probe = await probeShell({
+        platform,
+        env,
+        probeFile,
+        ...(options.runner !== undefined ? { runner: options.runner } : {})
+    });
+    if (probe.available && probe.path !== null) {
+        return { kind: 'bash', path: probe.path, note: `bash: ${probe.path} (${probe.reason})` };
+    }
+    const powershell = await findPowershell(platform, env, probeFile);
+    if (powershell !== null) {
+        return {
+            kind: 'powershell',
+            path: powershell,
+            note: `PowerShell: ${powershell} — Git Bash is absent on this host (${probe.reason})`
+        };
+    }
+    return {
+        kind: 'direct',
+        path: null,
+        note: 'no shell: this host has neither Git Bash nor PowerShell, so npx is launched directly'
+    };
+}
+/**
+ * The Windows PowerShell that ships with the OS, or `null`.
+ *
+ * Its location is not searched for on PATH: `%SystemRoot%\System32\
+ * WindowsPowerShell\v1.0\powershell.exe` is where Windows has put it since
+ * Windows 7, and a PATH that cannot see it is a PATH problem the `direct`
+ * branch below already survives.
+ */
+async function findPowershell(platform, env, probeFile) {
+    if (platform !== 'win32') {
+        return null;
+    }
+    const root = env['SystemRoot'] ?? env['windir'] ?? 'C:\\Windows';
+    const candidate = join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    return (await probeFile(candidate)) ? candidate : null;
+}
+/**
+ * The exact argv of the one-time acquisition. Exported so a unit test can
+ * assert the arguments WITHOUT spawning anything — an install is not a test's
+ * side effect (same rule as `installCommandLine`).
+ *
+ * `--yes` is what makes this non-interactive: without it `npx` stops to ask
+ * "Ok to proceed?" on a machine that has not cached the package, which is the
+ * hang this verb exists to avoid.
+ */
+export function acquireCommandArgs() {
+    return ['--yes', '--package', OCR_18_PACKAGE, '--', 'ocr', 'version'];
+}
+/**
+ * The same argv as ONE shell line, for the bash / PowerShell branches.
+ *
+ * Every token is double-quoted, and that is load-bearing rather than
+ * cosmetic: a bare `@alibaba-group/…` is PowerShell's array syntax. Every
+ * token here is a module constant built from `OCR_18_PACKAGE`, so quoting is
+ * sufficient — no token carries a `"`, `\`, `$` or backtick that the two
+ * shells would escape differently, and none is caller-supplied.
+ */
+export function acquireCommandLine() {
+    return ['npx', ...acquireCommandArgs()].map((token) => `"${token}"`).join(' ');
+}
+/**
+ * Run the acquisition once, under the lock. Returns an outcome on every path —
+ * a held lock, a non-zero exit, a timeout, a thrown spawn — so no caller ever
+ * sees an exception from here, and never a silent no-op.
+ */
+export async function acquireOcr18(options = {}) {
+    const startedAt = Date.now();
+    const shell = options.shell ?? (await resolveAcquireShell());
+    let locked = false;
+    try {
+        locked = acquireOcrLock();
+        if (!locked) {
+            return failure('OCR18_ACQUIRE_BUSY', 'another OCR 1.8.x acquisition is already running on this machine; ' +
+                `the lock (${ocrAcquireLockPath()}) prevents a second download — retry once it finishes`, shell, startedAt);
+        }
+        // R2's discipline, mirrored: name the network wait BEFORE the block, on the
+        // channel a human reads, so the pause is never unexplained.
+        process.stderr.write(`peaks code-review: ${ACQUIRE_NETWORK_WARNING}\n`);
+        const result = runOcrAcquire(shell, options.asJson === true);
+        if (result.error !== undefined && result.error !== null) {
+            return spawnFailure(result.error, shell, startedAt);
+        }
+        if (result.status !== 0) {
+            return failure('OCR18_ACQUIRE_FAILED', `\`npx --package ${OCR_18_PACKAGE} -- ocr version\` exited with status ` +
+                `${String(result.status)} (shell: ${shell.kind})`, shell, startedAt);
+        }
+        return {
+            ok: true,
+            code: '',
+            message: '',
+            shell,
+            durationMs: Date.now() - startedAt,
+            warnings: [ACQUIRE_NETWORK_WARNING]
+        };
+    }
+    catch (error) {
+        return failure('OCR18_ACQUIRE_FAILED', getErrorMessage(error), shell, startedAt);
+    }
+    finally {
+        // Every path releases, including a thrown spawn — but only if THIS call
+        // took the lock; releasing someone else's would let a second install in.
+        if (locked) {
+            releaseOcrLock();
+        }
+    }
+}
+/**
+ * One blocking acquisition. See the module docstring for why `stdio` is the
+ * visibility switch and why `windowsHide` complements rather than hides it.
+ */
+function runOcrAcquire(shell, asJson) {
+    const stdio = asJson ? ['ignore', 'ignore', 'inherit'] : 'inherit';
+    const options = { stdio, timeout: ACQUIRE_TIMEOUT_MS, windowsHide: true };
+    if (shell.kind === 'powershell' && shell.path !== null) {
+        return spawnSync(shell.path, ['-NoProfile', '-NonInteractive', '-Command', acquireCommandLine()], options);
+    }
+    if (shell.kind === 'bash' && shell.path !== null) {
+        return spawnSync(shell.path, ['-c', acquireCommandLine()], options);
+    }
+    // No shell at all: bypass the Windows `npx.cmd` shim the way every other
+    // spawn in this repo does (see `resolveNpxInvocation`). `shell: true` is NOT
+    // an alternative — it concatenates and splits the `--package` argv.
+    const invocation = resolveNpxInvocation(acquireCommandArgs());
+    return spawnSync(invocation.command, [...invocation.args], { ...options, env: invocation.baseEnv });
+}
+function spawnFailure(error, shell, startedAt) {
+    const code = error.code === 'ETIMEDOUT' ? 'OCR18_ACQUIRE_TIMEOUT' : 'OCR18_ACQUIRE_FAILED';
+    return failure(code, `the acquisition did not complete: ${error.message}`, shell, startedAt);
+}
+function failure(code, message, shell, startedAt) {
+    return { ok: false, code, message, shell, durationMs: Date.now() - startedAt, warnings: [] };
+}

package/dist/services/lint/ocr-multilang-adapter.js

@@ -3,6 +3,7 @@
  * 8 supported languages to the corresponding `ocr review` filter.
  */
 import { spawnSync } from 'node:child_process';
+import { resolveNpxInvocation } from './npx-resolver.js';
 export const OCR_18_PACKAGE = '@alibaba-group/open-code-review@1.8.9';
 export const OCR_18_LANGUAGES = [
     'python',
@@ -75,10 +76,18 @@ export function runOcr18(options) {
     const spawnOptions = {
         cwd: options.cwd,
         encoding: 'utf8',
+        // Repo convention: without this the child pops a console window on the
+        // user's desktop — and this child can run for the length of a full review.
+        windowsHide: true,
         timeout: options.timeoutMs ?? 60_000,
         maxBuffer: 32 * 1024 * 1024
     };
-    const result = spawnSync('npx', args, spawnOptions);
+    // 2026-09-10: bare `spawnSync('npx', …)` cannot launch the Windows `npx.cmd`
+    // shim (ENOENT, no shell) — same fix and same helper as `detect-ocr-18.ts` /
+    // `detect-eslint.ts`. `shell: true` is NOT an option: it would concatenate the
+    // argv unescaped and split the `--package` flag.
+    const { command, args: npxArgs, baseEnv } = resolveNpxInvocation(args);
+    const result = spawnSync(command, npxArgs, { ...spawnOptions, env: baseEnv });
     const stdout = typeof result.stdout === 'string' ? result.stdout : '';
     const stderr = typeof result.stderr === 'string' ? result.stderr : '';
     if (result.error !== undefined && result.error !== null) {
@@ -87,7 +96,8 @@ export function runOcr18(options) {
             findings: [],
             summary: null,
             durationMs: Date.now() - start,
-            rawOutput: stderr || stdout
+            // Never discard WHY the launch failed — stdout/stderr are both empty here.
+            rawOutput: stderr || stdout || result.error.message
         };
     }
     if (result.status !== 0) {

package/dist/services/skills/hooks-codegate-superpowers.d.ts

@@ -95,4 +95,45 @@ export declare function resolveLegacySentinels(ide: IdeId): ReadonlyArray<string
 export declare const SUPERPOWERS_DENIED_SKILLS: ReadonlyArray<string>;
 export declare function formatSuperpowersDenyEntry(skillId: string): string;
 export declare const SUPERPOWERS_DENY_SENTINELS: ReadonlySet<string>;
+/**
+ * Adapter table: a Peaks *concept* → the settings value an EXTERNAL,
+ * non-Peaks PreToolUse gate must read to honour it.
+ *
+ * The concept Peaks holds is "the `.peaks/**` workspace tree is not project
+ * source, so 'who imports this / what schema' carries no signal there".
+ * Peaks already enforces it for its own hooks: slice 2.0.1-bug3 materializes
+ * a `Write|Edit|MultiEdit` bypass in `.claude/settings.local.json` precisely
+ * so the first workspace write is never fact-gated. This table is that same
+ * intent declared to a gate Peaks does not own.
+ *
+ * The mapped key is read by the ECC plugin's `gateguard-fact-force` hook: a
+ * comma-separated glob list matched against the normalized (forward-slash,
+ * lowercased) path, where a match skips first-touch fact-forcing. The row is
+ * INERT when that plugin is absent — an env var nothing reads.
+ *
+ * The key below is the ONLY occurrence of that third-party name in the source
+ * tree (a test pins the count). Vendor-specific translation belongs in the
+ * adapter layer, next to `HOOK_COMMAND_BY_IDE` and `resolveHookShell` — never
+ * scattered through the installer. And it is emitted into a MACHINE-LOCAL
+ * settings file only (see `resolveHookTargets`): a third-party variable name in
+ * the COMMITTED shared settings would be pushed to every consumer of this repo.
+ */
+export declare const EXTERNAL_GATE_EXEMPT_ENV: Readonly<Record<string, string>>;
+/** True when every `EXTERNAL_GATE_EXEMPT_ENV` glob is already declared in `settings.env`. */
+export declare function hasExternalGateExemptions(settings: Record<string, unknown>): boolean;
+/**
+ * Union every `EXTERNAL_GATE_EXEMPT_ENV` row into `settings.env`. An existing
+ * value is EXTENDED, never replaced, so a user who exempted other trees keeps
+ * them; unrelated `env` keys are untouched. Rows already carrying our glob are
+ * left byte-identical (so a re-run cannot churn the file), and the input object
+ * is returned unchanged when there is nothing to add. Pure.
+ */
+export declare function withExternalGateExemptions(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Inverse of `withExternalGateExemptions`: remove exactly the globs this repo
+ * added, keeping any the user wrote. The key is deleted once it holds nothing
+ * of ours, and `env` itself is dropped when it becomes empty — so uninstall
+ * leaves no orphan field behind. Pure.
+ */
+export declare function withoutExternalGateExemptions(settings: Record<string, unknown>): Record<string, unknown>;
 export {};

package/dist/services/skills/hooks-codegate-superpowers.js

@@ -233,3 +233,98 @@ export function formatSuperpowersDenyEntry(skillId) {
     return `UseSkill(${skillId})`;
 }
 export const SUPERPOWERS_DENY_SENTINELS = new Set(SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry));
+// --- External (third-party) PreToolUse gate exemptions ---------------------
+/**
+ * Adapter table: a Peaks *concept* → the settings value an EXTERNAL,
+ * non-Peaks PreToolUse gate must read to honour it.
+ *
+ * The concept Peaks holds is "the `.peaks/**` workspace tree is not project
+ * source, so 'who imports this / what schema' carries no signal there".
+ * Peaks already enforces it for its own hooks: slice 2.0.1-bug3 materializes
+ * a `Write|Edit|MultiEdit` bypass in `.claude/settings.local.json` precisely
+ * so the first workspace write is never fact-gated. This table is that same
+ * intent declared to a gate Peaks does not own.
+ *
+ * The mapped key is read by the ECC plugin's `gateguard-fact-force` hook: a
+ * comma-separated glob list matched against the normalized (forward-slash,
+ * lowercased) path, where a match skips first-touch fact-forcing. The row is
+ * INERT when that plugin is absent — an env var nothing reads.
+ *
+ * The key below is the ONLY occurrence of that third-party name in the source
+ * tree (a test pins the count). Vendor-specific translation belongs in the
+ * adapter layer, next to `HOOK_COMMAND_BY_IDE` and `resolveHookShell` — never
+ * scattered through the installer. And it is emitted into a MACHINE-LOCAL
+ * settings file only (see `resolveHookTargets`): a third-party variable name in
+ * the COMMITTED shared settings would be pushed to every consumer of this repo.
+ */
+export const EXTERNAL_GATE_EXEMPT_ENV = Object.freeze({
+    // peaks' `.peaks/**` workspace tree is not project source → skip fact-forcing
+    GATEGUARD_EXEMPT_GLOBS: '.peaks/**'
+});
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Split a comma-separated glob list, dropping blanks and surrounding space. */
+function splitGlobList(value) {
+    return value.split(',').map((glob) => glob.trim()).filter((glob) => glob.length > 0);
+}
+/** True when every `EXTERNAL_GATE_EXEMPT_ENV` glob is already declared in `settings.env`. */
+export function hasExternalGateExemptions(settings) {
+    const env = isPlainObject(settings.env) ? settings.env : {};
+    return Object.entries(EXTERNAL_GATE_EXEMPT_ENV).every(([key, glob]) => {
+        const current = env[key];
+        return typeof current === 'string' && splitGlobList(current).includes(glob);
+    });
+}
+/**
+ * Union every `EXTERNAL_GATE_EXEMPT_ENV` row into `settings.env`. An existing
+ * value is EXTENDED, never replaced, so a user who exempted other trees keeps
+ * them; unrelated `env` keys are untouched. Rows already carrying our glob are
+ * left byte-identical (so a re-run cannot churn the file), and the input object
+ * is returned unchanged when there is nothing to add. Pure.
+ */
+export function withExternalGateExemptions(settings) {
+    const env = isPlainObject(settings.env) ? { ...settings.env } : {};
+    let changed = false;
+    for (const [key, glob] of Object.entries(EXTERNAL_GATE_EXEMPT_ENV)) {
+        const current = typeof env[key] === 'string' ? env[key] : '';
+        const existing = splitGlobList(current);
+        if (existing.includes(glob))
+            continue;
+        env[key] = [...existing, glob].join(',');
+        changed = true;
+    }
+    return changed ? { ...settings, env } : settings;
+}
+/**
+ * Inverse of `withExternalGateExemptions`: remove exactly the globs this repo
+ * added, keeping any the user wrote. The key is deleted once it holds nothing
+ * of ours, and `env` itself is dropped when it becomes empty — so uninstall
+ * leaves no orphan field behind. Pure.
+ */
+export function withoutExternalGateExemptions(settings) {
+    if (!isPlainObject(settings.env))
+        return settings;
+    const env = { ...settings.env };
+    let changed = false;
+    for (const [key, glob] of Object.entries(EXTERNAL_GATE_EXEMPT_ENV)) {
+        const current = env[key];
+        if (typeof current !== 'string')
+            continue;
+        const kept = splitGlobList(current).filter((entry) => entry !== glob);
+        changed = true;
+        if (kept.length > 0) {
+            env[key] = kept.join(',');
+        }
+        else {
+            delete env[key];
+        }
+    }
+    if (!changed)
+        return settings;
+    if (Object.keys(env).length === 0) {
+        const { env: _omit, ...rest } = settings;
+        return rest;
+    }
+    return { ...settings, env };
+}

package/dist/services/skills/hooks-settings-service.d.ts

@@ -68,6 +68,20 @@ export type HookInstallOptions = {
 };
 /** Default (claude-code) hook command — kept as a stable export for tests. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\" --json";
+/**
+ * One peaks-managed entry paired with the settings file it is (or will be)
+ * written to.
+ *
+ * `entries` is a flat list of the same matcher/sentinel pairs, which reads as
+ * "written to `settingsPath`" even when the entry is routed to the other file
+ * (see `resolveHookTargets`). This carries the routing explicitly so the
+ * dry-run can name the real target without a real run.
+ */
+export type HookEntryTarget = {
+    matcher: string;
+    sentinel: string;
+    settingsPath: string;
+};
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
@@ -83,6 +97,8 @@ export type HookInstallPlan = {
      * machine-local). See `resolveHookTargets`.
      */
     localSettingsPath?: string;
+    /** Every entry the install writes, paired with its target file. */
+    entryTargets: ReadonlyArray<HookEntryTarget>;
 };
 export type HookInstallResult = HookInstallPlan & {
     applied: boolean;