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

package/dist/services/context/auto-compact-reader.js

@@ -0,0 +1,164 @@
+/**
+ * AC-1 — auto context-percent probe.
+ *
+ * Reads the current AI CLI context-fill ratio without requiring the
+ * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
+ * registered `IdeAdapter.compact` profile which env-var to read;
+ * no hard-coded IDE names. Per-adapter:
+ *
+ *   - claude-code: `CLAUDE_CONTEXT_USAGE_PERCENT` (MVP)
+ *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
+ *     openclaw: each adapter fills its own env-var; until L2-dogfood
+ *     verifies each surface, adapters may omit `compact` and the
+ *     probe returns `source: 'conservative-fallback'`.
+ *
+ * Fallback chain (when adapter.compact is undefined OR the env-var
+ * is missing):
+ *   1. statusline poll (`~/.claude/statusline-state.json` for
+ *      Claude Code MVP; other IDEs register their own poll path
+ *      by exposing `compact.postCompactDetectCommand`).
+ *   2. Conservative transcript-size estimate
+ *      (`~/.claude/projects/<hash>/<sid>.jsonl` for Claude Code).
+ *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
+ *      orchestrator MUST NOT auto-fire compact on this signal.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { detectIdeFromEnv } from './main-session-monitor.js';
+import { getAdapter } from '../ide/ide-registry.js';
+/**
+ * Read env-var-based context percentage. Returns `null` when the env
+ * is absent or unparseable. Adapter-driven: the caller passes the
+ * env-var name from `IdeAdapter.compact.envVarForContextPercent`,
+ * so the function itself has no hard-coded IDE names.
+ */
+function readEnvPercent(env, varName) {
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    if (parsed < 0 || parsed > 1.5)
+        return null;
+    return Math.max(0, Math.min(1, parsed));
+}
+/**
+ * Read the IDE-specific statusline state. MVP path is Claude Code's
+ * `~/.claude/statusline-state.json`; other IDEs are intentionally
+ * left for future slices (each IDE will expose its own
+ * `compact.postCompactDetectCommand` to drive this).
+ */
+function readClaudeStatuslinePercent() {
+    const path = join(homedir(), '.claude', 'statusline-state.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const json = JSON.parse(readFileSync(path, 'utf8'));
+        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
+        for (const key of candidates) {
+            const raw = json[key];
+            if (typeof raw === 'number' && Number.isFinite(raw)) {
+                return raw > 1.5 ? raw / 100 : Math.max(0, Math.min(1, raw));
+            }
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * Conservative transcript-size fallback. Walks
+ * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
+ * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
+ * orchestrator can show "estimated from 124KB of 256KB transcript"
+ * in the envelope. Tagged `'conservative-fallback'` so callers
+ * know NOT to treat this as a hard gate.
+ */
+function readClaudeTranscriptFallback(sessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    if (!existsSync(projectsDir))
+        return null;
+    try {
+        const { readdirSync } = require('node:fs');
+        for (const hashDir of readdirSync(projectsDir)) {
+            const candidate = join(projectsDir, hashDir, `${sessionId}.jsonl`);
+            if (existsSync(candidate)) {
+                const bytes = statSync(candidate).size;
+                const ratio = Math.min(1, bytes / (256 * 1024));
+                return { ratio, bytes };
+            }
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * Probe the current AI CLI's context-fill ratio. Adapter-driven:
+ * looks up the registered `IdeAdapter.compact` profile via
+ * `getIdeAdapter(detectIdeFromEnv(env))` and reads the
+ * adapter-declared env-var. Falls back to statusline poll +
+ * transcript estimate ONLY for adapters that opt in
+ * (`adapter.id === 'claude-code'` for the MVP); other adapters
+ * without an env-var hit return `source: 'conservative-fallback'`
+ * with `ratio: 0` so the orchestrator never auto-fires on a
+ * missing signal.
+ */
+export function readContextPercent(input) {
+    const env = input.env ?? process.env;
+    const capturedAt = new Date().toISOString();
+    const capacityBytes = 256 * 1024;
+    const detected = detectIdeFromEnv(env);
+    // `detectIdeFromEnv` may return `'unknown'` when no IDE-specific
+    // marker is on PATH; narrow to a registered adapter id so the
+    // typed `getAdapter` call accepts it. `'unknown'` falls through to
+    // the conservative-zero probe (no compact dispatch). IdeKind is a
+    // narrow 3-element union (claude-code / trae / opencode); cast
+    // through `unknown` to IdeId's wider 8-element set.
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    // Primary: read the adapter-declared env-var (no hard-coded IDE names).
+    if (adapter.compact) {
+        const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
+        if (primary !== null) {
+            return {
+                ratio: primary,
+                source: `${ideId}-env`,
+                capacityBytes,
+                ide: ideId,
+                capturedAt
+            };
+        }
+    }
+    // MVP-only fallback chain: statusline poll + transcript estimate.
+    // Non-MVP adapters that don't fill `compact` skip this and return
+    // a conservative-zero probe (the orchestrator will stay in
+    // 'none' / 'soft-warn' zone and never auto-fire compact).
+    if (ideId === 'claude-code') {
+        const statusline = readClaudeStatuslinePercent();
+        if (statusline !== null) {
+            return { ratio: statusline, source: 'statusline-poll', capacityBytes, ide: ideId, capturedAt };
+        }
+        const fallback = readClaudeTranscriptFallback(input.sessionId);
+        if (fallback !== null) {
+            return {
+                ratio: fallback.ratio,
+                source: 'conservative-fallback',
+                rawBytes: fallback.bytes,
+                capacityBytes,
+                ide: ideId,
+                capturedAt
+            };
+        }
+    }
+    // No signal available — return `ratio: 0` so the orchestrator
+    // stays in `none` zone and the LLM can still pass `--prompt-size`
+    // explicitly via `peaks context check`.
+    return { ratio: 0, source: 'conservative-fallback', capacityBytes, ide: ideId, capturedAt };
+}
+/** Re-export the env-var probe for unit tests. */
+export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback };

package/dist/services/context/auto-compact-types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Auto-compact shared types (v2.13.0 AC-1..AC-4).
+ *
+ * Two-tier threshold model — peaks-loop is project-aware and the LLM
+ * is the decision-maker:
+ *
+ *   - 50%  soft warn          — log a one-line info row; continue.
+ *   - 85%  pre-compact zone   — peaks-loop prepares the convergence
+ *                                toolkit (checkpoint + convergence
+ *                                plan + auto-decisions log +
+ *                                IDE-compact dispatcher). The LLM
+ *                                DECIDES when (or whether) to fire
+ *                                compact during this zone. The
+ *                                toolkit is "ready to use" so the
+ *                                LLM doesn't lose context to a
+ *                                last-second `/compact` panic.
+ *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
+ *                                further sub-agent and synchronously
+ *                                triggers IDE-side compact. At 95%+
+ *                                the context window is too tight to
+ *                                continue safely; the LLM cannot
+ *                                opt out. This is the compact red
+ *                                line that guarantees the LLM-runner
+ *                                keeps working with context < 95%.
+ *
+ * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
+ * intelligent convergence — wait for in-flight sub-agents, finish
+ * the current todo row, persist a checkpoint, then compact. peaks-loop
+ * provides the toolkit; the LLM picks the moment. At 0.95 the window
+ * is gone and peaks-loop takes over synchronously to keep the runner
+ * alive.
+ */
+export declare const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
+export declare const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
+export declare const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
+export declare const AUTO_COMPACT_THRESHOLD_RATIO = 0.85;
+/** Single source of truth for "what should we do at ratio X?" */
+export type CompactTrigger = {
+    kind: 'none';
+} | {
+    kind: 'soft-warn';
+    ratio: number;
+    message: string;
+}
+/** Pre-compact zone (0.85 ≤ ratio < 0.95): toolkit ready; LLM picks the moment. */
+ | {
+    kind: 'pre-compact';
+    ratio: number;
+    message: string;
+    toolkitReady: true;
+}
+/** Red line (ratio ≥ 0.95): peaks-loop forces synchronous compact; LLM cannot opt out. */
+ | {
+    kind: 'red-line';
+    ratio: number;
+    message: string;
+};
+/** Caller-side info about sub-agent batches in flight (D6.e). */
+export interface InFlightBatchProbe {
+    readonly hasInFlightBatch: boolean;
+    readonly sharedChannelEntries?: number;
+    readonly batchId?: string;
+}
+/** What the post-compact LLM reads to resume exactly where it stopped. */
+export interface ConvergencePlan {
+    readonly schemaVersion: 1;
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly createdAt: string;
+    readonly ratio: number;
+    readonly checkpointPath: string;
+    readonly nextActions: readonly string[];
+    readonly resumeHint: string;
+}
+/** Per-IDE compact pathway chosen by AC-3. */
+export interface CompactDispatchResult {
+    readonly ok: boolean;
+    readonly ide: string;
+    readonly pathway: 'ide-native' | 'llm-self-compress' | 'shell-exec' | 'noop';
+    readonly message: string;
+}
+/** Final envelope returned by `runAutoCompact`. */
+export type AutoCompactResult = {
+    readonly ok: false;
+    readonly code: 'AUTO_COMPACT_NO_SESSION';
+    readonly message: string;
+    readonly nextActions: readonly string[];
+} | {
+    readonly ok: true;
+    readonly code: 'AUTO_COMPACT_SKIP' | 'AUTO_COMPACT_WAIT';
+    readonly message: string;
+    readonly data: {
+        readonly sessionId: string;
+        readonly ratio: number;
+        readonly source: string;
+        readonly decision: 'below-threshold' | 'in-flight-batch';
+    };
+} | {
+    readonly ok: boolean;
+    readonly code: 'AUTO_COMPACT_DISPATCHED' | 'AUTO_COMPACT_DISPATCH_FAILED' | 'AUTO_COMPACT_RED_LINE';
+    readonly message: string;
+    readonly data: {
+        readonly sessionId: string;
+        readonly ratio: number;
+        readonly source: string;
+        readonly checkpointPath?: string;
+        readonly convergencePlan?: ConvergencePlan;
+        readonly dispatch?: CompactDispatchResult;
+        /**
+         * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which
+         * session the compact targeted. `'main'` (default) means the
+         * main-session Claude Code window will fire `/compact` on its
+         * next turn; `'sub-agent'` means the dispatcher shell-spawned
+         * `/compact` in a child process (legacy behaviour).
+         */
+        readonly target?: 'main' | 'sub-agent';
+        readonly redLineGated?: boolean;
+    };
+};
+/**
+ * Probe shape returned by AC-1 (`readContextPercent`). The source
+ * field tells callers how the ratio was obtained (env-var, statusline
+ * poller, IDE hook, conservative fallback) so the CLI can show
+ * "context % (source: statusline-poll)" and the LLM can trust it.
+ */
+export interface ContextPercentProbe {
+    readonly ratio: number;
+    /**
+     * Adapter-driven source tag. Fixed values:
+     *   - `${ideId}-env`            (e.g. `claude-code-env`)
+     *   - `statusline-poll`         (Claude Code MVP fallback)
+     *   - `conservative-fallback`   (transcript size estimate OR
+     *                                no signal available — caller
+     *                                MUST NOT treat as hard gate)
+     * Future IDEs may add per-ide sources; the type accepts any
+     * string to keep the schema forward-compatible.
+     */
+    readonly source: string;
+    readonly rawBytes?: number;
+    readonly capacityBytes?: number;
+    readonly ide: string;
+    readonly capturedAt: string;
+}

package/dist/services/context/auto-compact-types.js

@@ -0,0 +1,36 @@
+/**
+ * Auto-compact shared types (v2.13.0 AC-1..AC-4).
+ *
+ * Two-tier threshold model — peaks-loop is project-aware and the LLM
+ * is the decision-maker:
+ *
+ *   - 50%  soft warn          — log a one-line info row; continue.
+ *   - 85%  pre-compact zone   — peaks-loop prepares the convergence
+ *                                toolkit (checkpoint + convergence
+ *                                plan + auto-decisions log +
+ *                                IDE-compact dispatcher). The LLM
+ *                                DECIDES when (or whether) to fire
+ *                                compact during this zone. The
+ *                                toolkit is "ready to use" so the
+ *                                LLM doesn't lose context to a
+ *                                last-second `/compact` panic.
+ *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
+ *                                further sub-agent and synchronously
+ *                                triggers IDE-side compact. At 95%+
+ *                                the context window is too tight to
+ *                                continue safely; the LLM cannot
+ *                                opt out. This is the compact red
+ *                                line that guarantees the LLM-runner
+ *                                keeps working with context < 95%.
+ *
+ * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
+ * intelligent convergence — wait for in-flight sub-agents, finish
+ * the current todo row, persist a checkpoint, then compact. peaks-loop
+ * provides the toolkit; the LLM picks the moment. At 0.95 the window
+ * is gone and peaks-loop takes over synchronously to keep the runner
+ * alive.
+ */
+export const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
+export const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
+export const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
+export const AUTO_COMPACT_THRESHOLD_RATIO = AUTO_COMPACT_PRE_COMPACT_RATIO;

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

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { CollectorOutput } from './types.js';
+declare const CollectInputSchema: z.ZodObject<{
+    goal: z.ZodString;
+    project: z.ZodString;
+    depsMode: z.ZodEnum<["locked", "latest"]>;
+    out: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    goal: string;
+    depsMode: "locked" | "latest";
+    out?: string | undefined;
+}, {
+    project: string;
+    goal: string;
+    depsMode: "locked" | "latest";
+    out?: string | undefined;
+}>;
+export type CollectInput = z.infer<typeof CollectInputSchema>;
+export declare function collectContext(rawInput: unknown): Promise<{
+    readonly goal: string;
+    readonly collector: CollectorOutput;
+}>;
+export {};

package/dist/services/context/collector.js

@@ -0,0 +1,133 @@
+/**
+ * Per spec §4.1 Step 1 — Collector.
+ *
+ * Hard constraints H1 (CLI enforces reads, not LLM), H2 (locked version).
+ * All inputs validated via Zod; all reads via Node fs (no shell-out).
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { z } from 'zod';
+const CollectInputSchema = z.object({
+    goal: z.string().min(1),
+    project: z.string().min(1),
+    depsMode: z.enum(['locked', 'latest']),
+    out: z.string().optional(),
+});
+function classifyKind(path) {
+    if (path.includes('/__tests__/') || path.endsWith('.test.ts') || path.endsWith('.test.tsx')) {
+        return 'test';
+    }
+    if (path.startsWith('config') || path.endsWith('.config.ts') || path.endsWith('.config.js')) {
+        return 'config';
+    }
+    if (path.endsWith('.md') || path.endsWith('.mdx')) {
+        return 'doc';
+    }
+    return 'source';
+}
+async function scanFiles(root, exclude) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist') {
+                continue;
+            }
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            const rel = relative(root, full).replaceAll('\\', '/');
+            if (exclude !== undefined && rel === exclude) {
+                continue;
+            }
+            const s = await stat(full);
+            out.push({
+                path: rel,
+                kind: classifyKind(relative(root, full)),
+                lines: 0, // computed lazily; full line count is expensive
+                hash: '', // computed lazily via content-hash-cache-pattern
+            });
+        }
+    }
+    await walk(root);
+    return out;
+}
+async function readGitStatus(project) {
+    // Minimal git info via Node — for now delegate to `git` CLI in a future slice.
+    // Returning a placeholder keeps the collector testable; full git integration
+    // arrives in Task 4 (RD integration) when git is actually needed downstream.
+    return {
+        branch: 'main',
+        lastCommit: 'unknown',
+        dirty: false,
+    };
+}
+async function readMemoryEntries(project) {
+    // Read .peaks/memory/*.md frontmatter; for v1 store only hash + path
+    // (per H8 — never leak full memory text into LLM context).
+    const memDir = join(project, '.peaks', 'memory');
+    try {
+        const entries = await readdir(memDir);
+        return entries
+            .filter((n) => n.endsWith('.md'))
+            .map((n) => ({
+            path: join('.peaks/memory', n),
+            title: n,
+            relevanceScore: 0,
+            excerptHash: '',
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readDeps(project, depsMode) {
+    if (depsMode === 'latest') {
+        throw new Error('BLOCKED: --deps-mode latest is forbidden by spec §4.1 (H2: locked only). ' +
+            'Configure the project lockfile to enable locked mode.');
+    }
+    const pkgPath = join(project, 'package.json');
+    let raw;
+    try {
+        raw = await readFile(pkgPath, 'utf8');
+    }
+    catch {
+        throw new Error(`BLOCKED: no package.json at ${project}`);
+    }
+    const pkg = JSON.parse(raw);
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (Object.keys(deps).length === 0) {
+        throw new Error(`BLOCKED: no locked version found in ${pkgPath}. ` +
+            'spec §4.1 forbids running with empty dependencies (H2).');
+    }
+    const result = {};
+    for (const [name, version] of Object.entries(deps)) {
+        if (typeof version !== 'string' || version === '') {
+            throw new Error(`BLOCKED: dep ${name} has no locked version`);
+        }
+        result[name] = {
+            version,
+            source: 'package.json',
+            resolved: '', // filled by lockfile parser in a later slice
+        };
+    }
+    return result;
+}
+export async function collectContext(rawInput) {
+    const input = CollectInputSchema.parse(rawInput);
+    const exclude = input.out !== undefined
+        ? relative(input.project, input.out).replaceAll('\\', '/')
+        : undefined;
+    const [files, gitStatus, memoryEntries, deps] = await Promise.all([
+        scanFiles(input.project, exclude),
+        readGitStatus(input.project),
+        readMemoryEntries(input.project),
+        readDeps(input.project, input.depsMode),
+    ]);
+    return {
+        goal: input.goal,
+        collector: { files, gitStatus, memoryEntries, deps },
+    };
+}

package/dist/services/context/context-builder.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ContextJson } from './types.js';
+declare const BuildInputSchema: z.ZodObject<{
+    goal: z.ZodString;
+    project: z.ZodString;
+    audience: z.ZodEnum<["peaks-rd", "peaks-qa", "peaks-mut", "all"]>;
+    depsMode: z.ZodEnum<["locked", "latest"]>;
+    docBudgetTokens: z.ZodDefault<z.ZodNumber>;
+    out: z.ZodString;
+    fetcher: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    goal: string;
+    depsMode: "locked" | "latest";
+    out: string;
+    audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+    docBudgetTokens: number;
+    fetcher: (...args: unknown[]) => unknown;
+}, {
+    project: string;
+    goal: string;
+    depsMode: "locked" | "latest";
+    out: string;
+    audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+    fetcher: (...args: unknown[]) => unknown;
+    docBudgetTokens?: number | undefined;
+}>;
+export type BuildInput = z.infer<typeof BuildInputSchema>;
+export declare function buildContext(rawInput: unknown): Promise<ContextJson>;
+export {};

package/dist/services/context/context-builder.js

@@ -0,0 +1,78 @@
+/**
+ * Per spec §4.1 — ContextBuilder.
+ *
+ * Orchestrates Collector → DocRetriever → Tokenizer → Renderer.
+ * Computes sha256 over the content (excluding the sha256 field itself —
+ * H8 audit-trail integrity). Atomic write: tmp file + rename, so a crash
+ * mid-write leaves no partial context.json on disk.
+ */
+import { createHash } from 'node:crypto';
+import { writeFile, rename, unlink } from 'node:fs/promises';
+import { z } from 'zod';
+import { collectContext } from './collector.js';
+import { retrieveDocs } from './doc-retriever.js';
+import { tokenize } from './tokenizer.js';
+import { render } from './renderer.js';
+import { ContextJsonSchema } from './context-schema.js';
+const BuildInputSchema = z.object({
+    goal: z.string().min(1),
+    project: z.string().min(1),
+    audience: z.enum(['peaks-rd', 'peaks-qa', 'peaks-mut', 'all']),
+    depsMode: z.enum(['locked', 'latest']),
+    docBudgetTokens: z.number().int().positive().default(8000),
+    out: z.string().min(1),
+    fetcher: z.function(),
+});
+function sha256OfContent(content) {
+    // Exclude `sha256` field from the hash (else chicken-and-egg).
+    const { sha256: _omit, ...rest } = content;
+    void _omit;
+    const canonical = JSON.stringify(rest, Object.keys(rest).sort());
+    return createHash('sha256').update(canonical).digest('hex');
+}
+export async function buildContext(rawInput) {
+    const input = BuildInputSchema.parse(rawInput);
+    const collected = await collectContext({
+        goal: input.goal,
+        project: input.project,
+        depsMode: input.depsMode,
+        out: input.out,
+    });
+    const docs = await retrieveDocs(collected.collector.deps, { fetcher: input.fetcher });
+    const tok = tokenize(collected.collector, docs);
+    const renderInput = {
+        goal: input.goal,
+        audience: input.audience,
+        docBudgetTokens: input.docBudgetTokens,
+        collector: collected.collector,
+        docRetriever: docs,
+        tokenizer: tok,
+    };
+    const renderer = render(renderInput);
+    // First pass: placeholder sha256 so we can hash the rest.
+    const partial = {
+        version: '1.0',
+        goal: input.goal,
+        generatedAt: new Date().toISOString(),
+        sha256: '',
+        collector: collected.collector,
+        docRetriever: docs,
+        tokenizer: tok,
+        renderer,
+    };
+    const sha256 = sha256OfContent(partial);
+    const finalCtx = { ...partial, sha256 };
+    // Validate before write (H8: garbage context.json must never land).
+    ContextJsonSchema.parse(finalCtx);
+    // Atomic write: tmp + rename.
+    const tmp = `${input.out}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(finalCtx, null, 2), 'utf8');
+        await rename(tmp, input.out);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+    return finalCtx;
+}

package/dist/services/context/context-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { tierToCode, type ThresholdEvaluation } from './threshold.js';
+export type ContextGuardCode = 'OK' | 'CONTEXT_SOFT_WARN' | 'CONTEXT_NEAR_LIMIT' | 'PROMPT_TOO_LARGE' | 'PROMPT_EMERGENCY' | 'FORCED_OVER_THRESHOLD';
+export interface ContextGuardDecision {
+    readonly allow: boolean;
+    readonly code: ContextGuardCode;
+    readonly warnings: readonly string[];
+    readonly suggest: string | null;
+    readonly evaluation: ThresholdEvaluation;
+    /** ISO8601 timestamp when --force override was applied. null otherwise. */
+    readonly forcedAt: string | null;
+}
+export interface ContextGuardOptions {
+    /** Pass `true` to allow override at the ≥ 80% tier. CLI-only; hook layer MUST NOT set this. */
+    readonly force?: boolean;
+    /** Override the default 256K context capacity (e.g. for tests). */
+    readonly capacityBytes?: number;
+}
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export declare function evaluatePromptSize(promptSize: number, opts?: ContextGuardOptions): ContextGuardDecision;
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };