@vectorize-io/hindsight-coding-agents 0.7.0 → 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 +137 -13
  2. package/dist/antigravity-hook.js +711 -55
  3. package/dist/antigravity-statusline.js +68 -7
  4. package/dist/antigravity-stop-hook.js +771 -57
  5. package/dist/claude-hook.js +711 -55
  6. package/dist/claude-sessionstart-hook.js +789 -68
  7. package/dist/claude-stop-hook.js +771 -57
  8. package/dist/cline.js +295 -75
  9. package/dist/codex-hook.js +711 -55
  10. package/dist/codex-sessionstart-hook.js +789 -68
  11. package/dist/codex-stop-hook.js +771 -57
  12. package/dist/copilot-hook.js +711 -55
  13. package/dist/copilot-sessionstart-hook.js +789 -68
  14. package/dist/copilot-stop-hook.js +771 -57
  15. package/dist/cursor-hook.js +711 -55
  16. package/dist/cursor-sessionstart-hook.js +789 -68
  17. package/dist/cursor-stop-hook.js +771 -57
  18. package/dist/daemon-start.js +38 -1
  19. package/dist/dcode-hook.js +711 -55
  20. package/dist/dcode-sessionstart-hook.js +789 -68
  21. package/dist/dcode-stop-hook.js +771 -57
  22. package/dist/deepen.js +236 -61
  23. package/dist/devin-hook.js +711 -55
  24. package/dist/devin-sessionstart-hook.js +789 -68
  25. package/dist/devin-stop-hook.js +771 -57
  26. package/dist/droid-hook.js +711 -55
  27. package/dist/droid-sessionstart-hook.js +789 -68
  28. package/dist/droid-stop-hook.js +771 -57
  29. package/dist/dsh.js +296 -76
  30. package/dist/grok-hook.js +711 -55
  31. package/dist/grok-sessionstart-hook.js +789 -68
  32. package/dist/grok-stop-hook.js +771 -57
  33. package/dist/hindsight-seed.js +41 -4
  34. package/dist/index.js +295 -75
  35. package/dist/installer.js +1148 -303
  36. package/dist/kilo.js +295 -75
  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 +162 -33
  41. package/dist/opencode2.js +298 -76
  42. package/dist/pi.js +299 -75
  43. package/dist/prime-agent.js +299 -75
  44. package/dist/qwen-hook.js +711 -55
  45. package/dist/qwen-sessionstart-hook.js +789 -68
  46. package/dist/qwen-stop-hook.js +771 -57
  47. package/dist/status.js +132 -14
  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 +711 -55
  52. package/dist/zcode-sessionstart-hook.js +789 -68
  53. package/dist/zcode-stop-hook.js +771 -57
  54. package/package.json +15 -11
  55. package/plugin.json +1 -1
  56. package/skill/SKILL.md +70 -11
