@mentiko/pty-mgr 1.2.3 → 1.3.0

package/lib/pty-manager.mjs

@@ -28,11 +28,20 @@
  */
 
 import { EventEmitter } from "node:events";
+import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
-import { createWriteStream, mkdirSync, existsSync, readSync } from "node:fs";
-
-// replaced by --define at build time
-export const VERSION = "1.2.3";
+import {
+  createWriteStream,
+  mkdirSync,
+  existsSync,
+  readSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+
+// kept in sync by scripts/version-sync.cjs (rewrites this literal on release)
+export const VERSION = "1.3.0";
 import xterm from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 
@@ -528,8 +537,8 @@ export class PtyManager {
   }
 
   /** kill session process (session stays in registry for inspection) */
-  kill(name) {
-    this.get(name).kill();
+  kill(name, signal = "SIGTERM") {
+    this.get(name).kill(signal);
   }
 
   /** rename a session */
@@ -575,30 +584,51 @@ export class PtyManager {
     const re = typeof pattern === "string" ? new RegExp(pattern) : pattern;
 
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
+      let settled = false;
+      function cleanup() {
+        clearTimeout(timeout);
+        clearInterval(poll);
         session.events.off("data", onData);
-        reject(new Error(`timeout waiting for: ${pattern}`));
+      }
+
+      function settle(fn, value) {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        fn(value);
+      }
+
+      function checkCapture() {
+        for (const line of session.capture().split("\n")) {
+          if (re.test(line)) return line;
+        }
+        return null;
+      }
+
+      const timeout = setTimeout(() => {
+        settle(reject, new Error(`timeout waiting for: ${pattern}`));
       }, timeoutMs);
+      const poll = setInterval(() => {
+        const line = checkCapture();
+        if (line) settle(resolve, line);
+      }, 50);
 
       // check current screen
-      for (const line of session.capture().split("\n")) {
-        if (re.test(line)) {
-          clearTimeout(timeout);
-          resolve(line);
-          return;
-        }
+      const current = checkCapture();
+      if (current) {
+        settle(resolve, current);
+        return;
       }
 
       // poll on new data (re-read screen each time)
-      function onData() {
-        for (const line of session.capture().split("\n")) {
-          if (re.test(line)) {
-            clearTimeout(timeout);
-            session.events.off("data", onData);
-            resolve(line);
-            return;
-          }
+      function onData(chunk = "") {
+        if (re.test(chunk)) {
+          settle(resolve, chunk);
+          return;
         }
+
+        const line = checkCapture();
+        if (line) settle(resolve, line);
       }
       session.events.on("data", onData);
     });
@@ -639,13 +669,34 @@ import { createServer, createConnection } from "node:net";
 import { unlinkSync, chmodSync } from "node:fs";
 import { tmpdir, homedir } from "node:os";
 
-// daemon name from @name, --daemon flag, or PTY_DAEMON env var
-function getDaemonName() {
-  const at = process.argv.find((a) => a.startsWith("@"));
-  if (at) return at.slice(1);
-  const idx = process.argv.indexOf("--daemon");
-  if (idx !== -1 && process.argv[idx + 1]) return process.argv[idx + 1];
-  return process.env.PTY_DAEMON || "default";
+// Split the daemon selector off the front of the CLI tokens.
+//
+// The selector is `@name` or `--daemon <name>`. It is only recognized as a
+// LEADING token, or as the argument that immediately follows a leading
+// `daemon`/`d` command (the documented `p daemon @myproject` form). It is NOT
+// recognized anywhere else, so later `@...` tokens are preserved as data --
+// e.g. `p send agent "@everyone deploy now"` keeps the message intact.
+export function splitDaemonArgs(tokens = []) {
+  // pull a selector off the front of an array: returns [name|null, rest]
+  const takeSelector = (arr) => {
+    if (arr[0] && arr[0].startsWith("@")) return [arr[0].slice(1), arr.slice(1)];
+    if (arr[0] === "--daemon" && arr[1]) return [arr[1], arr.slice(2)];
+    return [null, arr];
+  };
+
+  let daemon = process.env.PTY_DAEMON || "default";
+  let [sel, rest] = takeSelector(tokens);
+  if (sel !== null) {
+    daemon = sel;
+  } else if (rest[0] === "daemon" || rest[0] === "d") {
+    // `daemon @name` / `daemon --daemon name`: selector trails the command
+    const [sel2, after] = takeSelector(rest.slice(1));
+    if (sel2 !== null) {
+      daemon = sel2;
+      rest = [rest[0], ...after];
+    }
+  }
+  return { daemon, args: rest };
 }
 
 function socketPath(name) {
@@ -655,7 +706,7 @@ function socketPath(name) {
   return join(dir, `${name}.sock`);
 }
 
-const DAEMON_NAME = getDaemonName();
+const { daemon: DAEMON_NAME, args: CLI_ARGS } = splitDaemonArgs(process.argv.slice(2));
 const SOCKET_PATH = socketPath(DAEMON_NAME);
 
 /**
@@ -1020,6 +1071,13 @@ export function buildSafeEnv(extra) {
   return safeEnv;
 }
 
+// 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`.
+export function shellQuote(arg) {
+  return `'${String(arg).replace(/'/g, "'\\''")}'`;
+}
+
 async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
   const { cmd, name, args } = req;
 
@@ -1130,14 +1188,19 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
         shellCmd = userShell;
         shellArgs = ["-l"];
       } else {
-        // wrap <cmd> [args]: run through login interactive shell
-        const escaped = [cmdToRun, ...cmdArgs].map(a => a.includes(" ") ? `"${a}"` : a).join(" ");
+        // wrap <cmd> [args]: run through login interactive shell.
+        // single-quote every token so shell metacharacters in args
+        // (;, |, &, $(), backticks, globs, spaces) are passed literally.
+        const escaped = [cmdToRun, ...cmdArgs].map(shellQuote).join(" ");
         shellCmd = userShell;
         shellArgs = ["-lic", escaped];
       }
 
-      // pass full env for wrap (user expects their shell env, not a sandbox)
-      const wrapEnv = { ...process.env, ...(args?.env || {}) };
+      // wrap inherits the daemon's real shell env (user expects their env, not
+      // a sandbox), but any client-supplied env overlay is filtered to the
+      // whitelist so a socket client can't inject arbitrary vars (LD_PRELOAD,
+      // DYLD_INSERT_LIBRARIES, ...) into the login shell.
+      const wrapEnv = { ...process.env, ...buildSafeEnv(args?.env) };
 
       mgr.spawn(nextName, shellCmd, shellArgs, { cwd: clientCwd, env: wrapEnv, cols, rows });
       const res = { ok: true, name: nextName, pid: mgr.pid(nextName) };
@@ -1482,11 +1545,13 @@ usage:
   p spawn <name> [cmd] [args...]     create session
   p wrap [cmd] [args...]             spawn with auto-incrementing cwd name
   p attach <name>                    interactive mode (ctrl-] detach)
+  p view <name1> <name2> [interval]  read-only split-pane live viewer
   p send <name> <text>               send text + enter
   p send <name> --raw <text>         send text as-is (no enter)
   p capture <name> [lines]           capture screen output
   p capture all [lines]              capture from all sessions
   p capture <glob*> [lines]          capture matching sessions
+  p watch <name> [interval]          compare two bottom-100 captures
   p list                             list all sessions
   p alive <name>                     check if alive
   p info <name>                      session details
@@ -1501,6 +1566,9 @@ usage:
   p stop                             stop current daemon
   p stop all                         stop all daemons
   p setup                            wrap CLI tools (claude, etc.)
+  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 demo                             run self-test (no daemon needed)
   p tg <message>                     send telegram notification
   p tg <message> --reply             send message and wait for reply (blocking)
@@ -1508,7 +1576,7 @@ usage:
 
 shortcuts:
   n|new = spawn    w|wrap = wrap  s = send       c|cap = capture
-  st = status      a = attach     k = kill
+  st = status      a = attach     v = view       k = kill
   l|ls = list      i = info       r|rm = remove
   mv|ren = rename
   d = daemon       cfg = config   x = stop
@@ -1543,18 +1611,64 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+function clipPad(value, width) {
+  const text = String(value || "").replace(/\r/g, "");
+  return text.slice(0, width).padEnd(width, " ");
+}
+
+export function composeSideBySideCaptureRows({
+  leftName,
+  rightName,
+  leftCapture = "",
+  rightCapture = "",
+  leftWidth,
+  rightWidth,
+  height,
+}) {
+  const rows = [];
+  const visibleHeight = Math.max(0, height || 0);
+  const leftLines = String(leftCapture || "").replace(/\r/g, "").split("\n");
+  const rightLines = String(rightCapture || "").replace(/\r/g, "").split("\n");
+
+  if (visibleHeight === 0) return rows;
+
+  rows.push(`${clipPad(leftName, leftWidth)}│${clipPad(rightName, rightWidth)}`);
+
+  for (let i = 1; i < visibleHeight; i++) {
+    rows.push(
+      `${clipPad(leftLines[i - 1] || "", leftWidth)}│${clipPad(rightLines[i - 1] || "", rightWidth)}`
+    );
+  }
+
+  return rows;
+}
+
 async function runDemo() {
   const mgr = new PtyManager();
 
   console.log("--- pty-manager demo (xterm-headless) ---\n");
 
-  console.log("1. spawn 'test-shell' (zsh in pty + xterm emulation)");
-  mgr.spawn("test-shell", "zsh", [], { cols: 120, rows: 30 });
-  await sleep(1000);
+  const demoShell = `
+print -r -- DEMO_READY
+while IFS= read -r line; do
+  print -r -- "> $line"
+  if [ "$line" = exit ]; then
+    exit 0
+  fi
+  eval "$line"
+done
+`;
+
+  console.log("1. spawn 'test-shell' (scripted zsh pty + xterm emulation)");
+  mgr.spawn("test-shell", "zsh", ["-f", "-c", demoShell], {
+    cols: 120,
+    rows: 30,
+  });
+  await mgr.waitFor("test-shell", /DEMO_READY/, 5000);
 
   console.log("2. sendKeys: echo hello-from-pty");
-  mgr.sendKeys("test-shell", "echo hello-from-pty\n");
-  await sleep(600);
+  mgr.sendKeys("test-shell", "echo hello-from-pty\r");
+  await mgr.waitFor("test-shell", /^hello-from-pty$/, 5000);
 
   console.log("3. capture (last 5 lines):");
   console.log("  ---");
@@ -1564,8 +1678,8 @@ async function runDemo() {
   console.log("  ---\n");
 
   console.log("4. sendKeys: ls | head -3");
-  mgr.sendKeys("test-shell", "ls | head -3\n");
-  await sleep(800);
+  mgr.sendKeys("test-shell", "ls | head -3\r");
+  await mgr.waitFor("test-shell", /^CHANGELOG.md$|^LICENSE$/, 5000);
 
   console.log("5. capture (last 8 lines):");
   console.log("  ---");
@@ -1585,28 +1699,45 @@ async function runDemo() {
   }
 
   console.log("\n8. waitFor: echo MARKER_42");
-  mgr.sendKeys("test-shell", "echo MARKER_42\n");
-  const match = await mgr.waitFor("test-shell", /MARKER_42/, 5000);
+  mgr.spawn("marker-shell", "zsh", ["-fc", "sleep 0.2; echo MARKER_42"], {
+    cols: 120,
+    rows: 10,
+  });
+  const marker = mgr.waitFor("marker-shell", /MARKER_42/, 5000);
+  const match = await marker;
   console.log("   matched:", match.trim());
+  await mgr.waitForExit("marker-shell", 5000).catch(() => {});
 
   console.log("\n9. tty check:");
-  mgr.sendKeys(
-    "test-shell",
-    'python3 -c "import sys; print(\'isatty:\', sys.stdout.isatty())"\n'
-  );
+  mgr.spawn("tty-check", "python3", ["-c", "import sys; print('isatty:', sys.stdout.isatty())"], {
+    cols: 120,
+    rows: 10,
+  });
   await sleep(800);
   const ttyLine = mgr
-    .capture("test-shell", 5)
+    .capture("tty-check", 5)
     .split("\n")
     .find((l) => l.includes("isatty:"));
   console.log("   " + (ttyLine || "(not found)").trim());
+  await mgr.waitForExit("tty-check", 5000).catch(() => {});
 
-  console.log("\n10. kill");
-  mgr.kill("test-shell");
-  await mgr.waitForExit("test-shell", 5000).catch(() => {});
+  console.log("\n10. exit scripted shell");
+  mgr.sendKeys("test-shell", "exit\r");
+  await mgr.waitForExit("test-shell", 5000).catch(() => {
+    mgr.kill("test-shell", "SIGKILL");
+  });
   console.log("    alive:", mgr.isAlive("test-shell"));
 
-  console.log("\n11. post-mortem (last 3 lines):");
+  console.log("\n11. kill disposable process");
+  mgr.spawn("kill-test", "zsh", ["-fc", "sleep 30"], { cols: 120, rows: 10 });
+  await sleep(200);
+  mgr.kill("kill-test");
+  await mgr.waitForExit("kill-test", 5000).catch(() => {
+    mgr.kill("kill-test", "SIGKILL");
+  });
+  console.log("    alive:", mgr.isAlive("kill-test"));
+
+  console.log("\n12. post-mortem (last 3 lines):");
   for (const l of mgr.capture("test-shell", 3).split("\n")) {
     console.log("    | " + l);
   }
@@ -1637,16 +1768,756 @@ ${cmd}() {
   local _p
   _p=$(command -v p 2>/dev/null || command -v pty-mgr 2>/dev/null)
   $_p status >/dev/null 2>&1 || $_p daemon
-  local _name
-  _name=$($_p wrap ${cmd} "$@" 2>&1 | awk '{print $1}')
+  local _wrap_out _wrap_status _name
+  _wrap_out=$($_p wrap command ${cmd} "$@" 2>&1)
+  _wrap_status=$?
+  if [ $_wrap_status -ne 0 ]; then
+    echo "pty-mgr: wrap failed for ${cmd}" >&2
+    case "$_wrap_out" in
+      *"unknown command: wrap"*) echo "pty-mgr: daemon does not support wrap; restart it after saving active sessions" >&2 ;;
+    esac
+    [ -n "$_wrap_out" ] && printf '%s\\n' "$_wrap_out" >&2
+    return $_wrap_status
+  fi
+  _name=$(printf '%s\\n' "$_wrap_out" | awk '$2 ~ /^pid=[0-9]+$/ { print $1; exit }')
   if [ -z "$_name" ]; then
-    echo "pty-mgr: wrap failed" >&2
+    echo "pty-mgr: wrap failed for ${cmd}: unexpected output" >&2
+    [ -n "$_wrap_out" ] && printf '%s\\n' "$_wrap_out" >&2
     return 1
   fi
   $_p attach "$_name"
 }`;
 }
 
+function parseWatchIntervalMs(value = "4s") {
+  const raw = String(value || "4s").trim().toLowerCase();
+  const match = raw.match(/^(\d+(?:\.\d+)?)(ms|s)?$/);
+  if (!match) throw new Error("watch interval must be milliseconds or seconds, e.g. 4000ms or 4s");
+  const amount = Number(match[1]);
+  const unit = match[2] || "ms";
+  const ms = unit === "s" ? amount * 1000 : amount;
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new Error("watch interval must be a non-negative duration");
+  }
+  return Math.round(ms);
+}
+
+async function verifyViewSession(name) {
+  const res = await sendCommand({ cmd: "capture", name, args: { lines: 1, screen: true } });
+  if (!res.ok) {
+    throw new Error(`session not found: ${name}`);
+  }
+}
+
+async function viewSessions(leftName, rightName, intervalMs = 500) {
+  if (!leftName || !rightName) {
+    throw new Error("usage: pty-mgr view <name1> <name2> [interval]");
+  }
+
+  const width = process.stdout.columns || 80;
+  if (width < 21) {
+    throw new Error("terminal too narrow for split view; need at least 21 columns");
+  }
+
+  await verifyViewSession(leftName);
+  await verifyViewSession(rightName);
+
+  let stopped = false;
+  let drawing = false;
+  let timer = null;
+  const stdinWasRaw = Boolean(process.stdin.isRaw);
+
+  const cleanup = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    process.stdout.write("\x1b[?25h\x1b[?1049l");
+    if (process.stdin.isTTY) {
+      try { process.stdin.setRawMode(stdinWasRaw); } catch {}
+      process.stdin.pause();
+      process.stdin.off("data", onData);
+    }
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+    process.off("exit", cleanup);
+  };
+
+  const onData = (chunk) => {
+    const text = chunk.toString("utf8");
+    if (text === "q" || text === "\x03") {
+      cleanup();
+      process.exit(0);
+    }
+  };
+
+  const onSignal = () => {
+    cleanup();
+    process.exit(0);
+  };
+
+  const draw = async () => {
+    if (stopped || drawing) return;
+    drawing = true;
+    try {
+      const cols = process.stdout.columns || 80;
+      const rows = process.stdout.rows || 24;
+      if (cols < 21) {
+        process.stdout.write("\x1b[H\x1b[2Jterminal too narrow for split view; need at least 21 columns");
+      } else {
+        const leftWidth = Math.floor((cols - 1) / 2);
+        const rightWidth = cols - 1 - leftWidth;
+        const captureLines = Math.max(1, rows - 1);
+        const [left, right] = await Promise.all([
+          sendCommand({ cmd: "capture", name: leftName, args: { lines: captureLines, screen: true } }),
+          sendCommand({ cmd: "capture", name: rightName, args: { lines: captureLines, screen: true } }),
+        ]);
+        if (!left.ok) throw new Error(`session not found: ${leftName}`);
+        if (!right.ok) throw new Error(`session not found: ${rightName}`);
+        const viewRows = composeSideBySideCaptureRows({
+          leftName,
+          rightName,
+          leftCapture: left.output || "",
+          rightCapture: right.output || "",
+          leftWidth,
+          rightWidth,
+          height: rows,
+        });
+        // Position each row absolutely at column 1. A bare "\n" in raw/alt-screen
+        // mode is a line feed without carriage return, so full-width rows cascade
+        // and scroll instead of stacking. Explicit cursor moves avoid all wrap.
+        let frame = "\x1b[H\x1b[2J";
+        for (let r = 0; r < viewRows.length; r++) {
+          frame += `\x1b[${r + 1};1H${viewRows[r]}`;
+        }
+        process.stdout.write(frame);
+      }
+    } catch (err) {
+      cleanup();
+      console.error(err.message);
+      process.exit(1);
+    } finally {
+      drawing = false;
+      if (!stopped) timer = setTimeout(draw, intervalMs);
+    }
+  };
+
+  process.stdout.write("\x1b[?1049h\x1b[?25l\x1b[H\x1b[2J");
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  }
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  process.on("exit", cleanup);
+
+  await draw();
+}
+
+function parseFlagArgs(tokens, startIndex = 0) {
+  const flags = {};
+  const rest = [];
+  for (let i = startIndex; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      const next = tokens[i + 1];
+      if (next == null || next.startsWith("--")) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      rest.push(token);
+    }
+  }
+  return { flags, rest };
+}
+
+function hashText(value) {
+  return createHash("sha256").update(value || "").digest("hex");
+}
+
+function capturePayloadText(res) {
+  if (res.results) {
+    return Object.entries(res.results)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([name, output]) => `--- ${name} ---\n${output || ""}`)
+      .join("\n");
+  }
+  return res.output || "";
+}
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+export function projectKeyForCwd(cwd) {
+  return cwd.replace(/\//g, "-");
+}
+
+export function loadFlowConfig(configPath = "pty-mgr.config.json") {
+  if (configPath && existsSync(configPath)) {
+    return JSON.parse(readFileSync(configPath, "utf8"));
+  }
+  return { adapters: {}, flows: {} };
+}
+
+function walkJsonlFiles(root, files = []) {
+  root = expandHome(root);
+  if (!root || !existsSync(root)) return files;
+
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      walkJsonlFiles(path, files);
+    } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function timestampMs(value) {
+  const ms = Date.parse(value || "");
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function getPath(obj, path) {
+  if (!path) return obj;
+  return String(path).split(".").reduce((value, part) => {
+    if (value == null) return undefined;
+    return value[part];
+  }, obj);
+}
+
+function matchesWhere(obj, where = {}) {
+  return Object.entries(where).every(([path, expected]) => getPath(obj, path) === expected);
+}
+
+function normalizeMessageText(value) {
+  return String(value || "").replace(/\r\n/g, "\n").trim();
+}
+
+function renderTemplate(value, context) {
+  return String(value)
+    .replaceAll("${home}", homedir())
+    .replaceAll("${cwd}", context.cwd)
+    .replaceAll("${projectKey}", projectKeyForCwd(context.cwd));
+}
+
+function adapterForKind(kind, config) {
+  const adapter = config.adapters?.[kind];
+  if (!adapter) throw new Error(`missing adapter config for agent kind: ${kind}`);
+  return adapter;
+}
+
+function transcriptStartedAtMs(file, adapter) {
+  const lines = readFileSync(file, "utf8").split("\n");
+  const timestampPaths = adapter.sessionTimestampPaths || ["payload.timestamp", "timestamp"];
+
+  for (const raw of lines.slice(0, 25)) {
+    const line = raw.trim();
+    if (!line) continue;
+
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    for (const path of timestampPaths) {
+      const ms = timestampMs(getPath(obj, path));
+      if (ms !== null) return ms;
+    }
+  }
+
+  return null;
+}
+
+export function transcriptRootsForKind(kind, config, cwd = process.cwd()) {
+  const adapter = adapterForKind(kind, config);
+  return (adapter.roots || [])
+    .map((root) => expandHome(renderTemplate(root, { cwd })))
+    .filter(Boolean)
+    .filter((root, index, roots) => existsSync(root) || index === roots.length - 1);
+}
+
+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))
+    .map((path) => {
+      const mtimeMs = statSync(path).mtimeMs;
+      const startedMs = transcriptStartedAtMs(path, adapter);
+      const matchMs = startedMs ?? mtimeMs;
+      return { path, mtimeMs, startedMs, matchMs };
+    })
+    .filter((file) => file.matchMs >= sinceMs)
+    .sort((a, b) => {
+      const aHasStart = a.startedMs !== null;
+      const bHasStart = b.startedMs !== null;
+      if (aHasStart && bHasStart) return b.startedMs - a.startedMs;
+      if (aHasStart !== bHasStart) return aHasStart ? -1 : 1;
+      return b.mtimeMs - a.mtimeMs;
+    });
+
+  return candidates[0]?.path || null;
+}
+
+function textFromSelector(obj, selector) {
+  if (selector.array) {
+    const value = getPath(obj, selector.array);
+    if (!Array.isArray(value)) return "";
+    return value
+      .filter((part) => part && typeof part === "object")
+      .filter((part) => matchesWhere(part, selector.where || {}))
+      .map((part) => getPath(part, selector.path || "text"))
+      .filter((text) => typeof text === "string" && text.length > 0)
+      .join("\n")
+      .trim();
+  }
+
+  const value = getPath(obj, selector.path);
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function recordTextFromObject(obj, spec = {}, stripPatterns = []) {
+  if (!matchesWhere(obj, spec.where || {})) return "";
+  if (spec.complete && !matchesWhere(obj, spec.complete)) return "";
+
+  let text = (spec.text || [])
+    .map((selector) => textFromSelector(obj, selector))
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+
+  for (const pattern of stripPatterns) {
+    text = text.replace(new RegExp(pattern, "m"), "").trim();
+  }
+
+  return normalizeMessageText(text);
+}
+
+function assistantTextFromObject(obj, adapter) {
+  return recordTextFromObject(obj, adapter.assistant || {}, adapter.stripPatterns || []);
+}
+
+function userTextFromObject(obj, adapter) {
+  return recordTextFromObject(obj, adapter.user || {});
+}
+
+function messageKey(obj, lineNumber) {
+  return [
+    obj.timestamp,
+    obj.uuid,
+    obj.payload?.id,
+    obj.payload?.call_id,
+    lineNumber,
+  ].filter(Boolean).join(":");
+}
+
+function lineFromMessageKey(key) {
+  const line = Number(String(key || "").split(":").at(-1));
+  return Number.isInteger(line) && line > 0 ? line : 0;
+}
+
+export function extractLastAssistantMessage(file, kind, afterKey = "", config = loadFlowConfig()) {
+  const adapter = adapterForKind(kind, config);
+  const lines = readFileSync(file, "utf8").split("\n");
+  const afterLine = lineFromMessageKey(afterKey);
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const text = assistantTextFromObject(obj, adapter);
+    if (!text) continue;
+
+    const key = messageKey(obj, i + 1);
+    if (afterLine && i + 1 <= afterLine) continue;
+    if (afterKey && key === afterKey) return null;
+    return { key, text, file };
+  }
+
+  return null;
+}
+
+function findSentMessageInTranscript(file, kind, sentText, config = loadFlowConfig()) {
+  const adapter = adapterForKind(kind, config);
+  if (!adapter.user) {
+    throw new Error(`agent kind ${kind} must define user parser to bind flow transcripts`);
+  }
+
+  const wanted = normalizeMessageText(sentText);
+  if (!wanted) return null;
+
+  const lines = readFileSync(file, "utf8").split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const text = userTextFromObject(obj, adapter);
+    if (!text || text !== wanted) continue;
+
+    return { key: messageKey(obj, i + 1), text, file };
+  }
+
+  return null;
+}
+
+export function findTranscriptForSentMessage({
+  kind,
+  cwd = process.cwd(),
+  text,
+  config,
+  file,
+}) {
+  if (file) return findSentMessageInTranscript(file, kind, text, config);
+
+  const candidates = transcriptRootsForKind(kind, config, cwd)
+    .flatMap((root) => walkJsonlFiles(root))
+    .map((path) => ({ path, mtimeMs: statSync(path).mtimeMs }))
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const candidate of candidates) {
+    const match = findSentMessageInTranscript(candidate.path, kind, text, config);
+    if (match) return match;
+  }
+
+  return null;
+}
+
+function renderSteeringTemplate(template, context) {
+  return String(template || "")
+    .replaceAll("{task}", context.task || "")
+    .replaceAll("{goal}", context.goal || context.task || "")
+    .replaceAll("{lastMessage}", context.lastMessage || "")
+    .replaceAll("{cycle}", String(context.cycle ?? ""))
+    .replaceAll("{from}", context.from || "")
+    .replaceAll("{to}", context.to || "");
+}
+
+export function buildFlowTurnMessage(turn, context) {
+  if (turn.template) return renderSteeringTemplate(turn.template, context).trim();
+  const text = (context.lastMessage || "").trim();
+  const steering = turn.append ? renderSteeringTemplate(turn.append, context).trim() : "";
+  return [text, steering].filter(Boolean).join("\n\n");
+}
+
+function flowAgentKind(agent) {
+  return agent.kind;
+}
+
+function workflowForName(config, workflowName) {
+  const workflow = config.flows?.[workflowName];
+  if (!workflow) throw new Error(`missing flow config: ${workflowName}`);
+  if (!workflow.agents || typeof workflow.agents !== "object") {
+    throw new Error(`flow ${workflowName} must define agents`);
+  }
+  if (!workflow.start?.to) throw new Error(`flow ${workflowName} must define start.to`);
+  if (!Array.isArray(workflow.turns) || workflow.turns.length === 0) {
+    throw new Error(`flow ${workflowName} must define at least one turn`);
+  }
+  return workflow;
+}
+
+async function ensureDaemonRunning() {
+  try {
+    const res = await sendCommand({ cmd: "status" });
+    if (res.ok) return;
+  } catch {}
+  throw new Error("daemon not running; start it with: p daemon");
+}
+
+async function launchFlowAgent(alias, agent, config, options, deps = {}) {
+  const kind = flowAgentKind(agent);
+  if (!kind) throw new Error(`flow agent ${alias} must define kind`);
+  const adapter = adapterForKind(kind, config);
+  const cwd = agent.cwd || options.cwd || process.cwd();
+  const startedAtMs = Date.now();
+
+  if (agent.session) {
+    const transcriptFile = agent.transcript
+      ? expandHome(renderTemplate(agent.transcript, { cwd }))
+      : null;
+    return { alias, session: agent.session, kind, cwd, startedAtMs, transcriptFile };
+  }
+
+  const command = agent.command || adapter.command || kind;
+  const args = agent.args || adapter.defaultArgs || [];
+  if (deps.launchAgent) return deps.launchAgent(alias, { command, args, kind, cwd, startedAtMs });
+
+  const res = await sendCommand({
+    cmd: "wrap",
+    args: {
+      cmd: command,
+      args,
+      cwd,
+      base: agent.base || alias,
+    },
+  });
+  if (!res.ok) throw new Error(res.error || `failed to launch agent ${alias}`);
+  const transcriptFile = agent.transcript
+    ? expandHome(renderTemplate(agent.transcript, { cwd }))
+    : null;
+  return { alias, session: res.name, kind, cwd, startedAtMs, transcriptFile };
+}
+
+async function sendFlowMessage(session, text, deps = {}) {
+  if (deps.sendMessage) return deps.sendMessage(session, text);
+  const res = await sendCommand({ cmd: "send", name: session, args: { text, enter: true } });
+  if (!res.ok) throw new Error(res.error || `failed to send to ${session}`);
+  return res;
+}
+
+async function waitForFlowSessionReady(session, { tries = 12, intervalMs = 1500 } = {}) {
+  // A freshly spawned agent CLI (codex, claude) repaints a splash/tips screen
+  // while booting; sending the first prompt during that repaint drops the
+  // keystrokes. Poll until the rendered screen is non-empty and unchanged
+  // between two samples (idle at its prompt). Best-effort: returns after the cap.
+  let prev = null;
+  for (let i = 0; i < tries; i++) {
+    const cap = await sendCommand({ cmd: "capture", name: session, args: { lines: 100 } });
+    const text = cap.ok ? capturePayloadText(cap) : "";
+    if (prev !== null && text.trim().length > 0 && text === prev) {
+      await sleep(400);
+      return true;
+    }
+    prev = text;
+    await sleep(intervalMs);
+  }
+  return false;
+}
+
+async function sendFlowMessageConfirmed(meta, text, config, deps = {}) {
+  // Send a prompt and confirm the agent actually accepted it. A freshly booted
+  // TUI can leave typed input un-submitted (the Enter races startup), which
+  // strands the flow waiting for a turn that never runs. If the sent message
+  // doesn't appear in the agent's transcript, nudge submit with a bare Enter.
+  // The nudge is always just Enter (never re-typed) so a spurious retry can't
+  // duplicate input. Returns whether acceptance was confirmed.
+  await sendFlowMessage(meta.session, text, deps);
+  meta.lastSentText = text;
+  meta.lastUserKey = "";
+  if (deps.launchAgent) return true; // dep-injected (test) mode: no real transcript
+  const nudges = 2;
+  for (let attempt = 0; attempt <= nudges; attempt++) {
+    const polls = attempt === 0 ? 5 : 4;
+    for (let i = 0; i < polls; i++) {
+      await sleep(3000);
+      const bound = findTranscriptForSentMessage({
+        kind: meta.kind,
+        cwd: meta.cwd,
+        text,
+        config,
+        file: meta.transcriptFile,
+      });
+      if (bound) {
+        meta.transcriptFile = bound.file;
+        meta.lastUserKey = bound.key;
+        return true;
+      }
+    }
+    if (attempt < nudges) await sendFlowMessage(meta.session, "", deps);
+  }
+  return false;
+}
+
+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";
+}
+
+async function waitForFlowMessage({
+  meta,
+  config,
+  afterKey,
+  intervalMs,
+  timeoutMs,
+  watchIntervalMs,
+  settleMs,
+  deps,
+}) {
+  const started = Date.now();
+  while (true) {
+    const status = await watchFlowSession(meta.session, watchIntervalMs, deps);
+    if (status === "done") {
+      if (settleMs > 0) {
+        await sleep(settleMs);
+        const settled = await watchFlowSession(meta.session, watchIntervalMs, deps);
+        if (settled !== "done") {
+          if (settled !== "working") {
+            throw new Error(`unexpected watch status for ${meta.session}: ${settled}`);
+          }
+          await sleep(intervalMs);
+          continue;
+        }
+      }
+
+      const bound = findTranscriptForSentMessage({
+        kind: meta.kind,
+        cwd: meta.cwd,
+        text: meta.lastSentText,
+        config,
+        file: meta.transcriptFile,
+      });
+      if (bound) {
+        meta.transcriptFile = bound.file;
+        meta.lastUserKey = bound.key;
+        const msg = extractLastAssistantMessage(
+          bound.file,
+          meta.kind,
+          meta.lastUserKey || afterKey || "",
+          config
+        );
+        if (msg?.text) return msg;
+      }
+    } else if (status !== "working") {
+      throw new Error(`unexpected watch status for ${meta.session}: ${status}`);
+    }
+
+    if (timeoutMs && Date.now() - started > timeoutMs) return null;
+    await sleep(intervalMs);
+  }
+}
+
+export async function runFlowWorkflow(options, deps = {}) {
+  const config = deps.config || loadFlowConfig(options.config);
+  const workflow = workflowForName(config, options.workflow);
+  const watchIntervalMs = parseWatchIntervalMs(
+    options.watchInterval || workflow.watchInterval || "10s"
+  );
+  const intervalMs = Number(options.intervalMs ?? workflow.intervalMs ?? 1000);
+  const settleMs = Number(options.settleMs ?? workflow.settleMs ?? 1500);
+  const timeoutMs = Number(options.timeoutMs ?? workflow.timeoutMs ?? 0);
+  const maxCycles = Number(options.maxCycles ?? workflow.maxCycles ?? 1);
+  const task = options.task || "";
+  const goal = options.goal || workflow.goal || task;
+  const agents = {};
+  const events = [];
+
+  if (!deps.launchAgent) await ensureDaemonRunning();
+
+  for (const [alias, agent] of Object.entries(workflow.agents)) {
+    agents[alias] = await launchFlowAgent(alias, agent, config, options, deps);
+    events.push({ type: "agent", alias, session: agents[alias].session, kind: agents[alias].kind });
+  }
+
+  const startAgent = agents[workflow.start.to];
+  if (!startAgent) throw new Error(`flow start target not found: ${workflow.start.to}`);
+  const startText = renderSteeringTemplate(workflow.start.template || "{task}", {
+    task,
+    goal,
+    cycle: 0,
+    to: workflow.start.to,
+  });
+  if (!deps.launchAgent) await waitForFlowSessionReady(startAgent.session);
+  const startAccepted = await sendFlowMessageConfirmed(startAgent, startText, config, deps);
+  events.push({ type: "send", from: "user", to: workflow.start.to, text: startText, accepted: startAccepted });
+  if (!startAccepted) {
+    return {
+      completed: false,
+      waitingFor: workflow.start.to,
+      reason: "start agent never accepted the initial task (input typed but not submitted)",
+      cycle: 0,
+      agents,
+      events,
+    };
+  }
+
+  const lastKeys = {};
+  for (let cycle = 0; cycle < maxCycles; cycle++) {
+    for (const turn of workflow.turns) {
+      const fromMeta = agents[turn.from];
+      const toMeta = agents[turn.to];
+      if (!fromMeta) throw new Error(`flow turn source not found: ${turn.from}`);
+      if (!toMeta) throw new Error(`flow turn target not found: ${turn.to}`);
+
+      const msg = await waitForFlowMessage({
+        meta: fromMeta,
+        config,
+        afterKey: lastKeys[turn.from] || "",
+        intervalMs,
+        timeoutMs,
+        watchIntervalMs,
+        settleMs,
+        deps,
+      });
+      if (!msg) {
+        return { completed: false, waitingFor: turn.from, cycle, agents, events };
+      }
+
+      lastKeys[turn.from] = msg.key;
+      const text = buildFlowTurnMessage(turn, {
+        task,
+        goal,
+        cycle: cycle + 1,
+        from: turn.from,
+        to: turn.to,
+        lastMessage: msg.text,
+      });
+      const accepted = await sendFlowMessageConfirmed(toMeta, text, config, deps);
+      events.push({ type: "turn", cycle: cycle + 1, from: turn.from, to: turn.to, key: msg.key, text, accepted });
+    }
+  }
+
+  return { completed: true, workflow: options.workflow, cycles: maxCycles, agents, events };
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function replaceManagedWrapper(rcContent, cmd, fn) {
+  const marker = `# pty-mgr: managed ${cmd} sessions`;
+  const pattern = new RegExp(
+    `\\n?${escapeRegex(marker)}\\n${escapeRegex(cmd)}\\(\\) \\{[\\s\\S]*?\\n\\}\\n?`,
+    "m"
+  );
+  const match = rcContent.match(pattern);
+
+  if (!match) return { content: rcContent, changed: false, found: false };
+  if (match[0].trim() === fn.trim()) {
+    return { content: rcContent, changed: false, found: true };
+  }
+
+  const prefix = match[0].startsWith("\n") ? "\n" : "";
+  const suffix = match[0].endsWith("\n") ? "\n" : "";
+  return {
+    content: rcContent.replace(pattern, `${prefix}${fn.trim()}\n${suffix}`),
+    changed: true,
+    found: true,
+  };
+}
+
 function detectRcFile() {
   const shell = process.env.SHELL || "";
   if (shell.endsWith("/zsh")) return join(homedir(), ".zshrc");
@@ -1660,7 +2531,7 @@ function detectRcFile() {
 }
 
 async function runSetup() {
-  const { appendFileSync, readFileSync } = await import("node:fs");
+  const { appendFileSync, readFileSync, writeFileSync } = await import("node:fs");
 
   console.log("pty-mgr setup");
   console.log("wrap CLI tools in managed PTY sessions.\n");
@@ -1699,21 +2570,33 @@ async function runSetup() {
 
   // write to rc file
   let added = [];
+  let updated = [];
   for (const cmd of wrapped) {
     const marker = `# pty-mgr: managed ${cmd} sessions`;
+    const fn = wrapperFunction(cmd);
     if (rcContent.includes(marker)) {
-      console.log(`'${cmd}' already in ${rcFile}, skipping`);
+      const replaced = replaceManagedWrapper(rcContent, cmd, fn);
+      if (replaced.changed) {
+        rcContent = replaced.content;
+        writeFileSync(rcFile, rcContent);
+        updated.push(cmd);
+      } else {
+        console.log(`'${cmd}' already in ${rcFile}, skipping`);
+      }
       continue;
     }
-    const fn = wrapperFunction(cmd);
     appendFileSync(rcFile, "\n" + fn + "\n");
+    rcContent += "\n" + fn + "\n";
     added.push(cmd);
   }
 
-  closeAsk();
-
   if (added.length > 0) {
     console.log(`\nadded to ${rcFile}: ${added.join(", ")}`);
+  }
+  if (updated.length > 0) {
+    console.log(`\nupdated in ${rcFile}: ${updated.join(", ")}`);
+  }
+  if (added.length > 0 || updated.length > 0) {
     console.log("\nrestart your shell or run:");
     console.log(`  source ${rcFile}`);
   } else {
@@ -1722,14 +2605,9 @@ async function runSetup() {
 }
 
 async function cli() {
-  // strip @name and --daemon <name> from argv (already consumed by getDaemonName)
-  const cleaned = process.argv.slice(2).filter((a, i, arr) => {
-    if (a.startsWith("@")) return false;
-    if (a === "--daemon") return false;
-    if (i > 0 && arr[i - 1] === "--daemon") return false;
-    return true;
-  });
-  const [rawCommand, ...args] = cleaned;
+  // daemon selector already consumed by splitDaemonArgs at module load;
+  // CLI_ARGS is the remaining command + args, with data tokens preserved.
+  const [rawCommand, ...args] = CLI_ARGS;
 
   // command aliases - short forms
   const ALIASES = {
@@ -1739,6 +2617,7 @@ async function cli() {
     c: "capture", cap: "capture",
     st: "status",
     a: "attach",
+    v: "view",
     k: "kill",
     l: "list", ls: "list",
     i: "info",
@@ -1763,7 +2642,7 @@ async function cli() {
 
   if (command === "demo") {
     await runDemo();
-    return;
+    process.exit(0);
   }
 
   if (command === "setup") {
@@ -1771,6 +2650,97 @@ async function cli() {
     return;
   }
 
+  if (command === "flow") {
+    const subcommand = args[0];
+    const { flags } = parseFlagArgs(args, 1);
+    const configPath = flags.config || "pty-mgr.config.json";
+    if (subcommand === "list") {
+      const config = loadFlowConfig(configPath);
+      const names = Object.keys(config.flows || {});
+      if (names.length === 0) {
+        console.log("no flows configured");
+      } else {
+        for (const name of names) {
+          console.log(name);
+          if (flags.verbose) {
+            const flow = config.flows[name] || {};
+            for (const [alias, agent] of Object.entries(flow.agents || {})) {
+              console.log(`  ${alias} -> ${flowAgentKind(agent)}`);
+            }
+            console.log(`  start -> ${flow.start?.to || ""}, maxCycles -> ${flow.maxCycles ?? 1}`);
+          }
+        }
+      }
+      return;
+    }
+
+    if (subcommand === "show") {
+      const name = args[1];
+      if (!name) {
+        console.error("usage: pty-mgr flow show <name>");
+        process.exit(1);
+      }
+      const config = loadFlowConfig(configPath);
+      const flow = config.flows?.[name];
+      if (!flow) {
+        console.error(`flow not found: ${name}`);
+        process.exit(1);
+      }
+
+      console.log(name);
+      console.log("agents:");
+      for (const [alias, agent] of Object.entries(flow.agents || {})) {
+        console.log(`  ${alias} -> ${flowAgentKind(agent)}`);
+      }
+      console.log(`start -> ${flow.start?.to || ""}`);
+      console.log("turns:");
+      for (const turn of flow.turns || []) {
+        console.log(`  ${turn.from || ""} -> ${turn.to || ""}`);
+        console.log(`    append: ${turn.append || ""}`);
+      }
+      console.log(`maxCycles -> ${flow.maxCycles ?? 1}`);
+      console.log(`watchInterval -> ${flow.watchInterval ?? "10s"}`);
+      console.log(`settleMs -> ${flow.settleMs ?? 1500}`);
+      return;
+    }
+
+    if (subcommand === "run") {
+      const workflow = args[1];
+      if (!workflow) {
+        console.error("usage: pty-mgr flow run <name> --task <text>");
+        process.exit(1);
+      }
+      const { flags: runFlags } = parseFlagArgs(args, 2);
+      const task = runFlags.task || "";
+      if (!task) {
+        console.error("flow run requires --task <text>");
+        process.exit(1);
+      }
+      try {
+        const result = await runFlowWorkflow({
+          workflow,
+          task,
+          goal: runFlags.goal,
+          config: runFlags.config || configPath,
+          cwd: runFlags.cwd || process.cwd(),
+          maxCycles: runFlags["max-cycles"],
+          watchInterval: runFlags["watch-interval"],
+          settleMs: runFlags["settle-ms"],
+          timeoutMs: runFlags["timeout-ms"],
+          intervalMs: runFlags["interval-ms"],
+        });
+        console.log(JSON.stringify(result, null, 2));
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+      return;
+    }
+
+    console.error("usage: pty-mgr flow list|show|run");
+    process.exit(1);
+  }
+
   if (command === "tg") {
     const flags = { reply: false, timeout: 60 };
     const parts = [];
@@ -1901,6 +2871,56 @@ async function cli() {
     return;
   }
 
+  if (command === "view") {
+    const [leftName, rightName, intervalArg] = args;
+    let intervalMs;
+    try {
+      intervalMs = parseWatchIntervalMs(intervalArg || "500ms");
+      await viewSessions(leftName, rightName, intervalMs);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === "watch") {
+    const name = args[0];
+    if (!name) {
+      console.error("usage: pty-mgr watch <name> [interval]");
+      process.exit(1);
+    }
+
+    let intervalMs;
+    try {
+      intervalMs = parseWatchIntervalMs(args[1] || "4s");
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+
+    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");
+      process.exit(0);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+
   // all other commands go through the daemon
   const name = args[0];