brainclaw 0.29.2 → 1.5.4

package/dist/core/governance.js

@@ -0,0 +1,247 @@
+/**
+ * Governance posture report.
+ *
+ * Aggregates claims, constraints, traps, instructions, and audit entries
+ * into a structured governance snapshot. No scores, no synthetic metrics —
+ * only verifiable facts.
+ *
+ * @module
+ */
+import { listClaims, isClaimExpired } from './claims.js';
+import { loadState } from './state.js';
+import { loadInstructions, resolveInstructions } from './instructions.js';
+import { readAuditLog } from './audit.js';
+// ---------------------------------------------------------------------------
+// Report builder
+// ---------------------------------------------------------------------------
+export function buildGovernanceReport(options = {}) {
+    const cwd = options.cwd;
+    const now = new Date();
+    const last24h = new Date(now.getTime() - 24 * 60 * 60 * 1000).toISOString();
+    // --- Constitution (global instructions) ---
+    const allInstructions = loadInstructions(cwd);
+    const activeInstructions = resolveInstructions(allInstructions, {});
+    const globalInstructions = activeInstructions.filter(i => i.layer === 'global');
+    // --- Red Lines (constraints) ---
+    const state = loadState(cwd);
+    const activeConstraints = state.active_constraints.filter(c => c.status === 'active');
+    const constraintsByCategory = {};
+    for (const c of activeConstraints) {
+        const cat = c.category ?? 'other';
+        (constraintsByCategory[cat] ??= []).push(c);
+    }
+    const highSeverityCount = activeConstraints.filter(c => c.tags?.includes('high') || c.category === 'security').length;
+    // --- Claims ---
+    const allClaims = listClaims(cwd);
+    const activeClaims = allClaims.filter(c => c.status === 'active' && !isClaimExpired(c));
+    const expiredUnreleased = allClaims.filter(c => c.status === 'active' && isClaimExpired(c));
+    const claimsByAgent = {};
+    for (const c of activeClaims) {
+        claimsByAgent[c.agent] = (claimsByAgent[c.agent] ?? 0) + 1;
+    }
+    // Apply filters
+    let filteredActiveClaims = activeClaims;
+    let filteredExpired = expiredUnreleased;
+    if (options.agent) {
+        const agentLower = options.agent.toLowerCase();
+        filteredActiveClaims = activeClaims.filter(c => c.agent.toLowerCase() === agentLower || c.agent_id?.toLowerCase() === agentLower);
+        filteredExpired = expiredUnreleased.filter(c => c.agent.toLowerCase() === agentLower || c.agent_id?.toLowerCase() === agentLower);
+    }
+    // --- Traps (shared visibility only — machine/private traps are environment-specific) ---
+    const openTraps = state.known_traps.filter(t => t.status === 'active' && (t.visibility === 'shared' || !t.visibility));
+    const trapsBySeverity = {};
+    for (const t of openTraps) {
+        trapsBySeverity[t.severity] = (trapsBySeverity[t.severity] ?? 0) + 1;
+    }
+    // --- Recent activity ---
+    const recentEntries = readAuditLog({ since: last24h }, cwd);
+    const claimsLast24h = recentEntries.filter(e => e.action === 'claim').length;
+    const releasesLast24h = recentEntries.filter(e => e.action === 'release_claim').length;
+    // Detect mutations without claim — check creates/updates that aren't claim/release/session actions
+    const mutationActions = new Set(['create', 'update', 'delete', 'promote_direct']);
+    const sessionTypes = new Set(['session', 'claim']);
+    const actionsWithoutClaim = recentEntries.filter(e => {
+        if (!mutationActions.has(e.action))
+            return false;
+        if (sessionTypes.has(e.item_type ?? ''))
+            return false;
+        // Check if the actor had any active claim at that time
+        const actorClaims = activeClaims.filter(c => c.agent === e.actor);
+        return actorClaims.length === 0;
+    });
+    // --- Recommendations ---
+    const recommendations = [];
+    if (expiredUnreleased.length > 0) {
+        recommendations.push(`${expiredUnreleased.length} expired claim(s) need release. Run: bclaw release-claims --expired`);
+    }
+    if (openTraps.length > 0) {
+        const highTraps = openTraps.filter(t => t.severity === 'high');
+        if (highTraps.length > 0) {
+            recommendations.push(`${highTraps.length} high-severity trap(s) open. Review before editing related files.`);
+        }
+    }
+    if (actionsWithoutClaim.length > 0) {
+        recommendations.push(`${actionsWithoutClaim.length} mutation(s) detected without active claim in last 24h.`);
+    }
+    if (globalInstructions.length === 0) {
+        recommendations.push('No global instructions set. Consider adding governance rules via: bclaw instruction add --layer global');
+    }
+    return {
+        generated_at: now.toISOString(),
+        scope_filter: options.scope,
+        agent_filter: options.agent,
+        constitution: {
+            global_instructions: globalInstructions,
+            total: globalInstructions.length,
+        },
+        red_lines: {
+            constraints_by_category: constraintsByCategory,
+            high_severity_count: highSeverityCount,
+            total: activeConstraints.length,
+        },
+        claims: {
+            active: filteredActiveClaims.map(toClaimSummary),
+            expired_unreleased: filteredExpired.map(toClaimSummary),
+            by_agent: claimsByAgent,
+            total_active: filteredActiveClaims.length,
+            total_expired_unreleased: filteredExpired.length,
+        },
+        traps: {
+            open: openTraps.map(toTrapSummary),
+            by_severity: trapsBySeverity,
+            total_open: openTraps.length,
+        },
+        recent_activity: {
+            claims_last_24h: claimsLast24h,
+            releases_last_24h: releasesLast24h,
+            actions_without_claim: actionsWithoutClaim,
+        },
+        recommendations,
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+export function renderGovernanceMarkdown(report) {
+    const lines = [];
+    const ts = report.generated_at.slice(0, 16).replace('T', ' ');
+    lines.push(`# Governance Posture Report`);
+    lines.push(`Generated: ${ts} UTC`);
+    if (report.scope_filter)
+        lines.push(`Scope: ${report.scope_filter}`);
+    if (report.agent_filter)
+        lines.push(`Agent: ${report.agent_filter}`);
+    lines.push('');
+    // --- Summary ---
+    lines.push('## Summary');
+    lines.push(`- Active claims: ${report.claims.total_active}`);
+    lines.push(`- Expired (unreleased): ${report.claims.total_expired_unreleased}`);
+    lines.push(`- Active constraints: ${report.red_lines.total}`);
+    lines.push(`- Open traps: ${report.traps.total_open}`);
+    lines.push(`- Global instructions: ${report.constitution.total}`);
+    lines.push(`- Claims (24h): ${report.recent_activity.claims_last_24h} created, ${report.recent_activity.releases_last_24h} released`);
+    if (report.recent_activity.actions_without_claim.length > 0) {
+        lines.push(`- **Mutations without claim (24h): ${report.recent_activity.actions_without_claim.length}**`);
+    }
+    lines.push('');
+    // --- Constitution ---
+    if (report.constitution.total > 0) {
+        lines.push('## Constitution (Global Instructions)');
+        for (const ins of report.constitution.global_instructions) {
+            lines.push(`- ${ins.text}`);
+        }
+        lines.push('');
+    }
+    // --- Red Lines ---
+    if (report.red_lines.total > 0) {
+        lines.push('## Red Lines (Active Constraints)');
+        for (const [category, constraints] of Object.entries(report.red_lines.constraints_by_category)) {
+            lines.push(`### ${category} (${constraints.length})`);
+            for (const c of constraints) {
+                const paths = c.related_paths?.length ? ` — ${c.related_paths.join(', ')}` : '';
+                lines.push(`- [${c.id}] ${c.text}${paths}`);
+            }
+        }
+        lines.push('');
+    }
+    // --- Claims ---
+    if (report.claims.total_active > 0) {
+        lines.push('## Active Claims');
+        const agentEntries = Object.entries(report.claims.by_agent).sort((a, b) => b[1] - a[1]);
+        if (agentEntries.length > 1) {
+            lines.push(`By agent: ${agentEntries.map(([a, n]) => `${a} (${n})`).join(', ')}`);
+            lines.push('');
+        }
+        for (const c of report.claims.active) {
+            const planNote = c.plan_id ? ` [${c.plan_id}]` : '';
+            const expiryNote = c.expires_at ? ` (expires ${c.expires_at.slice(0, 16).replace('T', ' ')})` : '';
+            lines.push(`- [${c.id}] ${c.agent} → ${c.scope}: ${c.description}${planNote}${expiryNote}`);
+        }
+        lines.push('');
+    }
+    if (report.claims.total_expired_unreleased > 0) {
+        lines.push('## Expired Claims (Need Release)');
+        for (const c of report.claims.expired_unreleased) {
+            lines.push(`- [${c.id}] ${c.agent} → ${c.scope}: ${c.description} (expired ${c.expires_at?.slice(0, 16).replace('T', ' ') ?? '?'})`);
+        }
+        lines.push('');
+    }
+    // --- Traps ---
+    if (report.traps.total_open > 0) {
+        lines.push('## Open Traps');
+        const sevEntries = Object.entries(report.traps.by_severity);
+        if (sevEntries.length > 0) {
+            lines.push(`By severity: ${sevEntries.map(([s, n]) => `${s} (${n})`).join(', ')}`);
+            lines.push('');
+        }
+        for (const t of report.traps.open) {
+            const paths = t.related_paths?.length ? ` — ${t.related_paths.join(', ')}` : '';
+            lines.push(`- [${t.id}] [${t.severity}] ${t.text}${paths}`);
+        }
+        lines.push('');
+    }
+    // --- Mutations without claim ---
+    if (report.recent_activity.actions_without_claim.length > 0) {
+        lines.push('## Mutations Without Claim (Last 24h)');
+        for (const e of report.recent_activity.actions_without_claim.slice(0, 20)) {
+            const scope = e.scope ? ` → ${e.scope}` : '';
+            lines.push(`- ${e.timestamp.slice(0, 16).replace('T', ' ')} [${e.actor}] ${e.action} ${e.item_type ?? ''}${scope}`);
+        }
+        if (report.recent_activity.actions_without_claim.length > 20) {
+            lines.push(`  ... and ${report.recent_activity.actions_without_claim.length - 20} more`);
+        }
+        lines.push('');
+    }
+    // --- Recommendations ---
+    if (report.recommendations.length > 0) {
+        lines.push('## Recommendations');
+        for (const r of report.recommendations) {
+            lines.push(`- ${r}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function toClaimSummary(c) {
+    return {
+        id: c.id,
+        agent: c.agent,
+        scope: c.scope,
+        description: c.description,
+        created_at: c.created_at,
+        expires_at: c.expires_at,
+        plan_id: c.plan_id,
+    };
+}
+function toTrapSummary(t) {
+    return {
+        id: t.id,
+        text: t.text,
+        severity: t.severity,
+        related_paths: t.related_paths,
+    };
+}
+//# sourceMappingURL=governance.js.map

package/dist/core/guards.js

@@ -0,0 +1,19 @@
+/**
+ * Shared guard utilities for CLI commands.
+ *
+ * These replace the duplicated memoryExists + process.exit(1) pattern
+ * found across 70+ command files.
+ *
+ * @module
+ */
+import { memoryExists } from './io.js';
+/**
+ * Abort the CLI process if .brainclaw/ is not found at the given path.
+ */
+export function requireInitialized(cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=guards.js.map

package/dist/core/ideation.js

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { memoryDir } from './io.js';
+export const IdeationRoundSchema = z.object({
+    schema_version: z.literal(1),
+    thread_id: z.string(),
+    round_number: z.number().int().min(0),
+    round_type: z.enum(['position', 'reaction', 'convergence']),
+    positions: z.array(z.object({
+        persona: z.string(),
+        agent: z.string(),
+        text: z.string(),
+        duration_ms: z.number().optional(),
+    })),
+    tensions: z.array(z.string()).default([]),
+    convergences: z.array(z.string()).default([]),
+    created_at: z.string(),
+});
+function sanitizeForPath(slug) {
+    return slug.replace(/[<>:"/\\|?*]/g, '_');
+}
+export function ideationDir(threadSlug, cwd) {
+    return path.join(memoryDir(cwd), 'coordination', 'ideation', sanitizeForPath(threadSlug));
+}
+export function saveIdeationRound(threadSlug, round, cwd) {
+    const dir = ideationDir(threadSlug, cwd);
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `round_${round.round_number}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(round, null, 2), 'utf8');
+}
+export function loadIdeationRound(threadSlug, roundNumber, cwd) {
+    const filePath = path.join(ideationDir(threadSlug, cwd), `round_${roundNumber}.json`);
+    if (!fs.existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        return IdeationRoundSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listIdeationThreads(cwd) {
+    const base = path.join(memoryDir(cwd), 'coordination', 'ideation');
+    if (!fs.existsSync(base))
+        return [];
+    return fs.readdirSync(base, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .sort();
+}
+export function listIdeationRounds(threadSlug, cwd) {
+    const dir = ideationDir(threadSlug, cwd);
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    const rounds = [];
+    for (const entry of fs.readdirSync(dir)) {
+        const match = /^round_(\d+)\.json$/.exec(entry);
+        if (!match) {
+            continue;
+        }
+        const round = loadIdeationRound(threadSlug, Number(match[1]), cwd);
+        if (round) {
+            rounds.push(round);
+        }
+    }
+    return rounds.sort((a, b) => a.round_number - b.round_number);
+}
+//# sourceMappingURL=ideation.js.map

package/dist/core/identity.js

@@ -76,18 +76,23 @@ export function loadCurrentSession(cwd) {
     const currentUser = resolveCurrentUser();
     const currentAgent = resolveCurrentAgentName();
     // 1. Look in sessions/ directory for a matching session
-    if (fs.existsSync(dir)) {
+    if (fs.existsSync(dir) && currentAgent) {
         const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
         const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
         const now = Date.now();
         for (const file of files) {
             try {
-                const session = CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', path.join(dir, file)).document);
-                // Match by agent+user (or agent only if user not set in old sessions)
+                const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+                const session = {
+                    ...CurrentSessionStateSchema.parse(migration.document),
+                    schema_version: migration.metadata.currentVersion,
+                };
+                // Strict match: agent name must match, user must match (when both are known)
+                if (session.agent !== currentAgent)
+                    continue;
                 const userMatch = !session.user || !currentUser || session.user === currentUser;
-                const agentMatch = !currentAgent || session.agent === currentAgent;
                 const alive = (now - Date.parse(session.last_seen_at)) <= ttlMs;
-                if (userMatch && agentMatch && alive) {
+                if (userMatch && alive) {
                     return session;
                 }
             }
@@ -100,7 +105,11 @@ export function loadCurrentSession(cwd) {
     const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
     if (fs.existsSync(legacyPath)) {
         try {
-            return CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', legacyPath).document);
+            const migration = loadVersionedJsonFile('current_session', legacyPath);
+            return {
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            };
         }
         catch {
             return undefined;
@@ -116,7 +125,11 @@ export function loadSessionById(sessionId, cwd) {
     if (!fs.existsSync(filepath))
         return undefined;
     try {
-        return CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', filepath).document);
+        const migration = loadVersionedJsonFile('current_session', filepath);
+        return {
+            ...CurrentSessionStateSchema.parse(migration.document),
+            schema_version: migration.metadata.currentVersion,
+        };
     }
     catch {
         return undefined;
@@ -133,7 +146,11 @@ export function loadAllSessions(cwd) {
     const sessions = [];
     for (const file of files) {
         try {
-            sessions.push(CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', path.join(dir, file)).document));
+            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+            sessions.push({
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            });
         }
         catch {
             // skip invalid
@@ -195,7 +212,11 @@ export function gcStaleSessions(cwd, ttlOverride) {
     const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
     for (const file of files) {
         try {
-            const session = CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', path.join(dir, file)).document);
+            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+            const session = {
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            };
             if (now - Date.parse(session.last_seen_at) > ttlMs) {
                 fs.unlinkSync(path.join(dir, file));
                 removed++;
@@ -223,7 +244,11 @@ function resolveCurrentUser() {
     return process.env.USER || process.env.USERNAME || os.userInfo().username || undefined;
 }
 function resolveCurrentAgentName() {
-    return process.env.BRAINCLAW_AGENT_NAME || process.env.CLAUDE_CODE_VERSION ? 'claude-code' : undefined;
+    if (process.env.BRAINCLAW_AGENT_NAME)
+        return process.env.BRAINCLAW_AGENT_NAME;
+    if (process.env.CLAUDE_CODE_VERSION)
+        return 'claude-code';
+    return undefined;
 }
 function loadConfigSafe(cwd) {
     try {
@@ -233,29 +258,90 @@ function loadConfigSafe(cwd) {
         return undefined;
     }
 }
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find the session matching the current process among all active sessions.
+ *
+ * Resolution order:
+ *  1. Preferred session ID (explicit env var / parameter) → exact match
+ *  2. Same agent + user + host + same PID → refresh (same process reconnecting)
+ *  3. Same agent + user + host + dead PID → reclaim stale session
+ *  4. No match → create new session
+ *
+ * Crucially, if another session exists for the same agent+user+host but with
+ * a LIVE different PID, it is left untouched — that's a parallel instance.
+ */
 function resolveImplicitSession(cwd, options) {
-    const current = loadCurrentSession(cwd);
     const persistImplicit = options.persistImplicit ?? true;
     const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
     const now = new Date();
     const currentUser = resolveCurrentUser();
-    if (current
-        && current.agent === options.agentName
-        && current.agent_id === options.agentId
-        && current.host_id === options.hostId
-        && (!current.user || !currentUser || current.user === currentUser)
-        && now.getTime() - Date.parse(current.last_seen_at) <= ttlMs) {
+    const currentPid = process.pid;
+    // 1. If a preferred session ID is given, try exact match first
+    if (options.preferredSessionId) {
+        const exact = loadSessionById(options.preferredSessionId, cwd);
+        if (exact && now.getTime() - Date.parse(exact.last_seen_at) <= ttlMs) {
+            const refreshed = {
+                ...exact,
+                last_seen_at: now.toISOString(),
+                user: exact.user || currentUser,
+                pid: currentPid,
+            };
+            if (persistImplicit)
+                saveCurrentSession(refreshed, cwd);
+            return refreshed;
+        }
+    }
+    // 2. Scan all sessions for PID-aware matching
+    const allSessions = loadAllSessions(cwd);
+    let samePidSession;
+    let deadPidSession;
+    for (const session of allSessions) {
+        if (session.agent !== options.agentName)
+            continue;
+        if (session.agent_id !== options.agentId)
+            continue;
+        if (session.host_id !== options.hostId)
+            continue;
+        if (currentUser && session.user && session.user !== currentUser)
+            continue;
+        if (now.getTime() - Date.parse(session.last_seen_at) > ttlMs)
+            continue;
+        // Same PID = same process reconnecting (e.g. MCP server refreshing)
+        if (session.pid === currentPid) {
+            samePidSession = session;
+            break;
+        }
+        // Different PID but alive = parallel instance, do NOT reclaim
+        if (session.pid && isPidAlive(session.pid)) {
+            continue;
+        }
+        // Dead PID = stale session, candidate for reclaim
+        if (!deadPidSession) {
+            deadPidSession = session;
+        }
+    }
+    const toRefresh = samePidSession ?? deadPidSession;
+    if (toRefresh) {
         const refreshed = {
-            ...current,
+            ...toRefresh,
             last_seen_at: now.toISOString(),
-            user: current.user || currentUser,
-            pid: process.pid,
+            user: toRefresh.user || currentUser,
+            pid: currentPid,
         };
-        if (persistImplicit) {
+        if (persistImplicit)
             saveCurrentSession(refreshed, cwd);
-        }
         return refreshed;
     }
+    // 3. No match — create new session
     const created = {
         session_id: options.preferredSessionId ?? generateImplicitSessionId(),
         started_at: now.toISOString(),
@@ -264,11 +350,10 @@ function resolveImplicitSession(cwd, options) {
         agent_id: options.agentId,
         host_id: options.hostId,
         user: currentUser,
-        pid: process.pid,
+        pid: currentPid,
     };
-    if (persistImplicit) {
+    if (persistImplicit)
         saveCurrentSession(created, cwd);
-    }
     return created;
 }
 function parseDurationToMs(value) {

package/dist/core/ids.js

@@ -10,8 +10,14 @@ const PREFIXES = {
     open_handoffs: 'hnd',
     plan_items: 'pln',
     plan_steps: 'stp',
+    sequences: 'seq',
     instruction_entries: 'ins',
     ai_surface_tasks: 'ast',
+    inbox_messages: 'msg',
+    assignments: 'asgn',
+    runs: 'run',
+    actions: 'act',
+    runtime_events: 'evt',
 };
 const ID_COUNTER_FILE = '.id-counter.json';
 function counterPath(cwd) {

package/dist/core/input-validation.js

@@ -11,7 +11,7 @@ export const TtlSchema = z
     .string()
     .regex(TTL_PATTERN, 'Invalid TTL format. Use <number><unit> where unit is m (minutes), h (hours), or d (days). Example: 30m, 2h, 7d');
 function formatZodError(error, field) {
-    return error.errors.map((e) => ({ field, message: e.message }));
+    return error.issues.map((e) => ({ field, message: e.message }));
 }
 /**
  * Validate CLI mutation inputs. On failure: prints error and calls process.exit(1).
@@ -41,7 +41,7 @@ export function validateCliInput(text, tags) {
 export function validateCliTtl(ttl) {
     const result = TtlSchema.safeParse(ttl);
     if (!result.success) {
-        console.error(`Error: ${result.error.errors[0]?.message ?? 'Invalid TTL'}`);
+        console.error(`Error: ${result.error.issues[0]?.message ?? 'Invalid TTL'}`);
         process.exit(1);
     }
 }