@mentiko/pty-mgr 1.3.1 → 1.4.2

package/lib/pty-manager.mjs

@@ -1,30 +1,27 @@
 #!/usr/bin/env bun
 /**
- * pty-manager.mjs - PTY-based agent session manager
+ * pty-manager.mjs (v2) - PTY-based agent session manager
  *
  * Uses:
  *   - Bun.spawn        native PTY support (no python, no native addons)
  *   - @xterm/headless   terminal emulator (parses escape codes into screen)
  *
- * capture() returns the actual rendered screen state, not raw output.
+ * capture() returns the actual rendered screen state, not raw output:
  * spinners, progress bars, cursor movements, and TUI redraws are all
  * resolved into clean text.
  *
- * API:
- *   mgr.spawn(name, cmd)       create session
- *   mgr.sendKeys(name, text)   send keystrokes
- *   mgr.capture(name, lines)   capture rendered screen
- *   mgr.has(name)              check if session exists
- *   mgr.kill(name)             kill session
- *   mgr.list()                 list sessions
- *   mgr.pid(name)              get child process pid
+ * v2 refactor: deduplicated the socket client, terminal-size clamps,
+ * capture-stability check, `--log` wiring, telegram send, and transcript
+ * listing; hardened error handling on the socket read path, the attach
+ * input path, and the log write stream. Behavior and the public API are
+ * unchanged (see the test suite).
  *
- * Usage:
- *   import { PtyManager } from './pty-manager.mjs';
+ * Library API:
  *   const mgr = new PtyManager();
- *   mgr.spawn('agent-1', 'claude', ['--print']);
- *   mgr.sendKeys('agent-1', 'fix the bug\r');
- *   console.log(mgr.capture('agent-1', 40));
+ *   mgr.spawn('agent-1', 'claude', ['--print']);  // create session
+ *   mgr.sendKeys('agent-1', 'fix the bug\r');      // send keystrokes
+ *   mgr.capture('agent-1', 40);                    // rendered screen
+ *   mgr.has(name) / mgr.kill(name) / mgr.list() / mgr.pid(name)
  */
 
 import { EventEmitter } from "node:events";
@@ -38,10 +35,14 @@ import {
   readFileSync,
   readdirSync,
   statSync,
+  writeFileSync,
+  appendFileSync,
 } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { spawn as spawnChild } from "node:child_process";
 
 // kept in sync by scripts/version-sync.cjs (rewrites this literal on release)
-export const VERSION = "1.3.1";
+export const VERSION = "1.4.2";
 import xterm from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 
@@ -65,6 +66,15 @@ export function validateSessionName(name) {
   }
 }
 
