peaks-cli 1.3.7 → 1.3.8

package/dist/src/cli/commands/core-artifact-commands.js

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { createArtifactInitPlan, getArtifactStatus, createGuidedArtifactSetup } from '../../services/artifacts/artifact-service.js';
 import { getArtifactWorkspaceStatus, planArtifactSync } from '../../services/artifacts/workspace-service.js';
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../services/memory/project-memory-service.js';
@@ -206,26 +208,129 @@ export function registerCoreAndArtifactCommands(program, io) {
     });
     addJsonOption(session
         .command('info [sessionId]')
-        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive).')
-        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')).action(async (sessionId, options) => {
-        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-        // Slice 007 — sub-agent session sharing. A sub-agent that does
-        // not know the parent's sid reads it from the binding via
-        // `peaks session info --active`. The call uses the
-        // canonicalize-on-read path so a stored "projectRoot: '.'" and a
-        // caller-passed absolute realpath both resolve to the same
-        // binding. Without this primitive the sub-agent has no way to
-        // discover the parent sid short of scanning the filesystem.
+        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive). Slice 021: --active is the SOLE authoritative way to look up the active session id; the on-disk file path is internal and must NOT be `cat`-ed directly.')
+        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd). Slice 021: lets sub-agents skip the cwd heuristic and look up the binding for a specific repo.')
+        // Slice 020 — caller-keyed session binding. The --caller-id flag
+        // overrides the per-process PEAKS_CALLER_ID env var and the
+        // PLATFORM_FALLBACKS table (D4 priority). The resolved callerId is
+        // surfaced in the JSON envelope so callers can confirm what was
+        // resolved without re-deriving it.
+        .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). When set, the response envelope includes the resolved callerId.')).action(async (sessionId, options) => {
+        // Slice 021: --project wins; otherwise the git-root / cwd fallback
+        // (matches the pre-021 behaviour so the existing slice-020 / slice-007
+        // sub-agent flow keeps working unchanged).
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        // Slice 020 — resolve the callerId up front when the flag was passed.
+        // We use `resolveCallerId` for D1/D5 validation; an invalid flag
+        // throws CallerIdError (D5 → exit 65). A missing flag and no env
+        // and no fallback also throws (D2 → exit 64). The resolved id is
+        // surfaced in the envelope so the caller can audit.
+        if (options.callerId !== undefined) {
+            const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
+            let callerId;
+            try {
+                callerId = resolveCallerId({ flagValue: options.callerId });
+            }
+            catch (error) {
+                if (error instanceof CallerIdError) {
+                    const code = error.code === 'EX_USAGE' ? 64 : 65;
+                    printResult(io, fail('session.info', 'CALLER_ID_INVALID', error.message, { source: error.source }, [`Set --caller-id to a value matching ^[a-zA-Z0-9._-]{1,200}$`, 'Or set PEAKS_CALLER_ID env var (or CLAUDE_CODE_SESSION_ID for Claude Code)']), options.json);
+                    process.exitCode = code;
+                    return;
+                }
+                throw error;
+            }
+            // Surface the resolved id in the envelope. When --active is also
+            // passed, look up the binding for this callerId; otherwise
+            // just emit the resolved id so the caller knows what was used.
+            if (options.active === true) {
+                const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+                const { getCallerBinding } = await import('../../services/session/caller-binding-service.js');
+                const activeSid = getSessionIdCanonical(projectRoot);
+                const callerBinding = getCallerBinding(projectRoot, callerId);
+                // Slice 021: source is the enum that the unified --active primitive
+                // reports. Callers / migration tooling can detect pre-migration trees
+                // by inspecting `source === 'legacy'`.
+                const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                    ? 'canonical'
+                    : 'legacy';
+                printResult(io, ok('session.info', {
+                    active: true,
+                    sessionId: activeSid,
+                    callerId,
+                    callerBindingPeakSessionId: callerBinding?.peakSessionId ?? null,
+                    source: bindingSource
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('session.info', { callerId, note: '--caller-id resolved; pass --active to also look up the bound peak session' }), options.json);
+            return;
+        }
+        // Slice 007 + slice 021 — sub-agent session sharing. A sub-agent that
+        // does not know the parent's sid reads it from the binding via
+        // `peaks session info --active`. Slice 021 turned this into the
+        // SOLE authoritative discovery primitive: it composes on
+        // getSessionIdCanonical (canonicalize-on-read; handles the stored
+        // "projectRoot: '.'" vs caller-passed absolute realpath mismatch
+        // that the F22 fix addressed) AND falls through to getSessionId
+        // (strict-equality) for callers on the original contract. NEITHER
+        // path may call ensureSession() — that would side-effect-create a
+        // fresh binding on miss, erasing the "no active session" signal
+        // sub-agents rely on.
         if (options.active === true) {
             // Import lazily to avoid a cycle with workspace-commands.
-            const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
-            const activeSid = getSessionIdCanonical(projectRoot);
+            const { getSessionIdCanonical, getSessionId } = await import('../../services/session/session-manager.js');
+            // 1. Canonicalize-on-read first.
+            let activeSid = getSessionIdCanonical(projectRoot);
+            // 2. Fall through to the strict-equality reader if the canonical
+            //    miss is a projectRoot-form mismatch (e.g. the binding was
+            //    written with the absolute realpath but the caller's form
+            //    normalizes differently). The 2-read fan-out mirrors the
+            //    fallback ensureSession() uses.
+            if (activeSid === null) {
+                activeSid = getSessionId(projectRoot);
+            }
             if (activeSid === null) {
-                printResult(io, fail('session.info', 'NO_ACTIVE_BINDING', 'No canonical session binding at .peaks/_runtime/session.json', { projectRoot }, ['Run `peaks workspace init` or `peaks skill presence:set` to anchor a session']), options.json);
+                // 3. No binding at all — fail loudly, NO crash, NO side-effect,
+                //    exit 1, message must point at `peaks workspace init`
+                //    (the canonical "first action" command, not the legacy
+                //    "or `peaks skill presence:set`" hedge that the pre-021
+                //    wording used — presence:set would also need a binding to
+                //    resolve the parent sid, so it's not actually a bootstrap
+                //    path).
+                printResult(io, fail('session.info', 'NO_ACTIVE_SESSION', 'No session bound. Run `peaks workspace init --project <repo> --json` to bind one.', { projectRoot }, [`peaks workspace init --project ${projectRoot} --json`]), options.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('session.info', { active: true, sessionId: activeSid, source: '.peaks/_runtime/session.json' }), options.json);
+            // 4. Determine the on-disk source so callers (and future
+            //    migration tooling) can detect pre-migration trees. The
+            //    canonical file is preferred when both exist (slice 005
+            //    contract).
+            const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                ? 'canonical'
+                : 'legacy';
+            // Slice 021: when only the legacy back-compat path is present,
+            // surface a warning so callers (and humans tailing the JSON)
+            // see "this tree has not been reconciled to the canonical
+            // home yet". The warning is informational; the binding is
+            // still valid for one minor release (slice 005 / 006
+            // contract). `warnings` is a top-level envelope field, not a
+            // data field, so it goes through ok()'s 3rd positional arg.
+            const legacyWarnings = bindingSource === 'legacy'
+                ? ['Read from legacy back-compat path .peaks/.session.json. Run `peaks workspace reconcile --apply` to migrate to the canonical home (.peaks/_runtime/session.json).']
+                : [];
+            printResult(io, ok('session.info', {
+                active: true,
+                sessionId: activeSid,
+                bindingPath: bindingSource === 'canonical'
+                    ? join(projectRoot, '.peaks', '_runtime', 'session.json')
+                    : join(projectRoot, '.peaks', '.session.json'),
+                projectRoot,
+                source: bindingSource
+            }, legacyWarnings), options.json);
             return;
         }
         if (sessionId === undefined) {

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

@@ -36,7 +36,12 @@ export function registerRequestCommands(program, io) {
         .requiredOption('--project <path>', 'target project root')
         .option('--session-id <session>', 'override the default date-stamped session id')
         .option('--apply', 'write the artifact file (default: preview only)')
-        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)).action(async (options) => {
+        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)
+        // Slice 020 — caller-keyed session binding. Per-invocation override
+        // (D4 priority level 1). When set, the resolved callerId is surfaced
+        // in the JSON envelope; the on-disk artifact records it in the
+        // artifact body so future reads know which caller produced it.
+        .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). The resolved callerId is stamped on the artifact body and surfaced in the response envelope.')).action(async (options) => {
         try {
             const serviceOptions = {
                 role: options.role,
@@ -57,6 +62,31 @@ export function registerRequestCommands(program, io) {
             if (options.type !== undefined) {
                 serviceOptions.requestType = options.type;
             }
+            // Slice 020.1 — resolve the callerId via D4 priority (flag > env >
+            // platform fallback > reject). The CLI integration layer is the
+            // single entry point for the resolver; we do not pre-judge whether
+            // the caller passed a flag. D2 (no callerId available) and D5
+            // (regex fail) both surface as `CALLER_ID_INVALID` with the inner
+            // `CallerIdError.source` propagated for caller-side audit.
+            const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
+            try {
+                const callerId = resolveCallerId(options.callerId !== undefined ? { flagValue: options.callerId } : {});
+                serviceOptions.callerId = callerId;
+            }
+            catch (error) {
+                if (error instanceof CallerIdError) {
+                    // D2 (EX_USAGE, exit 64) = nothing usable; D5 (EX_DATAERR, exit 65)
+                    // = something was passed but did not match the D1 regex.
+                    const code = error.code === 'EX_USAGE' ? 64 : 65;
+                    printResult(io, fail('request.init', 'CALLER_ID_INVALID', error.message, { source: error.source }, [
+                        'Set --caller-id to a value matching ^[a-zA-Z0-9._-]{1,200}$',
+                        'Or set PEAKS_CALLER_ID env var (or CLAUDE_CODE_SESSION_ID for Claude Code)'
+                    ]), options.json);
+                    process.exitCode = code;
+                    return;
+                }
+                throw error;
+            }
             const result = await createRequestArtifact(serviceOptions);
             printResult(io, ok('request.init', result, [], result.applied ? [] : [`Re-run with --apply to write ${result.path}`]), options.json);
         }

package/dist/src/services/artifacts/request-artifact-service.d.ts

@@ -17,6 +17,16 @@ export type CreateRequestArtifactOptions = {
     apply?: boolean;
     requestType?: RequestType;
     clock?: () => string;
+    /**
+     * Slice 020 — caller-keyed session binding. The callerId that initiated
+     * this artifact creation (resolved via `resolveCallerId` by the CLI).
+     * Recorded in the JSON envelope and on the artifact body's frontmatter
+     * so a future reader knows which caller produced it. The caller-keyed
+     * binding file itself is at `.peaks/_runtime/callers/<callerId>.json`;
+     * the per-caller active-skill marker is at
+     * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6).
+     */
+    callerId?: string;
 };
 export type CreateRequestArtifactResult = {
     role: RequestArtifactRole;
@@ -25,6 +35,12 @@ export type CreateRequestArtifactResult = {
     path: string;
     content: string;
     applied: boolean;
+    /**
+     * Slice 020 — caller-keyed session binding. The resolved callerId
+     * (D4 priority: flag > env > platform fallback) when --caller-id
+     * was passed. Omitted from the result when no callerId was set.
+     */
+    callerId?: string;
 };
 export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
 export type RequestArtifactSummary = {

package/dist/src/services/artifacts/request-artifact-service.js

@@ -374,7 +374,15 @@ export async function createRequestArtifact(options) {
     const path = join(requestsDir, filename);
     const content = renderTemplate(options.role, options.requestId, changeId, sessionId, timestamp, requestType);
     if (options.apply !== true) {
-        return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: false };
+        return {
+            role: options.role,
+            requestId: options.requestId,
+            sessionId,
+            path,
+            content,
+            applied: false,
+            ...(options.callerId !== undefined ? { callerId: options.callerId } : {})
+        };
     }
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
@@ -390,7 +398,15 @@ export async function createRequestArtifact(options) {
             await writeFile(initiatedPath, '', 'utf8');
         }
     }
-    return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: true };
+    return {
+        role: options.role,
+        requestId: options.requestId,
+        sessionId,
+        path,
+        content,
+        applied: true,
+        ...(options.callerId !== undefined ? { callerId: options.callerId } : {})
+    };
 }
 function extractMetadata(markdown) {
     let state = 'unknown';

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>;