moshcode 0.51.0 → 0.53.0

package/README.md

@@ -449,6 +449,12 @@ MoshCode resolves the latest GitHub release and drops the binary in
 goes through your distro's package manager and will ask for sudo (on macOS it
 delegates to the App Store).
 
+MoshCode asks for that password **before** starting the work rather than letting
+the installer stop for it partway through — which matters most in `moshcode
+update`, where tailscale is one step in a long unattended run and the prompt
+would otherwise land where nobody is watching. Nothing is asked when the plan has
+no privileged step in it, when a credential is already cached, or on macOS.
+
 Top-level passthrough preserves stdin, stdout, stderr, environment variables,
 the current directory, and the native exit result. That keeps JSON pipelines
 usable:
@@ -1035,7 +1041,7 @@ chmod +x deploy.mosh
 | `ask(prompt)` | blocking gate — waits for human reply at moshcode.sh |
 | `say("…")` | print a line |
 | `sleep(ms)` | pause for N milliseconds (blocking) |
-| `shell(cmd)` | run a shell command (blocking, `$SHELL -c`); returns `{ ok, code }` |
+| `shell(cmd)` | run a shell command (blocking, `$SHELL +m -ic`, so your rc file loads without job control taking the terminal); returns `{ ok, code }` |
 | `stop()` | end the loop (`alive = false`) |
 | `repeat()` | back to the top of the loop |
 

package/bin/moshcode.mjs

@@ -43,6 +43,7 @@ import {
   renderMarkdown, renderScriptVerb, suggest, wantsHelp, withoutHelp,
 } from "../src/help.mjs";
 import { moshcodeVersion } from "../src/ui.mjs";
+import { needsRootHere, primeEscalation } from "../src/escalate.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const EXAMPLE = path.join(HERE, "..", "examples", "alive.mosh");
@@ -445,6 +446,9 @@ async function main() {
     }
     const { install, desc, bin } = entry;
     console.log(`🎸 installing ${target} — ${desc}\n$ ${install.cmd} ${install.args.join(" ")}\n`);
