@jaguilar87/gaia 5.2.0-rc.1 → 5.2.0-rc.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gaia",
       "description": "Security-first multi-agent orchestration for Claude Code. Specialized agents cover the full development lifecycle — analysis, planning, execution, deployment — with codebase-aware context injection. Every command is risk-classified: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
-      "version": "5.2.0-rc.1",
+      "version": "5.2.0-rc.2",
       "category": "devops",
       "author": {
         "name": "jaguilar87",
@@ -19,7 +19,7 @@
       "source": {
         "source": "github",
         "repo": "metraton/gaia",
-        "ref": "v5.2.0-rc.1"
+        "ref": "v5.2.0-rc.2"
       }
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia",
-  "version": "5.2.0-rc.1",
+  "version": "5.2.0-rc.2",
   "description": "Security-first multi-agent orchestration for Claude Code. Agents span the full lifecycle; commands are risk-classified \u2014 reads run free, state changes need approval, irreversible ops blocked.",
   "author": {
     "name": "jaguilar87",

package/CHANGELOG.md

@@ -29,6 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `gaia context prune-workspaces --yes` is now correctly classified T3 (state-mutating): it hard-deletes `workspaces` rows, but the `context` group carried no mutative verb and classified read-only by elimination. Only the destructive subcommand is anchored (`COMMAND_SUBCOMMAND_MUTATIVE_UPGRADES[("gaia","context")]`); other `context` subcommands stay read-only. Separately, the Step 5 ALWAYS-dangerous flag scan now runs before the read-only-verb early return, so `git fetch --prune` (a read-only verb with a destructive flag) escalates to T3 instead of being skipped.
 - SubagentStop M4 fence footgun: a turn that built its contract via the `gaia contract` CLI and ran `gaia contract finalize` (valid terminal row) but forgot to echo the fenced `agent_contract_handoff` in its response text was hard-rejected by the full-verdict gate. `adapt_subagent_stop` now reconstructs the envelope from the agent's own finalized draft when the fence is missing, so the gate parses the completed contract; non-fatal (falls back to the unchanged gate when no finalized row exists). The minted-agent-id resolver was factored into a shared `resolve_minted_agent_id` reused by the backstop, truncation salvage, and this path.
 
+## [5.2.0-rc.2] - 2026-07-17
+
 ## [5.2.0-rc.1] - 2026-07-17
 
 ## [5.1.3] - 2026-07-07

package/bin/cli/doctor.py

@@ -103,7 +103,16 @@ def _derive_workspace(override: str = None) -> Path:
     Algorithm
     ---------
     1. If *override* is given (from --workspace), validate it has .claude/
-       and return it directly.
+       and return it directly. (Highest priority -- always wins.)
+    1b. Else if the ``GAIA_WORKSPACE_PATH`` env var is set AND points at a dir
+       containing ``.claude/``, return it. This is set by the Windows launcher
+       (see install.py Step 6.5), which bakes the resolved workspace so a
+       global-shim invocation resolves the SAME workspace POSIX derives from
+       ``__file__``. Without this, the npm global ``gaia.cmd`` runs ``bin/gaia``
+       from the npm prefix, ``__file__`` lands there, and the derivation below
+       yields the npm prefix as the "workspace" -- a false CRITICAL. An env var
+       that is unset OR points at a dir without ``.claude/`` falls through to
+       the ``__file__`` derivation (it is a hint, not an override).
     2. Resolve Path(__file__) to its realpath and find the FIRST (leftmost)
        ``node_modules`` path segment; the workspace is everything before it.
     3. Sanity-check that ``@jaguilar87`` and ``gaia`` both appear somewhere
@@ -148,6 +157,16 @@ def _derive_workspace(override: str = None) -> Path:
             sys.exit(2)
         return ws
 
+    # --- GAIA_WORKSPACE_PATH env (baked by the Windows launcher) ---
+    # Consulted BEFORE the __file__ derivation but AFTER --workspace. Only
+    # honored when it resolves to a dir with .claude/; otherwise fall through
+    # (never a cwd walk-up -- that was removed on purpose). See docstring 1b.
+    env_ws = os.environ.get("GAIA_WORKSPACE_PATH")
+    if env_ws:
+        candidate = Path(env_ws).expanduser().resolve()
+        if (candidate / ".claude").is_dir():
+            return candidate
+
     # --- Derive from __file__ realpath ---
     script_path = Path(__file__).resolve()
     parts = script_path.parts

package/bin/cli/install.py

@@ -61,8 +61,9 @@ Flags:
                      Useful when running install just to refresh the DB
                      schema from a non-Gaia directory.
   --no-path          Skip creating the ~/.local/bin/gaia launcher. By default
-                     install writes a workspace-aware bash launcher so `gaia`
-                     is callable from any cwd.
+                     install writes a workspace-aware launcher so `gaia` is
+                     callable from any cwd: a bash launcher on POSIX, and
+                     `gaia.cmd` + `gaia.ps1` on Windows.
 """
 
 from __future__ import annotations
@@ -92,30 +93,90 @@ _SEED_SURFACE_ROUTING = _PACKAGE_ROOT / "tools" / "scan" / "seed_surface_routing
 
 
 # ---------------------------------------------------------------------------
-# PATH launcher (~/.local/bin/gaia -- workspace-bound bash launcher)
+# PATH launcher (~/.local/bin/gaia -- workspace-bound launcher)
 # ---------------------------------------------------------------------------
-
-# Hardcoded launcher template. The workspace path is resolved at install time
-# (the cwd of `gaia install`) and baked into the script verbatim. No discovery,
-# no env vars, no fallbacks -- the shim is a 3-line exec to a fixed path.
 #
-# Rationale: the previous workspace-aware launcher walked up from $PWD looking
-# for node_modules/@jaguilar87/gaia/, which failed silently from any cwd
-# outside the consumer workspace tree (e.g. /tmp). Same conceptual bug that
-# rc.5 fixed in doctor.py for the Python layer.
+# Platform split (Step 6.5): the launcher form is chosen by platform. This is a
+# hard guard, not a preference -- a bash script has no meaning to the Windows
+# shell (PowerShell opens an "open with" dialog on an extensionless file), and
+# the POSIX shim's ``{workspace}/node_modules/...`` target does not exist under
+# ``npm install -g`` on any platform. So:
+#
+#   * POSIX  -> one bash launcher at ``<link>`` (unchanged behavior).
+#   * Windows -> ``<link>.cmd`` and ``<link>.ps1``, each of which
+#       (a) bakes the resolved workspace path,
+#       (b) exports ``GAIA_WORKSPACE_PATH`` so `gaia doctor` resolves the
+#           correct workspace from the env instead of deriving it from
+#           ``__file__`` (which, via the npm global shim, lands in the npm
+#           prefix and yields a false CRITICAL -- see doctor._derive_workspace),
+#       (c) execs the ACTUAL installed ``bin/gaia`` dispatcher
+#           (``_gaia_entrypoint()`` = ``<package_root>/bin/gaia``), which is
+#           valid for BOTH a global (`-g`) and a local install, unlike the
+#           POSIX shim's workspace-relative ``node_modules`` path.
 #
-# Re-running `gaia install` from a different workspace rewrites the shim to
-# point at that workspace -- the install action is what selects which Gaia
-# install ~/.local/bin/gaia targets.
+# PATH precedence vs npm's own shim (Windows): `npm install -g @jaguilar87/gaia`
+# writes its own ``gaia.cmd`` into the npm global prefix (on PATH), and that
+# shim execs ``bin/gaia`` WITHOUT setting GAIA_WORKSPACE_PATH -- which is
+# exactly the origin of the false-CRITICAL bug. Gaia's launcher coexists with
+# and wins over npm's by being written to Gaia's own bin dir (default
+# ``~/.local/bin``): when that dir precedes the npm prefix on PATH, cmd.exe /
+# PowerShell resolve ``gaia`` (``gaia.cmd`` / ``gaia.ps1``) to Gaia's launcher,
+# which sets GAIA_WORKSPACE_PATH before dispatching. Where Gaia's dir is NOT
+# ahead of the npm prefix, npm's shim still runs and still dispatches correctly
+# for workspace-independent subcommands; only the workspace-derivation path
+# needs the env var, and the doctor `__file__` fallback keeps working. The
+# env-var contract is the load-bearing coupling, not the PATH order.
+#
+# Re-running `gaia install` from a different workspace rewrites the launcher(s)
+# to point at that workspace -- the install action is what selects which
+# workspace the launcher targets.
+
+# POSIX bash launcher. The workspace path is resolved at install time and baked
+# in verbatim. No discovery, no env vars, no fallbacks -- a 3-line exec.
 _LAUNCHER_TEMPLATE = """#!/bin/bash
 # gaia -- workspace-bound launcher (workspace path hardcoded at install time)
 # Generated by `gaia install`. Re-run install from another workspace to retarget.
 exec python3 "{workspace_path}/node_modules/@jaguilar87/gaia/bin/gaia" "$@"
 """
 
+# Windows launchers. Both bake the resolved workspace, export GAIA_WORKSPACE_PATH,
+# and dispatch to the ACTUAL installed bin/gaia (global- or local-install safe).
+_CMD_LAUNCHER_TEMPLATE = """@echo off
+REM gaia -- workspace-bound launcher (generated by `gaia install`)
+REM Re-run install from another workspace to retarget. Exports GAIA_WORKSPACE_PATH
+REM so `gaia doctor` resolves this workspace instead of deriving from __file__.
+set "GAIA_WORKSPACE_PATH={workspace_path}"
+python "{gaia_bin}" %*
+"""
+
+_PS1_LAUNCHER_TEMPLATE = """# gaia -- workspace-bound launcher (generated by `gaia install`)
+# Re-run install from another workspace to retarget. Exports GAIA_WORKSPACE_PATH
+# so `gaia doctor` resolves this workspace instead of deriving from __file__.
+$env:GAIA_WORKSPACE_PATH = "{workspace_path}"
+& python "{gaia_bin}" @args
+exit $LASTEXITCODE
+"""
+
+
+def _is_windows() -> bool:
+    """True on Windows. Isolated so the platform guard is trivially patchable."""
+    return sys.platform == "win32"
+
+
+def _gaia_entrypoint() -> Path:
+    """Absolute path to the installed ``bin/gaia`` dispatcher.
+
+    This is ``<package_root>/bin/gaia`` -- the real location of the running
+    Gaia package, which resolves correctly under both a global (`npm i -g`)
+    and a local install. The POSIX shim's ``{workspace}/node_modules/...``
+    assumption breaks under `-g` (there is no workspace-relative node_modules);
+    the Windows launchers bake this resolved path instead.
+    """
+    return _PACKAGE_ROOT / "bin" / "gaia"
+
 
 def _render_launcher(workspace: Path) -> str:
-    """Render the launcher script with the workspace path baked in.
+    """Render the POSIX bash launcher with the workspace path baked in.
 
     The workspace must be an absolute, resolved path -- the rendered script
     references it verbatim. Quoting in the template uses double quotes so
@@ -124,21 +185,40 @@ def _render_launcher(workspace: Path) -> str:
     return _LAUNCHER_TEMPLATE.format(workspace_path=str(workspace))
 
 
+def _render_cmd_launcher(workspace: Path, gaia_bin: Path) -> str:
+    """Render the Windows ``gaia.cmd`` launcher (workspace + bin baked in)."""
+    return _CMD_LAUNCHER_TEMPLATE.format(
+        workspace_path=str(workspace), gaia_bin=str(gaia_bin)
+    )
+
+
+def _render_ps1_launcher(workspace: Path, gaia_bin: Path) -> str:
+    """Render the Windows ``gaia.ps1`` launcher (workspace + bin baked in)."""
+    return _PS1_LAUNCHER_TEMPLATE.format(
+        workspace_path=str(workspace), gaia_bin=str(gaia_bin)
+    )
+
+
 def _install_path_launcher(
     target_path: Path | None = None,
     link_path: Path | str = "~/.local/bin/gaia",
     overwrite: bool = False,
     workspace: Path | str | None = None,
+    gaia_bin: Path | str | None = None,
 ) -> dict:
-    """Install the workspace-bound bash launcher at `link_path`.
+    """Install the workspace-bound launcher at `link_path`.
+
+    Platform-guarded (Step 6.5): on Windows this writes ``<link>.cmd`` and
+    ``<link>.ps1`` (see ``_install_windows_launchers``); on POSIX it writes a
+    single bash launcher at ``<link>``. The POSIX behavior below is unchanged.
 
-    The launcher is a 3-line script that execs into a hardcoded absolute path
-    pointing at ``<workspace>/node_modules/@jaguilar87/gaia/bin/gaia``. There
-    is no discovery logic, no env-var override, no fallback chain -- the path
-    is fixed at install time and only changes when ``gaia install`` runs again
-    from a different workspace.
+    The POSIX launcher is a 3-line script that execs into a hardcoded absolute
+    path pointing at ``<workspace>/node_modules/@jaguilar87/gaia/bin/gaia``.
+    There is no discovery logic, no env-var override, no fallback chain -- the
+    path is fixed at install time and only changes when ``gaia install`` runs
+    again from a different workspace.
 
-    Behavior:
+    Behavior (POSIX):
       - If `link_path` is a symlink (legacy install): unlink, write launcher.
       - If `link_path` is a regular file with the expected content: noop.
       - If `link_path` is a regular file with different content and
@@ -151,10 +231,14 @@ def _install_path_launcher(
         target_path: accepted for API compatibility; the launcher embeds the
             workspace path instead. Ignored.
         link_path: where the shim is written (default ``~/.local/bin/gaia``).
+            On Windows, ``.cmd``/``.ps1`` suffixes are derived from this base.
         overwrite: replace existing different-content files when True.
         workspace: absolute path to the consumer workspace (the directory
             that contains ``node_modules/@jaguilar87/gaia/``). Resolved with
             ``Path.cwd().resolve()`` when None.
+        gaia_bin: Windows only -- the ``bin/gaia`` dispatcher the launchers
+            exec. Defaults to ``_gaia_entrypoint()`` (the installed package's
+            ``bin/gaia``, valid for global and local installs). Ignored on POSIX.
 
     Returns a dict with `action`, `path`, and `details`. `action` is one
     of: created, replaced, migrated, noop, skipped, error.
@@ -167,6 +251,20 @@ def _install_path_launcher(
     else:
         workspace_resolved = Path(workspace).expanduser().resolve()
 
+    # Windows: emit gaia.cmd + gaia.ps1 instead of a bash shim. The POSIX path
+    # below is left entirely unchanged.
+    if _is_windows():
+        entry = (
+            Path(gaia_bin).expanduser() if gaia_bin is not None
+            else _gaia_entrypoint()
+        )
+        return _install_windows_launchers(
+            link=link,
+            workspace=workspace_resolved,
+            gaia_bin=entry,
+            overwrite=overwrite,
+        )
+
     parent = link.parent
     try:
         parent.mkdir(parents=True, exist_ok=True)
@@ -268,6 +366,86 @@ def _install_path_launcher(
     }
 
 
+def _install_windows_launchers(
+    link: Path,
+    workspace: Path,
+    gaia_bin: Path,
+    overwrite: bool = False,
+) -> dict:
+    """Write the Windows ``gaia.cmd`` + ``gaia.ps1`` launchers.
+
+    Both are derived from ``link`` by suffix: ``<link>.cmd`` and ``<link>.ps1``
+    (so a default ``~/.local/bin/gaia`` yields ``gaia.cmd`` / ``gaia.ps1``).
+    Each bakes the resolved ``workspace``, exports ``GAIA_WORKSPACE_PATH``, and
+    dispatches to ``gaia_bin`` (the actual installed ``bin/gaia``).
+
+    Idempotent and non-destructive, mirroring the POSIX branch:
+      - missing            -> created
+      - present, matches   -> noop
+      - present, drifted   -> replaced (overwrite=True) / skipped (overwrite=False)
+      - a directory in the way -> skipped
+
+    The aggregate ``action`` is the "strongest" over the two files: error >
+    skipped > replaced > created > noop. ``path`` lists both files.
+    """
+    parent = link.parent
+    try:
+        parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return {
+            "action": "error",
+            "path": str(link),
+            "details": f"failed to create parent {parent}: {exc}",
+        }
+
+    targets = [
+        (link.with_suffix(".cmd"), _render_cmd_launcher(workspace, gaia_bin)),
+        (link.with_suffix(".ps1"), _render_ps1_launcher(workspace, gaia_bin)),
+    ]
+
+    # Rank so the aggregate reports the most significant per-file outcome.
+    rank = {"noop": 0, "created": 1, "replaced": 2, "skipped": 3, "error": 4}
+    per_file: list[str] = []
+    worst = "noop"
+
+    for path, content in targets:
+        action = _write_windows_launcher_file(path, content, overwrite=overwrite)
+        per_file.append(f"{path.name}={action}")
+        if rank[action] > rank[worst]:
+            worst = action
+
+    return {
+        "action": worst,
+        "path": ", ".join(str(p) for p, _ in targets),
+        "details": "; ".join(per_file),
+    }
+
+
+def _write_windows_launcher_file(path: Path, content: str, overwrite: bool) -> str:
+    """Write one Windows launcher file idempotently. Returns the action string."""
+    if path.is_dir():
+        return "skipped"
+    if path.exists():
+        try:
+            current = path.read_text()
+        except OSError:
+            return "error"
+        if current == content:
+            return "noop"
+        if not overwrite:
+            return "skipped"
+        try:
+            path.write_text(content)
+        except OSError:
+            return "error"
+        return "replaced"
+    try:
+        path.write_text(content)
+    except OSError:
+        return "error"
+    return "created"
+
+
 # Backward-compatible alias -- existing tests/imports continue to work
 # while migrating to the new name.
 _create_path_symlink = _install_path_launcher
@@ -632,7 +810,7 @@ def register(subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
         dest="no_path",
         action="store_true",
         default=False,
-        help="Skip creating the ~/.local/bin/gaia symlink",
+        help="Skip creating the ~/.local/bin/gaia launcher",
     )
     return p
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.2.0-rc.1",
+  "version": "5.2.0-rc.2",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gaia"
-version = "5.2.0-rc.1"
+version = "5.2.0-rc.2"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.11"
 license = {text = "MIT"}

package/skills/gaia-patterns/reference.md

@@ -169,7 +169,7 @@ There is **no npm postinstall hook**. `package.json` carries an explicit `_insta
 4. Merge hooks from `hooks.json` into `settings.local.json`.
 5. Create `.claude/{agents, tools, hooks, config, skills}` symlinks (5) plus a `CHANGELOG.md` file link.
 6. Write `plugin-registry.json` with `installed[].name == "gaia"` (the single unified plugin identity).
-7. Write the `~/.local/bin/gaia` PATH launcher unless `--no-path`.
+7. Write the PATH launcher unless `--no-path`: POSIX still gets the `~/.local/bin/gaia` bash shim; Windows instead gets `gaia.cmd` + `gaia.ps1` (`_install_windows_launchers` / `_render_cmd_launcher` / `_render_ps1_launcher` in `bin/cli/install.py`), each baking in the resolved workspace and exporting `GAIA_WORKSPACE_PATH` before dispatching to `bin/gaia`.
 
 Note: no `project-context.json` is written. Project context lives in `~/.gaia/gaia.db`. Run `gaia scan` separately to populate it -- install never triggers a scan.