peaks-cli 1.3.1 → 1.3.3

package/dist/src/services/security/safe-settings-path.js

@@ -0,0 +1,104 @@
+/**
+ * R-2 path-safety guard for sub-agent state files.
+ *
+ * Slice 2026-06-07-sub-agent-dispatch-decouple (G4) — reuses the same
+ * R-2 symlink/junction guard as `assertSafeSettingsFile` for
+ * `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` paths.
+ *
+ * Why a separate helper:
+ *   - The settings-file guard is a per-IDE 8th field (settings.json path);
+ *     this one is for runtime sub-agent trace records.
+ *   - Both reject paths that resolve outside the project root after
+ *     symlink resolution, and both reject `..` segments before
+ *     resolution (defense in depth).
+ *
+ * The guard is intentionally small and pure (no IO beyond `realpathSync`)
+ * so it can be called from CLI handlers and from service helpers alike.
+ */
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+const SUB_AGENTS_DIR = '_sub_agents';
+/** Build the canonical record path for a given session/rid/timestamp. */
+export function dispatchRecordPath(projectRoot, sid, rid, ts = new Date()) {
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    const tsCompact = ts.toISOString().replace(/[:.]/g, '-');
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, `dispatch-${safeRid}-${tsCompact}.json`);
+}
+/** The directory under which dispatch records live. */
+export function dispatchRecordsDir(projectRoot, sid) {
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid);
+}
+/**
+ * Assert that `recordPath` lives under `projectRoot/.peaks/_sub_agents/<sid>/`.
+ * Rejects symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_RECORD_PATH'` on rejection so
+ * the CLI can map to `{ok: false, code: "INVALID_RECORD_PATH"}`.
+ */
+export function assertSafeDispatchRecordPath(recordPath, projectRoot) {
+    if (!isAbsolute(recordPath)) {
+        throw invalidPathError(recordPath, 'must be absolute');
+    }
+    // Reject lexical `..` segments in the raw path BEFORE the OS-level resolver
+    // collapses them. POSIX `path.normalize` will turn `/a/b/../c` into `/a/c`,
+    // silently dropping the `..` — and that is exactly the symlink/junction
+    // escape we are guarding against. Test the raw string form.
+    const rawSegments = recordPath.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathError(recordPath, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, recordPath);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathError(recordPath, 'must be under .peaks/_sub_agents/');
+    }
+    let realRecord;
+    let realRoot;
+    try {
+        // For existing files, realpathSync resolves symlinks/junctions.
+        // For new files (the common case for `dispatch` CLI writing the
+        // record for the first time), we realpath the parent + check the
+        // leaf's basename shape.
+        const parent = dirname(recordPath);
+        const realParent = realpathSync(parent);
+        realRecord = resolve(realParent, recordPath.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch (error) {
+        // Realpath can fail if the parent does not exist yet (CLI is about
+        // to create it). Fall back to lexical comparison against the
+        // canonical projectRoot — the write will then create the file,
+        // and any symlink in the parent will be caught on the next read.
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, recordPath);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathError(recordPath, 'must be under .peaks/_sub_agents/');
+        }
+        return recordPath;
+    }
+    const realRel = relative(realRoot, realRecord);
+    if (realRel.startsWith('..' + sep) || realRel === '..' || isAbsolute(realRel)) {
+        throw invalidPathError(recordPath, 'escapes project root via symlink');
+    }
+    return realRecord;
+}
+function sanitizeSegment(segment, label) {
+    if (typeof segment !== 'string' || segment.length === 0) {
+        throw new Error(`Invalid ${label}: empty`);
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(segment)) {
+        throw new Error(`Invalid ${label}: must match [A-Za-z0-9._-]+ (got ${JSON.stringify(segment)})`);
+    }
+    if (segment.includes('..')) {
+        throw new Error(`Invalid ${label}: must not contain ..`);
+    }
+    return segment;
+}
+function invalidPathError(path, reason) {
+    const err = new Error(`Unsafe dispatch record path (${reason}): ${path}`);
+    err.code = 'INVALID_RECORD_PATH';
+    err.path = path;
+    return err;
+}

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

@@ -45,6 +45,13 @@ export type SessionMeta = {
  * 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 declare function rotateSessionBinding(projectRoot: string): string | null;
 /**
@@ -75,6 +82,11 @@ export declare function setSessionTitle(projectRoot: string, sessionId: string,
 /**
  * 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 declare function listSessionMetas(projectRoot: string): SessionMeta[];
 export declare function ensureSession(projectRoot: string): Promise<string>;
@@ -118,14 +130,23 @@ export declare function getSessionIdCanonical(projectRoot: string): string | nul
  * 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 declare function getCurrentSessionDir(projectRoot: string): Promise<string>;
 /**
  * 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
  */

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

@@ -180,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;
     }
@@ -221,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);
@@ -241,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 });
     }
