@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/routes/execution-workspaces.js

@@ -1,7 +1,12 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants as fsConstants, existsSync, readFileSync } from "node:fs";
+import path from "node:path";
 import { and, eq } from "drizzle-orm";
 import { Router } from "express";
 import { issues, projects, projectWorkspaces } from "@paperclipai/db";
 import { findWorkspaceCommandDefinition, matchWorkspaceRuntimeServiceToCommand, reconcileExecutionWorkspaceBranchSchema, updateExecutionWorkspaceSchema, workspaceOverviewQuerySchema, workspaceRuntimeControlTargetSchema, } from "@paperclipai/shared";
+import { baseWorkspaceDeclaresInstanceConfig, resolveCanonicalWorktreeSeedSource, } from "@paperclipai/shared/worktree-seed-source";
+import { resolvePaperclipConfigPath } from "../paths.js";
 import { validate } from "../middleware/validate.js";
 import { accessService, executionWorkspaceService, heartbeatService, logActivity, workspaceOperationService, workspaceRuntimeLeaseService, LEASED_WORKSPACE_RUNTIME_ACTIONS, } from "../services/index.js";
 import { mergeExecutionWorkspaceConfig, readExecutionWorkspaceConfig } from "../services/execution-workspaces.js";
@@ -15,7 +20,29 @@ import { assertCanManageExecutionWorkspaceRuntimeServices } from "./workspace-ru
 import { appendWithCap } from "../adapters/utils.js";
 import { environmentRuntimeService } from "../services/environment-runtime.js";
 import { runExclusiveWorkspaceRuntimeControl } from "../services/workspace-operations.js";
+import { resolveManagedWorkspaceInstanceId } from "../services/managed-workspace-identity.js";
+import { isVerifiedWorktreeSeedManifest } from "../worktree-seed-manifest.js";
+import { issueWorkspaceLoginHandoff, workspaceLoginHandoffFailureStatus, } from "../services/workspace-login-handoff-issuer.js";
+import { conflict, unprocessable } from "../errors.js";
 const WORKSPACE_CONTROL_OUTPUT_MAX_CHARS = 256 * 1024;
