fix(coding-agents): keep a long-lived host's credential live, and say which one it used (#3600) (#3606)

* fix(coding-agents): keep a long-lived host's credential live, and say which one it used (#3600)

`HindsightClient` copied `apiToken` at construction and never re-read it, so a
host that outlives its credential — dsh, Cline, Kilo, Prime Agent, opencode,
the MCP server — kept signing with a key the operator had already replaced.
Enabling auth or rotating the key mid-session 401'd every call until the whole
host restarted, while `hindsight_diagnose` re-read the file and reported the
situation as healthy. The one-shot hook binaries were immune, which is why the
same machine showed working hooks alongside dead in-session tools.

The credential is now resolved through a provider on a 401 and the request
replayed once, but only if the re-resolved token actually CHANGED — a genuinely
wrong key still surfaces as one 401 rather than doubling every failing request.
The happy path never touches the filesystem.

All three fetch paths go through one signing helper. `reflect` and the drain
poll fetched directly, so a recovery wired into `req()` alone would have left
them failing forever.

Both #3600 and the two drifts below come from the same shape: five hosts each
carried their own copy of loadConfig -> deriveBankId -> applyBankConfig ->
new HindsightClient. So the fix is one shared builder (core/host-client.ts)
rather than a sixth line pasted into each. Hoisting it fixes two settings that
had already gone missing that way:

- dsh and Prime Agent never passed `maxParallelRetains`, so both silently
  ignored it and always used the default 10.
- dsh never passed the directory to `applyBankConfig`, so `optInOnly` was not
  enforced there at all: an unapproved repo still got a bank.

`hindsight_diagnose` now reports the credential IN USE next to the one on disk
(booleans only, never the value), resolved through the same pipeline the host
used — including a per-bank `banks.<id>.apiToken`, which a bare loadConfig()
comparison would have reported as a permanent false mismatch. Without this the
drift stays invisible to the one tool whose purpose is to explain it.

A 401 also now says whether a credential was even sent. The server answers
identically for "no key" and "wrong key"; only the client knows which it was.

Behaviour change worth naming: `disabled: true` now wins uniformly. It already
did for every host except the MCP server, which applied the `banks.<id>`
section first and so could be re-enabled per bank; `optInOnly`/`optInPaths` is
the supported way to run memory in only some projects. Resolution also stops
before bank derivation when disabled, since that shells out to git and the
disabled path exists to be a zero-overhead baseline.

Reported with a verified local patch and a full root-cause analysis by
@allenliang2022 in #3600; this implements that approach.

* docs(coding-agents): say when a config change takes effect, and that the token is the exception

Nothing in the README or the skill said when an edit to
~/.hindsight/coding-agent.json actually applies — and the answer differs per
host: a hook harness re-reads the file on every invocation and picks a change
up on the next prompt, a persistent plugin holds it for the life of the agent
process, and the MCP server for the session.

That gap got worse, not better, with the credential fix: the apiToken row now
says it is picked up without a restart, which reads as "config is live" unless
the rule it is an exception to is written down somewhere.

Author: nicoloboschi

hindsight-docs/docs-integrations/coding-agents.md

@@ -302,6 +302,26 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
 per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
 as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
 
+### When a change takes effect
+
+Config is read when a process starts — the file is not watched — so when an edit applies depends on
+what reads it:
+
+| host                                                                                                        | reads the file                                                      | an edit applies            |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
+| hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) | once per hook invocation — each hook is its own short-lived process | on your next prompt        |
+| persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness)                           | once per workspace, when the host loads the plugin                  | after restarting the agent |
+| the MCP server behind the `hindsight_*` tools                                                               | once at startup                                                     | in your next session       |
+
+`apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
+authentication or rotating the key is picked up on the next call with nothing to restart —
+otherwise a rotation would leave a long-running agent failing every memory call until it was
+restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
+the survey and knowledge-page settings.
+
+`hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
+client is actually using.
+
 ### Opt-in only
 
 By default every project gets memory — that is what makes the plugin zero-setup. If you would
