peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/24h-mode/decider.js

@@ -0,0 +1,144 @@
+/**
+ * 24h mode B3 trigger evaluation + attempts counter.
+ *
+ * Rid-020a (state-only slice). `fireB3` is the single mutating
+ * primitive: it increments the per-key counter and escalates with a
+ * `B3Escalation` when the count reaches `B3_THRESHOLD` (3). The
+ * counter is **per-key** — AC-T3 mandates B1 and B2 retries do not
+ * share a global counter. The T3/T4 auto-24H_ACTIVE path is encoded
+ * in `isAutoEngageTrigger` (BRAINSTORM is bypassed for these
+ * triggers so an offline-resumed session does not deadlock in
+ * WAITING_USER — proposal §1 T3/T4 exception).
+ */
+import { B3_THRESHOLD, isDecisionKey } from './state.js';
+import { read24hState } from './store.js';
+export const B3_TRIGGER_REASONS = [
+    'prd_direction_change',
+    'blocker_3_consecutive_slices',
+    'registry_affecting_failure',
+    'destructive_irreversible_op',
+    'any_B1_B2_failure_3x_non_converging',
+    'runtime_or_shared_version_mismatch',
+    'sub-agent_stale_5min_x3'
+];
+export class B3Escalation extends Error {
+    reason;
+    attempts;
+    constructor(reason, attempts) {
+        super(`B3 escalation: reason=${reason}, attempts=${attempts}`);
+        this.name = 'B3Escalation';
+        this.reason = reason;
+        this.attempts = attempts;
+    }
+}
+export function isB3Reason(value) {
+    return B3_TRIGGER_REASONS.includes(value);
+}
+export function isValidReason(value) {
+    return isDecisionKey(value);
+}
+export function freshAttempts() {
+    const out = {};
+    for (const key of B3_TRIGGER_REASONS)
+        out[key] = 0;
+    return out;
+}
+/**
+ * Per AC-T1 (attempts=1 continue, no B3) and AC-T2 (attempts=3
+ * escalate), the 3rd call escalates. The threshold is intentionally
+ * NOT configurable — the proposal pins the constant so QA v3 can
+ * assert it. Returns a FireB3Result instead of throwing so test
+ * code can read the `attempts` field via plain property access
+ * (Error-subclass property access through vitest 4.1.10 matchers
+ * is unreliable; the discriminated union sidesteps that).
+ */
+export function fireB3(reason, attempts) {
+    const cur = attempts[reason] ?? 0;
+    const next = cur + 1;
+    attempts[reason] = next;
+    if (next >= B3_THRESHOLD) {
+        return { kind: 'escalate', reason, attempts: next };
+    }
+    return { kind: 'continue', reason, attempts: next };
+}
+/**
+ * T3 (runaway recovery) and T4 (offline resume) auto-engage
+ * `24H_ACTIVE` without forcing `USER_CONFIRM` — the deferred
+ * AskUserQuestion fires at the first 10min checkpoint instead, so
+ * a T4 session does not deadlock in `WAITING_USER` while the
+ * user is offline (proposal §1 T3/T4 exception).
+ */
+export const AUTO_ENGAGE_TRIGGERS = ['T3', 'T4'];
+export function isAutoEngageTrigger(t) {
+    return AUTO_ENGAGE_TRIGGERS.includes(t);
+}
+export const T1_KEYWORDS = ['24h', '通宵跑', '通宵', '夜跑', '夜机', '不计成本', '不停机'];
+export const T2_MIN_SLICES = 30;
+export const T2_MIN_WALL_HOURS = 6;
+export const T3_MIN_MONOTONIC_GUARDS = 3;
+export const T3_MIN_REMAINING_SLICES = 10;
+export const T4_SESSION_GAP_HOURS = 4;
+export const T5_MIN_ACTIVE_SLICES = 3;
+export function checkTriggers(input) {
+    if (T1_KEYWORDS.some((kw) => input.userMessage.includes(kw))) {
+        return { triggered: true, trigger: 'T1', reason: `T1 keyword match in user message` };
+    }
+    if (input.sliceListSize >= T2_MIN_SLICES || input.estimatedWallHours >= T2_MIN_WALL_HOURS) {
+        return {
+            triggered: true,
+            trigger: 'T2',
+            reason: `T2 scale: sliceList=${input.sliceListSize} OR wallHours=${input.estimatedWallHours}`
+        };
+    }
+    if (input.monotonicGuards >= T3_MIN_MONOTONIC_GUARDS &&
+        input.remainingSlices >= T3_MIN_REMAINING_SLICES) {
+        return {
+            triggered: true,
+            trigger: 'T3',
+            reason: `T3 runaway recovery: monotonicGuards=${input.monotonicGuards} remaining=${input.remainingSlices}`
+        };
+    }
+    if (input.sessionGapHours >= T4_SESSION_GAP_HOURS && input.remainingSlices > 0) {
+        return {
+            triggered: true,
+            trigger: 'T4',
+            reason: `T4 offline resume: gapHours=${input.sessionGapHours} remaining=${input.remainingSlices}`
+        };
+    }
+    if (input.activeSlicesAcrossServices >= T5_MIN_ACTIVE_SLICES) {
+        return {
+            triggered: true,
+            trigger: 'T5',
+            reason: `T5 multi-business: activeAcrossServices=${input.activeSlicesAcrossServices}`
+        };
+    }
+    return { triggered: false, trigger: null, reason: 'no trigger' };
+}
+/**
+ * HANDOFF is reachable via three exit conditions per proposal §1:
+ *   - user abort
+ *   - all-trigger-resolved
+ *   - B3 unresolvable (B3Escalation that the user dismisses)
+ */
+export const HANDOFF_EXIT_CONDITIONS = ['user_abort', 'all_triggers_resolved', 'b3_unresolvable'];
+export function isHandoffExitCondition(s) {
+    return HANDOFF_EXIT_CONDITIONS.includes(s);
+}
+export function isHandoffState(s) {
+    return s === 'HANDOFF';
+}
+/**
+ * Slice 2026-07-28 (rid-027): resolve the auto-compact mode from
+ * 24h-mode awareness. Returns `'partial'` when the session is
+ * `24H_ACTIVE`, otherwise `'standard'`. This is the CLI-side default;
+ * the explicit `--mode` flag in `peaks compact auto` overrides it.
+ */
+export function getAutoCompactMode(projectRoot, sessionId) {
+    try {
+        const snap = read24hState(projectRoot, sessionId);
+        return snap.state === '24H_ACTIVE' ? 'partial' : 'standard';
+    }
+    catch {
+        return 'standard';
+    }
+}

