@theglitchking/persistent-planning 3.4.0 → 3.4.1

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.1"
   },
   "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.1",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "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,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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/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.1",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {