instar 1.3.600 → 1.3.602

package/dist/core/PrHandLease.d.ts

@@ -0,0 +1,151 @@
+/**
+ * PrHandLease — per-branch ownership lease so two of the agent's OWN concurrent
+ * sessions ("hands") cannot push competing commits to the same branch.
+ *
+ * Spec: docs/specs/parallel-hand-pr-lease.md (review-convergence + approved).
+ * Closes the push-competition cause of the 2026-06-15 PR #1183 merge thrash.
+ *
+ * Design anchors (from the converged spec):
+ *  - Identity = holderTopicId (stable across the constant session respawns);
+ *    holderSessionId is a LIVENESS-PROBE HANDLE ONLY, never the identity (§3.2/B2).
+ *  - ONE process-wide lock guards the single JSON file (matching ResumeQueue's
+ *    single lockPath); per-record compare-and-swap under that lock (§3.3/B3/M-D).
+ *  - Liveness probe is TTL-gated (only when a lease is past ttl) and reads the
+ *    in-memory running set — never a tmux exec (§3.5/M4).
+ *  - A holder on a DIFFERENT machine is NEVER judged dead from local session
+ *    absence (§3.5/M6); foreign-machine holder → fail-closed → treat as live.
+ *  - maxHold ceiling is liveness-discriminated: a DEAD/foreign-unverified holder
+ *    past the ceiling is CAS-seized + attention; a LIVE same-machine holder past
+ *    the ceiling is NOT seized — the caller escalates instead (§3.9/codex#3).
+ *  - Unreadable/corrupt/absent state file → fail-OPEN (treat as no lease) (§3.4/M10).
+ *  - dryRun leases carry dryRun:true; non-acquisition readers MUST ignore them (§5).
+ *
+ * This module is the STORE + the pure key-derivation helpers. The PreToolUse Bash
+ * hook (pr-hand-lease-guard.js) and the GET /pr-leases route consume it. Enforcement
+ * is the hook's (the real chokepoint where agent `git push` runs); SafeGitExecutor
+ * carries the same check as defense-in-depth for instar's own internal pushes.
+ */
+export type LeaseIntent = 'build' | 'rework' | 'merge';
+export type LeaseTombstoneStatus = 'released' | 'merged' | 'abandoned';
+export interface PrHandLeaseRecord {
+    /** STABLE logical owner — the conversation topic. Survives session respawn. */
+    holderTopicId: number;
+    /** Liveness-probe handle ONLY (tmux session name). NEVER the identity. */
+    holderSessionId: string;
+    /** Load-bearing for the never-falsely-dead rule (§3.5/M6). */
+    holderMachineId: string;
+    /** Secondary metadata once the PR exists; never the primary key. */
+    prNumber?: number | null;
+    intent: LeaseIntent;
+    acquiredAt: number;
+    renewedAt: number;
+    ttlMs: number;
+    maxHoldMs: number;
+    /** Observe-only soak: a dryRun lease MUST be ignored by all non-acquisition readers. */
+    dryRun?: boolean;
+    /** Set only on a tombstoned (released) record; a tombstone is never a live holder. */
+    tombstone?: {
+        status: LeaseTombstoneStatus;
+        at: number;
+    };
+}
+/** Derived liveness reported by GET /pr-leases — honest, computed, never the raw record. */
+export type DerivedLeaseLiveness = 'live' | 'stale-dead' | 'stale-ttl' | 'tombstoned' | 'foreign-machine';
+export interface LeaseEvalResult {
+    /** What the push chokepoint should do. */
+    decision: 'allow' | 'deny' | 'escalate';
+    reason: string;
+    holder?: PrHandLeaseRecord;
+}
+export interface PrHandLeaseDeps {
+    stateDir: string;
+    machineId: string;
+    /** Returns the tmux session names currently running (in-memory; no tmux exec). */
+    runningSessionNames: () => string[];
+    /** ms clock (injectable for tests). */
+    now?: () => number;
+    /** Emitted on a forced release / fail-open recurrence for the attention surface. */
+    onAttention?: (item: {
+        kind: string;
+        detail: string;
+    }) => void;
+    /** Structured audit sink — one row per acquire/renew/yield/auto-heal/release. */
+    onAudit?: (row: Record<string, unknown>) => void;
+}
+/**
+ * Canonicalize a `git push` command's destination ref to `refs/heads/<name>`.
+ * Two-tier (§3.1): explicit refspec / local @{push} fast path (no network);
+ * `git push --dry-run --porcelain` only for the ambiguous case, timeout-bounded.
+ * Returns null when no branch key is derivable (detached, tag, delete, resolver
+ * error/timeout) → the caller FAILS OPEN (does not gate).
+ */
+export declare function canonicalPushKey(command: string, cwd: string, opts?: {
+    execTimeoutMs?: number;
+}): string | null;
+export declare class PrHandLease {
+    private readonly d;
+    private readonly filePath;
+    private readonly lockPath;
+    private readonly now;
+    private failOpenCounts;
+    constructor(deps: PrHandLeaseDeps);
+    /** The path the BackupManager denylist must exclude (ephemeral, never restored). */
+    static stateFileRelPath(): string;
+    /**
+     * Evaluate a push against the lease for `key` (from canonicalPushKey).
+     * Returns the chokepoint decision. NEVER throws — any internal error resolves
+     * to allow (the hook's own-crash fail-open is the outer guarantee; this is the
+     * inner one).
+     */
+    evaluate(key: string, myTopicId: number, mySessionId: string): LeaseEvalResult;
+    /** Acquire or renew the lease for `key` for my (topic, session, machine). Atomic CAS under the lock. */
+    acquireOrRenew(key: string, holder: {
+        topicId: number;
+        sessionId: string;
+        intent?: LeaseIntent;
+        prNumber?: number | null;
+        dryRun?: boolean;
+    }): PrHandLeaseRecord;
+    /**
+     * Atomic-CAS takeover of a stale lease (§3.3/B3). Writes my record only if the
+     * on-disk record still matches the observed (holderTopicId, acquiredAt). Returns
+     * the new record on success, or null if another hand healed first (loser yields).
+     */
+    takeOverIfStale(key: string, observed: {
+        holderTopicId: number;
+        acquiredAt: number;
+    }, holder: {
+        topicId: number;
+        sessionId: string;
+        intent?: LeaseIntent;
+        prNumber?: number | null;
+        dryRun?: boolean;
+    }): PrHandLeaseRecord | null;
+    /** Release my lease (terminal status), tombstoned briefly to guard the re-grab race (§3.7). */
+    release(key: string, topicId: number, status: LeaseTombstoneStatus): void;
+    /** Read view for GET /pr-leases — each record + its DERIVED (honest) liveness. */
+    list(): Array<PrHandLeaseRecord & {
+        key: string;
+        liveness: DerivedLeaseLiveness;
+    }>;
+    private derivedLiveness;
+    /**
+     * Raw same-machine liveness probe: is the holder's tmux session in the
+     * in-memory running set? Same key at write + lookup (M-C). On probe error,
+     * fail toward LIVE (yield) — uncertainty about the probe must not seize a
+     * holder; the caller's past-ceiling path handles a persistently-wedged probe.
+     */
+    private isSessionRunning;
+    private acquireUnlocked;
+    /** Read with fail-OPEN on corrupt/absent (§3.4 step 1 / M10). */
+    private readAll;
+    private readAllUnlocked;
+    private pruneExpiredTombstones;
+    private persist;
+    /** One process-wide lock (matching ResumeQueue's single lockPath); 'wx' first-writer-wins. */
+    private withLock;
+    private recordFailOpen;
+    private attention;
+    private audit;
+}
+//# sourceMappingURL=PrHandLease.d.ts.map

