@senpi/runtime 3.0.72 → 3.0.73

package/dist/index.js

@@ -17,6 +17,7 @@ import { SenpiClient } from "./senpi/client.js";
 import { buildWalletStatusHint } from "./senpi/strategy-status.js";
 import { DeployJobController } from "./deploy/job.js";
 import { registerDeployGatewayMethods } from "./deploy/register.js";
+import { INSTALL_DEADLINE_MS, WALLET_INSTALL_IN_FLIGHT_CODE } from "./deploy/deadlines.js";
 import { AuditQueryError } from "./runtime/audit-query.types.js";
 import { buildRuntimeStateDir, archiveStateDir } from "./runtime/state-layout.js";
 import { describeRuntimeEntry } from "./runtime/runtime-descriptor.js";
@@ -137,6 +138,13 @@ const PLUGIN_PACKAGE_NAME = resolvePackageName();
  * nothing about the decision a caller has to make.
  */
 const WALLET_HAS_RUNTIME = "[E_WALLET_HAS_RUNTIME]";
+/**
+ * The fence refusal's code, IMPORTED rather than spelled here — `deploy/messages.ts` renders the
+ * same code for the same condition on the deploy path, and two module-private literals were one
+ * edit away from answering two different codes for one condition. See its doc in `deadlines.ts`
+ * for why it lives beside the install bound both copies quote.
+ */
+const WALLET_INSTALL_IN_FLIGHT = `[${WALLET_INSTALL_IN_FLIGHT_CODE}]`;
 /**
  * The id-collision refusal's code — the third gate on the same `senpi runtime create` path, and
  * plausibly the one hit most often, since re-running create with the same id lands on it.
@@ -342,6 +350,23 @@ const senpiRuntimePlugin = {
                 scanners: config.scanners ?? [],
             });
         };
+        /**
+         * Wallets with an install IN FLIGHT in this process, keyed by lowercased address.
+         *
+         * IN MEMORY, never persisted — the same reasoning `deploy/job.ts` gives for the single-flight
+         * slot. `installRuntimeCore` is in-process work, so a pending install cannot outlive this
+         * process: if the gateway dies mid-install, the install dies with it and the row it left
+         * behind is the ordinary "registry row with no live handle" case that deploy already handles by
+         * deleting and reinstalling. A persisted marker would need a liveness heuristic to tell those
+         * apart, and would wedge every install on the box after one crash.
+         *
+         * What it prevents: a deploy whose wait on an install expired (or whose job was force-
+         * terminated) frees its slot while the install runs on. Without this, the next deploy finds the
+         * row, sees no live handle, deletes it and reinstalls — and the first install then lands on top,
+         * clobbering `runtimeHandles` under a runtime id both installs derive identically. Two exit
+         * engines, one margin account: the exact state `[E_WALLET_HAS_RUNTIME]` exists to prevent.
+         */
+        const installsInFlight = new Map();
         // Dedicated logger for the runtime-api subtree — required because the
         // PluginLogger surface (info/warn/error) lacks `debug`, while the
         // Logger contract used by `runtime-api/` includes it.
