brainclaw 0.28.0 → 0.29.2

package/dist/cli.js

@@ -1157,6 +1157,17 @@ program
         cwd: globalOpts.cwd,
     });
 });
+program
+    .command('who')
+    .description('Show active agent sessions on this workspace')
+    .option('--json', 'Output as JSON')
+    .option('--all', 'Include stale sessions')
+    .option('--gc', 'Remove stale sessions')
+    .action(async (options) => {
+    const globalOpts = program.opts();
+    const { runWho } = await import('./commands/who.js');
+    runWho({ json: options.json, all: options.all, gc: options.gc, cwd: globalOpts.cwd });
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/commands/mcp.js

@@ -9,6 +9,7 @@ import { buildContext, renderContextMarkdown, renderContextPromptTemplate } from
 import { buildExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
 import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
+import { loadAllSessions, gcStaleSessions } from '../core/identity.js';
 import { loadState, persistState, saveState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, listArchivedCandidates, listCandidates, saveCandidate } from '../core/candidates.js';
@@ -307,6 +308,17 @@ export const MCP_READ_TOOLS = [
             },
         },
     },
+    {
+        name: 'bclaw_who',
+        description: 'List all active agent sessions on this workspace. Shows user, agent, active project, claims, and last activity for each session.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                all: { type: 'boolean', description: 'Include stale sessions (default: false).' },
+                gc: { type: 'boolean', description: 'Remove stale sessions and return count.' },
+            },
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
     {
@@ -1767,6 +1779,42 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             structuredContent: { agent: currentAgentName, conflicts, total: conflicts.length, schema_version: SCHEMA_VERSION },
         };
     }
