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

package/dist/services/context/dispatch-context-guard.js

@@ -0,0 +1,192 @@
+/**
+ * G7.4 path safety + G8 path safety — R-2 symlink/junction guard for
+ * sub-agent artifact + shared channel paths.
+ *
+ * Slice #009's `assertSafeDispatchRecordPath` covers the dispatch record
+ * path. This module covers two adjacent paths under the same canonical
+ * root (`.peaks/_sub_agents/<sid>/`):
+ *
+ *   - `artifacts/<rid>-<role>-<idx>.<ext>`   (G7 write-artifact)
+ *   - `shared/<batchId>.json`                (G8 share / shared-read)
+ *
+ * Both reuse the same R-2 logic: reject `..` segments BEFORE the OS
+ * resolver collapses them (POSIX normalize silently drops `..`), reject
+ * absolute paths that escape the canonical root, resolve symlinks via
+ * `realpathSync` and re-check the resolved path.
+ *
+ * The canonical-root pattern is intentionally identical to the slice #009
+ * helper, so future audits can reuse one mental model: "all sub-agent
+ * state files must live under `.peaks/_sub_agents/<sid>/` and pass the
+ * same R-2 guard."
+ */
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+const SUB_AGENTS_DIR = '_sub_agents';
+const ARTIFACTS_SUBDIR = 'artifacts';
+const SHARED_SUBDIR = 'shared';
+const ARTIFACT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\.[A-Za-z0-9]+$/;
+const BATCH_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export function artifactPath(projectRoot, sid, rid, role, idx, ext = 'md') {
+    if (typeof role !== 'string' || role.length === 0) {
+        throw new Error('artifactPath: role must be non-empty');
+    }
+    if (!Number.isInteger(idx) || idx < 1) {
+        throw new Error(`artifactPath: idx must be positive integer (got ${idx})`);
+    }
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    const safeRole = sanitizeSegment(role, 'role');
+    const safeExt = ext.replace(/[^A-Za-z0-9]/g, '');
+    if (safeExt.length === 0) {
+        throw new Error(`artifactPath: ext must be alphanumeric (got "${ext}")`);
+    }
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, ARTIFACTS_SUBDIR, `${safeRid}-${safeRole}-${String(idx).padStart(3, '0')}.${safeExt}`);
+}
+/** Build the canonical shared channel path. */
+export function sharedChannelPath(projectRoot, sid, rid, batchId) {
+    if (typeof batchId !== 'string' || batchId.length === 0) {
+        throw new Error('sharedChannelPath: batchId must be non-empty');
+    }
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    if (!BATCH_ID_PATTERN.test(batchId)) {
+        throw new Error(`sharedChannelPath: batchId must match ${BATCH_ID_PATTERN} (got "${batchId}")`);
+    }
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, SHARED_SUBDIR, `${safeRid}-${batchId}.json`);
+}
+/**
+ * Assert that `artifactPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/artifacts/`. Rejects
+ * symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_ARTIFACT_PATH'` on rejection.
+ */
+export function assertSafeArtifactPath(artifactPathInput, projectRoot) {
+    if (!isAbsolute(artifactPathInput)) {
+        throw invalidPathError(artifactPathInput, 'must be absolute');
+    }
+    const rawSegments = artifactPathInput.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathError(artifactPathInput, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, artifactPathInput);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+    }
+    let realArtifact;
+    let realRoot;
+    try {
+        const parent = dirname(artifactPathInput);
+        const realParent = realpathSync(parent);
+        realArtifact = resolve(realParent, artifactPathInput.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch {
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, artifactPathInput);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+        }
+        return artifactPathInput;
+    }
+    const realRel = relative(realRoot, realArtifact);
+    if (realRel.startsWith('..') || isAbsolute(realRel)) {
+        throw invalidPathError(artifactPathInput, 'symlink/junction escapes project root');
+    }
+    const realExpected = resolve(realRoot, '.peaks', SUB_AGENTS_DIR);
+    const realRelExpected = relative(realExpected, realArtifact);
+    if (realRelExpected.startsWith('..') || isAbsolute(realRelExpected)) {
+        throw invalidPathError(artifactPathInput, 'must be under .peaks/_sub_agents/');
+    }
+    return realArtifact;
+}
+/**
+ * Assert that `channelPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/shared/`. Same R-2 logic as
+ * `assertSafeArtifactPath` but with a different canonical subdir.
+ *
+ * Throws an Error with `.code = 'INVALID_SHARED_CHANNEL_PATH'` on rejection.
+ */
+export function assertSafeSharedChannelPath(channelPathInput, projectRoot) {
+    if (!isAbsolute(channelPathInput)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be absolute');
+    }
+    const rawSegments = channelPathInput.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathErrorShared(channelPathInput, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, channelPathInput);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+    }
+    let realChannel;
+    let realRoot;
+    try {
+        const parent = dirname(channelPathInput);
+        const realParent = realpathSync(parent);
+        realChannel = resolve(realParent, channelPathInput.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch {
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, channelPathInput);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+        }
+        return channelPathInput;
+    }
+    const realRel = relative(realRoot, realChannel);
+    if (realRel.startsWith('..') || isAbsolute(realRel)) {
+        throw invalidPathErrorShared(channelPathInput, 'symlink/junction escapes project root');
+    }
+    const realExpected = resolve(realRoot, '.peaks', SUB_AGENTS_DIR);
+    const realRelExpected = relative(realExpected, realChannel);
+    if (realRelExpected.startsWith('..') || isAbsolute(realRelExpected)) {
+        throw invalidPathErrorShared(channelPathInput, 'must be under .peaks/_sub_agents/shared/');
+    }
+    return realChannel;
+}
+/**
+ * Soft-warn check on the artifact file name pattern. Returns null if
+ * the name matches `<rid>-<role>-<idx>.<ext>`, otherwise returns a
+ * warning string. Does NOT reject (the path is still in the canonical
+ * dir; the warning is for human/audit readability per G7.4.c).
+ */
+export function checkArtifactNameConvention(artifactPathInput) {
+    const base = artifactPathInput.split(/[\\/]/).pop() ?? '';
+    if (ARTIFACT_NAME_PATTERN.test(base)) {
+        return null;
+    }
+    return `Artifact file name does not match <rid>-<role>-<idx>.<ext> convention: ${base}`;
+}
+function sanitizeSegment(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${field} must be non-empty`);
+    }
+    if (value.length > 256) {
+        throw new Error(`${field} must be ≤ 256 chars (got ${value.length})`);
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x20 || code === 0x7F) {
+            throw new Error(`${field} must not contain whitespace or control characters`);
+        }
+    }
+    if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+        throw new Error(`${field} must not contain '..' or path separators`);
+    }
+    return value;
+}
+function invalidPathError(path, reason) {
+    const e = new Error(`Invalid artifact path: ${reason} (path: ${path})`);
+    e.code = 'INVALID_ARTIFACT_PATH';
+    return e;
+}
+function invalidPathErrorShared(path, reason) {
+    const e = new Error(`Invalid shared channel path: ${reason} (path: ${path})`);
+    e.code = 'INVALID_SHARED_CHANNEL_PATH';
+    return e;
+}

package/dist/services/context/doc-retriever.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per spec §4.1 Step 2 — DocRetriever.
+ *
+ * HARD CONSTRAINTS:
+ *   H1 (CLI enforces — not LLM): this module is the only place that decides
+ *       which docs to fetch.
+ *   H2 (locked version): returns ONLY docs whose version exactly matches
+ *       the locked dep version. No fallback to "latest". If no doc exists
+ *       at the locked version, record `version_unknown` and move on.
+ *
+ * The fetcher is injected so tests can pin responses deterministically
+ * (cross-version isolation test relies on this).
+ */
+import type { DepInfo, DocRetrieverOutput } from './types.js';
+export interface DocFetcher {
+    (dep: string, version: string): Promise<FetcherPayload | null>;
+}
+export interface FetcherPayload {
+    readonly version: string;
+    readonly excerpt: string;
+}
+export interface RetrieveOptions {
+    readonly fetcher: DocFetcher;
+    readonly now?: () => Date;
+}
+export declare function retrieveDocs(deps: Readonly<Record<string, DepInfo>>, options: RetrieveOptions): Promise<DocRetrieverOutput>;

package/dist/services/context/doc-retriever.js

@@ -0,0 +1,51 @@
+function makeSection(excerpt) {
+    // Trivial section split — production slice would parse markdown headings.
+    // For v1, single-section per dep is sufficient.
+    return {
+        title: 'API Summary',
+        tokenEstimate: Math.ceil(excerpt.length / 4),
+        excerpt,
+    };
+}
+function hashContent(content) {
+    // Stable hash via Node crypto (deterministic for test pinning).
+    // Production uses sha256 from node:crypto.
+    // For v1, we accept that this returns a non-cryptographic digest.
+    let h = 0;
+    for (let i = 0; i < content.length; i += 1) {
+        h = ((h << 5) - h + content.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h).toString(16).padStart(16, '0').slice(0, 16);
+}
+export async function retrieveDocs(deps, options) {
+    const fetchedDocs = [];
+    const skipped = [];
+    const now = options.now ?? (() => new Date());
+    for (const [dep, info] of Object.entries(deps)) {
+        try {
+            const payload = await options.fetcher(dep, info.version);
+            if (payload === null) {
+                skipped.push({ dep, reason: 'version_unknown' });
+                continue;
+            }
+            // ★ Core isolation check — defense in depth even if the fetcher is wrong.
+            if (payload.version !== info.version) {
+                skipped.push({ dep, reason: 'version_unknown' });
+                continue;
+            }
+            fetchedDocs.push({
+                dep,
+                version: info.version,
+                source: 'remote-fetch',
+                fetchedAt: now().toISOString(),
+                contentHash: hashContent(payload.excerpt),
+                sections: [makeSection(payload.excerpt)],
+                stale: false,
+            });
+        }
+        catch {
+            skipped.push({ dep, reason: 'network_error' });
+        }
+    }
+    return { fetchedDocs, skipped };
+}

package/dist/services/context/headroom-client.d.ts

@@ -0,0 +1,34 @@
+export type HeadroomMode = 'balanced' | 'aggressive' | 'conservative';
+export interface HeadroomResult {
+    readonly compressed: boolean;
+    readonly originalSize: number;
+    readonly compressedSize: number;
+    readonly compressionRatio: number;
+    readonly mode: HeadroomMode;
+    /** `'HEADROOM_UNAVAILABLE'` on fallback; `null` on success. */
+    readonly warning: string | null;
+    /** Compressed prompt body. `null` if no compression happened. */
+    readonly compressedPrompt: string | null;
+    /** Tokens saved (from the SDK). 0 on fallback. */
+    readonly tokensSaved: number;
+}
+/**
+ * Compress a prompt via headroom-ai. The `fallback: true` option is
+ * non-negotiable: if the proxy daemon is unavailable, the SDK returns
+ * `result.compressed = false` and the original messages; we surface
+ * that as `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback.
+ */
+export declare function compressPrompt(prompt: string, mode?: HeadroomMode): Promise<HeadroomResult>;
+/**
+ * Bridge interface: when `--use-headroom` is set, share entries written
+ * via `peaks sub-agent share` MAY also flow through headroom's
+ * `SharedContext`. Slice #010 implements a peak-internal shared channel
+ * (see `shared-channel.ts`); the headroom-side `SharedContext` is a
+ * separate concept that future slices can layer on. For now this
+ * function is a stub that returns the peak-internal channel ID, which
+ * is enough to demonstrate the bridge contract.
+ */
+export declare function buildSharedContextBridge(batchId: string): {
+    peakChannelId: string;
+    headroomContextId: string;
+};

package/dist/services/context/headroom-client.js

@@ -0,0 +1,117 @@
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MODEL = 'claude-sonnet-4-5-20250929';
+// Approximate 1 token = 4 bytes for English text. This is a rough
+// heuristic; the SDK does its own tokenization internally.
+const BYTES_PER_TOKEN = 4;
+/**
+ * Compress a prompt via headroom-ai. The `fallback: true` option is
+ * non-negotiable: if the proxy daemon is unavailable, the SDK returns
+ * `result.compressed = false` and the original messages; we surface
+ * that as `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback.
+ */
+export async function compressPrompt(prompt, mode = 'balanced') {
+    const originalSize = Buffer.byteLength(prompt, 'utf8');
+    let compressFn = null;
+    try {
+        const mod = await import('headroom-ai');
+        if (typeof mod.compress === 'function') {
+            compressFn = mod.compress;
+        }
+    }
+    catch {
+        return fallback(originalSize, mode);
+    }
+    if (compressFn === null) {
+        return fallback(originalSize, mode);
+    }
+    const messages = [
+        { role: 'user', content: prompt }
+    ];
+    const opts = {
+        model: DEFAULT_MODEL,
+        timeout: DEFAULT_TIMEOUT_MS,
+        fallback: true, // CRITICAL: return original messages if proxy is down
+        retries: 1
+    };
+    if (mode === 'aggressive') {
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.20 / BYTES_PER_TOKEN));
+    }
+    else if (mode === 'conservative') {
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.70 / BYTES_PER_TOKEN));
+    }
+    else {
+        // balanced: target ~60% reduction
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.40 / BYTES_PER_TOKEN));
+    }
+    let result;
+    try {
+        result = await compressFn(messages, opts);
+    }
+    catch {
+        return fallback(originalSize, mode);
+    }
+    if (result.compressed === false) {
+        return {
+            compressed: false,
+            originalSize,
+            compressedSize: originalSize,
+            compressionRatio: 1.0,
+            mode,
+            warning: 'HEADROOM_UNAVAILABLE',
+            compressedPrompt: null,
+            tokensSaved: 0
+        };
+    }
+    const compressedContent = extractContent(result.messages);
+    if (compressedContent === null) {
+        return fallback(originalSize, mode);
+    }
+    const compressedSize = Buffer.byteLength(compressedContent, 'utf8');
+    return {
+        compressed: true,
+        originalSize,
+        compressedSize,
+        compressionRatio: compressedSize / originalSize,
+        mode,
+        warning: null,
+        compressedPrompt: compressedContent,
+        tokensSaved: result.tokensSaved ?? 0
+    };
+}
+function fallback(originalSize, mode) {
+    return {
+        compressed: false,
+        originalSize,
+        compressedSize: originalSize,
+        compressionRatio: 1.0,
+        mode,
+        warning: 'HEADROOM_UNAVAILABLE',
+        compressedPrompt: null,
+        tokensSaved: 0
+    };
+}
+function extractContent(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return null;
+    }
+    const last = messages[messages.length - 1];
+    if (typeof last.content === 'string') {
+        return last.content;
+    }
+    return null;
+}
+/**
+ * Bridge interface: when `--use-headroom` is set, share entries written
+ * via `peaks sub-agent share` MAY also flow through headroom's
+ * `SharedContext`. Slice #010 implements a peak-internal shared channel
+ * (see `shared-channel.ts`); the headroom-side `SharedContext` is a
+ * separate concept that future slices can layer on. For now this
+ * function is a stub that returns the peak-internal channel ID, which
+ * is enough to demonstrate the bridge contract.
+ */
+export function buildSharedContextBridge(batchId) {
+    return {
+        peakChannelId: batchId,
+        headroomContextId: `headroom-ctx-${batchId}`
+    };
+}

