start-vibing-stacks 2.22.0 → 2.23.0

package/stacks/_shared/hooks/post-tool-use.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse Hook — Multi-Instance Coordination
+ *
+ * Wired with matcher `Edit|Write|MultiEdit|NotebookEdit`. Runs AFTER a write
+ * succeeds. Responsibilities:
+ *  1. Append a `FileTouch` record to `.claude/state/file-touches.jsonl`.
+ *  2. Update the session's heartbeat + `filesTouched` (capped at 50, deduped).
+ *
+ * On any internal error the hook exits silently — coordination must NEVER
+ * disturb Claude after a successful tool call.
+ */
+
+import {
+  FILES_TOUCHED_CAP,
+  ensureStateDirs,
+  extractTargetFiles,
+  getProjectDir,
+  getStateDir,
+  heartbeat,
+  nowIso,
+  readSession,
+  readStdinJson,
+  recordFileTouch,
+} from './_state.js';
+
+async function main(): Promise<void> {
+  const input = await readStdinJson(1500);
+  const sessionId: string | undefined = input.session_id || input.sessionId;
+  const toolName: string = input.tool_name || input.toolName || '';
+  const toolInput: any = input.tool_input || input.toolInput || {};
+  const toolResponse: any = input.tool_response || input.toolResponse;
+
+  if (!sessionId || !/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(toolName)) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Some tool responses surface a `success: false` — do not record those.
+  if (toolResponse && typeof toolResponse === 'object' && toolResponse.success === false) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const projectDir = getProjectDir();
+  const stateDir = getStateDir(projectDir);
+  ensureStateDirs(stateDir);
+
+  const targets = extractTargetFiles(toolName, toolInput, projectDir);
+  const ts = nowIso();
+  for (const file of targets) {
+    recordFileTouch(stateDir, { ts, sessionId, tool: toolName, file });
+  }
+
+  const session = readSession(stateDir, sessionId);
+  const previous = session?.filesTouched || [];
+  const merged = dedupeKeepLast([...previous, ...targets], FILES_TOUCHED_CAP);
+  heartbeat(stateDir, sessionId, `PostToolUse:${toolName}`, { filesTouched: merged });
+
+  console.log(JSON.stringify({ continue: true }));
+}
+
+function dedupeKeepLast(items: string[], cap: number): string[] {
+  const seen = new Set<string>();
+  const reversed: string[] = [];
+  for (let i = items.length - 1; i >= 0; i--) {
+    const x = items[i]!;
+    if (seen.has(x)) continue;
+    seen.add(x);
+    reversed.push(x);
+    if (reversed.length >= cap) break;
+  }
+  return reversed.reverse();
+}
+
+main().catch(() => {
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});

