peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/services/compact-statusline/compact-statusline-service.js

@@ -0,0 +1,83 @@
+// src/services/compact-statusline/compact-statusline-service.ts
+//
+// Slice 2026-07-30-compact-visibility (slice 3/4). Pure helper
+// for the 'peaks statusline compact' indicator. Reads
+// .peaks/_runtime/<sessionId>/auto-compact-pending.json +
+// compact-history.jsonl and decides the single-line text
+// the LLM should embed in Claude Code's statusline.
+//
+// State machine:
+//   - pending: a 'block' intent is sitting in
+//     auto-compact-pending.json → 'compact pending (<ratio>)'
+//   - redLine: pending.redLine === true → 'REDLINE 0.95'
+//   - just-compacted: history has an event within the last
+//     30 seconds → 'just compacted (<from>→<to>)'
+//   - idle: nothing recent → '--'
+//   - missing: no session binding or no orchestrator run yet
+//     → '' (empty)
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const JUST_COMPACTED_WINDOW_MS = 30_000;
+export function decideCompactStatusline(input) {
+    if (input.sessionId === null) {
+        return { kind: 'missing', label: '' };
+    }
+    const runtimeDir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId);
+    const pendingPath = join(runtimeDir, 'txt', 'auto-compact-pending.json');
+    const historyPath = join(runtimeDir, 'compact-history.jsonl');
+    // Priority 1: a pending compact intent.
+    if (existsSync(pendingPath)) {
+        try {
+            const raw = readFileSync(pendingPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.pending === true) {
+                if (parsed.redLine === true) {
+                    return {
+                        kind: 'red-line',
+                        label: `REDLINE ${(parsed.ratio ?? 0).toFixed(2)}`,
+                        detail: pendingPath,
+                    };
+                }
+                return {
+                    kind: 'pending',
+                    label: `compact pending (${(parsed.ratio ?? 0).toFixed(2)})`,
+                    detail: pendingPath,
+                };
+            }
+        }
+        catch { /* fall through to history check */ }
+    }
+    // Priority 2: the most recent history event is within 30s.
+    if (existsSync(historyPath)) {
+        try {
+            const mtimeMs = statSync(historyPath).mtimeMs;
+            if (input.now - mtimeMs <= JUST_COMPACTED_WINDOW_MS) {
+                const raw = readFileSync(historyPath, 'utf8');
+                const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+                const last = lines[lines.length - 1];
+                if (last !== undefined) {
+                    const parsed = JSON.parse(last);
+                    const from = (parsed.beforeRatio ?? 0).toFixed(2);
+                    const to = (parsed.ok === false) ? 'failed' : '0.0?';
+                    return {
+                        kind: 'just-compacted',
+                        label: parsed.redLine === true
+                            ? `just compacted (REDLINE ${from}→?)`
+                            : `just compacted (${from}→${to})`,
+                        detail: historyPath,
+                    };
+                }
+            }
+        }
+        catch { /* fall through to idle */ }
+    }
+    return { kind: 'idle', label: '--' };
+}
+/**
+ * Plain-text render: just the label. The LLM embeds this in
+ * the Claude Code statusline. Pure: no side effects, no I/O
+ * beyond the two file reads.
+ */
+export function renderCompactStatusline(state) {
+    return state.label;
+}

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

