slashvibe-mcp 0.8.13 → 0.8.15

package/README.md

@@ -18,6 +18,23 @@ GitHub to sign you in, and your GitHub username becomes your @handle. About 30 s
 Invited by someone? After setup, say `vibe inbox` — their message is waiting. Reply and
 you're done; that's the whole onboarding.
 
+## Put waiting messages at the top of your next Claude session
+
+For the small, opt-in Gate 1 pilot, install the read-only Claude Code `SessionStart` hook:
+
+```bash
+npx slashvibe-mcp hook install
+```
+
+The hook checks the ordinary inbox when Claude starts or resumes. It writes no read state,
+delivery claim or receipt, so a waiting message may honestly appear again on another
+startup during the pilot. Check or reverse the installation at any time:
+
+```bash
+npx slashvibe-mcp hook status
+npx slashvibe-mcp hook uninstall
+```
+
 ## Manual setup
 
 If you'd rather wire it yourself, add to `~/.claude.json` (or your host's MCP config):
@@ -43,8 +60,8 @@ Then run `vibe init` in your session to sign in.
 The default surface is deliberately small — 10 tools:
 
 - **who** — who's here now (🟢), who's idle, which agents are around
-- **dm / inbox / reply** — messages that survive restarts on both sides. A reply finds
-  your current session, or the top of your next one, exactly once
+- **dm / inbox / reply** — messages that survive restarts on both sides. The optional
+  read-only Claude hook can put a waiting reply at the top of your next session
 - **status** — what you're working on, in words (`shipping`, `debugging`)
 - **help**, plus setup plumbing (`init`, `token`, `bye`, `email`)
 

package/actor-session.js

