@expitc/termad 0.1.2 → 0.1.3

package/assets/pty-overlay.mjs

@@ -1,5 +1,54 @@
 #!/usr/bin/env node
-import { runWithAdOverlay } from "@expitc/termad/dist/surfaces/pty-inject.js";
+/**
+ * Launcher for the PTY overlay.
+ *
+ * Must work from any install layout:
+ *   <pkg>/dist/assets/pty-overlay.mjs   (published package, global install)
+ *   <pkg>/src/assets/pty-overlay.mjs    (running from source)
+ *   ~/.termad/pty-overlay.mjs            (written by `termad install`)
+ *
+ * Resolves pty-inject.js relative to itself first, then by package name.
+ * If nothing resolves, exit non-zero WITHOUT touching the CLI — the
+ * wrapper's own pre-banner fallback takes over and the CLI still runs.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const candidates = [
+  join(here, "..", "surfaces", "pty-inject.js"), // dist/assets → dist/surfaces
+  join(here, "surfaces", "pty-inject.js"), // src/assets → src/surfaces
+];
+
+let runWithAdOverlay = null;
+
+for (const c of candidates) {
+  if (!existsSync(c)) continue;
+  try {
+    ({ runWithAdOverlay } = await import(pathToFileURL(c).href));
+    break;
+  } catch {}
+}
+
+if (!runWithAdOverlay) {
+  try {
+    ({ runWithAdOverlay } = await import("@expitc/termad/dist/surfaces/pty-inject.js"));
+  } catch {}
+}
+
+if (typeof runWithAdOverlay !== "function") {
+  console.error("termad: pty-inject.js not found — falling back to banner mode");
+  process.exit(1);
+}
+
 const binary = process.argv[2];
 const args = process.argv.slice(3);
-runWithAdOverlay(binary, args);
+
+if (!binary) {
+  console.error("termad: usage: pty-overlay.mjs <binary> [args...]");
+  process.exit(1);
+}
+
+await runWithAdOverlay(binary, args);

package/assets/wrapper.sh.overlay

@@ -9,13 +9,13 @@
 TERMAD_AD_FILE="__TERMAD_AD__"
 TERMAD_BACKUP="__TERMAD_BACKUP__"
 TERMAD_COUNT="__TERMAD_COUNT__"
-TERMAD_HOME_DIR="$(dirname "$(dirname "$TERMAD_AD_FILE")")"
+TERMAD_HOME_DIR="$(dirname "$TERMAD_AD_FILE")"
 
 # Try PTY overlay via node script bundled with termad
 OVERLAY_SCRIPT="$TERMAD_HOME_DIR/pty-overlay.mjs"
 if [ ! -f "$OVERLAY_SCRIPT" ]; then
   # Try to find in node_modules or global install
-  OVERLAY_SCRIPT="$(npm root -g 2>/dev/null)/@expitc/termad/dist/surfaces/pty-inject.mjs"
+  OVERLAY_SCRIPT="$(npm root -g 2>/dev/null)/@expitc/termad/dist/assets/pty-overlay.mjs"
 fi
 
 if [ -f "$OVERLAY_SCRIPT" ] && command -v node >/dev/null 2>&1; then

package/dist/assets/pty-overlay.mjs

@@ -1,5 +1,54 @@
 #!/usr/bin/env node
-import { runWithAdOverlay } from "@expitc/termad/dist/surfaces/pty-inject.js";
+/**
+ * Launcher for the PTY overlay.
+ *
+ * Must work from any install layout:
+ *   <pkg>/dist/assets/pty-overlay.mjs   (published package, global install)
+ *   <pkg>/src/assets/pty-overlay.mjs    (running from source)
+ *   ~/.termad/pty-overlay.mjs            (written by `termad install`)
+ *
+ * Resolves pty-inject.js relative to itself first, then by package name.
+ * If nothing resolves, exit non-zero WITHOUT touching the CLI — the
+ * wrapper's own pre-banner fallback takes over and the CLI still runs.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const candidates = [
+  join(here, "..", "surfaces", "pty-inject.js"), // dist/assets → dist/surfaces
+  join(here, "surfaces", "pty-inject.js"), // src/assets → src/surfaces
+];
+
+let runWithAdOverlay = null;
+
+for (const c of candidates) {
+  if (!existsSync(c)) continue;
+  try {
+    ({ runWithAdOverlay } = await import(pathToFileURL(c).href));
+    break;
+  } catch {}
+}
+
+if (!runWithAdOverlay) {
+  try {
+    ({ runWithAdOverlay } = await import("@expitc/termad/dist/surfaces/pty-inject.js"));
+  } catch {}
+}
+
+if (typeof runWithAdOverlay !== "function") {
+  console.error("termad: pty-inject.js not found — falling back to banner mode");
+  process.exit(1);
+}
+
 const binary = process.argv[2];
 const args = process.argv.slice(3);
-runWithAdOverlay(binary, args);
+
+if (!binary) {
+  console.error("termad: usage: pty-overlay.mjs <binary> [args...]");
+  process.exit(1);
+}
+
+await runWithAdOverlay(binary, args);

package/dist/assets/wrapper.sh.overlay

@@ -9,13 +9,13 @@
 TERMAD_AD_FILE="__TERMAD_AD__"
 TERMAD_BACKUP="__TERMAD_BACKUP__"
 TERMAD_COUNT="__TERMAD_COUNT__"
-TERMAD_HOME_DIR="$(dirname "$(dirname "$TERMAD_AD_FILE")")"
+TERMAD_HOME_DIR="$(dirname "$TERMAD_AD_FILE")"
 
 # Try PTY overlay via node script bundled with termad
 OVERLAY_SCRIPT="$TERMAD_HOME_DIR/pty-overlay.mjs"
 if [ ! -f "$OVERLAY_SCRIPT" ]; then
   # Try to find in node_modules or global install
-  OVERLAY_SCRIPT="$(npm root -g 2>/dev/null)/@expitc/termad/dist/surfaces/pty-inject.mjs"
+  OVERLAY_SCRIPT="$(npm root -g 2>/dev/null)/@expitc/termad/dist/assets/pty-overlay.mjs"
 fi
 
 if [ -f "$OVERLAY_SCRIPT" ] && command -v node >/dev/null 2>&1; then

package/dist/core/paths.d.ts

@@ -6,6 +6,8 @@ export declare const paths: {
     adCache: () => string;
     /** Claude statusline launcher installed into ~/.claude/settings.json. */
     statuslineScript: () => string;