@@ -1015,6 +1040,7 @@ const senpiRuntimePlugin = {
             const resolvedId = id && id.length > 0
                 ? (sanitizeId(id) || "runtime")
                 : deriveRuntimeId(runtimeName, wallet);
+            const walletKey = (wallet ?? "").trim().toLowerCase();
             if (hasId(registry, resolvedId)) {
                 return { ok: false, error: toError(`${RUNTIME_ID_TAKEN} A runtime with id "${resolvedId}" already exists. Use a different id (e.g. --runtime-id another-name) or remove the existing one first: openclaw senpi runtime delete ${resolvedId}`) };
             }
@@ -1039,9 +1065,28 @@ const senpiRuntimePlugin = {
              * both, because the registry stores `strategy.wallet` verbatim from the YAML and a
              * checksummed address is the same margin account as its lowercase spelling.
              */
-            if (wallet) {
-                const walletKey = wallet.toLowerCase();
-                const liveId = [...runtimeHandles].find(([, handle]) => (handle.wallet ?? "").toLowerCase() === walletKey)?.[0];
+            // Gated on the FOLDED key, not on the raw field. `strategy.wallet` only has to be
+            // `z.string().min(1)`, so a whitespace-only value reaches here with `walletKey === ""` — and
+            // an empty key is not an identity: the live-handle compare below folds the same way, so `""`
+            // matched every handle carrying no wallet at all and refused the install with
+            // `[E_WALLET_HAS_RUNTIME]` naming an unrelated runtime. (`findByWallet` already refuses to
+            // match on an empty address for exactly this reason, and the fence is keyed on `walletKey`
+            // too, so a blank one is never set.) Nothing is skipped that could have matched.
+            if (walletKey) {
+                const inFlight = installsInFlight.get(walletKey);
+                if (inFlight) {
+                    const heldSec = Math.round((Date.now() - inFlight.startedAtMs) / 1000);
+                    const boundSec = Math.round(INSTALL_DEADLINE_MS / 1000);
+                    return { ok: false, error: toError(`${WALLET_INSTALL_IN_FLIGHT} An install is already running on wallet "${wallet}" ` +
+                            `(runtime "${inFlight.runtimeId}", started ${heldSec}s ago) in this gateway. Installing a ` +
+                            `second runtime on the same wallet would put two exit engines on one margin account. ` +
+                            `Nothing was installed and nothing was changed. This normally clears on its own once that ` +
+                            `install finishes. A deploy's own install bound is ${boundSec}s — well past that, this install ` +
+                            `is more likely wedged than merely slow, and if so the fence on this wallet will not clear ` +
+                            `until this gateway process restarts. Check what it produced before installing anything here: ` +
+                            `openclaw senpi deploy status, then openclaw senpi runtime list.`) };
+                }
+                const liveId = [...runtimeHandles].find(([, handle]) => (handle.wallet ?? "").trim().toLowerCase() === walletKey)?.[0];
                 // Which runtime holds this wallet, from either read. The live half matches on
                 // `handle.wallet`, the registry half on `entry.wallet`, so the id is what they have in
                 // common — and it is the id, not which read matched, that the two messages differ on.
@@ -1072,197 +1117,205 @@ const senpiRuntimePlugin = {
                             `openclaw senpi runtime delete --id ${holderId}`) };
                 }
             }
-            // Best-effort wallet ownership validation: calls the MCP server to check
-            // whether the wallet belongs to the authenticated user's strategies.
-            // If the MCP call fails (network issue, bad apiKey, server down), we warn
-            // and allow the install to proceed rather than blocking the user.
-            if (wallet) {
-                try {
-                    const client = mcpTransport
-                        ? new SenpiClient(mcpTransport)
-                        : new SenpiClient({ apiKey });
-                    if (!mcpTransport)
-                        await client.connect();
+            if (walletKey)
+                installsInFlight.set(walletKey, { runtimeId: resolvedId, startedAtMs: Date.now() });
+            try {
+                // Best-effort wallet ownership validation: calls the MCP server to check
+                // whether the wallet belongs to the authenticated user's strategies.
+                // If the MCP call fails (network issue, bad apiKey, server down), we warn
+                // and allow the install to proceed rather than blocking the user.
+                if (wallet) {
                     try {
-                        const strategies = await client.listStrategies({ strategyAddresses: [wallet] });
-                        const match = strategies.find((s) => s.strategyWalletAddress.toLowerCase() === wallet.toLowerCase());
-                        if (!match) {
-                            pluginLogger.info("[senpi-runtime] Wallet validation failed: not owned", { wallet });
-                            // `return` triggers the inner `finally` (disconnect) before exiting.
-                            return { ok: false, error: toError(`Strategy wallet "${wallet}" (YAML field: strategy.wallet) was not found in your Senpi account's strategies. ` +
-                                    `Check the address for typos. ` +
-                                    `To list all your strategies and their wallet addresses, call the MCP tool: strategy_list (no arguments needed). ` +
-                                    `Each result includes "strategyWalletAddress" — use that value as strategy.wallet in your YAML.`) };
+                        const client = mcpTransport
+                            ? new SenpiClient(mcpTransport)
+                            : new SenpiClient({ apiKey });
+                        if (!mcpTransport)
+                            await client.connect();
+                        try {
+                            const strategies = await client.listStrategies({ strategyAddresses: [wallet] });
+                            const match = strategies.find((s) => s.strategyWalletAddress.toLowerCase() === wallet.toLowerCase());
+                            if (!match) {
+                                pluginLogger.info("[senpi-runtime] Wallet validation failed: not owned", { wallet });
+                                // `return` triggers the inner `finally` (disconnect) before exiting.
+                                return { ok: false, error: toError(`Strategy wallet "${wallet}" (YAML field: strategy.wallet) was not found in your Senpi account's strategies. ` +
+                                        `Check the address for typos. ` +
+                                        `To list all your strategies and their wallet addresses, call the MCP tool: strategy_list (no arguments needed). ` +
+                                        `Each result includes "strategyWalletAddress" — use that value as strategy.wallet in your YAML.`) };
+                            }
+                            if (match.status !== "ACTIVE") {
+                                pluginLogger.info("[senpi-runtime] Wallet validation failed: strategy not active", { wallet, status: match.status, strategyId: match.id });
+                                return { ok: false, error: toError(
+                                    // H7/D-10: the status vocabulary lives in one module, shared with deploy's
+                                    // reconcile. This gate's private copy was already missing TERMINATED and
+                                    // CLOSING_DONE, so a gone strategy fell to the generic "only ACTIVE" hint.
+                                    `Strategy wallet "${wallet}" (YAML field: strategy.wallet) has status "${match.status}" — a runtime requires ACTIVE status. ` +
+                                        buildWalletStatusHint(match.status) +
+                                        ` To check the latest status, call the MCP tool: strategy_list.`) };
+                            }
+                            pluginLogger.info("[senpi-runtime] Wallet validation passed", { wallet, strategyId: match.id, status: match.status });
                         }
-                        if (match.status !== "ACTIVE") {
-                            pluginLogger.info("[senpi-runtime] Wallet validation failed: strategy not active", { wallet, status: match.status, strategyId: match.id });
-                            return { ok: false, error: toError(
-                                // H7/D-10: the status vocabulary lives in one module, shared with deploy's
-                                // reconcile. This gate's private copy was already missing TERMINATED and
-                                // CLOSING_DONE, so a gone strategy fell to the generic "only ACTIVE" hint.
-                                `Strategy wallet "${wallet}" (YAML field: strategy.wallet) has status "${match.status}" — a runtime requires ACTIVE status. ` +
-                                    buildWalletStatusHint(match.status) +
-                                    ` To check the latest status, call the MCP tool: strategy_list.`) };
+                        finally {
+                            if (!mcpTransport)
+                                await client.disconnect().catch(() => { });
                         }
-                        pluginLogger.info("[senpi-runtime] Wallet validation passed", { wallet, strategyId: match.id, status: match.status });
                     }
-                    finally {
-                        if (!mcpTransport)
-                            await client.disconnect().catch(() => { });
+                    catch (err) {
+                        // Soft-fail: validation is best-effort. If connect() or listStrategies()
+                        // throws, log a warning and let the install proceed.
+                        const msg = err instanceof Error ? err.message : String(err);
+                        pluginLogger.warn("[senpi-runtime] Could not validate strategy wallet ownership", { wallet, err: msg });
                     }
                 }
-                catch (err) {
-                    // Soft-fail: validation is best-effort. If connect() or listStrategies()
-                    // throws, log a warning and let the install proceed.
-                    const msg = err instanceof Error ? err.message : String(err);
-                    pluginLogger.warn("[senpi-runtime] Could not validate strategy wallet ownership", { wallet, err: msg });
+                const entry = hasPath
+                    ? { id: resolvedId, runtimeYamlPath, schemaVersion: parsedSchemaVersion, wallet }
+                    : {
+                        id: resolvedId,
+                        runtimeYamlContent: runtimeYamlContent,
+                        schemaVersion: parsedSchemaVersion,
+                        wallet,
+                        // Persist the recipe dir so a gateway restart can resolve an
+                        // external scanner's relative `path: ./` (content installs drop it).
+                        ...(runtimeYamlDir ? { runtimeYamlDir } : {}),
+                    };
+                const valid = validateEntry(entry);
+                if (!valid.ok) {
+                    return { ok: false, error: toError(valid.error) };
                 }
-            }
-            const entry = hasPath
-                ? { id: resolvedId, runtimeYamlPath, schemaVersion: parsedSchemaVersion, wallet }
-                : {
-                    id: resolvedId,
-                    runtimeYamlContent: runtimeYamlContent,
-                    schemaVersion: parsedSchemaVersion,
-                    wallet,
-                    // Persist the recipe dir so a gateway restart can resolve an
-                    // external scanner's relative `path: ./` (content installs drop it).
-                    ...(runtimeYamlDir ? { runtimeYamlDir } : {}),
-                };
-            const valid = validateEntry(entry);
-            if (!valid.ok) {
-                return { ok: false, error: toError(valid.error) };
-            }
-            registry.runtimes.push(entry);
-            await writeRegistry(baseStateDir, registry);
-            /**
-             * The unwired verdict for THIS install, tracked locally rather than read back out of
-             * `unwiredRuntimes`, so the result reports what this call did and never a leftover verdict
-             * from an earlier runtime that happened to share the id. Set at each of the three sites that
-             * leave the runtime without live entry scanners; cleared by the wire-success path.
-             */
-            let unwiredPhase;
-            try {
-                const scannerProviders = await createScannerProvidersForRun({
-                    mcpTransport,
-                    apiKey,
-                });
-                const entryStateDir = buildRuntimeStateDir(baseStateDir, resolvedId, wallet);
-                const handle = await run(pathOrContent, {
-                    fromPath: hasPath,
-                    stateDir: entryStateDir,
-                    mcpTransport,
-                    apiKey,
-                    scannerProviders,
-                    runtimeId: resolvedId,
-                });
-                runtimeHandles.set(resolvedId, handle);
-                if (parsedConfig)
-                    noteTelemetryRuntimeConfig(resolvedId, parsedConfig);
-                else
-                    noteTelemetryRuntime(resolvedId, wallet);
-                // Registry create fact — distinct from the runtime.started boot transition (which also fires
-                // on a transient restart). Emitted inside emitEvent's guard so telemetry never fails the install.
-                emitEvent(apiLogger, () => buildRuntimeCreatedEvent({ runtimeId: resolvedId, address: wallet, recipeName: runtimeName }));
-                // ── hot-install supervised scanner wire ───────────────────────────────
-                // Live-install path: used when a runtime is registered after boot via
-                // senpi.installRuntime, while the API is already listening — the
-                // counterpart to the boot-time `launcher` above. A runtime takes exactly
-                // one path: boot-present → `launcher` (deferred start); installed live →
-                // `hotLauncher` (immediate start). The two are mutually exclusive because
-                // installRuntime rejects any id/wallet already in the registry before
-                // wiring (the hasId guard), so a boot-present runtime never re-enters here.
-                // The API is already listening at this point, so we wire and start
-                // immediately (no deferred start needed). Any failure is swallowed so
-                // the install itself is not rolled back — the runtime is already up.
-                // Gate on the same API-disabled flag as the boot path: when the HTTP API
-                // is off (a test-only seam), the /signals route is never mounted, so
-                // starting scanners would only spawn children that POST to a closed port.
-                if (parsedConfig &&
-                    sharedIntakeContext &&
-                    process.env.SENPI_RUNTIME_API_DISABLED !== "true") {
-                    try {
-                        const apiConfig = loadApiConfig(api.pluginConfig);
-                        const scaffoldPackageDir = fileURLToPath(new URL("./scanners/external", import.meta.url));
-                        const entryStateDir = buildRuntimeStateDir(baseStateDir, resolvedId, wallet);
-                        const hotLauncher = wireRuntime({
-                            runtimeConfig: parsedConfig,
-                            recipeDir: hasPath ? dirname(pathOrContent) : runtimeYamlDir,
-                            runtimeId: resolvedId,
-                            wallet,
-                            sharedCtx: sharedIntakeContext,
-                            runtimeHandles,
-                            intakeUrl: intakeUrlFor(apiConfig.host, apiConfig.port),
-                            scaffoldPackageDir,
-                            runtimeStateDir: entryStateDir,
-                            logger: apiLogger,
-                        });
-                        if (hotLauncher) {
-                            try {
-                                await hotLauncher.start();
-                                launchers.set(resolvedId, hotLauncher);
-                                unwiredRuntimes.delete(resolvedId);
-                                unwiredPhase = undefined;
-                                runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
-                                    unwired: false,
-                                    rows: hotLauncher.describeSupervision(),
-                                }));
-                            }
-                            catch (startErr) {
-                                await hotLauncher.stop().catch(() => { });
-                                unwiredRuntimes.set(resolvedId, "install_launch");
-                                unwiredPhase = "install_launch";
-                                runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
-                                    unwired: true,
-                                    unwiredPhase: "install_launch",
-                                    rows: [],
-                                }));
-                                eventScannersUnwired("install_launch", resolvedId, wallet, appendCause("[senpi-runtime] hot-install supervised scanner launch failed — runtime running without it", startErr), startErr);
+                registry.runtimes.push(entry);
+                await writeRegistry(baseStateDir, registry);
+                /**
+                 * The unwired verdict for THIS install, tracked locally rather than read back out of
+                 * `unwiredRuntimes`, so the result reports what this call did and never a leftover verdict
+                 * from an earlier runtime that happened to share the id. Set at each of the three sites that
+                 * leave the runtime without live entry scanners; cleared by the wire-success path.
+                 */
+                let unwiredPhase;
+                try {
+                    const scannerProviders = await createScannerProvidersForRun({
+                        mcpTransport,
+                        apiKey,
+                    });
+                    const entryStateDir = buildRuntimeStateDir(baseStateDir, resolvedId, wallet);
+                    const handle = await run(pathOrContent, {
+                        fromPath: hasPath,
+                        stateDir: entryStateDir,
+                        mcpTransport,
+                        apiKey,
+                        scannerProviders,
+                        runtimeId: resolvedId,
+                    });
+                    runtimeHandles.set(resolvedId, handle);
+                    if (parsedConfig)
+                        noteTelemetryRuntimeConfig(resolvedId, parsedConfig);
+                    else
+                        noteTelemetryRuntime(resolvedId, wallet);
+                    // Registry create fact — distinct from the runtime.started boot transition (which also fires
+                    // on a transient restart). Emitted inside emitEvent's guard so telemetry never fails the install.
+                    emitEvent(apiLogger, () => buildRuntimeCreatedEvent({ runtimeId: resolvedId, address: wallet, recipeName: runtimeName }));
+                    // ── hot-install supervised scanner wire ───────────────────────────────
+                    // Live-install path: used when a runtime is registered after boot via
+                    // senpi.installRuntime, while the API is already listening — the
+                    // counterpart to the boot-time `launcher` above. A runtime takes exactly
+                    // one path: boot-present → `launcher` (deferred start); installed live →
+                    // `hotLauncher` (immediate start). The two are mutually exclusive because
+                    // installRuntime rejects any id/wallet already in the registry before
+                    // wiring (the hasId guard), so a boot-present runtime never re-enters here.
+                    // The API is already listening at this point, so we wire and start
+                    // immediately (no deferred start needed). Any failure is swallowed so
+                    // the install itself is not rolled back — the runtime is already up.
+                    // Gate on the same API-disabled flag as the boot path: when the HTTP API
+                    // is off (a test-only seam), the /signals route is never mounted, so
+                    // starting scanners would only spawn children that POST to a closed port.
+                    if (parsedConfig &&
+                        sharedIntakeContext &&
+                        process.env.SENPI_RUNTIME_API_DISABLED !== "true") {
+                        try {
+                            const apiConfig = loadApiConfig(api.pluginConfig);
+                            const scaffoldPackageDir = fileURLToPath(new URL("./scanners/external", import.meta.url));
+                            const entryStateDir = buildRuntimeStateDir(baseStateDir, resolvedId, wallet);
+                            const hotLauncher = wireRuntime({
+                                runtimeConfig: parsedConfig,
+                                recipeDir: hasPath ? dirname(pathOrContent) : runtimeYamlDir,
+                                runtimeId: resolvedId,
+                                wallet,
+                                sharedCtx: sharedIntakeContext,
+                                runtimeHandles,
+                                intakeUrl: intakeUrlFor(apiConfig.host, apiConfig.port),
+                                scaffoldPackageDir,
+                                runtimeStateDir: entryStateDir,
+                                logger: apiLogger,
+                            });
+                            if (hotLauncher) {
+                                try {
+                                    await hotLauncher.start();
+                                    launchers.set(resolvedId, hotLauncher);
+                                    unwiredRuntimes.delete(resolvedId);
+                                    unwiredPhase = undefined;
+                                    runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
+                                        unwired: false,
+                                        rows: hotLauncher.describeSupervision(),
+                                    }));
+                                }
+                                catch (startErr) {
+                                    await hotLauncher.stop().catch(() => { });
+                                    unwiredRuntimes.set(resolvedId, "install_launch");
+                                    unwiredPhase = "install_launch";
+                                    runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
+                                        unwired: true,
+                                        unwiredPhase: "install_launch",
+                                        rows: [],
+                                    }));
+                                    eventScannersUnwired("install_launch", resolvedId, wallet, appendCause("[senpi-runtime] hot-install supervised scanner launch failed — runtime running without it", startErr), startErr);
+                                }
                             }
                         }
+                        catch (wireErr) {
+                            // Wire failure must NOT fail the install — the runtime is already up. It IS reported
+                            // across the result boundary (payload.unwired) so a funding caller can refuse it.
+                            unwiredRuntimes.set(resolvedId, "install_wire");
+                            unwiredPhase = "install_wire";
+                            runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
+                                unwired: true,
+                                unwiredPhase: "install_wire",
+                                rows: [],
+                            }));
+                            eventScannersUnwired("install_wire", resolvedId, wallet, appendCause("[senpi-runtime] hot-install wiring failed — runtime running without supervised scanners", wireErr), wireErr);
+                        }
                     }
