peaks-cli 1.3.6 → 1.3.8

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

package/dist/src/services/session/platform-fallbacks.js

@@ -0,0 +1,35 @@
+/**
+ * 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 const PLATFORM_FALLBACKS = [
+    {
+        envVar: 'CLAUDE_CODE_SESSION_ID',
+        description: 'Claude Code session id',
+        addedIn: '1.3.7'
+    }
+    // Future entries (do NOT add without bumping the contract's A5):
+    // { envVar: 'CURSOR_SESSION_ID', description: 'Cursor session id', addedIn: 'TBD' },
+    // { envVar: 'WINDSURF_SESSION_ID', description: 'Windsurf session id', addedIn: 'TBD' },
+    // { envVar: 'PEAKS_IDE_SESSION_ID', description: 'peaks-ide session id', addedIn: 'TBD' },
+];

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

@@ -0,0 +1,57 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CallerIdError } from './caller-id-types.js';
+export { CallerIdError };
+export interface ResolveCallerIdOptions {
+    /**
+     * The `--caller-id <id>` flag value (per-invocation override).
+     * D4 priority level 1: flag wins.
+     */
+    flagValue?: string;
+    /**
+     * Override for the `PEAKS_CALLER_ID` environment variable. D4
+     * priority level 2: env wins. Defaults to `process.env.PEAKS_CALLER_ID`.
+     * The override exists so tests can run without mutating process.env.
+     */
+    envOverride?: string;
+    /**
+     * The env object to read. Defaults to `process.env`. Exists so
+     * tests can drive Level 3 (platform fallback) without mutating
+     * process.env.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export declare function resolveCallerId(opts?: ResolveCallerIdOptions): string;

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

@@ -0,0 +1,88 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';
+import { PLATFORM_FALLBACKS } from './platform-fallbacks.js';
+// Re-export for CLI consumers (avoids a second import line).
+export { CallerIdError };
+/**
+ * Check whether `value` looks like a callerId (non-empty, matches D1).
+ * Returns the trimmed value if so, undefined otherwise. Does not throw.
+ */
+function isNonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Read a single platform-fallback env var from `env`. Returns the
+ * non-empty trimmed value or `undefined`. Logs nothing.
+ */
+function readPlatformFallback(env) {
+    for (let i = 0; i < PLATFORM_FALLBACKS.length; i++) {
+        const candidate = env[PLATFORM_FALLBACKS[i].envVar];
+        if (isNonEmpty(candidate)) {
+            return { value: candidate, index: i };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate `value` against D1's regex. Returns the value on success,
+ * throws `CallerIdError` (EX_DATAERR, exit 65) on failure.
+ */
+function validateCallerId(value, source) {
+    if (!CALLER_ID_REGEX.test(value)) {
+        throw new CallerIdError('EX_DATAERR', source, `Invalid caller id "${value}" (source: ${source}). callerId must match ^[a-zA-Z0-9._-]{1,200}$.`, value);
+    }
+    return value;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export function resolveCallerId(opts = {}) {
+    const env = opts.env ?? process.env;
+    // D4 level 1: flag value
+    if (isNonEmpty(opts.flagValue)) {
+        return validateCallerId(opts.flagValue, 'flag');
+    }
+    // D4 level 2: env var
+    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : env.PEAKS_CALLER_ID;
+    if (isNonEmpty(envValue)) {
+        return validateCallerId(envValue, 'env');
+    }
+    // D4 level 3: PLATFORM_FALLBACKS table (top-to-bottom)
+    const fallback = readPlatformFallback(env);
+    if (fallback !== undefined) {
+        return validateCallerId(fallback.value, 'fallback');
+    }
+    // D4 level 4: D2 fires — no callerId available
+    throw new CallerIdError('EX_USAGE', 'none', 'No caller id available. Set PEAKS_CALLER_ID or pass --caller-id.');
+}

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

@@ -89,7 +89,62 @@ export declare function setSessionTitle(projectRoot: string, sessionId: string,
  * release) but is not authoritative.
  */
 export declare function listSessionMetas(projectRoot: string): SessionMeta[];
+export type EnsureSessionOptions = {
+    /**
+     * When `true`, suppress the outer-session-mismatch auto-rotation.
+     * The caller wants today's "stamp the field, do not rotate" behaviour
+     * even when the outer session id has changed. Used by
+     * `peaks workspace init --no-rotate-on-outer-mismatch`.
+     */
+    skipRotateOnOuterMismatch?: boolean;
+};
+/**
+ * Result of `ensureSessionWithRotation`. When the bound session was
+ * rotated because the outer session id had changed, `previousSessionId`
+ * is the id of the unbound session and `rotationReason` is the structured
+ * reason code the CLI surfaces in its JSON envelope.
+ */
+export type EnsureSessionResult = {
+    sessionId: string;
+    previousSessionId: string | null;
+    rotationReason: 'outer-session-mismatch' | null;
+};
 export declare function ensureSession(projectRoot: string): Promise<string>;
+/**
+ * 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 declare function ensureSessionWithRotation(projectRoot: string, options?: EnsureSessionOptions): Promise<EnsureSessionResult>;
 /**
  * Get the current session ID without creating a new one.
  * Returns null if no session exists.

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

@@ -421,6 +421,74 @@ export async function ensureSession(projectRoot) {
     });
     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
+    };
+}
 /**
  * Get the current session ID without creating a new one.
  * Returns null if no session exists.

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -22,10 +22,16 @@ export type SkillPresence = {
      * Set by `setSkillPresence` when the outer session id changed
      * between the last presence write and this one AND the bound
      * peaks session has a different (or no) recorded outer session id.
-     * The field is informational only — `setSkillPresence` does not
-     * roll a new session on its own. peaks-solo's Step 0 reads the
-     * field off the presence file and turns it into an
-     * AskUserQuestion: "Start a new peaks session / Keep this one".
+     *
+     * As of slice 018 (auto-roll on outer-mismatch), the field is
+     * informational only — it tells the statusline and any log /
+     * observability consumer that an outer-session swap was observed
+     * on the previous heartbeat. The actual binding rotation is
+     * performed by `ensureSessionWithRotation` (slice 018), not by
+     * `setSkillPresence`. `peaks-solo`'s Step 0 used to read this
+     * field and turn it into an AskUserQuestion; that ask is no
+     * longer needed because the rotation already happened by the time
+     * the skill is invoked.
      */
     outerSessionMismatch?: {
         previous?: string;
@@ -37,6 +43,17 @@ export type SkillPresence = {
     lastHeartbeat?: string;
 };
 export declare function exportSkillPresence(projectRootOverride?: string): string;
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export declare function setSkillPresenceForCaller(projectRootOverride: string, callerId: string, peakSessionId: string, skill: string, mode?: string, gate?: string): SkillPresence;
 export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
 export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
 export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;

package/dist/src/services/skills/skill-presence-service.js

@@ -124,18 +124,23 @@ function getBoundOuterSessionId(projectRootOverride) {
  * Used to detect "the LLM just opened a fresh outer session" — if
  * the previously-recorded outer session id differs from the one we
  * are about to stamp, the user probably closed the previous outer
- * session and is now driving peaks from a new one. We do NOT auto-
- * roll a new peaks session (that is destructive — it would leave
- * the in-flight session with no LLM watching it). Instead we emit
- * a structured `outerSessionMismatch` field on the presence
- * envelope, and peaks-solo's Step 0 turns that into an
- * AskUserQuestion. The user can opt to keep the current session
- * (most common when the swap is a no-op reconnect) or to roll a
- * fresh session (when the new outer session is genuinely a new
- * task).
+ * session and is now driving peaks from a new one.
  *
- * Reads from `.peaks/_runtime/active-skill.json` first; falls back to
- * the legacy `.peaks/.active-skill.json` for one minor release.
+ * As of slice 018 (auto-roll on outer-mismatch), the actual rotation
+ * is `ensureSessionWithRotation`'s job, not this one. The presence
+ * service still emits the structured `outerSessionMismatch` field on
+ * the presence envelope (useful for the statusline to render a stale
+ * marker and for the QA / log consumers to know an outer-session swap
+ * happened), but it no longer carries the implicit "ask the user"
+ * promise — `peaks-solo`'s Step 0 no longer needs to surface an
+ * AskUserQuestion, because the rotation already fired by the time the
+ * skill is invoked.
+ *
+ * `getPreviousOuterSessionId` keeps its read-side role: it powers the
+ * informational `outerSessionMismatch` field below and the legacy
+ * `claudeSessionId` back-compat. Reads from
+ * `.peaks/_runtime/active-skill.json` first; falls back to the
+ * legacy `.peaks/.active-skill.json` for one minor release.
  */
 function getPreviousOuterSessionId(projectRootOverride) {
     const result = readSkillPresenceBackCompat(projectRootOverride);
@@ -155,6 +160,65 @@ function getPreviousOuterSessionId(projectRootOverride) {
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
 }
+// ============================================================================
+// Slice 020 — caller-keyed active-skill marker (D6).
+// ============================================================================
+//
+// Today's per-project active-skill marker (`.peaks/_runtime/active-skill.json`)
+// races when multiple Claude Code windows (or different platforms) drive the
+// same project concurrently. Slice 020 introduces a per-caller file at
+// `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Two callers
+// bound to the same peak session never clobber each other.
+//
+// The single-file marker is RETAINED for one minor release as read-only
+// back-compat (M1, M4). The new write path is `setSkillPresenceForCaller`;
+// the legacy `setSkillPresence` is now a thin wrapper that synthesises a
+// legacy callerId from `process.env.CLAUDE_CODE_SESSION_ID` (or
+// `projectRoot` for the truly-anonymous case) and delegates.
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSessionId, skill, mode, gate) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const now = new Date().toISOString();
+    const presence = {
+        skill,
+        ...(validatedMode ? { mode: validatedMode } : {}),
+        ...(gate ? { gate } : {}),
+        ...(peakSessionId ? { sessionId: peakSessionId } : {}),
+        ...(callerId ? { outerSessionId: callerId } : {}),
+        setAt: now,
+        lastHeartbeat: now
+    };
+    const presencePath = getActiveSkillFileForCallerPath(resolveProjectRoot(projectRootOverride), peakSessionId, callerId);
+    const presenceDir = dirname(presencePath);
+    if (!existsSync(presenceDir)) {
+        mkdirSync(presenceDir, { recursive: true });
+    }
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: bring the memory store into existence for
+    // fresh projects. Same fail-open contract as the legacy path.
+    ensureMemoryBootstrap(resolveProjectRoot(projectRootOverride));
+    return presence;
+}
+/**
+ * Compute the per-caller active-skill file path. Re-exported for test
+ * ergonomics; canonical path lives in
+ * `src/services/session/caller-binding-service.ts` but inlined here to
+ * avoid a circular import (`caller-binding-service` reads
+ * `skill-presence-service` for the `setCallerBinding` integration in
+ * future slices; the inverse import would deadlock).
+ */
+function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
+    return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
+}
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);