@webpresso/agent-kit 3.1.26 → 3.1.30

package/dist/esm/cli/commands/blueprint/mutations.js

@@ -161,6 +161,31 @@ async function reIngestDb(cwd) {
         return;
     await reIngestProjection(cwd);
 }
+/**
+ * Force reingest of one blueprint document even when the stored content hash
+ * still matches. Used on complete so task-table lag cannot block finalize.
+ */
+async function forceReIngestBlueprint(cwd, slug, documentPath) {
+    const target = dbPath(cwd);
+    if (!existsSync(target))
+        return;
+    try {
+        const conn = openDb(target);
+        try {
+            // Invalidate hash so ingestAll's skip-if-unchanged path rewrites tasks.
+            conn.db.prepare(`UPDATE blueprints SET content_hash = NULL WHERE slug = ?`).run(slug);
+        }
+        finally {
+            conn.close();
+        }
+        await reIngestProjection(cwd);
+    }
+    catch {
+        // Projection is best-effort for complete; markdown gate already passed.
+        // Swallow so a broken local projection cannot block lifecycle completion.
+        void documentPath;
+    }
+}
 /**
  * Update `status:` in YAML frontmatter. Preserves everything else verbatim.
  */
@@ -306,7 +331,12 @@ async function promoteBlueprintLocked(cwd, slug, toState) {
         throw new Error(`Blueprint "${slug}" not found in any state directory under ${blueprintRoot}`);
     }
     const { dir: currentDir, documentPath: currentDocumentPath, shape, state: currentState } = found;
-    // Guard: refuse to complete if any tasks are not done/dropped
+    // Guard: refuse to complete if any tasks are not done/dropped.
+    // Markdown `_overview.md` is SSOT for task status + verification evidence.
+    // The projection DB is derived and can lag when agents edit task Status
+    // blocks without going through `task complete` (hash-skipping reingest then
+    // leaves stale todo rows). Do not fail completion on projection lag —
+    // reingest after the markdown gate so consumers see fresh rows.
     if (toState === "completed") {
         const markdown = readFileSync(currentDocumentPath, "utf8");
         const blueprint = parseBlueprint(markdown, slug);
@@ -319,23 +349,10 @@ async function promoteBlueprintLocked(cwd, slug, toState) {
             throw new Error(`Cannot promote "${slug}" to completed: the following tasks are not done/dropped: ${list}`);
         }
         assertAllTasksHaveCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status === "done").map((task) => task.id));
-        const target = dbPath(cwd);
-        if (existsSync(target)) {
-            const conn = openDb(target);
-            let openTasks;
-            try {
-                openTasks = conn.db
-                    .prepare(`SELECT task_id, status FROM tasks WHERE blueprint_slug = ? AND status NOT IN ('done', 'dropped')`)
-                    .all(slug);
-            }
-            finally {
-                conn.close();
-            }
-            if (openTasks.length > 0) {
-                const list = openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ");
-                throw new Error(`Cannot promote "${slug}" to completed: the following tasks are not done: ${list}`);
-            }
-        }
+        // Best-effort projection refresh. Clear content hash first so a lagging
+        // tasks table is rewritten even when a prior corrupt UPDATE left the
+        // stored hash equal to current markdown.
+        await forceReIngestBlueprint(cwd, slug, currentDocumentPath);
     }
     // Platform freshness must be resolved before trust validation so the proof
     // applies to the current replica, not stale local markdown.

package/dist/esm/cli/commands/blueprint/router.js

@@ -5,7 +5,9 @@ import { parseBlueprintForDb } from "#db/parser/blueprint-db-parser";
 import { blueprintToSpecKit } from "#export/spec-kit/index";
 import { getProjectRoot } from "#cli/utils";
 import { commandExists as defaultCommandExists } from "#runtime/command-exists.js";
