spec-kitty-cli 3.1.6__tar.gz → 3.1.8__tar.gz

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/CHANGELOG.md

@@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.8] - 2026-04-29
+
+### Fixed
+
+- Dashboard feature polling now tolerates `/api/features` error or malformed
+  payloads without crashing on an undefined `features` array, so the UI no
+  longer gets stuck on loading when feature scanning fails.
+- OpenCode global command installation now targets OpenCode's config command
+  directory, honoring `OPENCODE_CONFIG_DIR` and `XDG_CONFIG_HOME` before
+  falling back to `~/.config/opencode/commands`.
+
+## [3.1.7] - 2026-04-28
+
+### Fixed
+
+- Compact charter context now preserves charter section anchors, directive IDs,
+  and tactic IDs so follow-on agent prompts keep the project charter rules in
+  LLM context after the bootstrap load.
+- Review claims now enter the canonical `in_review` lane and still recognize
+  legacy review-claim events, avoiding review-loop false blocks.
+- Merge completion now keeps post-merge status transitions stable and avoids
+  duplicate done/approved emissions.
+- `spec-kitty intake` now caps oversized plan files, ignores out-of-repo and
+  symlinked auto-detected plans, and writes mission brief/provenance files
+  atomically.
+- `auth refresh` now treats `HTTP 401` responses with `invalid_grant` or
+  `session_invalid` error codes like `HTTP 400`, and clears locally stored
+  sessions after server-side refresh rejection.
+- Local dashboard mission selectors now sort by mission recency instead of
+  lexical slug order.
+- `agent config list/status/add/sync/remove` now respects global command roots
+  for slash-command agents and avoids recreating retired project-local command
+  directories.
+- Status event readers now ignore non-lane mission events in
+  `status.events.jsonl` while still failing loudly for malformed lane events.
+- Sync shutdown diagnostics are deduplicated within a process and suppressed
+  after successful JSON mission creation.
+
+### Changed
+
+- `spec-kitty-tracker` is pinned to `0.4.3` for the latest tracker-side
+  stability fixes.
+- The local `.python-version` pin now uses `3.13` instead of a patch-specific
+  interpreter version.
+
 ## [3.1.6] - 2026-04-20
 
 ### Fixed

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.1.6
+Version: 3.1.8
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -67,7 +67,7 @@ Requires-Dist: rich>=14.3.3
 Requires-Dist: ruamel-yaml>=0.18.0
 Requires-Dist: spec-kitty-events==3.0.0
 Requires-Dist: spec-kitty-runtime==0.4.3
-Requires-Dist: spec-kitty-tracker==0.4.1
+Requires-Dist: spec-kitty-tracker==0.4.3
 Requires-Dist: toml>=0.10.2
 Requires-Dist: transitions>=0.9.2
 Requires-Dist: truststore>=0.10.4
@@ -199,9 +199,11 @@ graph LR
 
 </div>
 
-**Current stable release line:** `v3.1.x` (current release: `3.1.6` on GitHub Releases and PyPI)
+**Current stable release line:** `v3.1.x` (current release: `3.1.7` on GitHub Releases and PyPI)
 
 **3.1.x highlights:**
+- **Compact charter context now keeps charter anchors in LLM context** — follow-on agent prompts retain charter section anchors plus directive and tactic IDs after bootstrap.
+- **Stability fixes for review, intake, auth, tracker sync, and dashboard selection** — 3.1.7 is a quality hotfix for the stable 3.1 line.
 - **`agent action implement` now honors the bulk-edit acknowledgement override** — false-positive bulk-edit inference warnings no longer block workspace creation when the mission is not actually a bulk edit and the user explicitly acknowledges that.
 - **Maintainer governance now documents the ownership boundary for user customizations** — Spec Kitty's internal charter records that package-owned mutation flows must not clobber user-authored custom commands, custom skills, or project overrides without explicit ownership proof.
 

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/README.md

@@ -101,9 +101,11 @@ graph LR
 
 </div>
 
-**Current stable release line:** `v3.1.x` (current release: `3.1.6` on GitHub Releases and PyPI)
+**Current stable release line:** `v3.1.x` (current release: `3.1.7` on GitHub Releases and PyPI)
 
 **3.1.x highlights:**
