@mutmutco/installer-face 0.2.3 → 0.4.1

package/dist/index.js

@@ -1,24 +1,35 @@
+// src/face.ts
+import { writeSync } from "node:fs";
+
 // src/products.ts
 var PRODUCTS = Object.freeze({
   "mm-strategy": Object.freeze({
     name: "MM Strategy",
+    installWarm: "Welcome. Let's set up MM Strategy \u2014 about a minute.",
     accent: "38;2;249;115;22",
-    warm: "Welcome. Let's set up MM Strategy \u2014 about a minute."
+    warm: "Welcome. Let's set up MM Strategy \u2014 about a minute.",
+    doctor: "mm-strategy doctor"
   }),
   "mmi-hub": Object.freeze({
     name: "mmi-hub",
+    installWarm: "Welcome. Setting up mmi-hub \u2014 about a minute.",
     accent: "38;2;125;211;252",
-    warm: "Welcome back. Checking your surfaces\u2026"
+    warm: "Welcome back. Checking your surfaces\u2026",
+    doctor: "mmi doctor"
   }),
   "jerv-hub": Object.freeze({
     name: "jerv-hub",
+    installWarm: "Welcome. Setting up jerv-hub \u2014 about a minute.",
     accent: "38;2;248;113;113",
-    warm: "Welcome back. Checking your surfaces\u2026"
+    warm: "Welcome back. Checking your surfaces\u2026",
+    doctor: "jerv doctor"
   }),
   jervcode: Object.freeze({
     name: "JervCode",
+    installWarm: "Welcome. Setting up JervCode \u2014 about a minute.",
     accent: "38;2;192;132;252",
-    warm: "Welcome back. Keeping JervCode current\u2026"
+    warm: "Welcome back. Keeping JervCode current\u2026",
+    doctor: "jervcode doctor"
   })
 });
 function identityFor(product) {
@@ -85,7 +96,14 @@ function wrapWords(text, width) {
   if (line) lines.push(line);
   return lines.length ? lines : [""];
 }
-function createFace({ product, color = false, columns, env = process.env }) {
+var PROGRESS_PROTOCOL = 1;
+function readProgressFd(env) {
+  const fd = Number.parseInt(String(env.MM_PROGRESS_FD ?? ""), 10);
+  if (!Number.isInteger(fd) || fd <= 0) return null;
+  const protocol = Number.parseInt(String(env.MM_PROGRESS_PROTOCOL ?? PROGRESS_PROTOCOL), 10);
+  return protocol === PROGRESS_PROTOCOL ? fd : null;
+}
+function createFace({ product, color = false, columns, env = process.env, operation }) {
   const identity = identityFor(product);
   const width = faceWidth(columns);
   const paint = (sgr, text) => color ? `\x1B[${sgr}m${text}\x1B[0m` : String(text);
@@ -93,28 +111,45 @@ function createFace({ product, color = false, columns, env = process.env }) {
   const indent = " ".repeat(TITLE_COLUMN - 1);
   const continuedPhases = new Set((env.MM_FACE_CONTINUES ?? "").split(",").map((phase) => phase.trim()).filter(Boolean));
   const continuesFace = continuedPhases.size > 0;
-  const welcome = () => continuesFace ? [] : [
+  const nested = env.MM_OUTER_CONSOLE === "1";
+  const progressFd = readProgressFd(env);
+  const emitMilestone = (title, measure, kind) => {
+    if (progressFd === null) return false;
+    const record = { v: PROGRESS_PROTOCOL, step: stripColor(title), state: kind };
+    if (typeof measure === "number") record.ms = Math.max(0, Math.round(measure * 1e3));
+    try {
+      writeSync(progressFd, `${JSON.stringify(record)}
+`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const welcome = () => continuesFace || nested ? [] : [
     `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, identity.name)} \u2014 Mutatis Mutandis`,
     bar(),
-    `${bar()}  ${identity.warm}`,
+    `${bar()}  ${operation === "install" ? identity.installWarm : identity.warm}`,
     bar()
   ];
   const continues = (phase, kind = "ok") => {
     const inherited = continuedPhases.delete(String(phase).trim());
     return kind === "fail" ? false : inherited;
   };
-  const step = (title, seconds = null, kind = "ok") => {
+  const step = (title, measure = null, kind = "ok") => {
+    if (emitMilestone(title, measure, kind)) return "";
     const glyph = kind === "fail" ? paint(identity.accent, GLYPH.cross) : kind === "note" ? paint(PALETTE.muted, GLYPH.dot) : paint(PALETTE.green, GLYPH.check);
-    const time = seconds === null || seconds === void 0 ? "" : paint(PALETTE.muted, `${Math.max(0, Math.round(seconds))}s`);
+    const measured = measure === null || measure === void 0 ? "" : paint(PALETTE.muted, typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : String(measure).trim());
+    const time = measured;
     const column = Math.min(44, Math.max(0, width - 8));
-    const reserved = time ? 6 : 0;
+    const reserved = time ? Math.max(6, visibleWidth(time) + 2) : 0;
     const [first, ...rest] = wrapWords(title, width - TITLE_COLUMN - reserved);
     const head = `${bar()}  ${glyph}  ${first}`;
     const pad = Math.max(1, column - visibleWidth(head));
     return [time ? `${head}${" ".repeat(pad)}${time}` : head, ...rest.map((line) => `${bar()}${indent}${line}`)].join("\n");
   };
-  const relay = (text) => String(text).split("\n").map((line) => line.trim() === "" ? bar() : `${bar()}${indent}${line}`).join("\n");
-  const receipt = (lines) => {
+  const relay = (text) => String(text).split("\n").flatMap((line) => line.trim() === "" ? [bar()] : (visibleWidth(line) <= width - TITLE_COLUMN ? [line] : wrapWords(line, width - TITLE_COLUMN)).map((part) => `${bar()}${indent}${part}`)).join("\n");
+  const receipt = (lines, { ready = true } = {}) => {
+    if (ready && nested) return [];
     const body = (Array.isArray(lines) ? lines : String(lines).split("\n")).flatMap((raw) => {
       const line = String(raw);
       if (visibleWidth(line) <= width - 6) return [line];
@@ -130,9 +165,20 @@ function createFace({ product, color = false, columns, env = process.env }) {
       frame(GLYPH.boxBottom, GLYPH.boxBottomEnd)
     ];
   };
-  const signOff = () => `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, `${identity.name} \xB7 Mutatis Mutandis`)}`;
+  const outcome = (changed, options = {}) => {
+    const fact = String(changed ?? "").trim();
+    if (!fact) {
+      throw new Error(`installer face: the receipt must say what changed \u2014 pass the one measured fact this run produced, such as "Updated 2 of 7 surfaces to 4.4.10." (${identity.name})`);
+    }
+    return receipt([
+      `${GLYPH.check}  ${identity.name} is ready.`,
+      fact,
+      `Check health any time:  ${identity.doctor}`
+    ], options);
+  };
+  const signOff = () => nested ? "" : `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, `${identity.name} \xB7 Mutatis Mutandis`)}`;
   const refusal = (message) => `${bar()}  ${paint(identity.accent, GLYPH.cross)}  ${message}`;
-  return { identity, width, welcome, continues, step, relay, receipt, signOff, refusal, paint };
+  return { identity, width, nested, emitsProgress: progressFd !== null, welcome, continues, step, relay, receipt, outcome, signOff, refusal, paint };
 }
 
 // src/shell.ts
@@ -148,7 +194,7 @@ if [ -t 1 ] && [ -z "\${NO_COLOR:-}" ] && [ "\${TERM:-}" != 'dumb' ]; then
 fi
 FACE_NAME='${identity.name}'
 FACE_ACCENT='${identity.accent}'
-FACE_WARM='${identity.warm.replace(/'/gu, "'\\''")}'
+FACE_WARM='${identity.installWarm.replace(/'/gu, "'\\''")}'
 FACE_MUTED='${PALETTE.muted}'
 FACE_GREEN='${PALETTE.green}'
 
@@ -161,11 +207,34 @@ paint() {
   fi
 }
 
+# JSONL capture uses only POSIX awk; a bootstrap cannot require an installed Node runtime.
+face_print() {
+  face_channel="$1"
+  shift
+  face_output=$(printf "$@"; printf '.')
+  face_output=\${face_output%.}
+  if [ "$face_channel" = stdout ]; then printf '%s' "$face_output"; else printf '%s' "$face_output" >&2; fi
+  if [ -n "\${MM_FACE_TRANSCRIPT:-}" ]; then
+    MM_FACE_TEXT="$face_output" MM_FACE_CHANNEL="$face_channel" awk '
+      BEGIN {
+        for (n = 1; n < 32; n++) escapes[sprintf("%c", n)] = sprintf("\\\\u%04x", n)
+        escapes["\\\\"] = "\\\\\\\\"; escapes["\\""] = "\\\\\\""
+        printf "{\\"channel\\":\\"%s\\",\\"text\\":\\"", ENVIRON["MM_FACE_CHANNEL"]
+        text = ENVIRON["MM_FACE_TEXT"]
+        for (i = 1; i <= length(text); i++) {
+          c = substr(text, i, 1); printf "%s", (c in escapes ? escapes[c] : c)
+        }
+        print "\\"}"
+      }
+    ' >> "$MM_FACE_TRANSCRIPT"
+  fi
+}
+
 face_welcome() {
-  printf '%s  %s %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME")" '\u2014 Mutatis Mutandis'
-  printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
-  printf '%s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$FACE_WARM"
-  printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+  face_print stdout '%s  %s %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME")" '\u2014 Mutatis Mutandis'
+  face_print stdout '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+  face_print stdout '%s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$FACE_WARM"
+  face_print stdout '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
 }
 
 # face_step <title> <start epoch seconds> \u2014 one durable line for a finished step, measured.
@@ -179,7 +248,7 @@ face_step() {
   else
     face_pad=$(( 38 - \${#face_title} ))
   fi
-  printf '%s  %s  %s%*s%s\\n' \\
+  face_print stdout '%s  %s  %s%*s%s\\n' \\
     "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_GREEN" '\u2714')" "$face_title" "$face_pad" '' "$(paint "$FACE_MUTED" "\${face_secs}s")"
 }
 
@@ -187,9 +256,9 @@ face_step() {
 face_relay() {
   while IFS= read -r face_l; do
     if [ -n "$face_l" ]; then
-      printf '%s${RELAY_INDENT}%s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$face_l"
+      face_print stdout '%s${RELAY_INDENT}%s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$face_l"
     else
-      printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+      face_print stdout '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
     fi
   done
 }
@@ -220,16 +289,16 @@ face_receipt() {
   [ \${#face_text3} -gt "$face_w" ] && face_w=\${#face_text3}
   face_bar="$(paint "$FACE_ACCENT" '\u2502')"
   face_line="$(face_rule $((face_w + 4)))"
-  printf '%s\\n' "$(paint "$FACE_ACCENT" "\u256D\${face_line}\u256E")"
-  printf '%s  %s  %*s%s\\n' "$face_bar" "$(paint "$FACE_GREEN" '\u2714')  $face_text1" "$((face_w - face_w1))" '' "$face_bar"
-  printf '%s  %s%*s  %s\\n' "$face_bar" "$face_text2" "$((face_w - \${#face_text2}))" '' "$face_bar"
-  printf '%s  %s%*s  %s\\n' "$face_bar" "$face_text3" "$((face_w - \${#face_text3}))" '' "$face_bar"
-  printf '%s\\n' "$(paint "$FACE_ACCENT" "\u2570\${face_line}\u256F")"
-  printf '%s  %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME \xB7 Mutatis Mutandis")"
+  face_print stdout '%s\\n' "$(paint "$FACE_ACCENT" "\u256D\${face_line}\u256E")"
+  face_print stdout '%s  %s  %*s%s\\n' "$face_bar" "$(paint "$FACE_GREEN" '\u2714')  $face_text1" "$((face_w - face_w1))" '' "$face_bar"
+  face_print stdout '%s  %s%*s  %s\\n' "$face_bar" "$face_text2" "$((face_w - \${#face_text2}))" '' "$face_bar"
+  face_print stdout '%s  %s%*s  %s\\n' "$face_bar" "$face_text3" "$((face_w - \${#face_text3}))" '' "$face_bar"
+  face_print stdout '%s\\n' "$(paint "$FACE_ACCENT" "\u2570\${face_line}\u256F")"
+  face_print stdout '%s  %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME \xB7 Mutatis Mutandis")"
 }
 
 face_refusal() {
-  printf '%s  %s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_ACCENT" '\u2716')" "$1" >&2
+  face_print stderr '%s  %s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_ACCENT" '\u2716')" "$1"
 }
 
 # face_status <text> \u2014 transient status, redrawn in place on STDERR (0.2.0). A served script has no
@@ -246,13 +315,13 @@ face_status() {
     2) face_f='\u25D3' ;;
     *) face_f='\u25D1' ;;
   esac
-  printf '\\r\\033[2K%s  %s  %s' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_MUTED" "$face_f")" "$1" >&2
+  face_print spinner '\\r\\033[2K%s  %s  %s' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_MUTED" "$face_f")" "$1"
 }
 
 # Always call before writing the durable line, or the finished step lands on a half-drawn frame.
 face_status_clear() {
   [ -t 2 ] || return 0
-  printf '\\r\\033[2K' >&2
+  face_print spinner '\\r\\033[2K'
 }
 # <<< installer-face:end
 `;
@@ -271,7 +340,7 @@ $FaceDash = [char] 0x2014
 
 $FaceName = '${identity.name}'
 $FaceAccent = '${identity.accent}'
-$FaceWarm = '${identity.warm.replace(/'/gu, "''").replace(/\u2026/gu, "' + [char] 0x2026 + '")}'
+$FaceWarm = '${identity.installWarm.replace(/'/gu, "''").replace(/\u2026/gu, "' + [char] 0x2026 + '").replace(/\u2014/gu, "' + [char] 0x2014 + '")}'
 $FaceMuted = '${PALETTE.muted}'
 $FaceGreen = '${PALETTE.green}'
 
@@ -288,6 +357,28 @@ catch {
     # A console that refuses UTF-8 still gets the glyphs its code page can draw.
 }
 
+# Use .NET JSON serialization: no Utility-module autoload, Node, or handwritten JSON escaping.
+function Write-FaceOutput {
+    param([string] $Text, [string] $Channel = 'stdout', [switch] $NoNewline)
+    if (-not $NoNewline) { $Text += [Environment]::NewLine }
+    if ($Channel -eq 'stdout') { [Console]::Out.Write($Text) } else { [Console]::Error.Write($Text) }
+    if (-not [string]::IsNullOrEmpty($env:MM_FACE_TRANSCRIPT)) {
+        [void] [Reflection.Assembly]::Load('System.Runtime.Serialization, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089')
+        $record = [Collections.Generic.Dictionary[string,string]]::new()
+        $record.Add('channel', $Channel)
+        $record.Add('text', $Text)
+        $settings = [Runtime.Serialization.Json.DataContractJsonSerializerSettings]::new()
+        $settings.UseSimpleDictionaryFormat = $true
+        $serializer = [Runtime.Serialization.Json.DataContractJsonSerializer]::new($record.GetType(), $settings)
+        $buffer = [IO.MemoryStream]::new()
+        try {
+            $serializer.WriteObject($buffer, $record)
+            $json = [Text.Encoding]::UTF8.GetString($buffer.ToArray())
+            [IO.File]::AppendAllText($env:MM_FACE_TRANSCRIPT, $json + [Environment]::NewLine, [Text.UTF8Encoding]::new($false))
+        } finally { $buffer.Dispose() }
+    }
+}
+
 function Write-Paint {
     param([string] $Sgr, [string] $Text)
     if ($FaceColor) {
@@ -297,10 +388,10 @@ function Write-Paint {
 }
 
 function Write-FaceWelcome {
-    Write-Host ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent $FaceName) + ' ' + $FaceDash + ' Mutatis Mutandis')
-    Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
-    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + $FaceWarm)
-    Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
+    Write-FaceOutput ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent $FaceName) + ' ' + $FaceDash + ' Mutatis Mutandis')
+    Write-FaceOutput (Write-Paint $FaceMuted ([string] $FaceBar))
+    Write-FaceOutput ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + $FaceWarm)
+    Write-FaceOutput (Write-Paint $FaceMuted ([string] $FaceBar))
 }
 
 # A title longer than the step column is shortened in the middle: a path's start and tail identify it.
@@ -317,17 +408,17 @@ function Get-FaceTitle {
 function Write-FaceStep {
     param([string] $Title, [DateTime] $Started)
     $seconds = [Math]::Max(0, [int] ([DateTime]::UtcNow - $Started).TotalSeconds)
-    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceGreen ([string] $FaceCheck)) + '  ' + (Get-FaceTitle $Title).PadRight(38) + ' ' + (Write-Paint $FaceMuted ($seconds.ToString() + 's')))
+    Write-FaceOutput ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceGreen ([string] $FaceCheck)) + '  ' + (Get-FaceTitle $Title).PadRight(38) + ' ' + (Write-Paint $FaceMuted ($seconds.ToString() + 's')))
 }
 
 # Another program's output, kept inside the face at the step-title column.
 function Write-FaceRelay {
     param([string] $Line)
     if ([string]::IsNullOrWhiteSpace($Line)) {
-        Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
+        Write-FaceOutput (Write-Paint $FaceMuted ([string] $FaceBar))
         return
     }
-    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '${RELAY_INDENT}' + $Line)
+    Write-FaceOutput ((Write-Paint $FaceMuted ([string] $FaceBar)) + '${RELAY_INDENT}' + $Line)
 }
 
 function Write-FaceReceipt {
@@ -337,17 +428,17 @@ function Write-FaceReceipt {
     $third = 'Check health any time:  ' + $Next
     $inner = ($first.Length, $second.Length, $third.Length | Measure-Object -Maximum).Maximum
     $rule = [string]::new([char] 0x2500, $inner + 4)
-    Write-Host (Write-Paint $FaceAccent ([string] [char] 0x256D + $rule + [char] 0x256E))
+    Write-FaceOutput (Write-Paint $FaceAccent ([string] [char] 0x256D + $rule + [char] 0x256E))
     foreach ($text in @($first, $second, $third)) {
-        Write-Host ((Write-Paint $FaceAccent ([string] $FaceBar)) + '  ' + $text.PadRight($inner) + '  ' + (Write-Paint $FaceAccent ([string] $FaceBar)))
+        Write-FaceOutput ((Write-Paint $FaceAccent ([string] $FaceBar)) + '  ' + $text.PadRight($inner) + '  ' + (Write-Paint $FaceAccent ([string] $FaceBar)))
     }
-    Write-Host (Write-Paint $FaceAccent ([string] [char] 0x2570 + $rule + [char] 0x256F))
-    Write-Host ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent ($FaceName + ' ' + [char] 0x00B7 + ' Mutatis Mutandis')))
+    Write-FaceOutput (Write-Paint $FaceAccent ([string] [char] 0x2570 + $rule + [char] 0x256F))
+    Write-FaceOutput ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent ($FaceName + ' ' + [char] 0x00B7 + ' Mutatis Mutandis')))
 }
 
 function Write-FaceRefusal {
     param([string] $Message)
-    [Console]::Error.WriteLine((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceAccent ([string] $FaceCross)) + '  ' + $Message)
+    Write-FaceOutput -Channel stderr ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceAccent ([string] $FaceCross)) + '  ' + $Message)
 }
 
 # Transient status, redrawn in place on STDERR (0.2.0). Frames are emitted BY CODE POINT for the same
@@ -363,7 +454,7 @@ function Write-FaceStatus {
     }
     $script:FaceFrame = ($script:FaceFrame + 1) % $FaceFrames.Length
     $line = (Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceMuted ([string] $FaceFrames[$script:FaceFrame])) + '  ' + $Text
-    [Console]::Error.Write([string] [char] 13 + ([char] 27) + '[2K' + $line)
+    Write-FaceOutput -Channel spinner -NoNewline ([string] [char] 13 + ([char] 27) + '[2K' + $line)
 }
 
 # Always call before writing the durable line.
@@ -371,7 +462,7 @@ function Clear-FaceStatus {
     if ([Console]::IsErrorRedirected) {
         return
     }
-    [Console]::Error.Write([string] [char] 13 + ([char] 27) + '[2K')
+    Write-FaceOutput -Channel spinner -NoNewline ([string] [char] 13 + ([char] 27) + '[2K')
 }
 # <<< installer-face:end
 `;
@@ -419,35 +510,109 @@ function clip(text, width) {
 }
 
 // src/spinner.ts
+import { appendFileSync, writeSync as writeSync2 } from "node:fs";
+import { Worker } from "node:worker_threads";
 var FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
-function createSpinner(face, { animate, stream = process.stderr, intervalMs = 90 }) {
+var WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const { writeSync, appendFileSync } = require('node:fs');
+const control = new Int32Array(workerData.control);
+let frames = workerData.frames, frame = workerData.frame;
+function draw() {
+  if (Atomics.compareExchange(control, 1, 0, 1) !== 0) return;
+  try {
+    if (Atomics.load(control, 0) || Atomics.load(control, 2) || !frames.length) return;
+    const text = frames[frame++ % frames.length];
+    writeSync(2, text);
+    if (workerData.transcriptPath) appendFileSync(workerData.transcriptPath, JSON.stringify({ channel: 'spinner', text }) + '\\n');
+  } finally {
+    Atomics.store(control, 1, 0);
+    Atomics.notify(control, 1);
+  }
+}
+parentPort.on('message', (next) => {
+  if (Atomics.load(control, 2)) return;
+  frames = next.frames;
+  frame = next.frame;
+  Atomics.store(control, 0, 0);
+});
+setInterval(draw, workerData.intervalMs);
+`;
+function createSpinner(face, { animate, stream, intervalMs = 90, transcriptPath }) {
+  animate = animate && !face.nested && !face.emitsProgress;
   let timer = null;
-  let text = "";
+  let worker = null;
+  let control = null;
+  let frames = [];
   let frame = 0;
-  const clear = () => {
-    if (animate) stream.write("\r\x1B[2K");
+  const write = (text) => {
+    if (stream) stream.write(text);
+    else {
+      writeSync2(2, text);
+      if (transcriptPath) appendFileSync(transcriptPath, `${JSON.stringify({ channel: "spinner", text })}
+`);
+    }
+  };
+  const render = (text, measure) => {
+    const line = face.step(text, measure, "note").split("\n")[0];
+    frames = line ? FRAMES.map((glyph) => `\r\x1B[2K${line.replace(GLYPH.dot, glyph)}`) : [];
   };
   const draw = () => {
-    if (!animate) return;
-    const line = face.step(text, null, "note").split("\n")[0].replace(GLYPH.dot, FRAMES[frame % FRAMES.length]);
-    stream.write(`\r\x1B[2K${line}`);
-    frame += 1;
+    if (animate && frames.length) write(frames[frame++ % frames.length]);
+  };
+  const pause = () => {
+    if (!control) return;
+    Atomics.store(control, 0, 1);
+    while (Atomics.load(control, 1)) Atomics.wait(control, 1, 1);
+  };
+  const halt = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    if (control) Atomics.store(control, 2, 1);
+    pause();
+    if (worker) void worker.terminate();
+    worker = null;
+    control = null;
   };
   return {
-    start(next) {
-      text = next;
+    start(text, measure = null) {
+      if (!animate) return;
+      halt();
+      render(text, measure);
       frame = 0;
       draw();
-      if (animate && !timer) timer = setInterval(draw, intervalMs).unref();
+      if (!frames.length) return;
+      if (stream) timer = setInterval(draw, intervalMs).unref();
+      else {
+        control = new Int32Array(new SharedArrayBuffer(12));
+        try {
+          worker = new Worker(WORKER_SOURCE, { eval: true, workerData: {
+            control: control.buffer,
+            frames,
+            frame,
+            intervalMs,
+            transcriptPath
+          } });
+          const active = worker;
+          worker.on("error", () => {
+            if (worker === active) halt();
+          });
+          worker.unref();
+        } catch {
+          halt();
+        }
+      }
     },
-    say(next) {
-      text = next;
+    say(text, measure = null) {
+      if (!animate) return;
+      pause();
+      render(text, measure);
       draw();
+      worker?.postMessage({ frames, frame });
     },
     stop() {
-      if (timer) clearInterval(timer);
-      timer = null;
-      clear();
+      halt();
+      if (animate) write("\r\x1B[2K");
     }
   };
 }
@@ -475,7 +640,42 @@ function assertFaceConformance(lines, options) {
   const head = plain[0] ?? "";
   const signOffLine = `${GLYPH.diamond}  ${identity.name} \xB7 Mutatis Mutandis`;
   const opensWithWelcome = head.startsWith(GLYPH.diamond) && head !== signOffLine;
+  if (options.complete && options.tty !== false) {
+    const welcome = `${GLYPH.diamond}  ${identity.name} \u2014 Mutatis Mutandis`;
+    const welcomes = plain.filter((line) => line === welcome).length;
+    const receipts = plain.filter((line) => line.startsWith(GLYPH.boxTop)).length;
+    const signOffs = plain.filter((line) => line === signOffLine).length;
+    if (welcomes !== (options.nested ? 0 : 1) || signOffs !== (options.nested ? 0 : 1) || !options.nested && receipts !== 1) {
+      fail("complete run", "expected one console owner, one welcome, one receipt and one sign-off");
+    }
+    for (const line of plain) {
+      if (line && ![GLYPH.bar, GLYPH.diamond, GLYPH.hollow, GLYPH.boxTop, GLYPH.boxBottom].some((glyph) => line.startsWith(glyph))) {
+        fail("complete run", `unframed output: ${JSON.stringify(line)}`);
+      }
+    }
+  }
   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`));
+  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");
+  }
+  if (options.nested === true) {
+    if (opensWithWelcome) {
+      fail("R8 a nested run draws no welcome", `an outer console already greeted the user; this run opened with ${JSON.stringify(head)}`);
+    }
+    const signOffAt = plain.findIndex((line) => line === signOffLine);
+    if (signOffAt !== -1) {
+      fail("R8 a nested run draws no sign-off", `the outer console closes the run; line ${signOffAt + 1} signs off`);
+    }
+    const boxAt = plain.findIndex((line) => line.startsWith(GLYPH.boxTop));
+    if (boxAt !== -1) {
+      const headline = plain.slice(boxAt + 1).find((line) => line.startsWith(GLYPH.bar) && line.trim() !== GLYPH.bar) ?? "";
+      if (headline.includes(GLYPH.check)) {
+        fail("R8 a nested run draws no success receipt", `the outer console owns the outcome; this run printed ${JSON.stringify(headline.trim())}`);
+      }
+    }
+  }
   if (options.tty === false) {
     for (const line of plain) {
       const glyph = [...line].find((char) => ALLOWED.has(char));
@@ -511,6 +711,14 @@ function assertFaceConformance(lines, options) {
     if (!plain[bottom].endsWith(GLYPH.boxBottomEnd)) fail("R5 receipt frame", `the bottom row does not pair its corners: ${JSON.stringify(plain[bottom])}`);
     const widths = new Set(plain.slice(top, bottom + 1).map(visibleWidth));
     if (widths.size !== 1) fail("R5 receipt frame", `the box is ragged: widths ${[...widths].join(", ")}`);
+    const rows = plain.slice(top + 1, bottom);
+    if (rows.length > 0 && rows[0].includes(GLYPH.check)) {
+      if (rows.length < 3) {
+        fail("R9 the receipt says what changed", `a success receipt has three lines \u2014 ready, what changed, the health command \u2014 and this one has ${rows.length}: ${JSON.stringify(rows.map((row) => row.trim()))}`);
+      }
+      const changed = rows[1].replace(GLYPH.bar, "").trim();
+      if (changed === "") fail("R9 the receipt says what changed", "the middle line of the success receipt is blank");
+    }
   }
   const inReceipt = (index) => top !== -1 && index >= top && index <= plain.findIndex((line, at) => at > top && line.startsWith(GLYPH.boxBottom));
   const welcomeEnd = opensWithWelcome ? 4 : 0;
@@ -544,7 +752,7 @@ function assertFaceConformance(lines, options) {
   if (opensWithWelcome) {
     const expected = `${GLYPH.diamond}  ${identity.name} \u2014 Mutatis Mutandis`;
     if (head !== expected) fail("welcome is the product table's", `expected ${JSON.stringify(expected)}, got ${JSON.stringify(head)}`);
-    const warm = plain.slice(1, 4).find((line) => line.includes(identity.warm));
+    const warm = plain.slice(1, 4).find((line) => line.includes(identity.warm) || line.includes(identity.installWarm));
     if (!warm) fail("welcome is the product table's", `the warm line for ${options.product} is missing or reworded`);
   }
   const painted = rendered.join("\n");
@@ -579,6 +787,391 @@ function assertScriptConformance(script, options) {
   }
   if (!/NO_COLOR/u.test(text)) fail("served script", "NO_COLOR must disable colour");
 }
+
+// src/run.ts
+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 flags = ["dryRun", "installed", "deferred", "operationFailed"];
+function validateInstallerOutcome(value) {
+  const invalid = () => {
+    throw new Error("installer outcome: invalid child result");
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
+  const facts = value;
+  const allowed = [...counts, ...strings, ...flags];
+  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();
+  return { ...facts };
+}
+function writeInstallerOutcome(path, value) {
+  writeFileSync(path, JSON.stringify(validateInstallerOutcome(value)), { encoding: "utf8", mode: 384 });
+}
+function readInstallerOutcome(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  if (text.length > 16384) throw new Error("installer outcome: child result is too large");
+  try {
+    return validateInstallerOutcome(JSON.parse(text));
+  } catch {
+    throw new Error("installer outcome: invalid child result");
+  }
+}
+
+// src/run.ts
+function validateInstallerProduct(value) {
+  const fail2 = (field) => {
+    throw new Error(`installer product: invalid ${field}`);
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail2("declaration");
+  const input = value;
+  const text = (value2, field) => typeof value2 === "string" && value2.trim() && !/[\r\n\x00-\x1f]/u.test(value2) ? value2 : fail2(field);
+  const key = text(input.product, "product");
+  const product = { mmi: "mmi-hub", jerv: "jerv-hub" }[key] ?? key;
+  const identity = identityFor(product);
+  const gate = text(input.gate, "gate");
+  let gateUrl;
+  try {
+    gateUrl = new URL(gate);
+  } catch {
+    return fail2("gate");
+  }
+  if (!["https:", "http:"].includes(gateUrl.protocol) || gateUrl.username || gateUrl.password) return fail2("gate");
+  const doctor = text(input.doctor, "doctor");
+  if (doctor !== identity.doctor) return fail2("doctor");
+  if (!Array.isArray(input.surfaces) || input.surfaces.length === 0) return fail2("surfaces");
+  const ids = /* @__PURE__ */ new Set();
+  const surfaces = input.surfaces.map((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail2("surface");
+    const source = raw;
+    const id = text(source.id, "surface.id");
+    if (ids.has(id)) return fail2("duplicate surface.id");
+    ids.add(id);
+    const surface = { id };
+    for (const field of ["npm", "bin", "kind", "activation"]) {
+      if (source[field] !== void 0) surface[field] = text(source[field], `surface.${field}`);
+    }
+    if (Boolean(surface.npm) !== Boolean(surface.bin)) return fail2("surface npm/bin pair");
+    if (surface.kind !== void 0 && !["agent-home", "payload"].includes(surface.kind)) return fail2("surface.kind");
+    if (!surface.npm && !surface.kind) return fail2("surface implementation");
+    return surface;
+  });
+  return { product, gate, doctor, surfaces };
+}
+var PHASES = {
+  preflight: ["Checking prerequisites", "Checked prerequisites"],
+  resolve: ["Resolving the release", "Resolved the release"],
+  download: ["Downloading the payload", "Downloaded the payload"],
+  "sign-in": ["Signing in", "Signed in"],
+  check: ["Checking surfaces", "Checked surfaces"],
+  arm: ["Scheduling updates", "Armed hourly updates"],
+  "verify-release": ["Checking the release version", "Verified the release version"],
+  verify: ["Verifying the payload", "Verified the payload"],
+  install: ["Installing the product", "Installed the product"],
+  activate: ["Activating surfaces", "Activated surfaces"],
+  doctor: ["Checking health", "Checked health"]
+};
+function createInstallerRun(value, options = {}) {
+  const declaration = validateInstallerProduct(value);
+  const env = options.env ?? process.env;
+  const tty = options.tty ?? Boolean(process.stdout.isTTY);
+  const face = createFace({
+    operation: options.operation,
+    product: declaration.product,
+    columns: options.columns,
+    env,
+    color: tty && options.color !== false && env.NO_COLOR === void 0
+  });
+  const write = options.write ?? ((text, channel) => {
+    (channel === "stdout" ? process.stdout : process.stderr).write(text);
+  });
+  const emit = (text, channel = "stdout", recorded = text) => {
+    if (!text) return;
+    write(text, channel);
+    if (env.MM_FACE_TRANSCRIPT) {
+      appendFileSync2(env.MM_FACE_TRANSCRIPT, `${JSON.stringify({ channel, text: recorded })}
+`, "utf8");
+    }
+  };
+  const lines = (rows, channel = "stdout") => {
+    for (const row of rows.flatMap((row2) => row2.split("\n"))) if (row) emit(`${row}
+`, channel);
+  };
+  const spinner = createSpinner(face, {
+    animate: tty && env.TERM !== "dumb" && (options.animate ?? Boolean(process.stderr.isTTY)),
+    ...options.write ? { stream: { write: (text) => {
+      emit(String(text), "spinner");
+      return true;
+    } } } : { transcriptPath: env.MM_FACE_TRANSCRIPT }
+  });
+  let started = false;
+  let finished = false;
+  const start = () => {
+    if (started || finished) return;
+    started = true;
+    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]);
+  };
+  const durable = (title, measure, kind) => {
+    spinner.stop();
+    const rendered = face.step(title, measure, kind);
+    if (rendered) lines([tty ? rendered : `${kind === "fail" ? "Failed: " : ""}${title}${measure === null ? "" : ` (${typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : measure})`}`]);
+  };
+  const run = {
+    start,
+    phase(id, facts = {}) {
+      if (finished) throw new Error("installer run already finished");
+      if (!Object.hasOwn(PHASES, id)) throw new Error("installer run: unknown phase");
+      start();
+      const state = facts.state ?? "ok";
+      const title = PHASES[id][state === "ok" ? 1 : 0];
+      if (state === "running") {
+        spinner.start(title, facts.measure ?? null);
+        return;
+      }
+      if (!face.continues(id, state)) durable(title, facts.seconds ?? facts.measure ?? null, state);
+      if (facts.detail) run.relay(facts.detail);
+    },
+    surface(facts) {
+      if (finished) throw new Error("installer run already finished");
+      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 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 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");
+      if (facts.detail) run.relay(facts.detail);
+    },
+    milestone({ step, state, ms }) {
+      start();
+      durable(step, ms === void 0 ? null : ms / 1e3, state);
+    },
+    signIn({ url, code }) {
+      start();
+      spinner.stop();
+      for (const text of [`Open ${url}`, `Enter code: ${code}`]) {
+        const rendered = `${tty ? face.relay(text) : text}
+`;
+        emit(rendered, "stdout", rendered.replace(code, "[redacted]"));
+      }
+    },
+    // Only pass safe diagnostic text, never authentication output or credentials.
+    relay(text, channel = "stdout", record = true) {
+      spinner.stop();
+      const rendered = tty ? face.relay(text) : stripColor(text);
+      for (const row of rendered.split("\n")) if (row) {
+        emit(`${row}
+`, channel, record ? `${row}
+` : `${tty ? face.relay("[external output omitted]") : "[external output omitted]"}
+`);
+      }
+    },
+    finish(facts) {
+      if (finished) return;
+      validateInstallerOutcome(facts);
+      if (env.MM_INSTALLER_OUTCOME_FILE) writeInstallerOutcome(env.MM_INSTALLER_OUTCOME_FILE, facts);
+      start();
+      spinner.stop();
+      finished = true;
+      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 = [
+        `${ready ? GLYPH.check : facts.dryRun ? GLYPH.dot : GLYPH.cross}  ${face.identity.name}${ready ? " is ready." : facts.dryRun ? " preview complete." : facts.deferred ? " update deferred." : " is not ready yet."}`,
+        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}`
+      ];
+      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, "")));
+      }
+      if (tty) lines([face.signOff()]);
+    },
+    stop() {
+      spinner.stop();
+    }
+  };
+  return run;
+}
+async function runInstaller(value, operation, options) {
+  const run = createInstallerRun(value, options);
+  run.start();
+  try {
+    const result = await operation(run);
+    run.finish(result);
+    return result;
+  } finally {
+    run.stop();
+  }
+}
+
+// src/payload.ts
+function renderPayloadEntry({ tarballs, converge, shippedFlag }) {
+  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");
+  }
+  if (!Array.isArray(converge) || converge.length === 0 || converge.some((arg) => typeof arg !== "string" || !arg.trim() || /[\x00-\x1f"&|<>^%!`()]/u.test(arg))) {
+    throw new Error("installer payload: invalid converge argv");
+  }
+  if (shippedFlag !== void 0 && !/^--[a-z][a-z0-9-]*$/u.test(shippedFlag)) {
+    throw new Error("installer payload: invalid shipped flag");
+  }
+  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';
+
+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 };
+  // 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, options);
+  if (result.error || result.status !== 0) {
+    process.stderr.write('Installer operation failed.\n');
+    process.exit(result.status === null || result.status === undefined ? 1 : result.status);
+  }
+}
+
+step('npm', ['install', '--global', '--no-fund', '--no-audit', ...tarballs]);
+let shipped = null;
+if (shippedFlag) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(payloadDir, 'payload.json'), 'utf8'));
+    shipped = typeof manifest.version === 'string' ? manifest.version.trim() || null : null;
+  } catch {
+    // Older/manual payloads have no manifest version and retain the plain converge operation.
+  }
+  if (shipped && !/^[A-Za-z0-9][A-Za-z0-9.+-]*$/.test(shipped)) {
+    process.stderr.write('Installer payload has an invalid shipped version.\n');
+    process.exit(1);
+  }
+  if (!shipped) process.stdout.write('Payload carries no shipped version; running the declared operation.\n');
+}
+step(converge[0], [...converge.slice(1), ...(shipped ? [shippedFlag, shipped] : [])]);
+`;
+}
+
+// src/maintenance.ts
+async function runMaintenance(product, args, dependencies) {
+  const json = args.includes("--json");
+  const dryRun = args.includes("--dry-run");
+  const installed = args.includes("install");
+  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,
+    dryRun,
+    operation: installed ? "install" : "update"
+  });
+  run?.start();
+  let mark = Date.now();
+  const pending = [];
+  let streaming = false;
+  const emitArm = ({ arm, seconds }) => {
+    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)
+    });
+  };
+  try {
+    const summary = await dependencies.engine({
+      dryRun,
+      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" }),
+      onArm: (arm) => {
+        const seconds = (Date.now() - mark) / 1e3;
+        mark = Date.now();
+        pending.push({ arm, seconds });
+        if (pending.length > 1) streaming = true;
+        if (streaming) for (const result of pending.splice(0)) emitArm(result);
+      }
+    });
+    if (summary.reexec) {
+      run?.stop();
+      return dependencies.handOff(summary.reexec, args, { ...process.env, MM_FACE_CONTINUES: "welcome" });
+    }
+    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" });
+    let schedule = null;
+    if (installed && !dryRun) {
+      const started = Date.now();
+      schedule = dependencies.schedule();
+      run?.phase("arm", {
+        state: schedule.ok ? "ok" : "fail",
+        seconds: (Date.now() - started) / 1e3,
+        detail: schedule.ok ? void 0 : schedule.detail
+      });
+    }
+    const counts2 = dependencies.counts(summary);
+    if (json) {
+      process.stdout.write(JSON.stringify(installed ? { convergence: summary, autoupdate: schedule } : summary, null, 2) + "\n");
+    } 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),
+        dryRun,
+        installed,
+        detail: schedule && !schedule.ok ? schedule.detail : summary.detail
+      });
+    }
+    return Math.max(summary.exit, schedule && !schedule.ok ? 1 : 0);
+  } catch (error) {
+    run?.finish({ total: 0, updated: 0, failed: 0, operationFailed: true, detail: error.message });
+    if (json) throw error;
+    return 1;
+  } finally {
+    run?.stop();
+  }
+}
+
+// src/transcript.ts
+function assertInstallerTranscript(jsonl, options, reference) {
+  const parse = (text) => text.trim().split(/\r?\n/u).filter(Boolean).map((line) => {
+    const record = JSON.parse(line);
+    if (!record || typeof record !== "object" || Array.isArray(record) || Object.keys(record).some((key) => key !== "channel" && key !== "text") || !["stdout", "stderr", "spinner"].includes(String(record.channel)) || typeof record.text !== "string") {
+      throw new Error("installer transcript: invalid record");
+    }
+    return { channel: String(record.channel), text: record.text };
+  });
+  const records = parse(jsonl);
+  const lines = records.filter((record) => record.channel !== "spinner").map((record) => record.text).join("").split(/\r?\n/u).filter(Boolean);
+  assertFaceConformance(lines, { ...options, complete: true });
+  if (reference !== void 0 && JSON.stringify(records) !== JSON.stringify(parse(reference))) {
+    throw new Error("installer transcript: output differs from the reviewed reference");
+  }
+}
 export {
   GLYPH,
   PALETTE,
@@ -586,15 +1179,24 @@ export {
   SPINNER_FRAMES,
   TITLE_COLUMN,
   assertFaceConformance,
+  assertInstallerTranscript,
   assertScriptConformance,
   createFace,
+  createInstallerRun,
   createSpinner,
   faceWidth,
   identityFor,
+  readInstallerOutcome,
+  renderPayloadEntry,
   renderPowerShellFace,
   renderRows,
   renderShellFace,
+  runInstaller,
+  runMaintenance,
   stripColor,
+  validateInstallerOutcome,
+  validateInstallerProduct,
   visibleWidth,
-  wrapWords
+  wrapWords,
+  writeInstallerOutcome
 };