@bli-cockpit/memory-mcp 0.1.3 → 0.1.5

package/README.md

@@ -96,9 +96,26 @@ every machine:
 - **Print nothing, or one whole block.** No "no memories found" line — the model
   would reason about it, and an empty record and an unreachable store would look
   the same to it. Zero hits is data and prints nothing.
-- **One stderr receipt per run**, on every branch:
-  `[bli-memory hook] prompt {"status":"empty","reason":"no_hits","hits":0,"elapsed_ms":140}`.
-  Counts and reason labels only — never a prompt, a memory, a path or a token.
+- **One stderr receipt per run**, on every branch, one of three shapes
+  (BLI-3664, `hooks/log-line.ts`):
+  `[bli-memory] prompt ok {"hits":0,"elapsed_ms":140,"deadline_ms":3000}`,
+  `[bli-memory] prompt skipped {"reason":"no_prompt"}`, or
+  `[bli-memory] prompt failed {"reason":"dashboard_unreachable","elapsed_ms":2201,"deadline_ms":3000}`.
+  `reason` on `skipped`/`failed` is always one of a closed set — the four
+  network reasons `timeout`, `http_<status>`, `dashboard_unreachable`,
+  `bad_response` (Tower answered with a body that was not readable JSON);
+  the six `StdinFailure` reasons `no_stdin`, `stdin_empty`, `stdin_timeout`,
+  `stdin_too_large`, `stdin_unreadable`, `stdin_malformed` — each its own
+  literal, never folded into `bad_response`, because a malformed payload from
+  the host never touched the network (BLI-3700); `unpaired`, `no_prompt`,
+  plus three Stop-only local skips (`reentrant`, `no_transcript`,
+  `redaction_failed`) — never a stack trace, never Tower's own error text,
+  never a prompt, a memory, a path or a token. A reason `toLogReason` has not
+  been taught becomes `unknown_internal:<name>`, never a silent
+  `bad_response`. A `failed` outcome also gets a one-line `systemMessage` (the
+  same JSON-on-stdout shape the Supermemory plugin's own banner uses),
+  because Claude Code does not surface a hook's stderr anywhere a person
+  reads it.
 
 `hook stop` sends the last user/assistant exchange (at most 12 KB, tail-read so
 a 40 MB transcript costs nothing) through the collector's own redactor —

package/dist/door.d.ts

@@ -31,6 +31,13 @@ export interface DoorResponse {
     body: Record<string, unknown>;
     /** Set when the request never produced a JSON answer at all. */
     transportError: string | null;
+    /**
+     * The CLOSED classification of `transportError`, `null` when there was none.
+     * `doorReason` reads this — never the free-text message and never
+     * `body.error` — so a hook's stderr line can never carry provider-controlled
+     * or exception-message text (BLI-3664).
+     */
+    transportKind: "timeout" | "network" | "malformed" | null;
 }
 export interface DoorRequest {
     session: MemorySession;
@@ -42,5 +49,18 @@ export interface DoorRequest {
     timeoutMs?: number;
 }
 export declare function postMemoryDoor(request: DoorRequest): Promise<DoorResponse>;
-/** The reason label for a failed door call: the refusal's own, or `transport`. */
-export declare function doorReason(response: DoorResponse): string;
+/**
+ * The CLOSED reason label a hook's stderr line may print for a failed door
+ * call (BLI-3664). Deliberately never `response.body["error"]` or a raw
+ * exception message — both are provider/dashboard-controlled free text, and a
+ * hook's log line is metadata-only. Four members, closed:
+ *
+ *  - `timeout` — the request itself was aborted on our own budget.
+ *  - `dashboard_unreachable` — a transport failure that was NOT a timeout
+ *    (DNS, TLS, connection refused).
+ *  - `bad_response` — Tower answered with a status but a body that was not
+ *    readable JSON.
+ *  - `http_<status>` — Tower gave a normal HTTP answer that was not 2xx.
+ */
+export type DoorFailureReason = "timeout" | "dashboard_unreachable" | "bad_response" | `http_${number}`;
+export declare function doorReason(response: DoorResponse): DoorFailureReason;

package/dist/door.js

@@ -49,11 +49,13 @@ export async function postMemoryDoor(request) {
         });
     }
     catch (error) {
+        const timedOut = isTimeoutError(error);
         return {
             ok: false,
             status: 0,
             body: {},
-            transportError: describeTransportError(error, request.timeoutMs),
+            transportError: describeTransportError(error, request.timeoutMs, timedOut),
+            transportKind: timedOut ? "timeout" : "network",
         };
     }
     finally {
@@ -71,29 +73,41 @@ export async function postMemoryDoor(request) {
             status: response.status,
             body: {},
             transportError: `Tower answered ${response.status} with a body this server could not read as JSON.`,
+            transportKind: "malformed",
         };
     }
-    return { ok: response.ok, status: response.status, body: parsed, transportError: null };
+    return {
+        ok: response.ok,
+        status: response.status,
+        body: parsed,
+        transportError: null,
+        transportKind: null,
+    };
+}
+function isTimeoutError(error) {
+    const name = error?.name;
+    return name === "AbortError" || name === "TimeoutError";
 }
 /**
  * An abort reads as a timeout with its budget named, because "The operation was
- * aborted" tells an operator nothing about which limit they hit.
+ * aborted" tells an operator nothing about which limit they hit. This message
+ * is for a human reading `server.ts`'s MCP tool error text, never for a hook's
+ * stderr line — `doorReason` below never reads it.
  */
