hypomnema 1.3.0 → 1.3.2

package/scripts/rename.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+/**
+ * rename.mjs — rename a wiki page and rewrite inbound wikilinks.
+ *
+ * A bare `git mv` leaves every `[[old]]` / `[[old|alias]]` / `[[old#anchor]]` /
+ * `[[dir/old]]` pointing at a now-missing target — broken links accumulate on
+ * every rename. This helper moves the page AND content-aware rewrites every
+ * inbound reference across the vault so a rename never breaks a link.
+ *
+ *   node rename.mjs --hypo-dir=<dir> --from=<slug|rel> --to=<slug|rel> [--apply] [--json]
+ *
+ * Default is a dry-run (report only); --apply performs the move + rewrites.
+ *
+ * Two design invariants:
+ *
+ * 1. Resolution, not string-match. A link `[[foo]]` (bare basename) can be
+ *    shared by two pages; a blind text replace would break the wrong one. Each
+ *    link target is resolved with the SAME precedence lint uses (full noExt →
+ *    bare basename → dir-relative drop). A reference is rewritten only when it
+ *    resolves UNAMBIGUOUSLY to the from-page. An ambiguous bare form (the slug
+ *    maps to >1 file) is reported, never auto-rewritten — which also makes the
+ *    ADR-renumber guard free: a `--to` that is not a unique destination is
+ *    rejected.
+ *
+ * 2. Preserve append-only time records. journal / session-log / weekly / archive
+ *    / postmortems (and root log.md) are frozen snapshots — rewriting a `[[old]]`
+ *    inside a past entry would falsify that moment's record. They are skipped as
+ *    link SOURCES. sources/* is likewise immutable. This tool's value is "update
+ *    live links at rename time", not "retroactively churn old snapshots".
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+} from 'fs';
+import { join, relative, extname, basename, dirname, normalize, isAbsolute } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, from: null, to: null, apply: false, json: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--from=')) args.from = arg.slice(7);
+    else if (arg.startsWith('--to=')) args.to = arg.slice(5);
+    else if (arg === '--apply') args.apply = true;
+    else if (arg === '--json') args.json = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── page collection (mirrors graph.mjs / crystallize.mjs collectPages) ──────────
+
+function collectPages(dir, root, pages = [], ignorePatterns = []) {
+  if (!existsSync(dir)) return pages;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (isIgnored(full, root, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      collectPages(full, root, pages, ignorePatterns);
+    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
+      const rel = relative(root, full).replace(/\\/g, '/');
+      pages.push({ path: full, rel, slug: rel.replace(/\.md$/, ''), bare: basename(full, '.md') });
+    }
+  }
+  return pages;
+}
+
+// ── preserved (append-only / immutable) link-source paths ──────────────────────
+// These are skipped as link SOURCES: their content is a frozen record. Rewriting
+// a [[old]] reference inside a past journal/session-log/weekly/archive/postmortem
+// snapshot (or root log.md) would falsify that moment. sources/* is immutable
+// captured material. decisions/ and other-project handoffs are NOT preserved here
+// (they were kept in the read-side triage for renumber/ownership reasons, not
+// because they are time records — a forward rename should update their live
+// cross-references). Matches a path SEGMENT so `pages/journal/x.md` and
+// `projects/p/session-log/2026-06.md` both qualify.
+function isPreservedSource(rel) {
+  const p = rel.replace(/\\/g, '/');
+  if (p === 'log.md') return true; // root append-only log
+  return /(^|\/)(journal|session-log|weekly|archive|postmortems|sources)(\/|$)/.test(p);
+}
+
+// ── slug-form index (resolution with collision detection) ──────────────────────
+// Unlike lint's buildSlugMap (a Set that silently dedups collisions), rename
+// needs to KNOW when a form is shared, so it maps each form → the set of page
+// rels that expose it. precedence forms per page: full noExt slug, bare
+// basename, dir-relative (drop the leading scan-dir segment).
+function dirRelForm(slug) {
+  const slash = slug.indexOf('/');
+  return slash === -1 ? null : slug.slice(slash + 1);
+}
+
+function buildFormIndex(pages) {
+  const index = new Map(); // form → Set<rel>
+  const add = (form, rel) => {
+    if (!form) return;
+    if (!index.has(form)) index.set(form, new Set());
+    index.get(form).add(rel);
+  };
+  for (const p of pages) {
+    add(p.slug, p.rel);
+    // sources/* are full-slug-only link targets, exactly as lint's
+    // collectLinkTargets treats them: a bare `[[name]]` must NOT resolve to a
+    // source file. Adding their bare/dir-relative aliases here would make a real
+    // page's bare link look ambiguous and skip a legitimate rewrite.
+    if (/(^|\/)sources(\/|$)/.test(p.rel)) continue;
+    add(p.bare, p.rel);
+    add(dirRelForm(p.slug), p.rel);
+  }
+  return index;
+}
+
+// Classify a link target against the from-page. Returns the form KIND when the
+// target points at from-page, plus whether that form is ambiguous (shared with
+// another page → unsafe to auto-rewrite).
+function classifyTarget(target, fromPage, formIndex) {
+  const owners = formIndex.get(target);
+  if (!owners || !owners.has(fromPage.rel)) return { kind: null, ambiguous: false };
+  const ambiguous = owners.size > 1;
+  let kind = null;
+  if (target === fromPage.slug) kind = 'full';
+  else if (target === dirRelForm(fromPage.slug)) kind = 'dirrel';
+  else if (target === fromPage.bare) kind = 'bare';
+  return { kind, ambiguous };
+}
+
+// The new target string for a matched form kind — same kind, new page.
+function newTargetFor(kind, toPage) {
+  if (kind === 'full') return toPage.slug;
+  if (kind === 'dirrel') return dirRelForm(toPage.slug) ?? toPage.bare;
+  return toPage.bare; // bare
+}
+
+// ── wikilink masking (mirror lint.mjs stripNonWikilinkRegions) ──────────────────
+// Blank out fenced code, inline code, and HTML comments WITHOUT changing length,
+// so a [[ref]] match index in the mask aligns with the same index in the source.
+// Rewriting then edits the source at those exact spans, never touching a link
+// that only appears inside a code sample.
+function maskNonWikilinkRegions(content) {
+  let out = content;
+  out = out.replace(/^[ \t]{0,3}```[\s\S]*?^[ \t]{0,3}```/gm, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/^[ \t]{0,3}~~~[\s\S]*?^[ \t]{0,3}~~~/gm, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/``[^`\n]*``/g, (m) => ' '.repeat(m.length));
+  out = out.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+  return out;
+}
+
+// Parse the inside of a `[[ ... ]]` into { target, suffix } where suffix is the
+// alias/anchor tail to preserve verbatim (including a table-escaped `\|`). The
+// target capture stops before an optional `\` preceding the `|`/`#` delimiter,
+// matching lint's extractor exactly.
+function splitLinkBody(body) {
+  const m = body.match(/^([^|#\\]+?)(\\?[|#][\s\S]*)?$/);
+  if (!m) return null;
+  return { target: m[1].trim(), suffix: m[2] || '' };
+}
+
+// Rewrite every inbound reference to fromPage in `content`. Returns
+// { content, rewrites, ambiguous } where rewrites/ambiguous list the links
+// changed / skipped-as-ambiguous (with their 1-based line numbers).
+function rewriteContent(content, fromPage, toPage, formIndex) {
+  const mask = maskNonWikilinkRegions(content);
+  const re = /\[\[([^\]]+?)\]\]/g;
+  const edits = []; // { start, end, replacement }
+  const rewrites = [];
+  const ambiguous = [];
+  let m;
+  while ((m = re.exec(mask)) !== null) {
+    const start = m.index;
+    const end = start + m[0].length;
+    const body = content.slice(start + 2, end - 2); // real body from source
+    const parsed = splitLinkBody(body);
+    if (!parsed) continue;
+    const { kind, ambiguous: amb } = classifyTarget(parsed.target, fromPage, formIndex);
+    if (!kind) continue; // does not resolve to from-page
+    const line = content.slice(0, start).split('\n').length;
+    if (amb) {
+      ambiguous.push({ link: m[0], line, target: parsed.target });
+      continue; // shared form — report, never auto-rewrite
+    }
+    const replacement = `[[${newTargetFor(kind, toPage)}${parsed.suffix}]]`;
+    edits.push({ start, end, replacement });
+    rewrites.push({ from: m[0], to: replacement, line });
+  }
+  // Apply edits back-to-front so earlier indices stay valid.
+  let out = content;
+  for (const e of edits.sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, e.start) + e.replacement + out.slice(e.end);
+  }
+  return { content: out, rewrites, ambiguous };
+}
+
+// ── resolve a --from / --to argument to a page rel + forms ──────────────────────
+// Accepts a full rel ("pages/foo.md" / "pages/foo"), a noExt slug, or a bare
+// basename when unambiguous. Returns { rel, slug, bare } or null.
+function resolveArgToPage(arg, pages, formIndex) {
+  const norm = arg.replace(/\\/g, '/').replace(/\.md$/, '');
+  // exact full-slug match first
+  const direct = pages.find((p) => p.slug === norm);
+  if (direct) return direct;
+  const owners = formIndex.get(norm);
+  if (owners && owners.size === 1) {
+    const rel = [...owners][0];
+    return pages.find((p) => p.rel === rel) || null;
+  }
+  return null; // missing or ambiguous
+}
+
+function fail(args, msg) {
+  if (args.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+  else console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+function run(args) {
+  if (!args.from || !args.to) {
+    fail(args, '--from=<slug|rel> and --to=<slug|rel> are required');
+  }
+  const ignorePatterns = loadHypoIgnore(args.hypoDir);
+  const pages = collectPages(args.hypoDir, args.hypoDir, [], ignorePatterns);
+  const formIndex = buildFormIndex(pages);
+
+  const fromPage = resolveArgToPage(args.from, pages, formIndex);
+  if (!fromPage) {
+    fail(args, `--from did not resolve to a unique existing page: ${args.from}`);
+  }
+
+  // Compute the destination rel. --to may be a full rel (move across dirs) or a
+  // bare new name (rename in place within from-page's directory).
+  const toNorm = args.to.replace(/\\/g, '/').replace(/\.md$/, '');
+  const toRelRaw = toNorm.includes('/')
+    ? `${toNorm}.md`
+    : `${dirname(fromPage.rel)}/${toNorm}.md`.replace(/^\.\//, '');
+  // Normalize away ./ and ../ segments, then require the result stays inside the
+  // vault: a `--to` like `../moved` must not move a page out of the wiki, and
+  // `pages/../pages/bar` must not become a non-canonical `[[pages/../pages/bar]]`
+  // link target.
+  const toRel = normalize(toRelRaw).replace(/\\/g, '/');
+  if (toRel === '..' || toRel.startsWith('../') || isAbsolute(toRel)) {
+    fail(args, `--to escapes the wiki root: ${args.to}`);
+  }
+  const toSlug = toRel.replace(/\.md$/, '');
+  const toPath = join(args.hypoDir, toRel);
+
+  // Guard: never overwrite an existing destination (an ADR-renumber / merge would
+  // land here — that is a report-only case, not a blind move).
+  if (existsSync(toPath) && toRel !== fromPage.rel) {
+    fail(
+      args,
+      `--to already exists: ${toRel}. Rename cannot overwrite a live page (renumber/merge is manual).`,
+    );
+  }
+  if (toRel === fromPage.rel) {
+    fail(args, `--from and --to resolve to the same page (${toRel}) — nothing to rename`);
+  }
+
+  const toPage = {
+    rel: toRel,
+    slug: toSlug,
+    bare: basename(toRel, '.md'),
+    path: toPath,
+  };
+
+  // Destination must be a UNIQUE link destination: existsSync(toPath) above only
+  // catches a same-path clobber, not a cross-directory basename collision
+  // (pages/bar.md vs projects/bar.md). If the new bare or dir-relative form
+  // already resolves to a DIFFERENT existing page, the rewritten `[[new]]` links
+  // would be ambiguous — the same contract that bars rewriting an ambiguous
+  // source link. Refuse rather than emit ambiguous links.
+  for (const form of [toPage.bare, dirRelForm(toPage.slug)]) {
+    if (!form) continue;
+    const owners = formIndex.get(form);
+    if (owners && [...owners].some((rel) => rel !== fromPage.rel)) {
+      fail(
+        args,
+        `--to '${args.to}' collides with an existing page on form '${form}' — rewritten links would be ambiguous. Pick a unique name.`,
+      );
+    }
+  }
+
+  // Rewrite inbound references across every NON-preserved page (skip the moved
+  // page itself — self-references are rewritten on its own content separately).
+  const fileResults = [];
+  let totalRewrites = 0;
+  const ambiguities = [];
+  for (const p of pages) {
+    if (isPreservedSource(p.rel)) continue;
+    let raw;
+    try {
+      raw = readFileSync(p.path, 'utf-8');
+    } catch {
+      continue;
+    }
+    const { content, rewrites, ambiguous } = rewriteContent(raw, fromPage, toPage, formIndex);
+    if (rewrites.length > 0) {
+      fileResults.push({ file: p.rel, rewrites });
+      totalRewrites += rewrites.length;
+      if (args.apply && content !== raw) {
+        // The from-page is about to move; write its rewritten body to the NEW
+        // path below, not the old one.
+        if (p.rel === fromPage.rel) {
+          fromPage._rewritten = content;
+        } else {
+          writeFileSync(p.path, content);
+        }
+      } else if (p.rel === fromPage.rel) {
+        fromPage._rewritten = content;
+      }
+    }
+    if (ambiguous.length > 0) {
+      ambiguities.push({ file: p.rel, ambiguous });
+    }
+  }
+
+  // Move the file (--apply only): write the (possibly self-rewritten) body at the
+  // new path, then drop the old one. Done as write-then-remove rather than a raw
+  // rename so the carried-over self-reference rewrites are preserved.
+  let moved = false;
+  if (args.apply) {
+    mkdirSync(dirname(toPath), { recursive: true });
+    const body = fromPage._rewritten ?? readFileSync(fromPage.path, 'utf-8');
+    writeFileSync(toPath, body);
+    if (toPath !== fromPage.path) rmSync(fromPage.path, { force: true });
+    moved = true;
+  }
+
+  const result = {
+    ok: true,
+    applied: args.apply,
+    from: fromPage.rel,
+    to: toRel,
+    moved,
+    files_rewritten: fileResults.length,
+    links_rewritten: totalRewrites,
+    rewrites: fileResults,
+    ambiguous: ambiguities,
+  };
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const mode = args.apply ? 'Renamed' : 'Dry-run (no changes written)';
+    console.log(`${mode}: ${fromPage.rel} → ${toRel}`);
+    console.log(`  ${totalRewrites} inbound link(s) across ${fileResults.length} file(s).`);
+    for (const f of fileResults) {
+      console.log(`  · ${f.file}: ${f.rewrites.map((r) => `${r.from}→${r.to}`).join(', ')}`);
+    }
+    if (ambiguities.length > 0) {
+      console.log('\n  ⚠ ambiguous links NOT rewritten (bare slug shared by >1 page):');
+      for (const a of ambiguities) {
+        for (const x of a.ambiguous) console.log(`    · ${a.file}:${x.line} ${x.link}`);
+      }
+      console.log('    Resolve these manually (use a dir-relative or full-slug form).');
+    }
+    if (!args.apply) console.log('\n  Re-run with --apply to write the move + rewrites.');
+  }
+  process.exit(0);
+}
+
+run(parseArgs(process.argv));

package/scripts/resume.mjs

@@ -9,13 +9,26 @@
  *   node scripts/resume.mjs [options]
  *
  * Options:
- *   --hypo-dir=<path>     Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
- *   --project=<name>      Project name (default: most recently active from hot.md)
+ *   --hypo-dir=<path>     Hypomnema root. When omitted, resolveHypoRoot()
+ *                         (see lib/hypo-root.mjs) resolves it in priority order:
+ *                           1. $HYPO_DIR if set — returned immediately; the
+ *                              hypo-config.md scan below is then skipped.
+ *                           2. else the first of 7 fixed candidates
+ *                              (~/{hypomnema,wiki,notes,knowledge},
+ *                              ~/Documents/{hypomnema,wiki,notes}) that contains
+ *                              a hypo-config.md marker.
+ *                           3. else the default ~/hypomnema.
+ *   --project=<name>      Project name. When omitted, resolveActiveProject()
+ *                         prefers the project whose working_dir contains the
+ *                         current directory (cwd-first), and only falls back to
+ *                         the most recently active hot.md row when nothing under
+ *                         cwd matches.
  *   --json                Output as JSON
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
+import { homedir } from 'os';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
@@ -33,7 +46,71 @@ function parseArgs(argv) {
 
 // ── active project from hot.md ───────────────────────────────────────────────
 
-function resolveActiveProject(hypoDir) {
+// Parse a single frontmatter scalar (mirrors the hook helpers in
+// hypo-session-start.mjs / hypo-cwd-change.mjs — kept local per the hook
+// self-contained convention rather than shared, to avoid script↔hook coupling).
+function parseFrontmatterField(content, key) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const line = m[1].split('\n').find((l) => l.startsWith(`${key}:`));
+  if (!line) return null;
+  return line
+    .slice(key.length + 1)
+    .trim()
+    .replace(/^['"]|['"]$/g, '');
+}
+
+// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
+// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
+// when cwd is falsy or matches none. resume gives this authority OVER recency
+// (ADR 0044): a cwd↔working_dir match wins regardless of which row is newest.
+function pickByCwd(hypoDir, slugs, cwd) {
+  if (!cwd) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const slug of slugs) {
+    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
+    if (!existsSync(indexPath)) continue;
+    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
+    if (!wd) continue;
+    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
+    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
+    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
+      bestLen = resolved.length;
+      best = slug;
+    }
+  }
+  return best;
+}
+
+// When cwd is set but no project's working_dir matches it, resume falls back to
+// recency silently — the user lands in an unrelated project with no clue why.
+// Emit a one-line stderr diagnostic (stdout `Project:`/`--json` contract is untouched)
+// naming why each candidate failed: missing index.md, missing working_dir, or a
+// working_dir that simply doesn't contain cwd. Logic mirrors pickByCwd's lookup.
+function warnCwdFallback(hypoDir, slugs, cwd) {
+  // No cwd, or no candidate rows at all (fresh-init / no real project): there is
+  // nothing to "fall back to most-recent" toward, so stay silent — the caller
+  // surfaces the real "no active project found" error instead.
+  if (!cwd || slugs.length === 0) return;
+  const reasons = [];
+  for (const slug of slugs) {
+    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
+    if (!existsSync(indexPath)) {
+      reasons.push(`${slug} (no index.md)`);
+      continue;
+    }
+    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
+    if (!wd) reasons.push(`${slug} (no working_dir)`);
+    // else: has working_dir but didn't contain cwd — expected, not flagged.
+  }
+  const detail = reasons.length ? ` Candidates missing cwd metadata: ${reasons.join(', ')}.` : '';
+  process.stderr.write(
+    `note: cwd "${cwd}" matched no project working_dir; falling back to most-recent.${detail}\n`,
+  );
+}
+
+function resolveActiveProject(hypoDir, cwd = null) {
   const hotPath = join(hypoDir, 'hot.md');
   if (!existsSync(hotPath)) return null;
 
@@ -48,25 +125,62 @@ function resolveActiveProject(hypoDir) {
     ),
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
+    // cwd-first (ADR 0044): a cwd↔working_dir match wins over recency, across
+    // ALL rows (not just a same-date tie). The user is physically in that
+    // project, so cwd is a stronger intent signal than "some other project was
+    // touched more recently". This reverses the earlier tie-breaker-only
+    // semantics now that resume=cwd-positive (ADR 0043). Tradeoff: a stale cwd
+    // match can mask a genuinely newer project; `--project` overrides. close
+    // callers pass null → recency path below (resume=cwd-positive / close=no-pick).
+    if (cwd) {
+      const picked = pickByCwd(
+        hypoDir,
+        wikiRows.map((r) => r.slug),
+        cwd,
+      );
+      if (picked) return picked;
+    }
+    // No cwd match → most recent by date (stable-sort keeps the first table row
+    // on a tie, the legacy behavior).
+    if (cwd)
+      warnCwdFallback(
+        hypoDir,
+        wikiRows.map((r) => r.slug),
+        cwd,
+      );
     wikiRows.sort((a, b) => b.date.localeCompare(a.date));
     return wikiRows[0].slug;
   }
   // Legacy markdown-link rows: | [name](projects/name/...) | ...
-  const mdRow = content.match(/\|\s*\[([^\]]+)\]\(projects\/([^/)]+)/);
-  if (mdRow) return mdRow[2];
+  const mdSlugs = [...content.matchAll(/\|\s*\[([^\]]+)\]\(projects\/([^/)]+)/g)].map((m) => m[2]);
+  if (mdSlugs.length > 0) {
+    if (cwd) {
+      const picked = pickByCwd(hypoDir, mdSlugs, cwd);
+      if (picked) return picked;
+      warnCwdFallback(hypoDir, mdSlugs, cwd);
+    }
+    return mdSlugs[0]; // legacy: first table row
+  }
 
-  // fallback: most recently modified project with a session-state.md
+  // fallback: a cwd-matched project, else the most recently modified one with a
+  // session-state.md. (mtime is only a heuristic once hot.md can't name a
+  // project — an explicit working_dir match is safer, so cwd-first here too.)
   const projectsDir = join(hypoDir, 'projects');
   if (!existsSync(projectsDir)) return null;
 
+  // Skip the scaffold project init.mjs writes — it isn't a real active project.
+  const candidates = readdirSync(projectsDir).filter(
+    (p) => p !== '_template' && existsSync(join(projectsDir, p, 'session-state.md')),
+  );
+  if (cwd) {
+    const picked = pickByCwd(hypoDir, candidates, cwd);
+    if (picked) return picked;
+    warnCwdFallback(hypoDir, candidates, cwd);
+  }
   let latest = null;
   let latestMtime = 0;
-  for (const p of readdirSync(projectsDir)) {
-    // Skip the scaffold project init.mjs writes — it isn't a real active project.
-    if (p === '_template') continue;
-    const ssPath = join(projectsDir, p, 'session-state.md');
-    if (!existsSync(ssPath)) continue;
-    const mtime = statSync(ssPath).mtimeMs;
+  for (const p of candidates) {
+    const mtime = statSync(join(projectsDir, p, 'session-state.md')).mtimeMs;
     if (mtime > latestMtime) {
       latestMtime = mtime;
       latest = p;
@@ -93,7 +207,7 @@ function readHot(hypoDir, project) {
 
 const args = parseArgs(process.argv);
 
-const project = args.project || resolveActiveProject(args.hypoDir);
+const project = args.project || resolveActiveProject(args.hypoDir, process.cwd());
 
 if (!project) {
   console.error('Error: no active project found. Use --project=<name> or create a hot.md entry.');

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;
 
@@ -64,7 +82,7 @@ try {
   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)`);
@@ -79,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));

package/scripts/uninstall.mjs

@@ -15,7 +15,7 @@
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
  *
- * Extensions (ADR 0024 fix #34): hypo-ext-* hard-copies under
+ * Extensions (ADR 0024): hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
  * --codex) are removed when their on-disk SHA matches the recorded one in
  * ~/.claude/hypo-pkg.json#extensions.<target>. User-modified copies are preserved