start-vibing-stacks 2.22.0 → 2.24.0

package/dist/setup.js

@@ -68,6 +68,10 @@ export async function setupProject(projectDir, config, options = {}) {
         mkdirSync(join(claudeDir, 'commands'), { recursive: true });
         mkdirSync(join(claudeDir, 'rules'), { recursive: true });
         mkdirSync(join(claudeDir, 'skills', 'codebase-knowledge', 'domains'), { recursive: true });
+        // Multi-instance coordination state (gitignored, runtime-managed)
+        mkdirSync(join(claudeDir, 'state', 'sessions', '_archive'), { recursive: true });
+        mkdirSync(join(claudeDir, 'state', 'inbox'), { recursive: true });
+        mkdirSync(join(claudeDir, 'state', 'file-touches', '_archive'), { recursive: true });
         spinner.text = 'Directory structure created';
         // 2. Copy shared agents (universal)
         const sharedAgentsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'agents');
@@ -79,6 +83,12 @@ export async function setupProject(projectDir, config, options = {}) {
         // 4. Copy shared hooks
         const sharedHooksDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'hooks');
         const hookCount = copyDirRecursive(sharedHooksDir, join(claudeDir, 'hooks'), options.force);
+        // 4b. Multi-instance coordination README in state dir
+        const stateReadmeSrc = join(PACKAGE_ROOT, 'stacks', '_shared', 'hooks', '_state.README.md');
+        const stateReadmeDest = join(claudeDir, 'state', 'README.md');
+        if (existsSync(stateReadmeSrc) && (!existsSync(stateReadmeDest) || options.force)) {
+            writeFileSync(stateReadmeDest, readFileSync(stateReadmeSrc, 'utf8'));
+        }
         // 5. Copy shared config
         const sharedConfigDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'config');
         copyDirRecursive(sharedConfigDir, join(claudeDir, 'config'), options.force);
@@ -140,13 +150,21 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = 'Imported .cursorrules into Claude config';
             }
         }
-        // 11b. Ensure CLAUDE.local.md is gitignored
+        // 11b. Ensure CLAUDE.local.md and .claude/state/ are gitignored
         const gitignorePath = join(projectDir, '.gitignore');
         if (existsSync(gitignorePath)) {
-            const gitignore = readFileSync(gitignorePath, 'utf8');
+            let gitignore = readFileSync(gitignorePath, 'utf8');
+            let changed = false;
             if (!gitignore.includes('CLAUDE.local.md')) {
-                writeFileSync(gitignorePath, gitignore.trimEnd() + '\n\n# Claude Code local preferences\nCLAUDE.local.md\n');
+                gitignore = gitignore.trimEnd() + '\n\n# Claude Code local preferences\nCLAUDE.local.md\n';
+                changed = true;
+            }
+            if (!gitignore.match(/^\.claude\/state\/?$/m) && !gitignore.match(/^\.claude\/?$/m)) {
+                gitignore = gitignore.trimEnd() + '\n\n# Claude Code multi-instance coordination state (runtime, per-host)\n.claude/state/\n';
+                changed = true;
             }
+            if (changed)
+                writeFileSync(gitignorePath, gitignore);
         }
         // 11c. Save standards review results
         if (config.standardsReview) {
@@ -230,6 +248,17 @@ export async function setupProject(projectDir, config, options = {}) {
                 deny: [],
             },
             hooks: {
+                SessionStart: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"',
+                                timeout: 10,
+                            },
+                        ],
+                    },
+                ],
                 UserPromptSubmit: [
                     {
                         matcher: '',
@@ -242,6 +271,30 @@ export async function setupProject(projectDir, config, options = {}) {
                         ],
                     },
                 ],
