acpx 0.1.0 → 0.1.3

package/dist/cli.js

@@ -2,54 +2,399 @@
 
 // src/cli.ts
 import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { realpathSync } from "fs";
+import path3 from "path";
+import { pathToFileURL } from "url";
+import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";
+
+// src/agent-registry.ts
+var AGENT_REGISTRY = {
+  codex: "npx @zed-industries/codex-acp",
+  claude: "npx @zed-industries/claude-agent-acp",
+  gemini: "gemini",
+  opencode: "npx opencode-ai",
+  pi: "npx pi-acp"
+};
+var DEFAULT_AGENT_NAME = "codex";
+function normalizeAgentName(value) {
+  return value.trim().toLowerCase();
+}
+function resolveAgentCommand(agentName) {
+  const normalized = normalizeAgentName(agentName);
+  return AGENT_REGISTRY[normalized] ?? agentName;
+}
+function listBuiltInAgents() {
+  return Object.keys(AGENT_REGISTRY);
+}
 
 // src/output.ts
+var MAX_THOUGHT_CHARS = 900;
+var MAX_INLINE_CHARS = 220;
+var MAX_OUTPUT_CHARS = 2e3;
+var MAX_OUTPUT_LINES = 28;
+var MAX_LOCATION_ITEMS = 5;
+var OUTPUT_PRIORITY_KEYS = [
+  "stdout",
+  "stderr",
+  "output",
+  "content",
+  "text",
+  "message",
+  "result",
+  "response",
+  "value"
+];
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function asStatus(status) {
   return status ?? "unknown";
 }