package/dist/services/24h-mode/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public barrel for 24h-mode service module.
+ *
+ * Rid-020a (state-only slice). Exports the 6-state enum, the
+ * DecisionKey enum, the persistence API, and the B3 decider API
+ * so that the `peaks session 24h-mode` CLI (and future rid-020b
+ * `peaks code run --24h`) can consume them without reaching into
+ * the internal file layout.
+ */
+export { B3_THRESHOLD, DECISION_KEYS, STATES, emptyAttempts, isDecisionKey, isState, type DecisionKey, type State, type State24hSnapshot } from './state.js';
+export { STATE_STORE_CONSTANTS, emptySnapshot, read24hState, write24hState } from './store.js';
+export { AUTO_ENGAGE_TRIGGERS, B3_TRIGGER_REASONS, B3Escalation, HANDOFF_EXIT_CONDITIONS, T1_KEYWORDS, T2_MIN_SLICES, T2_MIN_WALL_HOURS, T3_MIN_MONOTONIC_GUARDS, T3_MIN_REMAINING_SLICES, T4_SESSION_GAP_HOURS, T5_MIN_ACTIVE_SLICES, checkTriggers, fireB3, freshAttempts, isAutoEngageTrigger, isB3Reason, isHandoffExitCondition, isHandoffState, isValidReason, type AttemptsMap, type AutoEngageTrigger, type B3Reason, type FireB3Result, type HandoffExitCondition, type TriggerCheck } from './decider.js';

