knodin 0.10.0 → 0.10.1

package/dist/src/init.js

@@ -7,7 +7,7 @@ import { compareBytes } from "./compare.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
 import { lookupMirror } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
-import { acquireRepairLease } from "./repair-lease.js";
+import { acquireRepairLease, LIFECYCLE_LEASE_TOKEN_ENV } from "./repair-lease.js";
 import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
@@ -357,10 +357,29 @@ export async function refreshFromGitEvent(repo, event, index) {
     }
 }
 function backgroundScript(command) {
-    const invocation = command.map(shellQuote).join(" ");
+    // The interpreter is resolved at RUN time, not baked in. `process.execPath`
+    // is symlink-resolved by Node, so a stable `/opt/homebrew/bin/node` becomes
+    // a version-pinned `/opt/homebrew/Cellar/node/<version>/bin/node`. Homebrew
+    // deletes that directory on upgrade, and every hook generated beforehand
+    // then dies with exit 127 — silently, because refresh runs in the
+    // background, so the graph just stops keeping up.
+    //
+    // The generated path stays PREFERRED, so nothing changes while it exists;
+    // the fallback only engages once it does not. Falling back first would
+    // silently switch which runtime executes, which is its own bug.
+    const [interpreter, ...rest] = command;
+    const invocation = ['"$KNODIN_NODE"', ...rest.map(shellQuote)].join(" ");
+    const preferred = shellQuote(interpreter ?? process.execPath);
     return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u
+KNODIN_NODE=${preferred}
+if [ ! -x "$KNODIN_NODE" ]; then
+  KNODIN_NODE="$(command -v node 2>/dev/null || true)"
+  # No interpreter at all: fall through to the recorded path so the failure is
+  # the existing loud "not found", not a silent no-op.
+  [ -n "$KNODIN_NODE" ] || KNODIN_NODE=${preferred}
+fi
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$REPO_ROOT" ] || exit 0
 cd "$REPO_ROOT" || exit 0
@@ -460,7 +479,7 @@ function refreshProcessorIsRunning(repo) {
         return false;
     }
 }
-function drainQueuedLifecycleEvents(repo, backgroundPath) {
+function drainQueuedLifecycleEvents(repo, backgroundPath, leaseToken) {
     const before = queuedLifecycleEvents(repo);
     if (before.length === 0)
         return { state: "fresh", queuedEvents: 0 };
@@ -469,6 +488,13 @@ function drainQueuedLifecycleEvents(repo, backgroundPath) {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: 30_000,
+        // The caller holds the lifecycle lease while this runs. Without handing
+        // the token down, the child re-enters knodin, meets its own parent's
+        // lease, and refuses — so the drain could never succeed and init
+        // reported failure on every run.
+        env: leaseToken
+            ? { ...process.env, [LIFECYCLE_LEASE_TOKEN_ENV]: leaseToken }
+            : { ...process.env },
     });
     if (result.status !== 0) {
         const detail = result.error?.message || result.stderr.trim() || `exit ${result.status ?? "unknown"}`;
@@ -1289,7 +1315,7 @@ export async function initializeRepository(repo, options) {
         if (isIndexResult(indexResult) && indexResult.verification.status !== "healthy") {
             throw new InitializationHealthError(indexResult);
         }
-        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath);
+        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath, lifecycleLease.token);
         await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), {
             force: true,
         });

package/dist/src/mcp-worker-supervisor.js

