acpx 0.1.2 → 0.1.3

package/README.md

@@ -9,6 +9,8 @@ One command surface for Codex, Claude, Gemini, OpenCode, Pi, or custom ACP serve
 - **Persistent sessions**: multi-turn conversations that survive across invocations, scoped per repo
 - **Named sessions**: run parallel workstreams in the same repo (`-s backend`, `-s frontend`)
 - **Prompt queueing**: submit prompts while one is already running, they execute in order
+- **Soft-close lifecycle**: close sessions without deleting history from disk
+- **Queue owner TTL**: keep queue owners alive briefly for follow-up prompts (`--ttl`)
 - **Fire-and-forget**: `--no-wait` queues a prompt and returns immediately
 - **Structured output**: typed ACP messages (thinking, tool calls, diffs) instead of ANSI scraping
 - **Any ACP agent**: built-in registry + `--agent` escape hatch for custom servers
@@ -76,6 +78,8 @@ acpx codex -s docs 'rewrite API docs'           # parallel work in another named
 
 acpx codex sessions              # list sessions for codex command
 acpx codex sessions list         # explicit list
+acpx codex sessions new          # create fresh cwd-scoped default session
+acpx codex sessions new --name api # create fresh named session
 acpx codex sessions close        # close cwd-scoped default session
 acpx codex sessions close api    # close cwd-scoped named session
 
@@ -111,6 +115,7 @@ acpx --format json codex exec 'review changed files'
 acpx --format quiet codex 'final recommendation only'
 
 acpx --timeout 90 codex 'investigate intermittent test timeout'
+acpx --ttl 30 codex 'keep queue owner alive for quick follow-ups'
 acpx --verbose codex 'debug why adapter startup is failing'
 ```
 
@@ -150,7 +155,11 @@ acpx --agent ./my-custom-acp-server 'do something'
 
 - Prompt commands use saved sessions scoped to `(agent command, cwd, optional name)`.
 - `-s <name>` creates/selects a parallel named session in the same repo.
+- `sessions new [--name <name>]` creates a fresh session for that scope and soft-closes the prior one.
+- `sessions close [name]` soft-closes the session: queue owner/processes are terminated, record is kept with `closed: true`.
+- Auto-resume for cwd scope skips sessions marked closed.
 - Prompt submissions are queue-aware per session. If a prompt is already running, new prompts are queued and drained by the running `acpx` process.
+- Queue owners use an idle TTL (default 300s). `--ttl <seconds>` overrides it; `--ttl 0` keeps owners alive indefinitely.
 - `--no-wait` submits to that queue and returns immediately.
 - `exec` is always one-shot and does not reuse saved sessions.
 - Session metadata is stored under `~/.acpx/sessions/`.

package/dist/cli.d.ts

@@ -1 +1,5 @@
 #!/usr/bin/env node
+declare function parseTtlSeconds(value: string): number;
+declare function main(argv?: string[]): Promise<void>;
+
+export { main, parseTtlSeconds };

package/dist/cli.js

@@ -2,7 +2,10 @@
 
 // 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 = {
@@ -1300,7 +1303,7 @@ var PROCESS_EXIT_GRACE_MS = 1500;
 var PROCESS_POLL_MS = 50;
 var QUEUE_CONNECT_ATTEMPTS = 40;
 var QUEUE_CONNECT_RETRY_MS = 50;
-var QUEUE_IDLE_DRAIN_WAIT_MS = 150;
+var DEFAULT_QUEUE_OWNER_TTL_MS = 3e5;
 var TimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Timed out after ${timeoutMs}ms`);
@@ -1375,7 +1378,9 @@ function parseSessionRecord(raw) {
   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" || name === null || 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 {
@@ -1387,6 +1392,8 @@ function parseSessionRecord(raw) {
     name,
     createdAt: record.createdAt,
     lastUsedAt: record.lastUsedAt,
+    closed,
+    closedAt,
     pid
   };
 }
