peaks-loop 4.0.35 → 4.0.37

package/dist/services/release/version-precheck-service.js

@@ -114,9 +114,16 @@ export function runRootVsShared(opts) {
 export function runTagCollision(opts) {
     const rootVersion = readRootVersion(opts.projectRoot);
     const tagName = `v${rootVersion}`;
-    // Windows shell wrapping convention: 5 prior occurrences in tests/unit/release/.
+    // 2026-09-10: no shell. `git` is `git.exe` on Windows, so the wrapper bought
+    // nothing — and it actively broke this layer, because `projectRoot` is an
+    // ARGUMENT to git and a shell wraps the command line unescaped. On a project
+    // whose path contains a space the shell split it, git exited 128
+    // ("cannot change to '…'"), and the layer fell through to its
+    // "git tag --list exited with code 128; layer skipped" WARNING — so a real
+    // tag collision was reported as merely deferred. Reproduced on
+    // `…\Temp\peaks space demo` with tag v9.9.9 present: warning (should be
+    // blocker). It also emitted DEP0190 on every run, on every layer.
     const res = spawnSync('git', ['-C', opts.projectRoot, 'tag', '--list', tagName], {
-        shell: process.platform === 'win32',
         encoding: 'utf8',
         timeout: 5_000
     });

package/dist/services/scan/file-size-scan.d.ts

@@ -1,4 +1,29 @@
 export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export declare const SIZE_CAP_EXEMPT_PATTERNS: readonly string[];
+export declare function isSizeCapExempt(file: string): boolean;
 export type FileSizeViolation = {
     file: string;
     lines: number;
@@ -7,6 +32,10 @@ export type FileSizeScanResult = {
     ok: boolean;
     threshold: number;
     checkedFiles: number;
+    /** Paths skipped by SIZE_CAP_EXEMPT_PATTERNS (tool output + append-only
+     *  records). Reported so the exemption is auditable rather than a silent
+     *  skip. */
+    exemptFiles: string[];
     /** Files that appeared in `git diff` but no longer exist on disk (e.g.
      *  deleted in the working tree). Pre-#015 the scan crashed on these via
      *  ENOENT; now they are reported here as informational data. */

package/dist/services/scan/file-size-scan.js

@@ -2,6 +2,63 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export const SIZE_CAP_EXEMPT_PATTERNS = [
+    // tool output
+    '.peaks/**',
+    '**/pnpm-lock.yaml',
+    '**/package-lock.json',
+    '**/yarn.lock',
+    // append-only records
+    '**/CHANGELOG.md'
+];
+/**
+ * Glob → RegExp for the shapes above only, in a single split pass (chained
+ * string replaces would re-expand the `.*` they had just produced). The
+ * directory-wildcard prefix matches zero directories, so a root-level
+ * lockfile still counts.
+ */
+function exemptPatternToRegExp(pattern) {
+    const body = pattern
+        .split(/(\*\*\/|\*\*|\*)/)
+        .map((part) => {
+        if (part === '**/')
+            return '(?:.*/)?';
+        if (part === '**')
+            return '.*';
+        if (part === '*')
+            return '[^/]*';
+        return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('');
+    return new RegExp(`^${body}$`);
+}
+export function isSizeCapExempt(file) {
+    const normalized = file.replace(/\\/g, '/');
+    return SIZE_CAP_EXEMPT_PATTERNS.some((pattern) => exemptPatternToRegExp(pattern).test(normalized));
+}
 function getChangedFiles(projectRoot, baseRef) {
     try {
         // --diff-filter=AM keeps only Added + Modified entries. Deleted files
@@ -28,8 +85,13 @@ export function scanFileSize(options) {
     const files = getChangedFiles(options.projectRoot, baseRef);
     const violations = [];
     const deletedFiles = [];
+    const exemptFiles = [];
     let checkedFiles = 0;
     for (const file of files) {
+        if (isSizeCapExempt(file)) {
+            exemptFiles.push(file);
+            continue;
+        }
         const absolute = join(options.projectRoot, file);
         // Pre-#015: readFileSync threw ENOENT for files that appear in
         // `git diff --name-only` but no longer exist on disk (e.g. a refactor
@@ -62,6 +124,7 @@ export function scanFileSize(options) {
         ok: violations.length === 0,
         threshold,
         checkedFiles,
+        exemptFiles,
         deletedFiles,
         violations
     };

package/dist/services/session/caller-binding-service.d.ts

@@ -68,6 +68,30 @@ export declare function getCallerBinding(projectRoot: string, callerId: string):
  * documented 4.0.14 carry-forward micro-fix from QA's issue #1.
  */
 export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export declare function updateCallerBindingSessionId(projectRoot: string, callerId: string, peakSessionId: string): boolean;
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the

package/dist/services/session/caller-binding-service.js

@@ -120,6 +120,40 @@ export function setCallerBinding(projectRoot, callerId, binding) {
     };
     atomicWriteJson(bindingPath, payload);
 }
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export function updateCallerBindingSessionId(projectRoot, callerId, peakSessionId) {
+    const existing = getCallerBinding(projectRoot, callerId);
+    if (existing === null)
+        return false;
+    setCallerBinding(projectRoot, callerId, {
+        ...existing,
+        peakSessionId,
+        lastActivityAt: new Date().toISOString()
+    });
+    return true;
+}
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the

package/dist/services/session/getSessionDir.js

@@ -2,20 +2,25 @@
  * Canonical session-directory resolver.
  *
  * As of slice 2026-06-05-peaks-runtime-layer the per-session workspace
- * lives at `<root>/.peaks/_runtime/<sessionId>/` (NOT at the legacy
- * `<root>/.peaks/_runtime/<sessionId>/` location). All **write** paths MUST route
- * through this helper. The legacy top-level path is preserved as a
- * back-compat **read** fallback only (see
- * `src/services/artifacts/request-artifact-service.ts:662` etc.).
+ * lives at `<root>/.peaks/_runtime/<sessionId>/`, NOT at the legacy
+ * `<root>/.peaks/<sessionId>/` location. All **write** paths MUST route
+ * through this helper. The legacy top-level path survives only as a
+ * back-compat **read** fallback (see `legacySessionRoot` in
+ * `src/services/artifacts/artifact-prerequisites.ts` and `sessionOwnsSlice`
+ * in `src/services/sc/sc-service.ts`).
  *
- * The corresponding test in
  * `tests/unit/services/session/session-dir-canonical.test.ts` enforces
- * two invariants:
+ * three invariants:
  *
  *   (a) `getSessionDir(root, sid)` returns `<root>/.peaks/_runtime/<sid>`.
- *   (b) A static scan of `src/` flags any direct join of `.peaks` +
- *       `sessionId` that does NOT route through this resolver. The
- *       back-compat **read** sites are excluded by explicit allow-list.
+ *   (b) A static scan of `src/**` flags any `join()` chain that names
+ *       `.peaks` plus a session id without routing through this resolver,
+ *       wherever the id sits in the chain. The back-compat **read** sites
+ *       are exempted by an allow-list whose entries are asserted to be
+ *       load-bearing (an inert entry fails the scan).
+ *   (c) A static scan of every markdown file under `skills/` flags a
+ *       legacy `.peaks/<sid>/...` artifact path that a sub-agent would
+ *       follow verbatim.
  *
  * @param projectRoot - Absolute path to the project root.
  * @param sessionId - The session identifier (e.g. `2026-06-06-session-5b1095`).

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

@@ -15,7 +15,32 @@ interface ResolvedHookSpec {
     readonly hookEnforceSentinel: string;
     readonly hookEnforceMatcher: string;
     readonly hookEnforceEvent: string;
+    /**
+     * True when the gate-enforce entry must be materialized into the IDE's
+     * MACHINE-LOCAL settings file rather than the shared one (see
+     * `hookEnforceShell` below). Set for Claude Code, whose project-scope
+     * hooks have a gitignored per-machine sibling file.
+     */
+    readonly hookEnforceMachineLocal: boolean;
+    /**
+     * The `shell` field for the gate-enforce handler, or `undefined` to omit
+     * the key entirely and let the IDE use its documented default.
+     *
+     * Claude Code only. See `resolveHookShell` for why Windows needs this.
+     */
+    readonly hookEnforceShell: string | undefined;
 }
+/**
+ * Claude Code runs a shell-form hook command through a shell that defaults
+ * to bash — which on Windows means Git Bash, and MSYS2's bash
+ * force-allocates its own console window. The result is a visible window on
+ * EVERY Bash tool call. The window is created by the spawner (Claude Code)
+ * before any peaks code runs, so `windowsHide` and any in-process hiding
+ * cannot help; pinning the hook's `shell` is the only lever the hook schema
+ * offers. The platform-neutral default (`undefined` → omit the key) is kept
+ * everywhere else.
+ */
+export declare function resolveHookShell(platform?: NodeJS.Platform): string | undefined;
 export declare function resolveHookSpec(ide: IdeId): ResolvedHookSpec;
 /** A typed descriptor for a single peaks-managed hook entry. */
 export type PeaksHookEntry = {
@@ -23,6 +48,14 @@ export type PeaksHookEntry = {
     matcher: string;
     command: string;
     event: string;
+    /**
+     * When true the entry is written to the machine-local, gitignored settings
+     * file (`.claude/settings.local.json`) instead of the shared one, because
+     * the entry carries a machine-specific value (the `shell` field).
+     */
+    machineLocal?: boolean;
+    /** Optional `shell` field for the emitted handler. */
+    shell?: string;
 };
 /**
  * Slice 2026-08-06-codegate-vendor-neutral — code-gate hook entry.

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

@@ -11,6 +11,19 @@ import { getAdapter } from '../ide/ide-registry.js';
 import { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
+/**
+ * Claude Code runs a shell-form hook command through a shell that defaults
+ * to bash — which on Windows means Git Bash, and MSYS2's bash
+ * force-allocates its own console window. The result is a visible window on
+ * EVERY Bash tool call. The window is created by the spawner (Claude Code)
+ * before any peaks code runs, so `windowsHide` and any in-process hiding
+ * cannot help; pinning the hook's `shell` is the only lever the hook schema
+ * offers. The platform-neutral default (`undefined` → omit the key) is kept
+ * everywhere else.
+ */
+export function resolveHookShell(platform = process.platform) {
+    return platform === 'win32' ? 'powershell' : undefined;
+}
 /**
  * Per-IDE hook command + sentinel. The default (Claude Code) uses the
  * legacy `peaks gate enforce` surface; Trae / Cursor / Codex (Cursor-style
@@ -42,11 +55,22 @@ export function resolveHookSpec(ide) {
         // silently writing a Claude-shaped entry to a non-Claude settings.json.
         throw new Error(`peaks hooks install: unsupported IDE '${ide}' (no HOOK_COMMAND_BY_IDE entry; add one to hooks-settings-service.ts)`);
     }
+    const isClaudeCode = ide === 'claude-code';
+    // Claude Code's gate hook must emit its structured decision as JSON:
+    // without `--json` the hook validator rejects the plain `{}` stdout with
+    // "Hook JSON output validation failed". See
+    // .peaks/memory/bash-pretooluse-hook-json-error-fix.md.
+    const jsonFlag = isClaudeCode ? ' --json' : '';
     return {
-        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"`,
+        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"${jsonFlag}`,
         hookEnforceSentinel: spec.sentinel,
         hookEnforceMatcher: adapter.toolMatcher,
-        hookEnforceEvent: adapter.hookEvent
+        hookEnforceEvent: adapter.hookEvent,
+        // Only Claude Code has the machine-local sibling settings file the
+        // routing depends on, and only Claude Code's hook schema accepts a
+        // `shell` key.
+        hookEnforceMachineLocal: isClaudeCode,
+        hookEnforceShell: isClaudeCode ? resolveHookShell() : undefined
     };
 }
 /**
@@ -64,7 +88,14 @@ export const HOOK_CODE_GATE_COMMAND = `peaks code-gate --json`;
 export function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
     const entries = [
-        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+        {
+            sentinel: spec.hookEnforceSentinel,
+            matcher: spec.hookEnforceMatcher,
+            command: spec.hookEnforceCommand,
+            event: spec.hookEnforceEvent,
+            machineLocal: spec.hookEnforceMachineLocal,
+            ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+        }
     ];
     if (ide === 'claude-code') {
         entries.push({

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

@@ -76,6 +76,13 @@ export type HookInstallPlan = {
     desiredCommand: string;
     sentinel: string;
     matcher: string;
+    /**
+     * Machine-local, gitignored settings file that the gate-enforce entry is
+     * written to instead of `settingsPath`. Undefined when the IDE has no such
+     * file (or the scope is global, where the settings file is already
+     * machine-local). See `resolveHookTargets`.
+     */
+    localSettingsPath?: string;
 };
 export type HookInstallResult = HookInstallPlan & {
     applied: boolean;
@@ -83,12 +90,15 @@ export type HookInstallResult = HookInstallPlan & {
 export type HookRemoveResult = {
     scope: HookScope;
     settingsPath: string;
+    localSettingsPath?: string;
     removed: boolean;
 };
 export type HookStatus = {
     scope: HookScope;
     settingsPath: string;
     exists: boolean;
+    localSettingsPath?: string;
+    localExists?: boolean;
     installed: boolean;
 };
 /**