@jinn-network/client 0.1.6 → 0.1.7

package/dist/discovery/types.d.ts

@@ -145,6 +145,36 @@ export interface DiscoveryAPI {
      * `undefined` if no lifecycle events have been recorded for it yet.
      */
     getLifecycleStatus(manifestCid: string): Promise<SolverNetLifecycleStatus | undefined>;
+    /**
+     * Returns the number of distinct operators that have *ever* claimed a task
+     * on the SolverNet identified by `manifestCid` — i.e. the count of unique
+     * `attempt.operator` Safe addresses across every task whose
+     * `manifestDigest === keccak256(manifestCid)`, **including tasks that are
+     * now finalized or refunded**.
+     *
+     * This is an *ever-participated* signal, not a "currently active" one. The
+     * count never filters on task lifecycle state: the on-chain backing reads
+     * raw `TaskAttemptCreated` logs, which carry no finalized/refunded flag, so
+     * the only count consistent across all three backings (HTTP / embedded /
+     * on-chain) is the all-time distinct-operator total. Treat it as "operators
+     * who have participated at least once", not "operators participating today".
+     *
+     * It is the protocol-observable participation signal: a "join" in the
+     * operator app is purely a local config write (`joinedSolverNets[<cid>]`,
+     * see `spec/2026-05-05-solvernet-creation-and-launch.md` §12) and leaves no
+     * on-chain footprint. An operator only becomes visible to the network once
+     * they claim a task — `TaskAttemptCreated` is the first on-chain event tied
+     * to (operator, SolverNet). This method therefore counts *participating*
+     * operators (operators who have claimed at least one task), which is the
+     * only honest cross-operator count derivable from the indexer / chain.
+     *
+     * Task pagination is hard-capped (`MAX_OPERATOR_COUNT_TASK_PAGES` in each
+     * backing) so a pathological task volume cannot turn this into an unbounded
+     * scan; on a SolverNet beyond the cap the count is a lower bound.
+     *
+     * Returns `0` when no operator has attempted a task on the SolverNet yet.
+     */
+    getSolverNetOperatorCount(manifestCid: string): Promise<number>;
     /**
      * Returns envelope refs matching the query. Refs only — byte retrieval is
      * done by the corpus library on demand.
@@ -200,7 +230,21 @@ export interface DiscoveryAPI {
  * The `withFallback` wrapper catches this class (plus network-shaped errors)
  * and routes to the floor implementation for the duration of the outage.
  */
+/**
+ * Machine-readable reason a discovery read failed. `rpc_rate_limited` is the
+ * one branch callers act on distinctly: it means the configured RPC endpoint
+ * returned a 429 (or otherwise rate-limited the daemon), which — on the shared
+ * default RPC — is an operator-actionable condition ("add your own key"), not
+ * an indexer outage. Any other transport failure is left untyped (`undefined`).
+ */
+export type DiscoveryUnavailableCode = 'rpc_rate_limited';
 export declare class DiscoveryUnavailableError extends Error {
     readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
+    /**
+     * Typed reason, when one can be classified — currently only
+     * `rpc_rate_limited`, surfaced end-to-end so the operator UI can render a
+     * distinct "your RPC is throttled" message instead of a generic failure.
+     */
+    readonly code?: DiscoveryUnavailableCode;
+    constructor(message: string, cause?: unknown, code?: DiscoveryUnavailableCode);
 }

package/dist/discovery/types.js

@@ -9,21 +9,19 @@
  *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §5.
  */
-// ── Error ────────────────────────────────────────────────────────────────────
-/**
- * Thrown by a DiscoveryAPI implementation when it is temporarily unable to
- * serve a request — e.g. indexer unreachable, embedded Ponder still syncing,
- * hosted subgraph 5xx.
- *
- * The `withFallback` wrapper catches this class (plus network-shaped errors)
- * and routes to the floor implementation for the duration of the outage.
- */
 export class DiscoveryUnavailableError extends Error {
     cause;
-    constructor(message, cause) {
+    /**
+     * Typed reason, when one can be classified — currently only
+     * `rpc_rate_limited`, surfaced end-to-end so the operator UI can render a
+     * distinct "your RPC is throttled" message instead of a generic failure.
+     */
+    code;
+    constructor(message, cause, code) {
         super(message);
         this.name = 'DiscoveryUnavailableError';
         this.cause = cause;
+        this.code = code;
     }
 }
 //# sourceMappingURL=types.js.map

package/dist/discovery/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgOH,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAChC,KAAK,CAAW;IAElC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkRH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAChC,KAAK,CAAW;IAClC;;;;OAIG;IACM,IAAI,CAA4B;IAEzC,YAAY,OAAe,EAAE,KAAe,EAAE,IAA+B;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/discovery/with-fallback.d.ts

@@ -12,6 +12,13 @@
  * operators can see why their daemon is running slowly. After the window
  * elapses the wrapper probes the primary again on the next call.
  *
+ * NOTE (2026-05-23): this wrapper is no longer engaged by default. The
+ * factory installs it only when `discovery.fallbackToOnchain === true` (an
+ * explicit opt-in). Without the opt-in, indexer outages propagate as
+ * DiscoveryUnavailableError so the operator-app surfaces them rather than the
+ * daemon silently storming shared RPC. The wrapper itself is unchanged for
+ * operators who still want it.
+ *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §9.3.
  */
 import type { DiscoveryAPI } from './types.js';

package/dist/discovery/with-fallback.js

@@ -12,6 +12,13 @@
  * operators can see why their daemon is running slowly. After the window
  * elapses the wrapper probes the primary again on the next call.
  *
+ * NOTE (2026-05-23): this wrapper is no longer engaged by default. The
+ * factory installs it only when `discovery.fallbackToOnchain === true` (an
+ * explicit opt-in). Without the opt-in, indexer outages propagate as
+ * DiscoveryUnavailableError so the operator-app surfaces them rather than the
+ * daemon silently storming shared RPC. The wrapper itself is unchanged for
+ * operators who still want it.
+ *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §9.3.
  */
 import { DiscoveryUnavailableError } from './types.js';
@@ -145,6 +152,9 @@ export function withFallback(primary, floor, opts = {}) {
         getLifecycleStatus(manifestCid) {
             return dispatch(() => primary.getLifecycleStatus(manifestCid), () => floor.getLifecycleStatus(manifestCid));
         },
+        getSolverNetOperatorCount(manifestCid) {
+            return dispatch(() => primary.getSolverNetOperatorCount(manifestCid), () => floor.getSolverNetOperatorCount(manifestCid));
+        },
         queryEnvelopes(query) {
             return dispatch(() => primary.queryEnvelopes(query), () => floor.queryEnvelopes(query));
         },

package/dist/discovery/with-fallback.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-fallback.js","sourceRoot":"","sources":["../../src/discovery/with-fallback.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"with-fallback.js","sourceRoot":"","sources":["../../src/discovery/with-fallback.ts"],"names":[],"mappings":"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"}

package/dist/earning/bootstrap.d.ts

@@ -4,8 +4,78 @@
  * Phase 1 (master): generate mnemonic → fund master EOA
  * Phase 2 (per-service): derive agent → stake → deploy mech
  */
-import type { FleetState, FleetBootstrapResult } from './types.js';
+import type { FleetState, FleetBootstrapResult, StakingMode } from './types.js';
 import { requestTestnetFunding } from './faucet.js';
+import { type JinnOnchainNetwork } from './viem-clients.js';
+/**
+ * 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.
+ *
+ * Used by {@link stage1MinMasterEth} to size the Stage 1 master gas budget.
+ *
+ * Single source of truth: imported by funding-plan.ts.
+ */
+export declare const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * Self-bond mode needs much more ETH per service than standard mode because
+ * the master funds the agent which then pays for: Safe deploy, 5 service
+ * registry txs (create, activate, register, deploy, stake), and mech deploy.
+ * Roughly 15 txs at varying gas costs. 0.03 ETH per service is a safe
+ * estimate. Single source of truth: imported by funding-plan.ts.
+ */
+export declare const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n;
+/**
+ * Single source of truth for the master-ETH cold-start funding gate.
+ *
+ * Both the mutating bootstrapper ({@link FleetBootstrapper.ensureStage1And2})
+ * and the read-only funding plan (`planFleetFunding` in funding-plan.ts) route
+ * through this helper, so a migration-wiped fleet computes an identical
+ * required-ETH gate in both views. Re-implementing the gate inline at either
+ * call site is the u34i cross-module invariant-drift hazard — do not do it.
+ *
+ * Standard-mode gate has three branches:
+ *   1. `standardFleetAlreadyComplete` — fleet already has its full target of
+ *      operational services and no deprecated-setup migration is pending →
+ *      `0n` (nothing to fund).
+ *   2. `preStage1` — no fleet identity yet (`fleet_stage === 'none'` or no
+ *      fleet state at all) → the Stage 1 gate from {@link stage1MinMasterEth},
+ *      which covers the master → agent transfer plus the master's own gas
+ *      reserve. See jinn-mono-u34i.
+ *   3. otherwise — the Stage 2 master gas budget: `minEoaGasEth` (stake gas)
+ *      plus a per-extra-service top-up transfer for services 2..N.
+ *
+ * Self-bond mode is a flat `SELF_BOND_ETH_PER_SERVICE × targetServices`
+ * regardless of stage.
+ *
+ * @param services         Persisted service states
+ * @param minEoaGasEth     Configured minimum EOA gas target (wei)
+ * @param pendingSetupMigration  True when a deprecated testnet setup is
+ *   detected — suppresses the `standardFleetAlreadyComplete` short-circuit so a
+ *   migration-wiped fleet is correctly treated as needing funding. Both call
+ *   sites MUST pass this so the bootstrapper gate and the funding-plan view
+ *   agree for migration-wiped fleets.
+ * @param targetServices   How many services the fleet is aiming for
+ * @param stakingMode      `'standard'` (default) or `'self-bond'`
+ * @param preStage1        True when fleet identity is not yet provisioned —
+ *   selects the Stage 1 gate. The bootstrapper passes `false` here because it
+ *   only computes this gate *after* `ensureStage1` succeeds.
+ */
+export declare function computeRequiredMasterEth({ services, minEoaGasEth, pendingSetupMigration, targetServices, stakingMode, preStage1, }: {
+    services: Array<{
+        service_id?: number | null | undefined;
+        step?: string;
+    }>;
+    minEoaGasEth: bigint;
+    pendingSetupMigration?: boolean;
+    targetServices?: number;
+    stakingMode?: StakingMode;
+    preStage1?: boolean;
+}): bigint;
 /** 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
@@ -286,3 +356,24 @@ export declare class FleetBootstrapper {
 }
 /** @deprecated Use FleetBootstrapper */
 export declare const EarningBootstrapper: typeof FleetBootstrapper;
+export interface RecoverEvictedServiceOptions {
+    /** Display index of the service (used only for log messages). */
+    serviceDisplayIndex: number;
+    serviceId: number;
+    stakingAddress: string;
+    distributorAddress: string;
+    rpcUrl: string;
+    chain: JinnOnchainNetwork;
+    mnemonic: string;
+}
+/**
+ * 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 declare function recoverEvictedService(opts: RecoverEvictedServiceOptions): Promise<void>;

package/dist/earning/bootstrap.js

@@ -20,11 +20,95 @@ 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.
+ *
+ * Used by {@link stage1MinMasterEth} to size the Stage 1 master gas budget.
+ *
+ * Single source of truth: imported by funding-plan.ts.
+ */
+export const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * Self-bond mode needs much more ETH per service than standard mode because
+ * the master funds the agent which then pays for: Safe deploy, 5 service
+ * registry txs (create, activate, register, deploy, stake), and mech deploy.
+ * Roughly 15 txs at varying gas costs. 0.03 ETH per service is a safe
+ * estimate. Single source of truth: imported by funding-plan.ts.
+ */
+export const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n; // 0.03 ETH
+/**
+ * Single source of truth for the master-ETH cold-start funding gate.
+ *
+ * Both the mutating bootstrapper ({@link FleetBootstrapper.ensureStage1And2})
+ * and the read-only funding plan (`planFleetFunding` in funding-plan.ts) route
+ * through this helper, so a migration-wiped fleet computes an identical
+ * required-ETH gate in both views. Re-implementing the gate inline at either
+ * call site is the u34i cross-module invariant-drift hazard — do not do it.
+ *
+ * Standard-mode gate has three branches:
+ *   1. `standardFleetAlreadyComplete` — fleet already has its full target of
+ *      operational services and no deprecated-setup migration is pending →
+ *      `0n` (nothing to fund).
+ *   2. `preStage1` — no fleet identity yet (`fleet_stage === 'none'` or no
+ *      fleet state at all) → the Stage 1 gate from {@link stage1MinMasterEth},
+ *      which covers the master → agent transfer plus the master's own gas
+ *      reserve. See jinn-mono-u34i.
+ *   3. otherwise — the Stage 2 master gas budget: `minEoaGasEth` (stake gas)
+ *      plus a per-extra-service top-up transfer for services 2..N.
+ *
+ * Self-bond mode is a flat `SELF_BOND_ETH_PER_SERVICE × targetServices`
+ * regardless of stage.
+ *
+ * @param services         Persisted service states
+ * @param minEoaGasEth     Configured minimum EOA gas target (wei)
+ * @param pendingSetupMigration  True when a deprecated testnet setup is
+ *   detected — suppresses the `standardFleetAlreadyComplete` short-circuit so a
+ *   migration-wiped fleet is correctly treated as needing funding. Both call
+ *   sites MUST pass this so the bootstrapper gate and the funding-plan view
+ *   agree for migration-wiped fleets.
+ * @param targetServices   How many services the fleet is aiming for
+ * @param stakingMode      `'standard'` (default) or `'self-bond'`
+ * @param preStage1        True when fleet identity is not yet provisioned —
+ *   selects the Stage 1 gate. The bootstrapper passes `false` here because it
+ *   only computes this gate *after* `ensureStage1` succeeds.
+ */
+export function computeRequiredMasterEth({ services, minEoaGasEth, pendingSetupMigration = false, targetServices = 1, stakingMode = 'standard', preStage1 = false, }) {
+    if (stakingMode !== 'standard') {
+        return SELF_BOND_ETH_PER_SERVICE * BigInt(targetServices);
+    }
+    // Reconciled `standardFleetAlreadyComplete` — a single definition replacing
+    // the three historic inline variants. Adopts the strictest of them (the
+    // FleetBootstrapper variant): the fleet must have at least `targetServices`
+    // rows AND every row must be operational AND no deprecated-setup migration
+    // may be pending. A migration-wiped fleet (which sets
+    // `pendingSetupMigration`) is therefore never short-circuited to `0n`.
+    const standardFleetAlreadyComplete = services.length >= targetServices &&
+        services.every(s => s.step !== undefined && isOperationalServiceStep(s.step)) &&
+        !pendingSetupMigration;
+    if (standardFleetAlreadyComplete)
+        return 0n;
+    if (preStage1) {
+        // Stage 1 gate: master → agent transfer (STAGE1_AGENT_ETH) + the master's
+        // own gas reserve, plus per-extra-service transfers. See jinn-mono-u34i.
+        return stage1MinMasterEth({ minEoaGasEth }, targetServices);
+    }
+    // Stage 2 master gas budget — covers distributor.stake() (~0.003 ETH at
+    // typical 6 gwei Base Sepolia) plus per-extra-service top-up transfers.
+    // Service 1 piggybacks on HD-1's Stage 1 funding, so the base term is a
+    // single `minEoaGasEth` (not `× 2`). See jinn-mono-u34i.
+    return minEoaGasEth + minEoaGasEth * BigInt(Math.max(0, targetServices - 1));
+}
 /** 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
@@ -389,12 +473,8 @@ export class FleetBootstrapper {
             // 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
-            // funds the agent which then pays for: Safe deploy, 5 service registry txs
-            // (create, activate, register, deploy, stake), and mech deploy. Roughly
-            // 15 txs at varying gas costs. 0.03 ETH per service is a safe estimate.
-            // On re-runs, include ETH already held by funded agents/safes in the total.
-            const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n; // 0.03 ETH
+            // On re-runs, include ETH already held by funded agents/safes in the
+            // total for self-bond mode.
             let systemEth = masterBalance;
             if (this.stakingMode === 'self-bond') {
                 for (const svc of state.services) {
@@ -416,26 +496,20 @@ 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;
-            const requiredMasterEth = this.stakingMode === 'standard'
-                ? (standardFleetAlreadyComplete
-                    ? 0n
-                    // 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);
+            // Single source of truth: the master-ETH gate is computed by
+            // `computeRequiredMasterEth` (defined above), the same helper the
+            // read-only `planFleetFunding` view routes through. Re-deriving it inline
+            // here is the u34i cross-module invariant-drift hazard. `ensureStage1And2`
+            // only reaches this point AFTER `ensureStage1` has succeeded, so the
+            // fleet is always past Stage 1 — `preStage1` is `false`.
+            const requiredMasterEth = computeRequiredMasterEth({
+                services: state.services,
+                minEoaGasEth: this.config.minEoaGasEth,
+                pendingSetupMigration,
+                targetServices: this.targetServices,
+                stakingMode: this.stakingMode,
+                preStage1: false,
+            });
             const autoFaucetEnabled = this.autoTestnetFaucet;
             // Re-sum system ETH (master + agent/safe balances for self-bond mode).
             // Hoisted so the drip loop below can refresh cheaply.
@@ -578,7 +652,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);
@@ -594,11 +668,21 @@ 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 } : {}),
             };
         }
     }
@@ -1044,6 +1128,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) {
@@ -1109,42 +1226,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
@@ -1897,4 +1991,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