peaks-cli 1.2.9 → 1.3.0

package/dist/src/cli/commands/workspace-commands.js

@@ -1,8 +1,11 @@
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
+import { reconcileWorkspace } from '../../services/workspace/reconcile-service.js';
 import { ensureSession } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_RECONCILE_AGE_DAYS = 7;
 export function registerWorkspaceCommands(program, io) {
     const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
     addJsonOption(workspace
@@ -18,7 +21,7 @@ export function registerWorkspaceCommands(program, io) {
             //     session, unless --allow-session-rebind is set)
             //   - omitted: defer to ensureSession(), which reuses an existing
             //     binding or auto-generates a fresh one. The init then writes
-            //     .session.json so the binding sticks.
+            //     .peaks/_runtime/session.json so the binding sticks.
             //
             // Before that: canonicalise the project root. If the user (or the
             // LLM via "$(pwd)") passed a sub-directory of a real git repo
@@ -75,4 +78,59 @@ export function registerWorkspaceCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(workspace
+        .command('reconcile')
+        .description('Scan .peaks/2026-MM-DD-session-*/ directories and re-point .peaks/_runtime/session.json ' +
+        'to the canonical session (4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
+        'latest any-file mtime -> dir-name sort). Also migrates any legacy .peaks/.session.json / ' +
+        '.peaks/.active-skill.json / .peaks/sop-state/ into .peaks/_runtime/ (idempotent; no-op on a ' +
+        'tree that is already on the new layout). By default the command is a dry-run: it reports empty / abandoned ' +
+        `session dirs older than ${DEFAULT_RECONCILE_AGE_DAYS} days as deletion candidates but does not delete them. ` +
+        'Pass --apply to actually remove the listed candidate dirs (destructive). ' +
+        'Override the age threshold with --older-than <days>.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually delete the deletion candidates (destructive); without it, dry-run only', false)
+        .option('--older-than <days>', `age threshold in days for deletion candidates (default: ${DEFAULT_RECONCILE_AGE_DAYS})`, (value) => Number.parseFloat(value))).action((options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const olderThanDays = options.olderThan ?? DEFAULT_RECONCILE_AGE_DAYS;
+            if (typeof olderThanDays !== 'number' || !Number.isFinite(olderThanDays) || olderThanDays <= 0) {
+                printResult(io, fail('workspace.reconcile', 'INVALID_AGE_THRESHOLD', `--older-than must be a positive number of days`, { provided: options.olderThan }, ['Use --older-than 7 (or omit it to accept the 7-day default)']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const olderThanMs = olderThanDays * MS_PER_DAY;
+            const apply = options.apply === true;
+            const result = reconcileWorkspace({
+                projectRoot,
+                apply,
+                olderThanMs
+            });
+            const warnings = [];
+            if (result.sessions.length === 0) {
+                warnings.push('No session directories found under .peaks/. Run peaks workspace init first.');
+            }
+            if (apply && result.deleted.length > 0) {
+                warnings.push(`Deleted ${result.deleted.length} session dir(s) older than ${olderThanDays} day(s).`);
+            }
+            const nextActions = [];
+            if (result.migratedFiles.length > 0) {
+                nextActions.push(`Migrated ${result.migratedFiles.length} legacy runtime file(s) into .peaks/_runtime/: ${result.migratedFiles.join(', ')}.`);
+            }
+            if (result.repointed) {
+                nextActions.push(`Re-pointed .peaks/_runtime/session.json from ${result.repointedFrom ?? '<unbound>'} to ${result.repointedTo}.`);
+            }
+            if (!apply && result.wouldDelete.length > 0) {
+                nextActions.push(`Re-run with --apply to delete ${result.wouldDelete.length} candidate dir(s).`);
+            }
+            printResult(io, ok('workspace.reconcile', result, warnings, nextActions), options.json);
+            if (result.errors.length > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('workspace.reconcile', 'WORKSPACE_RECONCILE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -51,6 +51,52 @@ export type CommitBoundary = {
     syncState: 'synced' | 'pending' | 'failed';
     rollbackPoint: string | null;
 };
+/**
+ * Resolution sources for `resolveArtifactSession`, in priority order.
+ * - `active-skill`: the orchestrator's active-skill marker
+ *   (`.peaks/_runtime/active-skill.json`, with a one-minor-release
+ *   fallback to `.peaks/.active-skill.json`) `sessionId` points to a
+ *   session dir that owns the slice's marker artifact.
+ * - `session-json`: the workspace binding in
+ *   `.peaks/_runtime/session.json` (with back-compat fallback to
+ *   `.peaks/.session.json`) points to a session dir that owns the
+ *   slice's marker artifact (active-skill was checked but did not
+ *   own it; session-json is the next source).
+ * - `find-fallback`: neither binding owned the artifact, but a `find`
+ *   walk under `.peaks/` located a session dir that does own it.
+ */
+export type ArtifactSessionSource = 'active-skill' | 'session-json' | 'find-fallback';
+export type ResolvedArtifactSession = {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
+/**
+ * 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 declare function resolveArtifactSession(projectRoot: string, sliceId: string): ResolvedArtifactSession;
 export declare function getChangeTraceabilityStatus(): ChangeTraceabilityStatus;
 export declare function createChangeImpact(options: {
     changeId: string;
@@ -71,10 +117,15 @@ export declare function recordCommitBoundary(options: {
     sliceId: string;
     artifacts?: string[];
     codeFiles?: string[];
-}): CommitBoundary;
+}): CommitBoundary & {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
 export declare function validateArtifactRetention(sliceId: string): {
     valid: boolean;
     missingArtifacts: string[];
     warnings: string[];
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
 };
 export declare function getScHelpText(): string[];

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,150 @@ 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) {
+    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;
+    }
+    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 names;
+    try {
+        names = 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))
+            continue;
+        if (sessionOwnsSlice(projectRoot, name, sliceId)) {
+            return name;
+        }
+    }
+    return null;
+}
+/**
+ * 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 +361,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 +370,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/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,20 @@
  * 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 { 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 +77,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 +103,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 +132,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 +153,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 +189,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;
 }
 /**