start-vibing-stacks 2.26.0 → 2.28.0

package/dist/migrate.d.ts

@@ -10,7 +10,9 @@
  *  - commands: same `version:` frontmatter contract as skills/agents.
  *  - .claude/settings.json — patched idempotently to ensure the bundled hook
  *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
- *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    SessionEnd) is wired, plus high-reasoning defaults `effortLevel: "xhigh"`
+ *    and `permissions.defaultMode: "plan"` (only when MISSING — user choices are
+ *    never clobbered). Existing entries are preserved; only missing entries
  *    are appended. Atomic write (.tmp + rename).
  *  - .claude/state/ — runtime layout for multi-instance coordination is
  *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.

package/dist/migrate.js

@@ -10,7 +10,9 @@
  *  - commands: same `version:` frontmatter contract as skills/agents.
  *  - .claude/settings.json — patched idempotently to ensure the bundled hook
  *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
- *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    SessionEnd) is wired, plus high-reasoning defaults `effortLevel: "xhigh"`
+ *    and `permissions.defaultMode: "plan"` (only when MISSING — user choices are
+ *    never clobbered). Existing entries are preserved; only missing entries
  *    are appended. Atomic write (.tmp + rename).
  *  - .claude/state/ — runtime layout for multi-instance coordination is
  *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.
@@ -302,6 +304,26 @@ export function patchSettings(projectDir, dryRun) {
         }
         report.added.push(event);
     }
