@kabmo-labs/kabmo 0.15.0 → 0.16.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 (53) hide show
  1. package/README.md +1 -0
  2. package/dist/client/index.html +1 -1
  3. package/dist/client/index.js +374 -356
  4. package/dist/client/static/js/{index-mx658m43.js → index-cpydmygd.js} +644 -644
  5. package/dist/client/static/js/index-fjnq2z2d.css +1 -0
  6. package/marketplace/plugins/stats/README.md +27 -8
  7. package/marketplace/plugins/stats/package.json +2 -2
  8. package/marketplace/plugins/stats/src/HeaderReadout.test.tsx +2 -1
  9. package/marketplace/plugins/stats/src/HeaderReadout.tsx +6 -2
  10. package/marketplace/plugins/stats/src/KillConfirm.test.tsx +159 -0
  11. package/marketplace/plugins/stats/src/KillConfirm.tsx +145 -0
  12. package/marketplace/plugins/stats/src/ProcessTable.tsx +54 -8
  13. package/marketplace/plugins/stats/src/TotalsBar.test.tsx +5 -2
  14. package/marketplace/plugins/stats/src/TotalsBar.tsx +13 -3
  15. package/marketplace/plugins/stats/src/app.test.tsx +100 -4
  16. package/marketplace/plugins/stats/src/app.tsx +51 -4
  17. package/marketplace/plugins/stats/src/groups.test.ts +1 -1
  18. package/marketplace/plugins/stats/src/kill.test.ts +131 -0
  19. package/marketplace/plugins/stats/src/kill.ts +74 -0
  20. package/marketplace/plugins/stats/src/labels.test.ts +1 -0
  21. package/marketplace/plugins/stats/src/machine.test.ts +77 -0
  22. package/marketplace/plugins/stats/src/machine.ts +115 -0
  23. package/marketplace/plugins/stats/src/proc/darwin.ts +38 -0
  24. package/marketplace/plugins/stats/src/proc/linux.ts +4 -0
  25. package/marketplace/plugins/stats/src/proc/ps.ts +1 -0
  26. package/marketplace/plugins/stats/src/proc/types.ts +11 -0
  27. package/marketplace/plugins/stats/src/sampler.test.ts +42 -4
  28. package/marketplace/plugins/stats/src/sampler.ts +32 -18
  29. package/marketplace/plugins/stats/src/server.ts +29 -2
  30. package/marketplace/plugins/stats/src/snapshot.ts +31 -3
  31. package/package.json +3 -2
  32. package/src/client/components/common/Modal.tsx +7 -0
  33. package/src/client/components/layout/LeftDock.tsx +1 -0
  34. package/src/client/components/layout/desktop-layout/WorkspacePanels.tsx +1 -0
  35. package/src/client/components/mobile/RightSidebar.tsx +1 -0
  36. package/src/client/components/mobile/mobile-session-sidebar/use-dock.ts +1 -0
  37. package/src/client/components/workspace/model-dropdown/Panel.tsx +7 -2
  38. package/src/client/components/workspace/model-dropdown/Section.test.tsx +13 -0
  39. package/src/client/components/workspace/model-dropdown/Section.tsx +5 -1
  40. package/src/client/components/workspace/panels/builtin.tsx +7 -0
  41. package/src/client/components/workspace/wiki-panel/NavModal.test.tsx +136 -0
  42. package/src/client/components/workspace/wiki-panel/NavModal.tsx +94 -0
  43. package/src/client/components/workspace/wiki-panel/PageView.tsx +16 -10
  44. package/src/client/components/workspace/wiki-panel/index.tsx +44 -9
  45. package/src/server/lib/db/schema.ts +11 -0
  46. package/src/server/lib/lifecycle/memory.test.ts +41 -1
  47. package/src/server/lib/lifecycle/memory.ts +131 -14
  48. package/src/server/lib/omp/session/subagent-presence-scan.test.ts +137 -0
  49. package/src/server/lib/omp/session/subagent-presence-scan.ts +120 -0
  50. package/src/server/lib/omp/session/subagent-presence-store.test.ts +120 -0
  51. package/src/server/lib/omp/session/subagent-presence-store.ts +65 -0
  52. package/src/server/lib/omp/session/subagent-presence.ts +52 -15
  53. package/dist/client/static/js/index-28pwtt69.css +0 -1
