peaks-loop 4.0.17 → 4.0.19

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 4.0.19 — 2026-08-11 (detached sub-agent + G8 infinite-context — single-ship)
+
+**New feature — detached sub-agent mode (Phase A-E single-ship)**:
+- New monorepo package `peaks-loop-internal-runtime` (npm name `peaks-loop-internal-runtime`; sibling of `peaks-loop-shared`; private; consumed via `workspace:*`).
+- 11 new modules: `ProcessSupervisor` (Windows `DETACHED_PROCESS` + POSIX `setsid`), `LifecycleOwner` (closure invariant — 100% cleanup of pid / log.txt / status.json / owner-session on every exit path), `VendorAdapter` interface + `ClaudeAdapter` / `CodexAdapter` / `CopilotAdapter` + `VendorAdapterRegistry`, `PromptBuilder` (5-8KB minimum-context slice + forbidden-marker guard `@@@ORCHESTRATOR_SESSION_HISTORY_BOUNDARY@@@`), `StatusProtocol` (heartbeat merge + stale detection + autoCompact events), `AutoCompactAdapter` (G8 marker `<peaks-auto-compact threshold="0.85|0.95">` + scratch file parser), `ResourceBudgetGuard` (RSS ≤ 200MB / CPU ≤ 5% / fan-out ≤ 8 / `--no-throttle` user override), `dispatchDetached` orchestrator (wires all collaborators), `peaks-loop-internal-runtime/src/index.ts` (public re-exports).
+- 2 new CLI handlers: `src/cli/commands/sub-agent/detached.ts` (`peaks sub-agent dispatch <role> --mode detached --vendor claude|codex|copilot --no-throttle --max-concurrent <N>`), `src/cli/commands/vendor-detect.ts` (`peaks vendor-detect` — reports installed vendor CLIs + recommends default), `src/cli/commands/doctor/invoke-from-code.ts` (`peaks doctor invoke --from-code` — writes proposal stub for peaks-doctor bridge).
+- New bench: `benchmarks/runtime-detached/{baseline.ts, resource-budget-bench.ts}`. Idle sample: rssMb=79, cpuPct=0.34 (passes §5.3 ceiling rails).
+
+**G8 infinite-context auto-compact protocol (Phase A critical path)**:
+- Child vendor LLM receives `<peaks-auto-compact>` marker in minimum-context prompt.
+- At ≥ 0.85 of vendor window: child writes scratch file `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json` (summary + decisionsKept + discardedOptions) + calls `peaks runtime write-compact-event` to append `autoCompactEvents[]` to dispatch record.
+- At ≥ 0.95: synchronous compact + status.json `note: 'compact-emergency'` + peaks main process notification.
+- **Unlimited spend authorized**: G8 red line; `tokenUsage` recorded on dispatch record for audit visibility only (no alert, no kill, no user ask).
+
+**LifecycleOwner closure invariant — core red line**:
+- Every exit path (success / crash / OOM-killed / SIGTERM / orchestrator session exit) MUST remove `pid` + `log.txt` + `status.json` + `owner-session` (archived to `log-archive.txt` + `status-final.json` for forensics).
+- Orphan reaper (RL-15: user-only decision; peaks does NOT auto-kill).
+- Unit + integration test coverage (4 lifecycle + 3 integration closure audit).
+
+**Performance ceiling rails (spec §5.3)**:
+- peaks runtime RSS ≤ 200 MB idle / CPU ≤ 5% idle / fan-out ≤ 8 (default).
+- `--no-throttle --max-concurrent <N>` bypasses (user accepts risk; adds warning to envelope).
+- `peaks sub-agent cleanup --orphan` is the only orphan-killing path.
+
+**Publish lockstep 3 packages (gate-cli-version extension)**:
+- `gate-cli-version` now verifies 3 lockstep dimensions: root `package.json#version` ↔ peaks-loop-shared `dist/version.js#CLI_VERSION` ↔ peaks-loop-internal-runtime `src/index.ts#RUNTIME_VERSION` (private package — NOT in publish list; runtime is consumed via workspace:* only).
+- 2/2 lockstep test passes (`tests/unit/publish/lockstep-three-packages.test.ts`).
+
+**Doc updates**:
+- `skills/peaks-code/SKILL.md` + `skills/peaks-code/references/sub-agent-dispatch.md` — Detached mode section + G11.5 orchestrator prose obligation.
+- `skills/bee/peaks-rd/SKILL.md` + `skills/bee/peaks-qa/SKILL.md` — reviewer / sub-role `--mode detached` paragraphs.
+- `skills/peaks-code/references/lease-dashboard.html` — `detachedGraphView` empty container hook (Phase E render deferred).
+- Spec: `docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md`.
+- Plan: `docs/superpowers/plans/2026-08-10-peaks-detached-sub-agent-plan.md`.
+
+**Tests added**: 11 vitest files (15 unit + 3 integration suites): process-supervisor, lifecycle, vendor/{claude,codex,copilot}-adapter, prompt-builder, status-protocol, auto-compact-adapter, resource-budget, dispatch, sub-agent-detached, vendor-detect, doctor-invoke-from-code, lockstep-three-packages. 0 regressions in existing 106+ dispatch tests.
+
+**CI fix (publish #142)**:
+- Explicit `.js` extensions in all relative imports under `packages/peaks-loop-internal-runtime/src` (peaks-loop uses `module: NodeNext`; vitest hides this but `tsc -p tsconfig.build.json` requires `.js`).
+- Added `"peaks-loop-internal-runtime": "workspace:*"` to root `package.json` (CLI handlers consume runtime via npm name import, not relative path into `packages/`).
+
+**Backwards compat**: 100%. Default dispatch mode remains `in-process`; existing 106+ dispatch tests untouched; peak-loop-shared retains its 0.0.x SemVer.
+
+**For full design context**: `docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md` §0 + §3.2 + §3.5 + §5.3 + §6.3. Closure sediment: `.peaks/memory/2026-08-11-runtime-detached-4-0-19-ship-pending.md`.
+
+## 4.0.18 — 2026-08-10 (statusline 24h overlay)
+
+**Bug fix — statusline doesn't reflect 24h mode substate after transition**:
+- `src/services/skills/skill-statusline-service.ts`: adds `read24hOverlay` helper (name-distinct from canonical `src/services/24h-mode/store.ts:108 read24hState` so the two readers with divergent null vs empty-snapshot semantics are not confused); adds `TwentyFourHourOverlay` type (minimal `{ state: string }`); adds `twentyFourHourState: TwentyFourHourOverlay | null` field to `StatusLineModel`; populates the field in all 5 return paths of `buildStatusLineModel` (lines for projectRoot-null, invalid-presence, idle, outer-mismatch idle, and final active/stale — only the active branch calls `read24hOverlay`).
+- `src/services/skills/skill-statusline-renderer.ts`: adds `format24hSuffix(overlay, palette, capability, noColor)` exported helper; extends `renderActive` signature to a 7th arg `twentyFourHourState`; appends `[24h-<state.toLowerCase()>]` suffix in 3 active-return branches (attention-gate / activeLeaf / normal); updates the call site at line 822.
+- 12 new vitest cases in `tests/unit/skills/skill-statusline-sid-only-marker.test.ts` (3 service-layer `read24hOverlay` + 1 `buildStatusLineModel` integration + 3 `format24hSuffix` helper-level + 4 renderer-integration AC-1..AC-4 + 1 malformed-shape hardening).
+- 5 typed-fixture sites updated to include `twentyFourHourState: null` (`tests/unit/services/skills/skill-statusline-renderer.test.ts` 5 factories + `tests/unit/skills/skill-statusline-sid-only-marker.test.ts` 3 directly-constructed literals).
+
+**Safety semantics preserved**:
+- v2.15.0 `presence:check-stale --project . --json` still returns `stale: true` on outer-mismatch. `skill-presence-service.ts` / `presence-lease-service.ts` / `workspace-service.ts` / `session/**` / `audit/**` / `src/services/24h-mode/**` / `src/cli/commands/session-24h-mode.ts` are FORBIDDEN files in this slice — zero edits.
+- No new dependencies. No enum/API/command-surface changes.
+
+**Migration**: zero changes required for existing users. Active 24h mode sessions automatically pick up the new `[24h-<state>]` suffix on next statusline render after the user runs `peaks session 24h-mode transition`. Sessions without a 24h-state.json file render unchanged (back-compat).
+
 ## 4.0.17 — 2026-08-07 (Vitest worker cap + statusline SIGTERM + 9-slice shipped)
 
 **Core fix — vitest worker concurrency cap (root-cause)**:

package/dist/cli/commands/doctor/invoke-from-code.d.ts

@@ -0,0 +1,10 @@
+export declare function doctorInvokeFromCode(opts: {
+    sid: string;
+    json: boolean;
+}): Promise<{
+    ok: boolean;
+    command: string;
+    data: {
+        proposalPath: string;
+    };
+}>;

package/dist/cli/commands/doctor/invoke-from-code.js

@@ -0,0 +1,30 @@
+/**
+ * Phase D Task 24: peaks doctor invoke --from-code CLI.
+ * Contract surface for peaks-code Step 11 → peaks-doctor bridge.
+ * Writes proposal stub to .peaks/_runtime/<sid>/doctor/proposal.md.
+ * Real LLM call is delegated to peaks-doctor (Phase D Task 24 detail).
+ * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.6
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export async function doctorInvokeFromCode(opts) {
+    const dir = join('.peaks', '_runtime', opts.sid, 'doctor');
+    mkdirSync(dir, { recursive: true });
+    const proposalPath = join(dir, 'proposal.md');
+    // Stub: real implementation invokes peaks-doctor sub-skill
+    // (LLM-driven analysis of .peaks/_runtime/<sid>/txt/handoff.md
+    // + dispatch records + autoCompactEvents; emits OpenSpec proposals).
+    writeFileSync(proposalPath, [
+        '# doctor proposal (stub)',
+        '',
+        '## capability: <TBD>',
+        '## kind: <TBD>',
+        '',
+        'Real implementation: peaks-doctor LLM-driven analysis of',
+        '.peaks/_runtime/<sid>/txt/handoff.md + dispatch records.',
+    ].join('\n'));
+    // Normalize to POSIX-style separators so callers (and tests) can rely
+    // on a forward-slash contract regardless of host OS.
+    const normalizedPath = proposalPath.replaceAll('\\', '/');
+    return { ok: true, command: 'doctor.invoke.from-code', data: { proposalPath: normalizedPath } };
+}

package/dist/cli/commands/primer-command.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type PrimerOptions = {
+    project: string;
+    json?: boolean;
+};
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export declare function runPrimerAction(opts: PrimerOptions, io: ProgramIO): Promise<{
+    exitCode: 0 | 1;
+}>;
+export declare function registerPrimerCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/primer-command.js

@@ -0,0 +1,160 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRootStrict, InvalidProjectRootError } from '../../services/config/config-safety.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
+import { clearStalePresenceOnRotation } from '../../services/skills/skill-presence-service.js';
+import { gcStalePresenceLeases } from '../../services/skills/presence-lease-service.js';
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export async function runPrimerAction(opts, io) {
+    // Explicit empty / whitespace-only guard BEFORE the strict
+    // resolver. Commander's requiredOption checks presence, not
+    // emptiness; node's `resolve('')` returns cwd (silent
+    // fall-through), so we must short-circuit explicitly.
+    if (!opts.project || opts.project.trim() === '') {
+        printResult(io, fail('session.primer', 'PRIMER_EMPTY_PROJECT', '--project <path> required and must be non-empty', { project: opts.project }, ['Pass a non-empty absolute path to --project']), opts.json);
+        return { exitCode: 1 };
+    }
+    // P1 H1 option A: use NEW strict helper. Throws on NUL /
+    // non-canonical / non-existent path. The fail-open
+    // `resolveCanonicalProjectRoot` is not safe here because primer
+    // is invoked from a SessionStart hook on a path pulled from
+    // `${CLAUDE_PROJECT_DIR}` — the env var is user-controlled and
+    // may contain path traversal payloads.
+    let projectRoot;
+    try {
+        projectRoot = resolveCanonicalProjectRootStrict(opts.project);
+    }
+    catch (error) {
+        if (error instanceof InvalidProjectRootError) {
+            printResult(io, fail('session.primer', `PRIMER_INVALID_PROJECT_ROOT_${error.reason.replace(/-/g, '_').toUpperCase()}`, error.message, { project: opts.project, reason: error.reason }, ['Pass a non-empty absolute canonical path to --project']), opts.json);
+            return { exitCode: 1 };
+        }
+        throw error;
+    }
+    // Real rotation entry point (verified
+    // src/services/session/session-binding-bridge.ts:461-527).
+    // NOT the invented `runRotationCheck` from cycle-2 RD.
+    const rotation = await ensureSessionWithRotation(projectRoot);
+    const rotationOccurred = rotation.previousSessionId !== null
+        && rotation.rotationReason === 'outer-session-mismatch';
+    let clearOutcome = null;
+    if (rotationOccurred) {
+        // VERIFIED single-options-object signature (see
+        // skill-presence-service.ts:584-588). Mirror the real caller
+        // pattern at init-command.ts:324-329 with all 3 fields
+        // populated. NOTE: on 4.0.11-A sid-scoped leases this is a
+        // legacy-compat no-op (clearSkillPresence only unlinks legacy
+        // single-slot files; the real cleanup mechanism is rotation
+        // itself).
+        clearOutcome = clearStalePresenceOnRotation({
+            projectRootOverride: projectRoot,
+            currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID
+                ?? process.env.CLAUDE_CODE_SESSION_ID,
+            rotatedOutSessionId: rotation.previousSessionId
+        });
+    }
+    // Sync call (verified presence-lease-service.ts:383-414) —
+    // documented as legacy-compat no-op on 4.0.11-A sid-scoped
+    // data; iterates `input.leases ?? []` and gets `[]` on the
+    // real init-command.ts:463-466 caller.
+    const gcOutcome = gcStalePresenceLeases({
+        projectRoot,
+        trigger: 'manual'
+    });
+    printResult(io, ok('session.primer', {
+        projectRoot,
+        sessionId: rotation.sessionId,
+        rotationOccurred,
+        ...(rotation.previousSessionId !== null
+            ? { previousSessionId: rotation.previousSessionId }
+            : {}),
+        clearOutcome,
+        gcOutcome: {
+            removed: gcOutcome.removed,
+            retained: gcOutcome.retained
+        }
+    }), opts.json);
+    return { exitCode: 0 };
+}
+export function registerPrimerCommand(program, io) {
+    // Reuse the existing `session` commander group registered earlier
+    // in `createProgram` (via autoRegisterAllCommands → session-command.ts:32).
+    // Creating a new `program.command('session')` here throws
+    // `cannot add command 'session' as already have command 'session'`
+    // because commander disallows duplicate top-level command names.
+    // This regression was caught in publish.yml gate-changeset step
+    // (run #134, exit 1) on the first 4.0.18 release attempt.
+    const session = program.commands.find((c) => c.name() === 'session');
+    if (!session) {
+        throw new Error('registerPrimerCommand: session group not registered; ' +
+            'autoRegisterAllCommands must run before registerPrimerCommand');
+    }
+    session
+        .command('primer')
+        .description('Lightweight SessionStart primer: rotation + presence cleanup. ' +
+        'Does NOT bootstrap project scan / materialize settings / install hooks. ' +
+        'Idempotent; safe to run on every SessionStart.')
+        .requiredOption('--project <path>', 'Project root (must be non-empty canonical path)')
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action(async (opts) => {
+        try {
+            const { exitCode } = await runPrimerAction(opts, io);
+            if (exitCode !== 0) {
+                process.exitCode = exitCode;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(io, fail('session.primer', 'PRIMER_FAILED', message, { project: opts.project }, ['Verify the project path exists, is writable, and is canonical']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,29 @@
+export interface DispatchFlags {
+    role: string;
+    prompt: string;
+    requestId: string;
+    mode?: 'in-process' | 'detached';
+    vendor?: 'claude' | 'codex' | 'copilot';
+    project: string;
+    json: boolean;
+    /** Task 11.5: bypass ResourceBudgetGuard (user accepts risk) */
+    noThrottle?: boolean;
+    /** Task 11.5: override max concurrent (default 8) */
+    maxConcurrent?: number;
+}
+export declare function dispatch(f: DispatchFlags): Promise<{
+    ok: boolean;
+    command: string;
+    data: {
+        mode: string;
+        vendor: "claude" | "codex" | "copilot" | undefined;
+        pid: number;
+        dispatchRecordPath: string;
+        maxConcurrent: number;
+        noThrottle: boolean;
+        orchestratorVisibleHint: string;
+        expectedCompletionSeconds: number;
+    };
+    warnings: string[];
+    nextActions: string[];
+}>;

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