-import { clearBlueprintWorktreeOwnership, ensureBlueprintOwnerWorktree, } from "#worktrees/manager.js";
+import { adoptBlueprintOwnerWorktree, clearBlueprintWorktreeOwnership, ensureBlueprintOwnerWorktree, } from "#worktrees/manager.js";
+import { resolveCurrentManagedWorktreeContext } from "#worktrees/current.js";
+import { canonicalizeWorktreePath, WORKTREE_PROBE_TIMEOUT_MS } from "#worktrees/identity.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
 import { applyBlueprintLifecycleToFile, BlueprintCreationService, BlueprintService, complexitySchema, relativeBlueprintSlug, parseBlueprint, planStatusSchema, runBlueprintAudit, resolveBlueprintFile, serializeBlueprint, validateAllTasksDone, } from "#local";
@@ -392,7 +394,16 @@ export async function startBlueprint(slug, options = {}) {
     if (source.blueprint.status !== "planned") {
         throw new Error(`Blueprint ${source.slug} must be planned before start (current: ${source.blueprint.status}).`);
     }
-    const binding = ensureBlueprintOwnerWorktree(projectRoot, relativeBlueprintSlug(slug));
+    const relativeSlug = relativeBlueprintSlug(slug);
+    const currentManaged = resolveCurrentManagedWorktreeContext(projectRoot);
+    const canonicalProjectRoot = canonicalizeWorktreePath(projectRoot);
+    const currentBranch = readCurrentGitBranch(projectRoot);
+    const binding = currentManaged &&
+        currentManaged.kind === "owner" &&
+        currentManaged.worktreePath === canonicalProjectRoot &&
+        currentBranch === `bp/${relativeSlug}`
+        ? adoptBlueprintOwnerWorktree(currentManaged.repoRoot, relativeSlug, currentManaged.worktreePath)
+        : ensureBlueprintOwnerWorktree(projectRoot, relativeSlug);
     const result = await applyLifecycleMutation(slug, {
         type: "start",
         worktreeOwnerId: binding.id,
@@ -404,6 +415,20 @@ export async function startBlueprint(slug, options = {}) {
         ownerWorktreePath: binding.path,
     };
 }
+function readCurrentGitBranch(cwd) {
+    try {
+        const branch = execFileSync("git", ["branch", "--show-current"], {
+            cwd,
+            encoding: "utf8",
+            timeout: WORKTREE_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function parkBlueprint(slug, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     const result = await applyLifecycleMutation(slug, { type: "park" }, projectRoot);

package/dist/esm/cli/commands/ci.d.ts

@@ -2,12 +2,14 @@ import type { CAC } from "cac";
 import type { SecretGateCommandOptions, SecretGateRunResult } from "#secret-gate/runner.js";
 import { type CiActEventName, type CiActExecutionMode } from "#ci/act-runner.js";
 export declare const DEFAULT_CI_ACT_TIMEOUT_MS: number;
+export declare const SMOKE_CI_ACT_TIMEOUT_MS = 30000;
 export declare const MAX_CI_ACT_TIMEOUT_MS: number;
 export declare const CI_COMMAND_HELP: string;
 export interface CiActOptions {
     readonly workflow?: string;
     readonly workflowPath?: string;
     readonly job?: string;
+    readonly matrix?: readonly string[];
     readonly eventName?: CiActEventName;
     readonly eventPath?: string;
     readonly envProfile?: string;
@@ -17,6 +19,7 @@ export interface CiActOptions {
     readonly platformImage?: string;
     readonly execute?: boolean;
     readonly timeoutMs?: number;
+    readonly smoke?: boolean;
 }
 export interface CiCommandConfig {
     readonly command: string;
@@ -32,5 +35,9 @@ export declare function registerCiCommand(cli: CAC): void;
 export declare function buildCiActCommand(options?: CiActOptions, cwd?: string): CiCommandConfig;
 export declare function validateCiActCommand(..._legacyArgs: readonly unknown[]): string | null;
 export declare function runCiActCommand(options?: CiActOptions, deps?: CiCommandDeps): Promise<number>;
-export declare function normalizeCiActTimeoutMs(value: number | undefined): number;
+export declare function normalizeCiActTimeoutMs(value: number | undefined, options?: {
+    readonly smoke?: boolean;
+}): number;
 export declare function parseCiActTimeoutMs(value: unknown): number | undefined;
+export declare function parseCiActExecutionMode(value: unknown): CiActExecutionMode | undefined;
+export declare function parseCiActEventName(value: unknown): CiActEventName | undefined;

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

@@ -1,7 +1,8 @@
-import { buildPublicCiActCommand, resolveCiActExecutionMode, sanitizePublicCiActArgv, } from "#ci/act-runner.js";
+import { buildPublicCiActCommand, preparePublicCiActExecution, resolveCiActExecutionMode, resolveCiActSecretEnvProfile, sanitizePublicCiActArgv, shouldForceCiActSecretGate, } from "#ci/act-runner.js";
 import { redactText } from "#mcp/tools/_shared/redact.js";
 import { runSecretGateCommand } from "#secret-gate/runner.js";
 export const DEFAULT_CI_ACT_TIMEOUT_MS = 20 * 60_000;
+export const SMOKE_CI_ACT_TIMEOUT_MS = 30_000;
 export const MAX_CI_ACT_TIMEOUT_MS = 60 * 60_000;
 export const CI_COMMAND_HELP = [
     "Run repository CI helpers through the portable, secret-safe wp surface.",
@@ -10,6 +11,8 @@ export const CI_COMMAND_HELP = [
     "Examples:",
     "  wp ci act --workflow ci-e2e",
     "  wp ci act --workflow ci-e2e --execute",
+    "  wp ci act --workflow ci-e2e --execute --smoke",
+    "  wp ci act --workflow ci-e2e --job test --matrix target:beta",
     "  wp ci act --workflow-path .github/workflows/ci.yml --job test",
 ].join("\n");
 export function registerCiCommand(cli) {
@@ -20,6 +23,7 @@ export function registerCiCommand(cli) {
     })
         .option("--workflow-path <path>", "Explicit workflow file path")
         .option("--job <id>", "Workflow job id")
+        .option("--matrix <key:value>", "Run only matching act matrix selector(s) (repeatable)")
         .option("--event-name <name>", "act event name: pull_request | push | workflow_dispatch")
         .option("--event-path <path>", "Use an existing event JSON file")
         .option("--env-profile <profile>", "Secret-gate runtime profile", { default: "secrets-only" })
@@ -28,6 +32,7 @@ export function registerCiCommand(cli) {
         .option("--container-architecture <arch>", "act container architecture override")
         .option("--platform-image <image>", "act runner image for ubicloud-standard-2")
         .option("--timeout-ms <ms>", `act execution timeout in milliseconds (default: ${DEFAULT_CI_ACT_TIMEOUT_MS})`)
+        .option("--smoke", `Use a short ${SMOKE_CI_ACT_TIMEOUT_MS}ms timeout for targeted local proof`)
         .option("--execute", "Run act; default is a redacted dry-run preview")
         .option("--dry-run", "Print the resolved command without executing it")
         .action((action, flags) => {
@@ -39,14 +44,16 @@ export function registerCiCommand(cli) {
             workflow: flags.workflow,
             workflowPath: flags.workflowPath,
             job: flags.job,
-            eventName: flags.eventName,
+            matrix: parseCiActMatrixFlags(flags.matrix),
+            eventName: parseCiActEventName(flags.eventName),
             envProfile: flags.envProfile,
             secretProfile: flags.secretProfile,
-            mode: flags.mode,
+            mode: parseCiActExecutionMode(flags.mode),
             containerArchitecture: flags.containerArchitecture,
             platformImage: flags.platformImage,
             eventPath: flags.eventPath,
             execute: Boolean(flags.execute) && !flags.dryRun,
+            smoke: Boolean(flags.smoke),
             timeoutMs: parseCiActTimeoutMs(flags.timeoutMs),
         });
     });
@@ -60,8 +67,8 @@ export function validateCiActCommand(..._legacyArgs) {
 }
 export async function runCiActCommand(options = {}, deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
-    const command = buildPublicCiActCommand({ ...options, cwd });
     if (!options.execute) {
+        const command = buildPublicCiActCommand({ ...options, cwd });
         const preview = sanitizePublicCiActArgv(command);
         (deps.stdout ?? process.stdout).write(`${JSON.stringify({ command: preview.command, args: preview.args })}\n`);
         return 0;
@@ -69,23 +76,34 @@ export async function runCiActCommand(options = {}, deps = {}) {
     if (resolveCiActExecutionMode(options) === "replay") {
         (deps.stderr ?? process.stderr).write("Warning: replay mode is a generated local approximation and is not security-equivalent to GitHub CI or OIDC.\n");
     }
-    const result = await (deps.run ?? runSecretGateCommand)({
-        cwd,
-        envProfile: "none",
-        command: command.command,
-        args: command.args,
-        timeoutMs: normalizeCiActTimeoutMs(options.timeoutMs),
-    });
-    const stdout = redactText(result.stdout) ?? "";
-    const stderr = redactText(result.stderr) ?? "";
-    if (stdout)
-        (deps.stdout ?? process.stdout).write(stdout);
-    if (stderr)
-        (deps.stderr ?? process.stderr).write(stderr);
-    return result.exitCode;
+    const prepared = preparePublicCiActExecution({ ...options, cwd });
+    try {
+        const secretProfile = resolveCiActSecretEnvProfile({ ...options, cwd }) ?? "preview";
+        const result = await (deps.run ?? runSecretGateCommand)({
+            cwd,
+            commandCwd: prepared.cwd,
+            sink: "act",
+            profile: secretProfile,
+            envProfile: options.envProfile ?? "secrets-only",
+            forceSecretGate: shouldForceCiActSecretGate(options.envProfile),
+            command: "act",
+            args: prepared.command.actArgs,
+            timeoutMs: normalizeCiActTimeoutMs(options.timeoutMs, { smoke: options.smoke }),
+        });
+        const stdout = redactText(result.stdout) ?? "";
+        const stderr = redactText(result.stderr) ?? "";
+        if (stdout)
+            (deps.stdout ?? process.stdout).write(stdout);
+        if (stderr)
+            (deps.stderr ?? process.stderr).write(stderr);
+        return result.exitCode;
+    }
+    finally {
+        prepared.cleanup();
+    }
 }
-export function normalizeCiActTimeoutMs(value) {
-    const timeoutMs = value ?? DEFAULT_CI_ACT_TIMEOUT_MS;
+export function normalizeCiActTimeoutMs(value, options = {}) {
+    const timeoutMs = value ?? (options.smoke ? SMOKE_CI_ACT_TIMEOUT_MS : DEFAULT_CI_ACT_TIMEOUT_MS);
     if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
         throw new Error("--timeout-ms must be a positive integer");
     }
@@ -100,7 +118,48 @@ export function parseCiActTimeoutMs(value) {
     const parsed = typeof value === "number"
         ? value
         : typeof value === "string"
-            ? Number.parseInt(value, 10)
+            ? parseCiActTimeoutString(value)
             : Number.NaN;
     return normalizeCiActTimeoutMs(parsed);
 }
+export function parseCiActExecutionMode(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (value === "direct" || value === "replay")
+        return value;
+    throw new Error('--mode must be "direct" or "replay"');
+}
+export function parseCiActEventName(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (value === "pull_request" || value === "push" || value === "workflow_dispatch")
+        return value;
+    throw new Error('--event-name must be "pull_request", "push", or "workflow_dispatch"');
+}
+function parseCiActTimeoutString(value) {
+    const trimmed = value.trim();
+    if (!/^[1-9]\d*$/u.test(trimmed)) {
+        throw new Error("--timeout-ms must be a positive integer");
+    }
+    return Number(trimmed);
+}
+function parseCiActMatrixFlags(value) {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string") {
+        if (value.trim().length === 0) {
+            throw new Error("--matrix must be provided as one or more key:value selectors");
+        }
+        return [value];
+    }
+    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+        if (value.some((entry) => entry.trim().length === 0)) {
+            throw new Error("--matrix must be provided as one or more key:value selectors");
+        }
+        return [...value];
+    }
+    if (value === true) {
+        throw new Error("--matrix must be provided as one or more key:value selectors");
+    }
+    throw new Error("--matrix must be provided as one or more key:value selectors");
+}

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/keymap.js

@@ -27,6 +27,7 @@ const MENU_BINDINGS = [
     { keys: "x", label: "actions", footerPriority: 0 },
     { keys: "⇥/^s", label: "sessions" },
     { keys: "b", label: "blueprints" },
+    { keys: "c", label: "chat" },
     { keys: "d/^o", label: "mode" },
     { keys: "^p", label: "palette", footerPriority: 1 },
     { keys: "?/^x", label: "help" },

package/dist/esm/cli/commands/dash/launch-preferences.d.ts

@@ -1,7 +1,9 @@
 import { type DashPermissionMode, type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+import { type ControlPlaneChatMode } from "#cli/commands/dash/tui/chat-mode.js";
 export type LaunchPreferences = {
     readonly version: number;
     readonly yolo: boolean;
+    readonly chatMode?: ControlPlaneChatMode;
 };
 export type YoloPreferenceState = {
     readonly enabled: boolean;
@@ -9,9 +11,22 @@ export type YoloPreferenceState = {
     /** The preference file exists but could not be parsed (fails safe to off). */
     readonly corrupt: boolean;
 };
+export type ChatModePreferenceState = {
+    readonly mode: ControlPlaneChatMode;
+    readonly persisted: boolean;
+    /** The preference file exists but could not be parsed (fails safe to host-pane). */
+    readonly corrupt: boolean;
+};
 export declare function readYoloPreferenceState(): YoloPreferenceState;
 export declare function readYoloPreference(): boolean;
 export declare function writeYoloPreference(enabled: boolean): void;
+/**
+ * Read persisted control-plane chat mode. Missing, corrupt, or invalid values
+ * fail safe to host-pane (never open integrated-chat chrome from bad prefs).
+ */
+export declare function readChatModePreferenceState(): ChatModePreferenceState;
+export declare function readChatModePreference(): ControlPlaneChatMode;
+export declare function writeChatModePreference(mode: ControlPlaneChatMode): void;
 /**
  * Precedence: explicit `--wp-permission-mode` > provider-native permission flags
  * already in args > persisted yolo (true → 'dangerous') > 'safe'. When `provider`

package/dist/esm/cli/commands/dash/launch-preferences.js

@@ -1,12 +1,12 @@
-// User-scope persistence for the personal "yolo" launch preference. This is a
-// per-user risk choice (like ~/.codex/config.toml), deliberately NOT the tracked
-// .webpressorc.json — a repo file would let one contributor flip teammates into
-// bypass via git pull. The file lives under the env-paths state root and any
-// corrupt/missing read fails safe (yolo off).
+// User-scope persistence for personal dash launch preferences (yolo + chat mode).
+// Deliberately NOT the tracked .webpressorc.json — a repo file would let one
+// contributor flip teammates into bypass via git pull. The file lives under the
+// env-paths state root; corrupt/missing reads fail safe (yolo off, host-pane).
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { hasProviderNativePermissionFlag, parseDashPermissionMode, } from "#cli/commands/dash/provider-capabilities.js";
+import { DEFAULT_CONTROL_PLANE_CHAT_MODE, isControlPlaneChatMode, } from "#cli/commands/dash/tui/chat-mode.js";
 import { getStateRoot } from "#paths/state-root.js";
 const LAUNCH_PREFERENCES_FILENAME = "launch-preferences.json";
 const LAUNCH_PREFERENCES_VERSION = 1;
@@ -31,6 +31,23 @@ function readRawPreferences() {
         return null;
     }
 }
+/** Atomic read-merge-write so unknown fields survive partial updates. */
+function writePreferencesPatch(patch) {
+    const path = launchPreferencesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // A corrupt existing file is discarded (readRawPreferences → null).
+    const existing = readRawPreferences() ?? {};
+    const payload = { ...existing, version: LAUNCH_PREFERENCES_VERSION, ...patch };
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+        renameSync(tmpPath, path);
+    }
+    catch (error) {
+        rmSync(tmpPath, { force: true });
+        throw error;
+    }
+}
 export function readYoloPreferenceState() {
     const path = launchPreferencesPath();
     if (!existsSync(path))
@@ -44,21 +61,33 @@ export function readYoloPreference() {
     return readYoloPreferenceState().enabled;
 }
 export function writeYoloPreference(enabled) {
+    writePreferencesPatch({ yolo: enabled });
+}
+/**
+ * Read persisted control-plane chat mode. Missing, corrupt, or invalid values
+ * fail safe to host-pane (never open integrated-chat chrome from bad prefs).
+ */
+export function readChatModePreferenceState() {
     const path = launchPreferencesPath();
-    mkdirSync(dirname(path), { recursive: true });
-    // Read-merge-write so unknown fields written by a newer wp survive an older
-    // wp's toggle. A corrupt existing file is discarded (readRawPreferences → null).
-    const existing = readRawPreferences() ?? {};
-    const payload = { ...existing, version: LAUNCH_PREFERENCES_VERSION, yolo: enabled };
-    const tmpPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
-    try {
-        writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-        renameSync(tmpPath, path);
+    if (!existsSync(path)) {
+        return { mode: DEFAULT_CONTROL_PLANE_CHAT_MODE, persisted: false, corrupt: false };
     }
-    catch (error) {
-        rmSync(tmpPath, { force: true });
-        throw error;
+    const raw = readRawPreferences();
+    if (raw === null) {
+        return { mode: DEFAULT_CONTROL_PLANE_CHAT_MODE, persisted: false, corrupt: true };
     }
+    const value = raw.chatMode;
+    if (typeof value === "string" && isControlPlaneChatMode(value)) {
+        return { mode: value, persisted: true, corrupt: false };
+    }
+    // File present but chatMode absent or invalid — not corrupt JSON.
+    return { mode: DEFAULT_CONTROL_PLANE_CHAT_MODE, persisted: true, corrupt: false };
+}
+export function readChatModePreference() {
+    return readChatModePreferenceState().mode;
+}
+export function writeChatModePreference(mode) {
+    writePreferencesPatch({ chatMode: mode });
 }
 /**
  * Precedence: explicit `--wp-permission-mode` > provider-native permission flags

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-label.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared plan-once run label contract.
+ * Exact equality is SSOT for membership ↔ registry join; keep one helper.
+ */
+import type { PlanOnceHostEntry } from "#cli/commands/dash/plan-once-schema.js";
+/** Durable run label: `plan-once:<planId>:<label|host>`. */
+export declare function planOnceRunLabel(planId: string, host: PlanOnceHostEntry): string;

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

@@ -0,0 +1,5 @@
+/** Durable run label: `plan-once:<planId>:<label|host>`. */
+export function planOnceRunLabel(planId, host) {
+    const base = host.label?.trim() || host.host;
+    return `plan-once:${planId}:${base}`;
+}

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

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { type MultiHostPlanProposal } from "#cli/commands/dash/plan-once-schema.js";
+export declare const PLAN_MEMBERSHIP_SCHEMA_VERSION: 1;
+export declare const planMembershipHostSchema: z.ZodObject<{
+    host: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        grok: "grok";
+        opencode: "opencode";
+    }>;
+    workdir: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+export type PlanMembershipHost = z.infer<typeof planMembershipHostSchema>;
+export declare const planMembershipSchema: 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;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+    confirmedAt: z.ZodString;
+}, z.core.$strict>;
+export type PlanMembership = z.infer<typeof planMembershipSchema>;
+export declare const planMembershipStoreSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    plans: z.ZodRecord<z.ZodString, 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;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        confirmedAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PlanMembershipStore = z.infer<typeof planMembershipStoreSchema>;
+/** Pure: build immutable membership from a confirmed multi-host plan. */
+export declare function buildPlanMembership(plan: MultiHostPlanProposal, confirmedAt?: string): PlanMembership;
+/** Persist membership for a planId (idempotent overwrite for same planId). */
+export declare function writePlanMembership(membership: PlanMembership, options?: {
+    readonly cwd?: string;
+}): Promise<PlanMembership>;
+/** Read membership for planId, or null if absent. */
+export declare function readPlanMembership(planId: string, options?: {
+    readonly cwd?: string;
+}): Promise<PlanMembership | null>;
+/** List all durable plan memberships (operator / merge projection scan). */
+export declare function listPlanMemberships(options?: {
+    readonly cwd?: string;
+}): Promise<readonly PlanMembership[]>;
+/** Test helper: clear membership store file content via rewrite empty. */
+export declare function clearPlanMembershipStoreForTests(options: {
+    readonly cwd?: string;
+}): Promise<void>;