package/dist/services/24h-mode/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public barrel for 24h-mode service module.
+ *
+ * Rid-020a (state-only slice). Exports the 6-state enum, the
+ * DecisionKey enum, the persistence API, and the B3 decider API
+ * so that the `peaks session 24h-mode` CLI (and future rid-020b
+ * `peaks code run --24h`) can consume them without reaching into
+ * the internal file layout.
+ */
+export { B3_THRESHOLD, DECISION_KEYS, STATES, emptyAttempts, isDecisionKey, isState } from './state.js';
+export { STATE_STORE_CONSTANTS, emptySnapshot, read24hState, write24hState } from './store.js';
+export { AUTO_ENGAGE_TRIGGERS, B3_TRIGGER_REASONS, B3Escalation, HANDOFF_EXIT_CONDITIONS, T1_KEYWORDS, T2_MIN_SLICES, T2_MIN_WALL_HOURS, T3_MIN_MONOTONIC_GUARDS, T3_MIN_REMAINING_SLICES, T4_SESSION_GAP_HOURS, T5_MIN_ACTIVE_SLICES, checkTriggers, fireB3, freshAttempts, isAutoEngageTrigger, isB3Reason, isHandoffExitCondition, isHandoffState, isValidReason } from './decider.js';

package/dist/services/24h-mode/state.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 24h mode state machine — state types + DecisionKey enum.
+ *
+ * Rid-020a (state-only slice). The proposal defines six states that
+ * capture the lifecycle of a 24h code run; the DecisionKey enum is the
+ * enumeration of B1/B2 decision keys whose retry counter lives in
+ * `AttemptsMap`. Persistence and trigger evaluation live in sibling
+ * files; this module is pure data so the persistence tests can
+ * round-trip without pulling in IO and the decider tests can be
+ * exercised on an in-memory map.
+ */
+export declare const STATES: readonly ["IDLE", "BRAINSTORM", "USER_CONFIRM", "24H_ACTIVE", "WAITING_USER", "HANDOFF"];
+export type State = (typeof STATES)[number];
+/**
+ * Reasons recorded in the persisted `attempts` map. Mirrors the
+ * 7 B3 trigger rows in the v2 proposal §1 (B3 trigger table) plus
+ * generic B1/B2 retry keys (per-key independence in AC-T3).
+ */
+export declare const DECISION_KEYS: readonly ["prd_direction_change", "blocker_3_consecutive_slices", "registry_affecting_failure", "destructive_irreversible_op", "any_B1_B2_failure_3x_non_converging", "runtime_or_shared_version_mismatch", "sub-agent_stale_5min_x3"];
+export type DecisionKey = (typeof DECISION_KEYS)[number];
+/**
+ * B3 trigger threshold: per decision key, the 3rd consecutive fire
+ * escalates. Lower thresholds are not configurable here — proposal
+ * pins the constant so QA v3 can verify.
+ */
+export declare const B3_THRESHOLD = 3;
+/**
+ * The persisted shape for `.peaks/_runtime/<sessionId>/24h-state.json`.
+ * `enteredAt` is the ISO timestamp of the most recent state
+ * transition; `enteredFrom` is the previous state (or `null` for the
+ * IDLE bootstrap). `attempts` is keyed by `DecisionKey` and
+ * monotonically incremented by `fireB3`.
+ */
+export interface State24hSnapshot {
+    state: State;
+    enteredAt: string;
+    enteredFrom: State | null;
+    activeSlices: string[];
+    monotonicGuards: number;
+    autoCompactCount: number;
+    checkpoints: number;
+    lastCheckpointAt: string | null;
+    attempts: Record<DecisionKey, number>;
+    exitCondition: string | null;
+}
+export declare function isState(value: string): value is State;
+export declare function isDecisionKey(value: string): value is DecisionKey;
+export declare function emptyAttempts(): Record<DecisionKey, number>;

