peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/container-spawn-command.js

@@ -0,0 +1,148 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { normalizePath } from '../../shared/path-utils.js';
+import { containerLeaseFilePath, finalizeContainerLease, generateContainerLeaseId, ttlForContainerRole } from '../../services/container/container-lease.js';
+import { DEFAULT_DOCKER_IMAGE, detectContainerRuntime, joinPathSession, resolveContainerTarget } from './container-command-shared.js';
+export function registerContainerSpawnCommand(cmd, io) {
+    addJsonOption(cmd
+        .command('spawn')
+        .description('Spawn a container via `docker run` and write a container lease. ' +
+        'The lease is the source of truth for the L4 PreToolUse gate (Part 12 follow-up). ' +
+        'Default TTL is role-aware (rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override. ' +
+        'Default image is `node:22-slim`; pass --image <name> to override.')
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this container was spawned (audit log)')
+        .option('--image <name>', `container image (default ${DEFAULT_DOCKER_IMAGE})`)
+        .option('--ttl <ms>', 'time-to-live in ms (default role-aware; override with positive number)')
+        .option('--mount <path>', 'host path to mount as the container working dir (default: <projectRoot>)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runContainerSpawn(io, options));
+}
+/** The `--runtime` flag, narrowed to the two runtimes the adapter supports. */
+function explicitRuntimeOf(options) {
+    if (options.runtime === 'docker')
+        return 'docker';
+    if (options.runtime === 'podman')
+        return 'podman';
+    return undefined;
+}
+/** Refuse `--runtime` when neither binary answers; `null` once refused. */
+function requireRuntime(options, io, projectRoot, sessionId) {
+    const detected = detectContainerRuntime(explicitRuntimeOf(options));
+    if (detected.ok)
+        return detected;
+    printResult(io, fail('container.spawn', 'CONTAINER_RUNTIME_UNAVAILABLE', `${detected.stderr}: ${detected.hint}`, { rid: options.rid, role: options.role, sessionId }, [
+        'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).',
+        'On Windows, ensure WSL2 backend is enabled and the daemon is running.',
+        'Pass --runtime docker|podman to force a specific runtime.'
+    ]), options.json);
+    process.exitCode = 1;
+    return null;
+}
+/** Resolve `--ttl`, refusing a non-positive integer; `null` once refused. */
+function requireTtl(options, io) {
+    const ttlMs = options.ttl === undefined
+        ? ttlForContainerRole(options.role)
+        : Number.parseInt(options.ttl, 10);
+    if (Number.isInteger(ttlMs) && ttlMs > 0)
+        return ttlMs;
+    printResult(io, fail('container.spawn', 'INVALID_TTL', '--ttl must be a positive integer (ms)', { ttl: options.ttl }, ['Re-run with --ttl 1800000 (30 min) or omit to use role default.']), options.json);
+    process.exitCode = 1;
+    return null;
+}
+/** The worker root the cidfile lives in; `normalizePath` keeps Windows paths sane. */
+function cidFileFor(plan) {
+    const root = normalizePath(joinPathSession(plan.projectRoot, plan.sessionId));
+    return `${root}/.${plan.detected.runtime}-cid-${plan.leaseId}`;
+}
+/**
+ * `docker run --rm -d` so the container is detached and auto-removed when
+ * stopped; `--cidfile` writes the container id to a file we read back. The
+ * `--label peaks.leaseId=<id>` lets `peaks container list` / `peaks container gc`
+ * find orphans by label when the lease file is missing.
+ *
+ * Returns the container id, or `null` once DOCKER_RUN_FAILED is emitted.
+ */
+function runDockerSpawn(plan) {
+    const { options, io, projectRoot, detected, image, mount } = plan;
+    const cidFile = cidFileFor(plan);
+    try {
+        execSync(`${detected.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${plan.leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
+    }
+    catch (err) {
+        printResult(io, fail('container.spawn', 'DOCKER_RUN_FAILED', getErrorMessage(err), { rid: options.rid, image, runtime: detected.runtime, sessionId: plan.sessionId }, [
+            'Verify the image name is reachable on the configured registry.',
+            'Verify the host path is mounted correctly (Windows: the path must be visible to WSL2).',
+            `Run \`${detected.runtime} ps -a\` to inspect any leftover containers with the peaks.leaseId label.`
+        ]), options.json);
+        process.exitCode = 1;
+        return null;
+    }
+    return readFileSync(cidFile, 'utf8').trim();
+}
+/** Write the lease and print the success envelope. */
+function finishSpawn(plan, containerId) {
+    const { options, io, projectRoot, sessionId, detected, image, mount, leaseId, now, ttlMs } = plan;
+    const lease = finalizeContainerLease({
+        leaseId,
+        rid: options.rid,
+        role: options.role,
+        path: mount,
+        image,
+        containerId,
+        createdAt: now,
+        expiresAt: now + ttlMs,
+        purpose: options.purpose
+    });
+    atomicWriteJson(containerLeaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
+    printResult(io, ok('container.spawn', {
+        lease,
+        sessionId,
+        projectRoot,
+        runtime: detected.runtime,
+        runtimeVersion: detected.binary,
+        nextActions: [
+            `Container id: ${containerId}`,
+            `Image: ${image}`,
+            `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+            'Run `peaks container release --lease-id <id>` when done'
+        ]
+    }, [], []), options.json);
+}
+function runContainerSpawn(io, options) {
+    const { projectRoot, sessionId } = resolveContainerTarget(options);
+    try {
+        const detected = requireRuntime(options, io, projectRoot, sessionId);
+        if (detected === null)
+            return;
+        const ttlMs = requireTtl(options, io);
+        if (ttlMs === null)
+            return;
+        const plan = {
+            options,
+            io,
+            projectRoot,
+            sessionId,
+            detected,
+            image: options.image ?? DEFAULT_DOCKER_IMAGE,
+            mount: options.mount ?? projectRoot,
+            leaseId: generateContainerLeaseId(),
+            now: Date.now(),
+            ttlMs
+        };
+        const containerId = runDockerSpawn(plan);
+        if (containerId === null)
+            return;
+        finishSpawn(plan, containerId);
+    }
+    catch (err) {
+        printResult(io, fail('container.spawn', 'SPAWN_FAILED', getErrorMessage(err), { rid: options.rid, sessionId }, [
+            'See error message; if the lease was not written, retry after fixing the underlying issue.'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/commands/context-check-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContextCheckCommand(context: Command, io: ProgramIO): void;

package/dist/cli/commands/context-check-command.js

@@ -0,0 +1,81 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { formatMainSessionTriggerLogLine, pickMainSessionTrigger } from '../../services/context/main-session-monitor.js';
+import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { capacityOf, requirePromptSize } from './context-status-command.js';
+/** The `--in-flight-batch` seam: a sub-agent batch defers the trigger (D6.e). */
+function inFlightOf(opts) {
+    return opts.inFlightBatch === true
+        ? { hasInFlightBatch: true, sharedChannelEntries: 1 }
+        : undefined;
+}
+/**
+ * Observability hook #5/7. Fire-and-forget per PRD Q4; the synchronous emit
+ * never throws. Only fires when a session id is resolvable.
+ */
+function emitContextTrigger(trigger, promptSize) {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const sid = getSessionIdCanonical(projectRoot) ?? '';
+    if (sid.length === 0)
+        return;
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: new Date().toISOString(),
+        sessionId: sid,
+        category: 'context-trigger',
+        detail: {
+            kind: trigger.kind,
+            promptSize,
+            ...(trigger.kind === 'soft-warn' || trigger.kind === 'compact'
+                ? { ratio: trigger.ratio }
+                : {})
+        }
+    }, { projectRoot });
+}
+/** The single advisory line the tier decides. */
+function triggerAdvice(trigger) {
+    if (trigger.kind === 'compact') {
+        return `Tier reached → trigger ${trigger.path} on ${trigger.ide} (code=${trigger.code})`;
+    }
+    if (trigger.kind === 'defer')
+        return `Deferred: ${trigger.reason}`;
+    if (trigger.kind === 'soft-warn') {
+        return `Soft warning at ${(trigger.ratio * 100).toFixed(0)}% (no trigger yet)`;
+    }
+    return 'Below threshold; no trigger';
+}
+export function registerContextCheckCommand(context, io) {
+    addJsonOption(context
+        .command('check')
+        .description('v2.11.0 D6: threshold check + IDE-aware trigger dispatch. With --auto-trigger, returns the trigger path the LLM should follow; without, returns a dry-run recommendation. The LLM is responsible for actually invoking the trigger (slash command, self-compress, or escalation).')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')
+        .option('--in-flight-batch', 'a sub-agent batch is in flight (defer trigger per D6.e)', false)
+        .option('--auto-trigger', 'return the trigger path the LLM should follow', false)).action((opts) => {
+        try {
+            const promptSize = requirePromptSize('context.check', opts, io);
+            if (promptSize === null)
+                return;
+            const trigger = pickMainSessionTrigger({
+                promptSize,
+                capacityBytes: capacityOf(opts),
+                inFlightBatch: inFlightOf(opts)
+            });
+            emitContextTrigger(trigger, promptSize);
+            const payload = {
+                ...trigger,
+                autoTrigger: opts.autoTrigger === true,
+                logLine: formatMainSessionTriggerLogLine(trigger, 'main')
+            };
+            printResult(io, ok('context.check', payload, [], [triggerAdvice(trigger)]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.check', 'CONTEXT_CHECK_FAILED', getErrorMessage(err), null, [
+                'Verify --prompt-size is a non-negative number'
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/context-commands.d.ts

@@ -1,11 +1,6 @@
 /**
  * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
  *
- *   - L0: full read (every SKILL.md in full)
- *   - L1: summary (one paragraph per skill + the skill list)
- *   - L2: index (just names + paths)
- *   - L3: fuzzy search by query (delegates to peaks memory search)
- *
  * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
  * on the L1a task level:
  *   - typo:     L0 only (a few lines)
@@ -15,6 +10,6 @@
  *   - migration: L0 + L1 + L2 + L3 + codegraph
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+import type { ProgramIO } from '../cli-helpers.js';
+export type { ContextLayer } from './context-layer-fetchers.js';
 export declare function registerContextCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/context-commands.js

@@ -1,281 +1,11 @@
-/**
- * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
- *
- *   - L0: full read (every SKILL.md in full)
- *   - L1: summary (one paragraph per skill + the skill list)
- *   - L2: index (just names + paths)
- *   - L3: fuzzy search by query (delegates to peaks memory search)
- *
- * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
- * on the L1a task level:
- *   - typo:     L0 only (a few lines)
- *   - bug:     L0 + L1
- *   - feature: L0 + L1 + L2 + L3(按需)
- *   - refactor: L0 + L1 + L2 + L3
- *   - migration: L0 + L1 + L2 + L3 + codegraph
- */
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { searchMemory } from '../../services/memory/memory-search-service.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { getSessionIdCanonical } from '../../services/session/session-manager.js';
-import { evaluateMainSessionThreshold, pickMainSessionTrigger, formatMainSessionTriggerLogLine } from '../../services/context/main-session-monitor.js';
-import { detectIdeFromEnv } from '../../services/context/ide-detect.js';
-const SKILLS_DIR = 'skills';
-function readSkillsDir(projectRoot) {
-    const skillsRoot = join(projectRoot, SKILLS_DIR);
-    if (!existsSync(skillsRoot))
-        return [];
-    const out = [];
-    for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory() || entry.name.startsWith('.'))
-            continue;
-        const skillMd = join(skillsRoot, entry.name, 'SKILL.md');
-        if (existsSync(skillMd)) {
-            out.push(`skills/${entry.name}/SKILL.md`);
-        }
-    }
-    return out;
-}
-function readSkillFile(projectRoot, relPath) {
-    const abs = join(projectRoot, relPath);
-    try {
-        return readFileSync(abs, 'utf-8');
-    }
-    catch {
-        return '';
-    }
-}
-async function fetchL0(projectRoot) {
-    const files = readSkillsDir(projectRoot);
-    const warnings = [];
-    let content = '';
-    let byteSize = 0;
-    const sizes = [];
-    for (const rel of files) {
-        const body = readSkillFile(projectRoot, rel);
-        if (body.length === 0) {
-            warnings.push(`failed to read ${rel}`);
-            continue;
-        }
-        content += `## ${rel}\n\n${body}\n\n`;
-        sizes.push({ path: rel, bytes: body.length });
-        byteSize += body.length;
-    }
-    return {
-        layer: 'L0',
-        description: 'full read: every SKILL.md concatenated',
-        files: sizes,
-        content,
-        byteSize,
-        warnings
-    };
-}
-async function fetchL1(projectRoot) {
-    const files = readSkillsDir(projectRoot);
-    const warnings = [];
-    let content = '';
-    let byteSize = 0;
-    const sizes = [];
-    for (const rel of files) {
-        const body = readSkillFile(projectRoot, rel);
-        if (body.length === 0) {
-            warnings.push(`failed to read ${rel}`);
-            continue;
-        }
-        const firstPara = body.split(/\r?\n\r?\n/, 2)[0] ?? body.slice(0, 400);
-        content += `## ${rel}\n\n${firstPara}\n\n`;
-        sizes.push({ path: rel, bytes: firstPara.length });
-        byteSize += firstPara.length;
-    }
-    return {
-        layer: 'L1',
-        description: 'summary: first paragraph per skill',
-        files: sizes,
-        content,
-        byteSize,
-        warnings
-    };
-}
-async function fetchL2(projectRoot) {
-    const files = readSkillsDir(projectRoot);
-    const content = files.map((f) => `- ${f}`).join('\n') + '\n';
-    const byteSize = content.length;
-    return {
-        layer: 'L2',
-        description: 'index: skill paths only (no body)',
-        files: files.map((f) => ({ path: f, bytes: 0 })),
-        content,
-        byteSize,
-        warnings: []
-    };
-}
-async function fetchL3(projectRoot, query) {
-    const warnings = [];
-    if (query.trim().length === 0) {
-        warnings.push('empty query; L3 requires a --query string for fuzzy search');
-        return {
-            layer: 'L3',
-            description: 'fuzzy search (empty query)',
-            files: [],
-            content: '',
-            byteSize: 0,
-            warnings
-        };
-    }
-    try {
-        const hits = searchMemory({ projectRoot, query, limit: 10 });
-        const lines = [];
-        for (const hit of hits) {
-            lines.push(`- [${hit.score.toFixed(2)}] ${hit.sourcePath}: ${hit.description.slice(0, 120)}`);
-        }
-        const content = lines.join('\n') + '\n';
-        return {
-            layer: 'L3',
-            description: 'fuzzy search: top 10 hits from memory index',
-            files: hits.map((h) => ({ path: h.sourcePath, bytes: h.description.length })),
-            content,
-            byteSize: content.length,
-            warnings
-        };
-    }
-    catch (error) {
-        return {
-            layer: 'L3',
-            description: 'fuzzy search (failed)',
-            files: [],
-            content: '',
-            byteSize: 0,
-            warnings: [`L3 search failed: ${getErrorMessage(error)}`]
-        };
-    }
-}
+import { registerContextCheckCommand } from './context-check-command.js';
+import { registerContextLayerCommand } from './context-layer-command.js';
+import { registerContextStatusCommand } from './context-status-command.js';
 export function registerContextCommands(program, io) {
     const context = program
         .command('context')
         .description('Slice L1c: context 4-layer loader (L0 full / L1 summary / L2 index / L3 fuzzy)');
-    addJsonOption(context
-        .command('layer')
-        .description('Fetch a context layer (L0 = full SKILL.md; L1 = first paragraph; L2 = index; L3 = fuzzy search by --query)')
-        .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--level <L0|L1|L2|L3>', 'context layer to load')
-        .option('--query <text>', 'fuzzy search query (required for L3)')).action(async (options) => {
-        try {
-            const level = options.level;
-            if (level !== 'L0' && level !== 'L1' && level !== 'L2' && level !== 'L3') {
-                printResult(io, fail('context.layer', 'INVALID_LEVEL', `level must be one of L0, L1, L2, L3 (got ${level})`, { provided: level }, ['Pass --level L0|L1|L2|L3']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            let payload;
-            if (level === 'L0')
-                payload = await fetchL0(options.project);
-            else if (level === 'L1')
-                payload = await fetchL1(options.project);
-            else if (level === 'L2')
-                payload = await fetchL2(options.project);
-            else
-                payload = await fetchL3(options.project, options.query ?? '');
-            printResult(io, ok('context.layer', payload, [], [
-                `${payload.layer} loaded: ${payload.byteSize} bytes across ${payload.files.length} file(s)`,
-                payload.warnings.length > 0
-                    ? `${payload.warnings.length} warning(s); see envelope.warnings`
-                    : null
-            ].filter((x) => typeof x === 'string')), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('context.layer', 'CONTEXT_LAYER_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path and --level value']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(context
-        .command('status')
-        .description('v2.11.0 D6: report main-session threshold tier for a given prompt size (no trigger dispatched). Useful for `--json` probes before invoking `peaks context check --auto-trigger`.')
-        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
-        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')).action((opts) => {
-        try {
-            const promptSize = Number(opts.promptSize);
-            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
-            if (!Number.isFinite(promptSize) || promptSize < 0) {
-                printResult(io, fail('context.status', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            const evaluation = evaluateMainSessionThreshold(promptSize, capacity);
-            printResult(io, ok('context.status', { ...evaluation, ide: detectIdeFromEnv() }, [...evaluation.warnings], [`Main-session tier=${evaluation.tier} (${(evaluation.ratio * 100).toFixed(0)}%)`]), opts.json);
-        }
-        catch (err) {
-            printResult(io, fail('context.status', 'CONTEXT_STATUS_FAILED', getErrorMessage(err), null, [
-                'Verify --prompt-size is a non-negative number'
-            ]), opts.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(context
-        .command('check')
-        .description('v2.11.0 D6: threshold check + IDE-aware trigger dispatch. With --auto-trigger, returns the trigger path the LLM should follow; without, returns a dry-run recommendation. The LLM is responsible for actually invoking the trigger (slash command, self-compress, or escalation).')
-        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
-        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')
-        .option('--in-flight-batch', 'a sub-agent batch is in flight (defer trigger per D6.e)', false)
-        .option('--auto-trigger', 'return the trigger path the LLM should follow', false)).action((opts) => {
-        try {
-            const promptSize = Number(opts.promptSize);
-            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
-            if (!Number.isFinite(promptSize) || promptSize < 0) {
-                printResult(io, fail('context.check', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            const trigger = pickMainSessionTrigger({
-                promptSize,
-                capacityBytes: capacity,
-                inFlightBatch: opts.inFlightBatch === true
-                    ? { hasInFlightBatch: true, sharedChannelEntries: 1 }
-                    : undefined
-            });
-            // Slice C of v2.11.1 — observability hook #5/7. Fire-and-forget
-            // per PRD Q4. The synchronous emit never throws.
-            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-            const sid = getSessionIdCanonical(projectRoot) ?? '';
-            if (sid.length > 0) {
-                emitObservabilityEvent({
-                    schemaVersion: 1,
-                    ts: new Date().toISOString(),
-                    sessionId: sid,
-                    category: 'context-trigger',
-                    detail: {
-                        kind: trigger.kind,
-                        promptSize,
-                        ...(trigger.kind === 'soft-warn' || trigger.kind === 'compact'
-                            ? { ratio: trigger.ratio }
-                            : {})
-                    }
-                }, { projectRoot });
-            }
-            const logLine = formatMainSessionTriggerLogLine(trigger, 'main');
-            const payload = {
-                ...trigger,
-                autoTrigger: opts.autoTrigger === true,
-                logLine
-            };
-            printResult(io, ok('context.check', payload, [], [
-                trigger.kind === 'compact'
-                    ? `Tier reached → trigger ${trigger.path} on ${trigger.ide} (code=${trigger.code})`
-                    : trigger.kind === 'defer'
-                        ? `Deferred: ${trigger.reason}`
-                        : trigger.kind === 'soft-warn'
-                            ? `Soft warning at ${(trigger.ratio * 100).toFixed(0)}% (no trigger yet)`
-                            : 'Below threshold; no trigger'
-            ]), opts.json);
-        }
-        catch (err) {
-            printResult(io, fail('context.check', 'CONTEXT_CHECK_FAILED', getErrorMessage(err), null, [
-                'Verify --prompt-size is a non-negative number'
-            ]), opts.json);
-            process.exitCode = 1;
-        }
-    });
+    registerContextLayerCommand(context, io);
+    registerContextStatusCommand(context, io);
+    registerContextCheckCommand(context, io);
 }

package/dist/cli/commands/context-layer-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContextLayerCommand(context: Command, io: ProgramIO): void;

package/dist/cli/commands/context-layer-command.js

@@ -0,0 +1,34 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fetchContextLayer, isContextLayer } from './context-layer-fetchers.js';
+/** The two advisory `nextActions` a loaded layer reports. */
+function layerActions(payload) {
+    return [
+        `${payload.layer} loaded: ${payload.byteSize} bytes across ${payload.files.length} file(s)`,
+        payload.warnings.length > 0
+            ? `${payload.warnings.length} warning(s); see envelope.warnings`
+            : null
+    ].filter((x) => typeof x === 'string');
+}
+export function registerContextLayerCommand(context, io) {
+    addJsonOption(context
+        .command('layer')
+        .description('Fetch a context layer (L0 = full SKILL.md; L1 = first paragraph; L2 = index; L3 = fuzzy search by --query)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--level <L0|L1|L2|L3>', 'context layer to load')
+        .option('--query <text>', 'fuzzy search query (required for L3)')).action(async (options) => {
+        try {
+            if (!isContextLayer(options.level)) {
+                printResult(io, fail('context.layer', 'INVALID_LEVEL', `level must be one of L0, L1, L2, L3 (got ${options.level})`, { provided: options.level }, ['Pass --level L0|L1|L2|L3']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const payload = await fetchContextLayer(options.level, options.project, options.query ?? '');
+            printResult(io, ok('context.layer', payload, [], layerActions(payload)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('context.layer', 'CONTEXT_LAYER_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path and --level value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/context-layer-fetchers.d.ts

@@ -0,0 +1,15 @@
+export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+export interface LayerPayload {
+    readonly layer: ContextLayer;
+    readonly description: string;
+    readonly files: readonly {
+        path: string;
+        bytes: number;
+    }[];
+    readonly content: string;
+    readonly byteSize: number;
+    readonly warnings: readonly string[];
+}
+/** Dispatch one layer by its validated `L0|L1|L2|L3` id. */
+export declare function fetchContextLayer(level: ContextLayer, projectRoot: string, query: string): Promise<LayerPayload>;
+export declare function isContextLayer(value: string): value is ContextLayer;