moshcode 0.73.0 → 0.75.0

package/README.md

@@ -762,15 +762,50 @@ newer, and re-running `moshcode install alchemy` is its upgrade path.
 Where CoinPay is the payments product MoshCode ships alongside, Alchemy is the
 read side of the same world — the chain itself rather than one wallet's ledger.
 
+### yt-dlp, ffmpeg, ImageMagick — the media toolchain
+
+```sh
+moshcode install yt-dlp           # static binary → ~/.local/bin
+moshcode install ffmpeg           # your distro's package manager (needs sudo)
+moshcode install imagemagick      # likewise
+
+moshcode yt-dlp https://…         # or `dl https://…` from cli-tools
+moshcode ffmpeg -i in.mkv out.mp4
+```
+
+The odd three out: not workflow CLIs, but the media toolchain the rest of the
+roster is built on. `cli-tools` fronts all three — `dl` for yt-dlp, `vid` for
+ffmpeg, `img` for ImageMagick — and every one of them used to answer a missing
+binary by telling you to go and install a system package by hand. Now the
+registry that installs `cli-tools` installs what it runs on.
+
+**yt-dlp** comes from its own releases as a self-contained binary, so it needs
+no python and no package manager. That is deliberate rather than convenient:
+extractors break whenever a site changes its markup, upstream ships a fix within
+days, and a distro package of yt-dlp is frozen for the life of a release. Its
+upgrade is `yt-dlp -U`, the project's own updater.
+
+**ffmpeg** and **ImageMagick** exist only as distro packages — no vendor script,
+and the static rebuilds floating around are unsigned third-party redistributions
+of somebody else's codec stack, on the two tools most likely to be pointed at a
+file from the internet. So they go through `apt`/`dnf`/`zypper`/`pacman`/`apk`,
+or Homebrew on macOS, and ask for sudo everywhere but a Mac (see below).
+Re-running the install upgrades them.
+
+ImageMagick answers to two names: `magick` on version 7, `convert` on 6, both
+current across supported distros under the same package name. MoshCode looks for
+either, so a good install is never reported missing.
+
 `gh`, `supabase`, and `doctl` publish no cross-platform install script, so
 MoshCode resolves the latest GitHub release and drops the binary in
 `$MOSHCODE_BIN` (default `~/.local/bin`) — no sudo, no package manager. Set
 `MOSHCODE_BIN` to install elsewhere.
 
-`tailscale` and `spinifex` are the exceptions: both install system services
-rather than a user-local binary, so their official installers go through the
-distro's package manager and will ask for sudo (tailscale on macOS delegates to
-the App Store instead; Spinifex has no macOS build at all).
+`tailscale`, `spinifex`, `ffmpeg` and `imagemagick` are the exceptions: none of
+them is a user-local binary, so they go through the distro's package manager and
+will ask for sudo (tailscale on macOS delegates to the App Store, and `ffmpeg`
+and `imagemagick` to Homebrew, which refuses to run as root — so neither is
+prompted for a password on a Mac; Spinifex has no macOS build at all).
 
 MoshCode asks for that password **before** starting the work rather than letting
 the installer stop for it partway through — which matters most in `moshcode
@@ -1144,12 +1179,35 @@ What syncs is an allowlist, not a directory walk:
 |---|---|
 | `~/.moshcode/aliases.json` | your pit aliases (`/alias`) |
 | `~/.moshcode/herd/rules.json` | herd state-detection overrides |
+| `~/.moshcode/herd/config.json` | herd notification preferences |
+| `~/.moshcode/feeds.opml` | your `tcfeed` rss feeds |
+| `~/.moshcode/news.opml` | `/news` and `/rss` subscriptions |
+| `~/.moshcode/pricing.json` | per-model price overrides for `/cost` |
+| `~/.moshcode/dns-filter/filter.json` | dns filter categories and your allow/block lists |
+| `~/.moshcode/business.json` | clients, teams, rates and invoices |
 
