peaks-cli 1.2.9 → 1.3.1

package/dist/src/services/sc/sc-service.js

@@ -1,6 +1,6 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
-import { basename, relative, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { isInsidePath } from '../../shared/path-utils.js';
 import { getWorkspaceConfigForPath } from '../config/config-service.js';
 import { getArtifactRemoteRepo, getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
@@ -21,6 +21,27 @@ const RETENTION_REQUIREMENTS = [
     ['sc', 'retention-boundary.md'],
     ['txt', 'context-capsule.md']
 ];
+/**
+ * "Modern" retention requirements for the current peaks-cli artifact
+ * naming convention. The legacy `RETENTION_REQUIREMENTS` above assume
+ * older `refactor-goal.md` / `slice-spec.md` / `coverage-report.md` /
+ * `validation-report.md` / `change-impact.json` / `retention-boundary.md`
+ * / `context-capsule.md` filenames that predate the W4 session resolver.
+ *
+ * When the resolver finds a session that owns the slice, validate
+ * against the modern set: the actual files the current workflow emits
+ * (per-slice `prd/requests/<rid>.md`, per-slice `rd/requests/<rid>.md`,
+ * per-session `rd/tech-doc.md`, per-slice `qa/test-cases/<rid>.md`,
+ * per-slice `qa/test-reports/<rid>.md`, per-session `txt/handoff.md`).
+ * The legacy set is preserved for the workspace-artifact path so
+ * existing repos on the old convention keep working.
+ */
+const MODERN_RETENTION_REQUIREMENTS = [
+    'rd/tech-doc.md',
+    'qa/test-cases/{sliceId}.md',
+    'qa/test-reports/{sliceId}.md',
+    'txt/handoff.md'
+];
 const SLICE_ID_PATTERN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
 function getPeaksPath(workspaceRoot) {
     return resolve(workspaceRoot, '.peaks');
@@ -108,6 +129,208 @@ function isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, ch
         return false;
     }
 }
+/**
+ * Read the orchestrator's active-skill marker and return its
+ * `sessionId`, or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/active-skill.json`. The legacy
+ * `<projectRoot>/.peaks/.active-skill.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readActiveSkillSessionId(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'active-skill.json');
+    const legacyPath = join(projectRoot, '.peaks', '.active-skill.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Read the workspace session binding and return its `sessionId`,
+ * or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/session.json`. The legacy
+ * `<projectRoot>/.peaks/.session.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readSessionJsonBinding(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'session.json');
+    const legacyPath = join(projectRoot, '.peaks', '.session.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * The "marker" artifact whose existence under a session dir is the signal
+ * that the session owns the slice. We look for `qa/test-cases/<sliceId>.md`
+ * first (a present test plan is the most decisive signal of session
+ * ownership for a slice id). If the test plan is absent we also accept
+ * `qa/test-reports/<sliceId>.md` (a finished QA report is also a decisive
+ * ownership signal). When neither exists for a candidate session, that
+ * session does not own the slice.
+ */
+function sessionOwnsSlice(projectRoot, sessionId, sliceId) {
+    // As of slice 2026-06-05-change-id-as-unit-of-work, the same
+    // session id can live at multiple umbrella locations:
+    //   - `.peaks/<sessionId>/` (legacy or top-level active)
+    //   - `.peaks/retrospective/<sessionId>/` (shipped slice)
+    //   - `.peaks/_dogfood/<sessionId>/` (dogfood evidence)
+    // Try each in turn; the first match wins.
+    const candidateDirs = [
+        join(projectRoot, '.peaks', sessionId),
+        join(projectRoot, '.peaks', 'retrospective', sessionId),
+        join(projectRoot, '.peaks', '_dogfood', sessionId)
+    ];
+    for (const sessionDir of candidateDirs) {
+        if (!existsSync(sessionDir))
+            continue;
+        for (const marker of [`qa/test-cases/${sliceId}.md`, `qa/test-reports/${sliceId}.md`]) {
+            if (existsSync(join(sessionDir, marker)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Find a session dir under `<projectRoot>/.peaks/` that owns the slice
+ * (see `sessionOwnsSlice`). Returns the first match in lexicographic
+ * order, or null when no session owns the slice.
+ */
+function findSessionOwningSlice(projectRoot, sliceId) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return null;
+    let topLevel;
+    try {
+        topLevel = readdirSync(peaksRoot);
+    }
+    catch {
+        return null;
+    }
+    topLevel.sort();
+    // As of slice 2026-06-05-change-id-as-unit-of-work, shipped slices
+    // are archived under `.peaks/retrospective/<dir>/` and dogfood
+    // evidence lives under `.peaks/_dogfood/<dir>/`. Both umbrellas host
+    // scopes at one level deeper than the top-level `.peaks/<dir>/`
+    // shape. Expand the candidate list so the find-fallback tier can
+    // locate these. Accept both legacy session-id format
+    // (`YYYY-MM-DD-session-<6hex>`) and new change-id format
+    // (`YYYY-MM-DD-<slug>`) as valid scope dir names.
+    const candidateSessionIds = [];
+    for (const entry of topLevel) {
+        if (entry === 'retrospective' || entry === '_dogfood') {
+            const nested = readdirSyncSafe(join(peaksRoot, entry));
+            for (const n of nested) {
+                candidateSessionIds.push(n);
+            }
+        }
+        else {
+            candidateSessionIds.push(entry);
+        }
+    }
+    candidateSessionIds.sort();
+    for (const id of candidateSessionIds) {
+        // Legacy session-id format OR new change-id format. Reject files
+        // and other non-scope entries (e.g. .peaks-init-hooks-decision.json,
+        // PROJECT.md, _runtime, memory, sops, issues, perf-baseline, etc.)
+        if (!isScopeDirName(id))
+            continue;
+        if (sessionOwnsSlice(projectRoot, id, sliceId)) {
+            return id;
+        }
+    }
+    return null;
+}
+/** Is this a valid legacy session-id OR new change-id dir name? */
+function isScopeDirName(name) {
+    // Legacy: 2026-MM-DD-session-<6hex>
+    if (/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+        return true;
+    // New: 2026-MM-DD-<slug> where slug is letters / digits / hyphens / dots
+    // (the slice-migration kept the 4-digit year prefix, so 3-digit
+    // numbered filenames from request artifacts stay out of this path —
+    // they live in retrospective/ nested with the year-prefixed change-id
+    // as the dir, not at top level).
+    if (/^\d{4}-\d{2}-\d{2}-[\w.\-]+$/.test(name))
+        return true;
+    return false;
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve the session id that owns the slice's artifacts using a 3-tier
+ * precedence:
+ *
+ *   1. `.peaks/_runtime/active-skill.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.active-skill.json`) if it points to a real
+ *      session that owns the slice.
+ *   2. `.peaks/_runtime/session.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.session.json`) if it points to a real
+ *      session that owns the slice.
+ *   3. `find .peaks/ -name '<marker>'` — the first session dir under
+ *      `.peaks/` that owns the slice.
+ *   4. else `{ resolvedSessionId: null, candidateSources: [] }`.
+ *
+ * The back-compat fallbacks are tolerated for one minor release so
+ * users with pre-migration trees (or running an older CLI version)
+ * still get a clean resolution. After the migration (or after v1.3.0
+ * is installed and `peaks workspace reconcile` has been run), only
+ * the new paths exist and the fallbacks never fire.
+ *
+ * `candidateSources` reports which sources were checked before the
+ * resolver found (or did not find) a winner; the list is in the order
+ * the resolver consulted them. This makes the precedence observable in
+ * the JSON envelope so a human reviewer can see "active-skill was empty
+ * AND session-json was empty, so find-fallback won".
+ */
+export function resolveArtifactSession(projectRoot, sliceId) {
+    const activeSkill = readActiveSkillSessionId(projectRoot);
+    if (activeSkill !== null && sessionOwnsSlice(projectRoot, activeSkill, sliceId)) {
+        return { resolvedSessionId: activeSkill, candidateSources: ['active-skill'] };
+    }
+    const sessionJson = readSessionJsonBinding(projectRoot);
+    if (sessionJson !== null && sessionOwnsSlice(projectRoot, sessionJson, sliceId)) {
+        return { resolvedSessionId: sessionJson, candidateSources: ['active-skill', 'session-json'] };
+    }
+    const findHit = findSessionOwningSlice(projectRoot, sliceId);
+    if (findHit !== null) {
+        return { resolvedSessionId: findHit, candidateSources: ['active-skill', 'session-json', 'find-fallback'] };
+    }
+    return { resolvedSessionId: null, candidateSources: [] };
+}
 export function getChangeTraceabilityStatus() {
     const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
@@ -196,6 +419,8 @@ export function recordCommitBoundary(options) {
     const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
     const commitHash = getCurrentCommitHash(workspace?.rootPath);
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    const resolution = resolveArtifactSession(projectRoot, options.sliceId);
     return {
         sliceId: options.sliceId,
         commitHash,
@@ -203,38 +428,120 @@ export function recordCommitBoundary(options) {
         artifacts: options.artifacts ?? [],
         codeFiles: options.codeFiles ?? [],
         syncState: mapSyncState(artifactStatus.syncStatus),
-        rollbackPoint: commitHash
+        rollbackPoint: commitHash,
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
     };
 }
 export function validateArtifactRetention(sliceId) {
     const workspace = getWorkspaceConfigForPath(process.cwd());
-    if (!workspace) {
+    // Resolve from `process.cwd()` even when no workspace is configured, so
+    // the W4 session resolver can still find the slice's owning session.
+    // The legacy "no workspace" check still surfaces as a missing artifact,
+    // but the resolution happens first so the JSON envelope's additive
+    // `resolvedSessionId` is populated regardless of workspace state.
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    if (!SLICE_ID_PATTERN.test(sliceId)) {
         return {
             valid: false,
-            missingArtifacts: ['No workspace configured'],
-            warnings: ['Cannot validate without a configured workspace']
+            missingArtifacts: ['Invalid slice id'],
+            warnings: ['Slice id must stay inside .peaks/<session-id> and only contain letters, numbers, dots, underscores, or hyphens'],
+            resolvedSessionId: null,
+            candidateSources: []
         };
     }
-    if (!SLICE_ID_PATTERN.test(sliceId)) {
+    const resolution = resolveArtifactSession(projectRoot, sliceId);
+    const effectiveSliceId = resolution.resolvedSessionId ?? sliceId;
+    // W4: if the resolver found a session, ALSO accept artifacts under
+    // `<projectRoot>/.peaks/<resolvedSessionId>/` (the canonical per-slice
+    // dir). The project-root peaks is where the orchestrator's skills
+    // actually write (see `initWorkspace` in `workspace-service.ts`), so
+    // when the resolution chain lands on a real session the artifacts are
+    // usually there. We accept either location — workspace artifact path
+    // OR project-root peaks — so the additive behavior does not regress
+    // existing workspaces.
+    const resolvedPeaksSessionDir = resolution.resolvedSessionId !== null
+        ? join(projectRoot, '.peaks', resolution.resolvedSessionId)
+        : null;
+    // Collect present files: legacy workspace-artifact-path check, OR the
+    // resolved session's project-root peaks dir.
+    const legacyPresent = (folder, file) => {
+        if (!workspace)
+            return false;
+        const artifactWorkspacePath = getLocalArtifactPath(workspace);
+        const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, effectiveSliceId);
+        const filePath = resolve(changeDir, folder, file);
+        return isRetainedArtifactFile(filePath, artifactWorkspacePath, peaksPath, changeDir);
+    };
+    const resolvedPresent = (folder, file) => {
+        if (resolvedPeaksSessionDir === null)
+            return false;
+        return existsSync(join(resolvedPeaksSessionDir, folder, file));
+    };
+    if (!workspace) {
+        // No workspace: validate against the resolved session dir directly
+        // (this is the common peaks-solo / peaks-rd invocation: the slice
+        // lives under the project-root `.peaks/<sessionId>/`, and the
+        // workspace artifact path is irrelevant). When the resolution also
+        // fails, fall back to the legacy "No workspace configured" failure
+        // mode so the existing CLI contract is preserved.
+        if (resolvedPeaksSessionDir === null) {
+            return {
+                valid: false,
+                missingArtifacts: ['No workspace configured'],
+                warnings: ['Cannot validate without a configured workspace'],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+        const missingArtifacts = modernRequirementRelativePaths(sliceId).filter((rel) => !existsSync(join(resolvedPeaksSessionDir, rel)));
         return {
-            valid: false,
-            missingArtifacts: ['Invalid slice id'],
-            warnings: ['Slice id must stay inside .peaks/<session-id> and only contain letters, numbers, dots, underscores, or hyphens']
+            valid: missingArtifacts.length === 0,
+            missingArtifacts,
+            warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+            resolvedSessionId: resolution.resolvedSessionId,
+            candidateSources: resolution.candidateSources
         };
     }
-    const artifactWorkspacePath = getLocalArtifactPath(workspace);
-    const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, sliceId);
-    const changesRoot = peaksPath;
     const missingArtifacts = RETENTION_REQUIREMENTS
-        .map(([folder, file]) => resolve(changeDir, folder, file))
-        .filter((filePath) => !isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, changeDir))
-        .map((filePath) => relative(changeDir, filePath).replace(/\\/g, '/'));
+        .map(([folder, file]) => `${folder}/${file}`)
+        .filter((rel) => !legacyPresent(...rel.split('/')) && !resolvedPresent(...rel.split('/')));
+    // If the legacy check is short (i.e. we're missing a lot of legacy-named
+    // files) but the resolver landed on a real session, ALSO accept the
+    // modern set. The legacy set was designed for an older workflow naming
+    // and a freshly-minted session in the current peaks-cli flow will not
+    // have the legacy names. This keeps `peaks sc validate --slice-id <rid>`
+    // returning `valid: true` for slices that completed under the current
+    // peaks-cli convention.
+    if (missingArtifacts.length > 0 && resolvedPeaksSessionDir !== null) {
+        const modernMissing = modernRequirementRelativePaths(sliceId).filter((rel) => !resolvedPresent(...rel.split('/')));
+        if (modernMissing.length === 0) {
+            return {
+                valid: true,
+                missingArtifacts: [],
+                warnings: [],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+    }
     return {
         valid: missingArtifacts.length === 0,
         missingArtifacts,
-        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing']
+        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
     };
 }
+/**
+ * Render the modern retention requirements as relative paths keyed
+ * against the slice id. The `{sliceId}` placeholder in the template
+ * is replaced with the actual slice id; per-session files (no
+ * placeholder) keep their literal name.
+ */
+function modernRequirementRelativePaths(sliceId) {
+    return MODERN_RETENTION_REQUIREMENTS.map((template) => template.replace('{sliceId}', sliceId));
+}
 export function getScHelpText() {
     return [
         'peaks sc status                          Show change traceability status',

package/dist/src/services/scan/acceptance-coverage-service.js

@@ -104,8 +104,12 @@ export async function getAcceptanceCoverage(options) {
     if (prdArtifact === null) {
         return { kind: 'prd-not-found' };
     }
-    const sessionId = prdArtifact.sessionId;
-    const testCasesPath = join(options.projectRoot, '.peaks', sessionId, 'qa', 'test-cases', `${options.requestId}.md`);
+    // As of slice 2026-06-05-change-id-as-unit-of-work, test-cases live
+    // under the same change-id dir as the PRD itself (the on-disk scope),
+    // not under the body's `- session:` line. The `prdArtifact.changeId`
+    // is the dir the PRD was found in.
+    const changeId = prdArtifact.changeId;
+    const testCasesPath = join(options.projectRoot, '.peaks', changeId, 'qa', 'test-cases', `${options.requestId}.md`);
     if (!(await pathExists(testCasesPath))) {
         return { kind: 'test-cases-not-found', expectedPath: testCasesPath };
     }

package/dist/src/services/session/session-manager.d.ts

@@ -33,11 +33,13 @@ export type SessionMeta = {
     outerSessionId?: string;
 };
 /**
- * Drop the project-level session binding (`.peaks/.session.json`)
- * so the next `ensureSession()` call auto-generates a fresh
- * session id. The on-disk session directory is left intact —
- * rotating does NOT delete the user's data, it just unbinds the
- * project from that session.
+ * Drop the project-level session binding at the canonical
+ * `.peaks/_runtime/session.json` so the next `ensureSession()` call
+ * auto-generates a fresh session id. The on-disk session directory
+ * is left intact — rotating does NOT delete the user's data, it
+ * just unbinds the project from that session. Also drops the legacy
+ * `.peaks/.session.json` if present so a stale read from another
+ * tool cannot re-bind the project after rotation.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something

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

@@ -6,11 +6,21 @@
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { mkdir as mkdirAsync } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
-const SESSION_FILE = '.session.json';
+// 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
+// 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 SESSION_FILE = join('_runtime', 'session.json');
+const LEGACY_SESSION_FILE = '.session.json';
 const META_FILE = 'session.json';
+function getLegacySessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', LEGACY_SESSION_FILE);
+}
 /**
  * Canonicalize a project root path. Returns the realpath
  * (resolving all symlinks — important on macOS where `/var`
@@ -68,7 +78,9 @@ function generateSessionId() {
     return `${date}-session-${random}`;
 }
 /**
- * Get the path to the session file for a project.
+ * Get the path to the session file for a project. The canonical home is
+ * `.peaks/_runtime/session.json`; the legacy `.peaks/.session.json` is
+ * read-only fallback (see `readSessionFile`).
  */
 function getSessionFilePath(projectRoot) {
     return join(projectRoot, '.peaks', SESSION_FILE);
@@ -92,10 +104,15 @@ function getSessionFilePath(projectRoot) {
  */
 function readSessionFile(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
-    if (!existsSync(sessionFile))
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` so older CLI versions or pre-migration
+    // trees keep working. When both exist, the new path wins.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
         if (data.sessionId && data.projectRoot === projectRoot) {
             return data;
         }
@@ -116,10 +133,14 @@ function readSessionFile(projectRoot) {
  */
 function readSessionFileCanonical(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
-    if (!existsSync(sessionFile))
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` for one minor release.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
         const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
         if (data.sessionId &&
             storedRaw !== null &&
@@ -133,22 +154,27 @@ function readSessionFileCanonical(projectRoot) {
     }
 }
 /**
- * Write session info to disk.
+ * Write session info to disk at the canonical new path
+ * `.peaks/_runtime/session.json`. The `.peaks/_runtime/` directory is
+ * created on demand. The legacy `.peaks/.session.json` is NOT written by
+ * this slice; it is only read for back-compat.
  */
 function writeSessionFile(projectRoot, info) {
     const sessionFile = getSessionFilePath(projectRoot);
-    const dir = join(projectRoot, '.peaks');
+    const dir = dirname(sessionFile);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
 /**
- * Drop the project-level session binding (`.peaks/.session.json`)
- * so the next `ensureSession()` call auto-generates a fresh
- * session id. The on-disk session directory is left intact —
- * rotating does NOT delete the user's data, it just unbinds the
- * project from that session.
+ * Drop the project-level session binding at the canonical
+ * `.peaks/_runtime/session.json` so the next `ensureSession()` call
+ * auto-generates a fresh session id. The on-disk session directory
+ * is left intact — rotating does NOT delete the user's data, it
+ * just unbinds the project from that session. Also drops the legacy
+ * `.peaks/.session.json` if present so a stale read from another
+ * tool cannot re-bind the project after rotation.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something
@@ -164,6 +190,15 @@ export function rotateSessionBinding(projectRoot) {
     if (existsSync(sessionFile)) {
         unlinkSync(sessionFile);
     }
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    if (existsSync(legacyFile)) {
+        try {
+            unlinkSync(legacyFile);
+        }
+        catch {
+            // best-effort: a stale legacy binding is not blocking
+        }
+    }
     return previous.sessionId;
 }
 /**
@@ -387,7 +422,15 @@ export function listSessions(projectRoot) {
  */
 export async function getProjectScanPath(projectRoot) {
     const sessionId = await ensureSession(projectRoot);
-    return join(projectRoot, '.peaks', sessionId, 'rd', 'project-scan.md');
+    // As of slice 2026-06-05-change-id-as-unit-of-work the session dir
+    // is at the canonical runtime location (gitignored). The scan is a
+    // session-local artifact; it lives alongside the rest of the
+    // ephemeral state under `_runtime/`. The parent `rd/` subdir is
+    // created on demand so the first scanner call has a place to land
+    // (consistent with the legacy behavior pre-1.3.1).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'rd', 'project-scan.md');
+    await mkdirAsync(dirname(scanPath), { recursive: true });
+    return scanPath;
 }
 /**
  * Check if project-scan.md exists for the current session.
@@ -399,6 +442,7 @@ export function hasProjectScan(projectRoot) {
     const info = readSessionFile(projectRoot);
     if (!info)
         return false;
-    const scanPath = join(projectRoot, '.peaks', info.sessionId, 'rd', 'project-scan.md');
+    // Canonical runtime location of the session dir (slice 2026-06-05).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', info.sessionId, 'rd', 'project-scan.md');
     return existsSync(scanPath);
 }

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

@@ -14,16 +14,31 @@
  * removes only our own entry.
  */
 export type HookScope = 'project' | 'global';
-/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+/** The hook command written into settings for the gate-enforce PreToolUse hook. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
-/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
-export declare const HOOK_SENTINEL = "peaks gate enforce";
+/**
+ * Hook command for the sub-agent progress auto-spawn. Fires on every Task
+ * tool call (the harness-enforced mechanism for "sub-agent dispatch"). The
+ * command itself is non-blocking: `peaks progress start` is idempotent
+ * (5-minute TTL on the spawn record) so the LLM does not see a fresh
+ * terminal per Task. The `--quiet` flag keeps the LLM context clean — the
+ * hook output otherwise adds ~500 tokens per Task call.
+ */
+export declare const HOOK_PROGRESS_COMMAND = "peaks progress start --project \"${CLAUDE_PROJECT_DIR}\" --reason \"auto-spawn for sub-agent Task\" --quiet";
+/** Substring that identifies a Peaks-managed PreToolUse gate-enforce hook entry. */
+export declare const HOOK_ENFORCE_SENTINEL = "peaks gate enforce";
+/** Substring that identifies a Peaks-managed PreToolUse sub-agent-progress hook entry. */
+export declare const HOOK_PROGRESS_SENTINEL = "peaks progress start";
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
     exists: boolean;
     alreadyInstalled: boolean;
     desiredCommand: string;
+    /** Substring sentinel used to detect the entry. */
+    sentinel: string;
+    /** Tool name (Bash | Task) the PreToolUse hook is keyed on. */
+    matcher: string;
 };
 export type HookInstallResult = HookInstallPlan & {
     applied: boolean;
@@ -39,6 +54,13 @@ export type HookStatus = {
     exists: boolean;
     installed: boolean;
 };
+/** A typed descriptor for a single peaks-managed hook entry. */
+export type PeaksHookEntry = {
+    sentinel: string;
+    matcher: string;
+    command: string;
+};
+export declare const PEAKS_HOOK_ENTRIES: ReadonlyArray<PeaksHookEntry>;
 export declare function planHookInstall(scope: HookScope, projectRoot?: string): HookInstallPlan;
 export declare function applyHookInstall(scope: HookScope, projectRoot?: string): HookInstallResult;
 export declare function removeHookInstall(scope: HookScope, projectRoot?: string): HookRemoveResult;