@vectorize-io/hindsight-coding-agents 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Long-term project memory for **coding agents**, backed by [Hindsight](https://vectorize.io/hindsight).
4
4
  One package, several agents: a shared reflect-and-inject core with a thin entry point per agent
5
- (**opencode**, **Kilo CLI**, **Cline CLI**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
5
+ (**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
6
6
  automatic — there is no setup command: a repo's git history and conversations flow into its memory
7
7
  bank in the background as you work.
8
8
 
@@ -112,6 +112,14 @@ npx @vectorize-io/hindsight-coding-agents install cline-cli
112
112
 
113
113
  A native plugin via `cline plugin install`, plus MCP and the companion skill.
114
114
 
115
+ #### <img src="https://hindsight.vectorize.io/img/harness/prime-agent.svg" alt="" width="20" height="20" /> Prime Agent
116
+
117
+ ```bash
118
+ npx @vectorize-io/hindsight-coding-agents install prime-agent
119
+ ```
120
+
121
+ An extension entry in `~/.prime/agent/settings.json` — native tools, no MCP needed.
122
+
115
123
  Uninstall the same way: `npx @vectorize-io/hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
116
124
 
117
125
  **Devin CLI needs Node 22.5 or newer.** Its hooks pass only a session id — the conversation itself
@@ -266,7 +274,34 @@ Environment variables are a **fallback**: the file wins wherever it sets a value
266
274
  an existing setup changes nothing. `retainTags` takes a comma-separated list
267
275
  (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are trimmed and blanks dropped.
268
276
  The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
269
- per-key branching doesn't survive flattening into one variable.
277
+ per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
278
+ as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
279
+
280
+ ### Opt-in only
281
+
282
+ By default every project gets memory — that is what makes the plugin zero-setup. If you would
283
+ rather nothing be remembered until you say so, turn memory off everywhere and name the projects
284
+ that may use it:
285
+
286
+ ```jsonc
287
+ {
288
+ "optInOnly": true,
289
+ "optInPaths": ["~/work/client-x", "~/oss"],
290
+ }
291
+ ```
292
+
293
+ Anything outside those paths is **inert**: no bank is created, nothing is retained, no seed runs,
294
+ and the agent behaves exactly as it would without the plugin. Approving costs nothing else —
295
+ `optInPaths` says _which projects_, not _which bank_, so an approved repo keeps its usual
296
+ `coding-agent::{gitProject}` name. Paths are prefixes, so approving `~/work` approves every repo
297
+ under it while each still gets its own bank.
298
+
299
+ A `mapPathToBank` entry counts as opted in too, since routing a path to a named bank already
300
+ declares that project. A bare `bankId` does not: it names a bank rather than a project, so it
301
+ cannot say which work may be remembered, and a privacy switch has to fail closed.
302
+
303
+ There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
304
+ cloned repository must not be able to turn memory on.
270
305
 
271
306
  There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
272
307
  per-agent differences are `harnesses.<name>`.
@@ -294,9 +329,11 @@ hook by Codex...), so one shared config serves several agents side by side:
294
329
  | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
295
330
  | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
296
331
  | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; overrides everything |
332
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
333
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath keeps its own dynamic bank |
297
334
  | `resolveWorktrees` | `true` | `{gitProject}`: linked worktrees share the main repo's bank |
298
- | `retainTags` | — | extra tags on every session write-back, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
299
- | `retainMetadata` | — | extra metadata on every session write-back, e.g. `{"repo": "{gitProject}"}` |
335
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
336
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
300
337
  | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
301
338
  | `reflectTimeoutMs` | `120000` | session-reflect timeout (hook harnesses additionally cap it at 25s to fit the host's hook window); on timeout the session runs without reflect (recorded) |
302
339
  | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
@@ -306,7 +343,7 @@ hook by Codex...), so one shared config serves several agents side by side:
306
343
  | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
307
344
  | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
308
345
  | `retainSessions` | `true` | plugin-harness write-back (opencode, Kilo): async upsert of the session transcript every turn, plus an idle flush that captures the reply the per-turn pass can't see (set `false` to opt out; hook harnesses always write on Stop) |
309
- | `retainEveryTurns` | `1` | write-back cadence in user turns, for the plugin harnesses (opencode, Kilo, Cline CLI) — hook harnesses write on every Stop and ignore it |
346
+ | `maxParallelRetains` | `10` | cap on concurrent retain-related requests: drain()'s per-op polls plus deepen's chat/git retain pools. The API rate-limits bursts, not single requests — if you see 429s, lower this rather than raising it |
310
347
  | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
311
348
  | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
312
349
  | `harnesses.<name>` | — | per-harness override of any field above |
@@ -383,8 +420,9 @@ all share one memory per repo — use `"{harness}-{gitProject}"` to split per ag
383
420
 
384
421
  With a bank per repo, the bank _is_ the answer to "where did this come from". On a deliberately
385
422
  **shared** bank — one bank holding cross-project knowledge so facts recall everywhere — it isn't:
386
- every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto each session
387
- write-back:
423
+ every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto conversations,
424
+ git history and diffs, survey lifecycle documents, initiative markers, and documents saved through
425
+ `hindsight_ingest_document`:
388
426
 
389
427
  ```jsonc
390
428
  {
@@ -398,6 +436,7 @@ Recalls can then filter by `project:<repo>`, and every document shows which repo
398
436
  of. Both accept the same placeholders as `bankIdTemplate` — `{gitProject}`, `{project}`,
399
437
  `{harness}`, `{channel}`, `{user}` — plus `{bankId}`, `{sessionId}` and `{timestamp}`.
400
438
  `{gitProject}` is worktree-aware here too, so every linked worktree of a repo stamps one name.
439
+ `{sessionId}` resolves to `unknown` for documents that do not originate from an agent session.
401
440
 
402
441
  The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
403
442
  with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
@@ -1,10 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/core/hook.ts
4
- import { existsSync, readFileSync as readFileSync3 } from "fs";
4
+ import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
5
5
 
6
6
  // src/core/bank.ts
7
7
  import { execFileSync } from "child_process";
8
+ import { existsSync } from "fs";
8
9
  import { homedir } from "os";
9
10
  import { basename, dirname, join, normalize, sep } from "path";
10
11
 
@@ -40,25 +41,59 @@ function getProjectRootFromGit(directory) {
40
41
  return null;
41
42
  }
42
43
  }
44
+ var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
45
+ function nearestExistingDir(directory) {
46
+ let current2 = directory;
47
+ while (current2) {
48
+ if (existsSync(current2)) return current2;
49
+ const parent = dirname(current2);
50
+ if (parent === current2) return "";
51
+ current2 = parent;
52
+ }
53
+ return "";
54
+ }
55
+ function dirName(directory) {
56
+ return directory && basename(directory) || "unknown";
57
+ }
43
58
  function gitProjectName(directory, resolveWorktrees) {
44
59
  if (resolveWorktrees) {
45
- const root = getProjectRootFromGit(directory);
46
- if (root) return basename(root);
60
+ const candidates = [
61
+ nearestExistingDir(directory),
62
+ ...PROJECT_ROOT_ENV.map((v) => process.env[v] || "")
63
+ ];
64
+ for (const candidate of candidates) {
65
+ const root = candidate ? getProjectRootFromGit(candidate) : null;
66
+ if (root) return basename(root);
67
+ }
47
68
  }
48
- return directory ? basename(directory) : "unknown";
69
+ return dirName(directory);
70
+ }
71
+ function configuredDir(dir) {
72
+ const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
73
+ return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
74
+ }
75
+ function isWithin(directory, configured) {
76
+ return directory === configured || directory.startsWith(configured + sep);
49
77
  }
50
78
  function mapLookup(map, directory) {
51
79
  const cwd = normalize(directory);
52
80
  let best;
53
81
  for (const [dir, bank] of Object.entries(map)) {
54
- const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
55
- const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
56
- if (cwd === p || cwd.startsWith(p + sep)) {
82
+ const p = configuredDir(dir);
83
+ if (isWithin(cwd, p)) {
57
84
  if (!best || p.length > best.len) best = { len: p.length, bank };
58
85
  }
59
86
  }
60
87
  return best?.bank;
61
88
  }
89
+ function isOptedIn(config, directory) {
90
+ if (!config.optInOnly) return true;
91
+ if (!directory) return false;
92
+ const cwd = normalize(directory);
93
+ if ((config.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
94
+ return true;
95
+ return Boolean(config.mapPathToBank && mapLookup(config.mapPathToBank, directory));
96
+ }
62
97
  function deriveBankId(config, directory, harness = "coding") {
63
98
  const mapped = directory && config.mapPathToBank ? mapLookup(config.mapPathToBank, directory) : void 0;
64
99
  if (mapped) return mapped;
@@ -66,7 +101,7 @@ function deriveBankId(config, directory, harness = "coding") {
66
101
  if (!dynamic) return config.bankId || DEFAULT_BANK_NAME;
67
102
  const resolvers = {
68
103
  harness: () => harness,
69
- project: () => directory ? basename(directory) : "unknown",
104
+ project: () => dirName(directory),
70
105
  gitProject: () => gitProjectName(directory, config.resolveWorktrees ?? true),
71
106
  channel: () => process.env.HINDSIGHT_CHANNEL_ID || "default",
72
107
  user: () => process.env.HINDSIGHT_USER_ID || "anonymous"
@@ -136,11 +171,14 @@ function resolveConfig(raw = {}) {
136
171
  bankIdTemplate: raw.bankIdTemplate,
137
172
  mapPathToBank: raw.mapPathToBank,
138
173
  resolveWorktrees: raw.resolveWorktrees,
174
+ optInOnly: raw.optInOnly ?? false,
175
+ // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
176
+ optInPaths: Array.isArray(raw.optInPaths) ? raw.optInPaths.filter((p) => typeof p === "string" && p.trim() !== "") : [],
139
177
  harness: raw.harness ?? "opencode",
140
178
  disabled: raw.disabled ?? false,
141
179
  retainSessions: raw.retainSessions ?? true,
142
180
  // opencode: write back by default (parity with hook-harness Stop)
143
- retainEveryTurns: raw.retainEveryTurns || 1,
181
+ maxParallelRetains: raw.maxParallelRetains || 10,
144
182
  reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
145
183
  autoReflect: raw.autoReflect ?? true,
146
184
  pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
@@ -196,10 +234,12 @@ var ENV_KEYS = {
196
234
  dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
197
235
  bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
198
236
  resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
237
+ optInOnly: "HINDSIGHT_OPT_IN_ONLY",
238
+ optInPaths: "HINDSIGHT_OPT_IN_PATHS",
199
239
  harness: "HINDSIGHT_HARNESS",
200
240
  disabled: "HINDSIGHT_DISABLED",
201
241
  retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
202
- retainEveryTurns: "HINDSIGHT_RETAIN_EVERY_TURNS",
242
+ maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
203
243
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
204
244
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
205
245
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
@@ -218,17 +258,18 @@ var ENV_KEYS = {
218
258
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
219
259
  "dynamicBankId",
220
260
  "resolveWorktrees",
261
+ "optInOnly",
221
262
  "disabled",
222
263
  "retainSessions",
223
264
  "autoReflect",
224
265
  "autoSeed",
225
266
  "codebaseSurvey"
226
267
  ]);
227
- var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags"]);
268
+ var ENV_LISTS = /* @__PURE__ */ new Set(["retainTags", "optInPaths"]);
228
269
  var ENV_NUMBERS = /* @__PURE__ */ new Set([
229
270
  "apiPort",
230
271
  "daemonIdleTimeout",
231
- "retainEveryTurns",
272
+ "maxParallelRetains",
232
273
  "reflectTimeoutMs",
233
274
  "pageRefreshEveryTurns",
234
275
  "seedLimit",
@@ -268,9 +309,15 @@ var BANK_OVERRIDE_EXCLUDED = [
268
309
  "mapPathToBank",
269
310
  "dynamicBankId",
270
311
  "resolveWorktrees",
312
+ // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
313
+ // only ever arrive too late to matter — strip them rather than let them read as effective.
314
+ "optInOnly",
315
+ "optInPaths",
271
316
  "harness"
272
317
  ];
273
- function applyBankConfig(cfg, resolvedId) {
318
+ function applyBankConfig(cfg, resolvedId, directory) {
319
+ if (directory !== void 0 && !isOptedIn(cfg, directory))
320
+ return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
274
321
  const section = cfg.banks[resolvedId];
275
322
  if (!section) return { cfg, bankId: resolvedId };
276
323
  const safe = { ...section };
@@ -482,9 +529,40 @@ function semverGte(version, min) {
482
529
  }
483
530
  return true;
484
531
  }
532
+ async function pool(items, n, fn, onError, onProgress) {
533
+ let i = 0, done = 0;
534
+ async function worker() {
535
+ while (i < items.length) {
536
+ const idx = i++;
537
+ try {
538
+ await fn(items[idx], idx);
539
+ } catch (e) {
540
+ onError?.(idx, e);
541
+ }
542
+ onProgress?.(++done, items.length);
543
+ }
544
+ }
545
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
546
+ }
485
547
 
486
548
  // src/core/hindsight.ts
487
549
  var MIN_IDEMPOTENT_RETAIN_VERSION = "0.8.6";
550
+ var RateLimitedError = class extends Error {
551
+ constructor(retryAfterMs2) {
552
+ super(`rate limited; retry after ${Math.round(retryAfterMs2 / 1e3)}s`);
553
+ this.retryAfterMs = retryAfterMs2;
554
+ this.name = "RateLimitedError";
555
+ }
556
+ retryAfterMs;
557
+ code = "rate_limited";
558
+ };
559
+ function retryAfterMs(header) {
560
+ if (!header) return 0;
561
+ const secs = Number(header.trim());
562
+ if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
563
+ const at = Date.parse(header);
564
+ return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
565
+ }
488
566
  var KnowledgePagesUnavailableError = class extends Error {
489
567
  code = "knowledge_pages_unavailable";
490
568
  constructor() {
@@ -493,6 +571,10 @@ var KnowledgePagesUnavailableError = class extends Error {
493
571
  }
494
572
  };
495
573
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
574
+ var DEFAULT_MAX_PARALLEL_RETAINS = 10;
575
+ var POLL_CYCLE_MS = 5e3;
576
+ var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
577
+ var RETRY_AFTER_CEILING_MS = 60 * 1e3;
496
578
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
497
579
  var HindsightClient = class {
498
580
  apiUrl;
@@ -505,12 +587,14 @@ var HindsightClient = class {
505
587
  /** Tri-state capability probe: unknown until the first append-mode retain, then cached. */
506
588
  idempotentRetain;
507
589
  log;
590
+ maxParallelRetains;
508
591
  constructor(o) {
509
592
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
510
593
  this.apiToken = o.apiToken;
511
594
  this.bank = o.bank;
512
595
  this.log = o.log ?? (() => {
513
596
  });
597
+ this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
514
598
  }
515
599
  headers() {
516
600
  const h = { "Content-Type": "application/json" };
@@ -528,6 +612,8 @@ var HindsightClient = class {
528
612
  body: body ? JSON.stringify(body) : void 0,
529
613
  signal: AbortSignal.timeout(15e3)
530
614
  });
615
+ if (r.status === 429 && !tolerate.includes(429))
616
+ throw new RateLimitedError(retryAfterMs(r.headers.get("retry-after")));
531
617
  if (!r.ok && r.status !== 404 && !tolerate.includes(r.status))
532
618
  throw new Error(`${method} ${url} -> ${r.status} ${await r.text()}`);
533
619
  return r;
@@ -659,7 +745,14 @@ var HindsightClient = class {
659
745
  return 0;
660
746
  }
661
747
  }
662
- /** Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable. */
748
+ /**
749
+ * Poll each enqueued operation by id until terminal. LIST only shows active ops, so per-id GET is reliable.
750
+ *
751
+ * Concurrency is capped at `maxParallelRetains` (the API rate-limits bursts, not single
752
+ * requests — a 200 to a lone GET with 429s under `Promise.all` over every pending op). A 429
753
+ * leaves the op pending and backs the next cycle off by its `Retry-After` (10s floor) instead
754
+ * of hammering the next cycle 5s later.
755
+ */
663
756
  async drain(ids, label, maxMs = 60 * 60 * 1e3) {
664
757
  if (!ids.length) return;
665
758
  this.log(`[wait] draining ${ids.length} ${label} operations \u2026`);
@@ -667,23 +760,29 @@ var HindsightClient = class {
667
760
  const pending = new Set(ids);
668
761
  let failed = 0;
669
762
  while (pending.size && Date.now() - start < maxMs) {
670
- await Promise.all(
671
- [...pending].map(async (id) => {
672
- try {
673
- const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
674
- if (!r.ok) return;
675
- const st = ((await r.json()).status || "").toLowerCase();
676
- if (TERMINAL.has(st)) {
677
- pending.delete(id);
678
- if (st !== "completed") failed++;
679
- }
680
- } catch {
763
+ let backoffMs = POLL_CYCLE_MS;
764
+ await pool([...pending], this.maxParallelRetains, async (id) => {
765
+ try {
766
+ const r = await fetch(this.bankUrl(`/operations/${id}`), { headers: this.headers() });
767
+ if (r.status === 429) {
768
+ backoffMs = Math.min(
769
+ RETRY_AFTER_CEILING_MS,
770
+ Math.max(backoffMs, RETRY_AFTER_FLOOR_MS, retryAfterMs(r.headers.get("retry-after")))
771
+ );
772
+ return;
681
773
  }
682
- })
683
- );
774
+ if (!r.ok) return;
775
+ const st = ((await r.json()).status || "").toLowerCase();
776
+ if (TERMINAL.has(st)) {
777
+ pending.delete(id);
778
+ if (st !== "completed") failed++;
779
+ }
780
+ } catch {
781
+ }
782
+ });
684
783
  if (pending.size) {
685
784
  this.log(` \u2026 ${pending.size}/${ids.length} ${label} ops pending`);
686
- await sleep(5e3);
785
+ await sleep(backoffMs);
687
786
  }
688
787
  }
689
788
  this.log(
@@ -883,13 +982,20 @@ var HindsightClient = class {
883
982
  const verb = args.relatesToPageId ? "Enhancement to an existing initiative" : "New initiative";
884
983
  const content = `${verb}: ${args.title}. ${args.summary}`;
885
984
  const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
886
- await this.retain(
887
- content,
888
- "initiative marker",
889
- markerId,
890
- ["knowledge:feature-work", `relatedPageId:${pageId}`],
891
- "document"
892
- );
985
+ const tags = [
986
+ .../* @__PURE__ */ new Set([
987
+ ...args.stamp?.tags ?? [],
988
+ "knowledge:feature-work",
989
+ `relatedPageId:${pageId}`
990
+ ])
991
+ ];
992
+ if (Object.keys(args.stamp?.metadata ?? {}).length) {
993
+ await this.retain(content, "initiative marker", markerId, tags, "document", {
994
+ metadata: args.stamp?.metadata
995
+ });
996
+ } else {
997
+ await this.retain(content, "initiative marker", markerId, tags, "document");
998
+ }
893
999
  return { page_id: pageId };
894
1000
  }
895
1001
  /** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
@@ -988,7 +1094,7 @@ ${toolGuide(opts)}
988
1094
  }
989
1095
 
990
1096
  // src/core/session-cache.ts
991
- import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
1097
+ import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync } from "fs";
992
1098
  import { tmpdir as tmpdir2 } from "os";
993
1099
  import { dirname as dirname4, join as join5 } from "path";
994
1100
  function sessionCacheFile(harness, sessionId) {
@@ -1001,10 +1107,23 @@ function readSessionCache(cacheFile) {
1001
1107
  return {};
1002
1108
  }
1003
1109
  }
1110
+ function writeFileAtomic(path, body) {
1111
+ mkdirSync2(dirname4(path), { recursive: true });
1112
+ const tmp = `${path}.${process.pid}.tmp`;
1113
+ try {
1114
+ writeFileSync(tmp, body);
1115
+ renameSync(tmp, path);
1116
+ } catch (e) {
1117
+ try {
1118
+ rmSync(tmp, { force: true });
1119
+ } catch {
1120
+ }
1121
+ throw e;
1122
+ }
1123
+ }
1004
1124
  function writeSessionCache(cacheFile, cache) {
1005
1125
  try {
1006
- mkdirSync2(dirname4(cacheFile), { recursive: true });
1007
- writeFileSync(cacheFile, JSON.stringify(cache));
1126
+ writeFileAtomic(cacheFile, JSON.stringify(cache));
1008
1127
  } catch {
1009
1128
  }
1010
1129
  }
@@ -1025,7 +1144,10 @@ async function buildHookOutput(args) {
1025
1144
  const t0 = Date.now();
1026
1145
  try {
1027
1146
  reflectAnswer = await client.reflect(buildReflectQuery(prompt), {
1028
- budget: "high",
1147
+ // Automatic reflection runs inside a hard 25s hook window. Hindsight's low budget is the
1148
+ // supported default for bounded reflect calls; callers that explicitly invoke the MCP
1149
+ // tool still get the deeper high-budget path.
1150
+ budget: "low",
1029
1151
  timeoutMs: Math.min(cfg.reflectTimeoutMs, HOOK_REFLECT_CAP_MS)
1030
1152
  });
1031
1153
  diag(harness, reflectAnswer ? "reflect_ok" : "reflect_empty", {
@@ -1108,16 +1230,21 @@ async function runHook(spec, makeClient = (o) => new HindsightClient(o)) {
1108
1230
  return;
1109
1231
  }
1110
1232
  const out = (context, notice) => process.stdout.write(JSON.stringify(spec.emit(context ?? "", notice, ev)));
1111
- const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness));
1233
+ const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness), cwd);
1112
1234
  cfg = resolved.cfg;
1113
1235
  const bankId = resolved.bankId;
1114
1236
  if (cfg.disabled) {
1115
1237
  log.debug(spec.harness, "hook skipped: bank disabled via banks override", { bank: bankId });
1116
1238
  return;
1117
1239
  }
1118
- const client = makeClient({ apiUrl: cfg.apiUrl, apiToken: cfg.apiToken, bank: bankId });
1240
+ const client = makeClient({
1241
+ apiUrl: cfg.apiUrl,
1242
+ apiToken: cfg.apiToken,
1243
+ bank: bankId,
1244
+ maxParallelRetains: cfg.maxParallelRetains
1245
+ });
1119
1246
  const cacheFile = sessionCacheFile(spec.harness, sessionId || "no-session");
1120
- if (cfg.autoSeed !== false && !existsSync(cacheFile)) {
1247
+ if (cfg.autoSeed !== false && !existsSync2(cacheFile)) {
1121
1248
  startBackgroundSeed(cwd, { limit: cfg.seedLimit, harness: spec.harness });
1122
1249
  }
1123
1250
  const output = await buildHookOutput({ harness: spec.harness, prompt, cfg, client, cacheFile });
@@ -1252,13 +1379,13 @@ import { execFileSync as execFileSync4 } from "child_process";
1252
1379
 
1253
1380
  // src/core/survey.ts
1254
1381
  import { spawn as realSpawn3 } from "child_process";
1255
- import { accessSync, constants, existsSync as existsSync2 } from "fs";
1382
+ import { accessSync, constants, existsSync as existsSync3 } from "fs";
1256
1383
  import { homedir as homedir3 } from "os";
1257
1384
  import { delimiter, dirname as dirname6, join as join7 } from "path";
1258
1385
  import { fileURLToPath as fileURLToPath3 } from "url";
1259
1386
 
1260
1387
  // src/core/skill-sync.ts
1261
- import { cpSync, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1388
+ import { cpSync, existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
1262
1389
  import { homedir as homedir4 } from "os";
1263
1390
  import { dirname as dirname7, join as join8 } from "path";
1264
1391
  import { fileURLToPath as fileURLToPath4 } from "url";
@@ -1393,14 +1520,14 @@ function readCopilotTranscript(path) {
1393
1520
  }
1394
1521
 
1395
1522
  // src/core/transcript-grok.ts
1396
- import { existsSync as existsSync4, readFileSync as readFileSync7, readdirSync } from "fs";
1523
+ import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync } from "fs";
1397
1524
  import { homedir as homedir5 } from "os";
1398
1525
  import { join as join9 } from "path";
1399
1526
  var CHAT_HISTORY = "chat_history.jsonl";
1400
1527
  function grokTranscriptPath(cwd, sessionId, grokHome = process.env.GROK_HOME || join9(homedir5(), ".grok")) {
1401
1528
  const sessionsDir = join9(grokHome, "sessions");
1402
1529
  const direct = join9(sessionsDir, encodeURIComponent(cwd), sessionId, CHAT_HISTORY);
1403
- if (existsSync4(direct)) return direct;
1530
+ if (existsSync5(direct)) return direct;
1404
1531
  try {
1405
1532
  for (const candidate of readdirSync(sessionsDir)) {
1406
1533
  const directory = join9(sessionsDir, candidate);
@@ -1440,7 +1567,7 @@ function readGrokTranscript(path) {
1440
1567
  }
1441
1568
 
1442
1569
  // src/core/transcript-devin.ts
1443
- import { existsSync as existsSync5 } from "fs";
1570
+ import { existsSync as existsSync6 } from "fs";
1444
1571
  import { createRequire } from "module";
1445
1572
  import { homedir as homedir6 } from "os";
1446
1573
  import { join as join10 } from "path";
@@ -1482,7 +1609,7 @@ function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
1482
1609
  diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
1483
1610
  return [];
1484
1611
  }
1485
- if (!existsSync5(dbPath)) {
1612
+ if (!existsSync6(dbPath)) {
1486
1613
  diag("devin-cli", "session_db_missing", { dbPath });
1487
1614
  return [];
1488
1615
  }