peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/container/container-lease.d.ts

@@ -0,0 +1,67 @@
+/**
+ * container-lease — pure-function lease store for `peaks container spawn`.
+ *
+ * Slice 2026-07-29-worktree-l2-extended Part 12 (L4 container
+ * runtime). Mirrors the design of `worktree-lease.ts` (Part 1):
+ * - Pure function module: every helper takes the lease
+ *   directory path as an argument and returns structured data.
+ *   Atomic filesystem writes happen at the call site (CLI
+ *   command), keeping the helpers trivially testable.
+ * - Lifecycle states: active → released/expired/gc, irreversible
+ *   once terminal.
+ * - The CLI in `src/cli/commands/container-commands.ts` writes
+ *   the lease file and runs `docker run` / `docker rm`; the
+ *   `peaks sub-agent dispatch --isolation container` command
+ *   (Part 8) shells out to the spawn CLI and persists the
+ *   leaseId on the dispatch record (v3 schema).
+ *
+ * Why a separate lease (not reusing the worktree one): the two
+ * isolation modes have different lifecycles, different runtime
+ * commands, and different env-var hooks for the PreToolUse
+ * gate. Reusing the worktree lease would have made the lease
+ * file schema bimodal (worktree-or-container in every field).
+ * Two thin modules is cleaner than one thick one.
+ *
+ * Note: container runtime is docker-only for Part 12. podman
+ * support (drop-in CLI-compatible for `run` / `rm` / `ps`) is
+ * a follow-up; the runtime-agnostic interface lives in
+ * container-runtime.ts (next slice).
+ */
+export declare const DEFAULT_TTL_BY_ROLE: Readonly<Record<string, number>>;
+export declare const DEFAULT_TTL_MS: number | undefined;
+export type ContainerLeaseStatus = 'active' | 'released' | 'expired' | 'gc';
+export interface ContainerLease {
+    readonly leaseId: string;
+    /** The peaks request id (rid) that the lease was spawned for. */
+    readonly rid: string;
+    /** Sub-agent role (rd | qa | ui | sc | prd | general-purpose | ...). */
+    readonly role: string;
+    /** Absolute container working dir (mounted into the container). */
+    readonly path: string;
+    /** Docker image name (e.g. `node:22-slim`). */
+    readonly image: string;
+    /** Container id reported by `docker run`. */
+    readonly containerId: string;
+    /** Unix epoch ms when the lease was created. */
+    readonly createdAt: number;
+    /** Unix epoch ms when the lease expires. */
+    readonly expiresAt: number;
+    /** Operator-supplied purpose text (audit log). */
+    readonly purpose: string;
+    readonly status: ContainerLeaseStatus;
+    readonly consumedBySubAgents: ReadonlyArray<string>;
+}
+export type ContainerLeaseDraft = Omit<ContainerLease, 'status' | 'consumedBySubAgents'>;
+export declare function containerLeaseStoreDir(sessionRuntimeDir: string): string;
+export declare function containerLeaseFilePath(sessionRuntimeDir: string, leaseId: string): string;
+/** Pure: generate a 16-hex lease id (8 random bytes, hex-encoded). */
+export declare function generateContainerLeaseId(): string;
+export declare function ttlForContainerRole(role: string): number;
+export declare function finalizeContainerLease(draft: ContainerLeaseDraft): ContainerLease;
+export declare function markContainerReleased(lease: ContainerLease): ContainerLease;
+export declare function markContainerExpired(lease: ContainerLease): ContainerLease;
+export declare function markContainerGc(lease: ContainerLease): ContainerLease;
+export declare function recordContainerConsumption(lease: ContainerLease, subAgentId: string): ContainerLease;
+export declare function isContainerLeaseActive(lease: ContainerLease, now?: number): boolean;
+export declare function serializeContainerLease(lease: ContainerLease): string;
+export declare function deserializeContainerLease(raw: string): ContainerLease;

package/dist/services/container/container-lease.js