@@ -0,0 +1,60 @@
+/**
+ * Phase A Task 11 + 11.5: peaks sub-agent dispatch --mode detached CLI handler.
+ * Vendor-neutral detached sub-agent dispatch. Spawns real OS process via
+ * peaks-loop-internal-runtime/dispatch.dispatchDetached. --no-throttle and
+ * --max-concurrent flags bypass / scope ResourceBudgetGuard (Task 11.5).
+ *
+ * Default mode is in-process (backward compat — existing 106+ tests untouched).
+ * This handler only fires when the user explicitly passes --mode detached.
+ * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.1 §5.3
+ */
+import { dispatchDetached, ResourceBudgetGuard } from 'peaks-loop-internal-runtime';
+export async function dispatch(f) {
+    if (f.mode !== 'detached') {
+        throw new Error('src/cli/commands/sub-agent/detached.ts only handles --mode detached; ' +
+            'peaks sub-agent dispatch default mode remains in-process (backward compat)');
+    }
+    // Task 11.5: ResourceBudgetGuard gate
+    const maxConcurrent = f.maxConcurrent ?? 8;
+    const guard = new ResourceBudgetGuard({ maxRssMb: 200, maxCpuPct: 5 });
+    const enforce = guard.enforce({ active: 1 }, { maxConcurrent });
+    const warnings = [];
+    if (enforce.throttle && !f.noThrottle) {
+        throw new Error('RESOURCE_BUDGET_THROTTLED: concurrent fan-out > max-concurrent; pass --no-throttle to bypass');
+    }
+    if (f.noThrottle) {
+        warnings.push('user-overrode: --no-throttle (peak runtime may exceed performance ceiling)');
+    }
+    const sid = process.env.PEAKS_SESSION_ID ?? 'local';
+    const r = await dispatchDetached({
+        sid,
+        rid: f.requestId,
+        role: f.role,
+        vendor: (f.vendor ?? 'claude'),
+        userTask: f.prompt,
+        files: [],
+        refs: [],
+        runtimeDir: `.peaks/_runtime/${sid}/detached`,
+        subAgentsDir: `.peaks/_sub_agents/${sid}`,
+    });
+    return {
+        ok: true,
+        command: 'sub-agent.dispatch.detached',
+        data: {
+            mode: 'detached',
+            vendor: f.vendor,
+            pid: r.pid,
+            dispatchRecordPath: r.dispatchRecordPath,
+            maxConcurrent,
+            noThrottle: f.noThrottle ?? false,
+            orchestratorVisibleHint: `⏳ Spawning detached sub-agent via ${f.vendor ?? 'claude'}: rid=${f.requestId} (ETA ~60s)`,
+            expectedCompletionSeconds: 60,
+        },
+        warnings,
+        nextActions: [
+            'Sub-agent runs as detached OS process. Status at .peaks/_runtime/<sid>/detached/<rid>/status.json',
+            'Use `peaks sub-agent list --mode detached` to monitor.',
+            'Run `peaks sub-agent cleanup --orphan` to reap orphan processes (RL-15: user-only decision).',
+        ],
+    };
+}

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