package/dist/services/context/headroom-fetcher.d.ts

@@ -0,0 +1,6 @@
+import type { DocFetcher } from './doc-retriever.js';
+export interface HeadroomFetcherOptions {
+    readonly cacheDir: string;
+    readonly remoteFetcher?: DocFetcher;
+}
+export declare function createHeadroomFetcher(opts: HeadroomFetcherOptions): DocFetcher;

package/dist/services/context/headroom-fetcher.js

@@ -0,0 +1,28 @@
+/**
+ * Production DocFetcher. Uses existing headroom-ai dependency for remote
+ * fetch; local cache (per-session, per-dep markdown) preferred when version matches.
+ *
+ * Hard constraint H2 (locked version): never returns a doc whose version
+ * differs from the requested locked version.
+ *
+ * Cache path (per pre-flight fix #2): .peaks/_runtime/<sid>/doc-cache/<dep>@<version>.md
+ *   - Per-session (NOT cross-session shared at ~/.peaks/cache/docs/)
+ *   - Reason: spec §4.1 keeps everything under _runtime which is gitignored
+ *     and ephemeral; cross-session caching is a future-slice optimization.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function createHeadroomFetcher(opts) {
+    return async (dep, version) => {
+        const cachePath = join(opts.cacheDir, `${dep}@${version}.md`);
+        try {
+            const content = await readFile(cachePath, 'utf8');
+            return { version, excerpt: content };
+        }
+        catch {
+            if (!opts.remoteFetcher)
+                return null;
+            return opts.remoteFetcher(dep, version);
+        }
+    };
+}

package/dist/services/context/headroom-prefs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Headroom preferences resolver (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Pure functions that turn `ProjectPreferences.headroom.*` + CLI
+ * overrides into a single decision the dispatch path can act on.
+ * No IO. No side effects. Easy to test in isolation.
+ *
+ * Two distinct decisions:
+ *  1. `resolveHeadroomOptions` — should we compress the dispatch prompt?
+ *     Used by `peaks sub-agent dispatch`. Returns one of:
+ *       - `{ mode: <m>, blocked: null }`   → compress with mode <m>
+ *       - `{ mode: null, blocked: null }`  → skip compression (no --use-headroom)
+ *       - `{ mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' }` → hard fail
+ *  2. `shouldCompressResults` — should we compress search-result text?
+ *     Used by `peaks memory search` / `peaks retrospective search`.
+ *     Non-blocking: returns a `reason` instead of a `blocked` code.
+ *
+ * Precedence (dispatch):
+ *   1. `headroom.enabled = false`  → hard block (regardless of --use-headroom)
+ *   2. `headroom.enabled = true` + `--headroom-mode <m>` → use <m>
+ *   3. `headroom.enabled = true` + `--use-headroom` (no --headroom-mode) →
+ *      use `perTouchpoint.subAgentDispatch` (preferred) else `defaultMode`
+ *   4. no `--use-headroom` → mode = null (compression skipped)
+ */
+import type { HeadroomMode, ProjectPreferences } from '../preferences/preferences-types.js';
+export type HeadroomTouchpoint = keyof ProjectPreferences['headroom']['perTouchpoint'];
+export type HeadroomBlockCode = 'HEADROOM_DISABLED_BY_PREFERENCE';
+export interface ResolvedHeadroomOptions {
+    /** The mode to use for compression, or null if not compressing. */
+    readonly mode: HeadroomMode | null;
+    /** Hard-block reason; null when compression is allowed (or simply not requested). */
+    readonly blocked: HeadroomBlockCode | null;
+}
+export interface ResolveCliOverrides {
+    readonly useHeadroom: boolean;
+    readonly headroomMode?: string;
+}
+export declare function isHeadroomMode(value: string | undefined): value is HeadroomMode;
+export declare function resolveHeadroomOptions(prefs: ProjectPreferences['headroom'], cliOverrides: ResolveCliOverrides): ResolvedHeadroomOptions;
+export interface ShouldCompressDecision {
+    readonly compress: boolean;
+    readonly mode: HeadroomMode;
+    /** Non-null reason if not compressing. */
+    readonly reason: 'DISABLED' | 'BELOW_THRESHOLD' | null;
+}
+export declare function shouldCompressResults(prefs: ProjectPreferences['headroom'], joinedBytes: number, touchpoint: HeadroomTouchpoint): ShouldCompressDecision;