-                    catch (wireErr) {
-                        // Wire failure must NOT fail the install — the runtime is already up. It IS reported
-                        // across the result boundary (payload.unwired) so a funding caller can refuse it.
-                        unwiredRuntimes.set(resolvedId, "install_wire");
-                        unwiredPhase = "install_wire";
+                    else if (parsedConfig && !sharedIntakeContext && selectScanners(parsedConfig).length > 0) {
+                        // Supervised intake is DISABLED for the whole box (corrupt acceptance record).
+                        // The wire block above is skipped, so this hot-installed runtime declares
+                        // external scanners but has NO live entry scanners. Record that fail-closed
+                        // state (state only, no new event) so listRuntimes/health don't lie.
+                        unwiredRuntimes.set(resolvedId, "no_intake");
+                        unwiredPhase = "no_intake";
                         runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
                             unwired: true,
-                            unwiredPhase: "install_wire",
+                            unwiredPhase: "no_intake",
                             rows: [],
                         }));
-                        eventScannersUnwired("install_wire", resolvedId, wallet, appendCause("[senpi-runtime] hot-install wiring failed — runtime running without supervised scanners", wireErr), wireErr);
                     }
+                    // ──────────────────────────────────────────────────────────────────────
+                    return {
+                        ok: true,
+                        payload: {
+                            id: resolvedId,
+                            name: runtimeName,
+                            wallet,
+                            ...(unwiredPhase ? { unwired: unwiredPhase } : {}),
+                        },
+                    };
                 }
