dsh-thoughtdag 0.4.9 → 0.4.11

package/lib/runtime/agents/pi.cjs

@@ -0,0 +1,358 @@
+// Pi as an agent runtime for the desktop shell. One `pi --mode rpc` child
+// per working directory, spoken to in JSONL: commands go down stdin with an
+// id and come back as `response` lines; everything else on stdout is a
+// session event (agent_start, message_update, tool_execution_*, agent_end…)
+// which the shell forwards to the renderer untouched, tagged with the run
+// it belongs to. Pi keeps its own session files (~/.pi/agent/sessions), its
+// own keys and model catalog: the shell only asks, never copies.
+//
+// A run is one prompt on one session: fresh (`new_session`), continued
+// (`switch_session` to a file), or branched (`fork` at an entry of the
+// current session). Runs on one process are serialized; a process idle for
+// a while is closed; a process that dies is replaced on the next run.
+
+'use strict';
+
+const { spawn, execFile } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const { randomUUID } = require('node:crypto');
+
+const fsp = fs.promises;
+const GUARD = path.join(__dirname, 'pi-guard.mjs');
+const IDLE_MS = Number(process.env.TD_AGENT_IDLE_MS) || 10 * 60 * 1000; // a Pi process (session or catalog) retires after this long without a listener
+const RESPONSE_MS = 30 * 1000;
+const CANDIDATE_DIRS = [
+  '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin',
+  path.join(os.homedir(), '.bun', 'bin'), path.join(os.homedir(), '.npm-global', 'bin'),
+  path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), '.pi', 'bin'),
+];
+
+async function executable(p) {
+  try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+/** The pi binary: PATH first (a terminal launch), then the usual homes
+ *  (a Finder launch carries almost no PATH). */
+async function findPi() {
+  const names = process.platform === 'win32' ? ['pi.cmd', 'pi.exe', 'pi'] : ['pi'];
+  const dirs = [...(process.env.PATH || '').split(path.delimiter), ...CANDIDATE_DIRS].filter(Boolean);
+  for (const d of dirs) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return p; }
+  return null;
+}
+
+/** PATH for the child: the shell's plus the usual homes, so Pi's own bash
+ *  tool finds git, node and friends even under a Finder launch. */
+function childEnv() {
+  const seen = new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean));
+  const extra = CANDIDATE_DIRS.filter((d) => !seen.has(d));
+  return { ...process.env, PATH: [...seen, ...extra].join(path.delimiter) };
+}
+
+class PiProcess {
+  constructor(bin, cwd, opts) {
+    this.cwd = cwd;
+    this.log = opts.log || (() => {});
+    this.onExit = opts.onExit || (() => {});
+    this.pending = new Map();
+    this.nextId = 1;
+    this.buf = '';
+    this.dead = false;
+    this.busy = Promise.resolve();
+    this.listener = null;       // the run currently receiving events
+    this.openDialogs = new Set(); // confirm questions forwarded to the canvas, not yet answered
+    this.idleTimer = null;
+    // extra extensions for development and tests (colon-separated paths)
+    const extra = (process.env.TD_PI_EXTRA_EXTENSIONS || '').split(':').filter(Boolean).flatMap((e) => ['-e', e]);
+    const args = ['--mode', 'rpc', ...(opts.noSession ? ['--no-session'] : ['-e', GUARD, ...extra])];
+    this.proc = spawn(bin, args, { cwd, env: childEnv(), stdio: ['pipe', 'pipe', 'pipe'] });
+    this.proc.stdout.on('data', (d) => this.feed(d.toString()));
+    this.proc.stderr.on('data', (d) => this.log('[pi stderr] ' + d.toString().trim().slice(0, 400)));
+    this.proc.on('error', (e) => { this.log('[pi] spawn error: ' + e.message); this.die('spawn error: ' + e.message); });
+    this.proc.on('exit', (code, signal) => this.die(`pi exited (${signal || code})`));
+    this.touch();
+  }
+
+  touch() {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => { if (!this.listener) this.close(); }, IDLE_MS);
+  }
+
+  feed(chunk) {
+    this.buf += chunk;
+    let i;
+    while ((i = this.buf.indexOf('\n')) >= 0) {
+      const line = this.buf.slice(0, i); this.buf = this.buf.slice(i + 1);
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { this.log('[pi] non-JSON line: ' + line.slice(0, 120)); continue; }
+      this.dispatch(msg);
+    }
+  }
+
+  dispatch(msg) {
+    if (msg.type === 'response') {
+      const p = msg.id !== undefined ? this.pending.get(msg.id) : undefined;
+      if (p) { this.pending.delete(msg.id); p(msg); }
+      return;
+    }
+    if (msg.type === 'extension_ui_request') {
+      // a question for the person — confirm, select, input, editor — goes to
+      // the run as one `question` event; the canvas shows it on the node and
+      // answers through `answer`. Fire-and-forget notices (notify, status,
+      // widget, title) are not questions and get no answer.
+      const method = String(msg.method ?? '');
+      const KINDS = { confirm: 'confirm', select: 'select', input: 'input', editor: 'editor' };
+      if (KINDS[method] && this.listener) {
+        this.openDialogs.add(String(msg.id));
+        // the guard appends a structured tail (paths, a directory to offer)
+        // after U+241F; the person sees only the text before it
+        const raw = String(msg.message ?? '');
+        const cut = raw.indexOf('\u241F');
+        let extra = {};
+        if (cut >= 0) { try { extra = JSON.parse(raw.slice(cut + 1)); } catch { extra = {}; } }
+        this.listener({
+          type: 'question', kind: KINDS[method], id: msg.id, title: msg.title ?? '', message: cut >= 0 ? raw.slice(0, cut) : raw,
+          options: Array.isArray(msg.options) ? msg.options.map(String) : [],
+          placeholder: typeof msg.placeholder === 'string' ? msg.placeholder : null,
+          prefill: typeof msg.prefill === 'string' ? msg.prefill : null,
+          paths: Array.isArray(extra.paths) ? extra.paths : [], suggest: typeof extra.suggest === 'string' ? extra.suggest : null,
+        });
+        return;
+      }
+      if (KINDS[method]) {
+        // nobody is listening: the dialog resolves to its default at once
+        this.write({ type: 'extension_ui_response', id: msg.id, cancelled: true });
+      }
+      return;
+    }
+    this.listener?.(msg);
+  }
+
+  write(obj) {
+    try { this.proc.stdin.write(JSON.stringify(obj) + '\n'); return true; } catch { return false; }
+  }
+
+  /** Withdraw every question still waiting on the canvas: Pi resolves each
+   *  with its default at once, so nothing dangles after a stop. */
+  withdrawDialogs() {
+    for (const id of this.openDialogs) this.write({ type: 'extension_ui_response', id, cancelled: true });
+    this.openDialogs.clear();
+  }
+
+  send(cmd, timeoutMs = RESPONSE_MS) {
+    if (this.dead) return Promise.reject(new Error('pi process is gone'));
+    const id = String(this.nextId++);
+    this.touch();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`pi did not answer ${cmd.type} in ${timeoutMs / 1000}s`)); }, timeoutMs);
+      this.pending.set(id, (msg) => {
+        clearTimeout(timer);
+        if (msg.success === false) reject(new Error(msg.error || `pi refused ${cmd.type}`));
+        else resolve(msg.data);
+      });
+      if (!this.write({ id, ...cmd })) { clearTimeout(timer); this.pending.delete(id); reject(new Error('pi stdin closed')); }
+    });
+  }
+
+  /** Runs `fn` when no other run holds this process. */
+  exclusive(fn) {
+    const turn = this.busy.then(fn, fn);
+    this.busy = turn.catch(() => {});
+    return turn;
+  }
+
+  die(reason) {
+    if (this.dead) return;
+    this.dead = true;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    for (const p of this.pending.values()) p({ type: 'response', success: false, error: reason });
+    this.pending.clear();
+    this.listener?.({ type: 'process_exit', reason });
+    this.listener = null;
+    this.onExit(this);
+  }
+
+  close() {
+    if (this.dead) return;
+    try { this.proc.kill(); } catch { /* already gone */ }
+  }
+}
+
+const { snapshotDir, diffSnapshots } = require('./fs-diff.cjs');
+
+const textOf = (message) => (Array.isArray(message?.content) ? message.content : [])
+  .filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('');
+
+function createPiRuntime({ log } = {}) {
+  const say = log || (() => {});
+  const procs = new Map();     // cwd → PiProcess
+  const runs = new Map();      // runId → { proc, abort() }
+  let binPromise = null;
+
+  const bin = () => { if (!binPromise) binPromise = findPi(); return binPromise; };
+  // Pi's thinking levels in its own words, from its own `--help`
+  // (`--thinking <level>  Set thinking level: off, minimal, …`); read once
+  let levelsPromise = null;
+  const levelsOf = (b) => {
+    if (!levelsPromise) levelsPromise = new Promise((resolve) => {
+      execFile(b, ['--help'], { env: childEnv(), timeout: 8000, maxBuffer: 1 << 20 }, (_err, stdout) => {
+        const m = String(stdout || '').match(/--thinking[^\n]*?level:\s*([a-z0-9_, -]+)/i);
+        resolve(m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : []);
+      });
+    });
+    return levelsPromise;
+  };
+
+  async function processFor(cwd) {
+    const live = procs.get(cwd);
+    if (live && !live.dead) return live;
+    const b = await bin();
+    if (!b) throw new Error('pi is not installed (no `pi` on PATH or in the usual places)');
+    const p = new PiProcess(b, cwd, { log: say, onExit: (dead) => { if (procs.get(cwd) === dead) procs.delete(cwd); } });
+    procs.set(cwd, p);
+    return p;
+  }
+
+  const modelEntry = (m) => ({
+    provider: m.provider, id: m.id, name: m.name || m.id,
+    reasoning: !!m.reasoning, vision: Array.isArray(m.input) && m.input.includes('image'),
+  });
+
+  return {
+    /** Where pi is, or null. */
+    available: () => bin(),
+
+    /** Pi's configured models and its current default, asked of a
+     *  sessionless process in the home directory. */
+    async models() {
+      const b = await bin();
+      if (!b) return { installed: false, models: [], default: null };
+      const key = '\0catalog';
+      let p = procs.get(key);
+      if (!p || p.dead) { p = new PiProcess(b, os.homedir(), { log: say, noSession: true, onExit: (d) => { if (procs.get(key) === d) procs.delete(key); } }); procs.set(key, p); }
+      return p.exclusive(async () => {
+        const [cat, state, levels] = await Promise.all([p.send({ type: 'get_available_models' }), p.send({ type: 'get_state' }), levelsOf(b)]);
+        const defaultEffort = typeof state?.thinkingLevel === 'string' ? state.thinkingLevel : null;
+        const models = (cat?.models ?? []).map((m) => ({ ...modelEntry(m), efforts: m.reasoning ? levels : [], defaultEffort: m.reasoning ? defaultEffort : null }));
+        const cur = state?.model ? `${state.model.provider}/${state.model.id}` : null;
+        return { installed: true, models, default: cur && models.some((m) => `${m.provider}/${m.id}` === cur) ? cur : (models[0] ? `${models[0].provider}/${models[0].id}` : null), thinkingLevel: state?.thinkingLevel ?? null };
+      });
+    },
+
+    /**
+     * One prompt on one session. `onEvent` receives Pi's session events as
+     * they come, plus the shell's own: `session` (which session this run
+     * writes to, before the prompt), `run_end` (with the final text), and
+     * `run_error`. Resolves with the runId as soon as the run is accepted.
+     */
+    async run(req, onEvent) {
+      const cwd = String(req.cwd || '');
+      if (!cwd || !path.isAbsolute(cwd)) throw new Error('run needs an absolute cwd');
+      await fsp.mkdir(cwd, { recursive: true });
+      const runId = randomUUID();
+      const proc = await processFor(cwd);
+      const emit = (event) => { try { onEvent({ runId, event }); } catch { /* renderer gone */ } };
+      const aborter = { aborted: false };
+      runs.set(runId, { proc, abort: () => { aborter.aborted = true; proc.withdrawDialogs(); proc.send({ type: 'abort' }).catch(() => {}); } });
+
+      void proc.exclusive(async () => {
+        let text = '';
+        let ended;
+        const finished = new Promise((resolve) => { ended = resolve; });
+        // a turn that produces nothing for a long while — a command waiting
+        // on stdin, a stuck process — is stopped, with the reason on the node;
+        // a question waiting on the person does not count as silence
+        const IDLE = Number(process.env.TD_AGENT_IDLE_MS) || 10 * 60 * 1000;
+        let lastEvent = Date.now();
+        let waitingOnPerson = false;
+        const watchdog = setInterval(() => {
+          if (waitingOnPerson || Date.now() - lastEvent < IDLE) return;
+          emit({ type: 'run_error', message: `no activity for ${IDLE >= 60000 ? Math.round(IDLE / 60000) + ' min' : Math.round(IDLE / 1000) + ' s'}; the turn was stopped` });
+          proc.withdrawDialogs();
+          proc.send({ type: 'abort' }).catch(() => {});
+          setTimeout(() => ended('idle'), 5000);
+        }, 15000);
+        proc.listener = (event) => {
+          lastEvent = Date.now();
+          if (event.type === 'question') waitingOnPerson = true;
+          if (event.type === 'question_answered') waitingOnPerson = false;
+          if (event.type === 'message_end' && event.message?.role === 'assistant') text = textOf(event.message) || text;
+          if (event.type === 'process_exit') { emit({ type: 'run_error', message: event.reason }); ended('exit'); return; }
+          emit(event);
+          if (event.type === 'agent_end') ended('end');
+        };
+        try {
+          if (req.sessionPath) await proc.send({ type: 'switch_session', sessionPath: String(req.sessionPath) });
+          if (req.forkEntryId) await proc.send({ type: 'fork', entryId: String(req.forkEntryId) });
+          else if (!req.sessionPath) await proc.send({ type: 'new_session' });
+          if (req.model && typeof req.model === 'object' && req.model.provider && req.model.id) await proc.send({ type: 'set_model', provider: req.model.provider, modelId: req.model.id });
+          // only a level Pi itself lists; an explicit thinkingLevel still wins
+          const level = req.thinkingLevel || (req.effort && (await levelsOf(await bin())).includes(req.effort) ? req.effort : null);
+          if (level) await proc.send({ type: 'set_thinking_level', level });
+          const state = await proc.send({ type: 'get_state' });
+          emit({ type: 'session', effort: typeof state?.thinkingLevel === 'string' ? state.thinkingLevel : null, sessionId: state?.sessionId ?? null, sessionFile: state?.sessionFile ?? null, model: state?.model ? { provider: state.model.provider, id: state.model.id, name: state.model.name } : null, cwd });
+          const before = await snapshotDir(cwd).catch(() => null);
+          if (aborter.aborted) { ended('aborted'); }
+          else {
+            // the prompt's response may follow the whole turn; the end is read from events
+            proc.send({ type: 'prompt', message: String(req.prompt ?? ''), ...(Array.isArray(req.images) && req.images.length ? { images: req.images } : {}) }, 24 * 60 * 60 * 1000).catch((e) => { emit({ type: 'run_error', message: e.message }); ended('error'); });
+          }
+          const how = await finished;
+          if (before) {
+            const after = await snapshotDir(cwd).catch(() => null);
+            if (after) {
+              const d = diffSnapshots(before, after);
+              if (d.changed.length || d.added.length || d.removed.length || d.truncated) emit({ type: 'fs_changes', ...d });
+            }
+          }
+          emit({ type: 'run_end', text, how });
+        } catch (e) {
+          emit({ type: 'run_error', message: e instanceof Error ? e.message : String(e) });
+          emit({ type: 'run_end', text, how: 'error' });
+        } finally {
+          clearInterval(watchdog);
+          proc.withdrawDialogs();
+          proc.listener = null;
+          proc.touch();
+          runs.delete(runId);
+        }
+      });
+      return runId;
+    },
+
+    abort(runId) {
+      const r = runs.get(runId);
+      if (!r) return false;
+      r.abort();
+      return true;
+    },
+
+    /**
+     * The person's answer to a question of a running turn:
+     * { confirmed } for a confirm, { value } for select/input/editor,
+     * { cancelled: true } to withdraw (the dialog's default applies).
+     */
+    answer(runId, requestId, response) {
+      const r = runs.get(runId);
+      if (!r) return false;
+      const id = String(requestId);
+      const a = response && typeof response === 'object' ? response : { confirmed: !!response };
+      const wire = a.cancelled ? { type: 'extension_ui_response', id, cancelled: true }
+        : typeof a.value === 'string' ? { type: 'extension_ui_response', id, value: a.value }
+        : { type: 'extension_ui_response', id, confirmed: !!a.confirmed };
+      const ok = r.proc.write(wire);
+      r.proc.openDialogs.delete(id);
+      if (ok) r.proc.listener?.({ type: 'question_answered', id, outcome: a.cancelled ? 'cancelled' : typeof a.value === 'string' ? 'answered' : (a.confirmed ? 'allowed-once' : 'rejected'), value: typeof a.value === 'string' ? a.value : null });
+      return ok;
+    },
+
+    shutdown() {
+      for (const p of procs.values()) p.close();
+      procs.clear();
+    },
+  };
+}
+
+module.exports = { createPiRuntime, findPi };

