@webpresso/agent-kit 3.1.28 → 3.2.0

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

@@ -247,22 +247,10 @@ export async function runCompile(options) {
                 message: `wp compile: rulesync exited with code ${exitCode}`,
             };
         }
-        // Step 4: Emit plugin manifests in parallel
-        const skillNames = Object.keys(assets.skills);
-        const commandNames = Object.keys(assets.commands);
-        const pkgVersion = readPackageVersion(cwd);
-        const manifestOpts = {
-            agentDir,
-            outDir: cwd,
-            version: pkgVersion,
-            skills: skillNames,
-            commands: commandNames,
-        };
-        await Promise.all([
-            import("#compiler/manifests/claude").then((m) => m.emitManifest(manifestOpts)),
-            import("#compiler/manifests/codex").then((m) => m.emitManifest(manifestOpts)),
-        ]);
-        // Step 5: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // Step 4: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // (Plugin manifests are hand-maintained SSOT under packages/*-plugin/;
+        // wp compile no longer emits them — golden tests + version stamping own
+        // that surface.)
         const agentsLayers = collectAgentsLayers(agentDir);
         if (agentsLayers.length > 0) {
             const { mergeAgentsMd } = await import("#compiler/memory/merger");
@@ -278,11 +266,9 @@ export async function runCompile(options) {
                 writeFileSync(join(cwd, "AGENTS.md"), mergeResult.content);
             }
         }
-        // Step 6: Write .compile-manifest.json with content-hash sentinels
+        // Step 5: Write .compile-manifest.json with content-hash sentinels
         const outputHashes = {
             "AGENTS.md": hashFile(join(cwd, "AGENTS.md")),
-            "packages/claude-plugin/.claude-plugin/plugin.json": hashFile(join(cwd, "packages", "claude-plugin", ".claude-plugin", "plugin.json")),
-            "packages/codex-plugin/.codex-plugin/plugin.json": hashFile(join(cwd, "packages", "codex-plugin", ".codex-plugin", "plugin.json")),
         };
         const compileManifest = {
             version: COMPILE_MANIFEST_VERSION,
@@ -303,18 +289,6 @@ export async function runCompile(options) {
         cleanup();
     }
 }