-function describeTransportError(error, timeoutMs) {
-    const name = error?.name;
-    if (name === "AbortError" || name === "TimeoutError") {
+function describeTransportError(error, timeoutMs, timedOut) {
+    if (timedOut) {
         return timeoutMs
             ? `Tower did not answer within ${timeoutMs} ms; the request was abandoned.`
             : "The request was aborted before Tower answered.";
     }
     return error instanceof Error ? (error.message.split("\n")[0] ?? "unknown") : String(error);
 }
-/** The reason label for a failed door call: the refusal's own, or `transport`. */
 export function doorReason(response) {
-    if (response.transportError)
-        return "transport_failed";
-    const label = response.body["error"];
-    if (typeof label === "string" && label.trim())
-        return label.trim();
+    if (response.transportKind === "timeout")
+        return "timeout";
+    if (response.transportKind === "network")
+        return "dashboard_unreachable";
+    if (response.transportKind === "malformed")
+        return "bad_response";
     return `http_${response.status}`;
 }

package/dist/hooks/contract.d.ts

@@ -93,6 +93,14 @@ export interface HookOutcome {
     chars?: number;
     /** How many secret-like spans were masked before a save. A count, never a value. */
     masked?: number;
+    /**
+     * BLI-3718: how many extracted facts collided with another live memory's
+     * custom_id rather than being written. Counted SEPARATELY from `saved` so a
+     * session where every candidate conflicted reads as `custom_id_conflict`,
+     * never as `nothing_worth_keeping` — the two used to be indistinguishable at
+     * HTTP 200.
+     */
+    conflicts?: number;
 }
 /** The container this hook's memories live in, and how it was derived. */
 export interface HookContainer {
@@ -110,11 +118,32 @@ export declare const RECALL_BLOCK: {
 };
 /** The vendor plugin's bullet, kept byte for byte so the injection reads the same. */
 export declare const BULLET = "\u25EA";
-/** The per-prompt recall shape the `/v4/profile` shim documents: top 5, ≥ 0.55. */
+/**
+ * The vendor's own per-prompt recall floor. Kept only as the FALLBACK for a
+ * door old enough not to send its own `semanticFloor` on the search response
+ * (BLI-3697 tick 8) — the live floor is read from that response, never
+ * hardcoded here, because three tickets already moved the door's real
+ * number (0.55 -> 0.30 -> 0.65) while this constant sat still.
+ */
 export declare const RECALL_MIN_SIMILARITY = 0.55;
 export declare const RECALL_LIMIT = 5;
 /** One recalled line, capped. The vendor truncated at 300 characters. */
 export declare const RECALL_LINE_CHARS = 300;
+/**
+ * One recalled memory, its text and when it was written (BLI-3697 tick 8).
+ * A fact that changes over time — a version number, a decision, a status —
+ * read back with no date is a trap: the QA loop found a `min_cli_version`
+ * row from 2026-08-18 answering "what is the CLI floor" at rank 1, true in
+ * August and wrong by the time it was read. `renderRecall` prefixes every
+ * line with its date rather than trying to decide which rows count as
+ * "stale" — that judgment belongs to whoever reads the recall, and they
+ * cannot make it at all if the date is missing.
+ */
+export interface RecalledHit {
+    text: string;
+    /** ISO timestamp, or `null` when the door did not send one. */
+    createdAt: string | null;
+}
 /** The search door refuses a query over 1000 characters; a long prompt is trimmed, not dropped. */
 export declare const MAX_QUERY_CHARS = 1000;
 /** At most the final 12 KB of the last exchange travels to `save`. */

package/dist/hooks/contract.js

@@ -57,7 +57,13 @@ export const RECALL_BLOCK = {
 };
 /** The vendor plugin's bullet, kept byte for byte so the injection reads the same. */
 export const BULLET = "◪";
-/** The per-prompt recall shape the `/v4/profile` shim documents: top 5, ≥ 0.55. */
+/**
+ * The vendor's own per-prompt recall floor. Kept only as the FALLBACK for a
+ * door old enough not to send its own `semanticFloor` on the search response
+ * (BLI-3697 tick 8) — the live floor is read from that response, never
+ * hardcoded here, because three tickets already moved the door's real
+ * number (0.55 -> 0.30 -> 0.65) while this constant sat still.
+ */
 export const RECALL_MIN_SIMILARITY = 0.55;
 export const RECALL_LIMIT = 5;
 /** One recalled line, capped. The vendor truncated at 300 characters. */

package/dist/hooks/log-line.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The one line every hook run prints to stderr, and the one sentence Claude
+ * Code shows a person on `failed` (BLI-3664).
+ *
+ * Before this file, `run.ts` printed `{status, reason, ...}` where `reason`
+ * was whatever the hook body happened to produce — including, for a door
+ * failure, `doorReason(response)`'s old behaviour of echoing
+ * `response.body["error"]` straight from Tower. Across 580 real transcripts
+ * that line was never actually read (`docs/reports/supermemory-reachability-
+ * 2026-09-05.md` §6): stderr from a Claude Code hook is not captured in the
+ * transcript at all, so a BLI Memory outage and a quiet turn with nothing to
+ * recall were indistinguishable to anyone who was not tailing this process's
+ * stderr live. The fix is two mechanisms, not one:
+ *
+ *  1. **stderr, on every branch, one line, one shape.** `buildLogLine` below.
+ *     This is what an operator tailing a launchd-style log — or a future
+ *     collector upload of hook logs — can grep.
+ *  2. **`systemMessage`, on `failed` only.** Claude Code does not surface a
+ *     hook's stderr as a visible line; the Supermemory plugin's own banner
+ *     (`~/.claude/plugins/.../recall-directive.js`) is a JSON object on
+ *     STDOUT carrying a `systemMessage` field (`hooks/stdin.js:writeOutput`,
+ *     `console.log(JSON.stringify(data))`). `buildSystemMessage` produces the
+ *     same shape so a real failure — not a quiet turn — is the one case a
+ *     person actually sees something.
+ *
+ * **The reason vocabulary is closed and lives HERE, in one module.** Four
+ * members answer the network half of the ticket's own question (can a
+ * timeout, a 5xx and a dead dashboard be told apart?): `timeout`,
+ * `http_<status>`, `dashboard_unreachable`, `bad_response` — the last of
+ * those meaning specifically "Tower answered with a status but a body that
+ * was not readable JSON" (`door.ts`'s `doorReason`). Six more are the
+ * **caller's own stdin**, one per `stdin.ts` `StdinFailure` member —
+ * `no_stdin`, `stdin_empty`, `stdin_timeout`, `stdin_too_large`,
+ * `stdin_unreadable`, `stdin_malformed` — kept as their OWN literals rather
+ * than folded into `bad_response`, because a malformed payload from the host
+ * never touched the network at all (BLI-3700, QA tick 6 NEW-9: a plain-text
+ * stdin payload printed `bad_response` and read as a Tower outage for four
+ * runs that never made a request). `unpaired` and `no_prompt` round those
+ * out, and three more cover skip states local to one hook that never touch
+ * the network either — `reentrant` (Stop, re-entrant), `no_transcript`
+ * (Stop, nothing to read yet) and `redaction_failed` (Stop, the masking pass
+ * itself failed). Every member is a compile-time literal from OUR OWN code;
+ * none of them is `response.body` text, an `error.message`, or a stack trace
+ * (`door.ts`'s `doorReason` already enforces that at the source for the
+ * network four). `toLogReason` maps every other internal reason string this
+ * package can produce onto one of these, and anything it does not recognise —
+ * a future reason nobody wired in here — becomes `unknown_internal:<name>`,
+ * never a silent `bad_response`: a reason this table has not been taught must
+ * say so, not point at the wrong system.
+ */
+import type { HookEvent, HookOutcome, HookStatus } from "./contract.js";
+import type { DoorFailureReason } from "../door.js";
+import type { StdinFailure } from "./stdin.js";
+export declare const HOOK_LOG_TAG = "[bli-memory]";
+/**
+ * The closed set: the door's four network members, the six `StdinFailure`
+ * members (BLI-3700 — never folded into a door reason), five more fixed
+ * local literals, and the `unknown_internal:<name>` escape hatch for a
+ * reason `toLogReason` has not been taught.
+ */
+export type HookLogReason = DoorFailureReason | StdinFailure | "unpaired" | "no_prompt" | "reentrant" | "no_transcript" | "redaction_failed" | `unknown_internal:${string}`;
+/** The word printed after the event name. `empty` (ran fine, nothing to say) prints as `ok`. */
+export type HookLogWord = "ok" | "skipped" | "failed";
+export declare function logWordFor(status: HookStatus): HookLogWord;
+/**
+ * Normalises any reason string this package can produce into the closed set.
+ * A door failure already arrives normalised (`door.ts`'s `doorReason`), so
+ * this is mostly a lookup table for the handful of purely local reasons —
+ * plus a safe, named default for anything this table has not been taught.
+ */
+export declare function toLogReason(reason: string): HookLogReason;
+/**
+ * The one stderr line for one hook run. Exact shape per status:
+ *
+ *   [bli-memory] <hook> ok      {hits?, saved?, chars?, masked?, elapsed_ms, deadline_ms}
+ *   [bli-memory] <hook> skipped {reason}
+ *   [bli-memory] <hook> failed  {reason, elapsed_ms, deadline_ms}
+ *
+ * Metadata only — counts and a closed reason label, never a memory's text,
+ * never a path, never the device token.
+ */
+export declare function buildLogLine(event: HookEvent, outcome: HookOutcome, elapsedMs: number, deadlineMs: number): string;
+/**
+ * One short sentence for a `failed` outcome only, in the JSON envelope the
+ * host actually renders (`{"systemMessage": "…"}` on stdout — see the
+ * Supermemory mechanism cited in this file's header). `null` on every other
+ * branch: `ok`/`empty` already say their piece through the injected block,
+ * and `skipped` is a deliberate no-op nobody needs interrupted for.
+ */
+export declare function buildSystemMessage(outcome: HookOutcome): string | null;
+/** Renders one JSON block to stdout — the only shape a hook may emit there
+ * besides plain injected context. Used by `run.ts` on `failed` only, so the
+ * "one block or nothing" stdout contract for every other branch is untouched. */
+export declare function renderSystemMessageBlock(message: string): string;

package/dist/hooks/log-line.js

@@ -0,0 +1,216 @@
+/**
+ * The one line every hook run prints to stderr, and the one sentence Claude
+ * Code shows a person on `failed` (BLI-3664).
+ *
+ * Before this file, `run.ts` printed `{status, reason, ...}` where `reason`
+ * was whatever the hook body happened to produce — including, for a door
+ * failure, `doorReason(response)`'s old behaviour of echoing
+ * `response.body["error"]` straight from Tower. Across 580 real transcripts
+ * that line was never actually read (`docs/reports/supermemory-reachability-
+ * 2026-09-05.md` §6): stderr from a Claude Code hook is not captured in the
+ * transcript at all, so a BLI Memory outage and a quiet turn with nothing to
+ * recall were indistinguishable to anyone who was not tailing this process's
+ * stderr live. The fix is two mechanisms, not one:
+ *
+ *  1. **stderr, on every branch, one line, one shape.** `buildLogLine` below.
+ *     This is what an operator tailing a launchd-style log — or a future
+ *     collector upload of hook logs — can grep.
+ *  2. **`systemMessage`, on `failed` only.** Claude Code does not surface a
+ *     hook's stderr as a visible line; the Supermemory plugin's own banner
+ *     (`~/.claude/plugins/.../recall-directive.js`) is a JSON object on
+ *     STDOUT carrying a `systemMessage` field (`hooks/stdin.js:writeOutput`,
+ *     `console.log(JSON.stringify(data))`). `buildSystemMessage` produces the
+ *     same shape so a real failure — not a quiet turn — is the one case a
+ *     person actually sees something.
+ *
+ * **The reason vocabulary is closed and lives HERE, in one module.** Four
+ * members answer the network half of the ticket's own question (can a
+ * timeout, a 5xx and a dead dashboard be told apart?): `timeout`,
+ * `http_<status>`, `dashboard_unreachable`, `bad_response` — the last of
+ * those meaning specifically "Tower answered with a status but a body that
+ * was not readable JSON" (`door.ts`'s `doorReason`). Six more are the
+ * **caller's own stdin**, one per `stdin.ts` `StdinFailure` member —
+ * `no_stdin`, `stdin_empty`, `stdin_timeout`, `stdin_too_large`,
+ * `stdin_unreadable`, `stdin_malformed` — kept as their OWN literals rather
+ * than folded into `bad_response`, because a malformed payload from the host
+ * never touched the network at all (BLI-3700, QA tick 6 NEW-9: a plain-text
+ * stdin payload printed `bad_response` and read as a Tower outage for four
+ * runs that never made a request). `unpaired` and `no_prompt` round those
+ * out, and three more cover skip states local to one hook that never touch
+ * the network either — `reentrant` (Stop, re-entrant), `no_transcript`
+ * (Stop, nothing to read yet) and `redaction_failed` (Stop, the masking pass
+ * itself failed). Every member is a compile-time literal from OUR OWN code;
+ * none of them is `response.body` text, an `error.message`, or a stack trace
+ * (`door.ts`'s `doorReason` already enforces that at the source for the
+ * network four). `toLogReason` maps every other internal reason string this
+ * package can produce onto one of these, and anything it does not recognise —
+ * a future reason nobody wired in here — becomes `unknown_internal:<name>`,
+ * never a silent `bad_response`: a reason this table has not been taught must
+ * say so, not point at the wrong system.
+ */
+export const HOOK_LOG_TAG = "[bli-memory]";
+export function logWordFor(status) {
+    if (status === "skipped")
+        return "skipped";
+    if (status === "failed")
+        return "failed";
+    return "ok"; // "ok" and "empty" both read as "ok" — empty is data, not a failure.
+}
+/**
+ * Normalises any reason string this package can produce into the closed set.
+ * A door failure already arrives normalised (`door.ts`'s `doorReason`), so
+ * this is mostly a lookup table for the handful of purely local reasons —
+ * plus a safe, named default for anything this table has not been taught.
+ */
+export function toLogReason(reason) {
+    switch (reason) {
+        // Already-closed door failures (door.ts), including any `http_<status>`.
+        case "timeout":
+        case "dashboard_unreachable":
+        case "bad_response":
+            return reason;
+        // Pairing / credential (session.ts's `SessionFailure`).
+        case "session_file_missing":
+        case "session_file_unreadable":
+        case "session_file_invalid":
+        case "session_missing_token":
+            return "unpaired";
+        // The host's own payload could not be used (stdin.ts's `StdinFailure`).
+        // Each keeps its own literal — never folded into `bad_response`, which
+        // names a Tower reply, not a caller-side stdin defect (BLI-3700).
+        case "no_stdin":
+        case "stdin_empty":
+        case "stdin_timeout":
+        case "stdin_too_large":
+        case "stdin_unreadable":
+        case "stdin_malformed":
+            return reason;
+        // The prompt hook's own empty-prompt skip.
+        case "no_prompt":
+            return "no_prompt";
+        // Stop-only local skips (stop.ts / transcript.ts / redact.ts).
+        case "reentrant":
+            return "reentrant";
+        case "no_transcript_path":
+        case "transcript_unreadable":
+        case "transcript_no_exchange":
+            return "no_transcript";
+        case "redaction_failed":
+            return "redaction_failed";
+        // The run-level deadline race (run.ts).
+        case "deadline_exceeded":
+            return "timeout";
+        default:
+            // A door's `http_<status>` template literal passes through as-is; an
+            // unexpected reason nobody wired into this table — `hook_threw:<Name>`
+            // or a future internal reason — becomes `unknown_internal:<name>`
+            // rather than a silent `bad_response`, which would misname a caller-side
+            // or run-level defect as a Tower reply (BLI-3700). Never the raw
+            // string is dropped, and never is it printed unbounded: the name is
+            // one of OUR OWN reason literals, never `response.body` text.
+            if (reason.startsWith("http_"))
+                return reason;
+            return `unknown_internal:${reason}`;
+    }
+}
+/**
+ * The one stderr line for one hook run. Exact shape per status:
+ *
+ *   [bli-memory] <hook> ok      {hits?, saved?, chars?, masked?, elapsed_ms, deadline_ms}
+ *   [bli-memory] <hook> skipped {reason}
+ *   [bli-memory] <hook> failed  {reason, elapsed_ms, deadline_ms}
+ *
+ * Metadata only — counts and a closed reason label, never a memory's text,
+ * never a path, never the device token.
+ */
+export function buildLogLine(event, outcome, elapsedMs, deadlineMs) {
+    const word = logWordFor(outcome.status);
+    const fields = word === "skipped"
+        ? { reason: toLogReason(outcome.reason) }
+        : word === "failed"
+            ? { reason: toLogReason(outcome.reason), elapsed_ms: elapsedMs, deadline_ms: deadlineMs }
+            : {
+                ...(outcome.hits === undefined ? {} : { hits: outcome.hits }),
+                ...(outcome.saved === undefined ? {} : { saved: outcome.saved }),
+                ...(outcome.chars === undefined ? {} : { chars: outcome.chars }),
+                ...(outcome.masked === undefined ? {} : { masked: outcome.masked }),
+                // BLI-3718: printed whenever set, including 0 — a save that wrote
+                // nothing AND conflicted with nothing is a materially different
+                // fact from one that conflicted on every candidate.
+                ...(outcome.conflicts === undefined ? {} : { conflicts: outcome.conflicts }),
+                elapsed_ms: elapsedMs,
+                deadline_ms: deadlineMs,
+            };
+    return `${HOOK_LOG_TAG} ${event} ${word} ${JSON.stringify(fields)}\n`;
+}
+/**
+ * One short sentence for a `failed` outcome only, in the JSON envelope the
+ * host actually renders (`{"systemMessage": "…"}` on stdout — see the
+ * Supermemory mechanism cited in this file's header). `null` on every other
+ * branch: `ok`/`empty` already say their piece through the injected block,
+ * and `skipped` is a deliberate no-op nobody needs interrupted for.
+ */
+export function buildSystemMessage(outcome) {
+    if (outcome.status !== "failed")
+        return null;
+    return `BLI Memory: ${failureSentence(toLogReason(outcome.reason))}`;
+}
+function failureSentence(reason) {
+    if (reason.startsWith("http_")) {
+        return `Tower refused the request (${reason.slice("http_".length)}).`;
+    }
+    if (reason.startsWith("unknown_internal:")) {
+        // A reason this table has not been taught. Named, never a crash, and
+        // never claims to know which system was at fault (BLI-3700).
+        return "something went wrong that this hook does not yet name.";
+    }
+    switch (reason) {
+        case "timeout":
+            return "Tower did not answer in time.";
+        case "dashboard_unreachable":
+            return "Tower is unreachable from this machine.";
+        case "bad_response":
+            return "Tower's response could not be understood.";
+        case "unpaired":
+            return "this machine is not paired with Tower — run `cockpit login`.";
+        case "redaction_failed":
+            return "the turn could not be safely redacted before saving.";
+        // The six `StdinFailure` members (BLI-3700). Skip-only today —
+        // `readHookPayload` always returns these as a `skipped` outcome, so
+        // `buildSystemMessage` never reaches them in practice — but each still
+        // gets its own sentence, named rather than asserted unreachable, so a
+        // future change that DID route one through `failed` gets the right
+        // words instead of the wrong system's name.
+        case "no_stdin":
+            return "no payload arrived on stdin (not run from a host that pipes one).";
+        case "stdin_empty":
+            return "the payload on stdin was empty.";
+        case "stdin_timeout":
+            return "stdin never closed within this hook's own deadline.";
+        case "stdin_too_large":
+            return "the payload on stdin exceeded the size ceiling.";
+        case "stdin_unreadable":
+            return "the payload on stdin could not be read.";
+        case "stdin_malformed":
+            return "the payload on stdin was not readable JSON.";
+        case "no_transcript":
+        case "reentrant":
+        case "no_prompt":
+            // Skip-only reasons; `buildSystemMessage` never reaches these because
+            // none of them is produced on a `failed` outcome. Named rather than
+            // asserted unreachable, so a future change that DID route one through
+            // `failed` still gets a sentence instead of a crash.
+            return "the recall did not run.";
+        default:
+            // Unreached: the `http_`/`unknown_internal:` families returned above
+            // and every other member is handled. A safe sentence, never a crash,
+            // if that ever changes.
+            return "something went wrong.";
+    }
+}
+/** Renders one JSON block to stdout — the only shape a hook may emit there
+ * besides plain injected context. Used by `run.ts` on `failed` only, so the
+ * "one block or nothing" stdout contract for every other branch is untouched. */
+export function renderSystemMessageBlock(message) {
+    return JSON.stringify({ systemMessage: message });
+}

package/dist/hooks/prompt.d.ts

@@ -6,8 +6,13 @@
  * installer's 5 s timeout, one search, print or print nothing.
  *
  * The recall shape is the vendor's, kept so the injection reads the same: the
- * prompt itself is the query, hits below 0.55 similarity are dropped, at most
- * five survive, each capped at 300 characters.
+ * prompt itself is the query, hits below the door's OWN floor are dropped
+ * (BLI-3697 tick 8: this hook used to keep a hardcoded 0.55 of its own,
+ * which drifted out of step when the door's floor moved across three
+ * tickets — the door's `semanticFloor` in the response is read instead now,
+ * `RECALL_MIN_SIMILARITY` surviving only as the fallback for an older
+ * deployment that does not send the field yet), at most five survive, each
+ * capped at 300 characters.
  *
  * **Zero hits is data.** It prints nothing and exits 0 with `no_hits`. A search
  * that could NOT run is a different line with a different reason, because an

package/dist/hooks/prompt.js

@@ -6,8 +6,13 @@
  * installer's 5 s timeout, one search, print or print nothing.
  *
  * The recall shape is the vendor's, kept so the injection reads the same: the
- * prompt itself is the query, hits below 0.55 similarity are dropped, at most
- * five survive, each capped at 300 characters.
+ * prompt itself is the query, hits below the door's OWN floor are dropped
+ * (BLI-3697 tick 8: this hook used to keep a hardcoded 0.55 of its own,
+ * which drifted out of step when the door's floor moved across three
+ * tickets — the door's `semanticFloor` in the response is read instead now,
+ * `RECALL_MIN_SIMILARITY` surviving only as the fallback for an older
+ * deployment that does not send the field yet), at most five survive, each
+ * capped at 300 characters.
  *
  * **Zero hits is data.** It prints nothing and exits 0 with `no_hits`. A search
  * that could NOT run is a different line with a different reason, because an
@@ -45,7 +50,8 @@ export async function runPromptHook(context) {
     if (!response.ok) {
         return { status: "failed", reason: doorReason(response), stdout: "", hits: 0 };
     }
-    const memories = readHits(response.body["results"]);
+    const floor = doorFloor(response.body["semanticFloor"]);
+    const memories = readHits(response.body["results"], floor);
     const degraded = typeof response.body["degraded"] === "string" && response.body["degraded"]
         ? String(response.body["degraded"])
         : null;
@@ -70,20 +76,35 @@ export async function runPromptHook(context) {
     };
 }
 /**
- * The vendor's floor, applied to the vendor's channel only.
+ * The door's own floor for THIS search, or the vendor's fallback.
+ *
+ * BLI-3697 tick 8: this hook used to re-check every row against its own
+ * hardcoded `RECALL_MIN_SIMILARITY` (0.55) regardless of what floor the
+ * door had actually searched with — three tickets moved that number (0.55 ->
+ * 0.30 -> 0.65) and this hook never noticed, silently applying a SECOND,
+ * stale threshold on top of the door's real one. `semanticFloor` on the
+ * response is the number the search actually ran with; only a door old
+ * enough not to send it falls back to the vendor's constant.
+ */
+function doorFloor(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : RECALL_MIN_SIMILARITY;
+}
+/**
+ * The floor governs the SEMANTIC channel only.
  *
  * `similarity` on our door is **cosine similarity, zero when a row came only
  * from the lexical or recency channel** (`agent-memories/search.ts:74`). The
- * vendor filtered at 0.55 against a store where every hit was semantic; doing
- * that here would drop every keyword match, and on a deployment with no
- * embedding credential it would drop EVERY hit — a recall that silently returns
+ * vendor filtered against a store where every hit was semantic; doing that
+ * here would drop every keyword match, and on a deployment with no embedding
+ * credential it would drop EVERY hit — a recall that silently returns
  * nothing forever while the door reports `degraded` and nobody reads it.
  *
- * So the floor governs SEMANTIC hits and nothing else: a row the semantic
- * channel scored has to clear 0.55, and a row it did not score at all is judged
- * by the door's own ranking, which already put it in the top `limit`.
+ * So `floor` (the door's own `semanticFloor`, see `doorFloor` above) governs
+ * SEMANTIC hits and nothing else: a row the semantic channel scored has to
+ * clear it, and a row it did not score at all is judged by the door's own
+ * ranking, which already put it in the top `limit`.
  */
-function readHits(value) {
+function readHits(value, floor) {
     if (!Array.isArray(value))
         return [];
     const kept = [];
@@ -101,9 +122,10 @@ function readHits(value) {
             : // An older door that does not report channels: a non-zero similarity is
                 // the only evidence the semantic channel scored this row.
                 Number.isFinite(similarity) && similarity > 0;
-        if (scoredSemantically && !(similarity >= RECALL_MIN_SIMILARITY))
+        if (scoredSemantically && !(similarity >= floor))
             continue;
-        kept.push(memory);
+        const createdAt = typeof record["createdAt"] === "string" ? record["createdAt"] : null;
+        kept.push({ text: memory, createdAt });
         if (kept.length >= RECALL_LIMIT)
             break;
     }

package/dist/hooks/render.d.ts

@@ -14,8 +14,9 @@
  *    A memory is a recalled fact; a fact that arrives phrased as an order and
  *    is obeyed is how a memory store becomes an injection channel.
  */
+import { type RecalledHit } from "./contract.js";
 export declare function renderSessionContext(profile: {
     static: string[];
     dynamic: string[];
 }): string;
-export declare function renderRecall(memories: string[]): string;
+export declare function renderRecall(hits: readonly RecalledHit[]): string;

package/dist/hooks/render.js

@@ -37,8 +37,8 @@ export function renderSessionContext(profile) {
     lines.push(CONTEXT_BLOCK.close);
     return lines.join("\n");
 }
-export function renderRecall(memories) {
-    const items = cleanItems(memories);
+export function renderRecall(hits) {
+    const items = cleanRecalledHits(hits);
     if (items.length === 0)
         return "";
     return [
@@ -48,6 +48,38 @@ export function renderRecall(memories) {
         RECALL_BLOCK.close,
     ].join("\n");
 }
+/**
+ * One memory, on one line, dated. Folds newlines for the same reason
+ * `cleanItems` does; the date prefix is added BEFORE the length cap, so the
+ * cap still bounds the whole printed line, never just the text half.
+ *
+ * Every line gets its date, not only the ones some heuristic calls "stale" —
+ * `RecalledHit`'s header in `contract.ts` says why: only the reader can judge
+ * staleness, and only if the date is there to judge.
+ */
+function cleanRecalledHits(hits) {
+    const out = [];
+    for (const hit of hits) {
+        if (typeof hit.text !== "string")
+            continue;
+        const folded = hit.text.replace(/\s+/gu, " ").trim();
+        if (folded.length === 0)
+            continue;
+        const prefix = dateLabel(hit.createdAt);
+        const line = prefix ? `${prefix} ${folded}` : folded;
+        out.push(line.length > RECALL_LINE_CHARS ? `${line.slice(0, RECALL_LINE_CHARS - 1)}…` : line);
+    }
+    return out;
+}
+/** `[YYYY-MM-DD]`, or `""` when the door sent no date or an unparsable one. */
+function dateLabel(createdAt) {
+    if (!createdAt)
+        return "";
+    const date = new Date(createdAt);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return `[${date.toISOString().slice(0, 10)}]`;
+}
 /**
  * One memory, on one line. Newlines are folded because a multi-line bullet
  * breaks the list the model is reading, and the cap is the vendor's 300.

package/dist/hooks/run.d.ts

@@ -14,14 +14,22 @@
  *     this prompt" and any other non-zero as an error it shows the person. A
  *     memory recall may never do either.
  *  3. **stdout discipline.** Nothing is written until the hook has finished and
- *     produced a whole block. A partial injection is worse than none.
- *  4. **One stderr receipt per run, on every branch.** `[bli-memory hook]
- *     <event> {status, hits|saved, elapsed_ms, reason}` — metadata only, never a
- *     prompt, a memory, a path or a token. A hook that only logged failures
- *     could not answer "did recall work at all today?", which is the question
- *     an operator actually asks.
+ *     produced a whole block. A partial injection is worse than none — with
+ *     ONE exception, added in BLI-3664: a `failed` outcome also gets a single
+ *     `{"systemMessage": "…"}` JSON block, because that is the one shape
+ *     Claude Code actually renders to a person (see `log-line.ts`'s header).
+ *     Every other status's stdout is exactly as before.
+ *  4. **One stderr receipt per run, on every branch.** `[bli-memory] <event>
+ *     ok|skipped|failed {…}` (`log-line.ts:buildLogLine`) — metadata only,
+ *     never a prompt, a memory, a path or a token, and a `reason` drawn from a
+ *     closed set. A hook that only logged failures could not answer "did
+ *     recall work at all today?", which is the question an operator actually
+ *     asks — and across 580 real transcripts this line was the ONLY place
+ *     that question could ever have been answered, because Claude Code does
+ *     not surface a hook's stderr anywhere a person or a transcript reads
+ *     (`docs/reports/supermemory-reachability-2026-09-05.md` §6, BLI-3664).
  *
- * Why an unpaired machine is `skipped no_session` and not an error: an intern
+ * Why an unpaired machine is `skipped unpaired` and not an error: an intern
  * who has not run `cockpit login` yet has three registered hooks and no
  * credential, and that state must be quiet in the transcript and loud in the
  * log. Same for a machine whose token was revoked — the door answers 401, the
@@ -30,7 +38,7 @@
 import type { FetchImpl } from "../door.js";
 import { type HookEvent, type HookOutcome, type HookPayload } from "./contract.js";
 import type { StopHookOptions } from "./stop.js";
-export declare const HOOK_LOG_TAG = "[bli-memory hook]";
+export { HOOK_LOG_TAG } from "./log-line.js";
 export interface RunHookDeps {
     env?: NodeJS.ProcessEnv;
     cwd?: string;

package/dist/hooks/run.js

@@ -14,14 +14,22 @@
  *     this prompt" and any other non-zero as an error it shows the person. A
  *     memory recall may never do either.
  *  3. **stdout discipline.** Nothing is written until the hook has finished and
- *     produced a whole block. A partial injection is worse than none.
- *  4. **One stderr receipt per run, on every branch.** `[bli-memory hook]
- *     <event> {status, hits|saved, elapsed_ms, reason}` — metadata only, never a
- *     prompt, a memory, a path or a token. A hook that only logged failures
- *     could not answer "did recall work at all today?", which is the question
- *     an operator actually asks.
+ *     produced a whole block. A partial injection is worse than none — with
+ *     ONE exception, added in BLI-3664: a `failed` outcome also gets a single
+ *     `{"systemMessage": "…"}` JSON block, because that is the one shape
+ *     Claude Code actually renders to a person (see `log-line.ts`'s header).
+ *     Every other status's stdout is exactly as before.
+ *  4. **One stderr receipt per run, on every branch.** `[bli-memory] <event>
+ *     ok|skipped|failed {…}` (`log-line.ts:buildLogLine`) — metadata only,
+ *     never a prompt, a memory, a path or a token, and a `reason` drawn from a
+ *     closed set. A hook that only logged failures could not answer "did
+ *     recall work at all today?", which is the question an operator actually
+ *     asks — and across 580 real transcripts this line was the ONLY place
+ *     that question could ever have been answered, because Claude Code does
+ *     not surface a hook's stderr anywhere a person or a transcript reads
+ *     (`docs/reports/supermemory-reachability-2026-09-05.md` §6, BLI-3664).
  *
- * Why an unpaired machine is `skipped no_session` and not an error: an intern
+ * Why an unpaired machine is `skipped unpaired` and not an error: an intern
  * who has not run `cockpit login` yet has three registered hooks and no
  * credential, and that state must be quiet in the transcript and loud in the
  * log. Same for a machine whose token was revoked — the door answers 401, the
@@ -31,8 +39,9 @@ import path from "node:path";
 import { resolveContainerTag } from "../container-tag.js";
 import { loadMemorySession } from "../session.js";
 import { HOOK_BUDGETS, } from "./contract.js";
+import { buildLogLine, buildSystemMessage, renderSystemMessageBlock } from "./log-line.js";
 import { readHookPayload } from "./stdin.js";
-export const HOOK_LOG_TAG = "[bli-memory hook]";
+export { HOOK_LOG_TAG } from "./log-line.js";
 /**
  * Runs one hook and returns its outcome. The caller (`index.ts`) exits 0
  * regardless — the return value is for tests and for the receipt.
@@ -44,19 +53,22 @@ export async function runHook(event, deps = {}) {
     const stdout = deps.stdout ?? process.stdout;
     const stderr = deps.stderr ?? process.stderr;
     const outcome = await raceDeadline(() => resolveOutcome(event, deps), budget.totalMs);
+    const elapsedMs = now() - started;
     // stdout is written once, here, and only for a complete block.
     if (outcome.stdout.length > 0) {
         stdout.write(`${outcome.stdout}\n`);
     }
-    stderr.write(`${HOOK_LOG_TAG} ${event} ${JSON.stringify({
-        status: outcome.status,
-        reason: outcome.reason,
-        ...(outcome.hits === undefined ? {} : { hits: outcome.hits }),
-        ...(outcome.saved === undefined ? {} : { saved: outcome.saved }),
-        ...(outcome.chars === undefined ? {} : { chars: outcome.chars }),
-        ...(outcome.masked === undefined ? {} : { masked: outcome.masked }),
-        elapsed_ms: now() - started,
-    })}\n`);
+    else {
+        // The one exception to "one block or nothing": a `failed` outcome still
+        // prints nothing to the model (no additionalContext), but DOES get a
+        // `systemMessage` block, which is a status banner, not a memory. Every
+        // other status's stdout is unchanged from before BLI-3664.
+        const systemMessage = buildSystemMessage(outcome);
+        if (systemMessage) {
+            stdout.write(`${renderSystemMessageBlock(systemMessage)}\n`);
+        }
+    }
+    stderr.write(buildLogLine(event, outcome, elapsedMs, budget.totalMs));
     return outcome;
 }
 async function resolveOutcome(event, deps) {

package/dist/hooks/stop.js

@@ -75,19 +75,40 @@ export async function runStopHook(context, options = {}) {
     if (!response.ok) {
         return { status: "failed", reason: doorReason(response), stdout: "", saved: 0 };
     }
-    const decisions = response.body["decisions"];
-    const written = Array.isArray(decisions)
-        ? decisions.filter((decision) => decision &&
-            typeof decision === "object" &&
-            decision["verb"] !== "skip").length
+    const decisionsRaw = response.body["decisions"];
+    const decisions = Array.isArray(decisionsRaw)
+        ? decisionsRaw.filter((decision) => Boolean(decision) && typeof decision === "object")
+        : null;
+    const written = decisions
+        ? decisions.filter((decision) => decision["verb"] !== "skip").length
         : response.body["id"]
             ? 1
             : 0;
+    // BLI-3718: a candidate that collided with another live memory's custom_id
+    // is counted SEPARATELY from `written` — it is neither a save nor "nothing
+    // worth keeping", and folding it into the latter is exactly how a session's
+    // second-and-later Stop hooks reported `{"skipped":N}` at HTTP 200 while a
+    // fact silently never landed.
+    const conflicted = decisions
+        ? decisions.filter((decision) => decision["reason"] === "custom_id_conflict").length
+        : 0;
+    if (written > 0) {
+        return {
+            status: "ok",
+            reason: String(response.body["outcome"] ?? "saved"),
+            stdout: "",
+            saved: written,
+            conflicts: conflicted,
+            chars: masked.text.length,
+            masked: masked.masked,
+        };
+    }
     return {
-        status: written > 0 ? "ok" : "empty",
-        reason: written > 0 ? String(response.body["outcome"] ?? "saved") : "nothing_worth_keeping",
+        status: "empty",
+        reason: conflicted > 0 ? "custom_id_conflict" : "nothing_worth_keeping",
         stdout: "",
-        saved: written,
+        saved: 0,
+        conflicts: conflicted,
         chars: masked.text.length,
         masked: masked.masked,
     };

package/dist/server.d.ts

@@ -36,7 +36,7 @@ import { z } from "zod";
 import { type FetchImpl } from "./door.js";
 import type { MemorySession } from "./session.js";
 export declare const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
-export declare const PACKAGE_VERSION = "0.1.1";
+export declare const PACKAGE_VERSION = "0.1.5";
 /**
  * The server id an MCP client registers. Defined in `print-config.ts` and
  * re-exported here: `index.ts` needs the name on the hook and print-config

package/dist/server.js

@@ -37,7 +37,10 @@ import { resolveContainerTag } from "./container-tag.js";
 import { postMemoryDoor } from "./door.js";
 import { SERVER_NAME } from "./print-config.js";
 export const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
-export const PACKAGE_VERSION = "0.1.1";
+// BLI-3713: this constant had drifted from package.json's real version
+// (0.1.1 vs 0.1.4) — nobody had bumped it alongside a version bump before.
+// Kept in lockstep with package.json's "version" field going forward.
+export const PACKAGE_VERSION = "0.1.5";
 /**
  * The server id an MCP client registers. Defined in `print-config.ts` and
  * re-exported here: `index.ts` needs the name on the hook and print-config
@@ -241,7 +244,14 @@ export function createServer(deps) {
         const embedNote = response.body.embedded === false && response.body.embedSkippedReason
             ? ` It was stored without a search vector (${String(response.body.embedSkippedReason)}), so it is findable by keyword and not yet by meaning.`
             : "";
-        return textResult(`Memory ${outcome} in ${landedIn} (id: ${id}).${embedNote}`, response.body);
+        // BLI-3713: `mode: "extract"` can fall back to a verbatim save when
+        // distillation fails (a bad model answer must never mean the content is
+        // dropped) — say so plainly rather than let the caller believe atomic
+        // facts were written when the whole note was stored as one row instead.
+        const extractNote = response.body.extract === "fell_back_verbatim"
+            ? ` Saved as written; extraction failed (${String(response.body.extractFailureReason ?? "unknown")}).`
+            : "";
+        return textResult(`Memory ${outcome} in ${landedIn} (id: ${id}).${embedNote}${extractNote}`, response.body);
     });
     server.registerTool("update_memory", {
         title: "Correct a memory",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/memory-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "BLI Memory — an MCP server for the memory layer BLI owns (save, search, update, forget).",
   "type": "module",