squad-openclaw 2026.2.2703 → 2026.2.2704

package/README.md

@@ -1,18 +1,35 @@
 # squad-openclaw
 
-OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity registry, filesystem tools, SQL queries, version management, and Tailnet internal routes for secure onboarding helpers.
+OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity registry, locked-down filesystem tools, agent setup wrappers, plugin safety controls, and Tailnet internal routes for onboarding helpers.
 
 ## Features
 
-| Tool / Method | Description |
+| Tool / Method / Endpoint | Description |
 |---|---|
 | `entity_list`, `entity_search`, `entity_sync` | In-memory entity registry with filesystem watching (agents, skills, plugins, tools, media) |
 | `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | Remote filesystem access for browser clients (subject to security restrictions below) |
-| `sql_query` | Restricted SQLite query tool — `sqlite3` only, scoped to `~/.openclaw/squad-ceo-data/` |
-| `squad.version.check`, `squad.version.update` | Plugin version management and self-update |
-| `tools.invoke` | RPC-based tool invocation over gateway methods — **only invokes this plugin's own tools**, each with its own security restrictions (see below) |
+| `squad.agents.add` | Plugin wrapper for creating agent scaffolding (workspace seed files, sessions skeleton, and config list entry) |
+| `squad.version.check` | Plugin version reporting |
+| `squad.questions.validate-envelope` | HUMAN_INPUT_REQUIRED envelope validation |
+| `tools.invoke`, `tools.list`, `squad.layout.get` | Core plugin RPC entrypoints for tool invocation/listing and gateway layout metadata |
 | `squad.plugin.status`, `squad.plugin.recover`, `squad.plugin.disable` | Plugin safety-state RPC control (status, recovery, manual disable) |
-| `/squad-internal/health`, `/squad-internal/plugin/*`, `/squad-internal/pairing/*` | Tailnet internal health, safety-state, and pairing routes with origin/Tailnet checks |
+| `GET /squad-internal/health` | Tailnet internal health + pairing capability metadata |
+| `GET /squad-internal/plugin/status` | Tailnet internal plugin safety-state status |
+| `POST /squad-internal/plugin/recover`, `POST /squad-internal/plugin/disable` | Tailnet internal plugin safety-state controls |
+| `POST /squad-internal/pairing/request`, `GET /squad-internal/pairing/status` | Tailnet internal pairing helper routes with origin/Tailnet/browser-proof checks |
+
+## Internal Endpoint Reference
+
+All `/squad-internal/*` routes enforce Tailnet context and origin checks. CORS preflight (`OPTIONS`) is handled for these routes.
+
+| Route | Method | Purpose |
+|---|---|---|
+| `/squad-internal/health` | `GET` | Returns plugin safety snapshot and pairing capability hints |
+| `/squad-internal/plugin/status` | `GET` | Returns current plugin safety state |
+| `/squad-internal/plugin/recover` | `POST` | Recovers plugin safety state back to active (unless env kill-switch is set) |
+| `/squad-internal/plugin/disable` | `POST` | Manually disables plugin safety state |
+| `/squad-internal/pairing/request` | `POST` | Creates pairing request via gateway-native pairing methods (`node/devices/device.pair.request`) |
+| `/squad-internal/pairing/status` | `GET` | Resolves pairing status via gateway-native status methods (`node/devices/device.pair.status/get`) |
 
 ## State Directory Resolution
 
@@ -102,7 +119,7 @@ Filesystem operations are restricted to configured root directories. By default,
 
 Operators can customize via the `fs.allowedRoots` config option.
 
-### Layer 4: Filesystem Write Protection + Surgical Gateway Mutations
+### Layer 4: Filesystem Write Protection
 
 These files/directories cannot be written via filesystem tools (`fs_write`, `fs_rename`, etc.), even if they fall within `allowedRoots`:
 
@@ -192,6 +209,19 @@ Pairing helper routes enforce:
 
 `/squad-internal/pairing/request` and `/squad-internal/pairing/status` are still present for compatibility, but the current SPA pairing flow no longer depends on them as primary path.
 
+`POST /squad-internal/pairing/request` expects browser proof fields:
+
+- `deviceId`
+- `publicKey` (Ed25519) **or** `publicKeyJwk` (P-256)
+- `signature`
+- `nonce`
+- `signedAt`
+
+`GET /squad-internal/pairing/status` expects:
+
+- `requestId` query param
+- `deviceId` query param
+
 ### Legacy Relay-State File Handling
 
 `~/.openclaw/squad-ceo-data/relay/squad-relay.json` is still blocked by filesystem security rules to protect historical secrets from older relay transport versions.
@@ -203,23 +233,10 @@ The `tools.invoke` gateway method allows the browser to call plugin tools over W
 | Tool | What it can access | Restrictions |
 |---|---|---|
 | `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | `~/.openclaw/` only | All 4 security layers apply (blocked dirs, blocked files, redaction, allowed roots, write protection) |
-| `sql_query` | `~/.openclaw/squad-ceo-data/*.db` only | sqlite3 only, no shell, no command injection (see below) |
 | `entity_list`, `entity_search`, `entity_sync` | In-memory entity index | Read-only metadata (names, types, paths) |
-| `squad.version.check`, `squad.version.update` | npm registry | Read-only check + controlled `npm install` |
 
 It **cannot** invoke gateway core tools (`exec`, `bash`, `read`, `write`, `web_fetch`, etc.) — only the tools this plugin registers via `api.registerTool()`. Every invoked tool enforces its own security restrictions independently — `tools.invoke` is just a transport layer, not a privilege escalation.
 
-## SQL Query Tool
-
-> **`sql_query` can only access the plugin's own application data** in `~/.openclaw/squad-ceo-data/`. It cannot read or modify any other files on the system — not system databases, not user documents, not gateway configuration.
-
-The `sql_query` tool provides restricted SQLite access:
-
-- **Path restriction:** Database files must be within `~/.openclaw/squad-ceo-data/` — the plugin's own data directory containing entity registries and application state. Paths outside this directory are rejected before any query is executed.
-- **No shell:** Uses `execFile` (not `exec`) — arguments are passed as an argv array, preventing command injection
-- **No arbitrary commands:** Only `sqlite3` is executed — no other binary can be invoked through this tool
-- **Data scope:** The databases in `squad-ceo-data/` contain only Squad application data (entity metadata, search indexes, user preferences). No credentials, tokens, or gateway configuration is stored in these databases.
-
 ## Build Transparency
 
 The build configuration (`tsup.config.ts`) is optimized for security auditing:
@@ -244,10 +261,10 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 - **Plugin directory:** `extensions/squad-openclaw/`
 - **Security-critical files:**
   - `src/filesystem.ts` — path blocking, redaction, write protection
-  - `src/sql.ts` — restricted SQL execution
+  - `src/agents.ts` — wrapper for agent setup (workspace/session skeleton + config entry update)
   - `src/http-routes.ts` — Tailnet internal routes and browser-proof validation
   - `src/shared-api.ts` — gateway method + tool registration boundaries
-  - `src/relay-client.ts`, `src/device-keys.ts`, `src/e2e-crypto.ts` — legacy relay transport components retained in repository but not in the active Tailnet-direct setup path
+  - `src/plugin-safety-gateway.ts`, `src/plugin-safety-state.ts` — plugin safety-state control and persistence
 
 ## License
 

package/dist/index.js

@@ -1233,6 +1233,150 @@ function registerQuestionMethods(api) {
   );
 }
 
+// src/agents.ts
+import fs7 from "fs";
+import os2 from "os";
+import path7 from "path";
+var DEFAULT_WORKSPACE_FILES = {
+  "SOUL.md": "# Soul\n",
+  "USER.md": "# User\n",
+  "AGENTS.md": "# Agents\n",
+  "IDENTITY.md": "# Identity\n",
+  "BOOTSTRAP.md": "# Bootstrap\n",
+  "BOOT.md": "# Boot\n",
+  "HEARTBEAT.md": "# Heartbeat\n",
+  "TOOLS.md": "# Tools\n"
+};
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function normalizeAgentId(params) {
+  const candidate = typeof params.agentId === "string" && params.agentId.trim() || typeof params.name === "string" && params.name.trim() || "";
+  if (!candidate) throw new Error("Missing required parameter: agentId");
+  if (!/^[a-z0-9_-]+$/i.test(candidate)) {
+    throw new Error("Invalid agentId: only letters, numbers, _ and - are allowed");
+  }
+  return candidate;
+}
+function resolveWorkspacePath(input, stateDir, agentId) {
+  const fallback = agentId === "main" ? path7.join(stateDir, "workspace") : path7.join(stateDir, `workspace-${agentId}`);
+  if (typeof input !== "string" || !input.trim()) return fallback;
+  const raw = input.trim();
+  if (raw === "~/.openclaw") return stateDir;
+  if (raw.startsWith("~/.openclaw/")) {
+    return path7.resolve(stateDir, raw.slice("~/.openclaw/".length));
+  }
+  if (raw === "~") return os2.homedir();
+  if (raw.startsWith("~/")) return path7.resolve(os2.homedir(), raw.slice(2));
+  if (!path7.isAbsolute(raw)) return path7.resolve(stateDir, raw);
+  return path7.resolve(raw);
+}
+function assertWithinStateDir(targetPath, stateDir) {
+  const resolvedStateDir = path7.resolve(stateDir);
+  const resolvedTarget = path7.resolve(targetPath);
+  if (resolvedTarget === resolvedStateDir) return;
+  if (!resolvedTarget.startsWith(resolvedStateDir + path7.sep)) {
+    throw new Error("Workspace path must be inside OPENCLAW_STATE_DIR");
+  }
+}
+function normalizeModel(input) {
+  return typeof input === "string" && input.trim() ? input.trim() : void 0;
+}
+function normalizeIdentity(params) {
+  const identity = asRecord(params.identity);
+  const name = typeof identity.name === "string" && identity.name.trim() ? identity.name.trim() : typeof params.displayName === "string" && params.displayName.trim() ? params.displayName.trim() : void 0;
+  const emoji = typeof identity.emoji === "string" && identity.emoji.trim() ? identity.emoji.trim() : typeof params.emoji === "string" && params.emoji.trim() ? params.emoji.trim() : void 0;
+  const theme = typeof identity.theme === "string" && identity.theme.trim() ? identity.theme.trim() : typeof params.description === "string" && params.description.trim() ? params.description.trim() : typeof params.theme === "string" && params.theme.trim() ? params.theme.trim() : void 0;
+  return {
+    ...name ? { name } : {},
+    ...emoji ? { emoji } : {},
+    ...theme ? { theme } : {}
+  };
+}
+function ensureWorkspaceSkeleton(workspacePath) {
+  fs7.mkdirSync(workspacePath, { recursive: true });
+  for (const [fileName, defaultContent] of Object.entries(DEFAULT_WORKSPACE_FILES)) {
+    const filePath = path7.join(workspacePath, fileName);
+    if (!fs7.existsSync(filePath)) {
+      fs7.writeFileSync(filePath, defaultContent, "utf-8");
+    }
+  }
+}
+function ensureSessionsSkeleton(stateDir, agentId) {
+  const sessionsDir = path7.join(stateDir, "agents", agentId, "sessions");
+  fs7.mkdirSync(sessionsDir, { recursive: true });
+  const sessionsJsonPath = path7.join(sessionsDir, "sessions.json");
+  if (!fs7.existsSync(sessionsJsonPath)) {
+    fs7.writeFileSync(sessionsJsonPath, "{}", "utf-8");
+  }
+}
+function extractConfigList(snapshot) {
+  const cfgRoot = asRecord(snapshot);
+  const agentsRoot = asRecord(cfgRoot.agents);
+  const list = agentsRoot.list;
+  return Array.isArray(list) ? [...list] : [];
+}
+function upsertAgentListEntry(list, agentId, fields) {
+  const nextList = [];
+  let found = false;
+  for (const entry of list) {
+    const id = typeof entry?.id === "string" ? entry.id : void 0;
+    if (id === agentId) {
+      nextList.push({ ...entry, ...fields, id: agentId });
+      found = true;
+    } else {
+      nextList.push(entry);
+    }
+  }
+  if (!found) nextList.push({ id: agentId, ...fields });
+  return nextList;
+}
+function registerAgentMethods(api) {
+  api.registerGatewayMethod(
+    "squad.agents.add",
+    async (ctx) => {
+      try {
+        const params = ctx.params ?? {};
+        const stateDir = getOpenclawStateDir();
+        const configPath = process.env.OPENCLAW_CONFIG_PATH ? path7.resolve(process.env.OPENCLAW_CONFIG_PATH) : path7.join(stateDir, "openclaw.json");
+        const agentId = normalizeAgentId(params);
+        const workspacePath = resolveWorkspacePath(params.workspace, stateDir, agentId);
+        assertWithinStateDir(workspacePath, stateDir);
+        const model = normalizeModel(params.model);
+        const identity = normalizeIdentity(params);
+        ensureWorkspaceSkeleton(workspacePath);
+        ensureSessionsSkeleton(stateDir, agentId);
+        const rawConfig = fs7.readFileSync(configPath, "utf-8");
+        const snapshot = JSON.parse(rawConfig);
+        const cfgRoot = asRecord(snapshot);
+        const agentsRoot = asRecord(cfgRoot.agents);
+        const currentList = extractConfigList(snapshot);
+        const nextList = upsertAgentListEntry(currentList, agentId, {
+          workspace: workspacePath,
+          ...model ? { model } : {},
+          ...Object.keys(identity).length > 0 ? { identity } : {}
+        });
+        cfgRoot.agents = {
+          ...agentsRoot,
+          list: nextList
+        };
+        fs7.writeFileSync(configPath, JSON.stringify(cfgRoot, null, 2), "utf-8");
+        ctx.respond(true, {
+          ok: true,
+          agentId,
+          workspace: workspacePath
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.respond(false, {
+          error: message,
+          errorMessage: message
+        });
+      }
+    }
+  );
+}
+
 // src/safety.ts
 var TimeoutError = class extends Error {
   operation;
@@ -1268,6 +1412,262 @@ async function withTimeout(promise, timeoutMs, operation) {
   }
 }
 
+// src/plugin-safety-state.ts
+import crypto from "crypto";
+import fs8 from "fs";
+import path8 from "path";
+var SAFETY_DIR = path8.join(getOpenclawStateDir(), "squad-ceo-data", "safety");
+var PLUGIN_SAFETY_STATE_PATH = path8.join(SAFETY_DIR, "plugin-state.json");
+var FAILURE_THRESHOLD = readIntegerEnv("SQUAD_PLUGIN_FAILURE_THRESHOLD", 3, 1, 50);
+var FAILURE_WINDOW_MS = readTimeoutMs("SQUAD_PLUGIN_FAILURE_WINDOW_MS", 5 * 60 * 1e3, 1e3, 24 * 60 * 60 * 1e3);
+var QUARANTINE_MS = readTimeoutMs("SQUAD_PLUGIN_QUARANTINE_MS", 10 * 60 * 1e3, 1e3, 24 * 60 * 60 * 1e3);
+function readIntegerEnv(envName, fallback, min, max) {
+  const raw = process.env[envName];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  const rounded = Math.floor(parsed);
+  if (rounded < min) return min;
+  if (rounded > max) return max;
+  return rounded;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeIso(value) {
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) return null;
+  return new Date(parsed).toISOString();
+}
+function normalizeString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+function normalizeState(value) {
+  if (value === "ACTIVE" || value === "DISABLED_MANUAL" || value === "QUARANTINED_AUTO") {
+    return value;
+  }
+  return "ACTIVE";
+}
+function normalizeFailureCount(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  const rounded = Math.floor(value);
+  return rounded > 0 ? rounded : 0;
+}
+function parseMs(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) return null;
+  return parsed;
+}
+function defaultPersistedState() {
+  return {
+    version: 1,
+    state: "ACTIVE",
+    reasonCode: null,
+    reasonMessage: null,
+    remediation: null,
+    triggeredAt: null,
+    lastFailureAt: null,
+    lastFailureCode: null,
+    lastFailureMessage: null,
+    failureCount: 0,
+    failureWindowStartedAt: null,
+    quarantineUntil: null,
+    lastErrorId: null,
+    updatedAt: nowIso()
+  };
+}
+function sanitizePersistedState(value) {
+  const state = defaultPersistedState();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return state;
+  const record = value;
+  return {
+    version: 1,
+    state: normalizeState(record.state),
+    reasonCode: normalizeString(record.reasonCode),
+    reasonMessage: normalizeString(record.reasonMessage),
+    remediation: normalizeString(record.remediation),
+    triggeredAt: normalizeIso(record.triggeredAt),
+    lastFailureAt: normalizeIso(record.lastFailureAt),
+    lastFailureCode: normalizeString(record.lastFailureCode),
+    lastFailureMessage: normalizeString(record.lastFailureMessage),
+    failureCount: normalizeFailureCount(record.failureCount),
+    failureWindowStartedAt: normalizeIso(record.failureWindowStartedAt),
+    quarantineUntil: normalizeIso(record.quarantineUntil),
+    lastErrorId: normalizeString(record.lastErrorId),
+    updatedAt: normalizeIso(record.updatedAt) ?? nowIso()
+  };
+}
+function readPersistedState() {
+  try {
+    const raw = fs8.readFileSync(PLUGIN_SAFETY_STATE_PATH, "utf-8");
+    return sanitizePersistedState(JSON.parse(raw));
+  } catch {
+    return defaultPersistedState();
+  }
+}
+function writePersistedState(state) {
+  try {
+    fs8.mkdirSync(SAFETY_DIR, { recursive: true });
+    const tempPath = `${PLUGIN_SAFETY_STATE_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs8.writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+    fs8.renameSync(tempPath, PLUGIN_SAFETY_STATE_PATH);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[squad-openclaw] failed to persist plugin safety state: ${message}`);
+  }
+}
+function isTruthy(value) {
+  if (!value) return false;
+  return /^(1|true|yes|on)$/i.test(value.trim());
+}
+function isEnvKillSwitchActive() {
+  return isTruthy(process.env.SQUAD_PLUGIN_DISABLED);
+}
+function envKillSwitchReason() {
+  const configured = normalizeString(process.env.SQUAD_PLUGIN_DISABLE_REASON);
+  return configured ?? "Plugin disabled by SQUAD_PLUGIN_DISABLED";
+}
+function snapshotFromState(state, source, canRecover) {
+  return {
+    state: state.state,
+    source,
+    blocked: state.state !== "ACTIVE",
+    canRecover,
+    reasonCode: state.reasonCode,
+    reasonMessage: state.reasonMessage,
+    remediation: state.remediation,
+    triggeredAt: state.triggeredAt,
+    lastFailureAt: state.lastFailureAt,
+    lastFailureCode: state.lastFailureCode,
+    lastFailureMessage: state.lastFailureMessage,
+    failureCount: state.failureCount,
+    quarantineUntil: state.quarantineUntil,
+    lastErrorId: state.lastErrorId,
+    updatedAt: state.updatedAt,
+    stateFilePath: PLUGIN_SAFETY_STATE_PATH
+  };
+}
+function maybeReleaseExpiredQuarantine(state) {
+  if (state.state !== "QUARANTINED_AUTO") return state;
+  const untilMs = parseMs(state.quarantineUntil);
+  if (untilMs == null || Date.now() < untilMs) return state;
+  const released = {
+    ...state,
+    state: "ACTIVE",
+    reasonCode: null,
+    reasonMessage: null,
+    remediation: null,
+    triggeredAt: nowIso(),
+    quarantineUntil: null,
+    failureCount: 0,
+    failureWindowStartedAt: null,
+    updatedAt: nowIso()
+  };
+  writePersistedState(released);
+  return released;
+}
+function generateErrorId() {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  }
+}
+function getPluginSafetySnapshot() {
+  const persisted = maybeReleaseExpiredQuarantine(readPersistedState());
+  if (isEnvKillSwitchActive()) {
+    const envState = {
+      ...persisted,
+      state: "DISABLED_MANUAL",
+      reasonCode: "ENV_KILL_SWITCH",
+      reasonMessage: envKillSwitchReason(),
+      remediation: "Unset SQUAD_PLUGIN_DISABLED and restart the gateway process.",
+      triggeredAt: persisted.triggeredAt ?? nowIso(),
+      updatedAt: nowIso()
+    };
+    return snapshotFromState(envState, "env", false);
+  }
+  return snapshotFromState(persisted, "file", true);
+}
+function isPluginExecutionBlocked(snapshot) {
+  return snapshot.state !== "ACTIVE";
+}
+function recordPluginFailure(failureCode, failureMessage, remediation) {
+  if (isEnvKillSwitchActive()) return getPluginSafetySnapshot();
+  const state = readPersistedState();
+  const nowMs = Date.now();
+  const now = new Date(nowMs).toISOString();
+  const windowStartMs = parseMs(state.failureWindowStartedAt);
+  if (windowStartMs == null || nowMs - windowStartMs > FAILURE_WINDOW_MS) {
+    state.failureWindowStartedAt = now;
+    state.failureCount = 1;
+  } else {
+    state.failureCount += 1;
+  }
+  state.lastFailureAt = now;
+  state.lastFailureCode = failureCode;
+  state.lastFailureMessage = failureMessage;
+  state.lastErrorId = generateErrorId();
+  if (state.state !== "DISABLED_MANUAL" && state.failureCount >= FAILURE_THRESHOLD) {
+    state.state = "QUARANTINED_AUTO";
+    state.reasonCode = "AUTO_QUARANTINED";
+    state.reasonMessage = `Plugin auto-quarantined after ${state.failureCount} failures in ${Math.round(
+      FAILURE_WINDOW_MS / 1e3
+    )} seconds`;
+    state.remediation = remediation ?? "Resolve the underlying plugin issue, then run squad.plugin.recover or wait for quarantine expiry.";
+    state.triggeredAt = now;
+    state.quarantineUntil = new Date(nowMs + QUARANTINE_MS).toISOString();
+  }
+  state.updatedAt = now;
+  writePersistedState(state);
+  return getPluginSafetySnapshot();
+}
+function setPluginManualDisabled(reasonCode = "MANUAL_KILL_SWITCH", reasonMessage = "Plugin manually disabled", remediation = "Run squad.plugin.recover after resolving plugin issues.") {
+  if (isEnvKillSwitchActive()) return getPluginSafetySnapshot();
+  const state = readPersistedState();
+  const now = nowIso();
+  state.state = "DISABLED_MANUAL";
+  state.reasonCode = reasonCode;
+  state.reasonMessage = reasonMessage;
+  state.remediation = remediation;
+  state.triggeredAt = now;
+  state.quarantineUntil = null;
+  state.updatedAt = now;
+  writePersistedState(state);
+  return getPluginSafetySnapshot();
+}
+function recoverPlugin(reasonMessage = "Plugin manually recovered") {
+  if (isEnvKillSwitchActive()) {
+    return {
+      ok: false,
+      message: "Cannot recover while SQUAD_PLUGIN_DISABLED is enabled.",
+      snapshot: getPluginSafetySnapshot()
+    };
+  }
+  const state = readPersistedState();
+  const now = nowIso();
+  state.state = "ACTIVE";
+  state.reasonCode = null;
+  state.reasonMessage = null;
+  state.remediation = null;
+  state.triggeredAt = now;
+  state.quarantineUntil = null;
+  state.failureCount = 0;
+  state.failureWindowStartedAt = null;
+  state.updatedAt = now;
+  writePersistedState(state);
+  return {
+    ok: true,
+    message: reasonMessage,
+    snapshot: getPluginSafetySnapshot()
+  };
+}
+
 // src/shared-api.ts
 var CORE_TOOLS = [
   "exec",
@@ -1309,6 +1709,17 @@ var TOOLS_INVOKE_TIMEOUT_MS = readTimeoutMs("SQUAD_TOOLS_INVOKE_TIMEOUT_MS", 6e4
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function pluginBlockedPayload(snapshot) {
+  const code = snapshot.state === "QUARANTINED_AUTO" ? "PLUGIN_QUARANTINED" : "PLUGIN_DISABLED";
+  const message = snapshot.reasonMessage ?? (snapshot.state === "QUARANTINED_AUTO" ? "Plugin is temporarily auto-quarantined" : "Plugin is currently disabled");
+  return {
+    code,
+    error: message,
+    errorCode: code,
+    errorMessage: message,
+    plugin: snapshot
+  };
+}
 function registerSquadSharedApi(api, onFsChange) {
   const toolExecutors = /* @__PURE__ */ new Map();
   const registerToolFn = typeof api?.registerTool === "function" ? api.registerTool.bind(api) : null;
