llm-wiki-kit 0.2.12 → 0.2.14

package/README.md

@@ -133,7 +133,7 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `llm-wiki update --check [--to <version-or-tag>]` is the online update check. It compares the installed package version with the npm registry target without changing files, and reports an available update only when the target version is newer than the installed version.
 
-`llm-wiki update` upgrades the global npm package when npm has a newer target, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. If the installed runtime already satisfies the registry target, it skips `npm install -g` and still runs post-update maintenance. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten. The command prints step progress to stderr, including registry lookup, npm install, post-update, and project discovery. Use `--timeout-ms <ms>` to bound external commands and `--max-dirs <n>` to bound project discovery under large or slow roots such as WSL `/mnt/*` trees.
+`llm-wiki update` upgrades the global npm package when npm has a newer target, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. Before installing, it checks whether `npm root -g` points at the active runtime package root; after installing, it verifies the active runtime and `post-update` runtime reached the registry target. If either check fails, it exits nonzero and prints the exact runtime/npm roots plus the manual install/post-update commands to run. If the installed runtime already satisfies the registry target, it prints an already-current result, skips `npm install -g`, and still runs post-update maintenance. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten. The command prints step progress to stderr, including registry lookup, npm root/prefix checks, npm install, post-update, and project discovery. Use `--timeout-ms <ms>` to bound external commands and `--max-dirs <n>` to bound project discovery under large or slow roots such as WSL `/mnt/*` trees.
 
 Installed npm runtimes also perform a cached update notice check from hooks while the user works. This does not install anything automatically. When a newer npm release is detected, Codex and Claude receive the same passive runtime update status in hook context: current runtime, npm registry target, and the manual command to use when the user asks for update or maintenance work. It is not an instruction to interrupt the current answer or to sell the update to the user. The cache is scoped to the npm command used for lookup so test/fake npm checks do not leak into normal hook sessions. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only when diagnosing or suppressing that status block.
 

package/docs/manual.md

@@ -163,10 +163,13 @@ Most users should not need these during daily coding. They are for install, upda
 
 - runs `npm install -g llm-wiki-kit@<target>` only when needed;
 - skips npm install when the installed runtime already satisfies the target;
-- restarts into the updated binary for post-update work;
+- checks that `npm root -g` points at the active runtime package root before installing;
+- verifies that the active runtime and `post-update` runtime reached the registry target after installing;
+- exits nonzero instead of printing `updated` when `npm install -g` succeeds but the active runtime is still old;
 - reinstalls hooks without duplicating them;
 - updates only managed project templates and policy blocks;
 - preserves user-edited files and curated wiki contents;
+- prints before/after runtime, registry target, npm global root, active runtime root, and PATH command diagnostics;
 - prints progress to stderr so JSON stdout remains parseable;
 - supports `--timeout-ms` and `--max-dirs` for slow npm, WSL, or large search roots.
 

package/docs/operations.md

@@ -127,7 +127,9 @@ Installed npm runtimes also run a cached hook-side update notice check while the
 
 - runs `npm install -g llm-wiki-kit@<target>` only when the registry target is newer than the installed runtime
 - skips npm installation when the installed runtime already satisfies the target, then still runs post-update maintenance
-- restarts into the updated binary for `post-update`
+- checks `npm root -g`/`npm prefix -g` before install and refuses to claim success when npm would update a different global prefix than the active runtime
+- verifies that the active runtime and `post-update` child runtime reached the registry target after install
+- prints before/after runtime, registry target, npm global root, active runtime root, and PATH command diagnostics
 - reinstalls hook entries without duplicating them
 - patches only managed project files across known or discovered project roots
 - backs up changed files under `~/.local/share/llm-wiki-kit/backups/`

package/docs/troubleshooting.md

@@ -113,6 +113,8 @@ If the proxy performs TLS inspection, install the organization's CA and set `caf
 
 If `npm install -g llm-wiki-kit@latest` succeeds but `llm-wiki --help` does not show newer commands such as `projects`, `context`, `lint`, or `consolidate`, the shell is probably executing an older source checkout or stale shim before the npm global binary.
 