@@ -349,7 +369,7 @@ hook by Codex...), so one shared config serves several agents side by side:
 | field                   | default                              | meaning                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `apiUrl`                | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server)                                                                                                                                                                                                                                                                                                                                                                        |
-| `apiToken`              | —                                    | bearer token (Hindsight Cloud)                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `apiToken`              | —                                    | bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call                                                                                                                                                                                                                                        |
 | `bankId`                | —                                    | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below)                                                                                                                                                                                                                                                                                                                                                                             |
 | `dynamicBankId`         | dynamic iff no `bankId`              | force dynamic (`true`) or static (`false`) resolution                                                                                                                                                                                                                                                                                                                                                                                             |
 | `bankIdTemplate`        | `"coding-agent::{gitProject}"`       | dynamic bank id format; the default makes every agent share one bank per repo                                                                                                                                                                                                                                                                                                                                                                     |

hindsight-integrations/coding-agents/README.md

@@ -295,6 +295,26 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
 per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
 as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
 
+### When a change takes effect
+
+Config is read when a process starts — the file is not watched — so when an edit applies depends on
+what reads it:
+
+| host                                                                                                        | reads the file                                                      | an edit applies            |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
+| hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) | once per hook invocation — each hook is its own short-lived process | on your next prompt        |
+| persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness)                           | once per workspace, when the host loads the plugin                  | after restarting the agent |
+| the MCP server behind the `hindsight_*` tools                                                               | once at startup                                                     | in your next session       |
+
+`apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
+authentication or rotating the key is picked up on the next call with nothing to restart —
+otherwise a rotation would leave a long-running agent failing every memory call until it was
+restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
+the survey and knowledge-page settings.
+
+`hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
+client is actually using.
+
 ### Opt-in only
 
 By default every project gets memory — that is what makes the plugin zero-setup. If you would
@@ -342,7 +362,7 @@ hook by Codex...), so one shared config serves several agents side by side:
 | field                   | default                              | meaning                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `apiUrl`                | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server)                                                                                                                                                                                                                                                                                                                                                                        |
-| `apiToken`              | —                                    | bearer token (Hindsight Cloud)                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `apiToken`              | —                                    | bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call                                                                                                                                                                                                                                        |
 | `bankId`                | —                                    | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below)                                                                                                                                                                                                                                                                                                                                                                             |
 | `dynamicBankId`         | dynamic iff no `bankId`              | force dynamic (`true`) or static (`false`) resolution                                                                                                                                                                                                                                                                                                                                                                                             |
 | `bankIdTemplate`        | `"coding-agent::{gitProject}"`       | dynamic bank id format; the default makes every agent share one bank per repo                                                                                                                                                                                                                                                                                                                                                                     |

hindsight-integrations/coding-agents/skill/SKILL.md

@@ -88,6 +88,12 @@ created with), `autoSeed`/`seedLimit` (true/300),
 `codebaseSurvey`/`surveyModel`/`surveyBudgetUsd` (true/haiku/2), `surveyRefreshCommits` (0=off),
 `logLevel` ("info").
 
+Config is read at process start, not watched: a hook harness picks an edit up on the next prompt, a
+persistent plugin (opencode, Kilo, Cline, Prime Agent, dsh) only after the agent restarts, and the
+MCP server in the next session. `apiToken` is the exception — re-read whenever the server rejects a
+request, so rotating it needs no restart. `hindsight_diagnose` reports the file's token and the
+running client's separately, which is how you tell a stale credential from a wrong one.
+
 Blacklist a whole directory tree: map it to one bank and disable that bank —
 `"mapPathToBank": {"~/scratch": "scratch"}` + `"banks": {"scratch": {"disabled": true}}`.
 

hindsight-integrations/coding-agents/src/cline.ts