+    // Ask for the password before the installer starts, not after it has spent a
+    // minute refreshing package lists and then stopped to wait on one.
+    if (needsRootHere(entry)) primeEscalation({ what: target });
     const result = await runCmd(install.cmd, install.args);
     if (!result.ok) {
       console.error(`install failed: ${result.error?.message || result.error || "unknown error"}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/src/aliases.mjs

@@ -8,7 +8,7 @@
 // An alias is a name and a line. The line is a shell command unless it starts
 // with `/`, in which case it is a pit command:
 //
-//   /alias set gs "git status"       → /gs   runs `$SHELL -c "git status"`
+//   /alias set gs "git status"       → /gs   runs `$SHELL -ic "git status"`
 //   /alias set cc "/agents claude"   → /cc   opens claude autonomously
 //
 // Shell-by-default because that is what the prompt is mostly asked for, and the
@@ -148,7 +148,7 @@ export function removeAlias(name) {
  *
  * Appended rather than substituted, the way a shell alias behaves: `/gs -sb` is
  * `git status -sb`. `args` is the raw remainder of the typed line, not the
- * tokenized parts, so the user's own quoting survives into `$SHELL -c`.
+ * tokenized parts, so the user's own quoting survives into `$SHELL -ic`.
  *
  * The `!` is what routes a bare value to the shell — the pit already reads a
  * leading `!` as "run this in $SHELL", so an alias does not need a second path

package/src/commands.mjs

@@ -20,6 +20,7 @@ import { cliVerb, aiVerb } from "./cli.mjs";
 import { ingestApproval, pollApproval } from "./notify.mjs";
 import { capture, killSession, sendPrompt } from "./herd.mjs";
 import { herdStart, roster, waitFor } from "./herd-cli.mjs";
+import { shellInvocation } from "./shell.mjs";
 
 // The moshcoding pit-anthem playlist. mosh() blasts this URL and, on a desktop
 // with a GUI, tries to open it in the default browser.
@@ -190,9 +191,9 @@ const COMMANDS = [
 
   {
     name: "shell",
-    summary: "run a shell command (blocking, cmd.exe on Windows or $SHELL -c elsewhere)",
+    summary: "run a shell command (blocking, cmd.exe on Windows or $SHELL elsewhere)",
     usage: "shell(cmd)",
-    detail: "runs cmd in $SHELL; returns { ok, code, signal }",
+    detail: "runs cmd in $SHELL, loading your rc file where it can; returns { ok, code, signal }",
     // The moshscript system verb for arbitrary shell commands. Blocking
     // (spawnSync + inherited stdio) so it runs inline in the no-`await` style,
     // and the child owns the terminal for interactive commands. Returns
@@ -202,15 +203,16 @@ const COMMANDS = [
       const cmd = args.join(" ");
       if (!cmd) throw new Error("moshscript: shell() requires a command string");
       if (ctx.dryRun) {
-        ctx.out(`  ▶ shell(${JSON.stringify(cmd)}) → would run: $SHELL -c ${JSON.stringify(cmd)}`);
+        ctx.out(`  ▶ shell(${JSON.stringify(cmd)}) → would run: $SHELL ${shellInvocation(cmd).flags} ${JSON.stringify(cmd)}`);
         // Same R8 contract as the comment above: `code` is always present, so a
         // script branching on the exit status behaves the same under --dry-run.
         return { ok: true, code: 0, dryRun: true };
       }
-      const sh = process.platform === "win32"
-        ? (process.env.COMSPEC || "cmd.exe")
-        : (process.env.SHELL || "/bin/sh");
-      const shArgs = process.platform === "win32" ? ["/d", "/s", "/c", cmd] : ["-c", cmd];
+      // Same invocation the pit's own `!cmd` uses, so a command that works when
+      // typed works when scripted: interactive where a terminal is attached, so
+      // the user's rc file — and the aliases in it — are loaded. src/shell.mjs
+      // 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" });
       if (res.error) throw res.error;

package/src/escalate.mjs

@@ -27,6 +27,22 @@ function defaultProbe(tool) {
   return spawnSync("sh", ["-c", `command -v ${tool}`], { stdio: "ignore" }).status === 0;
 }
 
+/**
+ * How to ask a helper to cache a credential without running anything real.
+ *
+ * `sudo -v` exists for exactly this: validate, refresh the timestamp, run no
+ * command. doas has no equivalent flag, so it gets the smallest possible real
+ * command instead — the point is only to make it prompt.
+ */
+function primeArgs(tool) {
+  return tool === "sudo" ? ["-v"] : ["true"];
+}
+
+/** `-n` is "never prompt" in both, so a zero exit means a credential is ready. */
+function alreadyCached(tool, spawn) {
+  return spawn(tool, ["-n", "true"], { stdio: "ignore" })?.status === 0;
+}
+
 /**
  * Which escalation helper this machine has, honouring an explicit override.
  * Returns null when there is none — a container running as a non-root user
@@ -42,6 +58,82 @@ export function findEscalator({ env = process.env, probe = defaultProbe } = {})
   return null;
 }
 
+/**
+ * Does installing or upgrading this entry need root *on this machine*?
+ *
+ * A spec says `needsRoot: true` when it always does, or `{ except: [...] }` when
+ * a platform is the exception. tailscale is the reason for the second form: its
+ * script goes through the distro package manager on Linux and delegates to the
+ * App Store on macOS, where nothing escalates. Without the distinction, every
+ * mac running `moshcode update` would be asked for a password by a step that
+ * never wanted one — which is the same bug as prompting halfway through, just
+ * earlier and more annoying.
+ */
+export function needsRootHere(entry, platform = process.platform) {
+  const spec = entry?.needsRoot;
+  if (!spec) return false;
+  if (spec === true) return true;
+  if (Array.isArray(spec)) return spec.includes(platform);
+  if (Array.isArray(spec.except)) return !spec.except.includes(platform);
+  return false;
+}
+
+/**
+ * Ask for the password now, for a step that will need root later.
+ *
+ * Some installers escalate on their own partway through their own work —
+ * tailscale's goes through the distro package manager, so it calls sudo after
+ * refreshing package lists. That is fine when it is the only thing running and
+ * miserable inside `moshcode update`, which walks a plan: moshcode itself, then
+ * every installed engine, then every tool. The operator sees a long stream of
+ * downloads scroll past, looks away, and comes back to a run that has been
+ * parked on a password prompt — or worse, to sudo's own timeout having failed
+ * the step. The work is not interactive, so nobody is watching the one moment
+ * that is.
+ *
+ * So we prompt before starting instead. sudo caches the credential against the
+ * terminal, and every installer we hand off to inherits that same terminal, so
+ * the escalation they do later finds it already there and never asks.
+ *
+ * Returns `{ primed, tool, reason }` and never throws. `primed: false` is not
+ * fatal anywhere it is called: the caller carries on and the installer prompts
+ * whenever it was going to, which is exactly the old behaviour. Being unable to
+ * ask early is a missed convenience, not a reason to refuse to install.
+ */
+export function primeEscalation({
+  what = "this",
+  env = process.env,
+  isTTY = Boolean(process.stdin?.isTTY && process.stdout?.isTTY),
+  spawn = spawnSync,
+  probe = defaultProbe,
+  out = console.log,
+  getuid = typeof process.getuid === "function" ? process.getuid : null,
+} = {}) {
+  // Already root — nothing to ask for, and nothing to ask with.
+  if (getuid && getuid() === 0) return { primed: true, tool: null, reason: "already-root" };
+  // No terminal means no prompt. Warming a credential here would either fail or
+  // hang a CI job on a password nobody can type, which is the thing this exists
+  // to prevent rather than to cause.
+  if (!isTTY) return { primed: false, tool: null, reason: "no-tty" };
+
+  const tool = findEscalator({ env, probe });
+  if (!tool) return { primed: false, tool: null, reason: "no-escalator" };
+
+  // Silence is the right outcome when a credential is already cached, or when
+  // this operator's rule is NOPASSWD. Printing "asking for your password" and
+  // then not asking reads as a bug.
+  if (alreadyCached(tool, spawn)) return { primed: true, tool, reason: "cached" };
+
+  out(`· ${what} needs root partway through — asking ${tool} for your password now, so it doesn't stop halfway.`);
+  const result = spawn(tool, primeArgs(tool), { stdio: "inherit" });
+  if (result?.error) return { primed: false, tool, reason: "spawn-failed" };
+  // A non-zero exit is a wrong password, a cancelled prompt, or an operator who
+  // is not in sudoers. All three mean "carry on unprimed" rather than "stop":
+  // the installer may well not need root on this machine at all.
+  if (result?.status !== 0) return { primed: false, tool, reason: "declined" };
+  return { primed: true, tool, reason: "prompted" };
+}
+
 /**
  * Re-run this CLI's own argv under the escalation helper.
  *

package/src/shell.mjs

@@ -0,0 +1,134 @@
+// One answer to "how does the pit run a shell command".
+//
+// The pit is not a shell, so everything it runs on the user's behalf goes out
+// through $SHELL: `!cmd`, `/shell`, a shell-valued alias from /alias, and
+// moshscript's shell(). The obvious spelling is `$SHELL -c "<cmd>"`, and it is
+// wrong in a way that costs an afternoon to find. `zsh -c` and `bash -c` are
+// non-interactive shells, and a non-interactive shell does not read ~/.zshrc or
+// ~/.bashrc — so the aliases and functions defined there are simply not there:
+//
+//   /alias set prs gh-prs-all     → zsh -c gh-prs-all
+//                                 → zsh:1: command not found: gh-prs-all
+//
+// while the identical word works when typed at a prompt. That is a bug rather
+// than a footnote, because naming a shell command is most of what /alias is
+// for, and the shell commands people name are the ones they already named once
+// in ~/.zsh_aliases. An alias that resolves at the prompt and not in the pit
+// makes the pit look broken, and from the user's side it is.
+//
+// So we ask for an interactive shell. `-i` is the switch that makes bash and
+// zsh read their rc file, and the rc file is where the user's shell actually
+// lives. Anything already on PATH worked before and still works; what changes
+// is that aliases and functions now resolve too.
+
+/**
+ * Shells whose startup file is read only when the shell is interactive.
+ *
+ * Deliberately just bash and zsh. fish sources config.fish however it was
+ * started, so it needs nothing from us; plain sh/dash have no rc file to miss
+ * and `-i` would only buy them job-control machinery; and a shell we have not
+ * heard of is likelier to be harmed by an unexpected flag than helped by it.
+ * Being wrong here means running a command in a shell that cannot see the
+ * user's aliases, which is exactly where we started — so an unknown shell
+ * lands on the old behaviour rather than on a guess.
+ */
+const RC_ON_INTERACTIVE = new Set(["bash", "zsh"]);
+
+/**
+ * Shells that will give up job control if asked, and why we ask.
+ *
+ * `-i` buys the rc file and, unasked, brings job control with it. An interactive
+ * shell with job control makes itself a process group leader and takes the
+ * terminal — and when it hands it back, it hands it back to what it thinks the
+ * shell before it was. The pit is not a shell and does not play that game, so
+ * the terminal can be left belonging to a process group that has exited. The
+ * pit's very next write then takes SIGTTOU and the whole pit stops:
+ *
+ *   · shell exited (code 0). back in the pit.
+ *   [1]  + 3034615 suspended (tty output)  moshcode
+ *
+ * `+m` unsets MONITOR, so zsh reads the rc file and never touches the terminal's
+ * process group. Nothing is lost: job control exists to manage several jobs at a
+ * prompt, and this shell runs one command and exits. It also restores exactly
+ * the signal behaviour of the plain `-c` this replaced, where the command shared
+ * the pit's process group.
+ *
+ * bash is not in this set because it will not honour it — an interactive bash
+ * turns job control back on regardless of `+m`, which is measurable: `bash +m
+ * -ic 'case $- in *m*)…'` still reports `m`. Passing a flag that is ignored
+ * would only suggest a protection that is not there.
+ */
+const NO_JOB_CONTROL = new Set(["zsh"]);
+
+/** Set this to opt a session out of rc loading and get plain `-c` back. */
+export const NO_RC_ENV = "MOSHCODE_SHELL_NO_RC";
+
+/** Windows has no rc file in this sense; cmd.exe wants its own flag spelling. */
+const CMD_FLAGS = ["/d", "/s", "/c"];
+
+/** The shell the user runs, or the platform's fallback. */
+export function shellPath(env = process.env, platform = process.platform) {
+  if (platform === "win32") return env.COMSPEC || "cmd.exe";
+  return env.SHELL || "/bin/sh";
+}
+
+/**
+ * `zsh` from `/usr/bin/zsh`, `bash` from `C:\...\bash.exe`.
+ *
+ * Both separators by hand rather than path.basename, which is bound to the
+ * platform the code is running on: it would leave a Windows path intact when
+ * asked on Linux, and this function is also asked about the other platform —
+ * shellInvocation takes `platform` as an option so the Windows branch can be
+ * tested from anywhere.
+ */
+export function shellName(shell) {
+  const tail = String(shell || "").split(/[\\/]/).pop() || "";
+  return tail.replace(/\.exe$/i, "");
+}
+
+/**
+ * How to spawn `rawCmd`, as { shell, args, flags, interactive }.
+ *
+ * `rawCmd` empty means "a shell to sit in" — no args at all, which is already
+ * an interactive shell and already reads the rc file.
+ *
+ * `tty` is why this takes options rather than reading the world directly. An
+ * interactive bash with no terminal attached prints
+ *
+ *   bash: cannot set terminal process group (…): Inappropriate ioctl for device
+ *   bash: no job control in this shell
+ *
+ * on stderr before it runs a thing, which would turn every headless run — cron,
+ * CI, `moshcode run script.mosh` in a pipeline — into noise around the output
+ * someone is trying to read. With a terminal attached, both shells are silent.
+ * So the rc file is loaded where a person is watching, which is the case that
+ * wanted it, and a headless run keeps the old quiet behaviour. zsh alone would
+ * not need the guard; the guard is not worth splitting per shell for.
+ */
+export function shellInvocation(rawCmd, {
+  env = process.env,
+  platform = process.platform,
+  tty = Boolean(process.stdin?.isTTY && process.stdout?.isTTY),
+} = {}) {
+  const shell = shellPath(env, platform);
+  const name = shellName(shell);
+  if (!rawCmd) return { shell, args: [], flags: "", interactive: true, name };
+  if (platform === "win32") {
+    return { shell, args: [...CMD_FLAGS, rawCmd], flags: CMD_FLAGS.join(" "), interactive: false, name };
+  }
+  const interactive = tty && RC_ON_INTERACTIVE.has(name) && !env[NO_RC_ENV];
+  if (!interactive) return { shell, args: ["-c", rawCmd], flags: "-c", interactive, name, jobControl: false };
+  // `+m` before `-ic`: options have to precede the command string, and this one
+  // is what keeps an interactive shell from taking the terminal's process group
+  // away from the pit. See NO_JOB_CONTROL.
+  const argv = NO_JOB_CONTROL.has(name) ? ["+m", "-ic"] : ["-ic"];
+  return {
+    shell,
+    args: [...argv, rawCmd],
+    flags: argv.join(" "),
+    interactive,
+    name,
+    // True only where we could not turn it off — bash forces it back on.
+    jobControl: !NO_JOB_CONTROL.has(name),
+  };
+}

package/src/tools.mjs

@@ -118,6 +118,17 @@ export const TOOLS = {
     // which means it needs root — it finds sudo/doas itself and may prompt for a
     // password (stdio is inherited, so the prompt works). On macOS the same
     // script delegates to the App Store.
+    //
+    // `needsRoot` is what lets us get that prompt out of the way before the work
+    // starts rather than partway through it. It says nothing about how the
+    // escalation happens — the vendor script still does its own — only that one
+    // is coming, which is all primeEscalation needs to know. `tailscale update`
+    // needs root for the same reason, so it covers both directions.
+    //
+    // macOS is the exception, and the same line above says why: there the script
+    // delegates to the App Store, which does its own authorisation. Asking for a
+    // sudo password there would be a prompt for a step that never escalates.
+    needsRoot: { except: ["darwin"] },
     install: { cmd: "sh", args: ["-c", "curl -fsSL https://tailscale.com/install.sh | sh"] },
     // Native updater on Linux (v1.36+) and Windows. macOS updates come from the
     // App Store, so there it fails with tailscale's own message rather than

package/src/tui.mjs

@@ -25,6 +25,8 @@ import { stocksCommand } from "./advisor.mjs";
 import { cryptoCommand } from "./crypto.mjs";
 import { gamesCommand } from "./games.mjs";
 import { canOpenBrowser, openBrowser } from "./open-url.mjs";
+import { shellInvocation } from "./shell.mjs";
+import { needsRootHere, primeEscalation } from "./escalate.mjs";
 import { banner, hr, acid, ash, bone, dim, ok, err, warn, info, moshcodeVersion } from "./ui.mjs";
 import { CORE_CLI_COMMAND_NAMES } from "./cli-schema.mjs";
 import { RENAMED_COMMANDS, findPitCommand, pitHelpModel, renderPitCommand, suggest, wantsHelp } from "./help.mjs";
@@ -128,7 +130,7 @@ export function splitCommandLine(line) {
 }
 
 // Everything after the first word of a command line, exactly as typed. `/shell`
-// hands this straight to `$SHELL -c`, the same way `!cmd` does: the shell does
+// hands this straight to `$SHELL -ic`, the same way `!cmd` does: the shell does
 // its own parsing, so re-joining the tokenized parts would strip the user's
 // quotes and escapes and silently split `-m "two words"` into two arguments.
 function commandRemainder(line, words = 1) {
@@ -148,7 +150,7 @@ function commandRemainder(line, words = 1) {
  * quotes there belong to the shell. Tokenizing tells the two apart: exactly one
  * token means the whole value was quoted, so use it with the quotes stripped;
  * anything else is a bare command line, and it goes through verbatim so the
- * user's own quoting survives into `$SHELL -c`.
+ * user's own quoting survives into `$SHELL -ic`.
  */
 export function aliasValue(line) {
   const raw = commandRemainder(line, 3); // past "/alias", "set", "<name>"
@@ -508,12 +510,12 @@ async function openWorkflowTool(key, tool, args) {
 
 // Spawn the user's shell with the terminal fully handed over (stdio inherit),
 // inheriting the current cwd + env. No args → an interactive shell; a raw
-// command string → `$SHELL -c "<cmd>"` (one-off). Resolves { ok, code, signal }.
+// command string → `$SHELL +m -ic "<cmd>"` (one-off). Interactive so the command
+// can see the aliases and functions in ~/.zshrc — see src/shell.mjs for why
+// that is not optional. Resolves { ok, code, signal }.
 function runShell(rawCmd) {
   return new Promise((resolve) => {
-    const shell = process.env.SHELL
-      || (process.platform === "win32" ? (process.env.COMSPEC || "cmd.exe") : "/bin/sh");
-    const args = rawCmd ? ["-c", rawCmd] : [];
+    const { shell, args } = shellInvocation(rawCmd);
     let child;
     try { child = spawn(shell, args, { stdio: "inherit" }); }
     catch (e) { resolve({ ok: false, error: e }); return; }
@@ -525,9 +527,12 @@ function runShell(rawCmd) {
 // vim `:sh` — drop into a shell and land back at the mosh prompt on exit, with
 // the whole TUI session (history, cwd) intact. `rawCmd` runs a one-off instead.
 async function openShell(rawCmd) {
-  const shellName = path.basename(process.env.SHELL || "sh");
+  // The flags come from the same place the spawn does, so the echoed line is
+  // what actually ran — a `-c` printed above an `-ic` invocation is the kind of
+  // small lie that sends someone debugging the wrong shell.
+  const { flags, name: shellName } = shellInvocation(rawCmd);
   console.log(info(rawCmd
-    ? `${bone(shellName)} ${ash("-c")} ${ash(rawCmd)}`
+    ? `${bone(shellName)} ${ash(flags)} ${ash(rawCmd)}`
     : `dropping to ${bone(shellName)} — ${ash("`exit` or Ctrl-D brings you back to the pit")}`));
   console.log(hr());
   const r = await runShell(rawCmd);
@@ -546,6 +551,9 @@ function installTarget(key) {
     const target = (Object.hasOwn(ENGINES, key) && ENGINES[key]) || (Object.hasOwn(TOOLS, key) && TOOLS[key]);
     if (!target) { console.log(err(`unknown engine or tool "${key}"`)); return resolve(); }
     console.log(info(`installing ${key}: ${target.install.cmd} ${target.install.args.join(" ")}`));
+    // Before the rule, so the prompt reads as the pit asking rather than as
+    // something the installer's output scrolled into view.
+    if (needsRootHere(target)) primeEscalation({ what: key, out: (s) => console.log(info(s.replace(/^· /, ""))) });
     console.log(hr());
     const child = spawn(target.install.cmd, target.install.args, { stdio: "inherit" });
     child.on("error", (e) => {

package/src/upgrade.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { ENGINES, engineStatus, exitReason, ranOk, resolveEngine, upgradeSpec, runCmd } from "./engines.mjs";
 import { TOOLS, resolveTool, toolStatus, toolUpgradeSpec } from "./tools.mjs";
+import { needsRootHere, primeEscalation } from "./escalate.mjs";
 
 // Self-upgrade re-runs the moshcode installer's `update` path. Defaults to the
 // GitHub-hosted install.sh (always live); override with MOSHCODE_INSTALL_URL.
@@ -84,6 +85,7 @@ export function planUpgrade(targets = []) {
       // is something other than the installer, so a fallback can never repeat
       // the command that just failed.
       fallback: installed && upgradeSpec(ENGINES[key]) !== ENGINES[key].install ? ENGINES[key].install : null,
+      needsRoot: needsRootHere(ENGINES[key]),
       installed,
     });
   };
@@ -98,6 +100,7 @@ export function planUpgrade(targets = []) {
       kind: "tool",
       spec: installed ? toolUpgradeSpec(TOOLS[key]) : TOOLS[key].install,
       fallback: installed && toolUpgradeSpec(TOOLS[key]) !== TOOLS[key].install ? TOOLS[key].install : null,
+      needsRoot: needsRootHere(TOOLS[key]),
       installed,
     });
   };
@@ -167,6 +170,17 @@ export async function runUpgrade(targets = [], io = {}) {
 
   const exec = io.runCmd || runCmd;
 
+  // Get the password prompt out of the way before the first download rather than
+  // somewhere in the middle of the plan. A plan is long and unattended by
+  // design; the one interactive moment in it should not be buried where nobody
+  // is looking. Skipped entirely when nothing in the plan needs root, so the
+  // common `moshcode update` never asks.
+  const rootItems = items.filter((it) => it.needsRoot);
+  if (rootItems.length) {
+    const prime = io.primeEscalation || primeEscalation;
+    prime({ what: rootItems.map((it) => it.label).join(", "), out: log });
+  }
+
   const results = [];
   const attempt = async (name, spec, note) => {
     log(`\n⬆ upgrading ${name}${note ? ` ${note}` : ""} — ${spec.cmd} ${spec.args.join(" ")}`);