@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/orchestration-shell/root-discovery.d.ts

@@ -0,0 +1,25 @@
+export declare const DEFAULT_DISCOVERY_MAX_DEPTH = 2;
+export declare const DEFAULT_DISCOVERY_MAX_ROOTS = 25;
+type DiscoveryReason = 'git' | 'manifest' | 'fallback';
+export interface DiscoveredRepositoryRoot {
+    rootPath: string;
+    reason: DiscoveryReason;
+    manifestFile?: string;
+}
+export interface RepositoryRootDiscoveryResult {
+    launchDir: string;
+    rootPaths: string[];
+    roots: DiscoveredRepositoryRoot[];
+    maxDepth: number;
+    maxRoots: number;
+    omittedRootCount: number;
+    omittedAncestorRoots: string[];
+    prunedDirectoryCount: number;
+    capped: boolean;
+}
+export declare function discoverRepositoryRoots(deps?: {
+    launchDir?: string;
+    maxDepth?: number;
+    maxRoots?: number;
+}): Promise<RepositoryRootDiscoveryResult>;
+export {};

package/dist/orchestration-shell/route-browse.d.ts

@@ -0,0 +1,20 @@
+import type { OrchestrationStore } from './store';
+import type { LocalGemmaAdvisoryRunner } from '../planner/local-advisory';
+export interface RouteBrowseDeps {
+    store: OrchestrationStore;
+    /** Undefined when the local model isn't installed/enabled → no-model advisory. */
+    localAdvisoryRunner?: LocalGemmaAdvisoryRunner;
+    userPrompt: string;
+    browseUrls?: string[];
+    browseQuery?: string;
+    /** Recent conversation turns (for context-aware search-query formulation). */
+    priorTurns?: string[];
+    /** Esc-abort signal (shell-owned AbortController). */
+    signal?: AbortSignal;
+}
+/**
+ * Orchestrate a `browse` route. Fetch an explicit URL, or run a keyless web
+ * search and read the top result, then answer via local Gemma. Mirrors
+ * routeBrainstorm/routeFamiliarize (no-model advisory, clean failures, no crash).
+ */
+export declare function routeBrowse(deps: RouteBrowseDeps): Promise<void>;

package/dist/orchestration-shell/slash-router.d.ts

@@ -1,4 +1,4 @@
-import { OrchestrationAction } from './types';
+import { OrchestrationAction, Tier } from './types';
 /**
  * Side effects a handler can request the entrypoint to dispatch.
  * The router itself never touches the store — keeps slash handling
@@ -26,12 +26,31 @@ export interface SlashOutput {
     /** Optional side effect; only `/quit` populates it in CP-1.a. */
     sideEffect?: ShellAction;
 }
+/**
+ * Public, render-safe view of a catalog row for the autocomplete dropdown
+ * (`<InputBar>`). Carries no handler — keeps the UI decoupled from dispatch.
+ */
+export interface SlashCommandInfo {
+    name: string;
+    blurb: string;
+}
+/** True if `command` is a shell-exit command (`/quit` / `/exit`). */
+export declare function isExitCommand(command: string): boolean;
 /**
  * §16 LOCK #10 + §5.1.5 + §11 row. Routes user input that starts with
  * `/`. Per §17 Q3 RESOLVED disposition: EXACT-MATCH only. Unknown
  * commands return a help hint.
  */
 export declare function routeSlashCommand(input: string): SlashOutput;