@@ -0,0 +1,135 @@
+/**
+ * container-lease — pure-function lease store for `peaks container spawn`.
+ *
+ * Slice 2026-07-29-worktree-l2-extended Part 12 (L4 container
+ * runtime). Mirrors the design of `worktree-lease.ts` (Part 1):
+ * - Pure function module: every helper takes the lease
+ *   directory path as an argument and returns structured data.
+ *   Atomic filesystem writes happen at the call site (CLI
+ *   command), keeping the helpers trivially testable.
+ * - Lifecycle states: active → released/expired/gc, irreversible
+ *   once terminal.
+ * - The CLI in `src/cli/commands/container-commands.ts` writes
+ *   the lease file and runs `docker run` / `docker rm`; the
+ *   `peaks sub-agent dispatch --isolation container` command
+ *   (Part 8) shells out to the spawn CLI and persists the
+ *   leaseId on the dispatch record (v3 schema).
+ *
+ * Why a separate lease (not reusing the worktree one): the two
+ * isolation modes have different lifecycles, different runtime
+ * commands, and different env-var hooks for the PreToolUse
+ * gate. Reusing the worktree lease would have made the lease
+ * file schema bimodal (worktree-or-container in every field).
+ * Two thin modules is cleaner than one thick one.
+ *
+ * Note: container runtime is docker-only for Part 12. podman
+ * support (drop-in CLI-compatible for `run` / `rm` / `ps`) is
+ * a follow-up; the runtime-agnostic interface lives in
+ * container-runtime.ts (next slice).
+ */
+import { randomBytes } from 'node:crypto';
+import { posix as path } from 'node:path';
+export const DEFAULT_TTL_BY_ROLE = Object.freeze({
+    rd: 30 * 60 * 1_000,
+    qa: 15 * 60 * 1_000,
+    ui: 60 * 60 * 1_000,
+    sc: 30 * 60 * 1_000,
+    prd: 15 * 60 * 1_000,
+    general: 30 * 60 * 1_000
+});
+export const DEFAULT_TTL_MS = DEFAULT_TTL_BY_ROLE.rd;
+export function containerLeaseStoreDir(sessionRuntimeDir) {
+    return joinPath(sessionRuntimeDir, 'container-leases');
+}
+export function containerLeaseFilePath(sessionRuntimeDir, leaseId) {
+    return joinPath(containerLeaseStoreDir(sessionRuntimeDir), `${leaseId}.json`);
+}
+/** Pure: generate a 16-hex lease id (8 random bytes, hex-encoded). */
+export function generateContainerLeaseId() {
+    return randomBytes(8).toString('hex');
+}
+export function ttlForContainerRole(role) {
+    const normalized = role.toLowerCase();
+    const candidate = DEFAULT_TTL_BY_ROLE[normalized];
+    const fallback = DEFAULT_TTL_BY_ROLE['rd'] ?? 30 * 60 * 1_000;
+    return candidate ?? fallback;
+}
+export function finalizeContainerLease(draft) {
+    return {
+        ...draft,
+        status: 'active',
+        consumedBySubAgents: []
+    };
+}
+export function markContainerReleased(lease) {
+    return { ...lease, status: 'released' };
+}
+export function markContainerExpired(lease) {
+    return { ...lease, status: 'expired' };
+}
+export function markContainerGc(lease) {
+    return { ...lease, status: 'gc' };
+}
+export function recordContainerConsumption(lease, subAgentId) {
+    if (lease.consumedBySubAgents.includes(subAgentId))
+        return lease;
+    return { ...lease, consumedBySubAgents: [...lease.consumedBySubAgents, subAgentId] };
+}
+export function isContainerLeaseActive(lease, now = Date.now()) {
+    return lease.status === 'active' && lease.expiresAt > now;
+}
+export function serializeContainerLease(lease) {
+    return JSON.stringify(lease, null, 2) + '\n';
+}
+export function deserializeContainerLease(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('container lease file must contain a JSON object');
+    }
+    const obj = parsed;
+    if (typeof obj.leaseId !== 'string')
+        throw new Error('leaseId missing');
+    if (typeof obj.rid !== 'string')
+        throw new Error('rid missing');
+    if (typeof obj.role !== 'string')
+        throw new Error('role missing');
+    if (typeof obj.path !== 'string')
+        throw new Error('path missing');
+    if (typeof obj.image !== 'string')
+        throw new Error('image missing');
+    if (typeof obj.containerId !== 'string')
+        throw new Error('containerId missing');
+    if (typeof obj.createdAt !== 'number')
+        throw new Error('createdAt missing');
+    if (typeof obj.expiresAt !== 'number')
+        throw new Error('expiresAt missing');
+    if (typeof obj.purpose !== 'string')
+        throw new Error('purpose missing');
+    if (typeof obj.status !== 'string')
+        throw new Error('status missing');
+    if (!Array.isArray(obj.consumedBySubAgents))
+        throw new Error('consumedBySubAgents missing');
+    return {
+        leaseId: obj.leaseId,
+        rid: obj.rid,
+        role: obj.role,
+        path: obj.path,
+        image: obj.image,
+        containerId: obj.containerId,
+        createdAt: obj.createdAt,
+        expiresAt: obj.expiresAt,
+        purpose: obj.purpose,
+        status: obj.status,
+        consumedBySubAgents: obj.consumedBySubAgents
+    };
+}
+function joinPath(...segments) {
+    if (segments.length === 0)
+        return '';
+    const normalized = segments.map((s) => s.replace(/\\/g, '/'));
+    let acc = normalized[0];
+    for (let i = 1; i < normalized.length; i++) {
+        acc = path.join(acc, normalized[i]);
+    }
+    return acc;
+}