@@ -1451,6 +1458,15 @@ function normalizeName(value) {
 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;
@@ -1906,7 +1922,8 @@ var SessionQueueOwner = class _SessionQueueOwner {
       return void 0;
     }
     return await new Promise((resolve) => {
-      const timer = setTimeout(
+      const shouldTimeout = timeoutMs != null;
+      const timer = shouldTimeout && setTimeout(
         () => {
           const index = this.waiters.indexOf(waiter);
           if (index >= 0) {
@@ -1917,7 +1934,9 @@ var SessionQueueOwner = class _SessionQueueOwner {
         Math.max(0, timeoutMs)
       );
       const waiter = (task) => {
-        clearTimeout(timer);
+        if (timer) {
+          clearTimeout(timer);
+        }
         resolve(task);
       };
       this.waiters.push(waiter);
@@ -2268,6 +2287,8 @@ async function runSessionPrompt(options) {
         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);
@@ -2343,6 +2364,8 @@ async function createSession(options) {
           name: normalizeName(options.name),
           createdAt: now,
           lastUsedAt: now,
+          closed: false,
+          closedAt: void 0,
           pid: client.getAgentPid(),
           protocolVersion: client.initializeResult?.protocolVersion,
           agentCapabilities: client.initializeResult?.agentCapabilities
@@ -2360,6 +2383,7 @@ async function createSession(options) {
 }
 async function sendSession(options) {
   const waitForCompletion = options.waitForCompletion !== false;
+  const queueOwnerTtlMs = normalizeQueueOwnerTtlMs(options.ttlMs);
   const queuedToOwner = await trySubmitToRunningOwner({
     sessionId: options.sessionId,
     message: options.message,
@@ -2401,9 +2425,16 @@ async function sendSession(options) {
         timeoutMs: options.timeoutMs,
         verbose: options.verbose
       });
+      const idleWaitMs = queueOwnerTtlMs === 0 ? void 0 : Math.max(0, queueOwnerTtlMs);
       while (true) {
-        const task = await owner.nextTask(QUEUE_IDLE_DRAIN_WAIT_MS);
+        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);
@@ -2450,6 +2481,9 @@ async function findSession(options) {
     if (session.cwd !== normalizedCwd) {
       return false;
     }
+    if (!options.includeClosed && session.closed) {
+      return false;
+    }
     if (normalizedName == null) {
       return session.name == null;
     }
@@ -2472,8 +2506,10 @@ async function closeSession(sessionId) {
   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;
 }
 
@@ -2505,6 +2541,13 @@ 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) {
@@ -2569,6 +2612,10 @@ function addGlobalFlags(command) {
     "--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) {
@@ -2587,6 +2634,7 @@ function resolveGlobalFlags(command) {
     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,
@@ -2617,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;
@@ -2627,8 +2676,9 @@ function printSessionsByFormat(sessions, format) {
     return;
   }
   for (const session of sessions) {
+    const closedMarker = session.closed ? " [closed]" : "";
     process.stdout.write(
-      `${session.id}	${session.name ?? "-"}	${session.cwd}	${session.lastUsedAt}
+      `${session.id}${closedMarker}	${session.name ?? "-"}	${session.cwd}	${session.lastUsedAt}
 `
     );
   }
@@ -2652,6 +2702,33 @@ function printClosedSessionByFormat(record, format) {
   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(
@@ -2702,6 +2779,7 @@ async function handlePrompt(explicitAgentName, promptParts, flags, command) {
     permissionMode,
     outputFormatter,
     timeoutMs: globalFlags.timeout,
+    ttlMs: globalFlags.ttl,
     verbose: globalFlags.verbose,
     waitForCompletion: flags.wait !== false
   });
@@ -2759,14 +2837,48 @@ async function handleSessionsClose(explicitAgentName, sessionName, command) {
   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}
+`);
+    }
+  }
+  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 or close sessions for this agent");
+  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);
   });
@@ -2817,11 +2929,11 @@ function detectAgentToken(argv) {
       hasAgentOverride = true;
       continue;
     }
-    if (token === "--cwd" || token === "--format" || token === "--timeout") {
+    if (token === "--cwd" || token === "--format" || token === "--timeout" || token === "--ttl") {
       index += 1;
       continue;
     }
-    if (token.startsWith("--cwd=") || token.startsWith("--format=") || token.startsWith("--timeout=")) {
+    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") {
@@ -2831,7 +2943,11 @@ function detectAgentToken(argv) {
   }
   return { hasAgentOverride };
 }
-async function main() {
+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);
@@ -2840,7 +2956,7 @@ async function main() {
     registerAgentCommand(program, agentName);
   }
   registerDefaultCommands(program);
-  const scan = detectAgentToken(process.argv.slice(2));
+  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);
   }
@@ -2861,7 +2977,9 @@ Examples:
   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"`
@@ -2870,7 +2988,7 @@ Examples:
     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") {
@@ -2892,4 +3010,22 @@ Examples:
     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
+};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "acpx",
-  "version": "0.1.2",
-  "description": "Headless CLI client for the Agent Client Protocol (ACP) \u2014 talk to coding agents from the command line",
+  "version": "0.1.3",
+  "description": "Headless CLI client for the Agent Client Protocol (ACP) — talk to coding agents from the command line",
   "type": "module",
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -13,6 +14,10 @@
   },
   "scripts": {
     "build": "tsup src/cli.ts --format esm --dts --clean",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/test/*.test.js",
+    "prepare": "husky",
+    "precommit": "npm exec -- lint-staged && npm run -s build",
     "prepack": "npm run build",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
@@ -42,13 +47,16 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.14.1",
-    "commander": "^13.0.0"
+    "commander": "^13.0.0",
+    "skillflag": "^0.1.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
     "eslint": "^10.0.0",
     "globals": "^17.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
     "prettier": "^3.8.1",
     "release-it": "^19.2.4",
     "tsup": "^8.0.0",
@@ -56,21 +64,13 @@
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.56.0"
   },
-  "release-it": {
-    "git": {
-      "requireCleanWorkingDir": true,
-      "requireBranch": "main",
-      "commitMessage": "chore(release): ${version}",
-      "tagName": "v${version}",
-      "push": true
-    },
-    "npm": {
-      "publish": true,
-      "skipChecks": true
-    },
-    "github": {
-      "release": true,
-      "autoGenerate": true
-    }
+  "lint-staged": {
+    "*.{js,ts}": [
+      "prettier --write --ignore-unknown",
+      "eslint --fix"
+    ],
+    "*.{json,md}": [
+      "prettier --write --ignore-unknown"
+    ]
   }
 }

package/skills/acpx/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: acpx
+description: Use acpx as a headless ACP CLI for agent-to-agent communication, including prompt/exec/sessions workflows, session scoping, queueing, permissions, and output formats.
+---
+
+# acpx
+
+## When to use this skill
+
+Use this skill when you need to run coding agents through `acpx`, manage persistent ACP sessions, queue prompts, or consume structured agent output from scripts.
+
+## What acpx is
+
+`acpx` is a headless, scriptable CLI client for the Agent Client Protocol (ACP). It is built for agent-to-agent communication over the command line and avoids PTY scraping.
+
+Core capabilities:
+
+- Persistent multi-turn sessions per repo/cwd
+- One-shot execution mode (`exec`)
+- Named parallel sessions (`-s/--session`)
+- Queue-aware prompt submission with optional fire-and-forget (`--no-wait`)
+- Structured streaming output (`text`, `json`, `quiet`)
+- Built-in agent registry plus raw `--agent` escape hatch
+
+## Install
+
+```bash
+npm i -g acpx
+```
+
+For normal session reuse, prefer a global install over `npx`.
+
+## Command model
+
+`prompt` is the default verb.
+
+```bash
+acpx [global_options] [prompt_text...]
+acpx [global_options] prompt [prompt_options] [prompt_text...]
+acpx [global_options] exec [prompt_text...]
+acpx [global_options] sessions [list | new [--name <name>] | close [name]]
+
+acpx [global_options] <agent> [prompt_options] [prompt_text...]
+acpx [global_options] <agent> prompt [prompt_options] [prompt_text...]
+acpx [global_options] <agent> exec [prompt_text...]
+acpx [global_options] <agent> sessions [list | new [--name <name>] | close [name]]
+```
+
+If prompt text is omitted and stdin is piped, `acpx` reads prompt text from stdin.
+
+## Built-in agent registry
+
+Friendly agent names resolve to commands:
+
+- `codex` -> `npx @zed-industries/codex-acp`
+- `claude` -> `npx @zed-industries/claude-agent-acp`
+- `gemini` -> `gemini`
+- `opencode` -> `npx opencode-ai`
+- `pi` -> `npx pi-acp`
+
+Rules:
+
+- Default agent is `codex` for top-level `prompt`, `exec`, and `sessions`.
+- Unknown positional agent tokens are treated as raw agent commands.
+- `--agent <command>` explicitly sets a raw ACP adapter command.
+- Do not combine a positional agent and `--agent` in the same command.
+
+## Commands
+
+### Prompt (default, persistent session)
+
+Implicit:
+
+```bash
+acpx codex 'fix flaky tests'
+```
+
+Explicit:
+
+```bash
+acpx codex prompt 'fix flaky tests'
+acpx prompt 'fix flaky tests'   # defaults to codex
+```
+
+Behavior:
+
+- Uses a saved session for the session scope key
+- Auto-resumes prior session when one exists for that scope
+- Creates a new session record when none exists
+- Is queue-aware when another prompt is already running for the same session
+
+Prompt options:
+
+- `-s, --session <name>`: use a named session within the same cwd
+- `--no-wait`: enqueue and return immediately when session is already busy
+
+### Exec (one-shot)
+
+```bash
+acpx exec 'summarize this repo'
+acpx codex exec 'summarize this repo'
+```
+
+Behavior:
+
+- Runs a single prompt in a temporary ACP session
+- Does not reuse or save persistent session state
+
+### Sessions
+
+```bash
+acpx sessions
+acpx sessions list
+acpx sessions new
+acpx sessions new --name backend
+acpx sessions close
+acpx sessions close backend
+
+acpx codex sessions
+acpx codex sessions new --name backend
+acpx codex sessions close backend
+```
+
+Behavior:
+
+- `sessions` and `sessions list` are equivalent
+- `new` creates a fresh session for the current `(agentCommand, cwd, optional name)` scope
+- `new --name <name>` targets a named session scope
+- when `new` replaces an existing open session in that scope, the old one is soft-closed
+- `close` targets current cwd default session
+- `close <name>` targets current cwd named session
+
+## Global options
+
+- `--agent <command>`: raw ACP agent command (escape hatch)
+- `--cwd <dir>`: working directory for session scope (default: current directory)
+- `--approve-all`: auto-approve all permission requests
+- `--approve-reads`: auto-approve reads/searches, prompt for writes (default mode)
+- `--deny-all`: deny all permission requests
+- `--format <fmt>`: output format (`text`, `json`, `quiet`)
+- `--timeout <seconds>`: max wait time (positive number)
+- `--ttl <seconds>`: queue owner idle TTL before shutdown (default `300`, `0` disables TTL)
+- `--verbose`: verbose ACP/debug logs to stderr
+
+Permission flags are mutually exclusive.
+
+## Session behavior
+
+Persistent prompt sessions are scoped by:
+
+- `agentCommand`
+- absolute `cwd`
+- optional session `name`
+
+Persistence:
+
+- Session records are stored in `~/.acpx/sessions/*.json`.
+- `-s/--session` creates parallel named conversations in the same repo.
+- Changing `--cwd` changes scope and therefore session lookup.
+- closed sessions are retained on disk with `closed: true` and `closedAt`.
+- auto-resume by scope skips closed sessions.
+
+Resume behavior:
+
+- Prompt mode attempts to reconnect to saved session.
+- If adapter-side session is invalid/not found, `acpx` creates a fresh session and updates the saved record.
+- explicitly selected session records can still be resumed via `loadSession` even if previously closed.
+
+## Prompt queueing and `--no-wait`
+
+Queueing is per persistent session.
+
+- The active `acpx` process for a running prompt becomes the queue owner.
+- Other invocations submit prompts over local IPC.
+- On Unix-like systems, queue IPC uses a Unix socket under `~/.acpx/queues/<hash>.sock`.
+- Ownership is coordinated with a lock file under `~/.acpx/queues/<hash>.lock`.
+- On Windows, named pipes are used instead of Unix sockets.
+- after the queue drains, owner shutdown is governed by TTL (default 300s, configurable with `--ttl`).
+
+Submission behavior:
+
+- Default: enqueue and wait for queued prompt completion, streaming updates back.
+- `--no-wait`: enqueue and return after queue acknowledgement.
+
+## Output formats
+
+Use `--format <fmt>`:
+
+- `text` (default): human-readable stream with updates/tool status and done line
+- `json`: NDJSON event stream (good for automation)
+- `quiet`: final assistant text only
+
+Example automation:
+
+```bash
+acpx --format json codex exec 'review changed files' \
+  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'
+```
+
+## Permission modes
+
+- `--approve-all`: no interactive permission prompts
+- `--approve-reads` (default): approve reads/searches, prompt for writes
+- `--deny-all`: deny all permission requests
+
+If every permission request is denied/cancelled and none approved, `acpx` exits with permission-denied status.
+
+## Practical workflows
+
+Persistent repo assistant:
+
+```bash
+acpx codex 'inspect failing tests and propose a fix plan'
+acpx codex 'apply the smallest safe fix and run tests'
+```
+
+Parallel named streams:
+
+```bash
+acpx codex -s backend 'fix API pagination bug'
+acpx codex -s docs 'draft changelog entry for release'
+```
+
+Queue follow-up without waiting:
+
+```bash
+acpx codex 'run full test suite and investigate failures'
+acpx codex --no-wait 'after tests, summarize root causes and next steps'
+```
+
+One-shot script step:
+
+```bash
+acpx --format quiet exec 'summarize repo purpose in 3 lines'
+```
+
+Machine-readable output for orchestration:
+
+```bash
+acpx --format json codex 'review current branch changes' > events.ndjson
+```
+
+Raw custom adapter command:
+
+```bash
+acpx --agent './bin/custom-acp-server --profile ci' 'run validation checks'
+```
+
+Repo-scoped review with permissive mode:
+
+```bash
+acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
+  'review PR #842 for regressions and propose minimal patch'
+```