+/**
+ * Render-safe catalog view for the autocomplete dropdown (TUI redesign
+ * 2026-06-29). Returns `{ name, blurb }` in `/help` order, filtered to the
+ * commands the given `tier` can RUN (so a Pro user isn't suggested Max-only
+ * `/audit` or `/team`). `tier` omitted → the full catalog. The deferred
+ * `/attach` is excluded (it is not a runnable command). The orchestration TUI
+ * only renders for Pro/Max, so FREE is effectively unreachable here.
+ */
+export declare function listSlashCommands(tier?: Tier): SlashCommandInfo[];
 /**
  * Convenience helper for callers that wire the side effect directly
  * into the store. CP-1.a's `cli.ts` uses this; CP-1.b/c may dispatch

package/dist/orchestration-shell/slash-routes/continuation.d.ts

@@ -0,0 +1,71 @@
+import type { ContinuationPacketReader } from '../../continuation/packet-reader';
+import type { AgentKind } from '../../continuation/types';
+export interface ContinuationCliResult {
+    exitCode: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    stdout: string;
+}
+/**
+ * Valid `CONTINUE_WITH` target agents (#585 #C10M-1) — the closed enum the CLI
+ * validates user input against. Exported so the local `/continue accept` path in
+ * `index.ts` can validate the SERVER echo's `target_agent` through the SAME
+ * gate (first-wins: the echo's agent is authoritative, fail closed on anything
+ * outside this set).
+ */
+export declare const VALID_TARGET_AGENTS: ReadonlyArray<AgentKind>;
+/**
+ * PHASE-CP-10-MIN (#585) — the active-task context the `/continue request`
+ * subcommand needs to build the `PacketWriteInput`. Resolved by the entrypoint
+ * from the QuorumLoop's active loop state. `null` when no task is active.
+ */
+export interface ActiveContinuationRequestContext {
+    taskId: string;
+    gateId: string;
+    roundNumber: number;
+    brief: string;
+    sourceAgent: AgentKind;
+}
+/**
+ * PHASE-CP-10-MIN (#585) — the active continuation-handoff PROMPT context the
+ * `/continue accept` subcommand needs. Resolved by the entrypoint via Option A
+ * (the most-recent unresolved `continuation_offer_handoff` gate-prompt — from
+ * the store, or a `listEvents` piggyback). `null` when no offer is active.
+ */
+export interface ActiveContinuationOfferContext {
+    taskId: string;
+    gateId: string;
+    sessionId: string;
+    currentRound: number;
+    offerId: string;
+}
+export interface ContinuationCliDeps {
+    reader: ContinuationPacketReader;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-9/16 — `/continue request <target?>`: fire the
+     * `user_requested` continuation trigger for the active task. The entrypoint
+     * wires this to abort the running implementor (Codex-H1) THEN call
+     * `QuorumLoop.requestContinuation()` (the §3.5 H1 path — `writer.write()` →
+     * server stamps + emits the prompt). Resolves the minted `offerId` (or null
+     * on failure). ABSENT → `request` reports "unavailable".
+     */
+    request?: (ctx: ActiveContinuationRequestContext, targetAgent: AgentKind | undefined) => Promise<{
+        offerId: string;
+    } | null>;
+    /** Resolve the active-task request context (loop state). `null` if no active task. */
+    getActiveRequestContext?: () => ActiveContinuationRequestContext | null;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-9/11 — `/continue accept <target>`: the
+     * rescue/headless path. The entrypoint wires this to call
+     * `applyUserDecision({decision:'continue_with', notes: encrypt(target)})` AND
+     * drive the local `resumeFromContinuation` (with the `resumedOffers` dedupe).
+     * Resolves true on success. ABSENT → `accept` reports "unavailable".
+     */
+    accept?: (ctx: ActiveContinuationOfferContext, targetAgent: AgentKind) => Promise<boolean>;
+    /** Resolve the active continuation-handoff offer context. `null` if none. */
+    getActiveOfferContext?: () => ActiveContinuationOfferContext | null;
+}
+/**
+ * Dispatch a single `/continuation` invocation. Returns the exit code
+ * + stdout the shell should render. Caller wires `exitCode` into the
+ * `codevibe status` top-level binary's `process.exit(...)`.
+ */
+export declare function runContinuationCli(deps: ContinuationCliDeps, args: string[]): Promise<ContinuationCliResult>;

package/dist/orchestration-shell/slash-routes/reviewers.d.ts