@@ -200,8 +200,19 @@ export class RepositoryWorker extends EventEmitter {
         }
         const { requestId, operation } = context;
         try {
+            // Same race as the startup one below, one phase earlier: the queueAbort
+            // arm above reports CLIENT_DISCONNECTED, and this re-check reported
+            // CANCELLED for the identical event whenever the queue wait resolved in
+            // the same instant the abort landed.
+            //
+            // The supervisor observes only "the signal aborted" and cannot tell a
+            // disconnect from an explicit cancel; every abort-listener arm here
+            // already calls that a disconnect, so the re-checks now agree with them.
+            // The distinction belongs to the layer that knows why the signal fired —
+            // superviseMcpRequest, which raises REQUEST_CANCELLED for a client
+            // cancellation it can actually identify.
             if (signal.aborted)
-                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled before worker dispatch");
+                throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected before worker dispatch");
             if (!this.child) {
                 if (this.restartTimes.length >= MAX_RESTARTS)
                     throw codedError("KNODIN_RESTART_LIMIT", "graph worker restart limit reached");
@@ -233,8 +244,20 @@ export class RepositoryWorker extends EventEmitter {
                 if (startupAbort)
                     signal.removeEventListener("abort", startupAbort);
             });
+            // Same event as the startupAbort arm above, same code. Both describe an
+            // abort arriving during worker startup; which one reports it is decided
+            // by whether the startup race settles as ready or as aborted in the same
+            // instant. Reporting different codes made the SAME client disconnect
+            // surface as CLIENT_DISCONNECTED or REQUEST_CANCELLED depending on
+            // scheduling — stable on an idle machine, unstable under load, which is
+            // worse than a consistently wrong value because it invites trust.
+            //
+            // These codes name a CAUSE, not a phase. classifyMcpFailure maps them to
+            // distinct kinds in the reliability journal, so the race was also
+            // recording one disconnect under two kinds and silently contaminating
+            // any disconnect-versus-cancellation rate computed from it.
             if (signal.aborted)
-                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled during worker startup");
+                throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected during worker startup");
             const predecessorTraceId = this.lastFailureTraceId;
             if (predecessorTraceId)
                 recordMcpLifecycle(context, "restart", { predecessorTraceId });

package/dist/src/repair-lease.js

@@ -92,10 +92,34 @@ function removeStaleLeaseOrThrow(target, operation) {
             throw error;
     }
 }
