peaks-cli 1.3.2 → 1.3.3

package/dist/src/services/ide/shared/atomic-json.js

@@ -0,0 +1,58 @@
+import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+export const ATOMIC_JSON_FILE_MODE = 0o600;
+/**
+ * Read a JSON object file using a no-follow open. Returns an empty object when
+ * the file does not exist or is empty. Throws when the file exists but does not
+ * contain a JSON object (so callers can distinguish "no settings" from
+ * "malformed settings").
+ */
+export function readJsonObjectFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    const fd = openSync(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const raw = readFileSync(fd, 'utf8').trim();
+        if (raw.length === 0)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings file must contain a JSON object');
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Atomically write a JSON file: create a unique temp file in the same
+ * directory, fsync its contents via close, then `rename` over the target. A
+ * failure during rename removes the temp file (best effort). The target is
+ * created with 0o600 permissions.
+ */
+export function atomicWriteJson(filePath, value) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, ATOMIC_JSON_FILE_MODE);
+    try {
+        writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw error;
+    }
+}

package/dist/src/services/ide/shared/safe-path.d.ts

@@ -0,0 +1,11 @@
+export type HookScope = 'project' | 'global';
+/** True iff `childPath` resolves to `parentPath` or any path nested inside it. */
+export declare function isInsidePath(childPath: string, parentPath: string): boolean;
+/**
+ * Reject settings targets that are symlinked or escape the configured root.
+ * Used by the hook / statusline / MCP install paths to keep the project root the
+ * sole owner of writable settings files.
+ */
+export declare function assertSafeSettingsFile(scope: HookScope, root: string, dirName: string, settingsFileName: string): {
+    settingsPath: string;
+};

package/dist/src/services/ide/shared/safe-path.js

@@ -0,0 +1,29 @@
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+/** True iff `childPath` resolves to `parentPath` or any path nested inside it. */
+export function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Reject settings targets that are symlinked or escape the configured root.
+ * Used by the hook / statusline / MCP install paths to keep the project root the
+ * sole owner of writable settings files.
+ */
+export function assertSafeSettingsFile(scope, root, dirName, settingsFileName) {
+    const settingsPath = join(root, dirName, settingsFileName);
+    const dirPath = join(root, dirName);
+    if (existsSync(dirPath) && lstatSync(dirPath).isSymbolicLink()) {
+        throw new Error(`${dirName} directory must not be a symlink`);
+    }
+    if (existsSync(settingsPath)) {
+        if (lstatSync(settingsPath).isSymbolicLink()) {
+            throw new Error(`${settingsFileName} must not be a symlink`);
+        }
+        const realRoot = realpathSync(root);
+        if (!isInsidePath(realpathSync(settingsPath), realRoot)) {
+            throw new Error(`${settingsFileName} must stay inside the ${scope} root`);
+        }
+    }
+    return { settingsPath };
+}

package/dist/src/services/progress/progress-service.d.ts

@@ -2,7 +2,7 @@
  * Sub-agent progress surfacing for the RD/QA sub-agents in
  * `peaks-solo`'s Swarm phase. A sub-agent (or the LLM via the
  * `peaks progress step` CLI) writes a stable JSON file at
- * `.peaks/<sid>/system/subagent-progress.json`. The user-side
+ * `.peaks/_sub_agents/<sid>/subagent-progress.json`. The user-side
  * `peaks progress watch` CLI polls this file in a separate
  * terminal tab and renders elapsed / spinner / sub-step. The
  * `peaks progress start` CLI auto-spawns the watch in a new

package/dist/src/services/progress/progress-service.js

@@ -2,7 +2,7 @@
  * Sub-agent progress surfacing for the RD/QA sub-agents in
  * `peaks-solo`'s Swarm phase. A sub-agent (or the LLM via the
  * `peaks progress step` CLI) writes a stable JSON file at
