brainclaw 1.14.0 → 1.16.0

package/dist/core/federation-signing.js

@@ -0,0 +1,115 @@
+/**
+ * Ed25519 request signing for the Brainclaw Cloud federation bridge (pln#100).
+ *
+ * The cloud verifier (brainclaw-cloud/src/middleware/signature.ts) expects three
+ * headers on a signed runtime write:
+ *   X-Agent-Id:        the cloud agent id whose public_key_pem is stored in D1
+ *   X-Agent-Signature: base64 Ed25519 signature over (body + timestamp)
+ *   X-Agent-Timestamp: ISO-8601 timestamp (5-minute replay window)
+ *
+ * The signing key is the agent's local Ed25519 private key managed by
+ * agent-registry (~/.brainclaw/keys/<id>.ed25519.pem). Its SPKI public-key PEM
+ * is what gets registered with the cloud, and sha256(pem) is the fingerprint
+ * both sides compute — so a local↔remote fingerprint match proves the same key.
+ *
+ * @module
+ */
+import crypto from 'node:crypto';
+import { loadConfig } from './config.js';
+import { loadAgentSigningKey, resolveRegisteredAgentIdentity } from './agent-registry.js';
+import { logger } from './logger.js';
+export const AGENT_ID_HEADER = 'X-Agent-Id';
+export const AGENT_SIGNATURE_HEADER = 'X-Agent-Signature';
+export const AGENT_TIMESTAMP_HEADER = 'X-Agent-Timestamp';
+/**
+ * Sign a request body with an Ed25519 private key, producing the cloud's
+ * signature headers. The signed message is exactly `body + timestamp` (UTF-8),
+ * mirroring the verifier. Node signs Ed25519 with a null algorithm.
+ */
+export function signCloudBody(body, params) {
+    const timestamp = params.timestamp ?? new Date().toISOString();
+    const privateKey = crypto.createPrivateKey(params.privateKeyPem);
+    const signature = crypto.sign(null, Buffer.from(body + timestamp, 'utf-8'), privateKey);
+    return {
+        [AGENT_ID_HEADER]: params.agentId,
+        [AGENT_SIGNATURE_HEADER]: signature.toString('base64'),
+        [AGENT_TIMESTAMP_HEADER]: timestamp,
+    };
+}
+/**
+ * Build the outgoing header set for a cloud runtime write.
+ *
+ * - Always includes Content-Type + X-API-Key.
+ * - Adds the Ed25519 signature headers when a signing identity is available.
+ * - Returns `undefined` (fail-closed) when `requireSigned` is set but no signing
+ *   identity is available — the caller MUST NOT send the request in that case.
+ *
+ * Pure and dependency-injected (no filesystem/network) so it is unit-testable.
+ */
+export function buildCloudWriteHeaders(body, opts) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-API-Key': opts.apiKey,
+    };
+    if (opts.signing) {
+        Object.assign(headers, signCloudBody(body, {
+            agentId: opts.signing.cloudAgentId,
+            privateKeyPem: opts.signing.privateKeyPem,
+            timestamp: opts.timestamp,
+        }));
+    }
+    else if (opts.requireSigned) {
+        return undefined;
+    }
+    return headers;
+}
+/**
+ * Resolve the approved agent identity used to sign runtime writes.
+ *
+ * The private key is loaded from the LOCAL brainclaw identity (resolved by
+ * configured agent name / current-agent), while `cloudAgentId` (the value for
+ * X-Agent-Id) comes from the configured cloud agent id when set — the cloud
+ * assigns its own id at registration, distinct from the local identity id. When
+ * no cloud id is configured (self-hosted / id-preserving), the local id is used.
+ *
+ * Returns undefined when no agent is configured or no local Ed25519 key exists.
+ */
+export function resolveCloudSigningIdentity(cwd, env = process.env) {
+    let cfgAgentId;
+    let cfgAgentName;
+    try {
+        const config = loadConfig(cwd);
+        cfgAgentId = config.cloud_sync?.agent_id;
+        cfgAgentName = config.cloud_sync?.agent_name;
+    }
+    catch {
+        // No project config — fall back to env only.
+    }
+    // X-Agent-Id must be the CLOUD agent id, which is distinct from the local
+    // identity id. BRAINCLAW_AGENT_ID is already the LOCAL id everywhere in
+    // brainclaw (current-agent resolution, etc.), so a dedicated
+    // BRAINCLAW_CLOUD_AGENT_ID override avoids sending the local id as the cloud
+    // header when a session exports BRAINCLAW_AGENT_ID (review finding, pln#100).
+    const cloudAgentId = (env.BRAINCLAW_CLOUD_AGENT_ID?.trim() || cfgAgentId || '').trim() || undefined;
+    const agentName = (env.BRAINCLAW_AGENT_NAME?.trim() || env.BRAINCLAW_AGENT?.trim() || cfgAgentName || '').trim() || undefined;
+    // Resolve the LOCAL identity backing the private key: prefer name, then fall
+    // back to a local-id match (self-hosted), then the current agent.
+    const identity = resolveRegisteredAgentIdentity({ agentName, cwd, env, allowCurrent: true, allowEnv: true }) ??
+        (cloudAgentId ? resolveRegisteredAgentIdentity({ agentId: cloudAgentId, cwd, env }) : undefined);
+    if (!identity) {
+        logger.debug('Cloud signing: no local agent identity resolved.');
+        return undefined;
+    }
+    const key = loadAgentSigningKey(identity.agent_id, env);
+    if (!key) {
+        logger.debug(`Cloud signing: agent '${identity.agent_name}' has no local Ed25519 key.`);
+        return undefined;
+    }
+    return {
+        cloudAgentId: cloudAgentId ?? identity.agent_id,
+        localAgentId: identity.agent_id,
+        agentName: identity.agent_name,
+        ...key,
+    };
+}
+//# sourceMappingURL=federation-signing.js.map

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/io.js

@@ -34,6 +34,12 @@ const ENTITY_DIR_MAP = {
     'runtime': 'coordination/runtime',
     'runtime-hosts': 'coordination/runtime-hosts',
     'runtime-private': 'coordination/runtime-private',
+    // federation/ — outbound cloud sync queue (pln#101 Phase 2): durable outbox,
+    // archived 'sent' markers, and 'parked' dead-letters.
+    'federation': 'coordination/federation',
+    'federation/outbox': 'coordination/federation/outbox',
+    'federation/sent': 'coordination/federation/sent',
+    'federation/parked': 'coordination/federation/parked',
     'surface-tasks': 'coordination/surface-tasks',
     'assignments': 'coordination/assignments',
     'runs': 'coordination/runs',

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(),
@@ -1079,6 +1091,17 @@ export const CloudSyncConfigSchema = z.object({
     enabled: z.boolean().default(false),
     endpoint: z.string().default('https://app.brainclaw.dev'),
     api_key: z.string().optional(),
+    /** Remote project this bridge federates into (scopes signed runtime writes). */
+    project_id: z.string().optional(),
+    /** Approved remote agent identity used to sign runtime writes (pln#100). */
+    agent_id: z.string().optional(),
+    agent_name: z.string().optional(),
+    /**
+     * Fail-closed toggle: when true, the bridge refuses to push a runtime write
+     * unless it can sign it with an approved agent's Ed25519 key. Absent/false
+     * keeps existing API-key-only setups working (signing is additive).
+     */
+    require_signed: z.boolean().optional(),
 });
 export const SessionSnapshotSchema = z.object({
     schema_version: z.number().int().positive().optional(),

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`,
                 });
             }