+function isFinalStatus(status) {
+  return status === "completed" || status === "failed";
+}
+function toStatusLabel(status) {
+  switch (status) {
+    case "in_progress":
+      return "running";
+    case "pending":
+      return "pending";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    default:
+      return "running";
+  }
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function collapseWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function truncate(value, maxChars) {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  if (maxChars <= 3) {
+    return value.slice(0, maxChars);
+  }
+  return `${value.slice(0, maxChars - 3)}...`;
+}
+function toInline(value, maxChars = MAX_INLINE_CHARS) {
+  return truncate(collapseWhitespace(value), maxChars);
+}
+function indentBlock(value, prefix) {
+  return value.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
+function dedupeStrings(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const value of values) {
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+function safeJson(value, spacing) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  try {
+    return JSON.stringify(
+      value,
+      (_key, entry) => {
+        if (typeof entry === "bigint") {
+          return `${entry}n`;
+        }
+        if (typeof entry === "function") {
+          return `[Function ${entry.name || "anonymous"}]`;
+        }
+        if (typeof entry === "symbol") {
+          return entry.toString();
+        }
+        if (entry && typeof entry === "object") {
+          if (seen.has(entry)) {
+            return "[Circular]";
+          }
+          seen.add(entry);
+        }
+        return entry;
+      },
+      spacing
+    );
+  } catch {
+    return void 0;
+  }
+}
+function readFirstString(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function readFirstStringArray(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    const entries = value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter((entry) => entry.length > 0);
+    if (entries.length > 0) {
+      return entries;
+    }
+  }
+  return void 0;
+}
+function summarizeToolInput(rawInput) {
+  if (rawInput == null) {
+    return void 0;
+  }
+  if (typeof rawInput === "string" || typeof rawInput === "number" || typeof rawInput === "boolean") {
+    return toInline(String(rawInput));
+  }
+  const record = asRecord(rawInput);
+  if (record) {
+    const command = readFirstString(record, ["command", "cmd", "program"]);
+    const args = readFirstStringArray(record, ["args", "arguments"]);
+    if (command) {
+      const invocation = [command, ...args ?? []].join(" ");
+      return toInline(invocation);
+    }
+    const location = readFirstString(record, [
+      "path",
+      "file",
+      "filePath",
+      "filepath",
+      "target",
+      "uri",
+      "url"
+    ]);
+    if (location) {
+      return toInline(location);
+    }
+    const query = readFirstString(record, ["query", "pattern", "text", "search"]);
+    if (query) {
+      return toInline(query);
+    }
+  }
+  const json = safeJson(rawInput, 0);
+  return json ? toInline(json) : void 0;
+}
+function formatLocations(locations) {
+  if (!locations || locations.length === 0) {
+    return void 0;
+  }
+  const unique = /* @__PURE__ */ new Set();
+  for (const location of locations) {
+    const path4 = location.path?.trim();
+    if (!path4) {
+      continue;
+    }
+    const line = typeof location.line === "number" && Number.isFinite(location.line) ? `:${Math.max(1, Math.trunc(location.line))}` : "";
+    unique.add(`${path4}${line}`);
+  }
+  const items = [...unique];
+  if (items.length === 0) {
+    return void 0;
+  }
+  const visible = items.slice(0, MAX_LOCATION_ITEMS);
+  const hidden = items.length - visible.length;
+  if (hidden <= 0) {
+    return visible.join(", ");
+  }
+  return `${visible.join(", ")}, +${hidden} more`;
+}
+function summarizeDiff(path4, oldText, newText) {
+  const oldLines = oldText ? oldText.split("\n").length : 0;
+  const newLines = newText.split("\n").length;
+  const delta = newLines - oldLines;
+  if (delta === 0) {
+    return `diff ${path4} (line count unchanged)`;
+  }
+  const signedDelta = `${delta > 0 ? "+" : ""}${delta}`;
+  return `diff ${path4} (${signedDelta} lines)`;
+}
+function textFromContentBlock(content) {
+  switch (content.type) {
+    case "text":
+      return content.text;
+    case "resource_link":
+      return content.title ?? content.name ?? content.uri;
+    case "resource": {
+      if ("text" in content.resource && typeof content.resource.text === "string") {
+        return content.resource.text;
+      }
+      const uri = content.resource.uri;
+      const mimeType = content.resource.mimeType;
+      return `[resource] ${uri}${mimeType ? ` (${mimeType})` : ""}`;
+    }
+    case "image":
+      return `[image] ${content.mimeType}`;
+    case "audio":
+      return `[audio] ${content.mimeType}`;
+    default:
+      return void 0;
+  }
+}
+function summarizeToolContent(content) {
+  if (!content || content.length === 0) {
+    return void 0;
+  }
+  const fragments = [];
+  for (const entry of content) {
+    if (entry.type === "content") {
+      const text = textFromContentBlock(entry.content);
+      if (text && text.trim()) {
+        fragments.push(text.trimEnd());
+      }
+      continue;
+    }
+    if (entry.type === "diff") {
+      fragments.push(summarizeDiff(entry.path, entry.oldText, entry.newText));
+      continue;
+    }
+    if (entry.type === "terminal") {
+      fragments.push(`[terminal] ${entry.terminalId}`);
+    }
+  }
+  const unique = dedupeStrings(
+    fragments.map((fragment) => fragment.trim()).filter((fragment) => fragment.length > 0)
+  );
+  if (unique.length === 0) {
+    return void 0;
+  }
+  return unique.join("\n\n");
+}
+function extractOutputText(value, depth = 0, seen = /* @__PURE__ */ new Set()) {
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trimEnd();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (depth >= 4) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    const parts = value.map((entry) => extractOutputText(entry, depth + 1, seen)).filter((entry) => Boolean(entry));
+    if (parts.length === 0) {
+      return void 0;
+    }
+    return dedupeStrings(parts).join("\n");
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return void 0;
+  }
+  if (seen.has(record)) {
+    return void 0;
+  }
+  seen.add(record);
+  const preferred = [];
+  for (const key of OUTPUT_PRIORITY_KEYS) {
+    if (!(key in record)) {
+      continue;
+    }
+    const extracted = extractOutputText(record[key], depth + 1, seen);
+    if (extracted) {
+      preferred.push(extracted);
+    }
+  }
+  const uniquePreferred = dedupeStrings(preferred);
+  if (uniquePreferred.length > 0) {
+    return uniquePreferred.join("\n");
+  }
+  const json = safeJson(record, 2);
+  if (!json || json === "{}") {
+    return void 0;
+  }
+  return json;
+}
+function summarizeToolOutput(rawOutput, content) {
+  const outputFromRaw = extractOutputText(rawOutput);
+  const outputFromContent = summarizeToolContent(content);
+  const fragments = dedupeStrings(
+    [outputFromRaw, outputFromContent].map((fragment) => fragment?.trim()).filter((fragment) => Boolean(fragment))
+  );
+  if (fragments.length === 0) {
+    return void 0;
+  }
+  return fragments.join("\n\n");
+}
+function limitOutputBlock(value) {
+  const normalized = value.replace(/\r\n/g, "\n").trim();
+  if (!normalized) {
+    return "";
+  }
+  const lines = normalized.split("\n");
+  const visible = lines.slice(0, MAX_OUTPUT_LINES);
+  let result = visible.join("\n");
+  if (lines.length > visible.length) {
+    const hidden = lines.length - visible.length;
+    result += `
+... (${hidden} more lines)`;
+  }
+  if (result.length > MAX_OUTPUT_CHARS) {
+    result = `${result.slice(0, MAX_OUTPUT_CHARS - 3)}...`;
+  }
+  return result;
+}
 var TextOutputFormatter = class {
   stdout;
+  useColor;
+  toolStates = /* @__PURE__ */ new Map();
+  thoughtBuffer = "";
+  wroteAny = false;
+  atLineStart = true;
+  section = null;
   constructor(stdout) {
     this.stdout = stdout;
+    this.useColor = Boolean(stdout.isTTY);
   }
   onSessionUpdate(notification) {
     const update = notification.update;
+    if (update.sessionUpdate !== "agent_thought_chunk") {
+      this.flushThoughtBuffer();
+    }
     switch (update.sessionUpdate) {
       case "agent_message_chunk": {
         if (update.content.type === "text") {
-          this.stdout.write(update.content.text);
+          this.writeAssistantChunk(update.content.text);
         }
         return;
       }
       case "agent_thought_chunk": {
         if (update.content.type === "text") {
-          this.stdout.write(`
-[thought] ${update.content.text}
-`);
+          this.thoughtBuffer += update.content.text;
         }
         return;
       }
       case "tool_call": {
-        this.stdout.write(`
-[tool] ${update.title} (${asStatus(update.status)})
-`);
+        this.renderToolUpdate(update);
         return;
       }
       case "tool_call_update": {
-        const title = update.title ?? update.toolCallId;
-        this.stdout.write(`
-[tool] ${title} (${asStatus(update.status)})
-`);
+        this.renderToolUpdate(update);
         return;
       }
       case "plan": {
-        this.stdout.write("\n[plan]\n");
+        this.beginSection("plan");
+        this.writeLine(this.bold("[plan]"));
         for (const entry of update.entries) {
-          this.stdout.write(`- (${entry.status}) ${entry.content}
-`);
+          this.writeLine(`  - [${entry.status}] ${entry.content}`);
         }
         return;
       }
@@ -58,11 +403,181 @@ var TextOutputFormatter = class {
     }
   }
   onDone(stopReason) {
-    this.stdout.write(`
-[done] ${stopReason}
-`);
+    this.flushThoughtBuffer();
+    this.beginSection("done");
+    this.writeLine(this.dim(`[done] ${stopReason}`));
   }
   flush() {
+    this.flushThoughtBuffer();
+    if (!this.atLineStart) {
+      this.write("\n");
+    }
+  }
+  write(chunk) {
+    if (!chunk) {
+      return;
+    }
+    this.stdout.write(chunk);
+    this.wroteAny = true;
+    this.atLineStart = chunk.endsWith("\n");
+  }
+  writeLine(line) {
+    this.write(`${line}
+`);
+  }
+  beginSection(next) {
+    if (!this.atLineStart) {
+      this.write("\n");
+    }
+    if (this.wroteAny) {
+      this.write("\n");
+    }
+    this.section = next;
+  }
+  writeAssistantChunk(text) {
+    if (!text) {
+      return;
+    }
+    this.section = "assistant";
+    this.write(text);
+  }
+  flushThoughtBuffer() {
+    const thought = truncate(collapseWhitespace(this.thoughtBuffer), MAX_THOUGHT_CHARS);
+    this.thoughtBuffer = "";
+    if (!thought) {
+      return;
+    }
+    this.beginSection("thought");
+    this.writeLine(this.dim(`[thinking] ${thought}`));
+  }
+  renderToolUpdate(update) {
+    const state = this.getOrCreateToolState(update.toolCallId);
+    this.mergeToolState(state, update);
+    const status = asStatus(state.status);
+    if (isFinalStatus(status)) {
+      const signature = this.toolSignature(state);
+      if (signature !== state.finalSignature) {
+        state.finalSignature = signature;
+        this.renderFinalToolState(state, status);
+      }
+      return;
+    }
+    if (state.startedPrinted) {
+      return;
+    }
+    state.startedPrinted = true;
+    this.renderStartingToolState(state, status);
+  }
+  getOrCreateToolState(toolCallId) {
+    const existing = this.toolStates.get(toolCallId);
+    if (existing) {
+      return existing;
+    }
+    const created = {
+      id: toolCallId,
+      startedPrinted: false
+    };
+    this.toolStates.set(toolCallId, created);
+    return created;
+  }
+  mergeToolState(state, update) {
+    if (typeof update.title === "string" && update.title.trim().length > 0) {
+      state.title = update.title;
+    }
+    if (update.status !== void 0) {
+      state.status = update.status;
+    }
+    if (update.kind !== void 0) {
+      state.kind = update.kind;
+    }
+    if (update.locations !== void 0) {
+      state.locations = update.locations;
+    }
+    if (update.rawInput !== void 0) {
+      state.rawInput = update.rawInput;
+    }
+    if (update.rawOutput !== void 0) {
+      state.rawOutput = update.rawOutput;
+    }
+    if (update.content !== void 0) {
+      state.content = update.content;
+    }
+  }
+  toolSignature(state) {
+    const signaturePayload = {
+      title: state.title,
+      status: state.status,
+      kind: state.kind,
+      input: summarizeToolInput(state.rawInput),
+      files: formatLocations(state.locations),
+      output: summarizeToolOutput(state.rawOutput, state.content)
+    };
+    return safeJson(signaturePayload, 0) ?? JSON.stringify(signaturePayload);
+  }
+  renderStartingToolState(state, status) {
+    this.beginSection("tool");
+    const title = state.title ?? state.id;
+    const label = status === "pending" ? "pending" : "running";
+    const statusText = this.colorStatus(label, status);
+    this.writeLine(`${this.bold("[tool]")} ${title} (${statusText})`);
+    const input = summarizeToolInput(state.rawInput);
+    if (input) {
+      this.writeLine(`  input: ${input}`);
+    }
+    const files = formatLocations(state.locations);
+    if (files) {
+      this.writeLine(`  files: ${files}`);
+    }
+  }
+  renderFinalToolState(state, status) {
+    this.beginSection("tool");
+    const title = state.title ?? state.id;
+    const statusText = this.colorStatus(toStatusLabel(status), status);
+    this.writeLine(`${this.bold("[tool]")} ${title} (${statusText})`);
+    if (state.kind) {
+      this.writeLine(`  kind: ${state.kind}`);
+    }
+    const input = summarizeToolInput(state.rawInput);
+    if (input) {
+      this.writeLine(`  input: ${input}`);
+    }
+    const files = formatLocations(state.locations);
+    if (files) {
+      this.writeLine(`  files: ${files}`);
+    }
+    const output = summarizeToolOutput(state.rawOutput, state.content);
+    if (output) {
+      this.writeLine("  output:");
+      this.writeLine(indentBlock(limitOutputBlock(output), "    "));
+    }
+  }
+  formatAnsi(text, code) {
+    if (!this.useColor) {
+      return text;
+    }
+    return `\x1B[${code}m${text}\x1B[0m`;
+  }
+  bold(text) {
+    return this.formatAnsi(text, "1");
+  }
+  dim(text) {
+    return this.formatAnsi(text, "2");
+  }
+  colorStatus(text, status) {
+    if (!this.useColor) {
+      return text;
+    }
+    switch (status) {
+      case "completed":
+        return this.formatAnsi(text, "32");
+      case "failed":
+        return this.formatAnsi(text, "31");
+      case "pending":
+      case "in_progress":
+      case "unknown":
+      default:
+        return this.formatAnsi(text, "33");
+    }
   }
 };
 var JsonOutputFormatter = class {
@@ -190,7 +705,9 @@ function createOutputFormatter(format, options = {}) {
 }
 
 // src/session.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
 import fs2 from "fs/promises";
+import net from "net";
 import os from "os";
 import path2 from "path";
 
@@ -200,9 +717,7 @@ import {
   PROTOCOL_VERSION,
   ndJsonStream
 } from "@agentclientprotocol/sdk";
-import {
-  spawn
-} from "child_process";
+import { spawn } from "child_process";
 import { randomUUID } from "crypto";
 import fs from "fs/promises";
 import path from "path";
@@ -463,9 +978,15 @@ var AcpClient = class {
     this.log(`spawning agent: ${command} ${args.join(" ")}`);
     const child = spawn(command, args, {
       cwd: this.options.cwd,
-      stdio: ["pipe", "pipe", "inherit"]
+      stdio: ["pipe", "pipe", "pipe"]
     });
     await waitForSpawn(child);
+    child.stderr.on("data", (chunk) => {
+      if (!this.options.verbose) {
+        return;
+      }
+      process.stderr.write(chunk);
+    });
     const input = Writable.toWeb(child.stdin);
     const output = Readable.toWeb(child.stdout);
     const stream = ndJsonStream(input, output);
@@ -777,8 +1298,12 @@ var AcpClient = class {
 
 // src/session.ts
 var SESSION_BASE_DIR = path2.join(os.homedir(), ".acpx", "sessions");
+var QUEUE_BASE_DIR = path2.join(os.homedir(), ".acpx", "queues");
 var PROCESS_EXIT_GRACE_MS = 1500;
 var PROCESS_POLL_MS = 50;
+var QUEUE_CONNECT_ATTEMPTS = 40;
+var QUEUE_CONNECT_RETRY_MS = 50;
+var DEFAULT_QUEUE_OWNER_TTL_MS = 3e5;
 var TimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Timed out after ${timeoutMs}ms`);
@@ -851,8 +1376,11 @@ function parseSessionRecord(raw) {
     return null;
   }
   const record = raw;
+  const name = record.name == null ? void 0 : typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : null;
   const pid = record.pid == null ? void 0 : Number.isInteger(record.pid) && record.pid > 0 ? record.pid : null;
-  if (typeof record.id !== "string" || typeof record.sessionId !== "string" || typeof record.agentCommand !== "string" || typeof record.cwd !== "string" || typeof record.createdAt !== "string" || typeof record.lastUsedAt !== "string" || pid === null) {
+  const closed = record.closed == null ? false : typeof record.closed === "boolean" ? record.closed : null;
+  const closedAt = record.closedAt == null ? void 0 : typeof record.closedAt === "string" ? record.closedAt : null;
+  if (typeof record.id !== "string" || typeof record.sessionId !== "string" || typeof record.agentCommand !== "string" || typeof record.cwd !== "string" || name === null || typeof record.createdAt !== "string" || typeof record.lastUsedAt !== "string" || pid === null || closed === null || closedAt === null) {
     return null;
   }
   return {
@@ -861,8 +1389,11 @@ function parseSessionRecord(raw) {
     sessionId: record.sessionId,
     agentCommand: record.agentCommand,
     cwd: record.cwd,
+    name,
     createdAt: record.createdAt,
     lastUsedAt: record.lastUsedAt,
+    closed,
+    closedAt,
     pid
   };
 }
@@ -917,9 +1448,25 @@ function toPromptResult(stopReason, sessionId, client) {
 function absolutePath(value) {
   return path2.resolve(value);
 }
+function normalizeName(value) {
+  if (value == null) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
 function isoNow() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function normalizeQueueOwnerTtlMs(ttlMs) {
+  if (ttlMs == null) {
+    return DEFAULT_QUEUE_OWNER_TTL_MS;
+  }
+  if (!Number.isFinite(ttlMs) || ttlMs < 0) {
+    return DEFAULT_QUEUE_OWNER_TTL_MS;
+  }
+  return Math.round(ttlMs);
+}
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -1017,89 +1564,682 @@ async function isLikelyMatchingProcess(pid, agentCommand) {
     return true;
   }
 }
-async function runOnce(options) {
-  const output = options.outputFormatter;
-  const client = new AcpClient({
-    agentCommand: options.agentCommand,
-    cwd: absolutePath(options.cwd),
-    permissionMode: options.permissionMode,
-    verbose: options.verbose,
-    onSessionUpdate: (notification) => output.onSessionUpdate(notification)
-  });
-  try {
-    return await withInterrupt(
-      async () => {
-        await withTimeout(client.start(), options.timeoutMs);
-        const sessionId = await withTimeout(
-          client.createSession(absolutePath(options.cwd)),
-          options.timeoutMs
-        );
-        const response = await withTimeout(
-          client.prompt(sessionId, options.message),
-          options.timeoutMs
-        );
-        output.onDone(response.stopReason);
-        output.flush();
-        return toPromptResult(response.stopReason, sessionId, client);
-      },
-      async () => {
-        await client.close();
-      }
-    );
-  } finally {
-    await client.close();
+function asRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
   }
+  return value;
 }
-async function createSession(options) {
-  const client = new AcpClient({
-    agentCommand: options.agentCommand,
-    cwd: absolutePath(options.cwd),
-    permissionMode: options.permissionMode,
-    verbose: options.verbose
-  });
-  try {
-    return await withInterrupt(
-      async () => {
-        await withTimeout(client.start(), options.timeoutMs);
-        const sessionId = await withTimeout(
-          client.createSession(absolutePath(options.cwd)),
-          options.timeoutMs
-        );
-        const now = isoNow();
-        const record = {
-          id: sessionId,
-          sessionId,
-          agentCommand: options.agentCommand,
-          cwd: absolutePath(options.cwd),
-          createdAt: now,
-          lastUsedAt: now,
-          pid: client.getAgentPid(),
-          protocolVersion: client.initializeResult?.protocolVersion,
-          agentCapabilities: client.initializeResult?.agentCapabilities
-        };
-        await writeSessionRecord(record);
-        return record;
-      },
-      async () => {
-        await client.close();
-      }
-    );
-  } finally {
-    await client.close();
+function isPermissionMode(value) {
+  return value === "approve-all" || value === "approve-reads" || value === "deny-all";
+}
+function parseQueueOwnerRecord(raw) {
+  const record = asRecord2(raw);
+  if (!record) {
+    return null;
   }
+  if (!Number.isInteger(record.pid) || record.pid <= 0 || typeof record.sessionId !== "string" || typeof record.socketPath !== "string") {
+    return null;
+  }
+  return {
+    pid: record.pid,
+    sessionId: record.sessionId,
+    socketPath: record.socketPath
+  };
 }
-async function sendSession(options) {
-  const output = options.outputFormatter;
-  const record = await resolveSessionRecord(options.sessionId);
-  const storedProcessAlive = isProcessAlive(record.pid);
-  if (storedProcessAlive && options.verbose) {
-    process.stderr.write(
-      `[acpx] saved session pid ${record.pid} is running; reconnecting with loadSession
-`
-    );
+function parseQueueSubmitRequest(raw) {
+  const request = asRecord2(raw);
+  if (!request) {
+    return null;
   }
-  const client = new AcpClient({
-    agentCommand: record.agentCommand,
+  if (request.type !== "submit_prompt" || typeof request.requestId !== "string" || typeof request.message !== "string" || !isPermissionMode(request.permissionMode) || typeof request.waitForCompletion !== "boolean") {
+    return null;
+  }
+  const timeoutRaw = request.timeoutMs;
+  const timeoutMs = typeof timeoutRaw === "number" && Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? Math.round(timeoutRaw) : void 0;
+  return {
+    type: "submit_prompt",
+    requestId: request.requestId,
+    message: request.message,
+    permissionMode: request.permissionMode,
+    timeoutMs,
+    waitForCompletion: request.waitForCompletion
+  };
+}
+function parseSessionSendResult(raw) {
+  const result = asRecord2(raw);
+  if (!result) {
+    return null;
+  }
+  if (typeof result.stopReason !== "string" || typeof result.sessionId !== "string" || typeof result.resumed !== "boolean") {
+    return null;
+  }
+  const permissionStats = asRecord2(result.permissionStats);
+  const record = asRecord2(result.record);
+  if (!permissionStats || !record) {
+    return null;
+  }
+  const statsValid = typeof permissionStats.requested === "number" && typeof permissionStats.approved === "number" && typeof permissionStats.denied === "number" && typeof permissionStats.cancelled === "number";
+  if (!statsValid) {
+    return null;
+  }
+  const recordValid = typeof record.id === "string" && typeof record.sessionId === "string" && typeof record.agentCommand === "string" && typeof record.cwd === "string" && typeof record.createdAt === "string" && typeof record.lastUsedAt === "string";
+  if (!recordValid) {
+    return null;
+  }
+  return result;
+}
+function parseQueueOwnerMessage(raw) {
+  const message = asRecord2(raw);
+  if (!message || typeof message.type !== "string") {
+    return null;
+  }
+  if (typeof message.requestId !== "string") {
+    return null;
+  }
+  if (message.type === "accepted") {
+    return {
+      type: "accepted",
+      requestId: message.requestId
+    };
+  }
+  if (message.type === "session_update") {
+    const notification = message.notification;
+    if (!notification || typeof notification !== "object") {
+      return null;
+    }
+    return {
+      type: "session_update",
+      requestId: message.requestId,
+      notification
+    };
+  }
+  if (message.type === "done") {
+    if (typeof message.stopReason !== "string") {
+      return null;
+    }
+    return {
+      type: "done",
+      requestId: message.requestId,
+      stopReason: message.stopReason
+    };
+  }
+  if (message.type === "result") {
+    const parsedResult = parseSessionSendResult(message.result);
+    if (!parsedResult) {
+      return null;
+    }
+    return {
+      type: "result",
+      requestId: message.requestId,
+      result: parsedResult
+    };
+  }
+  if (message.type === "error") {
+    if (typeof message.message !== "string") {
+      return null;
+    }
+    return {
+      type: "error",
+      requestId: message.requestId,
+      message: message.message
+    };
+  }
+  return null;
+}
+function queueKeyForSession(sessionId) {
+  return createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
+}
+function queueLockFilePath(sessionId) {
+  return path2.join(QUEUE_BASE_DIR, `${queueKeyForSession(sessionId)}.lock`);
+}
+function queueSocketPath(sessionId) {
+  const key = queueKeyForSession(sessionId);
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\acpx-${key}`;
+  }
+  return path2.join(QUEUE_BASE_DIR, `${key}.sock`);
+}
+async function ensureQueueDir() {
+  await fs2.mkdir(QUEUE_BASE_DIR, { recursive: true });
+}
+async function removeSocketFile(socketPath) {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    await fs2.unlink(socketPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function readQueueOwnerRecord(sessionId) {
+  const lockPath = queueLockFilePath(sessionId);
+  try {
+    const payload = await fs2.readFile(lockPath, "utf8");
+    const parsed = parseQueueOwnerRecord(JSON.parse(payload));
+    return parsed ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function cleanupStaleQueueOwner(sessionId, owner) {
+  const lockPath = queueLockFilePath(sessionId);
+  const socketPath = owner?.socketPath ?? queueSocketPath(sessionId);
+  await removeSocketFile(socketPath).catch(() => {
+  });
+  await fs2.unlink(lockPath).catch((error) => {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+async function tryAcquireQueueOwnerLease(sessionId) {
+  await ensureQueueDir();
+  const lockPath = queueLockFilePath(sessionId);
+  const socketPath = queueSocketPath(sessionId);
+  const payload = JSON.stringify(
+    {
+      pid: process.pid,
+      sessionId,
+      socketPath,
+      createdAt: isoNow()
+    },
+    null,
+    2
+  );
+  try {
+    await fs2.writeFile(lockPath, `${payload}
+`, {
+      encoding: "utf8",
+      flag: "wx"
+    });
+    await removeSocketFile(socketPath).catch(() => {
+    });
+    return { lockPath, socketPath };
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+    const owner = await readQueueOwnerRecord(sessionId);
+    if (!owner || !isProcessAlive(owner.pid)) {
+      await cleanupStaleQueueOwner(sessionId, owner);
+    }
+    return void 0;
+  }
+}
+async function releaseQueueOwnerLease(lease) {
+  await removeSocketFile(lease.socketPath).catch(() => {
+  });
+  await fs2.unlink(lease.lockPath).catch((error) => {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+function shouldRetryQueueConnect(error) {
+  const code = error.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+}
+async function waitMs(ms) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function connectToSocket(socketPath) {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    const onConnect = () => {
+      socket.off("error", onError);
+      resolve(socket);
+    };
+    const onError = (error) => {
+      socket.off("connect", onConnect);
+      reject(error);
+    };
+    socket.once("connect", onConnect);
+    socket.once("error", onError);
+  });
+}
+async function connectToQueueOwner(owner) {
+  let lastError;
+  for (let attempt = 0; attempt < QUEUE_CONNECT_ATTEMPTS; attempt += 1) {
+    try {
+      return await connectToSocket(owner.socketPath);
+    } catch (error) {
+      lastError = error;
+      if (!shouldRetryQueueConnect(error)) {
+        throw error;
+      }
+      if (!isProcessAlive(owner.pid)) {
+        return void 0;
+      }
+      await waitMs(QUEUE_CONNECT_RETRY_MS);
+    }
+  }
+  if (lastError && !shouldRetryQueueConnect(lastError)) {
+    throw lastError;
+  }
+  return void 0;
+}
+function writeQueueMessage(socket, message) {
+  if (socket.destroyed || !socket.writable) {
+    return;
+  }
+  socket.write(`${JSON.stringify(message)}
+`);
+}
+var QueueTaskOutputFormatter = class {
+  requestId;
+  send;
+  constructor(task) {
+    this.requestId = task.requestId;
+    this.send = task.send;
+  }
+  onSessionUpdate(notification) {
+    this.send({
+      type: "session_update",
+      requestId: this.requestId,
+      notification
+    });
+  }
+  onDone(stopReason) {
+    this.send({
+      type: "done",
+      requestId: this.requestId,
+      stopReason
+    });
+  }
+  flush() {
+  }
+};
+var DISCARD_OUTPUT_FORMATTER = {
+  onSessionUpdate() {
+  },
+  onDone() {
+  },
+  flush() {
+  }
+};
+var SessionQueueOwner = class _SessionQueueOwner {
+  server;
+  pending = [];
+  waiters = [];
+  closed = false;
+  constructor(server) {
+    this.server = server;
+  }
+  static async start(lease) {
+    const ownerRef = { current: void 0 };
+    const server = net.createServer((socket) => {
+      ownerRef.current?.handleConnection(socket);
+    });
+    ownerRef.current = new _SessionQueueOwner(server);
+    await new Promise((resolve, reject) => {
+      const onListening = () => {
+        server.off("error", onError);
+        resolve();
+      };
+      const onError = (error) => {
+        server.off("listening", onListening);
+        reject(error);
+      };
+      server.once("listening", onListening);
+      server.once("error", onError);
+      server.listen(lease.socketPath);
+    });
+    return ownerRef.current;
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter(void 0);
+    }
+    for (const task of this.pending.splice(0)) {
+      if (task.waitForCompletion) {
+        task.send({
+          type: "error",
+          requestId: task.requestId,
+          message: "Queue owner shutting down before prompt execution"
+        });
+      }
+      task.close();
+    }
+    await new Promise((resolve) => {
+      this.server.close(() => resolve());
+    });
+  }
+  async nextTask(timeoutMs) {
+    if (this.pending.length > 0) {
+      return this.pending.shift();
+    }
+    if (this.closed) {
+      return void 0;
+    }
+    return await new Promise((resolve) => {
+      const shouldTimeout = timeoutMs != null;
+      const timer = shouldTimeout && setTimeout(
+        () => {
+          const index = this.waiters.indexOf(waiter);
+          if (index >= 0) {
+            this.waiters.splice(index, 1);
+          }
+          resolve(void 0);
+        },
+        Math.max(0, timeoutMs)
+      );
+      const waiter = (task) => {
+        if (timer) {
+          clearTimeout(timer);
+        }
+        resolve(task);
+      };
+      this.waiters.push(waiter);
+    });
+  }
+  enqueue(task) {
+    if (this.closed) {
+      if (task.waitForCompletion) {
+        task.send({
+          type: "error",
+          requestId: task.requestId,
+          message: "Queue owner is shutting down"
+        });
+      }
+      task.close();
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter(task);
+      return;
+    }
+    this.pending.push(task);
+  }
+  handleConnection(socket) {
+    socket.setEncoding("utf8");
+    if (this.closed) {
+      writeQueueMessage(socket, {
+        type: "error",
+        requestId: "unknown",
+        message: "Queue owner is closed"
+      });
+      socket.end();
+      return;
+    }
+    let buffer = "";
+    let handled = false;
+    const fail = (requestId, message) => {
+      writeQueueMessage(socket, {
+        type: "error",
+        requestId,
+        message
+      });
+      socket.end();
+    };
+    const processLine = (line) => {
+      if (handled) {
+        return;
+      }
+      handled = true;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        fail("unknown", "Invalid queue request payload");
+        return;
+      }
+      const request = parseQueueSubmitRequest(parsed);
+      if (!request) {
+        fail("unknown", "Invalid queue request");
+        return;
+      }
+      const task = {
+        requestId: request.requestId,
+        message: request.message,
+        permissionMode: request.permissionMode,
+        timeoutMs: request.timeoutMs,
+        waitForCompletion: request.waitForCompletion,
+        send: (message) => {
+          writeQueueMessage(socket, message);
+        },
+        close: () => {
+          if (!socket.destroyed) {
+            socket.end();
+          }
+        }
+      };
+      writeQueueMessage(socket, {
+        type: "accepted",
+        requestId: request.requestId
+      });
+      if (!request.waitForCompletion) {
+        task.close();
+      }
+      this.enqueue(task);
+    };
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      let index = buffer.indexOf("\n");
+      while (index >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (line.length > 0) {
+          processLine(line);
+        }
+        index = buffer.indexOf("\n");
+      }
+    });
+    socket.on("error", () => {
+    });
+  }
+};
+async function submitToQueueOwner(owner, options) {
+  const socket = await connectToQueueOwner(owner);
+  if (!socket) {
+    return void 0;
+  }
+  socket.setEncoding("utf8");
+  const requestId = randomUUID2();
+  const request = {
+    type: "submit_prompt",
+    requestId,
+    message: options.message,
+    permissionMode: options.permissionMode,
+    timeoutMs: options.timeoutMs,
+    waitForCompletion: options.waitForCompletion
+  };
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    let acknowledged = false;
+    let buffer = "";
+    let sawDone = false;
+    const finishResolve = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.removeAllListeners();
+      if (!socket.destroyed) {
+        socket.end();
+      }
+      resolve(result);
+    };
+    const finishReject = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.removeAllListeners();
+      if (!socket.destroyed) {
+        socket.destroy();
+      }
+      reject(error);
+    };
+    const processLine = (line) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        finishReject(new Error("Queue owner sent invalid JSON payload"));
+        return;
+      }
+      const message = parseQueueOwnerMessage(parsed);
+      if (!message || message.requestId !== requestId) {
+        finishReject(new Error("Queue owner sent malformed message"));
+        return;
+      }
+      if (message.type === "accepted") {
+        acknowledged = true;
+        if (!options.waitForCompletion) {
+          const queued = {
+            queued: true,
+            sessionId: options.sessionId,
+            requestId
+          };
+          finishResolve(queued);
+        }
+        return;
+      }
+      if (!acknowledged) {
+        finishReject(new Error("Queue owner did not acknowledge request"));
+        return;
+      }
+      if (message.type === "session_update") {
+        options.outputFormatter.onSessionUpdate(message.notification);
+        return;
+      }
+      if (message.type === "done") {
+        options.outputFormatter.onDone(message.stopReason);
+        sawDone = true;
+        return;
+      }
+      if (message.type === "result") {
+        if (!sawDone) {
+          options.outputFormatter.onDone(message.result.stopReason);
+        }
+        options.outputFormatter.flush();
+        finishResolve(message.result);
+        return;
+      }
+      finishReject(new Error(message.message));
+    };
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      let index = buffer.indexOf("\n");
+      while (index >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (line.length > 0) {
+          processLine(line);
+        }
+        index = buffer.indexOf("\n");
+      }
+    });
+    socket.once("error", (error) => {
+      finishReject(error);
+    });
+    socket.once("close", () => {
+      if (settled) {
+        return;
+      }
+      if (!acknowledged) {
+        finishReject(
+          new Error("Queue owner disconnected before acknowledging request")
+        );
+        return;
+      }
+      if (!options.waitForCompletion) {
+        const queued = {
+          queued: true,
+          sessionId: options.sessionId,
+          requestId
+        };
+        finishResolve(queued);
+        return;
+      }
+      finishReject(new Error("Queue owner disconnected before prompt completion"));
+    });
+    socket.write(`${JSON.stringify(request)}
+`);
+  });
+}
+async function trySubmitToRunningOwner(options) {
+  const owner = await readQueueOwnerRecord(options.sessionId);
+  if (!owner) {
+    return void 0;
+  }
+  if (!isProcessAlive(owner.pid)) {
+    await cleanupStaleQueueOwner(options.sessionId, owner);
+    return void 0;
+  }
+  const submitted = await submitToQueueOwner(owner, options);
+  if (submitted) {
+    if (options.verbose) {
+      process.stderr.write(
+        `[acpx] queued prompt on active owner pid ${owner.pid} for session ${options.sessionId}
+`
+      );
+    }
+    return submitted;
+  }
+  if (!isProcessAlive(owner.pid)) {
+    await cleanupStaleQueueOwner(options.sessionId, owner);
+    return void 0;
+  }
+  throw new Error("Session queue owner is running but not accepting queue requests");
+}
+async function runQueuedTask(sessionRecordId, task, verbose) {
+  const outputFormatter = task.waitForCompletion ? new QueueTaskOutputFormatter(task) : DISCARD_OUTPUT_FORMATTER;
+  try {
+    const result = await runSessionPrompt({
+      sessionRecordId,
+      message: task.message,
+      permissionMode: task.permissionMode,
+      outputFormatter,
+      timeoutMs: task.timeoutMs,
+      verbose
+    });
+    if (task.waitForCompletion) {
+      task.send({
+        type: "result",
+        requestId: task.requestId,
+        result
+      });
+    }
+  } catch (error) {
+    const message = formatError(error);
+    if (task.waitForCompletion) {
+      task.send({
+        type: "error",
+        requestId: task.requestId,
+        message
+      });
+    }
+    if (error instanceof InterruptedError) {
+      throw error;
+    }
+  } finally {
+    task.close();
+  }
+}
+async function runSessionPrompt(options) {
+  const output = options.outputFormatter;
+  const record = await resolveSessionRecord(options.sessionRecordId);
+  const storedProcessAlive = isProcessAlive(record.pid);
+  if (storedProcessAlive && options.verbose) {
+    process.stderr.write(
+      `[acpx] saved session pid ${record.pid} is running; reconnecting with loadSession
+`
+    );
+  }
+  const client = new AcpClient({
+    agentCommand: record.agentCommand,
     cwd: absolutePath(record.cwd),
     permissionMode: options.permissionMode,
     verbose: options.verbose,
@@ -1144,18 +2284,94 @@ async function sendSession(options) {
           client.prompt(activeSessionId, options.message),
           options.timeoutMs
         );
-        output.onDone(response.stopReason);
-        output.flush();
-        record.lastUsedAt = isoNow();
-        record.protocolVersion = client.initializeResult?.protocolVersion;
-        record.agentCapabilities = client.initializeResult?.agentCapabilities;
-        await writeSessionRecord(record);
-        return {
-          ...toPromptResult(response.stopReason, record.id, client),
-          record,
-          resumed,
-          loadError
+        output.onDone(response.stopReason);
+        output.flush();
+        record.lastUsedAt = isoNow();
+        record.closed = false;
+        record.closedAt = void 0;
+        record.protocolVersion = client.initializeResult?.protocolVersion;
+        record.agentCapabilities = client.initializeResult?.agentCapabilities;
+        await writeSessionRecord(record);
+        return {
+          ...toPromptResult(response.stopReason, record.id, client),
+          record,
+          resumed,
+          loadError
+        };
+      },
+      async () => {
+        await client.close();
+      }
+    );
+  } finally {
+    await client.close();
+  }
+}
+async function runOnce(options) {
+  const output = options.outputFormatter;
+  const client = new AcpClient({
+    agentCommand: options.agentCommand,
+    cwd: absolutePath(options.cwd),
+    permissionMode: options.permissionMode,
+    verbose: options.verbose,
+    onSessionUpdate: (notification) => output.onSessionUpdate(notification)
+  });
+  try {
+    return await withInterrupt(
+      async () => {
+        await withTimeout(client.start(), options.timeoutMs);
+        const sessionId = await withTimeout(
+          client.createSession(absolutePath(options.cwd)),
+          options.timeoutMs
+        );
+        const response = await withTimeout(
+          client.prompt(sessionId, options.message),
+          options.timeoutMs
+        );
+        output.onDone(response.stopReason);
+        output.flush();
+        return toPromptResult(response.stopReason, sessionId, client);
+      },
+      async () => {
+        await client.close();
+      }
+    );
+  } finally {
+    await client.close();
+  }
+}
+async function createSession(options) {
+  const client = new AcpClient({
+    agentCommand: options.agentCommand,
+    cwd: absolutePath(options.cwd),
+    permissionMode: options.permissionMode,
+    verbose: options.verbose
+  });
+  try {
+    return await withInterrupt(
+      async () => {
+        await withTimeout(client.start(), options.timeoutMs);
+        const sessionId = await withTimeout(
+          client.createSession(absolutePath(options.cwd)),
+          options.timeoutMs
+        );
+        const now = isoNow();
+        const record = {
+          id: sessionId,
+          sessionId,
+          agentCommand: options.agentCommand,
+          cwd: absolutePath(options.cwd),
+          name: normalizeName(options.name),
+          createdAt: now,
+          lastUsedAt: now,
+          closed: false,
+          closedAt: void 0,
+          pid: client.getAgentPid(),
+          protocolVersion: client.initializeResult?.protocolVersion,
+          agentCapabilities: client.initializeResult?.agentCapabilities
         };
+        await writeSessionRecord(record);
+        return record;
       },
       async () => {
         await client.close();
@@ -1165,6 +2381,73 @@ async function sendSession(options) {
     await client.close();
   }
 }
+async function sendSession(options) {
+  const waitForCompletion = options.waitForCompletion !== false;
+  const queueOwnerTtlMs = normalizeQueueOwnerTtlMs(options.ttlMs);
+  const queuedToOwner = await trySubmitToRunningOwner({
+    sessionId: options.sessionId,
+    message: options.message,
+    permissionMode: options.permissionMode,
+    outputFormatter: options.outputFormatter,
+    timeoutMs: options.timeoutMs,
+    waitForCompletion,
+    verbose: options.verbose
+  });
+  if (queuedToOwner) {
+    return queuedToOwner;
+  }
+  for (; ; ) {
+    const lease = await tryAcquireQueueOwnerLease(options.sessionId);
+    if (!lease) {
+      const retryQueued = await trySubmitToRunningOwner({
+        sessionId: options.sessionId,
+        message: options.message,
+        permissionMode: options.permissionMode,
+        outputFormatter: options.outputFormatter,
+        timeoutMs: options.timeoutMs,
+        waitForCompletion,
+        verbose: options.verbose
+      });
+      if (retryQueued) {
+        return retryQueued;
+      }
+      await waitMs(QUEUE_CONNECT_RETRY_MS);
+      continue;
+    }
+    let owner;
+    try {
+      owner = await SessionQueueOwner.start(lease);
+      const localResult = await runSessionPrompt({
+        sessionRecordId: options.sessionId,
+        message: options.message,
+        permissionMode: options.permissionMode,
+        outputFormatter: options.outputFormatter,
+        timeoutMs: options.timeoutMs,
+        verbose: options.verbose
+      });
+      const idleWaitMs = queueOwnerTtlMs === 0 ? void 0 : Math.max(0, queueOwnerTtlMs);
+      while (true) {
+        const task = await owner.nextTask(idleWaitMs);
+        if (!task) {
+          if (queueOwnerTtlMs > 0 && options.verbose) {
+            process.stderr.write(
+              `[acpx] queue owner TTL expired after ${Math.round(queueOwnerTtlMs / 1e3)}s for session ${options.sessionId}; shutting down
+`
+            );
+          }
+          break;
+        }
+        await runQueuedTask(options.sessionId, task, options.verbose);
+      }
+      return localResult;
+    } finally {
+      if (owner) {
+        await owner.close();
+      }
+      await releaseQueueOwnerLease(lease);
+    }
+  }
+}
 async function listSessions() {
   await ensureSessionDir();
   const entries = await fs2.readdir(SESSION_BASE_DIR, { withFileTypes: true });
@@ -1186,13 +2469,47 @@ async function listSessions() {
   records.sort((a, b) => b.lastUsedAt.localeCompare(a.lastUsedAt));
   return records;
 }
+async function listSessionsForAgent(agentCommand) {
+  const sessions = await listSessions();
+  return sessions.filter((session) => session.agentCommand === agentCommand);
+}
+async function findSession(options) {
+  const normalizedCwd = absolutePath(options.cwd);
+  const normalizedName = normalizeName(options.name);
+  const sessions = await listSessionsForAgent(options.agentCommand);
+  return sessions.find((session) => {
+    if (session.cwd !== normalizedCwd) {
+      return false;
+    }
+    if (!options.includeClosed && session.closed) {
+      return false;
+    }
+    if (normalizedName == null) {
+      return session.name == null;
+    }
+    return session.name === normalizedName;
+  });
+}
+async function terminateQueueOwnerForSession(sessionId) {
+  const owner = await readQueueOwnerRecord(sessionId);
+  if (!owner) {
+    return;
+  }
+  if (isProcessAlive(owner.pid)) {
+    await terminateProcess(owner.pid);
+  }
+  await cleanupStaleQueueOwner(sessionId, owner);
+}
 async function closeSession(sessionId) {
   const record = await resolveSessionRecord(sessionId);
+  await terminateQueueOwnerForSession(record.id);
   if (record.pid != null && isProcessAlive(record.pid) && await isLikelyMatchingProcess(record.pid, record.agentCommand)) {
     await terminateProcess(record.pid);
   }
-  const file = sessionFilePath(record.id);
-  await fs2.unlink(file);
+  record.pid = void 0;
+  record.closed = true;
+  record.closedAt = isoNow();
+  await writeSessionRecord(record);
   return record;
 }
 
@@ -1208,6 +2525,7 @@ var EXIT_CODES = {
 var OUTPUT_FORMATS = ["text", "json", "quiet"];
 
 // src/cli.ts
+var TOP_LEVEL_VERBS = /* @__PURE__ */ new Set(["prompt", "exec", "sessions", "help"]);
 function parseOutputFormat(value) {
   if (!OUTPUT_FORMATS.includes(value)) {
     throw new InvalidArgumentError(
@@ -1223,6 +2541,20 @@ function parseTimeoutSeconds(value) {
   }
   return Math.round(parsed * 1e3);
 }
+function parseTtlSeconds(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new InvalidArgumentError("TTL must be a non-negative number of seconds");
+  }
+  return Math.round(parsed * 1e3);
+}
+function parseSessionName(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new InvalidArgumentError("Session name must not be empty");
+  }
+  return trimmed;
+}
 function resolvePermissionMode(flags) {
   const selected2 = [flags.approveAll, flags.approveReads, flags.denyAll].filter(
     Boolean
@@ -1240,20 +2572,6 @@ function resolvePermissionMode(flags) {
   }
   return "approve-reads";
 }
-function addPermissionFlags(command) {
-  return command.option("--approve-all", "Auto-approve all permission requests").option(
-    "--approve-reads",
-    "Auto-approve read/search requests and prompt for writes"
-  ).option("--deny-all", "Deny all permission requests");
-}
-function addFormatFlag(command) {
-  return command.option(
-    "--format <fmt>",
-    "Output format: text, json, quiet",
-    parseOutputFormat,
-    "text"
-  );
-}
 async function readPrompt(promptParts) {
   const joined = promptParts.join(" ").trim();
   if (joined.length > 0) {
@@ -1281,19 +2599,63 @@ function applyPermissionExitCode(result) {
     process.exitCode = EXIT_CODES.PERMISSION_DENIED;
   }
 }
-function printSessionRecordByFormat(record, format) {
-  if (format === "json") {
-    process.stdout.write(
-      `${JSON.stringify({
-        type: "session",
-        ...record
-      })}
-`
+function addGlobalFlags(command) {
+  return command.option("--agent <command>", "Raw ACP agent command (escape hatch)").option("--cwd <dir>", "Working directory", process.cwd()).option("--approve-all", "Auto-approve all permission requests").option(
+    "--approve-reads",
+    "Auto-approve read/search requests and prompt for writes"
+  ).option("--deny-all", "Deny all permission requests").option(
+    "--format <fmt>",
+    "Output format: text, json, quiet",
+    parseOutputFormat,
+    "text"
+  ).option(
+    "--timeout <seconds>",
+    "Maximum time to wait for agent response",
+    parseTimeoutSeconds
+  ).option(
+    "--ttl <seconds>",
+    "Queue owner idle TTL before shutdown (0 = keep alive forever) (default: 300)",
+    parseTtlSeconds
+  ).option("--verbose", "Enable verbose debug logs");
+}
+function addSessionOption(command) {
+  return command.option(
+    "-s, --session <name>",
+    "Use named session instead of cwd default",
+    parseSessionName
+  ).option(
+    "--no-wait",
+    "Queue prompt and return immediately when another prompt is already running"
+  );
+}
+function resolveGlobalFlags(command) {
+  const opts = command.optsWithGlobals();
+  return {
+    agent: opts.agent,
+    cwd: opts.cwd ?? process.cwd(),
+    timeout: opts.timeout,
+    ttl: opts.ttl ?? DEFAULT_QUEUE_OWNER_TTL_MS,
+    verbose: opts.verbose,
+    format: opts.format ?? "text",
+    approveAll: opts.approveAll,
+    approveReads: opts.approveReads,
+    denyAll: opts.denyAll
+  };
+}
+function resolveAgentInvocation(explicitAgentName, globalFlags) {
+  const override = globalFlags.agent?.trim();
+  if (override && explicitAgentName) {
+    throw new InvalidArgumentError(
+      "Do not combine positional agent with --agent override"
     );
-    return;
   }
-  process.stdout.write(`${record.id}
-`);
+  const agentName = explicitAgentName ?? DEFAULT_AGENT_NAME;
+  const agentCommand = override && override.length > 0 ? override : resolveAgentCommand(agentName);
+  return {
+    agentName,
+    agentCommand,
+    cwd: path3.resolve(globalFlags.cwd)
+  };
 }
 function printSessionsByFormat(sessions, format) {
   if (format === "json") {
@@ -1303,7 +2665,8 @@ function printSessionsByFormat(sessions, format) {
   }
   if (format === "quiet") {
     for (const session of sessions) {
-      process.stdout.write(`${session.id}
+      const closedMarker = session.closed ? " [closed]" : "";
+      process.stdout.write(`${session.id}${closedMarker}
 `);
     }
     return;
@@ -1313,121 +2676,319 @@ function printSessionsByFormat(sessions, format) {
     return;
   }
   for (const session of sessions) {
+    const closedMarker = session.closed ? " [closed]" : "";
     process.stdout.write(
-      `${session.id}	${session.cwd}	${session.lastUsedAt}
+      `${session.id}${closedMarker}	${session.name ?? "-"}	${session.cwd}	${session.lastUsedAt}
 `
     );
   }
 }
-async function main() {
-  const program = new Command();
-  program.name("acpx").description("Headless CLI client for the Agent Client Protocol").showHelpAfterError();
-  program.command("run").description("Run a one-shot prompt").argument("[prompt...]", "Prompt text").requiredOption("--agent <command>", "ACP adapter command").option("--cwd <dir>", "Working directory", process.cwd()).option(
-    "--timeout <seconds>",
-    "Maximum time to wait for agent response",
-    parseTimeoutSeconds
-  ).option("--verbose", "Enable verbose debug logs").allowUnknownOption(false);
-  const runCommand = program.commands.find((cmd) => cmd.name() === "run");
-  if (!runCommand) {
-    throw new Error("Failed to build run command");
-  }
-  addPermissionFlags(runCommand);
-  addFormatFlag(runCommand);
-  runCommand.action(async (promptParts, flags) => {
-    const prompt = await readPrompt(promptParts);
-    const permissionMode = resolvePermissionMode(flags);
-    const formatter = createOutputFormatter(flags.format);
-    const result = await runOnce({
-      agentCommand: flags.agent,
-      cwd: flags.cwd,
-      message: prompt,
-      permissionMode,
-      outputFormatter: formatter,
-      timeoutMs: flags.timeout,
-      verbose: flags.verbose
-    });
-    applyPermissionExitCode(result);
+function printClosedSessionByFormat(record, format) {
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify({
+        type: "session_closed",
+        id: record.id,
+        sessionId: record.sessionId,
+        name: record.name
+      })}
+`
+    );
+    return;
+  }
+  if (format === "quiet") {
+    return;
+  }
+  process.stdout.write(`${record.id}
+`);
+}
+function printNewSessionByFormat(record, replaced, format) {
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify({
+        type: "session_created",
+        id: record.id,
+        sessionId: record.sessionId,
+        name: record.name,
+        replacedSessionId: replaced?.id
+      })}
+`
+    );
+    return;
+  }
+  if (format === "quiet") {
+    process.stdout.write(`${record.id}
+`);
+    return;
+  }
+  if (replaced) {
+    process.stdout.write(`${record.id}	(replaced ${replaced.id})
+`);
+    return;
+  }
+  process.stdout.write(`${record.id}
+`);
+}
+function printQueuedPromptByFormat(result, format) {
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify({
+        type: "queued",
+        sessionId: result.sessionId,
+        requestId: result.requestId
+      })}
+`
+    );
+    return;
+  }
+  if (format === "quiet") {
+    return;
+  }
+  process.stdout.write(`[queued] ${result.requestId}
+`);
+}
+async function handlePrompt(explicitAgentName, promptParts, flags, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const permissionMode = resolvePermissionMode(globalFlags);
+  const prompt = await readPrompt(promptParts);
+  const outputFormatter = createOutputFormatter(globalFlags.format);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  let record = await findSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: flags.session
   });
-  const session = program.command("session").description("Session management");
-  const sessionCreate = session.command("create").description("Create a persistent session").requiredOption("--agent <command>", "ACP adapter command").option("--cwd <dir>", "Working directory", process.cwd()).option(
-    "--timeout <seconds>",
-    "Maximum time to wait for agent response",
-    parseTimeoutSeconds
-  ).option("--verbose", "Enable verbose debug logs");
-  addPermissionFlags(sessionCreate);
-  addFormatFlag(sessionCreate);
-  sessionCreate.action(async (flags) => {
-    const permissionMode = resolvePermissionMode(flags);
-    const record = await createSession({
-      agentCommand: flags.agent,
-      cwd: flags.cwd,
+  if (!record) {
+    record = await createSession({
+      agentCommand: agent.agentCommand,
+      cwd: agent.cwd,
+      name: flags.session,
       permissionMode,
-      timeoutMs: flags.timeout,
-      verbose: flags.verbose
+      timeoutMs: globalFlags.timeout,
+      verbose: globalFlags.verbose
     });
-    printSessionRecordByFormat(record, flags.format);
-  });
-  const sessionSend = session.command("send").description("Send a prompt to an existing session").argument("<sessionId>", "Session ID").argument("[prompt...]", "Prompt text").option(
-    "--timeout <seconds>",
-    "Maximum time to wait for agent response",
-    parseTimeoutSeconds
-  ).option("--verbose", "Enable verbose debug logs");
-  addPermissionFlags(sessionSend);
-  addFormatFlag(sessionSend);
-  sessionSend.action(
-    async (sessionId, promptParts, flags) => {
-      const prompt = await readPrompt(promptParts);
-      const permissionMode = resolvePermissionMode(flags);
-      const formatter = createOutputFormatter(flags.format);
-      const result = await sendSession({
-        sessionId,
-        message: prompt,
-        permissionMode,
-        outputFormatter: formatter,
-        timeoutMs: flags.timeout,
-        verbose: flags.verbose
-      });
-      applyPermissionExitCode(result);
-      if (flags.verbose && result.loadError) {
-        process.stderr.write(
-          `[acpx] loadSession failed, started fresh session: ${result.loadError}
-`
-        );
-      }
+    if (globalFlags.verbose) {
+      const scope = flags.session ? `named session "${flags.session}"` : "cwd session";
+      process.stderr.write(`[acpx] created ${scope}: ${record.id}
+`);
     }
-  );
-  const sessionList = session.command("list").description("List saved sessions");
-  addFormatFlag(sessionList);
-  sessionList.action(async (flags) => {
-    const sessions = await listSessions();
-    printSessionsByFormat(sessions, flags.format);
+  }
+  const result = await sendSession({
+    sessionId: record.id,
+    message: prompt,
+    permissionMode,
+    outputFormatter,
+    timeoutMs: globalFlags.timeout,
+    ttlMs: globalFlags.ttl,
+    verbose: globalFlags.verbose,
+    waitForCompletion: flags.wait !== false
   });
-  const sessionClose = session.command("close").description("Close and remove a saved session").argument("<sessionId>", "Session ID");
-  addFormatFlag(sessionClose);
-  sessionClose.action(async (sessionId, flags) => {
-    const record = await closeSession(sessionId);
-    if (flags.format === "json") {
-      process.stdout.write(
-        `${JSON.stringify({
-          type: "session_closed",
-          id: record.id,
-          sessionId: record.sessionId
-        })}
+  if ("queued" in result) {
+    printQueuedPromptByFormat(result, globalFlags.format);
+    return;
+  }
+  applyPermissionExitCode(result);
+  if (globalFlags.verbose && result.loadError) {
+    process.stderr.write(
+      `[acpx] loadSession failed, started fresh session: ${result.loadError}
 `
+    );
+  }
+}
+async function handleExec(explicitAgentName, promptParts, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const permissionMode = resolvePermissionMode(globalFlags);
+  const prompt = await readPrompt(promptParts);
+  const outputFormatter = createOutputFormatter(globalFlags.format);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  const result = await runOnce({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    message: prompt,
+    permissionMode,
+    outputFormatter,
+    timeoutMs: globalFlags.timeout,
+    verbose: globalFlags.verbose
+  });
+  applyPermissionExitCode(result);
+}
+async function handleSessionsList(explicitAgentName, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  const sessions = await listSessionsForAgent(agent.agentCommand);
+  printSessionsByFormat(sessions, globalFlags.format);
+}
+async function handleSessionsClose(explicitAgentName, sessionName, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  const record = await findSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: sessionName
+  });
+  if (!record) {
+    if (sessionName) {
+      throw new Error(
+        `No named session "${sessionName}" for cwd ${agent.cwd} and agent ${agent.agentName}`
       );
-      return;
     }
-    if (flags.format === "quiet") {
-      return;
+    throw new Error(`No cwd session for ${agent.cwd} and agent ${agent.agentName}`);
+  }
+  const closed = await closeSession(record.id);
+  printClosedSessionByFormat(closed, globalFlags.format);
+}
+async function handleSessionsNew(explicitAgentName, flags, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const permissionMode = resolvePermissionMode(globalFlags);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  const replaced = await findSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: flags.name
+  });
+  if (replaced) {
+    await closeSession(replaced.id);
+    if (globalFlags.verbose) {
+      process.stderr.write(`[acpx] soft-closed prior session: ${replaced.id}
+`);
     }
-    process.stdout.write(`${record.id}
+  }
+  const created = await createSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: flags.name,
+    permissionMode,
+    timeoutMs: globalFlags.timeout,
+    verbose: globalFlags.verbose
+  });
+  if (globalFlags.verbose) {
+    const scope = flags.name ? `named session "${flags.name}"` : "cwd session";
+    process.stderr.write(`[acpx] created ${scope}: ${created.id}
 `);
+  }
+  printNewSessionByFormat(created, replaced, globalFlags.format);
+}
+function registerSessionsCommand(parent, explicitAgentName) {
+  const sessionsCommand = parent.command("sessions").description("List, create, or close sessions for this agent");
+  sessionsCommand.action(async function() {
+    await handleSessionsList(explicitAgentName, this);
+  });
+  sessionsCommand.command("list").description("List sessions").action(async function() {
+    await handleSessionsList(explicitAgentName, this);
+  });
+  sessionsCommand.command("new").description("Create a fresh session for current cwd").option("--name <name>", "Session name", parseSessionName).action(async function(flags) {
+    await handleSessionsNew(explicitAgentName, flags, this);
+  });
+  sessionsCommand.command("close").description("Close session for current cwd").argument("[name]", "Session name", parseSessionName).action(async function(name) {
+    await handleSessionsClose(explicitAgentName, name, this);
+  });
+}
+function registerAgentCommand(program, agentName) {
+  const agentCommand = program.command(agentName).description(`Use ${agentName} agent`).argument("[prompt...]", "Prompt text").showHelpAfterError();
+  addSessionOption(agentCommand);
+  agentCommand.action(async function(promptParts, flags) {
+    await handlePrompt(agentName, promptParts, flags, this);
+  });
+  const promptCommand = agentCommand.command("prompt").description("Prompt using persistent session").argument("[prompt...]", "Prompt text").showHelpAfterError();
+  addSessionOption(promptCommand);
+  promptCommand.action(async function(promptParts, flags) {
+    await handlePrompt(agentName, promptParts, flags, this);
+  });
+  agentCommand.command("exec").description("One-shot prompt without saved session").argument("[prompt...]", "Prompt text").showHelpAfterError().action(async function(promptParts) {
+    await handleExec(agentName, promptParts, this);
+  });
+  registerSessionsCommand(agentCommand, agentName);
+}
+function registerDefaultCommands(program) {
+  const promptCommand = program.command("prompt").description(`Prompt using ${DEFAULT_AGENT_NAME} by default`).argument("[prompt...]", "Prompt text").showHelpAfterError();
+  addSessionOption(promptCommand);
+  promptCommand.action(async function(promptParts, flags) {
+    await handlePrompt(void 0, promptParts, flags, this);
   });
+  program.command("exec").description(`One-shot prompt using ${DEFAULT_AGENT_NAME} by default`).argument("[prompt...]", "Prompt text").showHelpAfterError().action(async function(promptParts) {
+    await handleExec(void 0, promptParts, this);
+  });
+  registerSessionsCommand(program, void 0);
+}
+function detectAgentToken(argv) {
+  let hasAgentOverride = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      break;
+    }
+    if (!token.startsWith("-") || token === "-") {
+      return { token, hasAgentOverride };
+    }
+    if (token === "--agent") {
+      hasAgentOverride = true;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--agent=")) {
+      hasAgentOverride = true;
+      continue;
+    }
+    if (token === "--cwd" || token === "--format" || token === "--timeout" || token === "--ttl") {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--cwd=") || token.startsWith("--format=") || token.startsWith("--timeout=") || token.startsWith("--ttl=")) {
+      continue;
+    }
+    if (token === "--approve-all" || token === "--approve-reads" || token === "--deny-all" || token === "--verbose") {
+      continue;
+    }
+    return { hasAgentOverride };
+  }
+  return { hasAgentOverride };
+}
+async function main(argv = process.argv) {
+  await maybeHandleSkillflag(argv, {
+    skillsRoot: findSkillsRoot(import.meta.url),
+    includeBundledSkill: false
+  });
+  const program = new Command();
+  program.name("acpx").description("Headless CLI client for the Agent Client Protocol").showHelpAfterError();
+  addGlobalFlags(program);
+  const builtInAgents = listBuiltInAgents();
+  for (const agentName of builtInAgents) {
+    registerAgentCommand(program, agentName);
+  }
+  registerDefaultCommands(program);
+  const scan = detectAgentToken(argv.slice(2));
+  if (!scan.hasAgentOverride && scan.token && !TOP_LEVEL_VERBS.has(scan.token) && !builtInAgents.includes(scan.token)) {
+    registerAgentCommand(program, scan.token);
+  }
+  program.argument("[prompt...]", "Prompt text").action(async function(promptParts) {
+    if (promptParts.length === 0 && process.stdin.isTTY) {
+      this.outputHelp();
+      return;
+    }
+    await handlePrompt(void 0, promptParts, {}, this);
+  });
+  program.addHelpText(
+    "after",
+    `
+Examples:
+  acpx codex "fix the tests"
+  acpx codex prompt "fix the tests"
+  acpx codex --no-wait "queue follow-up task"
+  acpx codex exec "what does this repo do"
+  acpx codex -s backend "fix the API"
+  acpx codex sessions
+  acpx codex sessions new --name backend
+  acpx codex sessions close backend
+  acpx --ttl 30 codex "investigate flaky tests"
+  acpx claude "refactor auth"
+  acpx gemini "add logging"
+  acpx --agent ./my-custom-server "do something"`
+  );
   program.exitOverride((error) => {
     throw error;
   });
   try {
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
   } catch (error) {
     if (error instanceof CommanderError) {
       if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
@@ -1449,4 +3010,22 @@ async function main() {
     process.exit(EXIT_CODES.ERROR);
   }
 }
-void main();
+function isCliEntrypoint(argv) {
+  const entry = argv[1];
+  if (!entry) {
+    return false;
+  }
+  try {
+    const resolved = pathToFileURL(realpathSync(entry)).href;
+    return import.meta.url === resolved;
+  } catch {
+    return false;
+  }
+}
+if (isCliEntrypoint(process.argv)) {
+  void main(process.argv);
+}
+export {
+  main,
+  parseTtlSeconds
+};