@webpresso/agent-kit 3.1.26 → 3.1.30

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,142 @@
+/**
+ * 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 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";
+export { planOnceRunLabel } from "#cli/commands/dash/plan-once-label.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 ConfirmPlanOnceWithMembershipResult = {
+    readonly ok: true;
+    readonly session: PlanOnceSession;
+    /** Set when confirm succeeds and membership was written. */
+    readonly membershipWritten: boolean;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Confirm-once with durable membership write. Cancel never writes membership.
+ * Lazy-imports membership IO so pure reducers stay free of FS side effects.
+ */
+export declare function confirmPlanOnceWithMembership(input: {
+    readonly session: PlanOnceSession;
+    readonly decision: PlanOnceDecision | unknown;
+    readonly cwd?: string;
+    /** Injected for tests; default writes real membership store. */
+    readonly writeMembership?: (plan: MultiHostPlanProposal, cwd?: string) => Promise<unknown>;
+}): Promise<ConfirmPlanOnceWithMembershipResult>;
+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;
+};
+/**
+ * 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[];
+};

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

@@ -0,0 +1,261 @@
+import { resolveLaunchPermissionMode } from "#cli/commands/dash/launch-preferences.js";
+import { planOnceRunLabel } from "#cli/commands/dash/plan-once-label.js";
+import { parseMultiHostPlanProposal, parsePlanOnceDecision, } from "#cli/commands/dash/plan-once-schema.js";
+import { buildDashLaunchCommand, } from "#cli/commands/dash/provider-capabilities.js";
+import { updateDashRun } from "#cli/commands/dash/run-registry.js";
+export { PLAN_ONCE_SCHEMA_VERSION, parseMultiHostPlanProposal, parsePlanOnceDecision, multiHostPlanProposalSchema, planOnceDecisionSchema, } from "#cli/commands/dash/plan-once-schema.js";
+export { planOnceRunLabel } from "#cli/commands/dash/plan-once-label.js";
+/** Documented fan-out concurrency — sequential because coordinator admits one pending launch. */
+export const PLAN_ONCE_FANOUT_CONCURRENCY = "sequential";
+/** Pure confirm-once / cancel reducer — no registry side effects. */
+export function createPlanOnceSession(plan) {
+    return { status: "proposed", plan };
+}
+export function reducePlanOnceDecision(session, decision) {
+    if (decision.planId !== session.plan.planId) {
+        return { ok: false, error: `Decision planId ${decision.planId} does not match session plan` };
+    }
+    if (session.status !== "proposed") {
+        return {
+            ok: false,
+            error: `Cannot ${decision.kind} plan in status ${session.status} (confirm-once from proposed only)`,
+        };
+    }
+    if (decision.kind === "confirm") {
+        return { ok: true, session: { ...session, status: "confirmed" } };
+    }
+    return { ok: true, session: { ...session, status: "cancelled" } };
+}
+/** Parse decision then reduce — convenience for IPC/menu handlers. */
+export function applyPlanOnceDecision(session, rawDecision) {
+    const parsed = parsePlanOnceDecision(rawDecision);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            error: parsed.issues.map((i) => i.message).join("; ") || "Invalid plan decision",
+        };
+    }
+    return reducePlanOnceDecision(session, parsed.decision);
+}
+/**
+ * Confirm-once with durable membership write. Cancel never writes membership.
+ * Lazy-imports membership IO so pure reducers stay free of FS side effects.
+ */
+export async function confirmPlanOnceWithMembership(input) {
+    // Always schema-parse the public entrypoint (no cast-on-kind shortcut).
+    const parsed = parsePlanOnceDecision(input.decision);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            error: parsed.issues.map((i) => i.message).join("; ") || "Invalid plan decision",
+        };
+    }
+    const reduced = reducePlanOnceDecision(input.session, parsed.decision);
+    if (!reduced.ok)
+        return { ok: false, error: reduced.error };
+    if (reduced.session.status === "cancelled") {
+        return { ok: true, session: reduced.session, membershipWritten: false };
+    }
+    if (reduced.session.status !== "confirmed") {
+        return { ok: false, error: `Unexpected status after decision: ${reduced.session.status}` };
+    }
+    if (input.writeMembership) {
+        await input.writeMembership(reduced.session.plan, input.cwd);
+    }
+    else {
+        const { buildPlanMembership, writePlanMembership } = await import("#cli/commands/dash/plan-once-membership.js");
+        await writePlanMembership(buildPlanMembership(reduced.session.plan), { cwd: input.cwd });
+    }
+    return { ok: true, session: reduced.session, membershipWritten: true };
+}
+function defaultRegistryPort() {
+    // createRun is intentionally not used by apply — only updateRun for plan labels.
+    // Import createDashRun only when tests inject a full port; production update path:
+    return {
+        createRun: async () => {
+            throw new Error("plan-once apply must not createDashRun; selectAgent/pane-controller owns create");
+        },
+        updateRun: updateDashRun,
+    };
+}
+function defaultDeps(input) {
+    return {
+        launch: input.launch,
+        registry: input.registry ?? defaultRegistryPort(),
+        resolvePermissionMode: input.resolvePermissionMode ?? resolveLaunchPermissionMode,
+        registryCwd: input.registryCwd,
+    };
+}
+function outcomeRunId(result) {
+    const outcome = result.outcome;
+    if ("runId" in outcome && typeof outcome.runId === "string" && outcome.runId.length > 0) {
+        return outcome.runId;
+    }
+    return null;
+}
+/**
+ * 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 async function applyConfirmedMultiHostPlan(input) {
+    if (input.session.status !== "confirmed") {
+        return {
+            ok: false,
+            error: `Cannot apply plan in status ${input.session.status} (require confirmed)`,
+        };
+    }
+    const deps = defaultDeps(input);
+    const plan = input.session.plan;
+    const hostResults = [];
+    // Ensure durable membership exists before fan-out (idempotent). Cancel never reaches here.
+    try {
+        const { buildPlanMembership, writePlanMembership } = await import("#cli/commands/dash/plan-once-membership.js");
+        await writePlanMembership(buildPlanMembership(plan), { cwd: deps.registryCwd });
+    }
+    catch {
+        // Membership write failure does not block launch; merge may report incomplete.
+    }
+    for (const entry of plan.hosts) {
+        const permissionMode = deps.resolvePermissionMode(entry.extraArgs ?? [], entry.host);
+        const command = buildDashLaunchCommand(entry.host, permissionMode, entry.extraArgs ?? []);
+        const label = planOnceRunLabel(plan.planId, entry);
+        let launchResult;
+        try {
+            // newRun:true without runId — selectAgent owns createDashRun.
+            // prepared:true skips prepare thrash so sequential fan-out does not
+            // contend on coordinator pending Fresh.
+            launchResult = await deps.launch.launch(command, {
+                cwd: entry.workdir,
+                newRun: true,
+                prepared: true,
+                provider: entry.host,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Launch threw";
+            hostResults.push({
+                host: entry.host,
+                workdir: entry.workdir,
+                runId: null,
+                status: "failed",
+                permissionMode,
+                command,
+                error: message,
+            });
+            continue;
+        }
+        if (launchResult.kind === "launched") {
+            const runId = outcomeRunId(launchResult);
+            if (!runId) {
+                hostResults.push({
+                    host: entry.host,
+                    workdir: entry.workdir,
+                    runId: null,
+                    status: "failed",
+                    permissionMode,
+                    command,
+                    error: "selectAgent launched without dash runId (cannot label or attach)",
+                });
+                continue;
+            }
+            // Label the select-created run only — never invent a second registry row.
+            // Do not write runId into providerSessionId (that field is provider session).
+            // tmuxPaneId is already persisted by pane-controller before select returns.
+            try {
+                await deps.registry.updateRun(runId, { label, error: null }, { cwd: deps.registryCwd });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Failed to label dash run";
+                hostResults.push({
+                    host: entry.host,
+                    workdir: entry.workdir,
+                    runId,
+                    status: "failed",
+                    permissionMode,
+                    command,
+                    error: message,
+                });
+                continue;
+            }
+            hostResults.push({
+                host: entry.host,
+                workdir: entry.workdir,
+                runId,
+                status: "launched",
+                permissionMode,
+                command,
+                error: null,
+            });
+            continue;
+        }
+        if (launchResult.kind === "discarded") {
+            hostResults.push({
+                host: entry.host,
+                workdir: entry.workdir,
+                runId: null,
+                status: "discarded",
+                permissionMode,
+                command,
+                error: "launch discarded",
+            });
+            continue;
+        }
+        if (launchResult.kind === "pending") {
+            hostResults.push({
+                host: entry.host,
+                workdir: entry.workdir,
+                runId: null,
+                status: "failed",
+                permissionMode,
+                command,
+                error: launchResult.message || "Launch still pending (unexpected in sequential fan-out)",
+            });
+            continue;
+        }
+        // failed — selectAgent/pane-controller already marked its own run failed if created
+        const message = `${launchResult.message}${launchResult.action ? ` · ${launchResult.action}` : ""}`;
+        hostResults.push({
+            host: entry.host,
+            workdir: entry.workdir,
+            runId: null,
+            status: "failed",
+            permissionMode,
+            command,
+            error: message,
+        });
+    }
+    const launchedCount = hostResults.filter((h) => h.status === "launched").length;
+    const failedCount = hostResults.filter((h) => h.status === "failed").length;
+    const discardedCount = hostResults.filter((h) => h.status === "discarded").length;
+    let nextStatus;
+    if (launchedCount === hostResults.length && hostResults.length > 0) {
+        nextStatus = "applied";
+    }
+    else if (launchedCount === 0) {
+        nextStatus = "apply-failed";
+    }
+    else {
+        nextStatus = "apply-partial";
+    }
+    return {
+        ok: true,
+        result: {
+            planId: plan.planId,
+            concurrency: PLAN_ONCE_FANOUT_CONCURRENCY,
+            hosts: hostResults,
+            launchedCount,
+            failedCount,
+            discardedCount,
+        },
+        session: { ...input.session, status: nextStatus },
+    };
+}
+/** Propose → parse helper for callers that only have untrusted JSON. */
+export function proposeMultiHostPlan(raw) {
+    const parsed = parseMultiHostPlanProposal(raw);
+    if (!parsed.ok)
+        return parsed;
+    return { ok: true, session: createPlanOnceSession(parsed.plan) };
+}

