@trazum/cli 3.0.0 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/README.md +4 -1
  2. package/assets/trazum-statusline.sh +45 -0
  3. package/dist/base-cost.d.ts +173 -0
  4. package/dist/base-cost.d.ts.map +1 -0
  5. package/dist/base-cost.js +244 -0
  6. package/dist/base-cost.js.map +1 -0
  7. package/dist/bill-range.d.ts +118 -0
  8. package/dist/bill-range.d.ts.map +1 -0
  9. package/dist/bill-range.js +122 -0
  10. package/dist/bill-range.js.map +1 -0
  11. package/dist/command-help.d.ts +17 -0
  12. package/dist/command-help.d.ts.map +1 -0
  13. package/dist/command-help.js +69 -0
  14. package/dist/command-help.js.map +1 -0
  15. package/dist/filter.d.ts +7 -1
  16. package/dist/filter.d.ts.map +1 -1
  17. package/dist/filter.js +10 -18
  18. package/dist/filter.js.map +1 -1
  19. package/dist/gateway-metrics.d.ts +83 -0
  20. package/dist/gateway-metrics.d.ts.map +1 -0
  21. package/dist/gateway-metrics.js +181 -0
  22. package/dist/gateway-metrics.js.map +1 -0
  23. package/dist/gateway-server.d.ts +23 -5
  24. package/dist/gateway-server.d.ts.map +1 -1
  25. package/dist/gateway-server.js +26 -1
  26. package/dist/gateway-server.js.map +1 -1
  27. package/dist/gateway-spend.d.ts +11 -1
  28. package/dist/gateway-spend.d.ts.map +1 -1
  29. package/dist/gateway-spend.js +44 -32
  30. package/dist/gateway-spend.js.map +1 -1
  31. package/dist/git.d.ts +70 -0
  32. package/dist/git.d.ts.map +1 -1
  33. package/dist/git.js +145 -0
  34. package/dist/git.js.map +1 -1
  35. package/dist/i18n/en.d.ts.map +1 -1
  36. package/dist/i18n/en.js +358 -6
  37. package/dist/i18n/en.js.map +1 -1
  38. package/dist/i18n/es.d.ts +0 -1
  39. package/dist/i18n/es.d.ts.map +1 -1
  40. package/dist/i18n/es.js +456 -35
  41. package/dist/i18n/es.js.map +1 -1
  42. package/dist/i18n/types.d.ts +205 -0
  43. package/dist/i18n/types.d.ts.map +1 -1
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +942 -59
  46. package/dist/index.js.map +1 -1
  47. package/dist/loopback-guard.d.ts +37 -0
  48. package/dist/loopback-guard.d.ts.map +1 -0
  49. package/dist/loopback-guard.js +65 -0
  50. package/dist/loopback-guard.js.map +1 -0
  51. package/dist/markdown.d.ts +23 -0
  52. package/dist/markdown.d.ts.map +1 -1
  53. package/dist/markdown.js +105 -0
  54. package/dist/markdown.js.map +1 -1
  55. package/dist/plan-edits.d.ts +63 -0
  56. package/dist/plan-edits.d.ts.map +1 -0
  57. package/dist/plan-edits.js +96 -0
  58. package/dist/plan-edits.js.map +1 -0
  59. package/dist/proactive.d.ts +17 -2
  60. package/dist/proactive.d.ts.map +1 -1
  61. package/dist/proactive.js +16 -9
  62. package/dist/proactive.js.map +1 -1
  63. package/dist/receipt-send.d.ts +44 -0
  64. package/dist/receipt-send.d.ts.map +1 -0
  65. package/dist/receipt-send.js +71 -0
  66. package/dist/receipt-send.js.map +1 -0
  67. package/dist/serve.d.ts +7 -0
  68. package/dist/serve.d.ts.map +1 -1
  69. package/dist/serve.js +22 -1
  70. package/dist/serve.js.map +1 -1
  71. package/dist/session-guard.d.ts +210 -0
  72. package/dist/session-guard.d.ts.map +1 -0
  73. package/dist/session-guard.js +463 -0
  74. package/dist/session-guard.js.map +1 -0
  75. package/dist/task.d.ts +7 -1
  76. package/dist/task.d.ts.map +1 -1
  77. package/dist/task.js +7 -26
  78. package/dist/task.js.map +1 -1
  79. package/dist/waste.d.ts +25 -0
  80. package/dist/waste.d.ts.map +1 -0
  81. package/dist/waste.js +39 -0
  82. package/dist/waste.js.map +1 -0
  83. package/dist/zone.d.ts +27 -0
  84. package/dist/zone.d.ts.map +1 -0
  85. package/dist/zone.js +96 -0
  86. package/dist/zone.js.map +1 -0
  87. package/package.json +2 -2
  88. package/src/base-cost.ts +384 -0
  89. package/src/bill-range.ts +206 -0
  90. package/src/command-help.ts +65 -0
  91. package/src/filter.ts +11 -18
  92. package/src/gateway-metrics.ts +209 -0
  93. package/src/gateway-server.ts +43 -6
  94. package/src/gateway-spend.ts +45 -33
  95. package/src/git.ts +158 -0
  96. package/src/i18n/en.ts +424 -6
  97. package/src/i18n/es.ts +542 -35
  98. package/src/i18n/types.ts +208 -0
  99. package/src/index.ts +952 -58
  100. package/src/loopback-guard.ts +74 -0
  101. package/src/markdown.ts +117 -0
  102. package/src/plan-edits.ts +120 -0
  103. package/src/proactive.ts +22 -13
  104. package/src/receipt-send.ts +89 -0
  105. package/src/serve.ts +23 -1
  106. package/src/session-guard.ts +541 -0
  107. package/src/task.ts +8 -26
  108. package/src/waste.ts +42 -0
  109. package/src/zone.ts +95 -0
