@paperclipai/server 2026.817.0 → 2026.818.0-beta.1

package/dist/routes/agents.js

@@ -3,28 +3,35 @@ 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, } 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, 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";
 import { agentService, agentInstructionsService, accessService, approvalService, builtInAgentService, companySkillService, budgetService, heartbeatService, ISSUE_LIST_DEFAULT_LIMIT, issueApprovalService, issueRecoveryActionService, issueService, logActivity, syncInstructionsBundleConfigFromFilePath, workspaceOperationService, } from "../services/index.js";
 import { badRequest, conflict, forbidden, HttpError, notFound, unprocessable } from "../errors.js";
 import { createRunSecretRedactionRegistry } from "../services/run-secret-redaction.js";
-import { assertBoard, assertCompanyAccess, assertInstanceAdmin, buildActorSecretContext, getAccessibleResource, getActorInfo, hasCompanyAccess } from "./authz.js";
+import { assertAuthenticated, assertBoard, assertCompanyAccess, assertInstanceAdmin, buildActorSecretContext, getAccessibleResource, getActorInfo, hasCompanyAccess } from "./authz.js";
 import { assertNoAgentHostWorkspaceCommandMutation, collectAgentAdapterWorkspaceCommandPaths, } from "./workspace-command-authz.js";
 import { environmentService } from "../services/environments.js";
 import { resolveEnvironmentExecutionTarget } from "../services/environment-execution-target.js";
 import { environmentRuntimeService } from "../services/environment-runtime.js";
+import { resolvePluginSandboxProviderDriverByKey } from "../services/plugin-environment-driver.js";
+import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";
 import { skillVersionSelectionMap } from "../services/runtime-skill-selections.js";
 import { secretService } from "../services/secrets.js";
 import { authorizationDeniedDetails } from "../services/authorization.js";
-import { detectAdapterModel, findActiveServerAdapter, findServerAdapter, listAdapterModels, listAdapterModelProfiles, refreshAdapterModels, requireServerAdapter, } from "../adapters/index.js";
+import { detectAdapterModel, findActiveServerAdapter, findServerAdapter, listServerAdapters, listAdapterModels, listAdapterModelProfiles, refreshAdapterModels, requireServerAdapter, } from "../adapters/index.js";
 import { redactEventPayload } from "../redaction.js";
 import { redactCurrentUserValue } from "../log-redaction.js";
 import { renderOrgChartSvg, renderOrgChartPng, ORG_CHART_STYLES } from "./org-chart-svg.js";
 import { instanceSettingsService, isTruthyRuntimeEnvValue, resolveWorktreeRunExecutionActivationState, } from "../services/instance-settings.js";
 import { runClaudeLogin } from "@paperclipai/adapter-claude-local/server";
