peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,221 @@
+/**
+ * `peaks container spawn | release` — slice 2026-07-29-worktree-l2-extended Part 12.
+ *
+ * L4 container isolation bridge: Part 8 landed the CLI contract
+ * (`peaks sub-agent dispatch --isolation container` is accepted
+ * and fail-fasts with ISOLATION_CONTAINER_NOT_YET_IMPLEMENTED).
+ * Part 12 implements the spawn/release CLI surface so the
+ * dispatch command can shell out to it.
+ *
+ * This file is the `peaks container` parent command. Sub-commands:
+ *   - spawn   : `docker run <image> ...` + write container lease
+ *   - release : `docker rm --force <id>` + transition lease to released
+ *
+ * Runtime requirement: `docker` CLI on PATH. The spawn checks
+ * `docker --version` first and returns CONTAINER_RUNTIME_UNAVAILABLE
+ * with a remediation hint when the daemon is not running. Windows
+ * is supported if Docker Desktop / WSL2 is installed; native podman
+ * is a follow-up (the container-lease module is runtime-agnostic).
+ *
+ * Lease is the source of truth: the dispatch record (v3) carries
+ * the leaseId; the PreToolUse gate (Part 2.B pattern) will read
+ * PEAKS_CONTAINER_LEASE_ID and consult the lease file before
+ * allowing docker-related tool calls. The gate bridge is a
+ * follow-up rid.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { containerLeaseFilePath, deserializeContainerLease, finalizeContainerLease, generateContainerLeaseId, markContainerReleased, ttlForContainerRole } from '../../services/container/container-lease.js';
+const DEFAULT_DOCKER_IMAGE = 'node:22-slim';
+function detectContainerRuntime(explicit) {
+    const tryOrder = explicit ? [explicit] : ['docker', 'podman'];
+    for (const r of tryOrder) {
+        try {
+            const version = execSync(`${r} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
+            return { ok: true, runtime: r, binary: `${r} (${version.split('\n')[0] ?? ''})` };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return {
+        ok: false,
+        stderr: explicit
+            ? `explicit --runtime ${explicit} not on PATH`
+            : 'neither docker nor podman is on PATH',
+        hint: explicit
+            ? `Install ${explicit} or pass a different --runtime.`
+            : 'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).'
+    };
+}
+function joinPathSession(projectRoot, sessionId) {
+    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
+}
+function checkDockerAvailable() {
+    // Part 43: superseded by detectContainerRuntime above; this
+    // function is preserved for callers that imported it. The
+    // container-commands.ts action handlers all use
+    // detectContainerRuntime directly.
+    return { ok: false, stderr: 'deprecated — use detectContainerRuntime' };
+}
+export function registerContainerCommand(program, io) {
+    const cmd = program.command('container').description('L4 container isolation: spawn/release container leases (Part 12; pairs with --isolation container on dispatch).');
+    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(async (options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        try {
+            const explicitRuntime = (() => {
+                if (options.runtime === 'docker')
+                    return 'docker';
+                if (options.runtime === 'podman')
+                    return 'podman';
+                return undefined;
+            })();
+            const runtime = detectContainerRuntime(explicitRuntime);
+            if (!runtime.ok) {
+                printResult(io, fail('container.spawn', 'CONTAINER_RUNTIME_UNAVAILABLE', `${runtime.stderr}: ${runtime.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;
+            }
+            const leaseId = generateContainerLeaseId();
+            const now = Date.now();
+            const ttlMs = options.ttl === undefined ? ttlForContainerRole(options.role) : Number.parseInt(options.ttl, 10);
+            if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+                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;
+            }
+            const image = options.image ?? DEFAULT_DOCKER_IMAGE;
+            const mount = options.mount ?? projectRoot;
+            // `docker run --rm -d` so the container is detached and
+            // auto-removed when stopped; --cidfile writes the
+            // container id to a file we can read back. The
+            // `--label peaks.leaseId=<id>` lets `peaks container
+            // list` / `peaks container gc` find orphans by label
+            // when the lease file is missing.
+            const cidFile = `${joinPathSession(projectRoot, sessionId).replace(/\\/g, '/')}/.${runtime.runtime}-cid-${leaseId}`;
+            try {
+                execSync(`${runtime.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            }
+            catch (err) {
+                printResult(io, fail('container.spawn', 'DOCKER_RUN_FAILED', getErrorMessage(err), { rid: options.rid, image, runtime: runtime.runtime, 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 \`${runtime.runtime} ps -a\` to inspect any leftover containers with the peaks.leaseId label.`
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const containerId = readFileSync(cidFile, 'utf8').trim();
+            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: runtime.runtime,
+                runtimeVersion: runtime.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);
+        }
+        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;
+        }
+    });
+    addJsonOption(cmd.command('release')
+        .description('Transition a container lease to released and run `docker rm --force`. Idempotent on already-released leases.')
+        .requiredOption('--lease-id <id>', 'lease id returned by `peaks container spawn`')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        try {
+            const file = containerLeaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+            if (!existsSync(file)) {
+                printResult(io, fail('container.release', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
+                    'Run `peaks container list` to inspect active leases.',
+                    'For a never-spawned lease, this is a no-op — no further action needed.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let lease;
+            try {
+                lease = deserializeContainerLease(readFileSync(file, 'utf8'));
+            }
+            catch (err) {
+                printResult(io, fail('container.release', 'LEASE_FILE_INVALID', getErrorMessage(err), { leaseId: options.leaseId, file }, [
+                    'Delete the malformed lease file manually and re-issue spawn.',
+                    'For security, release never fails open on a malformed lease.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (lease.status === 'released') {
+                printResult(io, ok('container.release', { lease, sessionId, projectRoot, alreadyReleased: true }, [], [`Lease ${lease.leaseId} already released; nothing to do.`]), options.json);
+                return;
+            }
+            let dockerRmFailed = false;
+            try {
+                const releaseRuntime = detectContainerRuntime(undefined);
+                const runtimeCmd = releaseRuntime.ok ? releaseRuntime.runtime : 'docker';
+                execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            }
+            catch {
+                dockerRmFailed = true;
+            }
+            const released = markContainerReleased(lease);
+            atomicWriteJson(file, released);
+            printResult(io, ok('container.release', { lease: released, sessionId, projectRoot, dockerRmFailed }, dockerRmFailed ? ['docker rm failed (likely the container was already removed); lease marked released.'] : [], [
+                `Lease ${lease.leaseId} marked released.`,
+                dockerRmFailed ? 'Manual `docker ps -a` + `docker rm` may be needed.' : `Container ${lease.containerId} removed.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('container.release', 'RELEASE_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, [
+                'Verify the lease id and re-run.',
+                'If the lease was never spawned, no-op.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `peaks context <sub>` — CLI surface for the ContextBuilder.
+ * Per spec §4.1 — these commands are the only sanctioned entry point;
+ * peaks-rd / peaks-qa / peaks-mut invoke them programmatically.
+ */
+import { Command } from 'commander';
+import type { DocFetcher } from '../../services/context/doc-retriever.js';
+export interface ContextCommandsOptions {
+    readonly fetcher: DocFetcher;
+}
+export declare function createContextCommands(options: ContextCommandsOptions): Command;

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