package/dist/esm/cli/commands/dash/tui/attention-hud.d.ts

@@ -2,6 +2,15 @@ import { type AttentionItem } from "#cli/commands/dash/attention.js";
 import type { AgentRunStatus } from "#cli/commands/dash/pane-controller.js";
 export declare function attentionItemsFromRunStatuses(statuses: readonly AgentRunStatus[], now?: string): readonly AttentionItem[];
 export declare function formatAttentionLine(items: readonly AttentionItem[]): string | null;
+/**
+ * Prefer multi-host merge rollup when the merge line is non-null.
+ * Callers should pass a merge line only for non-all-ok rollups
+ * (`formatPrimaryMergeAttentionLine`) so all-ok does not hide live failures.
+ */
+export declare function selectAttentionLine(input: {
+    readonly mergeLine: string | null;
+    readonly genericLine: string | null;
+}): string | null;
 /** Dash-process RSS + active run count (owned tree probe is best-effort elsewhere). */
 export declare function formatResourceLine(input: {
     readonly statuses: readonly AgentRunStatus[];

package/dist/esm/cli/commands/dash/tui/attention-hud.js

@@ -1,5 +1,6 @@
 // Project session attention + process resource HUD lines for the pure TUI.
 // Uses the same normalizeSessionState / projectAttention domain as desktop.
+// Multi-host merge rollup (plan-once membership) can override the generic line.
 import { normalizeSessionState, projectAttention, } from "#cli/commands/dash/attention.js";
 import { resourceView } from "#cli/commands/dash/resources.js";
 export function attentionItemsFromRunStatuses(statuses, now = new Date().toISOString()) {
@@ -35,6 +36,14 @@ export function formatAttentionLine(items) {
         return null;
     return `attention · ${top.provider}:${top.state} · ${top.reason} · ${top.action}`;
 }
+/**
+ * Prefer multi-host merge rollup when the merge line is non-null.
+ * Callers should pass a merge line only for non-all-ok rollups
+ * (`formatPrimaryMergeAttentionLine`) so all-ok does not hide live failures.
+ */
+export function selectAttentionLine(input) {
+    return input.mergeLine ?? input.genericLine;
+}
 /** Dash-process RSS + active run count (owned tree probe is best-effort elsewhere). */
 export function formatResourceLine(input) {
     const active = input.statuses.filter((status) => status.running || status.active);

package/dist/esm/cli/commands/dash/tui/chat-bridge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Integrated-chat bridge port: hermetic fake for CI + real adapter seam.
+ * Does not create dash runs — uses existing run identity only (no second registry).
+ */
+import type { DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+export type ChatRole = "user" | "assistant" | "system";
+export type ChatMessage = {
+    readonly role: ChatRole;
+    readonly text: string;
+    readonly at: string;
+};
+export type ChatSession = {
+    readonly runId: string;
+    readonly host: DashProvider;
+    readonly label: string | null;
+    readonly messages: readonly ChatMessage[];
+};
+export type ChatBridgeResult = {
+    readonly ok: true;
+    readonly session: ChatSession;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type ChatBridge = {
+    open(input: {
+        readonly host: DashProvider;
+        readonly runId: string;
+        readonly label?: string | null;
+    }): Promise<ChatBridgeResult>;
+    send(session: ChatSession, text: string): Promise<ChatBridgeResult>;
+};
+/**
+ * Hermetic bridge: drives real send/receive entry points without live ACP.
+ * Codex is the MVP host (capability matrix); others fail with matrix reasons.
+ */
+export declare function createHermeticChatBridge(options?: {
+    readonly now?: () => string;
+}): ChatBridge;
+/** Format transcript lines for browser overlay. */
+export declare function formatChatTranscript(session: ChatSession): readonly string[];

package/dist/esm/cli/commands/dash/tui/chat-bridge.js

@@ -0,0 +1,73 @@
+import { hostAcpCapability } from "#cli/commands/dash/tui/chat-mode.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Hermetic bridge: drives real send/receive entry points without live ACP.
+ * Codex is the MVP host (capability matrix); others fail with matrix reasons.
+ */
+export function createHermeticChatBridge(options = {}) {
+    const stamp = options.now ?? nowIso;
+    return {
+        async open(input) {
+            if (!input.runId.trim()) {
+                return { ok: false, error: "runId is required (use existing dash run identity)" };
+            }
+            const cap = hostAcpCapability(input.host);
+            if (!cap.acpAvailable) {
+                return { ok: false, error: cap.reason };
+            }
+            const session = {
+                runId: input.runId,
+                host: input.host,
+                label: input.label ?? null,
+                messages: [
+                    {
+                        role: "system",
+                        text: `Integrated chat open for ${input.host} (hermetic). Host-pane remains available via mode switch.`,
+                        at: stamp(),
+                    },
+                ],
+            };
+            return { ok: true, session };
+        },
+        async send(session, text) {
+            const trimmed = text.trim();
+            if (!trimmed) {
+                return { ok: false, error: "message text is required" };
+            }
+            const cap = hostAcpCapability(session.host);
+            if (!cap.acpAvailable) {
+                return { ok: false, error: cap.reason };
+            }
+            const userMsg = { role: "user", text: trimmed, at: stamp() };
+            // Hermetic assistant echo proves receive path without live LLM.
+            const assistantMsg = {
+                role: "assistant",
+                text: `[hermetic:${session.host}] ${trimmed}`,
+                at: stamp(),
+            };
+            return {
+                ok: true,
+                session: {
+                    ...session,
+                    messages: [...session.messages, userMsg, assistantMsg],
+                },
+            };
+        },
+    };
+}
+/** Format transcript lines for browser overlay. */
+export function formatChatTranscript(session) {
+    const header = [
+        `chat · ${session.host} · run ${session.runId.slice(0, 8)}`,
+        session.label ? `label · ${session.label}` : null,
+        "scope · integrated-chat (host-pane available via mode switch)",
+        "─".repeat(40),
+    ].filter((line) => line !== null);
+    const body = session.messages.map((msg) => {
+        const tag = msg.role === "user" ? "you" : msg.role === "assistant" ? "host" : "sys";
+        return `${tag} · ${msg.text}`;
+    });
+    return [...header, ...body];
+}