@cotal-ai/tmux 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,37 @@
+# @cotal-ai/tmux
+
+The tmux integration: a thin driver over the tmux CLI (open/close a window, send keys) plus a
+self-registering `tmux` `Runtime` and `TerminalLayout` provider. Importing it registers both
+with the core `Registry`, so the manager can spawn agents into tmux windows without depending
+on this package.
+
+**Tier:** `extensions/`. Peer-depends [`@cotal-ai/core`](../../packages/core); self-registers on
+import.
+
+## What it does
+
+- **`Runtime` (`tmux`)** — each agent gets its own window in a shared per-space tmux session
+  (`cotal-<space>`). Spawned unfocused; switch to `session:name` to watch it. Env is isolated
+  (`env -i`) so the tmux server's environment doesn't reach agents. Graceful stop types `/exit`
+  then kills the window; hard stop kills immediately.
+
+- **`TerminalLayout` (`tmux`)** — opens/closes tmux windows for host-side orchestration
+  (e.g. `cotal setup`). Detects the current session from `$TMUX`; must be called from inside
+  a tmux session. Supports multi-pane tabs via `split-window`.
+
+## Usage
+
+```ts
+import "@cotal-ai/tmux"; // self-registers; no other setup needed
+```
+
+Then select via the manager: `cotal supervise --runtime tmux`.
+
+## Differences from `@cotal-ai/cmux`
+
+cmux opens a per-agent **workspace (tab)** in the cmux app; this package opens a per-agent
+**window** in a tmux session. Both are native-watch (no PTY streaming). No `cli.ts` helper is
+included — tmux is always on PATH and needs no bundled binary path.
+
+See [docs/architecture.md](../../docs/architecture.md) (*Manager*) and the
+[root AGENTS.md](../../AGENTS.md) for the tier rules.

package/dist/driver.d.ts

