peaks-loop 4.1.0 → 4.1.1

package/dist/services/comments/prune-apply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The line mechanics of a comment prune, and the proof that gates every write.
+ *
+ * Split from `comment-prune.ts` because the two change for different reasons: that
+ * module decides WHAT is debt (and follows the classifier), this one decides how a
+ * line is removed from a file without damaging the file (and follows the language).
+ * Keeping them apart is also what lets the proof be tested on a text array, with no
+ * filesystem and no scan in the room.
+ */
+import type { PruneAction, PruneSkip } from './comment-prune.js';
+/** What the write phase decided, per file. */
+export type WriteOutcome = {
+    touched: string[];
+    notWritten: string[];
+    fileSkips: PruneSkip[];
+};
+/**
+ * Read a file, or report that it is not there — a prune never creates one.
+ *
+ * `existsSync` first, and NO catch: a `catch { return null }` answers "present but
+ * unreadable" (permissions, a locked handle, a directory named as a file) with the same
+ * `null` as "absent", and that conflation is the defect this repository already
+ * ratchets under `silentWarningCatchReturnNull` — this very helper was counted by it.
+ * An absent path is a state the caller handles; an unreadable one should be a crash an
+ * operator sees.
+ */
+export declare function readFileSafe(root: string, rel: string): string | null;
+/**
+ * Split a source into lines, remembering what separated them.
+ *
+ * `mixed` is the signal to leave a file alone rather than a detail to paper over: a
+ * file with both CRLF and LF endings cannot be re-joined from one delimiter without
+ * rewriting every line, and a rewrite of every line is not a comment edit — it would
+ * also make the proof below vacuous, because all the lines would differ.
+ */
+export declare function splitLines(source: string): {
+    lines: string[];
+    eol: string;
+    mixed: boolean;
+};
+/** Group a plan by file, in first-seen order. */
+export declare function actionsByFile(actions: readonly PruneAction[]): Map<string, PruneAction[]>;
+/**
+ * The proof, as data: compare kept lines against the original.
+ *
+ * One string per violation; empty means every difference between the two texts is a
+ * line this plan named, and every line it named that was kept is byte-identical to
+ * what was there before. This is computed whether or not the caller intends to write,
+ * so a dry run reports the refusals a real run would hit.
+ */
+export declare function proofViolations(before: readonly string[], after: readonly string[], actions: readonly PruneAction[]): string[];
+/** Apply one file's actions to its lines, in the plan's own terms. */
+export declare function pruneFileLines(lines: readonly string[], actions: readonly PruneAction[]): string[];
+/**
+ * Run the proof on every planned file, and write only the files that passed it.
+ *
+ * A file that fails is reported and left alone — never written "mostly", because a
+ * partially-pruned file is exactly the state the proof exists to make unreachable.
+ */
+export declare function executePlan(projectRoot: string, byFile: Map<string, PruneAction[]>, apply: boolean): WriteOutcome;

package/dist/services/comments/prune-apply.js

