brainclaw 1.16.0 → 1.18.0

package/dist/commands/inbox.js

@@ -21,12 +21,15 @@ export function runInboxList(options) {
     }
     const effectiveCwd = cwd ?? process.cwd();
     const agent = options.agent ?? resolveCurrentAgentName(effectiveCwd) ?? 'unknown';
-    const status = options.all ? undefined : options.status ?? 'pending';
+    // --all widens past the core actionable default (pln#627 Phase A); without
+    // includeAll, a bare undefined status now hides acknowledged + archived.
+    const includeAll = options.all === true;
+    const status = includeAll ? undefined : options.status ?? 'pending';
     const msgType = options.type;
     const threadId = options.thread;
     let messages;
     if (options.localOnly) {
-        const result = readInbox({ agent, status, type: msgType, thread_id: threadId, markAsRead: false }, effectiveCwd);
+        const result = readInbox({ agent, status, includeAll, type: msgType, thread_id: threadId, markAsRead: false }, effectiveCwd);
         messages = result.messages;
     }
     else {
@@ -36,7 +39,7 @@ export function runInboxList(options) {
         for (const store of chain) {
             try {
                 // Fetch all messages from this store (no pagination limit)
-                const storeResult = readInbox({ agent, status, type: msgType, thread_id: threadId, markAsRead: false, limit: 1_000_000 }, store.cwd);
+                const storeResult = readInbox({ agent, status, includeAll, type: msgType, thread_id: threadId, markAsRead: false, limit: 1_000_000 }, store.cwd);
                 for (const msg of storeResult.messages) {
                     if (!seenIds.has(msg.id)) {
                         seenIds.add(msg.id);
@@ -48,7 +51,7 @@ export function runInboxList(options) {
         }
         // Fallback when no chain found
         if (messages.length === 0 && chain.length === 0) {
-            const result = readInbox({ agent, status, type: msgType, thread_id: threadId, markAsRead: false }, effectiveCwd);
+            const result = readInbox({ agent, status, includeAll, type: msgType, thread_id: threadId, markAsRead: false }, effectiveCwd);
             messages = result.messages;
         }
     }
@@ -140,6 +143,9 @@ export function runInboxSend(to, text, options) {
         }
         else {
             console.log(`✔ Message sent: [${result.shortLabel}] ${result.type} → ${result.to}`);
+            if (result.warning) {
+                console.warn(`⚠ ${result.warning}`);
+            }
         }
     }
     catch (err) {

package/dist/commands/loop.js

@@ -122,14 +122,14 @@ function buildRequest(subcommand, loopId, opts) {
             };
     }
 }
-export function runLoopCommand(subcommand, args, options = {}, cwd) {
+export async function runLoopCommand(subcommand, args, options = {}, cwd) {
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     const loopId = requireLoopId(args, options);
     const request = buildRequest(subcommand, loopId, options);
-    const handled = handleBclawLoop({ args: request, cwd });
+    const handled = await handleBclawLoop({ args: request, cwd });
     if (handled.response.status !== 'ok') {
         const message = handled.response.error ?? handled.summary;
         fail(`bclaw_loop.${String(request.intent)} rejected the call: ${message}`, 2, options);

package/dist/commands/loops-handlers.js

@@ -1,6 +1,9 @@
 import { ZodError } from 'zod';
 import { listAgentRuns } from '../core/agentruns.js';
 import { reconcileAgentRun } from '../core/agentrun-reconciler.js';
+import { findReservationByRunId } from '../core/loops/attempt-reservation.js';
+import { runVerify } from '../core/loops/verify-command.js';
+import { runImplBind } from '../core/loops/impl-bind.js';
 import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, turn, VersionConflictError, withLoopLock, } from '../core/loops/index.js';
 import { BclawLoopRequestSchema, BCLAW_LOOP_INTENTS, } from '../core/loops/facade-schema.js';
 // NextExpectedHint type now lives in src/core/loops/next-expected.ts
@@ -179,7 +182,7 @@ function trySweepLoopTimeouts(loop_id, cwd) {
     }
     catch { /* best-effort: never block facade on sweep errors */ }
 }
-export function handleBclawLoop(options) {
+export async function handleBclawLoop(options) {
     const startMs = Date.now();
     const defaultActor = options.defaultActor ?? 'bclaw_loop';
     const inferredIntent = inferIntent(options.args);
@@ -218,6 +221,7 @@ export function handleBclawLoop(options) {
                         linked: req.linked,
                         stop_condition: req.stop_condition,
                         mode: req.mode,
+                        verify: req.verify,
                         created_by: agentId,
                     }, options.cwd);
                     const newEvents = findNewLoopEvents(loop.id, undefined, options.cwd);
@@ -257,7 +261,20 @@ export function handleBclawLoop(options) {
                             continue;
                         if (slotStatus === 'done' || slotStatus === 'failed' || slotStatus === 'cancelled')
                             continue;
+                        // pln#630 PR2b-c (§13 R6): GET is strictly observational for
+                        // TURN-OWNED slots. A slot carrying current_turn_id reconciles only
+                        // via the dedicated mutating reconcile path (never on a read), so a
+                        // stale/racing read can't phantom-complete its run. Legacy slots
+                        // (no current_turn_id) keep the intentional lazy reconcile
+                        // (trp_fdf3e590) that converges silent-completion on access.
+                        if (slot.current_turn_id)
+                            continue;
                         for (const run of listAgentRuns(options.cwd, { assignment_id: assignmentId })) {
+                            // Belt-and-braces (review PR2b-c #D): skip by ACTUAL ownership too,
+                            // not just the slot pointer — if a run is turn-owned but its slot
+                            // wasn't stamped (write-ordering), GET must still not mutate it.
+                            if (findReservationByRunId(run.id, options.cwd))
+                                continue;
                             reconcileAgentRun(run.id, options.cwd);
                         }
                     }
@@ -426,6 +443,70 @@ export function handleBclawLoop(options) {
                     return successResponse('close', { loop, next_expected: null }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summarizeLoop(loop));
                 });
             }
+            case 'verify': {
+                // pln#632 — run the loop's opener-configured verify command + record a
+                // deterministic verify_report. runVerify manages its OWN two lock scopes (the
+                // spawn runs OUT of the lock), so it is NOT wrapped in withLockedLoopMutation.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('verify', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const result = runVerify({ loop_id: req.loop_id, actor }, options.cwd);
+                const newEvents = findNewLoopEvents(result.thread.id, beforeEvents, options.cwd);
+                const summary = result.unconfigured
+                    ? `verify: loop has no protocol.verify — falling back to an agent-narrated verify_report`
+                    : result.deduped
+                        ? `verify: a verify_report already exists for iteration ${result.thread.iteration_count} (idempotent)`
+                        : `${result.report?.passed ? '✔ verify green' : result.report?.timed_out ? '✖ verify RED (timeout)' : '✖ verify red'}: ${result.report?.command ?? ''}`;
+                return successResponse('verify', {
+                    loop: result.thread,
+                    verify_report: result.report ?? null,
+                    deduped: result.deduped,
+                    unconfigured: result.unconfigured ?? false,
+                    next_expected: computeNextExpected(result.thread),
+                }, [loopArtifactEntry(result.thread.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', result.thread.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summary);
+            }
+            case 'bind': {
+                // pln#632 impl-loop bind — dispatch the loop's linked sequence + advance
+                // bind→execute. runImplBind awaits the async spawn (the advance takes its own
+                // lock via the verb), so it is NOT wrapped in withLockedLoopMutation — it mirrors
+                // coordinate(open_loop)'s async-handler-spawns pattern, not a synchronous verb.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('bind', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                if (existing.kind !== 'implementation') {
+                    return errorResponse('bind', 'validation_error', `bind is only valid for implementation loops (loop ${req.loop_id} is kind='${existing.kind}'); review/ideation loops dispatch via bclaw_coordinate`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const bind = await runImplBind({
+                    loop_id: req.loop_id,
+                    dispatcherAgent: actor,
+                    dispatcherAgentId: agentId,
+                    sessionId: options.sessionId,
+                    dryRun: req.dry_run,
+                    lanes: req.lanes,
+                    autoExecute: req.auto_execute,
+                    model: req.model,
+                    maxAssignments: req.max_assignments,
+                }, options.cwd);
+                const loop = getLoop(req.loop_id, options.cwd);
+                const newEvents = findNewLoopEvents(loop.id, beforeEvents, options.cwd);
+                const sideEffects = bind.action === 'bound'
+                    ? [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)]
+                    : [...loopEventSideEffects(newEvents)];
+                return successResponse('bind', {
+                    loop,
+                    sequence_id: bind.sequence_id,
+                    action: bind.action,
+                    advanced_to: bind.advanced_to ?? null,
+                    auto_closed: bind.auto_closed ?? false,
+                    dispatched: bind.messages_sent,
+                    dispatch: bind.dispatch,
+                    next_expected: computeNextExpected(loop),
+                }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], sideEffects, bind.dispatch?.warnings ?? [], Date.now() - startMs, bind.reason);
+            }
         }
     }
     catch (err) {

package/dist/commands/mcp-catalog.js

@@ -360,19 +360,22 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_read_inbox',
-        description: 'Read messages from an agent inbox. Returns pending messages by default. Use markAsRead to auto-mark pending messages as read. Supports filtering by status, type, and thread_id.',
+        description: 'Read messages from an agent inbox, newest-first. By default returns only ACTIONABLE messages (pending + read) and hides acknowledged/archived — pass includeAll=true, or a specific status, to widen. Message bodies are previewed (~500 chars) unless full=true; the page is size-bounded by budget_tokens so a read can never blow the token budget. Use markAsRead to auto-mark pending messages as read.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 agent: { type: 'string', description: 'Agent name whose inbox to read. Defaults to calling agent.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
-                status: { type: 'string', description: 'Filter by status: pending, read, acknowledged, archived.' },
+                status: { type: 'string', description: 'Filter by an exact status: pending, read, acknowledged, archived. Overrides the actionable default.' },
+                includeAll: { type: 'boolean', description: 'Return every status (including acknowledged + archived), disabling the actionable default. Default: false.' },
                 type: { type: 'string', description: 'Filter by message type: assign, review, rfc, info, reply.' },
                 thread_id: { type: 'string', description: 'Filter by thread ID to see a conversation.' },
+                full: { type: 'boolean', description: 'Return complete message bodies instead of ~500-char previews. Each previewed message reports text_length + truncated:true. Default: false.' },
                 markAsRead: { type: 'boolean', description: 'Mark pending messages as read. Default: false.' },
                 limit: { type: 'number', description: 'Maximum messages to return (default: 20).' },
                 offset: { type: 'number', description: 'Skip N messages for pagination.' },
+                budget_tokens: { type: 'number', description: 'Cap the returned page size (~4 chars/token). Messages are trimmed until the payload fits; has_more/next_offset let you page the rest.' },
             },
         },
     },
@@ -1028,8 +1031,8 @@ const MCP_WRITE_TOOLS = [
                     // created a loop structure without dispatching the first turn, so
                     // nothing ever ran. Loops are opened via
                     // bclaw_coordinate(intent='review', open_loop=true) or intent='ideate'.
-                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close'],
-                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. See docs/concepts/loop-engine.md.',
+                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close', 'bind'],
+                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. `bind` (implementation loops only) dispatches the loop\'s linked sequence and advances bind→execute — the engine action for the `bind` phase. See docs/concepts/loop-engine.md.',
                 },
                 loop_id: { type: 'string', description: 'Target loop id (lop_…). Required for every intent except open and list.' },
                 kind: { type: 'string', enum: ['review', 'ideation', 'implementation', 'research', 'debug'], description: 'Loop kind for open / list filter.' },
@@ -1052,6 +1055,11 @@ const MCP_WRITE_TOOLS = [
                 outcome: { type: 'string', enum: ['done', 'failed', 'cancelled'], description: 'complete_turn outcome (default done).' },
                 failure_reason: { type: 'string', description: 'complete_turn: optional failure/cancel reason.' },
                 artifact: { type: 'object', description: 'complete_turn / add_artifact payload: { phase, type, body?, produced_by?, ref? }.' },
+                dry_run: { type: 'boolean', description: 'bind: analyze + report what would dispatch; no spawn, no advance.' },
+                lanes: { type: 'array', items: { type: 'string' }, description: 'bind: restrict the dispatch to specific sequence lanes.' },
+                auto_execute: { type: 'boolean', description: 'bind: deliver briefs without spawning (→ manual launch commands).' },
+                model: { type: 'string', description: 'bind: model override for the dispatched agents.' },
+                max_assignments: { type: 'number', description: 'bind: cap assignments made in this bind.' },
                 to_phase: { type: 'string', description: 'advance: explicit target phase (otherwise the next phase).' },
                 force: { type: 'boolean', description: 'advance: allow going backwards (increments iteration_count).' },
                 reason: { type: 'string', description: 'advance / pause / close: optional reason string.' },

package/dist/commands/mcp-read-handlers.js

@@ -149,6 +149,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     let agentNameCache;
     return dispatchReadTool(name, args, {
         cwd,
+        sourceCwd: effective.cwd,
         activeSource,
         resolvedProject,
         projectRoutingApplied,
@@ -1803,6 +1804,8 @@ function dispatchReadTool(name, args, ctx) {
     if (name === 'bclaw_read_inbox') {
         const agentName = args.agent ?? ctx.getAgentName();
         const markAsRead = args.markAsRead === true; // default: false — reading doesn't imply processing
+        const includeAll = args.includeAll === true; // pln#627 Phase A — widen past the actionable default
+        const full = args.full === true; // pln#627 Phase A — return whole bodies, not previews
         const result = readInbox({
             agent: agentName,
             status: args.status,
@@ -1810,21 +1813,77 @@ function dispatchReadTool(name, args, ctx) {
             thread_id: args.thread_id,
             limit: args.limit,
             offset: args.offset,
+            includeAll,
             markAsRead,
         }, cwd);
-        const lines = [`Inbox for ${agentName} — ${result.total} message(s):`];
-        for (const msg of result.messages) {
+        // pln#627 Phase A — bound the payload so a single inbox read can never blow
+        // the MCP token budget (root cause: persona/CoDev dumps persisted as inbox
+        // messages, one at 960 KB). Two independent guards:
+        //   1. per-message: preview each body to INBOX_PREVIEW_CHARS unless full=true;
+        //      the whole body stays available via full=true (bclaw_get(inbox_message)
+        //      is per-agent-scoped and cannot serve one message by id).
+        //   2. whole-page: boundListResult trims messages until the JSON fits the
+        //      char budget, the same way bclaw_find / bclaw_search do (~4 chars/token).
+        const INBOX_PREVIEW_CHARS = 500;
+        const projected = result.messages.map((msg) => {
+            const textLength = msg.text.length;
+            const truncated = !full && textLength > INBOX_PREVIEW_CHARS;
+            return {
+                ...msg,
+                text: truncated ? msg.text.slice(0, INBOX_PREVIEW_CHARS) : msg.text,
+                text_length: textLength,
+                truncated,
+            };
+        });
+        const budgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+        const charBudget = budgetTokens ? Math.min(budgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+        const bounded = boundListResult({ entity: 'inbox_message', total: result.total, items: projected }, result.offset, charBudget);
+        const scopeNote = includeAll || args.status ? '' : ' actionable (pending+read); pass includeAll=true for acknowledged/archived';
+        const lines = [`Inbox for ${agentName} — ${result.total} message(s)${scopeNote}:`];
+        for (const msg of bounded.items) {
             const ack = msg.requires_ack ? ' [ACK required]' : '';
             const thread = msg.thread_id ? ` thread:${msg.thread_id}` : '';
             lines.push(`  [${msg.short_label ?? msg.id}] ${msg.type} from ${msg.from} (${msg.status})${ack}${thread}`);
-            lines.push(`    ${msg.text.slice(0, 200)}${msg.text.length > 200 ? '...' : ''}`);
-        }
-        if (result.messages.length === 0) {
+            const preview = msg.text.slice(0, 200);
+            const more = msg.truncated || msg.text_length > 200;
+            const moreNote = more
+                ? `… (${msg.text_length} chars${msg.truncated ? '; pass full=true for the whole body' : ''})`
+                : '';
+            lines.push(`    ${preview}${moreNote}`);
+        }
+        if (bounded.items.length === 0) {
             lines.push('  (no messages)');
         }
+        if (bounded.hint)
+            lines.push('', bounded.hint);
+        const nextActions = bounded.has_more
+            ? [{
+                    tool: 'bclaw_read_inbox',
+                    args: {
+                        ...(args.agent ? { agent: args.agent } : {}),
+                        offset: bounded.next_offset,
+                        ...(args.limit ? { limit: args.limit } : {}),
+                        ...(args.status ? { status: args.status } : {}),
+                        ...(includeAll ? { includeAll: true } : {}),
+                    },
+                    when: 'to fetch the next page',
+                }]
+            : [];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...result, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                total: result.total,
+                offset: result.offset,
+                limit: result.limit,
+                messages: bounded.items,
+                returned: bounded.returned,
+                has_more: bounded.has_more,
+                ...(bounded.next_offset !== undefined ? { next_offset: bounded.next_offset } : {}),
+                ...(bounded.omitted_for_size ? { omitted_for_size: bounded.omitted_for_size } : {}),
+                ...(bounded.hint ? { hint: bounded.hint } : {}),
+                ...(nextActions.length ? { next_actions: nextActions } : {}),
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     if (name === 'bclaw_context') {
@@ -1915,9 +1974,33 @@ function dispatchReadTool(name, args, ctx) {
             `  stderr: ${status.runtime.log_files.stderr?.exists ? `${status.runtime.log_files.stderr.size_bytes}B` : 'absent'}`,
             `  git: commits_ahead=${status.runtime.commits_ahead ?? 'n/a'} dirty_tracked=${status.runtime.dirty_tracked ?? 'n/a'}`,
         ];
+        // pln#521 P1 (B4) — routing echo. Operators debugging a dispatch need to see
+        // which project this status was read from, and WHY that project won, without
+        // reverse-engineering cwd + store state. The decision (project_name/
+        // project_cwd) is a first-class field; the reasoning is the `_resolution_trace`
+        // sibling, which by design ships here and nowhere else. Deliberately cheap:
+        // no candidate/nested-store scan on a hot read path. source_cwd is the
+        // PRE-routing cwd (ctx.sourceCwd) — using the routed cwd would make the two
+        // ends identical exactly when a `project` arg hopped stores, i.e. the one
+        // case the trace exists to show.
+        const projectCwd = resolvedProject?.path ?? cwd;
+        const projectName = resolvedProject?.name;
+        const resolutionTrace = {
+            source_cwd: ctx.sourceCwd,
+            effective_cwd: projectCwd,
+            active_source: activeSource,
+            ...(projectRoutingApplied && typeof args.project === 'string' ? { project_arg: args.project } : {}),
+        };
+        lines.push('', `Project: ${projectName ?? '(unnamed)'} — ${projectCwd} (via ${activeSource})`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...status, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                ...status,
+                project_cwd: projectCwd,
+                ...(projectName ? { project_name: projectName } : {}),
+                _resolution_trace: resolutionTrace,
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     throw new Error(`Unknown read tool: ${name}`);

package/dist/commands/mcp-schemas.generated.js

@@ -291,6 +291,9 @@ export const generatedSchemas = {
                     "failed",
                     "cancelled"
                 ]
+            },
+            "current_turn_id": {
+                "type": "string"
             }
         },
         "required": [