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

package/dist/services/config/workspace-state-service.d.ts

@@ -0,0 +1,30 @@
+import type { WorkspaceConfig } from './config-types.js';
+/**
+ * Workspace state (registered workspaces + current-workspace pointer)
+ * lives in `~/.peaks/workspaces.json` — NOT in the slim
+ * `~/.peaks/config.json`. The slim config only carries `version` +
+ * `ocr.llm.*`; the user's workspace bookmarks live here.
+ *
+ * This module is the only owner of workspaces.json. Back-compat reads
+ * from `~/.peaks/config.json.workspaces` / `.currentWorkspace` are
+ * tolerated for legacy configs (1.x); the next write promotes the
+ * state into `~/.peaks/workspaces.json` and the legacy config.json
+ * fields are stripped by `loadGlobalConfig` governance.
+ */
+type WorkspacesSidecar = {
+    version: string;
+    workspaces: WorkspaceConfig[];
+    currentWorkspace: string | null;
+};
+export declare function getWorkspaces(): WorkspaceConfig[];
+export declare function getCurrentWorkspace(): string | null;
+export declare function setCurrentWorkspace(workspaceId: string | null): boolean;
+export declare function addWorkspace(workspace: WorkspaceConfig): void;
+export declare function removeWorkspace(workspaceId: string): boolean;
+export declare function getWorkspaceConfig(workspaceId: string): WorkspaceConfig | null;
+export declare function getCurrentWorkspaceConfig(): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForPath(path: string): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForPath(path: string): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
+export type { WorkspacesSidecar };

package/dist/services/config/workspace-state-service.js