package/dist/cline.js CHANGED
@@ -309,13 +309,13 @@ function isWithin(directory, configured) {
309
309
  function mapLookup(map2, directory) {
310
310
  const cwd = normalize(directory);
311
311
  let best;
312
- for (const [dir, bank] of Object.entries(map2)) {
312
+ for (const [dir, value] of Object.entries(map2)) {
313
313
  const p = configuredDir(dir);
314
314
  if (isWithin(cwd, p)) {
315
- if (!best || p.length > best.len) best = { len: p.length, bank };
315
+ if (!best || p.length > best.len) best = { len: p.length, value };
316
316
  }
317
317
  }
318
- return best?.bank;
318
+ return best?.value;
319
319
  }
320
320
  function lookupDirectories(config2, directory, sessionRoot = "") {
321
321
  const directories = [normalize(directory)];
@@ -339,6 +339,10 @@ function isOptedIn(config2, directory) {
339
339
  const pathMap = config2.mapPathToBank;
340
340
  return Boolean(pathMap && directories.some((candidate) => mapLookup(pathMap, candidate)));
341
341
  }
342
+ function pathSection(config2, paths, directory) {
343
+ if (!directory || !paths) return void 0;
344
+ return lookupDirectories(config2, directory).map((candidate) => mapLookup(paths, candidate)).find((section) => section !== void 0);
345
+ }
342
346
  function mappedBank(config2, directory, sessionRoot) {
343
347
  const pathMap = config2.mapPathToBank;
344
348
  if (!directory || !pathMap) return void 0;
@@ -586,12 +590,17 @@ var CODING_BANK_TEMPLATE = {
586
590
  }
587
591
  };
588
592
  var MISSION_FIELDS = ["reflect_mission", "retain_mission", "observations_mission"];
593
+ var PLUGIN_GOVERNED_BANK_FIELDS = [
594
+ "retain_strategies",
595
+ "entity_labels",
596
+ "retain_extraction_mode"
597
+ ];
589
598
  function isSet(v) {
590
599
  if (v === null || v === void 0) return false;
591
600
  if (typeof v === "string") return v.trim() !== "";
592
601
  return true;
593
602
  }
594
- function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
603
+ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE, defaults = {}) {
595
604
  const current2 = overrides ?? {};
596
605
  const template = CODING_BANK_TEMPLATE.bank;
597
606
  const bank = {};
@@ -620,6 +629,10 @@ function codingBankManifest(overrides, mode = DEFAULT_RETAIN_EXTRACTION_MODE) {
620
629
  const [knowledgeGroup] = template.entity_labels;
621
630
  if (!labels.some((g) => g?.key === knowledgeGroup.key))
622
631
  bank.entity_labels = [...labels, knowledgeGroup];
632
+ for (const [key, value] of Object.entries(defaults)) {
633
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key) || !isSet(value) || isSet(current2[key])) continue;
634
+ bank[key] = value;
635
+ }
623
636
  return Object.keys(bank).length > 0 ? { version: "1", bank } : void 0;
624
637
  }
625
638
 
@@ -742,6 +755,18 @@ var DEFAULT_RECALL_OPTIONS = {
742
755
  var POLL_CYCLE_MS = 5e3;
743
756
  var RETRY_AFTER_FLOOR_MS = 10 * 1e3;
744
757
  var RETRY_AFTER_CEILING_MS = 60 * 1e3;
758
+ function shapePage(page) {
759
+ const p = page ?? {};
760
+ const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
761
+ return {
762
+ id: p.id,
763
+ name: p.name,
764
+ ...p.description ? { description: p.description } : {},
765
+ ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
766
+ ...p.timestamp ? { last_updated_at: p.timestamp } : {},
767
+ body
768
+ };
769
+ }
745
770
  var HindsightClient = class {
746
771
  apiUrl;
747
772
  /** The credential the NEXT request will sign with — NOT the one the config file holds. The two
@@ -779,7 +804,10 @@ var HindsightClient = class {
779
804
  return this.token;
780
805
  }
781
806
  headers() {
782
- const h = { "Content-Type": "application/json" };
807
+ const h = {
808
+ "Content-Type": "application/json",
809
+ "Accept-Encoding": "identity"
810
+ };
783
811
  if (this.token) h["Authorization"] = `Bearer ${this.token}`;
784
812
  return h;
785
813
  }
@@ -887,6 +915,23 @@ var HindsightClient = class {
887
915
  return false;
888
916
  }
889
917
  }
918
+ /**
919
+ * Whether a session write-back may use `update_mode="append"`: the server must dedupe by
920
+ * `operation_id` AND the bank must keep document text, or the server rejects the append in the
921
+ * background (#4613). Only an explicit `store_document_text: false` answers "no" — an unreachable
922
+ * or unparseable config assumes the default (stored), so a flaky probe never downgrades appends.
923
+ */
924
+ async supportsAppendRetain() {
925
+ if (!await this.supportsIdempotentRetain()) return false;
926
+ try {
927
+ const r = await this.req("GET", this.bankUrl("/config"));
928
+ if (!r.ok) return true;
929
+ const j = await r.json();
930
+ return j.config?.store_document_text !== false;
931
+ } catch {
932
+ return true;
933
+ }
934
+ }
890
935
  /**
891
936
  * Every document_id currently in the bank under a strategy tag (e.g. `source:git`), paginated into a
892
937
  * Set. Powers the incremental git-sync's "what's already ingested?" check — since git commits are stored
@@ -912,6 +957,24 @@ var HindsightClient = class {
912
957
  }
913
958
  return ids;
914
959
  }
960
+ /**
961
+ * The tags on one document, or undefined when the bank holds none with that id. Read from the
962
+ * document LISTING narrowed by `q` (a substring match on the id, so the exact id is picked out of
963
+ * the page) rather than GET /documents/{id}, which also sends the document's full text: the
964
+ * caller, the git-log freshness check on SessionStart, reads a ~100k-character document for one tag.
965
+ */
966
+ async documentTags(documentId) {
967
+ const limit = 100;
968
+ for (let offset = 0; ; offset += limit) {
969
+ const q = `?q=${encodeURIComponent(documentId)}&limit=${limit}&offset=${offset}`;
970
+ const r = await this.req("GET", this.bankUrl(`/documents${q}`));
971
+ const j = await r.json();
972
+ const items = j.items ?? [];
973
+ const hit = items.find((it) => it.id === documentId);
974
+ if (hit) return hit.tags ?? [];
975
+ if (items.length < limit || offset + limit >= (j.total ?? 0)) return void 0;
976
+ }
977
+ }
915
978
  /** Configure the bank: POST the coding bank manifest to /import (missions, retain strategies,
916
979
  * entity labels), then seed knowledge pages when the server supports them. Both halves are
917
980
  * idempotent and ADDITIVE — nothing the bank already says is overwritten (#3927), bar the
@@ -933,7 +996,8 @@ var HindsightClient = class {
933
996
  } else {
934
997
  const manifest = codingBankManifest(
935
998
  opts.reset ? void 0 : await this.readBankOverrides(),
936
- opts.extractionMode
999
+ opts.extractionMode,
1000
+ opts.defaults
937
1001
  );
938
1002
  if (!manifest) {
939
1003
  this.log(`[bank] ${this.bank} already carries the coding structure \u2014 nothing to apply`);
@@ -1139,8 +1203,8 @@ var HindsightClient = class {
1139
1203
  return { items };
1140
1204
  }
1141
1205
  /**
1142
- * Read one knowledge page's synthesized content by knowledge-base id, as an OKF document
1143
- * (YAML frontmatter + markdown body). The endpoint omits the internal reflect trace that built
1206
+ * Read one knowledge page's synthesized content by knowledge-base id, shaped by `shapePage` so
1207
+ * the body arrives once. The endpoint omits the internal reflect trace that built
1144
1208
  * the page — that is 70-95% of the raw bytes and can blow past an MCP host's per-tool-result
1145
1209
  * token cap.
1146
1210
  */
@@ -1151,7 +1215,7 @@ var HindsightClient = class {
1151
1215
  this.bankUrl(`/knowledge-base/pages/${encodeURIComponent(pageId)}`)
1152
1216
  );
1153
1217
  if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
1154
- return await r.json();
1218
+ return shapePage(await r.json());
1155
1219
  }
1156
1220
  /** Hybrid (BM25 + vector, RRF-fused) server-side search over the bank's knowledge pages.
1157
1221
  * Returns page-level hits with a relevance snippet — the real search behind
@@ -1172,6 +1236,7 @@ var HindsightClient = class {
1172
1236
  return (j.results ?? []).map((x) => ({
1173
1237
  id: x.id,
1174
1238
  name: x.name,
1239
+ ...x.source_query ? { source_query: x.source_query } : {},
1175
1240
  snippet: x.snippet ?? "",
1176
1241
  score: x.score ?? 0
1177
1242
  }));
@@ -1442,6 +1507,7 @@ function resolveCustomPages(raw) {
1442
1507
  }
1443
1508
  var DEFAULT_REFLECT_TIMEOUT_MS = 2e4;
1444
1509
  var DEFAULT_REFLECT_TOOL_TIMEOUT_MS = 33e4;
1510
+ var DEFAULT_INJECT_TIMEOUT_MS = 7e3;
1445
1511
  var REFLECT_BUDGETS = ["low", "mid", "high"];
1446
1512
  function resolveReflectBudget(raw) {
1447
1513
  const value = raw.reflectBudget;
@@ -1468,6 +1534,22 @@ function resolveObservationScopes(raw) {
1468
1534
  }
1469
1535
  return DEFAULT_OBSERVATION_SCOPES;
1470
1536
  }
1537
+ function resolveDefaultBankConfig(raw) {
1538
+ const value = raw;
1539
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
1540
+ const out = {};
1541
+ for (const [key, v] of Object.entries(value)) {
1542
+ if (PLUGIN_GOVERNED_BANK_FIELDS.includes(key)) {
1543
+ log.warn(
1544
+ "config",
1545
+ `ignoring defaultBankConfig.${key} \u2014 the plugin manages this field itself` + (key === "retain_extraction_mode" ? " (set retainExtractionMode instead)" : "")
1546
+ );
1547
+ continue;
1548
+ }
1549
+ out[key] = v;
1550
+ }
1551
+ return out;
1552
+ }
1471
1553
  var AUTO_INJECT_MODES = ["reflect", "pages", "recall", "none"];
1472
1554
  function resolveAutoInject(raw) {
1473
1555
  if (raw.autoReflect !== void 0) {
@@ -1507,18 +1589,21 @@ function resolveConfig(raw = {}) {
1507
1589
  // write sessions back by default, every harness
1508
1590
  manageBankConfig: raw.manageBankConfig ?? true,
1509
1591
  retainExtractionMode: RETAIN_EXTRACTION_MODES.includes(raw.retainExtractionMode) ? raw.retainExtractionMode : DEFAULT_RETAIN_EXTRACTION_MODE,
1592
+ defaultBankConfig: resolveDefaultBankConfig(raw.defaultBankConfig),
1510
1593
  maxParallelRetains: raw.maxParallelRetains || 10,
1511
1594
  reflectTimeoutMs: raw.reflectTimeoutMs || DEFAULT_REFLECT_TIMEOUT_MS,
1512
1595
  // Inherit an explicitly-raised reflectTimeoutMs (that is what users reaching for a longer
1513
1596
  // reflect already set), but never let it LOWER the tool below the default — a short window is
1514
1597
  // set to bound the automatic hook, not to cut off a call the agent is waiting on.
1515
1598
  reflectToolTimeoutMs: raw.reflectToolTimeoutMs || Math.max(raw.reflectTimeoutMs || 0, DEFAULT_REFLECT_TOOL_TIMEOUT_MS),
1599
+ injectTimeoutMs: raw.injectTimeoutMs || DEFAULT_INJECT_TIMEOUT_MS,
1516
1600
  reflectBudget: resolveReflectBudget(raw),
1517
1601
  autoInject: resolveAutoInject(raw),
1518
1602
  pageSearchLimit: raw.pageSearchLimit || DEFAULT_PAGE_SEARCH_LIMIT,
1519
1603
  // Same shape as retainMetadata: an object, or nothing. An array would spread into numeric
1520
1604
  // keys and reach the API as garbage, so it is rejected like any other non-object.
1521
1605
  recallOptions: raw.recallOptions && typeof raw.recallOptions === "object" && !Array.isArray(raw.recallOptions) ? { ...raw.recallOptions } : {},
1606
+ toolGuideExtra: typeof raw.toolGuideExtra === "string" && raw.toolGuideExtra.trim() ? raw.toolGuideExtra : void 0,
1522
1607
  // Every turn, not every tenth. The guide is what tells the agent WHEN to reach for memory, and
1523
1608
  // at a cadence of 10 a normal session is told once, on turn 1, and never again. Measured over
1524
1609
  // 40 real Claude Code turns, moving this from 10 to 1 took searches from 15% of turns to 32.5%
@@ -1538,11 +1623,15 @@ function resolveConfig(raw = {}) {
1538
1623
  // Hostile input is a config typo, not an attack: keep only string entries so a stray number or
1539
1624
  // nested object cannot reach the API as a tag and fail the whole retain.
1540
1625
  retainTags: Array.isArray(raw.retainTags) ? raw.retainTags.filter((t) => typeof t === "string" && t.trim() !== "") : [],
1626
+ // Undefined, not "", when unset or blank: the retain call distinguishes "not configured" (use
1627
+ // the built-in default) from a configured value, and an empty context would strip the default.
1628
+ retainContext: typeof raw.retainContext === "string" && raw.retainContext.trim() !== "" ? raw.retainContext : void 0,
1541
1629
  retainMetadata: raw.retainMetadata && typeof raw.retainMetadata === "object" ? Object.fromEntries(
1542
1630
  Object.entries(raw.retainMetadata).filter(([, v]) => typeof v === "string")
1543
1631
  ) : {},
1544
1632
  observationScopes: resolveObservationScopes(raw.observationScopes),
1545
1633
  banks: raw.banks && typeof raw.banks === "object" ? raw.banks : {},
1634
+ paths: raw.paths && typeof raw.paths === "object" ? raw.paths : {},
1546
1635
  logLevel: ["debug", "info", "warn", "error"].includes(raw.logLevel) ? raw.logLevel : "info",
1547
1636
  autoUpdate: raw.autoUpdate ?? true
1548
1637
  };
@@ -1559,7 +1648,12 @@ function readRaw(path) {
1559
1648
  }
1560
1649
  function mergeRaw(a, b) {
1561
1650
  const { harnesses: _drop, ...flat } = b;
1562
- return { ...a, ...flat, banks: { ...a.banks ?? {}, ...b.banks ?? {} } };
1651
+ return {
1652
+ ...a,
1653
+ ...flat,
1654
+ banks: { ...a.banks ?? {}, ...b.banks ?? {} },
1655
+ paths: { ...a.paths ?? {}, ...b.paths ?? {} }
1656
+ };
1563
1657
  }
1564
1658
  function applyLayer(raw, layer, harness) {
1565
1659
  let out = mergeRaw(raw, layer);
@@ -1590,9 +1684,11 @@ var ENV_KEYS = {
1590
1684
  maxParallelRetains: "HINDSIGHT_MAX_PARALLEL_RETAINS",
1591
1685
  reflectTimeoutMs: "HINDSIGHT_REFLECT_TIMEOUT_MS",
1592
1686
  reflectToolTimeoutMs: "HINDSIGHT_REFLECT_TOOL_TIMEOUT_MS",
1687
+ injectTimeoutMs: "HINDSIGHT_INJECT_TIMEOUT_MS",
1593
1688
  reflectBudget: "HINDSIGHT_REFLECT_BUDGET",
1594
1689
  autoInject: "HINDSIGHT_AUTO_INJECT",
1595
1690
  pageSearchLimit: "HINDSIGHT_PAGE_SEARCH_LIMIT",
1691
+ toolGuideExtra: "HINDSIGHT_TOOL_GUIDE_EXTRA",
1596
1692
  autoReflect: "HINDSIGHT_AUTO_REFLECT",
1597
1693
  pageRefreshEveryTurns: "HINDSIGHT_PAGE_REFRESH_EVERY_TURNS",
1598
1694
  pageTriggerType: "HINDSIGHT_PAGE_TRIGGER_TYPE",
@@ -1634,6 +1730,7 @@ var ENV_NUMBERS = /* @__PURE__ */ new Set([
1634
1730
  "maxParallelRetains",
1635
1731
  "reflectTimeoutMs",
1636
1732
  "reflectToolTimeoutMs",
1733
+ "injectTimeoutMs",
1637
1734
  "pageSearchLimit",
1638
1735
  "pageRefreshEveryTurns",
1639
1736
  "seedLimit",
@@ -1682,15 +1779,25 @@ var BANK_OVERRIDE_EXCLUDED = [
1682
1779
  function applyBankConfig(cfg, resolvedId, directory) {
1683
1780
  if (directory !== void 0 && !isOptedIn(cfg, directory))
1684
1781
  return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
1782
+ const byPath = directory === void 0 ? void 0 : pathSection(cfg, cfg.paths, directory);
1783
+ if (byPath) {
1784
+ const { bank: _rename, ...rest } = overrideFields(byPath);
1785
+ cfg = { ...cfg, ...resolvePartial(cfg, rest) };
1786
+ }
1685
1787
  const section = cfg.banks[resolvedId];
1686
1788
  if (!section) return { cfg, bankId: resolvedId };
1687
- const safe = { ...section };
1688
- for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1689
- delete safe.banks;
1789
+ const safe = overrideFields(section);
1690
1790
  const bankId = typeof safe.bank === "string" && safe.bank ? safe.bank : resolvedId;
1691
1791
  delete safe.bank;
1692
1792
  return { cfg: { ...cfg, ...resolvePartial(cfg, safe) }, bankId };
1693
1793
  }
1794
+ function overrideFields(section) {
1795
+ const safe = { ...section };
1796
+ for (const k of BANK_OVERRIDE_EXCLUDED) delete safe[k];
1797
+ delete safe.banks;
1798
+ delete safe.paths;
1799
+ return safe;
1800
+ }
1694
1801
  function resolvePartial(cfg, patch) {
1695
1802
  const full = resolveConfig(patch);
1696
1803
  const out = {};
@@ -1699,6 +1806,16 @@ function resolvePartial(cfg, patch) {
1699
1806
  out[key] = full[key];
1700
1807
  }
1701
1808
  if ("autoReflect" in patch && !("autoInject" in patch)) out.autoInject = full.autoInject;
1809
+ if ("serverMode" in patch || "apiUrl" in patch || "apiPort" in patch) {
1810
+ const conn = resolveConfig({
1811
+ serverMode: patch.serverMode ?? cfg.serverMode,
1812
+ apiPort: patch.apiPort ?? cfg.apiPort,
1813
+ apiUrl: patch.apiUrl ?? (cfg.serverMode === "daemon" ? void 0 : cfg.apiUrl)
1814
+ });
1815
+ out.serverMode = conn.serverMode;
1816
+ out.apiUrl = conn.apiUrl;
1817
+ out.apiPort = conn.apiPort;
1818
+ }
1702
1819
  return out;
1703
1820
  }
1704
1821
 
@@ -1727,7 +1844,12 @@ function resolveHostMemory(harness, directory) {
1727
1844
  // rotate the key mid-session and the snapshot 401s every call until restart (#3600). Read
1728
1845
  // through the same pipeline the constructor used, so a per-bank `banks.<id>.apiToken` is
1729
1846
  // honoured on re-resolution exactly as it was on the first one.
1730
- tokenProvider: () => resolveHostConfig(harness, directory).cfg.apiToken
1847
+ // The URL stays the one this client was built with, so a token re-read after the config
1848
+ // moved this directory to ANOTHER server is that server's credential: never send it here.
1849
+ tokenProvider: () => {
1850
+ const live = resolveHostConfig(harness, directory).cfg;
1851
+ return live.apiUrl === cfg.apiUrl ? live.apiToken : cfg.apiToken;
1852
+ }
1731
1853
  })
1732
1854
  };
1733
1855
  }
@@ -2053,12 +2175,46 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn3) {
2053
2175
  } catch {
2054
2176
  }
2055
2177
  }
