@jinn-network/client 0.1.5 → 0.1.6-canary.107ea271

package/dist/earning/bootstrap.js

@@ -15,20 +15,121 @@ import { formatBootstrapOperatorMessage, isJinnDebug, } from '../operator-errors
 import { reconcileServiceAgainstChain, } from './reconcile.js';
 import { previousSafeBeingAbandoned, sweepOrphanedServiceFunds, } from './orphan-sweep.js';
 import { DEFAULT_FAUCET_LOOP_TIMEOUT_MS, computeFaucetDripCap, requestTestnetFunding, } from './faucet.js';
-import { flattenErrorMessage, viemSendTransactionWithRetry, waitForTransactionReceiptWithRetry, } from '../tx-retry.js';
+import { flattenErrorMessage, sleep, viemSendTransactionWithRetry, waitForContractCode, waitForTransactionReceiptWithRetry, } from '../tx-retry.js';
 import { isUnauthorizedAccountError } from '../errors/unauthorized-account.js';
 import { createJinnPublicClient, createJinnWalletClient } from './viem-clients.js';
 import { isTransientEthReadError } from '../chain-read-errors.js';
 import { nextFleetServiceIndex } from './next-service-index.js';
+import { displayFleetServiceIndex } from './fleet-display-index.js';
 import { rpcHostForDisplay } from '../preflight/rpc-network.js';
 import { detectDeprecatedTestnetSetup, migrateDeprecatedTestnetSetup, } from './testnet-setup-migration.js';
 const addr = (value) => getAddress(value);
 const SAFE_TOKEN_BOOTSTRAP_MULTIPLIER = 2n;
-const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * 2× cold-start headroom for master ETH target on a fresh bootstrap.
+ *
+ * Gas accounting for a single standard-mode service on first run:
+ *   ~1.3M gas for the Safe deploy + stake + mech (at 2 gwei ≈ 0.0026 ETH)
+ *   + 0.002 ETH Safe seed (sent to the Safe so it can pay mech fees)
+ *   ≈ 0.0046 ETH minimum; 2× gives ≈ 0.009–0.010 ETH — the bootstrap
+ *   `minEoaGasEth` default.
+ *
+ * The multiplier only applies when no service has a persisted `service_id`
+ * on-chain (i.e. the fleet is truly cold — OR migration-wiped, where
+ * services exist in shape but lost their on-chain anchor). Once any service
+ * has committed a `service_id`, the fleet is past the cold-start cliff and
+ * 1× suffices.
+ *
+ * Single source of truth: imported by funding-plan.ts.
+ */
+export const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * Compute the required master ETH gate for the standard staking mode.
+ *
+ * @param services         Persisted service states
+ * @param minEoaGasEth     Configured minimum EOA gas target (wei)
+ * @param standardMultiplier  Cold-start multiplier (defaults to {@link STANDARD_MASTER_BOOTSTRAP_MULTIPLIER})
+ * @param pendingSetupMigration  True when deprecated testnet setup detected
+ * @param targetServices   How many services the fleet is aiming for
+ */
+export function computeRequiredMasterEth({ services, minEoaGasEth, standardMultiplier = STANDARD_MASTER_BOOTSTRAP_MULTIPLIER, pendingSetupMigration = false, targetServices = 1, }) {
+    const completedCount = services.filter(s => s.step !== undefined && isOperationalServiceStep(s.step)).length;
+    const standardFleetAlreadyComplete = !pendingSetupMigration && completedCount >= targetServices;
+    if (standardFleetAlreadyComplete)
+        return 0n;
+    // "Cold in liability" = no service has an on-chain anchor yet.
+    // This includes:
+    //   1. Fresh fleet (services array is empty)
+    //   2. Migration-wiped fleet (services exist in shape but service_id === null)
+    // Apply the 2× headroom multiplier in both cases.
+    const hasPersistedOnChain = services.some(s => s.service_id != null);
+    return minEoaGasEth * (hasPersistedOnChain ? 1n : standardMultiplier);
+}
+/** Master ETH required to FINISH the whole bootstrap from a fresh start (not
+ *  just to enter Stage 1). Centralized so the daemon's ensureStage1 gate,
+ *  the read-side funding-plan, gather-status, and the panel faucet target
+ *  all agree on a single "one-shot fund the operator" number.
+ *
+ *  Components for a 1-service standard-mode bootstrap:
+ *    - STAGE1_AGENT_ETH (0.010 ETH): master → HD-1 fleet-agent transfer.
+ *      HD-1 pays for its own Safe deploy + register + setAgentWallet out
+ *      of this; leftover covers service 1's Stage 2 work (mech deploy +
+ *      rebind). May get a conditional minEoaGasEth top-up from master if
+ *      Stage 1's gas eats too much of the original transfer.
+ *    - minEoaGasEth × STANDARD_MASTER_BOOTSTRAP_MULTIPLIER (0.010 ETH):
+ *      master gas budget across both stages. Real spend (~0.0025 ETH at
+ *      typical 6 gwei Base Sepolia) leaves room for ~4× gas-spike margin
+ *      plus the conditional HD-1 top-up.
+ *    - minEoaGasEth × (targetServices - 1): per-extra-service top-up for
+ *      services 2..N. Service 1 piggybacks on HD-1's Stage 1 funding.
+ *
+ *  Total for N=1: 0.010 + 0.010 = 0.020 ETH.
+ *  Total for N=2: 0.025 ETH.
+ *  Total for N=3: 0.030 ETH.
+ *
+ *  This number works ONLY when Stage 2's internal gate is `minEoaGasEth ×
+ *  1n` (0.005 ETH) — not the historic `× 2n`. After Stage 1 transfers 0.010
+ *  out, master sits at ~0.0099 ETH (0.020 minus transfer minus Stage 1
+ *  funding-tx gas). The 0.005 gate clears that with margin; the 0.010 gate
+ *  did not. See the Stage 2 gate at ensureStage1And2 line ~484.
+ *
+ *  Operator may see a "low runway" warning after bootstrap — that's
+ *  intentional. The operator-facing 0.020 ETH covers bootstrap completion,
+ *  not multi-week post-bootstrap runway. Top-up is a separate concern.
+ */
+export const STAGE1_AGENT_ETH = 10000000000000000n; // 0.01 ETH (moved out of stepFleetSafeDeploy)
+export function stage1MinMasterEth(config, targetServices = 1) {
+    const extraServiceTransfers = config.minEoaGasEth * BigInt(Math.max(0, targetServices - 1));
+    return (STAGE1_AGENT_ETH +
+        config.minEoaGasEth * STANDARD_MASTER_BOOTSTRAP_MULTIPLIER +
+        extraServiceTransfers);
+}
 /** Conservative default: ~0.001 ETH/day master gas if not configured. */
 const DEFAULT_MASTER_ETH_DAILY_WEI = 1000000000000000n;
 /** Warn when ETH above the minimum would last fewer than this many days at the daily estimate. */
 const MASTER_ETH_RUNWAY_WARN_DAYS = 7n;
