@halfwhey/claudraband-core 0.2.0 → 0.3.0

package/README.md

@@ -75,17 +75,21 @@ cband continue <session-id> --select 3 "xyz"
 ### Headless persistent sessions with `serve`
 
 ```sh
-cband serve --host 127.0.0.1 --backend xterm --port 7842
+cband serve --host 127.0.0.1 --port 7842
 cband --connect localhost:7842 "start a migration plan"
 cband attach <session-id>
 cband continue <session-id> --select 2
 ```
 
-Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically. `attach` is especially useful here because it gives you a simple REPL for a headless xterm.js session.
+The daemon now defaults to `tmux`, just like the local first-class path. Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically.
 
-### Using the CLI without tmux or server
+`--backend xterm` still exists, but it is experimental while we improve it.
 
-If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. That mode is useful for one-off runs, but it is not a good default for interactive follow-up because the session is not kept alive between commands. It only works properly when Claude itself can proceed without an interactive permission prompt. Use one of:
+### Using the CLI without tmux or server (experimental)
+
+If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. This backend is **experimental** and slower than tmux. It is useful for one-off runs, but it is not a good default for interactive follow-up because the session is not kept alive between commands.
+
+The xterm backend cannot handle Claude Code's initial startup prompts (trust folder, bypass permissions confirmation). You must disable these before using it:
 
 - `-c "--dangerously-skip-permissions"`
 - `--permission-mode bypassPermissions`
