llm-wiki-kit 0.2.3 → 0.2.4

package/README.md

@@ -73,6 +73,7 @@ Use Claude Code or Codex normally.
 The installed hooks:
 
 - inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start, instructions loaded, prompt submit, and post-compact time
+- remove Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces at session start so `llm-wiki/` remains the active wiki implementation
 - record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
@@ -102,7 +103,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.
+`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.
 
 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, the injected hook context gives the active agent a Korean update reminder and tells it to offer `llm-wiki update --workspace <project-or-search-root>`. 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 reminder.
 
@@ -118,6 +119,8 @@ Installed npm runtimes also perform a cached update notice check from hooks whil
 
 `llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state or an older `llm-wiki/wiki/index.md`, and shows the update commands to run. `llm-wiki update --workspace /apps` updates the global runtime once, then reapplies managed templates across every known or discovered project root under `/apps`.
 
+For `llm-wiki-kit` code releases, source tests are not enough. After code changes, publish the package, install the newly published version, and verify the installed CLI and hooks with `version`, `status`, `doctor`, `update`, `lint`, and hook smoke checks before calling the release complete.
+
 After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. Clearly generated older `llm-wiki/AGENTS.md` and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.
 
 `llm-wiki install` no longer creates a user-local `~/.local/bin/llm-wiki` shim when an npm/nvm global `llm-wiki` command already resolves to the current runtime. If an older kit-managed local shim is shadowing that npm command, install backs it up and removes it.

package/docs/integrations/claude-code.md

@@ -16,7 +16,7 @@ The installed hook stores the Node executable and the absolute package binary pa
 
 User-local fallback installs may instead point under `$HOME/.local/lib/node_modules`.
 
-Handled events:
+Handled events on compatible Claude Code versions:
 
 - `SessionStart`
 - `InstructionsLoaded`
@@ -30,6 +30,8 @@ Handled events:
 - `Stop`
 - `SessionEnd`
 
+`llm-wiki install` detects `claude --version` and installs a conservative event set when the local Claude Code binary is older or cannot be detected. `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `SubagentStop`, and `Stop` are treated as the stable set. `InstructionsLoaded`, `PostToolBatch`, and `SessionEnd` are installed only for newer compatible versions, or when `LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS=1` is set. Existing kit-managed hooks for unsupported event keys are removed during install so Claude Code does not skip the entire settings file with an “Invalid key in record” error.
+
 Claude Code reads `CLAUDE.md`. For project compatibility, the kit creates a `CLAUDE.md` stub containing:
 
 ```text

package/docs/integrations/codex.md

@@ -29,7 +29,7 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any Korean update notice, and any maintenance note for outdated or customized managed rules.
+- `SessionStart` first attempts a safe managed-template refresh, removes Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces when they reappear, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any Korean update notice, and any maintenance note for outdated or customized managed rules.
 - `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.

package/docs/manual.md

@@ -69,6 +69,7 @@ llm-wiki/
 - 사용자가 명시적으로 문서화/기록을 요청했는데 durable wiki 반영이 없으면 `outputs/maintenance/queue.md`에 정리 후보를 남긴다.
 - 이전 session이 깨끗하게 종료되지 않았을 때 stale turn state를 maintenance queue로 복구할 수 있다.
 - 새 runtime이 오래된 project rules/templates를 발견하면 안전하게 갱신 가능한 managed file만 refresh한다.
+- `SessionStart`/`InstructionsLoaded`에서 Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` 설정과 스킬 표면이 되살아났는지 확인하고 제거한다. wiki 기능은 `llm-wiki/`가 단일 활성 구현이다.
 
 매번 저장 여부를 사용자가 고민해야 한다면 잘못 쓰고 있는 것이다. 답변보다 wiki maintenance가 먼저 오면 안 된다. 현재 사용자 요청을 먼저 처리하고, 오래 쓸 지식만 필요한 만큼 정리한다.
 
@@ -141,11 +142,14 @@ llm-wiki update --workspace /path/to/search-root
 llm-wiki update --workspace /path/to/search-root --to 0.2.1
 llm-wiki update --workspace /path/to/project --current-only
 llm-wiki update --workspace /path/to/project --dry-run
+llm-wiki update --workspace /path/to/search-root --timeout-ms 120000 --max-dirs 5000
 ```
 
 `--check`는 network를 사용하지만 파일을 변경하지 않는다. installed version보다 registry target이 최신일 때만 update available을 보고한다.
 
-기본 `update --workspace <search-root>`는 runtime update를 한 번 수행한 뒤, known/discovered project roots의 managed templates를 재적용한다. 기존 wiki contents는 덮어쓰지 않는다.
+기본 `update --workspace <search-root>`는 runtime update를 한 번 수행한 뒤, known/discovered project roots의 managed templates를 재적용한다. 기존 wiki contents는 덮어쓰지 않는다. `update`는 registry lookup, npm install, post-update, project discovery 진행 상태를 stderr에 출력한다. JSON 모드에서도 stdout은 JSON만 유지하고 progress는 stderr로 분리한다.
+
+`--timeout-ms`는 `npm view`, `npm install -g`, internal `post-update` 같은 외부 command timeout을 지정한다. timeout 후 SIGTERM과 짧은 grace period 뒤 SIGKILL을 사용해 child process가 terminal을 계속 붙잡는 hard hang을 방지한다. `--max-dirs`는 search root 아래 project discovery가 검사할 최대 directory 수를 제한한다.
 
 `update`는 source checkout에서 self-update하지 않는다. source checkout 개발 중에는 npm package나 local tarball로 global install한 뒤 update behavior를 테스트한다.
 
@@ -416,12 +420,17 @@ publish 후 검증:
 
 ```bash
 npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
+npm install -g llm-wiki-kit@<published-version> --registry=https://registry.npmjs.org/ --prefer-online
 llm-wiki version
 llm-wiki manual
 llm-wiki status --workspace /apps
 llm-wiki doctor --workspace /apps
+llm-wiki update --workspace /apps --dry-run
+llm-wiki update --workspace /apps --current-only
 ```
 
+`llm-wiki-kit` 코드 변경 릴리스는 publish와 새 published version 설치 후 검증까지 끝나야 완료로 본다. root-owned global npm prefix에서는 package install에 `sudo npm install -g`가 필요할 수 있고, user home hook 갱신은 일반 user로 `llm-wiki install` 또는 `post-update`를 실행한다.
+
 ## Troubleshooting Shortcuts
 
 hook이 안 돈다면:

package/docs/operations.md

@@ -81,6 +81,7 @@ llm-wiki update --check --workspace /path/to/project [--to <version-or-tag>]
 llm-wiki update --workspace /path/to/search-root
 llm-wiki update --current-only --workspace /path/to/project
 llm-wiki update --dry-run --workspace /path/to/project
+llm-wiki update --workspace /path/to/search-root --timeout-ms 120000 --max-dirs 5000
 llm-wiki post-update --workspace /path/to/project
 llm-wiki post-update --all --workspace /path/to/search-root
 llm-wiki context "search phrase" --workspace /path/to/project
@@ -113,8 +114,10 @@ Installed npm runtimes also run a cached hook-side update notice check while the
 - 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/`
+- prints update progress to stderr and keeps JSON output parseable on stdout
+- force-kills unresponsive child commands after timeout so slow npm/WSL environments do not wait forever
 
-By default, `update --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every known or discovered project root under the search root. Use `update --current-only --workspace <project>` to limit template reapplication to one project.
+By default, `update --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every known or discovered project root under the search root. Use `update --current-only --workspace <project>` to limit template reapplication to one project. Use `--max-dirs` when a search root is a very large or slow tree.
 
 `post-update --workspace <project>` skips npm installation and reapplies the current runtime's hook entries plus safe managed template updates. `post-update --all --workspace <search-root>` does the same template reapplication across discovered project roots.
 

package/docs/troubleshooting.md

@@ -36,6 +36,35 @@ llm-wiki update --check --workspace /path/to/project
 
 `status` does not contact the network. `update --check` contacts npm but does not change files.
 
+## llm-wiki update Appears To Hang
+
+`update` runs `npm view`, optional `npm install -g`, project discovery, and `post-update`. It prints progress to stderr while keeping JSON output on stdout parseable. In slow WSL or Windows-mounted trees, start with a bounded dry run:
+
+```bash
+llm-wiki update --dry-run --workspace /path/to/project --current-only --timeout-ms 30000
+llm-wiki update --dry-run --workspace /path/to/search-root --max-dirs 1000 --timeout-ms 30000
+```
+
+If the current project succeeds but the search root is slow, use `--current-only` for that project or raise `--max-dirs` intentionally. If npm itself is slow, compare with:
+
+```bash
+npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
+```
+
+When a child command exceeds `--timeout-ms`, `update` terminates it and then force-kills it after a short grace period.
+
+## Claude Code Settings Error: Invalid Hook Key
+
+Some Claude Code versions reject newer hook event keys such as `PostToolBatch`. Run:
+
+```bash
+claude --version
+llm-wiki install --workspace /path/to/project --profile standard
+llm-wiki doctor --workspace /path/to/project
+```
+
+The installer detects the local Claude version, installs only compatible hook events, and removes kit-managed hooks for unsupported event keys. User-defined hooks are preserved when possible.
+
 ## npm Says The Package Is Not Found
 
 If `llm-wiki update --check` returns npm 404, the package is not published to the registry being used. Until publish, test npm installation with a local tarball:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/claude-compat.js

@@ -0,0 +1,83 @@
+import { spawnSync } from 'child_process';
+
+export const CLAUDE_STABLE_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'Stop',
+];
+
+export const CLAUDE_MODERN_EVENTS = [
+  'InstructionsLoaded',
+  'PostToolBatch',
+  'SessionEnd',
+];
+
+export const CLAUDE_MODERN_MIN_VERSION = '2.1.138';
+
+function parseVersion(value) {
+  return String(value || '')
+    .replace(/^v/, '')
+    .split('.', 3)
+    .map((part) => {
+      const parsed = Number.parseInt(part, 10);
+      return Number.isFinite(parsed) ? parsed : 0;
+    });
+}
+
+export function compareClaudeVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+export function parseClaudeVersionOutput(output) {
+  return String(output || '').match(/\b(\d+\.\d+\.\d+)\b/)?.[1] || '';
+}
+
+export function detectClaudeVersion(options = {}) {
+  if (process.env.LLM_WIKI_KIT_CLAUDE_VERSION) {
+    const version = process.env.LLM_WIKI_KIT_CLAUDE_VERSION;
+    return {
+      available: true,
+      version,
+      raw: version,
+      modern: compareClaudeVersions(version, CLAUDE_MODERN_MIN_VERSION) >= 0,
+    };
+  }
+
+  const command = options.command || process.env.LLM_WIKI_KIT_CLAUDE || 'claude';
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    timeout: options.timeout || 5000,
+  });
+  const raw = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  const version = parseClaudeVersionOutput(raw);
+  return {
+    available: result.status === 0 && !result.error,
+    version,
+    raw,
+    modern: Boolean(version) && compareClaudeVersions(version, CLAUDE_MODERN_MIN_VERSION) >= 0,
+    error: result.error?.message || null,
+  };
+}
+
+export function supportedClaudeEvents(detection = detectClaudeVersion()) {
+  if (process.env.LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS === '1') {
+    return [...CLAUDE_STABLE_EVENTS, ...CLAUDE_MODERN_EVENTS];
+  }
+  if (process.env.LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS === '0') {
+    return [...CLAUDE_STABLE_EVENTS];
+  }
+  return detection.modern
+    ? [...CLAUDE_STABLE_EVENTS, ...CLAUDE_MODERN_EVENTS]
+    : [...CLAUDE_STABLE_EVENTS];
+}

package/src/cli.js

@@ -32,6 +32,22 @@ function parseOptions(args) {
     } else if (arg === '--to') {
       options.to = optionValue(arg, i);
       i += 1;
+    } else if (arg === '--timeout-ms') {
+      const value = optionValue(arg, i);
+      const timeout = Number(value);
+      if (!Number.isInteger(timeout) || timeout < 1000) {
+        throw new Error('--timeout-ms must be an integer >= 1000');
+      }
+      options.timeout = timeout;
+      i += 1;
+    } else if (arg === '--max-dirs') {
+      const value = optionValue(arg, i);
+      const maxDirs = Number(value);
+      if (!Number.isInteger(maxDirs) || maxDirs < 1) {
+        throw new Error('--max-dirs must be a positive integer');
+      }
+      options.maxDirs = maxDirs;
+      i += 1;
     } else if (arg === '--no-codex') {
       options.codex = false;
     } else if (arg === '--no-claude') {
@@ -88,7 +104,7 @@ export async function runCli(args) {
 
 Usage:
   llm-wiki install --workspace /apps [--profile standard]
-  llm-wiki update --workspace <project-or-search-root> [--check|--dry-run|--current-only|--to <version-or-tag>]
+  llm-wiki update --workspace <project-or-search-root> [--check|--dry-run|--current-only|--to <version-or-tag>] [--timeout-ms 120000] [--max-dirs 5000]
   llm-wiki post-update --workspace <project> [--all]
   llm-wiki doctor --workspace <project>
   llm-wiki projects --workspace /apps
@@ -156,12 +172,21 @@ Usage:
   }
 
   if (command === 'update') {
-    printJsonOrText(await update(options), options, formatUpdate);
+    printJsonOrText(await update({
+      ...options,
+      onProgress: (message) => console.error(`[llm-wiki update] ${message}`),
+    }), options, formatUpdate);
     return;
   }
 
   if (command === 'post-update') {
-    printJsonOrText(await postUpdate(options), options, formatPostUpdate);
+    const postOptions = process.env.LLM_WIKI_KIT_PROGRESS === '1'
+      ? {
+        ...options,
+        onProgress: (message) => console.error(`[llm-wiki post-update] ${message}`),
+      }
+      : options;
+    printJsonOrText(await postUpdate(postOptions), options, formatPostUpdate);
     return;
   }
 
@@ -226,7 +251,7 @@ Usage:
 
 async function listProjects(options) {
   const workspace = resolve(options.workspace || process.cwd());
-  const roots = await knownProjectRoots({ workspace });
+  const roots = await knownProjectRoots({ workspace, maxDirs: options.maxDirs });
   const projects = [];
   for (const root of roots) {
     let state = null;
@@ -264,6 +289,8 @@ function formatStatus(value) {
     `- hooks current: ${value.hooksCurrent ? 'yes' : 'no'}`,
     `- codex hook: ${value.codexInstalled ? 'current' : 'missing/outdated'}`,
     `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,
+    `- claude version: ${value.claudeVersion || 'unknown'} (${value.claudeModernHooks ? 'modern hooks' : 'compatible hooks'})`,
+    `- claude unsupported kit hooks: ${(value.claudeUnsupportedKitEvents || []).join(', ') || 'none'}`,
     `- project applied runtime: ${project.lastRuntimeVersionApplied || 'unknown'}`,
     `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
     `- project auto-updateable rules: ${autoUpdateCount}`,

package/src/doctor.js

@@ -21,6 +21,12 @@ export async function runDoctor(options = {}) {
   add('command-path', 'llm-wiki command resolves to current runtime', stat.commandMatchesRuntime, stat.commandPath ? `command=${stat.commandPath}; runtime=${stat.binPath}` : 'command not found on PATH');
   add('codex-hook', 'Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
   add('claude-hook', 'Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
+  add(
+    'claude-settings-compatible',
+    'Claude hook settings compatible',
+    (stat.claudeUnsupportedKitEvents || []).length === 0,
+    `version=${stat.claudeVersion || 'unknown'}; unsupported=${(stat.claudeUnsupportedKitEvents || []).join(', ') || 'none'}`
+  );
   add('project-templates', 'project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
   add('codex-command', 'codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
   add('claude-command', 'claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
@@ -111,7 +117,7 @@ function doctorRemediation(result) {
     }
     suggestions.push(`reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
   }
-  if (failed(result, 'codex-hook') || failed(result, 'claude-hook')) {
+  if (failed(result, 'codex-hook') || failed(result, 'claude-hook') || failed(result, 'claude-settings-compatible')) {
     suggestions.push(`install hooks: llm-wiki install --workspace ${workspace} --profile standard, then restart Codex/Claude Code sessions`);
   }
   if (failed(result, 'project-templates')) {

package/src/hook.js

@@ -7,6 +7,7 @@ import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
 import { buildEntryFromState, clearTurnState, rememberQuestion, rememberTool } from './state.js';
 import { updateNoticeContext } from './update-notice.js';
+import { removeLegacyOmxWikiSurfaces } from './legacy-omx-wiki.js';
 import { relative } from 'path';
 
 async function readStdinJson() {
@@ -104,6 +105,13 @@ async function autoUpdateManagedProject(projectRoot, eventName) {
   }
 }
 
+async function removeLegacyWikiSurfaces(projectRoot, eventName) {
+  if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') return;
+  const result = await removeLegacyOmxWikiSurfaces();
+  if (!result.changed) return;
+  await appendWikiLog(projectRoot, `removed legacy oh-my-codex wiki surfaces: ${result.removed.length}`);
+}
+
 export async function handleHook(provider, explicitEvent) {
   const payload = await readStdinJson();
   payload.__provider = provider;
@@ -113,6 +121,7 @@ export async function handleHook(provider, explicitEvent) {
   await bootstrapProject(projectRoot);
   await recordProject(projectRoot, 'hook').catch(() => {});
   await autoUpdateManagedProject(projectRoot, eventName).catch(() => {});
+  await removeLegacyWikiSurfaces(projectRoot, eventName).catch(() => {});
   await appendSessionEnvelope(projectRoot, eventName, payload).catch(() => {});
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded' || eventName === 'UserPromptSubmit') {
     await recoverStaleTurnStates(projectRoot).catch(() => []);

package/src/install.js

@@ -2,7 +2,8 @@ import { realpathSync } from 'fs';
 import { chmod, lstat, readlink, unlink } from 'fs/promises';
 import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
-import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
+import { CODEX_EVENTS, KIT_NAME } from './constants.js';
+import { detectClaudeVersion, supportedClaudeEvents } from './claude-compat.js';
 import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { maintenanceSummary } from './maintenance.js';
 import { inspectProjectState } from './project-state.js';
@@ -50,6 +51,11 @@ function isKitPath(path) {
   return String(path || '').replace(/\\/g, '/').includes('/llm-wiki-kit/');
 }
 
+function isKitHookEntry(entry) {
+  const serialized = JSON.stringify(entry || {});
+  return serialized.includes(KIT_NAME) || serialized.includes(binPath) || serialized.includes('/llm-wiki-kit/');
+}
+
 async function inspectLocalBin(localBinPath) {
   try {
     const stat = await lstat(localBinPath);
@@ -145,18 +151,43 @@ function removeKitHooks(hooks) {
   let changed = false;
   for (const [eventName, entries] of Object.entries(hooks || {})) {
     if (!Array.isArray(entries)) continue;
-    const next = entries.filter((entry) => {
-      const serialized = JSON.stringify(entry);
-      return !serialized.includes(KIT_NAME) && !serialized.includes(binPath);
-    });
+    const next = entries.filter((entry) => !isKitHookEntry(entry));
     if (next.length !== entries.length) {
-      hooks[eventName] = next;
+      if (next.length > 0) hooks[eventName] = next;
+      else delete hooks[eventName];
       changed = true;
     }
   }
   return changed;
 }
 
+function removeUnsupportedKitClaudeHooks(hooks, supportedEvents) {
+  const supported = new Set(supportedEvents);
+  const removed = [];
+  for (const [eventName, entries] of Object.entries(hooks || {})) {
+    if (supported.has(eventName) || !Array.isArray(entries)) continue;
+    const next = entries.filter((entry) => !isKitHookEntry(entry));
+    if (next.length !== entries.length) {
+      removed.push(eventName);
+      if (next.length > 0) hooks[eventName] = next;
+      else delete hooks[eventName];
+    }
+  }
+  return [...new Set(removed)];
+}
+
+function unsupportedKitClaudeEvents(hooks, supportedEvents) {
+  const supported = new Set(supportedEvents);
+  return Object.entries(hooks || {})
+    .filter(([eventName, entries]) => (
+      !supported.has(eventName) &&
+      Array.isArray(entries) &&
+      entries.some((entry) => isKitHookEntry(entry))
+    ))
+    .map(([eventName]) => eventName)
+    .sort();
+}
+
 export async function install(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
   await chmod(binPath, 0o755).catch(() => {});
@@ -196,12 +227,19 @@ export async function install(options = {}) {
   if (options.claude !== false) {
     const claude = (await readJson(claudeSettingsPath, null)) || {};
     claude.hooks = claude.hooks || {};
+    const claudeDetection = detectClaudeVersion();
+    const claudeEvents = supportedClaudeEvents(claudeDetection);
     let claudeChanged = false;
     if (options.replaceHooks && removeKitHooks(claude.hooks)) {
       claudeChanged = true;
       changed.push('claude:replaced');
     }
-    for (const eventName of CLAUDE_EVENTS) {
+    const removedUnsupported = removeUnsupportedKitClaudeHooks(claude.hooks, claudeEvents);
+    if (removedUnsupported.length > 0) {
+      claudeChanged = true;
+      changed.push(...removedUnsupported.map((eventName) => `claude:removed-unsupported:${eventName}`));
+    }
+    for (const eventName of claudeEvents) {
       const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
       if (addHook(claude.hooks, eventName, hookCommand('claude', eventName), { matcher })) {
         claudeChanged = true;
@@ -260,8 +298,12 @@ export async function status(options = {}) {
   const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
   const codex = await readJson(codexHooksPath, {});
   const claude = await readJson(claudeSettingsPath, {});
+  const claudeDetection = detectClaudeVersion();
+  const claudeEvents = supportedClaudeEvents(claudeDetection);
+  const claudeMissingEvents = claudeEvents.filter((eventName) => !JSON.stringify(claude.hooks?.[eventName] || []).includes(binPath));
+  const claudeUnsupportedKitEvents = unsupportedKitClaudeEvents(claude.hooks || {}, claudeEvents);
   const codexInstalled = JSON.stringify(codex.hooks || {}).includes(binPath);
-  const claudeInstalled = JSON.stringify(claude.hooks || {}).includes(binPath);
+  const claudeInstalled = claudeMissingEvents.length === 0 && claudeUnsupportedKitEvents.length === 0;
   const commandPaths = llmWikiCommandPaths();
   const commandPath = commandPaths[0] || null;
   const resolvedCommandPath = realpathOrOriginal(commandPath);
@@ -280,6 +322,11 @@ export async function status(options = {}) {
     localBin,
     codexInstalled,
     claudeInstalled,
+    claudeVersion: claudeDetection.version || 'unknown',
+    claudeModernHooks: claudeDetection.modern,
+    claudeSupportedEvents: claudeEvents,
+    claudeMissingEvents,
+    claudeUnsupportedKitEvents,
     hooksCurrent: codexInstalled && claudeInstalled,
     codexHooksPath,
     claudeSettingsPath,

package/src/legacy-omx-wiki.js

@@ -0,0 +1,222 @@
+import { mkdtemp, rm, readdir, writeFile } from 'fs/promises';
+import { spawnSync } from 'child_process';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { backupFile, exists, homeDir, readJson, readText, writeJson, writeText } from './fs-utils.js';
+
+const CODEX_CONFIG = '.codex/config.toml';
+const TOML_TABLE = /^\s*\[([^\]]+)\]\s*$/;
+
+function normalizeTomlHeader(header) {
+  return String(header || '').replace(/\s+/g, '').replace(/'/g, '"');
+}
+
+function isLegacyOmxWikiTable(header) {
+  const normalized = normalizeTomlHeader(header);
+  if (normalized === 'mcp_servers.omx_wiki') return true;
+  return normalized.includes('oh-my-codex') &&
+    normalized.includes('.mcp_servers.omx_wiki');
+}
+
+export function removeLegacyOmxWikiTomlTables(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const output = [];
+  let changed = false;
+  let skipping = false;
+
+  for (const line of lines) {
+    const table = line.match(TOML_TABLE);
+    if (table) {
+      skipping = isLegacyOmxWikiTable(table[1]);
+      if (skipping) {
+        changed = true;
+        continue;
+      }
+    }
+    if (!skipping) output.push(line);
+  }
+
+  if (!changed) return { changed: false, text: String(text || '') };
+  return {
+    changed: true,
+    text: `${output.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/g, '')}\n`,
+  };
+}
+
+function sourceRootsFromConfig(text) {
+  const roots = new Set();
+  const sourceRe = /^\s*source\s*=\s*["']([^"']*oh-my-codex[^"']*)["']\s*$/gm;
+  let match;
+  while ((match = sourceRe.exec(String(text || '')))) {
+    roots.add(match[1]);
+  }
+  return roots;
+}
+
+function configuredPackageRoots(home, configText) {
+  const roots = new Set([
+    '/usr/lib/node_modules/oh-my-codex',
+    '/usr/local/lib/node_modules/oh-my-codex',
+    join(home, '.local', 'lib', 'node_modules', 'oh-my-codex'),
+  ]);
+  for (const root of sourceRootsFromConfig(configText)) roots.add(root);
+  for (const root of String(process.env.LLM_WIKI_KIT_OMX_WIKI_ROOTS || '').split(':').filter(Boolean)) {
+    roots.add(root);
+  }
+  return roots;
+}
+
+function safeLegacyWikiSkillDir(path) {
+  const normalized = resolve(path).replace(/\\/g, '/');
+  return /(?:^|\/)oh-my-codex(?:\/|$)/.test(normalized) &&
+    /\/skills\/wiki$/.test(normalized);
+}
+
+function safeLegacyWikiMcpPath(path) {
+  const normalized = resolve(path).replace(/\\/g, '/');
+  return /(?:^|\/)oh-my-codex(?:\/|$)/.test(normalized) &&
+    /\/\.mcp\.json$/.test(normalized);
+}
+
+async function collectCachedSkillDirs(root, maxDepth = 8) {
+  const found = [];
+  async function walk(dir, depth) {
+    if (depth < 0) return;
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const full = join(dir, entry.name);
+      const normalized = full.replace(/\\/g, '/');
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      if (entry.name === 'wiki' && normalized.includes('/oh-my-codex/') && normalized.includes('/skills/wiki')) {
+        found.push(full);
+        continue;
+      }
+      await walk(full, depth - 1);
+    }
+  }
+  await walk(root, maxDepth);
+  return found;
+}
+
+async function legacyWikiSkillDirs(home, configText) {
+  const dirs = new Set();
+  for (const root of configuredPackageRoots(home, configText)) {
+    dirs.add(join(root, 'skills', 'wiki'));
+    dirs.add(join(root, 'plugins', 'oh-my-codex', 'skills', 'wiki'));
+  }
+  for (const root of [
+    join(home, '.codex', 'plugins', 'cache'),
+    join(home, '.codex', '.tmp'),
+  ]) {
+    for (const dir of await collectCachedSkillDirs(root)) dirs.add(dir);
+  }
+  return [...dirs].filter(safeLegacyWikiSkillDir);
+}
+
+async function removeSkillDir(dir) {
+  if (!(await exists(dir))) return false;
+  try {
+    await rm(dir, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (!['EACCES', 'EPERM'].includes(error?.code)) throw error;
+  }
+  if (process.env.LLM_WIKI_KIT_OMX_WIKI_SUDO === '0') return false;
+  const result = spawnSync('sudo', ['-n', 'rm', '-rf', dir], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  return result.status === 0 && !(await exists(dir));
+}
+
+async function removePluginMcpEntry(path) {
+  const json = await readJson(path, null);
+  if (!json?.mcpServers?.omx_wiki) return false;
+  delete json.mcpServers.omx_wiki;
+  try {
+    await writeJson(path, json);
+  } catch (error) {
+    if (!['EACCES', 'EPERM'].includes(error?.code) || !safeLegacyWikiMcpPath(path)) throw error;
+    if (process.env.LLM_WIKI_KIT_OMX_WIKI_SUDO === '0') return false;
+    const tempDir = await mkdtemp(join(tmpdir(), 'llm-wiki-kit-mcp-'));
+    const tempPath = join(tempDir, '.mcp.json');
+    await writeFile(tempPath, `${JSON.stringify(json, null, 2)}\n`, 'utf8');
+    const result = spawnSync('sudo', ['-n', 'cp', tempPath, path], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    if (result.status !== 0) return false;
+  }
+  return true;
+}
+
+async function removeWritablePluginMcpEntries(home, configText) {
+  const changed = [];
+  const candidates = new Set();
+  for (const root of configuredPackageRoots(home, configText)) {
+    candidates.add(join(root, 'plugins', 'oh-my-codex', '.mcp.json'));
+  }
+  for (const root of [
+    join(home, '.codex', 'plugins', 'cache'),
+    join(home, '.codex', '.tmp'),
+  ]) {
+    const dirs = await collectCachedSkillDirs(root);
+    for (const dir of dirs) {
+      candidates.add(resolve(dir, '..', '..', '.mcp.json'));
+    }
+  }
+  for (const candidate of candidates) {
+    try {
+      if (await removePluginMcpEntry(candidate)) changed.push(candidate);
+    } catch {
+      // Root-owned package manifests may be read-only to the hook user. The
+      // active Codex config cleanup is the enforcement point in that case.
+    }
+  }
+  return changed;
+}
+
+export async function removeLegacyOmxWikiSurfaces(options = {}) {
+  if (process.env.LLM_WIKI_KIT_OMX_WIKI_GUARD === '0') {
+    return { changed: false, removed: [], configChanged: false };
+  }
+
+  const home = options.home || homeDir();
+  const configPath = options.configPath || join(home, CODEX_CONFIG);
+  const originalConfig = await readText(configPath, null);
+  const removed = [];
+  let configText = originalConfig || '';
+  let configChanged = false;
+
+  if (originalConfig !== null) {
+    const cleaned = removeLegacyOmxWikiTomlTables(originalConfig);
+    if (cleaned.changed) {
+      await backupFile(configPath, 'codex-config-before-omx-wiki-removal.toml');
+      await writeText(configPath, cleaned.text);
+      configText = cleaned.text;
+      configChanged = true;
+      removed.push('codex-config:omx_wiki');
+    }
+  }
+
+  for (const dir of await legacyWikiSkillDirs(home, configText)) {
+    if (await removeSkillDir(dir)) removed.push(`skill:${dir}`);
+  }
+
+  for (const path of await removeWritablePluginMcpEntries(home, configText)) {
+    removed.push(`mcp:${path}`);
+  }
+
+  return {
+    changed: removed.length > 0,
+    removed,
+    configChanged,
+  };
+}

package/src/projects.js

@@ -58,12 +58,17 @@ async function looksLikeProjectRoot(root) {
 export async function discoverProjectRoots(searchRoot, options = {}) {
   const root = resolve(searchRoot || process.cwd());
   const maxDirs = options.maxDirs || 5000;
+  const progressEvery = options.progressEvery || 1000;
+  const onProgress = typeof options.onProgress === 'function' ? options.onProgress : null;
   const roots = new Set();
   let seen = 0;
 
   async function walk(dir) {
     if (seen >= maxDirs) return;
     seen += 1;
+    if (onProgress && seen % progressEvery === 0) {
+      onProgress(`scanned ${seen}/${maxDirs} directories while discovering projects`);
+    }
 
     if (await looksLikeProjectRoot(dir)) {
       roots.add(dir);
@@ -91,6 +96,9 @@ export async function discoverProjectRoots(searchRoot, options = {}) {
   }
 
   await walk(root);
+  if (onProgress) {
+    onProgress(`project discovery scanned ${seen} director${seen === 1 ? 'y' : 'ies'}; found ${roots.size}`);
+  }
   return [...roots].sort();
 }
 

package/src/update.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
@@ -7,18 +7,101 @@ import { applyProjectTemplateUpdate, inspectProjectState } from './project-state
 import { knownProjectRoots, recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
 
-function runCommand(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    encoding: 'utf8',
-    env: options.env || process.env,
-    timeout: options.timeout || 120000,
+function commandLine(command, args) {
+  return [command, ...args].join(' ');
+}
+
+function elapsedMs(startedAt) {
+  return Date.now() - startedAt;
+}
+
+function progress(options, message) {
+  if (typeof options.onProgress === 'function') options.onProgress(message);
+}
+
+async function runCommand(command, args, options = {}) {
+  const timeout = options.timeout || 120000;
+  const killGraceMs = options.killGraceMs || 2000;
+  const label = options.label || commandLine(command, args);
+  const startedAt = Date.now();
+  const detached = process.platform !== 'win32';
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+  let timedOut = false;
+  let timeoutId = null;
+  let killId = null;
+
+  progress(options, `starting ${label}`);
+
+  return new Promise((resolveResult) => {
+    let child;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      clearTimeout(killId);
+      progress(options, `${label} finished in ${elapsedMs(startedAt)}ms`);
+      resolveResult({
+        ...result,
+        stdout,
+        stderr,
+        elapsedMs: elapsedMs(startedAt),
+        timedOut,
+      });
+    };
+    const killChild = (signal) => {
+      if (!child?.pid) return;
+      try {
+        if (detached) {
+          process.kill(-child.pid, signal);
+        } else {
+          child.kill(signal);
+        }
+      } catch {
+        // The process may have already exited.
+      }
+    };
+
+    try {
+      child = spawn(command, args, {
+        detached,
+        env: options.env || process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish({ status: null, signal: null, error });
+      return;
+    }
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      finish({ status: null, signal: null, error });
+    });
+    child.on('close', (status, signal) => {
+      const error = timedOut
+        ? Object.assign(new Error(`${label} timed out after ${timeout}ms`), { code: 'ETIMEDOUT' })
+        : null;
+      finish({ status, signal, error });
+    });
+
+    timeoutId = setTimeout(() => {
+      timedOut = true;
+      progress(options, `${label} exceeded ${timeout}ms; terminating`);
+      killChild('SIGTERM');
+      killId = setTimeout(() => {
+        progress(options, `${label} did not exit after SIGTERM; killing`);
+        killChild('SIGKILL');
+      }, killGraceMs);
+    }, timeout);
   });
-  return {
-    status: result.status,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    error: result.error || null,
-  };
 }
 
 function npmCommand() {
@@ -31,7 +114,11 @@ function binCommand() {
 
 function assertCommandOk(result, label) {
   if (result.status === 0 && !result.error) return;
-  const detail = result.stderr.trim() || result.stdout.trim() || result.error?.message || 'unknown error';
+  const detail = result.stderr.trim() ||
+    result.stdout.trim() ||
+    result.error?.message ||
+    (result.signal ? `signal ${result.signal}` : '') ||
+    'unknown error';
   throw new Error(`${label} failed: ${detail}`);
 }
 
@@ -45,7 +132,13 @@ function shouldUpdateAllProjects(options = {}) {
 
 async function projectRootsForUpdate(workspace, options = {}) {
   if (!shouldUpdateAllProjects(options)) return [workspace];
-  const roots = await knownProjectRoots({ workspace });
+  progress(options, `discovering project roots under ${workspace}`);
+  const roots = await knownProjectRoots({
+    workspace,
+    maxDirs: options.maxDirs,
+    onProgress: options.onProgress,
+  });
+  progress(options, `discovered ${roots.length} project root(s)`);
   return roots.length > 0 ? roots : [workspace];
 }
 
@@ -97,7 +190,9 @@ export function compareVersions(a, b) {
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
-  const result = runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+  const result = await runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+    ...options,
+    label: 'npm view',
     timeout: options.timeout || 30000,
   });
   assertCommandOk(result, 'npm view');
@@ -120,9 +215,16 @@ export async function postUpdate(options = {}) {
   });
 
   if (options.all) {
-    const workspaces = await knownProjectRoots({ workspace });
+    progress(options, `discovering project roots under ${workspace}`);
+    const workspaces = await knownProjectRoots({
+      workspace,
+      maxDirs: options.maxDirs,
+      onProgress: options.onProgress,
+    });
+    progress(options, `post-update will inspect ${workspaces.length} project root(s)`);
     const projects = [];
     for (const projectRoot of workspaces) {
+      progress(options, `applying managed templates to ${projectRoot}`);
       const projectResult = await applyTemplatesToProject(projectRoot, options);
       if (!options.noProject && await hasProjectWiki(projectRoot)) {
         await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
@@ -194,7 +296,9 @@ export async function update(options = {}) {
   const target = options.to || 'latest';
   const shouldRunNpmInstall = check.updateAvailable;
   const installResult = shouldRunNpmInstall
-    ? runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+    ? await runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+      ...options,
+      label: 'npm install -g',
       timeout: options.timeout || 120000,
     })
     : {
@@ -210,7 +314,13 @@ export async function update(options = {}) {
   if (options.noProject) postArgs.push('--no-project');
   if (options.codex === false) postArgs.push('--no-codex');
   if (options.claude === false) postArgs.push('--no-claude');
-  const postResult = runCommand(process.execPath, postArgs, {
+  const postResult = await runCommand(process.execPath, postArgs, {
+    ...options,
+    env: {
+      ...process.env,
+      LLM_WIKI_KIT_PROGRESS: process.env.LLM_WIKI_KIT_PROGRESS || '1',
+    },
+    label: 'post-update',
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');