brainclaw 1.15.0 → 1.16.0

package/dist/core/execution.js

@@ -143,17 +143,37 @@ export async function attemptExecution(invoke, options) {
     const adapter = options.adapter ?? defaultExecutionAdapter;
     // No invoke command available (IDE-only agents, etc.)
     if (!invoke) {
-        return { execution_status: 'inbox_only' };
+        return { execution_status: 'inbox_only', execution_reason: 'no_invoke_command' };
     }
     const spawnCheck = adapter.canSpawn(options.agent);
-    // Opt-out or can't spawn: return command for manual execution
-    // Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes correctly
-    if (!options.autoExecute || !spawnCheck.canSpawn) {
+    // pln#626 Phase 1 — split the old `(!autoExecute || !spawnCheck.canSpawn)`
+    // branch, which collapsed two very different outcomes into one silent
+    // command_ready_manual (no reason, no failure_kind — it even discarded
+    // spawnCheck.reason). Callers could not tell "you didn't ask me to spawn"
+    // apart from "I tried and can't".
+    // (1) autoExecute explicitly disabled: a deliberate manual handoff, NOT a
+    // failure. Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes.
+    if (!options.autoExecute) {
         const manual = adapter.prepareManualCommand(invoke, options);
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
             shell: manual.shell,
+            execution_reason: 'auto_execute_disabled',
+        };
+    }
+    // (2) autoExecute requested but the agent cannot be spawned here: this IS a
+    // failure of the caller's intent. Surface spawnCheck.reason (previously
+    // dropped) instead of returning a bare manual command.
+    if (!spawnCheck.canSpawn) {
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+            error: spawnCheck.reason,
+            failure_kind: 'not_spawnable',
+            execution_reason: 'not_spawnable',
         };
     }
     // pln#531 — isolation invariant: a spawned worker MUST run in its own
@@ -179,6 +199,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: 'Refusing to spawn without an isolated worktree: with no worktree the worker would run in the integration repo and edit the main tree. Fix worktree creation (see claim worktreeWarning) or run the command manually inside a worktree.',
             failure_kind: 'spawn_no_worktree',
+            execution_reason: 'spawn_no_worktree',
         };
     }
     // Capacity guard: skip if agent is at max concurrent tasks
@@ -201,6 +222,7 @@ export async function attemptExecution(invoke, options) {
                 shell: manual.shell,
                 error: `Spawn skipped: ${instanceCheck.reason}. Use the command manually.`,
                 failure_kind: 'spawn_capacity',
+                execution_reason: 'spawn_capacity',
             };
         }
     }
@@ -239,6 +261,7 @@ export async function attemptExecution(invoke, options) {
                     shell: manual.shell,
                     error: `Spawn launched (pid ${result.pid}) but assignment ${options.assignmentId} did not acknowledge within ${handshakeTimeoutMs}ms`,
                     failure_kind: 'spawn_no_handshake',
+                    execution_reason: 'spawn_no_handshake',
                     pid: result.pid,
                 };
             }
@@ -280,6 +303,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: `Spawn failed (${errorMsg}), falling back to manual execution`,
             failure_kind: 'spawn_failed',
+            execution_reason: 'spawn_failed',
         };
     }
 }

package/dist/core/facade-schema.js

@@ -1,10 +1,17 @@
 import { z } from 'zod';
 export const ExecutionStatusSchema = z.enum(['delivered_and_started', 'command_ready_manual', 'inbox_only']);
 export const WorkIntentSchema = z.enum(['execute', 'consult', 'resume', 'review']);