+Newer `llm-wiki update` releases diagnose this before claiming success. If the npm global root does not match the active runtime root, or if `npm install -g` exits 0 but the active runtime is still old, `update` exits nonzero with details such as `active runtime root`, `npm global root`, `runtime before`, `runtime after`, and `command matches runtime`. On root-owned Linux prefixes, run the printed `sudo npm install -g llm-wiki-kit@<target>` command, then run the printed `llm-wiki post-update ...` command as the normal Codex/Claude user.
+
 Confirm what is actually running:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Hook-first living Markdown wiki runtime for Codex and Claude Code with Korean/English prompt-aware guidance.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -348,13 +348,26 @@ function formatUpdate(value) {
       `- project template skipped: ${skipped}`,
     ].join('\n');
   }
+  const title = value.updateApplied
+    ? 'llm-wiki-kit updated'
+    : 'llm-wiki-kit already current; post-update complete';
   return [
-    'llm-wiki-kit updated',
+    title,
     `- workspace: ${value.workspace}`,
-    `- before: ${value.before}`,
+    `- runtime before: ${value.runtimeBefore || value.before}`,
+    `- registry target: ${value.latest || value.target}`,
+    `- runtime after: ${value.runtimeAfter || 'unknown'}`,
+    ...(value.postUpdateRuntime ? [`- post-update runtime: ${value.postUpdateRuntime}`] : []),
+    `- runtime verified: ${value.runtimeVerified ? 'yes' : 'no'}`,
+    `- npm install: ${value.npmInstall?.skipped ? 'skipped' : 'ran'}`,
     `- target: ${value.target}`,
+    `- active runtime root: ${value.activePackageRoot || 'unknown'}`,
+    `- npm global root: ${value.npmGlobal?.root || 'unknown'}`,
+    `- command: ${value.command?.path || 'not found'}`,
+    `- command matches runtime: ${value.command?.matchesRuntime ? 'yes' : 'no'}`,
     `- scope: ${value.scope || 'current'}`,
     ...(value.projects ? [`- projects updated: ${value.projects.length}`] : []),
+    ...((value.warnings || []).map((warning) => `- warning: ${warning}`)),
   ].join('\n');
 }
 

package/src/update.js

@@ -3,10 +3,10 @@ import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
 import { install } from './install.js';
