@theaileverage/marionette 0.2.1 → 0.2.2

package/dist/cli.js

@@ -886,15 +886,15 @@ var require_depd = __commonJS({
       return relative5(basePath, callSite[0]) + ":" + callSite[1] + ":" + callSite[2];
     }
     function getStack() {
-      var limit = Error.stackTraceLimit;
+      var limit2 = Error.stackTraceLimit;
       var obj = {};
       var prep = Error.prepareStackTrace;
       Error.prepareStackTrace = prepareObjectStackTrace;
-      Error.stackTraceLimit = Math.max(10, limit);
+      Error.stackTraceLimit = Math.max(10, limit2);
       Error.captureStackTrace(obj);
       var stack = obj.stack.slice(1);
       Error.prepareStackTrace = prep;
-      Error.stackTraceLimit = limit;
+      Error.stackTraceLimit = limit2;
       return stack;
     }
     function prepareObjectStackTrace(obj, stack) {
@@ -5341,13 +5341,13 @@ var require_raw_body = __commonJS({
         throw new TypeError("argument callback is required");
       }
       var encoding = opts.encoding !== true ? opts.encoding : "utf-8";
-      var limit = bytes.parse(opts.limit);
+      var limit2 = bytes.parse(opts.limit);
       var length = opts.length != null && !isNaN(opts.length) ? parseInt(opts.length, 10) : null;
       if (done) {
-        return readStream(stream, encoding, length, limit, wrap(done));
+        return readStream(stream, encoding, length, limit2, wrap(done));
       }
       return new Promise(function executor(resolve13, reject) {
-        readStream(stream, encoding, length, limit, function onRead(err, buf) {
+        readStream(stream, encoding, length, limit2, function onRead(err, buf) {
           if (err) return reject(err);
           resolve13(buf);
         });
@@ -5359,14 +5359,14 @@ var require_raw_body = __commonJS({
         stream.pause();
       }
     }
-    function readStream(stream, encoding, length, limit, callback) {
+    function readStream(stream, encoding, length, limit2, callback) {
       var complete = false;
       var sync = true;
-      if (limit !== null && length !== null && length > limit) {
+      if (limit2 !== null && length !== null && length > limit2) {
         return done(createError(413, "request entity too large", {
           expected: length,
           length,
-          limit,
+          limit: limit2,
           type: "entity.too.large"
         }));
       }
@@ -5427,9 +5427,9 @@ var require_raw_body = __commonJS({
       function onData(chunk) {
         if (complete) return;
         received += chunk.length;
-        if (limit !== null && received > limit) {
+        if (limit2 !== null && received > limit2) {
           done(createError(413, "request entity too large", {
-            limit,
+            limit: limit2,
             received,
             type: "entity.too.large"
           }));
@@ -15608,11 +15608,11 @@ var require_utils = __commonJS({
         throw new TypeError("defaultType must be provided");
       }
       const inflate = options?.inflate !== false;
-      const limit = typeof options?.limit === "undefined" || options?.limit === null ? 102400 : bytes.parse(options.limit);
+      const limit2 = typeof options?.limit === "undefined" || options?.limit === null ? 102400 : bytes.parse(options.limit);
       const type = options?.type || defaultType;
       const verify = options?.verify || false;
       const defaultCharset = options?.defaultCharset || "utf-8";
-      if (limit === null) {
+      if (limit2 === null) {
         throw new TypeError(`option limit "${String(options.limit)}" is invalid`);
       }
       if (verify !== false && typeof verify !== "function") {
@@ -15621,7 +15621,7 @@ var require_utils = __commonJS({
       const shouldParse = typeof type !== "function" ? typeChecker(type) : type;
       return {
         inflate,
-        limit,
+        limit: limit2,
         verify,
         defaultCharset,
         shouldParse
@@ -17756,7 +17756,7 @@ var require_utils2 = __commonJS({
         return strWithoutPlus;
       }
     };
-    var limit = 1024;
+    var limit2 = 1024;
     var encode = function encode2(str, defaultEncoder, charset, kind, format) {
       if (str.length === 0) {
         return str;
@@ -17773,9 +17773,9 @@ var require_utils2 = __commonJS({
         });
       }
       var out = "";
-      for (var j = 0; j < string.length; j += limit) {
-        var segment = string.length >= limit ? string.slice(j, j + limit) : string;
-        if (j + limit < string.length) {
+      for (var j = 0; j < string.length; j += limit2) {
+        var segment = string.length >= limit2 ? string.slice(j, j + limit2) : string;
+        if (j + limit2 < string.length) {
           var last = segment.charCodeAt(segment.length - 1);
           if (last >= 55296 && last <= 56319) {
             segment = segment.slice(0, -1);
@@ -18246,13 +18246,13 @@ var require_parse = __commonJS({
       var obj = { __proto__: null };
       var cleanStr = options.ignoreQueryPrefix ? str.replace(/^\?/, "") : str;
       cleanStr = cleanStr.replace(/%5B/gi, "[").replace(/%5D/gi, "]");
-      var limit = options.parameterLimit === Infinity ? void 0 : options.parameterLimit;
+      var limit2 = options.parameterLimit === Infinity ? void 0 : options.parameterLimit;
       var parts = cleanStr.split(
         options.delimiter,
-        options.throwOnLimitExceeded && typeof limit !== "undefined" ? limit + 1 : limit
+        options.throwOnLimitExceeded && typeof limit2 !== "undefined" ? limit2 + 1 : limit2
       );
-      if (options.throwOnLimitExceeded && typeof limit !== "undefined" && parts.length > limit) {
-        throw new RangeError("Parameter limit exceeded. Only " + limit + " parameter" + (limit === 1 ? "" : "s") + " allowed.");
+      if (options.throwOnLimitExceeded && typeof limit2 !== "undefined" && parts.length > limit2) {
+        throw new RangeError("Parameter limit exceeded. Only " + limit2 + " parameter" + (limit2 === 1 ? "" : "s") + " allowed.");
       }
       var skipIndex = -1;
       var i;
@@ -18600,12 +18600,12 @@ var require_urlencoded = __commonJS({
         }
       };
     }
-    function parameterCount(body, limit) {
+    function parameterCount(body, limit2) {
       let count = 0;
       let index = -1;
       do {
         count++;
-        if (count > limit) return void 0;
+        if (count > limit2) return void 0;
         index = body.indexOf("&", index + 1);
       } while (index !== -1);
       return count;
@@ -28278,8 +28278,8 @@ var Store = class {
     const r = this.db.prepare("INSERT INTO events(project_id,data) VALUES(?,?)").run(projectId, JSON.stringify(event));
     return { ...event, id: Number(r.lastInsertRowid) };
   }
-  events(projectId, after = 0, limit = 200) {
-    return this.db.prepare("SELECT id,data FROM events WHERE project_id=? AND id>? ORDER BY id LIMIT ?").all(projectId, after, limit).map((r) => ({ ...JSON.parse(r.data), id: r.id }));
+  events(projectId, after = 0, limit2 = 200) {
+    return this.db.prepare("SELECT id,data FROM events WHERE project_id=? AND id>? ORDER BY id LIMIT ?").all(projectId, after, limit2).map((r) => ({ ...JSON.parse(r.data), id: r.id }));
   }
   close() {
     this.db.close();
@@ -28289,7 +28289,7 @@ var Store = class {
 // src/service.ts
 import { randomUUID as randomUUID6, randomBytes as randomBytes2 } from "node:crypto";
 import { realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
-import { isAbsolute as isAbsolute2 } from "node:path";
+import { isAbsolute as isAbsolute4 } from "node:path";
 
 // src/continuation.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -29163,6 +29163,7 @@ var Cleanup = class {
       runs: runs.map((r) => ({
         runId: r.id,
         tabId: r.tabId,
+        paneId: r.paneId,
         cleanup: r.cleanup,
         reasons: this.runReasons(t, r, true)
       })),
@@ -29193,7 +29194,7 @@ var Cleanup = class {
         this.saveRun(r, {
           ...r.cleanup,
           state: "uncertain",
-          error: "Restart during tab closure; inspect and reconcile. No automatic replay."
+          error: "Restart during terminal closure; inspect and reconcile. No automatic replay."
         });
   }
   async stop() {
@@ -29246,7 +29247,7 @@ var Cleanup = class {
     const tab = (await h.call("tab.get", { tab_id: r.tabId })).tab;
     const panes = (await h.call("pane.list", { workspace_id: p.workspaceId })).panes;
     const members = panes?.filter((pane) => pane.tab_id === r.tabId);
-    if (tab?.workspace_id !== p.workspaceId || tab.tab_id !== r.tabId || tab.pane_count !== 1 || members?.length !== 1 || members[0].pane_id !== r.paneId || members[0].terminal_id !== r.terminalId)
+    if (tab?.workspace_id !== p.workspaceId || tab.tab_id !== r.tabId || !r.terminalScope && (tab.pane_count !== 1 || members?.length !== 1) || members?.filter((pane) => pane.pane_id === r.paneId && pane.terminal_id === r.terminalId).length !== 1)
       refuse("Tab contents changed; refusing to close another pane");
     const a = (await h.call("agent.get", { target: r.paneId })).agent;
     if (a?.workspace_id !== p.workspaceId || a.pane_id !== r.paneId || a.terminal_id !== r.terminalId || a.name !== r.agentName || a.agent !== r.kind || a.agent_session?.value !== r.nativeSession || !["idle", "done"].includes(a.agent_status) || a.launch_pending || a.interactive_ready === false)
@@ -29255,6 +29256,17 @@ var Cleanup = class {
   }
   async absent(t, r) {
     const h = this.s.port(this.s.project(t.projectId));
+    if (r.terminalScope === "pane") {
+      const panes2 = (await h.call("pane.list")).panes;
+      if (!Array.isArray(panes2)) refuse("Cannot inspect worker terminal membership");
+      if (panes2.some(
+        (pane) => (pane.pane_id === r.paneId || pane.terminal_id === r.terminalId) && (pane.pane_id !== r.paneId || pane.tab_id !== r.tabId || pane.terminal_id !== r.terminalId)
+      ))
+        refuse("Original terminal may have moved; inspect it before cleanup");
+      return !panes2.some(
+        (pane) => pane.pane_id === r.paneId || pane.terminal_id === r.terminalId
+      );
+    }
     try {
       await h.call("tab.get", { tab_id: r.tabId });
       return false;
@@ -29279,7 +29291,7 @@ var Cleanup = class {
   }) {
     if (r.cleanup?.state === "closed") return r.cleanup;
     if (r.cleanup && ["closing", "uncertain"].includes(r.cleanup.state))
-      refuse("Reconcile ambiguous tab closure first");
+      refuse("Reconcile ambiguous terminal closure first");
     try {
       const reasons = this.runReasons(this.s.task(t.id), r, automatic);
       if (reasons.length) refuse(reasons.join("; "));
@@ -29306,12 +29318,13 @@ var Cleanup = class {
         updatedAt: now(),
         output: String(output).slice(-1e5)
       });
-      await h.call("tab.close", { tab_id: r.tabId });
+      if (r.terminalScope === "pane") await h.call("pane.close", { pane_id: r.paneId });
+      else await h.call("tab.close", { tab_id: r.tabId });
       this.saveRun(r, { ...this.s.store.get("run", r.id).cleanup, state: "closed" });
       this.s.store.event(
         t.projectId,
         "cleanup.released",
-        "Saved worker diagnostics and closed its settled tab",
+        "Saved worker diagnostics and closed its settled terminal",
         t.id,
         { runId: r.id }
       );
@@ -29609,7 +29622,7 @@ var Cleanup = class {
             this.saveRun(r, { ...r.cleanup, state: "closed", reason, error: void 0 });
             return this.s.store.get("run", r.id).cleanup;
           }
-          refuse("Original tab is still present");
+          refuse("Original worker terminal is still present");
         }
         await this.pinned(t, r);
         guard();
@@ -31267,68 +31280,620 @@ var Orchestration = class {
   }
 };
 
-// src/herdr.ts
+// src/herdr-protocol.ts
+var HERDR_METHODS = [
+  "ping",
+  "server.stop",
+  "server.live_handoff",
+  "server.reload_config",
+  "server.agent_manifests",
+  "server.reload_agent_manifests",
+  "notification.show",
+  "product_announcement.dismiss",
+  "release_notes.dismiss",
+  "command.invoke",
+  "client.window_title.set",
+  "client.window_title.clear",
+  "client_shell.surface.set",
+  "session.snapshot",
+  "workspace.create",
+  "workspace.list",
+  "workspace.get",
+  "workspace.focus",
+  "workspace.rename",
+  "workspace.move",
+  "workspace.move_block",
+  "workspace.report_metadata",
+  "workspace.close",
+  "worktree.list",
+  "worktree.create",
+  "worktree.open",
+  "worktree.remove",
+  "tab.create",
+  "tab.list",
+  "tab.get",
+  "tab.focus",
+  "tab.rename",
+  "tab.move",
+  "tab.close",
+  "agent.list",
+  "agent.get",
+  "agent.read",
+  "agent.explain",
+  "agent.send_keys",
+  "agent.rename",
+  "agent.view.set",
+  "agent.view.clear",
+  "agent.focus",
+  "agent.start",
+  "agent.prompt",
+  "agent.wait",
+  "pane.split",
+  "pane.swap",
+  "pane.move",
+  "pane.zoom",
+  "pane.layout",
+  "pane.process_info",
+  "layout.export",
+  "layout.apply",
+  "layout.set_split_ratio",
+  "pane.neighbor",
+  "pane.edges",
+  "pane.focus_direction",
+  "pane.resize",
+  "pane.scroll",
+  "pane.edit_scrollback",
+  "pane.selection.read",
+  "pane.copy_motion",
+  "pane.copy_search",
+  "pane.list",
+  "pane.current",
+  "pane.get",
+  "pane.focus",
+  "pane.input.set",
+  "pane.link.activate",
+  "pane.rename",
+  "pane.send_text",
+  "pane.send_keys",
+  "pane.send_input",
+  "pane.read",
+  "pane.graphics.set",
+  "pane.graphics.clear",
+  "pane.graphics.info",
+  "pane.report_agent",
+  "pane.report_agent_session",
+  "pane.report_metadata",
+  "pane.clear_agent_authority",
+  "pane.release_agent",
+  "pane.close",
+  "popup.close",
+  "events.subscribe",
+  "events.wait",
+  "pane.wait_for_output",
+  "integration.list",
+  "integration.install",
+  "integration.uninstall",
+  "plugin.link",
+  "plugin.list",
+  "plugin.unlink",
+  "plugin.enable",
+  "plugin.disable",
+  "plugin.action.list",
+  "plugin.action.invoke",
+  "plugin.log.list",
+  "plugin.pane.open",
+  "plugin.pane.focus",
+  "plugin.pane.close"
+];
+
+// src/herdr-streams.ts
+import { isAbsolute as isAbsolute3 } from "node:path";
+
+// src/herdr-transport.ts
 import net from "node:net";
 import { randomUUID as randomUUID5 } from "node:crypto";
-var Herdr = class {
+import { isAbsolute as isAbsolute2 } from "node:path";
+var HerdrError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "HerdrError";
+  }
+  code;
+};
+function validateSocketPath(path) {
+  if (!isAbsolute2(path) && !/^\\\\[.?]\\pipe\\[^\\]/.test(path))
+    throw new TypeError("An absolute Herdr socket path or Windows named pipe is required");
+}
+function validateTimeout(value) {
+  if (value !== null && (!Number.isFinite(value) || value <= 0 || value > 2147483647))
+    throw new TypeError("timeoutMs must be a positive bounded duration or null");
+}
+function limit(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new TypeError(`${name} must be a positive integer`);
+  return value;
+}
+var JsonConnection = class {
+  constructor(socketPath, options = {}) {
+    this.options = options;
+    validateSocketPath(socketPath);
+    this.maxMessageBytes = limit(options.maxResponseBytes ?? 32 * 1024 * 1024, "maxResponseBytes");
+    this.maxQueuedEvents = limit(options.maxQueuedEvents ?? 1024, "maxQueuedEvents");
+    this.maxQueuedBytes = limit(options.maxQueuedBytes ?? this.maxMessageBytes, "maxQueuedBytes");
+    if (options.signal?.aborted)
+      throw new HerdrError("herdr_aborted", "Herdr operation was aborted");
+    this.closed = new Promise((resolve13, reject) => {
+      this.resolveClosed = resolve13;
+      this.rejectClosed = reject;
+    });
+    void this.closed.catch(() => {
+    });
+    this.socket = net.createConnection(socketPath);
+    this.socket.setEncoding("utf8");
+    this.abort = () => this.fail(new HerdrError("herdr_aborted", "Herdr operation was aborted"), true);
+    options.signal?.addEventListener("abort", this.abort, { once: true });
+    this.socket.on(
+      "error",
+      (error) => this.fail(new HerdrError("herdr_unavailable", error.message))
+    );
+    this.socket.on("close", () => {
+      this.ended = true;
+      this.detachAbort();
+      this.rejectWrites(this.error());
+      if (this.failure || !this.explicitClose) this.rejectClosed(this.error());
+      else this.resolveClosed();
+      this.deliver();
+    });
+    this.socket.on("data", (data) => this.receive(data));
+  }
+  options;
+  id = randomUUID5();
+  closed;
+  resolveClosed;
+  rejectClosed;
+  socket;
+  buffer = "";
+  queue = [];
+  queuedBytes = 0;
+  reader;
+  writes = /* @__PURE__ */ new Set();
+  ended = false;
+  failure;
+  explicitClose = false;
+  maxMessageBytes;
+  maxQueuedEvents;
+  maxQueuedBytes;
+  abort;
+  error() {
+    return this.failure ?? new HerdrError(
+      "herdr_disconnected",
+      "Herdr disconnected before acknowledgement or stream completion"
+    );
+  }
+  detachAbort() {
+    this.options.signal?.removeEventListener("abort", this.abort);
+  }
+  rejectWrites(error) {
+    for (const reject of this.writes) reject(error);
+    this.writes.clear();
+  }
+  fail(error, discard = false) {
+    if (this.explicitClose) return;
+    this.failure ??= error;
+    this.ended = true;
+    this.buffer = "";
+    if (discard) {
+      this.queue = [];
+      this.queuedBytes = 0;
+    }
+    this.detachAbort();
+    this.socket.destroy();
+    this.rejectWrites(this.failure);
+    this.deliver();
+  }
+  close() {
+    this.explicitClose = true;
+    this.ended = true;
+    this.buffer = "";
+    this.queue = [];
+    this.queuedBytes = 0;
+    this.detachAbort();
+    this.socket.destroy();
+    this.rejectWrites(this.error());
+    this.deliver();
+  }
+  deliver() {
+    if (!this.reader) return;
+    const reader = this.reader;
+    if (this.failure) {
+      this.reader = void 0;
+      reader.reject(this.failure);
+      return;
+    }
+    const next = this.queue.shift();
+    if (next) {
+      this.reader = void 0;
+      this.queuedBytes -= next.bytes;
+      reader.resolve(next.value);
+    } else if (this.ended) {
+      this.reader = void 0;
+      if (this.explicitClose) reader.resolve(void 0);
+      else reader.reject(this.error());
+    }
+  }
+  receive(data) {
+    if (this.ended) return;
+    this.buffer += data;
+    let index;
+    while ((index = this.buffer.indexOf("\n")) >= 0) {
+      const line = this.buffer.slice(0, index);
+      this.buffer = this.buffer.slice(index + 1);
+      const bytes = Buffer.byteLength(line);
+      if (bytes > this.maxMessageBytes)
+        return this.fail(
+          new HerdrError("herdr_response_too_large", "Herdr message exceeded maxResponseBytes"),
+          true
+        );
+      let value;
+      try {
+        value = JSON.parse(line);
+      } catch (error) {
+        return this.fail(new HerdrError("herdr_invalid_response", String(error)), true);
+      }
+      if (value?.id !== void 0 && value.id !== this.id && !String(value.id).startsWith(this.id + ":"))
+        continue;
+      if (value?.error)
+        return this.fail(new HerdrError(value.error.code, value.error.message), true);
+      if (this.queue.length >= this.maxQueuedEvents || this.queuedBytes + bytes > this.maxQueuedBytes)
+        return this.fail(
+          new HerdrError(
+            "herdr_stream_overflow",
+            "Herdr consumer fell behind; stream closed without silently dropping events"
+          ),
+          true
+        );
+      this.queue.push({ value, bytes });
+      this.queuedBytes += bytes;
+      this.deliver();
+    }
+    if (Buffer.byteLength(this.buffer) > this.maxMessageBytes)
+      this.fail(
+        new HerdrError("herdr_response_too_large", "Herdr message exceeded maxResponseBytes"),
+        true
+      );
+  }
+  read() {
+    if (this.reader)
+      return Promise.reject(new Error("Only one reader may consume a Herdr connection"));
+    return new Promise((resolve13, reject) => {
+      this.reader = { resolve: resolve13, reject };
+      this.deliver();
+    });
+  }
+  write(data) {
+    if (this.ended) return Promise.reject(this.error());
+    return new Promise((resolve13, reject) => {
+      this.writes.add(reject);
+      this.socket.write(data, (error) => {
+        this.writes.delete(reject);
+        if (error) {
+          this.fail(new HerdrError("herdr_unavailable", error.message));
+          reject(this.error());
+        } else if (this.failure) reject(this.failure);
+        else resolve13();
+      });
+    });
+  }
+  async within(timeoutMs, action) {
+    validateTimeout(timeoutMs);
+    const timer = timeoutMs === null ? void 0 : setTimeout(
+      () => this.fail(
+        new HerdrError(
+          "herdr_timeout",
+          "Herdr response timed out; delivery may be ambiguous"
+        ),
+        true
+      ),
+      timeoutMs
+    );
+    try {
+      return await action();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async start(method, params, timeoutMs) {
+    return this.within(timeoutMs, async () => {
+      await this.write(JSON.stringify({ id: this.id, method, params }) + "\n");
+      const message = await this.read();
+      if (!message || message.id !== this.id || !Object.hasOwn(message, "result"))
+        throw new HerdrError("herdr_invalid_response", `${method}: missing correlated result`);
+      return message.result;
+    });
+  }
+};
+async function socketRequest(socketPath, method, params, options = {}) {
+  const timeoutMs = options.timeoutMs === void 0 ? 1e4 : options.timeoutMs;
+  validateTimeout(timeoutMs);
+  JSON.stringify(params);
+  const connection = new JsonConnection(socketPath, options);
+  try {
+    return await connection.start(method, params, timeoutMs);
+  } finally {
+    connection.close();
+  }
+}
+
+// src/herdr-streams.ts
+var HerdrEventStream = class _HerdrEventStream {
+  constructor(connection) {
+    this.connection = connection;
+  }
+  connection;
+  static async open(socketPath, subscriptions, options = {}) {
+    const timeout = options.timeoutMs === void 0 ? 1e4 : options.timeoutMs;
+    validateTimeout(timeout);
+    JSON.stringify(subscriptions);
+    const connection = new JsonConnection(socketPath, options);
+    try {
+      const result = await connection.start("events.subscribe", { subscriptions }, timeout);
+      if (result?.type !== "subscription_started")
+        throw new HerdrError("herdr_invalid_response", "Missing subscription acknowledgement");
+      return new _HerdrEventStream(connection);
+    } catch (error) {
+      connection.close();
+      throw error;
+    }
+  }
+  get closed() {
+    return this.connection.closed;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    const value = await this.connection.read();
+    if (value === void 0) return { done: true, value: void 0 };
+    if (!value || typeof value.event !== "string" || !Object.hasOwn(value, "data")) {
+      const error = new HerdrError("herdr_invalid_response", "Expected a Herdr event envelope");
+      this.connection.fail(error, true);
+      throw error;
+    }
+    return { done: false, value };
+  }
+  close() {
+    this.connection.close();
+  }
+  async return() {
+    this.close();
+    return { done: true, value: void 0 };
+  }
+};
+var maxInlineBytes = 16 * 1024 * 1024;
+function integer(value, name, min = 0, max = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value < min || value > max)
+    throw new TypeError(`Invalid ${name}`);
+}
+function frameHeader(frame) {
+  integer(frame.image_width, "image_width", 1, 4294967295);
+  integer(frame.image_height, "image_height", 1, 4294967295);
+  if (!["png", "rgb", "rgba", "bgra"].includes(frame.format))
+    throw new TypeError("Invalid frame format");
+  return {
+    format: frame.format,
+    image_width: frame.image_width,
+    image_height: frame.image_height,
+    ...frame.placement ? { placement: frame.placement } : {}
+  };
+}
+function encodeHeader(header) {
+  const line = JSON.stringify(header) + "\n";
+  if (Buffer.byteLength(line) > 64 * 1024) throw new TypeError("Graphics header exceeds 64 KiB");
+  return line;
+}
+var HerdrGraphicsStream = class _HerdrGraphicsStream {
+  constructor(connection) {
+    this.connection = connection;
+  }
+  connection;
+  busy = false;
+  static async open(socketPath, params, options = {}) {
+    const timeout = options.timeoutMs === void 0 ? 1e4 : options.timeoutMs;
+    validateTimeout(timeout);
+    JSON.stringify(params);
+    const connection = new JsonConnection(socketPath, options);
+    try {
+      const result = await connection.start("pane.graphics.stream", params, timeout);
+      if (result?.type !== "ok")
+        throw new HerdrError("herdr_invalid_response", "Missing graphics stream acknowledgement");
+      return new _HerdrGraphicsStream(connection);
+    } catch (error) {
+      connection.close();
+      throw error;
+    }
+  }
+  /** Resolves after local close; rejects on remote failure, cancellation, or disconnect. */
+  get closed() {
+    return this.connection.closed;
+  }
+  async exclusive(action) {
+    if (this.busy)
+      throw new HerdrError("herdr_stream_busy", "Await the previous frame before sending another");
+    this.busy = true;
+    try {
+      return await action();
+    } finally {
+      this.busy = false;
+    }
+  }
+  /** Resolves after local socket write, not a render ACK: inline success has no wire reply. */
+  async frame(frame, data, timeoutMs = 3e4) {
+    validateTimeout(timeoutMs);
+    if (!data.byteLength || data.byteLength > maxInlineBytes)
+      throw new TypeError("Inline graphics data must be 1 byte to 16 MiB");
+    const header = encodeHeader({ ...frameHeader(frame), data_length: data.byteLength });
+    return this.exclusive(async () => {
+      const bytes = Buffer.from(data);
+      await this.connection.within(timeoutMs, async () => {
+        await this.connection.write(header);
+        await this.connection.write(bytes);
+      });
+    });
+  }
+  /** Keep the immutable source file until this method acknowledges its sequence and revision. */
+  async fileFrame(frame, timeoutMs = 3e4) {
+    validateTimeout(timeoutMs);
+    if (!["rgba", "bgra"].includes(frame.format) || !isAbsolute3(frame.file.path))
+      throw new TypeError("File frames require rgba/bgra and an absolute source path");
+    integer(frame.sequence, "sequence");
+    integer(frame.revision, "revision");
+    const { sequence, revision } = frame;
+    const header = encodeHeader({
+      ...frameHeader(frame),
+      file: { path: frame.file.path },
+      sequence,
+      revision
+    });
+    return this.exclusive(
+      () => this.connection.within(timeoutMs, async () => {
+        await this.connection.write(header);
+        const message = await this.connection.read();
+        const result = message?.result;
+        if (message?.id !== `${this.connection.id}:file:${sequence}` || result?.type !== "pane_graphics_frame_ack" || result.sequence !== sequence || result.revision !== revision) {
+          const error = new HerdrError(
+            "herdr_invalid_response",
+            "Graphics acknowledgement did not match the file frame"
+          );
+          this.connection.fail(error, true);
+          throw error;
+        }
+        return result;
+      })
+    );
+  }
+  close() {
+    this.connection.close();
+  }
+};
+
+// src/herdr-sdk.ts
+function deadline(method, params) {
+  if (method === "agent.start") return (params.timeout_ms ?? 3e4) + 5e3;
+  const wait = method === "agent.prompt" ? params.wait : ["agent.wait", "events.wait", "pane.wait_for_output"].includes(method) ? params : void 0;
+  if (wait) return wait.timeout_ms == null ? null : wait.timeout_ms + 5e3;
+  return 1e4;
+}
+var HerdrClient = class _HerdrClient {
   constructor(socketPath) {
     this.socketPath = socketPath;
+    validateSocketPath(socketPath);
   }
   socketPath;
+  static fromEnv(env = process.env) {
+    if (env.HERDR_ENV !== "1" || !env.HERDR_SOCKET_PATH)
+      throw new Error("Run inside Herdr or supply an explicitly selected socket path");
+    return new _HerdrClient(env.HERDR_SOCKET_PATH);
+  }
+  /** Escape hatch for future one-shot methods. Streams require their dedicated transports. */
   call(method, params = {}, timeoutMs = 1e4) {
-    return new Promise((resolve13, reject) => {
-      const id = randomUUID5();
-      let buffer = "";
-      let settled2 = false;
-      const socket = net.createConnection(this.socketPath);
-      const finish = (error, result) => {
-        if (settled2) return;
-        settled2 = true;
-        clearTimeout(timer);
-        socket.destroy();
-        error ? reject(error) : resolve13(result);
-      };
-      const timer = setTimeout(
-        () => finish(
-          new AppError(
-            "herdr_timeout",
-            `${method}: response timed out; delivery may be ambiguous`,
-            503
-          )
-        ),
-        timeoutMs
-      );
-      socket.on("connect", () => socket.write(JSON.stringify({ id, method, params }) + "\n"));
-      socket.on(
-        "error",
-        (e) => finish(new AppError("herdr_unavailable", `${method}: ${e.message}`, 503))
+    if (method === "events.subscribe" || method === "pane.graphics.stream")
+      return Promise.reject(
+        new TypeError("Use subscribe(), graphicsStream(), or api for a streaming method")
       );
-      socket.on(
-        "close",
-        () => finish(
-          new AppError("herdr_disconnected", `${method}: disconnected before acknowledgement`, 503)
+    return socketRequest(this.socketPath, method, params, { timeoutMs });
+  }
+  /** All schema-defined one-shot methods with exact typed parameter objects. */
+  request(method, ...args2) {
+    const [params = {}, options = {}] = args2;
+    if (!HERDR_METHODS.includes(method) || method === "events.subscribe")
+      return Promise.reject(
+        new TypeError(
+          "Unknown one-shot method; use call() for extensions or subscribe() for events"
         )
       );
-      socket.on("data", (data) => {
-        buffer += data.toString();
-        if (buffer.length > 8 * 1024 * 1024)
-          return finish(new Error("Herdr response exceeded 8 MiB"));
-        let index;
-        while ((index = buffer.indexOf("\n")) >= 0) {
-          const line = buffer.slice(0, index);
-          buffer = buffer.slice(index + 1);
-          try {
-            const v = JSON.parse(line);
-            if (v.id !== id) continue;
-            if (v.error) finish(new AppError(v.error.code, v.error.message, 502));
-            else finish(void 0, v.result);
-          } catch (e) {
-            finish(e);
-          }
-        }
-      });
+    return socketRequest(this.socketPath, method, params, {
+      ...options,
+      timeoutMs: options.timeoutMs === void 0 ? deadline(method, params) : options.timeoutMs
     });
   }
+  subscribe(subscriptions, options) {
+    return HerdrEventStream.open(this.socketPath, subscriptions, options);
+  }
+  graphicsStream(params, options) {
+    return HerdrGraphicsStream.open(this.socketPath, params, options);
+  }
+  /** One-to-one method names, including streams, for discovery and generated agent code. */
+  api = Object.freeze(
+    Object.fromEntries([
+      ...HERDR_METHODS.map((method) => [
+        method,
+        method === "events.subscribe" ? (params, options) => this.subscribe(params.subscriptions, options) : (params = {}, options) => this.request(method, params, options)
+      ]),
+      [
+        "pane.graphics.stream",
+        (params, options) => this.graphicsStream(params, options)
+      ]
+    ])
+  );
+  workspace = {
+    list: () => this.call("workspace.list"),
+    create: (options) => this.call("workspace.create", {
+      focus: false,
+      ...options
+    })
+  };
+  tab = {
+    create: (workspaceId, options) => this.call("tab.create", {
+      focus: false,
+      ...options,
+      workspace_id: workspaceId
+    }),
+    list: (workspaceId) => this.call("tab.list", { workspace_id: workspaceId }),
+    close: (tabId) => this.call("tab.close", { tab_id: tabId })
+  };
+  pane = {
+    list: (workspaceId) => this.call("pane.list", { workspace_id: workspaceId }),
+    layout: (paneId) => this.call("pane.layout", { pane_id: paneId }),
+    split: (paneId, options) => this.call("pane.split", { focus: false, ...options, target_pane_id: paneId }),
+    read: (paneId, lines = 120) => this.call("pane.read", {
+      pane_id: paneId,
+      source: "recent_unwrapped",
+      format: "text",
+      lines
+    }),
+    sendText: (paneId, text2) => this.call("pane.send_text", { pane_id: paneId, text: text2 }),
+    sendKeys: (paneId, keys) => this.call("pane.send_keys", { pane_id: paneId, keys }),
+    close: (paneId) => this.call("pane.close", { pane_id: paneId })
+  };
+  agent = {
+    start: (paneId, name, kind, args2 = [], timeoutMs = 3e4) => this.call(
+      "agent.start",
+      { pane_id: paneId, name, kind, args: args2, timeout_ms: timeoutMs },
+      timeoutMs + 5e3
+    ),
+    get: (target) => this.call("agent.get", { target }),
+    prompt: (target, text2, wait) => this.call(
+      "agent.prompt",
+      { target, text: text2, ...wait ? { wait } : {} },
+      wait ? wait.timeout_ms + 5e3 : 1e4
+    ),
+    wait: (target, options) => this.call("agent.wait", { target, ...options }, options.timeout_ms + 5e3),
+    sendKeys: (target, keys) => this.call("agent.send_keys", { target, keys })
+  };
+};
+
+// src/herdr.ts
+var Herdr = class extends HerdrClient {
+  async call(method, params = {}, timeoutMs = 1e4) {
+    try {
+      return await super.call(method, params, timeoutMs);
+    } catch (error) {
+      if (error instanceof HerdrError)
+        throw new AppError(error.code, error.message, error.code.startsWith("herdr_") ? 503 : 502);
+      throw error;
+    }
+  }
 };
 
 // src/service.ts
@@ -31454,7 +32019,7 @@ var Service = class {
           agentArgs: external_exports.record(kindSchema, external_exports.array(external_exports.string())).default({}),
           trustAgyWorkspaces: external_exports.boolean().default(false)
         }).parse(raw);
-        if (!isAbsolute2(input.root) || !isAbsolute2(input.socketPath))
+        if (!isAbsolute4(input.root) || !isAbsolute4(input.socketPath))
           throw new AppError("absolute_paths", "root and socketPath must be absolute");
         const root = realpathSync4(input.root);
         if (!statSync4(root).isDirectory())
@@ -31701,29 +32266,55 @@ var Service = class {
               "No task prompt was attempted. Inspect the workspace and reconcile creation as not-delivered."
             );
           const project = this.project(t.projectId);
-          const tabs = (await h.call("tab.list", { workspace_id: project.workspaceId })).tabs ?? [];
-          const matches = tabs.filter(
-            (tab) => tab.workspace_id === project.workspaceId && tab.label === r.agentName
-          );
-          if (matches.length > 1)
-            throw new AppError(
-              "identity_changed",
-              "Multiple tabs match the interrupted creation; manual inspection is required",
-              409
+          if (r.creation?.mode === "pane") {
+            const all = (await h.call("pane.list", { workspace_id: project.workspaceId })).panes;
+            if (!Array.isArray(all) || !r.creation.beforePaneIds)
+              throw new AppError(
+                "identity_changed",
+                "Missing split membership; inspect the workspace",
+                409
+              );
+            const added = all.filter(
+              (pane) => !r.creation.beforePaneIds.includes(pane.pane_id)
             );
-          if (matches.length === 1) {
-            const panes = ((await h.call("pane.list", { workspace_id: project.workspaceId })).panes ?? []).filter((pane) => pane.tab_id === matches[0].tab_id);
-            if (panes.length !== 1 || panes[0].agent || panes[0].launch_pending || panes[0].workspace_id !== project.workspaceId || panes[0].cwd !== t.cwd)
+            const panes = added.filter((pane) => pane.tab_id === r.creation.tabId);
+            if (added.length !== panes.length || panes.length > 1 || panes.length === 1 && (panes[0].agent || panes[0].launch_pending || panes[0].workspace_id !== project.workspaceId || panes[0].cwd !== t.cwd))
               throw new AppError(
                 "identity_changed",
-                "The orphan tab is no longer an untouched shell; inspect it before recovery",
+                "Interrupted split is ambiguous or no longer an untouched shell; inspect it before recovery",
                 409
               );
-            Object.assign(r, {
-              paneId: panes[0].pane_id,
-              terminalId: panes[0].terminal_id,
-              tabId: panes[0].tab_id
-            });
+            if (panes.length === 1)
+              Object.assign(r, {
+                paneId: panes[0].pane_id,
+                terminalId: panes[0].terminal_id,
+                tabId: panes[0].tab_id
+              });
+          } else {
+            const tabs = (await h.call("tab.list", { workspace_id: project.workspaceId })).tabs ?? [];
+            const matches = tabs.filter(
+              (tab) => tab.workspace_id === project.workspaceId && tab.label === r.agentName
+            );
+            if (matches.length > 1)
+              throw new AppError(
+                "identity_changed",
+                "Multiple tabs match the interrupted creation; manual inspection is required",
+                409
+              );
+            if (matches.length === 1) {
+              const panes = ((await h.call("pane.list", { workspace_id: project.workspaceId })).panes ?? []).filter((pane) => pane.tab_id === matches[0].tab_id);
+              if (panes.length !== 1 || panes[0].agent || panes[0].launch_pending || panes[0].workspace_id !== project.workspaceId || panes[0].cwd !== t.cwd)
+                throw new AppError(
+                  "identity_changed",
+                  "The orphan tab is no longer an untouched shell; inspect it before recovery",
+                  409
+                );
+              Object.assign(r, {
+                paneId: panes[0].pane_id,
+                terminalId: panes[0].terminal_id,
+                tabId: panes[0].tab_id
+              });
+            }
           }
         } else {
           const a = (await h.call("agent.get", { target: r.paneId })).agent;
@@ -31919,7 +32510,7 @@ var Service = class {
         "Task directory must be within the registered root. Register external worktrees as projects."
       );
     for (const path of a.ownership) {
-      if (a.execution?.mode === "worktree" && isAbsolute2(path))
+      if (a.execution?.mode === "worktree" && isAbsolute4(path))
         throw new AppError(
           "worktree_path",
           "Worktree ownership paths must be relative to the task directory"
@@ -31933,7 +32524,7 @@ var Service = class {
     }
     for (const check of a.checks)
       if (check.type === "file") {
-        if (a.execution?.mode === "worktree" && isAbsolute2(check.path))
+        if (a.execution?.mode === "worktree" && isAbsolute4(check.path))
           throw new AppError(
             "worktree_path",
             "Worktree file checks must be relative to the task directory"
@@ -32067,6 +32658,52 @@ var Service = class {
   }
 };
 
+// src/worker-layout.ts
+async function planWorkerPane(h, workspaceId, runs) {
+  const panes = (await h.call("pane.list", { workspace_id: workspaceId })).panes;
+  if (!Array.isArray(panes)) throw new Error("Herdr did not return workspace panes");
+  const candidates = runs.filter(
+    (r) => r.terminalScope === "pane" && r.paneId && r.tabId && !r.cleanup && r.phase !== "creating"
+  );
+  for (const tabId of new Set(candidates.map((r) => r.tabId))) {
+    if (runs.some((r) => r.phase === "creating" && r.creation?.tabId === tabId)) continue;
+    const members = panes.filter((p) => p.workspace_id === workspaceId && p.tab_id === tabId);
+    if (!members.length || members.length >= 4) continue;
+    if (!members.every(
+      (p) => candidates.some(
+        (r) => r.paneId === p.pane_id && r.terminalId === p.terminal_id && r.tabId === p.tab_id
+      )
+    ))
+      continue;
+    const layout = (await h.call("pane.layout", { pane_id: members[0].pane_id })).layout;
+    if (layout?.workspace_id !== workspaceId || layout.tab_id !== tabId || !Array.isArray(layout.panes))
+      continue;
+    const choices = layout.panes.flatMap((p) => {
+      if (!members.some((m) => m.pane_id === p.pane_id)) return [];
+      const { width, height } = p.rect;
+      const right = width >= 121 && height >= 12;
+      const down = height >= 25 && width >= 60;
+      if (!right && !down) return [];
+      return [
+        {
+          paneId: p.pane_id,
+          area: width * height,
+          direction: right && (!down || width >= height * 3) ? "right" : "down"
+        }
+      ];
+    }).sort((a, b) => b.area - a.area);
+    if (choices.length)
+      return {
+        mode: "pane",
+        tabId,
+        targetPaneId: choices[0].paneId,
+        direction: choices[0].direction,
+        beforePaneIds: panes.map((p) => p.pane_id)
+      };
+  }
+  return { mode: "tab" };
+}
+
 // src/prompts.ts
 var leadContract = `Own the user's outcome through verified completion. Establish a persistent outcome with objective, explicit scope, observable criteria and required evidence before dispatch. Use criteria suited to the work: executable behavior checks for software, corroborated sources and traceable findings for research, reproducible calculations for analysis, and documented alternatives, tradeoffs and unresolved disagreements for decisions. Ask for clarification only when the evidence cannot resolve a necessary ambiguity.
 Choose exact available model profiles and an appropriate bounded collaboration strategy. Preserve a user's explicit model choice; if unavailable, report it and make any proposed fallback explicit. Stage independent council, debate or competing-proposal participants with deferStart: true, then use strategy_create to establish common evaluation criteria and release their initial assessments. Do not contaminate initial assessments by sharing another participant's conclusions. Use verified participant results in synthesis and preserve material disagreements. For later debate rounds, obtain fresh verified participant revisions before contributing their rebuttals.
@@ -32165,6 +32802,22 @@ var Supervisor = class {
   timer;
   busy = /* @__PURE__ */ new Set();
   stopped = false;
+  layouts = /* @__PURE__ */ new Map();
+  async withLayout(projectId, action) {
+    const previous = this.layouts.get(projectId) ?? Promise.resolve();
+    let release;
+    const pending = new Promise((resolve13) => {
+      release = resolve13;
+    });
+    this.layouts.set(projectId, pending);
+    await previous;
+    try {
+      return await action();
+    } finally {
+      release();
+      if (this.layouts.get(projectId) === pending) this.layouts.delete(projectId);
+    }
+  }
   start() {
     this.recover();
     this.service.continuation.recover();
@@ -32498,23 +33151,38 @@ ${JSON.stringify(children.map((child) => ({ id: child.id, title: child.title, st
       t = s.updateTask(s.task(id), { runId: run.id, attempt: run.attempt });
     });
     try {
-      const created = await h.call("tab.create", {
-        workspace_id: p.workspaceId,
-        cwd: t.cwd,
-        label: run.agentName,
-        focus: false,
-        env: { MARIONETTE_WORKER_TOKEN: token, MARIONETTE_TASK_ID: id, MARIONETTE_URL: this.url }
-      });
-      const pane = created.root_pane;
-      if (!pane?.pane_id || pane.workspace_id !== p.workspaceId)
-        throw new Error("Herdr did not return the expected scoped root pane");
-      Object.assign(run, {
-        paneId: pane.pane_id,
-        terminalId: pane.terminal_id,
-        tabId: pane.tab_id,
-        phase: "starting"
+      await this.withLayout(p.id, async () => {
+        const taskIds = new Set(s.tasks(p.id).map((task) => task.id));
+        const runs = s.store.all("run").filter((r) => taskIds.has(r.taskId) && !s.cleanup.active(r.taskId));
+        run.creation = await planWorkerPane(h, p.workspaceId, runs);
+        run.terminalScope = "pane";
+        this.saveRun(run);
+        const options = {
+          workspace_id: p.workspaceId,
+          cwd: t.cwd,
+          focus: false,
+          env: { MARIONETTE_WORKER_TOKEN: token, MARIONETTE_TASK_ID: id, MARIONETTE_URL: this.url }
+        };
+        const splitting = run.creation.mode === "pane";
+        const created = await h.call(
+          splitting ? "pane.split" : "tab.create",
+          splitting ? {
+            ...options,
+            target_pane_id: run.creation.targetPaneId,
+            direction: run.creation.direction
+          } : { ...options, label: run.agentName }
+        );
+        const pane = splitting ? created.pane : created.root_pane;
+        if (!pane?.pane_id || !pane.terminal_id || !pane.tab_id || pane.workspace_id !== p.workspaceId || splitting && (pane.tab_id !== run.creation.tabId || run.creation.beforePaneIds.includes(pane.pane_id)))
+          throw new Error("Herdr did not return the expected new scoped pane");
+        Object.assign(run, {
+          paneId: pane.pane_id,
+          terminalId: pane.terminal_id,
+          tabId: pane.tab_id,
+          phase: "starting"
+        });
+        this.saveRun(run);
       });
-      this.saveRun(run);
       for (let attempt = 0; ; attempt++) {
         try {
           await h.call(
@@ -32934,7 +33602,7 @@ ${result.output}`;
 };
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.2";
 var SETUP_VERSION = 2;
 
 // src/server.ts