peaks-cli 1.3.1 → 1.3.2

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

@@ -18,6 +18,32 @@ export type CodegraphCapabilityProbe = {
     binaryPath: string;
     binaryExists: boolean;
 };
+export type DistVersionComparison = {
+    dist: string | null;
+    source: string;
+    match: boolean;
+    distReadable: boolean;
+};
+export type DistVersionProbe = () => DistVersionComparison;
+export type WorkspaceLayoutInspection = {
+    topLevelSessionDirs: string[];
+    legacyDotfiles: string[];
+    /**
+     * Slice 007 — per-change-id top-level dirs (e.g. `.peaks/001-2026-06-06-.../`).
+     * The pre-F3 canonical layout put reviewable artifacts under a
+     * per-change-id top-level dir; the post-F3 canonical layout
+     * consolidates them under `.peaks/_runtime/<sid>/<role>/`. Any
+     * leftover per-change-id top-level dir is a regression to flag.
+     * Slice 008's migration will consolidate these; until then, the
+     * check reports them as `ok: false`.
+     *
+     * Optional in the type for back-compat with test probes that
+     * pre-date the slice 007 broadening; the check itself falls back
+     * to an empty array when the field is missing.
+     */
+    perChangeIdDirs?: string[];
+};
+export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
@@ -29,6 +55,10 @@ export type DoctorOptions = {
     workspaceInitializedProbe?: () => boolean;
     /** Platform string (defaults to process.platform); injectable for tests. */
     platform?: NodeJS.Platform;
+    /** Injected for the build:dist-version-matches-source check (defaults to compareDistVersion on disk). */
+    distVersionProbe?: DistVersionProbe;
+    /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
+    workspaceLayoutProbe?: WorkspaceLayoutProbe;
 };
 /**
  * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
@@ -37,4 +67,36 @@ export type DoctorOptions = {
  * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
  */
 export declare function isWorkspaceInitializedAt(projectRoot: string): boolean;
+/**
+ * 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 declare function compareDistVersion(opts: {
+    projectRoot: string;
+    distVersionReader?: (root: string) => string | null;
+    sourceVersionReader?: (root: string) => string | null;
+}): DistVersionComparison;
+/**
+ * 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 declare function inspectWorkspaceLayout(opts: {
+    projectRoot: string;
+    topLevelScanner?: (root: string) => string[];
+    dotfileScanner?: (root: string) => string[];
+    perChangeIdScanner?: (root: string) => string[];
+}): WorkspaceLayoutInspection;
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

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';
@@ -68,6 +68,192 @@ 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/,
     /peaks\s+memory\s+extract[^\n]*--apply/,
@@ -344,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/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
  */

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

