peaks-loop 4.0.18 → 4.0.19

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # 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**:

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/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/services/dispatch/dispatch-record-writer.d.ts

@@ -34,16 +34,13 @@ export interface DispatchRecord {
      * defaulted to `null` on read so v3 records upgrade cleanly.
      */
     /**
-     * Slice 2026-07-29-rid-prose-only-sweep Part 34: schema v3.1
-     * is the explicit minor bump that records the
-     * `isolationStartedAt` (Part 7) and `leaseId` (Part 3.A.1 +
-     * Part 4.C) fields as part of the canonical schema. v3
-     * records on disk upgrade transparently — see `upgradeRecord`
-     * in this file. The literal type ('3.1') is the source of
-     * truth for "this record is v3.1-form"; readers check
-     * `version === '3.1'` for forward-compatible dispatching.
+     * Phase A Task 8: schema bumped to v4.1.0 (additive). The bump
+     * is purely additive — new fields (`mode`, `vendor`,
+     * `autoCompactEvents`, `tokenUsage`) all default safely on
+     * read for legacy v4.0.0 / v3.2 / v3.1 / v3 / v2 / v1 records.
+     * No existing field semantics changed.
      */
-    readonly version: '4.0.0';
+    readonly version: '4.1.0';
     readonly createdAt: string;
     readonly completedAt: string | null;
     readonly outcome: DispatchOutcome;
@@ -136,6 +133,49 @@ export interface DispatchRecord {
     readonly workflowId: string | null;
     readonly graphNodeId: string | null;
     readonly graphRef: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. `in-process` is the
+     * current behavior (LLM-side runner, no separate OS process).
+     * `detached` is the new path: `peaks sub-agent dispatch --mode
+     * detached` spawns a real child OS process running a different
+     * LLM vendor (claude / codex / copilot) and reports back via
+     * the dispatch record. v4.1.0 is the additive bump; legacy v4.0.0
+     * records upgrade to `in-process` on read.
+     */
+    readonly mode: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. `null` when
+     * the dispatch is in-process. Reserved for future use; current
+     * detached sub-agents use `claude` but the schema also accepts
+     * `codex` and `copilot` for the vendor-neutral adapter layer.
+     */
+    readonly vendor: 'claude' | 'codex' | 'copilot' | null;
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM during a detached run. Each event records the threshold
+     * that fired (0.85 = first warning, 0.95 = second warning) plus
+     * token counts before/after. Empty for in-process dispatches
+     * and for legacy records upgraded on read.
+     */
+    readonly autoCompactEvents: ReadonlyArray<{
+        readonly at: number;
+        readonly threshold: '0.85' | '0.95';
+        readonly tokensBefore: number;
+        readonly tokensAfter: number;
+        readonly scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting for detached sub-agents.
+     * Detached runs have "unlimited spend but recorded" semantics —
+     * the cost is recorded for audit but not enforced. `null` when
+     * the dispatch is in-process (no detached accounting) or for
+     * legacy records upgraded on read.
+     */
+    readonly tokenUsage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalCostUsd?: number;
+    } | null;
 }
 /** Input for the initial write. */
 export type WriteInitialDispatchInput = {
@@ -172,6 +212,43 @@ export type WriteInitialDispatchInput = {
     workflowId?: string | null;
     graphNodeId?: string | null;
     graphRef?: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. Default `'in-process'`
+     * preserves the current LLM-side runner behavior. `'detached'`
+     * triggers the new real-OS-process path via
+     * `peaks sub-agent dispatch --mode detached`.
+     */
+    mode?: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. Required by
+     * the adapter layer to know which CLI / runtime to spawn. The
+     * schema accepts the three vendors peaks-loop has adapters for
+     * (claude / codex / copilot). Ignored when `mode='in-process'`.
+     */
+    vendor?: 'claude' | 'codex' | 'copilot';
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM. Optional on input — most dispatches start with an empty
+     * array and the detached runner appends events as they fire.
+     */
+    autoCompactEvents?: Array<{
+        at: number;
+        threshold: '0.85' | '0.95';
+        tokensBefore: number;
+        tokensAfter: number;
+        scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting. Detached runs
+     * record spend for audit (unlimited, but persisted). Optional
+     * on input; the detached runner fills this in as it streams
+     * usage from the vendor API.
+     */
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalCostUsd?: number;
+    };
 };
 /** Heartbeat write input. */
 export type AppendHeartbeatInput = {

package/dist/services/dispatch/dispatch-record-writer.js

@@ -86,7 +86,7 @@ export function writeInitialDispatchRecord(input) {
 function buildInitialDispatchRecord(input, now) {
     const { role, requestId, sessionId, prompt, toolCall, batchId } = input;
     return {
-        version: '4.0.0',
+        version: '4.1.0',
         createdAt: now().toISOString(),
         completedAt: null,
         outcome: 'no-execution',
@@ -141,6 +141,22 @@ function buildInitialDispatchRecord(input, now) {
         workflowId: typeof input.workflowId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(input.workflowId) ? input.workflowId : null,
         graphNodeId: typeof input.graphNodeId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(input.graphNodeId) ? input.graphNodeId : null,
         graphRef: typeof input.graphRef === 'string' && input.graphRef.length > 0 ? input.graphRef : null,
+        // Phase A Task 8: detached sub-agent mode (default in-process).
+        mode: input.mode === 'detached' ? 'detached' : 'in-process',
+        vendor: input.vendor === 'claude' || input.vendor === 'codex' || input.vendor === 'copilot' ? input.vendor : null,
+        autoCompactEvents: Array.isArray(input.autoCompactEvents)
+            ? input.autoCompactEvents.filter((e) => typeof e?.at === 'number' &&
+                (e?.threshold === '0.85' || e?.threshold === '0.95') &&
+                typeof e?.tokensBefore === 'number' &&
+                typeof e?.tokensAfter === 'number')
+            : [],
+        tokenUsage: typeof input.tokenUsage === 'object' && input.tokenUsage !== null && typeof input.tokenUsage.promptTokens === 'number' && typeof input.tokenUsage.completionTokens === 'number'
+            ? {
+                promptTokens: input.tokenUsage.promptTokens,
+                completionTokens: input.tokenUsage.completionTokens,
+                ...(typeof input.tokenUsage.totalCostUsd === 'number' ? { totalCostUsd: input.tokenUsage.totalCostUsd } : {}),
+            }
+            : null,
     };
 }
 function activeDispatchIndexPath(projectRoot, sessionId) {
@@ -663,18 +679,19 @@ function upgradeRecord(parsed) {
         throw new Error('Dispatch record root must be an object');
     }
     const obj = parsed;
-    // Slice 4.0.8: 3.2 → 4.0.0 schema bump. The literal type narrows
-    // to '4.0.0' but legacy v3.2 / v3.1 / 3 / 2 / 1 records are
-    // accepted transparently and upgraded on read.
+    // Slice 4.0.8: 3.2 → 4.0.0 schema bump. Phase A Task 8: 4.0.0 → 4.1.0
+    // (additive). The literal type narrows to '4.1.0' but legacy v4.0.0 /
+    // v3.2 / v3.1 / 3 / 2 / 1 records are accepted transparently and
+    // upgraded on read.
     const rawVersion = obj.version;
-    if (rawVersion !== '4.0.0' && rawVersion !== '3.2' && rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
-        throw new Error(`Dispatch record version mismatch: expected '4.0.0', '3.2', '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
-            'The v1 → v4.0.0 migration is in-file; records from much older or newer builds must be regenerated.');
+    if (rawVersion !== '4.1.0' && rawVersion !== '4.0.0' && rawVersion !== '3.2' && rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
+        throw new Error(`Dispatch record version mismatch: expected '4.1.0', '4.0.0', '3.2', '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
+            'The v1 → v4.1.0 migration is in-file; records from much older or newer builds must be regenerated.');
     }
     const legacy = parseUpgradeRecordLegacyFields(obj);
     const migration = parseUpgradeRecordMigrationFields(obj);
     return {
-        version: '4.0.0',
+        version: '4.1.0',
         createdAt: legacy.createdAt,
         completedAt: legacy.completedAt,
         outcome: legacy.outcome,
@@ -697,7 +714,16 @@ function upgradeRecord(parsed) {
         mergeBackAttempts: migration.mergeBackAttempts,
         workflowId: migration.workflowId,
         graphNodeId: migration.graphNodeId,
-        graphRef: migration.graphRef
+        graphRef: migration.graphRef,
+        // Phase A Task 8: detached sub-agent fields. Legacy records
+        // (pre-4.1.0) default mode='in-process', vendor=null,
+        // autoCompactEvents=[], tokenUsage=null. See
+        // parseUpgradeRecordMigrationFields for the per-field
+        // validation rules.
+        mode: migration.mode,
+        vendor: migration.vendor,
+        autoCompactEvents: migration.autoCompactEvents,
+        tokenUsage: migration.tokenUsage
     };
 }
 /**
@@ -812,7 +838,29 @@ function parseUpgradeRecordMigrationFields(obj) {
         // fields to `null` so a legacy record upgrades transparently.
         workflowId: typeof obj.workflowId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.workflowId) ? obj.workflowId : null,
         graphNodeId: typeof obj.graphNodeId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.graphNodeId) ? obj.graphNodeId : null,
-        graphRef: typeof obj.graphRef === 'string' ? obj.graphRef : null
+        graphRef: typeof obj.graphRef === 'string' ? obj.graphRef : null,
+        // Phase A Task 8: 4.0.0 → 4.1.0 migration. Pre-4.1.0 records
+        // have no mode / vendor / autoCompactEvents / tokenUsage
+        // fields. Default to safe in-process / null / [] / null so
+        // legacy records upgrade transparently without breaking
+        // consumers (e.g. the dashboard, the merge-back-runner).
+        mode: obj.mode === 'detached' ? 'detached' : 'in-process',
+        vendor: obj.vendor === 'claude' || obj.vendor === 'codex' || obj.vendor === 'copilot' ? obj.vendor : null,
+        autoCompactEvents: Array.isArray(obj.autoCompactEvents)
+            ? obj.autoCompactEvents.filter((e) => typeof e?.at === 'number' &&
+                (e?.threshold === '0.85' || e?.threshold === '0.95') &&
+                typeof e?.tokensBefore === 'number' &&
+                typeof e?.tokensAfter === 'number')
+            : [],
+        tokenUsage: typeof obj.tokenUsage === 'object' && obj.tokenUsage !== null && typeof obj.tokenUsage.promptTokens === 'number' && typeof obj.tokenUsage.completionTokens === 'number'
+            ? {
+                promptTokens: obj.tokenUsage.promptTokens,
+                completionTokens: obj.tokenUsage.completionTokens,
+                ...(typeof obj.tokenUsage.totalCostUsd === 'number'
+                    ? { totalCostUsd: obj.tokenUsage.totalCostUsd }
+                    : {}),
+            }
+            : null
     };
 }
 function isObject(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.18",
+  "version": "4.0.19",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,9 +101,10 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.21",
-    "peaks-loop-shared": "0.0.49",
-    "peaks-loop-shared-channel": "0.0.25"
+    "peaks-loop-internal-runtime": "4.0.0",
+    "peaks-loop-mut": "0.1.22",
+    "peaks-loop-shared": "0.0.50",
+    "peaks-loop-shared-channel": "0.0.26"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-qa/SKILL.md

@@ -259,3 +259,7 @@ QA contracts to assert on the L2 surface (a minimal acceptance test set):
 2. `peaks worktree list` reports 0 active leases after a clean run.
 3. `peaks lease-metrics --rate` after a 1-spawn / 0-release test reports `estimatedLeaked: 1, completedLifetimes: 0`.
 4. `peaks audit red-lines` reports `proseOnly: 0` and `partial: 0` for any shipped L2 surface.
+
+## Sub-role detached mode (Phase C, slice 2026-08-10)
+
+QA sub-roles (`qa-business`, `qa-perf`, `qa-security`, `qa-business-api`, `qa-business-frontend`, `qa-business-regression`) accept `--mode detached --vendor <vendor>` for parallel test-case execution. Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached`, isolated from the orchestrator session. Use detached mode when the test-case writer's expected runtime exceeds 60s OR it processes ≥ 20 source files. The default remains `in-process` (backward compat; existing 106+ dispatch tests untouched). When `--mode detached` is used, the child QA agent receives the G8 infinite-context auto-compact marker (0.85 / 0.95 thresholds; unlimited spend authorized). See `peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.

package/skills/bee/peaks-rd/SKILL.md

@@ -151,6 +151,10 @@ Both audit skills consume the immutable peaks-prd handoff (`prd/handoff.md`) and
 
 Full dispatch contract (when-to-fan-out rules, dispatch template, prereq gates) lives in **`references/parallel-review-fanout.md`**. Read that file before issuing any 3-way fan-out.
 
+## Reviewer fan-out detached mode (Phase C, slice 2026-08-10)
+
+Reviewer fan-out may run in detached mode for any of the 3-way fan-out roles (`code-reviewer`, `qa-test-cases-writer`, `karpathy-reviewer`). Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached --vendor <vendor>`, isolated from the orchestrator session. Use detached mode when the reviewer's expected runtime exceeds 60s OR processes ≥ 20 source files. Pass `--mode detached` explicitly per reviewer role; the default remains `in-process` (backward compat). The karpathy-reviewer's G8 infinite-context marker (auto-compact at 0.85/0.95, unlimited spend) is honored automatically when `--mode detached` is used. See `peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.
+
 ## Refactor hard gates
 
 If a request is refactor, cleanup, architecture adjustment, module split, or technical debt work: scan project structure and existing standards; locate or run UT coverage; block implementation unless coverage is >= 95%; treat missing, unknown, or unverifiable coverage as failing; generate intermediate artifacts before implementation; call or consume peaks-prd and peaks-qa artifacts even in direct RD mode; require strict slice spec before each slice; require 100% acceptance for the slice; require code changes and intermediate artifacts to be traceable in local `.peaks/_runtime/<sessionId>/` storage before continuing.

package/skills/peaks-code/SKILL.md

@@ -3,6 +3,9 @@ name: peaks-code
 description: Code-domain loop engineering orchestrator for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a code-repo workflow end-to-end (端到端/全流程/需求开发), especially from a product document (PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-code`, "peaks code", "全流程开发", "端到端迭代". General primitives (peaks-resume / peaks-status / peaks-test) are sibling skills, not children.
 ---
 
+> **Detached sub-agent mode (Phase A, slice 2026-08-10).** When the orchestrator requires true parallelism with isolated context windows and survives orchestrator session exit, dispatch sub-agents with `--mode detached --vendor <claude|codex|copilot>`. The CLI spawns a real OS process via `ProcessSupervisor` (Windows `DETACHED_PROCESS` + `CREATE_NEW_PROCESS_GROUP`, POSIX `setsid` + `nohup`); the child vendor LLM receives a 5–8KB minimum prompt slice (no orchestrator session history) and self-compacts at 0.85 / 0.95 against the vendor window via the `<peaks-auto-compact>` marker (G8 — unlimited spend authorized). Orchestrator MUST emit one line of prose before every detached dispatch: `⏳ Spawning detached sub-agent via <vendor>: rid=<rid> (ETA ~60s)`. Status is read from `.peaks/_runtime/<sid>/detached/<rid>/status.json`; `LifecycleOwner` enforces 100% cleanup of `pid` / `log.txt` / `status.json` / `owner-session` on every exit path. `--no-throttle --max-concurrent <N>` bypasses `ResourceBudgetGuard` (user accepts risk; default max=8). See `references/sub-agent-dispatch.md` §"Detached Mode" for the full contract. Default mode remains `in-process` for backward compat (existing 106+ dispatch tests untouched).
+---
+
 ## Scope (RL-8 — red line, locked 2026-07-08)
 
 `peaks-code` is a **code-domain long-task loop engineering orchestrator; not a general-purpose orchestrator.**

package/skills/peaks-code/references/sub-agent-dispatch.md

@@ -423,3 +423,19 @@ After every sub-agent dispatch returns, Code **restores presence** once (not per
 ```bash
 peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-converged
 ```
+
+---
+
+## Detached Mode (Phase A, slice 2026-08-10)
+
+`peaks sub-agent dispatch <role> --prompt <text> --request-id <rid> --mode detached --vendor claude|codex|copilot [--no-throttle --max-concurrent <N>] --json` spawns a real OS process independent of the orchestrator IDE session.
+
+- **Cross-platform spawn**: Windows uses `DETACHED_PROCESS` + `CREATE_NEW_PROCESS_GROUP`; POSIX uses `setsid` + `nohup`. Implementation: `packages/peaks-loop-internal-runtime/src/process-supervisor.ts`.
+- **Minimum-context prompt**: `PromptBuilder` emits a 5–8KB slice `{rid, role, vendor, files, refs}` plus the verbatim `<peaks-auto-compact>` marker. The forbidden marker `@@@ORCHESTRATOR_SESSION_HISTORY_BOUNDARY@@@` MUST NOT appear in any prompt (unit-tested; regression fails vitest).
+- **G8 infinite context**: the child LLM self-monitors context; on ≥0.85 it compacts and writes `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json`; on ≥0.95 it writes `status.json` note `'compact-emergency'`. peaks runtime does NOT throttle on token cost — user authorized unlimited spend for G8 (recorded as `tokenUsage` on the dispatch record for audit visibility only).
+- **Lifecycle closure invariant**: `pid` / `log.txt` / `status.json` / `owner-session` 100% cleaned on every exit path (success / crash / OOM / SIGTERM). `peaks sub-agent cleanup --orphan` is the only orphan-killing path (RL-15: user-only decision; default is "do nothing").
+- **Resource budget guard**: `ResourceBudgetGuard` enforces `runtime RSS ≤ 200MB / idle CPU ≤ 5% / fan-out ≤ 8 (default)`. `--no-throttle` bypasses (user accepts risk; adds warning to envelope). `--max-concurrent <N>` overrides the 8 default.
+- **Vendor-neutral**: `VendorAdapterRegistry` registers `ClaudeAdapter` (Phase A) / `CodexAdapter` + `CopilotAdapter` (Phase B). Missing vendor CLI → fallback to default with `dispatchRecord.warning = 'vendor fallback: <id>→claude'`.
+- **Orchestrator prose obligation (G11.5)**: before each detached dispatch, emit `⏳ Spawning detached sub-agent via <vendor>: rid=<rid> (ETA ~60s)`. Envelope field `data.orchestratorVisibleHint` carries the same string for tooling.
+
+Default mode remains `in-process` (backward compat). The dispatch CLI accepts `--mode in-process|detached`; existing 106+ tests dispatching without `--mode` continue to use the in-process IDE-internal Task path.