@wlfi-agent/cli 1.4.16 → 1.4.18

package/src/cli.ts

@@ -1,5 +1,6 @@
+import { setTimeout as sleep } from 'node:timers/promises';
 import * as configPackage from '../packages/config/src/index.js';
-import * as rpcPackage from '../packages/rpc/src/index.ts';
+import * as rpcPackage from '../packages/rpc/src/index.js';
 import type { ChainProfile, TokenChainProfile, WlfiConfig } from '../packages/config/src/index.js';
 import { Command, Option } from 'commander';
 import { type Address, type Hex, isAddress, isHex } from 'viem';
@@ -29,6 +30,7 @@ import {
   encodeErc20ApproveData,
   encodeErc20TransferData,
   formatBroadcastedAssetOutput,
+  resolveEstimatedPriorityFeePerGasWei,
   resolveAssetBroadcastPlan,
   waitForOnchainReceipt,
 } from './lib/asset-broadcast.js';
@@ -151,6 +153,14 @@ interface RustManualApprovalRequiredOutput {
   cli_approval_command: string;
 }
 
+type AgentCommandAttemptResult<T> =
+  | { type: 'success'; value: T }
+  | {
+      type: 'manualApproval';
+      output: RustManualApprovalRequiredOutput;
+      exitCode: number;
+    };
+
 function rewriteAgentAmountError(
   error: unknown,
   symbolAwareAsset: { decimals: number; symbol: string; assetId: string },
@@ -179,10 +189,12 @@ function isManualApprovalRequiredOutput(value: unknown): value is RustManualAppr
   );
 }
 