@@ -0,0 +1,94 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+
6
+ /**
7
+ * The wiki's navigation on the phone: the floating outline-style button in the
8
+ * page, and the page list as a modal.
9
+ *
10
+ * This is the same pattern the phone's markdown editor already uses for its
11
+ * outline (`MobileOutlineButton`): a tap-sized round button outlined rather
12
+ * than filled, floating over the document it belongs to, with the list in the
13
+ * shared `Modal` shell. The desktop panel keeps its nav column and its
14
+ * drill-down when the column is narrow; `WikiPanel` decides which one renders
15
+ * from the `layout` it was handed, never from a container query.
16
+ *
17
+ * Selecting a page closes the modal, because the point of opening it was to
18
+ * reach that page.
19
+ */
20
+
21
+ import { useEffect } from 'preact/hooks';
22
+ import { ListTree } from 'lucide-preact';
23
+ import { Modal } from '@/client/components/common/Modal';
24
+ import { WikiNav } from '@/client/components/workspace/wiki-panel/Nav';
25
+ import type { WikiNavSection } from '@/shared/types/wiki';
26
+
27
+ interface WikiNavTriggerProps {
28
+ open: boolean;
29
+ onClick: () => void;
30
+ }
31
+
32
+ export function WikiNavTrigger({ open, onClick }: WikiNavTriggerProps) {
33
+ return (
34
+ <button
35
+ type="button"
36
+ onClick={onClick}
37
+ title="Browse wiki pages"
38
+ aria-label="Browse wiki pages"
39
+ aria-expanded={open}
40
+ className="absolute bottom-3 right-3 z-20 flex h-9 w-9 items-center justify-center rounded-full border border-ink/20 bg-paper text-ink/60 shadow-sm transition-all hover:bg-ink/5 hover:text-ink active:scale-95"
41
+ >
42
+ <ListTree size={16} />
43
+ </button>
44
+ );
45
+ }
46
+
47
+ interface WikiNavModalProps {
48
+ open: boolean;
49
+ sections: readonly WikiNavSection[];
50
+ selected: string | null;
51
+ onSelect: (path: string) => void;
52
+ onClose: () => void;
53
+ }
54
+
55
+ export function WikiNavModal({ open, sections, selected, onSelect, onClose }: WikiNavModalProps) {
56
+ // A dialog this small is dismissed with Escape in every other surface; the
57
+ // shared `Modal` shell does not bind it, so the owner of the open flag does.
58
+ useEffect(() => {
59
+ if (!open) return;
60
+ const onKeyDown = (event: KeyboardEvent) => {
61
+ if (event.key === 'Escape') onClose();
62
+ };
63
+ document.addEventListener('keydown', onKeyDown);
64
+ return () => document.removeEventListener('keydown', onKeyDown);
65
+ }, [open, onClose]);
66
+
67
+ if (!open) return null;
68
+
69
+ return (
70
+ <Modal
71
+ onClose={onClose}
72
+ maxWidthClass="max-w-sm"
73
+ zClass="z-[70]"
74
+ ariaLabel="Wiki pages"
75
+ header={
76
+ <div className="flex min-w-0 items-center gap-2">
77
+ <ListTree size={15} className="flex-shrink-0 text-ink/50" />
78
+ <span className="text-sm font-medium">Wiki pages</span>
79
+ </div>
80
+ }
81
+ >
82
+ <div className="flex h-[60vh] min-h-0 flex-col">
83
+ <WikiNav
84
+ sections={sections}
85
+ selected={selected}
86
+ onSelect={(path) => {
87
+ onSelect(path);
88
+ onClose();
89
+ }}
90
+ />
91
+ </div>
92
+ </Modal>
93
+ );
94
+ }
@@ -29,7 +29,11 @@ interface WikiPageViewProps {
29
29
  rootPath?: string;
30
30
  repoScope: string;
31
31
  onNavigate: (path: string) => void;
32
- onBack: () => void;
32
+ /**
33
+ * The desktop's narrow-column back arrow. Absent on the phone, where the page
34
+ * list is a modal reached by the floating button and nothing needs a back.
35
+ */
36
+ onBack?: () => void;
33
37
  }
