eklavya 1.25.0 → 1.25.2

package/dist/migrate.js

@@ -10,34 +10,80 @@ function writeVersion(db, version) {
     db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
      ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(VERSION_KEY, String(version));
 }
+/**
+ * How long a process waits for another one's migration, whatever the caller's
+ * own `busy_timeout` says. A migration can be slow on a big database -- 014
+ * builds an index over every captured event -- and a session queued behind it
+ * that gives up after the usual five seconds crashes instead of starting late.
+ */
+export const MIGRATION_BUSY_TIMEOUT_MS = 60_000;
+function hasMeta(db) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get() !== undefined;
+}
 /**
  * Applies numbered SQL migrations in order, recording progress in `meta`.
  * Idempotent: re-running applies nothing. Returns the filenames applied.
+ *
+ * Safe when several processes migrate one file at once -- every session and
+ * every hook opens the database, so after an upgrade they all do. Each
+ * migration runs in a `BEGIN IMMEDIATE` transaction that re-reads the version
+ * once it holds the write lock, so a process that lost the race skips what the
+ * winner applied instead of re-running it. Reading the version outside the
+ * lock and trusting it is what let six processes all try the same
+ * `ALTER TABLE ... ADD COLUMN`, and every one but the first die on "duplicate
+ * column name". IMMEDIATE rather than the default DEFERRED because a deferred
+ * transaction reads first and upgrades later, and in WAL mode that upgrade
+ * fails at once (SQLITE_BUSY_SNAPSHOT) instead of waiting.
+ *
+ * An up-to-date database takes no write lock at all: the version is read
+ * unlocked first, and only a pending migration queues for the lock.
  */
 export function runMigrations(db, dir = migrationsDir()) {
-    // Bootstrap `meta` itself so the version read below has somewhere to look.
-    db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
-    const current = readVersion(db);
     const files = fs
         .readdirSync(dir)
         .filter((f) => f.endsWith('.sql'))
-        .sort();
-    const applied = [];
-    for (const file of files) {
+        .sort()
+        .map((file) => {
         const n = Number(file.slice(0, 3));
         if (!Number.isFinite(n) || n === 0) {
             throw new Error(`Migration filename must start with a number: ${file}`);
         }
-        if (n <= current)
-            continue;
-        const sql = fs.readFileSync(path.join(dir, file), 'utf8');
+        return { file, n };
+    });
+    // The fast path: nothing pending, nothing locked.
+    const bootstrapped = hasMeta(db);
+    const known = bootstrapped ? readVersion(db) : 0;
+    if (bootstrapped && files.every((f) => f.n <= known))
+        return [];
+    const callerTimeout = Number(db.pragma('busy_timeout', { simple: true }));
+    db.pragma(`busy_timeout = ${Math.max(callerTimeout, MIGRATION_BUSY_TIMEOUT_MS)}`);
+    try {
+        // Bootstrap `meta` itself under the same lock as everything else.
         db.transaction(() => {
-            db.exec(sql);
-            writeVersion(db, n);
-        })();
-        applied.push(file);
+            db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+        }).immediate();
+        const applied = [];
+        for (const { file, n } of files) {
+            if (n <= known)
+                continue;
+            const sql = fs.readFileSync(path.join(dir, file), 'utf8');
+            const ran = db.transaction(() => {
+                // Re-read under the lock: another process may have applied it while we
+                // were queued, and running an ALTER TABLE twice is an error, not a no-op.
+                if (readVersion(db) >= n)
+                    return false;
+                db.exec(sql);
+                writeVersion(db, n);
+                return true;
+            }).immediate();
+            if (ran)
+                applied.push(file);
+        }
+        return applied;
+    }
+    finally {
+        db.pragma(`busy_timeout = ${callerTimeout}`);
     }