+    // High-reasoning defaults (v2.28.0). Only set when MISSING so we never clobber
+    // a user's explicit choice. `ultracode` is intentionally never written here:
+    // it is session-only (/effort) and cannot be persisted in settings.json.
+    if (settings.effortLevel === undefined) {
+        if (!dryRun)
+            settings.effortLevel = 'xhigh';
+        report.added.push('effortLevel:xhigh');
+    }
+    else {
+        report.alreadyPresent.push('effortLevel');
+    }
+    settings.permissions = settings.permissions || {};
+    if (settings.permissions.defaultMode === undefined) {
+        if (!dryRun)
+            settings.permissions.defaultMode = 'plan';
+        report.added.push('permissions.defaultMode:plan');
+    }
+    else {
+        report.alreadyPresent.push('permissions.defaultMode');
+    }
     if (!dryRun && report.added.length > 0 && !report.error) {
         mkdirSync(dirname(path), { recursive: true });
         writeFileAtomic(path, JSON.stringify(settings, null, '\t'));

package/dist/setup.js

@@ -226,6 +226,10 @@ export async function setupProject(projectDir, config, options = {}) {
             model: 'sonnet',
             max_tokens: 8192,
             max_turns: 100,
+            // Persistent high-reasoning effort. Note: 'ultracode' is session-only
+            // (set via /effort) and cannot be persisted here; 'xhigh' is the highest
+            // persistable level. On 'sonnet' it falls back to 'high'.
+            effortLevel: 'xhigh',
             enableAllProjectMcpServers: true,
             autoMemoryEnabled: true,
             context: {
@@ -235,6 +239,9 @@ export async function setupProject(projectDir, config, options = {}) {
                 memory_files: ['.claude/CLAUDE.md', 'CLAUDE.md'],
             },
             permissions: {
+                // Always start sessions in plan mode (read-only): the agent must
+                // present a plan before editing. Shift+Tab still cycles modes per turn.
+                defaultMode: 'plan',
                 allow: [
                     'Bash(*)',
                     'Read(*)',

package/package.json

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

package/stacks/_shared/agents/commit-manager.md

@@ -1,7 +1,7 @@
 ---
 name: commit-manager
-version: 3.0.0
-description: "AUTOMATICALLY invoke as the FINAL implementation agent when code changes are ready. Verifies security-auditor and quality-gate passed (HARD GATE — will NOT commit if vetoed), analyzes the diff for a precise conventional commit message, stages ONLY this session's files via `scope.ts` when state is available (falls back to `git add -A` for solo projects), commits, pushes, and triggers the post-commit chain (documenter → domain-updater). Multi-instance safe: never bundles peer sessions' uncommitted files into your commit. Supports branch-merge and direct-to-main flows. v3.0.0 (May-2026): per-instance scoped staging + Recent Changes (LIFO) chain alignment."
+version: 3.1.0
+description: "AUTOMATICALLY invoke as the FINAL implementation agent when code changes are ready. Verifies security-auditor and quality-gate passed (HARD GATE — will NOT commit if vetoed), analyzes the diff for a precise conventional commit message, commits ONLY this session's files via `scope.ts commit` (atomic `git commit -o`, never bundles a peer's staged work; `git add -A` only in solo projects), pushes, and triggers the post-commit chain (documenter → domain-updater). Multi-instance safe: never bundles peer sessions' uncommitted files into your commit, and STOPS rather than falling back to `git add -A` when the session cannot be resolved. Supports branch-merge and direct-to-main flows. v3.1.0 (May-2026): atomic pathspec commit + safe (no -A) fallback + CLAUDE_SESSION_ID requirement."
 model: sonnet
 tools: Read, Bash, Grep, Glob
 skills: git-workflow
@@ -130,68 +130,73 @@ Read at most 3 files in full diff. For the rest, rely on the stat + file names.
 
 ## Step 4 — Stage and commit (per-instance scoped)
 
-### 4a. Stage — `scope.ts` first, `git add -A` as fallback
+### 4a. Compose the message (HEREDOC, shell-safe multi-line)
+
+```bash
+MSG="$(cat <<'EOF'
+<type>(<scope>): <subject>
+
+<body — 2-5 bullets if ≥ 3 files>
+EOF
+)"
+```
+
+Rules:
+- **No** `Co-Authored-By` header unless the user explicitly asked for it.
+- **No** `Generated with Claude Code` footer — it adds noise to git log.
+- Subject line ≤ 72 chars. Body wraps at 80 chars. Empty body is fine for single-file changes.
+
+### 4b. Commit — `scope.ts commit` (multi-instance) or `git add -A` (solo only)
 
 The truth of "what did THIS session edit?" lives in `.claude/state/sessions/<id>.json#filesTouched`,
-maintained by `post-tool-use.ts`. Stage from that, NOT from the worktree at large — otherwise
-you risk bundling a peer session's uncommitted files into your commit.
+maintained by `post-tool-use.ts`. In a multi-instance project, commit ONLY those files. `scope.ts
+commit` does this atomically via `git commit -o -- <files>` (commits exactly your paths regardless
+of what a peer has staged) — there is NO `git add -A`, because that is precisely what bundles a
+peer's uncommitted work into your commit.
 
 ```bash
 SCOPE_TS="$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts"
 STATE_DIR="$CLAUDE_PROJECT_DIR/.claude/state"
 
 if [ -f "$SCOPE_TS" ] && [ -d "$STATE_DIR" ]; then
-  # Multi-instance project: stage this session's files only.
-  npx tsx "$SCOPE_TS" stage
-  STAGE_CODE=$?
-  case "$STAGE_CODE" in
-    0)
-      # All safe files staged. Continue.
-      ;;
+  # Multi-instance project: commit this session's files only (never -A).
+  # scope.ts resolves the session via $CLAUDE_SESSION_ID, else the single active
+  # session. With ≥2 active sessions and no $CLAUDE_SESSION_ID it returns 1.
+  npx tsx "$SCOPE_TS" commit "$MSG"
+  COMMIT_CODE=$?
+  case "$COMMIT_CODE" in
+    0) ;;  # committed your scope cleanly
     2)
-      # Some safe files staged; conflicted ones skipped intentionally.
-      # scope.ts already printed the warning. Continue — committing the safe scope is correct.
-      echo "ℹ️  Conflicted files skipped (peer also touched in last 5 min). Proceeding with safe scope."
+      # A peer touched one of your files in the last 5 min. Do NOT override blindly.
+      echo "⛔ Conflict: a peer is editing one of your files. Coordinate via:"
+      echo "   npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts\" notify <id> \"...\""
+      echo "   Then re-run, or (only if you own the change) add --include-conflicted."
+      exit 1
       ;;
     *)
-      # scope.ts couldn't resolve session or found no dirty files in scope.
-      # Fall back to legacy behavior — should NOT happen in a healthy multi-instance project.
-      echo "⚠️  scope.ts returned $STAGE_CODE; falling back to legacy `git add -A` (multi-instance risk!)"
-      git add -A
+      # Session could not be resolved (≥2 active, no $CLAUDE_SESSION_ID) or no dirty
+      # files in scope. STOP — do NOT fall back to `git add -A` (it bundles peers).
+      echo "⛔ scope.ts could not commit this session's scope (code $COMMIT_CODE)."
+      echo "   Set CLAUDE_SESSION_ID or pass --session <id>, then re-run."
+      echo "   Inspect with: npx tsx \"$SCOPE_TS\" status"
+      exit 1
       ;;
   esac
 else
-  # Solo project (no .claude/state/) — legacy flow is correct.
+  # Solo project (no .claude/state/) — only here is `git add -A` safe.
   git add -A
+  # Guard against incidental junk (multi-instance path is immune: scope commits
+  # only filesTouched, so these never get staged in the first place).
+  git reset HEAD -- .DS_Store .env *.log 2>/dev/null || true
+  git commit -m "$MSG"
 fi
 
 git status --short
 ```
 
-Verify no unexpected files (`.DS_Store`, `.env`, `*.log`). If found:
-
-```bash
-git reset HEAD -- .DS_Store .env *.log 2>/dev/null || true
-```
-
-### 4b. Commit with HEREDOC (shell-safe multi-line)
-
-```bash
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <subject>
-
-<body — 2-5 bullets if ≥ 3 files>
-
-EOF
-)"
-```
-
-Rules:
-- **No** `Co-Authored-By` header unless the user explicitly asked for it.
-- **No** `Generated with Claude Code` footer — it adds noise to git log.
-- Subject line ≤ 72 chars.
-- Body wraps at 80 chars.
-- Empty body is fine for single-file changes.
+> Operational requirement: `scope.ts` needs to know which session is committing.
+> Ensure `CLAUDE_SESSION_ID` is exported to the shell, OR run with `--session <id>`
+> when more than one instance is active. The fallback is to STOP, never `git add -A`.
 
 ---
 
@@ -279,7 +284,7 @@ Action:     <what the user should do>
 ## Critical rules
 
 1. **GATE CHECK FIRST** — NEVER commit if `security-auditor` has open CRITICAL/HIGH/MEDIUM findings or `quality-gate` failed. This is non-negotiable.
-2. **PER-INSTANCE STAGING** — when `.claude/state/` exists, ALWAYS stage via `scope.ts` (Step 4a). NEVER `git add -A` blindly in a multi-instance project; it bundles peers' uncommitted files into your commit. See CLAUDE.md NRY "Instance N's commit bundling instance M's uncommitted files".
+2. **PER-INSTANCE COMMIT** — when `.claude/state/` exists, ALWAYS commit via `scope.ts commit` (Step 4b), which uses `git commit -o -- <files>` to commit EXACTLY your files. NEVER `git add -A` in a multi-instance project; it bundles peers' uncommitted files. If `scope.ts` cannot resolve the session, STOP — do NOT fall back to `git add -A`. See CLAUDE.md NRY "Instance N's commit bundling instance M's uncommitted files".
 3. **DIFF-DRIVEN MESSAGES** — read the actual diff (stat first, full only when needed). Never generate generic messages.
 4. **HEREDOC** — always use `cat <<'EOF'` for commit messages. Never inline multi-line strings.
 5. **NO FORCE PUSH** — never `git push --force` or `--force-with-lease` to main/master unless the user explicitly requests it.

package/stacks/_shared/commands/commit-mine.md

@@ -1,7 +1,7 @@
 ---
 name: commit-mine
 description: Commit ONLY this Claude session's edited files (multi-instance safe). Replaces raw `git add . && git commit` to prevent your commit from bundling a peer session's uncommitted changes.
-version: 1.0.0
+version: 1.1.0
 ---
 
 # /commit-mine — Per-Instance Commit
@@ -14,25 +14,30 @@ cleanly. This command stages and commits ONLY the files your session actually ed
 **Source of truth:** `.claude/state/sessions/<your-id>.json#filesTouched`, maintained by
 `post-tool-use.ts` (one entry per successful Edit / Write / MultiEdit / NotebookEdit).
 
-| # | Step | Tool |
-|---|---|---|
-| 1 | **Inspect scope** — list SAFE / CONFLICTED / NOT-YOURS / STAGED | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" status` |
-| 2 | **Resolve conflicts** if any (peer touched same file in last 5 min) | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify <id> "msg"` |
-| 3 | **Stage** — `git reset` then `git add` only this session's dirty files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" stage` |
-| 4 | **Review** — confirm the staged diff is what you expect | `git diff --cached --stat` and (optionally) `git diff --cached` |
-| 5 | **Commit** — conventional message (`feat`, `fix`, `docs`, etc.) + diff-driven body | `git commit -m "<message>"` OR delegate to `commit-manager` agent |
-| 6 | **Push** (optional) | `git push` |
-
-## Shortcut (single command)
-
-If steps 1–5 are routine and you already know what you edited:
+**Recommended (single atomic command):**
 
 ```bash
 npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>" [--push]
 ```
 
-This runs stage + commit (+ optional push) atomically. It will REFUSE to proceed if a
-peer touched any of your files in the last 5 min unless you pass `--include-conflicted`.
+This commits ONLY your session's files via `git commit -o -- <files>` — it commits
+exactly your paths regardless of what a peer has staged, so it can never bundle their
+work, and it never runs a global `git reset`. It REFUSES if a peer touched any of your
+files in the last 5 min unless you pass `--include-conflicted`.
+
+**Step-by-step (when you want to review first):**
+
+| # | Step | Tool |
+|---|---|---|
+| 1 | **Inspect scope** — list SAFE / CONFLICTED / NOT-YOURS / STAGED | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" status` |
+| 2 | **Resolve conflicts** if any (peer touched same file in last 5 min) | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify <id> "msg"` |
+| 3 | **Review** the diff of your files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" diff` |
+| 4 | **Commit** — atomic, only your files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>"` |
+| 5 | **Push** (optional) | add `--push` to step 4, or `git push` |
+
+> `scope stage` still exists for manual index inspection, but it is best-effort in a
+> shared worktree (a peer's staged files can linger). Prefer `scope commit` — it is the
+> only path that is atomic against a concurrent peer.
 
 ## Forbidden patterns (NEVER do these in a multi-instance project)
 
@@ -68,6 +73,6 @@ manual edits not via Claude tools) are skipped — they appear in `status` under
 
 - `/fix` step 7 ("Commit") and `/feature` workflows that previously implied `git add .`
   should now route through `/commit-mine` whenever `peers.ts list` shows ≥ 1 peer.
-- The `commit-manager` agent (if used) MUST call `scope stage` before any `git commit`
+- The `commit-manager` agent (if used) MUST commit via `scope commit` (never `git add -A`)
   in a multi-instance project.
 - See `CLAUDE.md` NRY: "Instance N's commit bundling instance M's uncommitted files".

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

@@ -26,8 +26,8 @@ When two or more Claude Code instances run in the same project folder, the hooks
 
 | 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.        |
+| < 180s        | active   | Counts for collision detection. PreToolUse may **block** Edit/Write.        |
+| 180s – 30min  | idle     | Surfaced as a warning in `systemMessage`. Edits are **not** blocked.        |
 | > 30min       | stale    | Auto-archived on the next sweep.                                            |
 | > 24h         | removed  | Deleted entirely.                                                           |
 

package/stacks/_shared/hooks/_state.ts

@@ -1,4 +1,4 @@
-// @sv-version: 1.0.0
+// @sv-version: 1.1.0
 /**
  * Multi-Instance Coordination — Shared State Library
  *
@@ -16,7 +16,13 @@
  * 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.
+ * - Heartbeat thresholds: <180s active, 180s-30min idle, >30min stale, >24h removed.
+ *
+ * v1.1.0: ACTIVE window 60s→180s (agent think/generate time between tool calls
+ * routinely exceeds 60s — a 60s window mis-classifies busy peers as IDLE);
+ * FILES_TOUCHED_CAP 50→200 (large sessions were dropping early edits, which then
+ * showed up as orphaned dirty files a peer could not attribute); path
+ * normalization in extractTargetFiles is now repo-root-stable.
  */
 
 import {
@@ -33,18 +39,18 @@ import {
   readSync,
   closeSync,
 } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, resolve, relative, isAbsolute } from 'path';
 import { randomBytes } from 'crypto';
 import { spawnSync } from 'child_process';
 
-export const ACTIVE_MS = 60 * 1000;
+export const ACTIVE_MS = 180 * 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 const FILES_TOUCHED_CAP = 200;
 
 export interface SessionRecord {
   sessionId: string;
@@ -238,7 +244,9 @@ export function tailFileTouches(stateDir: string, lines = TOUCHES_TAIL_LINES): F
   if (!existsSync(path)) return [];
   try {
     const size = statSync(path).size;
-    const readBytes = Math.min(size, 64 * 1024);
+    // 512KB tail comfortably holds ≳1000 touch records; collision decisions read
+    // up to 1000 lines (see callers), so the byte window must not truncate them.
+    const readBytes = Math.min(size, 512 * 1024);
     const fd = openSync(path, 'r');
     const buf = Buffer.alloc(readBytes);
     readSync(fd, buf, 0, readBytes, size - readBytes);
@@ -361,11 +369,19 @@ export function classifyAge(ageMsec: number): 'active' | 'idle' | 'stale' {
 export function extractTargetFiles(toolName: string, toolInput: any, projectDir: string): string[] {
   if (!toolInput || typeof toolInput !== 'object') return [];
   const out: string[] = [];
+  // Normalize every path to the SAME shape `git status --porcelain` emits:
+  // forward-slash, relative to the project (≈ repo) root. Tools may hand us an
+  // absolute path, a path relative to a subdirectory cwd, or already-relative.
+  // A mismatch here is the #1 cause of "I edited this file but scope.ts says it
+  // is NOT MINE" — the string simply fails to equal the git porcelain path.
   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);
+    const abs = isAbsolute(p) ? p : resolve(projectDir, p);
+    let rel = relative(projectDir, abs);
+    // Outside the project tree (rare): keep the original so we never crash; it
+    // simply will not match a git path, which is the correct, safe outcome.
+    if (!rel || rel.startsWith('..')) rel = p;
+    out.push(rel.split('\\').join('/'));
   };
   if (toolName === 'Edit' || toolName === 'Write') {
     push(toolInput.file_path || toolInput.path);

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

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-// @sv-version: 1.0.0
+// @sv-version: 1.1.0
 /**
  * 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
+ *  - BLOCK if a peer is currently ACTIVE (heartbeat < 180s) 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).
+ *    only IDLE (180s — 5min).
  *  - APPROVE silently otherwise.
  *
  * Hook input:
@@ -100,7 +100,7 @@ function evaluate(
       `  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).`;
+      `  4. If you must override: re-run the same Edit after 180s of peer inactivity (their heartbeat will go IDLE and the hook will downgrade to a warning).`;
     return { block: true, reason };
   }
 
@@ -141,7 +141,8 @@ async function main(): Promise<void> {
   }
 
   const peers = listPeerSessions(stateDir, sessionId || null);
-  const touches = tailFileTouches(stateDir);
+  // Read a wide tail so a peer's collision touch is not missed under heavy load.
+  const touches = tailFileTouches(stateDir, 1000);
 
   const verdict = evaluate(targetFiles, peers, touches, sessionId || '');
 

package/stacks/_shared/hooks/scope.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// @sv-version: 1.0.0
+// @sv-version: 1.1.0
 /**
  * `scope` — Per-Instance Commit Scoping CLI
  *
@@ -9,17 +9,29 @@
  *
  * Source of truth for "what did THIS session edit?":
  *   `.claude/state/sessions/<id>.json#filesTouched`
- * which is maintained by `post-tool-use.ts` (capped at 50, dedup-keep-last).
+ * which is maintained by `post-tool-use.ts` (capped at 200, dedup-keep-last).
+ *
+ * Concurrency model (v1.1.0): two instances in the SAME working directory share
+ * ONE `.git/index`. A `git reset` + `git add` + `git commit` sequence is therefore
+ * NOT atomic across peers — peer B's `git add` between our reset and commit would
+ * be folded into our commit. To be genuinely safe we commit by pathspec:
+ *   `git add -- <ours>` (additive, never disturbs a peer's staged entries) then
+ *   `git commit -o -- <ours>` (--only: commits EXACTLY these paths regardless of
+ *   what else is staged). No global `git reset`.
+ * For true isolation across concurrent commits, prefer one git worktree per
+ * instance (`git worktree add`); this CLI is the best-effort same-worktree path.
  *
  * Usage:
  *   scope status                        Show this session's files vs peers' files vs untracked.
- *   scope stage [--include-conflicted]  `git reset`, then `git add` only this session's dirty files.
- *                                       Refuses files a peer touched in the last 5 min unless
- *                                       --include-conflicted.
+ *   scope stage [--include-conflicted]  `git add` only this session's dirty files (additive;
+ *                                       resets the index only when no peer is active). Prefer
+ *                                       `scope commit` for the safe atomic path.
  *   scope diff                          `git diff` for files this session touched.
- *   scope commit "<msg>" [--push]       stage + commit + optional push.
+ *   scope commit "<msg>" [--push]       commit ONLY this session's files via `git commit -o`.
  *
  * Session discovery: --session <id>, else $CLAUDE_SESSION_ID, else single active session.
+ * NOTE: with ≥2 active sessions and CLAUDE_SESSION_ID unset, discovery fails by
+ * design (we will not guess) — pass --session <id> or export CLAUDE_SESSION_ID.
  *
  * Exit codes:
  *   0  ok
@@ -127,7 +139,7 @@ function classify(stateDir: string, sessionId: string, projectDir: string): Scop
   const status = gitDirty(projectDir);
   const dirty = new Set<string>([...status.modified, ...status.untracked]);
 
-  const touches = tailFileTouches(stateDir);
+  const touches = tailFileTouches(stateDir, 1000);
   const peerById = new Map(loadAllSessions(stateDir).map(p => [p.sessionId, p]));
   const peerTouches = new Map<string, FileTouch>();
   for (const t of touches) {
@@ -180,7 +192,7 @@ function cmdStatus(stateDir: string, projectDir: string, args: string[]): number
   console.log(
     `Session ${shortId(sessionId)} "${session.title}" (branch ${session.gitBranch || '?'})`
   );
-  console.log(`Files in session.filesTouched: ${session.filesTouched.length} (cap 50, dedup)`);
+  console.log(`Files in session.filesTouched: ${session.filesTouched.length} (cap 200, dedup)`);
   console.log();
   console.log(`SAFE TO STAGE (${mine.length}):`);
   if (mine.length === 0) {
@@ -254,13 +266,23 @@ function cmdStage(stateDir: string, projectDir: string, args: string[]): number
     return 1;
   }
 
-  // The `git reset` here is intentional: scope semantics own the index.
-  // Anything a peer staged previously will be unstaged; they will re-stage
-  // their own files via `scope stage` when they commit.
-  const resetR = git(['reset'], projectDir);
-  if (resetR.code !== 0) {
-    console.error(`git reset failed: ${resetR.stderr.trim()}`);
-    return 1;
+  // Index hygiene: a shared `.git/index` means a global `git reset` would wipe a
+  // peer's staged work. Only reset when NO peer is active (solo / safe). When a
+  // peer is active we stage ADDITIVELY and rely on `scope commit` (git commit -o)
+  // to commit exactly our paths regardless of what else is staged.
+  const activePeers = loadAllSessions(stateDir).filter(
+    s => s.sessionId !== sessionId && ageMs(s.lastSeenAt) < ACTIVE_MS
+  );
+  if (activePeers.length === 0) {
+    const resetR = git(['reset'], projectDir);
+    if (resetR.code !== 0) {
+      console.error(`git reset failed: ${resetR.stderr.trim()}`);
+      return 1;
+    }
+  } else {
+    console.log(
+      `${activePeers.length} active peer(s) — staging additively (no \`git reset\`) to protect their index.`
+    );
   }
   const addR = git(['add', '--', ...toStage], projectDir);
   if (addR.code !== 0) {
@@ -270,6 +292,8 @@ function cmdStage(stateDir: string, projectDir: string, args: string[]): number
 
   console.log(`Staged ${toStage.length} file(s) from session ${shortId(sessionId)}:`);
   for (const f of toStage) console.log(`  + ${f}`);
+  console.log();
+  console.log('SAFEST commit path (never bundles peers): scope commit "<message>"');
 
   if (conflicted.length > 0 && !includeConflicted) {
     console.log();
@@ -285,7 +309,6 @@ function cmdStage(stateDir: string, projectDir: string, args: string[]): number
     return 2;
   }
 
-  console.log();
   console.log('Review with: git diff --cached --stat');
   return 0;
 }
@@ -335,22 +358,66 @@ function cmdCommit(stateDir: string, projectDir: string, args: string[]): number
     return 1;
   }
 
-  const stageCode = cmdStage(stateDir, projectDir, args);
-  if (stageCode === 1) return 1;
-  if (stageCode === 2 && !hasFlag(args, '--include-conflicted')) {
-    console.error();
+  const sessionId = resolveSessionId(stateDir, parseFlag(args, '--session'));
+  if (!sessionId) {
+    console.error('Cannot resolve session ID. Set CLAUDE_SESSION_ID or pass --session <id>.');
+    console.error('Tip: run `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list`.');
+    return 1;
+  }
+  const session = readSession(stateDir, sessionId);
+  if (!session) {
+    console.error(`Session ${shortId(sessionId)} not registered.`);
+    return 1;
+  }
+
+  const { mine, conflicted } = classify(stateDir, sessionId, projectDir);
+  const includeConflicted = hasFlag(args, '--include-conflicted');
+  const conflictedFiles = conflicted.map(c => c.file);
+  const toCommit = includeConflicted ? [...mine, ...conflictedFiles] : mine;
+
+  if (toCommit.length === 0) {
+    if (conflicted.length > 0) {
+      console.error(
+        `No safe files to commit. ${conflicted.length} conflicted file(s) — pass --include-conflicted to override.`
+      );
+      for (const c of conflicted) {
+        const who = c.peer ? `${shortId(c.peer.sessionId)} "${c.peer.title}"` : '(unknown)';
+        console.error(`  ! ${c.file}  ←  ${who}, ${c.ageSec}s ago`);
+      }
+      return 2;
+    }
+    console.error('No files to commit (this session has no dirty files in filesTouched).');
+    return 1;
+  }
+
+  if (conflicted.length > 0 && !includeConflicted) {
     console.error(
-      'Refusing to commit while conflicted files were skipped. ' +
-        'Resolve, OR re-run with --include-conflicted.'
+      `Refusing to commit: ${conflicted.length} of your files were also touched by an active peer in the last 5 min.`
     );
+    for (const c of conflicted) {
+      const who = c.peer ? `${shortId(c.peer.sessionId)} "${c.peer.title}"` : '(unknown)';
+      console.error(`  ! ${c.file}  ←  ${who}, ${c.ageSec}s ago`);
+    }
+    console.error('Coordinate via `peers.ts notify <id> "..."`, OR re-run with --include-conflicted.');
     return 2;
   }
 
-  const commitR = git(['commit', '-m', message], projectDir);
+  // Atomic, shared-index-safe commit. `git add` is additive (never touches a
+  // peer's staged entries); `git commit -o -- <paths>` commits EXACTLY those
+  // paths regardless of what else is staged, so a peer's concurrently-staged
+  // files can never be folded into this commit. No global `git reset`.
+  const addR = git(['add', '--', ...toCommit], projectDir);
+  if (addR.code !== 0) {
+    console.error(`git add failed: ${addR.stderr.trim()}`);
+    return 1;
+  }
+  const commitR = git(['commit', '-o', '-m', message, '--', ...toCommit], projectDir);
   process.stdout.write(commitR.stdout);
   process.stderr.write(commitR.stderr);
   if (commitR.code !== 0) return 1;
 
+  console.log(`Committed ${toCommit.length} file(s) from session ${shortId(sessionId)}.`);
+
   if (hasFlag(args, '--push')) {
     const pushR = spawnSync('git', ['push'], { cwd: projectDir, stdio: 'inherit' });
     return pushR.status ?? 1;
@@ -367,9 +434,10 @@ Commands:
   scope diff     [--session <id>]
   scope commit   "<message>" [--session <id>] [--include-conflicted] [--push]
 
-Stages and commits ONLY the files this Claude session edited (per
-\`.claude/state/sessions/<id>.json#filesTouched\`). Refuses to stage
-files a peer session touched in the last 5 min unless --include-conflicted.
+Commits ONLY the files this Claude session edited (per
+\`.claude/state/sessions/<id>.json#filesTouched\`), via \`git commit -o\` so a
+peer's concurrently-staged files are never bundled in. Refuses files a peer
+session touched in the last 5 min unless --include-conflicted.
 
 Exit codes: 0=ok, 1=arg/state error, 2=conflict refusal.
 `);

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

@@ -17,6 +17,7 @@
  */
 
 import {
+  ACTIVE_MS,
   ageMs,
   appendInbox,
   drainInbox,
@@ -81,7 +82,7 @@ async function main(): Promise<void> {
     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);
+    const anyActive = peers.some(p => ageMs(p.lastSeenAt) < ACTIVE_MS);
     if (anyActive) {
       messageParts.push('');
       messageParts.push(
@@ -93,7 +94,7 @@ async function main(): Promise<void> {
     } else {
       messageParts.push('');
       messageParts.push(
-        'Peers are idle (>60s). Edits will be allowed but you will see a notice if ' +
+        'Peers are idle (>3min). Edits will be allowed but you will see a notice if ' +
           'you touch files they recently modified.'
       );
     }

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// @sv-version: 1.2.0
+// @sv-version: 1.3.0
 /**
  * Stop Validator Hook — Start Vibing Stacks (Universal)
  *
@@ -17,6 +17,13 @@
  * (append-only LIFO) as a valid changelog section. Source of truth for "what did
  * THIS session edit?" is `.claude/state/sessions/<id>.json#filesTouched`, maintained
  * by `post-tool-use.ts`.
+ *
+ * v1.3.0: on APPROVE, surface "orphan" dirty files — files dirty in the worktree
+ * that are NOT in this session's filesTouched (e.g. changed via Bash, codegen, or
+ * formatters, which post-tool-use cannot capture). These are scoped OUT of the
+ * blocking check (so a peer's work never blocks you), but silently leaving them
+ * behind is exactly what makes the NEXT instance "see files and hesitate to
+ * deploy". We never block on them; we WARN so the agent can verify/own them.
  */
 
 import { execSync } from 'child_process';
@@ -264,11 +271,24 @@ function validate(sessionId: string | undefined): HookResult {
     };
   }
 
-  // All good
+  // All good. If per-instance scoping hid orphan dirty files (dirty, but not in
+  // THIS session's filesTouched), surface them — they may be your own Bash/codegen
+  // changes that post-tool-use could not attribute. We do NOT block on them.
+  let orphanNote = '';
+  if (perInstance && totalDirty > modified.length) {
+    const orphans = getModifiedFiles().filter(f => !modified.includes(f));
+    orphanNote =
+      `\n\nNOTE: ${orphans.length} dirty file(s) are NOT attributed to this session ` +
+      `(e.g. changed via Bash, a formatter, or codegen):\n` +
+      orphans.slice(0, 10).map(f => `  ? ${f}`).join('\n') +
+      `\nIf any are yours, commit them with \`scope.ts commit\` (only your files). ` +
+      `If they belong to a peer, leave them. Do not \`git add -A\`.`;
+  }
+
   return {
     continue: false,
     decision: 'approve',
-    reason: `ALL CHECKS PASSED ✅\nStack: ${stackId}\nBranch: ${branch}\nTree: Clean\nSecrets: clean`,
+    reason: `ALL CHECKS PASSED ✅\nStack: ${stackId}\nBranch: ${branch}\nTree: Clean (this-session scope)\nSecrets: clean${orphanNote}`,
   };
 }
 

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

@@ -23,8 +23,8 @@ 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.                              |
+| < 180s               | active   | Counts for collision detection; PreToolUse may BLOCK Edit/Write.       |
+| 180s – 30min         | idle     | Surfaced as a warning; edits NOT blocked.                              |
 | > 30min              | stale    | Auto-archived on the next sweep.                                       |
 | > 24h                | removed  | Deleted entirely.                                                      |
 
@@ -40,12 +40,12 @@ Every hook updates `lastSeenAt` (heartbeat). Thresholds:
 
 | 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                                 | active (<180s)   | < 5min    | **BLOCK** with a recovery hint                |
+| any                                 | idle (180s–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.
+Override path: wait until the active peer's heartbeat goes idle (180s 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