peaks-loop 4.0.13 → 4.0.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.14 — 2026-08-06 (outer-session cache + ensureSession meta over-coverage)
+
+**Fixes the "5 terminals / 5 sessions stuck on 3fe1be" bug** (slice `2026-08-06-session-outer-cache-and-meta-coverage`, commit `f02a9b45`):
+- `src/services/session/session-binding-bridge.ts` `getCurrentOuterSessionId(projectRoot)` now resolves `PEAKS_OUTER_SESSION_ID` → `CLAUDE_CODE_SESSION_ID` → file-cache at `.peaks/_runtime/.outer-session-cache.json` → `undefined`. Any IO error or non-string `outerSessionId` is a cache-miss (no throw). The cache file lives under the existing `.peaks/_runtime/` gitignore parent rule — no `.gitignore` modification.
+- Same file: `ensureSession` early-return path now calls `setSessionMeta(projectRoot, existing.sessionId, { outerSessionId })` BEFORE returning. The on-disk `.peaks/_runtime/<sid>/session.json` always reflects the latest outerSessionId (not a stale value captured at first-bind time). All other meta fields (title / skill / mode / gate / createdAt) preserved via read-modify-write; `lastActivity` bumped to `now`.
+- `src/services/skills/hooks-settings-service.ts` `resolveHookEntries('claude-code')` now appends a SessionStart entry that runs `peaks outer-cache write --project ...` to keep the cache in sync with the active Claude Code session. Uninstall strips the entry alongside the gate-enforce entry. Multi-binary drift guard (slice 2026-08-05) still fires correctly because the SessionStart entry uses the same `peaks` binary.
+- New CLI: `peaks outer-cache write` (no flags) + `peaks outer-cache read` (returns `{ missing: true }` envelope on absent / malformed / IO error). Write exits 1 with `OUTER_CACHE_NO_ENV` when neither `PEAKS_OUTER_SESSION_ID` nor `CLAUDE_CODE_SESSION_ID` is set.
+- Tests: `tests/unit/session/get-current-outer-session-id.test.ts` (10 cases pinning env > cache > undefined ordering, cache-miss / malformed JSON / IO error tolerance) + `tests/unit/session/ensure-session-meta-coverage.test.ts` (7 cases pinning AC8-AC11 over-coverage). Regression sweep: 179/179 PASS / 1 SKIP (pre-existing Win-only conditional).
+- A.3 / A.4 / A.5 (workflowId by callerId + `session.json` migration + cross-outer rotation cases) explicitly reserved for a future session per PRD NG1-NG4.
+
+**Lockstep bump.** peaks-loop-shared `0.0.43 → 0.0.44` (CLI_VERSION re-stamped to 4.0.14); peaks-loop-mut `0.1.16 → 0.1.17`; peaks-loop-shared-channel `0.0.20 → 0.0.21`.
+
 ## 4.0.13 — 2026-08-06 (statusline empty-render fix + sid-only marker + multi-binary drift guard)
 
 **Statusline callerId fallback + active `[short-sid]` suffix** (slice `2026-08-05-statusline-empty-render-and-short-sid-suffix`, commit `4be37d08`):

package/dist/cli/commands/_register.js

@@ -36,6 +36,7 @@ import { registerWorkflowEvalCommands } from './loop-eval-commands.js';
 import { registerMutCommands } from './mut-commands.js';
 import { registerObservabilityCommands } from './observability-commands.js';
 import { registerOpenSpecCommands } from './openspec-commands.js';
+import { registerOuterCacheCommands } from './outer-cache-commands.js';
 import { registerPerfAuditCommands } from './perf-audit-commands.js';
 import { registerPerfCommands } from './perf-commands.js';
 import { registerPlaywrightCommands } from './playwright-commands.js';
