fix(coding-agents): say when a turn is running without memory (#3455)

Addresses #3443.

When the once-per-session hook reflect fails, the turn proceeds with no memory
injection and the session looks exactly like a healthy one. The failure IS
recorded — log.warn to plugin.log and a reflect_failed diag line — but both are
files nobody is tailing mid-session. The reporter found their own two failures
only because they happened to open the diag log for an unrelated reason, and one
of them ate the prompt in which they were asking about this very limit.

diag.ts already states the goal in its header: "so a silently memory-less session
can't masquerade as one that worked". A file achieves that only in a post-mortem.

One terse line on the affected turn, naming the trail to open:

  Hindsight · no memory this turn — see /tmp/hindsight-plugin.log

Deliberately not an explanation and not advice to the agent — the details are in
the file it names, and it fires at most once per session, on the turn reflect
ran. Later turns don't re-run reflect, so re-announcing a failure they never
observed would just nag.

An EMPTY answer is NOT a failure: reflect can legitimately have nothing to say on
a sparse bank, which diag already records as its own reflect_empty event. Tying
the line to a flag set only in the catch keeps "no relevant memory exists"
distinct from "reflect broke" — collapsing them would report a breakage on
exactly the fresh, sparse banks where nothing is broken, and that confusion is
what the issue is about in the first place.

The notice reaches the user on claude-code (systemMessage) and as a toast on
opencode/kilo; harnesses whose hook schema has no user-visible channel ignore it,
as they already do for the existing reflect notice.

Not addressed here: reflect overrunning the 25s cap in the first place. The cap
stays (it must remain under the harness hook timeout), and the reporter's own
measurements point at reasoning tokens, which is provider-specific and already
reachable through HINDSIGHT_API_REFLECT_LLM_EXTRA_BODY server-side.

Author: nicoloboschi

hindsight-integrations/coding-agents/src/core/diag.ts

@@ -10,11 +10,16 @@
 import { appendFileSync } from "node:fs";
 import { log } from "./log";
 
+/** Where the JSONL trail lands. Exported so a failure notice can name the file to open. */
+export function diagFilePath(): string {
+  return process.env.HINDSIGHT_DIAG_FILE || "/tmp/hindsight-plugin.log";
+}
+
 export function diag(harness: string, event: string, extra: Record<string, unknown> = {}): void {
   log.debug(harness, `diag:${event}`, extra); // debug level shows the full story in ONE file
   try {
     appendFileSync(
-      process.env.HINDSIGHT_DIAG_FILE || "/tmp/hindsight-plugin.log",
+      diagFilePath(),
       JSON.stringify({ ts: new Date().toISOString(), harness, event, ...extra }) + "\n"
     );
   } catch {

hindsight-integrations/coding-agents/src/core/hook.test.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveConfig } from "./config";
 import { buildHookOutput, runHook } from "./hook";
+import { diagFilePath } from "./diag";
 import { buildReflectQuery } from "./inject";
 
 let root: string;
@@ -138,7 +139,9 @@ describe("buildHookOutput", () => {
     });
     // Reflect failed -> no reflect block; pages are never auto-injected -> nothing to inject.
     expect(t1.context).toBeUndefined();
-    expect(t1.notice).toBeUndefined();
+    // ...but the turn is NOT silent: one line pointing at the diag trail (#3443).
+    expect(t1.notice).toContain("no memory this turn");
+    expect(t1.notice).toContain(diagFilePath());
     expect(JSON.parse(readFileSync(cacheFile, "utf8")).reflectAnswer).toBe("");
 
     await buildHookOutput({
@@ -152,6 +155,34 @@ describe("buildHookOutput", () => {
     expect(client.reflect).toHaveBeenCalledTimes(1);
   });
 
+  it("the notice fires ONCE — the turn reflect failed, not on later turns", async () => {
+    const cfg = resolveConfig({});
+    const client = makeClient({
+      reflect: vi.fn(async () => {
+        throw new Error("reflect boom");
+      }),
+    });
+    const args = { harness: "claude-code", prompt: UNRELATED_PROMPT, cfg, client, cacheFile };
+    expect((await buildHookOutput(args)).notice).toContain("no memory this turn");
+    // Turn 2 does not re-run reflect, so re-announcing a failure it did not observe would nag.
+    expect((await buildHookOutput(args)).notice).toBeUndefined();
+  });
+
+  it("an EMPTY answer is not a failure: no notice (reflect simply had nothing to say)", async () => {
+    const cfg = resolveConfig({});
+    // The real client returns (data.text || "").trim() — a 200 with no text yields "".
+    const client = makeClient({ reflect: vi.fn(async () => "") });
+    const result = await buildHookOutput({
+      harness: "claude-code",
+      prompt: UNRELATED_PROMPT,
+      cfg,
+      client,
+      cacheFile,
+    });
+    expect(result.notice).toBeUndefined();
+    expect(result.context).toBeUndefined();
+  });
+
   it("uses a bounded low-budget reflect and caps its timeout at 25000ms", async () => {
     const cfg = resolveConfig({}); // reflectTimeoutMs default 120000
     const client = makeClient();

hindsight-integrations/coding-agents/src/core/hook.ts

@@ -21,7 +21,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { deriveBankId } from "./bank";
 import type { Config } from "./config";
 import { applyBankConfig, loadConfig } from "./config";
-import { diag } from "./diag";
+import { diag, diagFilePath } from "./diag";
 import { log, setLogLevel } from "./log";
 import { startBackgroundSeed } from "./seed";
 import type { ClientOpts } from "./hindsight";
@@ -102,6 +102,10 @@ export async function buildHookOutput(args: {
   // instructs the agent to call hindsight_reflect itself when a new goal is set.
   let reflectAnswer = cached.reflectAnswer;
   let reflectRanThisTurn = false;
+  // Set ONLY by the catch below. An empty answer is not a failure: reflect can legitimately have
+  // nothing to say on a sparse bank (diag records that as reflect_empty), and reporting it as a
+  // failure would tell the user the plugin broke on exactly the sessions where it did not.
+  let reflectFailed = false;
   const deferInitialReflect = cached.deferInitialReflect === true;
   if (deferInitialReflect) {
     // A new bank has no useful history yet. Do not burn the once-per-session synthesis on prompt
@@ -128,6 +132,7 @@ export async function buildHookOutput(args: {
       });
     } catch (e) {
       reflectAnswer = ""; // ran and failed — don't retry every turn; the diag trail records it
+      reflectFailed = true;
       log.warn(harness, "reflect failed — session runs without memory", {
         error: String((e as Error)?.message || e).slice(0, 200),
       });
@@ -193,6 +198,12 @@ export async function buildHookOutput(args: {
     notice =
       `${brandWord()} · goal: recall this repo's past decisions about “${excerpt}”\n` +
       `↳ ${preview.length > 140 ? `${preview.slice(0, 140)}…` : preview}`;
+  } else if (reflectFailed) {
+    // The failure is already in the diag trail and plugin.log, but both are files nobody is
+    // tailing mid-session, so a memory-less session looked exactly like a healthy one (#3443).
+    // One terse line pointing at the trail — not an explanation, and not advice to the agent:
+    // this fires at most once per session, on the turn reflect ran.
+    notice = `${brandWord()} · no memory this turn — see ${diagFilePath()}`;
   }
 
   return { context: kept.length ? kept.join("\n\n") : undefined, notice, pagesKnown: pages.length };