package/stacks/_shared/hooks/pre-tool-use.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse Hook — Multi-Instance Coordination
+ *
+ * Wired with matcher `Edit|Write|MultiEdit|NotebookEdit`. Reads the file-touches
+ * log + active peer sessions and decides:
+ *
+ *  - BLOCK if a peer is currently ACTIVE (heartbeat < 60s) AND touched the same
+ *    file within the last 5 minutes. The reason explains how to recover.
+ *  - WARN (approve + systemMessage) if a peer touched the file recently but is
+ *    only IDLE (60s — 5min).
+ *  - APPROVE silently otherwise.
+ *
+ * Hook input:
+ *   { session_id, tool_name, tool_input, hook_event_name, ... }
+ *
+ * Output schema (JSON):
+ *   { decision?: 'block', reason?: string, continue: true, systemMessage?: string }
+ *
+ * On any internal error, the hook approves silently — coordination must NEVER
+ * break Claude.
+ */
+
+import {
+  ACTIVE_MS,
+  COLLISION_WINDOW_MS,
+  ageMs,
+  classifyAge,
+  ensureStateDirs,
+  extractTargetFiles,
+  getProjectDir,
+  getStateDir,
+  heartbeat,
+  listPeerSessions,
+  readStdinJson,
+  shortId,
+  tailFileTouches,
+  type FileTouch,
+  type SessionRecord,
+} from './_state.js';
+
+interface Verdict {
+  block: boolean;
+  reason?: string;
+  warning?: string;
+}
+
+function evaluate(
+  targetFiles: string[],
+  peers: SessionRecord[],
+  touches: FileTouch[],
+  selfSessionId: string
+): Verdict {
+  if (targetFiles.length === 0) return { block: false };
+
+  const peerById = new Map<string, SessionRecord>();
+  for (const p of peers) peerById.set(p.sessionId, p);
+
+  // Most-recent peer touch per (file).
+  const recent = new Map<string, FileTouch>();
+  for (const t of touches) {
+    if (t.sessionId === selfSessionId) continue;
+    if (!targetFiles.includes(t.file)) continue;
+    if (ageMs(t.ts) > COLLISION_WINDOW_MS) continue;
+    const prev = recent.get(t.file);
+    if (!prev || Date.parse(t.ts) > Date.parse(prev.ts)) recent.set(t.file, t);
+  }
+
+  if (recent.size === 0) return { block: false };
+
+  const blockers: string[] = [];
+  const warns: string[] = [];
+
+  for (const [file, touch] of recent) {
+    const peer = peerById.get(touch.sessionId);
+    const peerActive = peer && ageMs(peer.lastSeenAt) < ACTIVE_MS;
+    const touchAgeSec = Math.round(ageMs(touch.ts) / 1000);
+    const peerLabel = peer
+      ? `${shortId(peer.sessionId)} "${peer.title}"${peer.gitBranch ? ` @${peer.gitBranch}` : ''}`
+      : `${shortId(touch.sessionId)} (session record gone)`;
+
+    if (peerActive) {
+      blockers.push(
+        `  - ${file}\n    last touched ${touchAgeSec}s ago by peer ${peerLabel} (HEARTBEAT ACTIVE)`
+      );
+    } else {
+      const klass = peer ? classifyAge(ageMs(peer.lastSeenAt)) : 'stale';
+      warns.push(
+        `  - ${file}: peer ${peerLabel} (${klass}) touched it ${touchAgeSec}s ago`
+      );
+    }
+  }
+
+  if (blockers.length > 0) {
+    const reason =
+      `BLOCKED by multi-instance coordination — another active Claude session is editing the same file.\n` +
+      `Active collision(s):\n${blockers.join('\n')}\n\n` +
+      `Recommended actions:\n` +
+      `  1. Run \`npx tsx .claude/hooks/peers.ts list\` to see who is active.\n` +
+      `  2. Notify them: \`npx tsx .claude/hooks/peers.ts notify <id-prefix> "I need to edit <file>, can you commit/stash?"\`\n` +
+      `  3. Wait for them to commit, then retry — or have them call \`peers.ts cleanup\` if you confirm they are no longer editing.\n` +
+      `  4. If you must override: re-run the same Edit after 60s of peer inactivity (their heartbeat will go IDLE and the hook will downgrade to a warning).`;
+    return { block: true, reason };
+  }
+
+  if (warns.length > 0) {
+    const warning =
+      `MULTI-INSTANCE WARNING — files you are about to edit were recently touched by an idle peer:\n${warns.join('\n')}\n` +
+      `Edit is allowed (peer is not actively typing). Consider rebasing on their work after they commit.`;
+    return { block: false, warning };
+  }
+
+  return { block: false };
+}
+
+async function main(): Promise<void> {
+  const input = await readStdinJson(1500);
+  const sessionId: string | undefined = input.session_id || input.sessionId;
+  const toolName: string = input.tool_name || input.toolName || '';
+  const toolInput: any = input.tool_input || input.toolInput || {};
+
+  // Defensive: only act on edit-class tools.
+  if (!/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(toolName)) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const projectDir = getProjectDir();
+  const stateDir = getStateDir(projectDir);
+  ensureStateDirs(stateDir);
+
+  if (sessionId) {
+    heartbeat(stateDir, sessionId, `PreToolUse:${toolName}`);
+  }
+
+  const targetFiles = extractTargetFiles(toolName, toolInput, projectDir);
+  if (targetFiles.length === 0) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const peers = listPeerSessions(stateDir, sessionId || null);
+  const touches = tailFileTouches(stateDir);
+
+  const verdict = evaluate(targetFiles, peers, touches, sessionId || '');
+
+  if (verdict.block) {
+    console.log(
+      JSON.stringify({
+        continue: true,
+        decision: 'block',
+        reason: verdict.reason,
+      })
+    );
+    return;
+  }
+
+  if (verdict.warning) {
+    console.log(
+      JSON.stringify({
+        continue: true,
+        systemMessage: verdict.warning,
+      })
+    );
+    return;
+  }
+
+  console.log(JSON.stringify({ continue: true }));
+}
+
+main().catch(() => {
+  // Coordination must never block Claude on its own bug.
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});