package/src/i18n/en.ts CHANGED
@@ -30,6 +30,48 @@ export const en: CliMessages = {
30
30
  locale: 'en',
31
31
  numberLocale: 'en-US',
32
32
 
33
+ commandHelpMore: 'Every command, the config file, prices and examples: trazum --help',
34
+ taskFilter: {
35
+ taskHelp: (maxChars) => `Usage:
36
+ trazum task analyze --id <id> --type <type> --criterion <text>
37
+ --claude-code <file> [--codex <file>] [--claude-code <file> ...]
38
+ [--outcome accepted|rejected|unknown --assessor <label>]
39
+ [--policy baseline|repeat-review-v1] [-o <new-report.json>]
40
+ trazum task policy <report.json> [-o <new-policy.md>]
41
+ trazum task apply <report.json> --instructions <existing-file>
42
+ trazum task revert --instructions <existing-file>
43
+ trazum task compare <before.json> <after.json> [-o <new-comparison.json>]
44
+
45
+ Analyze explicit, complete task sources from Claude Code and Codex locally.
46
+ Repeat the source flags to include sessions from both harnesses. No home scan,
47
+ network access, provider call, hook installation or command execution occurs.
48
+ Up to 16 sources and ${maxChars} characters combined. Do not split one
49
+ session across sources or import the same session more than once.
50
+ Reports and comparisons are JSON by default (--json is also accepted).
51
+ Outcome and assessor are caller declarations, never inferred from usage.
52
+ Policy application adds a small, optional managed block to the file you choose.
53
+ Review the diff and run a comparable task yourself before comparing reports.
54
+ Revert removes only the exact unchanged block. Close other editors while applying
55
+ or reverting. Existing output reports are never overwritten; new files use 0600.
56
+ Repeated tool results may be intentional. A paired comparison is an observation,
57
+ not proof of causal savings, task quality or remaining subscription allowance.
58
+ `,
59
+ filterHelp: `Usage:
60
+ trazum filter compact --recovery-dir <private-directory> [--stats]
61
+ trazum filter restore <sha256> --recovery-dir <private-directory>
62
+ trazum filter instructions print optional output guidance
63
+
64
+ Experimental, opt-in display filter. Only consecutive repeated log lines are
65
+ compacted. Errors and unique lines are kept. Not for source files or data pipes.
66
+ Use Bash pipefail to preserve the producing command's failure status.
67
+ Original logs may contain sensitive data: --recovery-dir explicitly opts into local
68
+ retention. Delete that directory when the originals are no longer needed.
69
+ Token counts are estimates, not billing or subscription-quota measurements.
70
+ --stats writes one JSON record to stderr, without log content or recovery paths.
71
+ `,
72
+ // The source text is this language.
73
+ say: (message) => message,
74
+ },
33
75
  help: (d, bold) => `${bold('trazum')}, what your AI agents and API calls cost, read from logs on this machine.
34
76
 
35
77
  ${bold('START HERE')}
@@ -67,7 +109,8 @@ ${bold('USAGE')}
67
109
  trazum position <usage.jsonl>
68
110
  trazum receipt <usage.jsonl> [--stamp] [--since <when>] [--until <when>] [-o <file>]
69
111
  trazum bill [<file|dir>...] [--label <name>] [--no-label-from-project] [--receipt|--table] [--stamp] [-o <file>]
70
- [--since <when>] [--until <when>] [--by day|week|month] [--pdf-out|--html-out|--markdown-out|--csv-out <file>]
112
+ [--since <when>] [--until <when>] [--by day|week|month] [--pdf-out|--html-out|--markdown-out|--csv-out|--otlp-out|--prom-out <file>]
113
+ [--agent <name>] [--timezone <zone>] [--git-range <range> [--delivery]]
71
114
  trazum weekly [<file|dir>...] [--until <when>] [--label <name>] [--notify] [-o <file>]
72
115
  trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
73
116
  trazum from-codex <file|dir> [--label <name>] [-o <file>]
@@ -82,13 +125,16 @@ ${bold('USAGE')}
82
125
  trazum from-langsmith <file|dir> [-o <file>]
83
126
  trazum switch <usage.jsonl> --to <model> [--migration-usd <n>] [--cases <n>]
84
127
  trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]
128
+ trazum model-pricing <managed-settings.json> --reviewed <YYYY-MM-DD> [-o <file>]
85
129
  trazum pulse [--max-stale-hours <n>]
86
130
  trazum proactive [status|on|off] [--only <item,...>] [--dry-run | --yes] [--json]
131
+ trazum session-guard [status|install|uninstall] --warn <usd> --stop <usd> --on-cannot-tell <fail-open|fail-closed> [--dry-run | --yes]
132
+ trazum waste <transcript.jsonl> [--min-reads <n>] [--claude-md <file>] [--mcp-servers <a,b>] [--json]
87
133
  trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
88
134
  trazum write [--answers <file>] [--json] [-o <file>]
89
135
  trazum models
90
136
  trazum rules [--measure <dir>] [--level <safe|aggressive>]
91
- trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
137
+ trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed> [--metrics-port <n>]
92
138
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
93
139
  trazum quality <log> --label <name> --at <iso> [--gate]
94
140
  trazum semantic <prompt> [--yes]
@@ -189,6 +235,16 @@ ${bold('OPTIONS FOR ownrate')}
189
235
  into trazum.config.json, so the model you run yourself becomes a
190
236
  first-class row in every report, priced by you and marked as such.
191
237
 
238
+ ${bold('OPTIONS FOR model-pricing')}
239
+ --reviewed <YYYY-MM-DD> When the rates were last checked against the
240
+ contract. Required.
241
+ -o, --out <file> Write the overlay there instead of stdout.
242
+
243
+ The contracted rates your organisation gave Claude Code in its
244
+ modelPricing managed setting, as an overlay for --pricing, so Trazum's
245
+ figures match the ones Claude Code shows. What the table cannot say,
246
+ batch and fast mode, keeps the catalogue's figure and is named per model.
247
+
192
248
  ${bold('OPTIONS FOR reconcile')}
193
249
  --against <file> The provider's cost report: Anthropic's
194
250
  GET /v1/organizations/cost_report or OpenAI's
@@ -247,6 +303,41 @@ ${bold('OPTIONS FOR bill')}
247
303
  --by <day|week|month> Split the statement by UTC day, ISO week (Monday
248
304
  to Sunday) or month. Without it, a bill spanning
249
305
  two months or more is split by month.
306
+ --timezone <zone> Cut those days, and a bare --since/--until day, in
307
+ this IANA zone (Europe/Madrid) instead of UTC. The
308
+ statement says which. Not with --otlp-out,
309
+ --prom-out, --markdown-out, --html-out, --pdf-out or a
310
+ --csv-shape other than slice: they cut days in UTC.
311
+ --agent <name> Bill only one coding agent's records: claude-code,
312
+ codex or gemini-cli. A plain log or a provider
313
+ export belongs to no agent and is left out, counted.
314
+ --git-range <range> Instead of a bill, say what was recorded in this
315
+ repository's Claude Code sessions between the
316
+ earliest author time and the latest commit time of
317
+ the range (main..HEAD), run from the repository.
318
+ Only sessions that began and ended inside the span
319
+ are in the figure; sessions that crossed an edge are
320
+ named and counted apart. It is everything spent in
321
+ this repository then, not the cost of the change.
322
+ Not with --since, --until, --label or an output.
323
+ --delivery With --git-range, also say what local git shows
324
+ landed in the same range (commits, pull requests
325
+ named by number in a subject, days with a commit)
326
+ and divide the figure by each. Counts only: no
327
+ name, message or hash is read out. An average over
328
+ the span, not what any commit or pull request cost.
329
+ --otlp-out <file> Also write the bill as OpenTelemetry metrics (OTLP/HTTP
330
+ JSON): per closed UTC day, cost, tokens and calls by
331
+ project, model and agent, and what could not be priced
332
+ as its own metric. Every cost point says it is
333
+ api-equivalent, not what a plan paid. Today, and a day
334
+ the --since/--until window cuts, are not points: the
335
+ resource says which and what they held. Trazum writes
336
+ the file; your pipeline sends it.
337
+ --prom-out <file> Also write the same metrics in the Prometheus text
338
+ format, for the node exporter's textfile collector:
339
+ one series per closed UTC day (its trazum_day label),
340
+ no timestamps, nothing pushed.
250
341
  --stamp Stamp the receipt with the time it was written.
251
342
  -o, --out <file> Write the receipt there instead of stdout.
252
343
 
@@ -466,6 +557,46 @@ ${bold('OPTIONS FOR proactive')}
466
557
  no spend limit is "not ready", with the command or the key that would make it
467
558
  ready.
468
559
 
560
+ ${bold('OPTIONS FOR session-guard')}
561
+ status Whether the hook is in ~/.claude/settings.json, and
562
+ at which figures. The default; writes nothing.
563
+ install Add the hook to the UserPromptSubmit and PreToolUse
564
+ events. Says the file and every line first, and
565
+ writes only after a yes.
566
+ uninstall Remove exactly the hook it added.
567
+ check What the hook runs: reads the session's transcript,
568
+ prices it at the bundled catalogue and warns once,
569
+ stops (exit code 2) or stays silent. Not for typing.
570
+ --warn <usd> Warn once per session at this API-equivalent cost.
571
+ --stop <usd> Stop the session at this cost. Must exceed --warn.
572
+ --on-cannot-tell <policy> fail-open or fail-closed: what happens when the
573
+ cost cannot be told (no transcript, a model with
574
+ no price). It never counts the cost as zero.
575
+ --dry-run, --yes As for proactive.
576
+
577
+ There is no default for the thresholds or the policy: leave one out and the
578
+ command refuses by name. Every figure is API-equivalent cost, what the usage
579
+ would cost at the provider's list API prices, not what you were charged.
580
+ Nothing leaves this machine.
581
+
582
+ ${bold('OPTIONS FOR waste')}
583
+ <transcript.jsonl> A Claude Code session's transcript. Its subagents'
584
+ transcripts, in the folder beside it, are read too.
585
+ --min-reads <n> List a file only if it was read at least n times
586
+ (2 or more; default 3). It chooses what is listed,
587
+ not what is counted.
588
+ --claude-md <file> The CLAUDE.md to size. Without it, the CLAUDE.md in
589
+ the directory the session ran in, if there is one.
590
+ Only its size in bytes is read, never its content.
591
+ --mcp-servers <a,b> The MCP servers that were loaded, when the
592
+ transcript does not say. Names only.
593
+
594
+ It names a cost and prices it at the bundled catalogue, from this session's
595
+ own counts: a file read again, an MCP server loaded and never called, a
596
+ CLAUDE.md carried on every turn. It recommends and edits no file. A cost it
597
+ cannot compute from what the transcript records is named and not priced.
598
+ Every figure is API-equivalent cost, not what you were charged.
599
+
469
600
  ${bold('OPTIONS FOR bench')}
470
601
  --workload <id> Run one standard workload instead of all of them.
471
602
  An unknown id is refused with the known ones named.
@@ -543,6 +674,10 @@ ${bold('OPTIONS FOR gateway')}
543
674
  What happens when the gateway cannot judge a call:
544
675
  no budget, nothing measured, an unpriced model.
545
676
  --port <n> | --socket <p> Where to listen. Loopback only, always.
677
+ --metrics-port <n> Serve what the gateway has counted since it
678
+ started, in Prometheus text, at GET /metrics on
679
+ this second loopback port. Off unless given. Counts
680
+ and list-rate cost only, never a prompt.
546
681
  --log <usage.jsonl> The usage log the limits policy is measured
547
682
  against, read once at start, same flag as
548
683
  serve's, same reason: label and session spend
@@ -773,6 +908,16 @@ ${bold('OPTIONS FOR check')}
773
908
  loud; a list with nothing checkable passes. Budgets apply
774
909
  per file as always; the baseline needs the whole repository
775
910
  and is skipped, and says so.
911
+ --base <ref> Also price each changed prompt on that commit and here:
912
+ tokens, and its input cost a month at the calls a month
913
+ "volumes" states for its label, or a call when none is
914
+ stated. Each figure names its price and the day that
915
+ price was read. The commit is read from this clone with
916
+ git and never fetched; one that is not here is said.
917
+ --max-monthly-increase-usd <usd>
918
+ With --base: fail when the prompts with a stated volume
919
+ cost more than this many dollars a month more than on
920
+ the base. Off unless given.
776
921
 
777
922
  Built for CI: exits with code 1 when the prompt busts the budget, so a
778
923
  template that grows unchecked breaks the build instead of the bill.
@@ -899,6 +1044,12 @@ ${bold('OPTIONS FOR profile')}
899
1044
  ${bold('OPTIONS FOR plan')}
900
1045
  --min-usd <n> Leave out actions worth less than n dollars. How
901
1046
  many were left out is stated, never silent.
1047
+ --edits Add an edit to each prompt file "labels" in
1048
+ trazum.config.json maps a label to: the safe
1049
+ rules' text, recorded by hash, written nowhere.
1050
+ Only files git tracks. No saving is projected.
1051
+ --reorder With --edits: move stable blocks ahead of the
1052
+ first placeholder before trimming.
902
1053
  -o, --out <file> Save the plan as dated JSON: the file
903
1054
  "trazum verify" will later hold it to.
904
1055
  --markdown-out <file> Also write the plan as Markdown, for a CI job
@@ -1139,6 +1290,9 @@ ${bold('CONFIG FILE')}
1139
1290
  labels { "support-rag": "prompts/support.txt" }: which prompt file each
1140
1291
  usage-log label sends, so "trazum profile" can read the file and
1141
1292
  say why a failing cache fails
1293
+ volumes { "support-rag": 30000 }: calls a month for a label "labels"
1294
+ maps, so "check --base" can price that prompt a month at a
1295
+ time. A prompt with none is priced per call, and said
1142
1296
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } }: money budgets for
1143
1297
  "trazum profile", in dollars. A budgeted label with no calls in
1144
1298
  the log is reported as not measured, never as a pass
@@ -1836,6 +1990,9 @@ ${bold('EXAMPLES')}
1836
1990
  },
1837
1991
  pointYourSdk: (where) =>
1838
1992
  `Point your SDK's base URL at ${where} and change nothing else. It speaks the provider's own wire format, so no code changes and no new client.`,
1993
+ badMetricsPort: (given) => `--metrics-port is "${given}". Give a whole number from 0 to 65535: the loopback port Prometheus scrapes.`,
1994
+ metrics: (where) =>
1995
+ `Counts for Prometheus at ${where}/metrics, since this process started: calls, tokens, list-rate cost, refusals and what could not be measured. Nothing is pushed, and no prompt is in it.`,
1839
1996
  credential: () =>
1840
1997
  'Your credential is forwarded untouched and never read, never stored, never logged and never put in a URL. Trazum holds no key here and cannot make a call of its own through this.',
1841
1998
  neverSubstitutes: () =>
@@ -1996,6 +2153,39 @@ ${bold('EXAMPLES')}
1996
2153
  `Nothing above says whether the candidate can do the work. That is an evaluation, not arithmetic: ${routeCommand}`,
1997
2154
  },
1998
2155
 
2156
+ modelPricing: {
2157
+ noFile: () =>
2158
+ 'Name the settings file that holds modelPricing: trazum model-pricing <managed-settings.json> --reviewed YYYY-MM-DD',
2159
+ noReviewed: () =>
2160
+ '--reviewed YYYY-MM-DD is required: the date somebody last checked these rates against the contract. An overlay of unknown age is worse than the bundled catalogue, whose age every report prints.',
2161
+ notFound: (file) => `${file} is not a file.`,
2162
+ tooLarge: (file, bytes) => `${file} is larger than ${bytes} bytes, which is more than a settings file holds.`,
2163
+ notJson: (file, detail) => `${file} is not JSON: ${detail}`,
2164
+ skipped: (key, reason, detail) => {
2165
+ switch (reason) {
2166
+ case 'invalid':
2167
+ return `"${key}" is left out: ${detail}. Claude Code drops it too, and keeps the rest.`;
2168
+ case 'zero':
2169
+ return `"${key}" is left out: it holds a rate of zero, and Trazum prices nothing at zero. Calls to it stay at list price here.`;
2170
+ case 'unknown-model':
2171
+ return `"${key}" is not a model the catalogue knows, so nothing is priced from it. If it is a provider or gateway id for a Claude model, add that model's row under the catalogue id.`;
2172
+ case 'duplicate':
2173
+ return `"${key}" is left out: it is the same model as "${detail}", whose row is used. Trazum cannot price one model two ways.`;
2174
+ }
2175
+ },
2176
+ empty: () => 'Nothing in the table reaches a model Trazum prices, so no overlay was written.',
2177
+ summary: (fromRows, fromMultiplier, multiplier) =>
2178
+ `${fromRows} model(s) at the rates in your table${multiplier === undefined ? '' : `, times ${multiplier}`}` +
2179
+ (fromMultiplier > 0 ? `; ${fromMultiplier} other Claude model(s) at list price times ${multiplier}.` : '.'),
2180
+ batch: (models) =>
2181
+ `Batch: the table has no batch rate, so ${models} model(s) keep the catalogue's batch discount on the new input rate.`,
2182
+ fastKept: (models) =>
2183
+ `Fast mode: an overlay cannot carry a fast-mode rate, so these keep the published one, without your table or multiplier: ${models}. Claude Code applies them to fast turns.`,
2184
+ usOnly: (models) =>
2185
+ `US-only inference: no surcharge on a row, as Claude Code applies it: ${models}.`,
2186
+ written: (file, models) => `Wrote an overlay of ${models} model(s) to ${file}. Use it with --pricing ${file}.`,
2187
+ },
2188
+
1999
2189
  ownrate: {
2000
2190
  missing: () =>
2001
2191
  'Both numbers are yours to declare: trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]',
@@ -2220,6 +2410,18 @@ ${bold('EXAMPLES')}
2220
2410
  `${usd} from ${calls} call(s) with no timestamp is in the total and in no ${unit}.`,
2221
2411
  periodHint: (since, until, unit) => `One ${unit} on its own: --since ${since} --until ${until}.`,
2222
2412
  badBy: (value) => `--by takes day, week or month, not "${value}".`,
2413
+ badAgent: (value, known) => `--agent does not know "${value}". The agents it names are ${known}.`,
2414
+ agentNoRecords: (name, known) =>
2415
+ `--agent ${name} found no record of that agent among what was read. The agents it names are ${known}; a plain log or a provider export belongs to none of them.`,
2416
+ agentOnly: (name, kept, leftOut) =>
2417
+ `--agent: only ${name}'s ${kept} record(s) are billed; ${leftOut} record(s) of other agents or sources are left out.`,
2418
+ badTimezone: (value) => `--timezone does not know "${value}". Name an IANA time zone such as Europe/Madrid or America/New_York.`,
2419
+ timezoneConflict: (flag) =>
2420
+ `--timezone cuts the statement's days in that zone, and ${flag} cuts its days in UTC, so the two would print days that disagree. Leave one of them off.`,
2421
+ zoneLine: (zone) => `Days are cut in ${zone}, not UTC: a bare --since/--until day is a day there, and so is every row above.`,
2422
+ periodHintZone: (zone) => `Add --timezone ${zone} to bill it on the same days.`,
2423
+ zoneReceiptNote: (zone) =>
2424
+ `--timezone ${zone}: the receipt holds instants and no day, so the zone only decides what a bare --since/--until day means.`,
2223
2425
  colCalls: () => 'calls',
2224
2426
  colShare: () => 'share',
2225
2427
  moreRows: (count) => `… and ${count} more`,
@@ -2245,15 +2447,65 @@ ${bold('EXAMPLES')}
2245
2447
  `${path}: a provider's cost report, which is a bill rather than usage. Set it beside a receipt with trazum reconcile.`,
2246
2448
  nothingRead: () => 'Nothing here was a usage source this tool reads, so there is nothing to bill.',
2247
2449
  sources: (read, seen) => `${read} of ${seen} file(s) read as usage.`,
2450
+ sendNeedsReceipt: () =>
2451
+ '--send posts the receipt, so it needs --receipt: bill --receipt --send <url>. Nothing else is ever sent.',
2452
+ badSendTarget: (reason, keyVariable) =>
2453
+ reason === 'credentials-in-url'
2454
+ ? '--send: that URL carries credentials. URLs end up in logs, shell history and error messages, so it is refused. The key goes in the environment variable ' + keyVariable + ', and is sent as a bearer header.'
2455
+ : reason === 'insecure-scheme'
2456
+ ? '--send: the URL must be https, except on loopback. A receipt carries your spend figures, and sending them in the clear across a network is a leak you did not ask for.'
2457
+ : reason === 'bad-key'
2458
+ ? `--send: ${keyVariable} holds spaces, control characters or non-ASCII bytes, which cannot be sent as a bearer token. Its value is not shown.`
2459
+ : '--send: that is not a URL this tool can parse.',
2460
+ sendDelivered: (where, status) => `Sent the receipt to ${where} (HTTP ${status}). Nothing else was sent.`,
2461
+ sendFailed: (where, status) =>
2462
+ status === null
2463
+ ? `The receipt was not delivered to ${where}. It is written here as usual; this run exits 3 because the send failed. The error is below, without the request headers.`
2464
+ : `${where} answered HTTP ${status}, so the receipt was not delivered. It is written here as usual; this run exits 3 because the send failed. The response body is below, without the request headers.`,
2248
2465
  pricingLiveHint: (count) =>
2249
2466
  `${count} unpriced model id(s) carry a provider prefix, the way OpenRouter and LiteLLM name models, and the bundled catalogue does not carry those. Run again with --pricing-live to price OpenRouter's slugs from its own list.`,
2250
2467
  apiEquivalent: () =>
2251
2468
  'Agent sessions (Claude Code, Codex, Gemini CLI) are priced at catalogue API rates. On a subscription you paid the plan, not this API-equivalent estimate; missing telemetry and custom rates can change the result.',
2469
+ partnerUnpriced: (ids) =>
2470
+ `Claude models as Amazon Bedrock or Vertex AI name them: ${ids}. Those platforms set their own prices, which this catalogue does not carry, so the calls stay unpriced rather than billed at Anthropic's. To price them, give each id its own row in a --pricing overlay with the rates from the platform's own page.`,
2471
+ partnerModel: (platform, model) =>
2472
+ `${platform === 'bedrock' ? 'Amazon Bedrock' : 'Vertex AI'}, ${model ?? 'a model this catalogue does not know'}`,
2252
2473
  prefixedKnown: (ids) =>
2253
2474
  `${ids}: the model after the slash is priced here under its own name. The prefix is not stripped for you, because the same model through a router can bill differently. If those calls went straight to the provider, log the model without the prefix.`,
2254
2475
  windowMatchesNothing: (from, to) =>
2255
2476
  `No call falls inside this period. What was read covers ${from} → ${to}. A period with nothing in it is not a $0 bill: check the dates, or leave --since/--until off to bill everything.`,
2256
2477
  written: (file) => `Wrote ${file}.`,
2478
+ rangeConflict: (flag) =>
2479
+ `--git-range sets the period itself, from the commits, and prints its own statement: it cannot be combined with ${flag}.`,
2480
+ rangeNoGit: () => "could not run git, which --git-range reads the commits' times from.",
2481
+ rangeNoRepository: () => 'This directory is not inside a git repository, so --git-range has no repository to read.',
2482
+ rangeBad: (range) => `git does not know the range "${range}". Name one such as main..HEAD.`,
2483
+ rangeEmpty: (range) => `The range "${range}" holds no commit, so it has no span to sum.`,
2484
+ rangeHeading: (range) => `Recorded in this repository's sessions while ${range} was written`,
2485
+ rangeWindow: (from, to, commits) =>
2486
+ `Span: ${from} to ${to}, from the author and commit times of ${commits} commit(s).`,
2487
+ rangeInside: (usd, calls, sessions) =>
2488
+ `${usd} across ${calls.toLocaleString('en-US')} priced call(s) in ${sessions.toLocaleString('en-US')} session(s) that began and ended inside the span.`,
2489
+ rangeNothingInside: () => 'No session of this project began and ended inside the span.',
2490
+ rangeStraddleHeading: (count) =>
2491
+ `${count} session(s) began before the span or went on after it. Counted apart, not in the figure above:`,
2492
+ rangeStraddleRow: (session, from, to, insideUsd, insideCalls, outsideUsd, outsideCalls) =>
2493
+ ` ${session} ${from} to ${to}: ${insideUsd} (${insideCalls} call(s)) inside the span, ${outsideUsd} (${outsideCalls} call(s)) outside it.`,
2494
+ rangeNoStraddle: () => 'No session crossed either edge of the span.',
2495
+ rangeMeaning: () =>
2496
+ 'This is everything recorded in this repository during that span. It is not the cost of the change: other work in the same repository is in it, and work for the change done anywhere else is not.',
2497
+ rangeLeftOut: (outsideCalls, otherProjects, otherSources, undated) =>
2498
+ `Left out: ${outsideCalls} call(s) of sessions wholly outside the span, ${otherProjects} record(s) of other projects, ${otherSources} record(s) from sources with no project folder to match (Codex, Gemini CLI, logs), ${undated} call(s) with no timestamp.`,
2499
+ rangeUnpriced: (calls) =>
2500
+ `Not in the figure: ${calls} call(s) to models the catalogue does not price. Named, never counted as $0.`,
2501
+ deliveryNeedsRange: () => '--delivery sets the spend of a range of commits beside what git shows landed in it, so it needs --git-range.',
2502
+ rangeDelivered: (commits, merges, pullRequests, days) =>
2503
+ `Landed in the same range, from local git: ${commits.toLocaleString('en-US')} commit(s), ${merges.toLocaleString('en-US')} of them merge commits; ${pullRequests.toLocaleString('en-US')} pull request(s) named by number in a subject; ${days.toLocaleString('en-US')} UTC day(s) with a commit. A pull request merged by rebase names no number, so that count can be low.`,
2504
+ rangeDividedBy: (perCommit, perPullRequest, perDay) =>
2505
+ `The figure above divided by each count: ${perCommit ?? 'no figure'} per commit, ${perPullRequest ?? 'no figure (no pull request is named)'} per pull request, ${perDay ?? 'no figure'} per day. Two numbers over one span, not what any commit, pull request or day cost.`,
2506
+ rangeDividedNothing: () => 'No session began and ended inside the span, so there is no figure to divide by these counts.',
2507
+ rangeNoProject: () =>
2508
+ "No session read belongs to this repository's project folder. Claude Code names that folder after the repository's absolute path, so read the folder that holds it (trazum bill ~/.claude/projects --git-range main..HEAD) from the repository's own root. A session started in a subdirectory or a worktree sits in a folder of another name and is not matched.",
2257
2509
  },
