@christang/keel 5.77.0 → 5.79.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.77.0",
+  "version": "5.79.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.77.0",
+  "version": "5.79.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.77.0",
+  "version": "5.79.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/scripts/session-start.js

@@ -137,6 +137,44 @@ function pluginManifest() {
   return { version: null, remedy: HOST_UPDATE };
 }
 
+// On Claude the plugin is the published package, cached at
+// <plugins>/cache/<marketplace>/<plugin>/<version>, and the host records what
+// it installed in <plugins>/installed_plugins.json (#172). Another install of
+// this same plugin at a different version means the update already happened
+// and this session has not reloaded it. Located from this file's own path, like
+// the manifest; anything unexpected is no pending install, which leaves the
+// report exactly as it was.
+function pendingInstall(loaded) {
+  try {
+    const root = fs.realpathSync(path.resolve(__dirname, "..", "..", ".."));
+    const record = path.join(root, "..", "..", "..", "..", "installed_plugins.json");
+    const plugins = JSON.parse(fs.readFileSync(record, "utf8")).plugins;
+    const versions = new Set();
+    for (const entries of Object.values(plugins || {})) {
+      for (const entry of Array.isArray(entries) ? entries : []) {
+        if (!entry || typeof entry.installPath !== "string") continue;
+        // Compared through the real path: node loads this file through its
+        // symlinks resolved, while the host records whatever path it chose.
+        const installPath = path.resolve(entry.installPath);
+        let parent;
+        try {
+          parent = fs.realpathSync(path.dirname(installPath));
+        } catch {
+          continue;
+        }
+        if (parent !== path.dirname(root)) continue;
+        if (path.join(parent, path.basename(installPath)) === root) continue;
+        if (typeof entry.version === "string") versions.add(entry.version.trim());
+      }
+    }
+    if (versions.size !== 1) return null;
+    const [version] = versions;
+    return version && version !== loaded ? version : null;
+  } catch {
+    return null;
+  }
+}
+
 // The repository states which protocol it runs in the managed block the
 // installer wrote. AGENTS.md is the canonical carrier; CLAUDE.md is read second
 // because a repository may carry only the target-native file.
@@ -193,16 +231,25 @@ function versionReport(cwd, cli, pathCli = null) {
   // The host puts the user's PATH ahead of plugin `bin/` directories, so a
   // global install is what the agent's own `keel` commands run even though
   // this hook ran the plugin's. Both remedies are named; neither is run.
-  const shadow = pathCli && pathCli !== cli
+  const pending = pendingInstall(plugin.version);
+  // With an installed update pending, the PATH copy is judged against what
+  // the reload will load: one that matches it shadows nothing afterwards, and
+  // aligning with the loaded plugin would be a downgrade (#172).
+  const target = pending || cli;
+  const shadow = pathCli && pathCli !== target
     ? ` The \`keel\` on PATH (${pathCli}) shadows this plugin's CLI for the `
       + "agent's commands, because the host puts your PATH first: remove it "
       + "with `npm rm -g @christang/keel`, since the plugin carries its own, "
-      + `or align it with \`npm i -g @christang/keel@${cli}\`.`
+      + `or align it with \`npm i -g @christang/keel@${target}\`.`
     : "";
+  // An update the host already installed needs only the reload (#172), so
+  // naming the update command there sends the reader to what already happened.
+  const remedy = pending
+    ? `The host has already installed plugin ${pending}, so nothing needs updating.`
+    : `Updating is ${plugin.remedy}, which Keel names and does not run.`;
   return `runtime versions disagree: ${named}${missing}. A session's hooks are `
     + "fixed when it loads the plugin, so an updated plugin applies after "
-    + "`/reload-plugins` or at the next session start. Updating is "
-    + `${plugin.remedy}, which Keel names and does not run.${shadow}`;
+    + `\`/reload-plugins\` or at the next session start. ${remedy}${shadow}`;
 }
 
 // The `keel` a bare command resolves, asked only when this hook ran its own

package/scripts/validate_plugin.py

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.77.0"
-PROTOCOL_VERSION = "5.77.0"
+PACKAGE_VERSION = "5.79.0"
+PROTOCOL_VERSION = "5.79.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -1242,13 +1242,12 @@ def validate_target_surface_scenario() -> int:
             report((codex_init.stderr or codex_init.stdout).strip())
             return 1
         codex_doctor = run_keel(codex_repo, "--doctor", "--target", "codex", env=env)
