peaks-loop 4.0.54 → 4.1.1

package/dist/services/dispatch/slice-dag-types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Slice DAG type surface — moved VERBATIM out of `slice-dag.ts` for the
+ * 300-raw-line cap (slice `b1-filesplit-campaign`, wave 3C). No behavior
+ * lives here: node/edge model types, the complexity tier, and the two
+ * error classes, plus the wave-plan envelopes. `slice-dag.ts` re-exports
+ * every name from this module, so all existing import paths keep working.
+ */
+/**
+ * Slice complexity tier (v2.15.0 follow-up, G2 in 12 Gaps).
+ * Used by Code to schedule complex slices during user-attended hours
+ * and trivial / simple slices overnight.
+ */
+export type SliceComplexity = 'trivial' | 'simple' | 'complex';
+export declare const SLICE_COMPLEXITIES: readonly SliceComplexity[];
+export declare function isSliceComplexity(value: string): value is SliceComplexity;
+export interface SliceNode {
+    readonly id: string;
+    readonly role: string;
+    /** Human-readable label, optional. */
+    readonly label?: string;
+    /** Optional prompt override; dispatch falls back to a default placeholder. */
+    readonly prompt?: string;
+    /**
+     * v2.15.0 follow-up — G12: foundation slice. Foundation slices run before
+     * business slices in the layered DAG. Business slices do NOT wait for
+     * ALL foundation slices — they wait only for the foundation subset
+     * they declare as `dependsOn`. Optional; default false.
+     */
+    readonly foundation?: boolean;
+    /**
+     * v2.15.0 follow-up — G11: upstream sync slice. Marks a slice that
+     * syncs an upstream fork (e.g. hermes) to a new tag. UpstreamSync
+     * slices take priority within their topological level. Optional.
+     */
+    readonly upstreamSync?: boolean;
+    /**
+     * v2.15.0 follow-up — G2: complexity tier. Drives Code's scheduling
+     * (complex = user-attended, simple/trivial = overnight). Optional.
+     */
+    readonly complexity?: SliceComplexity;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §3: files this slice is
+     * expected to touch. When EVERY node of a topological level declares
+     * `files`, `--from-dag` emits a file-overlap wave plan (`firstLevelWaves`)
+     * so the LLM can fan the level out without serializing on a shared file.
+     * Optional and additive: absent → DAG hash and dispatch behavior are
+     * byte-identical to before this slice.
+     */
+    readonly files?: readonly string[];
+}
+export interface DependsOn {
+    readonly from: string;
+    readonly to: string;
+}
+export interface SliceDag {
+    readonly nodes: readonly SliceNode[];
+    readonly edges: readonly DependsOn[];
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export declare class InvalidSliceDagError extends Error {
+    readonly path?: readonly string[] | undefined;
+    readonly code: "INVALID_SLICE_DAG";
+    constructor(message: string, path?: readonly string[] | undefined);
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export declare class SliceDagCycleError extends Error {
+    readonly cyclePath: readonly string[];
+    readonly code: "SLICE_DAG_CYCLE";
+    constructor(cyclePath: readonly string[]);
+}
+/**
+ * Knobs for wave planning + artifact-pass behaviour.
+ *
+ * - `maxConcurrency`: hard cap on how many slices a single Wave can hold.
+ *   Each topological level is chunked into Waves of at most this many
+ *   slice IDs (default 6 per `2026-07-28-24h-loop-audit.md` E direction).
+ * - `passArtifacts`: when true, each Wave's prompt is augmented with a
+ *   `WaveArtifact` envelope (contracts of preceding Waves). Default
+ *   false — the existing `runDag` ancestor-injection path already covers
+ *   per-slice contract coverage.
+ */
+export interface WaveOptions {
+    readonly maxConcurrency: number;
+    readonly passArtifacts: boolean;
+}
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export declare const DEFAULT_MAX_CONCURRENCY = 6;
+export declare const DEFAULT_WAVE_OPTIONS: WaveOptions;
+/**
+ * Artifact envelope emitted when a Wave completes successfully.
+ *
+ * - `waveIndex`: sequential, 0-based across the whole plan.
+ * - `completedLeaves`: slice IDs that finished (`status: 'done'`). Failed
+ *    or cancelled leaves are NOT included.
+ * - `contracts`: per-slice public contract snapshot (sliceId → record).
+ *    Stored verbatim so a downstream Wave can re-inject this without
+ *    re-reading the disk-side contract store.
+ * - `passedAt`: ISO timestamp of Wave completion (caller-supplied to keep
+ *    the surface pure).
+ */
+export interface WaveArtifact {
+    readonly waveIndex: number;
+    readonly completedLeaves: readonly string[];
+    readonly contracts: Readonly<Record<string, unknown>>;
+    readonly passedAt: string;
+}
+/**
+ * A single dispatch Wave. Holds the slice IDs that must execute together,
+ * respecting `WaveOptions.maxConcurrency`. Waves are emitted in
+ * topological order; downstream consumers may treat `waveIndex` as a
+ * monotonic cursor.
+ */
+export interface Wave {
+    readonly waveIndex: number;
+    readonly slices: readonly string[];
+}

package/dist/services/dispatch/slice-dag-types.js

@@ -0,0 +1,41 @@
+/**
+ * Slice DAG type surface — moved VERBATIM out of `slice-dag.ts` for the
+ * 300-raw-line cap (slice `b1-filesplit-campaign`, wave 3C). No behavior
+ * lives here: node/edge model types, the complexity tier, and the two
+ * error classes, plus the wave-plan envelopes. `slice-dag.ts` re-exports
+ * every name from this module, so all existing import paths keep working.
+ */
+export const SLICE_COMPLEXITIES = [
+    'trivial',
+    'simple',
+    'complex'
+];
+export function isSliceComplexity(value) {
+    return SLICE_COMPLEXITIES.includes(value);
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export class InvalidSliceDagError extends Error {
+    path;
+    code = 'INVALID_SLICE_DAG';
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'InvalidSliceDagError';
+    }
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export class SliceDagCycleError extends Error {
+    cyclePath;
+    code = 'SLICE_DAG_CYCLE';
+    constructor(cyclePath) {
+        super(`cycle detected in slice DAG: ${cyclePath.join(' -> ')}`);
+        this.cyclePath = cyclePath;
+        this.name = 'SliceDagCycleError';
+    }
+}
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export const DEFAULT_MAX_CONCURRENCY = 6;
+export const DEFAULT_WAVE_OPTIONS = {
+    maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+    passArtifacts: false
+};

package/dist/services/dispatch/slice-dag.d.ts

@@ -1,66 +1,4 @@
-/**
- * Slice complexity tier (v2.15.0 follow-up, G2 in 12 Gaps).
- * Used by Code to schedule complex slices during user-attended hours
- * and trivial / simple slices overnight.
- */
-export type SliceComplexity = 'trivial' | 'simple' | 'complex';
-export declare const SLICE_COMPLEXITIES: readonly SliceComplexity[];
-export declare function isSliceComplexity(value: string): value is SliceComplexity;
-export interface SliceNode {
-    readonly id: string;
-    readonly role: string;
-    /** Human-readable label, optional. */
-    readonly label?: string;
-    /** Optional prompt override; dispatch falls back to a default placeholder. */
-    readonly prompt?: string;
-    /**
-     * v2.15.0 follow-up — G12: foundation slice. Foundation slices run before
-     * business slices in the layered DAG. Business slices do NOT wait for
-     * ALL foundation slices — they wait only for the foundation subset
-     * they declare as `dependsOn`. Optional; default false.
-     */
-    readonly foundation?: boolean;
-    /**
-     * v2.15.0 follow-up — G11: upstream sync slice. Marks a slice that
-     * syncs an upstream fork (e.g. hermes) to a new tag. UpstreamSync
-     * slices take priority within their topological level. Optional.
-     */
-    readonly upstreamSync?: boolean;
-    /**
-     * v2.15.0 follow-up — G2: complexity tier. Drives Code's scheduling
-     * (complex = user-attended, simple/trivial = overnight). Optional.
-     */
-    readonly complexity?: SliceComplexity;
-    /**
-     * Slice 2026-09-10-dispatch-token-and-swarm §3: files this slice is
-     * expected to touch. When EVERY node of a topological level declares
-     * `files`, `--from-dag` emits a file-overlap wave plan (`firstLevelWaves`)
-     * so the LLM can fan the level out without serializing on a shared file.
-     * Optional and additive: absent → DAG hash and dispatch behavior are
-     * byte-identical to before this slice.
-     */
-    readonly files?: readonly string[];
-}
-export interface DependsOn {
-    readonly from: string;
-    readonly to: string;
-}
-export interface SliceDag {
-    readonly nodes: readonly SliceNode[];
-    readonly edges: readonly DependsOn[];
-}
-/** Thrown by `validateDag` when the graph violates one of the constraints. */
-export declare class InvalidSliceDagError extends Error {
-    readonly path?: readonly string[] | undefined;
-    readonly code: "INVALID_SLICE_DAG";
-    constructor(message: string, path?: readonly string[] | undefined);
-}
-/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
-export declare class SliceDagCycleError extends Error {
-    readonly cyclePath: readonly string[];
-    readonly code: "SLICE_DAG_CYCLE";
-    constructor(cyclePath: readonly string[]);
-}
+import { type SliceDag } from './slice-dag-types.js';
 /**
  * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
  * Pure. Cheap. No I/O.
@@ -88,49 +26,5 @@ export declare function sliceReadyToRun(dag: SliceDag, completed: ReadonlySet<st
 export declare function serializeDag(dag: SliceDag): string;
 /** SHA-256 hash of the serialized DAG. Stable across runs. */
 export declare function hashDag(dag: SliceDag): string;
-/**
- * Knobs for wave planning + artifact-pass behaviour.
- *
- * - `maxConcurrency`: hard cap on how many slices a single Wave can hold.
- *   Each topological level is chunked into Waves of at most this many
- *   slice IDs (default 6 per `2026-07-28-24h-loop-audit.md` E direction).
- * - `passArtifacts`: when true, each Wave's prompt is augmented with a
- *   `WaveArtifact` envelope (contracts of preceding Waves). Default
- *   false — the existing `runDag` ancestor-injection path already covers
- *   per-slice contract coverage.
- */
-export interface WaveOptions {
-    readonly maxConcurrency: number;
-    readonly passArtifacts: boolean;
-}
-/** Default wave options: 6 leaves per wave; artifact-pass off. */
-export declare const DEFAULT_MAX_CONCURRENCY = 6;
-export declare const DEFAULT_WAVE_OPTIONS: WaveOptions;
-/**
- * Artifact envelope emitted when a Wave completes successfully.
- *
- * - `waveIndex`: sequential, 0-based across the whole plan.
- * - `completedLeaves`: slice IDs that finished (`status: 'done'`). Failed
- *    or cancelled leaves are NOT included.
- * - `contracts`: per-slice public contract snapshot (sliceId → record).
- *    Stored verbatim so a downstream Wave can re-inject this without
- *    re-reading the disk-side contract store.
- * - `passedAt`: ISO timestamp of Wave completion (caller-supplied to keep
- *    the surface pure).
- */
-export interface WaveArtifact {
-    readonly waveIndex: number;
-    readonly completedLeaves: readonly string[];
-    readonly contracts: Readonly<Record<string, unknown>>;
-    readonly passedAt: string;
-}
-/**
- * A single dispatch Wave. Holds the slice IDs that must execute together,
- * respecting `WaveOptions.maxConcurrency`. Waves are emitted in
- * topological order; downstream consumers may treat `waveIndex` as a
- * monotonic cursor.
- */
-export interface Wave {
-    readonly waveIndex: number;
-    readonly slices: readonly string[];
-}
+export { DEFAULT_MAX_CONCURRENCY, DEFAULT_WAVE_OPTIONS, isSliceComplexity, InvalidSliceDagError, SLICE_COMPLEXITIES, SliceDagCycleError } from './slice-dag-types.js';
+export type { DependsOn, SliceComplexity, SliceDag, SliceNode, Wave, WaveArtifact, WaveOptions } from './slice-dag-types.js';

package/dist/services/dispatch/slice-dag.js

@@ -25,40 +25,19 @@
  *   SHA-256 hash is therefore reproducible for the same logical DAG.
  */
 import { createHash } from 'node:crypto';
-export const SLICE_COMPLEXITIES = [
-    'trivial',
-    'simple',
-    'complex'
-];
-export function isSliceComplexity(value) {
-    return SLICE_COMPLEXITIES.includes(value);
-}
-/** Thrown by `validateDag` when the graph violates one of the constraints. */
-export class InvalidSliceDagError extends Error {
-    path;
-    code = 'INVALID_SLICE_DAG';
-    constructor(message, path) {
-        super(message);
-        this.path = path;
-        this.name = 'InvalidSliceDagError';
-    }
-}
-/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
-export class SliceDagCycleError extends Error {
-    cyclePath;
-    code = 'SLICE_DAG_CYCLE';
-    constructor(cyclePath) {
-        super(`cycle detected in slice DAG: ${cyclePath.join(' -> ')}`);
-        this.cyclePath = cyclePath;
-        this.name = 'SliceDagCycleError';
-    }
-}
+import { isArray } from '../../shared/array-guards.js';
+import { isSliceComplexity, InvalidSliceDagError, SLICE_COMPLEXITIES, SliceDagCycleError } from './slice-dag-types.js';
 /**
  * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
  * Pure. Cheap. No I/O.
  */
 export function validateDag(dag) {
-    if (!dag || !Array.isArray(dag.nodes) || !Array.isArray(dag.edges)) {
+    // `isArray` (not `Array.isArray`): at runtime this is the identical check, but
+    // `Array.isArray` is typed `arg is any[]` and so widens `dag.nodes` /
+    // `dag.edges` — already `readonly SliceNode[]` / `readonly DependsOn[]` — to
+    // `any[]` for the rest of the function, which is where this file's 43
+    // `no-unsafe-*` findings came from. See `src/shared/array-guards.ts`.
+    if (!dag || !isArray(dag.nodes) || !isArray(dag.edges)) {
         throw new InvalidSliceDagError('dag must have nodes and edges arrays');
     }
     if (dag.nodes.length === 0) {
@@ -105,7 +84,8 @@ export function validateDag(dag) {
         }
         // Slice 2026-09-10 §3: optional file list. Only shape-checked when
         // present so pre-existing DAGs stay valid.
-        if (n.files !== undefined && (!Array.isArray(n.files) || n.files.some((f) => typeof f !== 'string' || f.length === 0))) {
+        if (n.files !== undefined &&
+            (!isArray(n.files) || n.files.some((f) => typeof f !== 'string' || f.length === 0))) {
             throw new InvalidSliceDagError(`node ${n.id} files must be an array of non-empty strings when present`);
         }
     }
@@ -244,9 +224,6 @@ export function serializeDag(dag) {
 export function hashDag(dag) {
     return createHash('sha256').update(serializeDag(dag)).digest('hex');
 }
-/** Default wave options: 6 leaves per wave; artifact-pass off. */
-export const DEFAULT_MAX_CONCURRENCY = 6;
-export const DEFAULT_WAVE_OPTIONS = {
-    maxConcurrency: DEFAULT_MAX_CONCURRENCY,
-    passArtifacts: false
-};
+/* Type surface moved to `slice-dag-types.ts` (300-raw-line cap); re-exported
+ * here so every existing `slice-dag.js` import path keeps working. */
+export { DEFAULT_MAX_CONCURRENCY, DEFAULT_WAVE_OPTIONS, isSliceComplexity, InvalidSliceDagError, SLICE_COMPLEXITIES, SliceDagCycleError } from './slice-dag-types.js';

package/dist/services/dispatch/sub-agent-batch-await.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the two
+ * back-compat `awaitBatch` wrappers from `./sub-agent-dispatcher.ts`, so that
+ * module clears the 300 raw-line cap. Both are thin wrappers around the unified
+ * service in `./await-batch.ts`; neither body, default timeout, note prefix or
+ * doc comment changed, and the dispatch-record file layout they read is the one
+ * `./await-batch.ts#defaultReadOutcome` parses. `sub-agent-dispatcher.ts`
+ * imports and re-exports both, so the per-IDE dispatchers keep calling them
+ * through the same path and
+ * `tests/unit/services/dispatch/sub-agent-dispatcher-timeouts.test.ts` keeps
+ * observing the same per-IDE configuration through the same `vi.mock` seam.
+ */
+import type { SubAgentAwaitBatchInput, SubAgentBatchResult } from './sub-agent-dispatcher-types.js';
+/**
+ * Real awaitBatch for claude-code (MVP). In 1.2, dispatch + await are
+ * both in the same process; we record the batch size and resolve after
+ * `dispatchCount` heartbeats land for the given `recordPaths`, or after
+ * `timeoutMs` elapses (per-dispatch `timeout` status).
+ *
+ * Implementation contract (MVP):
+ *  - We poll each `recordPaths[i]` for an `outcome: success | failed` or
+ *    `status: done | failed` field; if absent after `timeoutMs`, that
+ *    dispatch is reported as `timeout`.
+ *  - The poll interval is 50ms (fast enough for unit tests, cheap enough
+ *    for the MVP; the real cross-process version uses heartbeat polling).
+ */
+export declare function awaitClaudeCodeBatch(input: SubAgentAwaitBatchInput): Promise<readonly SubAgentBatchResult[]>;
+/**
+ * Slice 1.3 — shared per-IDE polling core for trae / codex / cursor.
+ * Same polling loop shape as `awaitClaudeCodeBatch`, with per-IDE
+ * default timeout + note prefix. The 3 IDEs differ only in
+ * (a) `defaultTimeoutMs` (Trae / Cursor = 30s, Codex = 45s per slice
+ * #13 R-3) and (b) the `note` label surfaced when an IDE times out
+ * (so 1.4 dogfood can attribute a timeout to the right IDE).
+ *
+ * MVP rationale (per Karpathy §2 Simplicity First): the 3 IDEs
+ * currently share the same file-based polling transport. The only
+ * per-IDE distinction is the timeout + label. Future per-IDE
+ * divergence (real IPC / shell hooks) is a 1.4 dogfood concern —
+ * here we keep the dispatcher interface uniform while each IDE's
+ * `awaitBatch` is a real implementation.
+ */
+export interface PollDispatchRecordsOptions {
+    readonly defaultTimeoutMs: number;
+    readonly notePrefix: string;
+}
+export declare function pollDispatchRecords(input: SubAgentAwaitBatchInput, opts: PollDispatchRecordsOptions): Promise<readonly SubAgentBatchResult[]>;

package/dist/services/dispatch/sub-agent-batch-await.js

@@ -0,0 +1,73 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the two
+ * back-compat `awaitBatch` wrappers from `./sub-agent-dispatcher.ts`, so that
+ * module clears the 300 raw-line cap. Both are thin wrappers around the unified
+ * service in `./await-batch.ts`; neither body, default timeout, note prefix or
+ * doc comment changed, and the dispatch-record file layout they read is the one
+ * `./await-batch.ts#defaultReadOutcome` parses. `sub-agent-dispatcher.ts`
+ * imports and re-exports both, so the per-IDE dispatchers keep calling them
+ * through the same path and
+ * `tests/unit/services/dispatch/sub-agent-dispatcher-timeouts.test.ts` keeps
+ * observing the same per-IDE configuration through the same `vi.mock` seam.
+ */
+// Slice 2026-07-29-dispatch-stall-governance / S4 — the two near-
+// identical poll loops in this file are now thin wrappers around
+// `awaitBatch` (the unified implementation in ./await-batch.ts). The
+// back-compat envelopes are preserved so the pre-S4 S3 character-
+// ization tests + the existing call sites do not have to migrate in
+// the same slice.
+import { awaitBatch as awaitBatchUnified } from './await-batch.js';
+/* ──────────────────────────────────────────────────────────────────────────
+ * 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a) — awaitBatch implementation
+ * ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Real awaitBatch for claude-code (MVP). In 1.2, dispatch + await are
+ * both in the same process; we record the batch size and resolve after
+ * `dispatchCount` heartbeats land for the given `recordPaths`, or after
+ * `timeoutMs` elapses (per-dispatch `timeout` status).
+ *
+ * Implementation contract (MVP):
+ *  - We poll each `recordPaths[i]` for an `outcome: success | failed` or
+ *    `status: done | failed` field; if absent after `timeoutMs`, that
+ *    dispatch is reported as `timeout`.
+ *  - The poll interval is 50ms (fast enough for unit tests, cheap enough
+ *    for the MVP; the real cross-process version uses heartbeat polling).
+ */
+export async function awaitClaudeCodeBatch(input) {
+    // Slice 2026-07-29-dispatch-stall-governance / S4 (G8) — this
+    // function is now a thin wrapper around the unified `awaitBatch`
+    // service. The back-compat envelope shape is preserved (one
+    // `SubAgentBatchResult` per record path) so the S3 characterization
+    // test stays green; the underlying loop is identical to the trae /
+    // codex / cursor wrappers below. The new typed outcome
+    // lives on the unified service; the S4 fail-fast test pins it.
+    //
+    // Slice 2026-07-30-nightshift: claude-code does NOT use a
+    // per-IDE note prefix. The 1.4 dogfood contract says the done
+    // note is `null` (raw outcome) and the failed note is the raw
+    // `outcome` string with no prefix. The 3 non-Claude IDEs
+    // (trae / codex / cursor) prefix the note with their
+    // per-IDE label so cross-IDE attribution is visible to the LLM.
+    // Passing no `notePrefix` here keeps the legacy contract.
+    const unified = await awaitBatchUnified(input.dispatchCount, input.recordPaths, input.timeoutMs, {
+        defaultTimeoutMs: 60_000
+    });
+    // Touch batchId so the parameter remains in scope for any future
+    // in-process queue wiring.
+    void input.batchId;
+    return unified.results;
+}
+export async function pollDispatchRecords(input, opts) {
+    // Slice 2026-07-29-dispatch-stall-governance / S4 (G8) — this
+    // function is now a thin wrapper around the unified `awaitBatch`
+    // service. Pre-S4 it diverged from `awaitClaudeCodeBatch` in
+    // (a) the default-fallback source and (b) the `Math.max(deadline, 0)`
+    // step; the divergence is gone. The back-compat envelope (one
+    // `SubAgentBatchResult` per record path, with the IDE-prefixed
+    // note) is preserved.
+    const unified = await awaitBatchUnified(input.dispatchCount, input.recordPaths, input.timeoutMs, {
+        defaultTimeoutMs: opts.defaultTimeoutMs,
+        notePrefix: opts.notePrefix
+    });
+    return unified.results;
+}

package/dist/services/dispatch/sub-agent-dispatcher-types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the sub-agent
+ * dispatch CONTRACT (the role namespace, the IDE-private tool-call descriptor,
+ * the dispatch input, the per-IDE dispatcher interface and the two batch-await
+ * shapes) from `./sub-agent-dispatcher.ts`, so that module clears the 300
+ * raw-line cap. Every declaration is a type or interface: no runtime value
+ * moved, no member, modifier or doc comment changed. `sub-agent-dispatcher.ts`
+ * re-exports all six names from its own path, so no importer changed and the
+ * envelope schema pinned by `tests/unit/services/dispatch/sub-agent-dispatchers.test.ts`
+ * is the same schema.
+ */
+/**
+ * Role string namespace. Soft whitelist — the CLI does NOT hard-validate
+ * specific role names. Empirically observed (peaks-qa SKILL.md):3 top
+ * roles +3 sub-roles + arbitrary business subdivisions:
+ *
+ * - top: rd | qa | ui | txt | general-purpose
+ * - qa sub-roles: qa-business | qa-perf | qa-security
+ * - business细分: qa-business-regression | qa-business-api
+ * | qa-business-frontend | ...
+ * - promotable: prd-business | prd-technical | prd-ux |
+ * ui-visual | ui-flow | ui-component | ...
+ *
+ * Any non-empty string is a valid role. CLI emits a "soft whitelist"
+ * hint in --help but does not reject unknown values.
+ */
+export type SubAgentRole = string;
+/**
+ * IDE-private tool-call descriptor. The LLM, upon receiving this in
+ * the CLI's JSON envelope, must invoke the tool named `name` in its
+ * own environment with the provided `args`.
+ */
+export interface SubAgentToolCall {
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    /**
+     * Slice 2026-06-23-audit-4th #C2: toolCall version. The IDE's
+     * arg shape can change between versions (e.g. Claude Code's
+     * `subagent_type: "general-purpose"` may become
+     * `subagent_type: "claude-code-3.5"` in a future release). The
+     * dispatcher stamps this on `buildToolCall`; the dispatch record
+     * propagates it so a future reader can detect "this record is for
+     * v2.0 Task, current IDE is v3.0" without inspecting args.
+     * Pre-versioning records default to '2.0.0' on read.
+     */
+    readonly toolCallVersion?: string;
+}
+/**
+ * Input to `buildToolCall`. The CLI assembles this from the user's
+ * command-line args (role, prompt) + state-machine lookups
+ * (requestId, sessionId).
+ */
+export interface SubAgentDispatchInput {
+    readonly role: SubAgentRole;
+    readonly prompt: string;
+    readonly requestId: string;
+    readonly sessionId: string;
+}
+/**
+ * Per-IDE sub-agent dispatcher contract. Each IdeAdapter exposes
+ * one of these; the CLI calls `buildToolCall` after validating
+ * `supportsRole` (and `null-dispatcher` is the fallback when an
+ * IDE cannot dispatch sub-agents at all).
+ */
+export interface SubAgentDispatcher {
+    /**
+     * Short label used in envelope `ide` field and CLI help text.
+     * e.g. "claude-code" / "trae" / "null".
+     */
+    readonly label: string;
+    /**
+     * Whether this dispatcher supports dispatching a given role.
+     * claude-code returns true for all non-empty strings; trae is
+     * byte-identical (UNVERIFIED pending real Trae dogfood);
+     * null-dispatcher always returns false.
+     */
+    supportsRole(role: SubAgentRole): boolean;
+    /**
+     * Build the IDE-specific tool call descriptor for a dispatch.
+     * Must be pure: no I/O, no side effects. The CLI wraps the
+     * returned descriptor in its JSON envelope.
+     */
+    buildToolCall(input: SubAgentDispatchInput): SubAgentToolCall;
+    /**
+     * 2.7.0 slice-dag-dispatcher MVP: join barrier for a batch of dispatched
+     * sub-agents. Returns one BatchResult per dispatch in the batch.
+     *
+     * Default implementation in this MVP (1.2): claude-code holds an
+     * in-process Promise queue (LRU-keyed by batchId); the four non-Claude
+     * IDEs (trae / trae-cn / codex / cursor) return a
+     * `awaitByLlm: true` marker so the calling LLM holds the await itself
+     * — envelope shape is uniform. Real per-IDE implementations land in
+     * 1.3.
+     *
+     * `nullSubAgentDispatcher` throws `SubAgentNotSupportedError` here.
+     */
+    awaitBatch?(input: SubAgentAwaitBatchInput): Promise<readonly SubAgentBatchResult[]>;
+}
+/**
+ * 2.7.0 slice-dag-dispatcher MVP: input to the optional `awaitBatch` method.
+ * MVP dispatch is one batch per top-level `peaks sub-agent dispatch --from-dag`
+ * call; `batchId` is the same one returned in the dispatch envelope.
+ */
+export interface SubAgentAwaitBatchInput {
+    readonly batchId: string;
+    readonly dispatchCount: number;
+    /** Per-dispatch record path; CLI already has this from the dispatch envelope. */
+    readonly recordPaths: readonly string[];
+    /** Optional cap on how long the join should wait. */
+    readonly timeoutMs?: number;
+}
+/**
+ * 2.7.0 slice-dag-dispatcher MVP: per-dispatch result of a join barrier.
+ * The CLI returns one of these per dispatch in the batch.
+ */
+export interface SubAgentBatchResult {
+    readonly dispatchIndex: number;
+    readonly recordPath: string;
+    readonly status: 'done' | 'failed' | 'cancelled' | 'timeout';
+    readonly durationMs: number;
+    readonly note: string | null;
+}

package/dist/services/dispatch/sub-agent-dispatcher-types.js

@@ -0,0 +1,12 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the sub-agent
+ * dispatch CONTRACT (the role namespace, the IDE-private tool-call descriptor,
+ * the dispatch input, the per-IDE dispatcher interface and the two batch-await
+ * shapes) from `./sub-agent-dispatcher.ts`, so that module clears the 300
+ * raw-line cap. Every declaration is a type or interface: no runtime value
+ * moved, no member, modifier or doc comment changed. `sub-agent-dispatcher.ts`
+ * re-exports all six names from its own path, so no importer changed and the
+ * envelope schema pinned by `tests/unit/services/dispatch/sub-agent-dispatchers.test.ts`
+ * is the same schema.
+ */
+export {};