peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/scan/type-sanity-service.js

@@ -0,0 +1,116 @@
+import { execFileSync } from 'node:child_process';
+import { extname, basename } from 'node:path';
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.cpp', '.c', '.h', '.cs', '.rb', '.php', '.scala', '.dart', '.less', '.scss', '.sass', '.css']);
+const DOCS_EXTENSIONS = new Set(['.md', '.mdx', '.rst', '.txt']);
+const LOCKFILE_NAMES = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb', 'Cargo.lock', 'Gemfile.lock', 'composer.lock', 'go.sum', 'poetry.lock']);
+const CONFIG_NAMES = new Set(['package.json', 'tsconfig.json', 'tsconfig.base.json', 'vite.config.ts', 'vite.config.js', 'webpack.config.js', 'next.config.js', 'next.config.ts', '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.prettierrc', '.prettierrc.json', 'eslint.config.js', '.gitignore', '.npmrc', 'docker-compose.yml', 'docker-compose.yaml', 'Dockerfile', 'Makefile', '.editorconfig', 'tailwind.config.js', 'tailwind.config.ts', 'postcss.config.js', 'commitlint.config.js', 'lefthook.yml', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'nx.json']);
+const CONFIG_EXTENSIONS = new Set(['.toml', '.ini', '.cfg', '.env']);
+function classifyFile(filePath) {
+    const name = basename(filePath);
+    const ext = extname(filePath).toLowerCase();
+    if (LOCKFILE_NAMES.has(name))
+        return 'lockfile';
+    if (CONFIG_NAMES.has(name))
+        return 'config';
+    if (CONFIG_EXTENSIONS.has(ext))
+        return 'config';
+    if (filePath.startsWith('.github/') || filePath.includes('/workflows/') || name === 'release.yml' || name.endsWith('.yml') || name.endsWith('.yaml'))
+        return 'config';
+    if (DOCS_EXTENSIONS.has(ext))
+        return 'docs';
+    // Test files: anything under tests/, __tests__/, or matching *.test.*, *.spec.*
+    if (/\b(?:tests?|__tests__|__mocks__|spec)\b/.test(filePath) || /\.(test|spec)\.[a-z]+$/i.test(name))
+        return 'test';
+    if (SOURCE_EXTENSIONS.has(ext))
+        return 'source';
+    return 'unknown';
+}
+/**
+ * Peaks' own artifact workspace. Changes here (PRD/RD/QA markdown, session
+ * state) are never the "code change" a request type describes, so they must be
+ * excluded from the diff — otherwise a PRD-planning-phase handoff that only
+ * wrote `.peaks/**` markdown would be misclassified as a docs change.
+ */
+function isArtifactWorkspaceFile(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized === '.peaks' || normalized.startsWith('.peaks/');
+}
+function tryGitDiffFiles(projectRoot, baseRef) {
+    try {
+        // Combine: tracked changes vs baseRef + untracked files. Use porcelain status for untracked too.
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', baseRef], { encoding: 'utf8' });
+        const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
+        const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const merged = Array.from(new Set([...tracked, ...untracked])).filter((file) => !isArtifactWorkspaceFile(file));
+        return { ok: true, files: merged };
+    }
+    catch {
+        return { ok: false, files: [] };
+    }
+}
+function buildBreakdown(files) {
+    const grouped = new Map();
+    for (const file of files) {
+        const category = classifyFile(file);
+        const list = grouped.get(category) ?? [];
+        list.push(file);
+        grouped.set(category, list);
+    }
+    return Array.from(grouped.entries()).map(([category, examples]) => ({
+        category,
+        count: examples.length,
+        examples: examples.slice(0, 5)
+    }));
+}
+function suggestTypes(breakdown) {
+    const counts = { source: 0, config: 0, docs: 0, lockfile: 0, test: 0, unknown: 0 };
+    for (const entry of breakdown)
+        counts[entry.category] = entry.count;
+    const hasSource = counts.source > 0;
+    const hasConfig = counts.config > 0;
+    const hasDocs = counts.docs > 0;
+    const hasLockfile = counts.lockfile > 0;
+    const hasTest = counts.test > 0;
+    if (!hasSource && !hasConfig && hasDocs)
+        return ['docs'];
+    if (!hasSource && !hasDocs && hasConfig)
+        return ['config'];
+    if (!hasSource && !hasDocs && !hasConfig && hasLockfile)
+        return ['chore'];
+    if (!hasSource && !hasDocs && !hasConfig && !hasLockfile && hasTest)
+        return ['bugfix', 'refactor'];
+    if (hasSource)
+        return ['feature', 'bugfix', 'refactor'];
+    return ['feature', 'bugfix', 'refactor', 'config', 'docs', 'chore'];
+}
+function isConsistent(declared, suggested) {
+    return suggested.includes(declared);
+}
+function buildRationale(declared, breakdown, suggested, consistent) {
+    const summary = breakdown.map((entry) => `${entry.category}=${entry.count}`).join(', ');
+    if (consistent) {
+        return `declared --type=${declared} is consistent with the changed files (${summary})`;
+    }
+    return `declared --type=${declared} disagrees with the changed files (${summary}); suggested types: ${suggested.join(' | ')}`;
+}
+export function checkTypeSanity(options) {
+    const baseRef = options.baseRef ?? 'HEAD';
+    const { ok: gitAvailable, files } = tryGitDiffFiles(options.projectRoot, baseRef);
+    const breakdown = buildBreakdown(files);
+    const suggested = suggestTypes(breakdown);
+    const consistent = !gitAvailable ? true : files.length === 0 ? true : isConsistent(options.declaredType, suggested);
+    return {
+        declaredType: options.declaredType,
+        gitAvailable,
+        changedFiles: files,
+        breakdown,
+        suggestedTypes: suggested,
+        consistent,
+        rationale: !gitAvailable
+            ? 'git unavailable or not a git repository — type sanity check skipped (returns consistent=true)'
+            : files.length === 0
+                ? `no changes detected against ${baseRef} — type sanity check skipped (returns consistent=true)`
+                : buildRationale(options.declaredType, breakdown, suggested, consistent)
+    };
+}

