@zswarm/core 0.1.0

package/dist/ops/tail.js

@@ -0,0 +1,59 @@
+import { DEFAULT_DUMP_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, truncateDumpText, } from "./util.js";
+/**
+ * What is new in `cur` given the previously seen screen. The viewport scrolls,
+ * so the old bottom shows up as the new top: find the longest suffix of the
+ * previous screen that still heads the current one, and return the rest.
+ */
+export function diffScreens(prev, cur) {
+    if (prev === null)
+        return { text: cur, reset: true };
+    if (cur === prev)
+        return { text: "", reset: false };
+    if (cur.startsWith(prev))
+        return { text: cur.slice(prev.length), reset: false };
+    const prevLines = prev.split("\n");
+    const curLines = cur.split("\n");
+    for (let skip = 1; skip < prevLines.length; skip++) {
+        const overlap = prevLines.slice(skip);
+        if (overlap.length > curLines.length)
+            continue;
+        if (curLines.slice(0, overlap.length).join("\n") === overlap.join("\n")) {
+            return { text: curLines.slice(overlap.length).join("\n"), reset: false };
+        }
+    }
+    // Nothing lines up — the pane redrew itself.
+    return { text: cur, reset: true };
+}
+export function cursorKey(session, paneId) {
+    return `${session}:${paneId}`;
+}
+/** Read only what a pane printed since the last tail. */
+export async function tailPane(client, state, args, target) {
+    const { session, pane } = target;
+    const key = cursorKey(session, pane.id);
+    if (isTrue(args.reset))
+        state.clearCursor(key);
+    const dumped = await client.dumpPane({
+        session,
+        paneId: pane.id,
+        full: isTrue(args.full),
+    });
+    const screen = normalizeScreen(dumped.text);
+    const previous = state.readCursor(key);
+    const diff = diffScreens(previous, screen);
+    state.writeCursor(key, screen);
+    const max = dumpMaxChars(args, DEFAULT_DUMP_MAX_CHARS);
+    const clipped = truncateDumpText(diff.text, max);
+    return {
+        ok: true,
+        data: {
+            session,
+            to: pane.id,
+            text: clipped.text,
+            reset: diff.reset,
+            fresh: diff.text.length > 0,
+            truncated: clipped.truncated,
+            chars: clipped.chars,
+        },
+    };
+}

package/dist/ops/types.d.ts

@@ -0,0 +1,26 @@
+export type OpsResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+import type { GitClient } from "../git.js";
+import type { Policy } from "../policy.js";
+import type { StateStore } from "../state.js";
+/** Injectable clock, git, state, and policy so timing/IO ops stay testable. */
+export type DispatchDeps = {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    git?: GitClient;
+    state?: StateStore;
+    policy?: Policy;
+    env?: NodeJS.ProcessEnv;
+};
+export type Clock = {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+};

package/dist/ops/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ops/util.d.ts

@@ -0,0 +1,48 @@
+import type { ZellijPane } from "../zellij/panes.js";
+import type { OpsResult } from "./types.js";
+/** Default dump text budget (characters). Override with max=; max=0 disables. */
+export declare const DEFAULT_DUMP_MAX_CHARS = 8000;
+/** `wait` returns a short tail by default — it is called in loops. */
+export declare const DEFAULT_WAIT_MAX_CHARS = 2000;
+export declare function fail(err: unknown): OpsResult;
+export declare function isTrue(value: unknown): boolean;
+export declare function isVerbose(args: Record<string, unknown>): boolean;
+export declare function optionalString(value: unknown): string | null;
+export declare function paneViewSlim(p: ZellijPane): {
+    id: string;
+    title: string;
+    command: string | null;
+    tab: string | null;
+};
+/**
+ * The event-bus view. Zellij's pane manifest carries no command, so the key is
+ * left out rather than reported as null — absent means unknown, not none.
+ */
+export declare function paneViewBus(p: ZellijPane): {
+    id: string;
+    title: string;
+    tab: string | null;
+};
+export declare function paneViewFull(p: ZellijPane): {
+    cwd: string | null;
+    focused: boolean;
+    exited: boolean;
+    floating: boolean;
+    id: string;
+    title: string;
+    command: string | null;
+    tab: string | null;
+};
+/** Truncate dump text; default keeps the tail (recent output). */
+export declare function truncateDumpText(text: string, maxChars: number, keep?: "tail" | "head"): {
+    text: string;
+    truncated: boolean;
+    chars: number;
+};
+/** Screen text with trailing blanks removed, so idle detection ignores padding. */
+export declare function normalizeScreen(text: string): string;
+export declare function numberArg(args: Record<string, unknown>, key: string, fallback: number, limits: {
+    min: number;
+    max: number;
+}): number;
+export declare function dumpMaxChars(args: Record<string, unknown>, fallback?: number): number;