@@ -0,0 +1,10 @@
+export declare function vendorDetect(opts: {
+    json: boolean;
+}): Promise<{
+    ok: boolean;
+    command: string;
+    data: {
+        installed: string[];
+        recommended: string | null;
+    };
+}>;

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { defaultRegistry } from 'peaks-loop-internal-runtime';
+export async function vendorDetect(opts) {
+    const reg = defaultRegistry();
+    const list = reg.list();
+    const installed = [];
+    for (const a of list)
+        if (await a.detectInstalled())
+            installed.push(a.id);
+    const recommended = installed[0] ?? null;
+    return { ok: true, command: 'vendor-detect', data: { installed, recommended } };
+}

package/dist/cli/program.js

@@ -16,6 +16,7 @@ import { registerCronSchedulerCommand } from './commands/cron-scheduler-commands
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
+import { registerPrimerCommand } from './commands/primer-command.js';
 import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 import { printSuperCommandCatalog } from './cli-helpers.js';
@@ -209,5 +210,12 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // registerCoreAndArtifactCommands instead of being created twice.
     autoRegisterAllCommands(program, io);
     registerSkillVisibilityCommand(program, repoRoot);
+    // Slice rid-statusline-stale-ux AC-2: register `peaks session primer`
+    // so it appears in `peaks session --help` for LLM `<TAB>`-discovery.
+    // Mounted as a CHILD of the existing `session` commander group
+    // (verified at src/cli/commands/core/session-command.ts:32). NOT
+    // `program.command('session primer')` (that registers a single
+    // literal command name, not a child of the session group).
+    registerPrimerCommand(program, io);
     return program;
 }

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