@@ -1,4 +1,4 @@
-import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, ConfigV2, MiniMaxProviderConfig, OcrAuthHeader, OcrConfig, OcrLlmConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
+import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, ConfigV2, OcrAuthHeader, OcrConfig, OcrLlmConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
 export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 /**
  * Load the slim 2.0 `~/.peaks/config.json` file. Returns the parsed
@@ -22,17 +22,6 @@ export type RedactedConfigValue = string | number | boolean | null | RedactedCon
     [key: string]: RedactedConfigValue;
 };
 export declare function redactConfigSecrets(value: unknown, path?: string): RedactedConfigValue;
-export type MiniMaxProviderStatus = {
-    provider: 'minimax';
-    configured: boolean;
-    baseUrlConfigured: boolean;
-    apiKeyConfigured: boolean;
-    storage: 'user-plaintext-v1';
-    nextActions: string[];
-};
-export declare function getMiniMaxProviderConfig(): MiniMaxProviderConfig;
-export declare function getMiniMaxProviderStatus(): MiniMaxProviderStatus;
-export declare function setMiniMaxProviderConfig(input: MiniMaxProviderConfig): MiniMaxProviderStatus;
 /**
  * Read the ocr LLM endpoint config from the user-layer
  * `~/.peaks/config.json`. The user populates this themselves by

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

@@ -221,7 +221,6 @@ function sanitizeBaseUrlForDisplay(value) {
         return '[invalid-url-redacted]';
     }
 }
-const MINIMAX_API_HOST = 'api.minimaxi.com';
 function isProviderBaseUrlPath(path) {
     return /^providers\.[^.]+\.baseUrl$/.test(path);
 }
@@ -234,37 +233,11 @@ function isValidProviderBaseUrl(value) {
         return false;
     }
 }
-function isValidMiniMaxBaseUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
-    }
-    catch {
-        return false;
-    }
-}
-function getMiniMaxBaseUrlCandidate(key, value) {
-    if (key === 'providers.minimax.baseUrl') {
-        return value;
-    }
-    if (key === 'providers.minimax' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
-        return value.baseUrl;
-    }
-    if (key === 'providers' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
-        return value.minimax?.baseUrl;
-    }
-    return undefined;
-}
 function validateProviderBaseUrl(value) {
     if (value !== undefined && (typeof value !== 'string' || !isValidProviderBaseUrl(value))) {
         throw new Error('Provider base URL must be HTTPS without embedded credentials, query, or fragment');
     }
 }
-function validateMiniMaxBaseUrl(value) {
-    if (value !== undefined && (typeof value !== 'string' || !isValidMiniMaxBaseUrl(value))) {
-        throw new Error('MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials');
-    }
-}
 function getProxyUrlCandidate(key, value) {
     if (key === 'proxy.httpProxy') {
         return value;
@@ -278,11 +251,8 @@ function isProxyConfigPath(path) {
     return path === 'proxy' || path.startsWith('proxy.');
 }
 function validateModelProviderConfig(providers) {
-    validateMiniMaxBaseUrl(providers.minimax?.baseUrl);
     for (const [providerId, provider] of Object.entries(providers)) {
-        if (providerId !== 'minimax') {
-            validateProviderBaseUrl(provider?.baseUrl);
-        }
+        validateProviderBaseUrl(provider?.baseUrl);
     }
 }
 function validateProviderConfig(partial) {
@@ -363,9 +333,6 @@ function toProviderModelConfig(value) {
         ...(typeof value.apiKey === 'string' ? { apiKey: value.apiKey } : {})
     };
 }
-function toMiniMaxProviderConfig(value) {
-    return toProviderModelConfig(value);
-}
 const TOKEN_CONFIG_KEYS = new Set(['AnthropicApiKey', 'OpenAiApiKey', 'GitHubToken', 'GitLabToken']);
 function toTokenRef(value) {
     if (!isRecord(value))
@@ -445,41 +412,6 @@ export function redactConfigSecrets(value, path = '') {
         return [key, redactConfigSecrets(entry, nextPath)];
     }));
 }
-function createMiniMaxProviderStatus(config) {
-    const baseUrl = config.baseUrl?.trim();
-    const apiKey = config.apiKey?.trim();
-    const baseUrlConfigured = typeof baseUrl === 'string' && baseUrl.length > 0 && isValidMiniMaxBaseUrl(baseUrl);
-    const apiKeyConfigured = typeof apiKey === 'string' && apiKey.length > 0;
-    return {
-        provider: 'minimax',
-        configured: baseUrlConfigured && apiKeyConfigured,
-        baseUrlConfigured,
-        apiKeyConfigured,
-        storage: 'user-plaintext-v1',
-        nextActions: baseUrlConfigured && apiKeyConfigured ? [] : ['Export MINIMAX_API_KEY and rerun peaks config provider minimax set --base-url <url>']
-    };
-}
-export function getMiniMaxProviderConfig() {
-    return toMiniMaxProviderConfig(readUserJsonFile()?.providers?.minimax);
-}
-export function getMiniMaxProviderStatus() {
-    return createMiniMaxProviderStatus(getMiniMaxProviderConfig());
-}
-export function setMiniMaxProviderConfig(input) {
-    validateMiniMaxBaseUrl(input.baseUrl);
-    const userConfig = readUserJsonFile() ?? {};
-    const existingProviders = toModelProviderConfig(userConfig.providers);
-    const providers = {
-        ...existingProviders,
-        minimax: {
-            ...existingProviders.minimax,
-            ...input
-        }
-    };
-    validateMiniMaxBaseUrl(providers.minimax?.baseUrl);
-    writeConfig({ providers }, 'user');
-    return createMiniMaxProviderStatus(providers.minimax ?? {});
-}
 const OCR_AUTH_HEADERS = new Set(['authorization', 'x-api-key', 'bearer']);
 function toOcrLlmConfig(value) {
     if (!isRecord(value))
@@ -552,7 +484,7 @@ function toPeaksConfig(value) {
     return {
         ...(typeof value.version === 'string' ? { version: value.version } : {}),
         ...(typeof value.language === 'string' ? { language: value.language } : {}),
-        ...(typeof value.model === 'string' && ['haiku', 'sonnet', 'opus', 'minimax'].includes(value.model) ? { model: value.model } : {}),
+        ...(typeof value.model === 'string' && ['haiku', 'sonnet', 'opus'].includes(value.model) ? { model: value.model } : {}),
         ...(typeof value.economyMode === 'boolean' ? { economyMode: value.economyMode } : {}),
         ...(typeof value.swarmMode === 'boolean' ? { swarmMode: value.swarmMode } : {}),
         ...(isRecord(value.tokens) ? { tokens: toTokenConfig(value.tokens) } : {}),
@@ -644,11 +576,10 @@ export function setConfig(options) {
     if (layer === 'project' && (isProviderConfigPath(options.key) || isProxyConfigPath(options.key) || isSensitiveConfigPath(options.key) || containsSensitiveConfigValue(options.value))) {
         throw new Error('Sensitive config keys must be stored in the user config layer');
     }
-    validateMiniMaxBaseUrl(getMiniMaxBaseUrlCandidate(options.key, options.value));
     if (options.key === 'providers') {
         validateModelProviderConfig(toModelProviderConfig(options.value));
     }
-    else if (options.key.startsWith('providers.') && !options.key.startsWith('providers.minimax.')) {
+    else if (options.key.startsWith('providers.')) {
         const providerId = getNestedPathParts(options.key)[1];
         if (options.key === `providers.${providerId}`) {
             validateModelProviderConfig({ [providerId]: toProviderModelConfig(options.value) });

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

@@ -1,14 +1,12 @@
-export type ModelPreference = 'haiku' | 'sonnet' | 'opus' | 'minimax';
-export type ModelProviderId = 'minimax' | string;
+export type ModelPreference = 'haiku' | 'sonnet' | 'opus';
+export type ModelProviderId = string;
 export type ExecutionModelId = string;
 export type ProviderModelConfig = {
     model?: ExecutionModelId;
     baseUrl?: string;
     apiKey?: string;
 };
-export type MiniMaxProviderConfig = ProviderModelConfig;
 export type ModelProviderConfig = {
-    minimax?: MiniMaxProviderConfig;
     [providerId: string]: ProviderModelConfig | undefined;
 };
 export type ProxyConfig = {

package/dist/services/config/config-types.js

@@ -1,4 +1,4 @@
-import { CLI_VERSION } from '../../shared/version.js';
+import { CLI_VERSION } from 'peaks-loop-shared/version';
 /**
  * 2.0.1 slim runtime default for `~/.peaks/config.json`. The on-disk
  * file only carries `version` + empty `ocr.llm.*` placeholders.

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/auto-compact-dispatcher.d.ts

@@ -1,3 +1,37 @@
+/**
+ * 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 {
@@ -11,15 +45,16 @@ export interface DispatchIdeCompactInput {
      * 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
+     * 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 (spawn `sh -c /compact` in the
-     *                          sub-agent's own shell, preserving the
-     *                          pre-slice behaviour).
+     *   - 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;
@@ -31,7 +66,7 @@ export interface DispatchIdeCompactInput {
  * 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
+ * context actually shrunk; the next `peaks compact auto` probe
  * confirms.
  */
 export declare function dispatchIdeCompact(input: DispatchIdeCompactInput): Promise<CompactDispatchResult>;