-                else if (parsedConfig && !sharedIntakeContext && selectScanners(parsedConfig).length > 0) {
-                    // Supervised intake is DISABLED for the whole box (corrupt acceptance record).
-                    // The wire block above is skipped, so this hot-installed runtime declares
-                    // external scanners but has NO live entry scanners. Record that fail-closed
-                    // state (state only, no new event) so listRuntimes/health don't lie.
-                    unwiredRuntimes.set(resolvedId, "no_intake");
-                    unwiredPhase = "no_intake";
-                    runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
-                        unwired: true,
-                        unwiredPhase: "no_intake",
-                        rows: [],
-                    }));
+                catch (err) {
+                    const next = registry.runtimes.filter((e) => e.id !== resolvedId);
+                    await writeRegistry(baseStateDir, { ...registry, runtimes: next });
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { ok: false, error: toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`) };
                 }
-                // ──────────────────────────────────────────────────────────────────────
-                return {
-                    ok: true,
-                    payload: {
-                        id: resolvedId,
-                        name: runtimeName,
-                        wallet,
-                        ...(unwiredPhase ? { unwired: unwiredPhase } : {}),
-                    },
-                };
             }
-            catch (err) {
-                const next = registry.runtimes.filter((e) => e.id !== resolvedId);
-                await writeRegistry(baseStateDir, { ...registry, runtimes: next });
-                const msg = err instanceof Error ? err.message : String(err);
-                return { ok: false, error: toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`) };
+            finally {
+                if (walletKey)
+                    installsInFlight.delete(walletKey);
             }
         }
         /** Gateway respond accepts (ok, payload?, error?) with error as { code, message }; plugin SDK types may omit the third arg. */
@@ -1466,6 +1519,7 @@ const senpiRuntimePlugin = {
             // it "running — NO ENTRY SCANNERS"), and reporting `install: skipped` over it would be the
             // same clean line over a runtime that cannot tick.
             runtimeIsLive: async (id) => runtimeHandles.has(id) && !unwiredRuntimes.has(id),
+            installPendingOnWallet: async (wallet) => installsInFlight.has(wallet.trim().toLowerCase()),
             logger: { info: (line) => api.logger.info(`[senpi-runtime] ${line}`) },
         });
         /**