coding-agents: keep the installed runtime current by itself (#3965)

`install` stages this package into ~/.hindsight/coding-agents and points every wired
agent's hooks at that copy. Nothing ever refreshed it: the only update path was the
user remembering to re-run `install`, so a machine could sit several versions behind
indefinitely — a fix only reached people who happened to re-install. Found on a
machine running 0.4.2 while 0.4.3 had been published for days, with no signal
anywhere that an update existed.

Once a day, at session start, ask the registry for the published version and — when
it is newer — spawn a detached updater. The current session keeps running the code
it already loaded; the next one starts on the new build.

`update` is a new installer command: `install`'s staging half and nothing else. It
replaces the staged runtime (a path stable across versions, so every wired agent
picks the new code up on its next spawn) and writes to NO host config. That
separation is what makes it safe to run unattended — an `install` would need a
harness list, and choosing one on the user's behalf would rewire agents they never
asked us to touch. The cost is bounded and documented: a release introducing a NEW
hook entry point is staged but not referenced until a manual `install`.

Only ever replaces a runtime it can prove npx downloaded. `stageRuntime` records the
directory it copied from, and a copy staged from `npm i -g`, from a project
dependency, or from a local checkout is left to whoever manages that source:
re-staging behind npm's back would leave `npm ls -g` naming a version that is no
longer what runs, and re-staging over a checkout would replace a developer's own
build mid-session. A missing marker means no — it is written on every install from
this version on, and a machine has to re-install once to get this code at all, so a
runtime old enough to lack it is too old to be running the check. Failing closed
costs one manual install; failing open costs somebody their working tree.

Concurrency is real here, not hypothetical: this is a plugin for machines that run
five agents at once, and a 24h stamp does not serialise anything — several sessions
starting in the same second all read "due" before any has written it. Two concurrent
stageRuntime runs are `rmSync(dist)` then `cpSync`, where one process deletes the
directory the other is half way through writing, leaving a runtime with missing
entry points and every hook broken. A lock claimed before the registry call makes a
burst produce ONE request and one updater; same shape as deepen.ts's per-bank lock,
with the holder's pid deciding liveness so a crash cannot wedge the window, and the
stored pid is the detached CHILD's since the copy outlives the session.

Other guards, each with a test: `npx` must be on PATH (without it there is nothing
to spawn, so the check is skipped rather than burning a request and failing a spawn
asynchronously); a prerelease never supersedes the release of the same version; an
unreadable staged version never guesses; the survey's own headless session is
excluded; and both ownership refusals stamp the check so each states its reason at
most once a day.

`autoUpdate: false` (or HINDSIGHT_AUTO_UPDATE=false) pins the installed version,
settable globally, per harness or per bank. `disabled` stops it too — an inert
plugin should stay inert, and a network call plus a background npm install is not
inert.

Wired at BOTH session-start paths — `runSessionStartHook` for the hook harnesses and
`RuntimeCore.seedIfCold` for the persistent-plugin hosts — plus a family-wide guard
test that enumerates session starts structurally rather than from a hand-maintained
list, so a third host cannot land without an update check. Session-start
housekeeping has gone missing on the plugin hosts before (#3524), and the harness
that forgets is by definition the one whose test nobody wrote.

Known window, documented in the module doc: staging replaces dist/ wholesale, so a
hook spawning during the copy can fail to load. Running processes are unaffected,
the window is milliseconds once a day, and the cost is one turn without memory.
Serialising against it would need a lock every hook takes on every turn — a worse
trade than the window it closes.

Also hoists survey.ts's `binExists` to util.ts as `binOnPath`.

Claude-Session: https://claude.ai/code/session_011KDT484YujNcBxHzbfzNbk

Author: nicoloboschi

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

@@ -124,6 +124,13 @@ export interface RawConfig {
   /** Plugin log verbosity ("debug" | "info" | "warn" | "error", default "info");
    *  HINDSIGHT_LOG_LEVEL overrides for ad-hoc debugging. */
   logLevel?: "debug" | "info" | "warn" | "error";
+  /** Keep the installed runtime current by itself (default true). Once a day a session start asks
+   *  npm for the published version and, when it is newer, re-stages ~/.hindsight/coding-agents in
+   *  the background — the copy every wired agent's hooks already point at. It rewires no host
+   *  config, so a release that adds a NEW hook entry point still needs a manual `install`.
+   *  Set false to pin the installed version (air-gapped machines, or a deliberate downgrade);
+   *  updating is then `npx @vectorize-io/hindsight-coding-agents install` again, as before. */
+  autoUpdate?: boolean;
   surveyRefreshCommits?: number; // re-run the survey at SessionStart once this many commits have accrued since the last one, so structural pages track an evolving architecture (default 20; 0 = cold-seed only)
   /** How git history feeds memory — seeding AND keeping current use the same engine:
    *  "message" = commit messages only (cheap aggregated doc, re-upserted when HEAD moves);
@@ -201,6 +208,7 @@ export interface Config {
   observationScopes: ObservationScopes;
   banks: Record<string, Omit<RawConfig, "banks" | "harnesses"> & { bank?: string }>;
   logLevel: "debug" | "info" | "warn" | "error";
+  autoUpdate: boolean;
 }
 
 /**
@@ -344,6 +352,7 @@ export function resolveConfig(raw: RawConfig = {}): Config {
     logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel as string)
       ? (raw.logLevel as "debug" | "info" | "warn" | "error")
       : "info",
+    autoUpdate: raw.autoUpdate ?? true,
   };
 }
 
@@ -433,6 +442,7 @@ const ENV_KEYS = {
   surveyBudgetUsd: "HINDSIGHT_SURVEY_BUDGET_USD",
   surveyRefreshCommits: "HINDSIGHT_SURVEY_REFRESH_COMMITS",
   logLevel: "HINDSIGHT_LOG_LEVEL",
+  autoUpdate: "HINDSIGHT_AUTO_UPDATE",
   gitIngest: "HINDSIGHT_GIT_INGEST",
   // Scalar modes only ("shared", "combined", "per_tag", "all_combinations"). An explicit scope
   // list is a list OF lists, which does not survive flattening into one variable — file-only.
@@ -452,6 +462,7 @@ const ENV_BOOLEANS = new Set<keyof RawConfig>([
   "autoReflect",
   "autoSeed",
   "codebaseSurvey",
+  "autoUpdate",
 ]);
 const ENV_LISTS = new Set<keyof RawConfig>(["retainTags", "optInPaths"]);
 const ENV_NUMBERS = new Set<keyof RawConfig>([

hindsight-integrations/coding-agents/README.md

@@ -14,6 +14,7 @@
  * No opencode/claude specifics live here — only the memory logic.
  */
 import type { Config } from "./config";
+import { maybeAutoUpdate } from "./auto-update";
 import { DAEMON_WAIT_RETAIN_MS, DAEMON_WAIT_SESSION_START_MS, ensureDaemon } from "./daemon";
 import { diag } from "./diag";
 import { describeError, log, setLogLevel } from "./log";
@@ -112,6 +113,10 @@ export class RuntimeCore {
     // `runSessionStartHook` is a hook-only wrapper, so calling `buildSessionStartContext` directly
     // (as every plugin harness does) skipped the ensure entirely.
     await ensureDaemon(this.cfg, this.harness, { waitMs: DAEMON_WAIT_SESSION_START_MS });
+    // Same session-start housekeeping the hook harnesses do in `runSessionStartHook`: a persistent
+    // plugin host is a session start too, and leaving it out would mean opencode/Kilo/Cline users
+    // never got an update — the parity gap `ensureDaemon` above already had to be fixed for.
+    void maybeAutoUpdate(this.cfg);
     try {
       const out = await buildSessionStartContext({
         cwd: repoPath || process.cwd(),

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

@@ -22,6 +22,7 @@ import { readFileSync } from "node:fs";
 import { gitHeadSha, hasGitHistory, commitsSince, repoNameOf } from "./git";
 import { DEEPEN_DIFF_TARGET } from "./status";
 import { startBackgroundSeed } from "./seed";
+import { maybeAutoUpdate } from "./auto-update";
 import { syncCompanionSkill } from "./skill-sync";
 import { SURVEY_DOC_IDS, startCodebaseSurvey, type SurveyHarness } from "./survey";
 import { applyBankConfig, loadConfig } from "./config";
@@ -352,6 +353,12 @@ export async function runSessionStartHook(
     setLogLevel(cfg.logLevel);
     syncCompanionSkill(harness); // keep the installed skill current with the package version
     if (cfg.disabled) return;
+    // …and keep the package itself current. AFTER the disabled check, unlike the skill sync above:
+    // `disabled` means an inert plugin, and a network call plus a background npm install is not
+    // inert. It also keeps the two harness families symmetric — the plugin hosts never construct a
+    // RuntimeCore when disabled (harness/plugin-entry.ts), so they already skip this.
+    // Detached and rate-limited to once a day; the update lands for the NEXT session.
+    void maybeAutoUpdate(cfg);
 
     // Recorded HERE, on the session's first hook, so every later hook of this session resolves the
     // same bank however far the agent navigates (#3563).

hindsight-integrations/coding-agents/src/core/auto-update.test.ts

@@ -37,10 +37,11 @@
  * missing binary or a spawn failure must silently no-op, never crash the caller.
  */
 import { spawn as realSpawn } from "node:child_process";
-import { accessSync, constants, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { binOnPath } from "./util";
 
 /** Deterministic doc ids of the survey's findings (its fixed titles slugified by
  *  hindsight_ingest_document). Their presence in the bank = the survey actually FINISHED —
@@ -117,28 +118,6 @@ function resolveAgentBin(harness: SurveyHarness, claudeBin?: string): string {
   }
 }
 
-/** Is `bin` runnable? A path (contains "/") -> exists + executable; a bare name -> found on PATH. */
-function binExists(bin: string): boolean {
-  try {
-    if (bin.includes("/")) {
-      accessSync(bin, constants.X_OK);
-      return true;
-    }
-    for (const dir of (process.env.PATH || "").split(delimiter)) {
-      if (!dir) continue;
-      try {
-        accessSync(join(dir, bin), constants.X_OK);
-        return true;
-      } catch {
-        /* keep scanning PATH */
-      }
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
 export const SURVEY_PROMPT =
   "You are performing a one-time structural survey of THIS repository to seed its Hindsight " +
   "memory. Work efficiently — DO NOT read every file; sample enough to understand the " +
@@ -318,7 +297,7 @@ export function startCodebaseSurvey(
 ): void {
   try {
     const spawnFn = opts.spawn ?? realSpawn;
-    const exists = opts.exists ?? binExists;
+    const exists = opts.exists ?? binOnPath;
     const mcpServerPath =
       opts.mcpServerPath ?? join(dirname(fileURLToPath(import.meta.url)), "mcp-server.js");
 

hindsight-integrations/coding-agents/src/core/auto-update.ts

@@ -1,4 +1,33 @@
 /** Small shared helpers (no harness or Hindsight coupling). */
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/**
+ * Is `bin` runnable? A path (contains "/") -> exists + executable; a bare name -> found on PATH.
+ *
+ * Resolved by hand rather than by spawning: the callers use this to DECIDE whether to spawn, and
+ * `which`/`where` is itself a process launch on a path where the answer is usually "no".
+ */
+export function binOnPath(bin: string): boolean {
+  try {
+    if (bin.includes("/")) {
+      accessSync(bin, constants.X_OK);
+      return true;
+    }
+    for (const dir of (process.env.PATH || "").split(delimiter)) {
+      if (!dir) continue;
+      try {
+        accessSync(join(dir, bin), constants.X_OK);
+        return true;
+      } catch {
+        /* keep scanning PATH */
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
 
 export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));