@senpi/runtime 3.0.59 → 3.0.63

package/dist/index.js

@@ -14,6 +14,9 @@
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 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 { AuditQueryError } from "./runtime/audit-query.types.js";
 import { buildRuntimeStateDir, archiveStateDir } from "./runtime/state-layout.js";
 import { registerSenpiCli } from "./cli/senpi-commands.js";
@@ -35,8 +38,6 @@ import { resolvePackageName } from "./runtime/auto-update/resolve-package-name.j
 import { runOpenClawPluginsUpdate } from "./runtime/auto-update/run-update-command.js";
 import { registerSpanHooks } from "./telemetry/spans/index.js";
 import { registerSessionContextSeedHook } from "./prompt/session-context-seed-hook.js";
-import { createManagedWalletGuard } from "./runtime/managed-wallet-guard.js";
-import { createProtectionGate, createProtectionNudge, createProtectionSummaryCapture, } from "./runtime/protection-nudge.js";
 import { initDefaultPiiRedactor } from "./telemetry/spans/redact-pii.js";
 import { initOtelSdk, shutdownOtelSdk } from "./telemetry/otel-sdk.js";
 import { getLogLevel, getLogLevelSource, parseLogLevel, setLogLevel, } from "./utils/logger.js";
@@ -245,49 +246,6 @@ const senpiRuntimePlugin = {
             });
         }
         const runtimeHandles = new Map();
-        // Position-tool guards on ONE before_tool_call registration, composed in
-        // order. The managed-wallet hard block runs first: it vetoes agent-issued
-        // create_position calls into wallets an installed runtime manages (checking
-        // live handles — wallet parsed from YAML, covering registry entries with
-        // missing/stale wallet fields — then the registry read from the resolved
-        // `baseStateDir`, not the raw openclaw stateDir). A wallet-guard block
-        // short-circuits; only if it allows does the protection gate run, which on
-        // a manual (non-runtime) wallet vetoes an unprotected create_position and a
-        // stop-loss-cancel edit unless the agent opted out with protection:"none".
-        // The gate stashes each allowed create_position's protection summary into a
-        // shared capture that the tool_result_persist nudge reads back — the nudge
-        // event carries no params. `on`'s typing is void-only, so the
-        // veto/message-returning handlers are cast at this boundary.
-        try {
-            const managedWalletGuard = createManagedWalletGuard({
-                resolveStateDir: () => baseStateDir,
-                getLiveWallets: () => Array.from(runtimeHandles, ([id, handle]) => ({ id, wallet: handle.wallet })),
-                logger: createLogger("[senpi-core][managed-wallet-guard]"),
-            });
-            const protectionCapture = createProtectionSummaryCapture();
-            const protectionGate = createProtectionGate({
-                logger: createLogger("[senpi-core][protection-gate]"),
-                capture: protectionCapture,
-            });
-            const beforeToolCall = async (event) => {
-                const walletVerdict = await managedWalletGuard(event);
-                if (walletVerdict)
-                    return walletVerdict;
-                return protectionGate(event);
-            };
-            api.on("before_tool_call", beforeToolCall);
-            const protectionNudge = createProtectionNudge({
-                logger: createLogger("[senpi-core][protection-nudge]"),
-                capture: protectionCapture,
-            });
-            api.on("tool_result_persist", protectionNudge);
-            pluginLogger.info("[senpi-runtime] position-tool guards registered (before_tool_call: managed-wallet + protection gate; tool_result_persist: protection nudge)");
-        }
-        catch (err) {
-            pluginLogger.warn("[senpi-runtime] failed to register position-tool guards", {
-                err: err instanceof Error ? err.message : String(err),
-            });
-        }
         let apiHandle;
         // Supervised scanner state — module-scoped so stop() can reach them.
         // Created eagerly at register() time (not deferred to start()) so that
@@ -427,9 +385,23 @@ const senpiRuntimePlugin = {
                 restartPrefixes: [`plugins.entries.${api.id}.config.autoUpdate.lastRestartTrigger`],
             });
         }