@@ -180,9 +180,16 @@ function writeSessionFile(projectRoot, info) {
  * 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 function rotateSessionBinding(projectRoot) {
-    const previous = readSessionFile(projectRoot);
+    const previous = readSessionFileCanonical(projectRoot);
     if (previous === null) {
         return null;
     }
@@ -221,7 +228,14 @@ export function setCurrentSessionBinding(projectRoot, sessionId) {
     return info;
 }
 function getMetaFilePath(projectRoot, sessionId) {
-    return join(projectRoot, '.peaks', sessionId, META_FILE);
+    // As of slice 2026-06-06-session-layout-canonicalize, the per-session
+    // `session.json` (the file written by `setSessionMeta`) lives at the
+    // canonical runtime home `.peaks/_runtime/<sid>/session.json`, NOT
+    // at the top-level `.peaks/<sid>/session.json` (which would imply
+    // the legacy session-scoped layout and conflict with the workspace
+    // service's `_runtime/<sid>/` invariant). The migration in slice
+    // 003 moved any top-level meta files into the runtime home.
+    return join(projectRoot, '.peaks', '_runtime', sessionId, META_FILE);
 }
 function readSessionMeta(projectRoot, sessionId) {
     const metaPath = getMetaFilePath(projectRoot, sessionId);
@@ -241,7 +255,9 @@ function readSessionMeta(projectRoot, sessionId) {
 }
 function writeSessionMeta(projectRoot, sessionId, meta) {
     const metaPath = getMetaFilePath(projectRoot, sessionId);
-    const metaDir = join(projectRoot, '.peaks', sessionId);
+    // As of slice 003, the meta file lives at `.peaks/_runtime/<sid>/session.json`.
+    // The parent dir of that file is the canonical runtime session dir.
+    const metaDir = dirname(metaPath);
     if (!existsSync(metaDir)) {
         mkdirSync(metaDir, { recursive: true });
     }
@@ -282,23 +298,67 @@ export function setSessionTitle(projectRoot, sessionId, title) {
 /**
  * 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 function listSessionMetas(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    const entries = readdirSync(peaksRoot, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
-        .map((entry) => {
-        const meta = readSessionMeta(projectRoot, entry.name);
-        return meta ?? {
-            sessionId: entry.name,
-            projectRoot,
-            createdAt: ''
-        };
-    })
-        .sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const meta = readSessionMeta(projectRoot, name);
+            result.push(meta ?? { sessionId: name, projectRoot, createdAt: '' });
+        }
+    };
+    // Canonical home first, then the legacy top-level (back-compat).
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    result.sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+    return result;
+}
+/**
+ * Back-compat read for the legacy top-level meta file (the one that
+ * pre-slice 003 trees still have at `.peaks/<sid>/session.json`).
+ * Kept as a separate helper so the canonical reader is the default.
+ */
+function readSessionMetaCompat(peaksRoot, sessionId) {
+    const metaPath = join(peaksRoot, sessionId, META_FILE);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Get or create the current session for a project.
@@ -322,6 +382,26 @@ export async function ensureSession(projectRoot) {
     if (existing) {
         return existing.sessionId;
     }
+    // Slice 007 — sub-agent session sharing. When the strict-equality
+    // read returns null (e.g. the binding was written with the relative
+    // form "." from inside the project dir, but the caller passes the
+    // absolute realpath), fall through to the canonical-fallback read.
+    // `ensureSession` is a session-creating primitive — its caller
+    // wants the existing binding if one exists, even if the projectRoot
+    // forms differ. Without this fallback, a sub-agent that anchors via
+    // `cd <repo> && peaks skill presence:set` and then runs
+    // `peaks request init --project <abs-path>` would auto-generate a
+    // new session and create an orphan dir.
+    //
+    // The strict-equality read is preserved for other modules
+    // (notably `shared/change-id.ts` via `buildArtifactRelativePath`)
+    // that depend on the "no session bound" code path — switching the
+    // default would cascade into ~30 test failures in those modules.
+    // The canonical-fallback is opt-in for `ensureSession` only.
+    const canonical = getSessionIdCanonical(projectRoot);
+    if (canonical !== null) {
+        return canonical;
+    }
     const sessionId = generateSessionId();
     const now = new Date().toISOString();
     const info = {
@@ -387,31 +467,60 @@ export function getSessionIdCanonical(projectRoot) {
  * 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 async function getCurrentSessionDir(projectRoot) {
     const sessionId = await ensureSession(projectRoot);
-    return join(projectRoot, '.peaks', sessionId);
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
 }
 /**
  * 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
  */
 export function listSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    const { readdirSync } = require('node:fs');
-    const entries = readdirSync(peaksRoot, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
-        .map((entry) => entry.name)
-        .sort()
-        .reverse(); // Most recent first
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            result.push(name);
+        }
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    return result.sort().reverse();
 }
 /**
  * Get the path to project-scan.md for the current session.

package/dist/src/services/slice/slice-check-service.js

@@ -210,7 +210,26 @@ export async function sliceCheck(options) {
     stages.push(await runTypecheck(options.projectRoot));
     // Stage 2: full vitest
     if (!options.skipTests) {
-        stages.push(await runUnitTests(options.projectRoot));
+        const unitTests = await runUnitTests(options.projectRoot);
+        // Opt-in override: if --allow-pre-existing-failures is set AND the
+        // unit-test stage failed, downgrade `failed` to `skipped` with a
+        // reason that names the failure count and points to the long-term
+        // fix. Does NOT affect the other 3 stages.
+        if (options.allowPreExistingFailures === true &&
+            unitTests.status === 'fail') {
+            const failureCount = unitTests.data?.failed ?? 0;
+            stages.push({
+                name: 'unit-tests',
+                description: 'npx vitest run (overridden via --allow-pre-existing-failures)',
+                status: 'skipped',
+                durationMs: unitTests.durationMs,
+                detail: `pre-existing failures: ${failureCount} failing test(s) under coverage.exclude or unrelated to this slice; user opted in via --allow-pre-existing-failures. For the long-term fix, mark these tests .skip or move to coverage.exclude (see dogfood-2-f1-f4.md F17c).`,
+                data: { ...(unitTests.data ?? {}), overriddenFrom: 'fail', failureCount }
+            });
+        }
+        else {
+            stages.push(unitTests);
+        }
     }
     else {
         stages.push({