@mutmutco/installer-face 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.4.3
+
+- Resolve freshly installed npm commands outside the inherited PATH.
+- Preserve typed engine phases, safe authentication relay and product JSON through shared maintenance.
+- Own quiet output, cancellation and failure diagnostics in the shared lifecycle.
+- Preserve mid-run authentication handoff, measured progress timing and terminal routing.
+- Use ASCII plain labels without changing Unicode paths, names or authorization URLs.
+
+# 0.4.2
+
+- Preserve rollback and log facts, including retry guidance for early failures.
+- Isolate injected output observers while keeping terminal and filesystem failures visible.
+- Generate embedded-runtime convergence from a declaration without global npm installation.
+
 # 0.4.1
 
 - Capture bootstrap output and validate recorded installer transcripts.

package/README.md

@@ -20,6 +20,15 @@ only shared code and a shared guard can.
 Product install/update entrypoints call `runMaintenance(declaration, args, engines)`.
 The package owns phase ordering, self-update handoff, scheduler completion, outcome reporting and
 cleanup. Product engines return version, surface and failure facts; they do not draw a run.
+Engines receive `onPhaseEvent({ id, state, detail?, measure?, measured? })` for phase facts.
+Repeated running progress retains the original start time; the package measures elapsed time.
+Typed `measured` facts carry percent, bytes, or a count with an optional total. Unknown totals stay unknown.
+Each completed phase needs its own verdict: starting another phase does not imply success.
+`relay(text, channel?, record?)` defaults to live-only output, keeping authorization URLs out of transcripts.
+Optional `jsonResult(summary, schedule)` preserves product machine output while the shared owner serializes it.
+`safeErrorDetail(error)` supplies an actionable, non-sensitive failure message; the default is generic.
+Scheduling and self-handoff callbacks are optional, but a requested handoff without an implementation fails.
+Return `cancelled: true` to end without readiness. The package also owns `--quiet` output selection.
 The declaration contains the canonical product key (`mmi` and `jerv` aliases are accepted), gate
 URL, canonical doctor command, and a nonempty unique surface list
 `{ id, npm?, bin?, kind?, activation? }`.
@@ -27,26 +36,42 @@ URL, canonical doctor command, and a nonempty unique surface list
 `createInstallerRun` is the lower-level owner used by the shared launcher, not a reason for each
 product to author another installer. `renderPayloadEntry` generates the npm-install/converge entry
 from tarball names and a declared convergence command. Product release scripts supply those facts.
+The npm mode resolves that command from the global prefix after installation; it never relies on a refreshed PATH.
+For an embedded-runtime product, supply `installedRuntime: { entry, package, installRootEnv }`;
+`converge` then contains entry arguments rather than a binary name. The shared entry resolves the
+installed product and re-enters it with `--payload` and `--installed`, without invoking npm.
 
 The package owns greeting, phase names, spinner, surface status, receipt and sign-off.
 `phase` accepts preflight, resolve, download, verify, install, activate, doctor, sign-in, check,
-arm and verify-release. Its facts are state (running/ok/fail/note), seconds, measure and safe detail.
+arm, verify-release and rollback. Its facts are state (running/ok/fail/note), seconds, measure and safe detail.
 `surface` accepts updated/current/failed/skipped/retry/pending/kept. `finish` accepts version,
-total, updated, failed and optional retry, dryRun, installed, deferred and safe detail.
+total, updated, failed and optional retry, dryRun, installed, deferred, operationFailed and safe detail.
+Failure facts can include rollback (`completed`, `partial`, `not-needed`, `unknown`), logPath,
+or logState (`unavailable`, `omitted`). Early operation failures retain retry guidance even with zero surfaces.
 Missing version or deferred work never reports ready. Counts must describe the same operation set.
 Pass `dryRun: true` in options so individual rows also say “would update”.
 
 `operation: "install"` selects the canonical first-install welcome.
 `start()` and `finish()` are idempotent. `stop()` clears transient work. The orchestration wrapper
 always stops the spinner, including when an operation throws; the caller retains error handling.
-Use the manual lifecycle for a self-reexec that transfers final receipt ownership to its child.
+Use the shared maintenance handoff for self-reexec. For a mid-engine authentication retry,
+`withCustody` pauses the shared output and supplies completed `faceContinues` phases to the product
+operation. Return `{ kind: "resume", value }` to continue, or `{ kind: "reexec", code }` when the
+child owns the final result. The shared owner resumes timing or transfers receipt ownership.
 
 `signIn({url, code})` owns device-login instructions. The code is visible in the terminal and
 redacted in transcripts. `relay(text, channel)` and `milestone({step,state,ms})` accept only safe
 child diagnostics: never pass authentication responses, credentials or raw provider errors.
 
