agentp 0.12.0 → 1.13.0

package/README.md

@@ -22,6 +22,8 @@ It is designed for prompt-driven workflows where you want to do things like:
 
 These tools are built for my own daily workflow. They are heavily AI-assisted — including the tests — and I review things before shipping, but the real test is using them every day. Bugs happen; I value a working feature more than a flawless one. MIT license, no warranty. Issues, suggestions, and PRs are welcome.
 
+**Stability note:** `agentp` and `ocmux` are stable and used daily. `tgagentp` is still in a highly experimental stage — expect breaking changes and occasional bugs.
+
 ## Install
 
 From npm:
@@ -57,6 +59,8 @@ agentp [options] [url]
 Options:
 
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
+- `--defer [N]`: deferred execution — submit a prompt and get a ticket immediately (or wait up to N seconds for the answer and print it if it arrives); pipe the ticket back to retrieve the result later
+- `--onlineTicket`: print deferred tickets on a single line (default: pretty-printed JSON)
 - `--tg`: forward the answer to Telegram via tgagentp gateway (error if unreachable)
 - `--no-tg`: do not forward to Telegram
 - `--flush`: flush tgagentp's recorded buffer without prepending it to output
@@ -69,9 +73,17 @@ Options:
 By default, `--qa` auto-detects tgagentp (silently degrades if unavailable); standalone mode implies `--no-tg`.
 With `--tg`, errors if tgagentp is unavailable.
 
+> **Telegram notification from deferred jobs:** Use `--defer --tg` (or
+> `--defer N --tg`) to forward the answer to Telegram automatically when the
+> background job completes. The detached child process runs the full `--tg`
+> flow, including gateway detection and notification. If the gateway is
+> unreachable at completion time, a warning is printed on stderr; the answer
+> is still saved in the temp file and retrievable via ticket re-submission.
+
 Arguments:
 
 - `url`: OpenCode TUI server URL or port number (defaults to `4096`). Examples: `4096`, `http://localhost:4096`, `http://192.168.1.50:4096`
+- Tip: `$(ocmux)` expands to the URL of the current project's server, so you can run `agentp $(ocmux)` from any shell.
 
 ## Examples
 
@@ -142,6 +154,107 @@ From Vim/Neovim, flush the recorded buffer without prepending context:
 Useful when you've finished a conversation thread and want to reset the recorded
 context for a new topic.
 