@@ -28,6 +28,29 @@ export declare function resolveProjectRootForConfig(startPath: string): string;
  * `git rev-parse` exit; both fall through to the heuristic.
  */
 export declare function resolveCanonicalProjectRoot(startPath: string): string;
+/**
+ * Slice rid-statusline-stale-ux AC-2 + P1 H1 option A: strict
+ * canonicalization for use in trust-boundary paths (e.g.
+ * `peaks session primer`).
+ *
+ * Unlike `resolveCanonicalProjectRoot` (fail-open, returns `start`
+ * on any resolution failure), this helper THROWS on:
+ *   - empty / whitespace-only input
+ *   - NUL byte in input
+ *   - non-existent path (realpathSync ENOENT)
+ *   - non-canonical (symlink) input (when the input path and its
+ *     realpath differ in a way that suggests the user passed a
+ *     symlinked path through a security-sensitive surface)
+ *
+ * Existing fail-open `resolveCanonicalProjectRoot` is retained for
+ * back-compat — many callers depend on the fail-open behavior
+ * (e.g. `init-command.ts:32`). The strict variant is opt-in.
+ */
+export declare class InvalidProjectRootError extends Error {
+    readonly reason: 'empty' | 'nul-byte' | 'non-existent' | 'non-canonical';
+    constructor(reason: 'empty' | 'nul-byte' | 'non-existent' | 'non-canonical', input: string);
+}
+export declare function resolveCanonicalProjectRootStrict(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;

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

@@ -131,6 +131,68 @@ export function resolveCanonicalProjectRoot(startPath) {
     }
     return start;
 }