package/stacks/_shared/hooks/session-start.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * SessionStart Hook — Multi-Instance Coordination
+ *
+ * Runs once per Claude session start. Responsibilities:
+ *  1. Register this session in `.claude/state/sessions/<id>.json`.
+ *  2. Extract a human title from the transcript (matches what `claude --resume` shows).
+ *  3. Scan for peer sessions in the same project; warn if any are active.
+ *  4. Drain the inbox so messages from peers are surfaced in the first prompt.
+ *
+ * Hook input (JSON via stdin):
+ *   { session_id, transcript_path, cwd, hook_event_name, source }
+ *
+ * Output (JSON to stdout):
+ *   { continue: true, systemMessage?: string }
+ */
+
+import {
+  ageMs,
+  appendInbox,
+  drainInbox,
+  ensureStateDirs,
+  extractTitle,
+  formatPeer,
+  getGitBranch,
+  getProjectDir,
+  getStateDir,
+  heartbeat,
+  listPeerSessions,
+  nowIso,
+  readSession,
+  readStdinJson,
+  shortId,
+  type InboxMessage,
+} from './_state.js';
+
+async function main(): Promise<void> {
+  const input = await readStdinJson(1500);
+  const sessionId: string | undefined = input.session_id || input.sessionId;
+  const transcriptPath: string | undefined = input.transcript_path || input.transcriptPath;
+  const projectDir = getProjectDir();
+  const stateDir = getStateDir(projectDir);
+
+  if (!sessionId) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  ensureStateDirs(stateDir);
+
+  // Resolve title: prefer the existing record (so we don't lose a real title
+  // captured by user-prompt-submit when the SessionStart event also fires for
+  // a `/resume` flow that already had a title).
+  const existing = readSession(stateDir, sessionId);
+  const title = existing?.title && existing.title !== '(untitled)'
+    ? existing.title
+    : extractTitle(transcriptPath);
+
+  const branch = getGitBranch(projectDir);
+
+  heartbeat(stateDir, sessionId, 'SessionStart', {
+    transcriptPath,
+    title,
+    cwd: projectDir,
+    gitBranch: branch,
+  });
+
+  // Discover peers (active or idle within 30min).
+  const peers = listPeerSessions(stateDir, sessionId);
+
+  // Drain inbox messages addressed to this session.
+  const inbox = drainInbox(stateDir, sessionId);
+
+  const messageParts: string[] = [];
+  messageParts.push(
+    `MULTI-INSTANCE COORDINATION ACTIVE — this Claude session is registered as ${shortId(sessionId)} ("${title}"). State at .claude/state/.`
+  );
+
+  if (peers.length > 0) {
+    messageParts.push('');
+    messageParts.push(`PEERS DETECTED in this project (${peers.length}):`);
+    for (const p of peers) messageParts.push(`  - ${formatPeer(p)}`);
+    const anyActive = peers.some(p => ageMs(p.lastSeenAt) < 60 * 1000);
+    if (anyActive) {
+      messageParts.push('');
+      messageParts.push(
+        'WARNING: at least one peer is ACTIVE right now. Edit/Write of a file ' +
+          'a peer just touched will be BLOCKED by the PreToolUse hook to prevent ' +
+          'overwriting their uncommitted work. Coordinate via `/peers notify <id> "msg"` ' +
+          'before touching shared files.'
+      );
+    } else {
+      messageParts.push('');
+      messageParts.push(
+        'Peers are idle (>60s). Edits will be allowed but you will see a notice if ' +
+          'you touch files they recently modified.'
+      );
+    }
+  }
+
+  if (inbox.length > 0) {
+    messageParts.push('');
+    messageParts.push(`INBOX (${inbox.length} message${inbox.length === 1 ? '' : 's'} from peers):`);
+    for (const m of inbox) messageParts.push(formatInbox(m));
+  }
+
+  const systemMessage = messageParts.join('\n');
+
+  console.log(JSON.stringify({ continue: true, systemMessage }));
+}
+
+function formatInbox(m: InboxMessage): string {
+  const from = m.fromTitle ? `${shortId(m.fromSessionId)} "${m.fromTitle}"` : shortId(m.fromSessionId);
+  return `  [${m.ts}] from ${from}: ${m.message}`;
+}
+
+main().catch(() => {
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});
+
+// Silence unused-import warning when type-only imports are tree-shaken
+void nowIso;
+void appendInbox;

package/stacks/_shared/hooks/stop-validator.ts