@@ -127,6 +128,7 @@ const REGISTRATIONS = [
     ['adapter-commands-s2a', registerAdapterS2ACommands], ['polyrepo-commands', registerPolyrepoCommands],
     ['worktree-auth-commands', registerWorktreeAuthCommand],
     ['session-spill-demo', registerSpillDemoCommand],
+    ['outer-cache-commands', registerOuterCacheCommands],
 ];
 function dispatchRegister(register, program, io) {
     if (register.length <= 1) {

package/dist/cli/commands/outer-cache-commands.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type OuterCacheWriteOptions = {
+    readonly project?: string;
+    readonly json?: boolean;
+};
+export type OuterCacheReadOptions = {
+    readonly project?: string;
+    readonly json?: boolean;
+};
+export declare function registerOuterCacheCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/outer-cache-commands.js

@@ -0,0 +1,120 @@
+/**
+ * Slice 2026-08-06-session-outer-cache (G1 / G2) — per-project outer-session
+ * cache CLI surface.
+ *
+ * Writes and reads `.peaks/_runtime/.outer-session-cache.json` so that
+ * peaks CLI sub-processes (which typically do NOT inherit
+ * `CLAUDE_CODE_SESSION_ID` from the parent shell) can resolve the
+ * current outer session id via `getCurrentOuterSessionId(projectRoot)`
+ * in `src/services/session/session-binding-bridge.ts`.
+ *
+ * The SessionStart hook wired by `peaks hooks install` invokes
+ * `peaks outer-cache write` to keep this file in sync with the active
+ * Claude Code / Trae / IDE session. The file is under `.peaks/_runtime/`
+ * (gitignored), so no `.gitignore` change is required.
+ *
+ * Subcommand surface:
+ *   - `peaks outer-cache write` (no flags) — read PEAKS_OUTER_SESSION_ID
+ *     ?? CLAUDE_CODE_SESSION_ID, write the cache file, return JSON
+ *     envelope with `{ outerSessionId, capturedAt, cachePath, written }`.
+ *   - `peaks outer-cache read` — return
+ *     `{ outerSessionId, capturedAt, cachePath }` when present or
+ *     `{ missing: true, cachePath }` when not. Never throws on
+ *     malformed JSON / IO error.
+ *
+ * Both subcommands accept `--project <path>` (defaults to cwd / git
+ * root) and `--json` (default in TTY-less invocations).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const OUTER_SESSION_CACHE_REL = join('.peaks', '_runtime', '.outer-session-cache.json');
+function resolveCachePath(projectRoot) {
+    return join(projectRoot, OUTER_SESSION_CACHE_REL);
+}
+function readEnvOuter() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
+function readCacheFile(cachePath) {
+    if (!existsSync(cachePath))
+        return { ok: false, missing: true };
+    try {
+        const raw = readFileSync(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            typeof parsed.outerSessionId === 'string' &&
+            (parsed.outerSessionId).length > 0 &&
+            typeof parsed.capturedAt === 'string') {
+            return {
+                ok: true,
+                outerSessionId: parsed.outerSessionId,
+                capturedAt: parsed.capturedAt
+            };
+        }
+        return { ok: false, missing: true };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return { ok: false, missing: true };
+    }
+}
+export function registerOuterCacheCommands(program, io) {
+    const outerCache = program
+        .command('outer-cache')
+        .description('Read / write the per-project outer-session cache file (.peaks/_runtime/.outer-session-cache.json). The SessionStart hook installed by `peaks hooks install` keeps this file in sync with the live Claude Code / Trae / IDE session so peaks CLI sub-processes (which typically do NOT inherit CLAUDE_CODE_SESSION_ID) can resolve the current outer session via getCurrentOuterSessionId(projectRoot).');
+    addJsonOption(outerCache
+        .command('write')
+        .description('Write the current outer-session-id (PEAKS_OUTER_SESSION_ID ?? CLAUDE_CODE_SESSION_ID) into the per-project cache file. Idempotent: re-runs overwrite. Exits 1 with OUTER_CACHE_NO_ENV when neither env var is set.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project ?? (findProjectRoot(process.cwd()) ?? process.cwd());
+        const cachePath = resolveCachePath(projectRoot);
+        const outerSessionId = readEnvOuter();
+        if (outerSessionId === undefined) {
+            printResult(io, fail('outer-cache.write', 'OUTER_CACHE_NO_ENV', 'Neither PEAKS_OUTER_SESSION_ID nor CLAUDE_CODE_SESSION_ID is set; nothing to write', { cachePath, written: false, projectRoot }, [
+                'Set PEAKS_OUTER_SESSION_ID=<id> or run from inside Claude Code / Trae / IDE so CLAUDE_CODE_SESSION_ID is exported',
+                'Re-run `peaks hooks install` to wire the SessionStart hook that writes this cache automatically'
+            ]), options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        const capturedAt = new Date().toISOString();
+        const payload = { outerSessionId, capturedAt };
+        try {
+            const dir = dirname(cachePath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            writeFileSync(cachePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(io, fail('outer-cache.write', 'OUTER_CACHE_WRITE_FAILED', `Failed to write outer-session cache: ${message}`, { cachePath, written: false, projectRoot, outerSessionId, capturedAt }, [message]), options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('outer-cache.write', { cachePath, written: true, projectRoot, outerSessionId, capturedAt }, [], [`Wrote ${cachePath}; getCurrentOuterSessionId() will resolve to "${outerSessionId}" until the next SessionStart fires.`]), options.json === true);
+    });
+    addJsonOption(outerCache
+        .command('read')
+        .description('Read the current value of the per-project outer-session cache. Returns { missing: true, cachePath } when the file is absent / malformed / empty; never throws on IO error.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project ?? (findProjectRoot(process.cwd()) ?? process.cwd());
+        const cachePath = resolveCachePath(projectRoot);
+        const result = readCacheFile(cachePath);
+        if (result.ok) {
+            printResult(io, ok('outer-cache.read', { cachePath, missing: false, projectRoot, outerSessionId: result.outerSessionId, capturedAt: result.capturedAt }, [], [`outer-session-id resolved: ${result.outerSessionId} (captured ${result.capturedAt})`]), options.json === true);
+            return;
+        }
+        printResult(io, ok('outer-cache.read', { cachePath, missing: true, projectRoot }, ['No outer-session cache present — getCurrentOuterSessionId() will return undefined for this project.'], [
+            'Re-run `peaks hooks install` to wire the SessionStart hook that writes this cache automatically',
+            'Or set PEAKS_OUTER_SESSION_ID=<id> so env-first resolution wins without touching the cache'
+        ]), options.json === true);
+    });
+}

package/dist/services/session/session-binding-bridge.js

@@ -23,11 +23,18 @@ import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 import { projectRootsMatch, stableRealPath } from '../../shared/path-utils.js';
-import { getSessionId, getSessionIdCanonical, getSessionMeta, rotateSessionBinding } from './session-manager.js';
+import { getSessionId, getSessionIdCanonical, getSessionMeta, rotateSessionBinding, setSessionMeta } from './session-manager.js';
 // --- Lower-level helpers the bridge needs (moved verbatim) ---
 const SESSION_FILE = join('_runtime', 'session.json');
 const LEGACY_SESSION_FILE = '.session.json';
 const META_FILE = 'session.json';
+// Slice 2026-08-06-session-outer-cache: per-project file cache for the
+// outer (Claude Code / Trae / IDE) session id. Written by the
+// SessionStart hook via `peaks outer-cache write` so that peaks CLI
+// sub-processes (which do NOT inherit CLAUDE_CODE_SESSION_ID) can still
+// resolve the current outer session. Lives under the gitignored
+// `.peaks/_runtime/` tree, so no .gitignore change is required.
+const OUTER_SESSION_CACHE_FILE = join('_runtime', '.outer-session-cache.json');
 function getLegacySessionFilePath(projectRoot) {
     return join(projectRoot, '.peaks', LEGACY_SESSION_FILE);
 }
@@ -124,18 +131,58 @@ function writeSessionMeta(projectRoot, sessionId, meta) {
     }
     writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
 }
-function getCurrentOuterSessionId() {
+function getCurrentOuterSessionId(projectRoot) {
     const peaks = process.env.PEAKS_OUTER_SESSION_ID;
     if (typeof peaks === 'string' && peaks.length > 0)
         return peaks;
     const claude = process.env.CLAUDE_CODE_SESSION_ID;
     if (typeof claude === 'string' && claude.length > 0)
         return claude;
+    // Slice 2026-08-06-session-outer-cache (G1): when the peaks CLI runs
+    // as a sub-process of Claude Code (or any IDE that does not export
+    // CLAUDE_CODE_SESSION_ID into the child env), the env vars above are
+    // undefined. Fall back to the per-project file cache written by the
+    // SessionStart hook via `peaks outer-cache write`. The file lives
+    // under `.peaks/_runtime/` (gitignored) so no .gitignore change is
+    // required. Any IO error or non-string `outerSessionId` field is
+    // treated as a cache miss — never throw.
+    if (projectRoot !== undefined) {
+        const cachePath = join(projectRoot, '.peaks', OUTER_SESSION_CACHE_FILE);
+        if (existsSync(cachePath)) {
+            try {
+                const raw = readFileSync(cachePath, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed !== null &&
+                    typeof parsed === 'object' &&
+                    typeof parsed.outerSessionId === 'string' &&
+                    (parsed.outerSessionId).length > 0) {
+                    return parsed.outerSessionId;
+                }
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // fall through — file missing / malformed JSON / IO error → undefined
+            }
+        }
+    }
     return undefined;
 }
 export async function ensureSession(projectRoot) {
     const existing = readSessionFile(projectRoot);
     if (existing) {
+        // Slice 2026-08-06-session-outer-cache (G3 / AC8-AC11): on every
+        // already-bound invocation, stamp the current outer-session-id
+        // onto the bound session's meta so the on-disk
+        // `.peaks/_runtime/<sid>/session.json` always reflects the latest
+        // outer signal — not a stale value captured at session creation
+        // time. `setSessionMeta` is read-modify-write: every other field
+        // (title / skill / mode / gate / createdAt / lastActivity) is
+        // preserved. `getCurrentOuterSessionId(projectRoot)` reads env
+        // → file-cache → undefined; an undefined value is NOT written,
+        // so the previously-stamped outer (if any) survives.
+        const outerSessionId = getCurrentOuterSessionId(projectRoot);
+        if (outerSessionId !== undefined) {
+            setSessionMeta(projectRoot, existing.sessionId, { outerSessionId });
+        }
         return existing.sessionId;
     }
     // Slice 007 — sub-agent session sharing. When the strict-equality
@@ -165,8 +212,11 @@ export async function ensureSession(projectRoot) {
     };
     writeSessionFile(projectRoot, info);
     await initWorkspace({ projectRoot, sessionId });
-    // Initialize session metadata inside the session directory
-    const outerSessionId = getCurrentOuterSessionId();
+    // Initialize session metadata inside the session directory.
+    // Slice 2026-08-06-session-outer-cache (G1): pass `projectRoot` so
+    // the env → file-cache → undefined resolution chain also reads the
+    // SessionStart-written cache on first bind.
+    const outerSessionId = getCurrentOuterSessionId(projectRoot);
     writeSessionMeta(projectRoot, sessionId, {
         sessionId,
         projectRoot,
@@ -211,7 +261,10 @@ export async function ensureSession(projectRoot) {
  */
 export async function ensureSessionWithRotation(projectRoot, options) {
     const skipRotate = options?.skipRotateOnOuterMismatch === true;
-    const currentOuterSessionId = getCurrentOuterSessionId();
+    // Slice 2026-08-06-session-outer-cache (G1): pass `projectRoot` so
+    // the rotation-decision comparison sees the SessionStart cache
+    // when the env vars are unset (sub-process / nested invocation).
+    const currentOuterSessionId = getCurrentOuterSessionId(projectRoot);
     // Compute the rotation decision up front. We only rotate when ALL
     // three pre-conditions hold: (a) the current outer session id is
     // defined, (b) the bound session has a recorded outer session id,

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

@@ -4,6 +4,7 @@ import { 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 { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL } from './outer-cache-hook-constants.js';
 // --- Module-level defaults (claude-code) -----------------------------------
 // These exports remain for backward compat — tests and downstream callers
 // that only care about Claude Code can keep importing them. The per-IDE
@@ -181,12 +182,25 @@ export function readInstalledEntriesFromSettings(settings, ide) {
  * entry's sentinel is included in the legacy sentinel set so uninstall
  * can find + remove any stale progress-start entry that an older
  * `peaks hooks install` may have written before this slice.
+ *
+ * Slice 2026-08-06-session-outer-cache: a SessionStart outer-cache primer
+ * entry is appended for Claude Code only (SessionStart is a Claude-Code-
+ * specific event key today).
  */
 function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
-    return [
+    const entries = [
         { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
     ];
+    if (ide === 'claude-code') {
+        entries.push({
+            sentinel: HOOK_OUTER_CACHE_SENTINEL,
+            matcher: '',
+            command: HOOK_OUTER_CACHE_COMMAND,
+            event: HOOK_OUTER_CACHE_EVENT
+        });
+    }
+    return entries;
 }
 /**
  * Legacy sentinel set used by uninstall + status to find and remove stale
@@ -198,7 +212,13 @@ function resolveLegacySentinels(ide) {
     if (ide === 'trae') {
         return ['peaks hook handle', LEGACY_PROGRESS_START_SENTINEL];
     }
-    return [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
+    // Slice 2026-08-06-session-outer-cache: include the SessionStart outer-cache
+    // sentinel so uninstall strips it alongside the gate-enforce entry.
+    const base = [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
+    if (ide === 'claude-code') {
+        return [...base, HOOK_OUTER_CACHE_SENTINEL];
+    }
+    return base;
 }
 // --- Slice 2026-07-29-worktree-layer3-deny -----------------------------------
 // Layer 3 of the Worktree Governance 3-layer design (see

package/dist/services/skills/outer-cache-hook-constants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Slice 2026-08-06-session-outer-cache (G2): per-IDE SessionStart hook
+ * constants for the outer-session cache primer. Extracted from
+ * `hooks-settings-service.ts` to keep that file under the Karpathy
+ * 800 LOC cap.
+ *
+ * The SessionStart hook is fired by Claude Code (and any future IDE
+ * that ships a SessionStart-style event) every time a new outer
+ * session begins. It runs `peaks outer-cache write`, which reads
+ * PEAKS_OUTER_SESSION_ID ?? CLAUDE_CODE_SESSION_ID from env and
+ * persists it to `.peaks/_runtime/.outer-session-cache.json` so the
+ * next peaks CLI sub-process can resolve the current outer session
+ * via `getCurrentOuterSessionId(projectRoot)`.
+ *
+ * Only Claude Code supports SessionStart today; future adapters opt
+ * in by extending `resolveHookEntries` and adding an adapter-driven
+ * substitution for the `${...}` project-dir placeholder.
+ */
+/** Sentinel substring identifying a SessionStart outer-cache hook entry. */
+export declare const HOOK_OUTER_CACHE_SENTINEL = "peaks outer-cache write";
+/** Default (claude-code) SessionStart hook command. */
+export declare const HOOK_OUTER_CACHE_COMMAND = "peaks outer-cache write --project \"${CLAUDE_PROJECT_DIR}\"";
+/** SessionStart hook event key for Claude Code. */
+export declare const HOOK_OUTER_CACHE_EVENT = "SessionStart";

package/dist/services/skills/outer-cache-hook-constants.js

@@ -0,0 +1,24 @@
+/**
+ * Slice 2026-08-06-session-outer-cache (G2): per-IDE SessionStart hook
+ * constants for the outer-session cache primer. Extracted from
+ * `hooks-settings-service.ts` to keep that file under the Karpathy
+ * 800 LOC cap.
+ *
+ * The SessionStart hook is fired by Claude Code (and any future IDE
+ * that ships a SessionStart-style event) every time a new outer
+ * session begins. It runs `peaks outer-cache write`, which reads
+ * PEAKS_OUTER_SESSION_ID ?? CLAUDE_CODE_SESSION_ID from env and
+ * persists it to `.peaks/_runtime/.outer-session-cache.json` so the
+ * next peaks CLI sub-process can resolve the current outer session
+ * via `getCurrentOuterSessionId(projectRoot)`.
+ *
+ * Only Claude Code supports SessionStart today; future adapters opt
+ * in by extending `resolveHookEntries` and adding an adapter-driven
+ * substitution for the `${...}` project-dir placeholder.
+ */
+/** Sentinel substring identifying a SessionStart outer-cache hook entry. */
+export const HOOK_OUTER_CACHE_SENTINEL = 'peaks outer-cache write';
+/** Default (claude-code) SessionStart hook command. */
+export const HOOK_OUTER_CACHE_COMMAND = `peaks outer-cache write --project "\${CLAUDE_PROJECT_DIR}"`;
+/** SessionStart hook event key for Claude Code. */
+export const HOOK_OUTER_CACHE_EVENT = 'SessionStart';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.13",
+  "version": "4.0.14",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -100,9 +100,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-shared": "0.0.44",
-    "peaks-loop-mut": "0.1.17",
-    "peaks-loop-shared-channel": "0.0.21"
+    "peaks-loop-shared": "0.0.45",
+    "peaks-loop-shared-channel": "0.0.22",
+    "peaks-loop-mut": "0.1.18"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"