2178
+ var coldStarts = /* @__PURE__ */ new Map();
2179
+ async function waitBounded(p, ms) {
2180
+ let timer;
2181
+ try {
2182
+ await Promise.race([
2183
+ p,
2184
+ new Promise((resolve3) => {
2185
+ timer = setTimeout(resolve3, Math.max(ms, 0));
2186
+ })
2187
+ ]);
2188
+ } finally {
2189
+ clearTimeout(timer);
2190
+ }
2191
+ }
2056
2192
  async function ensureDaemon(cfg, harness, opts = {}) {
2057
2193
  if (cfg.serverMode !== "daemon") return;
2058
2194
  if (await isServerHealthy(cfg.apiUrl)) return;
2059
2195
  if (!preflightDaemon(cfg, harness)) return;
2060
- startDaemonDetached(cfg, harness, opts.spawnFn);
2061
- await waitForHealth(cfg.apiUrl, opts.waitMs ?? 0);
2196
+ const waitMs = opts.waitMs ?? 0;
2197
+ const running = coldStarts.get(cfg.apiUrl);
2198
+ if (running) {
2199
+ const startedAt = Date.now();
2200
+ await waitBounded(
2201
+ running.catch(() => void 0),
2202
+ waitMs
2203
+ );
2204
+ const remaining = waitMs - (Date.now() - startedAt);
2205
+ if (remaining > 0) await waitForHealth(cfg.apiUrl, remaining);
2206
+ return;
2207
+ }
2208
+ const attempt = (async () => {
2209
+ startDaemonDetached(cfg, harness, opts.spawnFn);
2210
+ await waitForHealth(cfg.apiUrl, waitMs);
2211
+ })();
2212
+ coldStarts.set(cfg.apiUrl, attempt);
2213
+ try {
2214
+ await attempt;
2215
+ } finally {
2216
+ if (coldStarts.get(cfg.apiUrl) === attempt) coldStarts.delete(cfg.apiUrl);
2217
+ }
2062
2218
  }
