limitcast 0.19.4 → 0.20.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/grok.mjs CHANGED
@@ -4,7 +4,8 @@ import { homedir } from 'node:os';
4
4
  import { dirname, join } from 'node:path';
5
5
  import { codexServers, setEnabled } from './codex.mjs';
6
6
  import { windowMs } from './forecast.mjs';
7
- import { KEEP_MS, stateDir, updateConfig } from './store.mjs';
7
+ import { KEEP_MS, stateDir, updateConfig, withStateLock } from './store.mjs';
8
+ import { commitTransaction, editText, readLedger, recoverTransaction } from './transaction.mjs';
8
9
  import { grokRoot } from './usage.mjs';
9
10
 
10
11
  /** @typedef {import('./forecast.mjs').Sample} Sample */
@@ -137,41 +138,49 @@ export function grokTrimReport({ servers, used, usedMonth = null, startup, days,
137
138
  * @param {string[]} names
138
139
  */
139
140
  export function applyGrokTrim(names, { now = Date.now(), path = grokConfigPath() } = {}) {
140
- if (!names.length || !existsSync(path)) return [];
141
- const toml = readFileSync(path, 'utf8');
142
- const before = new Map(codexServers(toml).map((s) => [s.name, s.enabled]));
143
- copyFileSync(path, `${path}.limitcast-backup-${new Date(now).toISOString().replace(/[:.]/g, '-')}`);
144
- writeText(path, setEnabled(toml, Object.fromEntries(names.map((n) => [n, false]))));
145
- const servers = names.map((name) => ({ name, prev: before.get(name) ?? null }));
146
- mkdirSync(stateDir(), { recursive: true });
147
- writeFileSync(trimLedger(), JSON.stringify([...loadTrimLedger(), { at: now, servers }], null, 2));
148
- return servers;
141
+ return withStateLock(() => {
142
+ recoverTransaction(trimLedger());
143
+ const ledger = loadTrimLedger();
144
+ if (!names.length || !existsSync(path)) return [];
145
+ let toml;
146
+ const update = editText(path, (text) => {
147
+ toml = text;
148
+ return setEnabled(text, Object.fromEntries(names.map((n) => [n, false])));
149
+ });
150
+ const before = new Map(codexServers(toml).map((s) => [s.name, s.enabled]));
151
+ copyFileSync(path, `${path}.limitcast-backup-${new Date(now).toISOString().replace(/[:.]/g, '-')}`);
152
+ const servers = names.map((name) => ({ name, prev: before.get(name) ?? null }));
153
+ commitTransaction(trimLedger(), [...ledger, { at: now, servers }], [update]);
154
+ return servers;
155
+ });
149
156
  }
150
157
 
151
158
  /** Reverse the last --apply. Servers the user turned back on stay on. */
152
159
  export function undoGrokTrim({ path = grokConfigPath() } = {}) {
153
- const ledger = loadTrimLedger();
154
- const last = ledger.pop();
155
- if (!last || !existsSync(path)) return null;
156
- const toml = readFileSync(path, 'utf8');
157
- copyFileSync(path, `${path}.limitcast-backup-${new Date().toISOString().replace(/[:.]/g, '-')}`);
158
- const off = new Set(
159
- codexServers(toml)
160
- .filter((s) => s.enabled === false)
161
- .map((s) => s.name),
162
- );
163
- writeText(path, setEnabled(toml, Object.fromEntries(last.servers.filter((s) => off.has(s.name)).map((s) => [s.name, s.prev]))));
164
- writeFileSync(trimLedger(), JSON.stringify(ledger, null, 2));
165
- return last;
160
+ return withStateLock(() => {
161
+ recoverTransaction(trimLedger());
162
+ const ledger = loadTrimLedger();
163
+ const last = ledger.pop();
164
+ if (!last || !existsSync(path)) return null;
165
+ const update = editText(path, (toml) => {
166
+ const off = new Set(
167
+ codexServers(toml)
168
+ .filter((s) => s.enabled === false)
169
+ .map((s) => s.name),
170
+ );
171
+ return setEnabled(toml, Object.fromEntries(last.servers.filter((s) => off.has(s.name)).map((s) => [s.name, s.prev])));
172
+ });
173
+ copyFileSync(path, `${path}.limitcast-backup-${new Date().toISOString().replace(/[:.]/g, '-')}`);
174
+ commitTransaction(trimLedger(), ledger, [update]);
175
+ return last;
176
+ });
166
177
  }
167
178
 
168
179
  /** @returns {{at:number, servers:{name:string, prev:boolean|null}[]}[]} */
169
180
  function loadTrimLedger() {
170
- try {
171
- return JSON.parse(readFileSync(trimLedger(), 'utf8'));
172
- } catch {
173
- return [];
174
- }
181
+ const entries = readLedger(trimLedger());
182
+ if (entries.some((e) => !Array.isArray(e.servers))) throw new Error('invalid Grok trim ledger');
183
+ return entries;
175
184
  }
176
185
 
177
186
  /**
@@ -553,7 +562,7 @@ export function installGrok({ guard, alerts = false, self, home = grokHome() })
553
562
  if (wantAlerts) {
554
563
  // Grok accepts Claude's tool names in a matcher (Read is read_file) and its MCP calls as mcp__server__tool.
555
564
  (hooks.PreToolUse ??= []).push({
556
- matcher: 'Read|Grep|mcp__.*',
565
+ matcher: 'Read|Grep',
557
566
  hooks: [{ type: 'command', command: `${self} tool-limit --src grok`, timeout: 10 }],
558
567
  });
559
568
  hooks.PostToolUse = [
package/src/guard.mjs CHANGED
@@ -60,7 +60,7 @@ export function guardDecision(tool, forecasts, now, minutes) {
60
60
  */
61
61
  function blockingForecast(tool, forecasts, now, minutes) {
62
62
  const src = spawnSource(tool);
63
- return forecasts.find((f) => f.src === src && f.verdict === 'AT_RISK' && f.wall !== null && f.wall - now <= minutes * 60_000);
63
+ return forecasts.find((f) => f.src === src && f.verdict === 'AT_RISK' && f.wall !== null && f.wall >= now && f.wall - now <= minutes * 60_000);
64
64
  }
65
65
 
66
66
  /**
package/src/install.mjs CHANGED
@@ -120,12 +120,7 @@ export function install({
120
120
  isToolCheck,
121
121
  );
122
122
  changes.push('added the large tool-output notice');
123
- upsertHook(
124
- cfg,
125
- 'PreToolUse',
126
- { matcher: 'Bash|Read|Grep|WebFetch|mcp__.*', hooks: [{ type: 'command', command: `${self} tool-limit`, timeout: 10 }] },
127
- isToolLimit,
128
- );
123
+ upsertHook(cfg, 'PreToolUse', { matcher: 'Read|Grep', hooks: [{ type: 'command', command: `${self} tool-limit`, timeout: 10 }] }, isToolLimit);
129
124
  changes.push('added the fat-tool limit check');
130
125
  }
131
126
  if (optimize) {
@@ -149,20 +144,14 @@ export function install({
149
144
  if (alerts && existsSync(join(codexPath, '..'))) {
150
145
  const codex = readSettings(codexPath);
151
146
  backup(codexPath);
152
- // Codex has no Read or Grep tool; its fat results come from shell commands and MCP tools. The check learns each
153
- // tool's usual result size as it goes, and only MCP calls (which take a limit) are held.
147
+ // Codex has no native Read/Grep controls. Keep result notices and remove the legacy generic MCP pre-call hold.
154
148
  upsertHook(
155
149
  codex,
156
150
  'PostToolUse',
157
151
  { matcher: 'Bash|mcp__.*', hooks: [{ type: 'command', command: `${self} tool-check --src codex`, timeout: 10 }] },
158
152
  isToolCheck,
159
153
  );
160
- upsertHook(
161
- codex,
162
- 'PreToolUse',
163
- { matcher: 'mcp__.*', hooks: [{ type: 'command', command: `${self} tool-limit --src codex`, timeout: 10 }] },
164
- isToolLimit,
165
- );
154
+ if (codex.hooks?.PreToolUse) codex.hooks.PreToolUse = codex.hooks.PreToolUse.filter((h) => !isToolLimit(h));
166
155
  upsertHook(
167
156
  codex,
168
157
  'SessionStart',
@@ -1,7 +1,16 @@
1
1
  import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
2
2
  import { applyCapabilities, capabilityStatus, configuredServers, restoreCapabilities } from './capabilities.mjs';
3
3
  import { reserveModelJob, startModelWorker } from './model-optimize.mjs';
4
- import { capabilityProposals, changeOptimization, HOSTS, normalizeEvent, processEvent, readOptimization, repository } from './optimize.mjs';
4
+ import {
5
+ CATALOG_LIMIT,
6
+ capabilityProposals,
7
+ changeOptimization,
8
+ HOSTS,
9
+ normalizeEvent,
10
+ processEvent,
11
+ readOptimization,
12
+ repository,
13
+ } from './optimize.mjs';
5
14
  import { installOptimizerHost } from './optimizer-hosts.mjs';
6
15
  import { repositoryMap } from './repomap.mjs';
7
16
 
@@ -10,9 +19,14 @@ export function runOptimizationHook(hook, host) {
10
19
  if (hook.is_subagent || hook.subagent_id || hook.isSidechain) return {};
11
20
  const repo = repository(hook.cwd ?? hook.workdir ?? process.cwd());
12
21
  if (host === 'claude' && ['Stop', 'SessionEnd'].includes(hook.hook_event_name) && typeof hook.transcript_path === 'string') {
13
- hook = { ...hook, tools: transcriptTools(hook.transcript_path) };
22
+ const tools = transcriptTools(hook.transcript_path);
23
+ hook = { ...hook, tools, tools_complete: tools.complete };
14
24
  }
15
25
  const event = normalizeEvent(hook, host);
26
+ if (['codex', 'grok'].includes(host) && ['SessionStart', 'UserPromptSubmit', 'Stop', 'SessionEnd'].includes(event.event))
27
+ event.servers = configuredServers(host)
28
+ .filter((s) => s.enabled !== false)
29
+ .map((s) => s.name);
16
30
  let job;
17
31
  const result = changeOptimization(repo, (state) => {
18
32
  const result = processEvent(state, event);
@@ -21,6 +35,13 @@ export function runOptimizationHook(hook, host) {
21
35
  });
22
36
  if (job) startModelWorker(repo, job);
23
37
  const context = [result.context, result.map ? repositoryMap(repo) : ''].filter(Boolean).join('\n\n');
38
+ if (context)
39
+ changeOptimization(repo, (state) => {
40
+ const m = (state.measurements ??= { injections: 0, contextChars: 0, estimatedContextTokens: 0 });
41
+ m.injections++;
42
+ m.contextChars += context.length;
43
+ m.estimatedContextTokens += Math.ceil(context.length / 4);
44
+ });
24
45
  if (host === 'copilot') return context ? { additionalContext: context } : result.notice ? { additionalContext: result.notice } : {};
25
46
  return {
26
47
  ...(result.notice ? { systemMessage: result.notice } : {}),
@@ -34,16 +55,22 @@ export function transcriptTools(path) {
34
55
  const buffer = Buffer.alloc(256_000);
35
56
  const bytes = readSync(fd, buffer, 0, buffer.length, 0);
36
57
  const names = [];
58
+ let complete = statSync(path).size <= buffer.length;
37
59
  for (const line of buffer.toString('utf8', 0, bytes).split('\n')) {
60
+ if (!line.trim()) continue;
38
61
  try {
39
62
  const row = JSON.parse(line);
40
63
  if (row.attachment?.type === 'deferred_tools_delta') names.push(...(row.attachment.addedNames ?? []));
41
64
  if (row.type === 'system' && row.subtype === 'init') names.push(...(row.tools ?? []));
42
65
  } catch {
66
+ complete = false;
43
67
  /* a partial line is not evidence */
44
68
  }
45
69
  }