-import { isWindows } from './platform.js';
+import { commandMatchesRuntime, commandPaths, isWindows, sameResolvedPath } from './platform.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { knownProjectRoots, recordProject } from './projects.js';
-import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
+import { binPath, detectInstallSource, packageName, packageRoot, runtimeVersion } from './version.js';
 
 function commandLine(command, args) {
   return [command, ...args].join(' ');
@@ -26,6 +26,7 @@ async function runCommand(command, args, options = {}) {
   const label = options.label || commandLine(command, args);
   const startedAt = Date.now();
   const windows = isWindows(options);
+  const useShell = options.shell !== undefined ? options.shell : windows;
   const detached = !windows;
   let stdout = '';
   let stderr = '';
@@ -69,7 +70,7 @@ async function runCommand(command, args, options = {}) {
       child = spawn(command, args, {
         detached,
         env: options.env || process.env,
-        shell: windows,
+        shell: useShell,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
     } catch (error) {
@@ -115,6 +116,10 @@ function binCommand() {
   return process.env.LLM_WIKI_KIT_BIN || binPath;
 }
 
+function packageSpec(target) {
+  return `${packageName()}@${target}`;
+}
+
 function assertCommandOk(result, label) {
   if (result.status === 0 && !result.error) return;
   const detail = result.stderr.trim() ||
@@ -125,6 +130,45 @@ function assertCommandOk(result, label) {
   throw new Error(`${label} failed: ${detail}`);
 }
 
+function postUpdateCommand(workspace, options = {}) {
+  const command = ['llm-wiki', 'post-update'];
+  if (shouldUpdateAllProjects(options)) command.push('--all');
+  command.push('--workspace', workspace);
+  return command.join(' ');
+}
+
+function formatRemediation(workspace, target, options = {}) {
+  const install = isWindows(options)
+    ? `npm install -g ${packageSpec(target)}`
+    : `sudo npm install -g ${packageSpec(target)}`;
+  return [
+    'Run the npm install command that owns the active runtime, then reapply hooks/templates:',
+    `  ${install}`,
+    `  ${postUpdateCommand(workspace, options)}`,
+    'Then verify:',
+    `  llm-wiki status --workspace ${workspace}`,
+  ].join('\n');
+}
+
+function createUpdateVerificationError(message, diagnostics = {}, workspace, target, options = {}) {
+  const lines = [
+    'llm-wiki-kit update did not update the active runtime.',
+    message,
+  ];
+  if (diagnostics.registryTarget) lines.push(`- registry target: ${diagnostics.registryTarget}`);
+  if (diagnostics.runtimeBefore) lines.push(`- runtime before: ${diagnostics.runtimeBefore}`);
+  if (diagnostics.runtimeAfter) lines.push(`- runtime after: ${diagnostics.runtimeAfter}`);
+  if (diagnostics.activePackageRoot) lines.push(`- active runtime root: ${diagnostics.activePackageRoot}`);
+  if (diagnostics.npmRoot) lines.push(`- npm global root: ${diagnostics.npmRoot}`);
+  if (diagnostics.npmPackageRoot) lines.push(`- npm target package root: ${diagnostics.npmPackageRoot}`);
+  if (diagnostics.commandPath) lines.push(`- command on PATH: ${diagnostics.commandPath}`);
+  if (diagnostics.commandMatchesRuntime !== undefined) {
+    lines.push(`- command matches runtime: ${diagnostics.commandMatchesRuntime ? 'yes' : 'no'}`);
+  }
+  lines.push(formatRemediation(workspace, target, options));
+  return Object.assign(new Error(lines.join('\n')), { diagnostics });
+}
+
 async function hasProjectWiki(projectRoot) {
   return exists(join(projectRoot, 'llm-wiki', 'wiki'));
 }
@@ -190,6 +234,74 @@ export function compareVersions(a, b) {
   return left.prerelease > right.prerelease ? 1 : -1;
 }
 
+async function npmGlobalInfo(options = {}) {
+  const rootResult = await runCommand(npmCommand(), ['root', '-g'], {
+    ...options,
+    label: 'npm root -g',
+    timeout: options.timeout || 30000,
+  });
+  assertCommandOk(rootResult, 'npm root -g');
+  const prefixResult = await runCommand(npmCommand(), ['prefix', '-g'], {
+    ...options,
+    label: 'npm prefix -g',
+    timeout: options.timeout || 30000,
+  });
+  assertCommandOk(prefixResult, 'npm prefix -g');
+  const root = rootResult.stdout.trim().split(/\r?\n/).at(-1) || '';
+  const prefix = prefixResult.stdout.trim().split(/\r?\n/).at(-1) || '';
+  return {
+    root,
+    prefix,
+    packageRoot: root ? join(root, packageName()) : '',
+  };
+}
+
+async function commandInfo(options = {}) {
+  const paths = await commandPaths('llm-wiki', options);
+  const commandPath = paths[0] || null;
+  const matchesRuntime = await commandMatchesRuntime(commandPath, binPath, {
+    ...options,
+    installSource: detectInstallSource(),
+  });
+  return {
+    path: commandPath,
+    paths,
+    matchesRuntime: Boolean(matchesRuntime),
+  };
+}
+
+function runtimeSatisfiesTarget(runtime, targetVersion) {
+  return compareVersions(runtime, targetVersion) >= 0;
+}
+
+function rootMatchesActiveRuntime(npmPackageRoot) {
+  return sameResolvedPath(npmPackageRoot, packageRoot) ||
+    resolve(npmPackageRoot || '') === resolve(packageRoot);
+}
+
+async function preflightRuntimeUpdate(check, workspace, target, options = {}) {
+  const npmGlobal = await npmGlobalInfo(options);
+  const command = await commandInfo(options);
+  if (check.updateAvailable && detectInstallSource() === 'npm' && !rootMatchesActiveRuntime(npmGlobal.packageRoot)) {
+    throw createUpdateVerificationError(
+      'The active llm-wiki runtime is not under the npm global root that this update command would modify.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        activePackageRoot: packageRoot,
+        npmRoot: npmGlobal.root,
+        npmPackageRoot: npmGlobal.packageRoot,
+        commandPath: command.path,
+        commandMatchesRuntime: command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
+  return { npmGlobal, command };
+}
+
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
@@ -297,9 +409,10 @@ export async function update(options = {}) {
   }
 
   const target = options.to || 'latest';
+  const beforeDiagnostics = await preflightRuntimeUpdate(check, workspace, target, options);
   const shouldRunNpmInstall = check.updateAvailable;
   const installResult = shouldRunNpmInstall
-    ? await runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+    ? await runCommand(npmCommand(), ['install', '-g', packageSpec(target)], {
       ...options,
       label: 'npm install -g',
       timeout: options.timeout || 120000,
@@ -310,6 +423,25 @@ export async function update(options = {}) {
       stderr: '',
     };
   assertCommandOk(installResult, 'npm install -g');
+  const runtimeAfterInstall = runtimeVersion();
+  if (shouldRunNpmInstall && !runtimeSatisfiesTarget(runtimeAfterInstall, check.latestVersion)) {
+    throw createUpdateVerificationError(
+      'npm install -g exited successfully, but the active runtime version did not change to the registry target.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        runtimeAfter: runtimeAfterInstall,
+        activePackageRoot: packageRoot,
+        npmRoot: beforeDiagnostics.npmGlobal.root,
+        npmPackageRoot: beforeDiagnostics.npmGlobal.packageRoot,
+        commandPath: beforeDiagnostics.command.path,
+        commandMatchesRuntime: beforeDiagnostics.command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
 
   const postArgs = [binCommand(), 'post-update', '--workspace', workspace, '--json'];
   if (shouldUpdateAllProjects(options)) postArgs.push('--all');
@@ -324,17 +456,52 @@ export async function update(options = {}) {
       LLM_WIKI_KIT_PROGRESS: process.env.LLM_WIKI_KIT_PROGRESS || '1',
     },
     label: 'post-update',
+    shell: false,
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');
   const parsedPostUpdate = parseJsonOutput(postResult.stdout);
+  const postRuntimeVersion = parsedPostUpdate?.runtimeVersion || null;
+  if (shouldRunNpmInstall && postRuntimeVersion && !runtimeSatisfiesTarget(postRuntimeVersion, check.latestVersion)) {
+    throw createUpdateVerificationError(
+      'post-update ran, but it did not run from the registry target runtime.',
+      {
+        registryTarget: check.latestVersion,
+        runtimeBefore: check.installedVersion,
+        runtimeAfter: postRuntimeVersion,
+        activePackageRoot: packageRoot,
+        npmRoot: beforeDiagnostics.npmGlobal.root,
+        npmPackageRoot: beforeDiagnostics.npmGlobal.packageRoot,
+        commandPath: beforeDiagnostics.command.path,
+        commandMatchesRuntime: beforeDiagnostics.command.matchesRuntime,
+      },
+      workspace,
+      target,
+      options
+    );
+  }
+  const afterCommand = await commandInfo(options);
+  const warnings = [];
+  if (!afterCommand.matchesRuntime) {
+    warnings.push(`llm-wiki command on PATH does not resolve to the active runtime: ${afterCommand.path || 'not found'}`);
+  }
 
   return {
     mode: 'update',
     workspace,
     before: check.installedVersion,
     target,
+    latest: check.latestVersion,
+    runtimeBefore: check.installedVersion,
+    runtimeAfter: runtimeAfterInstall,
+    postUpdateRuntime: postRuntimeVersion,
+    updateApplied: shouldRunNpmInstall,
+    runtimeVerified: runtimeSatisfiesTarget(runtimeAfterInstall, check.latestVersion),
     scope: shouldUpdateAllProjects(options) ? 'all' : 'current',
+    activePackageRoot: packageRoot,
+    npmGlobal: beforeDiagnostics.npmGlobal,
+    command: afterCommand,
+    warnings,
     npmInstall: {
       skipped: !shouldRunNpmInstall,
       stdout: installResult.stdout.trim(),