quotacap 0.0.22 → 0.0.24

package/dist/adapters/pty.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { registerTrackedChild } from "../runtime/spawn.js";
+import { diagnosticError, DiagnosticError } from "../diagnostics/failure.js";
 export function stripAnsi(s) {
     return s
         .replace(/\x1b\[[^A-Za-z]*[A-Za-z]/g, "")
@@ -18,17 +19,116 @@ function regexTest(re, s) {
     const fresh = new RegExp(re.source, re.flags.replace("g", ""));
     return fresh.test(s);
 }
+/**
+ * Canned answers to terminal capability queries, table-driven so a future
+ * query type is a one-line row. Replies are static: colour answers never
+ * affect parsing because styling is stripped before matching.
+ */
+export const TERMINAL_QUERY_RESPONSES = [
+    // DSR (device status report): cursor position request. Unanswered, some
+    // TUIs exit outright ("cursor position could not be read").
+    { match: /\x1b\[[0-9;]*6n/, reply: () => "\x1b[1;1R" },
+    // DA1 (primary device attributes): `CSI c` is exclusively a DA request.
+    { match: /\x1b\[[0-9;]*c/, reply: () => "\x1b[?1;2c" },
+    // OSC 4/10/11 colour queries, BEL- or ST-terminated. The palette index is
+    // echoed back; 16 OSC 4 queries were measured in a single Muse startup.
+    { match: /\x1b\]4;(\d+);\?(?:\x07|\x1b\\)/, reply: (m) => `\x1b]4;${m[1]};rgb:0000/0000/0000\x07` },
+    { match: /\x1b\]10;\?(?:\x07|\x1b\\)/, reply: () => "\x1b]10;rgb:ffff/ffff/ffff\x07" },
+    { match: /\x1b\]11;\?(?:\x07|\x1b\\)/, reply: () => "\x1b]11;rgb:0000/0000/0000\x07" },
+];
+/**
+ * Stateful feeder for `TERMINAL_QUERY_RESPONSES`. Consumes each matched query
+ * from an internal buffer, so a query split across chunks is answered once it
+ * completes and never answered twice. Plain output passes through silently.
+ */
+export function createTerminalQueryResponder(write) {
+    let buf = "";
+    return (chunk) => {
+        buf += chunk;
+        let progress = true;
+        while (progress) {
+            progress = false;
+            for (const rule of TERMINAL_QUERY_RESPONSES) {
+                const m = rule.match.exec(buf);
+                if (m?.index !== undefined) {
+                    write(rule.reply(m));
+                    buf = buf.slice(0, m.index) + buf.slice(m.index + m[0].length);
+                    progress = true;
+                    break;
+                }
+            }
+        }
+        // Bounded tail: a partial query can only straddle the end of the stream,
+        // and the longest query is well under 64 bytes.
+        if (buf.length > 64)
+            buf = buf.slice(-64);
+    };
+}
+/**
+ * Lazy replacement for the removed postinstall: best-effort `chmod 0o755`
+ * over every prebuilds entry `spawn-helper` under the given node-pty roots.
+ * Missing roots, missing prebuild dirs, and missing helpers are skipped
+ * silently; only attempted repairs are recorded.
+ */
+export function repairSpawnHelpers(roots, chmod = fs.chmodSync) {
+    const outcomes = [];
+    const seen = new Set();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, "prebuilds"));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const helper = path.join(root, "prebuilds", entry, "spawn-helper");
+            if (seen.has(helper))
+                continue;
+            seen.add(helper);
+            try {
+                if (!fs.existsSync(helper))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            try {
+                chmod(helper, 0o755);
+                outcomes.push({ helper, ok: true });
+            }
+            catch (e) {
+                outcomes.push({ helper, ok: false, error: String(e?.message ?? e) });
+            }
+        }
+    }
+    return outcomes;
+}
+/**
+ * Human diagnostic for failed repairs, or null when nothing failed.
+ * Load-bearing for root-owned trees (e.g. `sudo` global installs) where the
+ * invoking user cannot repair: without it the failure would go opaque again.
+ */
+export function describeSpawnHelperRepairs(outcomes) {
+    const failed = outcomes.filter((o) => !o.ok);
+    if (failed.length === 0)
+        return null;
+    const lines = failed.map((o) => `could not make ${o.helper} executable (${o.error ?? "unknown error"})`);
+    return (`${lines.join("; ")} — the install tree is likely root-owned (e.g. installed with sudo); ` +
+        `reinstall without sudo or fix the install's ownership so the invoking user can write it`);
+}
+function nodePtyPackageRoot(resolvedEntry) {
+    const dir = path.dirname(resolvedEntry);
+    // node-pty's main entry is lib/index.js; the package root is two levels up.
+    if (path.basename(dir) === "lib" && /^index\.[cm]?js$/.test(path.basename(resolvedEntry))) {
+        return path.dirname(dir);
+    }
+    return dir;
+}
 let ptyMod = null;
 function getPty() {
     if (ptyMod)
         return ptyMod;
-    try {
-        const require = createRequire(import.meta.url);
-        ptyMod = require("node-pty");
-        if (ptyMod?.spawn)
-            return ptyMod;
-    }
-    catch { }
     // Compiled binary (bun --compile) has no node_modules; try sidecar locations
     const execDir = path.dirname(process.execPath);
     const platformArch = `${process.platform}-${process.arch}`;
@@ -40,6 +140,29 @@ function getPty() {
         path.join(os.homedir(), ".local", "share", "quotacap", "pty", platformArch, "node-pty"),
         path.join(os.homedir(), ".quotacap", "pty", "node-pty"),
     ];
+    // Best-effort +x before requiring: the resolvable npm root (when present)
+    // plus every existing sidecar root. Successful repairs stay silent.
+    const repairRoots = [];
+    try {
+        const require0 = createRequire(import.meta.url);
+        repairRoots.push(nodePtyPackageRoot(require0.resolve("node-pty")));
+    }
+    catch { }
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c))
+                repairRoots.push(c);
+        }
+        catch { }
+    }
+    const repairs = repairSpawnHelpers(repairRoots);
+    try {
+        const require = createRequire(import.meta.url);
+        ptyMod = require("node-pty");
+        if (ptyMod?.spawn)
+            return ptyMod;
+    }
+    catch { }
     for (const c of candidates) {
         try {
             if (!fs.existsSync(c))
@@ -65,7 +188,9 @@ function getPty() {
         }
         catch { }
     }
-    throw new Error("pty: node-pty not available — install with build tools (Xcode on macOS, build-essential + python3 on Linux) or use exec-based adapters only; for compiled binaries, ensure the pty sidecar is installed alongside the binary (see install.sh)");
+    const repairNote = describeSpawnHelperRepairs(repairs);
+    throw diagnosticError(new Error("pty: node-pty not available — install with build tools (Xcode on macOS, build-essential + python3 on Linux) or use exec-based adapters only; for compiled binaries, ensure the pty sidecar is installed alongside the binary (see install.sh)" +
+        (repairNote ? `; ${repairNote}` : "")), { source: "pty" });
 }
 function isBunRuntime() {
     return typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.spawn === "function";
@@ -76,9 +201,9 @@ async function runPtyBun(opts) {
     const rows = opts.rows ?? 50;
     const readyTimeoutMs = opts.readyTimeoutMs ?? 6000;
     if (opts.timeoutMs <= 0)
-        throw new Error("pty: timeoutMs must be > 0");
+        throw diagnosticError(new Error("pty: timeoutMs must be > 0"), { source: "pty" });
     if (opts.signal?.aborted)
-        throw new Error("pty aborted");
+        throw diagnosticError(new Error("pty aborted"), { source: "pty", checkpoint: "abort" });
     let aborted = false;
     const onAbort = () => {
         aborted = true;
@@ -87,7 +212,7 @@ async function runPtyBun(opts) {
         opts.signal.addEventListener("abort", onAbort, { once: true });
     const checkAborted = () => {
         if (aborted)
-            throw new Error("pty aborted");
+            throw diagnosticError(new Error("pty aborted"), { source: "pty", checkpoint: "abort", stdout: transcript });
     };
     const teardownAbort = () => {
         if (opts.signal)
@@ -97,6 +222,12 @@ async function runPtyBun(opts) {
     let transcript = "";
     let exited = false;
     let exitCode;
+    // Genuine PTY via the Bun.spawn `terminal` option (verified on Bun 1.3.11):
+    // the child's stdin, stdout, and stderr are all the PTY slave, input goes
+    // through proc.terminal.write, and merged output arrives in `data`.
+    // proc.stdin/stdout/stderr are null in this mode.
+    const decoder = new TextDecoder();
+    let feedQueries = null;
     const proc = BunGlobal.spawn([opts.file, ...(opts.args ?? [])], {
         cwd: opts.cwd ?? process.cwd(),
         env: {
@@ -104,25 +235,36 @@ async function runPtyBun(opts) {
             ...(opts.env ?? {}),
             TERM: "xterm-256color",
         },
-        stdin: "pipe",
-        pty: { cols, rows },
+        terminal: {
+            cols,
+            rows,
+            data(_term, chunk) {
+                try {
+                    const text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+                    transcript += text;
+                    feedQueries?.(text);
+                }
+                catch { }
+            },
+        },
     });
-    // Capture stdout (pty merges stdout+stderr)
-    const decoder = new TextDecoder();
-    const reader = proc.stdout.getReader();
-    let reading = true;
-    const readLoop = (async () => {
+    if (!proc.terminal) {
+        // Old Bun runtimes silently ignore the unknown `terminal` option, so an
+        // absent proc.terminal is the fail-loud signal — never run half-attached.
         try {
-            while (reading) {
-                const { value, done } = await reader.read();
-                if (done)
-                    break;
-                if (value)
-                    transcript += decoder.decode(value);
-            }
+            proc.kill();
         }
         catch { }
-    })();
+        throw diagnosticError(new Error("pty: Bun runtime lacks terminal (PTY) support (Bun.spawn terminal option unavailable) — rebuild the standalone binary with a newer Bun version"), { source: "pty" });
+    }
+    if (opts.respondToQueries) {
+        feedQueries = createTerminalQueryResponder((s) => {
+            try {
+                proc.terminal.write(s);
+            }
+            catch { }
+        });
+    }
     // Poll for exit
     const exitPoll = (async () => {
         try {
@@ -132,14 +274,23 @@ async function runPtyBun(opts) {
         }
         catch { }
     })();
+    void exitPoll;
     const checkCap = () => {
         if (Buffer.byteLength(transcript, "utf8") > maxBytes) {
-            throw new Error(`pty transcript exceeds ${maxBytes} bytes`);
+            throw diagnosticError(new Error(`pty transcript exceeds ${maxBytes} bytes`), {
+                source: "pty",
+                checkpoint: "transcript overflow",
+                stdout: transcript,
+            });
         }
     };
     const checkAbort = (clean) => {
         if (opts.abortOn && regexTest(opts.abortOn, clean)) {
-            throw new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`);
+            throw diagnosticError(new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`), {
+                source: "pty",
+                checkpoint: "trust prompt",
+                stdout: transcript,
+            });
         }
     };
     const kill = async () => {
@@ -169,6 +320,10 @@ async function runPtyBun(opts) {
             proc.kill();
         }
         catch { }
+        try {
+            proc.terminal?.close();
+        }
+        catch { }
     }, opts.label ?? opts.file);
     try {
         if (opts.readyRegex) {
@@ -177,8 +332,14 @@ async function runPtyBun(opts) {
             while (Date.now() < deadline) {
                 checkCap();
                 checkAborted();
-                if (exited)
-                    throw new Error(`pty exited before ready (code ${exitCode})`);
+                if (exited) {
+                    throw diagnosticError(new Error(`pty exited before ready (code ${exitCode})`), {
+                        source: "pty",
+                        checkpoint: "before ready",
+                        exitCode,
+                        stdout: transcript,
+                    });
+                }
                 const clean = stripAnsi(transcript);
                 checkAbort(clean);
                 if (regexTest(opts.readyRegex, clean)) {
@@ -189,13 +350,24 @@ async function runPtyBun(opts) {
             }
             if (!matched) {
                 await kill();
-                throw new Error(`pty ready timeout after ${readyTimeoutMs}ms`);
+                throw diagnosticError(new Error(`pty ready timeout after ${readyTimeoutMs}ms`), {
+                    source: "pty",
+                    checkpoint: "ready timeout",
+                    durationMs: readyTimeoutMs,
+                    stdout: transcript,
+                });
             }
-            await delay(200);
+            await delay(opts.settleDelayMs ?? 200);
             checkCap();
             checkAborted();
-            if (exited)
-                throw new Error(`pty exited before input (code ${exitCode})`);
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "before input",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
             const postReadyClean = stripAnsi(transcript);
             checkAbort(postReadyClean);
         }
@@ -203,20 +375,57 @@ async function runPtyBun(opts) {
             await delay(opts.settleDelayMs);
             checkCap();
             checkAborted();
-            if (exited)
-                throw new Error(`pty exited during settle (code ${exitCode})`);
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited during settle (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "during settle",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
             const c = stripAnsi(transcript);
             checkAbort(c);
         }
-        if (exited)
-            throw new Error(`pty exited before input (code ${exitCode})`);
+        if (exited) {
+            throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                source: "pty",
+                checkpoint: "before input",
+                exitCode,
+                stdout: transcript,
+            });
+        }
         try {
-            proc.stdin.write(opts.input);
-            if (typeof proc.stdin.flush === "function")
-                proc.stdin.flush();
+            proc.terminal.write(opts.input);
         }
         catch (e) {
-            throw new Error(`pty write failed: ${e.message}`);
+            throw diagnosticError(new Error(`pty write failed: ${e.message}`), {
+                source: "pty",
+                checkpoint: "write",
+                stdout: transcript,
+            });
+        }
+        if (opts.submitInput !== undefined && opts.submitAfterMs !== undefined) {
+            await delay(opts.submitAfterMs);
+            checkCap();
+            checkAborted();
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "before input",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
+            try {
+                proc.terminal.write(opts.submitInput);
+            }
+            catch (e) {
+                throw diagnosticError(new Error(`pty write failed: ${e.message}`), {
+                    source: "pty",
+                    checkpoint: "write",
+                    stdout: transcript,
+                });
+            }
         }
         if (opts.completionRegex) {
             const deadline = Date.now() + opts.timeoutMs;
@@ -232,7 +441,12 @@ async function runPtyBun(opts) {
                 }
                 if (exited) {
                     if (!regexTest(opts.completionRegex, clean)) {
-                        throw new Error(`pty exited before completion (code ${exitCode})`);
+                        throw diagnosticError(new Error(`pty exited before completion (code ${exitCode})`), {
+                            source: "pty",
+                            checkpoint: "before completion",
+                            exitCode,
+                            stdout: transcript,
+                        });
                     }
                     done = true;
                     break;
@@ -241,7 +455,12 @@ async function runPtyBun(opts) {
             }
             if (!done) {
                 await kill();
-                throw new Error(`pty completion timeout after ${opts.timeoutMs}ms`);
+                throw diagnosticError(new Error(`pty completion timeout after ${opts.timeoutMs}ms`), {
+                    source: "pty",
+                    checkpoint: "completion timeout",
+                    durationMs: opts.timeoutMs,
+                    stdout: transcript,
+                });
             }
         }
         else {
@@ -257,12 +476,17 @@ async function runPtyBun(opts) {
             }
         }
         await kill();
-        reading = false;
+        // Drain late `data` callbacks, then close the terminal and flush the
+        // streamed decoder before the final checks.
+        await delay(200);
         try {
-            reader.cancel();
+            proc.terminal.close();
+        }
+        catch { }
+        try {
+            transcript += decoder.decode();
         }
         catch { }
-        await Promise.race([readLoop, delay(200)]);
         checkCap();
         checkAborted();
         const finalClean = stripAnsi(transcript);
@@ -272,15 +496,16 @@ async function runPtyBun(opts) {
         return transcript;
     }
     catch (e) {
-        reading = false;
+        await kill();
         try {
-            reader.cancel();
+            proc.terminal.close();
         }
         catch { }
-        await kill();
         unregisterChild();
         teardownAbort();
-        throw e;
+        if (e instanceof DiagnosticError)
+            throw e;
+        throw diagnosticError(e, { source: "pty", stdout: transcript, exitCode });
     }
 }
 async function runPtyNode(opts) {
@@ -289,9 +514,9 @@ async function runPtyNode(opts) {
     const rows = opts.rows ?? 50;
     const readyTimeoutMs = opts.readyTimeoutMs ?? 6000;
     if (opts.timeoutMs <= 0)
-        throw new Error("pty: timeoutMs must be > 0");
+        throw diagnosticError(new Error("pty: timeoutMs must be > 0"), { source: "pty" });
     if (opts.signal?.aborted)
-        throw new Error("pty aborted");
+        throw diagnosticError(new Error("pty aborted"), { source: "pty", checkpoint: "abort" });
     let aborted = false;
     const onAbort = () => {
         aborted = true;
@@ -300,7 +525,7 @@ async function runPtyNode(opts) {
         opts.signal.addEventListener("abort", onAbort, { once: true });
     const checkAborted = () => {
         if (aborted)
-            throw new Error("pty aborted");
+            throw diagnosticError(new Error("pty aborted"), { source: "pty", checkpoint: "abort", stdout: transcript });
     };
     const teardownAbort = () => {
         if (opts.signal)
@@ -325,7 +550,10 @@ async function runPtyNode(opts) {
         });
     }
     catch (e) {
-        throw new Error(`pty spawn failed for ${opts.file}: ${e.message}`);
+        throw diagnosticError(new Error(`pty spawn failed for ${opts.file}: ${e.message}`), {
+            source: "pty",
+            checkpoint: "spawn",
+        });
     }
     const unregisterChild = registerTrackedChild(() => {
         try {
@@ -333,9 +561,21 @@ async function runPtyNode(opts) {
         }
         catch { }
     }, opts.label ?? opts.file);
+    const feedQueries = opts.respondToQueries
+        ? createTerminalQueryResponder((s) => {
+            try {
+                ptyProcess.write(s);
+            }
+            catch { }
+        })
+        : null;
     const disposables = [];
     disposables.push(ptyProcess.onData((data) => {
         transcript += data;
+        try {
+            feedQueries?.(data);
+        }
+        catch { }
     }));
     disposables.push(ptyProcess.onExit(({ exitCode: c }) => {
         exited = true;
@@ -373,12 +613,20 @@ async function runPtyNode(opts) {
     };
     const checkCap = () => {
         if (Buffer.byteLength(transcript, "utf8") > maxBytes) {
-            throw new Error(`pty transcript exceeds ${maxBytes} bytes`);
+            throw diagnosticError(new Error(`pty transcript exceeds ${maxBytes} bytes`), {
+                source: "pty",
+                checkpoint: "transcript overflow",
+                stdout: transcript,
+            });
         }
     };
     const checkAbort = (clean) => {
         if (opts.abortOn && regexTest(opts.abortOn, clean)) {
-            throw new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`);
+            throw diagnosticError(new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`), {
+                source: "pty",
+                checkpoint: "trust prompt",
+                stdout: transcript,
+            });
         }
     };
     try {
@@ -388,8 +636,14 @@ async function runPtyNode(opts) {
             while (Date.now() < deadline) {
                 checkCap();
                 checkAborted();
-                if (exited)
-                    throw new Error(`pty exited before ready (code ${exitCode})`);
+                if (exited) {
+                    throw diagnosticError(new Error(`pty exited before ready (code ${exitCode})`), {
+                        source: "pty",
+                        checkpoint: "before ready",
+                        exitCode,
+                        stdout: transcript,
+                    });
+                }
                 const clean = stripAnsi(transcript);
                 checkAbort(clean);
                 if (regexTest(opts.readyRegex, clean)) {
@@ -400,13 +654,24 @@ async function runPtyNode(opts) {
             }
             if (!matched) {
                 await kill();
-                throw new Error(`pty ready timeout after ${readyTimeoutMs}ms`);
+                throw diagnosticError(new Error(`pty ready timeout after ${readyTimeoutMs}ms`), {
+                    source: "pty",
+                    checkpoint: "ready timeout",
+                    durationMs: readyTimeoutMs,
+                    stdout: transcript,
+                });
             }
-            await delay(200);
+            await delay(opts.settleDelayMs ?? 200);
             checkCap();
             checkAborted();
-            if (exited)
-                throw new Error(`pty exited before input (code ${exitCode})`);
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "before input",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
             const postReadyClean = stripAnsi(transcript);
             checkAbort(postReadyClean);
         }
@@ -414,14 +679,58 @@ async function runPtyNode(opts) {
             await delay(opts.settleDelayMs);
             checkCap();
             checkAborted();
-            if (exited)
-                throw new Error(`pty exited during settle (code ${exitCode})`);
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited during settle (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "during settle",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
             const c = stripAnsi(transcript);
             checkAbort(c);
         }
-        if (exited)
-            throw new Error(`pty exited before input (code ${exitCode})`);
-        ptyProcess.write(opts.input);
+        if (exited) {
+            throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                source: "pty",
+                checkpoint: "before input",
+                exitCode,
+                stdout: transcript,
+            });
+        }
+        try {
+            ptyProcess.write(opts.input);
+        }
+        catch (e) {
+            throw diagnosticError(new Error(`pty write failed: ${e.message}`), {
+                source: "pty",
+                checkpoint: "write",
+                stdout: transcript,
+            });
+        }
+        if (opts.submitInput !== undefined && opts.submitAfterMs !== undefined) {
+            await delay(opts.submitAfterMs);
+            checkCap();
+            checkAborted();
+            if (exited) {
+                throw diagnosticError(new Error(`pty exited before input (code ${exitCode})`), {
+                    source: "pty",
+                    checkpoint: "before input",
+                    exitCode,
+                    stdout: transcript,
+                });
+            }
+            try {
+                ptyProcess.write(opts.submitInput);
+            }
+            catch (e) {
+                throw diagnosticError(new Error(`pty write failed: ${e.message}`), {
+                    source: "pty",
+                    checkpoint: "write",
+                    stdout: transcript,
+                });
+            }
+        }
         if (opts.completionRegex) {
             const deadline = Date.now() + opts.timeoutMs;
             let done = false;
@@ -436,7 +745,12 @@ async function runPtyNode(opts) {
                 }
                 if (exited) {
                     if (!regexTest(opts.completionRegex, clean)) {
-                        throw new Error(`pty exited before completion (code ${exitCode})`);
+                        throw diagnosticError(new Error(`pty exited before completion (code ${exitCode})`), {
+                            source: "pty",
+                            checkpoint: "before completion",
+                            exitCode,
+                            stdout: transcript,
+                        });
                     }
                     done = true;
                     break;
@@ -445,7 +759,12 @@ async function runPtyNode(opts) {
             }
             if (!done) {
                 await kill();
-                throw new Error(`pty completion timeout after ${opts.timeoutMs}ms`);
+                throw diagnosticError(new Error(`pty completion timeout after ${opts.timeoutMs}ms`), {
+                    source: "pty",
+                    checkpoint: "completion timeout",
+                    durationMs: opts.timeoutMs,
+                    stdout: transcript,
+                });
             }
         }
         else {
@@ -471,7 +790,9 @@ async function runPtyNode(opts) {
     }
     catch (e) {
         await kill();
-        throw e;
+        if (e instanceof DiagnosticError)
+            throw e;
+        throw diagnosticError(e, { source: "pty", stdout: transcript, exitCode });
     }
     finally {
         cleanup();
@@ -480,8 +801,15 @@ async function runPtyNode(opts) {
     }
 }
 export async function runPty(opts) {
-    if (isBunRuntime()) {
-        return runPtyBun(opts);
+    try {
+        if (isBunRuntime()) {
+            return await runPtyBun(opts);
+        }
+        return await runPtyNode(opts);
+    }
+    catch (e) {
+        if (e instanceof DiagnosticError)
+            throw e;
+        throw diagnosticError(e, { source: "pty" });
     }
-    return runPtyNode(opts);
 }