@vectorize-io/hindsight-coding-agents 0.6.1 → 0.8.0

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.
Files changed (56) hide show
  1. package/README.md +314 -51
  2. package/dist/antigravity-hook.js +1039 -198
  3. package/dist/antigravity-statusline.js +185 -11
  4. package/dist/antigravity-stop-hook.js +1026 -163
  5. package/dist/claude-hook.js +1039 -198
  6. package/dist/claude-sessionstart-hook.js +1123 -190
  7. package/dist/claude-stop-hook.js +1026 -163
  8. package/dist/cline.js +749 -209
  9. package/dist/codex-hook.js +1039 -198
  10. package/dist/codex-sessionstart-hook.js +1123 -190
  11. package/dist/codex-stop-hook.js +1026 -163
  12. package/dist/copilot-hook.js +1039 -198
  13. package/dist/copilot-sessionstart-hook.js +1123 -190
  14. package/dist/copilot-stop-hook.js +1026 -163
  15. package/dist/cursor-hook.js +1039 -198
  16. package/dist/cursor-sessionstart-hook.js +1123 -190
  17. package/dist/cursor-stop-hook.js +1026 -163
  18. package/dist/daemon-start.js +154 -5
  19. package/dist/dcode-hook.js +1039 -198
  20. package/dist/dcode-sessionstart-hook.js +1123 -190
  21. package/dist/dcode-stop-hook.js +1026 -163
  22. package/dist/deepen.js +437 -105
  23. package/dist/devin-hook.js +1039 -198
  24. package/dist/devin-sessionstart-hook.js +1123 -190
  25. package/dist/devin-stop-hook.js +1026 -163
  26. package/dist/droid-hook.js +1039 -198
  27. package/dist/droid-sessionstart-hook.js +1123 -190
  28. package/dist/droid-stop-hook.js +1026 -163
  29. package/dist/dsh.js +750 -210
  30. package/dist/grok-hook.js +1039 -198
  31. package/dist/grok-sessionstart-hook.js +1123 -190
  32. package/dist/grok-stop-hook.js +1026 -163
  33. package/dist/hindsight-seed.js +157 -8
  34. package/dist/index.js +749 -209
  35. package/dist/installer.js +1233 -366
  36. package/dist/kilo.js +749 -209
  37. package/dist/kimi-hook.js +3909 -0
  38. package/dist/kimi-sessionstart-hook.js +4650 -0
  39. package/dist/kimi-stop-hook.js +4218 -0
  40. package/dist/mcp-server.js +373 -71
  41. package/dist/opencode2.js +778 -209
  42. package/dist/pi.js +754 -211
  43. package/dist/prime-agent.js +754 -211
  44. package/dist/qwen-hook.js +1039 -198
  45. package/dist/qwen-sessionstart-hook.js +1123 -190
  46. package/dist/qwen-stop-hook.js +1026 -163
  47. package/dist/status.js +333 -59
  48. package/dist/traecode-hook.js +3909 -0
  49. package/dist/traecode-sessionstart-hook.js +4650 -0
  50. package/dist/traecode-stop-hook.js +4218 -0
  51. package/dist/zcode-hook.js +1039 -198
  52. package/dist/zcode-sessionstart-hook.js +1123 -190
  53. package/dist/zcode-stop-hook.js +1026 -163
  54. package/package.json +15 -11
  55. package/plugin.json +1 -1
  56. package/skill/SKILL.md +241 -48
package/dist/deepen.js CHANGED
@@ -2,7 +2,6 @@
2
2
 
3
3
  // src/deepen.ts
4
4
  import { execFileSync as execFileSync3 } from "child_process";
5
- import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
6
5
  import { tmpdir as tmpdir2 } from "os";
7
6
  import { join as join10 } from "path";
8
7
 
@@ -273,13 +272,13 @@ function isWithin(directory, configured) {
273
272
  function mapLookup(map, directory) {
274
273
  const cwd = normalize(directory);
275
274
  let best;
276
- for (const [dir, bank] of Object.entries(map)) {
275
+ for (const [dir, value] of Object.entries(map)) {
277
276
  const p = configuredDir(dir);
278
277
  if (isWithin(cwd, p)) {
279
- if (!best || p.length > best.len) best = { len: p.length, bank };
278
+ if (!best || p.length > best.len) best = { len: p.length, value };
280
279
  }
281
280
  }
282
- return best?.bank;
281
+ return best?.value;
283
282
  }
284
283
  function lookupDirectories(config, directory, sessionRoot = "") {
285
284
  const directories = [normalize(directory)];
@@ -303,6 +302,10 @@ function isOptedIn(config, directory) {
303
302
  const pathMap = config.mapPathToBank;
304
303
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
305
304
  }
305
+ function pathSection(config, paths, directory) {
306
+ if (!directory || !paths) return void 0;
307
+ return lookupDirectories(config, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
308
+ }
306
309
  function mappedBank(config, directory, sessionRoot) {
307
310
  const pathMap = config.mapPathToBank;
308
311
  if (!directory || !pathMap) return void 0;
@@ -357,13 +360,15 @@ var CONVERSATION_MISSION = `You are ingesting a developer conversation as a JSON
357
360
  var REFLECT_MISSION = "You are a debugging assistant with the project's past decisions in memory (git rationale and developer chats). Given a bug's SYMPTOM, find the past decision whose rationale explains the ROOT CAUSE \u2014 not one that merely shares vocabulary. Answer with the PRECISE fix: state the EXACT rule and the LITERAL values, identifiers, strings, numbers, or set members that were decided \u2014 quote them VERBATIM, never paraphrase, generalize, or omit them (give the actual decided value, not 'the project standard'). If memories CONFLICT on the same rule, the LATEST decision wins \u2014 prefer facts that explicitly amend or supersede an earlier one, state the superseded rule as no longer in effect, and never present it as the fix. Name the function/file to change and cite the REF-ID(s). If NOTHING in memory genuinely explains THIS symptom, say exactly that in one short sentence \u2014 a wrong-but-confident nearest match is worse than an honest miss; never stretch an unrelated decision to fit.";
358
361
  var DOCUMENT_MISSION = "You are ingesting a standalone document (notes, docs, or structural findings). Extract the concrete facts, concepts, and structure it describes.";
359
362
  var OBSERVATIONS_MISSION = "Consolidate durable knowledge about THIS codebase \u2014 recurring patterns, conventions, module responsibilities, and how components relate \u2014 from the ingested commits and conversations. Favor stable structural understanding over one-off details. When a new fact contradicts or supersedes an existing observation, UPDATE that observation to reflect the current state rather than creating a sibling alongside it; note that the rule was revised and when, so the superseded version is visible as history rather than as a competing claim.";
363
+ var RETAIN_EXTRACTION_MODES = ["concise", "verbose", "verbatim", "chunks"];
364
+ var DEFAULT_RETAIN_EXTRACTION_MODE = "concise";
360
365
  var RETAIN_STRATEGIES = {
361
- git: { retain_mission: GIT_MISSION, retain_extraction_mode: "verbose" },
366
+ git: { retain_mission: GIT_MISSION, retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE },
362
367
  // ONE big aggregated document (last N commit messages, no diffs) -> a larger chunk size so it stays
363
368
  // in as few chunks as possible and the extractor sees the whole history arc at once.
364
369
  gitlog: {
365
370
  retain_mission: GITLOG_MISSION,
366
- retain_extraction_mode: "verbose",
371
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
367
372
  retain_chunk_size: 12e3
368
373
  },
369
374
  // ONE strategy for ALL developer conversations — backfilled decision chats and live working
@@ -374,15 +379,15 @@ var RETAIN_STRATEGIES = {
374
379
  // the consolidation layer.
375
380
  conversation: {
376
381
  retain_mission: CONVERSATION_MISSION,
377
- retain_extraction_mode: "verbose",
382
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
378
383
  retain_chunk_size: 12e3
379
384
  },
380
385
  // Structural documents (e.g. the codebase survey's ingested findings) aren't dialogue — the
381
- // chat strategy's "final decision vs rejected proposal" extraction doesn't apply. Verbose mode
382
- // with a bigger chunk size (documents can run long) captures the concrete facts/structure instead.
386
+ // chat strategy's "final decision vs rejected proposal" extraction doesn't apply. A bigger chunk
387
+ // size (documents can run long) keeps the concrete facts/structure together instead.
383
388
  document: {
384
389
  retain_mission: DOCUMENT_MISSION,
385
- retain_extraction_mode: "verbose",
390
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
386
391
  retain_chunk_size: 12e3
387
392
  },
388
393
  // Codebase-SURVEY lifecycle documents, ONE strategy with conditional rules: the survey's
@@ -455,9 +460,22 @@ var PAGE_TAXONOMY = [
455
460
  tags: ["knowledge:feature-work"]
456
461
  }
457
462
  ];
458
- function pagesFor(project) {
463
+ var PAGE_NAMES = PAGE_TAXONOMY.map((page) => page.name);
464
+ function pagesFor(project, pages = {}, customPages = {}) {
459
465
  const scope = pageScopeRule(project);
460
- return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
466
+ const byName = new Map(
467
+ Object.entries(pages).map(([name, override]) => [name.trim().toLowerCase(), override])
468
+ );
469
+ const out = [];
470
+ for (const page of PAGE_TAXONOMY) {
471
+ const override = byName.get(page.name.toLowerCase());
472
+ if (override === false) continue;
473
+ out.push({ ...page, source_query: (override?.source_query || page.source_query) + scope });
474
+ }
475
+ for (const [name, page] of Object.entries(customPages)) {
476
+ out.push({ name: name.trim(), source_query: page.source_query + scope, tags: page.tags ?? [] });
477
+ }
478
+ return out;
461
479
  }
462
480
  var PAGE_MAX_TOKENS = 4096;
463
481
  var PAGE_TAGS_MATCH = "all";
@@ -540,7 +558,7 @@ var CODING_BANK_TEMPLATE = {
540
558
  enable_observations: true,
541
559
  observations_mission: OBSERVATIONS_MISSION,
542
560
  retain_mission: GIT_MISSION,
543
- retain_extraction_mode: "verbose",
561
+ retain_extraction_mode: DEFAULT_RETAIN_EXTRACTION_MODE,
544
562
  retain_default_strategy: "git",
545
563
  retain_strategies: RETAIN_STRATEGIES,
546
564
  entity_labels: [KNOWLEDGE_LABELS],
@@ -548,12 +566,17 @@ var CODING_BANK_TEMPLATE = {
548
566
  }
549
567
  };
550
568
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
569
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
570
+ "retain_strategies",
571
+ "entity_labels",
572
+ "retain_extraction_mode"
573
+ ];
551
574
  function isSet(v) {
552
575
  if (v === null || v === void 0) return false;
553
576
  if (typeof v === "string") return v.trim() !== "";
554
577
  return true;
555
578
  }
556
- function codingBankManifest(overrides) {
579
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
557
580
  const current2 = overrides ?? {};
558
581
  const template = CODING_BANK_TEMPLATE.bank;
559
582
  const bank = {};
@@ -562,20 +585,30 @@ function codingBankManifest(overrides) {
562
585
  bank.enable_observations = template.enable_observations;
563
586
  bank.observations_mission = template.observations_mission;
564
587
  bank.retain_mission = template.retain_mission;
565
- bank.retain_extraction_mode = template.retain_extraction_mode;
588
+ bank.retain_extraction_mode = mode;
566
589
  }
567
590
  if (!isSet(current2.retain_default_strategy))
568
591
  bank.retain_default_strategy = template.retain_default_strategy;
569
592
  if (!isSet(current2.entities_allow_free_form))
570
593
  bank.entities_allow_free_form = template.entities_allow_free_form;
571
594
  const strategies = current2.retain_strategies && typeof current2.retain_strategies === "object" ? current2.retain_strategies : {};
572
- const missing = Object.entries(template.retain_strategies).filter(([n]) => !(n in strategies));
573
- if (missing.length > 0)
574
- bank.retain_strategies = { ...strategies, ...Object.fromEntries(missing) };
595
+ const updates = {};
596
+ for (const [name, def] of Object.entries(template.retain_strategies)) {
597
+ const synced = def.retain_extraction_mode === "custom" ? {} : { retain_extraction_mode: mode };
598
+ const have = strategies[name];
599
+ if (!have || typeof have !== "object") updates[name] = { ...def, ...synced };
600
+ else if ("retain_extraction_mode" in synced && have.retain_extraction_mode !== mode)
601
+ updates[name] = { ...have, ...synced };
602
+ }
603
+ if (Object.keys(updates).length > 0) bank.retain_strategies = { ...strategies, ...updates };
575
604
  const labels = Array.isArray(current2.entity_labels) ? current2.entity_labels : [];
576
605
  const [knowledgeGroup] = template.entity_labels;
577
606
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
578
607
  bank.entity_labels = [...labels, knowledgeGroup];
608
+ for (const [key, value] of Object.entries(defaults)) {
609
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
610
+ bank[key] = value;
611
+ }
579
612
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
580
613
  }
581
614
 
@@ -643,6 +676,14 @@ var KnowledgePagesUnavailableError = class extends Error {
643
676
  this.name = "KnowledgePagesUnavailableError";
644
677
  }
645
678
  };
679
+ async function isEndpointMissing(r) {
680
+ try {
681
+ const j = await r.json();
682
+ return String(j?.detail ?? "").trim().toLowerCase() === "not found";
683
+ } catch {
684
+ return true;
685
+ }
686
+ }
646
687
  var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
647
688
  var ReflectError = class extends Error {
648
689
  constructor(message, status, timedOut, options) {
@@ -661,9 +702,28 @@ var ReflectError = class extends Error {
661
702
  }
662
703
  };
663
704
  var DEFAULT_MAX_PARALLEL_RETAINS = 10;
705
+ var DEFAULT_PAGE_SEARCH_LIMIT = 10;
706
+ var DEFAULT_RECALL_OPTIONS = {
707
+ types: ["observation"],
708
+ budget: "low",
709
+ max_tokens: 2e3,
710
+ include: { entities: null }
711
+ };
664
712
  var POLL_CYCLE_MS = 5e3;
665
713
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
666
714
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
715
+ function shapePage(page) {
716
+ const p = page ?? {};
717
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
718
+ return {
719
+ id: p.id,
720
+ name: p.name,
721
+ ...p.description ? { description: p.description } : {},
722
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
723
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
724
+ body
725
+ };
726
+ }
667
727
  var HindsightClient = class {
668
728
  apiUrl;
669
729
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -681,6 +741,8 @@ var HindsightClient = class {
681
741
  log;
682
742
  maxParallelRetains;
683
743
  observationScopes;
744
+ pageSearchLimit;
745
+ recallOptions;
684
746
  constructor(o) {
685
747
  this.apiUrl = o.apiUrl.replace(/\/$/, "");
686
748
  this.token = o.apiToken;
@@ -691,13 +753,18 @@ var HindsightClient = class {
691
753
  });
692
754
  this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
693
755
  this.observationScopes = o.observationScopes ?? DEFAULT_OBSERVATION_SCOPES;
756
+ this.pageSearchLimit = o.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT;
757
+ this.recallOptions = { ...DEFAULT_RECALL_OPTIONS, ...o.recallOptions };
694
758
  }
695
759
  /** The credential in use, for diagnostics. Never log or report the VALUE — booleans only. */
696
760
  get apiToken() {
697
761
  return this.token;
698
762
  }
699
763
  headers() {
700
- const h = { "Content-Type": "application/json" };
764
+ const h = {
765
+ "Content-Type": "application/json",
766
+ "Accept-Encoding": "identity"
767
+ };
701
768
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
702
769
  return h;
703
770
  }
@@ -805,6 +872,23 @@ var HindsightClient = class {
805
872
  return false;
806
873
  }
807
874
  }
875
+ /**
876
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
877
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
878
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
879
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
880
+ */
881
+ async supportsAppendRetain() {
882
+ if (!await this.supportsIdempotentRetain()) return false;
883
+ try {
884
+ const r = await this.req("GET", this.bankUrl("/config"));
885
+ if (!r.ok) return true;
886
+ const j = await r.json();
887
+ return j.config?.store_document_text !== false;
888
+ } catch {
889
+ return true;
890
+ }
891
+ }
808
892
  /**
809
893
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
810
894
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -830,9 +914,28 @@ var HindsightClient = class {
830
914
  }
831
915
  return ids;
832
916
  }
917
+ /**
918
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
919
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
920
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
921
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
922
+ */
923
+ async documentTags(documentId) {
924
+ const limit = 100;
925
+ for (let offset = 0; ; offset += limit) {
926
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
927
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
928
+ const j = await r.json();
929
+ const items = j.items ?? [];
930
+ const hit = items.find((it) => it.id === documentId);
931
+ if (hit) return hit.tags ?? [];
932
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
933
+ }
934
+ }
833
935
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
834
936
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
835
- * idempotent and strictly ADDITIVE — nothing the bank already says is overwritten (#3927) — so
937
+ * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
938
+ * extraction mode of the plugin's own strategies, which follows its config (#4560) — so
836
939
  * the deepen engine can re-run this every pass. Creates the bank if missing; legacy servers
837
940
  * continue with the template-only path.
838
941
  *
@@ -848,7 +951,11 @@ var HindsightClient = class {
848
951
  if (opts.manage === false) {
849
952
  this.log(`[bank] manageBankConfig: false \u2014 leaving ${this.bank}'s configuration alone`);
850
953
  } else {
851
- const manifest = codingBankManifest(opts.reset ? void 0 : await this.readBankOverrides());
954
+ const manifest = codingBankManifest(
955
+ opts.reset ? void 0 : await this.readBankOverrides(),
956
+ opts.extractionMode,
957
+ opts.defaults
958
+ );
852
959
  if (!manifest) {
853
960
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
854
961
  } else {
@@ -856,7 +963,7 @@ var HindsightClient = class {
856
963
  this.log(`[bank] applied to ${this.bank}: ${Object.keys(manifest.bank).sort().join(", ")}`);
857
964
  }
858
965
  }
859
- await this.seedPages(opts.pageTrigger);
966
+ await this.seedPages(opts.pageTrigger, opts.pages, opts.customPages);
860
967
  }
861
968
  /**
862
969
  * This bank's own config OVERRIDES, or undefined when there are none to read.
@@ -972,20 +1079,22 @@ var HindsightClient = class {
972
1079
  }
973
1080
  }
974
1081
  /**
975
- * Raw recall restricted to consolidated observations — no LLM in the loop, so it still answers
976
- * when reflect's synthesis times out or 5xxs. Returns the observation texts in rank order.
1082
+ * Raw recall with no LLM in the loop, so it still answers when reflect's synthesis times out or
1083
+ * 5xxs. The body is `recallOptions` (consolidated observations by default) — a bank that grows
1084
+ * no observations widens it rather than getting nothing back. Returns the texts in rank order.
1085
+ *
1086
+ * The name predates `recallOptions` (the observation type used to be hardcoded here) and is
1087
+ * kept deliberately: this is the client's published surface, so renaming it would break
1088
+ * importers for a cosmetic gain. The doc above is the contract, not the name.
977
1089
  */
978
1090
  async recallObservations(query, opts) {
979
1091
  const r = await this.req(
980
1092
  "POST",
981
1093
  this.bankUrl("/memories/recall"),
982
- {
983
- query,
984
- types: ["observation"],
985
- budget: "low",
986
- max_tokens: opts.maxTokens,
987
- include: { entities: null }
988
- },
1094
+ // `query` is applied AFTER the spread: everything else is the caller's to override, but a
1095
+ // config that could replace the goal with a fixed string would silently recall for the
1096
+ // wrong question on every turn.
1097
+ { ...this.recallOptions, query },
989
1098
  [],
990
1099
  opts.timeoutMs
991
1100
  );
@@ -993,6 +1102,19 @@ var HindsightClient = class {
993
1102
  const j = await r.json();
994
1103
  return (j.results ?? []).map((x) => (x.text ?? "").trim()).filter(Boolean);
995
1104
  }
1105
+ /**
1106
+ * Latch `knowledgePagesSupported = false` iff this response really means the endpoint is absent.
1107
+ * Returns whether it latched. A bank-not-found 404 is NOT a capability verdict — it is the
1108
+ * expected answer before the bank's first retain — so it must never cache a negative (#4607).
1109
+ *
1110
+ * Only 404 is tested: `req` throws on every other non-ok status it was not told to tolerate, so
1111
+ * the 405/501 this used to check for never reach a caller in the first place.
1112
+ */
1113
+ async pagesUnsupported(r) {
1114
+ if (r.status !== 404 || !await isEndpointMissing(r)) return false;
1115
+ this.knowledgePagesSupported = false;
1116
+ return true;
1117
+ }
996
1118
  /**
997
1119
  * The bank's knowledge-base tree (folders + pages, nested). The tree carries names, source
998
1120
  * queries and staleness but NOT synthesized content, so it is cheap enough to poll.
@@ -1000,10 +1122,8 @@ var HindsightClient = class {
1000
1122
  async tree() {
1001
1123
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1002
1124
  const r = await this.req("GET", this.bankUrl("/knowledge-base/tree"));
1003
- if ([404, 405, 501].includes(r.status)) {
1004
- this.knowledgePagesSupported = false;
1005
- throw new KnowledgePagesUnavailableError();
1006
- }
1125
+ if (await this.pagesUnsupported(r)) throw new KnowledgePagesUnavailableError();
1126
+ if (r.status === 404) return [];
1007
1127
  this.knowledgePagesSupported = true;
1008
1128
  try {
1009
1129
  return (await r.json()).roots ?? [];
@@ -1040,8 +1160,8 @@ var HindsightClient = class {
1040
1160
  return { items };
1041
1161
  }
1042
1162
  /**
1043
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
1044
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
1163
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
1164
+ * the body arrives once. The endpoint omits the internal reflect trace that built
1045
1165
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
1046
1166
  * token cap.
1047
1167
  */
@@ -1052,25 +1172,28 @@ var HindsightClient = class {
1052
1172
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
1053
1173
  );
1054
1174
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
1055
- return await r.json();
1175
+ return shapePage(await r.json());
1056
1176
  }
1057
1177
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1058
1178
  * Returns page-level hits with a relevance snippet — the real search behind
1059
1179
  * hindsight_search_knowledge_pages. */
1060
- async searchKnowledgePages(query, limit = 3, timeoutMs) {
1180
+ async searchKnowledgePages(query, opts = {}) {
1061
1181
  if (this.knowledgePagesSupported === false) throw new KnowledgePagesUnavailableError();
1062
- const q = `?q=${encodeURIComponent(query)}&limit=${limit}`;
1182
+ const q = `?q=${encodeURIComponent(query)}&limit=${opts.limit ?? this.pageSearchLimit}`;
1063
1183
  const r = await this.req(
1064
1184
  "GET",
1065
1185
  this.bankUrl(`/knowledge-base/search${q}`),
1066
1186
  void 0,
1067
1187
  [],
1068
- timeoutMs
1188
+ opts.timeoutMs
1069
1189
  );
1190
+ if (await this.pagesUnsupported(r)) throw new KnowledgePagesUnavailableError();
1191
+ if (r.status === 404) return [];
1070
1192
  const j = await r.json();
1071
1193
  return (j.results ?? []).map((x) => ({
1072
1194
  id: x.id,
1073
1195
  name: x.name,
1196
+ ...x.source_query ? { source_query: x.source_query } : {},
1074
1197
  snippet: x.snippet ?? "",
1075
1198
  score: x.score ?? 0
1076
1199
  }));
@@ -1086,8 +1209,8 @@ var HindsightClient = class {
1086
1209
  * `source_query` re-syncs onto the live page instead of orphaning its synthesized content —
1087
1210
  * which is how `pageScopeRule`'s repo name reaches banks seeded by an earlier version.
1088
1211
  */
1089
- async seedPages(pageTrigger = buildPageTrigger()) {
1090
- const pages = pagesFor(this.project ?? this.bank);
1212
+ async seedPages(pageTrigger = buildPageTrigger(), pagesConfig = {}, customPages = {}) {
1213
+ const pages = pagesFor(this.project ?? this.bank, pagesConfig, customPages);
1091
1214
  const existing = /* @__PURE__ */ new Map();
1092
1215
  let roots;
1093
1216
  try {
@@ -1104,6 +1227,7 @@ var HindsightClient = class {
1104
1227
  }
1105
1228
  let created = 0;
1106
1229
  let updated = 0;
1230
+ let vanished = 0;
1107
1231
  for (const page of pages) {
1108
1232
  const hit = existing.get(page.name.toLowerCase());
1109
1233
  const body = {
@@ -1117,13 +1241,16 @@ var HindsightClient = class {
1117
1241
  };
1118
1242
  if (!hit) {
1119
1243
  const r = await this.req("POST", this.bankUrl("/knowledge-base/pages"), body, [409]);
1120
- if ([404, 405, 501].includes(r.status)) {
1121
- this.knowledgePagesSupported = false;
1244
+ if (await this.pagesUnsupported(r)) {
1122
1245
  this.log(
1123
1246
  `[bank] knowledge pages unavailable on ${this.apiUrl}; continuing without pages`
1124
1247
  );
1125
1248
  return;
1126
1249
  }
1250
+ if (r.status === 404) {
1251
+ this.log(`[bank] ${this.bank} does not exist yet; pages seed on the next session`);
1252
+ return;
1253
+ }
1127
1254
  if (r.status !== 409) created++;
1128
1255
  } else {
1129
1256
  const sourceDrift = hit.description !== page.source_query;
@@ -1133,6 +1260,9 @@ var HindsightClient = class {
1133
1260
  if (sourceDrift) {
1134
1261
  patch.source_query = page.source_query;
1135
1262
  patch.tags = page.tags;
1263
+ this.log(
1264
+ `[bank] re-syncing "${page.name}" to its configured source_query \u2014 set pages[${JSON.stringify(page.name)}].source_query to keep your own wording`
1265
+ );
1136
1266
  }
1137
1267
  if (triggerDrift) patch.trigger = pageTriggerPatch(body.trigger);
1138
1268
  const r = await this.req(
@@ -1140,19 +1270,22 @@ var HindsightClient = class {
1140
1270
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
1141
1271
  patch
1142
1272
  );
1143
- if ([404, 405, 501].includes(r.status)) {
1144
- this.knowledgePagesSupported = false;
1273
+ if (await this.pagesUnsupported(r)) {
1145
1274
  this.log(
1146
1275
  `[bank] knowledge pages unavailable on ${this.apiUrl}; continuing without pages`
1147
1276
  );
1148
1277
  return;
1149
1278
  }
1279
+ if (r.status === 404) {
1280
+ vanished++;
1281
+ continue;
1282
+ }
1150
1283
  updated++;
1151
1284
  }
1152
1285
  }
1153
1286
  const initiatives = await this.resyncInitiativeTriggers(roots, pageTrigger);
1154
1287
  this.log(
1155
- `[bank] knowledge pages seeded on ${this.bank} (scoped to ${this.project ?? this.bank}): ${created} created, ${updated} re-synced, ${pages.length - created - updated} unchanged` + (initiatives ? `, ${initiatives} initiative pages re-synced` : "")
1288
+ `[bank] knowledge pages seeded on ${this.bank} (scoped to ${this.project ?? this.bank}): ${created} created, ${updated} re-synced, ${pages.length - created - updated - vanished} unchanged` + (vanished ? `, ${vanished} deleted under us` : "") + (initiatives ? `, ${initiatives} initiative pages re-synced` : "")
1156
1289
  );
1157
1290
  }
1158
1291
  /**
@@ -1181,7 +1314,7 @@ var HindsightClient = class {
1181
1314
  this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(page.id)}`),
1182
1315
  { trigger: pageTriggerPatch(desired) }
1183
1316
  );
1184
- if ([404, 405, 501].includes(r.status)) break;
1317
+ if (r.status === 404) continue;
1185
1318
  updated++;
1186
1319
  }
1187
1320
  return updated;
@@ -1281,13 +1414,15 @@ async function ingestChats(client, sessions, opts = {}) {
1281
1414
  const id = s.id || `s${i}`;
1282
1415
  const stamp = opts.stampFor?.(id);
1283
1416
  const sessBase = NOW - (sessions.length - 1 - i) * 36e5;
1284
- const baseIso = new Date(sessBase).toISOString();
1417
+ const sourceTs = (s.turns || []).map((t) => t.timestamp).find((v) => typeof v === "string" && !Number.isNaN(Date.parse(v)));
1418
+ const anchorMs = sourceTs ? Date.parse(sourceTs) : sessBase;
1419
+ const baseIso = sourceTs ?? new Date(sessBase).toISOString();
1285
1420
  const turns = withRefId(
1286
1421
  `chat:${id}`,
1287
1422
  (s.turns || []).map((t, j) => ({
1288
1423
  role: t.role,
1289
1424
  content: t.text,
1290
- timestamp: t.timestamp || new Date(sessBase + (j + 1) * 6e4).toISOString()
1425
+ timestamp: t.timestamp || new Date(anchorMs + (j + 1) * 6e4).toISOString()
1291
1426
  })),
1292
1427
  baseIso
1293
1428
  );
@@ -1349,7 +1484,65 @@ function resolvePageTrigger(raw) {
1349
1484
  );
1350
1485
  return { type: "cron", cron: DEFAULT_PAGE_TRIGGER_CRON };
1351
1486
  }
1487
+ function resolvePages(raw) {
1488
+ const value = raw;
1489
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1490
+ const out = {};
1491
+ for (const [name, entry] of Object.entries(value)) {
1492
+ if (!PAGE_NAMES.some((known) => known.toLowerCase() === name.trim().toLowerCase())) {
1493
+ log.warn(
1494
+ "config",
1495
+ `ignoring pages[${JSON.stringify(name)}] \u2014 no seeded page has that name; expected one of: ${PAGE_NAMES.join(", ")}`
1496
+ );
1497
+ continue;
1498
+ }
1499
+ if (entry === false) {
1500
+ out[name] = false;
1501
+ continue;
1502
+ }
1503
+ const query = entry && typeof entry === "object" && !Array.isArray(entry) ? entry.source_query : void 0;
1504
+ if (typeof query === "string" && query.trim()) {
1505
+ out[name] = { source_query: query };
1506
+ continue;
1507
+ }
1508
+ log.warn(
1509
+ "config",
1510
+ `ignoring pages[${JSON.stringify(name)}]=${JSON.stringify(entry)} \u2014 expected false, or {"source_query": "<your question>"}`
1511
+ );
1512
+ }
1513
+ return out;
1514
+ }
1515
+ function resolveCustomPages(raw) {
1516
+ const value = raw;
1517
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1518
+ const out = {};
1519
+ for (const [rawName, entry] of Object.entries(value)) {
1520
+ const name = rawName.trim();
1521
+ if (!name) continue;
1522
+ if (PAGE_NAMES.some((known) => known.toLowerCase() === name.toLowerCase())) {
1523
+ log.warn(
1524
+ "config",
1525
+ `ignoring customPages[${JSON.stringify(rawName)}] \u2014 that is a seeded page; reword it under \`pages\` instead`
1526
+ );
1527
+ continue;
1528
+ }
1529
+ const query = entry && typeof entry === "object" && !Array.isArray(entry) ? entry.source_query : void 0;
1530
+ if (typeof query !== "string" || !query.trim()) {
1531
+ log.warn(
1532
+ "config",
1533
+ `ignoring customPages[${JSON.stringify(rawName)}]=${JSON.stringify(entry)} \u2014 expected {"source_query": "<your question>"}`
1534
+ );
1535
+ continue;
1536
+ }
1537
+ const rawTags = entry.tags;
1538
+ const tags = Array.isArray(rawTags) ? rawTags.filter((t) => typeof t === "string" && t.trim() !== "") : [];
1539
+ out[name] = tags.length ? { source_query: query, tags } : { source_query: query };
1540
+ }
1541
+ return out;
1542
+ }
1543
+ var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
1352
1544
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
1545
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
1353
1546
  var REFLECT_BUDGETS = ["low", "mid", "high"];
1354
1547
  function resolveReflectBudget(raw) {
1355
1548
  const value = raw.reflectBudget;
@@ -1376,6 +1569,31 @@ function resolveObservationScopes(raw) {
1376
1569
  }
1377
1570
  return DEFAULT_OBSERVATION_SCOPES;
1378
1571
  }
1572
+ function resolveDefaultBankConfig(raw) {
1573
+ const value = raw;
1574
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1575
+ const out = {};
1576
+ for (const [key, v] of Object.entries(value)) {
1577
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
1578
+ log.warn(
1579
+ "config",
1580
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
1581
+ );
1582
+ continue;
1583
+ }
1584
+ out[key] = v;
1585
+ }
1586
+ return out;
1587
+ }
1588
+ var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
1589
+ function resolveAutoInject(raw) {
1590
+ if (raw.autoReflect !== void 0) {
1591
+ const replacement = raw.autoReflect === false ? "none" : "reflect";
1592
+ log.warn("config", `autoReflect is deprecated \u2014 use autoInject: "${replacement}" instead`);
1593
+ }
1594
+ if (AUTO_INJECT_MODES.includes(raw.autoInject)) return raw.autoInject;
1595
+ return raw.autoReflect === false ? "none" : "reflect";
1596
+ }
1379
1597
  function resolveConfig(raw = {}) {
1380
1598
  const serverMode = ["cloud", "self-hosted", "daemon"].includes(raw.serverMode) ? raw.serverMode : "cloud";
1381
1599
  const apiPort = raw.apiPort || DEFAULT_DAEMON_PORT;
@@ -1405,17 +1623,31 @@ function resolveConfig(raw = {}) {
1405
1623
  retainSessions: raw.retainSessions ?? true,
1406
1624
  // write sessions back by default, every harness
1407
1625
  manageBankConfig: raw.manageBankConfig ?? true,
1626
+ retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
1627
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
1408
1628
  maxParallelRetains: raw.maxParallelRetains || 10,
1409
- reflectTimeoutMs: raw.reflectTimeoutMs || 12e4,
1629
+ reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
1410
1630
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
1411
1631
  // reflect already set), but never let it LOWER the tool below the default — a short window is
1412
1632
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
1413
1633
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
1634
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
1414
1635
  reflectBudget: resolveReflectBudget(raw),
1415
- autoReflect: raw.autoReflect ?? true,
1416
- pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 10,
1636
+ autoInject: resolveAutoInject(raw),
1637
+ pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
1638
+ // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
1639
+ // keys and reach the API as garbage, so it is rejected like any other non-object.
1640
+ recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
1641
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
1642
+ // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
1643
+ // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
1644
+ // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
1645
+ // with no wording change at all. The cost is the guide's ~2KB re-sent per turn, which caches.
1646
+ pageRefreshEveryTurns: raw.pageRefreshEveryTurns || 1,
1417
1647
  pageTriggerType: pageTrigger.type,
1418
1648
  pageTriggerCron: pageTrigger.cron,
1649
+ pages: resolvePages(raw.pages),
1650
+ customPages: resolveCustomPages(raw.customPages),
1419
1651
  autoSeed: raw.autoSeed ?? true,
1420
1652
  seedLimit: raw.seedLimit || DEFAULT_SEED_LIMIT,
1421
1653
  codebaseSurvey: raw.codebaseSurvey ?? true,
@@ -1426,11 +1658,15 @@ function resolveConfig(raw = {}) {
1426
1658
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
1427
1659
  // nested object cannot reach the API as a tag and fail the whole retain.
1428
1660
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
1661
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
1662
+ // the built-in default) from a configured value, and an empty context would strip the default.
1663
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
1429
1664
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
1430
1665
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
1431
1666
  ) : {},
1432
1667
  observationScopes: resolveObservationScopes(raw.observationScopes),
1433
1668
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
1669
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
1434
1670
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
1435
1671
  autoUpdate: raw.autoUpdate ?? true
1436
1672
  };
@@ -1447,7 +1683,12 @@ function readRaw(path) {
1447
1683
  }
1448
1684
  function mergeRaw(a, b) {
1449
1685
  const { harnesses: _drop, ...flat } = b;
1450
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
1686
+ return {
1687
+ ...a,
1688
+ ...flat,
1689
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
1690
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
1691
+ };
1451
1692
  }
1452
1693
  function applyLayer(raw, layer, harness) {
1453
1694
  let out = mergeRaw(raw, layer);
@@ -1478,7 +1719,11 @@ var ENV_KEYS = {
1478
1719
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
1479
1720
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
1480
1721
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
1722
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
1481
1723
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
1724
+ autoInject: "HINDSIGHT_AUTO_INJECT",
1725
+ pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
1726
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
1482
1727
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
1483
1728
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
1484
1729
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -1498,7 +1743,8 @@ var ENV_KEYS = {
1498
1743
  // Comma-separated, e.g. HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work". A LIST rather than
1499
1744
  // a map, so it flattens cleanly; its sibling retainMetadata stays file-only for the reason above.
1500
1745
  retainTags: "HINDSIGHT_RETAIN_TAGS",
1501
- manageBankConfig: "HINDSIGHT_MANAGE_BANK_CONFIG"
1746
+ manageBankConfig: "HINDSIGHT_MANAGE_BANK_CONFIG",
1747
+ retainExtractionMode: "HINDSIGHT_RETAIN_EXTRACTION_MODE"
1502
1748
  };
1503
1749
  var ENV_BOOLEANS = /* @__PURE__ */ new Set([
1504
1750
  "dynamicBankId",
@@ -1519,6 +1765,8 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
1519
1765
  "maxParallelRetains",
1520
1766
  "reflectTimeoutMs",
1521
1767
  "reflectToolTimeoutMs",
1768
+ "injectTimeoutMs",
1769
+ "pageSearchLimit",
1522
1770
  "pageRefreshEveryTurns",
1523
1771
  "seedLimit",
1524
1772
  "surveyBudgetUsd",
@@ -1566,15 +1814,25 @@ var BANK_OVERRIDE_EXCLUDED = [
1566
1814
  function applyBankConfig(cfg2, resolvedId, directory) {
1567
1815
  if (directory !== void 0 && !isOptedIn(cfg2, directory))
1568
1816
  return { cfg: { ...cfg2, disabled: true }, bankId: resolvedId };
1817
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg2, cfg2.paths, directory);
1818
+ if (byPath) {
1819
+ const { bank: _rename, ...rest } = overrideFields(byPath);
1820
+ cfg2 = { ...cfg2, ...resolvePartial(cfg2, rest) };
1821
+ }
1569
1822
  const section = cfg2.banks[resolvedId];
1570
1823
  if (!section) return { cfg: cfg2, bankId: resolvedId };
1571
- const safe = { ...section };
1572
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1573
- delete safe.banks;
1824
+ const safe = overrideFields(section);
1574
1825
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
1575
1826
  delete safe.bank;
1576
1827
  return { cfg: { ...cfg2, ...resolvePartial(cfg2, safe) }, bankId };
1577
1828
  }
1829
+ function overrideFields(section) {
1830
+ const safe = { ...section };
1831
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1832
+ delete safe.banks;
1833
+ delete safe.paths;
1834
+ return safe;
1835
+ }
1578
1836
  function resolvePartial(cfg2, patch) {
1579
1837
  const full = resolveConfig(patch);
1580
1838
  const out = {};
@@ -1582,6 +1840,17 @@ function resolvePartial(cfg2, patch) {
1582
1840
  if (key in full)
1583
1841
  out[key] = full[key];
1584
1842
  }
1843
+ if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
1844
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
1845
+ const conn = resolveConfig({
1846
+ serverMode: patch.serverMode ?? cfg2.serverMode,
1847
+ apiPort: patch.apiPort ?? cfg2.apiPort,
1848
+ apiUrl: patch.apiUrl ?? (cfg2.serverMode === "daemon" ? void 0 : cfg2.apiUrl)
1849
+ });
1850
+ out.serverMode = conn.serverMode;
1851
+ out.apiUrl = conn.apiUrl;
1852
+ out.apiPort = conn.apiPort;
1853
+ }
1585
1854
  return out;
1586
1855
  }
1587
1856
 
@@ -1590,11 +1859,15 @@ import { execFileSync } from "child_process";
1590
1859
  import { resolve as resolve2 } from "path";
1591
1860
  var US = "";
1592
1861
  var RS = "";
1862
+ var GITLOG_HEAD = "gitlog-head:";
1593
1863
  function git(repo, ...args) {
1594
1864
  return execFileSync("git", ["-C", repo, ...args], {
1595
1865
  encoding: "utf8",
1596
1866
  maxBuffer: 1 << 28,
1597
- windowsHide: true
1867
+ windowsHide: true,
1868
+ // execFileSync otherwise forwards failed git stderr into the host's TUI,
1869
+ // even when callers catch the error. Keep diagnostics on the error instead.
1870
+ stdio: ["ignore", "pipe", "pipe"]
1598
1871
  });
1599
1872
  }
1600
1873
  function repoNameOf(repo) {
@@ -1608,6 +1881,7 @@ function gitHeadSha(dir) {
1608
1881
  }
1609
1882
  }
1610
1883
  function commitsSince(dir, sinceSha) {
1884
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
1611
1885
  try {
1612
1886
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
1613
1887
  return Number.isFinite(n) ? n : null;
@@ -1706,7 +1980,7 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1706
1980
  ...stamp?.tags ?? [],
1707
1981
  "source:git",
1708
1982
  "source:git-log",
1709
- ...head ? [`gitlog-head:${head}`] : []
1983
+ ...head ? [`${GITLOG_HEAD}${head}`] : []
1710
1984
  ])
1711
1985
  ];
1712
1986
  await client.retain(
@@ -1732,12 +2006,20 @@ async function ingestGitLog(client, repo, opts = { limit: 300 }) {
1732
2006
  return 1;
1733
2007
  }
1734
2008
  }
2009
+ async function gitLogIsCurrent(client, repo, head) {
2010
+ const canonical2 = `gitlog:${repoNameOf(repo)}`;
2011
+ if ((await client.listDocumentIds(`${GITLOG_HEAD}${head}`, "all_strict")).has(canonical2))
2012
+ return true;
2013
+ const tags = await client.documentTags?.(canonical2) ?? [];
2014
+ return tags.some(
2015
+ (tag) => tag.startsWith(GITLOG_HEAD) && commitsSince(repo, tag.slice(GITLOG_HEAD.length)) === 0
2016
+ );
2017
+ }
1735
2018
  async function syncGitLog(client, repo, opts) {
1736
2019
  const log3 = opts.log ?? (() => {
1737
2020
  });
1738
2021
  const head = gitHeadSha(repo);
1739
- const canonical2 = `gitlog:${repoNameOf(repo)}`;
1740
- const current2 = head !== null && (await client.listDocumentIds(`gitlog-head:${head}`, "all_strict").catch(() => /* @__PURE__ */ new Set())).has(canonical2);
2022
+ const current2 = head !== null && await gitLogIsCurrent(client, repo, head).catch(() => false);
1741
2023
  if (current2) {
1742
2024
  log3("[gitlog] current with HEAD \u2014 skipping");
1743
2025
  return 0;
@@ -1769,6 +2051,70 @@ import {
1769
2051
  writeFileSync
1770
2052
  } from "fs";
1771
2053
  import { join as join8 } from "path";
2054
+ var LEASE_HEARTBEAT_MS = 5e3;
2055
+ var LEASE_STALE_MS = 3e4;
2056
+ function tryRename(from, to) {
2057
+ try {
2058
+ renameSync2(from, to);
2059
+ return true;
2060
+ } catch {
2061
+ return false;
2062
+ }
2063
+ }
2064
+ function releaseLease(lease2) {
2065
+ try {
2066
+ unlinkSync(join8(lease2.directory, lease2.owner));
2067
+ } catch {
2068
+ return;
2069
+ }
2070
+ try {
2071
+ rmdirSync(lease2.directory);
2072
+ } catch {
2073
+ }
2074
+ }
2075
+ function heartbeatLease(lease2) {
2076
+ try {
2077
+ const now = /* @__PURE__ */ new Date();
2078
+ utimesSync(join8(lease2.directory, lease2.owner), now, now);
2079
+ return true;
2080
+ } catch (error) {
2081
+ return error.code !== "ENOENT";
2082
+ }
2083
+ }
2084
+ function reclaimIfStale(directory, staleMs) {
2085
+ const owners = readdirSync(directory);
2086
+ if (owners.length === 0) {
2087
+ try {
2088
+ rmdirSync(directory);
2089
+ } catch {
2090
+ }
2091
+ return true;
2092
+ }
2093
+ if (owners.length !== 1) return false;
2094
+ const age = Date.now() - statSync2(join8(directory, owners[0])).mtimeMs;
2095
+ if (Math.abs(age) <= staleMs) return false;
2096
+ releaseLease({ directory, owner: owners[0] });
2097
+ return true;
2098
+ }
2099
+ function acquireLease(root, key, staleMs = LEASE_STALE_MS) {
2100
+ let staging;
2101
+ try {
2102
+ mkdirSync2(root, { recursive: true, mode: 448 });
2103
+ staging = mkdtempSync(join8(root, "claim-"));
2104
+ const owner = randomUUID();
2105
+ writeFileSync(join8(staging, owner), "", { flag: "wx", mode: 384 });
2106
+ const directory = join8(root, `survey-${key}.lock`);
2107
+ if (!tryRename(staging, directory)) {
2108
+ if (!reclaimIfStale(directory, staleMs)) return void 0;
2109
+ if (!tryRename(staging, directory)) return void 0;
2110
+ }
2111
+ return { directory, owner };
2112
+ } catch {
2113
+ return void 0;
2114
+ } finally {
2115
+ if (staging) rmSync(staging, { recursive: true, force: true });
2116
+ }
2117
+ }
1772
2118
 
1773
2119
  // src/core/survey.ts
1774
2120
  var SURVEY_DOC_IDS = [
@@ -1829,7 +2175,10 @@ var HARNESS_NAMES = [
1829
2175
  "factory-droid",
1830
2176
  // ZCode is a per-prompt HOOK host too, registered in its own CLI config
1831
2177
  // (~/.zcode/cli/config.json) under `hooks.events` — never the user's real Claude Code settings.
1832
- "zcode"
2178
+ "zcode",
2179
+ // TraeCode is a per-prompt HOOK host registered in ~/.trae-cn/hooks.json (see src/installer.ts).
2180
+ "traecode",
2181
+ "kimi-code"
1833
2182
  ];
1834
2183
  var HOOK_BINS = {
1835
2184
  "claude-code": "hindsight-claude-hook",
@@ -1842,7 +2191,9 @@ var HOOK_BINS = {
1842
2191
  "grok-build": "hindsight-grok-hook",
1843
2192
  "qwen-code": "hindsight-qwen-hook",
1844
2193
  "factory-droid": "hindsight-droid-hook",
1845
- zcode: "hindsight-zcode-hook"
2194
+ zcode: "hindsight-zcode-hook",
2195
+ traecode: "hindsight-traecode-hook",
2196
+ "kimi-code": "hindsight-kimi-hook"
1846
2197
  // more hook harnesses: add a HookSpec entry point (see src/cursor-hook.ts) + a registration here.
1847
2198
  };
1848
2199
  var PLUGIN_ENTRYPOINTS = {
@@ -1892,7 +2243,8 @@ function resolversFor(ctx) {
1892
2243
  function buildRetainStamp(cfg2, ctx) {
1893
2244
  const hasTags = Boolean(cfg2.retainTags?.length);
1894
2245
  const hasMetadata = Boolean(cfg2.retainMetadata && Object.keys(cfg2.retainMetadata).length);
1895
- if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
2246
+ const hasContext = Boolean(cfg2.retainContext?.trim());
2247
+ if (!hasTags && !hasMetadata && !hasContext) return { tags: [], metadata: {} };
1896
2248
  const base = resolversFor(ctx);
1897
2249
  const cache = /* @__PURE__ */ new Map();
1898
2250
  const resolvers = Object.fromEntries(
@@ -1916,12 +2268,12 @@ function buildRetainStamp(cfg2, ctx) {
1916
2268
  for (const [key, value] of Object.entries(cfg2.retainMetadata ?? {})) {
1917
2269
  metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
1918
2270
  }
1919
- return { tags, metadata };
2271
+ const context = hasContext ? applyTemplate(cfg2.retainContext, resolvers, "retainContext").trim() || void 0 : void 0;
2272
+ return { tags, metadata, context };
1920
2273
  }
1921
2274
 
1922
2275
  // src/deepen.ts
1923
2276
  var DIFF_BATCH = 50;
1924
- var LOCK_STALE_MS = 30 * 60 * 1e3;
1925
2277
  function arg(name, def) {
1926
2278
  const i = process.argv.indexOf(`--${name}`);
1927
2279
  if (i >= 0 && i + 1 < process.argv.length) return process.argv[i + 1];
@@ -1956,35 +2308,16 @@ var log2 = (m) => {
1956
2308
  console.log(`${(/* @__PURE__ */ new Date()).toISOString()} ${m}`);
1957
2309
  log.info("deepen", m);
1958
2310
  };
1959
- var LOCK_DIR = join10(tmpdir2(), "hindsight-coding-agent");
1960
- var LOCK = join10(LOCK_DIR, `deepen-${encodeURIComponent(FINAL_BANK ?? "")}.lock`);
1961
- function acquireLock() {
1962
- try {
1963
- const held = JSON.parse(readFileSync4(LOCK, "utf8"));
1964
- if (held.ts && Date.now() - held.ts < LOCK_STALE_MS) {
1965
- let holderAlive = false;
1966
- if (held.pid) {
1967
- try {
1968
- process.kill(held.pid, 0);
1969
- holderAlive = true;
1970
- } catch {
1971
- }
1972
- }
1973
- if (holderAlive) return false;
1974
- }
1975
- } catch {
1976
- }
1977
- try {
1978
- mkdirSync3(LOCK_DIR, { recursive: true });
1979
- writeFileSync2(LOCK, JSON.stringify({ pid: process.pid, ts: Date.now() }));
1980
- return true;
1981
- } catch {
1982
- return false;
1983
- }
2311
+ var LEASE_ROOT = join10(tmpdir2(), "hindsight-coding-agent", "deepen");
2312
+ var lease = acquireLease(LEASE_ROOT, encodeURIComponent(FINAL_BANK ?? ""));
2313
+ if (lease) {
2314
+ setInterval(() => {
2315
+ if (!heartbeatLease(lease)) process.exit(0);
2316
+ }, LEASE_HEARTBEAT_MS).unref();
1984
2317
  }
1985
2318
  async function main() {
1986
- if (!acquireLock()) {
1987
- log2(`deepen: another run holds the lock for ${FINAL_BANK} \u2014 nothing to do`);
2319
+ if (!lease) {
2320
+ log2(`deepen: another run holds the lease for ${FINAL_BANK} \u2014 nothing to do`);
1988
2321
  return;
1989
2322
  }
1990
2323
  const t0 = Date.now();
@@ -2017,7 +2350,11 @@ async function main() {
2017
2350
  });
2018
2351
  await client.configureBank({
2019
2352
  pageTrigger: buildPageTrigger(cfg),
2020
- manage: cfg.manageBankConfig
2353
+ pages: cfg.pages,
2354
+ customPages: cfg.customPages,
2355
+ manage: cfg.manageBankConfig,
2356
+ extractionMode: cfg.retainExtractionMode,
2357
+ defaults: cfg.defaultBankConfig
2021
2358
  });
2022
2359
  if (client.knowledgePagesSupported === false) {
2023
2360
  diag(harness.name, "knowledge_pages_unavailable", {
@@ -2053,7 +2390,8 @@ async function main() {
2053
2390
  const shas = execFileSync3(
2054
2391
  "git",
2055
2392
  ["-C", REPO, "rev-list", `-n`, String(DEEPEN_DIFF_TARGET), "HEAD"],
2056
- { encoding: "utf8", windowsHide: true }
2393
+ // `install` runs this with inherited stdio: an empty repo's HEAD error must not print.
2394
+ { encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }
2057
2395
  ).trim().split("\n").filter(Boolean).filter((sha) => !gitIds.has(`git:${sha}`)).slice(0, DIFF_BATCH);
2058
2396
  if (shas.length) {
2059
2397
  const repoName = repoNameOf(REPO);
@@ -2130,10 +2468,7 @@ async function main() {
2130
2468
  \u2705 deepen complete in ${((Date.now() - t0) / 1e3).toFixed(1)}s${failures ? ` (${failures} items failed to enqueue)` : ""}.`
2131
2469
  );
2132
2470
  } finally {
2133
- try {
2134
- unlinkSync2(LOCK);
2135
- } catch {
2136
- }
2471
+ releaseLease(lease);
2137
2472
  }
2138
2473
  }
2139
2474
  main().catch((e) => {
@@ -2142,9 +2477,6 @@ main().catch((e) => {
2142
2477
  error: describeError(e)
2143
2478
  });
2144
2479
  console.error("deepen failed:", e.message || e);
2145
- try {
2146
- unlinkSync2(LOCK);
2147
- } catch {
2148
- }
2480
+ if (lease) releaseLease(lease);
2149
2481
  process.exit(1);
2150
2482
  });