peaks-cli 1.3.7 → 1.3.9

package/dist/src/services/retrospective/retrospective-index.js

@@ -0,0 +1,110 @@
+/**
+ * retrospective-index — load `.peaks/retrospective/index.json`, parse to
+ * `RetrospectiveEntry[]`, return the index envelope.
+ *
+ * Slice 023 (R3). Pure read on the hot path: a single `fs.readFile` of
+ * the index, no MD-tree fallback. The migration script (G9) is the only
+ * writer; this loader is read-only.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const VALID_TYPES = new Set(['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore']);
+const VALID_OUTCOMES = new Set(['shipped', 'blocked', 'in-flight', 'cancelled']);
+export function loadRetrospectiveIndex(projectRoot) {
+    const resolvedRoot = resolve(projectRoot);
+    const indexPath = join(resolvedRoot, '.peaks', 'retrospective', 'index.json');
+    if (!existsSync(indexPath)) {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: 'no retrospective index; run `peaks retrospective migrate --apply` to build one from legacy MDs'
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(indexPath, 'utf8');
+    }
+    catch {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: `failed to read retrospective index at ${indexPath}`
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: `retrospective index at ${indexPath} is not valid JSON`
+        };
+    }
+    const entries = extractEntries(parsed);
+    const sorted = [...entries].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return {
+        projectRoot: resolvedRoot,
+        indexPath,
+        entries: sorted,
+        totalCount: sorted.length,
+        source: 'index.json',
+        warning: null
+    };
+}
+function extractEntries(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const obj = parsed;
+    if (!Array.isArray(obj.entries))
+        return [];
+    const result = [];
+    for (const candidate of obj.entries) {
+        if (!isRetrospectiveEntry(candidate))
+            continue;
+        result.push(candidate);
+    }
+    return result;
+}
+function isRetrospectiveEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (typeof v.id !== 'string' || v.id.length === 0)
+        return false;
+    if (typeof v.sessionId !== 'string')
+        return false;
+    if (typeof v.type !== 'string' || !VALID_TYPES.has(v.type))
+        return false;
+    if (typeof v.title !== 'string')
+        return false;
+    if (typeof v.summary !== 'string')
+        return false;
+    if (typeof v.outcome !== 'string' || !VALID_OUTCOMES.has(v.outcome))
+        return false;
+    if (!Array.isArray(v.keyDecisions))
+        return false;
+    if (!v.keyDecisions.every((decision) => typeof decision === 'string'))
+        return false;
+    if (typeof v.lessonsLearned !== 'number' || !Number.isInteger(v.lessonsLearned) || v.lessonsLearned < 0)
+        return false;
+    if (!Array.isArray(v.artifactPaths))
+        return false;
+    if (!v.artifactPaths.every((p) => typeof p === 'string'))
+        return false;
+    if (typeof v.updatedAt !== 'string')
+        return false;
+    if (v.sliceId !== undefined && typeof v.sliceId !== 'string')
+        return false;
+    return true;
+}

package/dist/src/services/retrospective/retrospective-show.d.ts

@@ -0,0 +1,40 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { loadRetrospectiveIndex, type RetrospectiveEntry, type RetrospectiveIndexResult } from './retrospective-index.js';
+export type RetrospectiveFormat = 'compact' | 'pretty';
+export interface RetrospectiveShowOptions {
+    projectRoot: string;
+    id: string;
+    format?: RetrospectiveFormat;
+}
+export interface RetrospectiveShowSuccess {
+    ok: true;
+    projectRoot: string;
+    format: RetrospectiveFormat;
+    entry: RetrospectiveEntry;
+    body: string;
+    warnings: string[];
+}
+export interface RetrospectiveShowError {
+    ok: false;
+    code: 'NOT_FOUND' | 'INDEX_MISSING' | 'ARTIFACT_MISSING' | 'INVALID_REQUEST';
+    message: string;
+    hint?: string;
+    projectRoot: string;
+    missingArtifacts?: string[];
+}
+export type RetrospectiveShowResult = RetrospectiveShowSuccess | RetrospectiveShowError;
+export declare function showRetrospective(options: RetrospectiveShowOptions): RetrospectiveShowResult;
+export { loadRetrospectiveIndex };
+export type { RetrospectiveEntry, RetrospectiveIndexResult };

package/dist/src/services/retrospective/retrospective-show.js

@@ -0,0 +1,109 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { loadRetrospectiveIndex } from './retrospective-index.js';
+export function showRetrospective(options) {
+    if (typeof options.id !== 'string' || options.id.trim().length === 0) {
+        return {
+            ok: false,
+            code: 'INVALID_REQUEST',
+            message: 'retrospective show requires a non-empty <id> argument',
+            projectRoot: resolve(options.projectRoot)
+        };
+    }
+    const resolvedRoot = resolve(options.projectRoot);
+    const index = loadRetrospectiveIndex(resolvedRoot);
+    if (index.source === null) {
+        return {
+            ok: false,
+            code: 'INDEX_MISSING',
+            message: index.warning ?? `retrospective index not found at ${index.indexPath}`,
+            hint: 'run `peaks retrospective migrate --apply` to build the index',
+            projectRoot: resolvedRoot
+        };
+    }
+    const entry = index.entries.find((e) => e.id === options.id);
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: 'NOT_FOUND',
+            message: `retrospective entry not found: ${options.id}`,
+            hint: 'run `peaks retrospective index --json` to see available ids',
+            projectRoot: resolvedRoot
+        };
+    }
+    const format = options.format ?? 'compact';
+    const synthesis = synthesizeBody(entry, resolvedRoot);
+    const body = format === 'pretty' ? synthesis.body : formatMdCompact(synthesis.body);
+    const warnings = synthesis.warnings;
+    return {
+        ok: true,
+        projectRoot: resolvedRoot,
+        format,
+        entry,
+        body,
+        warnings
+    };
+}
+function synthesizeBody(entry, projectRoot) {
+    if (entry.artifactPaths.length === 0) {
+        return { body: renderEntryHeader(entry), warnings: ['entry has no artifactPaths; body is the index summary only'] };
+    }
+    const sections = [];
+    const warnings = [];
+    for (const relativePath of entry.artifactPaths) {
+        const absolutePath = join(projectRoot, relativePath);
+        if (!existsSync(absolutePath)) {
+            warnings.push(`artifact missing on disk: ${relativePath}`);
+            continue;
+        }
+        try {
+            const content = readFileSync(absolutePath, 'utf8');
+            sections.push(`## ${relativePath}\n\n${content}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`failed to read ${relativePath}: ${message}`);
+        }
+    }
+    const header = renderEntryHeader(entry);
+    const body = sections.length === 0
+        ? `${header}\n\n_No artifacts available; only the index summary is shown._`
+        : `${header}\n\n${sections.join('\n\n---\n\n')}`;
+    return { body, warnings };
+}
+function renderEntryHeader(entry) {
+    const lines = [
+        `# ${entry.title}`,
+        '',
+        `- id: ${entry.id}`,
+        `- session: ${entry.sessionId}`,
+        ...(entry.sliceId !== undefined ? [`- slice: ${entry.sliceId}`] : []),
+        `- type: ${entry.type}`,
+        `- outcome: ${entry.outcome}`,
+        `- updatedAt: ${entry.updatedAt}`,
+        `- lessonsLearned: ${entry.lessonsLearned}`,
+        ''
+    ];
+    if (entry.keyDecisions.length > 0) {
+        lines.push('## Key Decisions', '', ...entry.keyDecisions.map((decision) => `- ${decision}`), '');
+    }
+    if (entry.summary.length > 0) {
+        lines.push('## Summary', '', entry.summary, '');
+    }
+    return lines.join('\n');
+}
+export { loadRetrospectiveIndex };

package/dist/src/services/session/caller-binding-service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Caller-Binding Service (slice 020 — caller-keyed session binding).
+ *
+ * Each caller has its own on-disk binding file at
+ * `.peaks/_runtime/callers/<callerId>.json`. This service is the
+ * single read/write surface for that file. Legacy single-file bindings
+ * (`.peaks/_runtime/session.json` and `.peaks/.session.json`) remain
+ * readable for one minor release (M1 / M4); the read path falls back
+ * to them with a `legacy-fallback-used: true` flag.
+ *
+ * M2: legacy bindings resolve into a synthetic callerId of the form
+ * `legacy-<8hex-of-sha256(outerSessionId)>`, with `claudeSessionId`
+ * and `projectRoot` as fallback hash inputs. The synthetic id is
+ * permanent and recognisable by the `legacy-` prefix.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract.
+ */
+import { type CallerBinding } from './caller-id-types.js';
+/**
+ * On-disk location of the per-caller binding file. P4 invariant:
+ * the `callers/<callerId>.json` lives at `.peaks/_runtime/callers/`,
+ * the same root as the per-peak session dirs.
+ */
+export declare function getCallerBindingFile(projectRoot: string, callerId: string): string;
+/**
+ * On-disk location of the per-(peak, caller) active-skill file. D6:
+ * one file per (peakSessionId, callerId) pair; two callers bound to
+ * the same peak session never clobber each other.
+ */
+export declare function getActiveSkillFileForCaller(projectRoot: string, peakSessionId: string, callerId: string): string;
+/**
+ * Resolve a stable, deterministic callerId for a legacy single-file
+ * binding (M2). The hash input priority is:
+ *
+ *   1. `outerSessionId` (slice 018 stamped this on the per-peak
+ *      session.json for sessions created after the slice shipped).
+ *   2. `claudeSessionId` (legacy field name on pre-018 presence
+ *      files; honour the read side so v1.2.x data does not lose its
+ *      binding).
+ *   3. `projectRoot` (truly anonymous case: pre-018 sessions that
+ *      never recorded an outer / claude id).
+ *
+ * The synthetic id is `legacy-<first 8 hex chars of sha256(input)>`.
+ * 32 bits of entropy is enough for typical on-disk state
+ * (R1: <100 legacy peak sessions per project; the test asserts
+ * uniqueness across 1000 synthetic ids).
+ */
+export declare function synthesiseLegacyCallerId(input: string): string;
+/**
+ * Read a per-caller binding file. Returns `null` if the file does
+ * not exist, is malformed, or is for a different project (M1 back-compat
+ * read returns the legacy file but only after the per-caller file is
+ * absent).
+ */
+export declare function getCallerBinding(projectRoot: string, callerId: string): CallerBinding | null;
+/**
+ * Write or update a per-caller binding file. The caller is responsible
+ * for the binding object (callerId must match the file stem, peakSessionId
+ * must be a valid session id, projectRoot is canonicalized). Idempotent:
+ * re-writing the same callerId overwrites the file.
+ */
+export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
+/**
+ * Enumerate the per-caller binding files under
+ * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the
+ * raw filenames (so callers can list orphan / legacy files without
+ * re-reading).
+ */
+export declare function listCallerBindings(projectRoot: string): CallerBinding[];