@@ -0,0 +1,150 @@
+/**
+ * The line mechanics of a comment prune, and the proof that gates every write.
+ *
+ * Split from `comment-prune.ts` because the two change for different reasons: that
+ * module decides WHAT is debt (and follows the classifier), this one decides how a
+ * line is removed from a file without damaging the file (and follows the language).
+ * Keeping them apart is also what lets the proof be tested on a text array, with no
+ * filesystem and no scan in the room.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Read a file, or report that it is not there — a prune never creates one.
+ *
+ * `existsSync` first, and NO catch: a `catch { return null }` answers "present but
+ * unreadable" (permissions, a locked handle, a directory named as a file) with the same
+ * `null` as "absent", and that conflation is the defect this repository already
+ * ratchets under `silentWarningCatchReturnNull` — this very helper was counted by it.
+ * An absent path is a state the caller handles; an unreadable one should be a crash an
+ * operator sees.
+ */
+export function readFileSafe(root, rel) {
+    const abs = join(root, rel);
+    return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+}
+/**
+ * Split a source into lines, remembering what separated them.
+ *
+ * `mixed` is the signal to leave a file alone rather than a detail to paper over: a
+ * file with both CRLF and LF endings cannot be re-joined from one delimiter without
+ * rewriting every line, and a rewrite of every line is not a comment edit — it would
+ * also make the proof below vacuous, because all the lines would differ.
+ */
+export function splitLines(source) {
+    const crlf = source.includes('\r\n');
+    const lfOnly = /\n(?!\r)/.test(source.replace(/\r\n/g, '\n')) || /\n[^\r]/.test(source);
+    return {
+        lines: source.split(/\r?\n/),
+        eol: crlf ? '\r\n' : '\n',
+        mixed: crlf && lfOnly
+    };
+}
+/** Group a plan by file, in first-seen order. */
+export function actionsByFile(actions) {
+    const byFile = new Map();
+    for (const action of actions) {
+        const list = byFile.get(action.file);
+        if (list === undefined)
+            byFile.set(action.file, [action]);
+        else
+            list.push(action);
+    }
+    return byFile;
+}
+/**
+ * The proof, as data: compare kept lines against the original.
+ *
+ * One string per violation; empty means every difference between the two texts is a
+ * line this plan named, and every line it named that was kept is byte-identical to
+ * what was there before. This is computed whether or not the caller intends to write,
+ * so a dry run reports the refusals a real run would hit.
+ */
+export function proofViolations(before, after, actions) {
+    const dropped = new Set(actions.filter((a) => a.mode === 'drop-line').map((a) => a.line));
+    const stripped = new Set(actions.filter((a) => a.mode === 'strip-trailing').map((a) => a.line));
+    const violations = [];
+    let afterAt = 0;
+    before.forEach((original, index) => {
+        const line = index + 1;
+        if (dropped.has(line))
+            return; // deleted on purpose
+        if (stripped.has(line)) {
+            // The only thing a strip may do is reveal the code that was already there, so
+            // what survives must be a PREFIX of the original line — that is what makes it a
+            // comment edit, and anything else is a code edit wearing its clothes.
+            const kept = after[afterAt] ?? '';
+            afterAt += 1;
+            if (!original.startsWith(kept))
+                violations.push(`line ${line}: code text changed`);
+            return;
+        }
+        if (after[afterAt] !== original)
+            violations.push(`line ${line}: untouched line differs`);
+        afterAt += 1;
+    });
+    if (afterAt !== after.length)
+        violations.push(`produced ${after.length - afterAt} extra line(s)`);
+    return violations;
+}
+/** Apply one file's actions to its lines, in the plan's own terms. */
+export function pruneFileLines(lines, actions) {
+    const drop = new Set(actions.filter((a) => a.mode === 'drop-line').map((a) => a.line));
+    const strip = new Map(actions.filter((a) => a.mode === 'strip-trailing').map((a) => [a.line, a.comment]));
+    const out = [];
+    lines.forEach((original, index) => {
+        const line = index + 1;
+        if (drop.has(line))
+            return;
+        if (strip.has(line)) {
+            // Cut where the scan's comment text starts, not at the first `//` in the line:
+            // `const url = "https://example.com"; // Slice 1 kept it` has its `//` inside a
+            // string literal, and slicing there would delete code.
+            const comment = strip.get(line) ?? '';
+            const at = original.indexOf(comment);
+            out.push(at > 0 ? original.slice(0, at).trimEnd() : comment.trimEnd());
+            return;
+        }
+        out.push(original);
+    });
+    return out;
+}
+/**
+ * Run the proof on every planned file, and write only the files that passed it.
+ *
+ * A file that fails is reported and left alone — never written "mostly", because a
+ * partially-pruned file is exactly the state the proof exists to make unreachable.
+ */
+export function executePlan(projectRoot, byFile, apply) {
+    const touched = [];
+    const notWritten = [];
+    const fileSkips = [];
+    for (const [file, fileActions] of byFile) {
+        const source = readFileSafe(projectRoot, file);
+        if (source === null) {
+            notWritten.push(file);
+            continue;
+        }
+        const parts = splitLines(source);
+        if (parts.mixed) {
+            fileSkips.push({
+                file,
+                line: 0,
+                reason: 'mixed-line-endings',
+                text: `${parts.lines.length} line(s) left untouched`
+            });
+            notWritten.push(file);
+            continue;
+        }
+        const after = pruneFileLines(parts.lines, fileActions);
+        const violations = proofViolations(parts.lines, after, fileActions);
+        if (violations.length > 0) {
+            notWritten.push(`${file} (${violations[0]})`);
+            continue;
+        }
+        touched.push(file);
+        if (apply)
+            writeFileSync(join(projectRoot, file), after.join(parts.eol));
+    }
+    return { touched, notWritten, fileSkips };
+}

