@pcircle/memesh 4.8.5 → 4.9.3

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

@@ -75,15 +75,14 @@ export function removeFromFts(db, entityId, name, prevObsText, prevTitle) {
         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

@@ -1,4 +1,5 @@
-import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'fs';
+import { appendFileSync, chmodSync, closeSync, constants as fsConstants, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'fs';
+import { createHash } from 'crypto';
 import { spawn } from 'child_process';
 import { MemeshDatabase } from './_generated/sqlite.js';
 import { dirname, join } from 'path';
@@ -31,7 +32,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 +127,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 +164,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 +364,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 +556,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
@@ -601,10 +597,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
@@ -833,6 +828,154 @@ const POLICY_RANK = { off: 0, patch: 1, minor: 2, major: 3 };
 const BUMP_RANK = { patch: 1, minor: 2, major: 3 };
 const AUTO_UPDATE_CACHE_FRESHNESS_MS = 24 * 60 * 60 * 1000;
 
+function autoUpdateConsentPath(sessionId, currentVersion, latestVersion, channel = 'unknown') {
+  if (typeof sessionId !== 'string' || sessionId.length === 0 || sessionId === 'unknown') return null;
+  const key = createHash('sha256')
+    .update(`${sessionId}\0${currentVersion}\0${latestVersion}\0${channel}`)
+    .digest('hex');
+  return join(memeshDir(), 'update-consent', `${key}.json`);
+}
+
+function updatePromptClaimPath(sessionId, currentVersion, latestVersion) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0 || sessionId === 'unknown') return null;
+  const key = createHash('sha256')
+    .update(`${sessionId}\0${currentVersion}\0${latestVersion}`)
+    .digest('hex');
+  return join(memeshDir(), 'update-prompt-claims', `${key}.json`);
+}
+
+/**
+ * Atomically claim the one first-use update notice for a session/version.
+ * Separate host hooks can start at the same time; a read-then-write pending
+ * marker lets both print the prompt. O_EXCL makes the claim the decision.
+ */
+export function claimUpdatePrompt(sessionId, currentVersion, latestVersion, channel) {
+  const path = updatePromptClaimPath(sessionId, currentVersion, latestVersion);
+  if (!path || typeof channel !== 'string' || channel.length === 0) return false;
+  try {
+    ensurePrivateDir(join(memeshDir(), 'update-prompt-claims'));
+    // A crash can leave a pending claim before the hook emits its output.
+    // Reclaim only when that owner process is definitely gone; emitted
+    // claims remain session-scoped and continue suppressing duplicates.
+    try {
+      const existing = JSON.parse(readFileSync(path, 'utf8'));
+      const ownerPid = Number(existing?.ownerPid);
+      if (existing?.decision === 'pending' && Number.isInteger(ownerPid) && ownerPid > 0) {
+        try {
+          process.kill(ownerPid, 0);
+        } catch (err) {
+          if (err?.code === 'ESRCH') unlinkSync(path);
+        }
+      }
+    } catch {
+      // A corrupt claim fails closed at the O_EXCL step below.
+    }
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    try {
+      writeFileSync(fd, JSON.stringify({
+        sessionId,
+        currentVersion,
+        latestVersion,
+        channel,
+        decision: 'pending',
+        ownerPid: process.pid,
+        recordedAt: new Date().toISOString(),
+      }));
+    } finally {
+      closeSync(fd);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function finalizeUpdatePromptClaim(sessionId, currentVersion, latestVersion) {
+  const path = updatePromptClaimPath(sessionId, currentVersion, latestVersion);
+  if (!path || !existsSync(path)) return false;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    if (value?.decision !== 'pending' || Number(value.ownerPid) !== process.pid) return false;
+    writePrivateJson(path, { ...value, decision: 'emitted', emittedAt: new Date().toISOString() });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readUpdatePromptClaim(sessionId, currentVersion, latestVersion) {
+  const path = updatePromptClaimPath(sessionId, currentVersion, latestVersion);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readAutoUpdateConsent(sessionId, currentVersion, latestVersion, channel = 'unknown') {
+  const path = autoUpdateConsentPath(sessionId, currentVersion, latestVersion, channel);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} sessionId
+ * @param {string} currentVersion
+ * @param {string} latestVersion
+ * @param {string|null} [channel=null]
+ */
+export function findAutoUpdateConsent(sessionId, currentVersion, latestVersion, channel = null) {
+  if (typeof sessionId !== 'string' || !sessionId || sessionId === 'unknown') return null;
+  try {
+    const dir = join(memeshDir(), 'update-consent');
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.json')) continue;
+      try {
+        const value = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+        if (value?.sessionId === sessionId
+          && value?.currentVersion === currentVersion
+          && value?.latestVersion === latestVersion
+          && (channel === null || value?.channel === channel)) return value;
+      } catch { /* ignore one corrupt marker */ }
+    }
+  } catch { /* missing/unreadable consent dir */ }
+  return null;
+}
+
+export function writeAutoUpdateConsent(sessionId, currentVersion, latestVersion, channel, decision) {
+  const path = autoUpdateConsentPath(sessionId, currentVersion, latestVersion, channel);
+  if (!path || !['pending', 'approved', 'declined'].includes(decision)) return false;
+  try {
+    ensurePrivateDir(join(memeshDir(), 'update-consent'));
+    writePrivateJson(path, {
+      sessionId,
+      currentVersion,
+      latestVersion,
+      channel,
+      decision,
+      recordedAt: new Date().toISOString(),
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function parseAutoUpdateConsent(prompt) {
+  if (typeof prompt !== 'string') return null;
+  const value = prompt.trim().toLowerCase().replace(/[.!?。！？]+$/u, '');
+  if (/^(?:yes|y|upgrade|update|install(?: it)?|go ahead|是|好|升級|更新|安裝)$/.test(value)) return 'approved';
+  if (/^(?:no|n|not now|later|不要|不用|稍後|暫時不要)$/.test(value)) return 'declined';
+  return null;
+}
+
 export function decideAutoUpdateHook(currentVersion, cache, policy) {
   if (!cache || cache.currentVersion !== currentVersion) return { run: false };
   const latest = cache.latestVersion;

package/scripts/hooks/session-start.js

@@ -26,6 +26,10 @@ import {
   memeshDir as memeshHomeDir,
   parseTaskState,
   readRepoState,
+  readAutoUpdateConsent,
+  claimUpdatePrompt,
+  finalizeUpdatePromptClaim,
+  readUpdatePromptClaim,
   readUpdateCheckCache,
   repoStateLines,
   resolvePluginRoot,
@@ -34,6 +38,7 @@ import {
   homeDir,
   taskStateName,
   writeCitationRule,
+  writeAutoUpdateConsent,
   writePrivateJson,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
@@ -326,6 +331,43 @@ function detectInstallChannelHook(pluginRoot) {
   }
 }
 
+function buildUpdateConsentPrompt(sessionId, currentVersion, cache, channel) {
+  if (!sessionId || sessionId === 'unknown' || !cache || cache.currentVersion !== currentVersion) return null;
+  if (!cache.latestVersion || !isStrictlyOlder(currentVersion, cache.latestVersion)) return null;
+  const existing = readAutoUpdateConsent(sessionId, currentVersion, cache.latestVersion, channel);
+  if (existing?.decision) return null;
+  // Claim the session-level notice before emitting it. A resumed hook or a
+  // concurrent host process (including a second host channel) sees the
+  // atomic claim and does not duplicate the ask.
+  if (readUpdatePromptClaim(sessionId, currentVersion, cache.latestVersion)
+    || !claimUpdatePrompt(sessionId, currentVersion, cache.latestVersion, channel)) return null;
+  const target = channel === 'plugin-marketplace'
+    ? 'the installed marketplace plugin'
+    : channel === 'npm-global' ? 'the global memesh installation' : 'this MeMesh installation';
+  if (channel !== 'npm-global') {
+    const pluginRoot = resolvePluginRoot(import.meta.url);
+    const action = channel === 'plugin-marketplace'
+      ? pluginUpgradeLine(pluginRoot)
+      : channel === 'source-checkout'
+        ? '    Source checkout: pull and rebuild (`git pull && npm install && npm run build`).'
+        : channel === 'npm-local'
+          ? '    Project-local install: run `npm install @pcircle/memesh@latest` in the project that installed it.'
+          : '    Update it through the tool or package manager that installed MeMesh.';
+    return {
+      system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. This installation cannot be upgraded automatically from this session.\n${action}`,
+      context: `MeMesh ${cache.latestVersion} is available for ${target}, but this channel has no safe in-session installer. Show the user the channel-specific update action and do not claim that an Upgrade reply will install it.`,
+    };
+  }
+  // The npm-global channel is the only hook-owned installer. Record a
+  // channel-specific pending consent for the Stop hook after the global
+  // session notice has been claimed.
+  if (!writeAutoUpdateConsent(sessionId, currentVersion, cache.latestVersion, channel, 'pending')) return null;
+  return {
+    system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. Reply “Upgrade” to install it, or “Not now” to skip for this session.`,
+    context: `MeMesh update consent is pending for this session. Ask the user whether to upgrade from ${currentVersion} to ${cache.latestVersion} for the ${target}. Wait for an explicit Upgrade or Not now response; do not install without affirmative consent.`,
+  };
+}
+
 /**
  * Which plugin runtime owns this copy: 'claude-code', 'codex', or null.
  *
@@ -503,6 +545,15 @@ function runPostBannerUpdateTasks() {
   if (__postBannerRan) return;
   __postBannerRan = true;
   try {
+    // A first-use session has no database yet. Starting the detached
+    // `memesh status` refresh in that state makes status create/migrate the
+    // database while the next SessionStart may already be opening it
+    // read-only. SQLite can expose that window as a partially-created schema
+    // (for example, `entities` exists while `tags` does not), turning a
+    // harmless update notice into "memories not loaded". The next session
+    // after the first capture will refresh the cache once the database is
+    // fully established; consent itself was already emitted above.
+    if (!existsSync(dbPath)) return;
     let installedVersion = null;
     try {
       const pluginRoot = resolvePluginRoot(import.meta.url);
@@ -679,7 +730,21 @@ process.stdin.on('end', async () => {
       // With no database there is nothing to recall either — the warning IS
       // the whole truth, and "memories will be created as you work" would
       // contradict it one line later.
-      output(combineWithBanner(captureWarning ?? '◉ MeMesh ready · no database yet, memories will be created as you work'));
+      const emptySummary = combineWithBanner(captureWarning ?? '◉ MeMesh ready · no database yet, memories will be created as you work');
+      let consent = null;
+      let consentVersion = null;
+      let consentCache = null;
+      try {
+        const pluginRoot = resolvePluginRoot(import.meta.url);
+        const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+        consentVersion = typeof pkg.version === 'string' ? pkg.version : null;
+        consentCache = readUpdateCheckCache(consentVersion);
+        const channel = detectInstallChannelHook(pluginRoot);
+        consent = buildUpdateConsentPrompt(data.session_id, consentVersion, consentCache, channel);
+      } catch { /* best-effort */ }
+      output(consent ? `${consent.system}\n${emptySummary}` : emptySummary,
+        consent ? `${consent.context}\n\n${workPackageGuidance}` : workPackageGuidance);
+      if (consent) finalizeUpdatePromptClaim(data.session_id, consentVersion, consentCache?.latestVersion);
       return;
     }
 
@@ -1042,7 +1107,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, '');
@@ -1055,7 +1120,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
@@ -1150,20 +1215,41 @@ process.stdin.on('end', async () => {
       }
       const updateCache = readUpdateCheckCache(installedVersion);
       let bannerLines = [];
+      let updateConsentContext = null;
       if (installedVersion) {
         const deprecation = buildDeprecationBanner(installedVersion, updateCache);
         if (deprecation.length > 0) {
           bannerLines = deprecation;
         } else {
-          bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache,
-            () => detectInstallChannelHook(resolvePluginRoot(import.meta.url)));
+          const channel = detectInstallChannelHook(resolvePluginRoot(import.meta.url));
+          const consent = buildUpdateConsentPrompt(data.session_id, installedVersion, updateCache, channel);
+          if (consent) {
+            // The first-use notice is the authoritative update message for
+            // this session. Do not append the softer 24h banner as well; a
+            // source/plugin user would otherwise see two contradictory
+            // update instructions in one SessionStart payload.
+            bannerLines = [consent.system];
+            updateConsentContext = consent.context;
+          } else if (readUpdatePromptClaim(data.session_id, installedVersion, updateCache?.latestVersion)) {
+            // A first-use notice was already shown (and may have been
+            // answered by UserPromptSubmit). Suppress the routine banner for
+            // the rest of this session as well.
+            bannerLines = [];
+          } else {
+            bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache, () => channel);
+          }
         }
       }
       const finalMessage = bannerLines.length > 0
         ? [...bannerLines.filter(l => l.length > 0), '', summary].join('\n')
         : summary;
 
-      output(withCaptureWarning(finalMessage), memoryContext);
+      output(withCaptureWarning(finalMessage), updateConsentContext
+        ? `${updateConsentContext}\n\n${memoryContext}`
+        : memoryContext);
+      if (updateConsentContext) {
+        finalizeUpdatePromptClaim(data.session_id, installedVersion, updateCache?.latestVersion);
+      }
 
       // Pre-read the noise-compression throttle on the handle we already
       // hold. compressWeeklyNoise() re-checks under its own connection, but
@@ -1221,9 +1307,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 {}
     }
 
@@ -1267,7 +1353,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 = {