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

package/dist/src/services/ide/adapters/zcode-adapter.js

@@ -0,0 +1,220 @@
+/**
+ * z-code IDE adapter (slice 2026-07-09-add-zcode-adapter) — peaks-loop 的第九个
+ * 内置 IDE 适配器。
+ *
+ * z-code 是一个 VS Code-style 的 Anthropic-compatible 桌面应用:
+ *   - 不是 CLI,没有 `zcode` binary (`which zcode` 返回空)。
+ *   - 桌面应用内置了 "导入 skills" 功能,user 手动触发后将本地 skills 目录
+ *     与 `~/.zcode/skills` 双向同步 (实测 symlink)。
+ *   - hook 协议、project-dir env var、compact command 均未公开。
+ *
+ * 设计前提 (RD-3 §2.2 D1 决策 + 现场实测,见
+ * `.peaks/memory/2026-07-09-zcode-context-probe-handoff.md` §2):
+ *   - `compact` 字段全部 undefined — 走 `llm-self-compress` fallback 路径。
+ *   - `envVar` / `hookEvent` / `toolMatcher` 全部标注 UNVERIFIED,因为
+ *     z-code 文档未公开,本 adapter 用 Anthropic-compatible 协议的合理
+ *     假设占位。
+ *   - `subAgentDispatcher` 用 `nullSubAgentDispatcher` 占位 — z-code
+ *     桌面应用没有公开的 Task 工具 dispatch 协议。
+ *   - `standardsProfile` 字段指向宪法文件根 + rules 目录 — z-code 的设计
+ *     就是借用上游 "import skills" 目标目录,因此保留上游路径常量。
+ *   - `skillInstall` 指向 `~/.zcode/skills` — 实测 z-code 已通过 user
+ *     手动导入同步到这里。
+ *   - 注:`standardsProfile` 中的常量子段是 z-code 借用的固定路径,属于
+ *     架构事实,不算 vendor verb 泄漏。
+ *
+ * Vendor-neutrality 备注 (SC-3 §5 + RD-3 §2.4):
+ *   本文件允许出现 vendor 字符串 (`zcode` / `ZCODE_PROJECT_DIR` 等),
+ *   **不允许** 出现其他 vendor 字符串 / 模型名。`standardsProfile`
+ *   中的 `CLAUDE.md` / `.claude/rules` 是 z-code 借用的上游路径常量,
+ *   属于架构事实,不算 vendor verb 泄漏。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { nullSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Helper exported for tests + internal use: the default location of the
+ * z-code v2 config file on the host filesystem.
+ */
+export function defaultZcodeConfigPath() {
+    return join(homedir(), '.zcode', 'v2', 'config.json');
+}
+/**
+ * Read the z-code config from `path` (string-typed to keep this
+ * swappable for tests). Synchronous + Node.js `fs` so adapter callers
+ * stay async-only at the public surface (`detectCurrentModel` is
+ * already declared `async`).
+ */
+function readZcodeConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the active model id from a parsed z-code config payload
+ * (the `~/.zcode/v2/config.json` root object). Pure / exported for
+ * unit tests so the file-IO seam and the resolution seam are
+ * independently verifiable.
+ *
+ * Resolution order (Slice C §"z-code config 解析路径"):
+ *   P1. env var `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` (test seam +
+ *       manual pin for the user).
+ *   P2. The provider whose top-level UUID key is NOT prefixed
+ *       `builtin:` — this matches the user-installed provider
+ *       pattern. Within that provider, prefer its `models` first
+ *       key (insertion order — z-code writes the active model
+ *       first in the picker).
+ *   P3. The first provider with `enabled: true`.
+ *   P4. The first provider in the object (insertion order) — last
+ *       resort. Returns undefined if there are zero providers.
+ *
+ * Returns `undefined` when nothing matches.
+ */
+export function resolveZcodeCurrentModel(config, envOverride) {
+    const providers = config?.provider;
+    if (!providers || typeof providers !== 'object')
+        return undefined;
+    // P1: env var override (vendor-neutral identifier: the provider UUID).
+    if (envOverride !== undefined && envOverride !== '') {
+        const target = providers[envOverride];
+        if (target && typeof target === 'object') {
+            const modelId = pickFirstModelId(target);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P2: prefer a non-builtin provider (the user-installed one).
+    for (const [uuid, entry] of Object.entries(providers)) {
+        if (uuid.startsWith('builtin:'))
+            continue;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    // P3: first enabled provider (legacy / fresh-install case).
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const enabled = entry.enabled;
+        if (enabled === true) {
+            const modelId = pickFirstModelId(entry);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P4: first provider at all.
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    return undefined;
+}
+function pickFirstModelId(provider) {
+    const models = provider.models;
+    if (!models || typeof models !== 'object')
+        return undefined;
+    for (const key of Object.keys(models)) {
+        if (typeof key === 'string' && key.trim().length > 0)
+            return key.trim();
+    }
+    return undefined;
+}
+/**
+ * The async adapter method that `detectCurrentIdeModel()` calls.
+ *
+ * Resolution order:
+ *   1. `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` env var override (test seam
+ *      + manual pin).
+ *   2. `PEAKS_ZCODE_CONFIG_PATH` env var override (test seam for a
+ *      fixture file). Falls back to `~/.zcode/v2/config.json`.
+ *   3. Returns `undefined` when the file is missing / malformed
+ *      (consistent with the cross-IDE contract).
+ */
+export async function detectZcodeCurrentModel() {
+    const overridePath = process.env.PEAKS_ZCODE_CONFIG_PATH;
+    const path = overridePath && overridePath.length > 0 ? overridePath : defaultZcodeConfigPath();
+    const config = readZcodeConfig(path);
+    if (config === undefined)
+        return undefined;
+    return resolveZcodeCurrentModel(config, process.env.PEAKS_ZCODE_ACTIVE_PROVIDER_UUID);
+}
+export const ZCODE_ADAPTER = {
+    id: 'zcode',
+    displayName: 'z-code',
+    settings: {
+        dirName: '.zcode', // VERIFIED — 实测 z-code 项目根目录是 `.zcode`
+        settingsFileName: 'settings.json',
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.zcode', 'settings.json');
+        },
+        supportsScope: (scope) => scope === 'project' || scope === 'global',
+    },
+    // UNVERIFIED — z-code 桌面应用未公开 `ZCODE_PROJECT_DIR` env var,这里
+    // 用占位符,RD 阶段假设 z-code 借用了 Anthropic-compatible 协议并可能
+    // 注入一个项目根 env 变量。若未注入,峰 router 会回退到 cwd 探测。
+    envVar: 'ZCODE_PROJECT_DIR',
+    // UNVERIFIED — z-code 未公开 hook event key,占位用 Anthropic-compatible
+    // 协议的常见命名 `PreToolUse`。若 z-code 用其他 key,peaks hooks install
+    // 钩子在此 IDE 上不生效,可由 user 通过手动导入绕过。
+    hookEvent: 'PreToolUse',
+    // UNVERIFIED — 同上,占位用 `Bash` matcher。
+    toolMatcher: 'Bash',
+    // Slice 2026-07-09: z-code 桌面应用没有公开 Task 工具 dispatch 协议,
+    // 用 `nullSubAgentDispatcher` 占位 — peaks sub-agent dispatch CLI 在
+    // z-code 上返回 SubAgentNotSupportedError,符合 slice #008 P-5 capability
+    // 检查契约 (CLI 不崩溃)。
+    subAgentDispatcher: nullSubAgentDispatcher,
+    // Slice #010 G9: 假设 z-code 支持 PreToolUse (UNVERIFIED)。Opt-in,等真实
+    // z-code 安装 dogfood 后再决定。若 z-code 不支持 G9 hook,CLI 兜底层仍会
+    // 强制执行 G9 阈值。
+    promptSizeAware: true,
+    installHints: [
+        'z-code 没有 CLI,因此无需重启 — skills symlink 已写入 ~/.zcode/skills/。',
+        '若 z-code 未自动加载 peaks-* skills,在 z-code 桌面应用里手动触发 "导入 skills" 功能即可。',
+    ],
+    capabilities: {
+        gateEnforce: true,
+        statusline: true,
+    },
+    // Standards profile: 路径常量保留 (z-code 的 "导入 skills" 功能
+    // 借用了上游 settings 目录,因此宪法文件路径常量同步保留)。
+    standardsProfile: {
+        rootFile: 'CLAUDE.md',
+        rulesDir: '.claude/rules',
+        rulesFileGlob: '**/*.md',
+        autoLoaded: true,
+        format: 'markdown',
+        migrationHint: 'z-code 借用了上游 standards 路径,无需迁移。',
+    },
+    // Skill install profile: 指向 `~/.zcode/skills` 系列 (实测 z-code 已通过
+    // user 手动 symlink 同步;peaks-loop 也直接支持)。
+    skillInstall: {
+        skillsDir: join(homedir(), '.zcode', 'skills'),
+        outputStylesDir: join(homedir(), '.zcode', 'output-styles'),
+        installStrategy: 'symlink',
+        envVarOverride: 'PEAKS_ZCODE_SKILLS_DIR',
+    },
+    // compact profile 留空 — z-code 没有 CLI binary (RD-3 §2.2 D1 决策)。
+    // peaks-loop 走 `llm-self-compress` fallback 路径 (LLM 自己总结 context),
+    // 不抛错、不警告 (符合 slice #008 P-5 capability-check contract)。
+    // Slice C (2026-07-09 add-zcode-adapter, C.2): runtime probe for
+    // the currently-active model id. Reads `~/.zcode/v2/config.json`
+    // and resolves the active provider via `resolveZcodeCurrentModel`.
+    // See `.peaks/_runtime/2026-07-08-session-17918f/qa/.../slice-C-completion.md`
+    // for the resolution priority chain (env override → non-builtin
+    // provider → first enabled → first provider). Returns undefined
+    // on any failure (consistent with the cross-IDE contract).
+    detectCurrentModel: detectZcodeCurrentModel,
+};

package/dist/src/services/ide/current-model-detector.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export declare function detectCurrentIdeModel(): Promise<string | undefined>;

package/dist/src/services/ide/current-model-detector.js

@@ -0,0 +1,60 @@
+/**
+ * Runtime current-model detector (Slice 2026-07-09 add-zcode-adapter, Slice C).
+ *
+ * Walks the registered IDE adapter chain and asks the IDE adapter
+ * (when it opts in via `IdeAdapter.detectCurrentModel?`) to report the
+ * currently-active model id. This is the runtime sibling of
+ * `getStrongestModelId(config)` in `src/services/config/model-routing.ts`:
+ *
+ *   - `getStrongestModelId(config)` reads `config.model` (user-set) and
+ *     falls back to the env-var / `'claude-opus-4-7'` constant. Sync.
+ *   - `detectCurrentIdeModel()` reads the IDE's runtime state (which
+ *     provider UI is active, which model the picker shows). Async.
+ *
+ * The CLI surface `peaks ide model --current` (added in this slice)
+ * delegates here. The future async resolver at
+ * `getStrongestModelIdAsync` (Slice C §C.4) calls this so config-less
+ * runs (e.g. an LLM inside z-code) can derive the strongest model from
+ * its actual environment.
+ *
+ * Vendor-neutrality notes (SC-3 §5 + RD-3 §2.4):
+ *   - This file never names a vendor (no "claude", "zcode", etc.).
+ *   - It only walks `IdeAdapter.detectCurrentModel?` — any adapter
+ *     can opt in.
+ *   - It returns `undefined` when detection is unavailable; callers
+ *     must fall back to the configured / hardcoded model.
+ */
+import { getAdapter } from './ide-registry.js';
+import { listAdapterIds } from './ide-registry.js';
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export async function detectCurrentIdeModel() {
+    for (const id of listAdapterIds()) {
+        const adapter = getAdapter(id);
+        if (typeof adapter.detectCurrentModel !== 'function')
+            continue;
+        try {
+            const modelId = await adapter.detectCurrentModel();
+            if (typeof modelId === 'string' && modelId.trim().length > 0) {
+                return modelId.trim();
+            }
+        }
+        catch {
+            // Per-SC §3.4: detection is best-effort. Swallow errors so a
+            // misconfigured adapter cannot poison the chain; the next
+            // adapter still gets a chance.
+        }
+    }
+    return undefined;
+}

package/dist/src/services/ide/ide-registry.js

@@ -4,6 +4,7 @@ import { CURSOR_ADAPTER } from './adapters/cursor-adapter.js';
 import { CODEX_ADAPTER } from './adapters/codex-adapter.js';
 import { HERMES_ADAPTER } from './adapters/hermes-adapter.js';
 import { OPENCLAW_ADAPTER } from './adapters/openclaw-adapter.js';
+import { ZCODE_ADAPTER } from './adapters/zcode-adapter.js';
 /**
  * Built-in IDE adapter registry。Map<IdeId, IdeAdapter> 是单一来源。
  *
@@ -24,6 +25,7 @@ const ADAPTERS = new Map([
     ['codex', CODEX_ADAPTER],
     ['hermes', HERMES_ADAPTER],
     ['openclaw', OPENCLAW_ADAPTER],
+    ['zcode', ZCODE_ADAPTER],
 ]);
 /** Get the adapter for a given IDE id. Throws on unsupported IDE. */
 export function getAdapter(ide) {
@@ -57,4 +59,5 @@ export function _resetAdaptersForTesting() {
     ADAPTERS.set('codex', CODEX_ADAPTER);
     ADAPTERS.set('hermes', HERMES_ADAPTER);
     ADAPTERS.set('openclaw', OPENCLAW_ADAPTER);
+    ADAPTERS.set('zcode', ZCODE_ADAPTER);
 }

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

@@ -12,7 +12,7 @@
  * 其他全部归一化到 peaks 内部模型(见 hook-protocol.ts)。
  */
 import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
-export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw';
+export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw' | 'zcode';
 export interface IdeCapabilities {
     /** peaks gate enforce 是否适用该 IDE(必备) */
     readonly gateEnforce: true;
@@ -125,6 +125,29 @@ export interface IdeAdapter {
      * `.peaks/memory/2026-06-27-auto-compact-design.md`.
      */
     readonly compact?: IdeCompactProfile;
+    /**
+     * Optional runtime probe for the IDE's currently-active model id.
+     * When defined, `detectCurrentIdeModel()` in
+     * `src/services/ide/current-model-detector.ts` calls this to
+     * discover which model the IDE UI is currently configured for —
+     * e.g. so `peaks ide model --current` and the future
+     * `getStrongestModelIdAsync()` can use the same value without
+     * forcing the user to set `config.model` manually.
+     *
+     * Returning `undefined` (or the method being absent on this
+     * adapter) means "I don't know — fall back to the configured
+     * model / env var / back-compat default".
+     *
+     * Implementations may read local files (`fs.readFileSync`),
+     * env vars, or both. They MUST NOT throw on missing files — catch
+     * locally and return `undefined`. The orchestration layer also
+     * catches, but defense in depth.
+     *
+     * Added in slice 2026-07-09 add-zcode-adapter (Slice C); only the
+     * `zcode` adapter opts in this slice. Future slices can opt in
+     * other IDEs without changing this signature (optional method).
+     */
+    readonly detectCurrentModel?: () => Promise<string | undefined>;
 }
 /**
  * Per-IDE auto-compact capability descriptor. See `IdeAdapter.compact`

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;
+}