@zswarm/core 0.1.5 → 0.1.7

package/dist/ops/spawn.js

@@ -1,97 +1,163 @@
 import { ZellijError } from "../errors.js";
 import { createGitClient } from "../git.js";
 import { tokenizeCommand } from "../keys.js";
-import { isTrue, isVerbose, optionalString, paneViewFull } from "./util.js";
+import { isTrue, isVerbose, numberArg, optionalString, paneViewFull, throwIfAborted } from "./util.js";
+import { observationBudget } from "./observation.js";
 import { ensurePeerWorktree } from "./worktree.js";
 function paneDirection(value) {
-    const dir = optionalString(value);
+    const dir = optionalString(value)?.toLowerCase();
     if (!dir)
         return null;
-    const lowered = dir.toLowerCase();
-    if (!["right", "left", "up", "down"].includes(lowered)) {
+    if (!["right", "left", "up", "down"].includes(dir)) {
         throw new ZellijError("bad_arg", "direction must be right|left|up|down");
     }
-    return lowered;
+    return dir;
 }
-/** Open a new pane (or tab) and report which pane it became. */
-export async function spawnPane(client, args, git) {
-    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+/** Create exactly once. Only observations are retried, never the create action. */
+export async function spawnPane(client, args, git, clock = { now: Date.now, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) }, signal) {
+    const started = clock.now();
+    const budget = observationBudget(clock, numberArg(args, "timeoutMs", 30_000, { min: 1, max: 900_000 }), signal);
+    const observeMs = numberArg(args, "observeMs", 3_000, { min: 0, max: 30_000 });
     const command = tokenizeCommand(args.command ?? args.cmd);
-    // A worktree peer works on its own branch, in its own directory.
+    const direction = paneDirection(args.direction);
+    const newTab = isTrue(args.newTab) || args.tab === true;
+    const { session } = await client.resolveSession(optionalString(args.session), budget.require());
     const worktree = optionalString(args.worktree)
         ? await ensurePeerWorktree(git ?? createGitClient(), args)
         : null;
     const cwd = worktree ? worktree.path : optionalString(args.cwd);
     const name = optionalString(args.name) ?? worktree?.branch ?? null;
-    const closeOnExit = isTrue(args.closeOnExit);
-    const before = new Set((await client.listPanes(session)).map((p) => p.id));
+    const beforePanes = await client.listPanes(session, budget.require(), { fresh: true });
+    const before = new Set(beforePanes.map((p) => p.id));
     let paneId = null;
     let tabId = null;
-    if (isTrue(args.newTab) || args.tab === true) {
-        const created = await client.newTab({
-            session,
-            command,
-            cwd,
-            name,
-            layout: optionalString(args.layout),
-            closeOnExit,
-        });
-        tabId = created.tabId;
+    let tabSource = newTab ? "created" : "explicit";
+    if (newTab) {
+        tabId = (await client.newTab({
+            session, command, cwd, name, layout: optionalString(args.layout),
+            closeOnExit: isTrue(args.closeOnExit), timeoutMs: budget.require(),
+        })).tabId;
     }
     else {
         const input = {
-            session,
-            command,
-            cwd,
-            name,
-            direction: paneDirection(args.direction),
-            floating: isTrue(args.floating),
-            closeOnExit,
-            width: optionalString(args.width),
-            height: optionalString(args.height),
+            session, command, cwd, name, direction, floating: isTrue(args.floating),
+            closeOnExit: isTrue(args.closeOnExit),
+            width: optionalString(args.width), height: optionalString(args.height),
         };
-        if (typeof args.tabId === "number")
-            input.tabId = args.tabId;
-        // `tab` as a name places the pane in that tab; ids come via tabId.
         const tabName = optionalString(args.tab);
-        if (input.tabId === undefined && tabName) {
-            input.tabId = client.resolveTab(await client.listTabs(session), tabName).id;
+        if (typeof args.tabId === "number") {
+            tabId = args.tabId;
         }
+        else if (tabName) {
+            tabId = client.resolveTab(await client.listTabs(session, budget.require(), { fresh: true }), tabName).id;
+        }
+        else {
+            // Address a tab explicitly even when no viewer is attached.
+            const focused = beforePanes.find((p) => p.focused && p.tabId != null);
+            const first = beforePanes.find((p) => !p.isPlugin && p.tabId != null);
+            tabId = focused?.tabId ?? first?.tabId ?? null;
+            tabSource = focused ? "focused-pane" : "first-tab";
+            if (tabId === null) {
+                const tabs = await client.listTabs(session, budget.require(), { fresh: true });
+                tabId = [...tabs].sort((a, b) => a.position - b.position)[0]?.id ?? null;
+            }
+            if (tabId === null)
+                throw new ZellijError("tab_not_found", "no tab for spawn; use --new-tab");
+        }
+        input.tabId = tabId;
+        input.timeoutMs = budget.require();
         paneId = (await client.newPane(input)).paneId;
     }
-    // new-tab reports a tab id, and a command that exits at once can vanish, so
-    // fall back to diffing the pane list against the pre-spawn snapshot.
-    const panes = await client.listPanes(session);
-    let resolvedBy = paneId
-        ? "stdout"
-        : "unresolved";
-    let pane = paneId ? (panes.find((p) => p.id === paneId) ?? null) : null;
-    if (!paneId) {
-        const fresh = panes.filter((p) => !p.isPlugin && !before.has(p.id));
-        const inTab = tabId === null ? fresh : fresh.filter((p) => p.tabId === tabId);
-        const candidates = inTab.length > 0 ? inTab : fresh;
-        if (candidates.length === 1) {
-            pane = candidates[0];
-            paneId = pane.id;
-            resolvedBy = "diff";
+    const observedUntil = Math.min(budget.deadline, clock.now() + observeMs);
+    let pane = null;
+    let resolvedBy = paneId ? "stdout" : "unresolved";
+    let observation = "timeout";
+    let diagnostic;
+    let renameAttempted = false;
+    let aliasObserved = !name;
+    const candidatesSeen = new Set();
+    let firstRead = true;
+    let candidateId = null;
+    try {
+        while (budget.remaining() > 0 && (firstRead || clock.now() < observedUntil)) {
+            firstRead = false;
+            try {
+                const left = observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, observedUntil - clock.now()));
+                const panes = await client.listPanes(session, left, { fresh: true });
+                throwIfAborted(signal);
+                if (paneId) {
+                    pane = panes.find((p) => p.id === paneId && !p.isPlugin) ?? null;
+                }
+                else if (newTab && tabId !== null) {
+                    const candidates = panes.filter((p) => !p.isPlugin && !before.has(p.id) && p.tabId === tabId);
+                    for (const candidate of candidates)
+                        candidatesSeen.add(candidate.id);
+                    if (candidatesSeen.size === 1 && candidates.length === 1) {
+                        const candidate = candidates[0];
+                        // A second observation catches a layout whose panes arrive in
+                        // separate manifests. Never lock onto its first partial snapshot.
+                        if (candidateId === candidate.id) {
+                            pane = candidate;
+                            paneId = pane.id;
+                            resolvedBy = "tab";
+                        }
+                        candidateId = candidate.id;
+                    }
+                    else if (candidatesSeen.size > 1) {
+                        observation = "ambiguous";
+                        break;
+                    }
+                }
+                else {
+                    // A global before/after diff cannot identify our concurrent creation.
+                    observation = "unresolved";
+                    break;
+                }
+                if (pane) {
+                    aliasObserved = !name || pane.title === name;
+                    if (!aliasObserved && !renameAttempted) {
+                        renameAttempted = true;
+                        await client.renamePane({ session, paneId: pane.id, name: name, timeoutMs: observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, observedUntil - clock.now())) });
+                        throwIfAborted(signal);
+                    }
+                    else if (aliasObserved) {
+                        observation = "observed";
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                throwIfAborted(signal);
+                if (err instanceof ZellijError && err.code === "cancelled")
+                    throw err;
+                diagnostic = err instanceof Error ? err.message : String(err);
+            }
+            if (observeMs === 0 || clock.now() >= observedUntil)
+                break;
+            await budget.pause(observedUntil);
+        }
+    }
+    catch (err) {
+        if (signal?.aborted || (err instanceof ZellijError && err.code === "cancelled")) {
+            return { ok: false, error: {
+                    code: "cancelled", message: "spawn was acknowledged; observation cancelled",
+                    details: { session, paneId, tabId, created: true },
+                } };
         }
+        throw err;
     }
     const data = {
-        session,
-        paneId,
-        resolvedBy,
-        live: pane !== null,
-        command: command.length > 0 ? command : null,
+        session, paneId, tabId, tabSource, resolvedBy, created: true,
+        observed: pane !== null, exited: pane?.exited ?? null,
+        live: pane !== null && !pane.exited,
+        ready: pane?.exited ? false : "unknown",
+        observation: { status: observation, elapsedMs: clock.now() - started, ...(diagnostic ? { diagnostic } : {}) },
+        command: command.length ? command : null,
     };
-    if (worktree) {
-        data.worktree = {
-            path: worktree.path,
-            branch: worktree.branch,
-            created: worktree.created,
-        };
-    }
-    if (tabId !== null)
-        data.tabId = tabId;
+    if (name)
+        data.alias = { name, observed: aliasObserved };
+    if (worktree)
+        data.worktree = { path: worktree.path, branch: worktree.branch, created: worktree.created };
     if (pane && isVerbose(args))
         data.pane = paneViewFull(pane);
     return { ok: true, data };

package/dist/ops/status.d.ts

@@ -3,7 +3,7 @@ import type { ZellijClient } from "../zellij/client.js";
 import type { ZellijPane } from "../zellij/panes.js";
 import type { Clock, OpsResult } from "./types.js";
 /** `running` only appears when sampling is off — busy and idle are indistinguishable then. */
-export type PeerState = "busy" | "waiting" | "idle" | "exited" | "running";
+export type PeerState = "busy" | "waiting" | "idle" | "exited" | "running" | "unknown";
 /** Pane list already in hand, so status does not re-fetch what the caller has. */
 export type StatusSource = {
     session: string;
@@ -12,25 +12,50 @@ export type StatusSource = {
     /**
      * Batched screen reader. Returns null when it cannot serve the whole set, and
      * status falls back to one `dump-screen` per pane.
+     * `timeoutMs` is the remaining overall status budget.
      */
-    readScreens?: (paneIds: string[]) => Promise<Map<string, string> | null>;
+    readScreens?: (paneIds: string[], timeoutMs: number) => Promise<Map<string, string> | null>;
     /** "Has this moved since you last asked?", answered without a sample gap. */
-    readChanged?: (paneIds: string[]) => Promise<Map<string, {
+    readChanged?: (paneIds: string[], timeoutMs: number) => Promise<Map<string, {
         changed: boolean;
         first: boolean;
         screen: string;
     }> | null>;
 };
+/** Default overall budget for a sampled status pass (covers IPC + dumps). */
+export declare const DEFAULT_STATUS_TIMEOUT_MS = 30000;
+/** How many dump-screen calls to run at once on the direct (non-bus) path. */
+export declare const STATUS_DUMP_CONCURRENCY = 3;
 export declare function lastLine(screen: string): string;
+export type WaitingEvidence = {
+    reason: "approval_menu" | "prompt";
+    evidence: string;
+    source: "screen";
+};
+export declare function waitingPrompt(screen: string, profile?: HarnessProfile | null): WaitingEvidence | null;
+/** Compact summary of the selected terminal peers, including inactive tabs. */
+export declare function statusTabs(peers: Record<string, unknown>[]): {
+    id: unknown;
+    name: unknown;
+    panes: number;
+    states: Record<string, number>;
+}[];
 export declare function classify(input: {
     exited: boolean;
     before: string;
     after: string;
-    /** The pane's harness; its waiting patterns name the prompts worth blocking on. */
     profile?: HarnessProfile | null;
 }): PeerState;
+/** Run `fn` over items with at most `limit` in flight. */
+export declare function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 /**
  * Sample every pane twice and say who is working, who is stuck on a prompt,
  * and who is free — the routing question `list` cannot answer.
+ *
+ * `deadlineAt` is the absolute clock deadline for the whole status op (setup
+ * included). When omitted, one is derived from `timeoutMs` at entry.
  */
-export declare function peerStatus(client: ZellijClient, args: Record<string, unknown>, clock: Clock, supplied?: StatusSource | null): Promise<OpsResult>;
+export declare function peerStatus(client: ZellijClient, args: Record<string, unknown>, clock: Clock, supplied?: StatusSource | null, opts?: {
+    deadlineAt?: number;
+    signal?: AbortSignal;
+}): Promise<OpsResult>;