peaks-cli 1.3.1 → 1.3.3

package/dist/src/services/ide/hook-translator.d.ts

@@ -0,0 +1,72 @@
+import type { IdeId } from './ide-types.js';
+/**
+ * hook-translator —— peaks 自有 hook 协议的核心。
+ *
+ * 单一职责:把 IDE 私有 stdin 形态归一化到 peaks canonical schema;把 peaks 决策
+ * 格式化回 IDE 期望的 stdout/exit-code 形态。
+ *
+ * auto-detection 算法(优先级从高到低):
+ *   1. env 变量:CLAUDE_PROJECT_DIR / TRAE_PROJECT_DIR / CODEX_PROJECT_DIR / ...
+ *   2. stdin shape:`{ tool_name, tool_input }` 是 Claude / Trae;
+ *                `{ toolName, toolInput }` 是 Cursor;
+ *                `{ eventName, parameters }` 是 Trae 另形态
+ *   3. cwd 启发式:存在 .claude / .trae / .codex / .cursor 目录
+ *   4. fallback:`claude-code`(backward compat,见 PRD preserved behavior #10)
+ */
+export interface DetectFromStdinInput {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+    /** 已解析的 stdin 形态;null = 空 stdin 或非 JSON */
+    readonly parsedStdin: unknown;
+}
+/**
+ * Detect the originating IDE from env / stdin shape / cwd heuristics.
+ * Falls back to 'claude-code' (PRD preserved behavior: backward compat).
+ */
+export declare function detectIdeFromContext(input: DetectFromStdinInput): IdeId;
+/**
+ * Pluck a string value at a nested path. Returns undefined if any segment is
+ * missing or non-object. Used by adapter-driven stdin parsers.
+ */
+export declare function pluckString(obj: unknown, path: readonly string[]): string | undefined;
+export declare function pluckObject(obj: unknown, path: readonly string[]): Record<string, unknown> | undefined;
+/**
+ * Default stdin parser for adapters that follow the Claude Code shape
+ * (most LLM-style IDEs do: tool_name at top, tool_input.{command} inside).
+ */
+export declare function parseClaudeShapeStdin(parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};
+/**
+ * Trae stdin parser. UNVERIFIED — Trae 1.x's actual stdin envelope shape is
+ * assumed to be Cursor-style (eventName at top, parameters nested), based on
+ * slice #2's read of Trae as a "Cursor sibling". When a real Trae 1.x hook
+ * payload is dogfooded, this parser is the seam to update.
+ *
+ * Shape (assumed):
+ *   { eventName: 'beforeToolCall', parameters: { command: 'rm -rf /' } }
+ *
+ * Returns the same `{ toolName, command }` shape as parseClaudeShapeStdin so
+ * downstream code (buildCanonicalHook, enforceBashCommand) does not need to
+ * branch on IDE. The `toolName` here is the IDE-specific name (e.g.
+ * 'terminal'); callers may normalize it to the canonical 'Bash' if needed.
+ */
+export declare function parseTraeShapeStdin(parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};
+/**
+ * Per-adapter stdin parser dispatch. Returns the `{ toolName, command }` pair
+ * for the given IDE, regardless of which stdin shape the IDE actually emits.
+ *
+ * The dispatch table is keyed on `IdeId` (not stdin shape) so an adapter can
+ * change its wire format without breaking the hook-handle flow. Unknown IDEs
+ * fall back to the Claude parser — that preserves the slice #1 "fail-open to
+ * Claude" behavior so a future adapter that has not yet been added does not
+ * crash the hook runtime.
+ */
+export declare function parseAdapterStdin(ide: IdeId, parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};

