peaks-loop 4.0.0-beta.5 → 4.0.0-beta.6

package/dist/src/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')));
+    });
+}

package/dist/src/services/polyrepo/polyrepo-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoDispatch, PolyrepoManifest } from './polyrepo-types.js';
+export interface DispatchOptions {
+    /** Manifest returned by scanPolyrepo (root + children list). */
+    readonly manifest: PolyrepoManifest;
+    /** Session id this dispatch belongs to. */
+    readonly sid: string;
+    /** Request id (used in the on-disk filename). */
+    readonly rid: string;
+    /** Target child ids. Empty = root-only dispatch. Unknown ids are
+     *  recorded as warnings in the result, NOT raised as errors. */
+    readonly targets: readonly string[];
+    /** Artifact body — the role + source path on the parent side. */
+    readonly artifact: PolyrepoDispatch['artifact'];
+}
+export interface ChildDispatchResult {
+    readonly childId: string;
+    readonly path: string;
+    readonly ok: boolean;
+    readonly error?: string;
+    /** Where the artifact was mirrored to (child-side path). */
+    readonly mirroredTo?: string;
+}
+export interface DispatchResult {
+    readonly dispatch: PolyrepoDispatch;
+    readonly perChild: ChildDispatchResult[];
+    readonly warnings: string[];
+}
+export declare function dispatchArtifact(opts: DispatchOptions): DispatchResult;
+/** Default location of the polyrepo manifest on disk. */
+export declare function manifestPath(root: string): string;
+/** Read a persisted manifest from disk. Returns null when missing. */
+export declare function readManifest(root: string): PolyrepoManifest | null;
+/** Write a manifest atomically. */
+export declare function writeManifest(root: string, manifest: PolyrepoManifest): void;

package/dist/src/services/polyrepo/polyrepo-dispatcher.js

