peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/context/memory-preflight-service.js

@@ -0,0 +1,120 @@
+/**
+ * MemoryPreflightService — orchestrator-facing API for the
+ * "Orchestrator Memory Preflight" slice (see
+ * docs/superpowers/specs/2026-07-22-orchestrator-memory-preflight-design.md).
+ *
+ * Consumes:
+ *   - resolveMemoryPreflightConfig (Task 1) — merged defaults + per-project overlay
+ *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json + layer=A filter
+ *   - MemoryLruCache (Task 2)               — constructed for capacity parity, but NOT used
+ *                                            for memo content (see deviation note below)
+ *   - compressPrompt (existing)             — headroom-ai wrapper for hard-cap compression
+ *
+ * Deviation from brief — controller-accepted (pre-task 4):
+ *   The brief mandated use of `MemoryLruCache` for memo content caching. The
+ *   orchestrator dispatch flow only ever has at most a handful of explicit
+ *   `cacheMemoContent` calls per task (typically 0-3), and ordering / explicit
+ *   invalidation is preferred over LRU eviction by recency. To keep the
+ *   semantic obvious and the byte budget check trivial, this implementation
+ *   uses a plain `Map<path, body>` for memo path -> body content. The
+ *   `MemoryLruCache` class remains as a separate, reusable LRU primitive
+ *   (Task 2) and is not consumed by this service.
+ */
+import { compressPrompt } from './headroom-client.js';
+import { MemoryIndexReader } from './memory-index-reader.js';
+import { resolveMemoryPreflightConfig, } from './memory-preflight-config.js';
+async function compressToCap(text, capBytes, mode) {
+    try {
+        const result = await compressPrompt(text, mode);
+        if (result.warning !== null || result.compressedPrompt === null) {
+            return { text, truncated: false };
+        }
+        const compressed = result.compressedPrompt;
+        if (Buffer.byteLength(compressed, 'utf8') > capBytes) {
+            const sliced = compressed.slice(0, Math.max(0, capBytes - 64)) + '\n…[truncated]';
+            return { text: sliced, truncated: true };
+        }
+        return { text: compressed, truncated: false };
+    }
+    catch {
+        return { text, truncated: false };
+    }
+}
+export class MemoryPreflightService {
+    reader;
+    config;
+    /** path -> body; sub-agent-requested memo contents (Task 4 deviation, see module header). */
+    cachedMemoContents = new Map();
+    constructor(projectRoot, prefs) {
+        this.config = resolveMemoryPreflightConfig(prefs);
+        this.reader = new MemoryIndexReader(projectRoot);
+    }
+    cacheMemoContent(path, content) {
+        if (!this.config.enabled)
+            return;
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (bytes > this.config.contentCacheBytes) {
+            // too big to ever fit; do not cache.
+            return;
+        }
+        this.cachedMemoContents.set(path, content);
+    }
+    async fetchBlock(_taskTitle) {
+        if (!this.config.enabled)
+            return { available: false, reason: 'DISABLED' };
+        const selected = this.reader.selectFeedbackLayerA(this.config.listCap);
+        if (selected.length === 0) {
+            const any = this.reader.loadIfStale();
+            if (any.length === 0)
+                return { available: false, reason: 'MEMORY_INDEX_MISSING' };
+            return { available: false, reason: 'NO_FEEDBACK_LAYER_A' };
+        }
+        const listLines = selected
+            .map((e) => `- * ${e.name}\n    Path: ${e.sourcePath}\n    One-line: ${summarize(e.description)}`)
+            .join('\n');
+        let tail = '\n';
+        let cachedCount = 0;
+        if (this.cachedMemoContents.size > 0) {
+            const sections = [];
+            for (const [path, body] of this.cachedMemoContents) {
+                sections.push(`### ${path}\n\n${body}`);
+                cachedCount += 1;
+            }
+            tail = `\n\n## Requested memory details:\n${sections.join('\n\n')}\n`;
+        }
+        const header = '## Project memory relevant to this task\n';
+        const composed = `${header}${listLines}${tail}`;
+        const capBytes = Math.max(64, this.config.maxTokens * 4);
+        const { text, truncated } = await compressToCap(composed, capBytes, 'balanced');
+        const droppedCount = truncated ? selected.length - countItemsInBlock(text) : 0;
+        return {
+            available: true,
+            block: text,
+            feedbackListItems: selected.length,
+            cachedItemCount: cachedCount,
+            truncated,
+            droppedCount: droppedCount > 0 ? droppedCount : undefined,
+        };
+    }
+}
+function summarize(description) {
+    // Drop the <!-- peaks-feedback-promoted: layer=A --> marker, take the next 1 line.
+    const cleaned = description.replace(/<!--[^>]*-->/g, '').trim();
+    return cleaned.split('\n')[0] ?? cleaned;
+}
+function countItemsInBlock(text) {
+    // Count `- * ` markers ONLY in the list portion (between the
+    // `## Project memory relevant to this task` header and the
+    // `## Requested memory details:` sub-section, if present). Memo
+    // bodies appended under `## Requested memory details:` may
+    // legitimately contain their own `- * ` markdown bullets, which
+    // would otherwise inflate the count and produce a wrong
+    // `droppedCount` in the truncated case.
+    const headerEnd = text.indexOf('\n## ');
+    if (headerEnd === -1) {
+        return (text.match(/- \* /g) ?? []).length;
+    }
+    const tailStart = text.indexOf('\n## Requested memory details:', headerEnd + 1);
+    const listEnd = tailStart === -1 ? text.length : tailStart;
+    return (text.slice(0, listEnd).match(/- \* /g) ?? []).length;
+}