2063
2219
  async function waitForHealth(baseUrl, budgetMs, pollMs = 1e3) {
2064
2220
  const deadline = Date.now() + budgetMs;
@@ -2110,13 +2266,13 @@ function indexLine(pages) {
2110
2266
  const count = pages.length === 1 ? "1 knowledge page covers" : `${pages.length} knowledge pages cover`;
2111
2267
  return `${count} this repository \u2014 architecture, conventions, past decisions and in-flight initiatives. They are deliberately NOT listed here: call hindsight_search_knowledge_pages(query) to find the ones that bear on the current turn, then hindsight_read_knowledge_page(<id>) on anything the results show is worth reading in full.`;
2112
2268
  }
2113
- var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today, never what was decided or why, so work built from code alone quietly re-litigates settled questions. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
2114
- \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, is usually already decided);
2269
+ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, and the way IN to everything below. The code shows what is true today but not what was decided or why; memory shows what was decided or said back then but not whether it still holds. Work built from either alone goes wrong: from code alone it quietly re-litigates settled questions, from memory alone it acts on stale claims. Search BEFORE you act whenever the turn is one of these \u2014 they are the ones that go wrong silently:
2270
+ \u2022 the user reports a bug or a wrong response (the intended behaviour, and the status code or value it should return, may already have been decided);
2115
2271
  \u2022 you are about to write or change a test (what this project expects a change to ship with, and how it asserts, is a convention, not a preference);
2116
2272
  \u2022 you are implementing something new, or two parts have to fit together;
2117
2273
  \u2022 the user asks why something is the way it is, or what is left to do;
2118
2274
  \u2022 you are about to commit, and need to know what the change was supposed to honour.
2119
- It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you.
2275
+ It ranks the pages by relevance and returns the matching passage, which a page title cannot tell you. What it returns is a past record, not a live reading: a claim that something was fixed, passes, or works is what someone said then \u2014 check it against the code before you rely on it, and say so when the two disagree.
2120
2276
  CREDITING IS NOT OPTIONAL AND NOT A JUDGEMENT CALL. If you called this tool and anything it returned reached your reply \u2014 quoted, paraphrased, or merely confirming what you were about to say \u2014 open that part with a markdown blockquote, exactly: "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. A search that turned up nothing useful needs no mention at all \u2014 just carry on.
2121
2277
  - hindsight_list_knowledge_pages / hindsight_read_knowledge_page \u2014 BEFORE substantial work, list the pages and read the relevant ones to ground yourself in this repo's architecture, conventions, and past decisions instead of re-deriving them from the code; follow any [[page:<id>]] links you see.