@@ -282,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.
@@ -322,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 = {
@@ -387,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.

package/dist/src/services/signal/cancel-handler.d.ts

@@ -0,0 +1,14 @@
+export interface CancelResult {
+    readonly cancelled: number;
+    readonly scanned: number;
+    readonly paths: readonly string[];
+}
+/**
+ * Walk `.peaks/_sub_agents/<sid>/`, mark every in-flight record as
+ * `cancelled + disposed`, write back atomically (tmp + rename), and
+ * return the count. Records that already have `completedAt` set are
+ * skipped (they were already finished by the time cancel fired).
+ */
+export declare function cancelInFlightDispatches(projectRoot: string, sessionId: string, options?: {
+    now?: () => Date;
+}): CancelResult;

package/dist/src/services/signal/cancel-handler.js

@@ -0,0 +1,76 @@
+/**
+ * Slice #009 / G5 RL-9 — user cancel must dispose in-flight dispatch records.
+ *
+ * When Solo's main loop receives SIGINT (Ctrl-C) or the user runs
+ * `peaks workflow cancel --rid <rid>`, the loop MUST mark in-flight
+ * dispatch records as `outcome: "cancelled"` + `disposed: true` +
+ * `disposedAt: now()` BEFORE exiting.
+ *
+ * "In-flight" = a record with `createdAt` populated AND
+ * `completedAt: null`. Those are the ones that the LLM got a toolCall
+ * for but did not (yet) confirm completion.
+ *
+ * This module is the helper Solo calls. The wiring (signal listener,
+ * cancel command side-effect) is the Solo main loop's responsibility;
+ * this module is the pure data operation.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const CANCELLED_OUTCOME = 'cancelled';
+const CANCELLED_STATUS = 'cancelled';
+/**
+ * Walk `.peaks/_sub_agents/<sid>/`, mark every in-flight record as
+ * `cancelled + disposed`, write back atomically (tmp + rename), and
+ * return the count. Records that already have `completedAt` set are
+ * skipped (they were already finished by the time cancel fired).
+ */
+export function cancelInFlightDispatches(projectRoot, sessionId, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(dir)) {
+        return { cancelled: 0, scanned: 0, paths: [] };
+    }
+    let scanned = 0;
+    const cancelledPaths = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+            continue;
+        const fullPath = join(dir, entry);
+        scanned += 1;
+        const record = readRecordOrNull(fullPath);
+        if (record === null)
+            continue;
+        if (record.completedAt !== null)
+            continue; // already finished
+        const cancelled = {
+            ...record,
+            completedAt: now().toISOString(),
+            outcome: CANCELLED_OUTCOME,
+            status: CANCELLED_STATUS,
+            disposed: true,
+            disposedAt: now().toISOString()
+        };
+        writeFileSync(fullPath, JSON.stringify(cancelled, null, 2) + '\n', 'utf8');
+        cancelledPaths.push(fullPath);
+    }
+    return { cancelled: cancelledPaths.length, scanned, paths: cancelledPaths };
+}
+function readRecordOrNull(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const obj = parsed;
+        if (typeof obj.createdAt !== 'string')
+            return null;
+        if (typeof obj.completedAt !== 'string' && obj.completedAt !== null)
+            return null;
+        if (typeof obj.role !== 'string')
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/services/skill/resume-detector.d.ts

@@ -0,0 +1,54 @@
+export type ResumeKind = 'fresh' | 'complete' | 'resume' | 'in-flight';
+/**
+ * Step at which the slice should resume. The values are stable strings
+ * (not raw step numbers) so log output is greppable and a future
+ * workflow reshuffle can keep the names but remap the steps.
+ */
+export type ResumePoint = 'rd-planning' | 'rd-review-fanout' | 'rd-perf-baseline' | 'qa-test-cases' | 'qa-execution' | 'qa-validation' | 'txt-handoff';
+/**
+ * Mid-implementation RD/QA states. The skill body treats these as
+ * "ask the user to confirm the in-flight gate" — there is no safe
+ * auto-resume for a slice the LLM is currently driving.
+ */
+export type InFlightState = 'spec-locked' | 'implemented' | 'running' | 'blocked';
+export type ResumeClassification = {
+    kind: ResumeKind;
+    /** Set when `kind === 'resume'`; the step that should be re-entered. */
+    point: ResumePoint | null;
+    /** Set when `kind === 'in-flight'`; the current non-terminal state. */
+    state: InFlightState | null;
+    /**
+     * Files that the SKILL.md spec says should already exist for the
+     * current gate but were not found. Informational — the LLM uses this
+     * to decide what to produce next. Includes legacy-missing files when
+     * the legacy path was read.
+     */
+    missingArtifacts: string[];
+    /**
+     * Inconsistencies between state and file presence (e.g. RD is
+     * `state: qa-handoff` but `rd/code-review.md` is absent). The
+     * classifier still emits a `resume:` verdict, but the warning is the
+     * audit trail.
+     */
+    warnings: string[];
+    /** Number of RD/QA requests filtered as `user-requested-abandon`. */
+    abandonedRequestCount: number;
+    /**
+     * True when the canonical `.peaks/_runtime/<sid>/` path was absent
+     * and the classifier fell back to `.peaks/<sid>/`. Lets the SKILL.md
+     * surface a one-time migration reminder to the user.
+     */
+    usedLegacyPath: boolean;
+};
+/**
+ * Classify a session's resume state. Pure function — does not write
+ * files, does not call any peaks CLI.
+ *
+ * @param sid        The session id (e.g. `2026-06-06-session-22f08c`).
+ * @param peaksRoot  The canonical peaks runtime root, i.e. the
+ *                   directory containing `<sid>/` subdirs. For the
+ *                   v1.3.2 layout this is `<repo>/.peaks/_runtime`.
+ *                   The legacy `<repo>/.peaks` layout is also accepted
+ *                   for one minor release (see `usedLegacyPath`).
+ */
+export declare function classifyResume(sid: string, peaksRoot: string): ResumeClassification;