peaks-loop 4.0.53 → 4.0.54

package/dist/services/codegraph/codegraph-config-repair-writer.js

@@ -3,7 +3,10 @@
 // The pure repair plans (`repairCodegraphExclude` for the exclude axis,
 // `repairCodegraphInclude` for the include axis) and the writer that applies
 // them to `<projectRoot>/.codegraph/config.json` in ONE atomic rewrite, plus
-// the byte-exact `config.json.bak` copy it keeps for rollback.
+// the byte-exact `config.json.bak` copy it keeps for rollback and
+// `rollbackCodegraphConfig`, that copy's reader (slice A1 of
+// `2026-09-17-session-607ead`: the reverse write, so the rollback the `.bak`
+// has always promised is reachable).
 //
 // Extracted verbatim from `codegraph-exclude-repair.ts` (rid
 // 2026-09-17-oversize-followup, G1 — the 800-line file-size cap). Every moved
@@ -142,6 +145,40 @@ function writeConfigAtomic(filePath, content, mode) {
         throw error;
     }
 }
+/**
+ * The shared shape of the two refusals this module makes at the FIXED,
+ * therefore guessable, `config.json.bak` path: a symbolic link (bytes land in
+ * whatever it points at), a directory (there is nowhere for them to land), or
+ * a hard link (`nlink > 1` — another name shares this inode). Returns `null`
+ * when the path is absent or is a plain regular file, the only two states both
+ * ends of the rollback contract may act on.
+ *
+ * ONE predicate, two callers, and that is the point: `writeConfigBackup`
+ * WRITES this copy and `rollbackCodegraphConfig` READS it back. A guard that
+ * drifted between the two would leave the rollback trusting a path the writer
+ * would have refused, so the refusal is the same at both ends because the
+ * trust premise is the same at both ends.
+ *
+ * `lstat`, never `stat`: `stat` follows a link and reports the victim's
+ * regular-file type, which is exactly the case both callers must refuse.
+ */
+function linkOrDirectoryAt(path) {
+    const existing = lstatSync(path, { throwIfNoEntry: false });
+    if (existing === undefined ||
+        (!existing.isSymbolicLink() && !existing.isDirectory() && existing.nlink <= 1)) {
+        return null;
+    }
+    return {
+        // "through" for a link (the bytes land in whatever it points at), "at" for
+        // a directory (there is nowhere for them to land).
+        preposition: existing.isDirectory() ? 'at' : 'through',
+        kind: existing.isSymbolicLink()
+            ? 'a symbolic link'
+            : existing.isDirectory()
+                ? 'a directory'
+                : `a hard link (link count ${String(existing.nlink)})`
+    };
+}
 /**
  * Copy the config's ORIGINAL bytes to `config.json.bak`, refusing to write
  * through a link that already occupies that path.
@@ -207,18 +244,9 @@ function writeConfigAtomic(filePath, content, mode) {
  */
 function writeConfigBackup(configPath, originalText) {
     const backupPath = `${configPath}${CODEGRAPH_CONFIG_BACKUP_SUFFIX}`;
-    const existing = lstatSync(backupPath, { throwIfNoEntry: false });
-    if (existing !== undefined &&
-        (existing.isSymbolicLink() || existing.isDirectory() || existing.nlink > 1)) {
-        const kind = existing.isSymbolicLink()
-            ? 'a symbolic link'
-            : existing.isDirectory()
-                ? 'a directory'
-                : `a hard link (link count ${String(existing.nlink)})`;
-        // "through" for a link (the bytes land in whatever it points at), "at" for
-        // a directory (there is nowhere for them to land).
-        const preposition = existing.isDirectory() ? 'at' : 'through';
-        throw new Error(`codegraph config backup ${backupPath}: refusing to write ${preposition} ${kind} occupying ` +
+    const occupied = linkOrDirectoryAt(backupPath);
+    if (occupied !== null) {
+        throw new Error(`codegraph config backup ${backupPath}: refusing to write ${occupied.preposition} ${occupied.kind} occupying ` +
             'this path. Another file or directory shares it, so a backup written here would overwrite ' +
             'that. Remove it (or point `peaks` at a project root whose `.codegraph/` it owns) and re-run.');
     }
@@ -320,3 +348,74 @@ export function applyCodegraphConfigRepair(projectRoot, repair) {
         includeCountAfter: includePlan.include.length
     };
 }
+// ─────────────────────────────────────────────────────────────────────
+// Rollback — the read side of the `.bak`
+// ─────────────────────────────────────────────────────────────────────
+/** Local, because this module must not import `codegraph-exclude-repair.ts`. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Put `configPath` back to the bytes `writeConfigBackup` saved beside it, and
+ * back to the mode those bytes were saved with.
+ *
+ * This is the reverse of `applyCodegraphConfigRepair`'s write half and the only
+ * reason the `.bak` exists: until this function, the backup had no reader
+ * anywhere in the repository, so "byte-exact rollback" described a file nobody
+ * ever restored.
+ *
+ * The guard is `linkOrDirectoryAt` — the SAME predicate that refuses to WRITE
+ * through a link at the backup path refuses to READ through one here. The
+ * attack it closes is the mirror image of the writer's: `config.json.bak` is
+ * fixed and committable, so a repository that ships it as a link would
+ * otherwise have the link's target's bytes published into `.codegraph/config.json`
+ * as if they were the pre-repair config — attacker-chosen content, written
+ * under the operator's own config path, from a file the operator never
+ * reviewed. A refusal is a refusal and not a repair, at both ends.
+ *
+ * The restore runs through `writeConfigAtomic` (same-directory CSPRNG temp +
+ * `renameSync`) for the same reason the backup write does: a crash mid-write
+ * must leave the repaired config intact rather than a prefix of the restored
+ * one, and the mode is applied to the TEMP before the rename so the published
+ * file never exists at the process umask. The mode comes from `statSync` of the
+ * backup, symmetrical with the write end: the copy carries the original
+ * config's mode, so handing that mode back to the config restores what the
+ * project had granted rather than this process's umask.
+ *
+ * A refusal, or a backup that cannot be read, is RETURNED rather than thrown:
+ * the caller reports it as a field and must keep going — the forced rebuild it
+ * was asked for still has to run. `writeConfigAtomic`'s own fs throw is left to
+ * propagate, and the caller catches that too.
+ */
+export async function rollbackCodegraphConfig(configPath) {
+    const backupPath = `${configPath}${CODEGRAPH_CONFIG_BACKUP_SUFFIX}`;
+    const occupied = linkOrDirectoryAt(backupPath);
+    if (occupied !== null) {
+        return {
+            rolledBack: false,
+            configPath,
+            backupPath,
+            error: `codegraph config rollback ${backupPath}: refusing to restore ${occupied.preposition} ${occupied.kind} occupying ` +
+                'this path. A backup this writer did not create is not a rollback point, and restoring through it ' +
+                'would publish bytes nobody reviewed. Restore it by hand and re-run.'
+        };
+    }
+    let originalText;
+    let originalMode;
+    try {
+        originalText = readFileSync(backupPath, 'utf8');
+        // `& 0o777` drops the file-type bits `statSync` packs above the permission
+        // bits — `chmod` takes permission bits only.
+        originalMode = statSync(backupPath).mode & 0o777;
+    }
+    catch (error) {
+        return {
+            rolledBack: false,
+            configPath,
+            backupPath,
+            error: `codegraph config rollback: cannot read ${backupPath}: ${errorMessage(error)}`
+        };
+    }
+    writeConfigAtomic(configPath, originalText, originalMode);
+    return { rolledBack: true, configPath, backupPath };
+}

package/dist/services/codegraph/codegraph-exclude-repair.d.ts

@@ -64,7 +64,15 @@ export type CodegraphExcludeRepairReport = {
      * AND the reads failed (there is no config to name).
      */
     readonly configPath: string;
-    /** Byte-exact rollback copy (null when nothing was written). */
+    /**
+     * Byte-exact rollback copy (null when nothing was written).
+     *
+     * It is a rollback POINT, not a rollback: nothing in this seam reads it back.
+     * Putting the config back is the separate, explicit
+     * `peaks codegraph config-restore` verb, so this field is what that verb
+     * would read — and its presence is the one guarantee that a restore is
+     * possible at all.
+     */
     readonly backupPath: string | null;
     /** True when the post-repair `codegraph index` finished successfully. */
     readonly reindexed: boolean;
@@ -127,6 +135,20 @@ export type CodegraphExcludeRepairOptions = {
      * C) exists so that upgrading peaks-loop cannot change a downstream
      * project's cost profile, and purging dead rows is the caller's explicit
      * request instead.
+     *
+     * `'force'` changes ONLY the rebuild, never the config: it is the same
+     * two-axis repair as `'exclude'`, followed by `cg.clear()` + `indexAll()`
+     * instead of an incremental index. The config repair STAYS — that is what
+     * makes the force mode worth its cost, because `include` has to be widened
+     * before a rebuild can admit the files the config was dropping.
+     *
+     * Not a self-cancelling run, and that is a design decision rather than a
+     * detail: a mode that wrote the repair and then restored the pre-repair bytes
+     * would leave the config exactly as it found it, `peaks codegraph status`
+     * would still report the gap, and exit 75 would never clear. Putting the
+     * config BACK is the explicit `peaks codegraph config-restore` verb, which
+     * reads the `.bak` this run leaves — an operator decision, not a side effect
+     * of asking for a rebuild.
      */
     readonly reindex?: boolean | 'force';
 };

package/dist/services/codegraph/codegraph-exclude-repair.js

@@ -64,6 +64,12 @@
 //     consumer project (`config.json.bak` matches neither the peaks-loop
 //     snippet nor upstream's own `.codegraph/.gitignore`), so both files
 //     are committable.
+//   - `rollbackCodegraphConfig` is that copy's READER, and it is reached by the
+//     EXPLICIT `peaks codegraph config-restore` verb — never from here. A
+//     repair must not undo itself: this seam's job is to close the gap, so a
+//     run that restored its own write would leave the config exactly as it
+//     found it and `peaks codegraph status` still reporting the gap (exit 75
+//     never clearing). Rolling back is an operator decision, not a step.
 //   - The DIRECTORY both paths live in is contained: `assertCodegraphDirContained`
 //     refuses when `<projectRoot>/.codegraph` resolves (junction or symlink)
 //     outside the canonical project root, so neither the read nor either

package/dist/services/evidence/evidence-generator.js

@@ -31,6 +31,7 @@
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { serializeHandoffFrontmatter } from '../prd/handoff-frontmatter.js';
+import { deriveGateEvidenceForRequest } from '../prd/gate-evidence-derivation.js';
 import { handoffRelativePath, sha256OfBody } from '../prd/handoff-service.js';
 import { getSessionDir } from '../session/getSessionDir.js';
 import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
@@ -260,7 +261,7 @@ function buildQaRequest(rid, sid, files) {
  * producer/consumer divergence rid `2026-09-14-handoff-writer-gate-divergence`
  * exists to remove, surviving in a function the same slice edited.
  */
-function buildHandoff(rid, sid, title, files, lineCounts) {
+function buildHandoff(rid, sid, title, files, lineCounts, gateEvidence) {
     const body = `# PRD Handoff — ${rid}
 
 ${title}. Mechanical verbatim module split; behavior-preserving.
@@ -281,7 +282,13 @@ ${lineCountsMd(lineCounts)}
         goals: [],
         acceptanceCriteria: [],
         preservedBehavior: [],
-        handoffPath: handoffRelativePath(sid, rid)
+        handoffPath: handoffRelativePath(sid, rid),
+        // B2 / F1: the THIRD frontmatter producer. B1 left this one untouched and
+        // QA found it, so a `peaks evidence generate` capsule and a
+        // `peaks prd handoff init` capsule for the same slice disagreed about the
+        // same contract. Passed in rather than derived here so this function stays
+        // synchronous and disk-free; the caller derives.
+        ...(gateEvidence === undefined ? {} : { gateEvidence })
     };
     return { content: `${serializeHandoffFrontmatter(frontmatter)}${body}`, hash: handoffHash };
 }
@@ -334,7 +341,8 @@ export async function generateEvidence(options) {
         createdDirectories.push(dir);
     }
     const qaRequestPath = await resolveQaRequestPath(qaDir, rid);
-    const handoff = buildHandoff(rid, sessionId, title, files, lineCounts);
+    const gateEvidence = await deriveGateEvidenceForRequest({ projectRoot, sessionId, requestId: rid });
+    const handoff = buildHandoff(rid, sessionId, title, files, lineCounts, gateEvidence);
     // Four of these twelve paths carry the rid because the `rd:qa-handoff` gate
     // requires `<rid>` in them: every slice in a session shares `rd/` and
     // `audit/`, so writing the ridless name silently destroyed the previous

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, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';
+export { assertSafeMemory, assertSafeMemoryFileContent, 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, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';
+export { assertSafeMemory, assertSafeMemoryFileContent, 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

@@ -1,5 +1,64 @@
 import type { ExtractedProjectMemory } from '../types.js';
+/**
+ * The names of the three checks `assertSafeMemory` can fail on, written once.
+ *
+ * The name of the check that fired rides the refusal message, so the reader is
+ * told WHICH rule stopped the write instead of only that something was
+ * refused. Callers route their remedy on these same constants (see
+ * `memoryExtractNextActions` in `src/cli/commands/core/memory-command.ts`) —
+ * two strings kept equal by hand is how a message and its advice drift apart.
+ */
+export declare const SENSITIVE_MEMORY_CHECKS: {
+    readonly metadataKey: "metadata key scan";
+    readonly content: "content scan";
+    readonly title: "title scan";
+};
+/**
+ * The credential term this title contains (as a run of words), or `null`.
+ *
+ * Returns the MATCHED TERM rather than a boolean because the refusal message
+ * names it: `title scan matched the credential term "apikey"` is actionable,
+ * while "Refusing to store sensitive memory content" is what sent slice C0's
+ * user looking for a secret that was not there. The returned string is a
+ * dictionary word from the list above — never the title's own text, and never
+ * a value — so echoing it into the error envelope cannot leak anything.
+ */
+export declare function findSensitiveMemoryTitleTerm(title: string): string | null;
 export declare function hasSensitiveMemoryContent(content: string): boolean;
+/**
+ * The refusal `assertSafeMemory` raises: the check that fired and the term it
+ * matched travel as DATA, not only as prose.
+ *
+ * WHY A TYPE RATHER THAN A MESSAGE. The envelope redactor behind every
+ * `fail()` (`packages/peaks-loop-shared/src/result.ts`) strips the words
+ * secret / token / password / api-key out of every failure MESSAGE — a blanket
+ * rule, applied to messages this module does not own. So a message that names
+ * the matched term reaches the CLI reading `… the credential term
+ * "[redacted]" …`: the term is named, and then removed, on the way out.
+ *
+ * The term is a word from `SENSITIVE_PROSE_TERMS` — a fixed vocabulary, never a
+ * value — so there is nothing about it to redact, and it rides a field
+ * instead: `fail()` redacts `message` only. The CLI routes its remedy on
+ * `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
+ * `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.
+     */
+    readonly matchedTerm: string | null;
+    constructor(check: string, detail: string, matchedTerm?: string | null);
+}
 export declare function assertSafeMemory(memory: ExtractedProjectMemory): void;
 export declare function assertSafeMemoryFileContent(content: string): void;
 export declare function writeNewFile(path: string, content: string): void;

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

@@ -5,9 +5,13 @@
 //     PEM private keys, JWTs, GitHub / GitLab tokens, AWS access keys. Used
 //     both by the extract path (`assertSafeMemory`) and the backup path
 //     (`assertSafeMemoryFileContent`).
+//   - `findSensitiveMemoryTitleTerm` — the PROSE predicate for
+//     `memory.title`. It is deliberately NOT the config-key predicate: see
+//     the block comment above it (slice C0).
 //   - `assertSafeMemory` — full safety gate applied during extraction.
-//     Combines title/body content scan + config-service secret check +
-//     sensitive-path check on the title.
+//     Combines the metadata key scan + the content pattern scan + the title
+//     scan. Each failure names the check that fired, and the title one names
+//     the term it matched.
 //   - `assertSafeMemoryFileContent` — lighter version for backup: just
 //     the content pattern scan, since the file already lives in
 //     `.peaks/memory/` and was authored through the normal pipeline.
@@ -17,7 +21,109 @@
 //     for index.json regeneration.
 // ---------------------------------------------------------------------------
 import { closeSync, constants, openSync, writeFileSync } from 'node:fs';
-import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../../../config/config-service.js';
+import { containsSensitiveConfigValue } from '../../../config/config-service.js';
+/**
+ * The names of the three checks `assertSafeMemory` can fail on, written once.
+ *
+ * The name of the check that fired rides the refusal message, so the reader is
+ * told WHICH rule stopped the write instead of only that something was
+ * refused. Callers route their remedy on these same constants (see
+ * `memoryExtractNextActions` in `src/cli/commands/core/memory-command.ts`) —
+ * two strings kept equal by hand is how a message and its advice drift apart.
+ */
+export const SENSITIVE_MEMORY_CHECKS = {
+    metadataKey: 'metadata key scan',
+    content: 'content scan',
+    title: 'title scan'
+};
+/** The stable prefix of every refusal this module raises on the extract path. */
+const SENSITIVE_MEMORY_REFUSAL = 'Refusing to store sensitive memory content';
+/**
+ * Credential TERMS as they appear in prose — the word-level counterpart of the
+ * config-key predicate `config-service.isSensitiveConfigPath`.
+ *
+ * WHY THE TITLE CHECK EXISTS AT ALL (it is not redundant with the content
+ * scanner). `hasSensitiveMemoryContent` looks for a credential *value*: its
+ * first pattern needs a `:` or `=`, so a title that is nothing but `apiKey`
+ * carries no value and slips past it. The title scan is the only rule that can
+ * see "the title IS a credential name" — so this check was kept, and only its
+ * predicate was replaced.
+ *
+ * WHY IT DOES NOT REUSE `isSensitiveConfigPath`. That predicate answers "is
+ * this a CONFIG KEY", and it answers by SUBSTRING: `includes('auth')` is true
+ * for `authority`, `author`, `unauthorized`. On a config key that breadth is
+ * harmless — an auth-bearing key IS a credential key, and the config domain is
+ * untouched here. On a prose title it is a false refusal the author cannot see
+ * the cause of: slice C0, where `peaks memory extract` refused a memory titled
+ * "Derive from the authority, never re-declare it" and told the user to
+ * "remove secrets" from a memory that had none.
+ *
+ * HOW IT MATCHES. The title is cut into alphanumeric segments (camelCase
+ * boundaries included) and a match is a CONTIGUOUS RUN of segments whose
+ * concatenation is one of the terms below. Runs — not single words — are what
+ * keep the credential-name spellings a substring check caught and a naive
+ * word-per-word check would lose: `private_key`, `api key`, `myApiKey` and
+ * `access token` all still match, while `authority`, `author`, `tokenizer`,
+ * `secretary` and `credentialed` do not.
+ *
+ * The residual narrowing is named rather than hidden: an UNSEPARATED compound
+ * with a term buried mid-word (`mysecretstuff`) no longer matches. That is the
+ * same class as the false refusals above — a word containing `secret` is not a
+ * credential term — and the memory body is scanned for values either way.
+ *
+ * The plural forms are listed explicitly instead of deriving them by stripping
+ * a trailing `s` from each match: that rule would turn `secretaries` into
+ * `secretarie` → `secret`, which is precisely the substring confusion this
+ * predicate exists to end.
+ */
+const SENSITIVE_PROSE_TERMS = new Set([
+    'apikey', 'apikeys',
+    'accesskey', 'accesskeys',
+    'privatekey', 'privatekeys',
+    'secretkey', 'secretkeys',
+    'accesstoken', 'accesstokens',
+    'authtoken', 'authtokens',
+    'authkey', 'authkeys',
+    'refreshtoken', 'refreshtokens',
+    'token', 'tokens',
+    'secret', 'secrets',
+    'password', 'passwords',
+    'passwd',
+    'bearer',
+    'credential', 'credentials'
+]);
+/** A lower→upper transition: the boundary between the words of `apiKey`. */
+const CAMEL_CASE_BOUNDARY = /([a-z0-9])([A-Z])/g;
+/** `myApiKey` → `['my', 'api', 'key']`; `private_key` → `['private', 'key']`. */
+function proseSegments(text) {
+    return text
+        .replace(CAMEL_CASE_BOUNDARY, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((segment) => segment.length > 0);
+}
+/**
+ * The credential term this title contains (as a run of words), or `null`.
+ *
+ * Returns the MATCHED TERM rather than a boolean because the refusal message
+ * names it: `title scan matched the credential term "apikey"` is actionable,
+ * while "Refusing to store sensitive memory content" is what sent slice C0's
+ * user looking for a secret that was not there. The returned string is a
+ * dictionary word from the list above — never the title's own text, and never
+ * a value — so echoing it into the error envelope cannot leak anything.
+ */
+export function findSensitiveMemoryTitleTerm(title) {
+    const segments = proseSegments(title);
+    for (let start = 0; start < segments.length; start += 1) {
+        let run = '';
+        for (let end = start; end < segments.length; end += 1) {
+            run += segments[end];
+            if (SENSITIVE_PROSE_TERMS.has(run))
+                return run;
+        }
+    }
+    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)
@@ -30,14 +136,68 @@ export function hasSensitiveMemoryContent(content) {
         || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)
         || /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(content);
 }
+/**
+ * The refusal `assertSafeMemory` raises: the check that fired and the term it
+ * matched travel as DATA, not only as prose.
+ *
+ * WHY A TYPE RATHER THAN A MESSAGE. The envelope redactor behind every
+ * `fail()` (`packages/peaks-loop-shared/src/result.ts`) strips the words
+ * secret / token / password / api-key out of every failure MESSAGE — a blanket
+ * rule, applied to messages this module does not own. So a message that names
+ * the matched term reaches the CLI reading `… the credential term
+ * "[redacted]" …`: the term is named, and then removed, on the way out.
+ *
+ * The term is a word from `SENSITIVE_PROSE_TERMS` — a fixed vocabulary, never a
+ * value — so there is nothing about it to redact, and it rides a field
+ * instead: `fail()` redacts `message` only. The CLI routes its remedy on
+ * `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
+ * `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.
+     */
+    matchedTerm;
+    constructor(check, detail, matchedTerm = null) {
+        super(`${SENSITIVE_MEMORY_REFUSAL}: ${check} ${detail}.`);
+        this.name = 'UnsafeMemoryError';
+        this.check = check;
+        this.matchedTerm = matchedTerm;
+    }
+}
 export function assertSafeMemory(memory) {
     const content = `${memory.title}\n${memory.kind}\n${memory.body}`;
     const metadata = { title: memory.title, kind: memory.kind, body: memory.body };
-    if (containsSensitiveConfigValue(metadata) || hasSensitiveMemoryContent(content)) {
-        throw new Error('Refusing to store sensitive memory content');
+    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
+        // copying it would write the value this scan exists to keep out.
+        //
+        // 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)');
     }
-    if (isSensitiveConfigPath(memory.title)) {
-        throw new Error('Refusing to store sensitive memory content');
+    const titleTerm = findSensitiveMemoryTitleTerm(memory.title);
+    if (titleTerm !== null) {
+        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.title, `matched the credential term "${titleTerm}" in memory.title`, titleTerm);
     }
 }
 export function assertSafeMemoryFileContent(content) {