peaks-loop 4.0.29 → 4.0.30

package/dist/services/code/auto-compact-lifecycle.js

@@ -0,0 +1,235 @@
+/**
+ * Auto-compact lifecycle telemetry (v2.13.0 AC-2 + AC-3 + AC-4,
+ * slice 2026-08-01-compact-lifecycle Task 5).
+ *
+ * Extracted from `auto-compact-orchestrator.ts` to keep that file under
+ * the 800 LOC cap (mechanical verbatim move). Publishes the stages a
+ * compact attempt actually PROVED in-process (`queued` / `preparing` /
+ * `compacting`) plus the terminal `failed` stage, and settles an open
+ * `compacting` run using a real post-compact measurement. Telemetry is
+ * strictly subordinate to the compact itself: every write is best-effort
+ * and never changes the threshold decision, the dispatch, or the
+ * returned envelope.
+ */
+import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
+/**
+ * PRD-002b slice 2 — extract the few cross-cutting magic numbers
+ * that actually appear at runtime call sites in this orchestrator.
+ * Threshold ratios (0.85 / 0.95) live in `auto-compact-types.ts`
+ * and are NOT extracted here because they ARE the contract; comment
+ * + spec prose references must keep the literal value visible.
+ */
+const COLLAPSED_ERROR_MAX_CHARS = 160;
+/**
+ * One id per compact attempt. Timestamp-prefixed so a human reading
+ * the raw record can order runs by eye; the random suffix keeps two
+ * attempts inside the same millisecond distinct.
+ */
+export function newCompactRunId(now) {
+    const stamp = now.toISOString().replace(/[:.]/g, '-');
+    const suffix = Math.random().toString(16).slice(2, 8);
+    return `compact-${stamp}-${suffix}`;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): read an open compact
+ * record ignoring staleness.
+ *
+ * The lifecycle store classifies an active record as `stalled` after a
+ * caller-supplied `staleAfterMs` window. That classification exists for
+ * the statusline renderer (Task 2/3) — it tells the user "this run
+ * hasn't heartbeated for a while".
+ *
+ * For settling a run by measurement, staleness is irrelevant: if a
+ * record exists at `compacting`, a post-compact probe that measures a
+ * drop should still complete it, even if the probe itself ran hours
+ * later. Wrapping that unbounded read here keeps the magic number out
+ * of the settle path and makes the intent self-documenting.
+ *
+ * Returns `null` for any non-`valid` kind (missing / invalid /
+ * stalled). Errors from the underlying read are swallowed — settling
+ * is best-effort telemetry and must never bubble.
+ */
+function readOpenCompactLifecycle(input) {
+    let out;
+    try {
+        out = readCompactLifecycle({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            nowMs: Date.now(),
+            // Number.MAX_SAFE_INTEGER disables the store's staleness gate
+            // for this call — see the doc comment above for why settling
+            // intentionally ignores staleness.
+            staleAfterMs: Number.MAX_SAFE_INTEGER
+        });
+    }
+    catch {
+        return null;
+    }
+    return out.kind === 'valid' ? out.record : null;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
+ * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
+ * the run that opened, and remembers the prior stage so a failure can
+ * name the stage it died in.
+ *
+ * TRUTHFULNESS: this publisher only ever emits a stage the calling
+ * process has actually PROVED. It never emits `verifying` or
+ * `completed` off the back of a successful dispatch — see
+ * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
+ *
+ * Telemetry is strictly subordinate to the compact itself: every write
+ * is best-effort, and a store failure must not change the threshold
+ * decision, the dispatch, or the returned envelope.
+ */
+export class CompactLifecyclePublisher {
+    ctx;
+    lastStage = 'queued';
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Publish an active stage the process has proved. */
+    advance(stage) {
+        this.lastStage = stage;
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine
+        });
+    }
+    /** Publish the terminal failure, attributed to the last stage reached. */
+    fail(error) {
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage: 'failed',
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine,
+            failedAt: this.lastStage,
+            errorSummary: summarizeLifecycleError(error)
+        });
+    }
+    write(record) {
+        try {
+            if (this.ctx.failLifecycleWrite)
+                throw new Error('lifecycle store unavailable');
+            writeCompactLifecycle({
+                projectRoot: this.ctx.projectRoot,
+                sessionId: this.ctx.sessionId,
+                record
+            });
+        }
+        catch {
+            // Best-effort telemetry: a lifecycle write failure must never
+            // change the compact decision, the dispatch, or the envelope.
+            return;
+        }
+        try {
+            this.ctx.onLifecycleStage?.(record.stage, record);
+        }
+        catch {
+            // An observer is a passive listener; its failure is not ours.
+        }
+    }
+}
+/**
+ * Reduce an arbitrary thrown value to a single-line, bounded summary
+ * fit for a statusline. Stack frames are dropped (the record is a
+ * human-facing indicator, not a crash dump); the store clamps the
+ * result to its own 160-character cap as a second line of defence.
+ *
+ * `null` / `undefined` thrown values — a real possibility from
+ * `Promise.reject(null)` or a thrown `undefined` — must not collapse
+ * to the empty string, which the store would then reject as missing.
+ * They map to a fixed "unknown error" sentinel so the record always
+ * carries some diagnostic text.
+ */
+export function summarizeLifecycleError(error) {
+    let raw;
+    if (error instanceof Error)
+        raw = error.message;
+    else if (error === null || error === undefined)
+        raw = 'unknown error';
+    else
+        raw = String(error);
+    if (raw.length === 0)
+        raw = 'unknown error';
+    const firstLine = raw.split('\n')[0] ?? '';
+    const collapsed = firstLine.replace(/\s+/g, ' ').trim();
+    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > COLLAPSED_ERROR_MAX_CHARS ? collapsed.slice(0, COLLAPSED_ERROR_MAX_CHARS) : collapsed);
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
+ * open compact run using a REAL measurement.
+ *
+ * This is the integration with the actual post-compact detection path.
+ * The claude-code adapter's `postCompactDetectCommand` is
+ * `peaks compact auto --json` — i.e. the next probe through this very
+ * function. So when a probe finds a run still sitting at `compacting`
+ * and MEASURES a ratio that has dropped below the auto-fire threshold,
+ * that measurement is the proof the compact landed. Only then do we
+ * emit `verifying` (we have a measurement in hand) followed by
+ * `completed` (it confirms the drop), carrying the measured
+ * `afterRatio`.
+ *
+ * We refuse to complete when:
+ *   - the probe could not measure anything (`conservative-fallback`
+ *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
+ *     `afterRatio: 0` there would publish a fabricated number;
+ *   - the ratio is still at or above the auto-fire threshold — the
+ *     compact has not landed, so the run stays open.
+ */
+export function settleOpenLifecycleRun(input) {
+    // A `conservative-fallback` probe means no signal was available at
+    // all. Its `ratio: 0` is the absence of a measurement, so it can
+    // never be evidence that the context shrank.
+    if (input.source === 'conservative-fallback')
+        return;
+    if (input.measuredRatio >= input.autoFireThreshold)
+        return;
+    const prior = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    if (prior === null)
+        return;
+    // Only a run that was actually dispatched (`compacting`) can be
+    // completed by a post-compact measurement.
+    if (prior.stage !== 'compacting')
+        return;
+    const emit = (stage, withAfterRatio) => {
+        const record = {
+            schemaVersion: 1,
+            runId: prior.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: prior.triggerRatio,
+            redLine: prior.redLine,
+            ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
+        };
+        try {
+            writeCompactLifecycle({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                record
+            });
+        }
+        catch {
+            return;
+        }
+        try {
+            input.onLifecycleStage?.(stage, record);
+        }
+        catch {
+            // Observer failures are not ours to propagate.
+        }
+    };
+    // `verifying` = we hold a measurement and are checking it.
+    emit('verifying', false);
+    // `completed` = the measurement confirms the drop; publish it.
+    emit('completed', true);
+}

package/dist/services/code/auto-compact-orchestrator.d.ts

@@ -1,7 +1,7 @@
 import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
 import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
 import { type AutoCompactMode } from './auto-compact-modes.js';
-import { type CompactLifecycleRecord, type CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
+import type { CompactLifecycleRecord, CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
 export interface AutoCompactInput {
     /** Project root for context (default cwd). */
     readonly projectRoot: string;

package/dist/services/code/auto-compact-orchestrator.js

@@ -35,16 +35,8 @@ import { resolveOuterSessionId } from '../session/binding-status-service.js';
 import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
 import { describeMode, thresholdFor } from './auto-compact-modes.js';
 import { read24hState } from '../24h-mode/store.js';
-import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
+import { CompactLifecyclePublisher, newCompactRunId, settleOpenLifecycleRun, summarizeLifecycleError } from './auto-compact-lifecycle.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
-/**
- * PRD-002b slice 2 — extract the few cross-cutting magic numbers
- * that actually appear at runtime call sites in this orchestrator.
- * Threshold ratios (0.85 / 0.95) live in `auto-compact-types.ts`
- * and are NOT extracted here because they ARE the contract; comment
- * + spec prose references must keep the literal value visible.
- */
-const COLLAPSED_ERROR_MAX_CHARS = 160;
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
  * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
@@ -278,219 +270,6 @@ function resolveAutoCompactMode(projectRoot, sessionId) {
         return 'standard';
     }
 }
-/**
- * One id per compact attempt. Timestamp-prefixed so a human reading
- * the raw record can order runs by eye; the random suffix keeps two
- * attempts inside the same millisecond distinct.
- */
-function newCompactRunId(now) {
-    const stamp = now.toISOString().replace(/[:.]/g, '-');
-    const suffix = Math.random().toString(16).slice(2, 8);
-    return `compact-${stamp}-${suffix}`;
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5): read an open compact
- * record ignoring staleness.
- *
- * The lifecycle store classifies an active record as `stalled` after a
- * caller-supplied `staleAfterMs` window. That classification exists for
- * the statusline renderer (Task 2/3) — it tells the user "this run
- * hasn't heartbeated for a while".
- *
- * For settling a run by measurement, staleness is irrelevant: if a
- * record exists at `compacting`, a post-compact probe that measures a
- * drop should still complete it, even if the probe itself ran hours
- * later. Wrapping that unbounded read here keeps the magic number out
- * of the settle path and makes the intent self-documenting.
- *
- * Returns `null` for any non-`valid` kind (missing / invalid /
- * stalled). Errors from the underlying read are swallowed — settling
- * is best-effort telemetry and must never bubble.
- */
-function readOpenCompactLifecycle(input) {
-    let out;
-    try {
-        out = readCompactLifecycle({
-            projectRoot: input.projectRoot,
-            sessionId: input.sessionId,
-            nowMs: Date.now(),
-            // Number.MAX_SAFE_INTEGER disables the store's staleness gate
-            // for this call — see the doc comment above for why settling
-            // intentionally ignores staleness.
-            staleAfterMs: Number.MAX_SAFE_INTEGER
-        });
-    }
-    catch {
-        return null;
-    }
-    return out.kind === 'valid' ? out.record : null;
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
- * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
- * the run that opened, and remembers the prior stage so a failure can
- * name the stage it died in.
- *
- * TRUTHFULNESS: this publisher only ever emits a stage the calling
- * process has actually PROVED. It never emits `verifying` or
- * `completed` off the back of a successful dispatch — see
- * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
- *
- * Telemetry is strictly subordinate to the compact itself: every write
- * is best-effort, and a store failure must not change the threshold
- * decision, the dispatch, or the returned envelope.
- */
-class CompactLifecyclePublisher {
-    ctx;
-    lastStage = 'queued';
-    constructor(ctx) {
-        this.ctx = ctx;
-    }
-    /** Publish an active stage the process has proved. */
-    advance(stage) {
-        this.lastStage = stage;
-        this.write({
-            schemaVersion: 1,
-            runId: this.ctx.runId,
-            stage,
-            updatedAt: new Date().toISOString(),
-            triggerRatio: this.ctx.triggerRatio,
-            redLine: this.ctx.redLine
-        });
-    }
-    /** Publish the terminal failure, attributed to the last stage reached. */
-    fail(error) {
-        this.write({
-            schemaVersion: 1,
-            runId: this.ctx.runId,
-            stage: 'failed',
-            updatedAt: new Date().toISOString(),
-            triggerRatio: this.ctx.triggerRatio,
-            redLine: this.ctx.redLine,
-            failedAt: this.lastStage,
-            errorSummary: summarizeLifecycleError(error)
-        });
-    }
-    write(record) {
-        try {
-            if (this.ctx.failLifecycleWrite)
-                throw new Error('lifecycle store unavailable');
-            writeCompactLifecycle({
-                projectRoot: this.ctx.projectRoot,
-                sessionId: this.ctx.sessionId,
-                record
-            });
-        }
-        catch {
-            // Best-effort telemetry: a lifecycle write failure must never
-            // change the compact decision, the dispatch, or the envelope.
-            return;
-        }
-        try {
-            this.ctx.onLifecycleStage?.(record.stage, record);
-        }
-        catch {
-            // An observer is a passive listener; its failure is not ours.
-        }
-    }
-}
-/**
- * Reduce an arbitrary thrown value to a single-line, bounded summary
- * fit for a statusline. Stack frames are dropped (the record is a
- * human-facing indicator, not a crash dump); the store clamps the
- * result to its own 160-character cap as a second line of defence.
- *
- * `null` / `undefined` thrown values — a real possibility from
- * `Promise.reject(null)` or a thrown `undefined` — must not collapse
- * to the empty string, which the store would then reject as missing.
- * They map to a fixed "unknown error" sentinel so the record always
- * carries some diagnostic text.
- */
-function summarizeLifecycleError(error) {
-    let raw;
-    if (error instanceof Error)
-        raw = error.message;
-    else if (error === null || error === undefined)
-        raw = 'unknown error';
-    else
-        raw = String(error);
-    if (raw.length === 0)
-        raw = 'unknown error';
-    const firstLine = raw.split('\n')[0] ?? '';
-    const collapsed = firstLine.replace(/\s+/g, ' ').trim();
-    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > COLLAPSED_ERROR_MAX_CHARS ? collapsed.slice(0, COLLAPSED_ERROR_MAX_CHARS) : collapsed);
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
- * open compact run using a REAL measurement.
- *
- * This is the integration with the actual post-compact detection path.
- * The claude-code adapter's `postCompactDetectCommand` is
- * `peaks compact auto --json` — i.e. the next probe through this very
- * function. So when a probe finds a run still sitting at `compacting`
- * and MEASURES a ratio that has dropped below the auto-fire threshold,
- * that measurement is the proof the compact landed. Only then do we
- * emit `verifying` (we have a measurement in hand) followed by
- * `completed` (it confirms the drop), carrying the measured
- * `afterRatio`.
- *
- * We refuse to complete when:
- *   - the probe could not measure anything (`conservative-fallback`
- *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
- *     `afterRatio: 0` there would publish a fabricated number;
- *   - the ratio is still at or above the auto-fire threshold — the
- *     compact has not landed, so the run stays open.
- */
-function settleOpenLifecycleRun(input) {
-    // A `conservative-fallback` probe means no signal was available at
-    // all. Its `ratio: 0` is the absence of a measurement, so it can
-    // never be evidence that the context shrank.
-    if (input.source === 'conservative-fallback')
-        return;
-    if (input.measuredRatio >= input.autoFireThreshold)
-        return;
-    const prior = readOpenCompactLifecycle({
-        projectRoot: input.projectRoot,
-        sessionId: input.sessionId
-    });
-    if (prior === null)
-        return;
-    // Only a run that was actually dispatched (`compacting`) can be
-    // completed by a post-compact measurement.
-    if (prior.stage !== 'compacting')
-        return;
-    const emit = (stage, withAfterRatio) => {
-        const record = {
-            schemaVersion: 1,
-            runId: prior.runId,
-            stage,
-            updatedAt: new Date().toISOString(),
-            triggerRatio: prior.triggerRatio,
-            redLine: prior.redLine,
-            ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
-        };
-        try {
-            writeCompactLifecycle({
-                projectRoot: input.projectRoot,
-                sessionId: input.sessionId,
-                record
-            });
-        }
-        catch {
-            return;
-        }
-        try {
-            input.onLifecycleStage?.(stage, record);
-        }
-        catch {
-            // Observer failures are not ours to propagate.
-        }
-    };
-    // `verifying` = we hold a measurement and are checking it.
-    emit('verifying', false);
-    // `completed` = the measurement confirms the drop; publish it.
-    emit('completed', true);
-}
 /**
  * Execute the auto-compact flow.
  *

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -42,6 +42,32 @@ export interface DispatchPromptInput {
      *   and the memory/task content.
      */
     codegraphBlock?: string | null;
+    /**
+     * Slice 2026-09-06-ui-lib-dispatch-priority: pre-composed
+     * `## Project stack` markdown block, rendered from the detected
+     * project context (component library + CSS framework + build tool) by
+     * the dispatch site BEFORE the sub-agent's task body is composed so
+     * the RD/UI sub-agent sees the library-first directive in-context.
+     *
+     * - `undefined` → no project-stack block (legacy callers unchanged).
+     * - `null` → the project has no detected component library; the
+     *   composer renders nothing (byte-identical degradation).
+     * - `string` → the block, rendered verbatim between the codegraph
+     *   block and the memory/task content.
+     */
+    projectStackBlock?: string | null;
+    /**
+     * Slice 2026-09-07-search-first-preflight: the orchestrator-synthesized
+     * `## Fresh context` block (≤5 binding directives from a Context7 →
+     * WebSearch preflight), read from `.peaks/_runtime/<sessionId>/fresh-context.md`.
+     *
+     * - `undefined` → no fresh-context block (legacy callers unchanged).
+     * - `null` → the block is unavailable (missing file / no `## Fresh context`
+     *   heading); the composer renders nothing (byte-identical degradation).
+     * - `string` → the block, rendered verbatim after the project-stack block
+     *   and before the memory/task content.
+     */
+    freshContextBlock?: string | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance

package/dist/services/context/build-dispatch-system-prompt.js

@@ -98,13 +98,15 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe, codegraphBlock } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
+    const projectStackText = renderProjectStackBlock(projectStackBlock);
+    const freshContextText = renderFreshContextBlock(freshContextBlock);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${taskBody}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${taskBody}`;
 }
 /**
  * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
@@ -133,6 +135,39 @@ function renderCodegraphBlock(codegraphBlock) {
     const text = codegraphBlock === null ? CODEGRAPH_UNAVAILABLE_BLOCK : codegraphBlock;
     return `${text.replace(/\s+$/, '')}\n\n`;
 }
+/**
+ * Render the project-stack insertion for a dispatch prompt.
+ *
+ * - `undefined` / `null` → empty (the composer is byte-identical to the
+ *   legacy shape — no dangling "Project stack" heading).
+ * - `string` → the pre-composed block from the dispatch site, verbatim.
+ *
+ * Mirrors `renderCodegraphBlock`: every non-empty variant is normalized
+ * to end on its own paragraph (`\n\n`) so the following block (project
+ * memory or task body) starts cleanly.
+ */
+function renderProjectStackBlock(projectStackBlock) {
+    if (projectStackBlock === undefined || projectStackBlock === null)
+        return '';
+    return `${projectStackBlock.replace(/\s+$/, '')}\n\n`;
+}
+/**
+ * Render the fresh-context insertion for a dispatch prompt.
+ *
+ * - `undefined` / `null` → empty (the composer is byte-identical to the
+ *   legacy shape — no dangling "Fresh context" heading).
+ * - `string` → the pre-composed block from the fresh-context preflight
+ *   synthesis, verbatim.
+ *
+ * Mirrors `renderProjectStackBlock`: every non-empty variant is normalized
+ * to end on its own paragraph (`\n\n`) so the following block (project
+ * memory or task body) starts cleanly.
+ */
+function renderFreshContextBlock(freshContextBlock) {
+    if (freshContextBlock === undefined || freshContextBlock === null)
+        return '';
+    return `${freshContextBlock.replace(/\s+$/, '')}\n\n`;
+}
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a
  * `## Context window` block with the authoritative ratio so the