@@ -0,0 +1,55 @@
+/** True if tmux is installed and reachable on PATH. */
+export declare function available(): boolean;
+/** Session name from the surrounding tmux environment. Throws if not inside tmux. */
+export declare function currentSession(): string;
+/** Ensure a detached tmux session exists; creates it if absent. A detached session has no client
+ *  to size it, and some tmux builds then treat its window as sizeless — so `split-window` fails
+ *  with "size missing". Give it an explicit initial size; tmux resizes to the real client on attach. */
+export declare function ensureSession(session: string, cwd: string): void;
+/** True if a window named `name` exists in `session`. Name-based — fragile under renames; prefer
+ *  {@link windowAliveRef} when you hold a stable `@N` ID. Kept for name-based discovery/cleanup. */
+export declare function windowAlive(session: string, name: string): boolean;
+/** True if a window with the stable ID `windowId` (`@N`) still exists. Window IDs are server-global,
+ *  so we test exact membership in the full window list — surviving renames, unlike {@link windowAlive}
+ *  (name match). (Don't use `display-message -t`: for a stale target it silently falls back to the
+ *  current window instead of erroring, so it can't detect a closed window.) */
+export declare function windowAliveRef(windowId: string): boolean;
+/** The stable refs for a freshly-opened window: its window ID (`@N`) and the ID of its initial
+ *  (only) pane (`%N`). Both survive renames/reorders — drive later close/split/send/refs calls off
+ *  these, not the mutable `session:name` target or pane indexes. */
+export interface WindowRefs {
+    windowId: string;
+    paneId: string;
+}
+/** Open a new tmux window `name` in `session` running `command` (a shell string).
+ *  Created detached (unfocused) by default; pass `focus: true` to switch to it.
+ *  Returns the stable window ID (`@N`) and its initial pane ID (`%N`). */
+export declare function openWindow(session: string, name: string, command: string, cwd: string, opts?: {
+    focus?: boolean;
+}): WindowRefs;
+/** Split `target` (a window ID `@N`, or session:window) creating a new pane running `command`.
+ *  Returns the new pane's stable ID (`%N`). Direction convention matches {@link Tab.split.direction}:
+ *  `"horizontal"` → stacked top/bottom rows (tmux `-v`, the default);
+ *  `"vertical"` → side-by-side columns (tmux `-h`).
+ *  `ratio` is the first pane's fraction — the new pane gets `(1 - ratio)`. */
+export declare function splitWindow(target: string, command: string, cwd: string, direction: "vertical" | "horizontal", ratio?: number): string;
+/** Focus a window by target (`session:name` or window ID). */
+export declare function selectWindow(target: string): void;
+/** Kill a tmux window by target (window ID `@N`, or `session:name`). Idempotent: already-gone is a no-op. */
+export declare function closeWindow(target: string): void;
+/** Window names open in `session`, or `[]` if unreachable. */
+export declare function listWindows(session: string): string[];
+/** Stable window IDs (`@N`) of every window in `session` whose name is exactly `label`. */
+export declare function windowRefs(session: string, label: string): string[];
+/** Shell command string that runs `command args` with `env -i` isolation — only the given
+ *  `env` entries reach the process (the tmux server's inherited env is stripped). */
+export declare function isolatedCommand(env: Record<string, string>, command: string, args: string[]): string;
+/** Shell command string that runs `command args` with extra `env` merged into the inherited env. */
+export declare function mergedCommand(env: Record<string, string>, command: string, args: string[]): string;
+/** Type literal text into a tmux target.
+ *  `-l` bypasses tmux's key-name lookup; `--` guards against text starting with `-`. */
+export declare function send(text: string, target: string): void;
+/** Send a named key sequence (e.g. `"Enter"`, `"C-c"`) to a tmux target.
+ *  `--` guards against key names starting with `-`. */
+export declare function sendKey(key: string, target: string): void;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,wBAAgB,SAAS,IAAI,OAAO,CAOnC;AAMD,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAWD;;wGAEwG;AACxG,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAKhE;AAED;oGACoG;AACpG,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CASlE;AAED;;;+EAG+E;AAC/E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CASxD;AASD;;oEAEoE;AACpE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;0EAE0E;AAC1E,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,UAAU,CAUZ;AAED;;;;8EAI8E;AAC9E,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,UAAU,GAAG,YAAY,EACpC,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAUR;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,6GAA6G;AAC7G,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOhD;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAWrD;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBnE;AAcD;qFACqF;AACrF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GACb,MAAM,CAER;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GACb,MAAM,CAER;AAED;wFACwF;AACxF,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;uDACuD;AACvD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEzD"}

package/dist/driver.js

