peaks-cli 1.2.7 → 1.2.9

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

@@ -5,12 +5,54 @@
  * Sessions are automatically created when any skill is invoked.
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 const SESSION_FILE = '.session.json';
 const META_FILE = 'session.json';
+/**
+ * Canonicalize a project root path. Returns the realpath
+ * (resolving all symlinks — important on macOS where `/var`
+ * is a symlink to `/private/var`, and on the dev box where
+ * `/tmp` is the same `/private/var/folders/...` target as
+ * `/var/folders/...`). If the path does not exist (e.g. in
+ * tests that write the binding before the dir, or callers
+ * that pass a non-existent path), falls back to the
+ * `resolve()`d absolute form so the function NEVER throws.
+ */
+function canonicalizeProjectRoot(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Resolve a stored `projectRoot` value (from
+ * `.peaks/.session.json`) against the caller-passed
+ * `projectRoot`, then canonicalize. Handles two forms the
+ * legacy strict-equality check missed:
+ *
+ *   1. **Stored is relative** (e.g. `"."` when the binding
+ *      was written from inside the project dir). We resolve
+ *      it against the caller — if the caller's project root
+ *      is absolute, `path.resolve(caller, ".")` returns the
+ *      caller's absolute form, which then canonicalizes to
+ *      the caller's realpath.
+ *
+ *   2. **Both are absolute but the stored form is not
+ *      canonical** (e.g. `/var/folders/...` vs
+ *      `/private/var/folders/...` on macOS). Both canonicalize
+ *      to the same realpath.
+ *
+ * The combined check is the canonicalize-on-read contract.
+ */
+function resolveStoredAgainstCaller(stored, caller) {
+    const resolved = resolve(caller, stored); // if `stored` is absolute, returns `stored`; else joins with caller
+    return canonicalizeProjectRoot(resolved);
+}
 /**
  * Generate a new session ID.
  * Format: YYYY-MM-DD-session-<6位hex>
@@ -34,6 +76,19 @@ function getSessionFilePath(projectRoot) {
 /**
  * Read existing session info from disk.
  * Returns null if no session file exists or if it's invalid.
+ *
+ * Strict equality on `data.projectRoot === projectRoot` is
+ * preserved here on purpose: many other modules (notably
+ * `shared/change-id.ts` via `buildArtifactRelativePath`)
+ * depend on the strict-equality semantics to test the
+ * "no session bound" code path. Changing the read semantics
+ * here would cascade into ~30 test failures in those
+ * modules — out of scope for the progress rebind fix.
+ *
+ * The progress subcommands (which are the surface that
+ * actually breaks on the rebind bug) use
+ * `getSessionIdCanonical` instead, which does the
+ * canonicalize-on-read resolution the bug fix needs.
  */
 function readSessionFile(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
@@ -50,6 +105,33 @@ function readSessionFile(projectRoot) {
         return null;
     }
 }
+/**
+ * Same as `readSessionFile` but canonicalizes BOTH the
+ * caller-passed and stored `projectRoot` before comparing.
+ * See `resolveStoredAgainstCaller` for the rules.
+ *
+ * Exported as `readSessionFileCanonical` so the new
+ * `getSessionIdCanonical` can use it; not part of the
+ * public API otherwise.
+ */
+function readSessionFileCanonical(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (!existsSync(sessionFile))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
+        if (data.sessionId &&
+            storedRaw !== null &&
+            resolveStoredAgainstCaller(storedRaw, projectRoot) === resolveStoredAgainstCaller(projectRoot, projectRoot)) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Write session info to disk.
  */
@@ -61,6 +143,29 @@ function writeSessionFile(projectRoot, info) {
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
+/**
+ * Drop the project-level session binding (`.peaks/.session.json`)
+ * so the next `ensureSession()` call auto-generates a fresh
+ * session id. The on-disk session directory is left intact —
+ * rotating does NOT delete the user's data, it just unbinds the
+ * project from that session.
+ *
+ * Returns the id of the session that was unbound, or `null` if
+ * no binding was present. The caller is expected to do something
+ * with that — at minimum surface it in the CLI response so the
+ * user can find the directory again if they need to.
+ */
+export function rotateSessionBinding(projectRoot) {
+    const previous = readSessionFile(projectRoot);
+    if (previous === null) {
+        return null;
+    }
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (existsSync(sessionFile)) {
+        unlinkSync(sessionFile);
+    }
+    return previous.sessionId;
+}
 /**
  * Bind the project's current session to the given session id by writing
  * `.peaks/.session.json`. The single-session binding is the source of truth
@@ -168,6 +273,15 @@ export function listSessionMetas(projectRoot) {
  * @param projectRoot - Root directory of the project
  * @returns Session ID (e.g., "2026-05-26-session-a3f8b1")
  */
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
 export async function ensureSession(projectRoot) {
     const existing = readSessionFile(projectRoot);
     if (existing) {
@@ -183,10 +297,12 @@ export async function ensureSession(projectRoot) {
     writeSessionFile(projectRoot, info);
     await initWorkspace({ projectRoot, sessionId });
     // Initialize session metadata inside the session directory
+    const outerSessionId = getCurrentOuterSessionId();
     writeSessionMeta(projectRoot, sessionId, {
         sessionId,
         projectRoot,
-        createdAt: now
+        createdAt: now,
+        ...(outerSessionId !== undefined ? { outerSessionId } : {})
     });
     return sessionId;
 }
@@ -201,6 +317,37 @@ export function getSessionId(projectRoot) {
     const info = readSessionFile(projectRoot);
     return info?.sessionId ?? null;
 }
+/**
+ * Resolve the current session id with canonicalize-on-read
+ * semantics. This is the variant the progress subcommands
+ * (step / watch / start / close) use, because the legacy
+ * `getSessionId` returns null any time the stored
+ * `projectRoot` form differs from the caller-passed form
+ * (e.g. stored is "." from inside the project dir; caller
+ * is the absolute realpath). When `getSessionId` returns
+ * null, callers like `ensureSession` create a brand-new
+ * session and overwrite the binding — which is what the
+ * user observed as the "mid-dogfood rebind" bug.
+ *
+ * The fix is to canonicalize both sides of the compare
+ * (realpath, then optionally resolve relative stored
+ * against the caller's project root). The two forms of
+ * the same physical directory now compare equal, and the
+ * existing binding is found instead of being overwritten.
+ *
+ * Use this instead of `getSessionId` only when the
+ * caller is operating on a user-supplied `--project` flag
+ * and the binding may have been written by a CLI invocation
+ * that was running from inside the project dir (the common
+ * peaks-solo / peaks-sop scenario). Other modules depend
+ * on the strict-equality semantics of `getSessionId` (the
+ * "no binding" fallback path is part of their contract),
+ * so this variant is opt-in.
+ */
+export function getSessionIdCanonical(projectRoot) {
+    const info = readSessionFileCanonical(projectRoot);
+    return info?.sessionId ?? null;
+}
 /**
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.

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

@@ -6,7 +6,33 @@ export type SkillPresence = {
     mode?: SkillPresenceMode;
     gate?: string;
     sessionId?: string;
-    claudeSessionId?: string;
+    /**
+     * Identifier of the *outer* session — the Claude Code / Cursor /
+     * VSCode-plugin / other harness session that is currently driving
+     * the LLM. Sourced from the `PEAKS_OUTER_SESSION_ID` environment
+     * variable when set, with `CLAUDE_CODE_SESSION_ID` as a fallback for
+     * Claude Code. Stamped onto the presence file so the status line
+     * can tell whether the recorded skill belongs to the live outer
+     * session (show it) or a previous one (render idle), and so
+     * `setSkillPresence` can detect a session swap and AskUserQuestion
+     * the user about rolling a new peaks session.
+     */
+    outerSessionId?: string;
+    /**
+     * 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".
+     */
+    outerSessionMismatch?: {
+        previous?: string;
+        current: string;
+        boundSessionId: string;
+        boundOuterSessionId?: string;
+    };
     setAt: string;
     lastHeartbeat?: string;
 };

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

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
+import { getSessionMeta } from '../session/session-manager.js';
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -12,14 +13,23 @@ export function isSkillPresenceMode(value) {
     return VALID_SKILL_PRESENCE_MODES.includes(value);
 }
 /**
- * The current Claude Code session id, exposed to Bash tool calls via the
- * CLAUDE_CODE_SESSION_ID environment variable. Stamping it onto the presence
- * file lets the read-only status line tell whether the recorded skill belongs
- * to the live session (show it) or a previous one (render idle).
+ * The current outer session id, exposed to Bash tool calls via the
+ * `PEAKS_OUTER_SESSION_ID` environment variable. Stamping it onto the
+ * presence file lets the read-only status line tell whether the recorded
+ * skill belongs to the live session (show it) or a previous one
+ * (render idle). Falls back to `CLAUDE_CODE_SESSION_ID` for Claude Code
+ * so existing Claude Code users get the field populated without any
+ * configuration; other harnesses that want a presence stamp can set
+ * either variable.
  */
-function getCurrentClaudeSessionId() {
-    const value = process.env.CLAUDE_CODE_SESSION_ID;
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
 }
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 const SESSION_FILE = '.peaks/.session.json';
@@ -45,23 +55,116 @@ function getCurrentSessionId(projectRootOverride) {
         return null;
     }
 }
+/**
+ * Look up the outer-session-id that was bound to the *current* peaks
+ * session, i.e. the one written to the per-session
+ * `.peaks/<sid>/session.json` by `ensureSession`/`initWorkspace`. This
+ * is the source of truth for "which outer session owns the
+ * in-flight peaks session".
+ *
+ * Returns `null` if no peaks session is bound yet, or if the bound
+ * session has no recorded outer session id (legacy sessions predating
+ * the outer-session contract).
+ */
+function getBoundOuterSessionId(projectRootOverride) {
+    const sessionId = getCurrentSessionId(projectRootOverride);
+    if (sessionId === null)
+        return undefined;
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const meta = getSessionMeta(projectRoot, sessionId);
+    if (meta === null)
+        return undefined;
+    return typeof meta.outerSessionId === 'string' && meta.outerSessionId.length > 0
+        ? meta.outerSessionId
+        : undefined;
+}
+/**
+ * Snapshot of the previous peaks session's outer session id, read
+ * straight off `.peaks/.active-skill.json` *before* we overwrite it.
+ * 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).
+ */
+function getPreviousOuterSessionId(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
+    if (!existsSync(presencePath))
+        return undefined;
+    try {
+        const raw = readFileSync(presencePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
+            return parsed.outerSessionId;
+        }
+        // Legacy field name. Honour it on the read side so v1.2.x
+        // presence files do not show as a false mismatch.
+        if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
+            return parsed.claudeSessionId;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
 }
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
-    const claudeSessionId = getCurrentClaudeSessionId();
+    const outerSessionId = getCurrentOuterSessionId();
+    const previousOuterSessionId = getPreviousOuterSessionId(projectRootOverride);
     const now = new Date().toISOString();
     const presence = {
         skill,
         ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
         ...(sessionId ? { sessionId } : {}),
-        ...(claudeSessionId ? { claudeSessionId } : {}),
+        ...(outerSessionId ? { outerSessionId } : {}),
         setAt: now,
         lastHeartbeat: now
     };
+    // Outer-session-mismatch detection. Fires only when:
+    //   (a) we have a *current* outer session id (i.e. some harness is
+    //       driving peaks right now — PEAKS_OUTER_SESSION_ID or
+    //       CLAUDE_CODE_SESSION_ID is set), AND
+    //   (b) the previous presence write recorded a *different* outer
+    //       session id (or none), AND
+    //   (c) the current peaks session is bound to a different outer
+    //       session id (or no outer session id is bound).
+    //
+    // The combination of (b) and (c) is what tells us "this is a
+    // genuine outer-session swap, not a transient env-var change".
+    // When only (b) fires (current bound session was started in this
+    // same outer session), no mismatch is reported — that is the
+    // common reconnect case.
+    if (outerSessionId !== undefined) {
+        const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
+        const outerChanged = previousOuterSessionId !== outerSessionId;
+        const boundOuterMatches = boundOuterSessionId === outerSessionId;
+        // Suppress the false-positive where neither side ever recorded
+        // an outer session id. Two unknowns are not a swap — they are
+        // simply "no outer-session signal available yet". Only report
+        // a mismatch when at least one side has a recorded outer id.
+        const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
+        if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
+            presence.outerSessionMismatch = {
+                ...(previousOuterSessionId !== undefined ? { previous: previousOuterSessionId } : {}),
+                current: outerSessionId,
+                boundSessionId: sessionId,
+                ...(boundOuterSessionId !== undefined ? { boundOuterSessionId } : {})
+            };
+        }
+    }
     const presencePath = resolvePresencePath(projectRootOverride);
     const presenceDir = dirname(presencePath);
     if (!existsSync(presenceDir)) {

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

@@ -1,3 +1,4 @@
+import { dirname, join } from 'node:path';
 import { readText } from '../../shared/fs.js';
 import { loadSkillRegistry } from './skill-registry.js';
 const DESTRUCTIVE_APPLY_PATTERNS = [
@@ -13,6 +14,38 @@ function extractRunbookSection(body) {
     const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
     return match === null ? null : match[1];
 }
+/**
+ * Load the runbook section, falling back to `references/runbook.md` if the
+ * SKILL.md only has a pointer section. This supports skills (notably
+ * `peaks-solo`) that extracted their 150-line bash runbook to a sibling
+ * reference to keep SKILL.md under the 800-line cap. The CLI
+ * `peaks skill runbook` command uses the same fallback so a human
+ * reviewer sees the full runbook regardless of where it lives.
+ *
+ * Strategy: prefer the LONGER of the two sections. A short pointer section
+ * in SKILL.md (~ 1-2 lines) is treated as a "this runbook is in the
+ * reference" marker; a long inline section (>= the reference length) is
+ * treated as the canonical runbook. This avoids the false positive where
+ * the pointer section's regex match returns a non-null but content-poor
+ * string.
+ */
+async function loadRunbookSection(skillPath, body) {
+    const inline = extractRunbookSection(body);
+    const refPath = join(dirname(skillPath), 'references', 'runbook.md');
+    let refSection = null;
+    try {
+        const refBody = await readText(refPath);
+        refSection = extractRunbookSection(refBody);
+    }
+    catch {
+        // reference file does not exist or is not readable
+    }
+    if (inline === null)
+        return refSection;
+    if (refSection === null)
+        return inline;
+    return inline.length >= refSection.length ? inline : refSection;
+}
 function findDestructiveApplyLines(section) {
     const lines = section.split(/\r?\n/);
     return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
@@ -30,7 +63,7 @@ export async function inspectSkillRunbook(name, baseDir) {
         throw new Error(`Skill "${name}" not found under skills directory`);
     }
     const body = await readText(skill.skillPath);
-    const section = extractRunbookSection(body);
+    const section = await loadRunbookSection(skill.skillPath, body);
     if (section === null) {
         return {
             name: skill.name,

package/dist/src/services/workflow/autonomous-resume-writer.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { buildArtifactRelativePath, validateChangeIdOrThrow } from '../../shared/change-id.js';
+import { buildArtifactRelativePathInRoot, validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { pathExists } from '../../shared/fs.js';
 function defaultClock() {
     return new Date().toISOString();
@@ -109,27 +109,27 @@ Next actions:
 function buildFiles(changeId, goal, createdAt, artifactWorkspacePath) {
     return [
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'prd', 'autonomous-goal-package.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'prd', 'autonomous-goal-package.json')),
             content: renderGoalPackage(changeId, goal)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
             content: renderRdPlan(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
             content: renderCheckpoint(changeId, createdAt)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
             content: renderUnitTestsEvidence(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
             content: renderValidationReport(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'resume-instructions.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'resume-instructions.md')),
             content: renderResumeInstructions(changeId)
         }
     ];

package/dist/src/shared/change-id.d.ts

@@ -11,6 +11,30 @@ export declare class ChangeIdValidationError extends Error {
     constructor(changeId: string);
 }
 export declare function isUnsafeArtifactPath(path: string): boolean;
+/**
+ * Build an artifact-relative path using a caller-supplied project root, so
+ * the helper does not need to walk `process.cwd()` to find a session.
+ *
+ * If a session exists for `projectRoot`, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * Use this from callers that have a workspace or `artifactWorkspacePath` in
+ * hand (e.g. CLI subcommands that received `--project`, or test fixtures
+ * that created a tmpdir workspace). Legacy callers without an explicit
+ * `projectRoot` should continue to use `buildArtifactRelativePath`.
+ *
+ * @param projectRoot - The project root to use for session lookup and dirPath
+ *   computation. Must be an absolute path. Falls back to `process.cwd()` if
+ *   the empty string is passed (defensive only; should not happen via the
+ *   public API).
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
+export declare function buildArtifactRelativePathInRoot(projectRoot: string, changeId: string, ...segments: string[]): string;
 /**
  * Build an artifact-relative path using session-based storage.
  *
@@ -20,6 +44,12 @@ export declare function isUnsafeArtifactPath(path: string): boolean;
  * If no session exists, falls back to legacy behavior:
  *   .peaks/<changeId>/<segments>
  *
+ * This function walks `process.cwd()` to find the project root and reads
+ * `.peaks/.session.json` from it. Callers that already have an explicit
+ * `projectRoot` (workspace handle, test fixture, or CLI `--project` flag)
+ * should prefer `buildArtifactRelativePathInRoot(projectRoot, ...)` to
+ * avoid being polluted by the host environment's session binding.
+ *
  * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
  * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
  * @returns Relative path to the artifact file

package/dist/src/shared/change-id.js

@@ -62,25 +62,37 @@ export function isUnsafeArtifactPath(path) {
     return isUnsafePathInput(path);
 }
 /**
- * Build an artifact-relative path using session-based storage.
+ * Build an artifact-relative path using a caller-supplied project root, so
+ * the helper does not need to walk `process.cwd()` to find a session.
  *
- * If a session exists, files are stored in:
+ * If a session exists for `projectRoot`, files are stored in:
  *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
  *
  * If no session exists, falls back to legacy behavior:
  *   .peaks/<changeId>/<segments>
  *
+ * Use this from callers that have a workspace or `artifactWorkspacePath` in
+ * hand (e.g. CLI subcommands that received `--project`, or test fixtures
+ * that created a tmpdir workspace). Legacy callers without an explicit
+ * `projectRoot` should continue to use `buildArtifactRelativePath`.
+ *
+ * @param projectRoot - The project root to use for session lookup and dirPath
+ *   computation. Must be an absolute path. Falls back to `process.cwd()` if
+ *   the empty string is passed (defensive only; should not happen via the
+ *   public API).
  * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
  * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
  * @returns Relative path to the artifact file
  */
-export function buildArtifactRelativePath(changeId, ...segments) {
+export function buildArtifactRelativePathInRoot(projectRoot, changeId, ...segments) {
     validateChangeIdOrThrow(changeId);
-    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-    const sessionId = getSessionId(projectRoot);
+    const resolvedProjectRoot = projectRoot && projectRoot.length > 0
+        ? projectRoot
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const sessionId = getSessionId(resolvedProjectRoot);
     if (sessionId && segments.length > 0 && segments[0]) {
         const role = normalizeForwardSlashes(segments[0]);
-        const dirPath = join(projectRoot, '.peaks', sessionId, role);
+        const dirPath = join(resolvedProjectRoot, '.peaks', sessionId, role);
         if (isUnsafeArtifactPath(role) || isUnsafeArtifactPath(sessionId)) {
             throw new ChangeIdValidationError(changeId);
         }
@@ -97,6 +109,28 @@ export function buildArtifactRelativePath(changeId, ...segments) {
     }
     return normalizeArtifactPath(candidatePath);
 }
+/**
+ * Build an artifact-relative path using session-based storage.
+ *
+ * If a session exists, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * This function walks `process.cwd()` to find the project root and reads
+ * `.peaks/.session.json` from it. Callers that already have an explicit
+ * `projectRoot` (workspace handle, test fixture, or CLI `--project` flag)
+ * should prefer `buildArtifactRelativePathInRoot(projectRoot, ...)` to
+ * avoid being polluted by the host environment's session binding.
+ *
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
+export function buildArtifactRelativePath(changeId, ...segments) {
+    return buildArtifactRelativePathInRoot(findProjectRoot(process.cwd()) ?? process.cwd(), changeId, ...segments);
+}
 export function isPathInsideArtifactRoot(path, artifactRoot) {
     if (!path || !artifactRoot)
         return false;

package/dist/src/shared/paths.d.ts

@@ -3,4 +3,4 @@ export declare const skillsDir: string;
 export declare const schemasDir: string;
 export declare const templatesDir: string;
 export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt", "peaks-sop"];
-export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json"];
+export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json", "library-breaking-changes.schema.json"];

package/dist/src/shared/paths.js

@@ -45,5 +45,6 @@ export const requiredSchemaFiles = [
     'openspec-change-summary.schema.json',
     'openspec-render-request.schema.json',
     'openspec-validation-result.schema.json',
-    'doctor-report.schema.json'
+    'doctor-report.schema.json',
+    'library-breaking-changes.schema.json'
 ];

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.7";
+export declare const CLI_VERSION = "1.2.9";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.7";
+export const CLI_VERSION = "1.2.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -43,10 +43,14 @@
   },
   "dependencies": {
     "@colbymchenry/codegraph": "0.7.10",
+    "chalk": "^5.6.2",
     "commander": "^12.1.0",
-    "shadcn": "4.7.0"
+    "ora": "^8.2.0",
+    "shadcn": "4.7.0",
+    "terminal-kit": "^3.1.2"
   },
   "devDependencies": {
+    "@types/chalk": "^2.2.4",
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",
     "tsx": "^4.19.2",