@@ -15,6 +15,16 @@
 import { execSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import {
+  ACTIVE_MS,
+  ageMs,
+  archiveSession,
+  clearInbox,
+  ensureStateDirs,
+  formatPeer,
+  getStateDir,
+  listPeerSessions,
+} from './_state.js';
 
 const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
 const CLAUDE_MD = join(PROJECT_DIR, 'CLAUDE.md');
@@ -237,6 +247,33 @@ async function main(): Promise<void> {
   }
 
   const result = validate();
+
+  // Multi-instance coordination side effects.
+  const sessionId: string | undefined = hookInput.session_id || hookInput.sessionId;
+  const eventName: string = hookInput.hook_event_name || hookInput.hookEventName || '';
+  const isSessionEnd = /SessionEnd/i.test(eventName);
+
+  try {
+    const stateDir = getStateDir(PROJECT_DIR);
+    ensureStateDirs(stateDir);
+
+    if (result.decision === 'approve' && sessionId) {
+      const peers = listPeerSessions(stateDir, sessionId);
+      const activePeers = peers.filter(p => ageMs(p.lastSeenAt) < ACTIVE_MS);
+      if (activePeers.length > 0) {
+        const lines = activePeers.map(p => `  - ${formatPeer(p)}`).join('\n');
+        result.reason +=
+          `\n\nNOTE: ${activePeers.length} peer instance(s) still active in this project:\n${lines}\n` +
+          `If you committed and pushed, your work is now visible to them.`;
+      }
+    }
+
+    if (isSessionEnd && sessionId) {
+      archiveSession(stateDir, sessionId);
+      clearInbox(stateDir, sessionId);
+    }
+  } catch {}
+
   console.log(JSON.stringify(result));
   process.exit(0);
 }

package/stacks/_shared/hooks/user-prompt-submit.ts

