brainclaw 0.28.0 → 1.5.3

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

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
@@ -7,7 +8,9 @@ import { resolveCurrentHostId } from './host.js';
 import { memoryDir } from './io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { CurrentSessionStateSchema } from './schema.js';
-const CURRENT_SESSION_FILE = '.current-session';
+const SESSIONS_DIR = 'sessions';
+const LEGACY_SESSION_FILE = '.current-session';
+// --- Public API ---
 export function resolveCurrentSessionId(env = process.env, cwd, options = {}) {
     const value = env.BRAINCLAW_SESSION_ID?.trim()
         || env.OPENCLAW_SESSION_ID?.trim()
@@ -64,61 +67,281 @@ export function resolveEventSessionId(event) {
         ? metadataSession
         : undefined;
 }
+/**
+ * Load the current session for this agent+user combo.
+ * Checks sessions/ directory first, falls back to legacy .current-session.
+ */
 export function loadCurrentSession(cwd) {
-    const filepath = currentSessionPath(cwd);
-    if (!fs.existsSync(filepath)) {
-        return undefined;
+    const dir = sessionsDir(cwd);
+    const currentUser = resolveCurrentUser();
+    const currentAgent = resolveCurrentAgentName();
+    // 1. Look in sessions/ directory for a matching session
+    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 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 alive = (now - Date.parse(session.last_seen_at)) <= ttlMs;
+                if (userMatch && alive) {
+                    return session;
+                }
+            }
+            catch {
+                // skip invalid session files
+            }
+        }
+    }
+    // 2. Legacy fallback: .current-session
+    const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
+    if (fs.existsSync(legacyPath)) {
+        try {
+            const migration = loadVersionedJsonFile('current_session', legacyPath);
+            return {
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            };
+        }
+        catch {
+            return undefined;
+        }
     }
+    return undefined;
+}
+/**
+ * Load a specific session by ID.
+ */
+export function loadSessionById(sessionId, cwd) {
+    const filepath = sessionFilePath(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;
     }
 }
+/**
+ * Load ALL sessions (active + stale) from the sessions/ directory.
+ */
+export function loadAllSessions(cwd) {
+    const dir = sessionsDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    const sessions = [];
+    for (const file of files) {
+        try {
+            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+            sessions.push({
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            });
+        }
+        catch {
+            // skip invalid
+        }
+    }
+    return sessions.sort((a, b) => b.last_seen_at.localeCompare(a.last_seen_at));
+}
+/**
+ * Save a session to the sessions/ directory.
+ */
 export function saveCurrentSession(session, cwd) {
-    saveVersionedJsonFile('current_session', currentSessionPath(cwd), CurrentSessionStateSchema.parse(session));
+    const dir = sessionsDir(cwd);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const filepath = sessionFilePath(session.session_id, cwd);
+    saveVersionedJsonFile('current_session', filepath, CurrentSessionStateSchema.parse(session));
 }
+/**
+ * Clear a session. If sessionId is provided, only clear that specific session.
+ */
 export function clearCurrentSession(cwd, sessionId) {
-    const filepath = currentSessionPath(cwd);
-    if (!fs.existsSync(filepath)) {
+    if (sessionId) {
+        // Remove specific session file
+        const filepath = sessionFilePath(sessionId, cwd);
+        try {
+            fs.unlinkSync(filepath);
+        }
+        catch { /* ignore */ }
         return;
     }
-    if (sessionId) {
-        const current = loadCurrentSession(cwd);
-        if (!current || current.session_id !== sessionId) {
-            return;
+    // Clear the session for the current agent+user
+    const session = loadCurrentSession(cwd);
+    if (session) {
+        const filepath = sessionFilePath(session.session_id, cwd);
+        try {
+            fs.unlinkSync(filepath);
+        }
+        catch { /* ignore */ }
+    }
+    // Also clean legacy file
+    const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
+    try {
+        fs.unlinkSync(legacyPath);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Remove stale sessions that have exceeded the TTL.
+ * Returns the number of sessions removed.
+ */
+export function gcStaleSessions(cwd, ttlOverride) {
+    const dir = sessionsDir(cwd);
+    if (!fs.existsSync(dir))
+        return 0;
+    const ttlMs = parseDurationToMs(ttlOverride ?? loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
+    const now = Date.now();
+    let removed = 0;
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+        try {
+            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++;
+            }
+        }
+        catch {
+            // Remove unparseable files too
+            try {
+                fs.unlinkSync(path.join(dir, file));
+                removed++;
+            }
+            catch { /* ignore */ }
         }
     }
+    return removed;
+}
+// --- Internal helpers ---
+function sessionsDir(cwd) {
+    return path.join(memoryDir(cwd), SESSIONS_DIR);
+}
+function sessionFilePath(sessionId, cwd) {
+    return path.join(sessionsDir(cwd), `${sessionId}.json`);
+}
+function resolveCurrentUser() {
+    return process.env.USER || process.env.USERNAME || os.userInfo().username || undefined;
+}
+function resolveCurrentAgentName() {
+    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 {
-        fs.unlinkSync(filepath);
+        return loadConfig(cwd);
     }
     catch {
-        // Ignore cleanup races.
+        return undefined;
     }
 }
-function currentSessionPath(cwd) {
-    return path.join(memoryDir(cwd), CURRENT_SESSION_FILE);
+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(loadConfig(cwd).implicit_session_ttl ?? '4h');
+    const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
     const now = new Date();
-    if (current
-        && current.agent === options.agentName
-        && current.agent_id === options.agentId
-        && current.host_id === options.hostId
-        && now.getTime() - Date.parse(current.last_seen_at) <= ttlMs) {
+    const currentUser = resolveCurrentUser();
+    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: 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(),
@@ -126,10 +349,11 @@ function resolveImplicitSession(cwd, options) {
         agent: options.agentName,
         agent_id: options.agentId,
         host_id: options.hostId,
+        user: currentUser,
+        pid: currentPid,
     };
-    if (persistImplicit) {
+    if (persistImplicit)
         saveCurrentSession(created, cwd);
-    }
     return created;
 }
 function parseDurationToMs(value) {