package/dist/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/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/services/sediment/dispose-confirm.d.ts

@@ -0,0 +1,9 @@
+import type { BeeManifest } from "./types.js";
+export type DisposePlan = {
+    decision: "destroy";
+    auto: true;
+} | {
+    decision: null;
+    requiresUserPrompt: true;
+};
+export declare function planDispose(m: BeeManifest): DisposePlan;

package/dist/services/sediment/dispose-confirm.js

@@ -0,0 +1,5 @@
+export function planDispose(m) {
+    if (m.source === "system")
+        return { decision: "destroy", auto: true };
+    return { decision: null, requiresUserPrompt: true };
+}

package/dist/services/sediment/json-schema.d.ts

@@ -0,0 +1,247 @@
+import { z } from "zod";
+export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"peaks.bee/1">;
+    name: z.ZodString;
+    source: z.ZodEnum<["system", "user"]>;
+    promotion_status: z.ZodEnum<["candidate", "stable", "retired", "system-stable"]>;
+    description: z.ZodString;
+    segments: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        inputs: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<["string", "number", "boolean", "json"]>;
+            required: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }, {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }>, "many">;
+        outputs: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<["string", "number", "boolean", "json"]>;
+            required: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }, {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }>, "many">;
+        sideEffects: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }, {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }>, "many">;
+    entrypoint: z.ZodObject<{
+        preamble: z.ZodString;
+        refs: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<["file", "dir", "script"]>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }, {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    }, {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    }>;
+    promotion: z.ZodObject<{
+        minCycles: z.ZodNumber;
+        requiresHumanApproval: z.ZodBoolean;
+        requiresSmokeTest: z.ZodBoolean;
+        retireOnMissesInRow: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    }, {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    }>;
+    createdBy: z.ZodEnum<["human", "llm"]>;
+    lastTouchedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    source: "user" | "system";
+    description: string;
+    schemaVersion: "peaks.bee/1";
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    segments: {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }[];
+    promotion_status: "candidate" | "stable" | "retired" | "system-stable";
+    entrypoint: {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    };
+    createdBy: "llm" | "human";
+    lastTouchedAt: string;
+}, {
+    name: string;
+    source: "user" | "system";
+    description: string;
+    schemaVersion: "peaks.bee/1";
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    segments: {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }[];
+    promotion_status: "candidate" | "stable" | "retired" | "system-stable";
+    entrypoint: {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    };
+    createdBy: "llm" | "human";
+    lastTouchedAt: string;
+}>, {
+    name: string;
+    source: "user" | "system";
+    description: string;
+    schemaVersion: "peaks.bee/1";
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    segments: {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }[];
+    promotion_status: "candidate" | "stable" | "retired" | "system-stable";
+    entrypoint: {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    };
+    createdBy: "llm" | "human";
+    lastTouchedAt: string;
+}, {
+    name: string;
+    source: "user" | "system";
+    description: string;
+    schemaVersion: "peaks.bee/1";
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    segments: {
+        name: string;
+        outputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        inputs: {
+            name: string;
+            type: "string" | "number" | "boolean" | "json";
+            required: boolean;
+        }[];
+        sideEffects: string[];
+    }[];
+    promotion_status: "candidate" | "stable" | "retired" | "system-stable";
+    entrypoint: {
+        preamble: string;
+        refs: {
+            path: string;
+            kind: "file" | "script" | "dir";
+        }[];
+    };
+    createdBy: "llm" | "human";
+    lastTouchedAt: string;
+}>;

