@pcircle/memesh 4.8.3 → 4.9.0

package/scripts/hooks/_generated/core-paths.js

@@ -11,6 +11,8 @@ import os from 'os';
 import path from 'path';
 import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
+export const AGENT_ROUTER_SOCKET_FILENAME = 'agent-router-v2.sock';
+const LEGACY_AGENT_ROUTER_SOCKET_FILENAME = 'agent-router.sock';
 export function homeDir() {
     const home = process.env.HOME;
     if (home && home.length > 0)
@@ -31,6 +33,15 @@ export function getMemeshDirFromDbPath() {
         ? path.dirname(process.env.MEMESH_DB_PATH)
         : memeshDir();
 }
+export function getAgentRouterSocketPath() {
+    return path.join(getMemeshDirFromDbPath(), AGENT_ROUTER_SOCKET_FILENAME);
+}
+export function normalizeAgentRouterSocketPath(socketPath) {
+    const dataDir = getMemeshDirFromDbPath();
+    return socketPath === path.join(dataDir, LEGACY_AGENT_ROUTER_SOCKET_FILENAME)
+        ? getAgentRouterSocketPath()
+        : socketPath;
+}
 export function getProjectName(cwdInput) {
     const cwd = cwdInput && cwdInput.length > 0 ? cwdInput : process.cwd();
     const cached = projectNameCache.get(cwd);
@@ -44,22 +55,36 @@ const projectNameCache = new Map();
 function resolveProjectIdentity(cwd) {
     const remote = tryGit(cwd, ['config', '--get', 'remote.origin.url']);
     if (remote) {
-        const slug = slugFromRemoteUrl(remote);
-        if (slug)
-            return slug;
+        const locator = canonicalRemoteLocator(remote);
+        if (locator) {
+            const label = path.posix.basename(locator).replace(/\.git$/i, '');
+            return projectIdentity(label, locator);
+        }
     }
     const root = tryGit(cwd, ['rev-parse', '--show-toplevel']);
-    if (root)
-        return path.basename(root);
+    const commonDir = root
+        ? tryGit(cwd, ['rev-parse', '--git-common-dir'])
+        : null;
+    const absoluteCommonDir = commonDir ? path.resolve(cwd, commonDir) : null;
+    const localPath = absoluteCommonDir && path.basename(absoluteCommonDir) === '.git'
+        ? path.dirname(absoluteCommonDir)
+        : (root ?? cwd);
     let real;
     try {
-        real = fs.realpathSync.native(cwd);
+        real = fs.realpathSync.native(localPath);
     }
     catch {
-        real = path.resolve(cwd);
+        real = path.resolve(localPath);
     }
-    const suffix = createHash('sha256').update(real).digest('hex').slice(0, 8);
-    return `${path.basename(real)}-${suffix}`;
+    return projectIdentity(path.basename(real), real);
+}
+const PROJECT_HASH_HEX_LENGTH = 32;
+const PROJECT_ID_MAX_LENGTH = 200;
+const PROJECT_LABEL_MAX_LENGTH = PROJECT_ID_MAX_LENGTH - PROJECT_HASH_HEX_LENGTH - 1;
+function projectIdentity(label, locator) {
+    const readable = label.normalize('NFC').slice(0, PROJECT_LABEL_MAX_LENGTH) || 'project';
+    const suffix = createHash('sha256').update(locator).digest('hex').slice(0, PROJECT_HASH_HEX_LENGTH);
+    return `${readable}~${suffix}`;
 }
 function tryGit(cwd, args) {
     try {
@@ -75,12 +100,61 @@ function tryGit(cwd, args) {
         return null;
     }
 }
-export function slugFromRemoteUrl(url) {
-    const cleaned = url.trim().replace(/\.git$/i, '').replace(/[/\\]+$/, '');
-    if (!cleaned)
+export function canonicalRemoteLocator(remote) {
+    const value = remote.trim();
+    if (!value)
+        return null;
+    if (path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value))
+        return null;
+    let host;
+    let port = '';
+    let user;
+    let remotePath;
+    let transport;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value)) {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            return null;
+        }
+        if (parsed.protocol === 'file:' || !parsed.hostname)
+            return null;
+        host = parsed.hostname.toLowerCase();
+        port = parsed.port;
+        const protocol = parsed.protocol.toLowerCase();
+        if ((protocol === 'ssh:' || protocol === 'git+ssh:') && port === '22')
+            port = '';
+        user = parsed.username;
+        remotePath = parsed.pathname;
+        transport = protocol === 'ssh:' || protocol === 'git+ssh:'
+            ? 'ssh-absolute'
+            : protocol.slice(0, -1);
+    }
+    else {
+        const scp = /^(?:([^@]+)@)?(\[[^\]]+\]|[^:/]+):(.+)$/.exec(value);
+        if (!scp)
+            return null;
+        user = scp[1] ?? '';
+        host = scp[2].toLowerCase();
+        remotePath = scp[3];
+        transport = remotePath.startsWith('/') ? 'ssh-absolute' : 'ssh-relative';
+    }
+    const pathWithoutSlashes = remotePath.replace(/^\/+|\/+$/g, '');
+    if (!host || !pathWithoutSlashes)
         return null;