+Deferred execution with `--defer`:
+
+Submit a prompt and get a ticket to retrieve the result later:
+
+```bash
+# Submit a prompt and get a deferred ticket (optionally wait up to N seconds)
+DEFERRED=$(printf "Refactor the authentication module" | agentp --defer)
+# Output: agentp_ticket {
+#            "ctime": "2026-08-03T14:30:00.000Z",
+#            "path": "/tmp/agentp_deferred_20260803_1430_a1b2.tmp",
+#            "server": "http://localhost:4096",
+#            "sessionId": "ses_abc123"
+#          }
+
+# Or wait up to 60s for the answer; only get a ticket if it's not ready in time
+DEFERRED=$(printf "Refactor the authentication module" | agentp --defer 60)
+
+# Continue working... retrieve the result when ready
+printf '%s\n' "$DEFERRED" | agentp --defer
+# Output: (the agent's response)
+```
+
+`--defer` takes an optional numeric timeout in seconds (default `0`). With a
+timeout, the invocation blocks until the answer arrives or the timeout expires:
+if the answer arrives in time it is printed immediately; otherwise a ticket is
+returned and the agent keeps working in the background.
+
+The ticket is `agentp_ticket` followed by a JSON object with these fields:
+
+- `ctime` — creation timestamp (ISO 8601). Only used to compute `elapsed`.
+- `path` — path to the temp file holding the result.
+- `server` — OpenCode server URL used by the deferred job.
+- `sessionId` — OpenCode session ID used by the deferred job.
+- `elapsed` — seconds since `ctime`, included only when the ticket is re-printed (not on first print).
+- `defer` — the timeout requested at submission, included only when it was > 0.
+
+Tickets are printed as pretty-printed (multi-line) JSON for easier reading and
+editing; pass `--onlineTicket` to print them on a single line instead:
+
+```bash
+printf "Refactor the auth module" | agentp --defer --onlineTicket
+# Output: agentp_ticket {"ctime":"...","path":"/tmp/agentp_deferred_....tmp"}
+```
+
+Both formats are accepted when piping a ticket back to `agentp --defer`.
+
+You can also append follow-up text after a not-yet-ready ticket to queue more
+input into the original running task, similar to typing into the OpenCode TUI
+while the agent is busy:
+
+```bash
+cat <<'EOF' | agentp --defer
+agentp_ticket {
+  "ctime": "2026-08-03T14:30:00.000Z",
+  "path": "/tmp/agentp_deferred_...tmp",
+  "server": "http://localhost:4096",
+  "sessionId": "ses_abc123"
+}
+Also make sure the migration is reversible.
+EOF
+```
+
+If the answer is already ready, the appended text is not sent to OpenCode; it is
+printed after the returned answer so you can edit and re-submit it if needed. In
+`--qa` output, it appears after the final ruler. If the answer is not ready, the
+appended text is sent through OpenCode's async prompt endpoint for the ticket's
+`server`/`sessionId`, stored with the ticket, and the ticket is re-printed with
+updated `elapsed` without echoing the extra text in that interim output. When
+the final answer is later retrieved with `--qa`, all stored follow-ups are
+printed inside the prompt block under `📝` separators. Without `--qa`, stored
+follow-ups are not printed. Older tickets without `server` and `sessionId` can
+still retrieve results, but cannot queue follow-up text.
+
+Piping a ticket back to `agentp --defer` ignores the `--defer` argument and uses
+the ticket's own `defer` value as the timeout (default `0`):
+
+- If the answer is ready, it is returned and the temp file is removed.
+- If not, the ticket is re-printed with the elapsed time updated.
+
+Works as a Vim/Neovim filter with deferred execution:
+
+```vim
+" Submit selection, get ticket immediately, continue editing
+:'<,'>!agentp --defer --qa
+
+" Later, retrieve the result
+:r !printf '%s\n' "$(cat <<'EOF'
+agentp_ticket {"ctime":"2026-08-03T14:30:00.000Z","path":"/tmp/agentp_deferred_...tmp","server":"http://localhost:4096","sessionId":"ses_abc123"}
+EOF
+)" | agentp --defer
+```
+
+The deferred workflow:
+1. Submit prompt with `--defer` → get a ticket (`agentp_ticket {...}`)
+2. Continue working (the agent processes in background)
+3. When ready, pipe the ticket back to `agentp --defer` to retrieve the result
+4. If the agent is still processing, you get the ticket back with the elapsed time updated
+5. If complete, you get the agent's response and the temp file is cleaned up
+
+Useful for long-running tasks where you don't want to block your editor.
+
 Retrieve the last 3 assistant answers from session history:
 
 ```bash
@@ -168,6 +281,7 @@ Subcommands:
   - `--print-logs` passes `--print-logs` to `opencode serve`, which prints server logs to stderr in the server tmux pane.
 - **`kill [dir]`** — Kill the server found upward from `dir`. Removes its tmux window and state file.
 - **`resurrect [--print-logs] [dir]`** — Recover a dead/crashed server: reads `.ocmux.json`, kills old tmux window, removes state file, then creates a fresh server + TUI in the same directory. Works even if no tmux window exists (stale state file).
+- **`switch`** — Interactive session picker: an interactive menu of all running servers (columns: dirname, status, url, full path). Arrow keys or `j`/`k` move the selection; `Enter`/`Space` switches to the selected server's tmux window (the menu stays open, so you can hop between servers); `q` or `Ctrl+C` exits. The currently active server (queried live from tmux on every redraw) is highlighted across the full line width. Prints the URL of the last selected server on exit. Requires a TTY.
 - **`list`** — List all running servers with their directories, URLs, and status.
 
 Options:
@@ -181,6 +295,7 @@ Notes:
 
 - If `<directory>` is not a valid path, `ocmux` tries to match it against the basenames of existing sessions (exact unique match).
 - When using `--git`/`--GIT`, `ocmux` refuses to create a new server above an existing `.ocmux.json` found while searching for the git root.
+- In default mode, if no server is found, the primary error line is printed to stdout. This intentionally makes `agentp $(ocmux)` fail instead of silently falling back to `agentp`'s default `localhost:4096` server.
 
 ### Requirements
 

package/bin/agentp

@@ -2,11 +2,15 @@
 
 const http = require('http');
 const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
 const readline = require('readline');
 const child_process = require('child_process');
 const { version } = require('../package.json');
 const {
   sendToSession,
+  sendToSessionAsync,
   listSessions,
   createSession,
   getSession,
@@ -60,6 +64,261 @@ function notifyAgentpGateway(port, server, text) {
   });
 }
 
+function isFileLocked(filePath) {
+  const lockPath = filePath + '.lock';
+  try {
+    if (!fs.existsSync(lockPath)) return false;
+    const pid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+    if (isNaN(pid)) return false;
+    // Check if process is still alive
+    try {
+      process.kill(pid, 0);
+      return true; // Process exists, file is locked
+    } catch (err) {
+      // Process doesn't exist, lock is stale
+      fs.unlinkSync(lockPath);
+      return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+function lockFile(filePath) {
+  const lockPath = filePath + '.lock';
+  fs.writeFileSync(lockPath, String(process.pid));
+}
+
+function unlockFile(filePath) {
+  const lockPath = filePath + '.lock';
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    // Ignore errors
+  }
+}
+
+function generateTempFilename() {
+  const now = new Date();
+  const timestamp = now.getFullYear().toString() +
+    String(now.getMonth() + 1).padStart(2, '0') +
+    String(now.getDate()).padStart(2, '0') + '_' +
+    String(now.getHours()).padStart(2, '0') +
+    String(now.getMinutes()).padStart(2, '0');
+  const hash = crypto.randomBytes(2).toString('hex').slice(0, 4);
+  return path.join(os.tmpdir(), `agentp_deferred_${timestamp}_${hash}.tmp`);
+}
+
+// Poll interval for --defer waiting (ms). Overridable for tests.
+const DEFER_POLL_MS = 250;
+const FOLLOWUP_ROW = '📝 —————————————————\n';
+
+function stripFollowupRow(text) {
+  return text.startsWith(FOLLOWUP_ROW) ? text.slice(FOLLOWUP_ROW.length) : text;
+}
+
+// Parse an `agentp_ticket <json>` reference from the start of input text.
+// The ticket may be wrapped in whitespace/newlines and may be followed by
+// additional text, which is returned separately for queued follow-ups.
+function parseDeferredTicketInput(text) {
+  const trimmed = String(text).trim();
+  if (!trimmed.startsWith('agentp_ticket')) return null;
+  const afterPrefix = trimmed.slice('agentp_ticket'.length).trimStart();
+  if (!afterPrefix.startsWith('{')) return null;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let jsonEnd = -1;
+  for (let i = 0; i < afterPrefix.length; i++) {
+    const ch = afterPrefix[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === '{') {
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        jsonEnd = i + 1;
+        break;
+      }
+    }
+  }
+  if (jsonEnd === -1) return null;
+  let data;
+  try {
+    data = JSON.parse(afterPrefix.slice(0, jsonEnd));
+  } catch {
+    return null;
+  }
+  if (!data || typeof data.path !== 'string' || !data.path) return null;
+  const rest = afterPrefix.slice(jsonEnd);
+  const followupText = rest.trim() ? stripFollowupRow(rest.trimStart()) : '';
+  return {
+    ctime: typeof data.ctime === 'string' ? data.ctime : null,
+    path: data.path,
+    defer: typeof data.defer === 'number' && data.defer > 0 ? data.defer : 0,
+    server: typeof data.server === 'string' ? data.server : null,
+    sessionId: typeof data.sessionId === 'string' ? data.sessionId : null,
+    followupText,
+  };
+}
+
+function parseDeferredTicket(text) {
+  const parsed = parseDeferredTicketInput(text);
+  if (!parsed) return null;
+  const { followupText, ...ticket } = parsed;
+  return ticket;
+}
+
+// Format a deferred ticket for printing. `elapsed` is only included on
+// re-prints; `defer` only when a timeout > 0 was requested. Pretty-printed
+// JSON by default (easier to read/edit); pass `compact` for a single line.
+function formatTicket(ticket, elapsed, compact) {
+  const fields = { ctime: ticket.ctime, path: ticket.path };
+  if (ticket.server) fields.server = ticket.server;
+  if (ticket.sessionId) fields.sessionId = ticket.sessionId;
+  if (elapsed !== undefined) fields.elapsed = elapsed;
+  if (ticket.defer > 0) fields.defer = ticket.defer;
+  return 'agentp_ticket ' + (compact ? JSON.stringify(fields) : JSON.stringify(fields, null, 2));
+}
+
+async function resolveTargetSession(serverBase, sessionName, newSession) {
+  let sessions;
+  try {
+    sessions = await listSessions(serverBase);
+  } catch (err) {
+    throw new Error(`Error connecting to server: ${err.message}`);
+  }
+
+  if (sessionName) {
+    const matches = sessions.filter(s => {
+      const title = s.title || s.slug || s.id;
+      return title.toLowerCase() === sessionName.toLowerCase();
+    });
+    if (matches.length === 0) {
+      const partial = sessions.filter(s => {
+        const title = s.title || s.slug || s.id;
+        return title.toLowerCase().includes(sessionName.toLowerCase());
+      });
+      if (partial.length === 1) return partial[0].id;
+      if (partial.length > 1) throw new Error(`Error: multiple sessions match "${sessionName}"`);
+      if (!newSession) throw new Error(`Error: no session found matching "${sessionName}"`);
+      try {
+        const session = await createSession(serverBase, sessionName);
+        await selectSession(serverBase, session.id);
+        return session.id;
+      } catch (err) {
+        throw new Error(`Error creating session: ${err.message}`);
+      }
+    }
+    return matches[0].id;
+  }
+
+  if (sessions && sessions.length > 0) {
+    const sorted = sessions
+      .filter(s => s.time && (s.time.updated || s.time.created))
+      .sort((a, b) => {
+        const aTime = (a.time && a.time.updated) || (a.time && a.time.created) || 0;
+        const bTime = (b.time && b.time.updated) || (b.time && b.time.created) || 0;
+        return bTime - aTime;
+      });
+    if (sorted.length > 0) return sorted[0].id;
+  }
+
+  try {
+    const session = await createSession(serverBase, 'agentp');
+    return session.id;
+  } catch (err) {
+    throw new Error(`Error creating session: ${err.message}`);
+  }
+}
+
+// Read the deferred output file. Returns the answer string, or null if the
+// answer is not ready yet (file missing, still locked, or still empty).
+function readDeferredResult(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  if (isFileLocked(filePath)) return null;
+  let content = '';
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  return content === '' ? null : content;
+}
+
+// Poll up to timeoutMs for a ready deferred result. Returns the answer or null.
+async function waitForDeferredResult(filePath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const result = readDeferredResult(filePath);
+    if (result !== null) return result;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return null;
+    await sleepMs(Math.min(DEFER_POLL_MS, remaining));
+  }
+}
+
+function sleepMs(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function appendUnusedFollowup(result, followupText) {
+  if (!followupText) return result;
+  return result + (result.endsWith('\n') ? '' : '\n') + followupText;
+}
+
+function queuedFollowupsPath(filePath) {
+  return filePath + '.followups';
+}
+
+function readQueuedFollowups(filePath) {
+  try {
+    const text = fs.readFileSync(queuedFollowupsPath(filePath), 'utf8');
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed.filter(item => typeof item === 'string' && item) : [];
+  } catch {
+    return [];
+  }
+}
+
+function appendQueuedFollowup(filePath, followupText) {
+  if (!followupText) return;
+  const followups = readQueuedFollowups(filePath);
+  followups.push(followupText);
+  fs.writeFileSync(queuedFollowupsPath(filePath), JSON.stringify(followups, null, 2));
+}
+
+function removeQueuedFollowups(filePath) {
+  try { fs.unlinkSync(queuedFollowupsPath(filePath)); } catch {}
+}
+
+function injectQueuedFollowups(result, followups) {
+  if (!followups.length) return result;
+  const addition = followups.map(text => FOLLOWUP_ROW + text + (text.endsWith('\n') ? '' : '\n')).join('');
+  const idx = result.indexOf(AGENT_ROW);
+  if (idx === -1) return appendUnusedFollowup(result, addition.trimEnd());
+  const before = result.slice(0, idx);
+  const after = result.slice(idx);
+  return before + (before.endsWith('\n') ? '' : '\n') + addition + after;
+}
+
+function formatDeferredResult(filePath, result, qaMode, unusedFollowupText) {
+  const followups = qaMode ? readQueuedFollowups(filePath) : [];
+  const output = qaMode ? injectQueuedFollowups(result, followups) : result;
+  return appendUnusedFollowup(output, unusedFollowupText);
+}
+
 async function readAllStdin() {
   let text = '';
   const rl = readline.createInterface({ input: process.stdin });
@@ -78,7 +337,14 @@ async function main() {
   let serverBase = 'http://localhost:4096';
   let qaMode = false;
   let flushMode = false;
+  let deferMode = false;
+  let deferSeconds = 0;
+  let deferChildMode = false;
+  let onlineTicket = false;
+  let promptFile = null;
+  let outputFile = null;
   let sessionName = null;
+  let resolvedSessionId = null;
   let newSession = false;
   // tgMode: false = disabled, 'auto' = auto-detect, true = explicit --tg
   let tgMode = null;
@@ -96,6 +362,11 @@ async function main() {
       console.error('Options:');
       console.error('  --version   Show version');
       console.error('  --qa        Print the original prompt and answer with labels (useful as a filter)');
+      console.error('  --defer [N] Deferred execution: submit prompt, get a ticket immediately');
+      console.error('              (or wait up to N seconds for the answer and print it if it arrives)');
+      console.error('              Pipe the ticket back to agentp --defer to retrieve the result later');
+      console.error('  --onlineTicket');
+      console.error('              Print deferred tickets on a single line (default: pretty-printed JSON)');
       console.error('  --tg        Forward the answer to Telegram via agentp gateway (error if unavailable)');
       console.error('  --no-tg     Do not forward to Telegram');
       console.error('  --flush     Flush tgagentp\'s recorded buffer without prepending it to output');
@@ -121,7 +392,7 @@ async function main() {
       console.error('Arguments:');
       console.error('  url        OpenCode server URL or port number (default: 4096)');
       console.error('             Examples: 4096, http://localhost:4096, http://192.168.1.50:4096');
-      console.error('             Use `ocmux` (with no args) to get the URL of the current project\'s server.');
+      console.error('             Tip: $(ocmux) expands to the URL of the current project\'s server.');
       console.error('');
       console.error('See also: tgagentp -- Telegram bridge (tgagentp --help), ocmux -- manage OpenCode tmux sessions (ocmux --help)');
       console.error('');
@@ -139,6 +410,25 @@ async function main() {
       process.exit(0);
     } else if (args[i] === '--qa') {
       qaMode = true;
+    } else if (args[i] === '--defer') {
+      deferMode = true;
+      const next = args[i + 1];
+      if (next !== undefined && /^\d+$/.test(next)) {
+        deferSeconds = parseInt(next, 10);
+        i++;
+      } else {
+        deferSeconds = 0;
+      }
+    } else if (args[i] === '--defer-child') {
+      deferChildMode = true;
+    } else if (args[i] === '--onlineTicket') {
+      onlineTicket = true;
+    } else if (args[i] === '--prompt-file') {
+      i++;
+      promptFile = args[i];
+    } else if (args[i] === '--output-file') {
+      i++;
+      outputFile = args[i];
     } else if (args[i] === '--flush') {
       flushMode = true;
     } else if (args[i] === '--session') {
@@ -148,6 +438,13 @@ async function main() {
         console.error('Error: --session requires a session name');
         process.exit(1);
       }
+    } else if (args[i] === '--resolved-session-id') {
+      i++;
+      resolvedSessionId = args[i];
+      if (!resolvedSessionId) {
+        console.error('Error: --resolved-session-id requires a session id');
+        process.exit(1);
+      }
     } else if (args[i] === '--new') {
       newSession = true;
     } else if (args[i] === '--getLast') {
@@ -289,113 +586,243 @@ async function main() {
 
   const promptText = await readAllStdin();
 
-  // Find most recent session or create one
-  let sessions;
-  try {
-    sessions = await listSessions(serverBase);
-  } catch (err) {
-    console.error('Error connecting to server:', err.message);
-    process.exit(1);
-  }
+  // Handle --defer mode
+  if (deferMode) {
+    // Check if stdin is a deferred ticket
+    const ticket = parseDeferredTicketInput(promptText);
 
-  let sessionId = null;
+    if (ticket) {
+      // This is a ticket — retrieve the result. The --defer argument is
+      // ignored; the ticket's own "defer" timeout is used instead (default 0).
+      const deferredPath = ticket.path;
 
-  if (sessionName) {
-    // Find session by name
-    const matches = sessions.filter(s => {
-      const title = s.title || s.slug || s.id;
-      return title.toLowerCase() === sessionName.toLowerCase();
-    });
-    if (matches.length === 0) {
-      // Try partial match
-      const partial = sessions.filter(s => {
-        const title = s.title || s.slug || s.id;
-        return title.toLowerCase().includes(sessionName.toLowerCase());
-      });
-      if (partial.length === 1) {
-        sessionId = partial[0].id;
-      } else if (partial.length > 1) {
-        console.error(`Error: multiple sessions match "${sessionName}":`);
-        partial.forEach(s => console.error(`  - ${s.title || s.slug || s.id}`));
+      if (!fs.existsSync(deferredPath)) {
+        process.stdout.write(`Error: deferred file not found: ${deferredPath}\n`);
         process.exit(1);
-      } else if (newSession) {
-        // Create new session
+      }
+
+      let result = ticket.followupText
+        ? readDeferredResult(deferredPath)
+        : await waitForDeferredResult(deferredPath, ticket.defer * 1000);
+
+      if (result !== null) {
+        // Answer available — return it and remove the temp file
         try {
-          const session = await createSession(serverBase, sessionName);
-          sessionId = session.id;
-          await selectSession(serverBase, sessionId);
+          fs.unlinkSync(deferredPath);
         } catch (err) {
-          console.error('Error creating session:', err.message);
+          process.stdout.write(`Error reading deferred file: ${err.message}\n`);
           process.exit(1);
         }
-      } else {
-        console.error(`Error: no session found matching "${sessionName}"`);
-        console.error('Use --new to create a new session with this name');
-        process.exit(1);
+        try { fs.unlinkSync(deferredPath + '.lock'); } catch {}
+        process.stdout.write(formatDeferredResult(deferredPath, result, qaMode, ticket.followupText));
+        removeQueuedFollowups(deferredPath);
+        process.exit(0);
       }
-    } else {
-      sessionId = matches[0].id;
+
+      if (ticket.followupText) {
+        if (!ticket.server || !ticket.sessionId) {
+          process.stdout.write('Error: deferred ticket does not include server/sessionId; cannot queue follow-up text. Re-submit only the ticket to check the result.\n');
+          process.exit(1);
+        }
+        try {
+          await sendToSessionAsync(ticket.server, ticket.sessionId, ticket.followupText);
+          appendQueuedFollowup(deferredPath, ticket.followupText);
+        } catch (err) {
+          process.stdout.write(`Error queueing follow-up prompt: ${err.message}\n`);
+          process.exit(1);
+        }
+      }
+
+      if (result === null && ticket.defer > 0) {
+        result = await waitForDeferredResult(deferredPath, ticket.defer * 1000);
+        if (result !== null) {
+          try {
+            fs.unlinkSync(deferredPath);
+          } catch (err) {
+            process.stdout.write(`Error reading deferred file: ${err.message}\n`);
+            process.exit(1);
+          }
+          try { fs.unlinkSync(deferredPath + '.lock'); } catch {}
+          process.stdout.write(formatDeferredResult(deferredPath, result, qaMode, ''));
+          removeQueuedFollowups(deferredPath);
+          process.exit(0);
+        }
+      }
+
+      // Answer not available yet — re-print the ticket with updated elapsed
+      const elapsed = ticket.ctime
+        ? Math.max(0, Math.floor((Date.now() - Date.parse(ticket.ctime)) / 1000))
+        : 0;
+      process.stdout.write(formatTicket(ticket, elapsed, onlineTicket) + '\n');
+      process.exit(0);
     }
-  } else if (sessions && sessions.length > 0) {
-    const sorted = sessions
-      .filter(s => s.time && (s.time.updated || s.time.created))
-      .sort((a, b) => {
-        const aTime = (a.time && a.time.updated) || (a.time && a.time.created) || 0;
-        const bTime = (b.time && b.time.updated) || (b.time && b.time.created) || 0;
-        return bTime - aTime;
-      });
-    if (sorted.length > 0) sessionId = sorted[0].id;
-  }
 
-  if (!sessionId) {
+    // This is a regular prompt — create deferred execution
+    const tempPath = generateTempFilename();
+    const promptTempPath = tempPath + '.prompt';
+
+    let targetSessionId;
     try {
-      const session = await createSession(serverBase, 'agentp');
-      sessionId = session.id;
+      targetSessionId = await resolveTargetSession(serverBase, sessionName, newSession);
     } catch (err) {
-      console.error('Error creating session:', err.message);
+      console.error(err.message);
       process.exit(1);
     }
-  }
 
-  let answer;
-  try {
-    answer = await sendToSession(serverBase, sessionId, promptText);
-  } catch (err) {
-    console.error('Error sending prompt:', err.message);
-    process.exit(1);
+    // Write prompt to temp file for child process
+    fs.writeFileSync(promptTempPath, promptText);
+
+    // Create and lock the output file
+    fs.writeFileSync(tempPath, '');
+    lockFile(tempPath);
+
+    const newTicket = {
+      ctime: new Date().toISOString(),
+      path: tempPath,
+      defer: deferSeconds,
+      server: serverBase,
+      sessionId: targetSessionId,
+    };
+
+    // Spawn detached child process
+    const childArgs = [
+      __filename,
+      '--defer-child',
+      '--prompt-file', promptTempPath,
+      '--output-file', tempPath,
+    ];
+
+    // Pass through other flags
+    if (qaMode) childArgs.push('--qa');
+    if (tgMode === true) childArgs.push('--tg');
+    if (tgMode === false) childArgs.push('--no-tg');
+    if (flushMode) childArgs.push('--flush');
+    if (sessionName) {
+      childArgs.push('--session', sessionName);
+      if (newSession) childArgs.push('--new');
+    }
+    childArgs.push('--resolved-session-id', targetSessionId);
+    childArgs.push(serverBase);
+
+    const child = child_process.spawn(process.execPath, childArgs, {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+
+    // If a timeout was given, block until the answer arrives or the timeout
+    // expires. Return the response when it arrives; otherwise print a ticket.
+    if (deferSeconds > 0) {
+      const result = await waitForDeferredResult(tempPath, deferSeconds * 1000);
+      if (result !== null) {
+        try {
+          fs.unlinkSync(tempPath);
+        } catch (err) {
+          process.stdout.write(`Error reading deferred file: ${err.message}\n`);
+          process.exit(1);
+        }
+        try { fs.unlinkSync(tempPath + '.lock'); } catch {}
+        process.stdout.write(result);
+        process.exit(0);
+      }
+    }
+
+    // Output the deferred ticket
+    process.stdout.write(formatTicket(newTicket, undefined, onlineTicket) + '\n');
+    process.exit(0);
   }
 
-  // Build the message to send to Telegram (QA pair with rulers)
-  let tgMessage = answer;
-  if (qaMode) {
-    tgMessage = HUMAN_ROW + promptText + AGENT_ROW + answer;
-    if (!answer.endsWith('\n')) tgMessage += '\n';
-    tgMessage += FINAL_ROW;
+  // Handle --defer-child mode (child process)
+  let actualPromptText = promptText;
+  if (deferChildMode && promptFile) {
+    try {
+      actualPromptText = fs.readFileSync(promptFile, 'utf8');
+      fs.unlinkSync(promptFile);
+    } catch (err) {
+      const errMsg = `Error reading prompt file: ${err.message}\n`;
+      if (outputFile) { fs.writeFileSync(outputFile, errMsg); unlockFile(outputFile); }
+      process.stdout.write(errMsg);
+      process.exit(1);
+    }
   }
 
-  // Post-send: notify tgagentp, get recorded context back
-  let buffered = [];
+  // Wrap main processing in try-catch for deferChildMode to write errors to output file
   let tgError = null;
-  if (tgPort) {
+  async function runMain() {
+    const sessionId = resolvedSessionId || await resolveTargetSession(serverBase, sessionName, newSession);
+
+    let answer;
     try {
-      buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
+      answer = await sendToSession(serverBase, sessionId, actualPromptText);
     } catch (err) {
-      tgError = err;
+      throw new Error(`Error sending prompt: ${err.message}`);
     }
-  }
 
-  // Build stdout output (prepend recorded context if any, unless --flush)
-  if (qaMode) {
-    if (!flushMode && buffered.length > 0) {
-      for (const msg of buffered) {
-        const row = msg.role === 'user' ? HUMAN_ROW : AGENT_ROW;
-        process.stdout.write(row + msg.text + '\n');
+    // Build the message to send to Telegram (QA pair with rulers)
+    let tgMessage = answer;
+    if (qaMode) {
+      tgMessage = HUMAN_ROW + actualPromptText + AGENT_ROW + answer;
+      if (!answer.endsWith('\n')) tgMessage += '\n';
+      tgMessage += FINAL_ROW;
+    }
+
+    // Post-send: notify tgagentp, get recorded context back
+    let buffered = [];
+    if (tgPort) {
+      try {
+        buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
+      } catch (err) {
+        tgError = err;
+      }
+    }
+
+    // Build output (prepend recorded context if any, unless --flush)
+    let output = '';
+    if (qaMode) {
+      if (!flushMode && buffered.length > 0) {
+        for (const msg of buffered) {
+          const row = msg.role === 'user' ? HUMAN_ROW : AGENT_ROW;
+          output += row + msg.text + '\n';
+        }
       }
+      output += tgMessage;
+    } else {
+      output = tgMessage;
+      if (!tgMessage.endsWith('\n')) output += '\n';
+    }
+
+    return output;
+  }
+
+  // Execute main processing with error handling for child mode
+  let output = '';
+  try {
+    output = await runMain();
+  } catch (err) {
+    const errMsg = err.message + '\n';
+    if (deferChildMode && outputFile) {
+      fs.writeFileSync(outputFile, errMsg);
+      unlockFile(outputFile);
+    } else {
+      console.error(err.message);
+    }
+    process.exit(1);
+  }
+
+  // Write output to file (child mode) or stdout (normal mode)
+  let finalOutput = output;
+  if (deferChildMode && outputFile) {
+    try {
+      fs.writeFileSync(outputFile, output);
+      unlockFile(outputFile);
+    } catch (err) {
+      const errMsg = `Error writing output file: ${err.message}\n`;
+      try { fs.writeFileSync(outputFile, errMsg); } catch {}
+      unlockFile(outputFile);
+      process.exit(1);
     }
-    process.stdout.write(tgMessage);
   } else {
-    process.stdout.write(tgMessage);
-    if (!tgMessage.endsWith('\n')) process.stdout.write('\n');
+    process.stdout.write(output);
   }
 
   // Warnings at the end (stderr)
@@ -416,5 +843,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, notifyAgentpGateway, readAllStdin };
-
+module.exports = { main, notifyAgentpGateway, readAllStdin, parseDeferredTicket, parseDeferredTicketInput, formatTicket, waitForDeferredResult };

package/bin/ocmux

@@ -24,6 +24,7 @@ const {
   resurrectServer,
   startServer,
   getActiveServer,
+  activateServer,
 } = require('../lib/ocmux');
 
 // ---------------------------------------------------------------------------
@@ -182,6 +183,9 @@ function printHelp() {
   console.error('            Works even if no tmux window exists (stale state file).');
   console.error('            --print-logs  Pass --print-logs to the new opencode serve.');
   console.error('  list      List all running servers with their directories and URLs.');
+  console.error('  switch    Interactively select a server to switch to.');
+  console.error('            j/k or arrows to move, Enter/Space selects (menu stays open),');
+  console.error('            q or Ctrl+C quits. Prints the URL of the last selected server on exit.');
   console.error('');
   console.error('  --         Treat the next argument as a directory even if it matches');
   console.error('            a subcommand name (e.g. "ocmux -- kill").');
@@ -253,6 +257,116 @@ function cmdSwitch(statefile, longMode) {
   outputUrl(url, serverDir, longMode);
 }
 
+// ---------------------------------------------------------------------------
+// Subcommand: switch — interactive session selection
+// ---------------------------------------------------------------------------
+
+function cmdSwitchMenu(longMode) {
+  const rows = listServers();
+  if (rows.length === 0) {
+    console.error('No opencode servers running.');
+    process.exit(1);
+  }
+  if (!process.stdin.isTTY) {
+    console.error('Error: "switch" is interactive and requires a TTY.');
+    console.error('Use "ocmux list" to list servers, or run "ocmux <dir>" to switch directly.');
+    process.exit(1);
+  }
+
+  const cols = process.stderr.columns || 80;
+  const nameW = Math.max(...rows.map(r => path.basename(r.dir).length), 4);
+  const stsW = Math.max(...rows.map(r => r.status.length), 6);
+  const urlW = Math.max(...rows.map(r => r.url.length), 3);
+  const dirW = Math.max(...rows.map(r => r.dir.length), 9);
+  const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
+  const lineWidth = Math.max(cols, nameW + 2 + stsW + 2 + urlW + 2 + dirW);
+
+  let cursor = 0;
+  let activeRow = 0;
+  let lastUrl = null;
+  let lastDir = null;
+  let exited = false;
+
+  // Query tmux for the currently active window and map it to a row. Called at
+  // init and on every draw, so the highlight always reflects tmux's real state.
+  const refreshActive = () => {
+    const idx = activeWindowIndex();
+    if (idx == null) return;
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i].index === idx) { activeRow = i; return; }
+    }
+  };
+
+  const cleanup = () => {
+    process.stderr.write('\x1b[?25h');
+    process.stderr.write('\x1b[?1049l');
+    try { process.stdin.setRawMode(false); } catch {}
+  };
+
+  const finish = () => {
+    if (exited) return;
+    exited = true;
+    cleanup();
+    process.stdin.pause();
+    if (lastUrl) outputUrl(lastUrl, lastDir, longMode);
+    process.exit(0);
+  };
+
+  const draw = () => {
+    refreshActive();
+    let out = '\x1b[2J\x1b[H';
+    out += 'ocmux switch — j/k or arrows: move, Enter/Space: select (keep switching), q/Ctrl+C: quit\n\n';
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const marker = i === cursor ? '▶ ' : '  ';
+      const line = `${marker}${pad(path.basename(row.dir), nameW)}  ${pad(row.status, stsW)}  ${pad(row.url, urlW)}  ${pad(row.dir, dirW)}`;
+      if (i === activeRow) {
+        out += '\x1b[7m' + pad(line, lineWidth) + '\x1b[0m\n';
+      } else {
+        out += line + '\n';
+      }
+    }
+    process.stderr.write(out);
+  };
+
+  const activate = (i) => {
+    const row = rows[i];
+    try {
+      activateServer(row.dir, row.index, row.url);
+      lastUrl = row.url;
+      lastDir = row.dir;
+    } catch (err) {
+      process.stderr.write(`\nError: ${err.message}\n`);
+    }
+    draw();
+  };
+
+  process.stdin.on('keypress', (str, key) => {
+    if (key.ctrl && key.name === 'c') return finish();
+    if (key.name === 'q') return finish();
+    if (key.name === 'up' || str === 'k') {
+      cursor = (cursor + rows.length - 1) % rows.length;
+      draw();
+    } else if (key.name === 'down' || str === 'j') {
+      cursor = (cursor + 1) % rows.length;
+      draw();
+    } else if (key.name === 'return' || key.name === 'enter' || key.name === 'space') {
+      activate(cursor);
+    }
+  });
+
+  process.on('SIGINT', finish);
+  process.on('SIGTERM', finish);
+
+  readline.emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stderr.write('\x1b[?1049h\x1b[?25l');
+  refreshActive();
+  cursor = activeRow;
+  draw();
+}
+
 // ---------------------------------------------------------------------------
 // Subcommand: list
 // ---------------------------------------------------------------------------
@@ -506,7 +620,7 @@ function main() {
         process.exit(1);
       }
       targetDir = resolveDir(arg);
-    } else if (arg === 'serve' || arg === 'new' || arg === 'kill' || arg === 'list' || arg === 'resurrect') {
+    } else if (arg === 'serve' || arg === 'new' || arg === 'kill' || arg === 'list' || arg === 'resurrect' || arg === 'switch') {
       if (subcommand) {
         console.error(`Error: multiple subcommands specified: '${subcommand}' and '${arg}'`);
         process.exit(1);
@@ -566,6 +680,21 @@ function main() {
       process.exit(1);
     }
     cmdList();
+  } else if (subcommand === 'switch') {
+    if (gitMode) {
+      console.error("Error: '--git' and '--GIT' are only valid with 'serve'.");
+      process.exit(1);
+    }
+    if (printLogs) {
+      console.error("Error: '--print-logs' is only valid with 'serve'.");
+      process.exit(1);
+    }
+    if (targetDir !== process.cwd()) {
+      console.error("Error: 'switch' does not accept a directory path.");
+      process.exit(1);
+    }
+    ensureSession();
+    cmdSwitchMenu(longMode);
   } else if (subcommand === 'kill') {
     if (gitMode) {
       console.error("Error: '--git' and '--GIT' are only valid with 'serve'.");
@@ -606,7 +735,7 @@ function main() {
     // Default mode — find an existing server and switch to it
     let sf = findParentStatefile(targetDir);
     if (!sf) {
-      console.error(`Error: no opencode server found in ${targetDir} or any of its parents.`);
+      console.log(`Error: no opencode server found in ${targetDir} or any of its parents.`);
       console.error("Run 'ocmux serve' to create a new server.");
       process.exit(1);
     }
@@ -628,4 +757,8 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

package/bin/tgagentp

@@ -1017,20 +1017,38 @@ async function processTelegramCommands(text, server, token, chatState) {
   const filesSent = [];
   const dir = serverDir(server);
 
+  // Resolve a file path: absolute paths used directly, relative paths resolved
+  // against the server's working directory. Returns null and sends an error
+  // message if the resolved path is outside the server's working directory.
+  function resolveUploadPath(p, errPrefix) {
+    const absolute = path.isAbsolute(p) ? p : path.resolve(dir || '', p);
+    if (!dir) return absolute; // no server dir — trust the path
+    let realDir, realPath;
+    try { realDir = fs.realpathSync(dir); } catch { realDir = dir; }
+    try { realPath = fs.realpathSync(absolute); } catch { realPath = absolute; }
+    if (!realPath.startsWith(realDir + path.sep) && realPath !== realDir) {
+      sendLongMessage(token, chatState,
+        `❌ ${errPrefix}: path outside project directory.\n` +
+        `  Path: \`${p}\`\n` +
+        `  Project: \`${realDir}\`\n\n` +
+        `Use a full path (starting with /) or a path relative to the project root.`).catch(() => {});
+      return null;
+    }
+    return absolute;
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const payload = parseTelegramLine(lines[i]);
     if (!payload) continue;
 
     if (payload.command === 'upload' && payload.path) {
       toStrip.add(i);
-      const resolved = dir ? path.resolve(dir, payload.path) : path.resolve(payload.path);
-      if (dir && !resolved.startsWith(dir + path.sep)) {
-        log.error(`processTelegramCommands: path outside project rejected: ${payload.path}`);
-        continue;
-      }
+      const resolved = resolveUploadPath(payload.path, 'Upload');
+      if (!resolved) continue;
       try {
         if (!fs.existsSync(resolved)) {
-          log.error(`processTelegramCommands: file not found: ${resolved}`);
+          await sendLongMessage(token, chatState,
+            `❌ File not found: \`${resolved}\``);
           continue;
         }
         const fileData = fs.readFileSync(resolved);
@@ -1039,22 +1057,21 @@ async function processTelegramCommands(text, server, token, chatState) {
         await sendTelegramDocument(token, chatState, fileData, fileName, caption);
         filesSent.push(fileName);
       } catch (err) {
-        log.error(`processTelegramCommands: failed to send file ${resolved}: ${err.message}`);
+        await sendLongMessage(token, chatState,
+          `❌ Failed to upload \`${resolved}\`: ${err.message}`);
       }
     } else if (payload.command === 'download' && payload.fileId && payload.path) {
       toStrip.add(i);
-      const resolved = dir ? path.resolve(dir, payload.path) : path.resolve(payload.path);
-      if (dir && !resolved.startsWith(dir + path.sep)) {
-        log.error(`processTelegramCommands: download path outside project rejected: ${payload.path}`);
-        continue;
-      }
+      const resolved = resolveUploadPath(payload.path, 'Download');
+      if (!resolved) continue;
       try {
         const fileData = await downloadTelegramFile(token, payload.fileId);
         fs.mkdirSync(path.dirname(resolved), { recursive: true });
         fs.writeFileSync(resolved, fileData);
         filesSent.push(path.basename(resolved));
       } catch (err) {
-        log.error(`processTelegramCommands: failed to download file: ${err.message}`);
+        await sendLongMessage(token, chatState,
+          `❌ Failed to download file to \`${resolved}\`: ${err.message}`);
       }
     } else if (payload.command === 'help') {
       toStrip.add(i);
@@ -2154,8 +2171,13 @@ async function main() {
     'Do NOT use CLI tools to generate them — just include them directly in your response:\n\n' +
     'To send a file to the user:\n' +
     '[Telegram]{"command":"upload","path":"<relative-path>","msg":"<optional caption>"}\n\n' +
+    '**Important:** `path` is relative to the project root (the OpenCode server\'s working directory).\n' +
+    'If the project uses a git worktree, the worktree directory IS the project root.\n' +
+    'Use CLI commands like `cat ./path/to/file` to verify the file exists before uploading.\n\n' +
     'To download a file the user sent:\n' +
     '[Telegram]{"command":"download","fileId":"<id>","path":"<relative-destination>"}\n\n' +
+    '**Important:** `path` is also relative to the project root (the OpenCode server\'s working directory).\n' +
+    'Use `ls` or `pwd` to confirm the current working directory before specifying download paths.\n\n' +
     'For more details about a command:\n' +
     '[Telegram]{"command":"help","topic":"<upload|download|help>"}';
 
@@ -2174,6 +2196,7 @@ async function main() {
     const monRef = { current: null };
     st._monitorRef = monRef;
     st._monitorStarted = true;
+    st._monitoredSessionId = sessionId;
 
     const notifiedPerms = new Set();
 
@@ -2239,6 +2262,7 @@ async function main() {
       if (getState(server)._monitorRef === monRef) {
         getState(server)._monitorRef = null;
         getState(server)._monitorStarted = false;
+        getState(server)._monitoredSessionId = null;
       }
     });
   }
@@ -2271,6 +2295,20 @@ async function main() {
 
   async function processMessageAsync(chatId, text, url, useSession, sessionId, myTaskId, replyTo, threadId) {
     const st = getState(url);
+    // Auto-discover active session if not set
+    if (!sessionId) {
+      try {
+        const discovered = await discoverActiveSession(url);
+        if (discovered) {
+          st.activeSessionId = discovered.id;
+          st.activeSessionName = discovered.name;
+          sessionId = discovered.id;
+          useSession = true;
+        }
+      } catch (err) {
+        log.debug(`processMessageAsync: auto-discover error: ${err.message}`);
+      }
+    }
     const isCancelled = () => getState(url).taskId !== myTaskId;
     const cancelRef = { current: null };
     const chatState = { chatId, threadId };
@@ -2281,11 +2319,12 @@ async function main() {
     st._cancelRef = cancelRef;
     st._sessionReq = sessionCancelRef;
 
-    // Ensure the persistent session monitor is running so question/permission
-    // events from any source (agentp, tgagentp, TUI) are caught, not just
-    // those triggered by this message's per-request SSE listener.
-    if (useSession && sessionId && !st._monitorStarted) {
-      startSessionMonitor(url, sessionId);
+    // Ensure the persistent session monitor is running and tracking the current session.
+    // Always restart when sessionId changes so TUI-initiated session switches are followed.
+    if (useSession && sessionId) {
+      if (!st._monitorStarted || st._monitoredSessionId !== sessionId) {
+        startSessionMonitor(url, sessionId);
+      }
     }
 
     try {

package/docs/specification.md

@@ -31,13 +31,25 @@ Reads stdin, sends to the most recent or named OpenCode session, streams answer
 **Options:**
 
 | Flag | Effect |
-|---|---|
+|---|---|---|
 | `--qa` | Print prompt/answer with rulers; auto-detect tgagentp |
+| `--defer [N]` | Deferred execution — submit a prompt and get a ticket immediately, or wait up to N seconds (default `0`) for the answer; piping the ticket back retrieves the result later |
+| `--onlineTicket` | Print deferred tickets on a single line (default: pretty-printed JSON) |
 | `--tg` | Forward answer via tgagentp gateway (error if unavailable) |
 | `--no-tg` | Explicitly disable Telegram forwarding |
 | `--flush` | Flush recorded buffer without prepending |
 | `--getLast N` | Retrieve last N assistant answers from session history |
 
+**Deferred tickets (`--defer`):**
+
+Ticket format on stdout: `agentp_ticket` followed by a JSON object `{ ctime, path, server, sessionId, elapsed, defer }`, printed as pretty-printed (multi-line) JSON by default or on a single line with `--onlineTicket`. Both formats are accepted when piping a ticket back.
+
+- First print omits `elapsed`; `defer` is included only when it was `> 0`.
+- Re-prints (answer not ready yet) include `elapsed` computed from `ctime` (0 when `ctime` is missing/unparseable).
+- A ticket piped back to `agentp --defer` ignores the CLI `--defer` value and uses the ticket's own `defer` (default 0): ready → print answer + delete temp file; not ready → re-print the ticket with updated `elapsed`; file missing → error, exit 1.
+- If a ticket is followed by additional text and the answer is not ready, `agentp --defer` sends that text to the ticket's `server`/`sessionId` with `sendToSessionAsync()` (`POST /session/:id/prompt_async`), stores it in a ticket sidecar file, and re-prints the ticket without echoing the extra text. When the final answer is retrieved with `--qa`, stored follow-ups are injected into the prompt block under `📝` separators; without `--qa`, they are omitted from output. If the answer is ready, appended text is not sent and is printed after the returned answer. Older tickets without `server`/`sessionId` can retrieve results but cannot queue follow-up text.
+- New run with `--defer N` (N > 0): wait up to N seconds polling the temp file; answer arrives in time → print + delete; else print the ticket and keep the background child alive.
+
 **Protocol:**
 
 1. Reads all stdin → string
@@ -63,9 +75,14 @@ Manages per-project OpenCode servers in a persistent `Opencode` tmux session.
 | `new [dir]` | Alias for `serve` (deprecated) |
 | `kill [dir]` | Kill server, remove tmux window + `.ocmux.json` |
 | `resurrect [dir]` | Recover dead server: kill old window, remove state file, create fresh server + TUI |
+| `switch` | Interactive session picker (TTY required) |
 | `list [-l]` | List all running servers |
 | _(no arg)_ | Switch to existing server (searches upward for `.ocmux.json`) |
 
+**`switch` behavior:** Renders an interactive menu of all running servers on an alt screen with columns `dirname | status | url | full path`. `j`/`k` or arrow keys move the cursor; `Enter`/`Space` activates the selected server (switches its tmux window) and keeps the menu open; `q`/`Ctrl+C` exits and prints the URL of the last selected server (if any). The row matching the tmux-active window (queried live from tmux via `activeWindowIndex()` on every redraw) is highlighted across the full line width, so the highlight tracks both local activations and external tmux window switches. Errors (exit 1) when no TTY or no servers. Rejects `--git`, `--GIT`, `--print-logs`, and directory arguments.
+
+**Default no-server behavior:** When no `.ocmux.json` is found for the current/target directory or any parent, default mode prints the primary `Error: no opencode server found...` line to stdout and the `Run 'ocmux serve'...` hint to stderr. This makes command substitution (`agentp $(ocmux)`) fail safely instead of passing no argument and falling back to `agentp`'s default server.
+
 **Flags:** `--git`, `--GIT`, `--print-logs`, `-l`, `--version`
 
 **Window layout:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentp",
-  "version": "0.12.0",
+  "version": "1.13.0",
   "description": "Pipe prompts into a running OpenCode TUI session and stream the final answer",
   "bin": {
     "agentp": "bin/agentp",