@trazum/cli 3.0.1 → 3.0.3

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/dist/i18n/en.js CHANGED
@@ -21,6 +21,48 @@ const ago = (days) => days === null ? '' : days === 0 ? ' (today)' : days === 1
21
21
  export const en = {
22
22
  locale: 'en',
23
23
  numberLocale: 'en-US',
24
+ commandHelpMore: 'Every command, the config file, prices and examples: trazum --help',
25
+ taskFilter: {
26
+ taskHelp: (maxChars) => `Usage:
27
+ trazum task analyze --id <id> --type <type> --criterion <text>
28
+ --claude-code <file> [--codex <file>] [--claude-code <file> ...]
29
+ [--outcome accepted|rejected|unknown --assessor <label>]
30
+ [--policy baseline|repeat-review-v1] [-o <new-report.json>]
31
+ trazum task policy <report.json> [-o <new-policy.md>]
32
+ trazum task apply <report.json> --instructions <existing-file>
33
+ trazum task revert --instructions <existing-file>
34
+ trazum task compare <before.json> <after.json> [-o <new-comparison.json>]
35
+
36
+ Analyze explicit, complete task sources from Claude Code and Codex locally.
37
+ Repeat the source flags to include sessions from both harnesses. No home scan,
38
+ network access, provider call, hook installation or command execution occurs.
39
+ Up to 16 sources and ${maxChars} characters combined. Do not split one
40
+ session across sources or import the same session more than once.
41
+ Reports and comparisons are JSON by default (--json is also accepted).
42
+ Outcome and assessor are caller declarations, never inferred from usage.
43
+ Policy application adds a small, optional managed block to the file you choose.
44
+ Review the diff and run a comparable task yourself before comparing reports.
45
+ Revert removes only the exact unchanged block. Close other editors while applying
46
+ or reverting. Existing output reports are never overwritten; new files use 0600.
47
+ Repeated tool results may be intentional. A paired comparison is an observation,
48
+ not proof of causal savings, task quality or remaining subscription allowance.
49
+ `,
50
+ filterHelp: `Usage:
51
+ trazum filter compact --recovery-dir <private-directory> [--stats]
52
+ trazum filter restore <sha256> --recovery-dir <private-directory>
53
+ trazum filter instructions print optional output guidance
54
+
55
+ Experimental, opt-in display filter. Only consecutive repeated log lines are
56
+ compacted. Errors and unique lines are kept. Not for source files or data pipes.
57
+ Use Bash pipefail to preserve the producing command's failure status.
58
+ Original logs may contain sensitive data: --recovery-dir explicitly opts into local
59
+ retention. Delete that directory when the originals are no longer needed.
60
+ Token counts are estimates, not billing or subscription-quota measurements.
61
+ --stats writes one JSON record to stderr, without log content or recovery paths.
62
+ `,
63
+ // The source text is this language.
64
+ say: (message) => message,
65
+ },
24
66
  help: (d, bold) => `${bold('trazum')}, what your AI agents and API calls cost, read from logs on this machine.
25
67
 
26
68
  ${bold('START HERE')}
@@ -58,7 +100,8 @@ ${bold('USAGE')}
58
100
  trazum position <usage.jsonl>
59
101
  trazum receipt <usage.jsonl> [--stamp] [--since <when>] [--until <when>] [-o <file>]
60
102
  trazum bill [<file|dir>...] [--label <name>] [--no-label-from-project] [--receipt|--table] [--stamp] [-o <file>]
61
- [--since <when>] [--until <when>] [--by day|week|month] [--pdf-out|--html-out|--markdown-out|--csv-out <file>]
103
+ [--since <when>] [--until <when>] [--by day|week|month] [--pdf-out|--html-out|--markdown-out|--csv-out|--otlp-out|--prom-out <file>]
104
+ [--agent <name>] [--timezone <zone>] [--git-range <range> [--delivery]]
62
105
  trazum weekly [<file|dir>...] [--until <when>] [--label <name>] [--notify] [-o <file>]
63
106
  trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
64
107
  trazum from-codex <file|dir> [--label <name>] [-o <file>]
@@ -73,13 +116,16 @@ ${bold('USAGE')}
73
116
  trazum from-langsmith <file|dir> [-o <file>]
74
117
  trazum switch <usage.jsonl> --to <model> [--migration-usd <n>] [--cases <n>]
75
118
  trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]
119
+ trazum model-pricing <managed-settings.json> --reviewed <YYYY-MM-DD> [-o <file>]
76
120
  trazum pulse [--max-stale-hours <n>]
77
121
  trazum proactive [status|on|off] [--only <item,...>] [--dry-run | --yes] [--json]
122
+ trazum session-guard [status|install|uninstall] --warn <usd> --stop <usd> --on-cannot-tell <fail-open|fail-closed> [--dry-run | --yes]
123
+ trazum waste <transcript.jsonl> [--min-reads <n>] [--claude-md <file>] [--mcp-servers <a,b>] [--json]
78
124
  trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
79
125
  trazum write [--answers <file>] [--json] [-o <file>]
80
126
  trazum models
81
127
  trazum rules [--measure <dir>] [--level <safe|aggressive>]
82
- trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
128
+ trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed> [--metrics-port <n>]
83
129
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
84
130
  trazum quality <log> --label <name> --at <iso> [--gate]
85
131
  trazum semantic <prompt> [--yes]
@@ -180,6 +226,16 @@ ${bold('OPTIONS FOR ownrate')}
180
226
  into trazum.config.json, so the model you run yourself becomes a
181
227
  first-class row in every report, priced by you and marked as such.
182
228
 
229
+ ${bold('OPTIONS FOR model-pricing')}
230
+ --reviewed <YYYY-MM-DD> When the rates were last checked against the
231
+ contract. Required.
232
+ -o, --out <file> Write the overlay there instead of stdout.
233
+
234
+ The contracted rates your organisation gave Claude Code in its
235
+ modelPricing managed setting, as an overlay for --pricing, so Trazum's
236
+ figures match the ones Claude Code shows. What the table cannot say,
237
+ batch and fast mode, keeps the catalogue's figure and is named per model.
238
+
183
239
  ${bold('OPTIONS FOR reconcile')}
184
240
  --against <file> The provider's cost report: Anthropic's
185
241
  GET /v1/organizations/cost_report or OpenAI's
@@ -238,6 +294,41 @@ ${bold('OPTIONS FOR bill')}
238
294
  --by <day|week|month> Split the statement by UTC day, ISO week (Monday
239
295
  to Sunday) or month. Without it, a bill spanning
240
296
  two months or more is split by month.
297
+ --timezone <zone> Cut those days, and a bare --since/--until day, in
298
+ this IANA zone (Europe/Madrid) instead of UTC. The
299
+ statement says which. Not with --otlp-out,
300
+ --prom-out, --markdown-out, --html-out, --pdf-out or a
301
+ --csv-shape other than slice: they cut days in UTC.
302
+ --agent <name> Bill only one coding agent's records: claude-code,
303
+ codex or gemini-cli. A plain log or a provider
304
+ export belongs to no agent and is left out, counted.
305
+ --git-range <range> Instead of a bill, say what was recorded in this
306
+ repository's Claude Code sessions between the
307
+ earliest author time and the latest commit time of
308
+ the range (main..HEAD), run from the repository.
309
+ Only sessions that began and ended inside the span
310
+ are in the figure; sessions that crossed an edge are
311
+ named and counted apart. It is everything spent in
312
+ this repository then, not the cost of the change.
313
+ Not with --since, --until, --label or an output.
314
+ --delivery With --git-range, also say what local git shows
315
+ landed in the same range (commits, pull requests
316
+ named by number in a subject, days with a commit)
317
+ and divide the figure by each. Counts only: no
318
+ name, message or hash is read out. An average over
319
+ the span, not what any commit or pull request cost.
320
+ --otlp-out <file> Also write the bill as OpenTelemetry metrics (OTLP/HTTP
321
+ JSON): per closed UTC day, cost, tokens and calls by
322
+ project, model and agent, and what could not be priced
323
+ as its own metric. Every cost point says it is
324
+ api-equivalent, not what a plan paid. Today, and a day
325
+ the --since/--until window cuts, are not points: the
326
+ resource says which and what they held. Trazum writes
327
+ the file; your pipeline sends it.
328
+ --prom-out <file> Also write the same metrics in the Prometheus text
329
+ format, for the node exporter's textfile collector:
330
+ one series per closed UTC day (its trazum_day label),
331
+ no timestamps, nothing pushed.
241
332
  --stamp Stamp the receipt with the time it was written.
242
333
  -o, --out <file> Write the receipt there instead of stdout.
243
334
 
@@ -457,6 +548,46 @@ ${bold('OPTIONS FOR proactive')}
457
548
  no spend limit is "not ready", with the command or the key that would make it
458
549
  ready.
459
550
 
551
+ ${bold('OPTIONS FOR session-guard')}
552
+ status Whether the hook is in ~/.claude/settings.json, and
553
+ at which figures. The default; writes nothing.
554
+ install Add the hook to the UserPromptSubmit and PreToolUse
555
+ events. Says the file and every line first, and
556
+ writes only after a yes.
557
+ uninstall Remove exactly the hook it added.
558
+ check What the hook runs: reads the session's transcript,
559
+ prices it at the bundled catalogue and warns once,
560
+ stops (exit code 2) or stays silent. Not for typing.
561
+ --warn <usd> Warn once per session at this API-equivalent cost.
562
+ --stop <usd> Stop the session at this cost. Must exceed --warn.
563
+ --on-cannot-tell <policy> fail-open or fail-closed: what happens when the
564
+ cost cannot be told (no transcript, a model with
565
+ no price). It never counts the cost as zero.
566
+ --dry-run, --yes As for proactive.
567
+
568
+ There is no default for the thresholds or the policy: leave one out and the
569
+ command refuses by name. Every figure is API-equivalent cost, what the usage
570
+ would cost at the provider's list API prices, not what you were charged.
571
+ Nothing leaves this machine.
572
+
573
+ ${bold('OPTIONS FOR waste')}
574
+ <transcript.jsonl> A Claude Code session's transcript. Its subagents'
575
+ transcripts, in the folder beside it, are read too.
576
+ --min-reads <n> List a file only if it was read at least n times
577
+ (2 or more; default 3). It chooses what is listed,
578
+ not what is counted.
579
+ --claude-md <file> The CLAUDE.md to size. Without it, the CLAUDE.md in
580
+ the directory the session ran in, if there is one.
581
+ Only its size in bytes is read, never its content.
582
+ --mcp-servers <a,b> The MCP servers that were loaded, when the
583
+ transcript does not say. Names only.
584
+
585
+ It names a cost and prices it at the bundled catalogue, from this session's
586
+ own counts: a file read again, an MCP server loaded and never called, a
587
+ CLAUDE.md carried on every turn. It recommends and edits no file. A cost it
588
+ cannot compute from what the transcript records is named and not priced.
589
+ Every figure is API-equivalent cost, not what you were charged.
590
+
460
591
  ${bold('OPTIONS FOR bench')}
461
592
  --workload <id> Run one standard workload instead of all of them.
462
593
  An unknown id is refused with the known ones named.
@@ -534,6 +665,10 @@ ${bold('OPTIONS FOR gateway')}
534
665
  What happens when the gateway cannot judge a call:
535
666
  no budget, nothing measured, an unpriced model.
536
667
  --port <n> | --socket <p> Where to listen. Loopback only, always.
668
+ --metrics-port <n> Serve what the gateway has counted since it
669
+ started, in Prometheus text, at GET /metrics on
670
+ this second loopback port. Off unless given. Counts
671
+ and list-rate cost only, never a prompt.
537
672
  --log <usage.jsonl> The usage log the limits policy is measured
538
673
  against, read once at start, same flag as
539
674
  serve's, same reason: label and session spend
@@ -764,6 +899,16 @@ ${bold('OPTIONS FOR check')}
764
899
  loud; a list with nothing checkable passes. Budgets apply
765
900
  per file as always; the baseline needs the whole repository
766
901
  and is skipped, and says so.
902
+ --base <ref> Also price each changed prompt on that commit and here:
903
+ tokens, and its input cost a month at the calls a month
904
+ "volumes" states for its label, or a call when none is
905
+ stated. Each figure names its price and the day that
906
+ price was read. The commit is read from this clone with
907
+ git and never fetched; one that is not here is said.
908
+ --max-monthly-increase-usd <usd>
909
+ With --base: fail when the prompts with a stated volume
910
+ cost more than this many dollars a month more than on
911
+ the base. Off unless given.
767
912
 
768
913
  Built for CI: exits with code 1 when the prompt busts the budget, so a
769
914
  template that grows unchecked breaks the build instead of the bill.
@@ -890,6 +1035,12 @@ ${bold('OPTIONS FOR profile')}
890
1035
  ${bold('OPTIONS FOR plan')}
891
1036
  --min-usd <n> Leave out actions worth less than n dollars. How
892
1037
  many were left out is stated, never silent.
1038
+ --edits Add an edit to each prompt file "labels" in
1039
+ trazum.config.json maps a label to: the safe
1040
+ rules' text, recorded by hash, written nowhere.
1041
+ Only files git tracks. No saving is projected.
1042
+ --reorder With --edits: move stable blocks ahead of the
1043
+ first placeholder before trimming.
893
1044
  -o, --out <file> Save the plan as dated JSON: the file
894
1045
  "trazum verify" will later hold it to.
895
1046
  --markdown-out <file> Also write the plan as Markdown, for a CI job
@@ -1130,6 +1281,9 @@ ${bold('CONFIG FILE')}
1130
1281
  labels { "support-rag": "prompts/support.txt" }: which prompt file each
1131
1282
  usage-log label sends, so "trazum profile" can read the file and
1132
1283
  say why a failing cache fails
1284
+ volumes { "support-rag": 30000 }: calls a month for a label "labels"
1285
+ maps, so "check --base" can price that prompt a month at a
1286
+ time. A prompt with none is priced per call, and said
1133
1287
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } }: money budgets for
1134
1288
  "trazum profile", in dollars. A budgeted label with no calls in
1135
1289
  the log is reported as not measured, never as a pass
@@ -1659,6 +1813,8 @@ ${bold('EXAMPLES')}
1659
1813
  return `unmeasured: the provider answered without any usage in the body, so the call was made and its cost is not knowable from the response, so the total below is short by these (${sofar} unmeasured so far)`;
1660
1814
  },
1661
1815
  pointYourSdk: (where) => `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.`,
1816
+ badMetricsPort: (given) => `--metrics-port is "${given}". Give a whole number from 0 to 65535: the loopback port Prometheus scrapes.`,
1817
+ metrics: (where) => `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.`,
1662
1818
  credential: () => '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.',
1663
1819
  neverSubstitutes: () => 'A call over budget is refused with HTTP 402 and the cheaper alternatives named, never silently swapped, trimmed or downgraded. 402 rather than 429 on purpose: every provider SDK retries a 429, which would turn one refusal into a retry storm.',
1664
1820
  standing: (consumed, limit) => `Judging against ${consumed} of ${limit}, measured, read once at start: a file read in the request path would put this tool's latency between you and your provider on every call.`,
@@ -1784,6 +1940,32 @@ ${bold('EXAMPLES')}
1784
1940
  evalCostHint: () => 'Pass --cases <n> to price the evaluation the switch requires.',
1785
1941
  quality: (routeCommand) => `Nothing above says whether the candidate can do the work. That is an evaluation, not arithmetic: ${routeCommand}`,
1786
1942
  },