-    const seg = cleaned.split(/[/:\\]/).filter(Boolean).pop();
-    return seg && seg.length > 0 ? seg : null;
+    const endpoint = `${host}${port ? `:${port}` : ''}`;
+    const standardGithub = host === 'github.com'
+        && port === ''
+        && (transport === 'https' || ((transport === 'ssh-relative' || transport === 'ssh-absolute') && user === 'git'));
+    const normalizedPath = standardGithub
+        ? pathWithoutSlashes.replace(/\.git$/i, '')
+        : pathWithoutSlashes;
+    if (standardGithub)
+        return `${endpoint}/${normalizedPath}`;
+    const authority = transport.startsWith('ssh-') && user ? `${user}@${endpoint}` : endpoint;
+    return `${transport}://${authority}/${normalizedPath}`;
 }
 export function _clearProjectNameCache() {
     projectNameCache.clear();

package/scripts/hooks/_generated/fts-index.js

@@ -67,18 +67,22 @@ function foldTitleIntoObservations(title, observationsText) {
 }
 export function removeFromFts(db, entityId, name, prevObsText, prevTitle) {
     try {
+        const indexed = db
+            .prepare('SELECT COUNT(*) AS c FROM entities_fts WHERE rowid = ?')
+            .get(entityId);
+        if (!indexed || indexed.c === 0)
+            return;
         db.prepare("INSERT INTO entities_fts (entities_fts, rowid, name, observations) VALUES('delete', ?, ?, ?)").run(entityId, toIndexForm(name), toIndexForm(foldTitleIntoObservations(prevTitle, prevObsText)));
     }
     catch (err) {
-        if (isBenignFtsDeleteError(err))
-            return;
-        process.stderr.write(`[memesh fts-index] removeFromFts(rowid=${entityId}) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        try {
+            process.stderr.write(`[memesh fts-index] removeFromFts(rowid=${entityId}) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        catch {
+        }
+        throw err;
     }
 }
-function isBenignFtsDeleteError(err) {
-    const msg = err?.message ?? '';
-    return /no such rowid|values do not match|no such row\b/i.test(msg);
-}
 export function joinIndexedObservations(contents) {
     return contents.join(' ');
 }

package/scripts/hooks/_generated/schema.js

@@ -56,8 +56,7 @@ CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity_id);
 CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity_id);
 CREATE INDEX IF NOT EXISTS idx_entities_type_created ON entities(type, created_at);
 
--- Migration markers and small bits of persistent state (index segmentation
--- version, embedding dimension, pending-reindex flags, backfill markers).
+-- Migration markers and small bits of persistent state.
 --
 -- This used to be created ad hoc by each helper that needed it — four inline
 -- CREATE TABLE IF NOT EXISTS copies in src/db.ts, none of them visible to