package/dist/services/sediment/json-schema.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export const BeeManifestSchema = z.object({
+    schemaVersion: z.literal("peaks.bee/1"),
+    name: z.string().regex(/^bee-[a-z0-9][a-z0-9-]*$|^peaks-[a-z0-9][a-z0-9-]*$/),
+    source: z.enum(["system", "user"]),
+    promotion_status: z.enum(["candidate", "stable", "retired", "system-stable"]),
+    description: z.string().min(1).max(200),
+    segments: z.array(z.object({
+        name: z.string(),
+        inputs: z.array(z.object({ name: z.string(), type: z.enum(["string", "number", "boolean", "json"]), required: z.boolean() })),
+        outputs: z.array(z.object({ name: z.string(), type: z.enum(["string", "number", "boolean", "json"]), required: z.boolean() })),
+        sideEffects: z.array(z.string()),
+    })),
+    entrypoint: z.object({
+        preamble: z.string(),
+        refs: z.array(z.object({ path: z.string(), kind: z.enum(["file", "dir", "script"]) })),
+    }),
+    promotion: z.object({
+        minCycles: z.number().int().nonnegative(),
+        requiresHumanApproval: z.boolean(),
+        requiresSmokeTest: z.boolean(),
+        retireOnMissesInRow: z.number().int().positive().optional(),
+    }),
+    createdBy: z.enum(["human", "llm"]),
+    lastTouchedAt: z.string().datetime(),
+}).refine((m) => !(m.source === "system" && m.promotion_status !== "system-stable"), { message: "source=system must have promotion_status=system-stable" });

package/dist/services/sediment/manifest-lint.d.ts

@@ -0,0 +1,13 @@
+import type { BeeManifest } from "./types.js";
+export type Finding = {
+    path: string;
+    message: string;
+};
+export type LintResult = {
+    ok: true;
+} | {
+    ok: false;
+    findings: Finding[];
+};
+export declare function lintManifest(m: unknown): LintResult;
+export declare function lintManifestStrict(m: unknown): BeeManifest;

package/dist/services/sediment/manifest-lint.js

@@ -0,0 +1,11 @@
+import { BeeManifestSchema } from "./json-schema.js";
+export function lintManifest(m) {
+    const r = BeeManifestSchema.safeParse(m);
+    if (r.success)
+        return { ok: true };
+    return { ok: false, findings: r.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })) };
+}
+export function lintManifestStrict(m) {
+    const r = BeeManifestSchema.parse(m);
+    return r;
+}

