@straiffi/archon 1.1.2 → 1.2.0

package/dist/server/index.js

@@ -7,8 +7,9 @@ import { randomUUID } from 'crypto';
 import cors from 'cors';
 import { adjectives, animals, uniqueNamesGenerator } from 'unique-names-generator';
 import db from './db.js';
-import { createChatSession, deleteChatSession, getChatSession, listChatSessions, updateChatSessionMode } from './lib/chats.js';
-import { doesChatSessionTargetMatchProjectTarget, resolveChatSessionTarget } from './lib/chatTargets.js';
+import { deleteChatSession, getChatSession, listChatSessions, updateChatSessionMode } from './lib/chats.js';
+import { createProjectChatSession, resolveChatMode, resolveChatTool, stopProjectChatSessionResponse, submitProjectChatSessionMessage, } from './lib/chatOperations.js';
+import { resolveChatSessionTarget } from './lib/chatTargets.js';
 import { createChatMessage, getChatMessage, updateChatMessageContent } from './lib/chatMessages.js';
 import { attachChatTicketProposalsToMessageContent } from './lib/chatTicketProposals.js';
 import { createCorsOriginResolver, parseCorsOrigins } from './lib/cors.js';
@@ -16,12 +17,15 @@ import { branchExistsLocally, commitGitChanges, createWorktreeAsync, deleteWorkt
 import config from './lib/config.js';
 import { autoConfigProject, ProjectAutoConfigError } from './lib/projectAutoConfig.js';
 import { browseRepoPath } from './lib/directoryPicker.js';
-import { isBuildAgentRunning, refreshChatSessionUsageSnapshot, stopAllBuildAgents, stopBuildAgent, stopChatAgent } from './lib/agent.js';
+import { resolveDesktopServerHost } from './lib/desktopServerHost.js';
+import { emitMobileRealtime, getMobileAccessStatus, regenerateMobilePairingChallenge, revokeMobileSession, startMobileAccess, stopMobileAccess, } from './lib/mobileAccess.js';
+import { validateDesktopMobileAccessRequest } from './lib/mobileAccessSecurity.js';
+import { refreshChatSessionUsageSnapshot, stopAllBuildAgents } from './lib/agent.js';
 import { runLightweightPrompt } from './lib/lightweightPrompt.js';
 import { startBuildChain, stopBuildChain } from './lib/buildChains.js';
-import { enqueueBundledBuild, getDependencyOrderedBundleTicketIds, hasActiveSequenceForBundle, removeTicketFromBuildSequence, stopAllActiveBuildSequences, } from './lib/buildSequences.js';
+import { enqueueBundledBuild, getDependencyOrderedBundleTicketIds, removeTicketFromBuildSequence, stopAllActiveBuildSequences, } from './lib/buildSequences.js';
 import { prepareTicketForBuild } from './lib/buildFlow.js';
-import { getBundlePlanMutationBlockerById, isBundleBuildBlocked, shouldBlockPlanForBundleMutationById, } from './lib/bundleActivity.js';
+import { getBundlePlanMutationBlockerById, shouldBlockPlanForBundleMutationById, } from './lib/bundleActivity.js';
 import { getDiscoveredModels, normalizeModelId } from './lib/models.js';
 import { acceptProjectMemorySuggestion, applyProjectMemorySuggestionToDecision, archiveProjectConvention, archiveProjectDecision, createProjectConvention, createProjectDecision, dismissProjectMemorySuggestion, getProjectMemoryById, getProjectMemorySuggestionById, isProjectMemoryEnabled, listProjectConventions, listLatestSuccessfulProjectContextArtifacts, listProjectDecisions, listProjectMemories, listProjectMemorySuggestions, restoreProjectConvention, restoreProjectDecision, serializeProjectMemoryFromConventionValue, serializeProjectMemoryFromDecisionValue, serializeProjectMemoryFromSuggestionValue, supersedeProjectDecision, updateProjectConvention, updateProjectDecision, validateProjectConventionPayload, validateProjectDecisionPayload, } from './lib/projectMemory.js';
 import { selectRelevantProjectMemory } from './lib/projectMemoryPrompt.js';
@@ -39,17 +43,19 @@ import { importJiraIssue, JiraApiError, validateJiraConnection } from './lib/int
 import { JiraPlanningReferenceError, resolveJiraPlanningDescription } from './lib/integrations/planning.js';
 import { getBundlePullRequestRecord, hasOpenBundlePullRequest, serializeBundlePullRequest, shouldSyncBundlePullRequest, upsertBundlePullRequest, } from './lib/bundlePullRequests.js';
 import { countInboundProjectLinks, getEffectiveProject, getProjectById, getProjectTicketStats, hasProjectRunIde, listProjects, replaceProjectLinks, serializeProject, updateProjectActiveTarget, validateProjectPayload, validateRepoPath, } from './lib/projects.js';
-import { getActiveRunStatus, getActiveRunStatusForProject, getPreviewStatusForProject, hasRunConfig, isRunning, openIde, openTicketIdeInWorkspace, resolveProjectRunContextKey, runProject, runSetupCommandsInWorkspace, runTicketInWorkspace, stopAllTickets, stopProjectRun, stopTicket } from './lib/run.js';
+import { getActiveRunStatus, getActiveRunStatusForProject, getPreviewStatusForProject, hasRunConfig, isRunning, openIde, openTicketIdeInWorkspace, resolveProjectRunContextKey, runSetupCommandsInWorkspace, runTicketInWorkspace, stopAllTickets, stopTicket } from './lib/run.js';
 import { clearAllTestSessions, createTestSession, deleteTestSession, discoverTestsForSession, doesTestFileExistForSession, findProjectTestCommand, getTestSession, isTestSelectionSupported, startTestSessionRun, stopTestSessionRun } from './lib/testSessions.js';
+import { getBundleBuildBlockerResponse, shouldStartBundleBuildNow, transitionTicketState, } from './lib/ticketWorkflowOperations.js';
+import { submitPlanTicketFollowUp, submitTicketFollowUp, } from './lib/ticketFollowUpOperations.js';
+import { canUseBuildControls, formatActiveRunConflict, getTicketRunReadinessError, resumeBuildTicketRun, runProjectTarget, runTicketRun, stopBuildTicketRun, stopProjectTargetRun, stopTicketRun, } from './lib/ticketRunOperations.js';
+import { isTicketAgentSettingsPayload, updateTicketAgentSettings, } from './lib/ticketSettingsOperations.js';
 import { getActiveBundleStageChangeHead, undoTicketStage } from './lib/ticketUndo.js';
 import { closeAllTerminalSessions, createProjectTerminalSession, createTerminalSessionForWorkspace, destroyTerminalSessionById, registerTerminalSocketHandlers, } from './lib/terminal.js';
 import { countBundleTickets, createTicketRecord, createBundle, deleteBundle, ensureProjectRootBundle, autoParkTicketIfStale, clearAutoParkDismissalIfNeeded, assignTicketDoneOrder, assignTicketLaneOrder, getBundle, getBundleByName, getBundleByBranch, getBundleRepresentativeTicketContext, isProjectRootBundle, getTicket, isBundledTicket, listTicketsInRunContext, listBundles, listBoardTicketEnrichment, listTickets, resolveTicketBranch, resolveTicketTool, } from './lib/tickets.js';
 import { createTicketMessage, upsertTicketDescriptionMessage } from './lib/ticketMessages.js';
 import { createTicketDependency, deleteTicketDependenciesForTicket, deleteTicketDependency, getTicketDependency, isTicketRunSetupReady, listTicketDependencies, validateCreateTicketDependency, } from './lib/ticketDependencies.js';
-import { resumeBuild, startBuild } from './workers/build.js';
-import { startChatSessionTurn } from './workers/chat.js';
+import { startBuild } from './workers/build.js';
 import { startFollowUp } from './workers/followUp.js';
-import { startPlanFollowUp } from './workers/planFollowUp.js';
 import { expandPlanningTicketOutline, generatePlanningTicketOutline, generatePlanText, IMPLEMENTATION_READY_DESCRIPTION_SECTION_HEADINGS, prepareLinkedPlanningResearch, startPlan, } from './workers/plan.js';
 import { startReview } from './workers/review.js';
 class HttpError extends Error {
@@ -151,34 +157,9 @@ const getParkTicketError = (ticket) => {
     }
     return 'Only build and review tickets can be parked';
 };
-const getBundleBuildBlockerError = (kind) => {
-    if (kind === 'review') {
-        return 'A review is currently active in this bundle. Finish or stop it before starting a new build.';
-    }
-    return 'A follow-up job is currently modifying this bundle. Finish it before starting a new build.';
-};
 const getBundlePlanBlockerError = () => {
     return 'AI planning is blocked because this bundle worktree is currently being modified.';
 };
-const isBuildBlockerKind = (kind) => {
-    return kind === 'review' || kind === 'build_follow_up' || kind === 'review_follow_up';
-};
-const getBundleBuildBlockerResponse = (ticket) => {
-    const blocker = isBundleBuildBlocked(ticket);
-    if (!blocker || !isBuildBlockerKind(blocker.kind)) {
-        return null;
-    }
-    return {
-        error: getBundleBuildBlockerError(blocker.kind),
-        blocker_ticket_id: blocker.ticketId,
-    };
-};
-const shouldStartBundleBuildNow = (ticket) => {
-    if (!ticket.project_id || !ticket.worktree_bundle_id) {
-        return true;
-    }
-    return !hasActiveSequenceForBundle(ticket.project_id, ticket.worktree_bundle_id);
-};
 const deleteTicketRecord = async (ticket) => {
     if (ticket.agent_status === 'running') {
         return { ok: false, status: 409, error: 'Cannot delete a ticket while the agent is running' };
@@ -275,6 +256,12 @@ const httpServer = createServer(app);
 const io = new Server(httpServer, {
     cors: { origin: CORS_ORIGIN_RESOLVER },
 });
+const emitDesktopRealtime = io.emit.bind(io);
+io.emit = ((event, ...args) => {
+    const result = emitDesktopRealtime(event, ...args);
+    emitMobileRealtime(event, args[0]);
+    return result;
+});
 app.use(cors({ origin: CORS_ORIGIN_RESOLVER }));
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
 const resolveRequestedSkills = (value) => normalizeSkillNames(value);
@@ -517,19 +504,6 @@ const asProjectPayload = (body) => {
 const isWorktreeReady = (branch, project) => {
     return existsSync(resolveWorktreePath(branch, project));
 };
-const getTicketRunReadinessError = (ticket, project) => {
-    const branch = resolveTicketBranch(ticket);
-    if (!branch || !isWorktreeReady(branch, project)) {
-        return 'Worktree not ready yet';
-    }
-    if (isTicketRunSetupReady(ticket)) {
-        return null;
-    }
-    if (ticket.run_setup_status === 'preparing') {
-        return 'Worktree setup is still running. Try again in a moment.';
-    }
-    return 'Worktree setup has not finished yet.';
-};
 // Any ticket left in 'running' on startup had its job lost when the server stopped
 db.prepare("UPDATE tickets SET agent_status = 'error' WHERE agent_status = 'running'").run();
 stopAllActiveBuildSequences();
@@ -573,15 +547,6 @@ const getProjectChatSession = (projectId, chatSessionId) => {
     }
     return chatSession;
 };
-const resolveChatMode = (value) => {
-    return value === 'plan' ? 'plan' : 'build';
-};
-const resolveChatTool = (value) => {
-    if (value === 'claude') {
-        return 'claude';
-    }
-    return 'opencode';
-};
 const resolveTicketDiffWorkspace = (ticket) => {
     const project = getEffectiveProject(ticket);
     if (!project) {
@@ -1877,9 +1842,6 @@ const buildChatTicketCreationResultMessage = ({ createdTickets, createdDependenc
         dependencyLine,
     ].filter(Boolean).join('\n\n');
 };
-const canUseBuildControls = (ticket) => {
-    return ticket.state === 'build' || (ticket.state === 'review' && ticket.review_follow_up_active === true);
-};
 const emitRunStateForContext = (ticket, isRunningValue) => {
     const relatedTickets = listTicketsInRunContext(ticket);
     if (relatedTickets.length === 0) {
@@ -1890,38 +1852,63 @@ const emitRunStateForContext = (ticket, isRunningValue) => {
         io.emit('ticket:updated', { ...relatedTicket, is_running: isRunningValue });
     }
 };
-const formatActiveRunConflict = (projectId) => {
-    const activeRun = getActiveRunStatusForProject(projectId);
-    if (!activeRun) {
-        return null;
-    }
-    if (activeRun.kind === 'project') {
-        const activeProject = getProjectById(activeRun.project_id);
-        const activeTargetBundle = activeRun.target_kind === 'bundle' && activeRun.target_bundle_id
-            ? getBundle(activeRun.target_bundle_id, activeRun.project_id)
-            : null;
-        return {
-            active_project_id: activeRun.project_id,
-            error: activeProject
-                ? activeTargetBundle
-                    ? `Bundle target run for "${activeProject.name}" (${activeTargetBundle.name}) is already running. Stop it before starting another run.`
-                    : `Repo root run for "${activeProject.name}" is already running. Stop it before starting another run.`
-                : activeTargetBundle
-                    ? 'A bundle target run is already running. Stop it before starting another run.'
-                    : 'A repo root run is already running. Stop it before starting another run.',
-        };
+app.use(express.json({ limit: '5mb' }));
+const requireDesktopMobileAccessRequest = (req, res) => {
+    const rejectionReason = validateDesktopMobileAccessRequest(req);
+    if (!rejectionReason) {
+        return true;
     }
-    const activeTicket = getTicket(activeRun.ticket_id);
-    return {
-        active_ticket_id: activeRun.ticket_id,
-        error: activeTicket
-            ? activeTicket.bundle
-                ? `Ticket "${activeTicket.title}" in bundle "${activeTicket.bundle.name}" is already running. Stop it before starting another run.`
-                : `Ticket "${activeTicket.title}" is already running. Stop it before starting another run.`
-            : 'Another ticket is already running. Stop it before starting another run.',
-    };
+    res.status(403).json({ error: rejectionReason });
+    return false;
 };
-app.use(express.json({ limit: '5mb' }));
+app.get('/mobile-access/status', (_req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(getMobileAccessStatus());
+});
+app.post('/mobile-access/enable', async (req, res) => {
+    if (!requireDesktopMobileAccessRequest(req, res)) {
+        return;
+    }
+    const requestedMode = req.body?.mode === 'custom_public_url'
+        ? 'custom_public_url'
+        : req.body?.mode === 'ngrok'
+            ? 'ngrok'
+            : req.body?.mode === 'lan'
+                ? 'lan'
+                : null;
+    const publicBaseUrl = typeof req.body?.public_base_url === 'string'
+        ? req.body.public_base_url
+        : null;
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(await startMobileAccess({
+        mode: requestedMode,
+        clientBuild: resolveClientBuildPaths(import.meta.url),
+        broadcaster: io,
+        reviewBundleTickets,
+        publicBaseUrl,
+    }));
+});
+app.post('/mobile-access/disable', async (req, res) => {
+    if (!requireDesktopMobileAccessRequest(req, res)) {
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(await stopMobileAccess());
+});
+app.post('/mobile-access/regenerate-pairing', (req, res) => {
+    if (!requireDesktopMobileAccessRequest(req, res)) {
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(regenerateMobilePairingChallenge());
+});
+app.post('/mobile-access/sessions/:sessionId/revoke', (req, res) => {
+    if (!requireDesktopMobileAccessRequest(req, res)) {
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(revokeMobileSession(req.params.sessionId));
+});
 app.get('/run-config', (req, res) => {
     const ticketId = typeof req.query.ticketId === 'string' ? req.query.ticketId : null;
     if (!ticketId) {
@@ -1964,29 +1951,15 @@ app.get('/projects/:id/chat-sessions', (req, res) => {
     return res.json(listChatSessions(project.id));
 });
 app.post('/projects/:id/chat-sessions', (req, res) => {
-    const project = getProjectById(req.params.id);
-    if (!project) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const tool = resolveChatTool(req.body.tool);
-    const mode = resolveChatMode(req.body.mode);
-    const rawModel = typeof req.body.model === 'string' ? req.body.model : project.helper_model;
-    const normalizedModel = tool === 'opencode' ? normalizeModelId(rawModel) || null : null;
-    const normalizedVariant = tool === 'opencode' && normalizedModel && typeof req.body.variant === 'string'
-        ? req.body.variant.trim() || null
-        : tool === 'opencode' && normalizedModel
-            ? project.helper_variant ?? null
-            : null;
-    const chatSession = createChatSession({
-        projectId: project.id,
-        mode,
-        tool,
-        model: normalizedModel,
-        variant: normalizedVariant,
-        skills: normalizeSkillNames(req.body.skills),
+    const result = createProjectChatSession({
+        projectId: req.params.id,
+        payload: req.body,
+        broadcaster: io,
     });
-    io.emit('chat-session:created', chatSession);
-    return res.status(201).json(chatSession);
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
+    }
+    return res.status(result.status).json(result.value);
 });
 app.get('/projects/:id/chat-sessions/:sessionId', (req, res) => {
     const project = getProjectById(req.params.id);
@@ -2020,55 +1993,26 @@ app.patch('/projects/:id/chat-sessions/:sessionId', (req, res) => {
     return res.json(updated);
 });
 app.post('/projects/:id/chat-sessions/:sessionId/messages', (req, res) => {
-    const project = getProjectById(req.params.id);
-    if (!project) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const existing = getProjectChatSession(project.id, req.params.sessionId);
-    if (!existing) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const instruction = typeof req.body.instruction === 'string' ? req.body.instruction.trim() : '';
-    if (!instruction) {
-        return res.status(400).json({ error: 'instruction is required' });
-    }
-    const targetResolution = resolveChatSessionTarget(existing, project);
-    if (!targetResolution.target_available) {
-        return res.status(409).json({ error: targetResolution.target_unavailable_reason ?? 'Chat target is unavailable.' });
-    }
-    if (!doesChatSessionTargetMatchProjectTarget(existing, project)) {
-        return res.status(409).json({ error: 'This chat session is out of sync with the current project target. Restore the session target to continue.' });
-    }
-    const rawModel = typeof req.body.model === 'string' ? req.body.model : project.helper_model;
-    const accepted = startChatSessionTurn({
-        chatSessionId: existing.id,
-        instruction,
-        tool: existing.tool,
-        model: typeof rawModel === 'string' ? rawModel : null,
-        variant: typeof req.body.variant === 'string' ? req.body.variant : project.helper_variant,
-        skills: normalizeSkillNames(req.body.skills),
-        io,
+    const result = submitProjectChatSessionMessage({
+        projectId: req.params.id,
+        chatSessionId: req.params.sessionId,
+        payload: req.body,
+        broadcaster: io,
     });
-    if (!accepted) {
-        return res.status(409).json({ error: 'This chat session is already running.' });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    const updated = getProjectChatSession(project.id, existing.id);
-    return res.json(updated);
+    return res.status(result.status).json(result.value);
 });
 app.post('/projects/:id/chat-sessions/:sessionId/stop', async (req, res) => {
-    const project = getProjectById(req.params.id);
-    if (!project) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const chatSession = getProjectChatSession(project.id, req.params.sessionId);
-    if (!chatSession) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const stopped = await stopChatAgent(chatSession.id);
-    if (!stopped) {
-        return res.status(409).json({ error: 'No active chat response found for this session.' });
+    const result = await stopProjectChatSessionResponse({
+        projectId: req.params.id,
+        chatSessionId: req.params.sessionId,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    return res.json({ ok: true });
+    return res.status(result.status).json(result.value);
 });
 app.get('/projects/:id/chat-sessions/:sessionId/diff', (req, res) => {
     const project = getProjectById(req.params.id);
@@ -2292,7 +2236,8 @@ app.get('/tickets/:id/git-status', (req, res) => {
     if ('error' in workspace) {
         return res.status(workspace.status).json({ error: workspace.error });
     }
-    return res.json(getGitStatus(workspace.cwd, workspace.branch, workspace.project));
+    const refreshRemote = req.query.refresh_remote === 'true';
+    return res.json(getGitStatus(workspace.cwd, workspace.branch, workspace.project, { refreshRemote }));
 });
 app.get('/tickets/:id/git-commits', (req, res) => {
     const ticket = getTicketRouteContext(req.params.id);
@@ -4363,6 +4308,18 @@ app.patch('/tickets/:id', (req, res) => {
     const hasVariantField = hasOwn(req.body, 'variant');
     const hasSkillsField = hasOwn(req.body, 'skills');
     const isSettingsOnlyUpdate = !hasTitleField && !hasDescriptionField && !hasProjectField && !hasBundleField && (hasModelField || hasVariantField || hasSkillsField);
+    if (isTicketAgentSettingsPayload(req.body)) {
+        const result = updateTicketAgentSettings({
+            ticketId: req.params.id,
+            requestedProjectId: getRequestedProjectId(req),
+            payload: req.body,
+            broadcaster: io,
+        });
+        if (!result.ok) {
+            return res.status(result.status).json({ error: result.error });
+        }
+        return res.status(result.status).json(result.value);
+    }
     if (!isPlanTicket && !isSettingsOnlyUpdate) {
         return res.status(400).json({ error: 'Only plan tickets can be fully edited after work begins' });
     }
@@ -4480,79 +4437,21 @@ app.patch('/tickets/:id', (req, res) => {
     res.json(updated);
 });
 app.patch('/tickets/:id/state', (req, res) => {
-    const state = typeof req.body.state === 'string' ? req.body.state : '';
-    const validStates = ['plan', 'build', 'review'];
-    if (!validStates.includes(state)) {
-        return res.status(400).json({ error: 'Invalid state' });
-    }
-    const existing = getTicket(req.params.id);
-    if (!existing) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(existing, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (state === 'plan' && existing.state !== 'plan') {
-        return res.status(409).json({ error: 'Tickets cannot be moved back to plan after work begins' });
-    }
-    if (state === 'build') {
-        const buildBlocker = getBundleBuildBlockerResponse(existing);
-        if (buildBlocker) {
-            return res.status(409).json(buildBlocker);
-        }
-        const buildTransition = prepareTicketForBuild(existing.id);
-        if (!buildTransition.ok) {
-            return res.status(buildTransition.status).json({
-                error: buildTransition.error,
-                ...(buildTransition.blockers ? { blockers: buildTransition.blockers } : {}),
-            });
-        }
-        io.emit('ticket:updated', buildTransition.ticket);
-        res.json(buildTransition.ticket);
-        if (buildTransition.ticket.project_id && buildTransition.ticket.worktree_bundle_id) {
-            const queuedBuild = enqueueBundledBuild({
-                ticketId: buildTransition.ticket.id,
-                projectId: buildTransition.ticket.project_id,
-                worktreeBundleId: buildTransition.ticket.worktree_bundle_id,
-                activate: shouldStartBundleBuildNow(buildTransition.ticket),
-            });
-            if (!queuedBuild.shouldStartNow) {
-                return;
-            }
-        }
-        startBuild(buildTransition.ticket, io);
-        return;
-    }
-    if (state === 'review' && (existing.state !== 'build' || existing.agent_status !== 'done')) {
-        return res.status(409).json({ error: 'Tickets can only be moved to review from build when done' });
-    }
-    const project = getEffectiveProject(existing);
-    if (state === 'review' && !project) {
-        return res.status(400).json({ error: 'Ticket project no longer exists' });
-    }
-    if (state === 'review' && existing.project_id && existing.worktree_bundle_id) {
-        const reviewResult = reviewBundleTickets(existing.project_id, existing.worktree_bundle_id);
-        if (!reviewResult.ok) {
-            return res.status(reviewResult.status).json({ error: reviewResult.error });
-        }
-        const updated = reviewResult.details.tickets.find(ticket => ticket.id === existing.id);
-        if (!updated) {
-            return res.status(409).json({ error: 'Unable to update the requested ticket in this bundle' });
-        }
-        return res.json(updated);
+    const result = transitionTicketState({
+        ticketId: req.params.id,
+        requestedState: req.body.state,
+        requestedProjectId: getRequestedProjectId(req),
+        broadcaster: io,
+        reviewBundleTickets,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({
+            error: result.error,
+            ...result.details,
+        });
     }
-    const nextAgentStatus = state === 'review' ? null : existing.agent_status;
-    const nextAgentLog = state === 'review' ? null : existing.agent_log;
-    const nextSessionId = existing.session_id;
-    db.prepare('UPDATE tickets SET state = ?, tool = ?, agent_status = ?, agent_log = ?, session_id = ?, streaming_response = NULL, lane_order = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(state, resolveTicketTool(existing, config.tool ?? 'opencode'), nextAgentStatus, nextAgentLog, nextSessionId, assignTicketLaneOrder({ ...existing, state }) ?? null, req.params.id);
-    const ticket = autoParkTicketIfStale(req.params.id);
-    if (state === 'review' && ticket) {
-        startReview(ticket, io);
-        const runningReview = getTicket(req.params.id);
-        return res.json(runningReview);
-    }
-    io.emit('ticket:updated', ticket);
-    res.json(ticket);
+    res.status(result.status).json(result.value);
+    result.afterResponse?.();
 });
 app.patch('/tickets/:id/park', (req, res) => {
     const ticket = getTicket(req.params.id);
@@ -4754,41 +4653,19 @@ app.post('/tickets/:id/undo', (req, res) => {
     return res.json(result.ticket);
 });
 app.post('/tickets/:id/run', (req, res) => {
-    const ticket = getTicket(req.params.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(ticket, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    const project = getEffectiveProject(ticket);
-    if (!project) {
-        return res.status(400).json({ error: 'Ticket project no longer exists' });
-    }
-    const workspace = resolveTicketGitWorkspace(ticket);
-    if ('error' in workspace) {
-        return res.status(workspace.status).json({ error: workspace.error });
-    }
-    if (!hasRunConfig(project)) {
-        return res.status(400).json({ error: 'No run config' });
-    }
-    const runReadinessError = getTicketRunReadinessError(ticket, project);
-    if (runReadinessError) {
-        return res.status(409).json({ error: runReadinessError });
-    }
-    if (isRunning(ticket)) {
-        emitRunStateForContext(ticket, true);
-        const runningTicket = listTicketsInRunContext(ticket).find(entry => entry.id === ticket.id);
-        return res.json(runningTicket ?? { ...ticket, is_running: true, has_run_config: true });
-    }
-    const activeRunConflict = formatActiveRunConflict(ticket.project_id);
-    if (activeRunConflict) {
-        return res.status(409).json(activeRunConflict);
+    const result = runTicketRun({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+        broadcaster: io,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({
+            error: result.error,
+            ...result.details,
+        });
     }
-    const running = { ...ticket, is_running: true, has_run_config: true };
-    emitRunStateForContext(ticket, true);
-    res.json(running);
-    runTicketInWorkspace(ticket, io, project, workspace.cwd);
+    res.status(result.status).json(result.value);
+    result.afterResponse?.();
 });
 app.post('/tickets/:id/open-ide', (req, res) => {
     const ticket = getTicket(req.params.id);
@@ -4981,46 +4858,17 @@ app.post('/projects/:id/open-ide', (req, res) => {
     return res.json({ ok: true });
 });
 app.post('/projects/:id/run', (req, res) => {
-    const project = getProjectById(req.params.id);
-    if (!project) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!hasRunConfig(project)) {
-        return res.status(400).json({ error: 'No run config' });
-    }
-    const workspace = resolveProjectTargetGitWorkspace(project);
-    if ('error' in workspace) {
-        return res.status(workspace.status).json({ error: workspace.error });
-    }
-    const contextKey = workspace.run_context_key;
-    if (isRunning(contextKey)) {
-        return res.json({
-            active_run: {
-                kind: 'project',
-                context_key: contextKey,
-                project_id: project.id,
-                target_kind: workspace.target_kind,
-                target_bundle_id: workspace.target_bundle_id,
-            },
+    const result = runProjectTarget({
+        projectId: req.params.id,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({
+            error: result.error,
+            ...result.details,
         });
     }
-    const activeRunConflict = formatActiveRunConflict(project.id);
-    if (activeRunConflict) {
-        return res.status(409).json(activeRunConflict);
-    }
-    const activeRun = {
-        kind: 'project',
-        context_key: contextKey,
-        project_id: project.id,
-        target_kind: workspace.target_kind,
-        target_bundle_id: workspace.target_bundle_id,
-    };
-    res.json({ active_run: activeRun });
-    void runProject(project, {
-        cwd: workspace.cwd,
-        targetKind: workspace.target_kind,
-        targetBundleId: workspace.target_bundle_id,
-    });
+    res.status(result.status).json(result.value);
+    result.afterResponse?.();
 });
 app.post('/projects/:id/test-sessions', (req, res) => {
     const project = getProjectById(req.params.id);
@@ -5203,154 +5051,69 @@ app.post('/terminals/:sessionId/destroy', (req, res) => {
     return res.status(204).send();
 });
 app.post('/tickets/:id/stop', async (req, res) => {
-    const ticket = getTicket(req.params.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(ticket, req)) {
-        return res.status(404).json({ error: 'Not found' });
+    const result = await stopTicketRun({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+        broadcaster: io,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    await stopTicket(ticket);
-    emitRunStateForContext(ticket, false);
-    const updated = listTicketsInRunContext(ticket).find(entry => entry.id === ticket.id) ?? { ...ticket, is_running: false };
-    res.json(updated);
+    return res.status(result.status).json(result.value);
 });
 app.post('/projects/:id/stop-run', async (req, res) => {
-    const project = getProjectById(req.params.id);
-    if (!project) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    await stopProjectRun(project.id, {
-        kind: project.active_target_kind,
-        bundleId: project.active_target_bundle_id,
+    const result = await stopProjectTargetRun({
+        projectId: req.params.id,
     });
-    return res.json({ active_run: getActiveRunStatusForProject(project.id) });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
+    }
+    return res.status(result.status).json(result.value);
 });
 app.post('/tickets/:id/stop-build', async (req, res) => {
-    const ticket = getTicket(req.params.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(ticket, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!canUseBuildControls(ticket)) {
-        return res.status(400).json({ error: 'Only build-stage and review follow-up tickets can stop builds' });
-    }
-    if (ticket.agent_status !== 'running') {
-        return res.status(400).json({ error: 'Ticket build is not running' });
-    }
-    if (!ticket.session_id) {
-        return res.status(400).json({ error: 'Build session is not ready to stop yet' });
-    }
-    if (!isBuildAgentRunning(ticket.id)) {
-        return res.status(409).json({ error: 'No active build process found for this ticket' });
-    }
-    await stopBuildAgent(ticket.id);
-    const updated = getTicket(req.params.id);
-    if (!updated) {
-        return res.status(404).json({ error: 'Not found' });
+    const result = await stopBuildTicketRun({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    res.json(updated);
+    return res.status(result.status).json(result.value);
 });
 app.post('/tickets/:id/resume-build', (req, res) => {
-    const existing = getTicket(req.params.id);
-    if (!existing) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(existing, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!canUseBuildControls(existing)) {
-        return res.status(400).json({ error: 'Only build-stage and review follow-up tickets can resume builds' });
-    }
-    if (existing.agent_status !== 'stopped') {
-        return res.status(400).json({ error: 'Only manually stopped builds can be resumed' });
-    }
-    if (!existing.session_id) {
-        return res.status(400).json({ error: 'Build session is not available to resume' });
-    }
-    db.prepare('UPDATE tickets SET build_completed_at = NULL, auto_park_dismissed_at = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(existing.id);
-    const ticket = getTicket(existing.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
+    const result = resumeBuildTicketRun({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+        broadcaster: io,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    resumeBuild(ticket, io);
-    res.json(ticket);
+    return res.status(result.status).json(result.value);
 });
 app.post('/tickets/:id/follow-up', (req, res) => {
-    const ticket = getTicket(req.params.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(ticket, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (ticket.state === 'plan') {
-        return res.status(400).json({ error: 'Only non-plan tickets can accept follow-up prompts' });
-    }
-    if (ticket.agent_status === 'running') {
-        return res.status(409).json({ error: 'Ticket is already running' });
-    }
-    const instruction = typeof req.body?.instruction === 'string'
-        ? req.body.instruction.trim()
-        : '';
-    if (!instruction) {
-        return res.status(400).json({ error: 'instruction is required' });
-    }
-    const project = getEffectiveProject(ticket);
-    if (!project) {
-        return res.status(400).json({ error: 'Ticket project no longer exists' });
-    }
-    const branch = resolveTicketBranch(ticket);
-    if (!branch || ticket.has_worktree === false || !isWorktreeReady(branch, project)) {
-        return res.status(400).json({ error: 'Worktree not ready yet' });
-    }
-    createTicketMessage({
-        ticketId: ticket.id,
-        role: 'user',
-        kind: 'follow_up',
-        content: instruction,
+    const result = submitTicketFollowUp({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+        payload: req.body,
+        broadcaster: io,
     });
-    const started = startFollowUp(ticket, io, instruction);
-    if (!started) {
-        return res.status(409).json({ error: 'Ticket is already running' });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    const updated = getTicket(ticket.id);
-    return res.json(updated ?? ticket);
+    return res.status(result.status).json(result.value);
 });
 app.post('/tickets/:id/plan-follow-up', (req, res) => {
-    const ticket = getTicket(req.params.id);
-    if (!ticket) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (!matchesTicketProjectContext(ticket, req)) {
-        return res.status(404).json({ error: 'Not found' });
-    }
-    if (ticket.state !== 'plan') {
-        return res.status(400).json({ error: 'Only plan tickets can accept planning follow-up prompts' });
-    }
-    if (ticket.agent_status === 'running') {
-        return res.status(409).json({ error: 'Ticket is already running' });
-    }
-    const instruction = typeof req.body?.instruction === 'string'
-        ? req.body.instruction.trim()
-        : '';
-    if (!instruction) {
-        return res.status(400).json({ error: 'instruction is required' });
-    }
-    createTicketMessage({
-        ticketId: ticket.id,
-        role: 'user',
-        kind: 'planning_follow_up',
-        content: instruction,
+    const result = submitPlanTicketFollowUp({
+        ticketId: req.params.id,
+        requestedProjectId: getRequestedProjectId(req),
+        payload: req.body,
+        broadcaster: io,
     });
-    const started = startPlanFollowUp(ticket, io, instruction);
-    if (!started) {
-        return res.status(409).json({ error: 'Ticket is already running' });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
     }
-    const updated = getTicket(ticket.id);
-    return res.json(updated ?? ticket);
+    return res.status(result.status).json(result.value);
 });
 app.post('/tickets/:id/plan', (req, res) => {
     const ticket = getTicket(req.params.id);
@@ -5429,26 +5192,20 @@ io.on('connection', (socket) => {
     registerTerminalSocketHandlers(io, socket);
 });
 const DEFAULT_PORT = 3001;
-const resolveListeningHost = (host) => {
-    if (!host || host === '0.0.0.0' || host === '::') {
-        return 'localhost';
-    }
-    return host;
-};
 const resolveStartResult = (host) => {
     const address = httpServer.address();
-    const listeningHost = resolveListeningHost(host);
+    const { displayHost } = resolveDesktopServerHost(host);
     if (!address || typeof address === 'string') {
         return {
-            host: listeningHost,
+            host: displayHost,
             port: DEFAULT_PORT,
-            url: `http://${listeningHost}:${DEFAULT_PORT}`,
+            url: `http://${displayHost}:${DEFAULT_PORT}`,
         };
     }
     return {
-        host: listeningHost,
+        host: displayHost,
         port: address.port,
-        url: `http://${listeningHost}:${address.port}`,
+        url: `http://${displayHost}:${address.port}`,
     };
 };
 export const startServer = ({ port = DEFAULT_PORT, host } = {}) => {
@@ -5466,14 +5223,12 @@ export const startServer = ({ port = DEFAULT_PORT, host } = {}) => {
             resolve(resolveStartResult(host));
         };
         httpServer.once('error', handleError);
-        if (host) {
-            httpServer.listen(port, host, handleListening);
-            return;
-        }
-        httpServer.listen(port, handleListening);
+        const { bindHost } = resolveDesktopServerHost(host);
+        httpServer.listen(port, bindHost, handleListening);
     });
 };
 export const shutdownServer = async (signal) => {
+    await stopMobileAccess();
     await clearAllTestSessions(io);
     await shutdownRealtimeServer({
         signal,