greprag 5.46.0 → 5.48.0

package/dist/hook.js

@@ -71,6 +71,13 @@ const opencode_plugin_helpers_1 = require("./opencode-plugin-helpers");
 // Mechanic dispatcher (Chip B) — PreToolUse guard + matchset boot pull/refresh.
 // docs/mechanic-repairs.md D1/D2/D5/D8; docs/mechanic-engine-contracts.md.
 const guard_1 = require("./guard");
+// Reminder-interrupt registry (docs/reminder-interrupt.md §Registry spec) — the
+// detector model: each module detects a live deficiency, fires while it holds, and
+// auto-silences when resolved (the arm-check pattern). The hook below assembles the
+// live env (ALL I/O) and emits; the modules are pure.
+const reminder_registry_1 = require("./commands/reminder-registry");
+const friction_reminder_1 = require("./commands/friction-reminder");
+const memory_reflex_1 = require("./commands/memory-reflex");
 const worktree_state_1 = require("./worktree-state");
 // Ingress-trigger bridge, Adapter A (LOCAL/state half) — the Stop hook computes
 // the deterministic state values (stress / turnCount / keyword-seen) from the
@@ -778,6 +785,37 @@ async function store(input, source = 'claude-code') {
     if (source === 'codex') {
         turn.toolCalls.push(...(0, codex_hook_events_1.readCodexSubagentToolCalls)(input));
     }
+    // Memory-reflex EFFICACY capture (adr/memory-reflex.md). If a memory injection was surfaced
+    // this turn: (1) score the FREE overlap proxy locally → bump the `used` numerator, and (2)
+    // carry the injection onto the turn POST so the server-side Flash-Lite judge (Chip A) can
+    // score it accurately. Consume-once: the stash is always cleared, so a turn with no injection
+    // never reuses a stale sample. adr: adr/memory-reflex.md
+    let memoryInjectionForStore = null;
+    try {
+        const effShort = (0, session_id_1.truncateSessionId)(input.session_id);
+        if (effShort) {
+            const pending = consumeMemoryInjection(effShort);
+            if (pending) {
+                memoryInjectionForStore = pending.hitText;
+                if ((0, memory_reflex_1.injectionWasUsed)(pending.hitText, turn.userPrompt, turn.agentResponse)) {
+                    recordMemoryUsed(pending.projectId);
+                }
+            }
+        }
+    }
+    catch { /* efficacy capture is best-effort — never block the turn */ }
+    // Self-report scan (P1b, adr/memory-reflex.md). If the agent emitted a [[recall: X]] marker
+    // (taught by the memory announce) it's flagging its OWN context gap → stash the topic so the
+    // NEXT turn's notify pulls + injects it (the self-report trigger). Best-effort.
+    try {
+        const srShort = (0, session_id_1.truncateSessionId)(input.session_id);
+        if (srShort && anchor.projectId) {
+            const topic = (0, memory_reflex_1.extractRecallMarker)(turn.agentResponse);
+            if (topic)
+                stashSelfReport(srShort, anchor.projectId, topic);
+        }
+    }
+    catch { /* best-effort — never block the turn */ }
     // Empty turn — nothing to capture.
     if (!turn.userPrompt && !turn.agentResponse && turn.toolCalls.length === 0)
         return;
@@ -814,6 +852,12 @@ async function store(input, source = 'claude-code') {
         status: turn.status,
         userPrompt,
         agentResponse,
+        // The memory injection surfaced this turn (when any) — the SEAM the Flash-Lite efficacy
+        // judge (Chip A) consumes server-side at ingest to score used÷injected. Scrubbed + capped
+        // like the other text fields. Omitted entirely on the common no-injection turn.
+        ...(memoryInjectionForStore
+            ? { memoryInjection: capField((0, secret_scrubber_1.scrubString)(memoryInjectionForStore, redaction)) }
+            : {}),
         toolCalls,
         filesTouched: turn.filesTouched,
         artifacts: artifactRefs,
@@ -822,6 +866,20 @@ async function store(input, source = 'claude-code') {
         provenance,
     });
 }
