peaks-loop 4.0.14 → 4.0.15

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 4.0.15 — 2026-08-06 (rotation guards tightening + caller-derived workflowId + caller-binding primary source + atomic write hygiene)
+
+**Tightens rotation guards with 4th same-process re-resolve short-circuit** (slice `2026-08-06-rotation-guards-and-caller-binding`, commit `f38a796f`):
+- `src/services/session/session-binding-bridge.ts` introduces a module-scoped `lastResolvedOuter: { value: string | undefined; resolvedAt: number } | null` populated on every non-throw `getCurrentOuterSessionId` call (env hit / cache hit / undefined fallback). `ensureSessionWithRotation` now short-circuits on a 4th additive guard: when `lastResolvedOuter.value === currentOuterSessionId === boundOuter`, the rotation path is skipped. The 3 legacy guards (currentOuterSessionId === undefined / boundOuter empty / boundOuter === currentOuter) are preserved verbatim per PRD PB3. Test seam `_resetLastResolvedOuterForTest()` exported.
+- Tests: `tests/unit/session/rotation-guards-tightening.test.ts` (11 cases: 3 legacy-guard regressions + 4th-guard flip A→B same-process + per-process isolation + writeAtomic fallback + skipRotate + module-state integrity).
+
+**Caller-derived workflowId in legacy compat shim** (slice same, commit `2f6322a3`):
+- `src/services/skills/skill-presence-service.ts:391` switches the legacy compat shim's `workflowId` from `wf-${sessionId}-compat` to `wf-${projection.callerId.slice(0, 189)}-compat`. The slice(0, 189) protects against `WORKFLOW_ID_REGEX` overflow (3 + 200 callerId + 7 = 210 chars > 200 regex cap). `presence-lease-service.ts` and the sub-agent graph workflowId generators at `workflow-presence-lifecycle.ts:95` + `workflow-lifecycle-commands.ts:125` are untouched (per-invocation `wf-${Date.now().toString(36)}`, NOT legacy compat shims).
+- No migration of legacy `wf-<sid>-compat` leases from 4.0.14 installs; they become orphans and are reaped by the 24h30m stale-started GC at `presence-lease-service.ts:42`.
+- Tests: `tests/unit/services/skills/workflow-id-caller-derivation.test.ts` (8 cases: short / long / 200-char callerId boundary / graphRef D4a validation / 2-caller key isolation / legacy back-compat read / slice loss-free regression).
+
+**Caller-binding becomes primary binding source + atomic write hygiene** (slice same, commit `97caa66b`):
+- `src/services/session/session-binding-bridge.ts:184-310` `ensureSession` now uses a 3-tier read order: **`callers/<callerId>.json` (if `resolveCallerProjection` succeeds)** → `session.json` (fallback) → fresh-generate. Write path: BOTH files written on first bind or rotation, with `callers/<callerId>.json` FIRST (source of truth) + `session.json` SECOND (denormalized cache for legacy consumers). The lazy `resolveCallerProjection` import is wrapped in try/catch so `PEAKS_CALLER_NOT_RESOLVED` falls through to `session.json` (preserves legacy behavior).
+- `src/services/session/session-manager.ts` adds internal helper `getSessionIdFromCallerBinding` (NOT exported; called from `getSessionId` and `getSessionIdCanonical` BEFORE `readSessionFile` / `readSessionFileCanonical`). Public signatures unchanged — all 14 `getSessionId(` consumers continue to compile and run without modification.
+- `src/services/session/caller-binding-service.ts:113-133` `setCallerBinding` swaps non-atomic `writeFileSync` for `atomicWriteJson` (single-line, plus import + removal of the now-redundant `mkdirSync` block — atomicWriteJson does its own `mkdirSync(dir, { recursive: true })`).
+- `src/cli/commands/outer-cache-commands.ts:125` `peaks outer-cache write` swaps non-atomic `writeFileSync` for `atomicWriteJson` (carry-forward bug from 4.0.14 QA issue #1: a power-loss mid-write left the cache in "permanent bad state" until the next SessionStart).
+- Tests: `tests/unit/session/caller-binding-primary-source.test.ts` (11 cases: 3-tier read order / dual-write ordering / callerId-unresolved fallback / malformed file graceful fallback / `getSessionId` preservation / `skipRotate` honored / 14-consumer regression / `setCallerBinding` atomic / temp-file cleanup) + `tests/unit/cli/outer-cache-atomic-write.test.ts` (4 cases: writeFileSync residue check / atomicWriteJson call / 4.0.14 AC1-AC7 regression / simulated write failure).
+- All 5 modified files stay under the 800 LOC cap: `session-binding-bridge.ts` 527 / `skill-presence-service.ts` 695 / `session-manager.ts` 618 / `caller-binding-service.ts` 204 / `outer-cache-commands.ts` 201. Regression sweep: 229/230 PASS / 1 SKIP (pre-existing Win-only conditional). `tsc -p tsconfig.json --noEmit` clean for slice files.
+
+**Lockstep bump.** peaks-loop-shared `0.0.44 → 0.0.45` (CLI_VERSION re-stamped to 4.0.15); peaks-loop-mut `0.1.17 → 0.1.18`; peaks-loop-shared-channel `0.0.21 → 0.0.22`.
+
 ## 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`):

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

@@ -25,9 +25,10 @@
  * 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 { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { fail, ok } from 'peaks-loop-shared/result';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
 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');
@@ -88,10 +89,16 @@ export function registerOuterCacheCommands(program, io) {
         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');
+            // Slice 2026-08-06-session-cacde8-A.5c: atomic write (temp +
+            // rename) so a power-loss mid-write cannot leave the cache file
+            // truncated. `atomicWriteJson` owns its own
+            // `mkdirSync(dir, { recursive: true })` so the inline mkdir
+            // block is removed. The previous `writeFileSync` path was the
+            // 4.0.14 carry-forward QA issue #1; the bridge's cache-miss
+            // fallback treated the truncated state as a miss (safe) but
+            // the file was stuck in "permanent bad state" until the next
+            // SessionStart fired.
+            atomicWriteJson(cachePath, payload);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/services/session/binding-store.d.ts

@@ -24,14 +24,14 @@ export declare const InstanceRecordSchema: z.ZodObject<{
     callerId: z.ZodString;
     lastHeartbeat: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    callerId: string;
     lastHeartbeat: string;
     startedAt: string;
     roles: string[];
-    callerId: string;
 }, {
+    callerId: string;
     lastHeartbeat: string;
     startedAt: string;
-    callerId: string;
     roles?: string[] | undefined;
 }>;
 export declare const BindingSchema: z.ZodObject<{
@@ -45,14 +45,14 @@ export declare const BindingSchema: z.ZodObject<{
         callerId: z.ZodString;
         lastHeartbeat: z.ZodString;
     }, "strip", z.ZodTypeAny, {
+        callerId: string;
         lastHeartbeat: string;
         startedAt: string;
         roles: string[];
-        callerId: string;
     }, {
+        callerId: string;
         lastHeartbeat: string;
         startedAt: string;
-        callerId: string;
         roles?: string[] | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -61,10 +61,10 @@ export declare const BindingSchema: z.ZodObject<{
     pid: number;
     scope: string;
     instances: Record<string, {
+        callerId: string;
         lastHeartbeat: string;
         startedAt: string;
         roles: string[];
-        callerId: string;
     }>;
 }, {
     lastHeartbeat: string;
@@ -72,9 +72,9 @@ export declare const BindingSchema: z.ZodObject<{
     pid: number;
     scope: string;
     instances: Record<string, {
+        callerId: string;
         lastHeartbeat: string;
         startedAt: string;
-        callerId: string;
         roles?: string[] | undefined;
     }>;
 }>;

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

@@ -59,6 +59,13 @@ export declare function getCallerBinding(projectRoot: string, callerId: string):
  * for the binding object (callerId must match the file stem, peakSessionId
  * must be a valid session id, projectRoot is canonicalized). Idempotent:
  * re-writing the same callerId overwrites the file.
+ *
+ * Slice 2026-08-06-session-cacde8-A.5b: writes via `atomicWriteJson`
+ * (temp-file-then-rename) so a power-loss mid-write cannot leave the
+ * caller-binding file in a half-truncated state. `atomicWriteJson`
+ * owns its own `mkdirSync(dir, { recursive: true })`, so the inline
+ * mkdir block is removed. The previous `writeFileSync` path was a
+ * documented 4.0.14 carry-forward micro-fix from QA's issue #1.
  */
 export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
 /**

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

@@ -16,9 +16,10 @@
  * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
  * for the freeze-in contract.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
+import { atomicWriteJson } from '../ide/shared/atomic-json.js';
 import { CALLER_ID_REGEX } from './caller-id-types.js';
 import { getSessionDir } from './getSessionDir.js';
 /**
@@ -100,21 +101,24 @@ export function getCallerBinding(projectRoot, callerId) {
  * for the binding object (callerId must match the file stem, peakSessionId
  * must be a valid session id, projectRoot is canonicalized). Idempotent:
  * re-writing the same callerId overwrites the file.
+ *
+ * Slice 2026-08-06-session-cacde8-A.5b: writes via `atomicWriteJson`
+ * (temp-file-then-rename) so a power-loss mid-write cannot leave the
+ * caller-binding file in a half-truncated state. `atomicWriteJson`
+ * owns its own `mkdirSync(dir, { recursive: true })`, so the inline
+ * mkdir block is removed. The previous `writeFileSync` path was a
+ * documented 4.0.14 carry-forward micro-fix from QA's issue #1.
  */
 export function setCallerBinding(projectRoot, callerId, binding) {
     if (binding.callerId !== callerId) {
         throw new Error(`setCallerBinding: binding.callerId "${binding.callerId}" does not match callerId "${callerId}"`);
     }
     const bindingPath = getCallerBindingFile(projectRoot, callerId);
-    const dir = dirname(bindingPath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
     const payload = {
         ...binding,
         projectRoot: resolve(binding.projectRoot)
     };
-    writeFileSync(bindingPath, JSON.stringify(payload, null, 2), 'utf8');
+    atomicWriteJson(bindingPath, payload);
 }
 /**
  * Enumerate the per-caller binding files under

package/dist/services/session/session-binding-bridge.d.ts

@@ -18,6 +18,12 @@
  * Body of every function moved verbatim per Karpathy #3 (Surgical
  * Changes). No behavior change. The bridge adds nothing of its own.
  */
+/**
+ * Test-only seam: reset the module-scoped `lastResolvedOuter` so
+ * individual tests start with a clean slate. NOT exported as part
+ * of the public API; marked TODO(g2) for the v2.14.0 grace window.
+ */
+export declare function _resetLastResolvedOuterForTest(): void;
 export type EnsureSessionOptions = {
     /**
      * When `true`, suppress the outer-session-mismatch auto-rotation.
@@ -52,7 +58,7 @@ export declare function ensureSession(projectRoot: string): Promise<string>;
  * binding changes — and the rotation is surfaced in the return value
  * so the CLI can include it in the JSON envelope.
  *
- * Rotation is suppressed in three cases (all false-positive guards):
+ * Rotation is suppressed in four cases (all false-positive guards):
  *
  *   1. The current outer session id is undefined (no env var set) —
  *      there is no signal to compare against, defaulting to "do not
@@ -63,6 +69,16 @@ export declare function ensureSession(projectRoot: string): Promise<string>;
  *   3. The bound session's recorded outer session id matches the
  *      current one (reconnect within the same Claude session) — this
  *      is the common case, not a swap.
+ *   4. Slice 2026-08-06-session-cacde8-A.3: same-process re-resolve —
+ *      `lastResolvedOuter.value` was already set to `currentOuterSessionId`
+ *      in this process and `boundOuter` equals that same value. Long-
+ *      running presence-lease writers that re-resolve within a single
+ *      process must not rotate on every CLI heartbeat. The module-scoped
+ *      state is per-process; each fresh CLI invocation starts with
+ *      `lastResolvedOuter === null`, so this guard cannot leak across
+ *      processes. The 4th guard ONLY fires when `lastResolvedOuter.value`
+ *      is a defined string (an undefined last-resolved value still
+ *      falls through to the legacy comparison path).
  *
  * When `options.skipRotateOnOuterMismatch === true`, the rotation
  * check is short-circuited and the binding is preserved (opt-out for

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

@@ -23,6 +23,8 @@ 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 { getCallerBinding, setCallerBinding, } from './caller-binding-service.js';
+import { resolveCallerProjection } from './resolve-caller-id.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');
@@ -131,42 +133,133 @@ function writeSessionMeta(projectRoot, sessionId, meta) {
     }
     writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
 }
+// Slice 2026-08-06-session-cacde8-A.3: module-scoped state populated on
+// every non-throw `getCurrentOuterSessionId` call. The 4th rotation
+// guard in `ensureSessionWithRotation` short-circuits when both
+// `currentOuterSessionId` and `boundOuter` equal the last-resolved
+// value in this process — a common case for long-running presence-
+// lease writers that re-resolve the outer session id within the same
+// process. Each CLI invocation is a fresh process, so this guard is
+// per-invocation and cannot leak across processes.
+let lastResolvedOuter = null;
 function getCurrentOuterSessionId(projectRoot) {
+    let resolved;
     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;
+    if (typeof peaks === 'string' && peaks.length > 0) {
+        resolved = peaks;
+    }
+    else {
+        const claude = process.env.CLAUDE_CODE_SESSION_ID;
+        if (typeof claude === 'string' && claude.length > 0) {
+            resolved = claude;
+        }
+        else {
+            // 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) {
+                            resolved = parsed.outerSessionId;
+                        }
+                    }
+                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                        // fall through — file missing / malformed JSON / IO error → undefined
+                    }
                 }
             }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // fall through — file missing / malformed JSON / IO error → undefined
-            }
         }
     }
-    return undefined;
+    // Record the resolved value on every non-throw call (env hit,
+    // cache hit, or undefined fallback). The 4th rotation guard reads
+    // this field to short-circuit same-process re-resolves.
+    lastResolvedOuter = { value: resolved, resolvedAt: Date.now() };
+    return resolved;
+}
+/**
+ * Test-only seam: reset the module-scoped `lastResolvedOuter` so
+ * individual tests start with a clean slate. NOT exported as part
+ * of the public API; marked TODO(g2) for the v2.14.0 grace window.
+ */
+export function _resetLastResolvedOuterForTest() {
+    lastResolvedOuter = null;
+}
+/**
+ * Slice 2026-08-06-session-cacde8-A.5a: resolve the current callerId
+ * (if any) and look up the per-caller binding. Returns the bound
+ * sessionId + creation timestamp, or `null` when caller-id
+ * resolution fails (`PEAKS_CALLER_NOT_RESOLVED`) or no per-caller
+ * file exists. The per-caller file is the 4.0.8 source of truth;
+ * `ensureSession` consults it BEFORE `readSessionFile` so a binding
+ * written by a previous call from the same caller is preferred over
+ * a stale `session.json` (the legacy single-file binding).
+ */
+function resolveCallerBindingForEnsure(projectRoot) {
+    let projection;
+    try {
+        projection = resolveCallerProjection({ projectRoot, env: process.env });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    try {
+        const binding = getCallerBinding(projectRoot, projection.callerId);
+        if (binding === null)
+            return null;
+        return {
+            sessionId: binding.peakSessionId,
+            createdAt: binding.createdAt,
+            callerId: projection.callerId
+        };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
 }
 export async function ensureSession(projectRoot) {
+    // Slice 2026-08-06-session-cacde8-A.5a: 3-tier read order —
+    // (1) per-caller binding (caller-keyed, primary), (2) legacy
+    // `session.json`, (3) fresh-generate. The per-caller lookup is
+    // preferred when `resolveCallerProjection` succeeds AND the
+    // per-caller file exists. When `resolveCallerProjection` throws
+    // `PEAKS_CALLER_NOT_RESOLVED` we fall through to the session.json
+    // path; the legacy fallback preserves existing CLI behaviour for
+    // projects without an active IDE adapter.
+    const callerBinding = resolveCallerBindingForEnsure(projectRoot);
+    if (callerBinding !== null) {
+        // Already-bound path via caller-binding (primary). Stamp the
+        // current outer-session-id onto the bound session's meta (G3).
+        const outerSessionId = getCurrentOuterSessionId(projectRoot);
+        if (outerSessionId !== undefined) {
+            setSessionMeta(projectRoot, callerBinding.sessionId, { outerSessionId });
+        }
+        // Slice 2026-08-06-session-cacde8-A.5a: dual-write — also write
+        // the legacy `session.json` (denormalized cache) when missing,
+        // so legacy consumers (e.g. `getSessionId` callers without a
+        // resolved callerId) still find the binding. The per-caller
+        // file is the source of truth; `session.json` is regenerated
+        // here for back-compat.
+        if (readSessionFile(projectRoot) === null) {
+            writeSessionFile(projectRoot, {
+                sessionId: callerBinding.sessionId,
+                createdAt: callerBinding.createdAt,
+                projectRoot
+            });
+        }
+        return callerBinding.sessionId;
+    }
     const existing = readSessionFile(projectRoot);
     if (existing) {
         // Slice 2026-08-06-session-outer-cache (G3 / AC8-AC11): on every
@@ -210,6 +303,39 @@ export async function ensureSession(projectRoot) {
         createdAt: now,
         projectRoot
     };
+    // Slice 2026-08-06-session-cacde8-A.5a: dual-write on fresh-generate.
+    // The per-caller file is the 4.0.8 source of truth; the legacy
+    // `session.json` is a denormalized cache for consumers that have
+    // not migrated to `getCallerBinding`. Per-caller file is written
+    // FIRST; on partial-write failure of either file, the next
+    // `ensureSession` will re-derive `session.json` from the
+    // per-caller file via the tier-1 read path above.
+    const newCallerId = (() => {
+        try {
+            return resolveCallerProjection({ projectRoot, env: process.env }).callerId;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (newCallerId !== null) {
+        const payload = {
+            callerId: newCallerId,
+            peakSessionId: sessionId,
+            projectRoot,
+            createdAt: now,
+            lastActivityAt: now,
+            skill: 'peaks-code',
+            mode: 'unknown',
+            gate: 'startup'
+        };
+        try {
+            setCallerBinding(projectRoot, newCallerId, payload);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best effort; session.json write below is the legacy fallback
+        }
+    }
     writeSessionFile(projectRoot, info);
     await initWorkspace({ projectRoot, sessionId });
     // Initialize session metadata inside the session directory.
@@ -238,7 +364,7 @@ export async function ensureSession(projectRoot) {
  * binding changes — and the rotation is surfaced in the return value
  * so the CLI can include it in the JSON envelope.
  *
- * Rotation is suppressed in three cases (all false-positive guards):
+ * Rotation is suppressed in four cases (all false-positive guards):
  *
  *   1. The current outer session id is undefined (no env var set) —
  *      there is no signal to compare against, defaulting to "do not
@@ -249,6 +375,16 @@ export async function ensureSession(projectRoot) {
  *   3. The bound session's recorded outer session id matches the
  *      current one (reconnect within the same Claude session) — this
  *      is the common case, not a swap.
+ *   4. Slice 2026-08-06-session-cacde8-A.3: same-process re-resolve —
+ *      `lastResolvedOuter.value` was already set to `currentOuterSessionId`
+ *      in this process and `boundOuter` equals that same value. Long-
+ *      running presence-lease writers that re-resolve within a single
+ *      process must not rotate on every CLI heartbeat. The module-scoped
+ *      state is per-process; each fresh CLI invocation starts with
+ *      `lastResolvedOuter === null`, so this guard cannot leak across
+ *      processes. The 4th guard ONLY fires when `lastResolvedOuter.value`
+ *      is a defined string (an undefined last-resolved value still
+ *      falls through to the legacy comparison path).
  *
  * When `options.skipRotateOnOuterMismatch === true`, the rotation
  * check is short-circuited and the binding is preserved (opt-out for
@@ -277,6 +413,26 @@ export async function ensureSessionWithRotation(projectRoot, options) {
     if (boundSessionId !== null && currentOuterSessionId !== undefined) {
         const boundMeta = getSessionMeta(projectRoot, boundSessionId);
         const boundOuter = boundMeta?.outerSessionId;
+        // Slice 2026-08-06-session-cacde8-A.3: 4th guard — same-process
+        // re-resolve. When `lastResolvedOuter` was already set to the
+        // current outer AND the bound session's recorded outer equals
+        // the same value, the rotation decision was already evaluated
+        // in this process. Without this short-circuit, a long-running
+        // presence-lease writer would rotate on every heartbeat within
+        // the same process. Skipping only fires when `lastResolvedOuter`
+        // is a defined string (undefined last-resolved values fall
+        // through to the legacy comparison path so the first-ever
+        // resolve still works).
+        if (lastResolvedOuter?.value !== undefined &&
+            lastResolvedOuter.value === currentOuterSessionId &&
+            lastResolvedOuter.value === boundOuter) {
+            const sessionId = await ensureSession(projectRoot);
+            return {
+                sessionId,
+                previousSessionId: null,
+                rotationReason: null
+            };
+        }
         if (typeof boundOuter === 'string' &&
             boundOuter.length > 0 &&
             boundOuter !== currentOuterSessionId &&

package/dist/services/session/session-manager.js

@@ -11,6 +11,8 @@ import { dirname, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { projectRootsMatch, stableRealPath } from '../../shared/path-utils.js';
 import { ensureSession } from './session-binding-bridge.js';
+import { getCallerBinding } from './caller-binding-service.js';
+import { resolveCallerProjection } from './resolve-caller-id.js';
 // As of slice 2026-06-05-peaks-runtime-layer the project-level session
 // binding lives under `.peaks/_runtime/session.json`. The legacy
 // `.peaks/.session.json` path is preserved as a read-only fallback for one
@@ -398,6 +400,18 @@ export { ensureSession, ensureSessionWithRotation } from './session-binding-brid
  * @returns Session ID or null
  */
 export function getSessionId(projectRoot) {
+    // Slice 2026-08-06-session-cacde8-A.5a: caller-binding becomes
+    // primary source. Read order is (1) `getCallerBinding` if
+    // `resolveCallerProjection` succeeds, (2) `readSessionFile`
+    // (the legacy session.json), (3) null (no binding). The legacy
+    // session.json is preserved as a fallback so a project without
+    // a caller-id resolution still resolves its binding (e.g. CLI
+    // run from a stock shell with no IDE adapter). `PEAKS_CALLER_NOT_RESOLVED`
+    // falls through to the session.json path; no caller-facing exit
+    // change.
+    const fromCallerBinding = getSessionIdFromCallerBinding(projectRoot);
+    if (fromCallerBinding !== null)
+        return fromCallerBinding;
     const info = readSessionFile(projectRoot);
     return info?.sessionId ?? null;
 }
@@ -429,9 +443,32 @@ export function getSessionId(projectRoot) {
  * so this variant is opt-in.
  */
 export function getSessionIdCanonical(projectRoot) {
+    // Slice 2026-08-06-session-cacde8-A.5a: same caller-binding primary
+    // lookup as `getSessionId`; fall back to the canonical-fallback
+    // `readSessionFileCanonical` if caller-binding is absent / unresolved.
+    const fromCallerBinding = getSessionIdFromCallerBinding(projectRoot);
+    if (fromCallerBinding !== null)
+        return fromCallerBinding;
     const info = readSessionFileCanonical(projectRoot);
     return info?.sessionId ?? null;
 }
+/**
+ * Internal helper: read the caller-binding primary source.
+ * Returns `null` when caller-id resolution fails
+ * (`PEAKS_CALLER_NOT_RESOLVED`), when no per-caller file exists,
+ * or when the file is malformed. NOT exported; the public surface
+ * is still `getSessionId` / `getSessionIdCanonical`.
+ */
+function getSessionIdFromCallerBinding(projectRoot) {
+    try {
+        const projection = resolveCallerProjection({ projectRoot, env: process.env });
+        const binding = getCallerBinding(projectRoot, projection.callerId);
+        return binding?.peakSessionId ?? null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
 /**
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.

package/dist/services/skills/skill-presence-service.js

@@ -319,7 +319,19 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
                     import('./presence-lease-service.js'),
                 ]);
                 const projection = resolveCallerProjection({ projectRoot, env: process.env });
-                const workflowId = `wf-${sessionId}-compat`;
+                // Slice 2026-08-06-session-cacde8-A.4: derive the legacy compat
+                // shim's workflowId from `projection.callerId` (caller-keyed,
+                // matching the 4.0.8 caller-binding direction) instead of
+                // `sessionId` (sid-keyed, pre-4.0.8). `slice(0, 189)` caps the
+                // callerId to 189 chars so the resulting workflowId
+                // (`wf-` + callerId + `-compat`) stays under the 200-char
+                // `WORKFLOW_ID_REGEX = /^[a-zA-Z0-9._-]{1,200}$/` cap. The
+                // truncation is loss-free for regex purposes — callerId is
+                // already regex-conformant before the slice. Existing 4.0.14
+                // leases with `wf-<sid>-compat` become orphans and are GC'd
+                // by the 24h30m stale-started GC at
+                // presence-lease-service.ts:42.
+                const workflowId = `wf-${projection.callerId.slice(0, 189)}-compat`;
                 const result = leaseMod.setPresenceLease({
                     projectRoot,
                     sessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.14",
+  "version": "4.0.15",
   "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.45",
-    "peaks-loop-shared-channel": "0.0.22",
-    "peaks-loop-mut": "0.1.18"
+    "peaks-loop-mut": "0.1.19",
+    "peaks-loop-shared-channel": "0.0.23",
+    "peaks-loop-shared": "0.0.46"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"