34
38
 
35
39
  /** Web URL of one page, for "open on the host". Null for an unknown provider. */
@@ -66,15 +70,17 @@ export function WikiPageView({
66
70
  return (
67
71
  <div className="flex h-full min-h-0 w-full flex-col bg-paper">
68
72
  <div className="flex flex-shrink-0 items-center gap-1.5 border-b border-ink/10 px-2.5 py-1.5">
69
- <button
70
- type="button"
71
- onClick={onBack}
72
- title="Back to the page list"
73
- aria-label="Back to the page list"
74
- className="flex-shrink-0 rounded p-1 text-ink/60 hover:bg-ink/5 hover:text-ink @[520px]:hidden"
75
- >
76
- <ArrowLeft size={13} />
77
- </button>
73
+ {onBack && (
74
+ <button
75
+ type="button"
76
+ onClick={onBack}
77
+ title="Back to the page list"
78
+ aria-label="Back to the page list"
79
+ className="flex-shrink-0 rounded p-1 text-ink/60 hover:bg-ink/5 hover:text-ink @[520px]:hidden"
80
+ >
81
+ <ArrowLeft size={13} />
82
+ </button>
83
+ )}
78
84
  <span className="min-w-0 flex-1 truncate text-[11px] text-ink/50" title={path}>
79
85
  {path}
80
86
  </span>
@@ -22,6 +22,7 @@ import { useEffect, useMemo, useState } from 'preact/hooks';
22
22
  import { AlertCircle, BookOpen, ExternalLink, Loader2, RefreshCw } from 'lucide-preact';
23
23
  import { GitRepoPicker } from '@/client/components/workspace/repo-picker';
24
24
  import { WikiNav } from '@/client/components/workspace/wiki-panel/Nav';
25
+ import { WikiNavModal, WikiNavTrigger } from '@/client/components/workspace/wiki-panel/NavModal';
25
26
  import { WikiPageView } from '@/client/components/workspace/wiki-panel/PageView';
26
27
  import { useSessionState } from '@/client/hooks/workspace/session-state';
27
28
  import { useRepoList, useRepoScope } from '@/client/hooks/workspace/repo-scope';
@@ -36,6 +37,12 @@ interface WikiPanelProps {
36
37
  active?: boolean;
37
38
  rootPath?: string;
38
39
  refreshKey?: number;
40
+ /**
41
+ * Which shell is drawing this view. The phone gets the floating page-list
42
+ * button; the desktop keeps its nav column and the drill-down a narrow
43
+ * column has always used. Defaults to desktop for a caller that predates it.
44
+ */
45
+ layout?: 'desktop' | 'phone';
39
46
  }
40
47
 
41
48
  /** Why there is no wiki, in the reader's terms. */
@@ -52,7 +59,15 @@ interface WikiPick {
52
59
  path: string;
53
60
  }
54
61
 
55
- export function WikiPanel({ className = '', enabled = true, active = true, rootPath, refreshKey = 0 }: WikiPanelProps) {
62
+ export function WikiPanel({
63
+ className = '',
64
+ enabled = true,
65
+ active = true,
66
+ rootPath,
67
+ refreshKey = 0,
68
+ layout = 'desktop',
69
+ }: WikiPanelProps) {
70
+ const isPhone = layout === 'phone';
56
71
  const { activeRepo, setActiveRepo } = useRepoScope(rootPath);
57
72
  const { repos, scanning: reposScanning, rescan: rescanRepos } = useRepoList(rootPath, enabled);
58
73
  const scope = wikiScopeKey(rootPath, activeRepo);
@@ -60,6 +75,10 @@ export function WikiPanel({ className = '', enabled = true, active = true, rootP
60
75
  // The pick is stored WITH its scope: a page path from another repository names
61
76
  // a page this wiki does not have, and restoring it would open a 404.
62
77
  const [pick, setPick] = useSessionState<WikiPick | null>('wiki.selectedPage', null);
78
+ // The phone's page-list modal.
79
+ const [navOpen, setNavOpen] = useState(false);
80
+ // The desktop's narrow-column drill-down: the list replaces the page until a
81
+ // page is chosen, then the page carries a back arrow.
63
82
  const [narrowShowingPage, setNarrowShowingPage] = useState(false);
64
83
  // Bumped by the panel's own Refresh so the open page follows a re-listed tree
65
84
  // (the tree's revision is what a page read is anchored to).
@@ -74,6 +93,9 @@ export function WikiPanel({ className = '', enabled = true, active = true, rootP
74
93
  () => tree.data?.sidebar ?? sectionsFromEntries(entries),
75
94
  [tree.data?.sidebar, entries],
76
95
  );
96
+ // A wiki with no links has nothing for the narrow modal to show, so the
97
+ // floating trigger stays away rather than opening an empty sheet.
98
+ const hasNavLinks = useMemo(() => sections.some((section) => section.links.length > 0), [sections]);
77
99
 
78
100
  const storedPath = pick && pick.scope === scope ? pick.path : null;
79
101
  // The stored page when it still exists in this wiki, else Home, else the first
@@ -100,15 +122,17 @@ export function WikiPanel({ className = '', enabled = true, active = true, rootP
100
122
  setPick({ scope, path: selectedPath });
101
123
  }, [selectedPath, storedPath, scope, setPick]);
102
124
 
103
- // A different wiki is a different document: drop the narrow-layout drill-down
104
- // so a repo switch lands on the list rather than on a page of the old one.
125
+ // A different wiki is a different document: close the nav and drop the
126
+ // desktop drill-down so a repo switch lands on the list, not on a page of the
127
+ // old one.
105
128
  useEffect(() => {
129
+ setNavOpen(false);
106
130
  setNarrowShowingPage(false);
107
131
  }, [scope]);
108
132
 
109
133
  const handleSelect = (path: string) => {
110
134
  setPick({ scope, path });
111
- setNarrowShowingPage(true);
135
+ if (!isPhone) setNarrowShowingPage(true);
112
136
  };
113
137
 
114
138
  const handleRefresh = () => {
@@ -209,15 +233,17 @@ export function WikiPanel({ className = '', enabled = true, active = true, rootP
209
233
  // narrow drill-down's hidden/shown pair needs no second set of rules.
210
234
  <div className="flex min-h-0 flex-1 flex-col @[520px]:flex-row-reverse">
211
235
  <div
212
- className={`min-h-0 w-full @[520px]:w-52 @[520px]:flex-shrink-0 border-b border-ink/10 @[520px]:border-b-0 @[520px]:border-l ${
213
- narrowShowingPage ? 'hidden @[520px]:flex' : 'flex'
214
- } flex-col`}
236
+ className={`${
237
+ isPhone ? 'hidden' : narrowShowingPage ? 'hidden @[520px]:flex' : 'flex'
238
+ } min-h-0 w-full flex-col @[520px]:w-52 @[520px]:flex-shrink-0 @[520px]:border-l @[520px]:border-ink/10`}
215
239
  >
216
240
  <WikiNav sections={sections} selected={selectedPath} onSelect={handleSelect} />
217
241
  </div>
218
242
 
219
243
  <div
220
- className={`min-w-0 min-h-0 flex-1 ${narrowShowingPage ? 'flex' : 'hidden @[520px]:flex'} flex-col`}
244
+ className={`relative min-w-0 min-h-0 flex-1 ${
245
+ isPhone ? 'flex' : narrowShowingPage ? 'flex' : 'hidden @[520px]:flex'
246
+ } flex-col`}
221
247
  >
222
248
  {repo && selectedPath ? (
223
249
  <WikiPageView
@@ -230,13 +256,22 @@ export function WikiPanel({ className = '', enabled = true, active = true, rootP
230
256
  rootPath={rootPath}
231
257
  repoScope={activeRepo}
232
258
  onNavigate={handleSelect}
233
- onBack={() => setNarrowShowingPage(false)}
259
+ onBack={isPhone ? undefined : () => setNarrowShowingPage(false)}
234
260
  />
235
261
  ) : (
236
262
  <div className="flex h-full items-center justify-center px-6 text-center text-[11px] text-ink/40">
237
263
  This wiki has no markdown pages.
238
264
  </div>
239
265
  )}
266
+
267
+ {isPhone && hasNavLinks && <WikiNavTrigger open={navOpen} onClick={() => setNavOpen(true)} />}
268
+ <WikiNavModal
269
+ open={navOpen}
270
+ sections={sections}
271
+ selected={selectedPath}
272
+ onSelect={handleSelect}
273
+ onClose={() => setNavOpen(false)}
274
+ />
240
275
  </div>
241
276
  </div>
242
277
  )}
@@ -74,6 +74,17 @@ export async function initSchema(db: DbClient): Promise<void> {
74
74
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
75
75
  );
76
76
 
77
+ -- The sidebar's subagent badge, saved per file version so a restart does
78
+ -- not re-derive it by streaming every transcript (see
79
+ -- lib/omp/session/subagent-presence-store). Derived data: deleting the
80
+ -- table only costs one cold pass.
81
+ CREATE TABLE IF NOT EXISTS session_subagent_presence (
82
+ session_path TEXT PRIMARY KEY,
83
+ version TEXT NOT NULL,
84
+ has_subagents INTEGER NOT NULL,
85
+ updated_at INTEGER NOT NULL DEFAULT 0
86
+ );
87
+
77
88
  CREATE TABLE IF NOT EXISTS queued_messages (
78
89
  id TEXT PRIMARY KEY,
79
90
  session_id TEXT NOT NULL,
@@ -13,7 +13,13 @@
13
13
  */
14
14
 
15
15
  import { afterEach, describe, expect, test } from 'bun:test';
16
- import { maintainMemory, snapshot, stopMemoryMaintenance } from '@/server/lib/lifecycle/memory';
16
+ import {
17
+ footprintMBFromOutput,
18
+ footprintMBFromSmapsRollup,
19
+ maintainMemory,
20
+ snapshot,
21
+ stopMemoryMaintenance,
22
+ } from '@/server/lib/lifecycle/memory';
17
23
 
18
24
  const originalCeiling = Bun.env.KABMO_MEMORY_CEILING_MB;
19
25
 
@@ -57,6 +63,40 @@ describe('snapshot', () => {
57
63
  );
58
64
  expect(Math.abs(snapshot().rssMB - Math.round(psKb / 1024))).toBeLessThanOrEqual(2);
59
65
  });
66
+
67
+ test('reports a physical footprint, because RSS is not the memory in use', () => {
68
+ // On macOS a Bun process that has read and dropped a transcript keeps
69
+ // freed pages resident: measured on a live server, RSS 752 MB against a
70
+ // 70.6 MB physical footprint and a 24 MB JS heap. The sweep reacts to the
71
+ // footprint, so it has to be there.
72
+ const snap = snapshot();
73
+ expect(snap.footprintMB).not.toBeNull();
74
+ expect(snap.footprintMB ?? 0).toBeGreaterThan(0);
75
+ // A footprint larger than the resident set would mean the parser read the
76
+ // wrong field; compressed pages can push it close, never past it by much.
77
+ expect(snap.footprintMB ?? 0).toBeLessThanOrEqual(snap.rssMB * 1.25 + 16);
78
+ });
79
+ });
80
+
81
+ describe('footprint parsing', () => {
82
+ test('reads the macOS `footprint -p` headline', () => {
83
+ expect(footprintMBFromOutput('bun [98166]: 64-bit Footprint: 122 MB (16384 bytes per page)')).toBe(122);
84
+ });
85
+
86
+ test('honours the unit the tool prints', () => {
87
+ expect(footprintMBFromOutput(' Footprint: 512 KB (4096 bytes per page)')).toBe(1);
88
+ expect(footprintMBFromOutput(' Footprint: 1.5 GB (16384 bytes per page)')).toBe(1536);
89
+ });
90
+
91
+ test('an unreadable report is null rather than a guess', () => {
92
+ expect(footprintMBFromOutput('')).toBeNull();
93
+ expect(footprintMBFromOutput('some other report')).toBeNull();
94
+ });
95
+
96
+ test('reads Pss from Linux smaps_rollup', () => {
97
+ expect(footprintMBFromSmapsRollup('Rss: 40960 kB\nPss: 12345 kB\nPss_Anon: 1 kB\n')).toBe(12);
98
+ expect(footprintMBFromSmapsRollup('Rss: 40960 kB\n')).toBeNull();
99
+ });
60
100
  });
61
101
 
62
102
  describe('maintainMemory', () => {
@@ -18,12 +18,6 @@
18
18
  * | 20 concurrent `GET /api/chat/:id` | 1.69 GB |
19
19
  * | 10 s idle afterwards | 1.13 GB |
20
20
  *
21
- * The same work with an explicit `Bun.gc(true)` in the middle measured
22
- * 319 MB → 69 MB in a standalone probe, so the memory is garbage the collector
23
- * had simply not been asked to reclaim — a young-generation collection returns
24
- * the JS objects but leaves the arena, and nothing in this process allocates
25
- * enough to force a full one.
26
- *
27
21
  * Two rules keep the sweep honest:
28
22
  *
29
23
  * 1. **It is a CEILING, not a schedule.** A full collection is stop-the-world,
@@ -32,11 +26,39 @@
32
26
  * 2. **It is observable.** `snapshot()` is what `/api/health` reports, so the
33
27
  * condition the sweep reacts to is visible from `kabmo status` rather than
34
28
  * only from Activity Monitor.
29
+ *
30
+ * ## Which number is "memory"
31
+ *
32
+ * RSS is NOT it. On macOS a Bun process that has read and dropped a large
33
+ * transcript keeps the freed pages resident: measured on a live server, RSS
34
+ * 752 MB while the operating system charged the process a 70.6 MB physical
35
+ * footprint (`vmmap -summary`), with a 24 MB JS heap — and `Bun.gc(true)`
36
+ * changed nothing (`swept 1049 MB → 1050 MB`, every minute, for hours). The
37
+ * same process's RSS fell to 134 MB on its own once the OS reclaimed the
38
+ * clean pages.
39
+ *
40
+ * So the ceiling is applied to the OS's PHYSICAL FOOTPRINT where the host can
41
+ * answer, and `rssMB` is reported beside it as a diagnostic because that is
42
+ * the number `ps`-style tools show. `footprint -p <pid>` prints it on macOS
43
+ * (78 ms, and its headline matched `vmmap`'s "Physical footprint" exactly —
44
+ * 122 MB against 121.6 MB); Linux answers from `/proc/self/smaps_rollup`
45
+ * (`Pss`, which discounts shared pages) with `VmRSS` as the fallback; Windows
46
+ * uses the runtime's own number, which is accurate there.
47
+ *
48
+ * A reading is cached for `FOOTPRINT_TTL_MS`: the probe costs a spawn, and
49
+ * `/api/health` is polled far more often than the number can move. The sweep
50
+ * always refreshes both sides, because it is reporting the effect of a
51
+ * collection it just ran.
35
52
  */
36
53
 
54
+ import { readFileSync } from 'node:fs';
55
+
37
56
  /** Bytes in a megabyte, for the MB-shaped numbers this module reports. */
38
57
  const BYTES_PER_MB = 1024 * 1024;
39
58
 
59
+ /** How long an operating-system footprint reading is reused. */
60
+ const FOOTPRINT_TTL_MS = 30_000;
61
+
40
62
  /**
41
63
  * The process's resident set, in MB, from the OPERATING SYSTEM.
42
64
  *
@@ -69,6 +91,79 @@ function residentMB(): number {
69
91
  return Math.round(process.memoryUsage().rss / BYTES_PER_MB);
70
92
  }
71
93
 
94
+ /**
95
+ * The footprint line from `footprint -p <pid>`:
96
+ * `bun [123]: 64-bit Footprint: 122 MB (16384 bytes per page)`.
97
+ *
98
+ * Exported as a pure parser so the shape is pinned without spawning anything.
99
+ */
100
+ export function footprintMBFromOutput(output: string): number | null {
101
+ const match = /Footprint:\s+([\d.]+)\s+(B|KB|MB|GB)\b/i.exec(output);
102
+ if (!match) return null;
103
+ const value = Number(match[1]);
104
+ if (!Number.isFinite(value)) return null;
105
+ const unit = match[2].toUpperCase();
106
+ const mb = unit === 'GB' ? value * 1024
107
+ : unit === 'KB' ? value / 1024
108
+ : unit === 'B' ? value / BYTES_PER_MB
109
+ : value;
110
+ return Math.round(mb);
111
+ }
112
+
113
+ /** `Pss:` from `/proc/self/smaps_rollup` — the Linux analogue of footprint. */
114
+ export function footprintMBFromSmapsRollup(text: string): number | null {
115
+ const match = /^Pss:\s+(\d+)\s+kB$/m.exec(text);
116
+ if (!match) return null;
117
+ return Math.round(Number(match[1]) / 1024);
118
+ }
119
+
120
+ /** The OS's own charge for this process, in MB, or null where it cannot answer. */
121
+ function readFootprintMB(): number | null {
122
+ if (process.platform === 'win32') {
123
+ return Math.round(process.memoryUsage().rss / BYTES_PER_MB);
124
+ }
125
+ if (process.platform === 'linux') {
126
+ try {
127
+ const pss = footprintMBFromSmapsRollup(readFileSync('/proc/self/smaps_rollup', 'utf8'));
128
+ if (pss !== null) return pss;
129
+ } catch {
130
+ // smaps_rollup is unreadable on a hardened kernel; VmRSS below.
131
+ }
132
+ try {
133
+ const match = /^VmRSS:\s+(\d+)\s+kB$/m.exec(readFileSync('/proc/self/status', 'utf8'));
134
+ if (match) return Math.round(Number(match[1]) / 1024);
135
+ } catch {
136
+ return null;
137
+ }
138
+ return null;
139
+ }
140
+ try {
141
+ const out = Bun.spawnSync(['footprint', '-p', String(process.pid)]);
142
+ return footprintMBFromOutput(out.stdout.toString());
143
+ } catch {
144
+ // No `footprint` on this host (an older macOS, another POSIX): the sweep
145
+ // falls back to RSS.
146
+ return null;
147
+ }
148
+ }
149
+
150
+ interface FootprintCache {
151
+ at: number;
152
+ mb: number | null;
153
+ }
154
+
155
+ let footprintCache: FootprintCache | null = null;
156
+
157
+ /** The cached OS charge, refreshed when `refresh` or when the reading is stale. */
158
+ function footprintMB(refresh: boolean): number | null {
159
+ if (!refresh && footprintCache && Date.now() - footprintCache.at < FOOTPRINT_TTL_MS) {
160
+ return footprintCache.mb;
161
+ }
162
+ const mb = readFootprintMB();
163
+ footprintCache = { at: Date.now(), mb };
164
+ return mb;
165
+ }
166
+
72
167
  /** Default ceiling: above this, a sweep is worth a pause. */
73
168
  const DEFAULT_CEILING_MB = 1024;
74
169
 
@@ -77,8 +172,13 @@ const DEFAULT_CEILING_MB = 1024;
77
172
  const DEFAULT_INTERVAL_MS = 60_000;
78
173
 
79
174
  export interface MemorySnapshot {
80
- /** Resident set size in MB — what a process monitor shows. */
175
+ /** Resident set size in MB — what a `ps`-style monitor shows. On macOS it
176
+ * counts freed pages Bun has not returned, so it can exceed the footprint
177
+ * many times over. Reported for diagnosis; never the sweep's input. */
81
178
  rssMB: number;
179
+ /** What the operating system actually charges this process, in MB. Null when
180
+ * the host cannot answer. This is the number the sweep reacts to. */
181
+ footprintMB: number | null;
82
182
  /** Live JS objects in MB. */
83
183
  heapUsedMB: number;
84
184
  /** Reserved JS heap in MB (what the collector has not returned). */
@@ -97,16 +197,26 @@ export interface MemoryMaintenance {
97
197
  stop: () => void;
98
198
  }
99
199
 
100
- /** The process's memory, in MB. Reads `process.memoryUsage()`, never throws. */
101
- export function snapshot(): MemorySnapshot {
200
+ function takeSnapshot(refreshFootprint: boolean): MemorySnapshot {
102
201
  const usage = process.memoryUsage();
103
202
  return {
104
203
  rssMB: residentMB(),
204
+ footprintMB: footprintMB(refreshFootprint),
105
205
  heapUsedMB: Math.round(usage.heapUsed / BYTES_PER_MB),
106
206
  heapTotalMB: Math.round(usage.heapTotal / BYTES_PER_MB),
107
207
  };
108
208
  }
109
209
 
210
+ /** The process's memory, in MB. Cached footprint, never throws. */
211
+ export function snapshot(): MemorySnapshot {
212
+ return takeSnapshot(false);
213
+ }
214
+
215
+ /** The pressure the ceiling is applied to: the OS's charge when it is known. */
216
+ function pressureMB(snap: MemorySnapshot): number {
217
+ return snap.footprintMB ?? snap.rssMB;
218
+ }
219
+
110
220
  /** The ceiling in bytes, from `KABMO_MEMORY_CEILING_MB` when set. */
111
221
  function ceilingBytes(): number {
112
222
  const raw = Number(Bun.env.KABMO_MEMORY_CEILING_MB);
@@ -121,14 +231,16 @@ function ceilingBytes(): number {
121
231
  * arena is holding it — the maintenance interval never passes it.
122
232
  */
123
233
  export function maintainMemory(force = false): SweepResult {
124
- const before = snapshot();
125
- if (!force && before.rssMB * BYTES_PER_MB < ceilingBytes()) {
234
+ // Both sides refresh the OS reading: this function exists to report what a
235
+ // collection did, and a cached number would report the state before it.
236
+ const before = takeSnapshot(true);
237
+ if (!force && pressureMB(before) * BYTES_PER_MB < ceilingBytes()) {
126
238
  return { swept: false, before, after: before };
127
239
  }
128
240
  // A full collection: the point is to release the arena, and the young
129
241
  // generation alone is what failed to do that.
130
242
  Bun.gc(true);
131
- return { swept: true, before, after: snapshot() };
243
+ return { swept: true, before, after: takeSnapshot(true) };
132
244
  }
133
245
 
134
246
  /** Where the interval lives, so a `bun --hot` reload does not install a second. */
@@ -159,7 +271,12 @@ export function installMemoryMaintenance(): MemoryMaintenance {
159
271
  try {
160
272
  const result = maintainMemory();
161
273
  if (result.swept) {
162
- console.log(`[kabmo] memory: swept ${result.before.rssMB} MB → ${result.after.rssMB} MB`);
274
+ // Footprint first: it is the number the decision used, and the one a
275
+ // reader should trust. RSS rides along because a monitor shows it.
276
+ console.log(
277
+ `[kabmo] memory: swept ${pressureMB(result.before)} MB → ${pressureMB(result.after)} MB`
278
+ + ` (rss ${result.after.rssMB} MB)`,
279
+ );
163
280
  }
164
281
  } catch (error) {
165
282
  // A sweep is maintenance, never a reason to take the server down.
@@ -170,4 +287,4 @@ export function installMemoryMaintenance(): MemoryMaintenance {
170
287
  timer.unref?.();
171
288
  host.__kabmoMemorySweep = timer;
172
289
  return { stop: stopMemoryMaintenance };
173
- }
290
+ }