+// ---------- Main ---------------------------------------------------------
+// ---------- Recap (SessionStart) ------------------------------------------
+// `ByPeriodRow`, `stripRecapNoise`, `fmtHoursAgo`, and the recap body
+// renderer (`buildRecapBody`) are now imported from `./opencode-plugin-helpers`
+// — see adr/opencode-monitor-relay.md 2026-06-06 (g). The recap content
+// pushed to the system prompt is the same for Claude/Codex and the opencode
+// plugin; per-harness wrappers (preamble, output mode, transform-hook push)
+// stay local.
+/** Fetch a slim summary of open checkpoints for the given project. Returns
+ *  up to `limit` rows so the checkpoint module can compute the overflow
+ *  (3-most-recent + "N more" hint). Returns [] on any error — the hook
+ *  must never block on a checkpoint query failure. (OpenCheckpointSlim +
+ *  renderCheckpointHint now live in commands/checkpoint-reminder.ts; the hook
+ *  owns only this fetch.) */
 async function fetchOpenCheckpoints(apiUrl, apiKey, projectId, limit = 10) {
     try {
         const url = `${apiUrl}/v1/checkpoints/${encodeURIComponent(projectId)}`
@@ -838,33 +896,6 @@ async function fetchOpenCheckpoints(apiUrl, apiKey, projectId, limit = 10) {
         return [];
     }
 }
-/** Render a YYYY-MM-DD date in UTC for the session-start hint. */
-function fmtCheckpointDate(iso) {
-    return iso.slice(0, 10);
-}
-/** Format the open-checkpoints hint block. Shape per design doc § Hint
- *  placement: 3-most-recent rows + a single overflow line when there are
- *  more. Returns null when there are zero open checkpoints — caller
- *  treats it as silent. */
-function renderCheckpointHint(open, projectName) {
-    if (open.length === 0)
-        return null;
-    // Server returns DESC by created_at; take the 3 most recent.
-    const top = open.slice(0, 3);
-    const overflow = open.length - top.length;
-    const lines = [];
-    lines.push(`[${open.length} checkpoint${open.length === 1 ? '' : 's'} open in ${projectName}:`);
-    for (const cp of top) {
-        lines.push(`  · ${cp.nodeId}  ${cp.title} (since ${fmtCheckpointDate(cp.createdAt)})`);
-    }
-    if (overflow > 0) {
-        lines.push(`  · ${overflow} more — greprag checkpoint list]`);
-    }
-    else {
-        lines.push(` View one: greprag checkpoint show <id>]`);
-    }
-    return lines.join('\n');
-}
 /** Fetch unread inbox count for the given project context. Project-scoped
  *  count includes tenant-level messages (mail addressed to the user, not
  *  any specific project, still shows up). Returns 0 on any error so the
@@ -906,6 +937,63 @@ async function fetchFrontDeskUnread(apiUrl, apiKey) {
         return 0;
     }
 }
+/** Fetch this session's OWN unread count — messages addressed to `to_session_id =
+ *  <short>` (mail a peer or the operator sent to THIS session). Safe + non-eavesdrop:
+ *  reads only this session's mail, NOT the project-wide count the v5.6.1 removal retired
+ *  (that count betrayed a sibling session's private DMs). Powers the watcher-arm module's
+ *  grounded "a peer messaged you" nag. Returns 0 on any error. adr: adr/session-id-awareness.md */
+async function fetchSessionUnread(apiUrl, apiKey, short) {
+    try {
+        const res = await fetch(`${apiUrl}/v1/inbox?count_only=1&session_id=${encodeURIComponent(short)}`, {
+            headers: { 'Authorization': `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return 0;
+        const data = await res.json();
+        return data.unread_count || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Fetch top episodic-memory hits for a query (the memory-reflex inline path), project-
+ *  scoped, with a HARD timeout so a slow search never blocks the turn. POSTs the same
+ *  `/v1/memory/query` the CLI `memory search` uses, with the de-pollution `session-turn`
+ *  provenance filter. Returns [] on any error/abort → the reflex stays silent. The
+ *  confidence gate + framing live in buildMemoryInjection (commands/memory-reflex.ts).
+ *  adr: adr/memory-reflex.md */
+async function fetchMemoryHits(apiUrl, apiKey, projectId, query, limit = 3, timeoutMs = 2000) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${apiUrl}/v1/memory/query`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, limit, projectId, filters: { provenance: 'session-turn' } }),
+            signal: ctl.signal,
+        });
+        if (!res.ok)
+            return { hits: [], quiet: false };
+        const data = await res.json();
+        // The server's Flash-Lite efficacy verdict rides the same response (adr/memory-reflex.md).
+        const quiet = data.memoryReflexQuiet === true;
+        if (!data.ok || !Array.isArray(data.nodes))
+            return { hits: [], quiet };
+        return {
+            hits: data.nodes.map(n => ({
+                content: n.content, score: n.score, confidence: n.confidence ?? null,
+                shape: n.shape ?? null, createdAt: n.createdAt ?? null, projectName: n.projectName ?? null,
+            })),
+            quiet,
+        };
+    }
+    catch {
+        return { hits: [], quiet: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Identity-drift warning rate limiter.
  *
  *  The drift warning ("stored ID ≠ git-derived ID, run `greprag doctor`") used
@@ -1070,40 +1158,51 @@ async function recap(input, mode = 'plain') {
     // (and then read) another session's session-targeted DM. Live inbox now
     // belongs exclusively to Monitor watchers; the agent learns about its own
     // mail via the watcher's session-scoped stream.
-    // Open-checkpoints hint still fires — checkpoints are operator-triggered
-    // landmarks, not message-shape inbox traffic, no privacy issue.
+    // Open-checkpoints — checkpoints are operator-triggered landmarks, not message-shape
+    // inbox traffic, no privacy issue. The hook owns ONLY this fetch; the checkpoint module
+    // (commands/checkpoint-reminder.ts) renders the list → hint block in its announce.
     const openCheckpoints = await fetchOpenCheckpoints(cfg.apiUrl, cfg.apiKey, anchor.projectId, 10);
-    const checkpointHint = renderCheckpointHint(openCheckpoints, anchor.projectName);
-    // Front-desk awareness — a discreet count of cold opens + inbound email waiting
-    // at the shared tenant front desk, so a stranger's first contact isn't stranded
-    // until someone happens to run `greprag inbox`. Content is NEVER injected — just
-    // the count + the door. Fires once per session (SessionStart), so it's naturally
-    // deduped. This is NOT the v5.6.1 eavesdrop vector — see fetchFrontDeskUnread.
-    // (Suppressing it when a live receptionist is attached is a clean follow-up.)
-    // adr: adr/address-grammar.md (2026-06-10), docs/front-desk-switchboard.md §5
+    // Front-desk awareness — a discreet count of cold opens + inbound email waiting at the
+    // shared tenant front desk, so a stranger's first contact isn't stranded until someone
+    // runs `greprag inbox`. Content is NEVER injected — just the count + the door, formatted
+    // by the front-desk module's announce. NOT the v5.6.1 eavesdrop vector — see
+    // fetchFrontDeskUnread. adr: adr/address-grammar.md (2026-06-10), docs/front-desk-switchboard.md §5
     const frontDeskUnread = await fetchFrontDeskUnread(cfg.apiUrl, cfg.apiKey);
-    const frontDeskHint = frontDeskUnread > 0
-        ? `[📬 ${frontDeskUnread} message${frontDeskUnread === 1 ? '' : 's'} at the front desk — \`greprag inbox --front-desk\` to read]`
-        : null;
     // Assistant doctrine auto-load — fires ONLY for the flagged assistant project
-    // (isAssistantProject), so a normal project sees zero change. Computed up here
-    // so it rides EVERY exit path below (recap body present, suppressed, or empty),
-    // guaranteeing the loop loads on every session start. adr: adr/assistant-role.md
+    // (isAssistantProject), so a normal project sees zero change. The hook owns the
+    // doctrine-file read; the assistant-doctrine module routes the text. adr: adr/assistant-role.md
     const assistantDoctrine = (0, project_anchor_1.isAssistantProject)(anchor)
         ? (0, assistant_doctrine_1.buildAssistantDoctrineContext)(cwd)
         : null;
-    const preamble = () => {
-        const lines = [];
-        if (setupWarning)
-            lines.push(setupWarning);
-        if (frontDeskHint)
-            lines.push(frontDeskHint);
-        if (checkpointHint)
-            lines.push(checkpointHint);
-        if (assistantDoctrine)
-            lines.push(assistantDoctrine);
-        return lines.length ? lines.join('\n') + '\n' : '';
+    // ── THE single SessionStart announce assembly (docs/reminder-interrupt.md §Registry
+    // spec) ──────────────────────────────────────────────────────────────────────────────
+    // Every agent-facing announce — setup-warning, front-desk, checkpoint, assistant-doctrine,
+    // watcher-arm, mechanic — is now a registry module. The hook did the I/O above; here it
+    // stuffs the results into ONE env and collectAnnounces renders them in registry order.
+    // Loaded once + re-fired on compact (recap matcher ''). The Mechanic kill switch drops
+    // ONLY the mechanic announce; a missing session id drops ONLY watcher-arm.
+    const announceShort = (0, session_id_1.truncateSessionId)(input.session_id) || '';
+    const announceEnv = {
+        short: announceShort, turnCount: 0, stress: 0, armed: false, sessionUnread: 0,
+        ownerPid: announceShort ? (0, watcher_registry_1.resolveClaudeOwnerPid)(announceShort) : null,
+        alias: (0, session_id_1.readIdentityAlias)(),
+        assistant: (() => { try {
+            return (0, project_anchor_1.isAssistantProject)(anchor);
+        }
+        catch {
+            return false;
+        } })(),
+        projectName: anchor.projectName,
+        setupWarning,
+        frontDeskUnread,
+        openCheckpoints,
+        assistantDoctrine,
     };
+    let announceReg = mechanicKilled() ? reminder_registry_1.REGISTRY.filter(m => m.id !== 'mechanic-friction') : reminder_registry_1.REGISTRY;
+    if (!announceShort)
+        announceReg = announceReg.filter(m => m.id !== 'watcher-arm');
+    const announceBlock = (0, reminder_registry_1.collectAnnounces)(announceEnv, announceReg).join('\n\n') || null;
+    const preamble = () => (announceBlock ? announceBlock + '\n' : '');
     // Per-project opt-out — agent flips session_start_recap=false to suppress
     // the episodic injection for a specific project without disabling the
     // hook globally. Setup warning + checkpoint hint still fire above.
@@ -1131,20 +1230,8 @@ async function recap(input, mode = 'plain') {
         return;
     }
     const parts = [];
-    if (setupWarning) {
-        parts.push(setupWarning);
-        parts.push('');
-    }
-    if (frontDeskHint) {
-        parts.push(frontDeskHint);
-        parts.push('');
-    }
-    if (checkpointHint) {
-        parts.push(checkpointHint);
-        parts.push('');
-    }
-    if (assistantDoctrine) {
-        parts.push(assistantDoctrine);
+    if (announceBlock) {
+        parts.push(announceBlock);
         parts.push('');
     }
     parts.push(body);
@@ -1236,69 +1323,328 @@ async function notify(input, source = 'claude-code') {
             writeAdditionalContext('UserPromptSubmit', context);
         return;
     }
-    // Local-first arm detection. Ground truth is a live watcher PROCESS on THIS
-    // machine — its consumer (the Monitor task) is local, so a live supervisor
-    // pidfile means a live, consumed watcher. This replaces the server
-    // `isSessionArmed` registry check, whose ghost-lease flaw made an orphan
-    // (consumer dead, socket still open) read as "armed" — which both suppressed
-    // re-arm when the real watcher was gone AND, once the lease expired, let
-    // re-arm stack a new watcher on the undead orphan. With EPIPE-terminal + the
-    // SessionStart reaper sweeping stale pidfiles, "no live pidfile" reliably means
-    // "needs arming", lag-free and with no cloud round-trip. adr: adr/monitor-resilience.md
-    if ((0, watcher_registry_1.isLocallyArmed)(short))
-        return; // live local watcher → silent
-    // Resolve the owning claude.exe PID HERE — this hook is a live, direct
-    // descendant of it, so its ancestry is intact (the watcher's is not). Stamped
-    // into the arm command so the reaper checks "owner alive?" not "ancestry
-    // reachable?". Only runs on unarmed turns (we returned above if armed).
-    // adr: adr/monitor-resilience.md
-    const ownerPid = (0, watcher_registry_1.resolveClaudeOwnerPid)(short);
-    // Assistant project → arm an elevated watcher (`--assistant`) so the session
-    // wakes on inbound tenant email, not just its own DMs. Scoped strictly to the
-    // flagged project; every other project arms a stock watcher. Fail-open: an
-    // anchor read failure just yields a normal arm. adr: adr/assistant-role.md
-    let assistant = false;
+    // Reminder-interrupt registry container (docs/reminder-interrupt.md §Registry spec):
+    // a detector loop over the watcher-arm + mechanic-friction modules. Runs HERE — in the
+    // proven-registered `notify` hook — so arming never depends on a freshly-merged
+    // subcommand reaching the operator's settings. Fires whatever's deficient (stacking),
+    // and auto-silences each module the instant its deficiency resolves.
+    await injectReminders(input, cfg, short);
+}
+/** Has the operator hit the Mechanic kill switch (`mechanic off` → the D8 panic
+ *  switch file the guard dispatcher also checks first)? When set, the active-
+ *  Mechanic pair (SessionStart announce + per-turn friction reminder) stays quiet,
+ *  so the same switch that quiets the dispatcher quiets this pair too. Fail-quiet:
+ *  any fs error reads as NOT killed (the pair keeps working). */
+function mechanicKilled() {
     try {
-        assistant = (0, project_anchor_1.isAssistantProject)((0, project_anchor_1.readAnchor)(input.cwd || process.cwd()));
-    }
-    catch { /* fail-open — normal arm */ }
-    writeAdditionalContext('UserPromptSubmit', (0, session_id_1.buildArmDirective)(short, (0, session_id_1.readIdentityAlias)(), ownerPid, assistant));
-}
-/** "You've got mail" turn hook (Chip B) — wire as a UserPromptSubmit hook.
- *  Each turn, ask the server for ENVELOPE-ONLY pending front-desk mail and
- *  inject a one-line "you've got mail from X" notice for any arrival not yet
- *  announced on this machine. It feeds the human sign-off gate — it NEVER
- *  ingests body (front-desk store contract invariant 2/3); the data path is
- *  body-free end to end (envelope type has no body field, server projection
- *  withholds it). Self-silences once each record is announced; the agent stops
- *  the loop by acting on the mail (`greprag email` marks it read).
+        return fs.existsSync((0, guard_1.killSwitchPath)());
+    }
+    catch {
+        return false;
+    }
+}
+/** Local path for this project's friction-reminder fire-counter (Measurement,
+ *  docs/reminder-interrupt.md). Sits beside the matchset cache under the shared
+ *  `~/.greprag/state` dir. */
+function frictionStatsPath(projectId) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state', `friction-reminder-${projectId}.json`);
+}
+/** Fire-counter I/O (the adherence DENOMINATOR). Reads the prior stats, tallies one
+ *  fire via the PURE tallyFrictionFire, writes them back. Fully best-effort: a miss
+ *  never blocks the turn. The numerator (reflex chips actually spawned) lands via
+ *  tallyReflexSpawn from the spawn path — see the report's Measurement note. */
+function recordFrictionFire(projectId, tier, turnCount) {
+    try {
+        const file = frictionStatsPath(projectId);
+        let prior = null;
+        try {
+            prior = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch { /* none yet */ }
+        const next = (0, friction_reminder_1.tallyFrictionFire)(prior, tier, turnCount, new Date().toISOString());
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch { /* counter is best-effort — never block the turn */ }
+}
+/** Local path for this project's memory-reflex fire-counter — the data the /mechanic
+ *  excessiveness monitor reads (fires · injected · silent · per-trigger). Beside the
+ *  friction counter under ~/.greprag/state. */
+function memoryReflexStatsPath(projectId) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state', `memory-reflex-${projectId}.json`);
+}
+/** Tally one memory-reflex fire (best-effort). `didInject` splits fire→injected vs silent
+ *  so the monitor can read the inject/fire ratio (firing without finding = noise). */
+function recordMemoryFire(projectId, trigger, didInject, turnCount) {
+    try {
+        const file = memoryReflexStatsPath(projectId);
+        let prior = null;
+        try {
+            prior = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch { /* none yet */ }
+        const next = (0, memory_reflex_1.tallyMemoryFire)(prior, trigger, didInject, turnCount, new Date().toISOString());
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch { /* counter is best-effort — never block the turn */ }
+}
+/** Stash for the memory-reflex efficacy capture — the raw hit content injected THIS turn, so
+ *  the Stop hook can score the response's overlap against it (the `used` numerator). Keyed by
+ *  session (Stop has the short id); carries projectId so Stop needn't re-derive it. Written at
+ *  inject-time, consumed + deleted at Stop. adr: adr/memory-reflex.md */
+function memoryReflexPendingPath(short) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state', `memory-reflex-pending-${short}.json`);
+}
+function stashMemoryInjection(short, projectId, hitText, turnCount) {
+    try {
+        const file = memoryReflexPendingPath(short);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ projectId, hitText, turnCount }) + '\n');
+    }
+    catch { /* best-effort — a missed stash just means no efficacy sample this turn */ }
+}
+/** Read + DELETE the pending injection stash (consume-once, so a turn with no injection never
+ *  reuses a stale sample). Returns null on the common no-stash path. */
+function consumeMemoryInjection(short) {
+    try {
+        const file = memoryReflexPendingPath(short);
+        const raw = fs.readFileSync(file, 'utf-8');
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* already gone — fine */ }
+        const p = JSON.parse(raw);
+        if (!p || typeof p.projectId !== 'string' || typeof p.hitText !== 'string')
+            return null;
+        return { projectId: p.projectId, hitText: p.hitText };
+    }
+    catch {
+        return null; // no stash this turn (the common case)
+    }
+}
+/** Bump the memory-reflex EFFICACY numerator (the response drew on the injection) — best-effort. */
+function recordMemoryUsed(projectId) {
+    try {
+        const file = memoryReflexStatsPath(projectId);
+        let prior = null;
+        try {
+            prior = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch { /* none yet */ }
+        const next = (0, memory_reflex_1.tallyMemoryUsed)(prior);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch { /* counter is best-effort */ }
+}
+/** Self-report stash (P1b, adr/memory-reflex.md) — the topic the agent flagged via a
+ *  `[[recall: X]]` marker LAST turn, so the NEXT turn's notify pulls + injects it. Separate
+ *  from the efficacy-injection stash. Keyed by session; carries projectId. Written at Stop,
+ *  consumed-once at the next notify. */
+function selfReportPendingPath(short) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state', `memory-reflex-selfreport-${short}.json`);
+}
+function stashSelfReport(short, projectId, topic) {
+    try {
+        const file = selfReportPendingPath(short);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ projectId, topic }) + '\n');
+    }
+    catch { /* best-effort — a missed self-report just means no pull this round */ }
+}
+/** Read + DELETE the self-report stash (consume-once). Null on the common no-marker path. */
+function consumeSelfReport(short) {
+    try {
+        const file = selfReportPendingPath(short);
+        const raw = fs.readFileSync(file, 'utf-8');
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* already gone — fine */ }
+        const p = JSON.parse(raw);
+        if (!p || typeof p.projectId !== 'string' || typeof p.topic !== 'string' || !p.topic)
+            return null;
+        return { projectId: p.projectId, topic: p.topic };
+    }
+    catch {
+        return null;
+    }
+}
+/** Local cache of the SERVER's auto-quiet verdict for this project (the
+ *  mechanicKilled() analog for the memory-reflex). The Flash-Lite efficacy judge
+ *  decides the threshold server-side and ships the boolean on the /v1/memory/query
+ *  response; the hook caches it here and `memoryReflexQuieted` honors it with a
+ *  TTL (quietCacheSaysSilent). Beside the fire-counter under ~/.greprag/state. */
+function memoryReflexQuietPath(projectId) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state', `memory-reflex-quiet-${projectId}.json`);
+}
+/** Has the server's efficacy judge QUIETED this project's memory-reflex (low
+ *  used÷injected over a meaningful sample)? Reads the local cache; honors it only
+ *  while fresh (TTL) so a recovered reflex re-probes instead of staying silenced.
+ *  Fail-quiet: any error reads as NOT quieted (the reflex keeps working) —
+ *  mirrors mechanicKilled()'s fail-open posture. */
+function memoryReflexQuieted(projectId) {
+    try {
+        const raw = fs.readFileSync(memoryReflexQuietPath(projectId), 'utf-8');
+        return (0, memory_reflex_1.quietCacheSaysSilent)(JSON.parse(raw), Date.now());
+    }
+    catch {
+        return false;
+    }
+}
+/** Cache the server's auto-quiet verdict from a /v1/memory/query response — written
+ *  whenever the reflex actually probes (fired the search). Best-effort. */
+function cacheMemoryReflexQuiet(projectId, quiet) {
+    try {
+        const file = memoryReflexQuietPath(projectId);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const payload = { quiet, cachedAt: new Date().toISOString() };
+        fs.writeFileSync(file, JSON.stringify(payload) + '\n');
+    }
+    catch { /* best-effort — a missed cache just means the reflex re-probes next turn */ }
+}
+/** The reminder-interrupt registry CONTAINER call (docs/reminder-interrupt.md §Registry
+ *  spec) — invoked from the proven-registered `notify` hook (claude-code path). Assembles
+ *  the live env (the ONLY i/o: armed via isLocallyArmed, this session's own unread, the
+ *  Stop-stashed stress/turnCount, the front-desk envelope notice) and fires every module
+ *  whose detector reports deficient: watcher-arm (unarmed → nag if a peer messaged you, else
+ *  nudge; silent when armed), the stress-gated mechanic-friction, front-desk (a soft
+ *  "you've got mail" when a new envelope landed), and memory-reflex (auto-surfaced episodic
+ *  memory when THIS prompt signals recall — an inline, time-capped, confidence-gated search).
+ *  The announce-only modules (setup-warning / checkpoint / assistant-doctrine) stay silent per
+ *  turn — their env signals are SessionStart-only. Stacking; emitted once. Fail-open — any miss
+ *  → silent. The Mechanic kill switch drops ONLY the mechanic module; the rest keep working. */
+async function injectReminders(input, cfg, short) {
+    try {
+        const cwd = input.cwd || process.cwd();
+        const anchor = (0, project_anchor_1.readAnchor)(cwd);
+        const armed = (0, watcher_registry_1.isLocallyArmed)(short);
+        const sessionUnread = armed ? 0 : await fetchSessionUnread(cfg.apiUrl, cfg.apiKey, short);
+        const ownerPid = armed ? null : (0, watcher_registry_1.resolveClaudeOwnerPid)(short);
+        let assistant = false;
+        try {
+            assistant = (0, project_anchor_1.isAssistantProject)(anchor);
+        }
+        catch { /* fail-open */ }
+        // Stress/turnCount from the Stop-stashed state bag (no LLM/network here).
+        const state = anchor.projectId
+            ? ((0, guard_1.readMatchsetCache)(anchor.projectId)?.stateValues || {})
+            : {};
+        const turnCount = typeof state.turnCount === 'number' ? state.turnCount : 0;
+        const stress = typeof state.stress === 'number' ? state.stress : 0;
+        // Front-desk envelope notice — the per-turn half of the front-desk module's pair (the
+        // SessionStart count is the announce half). Body-free, self-dedups per machine, returns
+        // null when nothing new. This is the network call the retired `mail` hook used to make;
+        // it moves here so the whole announce/reminder surface rides ONE detector loop.
+        const frontDeskNotice = await (0, front_desk_mail_1.buildFrontDeskNotice)(cfg.apiUrl, cfg.apiKey);
+        // Memory-reflex (keyword layer) — recall intent in THIS prompt fires an inline,
+        // time-capped, project-scoped search; a hit above the confidence gate is surfaced
+        // inline (top 1-2, capped) so the agent sees it AS it forms its reply. A miss stays
+        // silent (the search result is its own precision filter — no banner-blindness). Every
+        // fire is tallied for the /mechanic excessiveness monitor. Gated on recall-intent, so
+        // most turns skip the search entirely. docs/reminder-interrupt.md (memory-reflex).
+        let memoryHit = null;
+        const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+        // Pick the memory query + trigger (the hybrid): a self-report marker the agent emitted LAST
+        // turn ([[recall: X]], stashed at Stop) takes precedence over recall-intent in THIS prompt —
+        // the agent explicitly flagged its own gap. One injection per turn.
+        let memQuery = null;
+        let memTrigger = 'keyword';
+        const selfReport = anchor.projectId ? consumeSelfReport(short) : null;
+        if (selfReport) {
+            memQuery = selfReport.topic;
+            memTrigger = 'selfReport';
+        }
+        else if ((0, memory_reflex_1.hasRecallIntent)(prompt)) {
+            memQuery = prompt.slice(0, 500);
+            memTrigger = 'keyword';
+        }
+        // Auto-quiet gate (adr/memory-reflex.md): if the server's Flash-Lite efficacy judge has
+        // QUIETED this project's reflex (low used÷injected over a meaningful sample), skip the search
+        // entirely — the cached verdict expires on a TTL so a recovered reflex re-probes. mechanicKilled() analog.
+        if (anchor.projectId && memQuery && !memoryReflexQuieted(anchor.projectId)) {
+            const { hits, quiet } = await fetchMemoryHits(cfg.apiUrl, cfg.apiKey, anchor.projectId, memQuery);
+            cacheMemoryReflexQuiet(anchor.projectId, quiet); // refresh the verdict from this probe
+            memoryHit = (0, memory_reflex_1.buildMemoryInjection)(hits);
+            recordMemoryFire(anchor.projectId, memTrigger, !!memoryHit, turnCount);
+            // Stash what was injected so the Stop hook can score whether the response used it
+            // (the efficacy numerator). Only when something was actually surfaced.
+            if (memoryHit)
+                stashMemoryInjection(short, anchor.projectId, (0, memory_reflex_1.gatedHitText)(hits), turnCount);
+        }
+        const env = {
+            short, turnCount, stress, armed, sessionUnread,
+            ownerPid, alias: (0, session_id_1.readIdentityAlias)(), assistant,
+            frontDeskNotice, memoryHit,
+        };
+        // Kill switch drops ONLY the mechanic module — watcher-arm keeps working.
+        const reg = mechanicKilled() ? reminder_registry_1.REGISTRY.filter(m => m.id !== 'mechanic-friction') : reminder_registry_1.REGISTRY;
+        const fired = (0, reminder_registry_1.collectReminders)(env, reg);
+        if (!fired.length)
+            return;
+        // Authoring rule #4 — frame nag/nudge with the act-now directive envelope; ambient
+        // stays a soft pointer. Emit ONCE (stacking via join) so multiple due modules ride a
+        // single additionalContext.
+        const parts = fired.map(f => f.tier === 'ambient' ? f.line : (0, guard_1.wrapDirective)(f.line));
+        writeAdditionalContext('UserPromptSubmit', parts.join('\n\n'));
+        // Fire-counter (adherence denominator) for the mechanic module — best-effort.
+        const mf = fired.find(f => f.id === 'mechanic-friction');
+        if (mf && anchor.projectId)
+            recordFrictionFire(anchor.projectId, mf.tier, turnCount);
+    }
+    catch { /* fail-open — a reminder miss never breaks the turn */ }
+}
+/** RETIRED 2026-06-20 — the per-turn reminder injection moved into the registry
+ *  container (`injectReminders`, called from `notify`), so watcher-arm + mechanic-friction
+ *  fire together under one detector loop with no double-injection. Kept as a no-op for
+ *  hook-registration stability (a fleet `friction-reminder` entry is harmless).
+ *  docs/reminder-interrupt.md §Registry spec */
+async function frictionReminder(_input) {
+    // intentionally empty — see injectReminders (runs from notify)
+}
+/** Front-desk turn hook — wire as a UserPromptSubmit hook.
  *
- *  Unconfigured / no API key → silent. Tenant-scoped by the API key, so a
- *  session only ever sees its own tenant's front desk.
+ *  NOTICE ROLE RETIRED 2026-06-20 — the envelope-only "you've got mail from X" notice
+ *  moved into the reminder-interrupt registry (front-desk module, fired per turn from
+ *  `injectReminders` → the same detector loop as watcher-arm + mechanic-friction), so the
+ *  whole announce/reminder surface has ONE assembly. docs/reminder-interrupt.md §Registry spec.
  *
- *  Auto-save (Chip E): when a project opts in (`email_autosave=true` in
- *  .greprag/project.json, or env GREPRAG_EMAIL_AUTOSAVE), the hook also drains
- *  new attachments to the configured dir each turn and appends a one-line saved
- *  summary. Default OFF — no opt-in, no pull. Best-effort: a drain failure never
- *  blocks the turn or suppresses the envelope notice. */
+ *  What REMAINS here is the attachment auto-save DRAIN — a deliberate side-effect (it WRITES
+ *  files to disk), kept OUT of the pure announce/reminder registry by design (the registry
+ *  modules are pure; all I/O + side-effects live in the hook). Auto-save (Chip E): when a
+ *  project opts in (`email_autosave=true` in .greprag/project.json, or env
+ *  GREPRAG_EMAIL_AUTOSAVE), drain new attachments to the configured dir each turn and emit a
+ *  one-line saved summary. Default OFF — no opt-in, no pull. Best-effort: a drain failure
+ *  never blocks the turn. Unconfigured / no API key → silent. */
 async function mail(input) {
     const cwd = input.cwd || process.cwd();
     const cfg = getConfig(cwd);
     if (!cfg.enabled || !cfg.apiKey)
         return; // unconfigured → silent
-    const parts = [];
-    const notice = await (0, front_desk_mail_1.buildFrontDeskNotice)(cfg.apiUrl, cfg.apiKey);
-    if (notice)
-        parts.push(notice);
     try {
         const auto = await maybeAutoSaveAttachments(cwd, cfg.apiUrl, cfg.apiKey);
         if (auto)
-            parts.push(auto);
+            writeAdditionalContext(input.hook_event_name || 'UserPromptSubmit', auto);
     }
     catch { /* drain is best-effort — never block a turn */ }
-    if (parts.length) {
-        writeAdditionalContext(input.hook_event_name || 'UserPromptSubmit', parts.join('\n\n'));
-    }
 }
 /** Per-turn attachment auto-save. Returns a one-line summary of freshly-saved
  *  files, or null when auto-save is off or nothing new landed. Gated on an
@@ -1565,7 +1911,7 @@ async function guardFlush(input) {
 async function main() {
     const subcommand = process.argv[2];
     const validSubs = new Set([
-        'store', 'recap', 'notify', 'mail', 'session-id', 'pre-spawn-check', 'armcheck',
+        'store', 'recap', 'notify', 'mail', 'friction-reminder', 'session-id', 'pre-spawn-check', 'armcheck',
         'collision-check', 'drain', 'coordinate-gate',
         'guard', 'guard-refresh', 'guard-flush',
         'context-probe', 'context-check', 'crush-wrap',
@@ -1574,7 +1920,7 @@ async function main() {
         'codex-permission-context', 'codex-subagent-start',
     ]);
     if (!validSubs.has(subcommand)) {
-        process.stderr.write(`Usage: greprag-hook <store|recap|notify|mail|session-id|pre-spawn-check|armcheck|collision-check|drain|coordinate-gate|guard|guard-refresh|guard-flush|context-probe|context-check|crush-wrap|pre-compact|archive-pointer|codex-store|codex-notify|codex-inbox|codex-recap|codex-permission-context|codex-subagent-start>\n`);
+        process.stderr.write(`Usage: greprag-hook <store|recap|notify|mail|friction-reminder|session-id|pre-spawn-check|armcheck|collision-check|drain|coordinate-gate|guard|guard-refresh|guard-flush|context-probe|context-check|crush-wrap|pre-compact|archive-pointer|codex-store|codex-notify|codex-inbox|codex-recap|codex-permission-context|codex-subagent-start>\n`);
         process.exit(1);
     }
     let input = {};
@@ -1602,6 +1948,12 @@ async function main() {
     else if (subcommand === 'mail') {
         await mail(input);
     }
+    else if (subcommand === 'friction-reminder') {
+        // UserPromptSubmit — the active Mechanic's dynamic friction reminder (beside
+        // the arm directive). Stress-driven tier: silent/ambient/nudge/nag. Reads the
+        // Stop-stashed state bag; additive + fail-open. docs/reminder-interrupt.md
+        await frictionReminder(input);
+    }
     else if (subcommand === 'codex-notify') {
         await notify(input, 'codex');
     }