+import { createInviteRateLimiter } from "../services/invite-rate-limit.js";
+import { SetupTokenSessionService, SetupTokenSessionError, assessConfidentialStartup, evaluateConfidentialTransport, SETUP_TOKEN_START_FAILED, SETUP_TOKEN_SESSION_NOT_FOUND, SETUP_TOKEN_PROVIDER_UNSUPPORTED, SETUP_TOKEN_PROVIDER_UNSUPPORTED_CODE, } from "../services/setup-token-session.js";
+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 { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
 import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
 import { DEFAULT_OPENCODE_LOCAL_MODEL } from "@paperclipai/adapter-opencode-local";
@@ -131,6 +138,134 @@ export function agentRoutes(db, options = {}) {
     const environmentRuntime = environmentRuntimeService(db, {
         pluginWorkerManager: options.pluginWorkerManager,
     });
+    // --- Setup-token login session (Claude in-product login) -------------------
+    //
+    // The service owns a company-scoped, owner-bound login session, the
+    // confidential transport guard (SR-6, SR-7), the session caps, and the start
+    // rate limit. The `options.setupTokenLogin` transport binds the live sandbox
+    // pseudo-terminal login process and the real sandbox-lease acquisition. When a
+    // caller provides the transport, the session route is the live login path and
+    // `SETUP_TOKEN_LOGIN_TRANSPORT_READY` is true. When a caller omits it, the
+    // start route returns the fixed no-secret error and the login never spawns a
+    // process or holds a lease. The full session state machine, the cleanup order,
+    // and the reaper are covered by setup-token-session.test.ts.
+    const SETUP_TOKEN_LOGIN_TRANSPORT_READY = options.setupTokenLogin != null;
+    const setupTokenConfidentialConfig = {
+        deploymentMode: options.deploymentMode ?? "local_trusted",
+        trustedProxies: options.confidentialProxyAllowlist ?? [],
+        edgeTlsTerminated: options.confidentialEdgeTlsTerminated ?? false,
+    };
+    // Rate-limit the start route: a small window per company and owner (SR-4).
+    const setupTokenRateLimiter = createInviteRateLimiter({ windowMs: 60_000, maxRequests: 5 });
+    // The deferred lease manager. It fails closed on acquire until a caller binds
+    // the live transport. It still releases a lease by handle or by id, so a
+    // reaper or a shutdown can free a lease that an injected transport acquired.
+    const deferredSetupTokenLeaseManager = {
+        async acquire() {
+            // The real sandbox-lease acquisition binds through `options.setupTokenLogin`.
+            // Until then the start route fails closed before it reaches here.
+            throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);
+        },
+        async release(lease) {
+            await environmentsSvc.releaseLease(lease.id, "released").catch(() => { });
+        },
+        async releaseById(leaseId) {
+            await environmentsSvc.releaseLease(leaseId, "released").catch(() => { });
+        },
+    };
+    // The in-memory non-secret cleanup record store. It is the default store when a
+    // caller does not inject a durable database-backed store.
+    const setupTokenCleanupRows = new Map();
+    const scopeMatchesRow = (row, identity) => row.companyId === identity.companyId &&
+        row.ownerUserId === identity.ownerUserId &&
+        row.adapterType === identity.adapterType &&
+        row.environmentId === identity.environmentId;
+    const inMemorySetupTokenCleanupStore = {
+        async record(record) {
+            setupTokenCleanupRows.set(record.sessionId, { ...record });
+        },
+        async markState(identity, state) {
+            const row = setupTokenCleanupRows.get(identity.sessionId);
+            if (row && scopeMatchesRow(row, identity))
+                row.state = state;
+        },
+        async remove(identity) {
+            // The delete matches the full owner scope, so it never removes a row by the
+            // session id alone.
+            const row = setupTokenCleanupRows.get(identity.sessionId);
+            if (row && scopeMatchesRow(row, identity))
+                setupTokenCleanupRows.delete(identity.sessionId);
+        },
+        async listReapable() {
+            return [];
+        },
+        async consumeStoredClaim(identity) {
+            const row = setupTokenCleanupRows.get(identity.sessionId);
+            if (!row ||
+                !scopeMatchesRow(row, identity) ||
+                row.state !== "stored" ||
+                row.boundAt !== null ||
+                row.deadline <= Date.now()) {
+                return null;
+            }
+            row.boundAt = Date.now();
+            return { ...row };
+        },
+    };
+    const deferredSetupTokenLoginFactory = () => {
+        // The runner-over-pseudo-terminal binding arrives through
+        // `options.setupTokenLogin`. Until then the start route fails closed.
+        throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);
+    };
+    const deferredSetupTokenSecretWriter = async () => {
+        // The owner-bound secret writer arrives through `options.setupTokenLogin`.
+        // Until then the completion fails closed, so the session never reports a
+        // stored credential without a real secret write.
+        throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);
+    };
+    // Resolve the transport: use the injected factory, lease manager, store, and
+    // secret writer when a caller binds them; otherwise use the deferred,
+    // fail-closed defaults.
+    const setupTokenLoginFactory = options.setupTokenLogin?.factory ?? deferredSetupTokenLoginFactory;
+    const setupTokenLeaseManager = options.setupTokenLogin?.leases ?? deferredSetupTokenLeaseManager;
+    const setupTokenCleanupStore = options.setupTokenLogin?.store ?? inMemorySetupTokenCleanupStore;
+    const setupTokenSecretWriter = options.setupTokenLogin?.completeCredential ?? deferredSetupTokenSecretWriter;
+    // Re-check the environment company binding at lease acquisition. The start
+    // route runs `assertSandboxLoginEnvironment` before the session begins, but
+    // managed-environment reconciliation can bind the sandbox to another company
+    // between that guard and the lease acquire. This wrapper re-runs the same
+    // guard at acquire time and fails closed with the 403
+    // `environment_company_mismatch` before the transport provisions a sandbox.
+    // The lease insert transaction re-checks the binding once more inside the
+    // insert, so a bind that lands during the provider call still holds no lease.
+    const guardedSetupTokenLeaseManager = {
+        async acquire(input) {
+            await assertSandboxLoginEnvironment(input.scope.companyId, input.scope.environmentId, {
+                requireSetupTokenLoginProvider: true,
+            });
+            return setupTokenLeaseManager.acquire(input);
+        },
+        release: (lease) => setupTokenLeaseManager.release(lease),
+        releaseById: (leaseId) => setupTokenLeaseManager.releaseById(leaseId),
+    };
+    const setupTokenLoginService = new SetupTokenSessionService({
+        factory: setupTokenLoginFactory,
+        leases: guardedSetupTokenLeaseManager,
+        store: setupTokenCleanupStore,
+        completeCredential: setupTokenSecretWriter,
+        rateLimiter: setupTokenRateLimiter,
+    });
+    {
+        // Log the startup transport assessment, so an operator can see whether a
+        // forwarded proxy protocol is trusted for the confidential routes (SR-7).
+        const startupAssessment = assessConfidentialStartup(setupTokenConfidentialConfig);
+        logger.info({
+            proxyForwardingEnabled: startupAssessment.proxyForwardingEnabled,
+            reason: startupAssessment.reason,
+            deploymentMode: setupTokenConfidentialConfig.deploymentMode,
+        }, "Setup-token login confidential transport startup assessment");
+    }
+    options.onSetupTokenLoginService?.(setupTokenLoginService);
     const runRedactions = createRunSecretRedactionRegistry(db);
     const heartbeat = heartbeatService(db, {
         pluginWorkerManager: options.pluginWorkerManager,
@@ -143,6 +278,75 @@ export function agentRoutes(db, options = {}) {
     const workspaceOperations = workspaceOperationService(db);
     const instanceSettings = instanceSettingsService(db);
     const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";
+    // The company-scoped adapter login-session service. It runs the device-login
+    // flow in a fresh trusted sandbox and holds the one-time prompt in memory. The
+    // process owns one instance, so the in-memory prompt and the cancellation
+    // controllers persist across requests.
+    const adapterLoginStore = createDbAdapterAuthSessionStore(db);
+    const adapterLoginService = createCodexDeviceLoginService({
+        store: adapterLoginStore,
+        runtime: createProductionLoginSessionRuntime({ db, environmentRuntime }),
+        // 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
+        // active claim, and writes the credential into the company scope. A rejected
+        // or unready credential fails the session and writes nothing.
+        promotion: {
+            async promote(authBytes, context) {
+                // Hold the promotion critical-section lock across the ownership check and
+                // the credential write. The reaper takes the same lock before it reclaims
+                // a stale `promoting` row. So a reclaim never interleaves with a live
+                // write: the reaper either wins the lock first and the ownership check
+                // then reads a reclaimed row and writes nothing, or the write finishes
+                // 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({
+                    authBytes,
+                    companyId: context.companyId,
+                    userInitiated: true,
+                    checkReadiness: (bytes) => checkStagedCredentialReadiness(bytes),
+                    isSoleActiveOwner: async () => {
+                        // The partial unique index allows one active row per company and
+                        // adapter. So a `promoting` row for this session is the sole
+                        // active owner of the company credential slot. The read runs
+                        // inside the lock, so it observes a reaper reclaim that committed
+                        // before this section acquired the lock.
+                        const row = await adapterLoginStore.get(context.sessionId);
+                        return row?.status === "promoting" && row.companyId === context.companyId;
+                    },
+                    log: (line) => {
+                        // The promotion lines carry no token bytes and no raw account id,
+                        // so it is safe to log them with the session identifier.
+                        logger.info({ sessionId: context.sessionId }, line);
+                    },
+                }));
+                // A resolved promotion is not necessarily an accepted promotion. In
+                // particular, a reaper/expiry race can revoke this session's sole
+                // ownership between the service transition and Decision H. Fail closed:
+                // only a credential write or a deliberate safe keep can authenticate.
+                if (outcome === "kept_foreign_identity") {
+                    // The login produced a different account than the one the company
+                    // credential home already holds. The promotion never clobbers an
+                    // occupied home, so this login installed nothing durable, and the
+                    // identity-anchored vend can never select it: a later run keeps the
+                    // existing account. Fail the session, so the operator never sees a
+                    // false `authenticated` for an account the system will not use.
+                    throw new Error("device-login credential promotion rejected: the login is a different account than the one already set for this company; the existing account was kept");
+                }
+                if (outcome !== "promoted" && outcome !== "kept") {
+                    throw new Error(`device-login credential promotion rejected: ${outcome}`);
+                }
+            },
+        },
+        recordActivity: (event) => {
+            // The event carries no URL, no code, no credential, no account identifier,
+            // and no lease identifier, so it is safe to log.
+            logger.info(event, "adapter login session lifecycle");
+        },
+    });
+    // The cancellation controllers for the in-flight login runs this process owns.
+    const adapterLoginAbortControllers = new Map();
     async function assertAgentEnvironmentSelection(companyId, adapterType, environmentId) {
         if (environmentId === undefined || environmentId === null)
             return;
@@ -653,6 +857,113 @@ export function agentRoutes(db, options = {}) {
             return;
         throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
     }
+    // The single owner-authorization helper for the three adapter login routes. It
+    // requires a board actor, company access, and the same configuration
+    // permission as the adapter Test route (`agents:create`). It returns the
+    // immutable owner identifier: the board user that starts, reads, or cancels the
+    // session. The start route persists this identifier; the status and cancel
+    // routes compare it to the session owner and return 404 on a mismatch, so a
+    // non-owner cannot enumerate a session.
+    async function assertCanManageAdapterLogin(req, companyId) {
+        assertBoard(req);
+        assertCompanyAccess(req, companyId);
+        const decision = await access.decide({
+            actor: req.actor,
+            action: "agents:create",
+            resource: { type: "company", companyId },
+        });
+        if (!decision.allowed) {
+            throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
+        }
+        const userId = req.actor.userId;
+        if (!userId) {
+            throw forbidden("A board user identity is required to manage an adapter login session.");
+        }
+        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) {
+            throw badRequest(`Adapter "${type}" does not support a device login.`);
+        }
+    }
+    // The environment-eligibility guard for an adapter login. A device login runs
+    // only in an active sandbox environment. This reuses the shared environment
+    // selection guard, so it rejects a missing, archived (inactive), local, SSH, or
+    // plugin environment the same way the agent configuration routes do.
+    //
+    // The execution environment catalog is instance-scoped, not company-owned. PR
+    // #8375 moved the catalog to one shared instance catalog, so an environment row
+    // carries no single owning company. The shared selection guard therefore checks
+    // only the driver and the status. The company-binding check below then rejects
+    // an environment that binds to other companies. The route caller is already
+    // bound to the path company by `assertCompanyAccess`, and the acquired lease
+    // records that same company, so the login stays attributed to the caller.
+    async function assertSandboxLoginEnvironment(companyId, environmentId, options) {
+        await assertEnvironmentSelectionForCompany(environmentsSvc, companyId, environmentId, {
+            allowedDrivers: ["sandbox"],
+        });
+        // Reject an environment that another company owns. A managed sandbox
+        // environment binds to the companies that the instance provisions it for.
+        // When the environment binds to companies but not the request company, the
+        // environment belongs to another company. A login there runs the process in
+        // a foreign company sandbox, so the guard fails closed. An environment with
+        // no company binding is instance-global and stays open to every member.
+        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",
+            });
+        }
+        // Gate the Claude setup-token login on the provider capability. Only a
+        // sandbox provider that advertises the setup-token login capability
+        // implements the setup-token pseudo-terminal methods. The setup-token start
+        // routes pass this option, so an unsupported provider fails closed here
+        // before the session starts. The lease guard passes it too, so a
+        // reconciliation that rebinds the environment to an unsupported provider
+        // still fails closed before the lease and the pseudo-terminal.
+        if (options?.requireSetupTokenLoginProvider) {
+            await assertSetupTokenLoginProviderCapability(environmentId);
+        }
+    }
+    /**
+     * 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.
+     */
+    async function assertSetupTokenLoginProviderCapability(environmentId) {
+        const environment = await environmentsSvc.getById(environmentId);
+        const config = environment?.config && typeof environment.config === "object"
+            ? environment.config
+            : {};
+        const provider = typeof config.provider === "string" ? config.provider : "";
+        const resolved = provider
+            ? await resolvePluginSandboxProviderDriverByKey({ db, driverKey: provider })
+            : null;
+        if (!resolved?.driver.supportsSetupTokenLogin) {
+            throw unprocessable(SETUP_TOKEN_PROVIDER_UNSUPPORTED, {
+                code: SETUP_TOKEN_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) {
+            return null;
+        }
+        return adapterLoginService.readOwnerSession(sessionId, requestingUserId);
+    }
     async function assertCanReadConfigurations(req, companyId) {
         // Reading agent configurations, skills, and config revisions is a
         // read-only operation available to any board (human) member of the
@@ -812,6 +1123,35 @@ export function agentRoutes(db, options = {}) {
         }
         return adapterType;
     }
+    /**
+     * Adapter validation for the paths that CHOOSE a harness for a new agent
+     * (hire + create), as opposed to the paths that operate on an existing one.
+     *
+     * A disabled adapter is one this instance cannot run — most often because a
+     * declarative registry (PAPERCLIP_ADAPTERS) curated it out, which
+     * reconcileAdapterAvailability turns into a disabled type at boot. Registered
+     * but disabled still passes assertKnownAdapterType, so an agent could be
+     * created on it and then fail EVERY run at lease time with
+     * `Adapter "..." is not in the configured adapter registry` — an error that
+     * arrives minutes later, in a run log, with no way back to the choice that
+     * caused it. Refuse at selection time instead, and name what can be chosen.
+     *
+     * Existing agents on a now-disabled adapter are deliberately untouched
+     * (listEnabledServerAdapters documents the same rule: hidden from selection,
+     * still functional for agents that already use them).
+     */
+    function assertSelectableAdapterType(type) {
+        const adapterType = assertKnownAdapterType(type);
+        const disabled = new Set(getDisabledAdapterTypes());
+        if (!disabled.has(adapterType))
+            return adapterType;
+        const available = listServerAdapters()
+            .map((a) => a.type)
+            .filter((t) => !disabled.has(t))
+            .sort();
+        throw unprocessable(`Adapter "${adapterType}" is not available on this instance. `
+            + `Available adapters: ${available.length > 0 ? available.join(", ") : "(none configured)"}`);
+    }
     async function assertAgentDefaultEnvironmentSelection(companyId, environmentId, options) {
         if (environmentId === undefined || environmentId === null)
             return;
@@ -1598,6 +1938,99 @@ export function agentRoutes(db, options = {}) {
             await release(releaseStatus);
         }
     });
+    // Start a company-scoped adapter device login. The create form has no agent
+    // identifier, so the route keys on the company and the adapter. The owner
+    // helper requires a board actor with the configuration permission, and it
+    // returns the immutable owner identifier that the service persists on the row.
+    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);
+        const controller = new AbortController();
+        let result;
+        try {
+            result = await adapterLoginService.start({
+                companyId,
+                environmentId,
+                adapterType: type,
+                startedByUserId,
+                ttlSeconds,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            // A second active login for the same company and adapter loses the
+            // credential slot. Map the service conflict to a 409 response.
+            if (error instanceof AdapterAuthSessionConflictError) {
+                throw conflict(error.message);
+            }
+            throw error;
+        }
+        // Keep the controller so the cancel route can abort the in-flight run.
+        // Drop it when the run ends. The completion runs the terminal handling in
+        // the background; the response returns the initial session at once.
+        const startedSessionId = result.session.sessionId;
+        adapterLoginAbortControllers.set(startedSessionId, controller);
+        void result.completed
+            .catch(() => { })
+            .finally(() => {
+            adapterLoginAbortControllers.delete(startedSessionId);
+        });
+        res.status(201).json(result.session);
+    });
+    // Read a login session. The owner receives the status and the one-time prompt.
+    // A non-owner or a cross-company caller receives a 404.
+    router.get("/companies/:companyId/adapters/:type/login-sessions/:sessionId", async (req, res) => {
+        const companyId = req.params.companyId;
+        const type = req.params.type;
+        const sessionId = req.params.sessionId;
+        const ownerUserId = await assertCanManageAdapterLogin(req, companyId);
+        assertCodexLoginAdapter(type);
+        const owner = await readOwnerLoginSession(companyId, type, sessionId, ownerUserId);
+        if (!owner) {
+            res.status(404).json({ error: "Adapter login session not found" });
+            return;
+        }
+        res.json(owner);
+    });
+    // Cancel a login session. The owner aborts the in-flight run. A non-owner or a
+    // cross-company caller receives a 404.
+    router.post("/companies/:companyId/adapters/:type/login-sessions/:sessionId/cancel", async (req, res) => {
+        const companyId = req.params.companyId;
+        const type = req.params.type;
+        const sessionId = req.params.sessionId;
+        const ownerUserId = await assertCanManageAdapterLogin(req, companyId);
+        assertCodexLoginAdapter(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);
+        if (!owner) {
+            res.status(404).json({ error: "Adapter login session not found" });
+            return;
+        }
+        // Durably release the company slot. The durable write terminates the row
+        // 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);
+        // 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.
+        adapterLoginAbortControllers.get(sessionId)?.abort();
+        res.json(cancelled ?? owner);
+    });
     router.get("/agents/:id/skills", async (req, res) => {
         const id = req.params.id;
         const agent = await svc.getById(id);
@@ -2041,8 +2474,15 @@ export function agentRoutes(db, options = {}) {
         const companyId = req.params.companyId;
         await assertCanCreateAgentsForCompany(req, companyId);
         const sourceIssueIds = parseSourceIssueIds(req.body);
-        const { desiredSkills: requestedDesiredSkills, instructionsBundle, sourceIssueId: _sourceIssueId, sourceIssueIds: _sourceIssueIds, ...hireInput } = req.body;
-        hireInput.adapterType = assertKnownAdapterType(hireInput.adapterType);
+        const { desiredSkills: requestedDesiredSkills, instructionsBundle, sourceIssueId: _sourceIssueId, sourceIssueIds: _sourceIssueIds, 
+        // The stored-session claim is not an agent column. The server derives the
+        // owner from the authenticated actor and consumes the claim in the create
+        // transaction, so it never reaches the insert values.
+        storedSessionId: hireStoredSessionId, 
+        // The apply-existing flag is not an agent column. The server binds the
+        // fixed reference to the owner stored value with no login round trip.
+        applyStoredClaudeLogin: hireApplyStoredClaudeLogin, ...hireInput } = req.body;
+        hireInput.adapterType = assertSelectableAdapterType(hireInput.adapterType);
         const rawHireAdapterConfig = (hireInput.adapterConfig ?? {});
         assertNoNewAgentLegacyPromptTemplate(hireInput.adapterType, rawHireAdapterConfig);
         assertNoAgentAdapterConfigMutation(req, rawHireAdapterConfig);
@@ -2078,6 +2518,14 @@ export function agentRoutes(db, options = {}) {
             status,
             spentMonthlyCents: 0,
             lastHeartbeatAt: null,
+        }, {
+            claudeLogin: {
+                storedSessionId: hireStoredSessionId ?? null,
+                ownerUserId: req.actor.type === "agent" ? null : (req.actor.userId ?? null),
+                // The apply-existing path runs only for a user actor. The owner comes
+                // from the actor, so an agent actor never reaches the no-claim bind.
+                applyExistingWithoutClaim: req.actor.type !== "agent" && hireApplyStoredClaudeLogin === true,
+            },
         });
         const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent, instructionsBundle);
         let approval = null;
@@ -2183,8 +2631,15 @@ export function agentRoutes(db, options = {}) {
         if (company.requireBoardApprovalForNewAgents) {
             throw conflict("Direct agent creation requires board approval. Use POST /api/companies/:companyId/agent-hires to create a pending hire approval.");
         }
-        const { desiredSkills: requestedDesiredSkills, instructionsBundle, ...createInput } = req.body;
-        createInput.adapterType = assertKnownAdapterType(createInput.adapterType);
+        const { desiredSkills: requestedDesiredSkills, instructionsBundle, 
+        // The stored-session claim is not an agent column. The server derives the
+        // owner from the authenticated actor and consumes the claim in the create
+        // transaction, so it never reaches the insert values.
+        storedSessionId: createStoredSessionId, 
+        // The apply-existing flag is not an agent column. The server binds the
+        // fixed reference to the owner stored value with no login round trip.
+        applyStoredClaudeLogin: createApplyStoredClaudeLogin, ...createInput } = req.body;
+        createInput.adapterType = assertSelectableAdapterType(createInput.adapterType);
         const rawCreateAdapterConfig = (createInput.adapterConfig ?? {});
         assertNoNewAgentLegacyPromptTemplate(createInput.adapterType, rawCreateAdapterConfig);
         assertNoAgentAdapterConfigMutation(req, rawCreateAdapterConfig);
@@ -2211,6 +2666,14 @@ export function agentRoutes(db, options = {}) {
             status: "idle",
             spentMonthlyCents: 0,
             lastHeartbeatAt: null,
+        }, {
+            claudeLogin: {
+                storedSessionId: createStoredSessionId ?? null,
+                ownerUserId: req.actor.type === "agent" ? null : (req.actor.userId ?? null),
+                // The apply-existing path runs only for a user actor. The owner comes
+                // from the actor, so an agent actor never reaches the no-claim bind.
+                applyExistingWithoutClaim: req.actor.type !== "agent" && createApplyStoredClaudeLogin === true,
+            },
         });
         const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent, instructionsBundle);
         const actor = getActorInfo(req);