@@ -1333,6 +1744,7 @@ function registerSquadSharedApi(api, onFsChange) {
   registerStep("filesystem tools", () => registerFilesystemTools(api));
   registerStep("version methods", () => registerVersionMethods(api));
   registerStep("question methods", () => registerQuestionMethods(api));
+  registerStep("agent methods", () => registerAgentMethods(api));
   const invokeTool = async (tool, args) => {
     const executeFn = toolExecutors.get(tool);
     if (!executeFn) {
@@ -1357,6 +1769,11 @@ function registerSquadSharedApi(api, onFsChange) {
     safeRegisterGatewayMethod(
       "tools.invoke",
       async ({ params, respond }) => {
+        const safetySnapshot = getPluginSafetySnapshot();
+        if (isPluginExecutionBlocked(safetySnapshot)) {
+          respond(false, pluginBlockedPayload(safetySnapshot));
+          return;
+        }
         const tool = params?.tool;
         const args = params?.args ?? {};
         if (!tool) {
@@ -1372,7 +1789,18 @@ function registerSquadSharedApi(api, onFsChange) {
           respond(true, result);
         } catch (err2) {
           if (err2 instanceof TimeoutError) {
+            const snapshot = recordPluginFailure(
+              "TOOLS_INVOKE_TIMEOUT",
+              `Tool '${tool}' timed out after ${TOOLS_INVOKE_TIMEOUT_MS}ms`,
+              "Investigate long-running plugin operations and run squad.plugin.recover."
+            );
+            if (isPluginExecutionBlocked(snapshot)) {
+              respond(false, pluginBlockedPayload(snapshot));
+              return;
+            }
             respond(false, {
+              code: "PLUGIN_TIMEOUT",
+              error: `Tool '${tool}' timed out after ${TOOLS_INVOKE_TIMEOUT_MS}ms`,
               errorCode: "PLUGIN_TIMEOUT",
               errorMessage: `Tool '${tool}' timed out after ${TOOLS_INVOKE_TIMEOUT_MS}ms`
             });
@@ -1385,12 +1813,22 @@ function registerSquadSharedApi(api, onFsChange) {
     safeRegisterGatewayMethod(
       "tools.list",
       async ({ respond }) => {
+        const safetySnapshot = getPluginSafetySnapshot();
+        if (isPluginExecutionBlocked(safetySnapshot)) {
+          respond(false, pluginBlockedPayload(safetySnapshot));
+          return;
+        }
         respond(true, { tools: listTools() });
       }
     );
     safeRegisterGatewayMethod(
       "squad.layout.get",
       async ({ respond }) => {
+        const safetySnapshot = getPluginSafetySnapshot();
+        if (isPluginExecutionBlocked(safetySnapshot)) {
+          respond(false, pluginBlockedPayload(safetySnapshot));
+          return;
+        }
         try {
           const layout = resolveGatewayLayout();
           respond(true, layout);
@@ -1408,13 +1846,13 @@ function registerSquadSharedApi(api, onFsChange) {
 }
 
 // src/migrations/runner.ts
-import fs9 from "fs";
-import path9 from "path";
+import fs11 from "fs";
+import path11 from "path";
 
 // src/migrations/001-enable-main-subagent-access.ts
-import fs7 from "fs";
-import path7 from "path";
-function asRecord(value) {
+import fs9 from "fs";
+import path9 from "path";
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
@@ -1429,24 +1867,24 @@ function mergeStringArrayWithWildcard(value) {
   return Array.from(next);
 }
 function patchConfigOnDisk() {
-  const configPath = path7.join(getOpenclawStateDir(), "openclaw.json");
-  const raw = fs7.readFileSync(configPath, "utf-8");
+  const configPath = path9.join(getOpenclawStateDir(), "openclaw.json");
+  const raw = fs9.readFileSync(configPath, "utf-8");
   const parsed = JSON.parse(raw);
-  const agents = asRecord(parsed.agents) ?? {};
-  const defaults = asRecord(agents.defaults) ?? {};
-  const subagentsDefaults = asRecord(defaults.subagents) ?? {};
+  const agents = asRecord2(parsed.agents) ?? {};
+  const defaults = asRecord2(agents.defaults) ?? {};
+  const subagentsDefaults = asRecord2(defaults.subagents) ?? {};
   defaults.maxConcurrent = 4;
   defaults.subagents = {
     ...subagentsDefaults,
     maxConcurrent: 8
   };
   const listRaw = Array.isArray(agents.list) ? agents.list : [];
-  const list = listRaw.map((entry) => asRecord(entry)).filter((entry) => Boolean(entry));
+  const list = listRaw.map((entry) => asRecord2(entry)).filter((entry) => Boolean(entry));
   const mainIndex = list.findIndex((entry) => entry.id === "main");
   const existingMain = mainIndex >= 0 ? list[mainIndex] : {};
-  const existingIdentity = asRecord(existingMain.identity) ?? {};
-  const existingTools = asRecord(existingMain.tools) ?? {};
-  const existingSubagents = asRecord(existingMain.subagents) ?? {};
+  const existingIdentity = asRecord2(existingMain.identity) ?? {};
+  const existingTools = asRecord2(existingMain.tools) ?? {};
+  const existingSubagents = asRecord2(existingMain.subagents) ?? {};
   const nextMain = {
     ...existingMain,
     id: "main",
@@ -1470,7 +1908,7 @@ function patchConfigOnDisk() {
     defaults,
     list
   };
-  fs7.writeFileSync(configPath, `${JSON.stringify(parsed, null, 2)}
+  fs9.writeFileSync(configPath, `${JSON.stringify(parsed, null, 2)}
 `, "utf-8");
 }
 var migration = {
@@ -1545,13 +1983,13 @@ var migration = {
 var enable_main_subagent_access_default = migration;
 
 // src/auth-profiles.ts
-import fs8 from "fs";
-import path8 from "path";
+import fs10 from "fs";
+import path10 from "path";
 function getMainAuthProfilesPath(stateDir) {
-  return path8.join(stateDir, "agents", "main", "agent", "auth-profiles.json");
+  return path10.join(stateDir, "agents", "main", "agent", "auth-profiles.json");
 }
 function getAgentAuthProfilesPath(stateDir, agentId) {
-  return path8.join(stateDir, "agents", agentId, "agent", "auth-profiles.json");
+  return path10.join(stateDir, "agents", agentId, "agent", "auth-profiles.json");
 }
 function ensureAgentAuthProfiles(agentId) {
   const normalizedAgentId = agentId.trim();
@@ -1559,17 +1997,17 @@ function ensureAgentAuthProfiles(agentId) {
   const stateDir = getOpenclawStateDir();
   const sourcePath = getMainAuthProfilesPath(stateDir);
   const targetPath = getAgentAuthProfilesPath(stateDir, normalizedAgentId);
-  if (!fs8.existsSync(sourcePath) || fs8.existsSync(targetPath)) return false;
-  fs8.mkdirSync(path8.dirname(targetPath), { recursive: true });
-  fs8.copyFileSync(sourcePath, targetPath);
+  if (!fs10.existsSync(sourcePath) || fs10.existsSync(targetPath)) return false;
+  fs10.mkdirSync(path10.dirname(targetPath), { recursive: true });
+  fs10.copyFileSync(sourcePath, targetPath);
   return true;
 }
 function backfillAgentAuthProfiles() {
   const stateDir = getOpenclawStateDir();
-  const agentsDir = path8.join(stateDir, "agents");
-  if (!fs8.existsSync(agentsDir)) return [];
+  const agentsDir = path10.join(stateDir, "agents");
+  if (!fs10.existsSync(agentsDir)) return [];
   const copied = [];
-  for (const entry of fs8.readdirSync(agentsDir, { withFileTypes: true })) {
+  for (const entry of fs10.readdirSync(agentsDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     const agentId = entry.name;
     if (ensureAgentAuthProfiles(agentId)) {
@@ -1600,8 +2038,8 @@ var STARTUP_MIGRATIONS = [
 ];
 
 // src/migrations/runner.ts
-var MIGRATIONS_DIR = path9.join(getOpenclawStateDir(), "squad-ceo-data");
-var MIGRATIONS_PATH = path9.join(MIGRATIONS_DIR, "migrations.json");
+var MIGRATIONS_DIR = path11.join(getOpenclawStateDir(), "squad-ceo-data");
+var MIGRATIONS_PATH = path11.join(MIGRATIONS_DIR, "migrations.json");
 var STARTUP_MIGRATION_TIMEOUT_MS = readTimeoutMs("SQUAD_STARTUP_MIGRATION_TIMEOUT_MS", 2e4);
 var STARTUP_GATEWAY_CALL_TIMEOUT_MS = readTimeoutMs("SQUAD_STARTUP_GATEWAY_CALL_TIMEOUT_MS", 5e3);
 function defaultState() {
@@ -1612,7 +2050,7 @@ function defaultState() {
 }
 function readState() {
   try {
-    const raw = fs9.readFileSync(MIGRATIONS_PATH, "utf-8");
+    const raw = fs11.readFileSync(MIGRATIONS_PATH, "utf-8");
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed.completed)) return defaultState();
     return {
@@ -1624,8 +2062,8 @@ function readState() {
   }
 }
 function writeState(state) {
-  fs9.mkdirSync(MIGRATIONS_DIR, { recursive: true });
-  fs9.writeFileSync(MIGRATIONS_PATH, JSON.stringify(state, null, 2), "utf-8");
+  fs11.mkdirSync(MIGRATIONS_DIR, { recursive: true });
+  fs11.writeFileSync(MIGRATIONS_PATH, JSON.stringify(state, null, 2), "utf-8");
 }
 function makeGatewayCaller(api) {
   return async (method, params = {}) => {
@@ -1691,10 +2129,10 @@ async function runStartupMigrations(api) {
 }
 
 // src/http-routes.ts
-import crypto from "crypto";
+import crypto2 from "crypto";
 
 // src/gateway-invoke.ts
-function asRecord2(value) {
+function asRecord3(value) {
   return value && typeof value === "object" ? value : null;
 }
 function isInvoker(fn) {
@@ -1706,8 +2144,8 @@ function isUnknownGatewayMethodError(message) {
   );
 }
 async function callGatewayAny(ctx, api, method, params) {
-  const ctxGateway = asRecord2(ctx.gateway);
-  const apiGateway = asRecord2(api?.gateway);
+  const ctxGateway = asRecord3(ctx.gateway);
+  const apiGateway = asRecord3(api?.gateway);
   const candidates = [
     ctx.request,
     ctx.callGatewayMethod,
@@ -1768,7 +2206,7 @@ var PAIRING_GATEWAY_CALL_TIMEOUT_MS = readTimeoutMs("SQUAD_PAIRING_GATEWAY_CALL_
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function asRecord3(value) {
+function asRecord4(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
@@ -1834,6 +2272,11 @@ function ensureOriginAllowed(request) {
   if (!origin) return null;
   return resolveAllowedOrigin(origin);
 }
+function isOriginAllowedIfPresent(request) {
+  const origin = request.headers.get("origin");
+  if (!origin) return true;
+  return resolveAllowedOrigin(origin) !== null;
+}
 function firstHeaderToken(value) {
   if (!value) return null;
   const first = value.split(",")[0]?.trim();
@@ -1923,7 +2366,7 @@ function encodeUtf8(value) {
 function normalizeDevicePublicKeyBase64Url(publicKey) {
   try {
     if (publicKey.includes("BEGIN")) {
-      const spki = crypto.createPublicKey(publicKey).export({
+      const spki = crypto2.createPublicKey(publicKey).export({
         type: "spki",
         format: "der"
       });
@@ -1943,7 +2386,7 @@ function deriveDeviceIdFromPublicKey(publicKey) {
     if (!normalized) return null;
     const raw = decodeBase64Url(normalized);
     if (raw.length !== 32) return null;
-    return crypto.createHash("sha256").update(raw).digest("hex");
+    return crypto2.createHash("sha256").update(raw).digest("hex");
   } catch {
     return null;
   }
@@ -1952,7 +2395,7 @@ function verifyEd25519Signature(publicKey, payload, signatureBase64Url) {
   try {
     const normalized = normalizeDevicePublicKeyBase64Url(publicKey);
     if (!normalized) return false;
-    const key = crypto.createPublicKey({
+    const key = crypto2.createPublicKey({
       key: Buffer.concat([ED25519_SPKI_PREFIX, decodeBase64Url(normalized)]),
       type: "spki",
       format: "der"
@@ -1964,13 +2407,13 @@ function verifyEd25519Signature(publicKey, payload, signatureBase64Url) {
         return Buffer.from(signatureBase64Url, "base64");
       }
     })();
-    return crypto.verify(null, Buffer.from(payload, "utf8"), key, signature);
+    return crypto2.verify(null, Buffer.from(payload, "utf8"), key, signature);
   } catch {
     return false;
   }
 }
 function canonicalizeP256Jwk(value) {
-  const record = asRecord3(value);
+  const record = asRecord4(value);
   const kty = pickString(record?.kty);
   const crv = pickString(record?.crv);
   const x = pickString(record?.x);
@@ -1982,7 +2425,7 @@ function canonicalizeP256Jwk(value) {
 }
 function computeDeviceIdFromJwk(jwk) {
   const canonical = JSON.stringify(jwk);
-  return crypto.createHash("sha256").update(canonical).digest("hex");
+  return crypto2.createHash("sha256").update(canonical).digest("hex");
 }
 function buildProofPayload(action, deviceId, nonce, signedAt, origin) {
   return `squad.${action}|${deviceId}|${nonce}|${signedAt}|${origin}`;
@@ -2063,14 +2506,14 @@ async function verifyBrowserProof(payload, origin, action, usedProofNonces) {
       };
     }
     try {
-      const key = await crypto.webcrypto.subtle.importKey(
+      const key = await crypto2.webcrypto.subtle.importKey(
         "jwk",
         jwk,
         { name: "ECDSA", namedCurve: "P-256" },
         false,
         ["verify"]
       );
-      verified = await crypto.webcrypto.subtle.verify(
+      verified = await crypto2.webcrypto.subtle.verify(
         { name: "ECDSA", hash: "SHA-256" },
         key,
         decodeBase64Url(signature),
@@ -2101,18 +2544,18 @@ function normalizePairingStatus(value) {
   return "unknown";
 }
 function extractRequestId(result) {
-  const obj = asRecord3(result);
+  const obj = asRecord4(result);
   if (!obj) return null;
-  const nestedRequest = asRecord3(obj.request);
+  const nestedRequest = asRecord4(obj.request);
   return pickString(obj.requestId) ?? pickString(obj.id) ?? pickString(nestedRequest?.requestId) ?? pickString(nestedRequest?.id);
 }
 function extractExpiresAt(result) {
-  const obj = asRecord3(result);
+  const obj = asRecord4(result);
   const candidates = [
     obj?.expiresAt,
     obj?.expiresAtMs,
-    asRecord3(obj?.request)?.expiresAt,
-    asRecord3(obj?.request)?.expiresAtMs
+    asRecord4(obj?.request)?.expiresAt,
+    asRecord4(obj?.request)?.expiresAtMs
   ];
   for (const candidate of candidates) {
     if (typeof candidate === "number" && Number.isFinite(candidate) && candidate > Date.now()) {
@@ -2132,12 +2575,12 @@ function extractExpiresAt(result) {
   return Date.now() + DEFAULT_PAIRING_TTL_MS;
 }
 function extractPairingStatus(result) {
-  const obj = asRecord3(result);
+  const obj = asRecord4(result);
   if (!obj) return "unknown";
   const candidates = [
     obj.status,
-    asRecord3(obj.request)?.status,
-    asRecord3(obj.pairing)?.status
+    asRecord4(obj.request)?.status,
+    asRecord4(obj.pairing)?.status
   ];
   for (const candidate of candidates) {
     const parsed = normalizePairingStatus(candidate);
@@ -2158,6 +2601,12 @@ function isRateLimited(bucket, key, limit, windowMs) {
   existing.count += 1;
   return false;
 }
+function pluginBlockedCode(snapshot) {
+  return snapshot.state === "QUARANTINED_AUTO" ? "PLUGIN_QUARANTINED" : "PLUGIN_DISABLED";
+}
+function pluginBlockedMessage(snapshot) {
+  return snapshot.reasonMessage ?? (snapshot.state === "QUARANTINED_AUTO" ? "Plugin is temporarily auto-quarantined" : "Plugin is currently disabled");
+}
 function registerTailnetInternalRoutes(api) {
   const pendingPairings = /* @__PURE__ */ new Map();
   const proofNonces = /* @__PURE__ */ new Map();
@@ -2228,9 +2677,10 @@ function registerTailnetInternalRoutes(api) {
   };
   const handleRequest = async (request) => {
     const url = getRequestUrl(request);
-    const path10 = url.pathname;
+    const path12 = url.pathname;
     cleanupCaches();
-    if (request.method === "OPTIONS" && path10.startsWith("/squad-internal/")) {
+    let pluginState = getPluginSafetySnapshot();
+    if (request.method === "OPTIONS" && path12.startsWith("/squad-internal/")) {
       const origin = ensureOriginAllowed(request);
       if (!origin) {
         return new Response(null, { status: 403 });
@@ -2248,7 +2698,7 @@ function registerTailnetInternalRoutes(api) {
         })
       );
     }
-    if (request.method === "GET" && path10 === "/squad-internal/health") {
+    if (request.method === "GET" && path12 === "/squad-internal/health") {
       if (!isTailnetContext(request)) {
         return jsonError(request, "TAILNET_REQUIRED", "Tailnet context required", 403);
       }
@@ -2257,6 +2707,7 @@ function registerTailnetInternalRoutes(api) {
         json({
           ok: true,
           mode: "tailnet-direct",
+          plugin: pluginState,
           pairing: {
             requestSupported: preferredPairingRequestMethod ?? PAIRING_REQUEST_METHODS[0],
             statusSupported: preferredPairingStatusMethod ?? "auto"
@@ -2264,7 +2715,91 @@ function registerTailnetInternalRoutes(api) {
         })
       );
     }
-    if (request.method === "POST" && path10 === "/squad-internal/pairing/request") {
+    if (request.method === "GET" && path12 === "/squad-internal/plugin/status") {
+      if (!isTailnetContext(request)) {
+        return jsonError(request, "TAILNET_REQUIRED", "Tailnet context required", 403);
+      }
+      if (!isOriginAllowedIfPresent(request)) {
+        return jsonError(request, "ORIGIN_NOT_ALLOWED", "Origin is not allowed", 403);
+      }
+      return withCors(
+        request,
+        json({
+          ok: true,
+          plugin: pluginState
+        })
+      );
+    }
+    if (request.method === "POST" && path12 === "/squad-internal/plugin/recover") {
+      if (!isTailnetContext(request)) {
+        return jsonError(request, "TAILNET_REQUIRED", "Tailnet context required", 403);
+      }
+      if (!isOriginAllowedIfPresent(request)) {
+        return jsonError(request, "ORIGIN_NOT_ALLOWED", "Origin is not allowed", 403);
+      }
+      let note;
+      try {
+        const body = await request.json();
+        if (typeof body?.note === "string" && body.note.trim()) {
+          note = body.note.trim();
+        }
+      } catch {
+      }
+      const result = recoverPlugin(note ?? "Plugin recovered via internal route");
+      if (!result.ok) {
+        return withCors(
+          request,
+          json(
+            {
+              ok: false,
+              code: "PLUGIN_KILL_SWITCH_ENV",
+              error: result.message,
+              plugin: result.snapshot
+            },
+            409
+          )
+        );
+      }
+      pluginState = result.snapshot;
+      return withCors(request, json({ ok: true, plugin: pluginState, message: result.message }));
+    }
+    if (request.method === "POST" && path12 === "/squad-internal/plugin/disable") {
+      if (!isTailnetContext(request)) {
+        return jsonError(request, "TAILNET_REQUIRED", "Tailnet context required", 403);
+      }
+      if (!isOriginAllowedIfPresent(request)) {
+        return jsonError(request, "ORIGIN_NOT_ALLOWED", "Origin is not allowed", 403);
+      }
+      let reasonCode = "MANUAL_KILL_SWITCH";
+      let reasonMessage = "Plugin manually disabled via internal route";
+      let remediation = "Run /squad-internal/plugin/recover after fixing plugin issues.";
+      try {
+        const body = await request.json();
+        if (typeof body?.reasonCode === "string" && body.reasonCode.trim()) {
+          reasonCode = body.reasonCode.trim();
+        }
+        if (typeof body?.reasonMessage === "string" && body.reasonMessage.trim()) {
+          reasonMessage = body.reasonMessage.trim();
+        }
+        if (typeof body?.remediation === "string" && body.remediation.trim()) {
+          remediation = body.remediation.trim();
+        }
+      } catch {
+      }
+      pluginState = setPluginManualDisabled(reasonCode, reasonMessage, remediation);
+      return withCors(request, json({ ok: true, plugin: pluginState }));
+    }
+    if (path12.startsWith("/squad-internal/") && isPluginExecutionBlocked(pluginState)) {
+      const code = pluginBlockedCode(pluginState);
+      return jsonError(
+        request,
+        code,
+        pluginBlockedMessage(pluginState),
+        503,
+        { plugin: pluginState }
+      );
+    }
+    if (request.method === "POST" && path12 === "/squad-internal/pairing/request") {
       const origin = ensureOriginAllowed(request);
       if (!origin) {
         return jsonError(request, "ORIGIN_NOT_ALLOWED", "Origin is not allowed", 403);
@@ -2316,7 +2851,7 @@ function registerTailnetInternalRoutes(api) {
         );
       }
     }
-    if (request.method === "GET" && path10 === "/squad-internal/pairing/status") {
+    if (request.method === "GET" && path12 === "/squad-internal/pairing/status") {
       const origin = ensureOriginAllowed(request);
       if (!origin) {
         return jsonError(request, "ORIGIN_NOT_ALLOWED", "Origin is not allowed", 403);
@@ -2365,20 +2900,32 @@ function registerTailnetInternalRoutes(api) {
       );
     } catch (error) {
       if (error instanceof TimeoutError) {
+        const snapshot2 = recordPluginFailure(
+          "INTERNAL_ROUTE_TIMEOUT",
+          `${error.operation} timed out after ${error.timeoutMs}ms`,
+          "Investigate internal route hangs and run squad.plugin.recover after remediation."
+        );
         console.warn(`[squad-openclaw] ${error.operation}`);
         return jsonError(
           request,
-          "ROUTE_TIMEOUT",
+          snapshot2.state === "QUARANTINED_AUTO" ? "PLUGIN_QUARANTINED" : "ROUTE_TIMEOUT",
           `Internal route timed out after ${error.timeoutMs}ms`,
-          504
+          snapshot2.state === "QUARANTINED_AUTO" ? 503 : 504,
+          snapshot2.state === "QUARANTINED_AUTO" ? { plugin: snapshot2 } : {}
         );
       }
+      const snapshot = recordPluginFailure(
+        "INTERNAL_ROUTE_ERROR",
+        errorMessage2(error),
+        "Inspect internal route failures and run squad.plugin.recover after remediation."
+      );
       console.warn(`[squad-openclaw] internal route failure: ${errorMessage2(error)}`);
       return jsonError(
         request,
-        "INTERNAL_ROUTE_ERROR",
+        snapshot.state === "QUARANTINED_AUTO" ? "PLUGIN_QUARANTINED" : "INTERNAL_ROUTE_ERROR",
         "Internal route failed unexpectedly",
-        500
+        snapshot.state === "QUARANTINED_AUTO" ? 503 : 500,
+        snapshot.state === "QUARANTINED_AUTO" ? { plugin: snapshot } : {}
       );
     }
   };
@@ -2386,6 +2933,9 @@ function registerTailnetInternalRoutes(api) {
     api.registerHttpHandler(handle);
   } else if (typeof api.registerHttpRoute === "function") {
     api.registerHttpRoute("/squad-internal/health", handle);
+    api.registerHttpRoute("/squad-internal/plugin/status", handle);
+    api.registerHttpRoute("/squad-internal/plugin/recover", handle);
+    api.registerHttpRoute("/squad-internal/plugin/disable", handle);
     api.registerHttpRoute("/squad-internal/pairing/request", handle);
     api.registerHttpRoute("/squad-internal/pairing/status", handle);
     api.registerHttpRoute("/squad-internal/*", handle);
@@ -2396,36 +2946,122 @@ function registerTailnetInternalRoutes(api) {
   }
 }
 
+// src/plugin-safety-gateway.ts
+function errorMessage3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function registerPluginSafetyGatewayMethods(api) {
+  const registerGatewayMethod = typeof api?.registerGatewayMethod === "function" ? api.registerGatewayMethod.bind(api) : null;
+  if (!registerGatewayMethod) {
+    console.warn("[squad-openclaw] registerGatewayMethod unavailable; plugin safety methods disabled");
+    return;
+  }
+  const safeRegister = (method, handler) => {
+    try {
+      registerGatewayMethod(method, handler);
+    } catch (error) {
+      console.warn(`[squad-openclaw] failed to register ${method}: ${errorMessage3(error)}`);
+    }
+  };
+  safeRegister("squad.plugin.status", async ({ respond }) => {
+    respond(true, { plugin: getPluginSafetySnapshot() });
+  });
+  safeRegister("squad.plugin.recover", async ({ params, respond }) => {
+    const note = typeof params?.note === "string" ? params.note.trim() : "";
+    const result = recoverPlugin(note || "Plugin recovered via gateway RPC");
+    if (!result.ok) {
+      respond(false, {
+        code: "PLUGIN_KILL_SWITCH_ENV",
+        error: result.message,
+        plugin: result.snapshot
+      });
+      return;
+    }
+    respond(true, { plugin: result.snapshot, message: result.message });
+  });
+  safeRegister("squad.plugin.disable", async ({ params, respond }) => {
+    const reasonCode = typeof params?.reasonCode === "string" && params.reasonCode.trim() ? params.reasonCode.trim() : "MANUAL_KILL_SWITCH";
+    const reasonMessage = typeof params?.reasonMessage === "string" && params.reasonMessage.trim() ? params.reasonMessage.trim() : "Plugin manually disabled via gateway RPC";
+    const remediation = typeof params?.remediation === "string" && params.remediation.trim() ? params.remediation.trim() : "Run squad.plugin.recover after resolving plugin issues.";
+    const snapshot = setPluginManualDisabled(reasonCode, reasonMessage, remediation);
+    respond(true, { plugin: snapshot });
+  });
+}
+
 // src/index.ts
 var STARTUP_MIGRATIONS_TIMEOUT_MS = readTimeoutMs("SQUAD_STARTUP_MIGRATIONS_TIMEOUT_MS", 3e4);
-function errorMessage3(error) {
+function errorMessage4(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function squadAppPlugin(api) {
+  registerPluginSafetyGatewayMethods(api);
+  let safetySnapshot = getPluginSafetySnapshot();
+  if (safetySnapshot.blocked) {
+    console.warn(
+      `[squad-openclaw] plugin boot starts in ${safetySnapshot.state} mode (${safetySnapshot.reasonCode ?? "NO_REASON"})`
+    );
+  }
   let sharedApi = null;
+  try {
+    registerTailnetInternalRoutes(api);
+  } catch (error) {
+    safetySnapshot = recordPluginFailure(
+      "STARTUP_INTERNAL_ROUTES_FAILED",
+      errorMessage4(error),
+      "Fix route registration errors and run squad.plugin.recover."
+    );
+    console.warn(`[squad-openclaw] internal route registration failed: ${errorMessage4(error)}`);
+  }
+  safetySnapshot = getPluginSafetySnapshot();
+  if (isPluginExecutionBlocked(safetySnapshot)) {
+    console.warn(
+      `[squad-openclaw] plugin features disabled (${safetySnapshot.state}). ${safetySnapshot.reasonMessage ?? "No reason provided."}`
+    );
+    return;
+  }
   try {
     sharedApi = registerSquadSharedApi(api);
   } catch (error) {
-    console.warn(`[squad-openclaw] shared API registration failed: ${errorMessage3(error)}`);
+    safetySnapshot = recordPluginFailure(
+      "STARTUP_SHARED_API_FAILED",
+      errorMessage4(error),
+      "Fix shared API registration errors and run squad.plugin.recover."
+    );
+    console.warn(`[squad-openclaw] shared API registration failed: ${errorMessage4(error)}`);
   }
-  if (sharedApi) {
-    try {
-      sharedApi.registerCoreGatewayMethods();
-    } catch (error) {
-      console.warn(`[squad-openclaw] core gateway method registration failed: ${errorMessage3(error)}`);
-    }
+  if (!sharedApi || isPluginExecutionBlocked(safetySnapshot)) {
+    return;
   }
   try {
-    registerTailnetInternalRoutes(api);
+    sharedApi.registerCoreGatewayMethods();
   } catch (error) {
-    console.warn(`[squad-openclaw] internal route registration failed: ${errorMessage3(error)}`);
+    safetySnapshot = recordPluginFailure(
+      "STARTUP_GATEWAY_METHODS_FAILED",
+      errorMessage4(error),
+      "Fix gateway method registration errors and run squad.plugin.recover."
+    );
+    console.warn(`[squad-openclaw] core gateway method registration failed: ${errorMessage4(error)}`);
+  }
+  if (isPluginExecutionBlocked(safetySnapshot)) {
+    return;
   }
   void withTimeout(runStartupMigrations(api), STARTUP_MIGRATIONS_TIMEOUT_MS, "startup migrations").catch((error) => {
+    const errorId = error instanceof TimeoutError ? "STARTUP_MIGRATIONS_TIMEOUT" : "STARTUP_MIGRATIONS_FAILED";
+    const snapshot = recordPluginFailure(
+      errorId,
+      errorMessage4(error),
+      "Inspect startup migration logs and run squad.plugin.recover after fixing migration failures."
+    );
     if (error instanceof TimeoutError) {
       console.warn(`[squad-openclaw] startup migrations timed out after ${STARTUP_MIGRATIONS_TIMEOUT_MS}ms`);
-      return;
+    } else {
+      console.warn(`[squad-openclaw] startup migrations failed: ${errorMessage4(error)}`);
+    }
+    if (snapshot.blocked) {
+      console.warn(
+        `[squad-openclaw] plugin moved to ${snapshot.state} after startup migration failure (${snapshot.reasonCode ?? "NO_REASON"})`
+      );
     }
-    console.warn(`[squad-openclaw] startup migrations failed: ${errorMessage3(error)}`);
   });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-openclaw",
-  "version": "2026.2.2703",
+  "version": "2026.2.2704",
   "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
   "type": "module",
   "main": "./dist/index.js",