peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/sub-agent-shared.js

@@ -1,15 +1,12 @@
-// Slice F2 (rid-f2-ac1-wiring) — first caller of the RD dispatch policy
 // module. Before this wiring `src/services/rd/reviewer-dispatch-policy.ts`
 // had zero importers in src/ + packages/ + scripts/ and the 2 slots it
 // governs (`security-reviewer`, `perf-baseline-reviewer`) were neither
 // rejected nor rerouted by anything on the dispatch path.
 import { isDeprecatedReviewer } from '../../services/rd/reviewer-dispatch-policy.js';
-// Slice 2026-07-29-dispatch-stall-governance / S6 — `probeShell` is
 // re-exported here so the dispatch chokepoint (`dispatch-commands.ts`)
 // and the sub-agent batch-sync wait can lazily acquire a typed
 // shell-probe report without importing the env service at every
 // call site. Codifies .peaks/memory/2026-07-27-windows-shell-pref.md
-// at the dispatch / tool boundary (AC-6.2).
 export { probeShell } from '../../services/env/shell-probe.js';
 export const RECOMMENDED_ROLES = 'rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose';
 // Slice 2026-07-29-dispatch-stall-governance / S2 — align the per-
@@ -17,7 +14,6 @@ export const RECOMMENDED_ROLES = 'rd | qa | ui | txt | qa-business | qa-perf | q
 // union. The CLI --status help, the writer's isHeartbeatStatus guard,
 // and this constant must stay byte-identical (the parity test in
 // tests/unit/dispatch/heartbeat-parity.test.ts pins it). Adding
