peaks-loop 4.0.11 → 4.0.12

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

@@ -2,7 +2,15 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname, join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
-import { getSessionMeta } from '../session/session-manager.js';
+import { getSessionId, getSessionMeta } from '../session/session-manager.js';
+// Slice 4.0.8 compat shim: the canonical write path lives in
+// `presence-lease-service.ts`. The legacy shim dynamically imports
+// it inside `setSkillPresence` so the cold path of the legacy
+// `getSkillPresence` / `checkStalePresence` / `clearStalePresenceOnRotation`
+// read paths stays cheap. The static imports below are reserved for
+// the migration window and are referenced through the dynamic
+// `leaseMod.*` accessor at runtime.
+import { listPresenceLeases } from './presence-lease-service.js';
 // Re-export the 4.0.8 compat surface so legacy callers
 // (`presence-service` consumers in `code-mode-gate-commands.ts`,
 // `mode-enforcement.ts`, `code-job-shape-commands.ts`, etc.) keep
@@ -37,14 +45,13 @@ function getCurrentOuterSessionId() {
         return claude;
     return undefined;
 }
-// As of slice 2026-06-05-peaks-runtime-layer the orchestrator's
-// active-skill marker lives under `.peaks/_runtime/active-skill.json`.
-// The legacy `.peaks/.active-skill.json` path is preserved as a
-// read-only fallback for one minor release so older CLI versions (or
-// trees that have not been migrated by `peaks workspace reconcile`)
-// keep working without a forced re-init.
-const PRESENCE_FILE = join('.peaks', '_runtime', 'active-skill.json');
-const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
+// Slice 4.0.11 statusline-sid-scoped-lease C: the deprecated
+// project-level single-slot presence files
+// `.peaks/_runtime/active-skill.json` and `.peaks/.active-skill.json`
+// are REMOVED from this module. The canonical sid-scoped lease
+// projection (`.peaks/_runtime/<sid>/leases/presence-*.json`) is the
+// only source of truth. The legacy constants `PRESENCE_FILE` and
+// `PRESENCE_FILE_LEGACY` are deleted; readers use `listPresenceLeases`.
 const SESSION_FILE = join('.peaks', '_runtime', 'session.json');
 const SESSION_FILE_LEGACY = '.peaks/.session.json';
 function resolveProjectRoot(override) {
@@ -52,36 +59,6 @@ function resolveProjectRoot(override) {
         return resolve(override);
     return findProjectRoot(process.cwd()) ?? process.cwd();
 }
-function resolvePresencePath(projectRootOverride) {
-    return resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE);
-}
-/**
- * Back-compat read for the active-skill marker. Prefers the new
- * canonical `.peaks/_runtime/active-skill.json`; falls back to the
- * legacy `.peaks/.active-skill.json` for one minor release.
- *
- * Returns the parsed SkillPresence object, or null when neither
- * file is present / valid. The legacy file is never written by
- * current code — only the new path receives writes.
- */
-function readSkillPresenceBackCompat(projectRootOverride) {
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
-    const pathToRead = existsSync(presencePath) ? presencePath : legacyPath;
-    if (!existsSync(pathToRead))
-        return null;
-    try {
-        const raw = readFileSync(pathToRead, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
-            return null;
-        }
-        return { presence: parsed, path: pathToRead };
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-}
 /**
  * Resolve the active peaks session id from
  * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
@@ -112,6 +89,43 @@ export function getCurrentSessionId(projectRootOverride) {
         return null;
     }
 }
+/**
+ * Slice 4.0.11 statusline-sid-scoped-lease C: read the canonical
+ * sid-scoped lease projection and project the freshest in-flight
+ * lease into the legacy `SkillPresence` shape that the public
+ * `getSkillPresence` / `checkStalePresence` /
+ * `clearStalePresenceOnRotation` consumers expect. The projection
+ * is lossy (the lease does not carry `outerSessionId`; `setAt`
+ * maps to `startedAt`; `lastHeartbeat` is reused as `lastHeartbeat`).
+ *
+ * Returns `null` when the bound session has no in-flight leases
+ * (`running` or `preparing`); terminalized leases are ignored so
+ * the read does not resurrect a stale skill on a fresh session.
+ */
+function readSkillPresenceFromLease(projectRootOverride) {
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const sessionId = getSessionId(projectRoot);
+    if (sessionId === null)
+        return null;
+    const leases = listPresenceLeases(projectRoot, sessionId);
+    const inFlight = leases.filter((l) => l.status === 'running' || l.status === 'preparing');
+    if (inFlight.length === 0)
+        return null;
+    inFlight.sort((a, b) => b.lastHeartbeat.localeCompare(a.lastHeartbeat));
+    const lease = inFlight[0];
+    if (lease === undefined)
+        return null;
+    // The lease carries `callerId` (the adapter / harness session id),
+    // not the legacy `outerSessionId` field. Project it for back-compat
+    // with `clearStalePresenceOnRotation`'s outer-mismatch check.
+    return {
+        skill: lease.skill,
+        sessionId,
+        outerSessionId: lease.callerId,
+        setAt: lease.startedAt,
+        lastHeartbeat: lease.lastHeartbeat
+    };
+}
 /**
  * Look up the outer-session-id that was bound to the *current* peaks
  * session, i.e. the one written to the per-session
@@ -160,23 +174,14 @@ function getBoundOuterSessionId(projectRootOverride) {
  * legacy `.peaks/.active-skill.json` for one minor release.
  */
 function getPreviousOuterSessionId(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
+    const result = readSkillPresenceFromLease(projectRootOverride);
     if (result === null)
         return undefined;
-    const parsed = result.presence;
-    if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
-        return parsed.outerSessionId;
-    }
-    // Legacy field name. Honour it on the read side so v1.2.x
-    // presence files do not show as a false mismatch.
-    if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
-        return parsed.claudeSessionId;
+    if (typeof result.outerSessionId === 'string' && result.outerSessionId.length > 0) {
+        return result.outerSessionId;
     }
     return undefined;
 }
