@webpresso/agent-kit 3.1.26 → 3.1.28

package/dist/esm/cli/auto-update/installer.js

@@ -13,6 +13,8 @@
  * releases the lease. Concurrency control, the observability tombstone,
  * verification, and repair all live in the guard — this module only decides
  * WHETHER to spawn and wires the detached stdio to auto-update.log.
+ * Guard argv uses the cycle-free self-invocation leaf (never a full import of
+ * the guard command module).
  *
  * Invariants:
  *   - Synchronous: returns before the install starts.
@@ -24,14 +26,15 @@
  *     `logUpdateError` and swallowed; the user never sees an exception
  *     from a successful CLI run.
  */
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { dirname } from "node:path";
 import { getSurfacePath } from "#paths/state-root.js";
-import { writeJsonFile } from "#shared-utils/write-json-file.js";
-import { buildSelfInvocationCommand } from "#cli/commands/self-install-guard.js";
 import { logUpdateError } from "./log.js";
+import { buildSelfInvocationCommand } from "./self-invocation.js";
 export { isProcessAlive } from "./install-lock.js";
+/** Re-export for existing call sites and tests (implementation in guard-tombstone). */
+export { buildTombstone, writeGuardTombstone } from "./guard-tombstone.js";
 /**
  * Schedule a deferred install for the supplied package-manager command,
  * routed through the self-install guard. Synchronous — spawn() returns
@@ -66,37 +69,6 @@ export function scheduleDeferredInstall(plan, options = {}) {
         return { spawned: false, reason: "spawn error" };
     }
 }
-/**
- * Observability tombstone written by the self-install guard when it takes
- * the lease: records the guard's pid + start time in the notifier cache for
- * humans and `wp update`'s cache-reconcile step. NOT a concurrency gate —
- * the heartbeat lease in install-lock.ts owns mutual exclusion. Best-effort.
- */
-export function writeGuardTombstone() {
-    try {
-        const configPath = resolveConfigPath();
-        if (configPath === null)
-            return;
-        writeTombstone(configPath, buildTombstone(process.pid, Date.now()));
-    }
-    catch (err) {
-        logUpdateError(err);
-    }
-}
-/**
- * Build the canonical tombstone shape. Exported for testability.
- */
-export function buildTombstone(pid, ts) {
-    return { autoInstallInProgress: { pid, ts } };
-}
-function resolveConfigPath() {
-    try {
-        return getSurfacePath("update-notifier-cache.json", "user");
-    }
-    catch {
-        return null;
-    }
-}
 function resolveLogPath() {
     try {
         return getSurfacePath("auto-update.log", "user");
@@ -105,29 +77,6 @@ function resolveLogPath() {
         return null;
     }
 }
-function readRaw(configPath) {
-    if (!existsSync(configPath))
-        return {};
-    try {
-        const text = readFileSync(configPath, "utf-8");
-        if (text.trim().length === 0)
-            return {};
-        const parsed = JSON.parse(text);
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-            return {};
-        return parsed;
-    }
-    catch {
-        return {};
-    }
-}
-function writeTombstone(configPath, tombstone) {
-    const dir = dirname(configPath);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    const merged = { ...readRaw(configPath), ...tombstone };
-    writeJsonFile(configPath, merged, { atomic: true, indent: 0, trailingNewline: false });
-}
 function openLogForAppend(logPath) {
     const dir = dirname(logPath);
     if (!existsSync(dir))

package/dist/esm/cli/auto-update/self-invocation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cycle-free leaf: how `wp` re-invokes itself for self-install-guard.
+ *
+ * Lives outside `self-install-guard.ts` so deferred install, `wp update`, and
+ * setup can build guard argv without importing the full guard command module
+ * (which would re-create installer ↔ guard cycles and tempt dynamic imports).
+ *
+ * Survival rule: prefer a **stable** global launcher (`~/.vite-plus/bin/wp` or
+ * PATH `wp` outside an installId package tree). Re-execing
+ * `node …/agent-kit#id/…/cli.js` dies after `vp update -g` deletes the pre-swap
+ * tree mid-guard.
+ */
+export interface SelfInvocationOptions {
+    readonly execPath?: string;
+    readonly argv1?: string;
+    /** Injectable stable launcher for tests; `null` forces legacy argv1 path. */
+    readonly stableWp?: string | null;
+}
+/**
+ * Build argv to re-invoke wp with the given subcommand args.
+ * - Prefer stable non-versioned launcher when available.
+ * - Bun-compiled binary: process.execPath IS the binary (argv[1] is /$bunfs).
+ * - Source/dev lane without a stable launcher: `<runtime> <script>`.
+ */
+export declare function buildSelfInvocationCommand(args: readonly string[], options?: SelfInvocationOptions): string[];
+export interface ResolveStableWpLauncherOptions {
+    readonly home?: string;
+    readonly pathEnv?: string;
+    readonly existsSync?: (path: string) => boolean;
+}
+/**
+ * A launcher that survives installId package-tree deletion during global update.
+ * Rejects paths under `agent-kit#<uuid>/` (versioned store payload).
+ */
+export declare function resolveStableWpLauncher(options?: ResolveStableWpLauncherOptions): string | null;
+/** True when path lives inside a vite-plus installId package tree. */
+export declare function isVersionedAgentKitPayloadPath(filePath: string): boolean;

package/dist/esm/cli/auto-update/self-invocation.js

@@ -0,0 +1,62 @@
+/**
+ * Cycle-free leaf: how `wp` re-invokes itself for self-install-guard.
+ *
+ * Lives outside `self-install-guard.ts` so deferred install, `wp update`, and
+ * setup can build guard argv without importing the full guard command module
+ * (which would re-create installer ↔ guard cycles and tempt dynamic imports).
+ *
+ * Survival rule: prefer a **stable** global launcher (`~/.vite-plus/bin/wp` or
+ * PATH `wp` outside an installId package tree). Re-execing
+ * `node …/agent-kit#id/…/cli.js` dies after `vp update -g` deletes the pre-swap
+ * tree mid-guard.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+/**
+ * Build argv to re-invoke wp with the given subcommand args.
+ * - Prefer stable non-versioned launcher when available.
+ * - Bun-compiled binary: process.execPath IS the binary (argv[1] is /$bunfs).
+ * - Source/dev lane without a stable launcher: `<runtime> <script>`.
+ */
+export function buildSelfInvocationCommand(args, options = {}) {
+    const stableWp = options.stableWp !== undefined ? options.stableWp : resolveStableWpLauncher();
+    if (typeof stableWp === "string" && stableWp.length > 0) {
+        return [stableWp, ...args];
+    }
+    const execPath = options.execPath ?? process.execPath;
+    const argv1 = options.argv1 ?? process.argv[1] ?? "";
+    if (argv1.startsWith("/$bunfs"))
+        return [execPath, ...args];
+    return [execPath, argv1, ...args];
+}
+/**
+ * A launcher that survives installId package-tree deletion during global update.
+ * Rejects paths under `agent-kit#<uuid>/` (versioned store payload).
+ */
+export function resolveStableWpLauncher(options = {}) {
+    const exists = options.existsSync ?? existsSync;
+    const home = options.home ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const candidates = [];
+    if (home) {
+        candidates.push(path.join(home, ".vite-plus", "bin", "wp"));
+    }
+    const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        candidates.push(path.join(dir, "wp"));
+    }
+    for (const candidate of candidates) {
+        if (!exists(candidate))
+            continue;
+        if (isVersionedAgentKitPayloadPath(candidate))
+            continue;
+        return candidate;
+    }
+    return null;
+}
+/** True when path lives inside a vite-plus installId package tree. */
+export function isVersionedAgentKitPayloadPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    return /\/@webpresso\/agent-kit#[^/]+\//u.test(normalized);
+}

