@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/routes/agents.js

@@ -3,7 +3,7 @@ import { generateKeyPairSync, randomUUID } from "node:crypto";
 import path from "node:path";
 import { agents as agentsTable, companies, heartbeatRuns, issues as issuesTable, projects as projectsTable } from "@paperclipai/db";
 import { and, desc, eq, inArray, not, sql } from "drizzle-orm";
-import { agentSkillSyncSchema, agentMineInboxQuerySchema, ADAPTER_AGNOSTIC_KEYS, AGENT_DEFAULT_MAX_CONCURRENT_RUNS, createAgentKeySchema, createAgentHireSchema, createAgentSchema, deriveAgentUrlKey, isUuidLike, normalizeIssueIdentifier, resetAgentSessionSchema, testAdapterEnvironmentSchema, upsertAgentInstructionsFileSchema, updateAgentInstructionsBundleSchema, updateAgentPermissionsSchema, updateAgentInstructionsPathSchema, wakeAgentSchema, updateAgentSchema, supportedEnvironmentDriversForAdapter, LOW_TRUST_REVIEW_PRESET, startClaudeSetupTokenSessionRequestSchema, submitBrowserCodeRequestSchema, } from "@paperclipai/shared";
+import { agentSkillSyncSchema, agentMineInboxQuerySchema, ADAPTER_AGNOSTIC_KEYS, AGENT_DEFAULT_MAX_CONCURRENT_RUNS, createAgentKeySchema, createAgentHireSchema, createAgentSchema, deriveAgentUrlKey, isUuidLike, normalizeIssueIdentifier, resetAgentSessionSchema, testAdapterEnvironmentSchema, upsertAgentInstructionsFileSchema, updateAgentInstructionsBundleSchema, updateAgentPermissionsSchema, updateAgentInstructionsPathSchema, wakeAgentSchema, updateAgentSchema, supportedEnvironmentDriversForAdapter, LOW_TRUST_REVIEW_PRESET, startAdapterAuthSessionRequestSchema, startClaudeSetupTokenSessionRequestSchema, submitBrowserCodeRequestSchema, } from "@paperclipai/shared";
 import { isForbiddenConfigEnvKey, parseObject, resolvePaperclipInstanceRootForAdapter, readPaperclipSkillSyncPreference, writePaperclipSkillSyncPreference, } from "@paperclipai/adapter-utils/server-utils";
 import { trackAgentCreated } from "@paperclipai/shared/telemetry";
 import { validate } from "../middleware/validate.js";