-export function exportSkillPresence(projectRootOverride) {
-    return resolvePresencePath(projectRootOverride);
-}
 // ============================================================================
 // Slice 020 — caller-keyed active-skill marker (D6).
 // ============================================================================
@@ -336,12 +341,12 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
             catch { /* fall through to legacy write */ }
         })();
     }
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const presenceDir = dirname(presencePath);
-    if (!existsSync(presenceDir)) {
-        mkdirSync(presenceDir, { recursive: true });
-    }
-    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Slice 4.0.11 statusline-sid-scoped-lease A: the canonical write
+    // path is now exclusively `presence-lease-service.setPresenceLease`.
+    // The legacy single-slot marker file write was removed in this
+    // slice: every `setSkillPresence` call flows through the sid-scoped
+    // lease + presence-index machinery above. The legacy
+    // `active-skill.json` file is NOT recreated here.
     // Skill-activation side effect: ensure `.peaks/memory/` and a full-shape
     // empty `index.json` exist for the project. This is the user-facing fix
     // for "stock projects never get a memory directory or index". Every peaks
@@ -354,26 +359,17 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     return presence;
 }
 export function getSkillPresence(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
-    if (result === null)
-        return null;
-    const { presence, path: presencePath } = result;
-    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
-        const currentSessionId = getCurrentSessionId(projectRootOverride);
-        if (currentSessionId && presence.sessionId !== currentSessionId) {
-            try {
-                unlinkSync(presencePath);
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // best effort
-            }
-            return null;
-        }
-    }
-    return presence;
+    // Slice 4.0.11 statusline-sid-scoped-lease C: read from the
+    // canonical sid-scoped lease projection. The legacy
+    // `unlinkSync(presencePath)` purge on session-mismatch is
+    // removed: the lease projection is keyed off the bound session
+    // id, so a mismatch cannot happen — `listPresenceLeases`
+    // already filters by the session-id resolved from the workspace
+    // binding.
+    return readSkillPresenceFromLease(projectRootOverride);
 }
 export function checkStalePresence(opts) {
-    const result = readSkillPresenceBackCompat(opts?.projectRootOverride);
+    const result = readSkillPresenceFromLease(opts?.projectRootOverride);
     // `opts?.currentOuter === undefined` is the omitted-key case. A
     // falsy string `''` is an explicit "no signal" (used by tests to
     // simulate a CLI run with no harness env vars).
@@ -389,7 +385,7 @@ export function checkStalePresence(opts) {
             recordedOuterSessionId: undefined
         };
     }