-What never syncs, by name: `credentials.json` (the account token this very
-feature authenticates with), `herd/sessions.json` (live state pinned to one tmux
-server), `sync.json`, and the `pkg/` binary cache. Engine configuration
-(`~/.claude.json` and friends) is deliberately left alone — those files carry
-provider API keys.
+What never syncs, and why:
+
+| not carried | because |
+|---|---|
+| `credentials.json` | the account token this very feature authenticates with |
+| `herd/sessions.json`, `herd/tasks/`, `*.transcript` | live state, prompt text and full screen captures of your sessions |
+| `dns-filter/stats.json` | it records the last domains you were blocked from reaching |
+| `timers.json` | a running work ledger; two machines appending would lose entries |
+| `news-last.json`, `news-found.json`, `lists/`, `dns-filter/lists/` | caches that refill themselves |
+| `moshpit-dns.pid`, `*.log`, `*.sock` | one box's daemon |
+| `sync.json`, `pkg/` | this feature's own bookkeeping, and moshcode itself |
+
+Engine configuration (`~/.claude.json` and friends) is deliberately left alone —
+those files carry provider API keys. So is `~/.moshcode_history`, which holds
+whatever you typed at the prompt.
+
+Two things worth knowing about the caps. A file over 64 KiB is reported as
+skipped rather than failing the save, so a `business.json` that grew a year of
+invoices stops being carried and says so. And the 256 KiB total is spent in the
+order of the table above, which is why the file most likely to grow is last —
+otherwise it would push your aliases out of the snapshot rather than being
+skipped itself.
 
 Nothing is overwritten quietly:
 
@@ -1164,6 +1222,29 @@ Nothing is overwritten quietly:
 
 Both verbs take `--json`, so a provisioning script can act on the result.
 
+### It also syncs on its own
+
+An open pit runs `/load` then `/save` every five minutes, so the aliases you
+made on the desktop are on the laptop by the time you sit down at it. It is on
+by default and there is nothing to configure.
+
+What makes that safe is that it is never allowed to force. Both refusals above
+still apply to it: a tick that finds a settings file you edited locally leaves
+it alone and pushes it instead, and a tick that finds another machine got there
+first stops and tells you, rather than picking a winner. The order matters —
+loading first is what keeps the ordinary two-machine case from ever becoming a
+conflict you have to resolve by hand.
+
+It is quiet on purpose. Nothing is printed when nothing changed, when you are
+not logged in, or when the network is down. Four things get a line: settings
+arriving from another machine (your aliases just changed under you), a revision
+this machine pushed, a conflict, and a credential the app rejected.
+
+```sh
+MOSHCODE_NO_AUTOSYNC=1 moshcode      # turn it off for this pit
+MOSHCODE_AUTOSYNC_MS=900000 moshcode # every fifteen minutes instead
+```
+
 ## Browser terminal (`moshcode console`)
 
 A real terminal in the browser — arrow keys, history, full-screen TUIs — because

package/bin/moshcode.mjs

@@ -10,6 +10,7 @@ import {
   ENGINES,
   engineStatus,
   openSession,
+  primaryBin,
   resolveEngine,
   resolveExecutable,
   runCmd,
@@ -109,13 +110,15 @@ function printStatus(entries, json = false) {
     console.log(JSON.stringify(entries.map(({ key, desc, bin, installed }) => ({
       name: key,
       description: desc,
-      binary: bin,
+      // One name, even for an entry that answers to several: `binary` is a
+      // documented string in this JSON and something is parsing it.
+      binary: primaryBin(bin),
       installed,
     })), null, 2));
     return;
   }
   for (const entry of entries) {
-    console.log(`${entry.installed ? "●" : "○"} ${entry.key.padEnd(10)} ${entry.desc}`);
+    console.log(`${entry.installed ? "●" : "○"} ${entry.key.padEnd(11)} ${entry.desc}`);
   }
 }
 
