@vectorize-io/hindsight-coding-agents 0.4.1 → 0.4.2

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**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
5
+ (**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Devin 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
 
@@ -14,6 +14,8 @@ in front of the agent at the moment it starts working, and keeps a curated set o
14
14
 
15
15
  ## Install
16
16
 
17
+ <!-- skill:begin title="Install / update" -->
18
+
17
19
  ```bash
18
20
  npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
19
21
  npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
@@ -22,7 +24,10 @@ npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly
22
24
 
23
25
  `install` takes an explicit target — `all`, or one or more harness names. A bare
24
26
  `npx @vectorize-io/hindsight-coding-agents install` changes nothing and prints the choice, so wiring every agent on
25
- the machine is never something that happens by accident.
27
+ the machine is never something that happens by accident. **Updating is the same `install`
28
+ command again** — it re-copies the runtime in place.
29
+
30
+ <!-- skill:end -->
26
31
 
27
32
  On a terminal it also asks **where memory should live** — Hindsight Cloud, a server you run, or a
28
33
  local daemon on this machine (see [Where memory lives](#where-memory-lives)). Scripted installs pass
@@ -263,6 +268,8 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
263
268
  otherwise the first of `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`;
264
269
  otherwise the Claude Code CLI, which needs no key. `install` tells you which it found.
265
270
 
271
+ <!-- skill:begin title="Local daemon settings (daemon mode)" -->
272
+
266
273
  Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
267
274
  environment carries over unchanged:
268
275
 
@@ -278,6 +285,10 @@ environment carries over unchanged:
278
285
  Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
279
286
  no equivalent here.
280
287
 
288
+ <!-- skill:end -->
289
+
290
+ <!-- skill:begin -->
291
+
281
292
  ## Configuration
282
293
 
283
294
  Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering, later wins per field:
@@ -287,14 +298,22 @@ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering,
287
298
  (`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
288
299
  3. the file's top level
289
300
  4. its `harnesses.<name>` section — per-agent override
301
+ 5. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
302
+ (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
290
303
 
291
304
  Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
292
- an existing setup changes nothing. `retainTags` takes a comma-separated list
293
- (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are trimmed and blanks dropped.
305
+ an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
306
+ a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
307
+ trimmed and blanks dropped.
294
308
  The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
295
309
  per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
296
310
  as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
297
311
 
312
+ `HINDSIGHT_CONFIG` moves the file itself — point it at another path for a container or a test
313
+ harness where `$HOME` is not the right anchor. It is still exactly one file; only its location
314
+ changes. (The other variables that are not settings are `HINDSIGHT_LOG_FILE`, `HINDSIGHT_DIAG_FILE`
315
+ and `HINDSIGHT_LOG_LEVEL` — see [Diagnostics & logging](#diagnostics--logging).)
316
+
298
317
  ### When a change takes effect
299
318
 
300
319
  Config is read when a process starts — the file is not watched — so when an edit applies depends on
@@ -377,6 +396,7 @@ hook by Codex...), so one shared config serves several agents side by side:
377
396
  | `reflectTimeoutMs` | `120000` | **automatic** 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) |
378
397
  | `reflectToolTimeoutMs` | `330000` | timeout for the agent-invoked `hindsight_reflect` tool — a call the agent waits on, whose high-budget synthesis on a populated bank runs for minutes. Defaults above the server's own reflect wall timeout (`HINDSIGHT_API_REFLECT_WALL_TIMEOUT`, 300s) so the server decides when to give up. Unset, it inherits an explicitly raised `reflectTimeoutMs`, but a short one never lowers it |
379
398
  | `reflectBudget` | `"high"` | reflect budget for the `hindsight_reflect` tool: `"low"`, `"mid"` or `"high"`. Drop it on a large bank where high-budget synthesis exceeds the server's wall timeout. The automatic session-start reflect always uses `"low"` to fit its hook window and is unaffected |
399
+ | `autoReflect` | `true` | inject a one-time reflect synthesis on the session's **first prompt**. `false` = tool-only reflect: nothing is injected; the agent searches knowledge pages first and reflects only when they are too shallow |
380
400
  | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
381
401
  | `pageTriggerType` | `"auto-refresh"` | when NEW knowledge pages refresh, i.e. what keeping them current costs — `"auto-refresh"` after every consolidation that produced new material, `"cron"` on `pageTriggerCron` only, `"manual"` never on their own. Auto-refresh is the most current and the most expensive: one synthesis per page per consolidation. Maps to the page's `trigger.refresh_after_consolidation` in the Hindsight API (`true` for auto-refresh, `false` for manual) |
382
402
  | `pageTriggerCron` | — | schedule for `pageTriggerType: "cron"` — UTC, standard 5-field cron, e.g. `"0 3 * * *"`. Sets the page's `trigger.refresh_cron`, which the API treats as mutually exclusive with `refresh_after_consolidation`; a scheduled refresh is skipped when nothing changed |
@@ -385,6 +405,7 @@ hook by Codex...), so one shared config serves several agents side by side:
385
405
  | `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run under the current harness's own CLI (claude/codex/antigravity/opencode), falling back to any available agent |
386
406
  | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
387
407
  | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
408
+ | `surveyRefreshCommits` | `20` | re-run the survey at SessionStart once this many commits have accrued since the last one, so the structural pages track an architecture that keeps moving (`0` = survey a cold repo only, never again) |
388
409
  | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, plugin harnesses (opencode, Kilo) upsert it every turn plus an idle flush that captures the reply the per-turn pass can't see. Set `false` — globally, per harness, or per bank — to stop writing transcripts (the background history import stops with it) while recall, git ingest and the memory tools keep working |
389
410
  | `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 |
390
411
  | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
@@ -528,6 +549,8 @@ declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar mo
528
549
  file-only. Changing this does not rewrite observations already consolidated under the old scoping —
529
550
  they stay where they were built, and new work accrues under the new setting.
530
551
 
552
+ <!-- skill:end -->
553
+
531
554
  ## Ingestion internals (no CLI)
532
555
 
533
556
  There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every
@@ -550,6 +573,27 @@ docker run -d -p 8888:8888 -p 9999:9999 -e HINDSIGHT_API_LLM_PROVIDER=gemini \
550
573
  ghcr.io/vectorize-io/hindsight:latest
551
574
  ```
552
575
 
576
+ ## Companion skill (generated)
577
+
578
+ Every skills-capable host gets `skill/SKILL.md`, which teaches the agent what this integration does
579
+ and how to configure it. **It is generated — do not edit it.** This file is the single source: the
580
+ regions between `<!-- skill:begin -->` and `<!-- skill:end -->` are copied into the skill (a region
581
+ that starts mid-section names itself with `title="…"`, and heading levels are normalised so a marked
582
+ `###` becomes the skill's `##`). Only the agent-facing half — which tools to call, crediting memory,
583
+ correcting a wrong memory — lives outside it, in `skill-src/preamble.md`.
584
+
585
+ ```bash
586
+ npm run skill:build # after editing this README or the preamble
587
+ ```
588
+
589
+ `src/docs-freshness.test.ts` fails when the skill is stale, and when a field of `RawConfig` is
590
+ readable from a config file but named nowhere in this README — the drift that produced #3735, where
591
+ the skill and the README each documented a different subset of the same settings. The docs site page
592
+ is generated from this file too (`node hindsight-docs/scripts/sync-coding-agents-doc.mjs`), which
593
+ drops the markers along with the contributor-only sections.
594
+
595
+ <!-- skill:begin -->
596
+
553
597
  ## Diagnostics & logging
554
598
 
555
599
  Two files, two audiences:
@@ -577,3 +621,39 @@ as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FIL
577
621
  `reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
578
622
  check this file — a run whose reflects failed is a no-memory run. Seed starts are logged as
579
623
  `seed_started`.
624
+
625
+ ### Is the memory ready yet?
626
+
627
+ `hindsight_sync_status` — the agent-facing tool, `dist/status.js` for scripts — answers exactly
628
+ that: `"synced": true` means the seeded memory is queryable. It also reports gitlog freshness, how
629
+ far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last
630
+ survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 — a baseline
631
+ with no findings retries automatically), and the extraction operations still in flight.
632
+
633
+ ### Resetting a repo's memory
634
+
635
+ Delete its bank on the server. The bank is the **only** state this integration keeps, so the next
636
+ session in that repo is a true first open — seed and survey run again from scratch. There are no
637
+ client-side files to clean up.
638
+
639
+ ### Marker documents you may notice
640
+
641
+ Two document ids exist for the machinery's own bookkeeping. Both are safe to ignore and safe to
642
+ delete:
643
+
644
+ - `survey-baseline:<sha>` — reads "🛰️ researching…" while a codebase survey runs and flips to
645
+ "✅ completed" once its findings land. It is retained under the `survey` strategy, whose marker
646
+ rule extracts **nothing** from a status marker, and it drives the re-survey cadence
647
+ (`surveyRefreshCommits`) and `surveyBaseline` in sync status.
648
+ - `gitlog:<repo>` — the aggregated commit-message seed document, re-upserted rather than duplicated
649
+ when the seed runs again.
650
+
651
+ ### When memory seems to be missing
652
+
653
+ Failures never break the agent: a reflect, page fetch or retain that fails degrades to an ordinary
654
+ memoryless turn and is recorded in the logs. "No memory" is therefore a log question — check the
655
+ diag file for whether `session_start` and `deepen_started` ever fired for that bank. A session that
656
+ was already running when the plugin was installed has no SessionStart behind it; its first prompt
657
+ after the install self-heals.
658
+
659
+ <!-- skill:end -->
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
33
33
  const commonDir = execFileSync(
34
34
  "git",
35
35
  ["rev-parse", "--path-format=absolute", "--git-common-dir"],
36
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
36
+ {
37
+ cwd: directory,
38
+ encoding: "utf-8",
39
+ stdio: ["ignore", "pipe", "ignore"],
40
+ timeout: 1e3,
41
+ windowsHide: true
42
+ }
37
43
  ).trim();
38
44
  if (!commonDir) return null;
39
- return basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
45
+ if (basename(commonDir) === ".git") return dirname(commonDir);
46
+ if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
47
+ return dirname(commonDir);
48
+ }
49
+ return commonDir;
40
50
  } catch {
41
51
  return null;
42
52
  }
43
53
  }
54
+ function isBareRepository(commonDir) {
55
+ try {
56
+ return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
57
+ encoding: "utf-8",
58
+ stdio: ["ignore", "pipe", "ignore"],
59
+ timeout: 1e3,
60
+ env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
61
+ }).trim() === "true";
62
+ } catch {
63
+ return false;
64
+ }
65
+ }
44
66
  var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
45
67
  function nearestExistingDir(directory) {
46
68
  let current2 = directory;
@@ -157,7 +179,8 @@ function startBackgroundSeed(repoDir, opts = {}) {
157
179
  ],
158
180
  {
159
181
  detached: true,
160
- stdio: "ignore"
182
+ stdio: "ignore",
183
+ windowsHide: true
161
184
  }
162
185
  );
163
186
  child.on("error", () => {
@@ -837,14 +860,16 @@ var HindsightClient = class {
837
860
  return;
838
861
  }
839
862
  if (r.status !== 409) created++;
840
- } else if (hit.description !== page.source_query || hit.trigger?.tags_match !== pageTrigger.tags_match) {
841
- const patch = {
842
- trigger: pageTrigger
843
- };
844
- if (hit.description !== page.source_query) {
863
+ } else {
864
+ const sourceDrift = hit.description !== page.source_query;
865
+ const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
866
+ if (!sourceDrift && !triggerDrift) continue;
867
+ const patch = {};
868
+ if (sourceDrift) {
845
869
  patch.source_query = page.source_query;
846
870
  patch.tags = page.tags;
847
871
  }
872
+ if (triggerDrift) patch.trigger = pageTrigger;
848
873
  const r = await this.req(
849
874
  "PATCH",
850
875
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
@@ -1245,9 +1270,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP fo
1245
1270
  - hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
1246
1271
  - hindsight_capture_initiative(title, summary) \u2014 right after the user approves a plan or finishes brainstorming a new feature/capability and you are about to start implementing (BEFORE you write any code), call this to record it as a tracked page; then call it AGAIN with relates_to_page_id set to that page whenever the goal, scope, or rationale materially changes mid-work, so the page tracks the current plan and not the opening one. Skip bug fixes, small tweaks, chores, and trivial course-corrections.
1247
1272
  - hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
1248
- var REFLECT_ON_GOALS = "- The user just set a NEW task or goal \u2192 call hindsight_reflect with that goal FIRST, before planning: no memory is injected automatically in this configuration, so this call is the only way past decisions, constraints, and failed attempts relevant to the goal reach you.\n";
1273
+ var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
1249
1274
  function toolGuide(opts) {
1250
- return (opts?.reflectOnNewGoals ? REFLECT_ON_GOALS : "") + TOOL_GUIDE;
1275
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
1251
1276
  }
1252
1277
  function buildRosterRefresh(pages, opts) {
1253
1278
  const rosterBlock = pages.length ? `Current Hindsight knowledge pages (may have changed):
@@ -41,14 +41,36 @@ function getProjectRootFromGit(directory) {
41
41
  const commonDir = execFileSync(
42
42
  "git",
43
43
  ["rev-parse", "--path-format=absolute", "--git-common-dir"],
44
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
44
+ {
45
+ cwd: directory,
46
+ encoding: "utf-8",
47
+ stdio: ["ignore", "pipe", "ignore"],
48
+ timeout: 1e3,
49
+ windowsHide: true
50
+ }
45
51
  ).trim();
46
52
  if (!commonDir) return null;
47
- return basename(commonDir) === ".git" ? dirname2(commonDir) : commonDir;
53
+ if (basename(commonDir) === ".git") return dirname2(commonDir);
54
+ if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
55
+ return dirname2(commonDir);
56
+ }
57
+ return commonDir;
48
58
  } catch {
49
59
  return null;
50
60
  }
51
61
  }
