spec-kitty-cli 3.2.0a6__tar.gz → 3.2.0a7__tar.gz

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/CHANGELOG.md

@@ -17,6 +17,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [3.2.0a7] - 2026-05-01
+
+3.2.0a7 is a focused prerelease that bounds WebSocket sync startup and
+shutdown behavior. Short-lived agent commands now fail over to batch sync
+instead of hanging indefinitely when a local sync socket accepts the
+connection but never emits the initial snapshot.
+
+### Fixed
+
+- WebSocket sync startup now has bounded open, initial snapshot, and close
+  deadlines so `spec-kitty agent mission setup-plan` and other short-lived
+  commands degrade to batch sync instead of blocking forever on a stalled
+  sync socket (#936).
+
+### Internal
+
+- Added regression coverage for a WebSocket connection that never sends the
+  initial snapshot and for shutdown paths where the close handshake stalls.
+- Aligned existing Bandit suppressions in touched sync/readiness callsites so
+  local and CI security scans recognize the intended safe dynamic SQL and
+  localhost URL patterns.
+
 ## [3.2.0a6] - 2026-04-30
 
 3.2.0a6 is a prerelease hardening sweep that restores the documented
@@ -1345,6 +1367,7 @@ All fixes include comprehensive test coverage (54+ new tests) and maintain backw
   - **Errors handled**: TimeoutExpired (>10s git commands), general exceptions with warning
 
 ### Added
+
 - Git commit validation for "done" status transitions - prevents completing WPs with uncommitted changes
 - Empty branch detection in merge-base creation - warns when dependencies have no commits
 - Git commit workflow section in documentation mission template (consistency with software-dev/research)
@@ -1352,11 +1375,13 @@ All fixes include comprehensive test coverage (54+ new tests) and maintain backw
 - Migration to add commit workflow section to existing projects (`m_0_13_5_add_commit_workflow_to_templates.py`)
 
 ### Changed
+
 - `move-task --to done` now validates git status (same checks as "for_review")
 - Use `--force` flag to bypass validation (not recommended)
 - Warning messages in multi-parent merge now output to stderr instead of stdout (preserves JSON output integrity)
 
 ### Fixed (Non-Critical)
+
 - WP agents can no longer mark tasks as "done" without committing implementation files
 - Multi-parent merge-bases no longer silently accept empty dependency branches
 - Documentation mission now instructs agents to commit work before review
@@ -1418,7 +1443,7 @@ All fixes include comprehensive test coverage (54+ new tests) and maintain backw
   - Unit tests: `test_implement_validation.py` (11 tests)
   - Integration tests: `test_agent_command_wrappers.py` (11 tests)
 - Added `TestMigrationRegistryCompleteness` test (prevents 0.13.2-style release blocker)
-  - Verifies all m_*.py migration files are imported in __init__.py
+  - Verifies all `m_*.py` migration files are imported in `__init__.py`
   - Prevents silent bugs where migrations exist but never run
 - Added integration tests for merge with untracked branches
 - Added unit tests for `has_tracking_branch()` function
@@ -1840,9 +1865,9 @@ The migration will remove mission-specific constitution directories:
   - `signal.SIGKILL` and `signal.SIGTERM` don't exist on Windows
   - Added `psutil>=5.9.0` dependency for cross-platform process management
   - Refactored `src/specify_cli/dashboard/lifecycle.py`:
-    * `os.kill(pid, 0)` → `psutil.Process(pid).is_running()`
-    * `signal.SIGKILL` → `psutil.Process(pid).kill()` (6 locations)
-    * `signal.SIGTERM` → `psutil.Process(pid).terminate()` with timeout
+    - `os.kill(pid, 0)` → `psutil.Process(pid).is_running()`
+    - `signal.SIGKILL` → `psutil.Process(pid).kill()` (6 locations)
+    - `signal.SIGTERM` → `psutil.Process(pid).terminate()` with timeout
   - Added proper exception handling (NoSuchProcess, AccessDenied, TimeoutExpired)
   - Dashboard now starts, serves HTML, and stops cleanly on Windows 10/11
   - All 41 dashboard tests passing

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0a6
+Version: 3.2.0a7
 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
@@ -143,7 +143,7 @@ Spec Kitty addresses this with repository-native artifacts, work package workflo
 
 ---
 
-## 🚀 What You Get on `main` (`3.2.0a6`)
+## 🚀 What You Get on `main` (`3.2.0a7`)
 
 | Capability | What Spec Kitty provides |
 |------------|--------------------------|
@@ -205,7 +205,7 @@ graph LR
 
 **Current stable release line:** `v3.1.x` (current stable release: `3.1.8` on GitHub Releases and PyPI)
 
-**Current `main` development version:** `3.2.0a6`
+**Current `main` development version:** `3.2.0a7`
 
 **Current `main` highlights:**
 - **Brief-first and ticket-first intake** — `spec-kitty intake` ingests external plans into `.kittify/mission-brief.md`, and `spec-kitty mission create --from-ticket <provider:KEY>` seeds tracker context before `/spec-kitty.specify`
@@ -228,18 +228,18 @@ graph LR
 
 ## 📌 Release Channels
 
-Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a6` prerelease/dev line.
+Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a7` prerelease/dev line.
 The former `1.x` line is deprecated and lives on `1.x-maintenance` for maintenance-only fixes.
 
 | Source | Version | Status | Install |
 |--------|---------|--------|---------|
 | **PyPI / GitHub Releases** | **3.1.8** | Current stable line | `pip install spec-kitty-cli` |
-| **main** | **3.2.0a6** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
+| **main** | **3.2.0a7** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
 | **1.x-maintenance** | **1.x** | Deprecated, maintenance-only | Install from a pinned maintenance tag or source checkout |
 
 **For users:** install the stable line from PyPI with `pip install spec-kitty-cli`.
 **For testers following `main`:** use a source checkout or published prerelease builds to get the intake, profile-invocation, hosted tracker-read, and Teamspace-routing work that is newer than stable `3.1.x`.
-After `3.2.0a6` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a6"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
+After `3.2.0a7` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a7"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
 **For existing 3.0.x users:** upgrade to `3.1.x` and run `spec-kitty upgrade` in each project — the charter rename, mission identity, and prompt-neutrality migrations remain automatic.
 **For existing 1.x or 2.x users:** migrate to `3.1.x`; `1.x-maintenance` is maintenance-only and will no longer publish new PyPI releases.
 

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/README.md

@@ -45,7 +45,7 @@ Spec Kitty addresses this with repository-native artifacts, work package workflo
 
 ---
 
-## 🚀 What You Get on `main` (`3.2.0a6`)
+## 🚀 What You Get on `main` (`3.2.0a7`)
 
 | Capability | What Spec Kitty provides |
 |------------|--------------------------|
@@ -107,7 +107,7 @@ graph LR
 
 **Current stable release line:** `v3.1.x` (current stable release: `3.1.8` on GitHub Releases and PyPI)
 
-**Current `main` development version:** `3.2.0a6`
+**Current `main` development version:** `3.2.0a7`
 
 **Current `main` highlights:**
 - **Brief-first and ticket-first intake** — `spec-kitty intake` ingests external plans into `.kittify/mission-brief.md`, and `spec-kitty mission create --from-ticket <provider:KEY>` seeds tracker context before `/spec-kitty.specify`
@@ -130,18 +130,18 @@ graph LR
 
 ## 📌 Release Channels
 
-Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a6` prerelease/dev line.
+Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a7` prerelease/dev line.
 The former `1.x` line is deprecated and lives on `1.x-maintenance` for maintenance-only fixes.
 
 | Source | Version | Status | Install |
 |--------|---------|--------|---------|
 | **PyPI / GitHub Releases** | **3.1.8** | Current stable line | `pip install spec-kitty-cli` |
-| **main** | **3.2.0a6** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
+| **main** | **3.2.0a7** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
 | **1.x-maintenance** | **1.x** | Deprecated, maintenance-only | Install from a pinned maintenance tag or source checkout |
 
 **For users:** install the stable line from PyPI with `pip install spec-kitty-cli`.
 **For testers following `main`:** use a source checkout or published prerelease builds to get the intake, profile-invocation, hosted tracker-read, and Teamspace-routing work that is newer than stable `3.1.x`.
-After `3.2.0a6` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a6"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
+After `3.2.0a7` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a7"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
 **For existing 3.0.x users:** upgrade to `3.1.x` and run `spec-kitty upgrade` in each project — the charter rename, mission identity, and prompt-neutrality migrations remain automatic.
 **For existing 1.x or 2.x users:** migrate to `3.1.x`; `1.x-maintenance` is maintenance-only and will no longer publish new PyPI releases.
 

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0a6"
+version = "3.2.0a7"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/src/specify_cli/saas/readiness.py

@@ -182,7 +182,7 @@ def _probe_reachability(server_url: str, timeout_s: float = 2.0) -> bool:
     """
     try:
         req = urllib.request.Request(server_url, method="HEAD")
-        with urllib.request.urlopen(req, timeout=timeout_s):  # noqa: S310
+        with urllib.request.urlopen(req, timeout=timeout_s):  # noqa: S310  # nosec B310
             return True
     except Exception:  # noqa: BLE001
         return False

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/src/specify_cli/sync/client.py

@@ -10,6 +10,7 @@ state directly.
 import asyncio
 import json
 import random
+import sys
 from contextlib import suppress
 from collections.abc import Callable
 from typing import Any
@@ -63,6 +64,9 @@ class WebSocketClient:
     BASE_DELAY_SECONDS = 0.5  # 500ms
     MAX_DELAY_SECONDS = 30.0
     JITTER_RANGE = 1.0  # +/- 1 second
+    OPEN_TIMEOUT_SECONDS = 5.0
+    INITIAL_SNAPSHOT_TIMEOUT_SECONDS = 5.0
+    CLOSE_TIMEOUT_SECONDS = 2.0
 
     def __init__(
         self,
@@ -166,12 +170,17 @@ class WebSocketClient:
                 uri,
                 ping_interval=None,  # We handle heartbeat manually
                 ping_timeout=None,
+                open_timeout=self.OPEN_TIMEOUT_SECONDS,
+                close_timeout=self.CLOSE_TIMEOUT_SECONDS,
             )
             self.connected = True
             self.status = ConnectionStatus.CONNECTED
 
             # Receive initial snapshot
-            await self._receive_snapshot()
+            await asyncio.wait_for(
+                self._receive_snapshot(),
+                timeout=self.INITIAL_SNAPSHOT_TIMEOUT_SECONDS,
+            )
 
             # Start message listener
             self._listen_task = asyncio.create_task(self._listen())
@@ -187,7 +196,17 @@ class WebSocketClient:
             self.connected = False
             self.status = ConnectionStatus.OFFLINE
             raise
+        except TimeoutError:
+            await self._close_after_failed_connect()
+            print(
+                "Warning: WebSocket connection timed out; events will be queued for batch sync.",
+                file=sys.stderr,
+            )
+            self.connected = False
+            self.status = ConnectionStatus.BATCH_MODE
+            raise
         except Exception as e:
+            await self._close_after_failed_connect()
             self.connected = False
             self.status = ConnectionStatus.OFFLINE
             print(f"❌ Connection failed: {e}")
@@ -195,6 +214,7 @@ class WebSocketClient:
 
     async def disconnect(self):
         """Close WebSocket connection"""
+        had_ws = self.ws is not None
         if self._listen_task:
             self._listen_task.cancel()
             with suppress(asyncio.CancelledError):
@@ -202,12 +222,29 @@ class WebSocketClient:
             self._listen_task = None
 
         if self.ws:
-            await self.ws.close()
-            self.ws = None
-            self.connected = False
-            self.status = ConnectionStatus.OFFLINE
+            with suppress(Exception):
+                await asyncio.wait_for(
+                    self.ws.close(),
+                    timeout=self.CLOSE_TIMEOUT_SECONDS,
+                )
+        self.ws = None
+        self.connected = False
+        self.status = ConnectionStatus.OFFLINE
+        if had_ws:
             print("Disconnected from sync server")
 
+    async def _close_after_failed_connect(self) -> None:
+        """Best-effort cleanup when connect fails after a socket was opened."""
+        ws = self.ws
+        self.ws = None
+        if ws is None:
+            return
+        with suppress(Exception):
+            await asyncio.wait_for(
+                ws.close(),
+                timeout=self.CLOSE_TIMEOUT_SECONDS,
+            )
+
     async def reconnect(self) -> bool:
         """
         Reconnect with exponential backoff.

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/src/specify_cli/sync/orphan_sweep.py

@@ -110,8 +110,7 @@ def _probe_health(port: int) -> dict[str, Any] | None:
     """Issue ``GET /api/health`` and return the parsed JSON dict, or ``None`` on any failure."""
     url = f"http://127.0.0.1:{port}/api/health"
     try:
-        # nosec B310 — URL is always 127.0.0.1 in the reserved daemon range.
-        with urllib.request.urlopen(url, timeout=_HEALTH_PROBE_TIMEOUT_S) as response:
+        with urllib.request.urlopen(url, timeout=_HEALTH_PROBE_TIMEOUT_S) as response:  # nosec B310 - URL is always 127.0.0.1 in the reserved daemon range.
             if response.status != 200:
                 return None
             payload = response.read()
@@ -233,8 +232,7 @@ def _http_shutdown_no_token(port: int) -> None:
         method="POST",
     )
     try:
-        # nosec B310 — request URL is 127.0.0.1 in the reserved daemon range.
-        with urllib.request.urlopen(request, timeout=1.0):
+        with urllib.request.urlopen(request, timeout=1.0):  # nosec B310 - request URL is 127.0.0.1 in the reserved daemon range.
             return
     except Exception:
         return

{spec_kitty_cli-3.2.0a6 → spec_kitty_cli-3.2.0a7}/src/specify_cli/sync/queue.py

@@ -736,7 +736,7 @@ class OfflineQueue:
         try:
             placeholders = ",".join("?" * len(event_ids))
             conn.execute(
-                f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only
+                f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only  # nosec B608
                 event_ids,
             )
             conn.commit()
@@ -757,7 +757,7 @@ class OfflineQueue:
         try:
             placeholders = ",".join("?" * len(event_ids))
             conn.execute(
-                f"UPDATE queue SET retry_count = retry_count + 1 WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only
+                f"UPDATE queue SET retry_count = retry_count + 1 WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only  # nosec B608
                 event_ids,
             )
             conn.commit()
@@ -814,7 +814,7 @@ class OfflineQueue:
 
             placeholders = ",".join("?" * len(matching_ids))
             conn.execute(
-                f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only
+                f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only  # nosec B608
                 matching_ids,
             )
             conn.commit()
@@ -846,13 +846,13 @@ class OfflineQueue:
             if synced_or_duplicate:
                 placeholders = ",".join("?" * len(synced_or_duplicate))
                 conn.execute(
-                    f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only
+                    f"DELETE FROM queue WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only  # nosec B608
                     synced_or_duplicate,
                 )
             if rejected:
                 placeholders = ",".join("?" * len(rejected))
                 conn.execute(
-                    f"UPDATE queue SET retry_count = retry_count + 1 WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only
+                    f"UPDATE queue SET retry_count = retry_count + 1 WHERE event_id IN ({placeholders})",  # noqa: S608 - placeholders are count-derived only  # nosec B608
                     rejected,
                 )
             conn.commit()