+    if (name === 'bclaw_who') {
+        // loadAllSessions and gcStaleSessions imported at top of file
+        const doGc = args.gc === true;
+        const showAll = args.all === true;
+        if (doGc) {
+            const removed = gcStaleSessions(cwd);
+            return {
+                content: [{ type: 'text', text: `✔ Removed ${removed} stale session(s).` }],
+                structuredContent: { gc: true, removed, schema_version: SCHEMA_VERSION },
+            };
+        }
+        const allSessions = loadAllSessions(cwd);
+        const ttlMs = 4 * 60 * 60 * 1000;
+        const now = Date.now();
+        const sessions = showAll
+            ? allSessions
+            : allSessions.filter((s) => (now - Date.parse(s.last_seen_at)) <= ttlMs);
+        const activeClaims = listClaims(cwd).filter((c) => c.status === 'active');
+        const output = sessions.map((s) => ({
+            session_id: s.session_id,
+            user: s.user ?? 'unknown',
+            agent: s.agent,
+            agent_id: s.agent_id,
+            project: s.active_project?.name ?? s.active_project?.path ?? null,
+            claims: activeClaims.filter((c) => c.agent_id === s.agent_id).length,
+            last_seen_at: s.last_seen_at,
+            stale: (now - Date.parse(s.last_seen_at)) > ttlMs,
+        }));
+        const lines = sessions.length === 0
+            ? 'No active sessions.'
+            : output.map((s) => `${s.user} | ${s.agent} | ${s.project ?? '(root)'} | ${s.claims} claims | ${s.stale ? 'stale' : 'active'}`).join('\n');
+        return {
+            content: [{ type: 'text', text: lines }],
+            structuredContent: { sessions: output, total: output.length, schema_version: SCHEMA_VERSION },
+        };
+    }
     if (name === 'bclaw_doctor') {
         // Capture doctor JSON output by redirecting console.log
         const captured = [];
@@ -2188,6 +2236,7 @@ export async function executeMcpToolCall(payload) {
                 id: claimId,
                 agent: identity.agent,
                 agent_id: identity.agent_id,
+                user: process.env.USER || process.env.USERNAME || undefined,
                 project_id: identity.project_id,
                 host_id: identity.host_id,
                 session_id: identity.session_id,

package/dist/commands/switch.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
+import { loadCurrentSession, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef, resolveWorkspaceRoot } from '../core/store-resolution.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
@@ -18,6 +19,11 @@ export function runSwitch(projectRef, options = {}) {
     }
     // --clear: remove active project
     if (options.clear) {
+        const session = loadCurrentSession(cwd);
+        if (session?.active_project) {
+            const { active_project: _removed, ...rest } = session;
+            saveCurrentSession(rest, cwd);
+        }
         clearActiveProject(wsRoot);
         if (options.json) {
             console.log(JSON.stringify({ cleared: true }));
@@ -47,18 +53,35 @@ export function runSwitch(projectRef, options = {}) {
     catch {
         // name is optional
     }
-    saveActiveProject(wsRoot, {
-        path: resolved,
-        name: projectName,
-        switched_at: new Date().toISOString(),
-        switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
-    });
+    const now = new Date().toISOString();
+    const session = loadCurrentSession(cwd);
+    const scopedToSession = options.session ?? !!session;
+    let scope;
+    if (scopedToSession && session) {
+        // Write to session state — only this agent sees this switch
+        saveCurrentSession({
+            ...session,
+            active_project: { path: resolved, name: projectName, switched_at: now },
+        }, cwd);
+        scope = 'session';
+    }
+    else {
+        // Fall back to global active-project.json
+        saveActiveProject(wsRoot, {
+            path: resolved,
+            name: projectName,
+            switched_at: now,
+            switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
+        });
+        scope = 'global';
+    }
     if (options.json) {
-        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName }));
+        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName, scope }));
     }
     else {
         const rel = path.relative(wsRoot, resolved) || '.';
-        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}`);
+        const scopeHint = scope === 'session' ? ' (session-scoped)' : '';
+        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}${scopeHint}`);
     }
 }
 function showCurrent(wsRoot, json) {

package/dist/commands/who.js

@@ -0,0 +1,96 @@
+import { loadAllSessions, gcStaleSessions } from '../core/identity.js';
+import { listClaims } from '../core/claims.js';
+export function runWho(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.gc) {
+        const removed = gcStaleSessions(cwd);
+        if (options.json) {
+            console.log(JSON.stringify({ gc: true, removed }));
+        }
+        else {
+            console.log(`✔ Removed ${removed} stale session(s).`);
+        }
+        return;
+    }
+    const allSessions = loadAllSessions(cwd);
+    const ttlMs = 4 * 60 * 60 * 1000; // 4h default
+    const now = Date.now();
+    const sessions = options.all
+        ? allSessions
+        : allSessions.filter(s => (now - Date.parse(s.last_seen_at)) <= ttlMs);
+    const activeClaims = listClaims(cwd).filter(c => c.status === 'active');
+    const enriched = sessions.map(s => {
+        const age = now - Date.parse(s.last_seen_at);
+        const stale = age > ttlMs;
+        const dead = s.pid ? !isPidAlive(s.pid) : false;
+        const status = dead ? 'dead' : stale ? 'stale' : 'active';
+        return {
+            session_id: s.session_id,
+            user: s.user ?? 'unknown',
+            agent: s.agent,
+            agent_id: s.agent_id,
+            host_id: s.host_id,
+            project: s.active_project?.name ?? s.active_project?.path ?? null,
+            claims: activeClaims.filter(c => c.agent_id === s.agent_id).length,
+            started_at: s.started_at,
+            last_seen_at: s.last_seen_at,
+            status,
+            pid: s.pid,
+        };
+    });
+    if (options.json) {
+        console.log(JSON.stringify({ sessions: enriched, total: enriched.length }, null, 2));
+        return;
+    }
+    if (enriched.length === 0) {
+        console.log('No active sessions.');
+        return;
+    }
+    // Table header
+    const header = ['USER', 'AGENT', 'PROJECT', 'CLAIMS', 'STATUS', 'LAST SEEN'];
+    const rows = [];
+    for (const s of enriched) {
+        const age = now - Date.parse(s.last_seen_at);
+        const project = s.project ?? '(workspace root)';
+        rows.push([
+            s.user,
+            s.agent,
+            project.length > 25 ? project.slice(0, 22) + '...' : project,
+            String(s.claims),
+            s.status,
+            formatAge(age),
+        ]);
+    }
+    // Calculate column widths
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => r[i].length)));
+    console.log('Active sessions:\n');
+    console.log('  ' + header.map((h, i) => h.padEnd(widths[i])).join('  '));
+    console.log('  ' + widths.map(w => '─'.repeat(w)).join('  '));
+    for (const row of rows) {
+        console.log('  ' + row.map((cell, i) => cell.padEnd(widths[i])).join('  '));
+    }
+    console.log(`\n${enriched.length} session(s).`);
+}
+function isPidAlive(pid) {
+    try {
+        // process.kill(pid, 0) throws if process doesn't exist
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatAge(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}min ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+//# sourceMappingURL=who.js.map

package/dist/core/bootstrap.js

@@ -8,7 +8,7 @@ import { resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
-import { analyzeRepository } from './repo-analysis.js';
+import { analyzeRepository, findNestedAgentsFiles } from './repo-analysis.js';
 import { buildExecutionContext, compactExecutionContext } from './execution-context.js';
 import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
@@ -101,6 +101,7 @@ export function runBootstrapProfile(options = {}) {
         importPlan,
         lastApplication,
         reusedProfile: false,
+        subProjects: artifacts.subProjects,
     };
 }
 export function listBootstrapSeeds(cwd) {
@@ -183,6 +184,18 @@ export function renderBootstrapSummary(result) {
     if (result.lastApplication && !result.lastApplication.uninstalled_at) {
         lines.push(`Last bootstrap import: ${result.lastApplication.managed_artifacts.length} managed artifact(s) from ${result.lastApplication.applied_at}`);
     }
+    if (result.subProjects && result.subProjects.length > 0) {
+        lines.push('');
+        lines.push(`Sub-projects discovered (${result.subProjects.length}):`);
+        for (const sp of result.subProjects.slice(0, 20)) {
+            lines.push(`  ${sp}`);
+        }
+        if (result.subProjects.length > 20) {
+            lines.push(`  ... and ${result.subProjects.length - 20} more`);
+        }
+        lines.push('');
+        lines.push('Use: brainclaw bootstrap --for <sub-project-path> --refresh');
+    }
     if (result.importPlan.suggestions.length > 0) {
         lines.push('');
         lines.push('Import proposal:');
@@ -231,14 +244,19 @@ export function renderBootstrapInterview(result, audience = 'any') {
 function buildBootstrapArtifacts(input) {
     const sourcesScanned = [];
     const seeds = [];
-    const workspace = classifyWorkspace(input.cwd);
-    const nativeInstructionFiles = discoverNativeInstructionFiles(input.cwd);
-    const readmePath = findFirstExisting(input.cwd, README_CANDIDATES);
+    // When target is an absolute directory path, use it as the scan root
+    // so that instruction files, README, and AGENTS.md are discovered from
+    // the target scope — not from the workspace root. This fixes bootstrap
+    // returning wrong signals for monorepo sub-projects.
+    const scanRoot = resolveBootstrapScanRoot(input.cwd, input.target);
+    const workspace = classifyWorkspace(scanRoot);
+    const nativeInstructionFiles = discoverNativeInstructionFiles(scanRoot);
+    const readmePath = findFirstExisting(scanRoot, README_CANDIDATES);
     if (readmePath) {
         sourcesScanned.push('README');
         seeds.push(...extractReadmeSeeds(readmePath, input.target));
     }
-    const agentsPath = path.join(input.cwd, 'AGENTS.md');
+    const agentsPath = path.join(scanRoot, 'AGENTS.md');
     const agentsPresent = fs.existsSync(agentsPath);
     if (agentsPresent) {
         sourcesScanned.push('AGENTS.md');
@@ -246,9 +264,9 @@ function buildBootstrapArtifacts(input) {
     }
     if (nativeInstructionFiles.length > 0) {
         sourcesScanned.push('native_instructions');
-        seeds.push(...extractNativeInstructionSeeds(nativeInstructionFiles.map((relativePath) => path.join(input.cwd, relativePath)), input.cwd, input.target));
+        seeds.push(...extractNativeInstructionSeeds(nativeInstructionFiles.map((relativePath) => path.join(scanRoot, relativePath)), scanRoot, input.target));
     }
-    const manifestResult = extractManifestSeeds(input.cwd, input.target);
+    const manifestResult = extractManifestSeeds(scanRoot, input.target);
     if (manifestResult.seeds.length > 0) {
         sourcesScanned.push(...manifestResult.sources);
         seeds.push(...manifestResult.seeds);
@@ -265,16 +283,16 @@ function buildBootstrapArtifacts(input) {
         sourcesScanned.push('local_mcp');
         seeds.push(...extractMcpSeeds(agentTooling.mcp_servers, input.target));
     }
-    const repoAnalysis = analyzeRepository(input.cwd);
+    const repoAnalysis = analyzeRepository(scanRoot);
     sourcesScanned.push('repo-analysis');
     seeds.push(...extractRepoAnalysisSeeds(repoAnalysis, input.target));
     // Additional brownfield sources (step 12)
-    const additionalSeeds = extractAdditionalBrownfieldSeeds(input.cwd, input.target);
+    const additionalSeeds = extractAdditionalBrownfieldSeeds(scanRoot, input.target);
     if (additionalSeeds.seeds.length > 0) {
         sourcesScanned.push(...additionalSeeds.sources);
         seeds.push(...additionalSeeds.seeds);
     }
-    const gitProbe = probeGit(input.cwd, input.target);
+    const gitProbe = probeGit(scanRoot, input.target);
     if (gitProbe.available) {
         sourcesScanned.push('git');
         seeds.push(...gitProbe.hotspotSeeds);
@@ -342,6 +360,13 @@ function buildBootstrapArtifacts(input) {
             schema_version: DERIVED_SCHEMA_VERSION,
         })),
         importPlan,
+        // For multi-project workspaces without a target, list discovered sub-projects
+        subProjects: (!input.target && repoAnalysis.recommendedMode === 'multi-project')
+            ? findNestedAgentsFiles(scanRoot, 8)
+                .filter((p) => p !== 'AGENTS.md') // exclude root AGENTS.md
+                .map((p) => path.dirname(p))
+                .filter((d) => d !== '.')
+            : undefined,
     };
 }
 function extractReadmeSeeds(filepath, target) {
@@ -846,6 +871,9 @@ function buildSummary(input) {
     parts.push(`Onboarding mode: ${input.onboardingMode}.`);
     parts.push(`Confidence: ${input.confidence}.`);
     parts.push(`Repository mode looks ${input.repoAnalysis.recommendedMode}.`);
+    if (input.repoAnalysis.recommendedMode === 'multi-project' && !input.target) {
+        parts.push('This is a multi-project workspace — use --for <path> to bootstrap a specific sub-project.');
+    }
     if (input.agentsPresent) {
         parts.push('AGENTS.md detected and summarized.');
     }
@@ -1639,6 +1667,29 @@ function normalizeTarget(target) {
     const trimmed = target?.trim();
     return trimmed && trimmed.length > 0 ? trimmed : undefined;
 }
+/**
+ * Resolve where to scan for project files (README, AGENTS.md, manifests).
+ * If target is an absolute directory path, scan from there.
+ * Otherwise fall back to cwd (the workspace/store root).
+ */
+function resolveBootstrapScanRoot(cwd, target) {
+    if (!target)
+        return cwd;
+    const resolved = path.isAbsolute(target) ? target : path.resolve(cwd, target);
+    try {
+        if (fs.statSync(resolved).isDirectory())
+            return resolved;
+    }
+    catch { /* not a directory or doesn't exist */ }
+    // Target is a file path or glob — use its parent directory if it exists
+    const parent = path.dirname(resolved);
+    try {
+        if (fs.statSync(parent).isDirectory())
+            return parent;
+    }
+    catch { /* fall back to cwd */ }
+    return cwd;
+}
 // ─── Step 12: Additional brownfield sources ──────────────────────────────────
 const CI_WORKFLOW_DIRS = ['.github/workflows', '.gitlab'];
 const CI_FILES = ['.gitlab-ci.yml', 'Jenkinsfile', '.circleci/config.yml'];

package/dist/core/context.js

@@ -1,5 +1,8 @@
 import path from 'node:path';
+import { loadActiveProject } from './active-project.js';
+import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from './brainclaw-version.js';
 import { loadConfig } from './config.js';
+import { loadCurrentSession, loadAllSessions } from './identity.js';
 import { resolveCrossProjectLinks, loadCrossProjectState } from './cross-project.js';
 import { buildContextDiff } from './context-diff.js';
 import { resolveContextStoreCwd, resolveStoreChain } from './store-resolution.js';
@@ -502,6 +505,7 @@ export function buildContext(options = {}) {
                 return undefined;
             }
         })(),
+        active_project: findActiveProjectInChain(contextCwd, storeChain),
         cross_project_items: crossProjectItems.length > 0 ? crossProjectItems : undefined,
         claim_conflicts: detectClaimConflicts(myClaims, otherActiveClaims),
         workflow_hints: buildWorkflowHints(myClaims, openWork, state.plan_items),
@@ -550,7 +554,43 @@ export function renderContextMarkdown(result, explain = false) {
         lines.push(`Agent ID: ${result.agent_id}`);
     }
     lines.push(`Project mode: ${result.project_mode} (${result.project_strategy})`);
+    if (result.active_project) {
+        const ap = result.active_project;
+        const age = Math.floor((Date.now() - Date.parse(ap.switched_at)) / 3_600_000);
+        const sourceHint = ap.source === 'session' ? ', session-scoped' : ', global';
+        lines.push(`Active project: ${ap.name ?? ap.path} (switched ${age}h ago by ${ap.switched_by ?? 'unknown'}${sourceHint})`);
+        if (ap.source === 'global') {
+            lines.push(`  ⚠ This is a global switch — all agents on this host see the same project. Use \`brainclaw switch <project>\` during a session for agent-scoped switching.`);
+        }
+        lines.push(`  All commands target this project. Use \`brainclaw switch --clear\` to return to workspace root or \`brainclaw switch <project>\` to change.`);
+    }
     lines.push(`Current host: ${result.current_host}`);
+    // Show other active sessions
+    try {
+        const allSessions = loadAllSessions();
+        const ttlMs = 4 * 60 * 60 * 1000;
+        const now = Date.now();
+        const otherSessions = allSessions.filter(s => s.agent_id !== result.agent_id
+            && (now - Date.parse(s.last_seen_at)) <= ttlMs);
+        if (otherSessions.length > 0) {
+            const summaries = otherSessions.map(s => {
+                const proj = s.active_project?.name ?? s.active_project?.path;
+                return `${s.user ?? 'unknown'}/${s.agent}${proj ? ` on ${proj}` : ''}`;
+            });
+            lines.push(`Other active agents: ${summaries.join(', ')}`);
+        }
+    }
+    catch { /* ignore — sessions dir may not exist yet */ }
+    // Check for brainclaw update (lightweight local manifest read only)
+    try {
+        const config = loadConfig();
+        const updateCheck = checkBrainclawInstallableUpdate(config, process.cwd());
+        const notice = renderBrainclawInstallableUpdateNotice(updateCheck);
+        if (notice) {
+            lines.push(`⚠ ${notice}`);
+        }
+    }
+    catch { /* ignore — update check is best-effort */ }
     lines.push(`Memory version: ${result.memory_version}`);
     lines.push(`Memory density: ${result.memory_density}`);
     lines.push(`Bootstrap available: ${result.bootstrap_available ? 'yes' : 'no'}`);
@@ -758,6 +798,11 @@ export function renderContextPromptTemplate(result, compact = false) {
         }
         lines.push(`project_mode: ${result.project_mode}`);
         lines.push(`project_strategy: ${result.project_strategy}`);
+        if (result.active_project) {
+            lines.push(`active_project: ${result.active_project.name ?? result.active_project.path}`);
+            lines.push(`active_project_switched: ${result.active_project.switched_at}`);
+            lines.push(`active_project_source: ${result.active_project.source ?? 'global'}`);
+        }
         lines.push(`current_host: ${result.current_host}`);
         lines.push(`memory_version: ${result.memory_version}`);
         lines.push(`memory_density: ${result.memory_density}`);
@@ -1303,6 +1348,34 @@ function scopesOverlap(a, b) {
     }
     return null;
 }
+// --- Active project resolution ---
+function findActiveProjectInChain(contextCwd, _storeChain) {
+    // 1. Session-scoped active project (per-agent, highest priority)
+    const session = loadCurrentSession(contextCwd);
+    if (session?.active_project) {
+        return {
+            path: session.active_project.path,
+            name: session.active_project.name,
+            switched_at: session.active_project.switched_at,
+            switched_by: session.agent,
+            source: 'session',
+        };
+    }
+    // 2. Global active-project.json (walk up from contextCwd)
+    let dir = path.resolve(contextCwd);
+    const root = path.parse(dir).root;
+    const home = process.env.HOME || process.env.USERPROFILE || root;
+    while (dir !== root && dir !== home) {
+        const ap = loadActiveProject(dir);
+        if (ap)
+            return { ...ap, source: 'global' };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
 // --- Workflow hints ---
 function buildWorkflowHints(myClaims, openWork, plans) {
     const hints = [];

package/dist/core/event-log.js

@@ -12,6 +12,7 @@ export function appendEvent(event, cwd) {
             ts: event.ts ?? nowISO(),
             agent: event.agent ?? 'unknown',
             agent_id: event.agent_id,
+            user: event.user ?? process.env.USER ?? process.env.USERNAME,
             action: event.action,
             item_type: event.item_type,
             item_id: event.item_id,

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,11 +67,54 @@ 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)) {
+        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 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) {
+                    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 {
+            return CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', legacyPath).document);
+        }
+        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);
     }
@@ -76,43 +122,134 @@ export function loadCurrentSession(cwd) {
         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 {
+            sessions.push(CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', path.join(dir, file)).document));
+        }
+        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(filepath);
+        fs.unlinkSync(legacyPath);
     }
-    catch {
-        // Ignore cleanup races.
+    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 session = CurrentSessionStateSchema.parse(loadVersionedJsonFile('current_session', path.join(dir, file)).document);
+            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 currentSessionPath(cwd) {
-    return path.join(memoryDir(cwd), CURRENT_SESSION_FILE);
+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;
+}
+function loadConfigSafe(cwd) {
+    try {
+        return loadConfig(cwd);
+    }
+    catch {
+        return undefined;
+    }
 }
 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();
+    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 refreshed = {
             ...current,
             last_seen_at: now.toISOString(),
+            user: current.user || currentUser,
+            pid: process.pid,
         };
         if (persistImplicit) {
             saveCurrentSession(refreshed, cwd);
@@ -126,6 +263,8 @@ function resolveImplicitSession(cwd, options) {
         agent: options.agentName,
         agent_id: options.agentId,
         host_id: options.hostId,
+        user: currentUser,
+        pid: process.pid,
     };
     if (persistImplicit) {
         saveCurrentSession(created, cwd);

package/dist/core/repo-analysis.js

@@ -50,6 +50,16 @@ export function analyzeRepository(cwd) {
     if (matchedDirs.length > 0) {
         reasons.push(`Found top-level project folders: ${matchedDirs.join(', ')}`);
     }
+    // ── Signal 4: Multiple AGENTS.md files in the tree ──
+    const agentsFiles = findNestedAgentsFiles(cwd, 8);
+    if (agentsFiles.length > 1) {
+        reasons.push(`Found ${agentsFiles.length} AGENTS.md files: ${agentsFiles.slice(0, 5).join(', ')}${agentsFiles.length > 5 ? ` (+${agentsFiles.length - 5} more)` : ''}`);
+    }
+    // ── Signal 5: Multiple Dockerfiles or docker-compose files (service-oriented workspace) ──
+    const dockerComposeFiles = findFilesShallow(cwd, ['docker-compose.yml', 'docker-compose.yaml'], 6);
+    if (dockerComposeFiles.length > 1) {
+        reasons.push(`Found ${dockerComposeFiles.length} docker-compose files`);
+    }
     const packageJsonPath = path.join(cwd, 'package.json');
     if (fs.existsSync(packageJsonPath)) {
         try {
@@ -184,4 +194,61 @@ export function scanWorkspaceBoundaries(rootDir, maxDepth = 3) {
     walk(rootDir, 1);
     return { suggestions, alreadyInitialised };
 }
+/**
+ * Find AGENTS.md files up to maxDepth levels deep.
+ * Returns relative paths from cwd.
+ */
+export function findNestedAgentsFiles(cwd, maxDepth) {
+    const results = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth || results.length > 10)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === 'AGENTS.md') {
+                results.push(path.relative(cwd, path.join(dir, entry.name)));
+            }
+            if (entry.isDirectory() && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                walk(path.join(dir, entry.name), depth + 1);
+            }
+        }
+    }
+    walk(cwd, 0);
+    return results;
+}
+/**
+ * Find specific filenames up to maxDepth levels deep.
+ * Returns relative paths from cwd.
+ */
+function findFilesShallow(cwd, filenames, maxDepth) {
+    const nameSet = new Set(filenames);
+    const results = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth || results.length > 10)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && nameSet.has(entry.name)) {
+                results.push(path.relative(cwd, path.join(dir, entry.name)));
+            }
+            if (entry.isDirectory() && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                walk(path.join(dir, entry.name), depth + 1);
+            }
+        }
+    }
+    walk(cwd, 0);
+    return results;
+}
 //# sourceMappingURL=repo-analysis.js.map

package/dist/core/schema.js

@@ -33,6 +33,30 @@ function coerceEffortToMinutes(val) {
     }
     return undefined;
 }
+/** Coerce tags from JSON string to array when MCP clients serialize arrays as strings.
+ *  Accepts: string[] (passthrough), '["a","b"]' (JSON parse), 'a,b' (comma split). */
+function coerceTags(val) {
+    if (Array.isArray(val))
+        return val;
+    if (typeof val === 'string') {
+        const trimmed = val.trim();
+        if (trimmed.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (Array.isArray(parsed))
+                    return parsed;
+            }
+            catch { /* fall through */ }
+        }
+        if (trimmed.length > 0)
+            return trimmed.split(',').map(t => t.trim()).filter(Boolean);
+        return [];
+    }
+    return val;
+}
+/** Resilient tags schema that accepts string[] or JSON-serialized string. */
+export const TagsSchema = z.preprocess(coerceTags, z.array(z.string()));
+export const TagsWithDefaultSchema = z.preprocess(coerceTags, z.array(z.string()).default([]));
 // --- Entry schemas ---
 export const ConstraintStatusSchema = z.enum(['active', 'resolved', 'expired']);
 export const ConstraintCategorySchema = z.enum(['architecture', 'performance', 'security', 'reliability', 'compatibility', 'process', 'other']);
@@ -58,7 +82,7 @@ export const ConstraintSchema = z.object({
     status: ConstraintStatusSchema,
     category: ConstraintCategorySchema.optional(),
     scope: MemoryScopeSchema.optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     expires_at: z.string().optional(),
 });
@@ -78,7 +102,7 @@ export const DecisionSchema = z.object({
     scope: MemoryScopeSchema.optional(),
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
 });
 export const TrapSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -94,7 +118,7 @@ export const TrapSchema = z.object({
     status: TrapStatusSchema.default('active'),
     severity: SeveritySchema,
     scope: MemoryScopeSchema.optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
     visibility: MemoryVisibilitySchema.default('shared'),
@@ -119,7 +143,7 @@ export const HandoffSchema = z.object({
     status: HandoffStatusSchema,
     project: z.string().optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     snapshot: z.object({
         diff: z.string().optional(),
@@ -150,7 +174,7 @@ export const PlanItemSchema = z.object({
     priority: PrioritySchema,
     assignee: z.string().optional(),
     project: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     depends_on: z.array(z.string()).default([]),
     steps: z.array(PlanStepSchema).optional(),
@@ -170,7 +194,7 @@ export const InstructionEntrySchema = z.object({
     updated_at: z.string(),
     author: z.string(),
     model: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     active: z.boolean().default(true),
     supersedes: z.string().optional(),
 });
@@ -183,7 +207,7 @@ export const ProjectCapabilitySchema = z.object({
     category: z.string(), // e.g. "auth", "api", "storage", "testing"
     provided_by: z.string().optional(), // path to implementation
     requires: z.array(z.string()).optional(), // capability IDs this depends on
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     example_usage: z.string().optional(),
     status: CapabilityStatusSchema.default('stable'),
     related_paths: z.array(z.string()).optional(),
@@ -205,7 +229,7 @@ export const ProjectToolSchema = z.object({
     requires: z.array(z.string()).optional(), // tool IDs this depends on
     suggests_for: z.array(z.string()).optional(), // agent types or domains
     invocation_example: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     status: CapabilityStatusSchema.default('stable'),
     related_paths: z.array(z.string()).optional(),
     created_at: z.string(),
@@ -271,7 +295,7 @@ export const CandidateSchema = z.object({
     host_id: z.string().optional(),
     session_id: z.string().optional(),
     source: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     status: CandidateStatusSchema,
     // type-specific optional fields
     severity: SeveritySchema.optional(),
@@ -324,6 +348,8 @@ export const ClaimSchema = z.object({
     id: z.string(),
     agent: z.string(),
     agent_id: z.string().optional(),
+    /** OS user who created this claim. */
+    user: z.string().optional(),
     project_id: z.string().optional(),
     host_id: z.string().optional(),
     session_id: z.string().optional(),
@@ -349,7 +375,7 @@ export const RuntimeNoteSchema = z.object({
     created_at: z.string(),
     project: z.string().optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
@@ -376,7 +402,7 @@ export const AiSurfaceTaskRequestSchema = z.object({
     status: AiSurfaceTaskStatusSchema.default('queued'),
     requested_outputs: z.array(z.string()).default([]),
     related_paths: z.array(z.string()).optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     claimed_at: z.string().optional(),
     completed_at: z.string().optional(),
     result_note: z.string().optional(),
@@ -402,7 +428,7 @@ export const RuntimeEventSchema = z.object({
     event_type: RuntimeEventTypeSchema,
     created_at: z.string(),
     text: z.string(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     // Optional routing and type hints for candidate generation
     candidate_type: CandidateTypeSchema.optional(),
     severity: SeveritySchema.optional(),
@@ -468,6 +494,14 @@ export const SessionSnapshotSchema = z.object({
     initial_context_hash: z.string().optional(),
     git_sha: z.string().optional(),
 });
+export const SessionActiveProjectSchema = z.object({
+    /** Absolute path to the project directory. */
+    path: z.string(),
+    /** Project name from config.yaml (when available). */
+    name: z.string().optional(),
+    /** ISO timestamp of the switch. */
+    switched_at: z.string(),
+}).strict();
 export const CurrentSessionStateSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     session_id: z.string(),
@@ -476,6 +510,12 @@ export const CurrentSessionStateSchema = z.object({
     agent: z.string(),
     agent_id: z.string(),
     host_id: z.string(),
+    /** OS user who started this session. */
+    user: z.string().optional(),
+    /** Process ID of the agent process (for liveness detection). */
+    pid: z.number().int().positive().optional(),
+    /** Session-scoped active project (overrides global active-project.json). */
+    active_project: SessionActiveProjectSchema.optional(),
 });
 export const MemorySeedKindSchema = z.enum([
     'command',
@@ -516,7 +556,7 @@ export const MemorySeedDocumentSchema = z.object({
     source_ref: z.string(),
     confidence: MemorySeedConfidenceSchema,
     related_paths: z.array(z.string()).optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     promotion_hint: z.enum(['constraint', 'decision', 'trap']).optional(),
 });
 export const BootstrapProfileDocumentSchema = z.object({
@@ -547,7 +587,7 @@ export const BootstrapSuggestionDocumentSchema = z.object({
     source_refs: z.array(z.string()).default([]),
     layer: z.enum(['global', 'project', 'agent']).optional(),
     scope: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     related_paths: z.array(z.string()).optional(),
     category: ConstraintCategorySchema.optional(),
     outcome: DecisionOutcomeSchema.optional(),
@@ -581,7 +621,7 @@ export const BootstrapInterviewAnswerSuggestionSchema = z.object({
     confidence: MemorySeedConfidenceSchema.optional(),
     layer: z.enum(['global', 'project', 'agent']).optional(),
     scope: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     related_paths: z.array(z.string()).optional(),
     category: ConstraintCategorySchema.optional(),
     outcome: DecisionOutcomeSchema.optional(),

package/dist/core/store-resolution.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { loadActiveProject } from './active-project.js';
 import { loadConfig } from './config.js';
+import { loadCurrentSession } from './identity.js';
 import { MEMORY_DIR } from './io.js';
 import { summarizeWorkspaceProjects } from './workspace-projects.js';
 /**
@@ -91,8 +92,9 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
  * Priority:
  * 1. explicitCwd (--cwd flag)
  * 2. BRAINCLAW_PROJECT env var → resolved by name/path from workspace
- * 3. active-project.json in workspace root
- * 4. process.cwd()
+ * 3. Session-scoped active project (from .current-session)
+ * 4. Global active-project.json in workspace root
+ * 5. process.cwd()
  */
 export function resolveEffectiveCwd(options = {}) {
     // 1. Explicit --cwd flag
@@ -106,7 +108,15 @@ export function resolveEffectiveCwd(options = {}) {
         if (resolved)
             return resolved;
     }
-    // 3. active-project.json from workspace root
+    // 3. Session-scoped active project (per-agent, no cross-agent interference)
+    const session = loadCurrentSession(process.cwd());
+    if (session?.active_project) {
+        const sp = session.active_project;
+        if (fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
+            return sp.path;
+        }
+    }
+    // 4. Global active-project.json from workspace root
     const wsRoot = resolveWorkspaceRoot(process.cwd(), options.storeChainOptions);
     if (wsRoot) {
         const active = loadActiveProject(wsRoot);
@@ -114,7 +124,7 @@ export function resolveEffectiveCwd(options = {}) {
             return active.path;
         }
     }
-    // 4. Default
+    // 5. Default
     return process.cwd();
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.28.0",
+  "version": "0.29.2",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   "license": "BUSL-1.1",
   "homepage": "https://brainclaw.dev",
   "engines": {
-    "node": ">=20"
+    "node": ">=18.0.0"
   },
   "dependencies": {
     "commander": "^13.1.0",