@slaw-ai/server 2026.611.0

package/dist/services/plugin-host-services.js

@@ -0,0 +1,2460 @@
+import { activityLog, agentTaskSessions as agentTaskSessionsTable, agents as agentsTable, budgetIncidents, costEvents, heartbeatRuns, invites, issues as issuesTable, pluginLogs, principalPermissionGrants, projects as projectsTable, } from "@slaw-ai/db";
+import { eq, and, like, desc, inArray, sql, isNull, isNotNull, gt, lte } from "drizzle-orm";
+import { pluginOperationIssueOriginKind } from "@slaw-ai/shared";
+import { squadService } from "./squads.js";
+import { agentService } from "./agents.js";
+import { projectService } from "./projects.js";
+import { executionWorkspaceService } from "./execution-workspaces.js";
+import { issueService } from "./issues.js";
+import { issueThreadInteractionService } from "./issue-thread-interactions.js";
+import { goalService } from "./goals.js";
+import { documentService } from "./documents.js";
+import { heartbeatService } from "./heartbeat.js";
+import { budgetService } from "./budgets.js";
+import { issueApprovalService } from "./issue-approvals.js";
+import { subscribeSquadLiveEvents } from "./live-events.js";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import path from "node:path";
+import { pluginRegistryService } from "./plugin-registry.js";
+import { pluginStateStore } from "./plugin-state-store.js";
+import { pluginDatabaseService } from "./plugin-database.js";
+import { pluginManagedAgentService } from "./plugin-managed-agents.js";
+import { pluginManagedRoutineService } from "./plugin-managed-routines.js";
+import { pluginManagedSkillService } from "./plugin-managed-skills.js";
+import { assertConfiguredLocalFolder, assertWritableConfiguredLocalFolder, getStoredLocalFolders, deletePluginLocalFolderFile, inspectPluginLocalFolder, listPluginLocalFolderEntries, preparePluginLocalFolder, readPluginLocalFolderText, requireLocalFolderDeclaration, setStoredLocalFolder, writePluginLocalFolderTextAtomic, } from "./plugin-local-folders.js";
+import { createPluginSecretsHandler } from "./plugin-secrets-handler.js";
+import { logActivity } from "./activity-log.js";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import { logger } from "../middleware/logger.js";
+import { accessService } from "./access.js";
+import { authorizationService } from "./authorization.js";
+import { sanitizeRecord } from "../redaction.js";
+// ---------------------------------------------------------------------------
+// SSRF protection for plugin HTTP fetch
+// ---------------------------------------------------------------------------
+/** Maximum time (ms) a plugin fetch request may take before being aborted. */
+const PLUGIN_FETCH_TIMEOUT_MS = 30_000;
+/** Maximum time (ms) to wait for a DNS lookup before aborting. */
+const DNS_LOOKUP_TIMEOUT_MS = 5_000;
+/** Only these protocols are allowed for plugin HTTP requests. */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+/**
+ * Check if an IP address is in a private/reserved range (RFC 1918, loopback,
+ * link-local, etc.) that plugins should never be able to reach.
+ *
+ * Handles IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1) which Node's
+ * dns.lookup may return depending on OS configuration.
+ */
+function isPrivateIP(ip) {
+    const lower = ip.toLowerCase();
+    // Unwrap IPv4-mapped IPv6 addresses (::ffff:x.x.x.x) and re-check as IPv4
+    const v4MappedMatch = lower.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (v4MappedMatch && v4MappedMatch[1])
+        return isPrivateIP(v4MappedMatch[1]);
+    // IPv4 patterns
+    if (ip.startsWith("10."))
+        return true;
+    if (ip.startsWith("172.")) {
+        const second = parseInt(ip.split(".")[1], 10);
+        if (second >= 16 && second <= 31)
+            return true;
+    }
+    if (ip.startsWith("192.168."))
+        return true;
+    if (ip.startsWith("127."))
+        return true; // loopback
+    if (ip.startsWith("169.254."))
+        return true; // link-local
+    if (ip === "0.0.0.0")
+        return true;
+    // IPv6 patterns
+    if (lower === "::1")
+        return true; // loopback
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true; // ULA
+    if (lower.startsWith("fe80"))
+        return true; // link-local
+    if (lower === "::")
+        return true;
+    return false;
+}
+async function validateAndResolveFetchUrl(urlString) {
+    let parsed;
+    try {
+        parsed = new URL(urlString);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${urlString}`);
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`Disallowed protocol "${parsed.protocol}" — only http: and https: are permitted`);
+    }
+    // Resolve the hostname to an IP and check for private ranges.
+    // We pin the resolved IP into the URL to eliminate the TOCTOU window
+    // between DNS resolution here and the second resolution fetch() would do.
+    const originalHostname = parsed.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    const hostHeader = parsed.host; // includes port if non-default
+    // Race the DNS lookup against a timeout to prevent indefinite hangs
+    // when DNS is misconfigured or unresponsive.
+    const dnsPromise = dnsLookup(originalHostname, { all: true });
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`DNS lookup timed out after ${DNS_LOOKUP_TIMEOUT_MS}ms for ${originalHostname}`)), DNS_LOOKUP_TIMEOUT_MS);
+    });
+    try {
+        const results = await Promise.race([dnsPromise, timeoutPromise]);
+        if (results.length === 0) {
+            throw new Error(`DNS resolution returned no results for ${originalHostname}`);
+        }
+        // Filter to only non-private IPs instead of rejecting the entire request
+        // when some IPs are private. This handles multi-homed hosts that resolve
+        // to both private and public addresses.
+        const safeResults = results.filter((entry) => !isPrivateIP(entry.address));
+        if (safeResults.length === 0) {
+            throw new Error(`All resolved IPs for ${originalHostname} are in private/reserved ranges`);
+        }
+        const resolved = safeResults[0];
+        return {
+            parsedUrl: parsed,
+            resolvedAddress: resolved.address,
+            hostHeader,
+            tlsServername: parsed.protocol === "https:" && isIP(originalHostname) === 0
+                ? originalHostname
+                : undefined,
+            useTls: parsed.protocol === "https:",
+        };
+    }
+    catch (err) {
+        // Re-throw our own errors; wrap DNS failures
+        if (err instanceof Error && (err.message.startsWith("All resolved IPs") ||
+            err.message.startsWith("DNS resolution returned") ||
+            err.message.startsWith("DNS lookup timed out")))
+            throw err;
+        throw new Error(`DNS resolution failed for ${originalHostname}: ${err.message}`);
+    }
+}
+function buildPinnedRequestOptions(target, init) {
+    const headers = new Headers(init?.headers);
+    const method = init?.method ?? "GET";
+    const body = init?.body === undefined || init?.body === null
+        ? undefined
+        : typeof init.body === "string"
+            ? init.body
+            : String(init.body);
+    headers.set("Host", target.hostHeader);
+    if (body !== undefined && !headers.has("content-length") && !headers.has("transfer-encoding")) {
+        headers.set("content-length", String(Buffer.byteLength(body)));
+    }
+    const pathname = `${target.parsedUrl.pathname}${target.parsedUrl.search}`;
+    const auth = target.parsedUrl.username || target.parsedUrl.password
+        ? `${decodeURIComponent(target.parsedUrl.username)}:${decodeURIComponent(target.parsedUrl.password)}`
+        : undefined;
+    return {
+        options: {
+            protocol: target.parsedUrl.protocol,
+            host: target.resolvedAddress,
+            port: target.parsedUrl.port
+                ? Number(target.parsedUrl.port)
+                : target.useTls
+                    ? 443
+                    : 80,
+            path: pathname,
+            method,
+            headers: Object.fromEntries(headers.entries()),
+            auth,
+            servername: target.tlsServername,
+        },
+        body,
+    };
+}
+async function executePinnedHttpRequest(target, init, signal) {
+    const { options, body } = buildPinnedRequestOptions(target, init);
+    const response = await new Promise((resolve, reject) => {
+        const requestFn = target.useTls ? httpsRequest : httpRequest;
+        const req = requestFn({ ...options, signal }, resolve);
+        req.on("error", reject);
+        if (body !== undefined) {
+            req.write(body);
+        }
+        req.end();
+    });
+    const MAX_RESPONSE_BODY_BYTES = 200 * 1024 * 1024; // 200 MB
+    const chunks = [];
+    let totalBytes = 0;
+    await new Promise((resolve, reject) => {
+        response.on("data", (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buf.length;
+            if (totalBytes > MAX_RESPONSE_BODY_BYTES) {
+                chunks.length = 0;
+                response.destroy(new Error(`Response body exceeded ${MAX_RESPONSE_BODY_BYTES} bytes`));
+                return;
+            }
+            chunks.push(buf);
+        });
+        response.on("end", resolve);
+        response.on("error", reject);
+    });
+    const headers = {};
+    for (const [key, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value)) {
+            headers[key] = value.join(", ");
+        }
+        else if (value !== undefined) {
+            headers[key] = value;
+        }
+    }
+    return {
+        status: response.statusCode ?? 500,
+        statusText: response.statusMessage ?? "",
+        headers,
+        body: Buffer.concat(chunks).toString("utf8"),
+    };
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PATH_LIKE_PATTERN = /[\\/]/;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
+function looksLikePath(value) {
+    const normalized = value.trim();
+    return (PATH_LIKE_PATTERN.test(normalized)
+        || WINDOWS_DRIVE_PATH_PATTERN.test(normalized)) && !UUID_PATTERN.test(normalized);
+}
+function sanitizeWorkspaceText(value) {
+    const trimmed = value.trim();
+    if (!trimmed || UUID_PATTERN.test(trimmed))
+        return "";
+    return trimmed;
+}
+function sanitizeWorkspacePath(cwd) {
+    if (!cwd)
+        return "";
+    return looksLikePath(cwd) ? cwd.trim() : "";
+}
+function sanitizeWorkspaceName(name, fallbackPath) {
+    const safeName = sanitizeWorkspaceText(name);
+    if (safeName && !looksLikePath(safeName)) {
+        return safeName;
+    }
+    const normalized = fallbackPath.trim().replace(/[\\/]+$/, "");
+    const segments = normalized.split(/[\\/]/).filter(Boolean);
+    return segments[segments.length - 1] ?? "Workspace";
+}
+// ---------------------------------------------------------------------------
+// Buffered plugin log writes
+// ---------------------------------------------------------------------------
+/** How many buffered log entries trigger an immediate flush. */
+const LOG_BUFFER_FLUSH_SIZE = 100;
+/** How often (ms) the buffer is flushed regardless of size. */
+const LOG_BUFFER_FLUSH_INTERVAL_MS = 5_000;
+/** Max length for a single plugin log message (bytes/chars). */
+const MAX_LOG_MESSAGE_LENGTH = 10_000;
+/** Max serialised JSON size for plugin log meta objects. */
+const MAX_LOG_META_JSON_LENGTH = 50_000;
+/** Max length for a metric name. */
+const MAX_METRIC_NAME_LENGTH = 500;
+/** Pino reserved field names that plugins must not overwrite. */
+const PINO_RESERVED_KEYS = new Set([
+    "level",
+    "time",
+    "pid",
+    "hostname",
+    "msg",
+    "v",
+]);
+/** Truncate a string to `max` characters, appending a marker if truncated. */
+function truncStr(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + "...[truncated]";
+}
+/** Sanitise a plugin-supplied meta object: enforce size limit and strip reserved keys. */
+function sanitiseMeta(meta) {
+    if (meta == null)
+        return null;
+    // Strip pino reserved keys
+    const cleaned = {};
+    for (const [k, v] of Object.entries(meta)) {
+        if (!PINO_RESERVED_KEYS.has(k)) {
+            cleaned[k] = v;
+        }
+    }
+    // Enforce total serialised size
+    let json;
+    try {
+        json = JSON.stringify(cleaned);
+    }
+    catch {
+        return { _sanitised: true, _error: "meta was not JSON-serialisable" };
+    }
+    if (json.length > MAX_LOG_META_JSON_LENGTH) {
+        return { _sanitised: true, _error: `meta exceeded ${MAX_LOG_META_JSON_LENGTH} chars` };
+    }
+    return cleaned;
+}
+const _logBuffer = [];
+/**
+ * Flush all buffered log entries to the database in a single batch insert per
+ * unique db instance. Errors are swallowed with a console.error fallback so
+ * flushing never crashes the process.
+ */
+export async function flushPluginLogBuffer() {
+    if (_logBuffer.length === 0)
+        return;
+    // Drain the buffer atomically so concurrent flushes don't double-insert.
+    const entries = _logBuffer.splice(0, _logBuffer.length);
+    // Group entries by db identity so multi-db scenarios are handled correctly.
+    const byDb = new Map();
+    for (const entry of entries) {
+        const group = byDb.get(entry.db);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            byDb.set(entry.db, [entry]);
+        }
+    }
+    for (const [dbInstance, group] of byDb) {
+        const values = group.map((e) => ({
+            pluginId: e.pluginId,
+            level: e.level,
+            message: e.message,
+            meta: e.meta,
+        }));
+        try {
+            await dbInstance.insert(pluginLogs).values(values);
+        }
+        catch (err) {
+            try {
+                logger.warn({ err, count: values.length }, "Failed to batch-persist plugin logs to DB");
+            }
+            catch {
+                console.error("[plugin-host-services] Batch log flush failed:", err);
+            }
+        }
+    }
+}
+/** Interval handle for the periodic log flush. */
+const _logFlushInterval = setInterval(() => {
+    flushPluginLogBuffer().catch((err) => {
+        console.error("[plugin-host-services] Periodic log flush error:", err);
+    });
+}, LOG_BUFFER_FLUSH_INTERVAL_MS);
+// Allow the interval to be unref'd so it doesn't keep the process alive in tests.
+if (_logFlushInterval.unref)
+    _logFlushInterval.unref();
+/**
+ * buildHostServices — creates a concrete implementation of the `HostServices`
+ * interface for a specific plugin.
+ *
+ * This implementation delegates to the core Slaw domain services,
+ * providing the bridge between the plugin worker's SDK and the host platform.
+ *
+ * @param db - Database connection instance.
+ * @param pluginId - The UUID of the plugin installation record.
+ * @param pluginKey - The unique identifier from the plugin manifest (e.g., "acme.linear").
+ * @param eventBus - The system-wide event bus for publishing plugin events.
+ * @returns An object implementing the HostServices interface for the plugin SDK.
+ */
+/** Maximum time (ms) to keep a session event subscription alive before forcing cleanup. */
+const SESSION_EVENT_SUBSCRIPTION_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
+export function buildHostServices(db, pluginId, pluginKey, eventBus, notifyWorker, options = {}) {
+    const registry = pluginRegistryService(db);
+    const stateStore = pluginStateStore(db);
+    const pluginDb = pluginDatabaseService(db);
+    const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+    const squads = squadService(db);
+    const agents = agentService(db);
+    const managedAgents = pluginManagedAgentService(db, {
+        pluginId,
+        pluginKey,
+        manifest: options.manifest,
+        instructionTemplateVariables: async (squadId) => {
+            const variables = {};
+            for (const declaration of options.manifest?.localFolders ?? []) {
+                const status = await inspectPluginLocalFolder({
+                    folderKey: declaration.folderKey,
+                    declaration,
+                    storedConfig: await getStoredLocalFolderConfig(squadId, declaration.folderKey),
+                });
+                const prefix = `localFolders.${declaration.folderKey}`;
+                variables[`${prefix}.path`] = status.realPath ?? status.path ?? null;
+                variables[`${prefix}.agentsPath`] = status.realPath ? path.join(status.realPath, "AGENTS.md") : null;
+            }
+            return variables;
+        },
+    });
+    const managedRoutines = pluginManagedRoutineService(db, {
+        pluginId,
+        pluginKey,
+        manifest: options.manifest,
+        pluginWorkerManager: options.pluginWorkerManager,
+    });
+    const managedSkills = pluginManagedSkillService(db, {
+        pluginId,
+        pluginKey,
+        manifest: options.manifest,
+    });
+    const heartbeat = heartbeatService(db, {
+        pluginWorkerManager: options.pluginWorkerManager,
+    });
+    const projects = projectService(db);
+    const executionWorkspaces = executionWorkspaceService(db);
+    const issues = issueService(db);
+    const documents = documentService(db);
+    const goals = goalService(db);
+    const access = accessService(db);
+    const authorization = authorizationService(db);
+    const budgets = budgetService(db);
+    const issueApprovals = issueApprovalService(db);
+    const scopedBus = eventBus.forPlugin(pluginKey);
+    // Track active session event subscriptions for cleanup
+    const activeSubscriptions = new Set();
+    let disposed = false;
+    const ensureSquadId = (squadId) => {
+        if (!squadId)
+            throw new Error("squadId is required for this operation");
+        return squadId;
+    };
+    const parseWindowValue = (value) => {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return Math.max(0, Math.floor(value));
+        }
+        if (typeof value === "string" && value.trim().length > 0) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed)) {
+                return Math.max(0, Math.floor(parsed));
+            }
+        }
+        return null;
+    };
+    const applyWindow = (rows, params) => {
+        const offset = parseWindowValue(params?.offset) ?? 0;
+        const limit = parseWindowValue(params?.limit);
+        if (limit == null)
+            return rows.slice(offset);
+        return rows.slice(offset, offset + limit);
+    };
+    const authorizationAuditDecisionCondition = (decisionFilter) => {
+        const conditions = [
+            sql `lower(${activityLog.details}->>'decision') = ${decisionFilter}`,
+            decisionFilter === "allow" ? sql `left(coalesce(${activityLog.details}->>'reason', ''), 6) = 'allow_'` : undefined,
+            decisionFilter === "deny" ? sql `left(coalesce(${activityLog.details}->>'reason', ''), 5) = 'deny_'` : undefined,
+            decisionFilter === "allow" ? sql `${activityLog.details}->>'allowed' = 'true'` : undefined,
+            decisionFilter === "deny" ? sql `${activityLog.details}->>'allowed' = 'false'` : undefined,
+        ].filter((condition) => Boolean(condition));
+        return sql `(${sql.join(conditions, sql ` OR `)})`;
+    };
+    /**
+     * Plugins are instance-wide in the current runtime. Squad IDs are still
+     * required for squad-scoped data access, but there is no per-squad
+     * availability gate to enforce here.
+     */
+    const ensurePluginAvailableForSquad = async (_squadId) => { };
+    const getLocalFolderDeclaration = (folderKey) => requireLocalFolderDeclaration(options.manifest?.localFolders, folderKey);
+    const getStoredLocalFolderConfig = async (squadId, folderKey) => {
+        ensureSquadId(squadId);
+        await ensurePluginAvailableForSquad(squadId);
+        const settings = await registry.getSquadSettings(pluginId, squadId);
+        return getStoredLocalFolders(settings?.settingsJson)[folderKey] ?? null;
+    };
+    const inspectStoredLocalFolder = async (squadId, folderKey) => inspectPluginLocalFolder({
+        folderKey,
+        declaration: getLocalFolderDeclaration(folderKey),
+        storedConfig: await getStoredLocalFolderConfig(squadId, folderKey),
+    });
+    const inSquad = (record, squadId) => Boolean(record && record.squadId === squadId);
+    const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+    const readProviderMetadata = (metadata) => {
+        if (!isRecord(metadata))
+            return null;
+        if (isRecord(metadata.providerMetadata))
+            return { ...metadata.providerMetadata };
+        const rebuild = metadata.rebuild;
+        if (!isRecord(rebuild))
+            return null;
+        const rebuildMetadata = rebuild.metadata;
+        if (!isRecord(rebuildMetadata) || !isRecord(rebuildMetadata.providerMetadata))
+            return null;
+        return { ...rebuildMetadata.providerMetadata };
+    };
+    const toPluginExecutionWorkspaceMetadata = (workspace) => ({
+        id: workspace.id,
+        squadId: workspace.squadId,
+        projectId: workspace.projectId,
+        projectWorkspaceId: workspace.projectWorkspaceId,
+        path: workspace.cwd ?? workspace.providerRef,
+        cwd: workspace.cwd,
+        repoUrl: workspace.repoUrl,
+        baseRef: workspace.baseRef,
+        branchName: workspace.branchName,
+        providerType: workspace.providerType,
+        providerMetadata: readProviderMetadata(workspace.metadata),
+    });
+    const requireInSquad = (entityName, record, squadId) => {
+        if (!inSquad(record, squadId)) {
+            throw new Error(`${entityName} not found`);
+        }
+        return record;
+    };
+    const pluginActivityDetails = (details, actor) => {
+        const initiatingActorType = actor?.actorAgentId ? "agent" : actor?.actorUserId ? "user" : null;
+        const initiatingActorId = actor?.actorAgentId ?? actor?.actorUserId ?? null;
+        return {
+            ...(details ?? {}),
+            sourcePluginId: pluginId,
+            sourcePluginKey: pluginKey,
+            initiatingActorType,
+            initiatingActorId,
+            initiatingAgentId: actor?.actorAgentId ?? null,
+            initiatingUserId: actor?.actorUserId ?? null,
+            initiatingRunId: actor?.actorRunId ?? null,
+            pluginId,
+            pluginKey,
+        };
+    };
+    const defaultPluginOriginKind = `plugin:${pluginKey}`;
+    const normalizePluginOriginKind = (originKind = defaultPluginOriginKind) => {
+        if (originKind == null || originKind === "")
+            return defaultPluginOriginKind;
+        if (typeof originKind !== "string") {
+            throw new Error("Plugin issue originKind must be a string");
+        }
+        if (originKind === defaultPluginOriginKind || originKind.startsWith(`${defaultPluginOriginKind}:`)) {
+            return originKind;
+        }
+        throw new Error(`Plugin may only use originKind values under ${defaultPluginOriginKind}`);
+    };
+    const assertReadableOriginFilter = (originKind) => {
+        if (typeof originKind !== "string" || !originKind.startsWith("plugin:"))
+            return;
+        normalizePluginOriginKind(originKind);
+    };
+    const logPluginActivity = async (input) => {
+        await logActivity(db, {
+            squadId: input.squadId,
+            actorType: "plugin",
+            actorId: pluginId,
+            agentId: input.actor?.actorAgentId ?? null,
+            runId: input.actor?.actorRunId ?? null,
+            action: input.action,
+            entityType: input.entityType,
+            entityId: input.entityId,
+            details: pluginActivityDetails(input.details, input.actor),
+        });
+    };
+    const collectIssueSubtreeIds = async (squadId, rootIssueId) => {
+        const seen = new Set([rootIssueId]);
+        let frontier = [rootIssueId];
+        while (frontier.length > 0) {
+            const children = await db
+                .select({ id: issuesTable.id })
+                .from(issuesTable)
+                .where(and(eq(issuesTable.squadId, squadId), inArray(issuesTable.parentId, frontier)));
+            frontier = children.map((child) => child.id).filter((id) => !seen.has(id));
+            for (const id of frontier)
+                seen.add(id);
+        }
+        return [...seen];
+    };
+    const getIssueRunSummaries = async (squadId, issueIds, options = {}) => {
+        if (issueIds.length === 0)
+            return [];
+        const issueIdExpr = sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`;
+        const statusCondition = options.activeOnly
+            ? inArray(heartbeatRuns.status, ["queued", "running"])
+            : undefined;
+        const rows = await db
+            .select({
+            id: heartbeatRuns.id,
+            issueId: issueIdExpr,
+            agentId: heartbeatRuns.agentId,
+            status: heartbeatRuns.status,
+            invocationSource: heartbeatRuns.invocationSource,
+            triggerDetail: heartbeatRuns.triggerDetail,
+            startedAt: heartbeatRuns.startedAt,
+            finishedAt: heartbeatRuns.finishedAt,
+            error: heartbeatRuns.error,
+            createdAt: heartbeatRuns.createdAt,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.squadId, squadId), inArray(issueIdExpr, issueIds), statusCondition))
+            .orderBy(desc(heartbeatRuns.createdAt))
+            .limit(100);
+        return rows.map((row) => ({
+            ...row,
+            startedAt: row.startedAt?.toISOString() ?? null,
+            finishedAt: row.finishedAt?.toISOString() ?? null,
+            createdAt: row.createdAt.toISOString(),
+        }));
+    };
+    const setBlockedByWithActivity = async (params) => {
+        const existing = requireInSquad("Issue", await issues.getById(params.issueId), params.squadId);
+        const previous = await issues.getRelationSummaries(params.issueId);
+        await issues.update(params.issueId, {
+            blockedByIssueIds: params.blockedByIssueIds,
+            actorAgentId: params.actorAgentId ?? null,
+            actorUserId: params.actorUserId ?? null,
+        });
+        const relations = await issues.getRelationSummaries(params.issueId);
+        await logPluginActivity({
+            squadId: params.squadId,
+            action: "issue.relations.updated",
+            entityType: "issue",
+            entityId: params.issueId,
+            actor: {
+                actorAgentId: params.actorAgentId,
+                actorUserId: params.actorUserId,
+                actorRunId: params.actorRunId,
+            },
+            details: {
+                identifier: existing.identifier,
+                mutation: params.mutation,
+                blockedByIssueIds: params.blockedByIssueIds,
+                previousBlockedByIssueIds: previous.blockedBy.map((relation) => relation.id),
+            },
+        });
+        return relations;
+    };
+    const getIssueCostSummary = async (squadId, issueIds, billingCode) => {
+        const scopeConditions = [
+            issueIds.length > 0 ? inArray(costEvents.issueId, issueIds) : undefined,
+            billingCode ? eq(costEvents.billingCode, billingCode) : undefined,
+        ].filter((condition) => Boolean(condition));
+        if (scopeConditions.length === 0) {
+            return {
+                costCents: 0,
+                inputTokens: 0,
+                cachedInputTokens: 0,
+                outputTokens: 0,
+                billingCode: billingCode ?? null,
+            };
+        }
+        const scopeCondition = scopeConditions.length === 1 ? scopeConditions[0] : and(...scopeConditions);
+        const [row] = await db
+            .select({
+            costCents: sql `coalesce(sum(${costEvents.costCents}), 0)::double precision`,
+            inputTokens: sql `coalesce(sum(${costEvents.inputTokens}), 0)::double precision`,
+            cachedInputTokens: sql `coalesce(sum(${costEvents.cachedInputTokens}), 0)::double precision`,
+            outputTokens: sql `coalesce(sum(${costEvents.outputTokens}), 0)::double precision`,
+        })
+            .from(costEvents)
+            .where(and(eq(costEvents.squadId, squadId), scopeCondition));
+        return {
+            costCents: Number(row?.costCents ?? 0),
+            inputTokens: Number(row?.inputTokens ?? 0),
+            cachedInputTokens: Number(row?.cachedInputTokens ?? 0),
+            outputTokens: Number(row?.outputTokens ?? 0),
+            billingCode: billingCode ?? null,
+        };
+    };
+    const getOpenBudgetIncidents = async (squadId) => {
+        const rows = await db
+            .select({
+            id: budgetIncidents.id,
+            scopeType: budgetIncidents.scopeType,
+            scopeId: budgetIncidents.scopeId,
+            metric: budgetIncidents.metric,
+            windowKind: budgetIncidents.windowKind,
+            thresholdType: budgetIncidents.thresholdType,
+            amountLimit: budgetIncidents.amountLimit,
+            amountObserved: budgetIncidents.amountObserved,
+            status: budgetIncidents.status,
+            approvalId: budgetIncidents.approvalId,
+            createdAt: budgetIncidents.createdAt,
+        })
+            .from(budgetIncidents)
+            .where(and(eq(budgetIncidents.squadId, squadId), eq(budgetIncidents.status, "open")))
+            .orderBy(desc(budgetIncidents.createdAt));
+        return rows.map((row) => ({
+            ...row,
+            createdAt: row.createdAt.toISOString(),
+        }));
+    };
+    const INVITE_TOKEN_PREFIX = "pcp_invite_";
+    const INVITE_TOKEN_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const INVITE_TOKEN_SUFFIX_LENGTH = 8;
+    const INVITE_TOKEN_MAX_RETRIES = 5;
+    const SQUAD_INVITE_TTL_MS = 72 * 60 * 60 * 1000;
+    const hashToken = (token) => createHash("sha256").update(token).digest("hex");
+    const createInviteToken = () => {
+        const bytes = randomBytes(INVITE_TOKEN_SUFFIX_LENGTH);
+        let suffix = "";
+        for (let idx = 0; idx < INVITE_TOKEN_SUFFIX_LENGTH; idx += 1) {
+            suffix += INVITE_TOKEN_ALPHABET[bytes[idx] % INVITE_TOKEN_ALPHABET.length];
+        }
+        return `${INVITE_TOKEN_PREFIX}${suffix}`;
+    };
+    const isInviteTokenHashCollisionError = (error) => {
+        const candidates = [
+            error,
+            error?.cause ?? null,
+        ];
+        for (const candidate of candidates) {
+            if (!candidate || typeof candidate !== "object")
+                continue;
+            const code = "code" in candidate && typeof candidate.code === "string" ? candidate.code : null;
+            const message = "message" in candidate && typeof candidate.message === "string" ? candidate.message : "";
+            const constraint = "constraint" in candidate && typeof candidate.constraint === "string" ? candidate.constraint : null;
+            if (code !== "23505")
+                continue;
+            if (constraint === "invites_token_hash_unique_idx")
+                return true;
+            if (message.includes("invites_token_hash_unique_idx"))
+                return true;
+        }
+        return false;
+    };
+    const inviteState = (invite) => {
+        if (invite.revokedAt)
+            return "revoked";
+        if (invite.acceptedAt)
+            return "accepted";
+        if (invite.expiresAt <= new Date())
+            return "expired";
+        return "active";
+    };
+    const redactInvite = (invite) => {
+        const { tokenHash: _tokenHash, defaultsPayload, ...safeInvite } = invite;
+        return {
+            ...safeInvite,
+            allowedJoinTypes: safeInvite.allowedJoinTypes,
+            defaultsPayload: defaultsPayload && typeof defaultsPayload === "object"
+                ? sanitizeRecord(defaultsPayload)
+                : defaultsPayload ?? null,
+            state: inviteState(invite),
+        };
+    };
+    const inviteStateWhereClause = (state) => {
+        const now = new Date();
+        switch (state) {
+            case "active":
+                return and(isNull(invites.revokedAt), isNull(invites.acceptedAt), gt(invites.expiresAt, now));
+            case "accepted":
+                return isNotNull(invites.acceptedAt);
+            case "expired":
+                return and(isNull(invites.revokedAt), isNull(invites.acceptedAt), lte(invites.expiresAt, now));
+            case "revoked":
+                return isNotNull(invites.revokedAt);
+            default:
+                return undefined;
+        }
+    };
+    const mergeInviteDefaults = (defaultsPayload, agentMessage, humanRole) => {
+        const defaults = defaultsPayload && typeof defaultsPayload === "object"
+            ? { ...defaultsPayload }
+            : {};
+        if (humanRole) {
+            defaults.human = {
+                ...(typeof defaults.human === "object" && defaults.human !== null ? defaults.human : {}),
+                role: humanRole,
+            };
+        }
+        if (agentMessage) {
+            defaults.agent = {
+                ...(typeof defaults.agent === "object" && defaults.agent !== null ? defaults.agent : {}),
+                message: agentMessage,
+            };
+        }
+        return sanitizeRecord(defaults);
+    };
+    const redactGrant = (grant) => ({
+        ...grant,
+        principalType: grant.principalType,
+        permissionKey: grant.permissionKey,
+        scope: grant.scope && typeof grant.scope === "object" ? sanitizeRecord(grant.scope) : grant.scope ?? null,
+    });
+    const loadPluginMember = async (squadId, memberId) => {
+        const member = await access.getMemberById(squadId, memberId);
+        if (!member)
+            return null;
+        const grants = await access.listPrincipalGrants(squadId, member.principalType, member.principalId);
+        return {
+            ...member,
+            principalType: member.principalType,
+            status: member.status,
+            grants: grants.map(redactGrant),
+        };
+    };
+    const pluginAssignmentActor = (actor) => {
+        if (actor.type === "agent") {
+            return {
+                type: "agent",
+                agentId: actor.agentId ?? null,
+                squadId: actor.squadId ?? null,
+                source: "agent_key",
+            };
+        }
+        return {
+            type: "operator",
+            userId: actor.userId ?? null,
+            squadIds: Array.isArray(actor.squadIds) ? actor.squadIds : [],
+            source: "session",
+        };
+    };
+    const policyPathForResource = (resourceType) => {
+        switch (resourceType) {
+            case "agent":
+                return { table: "agent" };
+            case "project":
+                return { table: "project" };
+            case "issue":
+                return { table: "issue" };
+            case "squad":
+                return { table: "squad" };
+        }
+    };
+    const readAuthorizationPolicy = async (squadId, resourceType, resourceId) => {
+        const pathInfo = policyPathForResource(resourceType);
+        if (pathInfo.table === "agent") {
+            const agent = await agents.getById(resourceId);
+            if (!inSquad(agent, squadId))
+                return null;
+            const permissions = agent.permissions && typeof agent.permissions === "object" ? agent.permissions : {};
+            return {
+                resourceType,
+                resourceId,
+                squadId,
+                policy: permissions.authorizationPolicy && typeof permissions.authorizationPolicy === "object"
+                    ? sanitizeRecord(permissions.authorizationPolicy)
+                    : null,
+                updatedAt: agent.updatedAt,
+            };
+        }
+        if (pathInfo.table === "project") {
+            const project = await projects.getById(resourceId);
+            if (!inSquad(project, squadId))
+                return null;
+            const policy = project.executionWorkspacePolicy && typeof project.executionWorkspacePolicy === "object"
+                ? project.executionWorkspacePolicy.authorizationPolicy
+                : null;
+            return {
+                resourceType,
+                resourceId,
+                squadId,
+                policy: policy && typeof policy === "object" ? sanitizeRecord(policy) : null,
+                updatedAt: project.updatedAt,
+            };
+        }
+        if (pathInfo.table === "issue") {
+            const issue = await issues.getById(resourceId);
+            if (!inSquad(issue, squadId))
+                return null;
+            const policy = issue.executionPolicy && typeof issue.executionPolicy === "object"
+                ? issue.executionPolicy.authorizationPolicy
+                : null;
+            return {
+                resourceType,
+                resourceId,
+                squadId,
+                policy: policy && typeof policy === "object" ? sanitizeRecord(policy) : null,
+                updatedAt: issue.updatedAt,
+            };
+        }
+        const squad = await squads.getById(resourceId);
+        if (!squad || squad.id !== squadId)
+            return null;
+        return { resourceType, resourceId, squadId, policy: null, updatedAt: squad.updatedAt };
+    };
+    return {
+        config: {
+            async get() {
+                const configRow = await registry.getConfig(pluginId);
+                return configRow?.configJson ?? {};
+            },
+        },
+        localFolders: {
+            async declarations() {
+                return options.manifest?.localFolders ?? [];
+            },
+            async configure(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const declaration = getLocalFolderDeclaration(params.folderKey);
+                const existing = await registry.getSquadSettings(pluginId, squadId);
+                const existingConfig = getStoredLocalFolders(existing?.settingsJson)[params.folderKey] ?? null;
+                await preparePluginLocalFolder({
+                    folderKey: params.folderKey,
+                    declaration,
+                    storedConfig: existingConfig,
+                    overrideConfig: {
+                        path: params.path,
+                    },
+                });
+                const status = await inspectPluginLocalFolder({
+                    folderKey: params.folderKey,
+                    declaration,
+                    storedConfig: existingConfig,
+                    overrideConfig: {
+                        path: params.path,
+                    },
+                });
+                const nextSettings = setStoredLocalFolder(existing?.settingsJson, params.folderKey, {
+                    path: params.path,
+                    access: status.access,
+                    requiredDirectories: status.requiredDirectories,
+                    requiredFiles: status.requiredFiles,
+                });
+                await registry.upsertSquadSettings(pluginId, squadId, {
+                    enabled: existing?.enabled ?? true,
+                    settingsJson: nextSettings,
+                    lastError: status.healthy ? null : status.problems.map((item) => item.message).join("; "),
+                });
+                return status;
+            },
+            async status(params) {
+                return inspectStoredLocalFolder(params.squadId, params.folderKey);
+            },
+            async list(params) {
+                const status = await inspectStoredLocalFolder(params.squadId, params.folderKey);
+                assertConfiguredLocalFolder(status);
+                const listing = await listPluginLocalFolderEntries(status.realPath, {
+                    relativePath: params.relativePath,
+                    recursive: params.recursive,
+                    maxEntries: params.maxEntries,
+                });
+                return { ...listing, folderKey: params.folderKey };
+            },
+            async readText(params) {
+                const status = await inspectStoredLocalFolder(params.squadId, params.folderKey);
+                assertConfiguredLocalFolder(status);
+                return readPluginLocalFolderText(status.realPath, params.relativePath);
+            },
+            async writeTextAtomic(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await preparePluginLocalFolder({
+                    folderKey: params.folderKey,
+                    declaration: getLocalFolderDeclaration(params.folderKey),
+                    storedConfig: await getStoredLocalFolderConfig(squadId, params.folderKey),
+                });
+                const status = await inspectStoredLocalFolder(squadId, params.folderKey);
+                assertWritableConfiguredLocalFolder(status);
+                await writePluginLocalFolderTextAtomic(status.realPath, params.relativePath, params.contents);
+                return inspectStoredLocalFolder(squadId, params.folderKey);
+            },
+            async deleteFile(params) {
+                const squadId = ensureSquadId(params.squadId);
+                const status = await inspectStoredLocalFolder(squadId, params.folderKey);
+                assertWritableConfiguredLocalFolder(status);
+                await deletePluginLocalFolderFile(status.realPath, params.relativePath, params.folderKey);
+                return inspectStoredLocalFolder(squadId, params.folderKey);
+            },
+        },
+        state: {
+            async get(params) {
+                return stateStore.get(pluginId, params.scopeKind, params.stateKey, {
+                    scopeId: params.scopeId,
+                    namespace: params.namespace,
+                });
+            },
+            async set(params) {
+                await stateStore.set(pluginId, {
+                    scopeKind: params.scopeKind,
+                    scopeId: params.scopeId,
+                    namespace: params.namespace,
+                    stateKey: params.stateKey,
+                    value: params.value,
+                });
+            },
+            async delete(params) {
+                await stateStore.delete(pluginId, params.scopeKind, params.stateKey, {
+                    scopeId: params.scopeId,
+                    namespace: params.namespace,
+                });
+            },
+        },
+        db: {
+            async namespace() {
+                return pluginDb.getRuntimeNamespace(pluginId);
+            },
+            async query(params) {
+                return pluginDb.query(pluginId, params.sql, params.params);
+            },
+            async execute(params) {
+                return pluginDb.execute(pluginId, params.sql, params.params);
+            },
+        },
+        entities: {
+            async upsert(params) {
+                return registry.upsertEntity(pluginId, params);
+            },
+            async list(params) {
+                return registry.listEntities(pluginId, params);
+            },
+        },
+        events: {
+            async emit(params) {
+                if (params.squadId) {
+                    await ensurePluginAvailableForSquad(params.squadId);
+                }
+                await scopedBus.emit(params.name, params.squadId, params.payload);
+            },
+            async subscribe(params) {
+                const handler = async (event) => {
+                    if (notifyWorker) {
+                        notifyWorker("onEvent", { event });
+                    }
+                };
+                if (params.filter) {
+                    scopedBus.subscribe(params.eventPattern, params.filter, handler);
+                }
+                else {
+                    scopedBus.subscribe(params.eventPattern, handler);
+                }
+            },
+        },
+        http: {
+            async fetch(params) {
+                // SSRF protection: validate protocol whitelist + block private IPs.
+                // Resolve once, then connect directly to that IP to prevent DNS rebinding.
+                const target = await validateAndResolveFetchUrl(params.url);
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), PLUGIN_FETCH_TIMEOUT_MS);
+                try {
+                    const init = params.init;
+                    return await executePinnedHttpRequest(target, init, controller.signal);
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            },
+        },
+        secrets: {
+            async resolve(params) {
+                return secretsHandler.resolve(params);
+            },
+        },
+        activity: {
+            async log(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                await logActivity(db, {
+                    squadId,
+                    actorType: "plugin",
+                    actorId: pluginId,
+                    action: params.message,
+                    entityType: params.entityType ?? "plugin",
+                    entityId: params.entityId ?? pluginId,
+                    details: pluginActivityDetails(params.metadata),
+                });
+            },
+        },
+        metrics: {
+            async write(params) {
+                const safeName = truncStr(String(params.name ?? ""), MAX_METRIC_NAME_LENGTH);
+                logger.debug({ pluginId, name: safeName, value: params.value, tags: params.tags }, "Plugin metric write");
+                // Persist metrics to plugin_logs via the batch buffer (same path as
+                // logger.log) so they benefit from batched writes and are flushed
+                // reliably on shutdown. Using level "metric" makes them queryable
+                // alongside regular logs via the same API (§26).
+                _logBuffer.push({
+                    db,
+                    pluginId,
+                    level: "metric",
+                    message: safeName,
+                    meta: sanitiseMeta({ value: params.value, tags: params.tags ?? null }),
+                });
+                if (_logBuffer.length >= LOG_BUFFER_FLUSH_SIZE) {
+                    flushPluginLogBuffer().catch((err) => {
+                        console.error("[plugin-host-services] Triggered metric flush failed:", err);
+                    });
+                }
+            },
+        },
+        logger: {
+            async log(params) {
+                const { level, meta } = params;
+                const safeMessage = truncStr(String(params.message ?? ""), MAX_LOG_MESSAGE_LENGTH);
+                const safeMeta = sanitiseMeta(meta);
+                const pluginLogger = logger.child({ service: "plugin-worker", pluginId });
+                const logFields = {
+                    ...safeMeta,
+                    pluginLogLevel: level,
+                    pluginTimestamp: new Date().toISOString(),
+                };
+                if (level === "error")
+                    pluginLogger.error(logFields, `[plugin] ${safeMessage}`);
+                else if (level === "warn")
+                    pluginLogger.warn(logFields, `[plugin] ${safeMessage}`);
+                else if (level === "debug")
+                    pluginLogger.debug(logFields, `[plugin] ${safeMessage}`);
+                else
+                    pluginLogger.info(logFields, `[plugin] ${safeMessage}`);
+                // Persist to plugin_logs table via the module-level batch buffer (§26.1).
+                // Fire-and-forget — logging should never block the worker.
+                _logBuffer.push({
+                    db,
+                    pluginId,
+                    level: level ?? "info",
+                    message: safeMessage,
+                    meta: safeMeta,
+                });
+                if (_logBuffer.length >= LOG_BUFFER_FLUSH_SIZE) {
+                    flushPluginLogBuffer().catch((err) => {
+                        console.error("[plugin-host-services] Triggered log flush failed:", err);
+                    });
+                }
+            },
+        },
+        squads: {
+            async list(params) {
+                return applyWindow((await squads.list()), params);
+            },
+            async get(params) {
+                await ensurePluginAvailableForSquad(params.squadId);
+                return (await squads.getById(params.squadId));
+            },
+        },
+        projects: {
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return applyWindow((await projects.list(squadId)), params);
+            },
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const project = await projects.getById(params.projectId);
+                return (inSquad(project, squadId) ? project : null);
+            },
+            async listWorkspaces(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const project = await projects.getById(params.projectId);
+                if (!inSquad(project, squadId))
+                    return [];
+                const rows = await projects.listWorkspaces(params.projectId);
+                return rows.map((row) => {
+                    const path = sanitizeWorkspacePath(row.cwd);
+                    const name = sanitizeWorkspaceName(row.name, path);
+                    return {
+                        id: row.id,
+                        projectId: row.projectId,
+                        name,
+                        path,
+                        repoUrl: row.repoUrl,
+                        repoRef: row.repoRef,
+                        defaultRef: row.defaultRef,
+                        isPrimary: row.isPrimary,
+                        createdAt: row.createdAt.toISOString(),
+                        updatedAt: row.updatedAt.toISOString(),
+                    };
+                });
+            },
+            async getPrimaryWorkspace(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const project = await projects.getById(params.projectId);
+                if (!inSquad(project, squadId))
+                    return null;
+                const row = project.primaryWorkspace;
+                const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder);
+                const name = sanitizeWorkspaceName(row?.name ?? project.name, path);
+                return {
+                    id: row?.id ?? `${project.id}:managed`,
+                    projectId: project.id,
+                    name,
+                    path,
+                    repoUrl: row?.repoUrl ?? project.codebase.repoUrl,
+                    repoRef: row?.repoRef ?? project.codebase.repoRef,
+                    defaultRef: row?.defaultRef ?? project.codebase.defaultRef,
+                    isPrimary: true,
+                    createdAt: (row?.createdAt ?? project.createdAt).toISOString(),
+                    updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(),
+                };
+            },
+            async getWorkspaceForIssue(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = await issues.getById(params.issueId);
+                if (!inSquad(issue, squadId))
+                    return null;
+                const projectId = issue.projectId;
+                if (!projectId)
+                    return null;
+                const project = await projects.getById(projectId);
+                if (!inSquad(project, squadId))
+                    return null;
+                const row = project.primaryWorkspace;
+                const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder);
+                const name = sanitizeWorkspaceName(row?.name ?? project.name, path);
+                return {
+                    id: row?.id ?? `${project.id}:managed`,
+                    projectId: project.id,
+                    name,
+                    path,
+                    repoUrl: row?.repoUrl ?? project.codebase.repoUrl,
+                    repoRef: row?.repoRef ?? project.codebase.repoRef,
+                    defaultRef: row?.defaultRef ?? project.codebase.defaultRef,
+                    isPrimary: true,
+                    createdAt: (row?.createdAt ?? project.createdAt).toISOString(),
+                    updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(),
+                };
+            },
+            async getManaged(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return projects.resolveManagedProject({
+                    squadId,
+                    pluginId,
+                    pluginKey,
+                    projectKey: params.projectKey,
+                    createIfMissing: false,
+                });
+            },
+            async reconcileManaged(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return projects.resolveManagedProject({
+                    squadId,
+                    pluginId,
+                    pluginKey,
+                    projectKey: params.projectKey,
+                });
+            },
+            async resetManaged(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return projects.resolveManagedProject({
+                    squadId,
+                    pluginId,
+                    pluginKey,
+                    projectKey: params.projectKey,
+                    reset: true,
+                });
+            },
+        },
+        executionWorkspaces: {
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const workspace = await executionWorkspaces.getById(params.workspaceId);
+                if (inSquad(workspace, squadId)) {
+                    return toPluginExecutionWorkspaceMetadata(workspace);
+                }
+                return null;
+            },
+        },
+        routines: {
+            async managedGet(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedRoutines.get(params.routineKey, squadId);
+            },
+            async managedReconcile(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedRoutines.reconcile(params.routineKey, squadId, {
+                    assigneeAgentId: params.assigneeAgentId,
+                    projectId: params.projectId,
+                });
+            },
+            async managedReset(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedRoutines.reset(params.routineKey, squadId, {
+                    assigneeAgentId: params.assigneeAgentId,
+                    projectId: params.projectId,
+                });
+            },
+            async managedUpdate(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedRoutines.update(params.routineKey, squadId, {
+                    status: params.status,
+                });
+            },
+            async managedRun(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedRoutines.run(params.routineKey, squadId, {
+                    assigneeAgentId: params.assigneeAgentId,
+                    projectId: params.projectId,
+                });
+            },
+        },
+        skills: {
+            async managedGet(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedSkills.get(params.skillKey, squadId);
+            },
+            async managedReconcile(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedSkills.reconcile(params.skillKey, squadId);
+            },
+            async managedReset(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedSkills.reset(params.skillKey, squadId);
+            },
+        },
+        issues: {
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                assertReadableOriginFilter(params.originKind);
+                return applyWindow((await issues.list(squadId, params)), params);
+            },
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = await issues.getById(params.issueId);
+                return (inSquad(issue, squadId) ? issue : null);
+            },
+            async create(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const { actorAgentId, actorUserId, actorRunId, originKind, surfaceVisibility, ...issueInput } = params;
+                const normalizedOriginKind = normalizePluginOriginKind(surfaceVisibility === "plugin_operation" && !originKind
+                    ? pluginOperationIssueOriginKind(pluginKey)
+                    : originKind);
+                const issue = (await issues.create(squadId, {
+                    ...issueInput,
+                    originKind: normalizedOriginKind,
+                    originId: params.originId ?? null,
+                    originRunId: params.originRunId ?? actorRunId ?? null,
+                    createdByAgentId: actorAgentId ?? null,
+                    createdByUserId: actorUserId ?? null,
+                }));
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.created",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    actor: { actorAgentId, actorUserId, actorRunId },
+                    details: {
+                        title: issue.title,
+                        identifier: issue.identifier,
+                        originKind: normalizedOriginKind,
+                        originId: issue.originId,
+                        billingCode: issue.billingCode,
+                        blockedByIssueIds: params.blockedByIssueIds ?? [],
+                    },
+                });
+                return issue;
+            },
+            async update(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const existing = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const patch = { ...params.patch };
+                const actorAgentId = typeof patch.actorAgentId === "string" ? patch.actorAgentId : null;
+                const actorUserId = typeof patch.actorUserId === "string" ? patch.actorUserId : null;
+                const actorRunId = typeof patch.actorRunId === "string" ? patch.actorRunId : null;
+                delete patch.actorAgentId;
+                delete patch.actorUserId;
+                delete patch.actorRunId;
+                if (patch.originKind !== undefined) {
+                    patch.originKind = normalizePluginOriginKind(patch.originKind);
+                }
+                const updated = (await issues.update(params.issueId, {
+                    ...patch,
+                    actorAgentId,
+                    actorUserId,
+                }));
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.updated",
+                    entityType: "issue",
+                    entityId: updated.id,
+                    actor: { actorAgentId, actorUserId, actorRunId },
+                    details: {
+                        identifier: updated.identifier,
+                        patch,
+                        _previous: {
+                            status: existing.status,
+                            assigneeAgentId: existing.assigneeAgentId,
+                            assigneeUserId: existing.assigneeUserId,
+                        },
+                    },
+                });
+                return updated;
+            },
+            async getRelations(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                return await issues.getRelationSummaries(params.issueId);
+            },
+            async setBlockedBy(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return setBlockedByWithActivity({
+                    squadId,
+                    issueId: params.issueId,
+                    blockedByIssueIds: params.blockedByIssueIds,
+                    mutation: "set",
+                    actorAgentId: params.actorAgentId,
+                    actorUserId: params.actorUserId,
+                    actorRunId: params.actorRunId,
+                });
+            },
+            async addBlockers(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const previous = await issues.getRelationSummaries(params.issueId);
+                const nextBlockedByIssueIds = [
+                    ...new Set([
+                        ...previous.blockedBy.map((relation) => relation.id),
+                        ...params.blockerIssueIds,
+                    ]),
+                ];
+                return setBlockedByWithActivity({
+                    squadId,
+                    issueId: params.issueId,
+                    blockedByIssueIds: nextBlockedByIssueIds,
+                    mutation: "add",
+                    actorAgentId: params.actorAgentId,
+                    actorUserId: params.actorUserId,
+                    actorRunId: params.actorRunId,
+                });
+            },
+            async removeBlockers(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const previous = await issues.getRelationSummaries(params.issueId);
+                const removals = new Set(params.blockerIssueIds);
+                const nextBlockedByIssueIds = previous.blockedBy
+                    .map((relation) => relation.id)
+                    .filter((issueId) => !removals.has(issueId));
+                return setBlockedByWithActivity({
+                    squadId,
+                    issueId: params.issueId,
+                    blockedByIssueIds: nextBlockedByIssueIds,
+                    mutation: "remove",
+                    actorAgentId: params.actorAgentId,
+                    actorUserId: params.actorUserId,
+                    actorRunId: params.actorRunId,
+                });
+            },
+            async assertCheckoutOwner(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const ownership = await issues.assertCheckoutOwner(params.issueId, params.actorAgentId, params.actorRunId);
+                if (ownership.adoptedFromRunId) {
+                    await logPluginActivity({
+                        squadId,
+                        action: "issue.checkout_lock_adopted",
+                        entityType: "issue",
+                        entityId: params.issueId,
+                        actor: {
+                            actorAgentId: params.actorAgentId,
+                            actorRunId: params.actorRunId,
+                        },
+                        details: {
+                            previousCheckoutRunId: ownership.adoptedFromRunId,
+                            checkoutRunId: params.actorRunId,
+                            reason: "stale_checkout_run",
+                        },
+                    });
+                }
+                return {
+                    issueId: ownership.id,
+                    status: ownership.status,
+                    assigneeAgentId: ownership.assigneeAgentId,
+                    checkoutRunId: ownership.checkoutRunId,
+                    adoptedFromRunId: ownership.adoptedFromRunId,
+                };
+            },
+            async getSubtree(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rootIssue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const includeRoot = params.includeRoot !== false;
+                const subtreeIssueIds = await collectIssueSubtreeIds(squadId, rootIssue.id);
+                const issueIds = includeRoot ? subtreeIssueIds : subtreeIssueIds.filter((issueId) => issueId !== rootIssue.id);
+                const issueRows = issueIds.length > 0
+                    ? await db
+                        .select()
+                        .from(issuesTable)
+                        .where(and(eq(issuesTable.squadId, squadId), inArray(issuesTable.id, issueIds)))
+                    : [];
+                const issuesById = new Map(issueRows.map((issue) => [issue.id, issue]));
+                const outputIssues = issueIds
+                    .map((issueId) => issuesById.get(issueId))
+                    .filter((issue) => Boolean(issue));
+                const assigneeAgentIds = [
+                    ...new Set(outputIssues.map((issue) => issue.assigneeAgentId).filter((id) => Boolean(id))),
+                ];
+                const [relationPairs, documentPairs, activeRunRows, assigneeRows] = await Promise.all([
+                    params.includeRelations
+                        ? Promise.all(issueIds.map(async (issueId) => [issueId, await issues.getRelationSummaries(issueId)]))
+                        : Promise.resolve(null),
+                    params.includeDocuments
+                        ? Promise.all(issueIds.map(async (issueId) => {
+                            const docs = await documents.listIssueDocuments(issueId);
+                            const summaries = docs.map((document) => {
+                                const { body: _body, ...summary } = document;
+                                return { ...summary, format: "markdown" };
+                            });
+                            return [
+                                issueId,
+                                summaries,
+                            ];
+                        }))
+                        : Promise.resolve(null),
+                    params.includeActiveRuns
+                        ? getIssueRunSummaries(squadId, issueIds, { activeOnly: true })
+                        : Promise.resolve(null),
+                    params.includeAssignees && assigneeAgentIds.length > 0
+                        ? db
+                            .select({
+                            id: agentsTable.id,
+                            name: agentsTable.name,
+                            role: agentsTable.role,
+                            title: agentsTable.title,
+                            status: agentsTable.status,
+                        })
+                            .from(agentsTable)
+                            .where(and(eq(agentsTable.squadId, squadId), inArray(agentsTable.id, assigneeAgentIds)))
+                        : Promise.resolve(params.includeAssignees ? [] : null),
+                ]);
+                const activeRuns = activeRunRows
+                    ? Object.fromEntries(issueIds.map((issueId) => [
+                        issueId,
+                        activeRunRows.filter((run) => run.issueId === issueId),
+                    ]))
+                    : undefined;
+                return {
+                    rootIssueId: rootIssue.id,
+                    squadId,
+                    issueIds,
+                    issues: outputIssues,
+                    ...(relationPairs ? { relations: Object.fromEntries(relationPairs) } : {}),
+                    ...(documentPairs ? { documents: Object.fromEntries(documentPairs) } : {}),
+                    ...(activeRuns ? { activeRuns } : {}),
+                    ...(assigneeRows
+                        ? {
+                            assignees: Object.fromEntries(assigneeRows.map((agent) => [
+                                agent.id,
+                                { ...agent, status: agent.status },
+                            ])),
+                        }
+                        : {}),
+                };
+            },
+            async requestWakeup(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                if (!issue.assigneeAgentId) {
+                    throw new Error("Issue has no assigned agent to wake");
+                }
+                if (["backlog", "done", "cancelled"].includes(issue.status)) {
+                    throw new Error(`Issue is not wakeable in status: ${issue.status}`);
+                }
+                const relations = await issues.getRelationSummaries(issue.id);
+                const unresolvedBlockers = relations.blockedBy.filter((blocker) => blocker.status !== "done");
+                if (unresolvedBlockers.length > 0) {
+                    throw new Error("Issue is blocked by unresolved blockers");
+                }
+                const budgetBlock = await budgets.getInvocationBlock(squadId, issue.assigneeAgentId, {
+                    issueId: issue.id,
+                    projectId: issue.projectId,
+                });
+                if (budgetBlock) {
+                    throw new Error(budgetBlock.reason);
+                }
+                const contextSource = params.contextSource ?? "plugin.issue.requestWakeup";
+                const run = await heartbeat.wakeup(issue.assigneeAgentId, {
+                    source: "assignment",
+                    triggerDetail: "system",
+                    reason: params.reason ?? "plugin_issue_wakeup_requested",
+                    payload: {
+                        issueId: issue.id,
+                        mutation: "plugin_wakeup",
+                        pluginId,
+                        pluginKey,
+                        contextSource,
+                    },
+                    idempotencyKey: params.idempotencyKey ?? null,
+                    requestedByActorType: "system",
+                    requestedByActorId: pluginId,
+                    contextSnapshot: {
+                        issueId: issue.id,
+                        taskId: issue.id,
+                        wakeReason: params.reason ?? "plugin_issue_wakeup_requested",
+                        source: contextSource,
+                        pluginId,
+                        pluginKey,
+                    },
+                });
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.assignment_wakeup_requested",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    actor: {
+                        actorAgentId: params.actorAgentId,
+                        actorUserId: params.actorUserId,
+                        actorRunId: params.actorRunId,
+                    },
+                    details: {
+                        identifier: issue.identifier,
+                        assigneeAgentId: issue.assigneeAgentId,
+                        runId: run?.id ?? null,
+                        reason: params.reason ?? "plugin_issue_wakeup_requested",
+                        contextSource,
+                    },
+                });
+                return { queued: Boolean(run), runId: run?.id ?? null };
+            },
+            async requestWakeups(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const results = [];
+                for (const issueId of [...new Set(params.issueIds)]) {
+                    const issue = requireInSquad("Issue", await issues.getById(issueId), squadId);
+                    if (!issue.assigneeAgentId) {
+                        throw new Error("Issue has no assigned agent to wake");
+                    }
+                    if (["backlog", "done", "cancelled"].includes(issue.status)) {
+                        throw new Error(`Issue is not wakeable in status: ${issue.status}`);
+                    }
+                    const relations = await issues.getRelationSummaries(issue.id);
+                    const unresolvedBlockers = relations.blockedBy.filter((blocker) => blocker.status !== "done");
+                    if (unresolvedBlockers.length > 0) {
+                        throw new Error("Issue is blocked by unresolved blockers");
+                    }
+                    const budgetBlock = await budgets.getInvocationBlock(squadId, issue.assigneeAgentId, {
+                        issueId: issue.id,
+                        projectId: issue.projectId,
+                    });
+                    if (budgetBlock) {
+                        throw new Error(budgetBlock.reason);
+                    }
+                    const contextSource = params.contextSource ?? "plugin.issue.requestWakeups";
+                    const run = await heartbeat.wakeup(issue.assigneeAgentId, {
+                        source: "assignment",
+                        triggerDetail: "system",
+                        reason: params.reason ?? "plugin_issue_wakeup_requested",
+                        payload: {
+                            issueId: issue.id,
+                            mutation: "plugin_wakeup",
+                            pluginId,
+                            pluginKey,
+                            contextSource,
+                        },
+                        idempotencyKey: params.idempotencyKeyPrefix ? `${params.idempotencyKeyPrefix}:${issue.id}` : null,
+                        requestedByActorType: "system",
+                        requestedByActorId: pluginId,
+                        contextSnapshot: {
+                            issueId: issue.id,
+                            taskId: issue.id,
+                            wakeReason: params.reason ?? "plugin_issue_wakeup_requested",
+                            source: contextSource,
+                            pluginId,
+                            pluginKey,
+                        },
+                    });
+                    await logPluginActivity({
+                        squadId,
+                        action: "issue.assignment_wakeup_requested",
+                        entityType: "issue",
+                        entityId: issue.id,
+                        actor: {
+                            actorAgentId: params.actorAgentId,
+                            actorUserId: params.actorUserId,
+                            actorRunId: params.actorRunId,
+                        },
+                        details: {
+                            identifier: issue.identifier,
+                            assigneeAgentId: issue.assigneeAgentId,
+                            runId: run?.id ?? null,
+                            reason: params.reason ?? "plugin_issue_wakeup_requested",
+                            contextSource,
+                        },
+                    });
+                    results.push({ issueId: issue.id, queued: Boolean(run), runId: run?.id ?? null });
+                }
+                return results;
+            },
+            async getOrchestrationSummary(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rootIssue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const subtreeIssueIds = params.includeSubtree
+                    ? await collectIssueSubtreeIds(squadId, rootIssue.id)
+                    : [rootIssue.id];
+                const relationPairs = await Promise.all(subtreeIssueIds.map(async (issueId) => [issueId, await issues.getRelationSummaries(issueId)]));
+                const approvalRows = (await Promise.all(subtreeIssueIds.map(async (issueId) => {
+                    const rows = await issueApprovals.listApprovalsForIssue(issueId);
+                    return rows.map((approval) => ({
+                        issueId,
+                        id: approval.id,
+                        type: approval.type,
+                        status: approval.status,
+                        requestedByAgentId: approval.requestedByAgentId,
+                        requestedByUserId: approval.requestedByUserId,
+                        decidedByUserId: approval.decidedByUserId,
+                        decidedAt: approval.decidedAt?.toISOString() ?? null,
+                        createdAt: approval.createdAt.toISOString(),
+                    }));
+                }))).flat();
+                const [runs, costsSummary, openBudgetIncidents] = await Promise.all([
+                    getIssueRunSummaries(squadId, subtreeIssueIds),
+                    getIssueCostSummary(squadId, subtreeIssueIds, params.billingCode ?? rootIssue.billingCode ?? null),
+                    getOpenBudgetIncidents(squadId),
+                ]);
+                const issueRows = await db
+                    .select({
+                    id: issuesTable.id,
+                    assigneeAgentId: issuesTable.assigneeAgentId,
+                    projectId: issuesTable.projectId,
+                })
+                    .from(issuesTable)
+                    .where(and(eq(issuesTable.squadId, squadId), inArray(issuesTable.id, subtreeIssueIds)));
+                const invocationBlocks = (await Promise.all(issueRows
+                    .filter((issueRow) => issueRow.assigneeAgentId)
+                    .map(async (issueRow) => {
+                    const block = await budgets.getInvocationBlock(squadId, issueRow.assigneeAgentId, {
+                        issueId: issueRow.id,
+                        projectId: issueRow.projectId,
+                    });
+                    return block
+                        ? {
+                            issueId: issueRow.id,
+                            agentId: issueRow.assigneeAgentId,
+                            scopeType: block.scopeType,
+                            scopeId: block.scopeId,
+                            scopeName: block.scopeName,
+                            reason: block.reason,
+                        }
+                        : null;
+                }))).filter((block) => block !== null);
+                return {
+                    issueId: rootIssue.id,
+                    squadId,
+                    subtreeIssueIds,
+                    relations: Object.fromEntries(relationPairs),
+                    approvals: approvalRows,
+                    runs,
+                    costs: costsSummary,
+                    openBudgetIncidents,
+                    invocationBlocks,
+                };
+            },
+            async listComments(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                if (!inSquad(await issues.getById(params.issueId), squadId))
+                    return [];
+                return (await issues.listComments(params.issueId));
+            },
+            async createComment(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const comment = (await issues.addComment(params.issueId, params.body, { agentId: params.authorAgentId }));
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.comment.created",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    actor: { actorAgentId: params.authorAgentId ?? null },
+                    details: {
+                        identifier: issue.identifier,
+                        commentId: comment.id,
+                        bodySnippet: comment.body.slice(0, 120),
+                    },
+                });
+                return comment;
+            },
+            async createInteraction(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const interaction = await issueThreadInteractionService(db).create(issue, params.interaction, {
+                    agentId: params.authorAgentId ?? null,
+                });
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.thread_interaction_created",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    actor: { actorAgentId: params.authorAgentId ?? null },
+                    details: {
+                        identifier: issue.identifier,
+                        interactionId: interaction.id,
+                        interactionKind: interaction.kind,
+                        interactionStatus: interaction.status,
+                        continuationPolicy: interaction.continuationPolicy,
+                    },
+                });
+                return interaction;
+            },
+        },
+        issueDocuments: {
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const rows = await documents.listIssueDocuments(params.issueId);
+                return rows;
+            },
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const doc = await documents.getIssueDocumentByKey(params.issueId, params.key);
+                return (doc ?? null);
+            },
+            async upsert(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                const result = await documents.upsertIssueDocument({
+                    issueId: params.issueId,
+                    key: params.key,
+                    body: params.body,
+                    title: params.title ?? null,
+                    format: params.format ?? "markdown",
+                    changeSummary: params.changeSummary ?? null,
+                });
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.document_upserted",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    details: {
+                        identifier: issue.identifier,
+                        documentKey: params.key,
+                        title: params.title ?? null,
+                        format: params.format ?? "markdown",
+                    },
+                });
+                return result.document;
+            },
+            async delete(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const issue = requireInSquad("Issue", await issues.getById(params.issueId), squadId);
+                await documents.deleteIssueDocument(params.issueId, params.key);
+                await logPluginActivity({
+                    squadId,
+                    action: "issue.document_deleted",
+                    entityType: "issue",
+                    entityId: issue.id,
+                    details: {
+                        identifier: issue.identifier,
+                        documentKey: params.key,
+                    },
+                });
+            },
+        },
+        agents: {
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rows = await agents.list(squadId);
+                return applyWindow(rows.filter((agent) => !params.status || agent.status === params.status), params);
+            },
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const agent = await agents.getById(params.agentId);
+                return (inSquad(agent, squadId) ? agent : null);
+            },
+            async pause(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const agent = await agents.getById(params.agentId);
+                requireInSquad("Agent", agent, squadId);
+                return (await agents.pause(params.agentId));
+            },
+            async resume(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const agent = await agents.getById(params.agentId);
+                requireInSquad("Agent", agent, squadId);
+                return (await agents.resume(params.agentId));
+            },
+            async invoke(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const agent = await agents.getById(params.agentId);
+                requireInSquad("Agent", agent, squadId);
+                const run = await heartbeat.wakeup(params.agentId, {
+                    source: "automation",
+                    triggerDetail: "system",
+                    reason: params.reason ?? null,
+                    payload: { prompt: params.prompt },
+                    requestedByActorType: "system",
+                    requestedByActorId: pluginId,
+                });
+                if (!run)
+                    throw new Error("Agent wakeup was skipped by heartbeat policy");
+                return { runId: run.id };
+            },
+            async managedGet(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedAgents.get(params.agentKey, squadId);
+            },
+            async managedReconcile(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedAgents.reconcile(params.agentKey, squadId);
+            },
+            async managedReset(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return managedAgents.reset(params.agentKey, squadId);
+            },
+        },
+        goals: {
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rows = await goals.list(squadId);
+                return applyWindow(rows.filter((goal) => (!params.level || goal.level === params.level) &&
+                    (!params.status || goal.status === params.status)), params);
+            },
+            async get(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const goal = await goals.getById(params.goalId);
+                return (inSquad(goal, squadId) ? goal : null);
+            },
+            async create(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return (await goals.create(squadId, {
+                    title: params.title,
+                    description: params.description,
+                    level: params.level,
+                    status: params.status,
+                    parentId: params.parentId,
+                    ownerAgentId: params.ownerAgentId,
+                }));
+            },
+            async update(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                requireInSquad("Goal", await goals.getById(params.goalId), squadId);
+                return (await goals.update(params.goalId, params.patch));
+            },
+        },
+        access: {
+            async listMembers(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rows = await access.listMembers(squadId);
+                const visibleRows = params.includeArchived ? rows : rows.filter((row) => row.status !== "archived");
+                const grants = await db
+                    .select()
+                    .from(principalPermissionGrants)
+                    .where(eq(principalPermissionGrants.squadId, squadId));
+                const grantsByPrincipal = new Map();
+                for (const grant of grants) {
+                    const key = `${grant.principalType}:${grant.principalId}`;
+                    const existing = grantsByPrincipal.get(key) ?? [];
+                    existing.push(grant);
+                    grantsByPrincipal.set(key, existing);
+                }
+                return visibleRows.map((member) => ({
+                    ...member,
+                    principalType: member.principalType,
+                    status: member.status,
+                    grants: (grantsByPrincipal.get(`${member.principalType}:${member.principalId}`) ?? []).map(redactGrant),
+                }));
+            },
+            async getMember(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return loadPluginMember(squadId, params.memberId);
+            },
+            async updateMember(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const updated = await access.updateMember(squadId, params.memberId, params.patch);
+                if (!updated)
+                    throw new Error("Member not found");
+                await logPluginActivity({
+                    squadId,
+                    action: "squad_member.updated_by_plugin",
+                    entityType: "squad_membership",
+                    entityId: params.memberId,
+                    details: {
+                        patch: sanitizeRecord(params.patch),
+                    },
+                });
+                return (await loadPluginMember(squadId, params.memberId));
+            },
+            async listInvites(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const limit = Math.min(Math.max(Number(params.limit ?? 20), 1), 100);
+                const offset = Math.max(Number(params.offset ?? 0), 0);
+                const stateClause = inviteStateWhereClause(params.state);
+                const rows = await db
+                    .select()
+                    .from(invites)
+                    .where(stateClause ? and(eq(invites.squadId, squadId), stateClause) : eq(invites.squadId, squadId))
+                    .orderBy(desc(invites.createdAt))
+                    .limit(limit + 1)
+                    .offset(offset);
+                const hasMore = rows.length > limit;
+                return {
+                    invites: rows.slice(0, limit).map(redactInvite),
+                    nextOffset: hasMore ? offset + limit : null,
+                };
+            },
+            async createInvite(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const normalizedAgentMessage = typeof params.agentMessage === "string"
+                    ? params.agentMessage.trim() || null
+                    : null;
+                const allowedJoinTypes = params.allowedJoinTypes ?? "both";
+                const humanRole = allowedJoinTypes === "agent" ? null : params.humanRole ?? "operator";
+                const insertValues = {
+                    squadId,
+                    inviteType: "squad_join",
+                    allowedJoinTypes,
+                    defaultsPayload: mergeInviteDefaults(params.defaultsPayload ?? null, normalizedAgentMessage, humanRole),
+                    expiresAt: new Date(Date.now() + SQUAD_INVITE_TTL_MS),
+                    invitedByUserId: null,
+                };
+                let token = null;
+                let created = null;
+                for (let attempt = 0; attempt < INVITE_TOKEN_MAX_RETRIES; attempt += 1) {
+                    const candidateToken = createInviteToken();
+                    try {
+                        created = await db
+                            .insert(invites)
+                            .values({
+                            ...insertValues,
+                            tokenHash: hashToken(candidateToken),
+                        })
+                            .returning()
+                            .then((rows) => rows[0] ?? null);
+                        token = candidateToken;
+                        break;
+                    }
+                    catch (error) {
+                        if (!isInviteTokenHashCollisionError(error))
+                            throw error;
+                    }
+                }
+                if (!token || !created)
+                    throw new Error("Failed to generate a unique invite token");
+                await logPluginActivity({
+                    squadId,
+                    action: "invite.created_by_plugin",
+                    entityType: "invite",
+                    entityId: created.id,
+                    details: {
+                        allowedJoinTypes: created.allowedJoinTypes,
+                        expiresAt: created.expiresAt.toISOString(),
+                        hasAgentMessage: Boolean(normalizedAgentMessage),
+                    },
+                });
+                return { ...redactInvite(created), token };
+            },
+            async revokeInvite(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const invite = await db
+                    .select()
+                    .from(invites)
+                    .where(and(eq(invites.id, params.inviteId), eq(invites.squadId, squadId)))
+                    .then((rows) => rows[0] ?? null);
+                if (!invite)
+                    throw new Error("Invite not found");
+                if (invite.acceptedAt)
+                    throw new Error("Invite already consumed");
+                if (invite.revokedAt)
+                    return redactInvite(invite);
+                const revoked = await db
+                    .update(invites)
+                    .set({ revokedAt: new Date(), updatedAt: new Date() })
+                    .where(eq(invites.id, invite.id))
+                    .returning()
+                    .then((rows) => rows[0] ?? invite);
+                await logPluginActivity({
+                    squadId,
+                    action: "invite.revoked_by_plugin",
+                    entityType: "invite",
+                    entityId: invite.id,
+                });
+                return redactInvite(revoked);
+            },
+        },
+        authorization: {
+            async listGrants(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const conditions = [
+                    eq(principalPermissionGrants.squadId, squadId),
+                    params.principalType ? eq(principalPermissionGrants.principalType, params.principalType) : undefined,
+                    params.principalId ? eq(principalPermissionGrants.principalId, params.principalId) : undefined,
+                ].filter((condition) => Boolean(condition));
+                const rows = await db
+                    .select()
+                    .from(principalPermissionGrants)
+                    .where(and(...conditions))
+                    .orderBy(principalPermissionGrants.principalType, principalPermissionGrants.principalId, principalPermissionGrants.permissionKey);
+                return rows.map(redactGrant);
+            },
+            async setGrants(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                if (params.principalType !== "agent" && params.principalType !== "user") {
+                    throw new Error("principalType must be 'agent' or 'user'");
+                }
+                if (params.principalType === "agent") {
+                    requireInSquad("Agent", await agents.getById(params.principalId), squadId);
+                }
+                else {
+                    const membership = await access.getMembership(squadId, params.principalType, params.principalId);
+                    if (!membership)
+                        throw new Error("Principal is not a member of this squad");
+                }
+                await access.setPrincipalGrants(squadId, params.principalType, params.principalId, params.grants.map((grant) => ({
+                    permissionKey: grant.permissionKey,
+                    scope: grant.scope ? sanitizeRecord(grant.scope) : null,
+                })), params.grantedByUserId ?? null);
+                await logPluginActivity({
+                    squadId,
+                    action: "authorization.grants_updated_by_plugin",
+                    entityType: "principal_permission_grants",
+                    entityId: `${params.principalType}:${params.principalId}`,
+                    details: { grantCount: params.grants.length },
+                });
+                return access
+                    .listPrincipalGrants(squadId, params.principalType, params.principalId)
+                    .then((rows) => rows.map(redactGrant));
+            },
+            async policySummary(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const [members, grants] = await Promise.all([
+                    access.listMembers(squadId),
+                    db
+                        .select({ id: principalPermissionGrants.id })
+                        .from(principalPermissionGrants)
+                        .where(eq(principalPermissionGrants.squadId, squadId)),
+                ]);
+                return {
+                    squadId,
+                    permissionsMode: "simple",
+                    memberCount: members.length,
+                    activeMemberCount: members.filter((member) => member.status === "active").length,
+                    grantCount: grants.length,
+                    advancedPolicyAvailable: false,
+                };
+            },
+            async getPolicy(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return readAuthorizationPolicy(squadId, params.resourceType, params.resourceId);
+            },
+            async updatePolicy(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const policy = params.policy ? sanitizeRecord(params.policy) : null;
+                if (params.resourceType === "agent") {
+                    const agent = requireInSquad("Agent", await agents.getById(params.resourceId), squadId);
+                    const permissions = agent.permissions && typeof agent.permissions === "object"
+                        ? { ...agent.permissions }
+                        : {};
+                    if (policy)
+                        permissions.authorizationPolicy = policy;
+                    else
+                        delete permissions.authorizationPolicy;
+                    await db
+                        .update(agentsTable)
+                        .set({ permissions, updatedAt: new Date() })
+                        .where(eq(agentsTable.id, agent.id));
+                }
+                else if (params.resourceType === "project") {
+                    const project = requireInSquad("Project", await projects.getById(params.resourceId), squadId);
+                    const executionWorkspacePolicy = project.executionWorkspacePolicy && typeof project.executionWorkspacePolicy === "object"
+                        ? { ...project.executionWorkspacePolicy }
+                        : {};
+                    if (policy)
+                        executionWorkspacePolicy.authorizationPolicy = policy;
+                    else
+                        delete executionWorkspacePolicy.authorizationPolicy;
+                    await db
+                        .update(projectsTable)
+                        .set({ executionWorkspacePolicy, updatedAt: new Date() })
+                        .where(eq(projectsTable.id, project.id));
+                }
+                else if (params.resourceType === "issue") {
+                    const issue = requireInSquad("Issue", await issues.getById(params.resourceId), squadId);
+                    const executionPolicy = issue.executionPolicy && typeof issue.executionPolicy === "object"
+                        ? { ...issue.executionPolicy }
+                        : {};
+                    if (policy)
+                        executionPolicy.authorizationPolicy = policy;
+                    else
+                        delete executionPolicy.authorizationPolicy;
+                    await db
+                        .update(issuesTable)
+                        .set({ executionPolicy, updatedAt: new Date() })
+                        .where(eq(issuesTable.id, issue.id));
+                }
+                else {
+                    const squad = await squads.getById(params.resourceId);
+                    if (!squad || squad.id !== squadId)
+                        throw new Error("Squad not found");
+                    throw new Error("Squad authorization policy updates are not supported by the current core schema");
+                }
+                await logPluginActivity({
+                    squadId,
+                    action: "authorization.policy_updated_by_plugin",
+                    entityType: params.resourceType,
+                    entityId: params.resourceId,
+                    details: { hasPolicy: Boolean(policy) },
+                });
+                const updated = await readAuthorizationPolicy(squadId, params.resourceType, params.resourceId);
+                if (!updated)
+                    throw new Error("Policy resource not found");
+                return updated;
+            },
+            async previewAssignment(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return authorization.decide({
+                    actor: pluginAssignmentActor(params.actor),
+                    action: "tasks:assign",
+                    resource: { type: "issue", squadId, ...params.target },
+                    scope: {
+                        issueId: params.target.issueId ?? null,
+                        projectId: params.target.projectId ?? null,
+                        parentIssueId: params.target.parentIssueId ?? null,
+                        assigneeAgentId: params.target.assigneeAgentId ?? null,
+                        assigneeUserId: params.target.assigneeUserId ?? null,
+                    },
+                });
+            },
+            async explainAssignment(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                return authorization.decide({
+                    actor: pluginAssignmentActor(params.actor),
+                    action: "tasks:assign",
+                    resource: { type: "issue", squadId, ...params.target },
+                    scope: {
+                        issueId: params.target.issueId ?? null,
+                        projectId: params.target.projectId ?? null,
+                        parentIssueId: params.target.parentIssueId ?? null,
+                        assigneeAgentId: params.target.assigneeAgentId ?? null,
+                        assigneeUserId: params.target.assigneeUserId ?? null,
+                    },
+                });
+            },
+            async searchAudit(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const limit = Math.min(Math.max(Number(params.limit ?? 50), 1), 100);
+                const offset = Math.max(Number(params.offset ?? 0), 0);
+                const decisionFilter = typeof params.decision === "string" && params.decision.trim()
+                    ? params.decision.trim().toLowerCase()
+                    : null;
+                const conditions = [
+                    eq(activityLog.squadId, squadId),
+                    params.action ? eq(activityLog.action, params.action) : undefined,
+                    params.actorType ? eq(activityLog.actorType, params.actorType) : undefined,
+                    params.actorId ? eq(activityLog.actorId, params.actorId) : undefined,
+                    params.entityType ? eq(activityLog.entityType, params.entityType) : undefined,
+                    params.entityId ? eq(activityLog.entityId, params.entityId) : undefined,
+                    decisionFilter ? authorizationAuditDecisionCondition(decisionFilter) : undefined,
+                ].filter((condition) => Boolean(condition));
+                const rows = await db
+                    .select()
+                    .from(activityLog)
+                    .where(and(...conditions))
+                    .orderBy(desc(activityLog.createdAt))
+                    .limit(limit)
+                    .offset(offset);
+                return rows.map((row) => ({
+                    ...row,
+                    details: row.details && typeof row.details === "object"
+                        ? sanitizeRecord(row.details)
+                        : row.details ?? null,
+                }));
+            },
+        },
+        agentSessions: {
+            async create(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const agent = await agents.getById(params.agentId);
+                requireInSquad("Agent", agent, squadId);
+                const taskKey = params.taskKey ?? `plugin:${pluginKey}:session:${randomUUID()}`;
+                const row = await db
+                    .insert(agentTaskSessionsTable)
+                    .values({
+                    squadId,
+                    agentId: params.agentId,
+                    adapterType: agent.adapterType,
+                    taskKey,
+                    sessionParamsJson: null,
+                    sessionDisplayId: null,
+                    lastRunId: null,
+                    lastError: null,
+                })
+                    .returning()
+                    .then((rows) => rows[0]);
+                return {
+                    sessionId: row.id,
+                    agentId: params.agentId,
+                    squadId,
+                    status: "active",
+                    createdAt: row.createdAt.toISOString(),
+                };
+            },
+            async list(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const rows = await db
+                    .select()
+                    .from(agentTaskSessionsTable)
+                    .where(and(eq(agentTaskSessionsTable.agentId, params.agentId), eq(agentTaskSessionsTable.squadId, squadId), like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`)))
+                    .orderBy(desc(agentTaskSessionsTable.createdAt));
+                return rows.map((row) => ({
+                    sessionId: row.id,
+                    agentId: row.agentId,
+                    squadId: row.squadId,
+                    status: "active",
+                    createdAt: row.createdAt.toISOString(),
+                }));
+            },
+            async sendMessage(params) {
+                if (disposed) {
+                    throw new Error("Host services have been disposed");
+                }
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                // Verify session exists and belongs to this plugin
+                const session = await db
+                    .select()
+                    .from(agentTaskSessionsTable)
+                    .where(and(eq(agentTaskSessionsTable.id, params.sessionId), eq(agentTaskSessionsTable.squadId, squadId), like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`)))
+                    .then((rows) => rows[0] ?? null);
+                if (!session)
+                    throw new Error(`Session not found: ${params.sessionId}`);
+                const run = await heartbeat.wakeup(session.agentId, {
+                    source: "automation",
+                    triggerDetail: "system",
+                    reason: params.reason ?? null,
+                    payload: { prompt: params.prompt },
+                    contextSnapshot: {
+                        taskKey: session.taskKey,
+                        wakeSource: "automation",
+                        wakeTriggerDetail: "system",
+                    },
+                    requestedByActorType: "system",
+                    requestedByActorId: pluginId,
+                });
+                if (!run)
+                    throw new Error("Agent wakeup was skipped by heartbeat policy");
+                // Subscribe to live events and forward to the plugin worker as notifications.
+                // Track the subscription so it can be cleaned up on dispose() if the run
+                // never reaches a terminal status (hang, crash, network partition).
+                if (notifyWorker) {
+                    const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "timed_out"]);
+                    const cleanup = () => {
+                        unsubscribe();
+                        clearTimeout(timeoutTimer);
+                        activeSubscriptions.delete(entry);
+                    };
+                    const unsubscribe = subscribeSquadLiveEvents(squadId, (event) => {
+                        const payload = event.payload;
+                        if (!payload || payload.runId !== run.id)
+                            return;
+                        if (event.type === "heartbeat.run.log" || event.type === "heartbeat.run.event") {
+                            notifyWorker("agents.sessions.event", {
+                                sessionId: params.sessionId,
+                                runId: run.id,
+                                seq: payload.seq ?? 0,
+                                eventType: "chunk",
+                                stream: payload.stream ?? null,
+                                message: payload.chunk ?? payload.message ?? null,
+                                payload: payload,
+                            });
+                        }
+                        else if (event.type === "heartbeat.run.status") {
+                            const status = payload.status;
+                            if (TERMINAL_STATUSES.has(status)) {
+                                notifyWorker("agents.sessions.event", {
+                                    sessionId: params.sessionId,
+                                    runId: run.id,
+                                    seq: 0,
+                                    eventType: status === "succeeded" ? "done" : "error",
+                                    stream: "system",
+                                    message: status === "succeeded" ? "Run completed" : `Run ${status}`,
+                                    payload: payload,
+                                });
+                                cleanup();
+                            }
+                            else {
+                                notifyWorker("agents.sessions.event", {
+                                    sessionId: params.sessionId,
+                                    runId: run.id,
+                                    seq: 0,
+                                    eventType: "status",
+                                    stream: "system",
+                                    message: `Run status: ${status}`,
+                                    payload: payload,
+                                });
+                            }
+                        }
+                    });
+                    // Safety-net timeout: if the run never reaches a terminal status,
+                    // force-cleanup the subscription to prevent unbounded leaks.
+                    const timeoutTimer = setTimeout(() => {
+                        logger.warn({ pluginId, pluginKey, runId: run.id }, "session event subscription timed out — forcing cleanup");
+                        cleanup();
+                    }, SESSION_EVENT_SUBSCRIPTION_TIMEOUT_MS);
+                    const entry = { unsubscribe, timer: timeoutTimer };
+                    activeSubscriptions.add(entry);
+                }
+                return { runId: run.id };
+            },
+            async close(params) {
+                const squadId = ensureSquadId(params.squadId);
+                await ensurePluginAvailableForSquad(squadId);
+                const deleted = await db
+                    .delete(agentTaskSessionsTable)
+                    .where(and(eq(agentTaskSessionsTable.id, params.sessionId), eq(agentTaskSessionsTable.squadId, squadId), like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`)))
+                    .returning()
+                    .then((rows) => rows.length);
+                if (deleted === 0)
+                    throw new Error(`Session not found: ${params.sessionId}`);
+            },
+        },
+        /**
+         * Clean up all active session event subscriptions and flush any buffered
+         * log entries. Must be called when the plugin worker is stopped, crashed,
+         * or unloaded to prevent leaked listeners and lost log entries.
+         */
+        dispose() {
+            disposed = true;
+            // Clear event bus subscriptions to prevent accumulation on worker restart.
+            // Without this, each crash/restart cycle adds duplicate subscriptions.
+            scopedBus.clear();
+            // Snapshot to avoid iterator invalidation from concurrent sendMessage() calls
+            const snapshot = Array.from(activeSubscriptions);
+            activeSubscriptions.clear();
+            for (const entry of snapshot) {
+                clearTimeout(entry.timer);
+                entry.unsubscribe();
+            }
+            // Flush any buffered log entries synchronously-as-possible on dispose.
+            flushPluginLogBuffer().catch((err) => {
+                console.error("[plugin-host-services] dispose() log flush failed:", err);
+            });
+        },
+    };
+}
+//# sourceMappingURL=plugin-host-services.js.map