@@ -0,0 +1,187 @@
+import { execFileSync } from "node:child_process";
+/** True if tmux is installed and reachable on PATH. */
+export function available() {
+    try {
+        execFileSync("tmux", ["-V"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/** Session name from the surrounding tmux environment. Throws if not inside tmux. */
+export function currentSession() {
+    if (!process.env.TMUX)
+        throw new Error("tmux: not inside a tmux session ($TMUX is not set)");
+    try {
+        return execFileSync("tmux", ["display-message", "-p", "#S"], { encoding: "utf8" }).trim();
+    }
+    catch (err) {
+        throw new Error(`tmux: couldn't read current session name: ${err}`);
+    }
+}
+function hasSession(session) {
+    try {
+        execFileSync("tmux", ["has-session", "-t", session], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Ensure a detached tmux session exists; creates it if absent. A detached session has no client
+ *  to size it, and some tmux builds then treat its window as sizeless — so `split-window` fails
+ *  with "size missing". Give it an explicit initial size; tmux resizes to the real client on attach. */
+export function ensureSession(session, cwd) {
+    if (!hasSession(session))
+        execFileSync("tmux", ["new-session", "-d", "-s", session, "-x", "200", "-y", "50", "-c", cwd], {
+            stdio: "ignore",
+        });
+}
+/** True if a window named `name` exists in `session`. Name-based — fragile under renames; prefer
+ *  {@link windowAliveRef} when you hold a stable `@N` ID. Kept for name-based discovery/cleanup. */
+export function windowAlive(session, name) {
+    try {
+        const out = execFileSync("tmux", ["list-windows", "-t", session, "-F", "#W"], {
+            encoding: "utf8",
+        });
+        return out.split("\n").map((l) => l.trim()).includes(name);
+    }
+    catch {
+        return false;
+    }
+}
+/** True if a window with the stable ID `windowId` (`@N`) still exists. Window IDs are server-global,
+ *  so we test exact membership in the full window list — surviving renames, unlike {@link windowAlive}
+ *  (name match). (Don't use `display-message -t`: for a stale target it silently falls back to the
+ *  current window instead of erroring, so it can't detect a closed window.) */
+export function windowAliveRef(windowId) {
+    try {
+        return execFileSync("tmux", ["list-windows", "-a", "-F", "#{window_id}"], { encoding: "utf8" })
+            .split("\n")
+            .map((l) => l.trim())
+            .includes(windowId);
+    }
+    catch {
+        return false;
+    }
+}
+function isWindowGone(err) {
+    // Use both stderr (captured when stdio:"pipe") and message (contains the command + code).
+    const e = err;
+    const msg = `${String(e.stderr ?? "")}${String(e.message ?? "")}`;
+    return /can't find window|can't find session|no current window|session not found/i.test(msg);
+}
+/** Open a new tmux window `name` in `session` running `command` (a shell string).
+ *  Created detached (unfocused) by default; pass `focus: true` to switch to it.
+ *  Returns the stable window ID (`@N`) and its initial pane ID (`%N`). */
+export function openWindow(session, name, command, cwd, opts = {}) {
+    const args = ["new-window", "-t", session, "-n", name, "-c", cwd];
+    if (!(opts.focus ?? false))
+        args.push("-d");
+    // -P -F prints the new window + pane IDs before returning — stable across renames and reorders.
+    args.push("-P", "-F", "#{window_id} #{pane_id}", command);
+    const out = execFileSync("tmux", args, { encoding: "utf8" }).trim();
+    const [windowId, paneId] = out.split(/\s+/);
+    if (!windowId || !paneId)
+        throw new Error(`tmux: couldn't read window/pane IDs from new-window ("${out}")`);
+    return { windowId, paneId };
+}
+/** Split `target` (a window ID `@N`, or session:window) creating a new pane running `command`.
+ *  Returns the new pane's stable ID (`%N`). Direction convention matches {@link Tab.split.direction}:
+ *  `"horizontal"` → stacked top/bottom rows (tmux `-v`, the default);
+ *  `"vertical"` → side-by-side columns (tmux `-h`).
+ *  `ratio` is the first pane's fraction — the new pane gets `(1 - ratio)`. */
+export function splitWindow(target, command, cwd, direction, ratio) {
+    const args = ["split-window", "-t", target, "-c", cwd];
+    if (direction === "vertical")
+        args.push("-h"); // side-by-side columns = tmux -h
+    // `-l <n>%` is the modern size syntax; the old `-p <n>` is deprecated and errors "size missing"
+    // on tmux 3.4. The new pane gets (1 - ratio); the first keeps `ratio`.
+    if (ratio !== undefined)
+        args.push("-l", `${Math.round((1 - ratio) * 100)}%`);
+    // -P -F prints the new pane's ID — use it as a stable target (pane indexes shift under
+    // `pane-base-index` and renumber on close).
+    args.push("-P", "-F", "#{pane_id}", command);
+    return execFileSync("tmux", args, { encoding: "utf8" }).trim();
+}
+/** Focus a window by target (`session:name` or window ID). */
+export function selectWindow(target) {
+    execFileSync("tmux", ["select-window", "-t", target], { stdio: "ignore" });
+}
+/** Kill a tmux window by target (window ID `@N`, or `session:name`). Idempotent: already-gone is a no-op. */
+export function closeWindow(target) {
+    try {
+        execFileSync("tmux", ["kill-window", "-t", target], { stdio: "pipe" });
+    }
+    catch (err) {
+        if (isWindowGone(err))
+            return;
+        throw err;
+    }
+}
+/** Window names open in `session`, or `[]` if unreachable. */
+export function listWindows(session) {
+    try {
+        return execFileSync("tmux", ["list-windows", "-t", session, "-F", "#W"], {
+            encoding: "utf8",
+        })
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** Stable window IDs (`@N`) of every window in `session` whose name is exactly `label`. */
+export function windowRefs(session, label) {
+    try {
+        return execFileSync("tmux", ["list-windows", "-t", session, "-F", "#{window_id} #{window_name}"], { encoding: "utf8" })
+            .split("\n")
+            .filter(Boolean)
+            .flatMap((line) => {
+            const sp = line.indexOf(" ");
+            const id = line.slice(0, sp);
+            const name = line.slice(sp + 1).trim();
+            return name === label ? [id] : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Render `env` as shell-safe `KEY='value'` pairs. tmux (like cmux) shell-renders env into the
+ *  command line — pty passes it structurally — so reject any KEY that isn't a valid env identifier
+ *  before rendering, rather than splice an attacker-influenced name into the command. Shipped
+ *  connectors only generate safe names today; this is defense-in-depth. */
+function envPairs(env) {
+    return Object.entries(env).map(([k, v]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+            throw new Error(`tmux: refusing to render unsafe env var name ${JSON.stringify(k)}`);
+        return `${k}=${shellQuote(v)}`;
+    });
+}
+/** Shell command string that runs `command args` with `env -i` isolation — only the given
+ *  `env` entries reach the process (the tmux server's inherited env is stripped). */
+export function isolatedCommand(env, command, args) {
+    return ["env", "-i", ...envPairs(env), shellQuote(command), ...args.map(shellQuote)].join(" ");
+}
+/** Shell command string that runs `command args` with extra `env` merged into the inherited env. */
+export function mergedCommand(env, command, args) {
+    return ["env", ...envPairs(env), shellQuote(command), ...args.map(shellQuote)].join(" ");
+}
+/** Type literal text into a tmux target.
+ *  `-l` bypasses tmux's key-name lookup; `--` guards against text starting with `-`. */
+export function send(text, target) {
+    execFileSync("tmux", ["send-keys", "-l", "-t", target, "--", text], { stdio: "ignore" });
+}
+/** Send a named key sequence (e.g. `"Enter"`, `"C-c"`) to a tmux target.
+ *  `--` guards against key names starting with `-`. */
+export function sendKey(key, target) {
+    execFileSync("tmux", ["send-keys", "-t", target, "--", key], { stdio: "ignore" });
+}
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/** @cotal-ai/tmux — the tmux integration: a thin driver over the tmux CLI plus
+ *  self-registering `tmux` Runtime and TerminalLayout providers. Importing the package
+ *  registers both with the core Registry (like a connector), so the manager can spawn
+ *  into tmux windows and `cotal setup` can open/close them — neither depending on this
+ *  package. The driver itself stays mesh-free; launch scripts import `./driver.js`
+ *  directly to avoid the registration side effect. */
+export * as tmux from "./driver.js";
+export { TmuxRuntime, tmuxRuntimeProvider, tmuxTerminalProvider } from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;sDAKsD;AACtD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/** @cotal-ai/tmux — the tmux integration: a thin driver over the tmux CLI plus
+ *  self-registering `tmux` Runtime and TerminalLayout providers. Importing the package
+ *  registers both with the core Registry (like a connector), so the manager can spawn
+ *  into tmux windows and `cotal setup` can open/close them — neither depending on this
+ *  package. The driver itself stays mesh-free; launch scripts import `./driver.js`
+ *  directly to avoid the registration side effect. */
+export * as tmux from "./driver.js";
+// importing registers the tmux runtime + terminal-layout providers
+export { TmuxRuntime, tmuxRuntimeProvider, tmuxTerminalProvider } from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;sDAKsD;AACtD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,23 @@
+import { type AgentHandle, type LaunchSpec, type Runtime, type RuntimeProvider, type TerminalLayout } from "@cotal-ai/core";
+/**
+ * Spawns each agent into its own new tmux window in a shared per-space session, so
+ * spawned teammates get room rather than crowding the spawner. Opened unfocused so the
+ * human stays in their current window; switch to `session:name` to watch the worker.
+ * Like cmux, you watch natively, so `attach()` throws — but teardown is real: the window
+ * target is kept so it can be driven and closed.
+ */
+export declare class TmuxRuntime implements Runtime {
+    private readonly session;
+    readonly kind: "tmux";
+    constructor(session: string);
+    spawn(name: string, spec: LaunchSpec, cwd: string): AgentHandle;
+}
+/** Self-registering runtime provider — `import "@cotal-ai/tmux"` makes the manager's
+ *  `tmux` runtime available without the manager depending on this package. */
+export declare const tmuxRuntimeProvider: RuntimeProvider;
+/** Self-registering terminal-layout provider — lets a caller (e.g. `cotal setup`) open/close
+ *  tmux windows by resolving `registry.resolve("terminal","tmux")`, so an implementation
+ *  drives tmux without importing this package. The session is detected from the ambient `$TMUX`
+ *  environment; throws if not inside tmux (per AGENTS.md: no silent fallback). */
+export declare const tmuxTerminalProvider: TerminalLayout;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,eAAe,EAEpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAoBxB;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,OAAO;IAG7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAEH,OAAO,EAAE,MAAM;IAE5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;CAsDhE;AAED;8EAC8E;AAC9E,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAkCF;;;kFAGkF;AAClF,eAAO,MAAM,oBAAoB,EAAE,cAclC,CAAC"}

package/dist/runtime.js

@@ -0,0 +1,139 @@
+import { registry, } from "@cotal-ai/core";
+import * as tmux from "./driver.js";
+/** Grace window for a clean exit before a graceful stop force-closes the window. */
+const GRACE_MS = 1_500;
+/** Schedule Enter keypresses to `target` every second for 5 seconds — auto-clears a
+ *  one-time confirmation prompt (e.g. Claude's dev-channels prompt) without blocking. */
+function scheduleConfirm(target) {
+    for (let i = 1; i <= 5; i++) {
+        setTimeout(() => {
+            try {
+                tmux.sendKey("Enter", target);
+            }
+            catch {
+                /* window may be gone — ignore */
+            }
+        }, i * 1_000);
+    }
+}
+/**
+ * Spawns each agent into its own new tmux window in a shared per-space session, so
+ * spawned teammates get room rather than crowding the spawner. Opened unfocused so the
+ * human stays in their current window; switch to `session:name` to watch the worker.
+ * Like cmux, you watch natively, so `attach()` throws — but teardown is real: the window
+ * target is kept so it can be driven and closed.
+ */
+export class TmuxRuntime {
+    session;
+    kind = "tmux";
+    constructor(session) {
+        this.session = session;
+    }
+    spawn(name, spec, cwd) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name))
+            throw new Error(`tmux runtime: unsafe agent name ${JSON.stringify(name)} (allowed: letters, digits, _ . -)`);
+        if (!tmux.available())
+            throw new Error("tmux runtime: tmux is not available — is tmux installed and on PATH?");
+        tmux.ensureSession(this.session, cwd);
+        // P3: env -i strips the tmux server's inherited environment; only the connector-declared
+        // env reaches the spawned agent (identity, model key, OS allow-list).
+        const command = tmux.isolatedCommand(spec.env ?? {}, spec.command, spec.args);
+        // Key the whole lifecycle off the STABLE window ID (@N), not `session:name`. tmux can rename
+        // a window (automatic-rename / a title escape), which would desync a name-based status/stop.
+        const { windowId } = tmux.openWindow(this.session, name, command, cwd, { focus: false });
+        if (spec.confirm)
+            scheduleConfirm(windowId);
+        return {
+            name,
+            kind: "tmux",
+            status: () => (tmux.windowAliveRef(windowId) ? "running" : "exited"),
+            stop: (opts) => {
+                if (opts?.graceful === false)
+                    return tmux.closeWindow(windowId);
+                // Graceful: type `/exit` so the Claude session shuts down cleanly (its SessionEnd
+                // hook leaves the mesh), then close the now-idle window regardless.
+                try {
+                    tmux.send("/exit", windowId);
+                    tmux.sendKey("Enter", windowId);
+                }
+                catch {
+                    /* window already gone — still ensure it's closed below */
+                }
+                // Deferred, so a throw here is uncaught in a timer and would crash the manager.
+                // closeWindow already no-ops on an already-gone window; guard anyway and log a genuine
+                // tmux failure rather than let teardown cleanup take the process down.
+                setTimeout(() => {
+                    try {
+                        tmux.closeWindow(windowId);
+                    }
+                    catch (err) {
+                        console.error(`tmux runtime: failed to close window for "${name}":`, err);
+                    }
+                }, GRACE_MS);
+            },
+            interrupt: () => {
+                tmux.sendKey("C-c", windowId);
+            },
+            attach: () => {
+                throw new Error(`tmux runtime: attach natively — \`tmux attach-session -t ${this.session}\`, then ` +
+                    `\`tmux select-window -t ${windowId}\` (window "${name}")`);
+            },
+        };
+    }
+}
+/** Self-registering runtime provider — `import "@cotal-ai/tmux"` makes the manager's
+ *  `tmux` runtime available without the manager depending on this package. */
+export const tmuxRuntimeProvider = {
+    kind: "runtime",
+    name: "tmux",
+    available: () => tmux.available(),
+    create: (opts) => new TmuxRuntime(opts.session),
+};
+registry.register(tmuxRuntimeProvider);
+/** Translate a backend-agnostic {@link Tab} into a sequence of tmux commands on `session`.
+ *  One pane → a bare window; several → a window + splits. These panes inherit the caller's
+ *  env (setup panes run further `cotal` subcommands), so no `-i` isolation here. */
+function tmuxLayout(session, label, tab) {
+    const [first, ...rest] = tab.panes;
+    if (!first)
+        throw new Error(`tmux layout "${label}": tab has no panes`);
+    const firstCmd = tmux.mergedCommand(first.env ?? {}, first.command, first.args ?? []);
+    // Drive splits/focus/confirm off the STABLE window/pane IDs returned here — never `session:label`
+    // (labels can collide or be renamed) or pane indexes `.0`/`.1` (shift under `pane-base-index`).
+    const { windowId, paneId: firstPane } = tmux.openWindow(session, label, firstCmd, first.cwd ?? ".", {
+        focus: false,
+    });
+    if (rest.length > 0 && !tab.split)
+        throw new Error(`tmux layout "${label}": ${tab.panes.length} panes need a split (direction + ratio)`);
+    if (first.confirm)
+        scheduleConfirm(firstPane);
+    rest.forEach((pane) => {
+        const cmd = tmux.mergedCommand(pane.env ?? {}, pane.command, pane.args ?? []);
+        const newPane = tmux.splitWindow(windowId, cmd, pane.cwd ?? ".", tab.split.direction, tab.split.ratio);
+        if (pane.confirm)
+            scheduleConfirm(newPane);
+    });
+    return windowId;
+}
+/** Self-registering terminal-layout provider — lets a caller (e.g. `cotal setup`) open/close
+ *  tmux windows by resolving `registry.resolve("terminal","tmux")`, so an implementation
+ *  drives tmux without importing this package. The session is detected from the ambient `$TMUX`
+ *  environment; throws if not inside tmux (per AGENTS.md: no silent fallback). */
+export const tmuxTerminalProvider = {
+    kind: "terminal",
+    name: "tmux",
+    available: () => tmux.available(),
+    open: (label, tab, opts) => {
+        const session = tmux.currentSession();
+        const windowId = tmuxLayout(session, label, tab);
+        if (opts?.focus)
+            tmux.selectWindow(windowId);
+        // Return the exact window ID we created (stable across renames) — not a label re-lookup, which
+        // could resolve a different same-label window.
+        return windowId;
+    },
+    close: (ref) => tmux.closeWindow(ref),
+    refs: (label) => tmux.windowRefs(tmux.currentSession(), label),
+};
+registry.register(tmuxTerminalProvider);
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@cotal-ai/tmux",
+  "description": "Cotal tmux integration: a tmux Runtime and TerminalLayout provider for spawning agents into tmux windows.",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Cotal-AI/Cotal.git",
+    "directory": "extensions/tmux"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@cotal-ai/core": "0.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json"
+  }
+}