@@ -11,6 +11,8 @@ import { agentService, agentInstructionsService, accessService, approvalService,
 import { badRequest, conflict, forbidden, HttpError, notFound, unprocessable } from "../errors.js";
 import { createRunSecretRedactionRegistry } from "../services/run-secret-redaction.js";
 import { assertAuthenticated, assertBoard, assertCompanyAccess, assertInstanceAdmin, buildActorSecretContext, getAccessibleResource, getActorInfo, hasCompanyAccess } from "./authz.js";
+import { runAdapterLoginStartSpine } from "./adapter-login-route-spine.js";
+import { isLoginCommandSupportedAdapterType } from "../services/login-command.js";
 import { assertNoAgentHostWorkspaceCommandMutation, collectAgentAdapterWorkspaceCommandPaths, } from "./workspace-command-authz.js";
 import { environmentService } from "../services/environments.js";
 import { resolveEnvironmentExecutionTarget } from "../services/environment-execution-target.js";
@@ -31,9 +33,10 @@ import { SetupTokenSessionService, SetupTokenSessionError, assessConfidentialSta
 import { SETUP_TOKEN_TRANSPORT_ADVISORY_CODE } from "@paperclipai/shared";
 import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX } from "@paperclipai/adapter-codex-local";
 import { checkStagedCredentialReadiness, promoteDeviceLoginCredential, } from "@paperclipai/adapter-codex-local/server";
-import { AdapterAuthSessionConflictError, CODEX_DEVICE_LOGIN_ADAPTER_TYPE, createCodexDeviceLoginService, createDbAdapterAuthSessionStore, createProductionLoginSessionRuntime, } from "../services/codex-device-login-service.js";
+import { AdapterAuthSessionConflictError, createCodexDeviceLoginService, createCodexWorkerBoundLoginPtyOpener, createDbAdapterAuthSessionStore, createProductionLoginSessionRuntime, CODEX_DEVICE_LOGIN_PROVIDER_UNSUPPORTED, CODEX_DEVICE_LOGIN_PROVIDER_UNSUPPORTED_CODE, } from "../services/codex-device-login-service.js";
 import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
 import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";
 import { DEFAULT_OPENCODE_LOCAL_MODEL } from "@paperclipai/adapter-opencode-local";
 import { requireOpenCodeModelId } from "@paperclipai/adapter-opencode-local/server";
 import { loadDefaultAgentInstructionsBundle, resolveDefaultAgentInstructionsBundleRole, } from "../services/default-agent-instructions.js";
@@ -97,6 +100,7 @@ export function agentRoutes(db, options = {}) {
         codex_local: "instructionsFilePath",
         droid_local: "instructionsFilePath",
         gemini_local: "instructionsFilePath",
+        kimi_local: "instructionsFilePath",
         opencode_local: "instructionsFilePath",
         cursor: "instructionsFilePath",
         pi_local: "instructionsFilePath",
@@ -178,8 +182,7 @@ export function agentRoutes(db, options = {}) {
     const setupTokenCleanupRows = new Map();
     const scopeMatchesRow = (row, identity) => row.companyId === identity.companyId &&
         row.ownerUserId === identity.ownerUserId &&
-        row.adapterType === identity.adapterType &&
-        row.environmentId === identity.environmentId;
+        row.adapterType === identity.adapterType;
     const inMemorySetupTokenCleanupStore = {
         async record(record) {
             setupTokenCleanupRows.set(record.sessionId, { ...record });
@@ -285,7 +288,27 @@ export function agentRoutes(db, options = {}) {
     const adapterLoginStore = createDbAdapterAuthSessionStore(db);
     const adapterLoginService = createCodexDeviceLoginService({
         store: adapterLoginStore,
-        runtime: createProductionLoginSessionRuntime({ db, environmentRuntime }),
+        runtime: createProductionLoginSessionRuntime({
+            db,
+            environmentRuntime,
+            // Re-check the provider login pseudo-terminal capability from current
+            // runtime state immediately before the provider lease. The route gate ran
+            // earlier, so a managed reconciliation can rebind the environment to an
+            // unsupported provider between the gate and the acquire; this fails closed
+            // before the lease and the pseudo-terminal.
+            assertProviderSupportsLoginPty: (environmentId) => assertCodexLoginProviderCapability(environmentId),
+            // Wire the live Codex pseudo-terminal opener through the plugin worker
+            // manager route. The opener sets the sandbox `CODEX_HOME` to the same
+            // server-controlled session home the descriptor-bound credential read
+            // opens. When no worker manager is bound, the runtime keeps its fail-closed
+            // opener and the login fails closed.
+            openLivePtySession: options.pluginWorkerManager
+                ? createCodexWorkerBoundLoginPtyOpener({
+                    workerManager: options.pluginWorkerManager,
+                    log: (line) => logger.info(line),
+                })
+                : undefined,
+        }),
         // The mandatory credential promotion. A successful login authenticates only
         // after this promotion validates the exact staged credential, runs an
         // independent readiness check, confirms the session still holds the sole
@@ -301,7 +324,7 @@ export function agentRoutes(db, options = {}) {
                 // first under the lock and the reaper reclaims only after it completes. A
                 // read-only fence is not enough, because the filesystem write can start
                 // after the fence; the lock spans the whole section.
-                const outcome = await adapterLoginStore.withCompanyAdapterPromotionLock(context.companyId, context.adapterType, () => promoteDeviceLoginCredential({
+                const outcome = await adapterLoginStore.withCompanyAdapterPromotionLock(context.companyId, context.startedByUserId, context.adapterType, () => promoteDeviceLoginCredential({
                     authBytes,
                     companyId: context.companyId,
                     userInitiated: true,
@@ -404,8 +427,8 @@ export function agentRoutes(db, options = {}) {
                 release: noopRelease,
             };
         }
-        const environment = await environmentsSvc.getById(input.environmentId);
-        if (!environment) {
+        const requestedEnvironment = await environmentsSvc.getById(input.environmentId);
+        if (!requestedEnvironment) {
             return {
                 executionTarget: null,
                 environmentName: null,
@@ -419,6 +442,35 @@ export function agentRoutes(db, options = {}) {
                 release: noopRelease,
             };
         }
+        // Managed-sandbox-only policy: redirect a Test that would run on the local
+        // host onto the platform-managed sandbox, the same as a real run does
+        // (resolveExecutionWorkspaceEnvironmentId in heartbeat). Without this
+        // redirect the Test probes the local host while the run executes in the
+        // managed sandbox, so a passing Test validates the wrong execution target.
+        // With no active managed sandbox the Test fails closed — never local.
+        let environment = requestedEnvironment;
+        if (requestedEnvironment.driver === "local") {
+            const managedSandboxOnly = (await instanceSettings.getExperimental()).enableManagedSandboxOnly === true;
+            if (managedSandboxOnly) {
+                const managedSandboxEnvironment = await environmentsSvc.findManagedSandboxEnvironment(input.companyId);
+                if (!managedSandboxEnvironment) {
+                    return {
+                        executionTarget: null,
+                        environmentName: requestedEnvironment.name,
+                        fallbackChecks: [
+                            {
+                                code: "managed_sandbox_unavailable",
+                                level: "error",
+                                message: "This instance runs agents only in its platform-managed sandbox, but no active managed sandbox environment exists. The test did not run.",
+                                hint: "Restore the managed sandbox environment, then test again.",
+                            },
+                        ],
+                        release: noopRelease,
+                    };
+                }
+                environment = managedSandboxEnvironment;
+            }
+        }
         if (environment.driver === "local") {
             return {
                 executionTarget: null,
@@ -509,6 +561,11 @@ export function agentRoutes(db, options = {}) {
                 issueId: null,
                 heartbeatRunId: null,
                 persistedExecutionWorkspace: null,
+                // Re-check the company binding atomically at lease time. The route
+                // guard already rejected a foreign environment, but the binding could
+                // change between the guard check and the lease acquire. This closes
+                // that check-to-lease race so a foreign sandbox never gets a lease.
+                assertCompanyBinding: true,
                 // Apply the active custom-image template so the Test boots with the
                 // operator's captured sandbox customizations and prepared image state,
                 // matching what real agent runs use. Without this the test would
@@ -613,7 +670,7 @@ export function agentRoutes(db, options = {}) {
                     {
                         code: "environment_target_failed",
                         level: "error",
-                        message: `Could not resolve a sandbox execution target for "${environment.name}".`,
+                        message: `Could not resolve an execution target for "${environment.name}".`,
                         detail: err instanceof Error ? err.message : String(err),
                     },
                 ],
@@ -692,9 +749,9 @@ export function agentRoutes(db, options = {}) {
         return {
             code: "sandbox_test_identity",
             level: "info",
-            message: `Sandbox test identity for "${input.environmentName}".`,
+            message: `Environment test identity for "${input.environmentName}".`,
             detail: detailParts.join("; "),
-            hint: "Use these provider-neutral IDs when comparing model-test output with provider logs or refreshed sandbox snapshots.",
+            hint: "Use these provider-neutral IDs when comparing model-test output with provider logs or refreshed environment snapshots.",
         };
     }
     async function getCurrentUserRedactionOptions() {
@@ -881,9 +938,31 @@ export function agentRoutes(db, options = {}) {
         }
         return userId;
     }
-    // The device-login flow supports only the Codex adapter. Reject any other type.
-    function assertCodexLoginAdapter(type) {
-        if (type !== CODEX_DEVICE_LOGIN_ADAPTER_TYPE) {
+    // Read the interactive login capability the registry declares for an adapter
+    // type. Return null when the adapter declares no capability, so a guard fails
+    // closed on the absent case.
+    function getRegistryLoginCapability(type) {
+        return findActiveServerAdapter(type)?.loginCapability ?? null;
+    }
+    // The device-login route drives a login that shows a one-time code on a real
+    // pseudo-terminal. It serves an adapter whose registry login capability
+    // declares the displayed-code panel mode and whose trusted adapter type maps
+    // to a login command key. The guard reads the panel mode and the command map,
+    // not the adapter name, so a new adapter that satisfies both passes with no
+    // guard code change. It rejects an adapter with no matching capability, and an
+    // adapter with no mapped command key, with the same fixed 400.
+    //
+    // The command-map check keeps admission consistent with the closed command
+    // map. The login opener resolves the command key from the same map. An adapter
+    // that declares the displayed-code capability but has no mapped key would pass
+    // the panel-mode check, then fail at command resolution after the route
+    // creates session state. The guard rejects it before any session or lease side
+    // effect.
+    function assertDeviceLoginAdapter(type) {
+        if (getRegistryLoginCapability(type)?.panelMode !== "displayed_code") {
+            throw badRequest(`Adapter "${type}" does not support a device login.`);
+        }
+        if (!isLoginCommandSupportedAdapterType(type)) {
             throw badRequest(`Adapter "${type}" does not support a device login.`);
         }
     }
@@ -927,14 +1006,15 @@ export function agentRoutes(db, options = {}) {
         }
     }
     /**
-     * Fails closed when the environment provider does not advertise the Claude
-     * setup-token login capability. It resolves the effective provider from the
-     * environment config, then reads the static capability from the provider
-     * plugin manifest. It never checks the provider by name. A missing plugin, a
-     * non-plugin provider, and a provider without the flag all fail closed with
-     * the fixed, typed error, so no session row, lease, or pseudo-terminal starts.
+     * Reports whether the environment provider advertises the login pseudo-terminal
+     * capability. It resolves the effective provider from the current environment
+     * config, then reads the static capability from the provider plugin manifest. It
+     * never checks the provider by name. A missing provider, a missing plugin, a
+     * non-plugin provider, and a provider without the flag all return false. Both
+     * login flows share this resolver, so both gates read the same current
+     * capability.
      */
-    async function assertSetupTokenLoginProviderCapability(environmentId) {
+    async function resolveProviderSupportsLoginPty(environmentId) {
         const environment = await environmentsSvc.getById(environmentId);
         const config = environment?.config && typeof environment.config === "object"
             ? environment.config
@@ -943,26 +1023,50 @@ export function agentRoutes(db, options = {}) {
         const resolved = provider
             ? await resolvePluginSandboxProviderDriverByKey({ db, driverKey: provider })
             : null;
-        if (!resolved?.driver.supportsSetupTokenLogin) {
+        return resolved?.driver.supportsLoginPty === true;
+    }
+    /**
+     * Fails closed when the environment provider does not advertise the login
+     * pseudo-terminal capability that the Claude setup-token login needs. It reads
+     * the current provider capability. It fails closed with the fixed, typed error,
+     * so no session row, lease, or pseudo-terminal starts.
+     */
+    async function assertSetupTokenLoginProviderCapability(environmentId) {
+        if (!(await resolveProviderSupportsLoginPty(environmentId))) {
             throw unprocessable(SETUP_TOKEN_PROVIDER_UNSUPPORTED, {
                 code: SETUP_TOKEN_PROVIDER_UNSUPPORTED_CODE,
             });
         }
     }
+    /**
+     * Fails closed when the environment provider does not advertise the login
+     * pseudo-terminal capability that the Codex device login needs. It reads the
+     * current provider capability. The Codex route runs it before any session or
+     * lease state, and the lease-acquisition path runs it again from current runtime
+     * state before the provider lease. It fails closed with the fixed, typed error,
+     * so no session row, lease, or pseudo-terminal starts.
+     */
+    async function assertCodexLoginProviderCapability(environmentId) {
+        if (!(await resolveProviderSupportsLoginPty(environmentId))) {
+            throw unprocessable(CODEX_DEVICE_LOGIN_PROVIDER_UNSUPPORTED, {
+                code: CODEX_DEVICE_LOGIN_PROVIDER_UNSUPPORTED_CODE,
+            });
+        }
+    }
     // Read a login session for its owner. The durable row is the authority for the
     // company and the owner. This returns null when the row is absent, when it
     // belongs to another company or adapter, or when the requesting user is not the
     // owner. So a non-owner and a cross-company caller both receive a 404 and cannot
     // enumerate a session. Only the owner path reads the one-time prompt.
-    async function readOwnerLoginSession(companyId, adapterType, sessionId, requestingUserId) {
-        const row = await adapterLoginStore.get(sessionId);
-        if (!row ||
-            row.companyId !== companyId ||
-            row.adapterType !== adapterType ||
-            row.startedByUserId !== requestingUserId) {
+    async function readOwnerLoginSession(companyId, adapterType, publicSessionId, requestingUserId) {
+        // Read by the public session id, scoped to the company. The store predicate
+        // already carries the company id, so a foreign-company caller reads nothing
+        // and the internal row id never matches. Keep the adapter and owner checks.
+        const row = await adapterLoginStore.getByPublicId(publicSessionId, companyId);
+        if (!row || row.adapterType !== adapterType || row.startedByUserId !== requestingUserId) {
             return null;
         }
-        return adapterLoginService.readOwnerSession(sessionId, requestingUserId);
+        return adapterLoginService.readOwnerSession(publicSessionId, companyId, requestingUserId);
     }
     async function assertCanReadConfigurations(req, companyId) {
         // Reading agent configurations, skills, and config revisions is a
@@ -1453,6 +1557,10 @@ export function agentRoutes(db, options = {}) {
             next.model = DEFAULT_GEMINI_LOCAL_MODEL;
             return ensureGatewayDeviceKey(adapterType, next);
         }
+        if (adapterType === "kimi_local" && !asNonEmptyString(next.model)) {
+            next.model = DEFAULT_KIMI_LOCAL_MODEL;
+            return ensureGatewayDeviceKey(adapterType, next);
+        }
         if (adapterType === "opencode_local" && !asNonEmptyString(next.model)) {
             next.model = DEFAULT_OPENCODE_LOCAL_MODEL;
             return ensureGatewayDeviceKey(adapterType, next);
@@ -1577,6 +1685,19 @@ export function agentRoutes(db, options = {}) {
     async function assertCanApplyAgentProfileChange(req, targetAgent) {
         await assertCanApplyProtectedAgentChange(req, targetAgent, [agentProfileChangeTargetKey(targetAgent.id)]);
     }
+    async function assertCanResumeAgent(req, targetAgent) {
+        if (req.actor.type !== "agent")
+            return;
+        const decision = await access.decide({
+            actor: req.actor,
+            action: "agent_config:update",
+            resource: { type: "agent", companyId: targetAgent.companyId, agentId: targetAgent.id },
+            scope: { requiresChangeGrant: true },
+        });
+        if (decision.allowed)
+            return;
+        throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
+    }
     function assertNoAgentInstructionsConfigMutation(req, adapterConfig, path = "adapterConfig") {
         if (req.actor.type !== "agent" || !adapterConfig)
             return;
@@ -1822,6 +1943,34 @@ export function agentRoutes(db, options = {}) {
         const detected = await detectAdapterModel(type);
         res.json(detected);
     });
+    // The environment drivers the adapter Test route accepts. A local, SSH, or
+    // sandbox environment can host a probe; a plugin environment cannot.
+    const ADAPTER_TEST_ALLOWED_ENVIRONMENT_DRIVERS = ["local", "ssh", "sandbox"];
+    // The fail-closed tenant-binding guard for the adapter Test route. A caller
+    // may name any instance environment by id, so the route must reject an
+    // environment that binds to another company before it resolves secrets,
+    // merges env, resolves the target, leases a sandbox, or runs the adapter
+    // test. The guard checks the company binding BEFORE it validates the status
+    // or the driver, so it never reveals the status or the driver of a foreign
+    // environment. A same-company or an instance-global environment then gets the
+    // shared driver and status validation.
+    async function assertAdapterTestEnvironmentForCompany(companyId, environmentId) {
+        const environment = await environmentsSvc.getById(environmentId);
+        if (!environment) {
+            // A missing environment leaks no tenant state. The execution-context
+            // resolver surfaces the existing environment_not_found check.
+            return;
+        }
+        const boundCompanyIds = await environmentsSvc.listBoundCompanyIds(environmentId);
+        if (boundCompanyIds.length > 0 && !boundCompanyIds.includes(companyId)) {
+            throw forbidden("The selected environment belongs to another company.", {
+                code: "environment_company_mismatch",
+            });
+        }
+        await assertEnvironmentSelectionForCompany(environmentsSvc, companyId, environmentId, {
+            allowedDrivers: ADAPTER_TEST_ALLOWED_ENVIRONMENT_DRIVERS,
+        });
+    }
     router.post("/companies/:companyId/adapters/:type/test-environment", validate(testAdapterEnvironmentSchema), async (req, res) => {
         const companyId = req.params.companyId;
         const type = assertKnownAdapterType(req.params.type);
@@ -1831,6 +1980,11 @@ export function agentRoutes(db, options = {}) {
         const requestedEnvironmentId = typeof req.body?.environmentId === "string" && req.body.environmentId.trim().length > 0
             ? req.body.environmentId
             : null;
+        // Fail closed on a foreign environment before any secret resolution, env
+        // merge, target resolution, sandbox lease, or adapter test runs.
+        if (requestedEnvironmentId) {
+            await assertAdapterTestEnvironmentForCompany(companyId, requestedEnvironmentId);
+        }
         const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(companyId, inputAdapterConfig, { strictMode: strictSecretsMode, adapterType: type });
         // Prospective, non-persisted config: resolve the acting user's own user
         // secrets in owner_scoped mode (no declaration rows exist for this config).
@@ -1945,28 +2099,42 @@ export function agentRoutes(db, options = {}) {
     router.post("/companies/:companyId/adapters/:type/login-sessions", async (req, res) => {
         const companyId = req.params.companyId;
         const type = req.params.type;
-        const startedByUserId = await assertCanManageAdapterLogin(req, companyId);
-        assertCodexLoginAdapter(type);
-        const environmentId = typeof req.body?.environmentId === "string" && req.body.environmentId.trim().length > 0
-            ? req.body.environmentId
-            : null;
-        if (!environmentId) {
-            throw badRequest("A sandbox environment is required to start a device login.");
-        }
-        const ttlSeconds = typeof req.body?.ttlSeconds === "number" && Number.isFinite(req.body.ttlSeconds)
-            ? req.body.ttlSeconds
-            : undefined;
-        // Reject a non-sandbox or inactive environment before the service starts.
-        await assertSandboxLoginEnvironment(companyId, environmentId);
+        // The shared start-route spine derives the owner, checks the path adapter
+        // type, validates the strict request schema, and checks the sandbox
+        // environment before any session or lease side effect. The client body
+        // carries no adapter type, so the spine injects the path type into the
+        // parse. The strict schema rejects an unknown field, a non-uuid
+        // environment id, and an out-of-range time-to-live with a fixed 400.
+        const resolved = await runAdapterLoginStartSpine({
+            req,
+            res,
+            deriveOwner: () => assertCanManageAdapterLogin(req, companyId),
+            guardBeforeValidate: () => assertDeviceLoginAdapter(type),
+            requestSchema: startAdapterAuthSessionRequestSchema,
+            invalidRequestError: "The device login start request is invalid.",
+            requestOverrides: { adapterType: type },
+            assertSandbox: async (data) => {
+                // The device login runs on a real pseudo-terminal, so it needs a
+                // provider that advertises the login pseudo-terminal capability. Gate
+                // the route on the current provider capability before any session or
+                // lease state. The lease-acquisition path re-checks it from current
+                // runtime state before the provider lease.
+                await assertSandboxLoginEnvironment(companyId, data.environmentId);
+                await assertCodexLoginProviderCapability(data.environmentId);
+            },
+        });
+        if (!resolved)
+            return;
+        const { ownerUserId: startedByUserId, data } = resolved;
         const controller = new AbortController();
         let result;
         try {
             result = await adapterLoginService.start({
                 companyId,
-                environmentId,
+                environmentId: data.environmentId,
                 adapterType: type,
                 startedByUserId,
-                ttlSeconds,
+                ttlSeconds: data.ttlSeconds,
                 signal: controller.signal,
             });
         }
@@ -1997,7 +2165,7 @@ export function agentRoutes(db, options = {}) {
         const type = req.params.type;
         const sessionId = req.params.sessionId;
         const ownerUserId = await assertCanManageAdapterLogin(req, companyId);
-        assertCodexLoginAdapter(type);
+        assertDeviceLoginAdapter(type);
         const owner = await readOwnerLoginSession(companyId, type, sessionId, ownerUserId);
         if (!owner) {
             res.status(404).json({ error: "Adapter login session not found" });
@@ -2012,7 +2180,7 @@ export function agentRoutes(db, options = {}) {
         const type = req.params.type;
         const sessionId = req.params.sessionId;
         const ownerUserId = await assertCanManageAdapterLogin(req, companyId);
-        assertCodexLoginAdapter(type);
+        assertDeviceLoginAdapter(type);
         // Scope the cancel to this company, adapter, and owner. A non-owner and a
         // cross-company caller both receive a 404 and cannot cancel a session.
         const owner = await readOwnerLoginSession(companyId, type, sessionId, ownerUserId);
@@ -2024,7 +2192,7 @@ export function agentRoutes(db, options = {}) {
         // even when this process does not own the in-flight run, so a cross-process
         // cancel or a cancel after a restart does not leave the slot held until the
         // expiry. The reaper deletes the sandbox and finalizes the terminal.
-        const cancelled = await adapterLoginService.cancelOwnerSession(sessionId, ownerUserId);
+        const cancelled = await adapterLoginService.cancelOwnerSession(sessionId, companyId, ownerUserId);
         // Abort the in-flight run this process owns, so the local login stops at
         // once instead of waiting for the reaper. A run in another process, or an
         // already-terminal run, has no controller here.
@@ -3105,12 +3273,12 @@ export function agentRoutes(db, options = {}) {
         res.json(agent);
     });
     router.post("/agents/:id/resume", async (req, res) => {
-        assertBoard(req);
         const id = req.params.id;
         const existing = await getAccessibleAgent(req, res, id);
         if (!existing) {
             return;
         }
+        await assertCanResumeAgent(req, existing);
         if (existing.orgChainHealth?.status === "invalid_org_chain") {
             res.status(409).json({
                 error: existing.orgChainHealth?.repairGuidance ?? "Repair this agent's reporting chain before resuming it",
@@ -3122,10 +3290,14 @@ export function agentRoutes(db, options = {}) {
             res.status(404).json({ error: "Agent not found" });
             return;
         }
+        const actor = getActorInfo(req);
         await logActivity(db, {
             companyId: agent.companyId,
-            actorType: "user",
-            actorId: req.actor.userId ?? "board",
+            actorType: actor.actorType,
+            actorId: actor.actorId,
+            agentId: actor.agentId,
+            runId: actor.runId,
+            agentApiKeyId: actor.agentApiKeyId,
             action: "agent.resumed",
             entityType: "agent",
             entityId: agent.id,
@@ -3702,61 +3874,79 @@ export function agentRoutes(db, options = {}) {
     });
     router.post("/companies/:companyId/setup-token-login-sessions", async (req, res) => {
         const companyId = req.params.companyId;
-        assertCompanyAccess(req, companyId);
-        const ownerUserId = deriveSetupTokenOwnerUserId(req);
-        res.setHeader("Cache-Control", "no-store");
-        // Parse the request with the shared strict validator before any session,
-        // lease, or pseudo-terminal side effect. `.strict()` rejects an unknown field,
-        // including a legacy `ttlSeconds`, with a fixed 400. The route echoes no input.
-        const parsed = startClaudeSetupTokenSessionRequestSchema.safeParse(req.body);
-        if (!parsed.success) {
-            res.status(400).json({ error: "The Claude login start request is invalid." });
-            return;
-        }
-        const { environmentId, adapterType } = parsed.data;
-        const confirmedOverwrite = parsed.data.overwrite ?? null;
-        // The company-and-environment login serves only the Claude adapter. A
-        // different adapter type gets a fixed 400.
-        if (adapterType !== CLAUDE_SETUP_TOKEN_ADAPTER_TYPE) {
-            res.status(400).json({ error: "Only the claude_local adapter supports a setup-token login." });
-            return;
-        }
-        if (!SETUP_TOKEN_LOGIN_TRANSPORT_READY) {
-            // The live login transport binds at a later call site. Fail closed with the
-            // fixed no-secret error until then.
-            res.status(503).json({ error: SETUP_TOKEN_START_FAILED });
-            return;
-        }
-        // Resolve the environment server-side to a live instance sandbox. It fails
-        // closed on a missing, archived, non-sandbox, or fake-provider environment, so
-        // the route never persists an empty or invalid environment scope. It runs
-        // before the session starts, so no store holds a rejected environment. It
-        // also rejects an environment that another company owns (see
-        // `assertSandboxLoginEnvironment`), so a login never runs in a foreign
-        // company sandbox. It also fails closed when the provider does not advertise
-        // the setup-token login capability, so an unsupported provider never reaches
-        // a session row, a lease, or a pseudo-terminal.
-        await assertSandboxLoginEnvironment(companyId, environmentId, {
-            requireSetupTokenLoginProvider: true,
+        // The shared start-route spine derives the owner, validates the strict
+        // request schema, runs the Claude-only guards, and checks the sandbox
+        // environment before any session, lease, or pseudo-terminal side effect.
+        //
+        // The owner step runs the company access check, derives the owner, and then
+        // sets `Cache-Control: no-store`, so a rejected member sees no cache header
+        // and every other response carries it. The strict schema rejects an unknown
+        // field, including a legacy `ttlSeconds`, with a fixed 400. The post-validate
+        // guard rejects a non-Claude adapter with a fixed 400 and fails closed with
+        // the fixed no-secret 503 until the live login transport binds. The sandbox
+        // check fails closed on a missing, archived, non-sandbox, fake-provider, or
+        // foreign environment, and on a provider without the setup-token login
+        // capability, so no rejected environment reaches a session row, a lease, or a
+        // pseudo-terminal.
+        const resolved = await runAdapterLoginStartSpine({
+            req,
+            res,
+            deriveOwner: () => {
+                assertCompanyAccess(req, companyId);
+                const ownerUserId = deriveSetupTokenOwnerUserId(req);
+                res.setHeader("Cache-Control", "no-store");
+                return ownerUserId;
+            },
+            requestSchema: startClaudeSetupTokenSessionRequestSchema,
+            invalidRequestError: "The Claude login start request is invalid.",
+            guardAfterValidate: (data) => {
+                // The setup-token route drives a login on a pseudo-terminal and records a
+                // stored session identifier on success. It serves any adapter whose
+                // registry login capability records that completion claim. The guard reads
+                // the capability, not the adapter name, so a new adapter with the same
+                // claim passes with no code change. It rejects an adapter with no matching
+                // capability with a fixed 400.
+                const capability = getRegistryLoginCapability(data.adapterType);
+                if (capability?.completionClaim !== "storedSessionId") {
+                    res.status(400).json({ error: "This adapter does not support a setup-token login." });
+                    return true;
+                }
+                if (!SETUP_TOKEN_LOGIN_TRANSPORT_READY) {
+                    res.status(503).json({ error: SETUP_TOKEN_START_FAILED });
+                    return true;
+                }
+                return false;
+            },
+            assertSandbox: (data) => assertSandboxLoginEnvironment(companyId, data.environmentId, {
+                requireSetupTokenLoginProvider: true,
+            }),
         });
+        if (!resolved)
+            return;
+        const { ownerUserId, data } = resolved;
+        const { environmentId, adapterType } = data;
+        const confirmedOverwrite = data.overwrite ?? null;
         const scope = {
             companyId,
             ownerUserId,
-            targetAgentId: null,
             adapterType,
             environmentId,
             confirmedOverwrite,
         };
+        // Read the panel mode from the adapter capability. The guard already checked
+        // the capability, so it is present here. The client renders the panel from
+        // this value instead of a hard-coded mode.
+        const panelMode = getRegistryLoginCapability(adapterType)?.panelMode ?? "submitted_browser_code";
         try {
             const started = await setupTokenLoginService.start(scope);
             const descriptor = setupTokenLoginService.describeOwned(started.sessionId, scope);
             // The start response carries the panel mode, so the client renders the
-            // browser-code panel. The full login URL rides only through the
-            // guarded prompt read, not the start response, so the prompt is null here.
-            // The client reads the prompt route for the login URL.
+            // correct panel. The full login URL rides only through the guarded prompt
+            // read, not the start response, so the prompt is null here. The client
+            // reads the prompt route for the login URL.
             const body = {
                 ...toClaudePublicResponse(descriptor),
-                panelMode: "submitted_browser_code",
+                panelMode,
                 prompt: null,
             };
             res.status(201).json(body);