peaks-cli 1.3.0 → 1.3.2

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

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { readText } from '../../shared/fs.js';
@@ -48,7 +48,211 @@ function defaultWorkspaceInitializedProbe() {
     const projectRoot = findProjectRoot(process.cwd());
     if (projectRoot === null)
         return false;
-    return existsSync(join(projectRoot, '.peaks', '.session.json'));
+    // Workspace is "initialized" when EITHER the canonical runtime-layer session
+    // binding (`.peaks/_runtime/session.json`, the home since slice
+    // 2026-06-05-peaks-runtime-layer) OR the legacy top-level binding
+    // (`.peaks/.session.json`, kept as read-only back-compat for one minor
+    // release) is present. The legacy check is what catches projects that ran
+    // `peaks workspace init` before the runtime-layer migration and have not yet
+    // been reconciled; both paths must continue to satisfy the doctor until the
+    // legacy location is removed.
+    return isWorkspaceInitializedAt(projectRoot);
+}
+/**
+ * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
+ * drive the filesystem check without monkey-patching `process.cwd()` or
+ * `findProjectRoot`. Returns `true` when EITHER the canonical
+ * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
+ */
+export function isWorkspaceInitializedAt(projectRoot) {
+    return (existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json')) ||
+        existsSync(join(projectRoot, '.peaks', '.session.json')));
+}
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against the
+ * source-of-truth `package.json#version`. Default readers fail-soft to `null`
+ * on missing/unreadable/malformed input. Exported so tests can drive the
+ * filesystem reads without monkey-patching `process.cwd()`.
+ */
+export function compareDistVersion(opts) {
+    const distReader = opts.distVersionReader ?? defaultDistVersionReader;
+    const sourceReader = opts.sourceVersionReader ?? defaultSourceVersionReader;
+    const dist = safeRead(() => distReader(opts.projectRoot));
+    const source = safeRead(() => sourceReader(opts.projectRoot)) ?? 'unknown';
+    const distReadable = dist !== null;
+    return {
+        dist,
+        source,
+        match: distReadable && dist === source,
+        distReadable
+    };
+}
+function safeRead(reader) {
+    try {
+        return reader();
+    }
+    catch {
+        return null;
+    }
+}
+function defaultDistVersionReader(projectRoot) {
+    // Synchronous read is fine: the dist version.js is small and on the
+    // local build pipeline's hot path. readFileSync + regex is cheaper
+    // than pulling in fs/promises for a single short file.
+    const distPath = join(projectRoot, 'dist', 'src', 'shared', 'version.js');
+    if (!existsSync(distPath)) {
+        return null;
+    }
+    const body = readFileSync(distPath, 'utf8');
+    const match = /export\s+const\s+CLI_VERSION\s*=\s*["']([^"']+)["']/.exec(body);
+    return match?.[1] ?? null;
+}
+function defaultSourceVersionReader(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return null;
+    }
+    const body = readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(body);
+    return typeof parsed.version === 'string' ? parsed.version : null;
+}
+function defaultDistVersionProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { dist: null, source: 'unknown', match: false, distReadable: false };
+    }
+    return compareDistVersion({ projectRoot });
+}
+/**
+ * Pure helper that inspects the on-disk workspace layout for
+ * post-F3-canonical violations. The post-F3 canonical layout puts
+ * session dirs under `.peaks/_runtime/<sid>/` and the runtime
+ * binding at `.peaks/_runtime/session.json`; the legacy paths
+ * (top-level `<YYYY-MM-DD-session-<hex>>/` dirs and the legacy
+ * top-level `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * dotfiles) must be absent. This helper is exported so tests can
+ * drive the filesystem walk without monkey-patching `process.cwd()`
+ * or `findProjectRoot`.
+ *
+ * Both scanners fail-soft (return `[]` on read errors) so a flaky
+ * filesystem read on a non-fatal probe path never escalates into a
+ * doctor failure.
+ */
+export function inspectWorkspaceLayout(opts) {
+    const topLevel = opts.topLevelScanner ?? defaultTopLevelSessionDirScanner;
+    const dotfiles = opts.dotfileScanner ?? defaultLegacyDotfileScanner;
+    const perChangeId = opts.perChangeIdScanner ?? defaultPerChangeIdDirScanner;
+    return {
+        topLevelSessionDirs: safeList(() => topLevel(opts.projectRoot)),
+        legacyDotfiles: safeList(() => dotfiles(opts.projectRoot)),
+        perChangeIdDirs: safeList(() => perChangeId(opts.projectRoot))
+    };
+}
+function safeList(reader) {
+    try {
+        const out = reader();
+        return Array.isArray(out) ? out : [];
+    }
+    catch {
+        return [];
+    }
+}
+const SESSION_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
+function defaultTopLevelSessionDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!SESSION_DIR_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile or
+            // regular file, but be defensive against weird filesystem state
+            // (e.g. someone manually created a file whose name happens to
+            // match the session-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
+}
+const LEGACY_DOTFILES = ['.session.json', '.active-skill.json'];
+function defaultLegacyDotfileScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const offenders = [];
+    for (const name of LEGACY_DOTFILES) {
+        if (existsSync(join(peaksRoot, name))) {
+            offenders.push(join('.peaks', name));
+        }
+    }
+    return offenders;
+}
+function defaultWorkspaceLayoutProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { topLevelSessionDirs: [], legacyDotfiles: [], perChangeIdDirs: [] };
+    }
+    return inspectWorkspaceLayout({ projectRoot });
+}
+// Slice 007 — per-change-id top-level dir pattern. Matches the
+// F3-canonical (pre-canonicalization) layout the 5 already-shipped
+// slices left behind, e.g. `.peaks/001-2026-06-06-doctor-dist-version-check/`.
+// The pattern is intentionally narrow so it does NOT match the
+// post-F3 system dirs (`_runtime/`, `_dogfood/`, `retrospective/`,
+// `issues/`, `memory/`, `perf-baseline/`, `project-scan/`, `sops/`,
+// `0NN-session-...`, `YYYY-MM-DD-session-...`).
+const PER_CHANGE_ID_PATTERN = /^\d{3}-\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+function defaultPerChangeIdDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!PER_CHANGE_ID_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile
+            // or regular file, but be defensive against weird filesystem
+            // state (e.g. someone manually created a file whose name
+            // happens to match the per-change-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
 }
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
@@ -234,7 +438,7 @@ export async function runDoctor(options = {}) {
         checks.push({
             id: 'skill-presence:workspace',
             ok: false,
-            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/.session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
         });
     }
     else {
@@ -326,6 +530,95 @@ export async function runDoctor(options = {}) {
             message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
         });
     }
