peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/session/session-binding-bridge.js

@@ -0,0 +1,247 @@
+/**
+ * Session × binding-store × outer-session bridge layer.
+ *
+ * v2.18.0: extracted from `session-manager.ts` to keep that file under
+ * the Karpathy 800 LOC cap while the binding-store D2 sub-slice work
+ * adds ~65 LOC over the next slice. The 4 blocks that moved here are
+ * the natural "bridge" concern: the lower-level session-manager
+ * primitives (read / write the project-level session binding, get /
+ * rotate, etc.) are wired up here into the user-facing `ensureSession`
+ * and the outer-session-aware `ensureSessionWithRotation`.
+ *
+ * `session-manager.ts` re-exports the two functions and the two result
+ * types so the 5 external callers (`request-artifact-service.ts`,
+ * `upgrade-commands.ts`, `init-command.ts`, plus 2 test files) do NOT
+ * need to change their import path. The re-export shim is the only
+ * added code in `session-manager.ts`.
+ *
+ * Body of every function moved verbatim per Karpathy #3 (Surgical
+ * Changes). No behavior change. The bridge adds nothing of its own.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { initWorkspace } from '../workspace/workspace-service.js';
+import { getSessionId, getSessionIdCanonical, getSessionMeta, rotateSessionBinding } from './session-manager.js';
+// --- Lower-level helpers the bridge needs (moved verbatim) ---
+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);
+}
+function canonicalizeProjectRoot(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function resolveStoredAgainstCaller(stored, caller) {
+    const resolved = resolve(caller, stored);
+    return canonicalizeProjectRoot(resolved);
+}
+function generateSessionId() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const date = `${year}-${month}-${day}`;
+    const random = randomBytes(3).toString('hex');
+    return `${date}-session-${random}`;
+}
+function getSessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', SESSION_FILE);
+}
+function readSessionFile(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        if (data.sessionId && data.projectRoot === projectRoot) {
+            return data;
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function readSessionFileCanonical(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
+        if (data.sessionId &&
+            storedRaw !== null &&
+            resolveStoredAgainstCaller(storedRaw, projectRoot) === resolveStoredAgainstCaller(projectRoot, projectRoot)) {
+            return data;
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function writeSessionFile(projectRoot, info) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const dir = dirname(sessionFile);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
+}
+function getMetaFilePath(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, META_FILE);
+}
+function readSessionMeta(projectRoot, sessionId) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    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 { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function writeSessionMeta(projectRoot, sessionId, meta) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    const metaDir = dirname(metaPath);
+    if (!existsSync(metaDir)) {
+        mkdirSync(metaDir, { recursive: true });
+    }
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+}
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
+export async function ensureSession(projectRoot) {
+    const existing = readSessionFile(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 modules that depend on
+    // the "no session bound" code path. 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 = {
+        sessionId,
+        createdAt: now,
+        projectRoot
+    };
+    writeSessionFile(projectRoot, info);
+    await initWorkspace({ projectRoot, sessionId });
+    // Initialize session metadata inside the session directory
+    const outerSessionId = getCurrentOuterSessionId();
+    writeSessionMeta(projectRoot, sessionId, {
+        sessionId,
+        projectRoot,
+        createdAt: now,
+        ...(outerSessionId !== undefined ? { outerSessionId } : {})
+    });
+    return sessionId;
+}
+/**
+ * Outer-session-aware wrapper around `ensureSession`.
+ *
+ * Slice 018 (auto-roll on outer-mismatch). When the current outer
+ * session id (sourced from `PEAKS_OUTER_SESSION_ID` with
+ * `CLAUDE_CODE_SESSION_ID` as the Claude-Code fallback) differs from
+ * the outer session id recorded on the *bound* peaks session's
+ * `.peaks/_runtime/<sid>/session.json`, the project-level session
+ * binding is rotated before `ensureSession` is called. The old
+ * session dir is preserved on disk (data is never wiped) — only the
+ * binding changes — and the rotation is surfaced in the return value
+ * so the CLI can include it in the JSON envelope.
+ *
+ * Rotation is suppressed in three cases (all false-positive guards):
+ *
+ *   1. The current outer session id is undefined (no env var set) —
+ *      there is no signal to compare against, defaulting to "do not
+ *      rotate" avoids orphaning the session.
+ *   2. The bound session has no recorded `outerSessionId` (legacy
+ *      session predating the outer-session contract) — there is no
+ *      signal on the other side either.
+ *   3. The bound session's recorded outer session id matches the
+ *      current one (reconnect within the same Claude session) — this
+ *      is the common case, not a swap.
+ *
+ * When `options.skipRotateOnOuterMismatch === true`, the rotation
+ * check is short-circuited and the binding is preserved (opt-out for
+ * `peaks workspace init --no-rotate-on-outer-mismatch`). The wrapper
+ * still delegates to `ensureSession` so the caller gets the existing
+ * binding on a reconnect and a fresh id on a first run.
+ *
+ * Existing public surface is preserved: `ensureSession` is unchanged.
+ * This wrapper is the new entry point the CLI uses.
+ */
+export async function ensureSessionWithRotation(projectRoot, options) {
+    const skipRotate = options?.skipRotateOnOuterMismatch === true;
+    const currentOuterSessionId = getCurrentOuterSessionId();
+    // Compute the rotation decision up front. We only rotate when ALL
+    // three pre-conditions hold: (a) the current outer session id is
+    // defined, (b) the bound session has a recorded outer session id,
+    // and (c) the two differ. The bound session id is the *first*
+    // read so we can use it both for the comparison and for the
+    // rotation result.
+    const boundSessionId = getSessionId(projectRoot);
+    let rotated = null;
+    let rotationReason = null;
+    if (boundSessionId !== null && currentOuterSessionId !== undefined) {
+        const boundMeta = getSessionMeta(projectRoot, boundSessionId);
+        const boundOuter = boundMeta?.outerSessionId;
+        if (typeof boundOuter === 'string' &&
+            boundOuter.length > 0 &&
+            boundOuter !== currentOuterSessionId &&
+            !skipRotate) {
+            rotated = rotateSessionBinding(projectRoot);
+            rotationReason = 'outer-session-mismatch';
+        }
+    }
+    // After the rotation, `ensureSession` will either reuse the
+    // canonical-fallback binding (when one still exists, e.g. a sibling
+    // projectRoot form) or auto-generate a fresh id. We pass through.
+    void rotated; // rotated is the *previous* session id; preserved for the caller via the return value
+    const sessionId = await ensureSession(projectRoot);
+    return {
+        sessionId,
+        previousSessionId: rotated,
+        rotationReason
+    };
+}

