peaks-cli 1.3.1 → 1.3.3

package/dist/src/services/artifacts/request-artifact-service.js

@@ -3,8 +3,8 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDirectory, listDirectories } from '../../shared/fs.js';
 import { checkPrerequisites, DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES } from './artifact-prerequisites.js';
-import { ensureSession } from '../session/session-manager.js';
-import { getCurrentChangeId, getChangeArtifactRoot } from '../../shared/change-id.js';
+import { ensureSession, getSessionIdCanonical } from '../session/session-manager.js';
+import { getCurrentChangeId } from '../../shared/change-id.js';
 import { getNextNumber, buildNumberedFilename } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
@@ -313,25 +313,48 @@ export async function createRequestArtifact(options) {
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
     // Use provided session ID or get/create current session. The session
-    // id is kept as the in-memory binding (so the artifact body can record
-    // which session wrote it), but the artifact file is now written
-    // under the change-id dir, NOT the session dir.
+    // id is the binding for the artifact file's location.
     //
-    // The change-id is the file's durable scope. As of slice
-    // 2026-06-05-change-id-as-unit-of-work, the requestId IS the
-    // change-id (per the legacy `001-<change-id>.md` filename convention);
-    // a request that lives in a session dir under a different change-id
-    // is no longer the model. We honor a `current-change` binding if
-    // one is set, and otherwise fall back to the requestId itself.
+    // Slice 006 collapses the per-change-id top-level dirs. The artifact
+    // file is now written under the SESSION dir
+    // (`.peaks/_runtime/<sid>/<role>/requests/`) instead of the
+    // change-id dir. The 2-tier fallback (canonical session → legacy
+    // session) replaces the F3 3-tier fallback (per-change-id →
+    // canonical session → legacy session). The change-id is preserved
+    // in the artifact body's frontmatter (under `- change-id:`) for
+    // human navigation; it is no longer a filesystem path key.
     const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
     const boundChangeId = getCurrentChangeId(options.projectRoot);
-    // Resolution order for the change-id (file path key):
-    //   1. Explicit `options.changeId` (CLI `--session-id` pre-1.3.0 set this).
+    // Resolution order for the change-id (file body metadata):
+    //   1. Explicit `options.changeId` (CLI `--change-id`).
     //   2. `current-change` binding (live developer working context).
     //   3. The requestId itself (every request is its own scope by default).
     const changeId = options.changeId ?? boundChangeId ?? options.requestId;
-    // Build numbered path under the change-id dir
-    const requestsDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/' + options.role + '/requests';
+    // Slice 008 (F21 fix): fail fast when the resolved session id
+    // looks like a real session id (matches the date+session prefix)
+    // but does NOT correspond to an actual session dir under
+    // `.peaks/_runtime/`. Pre-F21 a sub-agent with a typo or stale
+    // binding (e.g. `2025-01-01-session-deadbe`) silently planned
+    // to write to a non-existent path. The check is intentionally
+    // scoped to "looks like a real session id" — a sid like
+    // `test-session` or `s` (no date prefix) is allowed through so
+    // the existing F3 / slice-007 back-compat flows (e.g. the
+    // `peaks request init --session-id <arbitrary-scope>` tests)
+    // can still create the dir on demand via the writer's
+    // `mkdir(..., { recursive: true })`.
+    const LOOKS_LIKE_SESSION_ID = /^\d{4}-\d{2}-\d{2}-session-/;
+    if (LOOKS_LIKE_SESSION_ID.test(sessionId)) {
+        const sessionDir = join(options.projectRoot, '.peaks', '_runtime', sessionId);
+        if (!(await isDirectory(sessionDir))) {
+            const canonicalSid = getSessionIdCanonical(options.projectRoot);
+            const hint = canonicalSid !== null
+                ? `Use --session-id ${canonicalSid} or run 'peaks workspace init' to create a new session.`
+                : `Run 'peaks workspace init' to create a new session.`;
+            throw new Error(`session id '${sessionId}' does not exist in _runtime/. Current canonical binding is '${canonicalSid ?? '<none>'}'. ${hint}`);
+        }
+    }
+    // Build numbered path under the session dir (canonical post-F3 home).
+    const requestsDir = join(options.projectRoot, '.peaks', '_runtime', sessionId, options.role, 'requests');
     // Check if a file with this requestId already exists (regardless of number prefix)
     if (await isDirectory(requestsDir)) {
         const existingFiles = await listMarkdownFiles(requestsDir);
@@ -356,11 +379,11 @@ export async function createRequestArtifact(options) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
     // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked.
-    // As of slice 2026-06-05-change-id-as-unit-of-work, the marker lives under
-    // the change-id dir (not the session dir), so the gate's prereq scan
-    // (which reads from `.peaks/<change-id>/<role>/...`) finds it.
+    // Slice 006: the marker lives under the SESSION dir (canonical post-F3
+    // home), not the change-id dir. The gate's prereq scan finds it at
+    // `.peaks/_runtime/<sid>/qa/.initiated`.
     if (options.role === 'qa') {
-        const qaDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/qa';
+        const qaDir = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa');
         const initiatedPath = join(qaDir, '.initiated');
         if (!existsSync(initiatedPath)) {
             await mkdir(qaDir, { recursive: true });
@@ -448,45 +471,45 @@ export async function listRequestArtifacts(options) {
     if (!(await isDirectory(peaksRoot))) {
         return [];
     }
-    // As of slice 2026-06-05-change-id-as-unit-of-work, artifact files live
-    // in `.peaks/<change-id>/<role>/requests/`. The top-level `.peaks/<dir>/`
-    // entries we scan here are change-id dirs (new layout) AND legacy
-    // session-id dirs (pre-1.3.0 layout). Both have the same
-    // `<role>/requests/<file>.md` shape, so we read them uniformly.
+    // Slice 006 collapsed the per-change-id top-level dirs. The 2-tier
+    // resolution model is:
+    //   1. `.peaks/_runtime/<sid>/<role>/requests/` (post-F3 canonical
+    //      session home; slice 006's primary home for request artifacts).
+    //   2. `.peaks/<sid>/<role>/requests/` (pre-F3 legacy home; back-compat
+    //      for users who have not yet migrated).
     //
-    // Additionally, shipped slices are archived under
-    // `.peaks/retrospective/<change-id>/<role>/requests/` and dogfood
-    // evidence lives under `.peaks/_dogfood/<change-id>/<role>/requests/`.
-    // When `sessionId` is NOT pinned, we scan ALL three umbrella dirs
-    // (`<top>`, `retrospective/`, `_dogfood/`) so a `peaks request show
-    // <rid>` resolves shipped slices too — which is what the slice check's
-    // gate-verify-pipeline stage needs to find evidence for the retrospective
-    // slice being verified.
-    //
-    // Skip well-known non-artifact dirs: `_runtime/` holds ephemeral state
-    // (no `requests/` subdirs anyway, but skip explicitly to avoid noise).
-    const allDirs = await listDirectories(peaksRoot);
-    const candidateDirs = allDirs.filter((dir) => dir !== '_runtime');
-    // Expand scopes to include the nested umbrellas that host change-id dirs
-    // (retrospective/, _dogfood/). For each, list its sub-dirs and treat
-    // them as additional scopes. This makes the lookup span the entire
-    // .peaks tree.
-    const expandedScopes = [];
+    // When `sessionId` is pinned, the function scans that one session's
+    // two tiers (canonical + legacy). When `sessionId` is NOT pinned,
+    // the function scans every session dir under `.peaks/_runtime/`
+    // (canonical) AND every legacy session dir under `.peaks/`
+    // (top-level). Per-change-id dirs (the old `.peaks/<changeId>/<role>/`
+    // layout) are NOT scanned — slice 008 will migrate the 5
+    // already-shipped slices' artifacts to the new layout; new request
+    // artifacts are written to the session dir directly.
+    const scopes = [];
     if (options.sessionId !== undefined) {
-        expandedScopes.push(options.sessionId);
+        scopes.push(join('_runtime', options.sessionId));
+        scopes.push(options.sessionId);
     }
     else {
-        for (const dir of candidateDirs) {
-            expandedScopes.push(dir);
-            if (dir === 'retrospective' || dir === '_dogfood') {
-                const nested = await listDirectories(join(peaksRoot, dir));
-                for (const n of nested) {
-                    expandedScopes.push(join(dir, n));
-                }
+        const runtimeRoot = join(peaksRoot, '_runtime');
+        if (await isDirectory(runtimeRoot)) {
+            for (const sid of await listDirectories(runtimeRoot)) {
+                scopes.push(join('_runtime', sid));
             }
         }
+        // Legacy top-level session dirs: scan every non-`._peaks` top-level
+        // dir as a potential legacy scope. Slice 006 dropped per-change-id
+        // dirs, so any top-level dir name under `.peaks/` that is NOT
+        // `_runtime` (and not a well-known umbrella like retrospective,
+        // _dogfood, memory, etc. — those have no `<role>/requests/` tree)
+        // is treated as a candidate legacy session dir.
+        for (const dir of await listDirectories(peaksRoot)) {
+            if (dir === '_runtime')
+                continue;
+            scopes.push(dir);
+        }
     }
-    const scopes = expandedScopes;
     const roles = options.role !== undefined ? [options.role] : Array.from(VALID_ROLES);
     const summaries = [];
     for (const scope of scopes) {
@@ -525,45 +548,56 @@ export async function showRequestArtifact(options) {
     // As of slice 2026-06-05-change-id-as-unit-of-work, the dir key is the
     // change-id (not the session-id). When the caller pins `sessionId` we
     // use it as the scope anyway (legacy callers, and tests that pass
-    // `STABLE_SESSION` as a stand-in). The directory layout is identical
-    // for both old session dirs and new change-id dirs, so a single
-    // read path works for both.
+    // `STABLE_SESSION` as a stand-in).
+    //
+    // As of slice 2026-06-06-session-layout-canonicalize (F3), the
+    // canonical home for session dirs is `.peaks/_runtime/<sid>/`.
+    // The pre-F3 layout `.peaks/<sid>/` is preserved as a one-minor
+    // back-compat fallback (the new path wins when both exist). We
+    // resolve the dir to use UP FRONT (not lazily after a miss) so the
+    // prerequisite gate's "request artifact present" check observes
+    // the same path the rest of the canonical layout uses.
     if (options.sessionId !== undefined) {
-        const dir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
+        const canonicalDir = join(options.projectRoot, '.peaks', '_runtime', options.sessionId, options.role, 'requests');
+        const legacyDir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
+        // Try the canonical (post-F3) path first; fall back to the legacy
+        // path only if the canonical path is absent. The legacy path is
+        // expected to be empty after a `peaks workspace migrate --to-runtime`
+        // run; this fallback exists for users who have not yet migrated.
+        const dir = (await isDirectory(canonicalDir)) ? canonicalDir : legacyDir;
+        const scope = dir === canonicalDir
+            ? join('_runtime', options.sessionId)
+            : options.sessionId;
         const found = await findFileInDir(dir);
         if (found === null) {
             return null;
         }
-        return await readRequestArtifact(options.projectRoot, options.sessionId, options.role, found);
+        return await readRequestArtifact(options.projectRoot, scope, options.role, found);
     }
     const peaksRoot = join(options.projectRoot, '.peaks');
     if (!(await isDirectory(peaksRoot))) {
         return null;
     }
-    // Scan all top-level dirs in `.peaks/` AND nested change-id dirs
-    // under `retrospective/` and `_dogfood/`. The expanded scope list
-    // lets us find request artifacts that live one or two levels deep
-    // (shipped slices, dogfood evidence). Without this expansion,
-    // verify-pipeline can't find the RD/QA request files for any
-    // retrospective slice.
-    const allDirs = await listDirectories(peaksRoot);
-    const scopes = [];
-    for (const dir of allDirs) {
-        if (dir === '_runtime')
-            continue;
-        scopes.push(dir);
-        if (dir === 'retrospective' || dir === '_dogfood') {
-            const nested = await listDirectories(join(peaksRoot, dir));
-            for (const n of nested) {
-                scopes.push(join(dir, n));
+    // Slice 006: scan only session-scoped dirs (canonical + legacy)
+    // for the artifact. The per-change-id top-level dirs are no longer
+    // scanned — they are frozen until slice 008 migrates them.
+    const runtimeRoot = join(peaksRoot, '_runtime');
+    if (await isDirectory(runtimeRoot)) {
+        for (const sid of await listDirectories(runtimeRoot)) {
+            const dir = join(runtimeRoot, sid, options.role, 'requests');
+            const found = await findFileInDir(dir);
+            if (found !== null) {
+                return await readRequestArtifact(options.projectRoot, join('_runtime', sid), options.role, found);
             }
         }
     }
-    for (const scope of scopes) {
-        const dir = join(peaksRoot, scope, options.role, 'requests');
-        const found = await findFileInDir(dir);
+    for (const dir of await listDirectories(peaksRoot)) {
+        if (dir === '_runtime')
+            continue;
+        const target = join(peaksRoot, dir, options.role, 'requests');
+        const found = await findFileInDir(target);
         if (found !== null) {
-            return await readRequestArtifact(options.projectRoot, scope, options.role, found);
+            return await readRequestArtifact(options.projectRoot, dir, options.role, found);
         }
     }
     return null;
@@ -719,6 +753,12 @@ export async function transitionRequestArtifact(options) {
     const prerequisiteResult = await checkPrerequisites({
         projectRoot: options.projectRoot,
         changeId: existing.changeId,
+        // F3 repair cycle 1: pass the session binding so the gate can fall
+        // back to `.peaks/_runtime/<sid>/<role>/` (and the legacy
+        // `.peaks/<sid>/<role>/`) for prerequisite artifacts that still
+        // live under the session dir rather than the change-id dir. This
+        // mirrors the F1/F2 back-compat pattern.
+        sessionId: existing.sessionId,
         role: options.role,
         newState: options.newState,
         requestId: options.requestId,

package/dist/src/services/config/config-types.d.ts

@@ -61,7 +61,7 @@ export type PeaksConfig = {
     /**
      * Sub-agent progress surfacing knobs. The `peaks progress watch`
      * CLI (intended to be run in a separate terminal tab while the
-     * LLM is working) reads `.peaks/<sid>/system/subagent-progress.json`
+     * LLM is working) reads `.peaks/_sub_agents/<sid>/subagent-progress.json`
      * and renders elapsed / spinner / sub-step in real time. The
      * `enabled` flag is a kill-switch for users who find the watch
      * distracting; the `heartbeatIntervalMs` lets power users tune

package/dist/src/services/context/artifact-meta.d.ts

@@ -0,0 +1,72 @@
+export type ArtifactStatus = 'created' | 'finalized' | 'partial' | 'failed';
+export interface ArtifactMeta {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly status: ArtifactStatus;
+    /** Mandatory literal `false`. The type system rejects `true`. */
+    readonly contentInlined: false;
+    /** 1-2 sentence description, ≤ 200 chars. Allowed in main context. */
+    readonly summary: string | null;
+    /** ISO8601. */
+    readonly writtenAt: string;
+    /** Request id this artifact belongs to. */
+    readonly rid: string;
+    /** Sub-agent role string. */
+    readonly role: string;
+    /** Sequence number when same role is dispatched multiple times. */
+    readonly idx: number;
+}
+export interface ContextImpact {
+    readonly promptSize: number;
+    readonly artifactSizes: readonly number[];
+    readonly batchTotalSize: number;
+    /** `high` if `batchTotalSize > 4MB` OR any `artifactSize > 1MB`. */
+    readonly contextWarning: 'normal' | 'high' | 'critical';
+}
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export declare function computeSha256(filePath: string): string;
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export declare function buildArtifactMeta(opts: {
+    path: string;
+    rid: string;
+    role: string;
+    idx: number;
+    summary: string | null;
+    status?: ArtifactStatus;
+    /** Override sha256 / size (e.g. when caller already computed them). */
+    precomputed?: {
+        size: number;
+        sha256: string;
+    };
+    /** Override the writtenAt timestamp. */
+    writtenAt?: string;
+}): ArtifactMeta;
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export declare function buildContextImpact(opts: {
+    promptSize: number;
+    artifactSizes: readonly number[];
+}): ContextImpact;
+export declare const ARTIFACT_LIMITS: {
+    readonly ARTIFACT_MAX_SIZE_BYTES: number;
+    readonly BATCH_TOTAL_HIGH_BYTES: number;
+    readonly ARTIFACT_SUMMARY_MAX_CHARS: 200;
+};

package/dist/src/services/context/artifact-meta.js

@@ -0,0 +1,105 @@
+/**
+ * G7 — sub-agent context minimal-occupation (RL-17..RL-22, AC-38..AC-43).
+ *
+ * `ArtifactMeta` is what the dispatch record stores per sub-agent artifact
+ * instead of the full content. The `contentInlined: false` literal is the
+ * API contract: the type system rejects `true`, so main LLM context can
+ * never accidentally be flooded with inlined artifact bodies.
+ *
+ * The artifact's content lives on disk at `path`; the meta is ~200 chars
+ * (path + size + sha256 + status + summary), so 3 sub-agents × ~200 chars
+ * = ~600 chars net context increase per batch instead of 3MB+.
+ *
+ * Path convention (G7.4.c):
+ *   `.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>`
+ *
+ * See: `.peaks/memory/sub-agent-context-minimal-occupation.md` for the
+ * full G7 rule.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+const ARTIFACT_MAX_SIZE_BYTES = 1024 * 1024; // 1MB
+const BATCH_TOTAL_HIGH_BYTES = 4 * 1024 * 1024; // 4MB
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export function computeSha256(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export function buildArtifactMeta(opts) {
+    let size;
+    let sha256;
+    let status = opts.status ?? 'created';
+    if (opts.precomputed) {
+        size = opts.precomputed.size;
+        sha256 = opts.precomputed.sha256;
+    }
+    else {
+        const stat = statSync(opts.path);
+        size = stat.size;
+        if (size === 0) {
+            // 0-byte artifact: cannot compute meaningful sha256; mark as failed.
+            sha256 = '0'.repeat(64);
+            status = 'failed';
+        }
+        else {
+            sha256 = computeSha256(opts.path);
+        }
+    }
+    const summary = opts.summary;
+    if (summary !== null && summary.length > 200) {
+        throw new Error(`ArtifactMeta summary must be ≤ 200 chars (got ${summary.length})`);
+    }
+    return {
+        path: opts.path,
+        size,
+        sha256,
+        status,
+        contentInlined: false,
+        summary,
+        writtenAt: opts.writtenAt ?? new Date().toISOString(),
+        rid: opts.rid,
+        role: opts.role,
+        idx: opts.idx
+    };
+}
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export function buildContextImpact(opts) {
+    const batchTotalSize = opts.promptSize + opts.artifactSizes.reduce((a, b) => a + b, 0);
+    let contextWarning = 'normal';
+    if (opts.artifactSizes.some((s) => s > ARTIFACT_MAX_SIZE_BYTES)) {
+        contextWarning = 'critical';
+    }
+    else if (batchTotalSize > BATCH_TOTAL_HIGH_BYTES) {
+        contextWarning = 'high';
+    }
+    return {
+        promptSize: opts.promptSize,
+        artifactSizes: opts.artifactSizes,
+        batchTotalSize,
+        contextWarning
+    };
+}
+export const ARTIFACT_LIMITS = {
+    ARTIFACT_MAX_SIZE_BYTES,
+    BATCH_TOTAL_HIGH_BYTES,
+    ARTIFACT_SUMMARY_MAX_CHARS: 200
+};

package/dist/src/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 };

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

@@ -0,0 +1,91 @@
+/**
+ * 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 { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
+const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
+const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
+const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
+/**
+ * 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 function evaluatePromptSize(promptSize, opts = {}) {
+    const capacity = opts.capacityBytes ?? CONTEXT_CAPACITY_DEFAULT_BYTES;
+    const evaluation = evaluateThresholdTier(promptSize, capacity);
+    const tier = evaluation.tier;
+    let allow;
+    let code;
+    let suggest;
+    let forcedAt = null;
+    switch (tier) {
+        case 'ok':
+            allow = true;
+            code = 'OK';
+            suggest = null;
+            break;
+        case 'soft-warn':
+            allow = true;
+            code = 'CONTEXT_SOFT_WARN';
+            suggest = SOFT_WARN_SUGGEST;
+            break;
+        case 'near-limit':
+            allow = true;
+            code = 'CONTEXT_NEAR_LIMIT';
+            suggest = NEAR_LIMIT_SUGGEST;
+            break;
+        case 'hard-reject':
+            allow = false;
+            code = 'PROMPT_TOO_LARGE';
+            suggest = HARD_REJECT_SUGGEST;
+            break;
+        case 'emergency':
+            allow = false;
+            code = 'PROMPT_EMERGENCY';
+            suggest = EMERGENCY_SUGGEST;
+            break;
+    }
+    // --force override (CLI only; hook layer never reaches this branch)
+    if (!allow && opts.force === true) {
+        allow = true;
+        code = 'FORCED_OVER_THRESHOLD';
+        suggest = 'Override applied at CLI. Hook layer will still reject.';
+        forcedAt = new Date().toISOString();
+    }
+    const warnings = [...evaluation.warnings];
+    if (forcedAt !== null && !warnings.includes('FORCED_OVER_THRESHOLD')) {
+        warnings.push('FORCED_OVER_THRESHOLD');
+    }
+    return {
+        allow,
+        code,
+        warnings,
+        suggest,
+        evaluation,
+        forcedAt
+    };
+}
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

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

@@ -0,0 +1,27 @@
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export declare function artifactPath(projectRoot: string, sid: string, rid: string, role: string, idx: number, ext?: string): string;
+/** Build the canonical shared channel path. */
+export declare function sharedChannelPath(projectRoot: string, sid: string, rid: string, batchId: string): string;
+/**
+ * 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 declare function assertSafeArtifactPath(artifactPathInput: string, projectRoot: string): string;
+/**
+ * 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 declare function assertSafeSharedChannelPath(channelPathInput: string, projectRoot: string): string;
+/**
+ * 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 declare function checkArtifactNameConvention(artifactPathInput: string): string | null;