@bbigbang/core 0.1.0

package/dist/services/workspaceToolService.js

@@ -0,0 +1,3067 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+import { BUILTIN_UI_PANEL_SKILL_ROOT_SENTINEL, BUILTIN_WORKSPACE_TOOL_SKILL_ROOT_SENTINEL, buildThreadShortId, normalizeThreadShortIdInput, } from '@bbigbang/protocol';
+import { log } from '@bbigbang/runtime-acp';
+import { allocateNextChannelMessageSeq } from '../web/channelMessageSequences.js';
+import { conversationBuiltinSkillRootsForSlashCommand } from '../web/conversationBuiltinSkillRoots.js';
+import { resolveDirectUserIdFromReplyTarget } from '../web/directReplyTargets.js';
+import { archivePanelWithArtifacts, hardDeletePanelWithArtifacts, unlinkPanelAttachmentStoragePaths, } from '../web/panelLifecycle.js';
+import { getPanelById, listPanelRows, } from '../web/panels.js';
+import { ensureSurfaceOwner, getSurfaceCollaboratorRole, listSurfaceCollaborators, removeSurfaceCollaborator, upsertSurfaceCollaborator, } from '../web/surfaceCollaborators.js';
+import { getUserAgentAccess, getUserChannelAccess } from './auth.js';
+import { WorkspaceToolActionRunner } from './workspaceToolActionRunner.js';
+import { WorkspaceToolLatestStateProjector } from './workspaceToolLatestStateProjector.js';
+import { buildDeletedWorkspaceToolSlug, closeTerminalBestEffort, deriveOneShotRunCompletion, formatBoundedJsonPreview, formatBoundedTextPreview, getPublishedWorkspaceToolBundleRoot, isPlainRecord, normalizeWorkspaceRelativePath, parseWorkspaceToolRunArtifactRefs, resolveToolCwd, runEventRowToInfo, shellEscape, validateManifestConsistency, validateManifestCwds, waitForTerminalExit, } from './workspaceToolExecutionUtils.js';
+import { WorkspaceToolServiceError } from './workspaceToolErrors.js';
+import { parseWorkspaceToolManifest, withPersistedToolSettings, } from './workspaceToolManifest.js';
+import { buildDirectPromotedToolManifest, hasRowTemplateGridPromotionSeed } from './workspaceToolPromotion.js';
+import { WorkspaceToolMutationQueues } from './workspaceToolMutationQueue.js';
+import { isDeletedLinkedToolPromotionRetryable, resolveWorkspaceToolPromotionState, } from './workspaceToolPromotionState.js';
+import { WorkspaceToolPublishIdentityResolver, } from './workspaceToolPublishIdentityResolver.js';
+import { buildWorkspaceToolPublishDiagnostics } from './workspaceToolPublishDiagnostics.js';
+import { WorkspaceToolReadModel, workspaceToolRunRowToInfoForViewer, } from './workspaceToolReadModel.js';
+import { WorkspaceToolSnapshotPanelSyncer } from './workspaceToolSnapshotPanelSync.js';
+export { WorkspaceToolServiceError } from './workspaceToolErrors.js';
+export { getPublishedWorkspaceToolBundleRoot, getWorkspaceToolMediaRelativePathCandidates, } from './workspaceToolExecutionUtils.js';
+const TOOL_MAINTENANCE_TITLE_PREFIX = '[workspace-tool:';
+const PANEL_TOOL_PROMOTION_THREAD_PREFIX = 'paneltool-';
+const DEFAULT_WORKSPACE_TOOL_MAX_ACTIVE_PERSISTENT_RUNS_PER_AGENT = 3;
+const PANEL_PROMOTION_SAMPLE_ROW_LIMIT = 3;
+const WORKSPACE_TOOL_PLATFORM_EXEC_MESSAGE_SOURCE = 'workspace_tool_platform_exec';
+const WORKSPACE_TOOL_PLATFORM_EXEC_OUTPUT_PREVIEW_LIMIT = 800;
+const WORKSPACE_TOOL_PLATFORM_EXEC_PARAMS_PREVIEW_LIMIT = 800;
+export const WORKSPACE_TOOL_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const WORKSPACE_TOOL_LOG_RETENTION_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const WORKSPACE_TOOL_RUNTIME_LOG_MAX_BYTES_BEFORE_ROTATE = 10 * 1024 * 1024;
+const WORKSPACE_TOOL_CLONE_ARCHIVE_MAX_BYTES = 25 * 1024 * 1024;
+const WORKSPACE_TOOL_CLONE_ARCHIVE_TIMEOUT_MS = 60_000;
+const WORKSPACE_TOOL_RUN_LIST_MAX_LIMIT = 100;
+export const WORKSPACE_TOOL_RUN_HISTORY_MAX_STORED_PER_TOOL = 100;
+const WORKSPACE_TOOL_RUN_EVENT_DEFAULT_LIMIT = 80;
+const WORKSPACE_TOOL_RUN_EVENT_MAX_LIMIT = 500;
+const WORKSPACE_TOOL_RUN_ARTIFACT_DEFAULT_LIMIT = 100;
+const WORKSPACE_TOOL_RUN_ARTIFACT_MAX_LIMIT = 500;
+const WORKSPACE_TOOL_RUN_ARTIFACT_SCAN_BATCH = 100;
+const WORKSPACE_TOOL_RUN_ARTIFACT_MAX_SCANNED_EVENTS = 1_000;
+function normalizeBoundedPositiveInteger(value, defaultValue, maxValue) {
+    if (!Number.isInteger(value) || value <= 0)
+        return defaultValue;
+    return Math.min(value, maxValue);
+}
+function normalizeOptionalBoundedPositiveInteger(value, maxValue) {
+    if (!Number.isInteger(value) || value <= 0)
+        return null;
+    return Math.min(value, maxValue);
+}
+function normalizeBeforeSequence(value) {
+    if (!Number.isInteger(value) || value <= 0)
+        return null;
+    return value;
+}
+function normalizeStringFilters(values) {
+    if (!Array.isArray(values))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        const normalized = value.trim().toLowerCase();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+const workspaceToolSettingsUpdateSchema = z.object({
+    userId: z.string().trim().min(1),
+    toolId: z.string().trim().min(1),
+    scope: z.enum(['private', 'channel', 'public']),
+    scopeChannelId: z.string().trim().min(1).nullable().optional(),
+    allowSharedExec: z.boolean().optional(),
+    cancelPendingPublicReview: z.boolean().optional(),
+});
+const workspaceToolCloneSchema = z.object({
+    userId: z.string().trim().min(1),
+    toolId: z.string().trim().min(1),
+    targetAgentId: z.string().trim().min(1),
+    slug: z.string().trim().min(1).optional().nullable(),
+    name: z.string().trim().min(1).optional().nullable(),
+    description: z.string().optional().nullable(),
+});
+const workspaceToolVerificationUpdateSchema = z.object({
+    agentId: z.string().trim().min(1),
+    toolId: z.string().trim().min(1),
+    conversationId: z.string().trim().min(1),
+    status: z.enum(['verified', 'failed', 'warning']),
+    summary: z.string().trim().min(1).max(2000),
+    details: z.record(z.string(), z.unknown()).optional().nullable(),
+    smokeRunId: z.string().trim().min(1).optional().nullable(),
+});
+function normalizeMaxActivePersistentRunsPerAgent(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0
+        ? value
+        : DEFAULT_WORKSPACE_TOOL_MAX_ACTIVE_PERSISTENT_RUNS_PER_AGENT;
+}
+function workspaceToolVerificationRowToInfo(row) {
+    let details = null;
+    if (row.detailsJson) {
+        try {
+            const parsed = JSON.parse(row.detailsJson);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                details = parsed;
+            }
+        }
+        catch {
+            details = null;
+        }
+    }
+    return {
+        verificationId: row.verificationId,
+        toolId: row.toolId,
+        toolRevision: row.toolRevision,
+        sourceToolId: row.sourceToolId,
+        sourceRevision: row.sourceRevision,
+        targetAgentId: row.targetAgentId,
+        targetNodeId: row.targetNodeId,
+        targetWorkspacePath: row.targetWorkspacePath,
+        conversationId: row.conversationId,
+        status: row.status,
+        summary: row.summary,
+        details,
+        smokeRunId: row.smokeRunId,
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        updatedAt: row.updatedAt,
+    };
+}
+function findWorkspaceToolVerificationStatusAction(manifest) {
+    return manifest.actions.find((action) => (action.kind === 'status'
+        && (action.paramsSchema?.length ?? 0) === 0)) ?? null;
+}
+function isWorkspaceFileMissingError(error) {
+    const message = String(error?.message ?? error).toLowerCase();
+    return message.includes('not_found') || message.includes('path not found');
+}
+function extractRuntimeLogTimestampMs(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainRecord(parsed))
+        return null;
+    for (const key of ['timestamp', 'time', 'createdAt', 'updatedAt', 'ts']) {
+        const raw = parsed[key];
+        if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0) {
+            return raw < 1_000_000_000_000 ? Math.floor(raw * 1000) : Math.floor(raw);
+        }
+        if (typeof raw === 'string' && raw.trim()) {
+            const timestamp = Date.parse(raw);
+            if (Number.isFinite(timestamp))
+                return timestamp;
+        }
+    }
+    return null;
+}
+function normalizeRuntimeLogDirCandidate(value) {
+    const normalized = path.posix.normalize(value.replace(/\\/g, '/')).replace(/^\.\/+/, '').replace(/\/+$/, '');
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+function normalizeWorkspaceToolUploadPathCandidate(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = path.posix.normalize(value.replace(/\\/g, '/')).replace(/^\.\/+/, '').replace(/\/+$/, '');
+    if (!normalized
+        || normalized === '.'
+        || normalized === '..'
+        || normalized.startsWith('../')
+        || path.posix.isAbsolute(normalized)
+        || !normalized.includes('/uploads/')
+        || !normalized.startsWith('.agent-tools-runtime/')) {
+        return null;
+    }
+    return normalized;
+}
+function normalizeWorkspaceToolCloneSlug(value) {
+    const slug = value.trim();
+    const normalizedPath = path.posix.normalize(slug.replace(/\\/g, '/'));
+    if (!slug
+        || slug.includes('/')
+        || slug.includes('\\')
+        || slug === '.'
+        || slug === '..'
+        || normalizedPath === '..'
+        || normalizedPath.startsWith('../')
+        || path.posix.isAbsolute(normalizedPath)) {
+        throw new WorkspaceToolServiceError('Tool clone slug must be a single workspace-safe path segment.', 400);
+    }
+    return slug;
+}
+function workspaceToolCloneManifestHasSourcePathReferences(manifest, sourceSlug) {
+    const roots = [
+        `.agent-tools/${sourceSlug}`,
+        `.agent-tools-runtime/${sourceSlug}`,
+    ];
+    const visits = new Set();
+    const stringContainsRoot = (value, root) => {
+        const text = value.replace(/\\/g, '/');
+        let index = text.indexOf(root);
+        while (index >= 0) {
+            const before = index > 0 ? text[index - 1] : '';
+            const after = text[index + root.length] ?? '';
+            const beforeOk = !before || !/[A-Za-z0-9_.-]/.test(before);
+            const afterOk = !after || after === '/' || !/[A-Za-z0-9_.-]/.test(after);
+            if (beforeOk && afterOk)
+                return true;
+            index = text.indexOf(root, index + root.length);
+        }
+        return false;
+    };
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            return roots.some((root) => stringContainsRoot(value, root));
+        }
+        if (!value || typeof value !== 'object' || visits.has(value))
+            return false;
+        visits.add(value);
+        if (Array.isArray(value))
+            return value.some((item) => visit(item));
+        return Object.values(value).some((item) => visit(item));
+    };
+    return visit(manifest);
+}
+function collectWorkspaceToolUploadPathsFromParamsJson(paramsJson) {
+    if (!paramsJson)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(paramsJson);
+    }
+    catch {
+        return [];
+    }
+    const paths = new Set();
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!isPlainRecord(value))
+            return;
+        if (value.type === 'workspace_tool_upload') {
+            const candidate = normalizeWorkspaceToolUploadPathCandidate(value.workspacePath ?? value.path);
+            if (candidate)
+                paths.add(candidate);
+        }
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    visit(parsed);
+    return [...paths];
+}
+export class WorkspaceToolService {
+    db;
+    conversationManager;
+    workspaceBroker;
+    terminalBroker;
+    onStateUpdated;
+    mutationQueues = new WorkspaceToolMutationQueues();
+    maxActivePersistentRunsPerAgent;
+    actionRunner;
+    publishIdentityResolver;
+    readModel;
+    snapshotPanels;
+    latestStateProjector;
+    logRetentionTimer = null;
+    constructor(params) {
+        this.db = params.db;
+        this.conversationManager = params.conversationManager;
+        this.workspaceBroker = params.workspaceBroker;
+        this.terminalBroker = params.terminalBroker;
+        this.onStateUpdated = params.onStateUpdated;
+        this.maxActivePersistentRunsPerAgent = normalizeMaxActivePersistentRunsPerAgent(params.maxActivePersistentRunsPerAgent);
+        this.readModel = new WorkspaceToolReadModel(this.db);
+        this.snapshotPanels = new WorkspaceToolSnapshotPanelSyncer({
+            db: this.db,
+            conversations: this.conversationManager,
+        });
+        this.latestStateProjector = new WorkspaceToolLatestStateProjector({
+            snapshotPanels: this.snapshotPanels,
+            onStateUpdated: this.onStateUpdated,
+            getToolInfoForActionViewer: (userId, toolId, allowAdminBypass) => this.getToolInfoForActionViewer(userId, toolId, allowAdminBypass),
+        });
+        this.publishIdentityResolver = new WorkspaceToolPublishIdentityResolver(this.db);
+        this.actionRunner = new WorkspaceToolActionRunner({
+            db: this.db,
+            conversationManager: this.conversationManager,
+            terminalBroker: this.terminalBroker,
+            silentStatusRefreshRetryDelayMs: Math.max(0, params.silentStatusRefreshRetryDelayMs ?? 200),
+            loadUsername: (userId) => this.readModel.loadUsername(userId),
+            isAdminUser: (userId) => this.readModel.isAdminUser(userId),
+            enqueueToolMutation: (toolId, work) => this.mutationQueues.enqueueTool(toolId, work),
+            enqueueAgentPersistentStart: (agentId, work) => this.mutationQueues.enqueueAgentPersistentStart(agentId, work),
+            maxActivePersistentRunsPerAgent: this.maxActivePersistentRunsPerAgent,
+            notifyAgentForToolAction: (runnerParams) => this.notifyAgentForToolAction(runnerParams),
+            getToolInfoForActionViewer: (userId, toolId, allowAdminBypass) => this.getToolInfoForActionViewer(userId, toolId, allowAdminBypass),
+            recordPlatformExecNotification: (runnerParams) => this.recordPlatformExecNotification(runnerParams),
+            latestStateProjector: this.latestStateProjector,
+            readWorkspaceFile: (nodeId, workspaceRoot, relativePath, options) => this.workspaceBroker.readFile(nodeId, workspaceRoot, relativePath, options),
+            writeWorkspaceFile: (nodeId, workspaceRoot, relativePath, content, mode, options) => this.workspaceBroker.writeFile(nodeId, workspaceRoot, relativePath, content, mode, options),
+            deleteWorkspaceFile: (nodeId, workspaceRoot, relativePath) => this.workspaceBroker.deleteFile(nodeId, workspaceRoot, relativePath),
+        });
+        this.terminalBroker.onTerminalTermination((event) => {
+            void this.actionRunner.handleTerminalTermination(event).catch((error) => {
+                log.warn('[workspace-tools] terminal termination cleanup failed', {
+                    terminalId: event.terminalId,
+                    error: String(error?.message ?? error),
+                });
+            });
+        });
+        this.terminalBroker.onOutput((event) => {
+            this.actionRunner.processTerminalOutput(event.terminalId, event.data);
+        });
+    }
+    startLogRetentionScheduler() {
+        if (this.logRetentionTimer)
+            return;
+        void this.cleanupExpiredLogs().catch((error) => {
+            log.warn('[workspace-tools] log retention cleanup failed', {
+                error: String(error?.message ?? error),
+            });
+        });
+        this.logRetentionTimer = setInterval(() => {
+            void this.cleanupExpiredLogs().catch((error) => {
+                log.warn('[workspace-tools] log retention cleanup failed', {
+                    error: String(error?.message ?? error),
+                });
+            });
+        }, WORKSPACE_TOOL_LOG_RETENTION_INTERVAL_MS);
+    }
+    stopLogRetentionScheduler() {
+        if (!this.logRetentionTimer)
+            return;
+        clearInterval(this.logRetentionTimer);
+        this.logRetentionTimer = null;
+    }
+    async cleanupExpiredLogs(now = Date.now()) {
+        const cutoff = now - WORKSPACE_TOOL_LOG_RETENTION_MS;
+        const cleanupRunSelect = `SELECT wtr.run_id as runId,
+              wtr.tool_id as toolId,
+              wtr.status,
+              wtr.tool_revision as toolRevision,
+              wtr.runtime_log_dir as runtimeLogDir,
+              wtr.execution_node_id as executionNodeId,
+              wtr.execution_workspace_path as executionWorkspacePath,
+              wtr.params_json as paramsJson,
+              wt.manifest_json as manifestJson,
+              wt.revision as currentRevision,
+              a.node_id as currentNodeId,
+              a.workspace_path as currentWorkspacePath
+         FROM workspace_tool_runs wtr
+         JOIN workspace_tools wt ON wt.tool_id = wtr.tool_id
+         LEFT JOIN agents a ON a.agent_id = wt.agent_id`;
+        const expiredRuns = this.db.prepare(`${cleanupRunSelect}
+        WHERE wtr.started_at < ?
+          AND wtr.status != 'running'`).all(cutoff);
+        const overflowRuns = this.db.prepare(`WITH ranked_runs AS (
+         SELECT run_id,
+                ROW_NUMBER() OVER (
+                  PARTITION BY tool_id
+                  ORDER BY started_at DESC, run_id DESC
+                ) as rank
+           FROM workspace_tool_runs
+          WHERE status != 'running'
+       )
+       ${cleanupRunSelect}
+         JOIN ranked_runs rr ON rr.run_id = wtr.run_id
+        WHERE rr.rank > ?`).all(WORKSPACE_TOOL_RUN_HISTORY_MAX_STORED_PER_TOOL);
+        const cleanupRunById = new Map();
+        for (const run of [...expiredRuns, ...overflowRuns]) {
+            cleanupRunById.set(run.runId, run);
+        }
+        const cleanupRuns = [...cleanupRunById.values()];
+        const skippedRunningRuns = this.db.prepare(`SELECT COUNT(*) as count
+         FROM workspace_tool_runs
+        WHERE started_at < ?
+          AND status = 'running'`).get(cutoff)?.count ?? 0;
+        let deletedRuntimeFiles = 0;
+        let deletedUploadFiles = 0;
+        let rotatedRuntimeLogs = 0;
+        const rotatedRuntimeKeys = new Set();
+        const activeRuntimeKeys = this.loadActiveRuntimeLogKeys();
+        const deletableRunIds = [];
+        for (const run of cleanupRuns) {
+            deletableRunIds.push(run.runId);
+            const targetNodeId = run.executionNodeId?.trim()
+                || (run.toolRevision === run.currentRevision ? run.currentNodeId?.trim() : null);
+            const targetWorkspacePath = run.executionWorkspacePath?.trim()
+                || (run.toolRevision === run.currentRevision ? run.currentWorkspacePath?.trim() : null);
+            if (targetNodeId && targetWorkspacePath) {
+                for (const uploadPath of collectWorkspaceToolUploadPathsFromParamsJson(run.paramsJson)) {
+                    if (await this.deleteWorkspaceToolUploadFileBestEffort(targetNodeId, targetWorkspacePath, uploadPath)) {
+                        deletedUploadFiles += 1;
+                    }
+                }
+            }
+            const logDir = run.runtimeLogDir?.trim()
+                ? normalizeRuntimeLogDirCandidate(run.runtimeLogDir)
+                : run.toolRevision === run.currentRevision
+                    ? this.resolveRuntimeLogDir(run.toolId, run.manifestJson)
+                    : null;
+            if (!logDir)
+                continue;
+            if (!targetNodeId || !targetWorkspacePath)
+                continue;
+            if (await this.deleteRuntimeLogFileBestEffort(targetNodeId, targetWorkspacePath, path.posix.join(logDir, 'runs', `${run.runId}.jsonl`))) {
+                deletedRuntimeFiles += 1;
+            }
+            const runtimeKey = `${targetNodeId}\0${targetWorkspacePath}\0${logDir}`;
+            if (!activeRuntimeKeys.has(runtimeKey) && !rotatedRuntimeKeys.has(runtimeKey)) {
+                rotatedRuntimeKeys.add(runtimeKey);
+                if (await this.rotateRuntimeLifecycleLogBestEffort(targetNodeId, targetWorkspacePath, path.posix.join(logDir, 'runtime.jsonl'), cutoff)) {
+                    rotatedRuntimeLogs += 1;
+                }
+            }
+        }
+        let deletedEvents = 0;
+        let deletedArtifacts = 0;
+        if (deletableRunIds.length > 0) {
+            const placeholders = deletableRunIds.map(() => '?').join(', ');
+            deletedArtifacts = this.db.prepare(`SELECT COUNT(*) as count
+           FROM workspace_tool_run_artifacts
+          WHERE run_id IN (${placeholders})`).get(...deletableRunIds)?.count ?? 0;
+            deletedEvents = this.db.prepare(`SELECT COUNT(*) as count
+           FROM workspace_tool_run_events
+          WHERE run_id IN (${placeholders})`).get(...deletableRunIds)?.count ?? 0;
+            const tx = this.db.transaction(() => {
+                this.db.prepare(`DELETE FROM workspace_tool_run_artifacts
+            WHERE run_id IN (${placeholders})`).run(...deletableRunIds);
+                this.db.prepare(`DELETE FROM workspace_tool_run_events
+            WHERE run_id IN (${placeholders})`).run(...deletableRunIds);
+                this.db.prepare(`DELETE FROM workspace_tool_runs
+            WHERE run_id IN (${placeholders})`).run(...deletableRunIds);
+            });
+            tx();
+        }
+        const result = {
+            deletedRuns: deletableRunIds.length,
+            deletedEvents,
+            deletedArtifacts,
+            deletedRuntimeFiles,
+            deletedUploadFiles,
+            rotatedRuntimeLogs,
+            skippedRunningRuns,
+        };
+        if (deletedArtifacts > 0 || deletedEvents > 0 || cleanupRuns.length > 0 || deletedRuntimeFiles > 0 || deletedUploadFiles > 0 || rotatedRuntimeLogs > 0 || skippedRunningRuns > 0) {
+            log.info('[workspace-tools] log retention cleanup complete', result);
+        }
+        return result;
+    }
+    loadActiveRuntimeLogKeys() {
+        const rows = this.db.prepare(`SELECT wt.tool_id as toolId,
+              wt.manifest_json as manifestJson,
+              a.node_id as nodeId,
+              a.workspace_path as workspacePath
+         FROM workspace_tools wt
+         JOIN agents a ON a.agent_id = wt.agent_id
+        WHERE wt.active_terminal_id IS NOT NULL`).all();
+        const keys = new Set();
+        for (const row of rows) {
+            if (!row.nodeId || !row.workspacePath)
+                continue;
+            const logDir = this.resolveRuntimeLogDir(row.toolId, row.manifestJson);
+            if (!logDir)
+                continue;
+            keys.add(`${row.nodeId}\0${row.workspacePath}\0${logDir}`);
+        }
+        return keys;
+    }
+    resolveRuntimeLogDir(toolId, manifestJson) {
+        try {
+            const manifest = parseWorkspaceToolManifest(manifestJson);
+            if (manifest.runtime?.mode !== 'persistent_runtime')
+                return null;
+            const raw = manifest.runtime.logDir?.trim() || `.agent-tools-runtime/${toolId}`;
+            return normalizeRuntimeLogDirCandidate(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async deleteRuntimeLogFileBestEffort(nodeId, workspaceRoot, relativePath) {
+        try {
+            await this.workspaceBroker.deleteFile(nodeId, workspaceRoot, relativePath);
+            return true;
+        }
+        catch (error) {
+            if (!isWorkspaceFileMissingError(error)) {
+                log.warn('[workspace-tools] runtime log file cleanup failed', {
+                    nodeId,
+                    relativePath,
+                    error: String(error?.message ?? error),
+                });
+            }
+            return false;
+        }
+    }
+    async deleteWorkspaceToolUploadFileBestEffort(nodeId, workspaceRoot, relativePath) {
+        try {
+            await this.workspaceBroker.deleteFile(nodeId, workspaceRoot, relativePath);
+            return true;
+        }
+        catch (error) {
+            if (!isWorkspaceFileMissingError(error)) {
+                log.warn('[workspace-tools] upload staging file cleanup failed', {
+                    nodeId,
+                    relativePath,
+                    error: String(error?.message ?? error),
+                });
+            }
+            return false;
+        }
+    }
+    async deleteRuntimeLogDirBestEffort(nodeId, workspaceRoot, relativePath) {
+        try {
+            await this.workspaceBroker.deletePath(nodeId, workspaceRoot, relativePath, { recursive: true });
+            return true;
+        }
+        catch (error) {
+            if (!isWorkspaceFileMissingError(error)) {
+                log.warn('[workspace-tools] runtime log directory cleanup failed', {
+                    nodeId,
+                    relativePath,
+                    error: String(error?.message ?? error),
+                });
+            }
+            return false;
+        }
+    }
+    async cleanupDeletedToolWorkspaceFilesBestEffort(tool, options = {}) {
+        const runRows = this.db.prepare(`SELECT run_id as runId,
+              params_json as paramsJson,
+              runtime_log_dir as runtimeLogDir,
+              execution_node_id as executionNodeId,
+              execution_workspace_path as executionWorkspacePath
+         FROM workspace_tool_runs
+        WHERE tool_id = ?`).all(tool.toolId);
+        let deletedUploadFiles = 0;
+        let deletedRuntimeFiles = 0;
+        const runtimeDirs = new Map();
+        const defaultRuntimeLogDir = `.agent-tools-runtime/${tool.toolId}`;
+        const defaultTarget = tool.agentNodeId?.trim() && tool.agentWorkspacePath?.trim()
+            ? { nodeId: tool.agentNodeId.trim(), workspaceRoot: tool.agentWorkspacePath.trim() }
+            : null;
+        const manifestLogDir = this.resolveRuntimeLogDir(tool.toolId, tool.manifestJson);
+        if (!options.skipRuntimeLogCleanup && manifestLogDir === defaultRuntimeLogDir && defaultTarget) {
+            runtimeDirs.set(`${defaultTarget.nodeId}\0${defaultTarget.workspaceRoot}\0${manifestLogDir}`, {
+                ...defaultTarget,
+                relativePath: manifestLogDir,
+            });
+        }
+        for (const row of runRows) {
+            const target = row.executionNodeId?.trim() && row.executionWorkspacePath?.trim()
+                ? { nodeId: row.executionNodeId.trim(), workspaceRoot: row.executionWorkspacePath.trim() }
+                : defaultTarget;
+            if (!target)
+                continue;
+            for (const uploadPath of collectWorkspaceToolUploadPathsFromParamsJson(row.paramsJson)) {
+                if (await this.deleteWorkspaceToolUploadFileBestEffort(target.nodeId, target.workspaceRoot, uploadPath)) {
+                    deletedUploadFiles += 1;
+                }
+            }
+            const runLogDir = row.runtimeLogDir?.trim()
+                ? normalizeRuntimeLogDirCandidate(row.runtimeLogDir)
+                : null;
+            if (runLogDir) {
+                if (!options.skipRuntimeLogCleanup) {
+                    if (await this.deleteRuntimeLogFileBestEffort(target.nodeId, target.workspaceRoot, path.posix.join(runLogDir, 'runs', `${row.runId}.jsonl`))) {
+                        deletedRuntimeFiles += 1;
+                    }
+                    if (runLogDir === defaultRuntimeLogDir) {
+                        runtimeDirs.set(`${target.nodeId}\0${target.workspaceRoot}\0${runLogDir}`, {
+                            ...target,
+                            relativePath: runLogDir,
+                        });
+                    }
+                }
+            }
+        }
+        let deletedRuntimeDirs = 0;
+        for (const runtimeDir of runtimeDirs.values()) {
+            if (await this.deleteRuntimeLogDirBestEffort(runtimeDir.nodeId, runtimeDir.workspaceRoot, runtimeDir.relativePath)) {
+                deletedRuntimeDirs += 1;
+            }
+        }
+        if (deletedUploadFiles > 0 || deletedRuntimeFiles > 0 || deletedRuntimeDirs > 0) {
+            log.info('[workspace-tools] deleted tool workspace cleanup complete', {
+                toolId: tool.toolId,
+                deletedUploadFiles,
+                deletedRuntimeFiles,
+                deletedRuntimeDirs,
+            });
+        }
+    }
+    async rotateRuntimeLifecycleLogBestEffort(nodeId, workspaceRoot, relativePath, cutoff) {
+        try {
+            const content = await this.readWorkspaceTextFileInChunks(nodeId, workspaceRoot, relativePath);
+            if (!content)
+                return false;
+            const lines = content.split('\n').filter((line) => line.trim());
+            const kept = lines.filter((line) => {
+                const timestamp = extractRuntimeLogTimestampMs(line);
+                return timestamp === null || timestamp >= cutoff;
+            });
+            let nextLines = kept;
+            const removedOldLines = kept.length !== lines.length;
+            const oversized = content.length > WORKSPACE_TOOL_RUNTIME_LOG_MAX_BYTES_BEFORE_ROTATE;
+            if (oversized && nextLines.join('\n').length > WORKSPACE_TOOL_RUNTIME_LOG_MAX_BYTES_BEFORE_ROTATE) {
+                nextLines = nextLines.slice(-1000);
+            }
+            if (!removedOldLines && !oversized)
+                return false;
+            const nextContent = nextLines.length > 0 ? `${nextLines.join('\n')}\n` : '';
+            await this.workspaceBroker.writeFile(nodeId, workspaceRoot, relativePath, nextContent, 'overwrite', {
+                scaffold: false,
+            });
+            return true;
+        }
+        catch (error) {
+            if (!isWorkspaceFileMissingError(error)) {
+                log.warn('[workspace-tools] runtime lifecycle log rotation failed', {
+                    nodeId,
+                    relativePath,
+                    error: String(error?.message ?? error),
+                });
+            }
+            return false;
+        }
+    }
+    async readWorkspaceTextFileInChunks(nodeId, workspaceRoot, relativePath) {
+        let offset = 0;
+        let content = '';
+        while (true) {
+            const chunk = await this.workspaceBroker.readFile(nodeId, workspaceRoot, relativePath, {
+                scaffold: false,
+                offset,
+                limit: 256 * 1024,
+            });
+            content += chunk.content;
+            if (!chunk.hasMore || chunk.nextOffset == null || chunk.nextOffset <= offset)
+                break;
+            offset = chunk.nextOffset;
+        }
+        return content;
+    }
+    async listToolsForUser(userId) {
+        return this.listToolsForViewer(userId);
+    }
+    async listToolsForViewer(userId) {
+        const rows = this.readModel.loadVisibleToolRowsForViewer(userId);
+        return rows.map((row) => this.readModel.rowToToolInfoForViewer(this.ensureReadableToolSnapshotPanel(row, userId), userId));
+    }
+    async getToolForUser(userId, toolId) {
+        return this.getToolForViewer(userId, toolId);
+    }
+    async getToolForViewer(userId, toolId) {
+        const row = this.readModel.loadToolRowForViewer(userId, toolId);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return this.readModel.rowToToolInfoForViewer(this.ensureReadableToolSnapshotPanel(row, userId), userId);
+    }
+    async getToolForViewerByPanelId(userId, panelId) {
+        const row = this.readModel.loadToolRowByPanelIdForViewer(userId, panelId);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return this.readModel.rowToToolInfoForViewer(this.ensureReadableToolSnapshotPanel(row, userId), userId);
+    }
+    async getToolMediaLookupForViewer(userId, toolId, options) {
+        const row = this.readModel.loadToolRowForViewer(userId, toolId, options);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return {
+            tool: this.readModel.rowToToolInfoForViewer(row, userId),
+            sourceBundleRoot: row.bundleRoot,
+        };
+    }
+    async listToolCollaboratorsForViewer(userId, toolId) {
+        const row = this.readModel.loadToolRowForViewer(userId, toolId);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        ensureSurfaceOwner(this.db, {
+            surfaceType: 'tool',
+            surfaceId: row.toolId,
+            agentId: row.agentId,
+            createdAt: row.createdAt,
+        });
+        return {
+            toolId: row.toolId,
+            canManage: this.readModel.canManageToolCollaborators(userId, row),
+            collaborators: listSurfaceCollaborators(this.db, 'tool', row.toolId).map((collaborator) => {
+                const agent = this.conversationManager.getAgent(collaborator.agentId);
+                return {
+                    agentId: collaborator.agentId,
+                    name: agent?.name ?? null,
+                    role: collaborator.role,
+                    addedBy: collaborator.addedBy ?? null,
+                    createdAt: new Date(collaborator.createdAt).toISOString(),
+                };
+            }),
+        };
+    }
+    async addToolCollaboratorForViewer(params) {
+        const row = this.readModel.loadToolRowForViewer(params.userId, params.toolId, { allowAdminBypass: true });
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        if (!this.readModel.canManageToolCollaborators(params.userId, row)) {
+            throw new WorkspaceToolServiceError('Access denied.', 403);
+        }
+        const collaboratorAgent = this.conversationManager.getAgent(params.collaboratorAgentId);
+        if (!collaboratorAgent || (collaboratorAgent.agentRole && collaboratorAgent.agentRole !== 'user')) {
+            throw new WorkspaceToolServiceError('Collaborator agent not found.', 404);
+        }
+        ensureSurfaceOwner(this.db, {
+            surfaceType: 'tool',
+            surfaceId: row.toolId,
+            agentId: row.agentId,
+            createdAt: row.createdAt,
+        });
+        if (collaboratorAgent.agentId === row.agentId) {
+            return this.listToolCollaboratorsForViewer(params.userId, row.toolId);
+        }
+        if (!this.readModel.isAdminUser(params.userId) && !getUserAgentAccess(this.db, params.userId).includes(collaboratorAgent.agentId)) {
+            throw new WorkspaceToolServiceError('Access denied.', 403);
+        }
+        upsertSurfaceCollaborator(this.db, {
+            surfaceType: 'tool',
+            surfaceId: row.toolId,
+            agentId: collaboratorAgent.agentId,
+            role: 'collaborator',
+            addedBy: `user:${params.userId}`,
+        });
+        return this.listToolCollaboratorsForViewer(params.userId, row.toolId);
+    }
+    async removeToolCollaboratorForViewer(params) {
+        const row = this.readModel.loadToolRowForViewer(params.userId, params.toolId, { allowAdminBypass: true });
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        if (!this.readModel.canManageToolCollaborators(params.userId, row)) {
+            throw new WorkspaceToolServiceError('Access denied.', 403);
+        }
+        ensureSurfaceOwner(this.db, {
+            surfaceType: 'tool',
+            surfaceId: row.toolId,
+            agentId: row.agentId,
+            createdAt: row.createdAt,
+        });
+        const role = getSurfaceCollaboratorRole(this.db, 'tool', row.toolId, params.collaboratorAgentId);
+        if (!role) {
+            throw new WorkspaceToolServiceError('Collaborator not found.', 404);
+        }
+        if (role === 'owner') {
+            throw new WorkspaceToolServiceError('Tool owner cannot be removed.', 400);
+        }
+        removeSurfaceCollaborator(this.db, 'tool', row.toolId, params.collaboratorAgentId);
+        return this.listToolCollaboratorsForViewer(params.userId, row.toolId);
+    }
+    resolvePanelPromotionStateForUser(params) {
+        const promotion = params.promotion ?? this.loadPanelToolPromotion(params.panel.id);
+        const eligible = this.isPanelEligibleForToolPromotion(params.userId, params.panel)
+            && !params.panel.archivedAt;
+        const directManifest = eligible && !promotion?.toolId
+            ? buildDirectPromotedToolManifest(params.panel)
+            : null;
+        let retryUnavailableReason = null;
+        if (isDeletedLinkedToolPromotionRetryable(promotion)) {
+            const sourceConversation = this.conversationManager.getConversation(params.panel.conversationId);
+            if (!sourceConversation?.agentId) {
+                retryUnavailableReason = 'Panel source conversation is unavailable.';
+            }
+            else {
+                const availability = getWorkspaceToolAgentAvailability(this.db, this.conversationManager.getAgent(sourceConversation.agentId));
+                if (!availability.allowed) {
+                    retryUnavailableReason = availability.error;
+                }
+            }
+        }
+        const resolved = resolveWorkspaceToolPromotionState({
+            panelId: params.panel.id,
+            panelArchivedAt: params.panel.archivedAt ?? null,
+            eligible,
+            directPromotable: Boolean(directManifest),
+            promotion,
+            ineligibleReason: params.panel.archivedAt && !promotion
+                ? 'Panel is archived.'
+                : 'This panel cannot be upgraded to a tool.',
+            retryUnavailableReason,
+        });
+        return { promotion, directManifest, resolved };
+    }
+    getPanelPromotionInfoForUser(userId, panelId) {
+        const panel = getPanelById(this.db, panelId);
+        if (!panel) {
+            return null;
+        }
+        const state = this.resolvePanelPromotionStateForUser({ userId, panel });
+        if (state.resolved.state === 'ineligible' && !state.promotion) {
+            return null;
+        }
+        return {
+            panelId,
+            state: state.resolved.state,
+            stateReason: state.resolved.stateReason,
+            ctaLabel: state.resolved.ctaLabel,
+            disabledReason: state.resolved.disabledReason,
+            promotionConversationId: state.promotion?.promotionConversationId ?? null,
+            toolId: state.promotion?.toolId ?? null,
+            toolName: state.promotion?.toolName ?? null,
+            toolRevision: state.promotion?.toolRevision ?? null,
+            maintenanceConversationId: state.promotion?.maintenanceConversationId ?? null,
+        };
+    }
+    async promotePanelToTool(params) {
+        return this.mutationQueues.enqueuePanelPromotion(params.panelId, async () => {
+            const panel = getPanelById(this.db, params.panelId);
+            if (!panel) {
+                throw new WorkspaceToolServiceError('Panel not found.', 404);
+            }
+            const state = this.resolvePanelPromotionStateForUser({ userId: params.userId, panel });
+            const existingPromotion = state.promotion;
+            if (state.resolved.shouldOpenLinkedTool) {
+                const linkedTool = await this.openLinkedPanelPromotionTool(params.userId, existingPromotion);
+                if (linkedTool)
+                    return linkedTool;
+                throw new WorkspaceToolServiceError('Linked Workspace Tool is unavailable.', 404);
+            }
+            if (state.resolved.shouldReturnPendingPromotion && existingPromotion) {
+                const promotionConversation = this.ensurePanelPromotionConversation({
+                    panel,
+                    userId: params.userId,
+                    existingConversationId: existingPromotion.promotionConversationId,
+                });
+                if (!promotionConversation) {
+                    throw new WorkspaceToolServiceError('Unable to open the panel promotion conversation.', 500);
+                }
+                if (existingPromotion.promotionConversationId !== promotionConversation.id) {
+                    this.db.prepare(`UPDATE panel_tool_promotions
+                SET promotion_conversation_id = ?,
+                    updated_at = ?
+              WHERE panel_id = ?`).run(promotionConversation.id, Date.now(), panel.id);
+                }
+                return {
+                    kind: 'promotion',
+                    conversation: promotionConversation,
+                    queued: false,
+                };
+            }
+            if (state.resolved.state === 'ineligible') {
+                throw new WorkspaceToolServiceError(state.resolved.disabledReason
+                    ?? (panel.archivedAt && !existingPromotion ? 'Panel is archived.' : 'This panel cannot be upgraded to a tool.'), panel.archivedAt && !existingPromotion ? 410 : 409);
+            }
+            const sourceConversation = this.conversationManager.getConversation(panel.conversationId);
+            if (!sourceConversation?.agentId) {
+                throw new WorkspaceToolServiceError('Panel source conversation is unavailable.', 409);
+            }
+            this.assertWorkspaceToolAgentAvailable(sourceConversation.agentId);
+            if (state.resolved.shouldCreateDirectTool && state.directManifest) {
+                return this.createDirectPromotedTool({
+                    userId: params.userId,
+                    panel,
+                    agentId: sourceConversation.agentId,
+                    manifest: state.directManifest,
+                    existingPromotion,
+                });
+            }
+            const promotionConversation = this.ensurePanelPromotionConversation({
+                panel,
+                userId: params.userId,
+                activeProjectId: sourceConversation.activeProjectId ?? null,
+                existingConversationId: existingPromotion?.promotionConversationId ?? null,
+            });
+            if (!promotionConversation) {
+                throw new WorkspaceToolServiceError('Unable to open the panel promotion conversation.', 500);
+            }
+            const shouldRequeueDeletedPromotion = state.resolved.shouldRequeueDeletedPromotion;
+            if (existingPromotion) {
+                if (existingPromotion.promotionConversationId !== promotionConversation.id) {
+                    this.db.prepare(`UPDATE panel_tool_promotions
+                SET promotion_conversation_id = ?,
+                    updated_at = ?
+              WHERE panel_id = ?`).run(promotionConversation.id, shouldRequeueDeletedPromotion ? existingPromotion.updatedAt : Date.now(), panel.id);
+                }
+                if (state.resolved.shouldReturnPendingPromotion) {
+                    return {
+                        kind: 'promotion',
+                        conversation: promotionConversation,
+                        queued: false,
+                    };
+                }
+            }
+            const username = this.readModel.loadUsername(params.userId);
+            if (!username) {
+                throw new WorkspaceToolServiceError('Unable to resolve the requesting user.', 500);
+            }
+            const now = Date.now();
+            if (!existingPromotion) {
+                this.db.prepare(`INSERT INTO panel_tool_promotions(
+             panel_id,
+             user_id,
+             agent_id,
+             promotion_conversation_id,
+             tool_id,
+             created_at,
+             updated_at
+           )
+           VALUES(?, ?, ?, ?, NULL, ?, ?)`).run(panel.id, params.userId, sourceConversation.agentId, promotionConversation.id, now, now);
+            }
+            const bodyText = this.buildPanelPromotionSlashBody(panel);
+            const rawText = `/tool ${bodyText}`;
+            try {
+                const result = await this.conversationManager.submitPrompt(promotionConversation.id, rawText, {
+                    senderName: username,
+                    clientMessageId: randomUUID(),
+                    activationMetadata: {
+                        slashCommand: {
+                            name: 'tool',
+                            bodyText,
+                        },
+                    },
+                    allowActiveSteer: false,
+                });
+                if (shouldRequeueDeletedPromotion) {
+                    this.db.prepare(`UPDATE panel_tool_promotions
+                SET tool_id = NULL,
+                    updated_at = ?
+              WHERE panel_id = ?
+                AND tool_id = ?`).run(Date.now(), panel.id, existingPromotion?.linkedToolId ?? '');
+                }
+                return {
+                    kind: 'promotion',
+                    conversation: promotionConversation,
+                    queued: result.queued,
+                    ...(result.runId ? { runId: result.runId } : {}),
+                };
+            }
+            catch (error) {
+                if (!existingPromotion) {
+                    this.db.prepare(`DELETE FROM panel_tool_promotions
+              WHERE panel_id = ?
+                AND tool_id IS NULL`).run(panel.id);
+                }
+                throw error;
+            }
+        });
+    }
+    async reopenLinkedPanelPromotionTool(params) {
+        return this.mutationQueues.enqueuePanelPromotion(params.panelId, async () => {
+            const panel = getPanelById(this.db, params.panelId);
+            if (!panel) {
+                throw new WorkspaceToolServiceError('Panel not found.', 404);
+            }
+            return this.openLinkedPanelPromotionTool(params.userId, this.loadPanelToolPromotion(panel.id));
+        });
+    }
+    async openLinkedPanelPromotionTool(userId, promotion) {
+        if (!promotion?.toolId)
+            return null;
+        const tool = await this.getToolForUser(userId, promotion.toolId);
+        const conversation = await this.getOrOpenMaintenanceConversation(userId, tool.toolId);
+        return {
+            kind: 'tool',
+            tool,
+            conversation,
+        };
+    }
+    async createDirectPromotedTool(params) {
+        const now = Date.now();
+        const toolId = randomUUID();
+        const maintenanceConversation = this.ensureMaintenanceConversation({
+            toolId,
+            agentId: params.agentId,
+            userId: params.userId,
+        });
+        if (!maintenanceConversation) {
+            throw new WorkspaceToolServiceError('Unable to open the tool maintenance conversation.', 500);
+        }
+        const agent = this.conversationManager.getAgent(params.agentId);
+        const staleCachedStoragePaths = [];
+        const tx = this.db.transaction(() => {
+            const snapshotSync = this.snapshotPanels.syncPanel({
+                sourcePanelId: params.panel.id,
+                toolId,
+                userId: params.userId,
+                agentId: params.agentId,
+                conversationId: maintenanceConversation.id,
+                nodeId: agent?.nodeId ?? null,
+                manifest: params.manifest,
+                latestState: null,
+                allowSharedExec: false,
+                status: 'idle',
+            });
+            staleCachedStoragePaths.push(...snapshotSync.staleCachedStoragePaths);
+            this.db.prepare(`INSERT INTO workspace_tools(
+           tool_id,
+           user_id,
+           agent_id,
+           slug,
+           name,
+           description,
+           icon,
+           scope,
+           scope_channel_id,
+           allow_shared_exec,
+           public_review_status,
+           pending_public_review,
+           manifest_path,
+           bundle_root,
+           source_panel_id,
+           panel_id,
+           manifest_json,
+           latest_state_json,
+           active_terminal_id,
+           maintenance_conversation_id,
+           source_conversation_id,
+           source_message_id,
+           revision,
+           created_at,
+           updated_at,
+           deleted_at
+         )
+         VALUES(
+           ?, ?, ?, ?, ?, ?, ?, 'private', NULL, 0, 'not_requested', 0,
+           ?, ?, ?, ?, ?,
+           NULL,
+           NULL,
+           ?, ?, NULL, 1, ?, ?,
+           NULL
+         )`).run(toolId, params.userId, params.agentId, params.manifest.slug, params.manifest.name, params.manifest.description, params.manifest.icon ?? null, `panel://${params.panel.id}`, '', params.panel.id, snapshotSync.panelId, JSON.stringify(withPersistedToolSettings(params.manifest, {
+                scope: 'private',
+                scopeChannelId: null,
+                allowSharedExec: false,
+            })), maintenanceConversation.id, params.panel.conversationId, now, now);
+            ensureSurfaceOwner(this.db, {
+                surfaceType: 'tool',
+                surfaceId: toolId,
+                agentId: params.agentId,
+                createdAt: now,
+            });
+            this.copyPanelMaintainersToTool({
+                panelId: params.panel.id,
+                toolId,
+                executionAgentId: params.agentId,
+                createdAt: now,
+            });
+            if (params.existingPromotion) {
+                this.db.prepare(`UPDATE panel_tool_promotions
+              SET promotion_conversation_id = ?,
+                  tool_id = ?,
+                  updated_at = ?
+            WHERE panel_id = ?`).run(maintenanceConversation.id, toolId, now, params.panel.id);
+            }
+            else {
+                this.db.prepare(`INSERT INTO panel_tool_promotions(
+             panel_id,
+             user_id,
+             agent_id,
+             promotion_conversation_id,
+             tool_id,
+             created_at,
+             updated_at
+           )
+           VALUES(?, ?, ?, ?, ?, ?, ?)`).run(params.panel.id, params.userId, params.agentId, maintenanceConversation.id, toolId, now, now);
+            }
+        });
+        tx();
+        unlinkPanelAttachmentStoragePaths(staleCachedStoragePaths);
+        archivePanelWithArtifacts(this.db, {
+            panelId: params.panel.id,
+            now: Date.now(),
+            reason: 'promoted_to_tool',
+        });
+        return {
+            kind: 'tool',
+            tool: await this.getToolForUser(params.userId, toolId),
+            conversation: maintenanceConversation,
+        };
+    }
+    async listRunsForUser(userId, toolId) {
+        return this.listRunsForViewer(userId, toolId);
+    }
+    async listRunsForViewer(userId, toolId, options = {}) {
+        const tool = this.readModel.loadToolRowForViewer(userId, toolId, { allowAdminBypass: true });
+        if (!tool) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        const manifest = parseWorkspaceToolManifest(tool.manifestJson);
+        const actionKindById = new Map(manifest.actions.map((action) => [action.actionId, action.kind]));
+        const limit = normalizeOptionalBoundedPositiveInteger(options.limit, WORKSPACE_TOOL_RUN_LIST_MAX_LIMIT);
+        const queryArgs = [toolId];
+        if (limit != null)
+            queryArgs.push(limit);
+        const rows = this.db.prepare(`SELECT run_id as runId,
+              wtr.tool_id as toolId,
+              tool_revision as toolRevision,
+              action_id as actionId,
+              terminal_id as terminalId,
+              status,
+              params_json as paramsJson,
+              exit_code as exitCode,
+              signal,
+              started_at as startedAt,
+              ended_at as endedAt,
+              requested_by_user_id as requestedByUserId,
+              u.username as requestedByUsername,
+              requested_by_agent_id as requestedByAgentId,
+              a.name as requestedByAgentName,
+              execution_target_kind as executionTargetKind,
+              execution_agent_id as executionAgentId,
+              execution_node_id as executionNodeId,
+              execution_hostname as executionHostname,
+              execution_workspace_path as executionWorkspacePath
+         FROM workspace_tool_runs wtr
+         LEFT JOIN users u ON u.id = wtr.requested_by_user_id
+         LEFT JOIN agents a ON a.agent_id = wtr.requested_by_agent_id
+        WHERE wtr.tool_id = ?
+        ORDER BY started_at DESC
+        ${limit != null ? 'LIMIT ?' : ''}`).all(...queryArgs);
+        const canViewOwnerFields = userId === tool.userId || this.readModel.isAdminUser(userId);
+        const visibleRunIds = rows
+            .filter((row) => canViewOwnerFields || userId === (row.requestedByUserId ?? null))
+            .map((row) => row.runId);
+        const eventsByRunId = options.includeEvents === false
+            ? new Map()
+            : this.loadRunEventsByRunId(visibleRunIds, options.eventLimit);
+        return rows.map((row) => ({
+            ...workspaceToolRunRowToInfoForViewer(row, actionKindById.get(row.actionId), {
+                viewerUserId: userId,
+                ownerUserId: tool.userId,
+                canViewOwnerFields,
+            }),
+            ...(options.includeEvents === false ? {} : { events: eventsByRunId.get(row.runId) ?? [] }),
+        }));
+    }
+    async listRunEventsForViewer(params) {
+        this.loadRunForEventViewer(params.userId, params.toolId, params.runId);
+        const limit = normalizeBoundedPositiveInteger(params.options?.limit, WORKSPACE_TOOL_RUN_EVENT_DEFAULT_LIMIT, WORKSPACE_TOOL_RUN_EVENT_MAX_LIMIT);
+        const beforeSequence = normalizeBeforeSequence(params.options?.beforeSequence);
+        const levelFilters = normalizeStringFilters(params.options?.levels);
+        const args = [params.runId];
+        const filters = ['run_id = ?'];
+        if (beforeSequence != null) {
+            filters.push('sequence < ?');
+            args.push(beforeSequence);
+        }
+        if (levelFilters.length > 0) {
+            const placeholders = levelFilters.map(() => '?').join(', ');
+            filters.push(`(LOWER(COALESCE(level, '')) IN (${placeholders}) OR LOWER(event_type) IN (${placeholders}))`);
+            args.push(...levelFilters, ...levelFilters);
+        }
+        args.push(limit + 1);
+        const rows = this.db.prepare(`SELECT event_id as eventId,
+              run_id as runId,
+              tool_id as toolId,
+              sequence,
+              event_type as eventType,
+              level,
+              summary,
+              payload_json as payloadJson,
+              artifacts_json as artifactsJson,
+              created_at as createdAt
+         FROM workspace_tool_run_events
+        WHERE ${filters.join(' AND ')}
+        ORDER BY sequence DESC
+        LIMIT ?`).all(...args);
+        const pageRows = rows.slice(0, limit);
+        const nextBeforeSequence = rows.length > limit && pageRows.length > 0
+            ? pageRows[pageRows.length - 1].sequence
+            : null;
+        return {
+            events: pageRows.reverse().map(runEventRowToInfo),
+            nextBeforeSequence,
+        };
+    }
+    async listRunArtifactsForViewer(params) {
+        this.loadRunForEventViewer(params.userId, params.toolId, params.runId);
+        const limit = normalizeBoundedPositiveInteger(params.options?.limit, WORKSPACE_TOOL_RUN_ARTIFACT_DEFAULT_LIMIT, WORKSPACE_TOOL_RUN_ARTIFACT_MAX_LIMIT);
+        const beforeSequence = normalizeBeforeSequence(params.options?.beforeSequence);
+        const kindFilters = new Set(normalizeStringFilters(params.options?.kinds));
+        const artifacts = [];
+        let scannedEvents = 0;
+        let exhausted = false;
+        let cursor = beforeSequence;
+        let deferredBeforeSequence = null;
+        let lastIncludedSequence = null;
+        scanLoop: while (artifacts.length < limit && scannedEvents < WORKSPACE_TOOL_RUN_ARTIFACT_MAX_SCANNED_EVENTS) {
+            const args = [params.runId];
+            const filters = [
+                'run_id = ?',
+                'artifacts_json IS NOT NULL',
+                "artifacts_json != ''",
+            ];
+            if (cursor != null) {
+                filters.push('sequence < ?');
+                args.push(cursor);
+            }
+            const batchLimit = Math.min(WORKSPACE_TOOL_RUN_ARTIFACT_SCAN_BATCH, WORKSPACE_TOOL_RUN_ARTIFACT_MAX_SCANNED_EVENTS - scannedEvents);
+            args.push(batchLimit);
+            const rows = this.db.prepare(`SELECT event_id as eventId,
+                run_id as runId,
+                tool_id as toolId,
+                sequence,
+                event_type as eventType,
+                level,
+                summary,
+                payload_json as payloadJson,
+                artifacts_json as artifactsJson,
+                created_at as createdAt
+           FROM workspace_tool_run_events
+          WHERE ${filters.join(' AND ')}
+          ORDER BY sequence DESC
+          LIMIT ?`).all(...args);
+            scannedEvents += rows.length;
+            if (rows.length === 0) {
+                exhausted = true;
+                break;
+            }
+            cursor = rows[rows.length - 1].sequence;
+            let processedRows = 0;
+            for (const row of rows) {
+                const refs = parseWorkspaceToolRunArtifactRefs(row.artifactsJson) ?? [];
+                const matchingRefs = kindFilters.size === 0
+                    ? refs
+                    : refs.filter((artifact) => kindFilters.has((artifact.mimeType ?? '').trim().toLowerCase()));
+                if (matchingRefs.length === 0) {
+                    processedRows += 1;
+                    continue;
+                }
+                if (artifacts.length > 0 && artifacts.length + matchingRefs.length > limit) {
+                    deferredBeforeSequence = row.sequence + 1;
+                    break scanLoop;
+                }
+                for (const artifact of matchingRefs) {
+                    artifacts.push({
+                        eventId: row.eventId,
+                        eventSequence: row.sequence,
+                        eventCreatedAt: row.createdAt,
+                        eventType: row.eventType,
+                        eventSummary: row.summary ?? null,
+                        artifact,
+                    });
+                }
+                lastIncludedSequence = row.sequence;
+                processedRows += 1;
+                if (artifacts.length >= limit)
+                    break;
+            }
+            if (rows.length < batchLimit) {
+                exhausted = processedRows === rows.length;
+                break;
+            }
+            if (artifacts.length >= limit)
+                break;
+        }
+        return {
+            artifacts,
+            nextBeforeSequence: exhausted ? null : deferredBeforeSequence ?? lastIncludedSequence ?? cursor,
+        };
+    }
+    async getRunArtifactForViewer(params) {
+        const toolRow = this.readModel.loadToolRowForViewer(params.userId, params.toolId, { allowAdminBypass: true });
+        if (!toolRow) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        const runRow = this.db.prepare(`SELECT run_id as runId,
+              tool_id as toolId,
+              action_id as actionId,
+              requested_by_user_id as requestedByUserId,
+              requested_by_agent_id as requestedByAgentId,
+              tool_revision as toolRevision,
+              source_bundle_root as sourceBundleRoot,
+              action_cwd_absolute as actionCwdAbsolute
+         FROM workspace_tool_runs
+        WHERE tool_id = ?
+          AND run_id = ?
+        LIMIT 1`).get(params.toolId, params.runId);
+        if (!runRow) {
+            throw new WorkspaceToolServiceError('Tool run not found.', 404);
+        }
+        const canReadRunEvents = params.userId === toolRow.userId
+            || this.readModel.isAdminUser(params.userId)
+            || params.userId === (runRow.requestedByUserId ?? null);
+        if (!canReadRunEvents) {
+            throw new WorkspaceToolServiceError('Tool run artifact not found.', 404);
+        }
+        const eventRow = this.db.prepare(`SELECT artifacts_json as artifactsJson
+         FROM workspace_tool_run_events
+        WHERE tool_id = ?
+          AND run_id = ?
+          AND event_id = ?
+        LIMIT 1`).get(params.toolId, params.runId, params.eventId);
+        const artifacts = parseWorkspaceToolRunArtifactRefs(eventRow?.artifactsJson ?? null) ?? [];
+        const artifact = artifacts.find((candidate) => candidate.path === params.artifactPath.trim());
+        if (!artifact) {
+            throw new WorkspaceToolServiceError('Tool run artifact not found.', 404);
+        }
+        const manifest = parseWorkspaceToolManifest(toolRow.manifestJson);
+        const action = manifest.actions.find((candidate) => candidate.actionId === runRow.actionId);
+        const agent = this.conversationManager.getAgent(toolRow.agentId);
+        const revision = runRow.toolRevision ?? toolRow.revision;
+        const sourceBundleRoot = runRow.sourceBundleRoot?.trim() || toolRow.bundleRoot;
+        const publishedBundleRoot = getPublishedWorkspaceToolBundleRoot(toolRow.toolId, revision);
+        const actionCwdAbsolute = runRow.actionCwdAbsolute?.trim()
+            || (action && agent?.workspacePath
+                ? resolveToolCwd(agent.workspacePath, manifest, action, sourceBundleRoot, publishedBundleRoot)
+                : null);
+        const tool = this.readModel.rowToToolInfoForViewer(toolRow, params.userId);
+        return {
+            tool,
+            artifact,
+            actionCwdAbsolute,
+            sourceBundleRoot,
+            revision,
+            includeWorkspaceFallback: params.userId === toolRow.userId || this.readModel.isAdminUser(params.userId),
+        };
+    }
+    loadRunEventsByRunId(runIds, eventLimit) {
+        if (runIds.length === 0)
+            return new Map();
+        const limit = normalizeOptionalBoundedPositiveInteger(eventLimit, WORKSPACE_TOOL_RUN_EVENT_MAX_LIMIT);
+        if (limit != null) {
+            const eventsByRunId = new Map();
+            for (const runId of runIds) {
+                const rows = this.db.prepare(`SELECT event_id as eventId,
+                  run_id as runId,
+                  tool_id as toolId,
+                  sequence,
+                  event_type as eventType,
+                  level,
+                  summary,
+                  payload_json as payloadJson,
+                  artifacts_json as artifactsJson,
+                  created_at as createdAt
+             FROM workspace_tool_run_events
+            WHERE run_id = ?
+            ORDER BY sequence DESC
+            LIMIT ?`).all(runId, limit);
+                eventsByRunId.set(runId, rows.reverse().map(runEventRowToInfo));
+            }
+            return eventsByRunId;
+        }
+        const placeholders = runIds.map(() => '?').join(', ');
+        const rows = this.db.prepare(`SELECT event_id as eventId,
+              run_id as runId,
+              tool_id as toolId,
+              sequence,
+              event_type as eventType,
+              level,
+              summary,
+              payload_json as payloadJson,
+              artifacts_json as artifactsJson,
+              created_at as createdAt
+         FROM workspace_tool_run_events
+        WHERE run_id IN (${placeholders})
+        ORDER BY run_id ASC, sequence ASC`).all(...runIds);
+        const eventsByRunId = new Map();
+        for (const row of rows) {
+            const events = eventsByRunId.get(row.runId) ?? [];
+            events.push(runEventRowToInfo(row));
+            eventsByRunId.set(row.runId, events);
+        }
+        return eventsByRunId;
+    }
+    loadRunForEventViewer(userId, toolId, runId) {
+        const tool = this.readModel.loadToolRowForViewer(userId, toolId, { allowAdminBypass: true });
+        if (!tool) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        const run = this.db.prepare(`SELECT run_id as runId,
+              tool_id as toolId,
+              action_id as actionId,
+              terminal_id as terminalId,
+              status,
+              params_json as paramsJson,
+              exit_code as exitCode,
+              signal,
+              started_at as startedAt,
+              ended_at as endedAt,
+              requested_by_user_id as requestedByUserId,
+              requested_by_agent_id as requestedByAgentId,
+              tool_revision as toolRevision,
+              source_bundle_root as sourceBundleRoot,
+              action_cwd_absolute as actionCwdAbsolute,
+              runtime_log_dir as runtimeLogDir,
+              execution_target_kind as executionTargetKind,
+              execution_agent_id as executionAgentId,
+              execution_node_id as executionNodeId,
+              execution_hostname as executionHostname,
+              execution_workspace_path as executionWorkspacePath
+         FROM workspace_tool_runs
+        WHERE tool_id = ?
+          AND run_id = ?
+        LIMIT 1`).get(toolId, runId);
+        if (!run) {
+            throw new WorkspaceToolServiceError('Tool run not found.', 404);
+        }
+        const canViewOwnerFields = userId === tool.userId || this.readModel.isAdminUser(userId);
+        if (!canViewOwnerFields && userId !== (run.requestedByUserId ?? null)) {
+            throw new WorkspaceToolServiceError('Tool run not found.', 404);
+        }
+        return run;
+    }
+    async getOrOpenMaintenanceConversation(userId, toolId) {
+        const tool = this.readModel.loadToolRowForUser(userId, toolId);
+        if (!tool) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        const conversation = this.ensureMaintenanceConversation(tool);
+        if (!conversation) {
+            throw new WorkspaceToolServiceError('Unable to open maintenance conversation.', 500);
+        }
+        if (conversation.id !== tool.maintenanceConversationId) {
+            this.db.prepare(`UPDATE workspace_tools
+            SET maintenance_conversation_id = ?,
+                updated_at = ?
+          WHERE tool_id = ?`).run(conversation.id, Date.now(), tool.toolId);
+        }
+        if (!tool.panelId || conversation.id !== tool.maintenanceConversationId) {
+            this.snapshotPanels.syncForTool(tool.toolId);
+        }
+        return conversation;
+    }
+    async getMaintenanceConversationForViewer(userId, toolId) {
+        const tool = this.readModel.loadToolRowForViewer(userId, toolId);
+        if (!tool) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        if (tool.userId !== userId) {
+            throw new WorkspaceToolServiceError('Tool maintenance chat is only available to the tool owner.', 403);
+        }
+        return this.getOrOpenMaintenanceConversation(userId, toolId);
+    }
+    async publishTool(params) {
+        if (params.dryRun) {
+            const dryRunResult = await this.performDryRunValidation(params);
+            return dryRunResult;
+        }
+        const agent = this.conversationManager.getAgent(params.agentId);
+        if (!agent?.nodeId || !agent.workspacePath) {
+            throw new WorkspaceToolServiceError('Agent workspace is unavailable for publishing.', 409);
+        }
+        const agentNodeId = agent.nodeId;
+        const agentWorkspacePath = agent.workspacePath;
+        const normalizedManifestPath = normalizeWorkspaceRelativePath(agentWorkspacePath, params.manifestPath);
+        const manifestSource = typeof params.manifestContent === 'string' && params.manifestContent.trim()
+            ? params.manifestContent
+            : (await this.workspaceBroker.readFile(agentNodeId, agentWorkspacePath, normalizedManifestPath.relativePath, { scaffold: false })).content;
+        const manifest = parseWorkspaceToolManifest(manifestSource);
+        validateManifestConsistency(agentWorkspacePath, normalizedManifestPath.relativePath, manifest);
+        validateManifestCwds(agentWorkspacePath, manifest, path.posix.dirname(normalizedManifestPath.relativePath));
+        const diagnostics = buildWorkspaceToolPublishDiagnostics(manifest);
+        return this.mutationQueues.enqueuePublish(`${params.userId}:${params.agentId}:${manifest.slug}`, async () => {
+            const identity = this.publishIdentityResolver.resolve({
+                userId: params.userId,
+                agentId: params.agentId,
+                slug: manifest.slug,
+                sourceConversationId: params.sourceConversationId,
+                allowCreateNewTool: params.allowCreateNewTool,
+            });
+            if (identity.loadConflict) {
+                throw new WorkspaceToolServiceError(identity.loadConflict.message, identity.loadConflict.statusCode);
+            }
+            // Keep source-panel ownership conflicts inside the per-tool queue; another
+            // queued republish can change the source-panel identity before mutation.
+            if (identity.publishState.conflict?.kind === 'different_live_tool_slug') {
+                throw new WorkspaceToolServiceError(identity.publishState.conflict.message, identity.publishState.conflict.statusCode);
+            }
+            if (identity.publishState.queueToolId) {
+                return this.mutationQueues.enqueueTool(identity.publishState.queueToolId, async () => this.publishToolMutation({
+                    params,
+                    manifest,
+                    diagnostics,
+                    agentNodeId,
+                    agentWorkspacePath,
+                }));
+            }
+            return this.publishToolMutation({
+                params,
+                manifest,
+                diagnostics,
+                agentNodeId,
+                agentWorkspacePath,
+            });
+        });
+    }
+    async performDryRunValidation(params) {
+        const agent = this.conversationManager.getAgent(params.agentId);
+        if (!agent?.nodeId || !agent.workspacePath) {
+            return {
+                valid: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'agent_workspace_unavailable',
+                        message: 'Agent workspace is unavailable for publishing.',
+                    }],
+            };
+        }
+        const agentNodeId = agent.nodeId;
+        const agentWorkspacePath = agent.workspacePath;
+        let normalizedManifestPath;
+        try {
+            normalizedManifestPath = normalizeWorkspaceRelativePath(agentWorkspacePath, params.manifestPath);
+        }
+        catch (error) {
+            return {
+                valid: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'manifest_path_invalid',
+                        message: String(error?.message ?? error),
+                    }],
+            };
+        }
+        let manifestSource;
+        try {
+            manifestSource = typeof params.manifestContent === 'string' && params.manifestContent.trim()
+                ? params.manifestContent
+                : (await this.workspaceBroker.readFile(agentNodeId, agentWorkspacePath, normalizedManifestPath.relativePath, { scaffold: false })).content;
+        }
+        catch (error) {
+            return {
+                valid: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'manifest_read_failed',
+                        message: String(error?.message ?? error),
+                    }],
+            };
+        }
+        try {
+            const manifest = parseWorkspaceToolManifest(manifestSource);
+            validateManifestConsistency(agentWorkspacePath, normalizedManifestPath.relativePath, manifest);
+            validateManifestCwds(agentWorkspacePath, manifest, path.posix.dirname(normalizedManifestPath.relativePath));
+            const diagnostics = buildWorkspaceToolPublishDiagnostics(manifest);
+            return {
+                valid: !diagnostics.some((diagnostic) => diagnostic.severity === 'error'),
+                diagnostics,
+                manifest,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'manifest_validation_failed',
+                        message: String(error?.message ?? error),
+                    }],
+            };
+        }
+    }
+    async cloneTool(params) {
+        const parsed = workspaceToolCloneSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new WorkspaceToolServiceError(`Invalid tool clone request: ${parsed.error.issues[0]?.message ?? 'unknown error'}`, 400);
+        }
+        const cloneParams = parsed.data;
+        const sourceRow = this.readModel.loadToolRowForViewer(cloneParams.userId, cloneParams.toolId, { allowAdminBypass: true });
+        if (!sourceRow) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        const isAdmin = this.readModel.isAdminUser(cloneParams.userId);
+        if (sourceRow.userId !== cloneParams.userId && !isAdmin) {
+            throw new WorkspaceToolServiceError('Only the tool owner can install this tool on another agent.', 403);
+        }
+        if (!sourceRow.agentNodeId || !sourceRow.agentWorkspacePath) {
+            throw new WorkspaceToolServiceError('Source tool workspace is unavailable for cloning.', 409);
+        }
+        if (sourceRow.activeTerminalId) {
+            throw new WorkspaceToolServiceError('Source tool is currently running. Stop it before installing a copy on another agent.', 409);
+        }
+        const currentRevisionRun = this.db.prepare(`SELECT run_id as runId
+         FROM workspace_tool_runs
+        WHERE tool_id = ?
+          AND (
+            tool_revision = ?
+            OR (tool_revision IS NULL AND started_at >= ?)
+          )
+        LIMIT 1`).get(sourceRow.toolId, sourceRow.revision, sourceRow.updatedAt);
+        if (currentRevisionRun) {
+            throw new WorkspaceToolServiceError('Source tool current revision has run history. Republish the tool to create a clean revision before installing a copy on another agent.', 409);
+        }
+        const targetAgent = this.conversationManager.getAgent(cloneParams.targetAgentId);
+        if (!targetAgent || targetAgent.deletedAt) {
+            throw new WorkspaceToolServiceError('Target agent not found.', 404);
+        }
+        const accessibleTargetAgentIds = new Set(getUserAgentAccess(this.db, cloneParams.userId));
+        if (!isAdmin && !accessibleTargetAgentIds.has(targetAgent.agentId)) {
+            throw new WorkspaceToolServiceError('Access denied for target agent.', 403);
+        }
+        if ((targetAgent.agentRole ?? 'user') !== 'user') {
+            throw new WorkspaceToolServiceError('Workspace tools can only be installed on user agents.', 409);
+        }
+        if (targetAgent.agentId === sourceRow.agentId) {
+            throw new WorkspaceToolServiceError('Workspace tools cannot be cloned onto their source agent.', 409);
+        }
+        if (!targetAgent.nodeId || !targetAgent.workspacePath) {
+            throw new WorkspaceToolServiceError('Target agent workspace is unavailable for cloning.', 409);
+        }
+        const sourceManifest = parseWorkspaceToolManifest(sourceRow.manifestJson);
+        const targetSlug = normalizeWorkspaceToolCloneSlug(cloneParams.slug ?? sourceManifest.slug);
+        if (targetSlug !== sourceManifest.slug
+            && workspaceToolCloneManifestHasSourcePathReferences(sourceManifest, sourceManifest.slug)) {
+            throw new WorkspaceToolServiceError('Cannot override the clone slug because the tool manifest references its source bundle path. Clone without a slug override or republish with slug-relative paths first.', 409);
+        }
+        const targetName = cloneParams.name?.trim() || sourceManifest.name;
+        const targetDescription = cloneParams.description ?? sourceManifest.description;
+        const targetBundleRoot = `.agent-tools/${targetSlug}`;
+        const targetManifestPath = `${targetBundleRoot}/tool.json`;
+        const existingTargetTool = this.db.prepare(`SELECT tool_id as toolId
+         FROM workspace_tools
+        WHERE user_id = ?
+          AND agent_id = ?
+          AND slug = ?
+          AND deleted_at IS NULL
+        LIMIT 1`).get(cloneParams.userId, targetAgent.agentId, targetSlug);
+        if (existingTargetTool) {
+            throw new WorkspaceToolServiceError('Target agent already has a live tool with this slug.', 409);
+        }
+        await this.assertWorkspaceDirectoryAvailableForClone({
+            nodeId: targetAgent.nodeId,
+            workspaceRoot: targetAgent.workspacePath,
+            relativePath: targetBundleRoot,
+        });
+        const adjustedManifest = {
+            ...sourceManifest,
+            slug: targetSlug,
+            name: targetName,
+            description: targetDescription,
+            scope: 'private',
+            scopeChannelId: null,
+            allowSharedExec: false,
+        };
+        const manifestJson = JSON.stringify(adjustedManifest, null, 2);
+        validateManifestConsistency(targetAgent.workspacePath, targetManifestPath, adjustedManifest);
+        validateManifestCwds(targetAgent.workspacePath, adjustedManifest, targetBundleRoot);
+        const sourcePublishedBundleRoot = getPublishedWorkspaceToolBundleRoot(sourceRow.toolId, sourceRow.revision);
+        let archiveBase64;
+        try {
+            const archive = await this.workspaceBroker.archiveDirectory(sourceRow.agentNodeId, sourceRow.agentWorkspacePath, sourcePublishedBundleRoot, {
+                maxBytes: WORKSPACE_TOOL_CLONE_ARCHIVE_MAX_BYTES,
+                timeoutMs: WORKSPACE_TOOL_CLONE_ARCHIVE_TIMEOUT_MS,
+            });
+            archiveBase64 = archive.archiveBase64;
+        }
+        catch (error) {
+            throw new WorkspaceToolServiceError(`Failed to read source tool bundle for cloning: ${String(error?.message ?? error)}`, isWorkspaceFileMissingError(error) ? 409 : 500);
+        }
+        let targetBundleMayNeedRollback = false;
+        try {
+            targetBundleMayNeedRollback = true;
+            await this.workspaceBroker.extractDirectoryArchive(targetAgent.nodeId, targetAgent.workspacePath, targetBundleRoot, archiveBase64, {
+                overwrite: false,
+                maxBytes: WORKSPACE_TOOL_CLONE_ARCHIVE_MAX_BYTES,
+                timeoutMs: WORKSPACE_TOOL_CLONE_ARCHIVE_TIMEOUT_MS,
+            });
+            await this.workspaceBroker.writeFile(targetAgent.nodeId, targetAgent.workspacePath, targetManifestPath, manifestJson, 'overwrite', { scaffold: false });
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            if (targetBundleMayNeedRollback && !message.includes('Target path already exists')) {
+                await this.cleanupFailedClonedToolBundle({
+                    nodeId: targetAgent.nodeId,
+                    workspaceRoot: targetAgent.workspacePath,
+                    relativePath: targetBundleRoot,
+                });
+            }
+            throw new WorkspaceToolServiceError(`Failed to install cloned tool bundle on target agent: ${message}`, message.includes('already exists') ? 409 : 500);
+        }
+        let published;
+        try {
+            published = await this.publishTool({
+                userId: cloneParams.userId,
+                agentId: targetAgent.agentId,
+                manifestPath: targetManifestPath,
+                manifestContent: manifestJson,
+                allowCreateNewTool: true,
+            });
+        }
+        catch (error) {
+            await this.cleanupFailedClonedToolBundle({
+                nodeId: targetAgent.nodeId,
+                workspaceRoot: targetAgent.workspacePath,
+                relativePath: targetBundleRoot,
+            });
+            if (error instanceof WorkspaceToolServiceError) {
+                throw error;
+            }
+            throw new WorkspaceToolServiceError(`Failed to publish cloned tool on target agent: ${String(error?.message ?? error)}`, 500);
+        }
+        const now = Date.now();
+        this.db.prepare(`UPDATE workspace_tools
+          SET cloned_from_tool_id = ?,
+              cloned_from_revision = ?,
+              updated_at = ?
+        WHERE tool_id = ?`).run(sourceRow.toolId, sourceRow.revision, now, published.tool.toolId);
+        const verification = this.createCloneVerification({
+            userId: cloneParams.userId,
+            sourceToolId: sourceRow.toolId,
+            sourceRevision: sourceRow.revision,
+            clonedToolId: published.tool.toolId,
+            clonedToolRevision: published.tool.revision,
+            clonedToolUrl: published.toolUrl,
+            targetAgent,
+            targetManifest: adjustedManifest,
+        });
+        return {
+            tool: await this.getToolForViewer(cloneParams.userId, published.tool.toolId),
+            toolUrl: published.toolUrl,
+            verification,
+        };
+    }
+    createCloneVerification(params) {
+        const conversation = this.conversationManager.openNamedAgentPrimaryThread({
+            agentId: params.targetAgent.agentId,
+            userId: params.userId,
+            title: `[workspace-tool-verify:${params.clonedToolId}] ${params.targetManifest.name}`,
+        });
+        if (!conversation) {
+            log.warn('[workspace-tools] failed to create clone verification conversation', {
+                toolId: params.clonedToolId,
+                agentId: params.targetAgent.agentId,
+            });
+            return null;
+        }
+        const now = Date.now();
+        const verificationId = randomUUID();
+        this.db.prepare(`INSERT INTO workspace_tool_verifications(
+         verification_id,
+         tool_id,
+         tool_revision,
+         source_tool_id,
+         source_revision,
+         target_agent_id,
+         target_node_id,
+         target_workspace_path,
+         conversation_id,
+         status,
+         summary,
+         details_json,
+         smoke_run_id,
+         started_at,
+         ended_at,
+         updated_at
+       )
+       VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, 'checking', ?, NULL, NULL, ?, NULL, ?)`).run(verificationId, params.clonedToolId, params.clonedToolRevision, params.sourceToolId, params.sourceRevision, params.targetAgent.agentId, params.targetAgent.nodeId ?? null, params.targetAgent.workspacePath ?? null, conversation.id, 'Waiting for target agent verification.', now, now);
+        const verification = this.readModel.loadLatestVerificationForTool(params.clonedToolId, params.clonedToolRevision);
+        const prompt = this.buildCloneVerificationPrompt({
+            toolId: params.clonedToolId,
+            toolUrl: params.clonedToolUrl,
+            manifest: params.targetManifest,
+            targetAgent: params.targetAgent,
+        });
+        void this.conversationManager.submitPrompt(conversation.id, prompt, {
+            recordAsUserMessage: true,
+            senderName: 'Workspace Tool verification',
+            suppressReplyContract: false,
+        }).catch((error) => {
+            log.warn('[workspace-tools] failed to dispatch clone verification prompt', {
+                toolId: params.clonedToolId,
+                conversationId: conversation.id,
+                error: String(error?.message ?? error),
+            });
+            this.markVerificationDispatchFailed(verificationId, String(error?.message ?? error));
+        });
+        return verification ? workspaceToolVerificationRowToInfo(verification) : null;
+    }
+    buildCloneVerificationPrompt(params) {
+        const statusAction = findWorkspaceToolVerificationStatusAction(params.manifest);
+        const env = params.manifest.env?.condaEnv?.trim() || '';
+        const cliEntry = params.manifest.cli?.entry?.trim() || '';
+        const runtimeEntry = params.manifest.runtime?.entry?.trim() || '';
+        const checks = [
+            env
+                ? `- Check conda env "${env}" exists and can run Python, for example: conda env list; conda run -n ${env} python --version.`
+                : '- No manifest env.condaEnv is declared; inspect the default shell/Python/runtime available on this target machine.',
+            cliEntry
+                ? `- Check bundle CLI entry exists and is executable/readable: ${cliEntry}.`
+                : '- No cli.entry is declared; inspect action command/runtime entry paths from tool.json.',
+            runtimeEntry
+                ? `- Check runtime.entry exists and can start under the target workspace: ${runtimeEntry}.`
+                : '- If runtime.mode is persistent_runtime, check the runtime starts through cli.entry or the declared runtime.entry.',
+            statusAction
+                ? `- Run a safe smoke check with: bigbang tool run --tool-id ${params.toolId} --action-id ${statusAction.actionId}`
+                : '- This manifest has no zero-parameter status action; mark warning if environment/entry checks pass but no smoke action can be run.',
+        ];
+        return [
+            `A Workspace Tool was installed on this agent and must be verified before users trust it on this machine.`,
+            '',
+            `Tool: ${params.manifest.name} (${params.manifest.slug})`,
+            `Tool id: ${params.toolId}`,
+            `Tool URL: ${params.toolUrl}`,
+            `Target agent: ${params.targetAgent.name} (${params.targetAgent.agentId})`,
+            `Target node: ${params.targetAgent.nodeId ?? 'unknown'}`,
+            `Target workspace: ${params.targetAgent.workspacePath ?? 'unknown'}`,
+            '',
+            'Run these checks on the target machine:',
+            ...checks,
+            '',
+            'When done, write back exactly one verification result:',
+            `- Success: bigbang tool verify --tool-id ${params.toolId} --status verified --summary "<what passed>"`
+                + (statusAction ? ` --smoke-run-id "<run id from the smoke action if available>"` : ''),
+            `- Warning: bigbang tool verify --tool-id ${params.toolId} --status warning --summary "<usable but limited, e.g. no smoke action>"`,
+            `- Failure: bigbang tool verify --tool-id ${params.toolId} --status failed --summary "<what failed and next fix>"`,
+            '',
+            'Do not finish with an ordinary final answer until the verification result has been written back.',
+        ].join('\n');
+    }
+    markVerificationDispatchFailed(verificationId, summary) {
+        const now = Date.now();
+        this.db.prepare(`UPDATE workspace_tool_verifications
+          SET status = 'failed',
+              summary = ?,
+              ended_at = ?,
+              updated_at = ?
+        WHERE verification_id = ?`).run(`Failed to dispatch verification thread: ${summary}`, now, now, verificationId);
+    }
+    recordToolVerificationResult(params) {
+        const parsed = workspaceToolVerificationUpdateSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new WorkspaceToolServiceError(`Invalid tool verification update: ${parsed.error.issues[0]?.message ?? 'unknown error'}`, 400);
+        }
+        const normalized = parsed.data;
+        const verification = this.readModel.loadVerificationByConversation(normalized.conversationId);
+        if (!verification || verification.toolId !== normalized.toolId) {
+            throw new WorkspaceToolServiceError('Tool verification thread not found for this tool.', 404);
+        }
+        if (verification.targetAgentId !== normalized.agentId) {
+            throw new WorkspaceToolServiceError('Tool verification can only be updated by the target agent.', 403);
+        }
+        const tool = this.readModel.loadToolRowById(normalized.toolId);
+        if (!tool || tool.agentId !== normalized.agentId) {
+            throw new WorkspaceToolServiceError('Tool is no longer bound to this verification target.', 409);
+        }
+        if (verification.toolRevision !== tool.revision) {
+            throw new WorkspaceToolServiceError('Tool verification thread is stale for the current tool revision.', 409);
+        }
+        if (normalized.smokeRunId) {
+            const smokeRun = this.db.prepare(`SELECT run_id as runId,
+                tool_id as toolId,
+                tool_revision as toolRevision
+           FROM workspace_tool_runs
+          WHERE run_id = ?
+          LIMIT 1`).get(normalized.smokeRunId);
+            if (!smokeRun) {
+                throw new WorkspaceToolServiceError('Smoke run was not found for this tool verification.', 400);
+            }
+            if (smokeRun.toolId !== normalized.toolId) {
+                throw new WorkspaceToolServiceError('Smoke run belongs to a different workspace tool.', 409);
+            }
+            if (smokeRun.toolRevision != null && smokeRun.toolRevision !== verification.toolRevision) {
+                throw new WorkspaceToolServiceError('Smoke run belongs to a different workspace tool revision.', 409);
+            }
+        }
+        const now = Date.now();
+        this.db.prepare(`UPDATE workspace_tool_verifications
+          SET status = ?,
+              summary = ?,
+              details_json = ?,
+              smoke_run_id = ?,
+              ended_at = ?,
+              updated_at = ?
+        WHERE verification_id = ?`).run(normalized.status, normalized.summary, normalized.details ? JSON.stringify(normalized.details) : null, normalized.smokeRunId ?? null, now, now, verification.verificationId);
+        const updated = this.readModel.loadLatestVerificationForTool(normalized.toolId, verification.toolRevision);
+        if (!updated) {
+            throw new WorkspaceToolServiceError('Tool verification update was not persisted.', 500);
+        }
+        return workspaceToolVerificationRowToInfo(updated);
+    }
+    async cleanupFailedPublishedToolBundle(params) {
+        try {
+            await this.workspaceBroker.deletePath(params.nodeId, params.workspaceRoot, params.relativePath, { recursive: true });
+        }
+        catch (error) {
+            if (!isWorkspaceFileMissingError(error)) {
+                log.warn('[workspace-tools] failed to rollback published tool bundle', {
+                    nodeId: params.nodeId,
+                    workspaceRoot: params.workspaceRoot,
+                    relativePath: params.relativePath,
+                    error: String(error?.message ?? error),
+                });
+            }
+        }
+    }
+    async cleanupFailedClonedToolBundle(params) {
+        try {
+            await this.workspaceBroker.deletePath(params.nodeId, params.workspaceRoot, params.relativePath, { recursive: true });
+        }
+        catch (error) {
+            log.warn('[workspace-tools] failed to rollback cloned tool bundle', {
+                nodeId: params.nodeId,
+                workspaceRoot: params.workspaceRoot,
+                relativePath: params.relativePath,
+                error: String(error?.message ?? error),
+            });
+        }
+    }
+    async publishToolMutation(params) {
+        const { params: publishParams, manifest, diagnostics, agentNodeId, agentWorkspacePath, } = params;
+        const now = Date.now();
+        const identity = this.publishIdentityResolver.resolve({
+            userId: publishParams.userId,
+            agentId: publishParams.agentId,
+            slug: manifest.slug,
+            sourceConversationId: publishParams.sourceConversationId,
+            allowCreateNewTool: publishParams.allowCreateNewTool,
+        });
+        if (identity.loadConflict) {
+            throw new WorkspaceToolServiceError(identity.loadConflict.message, identity.loadConflict.statusCode);
+        }
+        const { publishState } = identity;
+        if (publishState.conflict) {
+            throw new WorkspaceToolServiceError(publishState.conflict.message, publishState.conflict.statusCode);
+        }
+        const existingIdentity = publishState.existingIdentity ?? undefined;
+        const existing = publishState.existing ?? undefined;
+        let existingRow = existing?.toolId
+            ? this.readModel.loadToolRowForUser(publishParams.userId, existing.toolId)
+            : null;
+        const nextSourcePanelId = publishState.nextSourcePanelId;
+        const executionAgentId = existing?.agentId ?? publishParams.agentId;
+        if (existingIdentity?.toolId) {
+            this.assertAgentCanPublishToolRevision({
+                publishingAgentId: publishParams.agentId,
+                agentNodeId,
+                agentWorkspacePath,
+                tool: existingIdentity,
+            });
+        }
+        if (existingRow?.activeTerminalId) {
+            existingRow = await this.clearMissingActiveTerminalBeforePublish(existingRow);
+        }
+        if (existingRow?.activeTerminalId) {
+            throw new WorkspaceToolServiceError('Cannot publish a new tool revision while the current revision is still running.', 409);
+        }
+        const toolId = existing?.toolId ?? randomUUID();
+        const maintenanceConversation = this.ensureMaintenanceConversation({
+            toolId,
+            agentId: executionAgentId,
+            userId: publishParams.userId,
+            maintenanceConversationId: existingIdentity?.maintenanceConversationId ?? null,
+        });
+        if (!maintenanceConversation) {
+            throw new WorkspaceToolServiceError('Unable to create maintenance conversation.', 500);
+        }
+        const manifestPath = `.agent-tools/${manifest.slug}/tool.json`;
+        const bundleRoot = `.agent-tools/${manifest.slug}`;
+        const revision = existing ? existing.revision + 1 : 1;
+        const publishedBundleRoot = getPublishedWorkspaceToolBundleRoot(toolId, revision);
+        try {
+            await this.snapshotPublishedBundle({
+                agentNodeId,
+                workspaceRoot: agentWorkspacePath,
+                sourceBundleRoot: bundleRoot,
+                publishedBundleRoot,
+            });
+            const staleCachedStoragePaths = [];
+            const tx = this.db.transaction(() => {
+                const currentSharing = existing ? this.readModel.loadToolRowForUser(publishParams.userId, toolId) : null;
+                const allowSharedExec = currentSharing?.allowSharedExec ?? 0;
+                const snapshotSync = this.snapshotPanels.syncPanel({
+                    panelId: existingRow?.panelId ?? existing?.panelId ?? null,
+                    sourcePanelId: nextSourcePanelId,
+                    toolId,
+                    userId: publishParams.userId,
+                    agentId: executionAgentId,
+                    conversationId: maintenanceConversation.id,
+                    nodeId: agentNodeId,
+                    manifest,
+                    latestState: null,
+                    allowSharedExec: allowSharedExec === 1,
+                    status: 'idle',
+                });
+                staleCachedStoragePaths.push(...snapshotSync.staleCachedStoragePaths);
+                const panelId = snapshotSync.panelId;
+                if (existing) {
+                    const shouldReopenPublicReview = currentSharing?.pendingPublicReview === 0
+                        && (currentSharing.publicReviewStatus === 'approved' || currentSharing.publicReviewStatus === 'rejected');
+                    const scope = currentSharing?.scope ?? 'private';
+                    const scopeChannelId = scope === 'channel'
+                        ? (currentSharing?.scopeChannelId ?? null)
+                        : null;
+                    const publicReviewStatus = shouldReopenPublicReview
+                        ? 'pending_review'
+                        : (currentSharing?.publicReviewStatus ?? 'not_requested');
+                    const pendingPublicReview = shouldReopenPublicReview
+                        ? 1
+                        : (currentSharing?.pendingPublicReview ?? 0);
+                    this.db.prepare(`UPDATE workspace_tools
+              SET slug = ?,
+                  name = ?,
+                  description = ?,
+                  icon = ?,
+                  scope = ?,
+                  scope_channel_id = ?,
+                  allow_shared_exec = ?,
+                  public_review_status = ?,
+                  pending_public_review = ?,
+                  manifest_path = ?,
+                  bundle_root = ?,
+                  source_panel_id = ?,
+                  panel_id = ?,
+                  manifest_json = ?,
+                  latest_state_json = NULL,
+                  maintenance_conversation_id = ?,
+                  source_conversation_id = ?,
+                  source_message_id = ?,
+                  revision = ?,
+                  updated_at = ?,
+                  deleted_at = NULL
+            WHERE tool_id = ?`).run(manifest.slug, manifest.name, manifest.description, manifest.icon ?? null, scope, scopeChannelId, allowSharedExec, publicReviewStatus, pendingPublicReview, manifestPath, bundleRoot, nextSourcePanelId, panelId, JSON.stringify(withPersistedToolSettings(manifest, {
+                        scope,
+                        scopeChannelId,
+                        allowSharedExec: allowSharedExec === 1,
+                    })), maintenanceConversation.id, publishParams.sourceConversationId ?? null, publishParams.sourceMessageId ?? null, revision, now, toolId);
+                    ensureSurfaceOwner(this.db, {
+                        surfaceType: 'tool',
+                        surfaceId: toolId,
+                        agentId: executionAgentId,
+                        createdAt: now,
+                    });
+                    if (nextSourcePanelId) {
+                        this.db.prepare(`UPDATE panel_tool_promotions
+                SET tool_id = ?,
+                    updated_at = ?
+              WHERE panel_id = ?`).run(toolId, now, nextSourcePanelId);
+                    }
+                    return;
+                }
+                this.db.prepare(`INSERT INTO workspace_tools(
+           tool_id,
+           user_id,
+           agent_id,
+           slug,
+           name,
+           description,
+           icon,
+           scope,
+           scope_channel_id,
+           allow_shared_exec,
+           public_review_status,
+           pending_public_review,
+           manifest_path,
+           bundle_root,
+           source_panel_id,
+           panel_id,
+           manifest_json,
+           latest_state_json,
+           active_terminal_id,
+           maintenance_conversation_id,
+           source_conversation_id,
+           source_message_id,
+           revision,
+           created_at,
+           updated_at,
+           deleted_at
+         )
+         VALUES(
+           ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+           NULL,
+           NULL,
+           ?, ?, ?, ?, ?, ?,
+           NULL
+         )`).run(toolId, publishParams.userId, publishParams.agentId, manifest.slug, manifest.name, manifest.description, manifest.icon ?? null, 'private', null, 0, 'not_requested', 0, manifestPath, bundleRoot, nextSourcePanelId, panelId, JSON.stringify(withPersistedToolSettings(manifest, {
+                    scope: 'private',
+                    scopeChannelId: null,
+                    allowSharedExec: false,
+                })), maintenanceConversation.id, publishParams.sourceConversationId ?? null, publishParams.sourceMessageId ?? null, revision, now, now);
+                ensureSurfaceOwner(this.db, {
+                    surfaceType: 'tool',
+                    surfaceId: toolId,
+                    agentId: executionAgentId,
+                    createdAt: now,
+                });
+                if (nextSourcePanelId) {
+                    this.copyPanelMaintainersToTool({
+                        panelId: nextSourcePanelId,
+                        toolId,
+                        executionAgentId,
+                        createdAt: now,
+                    });
+                }
+                if (nextSourcePanelId) {
+                    this.db.prepare(`UPDATE panel_tool_promotions
+              SET tool_id = ?,
+                  updated_at = ?
+            WHERE panel_id = ?`).run(toolId, now, nextSourcePanelId);
+                }
+            });
+            tx();
+            unlinkPanelAttachmentStoragePaths(staleCachedStoragePaths);
+            if (identity.promotionLink?.panelId) {
+                archivePanelWithArtifacts(this.db, {
+                    panelId: identity.promotionLink.panelId,
+                    now: Date.now(),
+                    reason: 'promoted_to_tool',
+                });
+            }
+            let tool = await this.getToolForUser(publishParams.userId, toolId);
+            const username = this.readModel.loadUsername(publishParams.userId);
+            const toolUrl = username ? `/u/${encodeURIComponent(username)}/chat/tools/${toolId}` : `/chat/tools/${toolId}`;
+            if (existingRow?.clonedFromToolId && existingRow.clonedFromRevision != null) {
+                const targetAgent = this.conversationManager.getAgent(executionAgentId);
+                if (targetAgent) {
+                    const verification = this.createCloneVerification({
+                        userId: publishParams.userId,
+                        sourceToolId: existingRow.clonedFromToolId,
+                        sourceRevision: existingRow.clonedFromRevision,
+                        clonedToolId: toolId,
+                        clonedToolRevision: revision,
+                        clonedToolUrl: toolUrl,
+                        targetAgent,
+                        targetManifest: manifest,
+                    });
+                    if (verification) {
+                        tool = await this.getToolForUser(publishParams.userId, toolId);
+                    }
+                }
+                else {
+                    log.warn('[workspace-tools] skipped cloned tool verification after publish because target agent is missing', {
+                        toolId,
+                        agentId: executionAgentId,
+                    });
+                }
+            }
+            return { tool, toolUrl, diagnostics };
+        }
+        catch (error) {
+            await this.cleanupFailedPublishedToolBundle({
+                nodeId: agentNodeId,
+                workspaceRoot: agentWorkspacePath,
+                relativePath: publishedBundleRoot,
+            });
+            throw error;
+        }
+    }
+    async updateToolSettings(params) {
+        const parsed = workspaceToolSettingsUpdateSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new WorkspaceToolServiceError(`Invalid tool settings update: ${parsed.error.issues[0]?.message ?? 'unknown error'}`, 400);
+        }
+        const normalized = parsed.data;
+        return this.mutationQueues.enqueueTool(normalized.toolId, async () => {
+            const tool = this.readModel.loadToolRowForViewer(normalized.userId, normalized.toolId, { allowAdminBypass: true });
+            if (!tool) {
+                throw new WorkspaceToolServiceError('Tool not found.', 404);
+            }
+            if (!this.readModel.canManageToolForViewer(normalized.userId, tool)) {
+                throw new WorkspaceToolServiceError('Access denied.', 403);
+            }
+            const ownerChannelAccess = new Set(getUserChannelAccess(this.db, normalized.userId));
+            const ownerIsAdmin = this.readModel.isAdminUser(normalized.userId);
+            const requestedScopeChannelId = normalized.scopeChannelId ?? null;
+            if (normalized.scope === 'channel') {
+                if (!requestedScopeChannelId) {
+                    throw new WorkspaceToolServiceError('Channel-scoped tools require a scope channel id.', 400);
+                }
+                if (!this.conversationManager.getChannel(requestedScopeChannelId)) {
+                    throw new WorkspaceToolServiceError('Requested channel scope does not exist.', 404);
+                }
+                if (!ownerIsAdmin && !ownerChannelAccess.has(requestedScopeChannelId)) {
+                    throw new WorkspaceToolServiceError('You do not have access to the requested channel scope.', 403);
+                }
+            }
+            const allowSharedExec = normalized.allowSharedExec ?? (tool.allowSharedExec === 1);
+            const now = Date.now();
+            const manifest = parseWorkspaceToolManifest(tool.manifestJson);
+            const cancelPendingPublicReview = normalized.cancelPendingPublicReview === true
+                && tool.pendingPublicReview === 1
+                && tool.publicReviewStatus === 'pending_review';
+            const keepPendingPublicReview = !cancelPendingPublicReview
+                && tool.pendingPublicReview === 1
+                && tool.publicReviewStatus === 'pending_review'
+                && normalized.scope !== 'public';
+            const requestingPublic = normalized.scope === 'public';
+            const alreadyApprovedPublic = tool.scope === 'public' && tool.publicReviewStatus === 'approved' && tool.pendingPublicReview === 0;
+            const preservedScope = (requestingPublic && !alreadyApprovedPublic) || keepPendingPublicReview
+                ? tool.scope
+                : normalized.scope;
+            const nextScope = keepPendingPublicReview
+                ? tool.scope
+                : requestingPublic
+                    ? (alreadyApprovedPublic ? 'public' : tool.scope)
+                    : normalized.scope;
+            const nextScopeChannelId = keepPendingPublicReview
+                ? tool.scopeChannelId
+                : nextScope === 'channel'
+                    ? (preservedScope === 'channel'
+                        ? (requestingPublic && !alreadyApprovedPublic ? tool.scopeChannelId : requestedScopeChannelId)
+                        : requestedScopeChannelId)
+                    : null;
+            const nextPublicReviewStatus = keepPendingPublicReview
+                ? 'pending_review'
+                : requestingPublic
+                    ? (alreadyApprovedPublic ? 'approved' : 'pending_review')
+                    : 'not_requested';
+            const nextPendingPublicReview = keepPendingPublicReview
+                ? 1
+                : requestingPublic
+                    ? (alreadyApprovedPublic ? 0 : 1)
+                    : 0;
+            this.db.prepare(`UPDATE workspace_tools
+            SET scope = ?,
+                scope_channel_id = ?,
+                allow_shared_exec = ?,
+                public_review_status = ?,
+                pending_public_review = ?,
+                manifest_json = ?,
+                updated_at = ?
+          WHERE tool_id = ?`).run(nextScope, nextScopeChannelId, allowSharedExec ? 1 : 0, nextPublicReviewStatus, nextPendingPublicReview, JSON.stringify(withPersistedToolSettings(manifest, {
+                scope: nextScope,
+                scopeChannelId: nextScopeChannelId,
+                allowSharedExec,
+            })), now, tool.toolId);
+            const updatedTool = this.readModel.loadToolRowById(normalized.toolId);
+            if (!updatedTool) {
+                throw new WorkspaceToolServiceError('Tool not found.', 404);
+            }
+            return this.readModel.rowToToolInfoForViewer(updatedTool, normalized.userId);
+        });
+    }
+    listPendingPublicToolReviews(status) {
+        const rows = this.readModel.loadPublicReviewToolRows(status);
+        return rows.map((row) => this.readModel.rowToToolInfo(row));
+    }
+    async reviewPublicToolScope(params) {
+        return this.mutationQueues.enqueueTool(params.toolId, async () => {
+            const row = this.db.prepare(`SELECT tool_id as toolId,
+                scope,
+                scope_channel_id as scopeChannelId,
+                pending_public_review as pendingPublicReview,
+                public_review_status as publicReviewStatus,
+                user_id as userId
+           FROM workspace_tools
+          WHERE tool_id = ?
+            AND deleted_at IS NULL
+          LIMIT 1`).get(params.toolId);
+            if (!row) {
+                throw new WorkspaceToolServiceError('Tool not found.', 404);
+            }
+            if (row.pendingPublicReview !== 1) {
+                throw new WorkspaceToolServiceError('Tool has no pending public review request.', 409);
+            }
+            const tool = this.requireToolRow(row.userId, params.toolId);
+            const manifest = parseWorkspaceToolManifest(tool.manifestJson);
+            const nextScope = params.status === 'approved' ? 'public' : tool.scope;
+            const nextScopeChannelId = params.status === 'approved' ? null : tool.scopeChannelId;
+            this.db.prepare(`UPDATE workspace_tools
+            SET scope = ?,
+                scope_channel_id = ?,
+                public_review_status = ?,
+                pending_public_review = 0,
+                manifest_json = ?,
+                updated_at = ?
+          WHERE tool_id = ?`).run(nextScope, nextScopeChannelId, params.status, JSON.stringify(withPersistedToolSettings(manifest, {
+                scope: nextScope,
+                scopeChannelId: nextScopeChannelId,
+                allowSharedExec: tool.allowSharedExec === 1,
+            })), Date.now(), params.toolId);
+            return this.getToolForUser(row.userId, params.toolId);
+        });
+    }
+    async deleteTool(params) {
+        const tool = this.readModel.loadToolRowForViewer(params.userId, params.toolId, { allowAdminBypass: true });
+        if (!tool) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        if (!this.readModel.canManageToolForViewer(params.userId, tool)) {
+            throw new WorkspaceToolServiceError('Access denied.', 403);
+        }
+        await this.mutationQueues.enqueueTool(tool.toolId, async () => {
+            const currentTool = this.readModel.loadToolRowForViewer(params.userId, params.toolId, { allowAdminBypass: true });
+            if (!currentTool) {
+                return;
+            }
+            if (!this.readModel.canManageToolForViewer(params.userId, currentTool)) {
+                throw new WorkspaceToolServiceError('Access denied.', 403);
+            }
+            let stoppedActiveTerminal = false;
+            if (currentTool.activeTerminalId) {
+                const activeAgent = this.conversationManager.getAgent(currentTool.agentId);
+                if (!activeAgent?.nodeId) {
+                    throw new WorkspaceToolServiceError('Cannot delete a running tool because its terminal is unavailable.', 409);
+                }
+                try {
+                    await this.terminalBroker.closeTerminal(activeAgent.nodeId, currentTool.activeTerminalId);
+                }
+                catch (error) {
+                    const message = String(error?.message ?? error);
+                    if (message.includes('Agent node is offline')) {
+                        throw new WorkspaceToolServiceError(message, 409);
+                    }
+                    throw new WorkspaceToolServiceError('Failed to stop the active tool terminal before deletion.', 409);
+                }
+                this.actionRunner.finishActivePersistentRun(currentTool.toolId, currentTool.activeTerminalId, { status: 'cancelled' });
+                stoppedActiveTerminal = true;
+            }
+            const now = Date.now();
+            if (currentTool.sourcePanelId) {
+                this.db.prepare(`UPDATE panel_tool_promotions
+              SET updated_at = ?
+            WHERE panel_id = ?`).run(now, currentTool.sourcePanelId);
+            }
+            this.db.prepare(`DELETE FROM run_pending_tool_attachments
+          WHERE tool_id = ?`).run(currentTool.toolId);
+            this.db.prepare(`UPDATE workspace_tools
+            SET slug = ?,
+                panel_id = NULL,
+                deleted_at = ?,
+                updated_at = ?,
+                active_terminal_id = NULL
+          WHERE tool_id = ?`).run(buildDeletedWorkspaceToolSlug(currentTool.toolId, currentTool.slug), now, now, currentTool.toolId);
+            if (currentTool.panelId) {
+                hardDeletePanelWithArtifacts(this.db, currentTool.panelId);
+            }
+            await this.cleanupDeletedToolWorkspaceFilesBestEffort(currentTool, {
+                skipRuntimeLogCleanup: stoppedActiveTerminal,
+            });
+        });
+        return { ok: true };
+    }
+    async stopActiveTerminalsForAgent(agentId) {
+        const rows = this.db.prepare(`SELECT tool_id as toolId,
+              active_terminal_id as activeTerminalId
+         FROM workspace_tools
+        WHERE agent_id = ?
+          AND deleted_at IS NULL
+          AND active_terminal_id IS NOT NULL`).all(agentId);
+        if (rows.length === 0)
+            return { stopped: 0 };
+        const agent = this.conversationManager.getAgent(agentId);
+        if (!agent?.nodeId) {
+            throw new WorkspaceToolServiceError('Cannot delete agent because a running workspace tool terminal is unavailable.', 409);
+        }
+        let stopped = 0;
+        for (const row of rows) {
+            await this.mutationQueues.enqueueTool(row.toolId, async () => {
+                const current = this.db.prepare(`SELECT active_terminal_id as activeTerminalId
+             FROM workspace_tools
+            WHERE tool_id = ?
+              AND agent_id = ?
+              AND deleted_at IS NULL`).get(row.toolId, agentId);
+                if (!current?.activeTerminalId)
+                    return;
+                try {
+                    await this.terminalBroker.closeTerminal(agent.nodeId, current.activeTerminalId);
+                }
+                catch (error) {
+                    const message = String(error?.message ?? error);
+                    if (message.includes('Agent node is offline')) {
+                        throw new WorkspaceToolServiceError(message, 409);
+                    }
+                    throw new WorkspaceToolServiceError('Failed to stop the active workspace tool terminal before deleting agent.', 409);
+                }
+                this.actionRunner.finishActivePersistentRun(row.toolId, current.activeTerminalId, { status: 'cancelled' });
+                stopped += 1;
+            });
+        }
+        return { stopped };
+    }
+    async reconcileActiveTerminalsForNode(nodeId) {
+        const rows = this.db.prepare(`SELECT wt.tool_id as toolId,
+              wt.user_id as userId,
+              wt.agent_id as agentId,
+              wt.maintenance_conversation_id as maintenanceConversationId,
+              wt.manifest_json as manifestJson,
+              wt.active_terminal_id as activeTerminalId,
+              a.workspace_path as workspacePath,
+              (
+                SELECT wtr.run_id
+                  FROM workspace_tool_runs wtr
+                 WHERE wtr.tool_id = wt.tool_id
+                   AND wtr.terminal_id = wt.active_terminal_id
+                   AND wtr.status = 'running'
+                 ORDER BY wtr.started_at DESC
+                 LIMIT 1
+              ) as runningRunId,
+              (
+                SELECT wtr.action_id
+                  FROM workspace_tool_runs wtr
+                 WHERE wtr.tool_id = wt.tool_id
+                   AND wtr.terminal_id = wt.active_terminal_id
+                   AND wtr.status = 'running'
+                 ORDER BY wtr.started_at DESC
+                 LIMIT 1
+              ) as runningActionId,
+              (
+                SELECT wtr.started_at
+                  FROM workspace_tool_runs wtr
+                 WHERE wtr.tool_id = wt.tool_id
+                   AND wtr.terminal_id = wt.active_terminal_id
+                   AND wtr.status = 'running'
+                 ORDER BY wtr.started_at DESC
+                 LIMIT 1
+              ) as runStartedAt
+         FROM workspace_tools wt
+         JOIN agents a ON a.agent_id = wt.agent_id
+        WHERE a.node_id = ?
+          AND a.deleted_at IS NULL
+          AND wt.deleted_at IS NULL
+          AND wt.active_terminal_id IS NOT NULL`).all(nodeId);
+        if (rows.length === 0) {
+            return { checked: 0, cleared: 0, reattached: 0, skipped: 0 };
+        }
+        const rowsByWorkspacePath = new Map();
+        let skipped = 0;
+        for (const row of rows) {
+            if (!row.workspacePath?.trim()) {
+                skipped += 1;
+                continue;
+            }
+            const group = rowsByWorkspacePath.get(row.workspacePath) ?? [];
+            group.push(row);
+            rowsByWorkspacePath.set(row.workspacePath, group);
+        }
+        let checked = 0;
+        let cleared = 0;
+        let reattached = 0;
+        for (const [workspacePath, group] of rowsByWorkspacePath.entries()) {
+            let nodeTerminals;
+            try {
+                const terminals = await this.terminalBroker.listTerminals(nodeId, workspacePath);
+                nodeTerminals = new Set(terminals.map((terminal) => terminal.terminalId));
+            }
+            catch (error) {
+                skipped += group.length;
+                log.warn('[workspace-tools] active terminal reconcile list failed', {
+                    nodeId,
+                    workspacePath,
+                    error: String(error?.message ?? error),
+                });
+                continue;
+            }
+            for (const row of group) {
+                checked += 1;
+                if (nodeTerminals.has(row.activeTerminalId)) {
+                    await this.mutationQueues.enqueueTool(row.toolId, async () => {
+                        const current = this.db.prepare(`SELECT wt.active_terminal_id as activeTerminalId,
+                      a.node_id as nodeId,
+                      a.workspace_path as workspacePath
+                 FROM workspace_tools wt
+                 JOIN agents a ON a.agent_id = wt.agent_id
+                WHERE wt.tool_id = ?
+                  AND wt.deleted_at IS NULL
+                LIMIT 1`).get(row.toolId);
+                        if (current?.activeTerminalId !== row.activeTerminalId
+                            || current.nodeId !== nodeId
+                            || current.workspacePath !== workspacePath) {
+                            return;
+                        }
+                        if (this.actionRunner.reattachActivePersistentTerminal(row, nodeId)) {
+                            reattached += 1;
+                        }
+                    });
+                    continue;
+                }
+                await this.mutationQueues.enqueueTool(row.toolId, async () => {
+                    const current = this.db.prepare(`SELECT wt.active_terminal_id as activeTerminalId,
+                    a.node_id as nodeId,
+                    a.workspace_path as workspacePath
+               FROM workspace_tools wt
+               JOIN agents a ON a.agent_id = wt.agent_id
+              WHERE wt.tool_id = ?
+                AND wt.deleted_at IS NULL
+              LIMIT 1`).get(row.toolId);
+                    if (current?.activeTerminalId !== row.activeTerminalId
+                        || current.nodeId !== nodeId
+                        || current.workspacePath !== workspacePath) {
+                        return;
+                    }
+                    this.actionRunner.finishActivePersistentRun(row.toolId, row.activeTerminalId, {
+                        status: 'cancelled',
+                        signal: 'missing_terminal',
+                    });
+                    cleared += 1;
+                });
+            }
+        }
+        if (checked > 0 || cleared > 0 || reattached > 0 || skipped > 0) {
+            log.info('[workspace-tools] active terminal reconcile complete', {
+                nodeId,
+                checked,
+                cleared,
+                reattached,
+                skipped,
+            });
+        }
+        return { checked, cleared, reattached, skipped };
+    }
+    async clearMissingActiveTerminalBeforePublish(toolRow) {
+        if (!toolRow.activeTerminalId || !toolRow.agentNodeId || !toolRow.agentNodeId.trim() || !toolRow.agentWorkspacePath?.trim()) {
+            return toolRow;
+        }
+        try {
+            const terminals = await this.terminalBroker.listTerminals(toolRow.agentNodeId, toolRow.agentWorkspacePath);
+            if (terminals.some((terminal) => terminal.terminalId === toolRow.activeTerminalId)) {
+                return toolRow;
+            }
+        }
+        catch (error) {
+            log.warn('[workspace-tools] pre-publish active terminal refresh failed', {
+                toolId: toolRow.toolId,
+                activeTerminalId: toolRow.activeTerminalId,
+                nodeId: toolRow.agentNodeId,
+                error: String(error?.message ?? error),
+            });
+            return toolRow;
+        }
+        this.actionRunner.finishActivePersistentRun(toolRow.toolId, toolRow.activeTerminalId, {
+            status: 'cancelled',
+            signal: 'missing_terminal',
+        });
+        return this.readModel.loadToolRowForUser(toolRow.userId, toolRow.toolId) ?? toolRow;
+    }
+    async invokeAction(params) {
+        const toolRow = this.readModel.loadToolRowForViewer(params.userId, params.toolId, {
+            allowAdminBypass: params.allowAdminBypass,
+        });
+        if (!toolRow) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        if (this.conversationManager.isAgentDeletionInProgress(toolRow.agentId)) {
+            throw new WorkspaceToolServiceError('Agent deletion is in progress.', 409);
+        }
+        const canExecute = toolRow.userId === params.userId
+            || toolRow.allowSharedExec === 1
+            || (params.allowAdminBypass && this.readModel.isAdminUser(params.userId));
+        if (!canExecute) {
+            throw new WorkspaceToolServiceError('Shared execution is disabled for this tool.', 403);
+        }
+        return this.mutationQueues.enqueueTool(toolRow.toolId, async () => {
+            const refreshedToolRow = this.readModel.loadToolRowForViewer(params.userId, params.toolId, {
+                allowAdminBypass: params.allowAdminBypass,
+            });
+            if (!refreshedToolRow) {
+                throw new WorkspaceToolServiceError('Tool not found.', 404);
+            }
+            if (this.conversationManager.isAgentDeletionInProgress(refreshedToolRow.agentId)) {
+                throw new WorkspaceToolServiceError('Agent deletion is in progress.', 409);
+            }
+            const refreshedCanExecute = refreshedToolRow.userId === params.userId
+                || refreshedToolRow.allowSharedExec === 1
+                || (params.allowAdminBypass && this.readModel.isAdminUser(params.userId));
+            if (!refreshedCanExecute) {
+                throw new WorkspaceToolServiceError('Shared execution is disabled for this tool.', 403);
+            }
+            return this.actionRunner.invokeAction({
+                toolRow: refreshedToolRow,
+                actionId: params.actionId,
+                viewerUserId: params.userId,
+                inputParams: params.inputParams,
+                allowAdminBypass: params.allowAdminBypass,
+                requestedByAgentId: params.requestedByAgentId,
+            });
+        });
+    }
+    async notifyAgentForToolAction(params) {
+        if (params.toolRow.userId !== params.viewerUserId && !this.readModel.isAdminUser(params.viewerUserId)) {
+            throw new WorkspaceToolServiceError('Notify-agent tool actions are only available to the tool owner or admins.', 403);
+        }
+        const conversation = await this.getOrOpenMaintenanceConversation(params.toolRow.userId, params.toolRow.toolId);
+        const requesterAgent = params.requestedByAgentId
+            ? this.conversationManager.getAgent(params.requestedByAgentId)
+            : null;
+        const username = requesterAgent
+            ? requesterAgent.name
+            : (this.readModel.loadUsername(params.viewerUserId) ?? params.viewerUserId);
+        const payload = {
+            kind: 'workspace_tool_action',
+            mode: 'notify_agent',
+            toolId: params.toolRow.toolId,
+            toolName: params.toolRow.name,
+            actionId: params.action.actionId,
+            actionLabel: params.action.label,
+            actionKind: params.action.kind,
+            requestedByUserId: requesterAgent ? null : params.viewerUserId,
+            requestedByAgentId: requesterAgent ? params.requestedByAgentId : null,
+            params: params.actionParams,
+        };
+        const promptText = [
+            'Workspace Tool action requested.',
+            '',
+            'Handle this as a user-triggered tool action in the current maintenance conversation.',
+            'Do not assume a platform command has already run; inspect the tool bundle or update the tool if needed.',
+            '',
+            'Payload:',
+            '```json',
+            JSON.stringify(payload, null, 2),
+            '```',
+        ].join('\n');
+        const result = await this.conversationManager.submitPrompt(conversation.id, promptText, {
+            senderName: username,
+            clientMessageId: randomUUID(),
+            allowActiveSteer: false,
+        });
+        const tool = this.getToolInfoForActionViewer(params.viewerUserId, params.toolRow.toolId, params.allowAdminBypass);
+        return {
+            mode: 'notify_agent',
+            tool,
+            conversationId: conversation.id,
+            queued: result.queued,
+            ...(result.runId ? { runId: result.runId } : {}),
+            latestState: tool.latestState ?? null,
+            outputText: null,
+        };
+    }
+    async recordPlatformExecNotification(params) {
+        try {
+            const maintenanceConversationId = params.toolRow.maintenanceConversationId;
+            if (!maintenanceConversationId) {
+                log.warn('[workspace-tools] skipped platform_exec audit message without maintenance conversation', {
+                    toolId: params.toolRow.toolId,
+                    actionId: params.action.actionId,
+                    runId: params.run.runId,
+                });
+                return;
+            }
+            const conversation = this.conversationManager.getConversation(maintenanceConversationId);
+            if (!conversation || conversation.agentId !== params.toolRow.agentId) {
+                log.warn('[workspace-tools] skipped platform_exec audit message for missing maintenance conversation', {
+                    toolId: params.toolRow.toolId,
+                    actionId: params.action.actionId,
+                    runId: params.run.runId,
+                    maintenanceConversationId,
+                });
+                return;
+            }
+            this.ensureToolMaintenanceConversationRoots(conversation.id);
+            const actorUsername = this.readModel.loadUsername(params.viewerUserId) ?? params.viewerUserId;
+            const payload = {
+                kind: 'workspace_tool_action_result',
+                mode: 'platform_exec',
+                toolId: params.toolRow.toolId,
+                toolName: params.toolRow.name,
+                actionId: params.action.actionId,
+                actionLabel: params.action.label,
+                actionKind: params.action.kind,
+                requestedByUserId: params.viewerUserId,
+                requestedByUsername: actorUsername,
+                runId: params.run.runId,
+                status: params.run.status,
+                terminalId: params.run.terminalId ?? null,
+                exitCode: params.run.exitCode ?? null,
+                signal: params.run.signal ?? null,
+                params: params.actionParams,
+            };
+            const outputPreview = formatBoundedTextPreview(params.outputText, WORKSPACE_TOOL_PLATFORM_EXEC_OUTPUT_PREVIEW_LIMIT);
+            const content = [
+                'Workspace Tool platform_exec result recorded.',
+                '',
+                `Tool: ${params.toolRow.name} (${params.toolRow.toolId})`,
+                `Action: ${params.action.label} (${params.action.actionId})`,
+                `Run: ${params.run.runId} status=${params.run.status} exit=${params.run.exitCode ?? 'n/a'} signal=${params.run.signal ?? 'n/a'}`,
+                `Triggered by: ${actorUsername} (${params.viewerUserId})`,
+                '',
+                'Payload:',
+                '```json',
+                formatBoundedJsonPreview(payload, WORKSPACE_TOOL_PLATFORM_EXEC_PARAMS_PREVIEW_LIMIT),
+                '```',
+                ...(outputPreview
+                    ? [
+                        '',
+                        'Output preview:',
+                        '```text',
+                        outputPreview,
+                        '```',
+                    ]
+                    : []),
+                '',
+                'This is a non-waking audit record. No agent run was started for this notice.',
+            ].join('\n');
+            const messageId = randomUUID();
+            const createdAt = Date.now();
+            const seq = allocateNextChannelMessageSeq(this.db, conversation.channelId);
+            this.db.prepare(`INSERT INTO channel_messages(
+           message_id, channel_id, sender_id, sender_name, sender_type, target, content,
+           seq, created_at, thread_root_id, message_kind, message_source, tool_ids
+         )
+         VALUES(?, ?, 'system', 'Workspace Tool', 'system', ?, ?, ?, ?, ?, 'workspace_tool_action', ?, ?)`).run(messageId, conversation.channelId, conversation.replyTarget, content, seq, createdAt, conversation.threadRootId ?? null, WORKSPACE_TOOL_PLATFORM_EXEC_MESSAGE_SOURCE, JSON.stringify([params.toolRow.toolId]));
+        }
+        catch (error) {
+            log.warn('[workspace-tools] failed to record platform_exec audit message', {
+                toolId: params.toolRow.toolId,
+                actionId: params.action.actionId,
+                runId: params.run.runId,
+                error: String(error?.message ?? error),
+            });
+        }
+    }
+    updateLatestState(toolId, userId, agentId, maintenanceConversationId, state) {
+        this.latestStateProjector.updateLatestState({ toolId, userId, agentId, maintenanceConversationId, state });
+    }
+    ensureMaintenanceConversation(input) {
+        const existing = input.maintenanceConversationId
+            ? this.conversationManager.getConversation(input.maintenanceConversationId)
+            : null;
+        if (existing?.agentId === input.agentId) {
+            this.ensureToolMaintenanceConversationRoots(existing.id);
+            return existing;
+        }
+        const conversation = this.conversationManager.openNamedAgentPrimaryThread({
+            agentId: input.agentId,
+            userId: input.userId ?? null,
+            title: `${TOOL_MAINTENANCE_TITLE_PREFIX}${input.toolId}]`,
+        });
+        if (conversation) {
+            this.ensureToolMaintenanceConversationRoots(conversation.id);
+        }
+        return conversation;
+    }
+    ensureToolMaintenanceConversationRoots(conversationId) {
+        for (const root of conversationBuiltinSkillRootsForSlashCommand('tool')) {
+            this.conversationManager.enableBuiltinSkillRootForConversation(conversationId, root);
+        }
+    }
+    ensureReadableToolSnapshotPanel(row, viewerUserId) {
+        const repairableRow = this.ensureToolSnapshotRepairConversation(row, viewerUserId);
+        if (!this.shouldRepairToolSnapshotPanel(repairableRow)) {
+            return repairableRow;
+        }
+        this.snapshotPanels.syncForTool(repairableRow.toolId);
+        return this.readModel.loadToolRowById(repairableRow.toolId) ?? repairableRow;
+    }
+    ensureToolSnapshotRepairConversation(row, viewerUserId) {
+        if (row.maintenanceConversationId && this.conversationManager.getConversation(row.maintenanceConversationId)) {
+            return row;
+        }
+        if (row.userId !== viewerUserId && !this.readModel.isAdminUser(viewerUserId)) {
+            return row;
+        }
+        const conversation = this.ensureMaintenanceConversation({
+            toolId: row.toolId,
+            userId: row.userId,
+            agentId: row.agentId,
+            maintenanceConversationId: row.maintenanceConversationId,
+        });
+        if (!conversation) {
+            return row;
+        }
+        if (row.maintenanceConversationId !== conversation.id) {
+            this.db.prepare(`UPDATE workspace_tools
+            SET maintenance_conversation_id = ?,
+                updated_at = ?
+          WHERE tool_id = ?`).run(conversation.id, Date.now(), row.toolId);
+        }
+        return { ...row, maintenanceConversationId: conversation.id };
+    }
+    shouldRepairToolSnapshotPanel(row) {
+        if (!row.maintenanceConversationId || !this.conversationManager.getConversation(row.maintenanceConversationId)) {
+            return false;
+        }
+        if (!row.panelId) {
+            return true;
+        }
+        const panel = getPanelById(this.db, row.panelId);
+        if (!panel || panel.archivedAt) {
+            return true;
+        }
+        if (panel.scopeType === 'tool' && panel.scopeId === row.toolId) {
+            return false;
+        }
+        log.warn('[workspace-tools] refusing to repair snapshot panel bound to a different scope', {
+            toolId: row.toolId,
+            panelId: row.panelId,
+            panelScopeType: panel.scopeType,
+            panelScopeId: panel.scopeId,
+        });
+        return false;
+    }
+    requireToolRow(userId, toolId) {
+        const row = this.readModel.loadToolRowForUser(userId, toolId);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return row;
+    }
+    getToolInfoForActionViewer(userId, toolId, allowAdminBypass) {
+        const row = this.readModel.loadToolRowForViewer(userId, toolId, { allowAdminBypass });
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return this.readModel.rowToToolInfoForViewer(row, userId);
+    }
+    copyPanelMaintainersToTool(params) {
+        for (const collaborator of listSurfaceCollaborators(this.db, 'panel', params.panelId)) {
+            if (collaborator.agentId === params.executionAgentId)
+                continue;
+            upsertSurfaceCollaborator(this.db, {
+                surfaceType: 'tool',
+                surfaceId: params.toolId,
+                agentId: collaborator.agentId,
+                role: 'collaborator',
+                addedBy: collaborator.addedBy ?? `panel:${params.panelId}`,
+                createdAt: params.createdAt,
+            });
+        }
+    }
+    assertAgentCanPublishToolRevision(params) {
+        if (params.tool.agentId === params.publishingAgentId) {
+            return;
+        }
+        const role = getSurfaceCollaboratorRole(this.db, 'tool', params.tool.toolId, params.publishingAgentId);
+        if (!role) {
+            throw new WorkspaceToolServiceError('Access denied.', 403);
+        }
+        const executionAgent = this.conversationManager.getAgent(params.tool.agentId);
+        if (!executionAgent?.nodeId || !executionAgent.workspacePath) {
+            throw new WorkspaceToolServiceError('Tool owner workspace is unavailable for collaborator republish.', 409);
+        }
+        if (executionAgent.nodeId !== params.agentNodeId
+            || path.normalize(executionAgent.workspacePath) !== path.normalize(params.agentWorkspacePath)) {
+            throw new WorkspaceToolServiceError('Tool collaborator republish must use the tool owner agent workspace; ask the owner agent to publish this revision.', 409);
+        }
+    }
+    isPanelEligibleForToolPromotion(userId, panel) {
+        if (panel.component !== 'RowTemplateGrid')
+            return false;
+        if (panel.datasetSource?.kind === 'query_handle' || panel.datasetSource?.kind === 'api_jsonl')
+            return false;
+        const conversation = this.conversationManager.getConversation(panel.conversationId);
+        if (!conversation || conversation.threadKind !== 'direct' || !conversation.agentId) {
+            return false;
+        }
+        const conversationUserId = conversation.userId?.trim()
+            || resolveDirectUserIdFromReplyTarget(this.db, conversation.replyTarget);
+        if (!conversationUserId || conversationUserId !== userId) {
+            return false;
+        }
+        return hasRowTemplateGridPromotionSeed(panel.props);
+    }
+    loadPanelToolPromotion(panelId) {
+        return this.db.prepare(`SELECT ptp.panel_id as panelId,
+              ptp.user_id as userId,
+              ptp.agent_id as agentId,
+              ptp.promotion_conversation_id as promotionConversationId,
+              ptp.tool_id as linkedToolId,
+              wt.deleted_at as linkedToolDeletedAt,
+              CASE WHEN wt.deleted_at IS NULL THEN wt.tool_id ELSE NULL END as toolId,
+              CASE WHEN wt.deleted_at IS NULL THEN wt.name ELSE NULL END as toolName,
+              CASE WHEN wt.deleted_at IS NULL THEN wt.revision ELSE NULL END as toolRevision,
+              CASE WHEN wt.deleted_at IS NULL THEN wt.maintenance_conversation_id ELSE NULL END as maintenanceConversationId,
+              ptp.created_at as createdAt,
+              ptp.updated_at as updatedAt
+         FROM panel_tool_promotions ptp
+         LEFT JOIN workspace_tools wt
+           ON wt.tool_id = ptp.tool_id
+        WHERE ptp.panel_id = ?
+        LIMIT 1`).get(panelId) ?? null;
+    }
+    toolProjectionHasBrowseControls(panelId, sourcePanelId) {
+        void panelId;
+        return Boolean(sourcePanelId);
+    }
+    getToolSurfaceMetadataForViewer(userId, panelId) {
+        const row = this.readModel.loadToolRowByPanelIdForViewer(userId, panelId);
+        if (!row) {
+            throw new WorkspaceToolServiceError('Tool not found.', 404);
+        }
+        return {
+            surfaceProfile: 'tool',
+            surfaceFeatures: {
+                browseControls: this.toolProjectionHasBrowseControls(panelId, row.sourcePanelId ?? null),
+            },
+        };
+    }
+    ensurePanelPromotionConversation(input) {
+        const threadRootId = buildPanelPromotionThreadRootId(input.panel.id);
+        const normalizedThreadRootId = normalizeThreadShortIdInput(threadRootId);
+        const equivalentThreadRootIds = new Set([normalizedThreadRootId, normalizedThreadRootId ? buildThreadShortId(normalizedThreadRootId) : null]
+            .filter((value) => Boolean(value)));
+        const existing = input.existingConversationId
+            ? this.conversationManager.getConversation(input.existingConversationId)
+            : null;
+        if (existing?.agentId === input.panel.agentId
+            && existing.threadKind === 'direct'
+            && !existing.isPrimaryThread
+            && equivalentThreadRootIds.has(normalizeThreadShortIdInput(existing.threadRootId) ?? '')
+            && !existing.userId?.trim()) {
+            const existingUserId = existing.userId?.trim()
+                || resolveDirectUserIdFromReplyTarget(this.db, existing.replyTarget);
+            if (existingUserId === input.userId) {
+                this.db.prepare(`UPDATE conversations
+              SET user_id = ?,
+                  updated_at = ?
+            WHERE id = ?`).run(input.userId, Date.now(), existing.id);
+            }
+        }
+        const conversation = input.activeProjectId === undefined
+            ? this.conversationManager.openAgentDirectThread(input.panel.agentId, input.userId, threadRootId)
+            : this.conversationManager.openAgentDirectThread(input.panel.agentId, input.userId, threadRootId, input.activeProjectId);
+        if (conversation) {
+            this.ensureToolMaintenanceConversationRoots(conversation.id);
+        }
+        return conversation;
+    }
+    buildPanelPromotionSlashBody(panel) {
+        const props = isPlainRecord(panel.props) ? panel.props : {};
+        const sampleRows = listPanelRows(this.db, panel.id, {
+            limit: PANEL_PROMOTION_SAMPLE_ROW_LIMIT,
+        }).rows.map((row) => ({
+            rowIndex: row.rowIndex,
+            rowId: row.rowId ?? null,
+            fields: row.fields,
+            media: row.media,
+        }));
+        const capsule = {
+            panel_id: panel.id,
+            agent_id: panel.agentId,
+            conversation_id: panel.conversationId,
+            component: panel.component,
+            title: typeof props.title === 'string' ? props.title : null,
+            fields: Array.isArray(props.fields) ? props.fields : [],
+            mediaSlots: Array.isArray(props.mediaSlots) ? props.mediaSlots : [],
+            template: isPlainRecord(props.template) ? props.template : null,
+            status: panel.status,
+            progress: panel.progress ?? null,
+            result: panel.result ?? null,
+            sampleRows,
+        };
+        return [
+            'Upgrade the existing panel into a reusable Workspace Tool.',
+            'This is a panel-sourced upgrade. Use the panel only as the tool view seed.',
+            'If a ready workspace-tool bundle already exists in the agent workspace, publish that bundle directly with publish_workspace_tool instead of recreating it.',
+            'Do not create or patch another panel.',
+            'Do not treat panel actions, submits, or read_panel_rows as the tool runtime.',
+            'Otherwise, define tool actions, status output, and params explicitly, then publish with publish_workspace_tool.',
+            'If this panel already has a linked tool, update that tool in place instead of creating a parallel tool.',
+            '[Panel promotion capsule]',
+            `\`\`\`json\n${JSON.stringify(capsule, null, 2)}\n\`\`\``,
+        ].join('\n\n');
+    }
+    assertWorkspaceToolAgentAvailable(agentId) {
+        const agent = this.conversationManager.getAgent(agentId);
+        const availability = getWorkspaceToolAgentAvailability(this.db, agent);
+        if (!availability.allowed) {
+            throw new WorkspaceToolServiceError(availability.error, 409);
+        }
+    }
+    async assertWorkspaceDirectoryAvailableForClone(params) {
+        try {
+            await this.workspaceBroker.listDirectory(params.nodeId, params.workspaceRoot, params.relativePath, {
+                scaffold: false,
+                limit: 1,
+                timeoutMs: WORKSPACE_TOOL_CLONE_ARCHIVE_TIMEOUT_MS,
+            });
+            throw new WorkspaceToolServiceError('Target tool bundle directory already exists.', 409);
+        }
+        catch (error) {
+            if (error instanceof WorkspaceToolServiceError)
+                throw error;
+            if (isWorkspaceFileMissingError(error))
+                return;
+            if (String(error?.message ?? error).includes('not_directory')) {
+                throw new WorkspaceToolServiceError('Target tool bundle path already exists and is not a directory.', 409);
+            }
+            throw new WorkspaceToolServiceError(`Unable to inspect target tool bundle directory: ${String(error?.message ?? error)}`, 409);
+        }
+    }
+    async snapshotPublishedBundle(params) {
+        const parentDir = path.posix.dirname(params.publishedBundleRoot);
+        const command = [
+            `mkdir -p -- ${shellEscape(parentDir)}`,
+            `rm -rf -- ${shellEscape(params.publishedBundleRoot)}`,
+            `mkdir -p -- ${shellEscape(params.publishedBundleRoot)}`,
+            `cp -R -- ${shellEscape(`${params.sourceBundleRoot}/.`)} ${shellEscape(`${params.publishedBundleRoot}/`)}`,
+        ].join(' && ');
+        let terminalId = null;
+        try {
+            const terminal = await this.terminalBroker.createTerminal(params.agentNodeId, {
+                workspaceRoot: params.workspaceRoot,
+                cwd: params.workspaceRoot,
+                name: 'workspace-tool publish snapshot',
+                startupCommand: command,
+                closeOnStartupCommand: true,
+            });
+            terminalId = terminal.terminalId;
+            const snapshot = await waitForTerminalExit(this.terminalBroker, params.agentNodeId, terminalId);
+            const completion = deriveOneShotRunCompletion(snapshot);
+            if (completion.status !== 'completed') {
+                throw new WorkspaceToolServiceError(`Failed to snapshot published tool bundle: ${(snapshot.buffer ?? '').trim() || 'copy command failed'}`, 500);
+            }
+        }
+        finally {
+            if (terminalId) {
+                await closeTerminalBestEffort(this.terminalBroker, params.agentNodeId, terminalId);
+            }
+        }
+    }
+}
+function buildPanelPromotionThreadRootId(panelId) {
+    return `${PANEL_TOOL_PROMOTION_THREAD_PREFIX}${panelId.trim().toLowerCase()}`;
+}
+function canAgentPublishWorkspaceTool(agent) {
+    return Boolean(agent?.nodeId?.trim() && agent?.workspacePath?.trim());
+}
+function loadNodeRuntimeCapabilities(db, nodeId) {
+    const normalizedNodeId = nodeId?.trim();
+    if (!normalizedNodeId)
+        return null;
+    const row = db.prepare(`SELECT capabilities_json as capabilitiesJson
+       FROM node_runtime_snapshots
+      WHERE node_id = ?
+      LIMIT 1`).get(normalizedNodeId);
+    if (!row?.capabilitiesJson)
+        return null;
+    try {
+        const parsed = JSON.parse(row.capabilitiesJson);
+        return parsed && typeof parsed === 'object'
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getWorkspaceToolAgentAvailability(db, agent) {
+    if (!canAgentPublishWorkspaceTool(agent)) {
+        return {
+            allowed: false,
+            error: 'This agent does not have a publishable workspace for /tool',
+        };
+    }
+    const capabilities = loadNodeRuntimeCapabilities(db, agent?.nodeId);
+    if (!capabilities?.skills) {
+        return {
+            allowed: false,
+            error: 'This agent node does not advertise builtin skill support required for /tool. Update the remote node and retry.',
+        };
+    }
+    const builtinSkillRoots = Array.isArray(capabilities.builtinSkillRoots)
+        ? capabilities.builtinSkillRoots
+            .filter((value) => typeof value === 'string')
+            .map((value) => value.trim())
+            .filter(Boolean)
+        : [];
+    const missingRoots = [
+        BUILTIN_WORKSPACE_TOOL_SKILL_ROOT_SENTINEL,
+        BUILTIN_UI_PANEL_SKILL_ROOT_SENTINEL,
+    ].filter((root) => !builtinSkillRoots.includes(root));
+    if (missingRoots.length > 0) {
+        return {
+            allowed: false,
+            error: 'This agent node is missing the builtin workspace-tool skills required for /tool. Push the latest code and run pnpm update:nodes:remote before retrying.',
+        };
+    }
+    return { allowed: true };
+}