package/dist/services/24h-mode/state.js

@@ -0,0 +1,51 @@
+/**
+ * 24h mode state machine — state types + DecisionKey enum.
+ *
+ * Rid-020a (state-only slice). The proposal defines six states that
+ * capture the lifecycle of a 24h code run; the DecisionKey enum is the
+ * enumeration of B1/B2 decision keys whose retry counter lives in
+ * `AttemptsMap`. Persistence and trigger evaluation live in sibling
+ * files; this module is pure data so the persistence tests can
+ * round-trip without pulling in IO and the decider tests can be
+ * exercised on an in-memory map.
+ */
+export const STATES = [
+    'IDLE',
+    'BRAINSTORM',
+    'USER_CONFIRM',
+    '24H_ACTIVE',
+    'WAITING_USER',
+    'HANDOFF'
+];
+/**
+ * Reasons recorded in the persisted `attempts` map. Mirrors the
+ * 7 B3 trigger rows in the v2 proposal §1 (B3 trigger table) plus
+ * generic B1/B2 retry keys (per-key independence in AC-T3).
+ */
+export const DECISION_KEYS = [
+    'prd_direction_change',
+    'blocker_3_consecutive_slices',
+    'registry_affecting_failure',
+    'destructive_irreversible_op',
+    'any_B1_B2_failure_3x_non_converging',
+    'runtime_or_shared_version_mismatch',
+    'sub-agent_stale_5min_x3'
+];
+/**
+ * B3 trigger threshold: per decision key, the 3rd consecutive fire
+ * escalates. Lower thresholds are not configurable here — proposal
+ * pins the constant so QA v3 can verify.
+ */
+export const B3_THRESHOLD = 3;
+export function isState(value) {
+    return STATES.includes(value);
+}
+export function isDecisionKey(value) {
+    return DECISION_KEYS.includes(value);
+}
+export function emptyAttempts() {
+    const out = {};
+    for (const key of DECISION_KEYS)
+        out[key] = 0;
+    return out;
+}

package/dist/services/24h-mode/store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 24h mode persistence — atomic JSON snapshot under
+ * `.peaks/_runtime/<sessionId>/24h-state.json`.
+ *
+ * Rid-020a (state-only slice). The store never invents a session id:
+ * the caller passes one (the CLI resolves it from `.peaks/_runtime/session.json`).
+ * Writes use the temp-file + rename pattern so a crash mid-write never
+ * leaves a half-written state file (atomic on POSIX, near-atomic on
+ * Windows — same approach used by `session-checkpoint-service.ts`).
+ */
+import { type State24hSnapshot } from './state.js';
+export declare function emptySnapshot(now?: Date): State24hSnapshot;
+export declare function read24hState(projectRoot: string, sessionId: string): State24hSnapshot;
+/**
+ * Atomic write: temp file in the same directory, then rename. The
+ * rename is a single syscall on POSIX and a single MoveFile on
+ * Windows — a crash in between leaves the previous valid snapshot
+ * intact. `fsync` on the temp file is omitted (we accept the
+ * same weaker contract that `session-checkpoint-service.ts` uses)
+ * because the state is reconstructible from the B3 attempt log.
+ */
+export declare function write24hState(projectRoot: string, sessionId: string, snapshot: State24hSnapshot): {
+    path: string;
+};
+export declare const STATE_STORE_CONSTANTS: {
+    readonly STATE_FILENAME: "24h-state.json";
+};

package/dist/services/24h-mode/store.js