package/lib/runtime/sessions-fs.cjs

@@ -0,0 +1,100 @@
+// The other agents' session files as the atlas reads them, over HTTP, in
+// plain Node — the same primitives the desktop bridge and the harness
+// host expose: roots, a listing, a head, a whole read, a line-aligned
+// range. `rel` never escapes its root. Used by the local server.
+'use strict';
+const os = require('node:os');
+const { join, resolve, sep } = require('node:path');
+const { readdir, stat, open, readFile } = require('node:fs/promises');
+
+const FILE_ROOTS = {
+  'claude-projects': join(os.homedir(), '.claude', 'projects'),
+  'codex-sessions': join(os.homedir(), '.codex', 'sessions'),
+  'pi-sessions': join(os.homedir(), '.pi', 'agent', 'sessions'),
+};
+const FILE_READ_MAX = 256 * 1024 * 1024;
+
+class HttpError extends Error { constructor(status, message) { super(message); this.status = status; } }
+
+function fileInRoot(rootKey, rel) {
+  const root = FILE_ROOTS[rootKey];
+  if (!root) throw new HttpError(404, 'no such root');
+  if (typeof rel !== 'string' || !rel) throw new HttpError(400, 'rel required');
+  const abs = resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + sep)) throw new HttpError(400, 'rel escapes its root');
+  return abs;
+}
+
+async function listRoot(rootKey) {
+  const root = FILE_ROOTS[rootKey];
+  if (!root) throw new HttpError(404, 'no such root');
+  const out = [];
+  const walk = async (dir, depth) => {
+    if (depth > 5) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      const p = join(dir, ent.name);
+      if (ent.isDirectory()) await walk(p, depth + 1);
+      else if (ent.isFile() && ent.name.endsWith('.jsonl')) {
+        try { const st = await stat(p); out.push({ rel: p.slice(root.length + 1), size: st.size, mtime: st.mtimeMs }); } catch { /* raced */ }
+      }
+    }
+  };
+  await walk(root, 0);
+  return out;
+}
+
+async function headOfFile(abs, bytes) {
+  const n = Math.min(Math.max(1024, bytes | 0), 524288);
+  const fh = await open(abs, 'r');
+  try { const buf = Buffer.alloc(n); const { bytesRead } = await fh.read(buf, 0, n, 0); return buf.subarray(0, bytesRead).toString('utf8'); } finally { await fh.close(); }
+}
+
+async function rangeOfFile(abs, start, length) {
+  const fh = await open(abs, 'r');
+  try {
+    const from = Math.max(0, Number(start) || 0);
+    const want = Math.min(Math.max(65536, Number(length) || 0), 32 * 1024 * 1024);
+    const st = await fh.stat();
+    if (from >= st.size) return { text: '', nextStart: from, eof: true };
+    const buf = Buffer.alloc(Math.min(want, st.size - from));
+    const { bytesRead } = await fh.read(buf, 0, buf.length, from);
+    let slice = buf.subarray(0, bytesRead).toString('utf8');
+    const eof = from + bytesRead >= st.size;
+    if (!eof) { const cut = slice.lastIndexOf('\n'); if (cut >= 0) slice = slice.slice(0, cut + 1); }
+    return { text: slice, nextStart: from + Buffer.byteLength(slice, 'utf8'), eof };
+  } finally { await fh.close(); }
+}
+
+/** Handle `/roots` and `/roots/<key>/<op>`; returns false when not ours. */
+async function handleSessions(req, res, sub) {
+  const url = new URL(req.url ?? '/', 'http://local');
+  const p = sub.replace(/\/+$/, '');
+  const json = (status, body) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(body)); return true; };
+  const text = (type, body) => { res.writeHead(200, { 'content-type': type }); res.end(body); return true; };
+  try {
+    if (p === '/roots' && req.method === 'GET') {
+      const roots = [];
+      for (const [key, dir] of Object.entries(FILE_ROOTS)) roots.push({ key, path: dir, builtin: true, exists: await stat(dir).then((st) => st.isDirectory()).catch(() => false) });
+      return json(200, { roots });
+    }
+    const m = /^\/roots\/([a-z-]+)\/(list|head|read|range)$/.exec(p);
+    if (!m || req.method !== 'GET') return false;
+    const key = m[1];
+    if (m[2] === 'list') return json(200, { files: await listRoot(key) });
+    const abs = fileInRoot(key, url.searchParams.get('rel') ?? '');
+    if (m[2] === 'head') return text('text/plain; charset=utf-8', await headOfFile(abs, Number(url.searchParams.get('bytes')) || 16384).catch(() => ''));
+    if (m[2] === 'read') {
+      const st = await stat(abs).catch(() => null);
+      if (!st) return json(404, { error: 'no such file' });
+      if (st.size > FILE_READ_MAX) return json(413, { error: 'file too large to read whole; use range' });
+      return text('application/x-ndjson; charset=utf-8', await readFile(abs));
+    }
+    return json(200, await rangeOfFile(abs, url.searchParams.get('start'), url.searchParams.get('length')));
+  } catch (e) {
+    return json(e instanceof HttpError ? e.status : 500, { error: e instanceof Error ? e.message : String(e) });
+  }
+}
+
+module.exports = { FILE_ROOTS, fileInRoot, listRoot, headOfFile, rangeOfFile, handleSessions };