-        codex_prompt_dir = str(codex_home / "prompts")
         if (
             codex_doctor.returncode != 0
             or "OpenSpec commands: ok" not in codex_doctor.stdout
-            or posix_paths(codex_prompt_dir) not in posix_paths(codex_doctor.stdout)
+            or "OpenSpec 1.13 surfaces Codex's workflows" not in codex_doctor.stdout
             or "OpenSpec action skills: ok" not in codex_doctor.stdout
-            or ".codex/skills" not in posix_paths(codex_doctor.stdout)
+            or ".agents/skills" not in posix_paths(codex_doctor.stdout)
             or "bootstrap: ok" not in codex_doctor.stdout
             or "native plugin runtime: manual" not in codex_doctor.stdout
             or "Target capabilities (codex):" not in codex_doctor.stdout
@@ -1265,16 +1264,15 @@ def validate_target_surface_scenario() -> int:
             report("target-surface scenario Codex init created Claude-only paths.")
             return 1
 
-        for prompt in (codex_home / "prompts").glob("opsx-*.md"):
-            prompt.unlink()
+        # OpenSpec 1.13 writes Codex's workflows as skills only (#169), so the
+        # surface that can go missing is a skill.
+        shutil.rmtree(codex_repo / ".agents/skills/openspec-propose")
         codex_missing = run_keel(codex_repo, "--doctor", "--target", "codex", env=env)
         if (
             codex_missing.returncode != 0
-            or "OpenSpec commands: missing" not in codex_missing.stdout
-            or "keel --init --target codex" not in codex_missing.stdout
-            or "openspec update --force" not in codex_missing.stdout
+            or "OpenSpec action skills: missing" not in codex_missing.stdout
         ):
-            report("target-surface scenario Codex doctor did not report missing prompts.")
+            report("target-surface scenario Codex doctor did not report a missing skill.")
             report((codex_missing.stderr or codex_missing.stdout).strip())
             return 1
 
@@ -2649,15 +2647,11 @@ def openspec_overlay_files(
         }
     if target == "codex":
         assert codex_home is not None
+        # OpenSpec 1.13, which Keel pins, writes Codex's workflows as skills
+        # under `.agents/skills` and no command files (#169).
         return {
-            "apply": [
-                repo / ".codex/skills/openspec-apply-change/SKILL.md",
-                codex_home / "prompts/opsx-apply.md",
-            ],
-            "archive": [
-                repo / ".codex/skills/openspec-archive-change/SKILL.md",
-                codex_home / "prompts/opsx-archive.md",
-            ],
+            "apply": [repo / ".agents/skills/openspec-apply-change/SKILL.md"],
+            "archive": [repo / ".agents/skills/openspec-archive-change/SKILL.md"],
         }
     return {
         "apply": [
@@ -2777,8 +2771,7 @@ def expected_overlay_surfaces(
             surfaces.append(repo / f".claude/commands/opsx/{action}.md")
         elif target == "codex":
             assert codex_home is not None
-            surfaces.append(repo / f".codex/skills/{skill}/SKILL.md")
-            surfaces.append(codex_home / f"prompts/opsx-{action}.md")
+            surfaces.append(repo / f".agents/skills/{skill}/SKILL.md")
         else:
             surfaces.append(repo / f".opencode/skills/{skill}/SKILL.md")
             surfaces.append(repo / f".opencode/commands/opsx-{action}.md")
@@ -3022,7 +3015,7 @@ def validate_sync_surface_overlay_scenario() -> int:
                 ".claude/skills/openspec-sync-specs/SKILL.md",
             ],
             "codex": [
-                ".codex/skills/openspec-sync-specs/SKILL.md",
+                ".agents/skills/openspec-sync-specs/SKILL.md",
             ],
         }
 
@@ -3236,13 +3229,12 @@ def validate_openspec_surface_overlay_scenario() -> int:
         if (
             codex_doctor.returncode != 0
             or "Keel apply/archive/sync overlay: ok" not in codex_doctor.stdout
-            or str(codex_home / "prompts") not in codex_doctor.stdout
         ):
             report("openspec-surface-overlay scenario Codex doctor missed overlay health.")
             report((codex_doctor.stderr or codex_doctor.stdout).strip())
             return 1
 
-        codex_apply_prompt = codex_home / "prompts/opsx-apply.md"
+        codex_apply_prompt = codex_repo / ".agents/skills/openspec-apply-change/SKILL.md"
         original_prompt = codex_apply_prompt.read_text(encoding="utf-8")
         outdated_prompt = re.sub(
             r"<!--\s*keel:openspec-surface-overlay(?:\s+[^>]*)?\s*-->"
@@ -3269,6 +3261,33 @@ def validate_openspec_surface_overlay_scenario() -> int:
             report("openspec-surface-overlay scenario Codex install did not refresh overlay idempotently.")
             return 1
 
+        # M6 — a repository set up under OpenSpec 1.6 keeps its layout: skills
+        # under `.codex/skills` and commands as CODEX_HOME prompts (#169).
+        legacy_repo = tmp / "codex-legacy"
+        legacy_home = tmp / "codex-legacy-home"
+        legacy_env = os.environ.copy()
+        legacy_env["CODEX_HOME"] = str(legacy_home)
+        legacy_surfaces = []
+        for action, skill in OVERLAY_ACTION_SKILLS.items():
+            for surface in (
+                legacy_repo / f".codex/skills/{skill}/SKILL.md",
+                legacy_home / f"prompts/opsx-{action}.md",
+            ):
+                write_text(surface, f"---\nname: {skill}\n---\n\n# {action}\n")
+                legacy_surfaces.append(surface)
+        run_keel(legacy_repo, "--install", "--target", "codex", env=legacy_env)
+        lost = [
+            str(surface)
+            for surface in legacy_surfaces
+            if surface.read_text(encoding="utf-8").count(OPENSPEC_SURFACE_OVERLAY_START) != 1
+        ]
+        if lost:
+            report(
+                "openspec-surface-overlay scenario 1.6-layout Codex surfaces lost "
+                f"their overlay: {lost!r}"
+            )
+            return 1
+
         opencode_repo = tmp / "opencode"
         opencode_repo.mkdir()
         opencode_init = run_keel(opencode_repo, "--init", "--target", "opencode")
@@ -15983,6 +16002,135 @@ def validate_plugin_runs_its_own_cli_scenario() -> int:
     return 0
 
 
+def validate_drift_names_a_pending_reload_scenario() -> int:
+    """Issue #172: an update the host already installed needs only a reload.
+
+    The session keeps the hooks it loaded, and `/clear` does not reload them, so
+    a plugin the host has already updated keeps reporting drift until the
+    reader reloads. Naming the host's update command there sends them to an
+    action that already happened, and aligning the PATH copy with the loaded
+    plugin is a downgrade.
+    """
+    label = "drift-names-a-pending-reload"
+    event = {"hook_event_name": "SessionStart", "source": "clear"}
+    with tempfile.TemporaryDirectory(
+        prefix="keel-pending-reload-", ignore_cleanup_errors=True
+    ) as raw_tmp:
+        tmp = Path(raw_tmp)
+        repo = tmp / "repo"
+        write_text(repo / "openspec/changes/demo/tasks.md", task_contract_fixture())
+        write_text(
+            repo / "AGENTS.md",
+            "# Keel v5.81.0 Agent Protocol\n\n"
+            "<!-- keel:start version=5.81.0 -->\n## Session Start\n"
+            "<!-- keel:end -->\n",
+        )
+        # The host's layout: <plugins>/cache/<marketplace>/<plugin>/<version>,
+        # with its install record in <plugins>. The loaded copy is 5.80.0.
+        plugins_dir = tmp / "plugins"
+        package = plugins_dir / "cache/mkt/keel/5.80.0"
+        write_text(
+            package / "package.json",
+            json.dumps({"name": "@christang/keel", "version": "5.80.0"}) + "\n",
+        )
+        fake_keel_cli(package / "bin/keel.js", "5.80.0")
+        plugin = plant_session_start_plugin(package / "plugins/keel", "5.80.0")
+        record = plugins_dir / "installed_plugins.json"
+
+        def write_record(entries: dict) -> None:
+            write_text(record, json.dumps({"version": 2, "plugins": entries}) + "\n")
+
+        installed = str(plugins_dir / "cache/mkt/keel/5.81.0")
+        write_record(
+            {
+                "keel@mkt": [
+                    {"scope": "user", "installPath": installed, "version": "5.81.0"}
+                ]
+            }
+        )
+        path_cli = Path(fake_keel_cli(tmp / "path-cli.js", "5.81.0").split('"')[1])
+        path_dir = plant_path_keel(tmp / "path", path_cli)
+        env = {"PATH": str(path_dir) + os.pathsep + os.environ.get("PATH", "")}
+
+        def channels() -> dict[str, str]:
+            run = run_session_start_hook(
+                repo, event, keel_cli=None, plugin_root=plugin, extra_env=env
+            )
+            return {
+                "additionalContext": session_start_context(run) or "",
+                "systemMessage": session_start_message(run) or "",
+            }
+
+        pending = channels()
+        for channel, text in pending.items():
+            lowered = text.lower()
+            # M1 — the update is named as installed, and the reload as the remedy.
+            if "claude plugin update" in lowered:
+                report(
+                    f"{label} M1 {channel} named claude plugin update for an "
+                    f"update the host already installed: {text!r}"
+                )
+                return 1
+            if "already installed plugin 5.81.0" not in lowered:
+                report(
+                    f"{label} M1 {channel} does not say the host already "
+                    f"installed plugin 5.81.0: {text!r}"
+                )
+                return 1
+            if "/reload-plugins" not in lowered:
+                report(f"{label} M1 {channel} does not name /reload-plugins: {text!r}")
+                return 1
+            # M2 — a PATH copy at the installed version is not a shadow.
+            if "shadows" in lowered or "@christang/keel@5.80.0" in lowered:
+                report(
+                    f"{label} M2 {channel} called a PATH keel at the installed "
+                    f"version a shadow: {text!r}"
+                )
+                return 1
+
+        # M3 — another plugin's install is not this one's, and no record at
+        # all is the same as a record that names nothing of ours. Its directory
+        # exists, as the host's would, so the entry is excluded by being
+        # another plugin's and not by being unreadable.
+        (plugins_dir / "cache/mkt/other/9.9.9").mkdir(parents=True)
+        write_record(
+            {
+                "other@mkt": [
+                    {
+                        "scope": "user",
+                        "installPath": str(plugins_dir / "cache/mkt/other/9.9.9"),
+                        "version": "9.9.9",
+                    }
+                ]
+            }
+        )
+        unrelated = channels()
+        for channel, text in unrelated.items():
+            lowered = text.lower()
+            if "already installed" in lowered:
+                report(
+                    f"{label} M3 {channel} read another plugin's install as "
+                    f"this one's: {text!r}"
+                )
+                return 1
+            if "claude plugin update" not in lowered:
+                report(
+                    f"{label} M3 {channel} dropped the update command with no "
+                    f"install of this plugin recorded: {text!r}"
+                )
+                return 1
+        record.unlink()
+        absent = channels()
+        if absent != unrelated:
+            report(
+                f"{label} M3 a missing install record changed the report:\n"
+                f"  no record:      {absent!r}\n  other plugin:   {unrelated!r}"
+            )
+            return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
 def stage_claude_market_under_test(tmp: Path) -> tuple[Path, str, str] | str:
     """A Claude marketplace that installs this tree rather than the registry.
 
@@ -16617,8 +16765,7 @@ def validate_authoring_alignment_overlay_scenario() -> int:
             report((codex_init.stderr or codex_init.stdout).strip())
             return 1
         codex_surfaces = (
-            codex_repo / ".codex/skills/openspec-propose/SKILL.md",
-            codex_home / "prompts/opsx-propose.md",
+            codex_repo / ".agents/skills/openspec-propose/SKILL.md",
         )
         for surface in codex_surfaces:
             content = surface.read_text(encoding="utf-8")
@@ -16648,7 +16795,7 @@ def validate_authoring_alignment_overlay_scenario() -> int:
                 return 1
 
         apply_skill = (
-            codex_repo / ".codex/skills/openspec-apply-change/SKILL.md"
+            codex_repo / ".agents/skills/openspec-apply-change/SKILL.md"
         ).read_text(encoding="utf-8")
         if (
             "rerun `keel-align-expectations`" not in apply_skill
@@ -31428,6 +31575,7 @@ SCENARIOS: tuple = (
     ("native-plugin-session-start", validate_native_plugin_session_start_scenario),
     ("runtime-version-drift", validate_runtime_version_drift_scenario),
     ("plugin-runs-its-own-cli", validate_plugin_runs_its_own_cli_scenario),
+    ("drift-names-a-pending-reload", validate_drift_names_a_pending_reload_scenario),
     ("init-declares-plugin-auto-update", validate_init_declares_plugin_auto_update_scenario),
     ("context-names-the-protocol-refresh", validate_context_names_the_protocol_refresh_scenario),
     ("init-never-downgrades-openspec", validate_init_never_downgrades_openspec_scenario),

package/src/core/context.js

@@ -741,9 +741,10 @@ function stampedProtocol(repo) {
 
 // The target the installer left behind. `CLAUDE.md` carries the managed
 // import only on the Claude target, and only OpenCode writes project commands
-// under `.opencode/`. A Codex install writes neither — its OpenSpec commands
-// are global prompts under CODEX_HOME — so a managed `AGENTS.md` with neither
-// surface beside it is what a Codex install leaves.
+// under `.opencode/`. A Codex install writes neither: OpenSpec 1.13 puts its
+// skills under `.agents/skills`, and 1.6 put its commands in CODEX_HOME, so a
+// managed `AGENTS.md` with neither surface beside it is what a Codex install
+// leaves.
 function installedTarget(repo) {
   try {
     if (/<!--\s*keel:start/.test(fs.readFileSync(path.join(repo, "CLAUDE.md"), "utf8"))) {