@@ -2491,6 +2954,11 @@ export function agentRoutes(db, options = {}) {
         const patchData = { ...req.body };
         const replaceAdapterConfig = patchData.replaceAdapterConfig === true;
         delete patchData.replaceAdapterConfig;
+        // The apply-existing flag is not an agent column. The server binds the fixed
+        // reference to the owner stored value with no login round trip. Remove it
+        // from the patch so it never reaches the update values.
+        const applyStoredClaudeLogin = patchData.applyStoredClaudeLogin === true;
+        delete patchData.applyStoredClaudeLogin;
         if (hasOwn(patchData, "adapterConfig")) {
             const adapterConfig = asRecord(patchData.adapterConfig);
             if (!adapterConfig) {
@@ -2504,8 +2972,15 @@ export function agentRoutes(db, options = {}) {
             }
             patchData.adapterConfig = adapterConfig;
         }
+        // Switching an existing agent ONTO another adapter is a new selection, so
+        // it gets the selectable check; keeping the agent's current adapter (even
+        // one since disabled) stays allowed, so a disabled harness does not make an
+        // existing agent uneditable.
         const requestedAdapterType = hasOwn(patchData, "adapterType")
-            ? assertKnownAdapterType(patchData.adapterType)
+            ? (() => {
+                const next = assertKnownAdapterType(patchData.adapterType);
+                return next === existing.adapterType ? next : assertSelectableAdapterType(next);
+            })()
             : existing.adapterType;
         let requestedRuntimeConfig = null;
         if (hasOwn(patchData, "runtimeConfig")) {
@@ -2582,6 +3057,12 @@ export function agentRoutes(db, options = {}) {
                 createdByUserId: actor.actorType === "user" ? actor.actorId : null,
                 source: "patch",
             },
+            claudeLogin: {
+                ownerUserId: req.actor.type === "agent" ? null : (req.actor.userId ?? null),
+                // The apply-existing path runs only for a user actor. The owner comes
+                // from the actor, so an agent actor never reaches the no-claim bind.
+                applyExistingWithoutClaim: req.actor.type !== "agent" && applyStoredClaudeLogin,
+            },
         });
         if (!agent) {
             res.status(404).json({ error: "Agent not found" });
@@ -3032,6 +3513,392 @@ export function agentRoutes(db, options = {}) {
         });
         res.json(result);
     });