2258
2510
 
2259
2511
  fromOpenrouter: {
@@ -2531,6 +2783,97 @@ ${bold('EXAMPLES')}
2531
2783
  crontab: () => 'your crontab',
2532
2784
  },
2533
2785
 
2786
+ sessionGuard: {
2787
+ unknownAction: (given) => `Unknown action "${given}". Use: trazum session-guard [status|install|uninstall].`,
2788
+ refusedMissing: (flags) =>
2789
+ `Not set: ${flags}. There is no default for the two dollar thresholds or for what to do when the cost cannot be told: each is your decision, and a guard that picked one would have made it for you. Example: trazum session-guard install --warn 5 --stop 15 --on-cannot-tell fail-open`,
2790
+ refusedAmount: (flag, given) => `${flag} needs an amount in US dollars greater than zero, and "${given}" is not one.`,
2791
+ refusedPolicy: (given, allowed) => `--on-cannot-tell is "${given}". It has to be one of: ${allowed}. fail-open lets the work go on when the cost cannot be told, and fail-closed stops it.`,
2792
+ refusedWarnNotBelowStop: () => '--warn has to be less than --stop, or the warning could never be seen before the stop.',
2793
+ refusedFlag: (flag) =>
2794
+ `${flag} is not accepted here. The guard prices the session at the catalogue bundled with this version and reads only files already on this machine.`,
2795
+ warn: (usd, warnUsd, stopUsd, atLeast) =>
2796
+ `Trazum: this session has reached ${atLeast ? 'at least ' : ''}${usd} in API-equivalent cost. Your warning figure is ${warnUsd} and it stops at ${stopUsd}. API-equivalent is what this usage would cost at the provider's list API prices, not what you were charged.${atLeast ? ' Some calls are on a model Trazum has no price for, so the true figure is higher.' : ''} This is said once per session.`,
2797
+ block: (usd, stopUsd, atLeast) =>
2798
+ `Trazum: stopped. This session has reached ${atLeast ? 'at least ' : ''}${usd} in API-equivalent cost, at or over your stop figure of ${stopUsd}. API-equivalent is what this usage would cost at the provider's list API prices, not what you were charged. To go on, raise the figure: trazum session-guard install --warn <usd> --stop <usd> --on-cannot-tell <fail-open|fail-closed>.`,
2799
+ cannotTellOpen: (why) =>
2800
+ `Trazum could not tell what this session costs: ${why}. Your policy is fail-open, so the work goes on and this guard stops nothing. It did not count the cost as zero. This is said once per session.`,
2801
+ cannotTellClosed: (why) =>
2802
+ `Trazum: stopped, because it could not tell what this session costs: ${why}. Your policy is fail-closed. It did not count the cost as zero. To go on, fix the cause, or change the policy with trazum session-guard install.`,
2803
+ cause: {
2804
+ 'no-transcript': () => 'Claude Code gave no transcript to read',
2805
+ unreadable: () => 'the transcript could not be read',
2806
+ unparseable: () => 'the transcript has lines and none of them could be read as usage',
2807
+ skipped: () => 'part of the transcript could not be read as a usage record',
2808
+ },
2809
+ unpriced: (models) => `the catalogue has no price for ${models}`,
2810
+ settingsShape: (file, key) => `${file} has a "${key}" that is not the shape Claude Code reads, so it is left alone.`,
2811
+ wouldInstall: () => 'session guard: would write',
2812
+ wouldUninstall: () => 'session guard: would remove',
2813
+ askInstall: (file) => `Write the session guard hook (${file})? [y/N] `,
2814
+ askUninstall: (file) => `Remove the session guard hook (${file})? [y/N] `,
2815
+ didInstall: (file) => `session guard: wrote ${file}`,
2816
+ didUninstall: (file) => `session guard: removed from ${file}`,
2817
+ declined: () => 'session guard: not written, you said no.',
2818
+ nothingToUninstall: () => 'session guard: nothing to remove.',
2819
+ alreadyInstalled: (file) => `session guard: already as asked in ${file}, nothing to change.`,
2820
+ dryRun: () => 'Dry run: nothing was written.',
2821
+ dryRunNoTerminal: () =>
2822
+ 'This is not a terminal and --yes was not given, so it is a dry run: nothing was written. Run it in a terminal to be asked, or pass --yes.',
2823
+ failed: (reason) => `session guard: not written. ${reason}`,
2824
+ statusOn: (file, warnUsd, stopUsd, policy) =>
2825
+ `on in ${file}: warns at ${warnUsd}, stops at ${stopUsd} of API-equivalent cost, and when the cost cannot be told it is ${policy}.`,
2826
+ statusOff: (file) => `off: no session guard hook in ${file}.`,
2827
+ statusPartial: (file) => `partly on: ${file} has the hook on one of the two events and not the other. Run install again to complete it.`,
2828
+ apiEquivalent: () => "Every figure is API-equivalent cost: the usage at the provider's list API prices, not what you were charged.",
2829
+ windows: () => 'The session guard hook is written as a shell command and is not available on Windows.',
2830
+ noClaude: (dir) => `${dir} is not there, so Claude Code does not look installed for this user. Nothing was written.`,
2831
+ },
2832
+
2833
+ waste: {
2834
+ refusedFlag: (flag) =>
2835
+ `${flag} is not accepted here. waste prices at the catalogue bundled with this version and reads only files already on this machine.`,
2836
+ noPath: () => 'Name the session transcript to read. Example: trazum waste <session>.jsonl',
2837
+ notFound: (path) => `${path} is not a file.`,
2838
+ unreadable: (path) => `${path}, or a transcript of its subagents, could not be read.`,
2839
+ minReadsBad: (given) => `--min-reads needs a whole number of 2 or more, and "${given}" is not one: a file read once has not been read again.`,
2840
+ cannotTell: () =>
2841
+ 'Cannot tell: the transcript could not be paired with its usage line for line, and pairing a tool call with the wrong prompt would price the wrong thing. Nothing was computed. Run trazum from-claude-code on it to see what it reads as.',
2842
+ heading: (calls, threads) => `Waste in this session: ${plural(calls, 'call')} in ${plural(threads, 'thread')}`,
2843
+ apiEquivalent: (reviewed) =>
2844
+ `Every figure is API-equivalent cost at the bundled catalogue, last reviewed ${reviewed}: not what you were charged. A saving is a lower bound worked out from this session's own counts.`,
2845
+ unpriced: (models) => `No price in the catalogue for ${models}: those calls are left out of every figure, so each is a floor.`,
2846
+ readsHeading: () => 'The same file read again',
2847
+ readsNone: (minReads) => `No file was read ${minReads} or more times with nothing changing it in between.`,
2848
+ readLine: (reads, repeats, measured, tokens, usd) =>
2849
+ `read ${reads} times, ${plural(repeats, 'repeat')} of the same range with no edit between. ${
2850
+ usd === null
2851
+ ? 'Not priced: the calls that repeated it also made other tool calls, so the growth cannot be split.'
2852
+ : `${measured} measured, ${tokens.toLocaleString('en-US')} tokens added to the context and carried on every later call: ${usd}.`
2853
+ }`,
2854
+ readsOmitted: (count) => `${plural(count, 'more file')} read again and not listed (under --min-reads, or past the 20 listed).`,
2855
+ readsTotal: (usd, measured, repeats) =>
2856
+ `Together: ${usd} for the ${measured} of ${repeats} repeats that could be measured.`,
2857
+ readsUnmeasured: (repeats) => `${plural(repeats, 'repeat')} found and none could be priced from the counts.`,
2858
+ mcpHeading: () => 'MCP servers loaded and never called',
2859
+ mcpNoList: () =>
2860
+ 'Cannot tell which servers were loaded: this transcript records no list. Name them with --mcp-servers <a,b> and it will say which were never called.',
2861
+ mcpAllCalled: (loaded) => `${plural(loaded, 'server')} loaded, and every one was called at least once.`,
2862
+ mcpSummary: (loaded, called, source) =>
2863
+ `${plural(loaded, 'server')} loaded${source === 'flag' ? ' (as you named them)' : ''}, ${called} called.`,
2864
+ mcpUnused: (server, tools) => `${server}: never called${tools === null ? '' : `, ${plural(tools, 'tool')} loaded`}`,
2865
+ mcpNotPriced: () =>
2866
+ "Not priced: what a server's tool definitions cost is not in the transcript, and where tools are deferred their definitions are not sent until asked for. A number here would be invented.",
2867
+ claudeHeading: () => 'A CLAUDE.md carried on every turn',
2868
+ claudeNone: (path) =>
2869
+ path === ''
2870
+ ? 'No CLAUDE.md to size: the transcript names no directory. Pass --claude-md <file>.'
2871
+ : `No CLAUDE.md at ${path}. Pass --claude-md <file> to size another.`,
2872
+ claudeLine: (bytes, tokens, calls, usd, low, high, bandPct) =>
2873
+ `${plural(bytes, 'byte')}, about ${tokens.toLocaleString('en-US')} tokens, on ${plural(calls, 'call')} of the main thread: ${usd} (${low} to ${high}). Estimated: the transcript does not record its size, so tokens are bytes over the estimator's divisor, within its published band of ${bandPct}%. Only the file's size was read.`,
2874
+ nothingChanged: () => 'Nothing was changed. This command recommends and edits no file.',
2875
+ },
2876
+
2534
2877
  pulse: {
2535
2878
  heading: () => 'Did the things that are supposed to run, run?',
2536
2879
  kind: (kind) => {
@@ -2983,6 +3326,47 @@ ${bold('EXAMPLES')}
2983
3326
  exactCountsCost: (files) =>
2984
3327
  `Counting ${files} ${files === 1 ? 'file' : 'files'} through the API, one call each. This takes a moment.`,
2985
3328
  },
3329
+ againstBase: {
3330
+ heading: (ref, sha) => `Against the base, ${ref} at ${sha}`,
3331
+ columnTokens: () => 'Tokens, base → head',
3332
+ columnCalls: () => 'Calls a month',
3333
+ columnBase: () => 'Base',
3334
+ columnHead: () => 'Head',
3335
+ columnPrice: () => 'Price',
3336
+ notStated: () => 'not stated',
3337
+ perMonth: (usd) => `${usd} a month`,
3338
+ perCall: (usd) => `${usd} a call`,
3339
+ price: (perMTok, model, provider, readOn) =>
3340
+ `${perMTok} per million input tokens, ${model}, ${provider} prices read ${readOn}`,
3341
+ priceOverlay: (perMTok, model, readOn) =>
3342
+ `${perMTok} per million input tokens, ${model}, local price overlay dated ${readOn}`,
3343
+ promo: (until) => `promotional price until ${until}`,
3344
+ totals: (base, head, change) =>
3345
+ `The prompts with a stated volume: ${base} a month on the base, ${head} on the head (${change}).`,
3346
+ perCallNote: (count) =>
3347
+ `${count} changed ${count === 1 ? 'prompt has' : 'prompts have'} no stated volume, so ${count === 1 ? 'its cost is' : 'their cost is'} per call only. To price a month, map the prompt file under "labels" and state its calls a month under "volumes" in trazum.config.json.`,
3348
+ inputOnly: () =>
3349
+ 'Input tokens at the input price, both sides at the same prices. Output is left out: a prompt edit does not set how much the model writes back.',
3350
+ modelDefault: (model) =>
3351
+ `Priced on Trazum's default model, ${model}, because the config sets no usage.model. Set it to price the model the prompts are sent to.`,
3352
+ unchanged: (count) => `${count} ${count === 1 ? 'prompt is' : 'prompts are'} the same on both sides.`,
3353
+ nothingChanged: () => 'No prompt here changed against the base.',
3354
+ gateWithin: (change, limit) => `The monthly increase, ${change}, is within the limit of ${limit}.`,
3355
+ gateBreached: (change, limit) => `The monthly increase, ${change}, is over the limit of ${limit}.`,
3356
+ gateNotJudged: (count) =>
3357
+ `The limit judges the prompts with a stated volume only: ${count} changed ${count === 1 ? 'prompt was' : 'prompts were'} not judged.`,
3358
+ unavailable: (why, ref) =>
3359
+ why === 'no-commit'
3360
+ ? `The base, ${ref}, is not in this checkout, so nothing was compared. Nothing is fetched to find it. On GitHub Actions, give actions/checkout fetch-depth: 0.`
3361
+ : why === 'not-a-repository'
3362
+ ? `This is not a git repository, so there is no base to compare ${ref} with.`
3363
+ : `git could not be run, so the base, ${ref}, was not read.`,
3364
+ gateUnavailable: (limit) =>
3365
+ `The monthly increase limit of ${limit} judged nothing, because the base could not be read, and a gate that judged nothing fails.`,
3366
+ gateNeedsBase: () =>
3367
+ '--max-monthly-increase-usd limits what a change adds to the monthly cost against a base, so it needs --base <ref>.',
3368
+ noStdin: () => '--base reads the base side of a file from git, and standard input has no base side. Name the file.',
3369
+ },
2986
3370
  profile: {
2987
3371
  noTarget: () =>
2988
3372
  'Point this at a usage log: trazum profile usage.jsonl, one JSON object per line, each with a "model" and the "usage" object the API returned. Add "label" (which workload), "session" (which conversation) and "ts" (when) while you are there: without them every call looks alike, and the largest findings this command makes, conversation growth, and whether the cache TTL fits how fast your turns come, cannot be made at all. Recording it is four lines in your own code, it never contains prompt text, and the session key is grouped by and never printed.',
@@ -3437,7 +3821,9 @@ ${bold('EXAMPLES')}
3437
3821
  ? 'Route and batch'
3438
3822
  : kind === 'fix-truncation'
3439
3823
  ? 'Fix the truncation retries on'
3440
- : 'Look at the cache on';
3824
+ : kind === 'edit-file'
3825
+ ? 'Edit the prompt file of'
3826
+ : 'Look at the cache on';
3441
3827
  return `${verb} ${label} (${model})`;
3442
3828
  },
3443
3829
  routeTo: (model, withBatch) =>
@@ -3454,6 +3840,8 @@ ${bold('EXAMPLES')}
3454
3840
  return 'assumes a max_tokens the answers fit in removes the pair';
3455
3841
  case 'traffic-pattern-holds':
3456
3842
  return 'assumes the traffic pattern holds: a cache that lost money on this log may pay on different traffic';
3843
+ case 'file-is-what-label-sends':
3844
+ return `assumes ${assumption.path} is what this workload sends: trazum.config.json says so, the log records tokens, not files`;
3457
3845
  }