- * `.peaks/<sid>/system/subagent-progress.json`. The user-side
+ * `.peaks/_sub_agents/<sid>/subagent-progress.json`. The user-side
  * `peaks progress watch` CLI polls this file in a separate
  * terminal tab and renders elapsed / spinner / sub-step. The
  * `peaks progress start` CLI auto-spawns the watch in a new
@@ -34,20 +34,24 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
 import { findProjectRoot } from '../config/config-safety.js';
-const PROGRESS_REL_PATH = 'system/subagent-progress.json';
-const SPAWN_REL_PATH = 'system/progress-spawn.json';
+// As of slice 2026-06-06-sub-agent-spawn-bug-and-decouple, the per-session
+// sub-agent state files live under `.peaks/_sub_agents/<sid>/`, NOT under
+// `.peaks/<sid>/system/`. The new path mirrors the existing `_runtime/`
+// and `_dogfood/` convention (leading underscore = meta-classification, not
+// a per-session artifact). The previous `<sid>/system/...` locations are
+// migrated to the new path on first run of `peaks workspace reconcile
+// --apply` (see `migrateSubAgentState` in reconcile-service.ts).
+const SUB_AGENTS_DIR = '_sub_agents';
+const PROGRESS_FILE_NAME = 'subagent-progress.json';
+const SPAWN_FILE_NAME = 'progress-spawn.json';
 function progressPath(projectRoot) {
-    // The progress file lives under the *session* directory, not
-    // directly under .peaks/. Every other per-slice artefact
-    // (rd/tech-doc.md, qa/test-cases/<rid>.md, prd/requests/<rid>.md,
-    // memory/, openspec/) lives under .peaks/<sid>/, so progress
-    // should too. Without the session prefix, a session rotation
-    // would orphan the file in the project root, and switching
-    // sessions would have the watch reading the wrong slice's
-    // progress.
+    // The progress file lives at `.peaks/_sub_agents/<sid>/subagent-progress.json`.
+    // The leading `_sub_agents/` is a meta-classification (mirrors `_runtime/`,
+    // `_dogfood/`) — the SID is the per-session discriminator inside that meta
+    // dir. Without the SID, sessions would collide on the same file.
     const sessionId = getSessionIdCanonical(projectRoot);
     const subDir = sessionId ?? 'unbound';
-    return join(projectRoot, '.peaks', subDir, PROGRESS_REL_PATH);
+    return join(projectRoot, '.peaks', SUB_AGENTS_DIR, subDir, PROGRESS_FILE_NAME);
 }
 function ensureParentDir(path) {
     const dir = dirname(path);
@@ -199,12 +203,12 @@ export function subAgentProgressPath(projectRoot) {
 export function subAgentSpawnPath(projectRoot) {
     const sessionId = getSessionIdCanonical(projectRoot);
     const subDir = sessionId ?? 'unbound';
-    return join(projectRoot, '.peaks', subDir, SPAWN_REL_PATH);
+    return join(projectRoot, '.peaks', SUB_AGENTS_DIR, subDir, SPAWN_FILE_NAME);
 }
 function spawnRecordPath(projectRoot) {
     const sessionId = getSessionIdCanonical(projectRoot);
     const subDir = sessionId ?? 'unbound';
-    return join(projectRoot, '.peaks', subDir, SPAWN_REL_PATH);
+    return join(projectRoot, '.peaks', SUB_AGENTS_DIR, subDir, SPAWN_FILE_NAME);
 }
 export function writeSpawnRecord(options) {
     const sessionId = getSessionIdCanonical(options.projectRoot);

package/dist/src/services/security/safe-settings-path.d.ts

@@ -0,0 +1,12 @@
+/** Build the canonical record path for a given session/rid/timestamp. */
+export declare function dispatchRecordPath(projectRoot: string, sid: string, rid: string, ts?: Date): string;
+/** The directory under which dispatch records live. */
+export declare function dispatchRecordsDir(projectRoot: string, sid: string): string;
+/**
+ * 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 declare function assertSafeDispatchRecordPath(recordPath: string, projectRoot: string): string;

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