1943
+ modelPricing: {
1944
+ noFile: () => 'Name the settings file that holds modelPricing: trazum model-pricing <managed-settings.json> --reviewed YYYY-MM-DD',
1945
+ noReviewed: () => '--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.',
1946
+ notFound: (file) => `${file} is not a file.`,
1947
+ tooLarge: (file, bytes) => `${file} is larger than ${bytes} bytes, which is more than a settings file holds.`,
1948
+ notJson: (file, detail) => `${file} is not JSON: ${detail}`,
1949
+ skipped: (key, reason, detail) => {
1950
+ switch (reason) {
1951
+ case 'invalid':
1952
+ return `"${key}" is left out: ${detail}. Claude Code drops it too, and keeps the rest.`;
1953
+ case 'zero':
1954
+ 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.`;
1955
+ case 'unknown-model':
1956
+ 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.`;
1957
+ case 'duplicate':
1958
+ return `"${key}" is left out: it is the same model as "${detail}", whose row is used. Trazum cannot price one model two ways.`;
1959
+ }
1960
+ },
1961
+ empty: () => 'Nothing in the table reaches a model Trazum prices, so no overlay was written.',
1962
+ summary: (fromRows, fromMultiplier, multiplier) => `${fromRows} model(s) at the rates in your table${multiplier === undefined ? '' : `, times ${multiplier}`}` +
1963
+ (fromMultiplier > 0 ? `; ${fromMultiplier} other Claude model(s) at list price times ${multiplier}.` : '.'),
1964
+ batch: (models) => `Batch: the table has no batch rate, so ${models} model(s) keep the catalogue's batch discount on the new input rate.`,
1965
+ fastKept: (models) => `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.`,
1966
+ usOnly: (models) => `US-only inference: no surcharge on a row, as Claude Code applies it: ${models}.`,
1967
+ written: (file, models) => `Wrote an overlay of ${models} model(s) to ${file}. Use it with --pricing ${file}.`,
1968
+ },
1787
1969
  ownrate: {
1788
1970
  missing: () => 'Both numbers are yours to declare: trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]',
1789
1971
  invalid: (flag) => `--${flag} must be a positive number (utilization: greater than 0, at most 1).`,
@@ -1925,6 +2107,14 @@ ${bold('EXAMPLES')}
1925
2107
  periodsUndated: (calls, usd, unit) => `${usd} from ${calls} call(s) with no timestamp is in the total and in no ${unit}.`,
1926
2108
  periodHint: (since, until, unit) => `One ${unit} on its own: --since ${since} --until ${until}.`,
1927
2109
  badBy: (value) => `--by takes day, week or month, not "${value}".`,
2110
+ badAgent: (value, known) => `--agent does not know "${value}". The agents it names are ${known}.`,
2111
+ agentNoRecords: (name, known) => `--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.`,
2112
+ agentOnly: (name, kept, leftOut) => `--agent: only ${name}'s ${kept} record(s) are billed; ${leftOut} record(s) of other agents or sources are left out.`,
2113
+ badTimezone: (value) => `--timezone does not know "${value}". Name an IANA time zone such as Europe/Madrid or America/New_York.`,
2114
+ timezoneConflict: (flag) => `--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.`,
2115
+ zoneLine: (zone) => `Days are cut in ${zone}, not UTC: a bare --since/--until day is a day there, and so is every row above.`,
2116
+ periodHintZone: (zone) => `Add --timezone ${zone} to bill it on the same days.`,
2117
+ zoneReceiptNote: (zone) => `--timezone ${zone}: the receipt holds instants and no day, so the zone only decides what a bare --since/--until day means.`,
1928
2118
  colCalls: () => 'calls',
1929
2119
  colShare: () => 'share',
1930
2120
  moreRows: (count) => `… and ${count} more`,
@@ -1943,11 +2133,45 @@ ${bold('EXAMPLES')}
1943
2133
  costReport: (path) => `${path}: a provider's cost report, which is a bill rather than usage. Set it beside a receipt with trazum reconcile.`,
1944
2134
  nothingRead: () => 'Nothing here was a usage source this tool reads, so there is nothing to bill.',
1945
2135
  sources: (read, seen) => `${read} of ${seen} file(s) read as usage.`,
2136
+ sendNeedsReceipt: () => '--send posts the receipt, so it needs --receipt: bill --receipt --send <url>. Nothing else is ever sent.',
2137
+ badSendTarget: (reason, keyVariable) => reason === 'credentials-in-url'
2138
+ ? '--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.'
2139
+ : reason === 'insecure-scheme'
2140
+ ? '--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.'
2141
+ : reason === 'bad-key'
2142
+ ? `--send: ${keyVariable} holds spaces, control characters or non-ASCII bytes, which cannot be sent as a bearer token. Its value is not shown.`
2143
+ : '--send: that is not a URL this tool can parse.',
2144
+ sendDelivered: (where, status) => `Sent the receipt to ${where} (HTTP ${status}). Nothing else was sent.`,
2145
+ sendFailed: (where, status) => status === null
2146
+ ? `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.`
2147
+ : `${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.`,
1946
2148
  pricingLiveHint: (count) => `${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.`,
1947
2149
  apiEquivalent: () => '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.',
2150
+ partnerUnpriced: (ids) => `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.`,
2151
+ partnerModel: (platform, model) => `${platform === 'bedrock' ? 'Amazon Bedrock' : 'Vertex AI'}, ${model ?? 'a model this catalogue does not know'}`,
1948
2152
  prefixedKnown: (ids) => `${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.`,
1949
2153
  windowMatchesNothing: (from, to) => `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.`,
1950
2154
  written: (file) => `Wrote ${file}.`,
2155
+ rangeConflict: (flag) => `--git-range sets the period itself, from the commits, and prints its own statement: it cannot be combined with ${flag}.`,
2156
+ rangeNoGit: () => "could not run git, which --git-range reads the commits' times from.",
2157
+ rangeNoRepository: () => 'This directory is not inside a git repository, so --git-range has no repository to read.',
2158
+ rangeBad: (range) => `git does not know the range "${range}". Name one such as main..HEAD.`,
2159
+ rangeEmpty: (range) => `The range "${range}" holds no commit, so it has no span to sum.`,
2160
+ rangeHeading: (range) => `Recorded in this repository's sessions while ${range} was written`,
2161
+ rangeWindow: (from, to, commits) => `Span: ${from} to ${to}, from the author and commit times of ${commits} commit(s).`,
2162
+ rangeInside: (usd, calls, sessions) => `${usd} across ${calls.toLocaleString('en-US')} priced call(s) in ${sessions.toLocaleString('en-US')} session(s) that began and ended inside the span.`,
2163
+ rangeNothingInside: () => 'No session of this project began and ended inside the span.',
2164
+ rangeStraddleHeading: (count) => `${count} session(s) began before the span or went on after it. Counted apart, not in the figure above:`,
2165
+ rangeStraddleRow: (session, from, to, insideUsd, insideCalls, outsideUsd, outsideCalls) => ` ${session} ${from} to ${to}: ${insideUsd} (${insideCalls} call(s)) inside the span, ${outsideUsd} (${outsideCalls} call(s)) outside it.`,
2166
+ rangeNoStraddle: () => 'No session crossed either edge of the span.',
2167
+ rangeMeaning: () => '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.',
2168
+ rangeLeftOut: (outsideCalls, otherProjects, otherSources, undated) => `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.`,
2169
+ rangeUnpriced: (calls) => `Not in the figure: ${calls} call(s) to models the catalogue does not price. Named, never counted as $0.`,
2170
+ deliveryNeedsRange: () => '--delivery sets the spend of a range of commits beside what git shows landed in it, so it needs --git-range.',
2171
+ rangeDelivered: (commits, merges, pullRequests, days) => `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.`,
2172
+ rangeDividedBy: (perCommit, perPullRequest, perDay) => `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.`,
2173
+ rangeDividedNothing: () => 'No session began and ended inside the span, so there is no figure to divide by these counts.',
2174
+ rangeNoProject: () => "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.",
1951
2175
  },