package/dist/services/comments/repo-path-probe.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Is a path required to exist in a checkout at all?
+ *
+ * The dominant false positive on `dead-reference` was never a stale comment: it
+ * was a correct reference to a file git is told not to track. Ranked over this
+ * repository, the top twelve "dead" citations were `.claude/settings.local.json`,
+ * `.peaks/_runtime/session.json`, `.peaks/.session.json`,
+ * `.peaks/_runtime/active-skill.json`, `.codegraph/config.json`,
+ * `.peaks/preferences.json` and friends — all generated state, all named
+ * correctly by the code that writes them.
+ *
+ * So the probe answers "exists OR ignored", and the ignore reading is deliberately
+ * bounded: trailing-slash prefixes, whole-path entries, and bare-basename entries.
+ * That limit has a direction, and the direction is the safe one — a rule
+ * `.gitignore` expresses fancily (negation, `**`, character classes) is NOT read
+ * here, so such a path stays reported. A missed exemption is a finding a human
+ * reads and dismisses; a phantom exemption is a silent false green in a gate that
+ * exists to catch claims that outlived their referent.
+ */
+type IgnoreRules = {
+    /** Directory rules: match the path and everything below it. */
+    readonly prefixes: readonly string[];
+    /** File rules written with a slash: match that exact repo-relative path. */
+    readonly exact: ReadonlySet<string>;
+    /** Basename rules: match that name in any directory. */
+    readonly basenames: ReadonlySet<string>;
+};
+/** True when `.gitignore` says this repo-relative path need not be on disk. */
+export declare function isIgnoredPath(relPath: string, rules: IgnoreRules): boolean;
+/**
+ * Build the existence probe a scan should use: a real filesystem lookup, widened
+ * by the repository's own ignore list read from its root.
+ *
+ * The second export below is the deliberate exception. "Is this an installed
+ * package name?" must NOT be widened by the ignore list, because `node_modules` is
+ * itself ignored — an ignore-aware probe answers yes for every first segment, and
+ * the whole `dead-reference` count collapses to zero while looking perfectly
+ * healthy.
+ */
+export declare function createRepoProbe(repoRoot: string): (relPath: string) => boolean;
+/** Filesystem-only existence, for questions where "git ignores it" is no answer. */
+export declare function createFsProbe(repoRoot: string): (relPath: string) => boolean;
+export {};

package/dist/services/comments/repo-path-probe.js