package/dist/src/services/session/caller-binding-service.js

@@ -0,0 +1,148 @@
+/**
+ * Caller-Binding Service (slice 020 — caller-keyed session binding).
+ *
+ * Each caller has its own on-disk binding file at
+ * `.peaks/_runtime/callers/<callerId>.json`. This service is the
+ * single read/write surface for that file. Legacy single-file bindings
+ * (`.peaks/_runtime/session.json` and `.peaks/.session.json`) remain
+ * readable for one minor release (M1 / M4); the read path falls back
+ * to them with a `legacy-fallback-used: true` flag.
+ *
+ * M2: legacy bindings resolve into a synthetic callerId of the form
+ * `legacy-<8hex-of-sha256(outerSessionId)>`, with `claudeSessionId`
+ * and `projectRoot` as fallback hash inputs. The synthetic id is
+ * permanent and recognisable by the `legacy-` prefix.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { CALLER_ID_REGEX } from './caller-id-types.js';
+import { getSessionDir } from './getSessionDir.js';
+/**
+ * On-disk location of the per-caller binding file. P4 invariant:
+ * the `callers/<callerId>.json` lives at `.peaks/_runtime/callers/`,
+ * the same root as the per-peak session dirs.
+ */
+export function getCallerBindingFile(projectRoot, callerId) {
+    if (!CALLER_ID_REGEX.test(callerId)) {
+        // Defensive: a malformed callerId should never make it to disk.
+        // The caller is expected to validate via `resolveCallerId` first.
+        throw new Error(`getCallerBindingFile: invalid callerId "${callerId}"`);
+    }
+    return join(projectRoot, '.peaks', '_runtime', 'callers', `${callerId}.json`);
+}
+/**
+ * On-disk location of the per-(peak, caller) active-skill file. D6:
+ * one file per (peakSessionId, callerId) pair; two callers bound to
+ * the same peak session never clobber each other.
+ */
+export function getActiveSkillFileForCaller(projectRoot, peakSessionId, callerId) {
+    if (!CALLER_ID_REGEX.test(callerId)) {
+        throw new Error(`getActiveSkillFileForCaller: invalid callerId "${callerId}"`);
+    }
+    return join(getSessionDir(projectRoot, peakSessionId), `active-skill-${callerId}.json`);
+}
+/**
+ * Resolve a stable, deterministic callerId for a legacy single-file
+ * binding (M2). The hash input priority is:
+ *
+ *   1. `outerSessionId` (slice 018 stamped this on the per-peak
+ *      session.json for sessions created after the slice shipped).
+ *   2. `claudeSessionId` (legacy field name on pre-018 presence
+ *      files; honour the read side so v1.2.x data does not lose its
+ *      binding).
+ *   3. `projectRoot` (truly anonymous case: pre-018 sessions that
+ *      never recorded an outer / claude id).
+ *
+ * The synthetic id is `legacy-<first 8 hex chars of sha256(input)>`.
+ * 32 bits of entropy is enough for typical on-disk state
+ * (R1: <100 legacy peak sessions per project; the test asserts
+ * uniqueness across 1000 synthetic ids).
+ */
+export function synthesiseLegacyCallerId(input) {
+    const hash = createHash('sha256').update(input, 'utf8').digest('hex').slice(0, 8);
+    return `legacy-${hash}`;
+}
+/**
+ * Read a per-caller binding file. Returns `null` if the file does
+ * not exist, is malformed, or is for a different project (M1 back-compat
+ * read returns the legacy file but only after the per-caller file is
+ * absent).
+ */
+export function getCallerBinding(projectRoot, callerId) {
+    const bindingPath = getCallerBindingFile(projectRoot, callerId);
+    if (!existsSync(bindingPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(bindingPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.callerId !== 'string' || parsed.callerId !== callerId) {
+            return null;
+        }
+        if (typeof parsed.peakSessionId !== 'string' || parsed.peakSessionId.length === 0) {
+            return null;
+        }
+        if (typeof parsed.projectRoot !== 'string' || parsed.projectRoot.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write or update a per-caller binding file. The caller is responsible
+ * for the binding object (callerId must match the file stem, peakSessionId
+ * must be a valid session id, projectRoot is canonicalized). Idempotent:
+ * re-writing the same callerId overwrites the file.
+ */
+export function setCallerBinding(projectRoot, callerId, binding) {
+    if (binding.callerId !== callerId) {
+        throw new Error(`setCallerBinding: binding.callerId "${binding.callerId}" does not match callerId "${callerId}"`);
+    }
+    const bindingPath = getCallerBindingFile(projectRoot, callerId);
+    const dir = dirname(bindingPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const payload = {
+        ...binding,
+        projectRoot: resolve(binding.projectRoot)
+    };
+    writeFileSync(bindingPath, JSON.stringify(payload, null, 2), 'utf8');
+}
+/**
+ * Enumerate the per-caller binding files under
+ * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the
+ * raw filenames (so callers can list orphan / legacy files without
+ * re-reading).
+ */
+export function listCallerBindings(projectRoot) {
+    const dir = join(projectRoot, '.peaks', '_runtime', 'callers');
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        names = entries.filter((e) => e.isFile() && e.name.endsWith('.json')).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const callerId = name.replace(/\.json$/, '');
+        if (!CALLER_ID_REGEX.test(callerId))
+            continue;
+        const binding = getCallerBinding(projectRoot, callerId);
+        if (binding !== null) {
+            out.push(binding);
+        }
+    }
+    return out;
+}

package/dist/src/services/session/caller-id-types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Caller-Id Resolution types (slice 020 — caller-keyed session binding).
+ *
+ * The single shared `.peaks/_runtime/session.json` and
+ * `.peaks/_runtime/active-skill.json` files are replaced with per-caller
+ * layouts: `.peaks/_runtime/callers/<callerId>.json` and
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json`. The
+ * `callerId` is a generic identifier the calling platform declares
+ * itself (Claude Code via `CLAUDE_CODE_SESSION_ID`, future platforms
+ * via `PLATFORM_FALLBACKS`).
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7 + M1-M5).
+ */
+export type CallerIdSource = 'flag' | 'env' | 'fallback' | 'none';
+/**
+ * On-disk shape of `.peaks/_runtime/callers/<callerId>.json`. One file
+ * per caller; two callers may point to the same `peakSessionId` (D6).
+ */
+export interface CallerBinding {
+    /** Echo of the filename stem; matches D1 regex. */
+    callerId: string;
+    /** The peak session this caller is bound to. */
+    peakSessionId: string;
+    /** Absolute path to the project root, canonicalized. */
+    projectRoot: string;
+    /** ISO 8601 timestamp; stamped at first write. */
+    createdAt: string;
+    /** ISO 8601 timestamp; bumped on every `peaks <cmd>` that touches the binding. */
+    lastActivityAt: string;
+    /** Last skill that touched this binding, e.g. "peaks-solo". */
+    skill: string;
+    /** Last mode, e.g. "full-auto". */
+    mode: string;
+    /** Last gate, e.g. "startup". */
+    gate: string;
+}
+/**
+ * Per-(peakSessionId, callerId) presence record at
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json`. Each caller
+ * has its own file (D6); two callers bound to the same peak session
+ * never clobber each other's presence.
+ */
+export interface CallerSkillPresence {
+    callerId: string;
+    skill: string;
+    mode?: string;
+    gate?: string;
+    setAt: string;
+    lastHeartbeat?: string;
+}
+/**
+ * D1 callerId regex: ASCII letters, digits, dot, underscore, hyphen;
+ * 1-200 chars. Excludes path separators (Windows: `\`, Unix: `/`),
+ * NUL, control chars, whitespace, all other Unicode — callerId is
+ * embedded in a file path and must be portable across Windows / macOS
+ * / Linux.
+ */
+export declare const CALLER_ID_REGEX: RegExp;
+/**
+ * Thrown by `resolveCallerId` for two cases:
+ *
+ *   - `code: 'EX_USAGE'` (exit 64, D2): no callerId available
+ *     anywhere (flag/env/fallback all empty).
+ *   - `code: 'EX_DATAERR'` (exit 65, D5): resolved callerId does not
+ *     match D1's regex.
+ *
+ * The `source` field tells the user where the bad id came from
+ * (`flag` / `env` / `fallback` / `none`) so the error message points
+ * at the right thing to fix.
+ */
+export declare class CallerIdError extends Error {
+    readonly code: 'EX_USAGE' | 'EX_DATAERR';
+    readonly source: CallerIdSource;
+    readonly value: string | undefined;
+    constructor(code: 'EX_USAGE' | 'EX_DATAERR', source: CallerIdSource, message: string, value?: string);
+}

package/dist/src/services/session/caller-id-types.js

@@ -0,0 +1,46 @@
+/**
+ * Caller-Id Resolution types (slice 020 — caller-keyed session binding).
+ *
+ * The single shared `.peaks/_runtime/session.json` and
+ * `.peaks/_runtime/active-skill.json` files are replaced with per-caller
+ * layouts: `.peaks/_runtime/callers/<callerId>.json` and
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json`. The
+ * `callerId` is a generic identifier the calling platform declares
+ * itself (Claude Code via `CLAUDE_CODE_SESSION_ID`, future platforms
+ * via `PLATFORM_FALLBACKS`).
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7 + M1-M5).
+ */
+/**
+ * D1 callerId regex: ASCII letters, digits, dot, underscore, hyphen;
+ * 1-200 chars. Excludes path separators (Windows: `\`, Unix: `/`),
+ * NUL, control chars, whitespace, all other Unicode — callerId is
+ * embedded in a file path and must be portable across Windows / macOS
+ * / Linux.
+ */
+export const CALLER_ID_REGEX = /^[a-zA-Z0-9._-]{1,200}$/;
+/**
+ * Thrown by `resolveCallerId` for two cases:
+ *
+ *   - `code: 'EX_USAGE'` (exit 64, D2): no callerId available
+ *     anywhere (flag/env/fallback all empty).
+ *   - `code: 'EX_DATAERR'` (exit 65, D5): resolved callerId does not
+ *     match D1's regex.
+ *
+ * The `source` field tells the user where the bad id came from
+ * (`flag` / `env` / `fallback` / `none`) so the error message points
+ * at the right thing to fix.
+ */
+export class CallerIdError extends Error {
+    code;
+    source;
+    value;
+    constructor(code, source, message, value) {
+        super(message);
+        this.name = 'CallerIdError';
+        this.code = code;
+        this.source = source;
+        this.value = value;
+    }
+}

package/dist/src/services/session/index.d.ts

@@ -1,2 +1,6 @@
 export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
+export { resolveCallerId, type ResolveCallerIdOptions } from './resolve-caller-id.js';
+export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
+export { PLATFORM_FALLBACKS, type PlatformFallback } from './platform-fallbacks.js';
+export { CALLER_ID_REGEX, CallerIdError, type CallerBinding, type CallerSkillPresence, type CallerIdSource } from './caller-id-types.js';

package/dist/src/services/session/index.js

@@ -1,2 +1,7 @@
 export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
+// Slice 020 — caller-keyed session binding. The new canonical path.
+export { resolveCallerId } from './resolve-caller-id.js';
+export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
+export { PLATFORM_FALLBACKS } from './platform-fallbacks.js';
+export { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';

package/dist/src/services/session/platform-fallbacks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PLATFORM_FALLBACKS — the Level 3 fallback table for caller-id resolution.
+ *
+ * Slice 020 (D3): when neither `--caller-id` nor `PEAKS_CALLER_ID` is
+ * set, the resolver walks this table top-to-bottom and takes the
+ * first non-empty entry. Today there is exactly one entry: Claude
+ * Code (`CLAUDE_CODE_SESSION_ID`).
+ *
+ * To add a new platform (Cursor, Windsurf, peaks-ide, etc.):
+ *
+ *   1. Add a new entry below.
+ *   2. Bump the contract doc's A5 acceptance criterion
+ *      (`.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`).
+ *   3. Add a regression test that asserts the new entry resolves
+ *      correctly under D4 priority.
+ *
+ * The contract's A5 test (`tests/unit/services/session/caller-id-resolution.test.ts`)
+ * asserts `PLATFORM_FALLBACKS.length === 1`; adding a new entry will
+ * fail that test, forcing the contract bump.
+ *
+ * Adding an entry does NOT require code changes to read points
+ * (statusline, doctor, sc, session-info) — they all call the same
+ * resolver. Each entry is a one-line additive change.
+ */
+export interface PlatformFallback {
+    readonly envVar: string;
+    readonly description: string;
+    /** Semver this entry was added in (e.g. "1.3.7"). */
+    readonly addedIn: string;
+}
+export declare const PLATFORM_FALLBACKS: ReadonlyArray<PlatformFallback>;