brainclaw 0.28.0 → 1.5.3

package/dist/core/assignments.js

@@ -0,0 +1,367 @@
+import fs from 'node:fs';
+import { AssignmentSchema } from './schema.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
+import { nowISO, generateIdWithLabel } from './ids.js';
+import { JsonStore } from './json-store.js';
+import { appendAuditEntry } from './audit.js';
+import { appendEvent } from './event-log.js';
+import { createRuntimeEvent } from './events.js';
+import { findLatestAgentRunForAssignment, recordAgentRunProgress, syncAgentRunFromAssignmentTransition } from './agentruns.js';
+// ── Directory / Store ────────────────────────────────────────
+function assignmentsDir(cwd, mode = 'read') {
+    return resolveEntityDir('assignments', cwd, mode);
+}
+function ensureAssignmentsDir(cwd) {
+    const dir = assignmentsDir(cwd, 'write');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function assignmentStore(cwd) {
+    return new JsonStore({
+        dirPath: assignmentsDir(cwd, 'read'),
+        documentType: 'assignment',
+        getId: (a) => a.id,
+        sort: (a, b) => a.created_at.localeCompare(b.created_at),
+    });
+}
+// ── CRUD ─────────────────────────────────────────────────────
+export function saveAssignment(assignment, cwd) {
+    mutate({ cwd }, () => {
+        ensureAssignmentsDir(cwd);
+        const store = new JsonStore({
+            dirPath: assignmentsDir(cwd, 'write'),
+            documentType: 'assignment',
+            getId: (a) => a.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        store.save(AssignmentSchema.parse(assignment));
+    });
+}
+export function loadAssignment(id, cwd) {
+    // JsonStore.load throws when the id is missing; honor the declared
+    // "| undefined" return type so callers (e.g. transitionAssignment)
+    // can emit their own 'Assignment not found' error with the right wording.
+    try {
+        return assignmentStore(cwd).load(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listAssignments(cwd, filter) {
+    let items = assignmentStore(cwd).list();
+    if (filter?.status)
+        items = items.filter((a) => a.status === filter.status);
+    if (filter?.agent)
+        items = items.filter((a) => a.agent === filter.agent);
+    if (filter?.claim_id)
+        items = items.filter((a) => a.claim_id === filter.claim_id);
+    if (filter?.plan_id)
+        items = items.filter((a) => a.plan_id === filter.plan_id);
+    if (filter?.sequence_id)
+        items = items.filter((a) => a.sequence_id === filter.sequence_id);
+    return items;
+}
+// ── ID Generation ────────────────────────────────────────────
+export function generateAssignmentId(cwd) {
+    return generateIdWithLabel('assignments', cwd);
+}
+// ── Status FSM ───────────────────────────────────────────────
+/** Valid transitions: from → Set<to>.
+ *
+ * `rerouted` is reachable from every non-terminal state (pln#451 / trp#61):
+ * rerouting a claim must close the predecessor assignment regardless of where
+ * it was in the FSM. Previously only `blocked` could reach `rerouted`, which
+ * left assignments stuck in `created` or `offered` when the coordinator
+ * rerouted a still-unstarted lane.
+ */
+const VALID_TRANSITIONS = new Map([
+    ['created', new Set(['offered', 'rerouted'])],
+    ['offered', new Set(['accepted', 'failed', 'expired', 'rerouted'])],
+    ['accepted', new Set(['started', 'timed_out', 'rerouted'])],
+    ['started', new Set(['completed', 'failed', 'blocked', 'timed_out', 'rerouted'])],
+    ['failed', new Set(['retrying', 'rerouted'])],
+    ['timed_out', new Set(['retrying', 'rerouted'])],
+    ['retrying', new Set(['offered', 'rerouted'])],
+    ['blocked', new Set(['rerouted', 'started', 'failed'])],
+    // Terminal: completed, expired, rerouted (no outgoing transitions)
+]);
+export function validateTransition(from, to) {
+    const allowed = VALID_TRANSITIONS.get(from);
+    if (!allowed || !allowed.has(to)) {
+        return { valid: false, reason: `Invalid transition: ${from} → ${to}` };
+    }
+    return { valid: true };
+}
+/**
+ * Transition an assignment to a new status with FSM validation.
+ * Same-status transitions are idempotent no-ops (returns current state
+ * with idempotent=true instead of throwing). This handles network retries
+ * where a worker calls accepted/started again after a timeout.
+ * Updates relevant timestamps, emits event and audit entry.
+ */
+export function transitionAssignment(id, newStatus, options, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        throw new Error(`Assignment not found: ${id}`);
+    }
+    // Idempotent: same-status transition is a no-op (handles network retries)
+    if (assignment.status === newStatus) {
+        // Still update heartbeat for liveness tracking
+        assignment.last_heartbeat_at = nowISO();
+        assignment.updated_at = assignment.last_heartbeat_at;
+        saveAssignment(assignment, cwd);
+        return { assignment, previous_status: newStatus, idempotent: true };
+    }
+    const validation = validateTransition(assignment.status, newStatus);
+    if (!validation.valid) {
+        throw new Error(validation.reason);
+    }
+    const previous_status = assignment.status;
+    const now = nowISO();
+    // Update status
+    assignment.status = newStatus;
+    assignment.updated_at = now;
+    assignment.last_heartbeat_at = now;
+    if (options.status_reason)
+        assignment.status_reason = options.status_reason;
+    if (options.session_id)
+        assignment.session_id = options.session_id;
+    if (options.error_message)
+        assignment.error_message = options.error_message;
+    if (options.artifacts?.length) {
+        assignment.artifacts = [...assignment.artifacts, ...options.artifacts];
+    }
+    // Set transition-specific timestamps
+    switch (newStatus) {
+        case 'offered':
+            assignment.offered_at = now;
+            break;
+        case 'accepted':
+            assignment.accepted_at = now;
+            break;
+        case 'started':
+            assignment.started_at = now;
+            break;
+        case 'completed':
+            assignment.completed_at = now;
+            break;
+        case 'failed':
+            assignment.failed_at = now;
+            break;
+        case 'blocked':
+            assignment.blocked_at = now;
+            break;
+        case 'timed_out':
+            assignment.timed_out_at = now;
+            break;
+        case 'expired':
+            assignment.expired_at = now;
+            break;
+        case 'rerouted':
+            assignment.rerouted_at = now;
+            break;
+    }
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, `assignment_${newStatus}`, options.actor, cwd);
+    if (options.syncAgentRun !== false) {
+        try {
+            syncAgentRunFromAssignmentTransition(assignment, newStatus, {
+                actor: options.actor,
+                actor_id: options.actor_id,
+                session_id: options.session_id,
+                status_reason: options.status_reason,
+                artifacts: options.artifacts,
+                error_message: options.error_message,
+            }, cwd);
+        }
+        catch {
+            /* best-effort: run state should not break assignment lifecycle */
+        }
+    }
+    appendAuditEntry({
+        actor: options.actor ?? assignment.agent,
+        actor_id: options.actor_id,
+        action: 'update',
+        item_id: assignment.id,
+        item_type: 'assignment',
+        before: { status: previous_status },
+        after: { status: newStatus, reason: options.status_reason },
+        scope: assignment.scope,
+        session_id: options.session_id,
+    }, cwd);
+    return { assignment, previous_status };
+}
+/**
+ * Record progress on a started assignment (heartbeat).
+ * Updates last_heartbeat_at without changing status.
+ */
+export function recordProgress(id, options, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        throw new Error(`Assignment not found: ${id}`);
+    }
+    if (assignment.status !== 'started') {
+        throw new Error(`Cannot record progress: assignment ${id} is ${assignment.status}, expected started`);
+    }
+    const now = nowISO();
+    assignment.last_heartbeat_at = now;
+    assignment.updated_at = now;
+    if (options.message)
+        assignment.status_reason = options.message;
+    if (options.artifacts?.length) {
+        assignment.artifacts = [...assignment.artifacts, ...options.artifacts];
+    }
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, 'assignment_progress', options.actor, cwd);
+    try {
+        const latestRun = findLatestAgentRunForAssignment(assignment.id, cwd);
+        if (latestRun) {
+            recordAgentRunProgress(latestRun.id, {
+                message: options.message,
+                artifacts: options.artifacts,
+                actor: options.actor,
+                actor_id: options.actor_id,
+                session_id: options.session_id,
+            }, cwd);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return assignment;
+}
+/**
+ * Create a new assignment. Called by the dispatcher after creating a claim
+ * and sending an inbox message.
+ */
+export function createAssignment(options, cwd) {
+    const generated = options.id ? undefined : generateAssignmentId(cwd);
+    const id = options.id ?? generated.id;
+    const short_label = options.short_label ?? generated.short_label;
+    const assignment = AssignmentSchema.parse({
+        schema_version: 1,
+        id,
+        short_label,
+        claim_id: options.claim_id,
+        message_id: options.message_id,
+        plan_id: options.plan_id,
+        sequence_id: options.sequence_id,
+        correlation_id: options.correlation_id,
+        agent: options.agent,
+        agent_id: options.agent_id,
+        dispatcher_agent: options.dispatcher_agent,
+        dispatcher_session_id: options.dispatcher_session_id,
+        scope: options.scope,
+        description: options.description,
+        lane: options.lane,
+        worktree_path: options.worktree_path,
+        status: 'created',
+        created_at: nowISO(),
+        heartbeat_ttl_ms: options.heartbeat_ttl_ms,
+        acceptance_ttl_ms: options.acceptance_ttl_ms,
+        max_retries: options.max_retries,
+        retry_count: 0,
+        artifacts: [],
+        tags: options.tags ?? [],
+    });
+    saveAssignment(assignment, cwd);
+    emitAssignmentEvent(assignment, 'assignment_created', options.dispatcher_agent, cwd);
+    appendAuditEntry({
+        actor: options.dispatcher_agent,
+        action: 'create',
+        item_id: assignment.id,
+        item_type: 'assignment',
+        after: { agent: options.agent, scope: options.scope, claim_id: options.claim_id },
+    }, cwd);
+    return assignment;
+}
+// ── Active Assignment Lookup ─────────────────────────────────
+/** Statuses that indicate a finished assignment (no longer active). */
+const TERMINAL_STATUSES = new Set(['completed', 'expired', 'rerouted']);
+/**
+ * Return the most recently created non-terminal assignment for the given agent.
+ * When `claimId` is provided, it is used as a fast-path lookup before falling
+ * back to an agent-wide scan.
+ */
+export function getActiveAssignmentForAgent(agentId, cwd, claimId) {
+    if (claimId) {
+        const byClaim = listAssignments(cwd, { claim_id: claimId });
+        const active = byClaim.filter((a) => !TERMINAL_STATUSES.has(a.status));
+        // listAssignments returns ascending-by-created_at — last is most recent
+        if (active.length > 0)
+            return active[active.length - 1];
+    }
+    if (!agentId)
+        return undefined;
+    const all = listAssignments(cwd);
+    const active = all.filter((a) => a.agent_id === agentId && !TERMINAL_STATUSES.has(a.status));
+    return active.length > 0 ? active[active.length - 1] : undefined;
+}
+/**
+ * Bump `last_heartbeat_at` on the most recent active assignment for the given
+ * claim (or agent). Best-effort — throws are suppressed by the caller.
+ */
+export function bumpActiveAssignmentHeartbeat(claimId, agentId, cwd) {
+    const assignment = getActiveAssignmentForAgent(agentId ?? '', cwd, claimId);
+    if (!assignment)
+        return false;
+    const now = nowISO();
+    assignment.last_heartbeat_at = now;
+    assignment.updated_at = now;
+    saveAssignment(assignment, cwd);
+    return true;
+}
+// ── Post-creation patches ────────────────────────────────────
+/** Attach the inbox message_id after the message has been sent (message is created after assignment). */
+export function patchAssignmentMessageId(id, messageId, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment)
+        return;
+    assignment.message_id = messageId;
+    saveAssignment(assignment, cwd);
+}
+// ── Event Emission ───────────────────────────────────────────
+function emitAssignmentEvent(assignment, action, actor, cwd) {
+    const text = `${assignment.description} [${assignment.status}]${assignment.status_reason ? ` — ${assignment.status_reason}` : ''}`;
+    appendEvent({
+        ts: nowISO(),
+        agent: actor ?? assignment.agent,
+        agent_id: assignment.agent_id,
+        action: action,
+        item_type: 'assignment',
+        item_id: assignment.id,
+        summary: `${assignment.status}: ${assignment.description.slice(0, 80)}`,
+    }, cwd);
+    try {
+        createRuntimeEvent({
+            agent: actor ?? assignment.agent,
+            agent_id: assignment.agent_id,
+            project_id: undefined,
+            session_id: assignment.session_id,
+            event_type: action,
+            text,
+            tags: ['agent-runtime', 'assignment'],
+            assignment_id: assignment.id,
+            claim_id: assignment.claim_id,
+            message_id: assignment.message_id,
+            plan_id: assignment.plan_id,
+            sequence_id: assignment.sequence_id,
+            correlation_id: assignment.correlation_id,
+            scope: assignment.scope,
+            status: assignment.status,
+            status_reason: assignment.status_reason,
+            related_paths: [assignment.scope],
+            metadata: {
+                dispatcher_agent: assignment.dispatcher_agent,
+                protocol: 'brainclaw.agent_runtime.v0',
+            },
+        }, cwd);
+    }
+    catch {
+        /* best-effort: runtime event emission should not break assignment lifecycle */
+    }
+}
+//# sourceMappingURL=assignments.js.map

package/dist/core/audit.js

@@ -6,6 +6,7 @@ import { nowISO } from './ids.js';
 import { logger } from './logger.js';
 import { appendEvent } from './event-log.js';
 const AUDIT_LOG_FILE = 'audit.log';
+const MAX_AUDIT_LOG_BYTES = 10 * 1024 * 1024; // 10MB
 /** Map audit actions to event-log actions (subset that overlaps) */
 const AUDIT_TO_EVENT_ACTION = {
     create: 'create',
@@ -18,6 +19,8 @@ const AUDIT_TO_EVENT_ACTION = {
     session_start: 'session_start',
     session_end: 'session_end',
     rollback: 'rollback',
+    promote_direct: 'create',
+    trust_change: 'update',
 };
 function auditLogPath(cwd) {
     return path.join(memoryDir(cwd), AUDIT_LOG_FILE);
@@ -25,6 +28,7 @@ function auditLogPath(cwd) {
 export function appendAuditEntry(entry, cwd) {
     try {
         mutate({ cwd }, () => {
+            rotateAuditLogIfNeeded(cwd);
             const full = {
                 timestamp: nowISO(),
                 actor: entry.actor,
@@ -35,6 +39,10 @@ export function appendAuditEntry(entry, cwd) {
                 after: entry.after,
                 actor_id: entry.actor_id,
                 reason: entry.reason,
+                scope: entry.scope,
+                session_id: entry.session_id,
+                host_id: entry.host_id,
+                actor_session: entry.actor_session,
             };
             const line = JSON.stringify(Object.fromEntries(Object.entries(full).filter(([, v]) => v !== undefined)));
             fs.appendFileSync(auditLogPath(cwd), line + '\n', 'utf-8');
@@ -83,4 +91,26 @@ export function readAuditLog(options = {}, cwd) {
     }
     return entries;
 }
+/**
+ * Rotate audit.log if it exceeds MAX_AUDIT_LOG_BYTES.
+ * Archives to audit.{timestamp}.log in the same directory.
+ */
+export function rotateAuditLogIfNeeded(cwd) {
+    const logPath = auditLogPath(cwd);
+    if (!fs.existsSync(logPath))
+        return false;
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size < MAX_AUDIT_LOG_BYTES)
+            return false;
+        const archiveName = `audit.${Date.now()}.log`;
+        const archivePath = path.join(memoryDir(cwd), archiveName);
+        fs.renameSync(logPath, archivePath);
+        return true;
+    }
+    catch (err) {
+        logger.debug('Failed to rotate audit log:', err);
+        return false;
+    }
+}
 //# sourceMappingURL=audit.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'];