@@ -2,14 +2,37 @@
 /**
  * UserPromptSubmit Hook — Start Vibing Stacks
  *
- * Injects workflow instructions before each user prompt.
- * Reads active-project.json for stack-specific context.
+ * Two responsibilities:
+ *  1. Inject the per-stack workflow + project-standards context block.
+ *  2. Multi-instance coordination: heartbeat the session, capture the title
+ *     from the first prompt (matches `claude --resume`), drain the inbox so
+ *     peer messages reach the user before this turn runs, and warn if active
+ *     peers exist.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-
-const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+import {
+  ACTIVE_MS,
+  ageMs,
+  drainInbox,
+  ensureStateDirs,
+  extractTitle,
+  formatPeer,
+  getGitBranch,
+  getProjectDir,
+  getStateDir,
+  heartbeat,
+  listPeerSessions,
+  readSession,
+  readStdinJson,
+  shortId,
+  truncate,
+  type InboxMessage,
+  type SessionRecord,
+} from './_state.js';
+
+const PROJECT_DIR = getProjectDir();
 const ACTIVE_PROJECT = join(PROJECT_DIR, '.claude', 'config', 'active-project.json');
 const STANDARDS_REVIEW = join(PROJECT_DIR, '.claude', 'config', 'standards-review.json');
 
@@ -36,7 +59,8 @@ interface ReviewFile {
 let standardsContext = '';
 try {
   if (!existsSync(STANDARDS_REVIEW)) {
-    standardsContext = `\n\nSTANDARDS REVIEW NEEDED: No standards-review.json found. ` +
+    standardsContext =
+      `\n\nSTANDARDS REVIEW NEEDED: No standards-review.json found. ` +
       `This project may have existing coding standards (.cursorrules, composer.json configs). ` +
       `Ask the user: "I noticed this project hasn't been scanned for existing standards. ` +
       `Would you like me to review your codebase patterns and adapt my behavior, ` +
@@ -45,26 +69,66 @@ try {
     const review: ReviewFile = JSON.parse(readFileSync(STANDARDS_REVIEW, 'utf8'));
     if (review.status === 'adapted' && review.patterns && review.patterns.length > 0) {
       const patternList = review.patterns.map(p => `- [${p.category}] ${p.name}`).join('\n');
-      standardsContext = `\n\nPROJECT STANDARDS (scanned from ${(review.sources || []).join(', ')}):\n${patternList}\n` +
+      standardsContext =
+        `\n\nPROJECT STANDARDS (scanned from ${(review.sources || []).join(', ')}):\n${patternList}\n` +
         `Follow these project-specific patterns. They take priority over generic defaults.`;
     }
   }
 } catch {}
 
-async function main(): Promise<void> {
-  let hookInput: any = {};
-  try {
-    const chunks: string[] = [];
-    process.stdin.setEncoding('utf8');
-    const timeout = setTimeout(() => process.stdin.destroy(), 1000);
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
+function formatInbox(m: InboxMessage): string {
+  const from = m.fromTitle ? `${shortId(m.fromSessionId)} "${m.fromTitle}"` : shortId(m.fromSessionId);
+  return `  [${m.ts}] from ${from}: ${m.message}`;
+}
+
+function buildPeersBlock(stateDir: string, sessionId: string, prompt: string): string {
+  ensureStateDirs(stateDir);
+
+  // Heartbeat + capture title on first prompt of the session.
+  const existing = readSession(stateDir, sessionId);
+  const titleNeeded = !existing || !existing.title || existing.title === '(untitled)';
+  const title = titleNeeded
+    ? extractTitle(existing?.transcriptPath, prompt)
+    : existing!.title;
+
+  const branch = existing?.gitBranch ?? getGitBranch(PROJECT_DIR);
+
+  heartbeat(stateDir, sessionId, 'UserPromptSubmit', {
+    title,
+    cwd: PROJECT_DIR,
+    gitBranch: branch,
+  });
+
+  const peers: SessionRecord[] = listPeerSessions(stateDir, sessionId);
+  const inbox = drainInbox(stateDir, sessionId);
+
+  const parts: string[] = [];
+  if (peers.length > 0) {
+    const activeCount = peers.filter(p => ageMs(p.lastSeenAt) < ACTIVE_MS).length;
+    parts.push('');
+    parts.push(`PEER INSTANCES IN THIS PROJECT (${peers.length}, ${activeCount} active):`);
+    for (const p of peers) parts.push(`  - ${formatPeer(p)}`);
+    if (activeCount > 0) {
+      parts.push(
+        '  ! Edit/Write of files an active peer just touched will be BLOCKED. ' +
+          'Use `/peers notify <id> "message"` to coordinate.'
+      );
     }
-    clearTimeout(timeout);
-    hookInput = JSON.parse(chunks.join('') || '{}');
-  } catch {}
+  }
+
+  if (inbox.length > 0) {
+    parts.push('');
+    parts.push(`INBOX (${inbox.length} message${inbox.length === 1 ? '' : 's'} from peers — surface to the user):`);
+    for (const m of inbox) parts.push(formatInbox(m));
+  }
 
-  const prompt = hookInput.user_prompt || hookInput.prompt || '';
+  return parts.join('\n');
+}
+
+async function main(): Promise<void> {
+  const hookInput = await readStdinJson(1500);
+  const prompt: string =
+    hookInput.user_prompt || hookInput.prompt || hookInput.userPrompt || '';
   if (!prompt.trim()) {
     console.log(JSON.stringify({ continue: true }));
     process.exit(0);
@@ -72,6 +136,17 @@ async function main(): Promise<void> {
 
   const today = new Date().toISOString().split('T')[0];
 
+  let peersBlock = '';
+  const sessionId: string | undefined = hookInput.session_id || hookInput.sessionId;
+  if (sessionId) {
+    const stateDir = getStateDir(PROJECT_DIR);
+    try {
+      peersBlock = buildPeersBlock(stateDir, sessionId, prompt);
+    } catch {
+      peersBlock = '';
+    }
+  }
+
   const systemMessage = `TASK WORKFLOW (Stack: ${stackName}):
 
 0. READ both CLAUDE.md and .claude/config/active-project.json before changes.
@@ -89,7 +164,7 @@ async function main(): Promise<void> {
    a. "## Last Change" (date: ${today}, branch, summary)
    b. Update ALL affected rule/flow sections
 
-6. Run stop-validator before finishing.${standardsContext}`;
+6. Run stop-validator before finishing.${standardsContext}${peersBlock}`;
 
   console.log(JSON.stringify({ continue: true, systemMessage }));
   process.exit(0);
@@ -99,3 +174,5 @@ main().catch(() => {
   console.log(JSON.stringify({ continue: true }));
   process.exit(0);
 });
+
+void truncate;

package/stacks/_shared/skills/multi-instance-coordination/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: multi-instance-coordination
+version: 1.0.0
+description: Coordination protocol when multiple Claude Code instances run in the same project folder. State layout under `.claude/state/`, peer detection, file-edit collision avoidance (hybrid block/warn), and the `/peers` CLI for cross-instance messaging. Use when the user mentions another Claude instance, parallel work, concurrent sessions, the word "peers", or asks about /resume titles, file-touches.jsonl, or `.claude/state/`.
+---
+
+# Multi-Instance Coordination
+
+When two or more Claude Code instances are running in the same project folder, they auto-discover each other through `.claude/state/` and refuse to overwrite each other's uncommitted work.
+
+## Mental model
+
+```
+.claude/state/
+  sessions/<id>.json        registry  (heartbeat = lastSeenAt)
+  sessions/_archive/        sessions ended or gone idle >30min
+  inbox/<id>.jsonl          messages queued FOR that session
+  file-touches.jsonl        append-only log of every Edit/Write
+  file-touches/_archive/    rotated logs (every 1000 lines)
+```
+
+Every hook updates `lastSeenAt` (heartbeat). Thresholds:
+
+| Age of last activity | State    | Effect                                                                 |
+| -------------------- | -------- | ---------------------------------------------------------------------- |
+| < 60s                | active   | Counts for collision detection; PreToolUse may BLOCK Edit/Write.       |
+| 60s – 30min          | idle     | Surfaced as a warning; edits NOT blocked.                              |
+| > 30min              | stale    | Auto-archived on the next sweep.                                       |
+| > 24h                | removed  | Deleted entirely.                                                      |
+
+## How a Claude session announces itself
+
+1. `SessionStart` runs once. It registers the session, extracts a `title` from the transcript (this is the same title that appears in `claude --resume`), lists peers, and drains the inbox.
+2. `UserPromptSubmit` keeps the heartbeat fresh on every user turn. It re-drains the inbox so messages arrive between turns, not stuck waiting for a SessionStart.
+3. `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`) checks `file-touches.jsonl` against the target file BEFORE the edit runs.
+4. `PostToolUse` (same matcher) records the touch AFTER a successful edit.
+5. `Stop` / `SessionEnd` archives the session and clears its inbox.
+
+## PreToolUse decision matrix
+
+| Peer who touched the same file last | Peer's heartbeat | Touch age | Decision |
+| ----------------------------------- | ---------------- | --------- | --------------------------------------------- |
+| any                                 | active (<60s)    | < 5min    | **BLOCK** with a recovery hint                |
+| any                                 | idle (60s–30min) | < 5min    | APPROVE + warning in `systemMessage`          |
+| any                                 | stale or gone    | any       | APPROVE silently                              |
+| no peer touched the file            | n/a              | n/a       | APPROVE silently                              |
+
+Override path: wait until the active peer's heartbeat goes idle (60s of no activity), then retry — the hook will downgrade to a warning. If the user explicitly tells you to override, ask them to run `peers notify <id> "I'm taking over <file>"` first so the other instance gets the heads-up.
+
+## Talking to a peer
+
+Always use the `peers` CLI. NEVER write to `.claude/state/inbox/` by hand.
+
+```bash
+# See who is around
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list
+
+# Send a message (id-prefix is the 8-char short id from `list`)
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify a1b2c3d4 "I just committed auth changes"
+
+# See recent file edits across instances
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" locks --minutes 10
+
+# Cleanup zombie sessions (>1h idle)
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" cleanup
+```
+
+The `/peers` slash command wraps these.
+
+## Guardrails
+
+- The coordination layer is **single-host**. It does not replace `git pull` or PR review across machines.
+- All state writes are atomic (`.tmp` + `rename`); reads are tolerant of corruption — hooks never block Claude on a broken state file.
+- `.claude/state/` MUST stay gitignored. Committing it would leak per-host PIDs and transcript paths.
+- `peers` is the user-facing surface; the hooks are internal plumbing. Do not invoke `_state.ts` directly.
+
+## Failure modes (and what to do)
+
+| Symptom                                                  | Cause                                | Fix                                                    |
+| -------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
+| `peers list` shows a phantom session                     | Crashed instance left a record       | `peers cleanup` (archives idle, removes >24h)          |
+| Edit blocked but the other instance is gone              | Stale heartbeat, peer never archived | Wait 30min, or run `peers cleanup`                     |
+| Inbox messages didn't arrive                             | Peer is paused / no `UserPromptSubmit` | They will appear on the next prompt the peer submits   |
+| Two edits hit the same file in the same second           | Race condition (rare)                | The append-only log captures both; review with `git diff` |
+
+## See Also
+
+- `git-workflow` — branch and commit hygiene; the coordination layer is an in-flight collision shield, not a replacement for branches.
+- `_state.ts` — shared TypeScript helpers used by every hook.
+- `.claude/state/` README at `.claude/hooks/_state.README.md`.