+/**
+ * Safe → ERC-8004 agent NFT binding retry (jinn-mono-h74p).
+ *
+ * Empirical observation against fresh Base Sepolia 1/1 Safes: the first
+ * `IdentityRegistry.setAgentWallet` attempt reverts with a generic
+ * "Execution reverted for an unknown reason" — but the same Safe + same
+ * agentId + a freshly-signed message a few seconds later succeeds. The
+ * race window is likely freshly-deployed-Safe state lag on the public RPC
+ * (the simulator can't read the Safe's storage yet in the same block /
+ * eventual-consistency between sibling RPC nodes). A short bounded retry
+ * makes the operator-visible behaviour deterministic instead of relying on
+ * the "daemon exits → operator restarts → resume at safe_binding_pending"
+ * accidental safety net (which goes away when jinn-mono-vh74.2 removes the
+ * Claude-auth post-bootstrap exit gate).
+ *
+ * Defaults: 3 attempts × 3 s delay = at most ~6 s of in-process retry budget
+ * before falling through to the existing `safe_binding_pending` persisted
+ * state. Real (non-transient) failures still surface — just with a slightly
+ * higher latency tax for the diagnostic.
+ */
+const DEFAULT_SAFE_BINDING_MAX_ATTEMPTS = 3;
+const DEFAULT_SAFE_BINDING_RETRY_DELAY_MS = 3_000;
 export class FleetBootstrapper {
     store;
     config;
@@ -43,6 +144,8 @@ export class FleetBootstrapper {
     faucetLoopTimeoutMs;
     now;
     autoTestnetFaucet;
+    safeBindingMaxAttempts;
+    safeBindingRetryDelayMs;
     constructor(options = {}) {
         this.store = new FleetStateStore(options.earningDir);
         this.chain = options.chain ?? 'base';
@@ -55,6 +158,10 @@ export class FleetBootstrapper {
         this.now = options.now ?? Date.now;
         this.autoTestnetFaucet =
             options.autoTestnetFaucet ?? this.env['JINN_DISABLE_TESTNET_FAUCET'] !== '1';
+        this.safeBindingMaxAttempts =
+            options.safeBindingMaxAttempts ?? DEFAULT_SAFE_BINDING_MAX_ATTEMPTS;
+        this.safeBindingRetryDelayMs =
+            options.safeBindingRetryDelayMs ?? DEFAULT_SAFE_BINDING_RETRY_DELAY_MS;
         const dailyOpt = options.masterEthDailyEstimateWei;
         this.masterEthDailyEstimateWei =
             dailyOpt !== undefined
@@ -77,6 +184,71 @@ export class FleetBootstrapper {
     async getStatus() {
         return this.store.load(this.chain);
     }
+    /**
+     * Run `bindAgentWalletToSafe` with the freshly-deployed-Safe race retry
+     * (jinn-mono-h74p, corrected in jinn-mono-k1ng).
+     *
+     * The race: against a fresh 1/1 Safe on Base Sepolia, the first
+     * setAgentWallet attempt reverts with "Execution reverted for an unknown
+     * reason"; the same Safe + same agentId a few seconds later succeeds.
+     *
+     * The h74p version of the retry only wrapped the call in a try/catch.
+     * In production, `bindAgentWalletToSafe` doesn't throw on revert — it
+     * returns a `{ ok: false, error }` outcome — so the catch never fired
+     * and the retry was dead code. The per-service path "worked" anyway
+     * because it persists `safe_binding_pending` and the next bootstrap
+     * resumes the bind. Stage 1 had no equivalent safety net, so a single
+     * `ok: false` halted bootstrap (the 2026-05-18 canary failure).
+     *
+     * This wrapper:
+     *   - Retries on returned `ok: false` (the way the race actually
+     *     manifests in production).
+     *   - Also retries on thrown exceptions (defense-in-depth in case viem
+     *     error handling changes).
+     *   - Returns the final outcome; callers decide whether to throw, mark
+     *     pending, or proceed.
+     *
+     * Single attempt budget: `safeBindingMaxAttempts` × `safeBindingRetryDelayMs`
+     * (defaults: 3 × 3 s = ~9 s).
+     */
+    async bindAgentWalletWithRetry(args, label) {
+        const maxAttempts = Math.max(1, this.safeBindingMaxAttempts);
+        let lastResult;
+        let lastThrowError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                lastResult = await bindAgentWalletToSafe(args);
+                if (lastResult.ok)
+                    return lastResult;
+                if (attempt < maxAttempts) {
+                    console.error(`[fleet-bootstrap] ${label}: setAgentWallet attempt ` +
+                        `${attempt}/${maxAttempts} returned ok=false (${lastResult.error.shortMessage}); ` +
+                        `retrying in ${this.safeBindingRetryDelayMs}ms...`);
+                    if (this.safeBindingRetryDelayMs > 0) {
+                        await sleep(this.safeBindingRetryDelayMs);
+                    }
+                }
+            }
+            catch (err) {
+                lastThrowError = err;
+                if (attempt < maxAttempts) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    console.error(`[fleet-bootstrap] ${label}: setAgentWallet attempt ` +
+                        `${attempt}/${maxAttempts} threw (${reason}); retrying in ` +
+                        `${this.safeBindingRetryDelayMs}ms...`);
+                    if (this.safeBindingRetryDelayMs > 0) {
+                        await sleep(this.safeBindingRetryDelayMs);
+                    }
+                }
+            }
+        }
+        if (lastResult)
+            return lastResult; // final ok:false propagated to caller
+        // Only thrown all the way through — no successful response or returned outcome.
+        throw lastThrowError instanceof Error
+            ? lastThrowError
+            : new Error(String(lastThrowError));
+    }
     /**
      * Conservative daily master gas (wei): max(DEFAULT, rough tx count from poll interval × cost).
      */
@@ -112,16 +284,149 @@ export class FleetBootstrapper {
         const mnemonic = await this.loadExistingMnemonic(state, password);
         return this.stepRegisterAgent(state, mnemonic, serviceIndex);
     }
-    async bootstrap(password) {
-        // Handle legacy keystore migration
+    /**
+     * Stage 1 — Identity (universal). Walks: wallet → predict Safe (from
+     * HD-index-1 agent EOA) → ETH funding gate → deploy Safe → mint agentId
+     * + setAgentWallet via ERC-1271. Idempotent and re-entrant. Does NOT
+     * touch service rows or staking — those belong to Stage 2.
+     *
+     * Fleet-level fields written:
+     *   - fleet_safe_address (after predict)
+     *   - fleet_agent_id, fleet_identity_registry, fleet_stage='stage1'
+     *     (after mint + bind)
+     *
+     * Funding gate: requires ETH on the master EOA only (no OLAS). On testnet,
+     * the existing CDP faucet loop drains as usual when `autoTestnetFaucet`
+     * is enabled.
+     *
+     * See docs/superpowers/specs/2026-05-13-plug-in-builder-entry-point-design.md §5.1.
+     */
+    async ensureStage1(password) {
+        // Legacy keystore migration (same as bootstrap()).
         if (!this.store.hasMnemonicKeystore() && this.store.hasLegacyKeystore()) {
             await this.store.migrateLegacyFiles();
         }
         let state = await this.store.load(this.chain);
+        // Short-circuit if Stage 1 is already complete (or beyond).
+        if (state.fleet_stage === 'stage1' || state.fleet_stage === 'stage1_and_2') {
+            // Even when stage marker says complete, fleet identity may be empty for
+            // pre-j07 operators (`stage1_and_2` is set by the migration for
+            // services-complete-but-no-agent_id operators). In that case we leave
+            // Stage 1 alone — the legacy backfill in main.ts handles those rows
+            // and a future ensureStage1 call after backfill will promote.
+            return {
+                ok: true,
+                fleet_state: state,
+                message: state.fleet_agent_id !== null
+                    ? `Stage 1 already complete (fleet_agent_id=${state.fleet_agent_id}, fleet_safe=${state.fleet_safe_address}).`
+                    : 'Stage 1 marker present but fleet identity is empty (legacy operator). Skipping.',
+            };
+        }
         try {
-            // Phase 1: Master wallet setup
             state = await this.ensureMasterWallet(state, password);
-            // Phase 1b: Check master funding
+            // Stage 1 funding gate — ETH only (no OLAS). Stage 1 needs
+            // STAGE1_AGENT_ETH (0.01) for the master → agent transfer plus
+            // minEoaGasEth (0.005) reserved for the master's own gas to send that
+            // transfer. The agent EOA then pays for Safe deploy + ERC-8004 register
+            // + setAgentWallet out of the funds it just received.
+            // See jinn-mono-u34i: pre-fix this gate was 2×minEoaGasEth (= 0.01 ETH),
+            // which equaled the transfer amount and left no gas headroom, so a
+            // master holding the gate's minimum would fail eth_estimateGas with
+            // "gas required exceeds allowance (0)".
+            const requiredMasterEth = stage1MinMasterEth(this.config, this.targetServices);
+            const masterAddress = state.master_address;
+            const masterBalance = await this.publicClient.getBalance({
+                address: masterAddress,
+            });
+            if (masterBalance < requiredMasterEth) {
+                const shortfall = requiredMasterEth - masterBalance;
+                return {
+                    ok: false,
+                    fleet_state: state,
+                    message: `Your master wallet needs more ETH (currently ${formatEther(masterBalance)} ETH, need ${formatEther(shortfall)} ETH more) to complete Stage 1. Please send ETH to: ${masterAddress}`,
+                    funding: {
+                        master_address: masterAddress,
+                        eth_required: shortfall.toString(),
+                        eth_balance: masterBalance.toString(),
+                    },
+                };
+            }
+            const mnemonic = await this.loadExistingMnemonic(state, password);
+            // Step 1: predict fleet Safe from HD-index-1 agent EOA.
+            if (!state.fleet_safe_address) {
+                state = await this.stepFleetSafePredict(state, mnemonic);
+            }
+            // Step 2: deploy fleet Safe if bytecode absent.
+            const safeCode = await this.publicClient.getCode({
+                address: getAddress(state.fleet_safe_address),
+            });
+            if (safeCode === undefined || safeCode === '0x') {
+                state = await this.stepFleetSafeDeploy(state, mnemonic);
+            }
+            // Step 3: mint agentId + bind Safe via setAgentWallet.
+            if (!state.fleet_agent_id) {
+                state = await this.stepFleetIdentityRegister(state, mnemonic);
+            }
+            else if (state.fleet_stage !== 'stage1' && state.fleet_stage !== 'stage1_and_2') {
+                // Identity was minted but stage marker is stale; advance it.
+                state = await this.store.patchFleet({ fleet_stage: 'stage1' });
+            }
+            return {
+                ok: true,
+                fleet_state: state,
+                message: `Stage 1 complete. fleet_agent_id=${state.fleet_agent_id}, fleet_safe=${state.fleet_safe_address}.`,
+            };
+        }
+        catch (error) {
+            const { summary, hint, rawMessage } = formatBootstrapOperatorMessage(error);
+            const userMessage = hint !== undefined ? `${summary}\nHint: ${hint}` : summary;
+            if (this.debug) {
+                console.error(`[fleet-bootstrap] ensureStage1 failed:`, error);
+            }
+            else {
+                console.error(`[fleet-bootstrap] ${summary}`);
+                if (hint !== undefined)
+                    console.error(`Hint: ${hint}`);
+                if (rawMessage && rawMessage !== summary) {
+                    console.error(`[fleet-bootstrap] raw: ${rawMessage.split('\n')[0]}`);
+                }
+            }
+            return {
+                ok: false,
+                fleet_state: state,
+                message: userMessage,
+                rawErrorMessage: rawMessage,
+            };
+        }
+    }
+    /**
+     * Stage 1 + Stage 2 — full operator bootstrap. Calls `ensureStage1`
+     * first; on success, walks Stage 2 per service. Builder-only users who
+     * have completed Stage 1 and call this method later begin Stage 2 from
+     * `awaiting_stake` for the first service row (created lazily here).
+     *
+     * Two-Safe topology in standard mode: `fleet_safe_address !==
+     * services[0].safe_address` because Stage 2's `distributor.stake()`
+     * creates its own Safe. In self-bond mode the two converge (both
+     * derived from HD-index-1).
+     *
+     * See docs/superpowers/specs/2026-05-13-plug-in-builder-entry-point-design.md §5.1.
+     */
+    async ensureStage1And2(password) {
+        // Stage 1 first — establishes fleet identity. Short-circuits if already done.
+        const stage1Result = await this.ensureStage1(password);
+        if (!stage1Result.ok) {
+            return stage1Result;
+        }
+        // Original bootstrap body — copied verbatim from the previous bootstrap()
+        // method, with two changes:
+        //   (a) the legacy-keystore migration and master-wallet-ensure are no-ops
+        //       because ensureStage1 already ran them.
+        //   (b) at the end, if any service reached `complete`/`safe_binding_pending`
+        //       we advance `fleet_stage` to `'stage1_and_2'`.
+        let state = stage1Result.fleet_state;
+        try {
+            // Phase 1b: Check master funding for the full operator path.
             const masterAddress = state.master_address;
             let masterBalance = await this.publicClient.getBalance({ address: masterAddress });
             // Self-bond mode needs much more ETH than standard mode because the master
@@ -151,15 +456,24 @@ export class FleetBootstrapper {
                 stakingMode: this.stakingMode,
                 currentStakingContract: this.config.stakingContract,
             }).services.length > 0;
-            const completedCountBeforeFunding = state.services.filter(s => isOperationalServiceStep(s.step)).length;
             const standardFleetAlreadyComplete = this.stakingMode === 'standard' &&
-                !pendingSetupMigration &&
-                completedCountBeforeFunding >= this.targetServices;
-            const standardFleetHasInProgressServices = this.stakingMode === 'standard' && state.services.length > 0;
+                state.services.length >= this.targetServices &&
+                state.services.every(svc => svc.step !== undefined && isOperationalServiceStep(svc.step)) &&
+                !pendingSetupMigration;
             const requiredMasterEth = this.stakingMode === 'standard'
                 ? (standardFleetAlreadyComplete
                     ? 0n
-                    : this.config.minEoaGasEth * (standardFleetHasInProgressServices ? 1n : STANDARD_MASTER_BOOTSTRAP_MULTIPLIER))
+                    // Stage 2 master gas budget — covers distributor.stake() (~0.003
+                    // ETH at typical 6 gwei Base Sepolia) plus per-extra-service
+                    // top-up transfers. Previously this was `× 2` for fresh fleets,
+                    // which double-counted a service-1 transfer that doesn't actually
+                    // fire (HD-1 carries Stage 1 leftover, gets a conditional top-up
+                    // only if needed). See jinn-mono-u34i: the `× 2` figure also
+                    // exceeded the post-Stage-1 master balance at the operator-facing
+                    // 0.020 ETH budget by ~127k gwei of Stage 1 gas burn, causing a
+                    // second funding prompt.
+                    : this.config.minEoaGasEth +
+                        this.config.minEoaGasEth * BigInt(Math.max(0, this.targetServices - 1)))
                 : SELF_BOND_ETH_PER_SERVICE * BigInt(this.targetServices);
             const autoFaucetEnabled = this.autoTestnetFaucet;
             // Re-sum system ETH (master + agent/safe balances for self-bond mode).
@@ -291,6 +605,11 @@ export class FleetBootstrapper {
                 const nextIndex = nextFleetServiceIndex(state.services);
                 state = await this.bootstrapService(state, mnemonic, nextIndex);
             }
+            // Advance fleet_stage to 'stage1_and_2' if any service is operational.
+            const anyOperationalAfter = state.services.some(s => isOperationalServiceStep(s.step));
+            if (anyOperationalAfter && state.fleet_stage !== 'stage1_and_2') {
+                state = await this.store.patchFleet({ fleet_stage: 'stage1_and_2' });
+            }
             return {
                 ok: true,
                 fleet_state: state,
@@ -298,7 +617,7 @@ export class FleetBootstrapper {
             };
         }
         catch (error) {
-            const { summary, hint, rawMessage } = formatBootstrapOperatorMessage(error);
+            const { summary, hint, rawMessage, category } = formatBootstrapOperatorMessage(error);
             const userMessage = hint !== undefined ? `${summary}\nHint: ${hint}` : summary;
             if (this.debug) {
                 console.error(`[fleet-bootstrap] Bootstrap failed:`, error);
@@ -314,14 +633,32 @@ export class FleetBootstrapper {
                     console.error(`[fleet-bootstrap] raw: ${rawMessage.split('\n')[0]}`);
                 }
             }
+            // Extract a tx hash embedded in the error message by the on-chain revert
+            // paths (format: "...tx failed for service N: 0x<hash>" or
+            // "...tx reverted: 0x<hash>"). Surfaced in the fatal envelope so the SPA
+            // can render a block-explorer link. jinn-mono-hjex reviewer fix.
+            const txHashMatch = /(0x[a-fA-F0-9]{64})/.exec(rawMessage);
+            const txHash = txHashMatch ? txHashMatch[1] : null;
             return {
                 ok: false,
                 fleet_state: state,
                 message: userMessage,
                 rawErrorMessage: rawMessage,
+                // Preserve the structured category so the error envelope in main.ts
+                // can surface it in `details.category` for SPA consumers. jinn-mono-hjex.6
+                ...(category !== undefined ? { errorCategory: category } : {}),
+                ...(txHash !== null ? { txHash } : {}),
             };
         }
     }
+    /**
+     * Back-compat alias. Existing call sites in `client/src/cli/commands/bootstrap.ts`
+     * and `client/src/cli/commands/fleet-scale.ts` continue to call `bootstrap()`;
+     * forwarding to `ensureStage1And2` preserves their semantics without churn.
+     */
+    async bootstrap(password) {
+        return this.ensureStage1And2(password);
+    }
     /**
      * If the master is only slightly above the minimum, warn about gas runway (heuristic days).
      */
@@ -382,6 +719,133 @@ export class FleetBootstrapper {
             return freshMnemonic;
         }
     }
+    // ── Stage 1: fleet-level identity steps (nghf) ────────────────────────
+    /** Deterministic Safe predict from the HD-index-1 agent EOA. */
+    async stepFleetSafePredict(state, mnemonic) {
+        const agentAddress = deriveAgentAddress(mnemonic, 1);
+        const agentKey = walletPrivateKeyAtIndex(mnemonic, 1);
+        console.error(`[fleet-bootstrap] Stage 1: predicting fleet Safe (owner=${agentAddress})`);
+        const { address } = await initPredictedSafe({
+            rpcUrl: this.config.rpcUrl,
+            signerKey: agentKey,
+            owners: [agentAddress],
+            threshold: 1,
+        });
+        void state;
+        return this.store.patchFleet({ fleet_safe_address: getAddress(address) });
+    }
+    /** Deploy the predicted fleet Safe. Funds the agent EOA from master if needed. */
+    async stepFleetSafeDeploy(state, mnemonic) {
+        const agentAddress = deriveAgentAddress(mnemonic, 1);
+        const agentKey = walletPrivateKeyAtIndex(mnemonic, 1);
+        const agentSigner = deriveAgentSigner(mnemonic, 1);
+        const fleetSafe = state.fleet_safe_address;
+        // Fund agent EOA so it can pay for Safe deploy + setAgentWallet gas.
+        // 0.01 ETH covers Safe deploy (~250k gas) + register (~80k) + setAgentWallet
+        // (~200k) at testnet gas prices comfortably. STAGE1_AGENT_ETH is the
+        // module-level constant used both here and in `stage1MinMasterEth` so the
+        // gate and the transfer agree (jinn-mono-u34i).
+        const masterAccount = deriveMasterSigner(mnemonic);
+        const masterWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, masterAccount);
+        const agentBalance = await this.publicClient.getBalance({
+            address: getAddress(agentAddress),
+        });
+        if (agentBalance < STAGE1_AGENT_ETH) {
+            const fundAmount = STAGE1_AGENT_ETH - agentBalance;
+            console.error(`[fleet-bootstrap] Stage 1: funding fleet agent EOA with ${fundAmount} wei from master`);
+            const fundHash = await viemSendTransactionWithRetry(masterWallet, this.publicClient, {
+                account: masterAccount,
+                to: addr(agentAddress),
+                value: fundAmount,
+            });
+            await waitForTransactionReceiptWithRetry(this.publicClient, fundHash);
+        }
+        console.error(`[fleet-bootstrap] Stage 1: deploying fleet Safe at ${fleetSafe}`);
+        const { safe } = await initPredictedSafe({
+            rpcUrl: this.config.rpcUrl,
+            signerKey: agentKey,
+            owners: [agentAddress],
+            threshold: 1,
+        });
+        const deployTx = await safe.createSafeDeploymentTransaction();
+        const agentWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, agentSigner);
+        const deployHash = await viemSendTransactionWithRetry(agentWallet, this.publicClient, {
+            account: agentSigner,
+            to: deployTx.to,
+            value: BigInt(deployTx.value),
+            data: deployTx.data,
+        });
+        const receipt = await waitForTransactionReceiptWithRetry(this.publicClient, deployHash);
+        if (receipt.status !== 'success') {
+            throw new Error(`Fleet Safe deployment tx failed: ${deployHash}`);
+        }
+        try {
+            await waitForContractCode(this.publicClient, getAddress(fleetSafe));
+        }
+        catch {
+            throw new Error(`Fleet Safe deployment succeeded but no code at ${fleetSafe}`);
+        }
+        console.error(`[fleet-bootstrap] Stage 1: fleet Safe deployed (tx=${deployHash})`);
+        return this.store.load(this.chain);
+    }
+    /** Mint the fleet agentId + bind Safe via setAgentWallet (ERC-1271). */
+    async stepFleetIdentityRegister(state, mnemonic) {
+        const identityRegistry = this.config.identityRegistry ?? IDENTITY_REGISTRY_ADDRESSES[this.config.chainId];
+        if (!identityRegistry) {
+            throw new Error(`IdentityRegistry address not configured for chainId=${this.config.chainId}.`);
+        }
+        const fleetSafe = state.fleet_safe_address;
+        const agentSigner = deriveAgentSigner(mnemonic, 1);
+        const agentWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, agentSigner);
+        // Mint agentId — empty agent URI for v0 (matches stepRegisterAgent §6.1 in spec).
+        const registerData = encodeFunctionData({
+            abi: IDENTITY_REGISTRY_ABI,
+            functionName: 'register',
+            args: [''],
+        });
+        console.error(`[fleet-bootstrap] Stage 1: minting fleet agentId ` +
+            `(IdentityRegistry=${identityRegistry}, agentEOA=${agentSigner.address})`);
+        const mintTxHash = await viemSendTransactionWithRetry(agentWallet, this.publicClient, {
+            account: agentSigner,
+            to: addr(identityRegistry),
+            data: registerData,
+        });
+        const mintReceipt = await waitForTransactionReceiptWithRetry(this.publicClient, mintTxHash);
+        if (mintReceipt.status !== 'success') {
+            throw new Error(`Fleet IdentityRegistry.register() failed: ${mintTxHash}`);
+        }
+        const fleetAgentId = this.parseAgentIdFromReceipt(mintReceipt, identityRegistry);
+        if (fleetAgentId === null) {
+            throw new Error(`Fleet IdentityRegistry.register() succeeded but Registered event missing (tx=${mintTxHash})`);
+        }
+        // Persist agentId IMMEDIATELY so a crash between mint and bind doesn't lose it.
+        await this.store.patchFleet({
+            fleet_agent_id: fleetAgentId,
+            fleet_identity_registry: getAddress(identityRegistry),
+        });
+        // Bind the Safe via setAgentWallet (ERC-1271).
+        // Wrapped in the freshly-deployed-Safe retry (jinn-mono-k1ng). The
+        // pre-k1ng single-attempt version halted bootstrap when the documented
+        // race fired on the first attempt — exactly the 2026-05-18 canary's
+        // second-time-around failure mode.
+        console.error(`[fleet-bootstrap] Stage 1: binding fleet Safe ${fleetSafe} to agentId=${fleetAgentId}`);
+        const bindResult = await this.bindAgentWalletWithRetry({
+            identityRegistryAddress: addr(identityRegistry),
+            agentId: BigInt(fleetAgentId),
+            safeAddress: addr(fleetSafe),
+            agentEoaAccount: agentSigner,
+            agentEoaWalletClient: agentWallet,
+            publicClient: this.publicClient,
+            chainId: this.config.chainId,
+        }, 'Stage 1');
+        if (!bindResult.ok) {
+            const bindErr = bindResult.error;
+            throw new Error(`Fleet setAgentWallet failed after ${this.safeBindingMaxAttempts} attempts: ${bindErr.shortMessage}` +
+                (bindErr.revertReason ? ` (revert: ${bindErr.revertReason})` : ''));
+        }
+        console.error(`[fleet-bootstrap] Stage 1: setAgentWallet succeeded (tx=${bindResult.txHash})`);
+        return this.store.patchFleet({ fleet_stage: 'stage1' });
+    }
     // ── Phase 2: Per-service bootstrap ───────────────────────────────────
     async bootstrapService(state, mnemonic, index) {
         const agentAddress = deriveAgentAddress(mnemonic, index);
@@ -629,6 +1093,39 @@ export class FleetBootstrapper {
                 return this.store.updateService(index, { step: 'staked' });
             }
         }
