From 0d4c27a1f7d15a5c39211e31a2e1205a47784a0b Mon Sep 17 00:00:00 2001
From: Lior <lior@zeta.dev>
Date: Tue, 26 May 2026 00:19:12 -0400
Subject: [PATCH] =?UTF-8?q?feat(B-0789=20iter-4.2):=20zflash=20auto-inject?=
 =?UTF-8?q?=20of=20SSH=20pubkey=20to=20boot=20USB=20ESP=20+=20zeta-install?=
 =?UTF-8?q?.sh=20USB=20probe=20=E2=86=92=20zero-typing=20SSH=20access=20on?=
 =?UTF-8?q?=20first=20cluster=20boot?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The maintainer's actually-usable iter-4 path (v1 was scaffolding-only;
this PR is the workflow Aaron will test against). Per Aaron's 2026-05-26
discipline signals:

1. "we can do what's going to make cluster setup eaiser for me and not
   users if that's ssh lets do that first cause we want to get ai
   running the cluster asap" — iter-4 authorized
2. "i can wait for 4.2 or whatever version before we try again" —
   downgraded v1 to scaffolding; this PR is what Aaron flashes
3. "--no-creds is basically useless right?" — opt-out removed from
   recommended path (kept as --no-inject escape hatch only)
4. "whenever i have to ferry commands by reading and typing i'm going
   to avoid it like the plague and try to get like pictures and auto
   run and short commands pre built in" — design discipline: ALL
   diagnostics auto-fire in-place + are photo-friendly; zero operator-
   typed commands beyond `zflash`

Files:

- full-ai-cluster/tools/flash-usb.ts: added `--no-eject` flag (4 lines)
  so zflash can do post-flash ESP-mount-and-write before the USB ejects.
  Allowlist updated per the Copilot P0 catch about destructive-tool
  flag validation. Help text mentions iter-4.2 use case