@@ -0,0 +1,41 @@
+import type { AppSyncClient } from '../../appsync';
+import type { ReviewerAgentSpec, UserReviewerPolicySnapshot } from '../../types/reviewer';
+import { detectInstalledAgents } from '../../orchestration';
+/**
+ * Human-readable, ANSI-free rendering of a reviewer-policy snapshot. Renders ONLY
+ * the readable+writable policy surface (detected agents + the reviewer panel). The
+ * legacy `orchestrationEnabledDefault` opt-in was removed in CP-1 (2.0
+ * orchestration is shell-driven, not a stored flag — `queries.ts` does not select
+ * it: selecting it 401s on a post-CP-1 schema), so it is intentionally NOT shown
+ * (it would always render a misleading default).
+ */
+export declare function formatReviewerPolicy(snapshot: UserReviewerPolicySnapshot): string;
+/**
+ * Fetches + formats the user's reviewer panel. Re-pushes the locally detected
+ * agents (idempotent) and renders the returned snapshot. Never throws — returns
+ * a friendly error line so `/reviewers` can't crash the shell turn.
+ */
+export declare function runReviewersCli(client: AppSyncClient): Promise<string>;
+/**
+ * Tier-agnostic payload for opening the `/reviewer-setup` wizard: the host's
+ * detected agents + the user's current policy. The caller folds in the session
+ * `tier` to build the full `ReviewerWizardState`.
+ */
+export interface ReviewerWizardData {
+    installedAgents: ReturnType<typeof detectInstalledAgents>;
+    currentSeats: ReviewerAgentSpec[] | null;
+}
+/**
+ * Gathers everything the interactive wizard needs to render synchronously:
+ * detects installed agents (the only valid reviewer choices) and reads back the
+ * current policy via the idempotent `updateAvailableAgents` round-trip. Never
+ * throws — returns a `{ ok:false, message }` the caller surfaces as an advisory
+ * (no agents installed, or a transport error) instead of opening an empty modal.
+ */
+export declare function loadReviewerWizardData(client: AppSyncClient, detectFn?: typeof detectInstalledAgents): Promise<{
+    ok: true;
+    data: ReviewerWizardData;
+} | {
+    ok: false;
+    message: string;
+}>;

package/dist/orchestration-shell/slash-suggest.d.ts

@@ -0,0 +1,29 @@
+import type { SlashCommandInfo } from './slash-router';
+/**
+ * True when the current input is a slash COMMAND still being typed — a `/`
+ * followed by zero or more NON-space chars (no space yet). Once a space is
+ * typed the command is complete and the user is entering args, so the
+ * dropdown hides. A bare `/` qualifies (shows the full list).
+ */
+export declare function isSlashCommandInProgress(value: string): boolean;
+/**
+ * Prefix-filters the (already tier-filtered) catalog by the in-progress
+ * command token, case-insensitively, preserving catalog order. Returns `[]`
+ * when the value is not a command-in-progress (so the caller hides the
+ * dropdown). A bare `/` returns the whole list.
+ */
+export declare function filterSlashSuggestions(value: string, commands: SlashCommandInfo[]): SlashCommandInfo[];
+/**
+ * Builds a single dropdown row as ONE physical line (≤ `maxCols`) so it can
+ * never wrap and inflate the dropdown's row count on a narrow terminal
+ * (Stage-2 r4). The marker (`❯ `/`  `) + padded name come first; the blurb is
+ * appended ONLY if there's room (no dangling trailing space when it doesn't
+ * fit), and the whole row is truncated to `maxCols`.
+ */
+export declare function formatSuggestionRow(opts: {
+    name: string;
+    blurb: string;
+    highlighted: boolean;
+    maxCols: number;
+    namePad: number;
+}): string;

package/dist/orchestration-shell/status-format.d.ts

@@ -0,0 +1,59 @@
+/** The planner runtime kind resolved once at boot (NOT a live probe). */
+export type PlannerRuntimeKind = 'hosted' | 'local_gemma_qat' | 'local_unavailable';
+/**
+ * Truncate `s` to at most `max` columns with a trailing ellipsis. (Uses JS
+ * string length as a column proxy — adequate for the width-1 glyphs we render.)
+ */
+export declare function truncate(s: string, max: number): string;
+export interface PlannerBadge {
+    /** User-facing badge text. */
+    text: string;
+    /** Ink color when the badge is a warning; omitted → render dim. */
+    color?: string;
+}
+/**
+ * Abbreviates an absolute project path for the status bar:
+ *   - `$HOME` prefix → `~`
+ *   - if still wider than `maxCols`, left-truncate with a leading `…` so the
+ *     most-specific (rightmost) directories stay visible.
+ *
+ * Pure: `homedir` is injected (no `os` dependency here) so tests can pin it.
+ */
+export declare function formatProjectPath(projectPath: string, homedir: string, maxCols: number): string;
+/**
+ * Strips a model tag for display: `gemma4:latest` → `gemma4`. Falls back to a
+ * neutral label when nothing usable is provided.
+ */
+export declare function prettyModelLabel(model: string | null | undefined): string;
+/**
+ * Maps the boot-time planner runtime kind → the right-hand status badge.
+ *   - `local_gemma_qat`  → dim `<label> · local`   (no color → caller renders dim)
+ *   - `local_unavailable`→ yellow degraded warning  (the ONE state worth surfacing —
+ *     NL routing is off; only deterministic slash commands work)
+ *   - `hosted`           → null (hosted planner retired → no badge)
+ *
+ * The badge is a boot-time FACT, not a live health light — copy avoids implying
+ * liveness (see design doc "Architecture grounding").
+ */
+export declare function plannerBadge(kind: PlannerRuntimeKind, label: string): PlannerBadge | null;
+export interface StatusLayout {
+    /** Combined `<cwd> · <tier>` for the left, truncated to fit. */
+    leftText: string;
+    /** Badge text for the right (possibly truncated; '' when no badge). */
+    badgeText: string;
+}
+/**
+ * Computes the one-line status-bar layout so `leftText` + the badge ALWAYS fit
+ * within `columns` at ANY width (Stage-2). The badge is truncated so the
+ * ` · <tier>` always has room; the left (`<cwd> · <tier>`) is then truncated to
+ * the remaining width — on a sub-tier-width terminal the cwd vanishes and even
+ * the tier shrinks rather than wrapping. `.length` is the column proxy (the
+ * glyphs we render are width-1). Pure → unit-tested directly.
+ */
+export declare function computeStatusLayout(args: {
+    cwd: string;
+    tier: string;
+    homedir: string;
+    columns: number;
+    badge: PlannerBadge | null;
+}): StatusLayout;