-TTY, color, width, environment, animation and output sink can be injected through options.
+Maintenance callers can declare `render: { tty, color, columns, env, animate }` without supplying
+a writer or constructing a run. `--no-color`, `NO_COLOR`, and `TERM=dumb` disable color.
+The lower-level owner also accepts an output observer for tests.
+Omit `write` for production terminal output and worker animation during synchronous work.
+An injected `write` observer uses timer animation; its exceptions are retained in `run.errors`.
+Default terminal writes and transcript/outcome filesystem failures remain operation errors.
 Non-TTY output is plain append-only text. NO_COLOR disables color, not the visual structure.
+The shared plain lane uses ASCII labels and separators while preserving dynamic Unicode data.
+Do not transliterate paths or authorization URLs through a consumer output callback.
 Nested processes suppress greetings and send their final outcome to the console owner.
 The private outcome channel works through Windows command shims as well as direct child processes;
 a successful process exit never turns a deferred result into readiness.

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { InstallerProduct, InstallerRun, InstallerRunOptions, InstallerPhas
 export { renderPayloadEntry } from './payload.js';
 export type { PayloadEntryOptions } from './payload.js';
 export { runMaintenance } from './maintenance.js';
-export type { MaintenanceArm, MaintenanceSummary } from './maintenance.js';
+export type { MaintenanceArm, MaintenanceSummary, MaintenancePhaseEvent, MaintenanceCustodyResult, MaintenanceEngineOptions, MaintenanceSchedule } from './maintenance.js';
 export { validateInstallerOutcome, readInstallerOutcome, writeInstallerOutcome } from './outcome.js';
 export type { InstallerOutcome } from './outcome.js';
 export { assertInstallerTranscript } from './transcript.js';

package/dist/index.js

@@ -655,7 +655,7 @@ function assertFaceConformance(lines, options) {
     }
   }
   if (rendered.length === 0) fail("R7 render before you ship", "no rendered lines were given to the guard");