62
+ function isBareRepository(commonDir) {
63
+ try {
64
+ return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
65
+ encoding: "utf-8",
66
+ stdio: ["ignore", "pipe", "ignore"],
67
+ timeout: 1e3,
68
+ env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
69
+ }).trim() === "true";
70
+ } catch {
71
+ return false;
72
+ }
73
+ }
52
74
  var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
53
75
  function nearestExistingDir(directory) {
54
76
  let current2 = directory;
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
33
33
  const commonDir = execFileSync(
34
34
  "git",
35
35
  ["rev-parse", "--path-format=absolute", "--git-common-dir"],
36
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
36
+ {
37
+ cwd: directory,
38
+ encoding: "utf-8",
39
+ stdio: ["ignore", "pipe", "ignore"],
40
+ timeout: 1e3,
41
+ windowsHide: true
42
+ }
37
43
  ).trim();
38
44
  if (!commonDir) return null;
39
- return basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
45
+ if (basename(commonDir) === ".git") return dirname(commonDir);
46
+ if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
47
+ return dirname(commonDir);
48
+ }
49
+ return commonDir;
40
50
  } catch {
41
51
  return null;
42
52
  }
43
53
  }
54
+ function isBareRepository(commonDir) {
55
+ try {
56
+ return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
57
+ encoding: "utf-8",
58
+ stdio: ["ignore", "pipe", "ignore"],
59
+ timeout: 1e3,
60
+ env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
61
+ }).trim() === "true";
62
+ } catch {
63
+ return false;
64
+ }
65
+ }
44
66
  function projectNameOf(directory, sessionRoot) {
45
67
  return gitProjectName(directory, true, sessionRoot);
46
68
  }