46
- return [...new Set(names)].filter((n) => typeof n === 'string' && /^[\w:.-]{1,100}$/.test(n)).slice(0, 200);
70
+ const unique = [...new Set(names)].filter((n) => typeof n === 'string' && /^[\w:.-]{1,100}$/.test(n));
71
+ const tools = unique.slice(0, CATALOG_LIMIT);
72
+ tools.complete = complete && unique.length <= CATALOG_LIMIT;
73
+ return tools;
47
74
  } finally {
48
75
  closeSync(fd);
49
76
  }
@@ -122,9 +149,30 @@ export function runOptimize(args, cwd = process.cwd()) {
122
149
  config: state.config,
123
150
  facts: state.facts.length,
124
151
  hosts: Object.fromEntries(
125
- HOSTS.map((h) => [h, { completedSessions: state.hosts[h]?.completed ?? 0, proposed: capabilityProposals(state, h, configuredServers(h)) }]),
152
+ HOSTS.map((h) => [
153
+ h,
154
+ {
155
+ completedSessions: state.hosts[h]?.completed ?? 0,
156
+ proposed: capabilityProposals(state, h, configuredServers(h)),
157
+ catalogComplete: state.hosts[h]?.catalogComplete ?? null,
158
+ learningEvidence: state.hosts[h]?.learningEvidence ?? null,
159
+ },
160
+ ]),
126
161
  ),
127
162
  receipts: state.receipts,
163
+ measurements: {
164
+ injectedContext: state.measurements ?? { injections: 0, contextChars: 0, estimatedContextTokens: 0 },
165
+ modelCalls: state.model?.receipts ?? [],
166
+ learning: {
167
+ eligibleChecks: Object.values(state.hosts).reduce((n, h) => n + (h.learningEvidence?.eligible ?? 0), 0),
168
+ activeFacts: state.facts.filter((f) => f.state === 'active').length,
169
+ scope: 'Counters start with this version; unsupported and ambiguous command text is never retained.',
170
+ requirements:
171
+ 'Learning needs allowlisted checks with definite success and three independent sessions; model learning also requires the opt-in model backend. Inspect per-host learningEvidence for excluded or ambiguous calls.',
172
+ },
173
+ taskSuccess: 'unmeasured; completed sessions are not proof of task success',
174
+ netSavings: 'unproven; injected context and model calls add overhead',
175
+ },
128
176
  applied: Object.fromEntries(Object.entries(state.applied ?? {}).map(([h, a]) => [h, a.names])),
129
177
  };
