@zswarm/core 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export { buildServeTaskScript, DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLog
 export { allocateLoopbackPort, assertSafeSshTunnelOpts, buildSshTunnelArgv, createServeTunnelManager, DEFAULT_SSH_PORT, DEFAULT_SSH_SERVE_PORT, describeServeTarget, formatSshServeTarget, forwardServe, isSshServeTarget, parseSshServeTarget, redactSshUserinfo, serveTunnelCacheKey, SSH_SERVE_REMOTE_HOST, SSH_TUNNEL_KEEPALIVE_COUNT, SSH_TUNNEL_KEEPALIVE_INTERVAL_S, stripControllerRouting, type AcquireServeTunnelOptions, type ParsedSshServeTarget, type ServeTunnelHandle, type ServeTunnelManager, type ServeTunnelManagerOptions, } from "./ops/serve-tunnel.js";
 export { parseTabList, resolveTab, type ZellijTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
+export { originFromServeRequest, originSuffix, resolveSenderOrigin, sanitizeOriginPart, type SenderOrigin, } from "./ops/delivery.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, type PeerState, } from "./ops/status.js";
 export { normalizeScreen, unfoldScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";

package/dist/index.js

@@ -24,6 +24,7 @@ export { buildServeTaskScript, DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLog
 export { allocateLoopbackPort, assertSafeSshTunnelOpts, buildSshTunnelArgv, createServeTunnelManager, DEFAULT_SSH_PORT, DEFAULT_SSH_SERVE_PORT, describeServeTarget, formatSshServeTarget, forwardServe, isSshServeTarget, parseSshServeTarget, redactSshUserinfo, serveTunnelCacheKey, SSH_SERVE_REMOTE_HOST, SSH_TUNNEL_KEEPALIVE_COUNT, SSH_TUNNEL_KEEPALIVE_INTERVAL_S, stripControllerRouting, } from "./ops/serve-tunnel.js";
 export { parseTabList, resolveTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
+export { originFromServeRequest, originSuffix, resolveSenderOrigin, sanitizeOriginPart, } from "./ops/delivery.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, } from "./ops/status.js";
 export { normalizeScreen, unfoldScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";

package/dist/ops/delivery.d.ts

@@ -4,6 +4,41 @@ import type { ZellijClient } from "../zellij/client.js";
 import type { ZellijPane } from "../zellij/panes.js";
 import type { Clock } from "./types.js";
 export type Submitted = boolean | "queued" | "unverified" | "not-delivered";
+/**
+ * Where a message came from: the sending machine, the sender's Zellij session
+ * and pane, and whether this host received the op over `serve`. Every part is
+ * optional so an older caller (or a host with no Zellij env) still works.
+ */
+export type SenderOrigin = {
+    /** Sending machine. */
+    host: string | null;
+    /** Sender's Zellij session. */
+    session: string | null;
+    /** Sender's pane id, e.g. "terminal_3". */
+    pane: string | null;
+    /** "serve" only when this host received the op over serve. */
+    via: "serve" | null;
+};
+/**
+ * Clean one origin part for the `[zswarm from=…]` header: non-strings and
+ * blanks become null, header-breaking characters and whitespace runs become a
+ * single `_` (a value never holds a space, so `key=value` pairs stay
+ * splittable), and the result is capped at 64 chars.
+ */
+export declare function sanitizeOriginPart(raw: unknown): string | null;
+/** The origin of the caller's own process, read from its environment. */
+export declare function resolveSenderOrigin(env: NodeJS.ProcessEnv): SenderOrigin;
+/**
+ * The origin carried by a serve request. Only the serve worker trusts it: a
+ * local caller cannot claim another pane. Missing/garbage input (an older
+ * client) keeps every part null but still records that serve carried it.
+ */
+export declare function originFromServeRequest(raw: unknown): SenderOrigin;
+/**
+ * " src=session/pane host=host via=serve" (only the parts that are known).
+ * `from=` stays the bare label, so a reader can split the header on spaces.
+ */
+export declare function originSuffix(origin: SenderOrigin | null | undefined): string;
 export type DeliveryResult = {
     to: string;
     ok: boolean;
@@ -143,4 +178,6 @@ export declare function deliverTo(client: ZellijClient, state: StateStore, args:
     firstCallMs?: number;
     /** The observation timeout the scaled windows are capped by. */
     timeoutMs?: number;
+    /** Sender's environment; direct callers (restart, relay) fall back to it. */
+    env?: NodeJS.ProcessEnv;
 }): Promise<DeliveryResult>;

package/dist/ops/delivery.js

@@ -1,5 +1,84 @@
+import { hostname } from "node:os";
 import { busyMarker, queuedPrompt, resolveHarness } from "../harness.js";
+import { resolveSelfPaneId, resolveSelfSession } from "../zellij/session.js";
 import { isTrue, numberArg, optionalString } from "./util.js";
+/** Cap for one origin part; keeps a spoofed value from wrapping the header. */
+const ORIGIN_PART_MAX = 64;
+/**
+ * Clean one origin part for the `[zswarm from=…]` header: non-strings and
+ * blanks become null, header-breaking characters and whitespace runs become a
+ * single `_` (a value never holds a space, so `key=value` pairs stay
+ * splittable), and the result is capped at 64 chars.
+ */
+export function sanitizeOriginPart(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const cleaned = raw.replace(/[\r\n[\]\s]+/g, " ").trim().replace(/ /g, "_");
+    if (!cleaned)
+        return null;
+    return cleaned.length <= ORIGIN_PART_MAX
+        ? cleaned
+        : cleaned.slice(0, ORIGIN_PART_MAX).replace(/_+$/, "");
+}
+/** The origin of the caller's own process, read from its environment. */
+export function resolveSenderOrigin(env) {
+    const configured = env.ZSWARM_HOST;
+    const host = configured === undefined
+        ? sanitizeOriginPart(hostname().split(".")[0])
+        : configured === "-"
+            ? null
+            : sanitizeOriginPart(configured);
+    return {
+        host,
+        session: sanitizeOriginPart(resolveSelfSession(env)),
+        pane: sanitizeOriginPart(resolveSelfPaneId(env)),
+        via: null,
+    };
+}
+/**
+ * The origin carried by a serve request. Only the serve worker trusts it: a
+ * local caller cannot claim another pane. Missing/garbage input (an older
+ * client) keeps every part null but still records that serve carried it.
+ */
+export function originFromServeRequest(raw) {
+    const record = raw !== null && typeof raw === "object" && !Array.isArray(raw)
+        ? raw
+        : {};
+    return {
+        host: sanitizeOriginPart(record.host),
+        session: sanitizeOriginPart(record.session),
+        pane: sanitizeOriginPart(record.pane),
+        via: "serve",
+    };
+}
+/**
+ * " src=session/pane host=host via=serve" (only the parts that are known).
+ * `from=` stays the bare label, so a reader can split the header on spaces.
+ */
+export function originSuffix(origin) {
+    if (!origin)
+        return "";
+    const { session, pane, host, via } = origin;
+    const src = session && pane ? `${session}/${pane}` : (pane ?? session ?? null);
+    return ((src ? " src=" + src : "") +
+        (host ? " host=" + host : "") +
+        (via === "serve" ? " via=serve" : ""));
+}
+/**
+ * An args-supplied origin, cleaned again (a direct caller may skip dispatch),
+ * or null when it is absent/not an object.
+ */
+function originArg(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    return {
+        host: sanitizeOriginPart(record.host),
+        session: sanitizeOriginPart(record.session),
+        pane: sanitizeOriginPart(record.pane),
+        via: record.via === "serve" ? "serve" : null,
+    };
+}
 /** Fixed send windows before adaptive scaling; explicit flags always win. */
 export const SEND_BUDGETS = {
     /** Pause before checking the paste landed. */
@@ -97,7 +176,9 @@ export function attachKnownSender(args, env) {
     return { ...args, from: sender.label };
 }
 export function bodyText(client, args, body) {
-    return isTrue(args.raw) ? body : client.formatPeerMessage(senderLabel(args), body);
+    return isTrue(args.raw)
+        ? body
+        : client.formatPeerMessage(senderLabel(args), body, originArg(args.origin));
 }
 /**
  * Caller `submit=` always wins. With none given, the pane's harness picks
@@ -292,6 +373,10 @@ export async function submitAfterEnter(client, input) {
 export async function deliverTo(client, state, args, input) {
     const { session, pane, body, op, at, clock, firstCallMs = 0, timeoutMs = 30_000 } = input;
     const from = senderLabel(args);
+    // Dispatch stamps args.origin for the header; a direct caller (restart
+    // handoff, relay) has none and is described by its own environment.
+    const origin = originArg(args.origin) ?? resolveSenderOrigin(input.env ?? process.env);
+    const headerArgs = { ...args, origin };
     const override = optionalString(args.harness);
     const mode = resolveSubmitMode(args, pane);
     const profile = resolveHarness(pane, override);
@@ -313,7 +398,7 @@ export async function deliverTo(client, state, args, input) {
         const paste = () => client.injectPane({
             session,
             paneId: pane.id,
-            text: bodyText(client, args, body),
+            text: bodyText(client, headerArgs, body),
         });
         let delivered = await paste();
         let submitted = await verifySubmit(client, {
@@ -371,6 +456,10 @@ export async function deliverTo(client, state, args, input) {
                 session,
                 to: delivered.paneId,
                 from,
+                fromHost: origin.host,
+                fromSession: origin.session,
+                fromPane: origin.pane,
+                via: origin.via,
                 bytes: body.length,
                 ok: false,
                 detail: "submitted=not-delivered",
@@ -392,6 +481,10 @@ export async function deliverTo(client, state, args, input) {
             session,
             to: delivered.paneId,
             from,
+            fromHost: origin.host,
+            fromSession: origin.session,
+            fromPane: origin.pane,
+            via: origin.via,
             bytes: body.length,
             ok: true,
             detail: `submitted=${submitted}`,
@@ -414,6 +507,10 @@ export async function deliverTo(client, state, args, input) {
             session,
             to: pane.id,
             from,
+            fromHost: origin.host,
+            fromSession: origin.session,
+            fromPane: origin.pane,
+            via: origin.via,
             bytes: body.length,
             ok: false,
             detail: `${code}: ${message}`,

package/dist/ops/dispatch.js

@@ -12,7 +12,7 @@ import { broadcast } from "./broadcast.js";
 import { busChanged, busOp, busScreens, busSnapshot, busWait, planBus } from "./bus.js";
 import { dumpLayoutOp, focusTarget, listTabsOp, renameTarget, stackTargets, } from "./panes.js";
 import { peerCheckpoint, peerDiff } from "./review.js";
-import { attachKnownSender, deliverTo, scaleBudgets, withSenderLabel, selfPaneTitle } from "./delivery.js";
+import { attachKnownSender, deliverTo, originFromServeRequest, resolveSenderOrigin, scaleBudgets, withSenderLabel, selfPaneTitle, } from "./delivery.js";
 import { assertNotPlugin, assertNotSelf, assertExpectedScreen, assertWritable, } from "./guards.js";
 import { readDeliveryLog } from "./log.js";
 import { awaitSignal, listSignals, postSignal } from "./signals.js";
@@ -754,6 +754,13 @@ async function pruneExitedSessions(client, listed, args) {
 export async function dispatchZswarm(args, injected, deps = {}) {
     try {
         const env = resolveInvocationEnv(args, deps.env ?? process.env);
+        // A local caller can never claim another pane or `via serve`: its origin is
+        // always read from the environment it runs in. Only the serve worker trusts
+        // the request's origin, sanitized, and stamps it `via serve`.
+        args =
+            deps.viaServe === true
+                ? { ...args, origin: originFromServeRequest(args.origin) }
+                : { ...args, origin: resolveSenderOrigin(env) };
         const context = invocationContext(args, env, injected?.transport);
         const result = await dispatchOperation(args, injected, deps, context, env);
         if (context.transport === "serve" && result.context) {

package/dist/ops/types.d.ts

@@ -25,6 +25,12 @@ export type DispatchDeps = {
     state?: StateStore;
     policy?: Policy;
     env?: NodeJS.ProcessEnv;
+    /**
+     * True when this dispatch is the local worker behind `zswarm serve`: the
+     * request's own origin is trusted and stamped `via serve`, never replaced by
+     * the worker host's environment.
+     */
+    viaServe?: boolean;
     /** MCP cancellation; aborted waits stop instead of running to timeout. */
     signal?: AbortSignal;
     /** Process-owned ssh:// LocalForward manager. CLI disposes; MCP reuses. */

package/dist/schema.js

@@ -281,7 +281,7 @@ export const PARAMS = [
         type: "string",
         flags: ["--from", "-f"],
         ops: ["send", "broadcast"],
-        description: "send: sender label in the [zswarm from=…] prefix (default: ZSWARM_FROM, else the sending pane's title, else swarm)",
+        description: "send: sender label in the [zswarm from=…] prefix (default: ZSWARM_FROM, else the sending pane's title, else swarm). zswarm appends src=<session>/<pane>, host=<host> (ZSWARM_HOST) and via=serve",
     },
     {
         name: "raw",
@@ -648,7 +648,7 @@ export function cliUsage() {
         const value = param.type === "boolean" ? "" : param.type === "number" ? " N" : " VALUE";
         lines.push(`  ${param.flags.join(", ").padEnd(28)}${value.trim().padEnd(6)}${param.description}`);
     }
-    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`; `zswarm <command> --help` for each.", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
+    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`; `zswarm <command> --help` for each.", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZSWARM_HOST, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
     return lines.join("\n");
 }
 /**

package/dist/state.d.ts

@@ -9,6 +9,14 @@ export type LogEntry = {
     session?: string | null;
     to?: string | null;
     from?: string | null;
+    /** Sender's machine when the send was logged. */
+    fromHost?: string | null;
+    /** Sender's Zellij session. */
+    fromSession?: string | null;
+    /** Sender's pane id, e.g. "terminal_3". */
+    fromPane?: string | null;
+    /** "serve" when this host received the op over serve. */
+    via?: "serve" | null;
     bytes?: number;
     ok: boolean;
     detail?: string | null;

package/dist/zellij/client.d.ts

@@ -2,6 +2,7 @@ import { ListingCache } from "./cache.js";
 import { buildClosePaneArgs, buildDumpArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, type WaitRequest, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PipeInput } from "./args.js";
 import { resolveTab, type ZellijTab } from "./tabs.js";
 import { type IpcDiscoveryState } from "../exec.js";
+import { type SenderOrigin } from "../ops/delivery.js";
 import { type ZellijExecFn } from "./binary.js";
 import { normalizePaneId, resolvePane, type ZellijPane } from "./panes.js";
 import { type ZellijSession, type ZellijSessionResolve } from "./session.js";
@@ -183,7 +184,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
     }>;
     resolveTab: typeof resolveTab;
     normalizePaneId: typeof normalizePaneId;
-    formatPeerMessage: (from: string, body: string) => string;
+    formatPeerMessage: (from: string, body: string, origin?: SenderOrigin | null) => string;
     buildListPanesArgs: typeof buildListPanesArgs;
     buildPasteArgs: typeof buildPasteArgs;
     buildSendEnterArgs: typeof buildSendEnterArgs;

package/dist/zellij/client.js

@@ -4,6 +4,7 @@ import { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneA
 import { DEFAULT_BUS_TIMEOUT_MS, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, } from "./bus.js";
 import { parseTabList, resolveTab } from "./tabs.js";
 import { createSshExec } from "../exec.js";
+import { originSuffix } from "../ops/delivery.js";
 import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, zellijExecDetails, zellijMissingError, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
 import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, resolveSelfSession, sessionFromEnv, sessionFromList, } from "./session.js";
@@ -363,9 +364,9 @@ export function createZellijClient(options = {}) {
         };
     }
     /** Visible prefix so peer CLIs can tell zSwarm injects from human prompts. */
-    function formatPeerMessage(from, body) {
+    function formatPeerMessage(from, body, origin) {
         const sender = from.trim() || "swarm";
-        return `[zswarm from=${sender}]\n${body}`;
+        return `[zswarm from=${sender}${originSuffix(origin)}]\n${body}`;
     }
     return {
         zellijPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {