hypomnema 1.2.1 → 1.3.1

package/scripts/smoke-pack.mjs

@@ -32,6 +32,24 @@ import { fileURLToPath } from 'node:url';
 const REPO = join(fileURLToPath(new URL('.', import.meta.url)), '..');
 const KEEP = process.argv.includes('--keep');
 
+// When this script runs inside `npm publish --dry-run` (the release workflow's
+// publish-credential pre-check), npm exports `npm_config_dry_run=true` into the
+// lifecycle environment. spawnSync inherits process.env, so the nested
+// `npm pack` below would ALSO run in dry-run mode — reporting a tarball
+// filename/size it never actually writes to disk — and the subsequent
+// `npm install <tarball>` then fails with ENOENT (npm maps errno -2 → exit 254).
+// Strip the flag so the nested npm commands always perform real writes,
+// matching the real tag-push publish job (which has no outer `--dry-run`). The
+// outer workflow stays dry-run and still skips the registry PUT.
+// (This was the precheck-254 root cause; the earlier "missing NODE_AUTH_TOKEN"
+// theory was wrong — it is file absence, not auth.)
+const npmEnv = { ...process.env };
+for (const key of Object.keys(npmEnv)) {
+  if (key.toLowerCase().replaceAll('-', '_') === 'npm_config_dry_run') {
+    delete npmEnv[key];
+  }
+}
+
 const PKG = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf-8'));
 const PKG_NAME = PKG.name;
 
@@ -56,8 +74,15 @@ const wikiDir = join(work, 'wiki');
 let cleanupOk = false;
 
 try {
+  // Capture pre-commit hook contents (if any) BEFORE pack so we can prove
+  // `npm pack` didn't mutate it. The `prepare` lifecycle script runs during
+  // `npm pack` and could theoretically touch .git/hooks/pre-commit; the
+  // installer's CI/lifecycle guards must prevent that.
+  const preCommitPath = join(REPO, '.git', 'hooks', 'pre-commit');
+  const preCommitBefore = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : null;
+
   step('npm pack');
-  const pack = run('npm', ['pack', '--json'], { cwd: REPO });
+  const pack = run('npm', ['pack', '--json'], { cwd: REPO, env: npmEnv });
   const meta = JSON.parse(pack.stdout)[0];
   const tarball = join(REPO, meta.filename);
   console.log(`  → ${meta.filename} (${meta.size} bytes, ${meta.entryCount} entries)`);
@@ -72,7 +97,10 @@ try {
       private: true,
     }) + '\n',
   );
-  run('npm', ['install', '--no-audit', '--no-fund', '--silent', tarball], { cwd: installRoot });
+  // No `--silent`: run() only prints npm's stdout/stderr on a non-zero exit, so
+  // a real nested-install failure must not be muted (the precheck-254 error was
+  // masked by `--silent` for two release cycles).
+  run('npm', ['install', '--no-audit', '--no-fund', tarball], { cwd: installRoot, env: npmEnv });
 
   // Move tarball into the work dir so it's not left in the repo.
   renameSync(tarball, join(work, meta.filename));
@@ -203,6 +231,15 @@ try {
     );
   }
 