+/**
+ * Slice rid-statusline-stale-ux AC-2 + P1 H1 option A: strict
+ * canonicalization for use in trust-boundary paths (e.g.
+ * `peaks session primer`).
+ *
+ * Unlike `resolveCanonicalProjectRoot` (fail-open, returns `start`
+ * on any resolution failure), this helper THROWS on:
+ *   - empty / whitespace-only input
+ *   - NUL byte in input
+ *   - non-existent path (realpathSync ENOENT)
+ *   - non-canonical (symlink) input (when the input path and its
+ *     realpath differ in a way that suggests the user passed a
+ *     symlinked path through a security-sensitive surface)
+ *
+ * Existing fail-open `resolveCanonicalProjectRoot` is retained for
+ * back-compat — many callers depend on the fail-open behavior
+ * (e.g. `init-command.ts:32`). The strict variant is opt-in.
+ */
+export class InvalidProjectRootError extends Error {
+    reason;
+    constructor(reason, input) {
+        super(`Invalid project root (${reason}): "${input}"`);
+        this.reason = reason;
+        this.name = 'InvalidProjectRootError';
+    }
+}
+export function resolveCanonicalProjectRootStrict(startPath) {
+    if (!startPath || startPath.trim() === '') {
+        throw new InvalidProjectRootError('empty', startPath);
+    }
+    if (startPath.indexOf('\0') !== -1) {
+        throw new InvalidProjectRootError('nul-byte', startPath);
+    }
+    const start = resolve(startPath);
+    let realStart;
+    try {
+        realStart = realpathSync(start);
+    }
+    catch {
+        throw new InvalidProjectRootError('non-existent', startPath);
+    }
+    if (realStart !== start) {
+        // User passed a path through a symlink; reject as non-canonical
+        // for trust-boundary entry points.
+        throw new InvalidProjectRootError('non-canonical', startPath);
+    }
+    // Delegate to the existing canonicalization (git root → heuristic)
+    // AFTER the strict pre-checks pass.
+    const canonical = resolveCanonicalProjectRoot(startPath);
+    if (canonical === startPath || canonical === realStart) {
+        return canonical;
+    }
+    // Canonicalization moved the path (e.g. to a git root) — accept it
+    // but ensure it also exists.
+    try {
+        realpathSync(canonical);
+        return canonical;
+    }
+    catch {
+        throw new InvalidProjectRootError('non-existent', startPath);
+    }
+}
 function resolveProjectRootFromGit(startPath) {
     // execFileSync (not execSync) so a malicious `startPath` cannot
     // inject argv into the spawned git invocation. The child only