@@ -6,9 +6,7 @@
  * `beforeModel` hook can, so it is the only path that can provide the same reflect/page injection
  * guarantee as every other Hindsight harness. The memory behaviour itself stays in RuntimeCore.
  */
-import { applyBankConfig, loadConfig } from "./core/config";
-import { deriveBankId } from "./core/bank";
-import { HindsightClient } from "./core/hindsight";
+import { resolveHostMemory } from "./core/host-client";
 import { RuntimeCore } from "./core/runtime";
 import type { TransportTurn } from "./core/chat";
 import { diag } from "./core/diag";
@@ -187,23 +185,10 @@ export function createClineHooks(
 }
 
 function createRuntime(workspaceRoot: string | undefined): RuntimeCore | undefined {
-  let cfg = loadConfig({ harness: HARNESS });
-  if (cfg.disabled) return undefined;
-  const resolved = applyBankConfig(
-    cfg,
-    deriveBankId(cfg, workspaceRoot || process.cwd(), HARNESS),
-    workspaceRoot || process.cwd()
-  );
-  cfg = resolved.cfg;
-  if (cfg.disabled) return undefined;
-  const client = new HindsightClient({
-    apiUrl: cfg.apiUrl,
-    apiToken: cfg.apiToken,
-    bank: resolved.bankId,
-    maxParallelRetains: cfg.maxParallelRetains,
-    observationScopes: cfg.observationScopes,
-  });
-  return new RuntimeCore(client, resolved.bankId, cfg, HARNESS, workspaceRoot || process.cwd());
+  const dir = workspaceRoot || process.cwd();
+  const { cfg, bankId, client } = resolveHostMemory(HARNESS, dir);
+  if (cfg.disabled) return undefined; // global switch, per-bank opt-out or optInOnly
+  return new RuntimeCore(client, bankId, cfg, HARNESS, dir);
 }
 
 const plugin: ClinePlugin = {

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

@@ -129,8 +129,16 @@ describe("every harness entrypoint reaches a daemon", () => {
     "mcp-server.ts": "child of a hook harness whose SessionStart ensured the daemon first",
     "core/hook.ts":
       "the prompt path, deliberately: a cold start outlives the hook budget and stalls the turn",
+    "core/host-client.ts":
+      "the shared builder itself, not an entrypoint — its CALLERS are the request origins this checks",
   };
 
+  /** A module is a request origin if it constructs a client directly OR asks the shared builder
+   *  (core/host-client.ts) for one — the long-lived hosts do the latter, and reading only for
+   *  `new HindsightClient(` would silently stop checking every one of them. */
+  const buildsClient = (src: string): boolean =>
+    src.includes("new HindsightClient(") || src.includes("resolveHostMemory(");
+
   function sourceFiles(dir: string, prefix = ""): string[] {
     return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
       const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -144,7 +152,7 @@ describe("every harness entrypoint reaches a daemon", () => {
     const unreached = sourceFiles(SRC).filter((rel) => {
       if (rel in EXEMPT) return false;
       const src = readFileSync(join(SRC, rel), "utf8");
-      if (!src.includes("new HindsightClient(")) return false;
+      if (!buildsClient(src)) return false;
       // RuntimeCore is the persistent-plugin hosts' shared lifecycle; it ensures at both points.
       return !src.includes("ensureDaemon") && !src.includes("RuntimeCore");
     });
@@ -154,7 +162,7 @@ describe("every harness entrypoint reaches a daemon", () => {
   // An exemption for a file that no longer builds a client is a stale claim about live code.
   it("keeps no exemption for a module that stopped building a client", () => {
     const stale = Object.keys(EXEMPT).filter(
-      (rel) => !readFileSync(join(SRC, rel), "utf8").includes("new HindsightClient(")
+      (rel) => !buildsClient(readFileSync(join(SRC, rel), "utf8"))
     );
     expect(stale).toEqual([]);
   });