hypomnema 1.6.2 → 1.7.1

package/scripts/uninstall.mjs

@@ -39,6 +39,12 @@ import {
   CODEX_TYPES,
   readExtensionPkgStateNoMutate,
   parseExtKey,
+  parseSkillKey,
+  parseSkillShaValue,
+  isFlatShaValue,
+  emptyShaMap,
+  isContainedUnder,
+  hasSymlinkAncestor,
   buildHookCommand,
 } from './lib/extensions.mjs';
 
@@ -105,8 +111,8 @@ function removeCommands(apply, force) {
 // map empties out, drop the target key; when the whole `extensions` object empties,
 // drop it too. Other targets' records (e.g. codex map during a Claude-only uninstall)
 // are never touched.
-function stripExtensionsFromPkg(pkgPath, target, removedKeys, apply) {
-  if (!existsSync(pkgPath) || removedKeys.length === 0) return false;
+function stripExtensionsFromPkg(pkgPath, target, removedKeys, apply, rewrittenKeys = new Map()) {
+  if (!existsSync(pkgPath) || (removedKeys.length === 0 && rewrittenKeys.size === 0)) return false;
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
@@ -126,6 +132,15 @@ function stripExtensionsFromPkg(pkgPath, target, removedKeys, apply) {
       changed = true;
     }
   }
+  // A partially-uninstalled skill keeps only the files it still owns. Leaving the
+  // removed paths in the map would let a later --force run delete whatever the user
+  // has since put back at those paths.
+  for (const [key, nested] of rewrittenKeys) {
+    if (key in perTarget) {
+      perTarget[key] = nested;
+      changed = true;
+    }
+  }
   if (Object.keys(perTarget).length === 0) {
     delete extensions[target];
     changed = true;
@@ -157,6 +172,46 @@ function stripExtensionsFromPkg(pkgPath, target, removedKeys, apply) {
 // file whose on-disk SHA differs from the recorded one is user-modified and
 // preserved unless --force-extensions; a symlink/non-regular target is always
 // preserved (force does not follow them, matching install/upgrade E3's guard).
+// Remove the directories a skill removal emptied, deepest first, and finally the
+// skill root itself. Anything still holding files (user-added, or copies we
+// refused to remove) is left standing — rmdir on a non-empty directory throws and
+// we swallow it, which is exactly the "never destroy what we don't own" behavior.
+//
+// Every rmdir is guarded by the same containment + symlink-ancestor walk the file
+// removals use. Without it, a corrupt `"skills/x": {}` record plus a symlinked
+// skill dir was enough to rmdir empty directories anywhere on disk: the record
+// granted no file ownership, yet the prune still ran (codex pre-commit BLOCKER).
+function pruneSkillDirs(skillsRoot, skillRoot) {
+  if (hasSymlinkAncestor(skillsRoot, skillRoot)) return;
+  const dirs = [];
+  const collect = (dir, depth) => {
+    if (depth > 16) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue; // isDirectory() is false for a symlink here
+      const full = join(dir, e.name);
+      collect(full, depth + 1);
+      dirs.push(full);
+    }
+  };
+  collect(skillRoot, 1);
+  dirs.push(skillRoot);
+  for (const dir of dirs) {
+    if (!isContainedUnder(skillsRoot, dir)) continue;
+    if (hasSymlinkAncestor(skillsRoot, dir)) continue;
+    try {
+      rmdirSync(dir);
+    } catch {
+      // not empty (or gone) — leave it
+    }
+  }
+}
+
 function removeExtensions(target, apply, force) {
   const targetRoot = target === 'codex' ? join(HOME, '.codex') : join(HOME, '.claude');
   const types = target === 'codex' ? CODEX_TYPES : EXT_TYPES;
@@ -167,11 +222,77 @@ function removeExtensions(target, apply, force) {
 
   const removed = [];
   const removedKeys = [];
+  // Skill keys that survive in reduced form: key → the nested map of files we still
+  // own after this run.
+  const rewrittenKeys = new Map();
   const skippedUserModified = [];
   const skippedNonRegular = [];
 
   for (const [key, recordedSHA] of Object.entries(recorded)) {
     if (!recordedSHA) continue; // no ownership baseline → nothing to remove
+
+    // A directory skill records one key (`skills/<name>`) whose value is a map of
+    // per-file SHAs. parseExtKey rejects that key by design (it demands the type's
+    // file extension), so without this branch every installed skill file would be
+    // silently stranded: owned on paper, unreachable by uninstall.
+    const skillKey = types.includes('skills') ? parseSkillKey(key) : null;
+    if (skillKey) {
+      const nested = parseSkillShaValue(recordedSHA);
+      // A corrupt value grants no ownership: remove nothing, and do NOT prune —
+      // pruning on an empty/invalid record is destructive power the record never
+      // earned.
+      if (!nested || Object.keys(nested).length === 0) continue;
+      const skillsRoot = join(targetRoot, 'skills');
+      const skillRoot = join(skillsRoot, skillKey.installDir);
+      // What the record must still claim after this run. A file we removed drops
+      // out; a file we preserved stays. Keeping a removed path in the record is not
+      // cosmetic: a later --force run deletes whatever now sits at that path,
+      // including a brand-new file the user created there (codex fix-verify BLOCKER).
+      const remaining = emptyShaMap();
+      let removedAny = false;
+      const preserve = (rel, sha, path, bucket) => {
+        remaining[rel] = sha;
+        bucket.push(path);
+      };
+      for (const [rel, sha] of Object.entries(nested)) {
+        const fullPath = join(skillRoot, ...rel.split('/'));
+        // Same containment + symlink-ancestor guard the sync path uses: a lexical
+        // check alone cannot see a symlinked directory in the middle of the path.
+        if (!isContainedUnder(skillRoot, fullPath) || hasSymlinkAncestor(skillsRoot, fullPath)) {
+          preserve(rel, sha, fullPath, skippedNonRegular);
+          continue;
+        }
+        if (!existsSync(fullPath)) continue; // already gone: the claim goes too
+        if (!isRegularFile(fullPath)) {
+          preserve(rel, sha, fullPath, skippedNonRegular);
+          continue;
+        }
+        const buf = readFileIfRegular(fullPath);
+        const fileSha = buf ? sha256(buf) : null;
+        if (fileSha === sha || force) {
+          if (apply) rmSync(fullPath);
+          removed.push(fullPath);
+          removedAny = true;
+        } else {
+          preserve(rel, sha, fullPath, skippedUserModified);
+        }
+      }
+      // Prune the directories we emptied, deepest first. A skill dir still holding
+      // user files (or files we refused to remove) is left in place.
+      if (apply && removedAny) pruneSkillDirs(skillsRoot, skillRoot);
+      // Retire the key outright only when nothing is left to claim. Otherwise rewrite
+      // it down to just the preserved files: dropping the whole key would disown them
+      // forever, and keeping the whole key would leave stale claims on paths we no
+      // longer own.
+      if (Object.keys(remaining).length === 0) removedKeys.push(key);
+      else rewrittenKeys.set(key, remaining);
+      continue;
+    }
+
+    // A flat key's value must be a plain hex SHA. Anything else (an object parked
+    // there by a corrupt pkg-json) grants no ownership — otherwise --force would
+    // remove the file on the strength of a value we never wrote.
+    if (!isFlatShaValue(recordedSHA)) continue;
     const parsed = parseExtKey(key, types);
     if (!parsed) continue; // untrusted / cross-target key → never join+rm
     const fullPath = join(targetRoot, parsed.type, parsed.installFile);
@@ -193,7 +314,7 @@ function removeExtensions(target, apply, force) {
       skippedUserModified.push(fullPath);
     }
   }
-  return { target, removed, removedKeys, skippedUserModified, skippedNonRegular };
+  return { target, removed, removedKeys, rewrittenKeys, skippedUserModified, skippedNonRegular };
 }
 
 // True iff `pkg.json` still holds extensions state for a target the current
@@ -478,6 +599,7 @@ let codexExtResult = {
   target: 'codex',
   removed: [],
   removedKeys: [],
+  rewrittenKeys: new Map(),
   skippedUserModified: [],
   skippedNonRegular: [],
 };
@@ -497,10 +619,23 @@ if (args.codex) {
   );
 }
 
-// Surgical per-target ext SHA strip — only for files we actually removed.
-stripExtensionsFromPkg(pkgJsonPath, 'claude', claudeExtResult.removedKeys, args.apply);
+// Surgical per-target ext SHA strip — only for files we actually removed. A skill
+// we uninstalled only partway is rewritten down to the files we still own.
+stripExtensionsFromPkg(
+  pkgJsonPath,
+  'claude',
+  claudeExtResult.removedKeys,
+  args.apply,
+  claudeExtResult.rewrittenKeys,
+);
 if (args.codex) {
-  stripExtensionsFromPkg(pkgJsonPath, 'codex', codexExtResult.removedKeys, args.apply);
+  stripExtensionsFromPkg(
+    pkgJsonPath,
+    'codex',
+    codexExtResult.removedKeys,
+    args.apply,
+    codexExtResult.rewrittenKeys,
+  );
 }
 
 // pkg.json metadata file removal — only when no user-tracked state remains.

package/scripts/upgrade.mjs

@@ -49,9 +49,11 @@ import {
   sha256 as sha256Buf,
   isRegularFile,
   readFileIfRegular,
+  readVersionAtRoot,
+  writeDualSkipProvenance,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
-import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
+import { isHypomnemaPluginEnabled, resolveEnabledPluginRoot } from './lib/plugin-detect.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
@@ -213,26 +215,58 @@ const SHARED_FILES = _hookConfig.shared ?? [];
 
 // ── checks ───────────────────────────────────────────────────────────────────
 
-function checkSchemaVersion(hypoDir) {
-  const pkgPath = join(TEMPLATES, 'SCHEMA.md');
-  const hypoPath = join(hypoDir, 'SCHEMA.md');
+// Shared by SCHEMA.md and hypo-guide.md: both templates carry a top-level
+// `version:` frontmatter stamp, and both are compared the same way — installed
+// copy vs. the package's own template — without ever writing to hypoPath. This
+// function is read-only; nothing downstream may use its return value to
+// overwrite the installed file (hand-authored wiki files are never
+// silently clobbered).
+function checkTemplateVersion(hypoDir, filename) {
+  const pkgPath = join(TEMPLATES, filename);
+  const hypoPath = join(hypoDir, filename);
 
   const pkgVersion = existsSync(pkgPath)
     ? parseVersion((parseFrontmatter(readFileSync(pkgPath, 'utf-8')) ?? {}).version)
     : null;
-  const hypoVersion = existsSync(hypoPath)
+
+  const hypoExists = existsSync(hypoPath);
+  const hypoVersion = hypoExists
     ? parseVersion((parseFrontmatter(readFileSync(hypoPath, 'utf-8')) ?? {}).version)
     : null;
 
+  // File present but carries no `version:` frontmatter field at all — a
+  // pre-versioning install (the file predates this stamp existing). This is
+  // deliberately distinguished from "file missing entirely" (still routed to
+  // bumpType's 'unknown' below): a bare `bumpType(null, pkgVersion)` cannot
+  // tell the two apart, and folding this case into plain 'unknown' is exactly
+  // what let an already-installed, unstamped hypo-guide.md report "up to
+  // date" — the file this check exists to catch. The caller decides whether
+  // 'unstamped' counts as drift; this helper only classifies.
+  const unstamped = hypoExists && !hypoVersion && !!pkgVersion;
+
   return {
     installed: hypoVersion?.raw ?? null,
     current: pkgVersion?.raw ?? null,
-    bump: bumpType(hypoVersion, pkgVersion),
+    bump: unstamped ? 'unstamped' : bumpType(hypoVersion, pkgVersion),
     hypoPath,
     pkgPath,
   };
 }
 
+function checkSchemaVersion(hypoDir) {
+  return checkTemplateVersion(hypoDir, 'SCHEMA.md');
+}
+
+// hypo-guide.md had no update channel at all — upgrade.mjs never
+// looked at it, and init.mjs only ever writes it once (skip if present), so an
+// installed vault's copy went permanently stale the moment the shipped template
+// changed, with no signal to the user. This check restores visibility (a warning
+// on drift) without adding a write path: --apply still never touches an
+// installed hypo-guide.md, exactly like SCHEMA.md's existing Option C contract.
+function checkGuideVersion(hypoDir) {
+  return checkTemplateVersion(hypoDir, 'hypo-guide.md');
+}
+
 // Target-aware: the same core-hook integrity check runs against ~/.claude/hooks/
 // for the default claude target, and against ~/.codex/hooks/ when --codex is set
 // The function reads only (apply happens in applyHookFiles).
@@ -479,6 +513,11 @@ const GITIGNORE_REQUIRED_ENTRIES = [
     pattern: '.cache/',
     comment: '# Hypomnema runtime cache (page-usage log, session growth metrics)',
   },
+  {
+    pattern: '*.lock',
+    comment:
+      '# Append-lock files (transient <target>.lock; a crashed holder can leave a stale one)',
+  },
 ];
 
 function checkGitignore(hypoDir) {
@@ -836,6 +875,15 @@ function writePluginModeMetadata() {
   return true;
 }
 
+// readVersionAtRoot and writeDualSkipProvenance now live in ./lib/pkg-json.mjs
+// (imported above) — writeDualSkipProvenance is deliberately not
+// writePluginModeMetadata(): that function hardcodes THIS npm run's
+// PKG_ROOT/PKG_VERSION and always drops `commands` — both correct for true
+// plugin mode, both wrong for a dualSkip correction, where the identity being
+// written is the OTHER install's. Moving both into lib/pkg-json.mjs (alongside
+// the other pkgJsonPath-taking helpers already there) also makes the writer's
+// TOCTOU refusal directly unit-testable without spawning the whole script.
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -886,9 +934,41 @@ const managesClaudeCore = !pluginMode && (!dualInstallCoreConflict || args.allow
 const dualSkip = dualInstallCoreConflict && !args.allowDualInstall;
 
 const schema = checkSchemaVersion(args.hypoDir);
+const guide = checkGuideVersion(args.hypoDir);
 const hooks = checkHookFiles(claudeHooksDir);
 const settings = checkSettingsJson(claudeSettingsPath, claudeHooksDir);
 const pkgJson = checkPkgJson();
+// dualSkip provenance self-heal: the registry root the enabled plugin key
+// POSITIVELY resolves to (same lookup init.mjs's resolveDurableRoot uses), or
+// null when the registry is absent/unreadable/corrupt or names no usable entry
+// for the enabled key. Computed unconditionally (fail-open on any uncertainty —
+// see lib/plugin-detect.mjs) so both the --apply write below and the read-only
+// report can agree on the same positively-resolved identity without a second
+// registry read racing the first.
+const dualSkipRegistryRoot = dualSkip
+  ? resolveEnabledPluginRoot(
+      claudeSettingsPath,
+      join(HOME, '.claude', 'plugins', 'installed_plugins.json'),
+    )
+  : null;
+// The recorded pkgRoot currently on disk, read non-mutatingly (readPkgJsonSafe
+// would rename aside a corrupt file — a write — before this script has decided
+// whether to touch anything).
+const dualSkipRecordedRoot = (() => {
+  try {
+    const v = JSON.parse(readFileSync(pkgJsonPath(), 'utf-8')).pkgRoot;
+    return typeof v === 'string' ? v : null;
+  } catch {
+    return null;
+  }
+})();
+// A CONDITIONAL self-heal, never an unconditional rewrite: correct only when the
+// registry positively resolves a usable root that DIFFERS from what's already
+// recorded. An unresolvable registry (null) must PRESERVE the existing pointer,
+// not blank it or fall back to this npm PKG_ROOT — a null here is "cannot prove
+// a correction is needed", not "there is nothing to preserve".
+const dualSkipWouldCorrect =
+  dualSkip && dualSkipRegistryRoot !== null && dualSkipRegistryRoot !== dualSkipRecordedRoot;
 const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
 const hypoignore = checkHypoignore(args.hypoDir);
@@ -948,15 +1028,41 @@ const missingSettingsCodex = settingsCodex
 const invalidSettingsCodex = settingsCodex
   ? settingsCodex.some((s) => s.status === 'invalid-json')
   : false;
-const schemaDrift = schema.bump !== 'none' && schema.bump !== 'unknown' && schema.bump !== 'ahead';
-// 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
+// SCHEMA.md keeps its pre-existing behavior: 'unstamped' is deliberately NOT
+// counted as drift here (SCHEMA.md is user-owned vocabulary, Option C — an
+// unstamped SCHEMA.md was already the "cannot compare" case before this
+// classification existed, and no SCHEMA test exercises it as actionable).
+const schemaDrift =
+  schema.bump !== 'none' &&
+  schema.bump !== 'unknown' &&
+  schema.bump !== 'ahead' &&
+  schema.bump !== 'unstamped';
+// hypo-guide.md: 'unstamped' DOES count as drift — this is the exact shape of
+// an already-installed pre-versioning vault, the population this change targets.
+// Excluding it (as the old unknown-only check did) is the bug this fixes.
+const guideDrift = guide.bump !== 'none' && guide.bump !== 'unknown' && guide.bump !== 'ahead';
+// Dual-install: when core is skipped, hypo-pkg.json is normally 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 USUALLY
+// intentional — `--apply` will not rewrite an already-correct plugin pointer
+// — so it must not count as actionable drift by default, or the user would be
+// nagged to run --apply forever. The one exception is dualSkipWouldCorrect: an
+// npm-first divergence where the recorded pointer differs from what the plugin
+// registry POSITIVELY resolves (e.g. `npm init`, enable the plugin, `npm init`
+// again — the npm root stays recorded forever otherwise). THAT case IS
+// actionable — `--apply` corrects it via writeDualSkipProvenance — so it must
+// count as drift, or the user has no signal to ever run --apply. dualSkipWouldCorrect
+// is checked FIRST and unconditionally (not gated behind `pkgJson.status !==
+// 'up-to-date'`): checkPkgJson() compares the recorded pointer only against
+// THIS run's own PKG_ROOT, so an npm-first divergence where the recorded
+// pointer happens to equal PKG_ROOT (but the registry resolves a DIFFERENT
+// plugin root) would read 'up-to-date' and slip past that status check
+// entirely — leaving a correctable divergence permanently unreported. 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 pkgJsonDrift =
+  dualSkipWouldCorrect ||
+  (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');
@@ -968,6 +1074,11 @@ let migrationPath = null;
 let appliedHooks = [];
 let appliedSettings = [];
 let appliedPkgJson = false;
+// True only once the dualSkip provenance self-heal actually WROTE a correction
+// this run (a positively-resolved registry root that differed from the
+// recorded one). Distinct from dualSkipWouldCorrect (a pre-apply preview
+// computed above), which stays true even in a dry run.
+let dualSkipCorrected = false;
 let appliedHookNameRenames = [];
 let appliedHooksCodex = [];
 let appliedSettingsCodex = [];
@@ -1054,6 +1165,20 @@ if (args.apply) {
     // user to resolve the dual install.
     if (pkgJson.status === 'missing') {
       appliedPkgJson = writePluginModeMetadata();
+    } else if (dualSkipWouldCorrect) {
+      // npm-first correction: a usable pkgRoot IS already recorded (status
+      // 'stale' or 'up-to-date'), but the registry positively resolves a
+      // DIFFERENT usable root — e.g. `npm init`, then enable the plugin, then
+      // `npm init` again, leaving the npm root recorded forever. Correct the
+      // provenance to the registry's own root/version. When the registry
+      // cannot positively resolve one (dualSkipWouldCorrect is false — null
+      // registry lookup, or it already matches what's recorded), fall through
+      // to preserving the existing pointer untouched; never blank it.
+      // writeDualSkipProvenance can still refuse here (TOCTOU: the registry
+      // root's own package.json became unreadable between resolution and this
+      // write) — dualSkipCorrected only follows an ACTUAL write, never assume it.
+      appliedPkgJson = writeDualSkipProvenance(pkgJsonPath(), dualSkipRegistryRoot);
+      dualSkipCorrected = appliedPkgJson;
     } else {
       appliedPkgJson = false;
     }
@@ -1134,6 +1259,7 @@ const hasDrift =
   (managesClaudeCore && claudeCoreDrift) ||
   pkgJsonDrift ||
   schemaDrift ||
+  guideDrift ||
   hypoignore.status === 'needs-migration' ||
   gitignore.status === 'needs-migration' ||
   extDrift ||
@@ -1150,6 +1276,7 @@ if (args.json) {
         coreManagedBy: managesClaudeCore ? 'self' : pluginMode ? 'plugin' : 'plugin-enabled',
         dualInstallOverride: args.allowDualInstall,
         schema,
+        guide,
         hooks,
         settings,
         pkgJson,
@@ -1249,6 +1376,12 @@ if (schema.bump === 'none') {
   lines.push(
     `⚠ SCHEMA version    ${schema.installed} (installed is ahead of package ${schema.current})`,
   );
+} else if (schema.bump === 'unstamped') {
+  // Not counted as drift for SCHEMA.md (Option C, unchanged) — still surfaced
+  // as advisory-only visibility, same spirit as the pre-existing 'unknown' text.
+  lines.push(
+    `⚠ SCHEMA version    installed has no version stamp (pre-versioning copy), package=${schema.current} (cannot compare automatically)`,
+  );
 } else if (schema.bump === 'major') {
   lines.push(
     `✗ SCHEMA version    ${schema.installed} → ${schema.current}  [MAJOR — --apply writes MIGRATION report; SCHEMA must be merged manually]`,
@@ -1259,6 +1392,33 @@ if (schema.bump === 'none') {
   );
 }
 
+// hypo-guide.md version stamp. Visibility only — a drift warning,
+// never a write: --apply must not overwrite an installed hypo-guide.md, since a
+// user may have customized it (same Option C contract as SCHEMA.md above).
+if (guide.bump === 'none') {
+  lines.push(`✓ hypo-guide.md     v${guide.installed} (up to date)`);
+} else if (guide.bump === 'unknown') {
+  lines.push(
+    `⚠ hypo-guide.md     installed=${guide.installed ?? 'not found (no version stamp)'}, package=${guide.current ?? 'not found'} (cannot compare)`,
+  );
+} else if (guide.bump === 'ahead') {
+  lines.push(
+    `⚠ hypo-guide.md     v${guide.installed} (installed is ahead of package v${guide.current})`,
+  );
+} else if (guide.bump === 'unstamped') {
+  // The target case: the file exists (this is not a fresh/missing
+  // install) but predates the version stamp entirely. Counted as drift above
+  // (guideDrift) — the message must be actionable, not "cannot compare",
+  // since a pre-versioning copy silently reporting "up to date" was the bug.
+  lines.push(
+    `⚠ hypo-guide.md     installed copy has no version stamp (pre-versioning stale copy; package=v${guide.current}) — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it`,
+  );
+} else {
+  lines.push(
+    `⚠ hypo-guide.md     v${guide.installed} → v${guide.current}  [package template changed — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it]`,
+  );
+}
+
 // Hook files (target-aware so --codex can mirror the same block).
 function pushHookSummary(hookList, label, targetPath) {
   const colHook = `Hook files${label}`.padEnd(20);
@@ -1318,7 +1478,28 @@ if (managesClaudeCore) {
 if (settingsCodex) pushSettingsSummary(settingsCodex, ' (codex)', invalidSettingsCodex);
 
 // Package metadata
-if (dualSkip && pkgJson.status === 'stale') {
+if (dualSkip && dualSkipCorrected) {
+  // npm-first correction actually WROTE this run: the pre-apply pkgJson
+  // classification above was computed against the running npm PKG_ROOT, so
+  // without this branch a corrected pointer would still be reported as
+  // "preserved — not rewritten" (or "up to date"/"stale") below, contradicting
+  // what --apply just did. Report the explicit outcome instead, with the
+  // registry package's own version — the identity now on disk.
+  const correctedVersion = readVersionAtRoot(dualSkipRegistryRoot);
+  lines.push(
+    `✓ Package metadata  hypo-pkg.json corrected to enabled plugin registry root` +
+      (correctedVersion ? ` (v${correctedVersion})` : ''),
+  );
+} else if (dualSkip && dualSkipWouldCorrect) {
+  // Same divergence, but this was a dry run (no --apply): preview what
+  // --apply would do rather than claiming the identity is already preserved.
+  const previewVersion = readVersionAtRoot(dualSkipRegistryRoot);
+  lines.push(
+    `⚠ Package metadata  hypo-pkg.json points at a stale npm/manual root — \`--apply\` will` +
+      ` correct it to the enabled plugin registry root` +
+      (previewVersion ? ` (v${previewVersion})` : ''),
+  );
+} else if (dualSkip && pkgJson.status === 'stale') {
   // Dual-install: 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(
@@ -1572,6 +1753,7 @@ const totalDrift =
   claudeCoreCount +
   (pkgJsonDrift ? 1 : 0) +
   (schemaDrift ? 1 : 0) +
+  (guideDrift ? 1 : 0) +
   (hypoignore.status === 'needs-migration' ? hypoignore.missing.length : 0) +
   (gitignore.status === 'needs-migration' ? gitignore.missing.length : 0) +
   extCheck.actions.filter(

package/skills/crystallize/SKILL.md

@@ -11,7 +11,7 @@ When invoked to close a session — via an explicit close signal ("세션 종료
 
 ## What this does
 
-- **Close mode**: walks the checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) plus a lint step, then writes via `/hypo:crystallize` in `--apply-session-close --payload=<path>` mode — which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). `--check-session-close` is a read-only dry-run of the **full** PreCompact gate: close files + scoped lint + design-history + feedback projection, sharing one function (`precompactGateStatus`) with the gate. A green check means no gate blocker needs a human fix, so it is the signal to declare the session closed (pass `--transcript-path` to widen the lint scope to this session's edited files exactly as the interactive hook does). It is not a hard guarantee: the live `/compact` can still differ on a context-≥70% prompt, `HYPO_SKIP_GATE`, or a transcript-scoped lint error the check did not see.
+- **Close mode**: walks the checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) plus a lint step, then writes via `/hypo:crystallize` in `--apply-session-close --payload=<path> --session-id=<id>` mode, which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). **`--session-id` is required.** Before writing a byte, the apply resolves that session's transcript and refuses the whole close, exit 1 and nothing on disk, unless the **user** asked for it (`session-id-required` / `transcript-unresolved` / `no-user-close-signal`). A refusal is the answer, not an obstacle: ask the user, and re-run only if they say yes. `--check-session-close` is a read-only dry-run of the **full** PreCompact gate: close files + scoped lint + design-history + feedback projection, sharing one function (`precompactGateStatus`) with the gate. A green check means no gate blocker needs a human fix, so it is the signal to declare the session closed (pass `--transcript-path` to widen the lint scope to this session's edited files exactly as the interactive hook does). It is not a hard guarantee: the live `/compact` can still differ on a context-≥70% prompt, `HYPO_SKIP_GATE`, or a transcript-scoped lint error the check did not see.
 - **Synthesis mode**: finds tag clusters (≥ N pages), orphan pages (no outbound `[[wikilinks]]`), and draft / stub pages, then guides consolidation into `pages/syntheses/<topic>.md` with back-links and `index.md` updates.
 
 ---
@@ -102,15 +102,52 @@ Once it passes, report each item with ✓:
 - ✓ session-log entry
 - ✓ open-questions (or skipped if unchanged)
 - ✓ log.md entry
-- **marker written?** (required, if `--apply-session-close --session-id` was used): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete; recover per the `markerSkipReason` branch below.
+- **marker written?** (required): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete; recover per the branches below.
 
-If `markerWritten: true` (or `--session-id` was not passed), ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
+If `markerWritten: true`, ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
 
-If `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason`:
+**If `ok: false` with an authority `reason`, the close did not happen at all.** No file was written, nothing was committed. Do not report a partial close, and do not write the files by hand to get around it.
 
-- `no-user-close-signal`: files applied cleanly and the transcript resolved, but it carries no close phrase the gate recognizes (the user's close wording fell outside the close-signal set, e.g. "세션 마무리까지 진행해줘" / "세션 마무리 진행"). Re-running the same id will not help. Confirm intent once with `AskUserQuestion` (header "세션", one option **세션 마무리**); if the user picks it, that answer is a recognized close signal, so re-run the same `--apply-session-close … --session-id` command (idempotent no-op writes; the marker lands). If the user declines, leave the session unmarked. Do NOT change the close-signal matcher.
-- `transcript-unresolved` (wrong / background id): report "Files applied and verified (ok: true), but the marker was not written (reason: `<markerSkipReason>`). The Stop-chain is still active. Re-run with the correct main-conversation `--session-id`."
-- any other reason (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface it verbatim and resolve the underlying blocker before re-running.
+- `session-id-required`: `--session-id` was omitted. Pass the main conversation's id and re-run.
+- `transcript-unresolved`: the id resolved no transcript, so it is most likely a background-task or Agent-thread uuid rather than the main conversation's. Get the right one and re-run.
+- `no-user-close-signal`: the transcript is this session's, and the user never asked to close in wording the gate recognizes (e.g. "세션 마무리까지 진행해줘" falls outside the close-signal set). Re-running the same id changes nothing. Confirm intent once with `AskUserQuestion` (header "세션", one option **세션 마무리**); if the user picks it, that answer becomes a recognized close signal, so the same command now applies everything: writes, commit, and marker. If the user declines, the session stays open and nothing is written. Do NOT change the close-signal matcher.
+
+**If `ok: false` with `stage: "session-id-mismatch"`,** the payload carries a `sessionId` that is not the `--session-id` you passed, so this file was authored for a different session (a reused or overwritten temp path). Nothing was written. Do not force it: rebuild the payload for THIS session (write it to a session-scoped path, e.g. `/tmp/hypo-session-close-<session-id>.json`) and re-run.
+
+If the apply succeeded but `markerWritten: false`, branch on `markerSkipReason` (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface it verbatim and resolve the underlying blocker before re-running.
+
+### If the close came back `ok: false, stage: "proposal-pending"`
+
+A concurrent session wrote one of the pages this close wants to replace, so the close
+withheld the bytes rather than clobber that session's work, and parked them. Nothing is
+lost and nothing is broken. The close is waiting on a decision only the user makes:
+whether to replace the other session's bytes.
+
+Do NOT write the pages with the Write tool and mark the session closed. That path skips
+the store entirely and silently destroys the other session's edits. Drive it out properly:
+
+1. **Look at `proposals`.** If the array is EMPTY, no page was parked. The only conflicts
+   were append-lock timeouts, which the next close re-reads and re-appends by itself. Just
+   re-run the same close command.
+2. **`hypomnema proposal challenge --session-id <id> --ids <id,...>`** with the ids from
+   `proposals`. It re-reads each page from disk and prints the diff between what is there
+   now and what this close wants to write.
+3. **Show the user those diffs** and tell them plainly what would be overwritten. Then give
+   them the approval line the command printed, and ask them to type it:
+
+       apply-proposals <nonce>
+
+   They have to TYPE it. A click on `AskUserQuestion` does not approve an overwrite (you
+   author the option labels, so a click cannot prove they approved this specific write),
+   and the command refuses it. If they would rather keep the other session's page, run
+   `hypomnema proposal discard <id>` instead and re-run the close.
+4. **`hypomnema proposal resolve --session-id <id>`** once they have typed it. It verifies
+   the approval in the transcript, checks the pages have not moved since they saw the diff,
+   and writes them.
+5. **Re-run the close.** `resolve` writes the pages; it does NOT close the session. The
+   re-run skips what already landed and finishes the close.
+6. **Check `markerWritten` again** before you say the session is closed. It is never
+   automatic.
 
 ---