start-vibing-stacks 2.21.0 → 2.23.0

package/stacks/_shared/hooks/_state.ts

@@ -0,0 +1,444 @@
+/**
+ * Multi-Instance Coordination — Shared State Library
+ *
+ * Used by session-start.ts, user-prompt-submit.ts, pre-tool-use.ts,
+ * post-tool-use.ts, stop-validator.ts and peers.ts.
+ *
+ * Layout (project-local, gitignored):
+ *   .claude/state/
+ *     sessions/<id>.json        one record per active Claude instance
+ *     sessions/_archive/        sessions ended or stale
+ *     inbox/<id>.jsonl          messages queued for that session
+ *     file-touches.jsonl        append-only edit log
+ *     file-touches/_archive/    rotated logs
+ *
+ * Design rules:
+ * - All writes are atomic (.tmp + rename) where the file is read by peers.
+ * - Every read tolerates corruption (try/catch) — hooks must NEVER block Claude.
+ * - Heartbeat thresholds: <60s active, 60s-30min idle, >30min stale, >24h removed.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  appendFileSync,
+  openSync,
+  readSync,
+  closeSync,
+} from 'fs';
+import { join, basename } from 'path';
+import { randomBytes } from 'crypto';
+import { spawnSync } from 'child_process';
+
+export const ACTIVE_MS = 60 * 1000;
+export const IDLE_MS = 30 * 60 * 1000;
+export const STALE_MS = 24 * 60 * 60 * 1000;
+export const COLLISION_WINDOW_MS = 5 * 60 * 1000;
+
+export const TOUCHES_ROTATE_THRESHOLD = 1000;
+export const TOUCHES_TAIL_LINES = 200;
+export const FILES_TOUCHED_CAP = 50;
+
+export interface SessionRecord {
+  sessionId: string;
+  transcriptPath?: string;
+  title: string;
+  cwd: string;
+  ppid: number;
+  gitBranch?: string;
+  startedAt: string;
+  lastSeenAt: string;
+  lastActivity: string;
+  filesTouched: string[];
+}
+
+export interface FileTouch {
+  ts: string;
+  sessionId: string;
+  tool: string;
+  file: string;
+}
+
+export interface InboxMessage {
+  ts: string;
+  fromSessionId: string;
+  fromTitle?: string;
+  message: string;
+}
+
+export function getProjectDir(): string {
+  return process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+}
+
+export function getStateDir(projectDir: string = getProjectDir()): string {
+  return join(projectDir, '.claude', 'state');
+}
+
+export function ensureStateDirs(stateDir: string = getStateDir()): void {
+  mkdirSync(join(stateDir, 'sessions', '_archive'), { recursive: true });
+  mkdirSync(join(stateDir, 'inbox'), { recursive: true });
+  mkdirSync(join(stateDir, 'file-touches', '_archive'), { recursive: true });
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function ageMs(iso: string): number {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return Number.POSITIVE_INFINITY;
+  return Date.now() - t;
+}
+
+/** Atomic write: tmp + rename. Survives concurrent writers; the last rename wins. */
+export function writeFileAtomic(target: string, contents: string): void {
+  const tmp = `${target}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  writeFileSync(tmp, contents);
+  renameSync(tmp, target);
+}
+
+/** Read JSON; returns null on any error. */
+export function readJsonSafe<T>(path: string): T | null {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function getSessionPath(stateDir: string, sessionId: string): string {
+  return join(stateDir, 'sessions', `${sessionId}.json`);
+}
+
+export function readSession(stateDir: string, sessionId: string): SessionRecord | null {
+  return readJsonSafe<SessionRecord>(getSessionPath(stateDir, sessionId));
+}
+
+export function writeSession(stateDir: string, session: SessionRecord): void {
+  ensureStateDirs(stateDir);
+  writeFileAtomic(getSessionPath(stateDir, session.sessionId), JSON.stringify(session, null, 2));
+}
+
+export function listSessionFiles(stateDir: string): string[] {
+  const dir = join(stateDir, 'sessions');
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List sessions excluding the caller's own. Auto-archives stale (>30min) and
+ * removes very old (>24h) records as a side effect.
+ */
+export function listPeerSessions(
+  stateDir: string,
+  currentSessionId: string | null
+): SessionRecord[] {
+  const peers: SessionRecord[] = [];
+  for (const file of listSessionFiles(stateDir)) {
+    const rec = readJsonSafe<SessionRecord>(file);
+    if (!rec) continue;
+    if (rec.sessionId === currentSessionId) continue;
+
+    const age = ageMs(rec.lastSeenAt);
+    if (age > STALE_MS) {
+      try {
+        rmSync(file);
+      } catch {}
+      continue;
+    }
+    if (age > IDLE_MS) {
+      archiveSessionFile(stateDir, file);
+      continue;
+    }
+    peers.push(rec);
+  }
+  return peers;
+}
+
+export function archiveSessionFile(stateDir: string, sessionFile: string): void {
+  try {
+    const dest = join(stateDir, 'sessions', '_archive', basename(sessionFile));
+    renameSync(sessionFile, dest);
+  } catch {}
+}
+
+export function archiveSession(stateDir: string, sessionId: string): void {
+  const file = getSessionPath(stateDir, sessionId);
+  if (existsSync(file)) archiveSessionFile(stateDir, file);
+}
+
+/** Update lastSeenAt + lastActivity for the current session. Idempotent. */
+export function heartbeat(
+  stateDir: string,
+  sessionId: string,
+  activity: string,
+  patch: Partial<SessionRecord> = {}
+): SessionRecord {
+  const existing = readSession(stateDir, sessionId);
+  const now = nowIso();
+  const merged: SessionRecord = existing
+    ? { ...existing, ...patch, lastSeenAt: now, lastActivity: activity }
+    : {
+        sessionId,
+        title: patch.title || '(untitled)',
+        cwd: patch.cwd || getProjectDir(),
+        ppid: patch.ppid ?? process.ppid ?? 0,
+        gitBranch: patch.gitBranch,
+        transcriptPath: patch.transcriptPath,
+        startedAt: now,
+        lastSeenAt: now,
+        lastActivity: activity,
+        filesTouched: patch.filesTouched || [],
+      };
+  writeSession(stateDir, merged);
+  return merged;
+}
+
+export function recordFileTouch(stateDir: string, touch: FileTouch): void {
+  ensureStateDirs(stateDir);
+  const path = join(stateDir, 'file-touches.jsonl');
+  try {
+    appendFileSync(path, JSON.stringify(touch) + '\n');
+    rotateFileTouchesIfNeeded(stateDir);
+  } catch {}
+}
+
+export function rotateFileTouchesIfNeeded(stateDir: string): void {
+  const path = join(stateDir, 'file-touches.jsonl');
+  if (!existsSync(path)) return;
+  try {
+    const size = statSync(path).size;
+    if (size < 200_000) return;
+    const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    if (lines.length < TOUCHES_ROTATE_THRESHOLD) return;
+    const archiveName = `file-touches-${Date.now()}.jsonl`;
+    const archivePath = join(stateDir, 'file-touches', '_archive', archiveName);
+    writeFileSync(archivePath, lines.slice(0, lines.length - TOUCHES_TAIL_LINES).join('\n') + '\n');
+    writeFileSync(path, lines.slice(-TOUCHES_TAIL_LINES).join('\n') + '\n');
+  } catch {}
+}
+
+/** Read the last N lines of file-touches.jsonl (cheap tail, no full read). */
+export function tailFileTouches(stateDir: string, lines = TOUCHES_TAIL_LINES): FileTouch[] {
+  const path = join(stateDir, 'file-touches.jsonl');
+  if (!existsSync(path)) return [];
+  try {
+    const size = statSync(path).size;
+    const readBytes = Math.min(size, 64 * 1024);
+    const fd = openSync(path, 'r');
+    const buf = Buffer.alloc(readBytes);
+    readSync(fd, buf, 0, readBytes, size - readBytes);
+    closeSync(fd);
+    const text = buf.toString('utf8');
+    const all = text.split('\n').filter(Boolean);
+    const slice = all.slice(-lines);
+    const out: FileTouch[] = [];
+    for (const line of slice) {
+      try {
+        out.push(JSON.parse(line));
+      } catch {}
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export function getInboxPath(stateDir: string, sessionId: string): string {
+  return join(stateDir, 'inbox', `${sessionId}.jsonl`);
+}
+
+export function appendInbox(
+  stateDir: string,
+  targetSessionId: string,
+  msg: InboxMessage
+): void {
+  ensureStateDirs(stateDir);
+  try {
+    appendFileSync(getInboxPath(stateDir, targetSessionId), JSON.stringify(msg) + '\n');
+  } catch {}
+}
+
+/** Read all queued messages and remove the inbox file. */
+export function drainInbox(stateDir: string, sessionId: string): InboxMessage[] {
+  const path = getInboxPath(stateDir, sessionId);
+  if (!existsSync(path)) return [];
+  try {
+    const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    rmSync(path);
+    const out: InboxMessage[] = [];
+    for (const line of lines) {
+      try {
+        out.push(JSON.parse(line));
+      } catch {}
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export function clearInbox(stateDir: string, sessionId: string): void {
+  const path = getInboxPath(stateDir, sessionId);
+  if (existsSync(path)) {
+    try {
+      rmSync(path);
+    } catch {}
+  }
+}
+
+/** Read up to ~8KB of the transcript and extract a human title. */
+export function extractTitle(transcriptPath?: string, fallbackPrompt?: string): string {
+  if (transcriptPath && existsSync(transcriptPath)) {
+    try {
+      const fd = openSync(transcriptPath, 'r');
+      const buf = Buffer.alloc(8192);
+      const bytes = readSync(fd, buf, 0, buf.length, 0);
+      closeSync(fd);
+      const text = buf.subarray(0, bytes).toString('utf8');
+      for (const line of text.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const rec = JSON.parse(line);
+          if (typeof rec.summary === 'string' && rec.summary.trim()) {
+            return truncate(rec.summary.trim(), 80);
+          }
+          if (rec.type === 'user' && rec.message) {
+            const content =
+              typeof rec.message === 'string'
+                ? rec.message
+                : typeof rec.message?.content === 'string'
+                  ? rec.message.content
+                  : Array.isArray(rec.message?.content)
+                    ? rec.message.content
+                        .filter((c: any) => c.type === 'text')
+                        .map((c: any) => c.text)
+                        .join(' ')
+                    : '';
+            if (content) return truncate(content.replace(/\s+/g, ' ').trim(), 80);
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  if (fallbackPrompt) return truncate(fallbackPrompt.replace(/\s+/g, ' ').trim(), 80);
+  return '(untitled)';
+}
+
+export function truncate(s: string, n: number): string {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + '…';
+}
+
+export function shortId(sessionId: string): string {
+  return sessionId.slice(0, 8);
+}
+
+export function classifyAge(ageMsec: number): 'active' | 'idle' | 'stale' {
+  if (ageMsec < ACTIVE_MS) return 'active';
+  if (ageMsec < IDLE_MS) return 'idle';
+  return 'stale';
+}
+
+/**
+ * Inspect tool input and return a list of file paths that will be touched.
+ * Returns paths relative to projectDir when possible, else absolute.
+ */
+export function extractTargetFiles(toolName: string, toolInput: any, projectDir: string): string[] {
+  if (!toolInput || typeof toolInput !== 'object') return [];
+  const out: string[] = [];
+  const push = (p: any) => {
+    if (typeof p !== 'string' || !p) return;
+    let rel = p;
+    if (p.startsWith(projectDir + '/')) rel = p.slice(projectDir.length + 1);
+    out.push(rel);
+  };
+  if (toolName === 'Edit' || toolName === 'Write') {
+    push(toolInput.file_path || toolInput.path);
+  } else if (toolName === 'MultiEdit') {
+    push(toolInput.file_path || toolInput.path);
+  } else if (toolName === 'NotebookEdit') {
+    push(toolInput.notebook_path || toolInput.target_notebook);
+  }
+  return out;
+}
+
+/** Read JSON from stdin with a timeout fallback. */
+export async function readStdinJson(timeoutMs = 1500): Promise<any> {
+  return new Promise(resolve => {
+    let data = '';
+    const timer = setTimeout(() => {
+      try {
+        process.stdin.destroy();
+      } catch {}
+      try {
+        resolve(JSON.parse(data || '{}'));
+      } catch {
+        resolve({});
+      }
+    }, timeoutMs);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', c => {
+      data += c;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(data || '{}'));
+      } catch {
+        resolve({});
+      }
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      resolve({});
+    });
+  });
+}
+
+/** Resolve current git branch via spawnSync (no shell, no injection). */
+export function getGitBranch(projectDir: string): string | undefined {
+  try {
+    const r = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 2000,
+    });
+    if (r.status !== 0) return undefined;
+    const out = (r.stdout || '').toString().trim();
+    return out || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Format a peer session for systemMessage embedding.
+ */
+export function formatPeer(peer: SessionRecord): string {
+  const idle = ageMs(peer.lastSeenAt);
+  const klass = classifyAge(idle);
+  const idleSec = Math.round(idle / 1000);
+  const idleStr =
+    idleSec < 90
+      ? `${idleSec}s`
+      : idleSec < 60 * 60
+        ? `${Math.round(idleSec / 60)}min`
+        : `${Math.round(idleSec / 3600)}h`;
+  const branch = peer.gitBranch ? ` @${peer.gitBranch}` : '';
+  return `[${klass}] ${shortId(peer.sessionId)} "${peer.title}"${branch} idle=${idleStr}`;
+}

package/stacks/_shared/hooks/peers.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * `peers` — CLI for the multi-instance coordination layer.
+ *
+ * Usage:
+ *   peers list                                List active + idle peer sessions.
+ *   peers notify <id-prefix-or-substring> "msg"
+ *                                             Queue a message for that peer.
+ *   peers locks [--minutes 10]                Show files touched in the window.
+ *   peers cleanup                             Remove stale sessions (>1h idle).
+ *
+ * Exit codes:
+ *   0  success (and at least one peer for `list`)
+ *   1  argument / state error
+ *   2  no peers found (for `list`)
+ *
+ * Run:
+ *   npx tsx .claude/hooks/peers.ts <command>
+ */
+
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'fs';
+import { join, basename } from 'path';
+import {
+  ACTIVE_MS,
+  IDLE_MS,
+  STALE_MS,
+  ageMs,
+  appendInbox,
+  classifyAge,
+  ensureStateDirs,
+  formatPeer,
+  getProjectDir,
+  getStateDir,
+  listSessionFiles,
+  nowIso,
+  readJsonSafe,
+  shortId,
+  tailFileTouches,
+  type SessionRecord,
+} from './_state.js';
+
+function parseFlag(args: string[], flag: string, fallback?: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return fallback;
+  return args[i + 1];
+}
+
+function loadSessions(stateDir: string): SessionRecord[] {
+  const out: SessionRecord[] = [];
+  for (const file of listSessionFiles(stateDir)) {
+    const rec = readJsonSafe<SessionRecord>(file);
+    if (rec) out.push(rec);
+  }
+  return out;
+}
+
+function findCurrentSessionId(stateDir: string): string | null {
+  const fromEnv = process.env['CLAUDE_SESSION_ID'];
+  if (fromEnv) return fromEnv;
+  const sessions = loadSessions(stateDir).filter(s => ageMs(s.lastSeenAt) < ACTIVE_MS);
+  if (sessions.length === 1) return sessions[0]!.sessionId;
+  return null;
+}
+
+function cmdList(stateDir: string): number {
+  const all = loadSessions(stateDir);
+  const fresh = all.filter(s => ageMs(s.lastSeenAt) < IDLE_MS);
+  if (fresh.length === 0) {
+    console.log('No peer sessions in this project.');
+    return 2;
+  }
+  fresh.sort((a, b) => ageMs(a.lastSeenAt) - ageMs(b.lastSeenAt));
+  console.log(`Sessions registered for ${getProjectDir()}:`);
+  for (const s of fresh) console.log(`  ${formatPeer(s)}`);
+  return 0;
+}
+
+function cmdNotify(stateDir: string, args: string[]): number {
+  if (args.length < 2) {
+    console.error('Usage: peers notify <id-prefix-or-title-substring> "<message>"');
+    return 1;
+  }
+  const target = args[0]!;
+  const message = args.slice(1).join(' ');
+  if (!message.trim()) {
+    console.error('Empty message — nothing to send.');
+    return 1;
+  }
+
+  const all = loadSessions(stateDir).filter(s => ageMs(s.lastSeenAt) < STALE_MS);
+  const matches = all.filter(s => {
+    if (s.sessionId.startsWith(target)) return true;
+    if (s.title && s.title.toLowerCase().includes(target.toLowerCase())) return true;
+    return false;
+  });
+
+  if (matches.length === 0) {
+    console.error(`No peer session matches "${target}". Run \`peers list\`.`);
+    return 1;
+  }
+
+  if (matches.length > 1) {
+    console.error(`Ambiguous target "${target}" — ${matches.length} matches:`);
+    for (const m of matches) console.error(`  - ${formatPeer(m)}`);
+    console.error('Use a longer id prefix to disambiguate.');
+    return 1;
+  }
+
+  const target_ = matches[0]!;
+  const fromSessionId = findCurrentSessionId(stateDir) || 'cli';
+  const fromTitle = loadSessions(stateDir).find(s => s.sessionId === fromSessionId)?.title;
+
+  appendInbox(stateDir, target_.sessionId, {
+    ts: nowIso(),
+    fromSessionId,
+    fromTitle,
+    message,
+  });
+  console.log(`Queued message for ${shortId(target_.sessionId)} "${target_.title}".`);
+  return 0;
+}
+
+function cmdLocks(stateDir: string, args: string[]): number {
+  const minutes = Number(parseFlag(args, '--minutes', '10') || '10');
+  if (!Number.isFinite(minutes) || minutes <= 0) {
+    console.error('--minutes must be a positive number.');
+    return 1;
+  }
+  const windowMs = minutes * 60 * 1000;
+  const touches = tailFileTouches(stateDir, 1000).filter(t => ageMs(t.ts) <= windowMs);
+  if (touches.length === 0) {
+    console.log(`No file touches in the last ${minutes}min.`);
+    return 0;
+  }
+
+  const sessions = loadSessions(stateDir);
+  const sessById = new Map(sessions.map(s => [s.sessionId, s]));
+
+  type Row = { file: string; sessionId: string; ts: string; tool: string };
+  const byFile = new Map<string, Row>();
+  for (const t of touches) {
+    const prev = byFile.get(t.file);
+    if (!prev || Date.parse(t.ts) > Date.parse(prev.ts)) {
+      byFile.set(t.file, { file: t.file, sessionId: t.sessionId, ts: t.ts, tool: t.tool });
+    }
+  }
+
+  const rows = [...byFile.values()].sort(
+    (a, b) => Date.parse(b.ts) - Date.parse(a.ts)
+  );
+
+  console.log(`File touches in the last ${minutes}min (most-recent first):`);
+  for (const r of rows) {
+    const sess = sessById.get(r.sessionId);
+    const klass = sess ? classifyAge(ageMs(sess.lastSeenAt)) : 'gone';
+    const who = sess ? `${shortId(sess.sessionId)} "${sess.title}"` : `${shortId(r.sessionId)}(gone)`;
+    const ageSec = Math.round(ageMs(r.ts) / 1000);
+    console.log(`  ${r.file}  <-  ${who} [${klass}] via ${r.tool}, ${ageSec}s ago`);
+  }
+  return 0;
+}
+
+function cmdCleanup(stateDir: string): number {
+  ensureStateDirs(stateDir);
+  let archived = 0;
+  let removed = 0;
+  for (const file of listSessionFiles(stateDir)) {
+    const rec = readJsonSafe<SessionRecord>(file);
+    if (!rec) continue;
+    const age = ageMs(rec.lastSeenAt);
+    if (age > STALE_MS) {
+      try {
+        rmSync(file);
+        removed++;
+      } catch {}
+    } else if (age > IDLE_MS) {
+      try {
+        const dest = join(stateDir, 'sessions', '_archive', basename(file));
+        renameSync(file, dest);
+        archived++;
+      } catch {}
+    }
+  }
+
+  // Drop empty inbox files older than 7 days.
+  const inboxDir = join(stateDir, 'inbox');
+  if (existsSync(inboxDir)) {
+    try {
+      for (const f of readdirSync(inboxDir)) {
+        const p = join(inboxDir, f);
+        try {
+          const s = statSync(p);
+          if (s.size === 0 && Date.now() - s.mtimeMs > 7 * 24 * 60 * 60 * 1000) {
+            rmSync(p);
+          } else if (s.size > 0) {
+            const lines = readFileSync(p, 'utf8').split('\n').filter(Boolean);
+            if (lines.length === 0) rmSync(p);
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+
+  console.log(`Cleanup done. Archived: ${archived}. Removed: ${removed}.`);
+  return 0;
+}
+
+function usage(): void {
+  console.log(`peers — multi-instance coordination CLI
+
+Commands:
+  peers list
+  peers notify <id-prefix-or-title-substring> "<message>"
+  peers locks [--minutes 10]
+  peers cleanup
+`);
+}
+
+function main(): void {
+  const [, , cmd, ...rest] = process.argv;
+  const stateDir = getStateDir();
+
+  switch (cmd) {
+    case 'list':
+      process.exit(cmdList(stateDir));
+      break;
+    case 'notify':
+      process.exit(cmdNotify(stateDir, rest));
+      break;
+    case 'locks':
+      process.exit(cmdLocks(stateDir, rest));
+      break;
+    case 'cleanup':
+      process.exit(cmdCleanup(stateDir));
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      usage();
+      process.exit(0);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      usage();
+      process.exit(1);
+  }
+}
+
+main();