peaks-cli 1.3.0 → 1.3.2

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

@@ -6,6 +6,7 @@
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdir as mkdirAsync } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
@@ -179,9 +180,16 @@ function writeSessionFile(projectRoot, info) {
  * no binding was present. The caller is expected to do something
  * with that — at minimum surface it in the CLI response so the
  * user can find the directory again if they need to.
+ *
+ * Slice 008 (F22 fix): the read uses the canonicalize-on-read
+ * variant so a binding written with `projectRoot: "."` (relative
+ * form, anchored from inside the project dir) is still found when
+ * the caller passes the absolute realpath. Pre-F22 the
+ * strict-equality read returned null in that case, and rotate
+ * silently no-op'd (the CLI reported "no prior binding").
  */
 export function rotateSessionBinding(projectRoot) {
-    const previous = readSessionFile(projectRoot);
+    const previous = readSessionFileCanonical(projectRoot);
     if (previous === null) {
         return null;
     }
@@ -220,7 +228,14 @@ export function setCurrentSessionBinding(projectRoot, sessionId) {
     return info;
 }
 function getMetaFilePath(projectRoot, sessionId) {
-    return join(projectRoot, '.peaks', sessionId, META_FILE);
+    // As of slice 2026-06-06-session-layout-canonicalize, the per-session
+    // `session.json` (the file written by `setSessionMeta`) lives at the
+    // canonical runtime home `.peaks/_runtime/<sid>/session.json`, NOT
+    // at the top-level `.peaks/<sid>/session.json` (which would imply
+    // the legacy session-scoped layout and conflict with the workspace
+    // service's `_runtime/<sid>/` invariant). The migration in slice
+    // 003 moved any top-level meta files into the runtime home.
+    return join(projectRoot, '.peaks', '_runtime', sessionId, META_FILE);
 }
 function readSessionMeta(projectRoot, sessionId) {
     const metaPath = getMetaFilePath(projectRoot, sessionId);
@@ -240,7 +255,9 @@ function readSessionMeta(projectRoot, sessionId) {
 }
 function writeSessionMeta(projectRoot, sessionId, meta) {
     const metaPath = getMetaFilePath(projectRoot, sessionId);
-    const metaDir = join(projectRoot, '.peaks', sessionId);
+    // As of slice 003, the meta file lives at `.peaks/_runtime/<sid>/session.json`.
+    // The parent dir of that file is the canonical runtime session dir.
+    const metaDir = dirname(metaPath);
     if (!existsSync(metaDir)) {
         mkdirSync(metaDir, { recursive: true });
     }
@@ -281,23 +298,67 @@ export function setSessionTitle(projectRoot, sessionId, title) {
 /**
  * List all session directories under .peaks with their metadata.
  * Returns sessions sorted by sessionId descending (most recent first).
+ *
+ * As of slice 2026-06-06-session-layout-canonicalize the session
+ * dirs live at the canonical runtime home `.peaks/_runtime/<sid>/`.
+ * The legacy top-level layout is read for back-compat (one minor
+ * release) but is not authoritative.
  */
 export function listSessionMetas(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    const entries = readdirSync(peaksRoot, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
-        .map((entry) => {
-        const meta = readSessionMeta(projectRoot, entry.name);
-        return meta ?? {
-            sessionId: entry.name,
-            projectRoot,
-            createdAt: ''
-        };
-    })
-        .sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const meta = readSessionMeta(projectRoot, name);
+            result.push(meta ?? { sessionId: name, projectRoot, createdAt: '' });
+        }
+    };
+    // Canonical home first, then the legacy top-level (back-compat).
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    result.sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+    return result;
+}
+/**
+ * Back-compat read for the legacy top-level meta file (the one that
+ * pre-slice 003 trees still have at `.peaks/<sid>/session.json`).
+ * Kept as a separate helper so the canonical reader is the default.
+ */
+function readSessionMetaCompat(peaksRoot, sessionId) {
+    const metaPath = join(peaksRoot, sessionId, META_FILE);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Get or create the current session for a project.
@@ -321,6 +382,26 @@ export async function ensureSession(projectRoot) {
     if (existing) {
         return existing.sessionId;
     }
+    // Slice 007 — sub-agent session sharing. When the strict-equality
+    // read returns null (e.g. the binding was written with the relative
+    // form "." from inside the project dir, but the caller passes the
+    // absolute realpath), fall through to the canonical-fallback read.
+    // `ensureSession` is a session-creating primitive — its caller
+    // wants the existing binding if one exists, even if the projectRoot
+    // forms differ. Without this fallback, a sub-agent that anchors via
+    // `cd <repo> && peaks skill presence:set` and then runs
+    // `peaks request init --project <abs-path>` would auto-generate a
+    // new session and create an orphan dir.
+    //
+    // The strict-equality read is preserved for other modules
+    // (notably `shared/change-id.ts` via `buildArtifactRelativePath`)
+    // that depend on the "no session bound" code path — switching the
+    // default would cascade into ~30 test failures in those modules.
+    // The canonical-fallback is opt-in for `ensureSession` only.
+    const canonical = getSessionIdCanonical(projectRoot);
+    if (canonical !== null) {
+        return canonical;
+    }
     const sessionId = generateSessionId();
     const now = new Date().toISOString();
     const info = {
@@ -386,31 +467,60 @@ export function getSessionIdCanonical(projectRoot) {
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.
  *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/<sid>/` is the back-compat read fallback only.
+ *
  * @param projectRoot - Root directory of the project
- * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/2026-05-26-session-a3f8b1")
+ * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/_runtime/2026-05-26-session-a3f8b1")
  */
 export async function getCurrentSessionDir(projectRoot) {
     const sessionId = await ensureSession(projectRoot);
-    return join(projectRoot, '.peaks', sessionId);
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
 }
 /**
  * List all session directories in the .peaks folder.
  * Returns session IDs (directory names) sorted by date.
  *
+ * As of slice 2026-06-06-session-layout-canonicalize the canonical
+ * home is `.peaks/_runtime/<sid>/`. The legacy top-level layout
+ * `.peaks/<sid>/` is read for back-compat (one minor release) so
+ * pre-migration trees keep working.
+ *
  * @param projectRoot - Root directory of the project
  * @returns Array of session IDs
  */
 export function listSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    const { readdirSync } = require('node:fs');
-    const entries = readdirSync(peaksRoot, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
-        .map((entry) => entry.name)
-        .sort()
-        .reverse(); // Most recent first
+    const seen = new Set();
+    const result = [];
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        const names = [];
+        try {
+            const out = readdirSync(root, { withFileTypes: true });
+            for (const e of out) {
+                if (e.isDirectory())
+                    names.push(e.name);
+            }
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            result.push(name);
+        }
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    return result.sort().reverse();
 }
 /**
  * Get the path to project-scan.md for the current session.
@@ -421,7 +531,15 @@ export function listSessions(projectRoot) {
  */
 export async function getProjectScanPath(projectRoot) {
     const sessionId = await ensureSession(projectRoot);
-    return join(projectRoot, '.peaks', sessionId, 'rd', 'project-scan.md');
+    // As of slice 2026-06-05-change-id-as-unit-of-work the session dir
+    // is at the canonical runtime location (gitignored). The scan is a
+    // session-local artifact; it lives alongside the rest of the
+    // ephemeral state under `_runtime/`. The parent `rd/` subdir is
+    // created on demand so the first scanner call has a place to land
+    // (consistent with the legacy behavior pre-1.3.1).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'rd', 'project-scan.md');
+    await mkdirAsync(dirname(scanPath), { recursive: true });
+    return scanPath;
 }
 /**
  * Check if project-scan.md exists for the current session.
@@ -433,6 +551,7 @@ export function hasProjectScan(projectRoot) {
     const info = readSessionFile(projectRoot);
     if (!info)
         return false;
-    const scanPath = join(projectRoot, '.peaks', info.sessionId, 'rd', 'project-scan.md');
+    // Canonical runtime location of the session dir (slice 2026-06-05).
+    const scanPath = join(projectRoot, '.peaks', '_runtime', info.sessionId, 'rd', 'project-scan.md');
     return existsSync(scanPath);
 }

package/dist/src/services/skills/hooks-settings-service.d.ts

@@ -14,16 +14,31 @@
  * removes only our own entry.
  */
 export type HookScope = 'project' | 'global';
-/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+/** The hook command written into settings for the gate-enforce PreToolUse hook. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
-/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
-export declare const HOOK_SENTINEL = "peaks gate enforce";
+/**
+ * Hook command for the sub-agent progress auto-spawn. Fires on every Task
+ * tool call (the harness-enforced mechanism for "sub-agent dispatch"). The
+ * command itself is non-blocking: `peaks progress start` is idempotent
+ * (5-minute TTL on the spawn record) so the LLM does not see a fresh
+ * terminal per Task. The `--quiet` flag keeps the LLM context clean — the
+ * hook output otherwise adds ~500 tokens per Task call.
+ */
+export declare const HOOK_PROGRESS_COMMAND = "peaks progress start --project \"${CLAUDE_PROJECT_DIR}\" --reason \"auto-spawn for sub-agent Task\" --quiet";
+/** Substring that identifies a Peaks-managed PreToolUse gate-enforce hook entry. */
+export declare const HOOK_ENFORCE_SENTINEL = "peaks gate enforce";
+/** Substring that identifies a Peaks-managed PreToolUse sub-agent-progress hook entry. */
+export declare const HOOK_PROGRESS_SENTINEL = "peaks progress start";
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
     exists: boolean;
     alreadyInstalled: boolean;
     desiredCommand: string;
+    /** Substring sentinel used to detect the entry. */
+    sentinel: string;
+    /** Tool name (Bash | Task) the PreToolUse hook is keyed on. */
+    matcher: string;
 };
 export type HookInstallResult = HookInstallPlan & {
     applied: boolean;
@@ -39,6 +54,13 @@ export type HookStatus = {
     exists: boolean;
     installed: boolean;
 };
+/** A typed descriptor for a single peaks-managed hook entry. */
+export type PeaksHookEntry = {
+    sentinel: string;
+    matcher: string;
+    command: string;
+};
+export declare const PEAKS_HOOK_ENTRIES: ReadonlyArray<PeaksHookEntry>;
 export declare function planHookInstall(scope: HookScope, projectRoot?: string): HookInstallPlan;
 export declare function applyHookInstall(scope: HookScope, projectRoot?: string): HookInstallResult;
 export declare function removeHookInstall(scope: HookScope, projectRoot?: string): HookRemoveResult;

package/dist/src/services/skills/hooks-settings-service.js

@@ -2,11 +2,33 @@ import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readF
 import { randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
-/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+/** The hook command written into settings for the gate-enforce PreToolUse hook. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
 export const HOOK_ENFORCE_COMMAND = 'peaks gate enforce --project "${CLAUDE_PROJECT_DIR}"';
-/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
-export const HOOK_SENTINEL = 'peaks gate enforce';
-const HOOK_MATCHER = 'Bash';
+/**
+ * Hook command for the sub-agent progress auto-spawn. Fires on every Task
+ * tool call (the harness-enforced mechanism for "sub-agent dispatch"). The
+ * command itself is non-blocking: `peaks progress start` is idempotent
+ * (5-minute TTL on the spawn record) so the LLM does not see a fresh
+ * terminal per Task. The `--quiet` flag keeps the LLM context clean — the
+ * hook output otherwise adds ~500 tokens per Task call.
+ */
+export const HOOK_PROGRESS_COMMAND = 'peaks progress start --project "${CLAUDE_PROJECT_DIR}" --reason "auto-spawn for sub-agent Task" --quiet';
+/** Substring that identifies a Peaks-managed PreToolUse gate-enforce hook entry. */
+export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
+/** Substring that identifies a Peaks-managed PreToolUse sub-agent-progress hook entry. */
+export const HOOK_PROGRESS_SENTINEL = 'peaks progress start';
+const HOOK_GATE_MATCHER = 'Bash';
+const HOOK_PROGRESS_MATCHER = 'Task';
+/**
+ * Substring sentinels that identify a Peaks-managed PreToolUse hook entry.
+ * Used to keep `uninstall` and `isInstalled` checks tight: we only touch
+ * entries we wrote, never third-party hooks.
+ */
+const PEAKS_HOOK_SENTINELS = [HOOK_ENFORCE_SENTINEL, HOOK_PROGRESS_SENTINEL];
+export const PEAKS_HOOK_ENTRIES = [
+    { sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER, command: HOOK_ENFORCE_COMMAND },
+    { sentinel: HOOK_PROGRESS_SENTINEL, matcher: HOOK_PROGRESS_MATCHER, command: HOOK_PROGRESS_COMMAND }
+];
 function isInsidePath(childPath, parentPath) {
     const rel = relative(parentPath, childPath);
     return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
@@ -87,9 +109,17 @@ function readPreToolUse(settings) {
     const pre = hooks.PreToolUse;
     return Array.isArray(pre) ? pre : [];
 }
+/** True when every command handler in the entry matches a known peaks sentinel. */
 function entryIsPeaksManaged(entry) {
     const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
-    return handlers.length > 0 && handlers.every((h) => typeof h?.command === 'string' && h.command.includes(HOOK_SENTINEL));
+    if (handlers.length === 0)
+        return false;
+    return handlers.every((h) => {
+        if (typeof h?.command !== 'string')
+            return false;
+        const cmd = h.command;
+        return PEAKS_HOOK_SENTINELS.some((sentinel) => cmd.includes(sentinel));
+    });
 }
 function isInstalled(settings) {
     return readPreToolUse(settings).some(entryIsPeaksManaged);
@@ -100,18 +130,32 @@ export function planHookInstall(scope, projectRoot) {
     assertSafeSettingsPath(scope, root, settingsPath);
     const exists = existsSync(settingsPath);
     const settings = readSettings(settingsPath);
-    return { scope, settingsPath, exists, alreadyInstalled: isInstalled(settings), desiredCommand: HOOK_ENFORCE_COMMAND };
+    return {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled: isInstalled(settings),
+        desiredCommand: HOOK_ENFORCE_COMMAND,
+        sentinel: HOOK_ENFORCE_SENTINEL,
+        matcher: HOOK_GATE_MATCHER
+    };
 }
-/** Merge our PreToolUse entry into settings, preserving all other keys and hooks. */
-function withHookInstalled(settings) {
+/** Merge all peaks-managed PreToolUse entries into settings, preserving all other keys and hooks. */
+function withHooksInstalled(settings) {
     const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
         ? settings.hooks
         : {};
     const preToolUse = readPreToolUse(settings);
-    const ourEntry = { matcher: HOOK_MATCHER, hooks: [{ type: 'command', command: HOOK_ENFORCE_COMMAND }] };
+    // Drop any existing peaks-managed entries first so re-runs are idempotent
+    // even if the command string changed (e.g. a bug fix in the command).
+    const nonPeaks = preToolUse.filter((entry) => !entryIsPeaksManaged(entry));
+    const ourEntries = PEAKS_HOOK_ENTRIES.map((spec) => ({
+        matcher: spec.matcher,
+        hooks: [{ type: 'command', command: spec.command }]
+    }));
     return {
         ...settings,
-        hooks: { ...existingHooks, PreToolUse: [...preToolUse, ourEntry] }
+        hooks: { ...existingHooks, PreToolUse: [...nonPeaks, ...ourEntries] }
     };
 }
 export function applyHookInstall(scope, projectRoot) {
@@ -121,10 +165,10 @@ export function applyHookInstall(scope, projectRoot) {
     const exists = existsSync(settingsPath);
     const settings = readSettings(settingsPath);
     if (isInstalled(settings)) {
-        return { scope, settingsPath, exists, alreadyInstalled: true, desiredCommand: HOOK_ENFORCE_COMMAND, applied: false };
+        return { scope, settingsPath, exists, alreadyInstalled: true, desiredCommand: HOOK_ENFORCE_COMMAND, applied: false, sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER };
     }
-    atomicWriteJson(settingsPath, withHookInstalled(settings));
-    return { scope, settingsPath, exists, alreadyInstalled: false, desiredCommand: HOOK_ENFORCE_COMMAND, applied: true };
+    atomicWriteJson(settingsPath, withHooksInstalled(settings));
+    return { scope, settingsPath, exists, alreadyInstalled: false, desiredCommand: HOOK_ENFORCE_COMMAND, applied: true, sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER };
 }
 export function removeHookInstall(scope, projectRoot) {
     const root = resolveSettingsRoot(scope, projectRoot);

package/dist/src/services/slice/slice-check-service.d.ts

@@ -0,0 +1,2 @@
+import type { SliceCheckOptions, SliceCheckResult } from './slice-check-types.js';
+export declare function sliceCheck(options: SliceCheckOptions): Promise<SliceCheckResult>;