+    /** PTY overlay launcher the shell wrappers exec. Written by `termad install`. */
+    ptyOverlay: () => string;
     /** Captured pre-install statusLine (chain capture, like claude does natively). */
     prevStatusline: () => string;
     log: () => string;
@@ -22,3 +24,10 @@ export declare const paths: {
 export declare function backupPath(target: string): string;
 export declare const WRAPPER_MARKER = "===== TERMAD-CLI =====";
 export declare const OVERLAY_MARKER = "===== TERMAD-OVERLAY =====";
+/** Every marker termad can write into a wrapped target.
+ *  A target is termad's own if it carries ANY of them — checking only one
+ *  makes overlay-wrapped binaries look untouched, which breaks uninstall
+ *  (the original backup gets discarded) and misreports audit status. */
+export declare const WRAPPER_MARKERS: readonly ["===== TERMAD-CLI =====", "===== TERMAD-OVERLAY ====="];
+/** True if the content carries any termad wrapper marker. */
+export declare function hasWrapperMarker(content: string): boolean;

package/dist/core/paths.js

@@ -10,6 +10,8 @@ export const paths = {
     adCache: () => join(termadHome(), "ad.txt"),
     /** Claude statusline launcher installed into ~/.claude/settings.json. */
     statuslineScript: () => join(termadHome(), "statusline.mjs"),
+    /** PTY overlay launcher the shell wrappers exec. Written by `termad install`. */
+    ptyOverlay: () => join(termadHome(), "pty-overlay.mjs"),
     /** Captured pre-install statusLine (chain capture, like claude does natively). */
     prevStatusline: () => join(termadHome(), "prev-statusline.json"),
     log: () => join(termadHome(), "termad.log"),
@@ -28,3 +30,12 @@ export function backupPath(target) {
 }
 export const WRAPPER_MARKER = "===== TERMAD-CLI =====";
 export const OVERLAY_MARKER = "===== TERMAD-OVERLAY =====";
+/** Every marker termad can write into a wrapped target.
+ *  A target is termad's own if it carries ANY of them — checking only one
+ *  makes overlay-wrapped binaries look untouched, which breaks uninstall
+ *  (the original backup gets discarded) and misreports audit status. */
+export const WRAPPER_MARKERS = [WRAPPER_MARKER, OVERLAY_MARKER];
+/** True if the content carries any termad wrapper marker. */
+export function hasWrapperMarker(content) {
+    return WRAPPER_MARKERS.some((m) => content.includes(m));
+}

package/dist/install.js

@@ -7,7 +7,8 @@
 import { loadConfig, saveConfig, writeFileAtomic } from "./core/config.js";
 import { paths, termadHome, backupPath } from "./core/paths.js";
 import { fetchAd, writeAdCache } from "./core/source.js";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { getSurface } from "./surfaces/surfaces.js";
 import { installWrapper, uninstallWrapper, isWrapped } from "./surfaces/wrap.js";
 import { installStatusline, uninstallStatusline, settingsPath, isStatuslineInstalled } from "./surfaces/statusline.js";
@@ -46,11 +47,47 @@ export function planInstall(surfaces, force = false) {
     }
     return items;
 }
+/** Absolute path to the overlay implementation shipped with THIS install.
+ *  dist/surfaces/pty-inject.js in a published package, src/… when run from
+ *  source. */
+function ptyInjectPath() {
+    const here = dirname(new URL(import.meta.url).pathname);
+    const js = join(here, "surfaces", "pty-inject.js");
+    const ts = join(here, "surfaces", "pty-inject.ts");
+    return existsSync(js) ? js : ts;
+}
+/** Write the overlay launcher into termad home so the wrapper can always
+ *  find it. The absolute path to pty-inject is baked in, which keeps the
+ *  launcher working regardless of how termad itself was installed. */
+function installOverlayLauncher() {
+    const target = paths.ptyOverlay();
+    try {
+        const mod = ptyInjectPath();
+        const body = `#!/usr/bin/env node
+// Written by \`termad install\`. Launches the PTY ad overlay for a CLI binary.
+// Regenerated on every install — safe to edit/delete; termad rewrites it.
+import { pathToFileURL } from "node:url";
+const mod = await import(pathToFileURL(${JSON.stringify(mod)}).href);
+if (typeof mod.runWithAdOverlay !== "function") {
+  console.error("termad: overlay unavailable");
+  process.exit(1);
+}
+await mod.runWithAdOverlay(process.argv[2], process.argv.slice(3));
+`;
+        writeFileSync(target, body);
+        chmodSync(target, 0o755);
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
 /** Fetch the ad, write the cache, then install the opted-in surfaces. */
 export async function install(surfaces, opts = {}) {
     const force = opts.force ?? false;
     const cfg = loadConfig();
     mkdirSync(termadHome(), { recursive: true });
+    installOverlayLauncher();
     const ad = await fetchAd(surfaces?.[0] ?? "claude");
     writeAdCache(ad);
     const wanted = surfaces ?? Object.entries(cfg.surfaces).filter(([, v]) => v).map(([k]) => k);

package/dist/surfaces/inline.js

@@ -13,7 +13,7 @@
  */
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { WRAPPER_MARKER } from "../core/paths.js";
+import { hasWrapperMarker } from "../core/paths.js";
 export const INLINE_MARKER = "===== TERMAD-INLINE =====";
 export const INLINE_BACKUP_EXT = ".termad-bundle-orig";
 export function inlineBackupPath(target) {
@@ -141,7 +141,7 @@ export function installInline(target) {
 function isWrappedCheck(target) {
     try {
         const head = readFileSync(target, "utf8").slice(0, 256);
-        return head.includes(WRAPPER_MARKER);
+        return hasWrapperMarker(head);
     }
     catch {
         return false;

package/dist/surfaces/pty-inject.js

@@ -1,9 +1,10 @@
-import { readFileSync, appendFileSync } from "node:fs";
+import { readFileSync, appendFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const TERMAD_HOME = process.env.TERMAD_HOME || join(homedir(), ".termad");
 const AD_FILE = join(TERMAD_HOME, "ad.txt");
 const COUNT_FILE = join(TERMAD_HOME, "display.log");
+const CONFIG_FILE = join(TERMAD_HOME, "config.json");
 function readAd() {
     try {
         const raw = readFileSync(AD_FILE, "utf8").replace(/\r/g, "").split("\n");
@@ -18,6 +19,17 @@ function readAd() {
         return null;
     }
 }
+function readStyle() {
+    try {
+        if (!existsSync(CONFIG_FILE))
+            return "line";
+        const cfg = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+        return cfg.style === "banner" ? "banner" : "line";
+    }
+    catch {
+        return "line";
+    }
+}
 function count(id) {
     if (!id)
         return;
@@ -26,20 +38,65 @@ function count(id) {
     }
     catch { }
 }
-function buildFooter(ad) {
+function osc8(url, text) {
+    if (!url)
+        return text;
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
+function getDomain(url) {
+    if (!url)
+        return null;
+    try {
+        const u = new URL(url);
+        return u.hostname.replace(/^www\./, "");
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, Math.max(0, n - 3)) + "...";
+}
+function buildFooter(ad, style, width, offset = 0) {
     const label = "\x1b[2m\x1b[33m[ad]\x1b[0m";
-    const text = ad.text.length > 80 ? ad.text.slice(0, 77) + "..." : ad.text;
-    const url = ad.url && ad.url.length > 60 ? ad.url.slice(0, 57) + "..." : ad.url;
-    let line = ` ${label}  ${text}`;
-    if (url)
-        line += `  \x1b[36m${url}\x1b[0m`;
+    const domain = getDomain(ad.url);
+    const w = Math.max(40, width - 4);
+    if (style === "banner") {
+        // Boxed style like Kickbacks
+        const innerW = Math.max(30, w - 2);
+        let displayText = ad.text;
+        // Marquee for long text
+        if (displayText.length > innerW - 20) {
+            const padded = displayText + "   •   " + displayText;
+            const start = offset % displayText.length;
+            displayText = padded.slice(start, start + innerW - 25);
+        }
+        const linkText = domain || ad.url;
+        const linked = ad.url ? osc8(ad.url, `\x1b[36m${truncate(linkText, 30)}\x1b[0m`) : "";
+        const content = ` ${label} ${truncate(displayText, innerW - 15)}${linked ? "  " + linked : ""}`;
+        const padded = content + " ".repeat(Math.max(0, innerW - content.replace(/\x1b\[[0-9;]*m/g, "").length));
+        return `\x1b[90m┌${"─".repeat(innerW)}┐\x1b[0m\n\x1b[90m│\x1b[0m${padded}\x1b[90m│\x1b[0m\n\x1b[90m└${"─".repeat(innerW)}┘\x1b[0m`;
+    }
+    // Line style (minimal, clean)
+    let displayText = ad.text;
+    if (displayText.length > w - 40) {
+        const padded = displayText + "     ";
+        const start = offset % (displayText.length + 5);
+        displayText = padded.slice(start, start + w - 45);
+    }
+    const linkText = domain ? `\x1b[2m•\x1b[0m \x1b[36m${domain}\x1b[0m` : (ad.url ? `\x1b[2m•\x1b[0m \x1b[36m${truncate(ad.url, 40)}\x1b[0m` : "");
+    const linked = ad.url ? osc8(ad.url, linkText) : linkText;
+    let line = ` ${label}  ${truncate(displayText, w - 35)}`;
+    if (linked)
+        line += `  ${linked}`;
     return line;
 }
 export function runWithAdOverlay(binary, args = []) {
     return runWithAdOverlayAsync(binary, args);
 }
 async function runWithAdOverlayAsync(binary, args = []) {
-    // Try to use node-pty if available
     let pty;
     try {
         // @ts-ignore
@@ -53,12 +110,11 @@ async function runWithAdOverlayAsync(binary, args = []) {
         catch { }
     }
     if (!pty) {
-        // No PTY available - fall back to printing banner then execing
         const ad = readAd();
         if (ad) {
-            process.stdout.write("\n  [ad]  " + ad.text + "\n");
-            if (ad.url)
-                process.stdout.write("  " + ad.url + "\n\n");
+            const style = readStyle();
+            const width = process.stdout.columns || 120;
+            console.log(buildFooter(ad, style, width).replace(/\n/g, "\n"));
             count(ad.id);
         }
         const { spawn } = await import("node:child_process");
@@ -71,6 +127,7 @@ async function runWithAdOverlayAsync(binary, args = []) {
         count(ad.id);
     const cols = process.stdout.columns || 120;
     const rows = process.stdout.rows || 40;
+    const style = readStyle();
     const ptyProcess = pty.spawn(binary, args, {
         name: "xterm-256color",
         cols,
@@ -80,32 +137,46 @@ async function runWithAdOverlayAsync(binary, args = []) {
     });
     let footerVisible = !!ad;
     let lastAd = ad;
+    let marqueeOffset = 0;
     function drawFooter() {
         if (!footerVisible || !lastAd)
             return;
-        const footer = buildFooter(lastAd);
-        // Move to bottom row, clear line, print footer
+        const width = process.stdout.columns || cols;
         const termRows = ptyProcess.rows || rows;
-        process.stdout.write(`\x1b[s\x1b[${termRows};1H\x1b[2K${footer}\x1b[u`);
+        const footer = buildFooter(lastAd, style, width, marqueeOffset);
+        marqueeOffset++;
+        if (style === "banner") {
+            // Draw 3 lines for boxed
+            process.stdout.write(`\x1b[s\x1b[${termRows - 2};1H\x1b[2K${footer.split('\n')[0]}\x1b[u`);
+            process.stdout.write(`\x1b[s\x1b[${termRows - 1};1H\x1b[2K${footer.split('\n')[1]}\x1b[u`);
+            process.stdout.write(`\x1b[s\x1b[${termRows};1H\x1b[2K${footer.split('\n')[2]}\x1b[u`);
+        }
+        else {
+            process.stdout.write(`\x1b[s\x1b[${termRows};1H\x1b[2K${footer}\x1b[u`);
+        }
     }
     function hideFooter() {
         const termRows = ptyProcess.rows || rows;
-        process.stdout.write(`\x1b[s\x1b[${termRows};1H\x1b[2K\x1b[u`);
+        if (style === "banner") {
+            process.stdout.write(`\x1b[s\x1b[${termRows - 2};1H\x1b[2K\x1b[${termRows - 1};1H\x1b[2K\x1b[${termRows};1H\x1b[2K\x1b[u`);
+        }
+        else {
+            process.stdout.write(`\x1b[s\x1b[${termRows};1H\x1b[2K\x1b[u`);
+        }
     }
-    // Pipe PTY output to stdout with footer redrawn after each chunk
     ptyProcess.onData((data) => {
         process.stdout.write(data);
-        // Redraw footer after a short delay to stay on top
-        setTimeout(drawFooter, 10);
+        setTimeout(drawFooter, 15);
     });
-    // Pipe stdin to PTY
     if (process.stdin.isTTY) {
-        process.stdin.setRawMode(true);
+        try {
+            process.stdin.setRawMode(true);
+        }
+        catch { }
     }
     process.stdin.on("data", (data) => {
         ptyProcess.write(data);
     });
-    // Handle resize
     process.stdout.on("resize", () => {
         const c = process.stdout.columns || cols;
         const r = process.stdout.rows || rows;
@@ -115,7 +186,6 @@ async function runWithAdOverlayAsync(binary, args = []) {
         catch { }
         setTimeout(drawFooter, 50);
     });
-    // Handle exit
     ptyProcess.onExit(({ exitCode }) => {
         if (process.stdin.isTTY) {
             try {
@@ -127,7 +197,6 @@ async function runWithAdOverlayAsync(binary, args = []) {
         hideFooter();
         process.exit(exitCode ?? 0);
     });
-    // Initial draw
-    setTimeout(drawFooter, 100);
-    setInterval(drawFooter, 500); // Keep footer visible on redraws
+    setTimeout(drawFooter, 150);
+    setInterval(drawFooter, style === "banner" ? 800 : 1000);
 }

package/dist/surfaces/wrap.js

@@ -8,7 +8,7 @@
 import { chmodSync, copyFileSync, existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { homedir } from "node:os";
-import { WRAPPER_MARKER, backupPath, paths } from "../core/paths.js";
+import { hasWrapperMarker, backupPath, paths } from "../core/paths.js";
 const SH_TEMPLATE_OVERLAY = "wrapper.sh.overlay";
 const SH_TEMPLATE = "wrapper.sh.asset";
 const CMD_TEMPLATE = "wrapper.cmd.asset";
@@ -21,7 +21,10 @@ function templatePath(isWin, useOverlay = true) {
 }
 export function isWrapped(target) {
     try {
-        return readFileSync(target, "utf8").includes(WRAPPER_MARKER);
+        // Any termad marker counts — the overlay variant is just as much
+        // "ours" as the plain wrapper. Missing it makes uninstall discard the
+        // pristine backup and leaves the shim behind.
+        return hasWrapperMarker(readFileSync(target, "utf8"));
     }
     catch {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expitc/termad",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Opt-in, fully reversible text ads for terminal AI CLIs (claude, codex, opencode, gemini). Consent-first, tamper-evident audit, 50% runner revenue share.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "assets",
+    "scripts/ensure-pty-helper.mjs",
     "README.md",
     "POLICY.md",
     "LICENSE"
@@ -39,6 +40,7 @@
     "build": "tsc && node scripts/copy-assets.mjs",
     "dev": "tsc --watch",
     "server": "node server/server.mjs",
+    "postinstall": "node scripts/ensure-pty-helper.mjs || exit 0",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -47,5 +49,11 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "allowScripts": {
+    "node-pty@1.1.0": true
   }
 }

package/scripts/ensure-pty-helper.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * node-pty ships its prebuilt `spawn-helper` (the tiny helper that opens the
+ * pty) inside the npm tarball WITHOUT the executable bit, and npm >= 11
+ * blocks dependency install scripts by default — so the helper is never
+ * rebuilt and never made executable. The result is a confusing
+ * "posix_spawnp failed" error and a silent downgrade to banner mode.
+ *
+ * This postinstall just fixes the mode. It is a no-op if the helper is
+ * already executable, and a no-op if node-pty is not installed at all
+ * (it is an optional dependency).
+ */
+import { chmodSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+function findHelper() {
+  let root;
+  try {
+    root = join(require.resolve("node-pty/package.json"), "..");
+  } catch {
+    return null;
+  }
+  const candidates = [
+    join(root, "build", "Release", "spawn-helper"),
+    join(root, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper"),
+  ];
+  return candidates.find((c) => existsSync(c)) ?? null;
+}
+
+const helper = findHelper();
+if (!helper) process.exit(0);
+
+try {
+  const mode = statSync(helper).mode & 0o777;
+  if (mode & 0o111) process.exit(0); // already executable
+  chmodSync(helper, 0o755);
+  console.log("termad: made node-pty spawn-helper executable");
+} catch (e) {
+  // Non-fatal — the overlay degrades to banner mode.
+  console.log(`termad: could not make node-pty spawn-helper executable: ${e.message}`);
+}