package/lib/runtime/terminal.cjs

@@ -0,0 +1,105 @@
+// Opening a runner's session in the person's terminal, in plain Node: the
+// command each runner resumes with, the terminals we know how to launch on
+// each platform, and one call that picks the first available. The desktop
+// shell adds its own preferences on top; a host without preferences takes
+// the first terminal that exists.
+'use strict';
+const path = require('node:path');
+const os = require('node:os');
+const fsp = require('node:fs/promises');
+const { spawn } = require('node:child_process');
+
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const fileExists = (p) => fsp.access(p).then(() => true, () => false);
+const dirExists = async (p) => { try { return (await fsp.stat(p)).isDirectory(); } catch { return false; } };
+
+/** The command that resumes a session in each runner's own CLI. */
+const PROGRAMS = {
+  'claude-code': (id) => `claude --resume ${shq(id)}`,
+  codex: (id) => `codex resume ${shq(id)}`,
+  pi: (id) => `pi --session ${shq(id)}`,
+};
+
+const run = (bin, args) => new Promise((resolve) => {
+  const c = spawn(bin, args, { stdio: 'ignore', detached: process.platform === 'linux' });
+  c.on('error', () => resolve(false));
+  c.on('exit', (code) => resolve(code === 0));
+  if (process.platform === 'linux') c.unref();
+});
+
+async function binOnPath(name) {
+  for (const d of (process.env.PATH || '').split(path.delimiter)) {
+    if (d && await fileExists(path.join(d, name))) return true;
+  }
+  return false;
+}
+
+// macOS: a .command file runs in the user's default shell (right PATH,
+// zero automation permissions) inside any terminal app that accepts it.
+async function launchCommandFile(appPath, cwd, program) {
+  const file = path.join(os.tmpdir(), `thoughtdag-resume-${Date.now()}.command`);
+  try {
+    await fsp.writeFile(file, `#!/bin/zsh\nrm -- ${shq(file)}\ncd ${shq(cwd)}\n${program}\n`, { mode: 0o755 });
+  } catch { return false; }
+  return run('open', ['-a', appPath, file]);
+}
+const launchOpenArgs = (appPath, argv) => run('open', ['-na', appPath, '--args', ...argv]);
+const posix = (cwd, program) => ['-lc', `cd ${shq(cwd)} && ${program}`];
+
+/** The terminals this platform can launch, in preference order. */
+function buildTerminalRegistry(customTerminals = []) {
+  if (process.platform === 'darwin') {
+    const appEntry = (id, name, appPath, launch) => ({ id, name, probe: () => dirExists(appPath), launch });
+    return [
+      appEntry('terminal', 'Terminal', '/System/Applications/Utilities/Terminal.app', (cwd, p) => launchCommandFile('/System/Applications/Utilities/Terminal.app', cwd, p)),
+      appEntry('iterm', 'iTerm2', '/Applications/iTerm.app', (cwd, p) => launchCommandFile('/Applications/iTerm.app', cwd, p)),
+      appEntry('ghostty', 'Ghostty', '/Applications/Ghostty.app', (cwd, p) => launchOpenArgs('/Applications/Ghostty.app', ['-e', 'zsh', ...posix(cwd, p)])),
+      appEntry('warp', 'Warp', '/Applications/Warp.app', (cwd, p) => launchCommandFile('/Applications/Warp.app', cwd, p)),
+      appEntry('alacritty', 'Alacritty', '/Applications/Alacritty.app', (cwd, p) => launchOpenArgs('/Applications/Alacritty.app', ['-e', 'zsh', ...posix(cwd, p)])),
+      appEntry('kitty', 'kitty', '/Applications/kitty.app', (cwd, p) => launchOpenArgs('/Applications/kitty.app', ['zsh', ...posix(cwd, p)])),
+      appEntry('wezterm', 'WezTerm', '/Applications/WezTerm.app', (cwd, p) => launchOpenArgs('/Applications/WezTerm.app', ['start', '--', 'zsh', ...posix(cwd, p)])),
+      // user-picked terminal apps ride the .command road — the one macOS
+      // mechanism that needs nothing from the app but "opens shell scripts"
+      ...customTerminals.map((c) => ({ id: c.id, name: c.name, custom: true, probe: () => dirExists(c.app), launch: (cwd, p) => launchCommandFile(c.app, cwd, p) })),
+    ];
+  }
+  if (process.platform === 'win32') {
+    const wtPath = path.join(process.env.LOCALAPPDATA ?? '', 'Microsoft', 'WindowsApps', 'wt.exe');
+    return [
+      { id: 'wt', name: 'Windows Terminal', probe: async () => (await fileExists(wtPath)) || binOnPath('wt.exe'), launch: (cwd, p) => run('wt.exe', ['-d', cwd, 'cmd', '/k', p]) },
+      { id: 'powershell', name: 'PowerShell', probe: async () => true, launch: (cwd, p) => run('cmd', ['/c', 'start', '', 'powershell', '-NoExit', '-Command', `Set-Location -LiteralPath '${cwd.replace(/'/g, "''")}'; ${p}`]) },
+      { id: 'cmd', name: 'Command Prompt', probe: async () => true, launch: (cwd, p) => run('cmd', ['/c', 'start', '', 'cmd', '/k', `cd /d "${cwd}" && ${p}`]) },
+    ];
+  }
+  // linux: binaries on PATH, each with its documented cwd/exec flags
+  const bin = (id, name, argv) => ({ id, name, probe: () => binOnPath(id), launch: (cwd, p) => run(id, argv(cwd, p)) });
+  return [
+    bin('gnome-terminal', 'GNOME Terminal', (cwd, p) => ['--working-directory', cwd, '--', 'bash', ...posix(cwd, p)]),
+    bin('konsole', 'Konsole', (cwd, p) => ['--workdir', cwd, '-e', 'bash', ...posix(cwd, p)]),
+    bin('xfce4-terminal', 'Xfce Terminal', (cwd, p) => [`--working-directory=${cwd}`, '-x', 'bash', ...posix(cwd, p)]),
+    bin('ghostty', 'Ghostty', (cwd, p) => ['-e', 'bash', ...posix(cwd, p)]),
+    bin('alacritty', 'Alacritty', (cwd, p) => ['--working-directory', cwd, '-e', 'bash', ...posix(cwd, p)]),
+    bin('kitty', 'kitty', (cwd, p) => ['--directory', cwd, 'bash', ...posix(cwd, p)]),
+    bin('wezterm', 'WezTerm', (cwd, p) => ['start', '--cwd', cwd, '--', 'bash', ...posix(cwd, p)]),
+    bin('x-terminal-emulator', 'System terminal', (cwd, p) => ['-e', `bash -lc ${shq(`cd ${shq(cwd)} && ${p}`)}`]),
+  ];
+}
+
+/** Open a runner's session in a terminal: the preferred one, else the first
+ *  that exists. Returns what the atlas expects. */
+async function openInTerminal(runner, cwd, sessionId, { preferred = '', customTerminals = [] } = {}) {
+  const buildProgram = PROGRAMS[runner];
+  if (!buildProgram || !/^[\w.-]{4,}$/.test(String(sessionId))) return { opened: false, via: '', command: '' };
+  const dir = typeof cwd === 'string' && path.isAbsolute(cwd) && await dirExists(cwd) ? cwd : os.homedir();
+  const program = buildProgram(sessionId);
+  const command = `cd ${shq(dir)} && ${program}`;
+  const registry = buildTerminalRegistry(customTerminals);
+  const ordered = [...registry.filter((t) => t.id === preferred), ...registry.filter((t) => t.id !== preferred)];
+  for (const t of ordered) {
+    if (!(await t.probe().catch(() => false))) continue;
+    if (await t.launch(dir, program)) return { opened: true, via: 'terminal', command, terminal: t.id };
+  }
+  return { opened: false, via: '', command };
+}
+
+module.exports = { PROGRAMS, shq, run, binOnPath, launchCommandFile, launchOpenArgs, posix, buildTerminalRegistry, openInTerminal, dirExists, fileExists };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-thoughtdag",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "ThoughtDAG for DeepSeek Harness: turn the current DSH session into an editable thought graph on an infinite canvas.",
   "author": "Xia Chen",
   "repository": {