+- **Compact charter context now keeps charter anchors in LLM context** — follow-on agent prompts retain charter section anchors plus directive and tactic IDs after bootstrap.
+- **Stability fixes for review, intake, auth, tracker sync, and dashboard selection** — 3.1.7 is a quality hotfix for the stable 3.1 line.
 - **`agent action implement` now honors the bulk-edit acknowledgement override** — false-positive bulk-edit inference warnings no longer block workspace creation when the mission is not actually a bulk edit and the user explicitly acknowledges that.
 - **Maintainer governance now documents the ownership boundary for user customizations** — Spec Kitty's internal charter records that package-owned mutation flows must not clobber user-authored custom commands, custom skills, or project overrides without explicit ownership proof.
 

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.1.6"
+version = "3.1.8"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -62,7 +62,7 @@ dependencies = [
     "psutil>=5.9.0",  # Cross-platform process management for dashboard
     "spec-kitty-events==3.0.0",
     "spec-kitty-runtime==0.4.3",
-    "spec-kitty-tracker==0.4.1",
+    "spec-kitty-tracker==0.4.3",
     "websockets>=12.0",  # WebSocket client for sync protocol
     "toml>=0.10.2",  # Config file parsing
     "filelock>=3.13.0",  # Credential storage locking

spec_kitty_cli-3.1.8/src/charter/_doctrine_paths.py

@@ -0,0 +1,61 @@
+"""Shared DoctrineService project-root candidate resolution.
+
+Both ``src/charter/compiler.py::_default_doctrine_service`` and
+``src/charter/context.py::_build_doctrine_service`` use the same candidate-list
+ordering.  This module is the **single source of truth** for that ordering so
+the two call-sites cannot drift apart.
+
+Candidate ordering (FR-009 / T024 / T025):
+
+1. ``.kittify/doctrine/``   — Phase 3 synthesis target; present only after a
+                              successful ``spec-kitty charter synthesize`` run.
+2. ``src/doctrine/``        — code-local shipped-layer path (legacy 3.x default).
+3. ``doctrine/``            — flat shipped-layer fallback.
+
+Discovery is **conditional on directory presence**: if ``.kittify/doctrine/``
+does not exist the resolver returns the next matching candidate, preserving
+byte-identical behaviour for legacy (pre-synthesis) projects (R-2 mitigation).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Candidate list (ordered: synthesis-aware first, shipped-layer fallbacks after)
+# ---------------------------------------------------------------------------
+
+_PROJECT_ROOT_CANDIDATES: tuple[str, ...] = (
+    ".kittify/doctrine",  # NEW — Phase 3 synthesis target (FR-009)
+    "src/doctrine",  # existing — code-local shipped-layer path
+    "doctrine",  # existing — flat shipped-layer fallback
+)
+
+
+def resolve_project_root(repo_root: Path) -> Path | None:
+    """Return the first existing project-doctrine directory for *repo_root*.
+
+    Returns ``None`` when none of the candidates exist on disk, which means
+    ``DoctrineService`` will be constructed with ``project_root=None`` (shipped
+    layer only — identical to the pre-Phase-3 default).
+
+    The function is intentionally a thin directory-presence check: it does
+    **not** inspect the directory's contents.  An empty ``.kittify/doctrine/``
+    directory is still a valid candidate (the ``DoctrineService`` will simply
+    surface an empty project layer with no shipped-layer impact).
+
+    Args:
+        repo_root: Absolute path to the repository root.
+
+    Returns:
+        The first matching :class:`~pathlib.Path` or ``None``.
+    """
+    for candidate in _PROJECT_ROOT_CANDIDATES:
+        path = repo_root / candidate
+        if path.is_dir():
+            return path
+    return None
+
+
+__all__ = ["resolve_project_root", "_PROJECT_ROOT_CANDIDATES"]

spec_kitty_cli-3.1.8/src/charter/compact.py

@@ -0,0 +1,243 @@
+"""Compact charter view (FR-034, WP07/T041).
+
+Bootstrap mode renders the whole charter governance bundle: paradigms,
+directives, tactics, tools, plus the long-form prose body of each
+section. Compact mode is what we hand to agents on subsequent action
+loads to keep the context window cheap, but until WP07 it dropped the
+*identifiers* — directive IDs, tactic IDs, and section anchors — which
+agents key on. Issue #790 traced bad agent behaviour to that loss.
+
+The contract this module enforces (and the contract test asserts): for
+any charter, the set of directive IDs, tactic IDs, and section anchors
+emitted by ``render_compact_view`` is exactly the set emitted by the
+bootstrap view. Only long-form prose may be elided in compact mode.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from charter._doctrine_paths import resolve_project_root
+from charter.language_scope import infer_repo_languages
+from charter.resolver import GovernanceResolutionError, resolve_governance
+
+
+__all__ = [
+    "CompactView",
+    "extract_section_anchors",
+    "render_compact_view",
+]
+
+NONE_LABEL = "(none)"
+KITTIFY_DIRNAME = ".kittify"
+
+
+@dataclass(frozen=True)
+class CompactView:
+    """Structured payload for the compact charter view.
+
+    Tests treat the four ID/anchor sets as the contract surface.
+    ``text`` is the rendered string suitable for direct inclusion in
+    agent context, and ``token_estimate`` is a coarse character-based
+    proxy used by smoke checks to verify compact stays meaningfully
+    smaller than bootstrap.
+    """
+
+    text: str
+    directive_ids: tuple[str, ...] = field(default_factory=tuple)
+    tactic_ids: tuple[str, ...] = field(default_factory=tuple)
+    section_anchors: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def token_estimate(self) -> int:
+        """Rough proxy for token count (4 chars/token heuristic)."""
+        return max(1, len(self.text) // 4)
+
+
+def extract_section_anchors(charter_text: str) -> list[str]:
+    """Return ordered, de-duplicated section anchor strings.
+
+    A "section anchor" is the heading text from any ``#``-style
+    Markdown heading. We preserve insertion order so anchors line up
+    with the bootstrap reading order, and deduplicate so repeated
+    headings (rare, but possible) only contribute once to the contract.
+    """
+    seen: set[str] = set()
+    anchors: list[str] = []
+    for line in charter_text.splitlines():
+        anchor = _extract_markdown_heading(line)
+        if not anchor:
+            continue
+        if anchor in seen:
+            continue
+        seen.add(anchor)
+        anchors.append(anchor)
+    return anchors
+
+
+def _extract_markdown_heading(line: str) -> str | None:
+    """Return heading text from an ATX Markdown heading line."""
+    stripped = line.strip()
+    if not stripped.startswith("#"):
+        return None
+
+    level = 0
+    while level < len(stripped) and stripped[level] == "#":
+        level += 1
+    if level == 0 or level > 6:
+        return None
+    if level == len(stripped) or stripped[level] != " ":
+        return None
+
+    anchor = stripped[level + 1 :].strip()
+    return anchor or None
+
+
+def render_compact_view(
+    repo_root: Path,
+    *,
+    directive_ids: Iterable[str] = (),
+    tactic_ids: Iterable[str] = (),
+    section_anchors: Iterable[str] | None = None,
+    charter_text: str | None = None,
+) -> CompactView:
+    """Render the compact governance block with IDs + anchors preserved.
+
+    Args:
+        repo_root: The mission repo root used to resolve governance.
+        directive_ids: Directive IDs the bootstrap view would surface.
+            Each ID is emitted verbatim in the compact output.
+        tactic_ids: Tactic IDs the bootstrap view would surface.
+        section_anchors: Optional pre-computed anchor list. When omitted
+            the helper extracts anchors from ``charter_text`` (or, if
+            both are omitted, from ``<repo_root>/.kittify/charter/charter.md``
+            when present).
+        charter_text: Optional charter body text used for anchor
+            extraction; convenient for tests.
+
+    Returns:
+        :class:`CompactView` carrying the rendered text and the four
+        ID/anchor tuples that form the contract surface.
+    """
+    directive_tuple = tuple(dict.fromkeys(directive_ids))
+    tactic_tuple = tuple(dict.fromkeys(tactic_ids))
+
+    if section_anchors is not None:
+        anchor_tuple = tuple(dict.fromkeys(section_anchors))
+    else:
+        if charter_text is None:
+            charter_path = repo_root / KITTIFY_DIRNAME / "charter" / "charter.md"
+            charter_text = ""
+            if charter_path.exists():
+                try:
+                    charter_text = charter_path.read_text(encoding="utf-8")
+                except OSError:
+                    charter_text = ""
+        anchor_tuple = tuple(extract_section_anchors(charter_text))
+
+    text = _render_text(repo_root, directive_tuple, tactic_tuple, anchor_tuple)
+
+    return CompactView(
+        text=text,
+        directive_ids=directive_tuple,
+        tactic_ids=tactic_tuple,
+        section_anchors=anchor_tuple,
+    )
+
+
+def _render_text(
+    repo_root: Path,
+    directive_ids: tuple[str, ...],
+    tactic_ids: tuple[str, ...],
+    section_anchors: tuple[str, ...],
+) -> str:
+    """Render the human-readable compact governance block.
+
+    The format is intentionally line-oriented and stable so downstream
+    diffs in agent context stay reviewable. Long-form prose is replaced
+    by ID lists and an anchor index. When governance cannot be resolved
+    (e.g., the repo lacks ``.kittify`` config) the renderer still emits
+    every supplied directive ID, tactic ID, and section anchor — the
+    FR-034 contract is "no IDs are silently dropped", so a degraded
+    governance block must not erase the IDs the caller already knows.
+    """
+    (
+        template_set,
+        paradigms,
+        tools,
+        diagnostics,
+        resolver_directives,
+    ) = _resolve_governance_summary(repo_root)
+
+    merged_directive_ids = tuple(dict.fromkeys(list(directive_ids) + resolver_directives))
+
+    lines: list[str] = [
+        "Governance:",
+        f"  - Template set: {template_set}",
+        f"  - Paradigms: {paradigms}",
+        f"  - Tools: {tools}",
+    ]
+
+    _append_section(lines, "Directive IDs:", merged_directive_ids)
+    _append_section(lines, "Tactic IDs:", tactic_ids)
+    _append_section(lines, "Section Anchors:", section_anchors)
+
+    if diagnostics:
+        lines.append(f"  - Diagnostics: {' | '.join(diagnostics)}")
+
+    # Reference repo languages / project root only as a footnote so the
+    # compact view stays one-screen even on big charters.
+    try:
+        languages = infer_repo_languages(repo_root)
+        if languages:
+            lines.append(f"  - Languages: {', '.join(sorted(languages))}")
+    except Exception:  # pragma: no cover - defensive
+        pass
+
+    try:
+        project_root = resolve_project_root(repo_root)
+        if project_root != repo_root:
+            lines.append(f"  - Project root: {project_root}")
+    except Exception:  # pragma: no cover - defensive
+        pass
+
+    return "\n".join(lines)
+
+
+def _resolve_governance_summary(
+    repo_root: Path,
+) -> tuple[str, str, str, list[str], list[str]]:
+    template_set = NONE_LABEL
+    paradigms = NONE_LABEL
+    tools = NONE_LABEL
+    diagnostics: list[str] = []
+    resolver_directives: list[str] = []
+
+    try:
+        resolution = resolve_governance(repo_root)
+    except GovernanceResolutionError as exc:
+        diagnostics.append(f"governance unresolved ({exc})")
+        return template_set, paradigms, tools, diagnostics, resolver_directives
+    except Exception as exc:  # pragma: no cover - defensive degrade
+        diagnostics.append(f"governance unavailable ({exc})")
+        return template_set, paradigms, tools, diagnostics, resolver_directives
+
+    if resolution.paradigms:
+        paradigms = ", ".join(resolution.paradigms)
+    if resolution.tools:
+        tools = ", ".join(resolution.tools)
+    diagnostics.extend(list(resolution.diagnostics))
+    resolver_directives = list(resolution.directives)
+    return resolution.template_set, paradigms, tools, diagnostics, resolver_directives
+
+
+def _append_section(lines: list[str], title: str, values: Iterable[str]) -> None:
+    lines.append(title)
+    entries = list(values)
+    if not entries:
+        lines.append(f"  - {NONE_LABEL}")
+        return
+    for entry in entries:
+        lines.append(f"  - {entry}")

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/src/charter/context.py

@@ -12,7 +12,6 @@ from ruamel.yaml import YAML
 from ruamel.yaml.error import YAMLError
 
 from charter.language_scope import infer_repo_languages
-from charter.resolver import GovernanceResolutionError, resolve_governance
 from kernel.atomic import atomic_write
 
 
@@ -288,28 +287,29 @@ def _render_bootstrap(charter_path: Path, summary: list[str], references: list[d
     return "\n".join(lines)
 
 
-def _render_compact_governance(repo_root: Path) -> str:
-    try:
-        resolution = resolve_governance(repo_root)
-    except GovernanceResolutionError as exc:
-        return f"Governance: unresolved ({exc})"
-    except Exception as exc:
-        return f"Governance: unavailable ({exc})"
-
-    paradigms = ", ".join(resolution.paradigms) if resolution.paradigms else "(none)"
-    directives = ", ".join(resolution.directives) if resolution.directives else "(none)"
-    tools = ", ".join(resolution.tools) if resolution.tools else "(none)"
-
-    lines = [
-        "Governance:",
-        f"  - Template set: {resolution.template_set}",
-        f"  - Paradigms: {paradigms}",
-        f"  - Directives: {directives}",
-        f"  - Tools: {tools}",
-    ]
-    if resolution.diagnostics:
-        lines.append(f"  - Diagnostics: {' | '.join(resolution.diagnostics)}")
-    return "\n".join(lines)
+def _render_compact_governance(
+    repo_root: Path,
+    *,
+    directive_ids: list[str] | None = None,
+    tactic_ids: list[str] | None = None,
+) -> str:
+    """Render the compact governance block (FR-034).
+
+    Compact mode preserves every directive ID, tactic ID, and section
+    anchor that bootstrap mode would emit; only the long-form prose
+    body is collapsed. ``directive_ids`` / ``tactic_ids`` are optional
+    bootstrap-side lists that the caller has already resolved; when
+    omitted the compact view falls back to the resolver's directive
+    canon and charter heading anchors.
+    """
+    from charter.compact import render_compact_view
+
+    view = render_compact_view(
+        repo_root,
+        directive_ids=directive_ids or (),
+        tactic_ids=tactic_ids or (),
+    )
+    return view.text
 
 
 def _extract_policy_summary(content: str) -> list[str]:
@@ -391,9 +391,7 @@ def _write_state(path: Path, state: dict[str, object]) -> None:
     atomic_write(path, json.dumps(state, indent=2, sort_keys=True), mkdir=True)
 
 
-def _mark_action_loaded(
-    state: dict[str, object], state_path: Path, action: str
-) -> None:
+def _mark_action_loaded(state: dict[str, object], state_path: Path, action: str) -> None:
     """Persist first-load timestamp for *action* into context-state.json."""
     actions_obj = state.setdefault("actions", {})
     if not isinstance(actions_obj, dict):
@@ -469,7 +467,7 @@ def build_charter_context(
             action=normalized,
             mode="compact",
             first_load=False,
-            text=_render_compact_governance(repo_root),
+            text=_render_compact_governance(canonical_root),
             references_count=0,
             depth=effective_depth,
         )
@@ -505,7 +503,7 @@ def build_charter_context(
             action=normalized,
             mode="compact",
             first_load=first_load,
-            text=_render_compact_governance(repo_root),
+            text=_render_compact_governance(canonical_root),
             references_count=0,
             depth=effective_depth,
         )
@@ -525,9 +523,7 @@ def build_charter_context(
     mission = template_set.removesuffix("-default")
 
     # Project directive selection filtering (mirrors legacy behavior)
-    project_directives: set[str] = {
-        _normalize_directive_id(d) for d in governance.doctrine.selected_directives
-    }
+    project_directives: set[str] = {_normalize_directive_id(d) for d in governance.doctrine.selected_directives}
 
     # -- 3. Query the DRG -----------------------------------------------------
     action_urn = f"action:{mission}/{normalized}"
@@ -538,9 +534,7 @@ def build_charter_context(
         repo_root / "src" / "doctrine",
         repo_root / "doctrine",
     ]
-    project_root = next(
-        (p for p in project_root_candidates if p.is_dir()), None
-    )
+    project_root = next((p for p in project_root_candidates if p.is_dir()), None)
     svc = DoctrineService(shipped_root=doctrine_root, project_root=project_root)
 
     # Classify resolved URNs by node kind, applying directive selection

{spec_kitty_cli-3.1.6 → spec_kitty_cli-3.1.8}/src/specify_cli/auth/flows/refresh.py

@@ -13,12 +13,13 @@ is absent. The CLI NEVER hardcodes a TTL.
 
 Error semantics (feature 080, spec §7.2):
 
-- SaaS returns ``400 invalid_grant`` → :class:`RefreshTokenExpiredError`.
-  The refresh token is invalid or expired; the user must re-run
-  ``spec-kitty auth login``.
-- SaaS returns ``400 session_invalid`` → :class:`SessionInvalidError`. The
-  server has administratively invalidated this session; ``TokenManager``
-  clears local state and the user must re-login.
+- SaaS returns ``400`` or ``401`` with ``invalid_grant`` →
+  :class:`RefreshTokenExpiredError`. The refresh token is invalid or expired;
+  the user must re-run ``spec-kitty auth login``.
+- SaaS returns ``400`` or ``401`` with ``session_invalid`` →
+  :class:`SessionInvalidError`. The server has administratively invalidated
+  this session; ``TokenManager`` clears local state and the user must
+  re-login.
 - Any other HTTP error → :class:`TokenRefreshError`.
 - Transport-level failures → :class:`NetworkError`.
 """
@@ -64,9 +65,10 @@ class TokenRefreshFlow:
 
         Raises:
             RefreshTokenExpiredError: The SaaS rejected the refresh token
-                (``400 invalid_grant``). The user must re-run ``auth login``.
+                (``400/401 invalid_grant``). The user must re-run
+                ``auth login``.
             SessionInvalidError: The SaaS reports the session has been
-                invalidated server-side (``400 session_invalid``).
+                invalidated server-side (``400/401 session_invalid``).
             TokenRefreshError: Any other HTTP failure during refresh.
             NetworkError: Transport-level failure (DNS, connect, timeout).
         """
@@ -88,36 +90,23 @@ class TokenRefreshFlow:
             try:
                 tokens = response.json()
             except ValueError as exc:
-                raise TokenRefreshError(
-                    f"Refresh response was not JSON: {exc}"
-                ) from exc
+                raise TokenRefreshError(f"Refresh response was not JSON: {exc}") from exc
             return self._update_session(session, tokens)
 
-        if response.status_code == 400:
+        if response.status_code in {400, 401}:
             try:
                 body = response.json()
             except ValueError:
                 body = {}
             error = body.get("error", "")
             if error == "invalid_grant":
-                raise RefreshTokenExpiredError(
-                    "Refresh token is invalid or expired. "
-                    "Run `spec-kitty auth login` again."
-                )
+                raise RefreshTokenExpiredError("Refresh token is invalid or expired. Run `spec-kitty auth login` again.")
             if error == "session_invalid":
-                raise SessionInvalidError(
-                    "Session has been invalidated server-side. "
-                    "Run `spec-kitty auth login` again."
-                )
-
-        raise TokenRefreshError(
-            f"Token refresh failed: HTTP {response.status_code} - "
-            f"{response.text[:500]}"
-        )
+                raise SessionInvalidError("Session has been invalidated server-side. Run `spec-kitty auth login` again.")
+
+        raise TokenRefreshError(f"Token refresh failed: HTTP {response.status_code} - {response.text[:500]}")
 
-    def _update_session(
-        self, session: StoredSession, tokens: dict[str, Any]
-    ) -> StoredSession:
+    def _update_session(self, session: StoredSession, tokens: dict[str, Any]) -> StoredSession:
         """Build an updated session from a refresh response.
 
         Per C-012 (LANDED 2026-04-09), ``refresh_token_expires_at`` is read
@@ -135,9 +124,7 @@ class TokenRefreshFlow:
         try:
             new_access = tokens["access_token"]
         except KeyError as exc:
-            raise TokenRefreshError(
-                "Refresh response missing 'access_token'"
-            ) from exc
+            raise TokenRefreshError("Refresh response missing 'access_token'") from exc
 
         # Refresh token may rotate; keep the old one if the server doesn't rotate.
         new_refresh = tokens.get("refresh_token", session.refresh_token)
@@ -145,9 +132,7 @@ class TokenRefreshFlow:
         try:
             expires_in = int(tokens.get("expires_in", 3600))
         except (TypeError, ValueError) as exc:
-            raise TokenRefreshError(
-                f"Refresh response has invalid 'expires_in': {exc}"
-            ) from exc
+            raise TokenRefreshError(f"Refresh response has invalid 'expires_in': {exc}") from exc
 
         refresh_token_expires_at = self._resolve_refresh_expiry(tokens, now, session)
 
@@ -190,9 +175,7 @@ class TokenRefreshFlow:
             try:
                 return now + timedelta(seconds=int(relative))
             except (TypeError, ValueError):
-                log.warning(
-                    "refresh_token_expires_in was not an int: %r", relative
-                )
+                log.warning("refresh_token_expires_in was not an int: %r", relative)
 
         # Last-resort fallback: preserve the previous session's expiry so
         # we never produce a session with an indeterminate refresh expiry