package/dist/ops/util.js

@@ -0,0 +1,85 @@
+import { ZellijError } from "../errors.js";
+/** Default dump text budget (characters). Override with max=; max=0 disables. */
+export const DEFAULT_DUMP_MAX_CHARS = 8_000;
+/** `wait` returns a short tail by default — it is called in loops. */
+export const DEFAULT_WAIT_MAX_CHARS = 2_000;
+export function fail(err) {
+    if (err instanceof ZellijError) {
+        return { ok: false, error: { code: err.code, message: err.message } };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { code: "failed", message } };
+}
+export function isTrue(value) {
+    return value === true || value === "true";
+}
+export function isVerbose(args) {
+    return isTrue(args.verbose);
+}
+export function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+export function paneViewSlim(p) {
+    return {
+        id: p.id,
+        title: p.title,
+        command: p.command ?? null,
+        tab: p.tabName ?? null,
+    };
+}
+/**
+ * The event-bus view. Zellij's pane manifest carries no command, so the key is
+ * left out rather than reported as null — absent means unknown, not none.
+ */
+export function paneViewBus(p) {
+    return { id: p.id, title: p.title, tab: p.tabName ?? null };
+}
+export function paneViewFull(p) {
+    return {
+        ...paneViewSlim(p),
+        cwd: p.cwd ?? null,
+        focused: p.focused,
+        exited: p.exited,
+        floating: p.floating,
+    };
+}
+/** Truncate dump text; default keeps the tail (recent output). */
+export function truncateDumpText(text, maxChars, keep = "tail") {
+    const chars = text.length;
+    if (maxChars <= 0 || chars <= maxChars) {
+        return { text, truncated: false, chars };
+    }
+    if (keep === "head") {
+        return { text: text.slice(0, maxChars), truncated: true, chars };
+    }
+    return { text: text.slice(chars - maxChars), truncated: true, chars };
+}
+/** Screen text with trailing blanks removed, so idle detection ignores padding. */
+export function normalizeScreen(text) {
+    return text
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .join("\n")
+        .replace(/\n+$/, "");
+}
+export function numberArg(args, key, fallback, limits) {
+    const raw = args[key];
+    if (raw === undefined || raw === null || raw === "")
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+        throw new ZellijError("bad_arg", `${key} must be a number`);
+    }
+    return Math.min(limits.max, Math.max(limits.min, Math.floor(n)));
+}
+export function dumpMaxChars(args, fallback = DEFAULT_DUMP_MAX_CHARS) {
+    if (args.max === undefined || args.max === null || args.max === "") {
+        return fallback;
+    }
+    const n = Number(args.max);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new ZellijError("bad_max", "max must be a non-negative number");
+    }
+    return Math.floor(n);
+}

package/dist/ops/wait.d.ts

@@ -0,0 +1,19 @@
+import type { ZellijClient } from "../zellij/client.js";
+import type { BusWait } from "../zellij/bus.js";
+import type { ZellijPane } from "../zellij/panes.js";
+import type { Clock, OpsResult } from "./types.js";
+export declare function buildMatcher(args: Record<string, unknown>): ((text: string) => boolean) | null;
+/** Held-pipe wait answer, shaped by `parseWaitReply` in `zellij/bus.ts`. */
+export type { BusWait };
+/**
+ * Poll a pane's screen until it goes quiet, prints a match, or the deadline
+ * passes — so callers stop re-dumping in a loop of their own.
+ *
+ * `waitViaBus`, when provided, is one held pipe covering the whole wait.
+ * Null (plugin missing or silent) falls back to dump-screen polling. The
+ * pipe's own timeout belongs to the transport; this op does not cap it.
+ */
+export declare function waitForPane(client: ZellijClient, target: {
+    session: string;
+    pane: ZellijPane;
+}, args: Record<string, unknown>, clock: Clock, waitViaBus?: () => Promise<BusWait | null>): Promise<OpsResult>;

