brainclaw 1.7.5 → 1.9.0

package/dist/core/memory-lifecycle.js

@@ -0,0 +1,282 @@
+/**
+ * pln#544 — Memory lifecycle (confirm/decay/reinforce).
+ *
+ * Three primitives that combine into the "memory ages honestly" loop:
+ *
+ *  1. `recordMemoryEvent` — one-call confirm/infirm/saved_me/misled_me write
+ *     against an existing decision/constraint/trap. Updates the denormalised
+ *     counters and `last_confirmed_at` / `last_infirmed_at`, appends a
+ *     bounded event log entry, and re-saves the item.
+ *
+ *  2. `getLifecycleStats` — pure read of the lifecycle state for a single
+ *     item (age since confirmation, decay multiplier, "fresh" / "stale" /
+ *     "infirmed" classification). Context ranking and the curation hints
+ *     both consume this.
+ *
+ *  3. `buildMemoryLifecycleMetrics` — aggregate over the project's active
+ *     memory items: confirmed_ratio, average age, oldest unconfirmed, total
+ *     saved_me/misled_me signals. Surfaced in workflow hints and reputation.
+ *
+ * Decay curves are intentionally entity-specific (traps describe environment
+ * facts that mostly stay true, decisions/constraints describe project
+ * intent that drifts faster as the codebase evolves).
+ */
+import { mutateState } from './state.js';
+import { nowISO } from './ids.js';
+/** Maximum events kept inline on a memory item — older events are dropped
+ *  from the log. The counters stay accurate; the log is a recent-evidence
+ *  buffer, not an audit trail (audit.ts covers durable provenance). */
+export const MAX_INLINE_CONFIRMATIONS = 8;
+/** Per-entity decay half-life (days). Tuned by intuition + the rationale in
+ *  pln#544: traps describe stable environmental risks, decisions/constraints
+ *  describe project intent that goes stale faster as code evolves. */
+export const DECAY_HALF_LIFE_DAYS = {
+    trap: 90,
+    constraint: 60,
+    decision: 60,
+};
+/**
+ * Append a confirm/infirm/saved_me/misled_me event onto a memory item and
+ * update its denormalised counters. Returns the updated counters so the
+ * caller (CLI/MCP layer, tests) can echo them back to the operator.
+ *
+ * Throws if the item id is not present in the project's active state.
+ */
+export function recordMemoryEvent(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const at = input.at ?? nowISO();
+    let captured;
+    mutateState((state) => {
+        const bucket = input.entity === 'decision' ? state.recent_decisions
+            : input.entity === 'constraint' ? state.active_constraints
+                : state.known_traps;
+        const item = bucket.find((x) => x.id === input.id);
+        if (!item) {
+            throw new Error(`memory-lifecycle: ${input.entity} '${input.id}' not found in active state`);
+        }
+        const event = {
+            at,
+            by: input.by,
+            kind: input.kind,
+            ...(input.by_id ? { by_id: input.by_id } : {}),
+            ...(input.session_id ? { session_id: input.session_id } : {}),
+            ...(input.evidence ? { evidence: input.evidence } : {}),
+            ...(input.note ? { note: input.note } : {}),
+        };
+        const next = Array.isArray(item.confirmations)
+            ? [...item.confirmations, event]
+            : [event];
+        // Bounded log: keep the most recent MAX_INLINE_CONFIRMATIONS.
+        item.confirmations = next.slice(-MAX_INLINE_CONFIRMATIONS);
+        if (input.kind === 'confirm' || input.kind === 'saved_me') {
+            item.last_confirmed_at = at;
+            item.confirmation_count = (item.confirmation_count ?? 0) + 1;
+            if (input.kind === 'saved_me') {
+                item.saved_me_count = (item.saved_me_count ?? 0) + 1;
+            }
+        }
+        else {
+            item.last_infirmed_at = at;
+            item.infirmation_count = (item.infirmation_count ?? 0) + 1;
+            if (input.kind === 'misled_me') {
+                item.misled_me_count = (item.misled_me_count ?? 0) + 1;
+            }
+        }
+        captured = {
+            entity: input.entity,
+            id: input.id,
+            kind: input.kind,
+            last_confirmed_at: item.last_confirmed_at,
+            last_infirmed_at: item.last_infirmed_at,
+            confirmation_count: item.confirmation_count ?? 0,
+            infirmation_count: item.infirmation_count ?? 0,
+            saved_me_count: item.saved_me_count ?? 0,
+            misled_me_count: item.misled_me_count ?? 0,
+        };
+    }, cwd);
+    if (!captured) {
+        // Defensive: mutateState should have thrown on a missing item, but if
+        // mutateState swallows the throw we still surface a useful error.
+        throw new Error(`memory-lifecycle: ${input.entity} '${input.id}' could not be updated`);
+    }
+    return captured;
+}
+/**
+ * Compute the lifecycle stats for a single memory item. Pure function — no
+ * I/O, drivable from the schema fields alone. Context ranking calls this on
+ * every item; curation hints call it to surface the oldest unconfirmed.
+ */
+export function getLifecycleStats(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    const createdMs = Date.parse(input.created_at);
+    const confirmedMs = input.last_confirmed_at ? Date.parse(input.last_confirmed_at) : undefined;
+    const infirmedMs = input.last_infirmed_at ? Date.parse(input.last_infirmed_at) : undefined;
+    const anchorMs = Number.isFinite(createdMs)
+        ? Math.max(createdMs, confirmedMs ?? -Infinity)
+        : (confirmedMs ?? nowMs);
+    const anchorAt = new Date(anchorMs).toISOString();
+    const ageDays = Math.max(0, Math.floor((nowMs - anchorMs) / 86_400_000));
+    const infirmed = infirmedMs !== undefined
+        && (confirmedMs === undefined || infirmedMs > confirmedMs);
+    const infirmationAgeDays = infirmedMs !== undefined
+        ? Math.max(0, Math.floor((nowMs - infirmedMs) / 86_400_000))
+        : Number.POSITIVE_INFINITY;
+    const halfLife = DECAY_HALF_LIFE_DAYS[input.entity];
+    // 2^(-age / halfLife) — pure exponential decay, capped to [0, 1].
+    const decayFactor = Math.max(0, Math.min(1, Math.pow(2, -ageDays / halfLife)));
+    const confirmationCount = input.confirmation_count ?? 0;
+    const infirmationCount = input.infirmation_count ?? 0;
+    const savedMeCount = input.saved_me_count ?? 0;
+    const misledMeCount = input.misled_me_count ?? 0;
+    // Ranking delta combines:
+    //   decay     — gentle aging penalty up to ~-2 at +2 half-lives.
+    //   freshness — boost for items confirmed in the last 30d (+2).
+    //   reinforce — +1 per saved_me up to +3.
+    //   infirmed  — heavy penalty (-5) when infirmed after last confirm.
+    //   misled_me — extra penalty (-1 per misled_me up to -3).
+    //   stale     — -1 when never confirmed and older than half-life.
+    let rankingDelta = -2 * (1 - decayFactor);
+    const recentlyConfirmed = confirmedMs !== undefined && (nowMs - confirmedMs) <= 30 * 86_400_000;
+    if (recentlyConfirmed)
+        rankingDelta += 2;
+    rankingDelta += Math.min(savedMeCount, 3);
+    if (infirmed)
+        rankingDelta -= 5;
+    rankingDelta -= Math.min(misledMeCount, 3);
+    if (confirmationCount === 0 && ageDays > halfLife)
+        rankingDelta -= 1;
+    // Round to keep score reasons readable (e.g. "lifecycle:-2.5").
+    rankingDelta = Math.round(rankingDelta * 10) / 10;
+    let classification;
+    if (infirmed)
+        classification = 'infirmed';
+    else if (confirmationCount === 0 && ageDays > halfLife)
+        classification = 'never_confirmed';
+    else if (recentlyConfirmed)
+        classification = 'fresh';
+    else if (ageDays > 2 * halfLife)
+        classification = 'stale';
+    else
+        classification = 'aging';
+    return {
+        anchor_at: anchorAt,
+        age_days: ageDays,
+        infirmed,
+        infirmation_age_days: infirmationAgeDays,
+        decay_factor: Number(decayFactor.toFixed(3)),
+        ranking_delta: rankingDelta,
+        classification,
+        confirmation_count: confirmationCount,
+        infirmation_count: infirmationCount,
+        saved_me_count: savedMeCount,
+        misled_me_count: misledMeCount,
+    };
+}
+/**
+ * Aggregate lifecycle health across a project's active memory items. Pure
+ * function — callers (context.ts workflow hints, reputation.ts dashboard)
+ * pass the items they already loaded.
+ */
+export function buildMemoryLifecycleMetrics(items, nowMs = Date.now()) {
+    const active = items.filter((item) => !item.status || item.status === 'active');
+    const total = active.length;
+    if (total === 0) {
+        return {
+            total_items: 0,
+            confirmed_items: 0,
+            confirmed_ratio: 0,
+            average_age_days: 0,
+            total_saved_me: 0,
+            total_misled_me: 0,
+            total_infirmed_active: 0,
+            recall_precision_proxy: 0,
+        };
+    }
+    let confirmed = 0;
+    let ageSum = 0;
+    let savedMe = 0;
+    let misledMe = 0;
+    let infirmedActive = 0;
+    let oldestUnconfirmed;
+    for (const item of active) {
+        const stats = getLifecycleStats({
+            entity: item.entity,
+            created_at: item.created_at,
+            last_confirmed_at: item.last_confirmed_at,
+            last_infirmed_at: item.last_infirmed_at,
+            confirmation_count: item.confirmation_count,
+            infirmation_count: item.infirmation_count,
+            saved_me_count: item.saved_me_count,
+            misled_me_count: item.misled_me_count,
+            nowMs,
+        });
+        if (stats.confirmation_count > 0)
+            confirmed += 1;
+        if (stats.infirmed)
+            infirmedActive += 1;
+        ageSum += stats.age_days;
+        savedMe += stats.saved_me_count;
+        misledMe += stats.misled_me_count;
+        if (stats.confirmation_count === 0
+            && (!oldestUnconfirmed || stats.age_days > oldestUnconfirmed.age)) {
+            oldestUnconfirmed = { id: item.id, entity: item.entity, age: stats.age_days };
+        }
+    }
+    return {
+        total_items: total,
+        confirmed_items: confirmed,
+        confirmed_ratio: Number((confirmed / total).toFixed(3)),
+        average_age_days: Math.round(ageSum / total),
+        ...(oldestUnconfirmed ? {
+            oldest_unconfirmed_id: oldestUnconfirmed.id,
+            oldest_unconfirmed_entity: oldestUnconfirmed.entity,
+            oldest_unconfirmed_age_days: oldestUnconfirmed.age,
+        } : {}),
+        total_saved_me: savedMe,
+        total_misled_me: misledMe,
+        total_infirmed_active: infirmedActive,
+        recall_precision_proxy: savedMe - misledMe,
+    };
+}
+/**
+ * Convenience: load state and build the metrics in one call. Used by the
+ * curation surfacing in context.ts; tests can prefer the pure variant above.
+ */
+export function buildMemoryLifecycleMetricsForState(state, nowMs = Date.now()) {
+    const items = [];
+    for (const d of state.recent_decisions) {
+        items.push({
+            entity: 'decision', id: d.id, created_at: d.created_at,
+            last_confirmed_at: d.last_confirmed_at,
+            last_infirmed_at: d.last_infirmed_at,
+            confirmation_count: d.confirmation_count,
+            infirmation_count: d.infirmation_count,
+            saved_me_count: d.saved_me_count,
+            misled_me_count: d.misled_me_count,
+        });
+    }
+    for (const c of state.active_constraints) {
+        items.push({
+            entity: 'constraint', id: c.id, created_at: c.created_at, status: c.status,
+            last_confirmed_at: c.last_confirmed_at,
+            last_infirmed_at: c.last_infirmed_at,
+            confirmation_count: c.confirmation_count,
+            infirmation_count: c.infirmation_count,
+            saved_me_count: c.saved_me_count,
+            misled_me_count: c.misled_me_count,
+        });
+    }
+    for (const t of state.known_traps) {
+        items.push({
+            entity: 'trap', id: t.id, created_at: t.created_at, status: t.status,
+            last_confirmed_at: t.last_confirmed_at,
+            last_infirmed_at: t.last_infirmed_at,
+            confirmation_count: t.confirmation_count,
+            infirmation_count: t.infirmation_count,
+            saved_me_count: t.saved_me_count,
+            misled_me_count: t.misled_me_count,
+        });
+    }
+    return buildMemoryLifecycleMetrics(items, nowMs);
+}
+//# sourceMappingURL=memory-lifecycle.js.map