2122
2278
  - 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>").
@@ -2124,7 +2280,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP, a
2124
2280
  - 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).`;
2125
2281
  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";
2126
2282
  function toolGuide(opts) {
2127
- return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
2283
+ const extra = opts?.extra?.trim();
2284
+ return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE + (extra ? `
2285
+ ${extra}` : "");
2128
2286
  }
2129
2287
  function buildKnowledgePreamble(pages, opts) {
2130
2288
  const body = pages.length ? indexLine(pages) : EMPTY_STATE;
@@ -16670,6 +16828,7 @@ import { execFileSync as execFileSync3 } from "child_process";
16670
16828
  // src/core/git.ts
16671
16829
  import { execFileSync as execFileSync2 } from "child_process";
16672
16830
  import { resolve as resolve2 } from "path";
16831
+ var GITLOG_HEAD = "gitlog-head:";
16673
16832
  function git(repo, ...args) {
16674
16833
  return execFileSync2("git", ["-C", repo, ...args], {
16675
16834
  encoding: "utf8",
@@ -16691,6 +16850,7 @@ function gitHeadSha(dir) {
16691
16850
  }
16692
16851
  }
16693
16852
  function commitsSince(dir, sinceSha) {
16853
+ if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sinceSha)) return null;
16694
16854
  try {
16695
16855
  const n = Number.parseInt(git(dir, "rev-list", "--count", `${sinceSha}..HEAD`).trim(), 10);
16696
16856
  return Number.isFinite(n) ? n : null;
@@ -16705,6 +16865,15 @@ function hasGitHistory(dir) {
16705
16865
  return false;
16706
16866
  }
16707
16867
  }
16868
+ async function gitLogIsCurrent(client, repo, head) {
16869
+ const canonical2 = `gitlog:${repoNameOf(repo)}`;
16870
+ if ((await client.listDocumentIds(`${GITLOG_HEAD}${head}`, "all_strict")).has(canonical2))
16871
+ return true;
16872
+ const tags = await client.documentTags?.(canonical2) ?? [];
16873
+ return tags.some(
16874
+ (tag) => tag.startsWith(GITLOG_HEAD) && commitsSince(repo, tag.slice(GITLOG_HEAD.length)) === 0
16875
+ );
16876
+ }
16708
16877
 
16709
16878
  // src/core/survey.ts
16710
16879
  import { spawn as realSpawn5 } from "child_process";
@@ -17056,19 +17225,7 @@ var NON_DESTRUCTIVE_WRITE_ANNOTATIONS = {
17056
17225
  idempotentHint: false,
17057
17226
  openWorldHint: false
17058
17227
  };
17059
- var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention.';
17060
- function shapePage(page) {
17061
- const p = page ?? {};
17062
- const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
17063
- return {
17064
- id: p.id,
17065
- name: p.name,
17066
- ...p.description ? { description: p.description } : {},
17067
- ...Array.isArray(p.tags) && p.tags.length ? { tags: p.tags } : {},
17068
- ...p.timestamp ? { last_updated_at: p.timestamp } : {},
17069
- body
17070
- };
17071
- }
17228
+ var CREDIT_REMINDER = 'Crediting is mandatory, not a judgement call: if anything these results contribute reaches your reply \u2014 quoted, paraphrased, or merely confirming what you were going to say \u2014 open that part with "> \u{1F9E0} **From Hindsight memory (<page>)** \u2014 <the specific facts you drew on>". Rewriting a snippet in your own words does not make it yours. If none of them bear on the turn, ignore them silently \u2014 an unhelpful search needs no mention. These are past records: check a claim that something was fixed or works against the code before relying on it.';
17072
17229
  function ok(value) {
17073
17230
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
17074
17231
  }
@@ -17086,6 +17243,8 @@ function guarded(fn) {
17086
17243
  };
17087
17244
  }
17088
17245
  function buildKnowledgeTools(client, bankId, opts = {}) {
17246
+ const extra = opts.toolGuideExtra?.trim();
17247
+ const crediting = extra ? `${CREDIT_REMINDER} ${extra}` : CREDIT_REMINDER;
17089
17248
  return [
17090
17249
  {
17091
17250
  name: "hindsight_sync_status",
@@ -17145,7 +17304,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17145
17304
  },
17146
17305
  {
17147
17306
  name: "hindsight_search_knowledge_pages",
17148
- description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + CREDIT_REMINDER,
17307
+ description: "Search this repository's Hindsight knowledge pages for content relevant to a query \u2014 hybrid full-text + semantic search, server-side. Call this when the user's question may be answered by the project's accumulated knowledge (architecture, conventions, decisions, initiatives) rather than by reading code. Returns ranked pages with a relevance snippet; read a full page with hindsight_read_knowledge_page. " + crediting,
17149
17308
  inputSchema: { query: external_exports.string().describe("what to look for") },
17150
17309
  annotations: READ_ONLY_ANNOTATIONS,
17151
17310
  handler: async (args) => {
@@ -17155,9 +17314,12 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17155
17314
  pages: hits.map((h) => ({
17156
17315
  page: h.name,
17157
17316
  page_id: h.id,
17317
+ // The question the page answers — the same `description` the list and read tools
17318
+ // carry, so a hit says what the page is FOR, not just how it opens.
17319
+ ...h.source_query ? { description: h.source_query } : {},
17158
17320
  snippet: h.snippet
17159
17321
  })),
17160
- crediting: CREDIT_REMINDER
17322
+ crediting
17161
17323
  });
17162
17324
  } catch (e) {
17163
17325
  return err(e);
@@ -17176,7 +17338,7 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17176
17338
  description: "Read the full content of one knowledge page by its id (from hindsight_list_knowledge_pages). Call this whenever a listed page is relevant to what you're about to do \u2014 e.g. read Conventions before writing new code, Component map before changing a subsystem, or an initiative's page before continuing that feature. A page may contain [[page:<id>]] links to related pages; follow one by calling this tool again with that id. Prefer reading a page over re-deriving the same understanding from source.",
17177
17339
  inputSchema: { page_id: external_exports.string() },
17178
17340
  annotations: READ_ONLY_ANNOTATIONS,
17179
- handler: guarded(async ({ page_id }) => shapePage(await client.getPage(page_id)))
17341
+ handler: guarded(async ({ page_id }) => client.getPage(page_id))
17180
17342
  },
17181
17343
  {
17182
17344
  name: "hindsight_reflect",
@@ -17246,6 +17408,11 @@ function buildKnowledgeTools(client, bankId, opts = {}) {
17246
17408
  import { createHash as createHash4 } from "crypto";
17247
17409
  var PENDING_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
17248
17410
  var PENDING_MAX_BYTES = 256 * 1024;
17411
+ var MAX_CURSOR_PATHS = 16;
17412
+ function advancePaths(seen, path) {
17413
+ if (!path) return seen;
17414
+ return [...(seen ?? []).filter((p) => p !== path), path].slice(-MAX_CURSOR_PATHS);
17415
+ }
17249
17416
  function pendingReplayable(cursor, now) {
17250
17417
  const pending = cursor.pending ?? [];
17251
17418
  if (!pending.length) return true;
@@ -17262,8 +17429,10 @@ function planRetain(turns, cursor, opts) {
17262
17429
  if (!opts.appendSupported || !cursor || cursor.dirty) return { mode: "replace" };
17263
17430
  if (!pendingReplayable(cursor, opts.now ?? Date.now())) return { mode: "replace" };
17264
17431
  if (cursor.bank !== opts.bank) return { mode: "replace" };
17265
- if (cursor.turns > turns.length) return { mode: "replace" };
17266
- if (fingerprintTurns(turns, cursor.turns) !== cursor.fingerprint) return { mode: "replace" };
17432
+ const seen = cursor.paths ?? [];
17433
+ const newFile = Boolean(opts.path && seen.length && !seen.includes(opts.path));
17434
+ const continues = cursor.turns <= turns.length && fingerprintTurns(turns, cursor.turns) === cursor.fingerprint;
17435
+ if (!continues) return newFile ? { mode: "append", fromTurn: 0 } : { mode: "replace" };
17267
17436
  if (cursor.turns === turns.length) return { mode: "skip" };
17268
17437
  return { mode: "append", fromTurn: cursor.turns };
17269
17438
  }
@@ -17305,7 +17474,7 @@ function renderSessionJsonl(refId, turns, baseTs) {
17305
17474
  }
17306
17475
  async function supportsAppend(client) {
17307
17476
  try {
17308
- return await client.supportsIdempotentRetain();
17477
+ return await client.supportsAppendRetain();
17309
17478
  } catch {
17310
17479
  return false;
17311
17480
  }
@@ -17339,6 +17508,7 @@ function serialize(cursors, sessionId2, write2) {
17339
17508
  });
17340
17509
  return next;
17341
17510
  }
17511
+ var DEFAULT_RETAIN_CONTEXT = `conversation between the user and you (the coding agent): user turns are the user's words and decisions, assistant turns are yours. When an assistant turn says something is fixed, passes or works, record it as the agent's claim ("the agent reported X fixed"), not as an established fact.`;
17342
17512
  async function retainLiveSession(client, sessionId2, turns, startTs, harness, opts = {}) {
17343
17513
  const cursors = opts.cursors;
17344
17514
  if (!cursors)
@@ -17350,20 +17520,36 @@ async function retainLiveSession(client, sessionId2, turns, startTs, harness, op
17350
17520
  harness,
17351
17521
  opts.stamp,
17352
17522
  void 0,
17353
- opts.retryUntil
17523
+ opts.retryUntil,
17524
+ opts.transcriptPath
17354
17525
  );
17355
17526
  return serialize(
17356
17527
  cursors,
17357
17528
  sessionId2,
17358
- () => writeSession(client, sessionId2, turns, startTs, harness, opts.stamp, cursors, opts.retryUntil)
17529
+ () => writeSession(
17530
+ client,
17531
+ sessionId2,
17532
+ turns,
17533
+ startTs,
17534
+ harness,
17535
+ opts.stamp,
17536
+ cursors,
17537
+ opts.retryUntil,
17538
+ opts.transcriptPath
17539
+ )
17359
17540
  );
17360
17541
  }
17361
- async function writeSession(client, sessionId2, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS) {
17542
+ async function writeSession(client, sessionId2, turns, startTs, harness, stamp, cursors, retryUntil = Date.now() + DEFAULT_RETRY_WINDOW_MS, transcriptPath) {
17362
17543
  if (!turns.length) return;
17363
17544
  const refId = `conversation:${sessionId2}`;
17364
17545
  const cursor = cursors?.read(sessionId2);
17365
17546
  const appendSupported = Boolean(cursors) && (cursor?.appendSupported === true || await supportsAppend(client));
17366
- const plan = planRetain(turns, cursor, { appendSupported, bank: client.bank });
17547
+ const plan = planRetain(turns, cursor, {
17548
+ appendSupported,
17549
+ bank: client.bank,
17550
+ path: transcriptPath
17551
+ });
17552
+ const paths = plan.mode === "replace" ? transcriptPath ? [transcriptPath] : void 0 : advancePaths(cursor?.paths, transcriptPath);
17367
17553
  const outbox = plan.mode === "replace" ? [] : cursor?.pending ?? [];
17368
17554
  if (plan.mode === "skip" && !outbox.length) return;
17369
17555
  const opId = (mode, content) => uuidV5(`${client.bank}
