@shugaev/spur 0.1.1 → 0.1.2

package/dist/session-service.js

@@ -7,8 +7,10 @@ import { shellEscape } from "./agents/shell-escape.js";
 import { deleteAgentHookState, readAgentHookState } from "./agent-hook-state.js";
 import { assertBranchNameMatches, matchesBranchNaming, normalizeBranchName, } from "./branch-name.js";
 import { findLatestSessionFile as findLatestClaudeSessionFile } from "./agents/claude.js";
+import { extractGithubErrorText, isGitHubRateLimitError } from "./gh.js";
 import { codexHookHomePath, findLatestCodexSessionFile, readCodexRolloutState, } from "./agents/codex.js";
-import { cursorConfigDirForSession } from "./agents/cursor.js";
+import { DEFAULT_CURSOR_MODEL, cursorConfigDirForSession } from "./agents/cursor.js";
+import { resolveCursorLaunchModel } from "./agents/models.js";
 import { scanTmuxRateLimit } from "./rate-limit-detect.js";
 import { loadProjectSuggestions, loadSessionSuggestions } from "./agent-suggestions.js";
 import { readClaudeConversation, readClaudeJsonlState, } from "./claude-jsonl-state.js";
@@ -16,11 +18,12 @@ import { readClaudeSessionStatus } from "./claude-session-status.js";
 import { buildSidecarLinkUrl, deriveProjectIdFromDisplayName, expandHome, findProjectConfigPath, loadProjectConfig, PROJECT_ID_PATTERN, } from "./config.js";
 import { buildShepherdProject, ensureShepherdWorkspace, SHEPHERD_PROJECT_ID, SHEPHERD_PROJECT_NAME, renderShepherdPrompt, } from "./shepherd.js";
 import { renderBootstrapPrompt } from "./bootstrap-prompt.js";
+import { renderSpawnPrompt } from "./prompt-template.js";
 import { logSpurEvent } from "./event-log.js";
 import { reserveNextSessionId } from "./ids.js";
 import { clearPortListener, isHostPortFree } from "./port-probe.js";
 import { sendDesktopNotification } from "./desktop-notify.js";
-import { requestGitHubMergeConflictRestoreReplay, deleteRuntimeLogCursorsForSession, deleteServiceInstance, deleteServiceInstancesForSession, deleteServiceSourceStatesForService, deleteServiceSourceStatesForSession, listActiveServiceProblems, listServiceInstances, listServiceInstancesForSession, listSessions, readServiceInstance, readSession, writeServiceInstance, writeSession, } from "./metadata.js";
+import { claimAvailableBacklogItem, requestGitHubMergeConflictRestoreReplay, deleteRuntimeLogCursorsForSession, deleteServiceInstance, deleteServiceInstancesForSession, deleteServiceSourceStatesForService, deleteServiceSourceStatesForSession, listActiveServiceProblems, readAvailableBacklogItems, listServiceInstances, listServiceInstancesForSession, listSessions, readServiceInstance, readSession, writeServiceInstance, writeSession, } from "./metadata.js";
 import { PreflightBranchValidationError, runSpawnPreflight, } from "./preflight.js";
 import { PREFLIGHT_DEFER_SENTINEL } from "./preflight-contract.js";
 import { parseSpawnOverrides } from "./spawn-overrides.js";
@@ -75,6 +78,10 @@ const DEFAULT_DAILY_WAKE_MESSAGE = "Scheduled daily wake-up. Review current stat
 export class SessionResourceNotFoundError extends Error {
     statusCode = 404;
 }
+export class BacklogItemUnavailableError extends Error {
+    statusCode = 409;
+}
+const DEFAULT_BACKLOG_PROMPT = "Work on {{key}}: {{title}}\n\n{{url}}";
 export class InvalidClearPortError extends Error {
     statusCode = 400;
 }
@@ -107,6 +114,19 @@ export class OpenPrActionRequiredError extends Error {
         };
     }
 }