package/scripts/hooks/_shared.js

@@ -31,7 +31,7 @@ import {
   getMemeshDirFromDbPath,
   getProjectName,
   redactSecrets,
-  slugFromRemoteUrl,
+  canonicalRemoteLocator,
 } from './_generated/core-paths.js';
 import { autoCaptureDecision } from './_generated/capture-flag.js';
 export { assembleTopologyBlock, buildReferenceContext, extractCitedMemoryIds, DEFAULT_TOPOLOGY_BUDGET, GLOBAL_TOPOLOGY_LIMIT, SNIPPET_FETCH_CHARS, TOPOLOGY_CANDIDATE_CAP } from './_generated/work-topology.js';
@@ -126,15 +126,15 @@ import {
   tokenizeQuery,
 } from './_generated/fts-index.js';
 
-export { homeDir, memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, redactSecrets, slugFromRemoteUrl };
+export { homeDir, memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, redactSecrets, canonicalRemoteLocator };
 
 /**
  * Resolve the package root from a hook file's `import.meta.url`.
  *
  * Hooks live at `<pkgRoot>/scripts/hooks/<file>.js`, so the path needs
  * three `dirname()` hops to reach `<pkgRoot>`. Centralising this here
- * prevents the off-by-one regression that silently disabled noise
- * compression and LLM failure analysis between 4.0.4–4.1.0 (the inline
+ * prevents the off-by-one regression that silently disabled hook-to-core
+ * imports between 4.0.4–4.1.0 (the inline
  * `dirname(dirname(...))` only reached `<pkgRoot>/scripts`, and the
  * surrounding `catch` swallowed the resulting ENOENT).
  *
@@ -163,7 +163,7 @@ export function resolvePluginRoot(metaUrl) {
  *
  * That error is caught by each caller's surrounding try/catch and only
  * traced to stderr, so on Windows every hook that reaches for a dist module
- * — LLM failure analysis, lesson creation, dream auto-trigger, auto-decay —
+ * — lifecycle reads, lesson creation, and auto-decay —
  * silently did nothing, while macOS/Linux and `memesh doctor` stayed green.
  * A textbook fake-working boundary: the discipline of converting the path
  * (already applied to the install-channel import above via
@@ -363,19 +363,15 @@ export function openHookDb(env = process.env, opts = {}) {
   const dbDir = env.MEMESH_DB_PATH ? dirname(env.MEMESH_DB_PATH) : memeshDir();
   if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 
-  // `allowExtension` matches src/db.ts: it only permits a later
-  // `enableLoadExtension(true)`, and session-summary.js needs one to load
-  // sqlite-vec through this handle. The switch itself stays off.
-  const db = new MemeshDatabase(dbPath, { allowExtension: true });
+  const db = new MemeshDatabase(dbPath);
   db.pragma('journal_mode = WAL');
   db.pragma('foreign_keys = ON');
   // A hook waits for a held write lock for less time than Claude Code will
   // wait for the hook.
   //
-  // `MemeshDatabase` sets `busy_timeout = 30000`, and that number is right
-  // for the processes it was chosen for: a 30k-vector `swapVectorGeneration`
-  // holds the write lock for ~9s, and the CLI, the MCP server and the HTTP
-  // server should WAIT for it rather than fail. A hook cannot. Its budget in
+  // `MemeshDatabase` sets `busy_timeout = 30000`, which lets ordinary CLI,
+  // MCP and HTTP operations wait through brief write contention. A hook
+  // cannot use that whole budget. Its timeout in
   // `hooks/hooks.json` is 3s (UserPromptSubmit) to 10s (Stop, PreCompact),
   // so a 30s wait has exactly one possible ending: the harness kills the
   // hook. The capture is lost either way — the difference is that the user
@@ -559,9 +555,8 @@ export { truncateTitle } from './_generated/title.js';
  * as two implementations of the same contract).
  *
  * The caller MUST open its DB with `openHookDb(env, { fts: true })` so the FTS
- * table is guaranteed present. Embeddings + auto-tagging + signal-scoring are
- * deliberately NOT done here: hooks are cheap always-on capture, and those are
- * the heavier, user-initiated `remember` concerns (core owns them).
+ * table is guaranteed present. Signal scoring is deliberately not done here:
+ * hooks stay a cheap always-on capture path and core owns later enrichment.
  *
  * @param {import('./_generated/sqlite.js').MemeshDatabase} db - an open hook DB handle
  * @param {{name: string, type: string, observations?: string[], tags?: string[], title?: string | null, metadata?: Record<string, unknown>}} entity
@@ -585,6 +580,11 @@ export function captureEntity(db, { name, type, observations = [], tags = [], ti
   // retried, because the callers dedupe on the entity NAME existing —
   // `INSERT OR IGNORE` reports "already there" on the next run and the
   // half-written state is permanent.
+  //
+  // Returns `{ id, isNew, observationsWritten }`, or null when the entity row
+  // could not be resolved. `observationsWritten` may be lower than
+  // `observations.length`: an observation whose exact content is already on
+  // the entity is not stored again (see the dedupe in captureEntityInner).
   return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata }))();
 }
 
@@ -596,10 +596,9 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // earlier writer (possibly another host, via MCP) already recorded.
   //
   // title_source: every title a hook writes is machine-derived, so it is
-  // marked 'heuristic'. The mark is what lets a later LLM titling pass
-  // (dreamer backfill) know which titles it may replace — an UNMARKED title
-  // is treated as human-provided and never touched, so omitting the mark
-  // here would make today's date+verb titles permanent.
+  // marked 'heuristic'. The mark distinguishes generated display text from an
+  // unmarked human-provided title, so later reviewed edits can preserve the
+  // ownership boundary.
   const insertMetadata = { ...(metadata ?? {}), provenance: { source_host: 'claude-code' } };
   if (title != null) insertMetadata.title_source = 'heuristic';
   const insertResult = db
@@ -655,8 +654,47 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // BY + the one join rule), via the generated fts-index copy.
   const prevObsText = isNew ? undefined : indexedObservationText(db, id);
 
+  // Never store the same sentence twice on one entity (#240, widened).
+  //
+  // #240 was fixed in session-summary.js alone, with an EXISTENCE guard: "if
+  // this session already has an entity, bail". Its two siblings never got one
+  // and wrote 2,202 duplicate rows on the maintainer's graph —
+  // `pre-compact-<sessionId>` 2,188 of them (worst entity: 220 observations,
+  // 2 distinct), `commit-<sha>` 14.
+  //
+  // The guard belongs HERE, on CONTENT, not there, on existence, because a
+  // pre-compact entity is per-session and a session legitimately compacts
+  // more than once: entity 1947's 110 captures span four days. An existence
+  // guard would have dropped a second, genuinely different compaction
+  // ("Tool calls: 47", "Files edited: …") along with the identical ones. A
+  // content guard drops only rows that add nothing — a re-write of a sentence
+  // already stored carries no information, whatever produced it.
+  //
+  // Unconditional rather than opt-in: every caller of this function is an
+  // auto-capture hook writing machine-derived facts, and none of them has a
+  // case where re-storing an identical string means something. A flag two of
+  // three callers pass would be one more proxy for the question.
+  //
+  // Filtered ONCE, up front, because `allObsText` below composes the FTS text
+  // from this list rather than re-reading the rows. Filtering only at the
+  // insert loop would index text for rows that do not exist, and
+  // `entities_fts` is contentless: the next delete would not match, which is
+  // the "database disk image is malformed" failure this file warns about
+  // above. The `seen` set also collapses repeats WITHIN one call.
+  const seen = new Set(
+    isNew
+      ? []
+      : db.prepare('SELECT content FROM observations WHERE entity_id = ?').all(id).map((r) => r.content),
+  );
+  const freshObservations = [];
+  for (const obs of observations) {
+    if (seen.has(obs)) continue;
+    seen.add(obs);
+    freshObservations.push(obs);
+  }
+
   const insertObs = db.prepare('INSERT INTO observations (entity_id, content) VALUES (?, ?)');
-  for (const obs of observations) insertObs.run(id, obs);
+  for (const obs of freshObservations) insertObs.run(id, obs);
   const insertTag = db.prepare('INSERT OR IGNORE INTO tags (entity_id, tag) VALUES (?, ?)');
   for (const tag of tags) insertTag.run(id, tag);
 
@@ -673,7 +711,7 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // upserted entity's accumulated observation count.
   const obsParts = [];
   if (prevObsText) obsParts.push(prevObsText);
-  if (observations.length) obsParts.push(joinIndexedObservations(observations));
+  if (freshObservations.length) obsParts.push(joinIndexedObservations(freshObservations));
   const allObsText = joinIndexedObservations(obsParts);
   // Current title is fully determined by the branches above — no re-read.
   const currentTitle = isNew
@@ -681,7 +719,11 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
     : ((title !== undefined && title !== previousTitle) ? title : previousTitle);
   insertFtsRow(db, id, name, allObsText, currentTitle);
 
-  return { id, isNew };
+  // `observationsWritten` is what actually landed, which is no longer the same
+  // as `observations.length` once the dedupe above can drop rows. A caller
+  // that reports a count to the user must read this one — pre-compact.js
+  // printed "Saved 2 observations" on a run that stored none.
+  return { id, isNew, observationsWritten: freshObservations.length };
 }
 
 const PRIVATE_DIR_MODE = 0o700;

package/scripts/hooks/decision-nudge.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+// Decision Nudge — PostToolUse hook for ExitPlanMode and AskUserQuestion (#277).
+//
+// MeMesh's read side is automatic (SessionStart, PreToolUse Edit/Write inject
+// memories), but the write side had no in-flow trigger: an agent could make
+// several decisions in a session and store none of them until the user said
+// "remember this". `ExitPlanMode` (a plan just got approved) and
+// `AskUserQuestion` (the user just chose between options) are the two tool
+// calls where a decision is most likely to have just been made, so this hook
+// fires there and reminds the model — once per tool per session — to use
+// `remember` if the decision is worth keeping.
+//
+// Contract, in order of importance:
+//   1. NEVER block or slow the tool call: every failure path is a silent
+//      pass (with a stderr trace for anything that looks like schema
+//      drift), and this hook only ever emits additionalContext — exit code
+//      stays 0 no matter what.
+//   2. NEVER open the database. Unlike the capture hooks (post-commit,
+//      session-summary, pre-compact), this hook writes nothing to MeMesh
+//      itself — it only reminds the model to. Nothing here needs a
+//      knowledge-graph handle, so nothing opens one; that keeps the hook
+//      fast (well under its 5s budget) and removes an entire class of
+//      failure (lock contention, migration, corrupt schema) from a hook
+//      whose only job is a one-line reminder.
+//   3. Rate-limited to at most once per tool per session, or a plan-heavy
+//      session would see the same line after every ExitPlanMode call. A
+//      per-(session, tool) flag file under MEMESH_DIR is the mechanism —
+//      see claimNudge() for why, and why it is a NEW mechanism rather than
+//      a revived one.
+
+import { openSync, closeSync, writeSync, constants as fsConstants } from 'fs';
+import { join } from 'path';
+import { ensurePrivateDir, getMemeshDirFromDbPath } from './_shared.js';
+
+// The only two tools this hook is wired to in hooks/hooks.json — kept as an
+// explicit allowlist (not "any PostToolUse call") so a future matcher typo
+// or a Claude Code tool rename fails closed (no nudge) rather than nudging
+// on every tool call.
+const TARGET_TOOLS = new Set(['ExitPlanMode', 'AskUserQuestion']);
+
+// Real Claude Code session ids are UUIDs; test fixtures use short slugs like
+// `contract-8`. Restricting to this set is what makes the id safe to embed
+// directly in a filename below — anything that fails this (including a
+// missing/non-string id) exits quietly rather than touching the filesystem.
+const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+// Bounded stdin read. The real payload here (tool_name, tool_input,
+// session_id, cwd) is a few KB at most — ExitPlanMode's plan text is the
+// largest field — so 1 MiB is generous headroom, not a working limit. This
+// stops a malformed/runaway payload from growing an unbounded string before
+// JSON.parse ever runs.
+const MAX_STDIN_BYTES = 1_048_576;
+
+let input = '';
+let overflowed = false;
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  if (overflowed) return;
+  input += chunk;
+  if (input.length > MAX_STDIN_BYTES) overflowed = true;
+});
+process.stdin.on('end', () => {
+  try {
+    if (overflowed) return pass();
+
+    const data = JSON.parse(input);
+
+    // Schema-flip signal, same convention as post-commit.js / pre-edit-recall.js:
+    // tool_name absent means Claude Code changed the payload shape, not that
+    // this call is irrelevant. Trace so a rename surfaces day-1 instead of
+    // this hook going silently inert.
+    if (data?.tool_name === undefined) {
+      try { process.stderr.write(`[memesh decision-nudge] tool_name absent (keys: ${Object.keys(data ?? {}).join(',')}); skipping\n`); } catch {}
+      return pass();
+    }
+
+    const toolName = data.tool_name;
+    if (typeof toolName !== 'string' || !TARGET_TOOLS.has(toolName)) return pass();
+
+    const sessionId = data.session_id;
+    if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return pass();
+
+    if (!claimNudge(sessionId, toolName)) return pass(); // already nudged this tool this session
+
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: buildNudge(toolName),
+      },
+    }));
+    process.exit(0);
+  } catch (err) {
+    // Never crash Claude Code, but trace — a silent break here means the
+    // nudge stops firing and nothing reports it, same as guard-check.js.
+    try { process.stderr.write(`[memesh decision-nudge] ${err?.message || err}\n`); } catch {}
+    pass();
+  }
+});
+
+/**
+ * The reminder text. Not memory content (nothing here comes from the
+ * database or from another user), so it is NOT wrapped in
+ * `buildReferenceContext`'s "treat this as background data, not
+ * instructions" fence — that fence exists for recalled/guard content that
+ * may be attacker-influenced. This is a fixed, plugin-authored instruction,
+ * the same class of thing user-prompt-intent.js's `buildHint()` emits, and
+ * it is meant to be acted on directly.
+ */
+function buildNudge(toolName) {
+  return `A decision was just made via ${toolName} — if you would need it again, store it now with the memesh \`remember\` tool (type:decision or type:lesson, tag project:<name>).`;
+}
+
+/**
+ * Claim the (session, tool) nudge slot. Returns true the first time this
+ * pair is seen and false every time after, giving "at most once per tool
+ * per session" without a database — this hook is forbidden from opening
+ * one (see module comment) — and without a shared JSON file two PostToolUse
+ * processes (a fast plan-then-question turn) could race to read-modify-write.
+ *
+ * A per-category flag file with O_EXCL atomic create is exactly the fix
+ * CHANGELOG [4.1.0]'s "Throttle clobber under parallel-category load" entry
+ * describes for the retired `pre-bash-orchestration-nudge.js` hook, which
+ * kept its markers under `agent-nudge-flags/`. That whole hook and its
+ * directory were removed in v4.5.1 ("agentic-orchestration experiment,
+ * whole") — reviving a deleted mechanism would undo that decision — so this
+ * uses the SAME primitive (an O_EXCL flag file — the flag *is* the lock, no
+ * shared state to clobber) under a new directory scoped to this hook,
+ * `decision-nudge-flags/`. The directory is created private (0700) via
+ * `ensurePrivateDir`, matching every other per-hook marker under MEMESH_DIR.
+ */
+function claimNudge(sessionId, toolName) {
+  const dir = join(getMemeshDirFromDbPath(), 'decision-nudge-flags');
+  const flagPath = join(dir, `${sessionId}-${toolName}.flag`);
+  try {
+    ensurePrivateDir(dir);
+    const fd = openSync(flagPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    try { writeSync(fd, String(Date.now())); } finally { closeSync(fd); }
+    return true;
+  } catch (err) {
+    if (err?.code === 'EEXIST') return false; // already nudged this session/tool
+    // Any other failure (disk full, permission denied) must not block the
+    // tool call, and the safe default for a hint is silence rather than a
+    // duplicate-nudge storm — so this counts as "already claimed".
+    try { process.stderr.write(`[memesh decision-nudge] could not claim ${flagPath}: ${err?.message || err}\n`); } catch {}
+    return false;
+  }
+}
+
+function pass() {
+  process.exit(0);
+}

package/scripts/hooks/post-commit.js

@@ -168,6 +168,17 @@ process.stdin.on('end', () => {
       // TYPE, which a hand-typed `memesh learn` satisfied all by itself.
       // The commit subject IS the title — git authors already wrote a
       // one-line human summary; nothing to synthesize.
+      //
+      // Re-capture of an already-stored commit is expected and harmless: this
+      // hook runs on PostToolUse, so any later Bash call while HEAD is
+      // unchanged rebuilds the same `commit-<sha>` payload. It used to APPEND
+      // it — three commit entities on the maintainer's graph reached 6
+      // observations / 3 distinct, one triple re-written 107 seconds after the
+      // first. captureEntity now refuses to store an observation whose exact
+      // content is already on the entity (#240, widened), which is the right
+      // guard here rather than "skip if the entity exists": a sha is immutable,
+      // so any line that DOES differ on a later run (diff stats that failed the
+      // first time and succeeded now) is new information and must still land.
       const written = captureEntity(db, {
         name: entityName,
         type: 'commit',

package/scripts/hooks/pre-compact.js

@@ -159,12 +159,20 @@ process.stdin.on('end', () => {
     // it announced a save that may not have happened, with a number that never
     // matched the one entity and handful of observations actually written.
     //
-    // `obsLines.length` is the honest count on the success branch:
-    // `captureEntity` inserts every observation or throws, so a non-null return
-    // means all of them landed.
+    // `written.observationsWritten` is the honest count, NOT `obsLines.length`:
+    // a session compacts more than once, and the second compaction's lines are
+    // usually word-for-word the first's ("Compaction reason: auto", "Tool
+    // calls: 0"), which captureEntity now declines to store twice. Reporting
+    // the built count would announce "Saved 2 observations" on a run that
+    // stored none — the same success-shaped lie this comment block exists to
+    // stop. Zero written is still a successful run: the memory is already
+    // there.
+    const stored = written ? written.observationsWritten : 0;
     const hookOutput = {
       systemMessage: written
-        ? `Saved ${obsLines.length} observations to MeMesh before compaction`
+        ? (stored > 0
+          ? `Saved ${stored} observations to MeMesh before compaction`
+          : 'MeMesh: this compaction added nothing new (already captured)')
         : 'MeMesh: could not save pre-compaction insights (see stderr)',
     };
     console.log(JSON.stringify(hookOutput));

package/scripts/hooks/session-start.js

@@ -334,11 +334,24 @@ function detectInstallChannelHook(pluginRoot) {
  * Claude Code wording rather than suppressing the hint entirely — the
  * banner is more useful naming the majority host than naming none.
  */
+/**
+ * Which plugin host is this install under — or `'unknown'` when we could not
+ * ask.
+ *
+ * `null` is a real answer from `detectPluginHost`: "this path is not under any
+ * plugin cache". So `detectPluginHost?.(root) ?? null` inside a bare catch,
+ * which is what this was, gave a module that failed to load and a detector
+ * that threw the SAME value as a confident "not Codex" — and
+ * `pluginUpgradeLine` then handed every Codex user the Claude Code command.
+ * `getCurrentInstallChannel` above already returns `'unknown'` for exactly
+ * this state; this now matches it.
+ */
 function pluginHostOf(pluginRoot) {
+  if (typeof _installChannelMod?.detectPluginHost !== 'function') return 'unknown';
   try {
-    return _installChannelMod?.detectPluginHost?.(pluginRoot) ?? null;
+    return _installChannelMod.detectPluginHost(pluginRoot);
   } catch {
-    return null;
+    return 'unknown';
   }
 }
 
@@ -354,9 +367,17 @@ function pluginHostOf(pluginRoot) {
  * happened. One owner, so it cannot happen again.
  */
 function pluginUpgradeLine(pluginRoot) {
-  if (pluginHostOf(pluginRoot) === 'codex') {
+  const host = pluginHostOf(pluginRoot);
+  if (host === 'codex') {
     return `    Run: codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh`;
   }
+  if (host === 'unknown') {
+    // Naming one host's command here would be a guess presented as an
+    // instruction. Rare — it needs `dist/core/install-channel.js` to be
+    // missing or unloadable — but that is a broken install, which is exactly
+    // when wrong upgrade advice costs the most.
+    return `    Run: memesh upgrade-plugin   (on Codex: codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh)`;
+  }
   return `    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`;
 }
 
@@ -1021,7 +1042,7 @@ process.stdin.on('end', async () => {
       // nothing — a fenced block containing only a branch name tells the
       // agent something it can already see. briefing.test.ts's parity case
       // is what keeps this identical to the tool side.
-      let memoryContext = '';
+      let memoryContext = workPackageGuidance;
       if (memoryLines.length > 0) {
         const repoLines = repoStateLines(readRepoState(data.cwd));
         if (repoLines.length > 0) memoryLines.unshift(...repoLines, '');
@@ -1034,7 +1055,7 @@ process.stdin.on('end', async () => {
         // charges task state plus project/foreign sections against the main
         // ceiling and global context against its small additive ceiling. It
         // returns whole lines only, so the closing fence cannot be cut.
-        memoryContext = buildReferenceContext(memoryLines);
+        memoryContext = buildReferenceContext(memoryLines) + '\n\n' + workPackageGuidance;
         // The citation contract — OUTSIDE the fence on purpose: the fence
         // declares its content "background data, not instructions", and
         // this line IS an instruction. One line is the entire write side of
@@ -1200,9 +1221,9 @@ process.stdin.on('end', async () => {
     } catch (err) {
       // Non-critical — noise compression failed, will retry next session.
       // Trace because this catch previously hid an off-by-one regression
-      // in resolvePluginRoot (4.0.4-4.1.0) that silently disabled both
-      // noise compression AND LLM failure analysis for three minor
-      // releases. A one-line stderr would have surfaced it on day 1.
+      // in resolvePluginRoot (4.0.4-4.1.0) that silently disabled noise
+      // compression for three minor releases. A one-line stderr would have
+      // surfaced it on day 1.
       try { process.stderr.write(`[memesh session-start] noise-compression: ${err?.message || err}\n`); } catch {}
     }
 
@@ -1246,7 +1267,9 @@ process.stdin.on('end', async () => {
  *
  * The shape is asserted by tests/helpers/hook-output-contract.ts.
  */
-function output(text, memoryContext) {
+const workPackageGuidance = 'Work packages: check work_package prepare for this project (digest or transcript). When available, offer a concise host-native interactive choice in the user’s conversation language: dispatch an agent task, later (defer not_now), or stop suggesting for this session. Never dispatch without the user choosing it. The Dashboard cannot dispatch agents, and no durable opt-out is implied.';
+
+function output(text, memoryContext = workPackageGuidance) {
   const payload = { systemMessage: text };
   if (memoryContext) {
     payload.hookSpecificOutput = {