@@ -109,9 +113,9 @@ Some ACP clients still have limitations around resuming existing sessions. `clau
 
 Live sessions are tracked in `~/.claudraband/`.
 
-- `cband sessions` shows only live tracked sessions, either hosted by tmux or the xterm.js daemon.
+- `cband sessions` shows only live tracked sessions, either hosted by tmux directly or by the daemon.
 - `continue` can resume an existing Claude Code session even when it is no longer live, but `attach` only works on live sessions.
-- `sessions close ...` closes live sessions hosted by tmux or the xterm.js daemon
+- `sessions close ...` closes live sessions hosted by tmux directly or by the daemon
 - `sessions close --all` will close all live sessions controlled by Claudraband
 
 ## Examples

package/dist/claude/claude.d.ts

@@ -41,6 +41,9 @@ export declare class ClaudeWrapper implements Wrapper {
     /**
      * Poll the terminal until Claude Code is ready to accept input.
      * Looks for "INSERT" in the status bar, which indicates the TUI has loaded.
+     *
+     * Also handles the "trust this folder" prompt that appears before any JSONL
+     * is written when Claude Code runs in a directory for the first time.
      */
     private waitForReady;
     stop(): Promise<void>;

package/dist/index.js

@@ -1096,6 +1096,9 @@ class ClaudeWrapper {
         if (pane.includes("INSERT") || pane.includes("NORMAL")) {
           return;
         }
+        if (pane.includes("Yes, I trust this folder") && pane.includes("No, exit") || pane.includes("Bypass Permissions mode") && pane.includes("Yes, I accept")) {
+          return;
+        }
       } catch {}
       await new Promise((r) => setTimeout(r, POLL_MS));
     }
@@ -1178,6 +1181,9 @@ function parseClaudeArgs(args) {
 }
 // src/claude/inspect.ts
 import { readFile } from "node:fs/promises";
+function normalizeCapturedPane(paneText) {
+  return paneText.replace(/\r/g, "").replace(/\x1b\[(\d+)C/g, (_match, count) => " ".repeat(Number.parseInt(count, 10) || 0)).replace(/\x1b\[[0-9;]*[ABDHJKf]/g, "").replace(/\x1b\[\?[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
 async function hasPendingQuestion(jsonlPath) {
   let data;
   try {
@@ -1211,10 +1217,20 @@ async function hasPendingQuestion(jsonlPath) {
   return pendingIds.size > 0;
 }
 function parseNativePermissionPrompt(paneText) {
-  const questionMatch = paneText.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  const normalizedPane = normalizeCapturedPane(paneText);
+  const isTrustPrompt = normalizedPane.includes("Yes, I trust this folder") && normalizedPane.includes("No, exit");
+  const isBypassPrompt = normalizedPane.includes("Bypass Permissions mode") && normalizedPane.includes("Yes, I accept");
+  let questionMatch;
+  if (isTrustPrompt) {
+    questionMatch = normalizedPane.match(/(Is this a project you created[^\n]*)/);
+  } else if (isBypassPrompt) {
+    questionMatch = normalizedPane.match(/(you accept all responsibility[^\n]*)/);
+  } else {
+    questionMatch = normalizedPane.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  }
   if (!questionMatch)
     return null;
-  const afterQuestion = paneText.slice(paneText.indexOf(questionMatch[1]) + questionMatch[1].length);
+  const afterQuestion = normalizedPane.slice(normalizedPane.indexOf(questionMatch[1]) + questionMatch[1].length);
   const optionRegex = /(?:❯\s*)?(\d+)\.\s+(.+)/g;
   const options = [];
   let match;
@@ -1389,6 +1405,10 @@ var TERMINAL_BACKENDS = [
     description: "Run Claude Code in a headless xterm-backed PTY"
   }
 ];
+function isRejectingNativeOption(label) {
+  const normalized = label.trim().toLowerCase();
+  return normalized.startsWith("no") || normalized.startsWith("reject");
+}
 function makeDefaultLogger() {
   const noop = () => {};
   return {
@@ -1510,6 +1530,8 @@ class ClaudrabandSessionImpl {
   _permissionMode;
   allowTextResponses;
   sessionOwner;
+  lastNativePermissionFingerprint = null;
+  lastNativePermissionOutcome = "none";
   constructor(wrapper, sessionId, cwd, backend, model, permissionMode, allowTextResponses, logger, onPermissionRequest, lifetime, sessionOwner) {
     this.sessionId = sessionId;
     this.cwd = cwd;
@@ -1544,7 +1566,20 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter(text);
     this.activePrompt = prompt;
     this.logger.info("prompt received", "sid", this.sessionId, "length", text.length);
-    await this.wrapper.send(text);
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState !== "consumed") {
+      await this.wrapper.send(text);
+    }
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
       this.logger.info("prompt completed", "sid", this.sessionId, "stop_reason", stopReason);
@@ -1567,6 +1602,17 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(null);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
     this.logger.info("awaitTurn", "sid", this.sessionId);
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
@@ -1590,6 +1636,26 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState === "consumed") {
+      if (this.activePrompt === prompt) {
+        this.activePrompt = null;
+      }
+      if (this.promptAbortController === controller) {
+        this.promptAbortController = null;
+      }
+      return { stopReason: "end_turn" };
+    }
     this.logger.info("sendAndAwaitTurn", "sid", this.sessionId, "length", text.length);
     await this.wrapper.send(text);
     try {
@@ -1608,6 +1674,21 @@ class ClaudrabandSessionImpl {
   send(text) {
     return this.wrapper.send(text);
   }
+  async prepareForInput(intendedText) {
+    const handled = await this.pollNativePermission(null, intendedText);
+    if (handled === "handled" || handled === "consumed" || handled === "pending_clear") {
+      const ready = await this.waitForInsertMode();
+      if (!ready) {
+        return this.wrapper.isProcessAlive() ? "blocked" : "cancelled";
+      }
+      return handled === "consumed" ? "consumed" : "ready";
+    }
+    const stillBlocking = hasPendingNativePrompt(await this.wrapper.capturePane().catch(() => ""));
+    if (stillBlocking) {
+      return "blocked";
+    }
+    return "ready";
+  }
   async interrupt() {
     this.promptAbortController?.abort();
     await this.wrapper.interrupt();
@@ -1927,7 +2008,7 @@ class ClaudrabandSessionImpl {
         }
         if (prompt.pendingTools > 0) {
           const handled = await this.pollNativePermission(prompt.lastPendingTool);
-          if (handled) {
+          if (handled === "handled" || handled === "consumed") {
             prompt.pendingTools = Math.max(0, prompt.pendingTools - 1);
             prompt.gotResponse = true;
             prompt.lastPendingTool = null;
@@ -1942,16 +2023,28 @@ class ClaudrabandSessionImpl {
       }
     }
   }
-  async pollNativePermission(pendingTool) {
+  async pollNativePermission(pendingTool, intendedText = null) {
     let paneText;
     try {
       paneText = await this.wrapper.capturePane();
     } catch {
-      return false;
+      return "none";
     }
     const prompt = parseNativePermissionPrompt(paneText);
-    if (!prompt)
-      return false;
+    if (!prompt) {
+      this.lastNativePermissionFingerprint = null;
+      this.lastNativePermissionOutcome = "none";
+      return "none";
+    }
+    const fingerprint = `${prompt.question}
+${prompt.options.map((option) => `${option.number}:${option.label}`).join(`
+`)}`;
+    if (this.lastNativePermissionFingerprint === fingerprint) {
+      if (this.lastNativePermissionOutcome === "handled" || this.lastNativePermissionOutcome === "consumed") {
+        return "pending_clear";
+      }
+      return this.lastNativePermissionOutcome;
+    }
     const decision = await this.resolvePermission({
       source: "native_prompt",
       sessionId: this.sessionId,
@@ -1971,19 +2064,62 @@ class ClaudrabandSessionImpl {
         name: opt.label
       }))
     });
+    let outcome;
     if (decision.outcome === "deferred") {
-      return false;
+      outcome = "deferred";
+    } else if (decision.outcome === "cancelled") {
+      await this.safeInterruptNativePermission();
+      outcome = "handled";
+    } else if (decision.outcome === "text") {
+      await this.safeSendNativePermission(decision.text, false);
+      outcome = decision.text === intendedText ? "consumed" : "handled";
+    } else {
+      const selected = prompt.options.find((option) => option.number === decision.optionId);
+      const tolerateExit = selected ? isRejectingNativeOption(selected.label) : false;
+      await this.safeSendNativePermission(decision.optionId, tolerateExit);
+      outcome = decision.optionId === intendedText ? "consumed" : "handled";
+    }
+    this.lastNativePermissionFingerprint = fingerprint;
+    this.lastNativePermissionOutcome = outcome;
+    return outcome;
+  }
+  async safeSendNativePermission(input, tolerateExit) {
+    try {
+      await this.wrapper.send(input);
+    } catch (error) {
+      if (tolerateExit && !this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission send ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "cancelled") {
+  }
+  async safeInterruptNativePermission() {
+    try {
       await this.wrapper.interrupt();
-      return true;
+    } catch (error) {
+      if (!this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission interrupt ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "text") {
-      await this.wrapper.send(decision.text);
-      return true;
+  }
+  async waitForInsertMode(timeoutMs = 15000) {
+    const POLL_MS = 300;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (!this.wrapper.isProcessAlive()) {
+        return false;
+      }
+      try {
+        const pane = await this.wrapper.capturePane();
+        if (pane.includes("INSERT") || pane.includes("NORMAL"))
+          return true;
+      } catch {}
+      await new Promise((r) => setTimeout(r, POLL_MS));
     }
-    await this.wrapper.send(decision.optionId);
-    return true;
+    return false;
   }
   async handleUserQuestion(ev) {
     const parsed = parseAskUserQuestion(ev.toolInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halfwhey/claudraband-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript runtime for controlling local Claude Code sessions through a real terminal.",
   "type": "module",
   "main": "./dist/index.js",