@opengsd/gsd-pi 1.4.0 → 1.5.0

package/integrations/hermes/__init__.py

@@ -0,0 +1,31 @@
+"""open-gsd-hermes — Hermes Agent plugin directory-loader bridge."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_package() -> ModuleType:
+    package_dir = Path(__file__).resolve().parent / "open_gsd_hermes"
+    init_file = package_dir / "__init__.py"
+    spec = importlib.util.spec_from_file_location(
+        "open_gsd_hermes",
+        init_file,
+        submodule_search_locations=[str(package_dir)],
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load open_gsd_hermes from {init_file}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["open_gsd_hermes"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+_package = _load_package()
+register = _package.register
+
+__all__ = ["register"]

package/integrations/hermes/docs/issue-1162-grilling.md

@@ -0,0 +1,197 @@
+# Issue #1162 — Grilling summary: `/gsd new-milestone` via Hermes
+
+Source: `grill-with-docs` + `grilling` + `domain-modeling` skills on issue #1162.
+This is the shared understanding the interview reached — the design tree walked
+branch-by-branch with a decision at each node. Implementation should conform to
+this; deviations should re-open the corresponding question, not silently diverge.
+
+Glossary for every term below lives in [`../CONTEXT.md`](../CONTEXT.md).
+
+---
+
+## The one-line design
+
+Add a `/gsd new-milestone <spec>` slash command that spawns
+`gsd headless new-milestone` as a **plugin-owned subprocess**, fires-and-forgets
+an ack, drives lifecycle (blocker/terminal) notifications from the subprocess's
+stream-json stdout, and hands execution off to the **existing, untouched**
+`/gsd auto` path. No `--auto` chaining, no new MCP tool, no TS-side changes.
+
+---
+
+## Decision tree (Q1–Q9)
+
+### Q1 — Mechanism & transport → **(A) Slash command → CLI subprocess**
+- New `_cmd_new_milestone` in `GsdCommandRouter`. Shells out to
+  `gsd headless new-milestone --context-text <spec>`.
+- **Not** a Hermes skill (B), **not** a new MCP `gsd_create_milestone` tool (C).
+- Rationale: the plugin already has a proven direct-CLI pattern (`progress()`
+  calls `gsd read progress --json`); `new-milestone` is even more naturally a
+  CLI call (it bootstraps `.gsd/`, has a 10-min timeout, manages its own RPC
+  child). An MCP tool would re-implement what the CLI already does, and the
+  upstream lease-layer co-run issue (CHANGELOG:509, open) makes advertising
+  `gsd_create_milestone` over MCP actively unsafe to every MCP client.
+- A later Hermes skill (B) can wrap the same client method with zero rework.
+
+### Q2 — Co-run safety gate → **(A) Local supervisor state only**
+- Reject if `SupervisorContext.state in (RUNNING, BLOCKED)` before spawning.
+- **Not** a server-side cross-binding check (B). Documented limitation: a
+  session started by *another* plugin instance / a headless run outside this
+  plugin is invisible to the local guard; the CLI's own lease check is the
+  backstop.
+- Rationale: the plugin can only authoritatively own its own state; a
+  server-side "is anything running?" check is itself racy and adds a new query
+  path to design and test.
+
+### Q3 — Run model → **(A) Fire-and-track via the existing async-push model**
+- Return "🚀 Milestone creation started (session X)" immediately; push
+  blocker/terminal notifications from a background stream-reader.
+- **Not** a synchronous blocking call (rejected after discovering the plugin is
+  fundamentally async-push — `_cmd_auto` already works this way; the target
+  chat platforms don't hold request/response open for minutes).
+- *(Note: "reuse `SupervisorFsm` unchanged" was initially proposed under this
+  label but does NOT work — see A1 below.)*
+
+### Q3 follow-up — How to drive the fire-and-track → **(A1) Client-owned subprocess, direct stream→notification**
+- `GsdMcpClient` spawns `gsd headless new-milestone --output-format stream-json`
+  on a background thread, reads stdout line-by-line, captures
+  `init_result.sessionId`, and on terminal/blocker events calls
+  `NotificationService` directly.
+- `SupervisorContext` is **shared state** (written by the stream-reader, read by
+  `/gsd status`, `/gsd cancel`, the co-run gate); the `SupervisorFsm` poll loop
+  is **not** reused for the milestone path (its `_tick` calls `gsd_status`,
+  which can't see our subprocess).
+- Rationale: the stream *is* the lifecycle signal; polling would be a lossy
+  proxy for events we already get deterministically. Reuses
+  `NotificationService` and `SupervisorContext` unchanged.
+
+### Q4 — Cancellation → **(A) Local PID ownership + direct SIGTERM**
+- `GsdMcpClient` holds the `subprocess.Popen` handle; `cancel_milestone()` calls
+  `proc.terminate()` directly. `_cmd_cancel` routes to it when a milestone proc
+  is active.
+- **Not** a new `.gsd/milestone.lock` pid file for the MCP backstop (B) — that
+  crosses the Python/TS boundary and inverts ownership. **Not** "no cancel during
+  planning" (C) — a stuck planning run needs an escape hatch.
+- Discovered: MCP `cancelSessionByDir`'s `auto.lock` pid backstop does NOT find
+  our planning subprocess (no `auto.lock` exists during planning — it's an
+  auto-loop concept). So local ownership is required, not optional.
+- Plus explicit supervisor stop on cancel (immediate confirmation, don't wait
+  for next poll tick).
+
+### Q5 — Scope: `--auto` (chained execution)? → **No. Planning-only.**
+- The plugin creates the milestone and hands off; execution is `/gsd auto`'s job.
+- `/gsd auto` already has a robust path (MCP `gsd_execute` → self-healing poll
+  supervisor). Chaining `--auto` would duplicate that with a stateful
+  stream-reader over hours (fragile) instead of the proven poll loop.
+- **Boundary clarification:** this plugin (`gsd-pi/integrations/hermes/`) is the
+  chat gateway. One-shot `new-milestone --auto` is gsd-core's terminal surface,
+  not the gateway's.
+- `/gsd new-milestone --auto` is **rejected at the command level** with a message
+  pointing to the two-step flow.
+
+### Q6 — Input shape → **Bare positional, with `--file` escape**
+- `/gsd new-milestone <spec text>` → `--context-text` (matches `/gsd reply`).
+- `/gsd new-milestone --file <path>` → `--context <file>` (explicit opt-in).
+- **Not** auto-detect path-vs-text (heuristic misroutes on collision — rule #5).
+- **Not** `--description "..."` flag form (issue's example used it, but the bare
+  positional matches the sibling command users already know).
+
+### Q7 — Output → **(A) Bounded summary via `gsd_query` at completion, with (B) as graceful fallback**
+- Immediate ack: "🚀 Milestone creation started for `<project>`."
+- Completion push: bounded summary — milestone id, slice count, task count,
+  one-line next step ("Run `/gsd auto` to start."). Built from
+  `gsd_query {projectDir, query: "milestones"}` after exit-0.
+- Fallback: if the query comes back empty/missing after exit-0, degrade to
+  "✅ Milestone created. Run `/gsd status` for details."
+- **Trust exit-0; no defensive re-querying.** If exit-0 lies about flush state,
+  that's a gsd-core bug to fix at the source, not a leak for the plugin to patch
+  with a racy retry loop.
+- Error/blocked cases route through existing `notify_terminal`/`notify_blocker`
+  unchanged.
+
+### Q8 — Failure modes
+| # | Mode | Disposition |
+|---|---|---|
+| 1 | Active auto session (co-run) | Reject before spawn; fail closed |
+| 2 | No project bound | Reuse `BindingError` path (zero new code) |
+| 3 | Empty spec | Usage message (matches `_cmd_reply`/`_cmd_bind`) |
+| 4 | Spec too long for `--context-text` | Surface `E2BIG`/`OSError`; point to `--file` |
+| 5 | Planning errors (non-zero exit) | `notify_terminal(status, error)` via existing path |
+| 6 | Planning hits a blocker | `notify_blocker`; reply via **client-owned stdin** (see below) |
+| 7 | `--file` missing/unreadable | Validate before spawn |
+| 8 | Stream-reader thread/pipe dies | Best-effort: set FAILED, `notify_terminal("failed", "stream lost — run /gsd cancel")`. **No watchdog.** Cancel is the escape hatch. |
+| 9 | Plugin restart mid-planning | **Documented limitation.** Orphaned subprocess survives; invisible after restart (same as existing supervisor's restart-blindness). |
+| 10 | User passes `--auto` | Reject at command level (see Q5) |
+
+**Blocker replies (#6) — client-owned, not MCP-routed.** `gsd_resolve_blocker`
+calls `sessionManager.resolveBlocker` which looks up the MCP server's *own*
+sessions map — our subprocess isn't there, so it throws "Session not found".
+Because we own the subprocess's stdin (A1), `/gsd reply` for a planning blocker
+writes the response to *our* subprocess's stdin via a new
+`respond_to_milestone_blocker(response)` method. `_cmd_reply` gets one branch:
+if a milestone subprocess with a pending blocker is active, route locally; else
+fall through to the existing MCP `resolve_blocker` path.
+
+### Q9 — Cross-effects on existing commands
+- **`_cmd_cancel`** — MUST change: add milestone-subprocess branch routing to
+  local `cancel_milestone()` (SIGTERM) when one is active. *Required.*
+- **`_cmd_auto`** — MUST change: add symmetric co-run guard (reject if
+  `SupervisorContext` shows an active milestone run, point to `/gsd cancel`).
+  *Required* — without it, `/gsd auto` during milestone planning silently
+  re-exposes the unsafe co-run (the MCP server's "Session already active"
+  rejection does NOT fire for our planning subprocess, since it's not registered
+  and writes no `auto.lock`). Rule #12 (fail loud) over rule #3 (surgical) here.
+- **`/gsd status`** — leave alone. Reads disk honestly; the Q3-accepted planning
+  progress gap means it may show stale/partial state early on. The completion
+  notification is the real "done" signal.
+- **`/gsd reply`** — additive branch only (Q8 #6); core MCP path untouched.
+- **`SupervisorFsm`** — untouched (A1 uses a separate stream-reader driver).
+- **TS MCP server** — untouched (no new tools).
+
+---
+
+## Implementation surface (additive unless noted)
+
+**`gsd_client.py`** — new methods + state:
+- `self._milestone_proc: subprocess.Popen | None`
+- `create_milestone(project_dir, *, context_text=None, context_file=None) -> str` —
+  spawns `gsd headless new-milestone --output-format stream-json`, starts the
+  stream-reader thread, returns `sessionId` (captured from `init_result`). Throws
+  on co-run guard / missing spec.
+- `_milestone_stream_loop(proc)` — reads stdout JSONL; on `init_result` captures
+  `sessionId`; on blocker event → `notify_blocker` + sets
+  `SupervisorContext.pending_blocker_id`; on terminal/exit → `notify_terminal` +
+  sets `SupervisorContext.state`.
+- `cancel_milestone()` — `proc.terminate()` + cleanup.
+- `respond_to_milestone_blocker(response)` — writes UI-response to proc stdin.
+- `milestone_active()` predicate for the co-run gate.
+
+**`commands.py`** — new handler + two modifications:
+- `_cmd_new_milestone(rest)` — the new command (guard, parse, spawn, ack).
+- `_cmd_cancel` (modify) — milestone-subprocess branch.
+- `_cmd_auto` (modify) — symmetric co-run guard.
+- `_cmd_reply` (modify) — milestone-blocker branch (additive).
+- `_cmd_help` (modify) — list `new-milestone`.
+
+**`__init__.py`** — wire the new client methods / supervisor notifications if
+the constructor surface changes (likely no change — `GsdMcpClient` already has
+`config`, and `NotificationService` is already injected).
+
+**Tests** (new, matching existing `tests/test_*.py` patterns):
+- `test_new_milestone_command.py` — guard (co-run both ways), input parsing
+  (bare text, `--file`, empty, `--auto` rejected), spawn + ack.
+- extend `test_gsd_client_cache.py` or new `test_milestone_client.py` —
+  stream-reader captures sessionId from `init_result`; blocker event →
+  `notify_blocker`; terminal → `notify_terminal`; cancel SIGTERMs the proc;
+  blocker reply writes stdin.
+- extend cancel/reply tests for the new branches.
+
+---
+
+## Explicitly OUT of scope (v1)
+
+- `--auto` chaining (execution stays with `/gsd auto`).
+- Cross-instance / server-side co-run coordination (Q2 limitation).
+- Plugin-restart recovery of an orphaned planning subprocess (Q8 #9).
+- A Hermes skill (issue's Option B) — additive follow-on, wraps the same client.
+- Any TS-side / MCP-server change.

package/integrations/hermes/docs/setup.md

@@ -79,6 +79,7 @@ gsd:
   default_project: ~/code/myapp         # optional fallback
   poll_interval_seconds: 12
   cache_ttl_seconds: 45
+  mcp_read_timeout_seconds: 60          # per-response MCP read timeout
   notification_level: normal            # quiet | normal | verbose
   bindings:
     slack:
@@ -89,6 +90,8 @@ gsd:
 
 **Binding tiers (first match wins):** cron explicit → slash argument → `/gsd bind` session binding → channel map → `default_project` → cwd heuristic.
 
+**MCP read timeout:** `gsd.mcp_read_timeout_seconds` defaults to `60` seconds and bounds each response read from the `gsd-mcp-server` sidecar. Increase it for very slow projects, machines, or network-backed filesystems where Hermes reports MCP response timeouts but the same GSD command eventually completes locally; lower it only when you prefer faster failure detection. When the timeout fires, the plugin terminates the stuck sidecar and the next project-scoped call starts a fresh server in the bound project directory.
+
 **Credentials:** With `credential_source: gsd`, ensure GSD’s normal provider keys are configured (`~/.gsd/` or env). Hermes passthrough (`credential_source: hermes`) is 6b+.
 
 ### Verify plugin loaded
@@ -224,6 +227,7 @@ Verify on **one** platform (Slack or Telegram):
 | `GsdVersionError` on start | `gsd` outside semver range | Set `gsd_version_min` in `gsd.yaml` or upgrade gsd |
 | MCP spawn fails | Wrong `mcp_server_path` | `which gsd-mcp-server`; set absolute path |
 | `/gsd status` hangs | MCP sidecar stuck | Check `GSD_CLI_PATH`; restart gateway; kill orphaned `gsd-mcp-server` |
+| MCP response times out after 60s | Slow project or filesystem, or wedged sidecar | Confirm the command locally; tune `mcp_read_timeout_seconds` if it completes after 60s |
 | No push notifications | Invalid session key / target | Key must match `agent:main:{platform}:{chat_type}:{chat_id}`; check Hermes gateway logs |
 | Notifications in CLI but not Slack | `DeliveryTarget.from_session_key` returned None | Run checklist in **gateway** mode, not CLI-only |
 | Cancel ignored | Stale session id | `/gsd cancel` uses `gsd_cancel_by_project` fallback when no session id |

package/integrations/hermes/open_gsd_hermes/commands.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import shlex
 from typing import Any, Callable
 
@@ -58,6 +59,7 @@ class GsdCommandRouter:
             "auto": self._cmd_auto,
             "cancel": self._cmd_cancel,
             "reply": self._cmd_reply,
+            "new-milestone": self._cmd_new_milestone,
             "help": self._cmd_help,
         }
         handler = handlers.get(sub, self._cmd_help)
@@ -69,6 +71,7 @@ class GsdCommandRouter:
             "- `/gsd bind <path>` — bind this chat to a project\n"
             "- `/gsd status` — show progress snapshot\n"
             "- `/gsd auto` — start auto mode (MCP)\n"
+            "- `/gsd new-milestone <spec>` or `--file <path>` — create a milestone (then `/gsd auto`)\n"
             "- `/gsd cancel` — cancel running session\n"
             "- `/gsd reply <text>` — resolve blocker"
         )
@@ -112,6 +115,15 @@ class GsdCommandRouter:
             return f"GSD status unavailable: {e}"
 
     async def _cmd_auto(self, _rest: list[str]) -> str:
+        # Symmetric co-run guard (issue #1162): refuse if a milestone run is
+        # in progress. The MCP server's "Session already active" rejection
+        # does NOT fire for a milestone subprocess (it's not registered and
+        # writes no auto.lock during planning), so this local gate is the
+        # only thing preventing an unsafe co-run.
+        if self._client.milestone_active():
+            return (
+                "Milestone creation is in progress. Run `/gsd cancel` first."
+            )
         try:
             project_dir = resolve_project_dir(
                 self._config, self._binding_ctx()
@@ -140,6 +152,18 @@ class GsdCommandRouter:
 
     async def _cmd_cancel(self, _rest: list[str]) -> str:
         ctx = self._get_supervisor_ctx()
+        # Milestone subprocess is locally owned (issue #1162); route to the
+        # local SIGTERM path instead of MCP cancel, which cannot see it.
+        if self._client.milestone_active():
+            self._client.cancel_milestone()
+            ctx.session_id = None
+            ctx.state = SupervisorState.CANCELLED
+            ctx.notified_terminal = True
+            self._set_supervisor_ctx(ctx)
+            self._supervisor.stop()
+            if self._notifications is not None:
+                self._notifications.notify_terminal("cancelled")
+            return "Cancel requested."
         try:
             try:
                 if ctx.session_id and ctx.project_dir:
@@ -175,6 +199,17 @@ class GsdCommandRouter:
         if not rest:
             return "Usage: `/gsd reply <your answer>`"
         text = " ".join(rest)
+        # Milestone planning blocker (issue #1162): the subprocess is locally
+        # owned, so its blocker replies must go to its stdin, not MCP
+        # gsd_resolve_blocker (which can't see our session).
+        if self._client.milestone_active():
+            if not self._client.milestone_pending_blocker_id():
+                return "No pending blocker for the active milestone session."
+            try:
+                self._client.respond_to_milestone_blocker(text)
+            except Exception as e:
+                return f"Could not send blocker response: {e}"
+            return "Blocker response sent."
         ctx = self._get_supervisor_ctx()
         if not ctx.session_id:
             return "No active GSD session. Run `/gsd auto` first."
@@ -184,3 +219,109 @@ class GsdCommandRouter:
         except Exception as e:
             return f"Could not send blocker response: {e}"
         return "Blocker response sent."
+
+    async def _cmd_new_milestone(self, rest: list[str]) -> str:
+        """Create a milestone via `gsd headless --supervised new-milestone`.
+
+        Planning-only: the plugin spawns the subprocess, owns its lifecycle,
+        and notifies on blocker/terminal events. Execution stays with
+        `/gsd auto`. See integrations/hermes/docs/issue-1162-grilling.md.
+        """
+        if not rest:
+            return (
+                "Usage: `/gsd new-milestone <spec>` "
+                "(or `--file <path>`)"
+            )
+        # --auto is intentionally rejected (Q5): execution is /gsd auto's job.
+        if rest[0] == "--auto":
+            return (
+                "Execution isn't chained from `/gsd new-milestone`. "
+                "Create the milestone, then run `/gsd auto`."
+            )
+        # Co-run guard (Q2): refuse if a milestone or auto session is active.
+        if self._client.milestone_active():
+            return (
+                "Milestone creation is in progress. Run `/gsd cancel` first."
+            )
+        ctx = self._get_supervisor_ctx()
+        if ctx.state in (SupervisorState.RUNNING, SupervisorState.BLOCKED):
+            return (
+                "GSD auto is running. Run `/gsd cancel` first."
+            )
+        # Resolve the bound project.
+        try:
+            project_dir = resolve_project_dir(
+                self._config, self._binding_ctx()
+            )
+        except BindingError as e:
+            return str(e)
+
+        # Input shape (Q6): bare positional → context_text, `--file <path>`
+        # → context_file.
+        context_text: str | None = None
+        context_file: str | None = None
+        if rest[0] == "--file":
+            if len(rest) < 2:
+                return "Usage: `/gsd new-milestone --file <path>`"
+            context_file = rest[1]
+            resolved_file = (
+                context_file
+                if os.path.isabs(context_file)
+                else os.path.join(project_dir, context_file)
+            )
+            if not os.path.isfile(resolved_file):
+                return f"Context file not found: `{context_file}`"
+            if not os.access(resolved_file, os.R_OK):
+                return f"Context file is not readable: `{context_file}`"
+            context_file = resolved_file
+        else:
+            context_text = " ".join(rest)
+
+        def _on_milestone_terminal(status: str) -> None:
+            milestone_ctx = self._get_supervisor_ctx()
+            if milestone_ctx.session_id != session_id:
+                return
+            normalized = status.lower()
+            if normalized in ("complete", "completed", "done"):
+                milestone_ctx.state = SupervisorState.COMPLETE
+            elif normalized == "cancelled":
+                milestone_ctx.state = SupervisorState.CANCELLED
+            else:
+                milestone_ctx.state = SupervisorState.FAILED
+            milestone_ctx.session_id = None
+            milestone_ctx.pending_blocker_id = None
+            milestone_ctx.notified_terminal = True
+            self._set_supervisor_ctx(milestone_ctx)
+
+        # Spawn the supervised subprocess; create_milestone returns a local
+        # session id immediately and continues the stream reader in the
+        # background.
+        try:
+            session_id = self._client.create_milestone(
+                project_dir,
+                context_text=context_text,
+                context_file=context_file,
+                notifications=self._notifications,
+                on_terminal=_on_milestone_terminal,
+            )
+        except ValueError:
+            return "Usage: `/gsd new-milestone <spec>` (or `--file <path>`)"
+        except Exception as e:
+            return f"Could not start milestone creation: {e}"
+
+        # Record the active milestone run so /gsd status, /gsd cancel, and the
+        # co-run gate (in _cmd_auto) see it. The supervisor poll loop is NOT
+        # used (the stream reader drives notifications); we only carry state.
+        self._supervisor.stop()
+        ctx.session_id = session_id
+        ctx.project_dir = project_dir
+        ctx.state = SupervisorState.RUNNING
+        ctx.last_progress = None
+        ctx.last_status = None
+        ctx.pending_blocker_id = None
+        ctx.notified_terminal = False
+        self._set_supervisor_ctx(ctx)
+        return (
+            f"🚀 Milestone creation started (session `{session_id}`). "
+            "I'll notify you when it's ready; run `/gsd auto` to execute."
+        )

package/integrations/hermes/open_gsd_hermes/config.py

@@ -19,6 +19,7 @@ class GsdConfig:
     bindings: dict[str, dict[str, str]] = field(default_factory=dict)
     poll_interval_seconds: int = 12
     cache_ttl_seconds: int = 45
+    mcp_read_timeout_seconds: float = 60.0
     notification_level: str = "normal"
     gsd_version_min: str = "2.53"
     gsd_version_max: str = "3.0"
@@ -35,6 +36,7 @@ class GsdConfig:
             bindings=dict(gsd.get("bindings") or {}),
             poll_interval_seconds=int(gsd.get("poll_interval_seconds", 12)),
             cache_ttl_seconds=int(gsd.get("cache_ttl_seconds", 45)),
+            mcp_read_timeout_seconds=float(gsd.get("mcp_read_timeout_seconds", 60.0)),
             notification_level=str(gsd.get("notification_level", "normal")),
             gsd_version_min=str(gsd.get("gsd_version_min", "2.53")),
             gsd_version_max=str(gsd.get("gsd_version_max", "3.0")),