-  const greetings = plain.filter((line) => line.includes(`${identity.name} \u2014 Mutatis Mutandis`));
+  const greetings = plain.filter((line) => ["\u2014", "-"].some((separator) => line.includes(`${identity.name} ${separator} Mutatis Mutandis`)));
   if (greetings.length > 1) fail("R8 one welcome per run", "duplicate product greeting");
   if (plain.filter((line) => line.startsWith(GLYPH.boxTop)).length > 1) {
     fail("R8 one receipt per run", "duplicate receipt");
@@ -794,7 +794,7 @@ import { appendFileSync as appendFileSync2 } from "node:fs";
 // src/outcome.ts
 import { readFileSync, writeFileSync } from "node:fs";
 var counts = ["total", "updated", "failed"];
-var strings = ["version", "retry", "detail"];
+var strings = ["version", "retry", "detail", "logPath"];
 var flags = ["dryRun", "installed", "deferred", "operationFailed"];
 function validateInstallerOutcome(value) {
   const invalid = () => {
@@ -802,12 +802,15 @@ function validateInstallerOutcome(value) {
   };
   if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
   const facts = value;
-  const allowed = [...counts, ...strings, ...flags];
+  const allowed = [...counts, ...strings, ...flags, "rollback", "logState"];
   if (Object.keys(facts).some((key) => !allowed.includes(key))) return invalid();
   for (const key of counts) if (!Number.isSafeInteger(facts[key]) || facts[key] < 0) return invalid();
   if (facts.updated + facts.failed > facts.total) return invalid();
   for (const key of strings) if (facts[key] !== void 0 && (typeof facts[key] !== "string" || facts[key].length > 4096)) return invalid();
   for (const key of flags) if (facts[key] !== void 0 && typeof facts[key] !== "boolean") return invalid();
+  if (facts.rollback !== void 0 && !["completed", "partial", "not-needed", "unknown"].includes(facts.rollback)) return invalid();
+  if (facts.logState !== void 0 && !["unavailable", "omitted"].includes(facts.logState)) return invalid();
+  if (facts.logPath !== void 0 && (!facts.logPath.trim() || /[\x00-\x1f\x7f]/u.test(facts.logPath))) return invalid();
   return { ...facts };
 }
 function writeInstallerOutcome(path, value) {
@@ -880,7 +883,8 @@ var PHASES = {
   verify: ["Verifying the payload", "Verified the payload"],
   install: ["Installing the product", "Installed the product"],
   activate: ["Activating surfaces", "Activated surfaces"],
-  doctor: ["Checking health", "Checked health"]
+  doctor: ["Checking health", "Checked health"],
+  rollback: ["Restoring the previous version", "Restored the previous version"]
 };
 function createInstallerRun(value, options = {}) {
   const declaration = validateInstallerProduct(value);
@@ -891,11 +895,18 @@ function createInstallerRun(value, options = {}) {
     product: declaration.product,
     columns: options.columns,
     env,
-    color: tty && options.color !== false && env.NO_COLOR === void 0
+    color: tty && options.color !== false && env.NO_COLOR === void 0 && env.TERM !== "dumb"
   });
-  const write = options.write ?? ((text, channel) => {
+  const errors = [];
+  const write = options.write ? (text, channel) => {
+    try {
+      options.write(text, channel);
+    } catch (error) {
+      errors.push(`installer output observer: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } : (text, channel) => {
     (channel === "stdout" ? process.stdout : process.stderr).write(text);
-  });
+  };
   const emit = (text, channel = "stdout", recorded = text) => {
     if (!text) return;
     write(text, channel);
@@ -920,9 +931,13 @@ function createInstallerRun(value, options = {}) {
   const start = () => {
     if (started || finished) return;
     started = true;
+    if (options.quiet) return;
     const welcome = face.welcome();
     if (tty) lines(welcome);
-    else if (welcome.length) lines([`${face.identity.name} \u2014 Mutatis Mutandis`, options.operation === "install" ? face.identity.installWarm : face.identity.warm]);
+    else if (welcome.length) {
+      const warm = options.operation === "install" ? face.identity.installWarm : face.identity.warm;
+      lines([`${face.identity.name} - Mutatis Mutandis`, warm.replaceAll("\u2014", "-").replaceAll("\u2026", "...")]);
+    }
   };
   const durable = (title, measure, kind) => {
     spinner.stop();
@@ -930,6 +945,9 @@ function createInstallerRun(value, options = {}) {
     if (rendered) lines([tty ? rendered : `${kind === "fail" ? "Failed: " : ""}${title}${measure === null ? "" : ` (${typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : measure})`}`]);
   };
   const run = {
+    get errors() {
+      return [...errors];
+    },
     start,
     phase(id, facts = {}) {
       if (finished) throw new Error("installer run already finished");
@@ -949,12 +967,13 @@ function createInstallerRun(value, options = {}) {
       const surface = declaration.surfaces.find((surface2) => surface2.id === facts.id);
       if (!surface) throw new Error("installer run: undeclared surface");
       start();
-      const versions = facts.to ? facts.from && facts.from !== facts.to ? ` ${facts.from} \u2192 ${facts.to}` : ` ${facts.to}` : "";
+      const versions = facts.to ? facts.from && facts.from !== facts.to ? ` ${facts.from} ${tty ? "\u2192" : "->"} ${facts.to}` : ` ${facts.to}` : "";
       const status = { updated: options.dryRun ? "would update" : "updated", current: "already current", failed: "failed", skipped: "skipped", retry: "retrying", pending: "pending", kept: "kept" }[facts.state];
       if (!status) throw new Error("installer run: unknown surface state");
-      const activation = facts.state === "updated" && surface.activation ? ` \xB7 ${surface.activation}` : "";
+      const separator = tty ? "\xB7" : "-";
+      const activation = facts.state === "updated" && surface.activation ? ` ${separator} ${surface.activation}` : "";
       const completed = ["updated", "current", "kept", "skipped"].includes(facts.state);
-      durable(`${facts.id}${versions} \xB7 ${status}${activation}`, completed ? facts.seconds ?? null : null, facts.state === "failed" ? "fail" : facts.state === "updated" ? "ok" : "note");
+      durable(`${facts.id}${versions} ${separator} ${status}${activation}`, completed ? facts.seconds ?? null : null, facts.state === "failed" ? "fail" : facts.state === "updated" ? "ok" : "note");
       if (facts.detail) run.relay(facts.detail);
     },
     milestone({ step, state, ms }) {
@@ -981,6 +1000,20 @@ function createInstallerRun(value, options = {}) {
 `);
       }
     },
+    cancel() {
+      if (finished) return;
+      if (env.MM_INSTALLER_OUTCOME_FILE) writeInstallerOutcome(
+        env.MM_INSTALLER_OUTCOME_FILE,
+        { total: 0, updated: 0, failed: 0, deferred: true, detail: "Operation cancelled." }
+      );
+      start();
+      spinner.stop();
+      finished = true;
+      if (!face.nested || !env.MM_INSTALLER_OUTCOME_FILE) {
+        lines(tty ? face.receipt(["Operation cancelled."], { ready: false }) : ["Operation cancelled."]);
+      }
+      if (tty) lines([face.signOff()]);
+    },
     finish(facts) {
       if (finished) return;
       validateInstallerOutcome(facts);
@@ -988,6 +1021,7 @@ function createInstallerRun(value, options = {}) {
       start();
       spinner.stop();
       finished = true;
+      if (options.quiet && facts.updated === 0 && facts.failed === 0 && !facts.operationFailed) return;
       const changed = !facts.version ? "No release target is available." : facts.dryRun ? `Would update ${facts.updated} of ${facts.total} surfaces to ${facts.version}.` : facts.installed ? `Installed ${facts.version} across ${facts.total} surfaces.` : `Updated ${facts.updated} of ${facts.total} surfaces to ${facts.version}.`;
       const ready = facts.failed === 0 && !facts.dryRun && !facts.deferred && !facts.operationFailed && Boolean(facts.version);
       const body = [
@@ -995,7 +1029,9 @@ function createInstallerRun(value, options = {}) {
         changed,
         ...facts.failed ? [`Failed ${facts.failed} of ${facts.total} surfaces.`] : [],
         ...facts.detail ? [facts.detail] : [],
-        facts.retry && facts.failed ? `Retry:  ${facts.retry}` : `Check health any time:  ${declaration.doctor}`
+        ...facts.rollback ? [`Rollback: ${facts.rollback}`] : [],
+        ...facts.logPath ? [`Log: ${facts.logPath}`] : facts.logState ? [`Log: ${facts.logState}`] : [],
+        facts.retry && (facts.failed > 0 || facts.operationFailed) ? `Retry:  ${facts.retry}` : `Check health any time:  ${declaration.doctor}`
       ];
       if (!face.nested || !env.MM_INSTALLER_OUTCOME_FILE && (facts.failed > 0 || facts.operationFailed)) {
         lines(tty ? face.receipt(body, { ready }) : body.map((row) => row.replace(/^[✔✖●]  /u, "")));
@@ -1021,7 +1057,7 @@ async function runInstaller(value, operation, options) {
 }
 
 // src/payload.ts
-function renderPayloadEntry({ tarballs, converge, shippedFlag }) {
+function renderPayloadEntry({ tarballs, converge, shippedFlag, installedRuntime }) {
   if (!Array.isArray(tarballs) || tarballs.length === 0 || tarballs.some((name) => typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/u.test(name))) {
     throw new Error("installer payload: tarballs must be relative .tgz basenames");
   }
@@ -1031,26 +1067,84 @@ function renderPayloadEntry({ tarballs, converge, shippedFlag }) {
   if (shippedFlag !== void 0 && !/^--[a-z][a-z0-9-]*$/u.test(shippedFlag)) {
     throw new Error("installer payload: invalid shipped flag");
   }
+  if (installedRuntime !== void 0) {
+    if (!installedRuntime || typeof installedRuntime.entry !== "string" || typeof installedRuntime.package !== "string" || !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u.test(installedRuntime.entry) || installedRuntime.entry.split("/").some((part) => part === "." || part === "..") || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u.test(installedRuntime.package) || installedRuntime.package.split("/").some((part) => part === "." || part === "..") || !Array.isArray(installedRuntime.installRootEnv) || installedRuntime.installRootEnv.some((name) => !/^[A-Z][A-Z0-9_]*$/u.test(name))) {
+      throw new Error("installer payload: invalid installed runtime");
+    }
+    if (shippedFlag) throw new Error("installer payload: installed runtime reads its own payload manifest");
+    return String.raw`// Generated by @mutmutco/installer-face. Uses the installed product, never a registry.
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const runtime = ${JSON.stringify(installedRuntime)};
+const argv = process.argv.slice(2);
+const at = argv.indexOf('--payload');
+const payloadDir = resolve(at >= 0 && argv[at + 1] ? argv[at + 1] : dirname(process.argv[1]));
+const productDir = dirname(payloadDir);
+const packaged = join('node_modules', runtime.package);
+const candidates = [
+  ...runtime.installRootEnv.map((name) => process.env[name]),
+  productDir, join(productDir, 'app'), join(productDir, 'current'),
+  join(productDir, packaged), payloadDir, join(payloadDir, packaged),
+];
+const root = candidates.find((candidate) => {
+  if (!candidate) return false;
+  try { return statSync(join(candidate, runtime.entry)).isFile(); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false; throw error; }
+});
+if (!root) {
+  const archives = ${JSON.stringify(tarballs)}.map((name) => '"' + join(payloadDir, name) + '"').join(' ');
+  const viaLauncher = !/^node(\.exe)?$/iu.test(basename(process.execPath));
+  process.stderr.write([
+    'Installer payload has no installed product to converge: ' + payloadDir,
+    'NOT READY — nothing was armed and no host projection was written.',
+    'Finish by installing the payload archive offline:',
+    '  npm install --global --offline ' + archives,
+    'Then retry: "' + process.execPath + '" ' + (viaLauncher ? '--run ' : '') + '"' + process.argv[1] + '" --payload "' + payloadDir + '"',
+  ].join('\n') + '\n');
+  process.exitCode = 1;
+} else {
+  const viaLauncher = !/^node(\.exe)?$/iu.test(basename(process.execPath));
+  const args = [...(viaLauncher ? ['--run'] : []), join(root, runtime.entry),
+    ...${JSON.stringify(converge)}, '--payload', payloadDir, '--installed', root];
+  const child = spawnSync(process.execPath, args, { cwd: root, stdio: 'inherit', windowsHide: true });
+  if (child.error) {
+    process.stderr.write('Installer could not re-enter the installed product: ' + child.error.message + '\n');
+    process.exitCode = 1;
+  } else process.exitCode = child.status === null ? 1 : child.status;
+}
+`;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(converge[0])) {
+    throw new Error("installer payload: npm converge command must be a bin name");
+  }
   return String.raw`// Generated by @mutmutco/installer-face. Product code declares operations, never this program.
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
 
 const payloadDir = dirname(process.argv[1]);
 const tarballs = ${JSON.stringify(tarballs.map((name) => `./${name}`))};
 const converge = ${JSON.stringify(converge)};
 const shippedFlag = ${JSON.stringify(shippedFlag ?? null)};
 
-function step(command, args) {
-  const options = { cwd: payloadDir, stdio: 'inherit', windowsHide: true };
+function step(command, args, capture = false) {
+  const options = { cwd: payloadDir, stdio: capture ? 'pipe' : 'inherit', windowsHide: true, encoding: 'utf8' };
+  if (process.platform === 'win32' && [command, ...args].some((arg) => /[\x00-\x1f"%!]/u.test(arg))) {
+    process.stderr.write('Installer command contains unsupported Windows shell characters.\n');
+    process.exit(1);
+  }
   // One prequoted command and no argv avoids Node's args+shell warning for Windows .cmd shims.
   const result = process.platform === 'win32'
-    ? spawnSync([command, ...args].map((arg) => /\s/.test(arg) ? '"' + arg + '"' : arg).join(' '), [], { ...options, shell: true })
+    ? spawnSync([command, ...args].map((arg) => /[\s&|<>^()]/u.test(arg) ? '"' + arg + '"' : arg).join(' '), [], { ...options, shell: true })
     : spawnSync(command, args, options);
   if (result.error || result.status !== 0) {
+    if (capture && result.stderr) process.stderr.write(result.stderr);
     process.stderr.write('Installer operation failed.\n');
     process.exit(result.status === null || result.status === undefined ? 1 : result.status);
   }
+  return result.stdout ?? '';
 }
 
 step('npm', ['install', '--global', '--no-fund', '--no-audit', ...tarballs]);
@@ -1068,44 +1162,129 @@ if (shippedFlag) {
   }
   if (!shipped) process.stdout.write('Payload carries no shipped version; running the declared operation.\n');
 }
-step(converge[0], [...converge.slice(1), ...(shipped ? [shippedFlag, shipped] : [])]);
+// The new global bin directory may not be on this process's inherited PATH.
+const prefix = step('npm', ['prefix', '--global'], true).trim();
+if (!prefix || !isAbsolute(prefix)) {
+  process.stderr.write('Installer could not resolve the global npm prefix.\n');
+  process.exit(1);
+}
+const candidates = process.platform === 'win32'
+  ? [join(prefix, converge[0] + '.cmd'), join(prefix, converge[0])]
+  : [join(prefix, 'bin', converge[0]), join(prefix, converge[0])];
+const command = candidates.find((candidate) => {
+  try { return statSync(candidate).isFile(); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false; throw error; }
+});
+if (!command) {
+  process.stderr.write('Installer could not find the installed command: ' + converge[0] + '\n');
+  process.exit(1);
+}
+step(command, [...converge.slice(1), ...(shipped ? [shippedFlag, shipped] : [])]);
 `;
 }
 
 // src/maintenance.ts
 async function runMaintenance(product, args, dependencies) {
   const json = args.includes("--json");
+  const quiet = args.includes("--quiet");
   const dryRun = args.includes("--dry-run");
   const installed = args.includes("install");
+  const render = dependencies.render;
+  const env = render?.env ?? process.env;
+  const tty = render?.tty ?? Boolean(process.stdout.isTTY);
   const run = json ? null : dependencies.run ?? createInstallerRun(product, {
-    tty: Boolean(process.stdout.isTTY),
-    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
-    columns: process.stdout.columns,
+    ...render,
+    tty,
+    env,
+    color: tty && render?.color !== false && !args.includes("--no-color") && env.TERM !== "dumb",
+    columns: render?.columns ?? process.stdout.columns,
     dryRun,
+    quiet,
     operation: installed ? "install" : "update"
   });
-  run?.start();
+  if (!quiet) run?.start();
   let mark = Date.now();
+  let active;
+  let activeFacts;
+  let handedOff;
+  const shown = new Set((env.MM_FACE_CONTINUES ?? "").split(",").map((value) => value.trim()).filter(Boolean));
+  if (!quiet && !json) shown.add("welcome");
+  let phaseFailed = false;
+  let armFailed = false;
+  let knownFailure;
+  const phaseStarted = /* @__PURE__ */ new Map();
+  const phase = (event) => {
+    if (handedOff !== void 0) return;
+    if (event.state === "fail") phaseFailed = true;
+    const started = phaseStarted.get(event.id);
+    if (event.state === "running") {
+      if (started === void 0) phaseStarted.set(event.id, Date.now());
+      active = event.id;
+    } else {
+      phaseStarted.delete(event.id);
+      if (active === event.id) active = void 0;
+    }
+    if (!quiet && event.state === "running" && event.detail) run?.relay(event.detail);
+    const measured = event.measured;
+    const measure = measured?.kind === "percent" ? `${Math.max(0, Math.min(100, Math.round(measured.percent)))}%` : measured?.kind === "bytes" ? `${measured.done}/${measured.total} B` : measured?.kind === "count" ? `${measured.done}${measured.total === void 0 ? "" : `/${measured.total}`}` : event.measure;
+    const facts = {
+      state: event.state,
+      detail: event.detail,
+      measure,
+      ...event.state !== "running" && started !== void 0 ? { seconds: (Date.now() - started) / 1e3 } : {}
+    };
+    if (event.state === "running") activeFacts = facts;
+    if (!quiet) {
+      run?.phase(event.id, facts);
+      if (event.state === "ok" && run) shown.add(event.id);
+    }
+  };
   const pending = [];
   let streaming = false;
   const emitArm = ({ arm, seconds }) => {
+    if (quiet) return;
     run?.surface({
       id: arm.surface,
       from: arm.from ?? void 0,
       to: arm.to ?? void 0,
       state: arm.verdict === "fail" ? "failed" : arm.verdict === "defer" ? "retry" : arm.verdict === "skip" ? "kept" : arm.from === arm.to && !arm.launchStaged ? "current" : "updated",
       seconds,
-      detail: dependencies.diagnose(arm)
+      detail: dependencies.diagnose?.(arm)
     });
   };
+  const writeJson = (summary, schedule) => {
+    process.stdout.write(JSON.stringify(dependencies.jsonResult ? dependencies.jsonResult(summary, schedule) : installed ? { convergence: summary, autoupdate: schedule } : summary, null, 2) + "\n");
+  };
   try {
     const summary = await dependencies.engine({
       dryRun,
+      withCustody: async (operation) => {
+        if (handedOff !== void 0) throw new Error("installer terminal ownership already transferred");
+        run?.stop();
+        const result = await operation({ faceContinues: [...shown] });
+        if (result.kind === "reexec") {
+          if (!Number.isSafeInteger(result.code) || result.code < 0) throw new Error("invalid handoff exit code");
+          handedOff = result.code;
+        } else if (result.kind === "resume") {
+          if (!quiet && active) run?.phase(active, activeFacts);
+        } else throw new Error("invalid terminal custody result");
+        return result;
+      },
       shippedTarget: installed ? dependencies.shippedTarget : void 0,
-      narrate: args.includes("--verbose") ? (text) => run?.relay(text, "stderr") : void 0,
-      onTargetResolved: (target) => run?.phase("verify-release", { detail: target, state: "ok" }),
-      onPhase: () => run?.phase("check", { state: "running" }),
+      narrate: !quiet && !json && args.includes("--verbose") ? (text) => {
+        if (handedOff === void 0) run?.relay(text, "stderr", false);
+      } : void 0,
+      relay: (text, channel = "stdout", record = false) => {
+        if (handedOff === void 0) run?.relay(text, channel, record);
+      },
+      onTargetResolved: (target) => phase({ id: "verify-release", detail: target, state: "ok" }),
+      onPhase: () => {
+        if (!quiet && handedOff === void 0) run?.phase("check", { state: "running" });
+      },
+      onPhaseEvent: phase,
       onArm: (arm) => {
+        if (handedOff !== void 0) return;
+        if (arm.verdict === "fail") armFailed = true;
         const seconds = (Date.now() - mark) / 1e3;
         mark = Date.now();
         pending.push({ arm, seconds });
@@ -1113,43 +1292,68 @@ async function runMaintenance(product, args, dependencies) {
         if (streaming) for (const result of pending.splice(0)) emitArm(result);
       }
     });
+    if (handedOff !== void 0) return handedOff;
     if (summary.reexec) {
+      if (!dependencies.handOff) {
+        knownFailure = "The updated version needs a handoff, but no handoff is configured.";
+        throw new Error(knownFailure);
+      }
       run?.stop();
-      return dependencies.handOff(summary.reexec, args, { ...process.env, MM_FACE_CONTINUES: "welcome" });
+      knownFailure = "The updated updater could not launch.";
+      return await dependencies.handOff(summary.reexec, args, { ...process.env, MM_FACE_CONTINUES: "welcome" });
+    }
+    const counts2 = dependencies.counts(summary);
+    validateInstallerOutcome({ total: counts2.total, updated: counts2.updated, failed: counts2.failed });
+    if (!Number.isSafeInteger(counts2.retry) || counts2.retry < 0 || counts2.retry > counts2.total) throw new Error("invalid retry count");
+    if (summary.cancelled && summary.exit === 0 && !phaseFailed && !armFailed && counts2.failed === 0 && counts2.updated === 0) {
+      if (json) writeJson(summary, null);
+      else run?.cancel();
+      return 0;
     }
     for (const arm of pending) emitArm(arm);
     const waiting = summary.surfaces.filter((surface) => surface.present && surface.action === "arm-pending");
-    for (const surface of waiting) run?.surface({ id: surface.id, state: "pending" });
+    if (!quiet) for (const surface of waiting) run?.surface({ id: surface.id, state: "pending" });
     let schedule = null;
-    if (installed && !dryRun) {
-      const started = Date.now();
+    if (installed && !dryRun && dependencies.schedule) {
+      phase({ id: "arm", state: "running" });
       schedule = dependencies.schedule();
-      run?.phase("arm", {
-        state: schedule.ok ? "ok" : "fail",
-        seconds: (Date.now() - started) / 1e3,
-        detail: schedule.ok ? void 0 : schedule.detail
-      });
+      if (schedule) phase({ id: "arm", state: schedule.ok ? "ok" : "fail", detail: schedule.ok ? void 0 : schedule.detail });
     }
-    const counts2 = dependencies.counts(summary);
+    const failed = phaseFailed || armFailed || counts2.failed > 0 || Boolean(schedule && !schedule.ok);
+    const exit = Math.max(summary.exit, failed ? 1 : 0);
     if (json) {
-      process.stdout.write(JSON.stringify(installed ? { convergence: summary, autoupdate: schedule } : summary, null, 2) + "\n");
+      writeJson({ ...summary, exit }, schedule);
     } else {
       run.finish({
         version: summary.target ?? void 0,
         total: counts2.total,
         updated: counts2.updated,
         failed: counts2.failed,
-        operationFailed: summary.exit !== 0 || Boolean(schedule && !schedule.ok),
-        deferred: Boolean(counts2.retry || waiting.length || summary.deferred || !summary.target),
+        operationFailed: exit !== 0,
+        deferred: !failed && Boolean(counts2.retry || waiting.length || summary.deferred || summary.cancelled || !summary.target),
         dryRun,
         installed,
-        detail: schedule && !schedule.ok ? schedule.detail : summary.detail
+        detail: schedule && !schedule.ok ? schedule.detail : summary.detail ?? (summary.cancelled ? "Operation cancelled." : void 0),
+        retry: summary.retry,
+        rollback: summary.rollback,
+        logPath: summary.logPath,
+        logState: summary.logState
       });
     }
-    return Math.max(summary.exit, schedule && !schedule.ok ? 1 : 0);
+    return exit;
   } catch (error) {
-    run?.finish({ total: 0, updated: 0, failed: 0, operationFailed: true, detail: error.message });
-    if (json) throw error;
+    if (handedOff !== void 0) throw error;
+    let detail = knownFailure ?? (active === "sign-in" ? "Sign-in did not complete." : installed ? "Installation did not complete." : "Update did not complete.");
+    if (!knownFailure && dependencies.safeErrorDetail) {
+      try {
+        detail = dependencies.safeErrorDetail(error);
+      } catch {
+      }
+    }
+    if (active) phase({ id: active, state: "fail" });
+    run?.relay(detail, "stderr");
+    run?.finish({ total: 0, updated: 0, failed: 0, operationFailed: true, detail });
+    if (json) process.stdout.write(JSON.stringify({ error: detail }) + "\n");
     return 1;
   } finally {
     run?.stop();

package/dist/maintenance.d.ts

@@ -1,4 +1,4 @@
-import { type InstallerRun } from './run.js';
+import { type InstallerChannel, type InstallerFinish, type InstallerPhase, type InstallerPhaseFacts, type InstallerRunOptions, type InstallerRun } from './run.js';
 /** Facts produced by a product's convergence engine. No terminal labels or layout. */
 export interface MaintenanceArm {
     surface: string;
@@ -19,34 +19,76 @@ export interface MaintenanceSummary {
     exit: number;
     detail?: string;
     deferred?: boolean;
+    cancelled?: boolean;
+    retry?: string;
+    rollback?: InstallerFinish['rollback'];
+    logPath?: string;
+    logState?: InstallerFinish['logState'];
     reexec: {
         dist: string;
         target: string;
         from: string | null;
     } | null;
 }
+export interface MaintenancePhaseEvent {
+    id: InstallerPhase;
+    state: 'running' | 'ok' | 'fail' | 'note';
+    detail?: string;
+    measure?: InstallerPhaseFacts['measure'];
+    measured?: {
+        kind: 'percent';
+        percent: number;
+    } | {
+        kind: 'bytes';
+        done: number;
+        total: number;
+    } | {
+        kind: 'count';
+        done: number;
+        total?: number;
+    };
+}
+export type MaintenanceCustodyResult<T> = {
+    kind: 'reexec';
+    code: number;
+} | {
+    kind: 'resume';
+    value: T;
+};
+export interface MaintenanceEngineOptions {
+    dryRun: boolean;
+    withCustody: <T>(operation: (context: {
+        faceContinues: readonly string[];
+    }) => Promise<MaintenanceCustodyResult<T>>) => Promise<MaintenanceCustodyResult<T>>;
+    shippedTarget?: string;
+    narrate?: (line: string) => void;
+    onTargetResolved?: (target: string, gate: string | null) => void;
+    /** Legacy engine notification; it does not imply a completed phase. */
+    onPhase?: (line: string) => void;
+    onPhaseEvent?: (event: MaintenancePhaseEvent) => void;
+    relay?: (text: string, channel?: InstallerChannel, record?: boolean) => void;
+    onArm?: (arm: MaintenanceArm) => void;
+}
+export type MaintenanceSchedule = {
+    ok: boolean;
+    detail: string;
+} | null;
 /** One install/update lifecycle, including scheduler ordering and self-update continuation. */
 export declare function runMaintenance<S extends MaintenanceSummary>(product: unknown, args: string[], dependencies: {
-    engine: (options: {
-        dryRun: boolean;
-        shippedTarget?: string;
-        narrate?: (line: string) => void;
-        onTargetResolved?: (target: string, gate: string | null) => void;
-        onPhase?: (line: string) => void;
-        onArm?: (arm: MaintenanceArm) => void;
-    }) => Promise<S>;
+    engine: (options: MaintenanceEngineOptions) => Promise<S>;
     counts: (summary: S) => {
         total: number;
         updated: number;
         failed: number;
         retry: number;
     };
-    diagnose: (arm: MaintenanceArm) => string | undefined;
-    schedule: () => {
-        ok: boolean;
-        detail: string;
-    };
-    handOff: (next: NonNullable<S['reexec']>, args: string[], env: NodeJS.ProcessEnv) => number;
+    diagnose?: (arm: MaintenanceArm) => string | undefined;
+    schedule?: () => MaintenanceSchedule;
+    handOff?: (next: NonNullable<S['reexec']>, args: string[], env: NodeJS.ProcessEnv) => number | Promise<number>;
+    jsonResult?: (summary: S, schedule: MaintenanceSchedule) => object;
+    /** Return a safe, actionable diagnosis, never raw authentication output. */
+    safeErrorDetail?: (error: unknown) => string;
     shippedTarget?: string;
     run?: InstallerRun;
+    render?: Pick<InstallerRunOptions, 'tty' | 'color' | 'columns' | 'env' | 'animate'>;
 }): Promise<number>;

package/dist/payload.d.ts

@@ -3,5 +3,12 @@ export interface PayloadEntryOptions {
     tarballs: string[];
     converge: string[];
     shippedFlag?: string;
+    /** Converge an already installed product through this launcher's embedded runtime.
+     *  In this mode converge contains the entry's arguments, without a binary name. */
+    installedRuntime?: {
+        entry: string;
+        package: string;
+        installRootEnv: string[];
+    };
 }
-export declare function renderPayloadEntry({ tarballs, converge, shippedFlag }: PayloadEntryOptions): string;
+export declare function renderPayloadEntry({ tarballs, converge, shippedFlag, installedRuntime }: PayloadEntryOptions): string;

package/dist/run.d.ts

@@ -24,6 +24,7 @@ declare const PHASES: {
     readonly install: readonly ["Installing the product", "Installed the product"];
     readonly activate: readonly ["Activating surfaces", "Activated surfaces"];
     readonly doctor: readonly ["Checking health", "Checked health"];
+    readonly rollback: readonly ["Restoring the previous version", "Restored the previous version"];
 };
 export type InstallerPhase = keyof typeof PHASES;
 export type InstallerChannel = 'stdout' | 'stderr' | 'spinner';
@@ -31,10 +32,13 @@ export interface InstallerRunOptions {
     operation?: 'install' | 'update';
     tty?: boolean;
     dryRun?: boolean;
+    quiet?: boolean;
     color?: boolean;
     columns?: number;
     env?: Readonly<NodeJS.ProcessEnv>;
     animate?: boolean;
+    /** Optional output observer. Exceptions are recorded in run.errors, never operation failures.
+     *  Omit for production terminal output: the default worker animates during synchronous work. */
     write?: (text: string, channel: InstallerChannel) => void;
 }
 export interface InstallerFinish {
@@ -48,6 +52,9 @@ export interface InstallerFinish {
     detail?: string;
     deferred?: boolean;
     operationFailed?: boolean;
+    rollback?: 'completed' | 'partial' | 'not-needed' | 'unknown';
+    logPath?: string;
+    logState?: 'unavailable' | 'omitted';
 }
 export interface InstallerPhaseFacts {
     state?: 'running' | StepKind;
@@ -65,6 +72,7 @@ export interface InstallerSurfaceFacts {
 }
 /** One owner for the entire run. Callers supply measured facts, never terminal prose. */
 export declare function createInstallerRun(value: unknown, options?: InstallerRunOptions): {
+    readonly errors: readonly string[];
     start: () => void;
     phase(id: InstallerPhase, facts?: InstallerPhaseFacts): void;
     surface(facts: InstallerSurfaceFacts): void;
@@ -78,6 +86,7 @@ export declare function createInstallerRun(value: unknown, options?: InstallerRu
         code: string;
     }): void;
     relay(text: string, channel?: InstallerChannel, record?: boolean): void;
+    cancel(): void;
     finish(facts: InstallerFinish): void;
     stop(): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-face",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "The MM Terminal Line installer face: one renderer, the canonical product table, shell/PowerShell fragments for served one-liners, and the drift guard every surface runs.",
   "type": "module",
   "license": "UNLICENSED",