@jinn-network/client 0.1.5 → 0.1.6-canary.0b4ff7f9

package/dist/earning/bootstrap.d.ts

@@ -45,6 +45,16 @@ export interface FleetBootstrapperOptions {
      * testnet funding an explicit operator action.
      */
     autoTestnetFaucet?: boolean;
+    /**
+     * Max in-process attempts for the ERC-8004 Safe-binding step (jinn-mono-h74p).
+     * Defaults to 3. Tests pass small values to keep retry budgets predictable.
+     */
+    safeBindingMaxAttempts?: number;
+    /**
+     * Delay between Safe-binding retries (jinn-mono-h74p). Defaults to 3000 ms
+     * (~1.5 Base Sepolia blocks). Tests pass 0 to skip the sleep entirely.
+     */
+    safeBindingRetryDelayMs?: number;
 }
 export declare class FleetBootstrapper {
     private readonly store;
@@ -60,6 +70,8 @@ export declare class FleetBootstrapper {
     private readonly faucetLoopTimeoutMs;
     private readonly now;
     private readonly autoTestnetFaucet;
+    private readonly safeBindingMaxAttempts;
+    private readonly safeBindingRetryDelayMs;
     constructor(options?: FleetBootstrapperOptions);
     getStatus(): Promise<FleetState>;
     /**
@@ -83,6 +95,43 @@ export declare class FleetBootstrapper {
      * IdentityCard's "binding pending" chip on Overview.
      */
     retryAgentBindingFor(serviceIndex: number, password: string): Promise<FleetState>;
+    /**
+     * 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.
+     */
+    ensureStage1(password: string): Promise<FleetBootstrapResult>;
+    /**
+     * 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.
+     */
+    ensureStage1And2(password: string): Promise<FleetBootstrapResult>;
+    /**
+     * 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.
+     */
     bootstrap(password: string): Promise<FleetBootstrapResult>;
     /**
      * If the master is only slightly above the minimum, warn about gas runway (heuristic days).
@@ -90,6 +139,12 @@ export declare class FleetBootstrapper {
     private warnMasterEthRunway;
     private ensureMasterWallet;
     private loadExistingMnemonic;
+    /** Deterministic Safe predict from the HD-index-1 agent EOA. */
+    private stepFleetSafePredict;
+    /** Deploy the predicted fleet Safe. Funds the agent EOA from master if needed. */
+    private stepFleetSafeDeploy;
+    /** Mint the fleet agentId + bind Safe via setAgentWallet (ERC-1271). */
+    private stepFleetIdentityRegister;
     private bootstrapService;
     /**
      * Compare persisted per-service state to registry/staking/Safe bytecode and patch store

package/dist/earning/bootstrap.js

@@ -15,7 +15,7 @@ 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, 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';
@@ -29,6 +29,28 @@ const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
 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 +65,8 @@ export class FleetBootstrapper {
     faucetLoopTimeoutMs;
     now;
     autoTestnetFaucet;
+    safeBindingMaxAttempts;
+    safeBindingRetryDelayMs;
     constructor(options = {}) {
         this.store = new FleetStateStore(options.earningDir);
         this.chain = options.chain ?? 'base';
@@ -55,6 +79,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
@@ -112,16 +140,145 @@ 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). Self-bond Stage 1 needs:
+            // master ETH for the agent-funding transfer + agent ETH for Safe deploy
+            // + Safe deploy gas + ERC-8004 register + setAgentWallet (two agent EOA
+            // txs through the IdentityRegistry contract). 0.005 ETH is the
+            // configured `minEoaGasEth` floor; bump by 2x for safety.
+            const requiredMasterEth = this.config.minEoaGasEth * STANDARD_MASTER_BOOTSTRAP_MULTIPLIER;
+            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
@@ -291,6 +448,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,
@@ -322,6 +484,14 @@ export class FleetBootstrapper {
             };
         }
     }
+    /**
+     * 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 +552,128 @@ 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.
+        const STAGE1_AGENT_ETH = 10000000000000000n; // 0.01 ETH
+        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}`);
+        }
+        const deployedCode = await this.publicClient.getCode({
+            address: getAddress(fleetSafe),
+        });
+        if (deployedCode === undefined || deployedCode === '0x') {
+            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).
+        console.error(`[fleet-bootstrap] Stage 1: binding fleet Safe ${fleetSafe} to agentId=${fleetAgentId}`);
+        const bindResult = await bindAgentWalletToSafe({
+            identityRegistryAddress: addr(identityRegistry),
+            agentId: BigInt(fleetAgentId),
+            safeAddress: addr(fleetSafe),
+            agentEoaAccount: agentSigner,
+            agentEoaWalletClient: agentWallet,
+            publicClient: this.publicClient,
+            chainId: this.config.chainId,
+        });
+        if (!bindResult.ok) {
+            const bindErr = bindResult.error;
+            throw new Error(`Fleet setAgentWallet failed: ${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);
@@ -837,6 +1129,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 +1138,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 +1149,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,32 +1233,79 @@ export class FleetBootstrapper {
                 step: 'safe_binding_pending',
                 error: null,
             });
-            try {
-                const result = await bindAgentWalletToSafe({
-                    identityRegistryAddress: addr(identityRegistry),
-                    agentId: BigInt(agentId),
-                    safeAddress: addr(safeAddress),
-                    agentEoaAccount: agentSigner,
-                    agentEoaWalletClient: agentWallet,
-                    publicClient: this.publicClient,
-                    chainId: this.config.chainId,
-                });
+            // Combined h74p (retry-on-transient-throw) + hjex.4 (Result-typed
+            // structured errors) policy:
+            //   - bindAgentWalletToSafe now returns a BindAgentWalletOutcome
+            //     (ok=true | ok=false with structured SafeBindingError).
+            //   - A returned Result.ok=false is a deterministic contract revert —
+            //     don't retry; record the structured diagnostic.
+            //   - A *thrown* exception is the freshly-deployed-Safe RPC race
+            //     window h74p targets — retry up to safeBindingMaxAttempts with a
+            //     small delay; if every attempt throws we fall through to a plain
+            //     reason log (no structured fields available).
+            const maxAttempts = Math.max(1, this.safeBindingMaxAttempts);
+            let bindResult;
+            let lastBindError;
+            for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                try {
+                    bindResult = await bindAgentWalletToSafe({
+                        identityRegistryAddress: addr(identityRegistry),
+                        agentId: BigInt(agentId),
+                        safeAddress: addr(safeAddress),
+                        agentEoaAccount: agentSigner,
+                        agentEoaWalletClient: agentWallet,
+                        publicClient: this.publicClient,
+                        chainId: this.config.chainId,
+                    });
+                    break;
+                }
+                catch (err) {
+                    lastBindError = err;
+                    if (attempt < maxAttempts) {
+                        const reason = err instanceof Error ? err.message : String(err);
+                        console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet attempt ` +
+                            `${attempt}/${maxAttempts} failed (${reason}); retrying in ` +
+                            `${this.safeBindingRetryDelayMs}ms...`);
+                        if (this.safeBindingRetryDelayMs > 0) {
+                            await sleep(this.safeBindingRetryDelayMs);
+                        }
+                    }
+                }
+            }
+            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);
+            else if (bindResult && !bindResult.ok) {
+                const bindErr = bindResult.error;
                 console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet failed; continuing with ` +
-                    `safe_bound_to_agent=false (${reason}).`);
+                    `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 failed after ` +
+                    `${maxAttempts} attempts; 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,
                 });
             }
         }