- full-ai-cluster/tools/zflash.ts: extended with post-flash macOS-side
  ESP-mount-and-write step:
    * Default reads ~/.ssh/id_ed25519.pub
    * --ssh-key <path> overrides
    * --no-inject opt-out (escape hatch only)
    * Re-scans external disks post-flash (flash-usb's single-USB-only
      requirement guarantees exactly one external disk)
    * Identifies FAT/EFI partition via `diskutil list` regex match
      (DOS_FAT / EFI / MS-DOS / FAT16 / FAT32 / Windows_FAT)
    * Mounts via `diskutil mount`; gets mount point from `diskutil info`
    * Writes <mount>/zeta-authorized-keys.pub via `sudo tee` (stdin
      avoids shell-quoting hazards)
    * Unmounts + ejects when done
    * dumpDiagnostics() helper auto-runs on any failure path:
      diskutil list external + mounted /Volumes/* + "what to do next"
      suggestions. Compact + photo-friendly per the design discipline

- full-ai-cluster/usb-nixos-installer/zeta-install.sh: added step 6.5
  pre-install pubkey probe + injection:
    * Try 1: scan /iso /run /mnt /boot for zeta-authorized-keys.pub
      via `sudo find -maxdepth 5`
    * Try 2: probe USB partitions (/dev/sd? /dev/nvme?n? /dev/vd?
      /dev/mmcblk?, minus install targets) via vfat-readonly mount +
      file existence check. Partition suffix handling: 1/2 on sd/vd;
      p1/p2 on nvme/mmcblk
    * If found: writes operator-ssh-keys.nix with valid ssh-* lines
      from the file BEFORE nixos-install
    * If not found: diagnostics auto-fire (external block devices,
      install targets, full lsblk, "what to do next") + falls back to
      v1 stub
    * Post-install credentials echo branches on INJECT_OK: success
      path says "SSH works immediately"; fallback keeps v1 manual-
      edit + nixos-rebuild instructions
    * shellcheck clean (fixed SC2261 redundant stderr redirect)

- docs/backlog/P1/B-0789-*.md: updated iter-4.2 acceptance to reflect
  what shipped: [x] flash-usb.ts --no-eject; [x] zflash.ts ESP inject;
  [x] zeta-install.sh probe + inject + branched credentials echo;
  [ ] maintainer flashes + tests on PC; [ ] if failure: photo-driven
  fix-forward workflow per the maintainer's explicit design choice

Composes with PR #5080 (iter-4 v1 scaffolding: initial-password.nix +
operator-ssh-keys.nix stub + per-host imports) which this PR builds on.
The zero-typing target: `zflash` → boot USB on PC → install → SSH-able
as zeta@<hostname> from the maintainer's Mac using the existing
~/.ssh/id_ed25519 key. Failure path: photo of auto-diagnostics →
AI fixes-forward.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...ubstrate-for-cluster-bringup-2026-05-26.md |  29 +-
 full-ai-cluster/tools/flash-usb.ts            |  28 +-
 full-ai-cluster/tools/zflash.ts               | 278 +++++++++++++++++-
 .../usb-nixos-installer/zeta-install.sh       | 140 ++++++++-
 4 files changed, 434 insertions(+), 41 deletions(-)

diff --git a/docs/backlog/P1/B-0789-iter4-ssh-key-and-hashedpassword-substrate-for-cluster-bringup-2026-05-26.md b/docs/backlog/P1/B-0789-iter4-ssh-key-and-hashedpassword-substrate-for-cluster-bringup-2026-05-26.md
index 01ca4f7df6..2050cc0cd0 100644
--- a/docs/backlog/P1/B-0789-iter4-ssh-key-and-hashedpassword-substrate-for-cluster-bringup-2026-05-26.md
+++ b/docs/backlog/P1/B-0789-iter4-ssh-key-and-hashedpassword-substrate-for-cluster-bringup-2026-05-26.md
@@ -92,25 +92,30 @@ The maintainer 2026-05-26: *"i can wait for 4.2 or whatever version before we tr
 
 ### iter-4.2 acceptance (target the maintainer will actually test against)
 
-- [ ] `full-ai-cluster/tools/zflash.ts` extended (or new sibling `zflash-creds.ts`) with post-flash macOS-side ESP-mount-and-write step:
+Note: the maintainer 2026-05-26 *"--no-creds is basically useless right?"* signal removed the opt-out flag from the original design. The default behavior IS the new behavior; opt-out (renamed `--no-inject`) exists only as an escape hatch for the operator who explicitly wants the old flash-only flow without the pubkey-write step.
+
+- [x] `full-ai-cluster/tools/flash-usb.ts` extended with `--no-eject` flag so zflash can do the ESP-mount-and-write before the USB ejects (4-line change; allowlist + skip-eject branch)
+- [x] `full-ai-cluster/tools/zflash.ts` extended with post-flash macOS-side ESP-mount-and-write step:
   - Default reads `~/.ssh/id_ed25519.pub`
   - `--ssh-key <path>` overrides
-  - `--no-creds` opts out (preserves current zflash behavior)
-  - Mounts the FAT / ESP partition of the flashed USB via `diskutil mount`
-  - Writes `/Volumes/<label>/zeta-authorized-keys.pub` with the pubkey content
-  - Unmounts via `diskutil unmount`
-  - Substrate-honest about the macOS ESP-mount substrate (diskutil idempotency, label discovery, eject timing — verify before shipping)
-- [ ] `usb-nixos-installer/zeta-install.sh` extended with pre-install pubkey-inject step:
-  - Probes the boot USB's ESP for `zeta-authorized-keys.pub` after step 6 (clone)
-  - If found: rewrites `/mnt/etc/zeta/full-ai-cluster/nixos/modules/operator-ssh-keys.nix` with the pubkey injection BEFORE `nixos-install`
-  - If not found: leaves the stub unchanged (v1 fallback path; manual edit + rebuild after login)
-  - Post-install credentials echo updated to reflect "SSH works immediately" when pubkey was injected vs "edit-and-rebuild required" when stub stayed empty
+  - `--no-inject` opt-out (escape hatch only; not the recommended path)
+  - Re-scans external disks post-flash; finds the (single) freshly-flashed USB
+  - Identifies the FAT / EFI partition via `diskutil list` regex match (DOS_FAT / EFI / MS-DOS / FAT16 / FAT32 / Windows_FAT)
+  - Mounts via `diskutil mount <part>`; gets mount point from `diskutil info`
+  - Writes `<mount>/zeta-authorized-keys.pub` via `sudo tee` (stdin avoids shell-quoting hazards)
+  - Unmounts via `diskutil unmount`; ejects whole disk via `diskutil eject`
+  - Diagnostics auto-fire on any failure (photo-friendly: external-disk list, mounted USB volumes, "what to do next" suggestions)
+- [x] `usb-nixos-installer/zeta-install.sh` extended with pre-install pubkey-inject step:
+  - Step 6.5 probe: scans `/iso /run /mnt /boot` for `zeta-authorized-keys.pub`; if not found, probes USB partitions (`/dev/sd? /dev/nvme?n? /dev/vd? /dev/mmcblk?` minus install targets) via vfat-readonly mount + file existence check
+  - If found: writes `operator-ssh-keys.nix` with valid `ssh-*` lines from the file BEFORE `nixos-install`
+  - If not found: diagnostics auto-fire (external block devices, install targets, full lsblk, "what to do next") + falls back to v1 stub
+  - Post-install credentials echo branches on `INJECT_OK`: success path says "SSH works immediately"; fallback path keeps the v1 manual-edit + nixos-rebuild instructions
 - [ ] Maintainer flashes iter-4.2 USB once (single `zflash` invocation; no extra flags needed for default-key case)
   - Plugs into PC 1 (or PC 2 / PC 3)
   - Install runs zero-typing
   - PC X reboots; tty1 login as `zeta` / `zeta-change-me` works (initial-password substrate from v1)
   - `ssh zeta@<hostname>` from the maintainer's Mac works immediately — this is the iter-4.2 end-to-end success criterion
-- [ ] Documentation in the post-install echo block reflects the iter-4.2 zero-typing flow; v1's manual-edit fallback paragraph stays as the explicit-opt-out path
+- [ ] If failure: the auto-diagnostics output gets photographed + sent back; AI fixes-forward against the actual substrate the photo reveals (this is the photo-driven-diagnostics workflow the maintainer explicitly chose per 2026-05-26 *"i'm going to avoid it like the plague and try to get like pictures and auto run and short commands pre built in"*)
 
 ### Why ship v1 separately if 4.2 is the maintainer-usable target
 
diff --git a/full-ai-cluster/tools/flash-usb.ts b/full-ai-cluster/tools/flash-usb.ts
index 1b0ae60e85..393018e085 100755
--- a/full-ai-cluster/tools/flash-usb.ts
+++ b/full-ai-cluster/tools/flash-usb.ts
@@ -156,7 +156,7 @@ async function main() {
   // accepting unknown flags like `--dry-run` or a misspelled `--short`
   // would proceed to sudo dd despite operator intent. Bail explicitly
   // on any unrecognized flag.
-  const ALLOWED_FLAGS = new Set(["--short", "-h", "--help"]);
+  const ALLOWED_FLAGS = new Set(["--short", "--no-eject", "-h", "--help"]);
   const rawFlags = argv.filter((a) => a.startsWith("-"));
   const positional = argv.filter((a) => !a.startsWith("-"));
   const unknownFlags = rawFlags.filter((f) => !ALLOWED_FLAGS.has(f));
@@ -170,11 +170,15 @@ async function main() {
   }
   const flags = new Set(rawFlags);
   const useShortChallenge = flags.has("--short");
+  const noEject = flags.has("--no-eject");
   const isHelp = flags.has("-h") || flags.has("--help");
   if (isHelp || positional.length !== 1) {
     process.stdout.write(
-      "Usage: bun full-ai-cluster/tools/flash-usb.ts [--short] <path-to-iso>\n" +
-        "  --short   use shorter `yes <4-hex>` challenge format\n",
+      "Usage: bun full-ai-cluster/tools/flash-usb.ts [--short] [--no-eject] <path-to-iso>\n" +
+        "  --short      use shorter `yes <4-hex>` challenge format\n" +
+        "  --no-eject   leave the USB attached after dd (for downstream tooling\n" +
+        "               like zflash's iter-4.2 ESP-mount + pubkey-inject step;\n" +
+        "               downstream MUST eject itself when done)\n",
     );
     process.exit(isHelp && positional.length === 0 ? 0 : 2);
   }
@@ -437,14 +441,20 @@ async function main() {
     bail(code, `dd exited ${code}; partial flash may be on device.`);
   }
 
-  process.stdout.write(`\nEjecting ${device} ...\n`);
-  try {
-    execFileSync("diskutil", ["eject", device], { stdio: "inherit" });
-  } catch {
+  if (noEject) {
     process.stdout.write(
-      "(eject failed; that is fine — the flash succeeded. " +
-        "Unplug + replug to verify.)\n",
+      `\n(--no-eject passed; ${device} remains attached for downstream tooling)\n`,
     );
+  } else {
+    process.stdout.write(`\nEjecting ${device} ...\n`);
+    try {
+      execFileSync("diskutil", ["eject", device], { stdio: "inherit" });
+    } catch {
+      process.stdout.write(
+        "(eject failed; that is fine — the flash succeeded. " +
+          "Unplug + replug to verify.)\n",
+      );
+    }
   }
 
   process.stdout.write("\nFlash complete.\n");
diff --git a/full-ai-cluster/tools/zflash.ts b/full-ai-cluster/tools/zflash.ts
index 8757d0e94f..90f8fec559 100755
--- a/full-ai-cluster/tools/zflash.ts
+++ b/full-ai-cluster/tools/zflash.ts
@@ -7,6 +7,15 @@
 // flash-usb with the `--short` challenge format, and lets sudo's PAM
 // stack (Touch ID, after `zflash-setup` ran) gate the dd.
 //
+// iter-4.2 extension (B-0789): after the dd succeeds, zflash also
+// mounts the freshly-flashed USB's FAT ESP partition + writes the
+// operator's SSH pubkey to it as `/zeta-authorized-keys.pub` so
+// `zeta-install.sh` on the booted installer can pick it up + inject
+// into `operator-ssh-keys.nix` before `nixos-install`. Result: full
+// zero-typing flow from `zflash` on macOS → bootable USB → boot on
+// PC → install completes → SSH-able as `zeta` user with the operator's
+// existing key.
+//
 // End-to-end keystrokes after first-time setup:
 //
 //   $ bun full-ai-cluster/tools/zflash.ts
@@ -14,9 +23,11 @@
 //   USB: /dev/disk6 (115 GiB, USB 3.2.1 FD)
 //   *** ALL DATA ON /dev/disk6 WILL BE DESTROYED ***
 //   type: yes a3f9
-//   > yes a3f9         ← 8 chars; per-run random; can't be pre-baked
-//   [Touch ID prompt]   ← finger on trackpad; PAM gate
+//   > yes a3f9             ← 8 chars; per-run random; can't be pre-baked
+//   [Touch ID prompt]       ← finger on trackpad; PAM gate
 //   Flash complete.
+//   iter-4.2: injecting ~/.ssh/id_ed25519.pub into /dev/disk6 ESP ...
+//   iter-4.2: pubkey written; USB ejected. Safe to remove.
 //
 // Recommended shell alias (set up by zflash-setup) — note the path
 // is shell-quoted so checkout paths containing spaces / unicode work
@@ -31,6 +42,16 @@
 //   - Explicit consent token `yes` (not a stray Enter keypress)
 //   - Touch ID PAM gate on the sudo dd (biometric proof of physical
 //     presence; replaces password typing)
+//   - iter-4.2 inject: macOS-side `diskutil mount` + `sudo tee` write;
+//     read-only on the operator's `~/.ssh/id_ed25519.pub` (default) or
+//     the path passed via `--ssh-key <path>`. NEVER writes to user keys.
+//
+// Diagnostic discipline (per maintainer 2026-05-26 *"whenever i have to
+// ferry commands by reading and typing i'm going to avoid it like the
+// plague and try to get like pictures and auto run and short commands
+// pre built in"*): all failure paths AUTO-RUN diagnostics in-place.
+// No "now run this command to debug" — diagnostic output is photo-
+// friendly + appears immediately so the operator can snap + send.
 //
 // Agent-driven mode:
 //   When the runner is an authorized agent acting on the operator's
@@ -42,12 +63,13 @@
 //   finger on the actual trackpad.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const ISO_GLOB_PREFIX = "zeta-installer-";
+const DEFAULT_SSH_KEY = join(homedir(), ".ssh", "id_ed25519.pub");
 
 function bail(code: number, msg: string): never {
   process.stderr.write(`zflash: ${msg}\n`);
@@ -99,6 +121,192 @@ function findFlashUsbPath(): string {
   return sibling;
 }
 
+// ── iter-4.2 helpers (B-0789) ──────────────────────────────────────
+
+interface ExternalDiskBrief {
+  device: string; // e.g., /dev/disk6
+}
+
+function listExternalDisks(): ExternalDiskBrief[] {
+  // diskutil list external prints disk headers like "/dev/disk6 (external, physical):"
+  // Per-device, captures the path.
+  try {
+    const out = execFileSync("diskutil", ["list", "external"], { encoding: "utf8" });
+    const matches = [...out.matchAll(/^(\/dev\/disk\d+)\s+\(external/gm)];
+    return matches.map((m) => ({ device: m[1]! }));
+  } catch {
+    return [];
+  }
+}
+
+function findFatPartition(device: string): string | null {
+  // diskutil list <device> output includes lines per partition with
+  // type-info like "DOS_FAT_32" / "EFI" / "Microsoft Basic Data".
+  // Returns the partition device path (e.g., /dev/disk6s2) or null.
+  try {
+    const out = execFileSync("diskutil", ["list", device], { encoding: "utf8" });
+    const lines = out.split("\n");
+    for (const line of lines) {
+      // FAT/EFI partitions show up with types like:
+      //   2: EFI EFI                  209.7 MB   disk6s1
+      //   2: DOS_FAT_32 NIXOS_ISO     65.5 MB    disk6s2
+      // Be lenient — accept anything FAT/EFI/MS-DOS-shaped.
+      if (/\b(DOS_FAT|EFI|MS-DOS|FAT16|FAT32|Windows_FAT)\b/i.test(line)) {
+        const m = line.match(/\b(disk\d+s\d+)\s*$/);
+        if (m) return `/dev/${m[1]}`;
+      }
+    }
+  } catch {
+    /* fall through to null */
+  }
+  return null;
+}
+
+function getMountPoint(partition: string): string | null {
+  try {
+    const out = execFileSync("diskutil", ["info", partition], { encoding: "utf8" });
+    const m = out.match(/^\s*Mount Point:\s+(.+)$/m);
+    return m && m[1] && m[1].trim() !== "" ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function dumpDiagnostics(context: string): void {
+  // Photo-friendly compact diagnostic block per maintainer 2026-05-26
+  // discipline. Keep section count low + critical info at top so the
+  // operator can snap a single screenshot + send.
+  process.stderr.write(`\n=== iter-4.2 DIAGNOSTICS ===\n`);
+  process.stderr.write(`reason: ${context}\n`);
+  process.stderr.write(`\n--- diskutil list external ---\n`);
+  try {
+    process.stderr.write(execFileSync("diskutil", ["list", "external"], { encoding: "utf8" }));
+  } catch (e) {
+    process.stderr.write(`(diskutil list external failed: ${e instanceof Error ? e.message : String(e)})\n`);
+  }
+  process.stderr.write(`--- mounted USB volumes (/Volumes/*) ---\n`);
+  try {
+    const mountOut = execFileSync("mount", [], { encoding: "utf8" });
+    const usbLines = mountOut.split("\n").filter((l) => l.includes("/Volumes/"));
+    process.stderr.write(usbLines.length > 0 ? usbLines.join("\n") + "\n" : "(no /Volumes mounts)\n");
+  } catch (e) {
+    process.stderr.write(`(mount failed: ${e instanceof Error ? e.message : String(e)})\n`);
+  }
+  process.stderr.write(
+    `--- what to do next ---\n` +
+      `  - photograph the diagnostic block above + send to your AI collaborator\n` +
+      `  - OR re-plug the USB and re-run: zflash\n` +
+      `  - OR boot the cluster node + fall back to iter-4 v1 manual SSH-key flow\n` +
+      `    (login as zeta/zeta-change-me, passwd zeta, edit operator-ssh-keys.nix,\n` +
+      `    sudo nixos-rebuild switch --flake /etc/zeta/full-ai-cluster#<host>)\n` +
+      `============================\n\n`,
+  );
+}
+
+async function injectPubkeyToUsb(pubkeyPath: string): Promise<void> {
+  process.stdout.write(`\niter-4.2: injecting ${pubkeyPath} into freshly-flashed USB ESP ...\n`);
+
+  // Brief settle so macOS re-reads partition table after dd
+  await new Promise((r) => setTimeout(r, 2000));
+
+  // Re-scan external disks. flash-usb enforces single-USB-only so after a
+  // successful flash (--no-eject) there's exactly one external disk visible.
+  const externalDisks = listExternalDisks();
+  if (externalDisks.length === 0) {
+    dumpDiagnostics("no external USB visible post-flash");
+    bail(3, "iter-4.2 inject failed: no external USB disks found after flash. Re-plug + re-run zflash.");
+  }
+  if (externalDisks.length > 1) {
+    dumpDiagnostics(`expected exactly 1 external USB; saw ${externalDisks.length}`);
+    bail(
+      3,
+      `iter-4.2 inject failed: expected 1 external USB post-flash, saw ${externalDisks.length}. Unplug all but the flashed USB and re-run.`,
+    );
+  }
+  const flashedDevice = externalDisks[0]!.device;
+  process.stdout.write(`iter-4.2: target device ${flashedDevice}\n`);
+
+  // Find the FAT ESP partition (typical NixOS installer ISO leaves one at partition 2)
+  const espPart = findFatPartition(flashedDevice);
+  if (!espPart) {
+    dumpDiagnostics(`no FAT/EFI partition found on ${flashedDevice}`);
+    bail(3, `iter-4.2 inject failed: ${flashedDevice} has no FAT/EFI partition for pubkey-write.`);
+  }
+  process.stdout.write(`iter-4.2: ESP partition ${espPart}\n`);
+
+  // Mount it (diskutil mount may not need sudo if the ESP auto-mounts)
+  try {
+    execFileSync("diskutil", ["mount", espPart], { stdio: "inherit" });
+  } catch (e) {
+    dumpDiagnostics(`diskutil mount ${espPart} failed`);
+    bail(
+      3,
+      `iter-4.2 inject failed: diskutil mount ${espPart} failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  // Get mount point
+  const mountPoint = getMountPoint(espPart);
+  if (!mountPoint) {
+    dumpDiagnostics(`no Mount Point in diskutil info ${espPart}`);
+    try {
+      execFileSync("diskutil", ["unmount", espPart], { stdio: "ignore" });
+    } catch {
+      /* ignore */
+    }
+    bail(3, `iter-4.2 inject failed: mounted ${espPart} but couldn't determine mount point.`);
+  }
+  process.stdout.write(`iter-4.2: mounted at ${mountPoint}\n`);
+
+  // Read pubkey content
+  const pubkey = readFileSync(pubkeyPath, "utf8").trim();
+  const firstLine = pubkey.split("\n")[0] ?? "";
+  if (!/^ssh-(ed25519|rsa|ecdsa|dss)\s+/.test(firstLine)) {
+    try {
+      execFileSync("diskutil", ["unmount", espPart], { stdio: "ignore" });
+    } catch {
+      /* ignore */
+    }
+    dumpDiagnostics(`${pubkeyPath} first line is not a valid ssh-* pubkey`);
+    bail(3, `iter-4.2 inject failed: ${pubkeyPath} is not a recognized SSH pubkey format.`);
+  }
+
+  // Write via sudo tee (stdin avoids shell-quoting hazards)
+  const target = join(mountPoint, "zeta-authorized-keys.pub");
+  try {
+    execFileSync("sudo", ["tee", target], {
+      input: pubkey + "\n",
+      stdio: ["pipe", "ignore", "inherit"],
+    });
+  } catch (e) {
+    dumpDiagnostics(`sudo tee ${target} failed`);
+    try {
+      execFileSync("diskutil", ["unmount", espPart], { stdio: "ignore" });
+    } catch {
+      /* ignore */
+    }
+    bail(3, `iter-4.2 inject failed: sudo tee ${target} failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  process.stdout.write(`iter-4.2: wrote pubkey to ${target}\n`);
+
+  // Unmount
+  try {
+    execFileSync("diskutil", ["unmount", espPart], { stdio: "inherit" });
+  } catch {
+    process.stdout.write(`(unmount of ${espPart} reported error; that is usually safe to ignore.)\n`);
+  }
+
+  // Eject the whole disk so operator can safely remove
+  try {
+    execFileSync("diskutil", ["eject", flashedDevice], { stdio: "inherit" });
+    process.stdout.write(`iter-4.2: ${flashedDevice} ejected; safe to remove USB.\n`);
+  } catch {
+    process.stdout.write(
+      `(eject ${flashedDevice} reported error; safe to remove USB anyway.)\n`,
+    );
+  }
+}
+
 async function main() {
   if (platform() !== "darwin") {
     bail(2, "zflash is macOS-only; for Linux see the manual flow in flash-usb.ts header");
@@ -109,10 +317,36 @@ async function main() {
   // (`zflash --dry-run`) or extra arg (`zflash a.iso b.iso`) would still
   // proceed to sudo dd. Allowlist flags + bail on unrecognized or
   // duplicate-positional.
-  const ALLOWED_FLAGS = new Set(["-h", "--help"]);
+  const ALLOWED_FLAGS = new Set(["-h", "--help", "--ssh-key", "--no-inject"]);
   const argv = process.argv.slice(2);
-  const rawFlags = argv.filter((a) => a.startsWith("-"));
-  const positional = argv.filter((a) => !a.startsWith("-"));
+
+  // Two-arg flag parsing for --ssh-key <path>
+  let sshKeyOverride: string | null = null;
+  let noInject = false;
+  const rawFlags: string[] = [];
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--ssh-key") {
+      const next = argv[i + 1];
+      if (!next || next.startsWith("-")) {
+        bail(2, "--ssh-key requires a path argument (e.g., --ssh-key ~/.ssh/id_ed25519.pub)");
+      }
+      sshKeyOverride = resolve(next);
+      i++;
+      continue;
+    }
+    if (a === "--no-inject") {
+      noInject = true;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      rawFlags.push(a);
+      continue;
+    }
+    positional.push(a);
+  }
+
   const unknownFlags = rawFlags.filter((f) => !ALLOWED_FLAGS.has(f));
   if (unknownFlags.length > 0) {
     bail(
@@ -133,8 +367,13 @@ async function main() {
   const isHelp = rawFlags.includes("-h") || rawFlags.includes("--help");
   if (isHelp) {
     process.stdout.write(
-      "Usage: bun full-ai-cluster/tools/zflash.ts [iso-path]\n" +
-        "  Auto-discovers newest ~/Downloads/zeta-installer-*.iso if no path.\n" +
+      "Usage: bun full-ai-cluster/tools/zflash.ts [--ssh-key <path>] [--no-inject] [iso-path]\n" +
+        "  --ssh-key <path>  override default ~/.ssh/id_ed25519.pub for iter-4.2 inject\n" +
+        "  --no-inject       skip the iter-4.2 ESP pubkey write (USB will boot but\n" +
+        "                    cluster node won't have SSH access until manual edit +\n" +
+        "                    nixos-rebuild on first login per iter-4 v1 fallback)\n" +
+        "  iso-path          (optional) explicit ISO; default = newest\n" +
+        "                    ~/Downloads/zeta-installer-*.iso\n" +
         "  Run zflash-setup once first to install Touch ID for sudo.\n",
     );
     process.exit(0);
@@ -144,10 +383,25 @@ async function main() {
   const isoPath = explicit ? resolve(explicit) : autoDiscoverIso();
   const flashUsb = findFlashUsbPath();
 
+  // Pre-flight: determine if iter-4.2 inject will run + which key
+  const pubkeyPath = sshKeyOverride ?? DEFAULT_SSH_KEY;
+  let willInject = !noInject;
+  if (willInject && !existsSync(pubkeyPath)) {
+    process.stderr.write(
+      `\nzflash: iter-4.2 inject skipped — pubkey not found at ${pubkeyPath}\n` +
+        `  (proceeding with flash; cluster node will need manual operator-ssh-keys.nix\n` +
+        `   edit + nixos-rebuild on first login per iter-4 v1 fallback)\n\n`,
+    );
+    willInject = false;
+  }
+
   // Stdio inherit — child handles all I/O directly (readline, sudo Touch ID
   // PAM prompt, dd progress). We are a thin invocation wrapper.
+  const flashUsbArgs = willInject
+    ? [flashUsb, "--short", "--no-eject", isoPath]
+    : [flashUsb, "--short", isoPath];
   try {
-    execFileSync("bun", [flashUsb, "--short", isoPath], { stdio: "inherit" });
+    execFileSync("bun", flashUsbArgs, { stdio: "inherit" });
   } catch (e: unknown) {
     // execFileSync throws on non-zero exit; child has already printed its
     // own error message + exited with its own code via flash-usb's bail().
@@ -158,6 +412,12 @@ async function main() {
         : 1;
     process.exit(status);
   }
+
+  if (willInject) {
+    await injectPubkeyToUsb(pubkeyPath);
+  } else {
+    process.stdout.write("\n(iter-4.2 inject skipped per --no-inject or missing pubkey)\n");
+  }
 }
 
 main().catch((err) => {
diff --git a/full-ai-cluster/usb-nixos-installer/zeta-install.sh b/full-ai-cluster/usb-nixos-installer/zeta-install.sh
index d5362604dd..43a0dabfb8 100755
--- a/full-ai-cluster/usb-nixos-installer/zeta-install.sh
+++ b/full-ai-cluster/usb-nixos-installer/zeta-install.sh
@@ -226,6 +226,116 @@ sudo git clone "$REPO_URL" /mnt/etc/zeta
 echo "Generating hardware-configuration.nix ..."
 sudo nixos-generate-config --root /mnt --force
 
+# ── Step 6.5: iter-4.2 probe boot USB for operator SSH pubkey ────
+# Per B-0789: zflash on macOS writes ~/.ssh/id_ed25519.pub to the
+# boot USB's FAT ESP as `zeta-authorized-keys.pub`. Find it + inject
+# into operator-ssh-keys.nix before nixos-install so the freshly-
+# installed system has SSH access on first boot. Diagnostics auto-run
+# on failure (photo-friendly per the maintainer's 2026-05-26
+# discipline); fallback path = iter-4 v1 manual edit + nixos-rebuild
+# after first login.
+echo
+echo "[iter-4.2] probing boot USB for operator SSH pubkey ..."
+PUBKEY_DST="/mnt/etc/zeta/full-ai-cluster/nixos/modules/operator-ssh-keys.nix"
+PROBE_MOUNT="/tmp/zeta-boot-esp"
+sudo mkdir -p "$PROBE_MOUNT"
+
+PUBKEY_FILE=""
+INJECT_OK=0
+
+# Try 1: scan already-mounted filesystems
+PUBKEY_FILE=$(sudo find /iso /run /mnt /boot \
+  -maxdepth 5 -name "zeta-authorized-keys.pub" -type f 2>/dev/null | head -1)
+
+# Try 2: probe likely-USB block devices for a FAT partition with the pubkey.
+# Skip BOOT_DISK + DATA_DISKS (install targets).
+if [ -z "$PUBKEY_FILE" ]; then
+  echo "[iter-4.2]   not in mounted FS; probing USB partitions ..."
+  for dev in /dev/sd? /dev/nvme?n? /dev/vd? /dev/mmcblk?; do
+    [ -b "$dev" ] || continue
+    [ "$dev" = "$BOOT_DISK" ] && continue
+    skip=0
+    for data in "${DATA_DISKS[@]}"; do
+      [ "$dev" = "$data" ] && { skip=1; break; }
+    done
+    [ "$skip" = 1 ] && continue
+
+    # Partition suffix is 1/2 on sd/vd; p1/p2 on nvme/mmcblk
+    for partsfx in 2 1; do
+      case "$dev" in
+        /dev/nvme*|/dev/mmcblk*) part="${dev}p${partsfx}" ;;
+        *) part="${dev}${partsfx}" ;;
+      esac
+      [ -b "$part" ] || continue
+      if sudo mount -t vfat -o ro "$part" "$PROBE_MOUNT" 2>/dev/null; then
+        if [ -f "$PROBE_MOUNT/zeta-authorized-keys.pub" ]; then
+          PUBKEY_FILE="$PROBE_MOUNT/zeta-authorized-keys.pub"
+          break 2
+        fi
+        sudo umount "$PROBE_MOUNT" 2>/dev/null || true
+      fi
+    done
+  done
+fi
+
+if [ -n "$PUBKEY_FILE" ]; then
+  echo "[iter-4.2]   found: $PUBKEY_FILE"
+
+  KEY_LINES=()
+  while IFS= read -r line; do
+    case "$line" in
+      ssh-ed25519\ *|ssh-rsa\ *|ssh-ecdsa\ *|ssh-dss\ *|ecdsa-*) KEY_LINES+=("$line") ;;
+    esac
+  done < "$PUBKEY_FILE"
+
+  if [ ${#KEY_LINES[@]} -gt 0 ]; then
+    {
+      echo '# operator-ssh-keys.nix — populated by iter-4.2 zeta-install.sh probe.'
+      echo "# Source: $PUBKEY_FILE (boot USB ESP)"
+      echo "# Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+      echo
+      echo '{ config, pkgs, lib, ... }:'
+      echo
+      echo '{'
+      echo '  users.users.zeta.openssh.authorizedKeys.keys = ['
+      for line in "${KEY_LINES[@]}"; do
+        printf '    "%s"\n' "$line"
+      done
+      echo '  ];'
+      echo '}'
+    } | sudo tee "$PUBKEY_DST" > /dev/null
+    echo "[iter-4.2]   injected ${#KEY_LINES[@]} pubkey(s) into operator-ssh-keys.nix"
+    sudo umount "$PROBE_MOUNT" 2>/dev/null || true
+    INJECT_OK=1
+  else
+    echo "[iter-4.2]   WARN: $PUBKEY_FILE contained no valid ssh-* lines"
+    echo "[iter-4.2]          operator-ssh-keys.nix stub stays empty"
+    sudo umount "$PROBE_MOUNT" 2>/dev/null || true
+  fi
+else
+  echo
+  echo "=== [iter-4.2] DIAGNOSTICS ==="
+  echo "reason: no operator SSH pubkey found on boot USB ESP"
+  echo
+  echo "--- external block devices ---"
+  ls /dev/sd? /dev/nvme?n? /dev/vd? /dev/mmcblk? 2>/dev/null || echo "(none)"
+  echo
+  echo "--- install targets (skipped during probe) ---"
+  echo "  boot disk:  $BOOT_DISK"
+  echo "  data disks: ${DATA_DISKS[*]:-(none)}"
+  echo
+  echo "--- lsblk (full topology) ---"
+  lsblk 2>&1 || true
+  echo
+  echo "--- what to do next ---"
+  echo "  - photograph this diagnostic block + send to your AI collaborator"
+  echo "  - install will continue with EMPTY operator-ssh-keys.nix"
+  echo "  - fallback (iter-4 v1): on first boot, login as zeta/zeta-change-me,"
+  echo "    passwd zeta, edit /etc/zeta/full-ai-cluster/nixos/modules/operator-ssh-keys.nix,"
+  echo "    sudo nixos-rebuild switch --flake /etc/zeta/full-ai-cluster#$HOST"
+  echo "=============================="
+fi
+
 echo "Running nixos-install --flake /mnt/etc/zeta/full-ai-cluster#$HOST ..."
 sudo nixos-install --flake "/mnt/etc/zeta/full-ai-cluster#$HOST" --no-root-password
 
@@ -240,17 +350,25 @@ echo
 echo "    user:     zeta"
 echo "    password: zeta-change-me"
 echo
-echo "  AFTER FIRST LOGIN:"
-echo "    1. passwd zeta            # rotate the initial password"
-echo "    2. Edit /etc/zeta/full-ai-cluster/nixos/modules/operator-ssh-keys.nix"
-echo "       and add your ssh-ed25519 pubkey, then:"
-echo "    3. sudo nixos-rebuild switch --flake /etc/zeta/full-ai-cluster#$HOST"
-echo "    4. Verify SSH from your workstation:"
-echo "       ssh zeta@\$(hostname)"
-echo
-echo "  (Per docs/backlog/P1/B-0789 iter-4: SSH-key auto-inject from"
-echo "   the boot USB is a follow-up — for v1, the SSH key flow is"
-echo "   manual edit + nixos-rebuild as above.)"
+if [ "$INJECT_OK" = 1 ]; then
+  echo "  iter-4.2 SSH-KEY INJECTION: SUCCESS"
+  echo "    SSH access works on first boot from the workstation that flashed this USB:"
+  echo "      ssh zeta@\$(hostname)"
+  echo
+  echo "  AFTER FIRST LOGIN:"
+  echo "    1. passwd zeta            # rotate the initial password"
+  echo "    2. (SSH already works — no manual edit + rebuild required)"
+else
+  echo "  iter-4.2 SSH-KEY INJECTION: SKIPPED (see diagnostics above)"
+  echo
+  echo "  AFTER FIRST LOGIN (fallback to iter-4 v1 manual flow):"
+  echo "    1. passwd zeta            # rotate the initial password"
+  echo "    2. Edit /etc/zeta/full-ai-cluster/nixos/modules/operator-ssh-keys.nix"
+  echo "       and add your ssh-ed25519 pubkey, then:"
+  echo "    3. sudo nixos-rebuild switch --flake /etc/zeta/full-ai-cluster#$HOST"
+  echo "    4. Verify SSH from your workstation:"
+  echo "       ssh zeta@\$(hostname)"
+fi
 echo
 echo "================================================================"
 echo