fix(workspace): unfreeze re-run pipeline visual + add cooperative run cancel

Two coupled analysis-run-lifecycle changes (AnalysisRunner.tsx carries
both, so they ship together).

1. fix: the re-run pipeline visual was frozen at all-done.
   On a re-run the parent keeps the previous completed `analysisState`
   mounted (it is only swapped when the NEW result lands). AnalysisRunner
   tested `analysisState` BEFORE `analysisLoading` in the stage
   computation, status pip, sub-text and summary, so the stale completed
   result short-circuited every `analysisState ? : analysisLoading ?`
   ternary — every stage stuck at done/100% for the whole re-run. The Run
   button was the lone loading-first branch, which is exactly why it
   flipped to "Running..." while the agent cards stayed frozen. Flipped
   the precedence so `analysisLoading` wins everywhere a re-run needs
   live state; result-derived stale/outage notices are suppressed while
   a re-run is in flight.

2. feat: stop a run mid-flight (Cancel/Abort).
   There was no off-switch — a misfired premium (gpt-5.5) run burned
   tokens with no way to stop it. Added cooperative cancellation at the
   existing stage boundary:
   - WorkspaceRunJob.cancel_requested + cancel_workspace_analysis_job()
     + POST /workspace/analyze-jobs/{job_id}/cancel. WorkspaceRunJobCancelled
     is a plain Exception (not AppError) so it travels unchanged through
     the orchestrator's per-agent / AgentExecutionError handlers.
   - _update_job_progress (runs at every begin_stage) raises it once the
     flag is set; _run_job catches it BEFORE the failure handlers and
     ends the job in a distinct terminal "cancelled" state (no error
     banner, INFO log).
   - Credit auto-refunds: the cancel exception flows through
     run_workspace_analysis' existing `except BaseException` refund path,
     so a stopped run costs zero application/premium credits.
   - Frontend: cancelWorkspaceAnalysisJob() client; useAnalysisJob treats
     `cancelled` as terminal (info notice + quota refetch) + cancelAnalysis()
     + sticky analysisCancelling; "Stop run" button (replaces Clear role
     while running, "Stopping..." while it unwinds). Idempotent /
     double-click-guarded; unknown id -> actionable 404.

   Honest caveat by design: a Python thread mid-OpenAI-call cannot be
   force-killed, so cancel lands at the NEXT agent boundary (a few-30s,
   <=120s worst case). The UI says so rather than implying instant.

Tests: +10 unit (tests/test_workspace_run_jobs_cancel.py — cancel
mechanics, idempotency, the cooperative seam via a faithful fake,
regression guard that real failures still report `failed`) + 2 route
integration. 67 workspace-suite green (no regression); error-message
allowlist green; frontend tsc + eslint clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: LEANDERANTONY

backend/routers/workspace.py

@@ -58,6 +58,7 @@
 from backend.services.workspace_run_jobs import (
     JOB_RETRY_AFTER_SECONDS,
     WorkspaceRunJobCapacityError,
+    cancel_workspace_analysis_job,
     get_workspace_analysis_job,
     start_workspace_analysis_job,
 )
@@ -774,6 +775,31 @@ def get_workspace_analysis_job_route(job_id: str):
     return payload
 
 