package/dist/esm/cli/commands/audit.js

@@ -27,6 +27,7 @@ export const REPO_AUDIT_REGISTRY = {
         includeRuntimePlans: options.runtimePlans,
         baseRef: options.baseRef ?? options.base,
         changedOnly: options.changedOnly,
+        affectedFiles: options.affectedFiles,
     }),
     "blueprint-trust": async (root) => (await import("#audit/blueprint-trust")).auditBlueprintTrust(root),
     "roadmap-links": async (root, options) => (await import("#audit/roadmap-links")).auditRoadmapLinks(root, {

package/dist/esm/cli/commands/dash/index.js

@@ -121,8 +121,8 @@ async function runMenuMode(cwd, launch) {
     writeStartupFrame(label);
     try {
         const { runMenu } = await import("./menu.js");
-        // The import above is what the frame covers; clear it so Ink renders a
-        // single menu at the top instead of stacking below the ghost frame.
+        // Clear the startup ghost frame so the TUI (native Ratatui or pure-ANSI)
+        // paints a single menu at the home cursor instead of stacking below it.
         if (process.stdout.isTTY)
             process.stdout.write("\u001B[2J\u001B[3J\u001B[H");
         const exitCode = await runMenu({
@@ -136,7 +136,7 @@ async function runMenuMode(cwd, launch) {
         return exitCode;
     }
     catch (error) {
-        // The startup frame hid the cursor; Ink only restores it once it renders.
+        // The startup frame hid the cursor; restore it if the menu never paints.
         if (process.stdout.isTTY)
             process.stdout.write("\u001B[?25h");
         throw error;

package/dist/esm/cli/commands/dash/plan-once-attention.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Multi-run fan-out attention projection — derives HUD/attention from
+ * registry-visible runs for a plan-once set. Does not introduce a parallel store.
+ */
+import { type AttentionItem, type AttentionSource } from "#cli/commands/dash/attention.js";
+export type FanOutRunObservation = {
+    readonly runId: string;
+    readonly provider: string;
+    /** Registry / lifecycle state string (failed, running, starting, …). */
+    readonly state: string;
+    readonly error?: string | null;
+    readonly observedAt?: string;
+    readonly source?: Exclude<AttentionSource, "derived">;
+};
+export type FanOutAttentionProjection = {
+    readonly planId: string;
+    readonly total: number;
+    readonly failedCount: number;
+    readonly runningCount: number;
+    readonly items: readonly AttentionItem[];
+    /** One-line operator summary for attention strip. */
+    readonly summary: string;
+};
+/**
+ * Project multi-run fan-out state for attention/HUD consumption.
+ * Failed hosts are never dropped: they appear with inspect-failure action.
+ */
+export declare function projectFanOutAttention(input: {
+    readonly planId: string;
+    readonly runs: readonly FanOutRunObservation[];
+    readonly now?: string;
+}): FanOutAttentionProjection;

package/dist/esm/cli/commands/dash/plan-once-attention.js

@@ -0,0 +1,50 @@
+/**
+ * Multi-run fan-out attention projection — derives HUD/attention from
+ * registry-visible runs for a plan-once set. Does not introduce a parallel store.
+ */
+import { normalizeSessionState, projectAttention, } from "#cli/commands/dash/attention.js";
+/**
+ * Project multi-run fan-out state for attention/HUD consumption.
+ * Failed hosts are never dropped: they appear with inspect-failure action.
+ */
+export function projectFanOutAttention(input) {
+    const now = input.now ?? new Date().toISOString();
+    const sessions = input.runs.map((run) => normalizeSessionState({
+        runId: run.runId,
+        provider: run.provider,
+        observations: [
+            {
+                source: run.source ?? "registry",
+                value: run.state,
+                observedAt: run.observedAt ?? now,
+                confidence: "high",
+            },
+        ],
+    }));
+    const signals = new Map(input.runs.flatMap((run) => {
+        if (run.state === "failed" || run.error) {
+            return [[run.runId, { failedVerification: true }]];
+        }
+        return [];
+    }));
+    const items = projectAttention(sessions, signals);
+    const failedCount = items.filter((item) => item.state === "failed").length;
+    const runningCount = items.filter((item) => item.state === "running" || item.state === "starting").length;
+    const failureBits = items
+        .filter((item) => item.state === "failed")
+        .map((item) => {
+        const err = input.runs.find((r) => r.runId === item.runId)?.error;
+        return err ? `${item.provider}:${err}` : `${item.provider}:failed`;
+    });
+    const summary = failedCount > 0
+        ? `fan-out ${input.planId.slice(0, 8)} · ${runningCount}/${input.runs.length} ok · ${failedCount} failed · ${failureBits.join("; ")}`
+        : `fan-out ${input.planId.slice(0, 8)} · ${runningCount}/${input.runs.length} hosts · all ok`;
+    return {
+        planId: input.planId,
+        total: input.runs.length,
+        failedCount,
+        runningCount,
+        items,
+        summary,
+    };
+}

package/dist/esm/cli/commands/dash/plan-once-schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+/** Bump only with a coordinated migration; validators reject unknown versions. */
+export declare const PLAN_ONCE_SCHEMA_VERSION: 1;
+/** Agent hosts only — never fleet (fleet is a registry-derived provider, not a launch host). */
+export declare const PLAN_ONCE_HOSTS: readonly ["claude", "codex", "grok", "opencode"];
+export type PlanOnceHost = DashProvider;
+export declare const planOnceHostSchema: z.ZodEnum<{
+    claude: "claude";
+    codex: "codex";
+    grok: "grok";
+    opencode: "opencode";
+}>;
+export declare const planOnceHostEntrySchema: z.ZodObject<{
+    host: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        grok: "grok";
+        opencode: "opencode";
+    }>;
+    workdir: z.ZodString;
+    brief: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type PlanOnceHostEntry = z.infer<typeof planOnceHostEntrySchema>;
+export declare const multiHostPlanProposalSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    planId: z.ZodString;
+    hosts: z.ZodArray<z.ZodObject<{
+        host: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            grok: "grok";
+            opencode: "opencode";
+        }>;
+        workdir: z.ZodString;
+        brief: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    proposedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type MultiHostPlanProposal = z.infer<typeof multiHostPlanProposalSchema>;
+export declare const planOnceDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"confirm">;
+    planId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"cancel">;
+    planId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PlanOnceDecision = z.infer<typeof planOnceDecisionSchema>;
+export type PlanOnceValidationIssue = {
+    readonly code: "schema" | "bad-schema-version" | "empty-hosts" | "unknown-host" | "bad-workdir" | "plan-id";
+    readonly message: string;
+    readonly path?: string;
+};
+export type PlanOnceParseResult = {
+    readonly ok: true;
+    readonly plan: MultiHostPlanProposal;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PlanOnceValidationIssue[];
+};
+/** Parse + structural validate an untrusted plan proposal. */
+export declare function parseMultiHostPlanProposal(input: unknown): PlanOnceParseResult;
+export declare function parsePlanOnceDecision(input: unknown): {
+    readonly ok: true;
+    readonly decision: PlanOnceDecision;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PlanOnceValidationIssue[];
+};

package/dist/esm/cli/commands/dash/plan-once-schema.js

@@ -0,0 +1,119 @@
+/**
+ * Schema-first wire format for multi-host plan-once propose / confirm / cancel.
+ * Pure Zod surface — no I/O. Fan-out apply lives in plan-once.ts.
+ */
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { DASH_PROVIDERS } from "#cli/commands/dash/provider-capabilities.js";
+/** Bump only with a coordinated migration; validators reject unknown versions. */
+export const PLAN_ONCE_SCHEMA_VERSION = 1;
+/** Agent hosts only — never fleet (fleet is a registry-derived provider, not a launch host). */
+export const PLAN_ONCE_HOSTS = DASH_PROVIDERS;
+export const planOnceHostSchema = z.enum(PLAN_ONCE_HOSTS);
+export const planOnceHostEntrySchema = z
+    .object({
+    host: planOnceHostSchema,
+    /** Absolute workdir for this host launch. */
+    workdir: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, { message: "Plan host workdir must be absolute" }),
+    brief: z.string().min(1).optional(),
+    label: z.string().min(1).optional(),
+    /** Extra provider args after permission mode (not a free-form command bag). */
+    extraArgs: z.array(z.string()).optional(),
+})
+    .strict();
+export const multiHostPlanProposalSchema = z
+    .object({
+    schemaVersion: z.literal(PLAN_ONCE_SCHEMA_VERSION),
+    planId: z.string().uuid(),
+    hosts: z.array(planOnceHostEntrySchema).min(1),
+    proposedAt: z.string().datetime().optional(),
+})
+    .strict();
+export const planOnceDecisionSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("confirm"),
+        planId: z.string().uuid(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("cancel"),
+        planId: z.string().uuid(),
+    })
+        .strict(),
+]);
+function issueFromZod(error) {
+    return error.issues.map((item) => {
+        const path = item.path.join(".") || undefined;
+        const message = item.message;
+        if (path === "schemaVersion" || message.toLowerCase().includes("schemaversion")) {
+            return { code: "bad-schema-version", message, path };
+        }
+        if (path === "hosts" && message.toLowerCase().includes("at least")) {
+            return { code: "empty-hosts", message, path };
+        }
+        // Check workdir before host: path "hosts.0.workdir" contains the substring "host".
+        if (path?.includes("workdir") || message.toLowerCase().includes("absolute")) {
+            return { code: "bad-workdir", message, path };
+        }
+        const lastSegment = item.path[item.path.length - 1];
+        if (lastSegment === "host" || message.toLowerCase().includes("invalid enum")) {
+            return { code: "unknown-host", message, path };
+        }
+        if (path === "planId") {
+            return { code: "plan-id", message, path };
+        }
+        return { code: "schema", message, path };
+    });
+}
+/** Parse + structural validate an untrusted plan proposal. */
+export function parseMultiHostPlanProposal(input) {
+    if (input !== null &&
+        typeof input === "object" &&
+        !Array.isArray(input) &&
+        "schemaVersion" in input &&
+        input.schemaVersion !== PLAN_ONCE_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            issues: [
+                {
+                    code: "bad-schema-version",
+                    message: `Unsupported plan schemaVersion (expected ${PLAN_ONCE_SCHEMA_VERSION})`,
+                    path: "schemaVersion",
+                },
+            ],
+        };
+    }
+    const parsed = multiHostPlanProposalSchema.safeParse(input);
+    if (!parsed.success) {
+        const issues = issueFromZod(parsed.error);
+        // Empty array is a common operator mistake — ensure empty-hosts is explicit.
+        if (input !== null &&
+            typeof input === "object" &&
+            !Array.isArray(input) &&
+            Array.isArray(input.hosts) &&
+            input.hosts.length === 0 &&
+            !issues.some((i) => i.code === "empty-hosts")) {
+            return {
+                ok: false,
+                issues: [
+                    { code: "empty-hosts", message: "Plan must include at least one host", path: "hosts" },
+                    ...issues,
+                ],
+            };
+        }
+        return { ok: false, issues };
+    }
+    return { ok: true, plan: parsed.data };
+}
+export function parsePlanOnceDecision(input) {
+    const parsed = planOnceDecisionSchema.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, issues: issueFromZod(parsed.error) };
+    }
+    return { ok: true, decision: parsed.data };
+}

