brainclaw 1.7.5 → 1.9.0

package/dist/core/runtime-signals.js

@@ -46,6 +46,18 @@ export function getRuntimeSignalPath(root, assignmentId, signal) {
 export function getRuntimeLogPath(root, assignmentId, stream) {
     return path.join(runtimeDir(root), 'log', `${assignmentId}.${stream}.log`);
 }
+/**
+ * Worktree-local heartbeat path (sprint 1.5). The project-root signal path is
+ * NOT writable from inside many worker sandboxes (Claude Code restricts writes
+ * to its working directories; codex workspace-write roots exclude the project) —
+ * observed live: the generated brief demanded a heartbeat the worker could not
+ * write. The worktree root is the one location every dispatched worker can
+ * write, so briefs point step-0 here, and every heartbeat reader checks BOTH
+ * locations.
+ */
+export function getWorktreeHeartbeatPath(worktreePath, assignmentId) {
+    return path.join(worktreePath, `.brainclaw-heartbeat-${assignmentId}`);
+}
 /** Ensure the ack / signal / log directories exist (best-effort, recursive). */
 export function ensureRuntimeDirs(root) {
     const base = runtimeDir(root);
@@ -61,13 +73,7 @@ export function signalExists(root, assignmentId, signal) {
         return false;
     }
 }
-/**
- * Read the heartbeat sentinel. The body is expected to be
- * `work_loop_reached{run_id,nonce}` JSON, but a bare `touch` (empty file) still
- * counts as a heartbeat — the mtime alone is a valid life-sign.
- */
-export function readHeartbeat(root, assignmentId) {
-    const p = getRuntimeSignalPath(root, assignmentId, 'heartbeat');
+function readHeartbeatFile(p) {
     try {
         const stat = fs.statSync(p);
         const info = { exists: true, mtimeMs: stat.mtimeMs };
@@ -88,12 +94,68 @@ export function readHeartbeat(root, assignmentId) {
         return { exists: false };
     }
 }
+/**
+ * Read the heartbeat sentinel. The body is expected to be
+ * `work_loop_reached{run_id,nonce}` JSON, but a bare `touch` (empty file) still
+ * counts as a heartbeat — the mtime alone is a valid life-sign.
+ *
+ * Checks the project-root signal path AND (when `worktreePath` is given) the
+ * worktree-local heartbeat — sandboxed workers can only write the latter. When
+ * both exist, the freshest mtime wins.
+ */
+export function readHeartbeat(root, assignmentId, worktreePath) {
+    const projectInfo = readHeartbeatFile(getRuntimeSignalPath(root, assignmentId, 'heartbeat'));
+    const worktreeInfo = worktreePath
+        ? readHeartbeatFile(getWorktreeHeartbeatPath(worktreePath, assignmentId))
+        : { exists: false };
+    if (!projectInfo.exists)
+        return worktreeInfo;
+    if (!worktreeInfo.exists)
+        return projectInfo;
+    return (worktreeInfo.mtimeMs ?? 0) > (projectInfo.mtimeMs ?? 0) ? worktreeInfo : projectInfo;
+}
+/**
+ * can_c39f0961 — CP850 high-byte table (0x80–0xFF). Windows-native console
+ * tools write redirected stdout/stderr in the OEM codepage (cp850 on western
+ * locales), which read as UTF-8 produces U+FFFD mojibake in captured logs.
+ * WHATWG TextDecoder does not cover ibm850, so a 128-entry table keeps the
+ * fallback decode dependency-free.
+ */
+const CP850_HIGH = 'ÇüéâäàåçêëèïîìÄÅ' +
+    'ÉæÆôöòûùÿÖÜø£Ø׃' +
+    'áíóúñѪº¿®¬½¼¡«»' +
+    '░▒▓│┤ÁÂÀ©╣║╗╝¢¥┐' +
+    '└┴┬├─┼ãÃ╚╔╩╦╠═╬¤' +
+    'ðÐÊËÈıÍÎÏ┘┌█▄¦Ì▀' +
+    'ÓßÔÒõÕµþÞÚÛÙýݯ´' +
+    '­±‗¾¶§÷¸°¨·¹³²■ ';
+/**
+ * Decode a captured-log buffer: UTF-8 first, falling back to cp850 when the
+ * UTF-8 decode shows replacement characters (the OEM-output signature).
+ */
+export function decodeOemAwareBuffer(buf) {
+    const utf8 = buf.toString('utf-8');
+    if (!utf8.includes('�'))
+        return utf8;
+    let out = '';
+    for (const byte of buf) {
+        out += byte < 0x80 ? String.fromCharCode(byte) : CP850_HIGH[byte - 0x80];
+    }
+    return out;
+}
 /** Read the tail of a captured stream log (for failed_silent diagnostics). */
 export function readLogTail(root, assignmentId, stream, maxBytes = 2000) {
     try {
         const p = getRuntimeLogPath(root, assignmentId, stream);
-        const content = fs.readFileSync(p, 'utf-8');
-        return content.length > maxBytes ? content.slice(content.length - maxBytes) : content;
+        const buf = fs.readFileSync(p);
+        let slice = buf.length > maxBytes ? buf.subarray(buf.length - maxBytes) : buf;
+        // A byte-offset tail can start mid-UTF-8-sequence; dropping leading
+        // continuation bytes avoids a false U+FFFD that would trigger the cp850
+        // fallback on genuine UTF-8 content.
+        while (slice.length > 0 && slice[0] >= 0x80 && slice[0] <= 0xbf) {
+            slice = slice.subarray(1);
+        }
+        return decodeOemAwareBuffer(slice);
     }
     catch {
         return '';

package/dist/core/runtime.js

@@ -8,6 +8,7 @@ import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
+import { emitRegistryPostImage, emitRegistryTombstone, registryFaultPoint } from './events/registry-post-image.js';
 function sharedRuntimeDir(cwd, mode = 'read') {
     return resolveEntityDir('runtime', cwd ?? process.cwd(), mode);
 }
@@ -46,7 +47,16 @@ export function saveRuntimeNote(note, cwd) {
         const filepath = visibility === 'shared'
             ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
             : path.join(hostAgentDir(visibility, hostId, note.agent, cwd, 'write'), `${note.id}.json`);
-        saveVersionedJsonFile('runtime_note', filepath, RuntimeNoteSchema.parse(persistedNote));
+        const parsed = RuntimeNoteSchema.parse(persistedNote);
+        // pln#568 (I2): journal the post-image BEFORE the projection write — but
+        // SHARED notes only. Private/machine-visibility notes must not leak their
+        // payload into the shared journal (the observer's board shows shared notes).
+        if (visibility === 'shared') {
+            const created = !fs.existsSync(filepath);
+            emitRegistryPostImage('runtime_note', parsed, { created, agent: note.agent, agent_id: note.agent_id, session_id: note.session_id, cwd });
+            registryFaultPoint('after_registry_journal');
+        }
+        saveVersionedJsonFile('runtime_note', filepath, parsed);
         appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
         commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
     });
@@ -64,10 +74,47 @@ export function deleteRuntimeNote(note, cwd) {
         if (!fs.existsSync(filepath)) {
             return false;
         }
+        if ((note.visibility ?? 'shared') === 'shared') {
+            emitRegistryTombstone('runtime_note', note.id, {
+                agent: note.agent,
+                agent_id: note.agent_id,
+                session_id: note.session_id,
+                cwd,
+            });
+            registryFaultPoint('after_registry_journal');
+        }
         fs.unlinkSync(filepath);
         return true;
     });
 }
+/**
+ * The shared runtime notes that are journaled as post-images (pln#568): notes
+ * under `runtime/<agent>/*.json`, EXCLUDING `runtime/agent-runtime/` (which
+ * holds runtime EVENT files `evt_*.json`, not saveRuntimeNote post-images —
+ * they would otherwise be parsed as notes and report false drift). Single
+ * source of truth for the journaled-shared-note set, shared by the registry
+ * verifier (verify.ts) and the registry genesis backfill (genesis.ts).
+ */
+export function listSharedJournaledRuntimeNotes(cwd) {
+    const root = sharedRuntimeDir(cwd, 'read');
+    if (!fs.existsSync(root))
+        return [];
+    const notes = [];
+    for (const entry of fs.readdirSync(root).sort()) {
+        if (entry === 'agent-runtime')
+            continue;
+        const agentDir = path.join(root, entry);
+        if (!fs.existsSync(agentDir) || !fs.statSync(agentDir).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(agentDir).filter((name) => name.endsWith('.json')).sort()) {
+            try {
+                notes.push(loadVersionedJsonFile('runtime_note', path.join(agentDir, file)).document);
+            }
+            catch { /* mirror listRuntimeNotes' tolerant read */ }
+        }
+    }
+    return notes.sort((a, b) => a.id.localeCompare(b.id));
+}
 function readAgentNotes(dir, agent) {
     if (!fs.existsSync(dir))
         return [];
@@ -136,4 +183,40 @@ export function generateRuntimeNoteId() {
     const rand = crypto.randomBytes(4).toString('hex');
     return `rtn_${rand}`;
 }
+/**
+ * can_b8d53d18 — soft migration for runtime notes created with the legacy
+ * `run_` prefix (the generateId fallback collided with agent_run ids).
+ * Rewrites each note's id to `rtn_<same suffix>` and renames its file.
+ * Old ids referenced in historical events stay historical; lookups are
+ * list-scan based so nothing else needs to change.
+ */
+export function migrateRuntimeNoteIdPrefixes(cwd) {
+    const result = { migrated: [], errors: [] };
+    const legacy = listRuntimeNotes({ visibility: 'all', includeAllHosts: true }, cwd)
+        .filter((note) => note.id.startsWith('run_'));
+    if (legacy.length === 0)
+        return result;
+    const existingIds = new Set(listRuntimeNotes({ visibility: 'all', includeAllHosts: true }, cwd).map((n) => n.id));
+    mutate({ cwd }, () => {
+        for (const note of legacy) {
+            try {
+                let newId = `rtn_${note.id.slice('run_'.length)}`;
+                while (existingIds.has(newId))
+                    newId = generateRuntimeNoteId();
+                const oldPath = runtimeNotePath(note, cwd);
+                const migrated = { ...note, id: newId };
+                const newPath = runtimeNotePath(migrated, cwd);
+                saveVersionedJsonFile('runtime_note', newPath, RuntimeNoteSchema.parse(migrated));
+                if (fs.existsSync(oldPath) && oldPath !== newPath)
+                    fs.unlinkSync(oldPath);
+                existingIds.add(newId);
+                result.migrated.push({ from: note.id, to: newId });
+            }
+            catch (err) {
+                result.errors.push(`${note.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    });
+    return result;
+}
 //# sourceMappingURL=runtime.js.map

package/dist/core/schema.js

@@ -57,6 +57,33 @@ function coerceTags(val) {
 /** Resilient tags schema that accepts string[] or JSON-serialized string. */
 export const TagsSchema = z.preprocess(coerceTags, z.array(z.string()));
 export const TagsWithDefaultSchema = z.preprocess(coerceTags, z.array(z.string()).default([]));
+// --- Memory lifecycle (pln#544) ---
+/**
+ * One confirmation/infirmation event on a memory item (decision, constraint,
+ * trap). The full history is stored on the item as a bounded list — the
+ * `last_confirmed_at` / `last_infirmed_at` / `confirmation_count` /
+ * `infirmation_count` denormalisations let read paths avoid scanning the log
+ * for the common "is this still trustworthy" question.
+ *
+ *  - `confirm` / `infirm`: passive observation that the rule still holds /
+ *    no longer holds.
+ *  - `saved_me`: agent explicitly credits the item with avoiding a bug —
+ *    reinforces ranking weight via reputation.ts.
+ *  - `misled_me`: agent explicitly blames the item for a wrong move —
+ *    sinks ranking weight, mirror of saved_me.
+ */
+export const MemoryConfirmationKindSchema = z.enum(['confirm', 'infirm', 'saved_me', 'misled_me']);
+export const MemoryConfirmationEventSchema = z.object({
+    at: z.string(),
+    by: z.string(),
+    by_id: z.string().optional(),
+    session_id: z.string().optional(),
+    kind: MemoryConfirmationKindSchema,
+    /** Pointer at the evidence — file:line, commit sha, message id, command output. */
+    evidence: z.string().optional(),
+    /** Free-form note (the one-line "why" the agent attests). */
+    note: z.string().optional(),
+});
 // --- Entry schemas ---
 export const ConstraintStatusSchema = z.enum(['active', 'resolved', 'expired']);
 export const ConstraintCategorySchema = z.enum(['architecture', 'performance', 'security', 'reliability', 'compatibility', 'process', 'other']);
@@ -135,6 +162,18 @@ export const ConstraintSchema = z.object({
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
     expires_at: z.string().optional(),
+    // pln#544 — memory-lifecycle (confirm/decay/reinforce). Symmetric across
+    // constraint/decision/trap. `verified_at` (pln#530 perishable-fact
+    // re-verification) is kept as a narrower legacy signal alongside.
+    last_confirmed_at: z.string().optional(),
+    last_infirmed_at: z.string().optional(),
+    confirmation_count: z.number().int().nonnegative().optional(),
+    infirmation_count: z.number().int().nonnegative().optional(),
+    saved_me_count: z.number().int().nonnegative().optional(),
+    misled_me_count: z.number().int().nonnegative().optional(),
+    /** Bounded event log (most recent N) — older events are dropped, the
+     *  counts remain accurate. Empty / absent means "never confirmed". */
+    confirmations: z.array(MemoryConfirmationEventSchema).optional(),
     provenance: ProvenancePassthroughSchema,
 });
 export const DecisionSchema = z.object({
@@ -154,6 +193,19 @@ export const DecisionSchema = z.object({
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
     tags: TagsSchema,
+    // pln#530 — anti-staleness: ISO timestamp this fact was last empirically
+    // verified, and an optional command to re-confirm it. For fast-perishable
+    // facts (tool behaviour, config values), probe before trusting the memory.
+    verified_at: z.string().optional(),
+    verify_cmd: z.string().optional(),
+    // pln#544 — memory-lifecycle (see ConstraintSchema).
+    last_confirmed_at: z.string().optional(),
+    last_infirmed_at: z.string().optional(),
+    confirmation_count: z.number().int().nonnegative().optional(),
+    infirmation_count: z.number().int().nonnegative().optional(),
+    saved_me_count: z.number().int().nonnegative().optional(),
+    misled_me_count: z.number().int().nonnegative().optional(),
+    confirmations: z.array(MemoryConfirmationEventSchema).optional(),
     provenance: ProvenancePassthroughSchema,
 });
 export const TrapSchema = z.object({
@@ -177,6 +229,19 @@ export const TrapSchema = z.object({
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
     platform_scope: z.string().optional(),
+    // pln#530 — anti-staleness (see DecisionSchema): when did we last verify this
+    // is still true, and how to re-confirm it. Critical for environment/tool-fix
+    // traps that go stale (e.g. a service_tier value that the API later rejects).
+    verified_at: z.string().optional(),
+    verify_cmd: z.string().optional(),
+    // pln#544 — memory-lifecycle (see ConstraintSchema).
+    last_confirmed_at: z.string().optional(),
+    last_infirmed_at: z.string().optional(),
+    confirmation_count: z.number().int().nonnegative().optional(),
+    infirmation_count: z.number().int().nonnegative().optional(),
+    saved_me_count: z.number().int().nonnegative().optional(),
+    misled_me_count: z.number().int().nonnegative().optional(),
+    confirmations: z.array(MemoryConfirmationEventSchema).optional(),
     provenance: ProvenancePassthroughSchema,
 });
 export const HandoffContractSchema = z.object({
@@ -223,6 +288,17 @@ export const HandoffSchema = z.object({
     review: HandoffReviewSchema.optional(),
     snapshot: z.object({
         diff: z.string().optional(),
+        /**
+         * pln#569 — digest of the FULL uncommitted diff when `diff` holds only a
+         * capped preview (auto-handoffs). Lets a reader know the inline diff is a
+         * prefix (and verify a re-fetched full diff) without storing the whole
+         * ~450 KB on the handoff. Absent ⇒ `diff` is complete.
+         */
+        diff_digest: z.object({
+            full_bytes: z.number().int().nonnegative(),
+            sha256: z.string(),
+            truncated: z.boolean(),
+        }).optional(),
     }).optional(),
     provenance: ProvenancePassthroughSchema,
     /**
@@ -253,6 +329,15 @@ export const PlanStepSchema = z.object({
     assignee: z.string().optional(),
     created_at: z.string(),
     updated_at: z.string(),
+    // Step-level effort (pln#495). estimated_effort accepts legacy duration
+    // strings ("2h", "30m") via the same preprocess as plan-level; actual_effort
+    // stays a free string parsed by parseEffortMinutes when reported. started_at /
+    // completed_at are set on the todo→in_progress→done transitions so the
+    // estimation report can sum per-step durations and exclude inter-step idle.
+    estimated_effort: z.preprocess(coerceEffortToMinutes, z.number().int().positive().optional()),
+    actual_effort: z.string().optional(),
+    started_at: z.string().optional(),
+    completed_at: z.string().optional(),
 });
 export const PlanTypeEnumSchema = z.enum(['feat', 'fix', 'chore', 'spike', 'doc']);
 export const PlanTypeSchema = PlanTypeEnumSchema.default('feat');
@@ -448,11 +533,25 @@ export const PreinstallConfigSchema = z.object({
     denylist: z.array(z.string()).default([]),
     socket_endpoint: z.string().default('https://mcp.socket.dev/'),
 });
+export const TokenDetectionConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    /** Entropy-based detection for high-randomness strings (typically API keys / tokens). */
+    entropy: z.object({
+        enabled: z.boolean().default(true),
+        /** Minimum string length to consider as a potential secret. */
+        min_length: z.number().int().min(8).max(1024).default(32),
+        /** Minimum Shannon entropy (bits per char) to flag the string. ~4.0 is a reasonable line. */
+        min_entropy: z.number().min(0).max(8).default(4.0),
+    }).prefault({}),
+    /** Per-detector overrides: { aws_access_key: false } disables that detector. */
+    detectors: z.record(z.string(), z.boolean()).default({}),
+});
 export const SecurityConfigSchema = z.object({
     mode: z.enum(['warn', 'strict']).default('warn'),
     strict_redaction: z.boolean().default(false),
     block_sensitive_paths: z.boolean().default(true),
     preinstall: PreinstallConfigSchema.optional(),
+    token_detection: TokenDetectionConfigSchema.prefault({}),
 });
 export const MarkdownConfigSchema = z.object({
     max_items_per_section: z.number().default(20),
@@ -856,6 +955,7 @@ export const RuntimeEventTypeSchema = z.enum([
     'plan_cascade_to_done',
     'candidate_harvested',
     'lane_result_harvested',
+    'lane_integrated',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
@@ -1032,6 +1132,9 @@ export const MemorySeedKindSchema = z.enum([
     'warning',
     'environment',
     'tooling',
+    'decision',
+    'constraint',
+    'trap',
 ]);
 export const MemorySeedSourceKindSchema = z.enum([
     'readme',
@@ -1069,6 +1172,7 @@ export const BootstrapProfileDocumentSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     derived_at: z.string(),
     repo_fingerprint: z.string().optional(),
+    source_fingerprint: z.string().optional(),
     summary: z.string(),
     sources_scanned: z.array(z.string()).default([]),
     git_available: z.boolean().default(false),
@@ -1299,5 +1403,26 @@ export const ConfigSchema = z.object({
         shared_paths: z.array(z.string()).default([]),
         exclude_shared: z.array(z.string()).default([]),
     }).optional(),
+    // Event-log store (pln#543). Absent ⇒ off — fresh and existing stores keep
+    // today's behavior; the journal only activates when explicitly set here (or
+    // via the BRAINCLAW_JOURNAL_MODE env override). The cutover (step 5) flips
+    // the default to dual/primary.
+    store: z.object({
+        journal: z.object({
+            mode: z.enum(['off', 'dual', 'primary', 'registryPrimary']).optional(),
+            fsync: z.enum(['mutation', 'never']).optional(),
+            /**
+             * Phase-3 per-capability sub-flags (pln#566). Each ships + soaks GREEN
+             * independently before its capability is trusted; all default off so a
+             * bare `mode: primary` changes nothing until a capability is enabled.
+             */
+            primary: z.object({
+                checkpointRead: z.boolean().optional(),
+                readReconcile: z.boolean().optional(),
+                tombstoneDelete: z.boolean().optional(),
+                perEntityPatch: z.boolean().optional(),
+            }).optional(),
+        }).optional(),
+    }).optional(),
 });
 //# sourceMappingURL=schema.js.map

package/dist/core/security-detectors.js

@@ -0,0 +1,125 @@
+/**
+ * Structural secret detectors.
+ *
+ * These run alongside the user-configured regex patterns in
+ * `config.redaction.patterns`. They look for well-known token shapes
+ * (GitHub PATs, AWS access keys, JWTs, etc.) — high-precision signal
+ * that should fire even when the operator hasn't added a custom pattern.
+ *
+ * Each detector has a stable `id` so operators can disable individual
+ * detectors via `security.token_detection.detectors[id] = false` without
+ * having to redefine the full list.
+ */
+/**
+ * Detectors are tuned for low false-positive rates. Anchors and
+ * length constraints are intentional; loosening them turns noisy.
+ */
+export const BUILTIN_DETECTORS = [
+    // GitHub
+    { id: 'github_pat', label: 'GitHub personal access token', pattern: /\bghp_[A-Za-z0-9]{36}\b/ },
+    { id: 'github_pat_v2', label: 'GitHub fine-grained PAT', pattern: /\bgithub_pat_[A-Za-z0-9_]{82}\b/ },
+    { id: 'github_oauth', label: 'GitHub OAuth token', pattern: /\bgho_[A-Za-z0-9]{36}\b/ },
+    { id: 'github_user_to_server', label: 'GitHub user-to-server token', pattern: /\bghu_[A-Za-z0-9]{36}\b/ },
+    { id: 'github_server_to_server', label: 'GitHub server-to-server token', pattern: /\bghs_[A-Za-z0-9]{36}\b/ },
+    { id: 'github_refresh', label: 'GitHub refresh token', pattern: /\bghr_[A-Za-z0-9]{36}\b/ },
+    // AWS
+    { id: 'aws_access_key', label: 'AWS access key ID', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+    { id: 'aws_temp_access_key', label: 'AWS temporary access key ID', pattern: /\bASIA[0-9A-Z]{16}\b/ },
+    // Google
+    { id: 'google_api_key', label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/ },
+    // Slack
+    { id: 'slack_token', label: 'Slack token', pattern: /\bxox[abprs]-[0-9A-Za-z-]{10,}\b/ },
+    { id: 'slack_webhook', label: 'Slack webhook', pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]{8,}\/B[A-Z0-9]{8,}\/[A-Za-z0-9]{24,}/ },
+    // Stripe
+    { id: 'stripe_secret', label: 'Stripe secret key', pattern: /\bsk_(?:live|test)_[A-Za-z0-9]{24,}\b/ },
+    // Generic structural
+    { id: 'jwt', label: 'JSON Web Token', pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/ },
+    { id: 'pem_private_key', label: 'PEM-encoded private key', pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/ },
+    // Generic high-confidence: connection strings with embedded credentials.
+    { id: 'url_basic_auth', label: 'URL with embedded credentials', pattern: /[a-z][a-z+.-]+:\/\/[^\s:@/]+:[^\s@/]{4,}@[A-Za-z0-9.-]+/ },
+];
+/**
+ * Run every enabled structural detector across `text`. Detectors with an
+ * explicit `false` in `disabled` are skipped.
+ */
+export function runStructuralDetectors(text, disabled) {
+    const out = [];
+    for (const d of BUILTIN_DETECTORS) {
+        if (disabled && disabled[d.id] === false)
+            continue;
+        const m = text.match(d.pattern);
+        if (m) {
+            out.push({
+                detectorId: d.id,
+                label: d.label,
+                excerpt: truncate(m[0]),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Shannon entropy in bits per character. Higher = more random.
+ *  - English prose       ~2.5–3.0
+ *  - hex-encoded data    ~3.5–4.0
+ *  - base64-encoded data ~5.0–6.0
+ *  - cryptographic keys  ~5.5+
+ */
+export function shannonEntropy(s) {
+    if (!s)
+        return 0;
+    const counts = new Map();
+    for (const ch of s)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let h = 0;
+    const n = s.length;
+    for (const c of counts.values()) {
+        const p = c / n;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+const SECRET_KEYWORD_CONTEXT = /(?:api[_-]?key|secret|token|password|passwd|auth|bearer|access[_-]?key|private[_-]?key)/i;
+const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9_+/=\-]{16,}/g;
+/**
+ * Entropy-based detection. Scans `text` for token-shaped substrings near
+ * a sensitive keyword. Two-stage gating keeps false positives low:
+ *   1. The substring is at least `minLength` chars of token-character class.
+ *   2. Shannon entropy ≥ `minEntropy` bits/char.
+ *   3. Either the substring or the surrounding text contains a secret
+ *      keyword (api_key, token, secret, etc.).
+ */
+export function runEntropyDetector(text, options = {}) {
+    if (options.enabled === false)
+        return [];
+    const minLength = options.minLength ?? 32;
+    const minEntropy = options.minEntropy ?? 4.0;
+    const out = [];
+    HIGH_ENTROPY_CANDIDATE.lastIndex = 0;
+    let m;
+    while ((m = HIGH_ENTROPY_CANDIDATE.exec(text)) !== null) {
+        const token = m[0];
+        if (token.length < minLength)
+            continue;
+        const entropy = shannonEntropy(token);
+        if (entropy < minEntropy)
+            continue;
+        // Avoid flagging plain decimal numbers (very low entropy but pass length).
+        if (/^[0-9]+$/.test(token))
+            continue;
+        // Context check: keyword either in the candidate itself or in the surrounding 80 chars.
+        const start = Math.max(0, m.index - 40);
+        const end = Math.min(text.length, m.index + token.length + 40);
+        const context = text.slice(start, end);
+        if (!SECRET_KEYWORD_CONTEXT.test(context))
+            continue;
+        out.push({ excerpt: truncate(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));
+}
+//# sourceMappingURL=security-detectors.js.map