@@ -0,0 +1,78 @@
+/**
+ * Is a path required to exist in a checkout at all?
+ *
+ * The dominant false positive on `dead-reference` was never a stale comment: it
+ * was a correct reference to a file git is told not to track. Ranked over this
+ * repository, the top twelve "dead" citations were `.claude/settings.local.json`,
+ * `.peaks/_runtime/session.json`, `.peaks/.session.json`,
+ * `.peaks/_runtime/active-skill.json`, `.codegraph/config.json`,
+ * `.peaks/preferences.json` and friends — all generated state, all named
+ * correctly by the code that writes them.
+ *
+ * So the probe answers "exists OR ignored", and the ignore reading is deliberately
+ * bounded: trailing-slash prefixes, whole-path entries, and bare-basename entries.
+ * That limit has a direction, and the direction is the safe one — a rule
+ * `.gitignore` expresses fancily (negation, `**`, character classes) is NOT read
+ * here, so such a path stays reported. A missed exemption is a finding a human
+ * reads and dismisses; a phantom exemption is a silent false green in a gate that
+ * exists to catch claims that outlived their referent.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function parseGitignore(source) {
+    const prefixes = [];
+    const exact = new Set();
+    const basenames = new Set();
+    for (const raw of source.split(/\r?\n/)) {
+        const rule = raw.trim();
+        if (rule.length === 0 || rule.startsWith('#') || rule.startsWith('!'))
+            continue;
+        const cleaned = rule.replace(/^\//, '').replace(/\/$/, '');
+        if (cleaned.length === 0)
+            continue;
+        if (!cleaned.includes('/')) {
+            basenames.add(cleaned);
+            continue;
+        }
+        // A rule with a slash is registered both ways rather than guessed: `.peaks/_runtime/`
+        // is a directory, `.claude/settings.local.json` is one file, and a rule that
+        // matched only `path/` silently failed every single-file ignore in the
+        // repository. Registering both costs nothing — an over-broad directory prefix
+        // here can only ever name the path it was written for and things under it.
+        prefixes.push(`${cleaned}/`);
+        exact.add(cleaned);
+    }
+    return { prefixes, exact, basenames };
+}
+/** True when `.gitignore` says this repo-relative path need not be on disk. */
+export function isIgnoredPath(relPath, rules) {
+    const posix = relPath.replace(/\\/g, '/');
+    if (rules.exact.has(posix))
+        return true;
+    if (rules.prefixes.some((prefix) => posix.startsWith(prefix)))
+        return true;
+    const segments = posix.split('/');
+    return segments.some((segment) => rules.basenames.has(segment));
+}
+/**
+ * Build the existence probe a scan should use: a real filesystem lookup, widened
+ * by the repository's own ignore list read from its root.
+ *
+ * The second export below is the deliberate exception. "Is this an installed
+ * package name?" must NOT be widened by the ignore list, because `node_modules` is
+ * itself ignored — an ignore-aware probe answers yes for every first segment, and
+ * the whole `dead-reference` count collapses to zero while looking perfectly
+ * healthy.
+ */
+export function createRepoProbe(repoRoot) {
+    let rules = { prefixes: [], exact: new Set(), basenames: new Set() };
+    const ignorePath = join(repoRoot, '.gitignore');
+    if (existsSync(ignorePath)) {
+        rules = parseGitignore(readFileSync(ignorePath, 'utf8'));
+    }
+    return (relPath) => existsSync(join(repoRoot, relPath)) || isIgnoredPath(relPath, rules);
+}
+/** Filesystem-only existence, for questions where "git ignores it" is no answer. */
+export function createFsProbe(repoRoot) {
+    return (relPath) => existsSync(join(repoRoot, relPath));
+}

package/dist/services/log/retention.d.ts

@@ -32,19 +32,3 @@ export type ApplyRetentionOptions = {
  * process between the `readdir` and the `unlink`).
  */
 export declare function applyRetention(opts?: ApplyRetentionOptions): string[];
-/**
- * Slice 3 (on-demand-ecc) — 7-day TTL sweep over `~/.peaks/cache/ecc-<sha>/`
- * directories. Delegates to `cleanupStaleCache` in the ECC cache
- * service so the retention policy lives next to the cache it
- * governs.
- *
- * Mirrors the `applyRetention` signature for symmetry: tests pass
- * `nowMs` + `dirOverride`; production callers leave both unset.
- */
-export declare function cleanupEccCache(options: {
-    retentionDays: number;
-    nowMs?: number;
-    dirOverride?: string;
-}): {
-    removed: string[];
-};

package/dist/services/log/retention.js

@@ -16,7 +16,6 @@
 import { readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveLogDir } from './logger.js';
-import { cleanupStaleCache } from 'peaks-loop-mut';
 const LOG_FILE_NAME_PATTERN = /^peaks-loop-(\d{4}-\d{2}-\d{2})\.log$/;
 function dayDiffUtc(nowUtcMidnightMs, fileDateUtcMs) {
     const dayMs = 24 * 60 * 60 * 1000;
@@ -78,19 +77,3 @@ export function applyRetention(opts = {}) {
     }
     return removed;
 }