-// pln#492 phase 2.c — 'ideate' opens an ideation loop with a proposal seed
-// artifact. The handler does NOT yet dispatch turns (driver wire-up is
-// phase 2.d). Callers receive loop_id and may drive the loop manually via
-// bclaw_loop intent='turn' / 'advance' until the dispatch path lands.
+// pln#626 — coordinate intents split into three honest contracts:
+//  • SPAWNING (assign / review / reroute, + multi-agent ideate): create a claim
+//    + worktree and, when autoExecute is on, spawn a worker on the brief.
+//    'ideate' with targetAgents advances to critique and spawns one
+//    worktree-isolated critic worker per target (Phase 2, Option B); single-
+//    agent ideate just opens the loop for the champion to drive manually via
+//    bclaw_loop intent='turn'/'advance'.
+//  • INBOX-ONLY (consult): delivers the brief to the target inbox; autoExecute
+//    is a no-op here (never silently ignored).
+//  • READ-ONLY (summarize): reads a thread and returns a summary — no claim,
+//    no dispatch, no execution_status; autoExecute is irrelevant.
 export const CoordinateIntentSchema = z.enum(['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate']);
 export const WorkRequestSchema = z.object({
     intent: WorkIntentSchema,
@@ -172,6 +179,13 @@ export const FacadeResponseSchema = z.object({
     session_id: z.string().optional(),
     warnings: z.array(z.string()),
     execution_status: ExecutionStatusSchema.optional(),
+    /**
+     * pln#626 Phase 1 — machine-readable reason accompanying execution_status
+     * when it is not `delivered_and_started`: auto_execute_disabled (manual
+     * handoff), not_spawnable, spawn_no_worktree/capacity/no_handshake/failed,
+     * or intent_inbox_only (consult/ideate). Absent when everything spawned.
+     */
+    execution_reason: z.string().optional(),
     /** pln#503 phase 3.3: present when execution_status === 'delivered_and_started'. */
     verify_with: VerifyWithSchema.optional(),
     /**

package/dist/core/handoff-review.js

@@ -0,0 +1,35 @@
+import { nowISO } from './ids.js';
+/**
+ * The review sub-fields whose presence in a patch marks the review as
+ * "completed" and (re)stamps `reviewed_at`. Single source of truth for the
+ * completion rule — shared by the canonical grammar (`updateEntity(handoff)`)
+ * and the dispatcher/CLI path (`applyHandoffUpdates`) so the two write paths
+ * can never drift (pln#625 Phase 3, Codex review of #84).
+ */
+export const REVIEW_COMPLETION_FIELDS = [
+    'verdict',
+    'reviewed_by',
+    'summary',
+    'blocking_issues',
+    'suggestions',
+];
+/**
+ * Merge a partial review patch onto an existing review (shallow — PATCH
+ * semantics: provided fields overwrite, others survive) and stamp
+ * `reviewed_at` when the patch introduces a completion field.
+ *
+ * A caller that explicitly provides `reviewed_at` (e.g. a federation import
+ * replaying a prior review) keeps its value; otherwise a completing patch
+ * stamps `nowISO()`. The flat-option callers (applyHandoffUpdates) never carry
+ * `reviewed_at`, so for them this is an unconditional restamp-on-completion —
+ * identical to the pre-extraction behaviour.
+ */
+export function mergeHandoffReview(existing, patch) {
+    const merged = { ...(existing ?? {}), ...patch };
+    const completed = REVIEW_COMPLETION_FIELDS.some((field) => patch[field] !== undefined);
+    if (completed && patch.reviewed_at === undefined) {
+        merged.reviewed_at = nowISO();
+    }
+    return merged;
+}
+//# sourceMappingURL=handoff-review.js.map

package/dist/core/protocol-tool-policy.js

@@ -0,0 +1,113 @@
+/**
+ * Static protocol tool-policy name lists (core-owned, pln#622 PR1).
+ *
+ * Ces listes statiques REMPLACENT les dérivations depuis les annotations
+ * d'ALL_TOOLS ; la cohérence avec le catalogue est garantie par
+ * tests/unit/protocol-tool-policy.test.ts.
+ *
+ * (These STATIC lists REPLACE the derivations from ALL_TOOLS annotations for
+ * core consumers: core/ must not import the commands/ MCP layer, so the tool
+ * names are materialised here instead of being derived from the catalog at
+ * import time. The catalog — src/commands/mcp-catalog.ts — KEEPS deriving its
+ * own copies from tool annotations; bidirectional set equality between these
+ * static lists and the catalog derivations is enforced by
+ * tests/unit/protocol-tool-policy.test.ts.)
+ *
+ * Zero imports by design — this module must stay a pure leaf.
+ *
+ * @module
+ */
+/**
+ * Tools safe for headless auto-approval (annotation `headlessApproval: 'auto'`
+ * in the catalog). Consumed by agent-files writers (Cline autoApprove, Roo
+ * alwaysAllow, Codex approval_mode). Order mirrors catalog declaration order
+ * so generated agent config files are byte-identical to the derived era.
+ */
+export const MCP_HEADLESS_AUTO_TOOL_NAMES = [
+    'bclaw_context',
+    'bclaw_search',
+    'bclaw_estimation_report',
+    'bclaw_list_sequences',
+    'bclaw_assignment_events',
+    'bclaw_list_agents',
+    'bclaw_list_instructions',
+    'bclaw_get_capabilities',
+    'bclaw_list_tools',
+    'bclaw_search_tools',
+    'bclaw_doctor',
+    'bclaw_history',
+    'bclaw_audit',
+    'bclaw_get_discovery',
+    'bclaw_conflict_check',
+    'bclaw_who',
+    'bclaw_check_policy',
+    'bclaw_check_security',
+    'bclaw_read_inbox',
+    'bclaw_get_thread',
+    'bclaw_dispatch_status',
+    'bclaw_code_status',
+    'bclaw_code_find',
+    'bclaw_code_brief',
+    'bclaw_send_message',
+    'bclaw_ack_message',
+    'bclaw_write_note',
+    'bclaw_quick_capture',
+    'bclaw_claim',
+    'bclaw_release_claim',
+    'bclaw_session_start',
+    'bclaw_session_end',
+    'bclaw_add_step',
+    'bclaw_complete_step',
+    'bclaw_update_step',
+    'bclaw_update_handoff',
+    'bclaw_work',
+    'bclaw_coordinate',
+    'bclaw_loop',
+    'bclaw_assignment_update',
+    'bclaw_assignment_action',
+    'bclaw_harvest_candidates',
+    'bclaw_find',
+    'bclaw_get',
+];
+/**
+ * Narrow "canonical grammar" tool set — the read-side facade entries
+ * (session + context) plus the five memory verbs. Consumed by writers
+ * (e.g. Hermes' tools.include) that want a minimal advertised surface.
+ */
+export const MCP_CANONICAL_GRAMMAR_TOOL_NAMES = [
+    'bclaw_context',
+    'bclaw_work',
+    'bclaw_find',
+    'bclaw_get',
+    'bclaw_create',
+    'bclaw_update',
+    'bclaw_transition',
+];
+/**
+ * Tools removed from the MCP surface at the v1.0 cut (Phase 3 slice 3i).
+ * Hidden from every `tools/list` response; direct `tools/call` still works
+ * as a migration escape hatch.
+ */
+export const REMOVED_IN_V1_TOOLS = new Set([
+    'bclaw_list_plans',
+    'bclaw_list_candidates',
+    'bclaw_list_claims',
+    'bclaw_list_actions',
+    'bclaw_list_assignments',
+    'bclaw_list_runs',
+    'bclaw_list_agents', // pln#625 — retired for bclaw_find(entity='agent')
+    'bclaw_read_handoff',
+    'bclaw_create_plan',
+    'bclaw_update_plan',
+    'bclaw_create_candidate',
+    'bclaw_accept',
+    'bclaw_reject',
+    'bclaw_get_execution_context',
+    'bclaw_get_agent_board',
+    'bclaw_get_agent_board_summary',
+    'bclaw_dispatch_analysis',
+    'bclaw_dispatch_review',
+    'bclaw_update_handoff',
+    'bclaw_get_context',
+]);
+//# sourceMappingURL=protocol-tool-policy.js.map

package/dist/core/review-loop-close.js

@@ -0,0 +1,115 @@
+import { getLoop } from './loops/store.js';
+import { complete_turn, advance } from './loops/verbs.js';
+import { withLoopLock } from './loops/lock.js';
+/** review-loop:lop_xxx → the loop id (mirrors assignment-reconciler.ts). */
+const REVIEW_LOOP_SCOPE_RE = /^review-loop:(lop_[0-9a-z]+)/;
+const LOOP_TERMINAL = new Set(['completed', 'cancelled', 'blocked']);
+/** Mirrors verbs.ts:isVerdictAccepted — reviewer_green fires only on a `verdict`
+ * artifact whose body starts with "accepted". */
+function isAcceptedVerdict(artifact) {
+    if (artifact.type !== 'verdict')
+        return false;
+    return /^accepted(?:\b|[:\s])/.test((artifact.body ?? '').trim().toLowerCase());
+}
+/**
+ * Resolve the reviewer slot to complete. STRICT binding first: the active slot
+ * whose assignment_id matches this lane's assignment (the #87 coordinate fix
+ * stamps it), so symmetric loops target the right reviewer. If OTHER slots are
+ * bound but none matches ours, refuse (never complete someone else's slot).
+ * Falls back to a single active reviewer / agent match only for legacy unbound
+ * slots. Returns undefined when no active reviewer slot is ours — the caller
+ * then checks the resume path.
+ */
+function resolveReviewerSlot(loop, assignment) {
+    const active = loop.slots.filter((s) => s.role === 'reviewer' && s.status !== 'done' && s.status !== 'cancelled' && s.status !== 'failed');
+    if (active.length === 0)
+        return undefined;
+    if (assignment.id) {
+        const bound = active.find((s) => s.assignment_id === assignment.id);
+        if (bound)
+            return bound;
+        // Some active slots are bound to OTHER assignments — do not guess/steal.
+        if (active.some((s) => s.assignment_id !== undefined))
+            return undefined;
+    }
+    // Legacy unbound slots: single reviewer, else disambiguate by agent.
+    if (active.length === 1)
+        return active[0];
+    const byAgent = assignment.agent ? active.find((s) => s.agent === assignment.agent) : undefined;
+    return byAgent ?? active[0];
+}
+/**
+ * Map a harvested review lane onto its loop and close/advance it.
+ *
+ * Fires ONLY when the assignment scope is a review-loop (`review-loop:lop_…`)
+ * AND the lane carries a `review_verdict` — otherwise returns undefined and the
+ * caller (harvest) proceeds unchanged. Idempotent, convergent, and defensive:
+ * a terminal loop is a no-op, a partial prior pass is resumed, and any
+ * loop-verb / lock error is swallowed into a `noop` result so a loop-close
+ * failure never breaks harvest (mirrors convergeSlotAssignmentsForClosedLoop).
+ */
+export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd) {
+    const scopeMatch = assignment.scope?.match(REVIEW_LOOP_SCOPE_RE);
+    if (!scopeMatch)
+        return undefined;
+    if (!lane.review_verdict)
+        return undefined;
+    const loopId = scopeMatch[1];
+    const verdict = lane.review_verdict;
+    const noop = (reason, loop_status) => ({
+        loop_id: loopId, verdict, action: 'noop', reason, loop_status,
+    });
+    try {
+        // Lock the loop so the compound complete_turn + advance can't interleave
+        // with a concurrent harvest (BLOCKING 3). All state is re-read inside.
+        return withLoopLock({
+            cwd,
+            intent: 'review-harvest-close',
+            agentId: actor,
+            scope: { kind: 'loop', loopId },
+            work: () => {
+                const loop = getLoop(loopId, cwd);
+                if (!loop)
+                    return noop('loop not found');
+                if (LOOP_TERMINAL.has(loop.status))
+                    return noop(`loop already ${loop.status}`, loop.status);
+                const slot = resolveReviewerSlot(loop, assignment);
+                const acceptedVerdictExists = loop.artifacts.some(isAcceptedVerdict);
+                if (slot) {
+                    // Active reviewer slot → record the verdict on it. isVerdictAccepted
+                    // fires reviewer_green ONLY on an "accepted…" body, so approve MUST
+                    // start with "accepted" and request_changes must NOT.
+                    const summary = (lane.review_summary ?? '').trim();
+                    const body = verdict === 'approve'
+                        ? `accepted${summary ? `: ${summary}` : ''}`
+                        : `changes-requested${summary ? `: ${summary}` : ''}`;
+                    complete_turn({ id: loopId, slot_id: slot.slot_id, actor, artifact: { phase: loop.current_phase, type: 'verdict', body } }, cwd);
+                }
+                else if (!(verdict === 'approve' && acceptedVerdictExists)) {
+                    // No reviewer slot is ours to complete. Resume ONLY the approve→close
+                    // case: a prior pass recorded an accepted verdict but died before
+                    // advancing. For request_changes (or no accepted verdict), the single
+                    // advance already happened on the first pass — do not re-advance.
+                    return noop('already processed (no active reviewer slot to (re)advance)', loop.status);
+                }
+                // Advance: closes on reviewer_green (approve), else moves one phase.
+                // Convergent — safe whether we just recorded the verdict or are resuming
+                // an interrupted approve.
+                const advanced = advance({ id: loopId, actor }, cwd);
+                return {
+                    loop_id: loopId,
+                    verdict,
+                    action: advanced.auto_closed ? 'closed' : 'advanced',
+                    reason: advanced.auto_closed
+                        ? `reviewer_green → loop ${advanced.loop.status}`
+                        : `verdict recorded → advanced to phase "${advanced.loop.current_phase}" (awaiting fix cycle — PR2)`,
+                    loop_status: advanced.loop.status,
+                };
+            },
+        });
+    }
+    catch (err) {
+        return noop(`loop close error (harvest not blocked): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=review-loop-close.js.map

package/dist/core/schema.js

@@ -960,8 +960,9 @@ export const RuntimeEventTypeSchema = z.enum([
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
  * `LANE-RESULT.json` at its worktree root as its final step (a fallback that
- * works even when bclaw_assignment_update / MCP is unavailable, e.g. sandboxed
- * agents). The coordinator ingests it with `brainclaw harvest <assignment_id>`.
+ * works even when bclaw_assignment_update / MCP is unavailable in the worker's
+ * environment, e.g. a genuinely MCP-less agent). The coordinator ingests it with
+ * `brainclaw harvest <assignment_id>`.
  */
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
@@ -973,6 +974,17 @@ export const LaneResultSchema = z.object({
     files_changed: z.array(z.string()).optional(),
     /** Free-form notes (blockers, follow-ups). */
     notes: z.string().optional(),
+    /**
+     * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
+     * sets this to signal whether the change is good to merge (`approve`) or needs
+     * fixes (`request_changes`). The coordinator's harvest maps it onto a loop
+     * `verdict` artifact so `reviewer_green` can fire and the loop auto-closes
+     * without a human driving complete_turn/advance by hand. Absent on
+     * non-review lanes — harvest simply skips the loop-close callback then.
+     */
+    review_verdict: z.enum(['approve', 'request_changes']).optional(),
+    /** One-line rationale accompanying review_verdict (shown in the verdict artifact). */
+    review_summary: z.string().optional(),
 });
 export const RuntimeEventSchema = z.object({
     id: z.string(),

package/dist/core/security-detectors.js

@@ -52,7 +52,7 @@ export function runStructuralDetectors(text, disabled) {
             out.push({
                 detectorId: d.id,
                 label: d.label,
-                excerpt: truncate(m[0]),
+                excerpt: maskSecret(m[0]),
             });
         }
     }
@@ -113,13 +113,42 @@ export function runEntropyDetector(text, options = {}) {
         const context = text.slice(start, end);
         if (!SECRET_KEYWORD_CONTEXT.test(context))
             continue;
-        out.push({ excerpt: truncate(token), entropy: Math.round(entropy * 100) / 100 });
+        out.push({ excerpt: maskSecret(token), entropy: Math.round(entropy * 100) / 100 });
     }
     return out;
 }
-function truncate(s, maxLen = 48) {
-    if (s.length <= maxLen)
-        return s;
-    return s.slice(0, Math.max(8, maxLen / 2)) + '…' + s.slice(-Math.max(4, maxLen / 4));
+/**
+ * Irreversibly mask a matched secret for display.
+ *
+ * The previous behavior truncated the match to ~48 chars, which returned
+ * short secrets (GitHub PATs are 40 chars, AWS key IDs are 20) verbatim in
+ * warning messages and logs. Masking keeps just enough to identify the
+ * token family without ever exposing recoverable material. Splitting is
+ * done per Unicode code point, so surrogate pairs are never cut in half.
+ *
+ *   - matches of 2 code points or fewer: `***` alone (exposing even the
+ *     first code point would reveal most or all of the value);
+ *   - matches of 3–8 code points: first code point + `***`;
+ *   - longer matches: at most ⌊length/3⌋ code points are exposed, capped
+ *     at 6, split prefix-heavy (up to 4 leading — enough to identify
+ *     `ghp_`, `AKIA`, `sk_l` — the remainder trailing) around a fixed
+ *     `…***…` marker.
+ *
+ * The exposure budget grows smoothly with the match length (no cliff at
+ * the short/long boundary) and never reveals more than a third of a
+ * match longer than 8 code points.
+ */
+export function maskSecret(s) {
+    const cp = Array.from(s);
+    if (cp.length === 0)
+        return '';
+    if (cp.length <= 2)
+        return '***';
+    if (cp.length <= 8)
+        return cp[0] + '***';
+    const exposed = Math.min(6, Math.floor(cp.length / 3));
+    const lead = Math.min(4, exposed - 1);
+    const trail = exposed - lead;
+    return cp.slice(0, lead).join('') + '…***…' + cp.slice(cp.length - trail).join('');
 }
 //# sourceMappingURL=security-detectors.js.map

package/dist/core/security.js

@@ -1,14 +1,27 @@
-import { runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
+import { maskSecret, runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
 /**
- * Scan a text string for sensitive content. Three signal layers run:
- *   1. User-configured regex patterns from `config.redaction.patterns`
- *      (the legacy MVP behavior).
- *   2. Structural detectors — exact token shapes for GitHub PATs, AWS
- *      access keys, JWTs, etc. High precision; on by default.
- *   3. Entropy detector — flags high-entropy token-like substrings near
- *      a sensitive keyword. Tunable, on by default.
+ * Scan a text string for sensitive content. Four independent signal layers
+ * run, each with its own enable-gate (S4 semantics, pln#623):
  *
- * In strict mode all signals escalate to `block`; otherwise `warn`.
+ *   1. Redaction patterns — user-configured regexes from
+ *      `config.redaction.patterns`. Gate: `config.redaction.enabled` (whole
+ *      scan short-circuits off when false). The legacy MVP behavior.
+ *   2. Structural detectors — exact token shapes for GitHub PATs, AWS access
+ *      keys, JWTs, etc. High precision. Gate: `security.token_detection.enabled`
+ *      (default on); individual detectors via `token_detection.detectors[id]`.
+ *   3. Entropy detector — high-Shannon-entropy token-like substrings near a
+ *      secret keyword. Gate: `security.token_detection.entropy.enabled` (nested
+ *      under the token_detection gate; default on).
+ *   4. Sensitive paths — literal mentions of `config.sensitive_paths` entries
+ *      (`.env`, `secrets/`, …). Gate: `security.block_sensitive_paths` (default
+ *      on).
+ *
+ * LEVEL (uniform across ALL four layers): a match surfaces as `warn`, and
+ * escalates to `block` when `security.strict_redaction` is true (mode: strict).
+ * Strict mode blocks every signal uniformly — there is no per-layer level
+ * override. Detected/redacted excerpts in messages are always irreversibly
+ * masked (see maskSecret); the redaction pattern itself is referenced by index
+ * and masked, never echoed.
  */
 export function scanText(text, config) {
     const warnings = [];
@@ -16,7 +29,7 @@ export function scanText(text, config) {
         return warnings;
     const isStrict = config.security?.strict_redaction ?? false;
     const level = isStrict ? 'block' : 'warn';
-    for (const pattern of config.redaction.patterns) {
+    for (const [i, pattern] of config.redaction.patterns.entries()) {
         try {
             // Strip Python-style inline flags (?i) etc. since we always use 'i' flag
             const cleanPattern = pattern.replace(/^\(\?[gimsuy]+\)/g, '');
@@ -24,7 +37,9 @@ export function scanText(text, config) {
             if (re.test(text)) {
                 warnings.push({
                     level,
-                    message: `Possible sensitive content matching pattern '${pattern}' found in text`,
+                    // The configured pattern may itself be a literal secret value, so
+                    // it is referenced by index and masked, never echoed verbatim.
+                    message: `Possible sensitive content matching redaction pattern #${i} ('${maskSecret(pattern)}') found in text`,
                 });
             }
         }
@@ -61,7 +76,12 @@ export function scanText(text, config) {
         for (const sp of config.sensitive_paths) {
             if (text.includes(sp)) {
                 warnings.push({
-                    level: 'warn',
+                    // S3 (pln#623): the level is config-derived, not hardcoded. Like the
+                    // three detector layers above, a sensitive-path match surfaces as a
+                    // `warn` normally and escalates to `block` under strict_redaction —
+                    // strict mode blocks EVERY signal, uniformly. `block_sensitive_paths`
+                    // remains the enable-gate for this layer (default on).
+                    level,
                     message: `Sensitive path '${sp}' mentioned in text`,
                 });
             }

package/dist/core/worktree.js

@@ -369,14 +369,42 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         return { committed: false, files_changed: [], reason: 'worktree clean — nothing to commit' };
     }
     // Stage everything, then UNSTAGE the transient files that must never land on
-    // the lane branch: the worker's own `LANE-RESULT.json` report and any
-    // `.brainclaw/` coordination state. Committing those would pollute the branch
-    // (and master, on merge) with non-deliverable artefacts.
+    // the lane branch: the worker's own `LANE-RESULT.json` report, any
+    // `.brainclaw/` coordination state, and the `.brainclaw-worktree.json` marker.
+    // Committing those would pollute the branch (and master, on merge) with
+    // non-deliverable artefacts — a field report (Codex on macOS) caught them
+    // landing in a lane commit (trp_01a2ba2a). `.brainclaw-worktree.json` sits at
+    // the worktree ROOT (NOT inside `.brainclaw/`), so the `.brainclaw` pathspec
+    // does not cover it — it needs its own entry. These are ALWAYS transient, so
+    // the unstage is unconditional.
     const add = runGit(['add', '-A'], worktreePath);
     if (!add.ok) {
         return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
     }
-    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw', '.brainclaw-heartbeat-*'], worktreePath);
+    runGit([
+        'reset', '-q', '--',
+        'LANE-RESULT.json',
+        '.brainclaw',
+        '.brainclaw-worktree.json',
+        '.brainclaw-heartbeat-*',
+    ], worktreePath);
+    // node_modules needs a TRACKED-AWARE exclusion (Codex review of #88, BLOCKING).
+    // Unstage the links/dirs brainclaw provisions — but a project that VENDORS
+    // node_modules tracks those files, and a worker's change to a TRACKED
+    // node_modules file is a REAL deliverable; dropping it would silently omit
+    // work. Strategy: unstage every node_modules path, then RE-ADD only the ones
+    // already tracked at HEAD and modified/deleted (never the fresh provisioned
+    // link/dir, which is `A` vs HEAD). The component-bounded pathspecs never match
+    // a similarly-named deliverable such as `src/node_modules_helper.ts` — the
+    // plain `node_modules` is root-leading-dir only, the `:(glob)` forms match the
+    // `node_modules` path component exactly (nested link entry + nested contents).
+    const NODE_MODULES_SPECS = ['node_modules', ':(glob)**/node_modules', ':(glob)**/node_modules/**'];
+    runGit(['reset', '-q', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const trackedNm = runGit(['diff', '--name-only', '--diff-filter=MD', 'HEAD', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const keepNm = trackedNm.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (keepNm.length > 0) {
+        runGit(['add', '--', ...keepNm], worktreePath);
+    }
     // The files actually staged for this commit (post-exclusion) — also the
     // truthful files_changed report.
     const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
@@ -385,7 +413,7 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         // Only transient files changed — nothing deliverable to commit. Restore the
         // index so the worktree is left exactly as the worker left it.
         runGit(['reset', '-q'], worktreePath);
-        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw)' };
+        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw / node_modules links)' };
     }
     const authorName = options.authorName ?? 'brainclaw (on behalf)';
     const authorEmail = options.authorEmail ?? 'brainclaw@on-behalf.local';
@@ -503,6 +531,30 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  *
  * Returns the absolute path to the newly created worktree.
  */
+/**
+ * Whether the project looks like a Next.js app — a `next` dependency in
+ * package.json or a `next.config.*` at the root. Used to warn that the
+ * out-of-root `node_modules` symlink brainclaw provisions is rejected by
+ * `next dev` / Turbopack (trp_37b05a15), even though tsc / vitest / build accept
+ * it. Best-effort + defensive: any read/parse error → false (never blocks
+ * worktree creation over a heuristic).
+ */
+export function projectUsesNextjs(projectRoot) {
+    try {
+        for (const cfg of ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs']) {
+            if (fs.existsSync(path.join(projectRoot, cfg)))
+                return true;
+        }
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Boolean(pkg.dependencies?.next ?? pkg.devDependencies?.next);
+    }
+    catch {
+        return false;
+    }
+}
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // pln#614: resolve the true git toplevel first, so an in-tree project (project
     // dir ≠ git root) creates its worktree from the real repo root — `git worktree
@@ -631,6 +683,22 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     for (const entry of sharedPaths) {
         trySymlinkSharedPath(entry);
     }
+    // trp_37b05a15 (field report, Next.js 16 / Turbopack) — the node_modules link
+    // brainclaw provisions is an out-of-worktree-root symlink to the main repo.
+    // tsc / vitest / build follow it fine, but `next dev` (Turbopack) PANICS on a
+    // node_modules link that points outside the worktree root. Surface a warning
+    // (not a failure — the link is still correct for build/typecheck) so a worker
+    // or operator doing dev-server work knows the workaround up front. A full
+    // Turbopack-compatible per-worktree dependency mode is a planned follow-up.
+    const linkedNodeModules = sharedPaths.some((p) => p === 'node_modules' || p.endsWith('/node_modules'));
+    if (linkedNodeModules && projectUsesNextjs(mainWorktreePath)) {
+        const msg = 'Next.js detected: node_modules is linked as an out-of-worktree-root symlink, which '
+            + '`next dev` / Turbopack rejects (it requires node_modules under the worktree root). '
+            + 'tsc / vitest / build are unaffected. For dev-server work in this worktree, run '
+            + '`npm install` here (optionally with BRAINCLAW_NO_LINK_DEPS=1), or smoke-test on the merged branch.';
+        symlinkWarnings.push(msg);
+        logger.warn(`[worktree] ${msg}`);
+    }
     // NOTE: .brainclaw/ is intentionally NOT symlinked.
     // Symlinking .brainclaw/ causes hooks and session_start to trigger on the
     // shared store, creating session conflicts and potentially blocking agents