+function isReadableFile(filePath) {
+    try {
+        accessSync(filePath, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The control plane's own instance config, named as the seed source only when the base
+ * project workspace is a plain checkout carrying no instance config of its own. A base
+ * workspace that has one stays authoritative, so an operator's mismatched source is
+ * still rejected.
+ */
+function resolveFallbackSeedSourceConfigPath(baseWorkspaceCwd) {
+    return baseWorkspaceDeclaresInstanceConfig(baseWorkspaceCwd) ? null : resolvePaperclipConfigPath();
+}
 export function executionWorkspaceRoutes(db, opts = {}) {
     const router = Router();
     const svc = executionWorkspaceService(db);
@@ -106,6 +133,81 @@ export function executionWorkspaceRoutes(db, opts = {}) {
         }
         res.json(readiness);
     });
+    /**
+     * Mint a single-use workspace login handoff for the calling board user.
+     *
+     * Board-only: the ticket carries a user identity, so an agent key — which has
+     * no user to sign in — must never be able to mint one. Nothing in the request
+     * body influences what the ticket is bound to; only the landing path is taken
+     * from the caller, and it is reduced to a same-origin path before signing.
+     */
+    router.post("/execution-workspaces/:id/login-handoff", async (req, res) => {
+        const id = req.params.id;
+        assertBoard(req);
+        const workspace = await getAccessibleResource(req, res, svc.getById(id), "Execution workspace not found");
+        if (!workspace)
+            return;
+        // Opening a workspace board is a runtime-control-grade action: it hands the
+        // caller an authenticated session inside the cloned instance.
+        if (!(await assertRuntimeManageAllowed(req, res, workspace.companyId)))
+            return;
+        const requestedNext = typeof req.body?.next === "string"
+            ? req.body.next
+            : null;
+        const result = await issueWorkspaceLoginHandoff({
+            db,
+            companyId: workspace.companyId,
+            executionWorkspace: { id: workspace.id, cwd: workspace.cwd },
+            actor: {
+                userId: req.actor.userId ?? null,
+                userEmail: req.actor.userEmail ?? null,
+                source: req.actor.source ?? null,
+            },
+            next: requestedNext,
+        });
+        if (!result.ok) {
+            logger.warn({
+                executionWorkspaceId: workspace.id,
+                reason: result.failure.reason,
+                detail: "detail" in result.failure ? result.failure.detail : null,
+            }, "workspace login handoff was not issued");
+            res.status(workspaceLoginHandoffFailureStatus(result.failure)).json({
+                error: "workspace_login_handoff_unavailable",
+                // The UI turns this into the labeled snapshot-local credential fallback
+                // or a repair prompt, so the machine reason has to survive the boundary.
+                reason: result.failure.reason,
+                mode: "credentials",
+                ...("detail" in result.failure ? { detail: result.failure.detail } : {}),
+                ...("readiness" in result.failure ? { readiness: result.failure.readiness } : {}),
+            });
+            return;
+        }
+        await logActivity(db, {
+            companyId: workspace.companyId,
+            // Auditing issuance is a requirement of the handoff design: the nonce ties
+            // this record to the guest's own accept/reject record. The ticket itself is
+            // never recorded.
+            action: "workspace_login_handoff_issued",
+            entityType: "execution_workspace",
+            entityId: workspace.id,
+            actorType: "user",
+            actorId: result.issuance.userId,
+            details: {
+                nonce: result.issuance.nonce,
+                instanceId: result.issuance.instanceId,
+                origin: result.issuance.origin,
+                expiresAt: result.issuance.expiresAt,
+            },
+        }).catch((error) => {
+            logger.warn({ err: error, executionWorkspaceId: workspace.id }, "failed to audit workspace login handoff");
+        });
+        res.setHeader("Cache-Control", "no-store");
+        res.status(201).json({
+            url: result.issuance.url,
+            expiresAt: result.issuance.expiresAt,
+            mode: "handoff",
+        });
+    });
     router.get("/execution-workspaces/:id/workspace-operations", async (req, res) => {
         const id = req.params.id;
         const workspace = await getAccessibleResource(req, res, svc.getById(id), "Execution workspace not found");
@@ -119,7 +221,7 @@ export function executionWorkspaceRoutes(db, opts = {}) {
     async function handleExecutionWorkspaceRuntimeCommand(req, res) {
         const id = req.params.id;
         const action = String(req.params.action ?? "").trim().toLowerCase();
-        if (action !== "start" && action !== "stop" && action !== "restart" && action !== "run") {
+        if (action !== "start" && action !== "stop" && action !== "restart" && action !== "repair" && action !== "run") {
             res.status(404).json({ error: "Workspace command action not found" });
             return;
         }
@@ -133,13 +235,6 @@ export function executionWorkspaceRoutes(db, opts = {}) {
             executionWorkspaceId: existing.id,
             sourceIssueId: existing.sourceIssueId,
         });
-        // Recover any managed runtime-control operation this workspace was stranded with, then
-        // refuse only if one is genuinely still live. Authorization above still gates the caller,
-        // so recovery never widens who may control the workspace.
-        await workspaceOperationsSvc.assertRuntimeControlAvailable({
-            executionWorkspaceId: existing.id,
-            action,
-        });
         const workspaceCwd = existing.cwd;
         if (!workspaceCwd) {
             res.status(422).json({ error: "Execution workspace needs a local path before Paperclip can run workspace commands" });
@@ -156,7 +251,7 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                 metadata: projectWorkspaces.metadata,
             })
                 .from(projectWorkspaces)
-                .where(and(eq(projectWorkspaces.id, existing.projectWorkspaceId), eq(projectWorkspaces.companyId, existing.companyId)))
+                .where(and(eq(projectWorkspaces.id, existing.projectWorkspaceId), eq(projectWorkspaces.companyId, existing.companyId), eq(projectWorkspaces.projectId, existing.projectId)))
                 .then((rows) => rows[0] ?? null)
             : null;
         const projectWorkspaceRuntime = readProjectWorkspaceRuntimeConfig(projectWorkspace?.metadata ?? null)?.workspaceRuntime ?? null;
@@ -174,6 +269,7 @@ export function executionWorkspaceRoutes(db, opts = {}) {
         const configuredServices = effectiveRuntimeConfig
             ? listConfiguredRuntimeServiceEntries({ workspaceRuntime: effectiveRuntimeConfig })
             : [];
+        const repairRestartsRuntimeServices = action === "repair" && configuredServices.length > 0;
         const workspaceCommand = effectiveRuntimeConfig
             ? findWorkspaceCommandDefinition(effectiveRuntimeConfig, target.workspaceCommandId ?? null)
             : null;
@@ -214,6 +310,70 @@ export function executionWorkspaceRoutes(db, opts = {}) {
             res.status(422).json({ error: "Execution workspace has no workspace command configuration or inherited project workspace default" });
             return;
         }
+        let repairSeedSource = null;
+        let repairPreviousAttemptId = null;
+        let repairCliArgs = null;
+        if (action === "repair") {
+            const manifestPath = path.join(workspaceCwd, ".paperclip", "seed-manifest.json");
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            }
+            catch {
+                throw unprocessable("Workspace seed manifest is malformed; repair source identity cannot be trusted.", {
+                    code: "workspace_repair_precondition_failed",
+                    reason: "seed_manifest_malformed",
+                    repairPhase: "precondition_validation",
+                });
+            }
+            try {
+                if (!projectWorkspace?.cwd) {
+                    throw new Error("Workspace repair requires a registered base project workspace.");
+                }
+                const expectedTargetInstanceId = resolveManagedWorkspaceInstanceId(workspaceCwd);
+                if (!expectedTargetInstanceId) {
+                    throw new Error("Workspace repair cannot resolve the registered target instance.");
+                }
+                repairSeedSource = resolveCanonicalWorktreeSeedSource({
+                    registeredBaseWorkspaceCwd: projectWorkspace.cwd,
+                    explicitSourceConfigPath: resolveFallbackSeedSourceConfigPath(projectWorkspace.cwd),
+                    targetConfigPath: path.join(workspaceCwd, ".paperclip", "config.json"),
+                    expectedTargetInstanceId,
+                    manifestSource: manifest.source,
+                    manifestTargetInstanceId: manifest.targetInstanceId,
+                });
+                repairPreviousAttemptId = typeof manifest.attemptId === "string" ? manifest.attemptId : null;
+                const baseWorkspaceCwd = repairSeedSource.baseWorkspaceCwd;
+                if (!baseWorkspaceCwd) {
+                    throw new Error("Workspace repair source is not bound to a registered base project workspace.");
+                }
+                const cliRunner = path.join(baseWorkspaceCwd, "cli", "node_modules", "tsx", "dist", "cli.mjs");
+                const cliEntry = path.join(baseWorkspaceCwd, "cli", "src", "index.ts");
+                const cliDist = path.join(baseWorkspaceCwd, "cli", "dist", "index.js");
+                repairCliArgs = isReadableFile(cliRunner) && isReadableFile(cliEntry)
+                    ? [cliRunner, cliEntry]
+                    : isReadableFile(cliDist)
+                        ? [cliDist]
+                        : null;
+                if (!repairCliArgs) {
+                    throw new Error("Workspace repair cannot find a runnable Paperclip CLI in the base workspace.");
+                }
+            }
+            catch (error) {
+                throw unprocessable(error instanceof Error ? error.message : "Workspace repair source validation failed.", {
+                    code: "workspace_repair_precondition_failed",
+                    reason: "source_registration_invalid",
+                    repairPhase: "precondition_validation",
+                });
+            }
+        }
+        // This check can reconcile a stale operation row, so repair source validation must
+        // precede it. Invalid manifest diagnostics must fail before any operation or service
+        // mutation, not merely before the reseed child process is spawned.
+        await workspaceOperationsSvc.assertRuntimeControlAvailable({
+            executionWorkspaceId: existing.id,
+            action,
+        });
         const actor = getActorInfo(req);
         const recorder = workspaceOperationsSvc.createRecorder({
             companyId: existing.companyId,
@@ -268,7 +428,11 @@ export function executionWorkspaceRoutes(db, opts = {}) {
             }
         }
         const recordRuntimeControlOperation = () => recorder.recordOperation({
-            phase: action === "stop" ? "workspace_teardown" : "workspace_provision",
+            phase: action === "stop"
+                ? "workspace_teardown"
+                : action === "repair"
+                    ? "workspace_repair"
+                    : "workspace_provision",
             command: workspaceCommand?.command ?? `workspace command ${action}`,
             cwd: existing.cwd,
             metadata: {
@@ -280,7 +444,7 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                 runtimeServiceId: selectedRuntimeServiceId,
                 serviceIndex: selectedServiceIndex,
             },
-            run: async () => {
+            run: async (reportProgress) => {
                 const ensureWorkspaceAvailable = async () => await ensurePersistedExecutionWorkspaceAvailable({
                     base: {
                         baseCwd: projectWorkspace?.cwd ?? workspaceCwd,
@@ -367,7 +531,203 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                     else
                         stderr = appendWithCap(stderr, chunk, WORKSPACE_CONTROL_OUTPUT_MAX_CHARS);
                 };
-                if (action === "stop" || action === "restart") {
+                if (action === "repair") {
+                    const repairDiagnostics = [];
+                    let repairPhase = "managed_stop";
+                    const repairPreconditionError = (status, reason, message) => {
+                        const details = {
+                            code: "workspace_repair_precondition_failed",
+                            reason,
+                            repairPhase,
+                        };
+                        return status === 409
+                            ? conflict(message, details)
+                            : unprocessable(message, details);
+                    };
+                    const reportRepairPhase = async (phase, status) => {
+                        repairPhase = phase;
+                        repairDiagnostics.push({ phase, status, at: new Date().toISOString() });
+                        if (repairDiagnostics.length > 32)
+                            repairDiagnostics.splice(0, repairDiagnostics.length - 32);
+                        await reportProgress({
+                            metadata: {
+                                repairPhase,
+                                repairDiagnostics: [...repairDiagnostics],
+                                databaseOnly: true,
+                                worktreePreserved: true,
+                            },
+                            system: `Workspace repair ${phase}: ${status}.\n`,
+                        });
+                    };
+                    try {
+                        await reportRepairPhase("managed_stop", "started");
+                        await stopRuntimeServicesForExecutionWorkspace({
+                            db,
+                            executionWorkspaceId: existing.id,
+                            workspaceCwd,
+                        });
+                        await reportRepairPhase("managed_stop", "succeeded");
+                        if (!repairSeedSource?.baseWorkspaceCwd || !repairCliArgs) {
+                            throw new Error("Workspace repair source preflight did not complete.");
+                        }
+                        const manifestPath = path.join(workspaceCwd, ".paperclip", "seed-manifest.json");
+                        const sourceConfigPath = repairSeedSource.configPath;
+                        const baseWorkspaceCwd = repairSeedSource.baseWorkspaceCwd;
+                        await reportRepairPhase("target_backup", "started");
+                        const child = spawn(process.execPath, [
+                            ...repairCliArgs,
+                            "worktree",
+                            "reseed",
+                            "--from-config",
+                            sourceConfigPath,
+                            "--to",
+                            workspaceCwd,
+                            "--seed-mode",
+                            "full",
+                            "--yes",
+                            "--backup-target",
+                        ], {
+                            cwd: baseWorkspaceCwd,
+                            env: {
+                                ...process.env,
+                                PAPERCLIP_SEED_EXPECTED_COMPANY_ID: existing.companyId,
+                                PAPERCLIP_WORKSPACE_BASE_CWD: baseWorkspaceCwd,
+                                PAPERCLIP_PROJECT_WORKSPACE_ID: existing.projectWorkspaceId ?? "",
+                            },
+                            stdio: ["ignore", "pipe", "pipe"],
+                        });
+                        child.stdout?.on("data", (chunk) => {
+                            void onLog("stdout", chunk.toString("utf8"));
+                        });
+                        child.stderr?.on("data", (chunk) => {
+                            void onLog("stderr", chunk.toString("utf8"));
+                        });
+                        let repairCommandTimedOut = false;
+                        let repairCommandForceTimeout = null;
+                        const repairCommandTimeout = setTimeout(() => {
+                            repairCommandTimedOut = true;
+                            child.kill("SIGTERM");
+                            repairCommandForceTimeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
+                            repairCommandForceTimeout.unref?.();
+                        }, 20 * 60_000);
+                        repairCommandTimeout.unref?.();
+                        let reseedObserved = false;
+                        const manifestPoll = setInterval(() => {
+                            if (reseedObserved || !existsSync(manifestPath))
+                                return;
+                            try {
+                                const current = JSON.parse(readFileSync(manifestPath, "utf8"));
+                                if (typeof current.attemptId === "string"
+                                    && current.attemptId !== repairPreviousAttemptId
+                                    && (current.state === "pending" || current.state === "running" || current.state === "failed")) {
+                                    reseedObserved = true;
+                                }
+                            }
+                            catch {
+                                // The atomic manifest writer makes this unlikely; the terminal
+                                // read below remains authoritative.
+                            }
+                        }, 100);
+                        manifestPoll.unref?.();
+                        const exitCode = await new Promise((resolve, reject) => {
+                            child.once("error", reject);
+                            child.once("exit", (code) => resolve(code ?? 1));
+                        }).finally(() => {
+                            clearInterval(manifestPoll);
+                            clearTimeout(repairCommandTimeout);
+                            if (repairCommandForceTimeout)
+                                clearTimeout(repairCommandForceTimeout);
+                        });
+                        if (reseedObserved) {
+                            await reportRepairPhase("target_backup", "succeeded");
+                            await reportRepairPhase("full_reseed", "started");
+                        }
+                        if (exitCode !== 0) {
+                            let seedFailurePhase = null;
+                            try {
+                                const failedManifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+                                seedFailurePhase = failedManifest.state === "failed" && typeof failedManifest.phase === "string"
+                                    ? failedManifest.phase
+                                    : null;
+                            }
+                            catch {
+                                // The outer repair phase remains exact when no seed phase was persisted.
+                            }
+                            await reportProgress({
+                                metadata: { seedFailurePhase },
+                                system: seedFailurePhase ? `Workspace seed failed during ${seedFailurePhase}.\n` : null,
+                            });
+                            throw new Error(repairCommandTimedOut
+                                ? `Workspace database repair command timed out during ${repairPhase}.`
+                                : `Workspace database repair command failed during ${repairPhase}.`);
+                        }
+                        if (!reseedObserved) {
+                            await reportRepairPhase("target_backup", "succeeded");
+                            await reportRepairPhase("full_reseed", "started");
+                        }
+                        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+                        if (!isVerifiedWorktreeSeedManifest(manifest)) {
+                            throw new Error("Workspace reseed returned without a verified terminal manifest.");
+                        }
+                        const expectedInstanceId = resolveManagedWorkspaceInstanceId(workspaceCwd);
+                        if (manifest.targetInstanceId !== expectedInstanceId) {
+                            throw repairPreconditionError(422, "seed_manifest_instance_mismatch", "Verified seed manifest belongs to a different workspace instance.");
+                        }
+                        resolveCanonicalWorktreeSeedSource({
+                            registeredBaseWorkspaceCwd: baseWorkspaceCwd,
+                            explicitSourceConfigPath: resolveFallbackSeedSourceConfigPath(baseWorkspaceCwd),
+                            targetConfigPath: path.join(workspaceCwd, ".paperclip", "config.json"),
+                            expectedTargetInstanceId: repairSeedSource.targetInstanceId,
+                            manifestSource: manifest.source,
+                            manifestTargetInstanceId: manifest.targetInstanceId,
+                        });
+                        await reportRepairPhase("full_reseed", "succeeded");
+                        await reportRepairPhase("managed_restart", "started");
+                        let startedServices = [];
+                        if (repairRestartsRuntimeServices) {
+                            const availableWorkspace = await ensureWorkspaceAvailable();
+                            if (!availableWorkspace) {
+                                throw new Error("Execution workspace needs a local path before Paperclip can restart it.");
+                            }
+                            startedServices = await startRuntimeServicesForWorkspaceControl({
+                                db,
+                                actor: {
+                                    id: actor.agentId ?? null,
+                                    name: actor.actorType === "user" ? "Board" : "Agent",
+                                    companyId: existing.companyId,
+                                },
+                                issue: existing.sourceIssueId
+                                    ? { id: existing.sourceIssueId, identifier: null, title: existing.name }
+                                    : null,
+                                workspace: availableWorkspace,
+                                executionWorkspaceId: existing.id,
+                                config: {
+                                    workspaceRuntime: effectiveRuntimeConfig,
+                                    runtimeProvisionCommand: existing.config?.runtimeProvisionCommand
+                                        ?? projectPolicy?.workspaceStrategy?.runtimeProvisionCommand
+                                        ?? null,
+                                },
+                                adapterEnv: {},
+                                onLog,
+                                recorder,
+                            });
+                        }
+                        runtimeServiceCount = startedServices.length;
+                        await reportRepairPhase("managed_restart", "succeeded");
+                        await reportRepairPhase("readiness_validation", "started");
+                        if (repairRestartsRuntimeServices
+                            && (startedServices.length === 0
+                                || startedServices.some((service) => service.status !== "running" || service.healthStatus !== "healthy"))) {
+                            throw new Error("Managed restart did not produce healthy runtime services.");
+                        }
+                        await reportRepairPhase("readiness_validation", "succeeded");
+                    }
+                    catch (error) {
+                        await reportRepairPhase(repairPhase, "failed");
+                        throw error;
+                    }
+                }
+                else if (action === "stop" || action === "restart") {
                     await stopRuntimeServicesForExecutionWorkspace({
                         db,
                         executionWorkspaceId: existing.id,
@@ -419,7 +779,7 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                     }
                     runtimeServiceCount = startedServices.length;
                 }
-                else {
+                else if (action !== "repair") {
                     runtimeServiceCount = selectedRuntimeServiceId ? Math.max(0, (existing.runtimeServices?.length ?? 1) - 1) : 0;
                 }
                 const currentDesiredState = existing.config?.desiredState
@@ -435,7 +795,9 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                         config: { workspaceRuntime: effectiveRuntimeConfig },
                         currentDesiredState,
                         currentServiceStates: existing.config?.serviceStates ?? null,
-                        action,
+                        action: action === "repair"
+                            ? repairRestartsRuntimeServices ? "start" : "stop"
+                            : action,
                         serviceIndex: selectedServiceIndex,
                     });
                 const metadata = mergeExecutionWorkspaceConfig(existing.metadata, {
@@ -451,12 +813,17 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                         ? "Stopped execution workspace runtime services.\n"
                         : action === "restart"
                             ? "Restarted execution workspace runtime services.\n"
-                            : "Started execution workspace runtime services.\n",
+                            : action === "repair"
+                                ? repairRestartsRuntimeServices
+                                    ? "Repaired the isolated workspace database and restarted healthy runtime services.\n"
+                                    : "Repaired the isolated workspace database; no managed runtime services were configured to restart.\n"
+                                : "Started execution workspace runtime services.\n",
                     metadata: {
                         runtimeServiceCount,
                         workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
                         runtimeServiceId: selectedRuntimeServiceId,
                         serviceIndex: selectedServiceIndex,
+                        runtimeRestarted: action === "repair" ? repairRestartsRuntimeServices : undefined,
                     },
                 };
             },
@@ -494,8 +861,9 @@ export function executionWorkspaceRoutes(db, opts = {}) {
                     // The operation is already terminal here. This also catches the recorder's own time
                     // budget expiring on a start that never settles, which is the one failure the inner
                     // handler cannot see — reconcile there too so no listener or desired state is left over.
-                    if (action === "start" || action === "restart")
+                    if (action === "start" || action === "restart" || action === "repair") {
                         await reconcileFailedRuntimeStart(error);
+                    }
                     throw error;
                 }
             },