The Stream H wrapper shipped a deliberate no-op main() — the lock did nothing.
This wires it live: PreToolUse on a mutating tool acquires/refreshes the
workspace lock (blocks only when a DIFFERENT session holds a fresh, non-stale
lock); the Stop event releases it. Fail-open on any error so a lock bug can
never wedge the user out of their own session.
- runAcquireDecision({event,now,pid,cwd,readLock,writeLock}) — compose
acquire() + decide().
- runReleaseAction({event,cwd,readLock,deleteLock}) — release() if this
session owns the lock, no-op otherwise.
- live main(): branches on tool_name (present → acquire/refresh; absent/Stop
→ release); real fs binding via runtimeDir()/session-lock-<workspaceHash>.json.
Activation registers BOTH the PreToolUse (acquire) AND the Stop (release)
entries — the Stop wiring is mandatory; without it the lock is never released
and the next abnormal exit would lock the user out. Script:
.scratch/activate-point2-hooks.ps1 (also registers safe-baseline-metering +
runtime-write-deny per the point-2 plan).
Plan: docs/superpowers/plans/2026-05-30-router-gate-v4-stream-H.md Task 7.
Regression: parallel-session-lock 12/12 GREEN; full tools suite 1958 passed | 2 skipped.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Closes Stream H Task 7 (H7). Prevents two Claude sessions on the same
workspace from concurrently mutating files — addresses the cross-session
worktree collisions seen on 28.05/29.05 (deploy branch hijack + push
non-fast-forward incidents).
Architecture:
- Pure module tools/parallel-session-lock.mjs with injectable I/O
(readLock/writeLock/deleteLock) so unit tests cover all branches without
touching the real filesystem. Exports acquire(), refresh(), release(),
computeWorkspaceHash(), LOCK_DEFAULT_TTL_MS (5 minutes).
- Lock record schema (schema_version=1): {session_id, pid, acquired_at, ttl_ms}.
Stored at ~/.claude/runtime/session-lock-<workspaceHash>.json (production
binding handled in deferred batch). Workspace hash is MD5 first-12 hex of
the resolved workspace path.
- Acquisition semantics: stale (past TTL) → take over; same-session → idempotent
re-acquire; other-session fresh → block. refresh() is same-session only
(never steals). release() is same-session only (never deletes other's lock).
- Wrapper tools/enforce-parallel-session-lock.mjs exports decide(acquireResult,
sessionId) → {block, reason?}. Fail-open if acquireResult is missing
(internal-error safety net — avoids the Stream G Task 8 self-lockout
pattern). Block message names the other holder's pid for human triage
("parallel session lock held by <other> (pid N) — wait or close that
session first").
Defensive design:
- main() is a no-op (exit 0) until settings.json registration AND a Stop-hook
release pathway are wired together in the batched activation step. Activating
this hook before release-on-Stop would lock the user out of their own
session on first abnormal exit.
Regression: vitest tools 1763/1763 GREEN (was 1748; +10 pure-module tests
under "parallel-session-lock pure module (Stream H Task 7)" and
"computeWorkspaceHash (Stream H Task 7)" describe blocks; +5 wrapper-decide
tests under "enforce-parallel-session-lock wrapper (Stream H Task 7)").
DEFERRED: .claude/settings.json registration (PreToolUse matcher
"Edit|Write|MultiEdit|NotebookEdit|Bash", block-mode, timeout 3000ms);
Stop-hook release wiring; PostToolUse refresh-on-success wiring.
Batched at end of Phase H-α/H-β.
Stream H Task 7 of 11. Plan: docs/superpowers/plans/2026-05-30-router-gate-v4-stream-H.md
Дмитрий