@@ -814,14 +836,16 @@ var HindsightClient = class {
814
836
  return;
815
837
  }
816
838
  if (r.status !== 409) created++;
817
- } else if (hit.description !== page.source_query || hit.trigger?.tags_match !== pageTrigger.tags_match) {
818
- const patch = {
819
- trigger: pageTrigger
820
- };
821
- if (hit.description !== page.source_query) {
839
+ } else {
840
+ const sourceDrift = hit.description !== page.source_query;
841
+ const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
842
+ if (!sourceDrift && !triggerDrift) continue;
843
+ const patch = {};
844
+ if (sourceDrift) {
822
845
  patch.source_query = page.source_query;
823
846
  patch.tags = page.tags;
824
847
  }
848
+ if (triggerDrift) patch.trigger = pageTrigger;
825
849
  const r = await this.req(
826
850
  "PATCH",
827
851
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
@@ -1392,7 +1416,11 @@ async function isServerHealthy(baseUrl, timeoutMs = 2e3) {
1392
1416
  function hasRustToolchain() {
1393
1417
  if (process.platform !== "darwin") return true;
1394
1418
  try {
1395
- execFileSync2("cargo", ["--version"], { stdio: "pipe", timeout: 1e4 });
1419
+ execFileSync2("cargo", ["--version"], {
1420
+ stdio: "pipe",
1421
+ timeout: 1e4,
1422
+ windowsHide: true
1423
+ });
1396
1424
  return true;
1397
1425
  } catch {
1398
1426
  return false;
@@ -1400,7 +1428,11 @@ function hasRustToolchain() {
1400
1428
  }
1401
1429
  function hasUvx() {
1402
1430
  try {
1403
- execFileSync2("uvx", ["--version"], { stdio: "pipe", timeout: 1e4 });
1431
+ execFileSync2("uvx", ["--version"], {
1432
+ stdio: "pipe",
1433
+ timeout: 1e4,
1434
+ windowsHide: true
1435
+ });
1404
1436
  return true;
1405
1437
  } catch {
1406
1438
  return false;
@@ -1432,7 +1464,11 @@ function detectLlm(env = process.env) {
1432
1464
  }
1433
1465
  function onPath(bin) {
1434
1466
  try {
1435
- execFileSync2("which", [bin], { stdio: "pipe", timeout: 5e3 });
1467
+ execFileSync2("which", [bin], {
1468
+ stdio: "pipe",
1469
+ timeout: 5e3,
1470
+ windowsHide: true
1471
+ });
1436
1472
  return true;
1437
1473
  } catch {
1438
1474
  return false;
@@ -1443,7 +1479,8 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn2) {
1443
1479
  const starter = join6(dirname5(fileURLToPath2(import.meta.url)), "daemon-start.js");
1444
1480
  const child = spawnFn("node", [starter, "--harness", harness], {
1445
1481
  detached: true,
1446
- stdio: "ignore"
1482
+ stdio: "ignore",
1483
+ windowsHide: true
1447
1484
  });
1448
1485
  child.on("error", () => {
1449
1486
  });
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
33
33
  const commonDir = execFileSync(
34
34
  "git",
35
35
  ["rev-parse", "--path-format=absolute", "--git-common-dir"],
36
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
36
+ {
37
+ cwd: directory,
38
+ encoding: "utf-8",
39
+ stdio: ["ignore", "pipe", "ignore"],
40
+ timeout: 1e3,
41
+ windowsHide: true
42
+ }
37
43
  ).trim();
38
44
  if (!commonDir) return null;
39
- return basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
45
+ if (basename(commonDir) === ".git") return dirname(commonDir);
46
+ if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
47
+ return dirname(commonDir);
48
+ }
49
+ return commonDir;
40
50
  } catch {
41
51
  return null;
42
52
  }
43
53
  }
54
+ function isBareRepository(commonDir) {
55
+ try {
56
+ return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
57
+ encoding: "utf-8",
58
+ stdio: ["ignore", "pipe", "ignore"],
59
+ timeout: 1e3,
60
+ env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
61
+ }).trim() === "true";
62
+ } catch {
63
+ return false;
64
+ }
65
+ }
44
66
  var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
45
67
  function nearestExistingDir(directory) {
46
68
  let current2 = directory;
@@ -157,7 +179,8 @@ function startBackgroundSeed(repoDir, opts = {}) {
157
179
  ],
158
180
  {
159
181
  detached: true,
160
- stdio: "ignore"
182
+ stdio: "ignore",
183
+ windowsHide: true
161
184
  }
162
185
  );
163
186
  child.on("error", () => {
@@ -837,14 +860,16 @@ var HindsightClient = class {
837
860
  return;
838
861
  }
839
862
  if (r.status !== 409) created++;
840
- } else if (hit.description !== page.source_query || hit.trigger?.tags_match !== pageTrigger.tags_match) {
841
- const patch = {
842
- trigger: pageTrigger
843
- };
844
- if (hit.description !== page.source_query) {
863
+ } else {
864
+ const sourceDrift = hit.description !== page.source_query;
865
+ const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
866
+ if (!sourceDrift && !triggerDrift) continue;
867
+ const patch = {};
868
+ if (sourceDrift) {
845
869
  patch.source_query = page.source_query;
846
870
  patch.tags = page.tags;
847
871
  }
872
+ if (triggerDrift) patch.trigger = pageTrigger;
848
873
  const r = await this.req(
849
874
  "PATCH",
850
875
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
@@ -1245,9 +1270,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP fo
1245
1270
  - hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
1246
1271
  - hindsight_capture_initiative(title, summary) \u2014 right after the user approves a plan or finishes brainstorming a new feature/capability and you are about to start implementing (BEFORE you write any code), call this to record it as a tracked page; then call it AGAIN with relates_to_page_id set to that page whenever the goal, scope, or rationale materially changes mid-work, so the page tracks the current plan and not the opening one. Skip bug fixes, small tweaks, chores, and trivial course-corrections.
1247
1272
  - hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
1248
- var REFLECT_ON_GOALS = "- The user just set a NEW task or goal \u2192 call hindsight_reflect with that goal FIRST, before planning: no memory is injected automatically in this configuration, so this call is the only way past decisions, constraints, and failed attempts relevant to the goal reach you.\n";
1273
+ var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
1249
1274
  function toolGuide(opts) {
1250
- return (opts?.reflectOnNewGoals ? REFLECT_ON_GOALS : "") + TOOL_GUIDE;
1275
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
1251
1276
  }
1252
1277
  function buildRosterRefresh(pages, opts) {
1253
1278
  const rosterBlock = pages.length ? `Current Hindsight knowledge pages (may have changed):
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
33
33
  const commonDir = execFileSync(
34
34
  "git",
35
35
  ["rev-parse", "--path-format=absolute", "--git-common-dir"],
36
- { cwd: directory, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }
36
+ {
37
+ cwd: directory,
38
+ encoding: "utf-8",
39
+ stdio: ["ignore", "pipe", "ignore"],
40
+ timeout: 1e3,
41
+ windowsHide: true
42
+ }
37
43
  ).trim();
38
44
  if (!commonDir) return null;
39
- return basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
45
+ if (basename(commonDir) === ".git") return dirname(commonDir);
46
+ if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
47
+ return dirname(commonDir);
48
+ }
49
+ return commonDir;
40
50
  } catch {
41
51
  return null;
42
52
  }
43
53
  }
54
+ function isBareRepository(commonDir) {
55
+ try {
56
+ return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
57
+ encoding: "utf-8",
58
+ stdio: ["ignore", "pipe", "ignore"],
59
+ timeout: 1e3,
60
+ env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
61
+ }).trim() === "true";
62
+ } catch {
63
+ return false;
64
+ }
65
+ }
44
66
  function projectNameOf(directory, sessionRoot) {
45
67
  return gitProjectName(directory, true, sessionRoot);
46
68
  }
@@ -160,7 +182,8 @@ function startBackgroundSeed(repoDir, opts = {}) {
160
182
  ],
161
183
  {
162
184
  detached: true,
163
- stdio: "ignore"
185
+ stdio: "ignore",
186
+ windowsHide: true
164
187
  }
165
188
  );
166
189
  child.on("error", () => {
@@ -826,14 +849,16 @@ var HindsightClient = class {
826
849
  return;
827
850
  }
828
851
  if (r.status !== 409) created++;
829
- } else if (hit.description !== page.source_query || hit.trigger?.tags_match !== pageTrigger.tags_match) {
830
- const patch = {
831
- trigger: pageTrigger
832
- };
833
- if (hit.description !== page.source_query) {
852
+ } else {
853
+ const sourceDrift = hit.description !== page.source_query;
854
+ const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
855
+ if (!sourceDrift && !triggerDrift) continue;
856
+ const patch = {};
857
+ if (sourceDrift) {
834
858
  patch.source_query = page.source_query;
835
859
  patch.tags = page.tags;
836
860
  }
861
+ if (triggerDrift) patch.trigger = pageTrigger;
837
862
  const r = await this.req(
838
863
  "PATCH",
839
864
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
@@ -1205,9 +1230,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP fo
1205
1230
  - hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
1206
1231
  - hindsight_capture_initiative(title, summary) \u2014 right after the user approves a plan or finishes brainstorming a new feature/capability and you are about to start implementing (BEFORE you write any code), call this to record it as a tracked page; then call it AGAIN with relates_to_page_id set to that page whenever the goal, scope, or rationale materially changes mid-work, so the page tracks the current plan and not the opening one. Skip bug fixes, small tweaks, chores, and trivial course-corrections.
1207
1232
  - hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
1208
- var REFLECT_ON_GOALS = "- The user just set a NEW task or goal \u2192 call hindsight_reflect with that goal FIRST, before planning: no memory is injected automatically in this configuration, so this call is the only way past decisions, constraints, and failed attempts relevant to the goal reach you.\n";
1233
+ var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
1209
1234
  function toolGuide(opts) {
1210
- return (opts?.reflectOnNewGoals ? REFLECT_ON_GOALS : "") + TOOL_GUIDE;
1235
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
1211
1236
  }
1212
1237
  function buildKnowledgePreamble(pages, opts) {
1213
1238
  const body = pages.length ? `Knowledge pages currently in this repository:
@@ -1291,7 +1316,11 @@ async function isServerHealthy(baseUrl, timeoutMs = 2e3) {
1291
1316
  function hasRustToolchain() {
1292
1317
  if (process.platform !== "darwin") return true;
1293
1318
  try {
1294
- execFileSync2("cargo", ["--version"], { stdio: "pipe", timeout: 1e4 });
1319
+ execFileSync2("cargo", ["--version"], {
1320
+ stdio: "pipe",
1321
+ timeout: 1e4,
1322
+ windowsHide: true
1323
+ });
1295
1324
  return true;
1296
1325
  } catch {
1297
1326
  return false;
@@ -1299,7 +1328,11 @@ function hasRustToolchain() {
1299
1328
  }
1300
1329
  function hasUvx() {
1301
1330
  try {
1302
- execFileSync2("uvx", ["--version"], { stdio: "pipe", timeout: 1e4 });
1331
+ execFileSync2("uvx", ["--version"], {
1332
+ stdio: "pipe",
1333
+ timeout: 1e4,
1334
+ windowsHide: true
1335
+ });
1303
1336
  return true;
1304
1337
  } catch {
1305
1338
  return false;
@@ -1331,7 +1364,11 @@ function detectLlm(env = process.env) {
1331
1364
  }
1332
1365
  function onPath(bin) {
1333
1366
  try {
1334
- execFileSync2("which", [bin], { stdio: "pipe", timeout: 5e3 });
1367
+ execFileSync2("which", [bin], {
1368
+ stdio: "pipe",
1369
+ timeout: 5e3,
1370
+ windowsHide: true
1371
+ });
1335
1372
  return true;
1336
1373
  } catch {
1337
1374
  return false;
@@ -1342,7 +1379,8 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn2) {
1342
1379
  const starter = join6(dirname5(fileURLToPath2(import.meta.url)), "daemon-start.js");
1343
1380
  const child = spawnFn("node", [starter, "--harness", harness], {
1344
1381
  detached: true,
1345
- stdio: "ignore"
1382
+ stdio: "ignore",
1383
+ windowsHide: true
1346
1384
  });
1347
1385
  child.on("error", () => {
1348
1386
  });
@@ -1541,7 +1579,11 @@ import { readFileSync as readFileSync6 } from "fs";
1541
1579
  import { execFileSync as execFileSync3 } from "child_process";
1542
1580
  import { resolve } from "path";
1543
1581
  function git(repo, ...args) {
1544
- return execFileSync3("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
1582
+ return execFileSync3("git", ["-C", repo, ...args], {
1583
+ encoding: "utf8",
1584
+ maxBuffer: 1 << 28,
1585
+ windowsHide: true
1586
+ });
1545
1587
  }
1546
1588
  function gitHeadSha(dir) {
1547
1589
  try {
@@ -1752,6 +1794,7 @@ function startCodebaseSurvey(repoDir, opts = {}) {
1752
1794
  cwd: repoDir,
1753
1795
  detached: true,
1754
1796
  stdio: "ignore",
1797
+ windowsHide: true,
1755
1798
  env: plan.env
1756
1799
  });
1757
1800
  child.on("error", () => {
@@ -1818,7 +1861,10 @@ async function gitSyncNote(args) {
1818
1861
  try {
1819
1862
  const { execFileSync: execFileSync5 } = await import("child_process");
1820
1863
  const n = Number(
1821
- execFileSync5("git", ["-C", cwd, "rev-list", "--count", "HEAD"], { encoding: "utf8" }).trim()
1864
+ execFileSync5("git", ["-C", cwd, "rev-list", "--count", "HEAD"], {
1865
+ encoding: "utf8",
1866
+ windowsHide: true
1867
+ }).trim()
1822
1868
  );
1823
1869
  if (n > 0) target = Math.min(DEEPEN_DIFF_TARGET, n);
1824
1870
  } catch {