1952
2176
  fromOpenrouter: {
1953
2177
  noPath: () => 'from-openrouter needs the activity report your own curl produced: trazum from-openrouter activity.json --label billing',
@@ -2156,6 +2380,75 @@ ${bold('EXAMPLES')}
2156
2380
  backupNote: (suffix) => `The first time a file you own changes, a copy of it is kept beside it as <name>${suffix}. It is never replaced.`,
2157
2381
  crontab: () => 'your crontab',
2158
2382
  },
2383
+ sessionGuard: {
2384
+ unknownAction: (given) => `Unknown action "${given}". Use: trazum session-guard [status|install|uninstall].`,
2385
+ refusedMissing: (flags) => `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`,
2386
+ refusedAmount: (flag, given) => `${flag} needs an amount in US dollars greater than zero, and "${given}" is not one.`,
2387
+ 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.`,
2388
+ refusedWarnNotBelowStop: () => '--warn has to be less than --stop, or the warning could never be seen before the stop.',
2389
+ refusedFlag: (flag) => `${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.`,
2390
+ warn: (usd, warnUsd, stopUsd, atLeast) => `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.`,
2391
+ block: (usd, stopUsd, atLeast) => `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>.`,
2392
+ cannotTellOpen: (why) => `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.`,
2393
+ cannotTellClosed: (why) => `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.`,
2394
+ cause: {
2395
+ 'no-transcript': () => 'Claude Code gave no transcript to read',
2396
+ unreadable: () => 'the transcript could not be read',
2397
+ unparseable: () => 'the transcript has lines and none of them could be read as usage',
2398
+ skipped: () => 'part of the transcript could not be read as a usage record',
2399
+ },
2400
+ unpriced: (models) => `the catalogue has no price for ${models}`,
2401
+ settingsShape: (file, key) => `${file} has a "${key}" that is not the shape Claude Code reads, so it is left alone.`,
2402
+ wouldInstall: () => 'session guard: would write',
2403
+ wouldUninstall: () => 'session guard: would remove',
2404
+ askInstall: (file) => `Write the session guard hook (${file})? [y/N] `,
2405
+ askUninstall: (file) => `Remove the session guard hook (${file})? [y/N] `,
2406
+ didInstall: (file) => `session guard: wrote ${file}`,
2407
+ didUninstall: (file) => `session guard: removed from ${file}`,
2408
+ declined: () => 'session guard: not written, you said no.',
2409
+ nothingToUninstall: () => 'session guard: nothing to remove.',
2410
+ alreadyInstalled: (file) => `session guard: already as asked in ${file}, nothing to change.`,
2411
+ dryRun: () => 'Dry run: nothing was written.',
2412
+ dryRunNoTerminal: () => '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.',
2413
+ failed: (reason) => `session guard: not written. ${reason}`,
2414
+ statusOn: (file, warnUsd, stopUsd, policy) => `on in ${file}: warns at ${warnUsd}, stops at ${stopUsd} of API-equivalent cost, and when the cost cannot be told it is ${policy}.`,
2415
+ statusOff: (file) => `off: no session guard hook in ${file}.`,
2416
+ statusPartial: (file) => `partly on: ${file} has the hook on one of the two events and not the other. Run install again to complete it.`,
2417
+ apiEquivalent: () => "Every figure is API-equivalent cost: the usage at the provider's list API prices, not what you were charged.",
2418
+ windows: () => 'The session guard hook is written as a shell command and is not available on Windows.',
2419
+ noClaude: (dir) => `${dir} is not there, so Claude Code does not look installed for this user. Nothing was written.`,
2420
+ },
2421
+ waste: {
2422
+ refusedFlag: (flag) => `${flag} is not accepted here. waste prices at the catalogue bundled with this version and reads only files already on this machine.`,
2423
+ noPath: () => 'Name the session transcript to read. Example: trazum waste <session>.jsonl',
2424
+ notFound: (path) => `${path} is not a file.`,
2425
+ unreadable: (path) => `${path}, or a transcript of its subagents, could not be read.`,
2426
+ 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.`,
2427
+ cannotTell: () => '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.',
2428
+ heading: (calls, threads) => `Waste in this session: ${plural(calls, 'call')} in ${plural(threads, 'thread')}`,
2429
+ apiEquivalent: (reviewed) => `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.`,
2430
+ unpriced: (models) => `No price in the catalogue for ${models}: those calls are left out of every figure, so each is a floor.`,
2431
+ readsHeading: () => 'The same file read again',
2432
+ readsNone: (minReads) => `No file was read ${minReads} or more times with nothing changing it in between.`,
2433
+ readLine: (reads, repeats, measured, tokens, usd) => `read ${reads} times, ${plural(repeats, 'repeat')} of the same range with no edit between. ${usd === null
2434
+ ? 'Not priced: the calls that repeated it also made other tool calls, so the growth cannot be split.'
2435
+ : `${measured} measured, ${tokens.toLocaleString('en-US')} tokens added to the context and carried on every later call: ${usd}.`}`,
2436
+ readsOmitted: (count) => `${plural(count, 'more file')} read again and not listed (under --min-reads, or past the 20 listed).`,
2437
+ readsTotal: (usd, measured, repeats) => `Together: ${usd} for the ${measured} of ${repeats} repeats that could be measured.`,
2438
+ readsUnmeasured: (repeats) => `${plural(repeats, 'repeat')} found and none could be priced from the counts.`,
2439
+ mcpHeading: () => 'MCP servers loaded and never called',
2440
+ mcpNoList: () => '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.',
2441
+ mcpAllCalled: (loaded) => `${plural(loaded, 'server')} loaded, and every one was called at least once.`,
2442
+ mcpSummary: (loaded, called, source) => `${plural(loaded, 'server')} loaded${source === 'flag' ? ' (as you named them)' : ''}, ${called} called.`,
2443
+ mcpUnused: (server, tools) => `${server}: never called${tools === null ? '' : `, ${plural(tools, 'tool')} loaded`}`,
2444
+ mcpNotPriced: () => "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.",
2445
+ claudeHeading: () => 'A CLAUDE.md carried on every turn',
2446
+ claudeNone: (path) => path === ''
2447
+ ? 'No CLAUDE.md to size: the transcript names no directory. Pass --claude-md <file>.'
2448
+ : `No CLAUDE.md at ${path}. Pass --claude-md <file> to size another.`,
2449
+ claudeLine: (bytes, tokens, calls, usd, low, high, bandPct) => `${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.`,
2450
+ nothingChanged: () => 'Nothing was changed. This command recommends and edits no file.',
2451
+ },
2159
2452
  pulse: {
2160
2453
  heading: () => 'Did the things that are supposed to run, run?',
2161
2454
  kind: (kind) => {
@@ -2495,6 +2788,37 @@ ${bold('EXAMPLES')}
2495
2788
  filesFromNoBaseline: () => 'The baseline gate is skipped under --files-from: it compares the whole repository against the committed record, and a partial list would read as removals. Budgets are checked per file as always; run "trazum check ." for the baseline.',
2496
2789
  exactCountsCost: (files) => `Counting ${files} ${files === 1 ? 'file' : 'files'} through the API, one call each. This takes a moment.`,
2497
2790
  },
2791
+ againstBase: {
2792
+ heading: (ref, sha) => `Against the base, ${ref} at ${sha}`,
2793
+ columnTokens: () => 'Tokens, base → head',
2794
+ columnCalls: () => 'Calls a month',
2795
+ columnBase: () => 'Base',
2796
+ columnHead: () => 'Head',
2797
+ columnPrice: () => 'Price',
2798
+ notStated: () => 'not stated',
2799
+ perMonth: (usd) => `${usd} a month`,
2800
+ perCall: (usd) => `${usd} a call`,
2801
+ price: (perMTok, model, provider, readOn) => `${perMTok} per million input tokens, ${model}, ${provider} prices read ${readOn}`,
2802
+ priceOverlay: (perMTok, model, readOn) => `${perMTok} per million input tokens, ${model}, local price overlay dated ${readOn}`,
2803
+ promo: (until) => `promotional price until ${until}`,
2804
+ totals: (base, head, change) => `The prompts with a stated volume: ${base} a month on the base, ${head} on the head (${change}).`,
2805
+ perCallNote: (count) => `${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.`,
2806
+ inputOnly: () => '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.',
2807
+ modelDefault: (model) => `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.`,
2808
+ unchanged: (count) => `${count} ${count === 1 ? 'prompt is' : 'prompts are'} the same on both sides.`,
2809
+ nothingChanged: () => 'No prompt here changed against the base.',
2810
+ gateWithin: (change, limit) => `The monthly increase, ${change}, is within the limit of ${limit}.`,
2811
+ gateBreached: (change, limit) => `The monthly increase, ${change}, is over the limit of ${limit}.`,
2812
+ gateNotJudged: (count) => `The limit judges the prompts with a stated volume only: ${count} changed ${count === 1 ? 'prompt was' : 'prompts were'} not judged.`,
2813
+ unavailable: (why, ref) => why === 'no-commit'
2814
+ ? `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.`
2815
+ : why === 'not-a-repository'
2816
+ ? `This is not a git repository, so there is no base to compare ${ref} with.`
2817
+ : `git could not be run, so the base, ${ref}, was not read.`,
2818
+ gateUnavailable: (limit) => `The monthly increase limit of ${limit} judged nothing, because the base could not be read, and a gate that judged nothing fails.`,
2819
+ gateNeedsBase: () => '--max-monthly-increase-usd limits what a change adds to the monthly cost against a base, so it needs --base <ref>.',
2820
+ noStdin: () => '--base reads the base side of a file from git, and standard input has no base side. Name the file.',
2821
+ },
2498
2822
  profile: {
2499
2823
  noTarget: () => '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.',
2500
2824
  heading: () => 'Where the money went',
@@ -2772,7 +3096,9 @@ ${bold('EXAMPLES')}
2772
3096
  ? 'Route and batch'
2773
3097
  : kind === 'fix-truncation'
2774
3098
  ? 'Fix the truncation retries on'
2775
- : 'Look at the cache on';
3099
+ : kind === 'edit-file'
3100
+ ? 'Edit the prompt file of'
3101
+ : 'Look at the cache on';
2776
3102
  return `${verb} ${label} (${model})`;
2777
3103
  },
2778
3104
  routeTo: (model, withBatch) => withBatch ? `to ${model}, combined with batching where both apply, never summed` : `to ${model}`,
@@ -2788,6 +3114,8 @@ ${bold('EXAMPLES')}
2788
3114
  return 'assumes a max_tokens the answers fit in removes the pair';
2789
3115
  case 'traffic-pattern-holds':
2790
3116
  return 'assumes the traffic pattern holds: a cache that lost money on this log may pay on different traffic';
3117
+ case 'file-is-what-label-sends':
3118
+ return `assumes ${assumption.path} is what this workload sends: trazum.config.json says so, the log records tokens, not files`;
2791
3119
  }
2792
3120
  },