-    return applied;
 }
 export function schemaVersion(db) {
     return readVersion(db);

package/dist/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAErC,SAAS,WAAW,CAAC,EAAY;IAC/B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,WAAW,CAEjE,CAAC;IACd,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,YAAY,CAAC,EAAY,EAAE,OAAe;IACjD,EAAE,CAAC,OAAO,CACR;2DACuD,CACxD,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAY,EAAE,GAAG,GAAG,aAAa,EAAE;IAC/D,2EAA2E;IAC3E,EAAE,CAAC,IAAI,CAAC,6EAA6E,CAAC,CAAC;IAEvF,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,EAAE;SACb,WAAW,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjC,IAAI,EAAE,CAAC;IAEV,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,gDAAgD,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,OAAO;YAAE,SAAS;QAE3B,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1D,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;YAClB,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACb,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/dist/paths.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -82,4 +83,52 @@ export function projectConfigPath(repoRoot) {
 export function projectPacksDir(repoRoot) {
     return path.join(projectsDir(), projectSlug(repoRoot), 'packs');
 }
+/**
+ * Private to the person whose history it is.
+ *
+ * `~/.eklavya` holds every prompt, edit and answer Eklavya has seen, and it was
+ * created 0755 with a 0644 database: readable by every other account on a
+ * shared machine. The directory is now 0700 and the files in it 0600.
+ *
+ * Existing installs are tightened on the next open, but only when the path is
+ * ours (a directory somebody pointed `EKLAVYA_HOME` at on purpose, owned by
+ * another account, is left as found) and never at the cost of a failure: a
+ * filesystem that refuses `chmod` (Windows, some network mounts) still gets a
+ * working Eklavya.
+ */
+export function makePrivate(target, wanted) {
+    try {
+        const st = fs.statSync(target);
+        const uid = process.getuid?.();
+        if (uid === undefined || st.uid !== uid)
+            return;
+        if ((st.mode & 0o777 & ~wanted) !== 0)
+            fs.chmodSync(target, st.mode & 0o777 & wanted);
+    }
+    catch {
+        // Best effort, by design: see above.
+    }
+}
+/** Creates `~/.eklavya` 0700 if it is missing, and tightens it if it is looser. */
+export function ensureEklavyaHome() {
+    const home = eklavyaHome();
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    makePrivate(home, 0o700);
+    return home;
+}
+/**
+ * High, unassigned, and deliberately boring to collide with.
+ *
+ * The low 5000s are where every dev server lands — Vite alone walks 5173, 5174,
+ * 5175 upward as it finds ports taken — so a default down there is a default
+ * you have to override. This sits above the registered services in /etc/services
+ * and below the 49152+ ephemeral range the OS hands out for outbound sockets,
+ * so neither end can claim it first. (1729 is the Hardy–Ramanujan number, which
+ * is as good a reason as any to remember it.)
+ *
+ * Lives here, not in `dashboard.ts`, because the SessionStart hook probes it on
+ * every session and importing the dashboard module drags in zod and the memory
+ * worker for one number.
+ */
+export const DEFAULT_PORT = 41729;
 //# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,0EAA0E;AAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eklavya",
   "displayName": "Eklavya",
-  "version": "1.25.0",
+  "version": "1.25.2",
   "description": "Learn while your agent works. Turns coding-agent generation time into adaptive, Socratic learning grounded in the code being written.",
   "author": {
     "name": "Ajay Kumar"

package/dist/plugin/cli/CLAUDE.md

@@ -15,10 +15,22 @@ drives it through `/bin/sh`.
 ## It is opt-in, twice over
 
 Nothing in `eklavya install` puts this on a repo. `scripts/install-git-hook.sh`
-does, as a separate step the user runs per repo; it writes `.git/hooks/pre-commit`
-between the `# >>> eklavya gate >>>` markers, and if a `pre-commit` already
-existed it moves it to `pre-commit.local` and chains it first. `--uninstall`
-restores it.
+does, as a separate step the user runs per repo; it writes `pre-commit` in the
+**common** git directory's `hooks/` (so a linked worktree gets the main
+checkout's hook, which is the one git runs), between the `# >>> eklavya gate >>>`
+markers, and if a `pre-commit` already existed it moves it to `pre-commit.local`
+and chains it first. `--uninstall` restores it. Re-running it rewrites an older
+Eklavya hook in place. With `core.hooksPath` set (husky, lefthook) it installs
+nothing, prints the line to add to the manager's hook, and exits 2.
+
+The installed hook does not `exec` this file at a fixed path any more. It runs
+the first that exists of `~/.eklavya/runtime/node_modules/eklavya/dist/plugin/cli/eklavya-gate`
+(honouring `EKLAVYA_RUNTIME` and `EKLAVYA_HOME`) and the path the installer ran
+from, with `sh` so a lost executable bit cannot block. If neither exists the
+commit goes through with one stderr line. The old fixed-path `exec` meant a
+plugin update that moved the directory made every commit fail — the one failure
+this gate must never have. `eklavya uninstall` warns about the hook and prints
+the command to remove it; it never deletes it.
 
 Then the script itself only acts on a project whose config sets `quiz.enforced`
 (or the retired `"mode": "enforced"`, which it still reads). That config is at

package/dist/plugin/hooks/CLAUDE.md

@@ -23,6 +23,21 @@ back to `npx eklavya@<pinned> serve` and a hook starts a detached background
 `npm install` (once an hour at most, claimed by a `.installing` stamp before
 spawning) and exits 0 saying nothing.
 
+The same heal keeps an **installed** runtime current. The plugin moves when
+Claude Code updates it; the runtime only moves when npm runs. So when the entry
+resolved to `~/.eklavya/runtime` and its `package.json` version is older than
+`plugin.json`'s, `healIfBehind` starts that background install before the
+import — this run still uses the old runtime and never waits. It never
+downgrades (migrations only go forward), and leaves an `EKLAVYA_RUNTIME` or
+checkout build alone. `eklavya doctor`'s `versions` row reports the skew.
+
+The `npx` fallback retries `eklavya@latest` once, and only when npm says the
+pinned version does not exist (`E404`/`ETARGET`/`No matching version`). That is
+the release gap: semantic-release pushes the bumped `plugin.json` in its
+`prepare` step, before `npm publish`, so a marketplace pull can pin a version
+npm does not have yet for a minute or so. A server that started and then failed
+is not restarted.
+
 **It carries no version number.** It reads `.claude-plugin/plugin.json` at
 runtime, and `mcp/test/packaging.test.ts` asserts the file matches no
 `\d+\.\d+\.\d+` anywhere and does match `plugin\.json` — so writing any dotted
@@ -32,12 +47,15 @@ else.
 
 ## The seven hooks, out of `hooks.json`
 
+Seven scripts on six events: `checkpoint-quiz` is registered twice under
+PostToolUse, so the table has eight rows.
+
 | Event | Matcher | Timeout | Script | Job |
 |---|---|---|---|---|
-| SessionStart | — | 10s | `session-start` | stamp this checkout's session pointer (`meta.current_session:<repo root>`), replay the spool, summarise the last session's batch, recall this project's memory, show the developer the profile banner (`systemMessage`) and hand the model the recall and the standing log directive (`additionalContext`) |
+| SessionStart | — | 10s | `session-start` | stamp this checkout's session pointer (`meta.current_session:<repo root>`), replay the spool, summarise the last session's batch, recall this project's memory, show the developer the profile banner (`systemMessage`) and hand the model the recall and the standing log directive (`additionalContext`). A database that exists but will not open gets one line to the developer — `Eklavya paused · can't open its database · run: eklavya doctor`, or the SQLite/Node-mismatch variant — and a first run with no database stays silent |
 | UserPromptSubmit | — | 10s | `prompt-submit-nudge` | re-stamp this checkout's session pointer, then re-state the log directive in one line, but only for a session that has logged nothing after a grace window |
 | SubagentStart | — | 10s | `subagent-start` | give a delegated agent the log directive the parent's SessionStart never reached it with |
-| PreToolUse | `Bash` | 10s | `pre-tool-gate` | with `quiz.enforced` only, deny a `git commit` whose session gate has not passed |
+| PreToolUse | `Bash` | 10s | `pre-tool-gate` | with `quiz.enforced` only, deny a `git commit` (or `git merge --continue`) whose session gate has not passed. `commit-lib.ts` lexes the command like a shell — newlines, `env`/`sudo`/`timeout`/`VAR=x` prefixes, `bash -c`, subshells, substitutions, `git -C dir` — and accepts missing aliases and scripts: the git hook is the real enforcement |
 | PostToolUse | — | 10s | `capture-tool` | record the tool use as memory evidence |
 | PostToolUse | `mcp__.*log_session_concepts` | 10s | `checkpoint-quiz` | one mid-task question, `interleaved` cadence only |
 | PostToolUse | `^(Bash\|Edit\|Write\|MultiEdit\|NotebookEdit)$` | 10s | `checkpoint-quiz` | the same hook, re-armed by the work: the model logs once per task, so without this the checkpoint asked once per task. No `statusMessage` — it would flash on every command |
@@ -59,7 +77,19 @@ word `off` denied it, so `session-start` now says on screen which half stopped.
 the prompt; `capture-tool` captures the tool use; `stop-quiz-check` closes the
 batch at the seam. `mcp/src/hooks/memory-lib.ts` holds the shared helpers, and
 every one of them swallows its own failures — a capture path that throws is a
-throw on every tool call.
+throw on every tool call. The light capture path — `identityOf`, `record`,
+`batchIfFull` — lives in `capture-lib.ts`, so `capture-tool` and
+`prompt-submit-nudge` never import the worker, the provider, recall or notify;
+`memory-lib.ts` re-exports them for the seam hooks, and
+`mcp/test/hook-isolation.test.ts` fails if a hot path starts loading a heavy
+module again.
+
+A Stop seam does not close a batch every turn: only at `SEAM_MIN_EVENTS` (8)
+or once the oldest open event is `SEAM_MAX_AGE_MS` (20 minutes) old, because
+with an observer configured every closed batch is a `claude -p` call. A session
+start closes everything. The same seam runs the retention sweep
+(`pruneIfDue`, at most every six hours, 5,000 events at a time) and gives all
+notification sinks one shared 5s budget (`NOTIFY_BUDGET_MS`).
 
 The seam never waits on inference. With `providers.observer` configured,
 `flushAtSeam` queues the batch and hands it to a detached `eklavya memory

package/dist/plugin/hooks/run.mjs

@@ -30,6 +30,11 @@
  * alone gets you a working MCP server immediately, and the first session heals
  * the rest in the background.
  *
+ * The same heal keeps rule 3 current. The plugin updates itself through Claude
+ * Code (a marketplace pull, `/plugin update`); the runtime only moves when npm
+ * runs. So when the runtime is older than the plugin pins, this run still uses
+ * it — never blocking — and a background install brings it up to the pin.
+  *
  * Hard rule: a hook must never break a session. Everything here
  * fails to exit 0 in silence.
  */
@@ -60,6 +65,44 @@ function pinnedVersion() {
   }
 }
 
+/** The version of the runtime `eklavya install` wrote, or null. One small JSON read. */
+function runtimeVersion() {
+  try {
+    const manifest = path.join(runtimeHome, 'node_modules', 'eklavya', 'package.json');
+    return JSON.parse(readFileSync(manifest, 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when version `a` is older than `b`, comparing the numeric parts; a prerelease tag is ignored. */
+function olderThan(a, b) {
+  const parts = (v) => String(v).split('-')[0].split('.').map((n) => Number(n) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d < 0;
+  }
+  return false;
+}
+
+/**
+ * Starts the background heal when the runtime at `entry` is behind the plugin.
+ *
+ * Only for the runtime directory: an EKLAVYA_RUNTIME build or a development
+ * checkout is somebody's deliberate choice. And only when it is BEHIND — a
+ * runtime ahead of the plugin (a plugin rolled back, or updated late) is left
+ * alone, because migrations only go forward and an older runtime may not
+ * understand a database the newer one has already moved. `eklavya doctor`
+ * reports the skew either way.
+ */
+function healIfBehind(entry) {
+  if (!entry.startsWith(path.join(runtimeHome, 'node_modules', 'eklavya') + path.sep)) return;
+  const installed = runtimeVersion();
+  const pinned = pinnedVersion();
+  if (installed && pinned && olderThan(installed, pinned)) healInBackground();
+}
+
 /** The compiled entry point for `name`, or null if no build is reachable. */
 function resolveEntry() {
   const relative = name === 'server' ? ['dist', 'server.js'] : ['dist', 'hooks', `${name}.js`];
@@ -147,6 +190,9 @@ async function main() {
   const entry = resolveEntry();
 
   if (entry) {
+    // Before the import: a server never returns from it, and the heal is a
+    // detached spawn that costs this run nothing.
+    healIfBehind(entry);
     await import(pathToFileURL(entry).href);
     return;
   }
@@ -157,12 +203,30 @@ async function main() {
     // land there.
     const version = pinnedVersion();
     if (!version) process.exit(0);
+    //
+    // A release pushes the bumped plugin.json before `npm publish` finishes
+    // (semantic-release commits in its prepare step and publishes after), so a
+    // marketplace pull can pin a version npm does not have for a minute or so.
+    // Only that failure — npm saying the version does not exist — retries with
+    // `latest`; a server that started and then failed is not restarted.
     const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    const child = spawn(npx, ['--yes', `eklavya@${version}`, 'serve'], {
-      stdio: ['inherit', 'inherit', 'ignore'],
-      shell: process.platform === 'win32',
-    });
-    child.on('exit', (code) => process.exit(code ?? 0));
+    const serve = (spec, retry) => {
+      const child = spawn(npx, ['--yes', `eklavya@${spec}`, 'serve'], {
+        stdio: ['inherit', 'inherit', 'pipe'],
+        shell: process.platform === 'win32',
+      });
+      let errText = '';
+      // Kept draining past the cap, or a chatty server would block on stderr.
+      child.stderr.on('data', (chunk) => {
+        if (errText.length < 64 * 1024) errText += chunk;
+      });
+      child.on('error', () => process.exit(0));
+      child.on('exit', (code) => {
+        if (code && retry && /E404|ETARGET|No matching version/i.test(errText)) serve('latest', false);
+        else process.exit(code ?? 0);
+      });
+    };
+    serve(version, true);
     return;
   }
 

package/dist/plugin/scripts/install-git-hook.sh

@@ -4,6 +4,11 @@
 # replacing it.
 #
 #   scripts/install-git-hook.sh [--uninstall] [repo-path]
+#
+# Exit status: 0 installed, updated, already there, or uninstalled; 1 an error
+# (not a repository, or two existing hooks it will not choose between); 2 not
+# installed because core.hooksPath hands hooks to a hook manager -- the message
+# says how to call the gate from there instead.
 
 set -eu
 
@@ -14,69 +19,154 @@ REPO_ARG=""
 for arg in "$@"; do
   case "$arg" in
     --uninstall) UNINSTALL=1 ;;
-    -h|--help) sed -n '2,8p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,11p' "$0"; exit 0 ;;
     *) REPO_ARG=$arg ;;
   esac
 done
 
-CLI_PATH=$(cd "$(dirname "$0")/../cli" && pwd)/eklavya-gate
-REPO=${REPO_ARG:-$(git rev-parse --show-toplevel 2>/dev/null || true)}
+# Not `cd ../cli`: under `set -e` a missing cli/ would abort even --uninstall.
+CLI_PATH=$(cd "$(dirname "$0")/.." && pwd -P)/cli/eklavya-gate
 
+# A path argument may be anywhere inside the checkout; git names the top.
+REPO=$(cd "${REPO_ARG:-.}" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null) || REPO=''
 if [ -z "$REPO" ]; then
-  printf 'Not inside a git repository, and no path given.\n' >&2
+  if [ -n "$REPO_ARG" ]; then
+    printf '%s is not inside a git repository.\n' "$REPO_ARG" >&2
+  else
+    printf 'Not inside a git repository, and no path given.\n' >&2
+  fi
   exit 1
 fi
 
-HOOK_DIR="$REPO/.git/hooks"
+# Hooks live in the *common* git directory. In a linked worktree `.git` is a
+# file, not a directory, and every worktree runs the main checkout's hooks, so
+# `$REPO/.git/hooks` is wrong there. `--git-common-dir` may answer relative to
+# the checkout, hence the `cd` before resolving it.
+COMMON=$(cd "$REPO" && git rev-parse --git-common-dir 2>/dev/null) || COMMON=''
+COMMON=$(cd "$REPO" && cd "$COMMON" 2>/dev/null && pwd -P) || COMMON=''
+if [ -z "$COMMON" ]; then
+  printf 'Could not find the git directory for %s.\n' "$REPO" >&2
+  exit 1
+fi
+HOOK_DIR="$COMMON/hooks"
 HOOK="$HOOK_DIR/pre-commit"
 CHAINED="$HOOK_DIR/pre-commit.local"
 
+# "Is something there", counting a symlink whose target is gone: `[ -f ]` says
+# no to that, and writing the hook would then write through the dangling link.
+exists() { [ -e "$1" ] || [ -L "$1" ]; }
+ours() { [ -f "$1" ] && grep -q "$MARKER" "$1" 2>/dev/null; }
+
 if [ "$UNINSTALL" -eq 1 ]; then
-  if [ -f "$HOOK" ] && grep -q "$MARKER" "$HOOK" 2>/dev/null; then
+  if ours "$HOOK"; then
     rm -f "$HOOK"
-    if [ -f "$CHAINED" ]; then
+    if exists "$CHAINED"; then
       mv "$CHAINED" "$HOOK"
       printf 'Removed the Eklavya gate and restored your previous pre-commit hook.\n'
     else
       printf 'Removed the Eklavya gate.\n'
     fi
   else
-    printf 'No Eklavya gate installed here.\n'
+    printf 'No Eklavya gate installed in %s.\n' "$HOOK_DIR"
   fi
   exit 0
 fi
 
-mkdir -p "$HOOK_DIR"
+# A hook manager (husky, lefthook, pre-commit) sets core.hooksPath, and git
+# then never runs $HOOK. Installing there anyway would report a gate that never
+# fires; writing into the manager's directory would put Eklavya into a folder
+# that is usually committed. So neither: say how to call the gate from the
+# manager, and exit non-zero so nobody mistakes this for an installed gate.
+# The printed line must fail open too, and must not be the `[ -f X ] && sh X`
+# shape: pasted last in a hook, a missing file makes that line -- and so the
+# hook -- exit 1, blocking every commit. `if` exits 0 when its test fails.
+HOOKS_PATH=$(cd "$REPO" && git config --get core.hooksPath 2>/dev/null) || HOOKS_PATH=''
+if [ -n "$HOOKS_PATH" ]; then
+  cat >&2 <<EOF
+Not installed: this repository sets core.hooksPath to "$HOOKS_PATH" (a hook
+manager such as husky or lefthook), so git never runs $HOOK.
 
-if [ -f "$HOOK" ] && grep -q "$MARKER" "$HOOK" 2>/dev/null; then
-  printf 'Eklavya gate already installed in %s\n' "$HOOK"
-  exit 0
+To gate commits, add this line to the pre-commit hook your manager runs:
+
+  g="\${EKLAVYA_RUNTIME:-\${EKLAVYA_HOME:-\$HOME/.eklavya}/runtime}/node_modules/eklavya/dist/plugin/cli/eklavya-gate"; if [ -f "\$g" ]; then sh "\$g" || exit \$?; fi
+
+It holds a commit only when this project sets quiz.enforced and the session
+quiz has not passed. It names the installed runtime copy, which plugin updates
+keep at the same path, and if that file is ever missing the line does nothing,
+so your commits keep working.
+EOF
+  exit 2
 fi
 
-# Preserve whatever was there. The existing hook keeps running, first.
-if [ -f "$HOOK" ]; then
-  if [ -f "$CHAINED" ]; then
-    printf 'Refusing to overwrite: both %s and %s already exist.\n' "$HOOK" "$CHAINED" >&2
-    exit 1
+mkdir -p "$HOOK_DIR"
+
+if ours "$HOOK"; then
+  UPGRADE=1
+else
+  UPGRADE=0
+  # Preserve whatever was there. The existing hook keeps running, first.
+  if exists "$HOOK"; then
+    if exists "$CHAINED"; then
+      # Two hooks and one slot: moving either would lose one, so neither moves.
+      printf 'Not installed: %s and %s both exist, and neither is the Eklavya gate.\n' "$HOOK" "$CHAINED" >&2
+      printf 'Merge them into one pre-commit hook, then run this again.\n' >&2
+      exit 1
+    fi
+    mv "$HOOK" "$CHAINED"
+    printf 'Moved your existing pre-commit hook to %s; it will still run first.\n' "$CHAINED"
   fi
-  mv "$HOOK" "$CHAINED"
-  printf 'Moved your existing pre-commit hook to %s; it will still run first.\n' "$CHAINED"
 fi
 
-cat > "$HOOK" <<EOF
+# Where the hook looks for the gate at commit time, in order:
+#
+#   1. the installed runtime, ~/.eklavya/runtime/.../dist/plugin/cli/. It is
+#      the copy `eklavya install` and the plugin keep current, at a path that
+#      does not change between versions;
+#   2. the path this installer ran from, which a plugin update may delete.
+#
+# If neither is there the commit goes through with one line on stderr. The hook
+# used to `exec` path 2 unconditionally, so the next plugin update made every
+# commit in the repository fail -- the one failure this gate must never have.
+# Run with `sh` rather than exec'd, so a lost executable bit cannot block either.
+# Escaped for the double-quoted string it lands in, so a checkout path holding
+# a quote, backslash, backtick or dollar sign cannot break (or run code in) it.
+CLI_QUOTED=$(printf '%s' "$CLI_PATH" | sed 's/[\\"$`]/\\&/g')
+TMP="$HOOK_DIR/.pre-commit.eklavya-tmp.$$"
+trap 'rm -f "$TMP"' EXIT
+cat > "$TMP" <<EOF
 #!/bin/sh
 $MARKER
-# Installed by Eklavya. Remove with scripts/install-git-hook.sh --uninstall
+# Installed by Eklavya. Remove with "install-git-hook.sh --uninstall" from the
+# plugin's scripts/ directory, or delete this file.
 
 if [ -x "\$(dirname "\$0")/pre-commit.local" ]; then
   "\$(dirname "\$0")/pre-commit.local" "\$@" || exit \$?
 fi
 
-exec "$CLI_PATH"
+for gate in \\
+  "\${EKLAVYA_RUNTIME:-\${EKLAVYA_HOME:-\${HOME:-}/.eklavya}/runtime}/node_modules/eklavya/dist/plugin/cli/eklavya-gate" \\
+  "$CLI_QUOTED"
+do
+  [ -f "\$gate" ] && exec sh "\$gate"
+done
+
+printf 'eklavya: commit gate not found, so this commit is not gated. Run "npx eklavya install" to restore it, or delete %s to stop this message.\\n' "\$0" >&2
+exit 0
 # <<< eklavya gate <<<
 EOF
+chmod 755 "$TMP"
+
+if [ "$UPGRADE" -eq 1 ] && cmp -s "$TMP" "$HOOK"; then
+  printf 'Eklavya gate already installed in %s\n' "$HOOK"
+  exit 0
+fi
+mv -f "$TMP" "$HOOK"
+trap - EXIT
 
-chmod +x "$HOOK"
-printf 'Installed the Eklavya commit gate in %s\n' "$HOOK"
+if [ "$UPGRADE" -eq 1 ]; then
+  printf 'Updated the Eklavya commit gate in %s\n' "$HOOK"
+else
+  printf 'Installed the Eklavya commit gate in %s\n' "$HOOK"
+fi
 printf 'It only acts on projects whose config sets quiz.enforced. That config lives at\n'
 printf '~/.eklavya/projects/<checkout>/config.json, never inside the repository.\n'

package/dist/plugin/skills/CLAUDE.md

@@ -40,7 +40,7 @@ So, for `tutor` and anything else without `disable-model-invocation`:
 number of questions, never the order of the tool calls, never the grading.
 Those live in the body, which is where the model has to go to get them.
 
-The eight slash commands are exempt, and it is not a technicality:
+The nine slash commands are exempt, and it is not a technicality:
 `disable-model-invocation: true` means the model never matches on their
 description at all. The developer types the command and the description is its
 one line of help, so those should say what they do. `agents/tutor.md` keeps one

package/dist/plugin/skills/setup/SKILL.md

@@ -8,7 +8,9 @@ disable-model-invocation: true
 
 Get Eklavya working on this machine. Be brief; this should take one exchange.
 
-**1. Check prerequisites.** Run `node --version`. That is the whole list — the server, the CLI and all seven hooks are Node, so nothing else has to be on `PATH`. Node must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.
+**1. Check prerequisites.** Run `node --version`. Node is the only hard requirement — the server, the CLI and all seven hooks are Node. It must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.
+
+Two command-line tools matter for less: `sqlite3`, which step 2 uses to look at the database, and `jq`, which together with `sqlite3` the terminal commit gate in step 4 needs. Check with `command -v sqlite3 jq`. Missing ones do not stop setup — say which is missing and how to install it on this platform, skip the shell check in step 2 if it is `sqlite3`, and if they choose enforced, say plainly that commits made outside Claude Code will not be gated until both are installed. The gate lets commits through without them rather than blocking.
 
 Optionally run `eklavya doctor`, which reports the same thing plus the runtime, the SQLite driver, the plugin's registration, the chat skill, the database and the effective config. It exits non-zero and names the repair — `eklavya install` — if any of those has broken. That is also the command to reach for later, whenever Eklavya has gone quiet: the hooks never fail loudly, so a broken install looks exactly like a quiet one.
 
@@ -46,7 +48,12 @@ The `PreToolUse` hook only covers commits made inside Claude Code — which incl
 "${CLAUDE_PLUGIN_ROOT}"/scripts/install-git-hook.sh
 ```
 
-It chains to any existing `pre-commit` hook rather than replacing it, and only acts on projects whose config sets `quiz.enforced` (or the retired `"mode": "enforced"`) — so installing it is safe even if they turn enforcement off later. Mention `--uninstall` restores the previous hook.
+It works from a linked worktree too (all worktrees of a repository share one hook), chains to any existing `pre-commit` hook rather than replacing it, and only acts on projects whose config sets `quiz.enforced` (or the retired `"mode": "enforced"`) — so installing it is safe even if they turn enforcement off later. If the plugin moves or updates, the hook finds the gate in `~/.eklavya/runtime`, and if it finds none it lets the commit through with a one-line warning; it never blocks a commit because a file is missing. Mention `--uninstall` restores the previous hook.
+
+Read its exit status rather than assuming it worked:
+
+- **2** — the repository sets `core.hooksPath` (husky, lefthook and similar), so git would never run the hook and nothing was installed. Relay the line it printed: they add it to the `pre-commit` hook their manager runs. Do not edit their hook manager's files yourself — those are usually committed.
+- **1** — not a git repository, or a `pre-commit` and a `pre-commit.local` both already exist and it will not choose between them. Relay the message; nothing was changed.
 
 Skip this step unless they chose enforced.
 

package/dist/plugin/skills/tutor/references/focus-and-level.md

@@ -178,6 +178,13 @@ into the batch it replaced.
   once: the gate exists, here is what it needs, let's get through it. Supportive,
   not punitive. Never imply they are being punished.
 
+  While the gate is open the plan holds only this session's own work — no
+  review, no widening, since neither counts toward the gate. Items with
+  `reason: "gate_work"` are this session's concepts even when the learner has
+  mastered them in another session since: they are on the gate's list, so ask
+  them normally. Do not skip one because the profile says it is mastered, or
+  the gate can become impossible to pass.
+
   A blank grades 0, and 0 never passes the gate — so a session answered entirely
   with "I don't know" would leave nothing to ask and a commit that can never go
   through. When that happens the plan comes back with `reason: "gate_retry"`: the