@@ -0,0 +1,119 @@
+/**
+ * Polyrepo dispatcher — slice S2-b of RD-2.
+ *
+ * Takes a parent root + a list of target child ids + a PRD/RD/QA
+ * artifact, and mirrors the artifact into each target child's
+ * `.peaks/_runtime/<sid>/<role>/` directory. Mirroring is
+ * best-effort + atomic per child: a failure in one child does NOT
+ * block the others (the dispatcher collects per-child results and
+ * returns them all so the caller can surface partial successes).
+ *
+ * Design notes:
+ *  - Per the project's two-axis convention, the parent's reviewable
+ *    artifact lives under `.peaks/_runtime/<sid>/<role>/`, not as a
+ *    sibling of `.peaks/_runtime/`. We mirror the same shape into
+ *    each child (the child does NOT inherit the parent's session
+ *    id verbatim — it gets the same one, which is fine because the
+ *    sid is the project's binding, not the parent's transient
+ *    pid).
+ *  - The dispatcher does NOT spawn any vendor verb — vendor
+ *    neutrality is preserved. If a child has no peaks-loop binary
+ *    on PATH, the dispatcher writes the artifact to disk and notes
+ *    a `peaksInstalled: false` warning; the user / a future slice
+ *    can pick it up. Per PRD §5 mitigation for "child has no
+ *    peaks-loop installed".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Compute the child-side path where the artifact should be mirrored.
+ *  Mirrors the parent shape exactly: `.peaks/_runtime/<sid>/<role>/`. */
+function childArtifactPath(childRoot, sid, role, sourcePath) {
+    const filename = sourcePath.split(/[\\/]/).pop() ?? 'artifact.md';
+    return join(childRoot, '.peaks', '_runtime', sid, role, filename);
+}
+function ensureDirFor(file) {
+    mkdirSync(dirname(file), { recursive: true });
+}
+export function dispatchArtifact(opts) {
+    const warnings = [];
+    const perChild = [];
+    // Validate targets against the manifest.
+    const knownIds = new Set(opts.manifest.children.map((c) => c.id));
+    const validTargets = [];
+    for (const t of opts.targets) {
+        if (knownIds.has(t)) {
+            validTargets.push(t);
+        }
+        else {
+            warnings.push(`unknown target id "${t}" — ignored`);
+        }
+    }
+    // Read the source artifact body once (so we can mirror to N children).
+    let sourceBody;
+    try {
+        sourceBody = readFileSync(opts.artifact.path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`source artifact unreadable at ${opts.artifact.path}: ${err.message}`);
+    }
+    // Per-child write.
+    for (const targetId of validTargets) {
+        const child = opts.manifest.children.find((c) => c.id === targetId);
+        if (child === undefined)
+            continue; // already filtered above
+        const dest = childArtifactPath(child.path, opts.sid, opts.artifact.role, opts.artifact.path);
+        try {
+            ensureDirFor(dest);
+            writeFileSync(dest, sourceBody, 'utf8');
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: true,
+                mirroredTo: dest
+            });
+            if (!child.peaksInstalled) {
+                warnings.push(`child "${targetId}" has no peaks-loop install — artifact mirrored but not picked up by a running peaks process`);
+            }
+        }
+        catch (err) {
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: false,
+                error: err.message
+            });
+        }
+    }
+    const dispatch = {
+        rid: opts.rid,
+        sid: opts.sid,
+        root: opts.manifest.root,
+        targets: validTargets,
+        dispatchedAt: new Date().toISOString(),
+        artifact: opts.artifact
+    };
+    return { dispatch, perChild, warnings };
+}
+/** Default location of the polyrepo manifest on disk. */
+export function manifestPath(root) {
+    return join(root, '.peaks', 'polyrepo.json');
+}
+/** Read a persisted manifest from disk. Returns null when missing. */
+export function readManifest(root) {
+    const p = manifestPath(root);
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = readFileSync(p, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a manifest atomically. */
+export function writeManifest(root, manifest) {
+    const p = manifestPath(root);
+    ensureDirFor(p);
+    writeFileSync(p, JSON.stringify(manifest, null, 2), 'utf8');
+}

package/dist/src/services/polyrepo/polyrepo-scanner.d.ts

@@ -0,0 +1,9 @@
+import type { PolyrepoManifest } from './polyrepo-types.js';
+export interface ScanOptions {
+    /** Explicit list of child directory names (relative to root). When
+     *  provided, the scanner uses these instead of auto-discovery.
+     *  Matches the `peaks polyrepo init --children <dir1,dir2>` shape. */
+    readonly explicitChildren?: readonly string[];
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export declare function scanPolyrepo(root: string, opts?: ScanOptions): PolyrepoManifest;

package/dist/src/services/polyrepo/polyrepo-scanner.js

@@ -0,0 +1,94 @@
+/**
+ * Polyrepo scanner — slice S2-b of RD-2.
+ *
+ * Walks a parent directory looking for child git repos. A "child
+ * git repo" is defined as: a directory that contains a `.git`
+ * entry (file or directory — worktrees + submodules both qualify),
+ * is NOT the root itself, and sits at depth 1 from the root.
+ *
+ * Depth is intentionally bounded to 1 (per the PRD §4.3 model):
+ *   parent/
+ *     .peaks/
+ *     frontend/.git
+ *     backend/.git
+ * We do not recurse into nested monorepos in this slice — that is
+ * a future-slice concern.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+function isGitRoot(dir) {
+    // A `.git` directory (normal repo) OR a `.git` file (worktree +
+    // submodule pointer) both count. statSync follows the pointer for
+    // a `.git` file, so the existence check is the same.
+    return existsSync(join(dir, '.git'));
+}
+function childHasPeaks(dir) {
+    return existsSync(join(dir, '.peaks'));
+}
+/** Sanitize a candidate child id: lowercase, dash-joined, no
+ *  leading dots or dashes. Used when the dir name itself is the id
+ *  (the common case). */
+function sanitizeId(name) {
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export function scanPolyrepo(root, opts = {}) {
+    const absRoot = resolve(root);
+    if (!existsSync(absRoot)) {
+        throw new Error(`polyrepo root does not exist: ${absRoot}`);
+    }
+    const rootStat = statSync(absRoot);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`polyrepo root is not a directory: ${absRoot}`);
+    }
+    const children = [];
+    if (opts.explicitChildren !== undefined && opts.explicitChildren.length > 0) {
+        // Explicit mode: only consider the named subdirs. This matches
+        // `peaks polyrepo init --children ./frontend,./backend`.
+        for (const name of opts.explicitChildren) {
+            const childPath = resolve(absRoot, name);
+            if (!existsSync(childPath)) {
+                throw new Error(`polyrepo child directory does not exist: ${childPath}`);
+            }
+            const s = statSync(childPath);
+            if (!s.isDirectory()) {
+                throw new Error(`polyrepo child path is not a directory: ${childPath}`);
+            }
+            children.push({
+                id: sanitizeId(basename(childPath)),
+                path: childPath,
+                gitRoot: isGitRoot(childPath),
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    else {
+        // Auto-discovery mode: list immediate entries, filter to dirs with
+        // `.git`. This is intentionally narrow — see the file-level
+        // rationale at the top of this file.
+        const entries = readdirSync(absRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.'))
+                continue; // skip .git, .peaks, .vscode, etc.
+            const childPath = join(absRoot, entry.name);
+            if (!isGitRoot(childPath))
+                continue;
+            children.push({
+                id: sanitizeId(entry.name),
+                path: childPath,
+                gitRoot: true,
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    return {
+        version: 1,
+        root: absRoot,
+        detectedAt: new Date().toISOString(),
+        children
+    };
+}

package/dist/src/services/polyrepo/polyrepo-service.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoChild, PolyrepoManifest } from './polyrepo-types.js';
+export interface PolyrepoInitOptions {
+    readonly root: string;
+    readonly children?: readonly string[];
+}
+export interface PolyrepoInitResult {
+    readonly manifest: PolyrepoManifest;
+    readonly created: boolean;
+}
+export interface PolyrepoStatusResult {
+    readonly root: string;
+    readonly manifestExists: boolean;
+    readonly children: PolyrepoChild[];
+    readonly detectedAt: string | null;
+}
+export declare class PolyrepoService {
+    /** Run a scan and persist the manifest. Returns the manifest + a
+     *  `created` flag indicating whether a new manifest was written
+     *  (false = existing manifest was overwritten). */
+    init(opts: PolyrepoInitOptions): PolyrepoInitResult;
+    /** Read the persisted manifest + report children. */
+    status(root: string): PolyrepoStatusResult;
+    /** Dispatch an artifact to the named child targets. Wrapper
+     *  around dispatchArtifact that resolves the manifest from disk
+     *  first. Throws when no manifest exists (caller should run init
+     *  first). */
+    dispatch(root: string, params: {
+        sid: string;
+        rid: string;
+        targets: readonly string[];
+        role: 'prd' | 'rd' | 'qa';
+        artifactPath: string;
+    }): import("./polyrepo-dispatcher.js").DispatchResult;
+}

package/dist/src/services/polyrepo/polyrepo-service.js

@@ -0,0 +1,49 @@
+/**
+ * Polyrepo service — slice S2-b of RD-2.
+ *
+ * Thin orchestrator wrapping the scanner + dispatcher. CLI commands
+ * call into this service so they don't need to know about the
+ * individual helpers.
+ */
+import { dispatchArtifact, readManifest, writeManifest, manifestPath } from './polyrepo-dispatcher.js';
+import { scanPolyrepo } from './polyrepo-scanner.js';
+export class PolyrepoService {
+    /** Run a scan and persist the manifest. Returns the manifest + a
+     *  `created` flag indicating whether a new manifest was written
+     *  (false = existing manifest was overwritten). */
+    init(opts) {
+        const existing = readManifest(opts.root);
+        const manifest = opts.children === undefined
+            ? scanPolyrepo(opts.root)
+            : scanPolyrepo(opts.root, { explicitChildren: opts.children });
+        writeManifest(opts.root, manifest);
+        return { manifest, created: existing === null };
+    }
+    /** Read the persisted manifest + report children. */
+    status(root) {
+        const m = readManifest(root);
+        return {
+            root,
+            manifestExists: m !== null,
+            children: m?.children ?? [],
+            detectedAt: m?.detectedAt ?? null
+        };
+    }
+    /** Dispatch an artifact to the named child targets. Wrapper
+     *  around dispatchArtifact that resolves the manifest from disk
+     *  first. Throws when no manifest exists (caller should run init
+     *  first). */
+    dispatch(root, params) {
+        const manifest = readManifest(root);
+        if (manifest === null) {
+            throw new Error(`no polyrepo manifest at ${manifestPath(root)} — run \`peaks polyrepo init\` first`);
+        }
+        return dispatchArtifact({
+            manifest,
+            sid: params.sid,
+            rid: params.rid,
+            targets: params.targets,
+            artifact: { role: params.role, path: params.artifactPath }
+        });
+    }
+}

package/dist/src/services/polyrepo/polyrepo-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Polyrepo types — slice S2-b of RD-2.
+ *
+ * Models a parent directory that hosts one or more child git repos,
+ * each of which may carry its own `.peaks/` state. The root `.peaks/`
+ * is the source of truth for cross-child orchestration; child
+ * `.peaks/` are subsets that mirror only the artifacts the child
+ * needs (PRD §4.3).
+ */
+export type PeaksScope = 'root+child' | 'child-only';
+/** A single child repo discovered under the parent root. */
+export interface PolyrepoChild {
+    /** Stable id derived from the basename (e.g. `frontend`, `backend`). */
+    readonly id: string;
+    /** Absolute path to the child directory. */
+    readonly path: string;
+    /** Whether `.git` exists at the child root (true git repo, not just a subdir). */
+    readonly gitRoot: boolean;
+    /** Whether the child carries its own `.peaks/` artifact subset. */
+    readonly peaksScope: PeaksScope;
+    /** Whether the child has peaks-loop installed (peaks binary on PATH
+     *  is NOT checked here — that's done at dispatch time). */
+    readonly peaksInstalled: boolean;
+}
+/** The polyrepo manifest, written to `.peaks/polyrepo.json` on init. */
+export interface PolyrepoManifest {
+    /** Schema version — increment on breaking changes. */
+    readonly version: 1;
+    /** Absolute path to the parent (root) directory. */
+    readonly root: string;
+    /** ISO-8601 timestamp of when this manifest was generated. */
+    readonly detectedAt: string;
+    /** Children discovered under the root. */
+    readonly children: PolyrepoChild[];
+}
+/** A dispatch record — written to `.peaks/_runtime/<sid>/sc/dispatch/<rid>.json`
+ *  AND mirrored to each target child's
+ *  `.peaks/_runtime/<sid>/sc/dispatch/<rid>.json`. The two-axis
+ *  convention from .peaks/standards/ is preserved: reviewable
+ *  artifacts live under `.peaks/_runtime/<sid>/<role>/`, never as
+ *  top-level siblings of `.peaks/_runtime/`. */
+export interface PolyrepoDispatch {
+    readonly rid: string;
+    readonly sid: string;
+    readonly root: string;
+    /** Child ids targeted by this dispatch. Empty array = root-only. */
+    readonly targets: string[];
+    /** ISO timestamp. */
+    readonly dispatchedAt: string;
+    /** Source-of-truth for the artifact body. */
+    readonly artifact: {
+        readonly role: 'prd' | 'rd' | 'qa';
+        readonly path: string;
+    };
+}

package/dist/src/services/polyrepo/polyrepo-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/runtime/runtime-detector.d.ts

@@ -0,0 +1,15 @@
+export type DetectedVendor = 'claude-code' | 'codex' | 'copilot' | 'unknown';
+export interface RuntimeDetectorOptions {
+    /** Override for env (used by tests). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override for home directory (used by tests). */
+    readonly home?: string;
+}
+export interface DetectionResult {
+    readonly vendor: DetectedVendor;
+    /** Why this vendor was chosen — useful for diagnostics and tests. */
+    readonly reason: string;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export declare function detectRuntime(opts?: RuntimeDetectorOptions): DetectionResult;

package/dist/src/services/runtime/runtime-detector.js

@@ -0,0 +1,62 @@
+/**
+ * Runtime detector — slice S2-a of RD-2.
+ *
+ * Given the current process environment, decide which vendor (if any)
+ * is the active AI runtime. Detection order matters: Claude Code is
+ * checked first because it is the default runtime for peaks-loop
+ * (the project literally runs inside Claude Code). Codex + Copilot
+ * are checked second; if none match we report `unknown`.
+ *
+ * Detectors MUST be cheap (no process spawn, no network). They look
+ * at env vars + filesystem sentinels + home-dir shapes only. This
+ * keeps `peaks runtime detect` sub-100ms even on cold paths.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Heuristic: Claude Code sets CLAUDE_CODE_ENTRYPOINT or has a
+ *  .claude/skills directory under HOME (peaks-loop installs there). */
+function detectClaudeCode(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CLAUDE_CODE === '1' || env.CLAUDE_CODE === 'true')
+        return true;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined && env.CLAUDE_CODE_ENTRYPOINT.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.claude')))
+        return true;
+    return false;
+}
+/** Heuristic: Codex sets CODEX_HOME or has a .codex dir under HOME. */
+function detectCodex(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CODEX_HOME !== undefined && env.CODEX_HOME.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.codex')))
+        return true;
+    return false;
+}
+/** Heuristic: Copilot sets GITHUB_COPILOT or has a .copilot dir. */
+function detectCopilot(opts) {
+    const env = opts.env ?? process.env;
+    if (env.GITHUB_COPILOT === '1' || env.GITHUB_COPILOT === 'true')
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.copilot')))
+        return true;
+    return false;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export function detectRuntime(opts = {}) {
+    if (detectClaudeCode(opts)) {
+        return { vendor: 'claude-code', reason: 'CLAUDE_CODE_ENTRYPOINT / CLAUDE_CODE / ~/.claude matched' };
+    }
+    if (detectCodex(opts)) {
+        return { vendor: 'codex', reason: 'CODEX_HOME / ~/.codex matched' };
+    }
+    if (detectCopilot(opts)) {
+        return { vendor: 'copilot', reason: 'GITHUB_COPILOT / ~/.copilot matched' };
+    }
+    return { vendor: 'unknown', reason: 'no vendor sentinel detected' };
+}