-/**
- * Slice 3 (on-demand-ecc) — 7-day TTL sweep over `~/.peaks/cache/ecc-<sha>/`
- * directories. Delegates to `cleanupStaleCache` in the ECC cache
- * service so the retention policy lives next to the cache it
- * governs.
- *
- * Mirrors the `applyRetention` signature for symmetry: tests pass
- * `nowMs` + `dirOverride`; production callers leave both unset.
- */
-export function cleanupEccCache(options) {
-    return cleanupStaleCache({
-        retentionDays: options.retentionDays,
-        nowMs: options.nowMs ?? Date.now(),
-        ...(options.dirOverride !== undefined ? { dirOverride: options.dirOverride } : {})
-    });
-}

package/dist/services/memory/project-memory-service/index.d.ts

@@ -7,7 +7,7 @@ export type { ExtractedMemoryBlocks } from './parsers/markdown-pure.js';
 export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
 export type { MemoryKindResolution, MemoryKindSource, MemoryNameResolution, MemoryNameSource, ParsedMemoryFrontmatter } from './parsers/frontmatter.js';
 export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
-export { assertSafeMemory, assertSafeMemoryFileContent, findSensitiveMemoryTitleTerm, hasSensitiveMemoryContent, SENSITIVE_MEMORY_CHECKS, UnsafeMemoryError, writeNewFile } from './store/atomic-write.js';
+export { assertSafeMemory, assertSafeMemoryFileContent, findSensitiveMemoryContentRule, findSensitiveMemoryTitleTerm, hasSensitiveMemoryContent, SENSITIVE_MEMORY_CHECKS, UnsafeMemoryError, writeNewFile } from './store/atomic-write.js';
 export { ensureMemoryBootstrap, emptyByKind, emptyIndex, listMarkdownFiles, readProjectMemories, readProjectMemoryBody } from './index/search.js';
 export { buildMemoryIndex, generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
 export { executeMemoryReindex, renderMemoryMarkdown, KIND_ORDER, MEMORY_MD_BANNER, MEMORY_MD_FILENAME } from './index/reindex.js';

package/dist/services/memory/project-memory-service/index.js

@@ -19,7 +19,7 @@ export { describeMemoryBlockDrops, describeSessionScanFailures, summarizeBackupR
 export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
 // Store: path safety + sensitive content
 export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
-export { assertSafeMemory, assertSafeMemoryFileContent, findSensitiveMemoryTitleTerm, hasSensitiveMemoryContent, SENSITIVE_MEMORY_CHECKS, UnsafeMemoryError, writeNewFile } from './store/atomic-write.js';
+export { assertSafeMemory, assertSafeMemoryFileContent, findSensitiveMemoryContentRule, findSensitiveMemoryTitleTerm, hasSensitiveMemoryContent, SENSITIVE_MEMORY_CHECKS, UnsafeMemoryError, writeNewFile } from './store/atomic-write.js';
 // Index: search / ranking / dispatch
 export { ensureMemoryBootstrap, emptyByKind, emptyIndex, listMarkdownFiles, readProjectMemories, readProjectMemoryBody } from './index/search.js';
 export { buildMemoryIndex, generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';

package/dist/services/memory/project-memory-service/store/atomic-write.d.ts

@@ -24,6 +24,12 @@ export declare const SENSITIVE_MEMORY_CHECKS: {
  * a value — so echoing it into the error envelope cannot leak anything.
  */
 export declare function findSensitiveMemoryTitleTerm(title: string): string | null;
+/**
+ * Which content rule refused this text — the id, never the match. A rule whose
+ * candidate fails `shaped` does not stop the scan: a later rule may still fire,
+ * exactly as a later alternative in the old `||` chain would have.
+ */
+export declare function findSensitiveMemoryContentRule(content: string): string | null;
 export declare function hasSensitiveMemoryContent(content: string): boolean;
 /**
  * The refusal `assertSafeMemory` raises: the check that fired and the term it
@@ -42,19 +48,25 @@ export declare function hasSensitiveMemoryContent(content: string): boolean;
  * `check` for the same reason — a substring test against a message whose words
  * can be rewritten is not a routing rule, it is a guess.
  *
- * NOTHING HERE WEAKENS THE REDACTOR. The content scan never puts its match in
- * this object (see `matchedTerm` below), so no value can reach an envelope
- * through it; the redactor's guarantee is intact and is pinned by the cases in
+ * NOTHING HERE WEAKENS THE REDACTOR. Both scans put a NAME in this field, never
+ * a match: the title term comes from `SENSITIVE_PROSE_TERMS` and the content
+ * value from the closed id list in `SENSITIVE_CONTENT_RULES`, so no credential
+ * can reach an envelope through it. The redactor's guarantee over `message` is
+ * intact and is pinned by the cases in
  * `tests/unit/services/memory/memory-title-sensitive-scan.test.ts`.
  */
 export declare class UnsafeMemoryError extends Error {
     /** One of `SENSITIVE_MEMORY_CHECKS` — which rule refused the write. */
     readonly check: string;
     /**
-     * The credential term the TITLE scan matched, or `null` for the other two
-     * checks. `null` is not an omission: their match can BE the credential
-     * (`ghp_…`, the PEM header, the JWT), which is why their messages describe
-     * the pattern family and never echo the text.
+     * WHAT matched, as a name rather than a value: the credential term for the
+     * title scan, the rule id for the content scan, `null` only for the metadata
+     * key scan (whose predicate answers by a config-key vocabulary the memory
+     * metadata never contains — see the note on `assertSafeMemory`).
+     *
+     * It is never the match itself: for most content patterns the match IS the
+     * credential (`ghp_…`, the PEM header, the JWT), which is why their messages
+     * describe the pattern family and never echo the text.
      */
     readonly matchedTerm: string | null;
     constructor(check: string, detail: string, matchedTerm?: string | null);

package/dist/services/memory/project-memory-service/store/atomic-write.js

@@ -4,7 +4,9 @@
 //   - `hasSensitiveMemoryContent` — pattern check for api keys, tokens,
 //     PEM private keys, JWTs, GitHub / GitLab tokens, AWS access keys. Used
 //     both by the extract path (`assertSafeMemory`) and the backup path
-//     (`assertSafeMemoryFileContent`).
+//     (`assertSafeMemoryFileContent`). It is a wrapper over
+//     `findSensitiveMemoryContentRule`, which answers the same question and
+//     names the rule that answered it.
 //   - `findSensitiveMemoryTitleTerm` — the PROSE predicate for
 //     `memory.title`. It is deliberately NOT the config-key predicate: see
 //     the block comment above it (slice C0).
@@ -136,17 +138,89 @@ export function findSensitiveMemoryTitleTerm(title) {
     }
     return null;
 }
+/**
+ * Is this string shaped like a credential VALUE rather than like prose?
+ *
+ * WHY THIS EXISTS. The value-carrying patterns used to fire on the SEPARATOR
+ * alone: `password:` was a match whether or not anything followed it, so a
+ * memory writing `password: the field label in the form` or `myApiKey: from
+ * env` was refused for describing an interface. Two documents were killed that
+ * way before anyone could say which of ten rules had fired — and the rules
+ * could not be tightened, because nothing in them described the VALUE.
+ *
+ * THE TEST, AND WHAT IT COSTS. A value is credential-shaped when it is at least
+ * 5 characters AND carries a digit or one of `_ + / =`. `hunter2`,
+ * `abcdef123456`, `supp3rSecret` and every base64-ish token pass;
+ * `Authorization`, `the`, `from`, `abc`, `well-designed` fail. Given up
+ * deliberately: an all-letter opaque run (`bearer abcdefghijklmnopq`) is no
+ * longer caught, and neither is a 4-character real password. The alternative was
+ * a rule that cannot tell an English word from a random string, and the
+ * complaint on record is about English words. Digits are the discriminator
+ * rather than `-` and `.` because hyphens and full stops belong to ordinary
+ * prose; provider tokens in the wild carry digits, and the prefix-shaped
+ * patterns (`ghp_`, `AKIA`, the PEM header, the JWT) keep their own length floors
+ * and are untouched by this predicate.
+ */
+const MIN_VALUE_CHARS = 5;
+function isCredentialShapedValue(value) {
+    return value.length >= MIN_VALUE_CHARS && /[0-9_+/=]/.test(value);
+}
+/** A placeholder names where a value will go; it is not itself a secret. */
+const PLACEHOLDER_VALUE = /^[<[{(]|^(?:your|the|an|some|my|example|placeholder|todo|fake)/i;
+function isPlaceholderValue(value) {
+    return (PLACEHOLDER_VALUE.test(value) ||
+        /(?:replace|insert|provide|redact|<[a-z_]+>)/i.test(value) ||
+        /^[A-Za-z]+(?:_[A-Z*]+)+$/.test(value) // API_KEY_HERE-style constant
+    );
+}
+const SENSITIVE_CONTENT_RULES = [
+    {
+        id: 'credential-assignment',
+        pattern: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|password|passwd|credential|token|bearer)\s*[:=]\s*([^\s,;"'`]+)/gi,
+        shaped: (value) => isCredentialShapedValue(value) && !isPlaceholderValue(value)
+    },
+    {
+        id: 'authorization-bearer-header',
+        pattern: /\bauthorization\s*:\s*bearer\s+([^\s,;"'`]+)/gi,
+        shaped: (value) => isCredentialShapedValue(value) && !isPlaceholderValue(value)
+    },
+    {
+        id: 'bearer-value',
+        pattern: /\bbearer\s+([A-Za-z0-9._~+/=-]{8,})/gi,
+        shaped: (value) => isCredentialShapedValue(value) && !isPlaceholderValue(value)
+    },
+    {
+        id: 'sk-prefixed-key',
+        // The SUFFIX is captured, not the whole `sk-…`: `sk-abcdef is the prefix`
+        // is a sentence about the scheme, and the shape test on the suffix is what
+        // tells it from `sk-abcdef1234567890`.
+        pattern: /\bsk-([A-Za-z0-9_-]{6,})\b/g,
+        shaped: (value) => isCredentialShapedValue(value) && !isPlaceholderValue(value)
+    },
+    { id: 'gh-prefixed-key', pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g },
+    { id: 'github-pat', pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+    { id: 'glpat-prefixed-key', pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+    { id: 'akia-prefixed-key', pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+    { id: 'pem-private-key', pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+    { id: 'jwt-shaped-value', pattern: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g }
+];
+/**
+ * Which content rule refused this text — the id, never the match. A rule whose
+ * candidate fails `shaped` does not stop the scan: a later rule may still fire,
+ * exactly as a later alternative in the old `||` chain would have.
+ */
+export function findSensitiveMemoryContentRule(content) {
+    for (const rule of SENSITIVE_CONTENT_RULES) {
+        for (const match of content.matchAll(rule.pattern)) {
+            const candidate = match[1] ?? match[0];
+            if (rule.shaped === undefined || rule.shaped(candidate))
+                return rule.id;
+        }
+    }
+    return null;
+}
 export function hasSensitiveMemoryContent(content) {
-    return (/(?:api[_-]?key|token|secret|password|credential|bearer)\s*[:=]/i.test(content) ||
-        /\bauthorization\s*:\s*bearer\s+\S+/i.test(content) ||
-        /\bbearer\s+[A-Za-z0-9._~+/=-]{12,}\b/i.test(content) ||
-        /\bsk-[A-Za-z0-9_-]{6,}\b/.test(content) ||
-        /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/.test(content) ||
-        /\bgithub_pat_[A-Za-z0-9_]{20,}\b/.test(content) ||
-        /\bglpat-[A-Za-z0-9_-]{20,}\b/.test(content) ||
-        /\bAKIA[0-9A-Z]{16}\b/.test(content) ||
-        /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content) ||
-        /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(content));
+    return findSensitiveMemoryContentRule(content) !== null;
 }
 /**
  * The refusal `assertSafeMemory` raises: the check that fired and the term it
@@ -165,19 +239,25 @@ export function hasSensitiveMemoryContent(content) {
  * `check` for the same reason — a substring test against a message whose words
  * can be rewritten is not a routing rule, it is a guess.
  *
- * NOTHING HERE WEAKENS THE REDACTOR. The content scan never puts its match in
- * this object (see `matchedTerm` below), so no value can reach an envelope
- * through it; the redactor's guarantee is intact and is pinned by the cases in
+ * NOTHING HERE WEAKENS THE REDACTOR. Both scans put a NAME in this field, never
+ * a match: the title term comes from `SENSITIVE_PROSE_TERMS` and the content
+ * value from the closed id list in `SENSITIVE_CONTENT_RULES`, so no credential
+ * can reach an envelope through it. The redactor's guarantee over `message` is
+ * intact and is pinned by the cases in
  * `tests/unit/services/memory/memory-title-sensitive-scan.test.ts`.
  */
 export class UnsafeMemoryError extends Error {
     /** One of `SENSITIVE_MEMORY_CHECKS` — which rule refused the write. */
     check;
     /**
-     * The credential term the TITLE scan matched, or `null` for the other two
-     * checks. `null` is not an omission: their match can BE the credential
-     * (`ghp_…`, the PEM header, the JWT), which is why their messages describe
-     * the pattern family and never echo the text.
+     * WHAT matched, as a name rather than a value: the credential term for the
+     * title scan, the rule id for the content scan, `null` only for the metadata
+     * key scan (whose predicate answers by a config-key vocabulary the memory
+     * metadata never contains — see the note on `assertSafeMemory`).
+     *
+     * It is never the match itself: for most content patterns the match IS the
+     * credential (`ghp_…`, the PEM header, the JWT), which is why their messages
+     * describe the pattern family and never echo the text.
      */
     matchedTerm;
     constructor(check, detail, matchedTerm = null) {
@@ -193,19 +273,28 @@ export function assertSafeMemory(memory) {
     if (containsSensitiveConfigValue(metadata)) {
         throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.metadataKey, 'matched a credential key in the memory metadata');
     }
-    if (hasSensitiveMemoryContent(content)) {
-        // The match is deliberately NOT echoed, in the message or in the error's
-        // fields: for most of these patterns the match IS the credential, so
+    const contentRule = findSensitiveMemoryContentRule(content);
+    if (contentRule !== null) {
+        // The matched TEXT is deliberately NOT echoed, in the message or in the
+        // error's fields: for most of these patterns the match IS the credential, so
         // copying it would write the value this scan exists to keep out.
         //
+        // The RULE ID is echoed, and it is echoed in `matchedTerm` rather than only
+        // in prose. This used to be the one refusal that could not say what fired:
+        // the predicate returned a boolean, so the caller had no match to report and
+        // `matchedTerm` was `null` by construction while the title scan named its
+        // term. A reader then had to guess across documents which of ten shapes had
+        // refused them. An id from a closed vocabulary leaks nothing and answers the
+        // question, so the two paths are diagnosable the same way.
+        //
         // The DETAIL is worded around the envelope redactor's vocabulary on
         // purpose. Its catch-all (`/(secret|token|password|api[-_ ]?key)/gi`)
         // rewrites those four words wherever they appear in a failure message, so
         // naming the pattern families in their own words arrives on the CLI as
         // "an [redacted] / [redacted] / [redacted] assignment" — a remedy sentence
-        // redacted into uselessness by the very policy it agrees with. Measured on
-        // the real CLI, both wordings; this one survives intact.
-        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.content, 'matched a credential value in the memory content (a `key=value` credential assignment, a Bearer header, a PEM private key, a JWT, or a provider credential)');
+        // redacted into uselessness by the very policy it agrees with. The rule ids
+        // above are spelled to survive that pass.
+        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.content, `matched the credential pattern "${contentRule}" in the memory content`, contentRule);
     }
     const titleTerm = findSensitiveMemoryTitleTerm(memory.title);
     if (titleTerm !== null) {
@@ -213,8 +302,13 @@ export function assertSafeMemory(memory) {
     }
 }
 export function assertSafeMemoryFileContent(content) {
-    if (hasSensitiveMemoryContent(content)) {
-        throw new Error('Refusing to back up sensitive memory content');
+    const rule = findSensitiveMemoryContentRule(content);
+    if (rule !== null) {
+        // The id travels here too. This path has no `UnsafeMemoryError` (it is not
+        // the extract gate, and its callers do not route on `check`), but a backup
+        // refusal that cannot say which shape fired is the same dead end as the one
+        // the extract path used to be.
+        throw new Error(`Refusing to back up sensitive memory content (rule: ${rule})`);
     }
 }
 export function writeNewFile(path, content) {