package/dist/core/PrHandLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrHandLease.d.ts","sourceRoot":"","sources":["../../src/core/PrHandLease.ts"],"names":[],"mappings":"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"}

package/dist/core/PrHandLease.js

@@ -0,0 +1,448 @@
+/**
+ * PrHandLease — per-branch ownership lease so two of the agent's OWN concurrent
+ * sessions ("hands") cannot push competing commits to the same branch.
+ *
+ * Spec: docs/specs/parallel-hand-pr-lease.md (review-convergence + approved).
+ * Closes the push-competition cause of the 2026-06-15 PR #1183 merge thrash.
+ *
+ * Design anchors (from the converged spec):
+ *  - Identity = holderTopicId (stable across the constant session respawns);
+ *    holderSessionId is a LIVENESS-PROBE HANDLE ONLY, never the identity (§3.2/B2).
+ *  - ONE process-wide lock guards the single JSON file (matching ResumeQueue's
+ *    single lockPath); per-record compare-and-swap under that lock (§3.3/B3/M-D).
+ *  - Liveness probe is TTL-gated (only when a lease is past ttl) and reads the
+ *    in-memory running set — never a tmux exec (§3.5/M4).
+ *  - A holder on a DIFFERENT machine is NEVER judged dead from local session
+ *    absence (§3.5/M6); foreign-machine holder → fail-closed → treat as live.
+ *  - maxHold ceiling is liveness-discriminated: a DEAD/foreign-unverified holder
+ *    past the ceiling is CAS-seized + attention; a LIVE same-machine holder past
+ *    the ceiling is NOT seized — the caller escalates instead (§3.9/codex#3).
+ *  - Unreadable/corrupt/absent state file → fail-OPEN (treat as no lease) (§3.4/M10).
+ *  - dryRun leases carry dryRun:true; non-acquisition readers MUST ignore them (§5).
+ *
+ * This module is the STORE + the pure key-derivation helpers. The PreToolUse Bash
+ * hook (pr-hand-lease-guard.js) and the GET /pr-leases route consume it. Enforcement
+ * is the hook's (the real chokepoint where agent `git push` runs); SafeGitExecutor
+ * carries the same check as defense-in-depth for instar's own internal pushes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { SafeGitExecutor } from './SafeGitExecutor.js';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30m dead-holder backstop
+const DEFAULT_MAX_HOLD_MS = 90 * 60 * 1000; // 90m absolute ceiling
+const TOMBSTONE_WINDOW_MS = 5 * 1000; // ≤5s re-grab guard
+/**
+ * Canonicalize a `git push` command's destination ref to `refs/heads/<name>`.
+ * Two-tier (§3.1): explicit refspec / local @{push} fast path (no network);
+ * `git push --dry-run --porcelain` only for the ambiguous case, timeout-bounded.
+ * Returns null when no branch key is derivable (detached, tag, delete, resolver
+ * error/timeout) → the caller FAILS OPEN (does not gate).
+ */
+export function canonicalPushKey(command, cwd, opts) {
+    // Extract the git push invocation from a possibly-composite command
+    // (cd && git push, env-prefix, git -C path push, command git push, multiline).
+    // We do not try to defeat obfuscation/aliases/script-bodies — that is an
+    // accepted residual evasion of a cooperative guard (§2 non-goal).
+    const pushMatch = command.match(/\bgit\b[^\n;&|]*\bpush\b([^\n;&|]*)/);
+    if (!pushMatch)
+        return null;
+    const tail = pushMatch[1] ?? '';
+    // Ref deletion → no commit content → not gated.
+    if (/--delete\b/.test(tail) || /(^|\s):refs?\/|(^|\s):\S/.test(tail))
+        return null;
+    // -C <dir> overrides cwd for resolution.
+    const cMatch = command.match(/\bgit\b\s+(?:[^\n]*?\s)?-C\s+(\S+)/);
+    const effectiveCwd = cMatch ? resolveDir(cwd, stripQuotes(cMatch[1])) : cwd;
+    // Fast path: an explicit refspec token (last non-flag arg that isn't the remote).
+    const explicit = parseExplicitRefspec(tail);
+    if (explicit)
+        return `branch:${explicit}`;
+    // No explicit refspec → resolve the push destination locally via git's own
+    // ref resolution (no network — `rev-parse @{push}` reads config only). If that
+    // can't resolve it (no upstream / ambiguous push.default), FAIL-OPEN (no key):
+    // we never contact the remote from the push hot-path, and an unresolvable ref is
+    // the safe direction (the push proceeds). This deliberately drops the earlier
+    // remote-contacting `push --dry-run` fallback — it removes the hang surface the
+    // round-4 review flagged AND keeps the resolver off the network entirely.
+    const local = resolveLocalPushRef(effectiveCwd, opts?.execTimeoutMs);
+    return local ? `branch:${local}` : null;
+}
+function stripQuotes(s) {
+    return s.replace(/^['"]|['"]$/g, '');
+}
+function resolveDir(cwd, dir) {
+    return path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+}
+/** Parse `origin foo` / `origin HEAD:foo` / `origin HEAD:refs/heads/foo` → refs/heads/foo. */
+function parseExplicitRefspec(tail) {
+    // Drop flags; tokens left are [remote] [refspec...].
+    const tokens = tail.split(/\s+/).filter((t) => t && !t.startsWith('-'));
+    // remote is the first bare token; a refspec is any token containing ':' or a bare branch after the remote.
+    for (const tok of tokens) {
+        const t = stripQuotes(tok);
+        if (t.includes(':')) {
+            const dst = t.split(':')[1];
+            return normalizeHeadsRef(dst);
+        }
+    }
+    // bare `git push origin foo` → tokens [origin, foo]; foo is the destination branch.
+    if (tokens.length >= 2) {
+        return normalizeHeadsRef(stripQuotes(tokens[1]));
+    }
+    return null;
+}
+function normalizeHeadsRef(ref) {
+    if (!ref)
+        return null;
+    if (ref.startsWith('refs/heads/'))
+        return ref;
+    if (ref.startsWith('refs/'))
+        return null; // tag/non-heads → not gated
+    if (ref === 'HEAD')
+        return null; // unresolved here; local resolver handles it
+    return `refs/heads/${ref}`;
+}
+function resolveLocalPushRef(cwd, timeoutMs) {
+    try {
+        const out = SafeGitExecutor.readSync(['rev-parse', '--symbolic-full-name', '@{push}'], {
+            cwd,
+            operation: 'pr-hand-lease canonical-key resolve',
+            encoding: 'utf-8',
+            timeout: timeoutMs ?? 2000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        }).trim();
+        if (out.startsWith('refs/remotes/')) {
+            // refs/remotes/<remote>/<branch> → refs/heads/<branch>
+            const parts = out.split('/');
+            const branch = parts.slice(3).join('/');
+            return branch ? `refs/heads/${branch}` : null;
+        }
+        if (out.startsWith('refs/heads/'))
+            return out;
+        return null;
+    }
+    catch {
+        // @silent-fallback-ok: no upstream / unresolvable push.default → no key → caller FAILS OPEN
+        // (the push proceeds). We never contact the remote from the push hot-path.
+        return null;
+    }
+}
+export class PrHandLease {
+    d;
+    filePath;
+    lockPath;
+    now;
+    failOpenCounts = new Map();
+    constructor(deps) {
+        this.d = deps;
+        const root = path.join(deps.stateDir, 'state');
+        this.filePath = path.join(root, 'pr-hand-leases.json');
+        this.lockPath = path.join(root, 'pr-hand-leases.lock');
+        this.now = deps.now ?? (() => Date.now());
+    }
+    /** The path the BackupManager denylist must exclude (ephemeral, never restored). */
+    static stateFileRelPath() {
+        return 'state/pr-hand-leases.json';
+    }
+    /**
+     * Evaluate a push against the lease for `key` (from canonicalPushKey).
+     * Returns the chokepoint decision. NEVER throws — any internal error resolves
+     * to allow (the hook's own-crash fail-open is the outer guarantee; this is the
+     * inner one).
+     */
+    evaluate(key, myTopicId, mySessionId) {
+        try {
+            const all = this.readAll(); // fail-open on corrupt → {}
+            const rec = all[key];
+            if (!rec || rec.tombstone) {
+                return { decision: 'allow', reason: rec?.tombstone ? 'tombstoned-free' : 'no-lease' };
+            }
+            if (rec.holderTopicId === myTopicId) {
+                return { decision: 'allow', reason: 'own-topic', holder: rec };
+            }
+            // dryRun leases never block a different hand (observe-only).
+            if (rec.dryRun) {
+                return { decision: 'allow', reason: 'foreign-dryrun-ignored', holder: rec };
+            }
+            const t = this.now();
+            const sameMachine = rec.holderMachineId === this.d.machineId;
+            const ttlExpired = t - rec.renewedAt > rec.ttlMs;
+            const pastCeiling = t - rec.acquiredAt > rec.maxHoldMs;
+            // Ceiling override FIRST (§3.9 precedence — overrides foreign-machine conservatism).
+            if (pastCeiling) {
+                if (sameMachine && this.isSessionRunning(rec)) {
+                    // LIVE same-machine holder past ceiling → escalate, do NOT seize (codex#3/§3.9).
+                    return { decision: 'escalate', reason: 'live-holder-past-ceiling', holder: rec };
+                }
+                // DEAD same-machine OR foreign-machine-unverified past ceiling → stale → caller seizes (+attention).
+                return { decision: 'allow', reason: 'stale-past-ceiling', holder: rec };
+            }
+            // Within ceiling:
+            if (!ttlExpired) {
+                // TTL-gate: a fresh lease is live without probing.
+                return { decision: 'deny', reason: 'live-foreign-lease', holder: rec };
+            }
+            if (!sameMachine) {
+                // Foreign-machine holder within ceiling, past TTL → NEVER judged dead from local
+                // session absence → yield (§3.5/M6).
+                return { decision: 'deny', reason: 'foreign-machine-within-ceiling', holder: rec };
+            }
+            // Same-machine, TTL-expired → probe the in-memory running set.
+            if (this.isSessionRunning(rec)) {
+                return { decision: 'deny', reason: 'live-foreign-lease', holder: rec };
+            }
+            return { decision: 'allow', reason: 'stale-dead', holder: rec };
+        }
+        catch (err) {
+            // Inner fail-open — never block on an internal error.
+            this.audit({ event: 'evaluate-error', key, error: String(err) });
+            return { decision: 'allow', reason: 'eval-error-failopen' };
+        }
+    }
+    /** Acquire or renew the lease for `key` for my (topic, session, machine). Atomic CAS under the lock. */
+    acquireOrRenew(key, holder) {
+        return this.withLock(() => {
+            const all = this.readAllUnlocked();
+            const existing = all[key];
+            const t = this.now();
+            if (existing && !existing.tombstone && existing.holderTopicId === holder.topicId) {
+                existing.renewedAt = t;
+                existing.holderSessionId = holder.sessionId;
+                if (holder.intent)
+                    existing.intent = holder.intent;
+                if (holder.prNumber !== undefined)
+                    existing.prNumber = holder.prNumber;
+                if (holder.dryRun !== undefined)
+                    existing.dryRun = holder.dryRun;
+                this.persist(all);
+                this.audit({ event: 'renew', key, topicId: holder.topicId, dryRun: !!holder.dryRun });
+                return existing;
+            }
+            const rec = {
+                holderTopicId: holder.topicId,
+                holderSessionId: holder.sessionId,
+                holderMachineId: this.d.machineId,
+                prNumber: holder.prNumber ?? null,
+                intent: holder.intent ?? 'build',
+                acquiredAt: t,
+                renewedAt: t,
+                ttlMs: DEFAULT_TTL_MS,
+                maxHoldMs: DEFAULT_MAX_HOLD_MS,
+                dryRun: holder.dryRun || undefined,
+            };
+            all[key] = rec;
+            this.persist(all);
+            this.audit({ event: 'acquire', key, topicId: holder.topicId, dryRun: !!holder.dryRun });
+            return rec;
+        });
+    }
+    /**
+     * Atomic-CAS takeover of a stale lease (§3.3/B3). Writes my record only if the
+     * on-disk record still matches the observed (holderTopicId, acquiredAt). Returns
+     * the new record on success, or null if another hand healed first (loser yields).
+     */
+    takeOverIfStale(key, observed, holder) {
+        return this.withLock(() => {
+            const all = this.readAllUnlocked();
+            const cur = all[key];
+            if (!cur || cur.tombstone) {
+                // Already free → acquire fresh.
+                return this.acquireUnlocked(all, key, holder);
+            }
+            // CAS precondition: the record must be exactly the one we observed as stale.
+            if (cur.holderTopicId !== observed.holderTopicId || cur.acquiredAt !== observed.acquiredAt) {
+                this.audit({ event: 'takeover-cas-lost', key });
+                return null; // another hand healed first → yield
+            }
+            const forcedRelease = this.now() - cur.acquiredAt > cur.maxHoldMs;
+            const rec = this.acquireUnlocked(all, key, holder);
+            this.audit({
+                event: forcedRelease ? 'auto-heal-ceiling' : 'auto-heal-dead',
+                key,
+                priorTopicId: observed.holderTopicId,
+                priorMachineId: cur.holderMachineId,
+            });
+            if (forcedRelease || cur.holderMachineId !== this.d.machineId) {
+                this.attention('pr-lease-forced-release', `Branch ${key} lease force-released from topic ${observed.holderTopicId} (machine ${cur.holderMachineId}).`);
+            }
+            return rec;
+        });
+    }
+    /** Release my lease (terminal status), tombstoned briefly to guard the re-grab race (§3.7). */
+    release(key, topicId, status) {
+        this.withLock(() => {
+            const all = this.readAllUnlocked();
+            const cur = all[key];
+            if (cur && cur.holderTopicId === topicId && !cur.tombstone) {
+                cur.tombstone = { status, at: this.now() };
+                this.persist(all);
+                this.audit({ event: 'release', key, topicId, status });
+            }
+            return undefined;
+        });
+    }
+    /** Read view for GET /pr-leases — each record + its DERIVED (honest) liveness. */
+    list() {
+        const all = this.readAll();
+        const out = [];
+        for (const [key, rec] of Object.entries(all)) {
+            out.push({ ...rec, key, liveness: this.derivedLiveness(rec) });
+        }
+        return out;
+    }
+    // ---- internals ----
+    derivedLiveness(rec) {
+        if (rec.tombstone)
+            return 'tombstoned';
+        if (rec.holderMachineId !== this.d.machineId)
+            return 'foreign-machine';
+        const ttlExpired = this.now() - rec.renewedAt > rec.ttlMs;
+        if (!ttlExpired)
+            return 'live';
+        return this.isSessionRunning(rec) ? 'live' : 'stale-dead';
+    }
+    /**
+     * Raw same-machine liveness probe: is the holder's tmux session in the
+     * in-memory running set? Same key at write + lookup (M-C). On probe error,
+     * fail toward LIVE (yield) — uncertainty about the probe must not seize a
+     * holder; the caller's past-ceiling path handles a persistently-wedged probe.
+     */
+    isSessionRunning(rec) {
+        try {
+            return this.d.runningSessionNames().includes(rec.holderSessionId);
+        }
+        catch {
+            // @silent-fallback-ok: probe unavailable → treat live (yield), bounded by the ceiling override.
+            return true;
+        }
+    }
+    acquireUnlocked(all, key, holder) {
+        const t = this.now();
+        const rec = {
+            holderTopicId: holder.topicId,
+            holderSessionId: holder.sessionId,
+            holderMachineId: this.d.machineId,
+            prNumber: holder.prNumber ?? null,
+            intent: holder.intent ?? 'build',
+            acquiredAt: t,
+            renewedAt: t,
+            ttlMs: DEFAULT_TTL_MS,
+            maxHoldMs: DEFAULT_MAX_HOLD_MS,
+            dryRun: holder.dryRun || undefined,
+        };
+        all[key] = rec;
+        this.persist(all);
+        return rec;
+    }
+    /** Read with fail-OPEN on corrupt/absent (§3.4 step 1 / M10). */
+    readAll() {
+        try {
+            if (!fs.existsSync(this.filePath))
+                return {};
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return this.pruneExpiredTombstones(parsed);
+        }
+        catch (err) {
+            // @silent-fallback-ok: corrupt/torn/absent lease file → fail-OPEN (treat as no lease,
+            // the push proceeds — a missing lease must NEVER block all pushes). NOT silent:
+            // recordFailOpen() logs every occurrence and raises an attention item on recurrence.
+            this.recordFailOpen('readAll');
+            return {};
+        }
+    }
+    readAllUnlocked() {
+        return this.readAll();
+    }
+    pruneExpiredTombstones(all) {
+        const t = this.now();
+        for (const [key, rec] of Object.entries(all)) {
+            if (rec.tombstone && t - rec.tombstone.at > TOMBSTONE_WINDOW_MS)
+                delete all[key];
+        }
+        return all;
+    }
+    persist(all) {
+        const dir = path.dirname(this.filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = `${this.filePath}.${process.pid}.tmp`;
+        const fd = fs.openSync(tmp, 'w');
+        try {
+            fs.writeSync(fd, JSON.stringify(all, null, 2));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, this.filePath); // atomic swap — readers never see a torn file
+    }
+    /** One process-wide lock (matching ResumeQueue's single lockPath); 'wx' first-writer-wins. */
+    withLock(fn) {
+        const dir = path.dirname(this.lockPath);
+        fs.mkdirSync(dir, { recursive: true });
+        const deadline = this.now() + 5000;
+        // simple spin with O_EXCL; the critical section is a sub-ms file rewrite.
+        for (;;) {
+            let fd = null;
+            try {
+                fd = fs.openSync(this.lockPath, 'wx');
+                fs.writeSync(fd, JSON.stringify({ pid: process.pid, host: os.hostname(), at: this.now() }));
+                fs.closeSync(fd);
+                fd = null;
+                try {
+                    return fn();
+                }
+                finally {
+                    try {
+                        SafeFsExecutor.safeUnlinkSync(this.lockPath, { operation: 'PrHandLease lock release' });
+                    }
+                    catch { /* @silent-fallback-ok: lock cleanup best-effort */ }
+                }
+            }
+            catch (err) {
+                if (fd !== null) {
+                    try {
+                        fs.closeSync(fd);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (err?.code === 'EEXIST') {
+                    // Stale lock recovery: if the lock is older than the deadline window, steal it.
+                    if (this.now() > deadline) {
+                        try {
+                            SafeFsExecutor.safeUnlinkSync(this.lockPath, { operation: 'PrHandLease stale-lock steal' });
+                        }
+                        catch { /* ignore */ }
+                        continue;
+                    }
+                    continue; // retry
+                }
+                throw err;
+            }
+        }
+    }
+    recordFailOpen(where) {
+        const n = (this.failOpenCounts.get(where) ?? 0) + 1;
+        this.failOpenCounts.set(where, n);
+        this.audit({ event: 'fail-open', where, count: n });
+        if (n >= 3) {
+            this.attention('pr-lease-failopen', `pr-hand-leases.json repeatedly unreadable (${n}x at ${where}) — lease protection degraded; check the state file.`);
+        }
+    }
+    attention(kind, detail) {
+        try {
+            this.d.onAttention?.({ kind, detail });
+        }
+        catch { /* @silent-fallback-ok */ }
+    }
+    audit(row) {
+        try {
+            this.d.onAudit?.({ ...row, ts: new Date(this.now()).toISOString() });
+        }
+        catch { /* @silent-fallback-ok */ }
+    }
+}
+//# sourceMappingURL=PrHandLease.js.map

package/dist/core/PrHandLease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrHandLease.js","sourceRoot":"","sources":["../../src/core/PrHandLease.ts"],"names":[],"mappings":"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"}

package/dist/core/devGatedFeatures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devGatedFeatures.d.ts","sourceRoot":"","sources":["../../src/core/devGatedFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EAqT/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,cAAc,GACd,gBAAgB,GAChB,sBAAsB,GACtB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,oBAAoB,EAAE,iBAAiB,EAuHnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAO5E"}
+{"version":3,"file":"devGatedFeatures.d.ts","sourceRoot":"","sources":["../../src/core/devGatedFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA2T/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,cAAc,GACd,gBAAgB,GAChB,sBAAsB,GACtB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,oBAAoB,EAAE,iBAAiB,EAuHnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAO5E"}

package/dist/core/devGatedFeatures.js

@@ -120,6 +120,12 @@ export const DEV_GATED_FEATURES = [
         description: 'Playwright profile↔accounts registry + boot awareness + activate.',
         justification: 'Stores vault secret NAMES only (never values) + browser-profile metadata; reads are advisory signal; the only destructive op (activate: MCP-config rewrite + session restart) ships dryRun:true and is reversible; dev-dogfooded.',
     },
+    {
+        name: 'prHandLease',
+        configPath: 'monitoring.prHandLease.enabled',
+        description: 'Per-branch PR-push lease so two of the agent’s own concurrent sessions can’t push competing commits to the same branch (spec: parallel-hand-pr-lease).',
+        justification: 'Ships dryRun:true (the dry-run canary): on a dev agent the PreToolUse hook + the /pr-leases/evaluate route run the FULL decision loop and AUDIT every would-deny, but the route returns decision:allow (wouldDeny flag) while dryRun holds, so NO push is ever blocked until a deliberate dryRun:false. Coordinates the agent’s OWN cooperating hands only — never authority over a principal, never external egress; every uncertainty (corrupt state, server down, hook crash, no branch key) fails OPEN (allows the push). No spend, no destructive action while the canary holds. Same dogfooding posture as topicProfiles / credentialRepointing.',
+    },
     // ── multi-machine seamlessness coherence layers (WS3 / WS1.3 / WS4.1 / WS4.3),
     //    MOVED from hardcoded `false` in ConfigDefaults on 2026-06-13 per operator
     //    directive topic 13481 ("NOTHING should ship dark on development agents —