@webpresso/agent-kit 3.1.28 → 3.1.30

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

@@ -0,0 +1,238 @@
+/**
+ * Merge-set projection: membership (expected hosts) + registry runs → rollup.
+ * Pure given membership + run observations — no second run store.
+ *
+ * Operator surface: summary + per-host matrix only. Git/PR auto-merge is out of
+ * scope (no silent git merge of host work).
+ */
+import { z } from "zod";
+import { projectFanOutAttention, } from "#cli/commands/dash/plan-once-attention.js";
+import { readPlanMembership, listPlanMemberships, } from "#cli/commands/dash/plan-once-membership.js";
+import { readDashRuns } from "#cli/commands/dash/run-registry.js";
+export const MERGE_ROLLUPS = ["all-ok", "partial", "all-failed", "incomplete"];
+/** Rollups that should occupy the attention strip (all-ok does not). */
+export const MERGE_ATTENTION_ROLLUPS = ["incomplete", "partial", "all-failed"];
+export const mergeRollupSchema = z.enum(MERGE_ROLLUPS);
+export const mergeHostStatusSchema = z.enum(["ok", "failed", "missing", "unknown"]);
+export const mergeHostObservationSchema = z
+    .object({
+    host: z.string().min(1),
+    workdir: z.string().min(1),
+    expectedLabel: z.string().min(1),
+    runId: z.string().nullable(),
+    state: z.string().nullable(),
+    error: z.string().nullable(),
+    status: mergeHostStatusSchema,
+})
+    .strict();
+/** Serializable subset of merge projection (attention omitted). */
+export const mergeSetCoreSchema = z
+    .object({
+    planId: z.string().uuid(),
+    expectedCount: z.number().int().nonnegative(),
+    observedCount: z.number().int().nonnegative(),
+    missingCount: z.number().int().nonnegative(),
+    failedCount: z.number().int().nonnegative(),
+    okCount: z.number().int().nonnegative(),
+    rollup: mergeRollupSchema,
+    hosts: z.array(mergeHostObservationSchema),
+})
+    .strict();
+function matchRun(expected, runs) {
+    // Exact label only — substring/prefix matching can join the wrong host when
+    // labels share prefixes and would undercount missing hosts as observed.
+    const matches = runs.filter((r) => r.label === expected.label);
+    if (matches.length === 0)
+        return undefined;
+    if (matches.length === 1)
+        return matches[0];
+    // Prefer newest when re-apply leaves multiple rows with the same label.
+    return matches.reduce((best, row) => {
+        const bestTs = best.updatedAt ?? "";
+        const rowTs = row.updatedAt ?? "";
+        return rowTs >= bestTs ? row : best;
+    });
+}
+function hostStatus(run) {
+    if (!run)
+        return "missing";
+    const state = run.state.toLowerCase();
+    if (state === "failed" || state === "error")
+        return "failed";
+    if (state === "unknown" || state === "stale")
+        return "unknown";
+    if (state === "running" ||
+        state === "starting" ||
+        state === "completed" ||
+        state === "idle" ||
+        state === "waiting" ||
+        state === "detached" ||
+        state === "stopped" ||
+        state === "archived") {
+        return "ok";
+    }
+    // Unrecognized durable state: fail-closed as unknown (not green)
+    return "unknown";
+}
+/**
+ * Project merge set from durable membership + registry-visible runs.
+ * Missing expected host → incomplete (never all-ok).
+ */
+export function projectMergeSet(input) {
+    const hosts = input.membership.hosts.map((expected) => {
+        const run = matchRun(expected, input.runs);
+        const status = hostStatus(run);
+        return {
+            host: expected.host,
+            workdir: expected.workdir,
+            expectedLabel: expected.label,
+            runId: run?.id ?? null,
+            state: run?.state ?? null,
+            error: run?.error ?? null,
+            status,
+        };
+    });
+    const missingCount = hosts.filter((h) => h.status === "missing").length;
+    const failedCount = hosts.filter((h) => h.status === "failed" || h.status === "unknown").length;
+    const okCount = hosts.filter((h) => h.status === "ok").length;
+    const observedCount = hosts.filter((h) => h.runId !== null).length;
+    let rollup;
+    if (missingCount > 0) {
+        rollup = "incomplete";
+    }
+    else if (failedCount === hosts.length && hosts.length > 0) {
+        rollup = "all-failed";
+    }
+    else if (failedCount > 0) {
+        rollup = "partial";
+    }
+    else {
+        rollup = "all-ok";
+    }
+    const attentionRuns = hosts
+        .filter((h) => h.runId)
+        .map((h) => ({
+        runId: h.runId,
+        provider: h.host,
+        state: h.state ?? "unknown",
+        error: h.error,
+    }));
+    const attention = projectFanOutAttention({
+        planId: input.membership.planId,
+        runs: attentionRuns,
+        now: input.now,
+    });
+    return {
+        planId: input.membership.planId,
+        expectedCount: hosts.length,
+        observedCount,
+        missingCount,
+        failedCount,
+        okCount,
+        rollup,
+        hosts,
+        attention,
+    };
+}
+function toMergeRunRows(runs) {
+    return runs.map((r) => ({
+        id: r.id,
+        provider: r.provider,
+        state: r.state,
+        error: r.error,
+        label: r.label,
+        updatedAt: r.updatedAt,
+    }));
+}
+/**
+ * planId → load durable membership + readDashRuns → merge projection.
+ * Uses run-registry only (no second run store). Missing membership fails closed.
+ * Includes archived runs so archived hosts do not look missing after cleanup.
+ */
+export async function projectMergeSetForPlan(planId, options = {}) {
+    const membership = await readPlanMembership(planId, { cwd: options.cwd });
+    if (!membership) {
+        return { ok: false, error: "membership-missing", planId };
+    }
+    const { runs } = await readDashRuns({ cwd: options.cwd, includeArchived: true });
+    const projection = projectMergeSet({
+        membership,
+        runs: toMergeRunRows(runs),
+        now: options.now,
+    });
+    return { ok: true, projection };
+}
+/** Project merge sets for every durable membership under the state root. */
+export async function projectAllMergeSets(options = {}) {
+    const memberships = await listPlanMemberships({ cwd: options.cwd });
+    if (memberships.length === 0)
+        return [];
+    // includeArchived: archived plan-once hosts are still N-of-N observations.
+    const { runs } = await readDashRuns({ cwd: options.cwd, includeArchived: true });
+    const rows = toMergeRunRows(runs);
+    return memberships.map((membership) => projectMergeSet({ membership, runs: rows, now: options.now }));
+}
+/** One-line operator rollup for HUD/attention strip. */
+export function formatMergeSetSummary(projection) {
+    const short = projection.planId.slice(0, 8);
+    const base = `merge ${short} · ${projection.rollup} · ${projection.okCount}/${projection.expectedCount} ok`;
+    // "all-ok" means every expected host is observed and non-failed — not that
+    // every host is terminal (running/starting still map to ok for N-of-N).
+    if (projection.rollup === "all-ok")
+        return `${base} · all observed · none failed`;
+    if (projection.missingCount > 0) {
+        const missing = projection.hosts
+            .filter((h) => h.status === "missing")
+            .map((h) => h.host)
+            .join(",");
+        return `${base} · missing ${missing}`;
+    }
+    if (projection.failedCount > 0) {
+        const failed = projection.hosts
+            .filter((h) => h.status === "failed" || h.status === "unknown")
+            .map((h) => `${h.host}:${h.error ?? h.state ?? h.status}`)
+            .join("; ");
+        return `${base} · ${failed}`;
+    }
+    return base;
+}
+/** Per-host matrix lines for operator surface. */
+export function formatMergeSetMatrix(projection) {
+    return projection.hosts.map((h) => {
+        const state = h.state ?? "—";
+        const err = h.error ? ` · ${h.error}` : "";
+        return `${h.host} · ${h.status} · ${state}${err}`;
+    });
+}
+/** Operator-visible merge surface (HUD/browser). No silent git merge. */
+export function formatMergeOperatorSurface(projection) {
+    return {
+        summary: formatMergeSetSummary(projection),
+        matrix: formatMergeSetMatrix(projection),
+        scopeNote: "git/PR auto-merge out of scope — status/summary only",
+    };
+}
+const ROLLUP_SEVERITY = {
+    incomplete: 4,
+    "all-failed": 3,
+    partial: 2,
+    "all-ok": 1,
+};
+/** Pick the highest-severity merge projection for a single attention line. */
+export function pickPrimaryMergeProjection(projections) {
+    if (projections.length === 0)
+        return null;
+    return [...projections].sort((a, b) => ROLLUP_SEVERITY[b.rollup] - ROLLUP_SEVERITY[a.rollup])[0];
+}
+/**
+ * Attention-strip line for the worst non-ok merge set.
+ * all-ok is omitted so generic per-run attention remains visible.
+ */
+export function formatPrimaryMergeAttentionLine(projections) {
+    const primary = pickPrimaryMergeProjection(projections);
+    if (!primary)
+        return null;
+    if (primary.rollup === "all-ok")
+        return null;
+    return formatMergeSetSummary(primary);
+}

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