package/dist/core/merge-risk.js

@@ -0,0 +1,150 @@
+/**
+ * Pre-merge conflict detection for worktree-based parallel execution
+ * (pln#396). Before lanes are merged back, surface which worktrees touch
+ * overlapping files — the textual-conflict risk — and which claim / session /
+ * agent owns each side, so the operator (or the merge path) sees the danger
+ * before `git merge`, not after.
+ *
+ * This is a *risk signal*, not a merge engine: file-level overlap is a
+ * necessary-not-sufficient predictor (two lanes editing the same file usually
+ * conflict; disjoint hunks sometimes don't). It deliberately over-reports
+ * rather than miss — a flagged non-conflict costs a glance; a missed conflict
+ * costs the trp_merge_wipes_node_modules / parasitic-deletion class of pain.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { listWorktrees } from './worktree.js';
+import { listClaims } from './claims.js';
+import { logger } from './logger.js';
+function git(args, cwd) {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 15000 });
+    return { ok: r.status === 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+/** Paths never counted as conflict risk: store-internal + birth noise. */
+function isIgnorablePath(file) {
+    return file === '.gitignore'
+        || file.startsWith('.brainclaw/')
+        || file.startsWith('.git/');
+}
+function committedChangedFiles(mainPath, baseRef, branch) {
+    // base...branch = changes on `branch` since it diverged from baseRef.
+    // --no-renames: a committed rename old→new must surface BOTH paths so a lane
+    // that EDITS `old` overlaps with a lane that RENAMES `old`→`new` (otherwise
+    // the rename-vs-modify conflict is invisible to overlap detection). Default
+    // rename detection collapses this to the destination only.
+    const r = git(['diff', '--name-only', '--no-renames', `${baseRef}...${branch}`], mainPath);
+    if (r.ok) {
+        return r.stdout.split('\n').map(s => s.trim()).filter(Boolean);
+    }
+    // Three-dot diff requires a merge base; an unrelated-history branch errors
+    // out (`fatal: no merge base`). Fall back to a plain two-arg diff, which
+    // works across unrelated histories and yields the union of touched paths —
+    // over-reporting (every file in either tree) rather than silently missing
+    // the real divergence with an empty list.
+    const fallback = git(['diff', '--name-only', '--no-renames', baseRef, branch], mainPath);
+    if (fallback.ok) {
+        logger.warn(`[merge-risk] no merge base between ${baseRef} and ${branch}; falling back to two-arg diff (over-reports rather than miss).`);
+        return fallback.stdout.split('\n').map(s => s.trim()).filter(Boolean);
+    }
+    logger.warn(`[merge-risk] git diff failed for ${branch} vs ${baseRef}: ${r.stderr.trim() || fallback.stderr.trim()}`);
+    return [];
+}
+function dirtyTrackedFiles(worktreePath) {
+    const r = git(['status', '--short', '--untracked-files=no'], worktreePath);
+    if (!r.ok)
+        return [];
+    return r.stdout.split('\n')
+        .filter(Boolean)
+        .map(line => line.slice(3).trim()) // strip the XY status prefix
+        // a rename shows "old -> new"; keep the destination path
+        .map(p => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
+        .filter(Boolean);
+}
+/**
+ * Analyze pre-merge conflict risk across the parallel worktree lanes.
+ * Pure read: runs only `git diff`/`git status` (no lock, no mutation).
+ */
+export function analyzeMergeRisk(mainWorktreePath, options = {}) {
+    const includeDirty = options.includeDirty ?? true;
+    // Resolve the base ref: explicit, else the main worktree's current branch, else master.
+    let baseRef = options.baseRef;
+    if (!baseRef) {
+        const head = git(['rev-parse', '--abbrev-ref', 'HEAD'], mainWorktreePath);
+        baseRef = head.ok && head.stdout.trim() && head.stdout.trim() !== 'HEAD' ? head.stdout.trim() : 'master';
+    }
+    const claims = listClaims(mainWorktreePath).filter(c => c.status === 'active');
+    const claimByWorktree = new Map();
+    for (const c of claims) {
+        if (c.worktree_path)
+            claimByWorktree.set(normalizePath(c.worktree_path), { id: c.id, scope: c.scope });
+    }
+    const worktrees = listWorktrees(mainWorktreePath).filter((w) => !w.is_main && w.branch !== '(detached)' && w.branch !== '(bare)'
+        && (!options.branches || options.branches.includes(w.branch)));
+    const lanes = [];
+    for (const w of worktrees) {
+        const committed = committedChangedFiles(mainWorktreePath, baseRef, w.branch).filter(f => !isIgnorablePath(f));
+        const dirty = includeDirty ? dirtyTrackedFiles(w.path).filter(f => !isIgnorablePath(f)) : [];
+        const changed = [...new Set([...committed, ...dirty])].sort();
+        const claim = claimByWorktree.get(normalizePath(w.path));
+        lanes.push({
+            branch: w.branch,
+            path: w.path,
+            session_id: w.session_id,
+            agent: w.agent,
+            claim_id: claim?.id,
+            claim_scope: claim?.scope,
+            committed_files: committed.sort(),
+            dirty_files: dirty.sort(),
+            changed_files: changed,
+        });
+    }
+    // File → lanes touching it; an overlap is any file in ≥2 lanes.
+    const fileToLanes = new Map();
+    for (const lane of lanes) {
+        for (const file of lane.changed_files) {
+            const arr = fileToLanes.get(file) ?? [];
+            arr.push(lane);
+            fileToLanes.set(file, arr);
+        }
+    }
+    const overlaps = [];
+    for (const [file, touching] of fileToLanes) {
+        if (touching.length < 2)
+            continue;
+        overlaps.push({
+            file,
+            branches: touching.map(l => l.branch),
+            claims: [...new Set(touching.map(l => l.claim_id).filter((x) => !!x))],
+        });
+    }
+    overlaps.sort((a, b) => b.branches.length - a.branches.length || a.file.localeCompare(b.file));
+    const hasRisk = overlaps.length > 0;
+    const summary = lanes.length === 0
+        ? 'No parallel worktree lanes to analyze.'
+        : hasRisk
+            ? `${overlaps.length} file(s) touched by multiple lanes across ${lanes.length} lane(s) — review before merge.`
+            : `${lanes.length} lane(s), no overlapping files — lanes are disjoint, safe to merge in any order.`;
+    return { base_ref: baseRef, lanes, overlaps, has_risk: hasRisk, summary };
+}
+function normalizePath(p) {
+    // Slash + trailing-slash normalisation is universal. Case-folding only on
+    // win32: POSIX filesystems are case-sensitive, so lowercasing `/Users/Foo`
+    // and `/users/foo` would collapse two genuinely distinct directories and
+    // mis-attribute a claim to the wrong lane.
+    // Resolve to the canonical real path when it exists, so a stored
+    // worktree_path in Windows 8.3 short form (e.g. C:\Users\RUNNER~1\…, as
+    // GitHub runners' TEMP expands) reconciles with the long-form path that
+    // `git worktree list` reports. Without this the claim never matches its lane
+    // on Windows CI (pln#576). Falls back to the literal path for stale claims
+    // whose worktree has been removed.
+    let resolved = p;
+    try {
+        resolved = fs.realpathSync.native(p);
+    }
+    catch {
+        // Path no longer exists — keep the literal value.
+    }
+    const normalized = resolved.replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+//# sourceMappingURL=merge-risk.js.map

package/dist/core/messaging.js

@@ -134,7 +134,7 @@ export function readInbox(input, cwd) {
     const page = messages.slice(offset, offset + limit);
     return { total, offset, limit, messages: page };
 }
-export function ackMessage(messageId, agent, cwd) {
+export function ackMessage(messageId, agent, cwd, options = {}) {
     return mutate({ cwd }, () => {
         const dir = agentInboxDir(agent, cwd);
         const messages = loadMessagesFromDir(dir);
@@ -142,6 +142,13 @@ export function ackMessage(messageId, agent, cwd) {
         if (!msg) {
             throw new Error(`Message '${messageId}' not found in ${agent}'s inbox.`);
         }
+        const callerClaimId = options.claimId?.trim();
+        const messageClaimId = msg.claim_id
+            ?? msg.payload?.claim_id;
+        if (callerClaimId && messageClaimId && messageClaimId !== callerClaimId) {
+            throw new Error(`Message '${msg.id}' is bound to claim '${messageClaimId}' but the caller holds claim '${callerClaimId}'. `
+                + 'Only the instance holding the message\'s claim may acknowledge it.');
+        }
         const timestamp = nowISO();
         msg.status = 'acknowledged';
         msg.ack_at = timestamp;

package/dist/core/migration.js

@@ -139,8 +139,18 @@ export function preparePersistedDocument(documentType, document) {
         schema_version: currentDocumentVersion(documentType),
     };
 }
+/**
+ * The exact on-disk bytes for a versioned JSON document — the single
+ * serialization source of truth shared by the writer and the
+ * dirty-tracking skip check (pln#543 step 3). Computing the would-be
+ * content here means the skip comparison can never drift from what the
+ * writer actually produces.
+ */
+export function serializeVersionedJson(documentType, document) {
+    return `${JSON.stringify(preparePersistedDocument(documentType, document), null, 2)}\n`;
+}
 export function saveVersionedJsonFile(documentType, filepath, document) {
-    writeFileAtomic(filepath, `${JSON.stringify(preparePersistedDocument(documentType, document), null, 2)}\n`);
+    writeFileAtomic(filepath, serializeVersionedJson(documentType, document));
 }
 export function saveVersionedYamlFile(documentType, filepath, document) {
     const yaml = YAML.stringify(preparePersistedDocument(documentType, document), { lineWidth: 0 });

package/dist/core/observer-mode.js

@@ -0,0 +1,26 @@
+/**
+ * Observer-mode helper (asgn_8a3790f6 / pln#558 step 1).
+ *
+ * When `BRAINCLAW_OBSERVER=1` is set in the process environment, the brainclaw
+ * store treats this process as a passive observer (a dashboard, the VS Code
+ * extension, an inspection script) and suppresses every read-path side effect:
+ *
+ *   - auto-acknowledge of open handoffs in the coordination snapshot
+ *   - lazy reconciliation of agent_run records during read paths
+ *   - cursor advancement in readUnseenEvents
+ *   - implicit heartbeat / auto-registration of identity
+ *
+ * A dashboard is not an agent. Reading the board must never mutate the store
+ * it observes — that loop is what caused the 2026-06-10 lock-contention storm
+ * (the VS Code extension's poll re-wrote and git-committed the entire store
+ * under the mutation lock, holding it >5s and timing out every other writer).
+ *
+ * The flag is intentionally an environment variable — workers inherit it from
+ * the parent, so a single setting at MCP-server spawn time covers every read
+ * dispatched through the worker pool.
+ */
+export function isObserverMode(env = process.env) {
+    const raw = (env.BRAINCLAW_OBSERVER ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+//# sourceMappingURL=observer-mode.js.map