+@router.post(
+    "/analyze-jobs/{job_id}/cancel",
+    response_model=WorkspaceAnalyzeJobStatusResponseModel,
+)
+def cancel_workspace_analysis_job_route(job_id: str):
+    # Cooperative cancel: sets the flag and returns immediately. The
+    # job typically comes back still "running" (the worker observes
+    # the flag at its next stage boundary); the frontend keeps polling
+    # GET /analyze-jobs/{job_id} until it sees the terminal
+    # "cancelled". Idempotent for already-terminal jobs. Same
+    # job_id-scoped access model as the status route (the id is an
+    # unguessable uuid4 hex; no extra auth surface added).
+    payload = cancel_workspace_analysis_job(job_id)
+    if payload is None:
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                "This workflow run is no longer available — it may have "
+                "already finished, or the server restarted. There's "
+                "nothing to stop; run the workflow again if needed."
+            ),
+        )
+    return payload
+
+
 @router.post("/assistant/answer")
 @limiter.limit(LIMIT_LLM)
 def answer_assistant_question(

backend/services/workspace_run_jobs.py

@@ -27,6 +27,31 @@ class WorkspaceRunJobCapacityError(RuntimeError):
     """Raised when `_RUN_SEMAPHORE` is exhausted at request time."""
 
 
+class WorkspaceRunJobCancelled(Exception):
+    """Cooperative-cancellation signal for an in-flight analysis job.
+
+    Deliberately a plain `Exception` (NOT an `AppError` / not an
+    `AgentExecutionError`): it must travel UNCHANGED through every
+    handler between the stage-boundary progress callback and
+    `_run_job`'s terminal handler —
+      * the orchestrator's per-agent `except AgentExecutionError` /
+        `except OpenAIUnavailableError` (no match → not swallowed),
+      * `ApplicationOrchestrator.run`'s `except AgentExecutionError`
+        (no match → not turned into a deterministic fallback),
+      * `run_workspace_analysis`'s `except BaseException` (matches →
+        refunds the consumed quota credit, then re-raises — so a
+        cancelled run never costs the user an application credit).
+    `_run_job` catches it explicitly and marks the job `cancelled`
+    (a normal user action, not a failure).
+    """
+
+
+# Terminal statuses: a job here is done moving and a cancel request is
+# a no-op (idempotent — a double-click or a cancel that races
+# completion must not error).
+_TERMINAL_JOB_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+
 @dataclass
 class WorkspaceRunJob:
     job_id: str
@@ -36,6 +61,13 @@ class WorkspaceRunJob:
     progress_percent: int = 3
     result: dict[str, Any] | None = None
     error_message: str | None = None
+    # Set by `cancel_workspace_analysis_job`; observed by the worker at
+    # the next stage boundary (begin_stage → progress callback →
+    # `_update_job_progress`). Cooperative because a Python thread
+    # blocked inside an OpenAI call cannot be force-killed safely, so
+    # cancellation takes effect at the next agent boundary (≤ one
+    # agent / ≤ the per-call timeout), never mid-LLM-call.
+    cancel_requested: bool = False
     created_at: float = field(default_factory=time.time)
     updated_at: float = field(default_factory=time.time)
 
@@ -65,15 +97,30 @@ def _serialize_job(job: WorkspaceRunJob) -> dict[str, Any]:
 
 
 def _update_job_progress(job_id: str, title: str, detail: str, value: int) -> None:
+    # This runs on every pipeline stage boundary (the orchestrator's
+    # `begin_stage` → `_emit_progress` → this callback), which makes it
+    # the natural cooperative-cancellation checkpoint: if a cancel was
+    # requested while the previous agent was working, we abandon the
+    # progress write and raise so the run unwinds at the boundary
+    # instead of advancing into the next (possibly premium) LLM call.
+    cancelled = False
     with _LOCK:
         job = _JOBS.get(job_id)
         if job is None:
             return
-        job.status = "running"
-        job.stage_title = title
-        job.stage_detail = detail
-        job.progress_percent = max(0, min(100, int(value)))
-        job.updated_at = time.time()
+        if job.cancel_requested:
+            cancelled = True
+        else:
+            job.status = "running"
+            job.stage_title = title
+            job.stage_detail = detail
+            job.progress_percent = max(0, min(100, int(value)))
+            job.updated_at = time.time()
+    if cancelled:
+        # Raise OUTSIDE the lock — the unwinding stack (orchestrator →
+        # run_workspace_analysis' refund → _run_job) must never contend
+        # on _LOCK while this propagates.
+        raise WorkspaceRunJobCancelled(job_id)
 
 
 def _run_job(
@@ -117,6 +164,31 @@ def _run_job(
                 job.stage_title = "Workflow crew"
                 job.stage_detail = "All agents are done. Your tailored documents are ready to review."
                 job.updated_at = time.time()
+        except WorkspaceRunJobCancelled:
+            # A normal user action, not a failure — log at INFO and end
+            # the job in a distinct terminal state (NOT "failed", so the
+            # UI doesn't show an error banner). The quota credit was
+            # already refunded by run_workspace_analysis' BaseException
+            # handler on the way up, so the copy can promise that.
+            log_event(
+                LOGGER,
+                20,
+                "workspace_run_job_cancelled",
+                "The background workspace analysis job was cancelled by the user before completion.",
+                job_id=job_id,
+            )
+            with _LOCK:
+                job = _JOBS.get(job_id)
+                if job is None:
+                    return
+                job.status = "cancelled"
+                job.stage_title = "Run stopped"
+                job.stage_detail = (
+                    "You stopped this run before it finished. No credit "
+                    "was used — start a new run whenever you're ready."
+                )
+                job.error_message = None
+                job.updated_at = time.time()
         except AppError as error:
             message = error.user_message
             log_event(
@@ -211,3 +283,33 @@ def get_workspace_analysis_job(job_id: str) -> dict[str, Any] | None:
         if job is None:
             return None
         return _serialize_job(job)
+
+
+def cancel_workspace_analysis_job(job_id: str) -> dict[str, Any] | None:
+    """Request cooperative cancellation of an in-flight analysis job.
+
+    Returns the serialized job, or ``None`` when ``job_id`` is unknown
+    (pruned past TTL, wrong id, or the single-worker process restarted
+    and lost the in-memory registry — the caller maps this to a 404).
+
+    Idempotent by design: cancelling an already-terminal job
+    (completed / failed / cancelled) just returns its current state. A
+    double-click, or a Stop that races the run finishing, must never
+    error.
+
+    This only *sets the flag*. The worker thread is blocked inside the
+    synchronous pipeline (often mid-OpenAI-call) and a Python thread
+    can't be force-killed safely, so the request returns immediately
+    with the job still ``running``; the worker observes the flag at its
+    next stage boundary and flips the job to ``cancelled`` within
+    ≤ one agent. The frontend keeps polling until that terminal state.
+    """
+    with _LOCK:
+        _prune_jobs()
+        job = _JOBS.get(job_id)
+        if job is None:
+            return None
+        if job.status not in _TERMINAL_JOB_STATUSES:
+            job.cancel_requested = True
+            job.updated_at = time.time()
+        return _serialize_job(job)

frontend/src/components/workspace/AnalysisRunner.tsx

@@ -37,6 +37,14 @@ export type AnalysisRunnerProps = {
   analysisIsStale: boolean;
   currentWorkflowStage: WorkflowStage | null;
   onRunAnalysis: () => void;
+  /** Request cooperative cancellation of the in-flight run. Only
+   *  meaningful while `analysisLoading` is true. */
+  onCancelAnalysis: () => void;
+  /** True from Stop-pressed until the run actually ends. Drives the
+   *  Stop button's "Stopping…" + disabled state — cancel is
+   *  cooperative (effective at the next agent boundary), not instant,
+   *  and the UI must not pretend otherwise. */
+  analysisCancelling: boolean;
   onClearRole: () => void;
   /** True when both a resume + JD are present. */
   ready: boolean;
@@ -120,6 +128,8 @@ export function AnalysisRunner({
   analysisIsStale,
   currentWorkflowStage,
   onRunAnalysis,
+  onCancelAnalysis,
+  analysisCancelling,
   onClearRole,
   ready,
   quota,
@@ -169,6 +179,13 @@ export function AnalysisRunner({
   // and a value. We mark stages BEFORE the live one as done, the live
   // one as active w/ the live percent, and stages AFTER as next.
   // After analysis completes, every stage ticks to done.
+  //
+  // Precedence: `analysisLoading` is checked BEFORE `analysisState`.
+  // On a re-run the parent keeps the previous completed
+  // `analysisState` mounted (it's only swapped when the NEW result
+  // lands), so checking it first would freeze every stage at
+  // done/100% for the whole re-run — the live pipeline would never
+  // re-animate. Loading must win so the cards replay the run.
   const liveIndex = liveStageTitle
     ? PIPELINE_STAGES.findIndex((stage) => stage.key === liveStageTitle)
     : -1;
@@ -178,10 +195,7 @@ export function AnalysisRunner({
     let value = 0;
     let detail = "";
 
-    if (analysisState) {
-      state = "done";
-      value = 100;
-    } else if (analysisLoading) {
+    if (analysisLoading) {
       if (liveIndex >= 0) {
         if (index < liveIndex) {
           state = "done";
@@ -196,6 +210,9 @@ export function AnalysisRunner({
         value = livePercent ?? 25;
         detail = "Coordinating agents";
       }
+    } else if (analysisState) {
+      state = "done";
+      value = 100;
     }
     return { ...stage, state, value, detail };
   });
@@ -206,14 +223,14 @@ export function AnalysisRunner({
         <div>
           <div className="b-region-title">Workflow run</div>
           <div className="b-region-sub">
-            {analysisState
-              ? `${analysisState.workflow.mode} · ${
-                  analysisState.workflow.review_approved
-                    ? "review approved"
-                    : "review pending"
-                }`
-              : analysisLoading
-                ? "Generating tailored documents…"
+            {analysisLoading
+              ? "Generating tailored documents…"
+              : analysisState
+                ? `${analysisState.workflow.mode} · ${
+                    analysisState.workflow.review_approved
+                      ? "review approved"
+                      : "review pending"
+                  }`
                 : ready
                   ? "Ready to run — both inputs are loaded."
                   : "Need a parsed resume + JD to run."}
@@ -226,17 +243,17 @@ export function AnalysisRunner({
         <div className="b-run-bar-info">
           <span
             className={
-              analysisState
-                ? "rd-pip rd-pip-live"
-                : analysisLoading
-                  ? "rd-pip rd-pip-ready"
+              analysisLoading
+                ? "rd-pip rd-pip-ready"
+                : analysisState
+                  ? "rd-pip rd-pip-live"
                   : "rd-pip"
             }
           >
-            {analysisState
-              ? "Outputs ready"
-              : analysisLoading
-                ? "Running…"
+            {analysisLoading
+              ? "Running…"
+              : analysisState
+                ? "Outputs ready"
                 : ready
                   ? "Idle"
                   : "Inputs needed"}
@@ -290,25 +307,45 @@ export function AnalysisRunner({
           >
             <PlayIcon /> {analysisLoading ? "Running…" : analysisState ? "Re-run" : "Run analysis"}
           </button>
-          <button
-            className="rd-btn rd-btn-danger rd-btn-sm"
-            disabled={analysisLoading}
-            onClick={onClearRole}
-            type="button"
-          >
-            Clear role
-          </button>
+          {analysisLoading ? (
+            // Stop is only meaningful mid-run. Disabled until the
+            // backend job has an id (the queued placeholder carries
+            // job_id "") and while a stop is already unwinding. Cancel
+            // is cooperative — it lands at the next agent boundary, so
+            // the label says "Stopping…" rather than implying instant.
+            <button
+              className="rd-btn rd-btn-danger rd-btn-sm"
+              disabled={analysisCancelling || !analysisJobState?.job_id}
+              onClick={onCancelAnalysis}
+              title="Stop this run. It wraps up after the current step; no application credit is used."
+              type="button"
+            >
+              {analysisCancelling ? "Stopping…" : "Stop run"}
+            </button>
+          ) : (
+            <button
+              className="rd-btn rd-btn-danger rd-btn-sm"
+              disabled={analysisLoading}
+              onClick={onClearRole}
+              type="button"
+            >
+              Clear role
+            </button>
+          )}
         </div>
       </div>
 
-      {analysisIsStale ? (
+      {analysisIsStale && !analysisLoading ? (
         <div className="b-notice b-notice-warning">
           The inputs changed after the last run. Re-run the workflow to refresh
           your documents.
         </div>
       ) : null}
 
-      {analysisState?.workflow?.service_unavailable ? (
+      {/* Result-derived notices reflect the PREVIOUS run. Suppress
+          while a re-run is in flight so a stale "OpenAI had a moment"
+          banner doesn't contradict the live "Running…" pipeline. */}
+      {analysisState?.workflow?.service_unavailable && !analysisLoading ? (
         <div className="b-notice b-notice-warning">
           {analysisState.workflow.fallback_reason ||
             "Our AI provider (OpenAI) is having a moment, so we built a baseline version of your application. Re-run in a few minutes for the full AI-tailored result."}
@@ -361,7 +398,7 @@ export function AnalysisRunner({
           line. Hidden on desktop via CSS. The pipeline cards
           themselves are also hidden on mobile in the idle / all-done
           states (see globals.css mobile pass). */}
-      {analysisState ? (
+      {analysisState && !analysisLoading ? (
         <div className="b-pipeline-summary" role="status">
           <span aria-hidden="true" className="b-pipeline-summary-pip">
             ✓

frontend/src/components/workspace/WorkspaceShell.tsx

@@ -497,6 +497,8 @@ export function WorkspaceShell() {
     setAnalysisJobState: _setAnalysisJobState,
     currentWorkflowStage,
     runAnalysis: handleRunAnalysis,
+    cancelAnalysis: handleCancelAnalysis,
+    analysisCancelling,
     resetAnalysis,
   } = useAnalysisJob({
     resumeText,
@@ -2337,7 +2339,9 @@ export function WorkspaceShell() {
               analysisJobState={analysisJobState}
               analysisLoading={analysisLoading}
               analysisState={analysisState}
+              analysisCancelling={analysisCancelling}
               currentWorkflowStage={currentWorkflowStage}
+              onCancelAnalysis={() => void handleCancelAnalysis()}
               onClearRole={clearWorkspaceRole}
               onPremiumChange={setPremium}
               onPremiumLockedUpgrade={() =>