@@ -0,0 +1,142 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { SIDECAR_SCHEMA_VERSION, ensureSidecarVersion, workspacesConfigPath, readSidecarJson, writeSidecarJson } from './sidecar-store.js';
+import { stablePath } from '../../shared/path-utils.js';
+import { isInsidePath } from './config-safety.js';
+const EMPTY_WORKSPACES = {
+    version: SIDECAR_SCHEMA_VERSION,
+    workspaces: [],
+    currentWorkspace: null
+};
+const UNSAFE_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isSafeSegment(value) {
+    return UNSAFE_SEGMENT_PATTERN.test(value) && !value.includes('..') && !value.endsWith('.');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function sanitizeArtifactRemoteRepo(value) {
+    if (!isRecord(value) || (value.provider !== 'github' && value.provider !== 'gitlab') || typeof value.owner !== 'string' || typeof value.name !== 'string')
+        return null;
+    if (!isSafeSegment(value.owner) || !isSafeSegment(value.name))
+        return null;
+    return { provider: value.provider, owner: value.owner, name: value.name };
+}
+function sanitizeArtifactStorage(value) {
+    if (!isRecord(value))
+        return null;
+    const localPath = typeof value.localPath === 'string' ? { localPath: value.localPath } : {};
+    if (value.mode === 'local')
+        return { mode: 'local', ...localPath };
+    const remote = sanitizeArtifactRemoteRepo(value.remote);
+    if (value.mode === 'local-with-remote-sync' && remote)
+        return { mode: 'local-with-remote-sync', ...localPath, remote };
+    return null;
+}
+function sanitizeWorkspace(value) {
+    if (!isRecord(value))
+        return null;
+    const { workspaceId, name, rootPath, installedCapabilityIds } = value;
+    if (typeof workspaceId !== 'string' || !isSafeSegment(workspaceId) || typeof name !== 'string' || typeof rootPath !== 'string' || !Array.isArray(installedCapabilityIds) || !installedCapabilityIds.every((id) => typeof id === 'string'))
+        return null;
+    const artifactRepo = sanitizeArtifactRemoteRepo(value.artifactRepo);
+    const artifactStorage = sanitizeArtifactStorage(value.artifactStorage);
+    return {
+        workspaceId,
+        name,
+        rootPath,
+        installedCapabilityIds,
+        ...(artifactRepo ? { artifactRepo } : {}),
+        ...(artifactStorage ? { artifactStorage } : {})
+    };
+}
+function sanitizeWorkspaces(value) {
+    return Array.isArray(value) ? value.map(sanitizeWorkspace).filter((w) => w !== null) : [];
+}
+function loadWorkspacesSidecar() {
+    const raw = readSidecarJson(workspacesConfigPath(), EMPTY_WORKSPACES);
+    const version = ensureSidecarVersion(raw).version;
+    const workspaces = sanitizeWorkspaces(raw.workspaces);
+    const currentWorkspace = typeof raw.currentWorkspace === 'string' ? raw.currentWorkspace : null;
+    return { version, workspaces, currentWorkspace };
+}
+function saveWorkspacesSidecar(data) {
+    writeSidecarJson(workspacesConfigPath(), {
+        ...data,
+        version: SIDECAR_SCHEMA_VERSION
+    });
+}
+export function getWorkspaces() {
+    return loadWorkspacesSidecar().workspaces;
+}
+export function getCurrentWorkspace() {
+    return loadWorkspacesSidecar().currentWorkspace;
+}
+export function setCurrentWorkspace(workspaceId) {
+    if (workspaceId !== null && !isSafeSegment(workspaceId))
+        return false;
+    const data = loadWorkspacesSidecar();
+    if (workspaceId !== null) {
+        const exists = data.workspaces.some((w) => w.workspaceId === workspaceId);
+        if (!exists)
+            return false;
+    }
+    saveWorkspacesSidecar({ ...data, currentWorkspace: workspaceId });
+    return true;
+}
+export function addWorkspace(workspace) {
+    if (!isSafeSegment(workspace.workspaceId)) {
+        throw new Error('Workspace id must only contain letters, numbers, dots, underscores, or hyphens and must not contain path traversal');
+    }
+    const data = loadWorkspacesSidecar();
+    const existingIndex = data.workspaces.findIndex((w) => w.workspaceId === workspace.workspaceId);
+    const nextWorkspaces = existingIndex >= 0
+        ? data.workspaces.map((w) => (w.workspaceId === workspace.workspaceId ? workspace : w))
+        : [...data.workspaces, workspace];
+    saveWorkspacesSidecar({ ...data, workspaces: nextWorkspaces });
+}
+export function removeWorkspace(workspaceId) {
+    if (!isSafeSegment(workspaceId))
+        return false;
+    const data = loadWorkspacesSidecar();
+    const idx = data.workspaces.findIndex((w) => w.workspaceId === workspaceId);
+    if (idx < 0)
+        return false;
+    const nextWorkspaces = data.workspaces.filter((w) => w.workspaceId !== workspaceId);
+    const nextCurrent = data.currentWorkspace === workspaceId ? nextWorkspaces[0]?.workspaceId ?? null : data.currentWorkspace;
+    saveWorkspacesSidecar({ ...data, workspaces: nextWorkspaces, currentWorkspace: nextCurrent });
+    return true;
+}
+export function getWorkspaceConfig(workspaceId) {
+    return getWorkspaces().find((w) => w.workspaceId === workspaceId) ?? null;
+}
+export function getCurrentWorkspaceConfig() {
+    const data = loadWorkspacesSidecar();
+    if (!data.currentWorkspace)
+        return null;
+    return data.workspaces.find((w) => w.workspaceId === data.currentWorkspace) ?? null;
+}
+function findWorkspaceForPath(workspaces, path) {
+    const targetPath = stablePath(path);
+    const matches = workspaces.flatMap((workspace) => {
+        if (!isAbsolute(workspace.rootPath) || !existsSync(workspace.rootPath))
+            return [];
+        const rootPath = stablePath(workspace.rootPath);
+        return isInsidePath(targetPath, rootPath) ? [{ workspace, rootPath }] : [];
+    });
+    if (matches.length === 0)
+        return null;
+    return matches.reduce((best, match) => (match.rootPath.length > best.rootPath.length ? match : best)).workspace;
+}
+export function getWorkspaceConfigForPath(path) {
+    return findWorkspaceForPath(getWorkspaces(), path);
+}
+export function getWorkspaceConfigForCurrentPath() {
+    return getWorkspaceConfigForPath(process.cwd());
+}
+export function ensureWorkspaceConfigForPath(path) {
+    return getWorkspaceConfigForPath(path);
+}
+export function ensureWorkspaceConfigForCurrentPath() {
+    return ensureWorkspaceConfigForPath(process.cwd());
+}

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,37 @@
+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 code auto-compact` 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 (spawn `sh -c /compact` in the
+     *                          sub-agent's own shell, preserving the
+     *                          pre-slice behaviour).
+     * 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 context now` probe
+ * confirms.
+ */
+export declare function dispatchIdeCompact(input: DispatchIdeCompactInput): Promise<CompactDispatchResult>;

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

@@ -0,0 +1,240 @@
+/**
+ * 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:
+ *
+ *   - `shell-exec`     — peaks-loop spawns the adapter's
+ *                        `compactCommand` via `child_process.spawn`.
+ *                        Works for any IDE that accepts a slash
+ *                        command via a shell-spawnable entry point
+ *                        (Claude Code MVP: `/compact`).
+ *   - `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.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from './main-session-monitor.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 context now` 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':
+            // Slice 2026-06-28: shell-exec is only correct when the caller
+            // IS the shell whose context we want compressed. Sub-agents
+            // qualify; the main-session orchestrator does not.
+            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 await dispatchShellExec({
+                ideId,
+                command: profile.compactCommand,
+                timeoutMs
+            });
+        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 session auto-compact-hook`) 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') {
+                return await dispatchShellExec({
+                    ideId,
+                    command: profile.compactCommand,
+                    timeoutMs
+                });
+            }
+            // Lazy install: we only get here when the caller explicitly
+            // invokes `peaks code auto-compact --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}'.`
+            };
+    }
+}
+/**
+ * Spawn the adapter's `compactCommand` via child_process. Returns
+ * the dispatch envelope with `pathway: 'shell-exec'`.
+ *
+ * MVP: Claude Code registers `compactCommand: '/compact'` and
+ * `compactPathway: 'shell-exec'`. We spawn via `sh -c` so the
+ * slash-command resolves inside the runner's shell session.
+ *
+ * For other IDEs that adopt `shell-exec` in the future, the
+ * `compactCommand` field drives whatever shell-spawnable token
+ * the IDE accepts (e.g. trae's compact-token).
+ */
+function dispatchShellExec(input) {
+    return new Promise((resolve) => {
+        const child = spawn('sh', ['-c', input.command], {
+            stdio: 'ignore',
+            // Detach so the IDE's runner picks up the slash command.
+            detached: true,
+            env: process.env
+        });
+        child.unref();
+        const timer = setTimeout(() => {
+            // Don't kill — the IDE runner keeps the command alive in
+            // its own session; we just stop waiting.
+            resolve({
+                ok: true,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Compact command '${input.command}' dispatched (timeout=${input.timeoutMs}ms); IDE runner should pick it up.`
+            });
+        }, input.timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                ok: false,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Failed to spawn compact command '${input.command}': ${err.message}`
+            });
+        });
+        child.on('spawn', () => {
+            // Spawn succeeded — return immediately; the IDE runner
+            // continues processing the slash command in its own session.
+            clearTimeout(timer);
+            resolve({
+                ok: true,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Compact command '${input.command}' spawned successfully.`
+            });
+        });
+    });
+}
+/**
+ * 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 session auto-compact-hook` 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 {};