package/dist/ops/wait.js

@@ -0,0 +1,138 @@
+import { ZellijError } from "../errors.js";
+import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, truncateDumpText, } from "./util.js";
+const WAIT_DEFAULTS = {
+    idleMs: 2_000,
+    pollMs: 150,
+    timeoutMs: 60_000,
+};
+const WAIT_LIMITS = {
+    idleMs: { min: 200, max: 600_000 },
+    pollMs: { min: 50, max: 30_000 },
+    timeoutMs: { min: 1_000, max: 900_000 },
+};
+export function buildMatcher(args) {
+    const match = optionalString(args.match);
+    if (!match)
+        return null;
+    if (isTrue(args.regex)) {
+        try {
+            const re = new RegExp(match, isTrue(args.ignoreCase) ? "im" : "m");
+            return (text) => re.test(text);
+        }
+        catch (err) {
+            throw new ZellijError("bad_match", `invalid regex: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (isTrue(args.ignoreCase)) {
+        const needle = match.toLowerCase();
+        return (text) => text.toLowerCase().includes(needle);
+    }
+    return (text) => text.includes(match);
+}
+function waitResult(reason, ctx) {
+    const max = dumpMaxChars(ctx.args, DEFAULT_WAIT_MAX_CHARS);
+    const clipped = truncateDumpText(ctx.text, max);
+    return {
+        ok: true,
+        data: {
+            session: ctx.session,
+            to: ctx.pane.id,
+            reason,
+            elapsedMs: ctx.at - ctx.started,
+            polls: ctx.polls,
+            changes: ctx.changes,
+            idleMs: ctx.idleMs,
+            text: clipped.text,
+            truncated: clipped.truncated,
+            chars: clipped.chars,
+        },
+    };
+}
+/**
+ * Poll a pane's screen until it goes quiet, prints a match, or the deadline
+ * passes — so callers stop re-dumping in a loop of their own.
+ *
+ * `waitViaBus`, when provided, is one held pipe covering the whole wait.
+ * Null (plugin missing or silent) falls back to dump-screen polling. The
+ * pipe's own timeout belongs to the transport; this op does not cap it.
+ */
+export async function waitForPane(client, target, args, clock, waitViaBus) {
+    const { session, pane } = target;
+    const matcher = buildMatcher(args);
+    const requested = optionalString(args.for) ?? (matcher ? "match" : "idle");
+    if (!["idle", "match", "either"].includes(requested)) {
+        throw new ZellijError("bad_arg", "for must be idle|match|either");
+    }
+    if (requested !== "idle" && !matcher) {
+        throw new ZellijError("missing_match", `for=${requested} needs match=`);
+    }
+    const wantMatch = requested !== "idle";
+    const wantIdle = requested !== "match";
+    const idleMs = numberArg(args, "idleMs", WAIT_DEFAULTS.idleMs, WAIT_LIMITS.idleMs);
+    const pollMs = numberArg(args, "pollMs", WAIT_DEFAULTS.pollMs, WAIT_LIMITS.pollMs);
+    const timeoutMs = numberArg(args, "timeoutMs", WAIT_DEFAULTS.timeoutMs, WAIT_LIMITS.timeoutMs);
+    const started = clock.now();
+    if (waitViaBus) {
+        const reply = await waitViaBus();
+        // `gone` is filtered upstream: a pane that vanished mid-wait is reported by
+        // the polling path, which has the error message for it.
+        if (reply && reply.reason !== "gone") {
+            const at = clock.now();
+            return waitResult(reply.reason, {
+                session,
+                pane,
+                text: reply.screen,
+                args,
+                started,
+                at,
+                polls: 1,
+                changes: 0,
+                idleMs,
+            });
+        }
+    }
+    let previous = null;
+    let lastChangeAt = started;
+    let polls = 0;
+    let changes = 0;
+    for (;;) {
+        const dumped = await client.dumpPane({
+            session,
+            paneId: pane.id,
+            full: isTrue(args.full),
+        });
+        polls++;
+        const text = dumped.text;
+        const screen = normalizeScreen(text);
+        const at = clock.now();
+        const ctx = {
+            session,
+            pane,
+            text,
+            args,
+            started,
+            at,
+            polls,
+            changes,
+            idleMs,
+        };
+        if (wantMatch && matcher && matcher(screen))
+            return waitResult("match", ctx);
+        if (previous === null) {
+            previous = screen;
+            lastChangeAt = at;
+        }
+        else if (screen !== previous) {
+            previous = screen;
+            lastChangeAt = at;
+            changes++;
+            ctx.changes = changes;
+        }
+        else if (wantIdle && at - lastChangeAt >= idleMs) {
+            return waitResult("idle", ctx);
+        }
+        if (at - started >= timeoutMs)
+            return waitResult("timeout", ctx);
+        await clock.sleep(pollMs);
+    }
+}

package/dist/ops/worktree.d.ts

@@ -0,0 +1,21 @@
+import { type GitClient } from "../git.js";
+import type { ZellijClient } from "../zellij/client.js";
+import type { OpsResult } from "./types.js";
+export type PeerWorktree = {
+    path: string;
+    branch: string;
+    root: string;
+    created: boolean;
+};
+/**
+ * Give a peer its own branch and working directory. Reuses the worktree when
+ * one already sits at the target path, so spawn stays idempotent.
+ */
+export declare function ensurePeerWorktree(git: GitClient, args: Record<string, unknown>, env?: NodeJS.ProcessEnv): Promise<PeerWorktree>;
+/** List the repo's worktrees, annotated with the panes working in each. */
+export declare function listPeerWorktrees(git: GitClient, client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+/**
+ * Remove a worktree. Refuses the main worktree, a worktree a pane is still
+ * working in, and one with uncommitted changes — `force` overrides the last two.
+ */
+export declare function removePeerWorktree(git: GitClient, client: ZellijClient, args: Record<string, unknown>, env?: NodeJS.ProcessEnv): Promise<OpsResult>;

package/dist/ops/worktree.js

@@ -0,0 +1,144 @@
+import { isAbsolute, join } from "node:path";
+import { ZellijError } from "../errors.js";
+import { defaultWorktreeRoot, normalizeRepoPath, worktreeDirName, } from "../git.js";
+import { isTrue, optionalString } from "./util.js";
+function startDir(args) {
+    return optionalString(args.cwd) ?? process.cwd();
+}
+function worktreeRootFor(args, repoRoot, env) {
+    const explicit = optionalString(args.worktreeRoot) ??
+        (env.ZSWARM_WORKTREE_ROOT?.trim() || null);
+    if (!explicit)
+        return defaultWorktreeRoot(repoRoot);
+    return isAbsolute(explicit) ? explicit : join(repoRoot, explicit);
+}
+function findByPath(trees, path) {
+    const wanted = normalizeRepoPath(path);
+    return trees.find((t) => normalizeRepoPath(t.path) === wanted) ?? null;
+}
+/** Panes whose cwd sits inside a worktree — the agents that would lose the floor. */
+function panesIn(panes, path) {
+    const prefix = `${normalizeRepoPath(path)}/`;
+    return panes
+        .filter((p) => {
+        if (!p.cwd)
+            return false;
+        const cwd = `${normalizeRepoPath(p.cwd)}/`;
+        return cwd === prefix || cwd.startsWith(prefix);
+    })
+        .map((p) => p.id);
+}
+/**
+ * Give a peer its own branch and working directory. Reuses the worktree when
+ * one already sits at the target path, so spawn stays idempotent.
+ */
+export async function ensurePeerWorktree(git, args, env = process.env) {
+    const branch = optionalString(args.worktree);
+    if (!branch) {
+        throw new ZellijError("bad_arg", "worktree must be a branch name");
+    }
+    const repoRoot = await git.repoRoot(startDir(args));
+    const path = join(worktreeRootFor(args, repoRoot, env), worktreeDirName(branch));
+    const existing = findByPath(await git.listWorktrees(repoRoot), path);
+    if (existing) {
+        if (existing.branch && existing.branch !== branch) {
+            throw new ZellijError("worktree_conflict", `${path} already holds branch ${existing.branch}, not ${branch}`);
+        }
+        return { path: existing.path, branch, root: repoRoot, created: false };
+    }
+    await git.addWorktree({
+        root: repoRoot,
+        path,
+        branch,
+        baseRef: optionalString(args.baseRef),
+        createBranch: !(await git.branchExists(repoRoot, branch)),
+    });
+    return { path, branch, root: repoRoot, created: true };
+}
+/** List the repo's worktrees, annotated with the panes working in each. */
+export async function listPeerWorktrees(git, client, args) {
+    const repoRoot = await git.repoRoot(startDir(args));
+    const trees = await git.listWorktrees(repoRoot);
+    let panes = [];
+    try {
+        const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+        panes = await client.listPanes(session);
+    }
+    catch {
+        // Worktrees are useful to list even with no live Zellij session.
+    }
+    return {
+        ok: true,
+        data: {
+            repo: repoRoot,
+            worktrees: trees.map((t) => ({
+                path: t.path,
+                branch: t.branch,
+                main: normalizeRepoPath(t.path) === normalizeRepoPath(repoRoot),
+                detached: t.detached,
+                locked: t.locked,
+                panes: panesIn(panes, t.path),
+            })),
+        },
+    };
+}
+/**
+ * Remove a worktree. Refuses the main worktree, a worktree a pane is still
+ * working in, and one with uncommitted changes — `force` overrides the last two.
+ */
+export async function removePeerWorktree(git, client, args, env = process.env) {
+    const repoRoot = await git.repoRoot(startDir(args));
+    const trees = await git.listWorktrees(repoRoot);
+    const force = isTrue(args.force);
+    const wantedPath = optionalString(args.path);
+    const wantedBranch = optionalString(args.branch) ?? optionalString(args.worktree);
+    if (!wantedPath && !wantedBranch) {
+        throw new ZellijError("missing_target", "path or branch required");
+    }
+    let target = null;
+    if (wantedPath) {
+        const abs = isAbsolute(wantedPath)
+            ? wantedPath
+            : join(worktreeRootFor(args, repoRoot, env), wantedPath);
+        target = findByPath(trees, abs) ?? findByPath(trees, wantedPath);
+    }
+    else if (wantedBranch) {
+        const matches = trees.filter((t) => t.branch === wantedBranch);
+        if (matches.length > 1) {
+            throw new ZellijError("worktree_ambiguous", `multiple worktrees on branch ${wantedBranch}; pass path=`);
+        }
+        target = matches[0] ?? null;
+    }
+    if (!target) {
+        throw new ZellijError("worktree_not_found", `no worktree for ${wantedPath ?? wantedBranch}`);
+    }
+    if (normalizeRepoPath(target.path) === normalizeRepoPath(repoRoot)) {
+        throw new ZellijError("worktree_is_main", "refusing to remove the main worktree");
+    }
+    let occupants = [];
+    try {
+        const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+        occupants = panesIn(await client.listPanes(session), target.path);
+    }
+    catch {
+        // No live session means nobody is working in it.
+    }
+    if (occupants.length > 0 && !force) {
+        throw new ZellijError("worktree_busy", `${occupants.join(", ")} still working in ${target.path}; close the pane or pass force=true`);
+    }
+    const dirty = await git.isDirty(target.path);
+    if (dirty && !force) {
+        throw new ZellijError("worktree_dirty", `${target.path} has uncommitted changes; commit them or pass force=true`);
+    }
+    await git.removeWorktree({ root: repoRoot, path: target.path, force });
+    return {
+        ok: true,
+        data: {
+            repo: repoRoot,
+            removed: target.path,
+            branch: target.branch,
+            wasDirty: dirty,
+            evicted: occupants,
+        },
+    };
+}

package/dist/policy.d.ts

@@ -0,0 +1,15 @@
+export type Policy = {
+    readOnly: boolean;
+    allowPanes: string[] | null;
+    denyPanes: string[];
+    allowSpawn: boolean;
+    allowClose: boolean;
+    allowWorktreeRemove: boolean;
+};
+export declare function loadPolicy(env?: NodeJS.ProcessEnv): Policy;
+export declare function isWriteOp(op: string): boolean;
+export declare function assertOpAllowed(policy: Policy, op: string): void;
+export declare function assertPaneAllowed(policy: Policy, pane: {
+    id: string;
+    title: string;
+}, op: string): void;

package/dist/policy.js

@@ -0,0 +1,75 @@
+import { ZellijError } from "./errors.js";
+const WRITE_OPS = new Set([
+    "send",
+    "broadcast",
+    "keys",
+    "interrupt",
+    "spawn",
+    "close",
+    "unworktree",
+]);
+/** Explicit disable tokens for ZSWARM_ALLOW_* switches. */
+function isDisabled(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v === "0" || v === "false" || v === "no";
+}
+/** Affirmative tokens for ZSWARM_READONLY. */
+function isEnabled(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+function parseList(raw) {
+    const text = (raw ?? "").trim();
+    if (!text)
+        return [];
+    return text
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function loadPolicy(env = process.env) {
+    const allowRaw = (env.ZSWARM_ALLOW_PANES ?? "").trim();
+    return {
+        readOnly: isEnabled(env.ZSWARM_READONLY),
+        allowPanes: allowRaw ? parseList(allowRaw) : null,
+        denyPanes: parseList(env.ZSWARM_DENY_PANES),
+        allowSpawn: !isDisabled(env.ZSWARM_ALLOW_SPAWN),
+        allowClose: !isDisabled(env.ZSWARM_ALLOW_CLOSE),
+        allowWorktreeRemove: !isDisabled(env.ZSWARM_ALLOW_WORKTREE_REMOVE),
+    };
+}
+export function isWriteOp(op) {
+    return WRITE_OPS.has(op);
+}
+function deny(envVar, detail) {
+    throw new ZellijError("policy_denied", `${detail}; denied by ${envVar}`);
+}
+export function assertOpAllowed(policy, op) {
+    if (policy.readOnly && isWriteOp(op)) {
+        deny("ZSWARM_READONLY", `op "${op}" is a write`);
+    }
+    if (op === "spawn" && !policy.allowSpawn) {
+        deny("ZSWARM_ALLOW_SPAWN", `op "spawn" disabled`);
+    }
+    if (op === "close" && !policy.allowClose) {
+        deny("ZSWARM_ALLOW_CLOSE", `op "close" disabled`);
+    }
+    if (op === "unworktree" && !policy.allowWorktreeRemove) {
+        deny("ZSWARM_ALLOW_WORKTREE_REMOVE", `op "unworktree" disabled`);
+    }
+}
+function paneMatches(entry, pane) {
+    if (pane.id === entry)
+        return true;
+    const needle = entry.toLowerCase();
+    return pane.title.toLowerCase().includes(needle);
+}
+export function assertPaneAllowed(policy, pane, op) {
+    if (policy.denyPanes.some((entry) => paneMatches(entry, pane))) {
+        deny("ZSWARM_DENY_PANES", `op "${op}" on pane ${pane.id} ("${pane.title}")`);
+    }
+    if (policy.allowPanes !== null &&
+        !policy.allowPanes.some((entry) => paneMatches(entry, pane))) {
+        deny("ZSWARM_ALLOW_PANES", `op "${op}" on pane ${pane.id} ("${pane.title}") not in allowlist`);
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One description of the zswarm surface. The MCP tool schema, the CLI flags,
+ * and the CLI help text are all generated from it, so they cannot drift apart.
+ */
+export declare const OP_NAMES: readonly ["list", "sessions", "send", "broadcast", "dump", "tail", "wait", "status", "keys", "interrupt", "spawn", "close", "worktrees", "unworktree", "signal", "signals", "await", "log", "rename", "focus", "tabs", "layout", "stack", "diff", "checkpoint", "bus"];
+export type OpName = (typeof OP_NAMES)[number];
+/** Ops that address an existing pane through `to`. */
+export declare const TARGET_OPS: readonly OpName[];
+export type ParamType = "string" | "number" | "boolean" | "stringOrArray";
+export type ParamSpec = {
+    name: string;
+    type: ParamType;
+    /** CLI flags; empty means the parameter is reachable through MCP only. */
+    flags: string[];
+    /** Repeatable flags collect into an array (`--key a --key b`). */
+    repeat?: boolean;
+    values?: readonly string[];
+    description: string;
+};
+export declare const PARAMS: readonly ParamSpec[];
+/** JSON Schema for the single `zswarm` MCP tool. */
+export declare function mcpInputSchema(): Record<string, unknown>;
+export declare const MCP_TOOL_DESCRIPTION: string;
+export declare function cliUsage(): string;
+/** Turn argv (without the op) into dispatch args, driven by PARAMS. */
+export declare function parseCliArgv(argv: string[]): Record<string, unknown>;