package/dist/services/session/session-checkpoint-service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `peaks session checkpoint` — slice 011.
+ *
+ * Writes a JSON snapshot of the current session's state to
+ * `_runtime/<sessionId>/checkpoints/<iso-timestamp>.json`. Idempotent —
+ * any number of checkpoints may exist; the service prunes the oldest
+ * beyond `MAX_CHECKPOINTS` so the directory does not grow without bound.
+ *
+ * Designed for skill-level invocation (NG1). The LLM is the only one
+ * that knows when context pressure is high; the CLI is the muscle.
+ */
+export type CheckpointReason = 'context-fill' | 'periodic' | 'artifact-written' | 'user-pause' | 'user-close';
+export declare const CHECKPOINT_REASONS: readonly CheckpointReason[];
+export interface CheckpointSnapshot {
+    sessionId: string;
+    lastActivity: string;
+    currentPlan: string;
+    openQuestions: string[];
+    recentDecisions: string[];
+    recentArtifactPaths: string[];
+    gitStatus: string;
+    skillsActive: string[];
+    todoState: string[];
+    reason: CheckpointReason;
+    createdAt: string;
+}
+export interface CheckpointOptions {
+    sessionId: string;
+    reason: CheckpointReason;
+    /** Injectable clock for deterministic tests. Returns ISO timestamp. */
+    now?: () => Date;
+    currentPlan?: string;
+    openQuestions?: string[];
+    recentDecisions?: string[];
+    recentArtifactPaths?: string[];
+    gitStatus?: string;
+    skillsActive?: string[];
+    todoState?: string[];
+}
+export declare function isValidCheckpointReason(value: string): value is CheckpointReason;
+export interface CheckpointWriteResult {
+    path: string;
+    sessionId: string;
+    reason: CheckpointReason;
+    createdAt: string;
+    pruned: string[];
+    totalRetained: number;
+}
+export declare function writeCheckpoint(projectRoot: string, options: CheckpointOptions): CheckpointWriteResult;
+export declare function readCheckpoint(path: string): CheckpointSnapshot;
+export declare function listCheckpointPaths(projectRoot: string, sessionId: string): string[];
+export declare function latestCheckpointPath(projectRoot: string, sessionId: string): string | null;
+export declare const CHECKPOINT_CONSTANTS: {
+    readonly CHECKPOINTS_DIR: "checkpoints";
+    readonly CHECKPOINT_FILENAME_EXT: ".json";
+    readonly MAX_CHECKPOINTS: 10;
+};

package/dist/services/session/session-checkpoint-service.js