@@ -0,0 +1,85 @@
+/**
+ * `peaks context <sub>` — CLI surface for the ContextBuilder.
+ * Per spec §4.1 — these commands are the only sanctioned entry point;
+ * peaks-rd / peaks-qa / peaks-mut invoke them programmatically.
+ */
+import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { buildContext } from '../../services/context/context-builder.js';
+import { ContextJsonSchema } from '../../services/context/context-schema.js';
+export function createContextCommands(options) {
+    const context = new Command('context').description('peaks-context: build versioned, version-locked context.json (spec §4.1)');
+    context
+        .command('build')
+        .requiredOption('--goal <text>', 'user request goal')
+        .requiredOption('--project <path>', 'project root')
+        .option('--audience <role>', 'peaks-rd | peaks-qa | peaks-mut | all', 'all')
+        .option('--deps-mode <mode>', 'locked | latest', 'locked')
+        .option('--doc-budget-tokens <n>', 'token budget for renderer', '8000')
+        .requiredOption('--out <path>', 'output path for context.json')
+        .option('--json', 'machine-readable output', false)
+        .action(async (opts) => {
+        const ctx = await buildContext({
+            goal: opts.goal,
+            project: opts.project,
+            audience: opts.audience,
+            depsMode: opts.depsMode,
+            docBudgetTokens: Number(opts.docBudgetTokens),
+            out: opts.out,
+            fetcher: options.fetcher,
+        });
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ ok: true, sha256: ctx.sha256 }) + '\n');
+        }
+        else {
+            process.stdout.write(`context.json written: ${opts.out}\nsha256: ${ctx.sha256}\n`);
+        }
+    });
+    context
+        .command('validate <file>')
+        .action(async (file) => {
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        const result = ContextJsonSchema.safeParse(parsed);
+        if (!result.success) {
+            process.stderr.write(`INVALID: ${result.error.message}\n`);
+            process.exit(2);
+        }
+        process.stdout.write(`OK: ${file}\n`);
+    });
+    context
+        .command('inspect <file>')
+        .action(async (file) => {
+        const raw = await readFile(file, 'utf8');
+        const ctx = JSON.parse(raw);
+        process.stdout.write([
+            `version: ${ctx.version}`,
+            `goal: ${ctx.goal}`,
+            `sha256: ${ctx.sha256}`,
+            `deps: ${Object.keys(ctx.collector.deps).join(', ')}`,
+            `fetchedDocs: ${ctx.docRetriever.fetchedDocs.length}`,
+            `skipped: ${ctx.docRetriever.skipped.length}`,
+            `truncated: ${ctx.renderer.truncated}`,
+            `audience: ${ctx.renderer.audience}`,
+        ].join('\n') + '\n');
+    });
+    context
+        .command('schema')
+        .action(async () => {
+        // Pre-flight fix #3: read from the canonical schemas/context.schema.json
+        // (generated by Task 12) instead of serializing Zod internals at runtime.
+        // Both files must agree; if schema.json is missing, this command fails
+        // with a clear message pointing at Task 12.
+        const fs = await import('node:fs/promises');
+        try {
+            const content = await fs.readFile('schemas/context.schema.json', 'utf8');
+            process.stdout.write(content + '\n');
+        }
+        catch {
+            process.stderr.write('BLOCKED: schemas/context.schema.json not found.\n' +
+                'Run Task 12 of Plan 1 to generate it.\n');
+            process.exit(2);
+        }
+    });
+    return context;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
+ *   - 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 { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+export declare function registerContextCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,255 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
+ *   - 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)}`],
+        };
+    }
+}
+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;
+        }
+    });
+}

package/dist/cli/commands/core/artifacts-command.d.ts

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

package/dist/cli/commands/core/artifacts-command.js

@@ -0,0 +1,62 @@
+import { createArtifactInitPlan, getArtifactStatus, createGuidedArtifactSetup } from '../../../services/artifacts/artifact-service.js';
+import { getArtifactWorkspaceStatus, planArtifactSync } from '../../../services/artifacts/workspace-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, failUnsupportedNonDryRun, isArtifactProvider, isArtifactSetupStep, printResult } from '../../cli-helpers.js';
+export function registerArtifactsCommand(program, io) {
+    const artifacts = program.command('artifacts').description('Manage intermediate artifact repositories');
+    addJsonOption(artifacts.command('status').description('Show artifact repository status')).action((options) => {
+        printResult(io, ok('artifacts.status', getArtifactStatus()), options.json);
+    });
+    addJsonOption(artifacts
+        .command('init')
+        .description('Plan remote-first artifact repository initialization')
+        .requiredOption('--provider <provider>', 'artifact provider: github or gitlab')
+        .requiredOption('--name <name>', 'remote repository name')
+        .option('--path <path>', 'local artifact working copy path', '.peaks-artifacts')
+        .option('--dry-run', 'preview without creating repositories or files', true)
+        .option('--no-dry-run', 'unsupported: do not create repositories or files from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'artifacts.init', options.json);
+            return;
+        }
+        if (!isArtifactProvider(options.provider)) {
+            printResult(io, fail('artifacts.init', 'UNSUPPORTED_ARTIFACT_PROVIDER', `Unsupported provider ${options.provider}`, {}, ['Use --provider github or --provider gitlab']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('artifacts.init', createArtifactInitPlan({
+            provider: options.provider,
+            name: options.name,
+            localPath: options.path,
+            dryRun: true
+        })), options.json);
+    });
+    addJsonOption(artifacts
+        .command('sync')
+        .description('Plan sync between local artifact workspace and remote repository')
+        .option('--workspace <id>', 'workspace identifier (uses current if not specified)')
+        .option('--dry-run', 'preview sync plan without executing', true)
+        .option('--no-dry-run', 'unsupported: do not sync from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'artifacts.sync', options.json);
+            return;
+        }
+        printResult(io, ok('artifacts.sync', planArtifactSync(options.workspace, true)), options.json);
+    });
+    addJsonOption(artifacts.command('workspace').description('Show artifact workspace status for current or specified workspace').option('--workspace <id>', 'workspace identifier')).action((options) => {
+        printResult(io, ok('artifacts.workspace', getArtifactWorkspaceStatus(options.workspace)), options.json);
+    });
+    addJsonOption(artifacts.command('setup').description('Interactive guided artifact repository setup').option('--step <step>', 'start from specific step: detect, configure, validate, complete')).action((options) => {
+        const requestedStep = options.step;
+        const setup = createGuidedArtifactSetup();
+        if (requestedStep) {
+            if (!isArtifactSetupStep(requestedStep)) {
+                printResult(io, fail('artifacts.setup', 'INVALID_ARTIFACT_SETUP_STEP', `Invalid artifact setup step ${requestedStep}`, {}, ['Use one of: detect, configure, validate, complete']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            setup.step = requestedStep;
+        }
+        printResult(io, ok('artifacts.setup', setup), options.json);
+    });
+}