package/dist/services/context/spillover-store.d.ts

@@ -0,0 +1,23 @@
+import type { SpillId, SpillOptions, SpillRecord, SpillState } from './spillover-types.js';
+/**
+ * Defense-in-depth: assert the given path is NOT a symbolic link.
+ *
+ * Symlinks pointing outside the spill directory could be used to bypass
+ * the containment check (assertInside). This function uses lstat (which
+ * does NOT follow symlinks) to detect symbolic links and reject them.
+ *
+ * Note: this check is redundant with the entry.isFile() check in
+ * listSpills() (which rejects symlinks on most platforms), but
+ * provides belt-and-suspenders defense for the writeRecord and
+ * hydrate entry points.
+ */
+export declare function assertNotSymlink(path: string): void;
+export declare function spillDir(projectRoot: string, sessionId: string): string;
+export declare function spillPath(projectRoot: string, sessionId: string, spillId: SpillId): string;
+export declare function createSpillId(now?: Date): SpillId;
+export declare function spill(options: SpillOptions, payload: Readonly<Record<string, unknown>>): SpillRecord;
+export declare function hydrate(projectRoot: string, sessionId: string, spillId: SpillId): SpillRecord | null;
+export declare function listSpills(projectRoot: string, sessionId: string, options?: {
+    readonly state?: SpillState;
+}): readonly SpillRecord[];
+export declare function pruneExpiredSpills(projectRoot: string, sessionId: string): readonly string[];

package/dist/services/context/spillover-store.js