package/dist/orchestration-shell/task-progress.d.ts

@@ -0,0 +1,122 @@
+/**
+ * One desktop-local progress phase. Discriminated by `phase`. Every variant is
+ * counts + labels + paths only — NEVER plaintext (see the module invariant).
+ */
+export type TaskProgressEvent = ({
+    phase: 'shadow_created';
+    round: number;
+} | {
+    phase: 'implementor_running';
+    round: number;
+    elapsedMs: number;
+    filesChanged?: number;
+} | {
+    phase: 'diff_captured';
+    round: number;
+    files: number;
+    created: number;
+    modified: number;
+    deleted: number;
+} | {
+    phase: 'submitting_diff';
+    round: number;
+} | {
+    phase: 'reviewers_dispatched';
+    gateId: string;
+    seats: number;
+} | {
+    phase: 'seat_update';
+    gateId: string;
+    seatId: number;
+    seatLabel: string;
+    state: 'running' | 'verdict_submitted';
+} | {
+    phase: 'verdicts_progress';
+    gateId: string;
+    received: number;
+    expected: number;
+} | {
+    phase: 'revise_round';
+    round: number;
+    feedbackSummary?: string;
+} | {
+    phase: 'round_failed';
+    round: number;
+    reason: string;
+} | {
+    phase: 'continuation_offered';
+    round: number;
+    reason: string;
+} | {
+    phase: 'declared_tests_skipped';
+    round: number;
+    paths: string[];
+} | {
+    phase: 'promoting';
+    files: number;
+} | {
+    phase: 'promoted';
+    files: number;
+} | {
+    phase: 'discarding';
+} | {
+    phase: 'discarded';
+} | {
+    phase: 'waiting_user';
+} | {
+    phase: 'planner_classifying';
+} | {
+    phase: 'familiarizing';
+} | {
+    phase: 'progress_cleared';
+}) & {
+    epoch?: number;
+    tokens?: number;
+};
+/** The callback the QuorumLoop invokes on each progress phase. */
+export type OnProgress = (event: TaskProgressEvent) => void;
+/**
+ * Format an elapsed-ms duration for the live timer: `M:SS` under an hour,
+ * `H:MM:SS` at/over an hour (design §6; matches Codex/Claude). Floored at 0 so an
+ * NTP backward step shows `0:00`, never a negative/huge value.
+ */
+export declare function formatElapsed(elapsedMs: number): string;
+export { finiteToken, unwrapClaudeJson } from '../reviewer/token-usage';
+/**
+ * [Phase 2 · P2-5] Humanize a token COUNT for the ` · ↓ <tokens>` segment. Pure;
+ * the input is an already-finite-non-negative integer (from `finiteToken`/
+ * `tokensFor`), defensively re-clamped so a stray caller can never render `NaN`.
+ *   • `n >= 999500` → `(n/1e6).toFixed(1)+'M'` (the 999500 boundary avoids
+ *     `999999 → "1000k"`).
+ *   • `n >= 1000`   → `v=n/1000`; `(v>=10 ? v.toFixed(0) : v.toFixed(1))+'k'`
+ *     (so `1.0k`/`9.9k` carry one decimal but `10k`/`57k`/`999k` carry none).
+ *   • else          → `String(n)`.
+ * The caller renders ONLY when `tokens && tokens > 0` (a `0`/absent count omits
+ * the whole segment), so `formatTokens(0)` is never surfaced.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * Whether a phase is a transient/spinner phase (an ephemeral live status line)
+ * vs a milestone that persists in scrollback. `implementor_running` (a ticking
+ * line) is the canonical spinner phase; `promoting`/`discarding` show a spinner
+ * while in flight. Everything else is a one-shot milestone.
+ *
+ * TODO(cleanup): production-UNUSED after the live-task-timer reducer rewrite (the
+ * reducer now classifies via the OPENER/REFRESH-ONLY/CLOSER trichotomy, not this
+ * helper). Kept + unit-tested for now; remove once single-track progress is stable.
+ */
+export declare function isSpinnerPhase(phase: TaskProgressEvent['phase']): boolean;
+/**
+ * Render the user-facing ONE-LINE text for a progress event. Pure (no plaintext
+ * — only counts/labels/paths/elapsed). The TUI shows spinner phases as an
+ * ephemeral live line and milestone phases as persisted scrollback entries.
+ */
+export declare function renderProgressLine(event: TaskProgressEvent): string;
+/**
+ * The BOUNDED label for the ephemeral LIVE line (design §5). Identical to
+ * `renderProgressLine` for the short phases, but path-bearing phases collapse to a
+ * count so the live line stays short (the FULL path list still persists in
+ * scrollback via `renderProgressLine`). The component additionally truncates this
+ * to the terminal width, timer-last, so the clock is never clipped.
+ */
+export declare function liveLabel(event: TaskProgressEvent): string;

