brainclaw 1.8.0 → 1.9.1

package/dist/core/claims.js

@@ -1,17 +1,19 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import path from 'node:path';
 import { ClaimSchema } from './schema.js';
 import { resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 import { loadConfig } from './config.js';
-import { createWorktree, resetWorktreeToRef } from './worktree.js';
+import { createWorktree, resetWorktreeToRef, removeWorktree, sanitizeBranchComponent } from './worktree.js';
 import { appendAuditEntry } from './audit.js';
 import { refreshLiveCompanions } from '../commands/export.js';
 import { loadSessionById } from './identity.js';
 import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
+import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
 /** Parse duration string like '4h', '30m' to ms. */
 function parseTtl(value) {
     const match = /^(\d+)([mhd])$/i.exec(value.trim());
@@ -28,35 +30,75 @@ function parseTtl(value) {
 function claimsDir(cwd, mode = 'read') {
     return resolveEntityDir('claims', cwd ?? process.cwd(), mode);
 }
+function claimDirs(cwd) {
+    const effectiveCwd = cwd ?? process.cwd();
+    return Array.from(new Set([
+        claimsDir(effectiveCwd, 'write'),
+        claimsDir(effectiveCwd, 'read'),
+    ]));
+}
 export function ensureClaimsDir(cwd) {
     const dir = claimsDir(cwd, 'write');
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
-function claimStore(cwd) {
+function claimStoreForDir(dirPath) {
     return new JsonStore({
-        dirPath: claimsDir(cwd, 'read'),
+        dirPath,
         documentType: 'claim',
         getId: (claim) => claim.id,
         sort: (a, b) => a.created_at.localeCompare(b.created_at),
     });
 }
-export function saveClaim(claim, cwd) {
-    mutate({ cwd }, () => {
-        ensureClaimsDir(cwd);
-        const writeStore = new JsonStore({
-            dirPath: claimsDir(cwd, 'write'),
-            documentType: 'claim',
-            getId: (c) => c.id,
-            sort: (a, b) => a.created_at.localeCompare(b.created_at),
-        });
-        writeStore.save(ClaimSchema.parse(claim));
-        // Auto-refresh live companions after claim changes (non-fatal)
+function writeClaimStore(cwd) {
+    return claimStoreForDir(claimsDir(cwd, 'write'));
+}
+function loadClaimFromAnyDir(id, cwd) {
+    for (const dirPath of claimDirs(cwd)) {
+        const store = claimStoreForDir(dirPath);
+        if (store.exists(id))
+            return store.load(id);
+    }
+    throw new Error(`claim '${id}' not found`);
+}
+function saveClaimUnlocked(claim, cwd, options) {
+    ensureClaimsDir(cwd);
+    const store = writeClaimStore(cwd);
+    const parsed = ClaimSchema.parse(claim);
+    // pln#568 (I2): journal the post-image BEFORE the projection write, so a
+    // crash can only leave the journal ahead of the projection, never behind.
+    const created = !store.exists(parsed.id);
+    emitRegistryPostImage('claim', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
+    registryFaultPoint('after_registry_journal');
+    store.save(parsed);
+    const writeDir = claimsDir(cwd, 'write');
+    for (const dirPath of claimDirs(cwd)) {
+        if (dirPath === writeDir)
+            continue;
+        const legacyPath = path.join(dirPath, `${claim.id}.json`);
+        try {
+            if (fs.existsSync(legacyPath))
+                fs.unlinkSync(legacyPath);
+        }
+        catch {
+            // Best effort: listClaims() reads both dirs, so a missed cleanup remains visible.
+        }
+    }
+    // Auto-refresh live companions after claim changes (non-fatal). Sweep loops
+    // pass refreshCompanions:false and refresh ONCE after the loop — review
+    // follow-up O5: a per-save refresh inside the critical section compounded an
+    // O(store) cost on every iteration.
+    if (options?.refreshCompanions !== false) {
         try {
             refreshLiveCompanions(cwd);
         }
         catch { /* best-effort */ }
+    }
+}
+export function saveClaim(claim, cwd) {
+    mutate({ cwd }, () => {
+        saveClaimUnlocked(claim, cwd);
     });
 }
 /**
@@ -84,22 +126,63 @@ export function acquireClaimScope(input, cwd) {
             plan_id: input.plan_id,
             model: input.model,
         };
-        saveClaim(claim, cwd);
+        saveClaimUnlocked(claim, cwd);
         return { acquired: true, claim };
     });
 }
 export function loadClaim(id, cwd) {
-    return claimStore(cwd).load(id);
+    return loadClaimFromAnyDir(id, cwd);
 }
 export function listClaims(cwd) {
-    return claimStore(cwd).list();
+    const byId = new Map();
+    for (const dirPath of claimDirs(cwd)) {
+        for (const claim of claimStoreForDir(dirPath).list()) {
+            if (!byId.has(claim.id))
+                byId.set(claim.id, claim);
+        }
+    }
+    return Array.from(byId.values()).sort((a, b) => a.created_at.localeCompare(b.created_at));
 }
-export function releaseClaim(id, cwd) {
-    const claim = loadClaim(id, cwd);
-    claim.status = 'released';
-    claim.released_at = nowISO();
-    saveClaim(claim, cwd);
-    return claim;
+function assertReleaseOwnership(claim, auth) {
+    if (!auth)
+        return { overrideUsed: false };
+    const ownerMatches = (auth.session_id !== undefined && claim.session_id !== undefined && auth.session_id === claim.session_id)
+        || (auth.agent_id !== undefined && claim.agent_id !== undefined && auth.agent_id === claim.agent_id)
+        || (auth.agent !== undefined && claim.agent === auth.agent);
+    if (ownerMatches)
+        return { overrideUsed: false };
+    if (auth.override)
+        return { overrideUsed: true };
+    throw new Error(`claim '${claim.id}' is held by '${claim.agent}'${claim.session_id ? ` (session ${claim.session_id})` : ''}; `
+        + `caller '${auth.agent ?? auth.agent_id ?? auth.session_id ?? 'unknown'}' does not own it. `
+        + 'Coordinator-level callers may release with override.');
+}
+function auditReleaseOverride(claim, auth, cwd) {
+    appendAuditEntry({
+        actor: auth.agent ?? 'coordinator',
+        actor_id: auth.agent_id,
+        action: 'release_claim',
+        item_id: claim.id,
+        item_type: 'claim',
+        scope: claim.scope,
+        session_id: auth.session_id,
+        after: { ownership_override: true, claim_owner: claim.agent },
+    }, cwd);
+}
+export function releaseClaim(id, cwd, auth) {
+    let overrideUsed = false;
+    const released = mutate({ cwd }, () => {
+        const claim = loadClaim(id, cwd);
+        overrideUsed = assertReleaseOwnership(claim, auth).overrideUsed;
+        claim.status = 'released';
+        claim.released_at = nowISO();
+        saveClaimUnlocked(claim, cwd);
+        return claim;
+    });
+    if (overrideUsed && auth) {
+        auditReleaseOverride(released, auth, cwd);
+    }
+    return released;
 }
 /**
  * Release a claim and optionally cascade the status to its linked plan.
@@ -113,83 +196,95 @@ export function releaseClaim(id, cwd) {
  * Emits `plan_cascade_to_done` runtime event when auto-transitioning to done.
  */
 export function releaseClaimWithCascade(id, options = {}) {
-    const { planStatus, cwd } = options;
-    // Release the claim (idempotent: already-released claims are returned as-is)
-    const claim = loadClaim(id, cwd);
-    if (claim.status === 'released') {
+    const { planStatus, cwd, auth } = options;
+    let overrideUsed = false;
+    const result = mutate({ cwd }, () => {
+        // Release the claim (idempotent: already-released claims are returned as-is)
+        const claim = loadClaim(id, cwd);
+        if (claim.status === 'released') {
+            return { claim, planTransitioned: false };
+        }
+        overrideUsed = assertReleaseOwnership(claim, auth).overrideUsed;
+        claim.status = 'released';
+        claim.released_at = nowISO();
+        saveClaimUnlocked(claim, cwd);
+        // No cascade requested or no linked plan
+        if (!planStatus || !claim.plan_id) {
+            return { claim, planTransitioned: false };
+        }
+        const state = loadState(cwd);
+        const plan = state.plan_items.find((item) => item.id === claim.plan_id);
+        if (!plan) {
+            return { claim, planTransitioned: false };
+        }
+        const ts = nowISO();
+        if (planStatus === 'blocked') {
+            // Always propagate blocked status to plan
+            plan.status = 'blocked';
+            plan.updated_at = ts;
+            persistState(state, cwd);
+            return { claim, planTransitioned: true, planId: plan.id, newPlanStatus: 'blocked' };
+        }
+        if (planStatus === 'done') {
+            // Count OTHER active claims on the same plan (current claim already released above)
+            const otherActive = listClaims(cwd).filter((c) => c.status === 'active' && c.plan_id === claim.plan_id && c.id !== id);
+            if (otherActive.length > 0) {
+                const planWarning = `Plan has ${otherActive.length} other active claim(s); staying in_progress`;
+                return {
+                    claim,
+                    planTransitioned: false,
+                    planWarning,
+                    planId: plan.id,
+                    newPlanStatus: plan.status,
+                    otherActiveClaimsCount: otherActive.length,
+                };
+            }
+            // Last active claim released → auto-transition plan to done
+            plan.status = 'done';
+            if (!plan.completed_at)
+                plan.completed_at = ts;
+            plan.updated_at = ts;
+            persistState(state, cwd);
+            return { claim, planTransitioned: true, planId: plan.id, newPlanStatus: 'done' };
+        }
+        // planStatus='todo', 'in_progress', or other — no cascade
         return { claim, planTransitioned: false };
-    }
-    claim.status = 'released';
-    claim.released_at = nowISO();
-    saveClaim(claim, cwd);
+    });
     appendAuditEntry({
-        actor: claim.agent,
-        actor_id: claim.agent_id,
+        actor: result.claim.agent,
+        actor_id: result.claim.agent_id,
         action: 'release_claim',
         item_id: id,
         item_type: 'claim',
-        scope: claim.scope,
-        session_id: claim.session_id,
-        host_id: claim.host_id,
+        scope: result.claim.scope,
+        session_id: result.claim.session_id,
+        host_id: result.claim.host_id,
     }, cwd);
-    // No cascade requested or no linked plan
-    if (!planStatus || !claim.plan_id) {
-        return { claim, planTransitioned: false };
+    if (overrideUsed && auth) {
+        auditReleaseOverride(result.claim, auth, cwd);
     }
-    const state = loadState(cwd);
-    const plan = state.plan_items.find((item) => item.id === claim.plan_id);
-    if (!plan) {
-        return { claim, planTransitioned: false };
-    }
-    const ts = nowISO();
-    if (planStatus === 'blocked') {
-        // Always propagate blocked status to plan
-        plan.status = 'blocked';
-        plan.updated_at = ts;
-        persistState(state, cwd);
-        return { claim, planTransitioned: true, planId: plan.id, newPlanStatus: 'blocked' };
+    if (result.planWarning && result.planId) {
+        appendAuditEntry({
+            actor: result.claim.agent,
+            action: 'update',
+            item_id: result.planId,
+            item_type: 'plan',
+            after: { cascade_blocked: true, reason: result.planWarning },
+        }, cwd);
     }
-    if (planStatus === 'done') {
-        // Count OTHER active claims on the same plan (current claim already released above)
-        const otherActive = listClaims(cwd).filter((c) => c.status === 'active' && c.plan_id === claim.plan_id && c.id !== id);
-        if (otherActive.length > 0) {
-            const planWarning = `Plan has ${otherActive.length} other active claim(s); staying in_progress`;
-            appendAuditEntry({
-                actor: claim.agent,
-                action: 'update',
-                item_id: plan.id,
-                item_type: 'plan',
-                after: { cascade_blocked: true, reason: planWarning },
-            }, cwd);
-            return {
-                claim,
-                planTransitioned: false,
-                planWarning,
-                planId: plan.id,
-                newPlanStatus: plan.status,
-                otherActiveClaimsCount: otherActive.length,
-            };
-        }
-        // Last active claim released → auto-transition plan to done
-        plan.status = 'done';
-        if (!plan.completed_at)
-            plan.completed_at = ts;
-        plan.updated_at = ts;
-        persistState(state, cwd);
+    if (result.newPlanStatus === 'done' && result.planId) {
         createRuntimeEvent({
-            agent: claim.agent,
-            agent_id: claim.agent_id,
+            agent: result.claim.agent,
+            agent_id: result.claim.agent_id,
             event_type: 'plan_cascade_to_done',
             claim_id: id,
-            plan_id: plan.id,
-            session_id: claim.session_id,
-            host_id: claim.host_id,
-            text: `Plan ${plan.id} auto-transitioned to done — last active claim released by ${claim.agent}`,
+            plan_id: result.planId,
+            session_id: result.claim.session_id,
+            host_id: result.claim.host_id,
+            text: `Plan ${result.planId} auto-transitioned to done — last active claim released by ${result.claim.agent}`,
         }, cwd);
-        return { claim, planTransitioned: true, planId: plan.id, newPlanStatus: 'done' };
     }
-    // planStatus='todo', 'in_progress', or other — no cascade
-    return { claim, planTransitioned: false };
+    return result;
 }
 export function generateClaimId() {
     const rand = crypto.randomBytes(4).toString('hex');
@@ -202,19 +297,26 @@ export function isClaimExpired(claim) {
 }
 /** Mark active claims past their expires_at as released. Returns count of expired claims. */
 export function expireStaleActiveClaims(cwd) {
-    const store = claimStore(cwd);
-    const all = store.list();
-    let count = 0;
-    const now = nowISO();
-    for (const claim of all) {
-        if (claim.status === 'active' && isClaimExpired(claim)) {
-            claim.status = 'released';
-            claim.released_at = now;
-            store.save(claim);
-            count++;
+    return mutate({ cwd }, () => {
+        const all = listClaims(cwd);
+        let count = 0;
+        const now = nowISO();
+        for (const claim of all) {
+            if (claim.status === 'active' && isClaimExpired(claim)) {
+                claim.status = 'released';
+                claim.released_at = now;
+                saveClaimUnlocked(claim, cwd, { refreshCompanions: false });
+                count++;
+            }
         }
-    }
-    return count;
+        if (count > 0) {
+            try {
+                refreshLiveCompanions(cwd);
+            }
+            catch { /* best-effort */ }
+        }
+        return count;
+    });
 }
 /** Default stale threshold: 24 hours. */
 const DEFAULT_STALE_HOURS = 24;
@@ -369,33 +471,40 @@ export function isClaimStale(claim, thresholdHours, cwd) {
 export function releaseStaleClaimsFromOtherAgents(currentAgent, cwd, currentSessionId) {
     const config = loadConfig(cwd);
     const thresholdHours = config.claims?.auto_release_after_hours ?? DEFAULT_STALE_HOURS;
-    const store = claimStore(cwd);
-    const all = store.list();
-    const now = nowISO();
-    const released = [];
-    const warned = [];
-    for (const claim of all) {
-        if (claim.status !== 'active')
-            continue;
-        // Session-aware skip: if the caller names its current session, only that
-        // session's claims are off-limits. Otherwise fall back to the legacy
-        // "skip same agent" rule.
-        if (currentSessionId) {
-            if (claim.session_id === currentSessionId)
+    return mutate({ cwd }, () => {
+        const all = listClaims(cwd);
+        const now = nowISO();
+        const released = [];
+        const warned = [];
+        for (const claim of all) {
+            if (claim.status !== 'active')
+                continue;
+            // Session-aware skip: if the caller names its current session, only that
+            // session's claims are off-limits. Otherwise fall back to the legacy
+            // "skip same agent" rule.
+            if (currentSessionId) {
+                if (claim.session_id === currentSessionId)
+                    continue;
+            }
+            else if (claim.agent === currentAgent) {
+                continue;
+            }
+            const { status } = assessClaimLiveness(claim, { thresholdHours, cwd });
+            if (status === 'live' || status === 'young')
                 continue;
+            claim.status = 'released';
+            claim.released_at = now;
+            saveClaimUnlocked(claim, cwd, { refreshCompanions: false });
+            released.push(claim);
         }
-        else if (claim.agent === currentAgent) {
-            continue;
+        if (released.length > 0) {
+            try {
+                refreshLiveCompanions(cwd);
+            }
+            catch { /* best-effort */ }
         }
-        const { status } = assessClaimLiveness(claim, { thresholdHours, cwd });
-        if (status === 'live' || status === 'young')
-            continue;
-        claim.status = 'released';
-        claim.released_at = now;
-        store.save(claim);
-        released.push(claim);
-    }
-    return { released, warned };
+        return { released, warned };
+    });
 }
 /**
  * Create a coordinator-owned claim with worktree isolation.
@@ -445,8 +554,11 @@ export function createCoordinatorClaim(options) {
     const claimId = generateClaimId();
     let worktreePath;
     let worktreeWarning;
-    // Create isolated worktree (matching bclaw_claim MCP handler behavior)
-    const branchSlug = options.scope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
+    // Create isolated worktree (matching bclaw_claim MCP handler behavior).
+    // can_45316d5c: the slug must be a valid git ref component — scopes like
+    // `.github/workflows` previously produced `feat/.github-…` (leading dot),
+    // which git rejects and the whole spawn failed.
+    const branchSlug = sanitizeBranchComponent(options.scope);
     const worktreeBranch = `feat/${branchSlug}`;
     try {
         worktreePath = createWorktree(options.cwd, worktreeBranch, {
@@ -463,24 +575,58 @@ export function createCoordinatorClaim(options) {
     catch (err) {
         worktreeWarning = `Worktree creation failed: ${err instanceof Error ? err.message : String(err)}`;
     }
-    saveClaim({
-        id: claimId,
-        agent: options.agent,
-        scope: options.scope,
-        description: options.description,
-        plan_id: options.planId,
-        created_at: nowISO(),
-        status: 'active',
-        worktree_path: worktreePath,
-    }, options.cwd);
-    appendAuditEntry({
-        actor: options.dispatcherAgent,
-        action: 'claim',
-        item_id: claimId,
-        item_type: 'claim',
-        scope: options.scope,
-    }, options.cwd);
-    return { claimId, worktreePath, worktreeWarning, reusedExisting: false };
+    const result = mutate({ cwd: options.cwd }, () => {
+        const racedScopeClaim = listClaims(options.cwd).find((claim) => claim.status === 'active' && claim.scope === options.scope);
+        if (racedScopeClaim) {
+            if (racedScopeClaim.agent === options.agent) {
+                return {
+                    claimId: racedScopeClaim.id,
+                    worktreePath: racedScopeClaim.worktree_path,
+                    worktreeWarning,
+                    reusedExisting: true,
+                };
+            }
+            return {
+                claimId: racedScopeClaim.id,
+                worktreePath: racedScopeClaim.worktree_path,
+                reusedExisting: true,
+                scopeConflict: true,
+                conflictAgent: racedScopeClaim.agent,
+            };
+        }
+        saveClaimUnlocked({
+            id: claimId,
+            agent: options.agent,
+            scope: options.scope,
+            description: options.description,
+            plan_id: options.planId,
+            created_at: nowISO(),
+            status: 'active',
+            worktree_path: worktreePath,
+        }, options.cwd);
+        return { claimId, worktreePath, worktreeWarning, reusedExisting: false };
+    });
+    // Review follow-up O1 (lop_e2d566765b8b4ce3): when the in-lock re-check finds
+    // a raced claim, the worktree created moments earlier (outside the lock) is
+    // orphaned — nobody would ever remove it. Decision: delete it (it is seconds
+    // old and contains only birth artifacts; a reuse-pool is not worth the
+    // bookkeeping). Best-effort and outside the critical section.
+    if (result.reusedExisting && worktreePath && worktreePath !== result.worktreePath) {
+        try {
+            removeWorktree(options.cwd, worktreePath, { force: true });
+        }
+        catch { /* best-effort GC — a leftover dir is caught by worktree clean */ }
+    }
+    if (!result.reusedExisting && !result.scopeConflict) {
+        appendAuditEntry({
+            actor: options.dispatcherAgent,
+            action: 'claim',
+            item_id: result.claimId,
+            item_type: 'claim',
+            scope: options.scope,
+        }, options.cwd);
+    }
+    return result;
 }
 // ── Claim lifecycle helpers for multi-instance dispatch ────
 /**
@@ -488,15 +634,32 @@ export function createCoordinatorClaim(options) {
  * Called by the dispatcher after sending the inbox message.
  */
 export function attachAssignmentMessageToClaim(claimId, messageId, cwd) {
-    const claim = loadClaim(claimId, cwd);
-    claim.assignment_message_id = messageId;
-    saveClaim(claim, cwd);
+    mutate({ cwd }, () => {
+        const claim = loadClaim(claimId, cwd);
+        claim.assignment_message_id = messageId;
+        saveClaimUnlocked(claim, cwd);
+    });
+}
+/**
+ * sprint 1.5 — patch a claim's worktree_path so a coordinator can register a
+ * manually created worktree (or correct a stale path) without hand-editing the
+ * store. Surfaced through bclaw_update(entity="claim", patch={worktree_path}).
+ */
+export function patchClaimWorktreePath(claimId, worktreePath, cwd) {
+    return mutate({ cwd }, () => {
+        const claim = loadClaim(claimId, cwd);
+        claim.worktree_path = worktreePath;
+        saveClaimUnlocked(claim, cwd);
+        return claim;
+    });
 }
 /** Link a claim to its Assignment entity (Agent SDK runtime protocol). */
 export function linkClaimToAssignment(claimId, assignmentId, cwd) {
-    const claim = loadClaim(claimId, cwd);
-    claim.assignment_id = assignmentId;
-    saveClaim(claim, cwd);
+    mutate({ cwd }, () => {
+        const claim = loadClaim(claimId, cwd);
+        claim.assignment_id = assignmentId;
+        saveClaimUnlocked(claim, cwd);
+    });
 }
 /**
  * Adopt a claim from a spawned instance's session.
@@ -538,7 +701,7 @@ export function adoptClaimSession(claimId, sessionId, cwd) {
         }
         claim.session_id = sessionId;
         claim.adopted_at = nowISO();
-        saveClaim(claim, cwd);
+        saveClaimUnlocked(claim, cwd);
         return { adopted: true, reason: 'ok' };
     });
 }