-function printManualApprovalRequired(output: RustManualApprovalRequiredOutput, asJson: boolean) {
+function renderManualApprovalRequired(
+  output: RustManualApprovalRequiredOutput,
+  asJson: boolean,
+): string {
   if (asJson) {
-    print(output, true);
-    return;
+    return formatJson(output);
   }
 
   const lines = [
@@ -196,7 +208,37 @@ function printManualApprovalRequired(output: RustManualApprovalRequiredOutput, a
     lines.push(`Relay URL: ${output.relay_url}`);
   }
   lines.push(`CLI Approval Command: ${output.cli_approval_command}`);
-  print(lines.join('\n'), false);
+  return lines.join('\n');
+}
+
+function printManualApprovalRequired(
+  output: RustManualApprovalRequiredOutput,
+  asJson: boolean,
+  useStderr = false,
+) {
+  const rendered = renderManualApprovalRequired(output, asJson);
+  if (useStderr) {
+    console.error(rendered);
+    return;
+  }
+  console.log(rendered);
+}
+
+function printManualApprovalWaiting(
+  output: RustManualApprovalRequiredOutput,
+  asJson: boolean,
+) {
+  if (asJson) {
+    console.error(
+      formatJson({
+        event: 'manualApprovalPending',
+        approvalRequestId: output.approval_request_id,
+      }),
+    );
+    return;
+  }
+
+  console.error(`Waiting for manual approval decision: ${output.approval_request_id}`);
 }
 
 const MAX_SECRET_STDIN_BYTES = 16 * 1024;
@@ -335,6 +377,16 @@ function print(payload: unknown, asJson: boolean) {
 
 const ONCHAIN_RECEIPT_TIMEOUT_MS = 30_000;
 const ONCHAIN_RECEIPT_POLL_INTERVAL_MS = 2_000;
+const MANUAL_APPROVAL_POLL_INTERVAL_MS = 2_000;
+const MANUAL_APPROVAL_WAIT_TIMEOUT_MS =
+  (() => {
+    const raw = process.env.WLFI_TEST_MANUAL_APPROVAL_TIMEOUT_MS;
+    if (!raw) {
+      return 5 * 60_000;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 5 * 60_000;
+  })();
 
 async function reportOnchainReceiptStatus(input: {
   rpcUrl: string;
@@ -510,44 +562,45 @@ async function resolveAgentCommandContext(
   return { agentKeyId, agentAuthToken, daemonSocket };
 }
 
-async function runAgentCommandJson<T>(input: {
+async function runAgentCommandJsonOnce<T>(input: {
   commandArgs: string[];
-  auth: AgentCommandAuthOptions;
   config: WlfiConfig;
-  asJson: boolean;
-}): Promise<T | null> {
-  const { agentKeyId, agentAuthToken, daemonSocket } = await resolveAgentCommandContext(
-    input.auth,
-    input.config,
-  );
-
+  agentKeyId: string;
+  agentAuthToken: string;
+  daemonSocket: string;
+}): Promise<AgentCommandAttemptResult<T>> {
   try {
-    return await runRustBinaryJson<T>(
-      'wlfi-agent-agent',
-      [
-        '--json',
-        '--agent-key-id',
-        agentKeyId,
-        '--agent-auth-token-stdin',
-        '--daemon-socket',
-        daemonSocket,
-        ...input.commandArgs,
-      ],
-      input.config,
-      {
-        stdin: `${agentAuthToken}\n`,
-        preSuppliedSecretStdin: 'agentAuthToken',
-        scrubSensitiveEnv: true,
-      },
-    );
+    return {
+      type: 'success',
+      value: await runRustBinaryJson<T>(
+        'wlfi-agent-agent',
+        [
+          '--json',
+          '--agent-key-id',
+          input.agentKeyId,
+          '--agent-auth-token-stdin',
+          '--daemon-socket',
+          input.daemonSocket,
+          ...input.commandArgs,
+        ],
+        input.config,
+        {
+          stdin: `${input.agentAuthToken}\n`,
+          preSuppliedSecretStdin: 'agentAuthToken',
+          scrubSensitiveEnv: true,
+        },
+      ),
+    };
   } catch (error) {
     if (error instanceof RustBinaryExitError && error.stdout.trim()) {
       try {
         const parsed = JSON.parse(error.stdout) as unknown;
         if (isManualApprovalRequiredOutput(parsed)) {
-          printManualApprovalRequired(parsed, input.asJson);
-          process.exitCode = error.code;
-          return null;
+          return {
+            type: 'manualApproval',
+            output: parsed,
+            exitCode: error.code,
+          };
         }
       } catch {
         // fall through to the original error
@@ -557,6 +610,64 @@ async function runAgentCommandJson<T>(input: {
   }
 }
 
+async function runAgentCommandJson<T>(input: {
+  commandArgs: string[];
+  auth: AgentCommandAuthOptions;
+  config: WlfiConfig;
+  asJson: boolean;
+  waitForManualApproval?: boolean;
+}): Promise<T | null> {
+  const { agentKeyId, agentAuthToken, daemonSocket } = await resolveAgentCommandContext(
+    input.auth,
+    input.config,
+  );
+
+  const runOnce = () =>
+    runAgentCommandJsonOnce<T>({
+      commandArgs: input.commandArgs,
+      config: input.config,
+      agentKeyId,
+      agentAuthToken,
+      daemonSocket,
+    });
+
+  const firstAttempt = await runOnce();
+  if (firstAttempt.type === 'success') {
+    return firstAttempt.value;
+  }
+
+  if (!input.waitForManualApproval) {
+    printManualApprovalRequired(firstAttempt.output, input.asJson);
+    process.exitCode = firstAttempt.exitCode;
+    return null;
+  }
+
+  printManualApprovalRequired(firstAttempt.output, input.asJson, true);
+  printManualApprovalWaiting(firstAttempt.output, input.asJson);
+  const pendingApprovalRequestId = firstAttempt.output.approval_request_id;
+  const startedWaitingAt = Date.now();
+
+  for (;;) {
+    await sleep(MANUAL_APPROVAL_POLL_INTERVAL_MS);
+    const nextAttempt = await runOnce();
+    if (nextAttempt.type === 'success') {
+      return nextAttempt.value;
+    }
+
+    if (nextAttempt.output.approval_request_id !== pendingApprovalRequestId) {
+      throw new Error(
+        `manual approval request changed while waiting for a decision (${pendingApprovalRequestId} -> ${nextAttempt.output.approval_request_id}); stop and rerun the command after checking the approval status.`,
+      );
+    }
+
+    if (Date.now() - startedWaitingAt >= MANUAL_APPROVAL_WAIT_TIMEOUT_MS) {
+      throw new Error(
+        `Timed out after ${Math.ceil(MANUAL_APPROVAL_WAIT_TIMEOUT_MS / 1000)}s waiting for manual approval decision: ${pendingApprovalRequestId}`,
+      );
+    }
+  }
+}
+
 function legacyAmountToDecimalString(value: number | undefined): string | undefined {
   if (value === undefined) {
     return undefined;
@@ -1487,6 +1598,7 @@ async function main() {
           auth: options,
           config,
           asJson: options.json,
+          waitForManualApproval: true,
         });
         if (!signed) {
           return;
@@ -1550,22 +1662,128 @@ async function main() {
       .requiredOption('--network <name>', 'Network name')
       .requiredOption('--to <address>', 'Recipient address')
       .requiredOption('--amount <amount>', 'Transfer amount in configured native token units')
+      .option('--broadcast', 'Broadcast the signed transaction through RPC', false)
+      .option('--rpc-url <url>', 'Ethereum RPC URL override used only for broadcast')
+      .option(
+        '--from <address>',
+        'Sender address override for broadcast; defaults to configured wallet address',
+      )
+      .option('--nonce <nonce>', 'Explicit nonce override for broadcast')
+      .option('--gas-limit <gas>', 'Gas limit override for broadcast')
+      .option('--max-fee-per-gas-wei <wei>', 'Max fee per gas override for broadcast')
+      .option('--max-priority-fee-per-gas-wei <wei>', 'Priority fee per gas override for broadcast')
+      .option('--tx-type <type>', 'Typed tx value for broadcast', '0x02')
+      .option('--no-wait', 'Do not wait up to 30s for an on-chain receipt after broadcast')
+      .option(
+        '--reveal-raw-tx',
+        'Include the signed raw transaction bytes in broadcast output',
+        false,
+      )
+      .option('--reveal-signature', 'Include signer r/s/v fields in broadcast output', false)
       .addOption(new Option('--amount-wei <wei>').hideHelp()),
   ).action(async (options) => {
     const config = readConfig();
     const network = resolveCliNetworkProfile(options.network, config).chainId;
     const asset = resolveConfiguredNativeAsset(config, network);
+    const recipient = assertAddress(options.to, 'to');
     const amountWei = options.amount
       ? parseConfiguredAmount(options.amount, asset.decimals, 'amount')
       : parseBigIntString(options.amountWei, 'amountWei');
     try {
+      if (options.broadcast) {
+        const plan = await resolveAssetBroadcastPlan(
+          {
+            rpcUrl: resolveCliRpcUrl(options.rpcUrl, options.network, config),
+            chainId: network,
+            from: options.from ? assertAddress(options.from, 'from') : resolveWalletAddress(config),
+            to: recipient,
+            valueWei: amountWei,
+            dataHex: '0x',
+            nonce: options.nonce ? parseIntegerString(options.nonce, 'nonce') : undefined,
+            gasLimit: options.gasLimit
+              ? parsePositiveBigIntString(options.gasLimit, 'gasLimit')
+              : undefined,
+            maxFeePerGasWei: options.maxFeePerGasWei
+              ? parsePositiveBigIntString(options.maxFeePerGasWei, 'maxFeePerGasWei')
+              : undefined,
+            maxPriorityFeePerGasWei: options.maxPriorityFeePerGasWei
+              ? parseBigIntString(options.maxPriorityFeePerGasWei, 'maxPriorityFeePerGasWei')
+              : undefined,
+            txType: options.txType,
+          },
+          {
+            getChainInfo,
+            assertRpcChainIdMatches,
+            getNonce,
+            estimateGas,
+            estimateFees,
+          },
+        );
+        const signed = await runAgentCommandJson<RustBroadcastOutput>({
+          commandArgs: [
+            'broadcast',
+            '--network',
+            String(plan.chainId),
+            '--nonce',
+            String(plan.nonce),
+            '--to',
+            recipient,
+            '--value-wei',
+            amountWei.toString(),
+            '--data-hex',
+            '0x',
+            '--gas-limit',
+            plan.gasLimit.toString(),
+            '--max-fee-per-gas-wei',
+            plan.maxFeePerGasWei.toString(),
+            '--max-priority-fee-per-gas-wei',
+            plan.maxPriorityFeePerGasWei.toString(),
+            '--tx-type',
+            plan.txType,
+          ],
+          auth: options,
+          config,
+          asJson: options.json,
+          waitForManualApproval: true,
+        });
+        if (!signed) {
+          return;
+        }
+        const completed = await completeAssetBroadcast(plan, signed, {
+          assertSignedBroadcastTransactionMatchesRequest,
+          broadcastRawTransaction,
+        });
+        print(
+          formatBroadcastedAssetOutput({
+            command: 'transfer-native',
+            counterparty: recipient,
+            asset,
+            signed,
+            plan,
+            signedNonce: completed.signedNonce,
+            networkTxHash: completed.networkTxHash,
+            revealRawTx: options.revealRawTx,
+            revealSignature: options.revealSignature,
+          }),
+          options.json,
+        );
+        if (options.wait) {
+          await reportOnchainReceiptStatus({
+            rpcUrl: plan.rpcUrl,
+            txHash: completed.networkTxHash,
+            asJson: options.json,
+          });
+        }
+        return;
+      }
+
       const result = await runAgentCommandJson<RustBroadcastOutput>({
         commandArgs: [
           'transfer-native',
           '--network',
           String(network),
           '--to',
-          assertAddress(options.to, 'to'),
+          recipient,
           '--amount-wei',
           amountWei.toString(),
         ],
@@ -1672,6 +1890,7 @@ async function main() {
           auth: options,
           config,
           asJson: options.json,
+          waitForManualApproval: true,
         });
         if (!signed) {
           return;
@@ -1736,34 +1955,53 @@ async function main() {
       .requiredOption('--to <address>', 'Recipient or target contract')
       .requiredOption('--gas-limit <gas>', 'Gas limit')
       .requiredOption('--max-fee-per-gas-wei <wei>', 'Max fee per gas in wei')
-      .option('--nonce <nonce>', 'Explicit nonce override', '0')
+      .option('--nonce <nonce>', 'Explicit nonce override')
       .option('--value-wei <wei>', 'Value in wei', '0')
       .option('--data-hex <hex>', 'Calldata hex', '0x')
-      .option('--max-priority-fee-per-gas-wei <wei>', 'Priority fee per gas in wei', '0')
-      .option('--tx-type <type>', 'Typed tx value', '2')
+      .option('--max-priority-fee-per-gas-wei <wei>', 'Priority fee per gas in wei')
+      .option('--tx-type <type>', 'Typed tx value', '0x02')
       .option('--delegation-enabled', 'Forward delegation flag to Rust signing request', false),
   ).action(async (options) => {
     const config = readConfig();
     const network = resolveCliNetworkProfile(options.network, config);
-    const result = await runAgentCommandJson<RustBroadcastOutput>({
+    const to = assertAddress(options.to, 'to');
+    const valueWei = parseBigIntString(options.valueWei, 'valueWei');
+    const dataHex = assertHex(options.dataHex, 'dataHex');
+    const gasLimit = parsePositiveBigIntString(options.gasLimit, 'gasLimit');
+    const maxFeePerGasWei = parsePositiveBigIntString(options.maxFeePerGasWei, 'maxFeePerGasWei');
+    const explicitNonce = options.nonce ? parseIntegerString(options.nonce, 'nonce') : undefined;
+    const rpcUrl = resolveCliRpcUrl(undefined, options.network, config);
+    const from = resolveWalletAddress(config);
+    const chainInfo = await getChainInfo(rpcUrl);
+    assertRpcChainIdMatches(network.chainId, chainInfo.chainId);
+    const nonce = explicitNonce ?? (await getNonce(rpcUrl, from));
+    const fees = options.maxPriorityFeePerGasWei ? null : await estimateFees(rpcUrl);
+    const maxPriorityFeePerGasWei = options.maxPriorityFeePerGasWei
+      ? parseBigIntString(options.maxPriorityFeePerGasWei, 'maxPriorityFeePerGasWei')
+      : resolveEstimatedPriorityFeePerGasWei({
+          gasPrice: fees?.gasPrice ?? null,
+          maxFeePerGas: fees?.maxFeePerGas ?? null,
+          maxPriorityFeePerGas: fees?.maxPriorityFeePerGas ?? null,
+        });
+    const signed = await runAgentCommandJson<RustBroadcastOutput>({
       commandArgs: [
         'broadcast',
         '--network',
         String(network.chainId),
         '--nonce',
-        String(parseIntegerString(options.nonce, 'nonce')),
+        String(nonce),
         '--to',
-        assertAddress(options.to, 'to'),
+        to,
         '--value-wei',
-        parseBigIntString(options.valueWei, 'valueWei').toString(),
+        valueWei.toString(),
         '--data-hex',
-        assertHex(options.dataHex, 'dataHex'),
+        dataHex,
         '--gas-limit',
-        parsePositiveBigIntString(options.gasLimit, 'gasLimit').toString(),
+        gasLimit.toString(),
         '--max-fee-per-gas-wei',
-        parsePositiveBigIntString(options.maxFeePerGasWei, 'maxFeePerGasWei').toString(),
+        maxFeePerGasWei.toString(),
         '--max-priority-fee-per-gas-wei',
-        parseBigIntString(options.maxPriorityFeePerGasWei, 'maxPriorityFeePerGasWei').toString(),
+        maxPriorityFeePerGasWei.toString(),
         '--tx-type',
         options.txType,
         ...(options.delegationEnabled ? ['--delegation-enabled'] : []),
@@ -1772,9 +2010,31 @@ async function main() {
       config,
       asJson: options.json,
     });
-    if (result) {
-      print(result, options.json);
+    if (!signed) {
+      return;
     }
+
+    if (!signed.raw_tx_hex) {
+      throw new Error('Rust agent did not return raw_tx_hex for broadcast signing');
+    }
+
+    await assertSignedBroadcastTransactionMatchesRequest({
+      rawTxHex: signed.raw_tx_hex as Hex,
+      from,
+      to,
+      chainId: network.chainId,
+      nonce,
+      allowHigherNonce: false,
+      value: valueWei,
+      data: dataHex,
+      gasLimit,
+      maxFeePerGas: maxFeePerGasWei,
+      maxPriorityFeePerGas: maxPriorityFeePerGasWei,
+      txType: options.txType,
+    });
+
+    await broadcastRawTransaction(rpcUrl, signed.raw_tx_hex as Hex);
+    print(signed, options.json);
   });
 
   const rpc = program.command('rpc').description('RPC methods implemented in TypeScript');
@@ -2083,7 +2343,7 @@ async function main() {
         to,
         chainId,
         nonce,
-        allowHigherNonce: true,
+        allowHigherNonce: false,
         value: valueWei,
         data: dataHex,
         gasLimit,

package/src/lib/admin-reset.ts

@@ -24,6 +24,7 @@ import {
   LAUNCHD_UNINSTALL_SCRIPT_NAME,
   resolveLaunchDaemonHelperScriptPath,
 } from './launchd-assets.js';
+import { promptHiddenTty } from './hidden-tty-prompt.js';
 import { createSudoSession } from './sudo.js';
 
 const DEFAULT_LAUNCH_DAEMON_LABEL = 'com.wlfi.agent.daemon';
@@ -134,32 +135,7 @@ function validateSecret(value: string, label: string): string {
 }
 
 async function promptHidden(query: string, label: string): Promise<string> {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new Error(`${label} is required; rerun on a local TTY`);
-  }
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    terminal: true,
-  }) as readline.Interface & { stdoutMuted?: boolean; _writeToOutput?: (value: string) => void };
-
-  rl.stdoutMuted = true;
-  rl._writeToOutput = (value: string) => {
-    if (value.includes(query)) {
-      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
-      return;
-    }
-    if (!rl.stdoutMuted) {
-      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
-    }
-  };
-
-  const answer = await new Promise<string>((resolve) => {
-    rl.question(query, resolve);
-  });
-  rl.close();
-  process.stdout.write('\n');
+  const answer = await promptHiddenTty(query, `${label} is required; rerun on a local TTY`);
   return validateSecret(answer, label);
 }
 
@@ -184,8 +160,8 @@ async function promptVisible(query: string): Promise<string> {
 const sudoSession = createSudoSession({
   promptPassword: async () =>
     await promptHidden(
-      'Root password (input hidden; required to uninstall the root daemon and delete its state): ',
-      'root password',
+      'macOS admin password for sudo (input hidden; required to uninstall the root daemon and delete its state): ',
+      'macOS admin password for sudo',
     ),
 });
 
@@ -241,11 +217,13 @@ function print(payload: unknown, asJson: boolean | undefined): void {
     console.log(JSON.stringify(payload, null, 2));
     return;
   }
+  /* c8 ignore start -- this module only calls print() for JSON output; non-JSON summaries bypass this helper */
   if (typeof payload === 'string') {
     console.log(payload);
     return;
   }
   console.dir(payload, { depth: null, colors: process.stdout.isTTY });
+  /* c8 ignore stop */
 }
 
 function printResetSummary(result: {
@@ -332,6 +310,7 @@ export function cleanupLocalAdminResetState(
   const keychainRemoved = agentKeyId ? deleteAgentAuthTokenImpl(agentKeyId) : false;
 
   let configDeleted = false;
+  /* c8 ignore next -- configExists implies readConfigImpl() returned an object in this module; nullish fallback is defensive */
   let configValue: Record<string, unknown> | null = configExists ? redactConfig(currentConfig ?? {}) : null;
   if (options.deleteConfig) {
     if (configExists) {
@@ -483,7 +462,7 @@ async function runAdminReset(options: AdminResetOptions): Promise<void> {
 
   if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
     process.stderr.write(
-      'Root password required: reset must uninstall the root LaunchDaemon and delete the root-managed daemon state.\n',
+      'macOS admin password required: reset uses sudo to uninstall the root LaunchDaemon and delete the root-managed daemon state.\n',
     );
   }
   await sudoSession.prime();
@@ -502,6 +481,7 @@ async function runAdminReset(options: AdminResetOptions): Promise<void> {
       keychainAccount,
       '--delete-keychain-password',
     ]);
+    /* c8 ignore next 4 -- sudoSession.run reports command failures via exit codes; synchronous throws are defensive */
   } catch (error) {
     uninstallProgress.fail();
     throw error;
@@ -524,6 +504,7 @@ async function runAdminReset(options: AdminResetOptions): Promise<void> {
       '-f',
       ...managedDaemonResetArtifactPaths(),
     ]);
+    /* c8 ignore next 4 -- sudoSession.run reports command failures via exit codes; synchronous throws are defensive */
   } catch (error) {
     stateProgress.fail();
     throw error;
@@ -612,9 +593,11 @@ function printUninstallSummary(result: {
     result.local.agentKeyId
       ? `old agent key cleared: ${result.local.agentKeyId}`
       : 'old agent key cleared: no configured agent key was found',
+    /* c8 ignore start -- public uninstall summary only reaches here when a WLFI home existed or config provided the helper paths */
     result.local.wlfiHome.existed
       ? `local WLFI home removed: ${result.local.wlfiHome.path}`
       : `local WLFI home not found: ${result.local.wlfiHome.path}`,
+    /* c8 ignore stop */
     result.local.config.existed
       ? `config removed: ${result.local.config.path}`
       : `config not found: ${result.local.config.path}`,
@@ -630,7 +613,7 @@ async function runAdminUninstall(options: AdminUninstallOptions): Promise<void>
 
   if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
     process.stderr.write(
-      'Root password required: uninstall must remove the root LaunchDaemon and all managed root-owned files.\n',
+      'macOS admin password required: uninstall uses sudo to remove the root LaunchDaemon and all managed root-owned files.\n',
     );
   }
   await sudoSession.prime();
@@ -649,6 +632,7 @@ async function runAdminUninstall(options: AdminUninstallOptions): Promise<void>
       keychainAccount,
       '--delete-keychain-password',
     ]);
+    /* c8 ignore next 4 -- sudoSession.run reports command failures via exit codes; synchronous throws are defensive */
   } catch (error) {
     uninstallProgress.fail();
     throw error;
@@ -673,6 +657,7 @@ async function runAdminUninstall(options: AdminUninstallOptions): Promise<void>
       DEFAULT_MANAGED_STATE_DIR,
       DEFAULT_MANAGED_LOG_DIR,
     ]);
+    /* c8 ignore next 4 -- sudoSession.run reports command failures via exit codes; synchronous throws are defensive */
   } catch (error) {
     rootProgress.fail();
     throw error;