+    // --- Setup-token login session routes --------------------------------------
+    //
+    // The routes give the UI operations against one live login session. Every
+    // operation verifies the company and owner user through the session scope. A
+    // missing session and a cross-scope session both return the same 404. The
+    // confidential responses pass through the transport assessment and set
+    // `Cache-Control: no-store`. The routes write no prompt, code, token, or raw
+    // process chunk to a log or an activity detail, and they return fixed error
+    // text only.
+    //
+    // Operator requirement (SR-7): to serve the confidential responses behind a
+    // TLS-terminating reverse proxy, set `CLAUDE_LOGIN_TRUSTED_PROXIES` to the
+    // explicit proxy IP or CIDR allowlist — or, on a managed platform whose edge
+    // always terminates TLS and whose proxy peer addresses cannot be allowlisted,
+    // declare `CLAUDE_LOGIN_EDGE_TLS_TERMINATED=true`. The global `TRUST_PROXY`
+    // setting, including `TRUST_PROXY=true` and a hop-count value, does not
+    // satisfy the guard. A direct TLS request is always valid; a non-TLS request
+    // is valid only on a loopback peer in the `local_trusted` deployment mode.
+    //
+    // Each route below writes its full path as a plain string literal. The static
+    // OpenAPI coverage test reads the route paths from the source text; it does
+    // not evaluate a template variable. A shared base constant would leave the
+    // test with an unresolved path, so the routes repeat the base path instead.
+    /**
+     * Derives the immutable owner of a setup-token login session from the actor.
+     * Only a board user owns a login session. It returns the owner id, or it
+     * throws a forbidden error. The owner is never a client field; it comes only
+     * from the authenticated actor.
+     */
+    const deriveSetupTokenOwnerUserId = (req) => {
+        const actor = getActorInfo(req);
+        if (actor.actorType !== "user") {
+            throw forbidden("A user must own a setup-token login session.");
+        }
+        return actor.actorId;
+    };
+    /**
+     * Read-access gate for the company-scoped setup-token session routes. It runs
+     * before a route resolves a session. The session id is an opaque secret-bearing
+     * reference, so a cross-company reference must fail closed like a missing
+     * session. This gate returns the same fixed not-found error for a cross-company
+     * reference by an authenticated non-member as for a missing session, so the
+     * route is not a company-membership oracle. It keeps the not-found equivalence
+     * the session lookups use.
+     *
+     * The gate keeps the actor rules unchanged. It throws 401 for an unauthenticated
+     * caller and 403 for a non-user actor through the owner derivation. For an
+     * authorized member it runs the full `assertCompanyAccess` write-path checks and
+     * returns the owner user id. For a non-member it sends the fixed 404 and returns
+     * null; the route must stop.
+     */
+    const resolveCompanySessionOwner = (req, companyId, res) => {
+        assertAuthenticated(req);
+        const ownerUserId = deriveSetupTokenOwnerUserId(req);
+        if (!hasCompanyAccess(req, companyId)) {
+            res.setHeader("Cache-Control", "no-store");
+            res.status(404).json({ error: SETUP_TOKEN_SESSION_NOT_FOUND });
+            return null;
+        }
+        assertCompanyAccess(req, companyId);
+        return ownerUserId;
+    };
+    /**
+     * Assesses the setup-token confidential transport. The product
+     * owner set a non-negotiable requirement: do not force TLS. Many users run
+     * Paperclip over plain HTTP on a home server or a Tailscale tailnet. So the
+     * route does not block a non-confidential transport. It returns a non-blocking
+     * advisory instead, and the route attaches it to the confidential response.
+     * The client shows a visible disclaimer and lets the login proceed. The
+     * function reads the raw socket TLS bit and the immediate peer address, so the
+     * global `trust proxy` setting cannot change the result. It returns null when
+     * the transport is confidential (direct TLS, a local-trusted loopback, or an
+     * allowlisted TLS proxy), so a confidential response shows no disclaimer.
+     */
+    const assessSetupTokenTransport = (req) => {
+        const socket = req.socket;
+        const forwardedProto = req.headers["x-forwarded-proto"];
+        const decision = evaluateConfidentialTransport(setupTokenConfidentialConfig, {
+            socketEncrypted: socket?.encrypted === true,
+            remoteAddress: socket?.remoteAddress,
+            forwardedProto: Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto,
+        });
+        return decision.allowed ? null : { code: SETUP_TOKEN_TRANSPORT_ADVISORY_CODE };
+    };
+    const sendSetupTokenError = (res, err) => {
+        if (err instanceof SetupTokenSessionError) {
+            res.status(err.status).json({ error: err.message });
+            return;
+        }
+        throw err;
+    };
+    // --- Company-and-environment setup-token login routes ----------------------
+    //
+    // These routes serve the agentless Claude login. The scope binds one login to
+    // one company, one owner user, one adapter, and one environment. The scope
+    // carries no agent id, so a hire flow starts one login before an agent exists.
+    //
+    // Object-level authorization: every action derives the owner from
+    // the authenticated actor, fixes the adapter to `claude_local`, and resolves
+    // the environment server-side. The lookup scopes by the immutable tuple
+    // company, owner, adapter, environment, and session. A foreign session returns
+    // the same not-found error as a missing session, so a caller cannot enumerate
+    // a session across a company, an owner, an adapter, or an environment.
+    //
+    // Each route writes its full path as a plain string literal, so the static
+    // OpenAPI coverage test can read the path from the source text.
+    // The company-and-environment login serves only the Claude adapter.
+    const CLAUDE_SETUP_TOKEN_ADAPTER_TYPE = "claude_local";
+    // Maps the internal session state to the public login status. The public union
+    // carries no server-only state, so the route never returns the internal
+    // `submitting` or `stored` state to a client.
+    const toClaudeLoginStatus = (state) => {
+        switch (state) {
+            case "starting":
+                return "starting";
+            case "awaiting_code":
+            case "submitting":
+            case "stored":
+                return "waiting_for_user";
+            case "completed":
+                return "authenticated";
+            case "failed":
+                return "failed";
+            case "timed_out":
+                return "timed_out";
+            case "cancelled":
+                return "cancelled";
+        }
+    };
+    // Builds the fixed, non-secret failure for a terminal failure state. A live or
+    // a completed session has no failure. The failure carries a stable reason and
+    // no secret detail.
+    const toClaudeLoginFailure = (state) => {
+        switch (state) {
+            case "failed":
+                return { reason: "failed", message: null };
+            case "timed_out":
+                return { reason: "timed_out", message: null };
+            case "cancelled":
+                return { reason: "cancelled", message: null };
+            default:
+                return null;
+        }
+    };
+    // The public login-session response. It carries no prompt and no secret.
+    const toClaudePublicResponse = (descriptor) => ({
+        sessionId: descriptor.sessionId,
+        environmentId: descriptor.environmentId,
+        status: toClaudeLoginStatus(descriptor.state),
+        expiresAt: new Date(descriptor.deadline).toISOString(),
+        failure: toClaudeLoginFailure(descriptor.state),
+    });
+    // The company-and-environment login key the non-start routes derive. The route
+    // path gives the company, the actor gives the owner, and the route fixes the
+    // adapter. The service matches this key and the agentless marker.
+    const companySetupTokenKey = (companyId, ownerUserId) => ({
+        companyId,
+        ownerUserId,
+        adapterType: CLAUDE_SETUP_TOKEN_ADAPTER_TYPE,
+    });
+    // The stored Claude OAuth token status read. It returns
+    // only the secret id and the latest version of the owner value; it returns no
+    // token. The client reads the version, applies the stored token first, and
+    // captures the version for a later confirmed overwrite. The route derives the
+    // owner only from the authenticated actor and reads the fixed Claude
+    // definition; it accepts no owner, no definition, and no secret id as input.
+    //
+    // The route returns the same fixed 404 for a missing owner value as the
+    // company gate returns for a non-member, so it discloses no existence
+    // distinction across owners or companies. It sets `Cache-Control: no-store`,
+    // so no cache holds the metadata.
+    router.get("/companies/:companyId/claude-oauth-token-status", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        const status = await secretsSvc.readClaudeOAuthUserSecretStatus(companyId, ownerUserId);
+        if (!status) {
+            // A missing owner value returns the same fixed not-found as the non-member
+            // gate, so a member without a value and a non-member look the same.
+            res.status(404).json({ error: SETUP_TOKEN_SESSION_NOT_FOUND });
+            return;
+        }
+        const body = status;
+        res.json(body);
+    });
+    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,
+        });
+        const scope = {
+            companyId,
+            ownerUserId,
+            targetAgentId: null,
+            adapterType,
+            environmentId,
+            confirmedOverwrite,
+        };
+        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.
+            const body = {
+                ...toClaudePublicResponse(descriptor),
+                panelMode: "submitted_browser_code",
+                prompt: null,
+            };
+            res.status(201).json(body);
+        }
+        catch (err) {
+            sendSetupTokenError(res, err);
+        }
+    });
+    router.get("/companies/:companyId/setup-token-login-sessions/:sessionId", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        try {
+            const sessionId = req.params.sessionId;
+            const scope = setupTokenLoginService.resolveCompanyScope(sessionId, companySetupTokenKey(companyId, ownerUserId));
+            const descriptor = setupTokenLoginService.describeOwned(sessionId, scope);
+            // The status response is public. It carries no prompt and no secret.
+            res.json(toClaudePublicResponse(descriptor));
+        }
+        catch (err) {
+            sendSetupTokenError(res, err);
+        }
+    });
+    router.get("/companies/:companyId/setup-token-login-sessions/:sessionId/prompt", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        // The full login URL is a confidential response. The route
+        // does not force TLS. It attaches a non-blocking advisory instead.
+        const transportAdvisory = assessSetupTokenTransport(req);
+        try {
+            const sessionId = req.params.sessionId;
+            const scope = setupTokenLoginService.resolveCompanyScope(sessionId, companySetupTokenKey(companyId, ownerUserId));
+            const descriptor = setupTokenLoginService.describeOwned(sessionId, scope);
+            if (!descriptor.loginUrl) {
+                // The prompt has not surfaced yet. Return the same not-found error as a
+                // missing or a foreign session, so the route never confirms the session
+                // exists before the URL is ready.
+                res.status(404).json({ error: SETUP_TOKEN_SESSION_NOT_FOUND });
+                return;
+            }
+            // The full login URL rides only in this authorized owner response.
+            const body = {
+                authorizationUrl: descriptor.loginUrl,
+                transportAdvisory,
+            };
+            res.json(body);
+        }
+        catch (err) {
+            sendSetupTokenError(res, err);
+        }
+    });
+    router.post("/companies/:companyId/setup-token-login-sessions/:sessionId/code", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        // The browser code is the confidential OAuth authorization
+        // secret. The route does not force TLS. It attaches a non-blocking advisory
+        // to the response instead, so the client can show a disclaimer.
+        const transportAdvisory = assessSetupTokenTransport(req);
+        // Parse the request with the shared strict validator before the route forwards
+        // the code to the live process. `.strict()` rejects an unknown field, and the
+        // grammar rejects an empty, an oversized, or a control-byte code. The route
+        // echoes no input; it returns fixed error text only.
+        const parsed = submitBrowserCodeRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: "A valid browser code is required." });
+            return;
+        }
+        try {
+            const sessionId = req.params.sessionId;
+            const scope = setupTokenLoginService.resolveCompanyScope(sessionId, companySetupTokenKey(companyId, ownerUserId));
+            setupTokenLoginService.submitCode(sessionId, scope, parsed.data.browserCode);
+            const descriptor = setupTokenLoginService.describeOwned(sessionId, scope);
+            const body = {
+                ...toClaudePublicResponse(descriptor),
+                transportAdvisory,
+            };
+            res.json(body);
+        }
+        catch (err) {
+            sendSetupTokenError(res, err);
+        }
+    });
+    router.post("/companies/:companyId/setup-token-login-sessions/:sessionId/completion", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        try {
+            const sessionId = req.params.sessionId;
+            const scope = setupTokenLoginService.resolveCompanyScope(sessionId, companySetupTokenKey(companyId, ownerUserId));
+            // The service returns the non-secret `storedSessionId` claim from a
+            // completed session whose owner-bound secret write succeeded. The response
+            // carries no token.
+            const result = setupTokenLoginService.completeSession(sessionId, scope);
+            const body = { storedSessionId: result.storedSessionId };
+            res.json(body);
+        }
+        catch (err) {
+            sendSetupTokenError(res, err);
+        }
+    });
+    router.post("/companies/:companyId/setup-token-login-sessions/:sessionId/cancel", async (req, res) => {
+        const companyId = req.params.companyId;
+        const ownerUserId = resolveCompanySessionOwner(req, companyId, res);
+        if (ownerUserId === null)
+            return;
+        res.setHeader("Cache-Control", "no-store");
+        const sessionId = req.params.sessionId;
+        try {
+            const scope = setupTokenLoginService.resolveCompanyScope(sessionId, companySetupTokenKey(companyId, ownerUserId));
+            await setupTokenLoginService.cancel(sessionId, scope);
+            res.status(200).json({});
+        }
+        catch (err) {
+            // Cancel is idempotent. The service removes a session when it reaches a
+            // terminal state, so a repeat cancel, a cancel after a timeout, or a
+            // cancel of an unknown session finds no record and throws the fixed
+            // not-found error. Return the same success as an active cancel, so the
+            // client stops the poll and returns to its start state.
+            //
+            // This keeps the not-found uniform. The 200 response is identical
+            // for a missing session, an already-terminal session, and a foreign
+            // session, so the route never confirms a session exists and cancels
+            // nothing for a foreign id. A non-member still fails closed with a 404 at
+            // the company-access gate above, before this handler runs. A non-404
+            // error still surfaces.
+            if (err instanceof SetupTokenSessionError && err.status === 404) {
+                res.status(200).json({});
+                return;
+            }
+            sendSetupTokenError(res, err);
+        }
+    });
     router.get("/companies/:companyId/heartbeat-runs", async (req, res) => {
         const companyId = req.params.companyId;
         assertCompanyAccess(req, companyId);