+/**
+ * Environment channel by which a lease holder tells a process it spawns that
+ * the lease it is about to meet is its OWN.
+ *
+ * `knodin init` holds the lease and then drains the queued lifecycle refresh by
+ * spawning the background hook, which re-enters knodin and tries to take the
+ * same lease. Without this the child sees a live pid — its own parent — and
+ * refuses, so init can never drain its own queue and reports failure on every
+ * run while telling the user to run init again.
+ */
+export const LIFECYCLE_LEASE_TOKEN_ENV = "KNODIN_LIFECYCLE_LEASE_TOKEN";
 /** Atomically serialize repair post-processing across independent CLI/MCP processes. */
 export function acquireRepairLease(repo, operation = "repair") {
     const target = leasePath(repo);
     fs.mkdirSync(path.dirname(target), { recursive: true });
+    // Re-entrant ONLY for a token that matches the lease actually on disk. A
+    // stale or forged token falls through to the normal contention check, so a
+    // genuinely concurrent mutation from another process is still refused —
+    // this makes the lease stop blocking its own holder, it does not disable it.
+    const inheritedToken = process.env[LIFECYCLE_LEASE_TOKEN_ENV];
+    if (inheritedToken) {
+        const held = readLease(target);
+        if (held?.nonce === inheritedToken) {
+            // The holder releases it. Releasing here would drop the lock while the
+            // parent still believes it holds it.
+            return { release() { } };
+        }
+    }
     const lifecycleCommand = [
         "repair",
         "init",
@@ -124,6 +148,7 @@ export function acquireRepairLease(repo, operation = "repair") {
             writeLease(target, record);
             writeActivity(repo, record);
             return {
+                token: record.nonce,
                 release() {
                     try {
                         const current = readLease(target);

package/docs/releases/0.10.1.md

@@ -0,0 +1,83 @@
+# knodin 0.10.1
+
+Three defects, none of which a test suite would have found on its own. Two were
+found by upgrading knodin on a real machine: one only appears after Homebrew
+moves the Node binary, the other only when a lifecycle event is already queued.
+The third is a scheduling race that reported the same cause under two different
+codes, and it surfaced as an unrelated pre-push failure after six clean runs.
+
+## Background refresh survives a moved Node binary
+
+`knodin init` wrote the generated hook with a fully-resolved path to whichever
+Node was running at the time. `process.execPath` is symlink-resolved, so a
+stable `/opt/homebrew/bin/node` became a version-pinned
+`/opt/homebrew/Cellar/node/<version>/bin/node`.
+
+Homebrew deletes that directory on upgrade, so every hook written beforehand
+died with exit 127 — silently, because refresh runs in the background. The
+graph simply stopped keeping up, and only a `knodin status` run revealed it.
+It affected every repository initialized before the upgrade, not one.
+
+The hook now resolves its interpreter when it runs. The recorded path stays
+preferred, so nothing changes while it exists; `PATH` is consulted only once it
+does not. Falling back first would silently change which runtime executes,
+which is its own bug.
+
+Hooks generated before this release still carry the old absolute path. They
+keep failing until regenerated with `knodin init`; the fix prevents recurrence
+after the next Node upgrade rather than repairing them retroactively.
+
+## `knodin init` can drain its own lifecycle queue
+
+`init` takes the lifecycle lease, then drains queued events by spawning the
+background hook. The hook re-entered knodin, met the same lease, saw a live
+pid — its own parent — and refused. `init` reported "queued lifecycle refresh
+could not be drained (exit 1)" on every run, and `knodin status` then advised
+running `init`, which reproduced the failure exactly.
+
+Worse, the failed drain wrote a failure marker that `status` kept reporting, so
+a transient condition looked permanent while the graph was in fact intact — in
+the observed case 5,883 of 5,883 files indexed and 5,059 carrying symbols.
+
+A lease holder now passes its nonce to processes it spawns, and a child whose
+token matches the lease on disk is admitted re-entrantly. Re-entry returns a
+no-op release, because releasing there would drop the lock while the parent
+still believes it holds it.
+
+The lease is not weakened. A missing token, or one that does not match the
+lease on disk, still hits the existing contention check, so a genuinely
+concurrent mutation from another process is refused exactly as before.
+
+## One abort cause, one code
+
+Worker startup and queue admission are each a race between "ready" and
+"aborted". Each arm had an abort listener rejecting with
+`KNODIN_CLIENT_DISCONNECTED` and a follow-up `signal.aborted` re-check
+rejecting with `KNODIN_REQUEST_CANCELLED`, so the same client disconnect
+surfaced as either code depending on which arm settled first.
+
+That is worse than a consistently wrong code. It was stable on an idle machine
+and unstable under load, so it looked trustworthy everywhere anyone would have
+checked it — it surfaced as a pre-push gate failure on an unrelated change
+after six clean runs.
+
+It also fed the reliability journal, where the two codes map to distinct kinds.
+One disconnect was recorded under two kinds, quietly skewing any rate computed
+from them. **That contamination is retroactive and cannot be repaired:** journal
+entries written before this release cannot be reattributed, so a
+cancellation-versus-disconnect rate spanning the 0.10.1 boundary should be read
+as suspect rather than corrected.
+
+The taxonomy is unchanged. `superviseMcpRequest` can still tell an explicit
+cancellation from a disconnect; the supervisor cannot, so it now names only the
+cause it actually knows.
+
+## Homebrew formula retention
+
+The `Retain versioned Homebrew formula` job ran on a GitHub-hosted runner whose
+ephemeral IP is not on the organization's allow list, so it failed at checkout
+with a 403 on every release since it was added — and it cloned
+`knodin/knodin`, a stale source mirror, rather than `knodin/homebrew-tap`.
+
+Both are corrected. Every formula through 0.10.0 was retained by hand; this is
+the first release where that job can do it.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.0",
+	"version": "0.10.1",
 	"knodin": {
 		"compatibility": "breaking"
 	},
@@ -72,6 +72,7 @@
 		"docs/releases/0.8.7.md",
 		"docs/releases/0.9.0.md",
 		"docs/releases/0.10.0.md",
+		"docs/releases/0.10.1.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",