-// `cancelled` / `no-execution` closes AC-2.1; adding `never-started`
 // and `unreadable` closes the S1 status surface.
 export const HEARTBEAT_STATUSES = [
     'queued',
@@ -58,7 +54,6 @@ export function validateRole(role) {
     return null;
 }
 /**
- * Slice F2 (rid-f2-ac1-wiring) — the dispatch-side twin of the prereq-side
  * back-compat in `artifact-prerequisites.ts` (`AUDIT_SECURITY` /
  * `AUDIT_PERF` accept `rd/security-review.md` / `rd/perf-baseline.md` via
  * `legacyRelativePaths`).

package/dist/cli/commands/sub-agent-shutdown-commands.d.ts

@@ -1,7 +1,6 @@
 /**
  * `peaks sub-agent shutdown register|unregister|list` CLI verbs.
  *
- * Slice 2026-08-01-subagent-merge-and-e2e (Task 6). The sub-agent
  * dispatches a long-lived local process (vite dev, mock API, docker
  * proxy, etc.). Before it exits, it MUST register the process with
  * `peaks sub-agent shutdown register --pid <pid> --name <label>`. The

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

@@ -1,5 +1,4 @@
 /**
- * tech-commands — change-id-axis CLI registration (rid-012).
  *
  * Adds two nested subcommands under the existing `peaks tech` parent:
  *
@@ -8,14 +7,12 @@
  *
  * These are ADDITIVE — the existing session-axis commands (`peaks tech plan`
  * / `peaks tech status`) are untouched. The new subcommands reuse the
- * rid-009 helpers (validateChangeId / planArtifactPath / buildWorkspaceUnavailable)
  * via the consumer-side wrapper in
  * `src/services/tech/tech-change-id-service.ts`.
  *
  * Hard ban:
  *   - Do NOT touch the existing `runTechPlan` / `runTechStatus` /
  *     `addTechPlanOptions` / `addTechStatusOptions` in `workflow-commands.ts`
- *     (B2 contract preservation rule from the rid-009 closure record).
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
@@ -31,7 +28,6 @@ export declare function addTechChangeIdStatusOptions(command: Command): Command;
  *
  * The subcommand names are `plan-change-id` and `status-change-id` (NOT
  * `plan` / `status`) to avoid colliding with the existing session-axis
- * registrations at `workflow-commands.ts:441-445` (rid-012 risk register R6).
  */
 export declare function registerTechCommands(program: Command, io: ProgramIO): void;
 export type { _WorkspaceConfig };

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

@@ -1,5 +1,4 @@
 /**
- * tech-commands — change-id-axis CLI registration (rid-012).
  *
  * Adds two nested subcommands under the existing `peaks tech` parent:
  *
@@ -8,14 +7,12 @@
  *
  * These are ADDITIVE — the existing session-axis commands (`peaks tech plan`
  * / `peaks tech status`) are untouched. The new subcommands reuse the
- * rid-009 helpers (validateChangeId / planArtifactPath / buildWorkspaceUnavailable)
  * via the consumer-side wrapper in
  * `src/services/tech/tech-change-id-service.ts`.
  *
  * Hard ban:
  *   - Do NOT touch the existing `runTechPlan` / `runTechStatus` /
  *     `addTechPlanOptions` / `addTechStatusOptions` in `workflow-commands.ts`
- *     (B2 contract preservation rule from the rid-009 closure record).
  */
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
@@ -166,7 +163,6 @@ export function addTechChangeIdStatusOptions(command) {
  *
  * The subcommand names are `plan-change-id` and `status-change-id` (NOT
  * `plan` / `status`) to avoid colliding with the existing session-axis
- * registrations at `workflow-commands.ts:441-445` (rid-012 risk register R6).
  */
 export function registerTechCommands(program, io) {
     const tech = program.commands.find((c) => c.name() === 'tech');

package/dist/cli/commands/vendor-detect.d.ts

@@ -1,7 +1,6 @@
 /**
  * Phase B Task 20: peaks vendor-detect CLI.
  * Reports which vendor CLIs are installed on PATH + recommends default.
- * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.3
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
@@ -16,8 +15,6 @@ export declare function vendorDetect(opts: {
     };
 }>;
 /**
- * `peaks vendor-detect` CLI registration (rid-001 redo).
- * Slice 2026-08-11 detached-sub-agent-design §3.3 + §5.3 — register the
  * previously-dead-coded `vendorDetect()` handler at the top-level program
  * surface so `peaks vendor-detect --json` actually reaches it (was
  * dead-coded at the CLI seam even though the handler existed).

package/dist/cli/commands/vendor-detect.js

@@ -12,8 +12,6 @@ export async function vendorDetect(opts) {
     return { ok: true, command: 'vendor-detect', data: { installed, recommended } };
 }
 /**
- * `peaks vendor-detect` CLI registration (rid-001 redo).
- * Slice 2026-08-11 detached-sub-agent-design §3.3 + §5.3 — register the
  * previously-dead-coded `vendorDetect()` handler at the top-level program
  * surface so `peaks vendor-detect --json` actually reaches it (was
  * dead-coded at the CLI seam even though the handler existed).

package/dist/cli/commands/verdict-aggregate-command.d.ts

@@ -1,5 +1,4 @@
 /**
- * v2.13.2 AC-2 — `peaks verdict aggregate` CLI surface.
  *
  * Reads the 5 envelope sources under `.peaks/_runtime/<sid>/` for a
  * given rid, runs `aggregateVerdict()`, and prints the verdict +

package/dist/cli/commands/verdict-aggregate-command.js

@@ -8,11 +8,8 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { DEFAULT_REQUEST_TYPE } from '../../services/artifacts/artifact-prerequisites.js';
 import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
 import { contractEvidencePaths } from '../../services/workflow/pipeline-verify-gate-support.js';
-// Slice `2026-09-14-audit-artifact-rid-scoping`: the audit/review evidence
 // filenames carry the rid. The ridless names are the pre-rid locations and
-// stay readable during the back-compat window. `mut/` is NOT rid-scoped —
 // see `MUT_REPORT` in `artifact-prerequisites.ts`: no producer in the repo
-// can write a rid-scoped mut report, so probing a templated name here would
 // look for a file that no writer can create.
 //
 // The candidate lists are read FROM the contract — the same
@@ -27,7 +24,6 @@ const MUT_REL = 'mut/mut-report.json';
 const QA_REL = 'qa/test-reports';
 /**
  * The declared tiers for one artifact name, primary first. Probed by the name
- * this command used before the rid-scoping (the table matches it as either
  * the primary or a legacy tier), so the lookup survives the primary moving.
  * `verdict aggregate` is request-type-agnostic and every fanout-trigger type
  * declares these artifacts identically, so the default type's list is the
@@ -94,7 +90,6 @@ export function registerVerdictAggregateCommands(program, io) {
         }
         try {
             const sources = {
-                // v2.13.3 AC-1: use the canonical markdown-aware parser from
                 // envelopes.ts. The old inline `parseSecurityFromMarkdown`
                 // only understood shape A (`- [SEV] dim @ file:line — hint`),
                 // so real dogfood fixtures using shape B (`- HIGH: hint in file:line`)
@@ -157,7 +152,6 @@ export function registerVerdictAggregateCommands(program, io) {
     });
 }
 function readAudit(projectRoot, sid, rid, rels, parse) {
-    // Canonical rid-scoped location first, then the pre-rid locations.
     for (const rel of rels) {
         const path = join(projectRoot, '.peaks', '_runtime', sid, rel.replace('<rid>', rid));
         if (existsSync(path))
@@ -195,7 +189,6 @@ function readQa(projectRoot, sid, rid) {
 function parseMutJson(json) {
     return parseMutEnvelope(json);
 }
-// v2.13.3 AC-1: removed inline `parseSecurityFromMarkdown` /
 // `parsePerfFromMarkdown` (only handled shape A). The canonical
 // `parseSecurityEnvelope` / `parsePerfEnvelope` in envelopes.ts now
 // own the markdown parse + JSON back-compat fallback.

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

@@ -1,5 +1,4 @@
 /**
- * `peaks vm spawn | release` — slice 2026-07-29-worktree-l2-extended Part 35.
  *
  * L4 VM isolation runtime. Parallels the design of
  * `container-commands.ts` (Part 12, docker) and

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

@@ -1,5 +1,4 @@
 /**
- * `peaks vm spawn | release` — slice 2026-07-29-worktree-l2-extended Part 35.
  *
  * L4 VM isolation runtime. Parallels the design of
  * `container-commands.ts` (Part 12, docker) and
@@ -34,6 +33,8 @@ 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 { DEFAULT_VM_IMAGE, deserializeVmLease, finalizeVmLease, generateVmLeaseId, markVmReleased, ttlForVmRole, vmLeaseFilePath } from '../../services/vm/vm-lease.js';
+import { detectHypervisor } from './vm-hypervisor-probe.js';
+import { registerVmStatusCommand } from './vm-status-command.js';
 function joinPathSession(projectRoot, sessionId) {
     return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
 }
@@ -45,34 +46,6 @@ function resolveTtlMs(raw, role) {
         return ttlForVmRole(role);
     return parsed;
 }
-function detectHypervisor(requested) {
-    let binary;
-    switch (requested) {
-        case 'kvm':
-            binary = 'virsh';
-            break;
-        case 'hyperkit':
-            binary = 'hvftool';
-            break;
-        case 'hyperv':
-            binary = 'hvc';
-            break;
-    }
-    try {
-        const v = execSync(`${binary} --version`, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            encoding: 'utf8',
-            windowsHide: true
-        });
-        if (requested === 'kvm' && !existsSync('/dev/kvm')) {
-            return { ok: false, stderr: 'KVM kernel module not loaded (/dev/kvm absent)' };
-        }
-        return { ok: true, binary: `${binary} (${v.trim().split('\n')[0] ?? ''})` };
-    }
-    catch (err) {
-        return { ok: false, stderr: err.message };
-    }
-}
 function spawnVmWithHypervisor(args) {
     if (args.hypervisor === 'kvm') {
         // virsh create expects a domain XML file. We emit a minimal
@@ -134,6 +107,9 @@ export function registerVmCommand(program, io) {
     const cmd = program
         .command('vm')
         .description('L4 VM isolation: spawn/release VM leases via kvm | hyperkit | hyperv (Part 35; pairs with --isolation vm on dispatch).');
+    // The host probe rides on the same parent, so `peaks vm status`
+    // can say which prerequisite is missing before a spawn fails.
+    registerVmStatusCommand(cmd, io);
     addJsonOption(cmd
         .command('spawn')
         .description('Spawn a VM via the requested hypervisor (kvm | hyperkit | hyperv) and write a VM lease. ' +

package/dist/cli/commands/vm-hypervisor-probe.d.ts

@@ -0,0 +1,27 @@
+import type { VmHypervisor } from '../../services/vm/vm-lease.js';
+export type HypervisorProbeRow = {
+    readonly hypervisor: VmHypervisor;
+    readonly binary: string;
+    readonly available: boolean;
+    /** The version line when available; why not when it is not. */
+    readonly detail: string;
+};
+/** Every hypervisor the CLI can dispatch to, and the binary it shells out to. */
+export declare const VM_HYPERVISOR_BINARIES: ReadonlyArray<{
+    hypervisor: VmHypervisor;
+    binary: string;
+}>;
+export declare function binaryForHypervisor(requested: VmHypervisor): string;
+/**
+ * Is this hypervisor usable here right now? `kvm` needs both the libvirt CLI
+ * and the kernel device node; the others need their binary to answer.
+ */
+export declare function detectHypervisor(requested: VmHypervisor): {
+    ok: true;
+    binary: string;
+} | {
+    ok: false;
+    stderr: string;
+};
+/** Probe every dispatchable hypervisor, in the order the CLI lists them. */
+export declare function probeHypervisors(): HypervisorProbeRow[];

package/dist/cli/commands/vm-hypervisor-probe.js

@@ -0,0 +1,78 @@
+// src/cli/commands/vm-hypervisor-probe.ts
+//
+// The host-side question every `peaks vm` path has to answer: is there a
+// hypervisor on this machine that a VM could actually be created with?
+//
+// Split out of `vm-commands.ts` because two consumers need it — `vm spawn`
+// (fail-fast before leasing) and `vm status` (report every hypervisor,
+// including the ones that are absent) — and because a command file that both
+// registers commands and answers host questions is the shape this repo keeps
+// paying for in `max-lines` findings.
+//
+// Detection is a real probe, not a platform guess: the binary must answer
+// `--version`, and for KVM the kernel device node must exist. That means the
+// answer can change between two calls (an operator installs libvirt mid-run),
+// which is exactly why `vm status` reports it instead of caching it.
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+/** Every hypervisor the CLI can dispatch to, and the binary it shells out to. */
+export const VM_HYPERVISOR_BINARIES = [
+    { hypervisor: 'kvm', binary: 'virsh' },
+    { hypervisor: 'hyperkit', binary: 'hvftool' },
+    { hypervisor: 'hyperv', binary: 'hvc' }
+];
+export function binaryForHypervisor(requested) {
+    const entry = VM_HYPERVISOR_BINARIES.find((row) => row.hypervisor === requested);
+    if (entry === undefined) {
+        throw new Error(`unknown hypervisor: ${requested}`);
+    }
+    return entry.binary;
+}
+/**
+ * Is this hypervisor usable here right now? `kvm` needs both the libvirt CLI
+ * and the kernel device node; the others need their binary to answer.
+ */
+export function detectHypervisor(requested) {
+    const binary = binaryForHypervisor(requested);
+    try {
+        const version = execSync(`${binary} --version`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf8',
+            windowsHide: true
+        });
+        if (requested === 'kvm' && !existsSync('/dev/kvm')) {
+            return { ok: false, stderr: 'KVM kernel module not loaded (/dev/kvm absent)' };
+        }
+        return { ok: true, binary: `${binary} (${version.trim().split('\n')[0] ?? ''})` };
+    }
+    catch (error) {
+        const message = error.message;
+        // A binary that is not installed fails at exec time, and on Windows that
+        // error arrives in the console codepage — it renders as mojibake in the
+        // terminal. Name the cause instead of quoting it.
+        const absent = /not recognized|not found|ENOENT|Command failed/i.test(message);
+        return {
+            ok: false,
+            stderr: absent ? `${binary} is not on PATH` : (message.split('\n')[0] ?? '')
+        };
+    }
+}
+/** Probe every dispatchable hypervisor, in the order the CLI lists them. */
+export function probeHypervisors() {
+    return VM_HYPERVISOR_BINARIES.map((entry) => {
+        const detected = detectHypervisor(entry.hypervisor);
+        return detected.ok
+            ? {
+                hypervisor: entry.hypervisor,
+                binary: entry.binary,
+                available: true,
+                detail: detected.binary
+            }
+            : {
+                hypervisor: entry.hypervisor,
+                binary: entry.binary,
+                available: false,
+                detail: detected.stderr
+            };
+    });
+}

package/dist/cli/commands/vm-status-command.d.ts

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

package/dist/cli/commands/vm-status-command.js

@@ -0,0 +1,50 @@
+// src/cli/commands/vm-status-command.ts
+//
+// `peaks vm status` — the read-only host probe that rides on the `vm` parent.
+//
+// `peaks vm spawn` refuses with VM_RUNTIME_UNAVAILABLE and
+// `peaks sub-agent dispatch --isolation vm` refuses with
+// ISOLATION_VM_NOT_YET_IMPLEMENTED, but neither said WHICH prerequisite is
+// missing on the machine actually running the command: the hypervisor binary,
+// the KVM device node, or a host with no hypervisor at all. The only way to
+// find out was to attempt a spawn that was going to fail.
+//
+// This reports it, and it does not pretend the runtime exists: a probe that
+// finds libvirt on PATH still leaves `--isolation vm` refused, because the
+// missing piece is peaks' VM runtime (image, `vm exec`, per-OS bindings), not
+// the hypervisor. The envelope says so rather than letting a green probe read
+// as "vm works now".
+//
+import { probeHypervisors } from './vm-hypervisor-probe.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+export function registerVmStatusCommand(vm, io) {
+    addJsonOption(vm
+        .command('status')
+        .description('Report which VM hypervisor this host offers (read-only probe; the peaks VM runtime is a separate rid)')).action((options) => {
+        const rows = probeHypervisors();
+        const anyAvailable = rows.some((row) => row.available);
+        const data = {
+            platform: process.platform,
+            hypervisors: rows,
+            anyAvailable,
+            // The runtime statement, kept next to the probe result so the two can
+            // never be read apart.
+            dispatchIsolationVm: 'not implemented'
+        };
+        for (const row of rows) {
+            io.stdout(`${row.hypervisor}  ${row.available ? 'present' : 'absent'}  ${row.binary}: ${row.detail}`);
+        }
+        io.stdout(`platform:  ${process.platform}`);
+        const nextActions = [
+            'The peaks VM runtime (image build, `peaks vm exec`, Hyper-V/HyperKit bindings) is not implemented yet: `peaks sub-agent dispatch --isolation vm` stays refused even when a hypervisor is present.',
+            'For isolation today use --isolation worktree (L2, production) or --isolation container (L4, docker/podman).'
+        ];
+        if (!anyAvailable) {
+            printResult(io, fail('vm.status', 'VM_RUNTIME_UNAVAILABLE', `no VM hypervisor is usable on ${process.platform}: install one of virsh (KVM/libvirt, Linux), hvftool (HyperKit, macOS) or hvc (Hyper-V, Windows) — and on Linux the /dev/kvm device node — or drop --isolation and use worktree/container.`, data, nextActions), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('vm.status', data, [], nextActions), options.json);
+    });
+}

package/dist/cli/commands/wave-plan-commands.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks sub-agent wave-plan` — slice 2026-09-10-dispatch-token-and-swarm §3.
  *
  * Nested under the existing `sub-agent` verb (no new top-level verb, per the
  * project-level rule that users never learn a new CLI surface; the LLM runs

package/dist/cli/commands/web-lifecycle-commands.d.ts

@@ -1,6 +1,5 @@
 /**
  * `peaks web status|stop|install|login` — the daemon-lifecycle, acquisition and
- * persistent-login verbs (slice S2, file 13; S3 adds `install`; S4 adds `login`).
  *
  * Attaches to the `web` parent handed in by `web-commands.ts` rather than
  * looking it up: the lookup needs a fallback branch for "parent not registered

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

@@ -1,3 +1,12 @@
+/**
+ * The `peaks refactor | tech | workflow | route | autonomous | swarm | recommend`
+ * planning surface.
+ *
+ * This module is the registrar: each family owns its own file, and the two helpers
+ * they share live in `workflow-plan-helpers.ts`. The `peaks workflow` parent is
+ * created by the planning family and handed back, so the gate family attaches to
+ * the same group instead of creating a second one.
+ */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerWorkflowCommands(program: Command, io: ProgramIO): void;