@pcircle/memesh 4.7.3 → 4.8.0

package/scripts/hooks/_generated/schema.js

@@ -69,6 +69,235 @@ CREATE TABLE IF NOT EXISTS memesh_metadata (
   value TEXT NOT NULL
 );
 
+-- Local agent messaging core. Messages are immutable, deliveries identify the
+-- authorized recipient, events are the wakeup/catch-up surface, cursors keep
+-- the internal sequence opaque, and receipts are append-only facts that remain
+-- separate from delivery existence.
+CREATE TABLE IF NOT EXISTS agent_messages (
+  message_id         TEXT PRIMARY KEY,
+  project            TEXT NOT NULL,
+  sender             TEXT NOT NULL,
+  sender_host        TEXT,
+  recipient          TEXT NOT NULL,
+  content_type       TEXT NOT NULL,
+  correlation_id     TEXT,
+  reply_to_message_id TEXT,
+  privacy            TEXT NOT NULL,
+  payload_json       TEXT NOT NULL,
+  -- A tombstone replaces only a terminal payload. The original JSON bytes
+  -- are never reconstructed from these fields; they retain enough identity to
+  -- audit the erasure while the routing and lifecycle tables remain intact.
+  payload_sha256     TEXT,
+  payload_original_bytes INTEGER,
+  payload_tombstoned_at TIMESTAMP,
+  provenance_json    TEXT NOT NULL,
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS agent_message_deliveries (
+  delivery_id        TEXT PRIMARY KEY,
+  message_id         TEXT NOT NULL,
+  project            TEXT NOT NULL,
+  recipient          TEXT NOT NULL,
+  target_kind        TEXT NOT NULL DEFAULT 'principal' CHECK (target_kind IN ('principal', 'session')),
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (message_id) REFERENCES agent_messages(message_id) ON DELETE CASCADE,
+  UNIQUE(message_id, project, recipient)
+);
+
+CREATE TABLE IF NOT EXISTS agent_message_events (
+  event_sequence     INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_id           TEXT NOT NULL UNIQUE,
+  message_id         TEXT NOT NULL,
+  delivery_id        TEXT NOT NULL,
+  project            TEXT NOT NULL,
+  recipient          TEXT NOT NULL,
+  event_kind         TEXT NOT NULL,
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (message_id) REFERENCES agent_messages(message_id) ON DELETE CASCADE,
+  FOREIGN KEY (delivery_id) REFERENCES agent_message_deliveries(delivery_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS agent_message_idempotency (
+  project            TEXT NOT NULL,
+  sender             TEXT NOT NULL,
+  idempotency_key    TEXT NOT NULL,
+  request_hash       TEXT NOT NULL,
+  message_id         TEXT NOT NULL UNIQUE,
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (message_id) REFERENCES agent_messages(message_id) ON DELETE CASCADE,
+  PRIMARY KEY(project, sender, idempotency_key)
+);
+
+CREATE TABLE IF NOT EXISTS agent_message_cursors (
+  cursor_token       TEXT PRIMARY KEY,
+  project            TEXT NOT NULL,
+  recipient          TEXT NOT NULL,
+  event_sequence     INTEGER NOT NULL,
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS agent_message_receipts (
+  receipt_id         TEXT PRIMARY KEY,
+  message_id         TEXT NOT NULL,
+  project            TEXT NOT NULL,
+  recipient          TEXT NOT NULL,
+  receipt_kind       TEXT NOT NULL,
+  actor              TEXT NOT NULL,
+  idempotency_key    TEXT NOT NULL,
+  request_hash       TEXT NOT NULL,
+  detail_json        TEXT NOT NULL,
+  created_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (message_id) REFERENCES agent_messages(message_id) ON DELETE CASCADE,
+  UNIQUE(project, recipient, message_id, receipt_kind, idempotency_key)
+);
+
+-- Host-native push identity and lifecycle. A principal is stable, a session
+-- instance is ephemeral, and every connection to that session gets a strictly
+-- increasing generation. The activation checkpoint is intentionally created
+-- at first principal registration: principal-targeted history at or before it
+-- is durable inbox history, but is never replayed as a first-time host push.
+CREATE TABLE IF NOT EXISTS agent_principals (
+  project                     TEXT NOT NULL,
+  principal_id                TEXT NOT NULL,
+  activation_event_sequence   INTEGER NOT NULL,
+  created_at                  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY(project, principal_id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_session_instances (
+  project                  TEXT NOT NULL,
+  session_instance_id      TEXT NOT NULL,
+  principal_id             TEXT NOT NULL,
+  adapter_kind             TEXT NOT NULL,
+  last_generation          INTEGER NOT NULL DEFAULT 0,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY(project, session_instance_id),
+  FOREIGN KEY (project, principal_id) REFERENCES agent_principals(project, principal_id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_session_connections (
+  connection_id            TEXT PRIMARY KEY,
+  project                  TEXT NOT NULL,
+  principal_id             TEXT NOT NULL,
+  session_instance_id      TEXT NOT NULL,
+  generation               INTEGER NOT NULL,
+  adapter_kind             TEXT NOT NULL,
+  router_instance_id       TEXT NOT NULL,
+  lease_expires_at_ms      INTEGER NOT NULL,
+  connected_at             TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  disconnected_at          TIMESTAMP,
+  disconnect_reason        TEXT,
+  UNIQUE(project, session_instance_id, generation),
+  FOREIGN KEY (project, session_instance_id)
+    REFERENCES agent_session_instances(project, session_instance_id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_presence_facts (
+  presence_fact_id          TEXT PRIMARY KEY,
+  project                  TEXT NOT NULL,
+  principal_id             TEXT NOT NULL,
+  session_instance_id      TEXT NOT NULL,
+  connection_id            TEXT NOT NULL,
+  generation               INTEGER NOT NULL,
+  presence_kind            TEXT NOT NULL CHECK (presence_kind IN ('connected', 'heartbeat', 'disconnected', 'superseded')),
+  detail_json              TEXT NOT NULL,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (connection_id) REFERENCES agent_session_connections(connection_id)
+);
+
+-- Dispatch is at-least-once across a crash boundary. delivery_id is the stable
+-- adapter dispatch key; attempt_id identifies one invocation. A host_accept is
+-- a separate fact and never implies an agent acknowledgement or workflow
+-- outcome.
+CREATE TABLE IF NOT EXISTS agent_dispatch_attempts (
+  attempt_id               TEXT PRIMARY KEY,
+  delivery_id              TEXT NOT NULL,
+  project                  TEXT NOT NULL,
+  principal_id             TEXT NOT NULL,
+  session_instance_id      TEXT NOT NULL,
+  connection_id            TEXT NOT NULL,
+  generation               INTEGER NOT NULL,
+  router_instance_id       TEXT NOT NULL,
+  attempt_number           INTEGER NOT NULL,
+  result                   TEXT NOT NULL DEFAULT 'started' CHECK (result IN ('started', 'adapter_returned', 'adapter_rejected', 'adapter_failed', 'stale_generation')),
+  failure_code             TEXT,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  completed_at             TIMESTAMP,
+  UNIQUE(delivery_id, attempt_number),
+  FOREIGN KEY (delivery_id) REFERENCES agent_message_deliveries(delivery_id) ON DELETE CASCADE,
+  FOREIGN KEY (connection_id) REFERENCES agent_session_connections(connection_id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_host_accepts (
+  host_accept_id           TEXT PRIMARY KEY,
+  attempt_id               TEXT NOT NULL UNIQUE,
+  delivery_id              TEXT NOT NULL UNIQUE,
+  adapter_kind             TEXT NOT NULL,
+  receipt_json             TEXT NOT NULL,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (attempt_id) REFERENCES agent_dispatch_attempts(attempt_id),
+  FOREIGN KEY (delivery_id) REFERENCES agent_message_deliveries(delivery_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS agent_ack_facts (
+  ack_fact_id              TEXT PRIMARY KEY,
+  delivery_id              TEXT NOT NULL,
+  host_accept_id           TEXT NOT NULL,
+  actor                    TEXT NOT NULL,
+  idempotency_key          TEXT NOT NULL,
+  request_hash             TEXT NOT NULL,
+  detail_json              TEXT NOT NULL,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(delivery_id, actor, idempotency_key),
+  FOREIGN KEY (delivery_id) REFERENCES agent_message_deliveries(delivery_id) ON DELETE CASCADE,
+  FOREIGN KEY (host_accept_id) REFERENCES agent_host_accepts(host_accept_id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_workflow_facts (
+  workflow_fact_id         TEXT PRIMARY KEY,
+  delivery_id              TEXT NOT NULL,
+  actor                    TEXT NOT NULL,
+  workflow_state           TEXT NOT NULL,
+  idempotency_key          TEXT NOT NULL,
+  request_hash             TEXT NOT NULL,
+  detail_json              TEXT NOT NULL,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(delivery_id, actor, idempotency_key),
+  FOREIGN KEY (delivery_id) REFERENCES agent_message_deliveries(delivery_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS agent_retention_facts (
+  retention_fact_id        TEXT PRIMARY KEY,
+  message_id               TEXT NOT NULL,
+  actor                    TEXT NOT NULL,
+  retention_state          TEXT NOT NULL,
+  idempotency_key          TEXT NOT NULL,
+  request_hash             TEXT NOT NULL,
+  detail_json              TEXT NOT NULL,
+  created_at               TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(message_id, actor, idempotency_key),
+  FOREIGN KEY (message_id) REFERENCES agent_messages(message_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_message_events_recipient_sequence
+  ON agent_message_events(project, recipient, event_sequence);
+CREATE INDEX IF NOT EXISTS idx_agent_message_deliveries_scope
+  ON agent_message_deliveries(project, recipient, message_id);
+CREATE INDEX IF NOT EXISTS idx_agent_message_receipts_scope
+  ON agent_message_receipts(project, recipient, message_id, created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_message_cursors_unique_scope_sequence
+  ON agent_message_cursors(project, recipient, event_sequence);
+CREATE INDEX IF NOT EXISTS idx_agent_principals_activation
+  ON agent_principals(project, activation_event_sequence);
+CREATE INDEX IF NOT EXISTS idx_agent_session_connections_active
+  ON agent_session_connections(project, principal_id, session_instance_id, lease_expires_at_ms)
+  WHERE disconnected_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_agent_dispatch_attempts_delivery
+  ON agent_dispatch_attempts(delivery_id, attempt_number);
+CREATE INDEX IF NOT EXISTS idx_agent_workflow_facts_delivery_created
+  ON agent_workflow_facts(delivery_id, created_at, workflow_fact_id);
+
 -- Proof that a capture hook actually RAN. Nothing else in this schema can
 -- give it: every other signal is "a row was written", and "the hook ran and
 -- found nothing worth saving" is the healthy case that produces no row at
@@ -148,6 +377,32 @@ export function migrateEntitiesSchema(db) {
     addColumn('title', "ALTER TABLE entities ADD COLUMN title TEXT");
     db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_status ON entities(status);
      CREATE INDEX IF NOT EXISTS idx_entities_namespace ON entities(namespace);`);
+    const deliveryTableExists = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'agent_message_deliveries'")
+        .get();
+    if (!deliveryTableExists)
+        return;
+    const deliveryColumns = new Set(db.prepare("PRAGMA table_info(agent_message_deliveries)").all().map((column) => column.name));
+    if (!deliveryColumns.has('target_kind')) {
+        safeAlter(db, "ALTER TABLE agent_message_deliveries ADD COLUMN target_kind TEXT NOT NULL DEFAULT 'principal' " +
+            "CHECK (target_kind IN ('principal', 'session'))");
+    }
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_message_deliveries_target
+       ON agent_message_deliveries(project, target_kind, recipient, message_id);`);
+    const messageColumns = new Set(db.prepare("PRAGMA table_info(agent_messages)").all().map((column) => column.name));
+    const addMessageColumn = (column, sql) => {
+        if (messageColumns.has(column))
+            return;
+        safeAlter(db, sql);
+        messageColumns.add(column);
+    };
+    addMessageColumn('payload_sha256', 'ALTER TABLE agent_messages ADD COLUMN payload_sha256 TEXT');
+    addMessageColumn('payload_original_bytes', 'ALTER TABLE agent_messages ADD COLUMN payload_original_bytes INTEGER');
+    addMessageColumn('payload_tombstoned_at', 'ALTER TABLE agent_messages ADD COLUMN payload_tombstoned_at TIMESTAMP');
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_messages_tombstone
+       ON agent_messages(payload_tombstoned_at, created_at);
+     CREATE INDEX IF NOT EXISTS idx_agent_workflow_facts_delivery_created
+       ON agent_workflow_facts(delivery_id, created_at, workflow_fact_id);`);
 }
 export function ensureTagsUniqueIndex(db) {
     try {

package/scripts/hooks/_generated/task-state.js

@@ -72,7 +72,7 @@ const FIELD_LABELS = {
     goal: 'Goal',
     next: 'Next',
     blocked: 'Blocked',
-    done: 'Just finished',
+    done: 'Had just finished',
 };
 function ageInDays(updatedAt, now) {
     if (!updatedAt)
@@ -87,8 +87,8 @@ export function taskStateLines(state, project, now = new Date()) {
     if (isEmptyTaskState(state))
         return [];
     const days = ageInDays(state.updated_at, now);
-    const age = days === null ? '' : days === 0 ? ' (today)' : days === 1 ? ' (yesterday)' : ` (${days} days ago)`;
-    const lines = [`Where "${project}" was left off${age}:`];
+    const age = days === null ? 'at some point' : days === 0 ? 'today' : days === 1 ? 'yesterday' : `${days} days ago`;
+    const lines = [`Stated about "${project}" ${age}, and not revisited since:`];
     for (const field of TASK_STATE_FIELDS) {
         const value = state[field];
         if (value)

package/scripts/hooks/_generated/work-topology.js

@@ -13,6 +13,7 @@ export const WORK_LAYER_TYPES = new Set([
     'milestone',
     'pattern',
     'technical_pattern',
+    'product_improvement',
     'goal',
     'plan',
     'task-state',

package/scripts/hooks/_shared.js

@@ -1,6 +1,5 @@
 import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'fs';
 import { spawn } from 'child_process';
-import { createRequire } from 'module';
 import { MemeshDatabase } from './_generated/sqlite.js';
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -36,6 +35,7 @@ import {
 } from './_generated/core-paths.js';
 import { autoCaptureDecision } from './_generated/capture-flag.js';
 export { assembleTopologyBlock, buildReferenceContext, extractCitedMemoryIds, DEFAULT_TOPOLOGY_BUDGET, SNIPPET_FETCH_CHARS, TOPOLOGY_CANDIDATE_CAP } from './_generated/work-topology.js';
+export { readRepoState, repoStateLines } from './_generated/repo-state.js';
 export { matchingGuards, guardFromMetadata } from './_generated/guards.js';
 export { writeCitationRule, citationRulePath, CITATION_RULE_BODY } from './_generated/citation-rule.js';
 import { guardFromMetadata as guardFromMetadataLocal } from './_generated/guards.js';
@@ -128,8 +128,6 @@ import {
 
 export { homeDir, memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, redactSecrets, slugFromRemoteUrl };
 
-const require = createRequire(import.meta.url);
-
 /**
  * Resolve the package root from a hook file's `import.meta.url`.
  *
@@ -285,9 +283,13 @@ const VALID_AUTO_UPDATE_POLICIES = new Set(['off', 'patch', 'minor', 'major']);
  */
 export function resolveAutoUpdatePolicy(env = process.env) {
   const envVal = env.MEMESH_AUTO_UPDATE;
-  if (typeof envVal === 'string') {
+  if (envVal !== undefined) {
+    if (typeof envVal !== 'string') return 'off';
     const lowered = envVal.toLowerCase();
     if (VALID_AUTO_UPDATE_POLICIES.has(lowered)) return lowered;
+    // An explicit but malformed higher-priority value must not uncover a
+    // permissive config value and authorise an unattended global mutation.
+    return 'off';
   }
   const cfg = readHookConfig(env);
   if (typeof cfg.autoUpdate === 'string') {
@@ -827,84 +829,28 @@ export function decideAutoUpdateHook(currentVersion, cache, policy) {
 
 export function logAutoUpdate(line) {
   try {
-    const dir = getMemeshDirFromDbPath();
+    const dir = memeshDir();
     ensurePrivateDir(dir);
     const path = join(dir, 'auto-update.log');
     appendFileSync(path, `[${new Date().toISOString()}] ${line}\n`);
     try { chmodSync(path, 0o600); } catch { /* non-POSIX */ }
+    return true;
   } catch {
-    // Logging is best-effort.
-  }
-}
-
-export const AUTO_UPDATE_LOCK_TTL_MS = 10 * 60 * 1000;
-
-export function tryAcquireAutoUpdateLock(version) {
-  try {
-    const dir = memeshDir();
-    ensurePrivateDir(dir);
-    const lockPath = join(dir, 'auto-update.lock');
-    const fs = require('fs');
-    const myToken = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-    const payload = `${myToken}\n${process.pid}\n${Date.now()}\n${version}\n`;
-    try {
-      // O_CREAT|O_EXCL is the POSIX atomic create primitive — only one process wins.
-      const O_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL;
-      const fd = fs.openSync(lockPath, O_FLAGS, 0o600);
-      try { fs.writeFileSync(fd, payload); } finally { fs.closeSync(fd); }
-      return { acquired: true, lockPath };
-    } catch (err) {
-      if (err?.code !== 'EEXIST') throw err;
-    }
-    let stat;
-    try { stat = fs.statSync(lockPath); } catch { return { acquired: false, lockPath }; }
-    if (Date.now() - stat.mtimeMs <= AUTO_UPDATE_LOCK_TTL_MS) {
-      return { acquired: false, lockPath };
-    }
-    const tempPath = `${lockPath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
-    try {
-      fs.writeFileSync(tempPath, payload, { mode: 0o600 });
-      try { fs.unlinkSync(lockPath); } catch (e2) {
-        if (e2?.code !== 'ENOENT') {
-          try { fs.unlinkSync(tempPath); } catch { /* best-effort */ }
-          return { acquired: false, lockPath };
-        }
-      }
-      fs.renameSync(tempPath, lockPath);
-    } catch {
-      try { fs.unlinkSync(tempPath); } catch { /* best-effort */ }
-      return { acquired: false, lockPath };
-    }
-    // The "race" here is the lock primitive itself: we just renamed our
-    // temp file onto lockPath, then immediately read back to see whether
-    // our token won. If a concurrent caller's rename landed in the
-    // window between our rename and our read, their token is now there
-    // and we correctly conclude we did NOT acquire the lock. That race
-    // outcome IS the contract — last-writer-wins lock-file pattern, not
-    // a TOCTOU defect. (CodeQL js/file-system-race #82 is dismissed on
-    // the security dashboard with this rationale; CodeQL does not honor
-    // inline suppression comments, so dismissal is the correct route.)
-    let recorded;
-    try { recorded = fs.readFileSync(lockPath, 'utf8'); } catch { return { acquired: false, lockPath }; }
-    return recorded.split('\n')[0] === myToken
-      ? { acquired: true, lockPath }
-      : { acquired: false, lockPath };
-  } catch {
-    return { acquired: false, lockPath: null };
+    return false;
   }
 }
 
 /**
- * Spawn `npm install -g @pcircle/memesh@<version>` detached so the upgrade
- * can finish after this hook returns. Never blocks the session.
+ * Dispatch the detached updater runner after proving that this is an
+ * npm-global install and that its durable outcome log is writable. The runner
+ * owns the single-flight lock and emits the only terminal SUCCESS/FAILED line.
  *
  * @param {string} version - Target version to install
- * @param {boolean} deprecationOverride - Whether this is a security-override install
  * @param {object|null} installChannelMod - Preloaded dist/core/install-channel.js module
- * @returns {{ state: 'spawned'|'in-progress'|'channel'|'failed' }}
+ * @returns {Promise<{ state: 'dispatched'|'channel'|'failed' }>}
  */
-export function spawnAutoUpdate(version, deprecationOverride, installChannelMod) {
-  let lock = null;
+export async function spawnAutoUpdate(version, installChannelMod) {
+  let fd = -1;
   try {
     const pluginRoot = resolvePluginRoot(import.meta.url);
     let channel = 'unknown';
@@ -914,42 +860,76 @@ export function spawnAutoUpdate(version, deprecationOverride, installChannelMod)
       } catch { /* best-effort */ }
     }
     if (channel !== 'npm-global') {
-      logAutoUpdate(
-        `auto-update SKIPPED: install channel '${channel}' does not support self-update via npm install -g`
-      );
+      const line = `auto-update SKIPPED: install channel '${channel}' does not support self-update via npm install -g`;
+      if (!logAutoUpdate(line)) {
+        try { process.stderr.write(`[memesh] ${line}\n`); } catch { /* stderr unavailable */ }
+      }
       return { state: 'channel' };
     }
-    lock = tryAcquireAutoUpdateLock(version);
-    if (!lock.acquired) {
-      logAutoUpdate(
-        `auto-update SKIPPED: another session already holds ${lock.lockPath ?? 'auto-update.lock'} for this upgrade`
-      );
-      return { state: 'in-progress' };
-    }
-    const dir = getMemeshDirFromDbPath();
+
+    const dir = memeshDir();
     ensurePrivateDir(dir);
     const logPath = join(dir, 'auto-update.log');
-    let fd = -1;
-    try { fd = openSync(logPath, 'a', 0o600); } catch { fd = -1; }
-    const stdio = fd >= 0 ? ['ignore', fd, fd] : 'ignore';
+    const lockPath = join(dir, 'auto-update.lock');
+    const runnerPath = join(pluginRoot, 'scripts', 'hooks', 'auto-update-runner.mjs');
+    if (!existsSync(runnerPath)) {
+      const line = `auto-update FAILED: runner missing at ${runnerPath}`;
+      if (!logAutoUpdate(line)) {
+        try { process.stderr.write(`[memesh] ${line}\n`); } catch { /* stderr unavailable */ }
+      }
+      return { state: 'failed' };
+    }
+
+    try {
+      fd = openSync(logPath, 'a', 0o600);
+      try { chmodSync(logPath, 0o600); } catch { /* non-POSIX */ }
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[memesh] auto-update FAILED: durable log unavailable at ${logPath} (${err?.message ?? err})\n`,
+        );
+      } catch { /* stderr unavailable */ }
+      return { state: 'failed' };
+    }
+
     const child = spawn(
-      'npm',
-      ['install', '-g', `@pcircle/memesh@${version}`],
-      // windowsHide avoids a flashing console window on Windows; harmless on POSIX.
-      { detached: true, stdio, env: process.env, windowsHide: true },
+      process.execPath,
+      [runnerPath, version, lockPath],
+      { detached: true, stdio: ['ignore', fd, fd], env: process.env, windowsHide: true },
     );
-    child.unref();
+
+    return await new Promise((resolve) => {
+      let settled = false;
+      const finish = (state, line) => {
+        if (settled) return;
+        settled = true;
+        if (fd >= 0) {
+          try { closeSync(fd); } catch { /* already closed */ }
+          fd = -1;
+        }
+        if (!logAutoUpdate(line)) {
+          try { process.stderr.write(`[memesh] ${line}\n`); } catch { /* stderr unavailable */ }
+        }
+        resolve({ state });
+      };
+      child.once('spawn', () => {
+        child.unref();
+        finish(
+          'dispatched',
+          `auto-update DISPATCHED: target=${version} worker_pid=${child.pid ?? 'unknown'} lock=${lockPath}`,
+        );
+      });
+      child.once('error', (err) => {
+        finish('failed', `auto-update FAILED: target=${version} stage=dispatch error=${err?.message ?? err}`);
+      });
+    });
+  } catch (err) {
     if (fd >= 0) {
-      try { closeSync(fd); } catch { /* ignore */ }
+      try { closeSync(fd); } catch { /* already closed */ }
     }
-    logAutoUpdate(
-      `auto-update spawn: target=${version}${deprecationOverride ? ' (deprecation-override)' : ''} pid=${child.pid ?? 'unknown'} lock=${lock.lockPath}`
-    );
-    return { state: 'spawned' };
-  } catch (err) {
-    logAutoUpdate(`auto-update spawn FAILED: ${err?.message ?? err}`);
-    if (lock?.acquired && lock.lockPath) {
-      try { require('fs').unlinkSync(lock.lockPath); } catch { /* best-effort */ }
+    const line = `auto-update FAILED: target=${version} stage=dispatch error=${err?.message ?? err}`;
+    if (!logAutoUpdate(line)) {
+      try { process.stderr.write(`[memesh] ${line}\n`); } catch { /* stderr unavailable */ }
     }
     return { state: 'failed' };
   }