-function readPackageVersion(cwd) {
-    const pkgPath = join(cwd, "package.json");
-    if (!existsSync(pkgPath))
-        return "0.0.0";
-    try {
-        const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        return typeof parsed.version === "string" ? parsed.version : "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
 function collectAgentsLayers(agentDir) {
     const agentsDir = join(agentDir, "agents");
     if (!existsSync(agentsDir))

package/dist/esm/cli/commands/dash/delivery-status.d.ts

@@ -56,3 +56,4 @@ export type DeliveryStatusOptions = {
  * prior values and expose a retryable adapter warning.
  */
 export declare function collectDeliveryStatus(options?: DeliveryStatusOptions): Promise<DeliveryStatus>;
+export declare function blueprintDocumentPath(cwd: string, state: string, slug: string): string | null;

package/dist/esm/cli/commands/dash/delivery-status.js

@@ -107,14 +107,21 @@ function checkState(value) {
         return "pending";
     return states.length > 0 ? "passing" : "unknown";
 }
+export function blueprintDocumentPath(cwd, state, slug) {
+    const folder = join(cwd, "blueprints", state, slug, "_overview.md");
+    if (existsSync(folder))
+        return folder;
+    const flat = join(cwd, "blueprints", state, `${slug}.md`);
+    return existsSync(flat) ? flat : null;
+}
 function readBlueprintDelivery(cwd) {
     const branch = run("git", ["branch", "--show-current"], cwd);
     if (!branch?.startsWith("bp/"))
         return null;
     const slug = branch.slice(3);
     for (const state of ["in-progress", "planned", "draft", "completed", "parked", "archived"]) {
-        const path = join(cwd, "blueprints", state, slug, "_overview.md");
-        if (!existsSync(path))
+        const path = blueprintDocumentPath(cwd, state, slug);
+        if (!path)
             continue;
         const raw = readFileSync(path, "utf8");
         return {
@@ -129,8 +136,8 @@ function readVerificationDelivery(cwd) {
     const blueprint = readBlueprintDelivery(cwd);
     if (!blueprint)
         return null;
-    const path = join(cwd, "blueprints", blueprint.state, blueprint.slug, "_overview.md");
-    if (!existsSync(path))
+    const path = blueprintDocumentPath(cwd, blueprint.state, blueprint.slug);
+    if (!path)
         return null;
     const raw = readFileSync(path, "utf8");
     const evidenceCount = (raw.match(/^\*\*Verification:\*\*/gmu) ?? []).length;

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-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>;

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

@@ -0,0 +1,151 @@
+/**
+ * Durable plan-once membership (expected host set for a planId).
+ *
+ * Labels alone are not N-of-N SSOT: a host that never creates a run disappears
+ * from registry-only views. Membership is written on confirm (not cancel) and
+ * is a plan-record sidecar — not a second run-registry.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { planOnceRunLabel } from "#cli/commands/dash/plan-once-label.js";
+import { planOnceHostSchema, } from "#cli/commands/dash/plan-once-schema.js";
+import { getSurfacePathAsync, withLock } from "#paths/state-root.js";
+import { writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
+export const PLAN_MEMBERSHIP_SCHEMA_VERSION = 1;
+const MEMBERSHIP_SURFACE = "dash/plan-once-memberships.json";
+export const planMembershipHostSchema = z
+    .object({
+    host: planOnceHostSchema,
+    workdir: z.string().min(1),
+    /** Expected run label: plan-once:<planId>:<label|host> */
+    label: z.string().min(1),
+})
+    .strict();
+export const planMembershipSchema = z
+    .object({
+    schemaVersion: z.literal(PLAN_MEMBERSHIP_SCHEMA_VERSION),
+    planId: z.string().uuid(),
+    hosts: z.array(planMembershipHostSchema).min(1),
+    confirmedAt: z.string().datetime(),
+})
+    .strict();
+export const planMembershipStoreSchema = z
+    .object({
+    version: z.literal(1),
+    plans: z.record(z.string(), planMembershipSchema),
+})
+    .strict();
+function emptyStore() {
+    return { version: 1, plans: {} };
+}
+/** Pure: build immutable membership from a confirmed multi-host plan. */
+export function buildPlanMembership(plan, confirmedAt = new Date().toISOString()) {
+    const hosts = plan.hosts.map((entry) => ({
+        host: entry.host,
+        workdir: entry.workdir,
+        label: planOnceRunLabel(plan.planId, entry),
+    }));
+    return planMembershipSchema.parse({
+        schemaVersion: PLAN_MEMBERSHIP_SCHEMA_VERSION,
+        planId: plan.planId,
+        hosts,
+        confirmedAt,
+    });
+}
+async function membershipPath(cwd) {
+    return getSurfacePathAsync(MEMBERSHIP_SURFACE, "repo", cwd);
+}
+function corruptCopyPath(path) {
+    return `${path}.corrupt-${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
+}
+function preserveStore(path) {
+    if (!existsSync(path))
+        return undefined;
+    const preservedPath = corruptCopyPath(path);
+    try {
+        copyFileSync(path, preservedPath);
+        return preservedPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read membership store. Missing file → empty (ok).
+ * Corrupt/unreadable file → ok:false with quarantine path; never treat as empty
+ * for write merge (would wipe sibling plan memberships).
+ */
+function readStoreFromPath(path) {
+    if (!existsSync(path))
+        return { ok: true, store: emptyStore() };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = planMembershipStoreSchema.safeParse(raw);
+        if (parsed.success)
+            return { ok: true, store: parsed.data };
+        const preservedPath = preserveStore(path);
+        return {
+            ok: false,
+            reason: "plan membership store failed schema validation",
+            ...(preservedPath ? { preservedPath } : {}),
+        };
+    }
+    catch (error) {
+        const preservedPath = preserveStore(path);
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "plan membership store unreadable",
+            ...(preservedPath ? { preservedPath } : {}),
+        };
+    }
+}
+function storeForRead(path) {
+    const read = readStoreFromPath(path);
+    // Projection reads fail closed to empty (no memberships) without wiping disk.
+    return read.ok ? read.store : emptyStore();
+}
+/** Persist membership for a planId (idempotent overwrite for same planId). */
+export async function writePlanMembership(membership, options = {}) {
+    const validated = planMembershipSchema.parse(membership);
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const read = readStoreFromPath(path);
+        if (!read.ok) {
+            const preserved = read.preservedPath ? ` (preserved ${read.preservedPath})` : "";
+            throw new Error(`Refusing to write plan membership: store corrupt — ${read.reason}${preserved}`);
+        }
+        const next = {
+            version: 1,
+            plans: { ...read.store.plans, [validated.planId]: validated },
+        };
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonFileAtomic(path, planMembershipStoreSchema.parse(next));
+        return validated;
+    }, options.cwd);
+}
+/** Read membership for planId, or null if absent. */
+export async function readPlanMembership(planId, options = {}) {
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const store = storeForRead(path);
+        return store.plans[planId] ?? null;
+    }, options.cwd);
+}
+/** List all durable plan memberships (operator / merge projection scan). */
+export async function listPlanMemberships(options = {}) {
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const store = storeForRead(path);
+        return Object.values(store.plans);
+    }, options.cwd);
+}
+/** Test helper: clear membership store file content via rewrite empty. */
+export async function clearPlanMembershipStoreForTests(options) {
+    const path = await membershipPath(options.cwd);
+    await withLock("repo", () => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonFileAtomic(path, emptyStore());
+    }, options.cwd);
+}