package/dist/services/sediment/pool-paths.d.ts

@@ -0,0 +1,22 @@
+export declare class SYSTEM_PATH_FORBIDDEN extends Error {
+    constructor(p: string);
+}
+export interface Home {
+    home: string;
+}
+export declare const resolvePoolRoot: ({ home }: Home) => string;
+export declare const resolveSystemDir: ({ home }: Home) => string;
+export declare const resolveUserBeesDir: ({ home }: Home) => string;
+export declare const resolveUserBeeDir: ({ home }: Home, name: string) => string;
+export declare const resolveSegmentsDir: ({ home }: Home) => string;
+export declare const resolveSegmentDir: ({ home }: Home, name: string) => string;
+export declare const resolveStateDbPath: ({ home }: Home) => string;
+export declare const resolveBlobsDir: ({ home }: Home) => string;
+/**
+ * Normalize `..` segments via `path.resolve` before splitting, so a path like
+ * `/h/foo/../.system/evil` collapses to `/h/.system/evil` and its `.system`
+ * segment is correctly identified. Also defends against Windows-style
+ * traversal patterns such as `..\\.system\\evil`.
+ */
+export declare function isSystemPath(p: string): boolean;
+export declare function assertNotSystemPath(p: string): void;

package/dist/services/sediment/pool-paths.js

@@ -0,0 +1,25 @@
+import { join, resolve as pathResolve } from "node:path";
+export class SYSTEM_PATH_FORBIDDEN extends Error {
+    constructor(p) { super(`SYSTEM_PATH_FORBIDDEN: refusing to write ${p}`); }
+}
+export const resolvePoolRoot = ({ home }) => join(home, ".peaks", "skills");
+export const resolveSystemDir = ({ home }) => join(resolvePoolRoot({ home }), ".system");
+export const resolveUserBeesDir = ({ home }) => join(resolvePoolRoot({ home }), "bees");
+export const resolveUserBeeDir = ({ home }, name) => join(resolveUserBeesDir({ home }), name);
+export const resolveSegmentsDir = ({ home }) => join(resolvePoolRoot({ home }), "segments");
+export const resolveSegmentDir = ({ home }, name) => join(resolveSegmentsDir({ home }), name);
+export const resolveStateDbPath = ({ home }) => join(resolvePoolRoot({ home }), "state.db");
+export const resolveBlobsDir = ({ home }) => join(resolvePoolRoot({ home }), "blobs");
+/**
+ * Normalize `..` segments via `path.resolve` before splitting, so a path like
+ * `/h/foo/../.system/evil` collapses to `/h/.system/evil` and its `.system`
+ * segment is correctly identified. Also defends against Windows-style
+ * traversal patterns such as `..\\.system\\evil`.
+ */
+export function isSystemPath(p) {
+    return pathResolve(p).split(/[\\/]/).some((seg) => seg === ".system");
+}
+export function assertNotSystemPath(p) {
+    if (isSystemPath(p))
+        throw new SYSTEM_PATH_FORBIDDEN(p);
+}

package/dist/services/sediment/pool-read.d.ts

@@ -0,0 +1,20 @@
+import type { IndexFile } from "./types.js";
+export declare class POOL_READ_ERROR extends Error {
+}
+/** Pure read of the in-memory pool index (Critical #2 fix).
+ *
+ *  CONTRACT: this function is a READ-ONLY computation. It MUST NOT
+ *  write `index.json` (or any other file) as a side-effect. The
+ *  "self-heal" property of rewriting index.json when it goes stale
+ *  belongs to `rebuildIndexFromFs`, not here. List / search / recent /
+ *  add-* verbs that need to mutate the on-disk cache should call
+ *  `rebuildIndexFromFs` explicitly.
+ *
+ *  Edge case: if the pool root does not yet exist, this returns an
+ *  empty index WITHOUT creating the directory. Callers that need a
+ *  materialized root should use `rebuildIndexFromFs` or `mkdirSync`
+ *  themselves.
+ */
+export declare function readPool({ home }: {
+    home: string;
+}): IndexFile;