+// terminal-size clamps: keep buffers sane, prevent memory exhaustion from a
+// hostile/typo'd size. shared by PtySession.resize and the daemon spawn/wrap.
+function clampCols(value, fallback) {
+  return Math.max(20, Math.min(500, value || fallback));
+}
+function clampRows(value, fallback) {
+  return Math.max(5, Math.min(200, value || fallback));
+}
+
 class PtySession {
   constructor(name, opts = {}) {
     this.name = name;
@@ -149,16 +159,9 @@ class PtySession {
   }
 
   /**
-   * capture the rendered screen buffer.
-   *
-   * returns what you'd actually see on the terminal right now.
-   * escape codes, cursor movements, line erases -- all resolved.
-   * equivalent of reading the full terminal screen buffer.
-   *
-   * @param {number} [tailLines] - last N lines (0 or omit = visible screen)
-   * @param {object} [opts] - options
-   * @param {boolean} [opts.screen] - only capture visible rows (skip scrollback)
-   * @returns {string}
+   * capture the rendered screen: what you'd see now, with escape codes, cursor
+   * moves and line-erases all resolved. tailLines>0 returns the last N lines;
+   * opts.screen limits to visible rows (skips scrollback).
    */
   capture(tailLines, opts = {}) {
     const buf = this.terminal.buffer.active;
@@ -184,21 +187,15 @@ class PtySession {
     return lines.join("\n");
   }
 
-  /**
-   * capture the rendered screen with ANSI color/attribute escape codes.
-   * uses @xterm/addon-serialize to preserve colors, bold, etc.
-   * @returns {string}
-   */
+  /** rendered screen with ANSI color/attribute codes (via addon-serialize). */
   captureAnsi() {
     return this._serializer.serialize();
   }
 
   /**
-   * capture visible content with ANSI colors, trimmed of empty lines.
-   * reads cells individually to build colored output line by line.
-   * result starts from line 0 (no leading empty rows).
-   * @param {number} [tailLines] - last N lines (0 = all content)
-   * @returns {string}
+   * visible content with ANSI colors, trimmed of leading/trailing empty lines.
+   * reads cells individually (line by line) so colors/attributes survive.
+   * tailLines>0 = last N lines.
    */
   captureAnsiCompact(tailLines) {
     const buf = this.terminal.buffer.active;
@@ -210,14 +207,17 @@ class PtySession {
       if (!line) { lines.push(""); continue; }
 
       let out = "";
+      let keep = 0; // output length up to the last cell worth keeping
       let prevFg = -1, prevBg = -1, prevBold = false, prevDim = false;
       let prevItalic = false, prevUnder = false, prevInverse = false;
 
       for (let x = 0; x < line.length; x++) {
         const cell = line.getCell(x);
         if (!cell) continue;
-        const ch = cell.getChars();
-        if (!ch) continue;
+        if (cell.getWidth() === 0) continue; // wide-char continuation cell
+        // null cells (never written; TUIs skip them with cursor moves)
+        // must still occupy a column, or text collapses together
+        const ch = cell.getChars() || " ";
 
         const fg = cell.getFgColor();
         const bg = cell.getBgColor();
@@ -258,8 +258,13 @@ class PtySession {
           prevItalic = italic; prevUnder = under; prevInverse = inverse;
         }
         out += ch;
+        if (ch !== " " || fgMode !== 0 || bgMode !== 0 ||
+            bold || dim || italic || under || inverse) {
+          keep = out.length;
+        }
       }
-      if (prevFg !== -1 || prevBold) out += "\x1b[0m";
+      out = out.slice(0, keep); // drop trailing unstyled blanks
+      if (keep > 0 && (prevFg !== -1 || prevBold)) out += "\x1b[0m";
       lines.push(out);
     }
 
@@ -278,14 +283,10 @@ class PtySession {
     return lines.join("\r\n");
   }
 
-  /**
-   * resize the PTY and headless terminal.
-   * @param {number} cols
-   * @param {number} rows
-   */
+  /** resize the PTY and headless terminal (clamped to sane bounds). */
   resize(cols, rows) {
-    cols = Math.max(20, Math.min(500, cols));
-    rows = Math.max(5, Math.min(200, rows));
+    cols = clampCols(cols, cols);
+    rows = clampRows(rows, rows);
     this.terminal.resize(cols, rows);
     if (this._pty && !this.exited) {
       try { this._pty.resize(cols, rows); } catch {}
@@ -324,15 +325,10 @@ class PtySession {
   }
 
   /**
-   * start logging session output to a file.
-   *
-   * format:
+   * start logging session output to a file. format:
    *   "raw"      - raw PTY bytes (escape codes included, replayable)
-   *   "rendered"  - clean screen snapshots on each data event
-   *   "jsonl"     - timestamped JSON lines { t, type, data }
-   *
-   * @param {string} logPath - file path to write to
-   * @param {string} [format="raw"] - log format
+   *   "rendered" - clean screen snapshots on each data event
+   *   "jsonl"    - timestamped JSON lines { t, type, data }
    */
   startLog(logPath, format = "raw") {
     if (this._logStream) this.stopLog();
@@ -343,6 +339,10 @@ class PtySession {
     this._logPath = logPath;
     this._logFormat = format;
     this._logStream = createWriteStream(logPath, { flags: "a" });
+    // a write error (disk full, perms, unlinked path) emits 'error'; without a
+    // listener node throws it as uncaught and takes the daemon down. drop
+    // logging on error rather than crash the session.
+    this._logStream.on("error", () => { try { this.stopLog(); } catch {} });
 
     // write header for jsonl
     if (format === "jsonl") {
@@ -459,18 +459,9 @@ export class PtyManager {
   }
 
   /**
-   * spawn a command inside a real PTY with terminal emulation
-   *
-   * @param {string} name - unique session name
-   * @param {string} cmd - command to run
-   * @param {string[]} [args] - arguments
-   * @param {object} [opts]
-   * @param {string} [opts.cwd] - working directory
-   * @param {object} [opts.env] - extra env vars
-   * @param {number} [opts.cols] - terminal columns (default 200)
-   * @param {number} [opts.rows] - terminal rows (default 50)
-   * @param {number} [opts.scrollback] - scrollback lines (default 5000)
-   * @returns {string} session name
+   * spawn a command inside a real PTY with terminal emulation. opts: cwd, env
+   * (extra vars), cols (default 100), rows (default 35), scrollback (5000).
+   * returns the session name.
    */
   spawn(name, cmd, args = [], opts = {}) {
     validateSessionName(name);
@@ -765,9 +756,11 @@ function startDaemon() {
       });
 
       conn.on("data", async (data) => {
-        // in attach mode, forward raw input to the pty
+        // in attach mode, forward raw input to the pty. the session can exit
+        // between attach and this write (write() throws once exited); swallow
+        // so a late keystroke can't crash the daemon's data handler.
         if (attached) {
-          attached.write(data.toString());
+          try { attached.write(data.toString()); } catch {}
           return;
         }
 
@@ -790,15 +783,18 @@ function startDaemon() {
               const session = mgr.get(req.name);
               const cols = session.terminal.cols;
               const rows = session.terminal.rows;
-              // send initial ack with terminal size
-              conn.write(JSON.stringify({ ok: true, mode: "attach", cols, rows }) + "\n");
-
-              // send current buffer as plain text, then SIGWINCH for colored redraw
-              conn.write("\x1b[2J\x1b[H");
-              const screen = session.capture(session.terminal.rows);
-              if (screen) conn.write(screen.replace(/\n/g, "\r\n") + "\r\n");
-
-              // force TUI apps to redraw on top
+              const alt = session.terminal.buffer.active.type === "alternate";
+              // send initial ack with terminal size + buffer state
+              conn.write(JSON.stringify({ ok: true, mode: "attach", cols, rows, alt }) + "\n");
+
+              // replay the session's full terminal state: scrollback, screen,
+              // colors, cursor, modes. history lands in the client's own
+              // scrollback so it stays scrollable. if the session is inside a
+              // TUI, the serializer emits the alt-screen switch itself and the
+              // client pops back out on detach.
+              conn.write("\x1b[2J\x1b[H" + session.captureAnsi());
+
+              // nudge the app to repaint so live output aligns with the replay
               if (session.childPid) {
                 try { process.kill(session.childPid, "SIGWINCH"); } catch {}
               }
@@ -812,7 +808,10 @@ function startDaemon() {
               // when session exits, notify and close
               const onExit = () => {
                 try {
-                  conn.write("\r\n[session exited]\r\n");
+                  if (session.terminal.buffer.active.type === "alternate") {
+                    conn.write("\x1b[?1049l");
+                  }
+                  conn.write("\x1b[0m\r\n[session exited]\r\n");
                   conn.end();
                 } catch {}
               };
@@ -861,15 +860,9 @@ function startDaemon() {
 
     async function tgSend(chatId, text) {
       const token = process.env.TELEGRAM_BOT_TOKEN;
-      // telegram max message length is 4096
-      const chunks = [];
-      for (let i = 0; i < text.length; i += 4000) chunks.push(text.slice(i, i + 4000));
-      for (const chunk of chunks) {
-        await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ chat_id: chatId, text: chunk }),
-        });
+      // telegram max message length is 4096; chunk under it
+      for (let i = 0; i < text.length; i += 4000) {
+        await telegramSend(token, chatId, text.slice(i, i + 4000));
       }
     }
 
@@ -1071,6 +1064,15 @@ export function buildSafeEnv(extra) {
   return safeEnv;
 }
 
+// start default jsonl logging for a session, under the session's own cwd (the
+// client's dir, not the daemon's frozen cwd). used by the `--log` shortcut on
+// spawn/wrap; the `log` command does its own format/dir handling. returns path.
+function startDefaultLog(mgr, name) {
+  const logPath = join(mgr.get(name).cwd, "agents", "logs", `${name}-${Date.now()}.jsonl`);
+  mgr.get(name).startLog(logPath, "jsonl");
+  return logPath;
+}
+
 // POSIX single-quote escaping: wrap in '...' and replace each ' with '\''.
 // Makes a token literal to the shell -- no expansion, no command substitution,
 // no word splitting. Used to build the `zsh -lic` command line for `wrap`.
@@ -1078,6 +1080,17 @@ export function shellQuote(arg) {
   return `'${String(arg).replace(/'/g, "'\\''")}'`;
 }
 
+// one place that talks to the Telegram Bot API. returns the fetch promise so
+// callers keep their existing error semantics (handleCommand's try/catch for
+// the tg-send/tg-wait commands; the poller's own catch for notifications).
+function telegramSend(token, chatId, text) {
+  return fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ chat_id: chatId, text }),
+  });
+}
+
 async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
   const { cmd, name, args } = req;
 
@@ -1093,6 +1106,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
           name: DAEMON_NAME,
           pid: process.pid,
           socket: SOCKET_PATH,
+          cwd: process.cwd(),
           startedAt: daemonStartedAt.toISOString(),
           uptimeMs,
           uptime: formatUptime(uptimeMs),
@@ -1135,8 +1149,8 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       const cmdToRun = args?.cmd || "zsh";
       const cmdArgs = args?.args || [];
       // clamp terminal size to prevent memory exhaustion
-      const cols = Math.max(20, Math.min(500, args?.cols || config.cols));
-      const rows = Math.max(5, Math.min(200, args?.rows || config.rows));
+      const cols = clampCols(args?.cols, config.cols);
+      const rows = clampRows(args?.rows, config.rows);
       const safeEnv = buildSafeEnv(args?.env);
       safeEnv.PTY_MGR_SESSION = name;
       const opts = {
@@ -1147,13 +1161,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       };
       mgr.spawn(name, cmdToRun, cmdArgs, opts);
       const res = { ok: true, name, pid: mgr.pid(name) };
-      // auto-start logging if --log flag
-      if (args?.log) {
-        const logDir = join(process.cwd(), "agents", "logs");
-        const logPath = join(logDir, `${name}-${Date.now()}.jsonl`);
-        mgr.get(name).startLog(logPath, "jsonl");
-        res.logPath = logPath;
-      }
+      if (args?.log) res.logPath = startDefaultLog(mgr, name);
       return res;
     }
     case "wrap": {
@@ -1176,8 +1184,8 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       if (maxNum === 0) maxNum = 1;
       const nextName = `${baseName}-${maxNum}`;
 
-      const cols = Math.max(20, Math.min(500, args?.cols || config.cols));
-      const rows = Math.max(5, Math.min(200, args?.rows || config.rows));
+      const cols = clampCols(args?.cols, config.cols);
+      const rows = clampRows(args?.rows, config.rows);
 
       // wrap spawns through user's login shell so shell functions/aliases work
       // (like tmux does). this means glm, nvm, conda, etc. all resolve.
@@ -1204,13 +1212,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
 
       mgr.spawn(nextName, shellCmd, shellArgs, { cwd: clientCwd, env: wrapEnv, cols, rows });
       const res = { ok: true, name: nextName, pid: mgr.pid(nextName) };
-
-      if (args?.log) {
-        const logDir = join(clientCwd, "agents", "logs");
-        const logPath = join(logDir, `${nextName}-${Date.now()}.jsonl`);
-        mgr.get(nextName).startLog(logPath, "jsonl");
-        res.logPath = logPath;
-      }
+      if (args?.log) res.logPath = startDefaultLog(mgr, nextName);
       return res;
     }
     case "send": {
@@ -1301,10 +1303,11 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
         const path = session.stopLog();
         return { ok: true, stopped: true, path };
       }
-      // default log dir: ./agents/logs/
+      // default log dir: <session cwd>/agents/logs/ -- follow the session's
+      // own dir, not the daemon's frozen cwd.
       const format = args?.format || "jsonl";
       const ext = format === "jsonl" ? "jsonl" : format === "rendered" ? "log" : "raw";
-      const logDir = args?.dir || join(process.cwd(), "agents", "logs");
+      const logDir = args?.dir || join(session.cwd, "agents", "logs");
       const ts = Date.now();
       const logPath = args?.path || join(logDir, `${name}-${ts}.${ext}`);
       session.startLog(logPath, format);
@@ -1326,11 +1329,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       const msg = req.args?.message;
       if (!msg) return { ok: false, error: "message required" };
       if (req.args?.session) tgState.lastSession = req.args.session;
-      await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ chat_id: chatId, text: msg }),
-      });
+      await telegramSend(token, chatId, msg);
       return { ok: true };
     }
     case "tg-wait": {
@@ -1340,11 +1339,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       if (tgState.waiter) return { ok: false, error: "ALREADY_WAITING" };
       const msg = req.args?.message;
       const timeoutMs = req.args?.timeout ?? 60000;
-      await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ chat_id: chatId, text: msg }),
-      });
+      await telegramSend(token, chatId, msg);
       const sessionName = req.args?.session;
       return new Promise((resolve) => {
         const timer = setTimeout(() => {
@@ -1369,58 +1364,55 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
 }
 
 /**
- * client: send a single command to the daemon, print result.
+ * client: send one newline-framed JSON command to a daemon socket and resolve
+ * with the parsed JSON reply. Rejects with a friendly message when the daemon
+ * is absent, and — unlike a bare JSON.parse in the data handler — turns a
+ * malformed or truncated reply into a rejection instead of an uncaught throw.
  */
-function sendCommandTo(sock, req) {
+function requestSocket(sock, req, notRunningMsg) {
   return new Promise((resolve, reject) => {
     const conn = createConnection(sock);
+    let buf = "";
+    let settled = false;
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      try { conn.end(); } catch {}
+      fn(value);
+    };
+    const parseAndSettle = (chunk) => {
+      try { settle(resolve, JSON.parse(chunk)); }
+      catch (err) { settle(reject, new Error(`bad response from daemon: ${err.message}`)); }
+    };
     conn.on("error", (err) => {
-      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
-        reject(new Error("daemon not running"));
-      } else {
-        reject(err);
-      }
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") settle(reject, new Error(notRunningMsg));
+      else settle(reject, err);
     });
     conn.on("connect", () => {
-      conn.write(JSON.stringify(req) + "\n");
+      try { conn.write(JSON.stringify(req) + "\n"); }
+      catch (err) { settle(reject, err); }
     });
-    let buf = "";
     conn.on("data", (data) => {
       buf += data.toString();
       const nl = buf.indexOf("\n");
-      if (nl !== -1) {
-        const res = JSON.parse(buf.slice(0, nl));
-        conn.end();
-        resolve(res);
-      }
+      if (nl !== -1) parseAndSettle(buf.slice(0, nl));
+    });
+    conn.on("end", () => {
+      if (settled) return;
+      if (buf) parseAndSettle(buf); // reply without a trailing newline
+      else settle(reject, new Error(notRunningMsg));
     });
   });
 }
 
+// send to a specific socket file (used by `stop all` sweeping ~/.pty-manager).
+function sendCommandTo(sock, req) {
+  return requestSocket(sock, req, "daemon not running");
+}
+
+// send to the daemon selected by @name / --daemon / $PTY_DAEMON.
 function sendCommand(req) {
-  return new Promise((resolve, reject) => {
-    const conn = createConnection(SOCKET_PATH);
-    conn.on("error", (err) => {
-      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
-        reject(new Error("daemon not running. start with: pty-mgr daemon"));
-      } else {
-        reject(err);
-      }
-    });
-    conn.on("connect", () => {
-      conn.write(JSON.stringify(req) + "\n");
-    });
-    let buf = "";
-    conn.on("data", (data) => {
-      buf += data.toString();
-      const nl = buf.indexOf("\n");
-      if (nl !== -1) {
-        const res = JSON.parse(buf.slice(0, nl));
-        conn.end();
-        resolve(res);
-      }
-    });
-  });
+  return requestSocket(SOCKET_PATH, req, "daemon not running. start with: pty-mgr daemon");
 }
 
 /**
@@ -1431,8 +1423,12 @@ function sendCommand(req) {
 function attachToSession(name) {
   return new Promise((resolve, reject) => {
     const conn = createConnection(SOCKET_PATH);
+    // set on any pre-attach failure so the close handler doesn't run the
+    // detach cleanup (stray "detached" + terminal resets after an error)
+    let failed = false;
 
     conn.on("error", (err) => {
+      failed = true;
       if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
         reject(new Error("daemon not running. start with: pty-mgr daemon"));
       } else {
@@ -1447,6 +1443,15 @@ function attachToSession(name) {
       let gotAck = false;
       let headerBuf = "";
 
+      // last-seen alt-screen state: detach pops the client back to its
+      // normal screen only if the session left it in the alternate buffer
+      let altActive = false;
+      const trackAlt = (chunk) => {
+        const h = chunk.lastIndexOf("\x1b[?1049h");
+        const l = chunk.lastIndexOf("\x1b[?1049l");
+        if (h !== -1 || l !== -1) altActive = h > l;
+      };
+
       conn.on("data", (data) => {
         if (!gotAck) {
           // first line is the JSON ack
@@ -1461,19 +1466,20 @@ function attachToSession(name) {
           try {
             ack = JSON.parse(ackStr);
             if (!ack.ok) {
-              console.error("error:", ack.error);
+              failed = true;
               conn.end();
               reject(new Error(ack.error));
               return;
             }
           } catch {
-            console.error("bad ack from daemon");
+            failed = true;
             conn.end();
-            reject(new Error("bad ack"));
+            reject(new Error("bad ack from daemon"));
             return;
           }
 
           gotAck = true;
+          altActive = !!ack.alt;
 
           // resize client terminal to match session
           if (ack.cols && ack.rows) {
@@ -1489,6 +1495,7 @@ function attachToSession(name) {
 
           // write any remaining data after the ack
           if (remainder) {
+            trackAlt(remainder);
             process.stdout.write(remainder);
           }
 
@@ -1506,6 +1513,7 @@ function attachToSession(name) {
         }
 
         // streaming mode: write pty output to terminal
+        trackAlt(data);
         process.stdout.write(data);
       });
 
@@ -1515,15 +1523,22 @@ function attachToSession(name) {
 
       let detached = false;
       function detach() {
-        if (detached) return;
+        if (detached || failed) return;
         detached = true;
         if (process.stdin.isRaw) {
           process.stdin.setRawMode(false);
           process.stdin.pause();
           process.stdin.removeAllListeners("data");
         }
+        // pop the alt screen only if the session left us in one, then
+        // reset SGR/cursor and any modes the replayed TUI enabled
+        // (keypad, cursor keys, bracketed paste, mouse tracking)
+        if (altActive) process.stdout.write("\x1b[?1049l");
+        process.stdout.write(
+          "\x1b[0m\x1b[?25h\x1b>\x1b[?1l\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1004l\x1b[?9l"
+        );
         conn.end();
-        console.log("\r\ndetached");
+        console.log("detached");
         resolve();
       }
     });
@@ -1569,6 +1584,8 @@ usage:
   p flow list [--verbose] [--config file] list configured agent workflows
   p flow show <name> [--config file]   show one configured agent workflow
   p flow run <name> --task <text>     run a configured agent workflow
+  p flow new [name] [--global]        scaffold an example flow (project cwd, or --global user config)
+  p open config [editor]              open config dir in editor (--local project, --defaults packaged)
   p demo                             run self-test (no daemon needed)
   p tg <message>                     send telegram notification
   p tg <message> --reply             send message and wait for reply (blocking)
@@ -1949,6 +1966,20 @@ function capturePayloadText(res) {
   return res.output || "";
 }
 
+// capture a session (or glob/all) twice, intervalMs apart, and report whether
+// the rendered bottom-100 lines are stable ("done") or still changing
+// ("working"). shared by `p watch` and the flow engine's turn-completion check.
+async function captureStability(name, intervalMs) {
+  const capture = () => sendCommand({ cmd: "capture", name, args: { lines: 100 } });
+  const first = await capture();
+  if (!first.ok) throw new Error(first.error || `failed to capture ${name}`);
+  const firstHash = hashText(capturePayloadText(first));
+  await sleep(intervalMs);
+  const second = await capture();
+  if (!second.ok) throw new Error(second.error || `failed to capture ${name}`);
+  return firstHash === hashText(capturePayloadText(second)) ? "done" : "working";
+}
+
 function expandHome(value) {
   if (!value) return value;
   if (value === "~") return homedir();
@@ -1967,6 +1998,104 @@ export function loadFlowConfig(configPath = "pty-mgr.config.json") {
   return { adapters: {}, flows: {} };
 }
 
+function xdgConfigHome() {
+  return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+export function userConfigPath() {
+  return process.env.PTY_MGR_CONFIG || join(xdgConfigHome(), "pty-mgr", "config.json");
+}
+
+function packagedDefaultsConfigPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "pty-mgr.config.json");
+}
+
+export function findProjectConfigPath(cwd = process.cwd()) {
+  let dir = cwd;
+  const home = homedir();
+  while (true) {
+    const candidate = join(dir, "pty-mgr.config.json");
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, ".git")) || dir === home) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// merge flow configs low->high precedence; higher layers override by top-level key.
+// returns { adapters, flows, scopes } where scopes maps flow name -> layer it came from.
+export function resolveMergedConfig({ cwd = process.cwd(), explicitPath = null } = {}) {
+  if (explicitPath) {
+    const config = loadFlowConfig(explicitPath);
+    const scopes = {};
+    for (const name of Object.keys(config.flows || {})) scopes[name] = "config";
+    return { adapters: config.adapters || {}, flows: config.flows || {}, scopes };
+  }
+  const layers = [];
+  const defaultsPath = packagedDefaultsConfigPath();
+  if (existsSync(defaultsPath)) layers.push(["default", loadFlowConfig(defaultsPath)]);
+  const userPath = userConfigPath();
+  if (existsSync(userPath)) layers.push(["user", loadFlowConfig(userPath)]);
+  const projectPath = findProjectConfigPath(cwd);
+  if (projectPath && projectPath !== defaultsPath) layers.push(["project", loadFlowConfig(projectPath)]);
+
+  const adapters = {};
+  const flows = {};
+  const scopes = {};
+  for (const [scope, config] of layers) {
+    Object.assign(adapters, config.adapters || {});
+    for (const [name, flow] of Object.entries(config.flows || {})) {
+      flows[name] = flow;
+      scopes[name] = scope;
+    }
+  }
+  return { adapters, flows, scopes };
+}
+
+function exampleFlow() {
+  return {
+    agents: {
+      writer: { kind: "codex", base: "flow-writer" },
+      reviewer: { kind: "claude", base: "flow-reviewer" },
+    },
+    start: { to: "writer", template: "{task}" },
+    turns: [
+      {
+        from: "writer",
+        to: "reviewer",
+        append:
+          "Review what the other agent just did in this repository. Give specific, actionable feedback as a short numbered list, each item referencing file:line.",
+      },
+      {
+        from: "reviewer",
+        to: "writer",
+        append:
+          "Apply the feedback you agree with, note anything you skip and why, then report the final state. Original task: {goal}",
+      },
+    ],
+    maxCycles: 1,
+    watchInterval: "10s",
+    settleMs: 1500,
+  };
+}
+
+function scaffoldFlowConfig(targetPath, name) {
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const config = existsSync(targetPath) ? loadFlowConfig(targetPath) : { flows: {} };
+  if (!config.flows) config.flows = {};
+  if (config.flows[name]) {
+    console.error(`flow already exists: ${name} (${targetPath})`);
+    process.exit(1);
+  }
+  config.flows[name] = exampleFlow();
+  writeFileSync(targetPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(`created flow "${name}" in ${targetPath}`);
+  console.log(`  edit: p open config${targetPath === userConfigPath() ? "" : " --local"}`);
+  console.log(`  run:  p flow run ${name} --task "..."`);
+}
+
 function walkJsonlFiles(root, files = []) {
   root = expandHome(root);
   if (!root || !existsSync(root)) return files;
@@ -2048,11 +2177,14 @@ export function transcriptRootsForKind(kind, config, cwd = process.cwd()) {
     .filter((root, index, roots) => existsSync(root) || index === roots.length - 1);
 }
 
+// flatten every .jsonl transcript under a kind's configured roots.
+function transcriptFiles(kind, config, cwd = process.cwd()) {
+  return transcriptRootsForKind(kind, config, cwd).flatMap((root) => walkJsonlFiles(root));
+}
+
 export function findNewestTranscript({ kind, cwd = process.cwd(), sinceMs = 0, config }) {
   const adapter = adapterForKind(kind, config);
-  const roots = transcriptRootsForKind(kind, config, cwd);
-  const candidates = roots
-    .flatMap((root) => walkJsonlFiles(root))
+  const candidates = transcriptFiles(kind, config, cwd)
     .map((path) => {
       const mtimeMs = statSync(path).mtimeMs;
       const startedMs = transcriptStartedAtMs(path, adapter);
@@ -2195,8 +2327,7 @@ export function findTranscriptForSentMessage({
 }) {
   if (file) return findSentMessageInTranscript(file, kind, text, config);
 
-  const candidates = transcriptRootsForKind(kind, config, cwd)
-    .flatMap((root) => walkJsonlFiles(root))
+  const candidates = transcriptFiles(kind, config, cwd)
     .map((path) => ({ path, mtimeMs: statSync(path).mtimeMs }))
     .sort((a, b) => b.mtimeMs - a.mtimeMs);
 
@@ -2346,14 +2477,7 @@ async function sendFlowMessageConfirmed(meta, text, config, deps = {}) {
 
 async function watchFlowSession(session, intervalMs, deps = {}) {
   if (deps.watchSession) return deps.watchSession(session, intervalMs);
-  const first = await sendCommand({ cmd: "capture", name: session, args: { lines: 100 } });
-  if (!first.ok) throw new Error(first.error || `failed to capture ${session}`);
-  const firstHash = hashText(capturePayloadText(first));
-  await sleep(intervalMs);
-  const second = await sendCommand({ cmd: "capture", name: session, args: { lines: 100 } });
-  if (!second.ok) throw new Error(second.error || `failed to capture ${session}`);
-  const secondHash = hashText(capturePayloadText(second));
-  return firstHash === secondHash ? "done" : "working";
+  return captureStability(session, intervalMs);
 }
 
 async function waitForFlowMessage({
@@ -2531,8 +2655,6 @@ function detectRcFile() {
 }
 
 async function runSetup() {
-  const { appendFileSync, readFileSync, writeFileSync } = await import("node:fs");
-
   console.log("pty-mgr setup");
   console.log("wrap CLI tools in managed PTY sessions.\n");
   console.log("when you type a wrapped command (e.g. claude), pty-mgr will:");
@@ -2650,20 +2772,55 @@ async function cli() {
     return;
   }
 
+  if (command === "open") {
+    const sub = args[0];
+    if (sub !== "config") {
+      console.error("usage: p open config [editor] [--local|--defaults]");
+      process.exit(1);
+    }
+    const { flags: openFlags, rest: openRest } = parseFlagArgs(args, 1);
+    const editor = openRest[0] || process.env.VISUAL || process.env.EDITOR || "code";
+    let dir;
+    if (openFlags.defaults) {
+      dir = dirname(packagedDefaultsConfigPath());
+    } else if (openFlags.local) {
+      const projectPath = findProjectConfigPath(process.cwd());
+      dir = projectPath ? dirname(projectPath) : process.cwd();
+    } else {
+      dir = dirname(userConfigPath());
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    }
+    console.log(`opening ${dir} with ${editor}`);
+    await new Promise((resolve) => {
+      const child = spawnChild(editor, [dir], { stdio: "inherit" });
+      child.on("error", (err) => {
+        console.error(`could not launch ${editor}: ${err.message}`);
+        resolve();
+      });
+      child.on("exit", () => resolve());
+    });
+    return;
+  }
+
   if (command === "flow") {
     const subcommand = args[0];
-    const { flags } = parseFlagArgs(args, 1);
-    const configPath = flags.config || "pty-mgr.config.json";
+    const { flags, rest } = parseFlagArgs(args, 1);
+    if (subcommand === "new") {
+      const name = rest[0] || "example";
+      const target = flags.global ? userConfigPath() : join(process.cwd(), "pty-mgr.config.json");
+      scaffoldFlowConfig(target, name);
+      return;
+    }
     if (subcommand === "list") {
-      const config = loadFlowConfig(configPath);
-      const names = Object.keys(config.flows || {});
+      const { flows, scopes } = resolveMergedConfig({ cwd: process.cwd(), explicitPath: flags.config });
+      const names = Object.keys(flows);
       if (names.length === 0) {
         console.log("no flows configured");
       } else {
         for (const name of names) {
-          console.log(name);
+          console.log(flags.config ? name : `${name} [${scopes[name]}]`);
           if (flags.verbose) {
-            const flow = config.flows[name] || {};
+            const flow = flows[name] || {};
             for (const [alias, agent] of Object.entries(flow.agents || {})) {
               console.log(`  ${alias} -> ${flowAgentKind(agent)}`);
             }
@@ -2680,8 +2837,8 @@ async function cli() {
         console.error("usage: pty-mgr flow show <name>");
         process.exit(1);
       }
-      const config = loadFlowConfig(configPath);
-      const flow = config.flows?.[name];
+      const { flows } = resolveMergedConfig({ cwd: process.cwd(), explicitPath: flags.config });
+      const flow = flows[name];
       if (!flow) {
         console.error(`flow not found: ${name}`);
         process.exit(1);
@@ -2716,19 +2873,20 @@ async function cli() {
         console.error("flow run requires --task <text>");
         process.exit(1);
       }
+      const runCwd = runFlags.cwd || process.cwd();
+      const merged = resolveMergedConfig({ cwd: runCwd, explicitPath: runFlags.config || flags.config });
       try {
         const result = await runFlowWorkflow({
           workflow,
           task,
           goal: runFlags.goal,
-          config: runFlags.config || configPath,
-          cwd: runFlags.cwd || process.cwd(),
+          cwd: runCwd,
           maxCycles: runFlags["max-cycles"],
           watchInterval: runFlags["watch-interval"],
           settleMs: runFlags["settle-ms"],
           timeoutMs: runFlags["timeout-ms"],
           intervalMs: runFlags["interval-ms"],
-        });
+        }, { config: merged });
         console.log(JSON.stringify(result, null, 2));
       } catch (err) {
         console.error(err.message);
@@ -2773,12 +2931,11 @@ async function cli() {
   if (command === "daemon") {
     // fork into background as a true daemon (survives terminal close)
     if (!process.env.__PTY_DAEMON_CHILD) {
-      const { spawn: cpSpawn } = await import("node:child_process");
       // re-exec ourselves with the same args
       // process.execPath = bun (dev) or the compiled binary
       // filter out internal /$bunfs/ paths from argv
       const realArgs = process.argv.slice(1).filter(a => !a.startsWith("/$bunfs/"));
-      const child = cpSpawn(process.execPath, realArgs, {
+      const child = spawnChild(process.execPath, realArgs, {
         detached: true,
         stdio: ["ignore", "ignore", "ignore", "ipc"],
         env: { ...process.env, __PTY_DAEMON_CHILD: "1" },
@@ -2812,7 +2969,6 @@ async function cli() {
     const target = args[0]; // "all" or undefined (= current daemon)
     if (target === "all") {
       // find all pty-manager sockets and shut them down
-      const { readdirSync } = await import("node:fs");
       const dir = join(homedir(), ".pty-manager");
       let socks = [];
       try {
@@ -2900,20 +3056,7 @@ async function cli() {
     }
 
     try {
-      const first = await sendCommand({ cmd: "capture", name, args: { lines: 100 } });
-      if (!first.ok) {
-        console.error("error:", first.error);
-        process.exit(1);
-      }
-      const firstHash = hashText(capturePayloadText(first));
-      await sleep(intervalMs);
-      const second = await sendCommand({ cmd: "capture", name, args: { lines: 100 } });
-      if (!second.ok) {
-        console.error("error:", second.error);
-        process.exit(1);
-      }
-      const secondHash = hashText(capturePayloadText(second));
-      console.log(firstHash === secondHash ? "done" : "working");
+      console.log(await captureStability(name, intervalMs));
       process.exit(0);
     } catch (err) {
       console.error(err.message);
@@ -3031,6 +3174,7 @@ async function cli() {
       console.log(`pty-manager daemon (${st.name})`);
       console.log(`  pid:      ${st.pid}`);
       console.log(`  socket:   ${st.socket}`);
+      console.log(`  cwd:      ${st.cwd}`);
       console.log(`  uptime:   ${st.uptime}`);
       console.log(`  sessions: ${st.sessions.alive} alive, ${st.sessions.dead} dead, ${st.sessions.total} total`);
       console.log(`  screen:   ${st.config.cols}x${st.config.rows}`);
@@ -3119,7 +3263,10 @@ const isMain = _isBunCompiled || (_basename1 && _pat.test(_basename1)) || (_base
 
 if (isMain) {
   cli().catch((err) => {
-    console.error(err);
+    // message only -- a raw error object prints a stack trace for what are
+    // usually plain user-facing failures (session not found, daemon down)
+    console.error("error:", err.message);
+    if (process.env.PTY_MGR_DEBUG) console.error(err.stack);
     process.exit(1);
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentiko/pty-mgr",
-  "version": "1.3.1",
+  "version": "1.4.2",
   "description": "PTY session manager with terminal emulation for programmatic session control.",
   "type": "module",
   "main": "lib/pty-manager.mjs",
@@ -26,10 +26,10 @@
     "@xterm/headless": "^6.0.0"
   },
   "optionalDependencies": {
-    "@mentiko/pty-mgr-linux-x64": "1.3.1",
-    "@mentiko/pty-mgr-linux-arm64": "1.3.1",
-    "@mentiko/pty-mgr-darwin-x64": "1.3.1",
-    "@mentiko/pty-mgr-darwin-arm64": "1.3.1"
+    "@mentiko/pty-mgr-linux-x64": "1.4.2",
+    "@mentiko/pty-mgr-linux-arm64": "1.4.2",
+    "@mentiko/pty-mgr-darwin-x64": "1.4.2",
+    "@mentiko/pty-mgr-darwin-arm64": "1.4.2"
   },
   "engines": {
     "bun": ">=1.0"