package/dist/esm/cli/commands/dash/plan-once.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Multi-host plan-once confirm/cancel reducers and fan-out apply.
+ *
+ * Design:
+ * - Schema-first parse lives in plan-once-schema.ts (pure).
+ * - Confirm-once: one human decision for the full host set; cancel never launches.
+ * - Fan-out reuses DashLaunchCoordinator + existing selectAgent path only.
+ * - **Registry ownership:** `DashPaneController.select` (via selectAgent) is the
+ *   sole createDashRun owner for launches. plan-once must NOT pre-create runs
+ *   (newRun + runId is rejected; dual create would orphan plan-once rows without
+ *   tmuxPaneId). After success, plan-once only **labels** the select-created run.
+ * - Per-host permission via resolveLaunchPermissionMode (no policy fork).
+ * - Concurrency: sequential (required by DashLaunchCoordinator single-pending).
+ * - Partial failure: continue remaining hosts; failed hosts reported honestly.
+ */
+import type { DashLaunchCoordinator, DashLaunchResult } from "#cli/commands/dash/launch-coordinator.js";
+import { type MultiHostPlanProposal, type PlanOnceDecision, type PlanOnceHostEntry, type PlanOnceValidationIssue } from "#cli/commands/dash/plan-once-schema.js";
+import { type DashPermissionMode, type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+import { type CreateDashRunInput } from "#cli/commands/dash/run-registry.js";
+import type { DashRun, DashRunState } from "#cli/commands/dash/run-types.js";
+export { PLAN_ONCE_SCHEMA_VERSION, parseMultiHostPlanProposal, parsePlanOnceDecision, multiHostPlanProposalSchema, planOnceDecisionSchema, type MultiHostPlanProposal, type PlanOnceDecision, type PlanOnceHostEntry, type PlanOnceValidationIssue, } from "#cli/commands/dash/plan-once-schema.js";
+/** Documented fan-out concurrency — sequential because coordinator admits one pending launch. */
+export declare const PLAN_ONCE_FANOUT_CONCURRENCY: "sequential";
+export type PlanOnceFanOutConcurrency = typeof PLAN_ONCE_FANOUT_CONCURRENCY;
+export type PlanOnceSessionStatus = "proposed" | "confirmed" | "cancelled" | "applying" | "applied" | "apply-partial" | "apply-failed";
+export type PlanOnceSession = {
+    readonly status: PlanOnceSessionStatus;
+    readonly plan: MultiHostPlanProposal;
+};
+export type PlanOnceReduceResult = {
+    readonly ok: true;
+    readonly session: PlanOnceSession;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Pure confirm-once / cancel reducer — no registry side effects. */
+export declare function createPlanOnceSession(plan: MultiHostPlanProposal): PlanOnceSession;
+export declare function reducePlanOnceDecision(session: PlanOnceSession, decision: PlanOnceDecision): PlanOnceReduceResult;
+/** Parse decision then reduce — convenience for IPC/menu handlers. */
+export declare function applyPlanOnceDecision(session: PlanOnceSession, rawDecision: unknown): PlanOnceReduceResult;
+export type FanOutHostResult = {
+    readonly host: DashProvider;
+    readonly workdir: string;
+    /** Dash run id from selectAgent (sole registry create path). */
+    readonly runId: string | null;
+    readonly status: "launched" | "failed" | "discarded";
+    readonly permissionMode: DashPermissionMode;
+    readonly command: string;
+    readonly error: string | null;
+};
+export type FanOutApplyResult = {
+    readonly planId: string;
+    readonly concurrency: PlanOnceFanOutConcurrency;
+    readonly hosts: readonly FanOutHostResult[];
+    readonly launchedCount: number;
+    readonly failedCount: number;
+    readonly discardedCount: number;
+};
+export type PlanOnceLaunchPort = {
+    launch(command: string, context?: {
+        readonly cwd?: string;
+        readonly newRun?: boolean;
+        readonly prepared?: boolean;
+        readonly provider?: DashProvider;
+        readonly argv?: readonly string[];
+        /** Never pass with newRun:true — pane-controller rejects that combo. */
+        readonly runId?: string;
+    }): Promise<DashLaunchResult>;
+};
+/**
+ * Registry port used **only** to label/update the run selectAgent already created.
+ * createRun is available for tests that simulate selectAgent; apply must not call it.
+ */
+export type PlanOnceRegistryPort = {
+    createRun(input: CreateDashRunInput): Promise<DashRun>;
+    updateRun(id: string, update: {
+        readonly state?: DashRunState;
+        readonly error?: string | null;
+        readonly label?: string | null;
+        readonly tmuxPaneId?: string | null;
+        readonly providerSessionId?: string | null;
+    }, options?: {
+        readonly cwd?: string;
+    }): Promise<DashRun>;
+};
+export type PlanOnceApplyDeps = {
+    readonly launch: PlanOnceLaunchPort;
+    readonly registry: PlanOnceRegistryPort;
+    readonly resolvePermissionMode: (args?: readonly string[], provider?: DashProvider) => DashPermissionMode;
+    /** Registry file scope (dash instance cwd). Host workdirs may differ. */
+    readonly registryCwd: string;
+};
+export declare function planOnceRunLabel(planId: string, host: PlanOnceHostEntry): string;
+/**
+ * Apply a confirmed plan: sequential fan-out through launch coordinator.
+ *
+ * Does **not** pre-create registry rows. selectAgent (pane-controller) creates
+ * exactly one dash run per host on newRun. On success, plan-once labels that run.
+ */
+export declare function applyConfirmedMultiHostPlan(input: {
+    readonly session: PlanOnceSession;
+    readonly launch: PlanOnceLaunchPort | DashLaunchCoordinator;
+    readonly registryCwd: string;
+    readonly registry?: PlanOnceRegistryPort;
+    readonly resolvePermissionMode?: PlanOnceApplyDeps["resolvePermissionMode"];
+}): Promise<{
+    readonly ok: true;
+    readonly result: FanOutApplyResult;
+    readonly session: PlanOnceSession;
+} | {
+    readonly ok: false;
+    readonly error: string;
+}>;
+/** Propose → parse helper for callers that only have untrusted JSON. */
+export declare function proposeMultiHostPlan(raw: unknown): {
+    readonly ok: true;
+    readonly session: PlanOnceSession;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PlanOnceValidationIssue[];
+};