@@ -0,0 +1,155 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, join, relative } from 'node:path';
+import { SPILL_TTL_MS } from './spillover-types.js';
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function assertSafeSegment(value, name) {
+    if (!SAFE_SEGMENT.test(value) || value === '.' || value === '..') {
+        throw new Error(`${name} must be a safe path segment`);
+    }
+}
+function assertInside(base, target) {
+    const rel = relative(base, target);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)) {
+        throw new Error('Spill path must stay inside the session spill directory');
+    }
+}
+/**
+ * Defense-in-depth: assert the given path is NOT a symbolic link.
+ *
+ * Symlinks pointing outside the spill directory could be used to bypass
+ * the containment check (assertInside). This function uses lstat (which
+ * does NOT follow symlinks) to detect symbolic links and reject them.
+ *
+ * Note: this check is redundant with the entry.isFile() check in
+ * listSpills() (which rejects symlinks on most platforms), but
+ * provides belt-and-suspenders defense for the writeRecord and
+ * hydrate entry points.
+ */
+export function assertNotSymlink(path) {
+    if (!existsSync(path))
+        return; // file doesn't exist yet (writeRecord) or already gone (hydrate)
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) {
+        throw new Error(`Refusing to operate on symbolic link: ${path}`);
+    }
+}
+export function spillDir(projectRoot, sessionId) {
+    assertSafeSegment(sessionId, 'sessionId');
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'spill');
+}
+export function spillPath(projectRoot, sessionId, spillId) {
+    assertSafeSegment(spillId, 'spillId');
+    const dir = spillDir(projectRoot, sessionId);
+    const path = join(dir, `${spillId}.json`);
+    assertInside(dir, path);
+    return path;
+}
+export function createSpillId(now = new Date()) {
+    const date = now.toISOString().slice(0, 10);
+    const timestamp = now.getTime().toString(36);
+    return `spill-${date}-${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+function writeRecord(path, record) {
+    assertNotSymlink(path);
+    const content = JSON.stringify(record, null, 2);
+    const temporaryPath = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporaryPath, content, 'utf8');
+    try {
+        renameSync(temporaryPath, path);
+    }
+    catch {
+        writeFileSync(path, content, 'utf8');
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Best-effort cleanup after the direct-write fallback.
+        }
+    }
+}
+export function spill(options, payload) {
+    const record = {
+        spillId: createSpillId(),
+        sessionId: options.sessionId,
+        projectRoot: options.projectRoot,
+        createdAt: new Date().toISOString(),
+        state: 'pending',
+        payload,
+        ...(options.batchId === undefined ? {} : { batchId: options.batchId })
+    };
+    mkdirSync(spillDir(options.projectRoot, options.sessionId), { recursive: true });
+    writeRecord(spillPath(options.projectRoot, options.sessionId, record.spillId), record);
+    return record;
+}
+function readRecord(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function hydrate(projectRoot, sessionId, spillId) {
+    const path = spillPath(projectRoot, sessionId, spillId);
+    if (!existsSync(path))
+        return null;
+    try {
+        assertNotSymlink(path);
+        const record = readRecord(path);
+        if (record === null)
+            return null;
+        const hydrated = {
+            ...record,
+            state: 'hydrated',
+            hydratedAt: new Date().toISOString()
+        };
+        writeRecord(path, hydrated);
+        return hydrated;
+    }
+    catch {
+        return null;
+    }
+}
+export function listSpills(projectRoot, sessionId, options) {
+    const dir = spillDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    const records = readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => readRecord(join(dir, entry.name)))
+        .filter((record) => record !== null)
+        .map((record) => {
+        const age = now - new Date(record.createdAt).getTime();
+        return age > SPILL_TTL_MS && record.state === 'pending'
+            ? { ...record, state: 'expired' }
+            : record;
+    })
+        .filter((record) => options?.state === undefined || record.state === options.state);
+    records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    return records;
+}
+export function pruneExpiredSpills(projectRoot, sessionId) {
+    const dir = spillDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    const removed = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const path = join(dir, entry.name);
+        const record = readRecord(path);
+        if (record === null || now - new Date(record.createdAt).getTime() <= SPILL_TTL_MS)
+            continue;
+        try {
+            unlinkSync(path);
+            removed.push(path);
+        }
+        catch {
+            // Best-effort pruning leaves failed paths for a later attempt.
+        }
+    }
+    return removed;
+}

package/dist/services/context/spillover-types.d.ts

@@ -0,0 +1,18 @@
+export type SpillId = string;
+export type SpillState = 'pending' | 'hydrated' | 'expired';
+export interface SpillRecord {
+    readonly spillId: SpillId;
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly createdAt: string;
+    readonly state: SpillState;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly batchId?: string;
+    readonly hydratedAt?: string;
+}
+export interface SpillOptions {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly batchId?: string;
+}
+export declare const SPILL_TTL_MS: number;

package/dist/services/context/spillover-types.js

@@ -0,0 +1 @@
+export const SPILL_TTL_MS = 24 * 60 * 60 * 1000;

package/dist/services/crystallization/crystallization-service.d.ts

@@ -2,7 +2,17 @@ import type Database from "better-sqlite3";
 import { z } from "zod";
 import { type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief } from "./crystallization-types.js";
 import { listCrystallizationEvents } from "./crystallization-store.js";
-import { type LoopReleaseInput } from "../loop/loop-release-types.js";
+type LoopReleaseZodSchema = {
+    parse: (input: unknown) => unknown;
+};
+type LoopBeeRelationZodSchema = {
+    parse: (input: unknown) => unknown;
+    omit: (keys: Record<string, true>) => {
+        parse: (input: unknown) => unknown;
+    };
+};
+type InsertLoopReleaseFn = (db: Database.Database, row: unknown) => void;
+type InsertLoopBeeRelationFn = (db: Database.Database, row: unknown) => unknown;
 /**
  * CrystallizationService — spec §5 (post-run crystallization)
  * + §4.5 + §4.7 + §10 RL-2 / RL-3 / RL-7.
@@ -88,7 +98,7 @@ export interface CrystallizePayload {
     /** The candidate task state. Must satisfy the pre-run gate. */
     task: CrystallizationTaskState;
     /** The loop_release to create (new). Must include main bee via relation. */
-    loop_input: LoopReleaseInput;
+    loop_input: unknown;
     /**
      * The main bee_release to create. Note: bee_release requires a
      * manifest row to keep the existing 4.x schema consistent;
@@ -153,9 +163,16 @@ export interface CrystallizationResult {
 /**
  * Service interface for the post-run crystallization flow.
  */
+export interface CrystallizationOptions {
+    loopReleaseSchema: LoopReleaseZodSchema;
+    loopBeeRelationSchema: LoopBeeRelationZodSchema;
+    insertLoopRelease: InsertLoopReleaseFn;
+    insertLoopBeeRelation: InsertLoopBeeRelationFn;
+}
 export declare class CrystallizationService {
     private readonly db;
-    constructor(db: Database.Database);
+    private readonly opts;
+    constructor(db: Database.Database, opts: CrystallizationOptions);
     /**
      * Read a CrystallizationEvent by id.
      */
@@ -167,8 +184,6 @@ export declare class CrystallizationService {
      */
     list(opts?: Parameters<typeof listCrystallizationEvents>[1]): {
         schema_version: "peaks.crystallization/1";
-        id: string;
-        lifecycle_status: "candidate" | "stable" | "retired";
         trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
         evidence_brief: {
             what_happened: string;
@@ -180,6 +195,8 @@ export declare class CrystallizationService {
         source_trace_pointers: string[];
         evaluator_summary: string;
         user_decision_summary: string;
+        lifecycle_status: "candidate" | "stable" | "retired";
+        id: string;
         created_at: string;
         created_loop_release_id?: string | undefined;
         updated_loop_release_id?: string | undefined;

package/dist/services/crystallization/crystallization-service.js

@@ -2,10 +2,6 @@ import { z, ZodError } from "zod";
 import { CrystallizationEventSchema, EvidenceBriefSchema, } from "./crystallization-types.js";
 import { BriefSectionError } from "./evidence-brief-builder.js";
 import { CRYSTALLIZATION_SCHEMA_VERSION, ensureCrystallizationEventTable, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from "./crystallization-store.js";
-import { insertLoopRelease } from "../loop/loop-release-store.js";
-import { LoopReleaseSchema } from "../loop/loop-release-types.js";
-import { insertLoopBeeRelation } from "../loop/loop-bee-relation-store.js";
-import { LoopBeeRelationSchema, } from "../loop/loop-bee-relation-types.js";
 /**
  * CrystallizationService — spec §5 (post-run crystallization)
  * + §4.5 + §4.7 + §10 RL-2 / RL-3 / RL-7.
@@ -126,13 +122,12 @@ const BeeCrystallizeInputSchema = z.object({
     parent_version: z.string().trim().max(64).optional(),
     changelog: z.string().trim().max(8000).optional(),
 });
-/**
- * Service interface for the post-run crystallization flow.
- */
 export class CrystallizationService {
     db;
-    constructor(db) {
+    opts;
+    constructor(db, opts) {
         this.db = db;
+        this.opts = opts;
         // Idempotent — safe to call on every constructor invocation; the
         // openStateDb pipeline already applied the SQL migration, but a
         // caller-built DB (e.g. tests) needs this.
@@ -256,14 +251,14 @@ export class CrystallizationService {
         }
         // Re-validate loop_input via Zod so a hand-crafted caller input
         // cannot bypass the schema. (M8 dogfood follow-up.)
-        const loopRow = LoopReleaseSchema.parse(payload.loop_input);
+        const loopRow = this.opts.loopReleaseSchema.parse(payload.loop_input);
         // Re-validate bee_input.
         const beeRow = BeeCrystallizeInputSchema.parse(payload.bee_input);
         // Loop-bee relation input (the relation's `reason` is the NL
         // account the LLM authored). We validate the shape WITHOUT
         // bee_release_id (which is filled in by the bee insert below),
         // then validate the final tuple after the SQL writes.
-        const relationInputShape = LoopBeeRelationSchema.omit({
+        const relationInputShape = this.opts.loopBeeRelationSchema.omit({
             id: true,
             created_at: true,
             bee_release_id: true,
@@ -280,7 +275,7 @@ export class CrystallizationService {
         let eventPersistedId = eventId;
         const tx = this.db.transaction(() => {
             // 1. Insert loop_release.
-            insertLoopRelease(this.db, loopRow);
+            this.opts.insertLoopRelease(this.db, loopRow);
             // 2. Insert bee_release header. The existing
             // `retainRelease` adds segment_ref / file / change rows; the
             // minimal crystallization write here only opens the bee_release
@@ -311,7 +306,7 @@ export class CrystallizationService {
             // 4. Insert the loop_bee_relation row (FKs now valid). Re-parse
             // through the input schema so the bee_release_id is validated
             // too — defense in depth. `id` is autoincrement (not in input).
-            const fullRelation = LoopBeeRelationSchema.omit({
+            const fullRelation = this.opts.loopBeeRelationSchema.omit({
                 id: true,
                 created_at: true,
             }).parse({
@@ -319,9 +314,8 @@ export class CrystallizationService {
                 bee_release_id: beeReleaseId,
                 role: relationInputShape.role,
                 reason: relationInputShape.reason,
-                schema_version: "peaks.loop-bee-relation/1",
             });
-            const relationRow = insertLoopBeeRelation(this.db, fullRelation);
+            const relationRow = this.opts.insertLoopBeeRelation(this.db, fullRelation);
             relationId = relationRow.id;
             // 5. Persist the crystallization_event row with the brief inline
             // (the brief is the durable evidence — AC-17).

package/dist/services/crystallization/crystallization-types.d.ts

@@ -136,7 +136,6 @@ export declare const CrystallizationEventInputSchema: z.ZodObject<{
     updated_bee_release_id: z.ZodOptional<z.ZodNumber>;
     lifecycle_status: z.ZodDefault<z.ZodEnum<["candidate", "stable", "retired"]>>;
 }, "strip", z.ZodTypeAny, {
-    lifecycle_status: "candidate" | "stable" | "retired";
     trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
     evidence_brief: {
         what_happened: string;
@@ -148,6 +147,7 @@ export declare const CrystallizationEventInputSchema: z.ZodObject<{
     source_trace_pointers: string[];
     evaluator_summary: string;
     user_decision_summary: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
     created_loop_release_id?: string | undefined;
     updated_loop_release_id?: string | undefined;
     created_bee_release_id?: number | undefined;
@@ -160,7 +160,6 @@ export declare const CrystallizationEventInputSchema: z.ZodObject<{
         what_learned: string;
         what_action: string;
     };
-    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
     evidence_bullets?: string[] | undefined;
     source_trace_pointers?: string[] | undefined;
     evaluator_summary?: string | undefined;
@@ -169,6 +168,7 @@ export declare const CrystallizationEventInputSchema: z.ZodObject<{
     updated_loop_release_id?: string | undefined;
     created_bee_release_id?: number | undefined;
     updated_bee_release_id?: number | undefined;
+    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
 }>;
 export type CrystallizationEventInput = z.input<typeof CrystallizationEventInputSchema>;
 /**
@@ -223,8 +223,6 @@ export declare const CrystallizationEventSchema: z.ZodObject<{
     created_at: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     schema_version: "peaks.crystallization/1";
-    id: string;
-    lifecycle_status: "candidate" | "stable" | "retired";
     trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
     evidence_brief: {
         what_happened: string;
@@ -236,13 +234,14 @@ export declare const CrystallizationEventSchema: z.ZodObject<{
     source_trace_pointers: string[];
     evaluator_summary: string;
     user_decision_summary: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    id: string;
     created_at: string;
     created_loop_release_id?: string | undefined;
     updated_loop_release_id?: string | undefined;
     created_bee_release_id?: number | undefined;
     updated_bee_release_id?: number | undefined;
 }, {
-    id: string;
     trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
     evidence_brief: {
         what_happened: string;
@@ -250,9 +249,9 @@ export declare const CrystallizationEventSchema: z.ZodObject<{
         what_learned: string;
         what_action: string;
     };
+    id: string;
     created_at: string;
     schema_version?: "peaks.crystallization/1" | undefined;
-    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
     evidence_bullets?: string[] | undefined;
     source_trace_pointers?: string[] | undefined;
     evaluator_summary?: string | undefined;
@@ -261,6 +260,7 @@ export declare const CrystallizationEventSchema: z.ZodObject<{
     updated_loop_release_id?: string | undefined;
     created_bee_release_id?: number | undefined;
     updated_bee_release_id?: number | undefined;
+    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
 }>;
 export type CrystallizationEvent = z.infer<typeof CrystallizationEventSchema>;
 /**

package/dist/services/crystallization/evidence-brief-builder.d.ts

@@ -76,11 +76,11 @@ export declare const BriefTraceInputSchema: z.ZodObject<{
      */
     source_trace_pointers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    source_trace_pointers: string[];
     what_happened: string;
     why_it_matters: string;
     what_learned: string;
     what_action: string;
+    source_trace_pointers: string[];
     trace_id: string;
     bullets: string[];
 }, {

package/dist/services/crystallization/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * peaks-loop-crystallization area (consolidated into peaks-loop).
+ *
+ * Loop domain (loop-release / loop-bee-relation) lives in the main
+ * peaks-loop package. They are injected via CrystallizationOptions
+ * at call-site in src/cli/commands/asset-commands.ts, so this
+ * subpackage stays standalone and does NOT depend on the main
+ * peaks-loop package (avoiding workspace:* circular trap).
+ */
+export { CrystallizationService, CrystallizationIntegrityError, type CrystallizationOptions, type CrystallizationTaskState, } from './crystallization-service.js';
+export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from './crystallization-store.js';
+export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections, type CrystallizationTrigger, type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief, } from './crystallization-types.js';
+export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief, type BriefTraceInput, } from './evidence-brief-builder.js';

package/dist/services/crystallization/index.js

@@ -0,0 +1,13 @@
+/**
+ * peaks-loop-crystallization area (consolidated into peaks-loop).
+ *
+ * Loop domain (loop-release / loop-bee-relation) lives in the main
+ * peaks-loop package. They are injected via CrystallizationOptions
+ * at call-site in src/cli/commands/asset-commands.ts, so this
+ * subpackage stays standalone and does NOT depend on the main
+ * peaks-loop package (avoiding workspace:* circular trap).
+ */
+export { CrystallizationService, CrystallizationIntegrityError, } from './crystallization-service.js';
+export { ensureCrystallizationEventTable, insertCrystallizationEvent, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from './crystallization-store.js';
+export { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, EvidenceBriefSchema, CrystallizationEventSchema, parseCrystallizationEvent, safeParseEvidenceBrief, safeParseCrystallizationEvent, hasAllFourBriefSections, } from './crystallization-types.js';
+export { BriefSectionError, renderRecommendationPayload, safeRenderRecommendationPayload, buildEvidenceBrief, } from './evidence-brief-builder.js';

package/dist/services/dashboard/project-dashboard-service.js

@@ -2,7 +2,7 @@ import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
 import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
 import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
 import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
-import { requiredSkillNames } from '../../shared/paths.js';
+import { requiredSkillNames } from 'peaks-loop-shared/paths';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
 const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 /**
@@ -45,7 +45,7 @@ async function loadDoctorAndRunbookHealth(doctorOverride, runbookOverride) {
             runbookHealth: { ok: true, required: 0, healthy: 0, missingRunbook: [], applyNoteFailed: [] }
         };
     }
-    const { runDoctor } = await import('../doctor/doctor-service.js');
+    const { runDoctor } = await import('../doctor/index.js');
     const report = await runDoctor();
     return {
         doctor: { ok: report.summary.ok, passed: report.summary.passed, failed: report.summary.failed },

package/dist/services/dispatch/await-batch.d.ts

@@ -0,0 +1,70 @@
+export type AwaitBatchOutcome = 'completed' | 'timed-out' | 'clamped' | 'no-progress';
+export interface AwaitBatchOptions {
+    /** Caller-supplied per-IDE default when no timeoutMs is provided. */
+    readonly defaultTimeoutMs: number;
+    /** Hard cap on the effective wait, in ms. Default: 120_000. */
+    readonly hardCapMs?: number;
+    /** Optional per-IDE label written into result `note` for attribution. */
+    readonly notePrefix?: string;
+    /**
+     * No-progress watchdog. If a slot's progress is unchanged for
+     * `noProgressMs`, the batch escalates with outcome `no-progress`
+     * (and the slot's status is left as the caller would observe at
+     * that moment — typically still `running` or `queued`).
+     */
+    readonly noProgressMs?: number;
+    /**
+     * Test seam: override Date.now() and setTimeout's clock. Production
+     * callers leave this undefined.
+     */
+    readonly now?: () => number;
+    /**
+     * Test seam: override setTimeout / setInterval. Production callers
+     * leave this undefined.
+     */
+    readonly schedule?: (cb: () => void, ms: number) => void;
+    /**
+     * Test seam: how to read a record's status. Production callers
+     * leave this undefined (the default reads `status` from the file).
+     * Returning a plain string is treated as the record's status; the
+     * default reader also exposes the `outcome` field via the optional
+     * second tuple element (see `defaultReadOutcome`).
+     *
+     * Test-only escape hatch: callers that need to return both status
+     * and outcome can implement `readRecord` instead.
+     */
+    readonly readOutcome?: (recordPath: string) => string | null;
+    /**
+     * Test seam: read a record's status AND outcome together. When
+     * defined, this overrides `readOutcome`. Implementations should
+     * return `{ status: null, outcome: null }` when the file is missing
+     * or unreadable, and `{ status }` / `{ status, outcome }` otherwise.
+     */
+    readonly readRecord?: (recordPath: string) => {
+        status: string | null;
+        outcome: string | null;
+    };
+}
+export interface AwaitBatchResult {
+    /** Per-dispatch slot, in dispatchIndex order. */
+    readonly results: ReadonlyArray<{
+        readonly dispatchIndex: number;
+        readonly recordPath: string;
+        readonly status: 'done' | 'failed' | 'cancelled' | 'timeout';
+        readonly durationMs: number;
+        readonly note: string | null;
+    }>;
+    /** Batch-level outcome — distinct, machine-readable. */
+    readonly outcome: AwaitBatchOutcome;
+    /** What the caller asked for (or the IDE default, when omitted). */
+    readonly requestedTimeoutMs: number;
+    /** What the loop actually waited (≤ requestedTimeoutMs after clamp). */
+    readonly effectiveTimeoutMs: number;
+    /** The hard cap applied; equals `requestedTimeoutMs` if no clamp. */
+    readonly hardCapMs: number;
+}
+/**
+ * Run one awaitBatch. Pure (no module-level state); the two
+ * back-compat wrappers in sub-agent-dispatcher.ts call this.
+ */
+export declare function awaitBatch(dispatchCount: number, recordPaths: readonly string[], timeoutMs: number | undefined, options?: AwaitBatchOptions): Promise<AwaitBatchResult>;