@@ -17372,7 +17558,10 @@ ${mode}
17372
17558
  ${content}`);
17373
17559
  const submit = (content, operationId, append) => client.retain(
17374
17560
  content,
17375
- "coding agent session",
17561
+ // Configured context wins. Extraction reads this to decide whose claim a sentence is, so the
17562
+ // default names both speakers: the previous "coding agent session" said nothing about
17563
+ // authorship and let an assistant's proposal be recorded as the user's decision.
17564
+ stamp?.context ?? DEFAULT_RETAIN_CONTEXT,
17376
17565
  refId,
17377
17566
  // Configured tags first, built-ins last and deduped: `source:chat` and `harness:<id>` are what
17378
17567
  // the documents list filters and draws its agent logo from, so a template cannot displace them.
@@ -17402,6 +17591,7 @@ ${content}`);
17402
17591
  turns: turns.length,
17403
17592
  fingerprint: fingerprintTurns(turns, turns.length),
17404
17593
  bank: client.bank,
17594
+ ...paths ? { paths } : {},
17405
17595
  ...appendSupported ? { appendSupported: true } : {}
17406
17596
  };
17407
17597
  const stillOurs = () => {
@@ -17518,7 +17708,8 @@ function resolversFor(ctx) {
17518
17708
  function buildRetainStamp(cfg, ctx) {
17519
17709
  const hasTags = Boolean(cfg.retainTags?.length);
17520
17710
  const hasMetadata = Boolean(cfg.retainMetadata && Object.keys(cfg.retainMetadata).length);
17521
- if (!hasTags && !hasMetadata) return { tags: [], metadata: {} };
17711
+ const hasContext = Boolean(cfg.retainContext?.trim());
17712
+ if (!hasTags && !hasMetadata && !hasContext) return { tags: [], metadata: {} };
17522
17713
  const base = resolversFor(ctx);
17523
17714
  const cache = /* @__PURE__ */ new Map();
17524
17715
  const resolvers = Object.fromEntries(
@@ -17542,19 +17733,22 @@ function buildRetainStamp(cfg, ctx) {
17542
17733
  for (const [key, value] of Object.entries(cfg.retainMetadata ?? {})) {
17543
17734
  metadata[key] = applyTemplate(value, resolvers, "retainMetadata");
17544
17735
  }
17545
- return { tags, metadata };
17736
+ const context = hasContext ? applyTemplate(cfg.retainContext, resolvers, "retainContext").trim() || void 0 : void 0;
17737
+ return { tags, metadata, context };
17546
17738
  }
17547
17739
 
17548
17740
  // src/core/session-start.ts
17549
17741
  import { readFileSync as readFileSync8 } from "fs";
17550
17742
 
17551
17743
  // src/core/skill-sync.ts
17552
- import { cpSync, existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
17744
+ import { cpSync, existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
17553
17745
  import { homedir as homedir7 } from "os";
17554
- import { dirname as dirname8, join as join14 } from "path";
17746
+ import { dirname as dirname8, join as join15 } from "path";
17555
17747
  import { fileURLToPath as fileURLToPath5 } from "url";
17556
17748
 
17557
17749
  // src/core/skill-dirs.ts
17750
+ import { existsSync as existsSync5 } from "fs";
17751
+ import { join as join14 } from "path";
17558
17752
  var SKILL_DIRS = {
17559
17753
  "claude-code": [".claude", "skills"],
17560
17754
  // Codex and dsh share the agentskills-standard root; uninstalling either removes the one copy.
@@ -17567,6 +17761,8 @@ var SKILL_DIRS = {
17567
17761
  "cline-cli": [".cline", "data", "settings", "skills"],
17568
17762
  "qwen-code": [".qwen", "skills"],
17569
17763
  // Qwen's user-level skills root (Storage.getUserSkillsDirs)
17764
+ // Kimi Code's user-level skills root, alongside its config.toml and mcp.json.
17765
+ "kimi-code": [".kimi-code", "skills"],
17570
17766
  "factory-droid": [".factory", "skills"],
17571
17767
  // Droid's user-level skills root
17572
17768
  // ZCode scans TWO user roots by default (its resolveDefaultSkillRoots): `~/.zcode/skills` and the
@@ -17574,29 +17770,46 @@ var SKILL_DIRS = {
17574
17770
  // skill removal is by fixed directory name, so installing into the shared root would make
17575
17771
  // `uninstall zcode` take Codex's and dsh's copy with it.
17576
17772
  zcode: [".zcode", "skills"],
17773
+ // TraeCode's user-level skills root, resolved per edition by traecodeDotDir below — like ZCode's
17774
+ // its own, never the shared agentskills root other hosts install into.
17775
+ traecode: [".trae-cn", "skills"],
17577
17776
  // The pi family reads the shared ~/.agents/skills too, but writes its OWN root: skill removal is
17578
17777
  // by fixed directory name, so installing to the shared one would make `uninstall pi` take Codex's
17579
17778
  // and dsh's copy with it.
17580
17779
  pi: [".pi", "agent", "skills"],
17581
17780
  "prime-agent": [".prime", "agent", "skills"]
17582
17781
  };
17782
+ var TRAE_DOT_DIRS = [".trae-cn", ".trae"];
17783
+ var traecodeDotDirName = (home, exists = existsSync5) => {
17784
+ for (const dir of TRAE_DOT_DIRS) {
17785
+ if (exists(join14(home, dir))) return dir;
17786
+ }
17787
+ return ".trae-cn";
17788
+ };
17789
+ var resolveSkillDirs = (harness, home) => {
17790
+ const parts = SKILL_DIRS[harness];
17791
+ if (harness === "traecode" && parts) {
17792
+ return [traecodeDotDirName(home), ...parts.slice(1)];
17793
+ }
17794
+ return parts;
17795
+ };
17583
17796
 
17584
17797
  // src/core/skill-sync.ts
17585
17798
  function packagedSkillDir() {
17586
17799
  const here = dirname8(fileURLToPath5(import.meta.url));
17587
- const dist = join14(here, "..", "skill");
17588
- return existsSync5(join14(dist, "SKILL.md")) ? dist : join14(here, "..", "..", "skill");
17800
+ const dist = join15(here, "..", "skill");
17801
+ return existsSync6(join15(dist, "SKILL.md")) ? dist : join15(here, "..", "..", "skill");
17589
17802
  }
17590
17803
  function syncCompanionSkill(harness, opts = {}) {
17591
17804
  try {
17592
- const parts = SKILL_DIRS[harness];
17805
+ const parts = resolveSkillDirs(harness, opts.home ?? homedir7());
17593
17806
  if (!parts) return;
17594
17807
  const src = opts.srcDir ?? packagedSkillDir();
17595
- const srcMd = join14(src, "SKILL.md");
17596
- if (!existsSync5(srcMd)) return;
17597
- const dst = join14(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17598
- const dstMd = join14(dst, "SKILL.md");
17599
- const installed = existsSync5(dstMd);
17808
+ const srcMd = join15(src, "SKILL.md");
17809
+ if (!existsSync6(srcMd)) return;
17810
+ const dst = join15(opts.home ?? homedir7(), ...parts, "hindsight-coding-agent");
17811
+ const dstMd = join15(dst, "SKILL.md");
17812
+ const installed = existsSync6(dstMd);
17600
17813
  if (!installed && !opts.install) return;
17601
17814
  if (!installed || readFileSync5(srcMd, "utf8") !== readFileSync5(dstMd, "utf8")) {
17602
17815
  cpSync(src, dst, { recursive: true });
@@ -17620,15 +17833,15 @@ function brandWord() {
17620
17833
  }
17621
17834
 
17622
17835
  // src/core/legacy.ts
17623
- import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
17836
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
17624
17837
  import { homedir as homedir8 } from "os";
17625
- import { join as join15, relative, isAbsolute as isAbsolute2 } from "path";
17838
+ import { join as join16, relative, isAbsolute as isAbsolute2 } from "path";
17626
17839
  var LEGACY_CLAUDE_PLUGIN = "hindsight-memory";
17627
- function detectLegacyClaudePlugin(cwd, claudeDir = join15(homedir8(), ".claude")) {
17628
- const registry2 = readJson(join15(claudeDir, "plugins", "installed_plugins.json"));
17840
+ function detectLegacyClaudePlugin(cwd, claudeDir = join16(homedir8(), ".claude")) {
17841
+ const registry2 = readJson(join16(claudeDir, "plugins", "installed_plugins.json"));
17629
17842
  const plugins = registry2?.plugins;
17630
17843
  if (!plugins || typeof plugins !== "object") return void 0;
17631
- const enabled = readJson(join15(claudeDir, "settings.json"))?.enabledPlugins;
17844
+ const enabled = readJson(join16(claudeDir, "settings.json"))?.enabledPlugins;
17632
17845
  for (const [key, raw] of Object.entries(plugins)) {
17633
17846
  if (key.split("@")[0] !== LEGACY_CLAUDE_PLUGIN) continue;
17634
17847
  if (enabled && enabled[key] === false) continue;
@@ -17659,9 +17872,9 @@ function legacyClaudePluginWarning(key) {
17659
17872
  // src/core/session-cache.ts
17660
17873
  import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
17661
17874
  import { tmpdir as tmpdir3 } from "os";
17662
- import { dirname as dirname9, join as join16 } from "path";
17875
+ import { dirname as dirname9, join as join17 } from "path";
17663
17876
  function sessionCacheFile(harness, sessionId2) {
17664
- return join16(tmpdir3(), `hindsight-${harness}`, `${sessionId2}.json`);
17877
+ return join17(tmpdir3(), `hindsight-${harness}`, `${sessionId2}.json`);
17665
17878
  }
17666
17879
  function readSessionCache(cacheFile) {
17667
17880
  try {
@@ -17703,7 +17916,7 @@ async function gitSyncNote(args) {
17703
17916
  if (mode === "none" || cold) return void 0;
17704
17917
  const head = gitHeadSha(cwd);
17705
17918
  if (!head) return void 0;
17706
- const gitlogCurrent = await client.listDocumentIds(`gitlog-head:${head}`, "all_strict").then((s) => s.has(`gitlog:${repoNameOf(cwd)}`)).catch(() => void 0);
17919
+ const gitlogCurrent = await gitLogIsCurrent(client, cwd, head).catch(() => void 0);
17707
17920
  if (gitlogCurrent === void 0) return void 0;
17708
17921
  if (mode === "message") return gitlogCurrent ? "git in sync" : "catching up on new commits";
17709
17922
  const deepened = [...gitIds].filter((id) => id.startsWith("git:")).length;
@@ -17829,7 +18042,8 @@ async function buildSessionStartContext(args) {
17829
18042
  }
17830
18043
  }
17831
18044
  const additionalContext = buildKnowledgePreamble(pages, {
17832
- reflectOnNewGoals: cfg.autoInject !== "reflect"
18045
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18046
+ extra: cfg.toolGuideExtra
17833
18047
  });
17834
18048
  const deferInitialReflect = cold === true || pageListKnown && pages.length === 0;
17835
18049
  let gitNote;
@@ -17855,7 +18069,7 @@ ${legacyClaudePluginWarning(legacyPlugin)}`;
17855
18069
  }
17856
18070
 
17857
18071
  // src/core/hook.ts
17858
- import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
18072
+ import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
17859
18073
 
17860
18074
  // src/core/inject.ts
17861
18075
  function buildReflectQuery(prompt) {
@@ -17904,11 +18118,10 @@ If you VERIFY this memory is wrong or outdated (the code or facts contradict it)
17904
18118
  // src/core/turn-journal.ts
17905
18119
  import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync5, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
17906
18120
  import { tmpdir as tmpdir4 } from "os";
17907
- import { dirname as dirname10, join as join17 } from "path";
18121
+ import { dirname as dirname10, join as join18 } from "path";
17908
18122
  var JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
17909
18123
 
17910
18124
  // src/core/hook.ts
17911
- var HOOK_FALLBACK_BUDGET_MS = 7e3;
17912
18125
  var HOOK_INJECT_ATTEMPTS = 2;
17913
18126
  function resolveInjection(got, attempts) {
17914
18127
  if (got != null) return got;
@@ -17936,8 +18149,8 @@ async function injectRecall(harness, prompt, client, timeoutMs, event, lead) {
17936
18149
  return void 0;
17937
18150
  }
17938
18151
  }
17939
- async function reflectFallback(harness, prompt, client) {
17940
- const deadline = Date.now() + HOOK_FALLBACK_BUDGET_MS;
18152
+ async function reflectFallback(harness, prompt, client, timeoutMs) {
18153
+ const deadline = Date.now() + timeoutMs;
17941
18154
  const remaining = () => Math.max(deadline - Date.now(), 1);
17942
18155
  return await injectPages(harness, prompt, client, remaining(), "reflect_fallback_pages") ?? // Event name predates the `injectRecall` rename and is kept: it is a logged contract that
17943
18156
  // other tools read, so renaming it would silently break them.
@@ -17962,7 +18175,7 @@ async function buildHookOutput(args) {
17962
18175
  harness,
17963
18176
  prompt,
17964
18177
  client,
17965
- HOOK_FALLBACK_BUDGET_MS,
18178
+ cfg.injectTimeoutMs,
17966
18179
  "inject_pages",
17967
18180
  PAGE_INJECT_LEAD
17968
18181
  );
@@ -17975,7 +18188,7 @@ async function buildHookOutput(args) {
17975
18188
  harness,
17976
18189
  prompt,
17977
18190
  client,
17978
- HOOK_FALLBACK_BUDGET_MS,
18191
+ cfg.injectTimeoutMs,
17979
18192
  "inject_recall",
17980
18193
  RECALL_INJECT_LEAD
17981
18194
  );
@@ -18017,7 +18230,7 @@ async function buildHookOutput(args) {
18017
18230
  query: prompt.slice(0, 80)
18018
18231
  });
18019
18232
  if (e instanceof ReflectError && e.fallbackEligible) {
18020
- fallback = await reflectFallback(harness, prompt, client);
18233
+ fallback = await reflectFallback(harness, prompt, client, cfg.injectTimeoutMs);
18021
18234
  if (fallback) reflectAnswer = fallback;
18022
18235
  }
18023
18236
  }
@@ -18050,7 +18263,12 @@ async function buildHookOutput(args) {
18050
18263
  const blocks = [];
18051
18264
  if (reflectAnswer && reflectRanThisTurn) blocks.push(buildSystemInjection(reflectAnswer));
18052
18265
  if (cadence > 0 && turns % cadence === 0) {
18053
- blocks.push(buildRosterRefresh(pages, { reflectOnNewGoals: cfg.autoInject !== "reflect" }));
18266
+ blocks.push(
18267
+ buildRosterRefresh(pages, {
18268
+ reflectOnNewGoals: cfg.autoInject !== "reflect",
18269
+ extra: cfg.toolGuideExtra
18270
+ })
18271
+ );
18054
18272
  }
18055
18273
  const kept = blocks.filter(Boolean);
18056
18274
  let notice;
@@ -18119,6 +18337,7 @@ var RuntimeCore = class {
18119
18337
  pageTrigger: buildPageTrigger(this.cfg),
18120
18338
  reflectTimeoutMs: this.cfg.reflectToolTimeoutMs,
18121
18339
  reflectBudget: this.cfg.reflectBudget,
18340
+ toolGuideExtra: this.cfg.toolGuideExtra,
18122
18341
  stampFor: () => buildRetainStamp(this.cfg, {
18123
18342
  directory: this.projectDir,
18124
18343
  harness: this.harness,
@@ -18186,7 +18405,8 @@ var RuntimeCore = class {
18186
18405
  if (turns === 1) {
18187
18406
  blocks.push(
18188
18407
  buildKnowledgePreamble(output.pages, {
18189
- reflectOnNewGoals: this.cfg.autoInject !== "reflect"
18408
+ reflectOnNewGoals: this.cfg.autoInject !== "reflect",
18409
+ extra: this.cfg.toolGuideExtra
18190
18410
  })
18191
18411
  );
18192
18412
  }