-    const recorded = result.presence.outerSessionId;
+    const recorded = result.outerSessionId;
     // Suppress false-positives when NEITHER side recorded an outer
     // session id (legacy project, no harness signal). Two unknowns
     // are not a swap — they are "no signal available yet".
@@ -399,7 +395,7 @@ export function checkStalePresence(opts) {
         return {
             stale: false,
             reason: null,
-            presence: result.presence,
+            presence: result,
             currentOuterSessionId: current,
             recordedOuterSessionId: recorded
         };
@@ -408,7 +404,7 @@ export function checkStalePresence(opts) {
         return {
             stale: false,
             reason: null,
-            presence: result.presence,
+            presence: result,
             currentOuterSessionId: current,
             recordedOuterSessionId: recorded
         };
@@ -416,7 +412,7 @@ export function checkStalePresence(opts) {
     return {
         stale: true,
         reason: 'outer-session-mismatch',
-        presence: result.presence,
+        presence: result,
         currentOuterSessionId: current,
         recordedOuterSessionId: recorded
     };
@@ -444,11 +440,11 @@ export function checkStalePresence(opts) {
  * decide what the "rotated-out" id was.
  */
 export function clearStalePresenceOnRotation(opts) {
-    const result = readSkillPresenceBackCompat(opts.projectRootOverride);
+    const result = readSkillPresenceFromLease(opts.projectRootOverride);
     if (result === null) {
         return { cleared: false, reason: 'no-presence' };
     }
-    const recorded = result.presence.outerSessionId;
+    const recorded = result.outerSessionId;
     const current = opts.currentOuterSessionId;
     // If the recorded outer id matches the new (current) outer id,
     // this presence is NOT stale — the user just reconnected from
@@ -483,24 +479,25 @@ export function clearStalePresenceOnRotation(opts) {
     };
 }
 export function touchSkillHeartbeat(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
-    if (result === null)
+    // Slice 4.0.11 statusline-sid-scoped-lease C: read from the
+    // canonical sid-scoped lease projection. The legacy
+    // unlink-on-session-mismatch purge is removed: the lease is
+    // keyed off the bound session id, so the mismatch path cannot
+    // fire (a lease under session A is never returned when the bound
+    // session is B).
+    const presence = readSkillPresenceFromLease(projectRootOverride);
+    if (presence === null)
         return null;
-    const { presence, path: presencePath } = result;
-    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
-        const currentSessionId = getCurrentSessionId(projectRootOverride);
-        if (currentSessionId && presence.sessionId !== currentSessionId) {
-            try {
-                unlinkSync(presencePath);
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // best effort
-            }
-            return null;
-        }
-    }
+    // Slice 4.0.11 statusline-sid-scoped-lease A: the legacy write to
+    // the single-slot marker file was removed. Heartbeat refresh now
+    // lives exclusively in `presence-lease-service.setPresenceLease`
+    // (the canonical sid-scoped lease). This function remains as a
+    // read-only back-compat shim for the 4-B / 4-C sub-slices; callers
+    // still receive the in-memory `presence` (with the new
+    // `lastHeartbeat` stamped) but the legacy `active-skill.json` file
+    // is no longer touched. The canonical lease / presence-index
+    // entries are the source of truth for heartbeat freshness.
     presence.lastHeartbeat = new Date().toISOString();
-    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
     return presence;
 }
 export function clearSkillPresence(projectRootOverride) {
@@ -518,12 +515,25 @@ export function clearSkillPresence(projectRootOverride) {
     // `.peaks/.active-skill.json` so a stale marker from a prior CLI
     // version cannot resurrect after a fresh `clear`. The canonical
     // lease + index entries are NOT touched by this shim — they
-    // remain under the workflow's terminalize lock until
-    // `terminalizeWorkflow` or the next workflow init reclaims them.
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    // Slice 4.0.11 statusline-sid-scoped-lease C: the deprecated
+    // single-slot presence files (`.peaks/_runtime/active-skill.json`
+    // and `.peaks/.active-skill.json`) are removed. The canonical
+    // sid-scoped lease projection (under
+    // `.peaks/_runtime/<sid>/leases/`) is untouched here — workflow
+    // leases route through `terminalizeWorkflow`, NOT this shim.
+    //
+    // This shim remains as a best-effort stale-file cleanup for
+    // projects that still carry the deprecated single-slot file from
+    // a pre-4.0.11 CLI version. After one minor release the legacy
+    // paths are gone and the loop is a no-op. Returns true when a
+    // stale file was actually removed.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const candidates = [
+        resolve(projectRoot, '.peaks', '_runtime', 'active-skill.json'),
+        resolve(projectRoot, '.peaks', '.active-skill.json')
+    ];
     let cleared = false;
-    for (const p of [presencePath, legacyPath]) {
+    for (const p of candidates) {
         if (!existsSync(p))
             continue;
         try {

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

@@ -1,28 +1,34 @@
-import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { decideCompactStatusline } from '../compact-statusline/compact-statusline-service.js';
 import { getSessionIdCanonical } from '../session/session-manager.js';
 import { resolveActiveSkillForCaller } from '../audit/enforcers/active-skill-resolver.js';
+import { listPresenceLeases } from './presence-lease-service.js';
 import { readActiveDispatchIndex } from '../dispatch/dispatch-record-writer.js';
 /**
  * Out-of-band Peaks skill status renderer for the Claude Code statusLine.
  *
  * Claude Code invokes the configured statusLine command on every turn and pipes
- * a JSON session payload on stdin. This renderer reads the durable presence file
- * (`.peaks/_runtime/active-skill.json`, with a one-minor-release back-compat
- * fallback to `.peaks/.active-skill.json`) and prints a single line that
- * Claude Code paints at the bottom of the terminal. Because it is rendered
- * by the harness — not emitted as LLM tokens — the signal cannot be forgotten
- * by the model, cannot be confused with normal output, and survives context
- * compaction.
+ * a JSON session payload on stdin. This renderer reads the canonical
+ * sid-scoped lease projection
+ * (`.peaks/_runtime/<sid>/leases/presence-<caller>-<workflow>.json` +
+ * the per-caller index under `presence-index/<caller>.json`) and prints a
+ * single line that Claude Code paints at the bottom of the terminal. Because
+ * it is rendered by the harness — not emitted as LLM tokens — the signal
+ * cannot be forgotten by the model, cannot be confused with normal output,
+ * and survives context compaction.
  *
  * This module is intentionally READ-ONLY. Unlike getSkillPresence in
  * skill-presence-service.ts, it never deletes or rewrites the presence file:
  * the statusLine runs on every turn and must have zero side effects.
+ *
+ * Slice 2026-08-05-statusline-sid-scoped-lease-B: the read no longer falls
+ * back to the project-level `.peaks/_runtime/active-skill.json` (or its
+ * legacy `.peaks/.active-skill.json`). The canonical lease projection is
+ * the only source. When `callerId === null` (non-IDE caller), the read
+ * picks the most recent in-flight lease across all callers; this is the
+ * documented back-compat path.
  */
-const PRESENCE_FILE = '.peaks/_runtime/active-skill.json';
-const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
 const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function resolveCwdFromStdin(stdin) {
     const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
@@ -113,16 +119,23 @@ function readActiveLeaf(projectRoot, sessionId) {
  * Read the presence file without any side effects. Returns null when the file is
  * absent (idle) and a sentinel object for malformed content (invalid-presence).
  *
- * When `callerId` is non-null, delegates to the canonical lease resolver
- * (presence-lease-service via active-skill-resolver) so the read is
- * session+caller-isolated. When `callerId` is null, falls back to the
- * project-level single-file read (back-compat for callers that don't pass
- * a callerId yet, e.g. legacy CLI invocations).
+ * Both branches now route through the canonical sid-scoped lease projection
+ * (slice 2026-08-05-statusline-sid-scoped-lease-B):
+ *   - `callerId !== null` → `resolveActiveSkillForCaller` with the canonical
+ *     (non-legacy) lease projection, filtered to this callerId.
+ *   - `callerId === null` → enumerate `listPresenceLeases` for the
+ *     canonical session and pick the most recent in-flight lease. Back-compat
+ *     for non-IDE callers (e.g. legacy CLI invocations) that have no callerId.
+ *
+ * No fallback to `.peaks/_runtime/active-skill.json` (or its legacy path):
+ * the canonical lease projection is the single source of truth. When no
+ * in-flight leases exist, the read returns `{ presence: null, invalid: false }`
+ * and the renderer falls back to the idle state.
  */
 function readPresenceReadOnly(projectRoot, callerId) {
     if (callerId !== null) {
         try {
-            const resolution = resolveActiveSkillForCaller(projectRoot, { legacyPresence: true, callerId });
+            const resolution = resolveActiveSkillForCaller(projectRoot, { callerId });
             if (resolution.source === 'none' || resolution.skill === null) {
                 return { presence: null, invalid: false };
             }
@@ -138,36 +151,55 @@ function readPresenceReadOnly(projectRoot, callerId) {
             return { presence: null, invalid: true };
         }
     }
-    const presencePath = resolve(projectRoot, PRESENCE_FILE);
-    // Back-compat: prefer the new canonical path; fall back to the legacy
-    // `.peaks/.active-skill.json` for one minor release.
-    const pathToRead = existsSync(presencePath) ? presencePath : resolve(projectRoot, PRESENCE_FILE_LEGACY);
-    if (!existsSync(pathToRead)) {
+    // callerId === null branch: enumerate the canonical session dir's leases
+    // and pick the most recent in-flight lease. This is the back-compat path
+    // for non-IDE callers that don't supply a callerId.
+    let sessionId = null;
+    try {
+        sessionId = getSessionIdCanonical(projectRoot);
+    }
+    catch {
+        return { presence: null, invalid: false };
+    }
+    if (sessionId === null) {
         return { presence: null, invalid: false };
     }
+    let leases = [];
     try {
-        const parsed = JSON.parse(readFileSync(pathToRead, 'utf8'));
-        if (!parsed || typeof parsed !== 'object') {
-            return { presence: null, invalid: true };
-        }
-        const candidate = parsed;
-        if (typeof candidate.skill !== 'string' || candidate.skill.length === 0) {
-            return { presence: null, invalid: true };
-        }
-        return {
-            presence: {
-                skill: candidate.skill,
-                ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
-                ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
-                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {}),
-                ...(typeof candidate.claudeSessionId === 'string' ? { claudeSessionId: candidate.claudeSessionId } : {})
-            },
-            invalid: false
-        };
+        leases = listPresenceLeases(projectRoot, sessionId);
     }
     catch {
         return { presence: null, invalid: true };
     }
+    const inFlight = leases
+        .filter((l) => l.status === 'preparing' || l.status === 'running')
+        .filter((l) => typeof l.skill === 'string' && l.skill.length > 0);
+    if (inFlight.length === 0) {
+        return { presence: null, invalid: false };
+    }
+    // Most recent wins — sort by `lastHeartbeat` desc, fall back to `startedAt`.
+    const sorted = inFlight.slice().sort((a, b) => {
+        const hb = b.lastHeartbeat.localeCompare(a.lastHeartbeat);
+        if (hb !== 0)
+            return hb;
+        return b.startedAt.localeCompare(a.startedAt);
+    });
+    const latest = sorted[0];
+    if (latest === undefined || typeof latest.skill !== 'string' || latest.skill.length === 0) {
+        return { presence: null, invalid: false };
+    }
+    // Leases on disk may carry an optional `mode` field (the lease constructor
+    // spreads `input.mode` when present); the typed `SkillPresenceLease` does
+    // not declare it, so widen the read shape here.
+    const latestMode = latest.mode;
+    return {
+        presence: {
+            skill: latest.skill,
+            ...(typeof latestMode === 'string' && latestMode.length > 0 ? { mode: latestMode } : {}),
+            setAt: latest.startedAt,
+        },
+        invalid: false,
+    };
 }
 export function buildStatusLineModel(stdin, nowMs) {
     const cwd = resolveCwdFromStdin(stdin);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.11",
+  "version": "4.0.12",
   "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-channel": "0.0.19",
-    "peaks-loop-mut": "0.1.15",
-    "peaks-loop-shared": "0.0.42"
+    "peaks-loop-mut": "0.1.16",
+    "peaks-loop-shared-channel": "0.0.20",
+    "peaks-loop-shared": "0.0.43"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"

package/skills/peaks-code/SKILL.md

@@ -102,6 +102,10 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 
 **Step 0.7 resume rule (read-FIRST):** on resume, `peaks code gate-step-08` reads `progress.json` first and surfaces `Next: slice #N of M (<currentSlice>)` so the orchestrator picks up at the right slice without re-reading the artifact tree.
 
+### Peaks-Loop Step 0.51 — `orchestrator-can-do` probe (slice 2026-08-05, lesson-encoded CLI)
+
+> **Before deciding to push a slice to the next session**, run `peaks code orchestrator-can-do --slice-spec '<text>' --json`. The command evaluates 4 boundary questions (source code? sub-agent available? requires user decision? context sustainable?) and returns whether the slice can be done in the current session. Default to `canDoInSession=true` unless hard blockers are present; sub-agent dispatch (`peaks sub-agent dispatch rd`) is the canonical delegation path for source-code changes. This encodes the 2026-08-05 lesson — orchestrator MUST NOT Edit/Write `src/` directly, but MUST delegate via sub-agent dispatch. See `.peaks/memory/2026-08-05-peaks-code-orchestrator-capability-misjudgment.md`.
+
 ### Peaks-Loop Step N+2: Auto-compact at the warning line (v2.13.0 zero-pause contract)
 
 > **Zero-pause contract.** When context usage crosses the pre-compact threshold, peaks-loop **automatically fires `peaks compact auto --execute` — the LLM does NOT prompt the user to run `/compact` manually**. Stale prose that says "ask the user to compact" silently stalls the workflow. The v2.13.0 contract makes auto-compact a system responsibility, not a user action.
@@ -127,6 +131,8 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 
 If the prose audit (`peaks audit red-lines`) flags any of the above, the slice is **blocked** until the prose is rewritten.
 
+See also: references/session-overload-signal-index.md for the 7-signal lookup table the LLM consults before deciding to open a new session.
+
 ## CLI Drift Index (sediment 2026-07-09)
 
 > **Reading guide:** Verified against peaks-loop 4.0.0-beta.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing.

package/skills/peaks-code/references/session-overload-signal-index.md

@@ -0,0 +1,60 @@
+# Session Overload Signal Index
+
+> Single-source lookup for the LLM-side "should I open a new session?" decision.
+> Slice 2026-08-05-session-overload-signal-index.
+
+## What this doc is
+
+When the LLM senses context pressure, it must consult these 7 signals before
+deciding to (a) auto-compact, (b) refuse the next slice, or (c) ask the user to
+open a new session. The contract is: **LLM never re-asks the user about
+cost/length/context** (red line #2 of `references/job-loop.md`). This index is
+the lookup table the LLM must consult in lieu of intuition.
+
+## The 7 signals
+
+| # | Signal source | Threshold | File / CLI | LLM action |
+|---|---|---|---|---|
+| 1 | prompt size (main session) | 50% / 75% / 80% / 90% | `src/services/context/threshold.ts`; probe via `peaks code context-now` | soft-warn at 50%; consider compact at 75%; MUST NOT auto-compact mid-batch (D6.e); Job mode ≥ 0.85 ⇒ MANDATORY `peaks compact auto --execute` |
+| 2 | auto-compact zone | 0.85 pre-compact / 0.95 red-line | `src/services/code/auto-compact-orchestrator.ts`; `--enforce-job-mode` flag | Auto-fires `peaks compact auto --execute`; LLM MUST NOT prompt user to compact (zero-pause contract v2.13.0) |
+| 3 | sub-agent dispatch prompt size | 50% / 75% / 80% | `src/services/context/context-guard.ts`; `peaks sub-agent-dispatch-guard` PreToolUse hook | soft-warn at 50%; CONTEXT_NEAR_LIMIT at 75%; hard-reject at 80% (CLI + hook double-guard) |
+| 4 | statusline compact bar | visual | `src/services/compact-statusline/compact-statusline-service.ts` | ambient UI; surfaces queued/preparing/compacting/verifying/completed/failed/stalled |
+| 5 | in-flight batch deferral | D6.e | `src/services/code/auto-compact-modes.ts` | defer compact until batch lands (NOT "new session") |
+| 6 | compact stalled | 120s heartbeat timeout | `compact-lifecycle-store.ts` | ambient "stalled" detail in statusline |
+| 7 | sub-agent heartbeat missing | per-role TTL | `peaks sub-agent heartbeat`; `peaks heartbeat-watch` | orchestrator-side warning, not LLM-driven "new session" |
+
+## Hard rules
+
+- peaks-code SKILL.md red line #2 (see `references/job-loop.md`):
+  **Re-ask the user about cost / length / context is forbidden**.
+  The LLM MUST NOT prompt the user to open a new session based on overload
+  intuition alone; it MUST consult the 7 signals above and prefer auto-compact /
+  sub-agent dispatch guard / heartbeat-watch first.
+- "Open a new session" is a **last resort** after auto-compact has been
+  attempted and the slice cannot fit. The user's role is to receive the
+  handoff capsule, not to micro-manage session lifecycle.
+
+## Decision flowchart
+
+```
+LLM senses context pressure
+  ├─► Probe `peaks code context-now --json`
+  │   ├─ ratio < 0.50  → continue (no action)
+  │   ├─ 0.50 ≤ ratio < 0.75 → soft-warn; continue
+  │   ├─ 0.75 ≤ ratio < 0.85 → compact-zone candidate
+  │   │     ├─ Job mode → MUST auto-compact now
+  │   │     └─ non-Job  → wait for next idle turn, then compact
+  │   ├─ 0.85 ≤ ratio < 0.95 → pre-compact zone; auto-compact MUST fire
+  │   └─ ratio ≥ 0.95       → red-line; synchronous gate (Karpathy §4)
+  ├─► Check statusline compact bar (signal #4)
+  │   ├─ queued / preparing / compacting / verifying → wait
+  │   ├─ failed → read failure reason, do NOT spawn new session
+  │   └─ stalled (>120s) → surface to user as a blocker, not a new-session ask
+  └─► Check sub-agent dispatch guard (signal #3)
+      ├─ 75% CONTEXT_NEAR_LIMIT → warn, continue with smaller prompt
+      └─ 80% PROMPT_TOO_LARGE → hard-reject; refactor the prompt
+
+Only after ALL three checks above have been attempted without resolution:
+emit the `peaks session split-handoff` capsule (NOT in this slice; follow-up)
+and the user opens a new session in their own time.
+```