@@ -0,0 +1,119 @@
+/**
+ * 24h mode persistence — atomic JSON snapshot under
+ * `.peaks/_runtime/<sessionId>/24h-state.json`.
+ *
+ * Rid-020a (state-only slice). The store never invents a session id:
+ * the caller passes one (the CLI resolves it from `.peaks/_runtime/session.json`).
+ * Writes use the temp-file + rename pattern so a crash mid-write never
+ * leaves a half-written state file (atomic on POSIX, near-atomic on
+ * Windows — same approach used by `session-checkpoint-service.ts`).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { emptyAttempts, isDecisionKey, isState } from './state.js';
+const STATE_FILENAME = '24h-state.json';
+function statePath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), STATE_FILENAME);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function coerceSnapshot(raw) {
+    if (!isPlainObject(raw)) {
+        throw new Error('24H_STATE_INVALID: root must be an object');
+    }
+    if (typeof raw['state'] !== 'string' || !isState(raw['state'])) {
+        throw new Error(`24H_STATE_INVALID: state must be one of IDLE|BRAINSTORM|USER_CONFIRM|24H_ACTIVE|WAITING_USER|HANDOFF (got ${JSON.stringify(raw['state'])})`);
+    }
+    if (typeof raw['enteredAt'] !== 'string') {
+        throw new Error('24H_STATE_INVALID: enteredAt must be an ISO string');
+    }
+    if (raw['enteredFrom'] !== null && (typeof raw['enteredFrom'] !== 'string' || !isState(raw['enteredFrom']))) {
+        throw new Error('24H_STATE_INVALID: enteredFrom must be a State or null');
+    }
+    if (!Array.isArray(raw['activeSlices']) || !raw['activeSlices'].every((s) => typeof s === 'string')) {
+        throw new Error('24H_STATE_INVALID: activeSlices must be string[]');
+    }
+    if (typeof raw['monotonicGuards'] !== 'number' || !Number.isInteger(raw['monotonicGuards'])) {
+        throw new Error('24H_STATE_INVALID: monotonicGuards must be a non-negative integer');
+    }
+    if (typeof raw['autoCompactCount'] !== 'number' || !Number.isInteger(raw['autoCompactCount'])) {
+        throw new Error('24H_STATE_INVALID: autoCompactCount must be a non-negative integer');
+    }
+    if (typeof raw['checkpoints'] !== 'number' || !Number.isInteger(raw['checkpoints'])) {
+        throw new Error('24H_STATE_INVALID: checkpoints must be a non-negative integer');
+    }
+    if (raw['lastCheckpointAt'] !== null && typeof raw['lastCheckpointAt'] !== 'string') {
+        throw new Error('24H_STATE_INVALID: lastCheckpointAt must be ISO string or null');
+    }
+    if (raw['exitCondition'] !== null && typeof raw['exitCondition'] !== 'string') {
+        throw new Error('24H_STATE_INVALID: exitCondition must be string or null');
+    }
+    const rawAttempts = raw['attempts'];
+    if (!isPlainObject(rawAttempts)) {
+        throw new Error('24H_STATE_INVALID: attempts must be an object');
+    }
+    const attempts = emptyAttempts();
+    for (const [k, v] of Object.entries(rawAttempts)) {
+        if (!isDecisionKey(k)) {
+            throw new Error(`24H_STATE_INVALID: attempts has unknown key ${k}`);
+        }
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+            throw new Error(`24H_STATE_INVALID: attempts.${k} must be a non-negative integer`);
+        }
+        attempts[k] = v;
+    }
+    return {
+        state: raw['state'],
+        enteredAt: raw['enteredAt'],
+        enteredFrom: raw['enteredFrom'],
+        activeSlices: raw['activeSlices'],
+        monotonicGuards: raw['monotonicGuards'],
+        autoCompactCount: raw['autoCompactCount'],
+        checkpoints: raw['checkpoints'],
+        lastCheckpointAt: raw['lastCheckpointAt'],
+        attempts,
+        exitCondition: raw['exitCondition']
+    };
+}
+export function emptySnapshot(now = new Date()) {
+    return {
+        state: 'IDLE',
+        enteredAt: now.toISOString(),
+        enteredFrom: null,
+        activeSlices: [],
+        monotonicGuards: 0,
+        autoCompactCount: 0,
+        checkpoints: 0,
+        lastCheckpointAt: null,
+        attempts: emptyAttempts(),
+        exitCondition: null
+    };
+}
+export function read24hState(projectRoot, sessionId) {
+    const path = statePath(projectRoot, sessionId);
+    if (!existsSync(path))
+        return emptySnapshot();
+    const raw = readFileSync(path, 'utf8');
+    return coerceSnapshot(JSON.parse(raw));
+}
+/**
+ * Atomic write: temp file in the same directory, then rename. The
+ * rename is a single syscall on POSIX and a single MoveFile on
+ * Windows — a crash in between leaves the previous valid snapshot
+ * intact. `fsync` on the temp file is omitted (we accept the
+ * same weaker contract that `session-checkpoint-service.ts` uses)
+ * because the state is reconstructible from the B3 attempt log.
+ */
+export function write24hState(projectRoot, sessionId, snapshot) {
+    const path = statePath(projectRoot, sessionId);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
+    renameSync(tmp, path);
+    return { path };
+}
+export const STATE_STORE_CONSTANTS = {
+    STATE_FILENAME
+};