package/dist/orchestration-shell/team-decompose.d.ts

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+import { buildImplementorArgv } from '../local-executor/implementor-argv';
+import type { LocalExecutor } from '../local-executor';
+import type { AgentKind } from '../local-executor/types';
+import type { WorkItemInput } from '../local-executor/task-group-types';
+/**
+ * The full decomposer-output shape pre-check (§3.E): `decompose:true` with ≥2
+ * well-shaped work items, OR `decompose:false` with a reason. ≥2 is the
+ * "a team is ≥2 tracks" contract (mirrors `parseTeamWorkItems`).
+ */
+export declare const WorkItemInputSchema: z.ZodDiscriminatedUnion<"decompose", [z.ZodObject<{
+    decompose: z.ZodLiteral<true>;
+    workItems: z.ZodArray<z.ZodObject<{
+        ownershipScope: z.ZodObject<{
+            write_paths: z.ZodArray<z.ZodString, "many">;
+            shared_contracts: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                access: z.ZodEnum<["write", "read"]>;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                access: "write" | "read";
+            }, {
+                path: string;
+                access: "write" | "read";
+            }>, "many">;
+            test_surfaces: z.ZodArray<z.ZodString, "many">;
+            auto_modified_files: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        }, {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        }>;
+        implementorAgent: z.ZodEffects<z.ZodEnum<["CLAUDE", "CODEX", "GEMINI", "ANTIGRAVITY"]>, "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY", unknown>;
+        isSharedTestOwner: z.ZodBoolean;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        ownershipScope: {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        };
+        implementorAgent: "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY";
+        isSharedTestOwner: boolean;
+    }, {
+        description: string;
+        ownershipScope: {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        };
+        isSharedTestOwner: boolean;
+        implementorAgent?: unknown;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    decompose: true;
+    workItems: {
+        description: string;
+        ownershipScope: {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        };
+        implementorAgent: "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY";
+        isSharedTestOwner: boolean;
+    }[];
+}, {
+    decompose: true;
+    workItems: {
+        description: string;
+        ownershipScope: {
+            shared_contracts: {
+                path: string;
+                access: "write" | "read";
+            }[];
+            write_paths: string[];
+            test_surfaces: string[];
+            auto_modified_files: string[];
+        };
+        isSharedTestOwner: boolean;
+        implementorAgent?: unknown;
+    }[];
+}>, z.ZodObject<{
+    decompose: z.ZodLiteral<false>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    decompose: false;
+}, {
+    reason: string;
+    decompose: false;
+}>]>;
+/** One work item the decomposer emits — the real wire `WorkItemInput` field
+ *  `implementorAgent` plus a desktop-local `description` brief. */
+export type DecomposerWorkItem = WorkItemInput & {
+    description: string;
+};
+export type DecomposerResult = {
+    decompose: true;
+    workItems: DecomposerWorkItem[];
+} | {
+    decompose: false;
+    reason: string;
+};
+/**
+ * Read the implementor's FINAL message text per-agent (§3.B / L9). Unlike
+ * `extractAgentSummary` (which returns '' for Codex because the diff is the
+ * single-impl contract), the DECOMPOSER needs the actual reply text — so for
+ * Codex we read AND unlink the `--output-last-message` temp file. A Codex
+ * decomposer would otherwise always parse-fail on its `--json` JSONL stdout.
+ *   - Claude  → `capture.kind === 'stdout'` → `handle.stdout()`.
+ *   - Codex   → `capture.kind === 'file'`   → read+unlink the temp file.
+ *   - Gemini  → stdout, unwrap the `{ response }` JSON envelope.
+ * NEVER throws — a capture error returns '' (→ the caller's parse-fail →
+ * single-task fallback).
+ */
+export declare function readImplementorFinalMessage(plan: ReturnType<typeof buildImplementorArgv>, handle: {
+    stdout: () => string;
+}, agent: AgentKind, exitCode: number): Promise<string>;
+/**
+ * Build the decomposition prompt fed to the local decomposer on stdin (§3.B).
+ * `brief` is the composed lossless implementation brief (§3.D step 0).
+ * `availableAgents` is the DETECTED set (§3.C) — the strengths list is filtered
+ * to it, and the decomposer is told to pick `implementorAgent` from it.
+ */
+export declare function buildDecomposerPrompt(brief: string, availableAgents: AgentKind[]): string;
+/**
+ * #590 — append a deterministic "allowed test files" line to a track's brief so
+ * the implementor agent writes its own-module tests at the EXACT declared
+ * `test_surfaces` paths (which `filesOutsideWriteScope` then accepts in-lane).
+ * Belt-and-suspenders to the decomposer-prompt instruction: even if the model's
+ * `description` prose omits the test paths, the agent is told them verbatim, so a
+ * test write lands inside the declared lane rather than tripping out_of_scope_write.
+ * No-op (returns the brief unchanged) when the track declares no test surfaces.
+ */
+export declare function appendTestSurfaceGuidance(brief: string, testSurfaces: string[]): string;
+/**
+ * Parse + shape-validate a decomposer reply into a `DecomposerResult`. Returns
+ * null when the text contains no parseable/valid JSON (the caller retries once,
+ * then falls back to single). The full `WorkItemInputSchema` (§3.E) is applied
+ * here so a deep-malformed shape fails the parse LOCALLY (NOT later as an
+ * `unknown_create_error`).
+ */
+export declare function parseDecomposerResult(text: string): DecomposerResult | null;
+export interface RunLocalDecomposerDeps {
+    localExecutor: LocalExecutor;
+    /** Canonicalized real working dir (the repo) — the decomposer reads the tree. */
+    workingDir: string;
+}
+/**
+ * Run the local decomposition pass (§3.B). Spawns the FIRST available agent in
+ * read-only `plan` mode via the PRODUCTION `LocalExecutor.spawnImplementor` path
+ * (NOT `AdapterRegistry.launchImplementor`, which has no prompt/capture). The
+ * decomposition prompt rides stdin; output is captured per-agent via
+ * `readImplementorFinalMessage` and tolerant-parsed. On a parse failure it
+ * retries ONCE with a "JSON only" suffix; a second failure → `{ decompose:false }`
+ * (the caller treats that as the single-task fallback).
+ *
+ * `availableAgents` is the DETECTED set (§3.C). The decomposer itself runs as
+ * the first detected agent; CP-7 engages because `role:'implementor'` + a
+ * (synthetic) `taskId` are passed.
+ */
+export declare function runLocalDecomposer(deps: RunLocalDecomposerDeps, brief: string, availableAgents: AgentKind[]): Promise<DecomposerResult>;
+/**
+ * Validate + normalize each work item's `implementorAgent` against the DETECTED
+ * agent set (§3.C — v1 is DETECTED-ONLY; NO capability-health filtering, NO
+ * per-spawn auth-recheck). For each item: `.toUpperCase()`-normalize the
+ * suggested agent; keep it if detected; else SUBSTITUTE the first detected
+ * agent. If NO agent is detected → `null` (the caller falls back to single).
+ * Returns NEW work items (does not mutate the inputs).
+ */
+export declare function validateAgentAvailability(workItems: DecomposerWorkItem[], detected: AgentKind[]): DecomposerWorkItem[] | null;