2793
3121
  check: (command) => `check it: ${command}`,
@@ -2795,6 +3123,20 @@ ${bold('EXAMPLES')}
2795
3123
  batchExcluded: (usd) => `No batch saving is projected on ${usd} of input and output: those calls already ran on the Batch API, or something waited on their answer (marked interactive, as every turn of a coding agent is).`,
2796
3124
  footer: () => '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.',
2797
3125
  wrote: (path) => `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
3126
+ editsNeedLabels: () => '--edits reads the prompt file each label sends, and trazum.config.json maps none: add "labels", for example {"labels": {"support": "prompts/support.txt"}}.',
3127
+ reorderNeedsEdits: () => '--reorder is a step of an edit: add --edits.',
3128
+ editMeasured: (usd, calls, inputPerCall) => `expected against ${usd} over ${calls} calls at ${inputPerCall} input tokens a call, measured`,
3129
+ editChange: (path, reordered, tokensBefore, tokensAfter) => `${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`,
3130
+ editCheck: () => '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',
3131
+ editSkipped: (why, label, path) => why === 'no-traffic'
3132
+ ? `No edit for ${label} (${path}): the log has no priced call carrying that label, so there is no measured figure to expect it against.`
3133
+ : why === 'unreadable'
3134
+ ? `No edit for ${label}: ${path} could not be read.`
3135
+ : why === 'not-tracked'
3136
+ ? `No edit for ${label}: git does not track ${path}, and an edit is proposed to the repository.`
3137
+ : why === 'source-file'
3138
+ ? `No edit for ${label}: ${path} is source code, and an edit rewrites a whole file.`
3139
+ : `No edit for ${label}: the safe rules leave ${path} as it is.`,
2798
3140
  },
2799
3141
  serve: {
2800
3142
  listening: (where) => `Answering on ${where}`,
@@ -2916,7 +3258,9 @@ ${bold('EXAMPLES')}
2916
3258
  ? `Routing and batching ${label} (${model})`
2917
3259
  : kind === 'fix-truncation'
2918
3260
  ? `Fixing the truncation retries on ${label} (${model})`
2919
- : `Fixing the cache on ${label} (${model})`;
3261
+ : kind === 'edit-file'
3262
+ ? `Editing the prompt file of ${label} (${model})`
3263
+ : `Fixing the cache on ${label} (${model})`;
2920
3264
  const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
2921
3265
  return `${what} has been planned ${appearances} times${span} and is still in the newest plan: a decision nobody is revisiting.`;
2922
3266
  },
@@ -2974,7 +3318,9 @@ ${bold('EXAMPLES')}
2974
3318
  ? `Route and batch ${label} (${model})`
2975
3319
  : kind === 'fix-truncation'
2976
3320
  ? `Fix the truncation retries on ${label} (${model})`
2977
- : `Fix the cache on ${label} (${model})`;
3321
+ : kind === 'edit-file'
3322
+ ? `Edit the prompt file of ${label} (${model})`
3323
+ : `Fix the cache on ${label} (${model})`;
2978
3324
  const verdict = outcome === 'arrived' ? 'ARRIVED' : outcome === 'not-arrived' ? 'DID NOT ARRIVE' : 'CANNOT BE TOLD';
2979
3325
  return `${what}, ${verdict}`;
2980
3326
  },
@@ -2982,13 +3328,19 @@ ${bold('EXAMPLES')}
2982
3328
  ? 'the label carries no priced traffic in this log: a vanished workload is not a fixed one, and not a broken one either'
2983
3329
  : reason === 'fields-stopped'
2984
3330
  ? 'the fields the detection needs are not in this log, "not recorded" must not read as "fixed", so with --gate this fails'
2985
- : 'the log records tokens, and tokens do not say which tier billed them: the Batch API cannot be seen from here',
3331
+ : reason === 'file-not-read'
3332
+ ? 'the file could not be read from here, so whether the edit was made cannot be told'
3333
+ : reason === 'file-changed'
3334
+ ? 'the file holds neither the text the plan was made from nor the text it promised: it moved on, and with --gate this fails'
3335
+ : 'the log records tokens, and tokens do not say which tier billed them: the Batch API cannot be seen from here',
2986
3336
  routeObserved: (dearestModel, onTargetUsd, onOldUsd) => `the label's dearest model is now ${dearestModel} · ${onTargetUsd} on the target, ${onOldUsd} still on the old model`,
2987
3337
  batchUnobservable: () => 'the batch half of this action cannot be seen in token counts; the verdict above is the route half alone',
2988
3338
  truncationObserved: (retryBillUsd) => `this log still shows ${retryBillUsd} of truncation waste and retries`,
2989
3339
  cacheObserved: (deltaUsd, outcome) => outcome === 'arrived'
2990
3340
  ? `caching now pays for itself on this slice (${deltaUsd} against the no-cache bill)`
2991
3341
  : `caching still adds ${deltaUsd} to this slice's bill`,
3342
+ editObserved: (before, after) => `the file holds the planned text; input per call ${before} → ${after} tokens, measured`,
3343
+ editNotMade: (path) => `${path} still holds the text the plan was made from: the edit was not made`,
2992
3344
  attribution: (callsBefore, callsAfter, outBefore, outAfter) => `the world moved too: calls ${callsBefore} → ${callsAfter}, output/call ${outBefore} → ${outAfter} tokens, stated so the verdict is not read as the whole story`,
2993
3345
  gateFailed: (failures, total) => `GATE FAILED, ${failures} of ${total} actions did not produce what the plan promised, or stopped being measurable by the team's own log.`,
2994
3346
  gateOk: () => 'Gate passed: every verifiable action arrived, and nothing became unverifiable.',