3458
3846
  },
3459
3847
  check: (command) => `check it: ${command}`,
@@ -3465,6 +3853,25 @@ ${bold('EXAMPLES')}
3465
3853
  'Ranked by money, projected or already spent alike. The assumptions are yours to answer: this plan is arithmetic over the log, not knowledge of your product.',
3466
3854
  wrote: (path) =>
3467
3855
  `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
3856
+ editsNeedLabels: () =>
3857
+ '--edits reads the prompt file each label sends, and trazum.config.json maps none: add "labels", for example {"labels": {"support": "prompts/support.txt"}}.',
3858
+ reorderNeedsEdits: () => '--reorder is a step of an edit: add --edits.',
3859
+ editMeasured: (usd, calls, inputPerCall) =>
3860
+ `expected against ${usd} over ${calls} calls at ${inputPerCall} input tokens a call, measured`,
3861
+ editChange: (path, reordered, tokensBefore, tokensAfter) =>
3862
+ `${path}: ${reordered ? 'stable blocks moved ahead of the first placeholder, then trimmed' : 'trimmed'} by the safe rules, ${tokensBefore} → ${tokensAfter} tokens by the estimator, estimated, not measured; no saving is projected`,
3863
+ editCheck: () =>
3864
+ 'trazum verify reads the file, which must hold the text this plan promised, and the newer log, where the input per call must fall below the figure above',
3865
+ editSkipped: (why, label, path) =>
3866
+ why === 'no-traffic'
3867
+ ? `No edit for ${label} (${path}): the log has no priced call carrying that label, so there is no measured figure to expect it against.`
3868
+ : why === 'unreadable'
3869
+ ? `No edit for ${label}: ${path} could not be read.`
3870
+ : why === 'not-tracked'
3871
+ ? `No edit for ${label}: git does not track ${path}, and an edit is proposed to the repository.`
3872
+ : why === 'source-file'
3873
+ ? `No edit for ${label}: ${path} is source code, and an edit rewrites a whole file.`
3874
+ : `No edit for ${label}: the safe rules leave ${path} as it is.`,
3468
3875
  },
3469
3876
 
3470
3877
  serve: {
@@ -3647,7 +4054,9 @@ ${bold('EXAMPLES')}
3647
4054
  ? `Routing and batching ${label} (${model})`
3648
4055
  : kind === 'fix-truncation'
3649
4056
  ? `Fixing the truncation retries on ${label} (${model})`
3650
- : `Fixing the cache on ${label} (${model})`;
4057
+ : kind === 'edit-file'
4058
+ ? `Editing the prompt file of ${label} (${model})`
4059
+ : `Fixing the cache on ${label} (${model})`;
3651
4060
  const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
3652
4061
  return `${what} has been planned ${appearances} times${span} and is still in the newest plan: a decision nobody is revisiting.`;
3653
4062
  },
@@ -3728,7 +4137,9 @@ ${bold('EXAMPLES')}
3728
4137
  ? `Route and batch ${label} (${model})`
3729
4138
  : kind === 'fix-truncation'
3730
4139
  ? `Fix the truncation retries on ${label} (${model})`
3731
- : `Fix the cache on ${label} (${model})`;
4140
+ : kind === 'edit-file'
4141
+ ? `Edit the prompt file of ${label} (${model})`
4142
+ : `Fix the cache on ${label} (${model})`;
3732
4143
  const verdict =
3733
4144
  outcome === 'arrived' ? 'ARRIVED' : outcome === 'not-arrived' ? 'DID NOT ARRIVE' : 'CANNOT BE TOLD';
3734
4145
  return `${what}, ${verdict}`;
@@ -3738,7 +4149,11 @@ ${bold('EXAMPLES')}
3738
4149
  ? 'the label carries no priced traffic in this log: a vanished workload is not a fixed one, and not a broken one either'
3739
4150
  : reason === 'fields-stopped'
3740
4151
  ? 'the fields the detection needs are not in this log, "not recorded" must not read as "fixed", so with --gate this fails'
3741
- : 'the log records tokens, and tokens do not say which tier billed them: the Batch API cannot be seen from here',
4152
+ : reason === 'file-not-read'
4153
+ ? 'the file could not be read from here, so whether the edit was made cannot be told'
4154
+ : reason === 'file-changed'
4155
+ ? 'the file holds neither the text the plan was made from nor the text it promised: it moved on, and with --gate this fails'
4156
+ : 'the log records tokens, and tokens do not say which tier billed them: the Batch API cannot be seen from here',
3742
4157
  routeObserved: (dearestModel, onTargetUsd, onOldUsd) =>
3743
4158
  `the label's dearest model is now ${dearestModel} · ${onTargetUsd} on the target, ${onOldUsd} still on the old model`,
3744
4159
  batchUnobservable: () =>
@@ -3749,6 +4164,9 @@ ${bold('EXAMPLES')}
3749
4164
  outcome === 'arrived'
3750
4165
  ? `caching now pays for itself on this slice (${deltaUsd} against the no-cache bill)`
3751
4166
  : `caching still adds ${deltaUsd} to this slice's bill`,
4167
+ editObserved: (before, after) =>
4168
+ `the file holds the planned text; input per call ${before} → ${after} tokens, measured`,
4169
+ editNotMade: (path) => `${path} still holds the text the plan was made from: the edit was not made`,
3752
4170
  attribution: (callsBefore, callsAfter, outBefore, outAfter) =>
3753
4171
  `the world moved too: calls ${callsBefore} → ${callsAfter}, output/call ${outBefore} → ${outAfter} tokens, stated so the verdict is not read as the whole story`,
3754
4172
  gateFailed: (failures, total) =>