+  step('verify pre-commit hook was not mutated by npm pack');
+  const preCommitAfter = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : null;
+  if (preCommitBefore !== preCommitAfter) {
+    throw new Error(
+      'npm pack mutated .git/hooks/pre-commit — the prepare lifecycle ' +
+        'guard (npm_command=pack) is not firing.',
+    );
+  }
+
   console.log('\n✓ smoke-pack passed');
   cleanupOk = true;
 } catch (err) {

package/scripts/upgrade.mjs

@@ -19,6 +19,11 @@
  *                       wiki-*.mjs → hypo-*.mjs rename migration (fix #48), and
  *                       the user-extensions companion sync (E4 / fix #32).
  *   --json              Output results as JSON
+ *   --allow-downgrade   Override the guard that refuses to overwrite a NEWER
+ *                       active install with an older package (ADR 0038)
+ *   --allow-dual-install  Override the ISSUE-8 guard: register the Claude core
+ *                       surface even though the Hypomnema plugin is also enabled
+ *                       (knowingly accept the double-registration risk)
  */
 
 import {
@@ -45,6 +50,8 @@ import {
   readFileIfRegular,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
+import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
+import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -76,6 +83,8 @@ function parseArgs(argv) {
     forceCommands: false,
     forceExtensions: false,
     codex: false,
+    allowDowngrade: false,
+    allowDualInstall: false,
   };
   for (const arg of argv.slice(2)) {
     if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
@@ -84,6 +93,8 @@ function parseArgs(argv) {
     else if (arg === '--force-extensions') args.forceExtensions = true;
     else if (arg === '--codex') args.codex = true;
     else if (arg === '--json') args.json = true;
+    else if (arg === '--allow-downgrade') args.allowDowngrade = true;
+    else if (arg === '--allow-dual-install') args.allowDualInstall = true;
   }
   if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
   return args;
@@ -312,7 +323,7 @@ function applySettingsJson(settingsResults, settingsPath) {
   for (const s of settingsResults) {
     if (s.status !== 'missing') continue;
     if (!Array.isArray(settings.hooks[s.event])) settings.hooks[s.event] = [];
-    // fix #48 BLOCKER: re-check the current parsed settings before appending.
+    // re-check the current parsed settings before appending.
     // applyHookNameMigration may have rewritten a legacy wiki-*.mjs command to
     // exactly `s.cmd` between checkSettingsJson and now — appending without
     // this guard creates a duplicate registration (codex 2-worker review
@@ -453,7 +464,7 @@ function applyHypoignoreMigration(result) {
   return appended;
 }
 
-function writeMigrationReport(hypoDir, fromVersion, toVersion) {
+function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = false } = {}) {
   const today = new Date().toISOString().slice(0, 10);
   const filename = `MIGRATION-v${toVersion}.md`;
   const dest = join(hypoDir, filename);
@@ -521,15 +532,16 @@ checklist below is manual:
 - [ ] **Re-run \`hypomnema lint\` after backfilling — confirm 0 feedback errors
       remain (including the conditional \`claude-learned\` fields above)**
 
-## Caveat — \`scope: project:<project-id>\` and slug regex
+## Note — \`scope: project:<project-id>\` and the scope regex
 
-The lint regex \`^project:[a-z0-9][a-z0-9-]*$\` accepts only short slugs, but
-\`feedback-sync\`'s default resolved project-id is cwd-derived (e.g.
-\`-Users-you-Workspace-Project\`), which the regex rejects. To use a
-\`scope: project:*\` page in v1.2.0 you must override with
-\`--project-id=<slug>\` so the resolved id is slug-safe. The full resolved-id
-↔ wiki-slug reconciliation is deferred to v1.3.0; \`commands/feedback.md\`
-documents the interim pattern.
+As of v1.3.0 the feedback scope regex \`^(global|project:[A-Za-z0-9_-]+)\$\`
+accepts cwd-derived project-ids directly (e.g.
+\`-Users-you-Workspace-Project\`), so a \`scope: project:*\` page no longer needs
+a \`--project-id=<slug>\` override just to pass \`lint\`. The resolved id must
+still exact-match \`feedback-sync\`'s project-id for projection (default: cwd
+with \`/\` and \`.\` replaced by \`-\`). Known limit: a cwd containing spaces or
+other characters outside \`[A-Za-z0-9_-]\` still derives an id the regex
+rejects — pass \`--project-id=<id>\` for those.
 `
     : `## What changed
 
@@ -538,9 +550,15 @@ Review the SCHEMA diff and update your wiki pages accordingly.
 
 ## Action items
 
-This report was generated during \`/hypo:upgrade --apply\`. Hook files and settings.json
-entries were applied by that run (or skipped with a warning if the target was malformed —
-see the upgrade output). \`SCHEMA.md\` is intentionally **not** overwritten by upgrade — the
+This report was generated during \`/hypo:upgrade --apply\`. ${
+        pluginMode
+          ? 'You are on a **plugin install**, so the core hook files and settings.json hook ' +
+            'registrations were NOT touched — the Claude Code plugin loader owns them (upgrade the ' +
+            'plugin via `/plugin marketplace update hypomnema` then `/reload-plugins`). Vault ' +
+            'extensions, if any, were still synced.'
+          : 'Hook files and settings.json entries were applied by that run (or skipped with a ' +
+            'warning if the target was malformed — see the upgrade output).'
+      } \`SCHEMA.md\` is intentionally **not** overwritten by upgrade — the
 remaining steps are manual:
 
 - [ ] Compare your \`SCHEMA.md\` (v${fromVersion}) with the package template (v${toVersion}) and merge changes manually
@@ -743,6 +761,31 @@ function applyCommands(commandResults, force) {
   return applied;
 }
 
+// ISSUE-6: in plugin mode `applyCommands` is skipped (no command copy), but the
+// runtime still needs hypo-pkg.json to resolve PKG_ROOT for lint/feedback scripts
+// (hooks/hypo-shared.mjs → hypo-personal-check). Write minimal metadata pointing
+// at the plugin's package root, preserving any existing fields (e.g. `extensions`)
+// but DROPPING any prior `commands` map (no commands were copied, so a stale map
+// would falsely assert ownership of ~/.claude/commands/hypo).
+function writePluginModeMetadata() {
+  const path = pkgJsonPath();
+  // Drop any prior top-level `commands` SHA map: no commands were copied in plugin
+  // mode, so keeping a manual install's map would falsely assert ownership of
+  // ~/.claude/commands/hypo. Preserve every other field (e.g. `extensions`).
+  const { commands: _droppedCommands, ...existing } = readPkgJsonSafe(path) || {};
+  let pkgVersion = null;
+  try {
+    pkgVersion = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
+  } catch {}
+  writePkgJsonAtomic(path, {
+    ...existing,
+    pkgRoot: PKG_ROOT,
+    pkgVersion,
+    schemaVersion: '2.0',
+  });
+  return true;
+}
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -754,6 +797,43 @@ const claudeSettingsPath = join(HOME, '.claude', 'settings.json');
 const codexHooksDir = join(HOME, '.codex', 'hooks');
 const codexSettingsPath = join(HOME, '.codex', 'settings.json');
 
+// ISSUE-6: when `/hypo:upgrade` runs as the Claude Code PLUGIN, the 15 core hooks
+// and 14 slash commands are provided by the plugin's hooks.json + commands/
+// (auto-wired by Claude Code), NOT copied into ~/.claude/. The manual/npm health
+// check below would then report all of them "missing" and recommend `--apply`,
+// which copies the hooks into ~/.claude/hooks/ and registers 14 settings.json
+// events → Claude Code runs BOTH the plugin hooks.json AND user settings.json, so
+// every hook fires TWICE. The decisive signal: the plugin command runs the
+// PLUGIN's upgrade.mjs, so PKG_ROOT lives under ~/.claude/plugins/. (A manual/npm
+// upgrade.mjs run while the plugin is ALSO enabled is a different failure mode —
+// dual install — tracked as ISSUE-8.)
+// Match the Claude plugin cache shape specifically (`~/.claude/plugins/…`), NOT a
+// generic `/plugins/` substring — this flag now GATES install behavior, so a
+// legitimate npm/dev checkout under some unrelated `…/plugins/…` path must not be
+// misclassified and silently stop managing its hooks. (detectChannel's broad
+// `/plugins/` test is fine for the notifier's display-only use, but too loose here.)
+const pluginMode = PKG_ROOT.replace(/\\/g, '/').includes('/.claude/plugins/');
+// ISSUE-8 (dual install): the OTHER way the same double-registration can happen.
+// Here the MANUAL/npm upgrade.mjs is running (pluginMode=false), but the Hypomnema
+// plugin is ALSO enabled in ~/.claude/settings.json — so the plugin loader already
+// provides the core hooks/commands/settings. A manual/npm `--apply` would copy and
+// register them on top, and every core hook fires twice. The detector is fail-open
+// (see lib/plugin-detect.mjs): a false positive would wrongly alter a legitimate
+// npm-only user's upgrade, so it only fires on an exact `hypomnema@<mp>: true`.
+const hypomnemaPluginEnabled = !pluginMode && isHypomnemaPluginEnabled(claudeSettingsPath);
+const dualInstallCoreConflict = hypomnemaPluginEnabled;
+// Surface policy: the Claude core surface (hooks/settings/commands/hook-name
+// migration) is skipped when EITHER the plugin runs this script (pluginMode) OR a
+// manual/npm run detects the plugin is enabled (dualInstallCoreConflict) — unless
+// the user knowingly overrides with --allow-dual-install. The codex core surface
+// (--codex) and vault-defined extensions are NOT plugin-provided, so they stay
+// managed in every case.
+const managesClaudeCore = !pluginMode && (!dualInstallCoreConflict || args.allowDualInstall);
+// dualSkip = core was skipped specifically because of the dual install (not a true
+// plugin-mode run, and not overridden). Drives the warning banner and the metadata
+// preservation below.
+const dualSkip = dualInstallCoreConflict && !args.allowDualInstall;
+
 const schema = checkSchemaVersion(args.hypoDir);
 const hooks = checkHookFiles(claudeHooksDir);
 const settings = checkSettingsJson(claudeSettingsPath, claudeHooksDir);
@@ -762,7 +842,7 @@ const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
 const hypoignore = checkHypoignore(args.hypoDir);
 
-// fix #48: when --codex is set, mirror the same core-hook checks against ~/.codex/
+// when --codex is set, mirror the same core-hook checks against ~/.codex/
 // so `hypomnema upgrade --codex` reports drift symmetrically and `--apply --codex`
 // updates both targets in one pass (matching init.mjs behaviour).
 const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
@@ -784,7 +864,7 @@ const extCheck = syncExtensions({
   force: args.forceExtensions,
 });
 
-// E4 (#32): --codex mirrors the extensions sync into ~/.codex (hooks + commands
+// E4 (fix #32): --codex mirrors the extensions sync into ~/.codex (hooks + commands
 // only; skills/agents skipped with a notice). The per-target SHA map lives in the
 // same ~/.claude/hypo-pkg.json under extensions.codex, so pkgPath is unchanged.
 const extCodexSettingsPath = codexSettingsPath;
@@ -817,7 +897,14 @@ const invalidSettingsCodex = settingsCodex
   ? settingsCodex.some((s) => s.status === 'invalid-json')
   : false;
 const schemaDrift = schema.bump !== 'none' && schema.bump !== 'unknown' && schema.bump !== 'ahead';
-const pkgJsonDrift = pkgJson.status !== 'up-to-date';
+// ISSUE-8 dual-install: when core is skipped, hypo-pkg.json is deliberately left
+// pointing at the PLUGIN's package root (preserved identity), so checkPkgJson()
+// reports it 'stale' relative to this npm/manual PKG_ROOT. That mismatch is
+// INTENTIONAL — `--apply` will not (and must not) rewrite it — so it must not
+// count as actionable drift, or the user would be nagged to run --apply forever.
+// A genuinely missing/corrupt file (status 'missing') is still surfaced (warning
+// below), because the runtime then cannot resolve its package root at all.
+const pkgJsonDrift = pkgJson.status !== 'up-to-date' && !(dualSkip && pkgJson.status === 'stale');
 const staleCommands = commands.filter((c) => c.status === 'stale' || c.status === 'missing');
 const userModifiedCommands = commands.filter((c) => c.status === 'user-modified');
 const orphanedCommands = commands.filter((c) => c.status === 'orphaned');
@@ -839,23 +926,87 @@ let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
 if (args.apply) {
-  if (oldHookRefs.length > 0) {
-    appliedHookNameRenames = applyHookNameMigration(
-      oldHookRefs,
-      claudeSettingsPath,
-      claudeHooksDir,
-    );
+  // Downgrade guard (ADR 0038, P): an `--apply` from an OLDER package than the
+  // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
+  // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
+  // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
+  // is exempt via realpath'd pkgRoot equality. Exit 2 = refused downgrade.
+  if (!args.allowDowngrade) {
+    const _active = readPkgJsonSafe(pkgJsonPath());
+    let _incomingVersion = null;
+    try {
+      _incomingVersion = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
+    } catch {
+      /* unreadable own package.json — cannot prove a downgrade, allow */
+    }
+    if (
+      _active &&
+      _active.pkgVersion &&
+      _incomingVersion &&
+      classifyInstall(
+        { pkgRoot: PKG_ROOT, version: _incomingVersion },
+        { pkgRoot: _active.pkgRoot, version: _active.pkgVersion },
+      ) === 'downgrade'
+    ) {
+      console.error(downgradeGuardMessage(_incomingVersion, _active.pkgVersion, 'upgrade --apply'));
+      process.exit(2);
+    }
   }
+  // Migration report is vault-side (writes into the Hypomnema root) and applies
+  // in both install models.
   if (schema.bump === 'major' && schema.installed && schema.current && existsSync(args.hypoDir)) {
-    migrationPath = writeMigrationReport(args.hypoDir, schema.installed, schema.current);
+    migrationPath = writeMigrationReport(args.hypoDir, schema.installed, schema.current, {
+      // Use the core-skipped predicate, not raw pluginMode: in a dual-install skip
+      // the core surface is plugin-owned too, so the report must not claim the
+      // core hooks/settings were applied (ISSUE-8, W2 review note).
+      pluginMode: !managesClaudeCore,
+    });
+  }
+  if (managesClaudeCore) {
+    if (oldHookRefs.length > 0) {
+      appliedHookNameRenames = applyHookNameMigration(
+        oldHookRefs,
+        claudeSettingsPath,
+        claudeHooksDir,
+      );
+    }
+    appliedHooks = applyHookFiles(hooks, claudeHooksDir);
+    appliedSettings = applySettingsJson(settings, claudeSettingsPath);
+    // applyCommands handles the single atomic hypo-pkg.json write (pkgRoot, version, schema, commands map)
+    appliedCommands = applyCommands(commands, args.forceCommands);
+    appliedPkgJson = true;
+  } else if (pluginMode) {
+    // ISSUE-6 plugin mode: the plugin loader owns the core hooks/commands and
+    // settings.json wiring — copying them here would double-register. Skip those,
+    // but STILL write minimal package metadata so the runtime can resolve PKG_ROOT
+    // for lint/feedback scripts (hooks/hypo-shared.mjs → hypo-personal-check). The
+    // commands SHA map is intentionally omitted (no command copy happened). PKG_ROOT
+    // is the plugin's own path here, so this metadata is authoritative.
+    appliedPkgJson = writePluginModeMetadata();
+  } else {
+    // ISSUE-8 dual-install skip: a manual/npm run while the plugin is enabled. We
+    // skip the core surface (the plugin owns it), but — unlike true plugin mode —
+    // PKG_ROOT here is the npm/manual path while the ACTIVE runtime hooks are the
+    // PLUGIN's. Rewriting a VALID hypo-pkg.json.pkgRoot to this npm path would
+    // mis-point the plugin runtime's lint/feedback resolution, so we PRESERVE an
+    // existing plugin-written identity (pkgJson.status 'stale'/'up-to-date' both
+    // mean a usable pkgRoot is already on disk) and do not touch it.
+    //
+    // If the metadata is MISSING or corrupt (status 'missing'; corrupt files are
+    // renamed to *.corrupt-*.json by readPkgJson and then read as absent), there is
+    // no plugin identity to preserve. Write minimal fallback metadata pointing at
+    // this (same-version) npm copy so the plugin runtime can resolve a package root
+    // at all — strictly better than the pkgRoot-less file extension sync would
+    // otherwise create, or no file at all. The dual-install banner still tells the
+    // user to resolve the dual install.
+    if (pkgJson.status === 'missing') {
+      appliedPkgJson = writePluginModeMetadata();
+    } else {
+      appliedPkgJson = false;
+    }
   }
-  appliedHooks = applyHookFiles(hooks, claudeHooksDir);
-  appliedSettings = applySettingsJson(settings, claudeSettingsPath);
-  // applyCommands handles the single atomic hypo-pkg.json write (pkgRoot, version, schema, commands map)
-  appliedCommands = applyCommands(commands, args.forceCommands);
-  appliedPkgJson = true;
   appliedHypoignore = applyHypoignoreMigration(hypoignore);
-  // fix #48: codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
+  // codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
   // as the claude side (rename first so subsequent hook copy can find renamed targets).
   if (args.codex) {
     if (oldHookRefsCodex.length > 0) {
@@ -878,7 +1029,7 @@ if (args.apply) {
     apply: true,
     force: args.forceExtensions,
   });
-  // E4 (#32): codex apply runs AFTER the claude apply so it reads the freshly
+  // E4 (fix #32): codex apply runs AFTER the claude apply so it reads the freshly
   // written hypo-pkg.json and merges extensions.codex alongside extensions.claude
   // (the per-target spread in syncExtensions preserves the other target's map).
   if (args.codex) {
@@ -898,7 +1049,7 @@ if (args.apply) {
 
 const extDrift = extCheck.needsWork || (extCheckCodex?.needsWork ?? false);
 
-// fix #48: codex drift only counts when --codex is set — without the flag the codex
+// codex drift only counts when --codex is set — without the flag the codex
 // target is intentionally unobserved (parity with the existing extensions pattern).
 const codexCoreDrift =
   args.codex &&
@@ -907,17 +1058,28 @@ const codexCoreDrift =
     invalidSettingsCodex ||
     (oldHookRefsCodex?.length ?? 0) > 0);
 
-const hasDrift =
+// Claude core-surface drift (hooks/settings/commands/rename/metadata). In plugin
+// mode these are plugin-managed, so they must NOT count as drift — otherwise the
+// report nags "N items need updating" and recommends a double-registering --apply.
+// Plugin-provided surface (hooks/settings/commands/rename) — excluded from drift
+// in plugin mode. pkgJsonDrift is intentionally NOT here: hypo-pkg.json is written
+// in BOTH install models (plugin mode writes minimal metadata so the runtime can
+// resolve PKG_ROOT for lint/feedback), so a missing/stale metadata file should
+// still prompt a (safe, metadata-only) --apply.
+const claudeCoreDrift =
   staleHooks.length > 0 ||
   missingSettings.length > 0 ||
-  schemaDrift ||
   invalidSettings ||
-  pkgJsonDrift ||
   oldHookRefs.length > 0 ||
   staleCommands.length > 0 ||
   userModifiedCommands.length > 0 ||
   orphanedCommands.length > 0 ||
-  nonRegularCommands.length > 0 ||
+  nonRegularCommands.length > 0;
+
+const hasDrift =
+  (managesClaudeCore && claudeCoreDrift) ||
+  pkgJsonDrift ||
+  schemaDrift ||
   hypoignore.status === 'needs-migration' ||
   extDrift ||
   codexCoreDrift;
@@ -926,6 +1088,12 @@ if (args.json) {
   console.log(
     JSON.stringify(
       {
+        pluginMode,
+        // ISSUE-8 dual-install signals.
+        hypomnemaPluginEnabled,
+        dualInstallCoreConflict,
+        coreManagedBy: managesClaudeCore ? 'self' : pluginMode ? 'plugin' : 'plugin-enabled',
+        dualInstallOverride: args.allowDualInstall,
         schema,
         hooks,
         settings,
@@ -935,7 +1103,7 @@ if (args.json) {
         hypoignore,
         extensions: extCheck,
         extensionsCodex: extCheckCodex,
-        // fix #48: codex core mirror (null when --codex absent).
+        // codex core mirror (null when --codex absent).
         hooksCodex,
         settingsCodex,
         oldHookRefsCodex,
@@ -970,6 +1138,49 @@ if (args.json) {
 // Human-readable report
 const lines = [];
 
+// ISSUE-6: lead with the plugin-mode banner so the user understands why the core
+// hook/command/settings sections read "managed by plugin" and that `--apply` will
+// NOT touch them (only vault-side migrations + package metadata).
+if (pluginMode) {
+  lines.push(
+    'ℹ Plugin install detected — Hypomnema is loaded via the Claude Code plugin.',
+    '  Core hooks, slash commands, and settings.json wiring are provided by the',
+    '  plugin loader, so `/hypo:upgrade` does NOT manage them (and `--apply` will',
+    '  not copy/register them — that would double-register every hook).',
+    '  → To upgrade the plugin: `/plugin marketplace update hypomnema` then `/reload-plugins`.',
+    '  → `/hypo:upgrade --apply` here applies vault-side migrations (SCHEMA,',
+    '    .hypoignore), refreshes package metadata, and still syncs any vault',
+    '    extensions — but does NOT install the core hooks/commands/settings.',
+    '',
+  );
+}
+
+// ISSUE-8: a manual/npm upgrade.mjs is running while the Hypomnema plugin is ALSO
+// enabled — a dual install. Lead with a loud banner: the core surface is owned by
+// the plugin and is intentionally skipped, so `--apply` will not double-register.
+if (dualSkip) {
+  lines.push(
+    '⚠ Dual install detected — you are running the MANUAL/npm `upgrade.mjs`, but the',
+    '  Hypomnema plugin is ALSO enabled in ~/.claude/settings.json. The plugin loader',
+    '  already provides the core hooks, slash commands, and settings.json wiring, so',
+    '  this run does NOT copy/register them (doing so would double-register every hook).',
+    '  → Recommended: pick ONE install. To keep the plugin, remove the npm/manual copy',
+    '    (`npm uninstall -g hypomnema`) and upgrade via `/plugin marketplace update',
+    '    hypomnema` + `/reload-plugins`. Vault extensions + codex (if any) are still synced.',
+    '  → To register the core surface here anyway (knowingly accept the double-register',
+    '    risk), re-run with `--allow-dual-install`.',
+    '',
+  );
+} else if (dualInstallCoreConflict && args.allowDualInstall) {
+  // Override path: the user forced core registration despite the enabled plugin.
+  lines.push(
+    '⚠ Dual install — `--allow-dual-install` set: registering the Claude core surface',
+    '  even though the Hypomnema plugin is enabled. Every core hook may now fire TWICE',
+    '  (plugin loader + ~/.claude registration) until one install is removed.',
+    '',
+  );
+}
+
 // Schema version
 if (schema.bump === 'none') {
   lines.push(`✓ SCHEMA version    ${schema.installed} (up to date)`);
@@ -1015,7 +1226,13 @@ function pushHookSummary(hookList, label, targetPath) {
     }
   }
 }
-pushHookSummary(hooks, '', '~/.claude/hooks/');
+if (managesClaudeCore) {
+  pushHookSummary(hooks, '', '~/.claude/hooks/');
+} else {
+  lines.push(
+    '✓ Hook files          provided by the plugin loader (not managed in ~/.claude/hooks/)',
+  );
+}
 if (hooksCodex) pushHookSummary(hooksCodex, ' (codex)', '~/.codex/hooks/');
 
 // settings.json registrations (target-aware mirror; fix #48).
@@ -1034,11 +1251,33 @@ function pushSettingsSummary(sList, label, invalidFlag) {
     }
   }
 }
-pushSettingsSummary(settings, '', invalidSettings);
+if (managesClaudeCore) {
+  pushSettingsSummary(settings, '', invalidSettings);
+} else {
+  lines.push(
+    '✓ settings.json       hook wiring provided by the plugin (no ~/.claude registration)',
+  );
+}
 if (settingsCodex) pushSettingsSummary(settingsCodex, ' (codex)', invalidSettingsCodex);
 
 // Package metadata
-if (pkgJson.status === 'up-to-date') {
+if (dualSkip && pkgJson.status === 'stale') {
+  // ISSUE-8: the 'stale' here is the preserved plugin identity (pkgRoot points at
+  // the plugin, not this npm/manual copy). That is intentional — not actionable.
+  lines.push(
+    `✓ Package metadata  hypo-pkg.json plugin-owned (preserved — not rewritten in a dual install)`,
+  );
+} else if (dualSkip && pkgJson.status === 'missing') {
+  // Missing/corrupt in a dual install: there is no plugin identity to preserve, so
+  // `--apply` writes minimal fallback metadata (pointing at this same-version npm
+  // copy) — enough for the plugin runtime to resolve its scripts. The real fix is
+  // still to resolve the dual install.
+  lines.push(
+    `⚠ Package metadata  hypo-pkg.json missing/unreadable — \`--apply\` writes fallback metadata`,
+    `                    for this npm copy so the plugin runtime can resolve its scripts.`,
+    `                    Better: resolve the dual install (remove the npm/manual copy).`,
+  );
+} else if (pkgJson.status === 'up-to-date') {
   lines.push(`✓ Package metadata  hypo-pkg.json up to date`);
 } else if (pkgJson.status === 'stale') {
   lines.push(
@@ -1055,7 +1294,9 @@ const cmdMissCount = commands.filter((c) => c.status === 'missing').length;
 const cmdUserCount = userModifiedCommands.length;
 const cmdOrphanCount = orphanedCommands.length;
 const cmdNonRegCount = nonRegularCommands.length;
-if (commands.length === 0) {
+if (!managesClaudeCore) {
+  lines.push('✓ Slash commands    provided by the plugin loader (not ~/.claude/commands/hypo/)');
+} else if (commands.length === 0) {
   lines.push(`⚠ Slash commands    package commands/ is empty`);
 } else if (
   cmdStaleCount === 0 &&
@@ -1090,7 +1331,7 @@ if (commands.length === 0) {
 }
 
 // Old hook names (wiki-*.mjs → hypo-*.mjs rename migration). Target-aware so
-// fix #48 surfaces codex settings.json that still references the v1.0/v1.1 names.
+// codex settings.json entries that still reference the v1.0/v1.1 names are surfaced.
 function pushHookNameSummary(refs, label) {
   if (refs.length > 0) {
     lines.push(
@@ -1102,7 +1343,10 @@ function pushHookNameSummary(refs, label) {
     lines.push(`✓ ${colN}All hook references use current hypo-*.mjs names`);
   }
 }
-pushHookNameSummary(oldHookRefs, '');
+// In plugin mode the Claude settings.json is plugin-owned and --apply skips the
+// rename migration, so do not print a "run --apply to rename" instruction it will
+// not honor. (codex hook-name migration is unaffected by pluginMode.)
+if (managesClaudeCore) pushHookNameSummary(oldHookRefs, '');
 if (oldHookRefsCodex) pushHookNameSummary(oldHookRefsCodex, ' (codex)');
 
 // .hypoignore migration (ensure required runtime patterns are present)
@@ -1142,7 +1386,7 @@ function pushExtSummary(check, label) {
     for (const c of check.conflicts) lines.push(`    ✗ ${c.file}  [${c.action} — left untouched]`);
     for (const d of check.drifts) lines.push(`    ⚠ ${d.file}  [drift — left untouched]`);
   }
-  // E3 (#31): a hard conflict blocks install (exit 1, even under --apply); drift is
+  // E3 (fix #31): a hard conflict blocks install (exit 1, even under --apply); drift is
   // resolvable advisory. Emit the spec'd WIKI messages so the user knows the recovery.
   if (nConflicts > 0) {
     lines.push('  [WIKI: existing file conflicts. Backup and retry, or use --force-extensions]');
@@ -1200,7 +1444,7 @@ if (
     lines.push(`✓ Appended .hypoignore entries (${appliedHypoignore.length}):`);
     for (const e of appliedHypoignore) lines.push(`    → ${e}`);
   }
-  // fix #48: codex-target applied actions (mirrors claude blocks above).
+  // codex-target applied actions (mirrors claude blocks above).
   if (appliedHookNameRenamesCodex.length > 0) {
     lines.push(`✓ Renamed legacy hook references (codex) (${appliedHookNameRenamesCodex.length}):`);
     for (const r of appliedHookNameRenamesCodex) lines.push(`    → ${r}`);
@@ -1237,26 +1481,32 @@ pushAppliedExt(appliedExtensionsCodex, ' (codex)');
 
 // Summary
 lines.push('');
+// Claude core-surface item count — zeroed in plugin mode (plugin-managed), so the
+// summary never reads "N items need updating" for hooks/settings/commands.
+const claudeCoreCount = managesClaudeCore
+  ? staleHooks.length +
+    missingSettings.length +
+    (invalidSettings ? 1 : 0) +
+    oldHookRefs.length +
+    staleCommands.length +
+    userModifiedCommands.length +
+    orphanedCommands.length +
+    nonRegularCommands.length
+  : 0;
+
 const totalDrift =
-  staleHooks.length +
-  missingSettings.length +
-  (schemaDrift ? 1 : 0) +
-  (invalidSettings ? 1 : 0) +
+  claudeCoreCount +
   (pkgJsonDrift ? 1 : 0) +
-  oldHookRefs.length +
-  staleCommands.length +
-  userModifiedCommands.length +
-  orphanedCommands.length +
-  nonRegularCommands.length +
+  (schemaDrift ? 1 : 0) +
   (hypoignore.status === 'needs-migration' ? hypoignore.missing.length : 0) +
   extCheck.actions.filter(
     (a) => a.action === 'create' || a.action === 'update' || a.action === 'force-update',
   ).length +
-  // E3 (#31): unresolved drift/conflict is pending work too — without these the
-  // summary printed "up to date" while the exit code was 1 (codex review).
+  // E3 (fix #31): unresolved drift/conflict is pending work too — without these the
+  // summary printed "up to date" while the exit code was 1.
   extCheck.conflicts.length +
   extCheck.drifts.length +
-  // E4 (#32): codex-target pending work counts identically (same message/exit
+  // E4 (fix #32): codex-target pending work counts identically (same message/exit
   // consistency the E3 review caught — a codex conflict must not read "up to date").
   (extCheckCodex
     ? extCheckCodex.actions.filter(
@@ -1265,7 +1515,7 @@ const totalDrift =
       extCheckCodex.conflicts.length +
       extCheckCodex.drifts.length
     : 0) +
-  // fix #48: codex core mirror counts the same way as the claude side.
+  // codex core mirror counts the same way as the claude side.
   staleHooksCodex.length +
   missingSettingsCodex.length +
   (invalidSettingsCodex ? 1 : 0) +
@@ -1297,7 +1547,7 @@ if (totalDrift === 0) {
 
 console.log(lines.join('\n'));
 
-// E3 (#31): a hard extension conflict blocks even under --apply (unlike ordinary
+// E3 (fix #31): a hard extension conflict blocks even under --apply (unlike ordinary
 // drift, which only fails check mode). --force-extensions clears the resolvable
 // cases; an unfollowable symlink/non-regular dest still counts and stays exit 1.
 const extBlocked = extCheck.conflicts.length > 0 || (extCheckCodex?.conflicts.length ?? 0) > 0;