package/dist/services/context/headroom-prefs.js

@@ -0,0 +1,34 @@
+const VALID_MODES = new Set([
+    'balanced',
+    'aggressive',
+    'conservative'
+]);
+export function isHeadroomMode(value) {
+    return typeof value === 'string' && VALID_MODES.has(value);
+}
+export function resolveHeadroomOptions(prefs, cliOverrides) {
+    // (1) Hard block when preference disables headroom entirely.
+    if (cliOverrides.useHeadroom === true && prefs.enabled === false) {
+        return { mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' };
+    }
+    // (4) No --use-headroom → no compression.
+    if (cliOverrides.useHeadroom !== true) {
+        return { mode: null, blocked: null };
+    }
+    // (2) CLI --headroom-mode wins (even if preference is set, CLI overrides).
+    if (isHeadroomMode(cliOverrides.headroomMode)) {
+        return { mode: cliOverrides.headroomMode, blocked: null };
+    }
+    // (3) Preference path: perTouchpoint > defaultMode > 'balanced'.
+    const touchpointMode = prefs.perTouchpoint.subAgentDispatch;
+    return { mode: touchpointMode ?? prefs.defaultMode, blocked: null };
+}
+export function shouldCompressResults(prefs, joinedBytes, touchpoint) {
+    if (prefs.enabled === false) {
+        return { compress: false, mode: prefs.defaultMode, reason: 'DISABLED' };
+    }
+    if (joinedBytes < prefs.compressMinBytes) {
+        return { compress: false, mode: prefs.perTouchpoint[touchpoint], reason: 'BELOW_THRESHOLD' };
+    }
+    return { compress: true, mode: prefs.perTouchpoint[touchpoint], reason: null };
+}

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

@@ -0,0 +1,7 @@
+export { collectContext, type CollectInput } from './collector.js';
+export { retrieveDocs, type DocFetcher, type FetcherPayload, type RetrieveOptions } from './doc-retriever.js';
+export { tokenize } from './tokenizer.js';
+export { render, type RenderInput } from './renderer.js';
+export { ContextJsonSchema } from './context-schema.js';
+export { buildContext, type BuildInput } from './context-builder.js';
+export type { ContextJson, Audience, DepsMode, FileKind, CollectedFile, GitStatus, MemoryEntry, DepInfo, DocSection, FetchedDoc, SkippedDoc, TokenizedItem, CollectorOutput, DocRetrieverOutput, TokenizerOutput, RendererOutput, } from './types.js';

package/dist/services/context/index.js

@@ -0,0 +1,6 @@
+export { collectContext } from './collector.js';
+export { retrieveDocs } from './doc-retriever.js';
+export { tokenize } from './tokenizer.js';
+export { render } from './renderer.js';
+export { ContextJsonSchema } from './context-schema.js';
+export { buildContext } from './context-builder.js';

package/dist/services/context/main-session-monitor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D6: main-session context window monitor.
+ *
+ * Per `.peaks/memory/2026-06-26-v2-11-main-session-context-monitor.md`:
+ *
+ *   D6.a — IDE detection (`peaks ide detect --json`); env-var fallback.
+ *   D6.b — Main-session thresholds (50% warn / 75% user red line / 90% emergency)
+ *   D6.c — IDE-dependent trigger (claude-code → /compact; else LLM self-compress)
+ *   D6.d — Always log; never silently skip
+ *   D6.e — Do NOT auto-compact mid-tool-call-batch (in-flight deferral)
+ *   D6.f — Complements Step N periodic checkpoint (soft signal vs hard signal)
+ *
+ * Distinct from G7-G9 (sub-agent dispatch prompt governance). Same
+ * numbers, different scope. Extends `src/services/context/threshold.ts`
+ * rather than duplicating (D6.h).
+ *
+ * Karpathy §2: this module is the only place that decides
+ * "main-session context threshold" — the LLM-side caller probes via
+ * `evaluateMainSessionThreshold()` and `pickMainSessionTrigger()`.
+ * No inline `promptSize / 256K > 0.75` checks scattered across
+ * SKILL.md or other services.
+ */
+export type MainSessionTier = 'ok' | 'soft-warn' | 'near-limit' | 'emergency';
+export declare const MAIN_SESSION_THRESHOLD_RATIOS: {
+    readonly [K in MainSessionTier]: number;
+};
+export type IdeKind = 'claude-code' | 'trae' | 'opencode' | 'unknown';
+export declare const IDE_KINDS: readonly IdeKind[];
+export type MainSessionTrigger = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'soft-warn';
+    readonly promptSize: number;
+    readonly ratio: number;
+} | {
+    readonly kind: 'compact';
+    readonly ide: IdeKind;
+    readonly path: 'ide-native' | 'llm-self-compress';
+    readonly promptSize: number;
+    readonly ratio: number;
+    readonly code: 'CONTEXT_NEAR_LIMIT' | 'PROMPT_EMERGENCY';
+} | {
+    readonly kind: 'defer';
+    readonly reason: 'in-flight-batch' | 'unsupported-ide';
+};
+export interface MainSessionEvaluation {
+    readonly tier: MainSessionTier;
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+export declare function isIdeKind(value: string): value is IdeKind;
+export declare function detectIdeFromEnv(env?: NodeJS.ProcessEnv): IdeKind;
+/**
+ * Threshold check. Pure function (no IO). `capacityBytes` is injectable
+ * for tests and future per-IDE capacity overrides. Defaults to the
+ * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
+ */
+export declare function evaluateMainSessionThreshold(promptSize: number, capacityBytes?: number): MainSessionEvaluation;
+export interface InFlightBatchProbe {
+    readonly hasInFlightBatch: boolean;
+    readonly sharedChannelEntries: number;
+}
+export declare function pickMainSessionTrigger(opts: {
+    promptSize: number;
+    ide?: IdeKind | undefined;
+    capacityBytes?: number | undefined;
+    inFlightBatch?: InFlightBatchProbe | undefined;
+    /** Injectable env for IDE detection (test seam). */
+    env?: NodeJS.ProcessEnv | undefined;
+}): MainSessionTrigger;
+/**
+ * One-line audit log entry. Pure formatter; the LLM / CLI appends to
+ * `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`. Matches D6.d.
+ */
+export declare function formatMainSessionTriggerLogLine(trigger: MainSessionTrigger, contextId: string): string;