@@ -0,0 +1,475 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const ACTOR_BUNDLE_VERSION = 1;
+const ACTOR_SESSION_FILE = 'actor-session.json';
+const ACTOR_LOCK_DIRECTORY = '.actor-session.lock';
+const ACTOR_LOCK_OWNER = 'owner.json';
+const REFRESH_TOKEN_PATTERN = /^vrt_[A-Za-z0-9_-]{43}$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DEFAULT_LOCK_WAIT_MS = 5000;
+const DEFAULT_LOCK_STALE_MS = 15000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+const DEFAULT_MINIMUM_TTL_SECONDS = 30;
+
+class ActorSessionError extends Error {
+  constructor(code, options = {}) {
+    super(options.message || code);
+    this.name = 'ActorSessionError';
+    this.code = code;
+    this.reason = options.reason || null;
+    this.reauthenticate = options.reauthenticate === true;
+    this.ambiguous = options.ambiguous === true;
+    if (options.cause) this.cause = options.cause;
+  }
+}
+
+function actorPaths(env = process.env) {
+  const home = env.HOME || os.homedir();
+  const configured = env.VIBE_HOME
+    ? String(env.VIBE_HOME).replace(/^~(?=$|\/)/, home)
+    : path.join(home, '.vibe');
+  const directory = path.resolve(configured);
+  return {
+    directory,
+    sessionFile: path.join(directory, ACTOR_SESSION_FILE),
+    lockDirectory: path.join(directory, ACTOR_LOCK_DIRECTORY),
+    lockOwner: path.join(directory, ACTOR_LOCK_DIRECTORY, ACTOR_LOCK_OWNER),
+  };
+}
+
+function parseAccessToken(token) {
+  try {
+    const parts = String(token || '').split('.');
+    if (parts.length !== 3 || parts.some((part) => !part)) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    if (
+      typeof payload.sub !== 'string' ||
+      !UUID_PATTERN.test(payload.sub) ||
+      typeof payload.sid !== 'string' ||
+      !UUID_PATTERN.test(payload.sid) ||
+      typeof payload.exp !== 'number' ||
+      !Number.isFinite(payload.exp)
+    ) {
+      return null;
+    }
+    return {
+      principalId: payload.sub,
+      runtimeId: payload.sid,
+      expiresAt: payload.exp,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function normalizedBundle(input, timestamp) {
+  if (!input || typeof input !== 'object') return null;
+  const refreshToken = input.refreshToken;
+  const principalId = input.principalId;
+  const runtimeId = input.runtimeId;
+  const handleVersion = input.handleVersion;
+  if (
+    typeof refreshToken !== 'string' ||
+    !REFRESH_TOKEN_PATTERN.test(refreshToken) ||
+    typeof principalId !== 'string' ||
+    !UUID_PATTERN.test(principalId) ||
+    typeof runtimeId !== 'string' ||
+    !UUID_PATTERN.test(runtimeId) ||
+    typeof handleVersion !== 'string' ||
+    !UUID_PATTERN.test(handleVersion)
+  ) {
+    return null;
+  }
+  return {
+    version: ACTOR_BUNDLE_VERSION,
+    refreshToken,
+    principalId,
+    runtimeId,
+    handleVersion,
+    updatedAt: new Date(timestamp).toISOString(),
+  };
+}
+
+function createActorSessionManager(options = {}) {
+  const env = options.env || process.env;
+  const paths = options.paths || actorPaths(env);
+  const fileSystem = options.fs || fs;
+  const now = options.now || (() => Date.now());
+  const randomId = options.randomUUID || crypto.randomUUID;
+  const wait =
+    options.wait || ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const fetchImpl = options.fetch || globalThis.fetch;
+  const apiUrl = String(options.apiUrl || env.VIBE_API_URL || 'https://www.slashvibe.dev').replace(
+    /\/$/,
+    ''
+  );
+  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+  const lockStaleMs = options.lockStaleMs ?? DEFAULT_LOCK_STALE_MS;
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  let accessCache = null;
+  let refreshInFlight = null;
+
+  function ensureDirectory() {
+    fileSystem.mkdirSync(paths.directory, { recursive: true, mode: 0o700 });
+    fileSystem.chmodSync(paths.directory, 0o700);
+  }
+
+  function atomicWriteBundle(bundle) {
+    ensureDirectory();
+    const temporary = path.join(
+      paths.directory,
+      `.${ACTOR_SESSION_FILE}.${process.pid}.${randomId()}.tmp`
+    );
+    let descriptor = null;
+    try {
+      descriptor = fileSystem.openSync(temporary, 'wx', 0o600);
+      fileSystem.writeFileSync(descriptor, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+      fileSystem.fsyncSync(descriptor);
+      fileSystem.closeSync(descriptor);
+      descriptor = null;
+      fileSystem.chmodSync(temporary, 0o600);
+      fileSystem.renameSync(temporary, paths.sessionFile);
+      fileSystem.chmodSync(paths.sessionFile, 0o600);
+    } catch (error) {
+      if (descriptor !== null) {
+        try {
+          fileSystem.closeSync(descriptor);
+        } catch {}
+      }
+      try {
+        fileSystem.unlinkSync(temporary);
+      } catch {}
+      throw error;
+    }
+  }
+
+  function clearUnsafe() {
+    accessCache = null;
+    try {
+      fileSystem.unlinkSync(paths.sessionFile);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+
+  function readBundle() {
+    let parsed;
+    try {
+      parsed = JSON.parse(fileSystem.readFileSync(paths.sessionFile, 'utf8'));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      clearUnsafe();
+      throw new ActorSessionError('actor_reauthentication_required', {
+        reason: 'actor_bundle_invalid',
+        reauthenticate: true,
+        cause: error,
+      });
+    }
+    const bundle = normalizedBundle(parsed, now());
+    if (!bundle || parsed.version !== ACTOR_BUNDLE_VERSION) {
+      clearUnsafe();
+      throw new ActorSessionError('actor_reauthentication_required', {
+        reason: 'actor_bundle_invalid',
+        reauthenticate: true,
+      });
+    }
+    bundle.updatedAt = parsed.updatedAt;
+    return bundle;
+  }
+
+  function processIsAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error?.code === 'EPERM';
+    }
+  }
+
+  function removeStaleLock() {
+    let owner = null;
+    let age = 0;
+    try {
+      owner = JSON.parse(fileSystem.readFileSync(paths.lockOwner, 'utf8'));
+    } catch {}
+    try {
+      age = now() - fileSystem.statSync(paths.lockDirectory).mtimeMs;
+    } catch {
+      return false;
+    }
+    if (age <= lockStaleMs || (owner?.pid && processIsAlive(Number(owner.pid)))) return false;
+    try {
+      fileSystem.unlinkSync(paths.lockOwner);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return false;
+    }
+    try {
+      fileSystem.rmdirSync(paths.lockDirectory);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function acquireLock() {
+    ensureDirectory();
+    const deadline = now() + lockWaitMs;
+    const nonce = randomId();
+    for (;;) {
+      let madeLockDirectory = false;
+      try {
+        fileSystem.mkdirSync(paths.lockDirectory, { mode: 0o700 });
+        madeLockDirectory = true;
+        fileSystem.writeFileSync(
+          paths.lockOwner,
+          `${JSON.stringify({ pid: process.pid, nonce, acquiredAt: new Date(now()).toISOString() })}\n`,
+          { encoding: 'utf8', flag: 'wx', mode: 0o600 }
+        );
+        return { nonce };
+      } catch (error) {
+        if (madeLockDirectory) {
+          try {
+            fileSystem.unlinkSync(paths.lockOwner);
+          } catch {}
+          try {
+            fileSystem.rmdirSync(paths.lockDirectory);
+          } catch {}
+        }
+        if (error?.code !== 'EEXIST') throw error;
+        if (removeStaleLock()) continue;
+        if (now() >= deadline) {
+          throw new ActorSessionError('actor_refresh_busy', { reason: 'lock_timeout' });
+        }
+        await wait(25);
+      }
+    }
+  }
+
+  function releaseLock(lock) {
+    let owner = null;
+    try {
+      owner = JSON.parse(fileSystem.readFileSync(paths.lockOwner, 'utf8'));
+    } catch {}
+    if (owner?.nonce !== lock.nonce) return;
+    try {
+      fileSystem.unlinkSync(paths.lockOwner);
+    } catch {}
+    try {
+      fileSystem.rmdirSync(paths.lockDirectory);
+    } catch {}
+  }
+
+  async function withLock(operation) {
+    const lock = await acquireLock();
+    try {
+      return await operation();
+    } finally {
+      releaseLock(lock);
+    }
+  }
+
+  function cacheAccessToken(token, bundle) {
+    const claims = parseAccessToken(token);
+    if (
+      !claims ||
+      claims.principalId !== bundle.principalId ||
+      claims.runtimeId !== bundle.runtimeId ||
+      claims.expiresAt * 1000 <= now()
+    ) {
+      throw new ActorSessionError('actor_access_token_invalid', {
+        reason: 'access_binding_invalid',
+      });
+    }
+    accessCache = { token, ...claims };
+    return token;
+  }
+
+  function reauthenticationError(reason, options = {}) {
+    return new ActorSessionError('actor_reauthentication_required', {
+      reason,
+      reauthenticate: true,
+      ambiguous: options.ambiguous === true,
+      cause: options.cause,
+    });
+  }
+
+  async function rotate(bundle) {
+    if (typeof fetchImpl !== 'function') {
+      throw new ActorSessionError('actor_refresh_unavailable', { reason: 'fetch_unavailable' });
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(`${apiUrl}/api/auth/token`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Cache-Control': 'no-store',
+        },
+        body: JSON.stringify({
+          grant_type: 'refresh_token',
+          refresh_token: bundle.refreshToken,
+        }),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      clearUnsafe();
+      throw reauthenticationError('refresh_ambiguous', {
+        ambiguous: true,
+        cause: error,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (!response || response.status === 401) {
+      clearUnsafe();
+      throw reauthenticationError('invalid_grant');
+    }
+    if (!response.ok) {
+      clearUnsafe();
+      throw reauthenticationError('refresh_ambiguous', { ambiguous: true });
+    }
+
+    let payload;
+    try {
+      payload = await response.json();
+    } catch (error) {
+      clearUnsafe();
+      throw reauthenticationError('refresh_ambiguous', {
+        ambiguous: true,
+        cause: error,
+      });
+    }
+
+    const nextBundle = normalizedBundle(
+      {
+        refreshToken: payload?.refresh_token,
+        principalId: payload?.principal_id,
+        runtimeId: payload?.runtime_id,
+        handleVersion: payload?.handle_version,
+      },
+      now()
+    );
+    if (
+      !nextBundle ||
+      payload?.token_type !== 'Bearer' ||
+      typeof payload?.access_token !== 'string' ||
+      nextBundle.principalId !== bundle.principalId ||
+      nextBundle.runtimeId !== bundle.runtimeId
+    ) {
+      clearUnsafe();
+      throw reauthenticationError('refresh_response_invalid', { ambiguous: true });
+    }
+
+    try {
+      cacheAccessToken(payload.access_token, nextBundle);
+      atomicWriteBundle(nextBundle);
+    } catch (error) {
+      clearUnsafe();
+      if (error instanceof ActorSessionError && error.reauthenticate) throw error;
+      throw reauthenticationError('refresh_persistence_failed', {
+        ambiguous: true,
+        cause: error,
+      });
+    }
+    return accessCache.token;
+  }
+
+  async function installOAuthSession(session) {
+    return withLock(async () => {
+      const bundle = normalizedBundle(session, now());
+      if (!bundle || typeof session?.accessToken !== 'string') {
+        throw new ActorSessionError('actor_oauth_bundle_invalid');
+      }
+      try {
+        cacheAccessToken(session.accessToken, bundle);
+        atomicWriteBundle(bundle);
+      } catch (error) {
+        clearUnsafe();
+        if (error instanceof ActorSessionError) throw error;
+        throw new ActorSessionError('actor_oauth_persistence_failed', { cause: error });
+      }
+      return {
+        principalId: bundle.principalId,
+        runtimeId: bundle.runtimeId,
+        handleVersion: bundle.handleVersion,
+      };
+    });
+  }
+
+  async function refreshAccessToken(minimumTtlSeconds = DEFAULT_MINIMUM_TTL_SECONDS) {
+    if (refreshInFlight) return refreshInFlight;
+    refreshInFlight = withLock(async () => {
+      const bundle = readBundle();
+      if (!bundle) return null;
+      if (
+        accessCache &&
+        accessCache.principalId === bundle.principalId &&
+        accessCache.runtimeId === bundle.runtimeId &&
+        accessCache.expiresAt * 1000 > now() + minimumTtlSeconds * 1000
+      ) {
+        return accessCache.token;
+      }
+      return rotate(bundle);
+    }).finally(() => {
+      refreshInFlight = null;
+    });
+    return refreshInFlight;
+  }
+
+  async function getAccessToken(optionsForCall = {}) {
+    const minimumTtlSeconds = optionsForCall.minimumTtlSeconds ?? DEFAULT_MINIMUM_TTL_SECONDS;
+    if (accessCache) {
+      // The durable bundle is also the cross-process stop signal. Another process
+      // may have cleared it after an ambiguous/spent refresh; returning a still-live
+      // memory token here would let this process perform a delivery transition after
+      // the family entered reauthentication. Atomic replacement makes this read safe.
+      const bundle = readBundle();
+      if (!bundle) {
+        accessCache = null;
+        return null;
+      }
+      if (
+        accessCache.principalId === bundle.principalId &&
+        accessCache.runtimeId === bundle.runtimeId &&
+        accessCache.expiresAt * 1000 > now() + minimumTtlSeconds * 1000
+      ) {
+        return accessCache.token;
+      }
+    }
+    return refreshAccessToken(minimumTtlSeconds);
+  }
+
+  async function clearActorSession() {
+    return withLock(async () => clearUnsafe());
+  }
+
+  return {
+    paths,
+    clearActorSession,
+    getAccessToken,
+    installOAuthSession,
+    readBundle,
+    refreshAccessToken,
+  };
+}
+
+const actorSession = createActorSessionManager();
+
+module.exports = {
+  ACTOR_BUNDLE_VERSION,
+  ActorSessionError,
+  actorPaths,
+  createActorSessionManager,
+  getAccessToken: actorSession.getAccessToken,
+  installOAuthSession: actorSession.installOAuthSession,
+  clearActorSession: actorSession.clearActorSession,
+};

package/cli.js

@@ -14,7 +14,18 @@
 
 const args = process.argv.slice(2);
 
-if (args.includes('setup')) {
+if (args[0] === 'hook') {
+  require('./hook-cli')
+    .run(args.slice(1))
+    .catch((error) => {
+      if (args[1] === 'run') {
+        process.stdout.write(JSON.stringify({ suppressOutput: true }));
+      } else {
+        process.stderr.write(`${error?.message || error}\n`);
+        process.exitCode = 1;
+      }
+    });
+} else if (args.includes('setup')) {
   require('./setup.js');
 } else if (process.stdin.isTTY) {
   // Running from terminal (not as MCP server)

package/hook-cli.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { createHookSettingsManager, HookSettingsError } = require('./session-start-hook-settings');
+
+function printStatus(result) {
+  if (result.installed) {
+    process.stdout.write(
+      `/vibe read-only SessionStart resurfacing is installed.\n${result.path}\n`
+    );
+  } else {
+    process.stdout.write(
+      `/vibe read-only SessionStart resurfacing is not installed.\n${result.path}\n`
+    );
+  }
+}
+
+async function run(args = []) {
+  const action = args[0];
+  if (action === 'run') {
+    const hook = require('./session-start-hook.cjs');
+    await hook.main();
+    return;
+  }
+
+  const manager = createHookSettingsManager();
+  if (action === 'install') {
+    const result = manager.install();
+    process.stdout.write(
+      result.changed
+        ? `/vibe read-only SessionStart resurfacing installed. Restart Claude Code, then use /hooks to verify it.\n`
+        : `/vibe read-only SessionStart resurfacing was already installed.\n`
+    );
+    return;
+  }
+  if (action === 'uninstall') {
+    const result = manager.uninstall();
+    process.stdout.write(
+      result.changed
+        ? `/vibe read-only SessionStart resurfacing removed.\n`
+        : `/vibe read-only SessionStart resurfacing was not installed.\n`
+    );
+    return;
+  }
+  if (action === 'status') {
+    printStatus(manager.status());
+    return;
+  }
+
+  throw new HookSettingsError('hook_command_invalid', {
+    message: 'Usage: npx slashvibe-mcp hook <install|status|uninstall>',
+  });
+}
+
+module.exports = { run };

package/index.js

@@ -16,6 +16,7 @@ const store = require('./store');
 const prompts = require('./prompts');
 const NotificationEmitter = require('./notification-emitter');
 const authStore = require('./auth-store');
+const actorSession = require('./actor-session');
 const { apiHeaders } = require('./api-auth');
 const presenceBoard = require('./resources/presence-board');
 const { resolveFooter } = require('./footer');
@@ -380,6 +381,20 @@ class VibeMCPServer {
     // Hydrate auth state from disk FIRST (before any tools need it)
     authStore.hydrate();
 
+    // An access token is memory/cache; only the rotating refresh bundle survives a
+    // process. Refresh once at startup so a dead/reused family becomes one truthful
+    // reauthentication state before any future delivery transition can use it.
+    this.actorAccessReady = actorSession.getAccessToken().catch((error) => {
+      if (error?.reauthenticate) {
+        process.stderr.write(
+          '/vibe: terminal delivery sign-in needs renewal — say "vibe init"; ordinary /vibe sign-in is unchanged\n'
+        );
+      } else if (error?.code === 'actor_refresh_busy') {
+        process.stderr.write('/vibe: terminal delivery sign-in is being refreshed by another session\n');
+      }
+      return null;
+    });
+
     // Initialize notification emitter
     this.notifier = new NotificationEmitter(this);
 
@@ -599,6 +614,9 @@ class VibeMCPServer {
             });
           }
 
+          // The HTTP store creates one random key per logical send and preserves it
+          // across its internal transport retries. JSON-RPC ids restart every MCP
+          // process, so deriving a durable key from `id` would collapse future sends.
           const result = await tool.handler(args);
 
           // Emit list_changed notification for state-changing tools

package/oauth-callback.js

@@ -8,6 +8,9 @@ const DEFAULT_CALLBACK_PORT = 9876;
 const DEFAULT_TIMEOUT_MS = 300000;
 const DEFAULT_GRACE_MS = 300000;
 const LOGIN_URL = 'https://www.slashvibe.dev/login';
+const ACTOR_BODY_LIMIT = 8192;
+const ACTOR_REFRESH_PATTERN = /^vrt_[A-Za-z0-9_-]{43}$/;
+const ACTOR_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 const SUCCESS_PAGE = `<!DOCTYPE html>
 <html lang="en">
@@ -101,6 +104,71 @@ const BAD_CALLBACK_PAGE = `<!DOCTYPE html>
 <title>sign-in could not finish · /vibe</title></head>
 <body><p>this sign-in callback could not be accepted. return to your terminal and try again.</p></body></html>`;
 
+function actorCapturePage(state) {
+  const script = `<script>
+  (() => {
+    const body = window.location.hash.slice(1) || 'actor_status=unavailable';
+    window.history.replaceState(null, '', window.location.pathname);
+    fetch('/actor-callback?state=' + encodeURIComponent(${JSON.stringify(state)}), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      cache: 'no-store',
+      credentials: 'omit',
+      body
+    }).catch(() => {});
+  })();
+</script>`;
+  return SUCCESS_PAGE.replace('</body>', `${script}\n</body>`);
+}
+
+function readBody(request, limit = ACTOR_BODY_LIMIT) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    request.setEncoding('utf8');
+    request.on('data', (chunk) => {
+      body += chunk;
+      if (body.length > limit) {
+        reject(new Error('ACTOR_CALLBACK_TOO_LARGE'));
+        request.destroy();
+      }
+    });
+    request.on('end', () => resolve(body));
+    request.on('error', reject);
+  });
+}
+
+function actorSessionFromBody(body) {
+  const fields = new URLSearchParams(body);
+  if (fields.get('actor_status') === 'unavailable') {
+    const credentialFields = [
+      'actor_access_token',
+      'actor_refresh_token',
+      'principal_id',
+      'runtime_id',
+      'handle_version',
+    ];
+    return credentialFields.some((field) => fields.has(field)) ? undefined : null;
+  }
+
+  const accessToken = fields.get('actor_access_token');
+  const refreshToken = fields.get('actor_refresh_token');
+  const principalId = fields.get('principal_id');
+  const runtimeId = fields.get('runtime_id');
+  const handleVersion = fields.get('handle_version');
+  if (
+    typeof accessToken !== 'string' ||
+    accessToken.length < 16 ||
+    accessToken.length > 4096 ||
+    !ACTOR_REFRESH_PATTERN.test(refreshToken || '') ||
+    !ACTOR_UUID_PATTERN.test(principalId || '') ||
+    !ACTOR_UUID_PATTERN.test(runtimeId || '') ||
+    !ACTOR_UUID_PATTERN.test(handleVersion || '')
+  ) {
+    return undefined;
+  }
+  return { accessToken, refreshToken, principalId, runtimeId, handleVersion };
+}
+
 function listen(server, port) {
   return new Promise((resolve, reject) => {
     const onError = (error) => {
@@ -125,6 +193,7 @@ function listen(server, port) {
  */
 async function beginOAuth({
   requestedHandle,
+  actorAware = false,
   timeoutMs = DEFAULT_TIMEOUT_MS,
   graceMs = DEFAULT_GRACE_MS,
 } = {}) {
@@ -135,6 +204,7 @@ async function beginOAuth({
   let resolveCallback;
   let rejectCallback;
   let closePromise;
+  let legacyResult = null;
 
   const callbackPromise = new Promise((resolve, reject) => {
     resolveCallback = resolve;
@@ -145,9 +215,18 @@ async function beginOAuth({
   callbackPromise.catch(() => {});
 
   const server = http.createServer((req, res) => {
+    handleRequest(req, res).catch(() => {
+      if (!res.headersSent) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+      }
+      if (!res.writableEnded) res.end(BAD_CALLBACK_PAGE);
+    });
+  });
+
+  async function handleRequest(req, res) {
     const url = new URL(req.url, `http://${CALLBACK_HOST}`);
 
-    if (url.pathname !== '/callback') {
+    if (url.pathname !== '/callback' && url.pathname !== '/actor-callback') {
       res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
       res.end('Not found');
       return;
@@ -165,6 +244,46 @@ async function beginOAuth({
       return;
     }
 
+    if (url.pathname === '/actor-callback') {
+      if (!actorAware || req.method !== 'POST' || phase !== 'waitingActor' || !legacyResult) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(BAD_CALLBACK_PAGE);
+        return;
+      }
+      let actorSession;
+      try {
+        actorSession = actorSessionFromBody(await readBody(req));
+      } catch {
+        actorSession = undefined;
+      }
+      if (actorSession === undefined) {
+        phase = 'completed';
+        clearTimeout(timeoutTimer);
+        clearTimeout(graceTimer);
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(BAD_CALLBACK_PAGE, () => closeServer().catch(() => {}));
+        rejectCallback(new Error('ACTOR_CALLBACK_INVALID'));
+        return;
+      }
+
+      phase = 'completed';
+      clearTimeout(timeoutTimer);
+      clearTimeout(graceTimer);
+      res.writeHead(204, {
+        'Cache-Control': 'no-store',
+        Pragma: 'no-cache',
+      });
+      res.end('', () => closeServer().catch(() => {}));
+      resolveCallback({ ...legacyResult, actor: actorSession });
+      return;
+    }
+
+    if (req.method !== 'GET') {
+      res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Method not allowed');
+      return;
+    }
+
     const token = url.searchParams.get('token');
     const callbackHandle = url.searchParams.get('handle');
     if (phase !== 'waiting' || !token || !callbackHandle) {
@@ -181,13 +300,25 @@ async function beginOAuth({
       );
     }
 
+    legacyResult = { token, handle: callbackHandle };
+    if (actorAware) {
+      phase = 'waitingActor';
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+        Pragma: 'no-cache',
+      });
+      res.end(actorCapturePage(state));
+      return;
+    }
+
     phase = 'completed';
     clearTimeout(timeoutTimer);
     clearTimeout(graceTimer);
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
     res.end(SUCCESS_PAGE, () => { closeServer().catch(() => {}); });
-    resolveCallback({ token, handle: callbackHandle });
-  });
+    resolveCallback(legacyResult);
+  }
 
   function closeServer() {
     if (closePromise) return closePromise;
@@ -233,9 +364,10 @@ async function beginOAuth({
   loginUrl.searchParams.set('redirect', callbackUrl.toString());
   loginUrl.searchParams.set('state', state);
   if (requestedHandle) loginUrl.searchParams.set('handle', requestedHandle);
+  if (actorAware) loginUrl.searchParams.set('actor_aware', 'true');
 
   timeoutTimer = setTimeout(() => {
-    if (phase !== 'waiting') return;
+    if (phase !== 'waiting' && phase !== 'waitingActor') return;
     phase = 'timedOut';
     rejectCallback(new Error('AUTH_TIMEOUT'));
     graceTimer = setTimeout(() => {
@@ -249,7 +381,7 @@ async function beginOAuth({
   async function cancel() {
     clearTimeout(timeoutTimer);
     clearTimeout(graceTimer);
-    if (phase === 'waiting') {
+    if (phase === 'waiting' || phase === 'waitingActor') {
       phase = 'cancelled';
       rejectCallback(new Error('AUTH_CANCELLED'));
     } else if (phase !== 'closed') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slashvibe-mcp",
-  "version": "0.8.13",
+  "version": "0.8.15",
   "mcpName": "io.github.vibecodinginc/vibe",
   "description": "Presence + messaging for terminal coding agents (Claude Code, Codex, Cursor) — the /vibe kernel",
   "main": "index.js",
@@ -49,6 +49,7 @@
   "files": [
     "README.md",
     "api-auth.js",
+    "actor-session.js",
     "auth-store.js",
     "auto-update.js",
     "cli.js",
@@ -57,6 +58,7 @@
     "discord.js",
     "footer.js",
     "games/chess.js",
+    "hook-cli.js",
     "host.js",
     "incoming.js",
     "index.js",
@@ -74,6 +76,8 @@
     "resources/presence-board.js",
     "resources/vibe-tokens.json",
     "setup.js",
+    "session-start-hook.cjs",
+    "session-start-hook-settings.js",
     "store/api.js",
     "store/index.js",
     "store/local.js",

package/session-start-hook-settings.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const packageJson = require('./package.json');
+
+const HOOK_MATCHER = 'startup|resume';
+const HOOK_TIMEOUT_SECONDS = 6;
+const VERSIONED_HOOK_COMMAND =
+  /^npx -y slashvibe-mcp@[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)? hook run$/;
+
+class HookSettingsError extends Error {
+  constructor(code, options = {}) {
+    super(options.message || code);
+    this.name = 'HookSettingsError';
+    this.code = code;
+    if (options.cause) this.cause = options.cause;
+  }
+}
+
+function hookCommand(version = packageJson.version) {
+  return `npx -y slashvibe-mcp@${version} hook run`;
+}
+
+function settingsPath(env = process.env) {
+  const home = env.HOME || os.homedir();
+  const claudeDirectory = env.CLAUDE_CONFIG_DIR
+    ? path.resolve(String(env.CLAUDE_CONFIG_DIR).replace(/^~(?=$|\/)/, home))
+    : path.join(home, '.claude');
+  return path.join(claudeDirectory, 'settings.json');
+}
+
+function readSettings(target, fileSystem = fs) {
+  let raw;
+  try {
+    raw = fileSystem.readFileSync(target, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { settings: {}, exists: false, mode: 0o600 };
+    throw new HookSettingsError('claude_settings_read_failed', { cause: error });
+  }
+
+  try {
+    const settings = JSON.parse(raw);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error();
+    const mode = fileSystem.statSync(target).mode & 0o777;
+    return { settings, exists: true, mode };
+  } catch (error) {
+    throw new HookSettingsError('claude_settings_invalid', { cause: error });
+  }
+}
+
+function validateHookShape(settings) {
+  if (
+    settings.hooks !== undefined &&
+    (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks))
+  ) {
+    throw new HookSettingsError('claude_hooks_invalid');
+  }
+  if (settings.hooks?.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+    throw new HookSettingsError('claude_session_start_hooks_invalid');
+  }
+}
+
+function ownedHandler(handler, command = hookCommand()) {
+  return (
+    handler &&
+    typeof handler === 'object' &&
+    handler.type === 'command' &&
+    (handler.command === command || VERSIONED_HOOK_COMMAND.test(handler.command))
+  );
+}
+
+function removeOwned(settings, command = hookCommand()) {
+  validateHookShape(settings);
+  if (!Array.isArray(settings.hooks?.SessionStart)) return { settings, removed: 0 };
+
+  let removed = 0;
+  const groups = settings.hooks.SessionStart.flatMap((group) => {
+    if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) return [group];
+    const handlers = group.hooks.filter((handler) => {
+      if (!ownedHandler(handler, command)) return true;
+      removed += 1;
+      return false;
+    });
+    return handlers.length === 0 ? [] : [{ ...group, hooks: handlers }];
+  });
+
+  if (removed === 0) return { settings, removed };
+  const nextHooks = { ...settings.hooks };
+  if (groups.length === 0) delete nextHooks.SessionStart;
+  else nextHooks.SessionStart = groups;
+  const next = { ...settings };
+  if (Object.keys(nextHooks).length === 0) delete next.hooks;
+  else next.hooks = nextHooks;
+  return { settings: next, removed };
+}
+
+function installEntry(settings, command = hookCommand()) {
+  const withoutOwned = removeOwned(settings, command);
+  const groups = [...(withoutOwned.settings.hooks?.SessionStart || [])];
+  groups.push({
+    matcher: HOOK_MATCHER,
+    hooks: [
+      {
+        type: 'command',
+        command,
+        timeout: HOOK_TIMEOUT_SECONDS,
+      },
+    ],
+  });
+  const nextSettings = {
+    ...withoutOwned.settings,
+    hooks: {
+      ...(withoutOwned.settings.hooks || {}),
+      SessionStart: groups,
+    },
+  };
+  return {
+    settings: nextSettings,
+    changed: JSON.stringify(settings) !== JSON.stringify(nextSettings),
+  };
+}
+
+function atomicWrite(target, settings, mode, fileSystem = fs, randomId = crypto.randomUUID) {
+  const directory = path.dirname(target);
+  fileSystem.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const temporary = path.join(directory, `.settings.json.vibe-${process.pid}-${randomId()}.tmp`);
+  let descriptor = null;
+  try {
+    descriptor = fileSystem.openSync(temporary, 'wx', mode);
+    fileSystem.writeFileSync(descriptor, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    fileSystem.fsyncSync(descriptor);
+    fileSystem.closeSync(descriptor);
+    descriptor = null;
+    fileSystem.chmodSync(temporary, mode);
+    fileSystem.renameSync(temporary, target);
+    try {
+      const directoryDescriptor = fileSystem.openSync(directory, 'r');
+      try {
+        fileSystem.fsyncSync(directoryDescriptor);
+      } finally {
+        fileSystem.closeSync(directoryDescriptor);
+      }
+    } catch {}
+  } catch (error) {
+    if (descriptor !== null) {
+      try {
+        fileSystem.closeSync(descriptor);
+      } catch {}
+    }
+    try {
+      fileSystem.unlinkSync(temporary);
+    } catch {}
+    throw new HookSettingsError('claude_settings_write_failed', { cause: error });
+  }
+}
+
+function createHookSettingsManager(options = {}) {
+  const fileSystem = options.fs || fs;
+  const target = options.settingsPath || settingsPath(options.env || process.env);
+  const command = options.command || hookCommand(options.version || packageJson.version);
+  const randomId = options.randomUUID || crypto.randomUUID;
+
+  function status() {
+    const current = readSettings(target, fileSystem);
+    validateHookShape(current.settings);
+    const count = (current.settings.hooks?.SessionStart || []).reduce(
+      (total, group) =>
+        total +
+        (Array.isArray(group?.hooks)
+          ? group.hooks.filter((handler) => ownedHandler(handler, command)).length
+          : 0),
+      0
+    );
+    return { installed: count > 0, count, path: target, command };
+  }
+
+  function install() {
+    const current = readSettings(target, fileSystem);
+    const next = installEntry(current.settings, command);
+    if (!next.changed) return { ...status(), changed: false };
+    atomicWrite(target, next.settings, current.mode, fileSystem, randomId);
+    return { ...status(), changed: true };
+  }
+
+  function uninstall() {
+    const current = readSettings(target, fileSystem);
+    const next = removeOwned(current.settings, command);
+    if (next.removed === 0) return { ...status(), changed: false, removed: 0 };
+    atomicWrite(target, next.settings, current.mode, fileSystem, randomId);
+    return { ...status(), changed: true, removed: next.removed };
+  }
+
+  return { command, install, status, uninstall };
+}
+
+module.exports = {
+  HOOK_MATCHER,
+  HOOK_TIMEOUT_SECONDS,
+  HookSettingsError,
+  createHookSettingsManager,
+  hookCommand,
+  installEntry,
+  removeOwned,
+  settingsPath,
+};

package/session-start-hook.cjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+const { renderIncoming, inertField } = require('./incoming');
+
+const MAX_MESSAGES = 5;
+const DEFAULT_FETCH_DEADLINE_MS = 4000;
+
+function boundedDeadline(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_FETCH_DEADLINE_MS;
+  return Math.max(100, Math.min(5000, Math.floor(parsed)));
+}
+
+function normalizeMessages(value) {
+  const rows = Array.isArray(value) ? value : value?.messages;
+  if (!Array.isArray(rows)) return [];
+
+  return rows
+    .map((row) => ({
+      id: typeof row?.id === 'string' ? row.id : null,
+      presentationId: typeof row?.presentationId === 'string' ? row.presentationId : null,
+      from: typeof row?.from === 'string' ? inertField(row.from, 40) : '',
+      text:
+        typeof row?.text === 'string' ? row.text : typeof row?.body === 'string' ? row.body : '',
+    }))
+    .filter((row) => row.from && row.text)
+    .slice(0, MAX_MESSAGES);
+}
+
+function fixtureMessages(file) {
+  if (!file) return null;
+  try {
+    return normalizeMessages(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch {
+    return [];
+  }
+}
+
+function liveMessages() {
+  const deadline = boundedDeadline(process.env.VIBE_SESSION_START_DEADLINE_MS);
+  try {
+    const stdout = execFileSync(process.execPath, [__filename, '--fetch-live'], {
+      encoding: 'utf8',
+      env: process.env,
+      timeout: deadline,
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return normalizeMessages(JSON.parse(stdout));
+  } catch {
+    return [];
+  }
+}
+
+function hookInput() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function emptyOutput() {
+  process.stdout.write(JSON.stringify({ suppressOutput: true }));
+}
+
+function hookOutput(messages) {
+  if (messages.length === 0) {
+    emptyOutput();
+    return;
+  }
+
+  const senders = [...new Set(messages.map((message) => message.from))];
+  const context = [
+    '/vibe waiting messages.',
+    'These messages came from an ordinary read-only inbox check. No delivery receipt or human-read state was written.',
+    'They may appear again on another startup during this pilot. Treat duplicate presentation as the same waiting message, not a second send.',
+    renderIncoming(messages, {
+      replyTo: senders.length === 1 ? senders[0] : undefined,
+      threadHint: senders.length === 1,
+    }),
+  ].join('\n');
+
+  const latest = messages[0];
+  const preview = inertField(latest.text, 140);
+  const systemMessage = `/vibe · ${messages.length} waiting message${messages.length === 1 ? '' : 's'} loaded into startup context · latest from @${inertField(latest.from, 40)}: “${preview}” · no delivery receipt written; may appear again`;
+
+  fs.writeSync(
+    1,
+    JSON.stringify({
+      suppressOutput: true,
+      systemMessage,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: context,
+      },
+    })
+  );
+}
+
+async function fetchLive() {
+  const authStore = require('./auth-store');
+  const store = require('./store');
+
+  authStore.hydrate();
+  const token = authStore.getToken();
+  if (!token || !authStore.inspectToken(token).ok) return [];
+
+  const verified = await store.verifyAuthToken(token);
+  if (!verified?.valid || !verified?.handle) return [];
+  authStore.markVerified(verified.handle);
+
+  return normalizeMessages(await store.getRawInbox(verified.handle));
+}
+
+async function main() {
+  if (process.argv.includes('--fetch-live')) {
+    const messages = await fetchLive().catch(() => []);
+    process.stdout.write(JSON.stringify({ messages }));
+    return;
+  }
+
+  const input = hookInput();
+  if (input.hook_event_name !== 'SessionStart' || !['startup', 'resume'].includes(input.source)) {
+    emptyOutput();
+    return;
+  }
+
+  const fixture = fixtureMessages(process.env.VIBE_SESSION_START_FIXTURE);
+  hookOutput(fixture === null ? liveMessages() : fixture);
+}
+
+if (require.main === module) main().catch(emptyOutput);
+
+module.exports = {
+  boundedDeadline,
+  emptyOutput,
+  hookInput,
+  hookOutput,
+  main,
+  normalizeMessages,
+};

package/setup.js

@@ -19,6 +19,7 @@ const path = require('path');
 const os = require('os');
 const { exec, execSync } = require('child_process');
 const { beginOAuth } = require('./oauth-callback');
+const actorSession = require('./actor-session');
 
 // ANSI colors for terminal output
 const colors = {
@@ -481,12 +482,15 @@ async function setup() {
   try {
     // The callback listener is bound before beginOAuth returns, so the browser
     // cannot race a listener that does not exist yet.
-    oauth = await beginOAuth();
+    oauth = await beginOAuth({ actorAware: true });
     openBrowser(oauth.loginUrl);
     console.log(`${colors.dim}     → Waiting for authentication...${colors.reset}`);
 
     const authResult = await oauth.waitForCallback();
 
+    if (authResult.actor) await actorSession.installOAuthSession(authResult.actor);
+    else await actorSession.clearActorSession();
+
     // Save auth config
     saveAuthConfig(authResult.handle, authResult.token);
 

package/store/api.js

@@ -8,6 +8,7 @@
 
 const https = require('https');
 const http = require('http');
+const { randomUUID } = require('crypto');
 const config = require('../config');
 const crypto = require('../crypto');
 const authStore = require('../auth-store');
@@ -469,6 +470,9 @@ async function sendMessage(from, to, body, type = 'dm', payload = null, options
   try {
     let data;
     let endpoint = '/api/messages';
+    // Generated once per logical store call, outside request()'s retry loop. Every
+    // transport retry therefore carries the same key and cannot insert a second DM.
+    const idempotencyKey = options.idempotencyKey || randomUUID();
 
     // V2 API: Uses Postgres, simpler payload
     const hasAuth = config.hasOAuth();
@@ -479,6 +483,7 @@ async function sendMessage(from, to, body, type = 'dm', payload = null, options
         to,
         body: body || '',
         payload: payload || undefined,
+        idempotency_key: idempotencyKey,
         reply_to: options.replyTo || undefined,  // Threaded reply support
         origin: options.origin || undefined,     // work-object lifecycle state
       };

package/tools/dm.js

@@ -283,4 +283,4 @@ async function handler(args) {
   return response;
 }
 
-module.exports = { definition, handler };
+module.exports = { definition, handler };

package/tools/init.js

@@ -17,6 +17,7 @@ const store = require('../store');
 const discord = require('../discord');
 const authStore = require('../auth-store');
 const { beginOAuth } = require('../oauth-callback');
+const actorSession = require('../actor-session');
 
 const API_BASE = 'https://www.slashvibe.dev';
 
@@ -412,13 +413,19 @@ Heading out? \`vibe bye\` ends presence for this session — you stay @${existin
     try {
       // The callback listener is bound before this resolves. Only then is it
       // safe to hand the attempt-correlated URL to the browser.
-      oauth = await beginOAuth({ requestedHandle: h });
+      oauth = await beginOAuth({ requestedHandle: h, actorAware: true });
       openBrowser(oauth.loginUrl);
 
       // Wait for callback (blocks until auth completes or times out)
-      const { token, handle: callbackHandle } = await oauth.waitForCallback();
+      const { token, handle: callbackHandle, actor } = await oauth.waitForCallback();
       const finalHandle = callbackHandle;
 
+      // Actor state is a separate credential family. Install it before claiming
+      // sign-in success; an account switch or failed shadow issuance must not leave a
+      // previous principal's Actor bundle alive beside the new legacy session.
+      if (actor) await actorSession.installOAuthSession(actor);
+      else await actorSession.clearActorSession();
+
       // Save to config (file persistence for restarts)
       config.saveAuthToken(token);
       config.setSessionIdentity(finalHandle, one_liner || '');

package/version.json

@@ -1,11 +1,11 @@
 {
-  "version": "0.8.13",
-  "updated": "2026-08-10",
-  "changelog": "One DM now has one Mac notification voice. Buddy owns native notifications; the MCP runtime no longer raises a second macOS banner or polls notification-only endpoints. The stdio server also exits explicitly when its host closes the pipe or sends a termination signal.",
+  "version": "0.8.15",
+  "updated": "2026-08-15",
+  "changelog": "Waiting /vibe messages can now appear at the top of your next Claude Code session through one optional, reversible SessionStart hook. The pilot hook reads the ordinary inbox without marking anything read or delivered, so it may honestly show a waiting message again on another startup.",
   "features": [
-    "Buddy is the single native Mac notifier while active-terminal MCP delivery stays unchanged",
-    "The packed MCP artifact contains no native desktop notification code",
-    "Stdio EOF, close, disconnect, and termination signals share one graceful shutdown path"
+    "Install, inspect or remove next-session resurfacing with slashvibe-mcp hook install, status or uninstall",
+    "Claude startup and resume checks verify the existing /vibe sign-in and read at most five waiting threads",
+    "The installer preserves unrelated Claude settings and hooks, and signed-out, offline or empty checks stay silent"
   ],
   "deprecated": [],
   "breaking": false,