agentp 1.12.1 → 1.13.0

package/README.md

@@ -59,7 +59,8 @@ agentp [options] [url]
 Options:
 
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
-- `--defer`: deferred execution — submit prompt, get immediate ticket, retrieve result later
+- `--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
@@ -72,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
 
@@ -147,18 +156,83 @@ context for a new topic.
 
 Deferred execution with `--defer`:
 
-Submit a prompt and get an immediate ticket to retrieve the result later:
+Submit a prompt and get a ticket to retrieve the result later:
 
 ```bash
-# Submit a prompt and get a deferred reference
+# Submit a prompt and get a deferred ticket (optionally wait up to N seconds)
 DEFERRED=$(printf "Refactor the authentication module" | agentp --defer)
-# Output: <agentp-deferred>/tmp/agentp_deferred_20260803_1430_a1b2.tmp</agentp-deferred>
+# 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
@@ -166,15 +240,18 @@ Works as a Vim/Neovim filter with deferred execution:
 :'<,'>!agentp --defer --qa
 
 " Later, retrieve the result
-:r !printf '%s\n' "<agentp-deferred>/tmp/agentp_deferred_...tmp</agentp-deferred>" | agentp --defer
+: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 immediate ticket (`<agentp-deferred>...</agentp-deferred>`)
+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 your input back (identity filter)
-4. If complete, you get the agent's response and the temp file is cleaned up
+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.
 
@@ -204,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:
@@ -217,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

@@ -10,6 +10,7 @@ const child_process = require('child_process');
 const { version } = require('../package.json');
 const {
   sendToSession,
+  sendToSessionAsync,
   listSessions,
   createSession,
   getSession,
@@ -108,6 +109,216 @@ function generateTempFilename() {
   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 });
@@ -127,10 +338,13 @@ async function main() {
   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;
@@ -148,7 +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     Deferred execution: write prompt to temp file, return path immediately');
+      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');
@@ -174,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('');
@@ -194,8 +412,17 @@ async function main() {
       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];
@@ -211,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') {
@@ -354,85 +588,148 @@ async function main() {
 
   // Handle --defer mode
   if (deferMode) {
-    // Check if stdin is a deferred reference
-    const deferredMatch = promptText.match(/<agentp-deferred>(.*?)<\/agentp-deferred>/);
-    
-    if (deferredMatch) {
-      // This is a deferred reference - retrieve the result
-      const deferredPath = deferredMatch[1].trim();
-      
+    // Check if stdin is a deferred ticket
+    const ticket = parseDeferredTicketInput(promptText);
+
+    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 (!fs.existsSync(deferredPath)) {
-        // File doesn't exist - error
         process.stdout.write(`Error: deferred file not found: ${deferredPath}\n`);
         process.exit(1);
       }
-      
-      // Check if file is locked (still processing) or empty (not ready yet)
-      const isLocked = isFileLocked(deferredPath);
-      let content = '';
-      try {
-        content = fs.readFileSync(deferredPath, 'utf8');
-      } catch {
-        content = '';
-      }
-      
-      if (isLocked || content === '') {
-        // File is locked (still processing) or empty (not ready yet) - identity filter
-        process.stdout.write(promptText);
+
+      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 {
+          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, ticket.followupText));
+        removeQueuedFollowups(deferredPath);
         process.exit(0);
       }
-      
-      // File exists, not locked, and has content - read and delete
-      try {
-        fs.unlinkSync(deferredPath);
-        process.stdout.write(content);
-        process.exit(0);
-      } catch (err) {
-        process.stdout.write(`Error reading deferred file: ${err.message}\n`);
-        process.exit(1);
+
+      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);
+        }
       }
-    } else {
-      // This is a regular prompt - create deferred execution
-      const tempPath = generateTempFilename();
-      const promptTempPath = tempPath + '.prompt';
-      
-      // Write prompt to temp file for child process
-      fs.writeFileSync(promptTempPath, promptText);
-      
-      // Create and lock the output file
-      fs.writeFileSync(tempPath, '');
-      lockFile(tempPath);
-      
-      // Output the deferred reference
-      process.stdout.write(`<agentp-deferred>${tempPath}</agentp-deferred>\n`);
-      
-      // 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');
+
+      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);
+        }
       }
-      childArgs.push(serverBase);
-      
-      const child = child_process.spawn(process.execPath, childArgs, {
-        detached: true,
-        stdio: 'ignore',
-      });
-      child.unref();
-      
+
+      // 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);
     }
+
+    // This is a regular prompt — create deferred execution
+    const tempPath = generateTempFilename();
+    const promptTempPath = tempPath + '.prompt';
+
+    let targetSessionId;
+    try {
+      targetSessionId = await resolveTargetSession(serverBase, sessionName, newSession);
+    } catch (err) {
+      console.error(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);
   }
 
   // Handle --defer-child mode (child process)
@@ -450,67 +747,9 @@ async function main() {
   }
 
   // Wrap main processing in try-catch for deferChildMode to write errors to output file
+  let tgError = null;
   async function runMain() {
-    // Find most recent session or create one
-    let sessions;
-    try {
-      sessions = await listSessions(serverBase);
-    } catch (err) {
-      throw new Error(`Error connecting to server: ${err.message}`);
-    }
-
-    let sessionId = null;
-
-    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) {
-          throw new Error(`Error: multiple sessions match "${sessionName}"`);
-        } else if (newSession) {
-          // Create new session
-          try {
-            const session = await createSession(serverBase, sessionName);
-            sessionId = session.id;
-            await selectSession(serverBase, sessionId);
-          } catch (err) {
-            throw new Error(`Error creating session: ${err.message}`);
-          }
-        } else {
-          throw new Error(`Error: no session found matching "${sessionName}"`);
-        }
-      } else {
-        sessionId = matches[0].id;
-      }
-    } 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) {
-      try {
-        const session = await createSession(serverBase, 'agentp');
-        sessionId = session.id;
-      } catch (err) {
-        throw new Error(`Error creating session: ${err.message}`);
-      }
-    }
+    const sessionId = resolvedSessionId || await resolveTargetSession(serverBase, sessionName, newSession);
 
     let answer;
     try {
@@ -529,7 +768,6 @@ async function main() {
 
     // Post-send: notify tgagentp, get recorded context back
     let buffered = [];
-    let tgError = null;
     if (tgPort) {
       try {
         buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
@@ -566,7 +804,7 @@ async function main() {
       fs.writeFileSync(outputFile, errMsg);
       unlockFile(outputFile);
     } else {
-      process.stdout.write(errMsg);
+      console.error(err.message);
     }
     process.exit(1);
   }
@@ -605,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/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": "1.12.1",
+  "version": "1.13.0",
   "description": "Pipe prompts into a running OpenCode TUI session and stream the final answer",
   "bin": {
     "agentp": "bin/agentp",