@theglitchking/persistent-planning 3.4.0 → 3.4.2

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for persistent-planning - Persistent markdown-based planning for Claude Code. Context engineering pattern with task directories, progress tracking, and working memory that persists across sessions.",
-    "version": "3.4.0"
+    "version": "3.4.2"
   },
   "plugins": [
     {
       "name": "persistent-planning",
       "description": "Persistent markdown-based planning for Claude Code. Uses on-disk markdown files as working memory for planning, progress tracking, and knowledge storage. Plans persist across sessions and support multiple concurrent tasks.",
-      "version": "3.4.0",
+      "version": "3.4.2",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "author": {
     "name": "TheGlitchKing"

package/.documentation/procedures/plugin-update-delivery.md

@@ -68,6 +68,13 @@ its own.
   failure is contained.
 - **Fails open.** Every path is wrapped. A broken migration must never cost someone
   their session start.
+- **Never let a dependency be fatal.** Load the runtime with `await import()` in a
+  try/catch. A static import makes an unresolvable dependency fatal for the whole hook,
+  including the repair — the delivery path must survive what it is delivering a fix for
+  (#18). Only the update check genuinely needs the runtime.
+- **Stamp on success, never on failure.** Marking a version done after a failed attempt
+  turns a transient problem into a permanent one: the repair never runs again, even once
+  the cause is gone. Retrying costs one spawn per session while genuinely drifted.
 - **One stdout write.** The runtime owns the single `SessionStart` JSON response and
   exposes no append hook; a second response line is invalid. Merge into the existing
   intercept.

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.2] - 2026-09-05
+
+### Changed — the local `update` guard moves upstream into the runtime
+
+3.4.0 added a `preAction` guard in `bin/persistent-planning.js` because the
+runtime's `update` resolved installation state from `<cwd>/node_modules` and
+`CLAUDE_PLUGIN_ROOT` only, found neither in a marketplace-only install, and
+exited 0 after an `npm update` that touched nothing. The guard worked, but it
+was a workaround living in one plugin while every sibling stayed broken —
+babel-fish#17 was the same defect reported against babel-fish.
+
+Fixed properly in `@theglitchking/claude-plugin-runtime` 0.1.1, which this
+release requires. `resolveInstall()` there probes npm dep → `CLAUDE_PLUGIN_ROOT`
+→ the marketplace record in `~/.claude/plugins/installed_plugins.json`, so the
+26-line guard is deleted rather than reimplemented.
+
+The result is strictly better than the guard it replaces. Previously a
+marketplace install satisfied the guard and fell through to a no-op `npm update`
+that exited 0; now it is recognised, named by path, and refused with a pointer
+at `/plugin` — the only thing that can actually update a plugin-cache copy.
+
+The dependency floor is `^0.1.1`, not `^0.1.0`: the shared plugin dep tree at
+`~/.claude/plugins/npm-cache` pins the runtime at 0.1.0 in its lockfile, and
+0.1.0 still satisfies `^0.1.0`, so the broken copy would have survived.
+
+### Fixed — the CLI test depended on the developer's own machine
+
+`tests/run.sh` ran `update` in a temp workspace but inherited the real `$HOME`,
+so once the runtime learned to read `~/.claude/plugins/installed_plugins.json`
+the assertion passed or failed depending on whether the person running it
+happened to have the plugin installed. `HOME` is now overridden, and the
+marketplace branch is asserted against a fixture rather than a machine.
+
+## [3.4.1] - 2026-09-04
+
+### Fixed — the SessionStart hook could not survive a missing runtime (#18)
+
+`hooks/session-start.js` imported `@theglitchking/claude-plugin-runtime` statically. That
+package resolves out of the shared `~/.claude/plugins/npm-cache/`, which a marketplace
+plugin cache does not carry itself, so when it could not resolve the **entire hook died** —
+`ERR_MODULE_NOT_FOUND` before any of its work ran.
+
+That took down the drift warning and `autoRepair` along with the update check: the two
+things #10 built precisely so a fix could reach an install that is already broken. The
+delivery path had a single point of failure the payload was meant to survive.
+
+- **The runtime is loaded lazily now**, in a try/catch returning `null`. A resolution
+  failure costs only the update check; the completion nudge, drift warning and repair all
+  still run, and the hook emits its own valid `SessionStart` payload since nothing else
+  will.
+- **A failed repair no longer stamps the version.** `autoRepair` previously stamped
+  `repairedSkillsForVersion` regardless of outcome, to avoid retrying every session — which
+  turned a *transient* failure into a permanent one. Reproduced: one session without a
+  resolvable runtime marked 3.4.0 done, and the repair was then skipped forever even once
+  the runtime returned. It stamps on success only; a failure costs one spawn per session
+  while genuinely drifted, and the drift warning fires alongside it naming the manual fix.
+
+Both defects came from the #10 work and shipped in 3.4.0. Test suite grows to 125
+assertions, including a fixture with no `node_modules` at all.
+
 ## [3.4.0] - 2026-09-04
 
 ### Changed — only completed plans are gitignored (#15)

package/bin/persistent-planning.js

@@ -55,32 +55,6 @@ program
   .description("Persistent markdown-based planning for Claude Code.")
   .version(version);
 
-// The runtime's `update` resolves the installed version, finds none in a
-// marketplace-only install, prints "Current: (not installed) / Now: (not installed)"
-// and exits 0 -- a clean success for a no-op. Fail before it gets that far, and say
-// where we looked. Same defect as runRelink's missing third probe (issue #10, fix #4).
-// Deliberately NOT including the package this CLI runs from: under
-// `npx --no @theglitchking/persistent-planning update` that copy always exists, which
-// is what let the original bug report see a clean exit 0 for a no-op. Only a *managed*
-// install -- a project dependency or a marketplace plugin root -- is updatable.
-function installCandidates(cwd) {
-  const out = [join(cwd, "node_modules", "@theglitchking", "persistent-planning", "package.json")];
-  if (process.env.CLAUDE_PLUGIN_ROOT) out.push(join(process.env.CLAUDE_PLUGIN_ROOT, "package.json"));
-  return out;
-}
-
-program.hook("preAction", (_thisCmd, actionCmd) => {
-  if (actionCmd.name() !== "update") return;
-  const candidates = installCandidates(process.cwd());
-  if (candidates.some((p) => existsSync(p))) return;
-  console.error("update failed: no managed install of @theglitchking/persistent-planning found.");
-  console.error("Looked in:");
-  for (const p of candidates) console.error(`  ${p}`);
-  console.error("\nInstall it with `npm i -D @theglitchking/persistent-planning`,");
-  console.error("or update the marketplace plugin with `/plugin` inside Claude Code.");
-  process.exit(1);
-});
-
 registerUpdateCommands(program, {
   packageName: PKG,
   pluginName: "persistent-planning",

package/hooks/session-start.js

@@ -3,6 +3,11 @@
 //
 // Three jobs:
 //   1. The update check, delegated entirely to @theglitchking/claude-plugin-runtime.
+//      That import is dynamic on purpose: the runtime resolves out of the shared
+//      ~/.claude/plugins/npm-cache/, which is not guaranteed to be populated. A
+//      static import made an unresolvable runtime fatal for the WHOLE hook, taking
+//      jobs 2-4 down with it — including the repair that is the only way a fix
+//      reaches an already-broken install. Jobs 2-4 need no runtime at all.
 //   2. A completion nudge: if any plan under .planning/ has every box checked
 //      but is still sitting in the active tree, say so, so the agent archives it
 //      instead of rediscovering a finished plan next session.
@@ -14,13 +19,23 @@
 //      node_modules in the plugin cache and never runs npm postinstall -- so it is
 //      the only delivery path a fix can reach existing broken installs through.
 
-import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { driftedSkills, readSkillVersion } from "../scripts/lib/skill-link.js";
 
+// Resolve the runtime lazily. Returns null when it cannot be loaded, which costs
+// only the update check — never the drift warning or the repair.
+async function loadRunSessionStart() {
+  try {
+    const mod = await import("@theglitchking/claude-plugin-runtime");
+    return typeof mod?.runSessionStart === "function" ? mod.runSessionStart : null;
+  } catch {
+    return null;
+  }
+}
+
 const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -96,14 +111,18 @@ function autoRepair() {
       timeout: 10000,
     });
 
-    // Stamp regardless of outcome: a repair that cannot succeed must not retry every
-    // session. A later release moves the version and gets one fresh attempt.
+    // Stamp only on success. Stamping a failure turns a transient problem — an
+    // unresolvable runtime, a locked file — into a permanent one: the version is
+    // marked done and the repair never runs again, even once the cause is gone.
+    // A failure costs one spawn per session while genuinely drifted, and the drift
+    // warning fires alongside it naming the manual fix, so nobody is stuck silently.
+    const remaining = driftedSkills(projectRoot, packageRoot, "skills");
+    if (remaining.length || r.status !== 0) return "";      // let driftNudge() report it
+
     try {
       writeFileSync(CONFIG, JSON.stringify({ ...cfg, repairedSkillsForVersion: version }, null, 2) + "\n", "utf8");
-    } catch { /* config unwritable — the drift warning still fires every session */ }
+    } catch { /* config unwritable — worst case the repair is attempted again */ }
 
-    const remaining = driftedSkills(projectRoot, packageRoot, "skills");
-    if (remaining.length || r.status !== 0) return "";      // let driftNudge() report it
     return "[persistent-planning] repaired a stale skill directory (originals kept as .bak-*).";
   } catch {
     return "";
@@ -147,12 +166,27 @@ function driftNudge() {
 const repaired = autoRepair();
 const notice = [planNudge(), repaired, driftNudge()].filter(Boolean).join("\n\n");
 
-if (!notice) {
-  await runSessionStart({
-    packageName: "@theglitchking/persistent-planning",
-    pluginName: "persistent-planning",
-    configFile: "persistent-planning.json",
-  });
+const runSessionStart = await loadRunSessionStart();
+const RUNTIME_OPTS = {
+  packageName: "@theglitchking/persistent-planning",
+  pluginName: "persistent-planning",
+  configFile: "persistent-planning.json",
+};
+
+function emitNoticeOnly() {
+  // No runtime, so nobody else will emit the response. Say our piece and stop.
+  if (!notice) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: notice },
+    }) + "\n"
+  );
+}
+
+if (!runSessionStart) {
+  emitNoticeOnly();
+} else if (!notice) {
+  await runSessionStart(RUNTIME_OPTS);
 } else {
   // ponytail: the runtime owns the one SessionStart JSON response and exposes no
   // hook for appending to it, and a second response line on stdout is invalid.
@@ -179,11 +213,7 @@ if (!notice) {
     return realWrite(chunk, ...rest);
   };
 
-  await runSessionStart({
-    packageName: "@theglitchking/persistent-planning",
-    pluginName: "persistent-planning",
-    configFile: "persistent-planning.json",
-  });
+  await runSessionStart(RUNTIME_OPTS);
 
   // The runtime can return without emitting (e.g. it chdir-failed). Say our piece.
   if (!merged) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
@@ -55,7 +55,7 @@
   },
   "homepage": "https://github.com/TheGlitchKing/persistent-planning#readme",
   "dependencies": {
-    "@theglitchking/claude-plugin-runtime": "^0.1.0",
+    "@theglitchking/claude-plugin-runtime": "^0.1.1",
     "commander": "^14.0.0"
   },
   "devDependencies": {