brainclaw 1.7.5 → 1.9.0

package/dist/core/security.js

@@ -1,6 +1,14 @@
+import { runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
 /**
- * Scan a text string for sensitive patterns defined in the config.
- * Returns a list of warnings.
+ * 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.
+ *
+ * In strict mode all signals escalate to `block`; otherwise `warn`.
  */
 export function scanText(text, config) {
     const warnings = [];
@@ -24,6 +32,30 @@ export function scanText(text, config) {
             // skip invalid regex patterns
         }
     }
+    // Structural detectors — only run when token_detection is enabled.
+    const td = config.security?.token_detection;
+    if (td?.enabled !== false) {
+        const disabled = td?.detectors;
+        for (const m of runStructuralDetectors(text, disabled)) {
+            warnings.push({
+                level,
+                message: `${m.label} (id=${m.detectorId}) detected: ${m.excerpt}`,
+            });
+        }
+        if (td?.entropy?.enabled !== false) {
+            const entropyMatches = runEntropyDetector(text, {
+                enabled: td?.entropy?.enabled ?? true,
+                minLength: td?.entropy?.min_length,
+                minEntropy: td?.entropy?.min_entropy,
+            });
+            for (const m of entropyMatches) {
+                warnings.push({
+                    level,
+                    message: `High-entropy token-shaped substring near a secret keyword (entropy=${m.entropy}): ${m.excerpt}`,
+                });
+            }
+        }
+    }
     const blockPaths = config.security?.block_sensitive_paths ?? true;
     if (blockPaths) {
         for (const sp of config.sensitive_paths) {

package/dist/core/sequence.js

@@ -5,6 +5,7 @@ import { generateIdWithLabel, nowISO } from './ids.js';
 import { resolveEntityDir } from './io.js';
 import { SequenceItemSchema, SequenceSchema } from './schema.js';
 import { refreshLiveCompanions } from '../commands/export.js';
+import { emitRegistryPostImage, emitRegistryTombstone, registryFaultPoint } from './events/registry-post-image.js';
 function sequencesDir(cwd, mode = 'read') {
     return resolveEntityDir('sequences', cwd ?? process.cwd(), mode);
 }
@@ -39,7 +40,13 @@ function validateRanks(items) {
 export function saveSequence(sequence, cwd) {
     mutate({ cwd }, () => {
         ensureSequencesDir(cwd);
-        sequenceStore(cwd, 'write').save(SequenceSchema.parse(sequence));
+        const store = sequenceStore(cwd, 'write');
+        const parsed = SequenceSchema.parse(sequence);
+        // pln#568 (I2): journal the post-image BEFORE the projection write.
+        const created = !store.exists(parsed.id);
+        emitRegistryPostImage('sequence', parsed, { created, agent: parsed.author, agent_id: parsed.author_id, session_id: parsed.session_id, cwd });
+        registryFaultPoint('after_registry_journal');
+        store.save(parsed);
         // Auto-refresh live companions after sequence changes (non-fatal)
         try {
             refreshLiveCompanions(cwd);
@@ -99,6 +106,8 @@ export function deleteSequence(id, cwd) {
         if (!current) {
             throw new Error(`Sequence not found: ${id}`);
         }
+        emitRegistryTombstone('sequence', current.id, { agent: current.author, agent_id: current.author_id, session_id: current.session_id, cwd });
+        registryFaultPoint('after_registry_journal');
         store.delete(current.id);
         return { id: current.id, name: current.name };
     });
@@ -123,7 +132,7 @@ export function updateSequence(input, cwd) {
             tags: input.tags ?? current.tags,
             updated_at: nowISO(),
         };
-        store.save(SequenceSchema.parse(next));
+        saveSequence(SequenceSchema.parse(next), cwd);
         return next;
     });
 }

package/dist/core/setup-flow.js

@@ -11,13 +11,150 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { memoryExists } from './io.js';
+import { spawnSync } from 'node:child_process';
+import { memoryDir, memoryExists } from './io.js';
 import { detectAiAgent } from './ai-agent-detection.js';
 import { resolveStoreChain } from './store-resolution.js';
 import { analyzeRepository } from './repo-analysis.js';
 import { getAgentCapabilityProfile, getAllAgentCapabilityProfiles } from './agent-capability.js';
 import { describeAgentSurfaces } from './agent-capability.js';
 import { loadState } from './state.js';
+/** Entries that don't count as "repo content" when deciding the bootstrap route. */
+const CONTENT_IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
+/** True when cwd contains anything beyond git/brainclaw plumbing. */
+export function repoHasContent(cwd) {
+    try {
+        return fs.readdirSync(cwd).some((e) => !CONTENT_IGNORED.has(e));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * THE decision rule for "the memory store is empty — what now?", emitted
+ * identically by the three onboarding surfaces (bclaw_work hint, quick_init
+ * preview, init preflight):
+ *
+ *   - repo with existing content → bclaw_bootstrap (extract context from docs/manifests/history)
+ *   - greenfield (nothing to extract) → bootstrap loop (ideate the vision first)
+ *
+ * The two routes are chainable: extraction first, then a bootstrap loop for
+ * whatever vision the docs could not provide — or ideation first, then
+ * extraction once content exists.
+ * Documented in docs/concepts/workspace-bootstrapping.md ("Empty memory: one rule").
+ */
+export function resolveEmptyMemoryRecommendation(cwd = process.cwd()) {
+    if (repoHasContent(cwd)) {
+        return {
+            route: 'extract',
+            reason: 'repo has existing content to extract from',
+            mcp_next_action: 'bclaw_bootstrap()',
+            cli_next_action: 'brainclaw bootstrap',
+            chained_mcp_action: "bclaw_coordinate(intent='ideate', preset='bootstrap')",
+            text: "Memory is empty and the repo has existing content → run bclaw_bootstrap (CLI: brainclaw bootstrap) to extract initial context. If the project vision is still missing afterwards, chain a bootstrap loop: bclaw_coordinate(intent='ideate', preset='bootstrap').",
+        };
+    }
+    return {
+        route: 'ideate',
+        reason: 'greenfield repo — nothing to extract yet',
+        mcp_next_action: "bclaw_coordinate(intent='ideate', preset='bootstrap')",
+        cli_next_action: 'brainclaw bootstrap-loop',
+        chained_mcp_action: 'bclaw_bootstrap()',
+        text: "Memory is empty and the repo is greenfield → open a bootstrap loop to ideate the project vision: bclaw_coordinate(intent='ideate', preset='bootstrap') (CLI: brainclaw bootstrap-loop). Once content exists, chain bclaw_bootstrap to extract it.",
+    };
+}
+/** Event log this large reads as a mature store, not a from-scratch case. */
+const RICH_EVENT_LOG_BYTES = 64 * 1024;
+/** This many memory items reads as a mature store. */
+const RICH_STATE_ITEMS = 25;
+/** PROJECT.md this much older than the latest repo/store activity is fossil. */
+const FOSSIL_GAP_MS = 30 * 86_400_000;
+function lastCommitEpochMs(cwd) {
+    try {
+        const probe = spawnSync('git', ['log', '-1', '--format=%ct'], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 2000,
+            windowsHide: true,
+        });
+        if (probe.status !== 0)
+            return undefined;
+        const epoch = Number.parseInt(probe.stdout.trim(), 10);
+        return Number.isFinite(epoch) ? epoch * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Composite replacement for the one-bit PROJECT.md stat() that backed
+ * `bootstrap_recommended` (pln#513). The single bit had two failure modes on
+ * a mature ("amorcé") project:
+ *   - false positive: rich store, missing PROJECT.md → recommended a
+ *     from-scratch bootstrap over 17k events of accumulated memory;
+ *   - eternal false negative: PROJECT.md exists but fossilized — never
+ *     flagged again no matter how far the repo drifted.
+ *
+ * Signals combined: PROJECT.md presence × its mtime vs recent activity
+ * (last commit, last memory write) × store density (event-log size,
+ * memory item count). 'refresh' maps to `bclaw_bootstrap(refresh: true)` —
+ * coordinate with the pln#514 step 1 force-flag on the bootstrap-loop side.
+ */
+export function assessBootstrapNeed(cwd = process.cwd()) {
+    const reasons = [];
+    // Signal 1 — PROJECT.md presence.
+    const projectMdPath = path.join(cwd, 'PROJECT.md');
+    let projectMdPresent = false;
+    let projectMdMtimeMs;
+    try {
+        const stat = fs.statSync(projectMdPath);
+        if (stat.isFile() && stat.size > 0) {
+            projectMdPresent = true;
+            projectMdMtimeMs = stat.mtimeMs;
+        }
+    }
+    catch { /* absent */ }
+    // Signal 2 — store density.
+    let eventLogBytes = 0;
+    let eventLogMtimeMs;
+    try {
+        const stat = fs.statSync(path.join(memoryDir(cwd), 'events.jsonl'));
+        eventLogBytes = stat.size;
+        eventLogMtimeMs = stat.mtimeMs;
+    }
+    catch { /* no event log */ }
+    let stateItems = 0;
+    try {
+        const state = loadState(cwd);
+        stateItems = state.active_constraints.length + state.recent_decisions.length
+            + state.known_traps.length + state.open_handoffs.length + state.plan_items.length;
+    }
+    catch { /* unreadable state → 0 */ }
+    const storeDensity = eventLogBytes >= RICH_EVENT_LOG_BYTES || stateItems >= RICH_STATE_ITEMS
+        ? 'rich'
+        : eventLogBytes === 0 && stateItems === 0
+            ? 'empty'
+            : 'low';
+    if (!projectMdPresent) {
+        if (storeDensity === 'rich') {
+            // The store already knows this project — regenerate PROJECT.md from it
+            // (scanner + memory), do NOT restart discovery from scratch.
+            reasons.push(`PROJECT.md missing but the store is rich (${stateItems} items, ${Math.round(eventLogBytes / 1024)} KB events) — regenerate from existing memory instead of bootstrapping from scratch`);
+            return { verdict: 'refresh', reasons, project_md_present: false, store_density: storeDensity };
+        }
+        reasons.push('PROJECT.md missing and the store is sparse — initial bootstrap applies');
+        return { verdict: 'bootstrap', reasons, project_md_present: false, store_density: storeDensity };
+    }
+    // Signal 3 — fossil check: PROJECT.md much older than the latest activity.
+    const lastActivityMs = Math.max(lastCommitEpochMs(cwd) ?? 0, eventLogMtimeMs ?? 0);
+    if (projectMdMtimeMs !== undefined && lastActivityMs > 0 && lastActivityMs - projectMdMtimeMs > FOSSIL_GAP_MS) {
+        const gapDays = Math.round((lastActivityMs - projectMdMtimeMs) / 86_400_000);
+        reasons.push(`PROJECT.md is ${gapDays} days older than the latest repo/store activity — likely fossil, refresh it`);
+        return { verdict: 'refresh', reasons, project_md_present: true, store_density: storeDensity };
+    }
+    reasons.push('PROJECT.md present and current relative to recent activity');
+    return { verdict: 'none', reasons, project_md_present: true, store_density: storeDensity };
+}
 /**
  * Probe the current working directory to understand what we're working with.
  * This is the first step of the quick setup flow — no questions yet, just detection.
@@ -37,16 +174,7 @@ export function probeForQuickSetup(cwd = process.cwd()) {
         : getAllAgentCapabilityProfiles();
     // Scan nearby stores
     const nearbyStores = resolveStoreChain(cwd);
-    // Has content?
-    const IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
-    let hasContent = false;
-    try {
-        const entries = fs.readdirSync(cwd);
-        hasContent = entries.some((e) => !IGNORED.has(e));
-    }
-    catch {
-        // empty or unreadable
-    }
+    const hasContent = repoHasContent(cwd);
     // Analyze repo for project type suggestion
     let suggestedProjectType = 'standalone';
     let analysisReasons = [];
@@ -164,7 +292,7 @@ export function buildOnboardingPreview(cwd) {
         const traps = state.known_traps.filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active'));
         const plans = state.plan_items.filter((p) => p.status === 'in_progress' || p.status === 'todo');
         if (constraints.length === 0 && traps.length === 0 && plans.length === 0) {
-            return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+            return resolveEmptyMemoryRecommendation(cwd).text;
         }
         const lines = ['Here is what your agent will see:'];
         if (constraints.length > 0) {
@@ -185,7 +313,7 @@ export function buildOnboardingPreview(cwd) {
         return lines.join('\n');
     }
     catch {
-        return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+        return resolveEmptyMemoryRecommendation(cwd).text;
     }
 }
 //# sourceMappingURL=setup-flow.js.map

package/dist/core/spawn-check.js

@@ -17,14 +17,33 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { buildInvokeCommand, getSpawnableAgents, getCapabilityProfile, } from './agent-capability.js';
 import { defaultExecutionAdapter, resolveBinaryOnPath } from './execution-adapters.js';
 import { signalExists, readLogTail } from './runtime-signals.js';
+import { recognizeStderrSignature } from './dispatch-status.js';
 const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
 const DEFAULT_PROBE_PROMPT = 'Reply with exactly: OK';
 async function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Make the probe's temp dir a real (empty) git repo so the round-trip is
+ * representative of a real dispatch (workers always run inside a git worktree)
+ * and so CLIs with a boot-time git-repo / trusted-directory check don't refuse
+ * it (pln#533 fix). Best-effort: if git is unavailable the probe still runs.
+ */
+function initProbeGitRepo(root) {
+    try {
+        const run = (...args) => spawnSync('git', args, { cwd: root, encoding: 'utf-8', timeout: 5000 });
+        run('init', '-q');
+        run('config', 'user.email', 'spawn-check@brainclaw.local');
+        run('config', 'user.name', 'brainclaw spawn-check');
+        run('config', 'commit.gpgsign', 'false');
+        run('commit', '--allow-empty', '-q', '-m', 'spawn-check probe');
+    }
+    catch { /* git absent or failed — probe proceeds without it */ }
+}
 /** Check one agent's spawn round-trip. Exposed for focused testing. */
 export async function checkAgentSpawn(agent, options = {}) {
     const start = Date.now();
@@ -43,6 +62,11 @@ export async function checkAgentSpawn(agent, options = {}) {
     }
     // Isolated signals root so the probe never pollutes the project's runtime dir.
     const root = fs.mkdtempSync(path.join(os.tmpdir(), `bclaw-spawncheck-${agent}-`));
+    // pln#533 fix: make the probe dir a real git repo. Real workers run inside a
+    // git worktree, and some CLIs refuse a non-git / untrusted dir at boot (codex:
+    // "Not inside a trusted directory and --skip-git-repo-check was not specified")
+    // — a non-git temp dir would otherwise produce a false-negative spawn failure.
+    initProbeGitRepo(root);
     const assignmentId = 'spawn_check';
     try {
         defaultExecutionAdapter.start(invoke, { agent, assignmentId, ackRoot: root, worktreePath: root });
@@ -59,17 +83,21 @@ export async function checkAgentSpawn(agent, options = {}) {
         const completed = signalExists(root, assignmentId, 'completed');
         const failed = signalExists(root, assignmentId, 'failed');
         const duration_ms = Date.now() - start;
+        // Capture the stderr tail once (used both for the detail string and for
+        // pln#533 boot-signature recognition on the preflight path).
+        const stderrRaw = readLogTail(root, assignmentId, 'stderr', 800).trim();
+        const stderrTail = stderrRaw ? stderrRaw.split(/\r?\n/).filter(Boolean) : undefined;
         if (completed) {
             return { agent, binary, status: 'ok', delivered, completed: true, duration_ms, detail: 'ack + completed round-trip' };
         }
         if (failed) {
-            const tail = readLogTail(root, assignmentId, 'stderr', 400).trim() || readLogTail(root, assignmentId, 'stdout', 400).trim();
-            return { agent, binary, status: 'failed', delivered, completed: false, duration_ms, detail: `wrapper reported failure${tail ? ` — ${tail.replace(/\s+/g, ' ').slice(0, 200)}` : ''}` };
+            const tail = stderrRaw || readLogTail(root, assignmentId, 'stdout', 400).trim();
+            return { agent, binary, status: 'failed', delivered, completed: false, duration_ms, detail: `wrapper reported failure${tail ? ` — ${tail.replace(/\s+/g, ' ').slice(0, 200)}` : ''}`, stderr_tail: stderrTail };
         }
         if (delivered) {
-            return { agent, binary, status: 'delivered_no_completion', delivered: true, completed: false, duration_ms, detail: `spawned + ack but no completion within ${timeout}ms (silent-death symptom)` };
+            return { agent, binary, status: 'delivered_no_completion', delivered: true, completed: false, duration_ms, detail: `spawned + ack but no completion within ${timeout}ms (silent-death symptom)`, stderr_tail: stderrTail };
         }
-        return { agent, binary, status: 'failed', delivered: false, completed: false, duration_ms, detail: `no ack within ${timeout}ms — delivery failed` };
+        return { agent, binary, status: 'failed', delivered: false, completed: false, duration_ms, detail: `no ack within ${timeout}ms — delivery failed`, stderr_tail: stderrTail };
     }
     finally {
         try {
@@ -122,4 +150,82 @@ export function renderSpawnCheckReport(report) {
     }
     return lines.join('\n');
 }
+/**
+ * Pre-flight a single target agent. Pass criteria:
+ *   - `ok` (ack + completed) → pass.
+ *   - `delivered_no_completion` (ack but the trivial probe didn't finish in the
+ *     short window) → PASS: the ack proves spawn + wrapper + delivery work; a
+ *     boot death never acks. We don't want a slow-but-healthy agent to block.
+ *   - `failed` / no-ack → BLOCK with a reason (enriched by a recognized boot
+ *     signature when the stderr matches one).
+ *   - `not_installed` / `no_template` → BLOCK: the agent cannot be spawned here,
+ *     so opening a loop on it would only time out.
+ * When BRAINCLAW_NO_SPAWN is set (tests/CI), pre-flight is skipped (ok:true).
+ */
+/**
+ * Pure mapper: SpawnCheckEntry → PreflightResult. No spawning — exposed so the
+ * pass/block policy (and the boot-signature enrichment) can be unit-tested with
+ * synthetic entries.
+ */
+export function preflightResultFromEntry(entry) {
+    const agent = entry.agent;
+    if (entry.status === 'ok' || entry.status === 'delivered_no_completion') {
+        return { agent, ok: true, status: entry.status, reason: entry.detail };
+    }
+    if (entry.status === 'not_installed') {
+        return {
+            agent, ok: false, status: entry.status,
+            reason: `${agent} binary not on PATH — cannot spawn it here`,
+            recommended_next_action: `Install the ${agent} CLI (or target a different agent), then retry.`,
+        };
+    }
+    if (entry.status === 'no_template') {
+        return {
+            agent, ok: false, status: entry.status,
+            reason: `${agent} has no CLI spawn template — it cannot be auto-dispatched (IDE-only?)`,
+            recommended_next_action: `Target a CLI-spawnable agent, or hand this work to ${agent} interactively.`,
+        };
+    }
+    // failed (or no-ack) — try to attach a recognized boot signature.
+    const sig = recognizeStderrSignature(entry.stderr_tail);
+    return {
+        agent, ok: false, status: entry.status,
+        reason: sig?.summary ?? `${agent} failed its pre-flight spawn — ${entry.detail}`,
+        recommended_next_action: sig?.recommended_next_action
+            ?? `Inspect the ${agent} CLI config/auth (run \`brainclaw doctor --spawn-check\` for detail), fix it, then retry.`,
+    };
+}
+export async function preflightAgentSpawn(agent, options = {}) {
+    if (process.env.BRAINCLAW_NO_SPAWN === '1') {
+        return { agent, ok: true, status: 'skipped', reason: 'pre-flight skipped (BRAINCLAW_NO_SPAWN)' };
+    }
+    // Pre-flight uses a tighter window than the full doctor round-trip: a boot
+    // death fails fast, and an ack is enough to pass, so we don't need to wait
+    // out a healthy agent's full probe completion.
+    const entry = await checkAgentSpawn(agent, { timeoutMs: 8_000, ...options });
+    return preflightResultFromEntry(entry);
+}
+/**
+ * Pre-flight a set of target agents (deduped), one trivial probe each. Returns
+ * the per-agent results plus `blocked` (the agents that failed). Callers use
+ * `blocked` to skip those agents and surface their reasons instead of opening a
+ * loop / dispatching work that would only time out.
+ */
+export async function preflightAgents(agents, options = {}) {
+    const unique = [...new Set(agents)];
+    const results = [];
+    for (const agent of unique) {
+        try {
+            results.push(await preflightAgentSpawn(agent, options));
+        }
+        catch (err) {
+            results.push({
+                agent, ok: false, status: 'failed',
+                reason: `pre-flight threw: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    const blocked = results.filter((r) => !r.ok);
+    return { results, blocked, all_ok: blocked.length === 0 };
+}
 //# sourceMappingURL=spawn-check.js.map

package/dist/core/staleness.js

@@ -4,6 +4,8 @@
  * Staleness is a soft signal — items are warned, not auto-archived.
  * Users choose to dismiss, resolve, or archive via explicit commands.
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import { resolvedSource } from './candidates.js';
 /** Thresholds in days. Adjust via config in the future. */
 export const STALENESS_THRESHOLDS = {
@@ -100,6 +102,101 @@ export function detectExpiredTraps(traps, nowIso = new Date().toISOString(), now
     }
     return warnings;
 }
+/** pln#530 — a perishable fact unverified for longer than this reads as stale. */
+const VERIFIED_STALE_DAYS = 30;
+/**
+ * pln#530 — flag perishable memories (traps that opted in by carrying a
+ * `verify_cmd` and/or `verified_at`) whose last empirical verification is stale
+ * or never happened, so an agent re-probes the live system instead of trusting a
+ * value that may have drifted (the LeaseUp `service_tier` trap that the API later
+ * rejected is the motivating case). Only traps with these fields are considered —
+ * durable facts are untouched.
+ */
+export function detectUnverifiedMemory(traps, nowMs = Date.now()) {
+    const warnings = [];
+    for (const trap of traps) {
+        if (trap.status !== 'active')
+            continue;
+        if (!trap.verify_cmd && !trap.verified_at)
+            continue; // opt-in: only perishable facts
+        const age = trap.verified_at ? ageDays(trap.verified_at, nowMs) : Infinity;
+        if (trap.verified_at && age < VERIFIED_STALE_DAYS)
+            continue; // freshly verified
+        warnings.push({
+            id: trap.id,
+            entity: 'trap',
+            text: truncate(trap.text),
+            age_days: Number.isFinite(age) ? age : 9999,
+            reason: trap.verified_at
+                ? `Perishable fact last verified ${age} day${age === 1 ? '' : 's'} ago — re-confirm against the live system before trusting`
+                : `Perishable fact never empirically verified (verify_cmd set) — confirm before trusting`,
+            suggested_action: trap.verify_cmd
+                ? `Run \`${trap.verify_cmd}\`, then bclaw_update(trap, ${trap.short_label ?? trap.id}, { verified_at: <now> })`
+                : `Re-verify against the live system, then set verified_at via bclaw_update`,
+        });
+    }
+    return warnings;
+}
+/** Glob chars / URL schemes — entries we cannot meaningfully existsSync. */
+const NON_CHECKABLE_PATH = /[*?[\]]|:\/\//;
+/**
+ * Detect memory entities whose `related_paths` point at files that no longer
+ * exist — memory that stayed "confident" through a refactor and is now wrong.
+ * Staleness today is purely temporal; this is the structural complement
+ * (pln#557 step 2, bridge to pln_79a995b6 memory-lifecycle confirm/decay).
+ *
+ * Only plain paths are probed: glob patterns and URLs are skipped, and a
+ * single missing path among several is enough to flag (the warning lists
+ * exactly which ones are gone).
+ */
+export function detectDeadReferences(items, projectRoot, nowMs = Date.now()) {
+    const warnings = [];
+    for (const item of items) {
+        if (!item.related_paths || item.related_paths.length === 0)
+            continue;
+        const missing = [];
+        for (const ref of item.related_paths) {
+            const trimmed = ref.trim();
+            if (!trimmed || NON_CHECKABLE_PATH.test(trimmed))
+                continue;
+            const resolved = path.isAbsolute(trimmed) ? trimmed : path.join(projectRoot, trimmed);
+            try {
+                if (!fs.existsSync(resolved))
+                    missing.push(trimmed);
+            }
+            catch { /* unreadable path — treat as non-checkable, not dead */ }
+        }
+        if (missing.length === 0)
+            continue;
+        warnings.push({
+            id: item.id,
+            entity: item.entity,
+            text: truncate(item.text),
+            age_days: ageDays(item.created_at, nowMs),
+            reason: `References missing path${missing.length > 1 ? 's' : ''}: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ` (+${missing.length - 3} more)` : ''} — likely stale after a refactor`,
+            suggested_action: `bclaw_update(entity: "${item.entity}", id: "${item.short_label ?? item.id}", { related_paths: [<current paths>] })  # or archive if obsolete`,
+        });
+    }
+    return warnings;
+}
+/** Map active entities into the dead-reference detector's input shape. */
+export function collectDeadReferenceCandidates(scan) {
+    const items = [];
+    for (const d of scan.decisions ?? []) {
+        items.push({ id: d.id, entity: 'decision', text: d.text, created_at: d.created_at, related_paths: d.related_paths, short_label: d.short_label });
+    }
+    for (const c of scan.constraints ?? []) {
+        if ((c.status ?? 'active') !== 'active')
+            continue;
+        items.push({ id: c.id, entity: 'constraint', text: c.text, created_at: c.created_at, related_paths: c.related_paths, short_label: c.short_label });
+    }
+    for (const t of scan.traps ?? []) {
+        if (t.status !== 'active')
+            continue;
+        items.push({ id: t.id, entity: 'trap', text: t.text, created_at: t.created_at, related_paths: t.related_paths, short_label: t.short_label });
+    }
+    return items;
+}
 /**
  * Detect open handoffs that have not been acted on for a long time.
  */
@@ -203,16 +300,24 @@ export function detectStaleRuntimeNotes(notes, nowMs = Date.now(), thresholds =
  * @param candidates Pending candidates
  * @param nowMs Optional timestamp override (for testing)
  */
-export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date.now(), runtimeNotes = []) {
+export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date.now(), runtimeNotes = [], deadRefScan) {
     const nowIso = new Date(nowMs).toISOString();
     const planWarnings = detectStalePlans(plans, nowMs);
     const trapWarnings = detectExpiredTraps(traps, nowIso, nowMs);
+    const unverifiedWarnings = detectUnverifiedMemory(traps, nowMs); // pln#530
     const handoffWarnings = detectStaleHandoffs(handoffs, nowMs);
     const candidateWarnings = detectStaleCandidates(candidates, nowMs);
     const noteWarnings = detectStaleRuntimeNotes(runtimeNotes, nowMs);
+    // pln#557 step 2 — structural staleness: dead related_paths. The trap list
+    // for the scan defaults to the traps already passed in.
+    const deadRefWarnings = deadRefScan
+        ? detectDeadReferences(collectDeadReferenceCandidates({ traps, ...deadRefScan }), deadRefScan.projectRoot, nowMs)
+        : [];
     const warnings = [
+        ...deadRefWarnings,
         ...planWarnings,
         ...trapWarnings,
+        ...unverifiedWarnings,
         ...handoffWarnings,
         ...candidateWarnings,
         ...noteWarnings,
@@ -224,6 +329,7 @@ export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date
         handoff_count: handoffWarnings.length,
         candidate_count: candidateWarnings.length,
         runtime_note_count: noteWarnings.length,
+        ...(deadRefScan ? { dead_reference_count: deadRefWarnings.length } : {}),
     };
 }
 /** Total warning count across all entity types. */
@@ -241,6 +347,8 @@ export function staleSummary(report) {
         parts.push(`${report.candidate_count} pending candidate${report.candidate_count > 1 ? 's' : ''}`);
     if (report.runtime_note_count > 0)
         parts.push(`${report.runtime_note_count} stale runtime note${report.runtime_note_count > 1 ? 's' : ''}`);
+    if ((report.dead_reference_count ?? 0) > 0)
+        parts.push(`${report.dead_reference_count} item${report.dead_reference_count > 1 ? 's' : ''} with dead file references`);
     return parts.join(', ');
 }
 //# sourceMappingURL=staleness.js.map