130
178
  }
package/src/optimize.mjs CHANGED
@@ -15,7 +15,7 @@ const CAPABILITIES = {
15
15
  };
16
16
  const validTool = (name) => typeof name === 'string' && /^[\w:.-]{1,100}$/.test(name) && !Object.hasOwn(Object.prototype, name);
17
17
  /** The tool catalog a session can declare, per host. Claude sessions with many connectors declare a few hundred tools. */
18
- const CATALOG_LIMIT = 400;
18
+ export const CATALOG_LIMIT = 400;
19
19
  export const normServer = (name) =>
20
20
  String(name)
21
21
  .toLowerCase()
@@ -193,12 +193,20 @@ export function normalizeEvent(hook, host) {
193
193
  const edit = /^(?:Edit|Write|MultiEdit|apply_patch|replace_file_content|write_to_file)$/i.test(name) || /\btools\.apply_patch\s*\(/.test(rawCode);
194
194
  const succeeded = Boolean(command) && !failed && (status === 0 || /(?:^|\n)(?:# fail 0|.*\b\d+ passed\b|OK)\s*$/m.test(text));
195
195
  const id = hook.tool_use_id ?? hook.toolUseId ?? hook.call_id;
196
+ const tools = Array.isArray(hook.tools) ? [...new Set(hook.tools.map((t) => (typeof t === 'string' ? t : t?.name)).filter(validTool))] : [];
196
197
  return {
197
198
  host,
198
199
  sid: digest(`${host}:${sid}`).slice(0, 24),
199
200
  event,
200
201
  name,
201
202
  command,
203
+ checkEvidence: command
204
+ ? 'eligible'
205
+ : nested.length > 1
206
+ ? 'ambiguous'
207
+ : typeof input?.command === 'string' || typeof input?.cmd === 'string' || nestedCommand
208
+ ? 'unsupported'
209
+ : undefined,
202
210
  failed,
203
211
  succeeded,
204
212
  edit,
@@ -210,12 +218,8 @@ export function normalizeEvent(hook, host) {
210
218
  capabilities: Object.entries(CAPABILITIES)
211
219
  .filter(([, re]) => re.test(`${name} ${JSON.stringify(input).slice(0, 32000)}`))
212
220
  .map(([key]) => key),
213
- tools: Array.isArray(hook.tools)
214
- ? hook.tools
215
- .map((t) => (typeof t === 'string' ? t : t?.name))
216
- .filter(validTool)
217
- .slice(0, CATALOG_LIMIT)
218
- : [],
221
+ tools: tools.slice(0, CATALOG_LIMIT),
222
+ toolsComplete: Array.isArray(hook.tools) ? hook.tools_complete !== false && tools.length <= CATALOG_LIMIT : undefined,
219
223
  };
220
224
  }
221
225
 
@@ -290,13 +294,32 @@ export function processEvent(state, e, now = Date.now()) {
290
294
  state.receipts = [...state.receipts, { kind, host: e.host, session: e.sid, t: now }].slice(-200);
291
295
  };
292
296
  host.used = [...new Set([...host.used, ...e.capabilities])];
293
- if (validTool(e.name) && host.usedTools.length < 200) host.usedTools = [...new Set([...host.usedTools, e.name])];
294
- // Servers are tracked on their own: a used server must stay protected after the 200-name tool list fills up.
297
+ if (validTool(e.name) && host.usedTools.length < CATALOG_LIMIT) host.usedTools = [...new Set([...host.usedTools, e.name])];
298
+ // Servers are tracked on their own: a used server must stay protected after the tool-name list fills up.
295
299
  const server = serverOf(e.host, e.name);
296
300
  if (server && (host.usedServers ??= []).length < 200) host.usedServers = [...new Set([...host.usedServers, normServer(server)])];
301
+ // Record use before catalog discovery, even when the bounded tool-name history is full.
302
+ if (e.host === 'claude' && validTool(e.name) && Object.keys(host.catalog).length < CATALOG_LIMIT)
303
+ host.catalog[e.name] ??= { used: true, sessions: [] };
297
304
  for (const tool of e.tools) {
298
305
  if (Object.keys(host.catalog).length < CATALOG_LIMIT) host.catalog[tool] ??= { used: host.usedTools.includes(tool), sessions: [] };
299
306
  }
307
+ if (e.toolsComplete !== undefined) host.catalogComplete = e.toolsComplete;
308
+ if (Array.isArray(e.servers)) {
309
+ const available = [...new Set(e.servers.filter(validTool).map(normServer).filter(validTool))].slice(0, CATALOG_LIMIT);
310
+ host.serverSessions ??= {};
311
+ if (['SessionStart', 'UserPromptSubmit'].includes(e.event)) {
312
+ for (const name of Object.keys(host.serverSessions)) if (!available.includes(name)) delete host.serverSessions[name];
313
+ session.servers ??= available;
314
+ }
315
+ if (['Stop', 'SessionEnd'].includes(e.event) && !host.finished.includes(e.sid)) {
316
+ for (const name of session.servers ?? []) {
317
+ if (!available.includes(name)) continue;
318
+ if (!Object.hasOwn(host.serverSessions, name) && Object.keys(host.serverSessions).length >= CATALOG_LIMIT) continue;
319
+ host.serverSessions[name] = [...new Set([...(host.serverSessions[name] ?? []), e.sid])].slice(-5);
320
+ }
321
+ }
322
+ }
300
323
  if (Object.hasOwn(host.catalog, e.name)) host.catalog[e.name].used = true;
301
324
  if (e.event === 'SessionStart' || (e.host === 'grok' && /^PostToolUse(?:Failure)?$/.test(e.event) && !session.injected)) {
302
325
  if (e.host === 'grok' && e.event === 'SessionStart') return {};
@@ -320,12 +343,18 @@ export function processEvent(state, e, now = Date.now()) {
320
343
  if (!host.finished.includes(e.sid)) {
321
344
  host.finished = [...host.finished, e.sid].slice(-1000);
322
345
  host.completed++;
323
- for (const name of e.tools) {
346
+ for (const name of e.toolsComplete === false ? [] : e.tools) {
324
347
  const tool = host.catalog[name];
325
348
  if (tool) tool.sessions = [...new Set([...tool.sessions, e.sid])].slice(-5);
326
349
  }
327
350
  }
328
351
  } else if (/^PostToolUse(?:Failure)?$/.test(e.event)) {
352
+ if (e.checkEvidence) {
353
+ const evidence = (host.learningEvidence ??= { eligible: 0, passed: 0, failed: 0, unsupported: 0, ambiguous: 0 });
354
+ evidence[e.checkEvidence]++;
355
+ if (e.command && e.succeeded) evidence.passed++;
356
+ if (e.command && e.failed) evidence.failed++;
357
+ }
329
358
  const turn = session.turn;
330
359
  turn.calls++;
331
360
  turn.trace = [
@@ -432,7 +461,15 @@ export function capabilityProposals(state, host, servers = []) {
432
461
  .map(normServer),
433
462
  ]);
434
463
  const kept = new Set(keep.map(normServer));
435
- return servers.filter((s) => s.enabled !== false && !used.has(normServer(s.name)) && !kept.has(normServer(s.name))).map((s) => s.name);
464
+ return servers
465
+ .filter(
466
+ (s) =>
467
+ s.enabled !== false &&
468
+ !used.has(normServer(s.name)) &&
469
+ !kept.has(normServer(s.name)) &&
470
+ (h.serverSessions?.[normServer(s.name)]?.length ?? 0) >= 5,
471
+ )
472
+ .map((s) => s.name);
436
473
  };
437
474
  if (host === 'codex') return [...Object.keys(CAPABILITIES).filter((c) => !h.used.includes(c) && !keep.includes(c)), ...idleServers()];
438
475
  if (host === 'grok') return idleServers();
package/src/store.mjs CHANGED
@@ -1,6 +1,20 @@
1
1
  // @ts-check
2
2
  import { randomUUID } from 'node:crypto';
3
- import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
3
+ import {
4
+ appendFileSync,
5
+ closeSync,
6
+ existsSync,
7
+ mkdirSync,
8
+ openSync,
9
+ readdirSync,
10
+ readFileSync,
11
+ renameSync,
12
+ rmdirSync,
13
+ rmSync,
14
+ statSync,
15
+ unlinkSync,
16
+ writeFileSync,
17
+ } from 'node:fs';
4
18
  import { homedir } from 'node:os';
5
19
  import { join } from 'node:path';
6
20
 
@@ -30,49 +44,80 @@ export function writeAtomic(/** @type {string} */ path, /** @type {string} */ te
30
44
  }
31
45
  }
32
46
 
33
- const LOCK_STALE_MS = 2_000; // the lock is held for one read and one write; older than this means its owner died
34
- const LOCK_WAIT_MS = 5_000;
47
+ const LOCK_WAIT_MS = 10_000;
48
+
49
+ function releaseLock(lock, owner) {
50
+ try {
51
+ unlinkSync(join(lock, owner));
52
+ // A contender can replace the now-empty directory with its populated lock. Never remove that lock recursively.
53
+ rmdirSync(lock);
54
+ } catch (error) {
55
+ if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
56
+ }
57
+ }
58
+
59
+ /** Serialize settings and trim transactions. Publish a populated owner directory atomically; reclaim only dead owners. */
60
+ export function withStateLock(change) {
61
+ const dir = stateDir();
62
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
63
+ const lock = join(dir, 'config.json.lock');
64
+ const owner = `${process.pid}-${randomUUID()}`;
65
+ const candidate = `${lock}.${owner}`;
66
+ mkdirSync(candidate, { mode: 0o700 });
67
+ let acquired = false;
68
+ try {
69
+ writeFileSync(join(candidate, owner), '', { mode: 0o600 });
70
+ const start = Date.now();
71
+ for (;;) {
72
+ try {
73
+ renameSync(candidate, lock);
74
+ acquired = true;
75
+ break;
76
+ } catch (error) {
77
+ if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
78
+ }
79
+ try {
80
+ for (const other of readdirSync(lock)) {
81
+ const pid = /^(\d+)-[a-f0-9-]+$/.exec(other)?.[1];
82
+ if (!pid) continue;
83
+ try {
84
+ process.kill(Number(pid), 0);
85
+ } catch (error) {
86
+ if (error.code === 'ESRCH') releaseLock(lock, other);
87
+ else if (error.code !== 'EPERM') throw error;
88
+ }
89
+ }
90
+ } catch (error) {
91
+ if (error.code !== 'ENOENT') throw error;
92
+ }
93
+ if (Date.now() - start > LOCK_WAIT_MS) throw new Error('could not lock settings: another limitcast command is changing settings');
94
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2 + Math.floor(Math.random() * 8));
95
+ }
96
+ return change();
97
+ } finally {
98
+ if (acquired) releaseLock(lock, owner);
99
+ rmSync(candidate, { recursive: true, force: true });
100
+ }
101
+ }
35
102
 
36
103
  /**
37
104
  * Change config.json under a lock: read it, let `change` return the new settings (or the same object to leave the file
38
105
  * alone), write it. Without the lock, two commands that each read the file and then each write it lose one change.
39
- * shortcut: two waiters that break the same stale lock in the same instant can both write; fix with a lockfile library if seen.
40
106
  * @param {(cfg: any) => any} change
41
107
  */
42
108
  export function updateConfig(change) {
43
- const dir = stateDir();
44
- mkdirSync(dir, { recursive: true });
45
- const file = join(dir, 'config.json');
46
- const lock = `${file}.lock`;
47
- const start = Date.now();
48
- for (;;) {
49
- try {
50
- mkdirSync(lock); // atomic: exactly one process creates it
51
- break;
52
- } catch (e) {
53
- if (/** @type {NodeJS.ErrnoException} */ (e).code !== 'EEXIST') throw e;
54
- try {
55
- if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) rmSync(lock, { recursive: true, force: true });
56
- } catch {
57
- /* released while we looked */
58
- }
59
- if (Date.now() - start > LOCK_WAIT_MS) throw new Error(`could not lock ${file}: another limitcast command is changing settings`);
60
- Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
61
- }
62
- }
63
- try {
109
+ return withStateLock(() => {
110
+ const file = join(stateDir(), 'config.json');
64
111
  let cfg = {};
65
112
  try {
66
113
  cfg = JSON.parse(readFileSync(file, 'utf8'));
67
- } catch {
68
- /* new or corrupt: start fresh */
114
+ } catch (error) {
115
+ if (error.code !== 'ENOENT') throw new Error('cannot read settings JSON; preserve config.json and repair it before retrying');
69
116
  }
70
- if (!cfg || typeof cfg !== 'object') cfg = {};
117
+ if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('settings JSON must be an object; preserve config.json');
71
118
  const next = change(cfg);
72
119
  if (next !== cfg) writeAtomic(file, JSON.stringify(next));
73
- } finally {
74
- rmSync(lock, { recursive: true, force: true });
75
- }
120
+ });
76
121
  }
77
122
 
78
123
  /**
@@ -85,7 +130,7 @@ export function record(samples) {
85
130
  const dir = stateDir();
86
131
  mkdirSync(dir, { recursive: true });
87
132
  const lastPath = join(dir, 'last.json');
88
- /** @type {Record<string, {pct:number, reset:number}>} */
133
+ /** @type {Record<string, Sample>} */
89
134
  let last = {};
90
135
  try {
91
136
  last = JSON.parse(readFileSync(lastPath, 'utf8'));
@@ -97,11 +142,11 @@ export function record(samples) {
97
142
  const prev = last[key(s)];
98
143
  return !prev || prev.pct !== s.pct || prev.reset !== s.reset;
99
144
  });
145
+ for (const s of samples) if (!Number.isFinite(last[key(s)]?.t) || s.t >= last[key(s)].t) last[key(s)] = s;
146
+ writeAtomic(lastPath, JSON.stringify(last));
100
147
  if (!fresh.length) return;
101
148
  const file = join(dir, 'samples.jsonl');
102
149
  appendFileSync(file, `${fresh.map((s) => JSON.stringify(s)).join('\n')}\n`);
103
- for (const s of fresh) last[key(s)] = { pct: s.pct, reset: s.reset };
104
- writeAtomic(lastPath, JSON.stringify(last));
105
150
  if (statSync(file).size > PRUNE_BYTES)
106
151
  writeAtomic(
107
152
  file,
@@ -117,10 +162,9 @@ export function record(samples) {
117
162
  */
118
163
  export function load(since) {
119
164
  const file = join(stateDir(), 'samples.jsonl');
120
- if (!existsSync(file)) return [];
121
165
  /** @type {Sample[]} */
122
166
  const out = [];
123
- for (const line of readFileSync(file, 'utf8').split('\n')) {
167
+ for (const line of (existsSync(file) ? readFileSync(file, 'utf8') : '').split('\n')) {
124
168
  if (!line) continue;
125
169
  try {
126
170
  const s = JSON.parse(line);
@@ -129,5 +173,25 @@ export function load(since) {
129
173
  /* skip a torn line from a concurrent write */
130
174
  }
131
175
  }
176
+ // The latest observation can be unchanged; keep one heartbeat per series rather than appending duplicates.
177
+ try {
178
+ const latest = JSON.parse(readFileSync(join(stateDir(), 'last.json'), 'utf8'));
179
+ for (const s of Object.values(latest)) {
180
+ if (
181
+ !s ||
182
+ !Number.isFinite(s.t) ||
183
+ s.t < since ||
184
+ !Number.isFinite(s.pct) ||
185
+ !Number.isFinite(s.reset) ||
186
+ s.reset <= 0 ||
187
+ typeof s.src !== 'string' ||
188
+ typeof s.win !== 'string'
189
+ )
190
+ continue;
191
+ if (!out.some((p) => p.src === s.src && p.win === s.win && p.sid === s.sid && p.t >= s.t)) out.push(s);
192
+ }
193
+ } catch {
194
+ /* legacy or unavailable heartbeat: retain the recorded observations */
195
+ }
132
196
  return out;
133
197
  }
package/src/toollimit.mjs CHANGED
@@ -4,13 +4,12 @@ import { join } from 'node:path';
4
4
  import { stateDir, writeAtomic } from './store.mjs';
5
5
  import { toolKey } from './toolcheck.mjs';
6
6
 
7
- // PreToolUse: a tool whose recent results are fat, and whose call sets no limit, is denied before it runs.
7
+ // PreToolUse: a native Read/Grep whose recent results are fat is bounded before it runs.
8
8
  // Rewriting a limit that is already present but huge keeps the call and caps it. Bash and WebFetch are left
9
9
  // alone: they have no limit argument, so a missing one is every call. Stats come from `report --why` / `--jobs`.
10
10
 
11
11
  export const FAT_AVG = 5_000;
12
12
  export const MIN_CALLS = 3;
13
- const MCP_CAP = 100;
14
13
  const READ_CAP = 400;
15
14
  const LIMIT_KEYS = new Set(['limit', 'max_results', 'maxresults', 'page_size', 'pagesize', 'top_k', 'topk', 'first']);
16
15
 
@@ -142,6 +141,8 @@ const k = (/** @type {number} */ n) => `${Math.max(1, Math.round(n / 1000))}k`;
142
141
  */
143
142
  export function toolLimitDecision(toolName, input, stats, { host = 'claude', rewrite = true } = {}) {
144
143
  const key = toolKey(toolName, host);
144
+ // MCP argument names do not establish pagination or read-only semantics. Their PostToolUse notices remain available.
145
+ if (toolName.startsWith('mcp__') || key.startsWith('mcp:')) return null;
145
146
  const stat = stats?.[key];
146
147
  if (!stat || stat.calls < MIN_CALLS || stat.avg < FAT_AVG) return null;
147
148
  const args = typeof input === 'string' ? tryJson(input) : input;
@@ -154,9 +155,9 @@ export function toolLimitDecision(toolName, input, stats, { host = 'claude', rew
154
155
  deny: `limitcast: Grep results average ≈${k(stat.avg)} tokens a call over ${stat.calls} calls. Add a path or a glob, then retry. Set LIMITCAST_ALLOW=1 to run it as written.`,
155
156
  };
156
157
  }
157
- if (toolName !== 'Read' && key !== 'Read' && !toolName.startsWith('mcp__') && !key.startsWith('mcp:')) return null;
158
- const cap = toolName === 'Read' || key === 'Read' ? READ_CAP : MCP_CAP;
159
- const limits = findLimits(obj);
158
+ if (toolName !== 'Read' && key !== 'Read') return null;
159
+ const cap = READ_CAP;
160
+ const limits = findLimits({ limit: obj.limit });
160
161
  if (limits.some((f) => f.value > 0 && f.value <= cap)) return null;
161
162
  const big = limits.find((f) => f.value > cap);
162
163
  const label = toolName === 'Read' || key === 'Read' ? 'Read' : key.replace(/^mcp:/, '');