package/dist/src/services/ide/hook-translator.js

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAdapter, listAdapterIds } from './ide-registry.js';
+/**
+ * Detect the originating IDE from env / stdin shape / cwd heuristics.
+ * Falls back to 'claude-code' (PRD preserved behavior: backward compat).
+ */
+export function detectIdeFromContext(input) {
+    // 1. env 变量优先级最高。Iterate ONLY over currently-registered adapters
+    // so the function does not throw on unregistered IDEs while future slices
+    // progressively add trae / codex / cursor / qoder / tongyi-lingma.
+    for (const adapter of listAdapterIds()) {
+        const a = getAdapter(adapter);
+        if (input.env[a.envVar] !== undefined) {
+            return adapter;
+        }
+    }
+    // 2. stdin shape
+    if (isObject(input.parsedStdin)) {
+        if ('tool_name' in input.parsedStdin || 'tool_input' in input.parsedStdin) {
+            return 'claude-code';
+        }
+        if ('toolName' in input.parsedStdin || 'toolInput' in input.parsedStdin) {
+            return 'cursor';
+        }
+        if ('eventName' in input.parsedStdin || 'parameters' in input.parsedStdin) {
+            return 'trae';
+        }
+    }
+    // 3. cwd 启发式。Same registration-aware iteration as step 1.
+    for (const adapter of listAdapterIds()) {
+        const a = getAdapter(adapter);
+        if (existsSync(join(input.cwd, a.settings.dirName))) {
+            return adapter;
+        }
+    }
+    // 4. fallback
+    return 'claude-code';
+}
+/**
+ * Pluck a string value at a nested path. Returns undefined if any segment is
+ * missing or non-object. Used by adapter-driven stdin parsers.
+ */
+export function pluckString(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (!isObject(cur) || !(seg in cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return typeof cur === 'string' ? cur : undefined;
+}
+export function pluckObject(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (!isObject(cur) || !(seg in cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return isObject(cur) ? cur : undefined;
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Default stdin parser for adapters that follow the Claude Code shape
+ * (most LLM-style IDEs do: tool_name at top, tool_input.{command} inside).
+ */
+export function parseClaudeShapeStdin(parsed) {
+    if (!isObject(parsed))
+        return {};
+    const toolName = pluckString(parsed, ['tool_name']);
+    const command = pluckString(parsed, ['tool_input', 'command']);
+    const result = {};
+    if (toolName !== undefined)
+        result.toolName = toolName;
+    if (command !== undefined)
+        result.command = command;
+    return result;
+}
+/**
+ * Trae stdin parser. UNVERIFIED — Trae 1.x's actual stdin envelope shape is
+ * assumed to be Cursor-style (eventName at top, parameters nested), based on
+ * slice #2's read of Trae as a "Cursor sibling". When a real Trae 1.x hook
+ * payload is dogfooded, this parser is the seam to update.
+ *
+ * Shape (assumed):
+ *   { eventName: 'beforeToolCall', parameters: { command: 'rm -rf /' } }
+ *
+ * Returns the same `{ toolName, command }` shape as parseClaudeShapeStdin so
+ * downstream code (buildCanonicalHook, enforceBashCommand) does not need to
+ * branch on IDE. The `toolName` here is the IDE-specific name (e.g.
+ * 'terminal'); callers may normalize it to the canonical 'Bash' if needed.
+ */
+export function parseTraeShapeStdin(parsed) {
+    if (!isObject(parsed))
+        return {};
+    const eventName = pluckString(parsed, ['eventName']);
+    const command = pluckString(parsed, ['parameters', 'command']);
+    const result = {};
+    // Trae sends the event name in the payload (`eventName: 'beforeToolCall'`)
+    // and the tool name on the parameters (e.g. `parameters.tool: 'terminal'`).
+    // We expose the event name as the "toolName" for now since Trae has not
+    // been observed to carry a top-level tool field. Future slice can split
+    // event vs tool if the real shape requires it.
+    if (eventName !== undefined)
+        result.toolName = eventName;
+    if (command !== undefined)
+        result.command = command;
+    return result;
+}
+/**
+ * Per-adapter stdin parser dispatch. Returns the `{ toolName, command }` pair
+ * for the given IDE, regardless of which stdin shape the IDE actually emits.
+ *
+ * The dispatch table is keyed on `IdeId` (not stdin shape) so an adapter can
+ * change its wire format without breaking the hook-handle flow. Unknown IDEs
+ * fall back to the Claude parser — that preserves the slice #1 "fail-open to
+ * Claude" behavior so a future adapter that has not yet been added does not
+ * crash the hook runtime.
+ */
+export function parseAdapterStdin(ide, parsed) {
+    if (ide === 'trae')
+        return parseTraeShapeStdin(parsed);
+    // Future adapters (codex, cursor, qoder, tongyi-lingma) — branch here when
+    // their adapters are registered. Until then, fall back to Claude shape.
+    return parseClaudeShapeStdin(parsed);
+}

package/dist/src/services/ide/ide-detector.d.ts

@@ -0,0 +1,10 @@
+import type { IdeId } from './ide-types.js';
+/**
+ * Detect which IDE a given project root is using, by looking for the IDE's
+ * settings directory (`.claude`, `.trae`, etc.). Returns the first match in
+ * adapter insertion order, or `null` if no adapter's directory is present.
+ *
+ * 启发式:基于 cwd 目录存在性。CLI 后续 slice 会扩展为 env 变量检测、settings
+ * 文件内容检测、显式 `--ide` flag 覆盖等。
+ */
+export declare function detectInstalledIde(projectRoot: string): IdeId | null;

package/dist/src/services/ide/ide-detector.js

@@ -0,0 +1,19 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { listAdapters } from './ide-registry.js';
+/**
+ * Detect which IDE a given project root is using, by looking for the IDE's
+ * settings directory (`.claude`, `.trae`, etc.). Returns the first match in
+ * adapter insertion order, or `null` if no adapter's directory is present.
+ *
+ * 启发式:基于 cwd 目录存在性。CLI 后续 slice 会扩展为 env 变量检测、settings
+ * 文件内容检测、显式 `--ide` flag 覆盖等。
+ */
+export function detectInstalledIde(projectRoot) {
+    for (const adapter of listAdapters()) {
+        if (existsSync(join(projectRoot, adapter.settings.dirName))) {
+            return adapter.id;
+        }
+    }
+    return null;
+}

package/dist/src/services/ide/ide-registry.d.ts

@@ -0,0 +1,14 @@
+import type { IdeAdapter, IdeId } from './ide-types.js';
+/** Get the adapter for a given IDE id. Throws on unsupported IDE. */
+export declare function getAdapter(ide: IdeId): IdeAdapter;
+/** All registered adapter ids (insertion order). */
+export declare function listAdapterIds(): readonly IdeId[];
+/** All registered adapters (insertion order). */
+export declare function listAdapters(): readonly IdeAdapter[];
+/**
+ * Test seam: register or replace an adapter. Used by future slices when adding
+ * a new IDE. Caller is responsible for ensuring the adapter is well-formed.
+ */
+export declare function _setAdapterForTesting(ide: IdeId, adapter: IdeAdapter): void;
+/** Test seam: reset to built-in defaults. */
+export declare function _resetAdaptersForTesting(): void;

package/dist/src/services/ide/ide-registry.js

@@ -0,0 +1,45 @@
+import { CLAUDE_CODE_ADAPTER } from './adapters/claude-code-adapter.js';
+import { TRAE_ADAPTER } from './adapters/trae-adapter.js';
+/**
+ * Built-in IDE adapter registry。Map<IdeId, IdeAdapter> 是单一来源。
+ *
+ * Slice #1 注册 claude-code。
+ * Slice #2 注册 trae —— 这是 slice #1 抽出的 IdeAdapter 形状的
+ * 第一个真实客户,验证"填表"承诺。
+ * 后续 slice 注入 codex / cursor / qoder / tongyi-lingma 时,只需在此
+ * Map 加条目 —— 所有 adapter 使用方(hook-translator、hooks install、statusline
+ * install、mcp apply)通过 `getAdapter(ide)` 拿取,无需修改。
+ */
+const ADAPTERS = new Map([
+    ['claude-code', CLAUDE_CODE_ADAPTER],
+    ['trae', TRAE_ADAPTER],
+]);
+/** Get the adapter for a given IDE id. Throws on unsupported IDE. */
+export function getAdapter(ide) {
+    const adapter = ADAPTERS.get(ide);
+    if (!adapter) {
+        throw new Error(`Unsupported IDE: ${ide}. Registered: ${listAdapterIds().join(', ') || '(none)'}`);
+    }
+    return adapter;
+}
+/** All registered adapter ids (insertion order). */
+export function listAdapterIds() {
+    return Array.from(ADAPTERS.keys());
+}
+/** All registered adapters (insertion order). */
+export function listAdapters() {
+    return Array.from(ADAPTERS.values());
+}
+/**
+ * Test seam: register or replace an adapter. Used by future slices when adding
+ * a new IDE. Caller is responsible for ensuring the adapter is well-formed.
+ */
+export function _setAdapterForTesting(ide, adapter) {
+    ADAPTERS.set(ide, adapter);
+}
+/** Test seam: reset to built-in defaults. */
+export function _resetAdaptersForTesting() {
+    ADAPTERS.clear();
+    ADAPTERS.set('claude-code', CLAUDE_CODE_ADAPTER);
+    ADAPTERS.set('trae', TRAE_ADAPTER);
+}

package/dist/src/services/ide/ide-types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * peaks 自有 hook 协议 + slim IDE adapter 接口。
+ *
+ * peaks-cli 不再适配 IDE 私有的 hook 协议;反之 peaks 定义自己的 canonical
+ * schema,每个 IDE 只需要填 4 字符串 + 1 settings 函数,新 IDE 适配变成"填表"。
+ *
+ * 不可消除的 per-IDE 字段(诚实交代,见 PRD R-1..R-4):
+ *   - settings.json 物理位置
+ *   - 项目根 env 变量名
+ *   - hook 事件名 + matcher 名
+ *
+ * 其他全部归一化到 peaks 内部模型(见 hook-protocol.ts)。
+ */
+import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
+export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma';
+export interface IdeCapabilities {
+    /** peaks gate enforce 是否适用该 IDE(必备) */
+    readonly gateEnforce: true;
+    /** peaks progress start(sub-agent 派发)是否适用 */
+    readonly progressStart: boolean;
+    /** peaks statusline 状态栏是否适用 */
+    readonly statusline: boolean;
+    /** peaks mcp install 是否适用 */
+    readonly mcpInstall: boolean;
+}
+export interface IdeSettingsLocation {
+    /** 项目根下的 settings 目录名,例如 '.claude' / '.trae' / '.cursor' */
+    readonly dirName: string;
+    /** settings 文件名(部分 IDE 叫 settings.json / mcp.json) */
+    readonly settingsFileName: string;
+    /** 解析出 settings.json 绝对路径 */
+    resolveSettingsFile(scope: 'project' | 'global', projectRoot: string | undefined): string;
+    /** 该 IDE 是否支持此 scope(用于清晰报错) */
+    supportsScope(scope: 'project' | 'global'): boolean;
+}
+/**
+ * Slim IDE adapter 描述。每 IDE 一个静态常量(无需 DI)。
+ * 字段故意保持少:让 adapter 的添加是"填表"而非"重写"。
+ */
+export interface IdeAdapter {
+    readonly id: IdeId;
+    /** 人类可读名,出现在 CLI help / 命令输出 */
+    readonly displayName: string;
+    readonly settings: IdeSettingsLocation;
+    /** IDE 注入的项目根 env 变量名;`peaks gate enforce` 等命令模板会引用此 env */
+    readonly envVar: string;
+    /** settings.json 里 hook 数组的 key,例如 'PreToolUse' / 'beforeToolCall' */
+    readonly hookEvent: string;
+    /** hook 数组元素的 matcher 字段(工具名匹配),例如 'Bash' / 'Task' / 'terminal' */
+    readonly toolMatcher: string;
+    /**
+     * The tool name used by this IDE to invoke a sub-agent (e.g. Claude Code
+     * uses 'Task' to dispatch a sub-agent, Trae may use a different name).
+     * Consumed by the `peaks progress start` hook entry so each IDE self-
+     * reports its sub-agent tool name. Additive on `toolMatcher`: the
+     * `toolMatcher` field still drives the gate-enforce hook entry, this
+     * one drives the sub-agent-progress hook entry.
+     *
+     * Added in slice 2026-06-06-sub-agent-spawn-bug-and-decouple.
+     */
+    readonly subAgentToolMatcher: string;
+    /**
+     * Per-IDE sub-agent dispatcher. The `peaks sub-agent dispatch` CLI reads
+     * this field, calls `supportsRole` + `buildToolCall`, and returns the
+     * resulting tool-call descriptor in the JSON envelope. Additive on
+     * `subAgentToolMatcher`: the matcher still drives the gate-enforce hook
+     * entry; this field drives the runtime sub-agent dispatch surface.
+     *
+     * Added in slice 2026-06-07-sub-agent-dispatch-decouple. See PRD #002
+     * G1 (AC-1, AC-2) + [[slim-ideadapter-shape-is-the-contract]].
+     */
+    readonly subAgentDispatcher: SubAgentDispatcher;
+    /**
+     * Per-IDE opt-in to the G9 prompt-size gate. When `true`, the
+     * `peaks hooks install` command registers the G9 PreToolUse hook
+     * (`peaks sub-agent-dispatch-guard`) for this IDE. When `false`,
+     * the hook is NOT installed (the IDE either doesn't support the
+     * PreToolUse event in a useful form, or the user has opted out).
+     *
+     * The CLI 兜底 layer in `peaks sub-agent dispatch` still enforces
+     * the threshold regardless of this field — `promptSizeAware` only
+     * controls the hook layer (R-15: G9 hook is LLM-platform-specific).
+     *
+     * Added in slice 2026-06-07-sub-agent-context-governance. See PRD
+     * #003 G9.2 + AC-56. Default `false` to preserve slice #009's
+     * `peaks hooks install` output byte-stability.
+     */
+    readonly promptSizeAware: boolean;
+    /** install / uninstall 后展示给用户的提示文本(各 IDE 不同,例如 Claude 提示重启窗口) */
+    readonly installHints: readonly string[];
+    /** 该 IDE 在 peaks 上可启用的能力(用于在不支持的 IDE 上软警告) */
+    readonly capabilities: IdeCapabilities;
+}
+/** peaks canonical hook schema 版本标识 */
+export declare const PEAKS_HOOK_SCHEMA: "peaks-hook/v1";
+/** peaks canonical hook 形态 —— 单一协议,所有 IDE 经 hook-translator 归一化到此 */
+export interface PeaksCanonicalHook {
+    readonly schema: typeof PEAKS_HOOK_SCHEMA;
+    readonly event: 'pre-tool-use' | 'post-tool-use' | 'sub-agent-start';
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+    /** 解析自 env 变量或 --project 的项目根 */
+    readonly projectRoot: string;
+    /** 选输出格式 */
+    readonly rawIdeFormat: IdeId;
+    /** 原始 stdin,留作回退 */
+    readonly rawPayload: unknown;
+}
+/** peaks 决策发回形态枚举(按 IDE 期望的"发回"形式) */
+export type PeaksDecisionTransport = {
+    kind: 'stdout-json';
+    denyShape: Record<string, unknown>;
+} | {
+    kind: 'exit-code';
+    denyCode: number;
+} | {
+    kind: 'both';
+    denyShape: Record<string, unknown>;
+    denyCode: number;
+};

package/dist/src/services/ide/ide-types.js

@@ -0,0 +1,2 @@
+/** peaks canonical hook schema 版本标识 */
+export const PEAKS_HOOK_SCHEMA = 'peaks-hook/v1';

package/dist/src/services/ide/shared/atomic-json.d.ts

@@ -0,0 +1,15 @@
+export declare const ATOMIC_JSON_FILE_MODE = 384;
+/**
+ * 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 declare function readJsonObjectFile<T extends Record<string, unknown> = Record<string, unknown>>(filePath: string): T;
+/**
+ * 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 declare function atomicWriteJson(filePath: string, value: unknown): void;

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;