peaks-loop 4.0.36 → 4.0.38

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

@@ -14,10 +14,12 @@
  * the in-memory template byte-for-byte.
  *
  * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
- *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
- *      for those paths, non-zero (deny → fall through to gate) for
- *      everything else.
+ *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
+ *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
+ *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
+ *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
+ *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
+ *      bash-specific and therefore could not take a platform `shell` pin.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -31,6 +33,9 @@
  * consumer project's `.claude/settings.json` and which exits 0
  * silently for any command not guarded by a registered SOP gate.
  */
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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
@@ -55,14 +60,41 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           gate). The existing Write|Edit|MultiEdit matcher is
  *           preserved. The new matcher's exit code is the load-bearing
  *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
+ *   1.4.0 — added the `peaks gate enforce` `Bash` PreToolUse entry. It
+ *           lives here (machine-local, gitignored file) rather than in
+ *           the committed `.claude/settings.json` because its `shell`
+ *           is machine-specific: on Windows the default Git-Bash shell
+ *           force-allocates a console window on every Bash tool call.
+ *           This template is the second writer of that file, so it must
+ *           emit the entry too — otherwise `peaks workspace init` would
+ *           overwrite whatever `peaks hooks install` put there.
+ *   1.5.0 — pinned the same platform `shell` on the `peaks code
+ *           gate-step-08` handler. It runs on the same `Bash` matcher,
+ *           so leaving it un-pinned left the console-window defect in
+ *           place for half of every Bash tool call.
+ *   1.6.0 — the `Write|Edit|MultiEdit` handler no longer inlines its
+ *           JavaScript as `node -e "<js>"`. It invokes the shipped script
+ *           `src/services/hooks/write-gate.js` instead, so the command
+ *           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.3.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
@@ -104,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) {
@@ -124,70 +161,70 @@ function sameHooksArray(a, b) {
     for (let i = 0; i < a.length; i += 1) {
         const ha = a[i];
         const hb = b[i];
-        if (ha.type !== hb.type || ha.command !== hb.command) {
+        // `shell` participates in the comparison: it is machine-specific (see
+        // `resolveHookShell`), so a file written on one platform must be
+        // recognized as drifted on the other instead of silently kept.
+        if (ha.type !== hb.type || ha.command !== hb.command || ha.shell !== hb.shell) {
             return false;
         }
     }
     return true;
 }
 /**
- * Wrap an inner JavaScript payload as a shell-evaluable `node -e "..."`
- * one-liner. The returned string is what Claude Code writes verbatim
- * into `.claude/settings.local.json` under the `command` field. Per
- * Node.js docs (https://nodejs.org/api/process.html#processargv), when
- * using `-e` there is no script-file slot, so `process.argv[1]` is the
- * first user-passed extra argument. This is consistent across Windows,
- * macOS, and Linux.
+ * This module's own directory — `<root>/src/services/workspace` in the
+ * source tree, `<root>/dist/services/workspace` in a build.
  *
- * Every `"` character in the inner JS must be JSON-escaped as `\\"`
- * so that the surrounding wrapper `node -e "..."` parses correctly:
- * the shell sees the escape and passes a literal `"` to Node. A
- * single missed escape closes the wrapper early and the entire hook
- * regresses to the bash-syntax-error class of bug.
+ * Anchored on the running module rather than on `process.argv[1]`: the
+ * same reason `daemon-supervisor.ts` documents — `argv[1]` is a different
+ * file in each way the CLI is entered (`bin/peaks.js`, `src/cli/index.ts`
+ * under tsx, `dist/cli/index.js` when invoked directly), whereas the
+ * module's own location is the one fact that is always true.
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute path of the shipped Write|Edit|MultiEdit gate script.
  *
- * @param js Inner JavaScript payload. Must be a single statement or a
- *           sequence of statements joined with `;`. The wrapper does
- *           not insert any `;` between the payload and the closing
- *           `"` because Node accepts a trailing expression with `;`
- *           already terminated by the payload itself.
+ * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
+ * single relative filename resolves in BOTH trees: `src/services/hooks/` for
+ * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
+ * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
+ * `package.json#files` already ships it).
+ *
+ * Separators are normalized to `/` so the emitted command contains no
+ * backslash at all. That is what makes the handler shell-agnostic: bash
+ * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
+ * backslash in the string is one dialect's problem waiting to happen.
  */
-function wrapAsNodeOneLiner(js) {
-    // Only `"` needs JSON-escaping: the wrapper uses double quotes, so an
-    // unescaped inner `"` would close the wrapper prematurely. Backslashes
-    // do NOT need escaping here — bash inside a `"..."` wrapper reduces
-    // `\\` to `\`, so any `\X` in the inner JS reaches Node as `\X`,
-    // which is what regex literals like `/\.peaks\//` need. Adding a
-    // second `\\` → `\\` pass would double-escape backslashes and break
-    // every regex literal the inner JS contains.
-    const escaped = js.replace(/"/g, '\\"');
-    return `node -e "${escaped}"`;
+export function writeGateScriptPath() {
+    return resolve(MODULE_DIR, '..', 'hooks', 'write-gate.js').replaceAll('\\', '/');
 }
 /**
- * Build the Write|Edit|MultiEdit matcher command. The command reads
- * the candidate file path from argv[2] and exits 0 iff the path
- * contains `.peaks/_runtime/` or `.peaks/_runtime/<sessionId>/` (the change-id
- * segment is the next path component after `.peaks/`). All other
- * paths exit 1 so the gate fires normally.
+ * Build the Write|Edit|MultiEdit matcher command.
  *
- * The matcher is intentionally narrow: it only fires for tools that
- * take a `file_path` (Write/Edit/MultiEdit) and for the Bash
- * subcommand allow-list. It does NOT silently allow arbitrary paths
- * under `.peaks/_runtime/<sessionId>/` — only those matching the documented
- * pattern. Future slice work can broaden the allow-list if the
- * peaks-code workflow needs more paths.
+ * TEMPLATE_VERSION 1.6.0: `node "<script>"` with NO inline payload. The
+ * decision lives in `src/services/hooks/write-gate.js` and was relocated
+ * there verbatim. Because there is nothing left to escape, this handler is
+ * shell-dialect-independent and can carry the same platform `shell` pin as
+ * its Bash siblings (see `resolveHookShell`).
  */
 function buildWriteHookCommand() {
-    // Path-matching: allow when the path contains `.peaks/_runtime/`
-    // OR when the second `.peaks/` segment starts with anything that
-    // looks like a change-id (kebab-case slug). Exit 0 for allow, exit
-    // 1 for deny. The candidate path arrives on `process.argv[1]` per
-    // Node.js argv layout under `-e` (cross-platform consistent).
-    const js = 'const p=process.argv[1]||"";' +
-        'if(p.includes(".peaks/_runtime/"))process.exit(0);' +
-        'const m=p.match(/\\.peaks\\/([a-z0-9][a-z0-9.-]*)\\//);' +
-        'if(m&&m[1]&&m[1]!=="_runtime"&&m[1]!=="_dogfood"&&m[1]!=="_sub_agents"&&m[1]!=="memory"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
-        'process.exit(1)';
-    return wrapAsNodeOneLiner(js);
+    return `node "${writeGateScriptPath()}"`;
+}
+/**
+ * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
+ * canonical hook spec `peaks hooks install` uses. Deriving it here (rather
+ * than re-typing the literal) is what keeps the two writers of this file
+ * byte-compatible: `templateContentMatches` compares the `command` string,
+ * so any drift would make every `peaks workspace init` rewrite the file and
+ * drop whatever `peaks hooks install` had merged in.
+ */
+function buildGateEnforceHandler() {
+    const spec = resolveHookSpec('claude-code');
+    return {
+        type: 'command',
+        command: spec.hookEnforceCommand,
+        ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+    };
 }
 /**
  * Build the full template object. The shape is the subset of Claude
@@ -202,7 +239,21 @@ function buildWriteHookCommand() {
  * `.claude/settings.json` (not `.claude/settings.local.json`).
  */
 export function buildClaudeSettingsLocalJson() {
+    // TEMPLATE_VERSION 1.6.0 — the write handler can now be shell-pinned for the
+    // same Windows reason as the two Bash handlers below: a shell-form command is
+    // executed by Git Bash / MSYS2, which force-allocates a console window on
+    // every matching tool call. It could NOT take the pin while its payload was
+    // inlined JavaScript, because PowerShell does not perform bash's backslash
+    // reduction and would have corrupted the payload. `undefined` on POSIX omits
+    // 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: [
                 {
@@ -210,7 +261,8 @@ export function buildClaudeSettingsLocalJson() {
                     hooks: [
                         {
                             type: 'command',
-                            command: buildWriteHookCommand()
+                            command: buildWriteHookCommand(),
+                            ...(writeShell !== undefined ? { shell: writeShell } : {})
                         }
                     ]
                 },
@@ -223,12 +275,22 @@ export function buildClaudeSettingsLocalJson() {
                     // 2 = block (stderr contains the BLOCKED: ... reason).
                     // The existing Write|Edit|MultiEdit matcher is preserved.
                     matcher: 'Bash',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildBashGateStep08Command()
-                        }
-                    ]
+                    hooks: [buildBashGateStep08Handler()]
+                },
+                {
+                    // TEMPLATE_VERSION 1.4.0 — SOP gate enforcement. Lives in this
+                    // machine-local file (not the committed settings.json) because
+                    // `shell` is machine-specific; see the version history above and
+                    // `resolveHookShell`.
+                    //
+                    // It sits in its own matcher group on purpose: a group counts as
+                    // peaks-managed only when EVERY handler in it carries a peaks
+                    // sentinel, and the `peaks code gate-step-08` handler above does
+                    // not. Sharing a group with it would make the whole group
+                    // unmanaged, so `peaks hooks install` would append a second Bash
+                    // group and the gate would run twice per Bash call.
+                    matcher: 'Bash',
+                    hooks: [buildGateEnforceHandler()]
                 }
             ]
         }
@@ -244,11 +306,21 @@ export function buildClaudeSettingsLocalJson() {
  * re-running `peaks workspace init` on a project that already has the
  * Bash hook is a no-op (already-current).
  */
-function buildBashGateStep08Command() {
+function buildBashGateStep08Handler() {
     // The hook receives the tool call on stdin. We ignore stdin and
     // delegate entirely to `peaks code gate-step-08`, which reads
     // .peaks/_runtime/<sessionId>/job-shape.json and last-prompt.txt.
     // `${CLAUDE_PROJECT_DIR}` resolves to the consumer project's root
     // (Claude Code's standard convention).
-    return 'peaks code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
+    //
+    // TEMPLATE_VERSION 1.5.0 — shell-pinned on Windows for the same reason
+    // as the gate-enforce handler below: this runs on the same `Bash`
+    // matcher, so a shell-form command is executed by Git Bash / MSYS2,
+    // which force-allocates a console window on every Bash tool call.
+    const shell = resolveHookShell();
+    return {
+        type: 'command',
+        command: 'peaks code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"',
+        ...(shell !== undefined ? { shell } : {})
+    };
 }

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 { existsSync, readFileSync } from 'node:fs';
 import { mkdir, 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
@@ -66,7 +93,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,23 +119,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');
-            if (existing === serialized) {
-                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');

package/dist/services/workspace/workspace-service.js

@@ -3,7 +3,31 @@ import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from 'peaks-loop-shared/fs';
 import { getSessionIdCanonical, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+import { updateCallerBindingSessionId } from '../session/caller-binding-service.js';
+import { resolveCallerProjection } from '../session/resolve-caller-id.js';
 import { normalizePath } from '../../shared/path-utils.js';
+/**
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): repoint the
+ * calling process's own per-caller binding at the session id this init just
+ * bound. `getSessionIdCanonical` reads `callers/<callerId>.json` FIRST, so a
+ * binding left behind by an earlier session shadows every explicit rebind.
+ *
+ * Best-effort: an unresolvable callerId (`PEAKS_CALLER_NOT_RESOLVED`, e.g. a
+ * stock shell with no IDE adapter) means there is no binding file to
+ * repoint, and `session.json` alone answers both resolvers.
+ *
+ * @returns `true` when a binding file existed and was repointed.
+ */
+function rebindCurrentCallerBinding(projectRoot, sessionId) {
+    let callerId;
+    try {
+        callerId = resolveCallerProjection({ projectRoot, env: process.env }).callerId;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return false;
+    }
+    return updateCallerBindingSessionId(projectRoot, callerId, sessionId);
+}
 /**
  * Slice 2026-06-29-change-id-root-removal: list the immediate children of
  * `.peaks/` so the legacy sibling-dir guard can enumerate date-stamped
@@ -299,6 +323,15 @@ export async function initWorkspace(options) {
         // Either: existing session dir is empty (true leftover, no user data),
         // or the caller explicitly authorised a rebind. Overwrite.
         setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        // Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an
+        // explicit rebind must ALSO repoint this caller's per-caller binding.
+        // `getSessionIdCanonical` prefers `callers/<callerId>.json`, so leaving
+        // it untouched shadowed the rebind for every command resolving through
+        // it (session checkpoint / 24h-mode wrote into the stale session dir)
+        // while `getCurrentSessionId` (session.json) reported the new one.
+        // Only THIS caller's binding is repointed — a second caller keeps its
+        // own session by design.
+        rebindCurrentCallerBinding(options.projectRoot, options.sessionId);
         bound = true;
     }
     // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.36",
+  "version": "4.0.38",
   "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-internal-runtime": "0.0.21",
-    "peaks-loop-shared-channel": "0.0.38",
-    "peaks-loop-shared": "0.0.70",
-    "peaks-loop-mut": "0.1.34"
+    "peaks-loop-internal-runtime": "0.0.23",
+    "peaks-loop-shared": "0.0.72",
+    "peaks-loop-mut": "0.1.36",
+    "peaks-loop-shared-channel": "0.0.40"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/scripts/copy-templates.mjs

@@ -60,6 +60,18 @@ const targets = [
     src: join(packageRoot, 'src/services/skillhub/migrations'),
     dest: join(packageRoot, 'dist/services/skillhub/migrations'),
     extensions: ['.sql']
+  },
+  {
+    // Slice c5-write-hook-exec-form: the Write|Edit|MultiEdit PreToolUse gate
+    // emitted by `peaks workspace init` is invoked as `node <path>`, and the
+    // path is resolved relative to this module — `dist/services/hooks/` in an
+    // installed consumer, `src/services/hooks/` under tsx. A plain `.js` asset
+    // (not a `.ts` compiled by tsc) is what lets ONE relative filename be valid
+    // in both trees. Without this copy the hook would be a broken path in every
+    // installed consumer while every test in this repo still passed.
+    src: join(packageRoot, 'src/services/hooks'),
+    dest: join(packageRoot, 'dist/services/hooks'),
+    extensions: ['.js']
   }
 ];
 

package/scripts/sync-version.mjs

@@ -18,6 +18,26 @@ writeFileSync(
   `export const CLI_VERSION = ${JSON.stringify(version)};\n`,
 );
 
+// Slice 2026-09-11 (runtime-version-lockstep) — sync RUNTIME_VERSION.
+// `packages/peaks-loop-internal-runtime/src/index.ts` declares
+// `RUNTIME_VERSION` under a comment stating it tracks the peaks-loop root
+// version, but nothing wrote it: v4.0.37 was tagged with the constant still
+// at 4.0.36 and publish.yml's gate-cli-version step aborted before npm
+// publish. The literal is replaced in place, single-quoted — the exact
+// shape the gate greps — because the file also holds the package's public
+// exports and must never be regenerated wholesale. A literal we cannot
+// find throws instead of no-op'ing: that silence is how the drift reached CI.
+const runtimeIndexPath = resolve('packages/peaks-loop-internal-runtime/src/index.ts');
+const runtimeIndex = readFileSync(runtimeIndexPath, 'utf8');
+const runtimeDecl = /(export const RUNTIME_VERSION = ')[^']*(';)/;
+if (!runtimeDecl.test(runtimeIndex)) {
+  throw new Error(`${runtimeIndexPath}: could not find "export const RUNTIME_VERSION = '...';"`);
+}
+const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2`);
+if (syncedRuntimeIndex !== runtimeIndex) {
+  writeFileSync(runtimeIndexPath, syncedRuntimeIndex);
+}
+
 // 2026-07-23 follow-up (peaks-publish-stale fix, AC6): the shared
 // bump used to live here, gated on `PEAKS_AUTO_BUMP_SHARED === '1'`.
 // That gate was the Layer 2 root cause: publish.yml set the env on

package/skills/peaks-code/SKILL.md

@@ -235,6 +235,16 @@ triggered for this intent.
 5. LLM picks one recommendation (★ marker) with reasoning block.
 6. **Mandatory ⚠️ catch gate** — user explicitly acks / picks alt / rejects + reason.
 
+**When the scan cannot be performed, the sub-step is SKIPPED — never fabricated.** The lookups behind
+this scan are stubs in the current build: they return synthetic fragments marked internally as
+synthetic. When the scan runs on a synthetic result it **refuses** — `ok:false`,
+`BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP`, exit 1 — and prints no recommendation, no comparison table and
+no ⚠️ catch gate, because there is nothing real for the user to judge. Record the sub-step as
+**skipped with reason `synthetic-lookup`** and carry on; do not synthesise a recommendation to satisfy
+the gate. `--intent <text>` is required (the business goal, not the project path) — omitting it is
+`BEST_PRACTICE_SCAN_INTENT_REQUIRED`, also exit 1. A real scan renders the full table and the gate
+normally; wiring the real Context7 / WebSearch lookup is a future slice.
+
 **Out of scope for this sub-step:**
 - ❌ No changes to RD dispatch Karpathy prose (Step 3 unchanged)
 - ❌ No changes to QA / SC / TXT skills

package/skills/peaks-code/references/browser-workflow.md

@@ -105,7 +105,7 @@ If the page redirects to a login challenge:
 
 ## Sensitive data sanitization
 
-Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
+**Default: never persist.** Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
 
 - Login URLs, redirect URLs, OAuth callback URLs containing tokens or state.
 - Cookies, request or response headers, session tokens, storage state, QR payloads.
@@ -113,6 +113,15 @@ Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifact
 - Raw browser state, browser traces.
 - Screenshots or logs containing PII, SSO challenge content, or MFA material.
 
+**The one exception, and it is narrow.** `peaks web login --profile <name>` persists a Playwright `storageState.json` to `~/.peaks/web-profiles/<name>/`. It is allowed only when the user explicitly asks for a persistent login. An LLM must never choose it on its own initiative, and it is never part of a default workflow. That name at that path is the whole of the exception: **no other artifact may hold these values, anywhere** — not under `.peaks/_runtime/`, not elsewhere in the project tree, not elsewhere under the user's home. This file is written outside the project tree and outside git; that is a property of this one path, not a licence to persist these values wherever the project tree happens to end.
+
+**Two named carve-outs, so the rule above can be read literally.**
+
+1. **The staging file.** The state is published atomically, which means writing it to a staging file **in the same profile directory** (`0600`) and renaming it into place. The staging name is **per-run** (`storageState.json.<pid>.staging`) so two concurrent logins cannot overwrite each other's in-flight bytes — the rule sanctions *a* staging file, and that is the only form it takes. It is sanctioned **only** while a publish is in flight: it must be deleted on every failure path, must never outlive the command that created it, and nothing may ever read it as a profile. A single non-atomic write is **not** an acceptable alternative — it truncates the previous session before writing the new one, so a failed write destroys a working login and the caller is told nothing happened.
+2. **The browser's own profile directory.** A headed Chromium writes its live session cookies to an **ephemeral profile directory the browser manages itself** (under the OS temp directory for the duration of the session, normally removed on close). This is not something a login flow can prevent and it is not what this rule is about — but it is a place those values are held, so it is named here rather than left implied. Launching a headed browser to log in is therefore **never zero-exposure**, and anyone weighing the exception above should weigh that too.
+
+**The risk, stated plainly.** That file holds live session cookies and tokens for the sites that were logged into. Any process running as this user can read it. It does not expire with the browser session, and it survives until it is deleted. Deleting `~/.peaks/web-profiles/<name>/` removes what the tool stored — it does not revoke the session at the site, so log out there as well if the account matters. Only persist a login for an account that may safely stay logged in on this machine.
+
 Redact sensitive values before retention. Store evidence as sanitized observations (e.g., "user reached settings page; first 3 list items had a missing-image regression") rather than raw captures.
 
 ## Fallback when Playwright MCP is not installed