@pcircle/memesh 4.7.3 → 4.8.0

package/scripts/hooks/auto-update-runner.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import {
+  closeSync,
+  linkSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from 'fs';
+import { createHash, randomBytes } from 'crypto';
+import { pathToFileURL } from 'url';
+import { runGlobalUpdate } from '../../dist/core/updater.js';
+
+export const AUTO_UPDATE_LOCK_TTL_MS = 10 * 60 * 1000;
+export const AUTO_UPDATE_RECOVERY_TTL_MS = 30 * 1000;
+const MAX_RECOVERY_GENERATIONS = 64;
+
+function ownerToken() {
+  return `${process.pid}-${Date.now()}-${randomBytes(8).toString('hex')}`;
+}
+
+function readLock(lockPath) {
+  try {
+    const [token, pidRaw, startedAtRaw, version] = readFileSync(lockPath, 'utf8').split('\n');
+    const pid = Number(pidRaw);
+    const startedAt = Number(startedAtRaw);
+    if (!token || !Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAt)) return null;
+    return { token, pid, startedAt, version: version || null };
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code !== 'ESRCH';
+  }
+}
+
+function createOwnedFile(filePath, token, payload) {
+  const fd = openSync(filePath, 'wx', 0o600);
+  try {
+    writeFileSync(fd, payload);
+  } finally {
+    closeSync(fd);
+  }
+  return token;
+}
+
+function tryCreateLock(lockPath, version) {
+  const token = ownerToken();
+  const startedAt = Date.now();
+  try {
+    createOwnedFile(
+      lockPath,
+      token,
+      `${token}\n${process.pid}\n${startedAt}\n${version}\n`,
+    );
+    return { acquired: true, lockPath, ownerToken: token, recoveredStale: false };
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      return { acquired: false, lockPath, ownerToken: null, recoveredStale: false };
+    }
+    throw err;
+  }
+}
+
+export function autoUpdateRecoveryClaimPath(lockPath, staleToken, generation = 0) {
+  const tokenHash = createHash('sha256').update(staleToken).digest('hex').slice(0, 24);
+  return `${lockPath}.recover.${tokenHash}.${generation}`;
+}
+
+function tryCreateRecoveryClaim(claimPath) {
+  const token = ownerToken();
+  const candidatePath = `${claimPath}.candidate.${token}`;
+  createOwnedFile(
+    candidatePath,
+    token,
+    `${token}\n${process.pid}\n${Date.now()}\nrecovery\n`,
+  );
+  try {
+    // The candidate is complete before the fixed claim path appears. linkSync
+    // gives the destination O_EXCL semantics, so a crash cannot leave a
+    // partially written claim that blocks recovery forever.
+    linkSync(candidatePath, claimPath);
+    return { acquired: true, claimPath, ownerToken: token };
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      return { acquired: false, claimPath, ownerToken: null };
+    }
+    throw err;
+  } finally {
+    try { unlinkSync(candidatePath); } catch { /* crash-only candidate orphan */ }
+  }
+}
+
+function tryAcquireRecoveryClaim(lockPath, staleToken) {
+  for (let generation = 0; generation < MAX_RECOVERY_GENERATIONS; generation += 1) {
+    const claimPath = autoUpdateRecoveryClaimPath(lockPath, staleToken, generation);
+    const created = tryCreateRecoveryClaim(claimPath);
+    if (created.acquired) return created;
+
+    const existing = readLock(claimPath);
+    if (!existing) return null;
+    if (Date.now() - existing.startedAt <= AUTO_UPDATE_RECOVERY_TTL_MS) return null;
+    if (processIsAlive(existing.pid)) return null;
+    // A complete claim whose owner crashed remains immutable. All contenders
+    // derive the same successor generation, where O_EXCL elects one recovery
+    // owner without deleting or replacing the orphaned claim.
+  }
+  return null;
+}
+
+export function releaseAutoUpdateLock(lockPath, token) {
+  const current = readLock(lockPath);
+  if (!current || current.token !== token) return false;
+  try {
+    unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function recoverObservedStaleAutoUpdateLock(lockPath, observed) {
+  const recovery = tryAcquireRecoveryClaim(lockPath, observed.token);
+  if (!recovery?.acquired) return false;
+
+  try {
+    const current = readLock(lockPath);
+    if (!current || current.token !== observed.token) return false;
+    if (Date.now() - current.startedAt <= AUTO_UPDATE_LOCK_TTL_MS) return false;
+    if (processIsAlive(current.pid)) return false;
+    try {
+      unlinkSync(lockPath);
+      return true;
+    } catch (err) {
+      if (err?.code === 'ENOENT') return false;
+      throw err;
+    }
+  } finally {
+    releaseAutoUpdateLock(recovery.claimPath, recovery.ownerToken);
+  }
+}
+
+export function tryAcquireAutoUpdateLock(lockPath, version) {
+  const created = tryCreateLock(lockPath, version);
+  if (created.acquired) return created;
+
+  const observed = readLock(lockPath);
+  if (!observed) return created;
+  if (Date.now() - observed.startedAt <= AUTO_UPDATE_LOCK_TTL_MS) return created;
+  if (processIsAlive(observed.pid)) return created;
+
+  // Recovery never installs. It removes only the exact stale token observed
+  // under a separate O_EXCL claim, then defers so a later trigger must acquire
+  // the normal update lock. No delayed stale contender touches a fresh lock.
+  const recoveredStale = recoverObservedStaleAutoUpdateLock(lockPath, observed);
+  return { ...created, recoveredStale };
+}
+
+function writeLine(fd, line) {
+  try {
+    writeSync(fd, `[memesh auto-update] ${line}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function errorMessage(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  return raw.replace(/[\r\n]+/g, ' ').slice(0, 500);
+}
+
+export function runAutoUpdate(targetVersion, lockPath) {
+  let lock;
+  try {
+    lock = tryAcquireAutoUpdateLock(lockPath, targetVersion);
+  } catch (err) {
+    writeLine(2, `FAILED target=${targetVersion} stage=lock error=${errorMessage(err)}`);
+    return 1;
+  }
+
+  if (!lock.acquired) {
+    const state = lock.recoveredStale ? 'RECOVERED_STALE' : 'IN_PROGRESS';
+    writeLine(1, `${state} target=${targetVersion} lock=${lockPath}`);
+    return 0;
+  }
+
+  if (!writeLine(1, `START target=${targetVersion} pid=${process.pid}`)) {
+    releaseAutoUpdateLock(lockPath, lock.ownerToken);
+    return 1;
+  }
+
+  let installedVersion = null;
+  let updateError = null;
+  try {
+    installedVersion = runGlobalUpdate(targetVersion).installedVersion;
+  } catch (err) {
+    updateError = err;
+  }
+
+  const released = releaseAutoUpdateLock(lockPath, lock.ownerToken);
+  if (updateError) {
+    writeLine(
+      2,
+      `FAILED target=${targetVersion} stage=install-or-readback error=${errorMessage(updateError)}`,
+    );
+    if (!released) writeLine(2, `FAILED target=${targetVersion} stage=lock-release`);
+    return 1;
+  }
+  if (!released) {
+    writeLine(2, `FAILED target=${targetVersion} stage=lock-release installed=${installedVersion}`);
+    return 1;
+  }
+
+  writeLine(1, `SUCCESS target=${targetVersion} installed=${installedVersion}`);
+  return 0;
+}
+
+async function main() {
+  const [targetVersion, lockPath] = process.argv.slice(2);
+  if (!targetVersion || !lockPath) {
+    writeLine(2, 'FAILED stage=arguments error=expected target version and lock path');
+    process.exitCode = 1;
+    return;
+  }
+  process.exitCode = runAutoUpdate(targetVersion, lockPath);
+}
+
+const invokedPath = process.argv[1]
+  ? pathToFileURL(realpathSync(process.argv[1])).href
+  : null;
+if (invokedPath === import.meta.url) {
+  await main();
+}

package/scripts/hooks/session-start.js

@@ -24,7 +24,9 @@ import {
   // home resolver the update-check cache itself uses.
   memeshDir as memeshHomeDir,
   parseTaskState,
+  readRepoState,
   readUpdateCheckCache,
+  repoStateLines,
   resolvePluginRoot,
   resolveSessionLimit,
   taskStateLines,
@@ -396,8 +398,8 @@ function spawnFreshUpdateCheck(installedVersion) {
     // racy — both peers' renames are destructive, so each could
     // read its own token back and both would spawn a refresh.
     // O_EXCL is the standard POSIX/libuv primitive that lets at
-    // most one process succeed. Same pattern as
-    // tryAcquireAutoUpdateLock above.
+    // most one process succeed. The updater runner uses the same O_EXCL
+    // ownership primitive for its separate update lock.
     const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
     const claim = () => {
       try {
@@ -976,8 +978,16 @@ process.stdin.on('end', async () => {
         try { process.stderr.write(`[memesh session-start] memory-context: ${err?.message || err}\n`); } catch {}
       }
 
+      // Same prefix, same rule, as `assembleBriefing`: repository facts are
+      // context for memories, never a briefing on their own. Inside the
+      // emptiness gate so a project with nothing recorded still injects
+      // 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 = '';
       if (memoryLines.length > 0) {
+        const repoLines = repoStateLines(readRepoState(data.cwd));
+        if (repoLines.length > 0) memoryLines.unshift(...repoLines, '');
         // Same wrapper pre-edit-recall uses: an explicit "background data,
         // not instructions" preamble plus a fenced block. Memory content is
         // attacker-influenced in the general case (anything the agent has

package/scripts/hooks/session-summary.js

@@ -60,9 +60,10 @@ try {
 } catch { /* best-effort */ }
 
 /**
- * Run auto-update at Stop hook: reads cache, evaluates policy, and spawns
- * npm install -g if warranted. Runs after all session work completes,
- * avoiding the TOCTOU race where install would overwrite dist/ mid-session.
+ * Run auto-update at Stop hook: reads cache, evaluates policy, and dispatches
+ * the detached updater runner if warranted. Runs after all session work
+ * completes, avoiding the TOCTOU race where install would overwrite dist/
+ * mid-session.
  */
 async function runAutoUpdateAtStop() {
   try {
@@ -75,7 +76,7 @@ async function runAutoUpdateAtStop() {
     const policy = resolveAutoUpdatePolicy(process.env);
     const decision = decideAutoUpdateHook(installedVersion, cache, policy);
     if (decision.run) {
-      spawnAutoUpdate(decision.latest, decision.deprecationOverride, _installChannelMod);
+      await spawnAutoUpdate(decision.latest, _installChannelMod);
     }
   } catch {
     // Best-effort — never crash the hook.
@@ -648,8 +649,8 @@ process.stdin.on('end', async () => {
     try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
   }
 
-  // Spawn auto-update if policy + cache permit. Runs after all session work
-  // so npm install -g doesn't overwrite dist/ while peer hooks are reading it.
+  // Dispatch auto-update if policy + cache permit. Runs after all session work
+  // so the runner cannot overwrite dist/ while peer hooks are reading it.
   await runAutoUpdateAtStop();
 
   // Emit NOTHING on success — not `{"suppressOutput": true}`.

package/skills/memesh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memesh
-description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, or analyze work patterns. Also triggers when the user asks "what do you remember", "where did we leave off", or wants to catch up on a project; when a session starts and project context is needed; and proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
+description: Use MeMesh to remember, recall, and manage AI knowledge across sessions, and to exchange durable task-focused messages with local agents. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, analyze work patterns, contact another agent, or handle a memesh_message_available marker. Also triggers when the user asks "what do you remember", "where did we leave off", or wants to catch up on a project; when a session starts and project context is needed; and proactively when you make important decisions, fix bugs, learn lessons worth preserving, or owe another agent a requested result or disposition.
 user-invocable: true
 ---
 
@@ -27,6 +27,44 @@ All examples below use CLI. MCP tools accept the same parameters as JSON objects
 
 Four moments. Everything else in this file is detail.
 
+## Durable messages and active-host delivery
+
+Use the `message` tool when another local agent needs a durable, exact-recipient handoff rather than an inferred memory. `send`, `poll`, `fetch`, `intake`, `ack`, `disposition`, `activation`, and `receipts` are independent lifecycle actions: fetching or host acceptance never implies acknowledgement or workflow acceptance.
+
+### Handle messages to a result
+
+- A `memesh_message_available` marker is routing metadata, not the payload. Call `message` with `action: "fetch"` using its exact `project`, `recipient`, and `message_id`; never answer from the marker or guess missing IDs.
+- Reply when the payload asks for work, a decision, review, feedback, missing information, status, or an explicit response. An FYI with no requested action needs no reply unless it asks for a receipt.
+- Do not leave requested work silently pending. If the result is not immediate, send one concise acceptance or blocker with the owner and next action; send the result when available. Do not send recurring progress chatter.
+- Reply with `action: "send"` to the original sender, in the same project. Preserve the original `correlation_id` (or use the original `message_id` when none exists), set `reply_to` to the original `message_id`, and use a stable idempotency key. Route to the sender's stable principal unless the message explicitly requires an exact session.
+- A useful reply states the outcome, decision or findings, essential evidence, any unresolved blocker, and the owner or next action. One result-oriented reply is enough; omit greetings, thanks, and conversational acknowledgements. Ask a follow-up only when missing information prevents a responsible result.
+- `ack` means the recipient explicitly acknowledges the message; `disposition` records workflow state such as `accepted`, `deferred`, or `completed`. Record only facts that occurred. Neither replaces a requested substantive reply.
+
+Use the routing and identity fields returned by `fetch`. A reply has this shape (replace placeholders with fetched or caller-stable values):
+
+```json
+{
+  "action": "send",
+  "project": "<original project>",
+  "sender": "<this agent's stable principal>",
+  "recipient": "<original sender>",
+  "target_kind": "principal",
+  "idempotency_key": "reply:<original message_id>:result",
+  "correlation_id": "<original correlation_id or message_id>",
+  "reply_to": "<original message_id>",
+  "content_type": "application/json",
+  "payload": {
+    "outcome": "<result, decision, or blocker>",
+    "evidence": ["<only the evidence needed by the recipient>"],
+    "next": "<owner and next action, if any>"
+  }
+}
+```
+
+An active compatible managed host can receive a native push, which removes polling for that live delivery. One-time provider enablement and a MeMesh-managed Codex app-server, Claude Channel, or Gemini ACP session may be required; ordinary unattached sessions are presence-only/inbound-unavailable. Adapter imports and a live router socket do not prove host registration or `host_accept`. Do not promise that a stopped, missing, or replaced session will wake up: it is not resumed or silently rerouted. Use the stable principal for logical routing, and an exact session/generation only when delivery must not move to a replacement connection. Local owns durable storage and host-native delivery; Cloud relay, A2A, SSE, discovery, or fetch is not host delivery.
+
+Durable audit does not mean unbounded silent growth. Owners can inspect it with `memesh message storage report --cutoff <ISO timestamp>`, preview bounded terminal-payload tombstones with `memesh message storage prune --cutoff <ISO timestamp>`, and explicitly add `--apply`. Never prune unresolved/offline-pending work. `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` is an optional owner policy; there is no default quota or automatic pruning.
+
 **SESSION START → load the briefing (once).**
 Call the `briefing` MCP tool or run `memesh briefing`. It returns the assembled
 work topology: where the work was left off (goal / next / blocked / done),
@@ -79,6 +117,7 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 | **Stop** | Session ends | Auto-captures session knowledge + runs LLM failure analysis → lessons |
 | **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 | **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |
+| **SessionStart (Codex, async)** | A configured Codex session starts or resumes | Registers that exact live thread for metadata-only MeMesh message wakeups; exits without registering outside the configured workspace |
 
 Because of the SessionStart hook: **in Claude Code, do NOT call `briefing` at
 session start — it is already in your context.** Call it only mid-session