+                PreToolUse: [
+                    {
+                        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"',
+                                timeout: 5,
+                            },
+                        ],
+                    },
+                ],
+                PostToolUse: [
+                    {
+                        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use.ts"',
+                                timeout: 5,
+                            },
+                        ],
+                    },
+                ],
                 Stop: [
                     {
                         hooks: [
@@ -253,6 +306,17 @@ export async function setupProject(projectDir, config, options = {}) {
                         ],
                     },
                 ],
+                SessionEnd: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"',
+                                timeout: 10,
+                            },
+                        ],
+                    },
+                ],
             },
             agents: {
                 'research-web': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/commands/peers.md

@@ -0,0 +1,37 @@
+---
+name: peers
+description: Inspect or talk to other Claude Code instances running in this same project (multi-instance coordination layer).
+version: 1.0.0
+---
+
+# /peers — Multi-Instance Coordination
+
+Use this when the user asks something like:
+
+- "is there another Claude running in this folder?"
+- "tell the other instance I finished the auth work"
+- "who touched `src/x.ts` recently?"
+- "clean up dead sessions"
+
+Run the `peers` CLI via Bash. The script lives at `.claude/hooks/peers.ts` and is installed by `start-vibing-stacks`.
+
+## Usage
+
+| Goal | Command |
+|---|---|
+| List active + idle peer sessions | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list` |
+| Notify another instance | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify <id-prefix> "message"` |
+| See who touched what file recently | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" locks --minutes 10` |
+| Remove stale sessions | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" cleanup` |
+
+The `<id-prefix>` is the 8-character short id printed by `peers list`, or any substring of the peer's title.
+
+## Output rules
+
+- Always quote the short id (first 8 chars), the title, and the idle time when reporting peers to the user.
+- If `peers notify` succeeds, tell the user the message will surface in the OTHER instance at the start of its next prompt (drained by `user-prompt-submit.ts`).
+- If `peers list` says "No peer sessions", confirm that to the user and DO NOT suggest workarounds.
+
+## Background
+
+State lives in `.claude/state/` (gitignored). Hooks `session-start.ts`, `user-prompt-submit.ts`, `pre-tool-use.ts`, `post-tool-use.ts` and `stop-validator.ts` keep it in sync. See `multi-instance-coordination` skill for the full protocol.

package/stacks/_shared/hooks/_state.README.md

@@ -0,0 +1,55 @@
+# `.claude/state/` — Multi-Instance Coordination
+
+> This directory is **gitignored** and managed automatically by hooks. Safe to delete; it will be recreated by the next Claude session.
+
+When two or more Claude Code instances run in the same project folder, the hooks under `.claude/hooks/` use this directory to:
+
+1. announce themselves to each other (`sessions/<id>.json`)
+2. record file edits as they happen (`file-touches.jsonl`)
+3. prevent simultaneous writes to the same file (PreToolUse hook reads the touch log)
+4. exchange messages (`inbox/<id>.jsonl` — drained at next prompt)
+
+## Layout
+
+```
+.claude/state/
+  sessions/
+    <session-id>.json          one record per active instance (heartbeat-tracked)
+    _archive/                  sessions ended or stale (>30min idle)
+  inbox/
+    <session-id>.jsonl         queued messages for that session
+  file-touches.jsonl           append-only Edit/Write log (rotates every 1000 lines)
+  file-touches/_archive/       rotated logs
+```
+
+## Heartbeat thresholds
+
+| Last activity | State    | Effect                                                                      |
+| ------------- | -------- | --------------------------------------------------------------------------- |
+| < 60s         | active   | Counts for collision detection. PreToolUse may **block** Edit/Write.        |
+| 60s – 30min   | idle     | Surfaced as a warning in `systemMessage`. Edits are **not** blocked.        |
+| > 30min       | stale    | Auto-archived on the next sweep.                                            |
+| > 24h         | removed  | Deleted entirely.                                                           |
+
+## Viewing peers
+
+From inside Claude or a terminal:
+
+```
+/peers
+```
+
+or directly:
+
+```
+npx tsx .claude/hooks/peers.ts list
+npx tsx .claude/hooks/peers.ts notify <id-prefix> "message"
+npx tsx .claude/hooks/peers.ts locks --minutes 10
+npx tsx .claude/hooks/peers.ts cleanup
+```
+
+## Safety
+
+- All state writes are atomic (`.tmp` + `rename`).
+- All reads are tolerant of corruption — hooks never block Claude on a malformed file.
+- This is a single-host coordination layer. It does **not** replace git; it only prevents two live sessions from stepping on the same uncommitted edit.

package/stacks/_shared/hooks/_state.ts

@@ -0,0 +1,445 @@
+// @sv-version: 1.0.0
+/**
+ * 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/final-check.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @sv-version: 1.0.0
 /**
  * Final Check — executable validator with VETO.
  *