package/dist/services/adapter/adapter-registry.d.ts

@@ -0,0 +1,48 @@
+import type { VendorAdapter } from '../runtime/vendor-adapter.js';
+/** Serializable adapter record (the on-disk shape). */
+export interface AdapterRecord {
+    readonly id: string;
+    readonly displayName: string;
+    /** Binary name or absolute path to invoke for compact. */
+    readonly binary: string;
+    /** Extra args appended after the compact verb. */
+    readonly args?: string[];
+}
+export interface PersistedAdapterRegistry {
+    readonly version: 1;
+    readonly adapters: AdapterRecord[];
+}
+export interface RegisterOptions {
+    /** Overwrite an existing record with the same id. Defaults to false
+     *  to prevent silent overwrites of user customizations. */
+    readonly force?: boolean;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export declare class AdapterRegistry {
+    private readonly records;
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record: AdapterRecord, opts?: RegisterOptions): {
+        record: AdapterRecord;
+        created: boolean;
+    };
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id: string): VendorAdapter | undefined;
+    /** List registered adapter records (serializable form). */
+    list(): AdapterRecord[];
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id: string): boolean;
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file: string): void;
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file: string): void;
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot: string): string;
+}

package/dist/services/adapter/adapter-registry.js

@@ -0,0 +1,186 @@
+/**
+ * Adapter registry — slice S2-a of RD-2.
+ *
+ * Persists user-registered vendor adapters to
+ * `.peaks/runtime/adapters.json` and resolves them by id. The
+ * registry is layered on top of `RuntimeService` (built-in adapters
+ * live there); a caller asks "do you have an adapter for id=X?" by
+ * first asking the registry, then falling back to built-ins. The
+ * runtime service itself does NOT consult the registry (kept
+ * decoupled so the registry can be swapped for a different
+ * persistence backend without touching runtime-service).
+ *
+ * Design notes:
+ *  - Persistence uses atomic write (write to tmp + rename) so a
+ *    crash mid-write does not corrupt the registry file.
+ *  - `register()` defaults to fail-if-exists to prevent silent
+ *    overwrites of user customizations; pass `force: true` to
+ *    overwrite (matches the CLI surface from PRD §4.4).
+ *  - VendorAdapter implementations are NOT directly serializable
+ *    (they hold closures over `home`, child_process handles, etc.).
+ *    Instead the registry persists a minimal JSON shape:
+ *    `{id, displayName, binary, args}` and reconstructs a
+ *    ProcessVendorAdapter wrapper on load. This keeps the JSON
+ *    file human-readable + diff-friendly.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** A registry-built adapter: wraps a persisted record + invokes the
+ *  recorded binary with the recorded args. Used so `peaks runtime
+ *  compact --via <id>` works against user-registered adapters without
+ *  peaks-loop needing to ship a vendor-specific implementation. */
+class ProcessVendorAdapter {
+    id;
+    displayName;
+    binary;
+    extraArgs;
+    constructor(record) {
+        this.id = record.id;
+        this.displayName = record.displayName;
+        this.binary = record.binary;
+        this.extraArgs = record.args ?? [];
+    }
+    async detect() {
+        // Heuristic: process-spawned adapters are always "detectable" once
+        // registered; their actual availability is checked at compact()
+        // time. This avoids probing every registered binary on every
+        // detect() call.
+        return true;
+    }
+    async compact(args = {}) {
+        const argv = [...this.extraArgs];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn(this.binary, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            proc.on('error', (err) => {
+                resolveRun({ exitCode: 127, stdout, stderr: stderr + (stderr.length > 0 ? '\n' : '') + err.message });
+            });
+            proc.on('close', (code) => {
+                resolveRun({ exitCode: code ?? 0, stdout, stderr });
+            });
+        });
+    }
+}
+/** Validate an adapter record. Used by register() to fail fast on
+ *  malformed CLI input. Returns an error message or undefined. */
+function validateRecord(record) {
+    if (record.id.length === 0)
+        return 'adapter id must be non-empty';
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(record.id)) {
+        return `adapter id "${record.id}" must match /^[a-z0-9][a-z0-9._-]*$/`;
+    }
+    if (record.displayName.length === 0)
+        return 'adapter displayName must be non-empty';
+    if (record.binary.length === 0)
+        return 'adapter binary must be non-empty';
+    if (record.binary.includes('/') || record.binary.includes('\\')) {
+        return `adapter binary "${record.binary}" must be a name, not a path`;
+    }
+    return undefined;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export class AdapterRegistry {
+    records = new Map();
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record, opts = {}) {
+        const validationError = validateRecord(record);
+        if (validationError !== undefined) {
+            throw new Error(`invalid adapter record: ${validationError}`);
+        }
+        const existed = this.records.has(record.id);
+        if (existed && opts.force !== true) {
+            return { record: this.records.get(record.id), created: false };
+        }
+        this.records.set(record.id, record);
+        return { record, created: !existed };
+    }
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id) {
+        const rec = this.records.get(id);
+        if (rec === undefined)
+            return undefined;
+        return new ProcessVendorAdapter(rec);
+    }
+    /** List registered adapter records (serializable form). */
+    list() {
+        return Array.from(this.records.values());
+    }
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id) {
+        return this.records.delete(id);
+    }
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file) {
+        const payload = {
+            version: 1,
+            adapters: this.list()
+        };
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp`;
+        writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+        renameSync(tmp, file);
+    }
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file) {
+        if (!existsSync(file))
+            return;
+        const raw = readFileSync(file, 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`adapter registry at ${file} is not valid JSON: ${err.message}`);
+        }
+        if (!isPersistedRegistry(parsed)) {
+            throw new Error(`adapter registry at ${file} has unexpected shape (expected version=1 + adapters[])`);
+        }
+        this.records.clear();
+        for (const rec of parsed.adapters) {
+            const validationError = validateRecord(rec);
+            if (validationError !== undefined) {
+                // Skip + continue — partial recovery is better than throwing on
+                // a single bad row. The CLI surfaces the count of skipped
+                // records via the load() return value below.
+                continue;
+            }
+            this.records.set(rec.id, rec);
+        }
+    }
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot) {
+        return join(projectRoot, '.peaks', 'runtime', 'adapters.json');
+    }
+}
+function isPersistedRegistry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v.version !== 1)
+        return false;
+    if (!Array.isArray(v.adapters))
+        return false;
+    return v.adapters.every((a) => {
+        if (typeof a !== 'object' || a === null)
+            return false;
+        const r = a;
+        return typeof r.id === 'string'
+            && typeof r.displayName === 'string'
+            && typeof r.binary === 'string'
+            && (r.args === undefined || (Array.isArray(r.args) && r.args.every((x) => typeof x === 'string')));
+    });
+}