+        // Pre-stake precondition: if migration cleared service_id but kept agent_address,
+        // check the EOA is not already registered on-chain as an agent instance. If it is,
+        // calling stake() again would revert with AgentInstanceRegistered (selector 0x631695bd)
+        // and there is nothing useful the operator can do without rotating the agent EOA.
+        // Fail fast with a typed error instead of letting the contract revert.
+        //
+        // ServiceRegistryL2 exposes the `mapAgentInstanceOperators(address) → address` mapping:
+        // it returns the operator address that registered the given agent instance, or the
+        // zero address when no operator has bound that instance. A non-zero return means the
+        // EOA is already bound. (There is no `mapAgentInstances(address) → uint256` getter on
+        // the deployed registry — an earlier draft of this guard referenced one and was a
+        // permanent no-op.)
+        if (svc.agent_address && svc.service_id === null && this.config.serviceRegistry) {
+            let alreadyBound = false;
+            try {
+                const boundOperator = (await this.publicClient.readContract({
+                    address: getAddress(this.config.serviceRegistry),
+                    abi: SERVICE_REGISTRY_L2_ABI,
+                    functionName: 'mapAgentInstanceOperators',
+                    args: [getAddress(svc.agent_address)],
+                }));
+                alreadyBound = boundOperator !== '0x0000000000000000000000000000000000000000';
+            }
+            catch {
+                // Registry read failure is non-fatal — proceed and let stake() surface
+                // the error if the agent really is bound.
+            }
+            if (alreadyBound) {
+                throw new Error(`agent_already_bound: agent EOA ${svc.agent_address} is already registered as an agent instance on-chain. ` +
+                    `The previous setup retirement may have been incomplete. ` +
+                    `Contact support or rotate the agent EOA to continue.`);
+            }
+        }
         // Fresh distributor stake() creates a new on-chain service. If state still
         // references an old Safe (e.g. hand-edited JSON), sweep it before replacing.
         if (svc.service_id === null && svc.safe_address && state.master_address) {
@@ -694,42 +1191,19 @@ export class FleetBootstrapper {
         const svc = state.services.find(s => s.index === index);
         const serviceId = svc.service_id;
         const stakingAddress = this.stakingAddressForService(svc);
-        // `reStake()` is operator-scoped: the master EOA must match the
-        // distributor's recorded `mapServiceIdCuratingAgents[serviceId]` entry.
-        // If it doesn't, the operator is likely using the wrong earning dir or
-        // password, or the service needs owner / managing-agent recovery.
-        const masterAccount = deriveMasterSigner(mnemonic);
-        const masterWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, masterAccount);
-        const reStakeData = encodeFunctionData({
-            abi: STOLAS_DISTRIBUTOR_ABI,
-            functionName: 'reStake',
-            args: [stakingAddress, BigInt(serviceId)],
+        const di = displayFleetServiceIndex(svc);
+        // Delegate to the standalone exported helper (shared with EvictionLoop /
+        // the dashboard "Re-stake now" CTA). This eliminates the duplicate
+        // implementation (jinn-mono-hjex.3).
+        await recoverEvictedService({
+            serviceDisplayIndex: di,
+            serviceId,
+            stakingAddress: stakingAddress,
+            distributorAddress: this.config.distributorAddress,
+            rpcUrl: this.config.rpcUrl,
+            chain: this.chain,
+            mnemonic,
         });
-        console.error(`[fleet-bootstrap] Service ${index}: calling distributor.reStake() for evicted service ${serviceId}`);
-        let reStakeHash;
-        try {
-            reStakeHash = await viemSendTransactionWithRetry(masterWallet, this.publicClient, {
-                account: masterAccount,
-                to: addr(this.config.distributorAddress),
-                data: reStakeData,
-                gas: 1500000n,
-            });
-        }
-        catch (err) {
-            const message = flattenErrorMessage(err);
-            if (isUnauthorizedAccountError(message)) {
-                throw new Error(`Service ${index} (service_id ${serviceId}) is evicted on the staking proxy, but master EOA ${masterAccount.address} is not authorized to reStake it. ` +
-                    `The distributor only permits the recorded service operator, a managing agent, or the owner. ` +
-                    `Verify JINN_EARNING_DIR and JINN_PASSWORD derive the original master EOA for this service, then re-run jinn bootstrap; otherwise request owner / managing-agent recovery or abandon-and-rebootstrap. ` +
-                    `reStake revert: ${message}`);
-            }
-            throw err;
-        }
-        const receipt = await waitForTransactionReceiptWithRetry(this.publicClient, reStakeHash);
-        if (receipt.status !== 'success') {
-            throw new Error(`reStake failed for service ${index}: ${reStakeHash}`);
-        }
-        console.error(`[fleet-bootstrap] Service ${index}: reStake confirmed (tx: ${reStakeHash})`);
         // Service is now Staked again with the same service_id, safe_address, and mech_address.
         // Step back to `mech_deployed` so the resume loop advances through
         // `stepRegisterAgent` (idempotent — short-circuits if `agent_id` is
@@ -837,6 +1311,7 @@ export class FleetBootstrapper {
         let svc = (await this.store.load(this.chain)).services.find(s => s.index === index);
         if (!svc)
             throw new Error(`Service ${index} not found in state`);
+        const fleetSnapshot = await this.store.load(this.chain);
         const identityRegistry = this.config.identityRegistry
             ?? IDENTITY_REGISTRY_ADDRESSES[this.config.chainId];
         if (!identityRegistry) {
@@ -845,7 +1320,7 @@ export class FleetBootstrapper {
         }
         const agentSigner = deriveAgentSigner(mnemonic, index);
         const agentWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, agentSigner);
-        // ── Sub-step A: mint NFT (skip if agent_id is already set). ─────────
+        // ── Sub-step A: mint NFT (skip if agent_id is already set OR fleet identity exists). ─
         let agentId;
         if (svc.agent_id) {
             console.error(`[fleet-bootstrap] Service ${index}: ERC-8004 agent already registered ` +
@@ -856,6 +1331,22 @@ export class FleetBootstrapper {
                 step: svc.step === 'safe_binding_pending' ? 'safe_binding_pending' : 'agent_registered',
             });
         }
+        else if (fleetSnapshot.fleet_agent_id) {
+            // nghf: reuse the fleet-level agentId minted by ensureStage1 instead of
+            // minting a second one. This collapses the "one agentId per user"
+            // invariant in spec §5.1 for the standard-mode two-Safe topology.
+            console.error(`[fleet-bootstrap] Service ${index}: reusing fleet agentId=${fleetSnapshot.fleet_agent_id} ` +
+                `(no second mint needed).`);
+            agentId = fleetSnapshot.fleet_agent_id;
+            svc = await this.firstServiceUpdate(index, {
+                agent_id: fleetSnapshot.fleet_agent_id,
+                agent_uri: '',
+                identity_registry_address: fleetSnapshot.fleet_identity_registry ?? getAddress(identityRegistry),
+                agent_registered_tx: null,
+                step: 'agent_registered',
+                error: null,
+            });
+        }
         else {
             // v0: empty agentURI. The richer agent card (per §6 of the spec) is
             // future work — operators may later call `setAgentURI`.
@@ -924,8 +1415,18 @@ export class FleetBootstrapper {
                 step: 'safe_binding_pending',
                 error: null,
             });
+            // Unified retry policy (jinn-mono-k1ng — supersedes h74p's throw-only
+            // retry): retry on `ok: false` and on thrown exceptions. The h74p
+            // version only caught throws, but `bindAgentWalletToSafe` returns
+            // `ok: false` for the documented freshly-deployed-Safe revert race —
+            // so the retry was dead code under real RPC. Per-service "worked"
+            // anyway because the next bootstrap resumes from `safe_binding_pending`;
+            // k1ng makes the in-process retry actually do its job so we don't
+            // depend on the operator restarting the daemon.
+            let bindResult;
+            let lastBindError;
             try {
-                const result = await bindAgentWalletToSafe({
+                bindResult = await this.bindAgentWalletWithRetry({
                     identityRegistryAddress: addr(identityRegistry),
                     agentId: BigInt(agentId),
                     safeAddress: addr(safeAddress),
@@ -933,23 +1434,45 @@ export class FleetBootstrapper {
                     agentEoaWalletClient: agentWallet,
                     publicClient: this.publicClient,
                     chainId: this.config.chainId,
-                });
+                }, `Service ${index}`);
+            }
+            catch (err) {
+                lastBindError = err;
+            }
+            if (bindResult?.ok === true) {
                 console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet succeeded ` +
-                    `(tx=${result.txHash}, safe=${safeAddress}).`);
+                    `(tx=${bindResult.txHash}, safe=${safeAddress}).`);
                 svc = await this.firstServiceUpdate(index, {
                     safe_bound_to_agent: true,
                     step: 'complete',
                     error: null,
+                    error_revert_reason: null,
+                    error_short_message: null,
                 });
             }
-            catch (err) {
-                const reason = err instanceof Error ? err.message : String(err);
-                console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet failed; continuing with ` +
-                    `safe_bound_to_agent=false (${reason}).`);
+            else if (bindResult && !bindResult.ok) {
+                const bindErr = bindResult.error;
+                console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet failed after retries; ` +
+                    `continuing with safe_bound_to_agent=false (${bindErr.shortMessage}` +
+                    `${bindErr.revertReason ? `, revert: ${bindErr.revertReason}` : ''}).`);
+                svc = await this.firstServiceUpdate(index, {
+                    safe_bound_to_agent: false,
+                    step: 'safe_binding_pending',
+                    error: `safe_binding_failed: ${bindErr.shortMessage}`,
+                    error_revert_reason: bindErr.revertReason,
+                    error_short_message: bindErr.shortMessage,
+                });
+            }
+            else {
+                const reason = lastBindError instanceof Error ? lastBindError.message : String(lastBindError);
+                console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet threw on every attempt; ` +
+                    `continuing with safe_bound_to_agent=false (${reason}).`);
                 svc = await this.firstServiceUpdate(index, {
                     safe_bound_to_agent: false,
                     step: 'safe_binding_pending',
                     error: `safe_binding_failed: ${reason}`,
+                    error_revert_reason: null,
+                    error_short_message: null,
                 });
             }
         }
@@ -1066,8 +1589,10 @@ export class FleetBootstrapper {
             if (receipt.status !== 'success') {
                 throw new Error(`Safe deployment tx failed for service ${index}: ${deployHash}`);
             }
-            const deployedCode = await this.publicClient.getCode({ address: getAddress(safeAddress) });
-            if (deployedCode === undefined || deployedCode === '0x') {
+            try {
+                await waitForContractCode(this.publicClient, getAddress(safeAddress));
+            }
+            catch {
                 throw new Error(`Safe deployment succeeded but no code at ${safeAddress}`);
             }
             console.error(`[fleet-bootstrap] Service ${index}: Safe deployed (tx: ${deployHash})`);
@@ -1431,4 +1956,50 @@ export class FleetBootstrapper {
 }
 /** @deprecated Use FleetBootstrapper */
 export const EarningBootstrapper = FleetBootstrapper;
+/**
+ * Re-stake an evicted service by calling `distributor.reStake(stakingProxy, serviceId)`.
+ *
+ * Extracted from `FleetBootstrapper.recoverEvictedService` so it can be called
+ * from the in-process `EvictionLoop` without requiring a full bootstrapper
+ * context (jinn-mono-hjex.3).
+ *
+ * The caller is responsible for advancing the local service step back to
+ * `mech_deployed` after this returns (just like the bootstrapper resume path does).
+ */
+export async function recoverEvictedService(opts) {
+    const { serviceDisplayIndex, serviceId, stakingAddress, distributorAddress, rpcUrl, chain, mnemonic, } = opts;
+    const masterAccount = deriveMasterSigner(mnemonic);
+    const publicClient = createJinnPublicClient(rpcUrl, chain);
+    const masterWallet = createJinnWalletClient(rpcUrl, chain, masterAccount);
+    const reStakeData = encodeFunctionData({
+        abi: STOLAS_DISTRIBUTOR_ABI,
+        functionName: 'reStake',
+        args: [addr(stakingAddress), BigInt(serviceId)],
+    });
+    console.error(`[eviction-recovery] Service ${serviceDisplayIndex}: calling distributor.reStake() for evicted service ${serviceId}`);
+    let reStakeHash;
+    try {
+        reStakeHash = await viemSendTransactionWithRetry(masterWallet, publicClient, {
+            account: masterAccount,
+            to: addr(distributorAddress),
+            data: reStakeData,
+            gas: 1500000n,
+        });
+    }
+    catch (err) {
+        const message = flattenErrorMessage(err);
+        if (isUnauthorizedAccountError(message)) {
+            throw new Error(`Service ${serviceDisplayIndex} (service_id ${serviceId}) is evicted on the staking proxy, but master EOA ` +
+                `${masterAccount.address} is not authorized to reStake it. ` +
+                `Verify JINN_EARNING_DIR and JINN_PASSWORD derive the original master EOA for this service. ` +
+                `reStake revert: ${message}`);
+        }
+        throw err;
+    }
+    const receipt = await waitForTransactionReceiptWithRetry(publicClient, reStakeHash);
+    if (receipt.status !== 'success') {
+        throw new Error(`reStake failed for service ${serviceDisplayIndex}: ${reStakeHash}`);
+    }
+    console.error(`[eviction-recovery] Service ${serviceDisplayIndex}: reStake confirmed (tx: ${reStakeHash})`);
+}
 //# sourceMappingURL=bootstrap.js.map