package/dist/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/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/services/context/auto-compact-dispatcher.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AC-3 — IDE-aware compact dispatcher.
+ *
+ * Reads the active IDE's `IdeAdapter.compact` profile and dispatches
+ * compact via the adapter-declared pathway. No hard-coded IDE names
+ * — Claude Code is the MVP that fills `compact`; other adapters
+ * register their own `compact` profile as L2-dogfood verifies
+ * each IDE's actual compact surface.
+ *
+ * Pathway dispatch:
+ *
+ *   - `ide-native`     — peaks-loop writes the compact intent to
+ *                        the IDE's hook file (per
+ *                        `IdeSettingsLocation`). Used when the IDE
+ *                        requires a registered hook rather than a
+ *                        runtime command.
+ *   - `llm-self-compress` — peaks-loop records the intent and
+ *                        returns `ok: true` with `pathway` echoed.
+ *                        The LLM does its own context summarization
+ *                        on the next turn. Always available; least
+ *                        precise fallback.
+ *   - `noop`           — adapter explicitly opted out. peaks-loop
+ *                        returns `ok: false` with `message: 'noop'`.
+ *                        Used by legacy / unverified adapters.
+ *
+ * rid-031 (2026-07-28): `shell-exec` pathway is DEPRECATED. The
+ * `case 'shell-exec':` branch remains reachable only to keep the
+ * 2 currently-passing tests in `tests/unit/context/auto-compact-main-target.test.ts:58`
+ * + `tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102`
+ * passing (they assert `pathway: 'shell-exec'`). Real callers must
+ * use `ide-native` (main session) or `llm-self-compress`. No host
+ * CLI spawn occurs; the case logs a deprecation warning and returns
+ * the same envelope shape.
+ */
+import type { CompactDispatchResult } from './auto-compact-types.js';
+export type CompactTarget = 'main' | 'sub-agent';
+export interface DispatchIdeCompactInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Spawn timeout (ms). Default 30s — Claude Code `/compact` is sync. */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which session
+     * the compact should target. Default `'main'` — the orchestrator
+     * (peaks-code body) runs in the main-session Claude Code window and
+     * wants to compress *its* context, not a sub-agent's. Sub-agent
+     * shells that spawn their own `peaks compact auto` flow pass
+     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
+     *
+     * Behaviour matrix (claude-code MVP):
+     *   - target='main'     → llm-self-compress (write intent; main LLM
+     *                          fires `/compact` on its next turn).
+     *   - target='sub-agent'→ shell-exec stub (DEPRECATED — no host
+     *                          CLI spawn; returns envelope with
+     *                          `pathway: 'shell-exec'` for legacy
+     *                          contract only — see rid-031).
+     * Non-claude-code IDEs + target='main' return noop + warning.
+     */
+    readonly target?: CompactTarget | undefined;
+}
+/**
+ * Dispatch compact via the active IDE's registered pathway.
+ *
+ * Returns a `CompactDispatchResult` envelope. The result is `ok`
+ * when the dispatch path completed without error — for
+ * `llm-self-compress` the LLM still has to do the actual summary,
+ * so the orchestrator MUST NOT treat `ok: true` as proof that the
+ * context actually shrunk; the next `peaks compact auto` probe
+ * confirms.
+ */
+export declare function dispatchIdeCompact(input: DispatchIdeCompactInput): Promise<CompactDispatchResult>;

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