+export class GithubPrCheckUnavailableError extends Error {
+    statusCode = 409;
+    payload;
+    constructor(sessionId, pr, { rateLimited }) {
+        super(`GitHub PR check unavailable for ${sessionId}`);
+        this.payload = {
+            code: "github_pr_check_unavailable",
+            sessionId,
+            pr,
+            rateLimited,
+        };
+    }
+}
 export class SessionNotRestorableError extends Error {
     statusCode = 409;
     payload;
@@ -540,7 +560,15 @@ function resolveSpawnWorktree(project, overrides) {
 // model wins; otherwise the project defaultModels entry for the resolved agent
 // applies. The map is keyed by agent, so it never bleeds onto another agent.
 export function resolveSpawnModel(args) {
-    return args.requestModel ?? args.project.defaultModels?.[args.resolvedAgent];
+    return (args.requestModel ??
+        args.project.defaultModels?.[args.resolvedAgent] ??
+        (args.resolvedAgent === "cursor" ? DEFAULT_CURSOR_MODEL : undefined));
+}
+async function resolveAgentLaunchModel(agent, model) {
+    if (agent !== "cursor") {
+        return model;
+    }
+    return resolveCursorLaunchModel(model);
 }
 function resolveSpawnDefaultBranch(args) {
     if (!args.worktree && args.overrides?.defaultBranch !== undefined) {
@@ -554,10 +582,18 @@ function normalizeShepherdSpawnRequest(request) {
     }
     return {
         ...request,
-        agent: "claude",
         overrides: { ...(request.overrides ?? {}), worktree: false },
     };
 }
+function spawnPreflightDeferLogMessage(preflight) {
+    if (!preflight.deferReason) {
+        return "Spawn preflight: agent deferred branch naming (NO_PROJECT_RULES); using default naming";
+    }
+    if (preflight.attempts < SPAWN_PREFLIGHT_MAX_ATTEMPTS) {
+        return `Spawn preflight failed; deferring to default naming: ${preflight.deferReason}`;
+    }
+    return `Spawn preflight exhausted ${preflight.attempts} attempts; deferring to default naming: ${preflight.deferReason}`;
+}
 function isFeedbackRetryablePreflightError(message) {
     return (message.startsWith("preflight branch ") ||
         message.startsWith("Spawn preflight must return exactly one branch name"));
@@ -671,13 +707,17 @@ async function runSpawnPreflightForSpawn(args) {
                 lastProposedBranch = error.branch;
             }
             if (!isFeedbackRetryablePreflightError(message)) {
-                throw lastError;
+                return {
+                    outcome: "defer",
+                    attempts: attempt,
+                    deferReason: message,
+                };
             }
             feedback = `${message}.${ruleHint} Return a corrected branch name, or return ${PREFLIGHT_DEFER_SENTINEL} if project rules do not define one.`;
             continue;
         }
         if (!preflight.branch) {
-            return { outcome: "defer", attempts: attempt };
+            return { outcome: "defer", attempts: attempt, unvalidated: true };
         }
         const branchConflictPath = await findWorktreePathForBranch(args.project.path, preflight.branch);
         if (!branchConflictPath) {
@@ -701,6 +741,7 @@ async function runSpawnPreflightForSpawn(args) {
         outcome: "defer",
         attempts: SPAWN_PREFLIGHT_MAX_ATTEMPTS,
         deferReason,
+        unvalidated: true,
     };
 }
 function projectHasService(project, serviceId) {
@@ -1907,6 +1948,42 @@ export class SessionService {
         }
         return this.enrich(session);
     }
+    listAvailableBacklog() {
+        const items = [];
+        for (const [projectId, project] of Object.entries(this.config.projects)) {
+            for (const backlogId of Object.keys(project.backlog)) {
+                items.push(...readAvailableBacklogItems(this.config.dataDir, projectId, backlogId));
+            }
+        }
+        return items.sort((left, right) => right.fetchedAt.localeCompare(left.fetchedAt));
+    }
+    async takeAvailableBacklog(request) {
+        const project = this.config.projects[request.projectId];
+        const binding = project?.backlog[request.backlogId];
+        if (!project || !binding) {
+            throw new BacklogItemUnavailableError("Backlog item is unavailable");
+        }
+        const item = claimAvailableBacklogItem(this.config.dataDir, request.projectId, request.backlogId, request.externalId);
+        if (!item) {
+            throw new BacklogItemUnavailableError("Backlog item is unavailable");
+        }
+        const prompt = renderSpawnPrompt(binding.spawn?.prompt ?? DEFAULT_BACKLOG_PROMPT, {
+            key: item.key,
+            title: item.title,
+            url: item.url,
+            provider: item.provider,
+            backlogId: request.backlogId,
+        });
+        const session = await this.spawnInBackground({
+            project: request.projectId,
+            prompt,
+            ...(binding.spawn?.agent ? { agent: binding.spawn.agent } : {}),
+            slots: {
+                links: [{ label: "tracker", url: item.url }],
+            },
+        });
+        return { item, session };
+    }
     listSessionMemory(sessionId) {
         this.requireSessionMemorySession(sessionId);
         return {
@@ -2271,7 +2348,6 @@ export class SessionService {
                 ...normalizeSpawnRequest({
                     ...request,
                     prompt: renderShepherdPrompt(request.prompt),
-                    agent: "claude",
                     overrides: { ...(request.overrides ?? {}), worktree: false },
                 }, project.spawn?.steps),
             };
@@ -2294,6 +2370,7 @@ export class SessionService {
             symlinks: [],
             sidecars: {},
             sources: {},
+            backlog: {},
             triggers: {},
         };
         const bootstrapPrompt = renderBootstrapPrompt({
@@ -2340,11 +2417,11 @@ export class SessionService {
             const reuseCtx = this.resolveWorkspaceReuseContext(request, project, worktree);
             const defaultBranch = resolveSpawnDefaultBranch({ project, worktree, overrides });
             agent = parseAgentName(request.agent ?? project.defaultAgent ?? this.config.defaultAgent);
-            resolvedModel = resolveSpawnModel({
+            resolvedModel = await resolveAgentLaunchModel(agent, resolveSpawnModel({
                 requestModel: request.model,
                 resolvedAgent: agent,
                 project,
-            });
+            }));
             let effectiveBranch = request.branch;
             let effectiveBranchSource = request.branch ? "explicit" : undefined;
             if (!reuseCtx && !effectiveBranch && worktree && project.preflight && prompt) {
@@ -2382,13 +2459,11 @@ export class SessionService {
                     });
                 }
                 else {
-                    preflightUnvalidatedBranch = true;
+                    preflightUnvalidatedBranch = preflight.unvalidated === true;
                     this.logEvent("session.preflight.deferred", {
                         level: "warn",
                         projectId: request.project,
-                        message: preflight.deferReason
-                            ? `Spawn preflight exhausted ${preflight.attempts} attempts; deferring to default naming: ${preflight.deferReason}`
-                            : "Spawn preflight: agent deferred branch naming (NO_PROJECT_RULES); using default naming",
+                        message: spawnPreflightDeferLogMessage(preflight),
                         details: {
                             attempts: preflight.attempts,
                             branch: null,
@@ -2397,6 +2472,11 @@ export class SessionService {
                     });
                 }
             }
+            // Preflight phase is done. Reserve/branch resolution below is the same
+            // phase the non-preflight path runs under "validating"; reset so a
+            // downstream failure here is not mislabeled as a preflight failure.
+            // Mirror: background runBackgroundSpawnAttempt() ~4032.
+            stage = "validating";
             sessionId = await reserveNextSessionId(this.config.dataDir, request.project, project.sessionPrefix);
             if (!reuseCtx && preflightOutcome) {
                 this.logEvent("session.preflight.completed", {
@@ -2878,11 +2958,11 @@ export class SessionService {
             reuseCtx = this.resolveWorkspaceReuseContext(request, project, worktree);
             const defaultBranch = resolveSpawnDefaultBranch({ project, worktree, overrides });
             agent = parseAgentName(request.agent ?? project.defaultAgent ?? this.config.defaultAgent);
-            resolvedModel = resolveSpawnModel({
+            resolvedModel = await resolveAgentLaunchModel(agent, resolveSpawnModel({
                 requestModel: request.model,
                 resolvedAgent: agent,
                 project,
-            });
+            }));
             sessionId = await reserveNextSessionId(this.config.dataDir, request.project, project.sessionPrefix);
             if (reuseCtx) {
                 resolvedBranch = reuseCtx.resolvedBranch;
@@ -2928,6 +3008,7 @@ export class SessionService {
                 ...(Object.keys(project.sidecars).length > 0
                     ? { sidecarNames: Object.keys(project.sidecars) }
                     : {}),
+                ...(request.slots?.links?.length ? { slots: { links: request.slots.links } } : {}),
                 ...(selfDestruct !== undefined ? { selfDestruct } : {}),
             };
             writeSession(this.config.dataDir, placeholder);
@@ -3057,14 +3138,12 @@ export class SessionService {
                         });
                     }
                     else {
-                        preflightUnvalidatedBranch = true;
+                        preflightUnvalidatedBranch = preflight.unvalidated === true;
                         this.logEvent("session.preflight.deferred", {
                             level: "warn",
                             sessionId,
                             projectId: request.project,
-                            message: preflight.deferReason
-                                ? `Spawn preflight exhausted ${preflight.attempts} attempts; deferring to default naming: ${preflight.deferReason}`
-                                : "Spawn preflight: agent deferred branch naming (NO_PROJECT_RULES); using default naming",
+                            message: spawnPreflightDeferLogMessage(preflight),
                             details: {
                                 attempts: preflight.attempts,
                                 branch: null,
@@ -3090,6 +3169,10 @@ export class SessionService {
                         },
                     });
                 }
+                // Preflight phase is done; branch resolution is its own phase. Reset so a
+                // resolveSpawnBranch failure is not mislabeled as a preflight failure.
+                // Mirror: foreground spawn() ~3238.
+                stage = attempt > 1 ? `retry.${attempt}.branch.resolve` : "branch.resolve";
                 resolvedBranch = await resolveSpawnBranch({
                     repoPath: project.path,
                     requestBranch: effectiveBranch,
@@ -3827,6 +3910,21 @@ export class SessionService {
         }
         const processAlive = await isProcessRunningInTmux(session.tmuxSession, sessionProcessMatchers(session));
         const elapsedMs = Date.now() - startedAt;
+        if (session.agent === "cursor" && processAlive) {
+            this.logEvent("session.submit.recovered", {
+                level: "warn",
+                sessionId: session.id,
+                message: `Cursor submit ack timed out for ${session.id} but agent process is live; continuing`,
+                details: {
+                    agent: session.agent,
+                    lastScannedFile: lastResult.lastScannedFile,
+                    messageLength: message.length,
+                    elapsedMs,
+                    processAlive,
+                },
+            });
+            return;
+        }
         this.logEvent("session.submit.timeout", {
             level: "warn",
             sessionId: session.id,
@@ -3863,35 +3961,45 @@ export class SessionService {
         if (!session.worktreePath || !(await isGitWorktree(session.worktreePath))) {
             return session;
         }
-        const { binding, updatedSession } = await resolveSessionPrBinding(session);
-        const checkedSession = updatedSession ?? session;
-        if (!binding) {
-            return checkedSession;
-        }
-        const pr = await viewSessionPrState(session.worktreePath, binding);
-        if (pr?.state !== "OPEN") {
+        try {
+            const { binding, updatedSession } = await resolveSessionPrBinding(session);
+            const checkedSession = updatedSession ?? session;
+            if (!binding) {
+                return checkedSession;
+            }
+            const pr = await viewSessionPrState(session.worktreePath, binding);
+            if (pr?.state !== "OPEN") {
+                if (updatedSession) {
+                    writeSession(this.config.dataDir, updatedSession);
+                }
+                return checkedSession;
+            }
+            if (action === undefined) {
+                if (updatedSession) {
+                    writeSession(this.config.dataDir, updatedSession);
+                }
+                throw new OpenPrActionRequiredError(session.id, {
+                    number: pr.number,
+                    title: pr.title,
+                    url: pr.url,
+                });
+            }
+            if (action === "close") {
+                await closeSessionPr(session.worktreePath, binding);
+            }
             if (updatedSession) {
                 writeSession(this.config.dataDir, updatedSession);
             }
             return checkedSession;
         }
-        if (action === undefined) {
-            if (updatedSession) {
-                writeSession(this.config.dataDir, updatedSession);
+        catch (error) {
+            if (error instanceof OpenPrActionRequiredError) {
+                throw error;
             }
-            throw new OpenPrActionRequiredError(session.id, {
-                number: pr.number,
-                title: pr.title,
-                url: pr.url,
+            throw new GithubPrCheckUnavailableError(session.id, session.pr ?? null, {
+                rateLimited: isGitHubRateLimitError(extractGithubErrorText(error)),
             });
         }
-        if (action === "close") {
-            await closeSessionPr(session.worktreePath, binding);
-        }
-        if (updatedSession) {
-            writeSession(this.config.dataDir, updatedSession);
-        }
-        return checkedSession;
     }
     async complete(sessionId, request = {}, options) {
         return this.applyManualStatus(sessionId, "completed", request, options);
@@ -4200,7 +4308,7 @@ export class SessionService {
         }
         const eventAction = targetStatus === "stopped" ? "pause" : "complete";
         try {
-            if (targetStatus === "completed") {
+            if (targetStatus === "completed" && !request.skipPrCheck) {
                 session = await this.applyOpenPrAction(session, request.prAction);
             }
             await killTmuxSession(session.tmuxSession);
@@ -4286,7 +4394,7 @@ export class SessionService {
         }
         await this.ensureKillDirtyWorktreeAllowed(session, request.force === true);
         try {
-            if (session.status !== "killed") {
+            if (session.status !== "killed" && !request.skipPrCheck) {
                 if (session.worktree && session.worktreePath && !workspaceExists(session.worktreePath)) {
                     this.logEvent("session.kill.pr_action_skipped_missing_worktree", {
                         level: "warn",
@@ -4452,11 +4560,15 @@ export class SessionService {
         const planMode = resolvePlanMode(session);
         const restrictWrites = resolveRestrictWrites(session);
         const project = this.getProject(session.project);
+        const resolvedModel = await resolveAgentLaunchModel(session.agent, session.model);
         const planOptions = withAgentModeOptions(withProjectAgentOptions(project, {
             ...hookSetup,
             ...(sessionAgentConfig.planOptions ?? {}),
         }), { planMode, restrictWrites });
-        const baseLaunchPlan = buildAgentLaunchPlan(session.agent, session.prompt, planOptions);
+        const baseLaunchPlan = buildAgentLaunchPlan(session.agent, session.prompt, {
+            ...planOptions,
+            ...(resolvedModel !== undefined ? { model: resolvedModel } : {}),
+        });
         const baseLaunchCommand = baseLaunchPlan.launchCommand;
         const recoveryPlan = sessionWithAgentId.agentSessionId
             ? buildAgentResumePlan(sessionWithAgentId.agent, sessionWithAgentId.agentSessionId, baseLaunchCommand, planOptions)
@@ -4613,8 +4725,13 @@ export class SessionService {
                 ...hookSetup,
                 ...(sessionAgentConfig.planOptions ?? {}),
             }), { planMode, restrictWrites });
-            const launchPlan = await waitForRestorePlan(current.agent, current.worktreePath, restorePrompt, planOptions);
-            const effectivePlan = launchPlan ?? buildAgentLaunchPlan(current.agent, restorePrompt, planOptions);
+            const resolvedModel = await resolveAgentLaunchModel(current.agent, current.model);
+            const launchPlanOptions = {
+                ...planOptions,
+                ...(resolvedModel !== undefined ? { model: resolvedModel } : {}),
+            };
+            const launchPlan = await waitForRestorePlan(current.agent, current.worktreePath, restorePrompt, launchPlanOptions);
+            const effectivePlan = launchPlan ?? buildAgentLaunchPlan(current.agent, restorePrompt, launchPlanOptions);
             await killTmuxSession(current.tmuxSession);
             let restoreLaunchCommand = effectivePlan.launchCommand;
             let restoreReadyMarkers = effectivePlan.readyMarkers;
@@ -5616,6 +5733,7 @@ export class SessionService {
         const state = this.stabilizeState(session.id, classified.state);
         await this.updateStateHistory(session, state, classified.source, classified.historySourcePath ?? null);
         const displaySlots = deriveSessionSlots(session);
+        const runningSidecarNames = (await Promise.all((session.sidecarNames ?? []).map(async (name) => (await sidecarTmuxAlive(session.id, name)) ? name : null))).filter((name) => name !== null);
         return {
             ...dashboardSession,
             planMode: resolvePlanMode(dashboardSession),
@@ -5626,6 +5744,7 @@ export class SessionService {
             state,
             lastActivityAt,
             ...((await this.hasServiceIssues(session)) ? { hasServiceIssues: true } : {}),
+            ...(runningSidecarNames.length > 0 ? { runningSidecarNames } : {}),
         };
     }
     async enrich(session) {