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

package/dist/{src/services → services}/config/model-routing.d.ts

@@ -52,6 +52,15 @@ export declare function getStrongestModelIdAsync(config?: {
     model?: unknown;
 }, runtimeProbeDisabled?: boolean): Promise<string>;
 export declare function getConfiguredExecutionModelId(providers: ModelProviderConfig | undefined): string;
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export declare class ProviderNotConfiguredError extends Error {
+    constructor(message?: string);
+}
 export declare function getEconomyAwareExecutionModelId(config: Pick<PeaksConfig, 'economyMode' | 'providers'> & {
     model?: string;
 }): string;

package/dist/{src/services → services}/config/model-routing.js

@@ -68,7 +68,7 @@ export async function getStrongestModelIdAsync(config, runtimeProbeDisabled = fa
             if (probed && probed.length > 0)
                 return probed;
         }
-        catch {
+        catch { // TODO(g2): best-effort runtime probe — fall through to back-compat default is intentional
             // best-effort — fall through to back-compat default
         }
     }
@@ -80,10 +80,22 @@ export function getConfiguredExecutionModelId(providers) {
         .map((provider) => provider?.model?.trim())
         .find((model) => typeof model === 'string' && model.length > 0);
     if (!configuredModel) {
-        throw new Error('Execution model must be configured in providers');
+        throw new ProviderNotConfiguredError();
     }
     return configuredModel;
 }
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export class ProviderNotConfiguredError extends Error {
+    constructor(message = 'Execution model must be configured in providers') {
+        super(message);
+        this.name = 'ProviderNotConfiguredError';
+    }
+}
 export function getEconomyAwareExecutionModelId(config) {
     // Slice 2.0.1-bug1 round 3: economy is the project default. Treat undefined as enabled
     // (matches the pre-slice implicit default from DEFAULT_CONFIG.economyMode = true). Only an

package/dist/{src/services → services}/filesystem/file-lock.js

@@ -54,21 +54,44 @@ export function withFileLockSync(filePath, fn) {
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
+    // Wall-clock guard (slice 014): in pathological slow-system cases, the
+    // retry backoff could push wall-clock above LOCK_STALE_MS. Cap the loop at
+    // LOCK_STALE_MS regardless of attempts; throw the existing LockTimeoutError.
+    //
+    // Slice 2026-07-12-fix note: the slice 014 implementation re-checked
+    // `isStaleLock(lockPath)` at the TOP of every loop iteration. Under
+    // vitest-on-Windows slowdown (each `spinSleep` actually waits hundreds of
+    // ms because of event-loop preemption), the wall clock would cross
+    // `LOCK_STALE_MS` mid-loop and the reaper would unlink a still-fresh
+    // lock — `file-lock.test.ts` "does NOT reap a fresh .lock (<30s old)"
+    // caught this: the lock was reaped at iter ~54 after 30s of retries,
+    // defeating the test that asserts the fresh lock should block. The fix
+    // is to check staleness ONCE, before the loop, and inside the loop
+    // only retry on EEXIST. A crashed previous holder is reaped at entry;
+    // after we begin the retry-backoff phase, the lock is by definition
+    // non-stale (or absent after a race with another reaper), so a stale
+    // check on each iteration only adds risk of spuriously reaping a lock
+    // we just decided was live.
+    const startedAt = Date.now();
     let attempts = 0;
     let fd = null;
+    // One-shot stale reap before the loop: if a previous holder crashed and
+    // left the lock older than LOCK_STALE_MS, unlink it now so the first
+    // `openSync(lockPath, 'wx')` attempt can succeed.
+    if (isStaleLock(lockPath)) {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // race: another process reaped it; loop will try to acquire directly.
+        }
+    }
     while (attempts < MAX_LOCK_RETRIES) {
-        // Stale-lock reap: if the lock file is older than LOCK_STALE_MS, the
-        // previous holder must have crashed. Unlink and retry without
-        // counting this attempt against MAX_LOCK_RETRIES (only EEXIST from
-        // a non-stale holder consumes a retry).
-        if (isStaleLock(lockPath)) {
-            try {
-                unlinkSync(lockPath);
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // race: another process reaped it; loop and try to acquire.
-            }
-            continue;
+        // Wall-clock guard runs at the top of each iteration so a slow retry
+        // backoff (e.g. vitest on Windows) never lets us outlive the stale
+        // threshold and re-enter the reaper branch on a still-live lock.
+        if (Date.now() - startedAt > LOCK_STALE_MS) {
+            throw new LockTimeoutError(lockPath, attempts);
         }
         try {
             fd = openSync(lockPath, 'wx');

package/dist/{src/services → services}/ide/adapters/zcode-adapter.js

@@ -52,7 +52,7 @@ function readZcodeConfig(path) {
     try {
         return JSON.parse(readFileSync(path, 'utf8'));
     }
-    catch {
+    catch { // TODO(g2): fail-closed JSON parse — undefined is the documented contract for missing/corrupt config
         return undefined;
     }
 }

package/dist/{src/services → services}/ide/current-model-detector.js

@@ -50,7 +50,7 @@ export async function detectCurrentIdeModel() {
                 return modelId.trim();
             }
         }
-        catch {
+        catch { // TODO(g2): Per-SC §3.4 best-effort — a misconfigured adapter must not poison the chain
             // Per-SC §3.4: detection is best-effort. Swallow errors so a
             // misconfigured adapter cannot poison the chain; the next
             // adapter still gets a chance.

package/dist/services/memory/project-context-service.d.ts

@@ -0,0 +1,21 @@
+import { type BootstrapProjectScanEnvelope } from '../prd/project-scan-bootstrap-service.js';
+export type ProjectContextSection = {
+    heading: string;
+    body: string;
+};
+/**
+ * Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+ * generateProjectContext now also bootstraps the project-level
+ * `.peaks/project-scan/` artifact set. The envelope is returned
+ * alongside the context so `peaks project context` can surface
+ * `templatesBooted` / `templatesSkipped` / `durationMs` in its JSON.
+ */
+export type ProjectContextEnvelope = {
+    path: string;
+    content: string;
+    sessionCount: number;
+    projectScan: BootstrapProjectScanEnvelope;
+};
+export declare function generateProjectContext(projectRoot: string): Promise<ProjectContextEnvelope>;
+export declare function readProjectContext(projectRoot: string): string | null;
+export declare function getProjectContextPath(projectRoot: string): string;

package/dist/{src/services → services}/memory/project-context-service.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import { listSessionMetas } from '../session/session-manager.js';
 import { getSessionDir } from '../session/getSessionDir.js';
+import { bootstrapProjectScan } from '../prd/project-scan-bootstrap-service.js';
 const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
 const CONTEXT_HEADER = `# Peaks Project Context
 
@@ -98,7 +99,7 @@ function buildSessionHistory(projectRoot) {
     body += `\n${MANAGED_BLOCK_END}`;
     return body;
 }
-export function generateProjectContext(projectRoot) {
+export async function generateProjectContext(projectRoot) {
     const peaksDir = join(projectRoot, '.peaks');
     if (!existsSync(peaksDir)) {
         mkdirSync(peaksDir, { recursive: true });
@@ -130,7 +131,19 @@ export function generateProjectContext(projectRoot) {
         content = header + '\n' + sessionHistory + '\n';
     }
     writeFileSync(contextPath, content, 'utf8');
-    return { path: contextPath, content, sessionCount: listSessionMetas(projectRoot).length };
+    // Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+    // After writing PROJECT.md, also bootstrap `.peaks/project-scan/`
+    // (project-scan.md + 4 bundled audit/business templates). Idempotent
+    // — re-running this call does not overwrite existing files (unless
+    // the caller passes `force` / `forceTemplates`, which we do NOT do
+    // here; peaks workspace init owns the force variants).
+    const projectScan = await bootstrapProjectScan({ projectRoot });
+    return {
+        path: contextPath,
+        content,
+        sessionCount: listSessionMetas(projectRoot).length,
+        projectScan
+    };
 }
 export function readProjectContext(projectRoot) {
     const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);

package/dist/{src/services → services}/polyrepo/polyrepo-dispatcher.js

@@ -107,7 +107,7 @@ export function readManifest(root) {
         const raw = readFileSync(p, 'utf8');
         return JSON.parse(raw);
     }
-    catch {
+    catch { // TODO(g2): fail-closed JSON parse — null is the documented contract, caller checks via existsSync
         return null;
     }
 }

package/dist/services/prd/project-scan-bootstrap-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * project-scan bootstrap service — slice 2026-07-15-project-scan-bootstrap
+ * (PRD G1 + G2 + G4b / AC1-AC10 / R1-R4).
+ *
+ * Owns the "first time a project enters Peaks-Loop" bootstrap flow:
+ *   - 0-1 detection (no package.json OR no source files)
+ *   - writes `.peaks/project-scan/project-scan.md` with empty placeholders
+ *     for 0-1 projects, or with archetype + libraryVersions for existing
+ *     projects (calling `scanArchetype` + `scanLibraries` directly, not
+ *     forking a CLI process)
+ *   - boots the 4 audit/business templates (bundled in repo at
+ *     `src/services/workspace/templates/project-scan/`) into
+ *     `.peaks/project-scan/` (AC9)
+ *   - idempotent: skips re-writes when the existing file is at
+ *     schemaVersion:1 (AC3); --force / --force-templates override
+ *
+ * Called by:
+ *   - `peaks project context` (via `generateProjectContext`)
+ *   - `peaks workspace init` (main path)
+ *
+ * The "5 templates" count: 4 bundled audit/business files + the
+ * dynamically-generated `project-scan.md` produced by this service.
+ * `templatesBooted` reflects the count of files actually written;
+ * `templatesSkipped` reflects files already present (sediment-protected).
+ */
+export type BootstrapProjectScanOptions = {
+    readonly projectRoot: string;
+    /** Override the existing-file skip and rewrite project-scan.md. */
+    readonly force?: boolean;
+    /** Override the bundled-template skip and overwrite audit/business files. */
+    readonly forceTemplates?: boolean;
+};
+export type BootstrapProjectScanEnvelope = {
+    /** True iff project-scan.md was written by this call. */
+    readonly created: boolean;
+    /** True iff project-scan.md existed and was skipped (idempotent). */
+    readonly skipped: boolean;
+    /** Count of files written to .peaks/project-scan/ (1 project-scan.md + N templates). */
+    readonly templatesBooted: number;
+    /** Count of files already present and skipped (sediment-preserved). */
+    readonly templatesSkipped: number;
+    /** Absolute path to the project-scan.md file (whether written or pre-existing). */
+    readonly projectScanPath: string;
+    /** Resolved archetype (when existing-project path was taken). */
+    readonly archetype?: string;
+    /** Total wall-time of the bootstrap call. */
+    readonly durationMs: number;
+};
+/**
+ * Public entry point. See the file header for the full contract.
+ */
+export declare function bootstrapProjectScan(options: BootstrapProjectScanOptions): Promise<BootstrapProjectScanEnvelope>;