@@ -0,0 +1,143 @@
+/**
+ * `peaks session checkpoint` — slice 011.
+ *
+ * Writes a JSON snapshot of the current session's state to
+ * `_runtime/<sessionId>/checkpoints/<iso-timestamp>.json`. Idempotent —
+ * any number of checkpoints may exist; the service prunes the oldest
+ * beyond `MAX_CHECKPOINTS` so the directory does not grow without bound.
+ *
+ * Designed for skill-level invocation (NG1). The LLM is the only one
+ * that knows when context pressure is high; the CLI is the muscle.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { emitObservabilityEvent } from '../observability/observability-service.js';
+const CHECKPOINTS_DIR = 'checkpoints';
+const CHECKPOINT_FILENAME_EXT = '.json';
+const MAX_CHECKPOINTS = 10;
+export const CHECKPOINT_REASONS = [
+    'context-fill',
+    'periodic',
+    'artifact-written',
+    'user-pause',
+    'user-close'
+];
+function toPosix(p) {
+    return p.split(sep).join('/');
+}
+function checkpointsDirPath(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, CHECKPOINTS_DIR);
+}
+function isoTimestamp(d) {
+    // Replace colons with dashes for filesystem safety. The full ISO is
+    // preserved inside the JSON content; the filename uses a
+    // filesystem-friendly form.
+    return d.toISOString().replace(/[:.]/g, '-');
+}
+export function isValidCheckpointReason(value) {
+    return CHECKPOINT_REASONS.includes(value);
+}
+function readSessionLastActivity(projectRoot, sessionId) {
+    const sessionJsonPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'session.json');
+    if (!existsSync(sessionJsonPath))
+        return '';
+    try {
+        const raw = readFileSync(sessionJsonPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.lastActivity === 'string' ? parsed.lastActivity : '';
+    }
+    catch {
+        return '';
+    }
+}
+function listCheckpoints(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(CHECKPOINT_FILENAME_EXT))
+        .map((e) => {
+        const path = join(dir, e.name);
+        const mtimeMs = statSync(path).mtimeMs;
+        const stem = e.name.slice(0, -CHECKPOINT_FILENAME_EXT.length);
+        return { path, createdAt: stem, mtimeMs };
+    });
+}
+function pruneOldest(dir) {
+    const all = listCheckpoints(dir);
+    if (all.length <= MAX_CHECKPOINTS)
+        return [];
+    all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const toRemove = all.slice(MAX_CHECKPOINTS);
+    const removed = [];
+    for (const item of toRemove) {
+        rmSync(item.path, { force: true });
+        removed.push(toPosix(item.path));
+    }
+    return removed;
+}
+export function writeCheckpoint(projectRoot, options) {
+    const now = (options.now ?? (() => new Date()))();
+    const createdAt = now.toISOString();
+    const lastActivity = readSessionLastActivity(projectRoot, options.sessionId) || createdAt;
+    const dir = checkpointsDirPath(projectRoot, options.sessionId);
+    mkdirSync(dir, { recursive: true });
+    const snapshot = {
+        sessionId: options.sessionId,
+        lastActivity,
+        currentPlan: options.currentPlan ?? '',
+        openQuestions: options.openQuestions ?? [],
+        recentDecisions: options.recentDecisions ?? [],
+        recentArtifactPaths: options.recentArtifactPaths ?? [],
+        gitStatus: options.gitStatus ?? '',
+        skillsActive: options.skillsActive ?? [],
+        todoState: options.todoState ?? [],
+        reason: options.reason,
+        createdAt
+    };
+    const filename = `${isoTimestamp(now)}${CHECKPOINT_FILENAME_EXT}`;
+    const path = join(dir, filename);
+    writeFileSync(path, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
+    // Slice C of v2.11.1 — observability hook #3/7. Fire-and-forget
+    // per PRD Q4. The synchronous emit never throws.
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: snapshot.createdAt,
+        sessionId: snapshot.sessionId,
+        category: 'checkpoint',
+        detail: {
+            reason: snapshot.reason,
+            checkpointPath: toPosix(path),
+            currentPlanLength: snapshot.currentPlan.length,
+            openQuestionsCount: snapshot.openQuestions.length,
+            recentDecisionsCount: snapshot.recentDecisions.length
+        }
+    }, { projectRoot });
+    const pruned = pruneOldest(dir);
+    const totalRetained = listCheckpoints(dir).length;
+    return {
+        path: toPosix(path),
+        sessionId: options.sessionId,
+        reason: options.reason,
+        createdAt,
+        pruned,
+        totalRetained
+    };
+}
+export function readCheckpoint(path) {
+    const raw = readFileSync(path, 'utf8');
+    return JSON.parse(raw);
+}
+export function listCheckpointPaths(projectRoot, sessionId) {
+    return listCheckpoints(checkpointsDirPath(projectRoot, sessionId))
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .map((c) => toPosix(c.path));
+}
+export function latestCheckpointPath(projectRoot, sessionId) {
+    const paths = listCheckpointPaths(projectRoot, sessionId);
+    return paths.length > 0 ? paths[0] ?? null : null;
+}
+export const CHECKPOINT_CONSTANTS = {
+    CHECKPOINTS_DIR,
+    CHECKPOINT_FILENAME_EXT,
+    MAX_CHECKPOINTS
+};

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

@@ -0,0 +1,168 @@
+/**
+ * Session management service for Peaks artifact storage.
+ * Manages session lifecycle: creation, retrieval, and directory initialization.
+ *
+ * Sessions are automatically created when any skill is invoked.
+ * Each session gets a unique directory under .peaks/ with incrementing numbered files.
+ */
+export type SessionInfo = {
+    sessionId: string;
+    createdAt: string;
+    projectRoot: string;
+};
+export type SessionMeta = {
+    sessionId: string;
+    title?: string;
+    skill?: string;
+    mode?: string;
+    gate?: string;
+    createdAt: string;
+    lastActivity?: string;
+    projectRoot: string;
+    /**
+     * The outer (harness / IDE / plugin) session id that
+     * `ensureSession` was called from. Sourced from
+     * `PEAKS_OUTER_SESSION_ID` env var, with `CLAUDE_CODE_SESSION_ID`
+     * as a Claude-Code fallback. Stamped once at session creation;
+     * later presence writes can compare against this to detect an
+     * outer-session swap and AskUserQuestion the user about rolling
+     * a new peaks session. Sessions predating the field simply
+     * have it undefined; presence-mismatch detection skips those
+     * (no false positives on legacy data).
+     */
+    outerSessionId?: string;
+};
+/**
+ * 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
+ * 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;
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/_runtime/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export declare function setCurrentSessionBinding(projectRoot: string, sessionId: string): SessionInfo;
+/**
+ * Read metadata for a specific session directory.
+ * Returns null if the session directory or its session.json does not exist.
+ */
+export declare function getSessionMeta(projectRoot: string, sessionId: string): SessionMeta | null;
+/**
+ * Write or update metadata for a session.  Fields besides sessionId and createdAt
+ * are merged on top of the current meta (partial update).
+ */
+export declare function setSessionMeta(projectRoot: string, sessionId: string, partial: Partial<Omit<SessionMeta, 'sessionId' | 'createdAt' | 'projectRoot'>>): SessionMeta;
+/**
+ * Set the display title for a session directory.
+ */
+export declare function setSessionTitle(projectRoot: string, sessionId: string, title: string): SessionMeta;
+/**
+ * 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 { ensureSession, ensureSessionWithRotation, type EnsureSessionOptions, type EnsureSessionResult } from './session-binding-bridge.js';
+/**
+ * Get the current session ID without creating a new one.
+ * Returns null if no session exists.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Session ID or null
+ */
+export declare function getSessionId(projectRoot: string): string | null;
+/**
+ * Resolve the current session id with canonicalize-on-read
+ * semantics. This is the variant the progress subcommands
+ * (step / watch / start / close) use, because the legacy
+ * `getSessionId` returns null any time the stored
+ * `projectRoot` form differs from the caller-passed form
+ * (e.g. stored is "." from inside the project dir; caller
+ * is the absolute realpath). When `getSessionId` returns
+ * null, callers like `ensureSession` create a brand-new
+ * session and overwrite the binding — which is what the
+ * user observed as the "mid-dogfood rebind" bug.
+ *
+ * The fix is to canonicalize both sides of the compare
+ * (realpath, then optionally resolve relative stored
+ * against the caller's project root). The two forms of
+ * the same physical directory now compare equal, and the
+ * existing binding is found instead of being overwritten.
+ *
+ * Use this instead of `getSessionId` only when the
+ * caller is operating on a user-supplied `--project` flag
+ * and the binding may have been written by a CLI invocation
+ * that was running from inside the project dir (the common
+ * peaks-code / peaks-sop scenario). Other modules depend
+ * on the strict-equality semantics of `getSessionId` (the
+ * "no binding" fallback path is part of their contract),
+ * so this variant is opt-in.
+ */
+export declare function getSessionIdCanonical(projectRoot: string): string | null;
+/**
+ * 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/_runtime/<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/_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/_runtime/<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 declare function listSessions(projectRoot: string): string[];
+/**
+ * Get the path to project-scan.md for the current session.
+ * Creates the session if it doesn't exist.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path to project-scan.md
+ */
+export declare function getProjectScanPath(projectRoot: string): Promise<string>;
+/**
+ * Check if project-scan.md exists for the current session.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns true if project-scan.md exists
+ */
+export declare function hasProjectScan(projectRoot: string): boolean;