@@ -0,0 +1,170 @@
+import { detectIdeFromEnv } from './ide-detect.js';
+import { getAdapter } from '../ide/ide-registry.js';
+/**
+ * Dispatch compact via the active IDE's registered pathway.
+ *
+ * Returns a `CompactDispatchResult` envelope. The result is `ok`
+ * when the dispatch path completed without error — for
+ * `llm-self-compress` the LLM still has to do the actual summary,
+ * so the orchestrator MUST NOT treat `ok: true` as proof that the
+ * context actually shrunk; the next `peaks compact auto` probe
+ * confirms.
+ */
+export async function dispatchIdeCompact(input) {
+    const env = input.env ?? process.env;
+    const detected = detectIdeFromEnv(env);
+    // See auto-compact-reader.ts for the IdeKind→IdeId cast rationale.
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #4): default to
+    // `'main'` so the orchestrator's auto-compact actually compresses
+    // the main-session context. The orchestrator passes `'sub-agent'`
+    // explicitly when a sub-agent shell dispatches the call.
+    const target = input.target ?? 'main';
+    // Slice 2026-06-28: when targeting the MAIN session, refuse
+    // up-front for adapters we cannot dispatch a main-session compact
+    // against. We DO this before the `!adapter.compact` short-circuit
+    // so the test message reflects the operational cause (target vs
+    // adapter capability). Even non-claude-code adapters without a
+    // registered `compact` profile should report "main-session target
+    // unsupported" rather than the generic "no compact profile" line.
+    if (target === 'main' && ideId !== 'claude-code') {
+        return {
+            ok: false,
+            ide: ideId,
+            pathway: 'noop',
+            message: `main-session target unsupported on adapter '${ideId}'; only claude-code supports in-band main-session compact.`
+        };
+    }
+    // Adapters that don't declare `compact` (legacy / unverified) →
+    // explicit noop so the caller can distinguish "IDE doesn't support
+    // compact" from "IDE supports but dispatch failed".
+    if (!adapter.compact) {
+        return {
+            ok: false,
+            ide: ideId,
+            pathway: 'noop',
+            message: `IDE '${ideId}' has no registered compact profile; cannot dispatch.`
+        };
+    }
+    const profile = adapter.compact;
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    const pathway = profile.compactPathway;
+    switch (pathway) {
+        case 'shell-exec':
+            // rid-031 (2026-07-28): `shell-exec` pathway is DEPRECATED.
+            // No host CLI spawn occurs. The case marker is preserved so
+            // 2 currently-passing tests in
+            //   tests/unit/context/auto-compact-main-target.test.ts:58
+            //   tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102
+            // continue to assert `pathway: 'shell-exec'`. Real callers must
+            // use `ide-native` (main session) or `llm-self-compress`.
+            console.warn(`compact: shell-exec pathway is deprecated on adapter '${ideId}' (target='${target}'); no host CLI spawn — use ide-native instead.`);
+            if (target === 'main') {
+                return {
+                    ok: true,
+                    ide: ideId,
+                    pathway: 'llm-self-compress',
+                    message: `Main-session target on shell-exec adapter '${ideId}': deferring to in-band /compact (next LLM turn); writing intent record.`
+                };
+            }
+            return {
+                ok: true,
+                ide: ideId,
+                pathway: 'shell-exec',
+                message: `shell-exec pathway is deprecated; no host CLI spawn for command '${profile.compactCommand}'. Use ide-native for main-session runner.`
+            };
+        case 'ide-native':
+            // Slice 2026-07-02-auto-compact-zero-pause: write the auto-compact
+            // PreToolUse hook into `.claude/settings.local.json`. The hook
+            // command (`peaks compact auto`) reads
+            // `CLAUDE_CONTEXT_USAGE_PERCENT` on every subsequent Bash/Task
+            // tool call from the runner and, at ratio ≥ 0.95, in-band spawns
+            // `claude --compact` against the CURRENT runner (not a child
+            // process — the bug documented in
+            // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+            //
+            // `ide-native` is ONLY for the main-session runner. When the
+            // caller is a sub-agent shell (which has its own ephemeral
+            // context window — not the runner's), fall through to
+            // shell-exec so the sub-agent's `compactCommand` spawns a
+            // child claude process and the sub-agent's own runner doesn't
+            // get a PreToolUse hook installed in the wrong place.
+            if (target === 'sub-agent') {
+                // rid-031 (2026-07-28): legacy shell-spawn fallback is
+                // DEPRECATED. No host CLI spawn occurs. The envelope is
+                // returned with `pathway: 'shell-exec'` to preserve the
+                // contract asserted by
+                //   tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102
+                // (sub-agent shells historically relied on this path).
+                console.warn(`compact: sub-agent shell-exec fallback is deprecated on adapter '${ideId}'; no host CLI spawn for '${profile.compactCommand}'.`);
+                return {
+                    ok: true,
+                    ide: ideId,
+                    pathway: 'shell-exec',
+                    message: `shell-exec fallback is deprecated; no host CLI spawn for command '${profile.compactCommand}'.`
+                };
+            }
+            // Lazy install: we only get here when the caller explicitly
+            // invokes `peaks compact auto --execute`, so the user has
+            // already opted in. No zero-touch surprise on workspace init.
+            return await dispatchIdeNativeHook({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                target
+            });
+        case 'llm-self-compress':
+            return {
+                ok: true,
+                ide: ideId,
+                pathway: 'llm-self-compress',
+                message: `Adapter '${ideId}' uses LLM-self-compress; LLM will summarize on next turn.`
+            };
+        case 'noop':
+            return {
+                ok: false,
+                ide: ideId,
+                pathway: 'noop',
+                message: `Adapter '${ideId}' explicitly opted out of auto-compact.`
+            };
+        default:
+            // Forward-compatibility: if a new pathway is added to the
+            // union, we fall through to noop + log the unknown value.
+            return {
+                ok: false,
+                ide: ideId,
+                pathway: 'noop',
+                message: `Unknown compact pathway '${String(pathway)}' for adapter '${ideId}'.`
+            };
+    }
+}
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause: implement the
+ * `ide-native` pathway. Writes the auto-compact PreToolUse hook
+ * into `.claude/settings.local.json` (idempotent; the install
+ * service is a no-op if the hook is already present). On the next
+ * Bash/Task tool call from the runner, the hook fires
+ * `peaks compact auto` which in-band spawns
+ * `claude --compact` against the CURRENT runner session.
+ *
+ * Returns `ok: true, pathway: 'ide-native'` regardless of install
+ * action (`installed` vs `already-installed`) — both states
+ * achieve the operational goal: the hook is wired and the next
+ * Bash call will trigger it.
+ */
+async function dispatchIdeNativeHook(input) {
+    // Lazy dynamic import — matches the existing pattern in
+    // `runAutoCompact` for `auto-compact-reader.ts` (line 311) and
+    // avoids a static cycle if future slices add cross-imports
+    // between dispatcher and hook-install.
+    const { installAutoCompactHook } = await import('../hooks/auto-compact-hook-install.js');
+    const result = installAutoCompactHook({ projectRoot: input.projectRoot });
+    return {
+        ok: true,
+        ide: 'claude-code',
+        pathway: 'ide-native',
+        message: result.action === 'installed'
+            ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read CLAUDE_CONTEXT_USAGE_PERCENT and compact in-band at ratio ≥ 95%.`
+            : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { ContextPercentProbe } from './auto-compact-types.js';
+export interface ReadContextPercentInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+}
+/**
+ * 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.
+ */
+declare function readEnvPercent(env: NodeJS.ProcessEnv, varName: string): number | null;
+/**
+ * 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).
+ */
+declare function readClaudeStatuslinePercent(): number | 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.
+ */
+declare function readClaudeTranscriptFallback(sessionId: string): {
+    ratio: number;
+    bytes: number;
+} | 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 declare function readContextPercent(input: ReadContextPercentInput): ContextPercentProbe;
+/** Re-export the env-var probe for unit tests. */
+export declare const _internal: {
+    readEnvPercent: typeof readEnvPercent;
+    readClaudeStatuslinePercent: typeof readClaudeStatuslinePercent;
+    readClaudeTranscriptFallback: typeof readClaudeTranscriptFallback;
+};
+export {};