+        // ── senpi deploy (detached job) ───────────────────────────────────────────
+        // Constructed here, ahead of registerService, because the service `start` hook below runs its
+        // boot scan: declaring it after would leave that reference in the temporal dead zone for any
+        // future refactor that starts the service earlier. The rest of the deploy wiring lives in
+        // src/deploy/register.ts behind an explicit context; this closure contributes collaborators only.
+        const deployController = new DeployJobController({
+            deploysDir: join(baseStateDir, "deploys"),
+            now: () => Date.now(),
+            log: (line) => api.logger.info(`[senpi-runtime] ${line}`),
+        });
         api.registerService({
             id: "senpi-runtime",
             async start() {
+                // Deploy-journal janitor: stamp anything a restart left unterminated as `interrupted`.
+                // It never re-enters a deploy state machine — discovery is pull-based via
+                // `senpi deploy status`.
+                await deployController.scanOnBoot();
                 await autoUpdateCoordinator.start();
                 // SENPI_RUNTIME_API_DISABLED=true also disables the skills coordinator.
                 // Skills bootstrap performs a real `git clone` synchronously during
@@ -741,13 +713,15 @@ const senpiRuntimePlugin = {
             pluginLogger.info("[senpi-runtime] CLI registrar callback invoked — attaching senpi subcommands to program");
             registerSenpiCli(ctx.program);
         }, { commands: ["senpi"] });
-        /** Gateway respond accepts (ok, payload?, error?) with error as { code, message }; plugin SDK types may omit the third arg. */
-        api.registerGatewayMethod("senpi.installRuntime", async (ctx) => {
-            const { params } = ctx;
-            const respond = ctx.respond;
+        /**
+         * The whole `senpi.installRuntime` behaviour, callable without a gateway ctx so
+         * `senpi deploy` installs through the SAME gates (wallet ownership, one-runtime-per-wallet,
+         * scanner-path resolution) instead of a parallel path that could drift.
+         */
+        async function installRuntimeCore(params) {
             const toError = (message) => ({ code: "INVALID_REQUEST", message });
             const toUnavailable = (message) => ({ code: "UNAVAILABLE", message });
-            const { readRegistry, writeRegistry, validateEntry, hasId, deriveRuntimeId, sanitizeId } = await import("./runtime/strategy-registry.js");
+            const { readRegistry, writeRegistry, validateEntry, hasId, findByWallet, deriveRuntimeId, sanitizeId } = await import("./runtime/strategy-registry.js");
             const id = typeof params?.id === "string" ? params.id : undefined;
             const runtimeYamlPath = typeof params?.runtimeYamlPath === "string" ? params.runtimeYamlPath : undefined;
             const runtimeYamlContent = typeof params?.runtimeYamlContent === "string" ? params.runtimeYamlContent : undefined;
@@ -760,12 +734,10 @@ const senpiRuntimePlugin = {
             const hasPath = runtimeYamlPath !== undefined && runtimeYamlPath.length > 0;
             const hasContent = runtimeYamlContent !== undefined;
             if (!hasPath && !hasContent) {
-                respond(false, undefined, toError("Please provide your runtime YAML: use the create command with --path <file> or --content \"<yaml text>\"."));
-                return;
+                return { ok: false, error: toError("Please provide your runtime YAML: use the create command with --path <file> or --content \"<yaml text>\".") };
             }
             if (hasPath && hasContent) {
-                respond(false, undefined, toError("Please provide either a file path (--path) or YAML content (--content), not both."));
-                return;
+                return { ok: false, error: toError("Please provide either a file path (--path) or YAML content (--content), not both.") };
             }
             const pathOrContent = runtimeYamlPath ?? runtimeYamlContent;
             // Parse YAML first to extract name, version, and wallet for ID derivation.
@@ -784,10 +756,15 @@ const senpiRuntimePlugin = {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                respond(false, undefined, toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`));
-                return;
+                return { ok: false, error: toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`) };
             }
             // ── install gate ────────────────────────────────────────────────────
+            // The cwd-resolution trap (M226926 inline -c, M279357 --path) is closed by this gate's
+            // E_VALIDATE_UNRESOLVABLE_SCANNER_PATH: a relative scanner path with no source dir would
+            // silently resolve against the process cwd (intake-mount.ts selectScanners baseDir=undefined)
+            // and mount a dead scanner. A second check for the same condition used to sit immediately
+            // above this one; two gates on one boundary meant the message a caller saw depended on which
+            // ran first, so it was folded into the finding's own `fix`.
             // The schema accepts recipes that cannot trade: an entry action with no
             // reachable margin source declines every signal it will ever see, one with
             // no guardrails trades with no daily-loss ceiling, and a declared scanner
@@ -797,9 +774,12 @@ const senpiRuntimePlugin = {
             // running runtime is untouched. Deliberately NOT done at boot: that loop
             // stops every started runtime on a throw, so refusing there would take the
             // box down over one bad recipe.
-            // Decide inside the guard, act outside it. A `return` within the `try`
-            // would let a throw from `respond` be swallowed by the catch below and the
-            // install proceed after we had decided to refuse it.
+            // Decide inside the guard, act outside it. The catch below exists to keep a
+            // defect in the CHECKS from failing an install, and it cannot tell one of
+            // those from a fault raised while acting on a refusal it already decided.
+            // Returning after the guard keeps the two apart, so no future statement
+            // added on the refusal path can be swallowed into "the gate could not run"
+            // and let the install proceed.
             let gateRefusal;
             try {
                 const { collectRecipeFindings } = await import("./validate/recipe.js");
@@ -829,6 +809,13 @@ const senpiRuntimePlugin = {
                 // themselves — log it and let the install proceed rather than blocking a
                 // good recipe on our own bug.
                 //
+                // This side fails OPEN and `runDeploy`'s pre-money install gate
+                // (deploy/orchestrator.ts, the `deploy.install_gate` span) fails CLOSED on
+                // the SAME fault, deliberately: refusing a good recipe HERE blocks a
+                // working install, while refusing a deploy costs only a re-run, before any
+                // money has moved. Two boundaries, one predicate — neither branch may be
+                // flipped on its own.
+                //
                 // But say so on the ledger, not only in a log line. Proceeding ungated is
                 // silent by construction: the install succeeds, nothing looks wrong, and
                 // protection has reverted to what it was before the gate existed — for
@@ -845,25 +832,67 @@ const senpiRuntimePlugin = {
                 pluginLogger.warn(appendCause("[senpi-runtime] install gate could not run — proceeding without it", gateErr));
             }
             if (gateRefusal !== undefined) {
-                respond(false, undefined, toError(gateRefusal));
-                return;
+                return { ok: false, error: toError(gateRefusal) };
             }
             const registry = await readRegistry(baseStateDir);
             const resolvedId = id && id.length > 0
                 ? (sanitizeId(id) || "runtime")
                 : deriveRuntimeId(runtimeName, wallet);
             if (hasId(registry, resolvedId)) {
-                respond(false, undefined, toError(`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}`));
-                return;
-            }
-            // Enforce one running runtime per wallet address
+                return { ok: false, error: toError(`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}`) };
+            }
+            /**
+             * One runtime per wallet address — asked of PERSISTED state, not only of this process.
+             *
+             * Two engines on one wallet is not a tidiness problem: each keeps its own high-water state,
+             * so they disagree about what is protected and stop each other's positions out on different
+             * floors, against one margin account.
+             *
+             * The live-handle half alone could not carry that guarantee, because it is blind in exactly
+             * the window where it is needed. A runtime that is INSTALLED but not running right now — its
+             * boot failed, or the box came up and it never started — has a registry row and no handle,
+             * so the loop below sees nothing and lets a second row land on the same wallet. Nothing
+             * reconciles the two afterwards: the registry has no uniqueness on `wallet`, and the boot
+             * loop starts every row it can resolve. The restart that fixes the first runtime is the one
+             * that brings up both.
+             *
+             * Both halves are kept because they answer different questions and the answers differ:
+             * a live handle proves a runtime is trading NOW (and names the stop-it-first step), while a
+             * registry row proves one is installed and will be started at the next boot. Case-folded on
+             * 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) {
-                for (const [existingId, existingHandle] of runtimeHandles) {
-                    if (existingHandle.wallet === wallet) {
-                        respond(false, undefined, toError(`A runtime for wallet "${wallet}" is already running (runtime "${existingId}"). ` +
-                            `Stop it first: openclaw senpi runtime delete --id ${existingId}`));
-                        return;
+                const walletKey = wallet.toLowerCase();
+                const liveId = [...runtimeHandles].find(([, handle]) => (handle.wallet ?? "").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.
+                const holderId = liveId ?? findByWallet(registry, wallet)?.id;
+                if (holderId !== undefined) {
+                    // "running" vs "installed and not running" is asked of THAT id — the same predicate
+                    // `senpi.listRuntimes` renders "stopped" from — rather than inferred from which of the
+                    // two reads found it. They agree in practice; the refusal has to agree with the surface
+                    // it sends the reader to, because that is where the reader checks it.
+                    if (runtimeHandles.has(holderId)) {
+                        return { ok: false, error: toError(`A runtime for wallet "${wallet}" is already running (runtime "${holderId}"). ` +
+                                `Stop it first: openclaw senpi runtime delete --id ${holderId}`) };
                     }
+                    return { ok: false, error: toError(
+                        // What is CLAIMED here is only what the two reads above prove: a registry row exists,
+                        // and this gateway has no live handle under its id. Not "it crashed", not "it is
+                        // broken" — neither was read, and the boot loop will not necessarily manage to start
+                        // it either (a boot that already failed once fails again), so the claim is that the
+                        // next restart TRIES. The next step leads with the read, because the operator has to
+                        // find out which of the two runtimes they actually want before removing either, and
+                        // deleting the wrong one leaves a funded wallet watched by nothing.
+                        `A runtime for wallet "${wallet}" is already installed (runtime "${holderId}"). ` +
+                            `It is not running in this gateway right now, but it is in the registry, so the next ` +
+                            `restart will try to start it — installing a second runtime on the same wallet would ` +
+                            `put two exit engines on one wallet's margin, each tracking its own high-water floor. ` +
+                            `Nothing was installed. See what that runtime is before removing anything: ` +
+                            `openclaw senpi runtime list. If it is genuinely unwanted, remove it first: ` +
+                            `openclaw senpi runtime delete --id ${holderId}`) };
                 }
             }
             // Best-effort wallet ownership validation: calls the MCP server to check
@@ -882,48 +911,21 @@ const senpiRuntimePlugin = {
                         const match = strategies.find((s) => s.strategyWalletAddress.toLowerCase() === wallet.toLowerCase());
                         if (!match) {
                             pluginLogger.info("[senpi-runtime] Wallet validation failed: not owned", { wallet });
-                            respond(false, undefined, 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.`));
                             // `return` triggers the inner `finally` (disconnect) before exiting.
-                            return;
+                            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 });
-                            respond(false, undefined, toError((() => {
-                                const initializingStatuses = new Set([
-                                    "SET_REFERRER_CODE", "SET_BUILDER_FEE", "SUBSCRIBE_TRADER",
-                                    "CREATE_WALLET", "FUND_WALLET", "INITIALIZE_POSITIONS",
-                                ]);
-                                const terminalStatuses = new Set([
-                                    "CLOSED", "FAILED", "CLOSING_POSITIONS", "CLOSE_STRATEGY",
-                                    "UNSUBSCRIBE_TRADER", "FUND_SOURCE_WALLET", "INACTIVE",
-                                ]);
-                                let hint;
-                                if (initializingStatuses.has(match.status)) {
-                                    hint =
-                                        `The strategy is still initializing (${match.status}). ` +
-                                            `It will reach ACTIVE automatically — wait a few minutes, then retry. ` +
-                                            `Initialization order: CREATE_WALLET → FUND_WALLET → INITIALIZE_POSITIONS → ACTIVE.`;
-                                }
-                                else if (match.status === "PAUSED") {
-                                    hint =
-                                        `The strategy is paused and cannot be used to create a runtime  — please create a new strategy instead.`;
-                                }
-                                else if (terminalStatuses.has(match.status)) {
-                                    hint =
-                                        `The strategy is closing or already closed (${match.status}). ` +
-                                            `A runtime cannot be created for a closed strategy — please create a new strategy instead.`;
-                                }
-                                else {
-                                    hint = `Only ACTIVE strategies can run a runtime.`;
-                                }
-                                return (`Strategy wallet "${wallet}" (YAML field: strategy.wallet) has status "${match.status}" — a runtime requires ACTIVE status. ` +
-                                    hint +
-                                    ` To check the latest status, call the MCP tool: strategy_list.`);
-                            })()));
-                            return;
+                            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 });
                     }
@@ -952,11 +954,17 @@ const senpiRuntimePlugin = {
                 };
             const valid = validateEntry(entry);
             if (!valid.ok) {
-                respond(false, undefined, toError(valid.error));
-                return;
+                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,
@@ -1013,6 +1021,7 @@ const senpiRuntimePlugin = {
                                 await hotLauncher.start();
                                 launchers.set(resolvedId, hotLauncher);
                                 unwiredRuntimes.delete(resolvedId);
+                                unwiredPhase = undefined;
                                 runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
                                     unwired: false,
                                     rows: hotLauncher.describeSupervision(),
@@ -1021,6 +1030,7 @@ const senpiRuntimePlugin = {
                             catch (startErr) {
                                 await hotLauncher.stop().catch(() => { });
                                 unwiredRuntimes.set(resolvedId, "install_launch");
+                                unwiredPhase = "install_launch";
                                 runtimeHandles.get(resolvedId)?.attachSupervisionSource(() => ({
                                     unwired: true,
                                     unwiredPhase: "install_launch",
@@ -1031,8 +1041,10 @@ const senpiRuntimePlugin = {
                         }
                     }
                     catch (wireErr) {
-                        // Wire failure must NOT fail the install — the runtime is already up.
+                        // 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",
@@ -1047,6 +1059,7 @@ const senpiRuntimePlugin = {
                     // 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",
@@ -1054,14 +1067,31 @@ const senpiRuntimePlugin = {
                     }));
                 }
                 // ──────────────────────────────────────────────────────────────────────
-                respond(true, { id: resolvedId, name: runtimeName, wallet });
+                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);
-                respond(false, undefined, toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`));
+                return { ok: false, error: toUnavailable(`Could not start the runtime. This is usually due to invalid or incomplete YAML.\n\n${msg}`) };
             }
+        }
+        /** Gateway respond accepts (ok, payload?, error?) with error as { code, message }; plugin SDK types may omit the third arg. */
+        api.registerGatewayMethod("senpi.installRuntime", async (ctx) => {
+            const respond = ctx.respond;
+            const result = await installRuntimeCore(ctx.params);
+            if (result.ok)
+                respond(true, result.payload);
+            else
+                respond(false, undefined, result.error);
         }, { scope: "operator.write" });
         api.registerGatewayMethod("senpi.listRuntimes", async (ctx) => {
             const respond = ctx.respond;
@@ -1088,9 +1118,12 @@ const senpiRuntimePlugin = {
             });
             respond(true, { runtimes });
         }, { scope: "operator.read" });
-        api.registerGatewayMethod("senpi.deleteRuntime", async (ctx) => {
-            const { params } = ctx;
-            const respond = ctx.respond;
+        /**
+         * The whole `senpi.deleteRuntime` behaviour, callable without a gateway ctx. `senpi deploy`
+         * reuses it to retire a runtime bound to an old wallet, so archival, launcher teardown and the
+         * unwired-verdict cleanup all happen exactly once, here.
+         */
+        async function deleteRuntimeCore(params) {
             const { readRegistry, writeRegistry } = await import("./runtime/strategy-registry.js");
             const registry = await readRegistry(baseStateDir);
             let targetId = typeof params?.id === "string" ? params.id : undefined;
@@ -1099,29 +1132,26 @@ const senpiRuntimePlugin = {
             if (!targetId && targetAddress) {
                 const entry = registry.runtimes.find((e) => e.wallet === targetAddress);
                 if (!entry) {
-                    respond(false, undefined, {
-                        code: "NOT_FOUND",
-                        message: `No runtime found for wallet address "${targetAddress}".`,
-                    });
-                    return;
+                    return { ok: false, error: {
+                            code: "NOT_FOUND",
+                            message: `No runtime found for wallet address "${targetAddress}".`,
+                        } };
                 }
                 targetId = entry.id;
             }
             if (!targetId) {
-                respond(false, undefined, {
-                    code: "INVALID_REQUEST",
-                    message: "Please provide the runtime id or wallet address. Example: openclaw senpi runtime delete --id my-runtime",
-                });
-                return;
+                return { ok: false, error: {
+                        code: "INVALID_REQUEST",
+                        message: "Please provide the runtime id or wallet address. Example: openclaw senpi runtime delete --id my-runtime",
+                    } };
             }
             const deletedEntry = registry.runtimes.find((e) => e.id === targetId);
             const handle = runtimeHandles.get(targetId);
             if (!deletedEntry && !handle) {
-                respond(false, undefined, {
-                    code: "NOT_FOUND",
-                    message: `No runtime found with id "${targetId}".`,
-                });
-                return;
+                return { ok: false, error: {
+                        code: "NOT_FOUND",
+                        message: `No runtime found with id "${targetId}".`,
+                    } };
             }
             if (handle) {
                 await handle.teardownDslForRuntimeDeletion();
@@ -1166,8 +1196,90 @@ const senpiRuntimePlugin = {
                 address: deletedEntry?.wallet,
                 hadLiveHandle: Boolean(handle),
             }));
-            respond(true, { id: targetId });
+            return { ok: true, payload: { id: targetId } };
+        }
+        api.registerGatewayMethod("senpi.deleteRuntime", async (ctx) => {
+            const respond = ctx.respond;
+            const result = await deleteRuntimeCore(ctx.params);
+            if (result.ok)
+                respond(true, result.payload);
+            else
+                respond(false, undefined, result.error);
         }, { scope: "operator.write" });
+        /** One connected SenpiClient per job; always disconnected, even on failure. */
+        async function withSenpiClient(fn) {
+            const client = mcpTransport ? new SenpiClient(mcpTransport) : new SenpiClient({ apiKey });
+            if (!mcpTransport)
+                await client.connect();
+            try {
+                return await fn(client);
+            }
+            finally {
+                if (!mcpTransport)
+                    await client.disconnect().catch(() => { });
+            }
+        }
+        async function findRegistryEntryByWallet(wallet) {
+            const { readRegistry, findByWallet } = await import("./runtime/strategy-registry.js");
+            const entry = findByWallet(await readRegistry(baseStateDir), wallet);
+            return entry ? { id: entry.id, wallet: entry.wallet } : undefined;
+        }
+        async function findRegistryEntryById(id) {
+            const { readRegistry } = await import("./runtime/strategy-registry.js");
+            const entry = (await readRegistry(baseStateDir)).runtimes.find((e) => e.id === id);
+            return entry ? { id: entry.id, wallet: entry.wallet } : undefined;
+        }
+        /** Narrow a live runtime's system state to the scanner columns the deploy report quotes. */
+        async function readScannerRows(runtimeId) {
+            const handle = runtimeHandles.get(runtimeId);
+            if (!handle)
+                return null;
+            try {
+                const state = await handle.getSystemState();
+                const rows = state?.components?.scanners?.state?.scanners;
+                if (!Array.isArray(rows))
+                    return null;
+                return rows.map((row) => ({
+                    scannerId: row.scannerId,
+                    health: row.health,
+                    enabled: row.enabled,
+                    scheduleMode: row.scheduleMode,
+                    lastRunStatus: row.lastRunStatus,
+                    lastRunFinishedAt: row.lastRunFinishedAt,
+                    lastAliveAt: row.lastAliveAt,
+                    nextRunAt: row.nextRunAt,
+                    runCount: row.runCount,
+                    errorCount: row.errorCount,
+                    signalsProduced: row.signalsProduced,
+                    lastError: row.lastError,
+                }));
+            }
+            catch (err) {
+                api.logger.warn("[senpi-runtime] deploy: could not read scanner rows", { runtimeId, err });
+                return null;
+            }
+        }
+        registerDeployGatewayMethods(api, {
+            controller: deployController,
+            withSenpiClient,
+            installRuntime: (params) => installRuntimeCore(params),
+            deleteRuntime: async (id) => {
+                const result = await deleteRuntimeCore({ id });
+                if (!result.ok)
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+            },
+            registryFindByWallet: findRegistryEntryByWallet,
+            registryFindById: findRegistryEntryById,
+            getScannerRows: readScannerRows,
+            // H4: `runtimeHandles` holds the live `run()` handles. A registry row without one is a
+            // previous install whose runtime died before start — deploy must reinstall, not report it
+            // adopted. `unwiredRuntimes` is the same judgement one step further in: a runtime that is up
+            // but whose entry scanners never wired is running BLIND (the health surface already renders
+            // 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),
+            logger: { info: (line) => api.logger.info(`[senpi-runtime] ${line}`) },
+        });
         /**
          * Gateway shim for `senpi.ingestExternalScannerData`.
          *