@@ -14,11 +14,12 @@
  * - 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 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;
@@ -39,6 +40,26 @@ export declare function createPlanOnceSession(plan: MultiHostPlanProposal): Plan
 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;
@@ -91,7 +112,6 @@ export type PlanOnceApplyDeps = {
     /** 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.
  *

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

@@ -1,8 +1,10 @@
 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. */
@@ -35,6 +37,37 @@ export function applyPlanOnceDecision(session, rawDecision) {
     }
     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:
@@ -53,10 +86,6 @@ function defaultDeps(input) {
         registryCwd: input.registryCwd,
     };
 }
-export function planOnceRunLabel(planId, host) {
-    const base = host.label?.trim() || host.host;
-    return `plan-once:${planId}:${base}`;
-}
 function outcomeRunId(result) {
     const outcome = result.outcome;
     if ("runId" in outcome && typeof outcome.runId === "string" && outcome.runId.length > 0) {
@@ -80,6 +109,14 @@ export async function applyConfirmedMultiHostPlan(input) {
     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 ?? []);

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

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

@@ -0,0 +1,47 @@
+/**
+ * Control-plane interaction mode + per-host ACP capability matrix.
+ * Pure — no I/O. Missing ACP never silently omits a host.
+ */
+import { type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+export declare const CONTROL_PLANE_CHAT_MODES: readonly ["host-pane", "integrated-chat"];
+export type ControlPlaneChatMode = (typeof CONTROL_PLANE_CHAT_MODES)[number];
+export declare const DEFAULT_CONTROL_PLANE_CHAT_MODE: ControlPlaneChatMode;
+export type HostAcpCapability = {
+    readonly host: DashProvider;
+    /** True when integrated-chat transport can open for this host (hermetic or real). */
+    readonly acpAvailable: boolean;
+    /**
+     * When acpAvailable is false, honest degrade reason (required).
+     * When true, optional note about transport class.
+     */
+    readonly reason: string;
+    /** Transport class for docs/tests — hermetic fake, headless, or acp. */
+    readonly transport: "hermetic" | "headless" | "acp" | "unavailable";
+};
+/**
+ * Explicit matrix for every control-plane host. Never omit a host.
+ * MVP: Codex is hermetic-chat capable for CI; others degrade with reasons.
+ */
+export declare const HOST_ACP_CAPABILITIES: readonly HostAcpCapability[];
+export declare function hostAcpCapability(host: DashProvider): HostAcpCapability;
+/** Every host has an entry — used by tests to lock non-silent-omit. */
+export declare function projectHostAcpMatrix(): readonly HostAcpCapability[];
+export declare function isControlPlaneChatMode(value: string): value is ControlPlaneChatMode;
+export declare function formatChatModePill(mode: ControlPlaneChatMode): string;
+export declare function toggleControlPlaneChatMode(mode: ControlPlaneChatMode): ControlPlaneChatMode;
+/**
+ * Pure mode transition. Integrated-chat requires an explicit host that is ACP-capable
+ * when opening chat; switching back to host-pane always succeeds.
+ */
+export declare function reduceChatModeSwitch(input: {
+    readonly mode: ControlPlaneChatMode;
+    readonly target: ControlPlaneChatMode;
+    readonly host?: DashProvider | null;
+}): {
+    readonly ok: true;
+    readonly mode: ControlPlaneChatMode;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly mode: ControlPlaneChatMode;
+};

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

@@ -0,0 +1,98 @@
+/**
+ * Control-plane interaction mode + per-host ACP capability matrix.
+ * Pure — no I/O. Missing ACP never silently omits a host.
+ */
+import { DASH_PROVIDERS } from "#cli/commands/dash/provider-capabilities.js";
+export const CONTROL_PLANE_CHAT_MODES = ["host-pane", "integrated-chat"];
+export const DEFAULT_CONTROL_PLANE_CHAT_MODE = "host-pane";
+/**
+ * Explicit matrix for every control-plane host. Never omit a host.
+ * MVP: Codex is hermetic-chat capable for CI; others degrade with reasons.
+ */
+export const HOST_ACP_CAPABILITIES = DASH_PROVIDERS.map((host) => {
+    if (host === "codex") {
+        return {
+            host,
+            acpAvailable: true,
+            reason: "Hermetic integrated-chat adapter (MVP); real ACP optional later",
+            transport: "hermetic",
+        };
+    }
+    if (host === "claude") {
+        return {
+            host,
+            acpAvailable: false,
+            reason: "Claude ACP not wired in dash yet — use host-pane",
+            transport: "unavailable",
+        };
+    }
+    if (host === "grok") {
+        return {
+            host,
+            acpAvailable: false,
+            reason: "Grok ACP/headless chat not wired in dash yet — use host-pane",
+            transport: "unavailable",
+        };
+    }
+    return {
+        host,
+        acpAvailable: false,
+        reason: "OpenCode ACP not wired in dash yet — use host-pane",
+        transport: "unavailable",
+    };
+});
+export function hostAcpCapability(host) {
+    const row = HOST_ACP_CAPABILITIES.find((item) => item.host === host);
+    if (!row) {
+        // Should be unreachable — matrix covers DASH_PROVIDERS SSOT.
+        return {
+            host,
+            acpAvailable: false,
+            reason: `No ACP capability entry for ${host}`,
+            transport: "unavailable",
+        };
+    }
+    return row;
+}
+/** Every host has an entry — used by tests to lock non-silent-omit. */
+export function projectHostAcpMatrix() {
+    return HOST_ACP_CAPABILITIES;
+}
+export function isControlPlaneChatMode(value) {
+    return CONTROL_PLANE_CHAT_MODES.includes(value);
+}
+export function formatChatModePill(mode) {
+    return mode === "integrated-chat" ? "[chat]" : "[pane]";
+}
+export function toggleControlPlaneChatMode(mode) {
+    return mode === "host-pane" ? "integrated-chat" : "host-pane";
+}
+/**
+ * Pure mode transition. Integrated-chat requires an explicit host that is ACP-capable
+ * when opening chat; switching back to host-pane always succeeds.
+ */
+export function reduceChatModeSwitch(input) {
+    if (input.target === input.mode) {
+        return { ok: true, mode: input.mode };
+    }
+    if (input.target === "host-pane") {
+        return { ok: true, mode: "host-pane" };
+    }
+    // target integrated-chat
+    if (!input.host) {
+        return {
+            ok: false,
+            error: "Select a host session before switching to integrated chat",
+            mode: input.mode,
+        };
+    }
+    const cap = hostAcpCapability(input.host);
+    if (!cap.acpAvailable) {
+        return {
+            ok: false,
+            error: cap.reason,
+            mode: input.mode,
+        };
+    }
+    return { ok: true, mode: "integrated-chat" };
+}

package/dist/esm/cli/commands/dash/tui/frame.d.ts

@@ -3,6 +3,7 @@ import { type MenuState } from "#cli/commands/dash/menu-state.js";
 import { type PaletteCommand } from "#cli/commands/dash/tui/palette.js";
 import { type HostAvailability } from "#cli/commands/dash/tui/hosts.js";
 import type { DashPermissionMode } from "#cli/commands/dash/provider-capabilities.js";
+import { type ControlPlaneChatMode } from "#cli/commands/dash/tui/chat-mode.js";
 export type TuiOverlay = {
     readonly kind: "none";
 } | {
@@ -28,6 +29,8 @@ export type AppViewModel = {
     readonly width: number;
     readonly height: number;
     readonly permissionMode: DashPermissionMode;
+    /** host-pane (default) vs integrated-chat ACP surface */
+    readonly chatMode: ControlPlaneChatMode;
     readonly agents: readonly AgentEntry[];
     readonly menu: MenuState;
     readonly hostAvailability: readonly HostAvailability[];