+    // Build-hygiene check: the published `dist/` ships a different CLI_VERSION
+    // than the source-of-truth `src/shared/version.ts` / `package.json#version`
+    // whenever the user runs `npx peaks` or `node bin/peaks.js` after `pnpm
+    // install` but before `pnpm build`. This is the silent-stale-CLI failure
+    // mode reported in `.peaks/2026-06-05-session-fecddb/txt/dogfood-2026-06-04-05.md`
+    // (F1). A missing dist/ is treated as informational (fresh clone, not broken)
+    // so the check does not flip the summary to red on a clean checkout.
+    const distProbe = options.distVersionProbe ?? defaultDistVersionProbe;
+    try {
+        const result = distProbe();
+        if (!result.distReadable) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/ is not present; run \`pnpm build\` to populate dist/src/shared/version.js (source version ${result.source})`
+            });
+        }
+        else if (result.match) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/src/shared/version.js ships CLI_VERSION ${result.dist} matching source ${result.source}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist/src/shared/version.js ships CLI_VERSION ${result.dist} but source ${result.source} is in src/shared/version.ts; run \`pnpm build\` to refresh dist/`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'build:dist-version-matches-source',
+            ok: false,
+            message: `dist version check failed: ${getErrorMessage(error)}`
+        });
+    }
+    // Build-hygiene check: a non-canonical post-F3 workspace layout is
+    // the silent-regression failure mode that slice 003 explicitly chose
+    // to allow (the current session binding was kept at top-level as a
+    // safety measure). This check surfaces any leftover top-level
+    // session dirs, the legacy runtime dotfiles (`.peaks/.session.json`,
+    // `.peaks/.active-skill.json`), OR per-change-id top-level dirs
+    // (`.peaks/NNN-YYYY-MM-DD-<slug>/`) so a future contributor who
+    // manually recreates one of them is warned. The check is read-only;
+    // the fix path is `peaks workspace migrate --to-runtime --project
+    // <repo> --apply`.
+    //
+    // Slice 007 broadened this check to flag per-change-id top-level
+    // dirs (the 5 already-shipped slices left them behind). Until
+    // slice 008's migration consolidates them, the check reports
+    // `ok: false` for any repo that still has the legacy per-change-id
+    // layout.
+    const layoutProbe = options.workspaceLayoutProbe ?? defaultWorkspaceLayoutProbe;
+    try {
+        const layout = layoutProbe();
+        // Back-compat: probes injected by older tests (pre-slice-007)
+        // return a 2-field shape (no perChangeIdDirs). Treat missing
+        // field as empty.
+        const perChangeIdDirs = layout.perChangeIdDirs ?? [];
+        if (layout.topLevelSessionDirs.length === 0 && layout.legacyDotfiles.length === 0 && perChangeIdDirs.length === 0) {
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: true,
+                message: 'Workspace layout is canonical: no top-level session dirs, no legacy runtime dotfiles, no per-change-id top-level dirs'
+            });
+        }
+        else {
+            const offenders = [
+                ...layout.topLevelSessionDirs.map((p) => `top-level session dir: ${p}`),
+                ...layout.legacyDotfiles.map((p) => `legacy dotfile: ${p}`),
+                ...perChangeIdDirs.map((p) => `per-change-id top-level dir: ${p}`)
+            ];
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: false,
+                message: `Workspace layout is not canonical. Offenders: ${offenders.join('; ')}. Run \`peaks workspace migrate --to-runtime --project <repo> --apply\` to consolidate.`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'build:workspace-layout-canonical',
+            ok: false,
+            message: `Workspace layout check failed: ${getErrorMessage(error)}`
+        });
+    }
     try {
         const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
         const schema = JSON.parse(schemaText);

package/dist/src/services/progress/progress-service.d.ts

@@ -164,6 +164,32 @@ export type ReadSpawnRecordResult = {
     reason: 'no-binding' | 'no-spawn-record' | 'invalid-json';
 };
 export declare function readSpawnRecord(projectRoot: string): ReadSpawnRecordResult;
+/**
+ * Idempotency check for the `peaks progress start` CLI (and the Task-tool
+ * PreToolUse hook that fires it on every Task call). Returns `true` when a
+ * recent spawn record exists for this project's session, meaning a watch
+ * window was opened within the last `ttlMs` milliseconds. The LLM-side
+ * caller treats `true` as "no-op — a watch is already running somewhere".
+ *
+ * Why TTL instead of pid liveness: the spawned terminal's pid is the
+ * osascript/gnome-terminal process, which exits as soon as it spawns the
+ * nested shell. Checking pid liveness gives false negatives (the process
+ * is gone by design). The spawn record is the canonical "watch was opened
+ * for this session" marker. After `ttlMs` the record is treated as stale
+ * (e.g. the user closed the window long ago) and a fresh start proceeds.
+ *
+ * `ttlMs` defaults to 5 minutes — long enough to cover a typical sub-agent
+ * slice (RD parallel fan-out + QA verdict), short enough that a user who
+ * closed the window gets a fresh one on the next Task call.
+ */
+export type RecentSpawnCheck = {
+    recent: boolean;
+    reason: 'recent-spawn' | 'no-spawn-record' | 'no-binding' | 'invalid-json' | 'stale-spawn' | 'process-dead';
+    /** When reason is 'recent-spawn' or 'stale-spawn', the spawn record. */
+    record?: ProgressSpawnRecord;
+    ageMs?: number;
+};
+export declare function isRecentSpawn(projectRoot: string, now?: () => number, ttlMs?: number): RecentSpawnCheck;
 export declare function clearSpawnRecord(projectRoot: string): boolean;
 export type PhaseClosingTrigger = 'finished' | 'failed';
 /**

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

@@ -245,6 +245,31 @@ export function readSpawnRecord(projectRoot) {
         return { ok: false, reason: 'invalid-json' };
     }
 }
+export function isRecentSpawn(projectRoot, now = Date.now, ttlMs = 5 * 60 * 1000) {
+    const result = readSpawnRecord(projectRoot);
+    if (!result.ok) {
+        return { recent: false, reason: result.reason };
+    }
+    const record = result.data;
+    const spawnedMs = Date.parse(record.spawnedAt);
+    if (Number.isNaN(spawnedMs)) {
+        // Treat unparseable timestamps as a stale record so the next start
+        // proceeds normally. This is the conservative choice — the alternative
+        // (treating unparseable as "always recent") would block legitimate
+        // re-spawns forever.
+        return { recent: false, reason: 'stale-spawn', record };
+    }
+    const ageMs = now() - spawnedMs;
+    if (ageMs < 0) {
+        // Clock skew or future-dated record: trust the record as "recent" so
+        // we do not double-spawn. Same conservative default as a 0-age record.
+        return { recent: true, reason: 'recent-spawn', record, ageMs: 0 };
+    }
+    if (ageMs >= ttlMs) {
+        return { recent: false, reason: 'stale-spawn', record, ageMs };
+    }
+    return { recent: true, reason: 'recent-spawn', record, ageMs };
+}
 export function clearSpawnRecord(projectRoot) {
     const path = spawnRecordPath(projectRoot);
     if (!existsSync(path))

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

@@ -197,12 +197,24 @@ function readSessionJsonBinding(projectRoot) {
  * session does not own the slice.
  */
 function sessionOwnsSlice(projectRoot, sessionId, sliceId) {
-    const sessionDir = join(projectRoot, '.peaks', sessionId);
-    if (!existsSync(sessionDir))
-        return false;
-    for (const marker of [`qa/test-cases/${sliceId}.md`, `qa/test-reports/${sliceId}.md`]) {
-        if (existsSync(join(sessionDir, marker)))
-            return true;
+    // 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;
 }
@@ -215,23 +227,69 @@ function findSessionOwningSlice(projectRoot, sliceId) {
     const peaksRoot = join(projectRoot, '.peaks');
     if (!existsSync(peaksRoot))
         return null;
-    let names;
+    let topLevel;
     try {
-        names = readdirSync(peaksRoot);
+        topLevel = readdirSync(peaksRoot);
     }
     catch {
         return null;
     }
-    names.sort();
-    for (const name of names) {
-        if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+    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, name, sliceId)) {
-            return name;
+        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:

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

@@ -45,6 +45,13 @@ export type SessionMeta = {
  * no binding was present. The caller is expected to do something
  * with that — at minimum surface it in the CLI response so the
  * user can find the directory again if they need to.
+ *
+ * Slice 008 (F22 fix): the read uses the canonicalize-on-read
+ * variant so a binding written with `projectRoot: "."` (relative
+ * form, anchored from inside the project dir) is still found when
+ * the caller passes the absolute realpath. Pre-F22 the
+ * strict-equality read returned null in that case, and rotate
+ * silently no-op'd (the CLI reported "no prior binding").
  */
 export declare function rotateSessionBinding(projectRoot: string): string | null;
 /**
@@ -75,6 +82,11 @@ export declare function setSessionTitle(projectRoot: string, sessionId: string,
 /**
  * List all session directories under .peaks with their metadata.
  * Returns sessions sorted by sessionId descending (most recent first).
+ *
+ * As of slice 2026-06-06-session-layout-canonicalize the session
+ * dirs live at the canonical runtime home `.peaks/_runtime/<sid>/`.
+ * The legacy top-level layout is read for back-compat (one minor
+ * release) but is not authoritative.
  */
 export declare function listSessionMetas(projectRoot: string): SessionMeta[];
 export declare function ensureSession(projectRoot: string): Promise<string>;
@@ -118,14 +130,23 @@ export declare function getSessionIdCanonical(projectRoot: string): string | nul
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.
  *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/<sid>/` is the back-compat read fallback only.
+ *
  * @param projectRoot - Root directory of the project
- * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/2026-05-26-session-a3f8b1")
+ * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/_runtime/2026-05-26-session-a3f8b1")
  */
 export declare function getCurrentSessionDir(projectRoot: string): Promise<string>;
 /**
  * List all session directories in the .peaks folder.
  * Returns session IDs (directory names) sorted by date.
  *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/<sid>/` is read for back-compat (one minor release) so
+ * pre-migration trees keep working.
+ *
  * @param projectRoot - Root directory of the project
  * @returns Array of session IDs
  */