@@ -375,7 +378,7 @@ async function main() {
     const r = await openTool(tool, translated.args);
     if (!r.ok) {
       console.error(r.error?.code === "ENOENT"
-        ? `alpaca isn't installed (\`${tool.bin}\`). run: moshcode install alpaca`
+        ? `alpaca isn't installed (\`${primaryBin(tool.bin)}\`). run: moshcode install alpaca`
         : `launch failed: ${r.error?.message || r.error}`);
       process.exitCode = 1;
       return;
@@ -806,7 +809,7 @@ async function main() {
     const r = await openTool(tool, rest);
     if (!r.ok) {
       console.error(r.error?.code === "ENOENT"
-        ? `${key} isn't installed (\`${tool.bin}\`). run: moshcode install ${key}`
+        ? `${key} isn't installed (\`${primaryBin(tool.bin)}\`). run: moshcode install ${key}`
         : `launch failed: ${r.error?.message || r.error}`);
       process.exitCode = 1;
       return;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "moshcode",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
-  "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
+  "description": "moshcode \u2014 a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/moshcoder/moshcode.git"

package/prd/0010-cloud-settings-sync.md

@@ -41,8 +41,13 @@ configuration is already there and already paired with every machine.
 
 ## Non-Goals
 
-- Continuous or background sync. Settings are edited by a person at a moment they
-  can name; a daemon that pushes silently is a daemon that overwrites silently.
+- Background sync that can *overwrite*. This line used to rule out background
+  sync altogether — "a daemon that pushes silently is a daemon that overwrites
+  silently" — and the reasoning was right about the daemon it imagined. R10
+  narrows it rather than dropping it: the pit does sync on its own, and is
+  allowed to because it is never permitted to force. Every refusal in R3 and R4
+  is what makes an unattended tick safe, and a background sync that could pass
+  `--force` would be exactly the thing this line was written to prevent.
 - Syncing engine configuration (`~/.claude.json`, `~/.codex`, MCP registrations).
   Those files carry provider API keys and are owned by other tools' schemas.
 - Syncing machine state: live herd sessions, the package cache, shell history.
@@ -62,9 +67,17 @@ configuration is already there and already paired with every machine.
 
 - R1 [P0] `/save` (and `moshcode save`) uploads this machine's pit settings to the
   logged-in account. `/load` (`moshcode load`) brings them back down.
-- R2 [P0] What syncs is an allowlist, not a directory walk: `aliases.json` and
-  `herd/rules.json` today. `credentials.json`, `herd/sessions.json`, `sync.json`
-  and `pkg/` are named as never-synced and asserted in tests.
+- R2 [P0] What syncs is an allowlist, not a directory walk: the pit's settings
+  (`aliases.json`), herd's (`herd/rules.json`, `herd/config.json`), the feed and
+  news subscriptions, `pricing.json`, the DNS filter's policy, and
+  `business.json`. `~/.moshcode` is also where moshcode installs itself and
+  where the account token lives, so the allowlist is load-bearing rather than
+  tidy. `credentials.json`, `herd/sessions.json`, `sync.json` and `pkg/` are
+  named as never-synced and asserted in tests, alongside the state that is
+  meaningless or private off its own machine: task ledgers and transcripts,
+  `timers.json`, `dns-filter/stats.json` (a list of blocked domains is browsing
+  history), listing caches, and one box's pidfiles and logs. Directory and
+  extension rules are enforced, not only documented.
 - R3 [P0] Each save is a numbered revision. `/save` sends the revision it last
   agreed on and the app refuses the write if the account has moved past it, so
   two machines cannot silently erase one another.
@@ -83,6 +96,16 @@ configuration is already there and already paired with every machine.
 - R9 [P2] Not logged in, session expired, nothing saved yet, conflict: each is a
   sentence naming the command that resolves it (`/login`, `/save`, `/load`,
   `--force`).
+- R10 [P1] The pit syncs on its own every five minutes: `/load` then `/save`, in
+  that order, never with `--force`. Loading first means the ordinary
+  two-machine case settles itself; when `/load` declines because of unsaved
+  local edits, the `/save` behind it carries exactly those edits up, which is
+  the resolution R4 already recommends. It is silent when logged out, silent
+  when nothing changed, and silent about network failure; it speaks only for
+  settings that arrived from another machine, a revision it pushed, and the two
+  states that need a person — a conflict and a rejected credential. On by
+  default. `MOSHCODE_NO_AUTOSYNC` turns it off, `MOSHCODE_AUTOSYNC_MS` retimes
+  it.
 
 ## UX Notes
 

package/src/autosync.mjs

@@ -0,0 +1,175 @@
+// Automatic settings sync — the unattended `/load` then `/save`.
+//
+// PRD 0010 ruled background sync out, and the reason it gave was the right
+// reason for the mechanism it had in mind: "a daemon that pushes silently is a
+// daemon that overwrites silently." What makes this one allowed is that it is
+// not permitted to overwrite anything. It never passes `--force`, and both
+// verbs already refuse rather than guess — `/load` stops when a settings file
+// changed locally since the last sync, `/save` stops on the 409 when another
+// machine saved first. So the worst an unattended tick can do is decline and
+// leave the decision exactly where it was: with the person at the prompt.
+//
+// The order is `/load` then `/save`, and that order is the whole design:
+//
+//   - `/load` first means this machine is at the account's revision before it
+//     pushes, so the ordinary two-machine case settles itself and nobody is
+//     ever shown a conflict they would only have resolved by loading anyway.
+//   - When `/load` declines because there are unsaved local edits, the `/save`
+//     that follows pushes exactly those edits — which is the resolution the
+//     manual conflict message already recommends ("`/save` to keep them").
+//
+// Quiet is a feature. A tick that changed nothing prints nothing, because a
+// line every five minutes saying "still fine" trains you to stop reading the
+// pit. Three things do print: settings that arrived from another machine (your
+// aliases just changed under you and you are owed that sentence), a revision
+// this machine pushed, and the two states that need a human — a conflict, and
+// credentials the app rejected. Network failures stay silent; a laptop on a
+// train would otherwise narrate every tunnel.
+import os from "node:os";
+import { loadCreds } from "./auth.mjs";
+import { loadCommand, saveCommand } from "./settings-sync.mjs";
+
+/** Five minutes. Long enough that a tick is never in the way of typing. */
+export const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+
+/**
+ * A floor, not a suggestion. `MOSHCODE_AUTOSYNC_MS=1` would turn the account
+ * into a write loop, so anything under this is treated as the minimum rather
+ * than refused — an env var is not the place to learn you typed milliseconds
+ * where you meant minutes.
+ */
+export const MIN_INTERVAL_MS = 30 * 1000;
+
+/**
+ * Off switch, in the shape the rest of the codebase already uses for one:
+ * presence disables, exactly like MOSHCODE_NO_MIRROR and MOSHCODE_NO_ADS.
+ */
+export function autoSyncEnabled(env = process.env) {
+  return !env.MOSHCODE_NO_AUTOSYNC;
+}
+
+/** `Number(x) || default`, the MOSHCODE_AD_COLS idiom, with a floor. */
+export function autoSyncInterval(env = process.env) {
+  const raw = Number(env.MOSHCODE_AUTOSYNC_MS);
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_INTERVAL_MS;
+  return Math.max(MIN_INTERVAL_MS, raw);
+}
+
+/**
+ * Run one verb and read its answer as data rather than as prose.
+ *
+ * Both commands take `--json` and emit a single object through their `write`
+ * sink, which is the only reason this can be quiet: it can tell "loaded four
+ * files" from "already at revision 9" without matching on English.
+ */
+async function runJson(command, argv, deps) {
+  const chunks = [];
+  const code = await command([...argv, "--json"], {
+    ...deps,
+    write: (line) => chunks.push(String(line)),
+  });
+  let body = null;
+  try { body = JSON.parse(chunks.join("\n")); } catch { /* not our business */ }
+  return { code, body, status: body?.status ?? null };
+}
+
+/**
+ * One tick: load, then save.
+ *
+ * Returns what happened, so the caller decides what is worth a line and the
+ * tests can assert on the sequence without reading output.
+ */
+export async function syncOnce({
+  load = loadCommand,
+  save = saveCommand,
+  creds = loadCreds(),
+  write = () => {},
+  ...deps
+} = {}) {
+  // Logged out is not an error and must never print. A pit that has never seen
+  // `/login` would otherwise nag about an account its owner has not asked for,
+  // every five minutes, forever.
+  if (!creds?.token) return { skipped: "not_logged_in" };
+
+  const loaded = await runJson(load, [], { ...deps, creds });
+
+  // `local_changes` is the expected, healthy half of this: you edited an alias
+  // and have not saved it. `/load` correctly declined to replace it, and the
+  // `/save` below is what carries it up. Anything else that failed is a reason
+  // to stop rather than push on top of a machine we could not read.
+  const loadBlocked = loaded.status === "expired";
+  if (loadBlocked) {
+    write("the app rejected this machine's credentials — run `/login` again");
+    return { load: loaded.status, save: null };
+  }
+
+  if (loaded.status === "loaded") {
+    const count = Array.isArray(loaded.body?.files) ? loaded.body.files.length : 0;
+    const from = loaded.body?.from;
+    write(`settings synced${from ? ` from ${from}` : ""} — ${count} file${count === 1 ? "" : "s"} changed (revision ${loaded.body?.revision ?? "?"})`);
+  }
+
+  const saved = await runJson(save, [], { ...deps, creds });
+
+  if (saved.status === "saved") {
+    write(`settings saved — revision ${saved.body?.revision ?? "?"}`);
+  } else if (saved.status === "conflict") {
+    // The one case an unattended tick cannot resolve: this machine loaded, and
+    // the account moved again between the load and the save. Say so once and
+    // stop; `--force` is a decision, not a retry.
+    write(`another machine saved first — \`/load\` to take theirs, or \`/save --force\` to keep this machine's`);
+  } else if (saved.status === "expired") {
+    write("the app rejected this machine's credentials — run `/login` again");
+  }
+
+  return { load: loaded.status, save: saved.status };
+}
+
+/**
+ * Start the timer. Returns the function that stops it.
+ *
+ * The caller must call that on the way out: `tui()` is re-entered after an
+ * engine session (bin/moshcode.mjs `backToPit`), so a timer left running would
+ * be joined by another on the next entry, and by a third after that.
+ */
+export function startAutoSync({
+  intervalMs = autoSyncInterval(),
+  enabled = autoSyncEnabled(),
+  write = (line) => console.log(`  ${line}`),
+  timers = { setInterval, clearInterval },
+  ...deps
+} = {}) {
+  if (!enabled) return () => {};
+
+  // A tick that is still running when the next one fires would race two writes
+  // to the same files, so ticks are single-flight rather than queued: a sync
+  // this machine skipped is one it does five minutes later, unchanged.
+  let running = false;
+  let stopped = false;
+
+  const tick = async () => {
+    if (running || stopped) return;
+    running = true;
+    try { await syncOnce({ write, ...deps }); }
+    catch { /* a background sync never takes the pit down with it */ }
+    finally { running = false; }
+  };
+
+  // Deliberately no tick at startup. The pit is most likely to be typed into in
+  // the second after it opens, and that is the worst moment to rewrite the
+  // aliases under it — the first sync can wait five minutes.
+  const handle = timers.setInterval(tick, intervalMs);
+
+  // Never hold the process open for the sake of a sync. `pty.mjs` sets the
+  // precedent: a piped `moshcode` that has run out of stdin should exit now,
+  // not at the end of the interval.
+  handle?.unref?.();
+
+  return () => {
+    stopped = true;
+    try { timers.clearInterval(handle); } catch { /* already gone */ }
+  };
+}
+
+/** Exported for the tests; the pit has no reason to care. */
+export const _internals = { runJson, hostname: os.hostname };

package/src/billing.mjs

@@ -19,6 +19,7 @@ import { spawnSync } from "node:child_process";
 
 import { loadBusiness, loadTimers, newId, updateBusiness, updateTimers } from "./business-store.mjs";
 import { clientLabel, parseFields, resolveClient } from "./clients.mjs";
+import { captureSpec } from "./pty.mjs";
 import { GATEWAYS, defaultGateway, gatewayState } from "./payments.mjs";
 import { chargeFor, describeRate, formatMoney, isDollarPegged, isFiat, rateFor } from "./rates.mjs";
 import { humanDuration, selectEntries, windowFrom } from "./timer.mjs";
@@ -289,7 +290,12 @@ function handOff(record, invoice, business, fields, write, run) {
     return 0;
   }
 
-  const result = run("coinpay", args, { stdio: "inherit" });
+  // Mirrored like every other hand-off: sending an invoice is exactly the kind
+  // of thing you want to read back from the session page afterwards.
+  const launch = captureSpec({ cmd: "coinpay", args });
+  let result;
+  try { result = run(launch.cmd, launch.args, { stdio: "inherit" }); }
+  finally { launch.stop(); }
   if (result?.error) { write(err(String(result.error.message || result.error))); return 1; }
   if (result?.status) { write(err(`coinpay exited ${result.status} — invoice ${record.id} is still a local draft`)); return result.status; }
   updateBusiness((data) => {

package/src/commands.mjs

@@ -22,6 +22,7 @@ import { capture, killSession, remoteStatus, sendPrompt } from "./herd.mjs";
 import { herdStart, isRemoteMember, roster, waitForMany, waitMember } from "./herd-cli.mjs";
 import { endTask, findTask, readTasks, startTask } from "./herd-tasks.mjs";
 import { shellInvocation } from "./shell.mjs";
+import { captureSpec } from "./pty.mjs";
 import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
 import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
 import { CORE_CLI_COMMAND_NAMES, PIT_COMMANDS } from "./cli-schema.mjs";
@@ -116,7 +117,15 @@ const SHELL = {
     // has the reasoning, including why a headless run stays non-interactive.
     const { shell: sh, args: shArgs } = shellInvocation(cmd);
     ctx.out(`  ▶ shell: ${cmd}`);
-    const res = spawnSync(sh, shArgs, { stdio: "inherit" });
+    // Captured for the session mirror like the pit's own `!cmd`. A blocking
+    // spawn holds the event loop, so the follower's poll never runs and the
+    // whole command arrives in the drain stop() does — batched rather than
+    // live, which is still the difference between reading it from a phone and
+    // not.
+    const launch = captureSpec({ cmd: sh, args: shArgs });
+    let res;
+    try { res = spawnSync(launch.cmd, launch.args, { stdio: "inherit" }); }
+    finally { launch.stop(); }
     if (res.error) throw res.error;
     const code = res.status ?? 1;
     if (code !== 0) {

package/src/dns.mjs

@@ -2274,7 +2274,7 @@ import { createParkingServer, DEFAULT_PARKING_HTTP_PORT } from "./parking-http.m
 // use it without importing this one back.
 export { pitNameUrl } from "./pit-url.mjs";
 import { pitNameUrl } from "./pit-url.mjs";
-import { applyTrust, createAutoTrust, trustName, verifyStockTls } from "./trust.mjs";
+import { applyTrust, applyUntrust, createAutoTrust, trustName, verifyStockTls } from "./trust.mjs";
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -2326,6 +2326,9 @@ const USAGE = `moshcode dns — resolve Moshpit names on this machine
   --no-trust   with enable: route names but skip the local CA. They will
                resolve and then fail TLS, which is the state this flag exists
                to leave you in deliberately.
+  --keep-trust with disable: put the routing back but leave the local CA in
+               your trust store. For turning resolution off for an afternoon
+               without paying to install the root again afterwards.
   --no-proxy   with enable: answer each name's origin rather than the local
                pinned-TLS proxy. Only the proxy can hand a stock client a
                certificate it will accept, so this is the other half of the
@@ -2956,6 +2959,14 @@ export async function dnsCommand(args = [], out = console.log, deps = {}) {
         const cleared2 = await applyPlan({ steps: [{ kind: "remove", path: manifestFile, why: "the restore point has been used" }] });
         if (cleared2.ok) out(`  ok   remove ${manifestFile}`);
       }
+
+      // The routing is back, which leaves the trust anchor as the last thing
+      // `enable` did that is still on this machine — and it was the one change
+      // the restore point never covered, because it is not a file in /etc.
+      // Removing it by default is what makes `disable` mean "as it was".
+      // `--keep-trust` is for turning resolution off for an afternoon without
+      // paying for a re-install of the root afterwards.
+      if (!rest.includes("--keep-trust")) await applyUntrust(out, deps);
       out("");
 
       // The line the old implementation printed unconditionally, now only when

package/src/engines.mjs

@@ -32,11 +32,11 @@
 // a session that starts fresh is a small disappointment, and one that starts
 // with a flag the engine does not have is a crash.
 import { spawn } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
 
-import { followFile, ptyEnabled, ptySpec, scriptFlavor, stripScriptBanner } from "./pty.mjs";
+import { captureSpec } from "./pty.mjs";
 
 export const ENGINES = {
   opencode: {
@@ -283,20 +283,36 @@ export function resolveEngine(token) {
 // script unpacks to $HOME/.turso and only appends it to your shell profile).
 // Searching them after PATH keeps a real `turso` on PATH winning, while still
 // finding the one we just installed.
+/**
+ * The name to print when talking about a `bin` that may be several.
+ *
+ * A `bin` is normally one string. ImageMagick is why it can be a list: the
+ * command is `magick` on ImageMagick 7 and `convert` on 6, both are current on
+ * supported distros at the same time, and picking either one alone makes a
+ * successful install report as missing on half of them. The first name is the
+ * one we prefer and the one worth naming in a message.
+ */
+export function primaryBin(bin) {
+  return Array.isArray(bin) ? bin[0] : bin;
+}
+
 function executableCandidates(bin, extraDirs = []) {
   const exts = process.platform === "win32" ? ["", ...(process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";")] : [""];
-  const dirs = path.isAbsolute(bin) || bin.includes(path.sep)
-    ? [""]
-    : [...(process.env.PATH || "").split(path.delimiter).filter(Boolean), ...extraDirs.filter(Boolean)];
+  const names = (Array.isArray(bin) ? bin : [bin]).filter(Boolean);
   const seen = new Set();
   const candidates = [];
-  for (const dir of dirs) {
-    for (const ext of exts) {
-      const candidate = dir ? path.join(dir, bin + ext) : bin + ext;
-      const key = candidate.toLowerCase();
-      if (!seen.has(key)) {
-        seen.add(key);
-        candidates.push(candidate);
+  for (const name of names) {
+    const dirs = path.isAbsolute(name) || name.includes(path.sep)
+      ? [""]
+      : [...(process.env.PATH || "").split(path.delimiter).filter(Boolean), ...extraDirs.filter(Boolean)];
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        const candidate = dir ? path.join(dir, name + ext) : name + ext;
+        const key = candidate.toLowerCase();
+        if (!seen.has(key)) {
+          seen.add(key);
+          candidates.push(candidate);
+        }
       }
     }
   }
@@ -323,7 +339,9 @@ function nodeShebang(file) {
 
 function spawnSpec(bin, args = [], extraDirs = []) {
   const resolved = resolveExecutable(bin, extraDirs);
-  if (!resolved) return { cmd: bin, args };
+  // Unresolved, so hand the spawn the preferred name and let it produce the
+  // ENOENT — a list would be spawned as a single nonsense filename.
+  if (!resolved) return { cmd: primaryBin(bin), args };
   if (process.platform === "win32" && path.extname(resolved) === "" && nodeShebang(resolved)) {
     return { cmd: process.execPath, args: [resolved, ...args] };
   }
@@ -421,21 +439,29 @@ export function runCmd(cmd, args = [], { capture = false } = {}) {
     let child;
     const spec = spawnSpec(cmd, args);
     const stdio = capture ? ["inherit", "pipe", "pipe"] : "inherit";
-    try { child = spawn(spec.cmd, spec.args, { stdio }); }
-    catch (e) { resolve({ ok: false, error: e }); return; }
+    // The `capture` branch already reaches a watching browser: it re-writes
+    // every byte through this process's own stdout/stderr, which the mirror
+    // tees. The inherited branch does not — those bytes go to the tty and
+    // nowhere else — so it goes under a pty when a mirror is live. This is what
+    // an upgrade, a plugin install and an `mcp add` all run through, and all
+    // three used to be a rule, a blank stretch, and a result line.
+    const launch = capture ? { ...spec, stop: () => {} } : captureSpec(spec);
+    const finish = (result) => { try { launch.stop(); } catch { /* already drained */ } resolve(result); };
+    try { child = spawn(launch.cmd, launch.args, { stdio }); }
+    catch (e) { finish({ ok: false, error: e }); return; }
     let output = "";
     if (capture) {
       for (const [stream, sink] of [[child.stdout, process.stdout], [child.stderr, process.stderr]]) {
         stream?.on("data", (chunk) => { output += chunk.toString(); sink.write(chunk); });
       }
     }
-    child.on("error", (e) => resolve({ ok: false, error: e, output }));
+    child.on("error", (e) => finish({ ok: false, error: e, output }));
     // "exit" fires as soon as the process is gone, which with pipes can leave
     // the last chunk still queued — the one line we are trying to read. "close"
     // waits for the streams too. With stdio inherited there are no streams, so
     // the two are the same moment and existing callers are unaffected; the
     // distinction is kept explicit so neither branch changes by accident.
-    child.on(capture ? "close" : "exit", (code, signal) => resolve({ ok: true, code, signal, output }));
+    child.on(capture ? "close" : "exit", (code, signal) => finish({ ok: true, code, signal, output }));
   });
 }
 
@@ -483,35 +509,8 @@ export function openPassthrough(target, args = [], { onOutput } = {}) {
     // the child the tty's own file descriptors, so none of its bytes ever pass
     // through this process. See src/pty.mjs for why this is script(1) and not
     // a pipe or node-pty.
-    let transcript = null;
-    let workDir = null;
-    let stopFollow = null;
-    let launch = { ...spec, stdio: "inherit" };
-    if (ptyEnabled(onOutput)) {
-      try {
-        workDir = mkdtempSync(path.join(tmpdir(), "moshcode-pty-"));
-        transcript = path.join(workDir, "transcript");
-        writeFileSync(transcript, "");
-        const wrapped = ptySpec(spec.cmd, spec.args, transcript, scriptFlavor());
-        if (wrapped) {
-          launch = { ...wrapped, stdio: "inherit" };
-          let first = true;
-          stopFollow = followFile(transcript, (chunk) => {
-            const clean = stripScriptBanner(chunk, first);
-            first = false;
-            if (clean) onOutput(clean);
-          });
-        }
-      } catch {
-        // Capture is a nicety; never let it stop the session from opening.
-        transcript = null;
-      }
-    }
-
-    const cleanup = () => {
-      try { stopFollow?.(); } catch { /* nothing left to drain */ }
-      if (workDir) { try { rmSync(workDir, { recursive: true, force: true }); } catch { /* temp dir */ } }
-    };
+    const launch = captureSpec(spec, onOutput);
+    const cleanup = () => launch.stop();
 
     let child;
     try { child = spawn(launch.cmd, launch.args, { stdio: "inherit", env }); }